Helix Swarm Guide (2018.3)

Install and configure Swarm from a package

Helix Swarm is available in two distribution package formats: Debian (.deb) for Ubuntu systems and RPMRPM Package Manager is a tool, and package format, for managing the installation, updates, and removal of software packages for Linux distributions such as Red Hat Enterprise Linux, the Fedora Project, and the CentOS Project. (.rpm) for CentOS and RedHat Enterprise Linux (RHEL).

Using distribution packages greatly simplifies the installation, updating, and removal of software, as the tools that manage these packages are aware of the dependencies for each package.

Note

The Swarm packages have been thoroughly tested on Ubuntu 14.04 LTS and Ubuntu 16.04 LTS, and CentOS/RHEL 6.1-6.7, and CentOS/RHEL 7. While the packages should work on other compatible distributions, these have not been tested.

Note

Helix Core Server can refer to a Helix Server machine (p4d), proxy, broker, replica, edge server, or commit server. For simplicity, the term Helix Server is used to refer to any configuration of a Helix Core Server machine.

Installation

Important

Review the Helix Server requirements before you install Swarm, see Helix Core Server requirements.

  1. Configure the Perforce package repository, on the server to host Swarm and on the server hosting your Helix Core Server.

    Important

    If the server hosting your Helix Core Server cannot use packages, for example when it is running Windows, skip this step on that server.

    As root, run one of the following:

    • For Ubuntu 14.04:

      Create the file /etc/apt/sources.list.d/perforce.list with the following content:

      deb http://package.perforce.com/apt/ubuntu/ trusty release

    • For Ubuntu 16.04:

      Create the file /etc/apt/sources.list.d/perforce.list with the following content:

      deb http://package.perforce.com/apt/ubuntu/ xenial release

    • For CentOS/RHEL 6:

      Create the file /etc/yum.repos.d/helix-swarm.repo with the following content:

      [Perforce]
      name=Perforce
      baseurl=http://package.perforce.com/yum/rhel/6/x86_64/
      enabled=1
      gpgcheck=1

    • For CentOS/RHEL 7:

      Create the file /etc/yum.repos.d/helix-swarm.repo with the following content:

      [Perforce]
      name=Perforce
      baseurl=http://package.perforce.com/yum/rhel/7/x86_64/
      enabled=1
      gpgcheck=1

  2. Import the Perforce package signing key, on the server to host Swarm and the server hosting your Helix Core Server.

    Important

    If the server hosting your Helix Server cannot use packages, for example when it is running Windows, skip this step on that server.

    Run one of the following:

    • For Ubuntu: 

      $ wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -
      $ sudo apt-get update

    • For CentOS/RHEL (run this command as root):

      # rpm --import https://package.perforce.com/perforce.pubkey

    For information about how to verify the authenticity of the signing key, see: https://www.perforce.com/perforce-packages

  3. Install the main Swarm package on the server to host Swarm.

    Run one of the following:

    • For Ubuntu: 

      $ sudo apt-get install helix-swarm

    • For CentOS/RHEL (run this command as root):

      # yum install helix-swarm
      Note

      For CentOS/RHEL, the firewall configuration may need to be adjusted to allow access to the web server.

      • For CentOS/RHEL 6.x: 

        $ sudo lokkit -s http

        If you subsequently wish to enable HTTPS, run (as root):

        $ sudo lokkit -s https

      • For CentOS/RHEL 7.x: 

        $ sudo firewall-cmd --permanent --add-service=http
        $ sudo systemctl reload firewalld

        If you subsequently wish to enable HTTPS, run (as root):

        $ sudo firewall-cmd --permanent --add-service=https
        $ sudo systemctl reload firewalld

  4. Install the Swarm triggers package on the server hosting your Helix Core Server.

    Install this package on the server hosting your Helix Core Server, which may be the same server that is hosting Swarm, or elsewhere on your network.

    Important

    If the server hosting your Helix Server cannot use packages, for example when it is running Windows, you need to copy the appropriate Swarm trigger script from /opt/perforce/swarm/p4-bin/scripts to the server hosting your Helix Server. The swarm-trigger.pl is for both Linux and Windows systems. Once copied, the trigger script needs to be configured. See Helix Core Server configuration for Swarm for details.

    Run one of the following:

    • For Ubuntu: 

      $ sudo apt-get install helix-swarm-triggers

    • For CentOS/RHEL (run this command as root): 

      $ yum install helix-swarm-triggers
    Important

    The package installs a config file at /opt/perforce/etc/swarm-trigger.conf that you will need to modify. See Helix Core Server configuration for Swarm for more details on configuring that file.

  5. Optional: Install the Swarm optional package, on the server hosting Swarm.

    While not required, installing this package installs the dependencies required to use the Imagick and LibreOffice Swarm modules. These modules provide previews of a variety of image and office documents.

    Run one of the following:

    • For Ubuntu: 

      $ sudo apt-get install helix-swarm-optional

    • For CentOS/RHEL (run this command as root): 

      # yum install helix-swarm-optional
      Important

      This package depends on the package php-pecl-imagick which is available from the EPEL project. In order to install packages from EPEL, you will need to add the EPEL repository and accept its signing key. Instructions are available at: https://fedoraproject.org/wiki/EPEL

      Note

      Installation of this package also installs APC for CentOS/RHEL 6, or Zend OPCache for CentOS/RHEL 7.

  6. 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
  7. Complete the Post-installation configuration steps.

