Chapter 6
Scripting Perforce:
Triggers and Daemons

• Perforce triggers are user-written scripts that are called by a Perforce server whenever certain operations (such as changelist submissions, changes to forms, attempts by users to log in or change passwords) are performed. If the script returns a value of 0, the operation continues; if the script returns any other value, the operation fails. Upon failure, the script's standard output (not error output) is sent to the Perforce client program as an error message.

• Daemons run at predetermined times, looking for changes to the Perforce metadata. When a daemon determines that the state of the depot has changed in some specified way, it runs other commands. For example, a daemon might look for newly submitted changelists and send email to users interested in tracking changes to those files. Perforce provides a number of tools that make writing daemons easier.

Triggers

• To validate changelist contents beyond the mechanisms afforded by the Perforce protections table. For example, you can use a pre-submit trigger to ensure that whenever file1 is submitted in a changelist, file2 is also submitted.

• To validate file contents as part of changelist submission. For example, you can use a mid-submit trigger to ensure that, when file1 and file2 are submitted, both files refer to the same set of header files.

• To start build processes after successful changelist submission.

• To validate forms, or to provide customized versions of Perforce forms. For example, you can use form triggers to generate a customized default workspace view when users run the p4 client command, or to ensure that users always enter a meaningful workspace description.

• To configure Perforce to work with external authentication mechanisms such as LDAP or Active Directory.

• To notify other users of attempts to change or delete data with commands such as p4 user and p4 job, or to trigger process control tools following updates to Perforce metadata.

  Note	As of Release 2007.3, trigger standard output is passed to the client program on both success and failure of the trigger script. Prior to this, standard output was only passed to the client program on failure of a trigger.

  Warning!

  When you use trigger scripts, remember that Perforce commands that write data to the depot are dangerous and should be avoided. In particular, do not run the p4 submit command from within a trigger script.

  Warning!

  If you write a trigger that fires on trigger forms, and the trigger fails in such a way that the p4 triggers command no longer works, the only recourse is to remove the db.triggers file in the server root directory.

  Example:  A basic trigger
  The development group wants to ensure that whenever a changelist containing an .exe file is submitted to the depot, the release notes for the program are submitted at the same time.
  You write a trigger script that takes a changelist number as its only argument, performs a p4 opened on the changelist, parses the results to find the files included in the changelist, and ensures that for every executable file that's been submitted, a RELNOTES file in the same directory has also been submitted. If the changelist includes a RELNOTES file, the script terminates with an exit status of 0; otherwise the exit status is set to 1.
  After you write the script, add it to the trigger table by editing the p4 triggers form as follows:

  Triggers:   rnotes change-submit  //depot/....exe  "/usr/bin/test.pl %change%"

  (Like other Perforce forms, indent each line under the Triggers: field with tabs.)
  Whenever a changelist containing an .exe file is submitted, this trigger fires. If the trigger script fails, it returns a nonzero exit status, and the user's submit fails.

The trigger table

As with all Perforce commands that use forms, field names (such as Triggers:) must be flush left (not indented) and must end with a colon, and field values (that is, the set of lines you add, one for each trigger) must be indented with spaces or tabs on the lines beneath the field name.

When testing and debugging triggers, remember that any p4 commands invoked from within the script will run within a different environment (P4USER, P4CLIENT, and so on) than that of the calling user.

You must specify the name of the trigger script or executable in ASCII, even when the server is running in Unicode mode and passes arguments to the trigger script in UTF8.

You must be a Perforce superuser to run p4 triggers.

Trigger table fields

Trigger script variables

Triggering on changelists

For changelist submission triggers, the path column of each trigger line is a file pattern in depot syntax. If a changelist being submitted contains any files in this path, the trigger fires. To prevent changes to a file from firing a trigger, use an exclusionary mapping in the path.

Change-submit triggers

Example:  The following change-submit trigger is an MS-DOS batch file that rejects a changelist if the submitter has not assigned a job to the changelist. This trigger fires only on changelist submission attempts that affect at least one file in the //depot/qa branch.  

To use the trigger, add the following line to your triggers table:

sample1   change-submit //depot/qa/...   "jobcheck.bat %changelist%"

Every time a changelist is submitted that affects any files under //depot/qa, the jobcheck.bat file is called. If the string "Jobs fixed..." (followed by two newlines and a tab character) is detected, the script assumes that a job has been attached to the changelist and permits changelist submission to continue. Otherwise, the submit is rejected.

The second findstr command ensures that the final error level of the trigger script is the same as the error level that determines whether to output the error message.

Change-content triggers

Use change-content triggers to validate file contents as part of changelist submission and to abort changelist submission if the validation fails.

Example:  The following change-content trigger is a Bourne shell script that ensures that every file in every changelist contains a copyright notice for the current year.

The script assumes the existence of a client workspace called copychecker that includes all of //depot/src. This workspace does not have to be synced.

#!/bin/sh # Set target string, files to search, location of p4 executable... TARGET="Copyright `date +%Y` Example Company" DEPOT_PATH="//depot/src/..." CHANGE=$1 P4CMD="/usr/local/bin/p4 -p 1666 -c copychecker" XIT=0 echo "" # For each file, strip off #version and other non-filename info # Use sed to swap spaces w/"%" to obtain single arguments for "for" for FILE in `$P4CMD files $DEPOT_PATH@=$CHANGE | \   sed -e 's/\(.*\)\#[0-9]* - .*$/\1/' -e 's/ /%/g'` do   # Undo the replacement to obtain filename...   FILE="`echo $FILE | sed -e 's/%/ /g'`" # ...and use @= specifier to access file contents:   # p4 print -q //depot/src/file.c@=12345   if $P4CMD print -q "$FILE@=$CHANGE" | grep "$TARGET" > /dev/null   then echo ""   else       echo "Submit fails: '$TARGET' not found in $FILE"       XIT=1   fi done exit $XIT

To use the trigger, add the following line to your triggers table:

sample2  change-content //depot/src/... "copydate.sh %change%"

The trigger fires when any changelist with at least one file in //depot/src is submitted. The corresponding DEPOT_PATH defined in the script ensures that of all the files in the triggering changelist, only those files actually under //depot/src are checked.

Change-commit triggers

Example:  A change-commit trigger that sends emails to other users who have files open in the submitted changelist.

#!/bin/sh # mailopens.sh - Notify users when open files are updated changelist=$1 workspace=$2 user=$3 p4 fstat @$changelist,@$changelist | while read line do   # Parse out the name/value pair.   name=`echo $line | sed 's/[\. ]\+\([^ ]\+\) .\+/\1/'`   value=`echo $line | sed 's/[\. ]\+[^ ]\+ \(.\+\)/\1/'`   if [ "$name" = "depotFile" ]   then     # Line is "... depotFile <depotFile>". Parse to get depotFile.     depotfile=$value   elif [ "`echo $name | cut -b-9`" = "otherOpen" -a \     "$name" != "otherOpen" ]   then     # Line is "... ... otherOpen[0-9]+ <otherUser@otherWorkspace>".     # Parse to get otherUser and otherWorkspace.     otheruser=`echo $value | sed 's/\(.\+\)@.\+/\1/'`     otherworkspace=`echo $value | sed 's/.\+@\(.\+\)/\1/'`     # Get email address of the other user from p4 user -o.     othermail=`p4 user -o $otheruser | grep Email: \       | grep -v \# | cut -b8-`     # Mail other user that a file they have open has been updated     mail -s "$depotfile was just submitted" $othermail <<EOM The Perforce file: $depotfile was just submitted in changelist $changelist by Perforce user $user from the $workspace workspace.  You have been sent this message because you have this file open in the $otherworkspace workspace. EOM   fi done exit 0

To use the trigger, add the following line to your triggers table:

sample3  change-commit //... "mailopens.sh %change% %client% %user%"

Whenever a user submits a changelist, any users with open files affected by that changelist receive an email notification.

Triggering on fixes

Fix-add and fix-delete triggers

Example:  The following script, when copied to fixadd.sh and fixdel.sh, fires when users attempt to add or remove fix records, whether by using the p4 fix command, or by modifying the Jobs: field of the forms presented by the p4 change and p4 submit commands. to fix-add and fix-delete triggers.

#!/bin/bash # fixadd.sh, fixdel.sh - illustrate fix-add and fix-delete triggers COMMAND=$0 CHANGE=$1 NUMJOBS=$(($# - 1 )) echo $COMMAND: fired against $CHANGE with $NUMJOBS job arguments. echo $COMMAND: Arguments were: $*

These fix-add and fix-delete triggers fire whenever users attempt to add (or delete) fix records from changelists. To use the trigger, add the following lines to the trigger table:

sample4   fix-add    fix "fixadd.sh %change% %jobs%" sample5   fix-delete fix "fixdel.sh %change% %jobs%"

