p4d-watch -- post-submit triggers

Introduction  ::  Warnings  ::  Installation  ::  p4d-watch.cfg  ::  p4d-protect/p4d-group.txt  ::  Enhancements

» Introduction

The Perforce journal records all updates to the Perforce database. P4d-watch monitors the journal for interesting events. For example, if someone submits a change to //road/Perforce/main/protections/p4d-protect.txt, p4d-watch can automatically update Perforce's protection table.

P4d-watch is like a fast Perforce daemon. Perforce daemons detect events whenever they poll the server, typically every one to five minutes. P4d-watch responds to events within a second or two.

Use p4d-watch to

  1. Automatically sync a web site when the Perforce depot changes.
  2. Define Perforce protections with a text file in the Perforce depot
  3. Define Perforce groups by text files in the Perforce depot
  4. Allow individual users to control a Perforce group's membership.
  5. Automatically sync a file without creating a clientspec.
  6. Define write permissions for //user/...

p4d-watch consists of p4d-watch.pl, p4d-watch-admin.pl, p4d-watch.cfg, and p4d-watch.d. It includes sample files for p4d-protect.txt and p4d-group.txt

p4d-watch.pl reads Perforce's journal file and writes events to pd-watch.log. It watches for updates to Perforce's db.change and db.revcx tables. It writes events as defined by p4d-watch.cfg. It recreates p4d-watch.log if the old one is deleted or renamed. See 'p4d-watch.pl --help' for additional options.

p4d-watch-admin.pl processes events from p4d-watch.log. It logs the result of each event to p4d-watch-admin.log. It recreates p4d-watch-admin.log if the old one is deleted or renamed. See 'p4d-watch.pl --help' for additional options.

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY, SUPPORT, OR COPYRIGHT.

Send questions and comments to bradb@shore.net.

Many thanks to Art Technology Group for supporting this work.

$Server: public.perforce.com:1666 $$Id: //main/2005/road/p4d-watch/p4d-watch.html#1 $
$Date: 2006/10/20 $$Change: 597 $$Author: bbarber $

» Warnings

BE CAREFUL -- THIS CODE HAS COMPLETE ACCESS TO YOUR PERFORCE DEPOT. IT MAY MODIFY ANY FILE ON YOUR NETWORK.

Warning: p4d-watch-admin.pl is a privileged process that runs as a Perforce superuser. It automatically updates the Perforce protections table and Perforce groups. p4d-watch.pl sees every update to your Perforce database. Test and review this code before trusting it on your system.

Warning: Review the access rights to p4d-watch-admin.pl and p4d-watch.pl. Anyone with access to these files has complete, automatic control of your Perforce installation.

Warning: p4d-watch-admin.pl automatically syncs files. With the appropriate permissions, it can modify any file on your network.

Warning: When you add p4d-protect.txt and p4d-watch.cfg to your depot, review their access rights. Anyone with access rights to these files has complete control of your Perforce installation.

Warning: p4d-watch is not user tested. Although it works successfully in my environment, it may not work in yours. Please report problems to bradb@shore.net.

» Installation

To test and install p4d-watch:

  1. Please read and understand this documentation before installing p4d-watch.

  2. You will need Perl with the modules GetOpt::Long, Time::localtime, and IPC::Open2.

  3. Your servers will need SSH with approved access for your userid.

  4. Unpack p4d-watch.zip into a directory on your Perforce server

  5. Edit p4d-watch.cfg to match your depot and server names,

  6. Locate your journal file (e.g., /var/perforce/journal)

  7. Run p4d-watch.pl in the background

    ./p4d-watch.pl --journal /var/perforce/journal --follow &

  8. Update a file that is matched by p4d-watch.cfg

  9. Look at p4d-watch.log. It should record the corresponding sync event. If not, check p4d-watch.cfg

  10. Run p4d-watch-admin.pl

    ./p4d-watch.pl --change 0

  11. Look at p4d-watch-event.log. It should record the corresponding 'p4 sync'. Check for errors and retry if necessary.

  12. Run p4d-watch-admin.pl in the background

    ./p4d-watch.pl --follow &

  13. Changes to your depot are automatically sync'd.

  14. Create p4d-protect.txt and check it into your depot. Use the included p4d-protect.txt as a model. Use the output of 'p4 protect -o' for your permissions. You can remove the leading indents and document your protection policies.

  15. Review your p4d-protect.txt. Mistakes here can open your depot to unauthorized access.

  16. Edit p4d-watch.cfg and turn on the p4d-protect event,

  17. Stop and restart the p4d-watch.pl process.

  18. Submit a modified p4d-protect.txt. Check p4d-watch.log and p4d-watch-admin.log. They should record the corresponding protect event. Check the output of 'p4 protect -o'. It should match your modified p4d-protect.txt.

  19. Similarly, set up p4d-group events using p4d-group.txt as a template. Check the output of 'p4 group -o'.

  20. Check in p4d-watch.cfg and enable p4d-newwatch events. If set up correctly, updates to p4d-watch.cfg will automatically update p4d-watch.pl.

  21. Decide on the official location of the p4d-watch code and log files. For example, use a 'triggers' subdirectory of your Perforce server for p4d-watch.pl, p4d-watch-admin.pl, and p4d-watch.cfg. Use your Perforce log directory for p4d-watch.log and p4d-watch-admin.log.

  22. Ask a sysadmin to edit and install p4d-watch.d in your /etc/init.d directory [Unix systems]. This will start p4d-watch on system boot. Windows users can probably set up p4d-watch as a service [Please send instructions].

» p4d-watch.cfg

p4d-watch.cfg defines the events for p4d-watch.pl. Perforce records each file of a changeset in its db.revcx table. When p4d-watch.pl sees an update to the db.revcx table, it reads each line of p4d-watch.cfg. If the filename matches a filespec in p4d-watch.cfg, p4d-watch.pl records the corresponding event in p4d-watch.log.

The format for p4d-watch.cfg is

    Filespec Type Event Args
For example the following line watches for submits to //qa/web/main/... When a submit occurs, p4d-watch-admin.pl executes 'p4 -c road-atlas-web sync //qa/web/main/...' on 'atlas'.
    //qa/web/main/...  once p4-sync atlas@road-atlas-www@$filespec

The Types for p4d-watch.cfg are:

The Events for p4d-watch.cfg are:

The Args for p4d-watch.cfg may use these variables:

» p4d-protect.txt and p4d-group.txt

p4d-watch defines Perforce protections with text files under Perforce control. The p4d-watch distribution includes two example files.

p4d-protect.txt is a text file under Perforce control. It defines the protection table for p4d. p4d-watch-admin.pl updates the protection table when it sees event 'p4d-protect'. //user is automatically added to the protections. Use '#' for comments. Indentation is ignored.

p4d-group.txt is a text file under Perforce control. It defines the group 'p4d-group' for p4d. p4d-watch-admin.pl updates the group when it sees event p4d-group. The DepotFile must define a Group with the same prefix. If missing, sets MaxResults and MaxScanRows from p4d-watch-admin.pl. Use '#' for comments. Uses the same indentation and fields as 'p4 group'.

» Enhancements

Suggestions for enhancing p4d-watch:

Introduction  ::  Warnings  ::  Installation  ::  p4d-watch.cfg  ::  p4d-protect/p4d-group.txt  ::  Enhancements