Post-install configuration options

There are a few options for customizing your Swarm installation's operation. This section covers the options that are officially supported.

This section contains:

• No customization required
• Back up your Swarm virtual host first
• HTTPS
• Run Swarm in a sub-folder of an existing web site
• Run the Swarm virtual host on a custom port
• Use your own Redis server
• Hiding Swarm storage from regular users
• Handling Exclusive Locks

No customization required

If you do not need to customize your Swarm installation, your Swarm installation is complete but you must check that it is working correctly before using it in production. For instructions on how to check your Swarm installation, see Validate your Swarm installation.

Back up your Swarm virtual host first

Before undertaking any of the following customization options, ensure that you have backed up your Swarm virtual host configuration. Choose the most appropriate option:

• If your Apache configuration directory contains the directories sites-available and sites-enabled:

  $ cd /path/to/apache/configuration/..
  $ cp -a sites-available sites-available.bak

  Important

  If the sites-enabled directory contains files, and not just symbolic links, you need to backup this folder as well:

  $ cd /path/to/apache/configuration/..
  $ cp -a sites-enabled sites-enabled.bak

• For CentOS/RHEL systems, if you used the Swarm packages to install Swarm:

  $ cd /path/to/apache/configuration/..
  $ cp -a conf.d conf.d.bak

• Otherwise, back up your Apache configuration.

HTTPS

This section describes how to make your Swarm installation more secure by using HTTPS.

Before you begin the following procedure, locate your system's Apache configuration. Common configuration directories include:

• /etc/httpd/conf/
• /etc/apache2/
• /usr/local/apache2/conf/
• /Applications/XAMPP/etc/

Within the Apache configuration path, the main Apache configuration file is usually named one of the following:

• httpd.conf
• apache2.conf

A longer discussion on the possible locations and names of Apache configuration files is available here: https://cwiki.apache.org/confluence/display/httpd/DistrosDefaultLayout

1. Enable SSL in Apache.

   If the Apache utility a2enmod is installed:

   $ sudo a2enmod ssl

   Without the a2enmod utility, edit the Apache configuration file by hand. Locate your Apache configuration file for modules and either uncomment or add the following lines:

   LoadModule  ssl_module  libexec/apache2/mod_ssl.so

2. Create a directory to store certificates.

   $ sudo mkdir -p /etc/apache2/ssl

3. Create a certificate/key pair.

   $ cd /etc/apache2/ssl
   
   $ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout apache.key -out apache.crt

   This command generates a private key and a certificate. To form the certificate, openssl prompts you for several details:

   Generating a 2048 bit RSA private key
   ...................+++
   ....................................+++
   writing new private key to 'apache.key'
   -----
   You are about to be asked to enter information that will be incorporated
   into your certificate request.
   What you are about to enter is what is called a Distinguished Name or a DN.
   There are quite a few fields but you can leave some blank
   For some fields there will be a default value,
   If you enter '.', the field will be left blank.
   -----
   Country Name (2 letter code) [AU]:CA
   State or Province Name (full name) [Some-State]:British Columbia
   Locality Name (eg, city) []:Victoria
   Organization Name (eg, company) [Internet Widgits Pty Ltd]:Perforce Software
   Organizational Unit Name (eg, section) []:Swarm development team
   Common Name (e.g. server FQDN or YOUR name) []:myswarm.host
   Email Address []:[email protected]

   The output above includes some example details. You should replace anything in italics with your own details. Since the certificate request details that can help users determine whether your certificate is valid, enter legitimate information whenever possible.

   Important

   The Common Name field must match the hostname for your Swarm installation exactly.

4. Secure the certificate directory.

   $ sudo chmod 600 /etc/apache2/ssl

