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 server to improve the performance of common searches in Swarm and to reduce the load on the Helix server.

Redis configuration:

• Swarm connection to Redis : SWARM_ROOT/data/config.php.
• Redis server configuration file: /opt/perforce/etc/redis-server.conf.

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 servers, the Redis namespace includes the server label and the character limit is reduced to ≤ 127 characters, see Multiple-Helix 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 server when Swarm is down or if errors occur during updates, the Redis cache can get out of sync with the Helix server. Swarm can run a regular integrity check to make sure that the Redis caches and Helix 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

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:

• 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

If users and groups are created, edited, or deleted in the Helix server while the Swarm server is shutdown, the user and group Redis caches will be out of sync with the Helix server. The workflow and project caches should remain in sync with the Helix server because Swarm does not support editing them outside of Swarm.

After the Swarm server has restarted, run a curl request to verify that the Redis caches are in sync with the Helix server. If a verification finds an out of sync cache file, Swarm automatically updates the data in that cache.

To start verification of the user and group caches:

curl -u "username:password" -X POST "https://myswarm.url/api/v9/cache/redis/verify?context=user,group"

JSON response

HTTP/1.1 200 OK

{
    isValid: true,
    data: {
        user: {
            state: "Queued",
            progress: false
        },
        group: {
            state: "Queued",
            progress: false
        }
    },
    messages: {
        "Verifying Redis cache for [user,group]"
    }
}

Check progress of the verification request

To check verification progress for the user and group caches:

curl -u "username:password" "http://myswarm.url/api/v9/cache/redis/verify?context=user,group"

JSON response

HTTP/1.1 200 OK

{
    isValid: true,
    data: {
        user: {
            state: "Running",
            progress: "Step 2 of 5; Calculating checksums for Redis keys"
        },
        group: {
            state: "Running",
            progress: "Step 1 of 5; Getting Redis cache entries"
        }
    }
}