Install and configure Swarm on Amazon Linux 2

Swarm packages can be used to install Swarm on Amazon Linux 2. Using packages greatly simplifies the installation, updating, and removal of software, because the tools that manage 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, 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 Core Server cannot use packages, for example when it is running Windows, skip this step on that server.

   Run the following command as root:

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

   For information about how to verify the authenticity of the signing key, see Perforce Packages.

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

   Run the following commands as root:

   1. Deploy the EPEL repository configuration package to give Swarm access to the EPEL packages.

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

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

   yum install yum-utils

   3. Install the Amazon Extras repository if it is not already installed:

      yum install -y amazon-linux-extras

   4. Enable PHP 8.3 from Amazon Linux Extras:

   amazon-linux-extras enable php8.3

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

   yum install helix-swarm

   Important

   When the Swarm installation has completed, you are prompted to run the configure-swarm.sh post-installation script.

   Do not run this script until you have completed the rest of these Installation instructions. Instructions for running the configure-swarm.sh post-installation script are in the Post-Installation configuration section referenced in the final step of the Installation instructions.

   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. Swarm needs to know about some Helix Core Server events to operate correctly. Use Helix Core Server Extensions (recommended) or Helix Core Server Triggers to notify Swarm about these events. The Swarm Helix Core Server extension can be installed automatically by the Swarm configure-swarm.sh post-installation script, but Triggers must be manually installed. To use Helix Core Server Extensions, ignore this step and skip to the next step.

   Trigger installation only (not recommended): Install the Swarm triggers package on the server hosting your Helix Core Server. This might be the server hosting Swarm or elsewhere on your network.

   Important

   If the server hosting your Helix Core 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 Core Server. The swarm-trigger.pl is for both Linux and Windows systems. Once copied, the trigger script needs to be configured. See Installing Triggers for details.

   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 Installing Triggers for more details on configuring that file.

5. Optional: While not required, installing the optional Swarm package installs the dependencies required to use the LibreOffice Swarm module. This enables Swarm to preview office documents.

   1. Enable LibreOffice in Amazon Linux Extras with:

   amazon-linux-extras enable libreoffice

   2. Install the Swarm optional package, on the server hosting Swarm (run the command as root):

   yum install helix-swarm-optional

6. Make your Swarm installation more secure by applying recommendations related to HTTP and Swarm implementation through security groups. See Secure your Swarm installation .

7. Complete the Post-installation configuration steps.

Secure your Swarm installation

To make your Swarm installation more secure apply the following recommendations for HTTP and Swarm implementation through security groups.

HTTP

Here is a list of best practices to use when port 80 is exposed for HTTP traffic:

• Redirect to HTTPS: If Port 80 needs to be open to support legacy systems or specific use cases, ensure that all HTTP traffic is redirected to HTTPS to encrypt data in transit.

• Use HSTS (HTTP Strict Transport Security) headers: Implement HSTS headers to force browsers only to use secure HTTPS connections when interacting with your server.

• Close port 80: If there is no requirement to use HTTP, Port 80 must be closed entirely to prevent any unencrypted data transmission.

• Implement SSL/TLS (secure sockets layer and transport layer security) certificates: Ensure that your server is configured with a valid SSL/TLS certificate to enable secure HTTPS connections.

• Firewall configuration: Configure firewalls to block or filter access to Port 80, particularly from untrusted networks.

• Continuous monitoring and auditing: Regularly monitor network traffic and audit server configurations to ensure that unnecessary ports are not exposed and that data is transmitted securely.

When you implement HTTPS, you must make the following changes:

1. Modify your cron job for the Swarm workers.

   Edit the cron configuration file to point to your HTTPS URL, for example, https://HOSTNAME/. For more information about how to edit the cron configuration file, see Set up a recurring task to spawn workers.

   To verify if the cron configuration file points to your HTTPS URL, run the following curl statement:

   curl https://myswarm.host/queue/worker

2. Modify the Swarm Extension or Trigger configuration.

   If you are using the Swarm extension run the following command and change ExtConfig’s Swarm URL to be your new HTTPS URL:

   p4 extension --configure Perforce:helix-swarm

   If you are using triggers, edit swarm-trigger.pl configuration file and set your SWARM_HOST to be https.

3. Edit the external_url in the SWARM_ROOT/data/config.php file’s environment block to point to your HTTPS URL. This URL is used in emails, Jira links, and Swarm test’s pass-and-fail outgoing URL parameters.

   Tip

   If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

