FSWATCH.CONF(5) BSD File Formats Manual FSWATCH.CONF(5)NAMEfswatch.conf — fswatch configuration file syntax
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.
a syntax of configuration file was designed in such a way that it is pos‐
sible to meet this need.
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.
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.
empty lines, lines beginning with a space (' '), a tabulator (' '), a
hash sign ('#'), a semicolon (';') are ignored. a config file structure
is as follows:
--begin--
node_1
entry_1
entry_2
...
entry_n1
node_2
entry_1
entry_2
...
entry_n2
...
node_N
entry_1
entry_2
...
entry_nN
--end--
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:
@_INHERITANCE_:_DIRECTORY_
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 near‐
est 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.
ENTRIES
<entries> define which files (and directiories) should be checked and
what information should be collected. an <entry> syntax in a configura‐
tion file is as follows:
+_MASK_:_OPTIONS_
name:_NAME_
namere:_NAMERE_
uid:_UID_
gid:_GID_
type:_TYPE_
_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 ;
_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 sub‐
directories which you do NOT want to check.
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.
_NAME_ is a file name. you can use a very simple regular expression (see
below).
_NAMRE_ is an extended regular expression which defines a file name. the
syntax is the same as in grep(1). (it is available only if you compile it
with --enable-regex option).
_UID_, _GID_ define uid (owner) and gid (group) of a file respectively.
you can use a simple regular expression (see below).
_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 spe‐
cial), r (regular), l (symbolic link), s (socket).
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.
e.g.:
abc
abc*
*abc?
a*b*c
a?*b??*c*
if you do NOT comply with these rules entry matching will be working
indefinitely.
SIMPLE REGULAR EXRESSION (UID, GID)
there are four types of regular expressions. they are the same for uid
and gid.
* a simple number id
id
e.g.:
uid:1010
gid:1010
* id <= numbers
id-
uid:1000-
gid:1000-
* numbers <= id
-id
uid:-1000
gid:-1000
* id1 <= numbers <= id2
id1-id2
e.g.:
uid:1000-2000
gid:1000-2000
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.
e.g.:
--begin--
@NO:/dira
+N
name:file1
name:file2
+F:I
name:file3
+N
uid:1500-
+F:I
type:r
@PRE:/dira/dirb/dirc
+ugfm
name:file4
--end--
the second <node> inherits ("PRE") from a <node> (on a lower level in a
directory tree). result (for /dira/dirb/dirc):
+F:I
name:file3
+F:I
type:r
+ugfm
name:file4
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.
fswbuild(1) works in a following way: it traverses a file system (direc‐
tories). it enters a directory and checks:
if <node> (for a directory) exists then; for every file in that directory
fswbuild searches a matching <entry> (from all <entries> in that <node>).
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>).
EXAMPLES
example 1
--begin--
@NO:/
+F
name:*
--end--
it matches all files in "/" which fulfill ALL conditions:
* file name is "*" (all names)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 2
--begin--
@NO:/
+F
name:a
name:b
--end--
it matches all files in "/" which fulfill ALL conditions:
* file name is "a" or "b"
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 3
--begin--
@NO:/
+F
name:a
name:b
name:c
type:r
--end--
it matches all files in "/" which fulfill ALL conditions:
* file name is "a" or "b" or "c"
* file type is "r" (regular)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 4
--begin--
@NO:/
+ugmtc
name:a
name:b
name:c
uid:1001
uid:2000-4000
type:rd
--end--
it matches all files in "/" which fulfill ALL conditions:
* 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)
fswbuild will collect information ("ugmtc" means: uid, gid, mode, ctime,
checksum) for all matched files.
example 5
--begin--
@NO:/
+N
uid:2000-4000
+F
name:*
--end--
there are two entries. the first entry matches all files in "/" which
fulfill ALL conditions:
* uid (file owner id) is in "2000-4000"
fswbuild will collect information ("N" means: no information) for all
matched files.
if file doesn`t match the first entry then the second entry is checked.
the second entry matches all files in "/" which fulfill ALL conditions:
* file name is "*" (all names)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 6
--begin--
@NO:/
+N
uid:2000-4000
+C
name:tmp
name:run
type:d
+F
name:*
--end--
there are three entries. the first entry matches all files in "/" which
fulfill ALL conditions:
* uid (file owner id) is in "2000-4000"
fswbuild will collect information ("N" means: no information) for all
matched files.
if file doesn`t match the first entry then the second entry is checked.
the second entry matches all files in "/" which fulfill ALL conditions:
* name is "tmp" or "run"
* type is "d" (directory)
fswbuild will collect information ("C" means: inode, links, uid, gid,
mode, flags) for all matched files.
if file doesn`t match the second entry then the third entry is checked.
the third entry matches all files in "/" which fulfill ALL conditions:
* file name is "*" (all names)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 7
--begin--
@NO:/
+F
name:???
type:d
--end--
it matches all files in "/" which fulfill ALL conditions:
* file name is "???" (it contains exactly three signs)
* file type is "d" (directory)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 8
--begin--
@NO:/
+F
name:???
+F
type:d
--end--
there are two entries. the first entry matches all files in "/" which
fulfill ALL conditions:
* file name is "???" (it contains exactly three signs)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
if file doesn`t match the first entry then the second entry is checked.
the second entry matches all files in "/" which fulfill ALL conditions:
* file type is "d" (directory)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 9
--begin--
@NO:/dir1/dir2
+F
name:*
--end--
it matches all files in "/dir1/dir2" which fulfill ALL conditions:
* file name is "*" (all names)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 10
--begin--
@NO:/dir1/dir2
+F:I
name:*
--end--
it matches all files in "/dir1/dir2" and all subdirectories ( because of
"I" options - inheritance by subdirectories) which fulfill ALL condi‐
tions:
* file name is "*" (all names)
fswbuild will collect information ("F" means: inode, links, uid, gid,
mode, size, flags, ctime, checksum) for all matched files.
example 11
--begin--
@NO:/dir1/dir2
+N
name:tmp
+F:I
name:*
--end--
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).
example 12
--begin--
@NO:/dir1
+F
name:dir2
@NO:/dir1/dir2
+F:I
name:*
--end--
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).
example 13
--begin--
@NO:/
+N:S
name:dir1
name:dir2
+F:I
name:*
--end--
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.
there is an equivalent example below:
--begin--
@NO:/
+N
name:dir1
name:dir2
+F:I
name:*
@NO:/dir1
+N:I
name:*
@NO:/dir2
+N:I
name:*
--end--
SEE ALSOfswbuild(1), fswcmp(1), fswshow(1), fswconf(1)BSD March 31, 2006 BSD
