man/man5/fswatch.conf.5

.Dd March 31, 2006
.Dt FSWATCH.CONF 5
.Os
.Sh NAME
.Nm fswatch.conf
.Nd fswatch configuration file syntax
.Sh DESCRIPTION
you can set which files (and directories) should be checked and what kind
of information should be collected. you can define any settings on any level
in a file tree regardless wether you define other settings on a higher or a lower
level. it works because fswatch traverses an entrie file system but checks
only selected part.
.Pp
a syntax of configuration file was designed in such a way that it is possible
to meet this need.
.Sh A FILE STRUCTURE
a configuration file is built from <nodes>. a <node> defines path to directory.
each <node> is built from <entries>. each
<entry> defines which files (in a directory specified in a <node>)
should be checked and what information
should be collected.
.Pp
fswbuild traverses the whole file system and for every file it searches an <entry>.
<entries> are being checked from the beginning to the
end and checking is stopped when the first matching entry is found. so the
order of entries matters.
.Pp
empty lines, lines beginning with a space (' '), a
tabulator (' '), a hash sign ('#'), a semicolon (';')  are ignored.
a config file structure is as follows:
.Pp
.nf
--begin--
node_1
entry_1
entry_2
 ...
entry_n1
.Pp
node_2
entry_1
entry_2
 ...
entry_n2
.Pp
 ...
.Pp
node_N
entry_1
entry_2
 ...
entry_nN
--end--
.fi
.Pp
.Sh NODES
in <nodes> you define a directory (a full path) and then you can define
<entries>
for this directory. in <nodes> you can define inheritance type. a <node> syntax is
as follows:
.Pp
.nf
@_INHERITANCE_:_DIRECTORY_
.fi
.Pp
where _INHERITANCE_ is one of three words NO, PRE, POST and _DIRECTORY_ is
a full path to a directory. entries can be inherited only from a nearest node
on a lower level in a directory tree. NO means without any inheritance. PRE or
POST means inheritance by adding inherited entries to begin or to end a node
respectively.
.Pp
.Sh ENTRIES
<entries> define which files (and directiories) should be checked and what information
should be collected. an <entry> syntax in a configuration file is as follows:
.Pp
.nf
+_MASK_:_OPTIONS_
name:_NAME_
namere:_NAMERE_
uid:_UID_
gid:_GID_
type:_TYPE_
.fi
.Pp
_MASK_ defines what information should be collected. it
can consist of the following signs: i, l, u, g, m, s, f, t, c, N, F, C ;
i (inode), m (mode), l (links), u (uid), g (gid), t (ctime), s (size),
f (flags), c (checksum). N means NOT to check anything. F means to check
everything. C is equivalent to the following signs: imlugf ;
.Pp
_OPTIONS_ can consist of the following signs: I, S ; entries marked with "I"
sign can be inherited. S functions only within a directory and means NOT to
traverse inside. you can use it to speed up work if a directory is a network
file system or a directory with a huge number of files and subdirectories which
you do NOT want to check.
.Pp
lines beginning with key words: name, namere, uid, gid, type ; define which
files (and directories) should be matched. you don`t have to use all these key
words. each key word can be used more than once. there is logical "or"
between the same type key words. there is logical
"and" between different type key words. key words: name, namere ; are the
same type.
.Pp
_NAME_ is a file name. you can use a very simple regular expression (see below).
.Pp
_NAMRE_ is an extended regular expression which defines a file name. the
syntax is the same as in
.Xr grep 1 . (it is available only if you compile it with --enable-regex
option).
.Pp
_UID_, _GID_ define uid (owner) and gid (group) of a file respectively. you
can use a simple regular expression (see below).
.Pp
_TYPE_ defines file types. you can set the following signs: f, c, d, b, r, l,
s ; f (fifo), c (special character),
d (directory), b (block special), r (regular), l (symbolic link), s (socket).
.Pp
.Sh SIMPLE REGULAR EXRESSION (NAME)
you can use simple regular expressions in lines beginning with name key word. besides
all letters and signs used in path names you can use: *, ? ; (an asterisk and
a question mark).
a question mark means any letter (or sign), an asterisk means zero or more letters
(or signs). '?' (a question mark) can stand before '*' (asterisk) but it can NOT stand
after '*'. there can NOT be two or more '*' next to each other. you can set one or
more '?' next to each other, though.
.Pp
.nf
e.g.:
abc
abc*
*abc?
a*b*c
a?*b??*c*
.fi
.Pp
if you do NOT comply with these rules entry matching will be working indefinitely.
.Pp
.Sh SIMPLE REGULAR EXRESSION (UID, GID)
there are four types of regular expressions. they are the same for uid and
gid.
.Pp
* a simple number id
.nf
id
.Pp
e.g.:
uid:1010
gid:1010
.Pp
* id <= numbers
id-
.Pp
.e.g.:
uid:1000-
gid:1000-
.Pp
* numbers <= id
-id
.e.g.:
uid:-1000
gid:-1000
.Pp
* id1 <= numbers <= id2
id1-id2
.Pp
e.g.:
uid:1000-2000
gid:1000-2000
.fi
.Pp
.Sh INHERITACE BY NODES
you can set which entries should be inherited by next nodes (the nearest node at a higher
level in a file
tree). you have to do two things. firstly, you have to mark entries you want to be
inherited as "I" (options "I"). secondly, in an inheriting node you have to set what kind of
inheritance you want to use (PRE or POST). PRE adds inherited entries at the beginning
and POST at the end respectively. NO means without any inheritance.
.Pp
e.g.:
.nf
--begin--
@NO:/dira
+N
name:file1
name:file2
+F:I
name:file3
+N
uid:1500-
+F:I
type:r
.Pp
@PRE:/dira/dirb/dirc
+ugfm
name:file4
--end--
.fi
.Pp
the second <node> inherits ("PRE") from a <node> (on a lower level in a directory
tree). result (for /dira/dirb/dirc):
.Pp
.nf
+F:I
name:file3
+F:I
type:r
+ugfm
name:file4
.fi
.Pp
.Sh INHERITANCE BY SUBDIRECTORIES
it goes without saying you don`t want to define node settings for each directory in
your file system because most settings for directories are the same. for directories
you didn`t create, node settings are inherited from the nearest node
(entries with "I" option) on a lower level in
a file tree.
.Pp
.Xr fswbuild 1
works in a following way: it traverses a file system (directories). it
enters a directory and checks:
.Pp
if <node> (for a directory) exists then; for every file
in that directory fswbuild searches a matching <entry> (from all <entries> in
that <node>).
.Pp
if <node> (for a directory) doesn`t exist then: fswbuild
searches the nearest <node> (the nearest in a directory tree) and then: for
every file in that directory fswbuild searches a matching <entry> (from all
<entries> with option "I" in a found <node>).
.Pp
.Sh EXAMPLES
.Pp
example 1
.Pp
.nf
 --begin--
