Redis server

Swarm requires Redis to manage its caches and by default Swarm uses its own Redis server on the Swarm machine. Swarm caches data from the Helix Core Server to improve the performance of common searches in Swarm and to reduce the load on the Helix Core Server.

Redis configuration:

Tip
  • If required, you can use your own Redis server instead of the Swarm Redis server. For instructions on how to configure Swarm to use your Redis server, see Use your own Redis server.
  • If users and groups are added, edited, or deleted in the Helix Core Server while the Swarm server is shutdown, the Swarm user and group Redis caches will be out of sync. After the Swarm server has restarted, run a curl request to verify that the Redis caches are in sync with the Helix Core Server. For the Redis cache verification steps, see Manually verify the Redis caches.

  • When Swarm starts it verifies the Redis cache, during this time you cannot log in to Swarm. The time taken to verify the Redis cache depends on the number of users, groups, and projects Swarm has. 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 in the redis-server.conf file, see Redis server configuration file.

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.

Swarm connection to Redis

The redis block of the SWARM_ROOT/data/config.php file contains the password, namespace, host and port details of the Swarm 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' => 'localhost', // Defaults to 'localhost' or enter your Redis server hostname
                'port' => '7379', // 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. 
    ),

Configurables:

  • password: Redis server password. Defaults to null and should be left at default if using the Swarm Redis server.
  • namespace: the prefix used for key values in the Redis cache. Defaults to Swarm and should be left at default if using the Swarm Redis server.
    • 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: Redis server hostname. Defaults to localhost and should be left at default if using the Swarm Redis server.
  • port: Redis server port number. Defaults to 7379. Swarm uses port 7379 as its default to avoid clashing with other Redis servers that might be on your network. It should be left at default if using the Swarm Redis server. The default port for a non-Swarm Redis server is 6379.
  • 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.

Redis server configuration file

Tip

To fine-tune your Redis server settings, make your changes in the Laminas Redis adapter. For information about the Laminas Redis adapter, see the Laminas Redis Adapter documentation.

The Redis server configuration for Swarm is defined in /opt/perforce/etc/redis-server.conf and defaults to:

bind 127.0.0.1
port 7379
supervised auto
save ""
dir /opt/perforce/swarm/redis

Default values:

Tip
  • The default settings are shown below, 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.
  • bind 127.0.0.1 - Redis server IP address (loopback interface)
  • port 7379 - 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 /opt/perforce/swarm/redis - the directory the Redis cache database is stored in.

Manually verify the Redis caches

Important
  • Only admin and super users can verify the Redis cache.

  • On Swarm systems with a large number of users, groups, and projects verification of the caches can take some time and can impact performance.

    In normal operation, the Redis cache and Helix Core Server data should stay in sync and there is no need to verify the caches.

    If you have a large number of users, groups, and projects, we recommend that you verify the individual user and group caches rather than using Verify All.

In normal operation the Redis cache and Helix Core Server data should stay in sync and there is no need to verify the caches. However, 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.

If you suspect that you have a cache issue, you can verify the cache manually from the System Information page.

For example, to verify the User cache:

  1. Navigate to the User id dropdown menu.
  2. Select System Information.
  3. Click the Cache Info tab.
  4. Click the Verify User button.

    5. Swarm responds with a message to say that it has successfully verified the user cache.

    If verification finds the cache is out of sync with the Helix Core Server, Swarm automatically updates the data in that cache.

    For more information, see Verify buttons.

Check progress of the verification request

To check the progress of the verification request:

  1. From the Cache Info tab.
  2. Click the Refresh Status button.