<html>
<head>
<title>p4d-watch -- post-submit triggers</title>
</head>
<body>
<h1><a name=TOP>p4d-watch</a> -- post-submit triggers</h1>
<blockquote>
<a href=#intro>Introduction</a> ::
<a href=#warning>Warnings</a> ::
<a href=#install>Installation</a> ::
<a href=#cfg>p4d-watch.cfg</a> ::
<a href=#protect>p4d-protect/p4d-group.txt</a> ::
<a href=#enhance>Enhancements</a>
</blockquote><h2><a href="#TOP"></a>
<a name=intro>Introduction</a>
</h2><blockquote>
The Perforce <i>journal</i> 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.
<p>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.
<p>Use p4d-watch to
<ol>
<li>Automatically sync a web site when the Perforce depot changes.
<li>Define Perforce protections with a text file in the Perforce depot
<li>Define Perforce groups by text files in the Perforce depot
<li>Allow individual users to control a Perforce group's membership.
<li>Automatically sync a file without creating a clientspec.
<li>Define write permissions for //user/...
</ol>
<p><b>p4d-watch</b> 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</p>
<p><b>p4d-watch.pl</b> 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.
<p><b>p4d-watch-admin.pl</b> 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.
<p>THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY, SUPPORT, OR COPYRIGHT.
<p>Send questions and comments to <a href=mailto:bradb@shore.net>bradb@shore.net</a>.
<p>Many thanks to <a href=http://www.atg.com>Art Technology Group</a> for
supporting this work.
<p>$Server: public.perforce.com:1666 $$Id: //guest/brad_barber/p4d-watch/main/p4d-watch.html#4 $
<br>$Date: 2002/07/09 $$Change: 1941 $$Author: brad_barber $
</blockquote><h2><a href="#TOP"></a>
<a name=warning>Warnings</a>
</h2><blockquote>
<p>BE CAREFUL -- THIS CODE HAS COMPLETE ACCESS TO YOUR PERFORCE DEPOT. IT MAY MODIFY
ANY FILE ON YOUR NETWORK.
<p><b>Warning:</b> 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.
<p><b>Warning:</b> 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.
<p><b>Warning:</b> p4d-watch-admin.pl automatically syncs
files. With the appropriate permissions, it can modify
any file on your network.
<p><b>Warning:</b> 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.
<p><b>Warning:</b> p4d-watch is not user tested. Although
it works successfully in my environment, it may not work in
yours. Please report
problems to <a href=mailto:bradb@shore.net>bradb@shore.net</a>.
</blockquote><h2><a href="#TOP"></a>
<a name=install>Installation</a>
</h2><blockquote>
<p>To test and install p4d-watch:
<ol>
<li>Please read and understand this documentation before installing p4d-watch.
<p>
<li>You will need Perl with the modules GetOpt::Long, Time::localtime,
and IPC::Open2.
<p>
<li>Your servers will need SSH with approved access for your userid.
<p>
<li>Unpack p4d-watch.zip into a directory on your Perforce server
<p>
<li>Edit p4d-watch.cfg to match your depot and server names,
<p>
<li>Locate your journal file (e.g., /var/perforce/journal)
<p>
<li>Run p4d-watch.pl in the background
<p>
./p4d-watch.pl --journal /var/perforce/journal --follow &
<li>Update a file that is matched by p4d-watch.cfg
<p>
<li>Look at p4d-watch.log. It should record the corresponding
sync event. If not, check p4d-watch.cfg
<p>
<li>Run p4d-watch-admin.pl
<p>
./p4d-watch.pl --change 0
<li>Look at p4d-watch-event.log. It should record the
corresponding 'p4 sync'. Check for errors and retry
if necessary.
<p>
<li>Run p4d-watch-admin.pl in the background
<p>
./p4d-watch.pl --follow &
<li>Changes to your depot are automatically sync'd.
<p>
<li>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.
<p>
<li>Review your p4d-protect.txt. Mistakes here can open your
depot to unauthorized access.
<p>
<li>Edit p4d-watch.cfg and turn on the p4d-protect event,
<p>
<li>Stop and restart the p4d-watch.pl process.
<p>
<li>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.
<p>
<li>Similarly, set up p4d-group events using p4d-group.txt
as a template. Check the output of 'p4 group -o'.
<p>
<li>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.
<p>
<li>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.
<p>
<li>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].
<p>
</ol>
</blockquote><h2><a href="#TOP"></a>
<a name=cfg>p4d-watch.cfg</a>
</h2><blockquote>
<p><b>p4d-watch.cfg</b> 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.
<p>The format for p4d-watch.cfg is
<pre>
Filespec Type Event Args
</pre>
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'.
<pre>
//qa/web/main/... once p4-sync atlas@road-atlas-www@$filespec
</pre>
<p>The Types for p4d-watch.cfg are:
<ul>
<li>all -- Generate an event for all files that match Filespec
<li>once -- Generate an event for the first matching file
<li>skip -- Skip the remaining Filespecs in p4d-watch.cfg
</ul>
<p>The Events for p4d-watch.cfg are:
<ul>
<li>p4d-newwatch DepotFile -- Read a new p4d-watch.cfg
<li>p4d-print DepotFile@File -- Execute p4 print -q Depotfile >File
<li>p4d-protect DepotFile -- Set p4 protect from File.
<li>p4d-group DepotFile -- Set p4 group from DepotFile.
<li>p4-sync host@clientspec@args -- Execute 'p4 -c clientspec sync args' on 'host'
</ul>
<p>The Args for p4d-watch.cfg may use these variables:
<ul>
<li>$filespec -- The corresponding Filespec from p4d-watch.cfg
<li>$depotfile -- The matched file in the changeset
</ul>
</blockquote><h2><a href="#TOP"></a>
<a name=protect>p4d-protect.txt</a> and p4d-group.txt
</h2><blockquote>
p4d-watch defines Perforce protections
with text files under Perforce control. The
p4d-watch distribution includes two example files.
<p><b>p4d-protect.txt</b> 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.
<p><b>p4d-group.txt</b> 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'.
</blockquote><h2><a href="#TOP"></a>
<a name=enhance>Enhancements</a>
</h2><blockquote>
<p>Suggestions for enhancing p4d-watch:
<ul>
<li>Special case 'localhost' for local p4d-sync events.
<p>
<li>Move the default ScanMaxRows and MaxResults from p4d-watch-admin.pl
to p4d-watch.cfg.
Update all groups if the default changes.
<p>
<li>Add a host field to event p4d-print (call it p4-print). It allows the
automatic update of files without defining a clientspec.
<p>
<li>Log uses of 'p4 protect' and 'p4 group'
<p>
<li>Highlight errors reported by p4 protect and p4 group.
Currently, errors are recorded in p4d-watch-admin.log.
<p>
<li>Identify other interesting events in p4d's journal file.
<p>
<li>Trigger other actions.
</ul>
</blockquote>
<p>
<a href=#intro>Introduction</a> ::
<a href=#warning>Warnings</a> ::
<a href=#install>Installation</a> ::
<a href=#cfg>p4d-watch.cfg</a> ::
<a href=#protect>p4d-protect/p4d-group.txt</a> ::
<a href=#enhance>Enhancements</a>
</body>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #4 | 1941 | brad_barber | post-submit triggers | ||
| #3 | 1940 | brad_barber | ktext | ||
| #2 | 1939 | brad_barber |
Initial release. Add $Change$. Switch to /usr/local/bin/perl Updated documentation with index header/footer Warning section |
||
| #1 | 1923 | brad_barber | Initial version. |