## Perforce configuration for Swarm

Now that you have a configured instance of Swarm, the last piece is to configure your Helix Versioning Engine to tell Swarm about interesting events. This is accomplished through the use of triggers.

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

### Using triggers to push events to Swarm

The Helix Versioning Engine provides a facility called triggers to customize the operation of the server, or to invoke additional processing for specific kinds of versioning operations. Swarm provides a trigger script written in Perl that notifies Swarm about activity within the Helix Versioning Engine.

#### Setup Swarm triggers with a Windows-hosted Helix Versioning Engine

1. Ensure that the required trigger dependencies have been installed on the machine hosting the Helix Versioning Engine.

2. Install the Swarm trigger script on the Perforce server.

If the Swarm trigger script has not already been installed on your Perforce server machine, you need to copy p4-bin/scripts/swarm-trigger.pl from your Swarm install to the Perforce server machine so that it can be executed by the Perforce server.

### Note

If you are using the Swarm OVA, the full path to the trigger script within the OVA's filesystem is: /opt/perforce/swarm/p4-bin/scripts/swarm-trigger.pl

3. Configure the Swarm trigger script.

You need to use the API token established in the Establish trigger token section.

swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf, as using the configuration file greatly simplifies upgrades. swarm-trigger.conf should be created in the same directory as swarm-trigger.pl.

If your Helix Versioning Engine is configure using a commit-edge configuration, copy swarm-trigger.pl and swarm-trigger.conf to the commit server and all edge servers, making sure that they exist in the same path on all servers.

The following is a sample of what your swarm-trigger.conf should contain:

# SWARM_HOST (required)
SWARM_HOST="http://my-swarm-host"

# SWARM_TOKEN (required)
# The token used when talking to Swarm to offer some security. To obtain the
# value, log in to Swarm as a super user and select 'About Swarm' to see the
# token value.
SWARM_TOKEN="MY-UUID-STYLE-TOKEN"

# For enforcing reviewed changes, optionally specify the normal Perforce user
# with admin privileges (to read keys); if not set, will use whatever Perforce
# user is set in environment.