Using both copies of the script, observe that fixadd.sh is triggered by p4 fix, the fixdel.sh script is triggered by p4 fix -d, and either script may be triggered by manually adding (or deleting) job numbers from within the Jobs: field in a changelist form - either by means of p4 change or as part of the p4 submit process.

Because the %jobs% variable is expanded to one argument for every job listed on the p4 fix command line (or in the Jobs: field of a p4 change or p4 submit form), it must be the last argument supplied to any fix-add or fix-delete trigger script.

Triggering on forms

Use form triggers to generate customized field values for users, to validate forms, to notify other users of attempted changes to form data, and to otherwise interact with process control and management tools.

Form-save triggers

Example:  To prohibit certain users from modifying their client workspaces, add the users to a group called lockedws and use the following form-save trigger.

This trigger denies attempts to change client workspace specifications for users in the lockedws group, outputs an error message containing the user name, IP address of the user's workstation, and the name of the workspace on which a modification was attempted, and notifies an administrator.

#!/bin/bash NOAUTH=lockedws USERNAME=$1 WSNAME=$2 IPADDR=$3 GROUPS=`p4 groups "$1"` if echo "$GROUPS" | grep -qs $NOAUTH then    echo "$USERNAME ($IPADDR) in $NOAUTH may not change $WSNAME"    mail -s "User $1 workspace mod denial" [email protected]    exit 1 else    exit 0 fi

This form-save trigger fires on client forms only. To use the trigger, add the following line to the trigger table:

sample6   form-save  client  "ws_lock.sh %user% %client% %clientip%"

Users whose names appear in the output of p4 groups lockedws have changes to their client workspaces parsed by the server, and even if those changes are syntactically correct, the attempted change to the workspace is denied, and an administrator is notified of the attempt.

Form-out triggers

Example:  The default Perforce client workspace view maps the entire depot //depot/... to the user's client workspace. To prevent novice users from attempting to sync the entire depot, this Perl script changes a default workspace view of //depot/... in the p4 client form to map only the current release codeline of //depot/releases/main/...

#!/usr/bin/perl # default_ws.pl - Customize the default client workspace view. $p4 = "p4 -p localhost:1666"; $formname = $ARGV[0];  # from %formname% in trigger table $formfile = $ARGV[1];  # from %formfile% in trigger table # Default server-generated workspace view and modified view # (Note: this script assumes that //depot is the only depot defined) $defaultin = "\t//depot/... //$formname/...\n"; $defaultout = "\t//depot/releases/main/... //$formname/...\n"; # Check "p4 clients": if workspace exists, exit w/o changing view. open CLIENTS, "$p4 clients |" or die "Couldn't get workspace list"; while ( <CLIENTS> ) {         if ( /^Client $formname .*/ ) { exit 0; } } # Build a modified workspace spec based on contents of %formfile% $modifiedform = ""; open FORM, $formfile or die "Trigger couldn't read form tempfile"; while ( <FORM> ) {       ## Do the substitution as appropriate.         if ( m:$defaultin: ) { $_ = "$defaultout"; }         $modifiedform .= $_; } # Write the modified spec back to the %formfile%, open MODFORM, ">$formfile" or die "Couldn't write form tempfile"; print MODFORM $modifiedform; exit 0;

This form-out trigger fires on client workspace forms only. To use the trigger, add the following line to the trigger table:

sample7   form-out  client  "default_ws.pl %formname% %formfile%"

New users creating client workspaces are presented with your customized default view.

Form-in triggers

Example:  All users permitted to edit jobs have been placed in a designated group called jobbers. The following Python script runs p4 group -o jobbers with the -G (Python marshaled objects) flag to determine if the user who triggered the script is in the jobbers group.

import sys, os, marshal # Configure for your environment tuser = "triggerman"   # trigger username job_group = "jobbers"  # Perforce group of users who may edit jobs # Get trigger input args user = sys.argv[1] # Get user list # Use global -G flag to get output as marshaled Python dictionary CMD = "p4 -G -u %s -p 1666 group -o %s" % \         (tuser, job_group) result = {} result = marshal.load(os.popen(CMD, 'r')) job_users = [] for k in result.keys():         if k[:4] == 'User': # user key format: User0, User1, ...                 u = result[k]                 job_users.append(u) # Compare current user to job-editing users. if not user in job_users:         print "\n\t>>> You don't have permission to edit jobs."         print "\n\t>>> You must be a member of '%s'.\n" % job_group         sys.exit(1) else: # user is in job_group -- OK to create/edit jobs         sys.exit(0)

