watchtab.5 (3296B)
1 .\" Copyright (c) 2015, Natacha Porté 2 .\" 3 .\" Permission to use, copy, modify, and distribute this software for any 4 .\" purpose with or without fee is hereby granted, provided that the above 5 .\" copyright notice and this permission notice appear in all copies. 6 .\" 7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14 .Dd October 20, 2015 15 .Dt WATCHTAB 5 16 .Os 17 .Sh NAME 18 .Nm watchtab 19 .Nd tables for driving filewatcherd 20 .Sh DESCRIPTION 21 A 22 .Nm 23 file contains instructions to the 24 .Xr filewatcherd 8 25 daemon of the general form: ``run this command when these events happen 26 to the file at this path''. 27 .Pp 28 Blank lines and leading spaces and tabs are ignored. 29 Lines whose first non-space character is a pound-sign (#) are comments, 30 and are ignored. Note that comments are not allowed on the same line as 31 .Nm 32 commands, since they will be taken to be part of the command. 33 Similarly, comments are not allowed on the same line as 34 environment variable settings. 35 .Pp 36 An active line of a 37 .Nm 38 will be either an environment setting or a command. 39 An environment setting is of the form 40 .Bd -literal 41 name = value 42 .Ed 43 .Pp 44 where the spaces around the equal-sign (=) are optional, and any subsequent 45 non-leading spaces in 46 .Em value 47 will be part of the value assigned to 48 .Em name . 49 Note that 50 .Em name 51 cannot contain any blackslash or tabulation. 52 .Pp 53 Several environment variables are set up automatically by the 54 .Xr filewatcherd 8 55 daemon. 56 .Ev LOGNAME 57 and 58 .Ev USER 59 are set to the command user, 60 .Ev HOME 61 is set to the home directory of the command user, unless explicitly overriden. 62 .Ev TRIGGER 63 is set to the path that has triggered the command execution. 64 .Pp 65 The format of a 66 .Nm 67 command is a tabulation-separated sequence of fields, interpreted as follow: 68 .Bl -tag -width command 69 .It path 70 Path of the file to watch. 71 .It events 72 Set of events which trigger the command. It can either be a single 73 star-sign (*), or a punctuation-separated list of names among: 74 DELETE, WRITE, EXTEND, ATTRIB, LINK, RENAME and REVOKE. Their meaning is 75 defined in 76 .Xr kqueue 2 77 for 78 .Va fflags 79 for EVFILT_VNODE. 80 .It delay 81 Number of seconds, allowing a decimal point, between the trigger and when 82 the command is actually run. 83 .It user 84 User, and optionally group preceded by a colon sign (:), to change to 85 before running the command. 86 .It chroot 87 Path of a directory in which to chroot before running the command. 88 .It command 89 The command to run. 90 .El 91 .Pp 92 When less than 6 fields are given in a command line, the 93 .Va chroot 94 value is considered omitted, and chroot will be performed. 95 When less than 5 fields are given, the 96 .Va user 97 value is considered omitted, and no setuid or setgid will be performed. 98 When less than 4 fields are given, the 99 .Va delay 100 value is considered as zero. 101 It is an error to provide less than 3 fields. 102 .Sh SEE ALSO 103 .Xr kqueue 2 , 104 .Xr crontab 5 , 105 .Xr filewatcherd 8