Swarm 2014.3: User Guide

By default, Swarm permits any users to view most Perforce resources available in the associated Perforce service, restricted only by the protections configuration in the Perforce service.

Swarm can be configured to require all users to be logged in. Add the following configuration block to the data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'require_login' => true, // defaults to false
    ),

Once enabled, non-authenticated users see a login page for most Swarm requests.

By default, there are two exceptions:

Authenticated users attempting to visit the login page are redirected to Swarm's home page.

When your Perforce service has users that should not be able to log in to Swarm, for example service users involved with Perforce replicas, the prevent_login configuration item can be used to prevent successful authentication.

Add or update the following configuration block to the data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'prevent_login' => array(
            'service_user1',
            'service_user2',
        ),
    ),

prevent_login defaults to array(), which means no users in your Perforce service are prevented from logging into Swarm. However, license restrictions might also prevent logins.

Swarm manages logged-in sessions using cookies in the browser, and PHP session storage on the server. Swarm uses reasonable defaults for the cookie and session lifetimes (measured in seconds); when the lifetime is exceeded users need to login again. To specify session lifetimes, add the following configuration block to the data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'session' => array(
        'cookie_lifetime'             => 0, // 0=expire when browser closed
        'gc_maxlifetime'              => 60*60*24*30, // 30 days
        'remembered_cookie_lifetime'  => 60*60*24*30, // 30 days
    ),

Swarm provides the ability to commit reviews within the Swarm interface. You may want to disable this capability to prevent reviews from being committed by someone other than the review's author. When disabled, the Approve and Commit (and Commit if the review is already committed) option is removed from the list of states available to a code review.

To disable commits, set disable_commit to true within the reviews item in the data/config.php file. For example:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'disable_commit' => true,
        ),
    ),

The Perforce service provides two changelist types: public (the default), and restricted. Swarm honours restricted changelists by preventing access to the changelist, and any associated comments or activity related to the changelist.

If a user has list-level privileges to at least one file in the changelist, Swarm allows the user to see the changelist and any of the files they have permission to see.

To prevent unintended disclosures, email notifications for restricted changes are disabled by default. To enable email notifications for restricted changes, set email_restricted_changes to true within the security item in the data/config.php file. For example:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'email_restricted_changes' => true,
        ),
    ),

By default, any authenticated user can add new projects. Swarm can restrict project creation to users with admin-level or super-level privileges. Once restricted, Swarm prevents non-administrators from adding projects, and does not display the + icon to add a project to non-administrators.

Add or update the following configuration block to the data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'add_project_admin_only' => true,
    ),

A Perforce service can be configured via protections to restrict access to a depot in a variety of ways, including by IP address. As Swarm is a web application acting as a client to the Perforce service, often with admin-level privileges, Swarm needs to emulate IP address-based restrictions. It does so by checking the user's IP address and applying any necessary restrictions during operations such as browsing files, viewing file content, viewing and adding comments on files.

IP address-based protections emulation is enabled by default. Swarm performs somewhat faster without this emulation; if you do not require them for your Swarm installation these can be disabled by setting the configuration:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'emulate_ip_protections' => false,
    ),

Swarm provides a “System Information” page, available to users with admin or super privileges, which displays information about the Perforce service that Swarm is configured to use, as well as PHP information and the Swarm log file.

While this information can be invaluable when communicating with Perforce support engineers, you may wish to prevent disclosure of any system information. The System Information page can be disabled for all users by adding the following configuration block to the data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'disable_system_info' => true, // defaults to false
    ),

Once disabled, the System Information link disappears from the “About Swarm” dialog, and 403 errors are generated for any attempts to browse to the System Information page.

Swarm permits configuration of options that are passed through to the underlying Zend Framework 2's HTTP client. These options can be used to specify SSL certificate locations, request timeouts, and more, and can be specified globally or per host.

Here is an example configuration:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'timeout'       => 5,

        // path to the SSL certificate directory
        'sslcapath'     => '',

        // the path to a PEM-encoded SSL certificate
        'sslcert'       => '',

        // the passphrase for the SSL certificate file
        'sslpassphrase' => '',

        // optional, per-host overrides;
        // host as key, array of options as value
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslcapath'     => '/path/to/certs',
                'sslcert'       => 'jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
        ),
    ),

See the Zend Framework 2's Socket Adapter documentation for more information.

To improve the security when users work with Swarm, particularly if they need to do so outside of your network, Swarm provides a mechanism that tries to force web browsers to use HTTPS. When enabled, Swarm's behaviour changes in the following ways:

Here is an example of how to enable strict HTTPS:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'https_strict'          => true,
        'https_strict_redirect' => true, // optional; set false to avoid meta-refresh
        'https_port'            => null, // optional; specify if HTTPS is
                                         // configured on a non-standard port
    ),

When the https_strict_redirect item is set to false, Swarm does not add a meta-refresh for HTTP clients. This prevents an endless redirect when a load balancer in front of Swarm applies HTTPS to the client-to-load balancer connection, but not the load balancer-to-Swarm connection.

There are several Apache configuration changes that can improve security for Swarm:

There are several PHP configuration changes that can improve security for Swarm: