Perforce 2009.2: System Administrator's Guide

Chapter 6

Scripting Perforce: Triggers and Daemons

There are two primary methods of scripting Perforce:

•

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.

To make use of this chapter, you must know how to write scripts.

Triggers

Triggers are useful in many situations. Consider the following common uses:

•	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 retrieve (or generate) content from data sources archived outside of the Perforce repository.

•	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

After you have written a trigger script, create the trigger by issuing the p4 triggers command. The p4 triggers form looks like this:

Triggers:   relnotecheck change-submit //depot/bld/... "/usr/bin/rcheck.pl %user%"   verify_jobs  change-submit //depot/...     "/usr/bin/job.py %change%"

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

Each line in the trigger table has four fields.

Field	Meaning
name	The user-defined name of the trigger. A run of the same trigger name on contiguous lines is treated as a single trigger, so that multiple paths may be specified. In this case, only the command of the first such trigger line is used.
type	There are thirteen trigger types, divided into four subtypes: changelist submission triggers, fix triggers, form triggers, and authentication triggers. Changelist submission triggers: • change-submit: Execute a changelist trigger after changelist creation, but before file transfer. Trigger may not access file contents. • change-content: Execute a changelist trigger after changelist creation and file transfer, but before file commit. To obtain file contents, use commands such as p4 diff2, p4 files, p4 fstat, and p4 print with the revision specifier @=change, where change is the changelist number of the pending changelist as passed to the script in the %changelist% variable. • change-commit: Execute a changelist trigger after changelist creation, file transfer, and changelist commit.
	Fix triggers: The special variable %jobs% is available for expansion; it expands 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), and must therefore be the last argument supplied to the trigger script. • fix-add: Execute fix trigger prior to adding a fix. • fix-delete: Execute fix trigger prior to deleting a fix.
	Form triggers: • form-save: Execute a form trigger after the form contents are parsed, but before the contents are stored in the Perforce database. The trigger cannot modify the form specified in %formfile% variable. • form-out: Execute form trigger upon generation of form to end user. The trigger can modify the form. • form-in: Execute form trigger on edited form before contents are parsed and validated by the Perforce server. The trigger can modify the form. • form-delete: Execute form trigger after the form contents are parsed, but before the form is deleted from the Perforce database. The trigger cannot modify the form. • form-commit: Execute form trigger after the form has been committed for access to automatically-generated fields such as jobname, dates, etc. For job forms, this trigger is run by p4 job as well as p4 fix (after the status is updated). The form-commit trigger has access to the new job name created by p4 job; any form-in and form-save triggers are run before the job name is created. For job forms, this trigger is also run by p4 change (if a job is added or deleted by editing the Jobs: field of the changelist), and p4 submit (for any jobs present in the Jobs: field of the changelist). In these cases, the special variable %action% is available for expansion on the job form-commit trigger command line. The trigger cannot modify the form.
	Authentication triggers: • auth-check: Execute an authentication check trigger to verify a user's password against an external password manager during login, or when setting a new password If an auth-check trigger is present, the Perforce security counter (and any associated password strength requirement) is ignored, as authentication is now controlled by the trigger script. • auth-set: Execute an authentication set trigger to send a new password to an external password manager. You must restart the Perforce server after adding an auth-check trigger.
	Archive triggers: • archive: Execute the script when a user accesses any file with a filetype containing the +X filetype modifier. The script is run once per file requested. For read operations, scripts should deliver the file to the user on standard output. For write operations, scripts receive the file on standard input.
path	For changelist submission triggers (change-submit, change-content, or change-commit), a file pattern in depot syntax. When a user submits a changelist that contains any files that match this file pattern, the script linked to this trigger is run. Use exclusionary mappings to prevent triggers from running on specified files. For fix triggers (fix-add or fix-delete), use fix as the path value. For form triggers (form-save, form-out, form-in, form-commit, or form-delete), the name of the type of form, (one of branch, change, client, depot, group, job, label, protect, spec, triggers, typemap, or user). For authentication triggers (auth-check or auth-set), use auth as the path value.
command	The command for the Perforce server to run when a matching path applies for the trigger type. Specify the command in a way that allows the Perforce server account to locate and run the command. The command must be quoted, and can take the variables specified below as arguments. For change-submit and change-content triggers, changelist submission continues if the trigger script exits with 0, or fails if the script exits with a nonzero value. For change-commit triggers, changelist submission succeeds regardless of the trigger script's exit code, but subsequent change-commit triggers do not fire if the script exits with a nonzero value. For form-in, form-out, form-save, and form-delete triggers, the data in the specification becomes part of the Perforce database if the script exits with 0. Otherwise, the database is not updated. The form-commit trigger type never rejects a change; it exists primarily so that scripts can access a job number (from the %formname% variable) during the process of job creation. For fix-add and fix-delete triggers, fix addition or deletion continues if the trigger script exits with 0, or fails if the script exits with a nonzero value. For auth-check triggers (fired by p4 login), the user's typed password is supplied to the trigger command as standard input. If the trigger executes successfully, the Perforce ticket is issued. The user name is available as %user% to be passed on the command line. For auth-set triggers, (fired by p4 passwd, but only after also passing an auth-check trigger check) the user's old password and new password are passed to the trigger as standard input. The user name is available as %user% to be passed on the command line.

