Loading...
Helix SwarmHelix Swarm
Loading...

p4d-watch.html

  • //
  • guest/
  • brad_barber/
  • p4d-watch/
  • main/
  • p4d-watch.html #4
  • View
  • Commits
  • Open Download .zip Download (10 KB) 
  1. <html>
  2. <head>
  3. <title>p4d-watch -- post-submit triggers</title>
  4. </head>
  5. <body>
  6. <h1><a name=TOP>p4d-watch</a> -- post-submit triggers</h1>
  7. <blockquote>
  8.  
  9. <a href=#intro>Introduction</a> &nbsp;::&nbsp;
  10. <a href=#warning>Warnings</a> &nbsp;::&nbsp;
  11. <a href=#install>Installation</a> &nbsp;::&nbsp;
  12. <a href=#cfg>p4d-watch.cfg</a> &nbsp;::&nbsp;
  13. <a href=#protect>p4d-protect/p4d-group.txt</a> &nbsp;::&nbsp;
  14. <a href=#enhance>Enhancements</a>
  15.  
  16. </blockquote><h2><a href="#TOP"></a>
  17. <a name=intro>Introduction</a>
  18. </h2><blockquote>
  19.  
  20. The Perforce <i>journal</i> records all updates to the Perforce 
  21. database.  P4d-watch monitors the journal for interesting
  22. events.  For example, if someone submits a change to //road/Perforce/main/protections/p4d-protect.txt,
  23. p4d-watch can automatically update Perforce's protection table.
  24.  
  25. <p>P4d-watch is like a fast Perforce daemon.  Perforce daemons detect events
  26. whenever they poll the server, typically every one to five minutes.  
  27. P4d-watch responds to events within a second or two.
  28.  
  29. <p>Use p4d-watch to 
  30. <ol>
  31. <li>Automatically sync a web site when the Perforce depot changes.
  32. <li>Define Perforce protections with a text file in the Perforce depot
  33. <li>Define Perforce groups by text files in the Perforce depot
  34. <li>Allow individual users to control a Perforce group's membership.
  35. <li>Automatically sync a file without creating a clientspec.
  36. <li>Define write permissions for //user/...
  37. </ol>
  38.  
  39. <p><b>p4d-watch</b> consists of p4d-watch.pl, p4d-watch-admin.pl, p4d-watch.cfg, and
  40. p4d-watch.d.  It includes sample files for p4d-protect.txt and p4d-group.txt</p>
  41.  
  42. <p><b>p4d-watch.pl</b> reads Perforce's journal file
  43. and writes events to pd-watch.log.  It watches for updates to Perforce's db.change and
  44. db.revcx tables.  It writes events as defined by p4d-watch.cfg.  It 
  45. recreates p4d-watch.log if the old one is
  46. deleted or renamed.  See 'p4d-watch.pl --help' for
  47. additional options.
  48.  
  49. <p><b>p4d-watch-admin.pl</b> processes events from p4d-watch.log.
  50. It logs the result of each event to p4d-watch-admin.log.  It 
  51. recreates p4d-watch-admin.log if the old one is
  52. deleted or renamed.  See 'p4d-watch.pl --help' for
  53. additional options.
  54.  
  55. <p>THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY, SUPPORT, OR COPYRIGHT.
  56.  
  57. <p>Send questions and comments to <a href=mailto:bradb@shore.net>bradb@shore.net</a>.
  58.  
  59. <p>Many thanks to <a href=http://www.atg.com>Art Technology Group</a> for 
  60. supporting this work.
  61.  
  62. <p>$Server: public.perforce.com:1666 $$Id: //guest/brad_barber/p4d-watch/main/p4d-watch.html#4 $
  63. <br>$Date: 2002/07/09 $$Change: 1941 $$Author: brad_barber $
  64.  
  65. </blockquote><h2><a href="#TOP"></a>
  66. <a name=warning>Warnings</a>
  67. </h2><blockquote>
  68.  
  69. <p>BE CAREFUL -- THIS CODE HAS COMPLETE ACCESS TO YOUR PERFORCE DEPOT.  IT MAY MODIFY 
  70. ANY FILE ON YOUR NETWORK. 
  71.  
  72. <p><b>Warning:</b>  p4d-watch-admin.pl is a privileged process that
  73. runs as a Perforce superuser.  It automatically updates
  74. the Perforce protections table and Perforce groups. p4d-watch.pl sees 
  75. every update to your Perforce database.  Test and review this
  76. code before trusting it on your system.  
  77.  
  78. <p><b>Warning:</b>  Review the access rights to p4d-watch-admin.pl
  79. and p4d-watch.pl.  Anyone with access to these files has 
  80. complete, automatic control of your Perforce installation.
  81.  
  82. <p><b>Warning:</b>  p4d-watch-admin.pl automatically syncs
  83. files.  With the appropriate permissions, it can modify 
  84. any file on your network.
  85.  
  86. <p><b>Warning:</b>  When you add p4d-protect.txt and p4d-watch.cfg
  87. to your depot, review their access rights.  Anyone with 
  88. access rights to these files has complete control of your
  89. Perforce installation.
  90.  
  91. <p><b>Warning:</b>  p4d-watch is not user tested.  Although
  92. it works successfully in my environment, it may not work in
  93. yours.  Please report 
  94. problems to <a href=mailto:bradb@shore.net>bradb@shore.net</a>.
  95.  
  96.  
  97. </blockquote><h2><a href="#TOP"></a>
  98. <a name=install>Installation</a>
  99. </h2><blockquote>
  100.  
  101. <p>To test and install p4d-watch:
  102. <ol>
  103. <li>Please read and understand this documentation before installing p4d-watch.
  104. <p>
  105. <li>You will need Perl with the modules GetOpt::Long, Time::localtime,
  106. and IPC::Open2.
  107. <p>
  108. <li>Your servers will need SSH with approved access for your userid.
  109. <p>
  110. <li>Unpack p4d-watch.zip into a directory on your Perforce server
  111. <p>
  112. <li>Edit p4d-watch.cfg to match your depot and server names, 
  113. <p>
  114. <li>Locate your journal file (e.g., /var/perforce/journal)
  115. <p>
  116. <li>Run p4d-watch.pl in the background
  117. <p>
  118. ./p4d-watch.pl --journal /var/perforce/journal --follow &
  119. <li>Update a file that is matched by p4d-watch.cfg
  120. <p>
  121. <li>Look at p4d-watch.log.  It should record the corresponding
  122. sync event.  If not, check p4d-watch.cfg
  123. <p>
  124. <li>Run p4d-watch-admin.pl
  125. <p>
  126. ./p4d-watch.pl --change 0
  127. <li>Look at p4d-watch-event.log.  It should record the
  128. corresponding 'p4 sync'.  Check for errors and retry
  129. if necessary.
  130. <p>
  131. <li>Run p4d-watch-admin.pl in the background
  132. <p>
  133. ./p4d-watch.pl --follow &
  134. <li>Changes to your depot are automatically sync'd.
  135. <p>
  136. <li>Create p4d-protect.txt and check it into your depot.
  137. Use the included p4d-protect.txt as a model.  Use the output of
  138. 'p4 protect -o' for your permissions.  You can remove the 
  139. leading indents and document your protection policies.
  140. <p>
  141. <li>Review your p4d-protect.txt.  Mistakes here can open your
  142. depot to unauthorized access.
  143. <p>
  144. <li>Edit p4d-watch.cfg and turn on the p4d-protect event,
  145. <p>
  146. <li>Stop and restart the p4d-watch.pl process. 
  147. <p>
  148. <li>Submit a modified p4d-protect.txt.  Check p4d-watch.log and 
  149. p4d-watch-admin.log.  They should record the corresponding
  150. protect event.  Check the output of 'p4 protect -o'.  It
  151. should match your modified p4d-protect.txt.
  152. <p>
  153. <li>Similarly, set up p4d-group events using p4d-group.txt
  154. as a template.  Check the output of 'p4 group -o'.
  155. <p>
  156. <li>Check in p4d-watch.cfg and enable p4d-newwatch events.  If
  157. set up correctly, updates to p4d-watch.cfg will automatically
  158. update p4d-watch.pl. 
  159. <p>
  160. <li>Decide on the official location of the p4d-watch code and
  161. log files. For example, use a 'triggers' subdirectory of your Perforce server
  162. for p4d-watch.pl, p4d-watch-admin.pl, and p4d-watch.cfg.  Use your
  163. Perforce log directory
  164. for p4d-watch.log and p4d-watch-admin.log.
  165. <p>
  166. <li>Ask a sysadmin to edit and install p4d-watch.d in your 
  167. /etc/init.d directory [Unix systems].  This will start 
  168. p4d-watch on system boot.  Windows users can probably set
  169. up p4d-watch as a service [Please send instructions].
  170. <p>
  171. </ol>
  172.  
  173. </blockquote><h2><a href="#TOP"></a>
  174. <a name=cfg>p4d-watch.cfg</a>
  175. </h2><blockquote>
  176.  
  177. <p><b>p4d-watch.cfg</b> defines the events for p4d-watch.pl.
  178. Perforce records each file of a changeset in its db.revcx table.
  179. When p4d-watch.pl sees an update to the db.revcx table, it
  180. reads each line of p4d-watch.cfg.  If the filename matches a
  181. filespec in p4d-watch.cfg, p4d-watch.pl records
  182. the corresponding event in p4d-watch.log.
  183.  
  184. <p>The format for p4d-watch.cfg is 
  185. <pre>
  186.     Filespec Type Event Args
  187. </pre>
  188. For example
  189. the following line watches for submits to //qa/web/main/...  When a 
  190. submit occurs, p4d-watch-admin.pl executes 'p4 -c road-atlas-web sync //qa/web/main/...' on 'atlas'.
  191. <pre>
  192.     //qa/web/main/...  once p4-sync atlas@road-atlas-www@$filespec
  193. </pre>
  194.  
  195. <p>The Types for p4d-watch.cfg are:
  196. <ul>
  197. <li>all -- Generate an event for all files that match Filespec 
  198. <li>once -- Generate an event for the first matching file 
  199. <li>skip -- Skip the remaining Filespecs in p4d-watch.cfg
  200. </ul>
  201.  
  202. <p>The Events for p4d-watch.cfg are:
  203. <ul>
  204. <li>p4d-newwatch DepotFile -- Read a new p4d-watch.cfg
  205. <li>p4d-print DepotFile@File -- Execute p4 print -q Depotfile >File
  206. <li>p4d-protect DepotFile -- Set p4 protect from File.  
  207. <li>p4d-group DepotFile -- Set p4 group from DepotFile.  
  208. <li>p4-sync host@clientspec@args -- Execute 'p4 -c clientspec sync args' on 'host'
  209. </ul>
  210.  
  211. <p>The Args for p4d-watch.cfg may use these variables:
  212. <ul>
  213. <li>$filespec -- The corresponding Filespec from p4d-watch.cfg
  214. <li>$depotfile -- The matched file in the changeset
  215. </ul>
  216.  
  217. </blockquote><h2><a href="#TOP"></a>
  218. <a name=protect>p4d-protect.txt</a> and p4d-group.txt
  219. </h2><blockquote>
  220.  
  221. p4d-watch defines Perforce protections 
  222. with text files under Perforce control.   The 
  223. p4d-watch distribution includes two example files.
  224.  
  225. <p><b>p4d-protect.txt</b> is a text file under Perforce control.  It
  226. defines the protection table for p4d.  p4d-watch-admin.pl updates
  227. the protection table when it sees event 'p4d-protect'.
  228. //user is automatically added to the protections.    Use '#' for comments. 
  229. Indentation is ignored.
  230.  
  231. <p><b>p4d-group.txt</b> is a text file under Perforce control.  It
  232. defines the group 'p4d-group' for p4d.  p4d-watch-admin.pl updates
  233. the group when it sees event p4d-group.  The DepotFile must define a Group 
  234. with the same prefix.  If missing, sets MaxResults and MaxScanRows from p4d-watch-admin.pl.
  235. Use '#' for comments.  Uses the same indentation and fields as 'p4 group'.
  236.  
  237. </blockquote><h2><a href="#TOP"></a>
  238. <a name=enhance>Enhancements</a>
  239. </h2><blockquote>
  240.  
  241. <p>Suggestions for enhancing p4d-watch:
  242. <ul>
  243. <li>Special case 'localhost' for local p4d-sync events.
  244. <p>
  245. <li>Move the default ScanMaxRows and MaxResults from p4d-watch-admin.pl
  246. to p4d-watch.cfg.
  247. Update all groups if the default changes.
  248. <p>
  249. <li>Add a host field to event p4d-print (call it p4-print).  It allows the 
  250. automatic update of files without defining a clientspec.
  251. <p>
  252. <li>Log uses of 'p4 protect' and 'p4 group'
  253. <p>
  254. <li>Highlight errors reported by p4 protect and p4 group. 
  255. Currently, errors are recorded in p4d-watch-admin.log.
  256. <p>
  257. <li>Identify other interesting events in p4d's journal file.
  258. <p>
  259. <li>Trigger other actions.
  260. </ul>
  261.  
  262. </blockquote>
  263. <p>
  264. <a href=#intro>Introduction</a> &nbsp;::&nbsp;
  265. <a href=#warning>Warnings</a> &nbsp;::&nbsp;
  266. <a href=#install>Installation</a> &nbsp;::&nbsp;
  267. <a href=#cfg>p4d-watch.cfg</a> &nbsp;::&nbsp;
  268. <a href=#protect>p4d-protect/p4d-group.txt</a> &nbsp;::&nbsp;
  269. <a href=#enhance>Enhancements</a>
  270.  
  271. </body>
# Change User Description Committed
#4 1941 brad_barber post-submit triggers 23 years ago
#3 1940 brad_barber ktext 23 years ago
#2 1939 brad_barber Initial release. 

Add $Change$. 
Switch to /usr/local/bin/perl
Updated docum...entation with index header/footer
Warning section «		 23 years ago
#1 1923 brad_barber Initial version. 23 years ago