Introduction :: Warnings :: Installation :: p4d-watch.cfg :: p4d-protect/p4d-group.txt :: Enhancements
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
- Automatically sync a web site when the Perforce depot changes.
- Define Perforce protections with a text file in the Perforce depot
- Define Perforce groups by text files in the Perforce depot
- Allow individual users to control a Perforce group's membership.
- Automatically sync a file without creating a clientspec.
- 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 $
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.
To test and install p4d-watch:
- Please read and understand this documentation before installing p4d-watch.
- You will need Perl with the modules GetOpt::Long, Time::localtime, and IPC::Open2.
- Your servers will need SSH with approved access for your userid.
- Unpack p4d-watch.zip into a directory on your Perforce server
- Edit p4d-watch.cfg to match your depot and server names,
- Locate your journal file (e.g., /var/perforce/journal)
- Run p4d-watch.pl in the background
./p4d-watch.pl --journal /var/perforce/journal --follow &
- Update a file that is matched by p4d-watch.cfg
- Look at p4d-watch.log. It should record the corresponding sync event. If not, check p4d-watch.cfg
- Run p4d-watch-admin.pl
./p4d-watch.pl --change 0
- Look at p4d-watch-event.log. It should record the corresponding 'p4 sync'. Check for errors and retry if necessary.
- Run p4d-watch-admin.pl in the background
./p4d-watch.pl --follow &
- Changes to your depot are automatically sync'd.
- 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.
- Review your p4d-protect.txt. Mistakes here can open your depot to unauthorized access.
- Edit p4d-watch.cfg and turn on the p4d-protect event,
- Stop and restart the p4d-watch.pl process.
- 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.
- Similarly, set up p4d-group events using p4d-group.txt as a template. Check the output of 'p4 group -o'.
- 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.
- 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.
- 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 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 ArgsFor 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@$filespecThe Types for p4d-watch.cfg are:
- all -- Generate an event for all files that match Filespec
- once -- Generate an event for the first matching file
- skip -- Skip the remaining Filespecs in p4d-watch.cfg
The Events for p4d-watch.cfg are:
- p4d-newwatch DepotFile -- Read a new p4d-watch.cfg
- p4d-print DepotFile@File -- Execute p4 print -q Depotfile >File
- p4d-protect DepotFile -- Set p4 protect from File.
- p4d-group DepotFile -- Set p4 group from DepotFile.
- p4-sync host@clientspec@args -- Execute 'p4 -c clientspec sync args' on 'host'
The Args for p4d-watch.cfg may use these variables:
- $filespec -- The corresponding Filespec from p4d-watch.cfg
- $depotfile -- The matched file in the changeset
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'.
Suggestions for enhancing p4d-watch:
- Special case 'localhost' for local p4d-sync events.
- Move the default ScanMaxRows and MaxResults from p4d-watch-admin.pl to p4d-watch.cfg. Update all groups if the default changes.
- Add a host field to event p4d-print (call it p4-print). It allows the automatic update of files without defining a clientspec.
- Log uses of 'p4 protect' and 'p4 group'
- Highlight errors reported by p4 protect and p4 group. Currently, errors are recorded in p4d-watch-admin.log.
- Identify other interesting events in p4d's journal file.
- Trigger other actions.
Introduction :: Warnings :: Installation :: p4d-watch.cfg :: p4d-protect/p4d-group.txt :: Enhancements