Helix Swarm Guide (2019.3)

Runtime dependencies

In order to successfully install, configure, and deploy Swarm, the following dependencies are required:

  • A supported operating system platform
  • An Apache web server with mod_rewrite and mod_phpx (where x is the version of PHP you are running, for example 7). For supported versions of PHP, see PHP.

  • A supported version of PHP with the following extensions:

    • iconv
    • JSON
    • Session
    • P4PHP version 2019.1 or later
    • php-mbstring (for multi-byte character strings)

    • php-xml (for RSS feeds)

    • php-redis (for Swarm caching)

    • CentOS/RHEL: in addition to php-redis:
      • CentOS/RHEL 6: PHP 7.0 redis and PHP 7.0 igbinary (for Swarm caching)
      • CentOS/RHEL 7: PHP 7.1 redis and PHP 7.1 igbinary (for Swarm caching)

    In addition, Swarm greatly benefits from the following optional extension: Imagick (used for viewing non-web safe images)

  • A supported Helix Core server deployment, and the ability to connect to it from the system hosting Swarm.

    Note

    "Helix server deployment" can refer to a running p4d or a proxy, replica, edge server, or commit server.

  • curl or wget (for Swarm worker operation)
  • A supported version of perl (to integrate with Helix Core server triggers)
  • That Security-enhanced Linux (SELinux), if installed, is configured

Optional dependencies:

  • LibreOffice: required to view office-type documents. For more information, see LibreOffice.
  • zip: command-line archiving tool: Required to download zip archives of files and folders. For more information, see Zip.
  • Helix Authentication Service SSO: enables Swarm to authenticate with SSO when the Helix Core server is configured for Helix Authentication Service, see Helix Authentication Service SSO.
  • Helix SAML authentication: enables Swarm to authenticate with a Helix Core server configured with Helix SAML. For more information, see Helix SAML authentication.
  • Sendmail or equivalent: required to use Swarm email notifications. For more information, see Swarm email notifications.

Supported operating system platforms

Because Swarm includes binary versions of P4PHP (the Perforce extension for PHP), we support Swarm on the following operating systems:

  • Linux 2.6+ Intel (x86_64) with glibc 2.11+
  • Mac OS X 10.6+ (x86_64)

Recommended for CentOS/RHEL 6: Change the following parameters in the [Pcre] section of the /etc/php.ini file to the values shown below. This ensures that very large comments are displayed:

  • pcre.backtrack_limit = 1000000
  • pcre.recursion_limit = 10000

You may be able to get Swarm running on another platform if you build P4PHP yourself and satisfy the other runtime dependencies. Instructions on how to obtain and build P4PHP from source can be found here.

Important

P4PHP does not support threaded operation. If you compile P4PHP from source, ensure that the version of PHP you compile for is non-threaded.

Apache web server

Swarm requires Apache HTTP Server 2.4 or newer:

Important

CentOS/RHEL only:

  • CentOS: You can use the centos-release-scl repository to install PHP 7.x and Apache 2.4, see https://wiki.centos.org/AdditionalResources/Repositories/SCL. Other repositories are available if you do not want to use the SCL repository.

  • RHEL: Enable the rhel-server-rhscl-x-eus-rpms repository to give Swarm access to PHP 7, Apache 2.4 and most of the required PHP extensions (where x is your version of RHEL, for example 6 or 7). The php7x-php-pecl-redis, php7x-php-pecl-igbinary, and imagick extensions are not available from this RedHat repository and you must source them from elsewhere.

  • If Apache 2.4 has been installed from the SCL or RHSCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

    • For CentOS/RHEL 6 to use System V scripts: service httpd24-httpd restart
    • For CentOS/RHEL 7 to use systemd scripts: systemctl restart httpd24-httpd

    The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

  • To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

Swarm also requires the following Apache modules:

Important

Only the prefork MPMMulti-Processing Module, a component of the Apache web server that is responsible for binding to network ports, accepting requests, and dispatch operations to handle the request. is supported. Use of the worker or event MPMs is not supported and is likely to cause problems because P4PHP does not support threaded operation.