@NO:/
+F
name:*
 --end--
.fi
.Pp
it matches all files in "/" which fulfill ALL conditions:
.nf
* file name is "*" (all names)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 2
.Pp
.nf
 --begin--
@NO:/
+F
name:a
name:b
 --end--
.fi
.Pp
it matches all files in "/" which fulfill ALL conditions:
.nf
* file name is "a" or "b"
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 3
.Pp
.nf
 --begin--
@NO:/
+F
name:a
name:b
name:c
type:r
 --end--
.fi
.Pp
it matches all files in "/" which fulfill ALL conditions:
.nf
* file name is "a" or "b" or "c"
* file type is "r" (regular)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 4
.Pp
.nf
 --begin--
@NO:/
+ugmtc
name:a
name:b
name:c
uid:1001
uid:2000-4000
type:rd
 --end--
.fi
.Pp
it matches all files in "/" which fulfill ALL conditions:
.nf
* file name is "a" or "b" or "c"
* uid (file owner id) is "1001" or in "2000-4000"
* file type is "r" (regular) or "d" (directory)
.fi
fswbuild will collect information ("ugmtc" means: uid, gid,
mode, ctime, checksum) for all matched files.
.Pp
example 5
.Pp
.nf
 --begin--
@NO:/
+N
uid:2000-4000
+F
name:*
 --end--
