Documentation | 2025.1

# 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

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

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

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: 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 []:admin@myswarm.host

   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.

   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.

   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: Apache Virtual Host documentation

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.

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

   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.

### Secure your Swarm installation

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.

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

Multiple Helix Core Server instances on a single Swarm instance: You cannot run Swarm in a sub-folder if Swarm is connected to multiple Helix Core Servers.

Issue: Swarm will lose connection to all of the Helix Core Servers if you edit the base_url configurable value in the environment block of <swarm_root>/data/config.php. This will stop your system working.

Fix: Remove the base_url configurable from the environment block of <swarm_root>/data/config.php.

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

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.

If you used the Swarm packages to install Swarm, you can adjust Swarm's configuration using the package configuration script `/opt/perforce/swarm/sbin/configure-swarm.sh`.

`configure-swarm.sh` does not read any existing Swarm configuration; you must provide all of the configuration details each time you execute `configure-swarm.sh`:

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

In the example above, the `-B` option is used to specify the name of the sub-folder.

If you use `configure-swarm.sh` to adjust the Swarm configuration, you only need to follow the Apache configuration steps described below; all of the changes listed in the Swarm configuration section below have been completed by `configure-swarm.sh`.

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

   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.

The location of the swarm-trigger.conf depends on your installation. For information on the location of the swarm-trigger.conf file, see Set up Swarm triggers with a Windows or Linux-hosted Helix Core Server.

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

Back up your Swarm virtual host configuration before customizing your Swarm installation, see Back up your Swarm virtual host first.

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.

In addition to the following instructions, you may also need to apply the `external_url` item described in the Environment section if your Swarm is behind a proxy, or you have multiple Swarm instances connected to Helix Core Server.

If you used the Swarm packages to install Swarm, you can adjust Swarm's configuration using the package configuration script `/opt/perforce/swarm/sbin/configure-swarm.sh`.

`configure-swarm.sh` does not read any existing Swarm configuration; you must provide all of the configuration details each time you execute `configure-swarm.sh`:

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

In the example above, the `-P` option is used to specify the custom port that Swarm should use.

If you use `configure-swarm.sh` to adjust Swarm's configuration, follow the additional steps that it describes. Once those steps are complete, do not perform any of the steps described below.

### Apache configuration

1. Edit the virtual host configuration.

   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.

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

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.

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

- 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

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.

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.

Your search for returned results