For more information on the prefork MPM, see: https://httpd.apache.org/docs/2.4/mod/prefork.html

PHP

Swarm requires PHP 7.0, 7.1, or 7.2:

Important
  • PHP must be non-threaded because P4PHP does not support threaded operation.

  • CentOS: You can use the centos-release-scl repository to install PHP 7.x and Apache 2.4, see https://wiki.centos.org/AdditionalResources/Repositories/SCL. Other repositories are available if you do not want to use the SCL repository.

  • RHEL: Enable the rhel-server-rhscl-x-eus-rpms repository to give Swarm access to PHP 7, Apache 2.4 and most of the required PHP extensions (where x is your version of RHEL, for example 6 or 7). The php7x-php-pecl-redis, php7x-php-pecl-igbinary, and imagick extensions are not available from this RedHat repository and you must source them from elsewhere.

Required PHP extensions

Swarm requires the following PHP extensions:

Tip

If you install Swarm from a package, all of these PHP extensions are automatically pulled in as dependencies on all platforms.

  • iconv (character encoding converter)
    https://secure.php.net/iconv

    This is typically enabled by default with most PHP distributions

  • JSON (JavaScript Object Notation)
    https://secure.php.net/json

    This is typically enabled by default with most PHP distributions, although recent distributions are making this optional.

  • Session (session handling)

    This is typically enabled by default with most PHP distributions

  • P4PHP version 2019.1 or later (the Perforce PHP Extension)

    The latest P4PHP version is included with the Swarm package, OVA and tarball installations.

    Note

    Swarm package, OVA and tarball installations: 2 versions of P4PHP are supplied for each PHP 7 version supported by Swarm. They are located in the p4-bin/bin.linux26x86_64 directory.

    • perforce-php7x.so compatible with systems using SSL 1.0.2
    • perforce-php7x-ssl1.1.1.so compatible with systems using SSL 1.1.1 (by default Ubuntu 18.04 uses SSL 1.1.1)

    Where x is the version of PHP 7.

    If the perforce.ini file is not pointing at the correct version of P4PHP and you connect to an SSL enabled Helix server:

    • The Swarm web-page will not load and you might see a Connection Reset error.
    • There might be an undefined symbol: SSLeay message in the Apache error log

    Upgrading Swarm:

    • Swarm package or OVA: the latest P4PHP version is installed automatically.
    • Swarm tarball installation: you must configure Swarm to use the version of P4PHP in the new Swarm tarball. For swarm tarball upgrade instructions, see Upgrade a Swarm tarball installation.

  • php-xml (DOM API for XML manipulation, the Swarm RSS feed will not work if it is not installed)

    Included with PHP on many operating systems. Must be manually installed on CentOS/RHEL unless you are installing Swarm from a package.

  • php-mbstring (multi-byte character strings, the Swarm RSS feed will not work if it is not installed)

    Included with PHP on many operating systems. Must be manually installed on CentOS/RHEL unless you are installing Swarm from a package.

  • php-redis (PHP extension for Redis, the Swarm cache will not work if it is not installed)

    Included with PHP on many operating systems. Must be manually installed on CentOS/RHEL unless you are installing Swarm from a package.

  • CentOS: in addition to php-redis:

    • CentOS 6: the following extensions must be manually installed unless you are installing Swarm from a package:

      • sclo-php70-php-pecl-redis (PHP extension for Redis, the Swarm cache will not work if it is not installed)
      • sclo-php70-php-pecl-igbinary (replacement PHP serializer for Redis, the Swarm cache will not work if it is not installed)

    • CentOS 7: the following extensions must be manually installed unless you are installing Swarm from a package:

      • sclo-php71-php-pecl-redis (PHP extension for Redis, the Swarm cache will not work if it is not installed)
      • sclo-php71-php-pecl-igbinary (replacement PHP serializer for Redis, the Swarm cache will not work if it is not installed)
  • RHEL: in addition to php-redis:

    • RHEL 6: the following extensions must be manually installed unless you are installing Swarm from a package:

      • php70-php-pecl-redis (PHP extension for Redis, the Swarm cache will not work if it is not installed)
      • php70-php-pecl-igbinary (replacement PHP serializer for Redis, the Swarm cache will not work if it is not installed)

    • RHEL 7: the following extensions must be manually installed unless you are installing Swarm from a package:

      • php71-php-pecl-redis (PHP extension for Redis, the Swarm cache will not work if it is not installed)
      • php71-php-pecl-igbinary (replacement PHP serializer for Redis, the Swarm cache will not work if it is not installed)

