Perforce 2007.3 System Administrator's Guide
<< Previous Chapter
Customizing Perforce:
Job Specifications

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Tuning Perforce for Performance

Chapter 6
Scripting Perforce:
Triggers and Daemons

There are two primary methods of scripting Perforce:

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

Triggers

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

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:
   relnotes_check  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.

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 twelve 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 its contents are parsed, but before its 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 its 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 it has been committed, enabling 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.

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). Triggers that fire on the p4 triggers command are ignored.

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

change-submit,
change-content,
change-commit,
fix-add,
fix-delete,
form-commit

%client%

Triggering user's client workspace name.

all

%clienthost%

Hostname of the client.

all

%clientip%

The IP address of the client.

all

%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

%serverhost%

Hostname of the Perforce server.

all

%serverip%

The IP address of the server.

all

%serverport%

The IP address and port of the Perforce server, in the format ip_address:port.

all

%serverroot%

The P4ROOT directory of the Perforce server.

all

%user%

Perforce username of the triggering user.

all

%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

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.

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.

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.

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

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 forms for users, to validate forms, to notify other users of attempted changes to forms, 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.

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.

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.

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.

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.

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:

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.

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.

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.

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

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" on page 108.

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.

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

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:

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:

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" on page 123) 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://www.perforce.com and follow the "Perforce Public Depot" link.

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 signed ints.  For most platforms, the largest value that can be stored in a counter is 231 - 1, or 2147483647. A server running on a 64-bit platform can store counters up to 263 - 1, or 9223372036854775807

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.


Perforce 2007.3 System Administrator's Guide
<< Previous Chapter
Customizing Perforce:
Job Specifications

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Tuning Perforce for Performance
Please send comments and questions about this manual to [email protected].
Copyright 1999-2007 Perforce Software. All rights reserved.
Last updated: 11/29/07