5. Edit the virtual host configuration.

   Note

   The virtual host configuration should be in the file you backed up initially.

   Edit the virtual host configuration to match:

   <VirtualHost *:80>
   	ServerName myswarm
   	AllowEncodedSlashes NoDecode
   	ServerAlias myswarm.host
   	ErrorLog "/path/to/apache/logs/myswarm.error_log"
   	CustomLog "/path/to/apache/logs/myswarm.access_log" common
   	DocumentRoot "/path/to/swarm/public"
   	<Directory "/path/to/swarm/public">
   		AllowOverride All
   		Require all granted
   	</Directory>
   							
          Redirect / https://myswarm.host/
   </VirtualHost>
   
   <VirtualHost *:443>
   	SSLEngine on
   	SSLCertificateFile /etc/apache2/ssl/apache.crt
   	SSLCertificateKeyFile /etc/apache2/ssl/apache.key
   
   	ServerName myswarm.host
   	AllowEncodedSlashes NoDecode
   	ServerAlias myswarm
   	ErrorLog "/path/to/apache/logs/myswarm.error_log"
   	CustomLog "/path/to/apache/logs/myswarm.access_log" common
   	DocumentRoot "/path/to/swarm/public"
   	<Directory "/path/to/swarm/public">
   		AllowOverride All
   		Require all granted
   	</Directory>
   </VirtualHost>

   See Apache's virtual host documentation for details: https://httpd.apache.org/docs/2.4/vhosts/

6. Customize the virtual host definition.

   1. Replace myswarm.host with the hostname for Swarm on your network.

   2. Replace myswarm with the name of the subdomain hosting Swarm. Many administrators choose swarm.

      Note

      The string myswarm in the log file paths: this should match the subdomain name and prefix for the log files, to help coordinate the active host with the log files for that host. Doing this is particularly useful when your Apache server hosts multiple instances of Swarm.

   3. Replace /path/to/apache/logs with the path where your Apache store its log files. Apache's log files are typically named access_log and error_log.
   4. Replace /path/to/swarm with the path to the Swarm directory.

7. Restart your web server.

   $ sudo apachectl restart

8. Adjust your firewall configuration to allow connections to the standard SSL port for web servers.

   • For CentOS/RHEL:

     $ sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
     $ sudo systemctl reload firewalld 

   • For other distributions, consult with your network administrator or operating system documentation to determine how to adjust your firewall configuration.

9. Test your HTTPS URL from a web browser.

   Important

   If the myswarm.host value in the virtual host configuration and the certificate do not match, the P4V integration with Swarm fails with the message SSL handshake failed.

   Also, when a reverse DNS lookup is performed, myswarm.host should be the answer when querying for the Swarm server's IP address.

10. Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.

Run Swarm in a sub-folder of an existing web site

If you cannot run Swarm in its own virtual host, which might be necessary when you do not control the hostname to be used with Swarm, installing Swarm in a sub-folder of an existing virtual host configuration can be a good solution.

Installing Swarm in a sub-folder requires modification of the previous installation steps covered in this chapter:

• The Apache configuration is entirely different; instead of establishing a new virtual host, you need to modify an existing virtual host configuration. Often, this would be Apache's default site.
• Swarm's configuration file requires an extra item.

The following sections cover the specifics of sub-folder installation.

See base_url for more details.

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -B /swarm

Apache configuration

1. Ensure that the SWARM_ROOT is not within the document root of the intended virtual host.

   This step ensures that Swarm's source code and configuration is impossible to browse, preventing access to important details such as stored credentials, and active sessions and workspaces.

2. Adjust the virtual host configuration that you are already using.

   Note

   Depending on the method used to install Swarm, the filename for virtual host configuration you need to edit is:

   • For Swarm package installations, edit perforce-swarm-site.conf.
   • For manual installations following Swarm's recommended Apache configuration edit swarm.
   • For other installations, you may have to edit httpd.conf or nearby files.

   Add the following lines to the virtual host definition:

   Alias "/swarm" "SWARM_ROOT/public"
   
   DocumentRoot "/var/www/html"
   							
   <Directory "SWARM_ROOT/public">
     AllowOverride All
     Require all granted
   </Directory>

   The Alias line configures Apache to respond to requests to https://myhost/swarm with content from Swarm's public folder. You can change the /swarm portion of the Alias line to anything you want.

   The DocumentRoot line configures the Apache DocumentRoot directory location.

   The <Directory> block grants access to everything within Swarm's public folder. Replace SWARM_ROOT with the actual path to Swarm.

3. Restart your web server.

   $ sudo apachectl restart

Swarm configuration

To successfully operate within a sub-folder, the swarm_root/data/config.php file needs to be adjusted to contain the following lines (as a peer of the p4 item):

	'environment' => array(

		'base_url' => '/swarm'

	),

Ensure that /swarm matches the first item in the Alias line in the virtual host configuration.