Recommended PHP extension

Swarm greatly benefits from the following PHP extension:

Building PHP from source (not recommended)

If you build PHP from source, the following dependencies are required:

  • openssl
  • mcrypt
  • zlib
  • gettext
  • curl
  • apxs (Apache extension tool)

See the source PHP documentation for details on how to include these modules in your PHP build. There is normally a --with-xxxx option that defines where the dependency is loaded from.

For example for apxs, zlib, and openssl:

./configure --with-apxs2=<path_to_apxs> --with-zlib=<path_to_zlib_library> --with-openssl

Helix Core server requirements

Swarm works with any supported version of the Helix server (Standard Maintenance). The versions supported in this release of Swarm are:

  • 2017.2 at 1622831 or later
  • 2018.1
  • 2018.2
  • 2019.1, see note below.

    • Note

    Helix server 2019.1 introduced the Private editing of streams feature that enables you to edit a stream spec in your workspace. The level of Swarm support depends on the version of Helix server 2019.1 installed:

    • Helix server 2019.1 at 1832527 or earlier: if you request a review from a changelist that contains a stream spec that was edited using this feature, it will not be displayed in the review. Other files in the changelist are displayed correctly in the review.
    • Helix server 2019.1 later than 1832527: stream specs can be edited in your workspace using this feature and they are displayed in reviews.

  • 2019.2

Download Helix server from here: https://www.perforce.com/downloads/helix-core-p4d

Helix server automated user requirements for Swarm

Swarm requires an automated user with at least admin privileges in the Helix Core server to enable Swarm to run against the Helix server. This can be an existing user, or a new user created specifically to support Swarm.

Important

If your Helix server is configured for Multi-Factor Authentication (MFA), the user account running Swarm must not use MFA.

For more information about setting up Helix Core server, see Installing and upgrading the server in Helix Core Server Administrator Guide: Fundamentals.

Trigger dependencies

Swarm triggers are installed on the Helix server during Swarm installation.

The Swarm triggers require perl 5.08+:
https://www.perl.org/get.html

On the Windows platform, we have tested Swarm against Strawberry Perl. There are two Perl modules that are also required which may not be part of a minimal Perl installation.

  • HTTP::Tiny is required to make calls to the Swarm server. If this is not present, then the trigger will attempt to use the command line curl program. This module is standard on Strawberry Perl on Windows, and available as a package with the version of Perl provided on CentOS 7, Ubuntu 16.04, and Ubuntu 18.04.

    • IO::Socket::SSL is required if the Swarm server is configured to use SSL and HTTP::Tiny is present. This is provided as standard by Strawberry Perl, and available on Linux.

    Warning

    If the HTTP::Tiny module is not available, for example on CentOS 6, then the triggers require the use of curl. This must be installed for the triggers to function. On CentOS 6 this can be done using the yum package installer using yum install curl if it isn't already installed.

Swarm triggers also require the following perl modules to be installed:

  • Windows:
    • JSON is required to exchange data between the browser and the server and is included by default with Strawberry Perl.
  • Ubuntu:
    • JSON is required to exchange data between the browser and the server and must be installed.
    • libjson-perl is required to manipulate JSON formatted data and must be installed.
  • CentOS/RHEL:
    • JSON is required to exchange data between the browser and the server and must be installed.
    • perl-JSON is required to manipulate JSON formatted data and must be installed.