# For enforcing reviewed changes, optionally specify the location of the
# p4tickets file if different from the default ($HOME/.p4tickets). # Ensure this user is a member of a group with an 'unlimited' or very long # timeout; then, manually login as this user from the Perforce server machine to # set the ticket. ADMIN_TICKET_FILE=  Modify the swarm-trigger.conf configuration file to set the SWARM_HOST and the SWARM_TOKEN variables appropriately. ### Note You may need to edit the trigger script to specify the full path to curl.exe. ### Important If you specify ADMIN_USER, the ticket contained in %USERPROFILE%/p4tickets.txt (or the ticket file specified with ADMIN_TICKET_FILE) must use the port that was used to start the Helix Versioning Engine. For example, if p4d is started with: C:\> p4d -p my-helix-versioning-engine:1666 ...  then the ticket for the admin user specified with ADMIN_USER should be established with: C:\> p4 -p my-helix-versioning-engine:1666 -u admin_userid login  If the ticket was established using the wrong port, the error message you encounter includes the port that the trigger is attempting to use: 'swarm.strict.1' validation failed: Invalid login credentials to [port] within this trigger script; please contact your administrator.  4. Verify that the trigger script executes correctly. Run: C:\> perl "C:\path\to\swarm-trigger.pl" -t ping -v 0  Use the full path to perl if it is not available in your command path. You should expect to see no output. If the trigger is misconfigured, such as using an invalid trigger token, you would see an error. ### Warning Installation of the triggers may cause a security warning dialog to appear when curl.exe executes: If this occurs, the triggers hang, creating zombie perl processes. Due to the way triggers are invoked by the Helix Versioning Engine, the dialog is normally not visible even though Windows is waiting on interaction. To resolve this: 1. Uncheck and click . 2. context-click curl.exe, choose Properties, and click . 5. Update the Perforce triggers table to run the trigger script. As a Perforce user with super privileges, edit the Perforce trigger table by running the p4 triggers command and add the following lines (including the initial tab character):  swarm.job form-commit job "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t job -v %formname%" swarm.user form-commit user "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t user -v %formname%" swarm.userdel form-delete user "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t userdel -v %formname%" swarm.group form-commit group "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t group -v %formname%" swarm.groupdel form-delete group "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t groupdel -v %formname%" swarm.changesave form-save change "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t changesave -v %formname%" swarm.shelve shelve-commit //... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t shelve -v %change%" swarm.commit change-commit //... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %C:\path\to\swarm-trigger.conf% -t commit -v %change%" # swarm.enforce.1 change-submit //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t enforce -v %change% -p %serverport%" # swarm.enforce.2 change-submit //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t enforce -v %change% -p %serverport%" # swarm.strict.1 change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t strict -v %change% -p %serverport%" # swarm.strict.2 change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t strict -v %change% -p %serverport%"  Update the perl.exe, trigger script, and configuration file paths in each line above to reflect the actual paths on your Perforce server. ### Important If your Helix Versioning Engine has SSL enabled and is older than the 2014.1 release, the %serverport% trigger variable does not include the necessary transport indicator, which can cause the enforce and strict triggers to fail. To solve this problem, add ssl: immediately before %serverport% in the trigger lines. For example: # swarm.enforce.1 change-submit //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t enforce -v %change% -p ssl:%serverport%" # swarm.enforce.2 change-submit //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t enforce -v %change% -p ssl:%serverport%" # swarm.strict.1 change-content //DEPOT_PATH1/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t strict -v %change% -p %ssl:serverport%" # swarm.strict.2 change-content //DEPOT_PATH2/... "%quote%C:\path\to\perl.exe%quote% %quote%C:\path\to\swarm-trigger.pl%quote% -c %/path/to/swarm-trigger.conf% -t strict -v %change% -p %ssl:serverport%"  ### Warning The use of %quote% is not supported on 2010.2 servers (it is harmless though); if you are using this version, ensure that you do not have any spaces in the path to perl.exe or the script's path. ### Note The last four trigger lines are commented out as they are optional, and require that the DEPOT_PATH1 and DEPOT_PATH2 values are configured appropriately. • The first two lines configure the enforce feature, which rejects any submitted changes that are not tied to an approved review. • The second two lines configure the strict feature, which rejects any submitted changes when the contents of the changelist do not match the contents of its associated approved review. If you need to apply enforce or strict to more depot paths, copy the lines and tweak their depot paths as necessary. ### Tip The trigger script can provide the list of trigger lines that should work, with little to no adjustment, by executing it with the -o option: C:\> perl "C:\path\to\swarm-trigger.pl" -o  6. Configure the Helix Versioning Engine to promote all shelved changes. C:\> p4 configure set dm.shelve.promote=1  When this configurable is set, Swarm has access to all shelved changelists, which is a requirement for pre-commit reviews. When it is not set, users connected to an edge server must remember to use the -p option when shelving files to promote their shelves to the commit server when initiating a pre-commit review. 7. Optionally forward logins to the commit server. If you intend to use P4V and its Swarm integration, you should consider forwarding logins to the commit server. See P4V Authentication for details. #### Setup Swarm triggers with a Linux-hosted Helix Versioning Engine 1. Ensure that the required trigger dependencies have been installed on the machine hosting the Helix Versioning Engine. 2. Copy the perl trigger to the Helix Versioning Engine. If your Helix Versioning Engine is version 2014.1 (or newer), we recommend submitting the trigger file, p4-bin/scripts/swarm-trigger.pl, to Perforce and running it from the depot. The recommended depot location would be //.swarm/triggers/swarm-trigger.pl, especially if you have already setup Comment attachments. If your Helix Versioning Engine is older than version 2014.1, or prefer that the trigger exist in the filesystem, you must copy the p4-bin/scripts/swarm-trigger.pl script to the server hosting the Helix Versioning Engine. If your Helix Versioning Engine deployment uses the commit-edge architecture, the script must also be copied to all edge servers, and it must exist in the same path on all servers. ### Note If you are using the Swarm OVA, the full path to the trigger script within the OVA's filesystem is: /opt/perforce/swarm/p4-bin/scripts/swarm-trigger.pl 3. Configure the Perl trigger. You need to use the API token established in the Establish trigger token section. swarm-trigger.pl can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf, as using the configuration file greatly simplifies upgrades. If you are using the Swarm triggers package described in Swarm packages, the file is available at /opt/perforce/etc/swarm-trigger.conf, otherwise create swarm-trigger.conf in the same directory as swarm-trigger.pl. If you submitted the trigger script to the depot in the previous step, you should similarly submit the configuration file to the depot. The recommended path is //.swarm/triggers/swarm-trigger.conf. If you copied the trigger script to the commit server and all edge servers in the previous step, also copy the configuration file to the commit server and all edge servers, making sure that it exists in the same path on all servers. The following is a sample of what your swarm-trigger.conf should contain: # SWARM_HOST (required) # Hostname of your Swarm instance, with leading "http://" or "https://". SWARM_HOST="https://my-swarm-host" # SWARM_TOKEN (required) # The token used when talking to Swarm to offer some security. To obtain the # value, log in to Swarm as a super user and select 'About Swarm' to see the # token value. SWARM_TOKEN="MY-UUID-STYLE-TOKEN" # ADMIN_USER (optional) # For enforcing reviewed changes, optionally specify the normal Perforce user # with admin privileges (to read keys); if not set, will use whatever Perforce # user is set in environment. ADMIN_USER= # ADMIN_TICKET_FILE (optional) # For enforcing reviewed changes, optionally specify the location of the # p4tickets file if different from the default ($HOME/.p4tickets).
# Ensure this user is a member of a group with an 'unlimited' or very long
# timeout; then, manually login as this user from the Perforce server machine to
# set the ticket.