See Environment for more details.

Swarm trigger configuration

The swarm-trigger.conf file must be updated to include the base_url in the SWARM_HOST path.

1. Edit the swarm-trigger.conf file.
2. Replace:

SWARM_HOST="http://my-swarm-host"

With:

SWARM_HOST="http://website-hostname/swarm"

3. Save the file.

Cron configuration

Swarm's recurring task configuration must be updated to reflect the sub-folder that you have configured in Apache's and Swarm's configurations. This is configured in the swarm-cron-hosts.conf file.

1. Edit /opt/perforce/etc/swarm-cron-hosts.conf.

2. Replace:

   https://swarm-host

   with:

   https://swarm-host/swarm/

   Where swarm-host is the hostname of your Swarm installation, and swarm is the sub-folder you want to use.

3. Save the edited file.

   New workers should be started at the start of the next minute.

4. Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.

Run the Swarm virtual host on a custom port

If you cannot run Swarm on port 80 (or port 443 for HTTPS), perhaps because you do not have root access, it is possible to run Swarm on a custom port.

Installing Swarm to use a custom port requires modification of the previous installation steps covered in this chapter: The Apache configuration is slightly different, requiring modification of Swarm's virtual host definition.

The following section covers the specifics of the custom port configuration.

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -n -p myp4host:1666 -u swarm -w password -e mx.example.com -H myhost -P 8080

Apache configuration

1. Edit the virtual host configuration.

   Note

   Depending on the method used to install Swarm, the filename for virtual host configuration you need to edit is:

   • For Swarm package installations, edit perforce-swarm-site.conf.
   • For manual installations following Swarm's recommended Apache configuration, edit swarm.
   • For other installations, you may have to edit httpd.conf or nearby files.

   1. Add the following line outside of the <VirtualHost> block:

      Listen 8080

   2. Edit the <VirtualHost *:80> line to read:

      <VirtualHost *:8080>

   For both lines, replace 8080 with the custom port you wish to use.

   Important

   If you choose a port that is already in use, Apache refuses to start.

2. Restart your web server.

   $ sudo apachectl restart

3. Adjust your firewall configuration to allow connections to the custom port.

   • For CentOS/RHEL:

     $ sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
     
     $ sudo systemctl reload firewalld

     Replace 8080 with the custom port you wish to use.

   • For other distributions, consult with your network administrator or operating system documentation to determine how to just your firewall configuration.

Cron configuration

Swarm's recurring task configuration must be updated to reflect the custom port that you have configured in Apache's configuration. This is configured in the swarm-cron-hosts.conf file.

1. Edit /opt/perforce/etc/swarm-cron-hosts.conf.

2. Replace:

   https://swarm-host:80

   with:

   https://swarm-host:8080

   Where swarm-host is the hostname of your Swarm installation, and 8080 is the custom port you want to use.

3. Save the edited file.

   New workers should be started at the start of the next minute.

4. Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.

Use your own Redis server

By default Swarm uses its own Redis server on the Swarm machine.

This section describes how to connect Swarm to your own Redis server.

To use your own Redis server:

1. Add the redis block to the SWARM_ROOT/data/config.php file, it contains the password, namespace, host, and port details of your Redis server

<?php
    // this block should be a peer of 'p4'
    'redis' => array(
        'options' => array( 
            'password' => null, // Defaults to null
            'namespace' => 'Swarm',  
            'server' => array(
                'host' => 'MyRedisServerHostname', // Defaults to 'localhost' or enter your Redis server hostname
                'port' => 'MyRedisServerPortNumber', // Defaults to '7379 or enter your Redis server port
            ), 
        ),
        'items_batch_size' => 100000,
        'check_integrity' => '03:00', // Defaults to '03:00' Use one of the following two formats: 
                                      // 1) The time of day that the integrity check starts each day. Set in 24 hour format with leading zeros and a : separator
                                      // 2) The number of seconds between each integrity check. Set as a positive integer. Specify '0' to disable the integrity check.
        'population_lock_timeout' => 300, // Timeout for initial cache population. Defaults to 300 seconds. 
    ),

• password: set to the password of your Redis server, defaults to null
• namespace: the prefix used for key values in the Redis cache. Defaults to Swarm.
Note