Trigger script variables

Use the following variables in the command field to pass data to a trigger script:

Argument	Description	Available for type
%action%	Either null or a string reflecting an action taken to a changelist or job. For example, "pending change 123 added" or "submitted change 124 deleted" are possible %action% values on change forms, and "job000123 created" or "job000123 edited" are possible %action% values for job forms.	form-commit
%changelist% %change%	The number of the changelist being submitted. The abbreviated form %change% is equivalent to %changelist%. A change-submit trigger is passed the pending changelist number; a change-commit trigger receives the committed changelist number.	change-submit, change-content, change-commit, fix-add, fix-delete, form-commit
%changeroot%	The root path of files submitted	change-commit
%client%	Triggering user's client workspace name.	all but archive
%clienthost%	Hostname of the client.	all but archive
%clientip%	The IP address of the client.	all but archive
%jobs%	A string of job numbers, expanded to one argument for each job number specified on a p4 fix command or for each job number added to (or removed from) the Jobs: field in a p4 submit, or p4 change form.	fix-add fix-delete
%oldchangelist%	If a changelist is renumbered on submit, this variable contains the old changelist number.	change-commit
%serverhost%	Hostname of the Perforce server.	all but archive
%serverip%	The IP address of the server.	all but archive
%serverport%	The IP address and port of the Perforce server, in the format ip_address:port.	all but archive
%serverroot%	The P4ROOT directory of the Perforce server.	all but archive
%user%	Perforce username of the triggering user.	all but archive
%formfile%	Path to temporary form specification file. To modify the form from an in or out trigger, overwrite this file. The file is read-only for triggers of type save and delete.	form-commit, form-save, form-out, form-in, form-delete
%formname%	Name of form (for instance, a branch name or a changelist number).	form-commit, form-save, form-out, form-delete
%formtype%	Type of form (for instance, branch, change, and so on).	form-commit, form-save, form-out, form-in, form-delete
%op%	Operation: read, write, or delete	archive
%file%	Path of archive file based on depot's Map: field. If the Map: field is relative to P4ROOT, the %file% is a server-side path relative to P4ROOT. If the Map: field is an absolute path, the %file% is an absolute server-side path.	archive
%rev%	Revision of archive file	archive

Triggering on changelists

To configure Perforce to run trigger scripts when users submit changelists, use changelist submission triggers: these are triggers of type change-submit, change-content, and change-commit.

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

Use the change-submit trigger type to create triggers that fire after changelist creation, but before files are transferred to the server. Because change-submit triggers fire before files are transferred to the server, these triggers cannot access file contents. Change-submit triggers are useful for integration with reporting tools or systems that do not require access to file contents.

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.