.fi
.Pp
there are two entries. the first entry matches all files in
"/" which fulfill ALL conditions:
.nf
* uid (file owner id) is in "2000-4000"
.fi
fswbuild will collect information ("N" means: no information)
for all matched files.
.Pp
if file doesn`t match the first entry then the second entry
is checked.
.Pp
the second entry matches all files in "/" which fulfill ALL
conditions:
.nf
* file name is "*" (all names)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 6
.Pp
.nf
 --begin--
@NO:/
+N
uid:2000-4000
+C
name:tmp
name:run
type:d
+F
name:*
 --end--
.fi
.Pp
there are three entries. the first entry matches all files in
"/" which fulfill ALL conditions:
.nf
* uid (file owner id) is in "2000-4000"
.fi
fswbuild will collect information ("N" means: no information)
for all matched files.
.Pp
if file doesn`t match the first entry then the second entry
is checked.
.Pp
the second entry matches all files in "/" which fulfill ALL
conditions:
.nf
* name is "tmp" or "run"
* type is "d" (directory)
.fi
fswbuild will collect information ("C" means: inode, links,
uid, gid, mode, flags) for all matched files.
.Pp
if file doesn`t match the second entry then the third entry
is checked.
.Pp
the third entry matches all files in "/" which fulfill ALL
conditions:
.nf
* file name is "*" (all names)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 7
.Pp
.nf
 --begin--
@NO:/
+F
name:???
type:d
 --end--
.fi
.Pp
it matches all files in "/" which fulfill ALL conditions:
.nf
* file name is "???" (it contains exactly three signs)
* file type is "d" (directory)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 8
.Pp
.nf
 --begin--
@NO:/
+F
name:???
+F
type:d
 --end--
.fi
.Pp
there are two entries. the first entry matches all files in
"/" which fulfill ALL conditions:
.nf
* file name is "???" (it contains exactly three signs)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
if file doesn`t match the first entry then the second entry
is checked.
.Pp
the second entry matches all files in "/" which fulfill ALL conditions:
.nf
* file type is "d" (directory)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 9
.Pp
.nf
 --begin--
@NO:/dir1/dir2
+F
name:*
 --end--
.fi
.Pp
it matches all files in "/dir1/dir2" which fulfill ALL conditions:
.nf
* file name is "*" (all names)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 10
.Pp
.nf
 --begin--
@NO:/dir1/dir2
+F:I
name:*
 --end--
.fi
.Pp
it matches all files in "/dir1/dir2" and all subdirectories (
because of "I" options - inheritance by subdirectories) which
fulfill ALL conditions:
.nf
* file name is "*" (all names)
.fi
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
.Pp
example 11
.Pp
.nf
 --begin--
@NO:/dir1/dir2
+N
name:tmp
+F:I
name:*
 --end--
.fi
.Pp
there are two entries. the first can match files only in
"/dir1/dir2". the second (because of "I" option) can match
files in "/dir1/dir2" and all subdirectories (inheratance
by subdirectories).
.Pp
example 12
.Pp
.nf
 --begin--
@NO:/dir1
+F
name:dir2
.Pp
@NO:/dir1/dir2
+F:I
name:*
 --end--
.fi
.Pp
there are two nodes. the first node sets that all information
("F") should be collected for file "/dir1/dir2". the second
node sets that all information ("F") should be collected for
files in "/dir1/dir2" directory and in its subdirectories
(because of "I" option).
.Pp
example 13
.Pp
.nf
 --begin--
@NO:/
+N:S
name:dir1
name:dir2
+F:I
name:*
 --end--
.fi
.Pp
the first entry has "S" option. it means fswbuild will NOT go into
"/dir1" and "/dir2" directories and all its subdirectories. it
means fswbuild will NOT collect any information for files in this
directories. because of "N" it will NOT collect any information
for file "/dir1" and "/dir2". for other files in "/" fswbuild will
collect all information ("F") and because of "I" option it will
collect all information for all files in its subdirectories.
.Pp
there is an equivalent example below:
.Pp
.nf
 --begin--
@NO:/
+N
name:dir1
name:dir2
+F:I
name:*
.Pp
@NO:/dir1
+N:I
name:*
.Pp
@NO:/dir2
+N:I
name:*
 --end--
.fi
.Pp
.Sh SEE ALSO
.Xr fswbuild 1 ,
.Xr fswcmp 1 ,
.Xr fswshow 1 ,
.Xr fswconf 1