If you have multiple-Swarm instances running against a single Redis server, each Swarm server must use a different Redis namespace. This enables the cache data for the individual Swarm instances to be identified. The namespace is limited to ≤ 128 characters.

If one or more of your Swarm instances is connected to multiple-Helix Core Servers, the Redis namespace includes the server label and the character limit is reduced to ≤ 127 characters, see Multiple-Helix Core Server instances.

• host MyRedisServerHostname: Redis server host name
• port MyRedisServerPortNumber: Redis server port number
• items_batch_size: Maximum number of key/value pairs allowed in an mset call to Redis. Sets exceeding this will be batched according to this maximum for efficiency. Defaults to 100000.
Note

The default value of 100000 was chosen to strike a balance between efficiency and project data complexity. This value should not normally need to be changed, contact support before making a change to this value.

• check_integrity: In some circumstances, such as when changes are made in the Helix Core Server when Swarm is down or if errors occur during updates, the Redis cache can get out of sync with the Helix Core Server. Swarm can run a regular integrity check to make sure that the Redis caches and Helix Core Server are in sync. If an integrity check finds an out of sync cache file, Swarm automatically updates the data in that cache.

The check_integrity configurable specifies when the Redis cache integrity check is run. Set as a specific time of day (24 hour format with leading zeros) or a number of seconds (positive integer) between checks. Disable the integrity check with '0'. Defaults to '03:00'.

• population_lock_timeout: specifies the timeout, in seconds, for initial cache population. If you have a large Swarm system, increase this time if the initial cache population times out. Defaults to 300 seconds.
2. Edit the Redis server configuration in the /opt/perforce/etc/redis-server.conf file:

bind MyRedisServerHostname
port MyRedisServerPortNumber
supervised auto
save ""
dir /MyRedis/CacheDatabase/Directory/Location

• bind MyRedisServerHostname - Redis server host name
• port MyRedisServerPortNumber - Redis server port number
• supervised auto - detects the use of upstart or systemd automatically to signal that the process is ready to use the supervisors
• save "" - background saves disabled, recommended.
• dir /MyRedis/CacheDatabase/Directory/Location - the directory the Redis cache database is stored in
Tip
• The redis-server.conf file contains more detailed information about the Redis configuration for Swarm.
• On Swarm systems with a large number of users, groups, and projects, start-up time can be improved by persisting the memory cache. You can persist the memory cache by disabling background saves and enabling append saves, see the redis-server.conf file comments for detailed information.

Swarm is now connected to your Redis server and your Swarm installation is complete.

3. Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.

Hiding Swarm storage from regular users

Swarm information storage uses Helix Core Server's keys facility. By default, users with list-level access can search keys and potentially obtain information they would not otherwise have access to, and users with review-level access can write or modify keys potentially corrupting or destroying data.

We recommend that you set the dm.keys.hide configurable to 2 to require admin-level access for searching and modifying keys. Note that dm.keys.hide is available in Helix Core Server versions 2013.1 and newer.

When dm.keys.hide is set to 2, both the p4 keys and p4 key commands require admin-level access in the Helix Core Server. When dm.keys.hide is set to 1, only the p4 keys command requires admin-level access in the Helix Core Server. When dm.keys.hide is set to 1, or is not set, users who know (or can deduce) key names can read values (if they have list-level access) or write values (if they have review-level access) with the p4 key command.

To set dm.keys.hide:

p4 configure set dm.keys.hide=2

To confirm the current value of dm.keys.hide:

p4 configure show dm.keys.hide

To unset dm.keys.hide:

p4 configure unset dm.keys.hide

Next step

Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.

Handling Exclusive Locks

Swarm takes copies of files when it is creating reviews. Some of the files managed by Helix Core Server may be limited to 'exclusive open' by having the filetype modifier '+l' set. This file-level setting ensures only one user at a time can open the file for editing.

To allow Swarm to work with these 'exclusive open' files, you must enable filetype.bypasslock in the Helix Core Server configuration.

To set filetype.bypasslock:

p4 configure set filetype.bypasslock=1

To confirm the current value of filetype.bypasslock:

p4 configure show filetype.bypasslock

To unset filetype.bypasslock:

p4 configure unset filetype.bypasslock

Next step

Validate that Swarm is working correctly before using it in production, see Validate your Swarm installation.