]> git.sur5r.net Git - bacula/docs/blob - docs/manual/fileset.tex
Update
[bacula/docs] / docs / manual / fileset.tex
1 -%
2 %%
3
4 \section{The FileSet Resource}
5 \label{FileSetResource}
6 \index[general]{Resource!FileSet}
7 \index[general]{FileSet Resource}
8
9 The FileSet resource defines what files are to be included or excluded in a
10 backup job.  A {\bf FileSet} resource is required for each backup Job.  It
11 consists of a list of files or directories to be included, a list of files
12 or directories to be excluded and the various backup options such as
13 compression, encryption, and signatures that are to be applied to each
14 file.
15
16 Any change to the list of the included files will cause Bacula to
17 automatically create a new FileSet (defined by the name and an MD5 checksum
18 of the Include/Exclude contents).  Each time a new FileSet is created,
19 Bacula will ensure that the next backup is always a Full save.
20
21 Bacula is designed to handle most character sets of the world,
22 US ASCII, German, French, Chinese, ...  However, it does this by
23 encoding everything in UTF-8, and it expects all configuration files
24 (including those read on Win32 machines) to be in UTF-8 format.
25 UTF-8 is typically the default on Linux machines, but not on all
26 Unix machines, nor on Windows, so you must take some care to ensure
27 that your locale is set properly before starting Bacula.  
28 On most modern Win32 machines, you can edit the conf files with {\bf
29 notebook} and choose output encoding UTF-8.
30
31 To ensure that Bacula configuration files can be correctly read including
32 foreign characters the {bf LANG} environment variable
33 must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
34 exact syntax may vary a bit from OS to OS, and exactly how you define
35 it will also vary.
36
37 Bacula assumes that all filenames are in UTF-8 format on Linux and
38 Unix machines. On Win32 they are in Unicode (UTF-16), and will
39 be automatically converted to UTF-8 format.
40
41
42 \begin{description}
43
44 \item [FileSet]
45 \index[dir]{FileSet}
46 \index[dir]{Directive!FileSet}
47 Start of the FileSet resource. One {\bf FileSet}  resource must be
48 defined for each Backup job.
49
50 \item [Name = \lt{}name\gt{}]
51 \index[dir]{Name}
52 \index[dir]{Directive!Name}
53    The name of the FileSet resource.  This directive is required. 
54
55 \item [Ignore FileSet Changes = \lt{}yes|no\gt{}]
56 \index[dir]{Ignore FileSet Changes}
57 \index[dir]{Directive!Ignore FileSet Changes}
58    Normally, if you modify the FileSet Include or Exclude lists,
59    the next backup will be forced to a Full so that Bacula can
60    guarantee that any additions or deletions are properly saved.
61
62    We strongly recommend against setting this directive to yes, 
63    since doing so may cause you to have an incomplete set of backups.
64
65    If this directive is set to {\bf yes}, any changes you make to the
66    FileSet Include or Exclude lists, will not force a Full during 
67    subsequent backups.
68
69    The default is {\bf no}, in which case, if you change the Include or
70    Exclude, Bacula will force a Full backup to ensure that everything is
71    properly backed up.
72
73 \item [Enable VSS = \lt{}yes|no\gt{}]
74 \index[dir]{Enable VSS}
75 \index[dir]{Directive!Enable VSS}
76   If this directive is set to {\bf yes} the File daemon will be notified
77   that the user wants to use a Volume Shadow Copy Service (VSS) backup
78   for this job. The default is {\bf yes}. This directive is effective
79   only for VSS enabled Win32 File daemons. It permits a consistent copy
80   of open files to be made for cooperating writer applications, and for
81   applications that are not VSS away, Bacula can at least copy open files.
82   For more information, please see the
83   \ilink{Windows}{VSS} chapter of this manual.
84
85 \item [Include \{ Options \{\lt{}file-options\gt{}\} ...;
86    \lt{}file-list\gt{} \} ]
87 \index[dir]{Include \{ [ Options \{\lt{}file-options\gt{}\} ...]
88    \lt{}file-list\gt{} \}  }
89 \index[dir]{Directive!Include}
90
91 \item [Options \{ \lt{}file-options\gt{} \} ]
92 \index[dir]{Options  \{ \lt{}file-options\gt{} \}  }
93
94 \item [Exclude \{ \lt{}file-list\gt{} \}]
95 \index[dir]{Exclude \{ \lt{}file-list\gt{} \} }
96 \index[dir]{Directive!Exclude}
97
98 \end{description}
99
100 The Include resource must contain a list of directories and/or files to be
101 processed in the backup job.  Normally, all files found in all
102 subdirectories of any directory in the Include File list will be backed up.
103 Note, see below for the definition of \lt{}file-list\gt{}. 
104 The Include resource may also contain one or more Options resources that
105 specify options such as compression to be applied to all or any subset of
106 the files found when processing the file-list for backup. Please see
107 below for more details concerning Options resources.
108
109 There can be any number of {\bf Include} resources within the FileSet, each
110 having its own list of directories or files to be backed up and the backup
111 options defined by one or more Options resources.  The {\bf file-list}
112 consists of one file or directory name per line.  Directory names should be
113 specified without a trailing slash with Unix path notation.
114
115 Windows users, please take note to specify directories (even c:/...) in
116 Unix path notation. If you use Windows conventions, you will most likely
117 not be able to restore your files due to the fact that the Windows
118 path separator was defined as an escape character long before Windows
119 existed, and Bacula adheres to that convention (i.e. \\  means the next character
120 appears as itself).
121
122 You should always specify a full path for every directory and file that you
123 list in the FileSet.  In addition, on Windows machines, you should {\bf
124 always} prefix the directory or filename with the drive specification in
125 lower case (e.g.  {\bf c:/xxx}) using Unix directory name separators
126 (forward slash).
127
128 Bacula's default for processing directories is to recursively descend in
129 the directory saving all files and subdirectories.  Bacula will not by
130 default cross filesystems (or mount points in Unix parlance).  This means
131 that if you specify the root partition (e.g.  {\bf /}), Bacula will save
132 only the root partition and not any of the other mounted filesystems.
133 Similarly on Windows systems, you must explicitly specify each of the
134 drives you want saved (e.g.
135 {\bf c:/} and {\bf d:/} ...). In addition, at least for Windows systems, you
136 will most likely want to enclose each specification within double quotes
137 particularly if the directory (or file) name contains spaces. The {\bf df}
138 command on Unix systems will show you which mount points you must specify to
139 save everything. See below for an example. 
140
141 Take special care not to include a directory twice or Bacula will backup
142 the same files two times wasting a lot of space on your archive device.
143 Including a directory twice is very easy to do.  For example:
144
145 \footnotesize
146 \begin{verbatim}
147   Include {
148     File = /
149     File = /usr
150     Options { compression=GZIP }
151   }
152 \end{verbatim}
153 \normalsize
154
155 on a Unix system where /usr is a subdirectory (rather than a mounted
156 filesystem) will cause /usr to be backed up twice. In this case, on Bacula
157 versions prior to 1.32f-5-09Mar04 due to a bug, you will not be able to
158 restore hard linked files that were backed up twice. 
159
160 If you have used Bacula prior to version 1.36.3, you will note three things in
161 the new FileSet syntax: 
162
163 \begin{enumerate}
164 \item There is no equal sign (=) after the Include and before the opening
165    brace (\{). The same is true for the Exclude. 
166 \item Each directory (or filename) to be included or excluded is preceded by a {\bf File
167    =}.  Previously they were simply listed on separate lines. 
168 \item The options that previously appeared on the Include line now must be
169    specified within their own Options resource.
170 \item The Exclude resource does not accept Options. 
171 \item When using wild-cards or regular expressions, directory names are
172    always terminated with a slash (/) and filenames have no trailing slash.
173 \end{enumerate}
174
175 The Options resource is optional, but when specified, it will contain a
176 list of {\bf keyword=value} options to be applied to the file-list.
177 See below for the definition of file-list.    
178 Multiple Options resources may be specified one after another.  As the
179 files are found in the specified directories, the Options will applied to
180 the filenames to determine if and how the file should be backed up.  The
181 wildcard and regular expression pattern matching parts of the
182 Options resources are checked in the order they are specified in the
183 FileSet until the first one that matches. Once one matches, the
184 compression and other flags within the Options specification will
185 apply to the pattern matched.
186
187 A key point is that in the absence of an Option or no other Option is
188 matched, every file is accepted for backing up. This means that if
189 you want to exclude something, you must explicitly specify an Option
190 with an {\bf exclude = yes} and some pattern matching.
191
192 Once Bacula determines that the Options resource matches the file under
193 consideration, that file will be saved without looking at any other Options
194 resources that may be present.  This means that any wild cards must appear
195 before an Options resource without wild cards.
196
197 If for some reason, Bacula checks all the Options resources to a file under
198 consideration for backup, but there are no matches (generally because of wild
199 cards that don't match), Bacula as a default will then backup the file.  This
200 is quite logical if you consider the case of no Options clause is specified,
201 where you want everything to be backed up, and it is important to keep in mind
202 when excluding as mentioned above.
203
204 However, one additional point is that in the case that no match was found,
205 Bacula will use the options found in the last Options resource.  As a
206 consequence, if you want a particular set of "default" options, you should put
207 them in an Options resource after any other Options.
208
209 It is a good idea to put all your wild-card and regex expressions inside
210 double quotes to prevent conf file scanning problems.
211
212 This is perhaps a bit overwhelming, so there are a number of examples included 
213 below to illustrate how this works.
214
215 The directives within an Options resource may be one of the following: 
216
217 \begin{description}
218
219 \item [compression=GZIP]
220 \index[dir]{compression}
221 \index[dir]{Directive!compression}
222    All files saved will be software compressed using the GNU ZIP
223    compression format.  The compression is done on a file by file basis by
224    the File daemon.  If there is a problem reading the tape in a single
225    record of a file, it will at most affect that file and none of the other
226    files on the tape.  Normally this option is {\bf not} needed if you have
227    a modern tape drive as the drive will do its own compression.  In fact,
228    if you specify software compression at the same time you have hardware
229    compression turned on, your files may actually take more space on the
230    volume.
231
232    Software compression is very important if you are writing your Volumes
233    to a file, and it can also be helpful if you have a fast computer but a
234    slow network, otherwise it is generally better to rely your tape drive's
235    hardware compression.  As noted above, it is not generally a good idea
236    to do both software and hardware compression.
237
238    Specifying {\bf GZIP} uses the default compression level 6 (i.e.  {\bf
239    GZIP} is identical to {\bf GZIP6}).  If you want a different compression
240    level (1 through 9), you can specify it by appending the level number
241    with no intervening spaces to {\bf GZIP}.  Thus {\bf compression=GZIP1}
242    would give minimum compression but the fastest algorithm, and {\bf
243    compression=GZIP9} would give the highest level of compression, but
244    requires more computation.  According to the GZIP documentation,
245    compression levels greater than six generally give very little extra
246    compression and are rather CPU intensive.
247
248 \item [signature=SHA1]
249 \index[dir]{signature}
250 \index[dir]{SHA1}
251 \index[dir]{Directive!signature}
252    An SHA1 signature will be computed for all The SHA1 algorithm is
253    purported to be some what slower than the MD5 algorithm, but at the same
254    time is significantly better from a cryptographic point of view (i.e.
255    much fewer collisions, much lower probability of being hacked.) It adds
256    four more bytes than the MD5 signature.  We strongly recommend that
257    either this option or MD5 be specified as a default for all files.
258    Note, only one of the two options MD5 or SHA1 can be computed for any
259    file.
260
261 \item [signature=MD5]
262 \index[dir]{signature}
263 \index[dir]{MD5}
264 \index[dir]{Directive!signature}
265    An MD5 signature will be computed for all files saved.  Adding this
266    option generates about 5\% extra overhead for each file saved.  In
267    addition to the additional CPU time, the MD5 signature adds 16 more
268    bytes per file to your catalog.  We strongly recommend that this option
269    or the SHA1 option be specified as a default for all files.
270
271 \item [verify=\lt{}options\gt{}]
272 \index[dir]{verify}
273 \index[dir]{Directive!verify}
274    The options letters specified are used  when running a {\bf Verify
275    Level=Catalog} as well as the  {\bf DiskToCatalog} level job. The options
276    letters may be any  combination of the following:  
277
278       \begin{description}
279
280       \item {\bf i}
281       compare the inodes  
282
283       \item {\bf p}
284       compare the permission bits  
285
286       \item {\bf n}
287       compare the number of links  
288
289       \item {\bf u}
290       compare the user id  
291
292       \item {\bf g}
293       compare the group id  
294
295       \item {\bf s}
296       compare the size  
297
298       \item {\bf a}
299       compare the access time  
300
301       \item {\bf m}
302       compare the modification time (st\_mtime)  
303
304       \item {\bf c}
305       compare the change time (st\_ctime)  
306
307       \item {\bf d}
308       report file size decreases  
309
310       \item {\bf 5}
311       compare the MD5 signature  
312
313       \item {\bf 1}
314       compare the SHA1 signature  
315       \end{description}
316
317    A useful set of general options on the {\bf Level=Catalog}  or {\bf
318    Level=DiskToCatalog}  verify is {\bf pins5} i.e. compare permission bits,
319    inodes, number  of links, size, and MD5 changes. 
320
321 \item [onefs=yes|no]
322 \index[dir]{onefs}
323 \index[dir]{Directive!onefs}
324    If set to {\bf yes} (the default), {\bf Bacula} will remain on a single
325    file system.  That is it will not backup file systems that are mounted
326    on a subdirectory.  If you are using a *nix system, you may not even be
327    aware that there are several different filesystems as they are often
328    automatically mounted by the OS (e.g.  /dev, /net, /sys, /proc, ...).
329    With Bacula 1.38.0 or later, it will inform you when it decides not to
330    traverse into another filesystem.  This can be very useful if you forgot
331    to backup a particular partition.  An example of the informational
332    message in the job report is:
333
334 \footnotesize
335 \begin{verbatim}
336 rufus-fd: /misc is a different filesystem. Will not descend from / into /misc
337 rufus-fd: /net is a different filesystem. Will not descend from / into /net
338 rufus-fd: /var/lib/nfs/rpc_pipefs is a different filesystem. Will not descend from /var/lib/nfs into /var/lib/nfs/rpc_pipefs
339 rufus-fd: /selinux is a different filesystem. Will not descend from / into /selinux
340 rufus-fd: /sys is a different filesystem. Will not descend from / into /sys
341 rufus-fd: /dev is a different filesystem. Will not descend from / into /dev
342 rufus-fd: /home is a different filesystem. Will not descend from / into /home
343 \end{verbatim}
344 \normalsize
345
346    Note: in previous versions of Bacula, the above message was of the form: 
347
348 \footnotesize
349 \begin{verbatim}
350 Filesystem change prohibited. Will not descend into /misc
351 \end{verbatim}
352 \normalsize
353
354    If you wish to backup multiple filesystems, you can  explicitly
355    list each filesystem you want saved.  Otherwise, if you set the onefs option
356    to {\bf no}, Bacula will backup  all mounted file systems (i.e. traverse mount
357    points) that  are found within the {\bf FileSet}. Thus if  you have NFS or
358    Samba file systems mounted on a directory listed  in your FileSet, they will
359    also be backed up. Normally, it is  preferable to set {\bf onefs=yes} and to
360    explicitly name  each filesystem you want backed up. Explicitly naming  the
361    filesystems you want backed up avoids the possibility  of getting into a
362    infinite loop recursing filesystems.  Another possibility is to 
363    use {\bf onefs=no} and to set {\bf fstype=ext2, ...}.             
364    See the example below for more details. 
365
366    If you think that Bacula should be backing up a particular directory
367    and it is not, and you have {\bf onefs=no} set, before you complain,
368    please do:
369
370 \footnotesize
371 \begin{verbatim}
372   stat /
373   stat <filesystem>
374 \end{verbatim}
375 \normalsize
376
377 where you replace {\bf filesystem} with the one in question.  If the 
378 {\bf Device:} number is different for / and for your filesystem, then they
379 are on different filesystems.  E.g.
380 \footnotesize
381 \begin{verbatim}
382 stat /
383   File: `/'
384   Size: 4096            Blocks: 16         IO Block: 4096   directory
385 Device: 302h/770d       Inode: 2           Links: 26
386 Access: (0755/drwxr-xr-x)  Uid: (    0/    root)   Gid: (    0/    root)
387 Access: 2005-11-10 12:28:01.000000000 +0100
388 Modify: 2005-09-27 17:52:32.000000000 +0200
389 Change: 2005-09-27 17:52:32.000000000 +0200
390
391 stat /net
392   File: `/home'
393   Size: 4096            Blocks: 16         IO Block: 4096   directory
394 Device: 308h/776d       Inode: 2           Links: 7
395 Access: (0755/drwxr-xr-x)  Uid: (    0/    root)   Gid: (    0/    root)
396 Access: 2005-11-10 12:28:02.000000000 +0100
397 Modify: 2005-11-06 12:36:48.000000000 +0100
398 Change: 2005-11-06 12:36:48.000000000 +0100
399 \end{verbatim}
400 \normalsize
401
402    Also be aware that even if you include {\bf /home} in your list
403    of files to backup, as you most likely should, you will get the
404    informational message that  "/home is a different filesystem" when 
405    Bacula is processing the {\bf /} directory.  This message does not
406    indicate an error. This message means that while examining the 
407    {\bf File =} referred to in the second part of the message, Bacula will 
408    not descend into the directory mentioned in the first part of the message.
409    However, it is possible that the separate filesystem will be backed up 
410    despite the message. For example, consider the following FileSet:
411
412 \footnotesize
413 \begin{verbatim}
414   File = /
415   File = /var
416 \end{verbatim}
417 \normalsize
418
419    where {\bf /var} is a separate filesystem.  In this example, you will get a
420    message saying that Bacula will not decend from {\bf /} into {\bf /var}.  But 
421    it is important to realise that Bacula will descend into {\bf /var} from the 
422    second File directive shown above.  In effect, the warning is bogus,
423    but it is supplied to alert you to possible omissions from your FileSet. In 
424    this example, {\bf /var} will be backed up.  If you changed the FileSet such 
425    that it did not specify {\bf /var}, then {\bf /var} will not be backed up.
426
427    
428
429
430 \label{portable}
431 \item [portable=yes|no]
432 \index[dir]{portable}
433 \index[dir]{Directive!portable}
434    If set to {\bf yes} (default is {\bf no}), the Bacula File daemon will
435    backup Win32 files in a portable format, but not all Win32 file
436    attributes will be saved and restored.  By default, this option is set
437    to {\bf no}, which means that on Win32 systems, the data will be backed
438    up using Windows API calls and on WinNT/2K/XP, all the security and
439    ownership attributes will be properly backed up (and restored).  However
440    this format is not portable to other systems -- e.g.  Unix, Win95/98/Me.
441    When backing up Unix systems, this option is ignored, and unless you
442    have a specific need to have portable backups, we recommend accept the
443    default ({\bf no}) so that the maximum information concerning your files
444    is saved.
445
446 \item [recurse=yes|no]
447 \index[dir]{recurse}
448 \index[dir]{Directive!recurse}
449    If set to {\bf yes} (the default), Bacula will recurse (or descend) into
450    all subdirectories found unless the directory is explicitly excluded
451    using an {\bf exclude} definition.  If you set {\bf recurse=no}, Bacula
452    will save the subdirectory entries, but not descend into the
453    subdirectories, and thus will not save the files or directories
454    contained in the subdirectories.  Normally, you will want the default
455    ({\bf yes}).
456
457 \item [sparse=yes|no]
458 \index[dir]{sparse}
459 \index[dir]{Directive!sparse}
460    Enable special code that checks for sparse files such as created by
461    ndbm.  The default is {\bf no}, so no checks are made for sparse files.
462    You may specify {\bf sparse=yes} even on files that are not sparse file.
463    No harm will be done, but there will be a small additional overhead to
464    check for buffers of all zero, and a small additional amount of space on
465    the output archive will be used to save the seek address of each
466    non-zero record read.
467
468    {\bf Restrictions:} Bacula reads files in 32K buffers.  If the whole
469    buffer is zero, it will be treated as a sparse block and not written to
470    tape.  However, if any part of the buffer is non-zero, the whole buffer
471    will be written to tape, possibly including some disk sectors (generally
472    4098 bytes) that are all zero.  As a consequence, Bacula's detection of
473    sparse blocks is in 32K increments rather than the system block size.
474    If anyone considers this to be a real problem, please send in a request
475    for change with the reason.
476
477    If you are not familiar with sparse files, an example is say a file
478    where you wrote 512 bytes at address zero, then 512 bytes at address 1
479    million.  The operating system will allocate only two blocks, and the
480    empty space or hole will have nothing allocated.  However, when you read
481    the sparse file and read the addresses where nothing was written, the OS
482    will return all zeros as if the space were allocated, and if you backup
483    such a file, a lot of space will be used to write zeros to the volume.
484    Worse yet, when you restore the file, all the previously empty space
485    will now be allocated using much more disk space.  By turning on the
486    {\bf sparse} option, Bacula will specifically look for empty space in
487    the file, and any empty space will not be written to the Volume, nor
488    will it be restored.  The price to pay for this is that Bacula must
489    search each block it reads before writing it.  On a slow system, this
490    may be important.  If you suspect you have sparse files, you should
491    benchmark the difference or set sparse for only those files that are
492    really sparse.
493
494 \label{readfifo}
495 \item [readfifo=yes|no]
496 \index[dir]{readfifo}
497 \index[dir]{Directive!readfifo}
498    If enabled, tells the Client to read the data on a backup and write the
499    data on a restore to any FIFO (pipe) that is explicitly mentioned in the
500    FileSet.  In this case, you must have a program already running that
501    writes into the FIFO for a backup or reads from the FIFO on a restore.
502    This can be accomplished with the {\bf RunBeforeJob} directive.  If this
503    is not the case, Bacula will hang indefinitely on reading/writing the
504    FIFO. When this is not enabled (default), the Client simply saves the
505    directory entry for the FIFO.
506
507    Unfortunately, when Bacula runs a RunBeforeJob, it waits until that
508    script terminates, and if the script accesses the FIFO to write   
509    into the it, the Bacula job will block and everything will stall.
510    However, Vladimir Stavrinov as supplied tip that allows this feature   
511    to work correctly.  He simply adds the following to the beginning
512    of the RunBeforeJob script:
513
514 \begin{verbatim}
515    exec > /dev/null
516 \end{verbatim}
517
518 \item [noatime=yes|no]
519 \index[dir]{noatime}
520 \index[dir]{Directive!noatime}
521    If enabled, and if your Operating System supports the O\_NOATIME file
522    open flag, Bacula will open all files to be backed up with this option.
523    It makes it possible to read a file without updating the inode atime
524    (and also without the inode ctime update which happens if you try to set
525    the atime back to its previous value).  It also prevents a race
526    condition when two programs are reading the same file, but only one does
527    not want to change the atime.  It's most useful for backup programs and
528    file integrity checkers (and bacula can fit on both categories).
529
530    This option is particularly useful for sites where users are sensitive
531    to their MailBox file access time.  It replaces both the {\bf keepatime}
532    option without the inconveniences of that option (see below).
533
534    If your Operating System does not support this option, it will be
535    silently ignored by Bacula.
536
537
538 \item [mtimeonly=yes|no]
539 \index[dir]{mtimeonly}
540 \index[dir]{Directive!mtimeonly}
541    If enabled, tells the Client that the selection of files during
542    Incremental and Differential backups should based only on the st\_mtime
543    value in the stat() packet.  The default is {\bf no} which means that
544    the selection of files to be backed up will be based on both the
545    st\_mtime and the st\_ctime values.  In general, it is not recommended
546    to use this option.
547
548 \item [keepatime=yes|no]
549 \index[dir]{keepatime}
550 \index[dir]{Directive!keepatime}
551    The default is {\bf no}.  When enabled, Bacula will reset the st\_atime
552    (access time) field of files that it backs up to their value prior to
553    the backup.  This option is not generally recommended as there are very
554    few programs that use st\_atime, and the backup overhead is increased
555    because of the additional system call necessary to reset the times.
556    However, for some files, such as mailboxes, when Bacula backs up the
557    file, the user will notice that someone (Bacula) has accessed the
558    file. In this, case keepatime can be useful.
559    (I'm not sure this works on Win32).
560
561    Note, if you use this feature, when Bacula resets the access time, the
562    change time (st\_ctime) will automatically be modified by the system,
563    so on the next incremental job, the file will be backed up even if
564    it has not changed. As a consequence, you will probably also want
565    to use {\bf mtimeonly = yes} as well as keepatime (thanks to
566    Rudolf Cejka for this tip).
567
568 \item [checkfilechanges=yes|no]
569 \index[dir]{checkfilechanges}
570 \index[dir]{Directive!checkfilechanges}
571    On versions 2.0.4 or greater, 
572    if enabled, the Client will checks size, age of each file after 
573    their backup to see if they have changed during backup. If time 
574    or size mismatch, an error will raise.
575
576 \begin{verbatim}
577  zog-fd: Client1.2007-03-31_09.46.21 Error: /tmp/test mtime changed during backup.
578 \end{verbatim}
579
580    In general, it is recommended to use this option.
581
582 \item [hardlinks=yes|no]
583 \index[dir]{hardlinks}
584 \index[dir]{Directive!hardlinks}
585    When enabled (default), this directive will cause hard links to be 
586    backed up. However, the File daemon keeps track of hard linked files and
587    will backup the data only once. The process of keeping track of the 
588    hard links can be quite expensive if you have lots of them (tens of
589    thousands or more). This doesn't occur on normal Unix systems, but if
590    you use a program like BackupPC, it can create hundreds of thousands, or
591    even millions of hard links. Backups become very long and the File daemon
592    will consume a lot of CPU power checking hard links.  In such a case,
593    set {\bf hardlinks=no} and hard links will not be backed up.  Note, using
594    this option will most likely backup more data and on a restore the file
595    system will not be restored identically to the original.
596
597 \item [wild=\lt{}string\gt{}]
598 \index[dir]{wild}
599 \index[dir]{Directive!wild}
600    Specifies a wild-card string to be applied to the filenames and
601    directory names.  Note, if {\bf Exclude} is not enabled, the wild-card
602    will select which files are to be included.  If {\bf Exclude=yes} is
603    specified, the wild-card will select which files are to be excluded.
604    Multiple wild-card directives may be specified, and they will be applied
605    in turn until the first one that matches.  Note, if you exclude a
606    directory, no files or directories below it will be matched.
607
608    You may want to test your expressions prior to running your
609    backup by using the bwild program. Please see the
610    \ilink{Utilities}{bwild} chapter of this manual for
611    more. You can also test your full FileSet definition by using
612    the \ilink{estimate}{estimate} command in the Console        
613    chapter of this manual.
614    It is recommended to enclose the string in double quotes.
615
616 \item [wilddir=\lt{}string\gt{}]
617 \index[dir]{wilddir}
618 \index[dir]{Directive!wilddir}
619    Specifies a wild-card string to be applied to directory names only.  No
620    filenames will be matched by this directive.  Note, if {\bf Exclude} is
621    not enabled, the wild-card will select directories to be
622    included.  If {\bf Exclude=yes} is specified, the wild-card will select
623    which directories are to be excluded.  Multiple wild-card directives may be
624    specified, and they will be applied in turn until the first one that
625    matches.  Note, if you exclude a directory, no files or directories
626    below it will be matched.
627
628    It is recommended to enclose the string in double quotes.
629
630    You may want to test your expressions prior to running your
631    backup by using the bwild program. Please see the
632    \ilink{Utilities}{bwild} chapter of this manual for
633    more. You can also test your full FileSet definition by using
634    the \ilink{estimate}{estimate} command in the Console        
635    chapter of this manual.
636    An example of excluding with the WildDir option on Win32 machines is    
637    presented below.
638
639 \item [wildfile=\lt{}string\gt{}]
640 \index[dir]{wildfile}
641 \index[dir]{Directive!wildfile}
642    Specifies a wild-card string to be applied to non-directories. That
643    is no directory entries will be matched by this directive.
644    However, note that the match is done against the full path and filename,
645    so your wild-card string must take into account that filenames
646    are preceded by the full path.
647    If {\bf Exclude}
648    is not enabled, the wild-card will select which files are to be
649    included.  If {\bf Exclude=yes} is specified, the wild-card will select
650    which files are to be excluded.  Multiple wild-card directives may be
651    specified, and they will be applied in turn until the first one that
652    matches.
653
654    It is recommended to enclose the string in double quotes.
655
656    You may want to test your expressions prior to running your
657    backup by using the bwild program. Please see the
658    \ilink{Utilities}{bwild} chapter of this manual for
659    more. You can also test your full FileSet definition by using
660    the \ilink{estimate}{estimate} command in the Console        
661    chapter of this manual.
662    An example of excluding with the WildFile option on Win32 machines is    
663    presented below.
664
665
666 \item [regex=\lt{}string\gt{}]
667 \index[dir]{regex}
668 \index[dir]{Directive!regex}
669    Specifies a POSIX extended regular expression to be applied to the
670    filenames and directory names, which include the full path.  If {\bf
671    Exclude} is not enabled, the regex will select which files are to be
672    included.  If {\bf Exclude=yes} is specified, the regex will select
673    which files are to be excluded.  Multiple regex directives may be
674    specified within an Options resource, and they will be applied in turn
675    until the first one that matches.  Note, if you exclude a directory, no
676    files or directories below it will be matched.
677
678    It is recommended to enclose the string in double quotes.
679
680    The regex libraries differ from one operating system to
681    another, and in addition, regular expressions are complicated,
682    so you may want to test your expressions prior to running your
683    backup by using the bregex program. Please see the
684    \ilink{Utilities}{bwild} chapter of this manual for
685    more. You can also test your full FileSet definition by using
686    the \ilink{estimate}{estimate} command in the Console        
687    chapter of this manual.
688
689
690 \item [regexfile=\lt{}string\gt{}]
691 \index[dir]{regexfile}
692 \index[dir]{Directive!regexfile}
693    Specifies a POSIX extended regular expression to be applied to
694    non-directories. No directories will be matched by this directive.  
695    However, note that the match is done against the full path and
696    filename, so your regex string must take into account that filenames
697    are preceded by the full path.
698    If {\bf Exclude} is not enabled, the regex will select which files are
699    to be included.  If {\bf Exclude=yes} is specified, the regex will
700    select which files are to be excluded.  Multiple regex directives may be
701    specified, and they will be applied in turn until the first one that
702    matches.
703
704    It is recommended to enclose the string in double quotes.
705
706    The regex libraries differ from one operating system to
707    another, and in addition, regular expressions are complicated,
708    so you may want to test your expressions prior to running your
709    backup by using the bregex program. Please see the
710    \ilink{Utilities}{bregex} chapter of this manual for
711    more.
712
713
714 \item [regexdir=\lt{}string\gt{}]
715 \index[dir]{regexdir}
716 \index[dir]{Directive!regexdir}
717    Specifies a POSIX extended regular expression to be applied to directory
718    names only.  No filenames will be matched by this directive.  Note, if
719    {\bf Exclude} is not enabled, the regex will select directories
720    files are to be included.  If {\bf Exclude=yes} is specified, the
721    regex will select which files are to be excluded.  Multiple
722    regex directives may be specified, and they will be applied in turn
723    until the first one that matches.  Note, if you exclude a directory, no
724    files or directories below it will be matched.
725
726    It is recommended to enclose the string in double quotes.
727
728    The regex libraries differ from one operating system to
729    another, and in addition, regular expressions are complicated,
730    so you may want to test your expressions prior to running your
731    backup by using the bregex program. Please see the
732    \ilink{Utilities}{bregex} chapter of this manual for
733    more.
734
735
736 \item [exclude=yes|no]
737 \index[dir]{exclude}
738 \index[dir]{Directive!exclude}
739    The default is {\bf no}.  When enabled, any files matched within the
740    Options will be excluded from the backup.
741
742 \label{ACLSupport}
743 \item [aclsupport=yes|no]
744 \index[dir]{aclsupport}
745 \index[dir]{Directive!aclsupport}
746    The default is {\bf no}.  If this option is set to yes, and you have the
747    POSIX {\bf libacl} installed on your system, Bacula will backup the file
748    and directory UNIX Access Control Lists (ACL) as defined in IEEE Std
749    1003.1e draft 17 and "POSIX.1e" (abandoned).  This feature is
750    available on UNIX only and depends on the ACL library.  Bacula is
751    automatically compiled with ACL support if the {\bf libacl} library is
752    installed on your system (shown in config.out).  While restoring the
753    files Bacula will try to restore the ACLs, if there is no ACL support
754    available on the system, Bacula restores the files and directories but
755    not the ACL information.  Please note, if you backup an EXT3 or XFS
756    filesystem with ACLs, then you restore them to a different filesystem
757    (perhaps reiserfs) that does not have ACLs, the ACLs will be ignored.
758
759 \item [ignore case=yes|no]
760 \index[dir]{ignore case}
761 \index[dir]{Directive!ignore case}
762    The default is {\bf no}.  On Windows systems, you will almost surely
763    want to set this to {\bf yes}.  When this directive is set to {\bf yes}
764    all the case of character will be ignored in wild-card and regex
765    comparisons.  That is an uppercase A will match a lowercase a.
766
767 \item [fstype=filesystem-type]
768 \index[dir]{fstype}
769 \index[dir]{Directive!fstype}
770    This option allows you to select files and directories by the
771    filesystem type.  The permitted filesystem-type names are:
772
773    ext2, jfs, ntfs, proc, reiserfs, xfs, usbdevfs, sysfs, smbfs,
774    iso9660.  For ext3 systems, use ext2.
775
776    You may have multiple Fstype directives, and thus permit matching
777    of multiple filesystem types within a single Options resource.  If
778    the type specified on the fstype directive does not match the
779    filesystem for a particular directive, that directory will not be
780    backed up.  This directive can be used to prevent backing up
781    non-local filesystems. Normally, when you use this directive, you
782    would also set {\bf onefs=no} so that Bacula will traverse filesystems.
783
784    This option is not implemented in Win32 systems.
785
786
787 \item [hfsplussupport=yes|no]
788 \index[dir]{hfsplussupport}
789 \index[dir]{Directive!hfsplussupport}
790    This option allows you to turn on support for Mac OSX HFS plus 
791    finder information.
792
793 \item [strippath=\lt{}integer\gt{}]
794 \index[dir]{strippath}
795 \index[dir]{Directive!strippath}
796    This option will cause {\bf integer} paths to be stripped from
797    the front of the full path/filename being backed up. This can
798    be useful if you are migrating data from another vendor or if
799    you have taken a snapshot into some subdirectory.  This directive
800    can cause your filenames to be overlayed with regular backup data,
801    so should be used only by experts and with great care.
802 \end{description}
803
804 {\bf \lt{}file-list\gt{}} is a list of directory and/or filename names
805 specified with a {\bf File =} directive. To include names containing spaces,
806 enclose the name between double-quotes. Wild-cards are not interpreted
807 in file-lists. They can only be specified in Options resources.
808
809 There are a number of special cases when specifying directories and files in a
810 {\bf file-list}. They are: 
811
812 \begin{itemize}
813 \item Any name preceded by an at-sign (@) is assumed to be the  name of a
814    file, which contains a list of files each preceded by a "File =".  The
815    named file is read once when the configuration file is parsed during the
816    Director startup.  Note, that the file is read on the Director's machine
817    and not on the Client's.  In fact, the @filename can appear anywhere
818    within the conf file where a token would be read, and the contents of
819    the named file will be logically inserted in the place of the @filename.
820    What must be in the file depends on the location the @filename is
821    specified in the conf file.  For example:
822
823 \footnotesize
824 \begin{verbatim}
825 Include {
826   Options { compression=GZIP }
827   @/home/files/my-files
828 }
829 \end{verbatim}
830 \normalsize
831
832 \item Any name beginning with a vertical bar (|) is  assumed to be the name of
833    a program.  This program will be executed on the Director's machine at
834    the time the Job starts (not when the Director reads the configuration
835    file), and any output from that program will be assumed to be a list of
836    files or directories, one per line, to be included. Before submitting the 
837    specified command bacula will performe 
838    \ilink{character substitution}{character substitution}.
839
840    This allows you to have a job that, for example, includes all the local
841    partitions even if you change the partitioning by adding a disk.  The
842    examples below show you how to do this.  However, please note two
843    things: \\
844    1.  if you want the local filesystems, you probably should be
845    using the new {\bf fstype} directive, which was added in version 1.36.3 
846    and set {\bf onefs=no}.
847    \\
848
849    2.  the exact syntax of the command needed in the examples below is very
850    system dependent.  For example, on recent Linux systems, you may need to
851    add the -P option, on FreeBSD systems, the options will be different as
852    well.
853
854    In general, you will need to prefix your command or commands with a {\bf
855    sh -c} so that they are invoked by a shell.  This will not be the case
856    if you are invoking a script as in the second example below.  Also, you
857    must take care to escape (precede with a \textbackslash{}) wild-cards,
858    shell character, and to ensure that any spaces in your command are
859    escaped as well.  If you use a single quotes (') within a double quote
860    ("), Bacula will treat everything between the single quotes as one field
861    so it will not be necessary to escape the spaces.  In general, getting
862    all the quotes and escapes correct is a real pain as you can see by the
863    next example.  As a consequence, it is often easier to put everything in
864    a file and simply use the file name within Bacula.  In that case the
865    {\bf sh -c} will not be necessary providing the first line of the file
866    is {\bf \#!/bin/sh}.
867
868    As an  example: 
869
870 \footnotesize
871 \begin{verbatim}
872  
873 Include {
874    Options { signature = SHA1 }
875    File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
876       | awk \"{print \\$6}\"'"
877 }
878 \end{verbatim}
879 \normalsize
880
881    will produce a list of all the local partitions on a Red Hat Linux system.
882    Note, the above line was split, but should normally  be written on one line. 
883    Quoting is a real problem because you must quote for Bacula  which consists of
884    preceding every \textbackslash{} and every " with a \textbackslash{}, and 
885    you must also quote for the shell command. In the end, it is probably  easier
886    just to execute a small file with: 
887
888
889 \footnotesize
890 \begin{verbatim}
891 Include {
892   Options {
893     signature=MD5
894   }
895   File = "|my_partitions"
896 }
897 \end{verbatim}
898 \normalsize
899
900    where my\_partitions has: 
901
902 \footnotesize
903 \begin{verbatim}
904 #!/bin/sh
905 df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
906       | awk "{print \$6}"
907 \end{verbatim}
908 \normalsize
909
910    If the vertical bar (|) in front of my\_partitions is preceded by a
911    backslash as in \textbackslash{}|, the program will be executed on the
912    Client's machine instead of on the Director's machine.
913    Please note that if the filename is given within quotes, you
914    will need to use two slashes.  An example, provided by John Donagher,
915    that backs up all the local UFS partitions on a remote system is:
916
917 \footnotesize
918 \begin{verbatim}
919 FileSet {
920   Name = "All local partitions"
921   Include {
922     Options { signature=SHA1; onefs=yes; }
923     File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
924   }
925 }
926 \end{verbatim}
927 \normalsize
928
929    The above requires two backslash characters after the double quote (one
930    preserves  the next one). If you are a Linux user, just change the {\bf ufs}
931    to  {\bf ext3} (or your preferred filesystem type), and you will be in 
932    business.  
933
934    If you know what filesystems you have mounted on your system, e.g. 
935    for Red Hat Linux normally only ext2 and ext3, you can backup
936    all local filesystems using something like:
937
938 \footnotesize
939 \begin{verbatim}
940  
941 Include {
942    Options { signature = SHA1; onfs=no; fstype=ext2 }
943    File = /
944 }
945 \end{verbatim}
946 \normalsize
947
948
949 \item Any file-list item preceded by a less-than sign (\lt{})  will be taken
950    to be a file. This file will be read on the Director's machine (see
951    below for doing it on the Client machine) at the time
952    the Job starts, and the  data will be assumed to be a list of directories or
953    files,  one per line, to be included. The names should start in  column 1 and
954    should not be quoted even if they contain  spaces. This feature allows you to
955    modify the external  file and change what will be saved without stopping and 
956    restarting Bacula as would be necessary if using the @  modifier noted above.
957    For example: 
958
959 \footnotesize
960 \begin{verbatim}
961 Include {
962   Options { signature = SHA1 }
963   File = "</home/files/local-filelist"
964 }
965 \end{verbatim}
966 \normalsize
967
968    If you precede the less-than sign (\lt{}) with a backslash as in
969    \textbackslash{}\lt{}, the file-list will be read on the Client machine
970    instead of on the Director's machine.  Please note that if the filename
971    is given within quotes, you will need to use two slashes.
972
973 \footnotesize
974 \begin{verbatim}
975 Include {
976   Options { signature = SHA1 }
977   File = "\\</home/xxx/filelist-on-client"
978 }
979 \end{verbatim}
980 \normalsize
981
982 \item If you explicitly specify a block device such as {\bf /dev/hda1},  then
983    Bacula (starting with version 1.28) will assume that this  is a raw partition
984    to be backed up. In this case, you are strongly  urged to specify a {\bf
985    sparse=yes} include option, otherwise, you  will save the whole partition
986    rather than just the actual data that  the partition contains. For example: 
987
988 \footnotesize
989 \begin{verbatim}
990 Include {
991   Options { signature=MD5; sparse=yes }
992   File = /dev/hd6
993 }
994 \end{verbatim}
995 \normalsize
996
997    will backup the data in device /dev/hd6.  
998
999    Ludovic Strappazon has pointed out that this feature can be  used to backup a
1000    full Microsoft Windows disk. Simply boot into  the system using a Linux Rescue
1001    disk, then load a statically  linked Bacula as described in the 
1002    \ilink{ Disaster Recovery Using Bacula}{RescueChapter} chapter of
1003    this manual. Then  save the whole disk partition. In the case of a disaster,
1004    you  can then restore the desired partition by again booting with  the rescue
1005    disk and doing a restore of the partition. 
1006    \item If you explicitly specify a FIFO device name (created with mkfifo),  and
1007    you add the option {\bf readfifo=yes} as an option, Bacula  will read the FIFO
1008    and back its data up to the Volume. For  example: 
1009
1010 \footnotesize
1011 \begin{verbatim}
1012 Include {
1013   Options {
1014     signature=SHA1
1015     readfifo=yes
1016   }
1017   File = /home/abc/fifo
1018 }
1019 \end{verbatim}
1020 \normalsize
1021
1022    if {\bf /home/abc/fifo} is a fifo device, Bacula will open the fifo,
1023    read it, and store all data thus obtained on the Volume.  Please note,
1024    you must have a process on the system that is writing into the fifo, or
1025    Bacula will hang, and after one minute of waiting, Bacula will give up
1026    and go on to the next file.  The data read can be anything since Bacula
1027    treats it as a stream.
1028
1029    This feature can be an excellent way to do a "hot" backup of a very
1030    large database.  You can use the {\bf RunBeforeJob} to create the fifo
1031    and to start a program that dynamically reads your database and writes
1032    it to the fifo.  Bacula will then write it to the Volume.  Be sure to
1033    read the \ilink{readfifo section}{readfifo} that gives a
1034    tip to ensure that the RunBeforeJob does not block Bacula.
1035
1036    During the restore operation, the inverse is true, after Bacula creates
1037    the fifo if there was any data stored with it (no need to explicitly
1038    list it or add any options), that data will be written back to the fifo.
1039    As a consequence, if any such FIFOs exist in the fileset to be restored,
1040    you must ensure that there is a reader program or Bacula will block, and
1041    after one minute, Bacula will time out the write to the fifo and move on
1042    to the next file.
1043
1044 \item A file-list may not contain wild-cards. Use directives in the
1045    Options resource if you wish to specify wild-cards or regular expression
1046    matching.
1047 \end{itemize}
1048
1049 \section{FileSet Examples}
1050 \index[general]{Examples!FileSet }
1051 \index[general]{FileSet Examples}
1052
1053 The following is an example of a valid FileSet resource definition.  Note,
1054 the first Include pulls in the contents of the file {\bf /etc/backup.list}
1055 when Bacula is started (i.e.  the @), and that file must have each filename
1056 to be backed up preceded by a {\bf File =} and on a separate line.
1057
1058 \footnotesize
1059 \begin{verbatim}
1060 FileSet {
1061   Name = "Full Set"
1062   Include {
1063     Options {
1064       Compression=GZIP
1065       signature=SHA1
1066       Sparse = yes
1067     }
1068     @/etc/backup.list
1069   }
1070   Include {
1071      Options {
1072         wildfile = "*.o"
1073         wildfile = "*.exe"
1074         Exclude = yes
1075      }
1076      File = /root/myfile
1077      File = /usr/lib/another_file
1078   }
1079 }
1080 \end{verbatim}
1081 \normalsize
1082
1083 In the above example, all the files contained in /etc/backup.list will
1084 be compressed with GZIP compression, an SHA1 signature will be computed on the
1085 file's contents (its data), and sparse file handling will apply. 
1086
1087 The two directories /root/myfile and /usr/lib/another\_file will also be saved
1088 without any options, but all files in those directories with the extensions
1089 {\bf .o} and {\bf .exe} will be excluded. 
1090
1091 Let's say that you now want to exclude the directory /tmp. The simplest way
1092 to do so is to add an exclude directive that lists /tmp.  The example
1093 above would then become:
1094
1095 \footnotesize 
1096 \begin{verbatim}
1097 FileSet {
1098   Name = "Full Set"
1099   Include {
1100     Options {
1101       Compression=GZIP
1102       signature=SHA1
1103       Sparse = yes
1104     }
1105     @/etc/backup.list
1106   }
1107   Include {
1108      Options {
1109         wildfile = "*.o"
1110         wildfile = "*.exe"
1111         Exclude = yes
1112      }
1113      File = /root/myfile
1114      File = /usr/lib/another_file
1115   }
1116   Exclude {
1117      File = /tmp
1118   }
1119 }
1120 \end{verbatim}
1121 \normalsize
1122
1123
1124 You can add wild-cards to the File directives listed in the Exclude
1125 directory, but you need to take care because if you exclude a directory,
1126 it and all files and directories below it will also be excluded.
1127
1128 Now lets take a slight variation on the above and suppose
1129 you want to save all your whole filesystem except {\bf /tmp}. 
1130 The problem that comes up is that Bacula will not normally
1131 cross from one filesystem to another.
1132 Doing a {\bf df} command, you get the following output: 
1133
1134 \footnotesize
1135 \begin{verbatim}
1136 [kern@rufus k]$ df
1137 Filesystem      1k-blocks      Used Available Use% Mounted on
1138 /dev/hda5         5044156    439232   4348692  10% /
1139 /dev/hda1           62193      4935     54047   9% /boot
1140 /dev/hda9        20161172   5524660  13612372  29% /home
1141 /dev/hda2           62217      6843     52161  12% /rescue
1142 /dev/hda8         5044156     42548   4745376   1% /tmp
1143 /dev/hda6         5044156   2613132   2174792  55% /usr
1144 none               127708         0    127708   0% /dev/shm
1145 //minimatou/c$   14099200   9895424   4203776  71% /mnt/mmatou
1146 lmatou:/          1554264    215884   1258056  15% /mnt/matou
1147 lmatou:/home      2478140   1589952    760072  68% /mnt/matou/home
1148 lmatou:/usr       1981000   1199960    678628  64% /mnt/matou/usr
1149 lpmatou:/          995116    484112    459596  52% /mnt/pmatou
1150 lpmatou:/home    19222656   2787880  15458228  16% /mnt/pmatou/home
1151 lpmatou:/usr      2478140   2038764    311260  87% /mnt/pmatou/usr
1152 deuter:/          4806936     97684   4465064   3% /mnt/deuter
1153 deuter:/home      4806904    280100   4282620   7% /mnt/deuter/home
1154 deuter:/files    44133352  27652876  14238608  67% /mnt/deuter/files
1155 \end{verbatim}
1156 \normalsize
1157
1158 And we see that there are a number of separate filesystems (/ /boot
1159 /home /rescue /tmp and /usr not to mention mounted systems).
1160 If you specify only {\bf /} in your Include list, Bacula will only save the
1161 Filesystem {\bf /dev/hda5}. To save all filesystems except {\bf /tmp} with
1162 out including any of the Samba or NFS mounted systems, and explicitly
1163 excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to
1164 be saved and restored, you can use the following: 
1165
1166 \footnotesize
1167 \begin{verbatim}
1168 FileSet {
1169   Name = Include_example
1170   Include {
1171     Options {
1172        wilddir = /proc
1173        wilddir = /tmp
1174        wildfile = "/.journal"
1175        wildfile = "/.autofsck"
1176        exclude = yes
1177     }
1178     File = /
1179     File = /boot
1180     File = /home
1181     File = /rescue
1182     File = /usr
1183   }
1184 }
1185 \end{verbatim}
1186 \normalsize
1187
1188 Since /tmp is on its own filesystem and it was not explicitly named in the
1189 Include list, it is not really needed in the exclude list. It is better to
1190 list it in the Exclude list for clarity, and in case the disks are changed so
1191 that it is no longer in its own partition. 
1192
1193 Now, lets assume you only want to backup .Z and .gz files and nothing 
1194 else. This is a bit trickier because Bacula by default will select 
1195 everything to backup, so we must exclude everything but .Z and .gz files.
1196 If we take the first example above and make the obvious modifications
1197 to it, we might come up with a FileSet that looks like this:
1198
1199 \footnotesize 
1200 \begin{verbatim}
1201 FileSet {
1202   Name = "Full Set"
1203   Include {                    !!!!!!!!!!!!
1204      Options {                    This
1205         wildfile = "*.Z"          example
1206         wildfile = "*.gz"         doesn't
1207                                   work
1208      }                          !!!!!!!!!!!!
1209      File = /myfile
1210   }
1211 }
1212 \end{verbatim}
1213 \normalsize
1214
1215 The *.Z and *.gz files will indeed be backed up, but all other files
1216 that are not matched by the Options directives will automatically
1217 be backed up too (i.e. that is the default rule).
1218
1219 To accomplish what we want, we must explicitly exclude all other files.
1220 We do this with the following:
1221
1222 \footnotesize
1223 \begin{verbatim}
1224 FileSet {
1225   Name = "Full Set"
1226   Include {
1227      Options {
1228         wildfile = "*.Z"
1229         wildfile = "*.gz"
1230      }
1231      Options {
1232         Exclude = yes
1233         RegexFile = ".*"
1234      }
1235      File = /myfile
1236   }
1237 }
1238 \end{verbatim}
1239 \normalsize
1240
1241 The "trick" here was to add a RegexFile expression that matches
1242 all files. It does not match directory names, so all directories in
1243 /myfile will be backed up (the directory entry) and any *.Z and *.gz
1244 files contained in them. If you know that certain directories do
1245 not contain any *.Z or *.gz files and you do not want the directory
1246 entries backed up, you will need to explicitly exclude those directories.
1247 Backing up a directory entries is not very expensive.
1248
1249 Bacula uses the system regex library and some of them are
1250 different on different OSes. The above has been reported not to work
1251 on FreeBSD. This can be tested by using the {\bf estimate job=job-name
1252 listing} command in the console and adapting the RegexFile expression
1253 appropriately. In a future version of Bacula, we will supply our own
1254 Regex code to avoid such system dependencies.
1255
1256 Please be aware that allowing Bacula to traverse or change file systems can be
1257 {\bf very} dangerous. For example, with the following: 
1258
1259 \footnotesize
1260 \begin{verbatim}
1261 FileSet {
1262   Name = "Bad example"
1263   Include {
1264     Options { onefs=no }
1265     File = /mnt/matou
1266   }
1267 }
1268 \end{verbatim}
1269 \normalsize
1270
1271 you will be backing up an NFS mounted partition ({\bf /mnt/matou}), and since
1272 {\bf onefs} is set to {\bf no}, Bacula will traverse file systems. Now if {\bf
1273 /mnt/matou} has the current machine's file systems mounted, as is often the
1274 case, you will get yourself into a recursive loop and the backup will never
1275 end. 
1276
1277 As a final example, let's say that you have only one or two 
1278 subdirectories of /home that you want to backup.  For example,
1279 you want to backup only subdirectories beginning with the letter
1280 a and the letter b -- i.e. /home/a* and /home/b*.  Now, you might first
1281 try:
1282 \footnotesize
1283 \begin{verbatim}
1284 FileSet {
1285   Name = "Full Set"
1286   Include {
1287      Options {
1288         wilddir = "/home/a*"
1289         wilddir = "/home/b*"
1290      }
1291      File = /home
1292   }
1293 }
1294 \end{verbatim}
1295 \normalsize
1296
1297 The problem is that the above will include everything in /home.  To get
1298 things to work correctly, you need to start with the idea of exclusion
1299 instead of inclusion.  So, you could simply exclude all directories
1300 except the two you want to use:
1301 \footnotesize
1302 \begin{verbatim}
1303 FileSet {
1304   Name = "Full Set"
1305   Include {
1306      Options {
1307         RegexDir = "^/home/[c-z]"
1308         exclude = yes
1309      }
1310      File = /home
1311   }
1312 }
1313 \end{verbatim}
1314 \normalsize
1315
1316 And assuming that all subdirectories start with a lowercase letter, this
1317 would work.
1318
1319 An alternative would be to include the two subdirectories desired and
1320 exclude everything else:
1321 \footnotesize
1322 \begin{verbatim}
1323 FileSet {
1324   Name = "Full Set"
1325   Include {
1326      Options {
1327         wilddir = "/home/a*"
1328         wilddir = "/home/b*"
1329      }
1330      Options {
1331         RegexDir = ".*"
1332         exclude = yes
1333      }
1334      File = /home
1335   }
1336 }
1337 \end{verbatim}
1338 \normalsize
1339
1340 \section{Backing up Raw Partitions}
1341 \index[general]{Backing up!Partitions }
1342 \index[general]{Backing up Raw Partitions }
1343
1344 The following FileSet definition will backup a raw partition: 
1345
1346 \footnotesize
1347 \begin{verbatim}
1348 FileSet {
1349   Name = "RawPartition"
1350   Include {
1351     Options { sparse=yes }
1352     File = /dev/hda2
1353   }
1354 }
1355 \end{verbatim}
1356 \normalsize
1357
1358 While backing up and restoring a raw partition, you should ensure that no
1359 other process including the system is writing to that partition. As a
1360 precaution, you are strongly urged to ensure that the raw partition is not
1361 mounted or is mounted read-only. If necessary, this can be done using the {\bf
1362 RunBeforeJob} directive. 
1363
1364
1365 \section{Excluding Files and Directories}
1366 \index[general]{Directories!Excluding Files and }
1367 \index[general]{Excluding Files and Directories }
1368
1369 You may also include full filenames or directory names in addition to using
1370 wild-cards and {\bf Exclude=yes} in the Options resource as specified above by
1371 simply including the files to be excluded in an Exclude resource within the
1372 FileSet. For example: 
1373
1374 \footnotesize
1375 \begin{verbatim}
1376 FileSet {
1377   Name = Exclusion_example
1378   Include {
1379     Options {
1380       Signature = SHA1
1381     }
1382     File = /
1383     File = /boot
1384     File = /home
1385     File = /rescue
1386     File = /usr
1387   }
1388   Exclude {
1389     File = /proc
1390     File = /tmp
1391     File = .journal
1392     File = .autofsck
1393   }
1394 }
1395 \end{verbatim}
1396 \normalsize
1397
1398 \label{win32}
1399 \section{Windows FileSets}
1400 \index[general]{Windows FileSets }
1401 \index[general]{FileSets!Windows }
1402 If you are entering Windows file names, the directory path may be preceded by
1403 the drive and a colon (as in c:). However, the path separators must be
1404 specified in Unix convention (i.e. forward slash (/)). If you wish to include
1405 a quote in a file name, precede the quote with a backslash
1406 (\textbackslash{}). For example you might use the following
1407 for a Windows machine to backup the "My Documents" directory: 
1408
1409 \footnotesize
1410 \begin{verbatim}
1411 FileSet {
1412   Name = "Windows Set"
1413   Include {
1414     Options {
1415        WildFile = "*.obj"
1416        WildFile = "*.exe"
1417        exclude = yes
1418      }
1419      File = "c:/My Documents"
1420   }
1421 }
1422 \end{verbatim}
1423 \normalsize
1424
1425 For exclude lists to work correctly on Windows, you must observe the following
1426 rules: 
1427
1428 \begin{itemize}
1429 \item Filenames are case sensitive, so you must use the correct case.  
1430 \item To 2~exclude a directory, you must not have a trailing slash on the 
1431    directory name.  
1432 \item I2~f you have spaces in your filename, you must enclose the entire name 
1433    in double-quote characters ("). Trying to use a backslash before  the space
1434    will not work.  
1435 \item If you are using the old Exclude syntax (noted below), you may not
1436    specify a drive letter in the exclude.  The new syntax noted above
1437    should work fine including driver letters.
1438 \end{itemize}
1439
1440 Thanks to Thiago Lima for summarizing the above items for us. If you are
1441 having difficulties getting includes or excludes to work, you might want to
1442 try using the {\bf estimate job=xxx listing} command documented in the 
1443 \ilink{Console chapter}{estimate} of this manual. 
1444
1445 On Win32 systems, if you move a directory or file or rename a file into the
1446 set of files being backed up, and a Full backup has already been made, Bacula
1447 will not know there are new files to be saved during an Incremental or
1448 Differential backup (blame Microsoft, not me). To avoid this problem, please
1449 {\bf copy} any new directory or files into the backup area. If you do not have
1450 enough disk to copy the directory or files, move them, but then initiate a
1451 Full backup. 
1452
1453
1454 \paragraph*{A Windows Example FileSet}
1455 \index[general]{FileSet!Windows Example }
1456 \index[general]{Windows Example FileSet }
1457
1458 The following example was contributed by Russell Howe. Please note that
1459 for presentation purposes, the lines beginning with Data and Internet 
1460 have been wrapped and should included on the previous line with one
1461 space.
1462
1463 \footnotesize
1464 \begin{verbatim}
1465 This is my Windows 2000 fileset:
1466 FileSet {
1467  Name = "Windows 2000"
1468  Include {
1469   Options {
1470    signature = MD5
1471    Exclude = yes
1472    IgnoreCase = yes
1473    # Exclude Mozilla-based programs' file caches
1474    WildDir = "[A-Z]:/Documents and Settings/*/Application 
1475 Data/*/Profiles/*/*/Cache"
1476    WildDir = "[A-Z]:/Documents and Settings/*/Application 
1477 Data/*/Profiles/*/*/Cache.Trash"
1478    WildDir = "[A-Z]:/Documents and Settings/*/Application
1479 Data/*/Profiles/*/*/ImapMail"
1480
1481    # Exclude user's registry files - they're always in use anyway.
1482    WildFile = "[A-Z]:/Documents and Settings/*/Local Settings/Application
1483 Data/Microsoft/Windows/usrclass.*"
1484    WildFile = "[A-Z]:/Documents and Settings/*/ntuser.*"
1485
1486    # Exclude directories full of lots and lots of useless little files
1487    WildDir = "[A-Z]:/Documents and Settings/*/Cookies"
1488    WildDir = "[A-Z]:/Documents and Settings/*/Recent"
1489    WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/History"
1490    WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temp"
1491    WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temporary
1492 Internet Files"
1493
1494    # These are always open and unable to be backed up
1495    WildFile = "[A-Z]:/Documents and Settings/All Users/Application
1496 Data/Microsoft/Network/Downloader/qmgr[01].dat"
1497
1498    # Some random bits of Windows we want to ignore
1499    WildFile = "[A-Z]:/WINNT/security/logs/scepol.log"
1500    WildDir = "[A-Z]:/WINNT/system32/config"
1501    WildDir = "[A-Z]:/WINNT/msdownld.tmp"
1502    WildDir = "[A-Z]:/WINNT/Internet Logs"
1503    WildDir = "[A-Z]:/WINNT/$Nt*Uninstall*"
1504    WildDir = "[A-Z]:/WINNT/sysvol"
1505    WildFile = "[A-Z]:/WINNT/cluster/CLUSDB"
1506    WildFile = "[A-Z]:/WINNT/cluster/CLUSDB.LOG"
1507    WildFile = "[A-Z]:/WINNT/NTDS/edb.log"
1508    WildFile = "[A-Z]:/WINNT/NTDS/ntds.dit"
1509    WildFile = "[A-Z]:/WINNT/NTDS/temp.edb"
1510    WildFile = "[A-Z]:/WINNT/ntfrs/jet/log/edb.log"
1511    WildFile = "[A-Z]:/WINNT/ntfrs/jet/ntfrs.jdb"
1512    WildFile = "[A-Z]:/WINNT/ntfrs/jet/temp/tmp.edb"
1513    WildFile = "[A-Z]:/WINNT/system32/CPL.CFG"
1514    WildFile = "[A-Z]:/WINNT/system32/dhcp/dhcp.mdb"
1515    WildFile = "[A-Z]:/WINNT/system32/dhcp/j50.log"
1516    WildFile = "[A-Z]:/WINNT/system32/dhcp/tmp.edb"
1517    WildFile = "[A-Z]:/WINNT/system32/LServer/edb.log"
1518    WildFile = "[A-Z]:/WINNT/system32/LServer/TLSLic.edb"
1519    WildFile = "[A-Z]:/WINNT/system32/LServer/tmp.edb"
1520    WildFile = "[A-Z]:/WINNT/system32/wins/j50.log"
1521    WildFile = "[A-Z]:/WINNT/system32/wins/wins.mdb"
1522    WildFile = "[A-Z]:/WINNT/system32/wins/winstmp.mdb"
1523
1524    # Temporary directories & files
1525    WildDir = "[A-Z]:/WINNT/Temp"
1526    WildDir = "[A-Z]:/temp"
1527    WildFile = "*.tmp"
1528    WildDir = "[A-Z]:/tmp"
1529    WildDir = "[A-Z]:/var/tmp"
1530
1531    # Recycle bins
1532    WildDir = "[A-Z]:/RECYCLER"
1533
1534    # Swap files
1535    WildFile = "[A-Z]:/pagefile.sys"
1536
1537    # These are programs and are easier to reinstall than restore from
1538    # backup
1539    WildDir = "[A-Z]:/cygwin"
1540    WildDir = "[A-Z]:/Program Files/Grisoft"
1541    WildDir = "[A-Z]:/Program Files/Java"
1542    WildDir = "[A-Z]:/Program Files/Java Web Start"
1543    WildDir = "[A-Z]:/Program Files/JavaSoft"
1544    WildDir = "[A-Z]:/Program Files/Microsoft Office"
1545    WildDir = "[A-Z]:/Program Files/Mozilla Firefox"
1546    WildDir = "[A-Z]:/Program Files/Mozilla Thunderbird"
1547    WildDir = "[A-Z]:/Program Files/mozilla.org"
1548    WildDir = "[A-Z]:/Program Files/OpenOffice*"
1549   }
1550
1551   # Our Win2k boxen all have C: and D: as the main hard drives.
1552   File = "C:/"
1553   File = "D:/"
1554  }
1555 }
1556 \end{verbatim}
1557 \normalsize
1558
1559 Note, the three line of the above Exclude were split to fit on the document
1560 page, they should be written on a single line in real use. 
1561
1562 \paragraph*{Windows NTFS Naming Considerations}
1563 \index[general]{Windows NTFS Naming Considerations }
1564 \index[general]{Considerations!Windows NTFS Naming }
1565
1566 NTFS filenames containing Unicode characters should now be supported
1567 as of version 1.37.30 or later.
1568
1569 \section{Testing Your FileSet}
1570 \index[general]{FileSet!Testing Your }
1571 \index[general]{Testing Your FileSet }
1572
1573 If you wish to get an idea of what your FileSet will really backup or if your
1574 exclusion rules will work correctly, you can test it by using the {\bf
1575 estimate} command in the Console program. See the 
1576 \ilink{estimate}{estimate} in the Console chapter of this
1577 manual.
1578
1579 As an example, suppose you add the following test FileSet:
1580
1581 \footnotesize
1582 \begin{verbatim}
1583 FileSet {
1584   Name = Test
1585   Include {
1586     File = /home/xxx/test
1587     Options {
1588        regex = ".*\.c$"
1589     }
1590   }
1591 }
1592 \end{verbatim}
1593 \normalsize
1594
1595 You could then add some test files to the directory {\bf /home/xxx/test}
1596 and use the following command in the console:
1597
1598 \footnotesize
1599 \begin{verbatim}
1600 estimate job=<any-job-name> listing client=<desired-client> fileset=Test
1601 \end{verbatim}
1602 \normalsize
1603
1604 to give you a listing of all files that match.