Modify the swarm-trigger.conf configuration file to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.

### Note

swarm-trigger.pl looks for configuration in the following files. Variables defined in the later files will override the earlier defined variables of the same name:

• Variables set inside the swarm-trigger.pl script itself

• /etc/perforce/swarm-trigger.conf

• /opt/perforce/etc/swarm-trigger.conf

• The swarm-trigger.conf file stored in the same directory as swarm-trigger.pl

• Any file passed to the swarm-trigger.pl script using the -c command line argument.

### Important

If you specify ADMIN_USER, the ticket contained in $HOME/.p4tickets (or the ticket file specified with ADMIN_TICKET_FILE) must use the port that was used to start the Helix Versioning Engine. For example, if p4d is started with: $ p4d -p my-helix-versioning-engine:1666 ...


then the ticket for the admin user specified with ADMIN_USER should be established with:

$p4 -p my-helix-versioning-engine:1666 -u admin_userid login  If the ticket was established using the wrong port, the error message you encounter includes the port that the trigger is attempting to use: 'swarm.strict.1' validation failed: Invalid login credentials to [port] within this trigger script; please contact your administrator.  4. Ensure that the script has execute permissions. ### Important Skip this step if you have committed the script to the Helix Versioning Engine. $ chmod +x /path/to/swarm-trigger.pl

5. Verify that the trigger script executes correctly.

### Important

Skip this step if you have committed the script to the Helix Versioning Engine.