@echo off rem REMINDERS rem - If necessary, set Perforce environment vars or use config file rem - Set PATH or use full paths (C:\PROGRA~1\Perforce\p4.exe) rem - Use short pathnames for paths with spaces, or quotes rem - For troubleshooting, log output to file, for instance: rem - C:\PROGRA~1\Perforce\p4 info >> trigger.log if not x%1==x goto doit echo Usage is %0[change#] :doit p4 describe -s %1|findstr "Jobs fixed...\n\n\t" > nul if errorlevel 1 echo No jobs found for changelist %1 p4 describe -s %1|findstr "Jobs fixed...\n\n\t" > nul

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 the change-content trigger type to create triggers that fire after changelist creation and file transfer, but prior to committing the submit to the database. Change-content triggers can access file contents by using the p4 diff2, p4 files, p4 fstat, and p4 print commands with the @=change revision specifier, where change is the number of the pending changelist as passed to the trigger script in the %changelist% variable.

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

Use the change-commit trigger type to create triggers that fire after changelist creation, file transfer, and changelist commission to the database. Use change-commit triggers for processes that assume (or require) the successful submission of a changelist.

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

To configure Perforce to run trigger scripts when users add or delete fixes from changelists, use fix triggers: these are triggers of type fix-add and fix-delete.

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.

#!/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

To configure Perforce to run trigger scripts when users edit forms, use form triggers: these are triggers of type form-save, form-in, form-out, form-delete, and form-commit.

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

Use the form-save trigger type to create triggers that fire when users send changed forms to the server. Form-save triggers are called after the form has been parsed by the server but before the changed form is stored in the Perforce metadata.

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

Use the form-out trigger type to create triggers that fire whenever the Perforce server generates a form for display to the user.

Warning!

Never use a Perforce command in a form-out trigger that fires the same form-out trigger, or infinite recursion will result. For example, never run p4 job -o from within a form-out trigger script that fires on job forms.

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

Use the form-in trigger type to create triggers that fire when a user attempts to send a form to the server, but before the form is parsed by the Perforce server.

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

Use the form-delete trigger type to create triggers that fire when users attempt to delete a form, after the form is parsed by the Perforce server, but before the form is deleted from the Perforce database.

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.

#!/bin/sh echo "Jobs may not be deleted. Please mark jobs as closed instead." exit 1

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

Unlike the other form triggers, the form-commit trigger fires after a form is committed to the database. Use these triggers for processes that assume (or require) the successful submission of a form. In the case of job forms, the job's name is not set until after the job has been committed to the database; the form-commit trigger is the only way to obtain the name of a new job as part of the process of job creation.

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

To configure Perforce to work with an external authentication manager (such as LDAP or Active Directory), use authentication triggers (auth-check and auth-set). These triggers fire on the p4 login and p4 passwd commands, respectively.

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

Warning!

Be sure to spell the trigger name correctly when you add the trigger to the trigger table because a misspelling can result in all users being locked out of Perforce. Be sure to fully test your trigger and trigger table invocation prior to deployment in a production environment. Contact Perforce Technical Support if you need assistance with restoring access to your server.

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

You must restart the Perforce server after adding an auth-check trigger in order for it to take effect. You can, however, change an existing auth-check trigger table entry (or trigger script) without restarting the server.

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

Triggers of type auth-check fire when users run the p4 login command. If the script returns 0, login is successful, and a ticket file is created for the user.

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.

#!/bin/bash # checkpass.sh - a trivial authentication-checking script # in this trivial example, all users have the same "secret" password USERNAME=$1 PASSWORD=secret # read user-supplied password from stdin read USERPASS # compare user-supplied password with correct password if [ "$USERPASS" = $PASSWORD ] then     # Success     exit 0 fi # Failure echo checkpass.sh: password $USERPASS for $USERNAME is incorrect exit 1

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

Triggers of type auth-set fire when users run the p4 passwd command and successfully validate their old password with an auth-check trigger. The process is as follows:

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.

Because the Perforce server must validate the user's current password, you must have a properly functioning auth-check trigger before attempting to write an auth-set trigger.

Example: A trivial authentication-setting script

#!/bin/bash # setpass.sh - a trivial authentication-setting script USERNAME=$1 read OLDPASS read NEWPASS echo setpass.sh: $USERNAME attempted to change $OLDPASS to $NEWPASS

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.

Archive triggers for external data sources

The archive trigger type is used in conjunction with the +X filetype modifier in order to replace the mechanism by which the Perforce Server archives files within the repository. See Triggers and Windows for platform-specific considerations.

Example: An archive trigger

This archive trigger fires when users access files that have the +X (archive) modifier set.

#!/bin/sh # archive.sh - illustrate archive trigger OP=$1 FILE=$2 REV=$3 if [ "$OP" = read ] then     cat ${FILE}${REV} fi if [ "$OP" = delete ] then     rm ${FILE}${REV} fi if [ "$OP" = write ] then     # Create new file from user's submission via stdin     while read LINE; do         echo ${LINE} >> ${FILE}${REV}     done     ls -t ${FILE}* |     {         read first; read second;         cmp -s $first $second         if [ $? -eq 0 ]         then             # Files identical, remove file, replace with symlink.             rm ${FILE}${REV}             ln -s $second $first         fi     } fi

To use the trigger, add the following two lines to the trigger table:

arch  archive  arch  "archive.sh %op% %file% %rev%"

When the user attempts to submit (write) a file of type +X, if there are no changes between the current revision and the previous revision, the current revision is replaced with a symlink pointing to the previous revision.

Using multiple triggers

Changelist and form triggers are run in the order in which they appear in the triggers table. If you have multiple triggers of the same type that fire on the same path, each is run in the order in which it appears in the triggers table. If one of these triggers fails, no further triggers are executed.

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)

Similarly, form triggers of different types are fired in the following order:

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

To call the same trigger script from more than one Perforce server, use the %serverhost%, %serverip%, and %serverport% variables to make your trigger script more portable.

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

#!/bin/sh # Usage: jobcheck.sh changelist CHANGE=$1 P4CMD="/usr/local/bin/p4 -p 192.168.0.12:1666" $P4CMD describe -s $1 | grep "Jobs fixed...\n\n\t" > /dev/null

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