Post-installation configuration

Once the helix-swarm package has been installed, additional configuration is required. Perform the following steps:

  1. Use the Swarm configuration script to setup Swarm, on the server hosting Swarm.

    Important

    If your Helix Server is configured for Helix SAML, the Helix Server must be temporarily configured to allow fall-back to passwords while you establish a connection to the Helix Server. Run the following command on the Helix Server to enable fall-back to passwords:

    p4 configure set auth.sso.allow.passwd=1

    Note

    The Swarm configuration script can be used in a few different ways. The steps below outline the most straightforward configuration using an interactive install, but you can review the options by running:

    $ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -h

    Run an interactive install:

    $ sudo /opt/perforce/swarm/sbin/configure-swarm.sh

    The configuration script displays the following summary:

    ------------------------------------------------------------
    configure-swarm.sh: Thu Aug 25 11:29:49 PDT 2016: commencing configuration of Swarm
    Summary of arguments passed:
    Interactive?       [yes]
    Force?             [no]
    P4PORT             [(not specified)]
    Swarm user         [(not specified, will suggest swarm)]
    Swarm password     [(not specified)]
    Email host         [(not specified)]
    Swarm host         [(not specified, will suggest myhost)]
    Swarm port         [80]
    Swarm base URL     [(default (empty))]
    Create Swarm user? [no]
    Super user         [(not specified)] * not needed
    Super password     [(not specified)] * not needed

  2. Provide information to the configuration script.

    After the summary, the configuration script prompts for the following information:

    1. Specify a value for P4PORT in the form: my-helix-core-server:1666

      No P4PORT specified

      Swarm requires a connection to a Helix Core Server.
Please supply the P4PORT to connect to.

      Helix Core Server address (P4PORT):

      Specify the hostname and port for your Helix Server. If defined, the value for P4PORT is used as the default. The configuration script verifies that it can connect:

      -response: [myp4host:1666]

      Checking P4PORT [myp4host:1666]...
      -P4 command line to use: [/opt/perforce/bin/p4 -p myp4host:1666]
      Attempting connection to [myp4host:1666]...
      -connection successful:
        Server address: myp4host:1666
        Server version: P4D/LINUX26X86_64/2016.1/1411799 (2016/07/12)
        Server license: 10000 users (support ends 2017/05/16)
        Server license-ip: 192.168.0.1
      Important

      If your Helix Core Server is deployed using the commit-edge architecture, ensure that the Swarm port value points to the commit server.

      For more information, see Commit-edge in the Helix Core Server Administrator Guide: Multi-Site Deployment.

    2. Specify the userid and password of a normal user with admin-level privileges in the Helix Core Server.

      Checking Swarm user credentials...
      No Swarm user specified

      Swarm requires a Helix user account with 'admin' rights.
      Please provide a username and password for this account.
      If this account does not have 'admin' rights, it will 
      be set for this user.

      Helix username for the Swarm user [swarm]:

      Enter the userid. The default is swarm.

      Note

      If the Helix Server user account is given 'super' rights, then this allows a user to clean up a review created by another user when the review is committed. See Review cleanup.

      -response: [swarm]
      						
      Helix password or login ticket for the Swarm user (typing hidden):

      Enter the login ticket, or password, for the userid.

      Important

      If your Helix Server is configured for Helix SAML, you must use a long-lived login ticket for the Swarm user.

      Note

      You can obtain a login ticket by running (in another shell):

      $ p4 -p myp4host:1666 -u userid login -p

      If the login ticket you provide would expire in less than a year, you will receive a warning.

      Checking Swarm user credentials...
      -checking if user [swarm] exists in [myp4host:1666]...
      -user exists
      Obtaining Helix login ticket for [swarm] in [myp4host:1666]...
      -login ticket obtained
      Checking user [swarm]'s ticket against [myp4host:1666]...
      -login ticket is good
      Checking user [swarm] has at least access level [admin]...
      -user has maximum access level [admin]
      -user meets minimum access level [admin]

    3. Specify the hostname for the Swarm UI.

      Swarm needs a distinct hostname that users can enter into their browsers to
      access Swarm. Ideally, this is a fully-qualified domain name, e.g.
      'swarm.company.com', but it can be just a hostname, e.g. 'swarm'.

      Whatever hostname you provide should be Swarm-specific and not shared with
      any other web service on this host.

      Note that the hostname you specify typically requires configuration in your
      network's DNS service. If you are merely testing Swarm, you can add a
      hostname->IP mapping entry to your computer's hosts configuration.

      Hostname for this Swarm server [myhost]:
      Note

      The default is the current hostname. The configuration script does not verify that the hostname actually works (DNS configuration may not exist yet).

    4. Specify a mail relay host.

      Swarm requires an mail relay host to send email notifications.

      Mail relay host (e.g.: mx.yourdomain.com):
      Note

      The configuration script does not verify that the mail relay host you provide actually accepts SMTP connections.

      Once this information has been provided, the configuration script performs the following steps (some of the detail depends on the version of PHP and Apache that is installed):

      Configuring Cron...