4. Modify the Helix Core Server's P4.Swarm.URL property. For more information about Helix Core Server integration, see Client integration.

   If your Apache server is listening on both HTTPS and HTTP in perforce-swarm-site.conf file, you must set the auto_register_urlconfigurable in the p4 block to false and correctly configure the P4.Swarm.URL property .

   If your Apache server is listening only on HTTPS and if the auto_register_urlconfigurable in the p4 block is set to true (default value), an Apache restart will correct the property.

   To get all your current values for P4.Swarm.URL property, run:

   p4 -Ztag property -A -l -n P4.Swarm.URL

   Ensure that the P4.Swarm.URL property points to your HTTPS URL.

5. Modify the URL of all applications. Any other applications that reference the URL should be switched to using the HTTPS URL.

Swarm implementation through security groups

Here is a list of best practices for implementation using security groups or the user's preferred setup:

• Use a trusted proxy: Ensure to only use a trusted proxy, such as allow lists, Content Delivery Networks (CDN), and API Gateways.

• Backend servers and other proxies or load balancers should be disabled: Ensure that direct access to backend servers and other proxies or load balancers is disabled, except through the trusted proxy mentioned above. This will prevent unauthorized access while ensuring that all requests are filtered through the trusted proxy.

• Continuous monitoring and logging of the X-Forwarded-For header: Implement monitoring and logging on the X-Forwarded-For header to track and identify any suspicious activities. This can help in identifying and preventing potential malicious activity or security threats.

• Use a secure protocol: Implement a secure protocol such as HTTPS to encrypt the communications between the client and the load balancers, and between the load balancer and backend server to prevent eavesdropping or tampering with the X-Forwarded-For header.

• Configure X-Forwarded-For header: Configure the processing mode of the X-Forwarded-For header (append, preserve, or remove) based on specific technical or security requirements.

Post-installation configuration

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