Swarm package installation on the same machine as P4D

If Swarm is installed from a package on the same machine as P4D, the triggers require the following perl modules to be installed:

  • Ubuntu:
    • Perl 5.08+
    • libio-socket-ssl-perl is required if the Swarm server is configured to use SSL.
    • libjson-perl is required to manipulate JSON formatted data and must be installed.
  • CentOS/RHEL:
    • Perl 5.08+
    • perl-IO-Socket-SSL is required if the Swarm server is configured to use SSL.
    • perl-JSON is required to manipulate JSON formatted data and must be installed.

Worker dependencies

Swarm uses short-lived workers to process the Swarm queue, new workers are regularly spawned by a recurring task.

One of the following must be installed to ensure new workers are regularly spawned:

For more information about Swarm workers, see Set up a recurring task to spawn workers.

Redis server

Swarm requires Redis to manage its caches. Swarm caches data from the Helix server to improve the performance of common searches in Swarm and to reduce the load on the Helix server.

Redis is included with the Swarm package, OVA, and Tarball installations:

  • Swarm package or OVA: Redis is automatically installed on the Swarm machine and Swarm is automatically configured to use Redis.
  • Swarm Tarball installation: see the Redis installation and configuration section for instructions about installing Redis.

Optional:

If you prefer to use your own Redis server, you must edit the Redis server connection configurable in Swarm. For information on setting your Redis server connection, see Use your own Redis server.

Supported web browsers

The following browsers are supported for use with Swarm:

  • Apple Safari, latest stable version
  • Google Chrome, latest stable version
  • Mozilla Firefox, latest stable version
  • Microsoft Edge, latest stable version
  • Microsoft Internet Explorer, latest stable version

Other web browsers might also work, including prior, development or beta builds of the above web browsers, but are not officially supported.

Note

JavaScript and cookies must be enabled in the web browser for Swarm to operate.

Optional dependencies

LibreOffice

Swarm can display previews of office-type documents when LibreOffice is installed on the Swarm server. Installation is not required, but when LibreOffice is installed Swarm automatically detects its presence.

For more information about LibreOffice, see LibreOffice.

Zip

You can download a ZIP archive of files/folders when the zip command-line tool is installed on the Swarm server.

For more information about installing and configuring Zip, see Zip archive.

Helix Authentication Service SSO

Swarm support for SSO using Helix Authentication Service with Helix server requires Helix server 2019.1 or later

For more information about configuring Swarm to authenticate with Helix Authentication Service, see Single Sign-On PHP configuration.

Helix SAML authentication

Swarm support for Helix SAML authentication with Helix server requires Helix server version 2018.2 or later.

Important

Swarm email notifications

Sendmail or an equivalent is required to use Swarm email notifications. By default, the configuration in php.ini relies on SendMail being installed. For more information about configuring email for Swarm, see Email configuration.

Security-enhanced Linux (SELinux)

Swarm supports SELinux on CentOS 7. SELinux is an advanced access control mechanism that improves security for Linux distributions.

SELinux operates in one of three modes:

  • enforcing: this mode blocks and logs any actions that do not match the defined security policy. This is the default mode for SELinux on CentOS 7.
  • permissive: this mode logs actions that do not match the defined security policy but these actions are not blocked.
  • disabled: in this mode SELinux is off, actions are not blocked and are not logged.

See SELinux on CentOS 7 configuration for details.

If you see a Swarm configuration error similar to the error shown below, SELinux has not been correctly configured for Swarm. Check you have configured SELinux on CentOS 7 correctly.

Choose the installation process

Once you have reviewed the Runtime dependencies and know that you can satisfy them, there are a number of ways to install Swarm.

Tip

Installing Swarm using Install and configure Swarm from a package ensures that all of the Swarm dependencies are installed and is the easiest way to install Swarm.

Choose one of the following installation processes:

Additional product documentation
Perforce training portal
Perforce video library
Perforce knowledge base
Perforce customer support
Email us at: manual@perforce.com