$/path/to/swarm-trigger.pl -t ping -v 0  You should expect to see no output. If the trigger is misconfigured, such as using an invalid trigger token, you would see an error. ### Note Run the trigger script without any arguments to see additional usage information. 6. Update the Perforce triggers table to run the Perl trigger. As a Perforce user with super privileges, edit the Perforce triggers table by running the p4 triggers command and add the appropriate set of lines (including the initial tab character): 1. If you have committed both the trigger script and the configuration file to the Helix Versioning Engine:  swarm.job form-commit job "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t job -v %formname%" swarm.user form-commit user "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t user -v %formname%" swarm.userdel form-delete user "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t userdel -v %formname%" swarm.group form-commit group "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t group -v %formname%" swarm.groupdel form-delete group "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t groupdel -v %formname%" swarm.changesave form-save change "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t changesave -v %formname%" swarm.shelve shelve-commit //... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t shelve -v %change%" swarm.commit change-commit //... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t commit -v %change%" # swarm.enforce.1 change-submit //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%" # swarm.enforce.2 change-submit //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%" # swarm.strict.1 change-content //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%" # swarm.strict.2 change-content //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"  2. If you have copied the trigger script and configuration file to common paths on all servers:  swarm.job form-commit job "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t job -v %formname%" swarm.user form-commit user "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t user -v %formname%" swarm.userdel form-delete user "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t userdel -v %formname%" swarm.group form-commit group "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t group -v %formname%" swarm.groupdel form-delete group "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t groupdel -v %formname%" swarm.changesave form-save change "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t changesave -v %formname%" swarm.shelve shelve-commit //... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t shelve -v %change%" swarm.commit change-commit //... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t commit -v %change%" # swarm.enforce.1 change-submit //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%" # swarm.enforce.2 change-submit //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%" # swarm.strict.1 change-content //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%" # swarm.strict.2 change-content //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.pl%quote% -c %quote%/path/to/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"  Update the trigger script and configuration file paths in each line above to reflect the actual paths on your Perforce server. ### Important If your Helix Versioning Engine has SSL enabled and is older than the 2014.1 release, the %serverport% trigger variable does not include the necessary transport indicator, which can cause the enforce and strict triggers to fail. To solve this problem, add ssl: immediately before %serverport% in the trigger lines. For example: # swarm.enforce.1 change-submit //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.pl%quote% -c %//.swarm/trigggers/swarm-trigger.conf% -t enforce -v %change% -p ssl:%serverport%" # swarm.enforce.2 change-submit //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.pl%quote% -c %//.swarm/trigggers/swarm-trigger.conf% -t enforce -v %change% -p ssl:%serverport%" # swarm.strict.1 change-content //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.pl%quote% -c %//.swarm/trigggers/swarm-trigger.conf% -t strict -v %change% -p ssl:%serverport%" # swarm.strict.2 change-content //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.pl%quote% -c %//.swarm/trigggers/swarm-trigger.conf% -t strict -v %change% -p ssl:%serverport%"  ### Note The last four trigger lines in either block are commented out as they are optional, and require that the DEPOT_PATH1 and DEPOT_PATH2 values are configured appropriately. • The first two lines configure the enforce feature, which rejects any submitted changes that are not tied to an approved review. • The second two lines configure the strict feature, which rejects any submitted changes when the contents of the changelist do not match the contents of its associated approved review. If you need to apply enforce or strict to more depot paths, copy the lines and tweak their depot paths as necessary. ### Tip The trigger script can provide the list of trigger lines that should work, with little to no adjustment, by executing it with the -o option: $ /path/to/swarm-trigger.pl -o

7. Configure the Helix Versioning Engine to promote all shelved changes.

$p4 configure set dm.shelve.promote=1  When this configurable is set, Swarm has access to all shelved changelists, which is a requirement for pre-commit reviews. When it is not set, users connected to an edge server must remember to use the -p option when shelving files to promote their shelves to the commit server when initiating a pre-commit review. 8. Optionally forward logins to the commit server. If you intend to use P4V and its Swarm integration, you should consider forwarding logins to the commit server. See P4V Authentication for details. ### Hiding Swarm storage from regular users Swarm information storage uses the Helix Versioning Engine'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 Perforce 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 Versioning Engine. When dm.keys.hide is set to 1, only the p4 keys command requires admin-level access in the Helix Versioning Engine. 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