Perforce configuration for Swarm // Swarm 2014.3: User Guide

Perforce configuration for Swarm

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

Tip

For more information about Perforce triggers, see:

Perforce System Administrator's Guide: Scripting Perforce

Using Perforce triggers to push events to Swarm

Use the following Swarm trigger script to push Perforce events into Swarm. For a Perforce service installed on Linux:

p4-bin/scripts/swarm-trigger.sh

For a Perforce service installed on Windows, use the following Swarm trigger script:

p4-bin/scripts/swarm-trigger.vbs
If the Swarm trigger script has not already been installed on your Perforce server machine, you need to copy the script above from your Swarm install to the Perforce server machine so it can be called from a Perforce trigger.
Configure the Swarm trigger script:

You will need to use the API token established in the “Establish trigger token” section.
1. For Windows:
  
  Modify the swarm-trigger.vbs script to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.
  
  Note
  
  You may need to edit the path for the CURL_EXE variable within swarm-trigger.vbs to reflect the actual location of curl.exe.
2. For Linux:
  
  swarm-trigger.sh can be configured directly, but the preferred approach is to create a configuration file called swarm-trigger.conf.
  
  If you are using the Swarm triggers package described in “Swarm packages” the file is available at /opt/perforce/etc/swarm-trigger.conf, otherwise you can create swarm-trigger.conf in the same directory as swarm-trigger.sh.
  
  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="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"

# ADMIN_USER (optional)
# For enforcing reviewed changes, optionally specify the 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.
ADMIN_TICKET_FILE=
```
  Modify the swarm-trigger.conf configuration file to set the SWARM_HOST and the SWARM_TOKEN variables appropriately.
  Note
  
  swarm-trigger.sh 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.sh 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.sh
  
  Any file passed to the swarm-trigger.sh script using the -c command line argument.
Ensure that the script has execute permissions. For Linux installations:
```
$ chmod +x swarm-trigger.sh
```
Verify that the trigger script executes correctly.
1. For Linux systems, run:
```
/path/to/swarm-trigger.sh -t ping -v 0
```
  Note
  
  Run the trigger script without any arguments to see additional usage information.
2. For Windows systems, run:
```
C:\windows\system32\cscript.exe /nologo "C:\path\to\swarm-trigger.vbs" /type:ping /value: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.
  Warning
  
  For a Perforce service on Windows, installation of the triggers may cause a security warning dialog to appear when curl.exe executes:
  
  If this occurs, the triggers hang, creating zombie cscript processes. Due to the way triggers are invoked by the Perforce service, the dialog is normally not visible even though Windows is waiting on interaction.
  
  To resolve this:
  Uncheck Always ask before opening this file and click Run.
  
  context-click curl.exe, choose Properties, and click Unblock.

For a Linux-based Perforce service (see below for a Windows-based Perforce service):

As a Perforce user with super privileges, edit the Perforce trigger table by running the p4 triggers command and adding the following lines:

swarm.job      form-commit   job    "%quote%/path/to/swarm-trigger.sh%quote% -t job      -v %formname%"
swarm.user     form-commit   user   "%quote%/path/to/swarm-trigger.sh%quote% -t user     -v %formname%"
swarm.userdel  form-delete   user   "%quote%/path/to/swarm-trigger.sh%quote% -t userdel  -v %formname%"
swarm.group    form-commit   group  "%quote%/path/to/swarm-trigger.sh%quote% -t group    -v %formname%"
swarm.groupdel form-delete   group  "%quote%/path/to/swarm-trigger.sh%quote% -t groupdel -v %formname%"
swarm.change   form-commit   change "%quote%/path/to/swarm-trigger.sh%quote% -t change   -v %formname%"
swarm.shelve   shelve-commit //...  "%quote%/path/to/swarm-trigger.sh%quote% -t shelve   -v %change%"
swarm.commit   change-commit //...  "%quote%/path/to/swarm-trigger.sh%quote% -t commit   -v %change%"
#swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.sh%quote% -t enforce -v %change% -p %serverport%"
#swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.sh%quote% -t enforce -v %change% -p %serverport%"
#swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.sh%quote% -t strict -v %change% -p %serverport%"
#swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.sh%quote% -t strict -v %change% -p %serverport%"

Tip

When you run the trigger script with the -o flag, the script displays the trigger lines it requires, complete with all of the paths filled in.

/path/to/swarm-trigger.sh -o

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 path as necessary.

Important

If your Perforce service 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.sh%quote% -t enforce -v %change% -p ssl:%serverport%"
#swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.sh%quote% -t enforce -v %change% -p ssl:%serverport%"
#swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%/path/to/swarm-trigger.sh%quote% -t strict -v %change% -p ssl:%serverport%"
#swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%/path/to/swarm-trigger.sh%quote% -t strict -v %change% -p ssl:%serverport%"

For a Windows-based Perforce service (see above for a Linux-based Perforce service):

As a Perforce user with super privileges, edit the Perforce trigger table by running the p4 triggers command and adding the following lines:

swarm.job      form-commit   job    "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:job /value:%formname%"
swarm.user     form-commit   user   "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:user /value:%formname%"
swarm.userdel  form-delete   user   "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:userdel /value:%formname%"
swarm.group    form-commit   group  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:group /value:%formname%"
swarm.groupdel form-delete   group  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:groupdel /value:%formname%"
swarm.change   form-commit   change "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:change /value:%formname%"
swarm.shelve   shelve-commit //...  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:shelve /value:%change%"
swarm.commit   change-commit //...  "C:\windows\system32\cscript.exe /nologo %quote%C:\path\to\swarm-trigger.vbs%quote% /type:commit /value:%change%"

Important

Update the trigger script paths in each line above to reflect the actual script path on your Perforce server.

The enforce and strict features available for a Linux-based Perforce service are not currently available for a Windows-based Perforce service.

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 script's path.

Hiding Swarm storage from regular users

Swarm information storage uses the Perforce service'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 Perforce service. When dm.keys.hide is set to 1, only the p4 keys command requires admin-level access in the Perforce service. 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