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. 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.

Installation

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, follow the instructions for your OS distribution:

   Ubuntu

   Ubuntu 18.04:

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

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

   Ubuntu 20.04:

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

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

   CentOS/RHEL

   CentOS/RHEL 7:

   Create the file /etc/yum.repos.d/perforce.repo with the following content:

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

   CentOS/RHEL 8:

   Create the file /etc/yum.repos.d/perforce.repo with the following content:

   [Perforce]
   name=Perforce
   baseurl=http://package.perforce.com/yum/rhel/8/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.

   Follow the instructions for your OS distribution:

   Ubuntu:

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

   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.

   Follow the instructions for your OS distribution:

   Ubuntu

   sudo apt-get install helix-swarm

   CentOS

   Follow the instructions for your CentOS distribution version:

   CentOS 7.9 (run these commands as root):

   1. Deploy the epel-release-latest-7.noarch.rpm repository configuration package to give Swarm access to EPEL packages:

   yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

   2. Deploy the Remi repository configuration package to give Swarm access to PHP 7.x (only required the first time you upgrade to PHP 7.x):

   yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm

   Tip

   If you don't deploy the Remi repository you will see an error similar to the one shown below when you do the next steps:

   

   3. Install the yum-utils package to give access to the yum-config-manager command:

   yum install yum-utils

   4. Install the Default/Single version of PHP:
      1. Disable remi-php*:

      yum-config-manager --disable 'remi-php*'

      2. Enable PHP 7.4:

      yum-config-manager --enable remi-php74

      3. Run an upgrade for PHP:

      yum update

   5. Install Swarm and accept the prompts to import the GPG keys for Remi and EPEL when requested:

   yum install helix-swarm

   Note

   The firewall configuration may need to be adjusted to allow access to the web server.

   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

   CentOS 8.3 (run these commands as root):

   1. Deploy the epel-release-latest-8.noarch.rpm repository configuration package to give Swarm access to EPEL packages:

   dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

   2. Deploy the Remi repository configuration package to give Swarm access to PHP 7.x (only required the first time you upgrade to PHP 7.x):

   dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm

   Tip

   If you don't deploy the Remi repository you will see an error similar to the one shown below when you do the next steps:

   

   3. Install the yum-utils package to give access to the yum-config-manager command:

   dnf install yum-utils

   4. Install the Default/Single version of PHP:
      1. Enable the module stream for PHP 7.4:

      dnf module reset php

      2. Install PHP 7.4:

      dnf module install php:remi-7.4

      3. Run an upgrade for PHP:

      dnf update

   5. Install Swarm and accept the prompts to import the GPG keys for Remi and EPEL when requested:

   yum install helix-swarm

   Note

   The firewall configuration may need to be adjusted to allow access to the web server.

   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

   RHEL

   Follow the instructions for your RHEL distribution version:

   RHEL 7.9 (run these commands as root):

   1. Deploy the epel-release-latest-7.noarch.rpm repository configuration package to give Swarm access to EPEL packages:

   yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

   2. Deploy the Remi repository configuration package to give Swarm access to PHP 7.x (only required the first time you upgrade to PHP 7.x):

   yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm

   Tip

   If you don't enable the repository you will see an error similar to the one shown below when you do the next step:

   Error: Package: helix-swarm-2020.2-1845646.el6.x86_64 (perforce)
           Requires: rh-php74

   3. Install the yum-utils package to give access to the yum-config-manager command:

   yum install yum-utils

   4. Enable the optional channel for some dependencies:

   subscription-manager repos --enable=rhel-7-server-optional-rpms

   5. Install the Default/Single version of PHP:
      1. Disable remi-php*:

      yum-config-manager --disable 'remi-php*'

      2. Enable PHP 7.4:

      yum-config-manager --enable remi-php74

      3. Run an upgrade for PHP:

      yum update

   6. Install Swarm and accept the prompts to import the GPG keys for Remi and EPEL when requested:

   yum install helix-swarm

   Note

   The firewall configuration may need to be adjusted to allow access to the web server.

   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

   RHEL 8.2 (run these commands as root):

   1. Deploy the epel-release-latest-8.noarch.rpm repository configuration package to give Swarm access to EPEL packages:

   dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

   2. Deploy the Remi repository configuration package to give Swarm access to PHP 7.x (only required the first time you upgrade to PHP 7.x):

   dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm

   Tip

   If you don't enable the repository you will see an error similar to the one shown below when you do the next step:

   Error: Package: helix-swarm-2020.2-1845646.el6.x86_64 (perforce)
           Requires: rh-php74

   3. Install the yum-utils package to give access to the yum-config-manager command:

   dnf install yum-utils

   4. Install the Default/Single version of PHP:
      1. Enable the module stream for PHP 7.4:

      dnf module reset php

      2. Install PHP 7.4:

      dnf module install php:remi-7.4

      3. Run an upgrade for PHP:

      dnf update

   5. Install Swarm and accept the prompts to import the GPG keys for Remi and EPEL when requested:

   yum install helix-swarm

   Note

   The firewall configuration may need to be adjusted to allow access to the web server.

   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.

   Follow the instructions for your OS distribution:

   Ubuntu:

   sudo apt-get install helix-swarm-triggers

   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 ImageMagick and LibreOffice Swarm modules. These modules provide previews of a variety of image and office documents.

   Follow the instructions for your OS distribution:

   Ubuntu:

   sudo apt-get install helix-swarm-optional

   CentOS/RHEL (run this command as root):

   yum install helix-swarm-optional