`/opt/perforce/etc/swarm-cron-hosts.conf.new' -> `/opt/perforce/etc/swarm-cron-hosts.conf'
-updated cron configuration file with supplied Swarm host
Configuring Swarm installation...
-composed new Swarm config file contents
`/opt/perforce/swarm/data/config.php.new' -> `/opt/perforce/swarm/data/config.php'
-wrote new Swarm config file to reflect new configuration
-identified Apache user:group: [www-data:www-data]
-setting permissions on the Swarm data directory...
-ensured file permissions are set properly
Configuring Apache...
-identified Swarm virtual host config file: [/etc/apache2/sites-available/perforce-swarm-site.conf]
-identified Apache log directory: [/var/log/apache2]
-updated the vhost file to set Apache log directory
-updated the vhost file to reflect Swarm host
-checking Apache modules...
Enabling module rewrite.
Module php5 already enabled
To activate the new configuration, you need to run:
  service apache2 restart
-proper Apache modules are enabled
-enabling Swarm Apache site...
Enabling site perforce-swarm-site.conf.
To activate the new configuration, you need to run:
  service apache2 reload
-Swarm Apache site enabled
-restarting Apache...
-Apache restarted
configure-swarm.sh: Thu Aug 25 11:31:36 PDT 2016: completed configuration of Helix Swarm

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::
::  Swarm is now configured and available at:
::
::      http://myhost/
::
::  You may login as the Swarm user [swarm] using the password
::  you specified.
::
::  Please ensure you install the following package on the server
::  hosting your Helix Core Server.
::
::      helix-swarm-triggers
::
::  (If your Helix Core Server is hosted on an OS and
::  platform that is not compatible with the above package, you can
::  also install the trigger script manually.)
::
::  You will need to configure the triggers, as covered in the Swarm
::  documentation:
::
::  http://www.perforce.com/perforce/doc.current/manuals/swarm/setup.perforce.html
::
::  Documentation for optional post-install configuration, such as
::  configuring Swarm to use HTTPS, operate in a sub-folder, or on a
::  custom port, is available:
::
::  https://www.perforce.com/perforce/doc.current/manuals/swarm/setup.post.html
::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
      Note

      If you have installed Swarm on a host that does not provide other web services, you may wish to disable Apache's default site configuration. Doing so means that regardless of the hostname a user might use to reach the web server hosting Swarm, Swarm would be presented.

      Be aware that disabling Apache's default site configuration could disable existing web services or content.

      Disabling Apache's default site configuration on Ubuntu hosts is easy. Run:

      $ sudo a2dissite 000-default

      For CentOS hosts, or for non-standard Apache installations, you would need to manually adjust the Apache configuration. Such changes require familiarity with Apache configuration; for more details, see: https://httpd.apache.org/docs/current/configuring.html

  3. Optional: To configure SELinux on CentOS 7 for Swarm, see SELinux on CentOS 7 configuration.

  4. The basic Swarm configuration is now complete.

    Important

    If your Helix Server is configured for Helix SAML, you can force all of your users to authenticate via your Identity Provider (IdP) by disabling fall-back to passwords. To disable fall-back to passwords on the Helix Server, run the following command:

    p4 configure set auth.sso.allow.passwd=0

  5. Configure the Swarm triggers on the Helix Server, see Helix Core Server configuration for Swarm.