This form-in trigger fires on job forms only. To use the trigger, add the following line to the trigger table:

sample8   form-in  job  "python jobgroup.py %user%"

If the user is in the jobbers group, the form-in trigger succeeds, and the changed job is passed to the Perforce server for parsing. Otherwise, an error message is displayed, and changes to the job are rejected.

Form-delete triggers

Example:  An administrator wants to enforce a policy that users are not to delete jobs from the system, but must instead mark such jobs as closed.  

This form-delete trigger fires on job forms only. To use the trigger, add the following line to the trigger table:

sample9   form-delete  job  "nodeljob.sh"

Whenever a user attempts to delete a job, the request to delete the job is rejected, and the user is shown an error message.

Form-commit triggers

Example:  The following script, when copied to newjob.sh, shows how to get a job name during the process of job creation, and also reports the status of changelists associated with job fixes.

#!/bin/sh # newjob.sh - illustrate form-commit trigger COMMAND=$0 USER=$1 FORM=$2 ACTION=$3 echo $COMMAND: User $USER, formname $FORM, action $ACTION >> log.txt

To use the trigger, add the following line to the trigger table:

sample10   form-commit  job    "newjob.sh %user% %formname% %action%"

Use the %action% variable to distinguish whether or not a change to a job was prompted by a user directly working with a job by means of p4 job, or indirectly by means of fixing the job within the context of p4 fix or the Jobs: field of a changelist.

The simplest case is the creation of a new job (or a change to an existing job) with the p4 job command; the trigger fires, and the script reports the user, the name of the newly-created (or edited) job. In these cases, the %action% variable is null.

The trigger also fires when users add or delete jobs to changelists, and it does so regardless of whether the changed jobs are being manipulated by means of p4 fix, p4 fix -d, or by editing the Jobs: field of the changelist form provided by p4 change or p4 submit form). In these cases, the %action% variable holds the status of the changelist (pending or submitted) to which the jobs are being added or deleted.

Because the %action% variable is not always set, it must be the last argument supplied to any form-commit trigger script.

Using triggers for external authentication

Authentication triggers differ from changelist and form triggers in that passwords typed by the user as part of the authentication process are supplied to authentication scripts as standard input; never on the command line. (The only arguments passed on the command line are those common to all trigger types, such as %user%, %clientip%, and so on.)

The examples in this book are for illustrative purposes only. For a more detailed discussion, including links to sample code for an LDAP environment, see the following Tech Note:

http://www.perforce.com/perforce/technotes/note074.html

After an auth-check trigger is in place and the server restarted, the Perforce security counter is ignored; because authentication is now under the control of the trigger script, the server's default mechanism for password strength requirements is redundant.

Auth-check triggers

Example:  A trivial authentication-checking script. All users must enter the password "secret" before being granted login tickets. Passwords supplied by the user are sent to the script on stdin.  

This auth-check trigger fires whenever users run p4 login. To use the trigger, add the following line to the trigger table:

sample11  auth-check  auth  "checkpass.sh %user%"

Users who enter the "secret" password are granted login tickets.

Auth-set triggers

1. A user invokes p4 passwd.

2. The Perforce server prompts the user to enter his or her old password.

3. The Perforce server fires an auth-check trigger to validate the old password against the external authentication service.

4. The script associated with the auth-check trigger runs. If the auth-check trigger fails, the process ends immediately: the user is not prompted for a new password, and the auth-set trigger never fires.

5. If the auth-check trigger succeeds, the Perforce server prompts the user for a new password.

6. The Perforce server fires an auth-set trigger and supplies the trigger script with both the old password and the new password on the standard input, separated by a newline.

   Note	In most cases, users in an external authentication environment will continue to set their passwords without use of Perforce. The auth-set trigger type is included mainly for completeness.

Example:  A trivial authentication-setting script  

This auth-set trigger fires after users run p4 passwd and successfully pass the external authentication required by the auth-check trigger. To use the trigger, add the following two lines to the trigger table:

sample11  auth-check  auth  "checkpass.sh %user%" sample12  auth-set    auth  "setpass.sh %user%"

This trivial example doesn't actually change any passwords; it merely reports back what the user attempted to do.

Using multiple triggers

Example:  Multiple triggers on the same file

All *.c files must pass through the scripts check1.sh, check2.sh, and check3.sh:

Triggers:   check1 change-submit //depot/src/*.c "/usr/bin/check1.sh %change%"   check2 change-submit //depot/src/*.c "/usr/bin/check2.sh %change%"   check3 change-submit //depot/src/*.c "/usr/bin/check3.sh %change%"

If any trigger fails (for instance, check1.sh), the submit fails immediately, and none of the subsequent triggers (that is, check2.sh and check3.sh) are called. Each time a trigger succeeds, the next matching trigger is run.

To link multiple file specifications to the same trigger (and trigger type), list the trigger multiple times in the trigger table.

Example:  Activating the same trigger for multiple filespecs

Triggers:   bugcheck change-submit //depot/*.c  "/usr/bin/check4.sh %change%"   bugcheck change-submit //depot/*.h  "/usr/bin/check4.sh %change%"   bugcheck change-submit //depot/*.cpp "/usr/bin/check4.sh %change%"

In this case, the bugcheck trigger runs on the *.c files, the *.h files, and the *.cpp files.

Multiple changelist submission triggers of different types that fire on the same path fire in the following order:

1. change-submit (fired on changelist submission, before file transmission)

2. change-content triggers (after changelist submission and file transmission)

3. change-commit triggers (on any automatic changelist renumbering by the server)

1. form-out (form generation)

2. form-in (changed form is transmitted to the server)

3. form-save (validated form is ready for storage in the Perforce database)

4. form-delete (validated form is already stored in the Perforce database)

Writing triggers to support multiple Perforce servers

For instance, if you have a script that uses hardcoded port numbers and addresses...

...and you call it with the following line in the trigger table...

...you can improve portability by changing the script as follows...

...and passing the server-specific data as an argument to the trigger script:

For a complete list of variables that apply for each trigger type, see "Trigger script variables" on page 110.

Triggers and security

Warning!

Because triggers are spawned by the p4d process, never run p4d as root on UNIX systems.

Triggers and Windows

Because Windows requires a real account name and password to access files on a network drive, if the trigger script resides on a network drive, you must configure the service to use a real userid and password to access the script.

For details, see "Installing the Perforce service on a network drive" on page 149.

Daemons

Typical daemon applications include:

• A change review daemon that wakes up every ten minutes to see if any changelists have been submitted to the production depot. If any changelists have been submitted, the daemon sends email to those users who have "subscribed" to any of the files included in those changelists. The message informs them that the files they're interested in have changed.

• A jobs daemon that generates a report at the end of each day to create a report on open jobs. It shows the number of jobs in each category, the severity each job, and more. The report is mailed to all interested users.

• A Web daemon that looks for changes to files in a particular depot subdirectory. If new file revisions are found there, they are synced to a client workspace that contains the live web pages.

Perforce's change review daemon

http://www.perforce.com/perforce/loadsupp.html#daemon

Users subscribe to files by calling p4 user, entering their email addresses in the Email: field, and entering any number of file patterns corresponding to files in which they're interested in to the Reviews: field.

The change review daemon monitors the files that were included in each newly submitted changelist and emails all users who have subscribed to any files included in a changelist, letting those users know that the files in question have changed.

By including the special path //depot/jobs in the Reviews: field, users can also receive mail from the Perforce change review daemon whenever job data is updated.

The change review daemon implements the following scheme:

1. p4 counter is used to read and change a variable, called a counter, in the Perforce metadata. The counter used by this daemon, review, stores the number of the latest changelist that's been reviewed.

2. The Perforce depot is polled for submitted, unreviewed changelists with the p4 review -t review command.

3. p4 reviews generates a list of reviewers for each of these changelists.

4. The Python mail module mails the p4 describe changelist description to each reviewer.

5. The first three steps are repeated every three minutes, or at some other interval configured at the time of installation.

Creating other daemons

If you write a daemon of your own and would like to share it with other users, you can submit it into the Perforce Public Depot. For more information, go to http://www.perforce.com and follow the "Perforce Public Depot" link.

Commands used by daemons

Daemons and counters

This is not the same as the output of p4 counter change. The last changelist number known to the Perforce server (the output of p4 counter change) includes pending changelists created by users, but not yet submitted to the depot.

Scripting and buffering

In general, stdout to a file or pipe is fully buffered, and stdout to a tty is line-buffered. If your trigger or daemon requires line-buffering (or no buffering), you can disable buffering by supplying the -v0 debug flag to the p4 command in question.

If you're using pipes to transfer standard output from a Perforce command (with or without the -v0 flag), you might also experience buffering issues introduced by the kernel, because the -v0 flag can only unbuffer the output of the command itself.