6. 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 Authentication Service, 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 23 11:29:49 PDT 2018: 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/2017.2/1622831 (2017/10/24)
        Server license: 10000 users (support ends 2019/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 the Commit-edge chapter in the Helix Core Server Administrator Guide.

   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 Authentication Service, 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 php7 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 23 11:31:36 PDT 2018: 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/2.4/configuring.html

3. CentOS/RHEL only: Configure SELinux on CentOS/RHEL for Swarm, see SELinux on CentOS/RHEL configuration.

4. The basic Swarm configuration is now complete.

   Important

   If your Helix server is configured for Helix Authentication Service, 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. Establish a trigger token, see Establish trigger token.

SELinux on CentOS/RHEL configuration

Swarm supports SELinux on CentOS/RHEL 7 and CentOS/RHEL 8. 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.
• 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.

Configure SELinux to enforcing mode

Run the following commands as root:

1. Install the package that contains the semanage configuration tool, this is used to configure SELinux:

Follow the instructions for your OS distribution:

• CentOS/RHEL 7: Install the policycoreutils-python package:

root $ yum install policycoreutils-python

• CentOS/RHEL 8: Install the policycoreutils-python-utils package:

root $ yum install policycoreutils-python-utils

2. Check the current SELinux mode:

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.

   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. Allow content in /opt/perforce/swarm to be read and written by the httpd process:

root $ semanage fcontext -a -t httpd_sys_rw_content_t "/opt/perforce/swarm(/.*)?"
root $ restorecon -R /opt/perforce/swarm			

5. Allow the httpd process to connect to other networked services, for example P4D and Redis:

root $ setsebool -P httpd_can_network_connect 1

6. Allow the files in p4-bin to be executed by the httpd process:

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. Remove the executable constraints on Redis, allowing it to be started by systemd at boot time:

root $ semanage fcontext -a -t bin_t /opt/perforce/swarm/sbin/redis-server-swarm
root $ restorecon -v /opt/perforce/swarm/sbin/redis-server-swarm		

8. Restart the system:

root $ systemctl restart httpd

9. Check that you can log in to Swarm.
10. Only if required: Relabel your filesystem, see note before relabeling:
Important

Relabeling your file system can be a time consuming process, it is recommended that you only do this if you need to. This depends entirely on your SELinux setup, Perforce cannot give you advice on this.

root $ touch /.autorelabel

11. Reboot the server.
12. Check that you can log in to Swarm.
13. SELinux is now configured for Swarm.

Error message: If you see an error message with a title similar to the message below, it may be because you are running CentOS/RHEL 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 permissive or disabled mode

Run the following as root:

1. Check the current SELinux mode:

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.

   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.

Upgrading

See Upgrade 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.

   Follow the instructions for your OS distribution, the following examples assume that the packages are all installed on the same server:

   Ubuntu, uninstalling packages:

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

   CentOS/RHEL, uninstalling packages (run this command as root):

   yum remove helix-swarm helix-swarm-triggers helix-swarm-optional