jc1 change-submit //depot/qa/... "jobcheck.sh %change%"

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

#!/bin/sh # Usage: jobcheck.sh changelist server:port CHANGE=$1 P4PORT=$2 P4CMD="/usr/local/bin/p4 -p $P4PORT" $P4CMD describe -s $1 | grep "Jobs fixed...\n\n\t" > /dev/null

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

jc2 change-submit //depot/qa/... "jobcheck.sh %change% %serverport%"

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

Triggers and security

Warning!

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

Triggers and Windows

By default, the Perforce service runs under the Windows local System account. The System account may have different environmental configurations (including not just Perforce-related variables, but PATH settings and file permissions) than the one in which you are using to test or write your trigger.

In general, it is good practice to:

•	Wherever possible, use the full path to executables.

•	For path names that contain spaces, use the short path name.

For example, C:\Program Files\Perforce\p4.exe is most likely located in C:\PROGRA~1\Perforce\p4.exe.

•	Login tickets may not be located in the same place as they were during testing; for testing, you can pass in data with p4 login < input.txt.

•	For troubleshooting, log output to a file. For example:

date /t >> trigger.log
p4 info >> trigger.log
C:\PROGRA~1\Perforce\p4.exe -p myserver:myport info

If the trigger.log isn't updated at all, the trigger was not fired. If the first p4 info fails, and the second p4 info runs, you'll know whether there were differences in environmental settings.

•	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 Windows, standard input does not default to binary mode. In text mode, line ending translations are performed on standard input, which is inappropriate for binary files.

If you are using archive triggers against binary files on a Windows machine, you must prevent unwanted line-ending translations by ensuring that standard input is changed to binary mode (O_BINARY).

Daemons

Daemons are processes that are called periodically or run continuously in the background. Daemons that use Perforce usually work by examining the server metadata as often as needed and taking action as often as necessary.

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.

Daemons can be used for almost any task that needs to occur when Perforce metadata has changed. Unlike triggers, which are used primarily for submission validation, daemons can also be used to write information (that is, submit files) to a depot.

Perforce's change review daemon

The Perforce change review daemon (p4review.py) is available from the Perforce Supporting Programs page:

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

The review daemon runs under Python, available at http://www.python.org/. Before you run the review daemon, be sure to read and follow the configuration instructions included in the daemon itself.

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.

User:     sarahm Email:    [email protected] Update:   1997/04/29 11:52:08 Access:   1997/04/29 11:52:08 FullName: Sarah MacLonnogan Reviews:         //depot/doc/...         //depot.../README

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.

The command used in the fourth step (p4 describe) is a straightforward reporting command. The other commands (p4 review, p4 reviews, and p4 counter) are used almost exclusively by review daemons.

Creating other daemons

You can use p4review.py (see Perforce's change review daemon) as a starting point to create your own daemons, changing it as needed. As an example, another daemon might upload Perforce job information into an external bug tracking system after changelist submission. It would use the p4 review command with a new review counter to list new changelists, and use p4 fixes to get the list of jobs fixed by the newly submitted changelists. This information might then be fed to the external system, notifying it that certain jobs have been completed.

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://public.perforce.com.

Commands used by daemons

Certain Perforce commands are used almost exclusively by review daemons. These commands are listed in the following table.

Command	Usage
p4 review -c change#	For all changelists between change# and the latest submitted changelist, this command lists the changelists' numbers, creators, and creators' email addresses. Requires at least review access to run.
p4 reviews -c change# filespec	Lists all users who have subscribed to review the named files or any files in the specified changelist.
p4 counter name [value]	To create a new counter or set the value of an existing counter, you must have review access or greater. To display a counter's value, you must have list access or greater. If a value argument is not included, p4 counter returns the value of name, or 0 if the counter does not exist. If a value argument is included, p4 counter sets the value of the name to value. If the counter name does not exist, it is created. WARNING: The review counters journal, job, and change are used internally by Perforce; use of any of these three names as review numbers could corrupt the Perforce database. Counters are represented internally as strings. (Prior to release 2008.1, they were stored as signed ints)
p4 counters	List all counters and their values.
p4 changes -m 1 -s submitted	Outputs a single line showing the changelist number of the last submitted changelist, as opposed to the highest changelist number known to the Perforce server.

Daemons and counters

If you're writing a change review daemon or other daemon that deals with submitted changelists, you might also want to keep track of the changelist number of the last submitted changelist, which is the second field in the output of a p4 changes -m 1 -s submitted command.

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

Depending on your platform, the output of individual p4 commands can be fully-buffered (output flushed only after a given number of bytes generated), line-buffered (as on a tty, one line sent per linefeed), or unbuffered.

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.