NAME

fswatch.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 possible 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 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.

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:

+_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 subdirectories 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 special), 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 (directories). 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 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 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--