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