SELinux on CentOS 7 configuration

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.

SELinux must be configured to enable it to work correctly with Swarm, these configuration steps are shown below.

Note

You must complete the Helix Swarm package Installation steps, and the Post-installation configuration steps before configuring SELinux.

Configure SELinux on CentOS 7 to enforcing mode

Run the following commands as root:

  1. Install the policycoreutils-python package, this contains semange which is used to configure SELinux: 
    2. root $ yum install policycoreutils-python
  2. Check the current SELinux mode:
    3. root $ getenforce
  3. SELinux will report its mode as; enforcing, permissive, or disabled.
    1. If the mode is not set correctly edit the /etc/selinux/config file with vi or a similar editor.
      2. root $ vi /etc/selinux/config
    2. Edit the config file so that SELinux= is set to enforcing .
    3. Save the config file.
    4. Reboot the server to complete the SELinux mode change.
  4. Define the context of the /opt/perforce/swarm directory and the files in it to httpd_sys_rw_content_t:
    5. root $ semanage fcontext -a -t httpd_sys_rw_content_t "/opt/perforce/swarm(/.*)?"
    root $ restorecon -R /opt/perforce/swarm
  5. Set the SELinux Boolean value to httpd_can_network_connect 1 to allow Swarm to connect to p4d and other services:
    6. root $ setsebool -P httpd_can_network_connect 1
  6. Define the context of the /opt/perforce/swarm/p4-bin directory and the files in it to httpd_sys_script_exec_t
    7. root $ semanage fcontext -a -t httpd_sys_script_exec_t '/opt/perforce/swarm/p4-bin(/.*)?'
root $ restorecon -R -v /opt/perforce/swarm/p4-bin
  7. Restart the system:
    8. root $ systemctl restart httpd
  8. Check that you can log in to Swarm.
  9. Reboot the server.
  10. Check that you can log in to Swarm.
  11. SELinux is now configured for Swarm.
Note

If you can not log in to Swarm it is possible that SELinux is blocking Swarm because its configuration is incorrect. You will need to troubleshoot the SELinux configuration to find any issues.

Install the setroubleshoot package, this contains sealert which is used when troubleshooting SELinux:

root $ yum install setroubleshoot

sealert helps you to interpret the contents of the audit.log. Run the following command:

root $ sealert -a /var/log/audit/audit.log

Error message: If you see an error message with a title similar to the message below, it may be because you are running CentOS 7 on a Virtual Machine (VM).

root $ SELinux is preventing /usr/sbin/ldconfig from write access on the directory etc.

Install open-vm-tools on the VM and reboot the VM. 

root $ yum install open-vm-tools

Configure SELinux on CentOS 7 to permissive or disabled mode

Run the following as root:

  1. Check the current SELinux mode:
    2. root $ getenforce
  2. SELinux will report its mode as; enforcing, permissive, or disabled.
    1. If the mode is not set correctly edit the /etc/selinux/config file with vi or a similar editor.
      2. root $ vi /etc/selinux/config
    2. Edit the config file so that SELinux= is set to permissive or disabled as required.
    3. Save the config file.
    4. Reboot the server to complete the SELinux mode change.
  3. Check that you can log in to Swarm.
  4. SELinux is now configured for Swarm.

Updating

See Update a Swarm package installation for details.

Uninstall

  1. Remove the Swarm triggers from your Helix Server.

  2. Remove the Swarm trigger scripts from the server hosting your Helix Server.

    Important

    If you manually installed the trigger script, perhaps because the server hosting your Helix Server cannot use packages (e.g. Windows), manually remove the script.

    Run one of the following:

    • For Ubuntu: 

      $ sudo apt-get remove helix-swarm helix-swarm-triggers helix-swarm-optional

    • For CentOS/RHEL (run this command as root): 

      # yum remove helix-swarm helix-swarm-triggers helix-swarm-optional
Additional product documentation
Perforce training portal
Perforce video library
Perforce knowledge base
Perforce customer support
Email us at: manual@perforce.com