1. Use the Swarm post-installation script to configure Swarm on the server hosting Swarm.

   Important

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

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

   • To use Helix Core Server Extensions, make sure that Extensions are installed and configured on your Helix Core Server before running the configuration script. For information about Helix Core Server Extensions , see p4 extension in Helix Core Command-Line (P4) Reference and Extensions overview in Helix Core Extensions Developer Guide.

   Note

   The Swarm post-installation 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 the interactive post-installation configuration script:

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

   The configuration script displays the following summary:

   ------------------------------------------------------------
   configure-swarm.sh: Thu Aug 26 11:29:49 PDT 2021: commencing configuration of Swarm
   Summary of arguments passed:
   Interactive?       [yes]
   Force?             [no]
   P4PORT             [(not specified, will prompt)]
   Swarm user         [(not specified, will prompt, will suggest swarm)]
   Swarm password     [(not specified, will prompt)]
   Email host         [(not specified, will prompt)]
   Create depot       [(not specified, will prompt)]
   Bypass Lock        [(not specified)] 
   Use Extensions?    [(not specified, will prompt)] 
   Swarm host         [(not specified, will prompt, will suggest myhost)]
   Swarm port         [(default (80))]
   Swarm base URL     [(default (empty))]
   Create Swarm user? [yes]
   Super user         [(not specified, will prompt)]
   Super password     [(not specified, will prompt)]

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 Core 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/2021.1/2179737 (2021/04/24)
        Server license: 10000 users (support ends 2022/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

      To allow users to clean up reviews created by other users when the review is committed, the Helix Core Server user account must have super permissions. 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

      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 expires in less than a year, you will receive a warning. If you receive this warning, ask your Helix Core Server administrator to make sure the swarm user is in a Helix Core Server group that has the Timeout field set to a year or more. See p4 group in the Helix Core Command-Line (P4) Reference.

      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, for example
      'swarm.company.com', but it can be just a hostname, for example '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 or leave empty to use your local mail handler.

      Swarm can use a mail relay host to send email notifications. Leave empty if
      you want to use the local mail handler (for example Sendmail, Postfix etc),
      or enter a hostname (for example mx.yourdomain.com) to use a relay host.
       
      Mail relay host: 

      Note

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

   5. To enable file attachments on comments, Swarm must have a depot location to save the attachment files in. Swarm can create this depot and set the depot protections for you automatically or you can manually set it up later.

      Important

      You must be a user with super user permissions to create the .swarm depot and set protections.

      - checking depot 
      
      Swarm has the ability to store attachments against review comments. To
      do this, it needs to have a depot where they are stored. By default,
      this is //.swarm. We can create the depot for you automatically, and
      set the protections on it to the following: 
      
      list user * * -//.swarm/...
      admin user swarm * //.swarm/...
      super user super * //.swarm/...
       
      If you want to enable attachments, and for the depot and protections
      to be set up for you, then say yes here. If you say no, then you can
      still do this manually later.
      Do you want to create a .swarm depot and set protections? (y/n) [n]

      When prompted to automatically create the depot, select one of the following:

      • Type y to automatically create the .swarm depot and set protections.

      • Type n skip depot creation. You can create the depot and set the protections manually later if you want to, see Comment attachments.

      If you choose to automatically create the depot, the script will create the depot, set the protections, and report when completed.

      Depot //.swarm successfully created. Protections have been set so
      that only the 'swarm' and 'super' have permissions to
      access it directly. 

   6. Swarm needs to know about the exclusive locks to work with exclusively opened files. To enable exclusive locks, set the filetype.bypasslock to 1. For more information about exclusive locks, see Handling Exclusive Locks.
   Tip

   If this setting is not enabled in Helix Core Server, Swarm will report exceptions when working with exclusively opened files similar to Cannot unshelve review (x). One or more files are exclusively open, and that you must have the filetype.bypasslock configurable enabled.

   7. Swarm needs to know about some Helix Core Server events to operate correctly. Use Helix Core Server Extensions (recommended) or Helix Core Server Triggers to notify Swarm about these events. Helix Core Server Extensions are easier to install and maintain than triggers.

      Important

      You must be a user with super user permissions to install and configure Helix Core Server Extensions.

      Do you want to use Swarm's Helix Core server extension?
      Configuring Server extensions requires super user access to the Helix Server.
      If you install the Swarm server extension, do not install the Swarm triggers.
      Server extensions are supported for:
      * Linux: Helix server 19.2 and later.
      * Windows: Helix server 21.2 and later. 
      
      Use server extensions? 

      When prompted to Use server Extensions, choose one of the following:

      • Recommended: Type y to use Helix Core Server Extensions. The configuration script will try and install and configure the Swarm Helix Core Server extension.

      • Type n to use Helix Core Server Triggers. Triggers must be installed manually, Swarm will prompt you to do this when the Swarm configuration script completes.

      Note

      If you choose to install the Swarm Helix Core Server Extensions, the script will:

      • check your Helix Core Server supports Helix Core Server Extensions

      • check if Helix Core Server Extensions are installed and configured on your Helix Core Server. If they are, Swarm does not need to do anything

      • install and configure the Swarm Helix Core Server extension on your Helix Core Server

      If any of these checks fail, Swarm will not install the Swarm Helix Core Server extension and will report the issues on the configuration summary screen.

   Once all of the information has been provided, the configuration script configures Swarm. When it has completed the configuration, the configuration summary screen is displayed, for example:

   ...........
   -restarting Apache...
   -Apache restarted
   configure-swarm.sh: Thu Aug 26 11:31:36 PDT 2021: 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.
   ::
   ::  Ensure that you have configured the Swarm hostname in your
   ::  network's DNS, or have added an IP address-to-hostname
   ::  mapping to your computer's hosts configuration so that you
   ::  can access Swarm.
   :: 
   ::  Server side extensions are installed and configured
   ::  on your P4D server.
   ::
   ::  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.

To disable Apache's default configuration, manually adjust the Apache configuration. Such changes require familiarity with Apache configuration; for more details, see Apache HTTP server project.

To add Swarm as an HTML tab in the Helix Core Visual Client (P4V), see HTML Tabs section in the P4VJS Developer Guide.

3. Configure SELinux for Swarm, see SELinux configuration.

4. The basic Swarm configuration is now complete.

   Important

   If your Helix Core 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 Core Server, run the following command:

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

5. Do one of the following:

   • If the Swarm Helix Core Server extension was installed by the configuration script: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.

   • If the Swarm Helix Core Server extension was not installed, you must install triggers: Configure Helix Core Server for Swarm, see Installing Triggers.

SELinux configuration

Swarm supports SELinux which 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 policycoreutils-python package that contains the semanage configuration tool, this is used to configure SELinux

root $ yum install policycoreutils-python

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 comment attachment thumbnails to be created:

root $ setsebool -P httpd_tmp_exec 1

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

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

9. Restart the system:

root $ systemctl restart httpd

10. Check that you can log in to Swarm.
11. 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

12. Reboot the server.
13. Check that you can log in to Swarm.
14. 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 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 permissiveor disabledas 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.

Uninstall

1. Depending on how you have configured your Helix Core Server events, do one of the following:

   • Uninstall the Swarm Helix Core Server extension. To do this, run the following command on your Helix Core Server:

     p4 extension --delete Perforce::helix-swarm --yes

   • Uninstall the Swarm triggers. As a super user, run the p4 triggers command from your Helix Core Server and manually remove all the Swarm trigger code lines.

2. Uninstall the Swarm main package, the Swarm triggers package, and the Swarm optional package. The following example assumes that the packages are all installed on the same server (run the command as root):

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

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

   Important

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