Swarm configuration // Swarm 2017.2 Guide

Swarm configuration

Now that Swarm is ready for use, you need to configure it to work in your environment.

Note

A Helix Versioning Engine can refer to a Helix server (p4d), proxy, broker, replica, edge server, or commit server. It does not refer to a service user; service users are used to coordinate replication in a Helix Versioning Engine. For simplicity, the term Helix server is used to refer to any configuration of a Helix Versioning Engine.

Swarm configuration file

Create a file named config.php under the data directory with the following contents:

<?php
    return array(
        'p4' => array(
            'port'      => 'my-helix-versioning-engine:1666',
            'user'      => 'admin_userid',
            'password'  => 'admin user ticket or password',
        ),
        'log' => array(
            'priority'  => 3, // 7 for max, defaults to 3
        ),
        'mail' => array(
            'transport' => array(
                'host' => 'my.mx.host',
            ),
        ),
    );

For the port value, replace my-helix-versioning-engine:1666 with the P4PORT value used to connect to your Helix Versioning Engine.

Important

If your Helix Versioning Engine is deployed using the commit-edge architecture, ensure that Swarm's port value points to the commit server.

For more information, see "Commit-edge Architecture" in the Perforce Server Administrator's Guide: Multi-site Deployment.

Warning

If the port points to a Helix Broker, ensure that the broker does not delegate commands to different replicas, edge servers, or proxies. Such delegation can cause odd problems or outright failures in Swarm.

Swarm needs to have a consistent, current view of the state of the Helix Versioning Engine, and works best when it connects to a central/commit server.
For the user value, replace admin_userid with a normal Perforce userid that has admin-level access to the Helix Versioning Engine.
For the password value, while a plain-text password works, we recommend that you use a ticket value instead. Obtain the ticket value for the admin_userid during login with this command:
```
$ p4 -p my-helix-versioning-engine:1666 -u admin_userid login -p
```
Note

For a Helix Versioning Engine with the security configurable set to level 3, or when authentication is configured to use LDAP, ticket-based authentication is required.

Important

When using ticket-based authentication, ensure that the ticket has a very long expiration. We recommend creating a group with an unlimited timeout, and adding admin_userid user to this group.

An expired ticket causes many Swarm operations to fail.

You can determine when the admin userid's ticket will expire with:
```
$ p4 -p my-helix-versioning-engine:1666 -u admin_userid -P ticket_value login -s
```
Tip

For more information about tickets, see the section Ticket-based authentication in the Helix Versioning Engine Administrator Guide: Fundamentals.
For the host value, replace my.mx.host with the hostname of the mail exchanger service that Swarm should use to send its email notifications.

Note

Since this configuration file contains the credentials for a Perforce admin-level user, we recommend that this file's ownership and permissions be adjusted such that only the web server user can read the file, and that no user can write the file.

Optional additional Swarm configuration

Swarm provides optional functionality that could be enabled at this time:

Swarm hostname

Swarm normally auto-detects the hostname it operates under. In some system configuration, the auto-detection logic might not choose the correct hostname, such as when there are multiple virtual hosts configured for a single Swarm instance. When auto-detection chooses the wrong hostname, email notifications, worker startup, and more could be affected.

If you need to specify the Swarm hostname, see hostname for details.

Swarm 2017.2 Guide (August 2017)