Final changes

[bacula/docs] / docs / manual / fileset.tex

%%
%%

\subsection*{The FileSet Resource}
\label{FileSetResource}
\index[general]{Resource!FileSet }
\index[general]{FileSet Resource }
\addcontentsline{toc}{subsection}{FileSet Resource}

The FileSet resource defines what files are to be included or excluded in a
backup job.  A {\bf FileSet} resource is required for each backup Job.  It
consists of a list of files or directories to be included, a list of files
or directories to be excluded and the various backup options such as
compression, encryption, and signatures that are to be applied to each
file.

Any change to the list of the included files will cause Bacula to
automatically create a new FileSet (defined by the name and an MD5 checksum
of the Include/Exclude contents).  Each time a new FileSet is created,
Bacula will ensure that the next backup is always a Full save.

\begin{description}

\item [FileSet]
\index[dir]{FileSet }
Start of the FileSet resource. One {\bf FileSet}  resource must be
defined for each Backup job.

\item [Name = \lt{}name\gt{}]
\index[dir]{Name  }
The name of the FileSet resource.  This directive is required. 

\item [Ignore FileSet Changes = \lt{}yes|no\gt{}]
\index[dir]{Ignore FileSet Changes}
   If this directive is set to {\bf yes}, any changes you make to the  FileSet
   Include or Exclude lists will be ignored and not cause Bacula  to immediately
   perform a Full backup. The default is {\bf no}, in which  case, if you change
   the Include or Exclude, Bacula will force a Full  backup to ensure that
   everything is properly backed up. It is not recommended  to set this directive
   to yes. This directive is available in Bacula  version 1.35.4 or later. 

\item [Enable VSS = \lt{}yes|no\gt{}]
\index[dir]{Enable VSS}
  If this directive is set to {\bf yes} the File daemon will be notified
  that the user wants to use a Volume Shadow Copy Service (VSS) backup
  for this job. The default is {\bf no}. This directive is effective
  only for VSS enabled Win32 File daemons. It permits a consistent copy
  of open files to be made for cooperating writer applications, and for
  applications that are not VSS away, Bacula can at least copy open files.
  For more information, please see the
  \ilink{Windows}{VSS} chapter of this manual.

\item [Include \{ Options \{\lt{}file-options\gt{}\} ...;
   \lt{}file-list\gt{} \} ]
\index[dir]{Include \{ [ Options \{\lt{}file-options\gt{}\} ...]
   \lt{}file-list\gt{} \}  }

\item [Options \{ \lt{}file-options\gt{} \} ]
\index[dir]{Options  \{ \lt{}file-options\gt{} \}  }

\item [Exclude \{ \lt{}file-list\gt{} \}]
\index[dir]{Exclude \{ \lt{}file-list\gt{} \} }

\end{description}

The Include resource must contain a list of directories and/or files to be
processed in the backup job.  Normally, all files found in all
subdirectories of any directory in the Include File list will be backed up.
Note, see below for the definition of \lt{}file-list\gt{}. 
The Include resource may also contain one or more Options resources that
specify options such as compression to be applied to all or any subset of
the files found for backup.

There can be any number of {\bf Include} resources within the FileSet, each
having its own list of directories or files to be backed up and the backup
options defined by one or more Options resources.  The {\bf file-list}
consists of one file or directory name per line.  Directory names should be
specified without a trailing slash with Unix path notation.

You should always specify a full path for every directory and file that you
list in the FileSet.  In addition, on Windows machines, you should {\bf
always} prefix the directory or filename with the drive specification in
lower case (e.g.  {\bf c:/xxx}) using Unix directory name separators
(forward slash).

Bacula's default for processing directories is to recursively descend in
the directory saving all files and subdirectories.  Bacula will not by
default cross filesystems (or mount points in Unix parlance).  This means
that if you specify the root partition (e.g.  {\bf /}), Bacula will save
only the root partition and not any of the other mounted filesystems.
Similarly on Windows systems, you must explicitly specify each of the
drives you want saved (e.g.
{\bf c:/} and {\bf d:/} ...). In addition, at least for Windows systems, you
will most likely want to enclose each specification within double quotes
particularly if the directory (or file) name contains spaces. The {\bf df}
command on Unix systems will show you which mount points you must specify to
save everything. See below for an example. 

Take special care not to include a directory twice or Bacula will backup
the same files two times wasting a lot of space on your archive device.
Including a directory twice is very easy to do.  For example:

\footnotesize
\begin{verbatim}
  Include {
    File = /
    File = /usr
    Options { compression=GZIP }
  }
\end{verbatim}
\normalsize

on a Unix system where /usr is a subdirectory (rather than a mounted
filesystem) will cause /usr to be backed up twice. In this case, on Bacula
versions prior to 1.32f-5-09Mar04 due to a bug, you will not be able to
restore hard linked files that were backed up twice. 

If you have used Bacula prior to version 1.36.3, you will note three things in
the new FileSet syntax: 

\begin{enumerate}
\item There is no equal sign (=) after the Include and before the opening
   brace (\{). The same is true for the Exclude. 
\item Each directory (or filename) to be included or excluded is preceded by a {\bf File
   =}.  Previously they were simply listed on separate lines. 
\item The options that previously appeared on the Include line now must be
   specified within their own Options resource.
\item The Exclude resource does not accept Options. 
\item When using wild-cards or regular expressions, directory names are
   always terminated with a slash (/) and filenames have no trailing slash.
\end{enumerate}

The Options resource is optional, but when specified, it will contain a
list of {\bf keyword=value} options to be applied to the file-list.
See below for the definition of file-list.    
Multiple Options resources may be specified one after another.  As the
files are found in the specified directories, the Options will applied to
the filenames to determine if and how the file should be backed up.  The
Options resources are applied in the order they are specified in the
FileSet until the first one that matches.  

Once Bacula determines that the Options resource matches the file under
consideration, that file will be saved without looking at any other Options
resources that may be present.  This means that any wild cards must appear
before an Options resource without wild cards.

If for some reason, Bacula applies all the Options resources to a file
under consideration for backup, but there are no matches (generally because
of wild cards that don't match), Bacula as a default will then backup the
file.  This is quite logical if you consider the case of no Options, where
you want everything to be backed up.  

However, one additional point is that
in the case that no match was found, Bacula will use the options found in
the last Options resource.  As a consequence, if you want a particular set
of "default" options, you should put them in an Options resource after
any other Options.

It is a good idea to put all your wild-card and regex expressions inside
double quotes to prevent conf file scanning problems.

This is perhaps a bit overwhelming, so there are a number of examples included 
below to illustrate how this works.

The directives within an Options resource may be one of the following: 

\begin{description}

\item [compression=GZIP]
\index[fd]{compression }
   All files saved will be software compressed using the GNU ZIP compression
   format. The  compression is done on a file by file basis by the File daemon. 
   If there is a problem reading the tape in a  single record of a file, it will
   at most affect that file and none  of the other files on the tape. Normally
   this option is {\bf not} needed  if you have a modern tape drive as the drive
   will do its own  compression. In fact, if you specify software compression at
   the same time you have hardware compression turned on, your files  may
   actually take more space on the volume.  

   Software compression is very important if you are writing  your Volumes to a
   file, and it can also be helpful if you have a fast computer but a slow
   network, otherwise it is generally better to rely your tape drive's hardware
   compression. As noted above, it is not generally a good idea to do both software 
   and hardware compression.

   Specifying {\bf GZIP} uses the default compression level six (i.e. {\bf GZIP}
   is identical to {\bf GZIP6}). If you  want a different compression level (1
   through 9), you can specify  it by appending the level number with no
   intervening spaces  to {\bf GZIP}. Thus {\bf compression=GZIP1} would give
   minimum  compression but the fastest algorithm, and {\bf compression=GZIP9} 
   would give the highest level of compression, but requires more  computation.
   According to the GZIP documentation, compression levels  greater than 6
   generally give very little extra compression and are rather CPU intensive. 

\item [signature=SHA1]
\index[fd]{signature }
   An SHA1 signature will be computed for all  The SHA1 algorithm is purported to
   be some  what slower than the MD5 algorithm, but at the same time is 
   significantly better from a cryptographic point of view (i.e.  much fewer
   collisions, much lower probability of being hacked.)  It adds four more bytes
   than the MD5 signature.  We strongly recommend that either this option  or MD5
   be specified as a default for all files. Note, only  one of the two options
   MD5 or SHA1 can be computed for any file. 

\item [signature=MD5]
   \index[fd]{signature }
   An MD5 signature will be computed for all  files saved. Adding this option
   generates about 5\% extra overhead  for each file saved. In addition to the
   additional CPU time,  the MD5 signature adds 16 more bytes per file to your
   catalog.  We strongly recommend that this option or the SHA1 option  be
   specified as a default for all files. 

\item [verify=\lt{}options\gt{}]
\index[fd]{verify }
   The options letters specified are used  when running a {\bf Verify
   Level=Catalog} as well as the  {\bf DiskToCatalog} level job. The options
   letters may be any  combination of the following:  

      \begin{description}

      \item {\bf i}
      compare the inodes  

      \item {\bf p}
      compare the permission bits  

      \item {\bf n}
      compare the number of links  

      \item {\bf u}
      compare the user id  

      \item {\bf g}
      compare the group id  

      \item {\bf s}
      compare the size  

      \item {\bf a}
      compare the access time  

      \item {\bf m}
      compare the modification time (st\_mtime)  

      \item {\bf c}
      compare the change time (st\_ctime)  

      \item {\bf s}
      report file size decreases  

      \item {\bf 5}
      compare the MD5 signature  

      \item {\bf 1}
      compare the SHA1 signature  
      \end{description}

   A useful set of general options on the {\bf Level=Catalog}  or {\bf
   Level=DiskToCatalog}  verify is {\bf pins5} i.e. compare permission bits,
   inodes, number  of links, size, and MD5 changes. 

\item [onefs=yes|no]
\index[fd]{onefs}
   If set to {\bf yes} (the default), {\bf Bacula}  will remain on a single file
   system. That is it will not backup  file systems that are mounted on a
   subdirectory. If you are using a *nix system, you may not even be aware 
   that there are several different filesystems as they are often
   automatically mounted by the OS (e.g. /dev, /net, /sys, /proc, ...).
   With Bacula 1.38.0 or later, it will inform you when it decides not
   to traverse into another filesystem. This can be very useful if you
   forgot to backup a particular partition.  An example of the
   informational message in the job report is:

\footnotesize
\begin{verbatim}
rufus-fd: Filesystem change prohibited. Will not descend into /misc
rufus-fd: Filesystem change prohibited. Will not descend into /net
rufus-fd: Filesystem change prohibited. Will not descend into /var/lib/nfs/rpc_pipefs
rufus-fd: Filesystem change prohibited. Will not descend into /selinux
rufus-fd: Filesystem change prohibited. Will not descend into /sys
rufus-fd: Filesystem change prohibited. Will not descend into /dev
rufus-fd: Filesystem change prohibited. Will not descend into /home
\end{verbatim}
\normalsize
   If you wish to backup multiple filesystems, you can  explicitly
   list each filesystem you want saved.  Otherwise, if you set the onefs option
   to {\bf no}, Bacula will backup  all mounted file systems (i.e. traverse mount
   points) that  are found within the {\bf FileSet}. Thus if  you have NFS or
   Samba file systems mounted on a directory listed  in your FileSet, they will
   also be backed up. Normally, it is  preferable to set {\bf onefs=yes} and to
   explicitly name  each filesystem you want backed up. Explicitly naming  the
   filesystems you want backed up avoids the possibility  of getting into a
   infinite loop recursing filesystems.  Another possiblity is to 
   use {\bf onefs=no} and to set {\bs fstype=ext2, ...}.             
   See the example below for more details. 

   If you think that Bacula should be backing up a particular directory
   and it is not, and you have {\bf onefs=no} set, before you complain,
   please do:

\footnotesize
\begin{verbatim}
  stat /
  stat <filesystem>
\end{verbatim}
\normalsize

where you replace {\bf filesystem} with the one in question.  If the 
{\bf Device:} number is different for / and for your filesystem, then they
are on different filesystems.  E.g.
\footnotesize
\begin{verbatim}
stat /
  File: `/'
  Size: 4096            Blocks: 16         IO Block: 4096   directory
Device: 302h/770d       Inode: 2           Links: 26
Access: (0755/drwxr-xr-x)  Uid: (    0/    root)   Gid: (    0/    root)
Access: 2005-11-10 12:28:01.000000000 +0100
Modify: 2005-09-27 17:52:32.000000000 +0200
Change: 2005-09-27 17:52:32.000000000 +0200

stat /net
  File: `/home'
  Size: 4096            Blocks: 16         IO Block: 4096   directory
Device: 308h/776d       Inode: 2           Links: 7
Access: (0755/drwxr-xr-x)  Uid: (    0/    root)   Gid: (    0/    root)
Access: 2005-11-10 12:28:02.000000000 +0100
Modify: 2005-11-06 12:36:48.000000000 +0100
Change: 2005-11-06 12:36:48.000000000 +0100
\end{verbatim}
\normalsize

   Also be aware that even if you include {\bf /home} in your list
   of files to backup, as you most likely should, you will get the
   informational message about Filesystem change prohibited when Bacula is
   processing the {\bf /} directory.


\label{portable}
\item [portable=yes|no]
\index[dir]{portable }
   If set to {\bf yes} (default is  {\bf no}), the Bacula File daemon will backup
   Win32 files  in a portable format, but not all Win32 file attributes  will be
   saved and restored. By default, this option is set to  {\bf no}, which means
   that on Win32 systems, the data will  be backed up using Windows API calls and
   on WinNT/2K/XP,  all the security and ownership attributes will be properly
   backed up  (and restored). However this format is not portable to other 
   systems -- e.g. Unix, Win95/98/Me. When backing up Unix systems, this  option
   is ignored, and unless you have a specific need to  have portable backups, we
   recommend accept the default  ({\bf no}) so that the maximum information
   concerning  your files is saved. 

\item [recurse=yes|no]
\index[fd]{recurse }
   If set to {\bf yes} (the default),  Bacula will recurse (or descend) into all
   subdirectories  found unless the directory is explicitly excluded  using an
   {\bf exclude} definition.  If you set {\bf recurse=no}, Bacula will save the 
   subdirectory entries, but not descend into the  subdirectories, and thus will
   not save the files or  directories contained in the subdirectories. Normally,
   you  will want the default ({\bf yes}). 

\item [sparse=yes|no]
\index[dir]{sparse }
   Enable special code that checks for sparse files such as created by
   ndbm.  The default is {\bf no}, so no checks are made for sparse files.
   You may specify {\bf sparse=yes} even on files that are not sparse file.
   No harm will be done, but there will be a small additional overhead to
   check for buffers of all zero, and a small additional amount of space on
   the output archive will be used to save the seek address of each
   non-zero record read.

   {\bf Restrictions:} Bacula reads files in 32K buffers.  If the whole
   buffer is zero, it will be treated as a sparse block and not written to
   tape.  However, if any part of the buffer is non-zero, the whole buffer
   will be written to tape, possibly including some disk sectors (generally
   4098 bytes) that are all zero.  As a consequence, Bacula's detection of
   sparse blocks is in 32K increments rather than the system block size.
   If anyone considers this to be a real problem, please send in a request
   for change with the reason.

   If you are not familiar with sparse files, an example is say a file
   where you wrote 512 bytes at address zero, then 512 bytes at address 1
   million.  The operating system will allocate only two blocks, and the
   empty space or hole will have nothing allocated.  However, when you read
   the sparse file and read the addresses where nothing was written, the OS
   will return all zeros as if the space were allocated, and if you backup
   such a file, a lot of space will be used to write zeros to the volume.
   Worse yet, when you restore the file, all the previously empty space
   will now be allocated using much more disk space.  By turning on the
   {\bf sparse} option, Bacula will specifically look for empty space in
   the file, and any empty space will not be written to the Volume, nor
   will it be restored.  The price to pay for this is that Bacula must
   search each block it reads before writing it.  On a slow system, this
   may be important.  If you suspect you have sparse files, you should
   benchmark the difference or set sparse for only those files that are
   really sparse.

\label{readfifo}
\item [readfifo=yes|no]
\index[fd]{readfifo }
   If enabled, tells the Client to read the data on a backup and write the
   data on a restore to any FIFO (pipe) that is explicitly mentioned in the
   FileSet.  In this case, you must have a program already running that
   writes into the FIFO for a backup or reads from the FIFO on a restore.
   This can be accomplished with the {\bf RunBeforeJob} directive.  If this
   is not the case, Bacula will hang indefinitely on reading/writing the
   FIFO. When this is not enabled (default), the Client simply saves the
   directory entry for the FIFO.

   Unfortunately, when Bacula runs a RunBeforeJob, it waits until that
   script terminates, and if the script accesses the FIFO to write   
   into the it, the Bacula job will block and everything will stall.
   However, Vladimir Stavrinov as supplied tip that allows this feature   
   to work correctly.  He simply adds the following to the beginning
   of the RunBeforeJob script:

\begin{verbatim}
   exec > /dev/null
\end{verbatim}


\item [mtimeonly=yes|no]
\index[dir]{mtimeonly }
   If enabled, tells the Client that the selection of files during
   Incremental and Differential backups should based only on the st\_mtime
   value in the stat() packet.  The default is {\bf no} which means that
   the selection of files to be backed up will be based on both the
   st\_mtime and the st\_ctime values.  In general, it is not recommended
   to use this option.

\item [keepatime=yes|no]
\index[dir]{keepatime }
   The default is {\bf no}.  When enabled, Bacula will reset the st\_atime
   (access time) field of files that it backs up to their value prior to
   the backup.  This option is not generally recommended as there are very
   few programs that use st\_atime, and the backup overhead is increased
   because of the additional system call necessary to reset the times.
   However, for some files, such as mailboxes, when Bacula backs up the
   file, the user will notice that someone (Bacula) has accessed the
   file. In this, case keepatime can be useful.
   (I'm not sure this works on Win32).

   Note, if you use this feature, when Bacula resets the access time, the
   change time (st\_ctime) will automatically be modified by the system,
   so on the next incremental job, the file will be backed up even if
   it has not changed. As a consequence, you will probably also want
   to use {\bf mtimeonly = yes} as well as keepatime (thanks to
   Rudolf Cejka for this tip).

\item [hardlinks=yes|no]
\index[dir]{hardlinks}
   When enabled (default), this directive will cause hard inks to be 
   backed up. However, the File daemon keeps track of hard linked files and
   will backup the data only once. The process of keeping track of the 
   hard links can be quite expensive if you have lots of them (tens of
   thousands or more). This doesn't occur on normal Unix systems, but if
   you use a program like BackupPC, it can create hundreds of thousands, or
   even millions of hard links. Backups become very long and the File daemon
   will consume a lot of CPU power checking hard links.  In such a case,
   set {\bf hardlinks=no} and hard links will not be backed up.  Note, using
   this option will most likely backup more data and on a restore the file
   system will not be restored identically to the original.

\item [wild=\lt{}string\gt{}]
\index[dir]{wild }
   Specifies a wild-card string to be applied to the filenames and
   directory names.  Note, if {\bf Exclude} is not enabled, the wild-card
   will select which files are to be included.  If {\bf Exclude=yes} is
   specified, the wild-card will select which files are to be excluded.
   Multiple wild-card directives may be specified, and they will be applied
   in turn until the first one that matches.  Note, if you exclude a
   directory, no files or directories below it will be matched.
   It is recommended to enclose the string in double quotes.

\item [wildfile=\lt{}string\gt{}]
\index[dir]{wildfile }
   Specifies a wild-card string to be applied to filenames only.  No
   directories will be matched by this directive.  Note, if {\bf Exclude}
   is not enabled, the wild-card will select which files are to be
   included.  If {\bf Exclude=yes} is specified, the wild-card will select
   which files are to be excluded.  Multiple wild-card directives may be
   specified, and they will be applied in turn until the first one that
   matches.
   It is recommended to enclose the string in double quotes.

\item [wilddir=\lt{}string\gt{}]
\index[dir]{wilddir }
   Specifies a wild-card string to be applied to directory names only.  No
   filenames will be matched by this directive.  Note, if {\bf Exclude} is
   not enabled, the wild-card will select directories files are to be
   included.  If {\bf Exclude=yes} is specified, the wild-card will select
   which files are to be excluded.  Multiple wild-card directives may be
   specified, and they will be applied in turn until the first one that
   matches.  Note, if you exclude a directory, no files or directories
   below it will be matched.
   It is recommended to enclose the string in double quotes.


\item [regex=\lt{}string\gt{}]
\index[dir]{regex }
   Specifies a POSIX extended regular expression to be applied to the
   filenames and directory names. 
   This directive is available in version 1.35 and later.  If {\bf
   Exclude} is not enabled, the regex will select which files are to be
   included.  If {\bf Exclude=yes} is specified, the regex will select
   which files are to be excluded.  Multiple regex directives may be
   specified within an Options resource, and they will be applied in turn
   until the first one that matches. Note, if you exclude a
   directory, no files or directories below it will be matched.
   It is recommended to enclose the string in double quotes.

\item [regexfile=\lt{}string\gt{}]
\index[dir]{regexfile }
   Specifies a POSIX extended regular expression to be applied to filenames
   only.  No directories will be matched by this directive.  Note, if {\bf
   Exclude} is not enabled, the regex will select which files are to be
   included.  If {\bf Exclude=yes} is specified, the regex will select
   which files are to be excluded.  Multiple regex directives may be
   specified, and they will be applied in turn until the first one that
   matches.
   It is recommended to enclose the string in double quotes.

\item [regexdir=\lt{}string\gt{}]
\index[dir]{regexdir }
   Specifies a POSIX extended regular expression to be applied to directory
   names only.  No filenames will be matched by this directive.  Note, if
   {\bf Exclude} is not enabled, the regex will select directories
   files are to be included.  If {\bf Exclude=yes} is specified, the
   regex will select which files are to be excluded.  Multiple
   regex directives may be specified, and they will be applied in turn
   until the first one that matches.  Note, if you exclude a directory, no
   files or directories below it will be matched.
   It is recommended to enclose the string in double quotes.

\item [exclude=yes|no]
\index[dir]{exclude }
   The default is {\bf no}. When  enabled, any files matched within the Options
   will be  excluded from the backup. 

\label{ACLSupport}

\item [aclsupport=yes|no]
\index[dir]{aclsupport }
   The default is {\bf no}.  If this option is set to yes, and you have the
   POSIX {\bf libacl} installed on your system, Bacula will backup the file
   and directory UNIX Access Control Lists (ACL) as defined in IEEE Std
   1003.1e draft 17 and "POSIX.1e" (abandoned).  This feature is
   available on UNIX only and depends on the ACL library.  Bacula is
   automatically compiled with ACL support if the {\bf libacl} library is
   installed on your system (shown in config.out).  While restoring the
   files Bacula will try to restore the ACLs, if there is no ACL support
   available on the system, Bacula restores the files and directories but
   not the ACL information.  Please note, if you backup an EXT3 or XFS
   filesystem with ACLs, then you restore them to a different filesystem
   (perhaps reiserfs) that does not have ACLs, the ACLs will be ignored.

\item [ignore case=yes|no]
\index[dir]{ignore case }
   The default is {\bf no}, except on Windows systems where the default
   is {\bf yes}. When this directive is set to {\bf yes} all the case
   of character will be ignored in wild-card and regex comparisons.
   That is an uppercase A will match a lowercase a.

\item [fstype=filesystem-type]
\index[dir]{fstype }
   This option allows you to select files and directories by the
   filesystem type.  The permitted filesystem-type names are:

   ext2, jfs, ntfs, proc, reiserfs, xfs, usbdevfs, sysfs, smbfs,
   iso9660.  For ext3 systems, use ext2.

   You may have multiple Fstype directives, and thus permit matching
   of multiple filesystem types within a single Options resource.  If
   the type specified on the fstype directive does not match the
   filesystem for a particular directive, that directory will not be
   backed up.  This directive can be used to prevent backing up
   non-local filesystems. Normally, when you use this directive, you
   would also set {\bf onefs=no} so that Bacula will traverse filesystems.

   This option is not implemented in Win32 systems.


\item [hfsplussupport=yes|no]
\index[dir]{hfsplussupport }
   This option allows you to turn on support for Mac OSX HFS plus 
   finder information.

\end{description}

{\bf \lt{}file-list\gt{}} is a list of directory and/or filename names
specified with a {\bf File =} directive. To include names containing spaces,
enclose the name between double-quotes. 

There are a number of special cases when specifying directories and files in a
{\bf file-list}. They are: 

\begin{itemize}
\item Any name preceded by an at-sign (@) is assumed to be the  name of a
   file, which contains a list of files each preceded by a "File =".  The
   named file is read once when the configuration file is parsed during the
   Director startup.  Note, that the file is read on the Director's machine
   and not on the Client's.  In fact, the @filename can appear anywhere
   within the conf file where a token would be read, and the contents of
   the named file will be logically inserted in the place of the @filename.
   What must be in the file depends on the location the @filename is
   specified in the conf file.  For example:

\footnotesize
\begin{verbatim}
Include {
  Options { compression=GZIP }
  @/home/files/my-files
}
\end{verbatim}
\normalsize

\item Any name beginning with a vertical bar (|) is  assumed to be the name of
   a program.  This program will be executed on the Director's machine at
   the time the Job starts (not when the Director reads the configuration
   file), and any output from that program will be assumed to be a list of
   files or directories, one per line, to be included.  

   This allows you to have a job that, for example, includes all the local
   partitions even if you change the partitioning by adding a disk.  The
   examples below show you how to do this.  However, please note two
   things: \\
   1.  if you want the local filesystems, you probably should be
   using the new {\bf fstype} directive, which was added in version 1.36.3 
   and set {\bf onefs=no}.
   \\

   2.  the exact syntax of the command needed in the examples below is very
   system dependent.  For example, on recent Linux systems, you may need to
   add the -P option, on FreeBSD systems, the options will be different as
   well.

   In general, you will need to prefix your command or commands with a {\bf
   sh -c} so that they are invoked by a shell.  This will not be the case
   if you are invoking a script as in the second example below.  Also, you
   must take care to escape (precede with a \textbackslash{}) wild-cards,
   shell character, and to ensure that any spaces in your command are
   escaped as well.  If you use a single quotes (') within a double quote
   ("), Bacula will treat everything between the single quotes as one field
   so it will not be necessary to escape the spaces.  In general, getting
   all the quotes and escapes correct is a real pain as you can see by the
   next example.  As a consequence, it is often easier to put everything in
   a file and simply use the file name within Bacula.  In that case the
   {\bf sh -c} will not be necessary providing the first line of the file
   is {\bf \#!/bin/sh}.

   As an  example: 

\footnotesize
\begin{verbatim}
 
Include {
   Options { signature = SHA1 }
   File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
      | awk \"{print \\$6}\"'"
}
\end{verbatim}
\normalsize

   will produce a list of all the local partitions on a RedHat Linux  system.
   Note, the above line was split, but should normally  be written on one line. 
   Quoting is a real problem because you must quote for Bacula  which consists of
   preceding every \textbackslash{} and every " with a \textbackslash{}, and 
   you must also quote for the shell command. In the end, it is probably  easier
   just to execute a small file with: 


\footnotesize
\begin{verbatim}
Include {
  Options {
    signature=MD5
  }
  File = "|my_partitions"
}
\end{verbatim}
\normalsize

   where my\_partitions has: 

\footnotesize
\begin{verbatim}
#!/bin/sh
df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
      | awk "{print \$6}"
\end{verbatim}
\normalsize

   If the vertical bar (|) in front of my\_partitions is preceded by a
   backslash as in \textbackslash{}|, the program will be executed on the
   Client's machine instead of on the Director's machine.
   Please note that if the filename is given within quotes, you
   will need to use two slashes.  An example, provided by John Donagher,
   that backs up all the local UFS partitions on a remote system is:

\footnotesize
\begin{verbatim}
FileSet {
  Name = "All local partitions"
  Include {
    Options { signature=SHA1; onefs=yes; }
    File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
  }
}
\end{verbatim}
\normalsize

   The above requires two backslash characters after the double quote (one
   preserves  the next one). If you are a Linux user, just change the {\bf ufs}
   to  {\bf ext3} (or your preferred filesystem type), and you will be in 
   business.  

   If you know what filesystems you have mounted on your system, e.g. 
   for RedHat Linux normally only ext2 and ext3, you can backup
   all local fileystems using something like:

\footnotesize
\begin{verbatim}
 
Include {
   Options { signature = SHA1; onfs=no; fstype=ext2 }
   File = /
}
\end{verbatim}
\normalsize


\item Any file-list item preceded by a less-than sign (\lt{})  will be taken
   to be a file. This file will be read on the  Director's machine at the time
   the Job starts, and the  data will be assumed to be a list of directories or
   files,  one per line, to be included. The names should start in  column 1 and
   should not be quoted even if they contain  spaces. This feature allows you to
   modify the external  file and change what will be saved without stopping and 
   restarting Bacula as would be necessary if using the @  modifier noted above.
   For example: 

\footnotesize
\begin{verbatim}
Include {
  Options { signature = SHA1 }
  File = "</home/files/local-filelist"
}
\end{verbatim}
\normalsize

   If you precede the less-than sign (\lt{}) with a backslash as in
   \textbackslash{}\lt{}, the file-list will be read on the Client machine
   instead of on the Director's machine.  Please note that if the filename
   is given within quotes, you will need to use two slashes.

\footnotesize
\begin{verbatim}
Include {
  Options { signature = SHA1 }
  File = "\\</home/xxx/filelist-on-client"
}
\end{verbatim}
\normalsize

\item If you explicitly specify a block device such as {\bf /dev/hda1},  then
   Bacula (starting with version 1.28) will assume that this  is a raw partition
   to be backed up. In this case, you are strongly  urged to specify a {\bf
   sparse=yes} include option, otherwise, you  will save the whole partition
   rather than just the actual data that  the partition contains. For example: 

\footnotesize
\begin{verbatim}
Include {
  Options { signature=MD5; sparse=yes }
  File = /dev/hd6
}
\end{verbatim}
\normalsize

   will backup the data in device /dev/hd6.  

   Ludovic Strappazon has pointed out that this feature can be  used to backup a
   full Microsoft Windows disk. Simply boot into  the system using a Linux Rescue
   disk, then load a statically  linked Bacula as described in the 
   \ilink{ Disaster Recovery Using Bacula}{_ChapterStart38} chapter of
   this manual. Then  save the whole disk partition. In the case of a disaster,
   you  can then restore the desired partition by again booting with  the rescue
   disk and doing a restore of the partition. 
   \item If you explicitly specify a FIFO device name (created with mkfifo),  and
   you add the option {\bf readfifo=yes} as an option, Bacula  will read the FIFO
   and back its data up to the Volume. For  example: 

\footnotesize
\begin{verbatim}
Include {
  Options {
    signature=SHA1
    readfifo=yes
  }
  File = /home/abc/fifo
}
\end{verbatim}
\normalsize

   if {\bf /home/abc/fifo} is a fifo device, Bacula will open the fifo,
   read it, and store all data thus obtained on the Volume.  Please note,
   you must have a process on the system that is writing into the fifo, or
   Bacula will hang, and after one minute of waiting, Bacula will give up
   and go on to the next file.  The data read can be anything since Bacula
   treats it as a stream.

   This feature can be an excellent way to do a "hot" backup of a very
   large database.  You can use the {\bf RunBeforeJob} to create the fifo
   and to start a program that dynamically reads your database and writes
   it to the fifo.  Bacula will then write it to the Volume.  Be sure to
   read the \ilink{readfifo section}{readfifo} that gives a
   tip to ensure that the RunBeforeJob does not block Bacula.

   During the restore operation, the inverse is true, after Bacula creates
   the fifo if there was any data stored with it (no need to explicitly
   list it or add any options), that data will be written back to the fifo.
   As a consequence, if any such FIFOs exist in the fileset to be restored,
   you must ensure that there is a reader program or Bacula will block, and
   after one minute, Bacula will time out the write to the fifo and move on
   to the next file.
\end{itemize}

\subsubsection*{FileSet Examples}
\index[general]{Examples!FileSet }
\index[general]{FileSet Examples}
\addcontentsline{toc}{subsection}{FileSet Examples}

The following is an example of a valid FileSet resource definition.  Note,
the first Include pulls in the contents of the file {\bf /etc/backup.list}
when Bacula is started (i.e.  the @), and that file must have each filename
to be backed up preceded by a {\bf File =} and on a separate line.

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Full Set"
  Include {
    Options {
      Compression=GZIP
      signature=SHA1
      Sparse = yes
    }
    @/etc/backup.list
  }
  Include {
     Options {
        wildfile = "*.o"
        wildfile = "*.exe"
        Exclude = yes
     }
     File = /root/myfile
     File = /usr/lib/another_file
  }
}
\end{verbatim}
\normalsize

In the above example, all the files contained in /etc/backup.list will
be compressed with GZIP compression, an SHA1 signature will be computed on the
file's contents (its data), and sparse file handling will apply. 

The two directories /root/myfile and /usr/lib/another\_file will also be saved
without any options, but all files in those directories with the extensions
{\bf .o} and {\bf .exe} will be excluded. 

Let's say that you now want to exclude the directory /tmp. The simplest way
to do so is to add an exclude directive that lists /tmp.  The example
above would then become:

\footnotesize 
\begin{verbatim}
FileSet {
  Name = "Full Set"
  Include {
    Options {
      Compression=GZIP
      signature=SHA1
      Sparse = yes
    }
    @/etc/backup.list
  }
  Include {
     Options {
        wildfile = "*.o"
        wildfile = "*.exe"
        Exclude = yes
     }
     File = /root/myfile
     File = /usr/lib/another_file
  }
  Exclude {
     File = /tmp
  }
}
\end{verbatim}
\normalsize


You can add wild-cards to the File directives listed in the Exclude
directory, but you need to take care because if you exclude a directory,
it and all files and directories below it will also be excluded.

Now lets take a slight variation on the above and suppose
you want to save all your whole filesystem except {\bf /tmp}. 
The problem that comes up is that Bacula will not normally
cross from one filesystem to another.
Doing a {\bf df} command, you get the following output: 

\footnotesize
\begin{verbatim}
[kern@rufus k]$ df
Filesystem      1k-blocks      Used Available Use% Mounted on
/dev/hda5         5044156    439232   4348692  10% /
/dev/hda1           62193      4935     54047   9% /boot
/dev/hda9        20161172   5524660  13612372  29% /home
/dev/hda2           62217      6843     52161  12% /rescue
/dev/hda8         5044156     42548   4745376   1% /tmp
/dev/hda6         5044156   2613132   2174792  55% /usr
none               127708         0    127708   0% /dev/shm
//minimatou/c$   14099200   9895424   4203776  71% /mnt/mmatou
lmatou:/          1554264    215884   1258056  15% /mnt/matou
lmatou:/home      2478140   1589952    760072  68% /mnt/matou/home
lmatou:/usr       1981000   1199960    678628  64% /mnt/matou/usr
lpmatou:/          995116    484112    459596  52% /mnt/pmatou
lpmatou:/home    19222656   2787880  15458228  16% /mnt/pmatou/home
lpmatou:/usr      2478140   2038764    311260  87% /mnt/pmatou/usr
deuter:/          4806936     97684   4465064   3% /mnt/deuter
deuter:/home      4806904    280100   4282620   7% /mnt/deuter/home
deuter:/files    44133352  27652876  14238608  67% /mnt/deuter/files
\end{verbatim}
\normalsize

And we see that there are a number of separate filesystems (/ /boot
/home /rescue /tmp and /usr not to mention mounted systems).
If you specify only {\bf /} in your Include list, Bacula will only save the
Filesystem {\bf /dev/hda5}. To save all filesystems except {\bf /tmp} with
out including any of the Samba or NFS mounted systems, and explicitly
excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to
be saved and restored, you can use the following: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = Include_example
  Include {
    Options {
       wilddir = /proc
       wilddir = /tmp
       wildfile = ".journal"
       wildfile = ".autofsck"
       exclude = yes
    }
    File = /
    File = /boot
    File = /home
    File = /rescue
    File = /usr
  }
}
\end{verbatim}
\normalsize

Since /tmp is on its own filesystem and it was not explicitly named in the
Include list, it is not really needed in the exclude list. It is better to
list it in the Exclude list for clarity, and in case the disks are changed so
that it is no longer in its own partition. 

Now, lets assume you only want to backup .Z and .gz files and nothing 
else. This is a bit trickier because Bacula by default will select 
everything to backup, so we must exclude everything but .Z and .gz files.
If we take the first example above and make the obvious modifications
to it, we might come up with a FileSet that looks like this:

\footnotesize 
\begin{verbatim}
FileSet {
  Name = "Full Set"
  Include {                    !!!!!!!!!!!!
     Options {                    This
        wildfile = "*.Z"          example
        wildfile = "*.gz"         doesn't
                                  work
     }                          !!!!!!!!!!!!
     File = /myfile
  }
}
\end{verbatim}
\normalsize

The *.Z and *.gz files will indeed be backed up, but all other files
that are not matched by the Options directives will automatically
be backed up too (i.e. that is the default rule).

To accomplish what we want, we must explicitly exclude all other files.
We do this with the fillowing:

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Full Set"
  Include {
     Options {
        wildfile = "*.Z"
        wildfile = "*.gz"
     }
     Options {
        Exclude = yes
        RegexFile = "^.?*$"
     }
     File = /myfile
  }
}
\end{verbatim}
\normalsize

The "trick" here was to add a RegexFile expression that matches
all files. It does not match directory names, so all directories in
/myfile will be backed up (the directory entry) and any *.Z and *.gz
files contained in them. If you know that certain directories do
not contain any *.Z or *.gz files and you do not want the directory
entries backed up, you will need to explicitly exclude those directories.
Backing up a directory entries is not very expensive.

Bacula uses the system regex library and some of them are
different on different OSes. The above has been reported not to work
on FreeBSD. This can be tested by using the {\bf estimate job=job-name
listing} command in the console and adapting the RegexFile expression
appropriately. In a future version of Bacula, we will supply our own
Regex code to avoid such system dependencies.

Please be aware that allowing Bacula to traverse or change file systems can be
{\bf very} dangerous. For example, with the following: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Bad example"
  Include {
    Options { onefs=no }
    File = /mnt/matou
  }
}
\end{verbatim}
\normalsize

you will be backing up an NFS mounted partition ({\bf /mnt/matou}), and since
{\bf onefs} is set to {\bf no}, Bacula will traverse file systems. Now if {\bf
/mnt/matou} has the current machine's file systems mounted, as is often the
case, you will get yourself into a recursive loop and the backup will never
end. 

\subsubsection*{Backing up Raw Partitions}
\index[general]{Backing up!Partitions }
\index[general]{Backing up Raw Partitions }
\addcontentsline{toc}{subsection}{Backing up Raw Partitions}

The following FileSet definition will backup a raw partition: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "RawPartition"
  Include {
    Options { sparse=yes }
    File = /dev/hda2
  }
}
\end{verbatim}
\normalsize

While backing up and restoring a raw partition, you should ensure that no
other process including the system is writing to that partition. As a
precaution, you are strongly urged to ensure that the raw partition is not
mounted or is mounted read-only. If necessary, this can be done using the {\bf
RunBeforeJob} directive. 


\subsubsection*{Excluding Files and Directories}
\index[general]{Directories!Excluding Files and }
\index[general]{Excluding Files and Directories }
\addcontentsline{toc}{subsubsection}{Excluding Files and Directories}

You may also include full filenames or directory names in addition to using
wild-cards and {\bf Exclude=yes} in the Options resource as specified above by
simply including the files to be excluded in an Exclude resource within the
FileSet. For example: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = Exclusion_example
  Include {
    Options {
      Signature = SHA1
    }
    File = /
    File = /boot
    File = /home
    File = /rescue
    File = /usr
  }
  Exclude {
    File = /proc
    File = /tmp
    File = .journal
    File = .autofsck
  }
}
\end{verbatim}
\normalsize

\label{win32}

\subsubsection*{Windows FileSets}
\index[general]{Windows FileSets }
\index[general]{FileSets!Windows }
\addcontentsline{toc}{subsection}{Windows FileSets}
If you are entering Windows file names, the directory path may be preceded by
the drive and a colon (as in c:). However, the path separators must be
specified in Unix convention (i.e. forward slash (/)). If you wish to include
a quote in a file name, precede the quote with a backslash
(\textbackslash{}). For example you might use the following
for a Windows machine to backup the "My Documents" directory: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Windows Set"
  Include {
    Options {
       WildFile = "*.obj"
       WildFile = "*.exe"
       exclude = yes
     }
     File = "c:/My Documents"
  }
}
\end{verbatim}
\normalsize

For exclude lists to work correctly on Windows, you must observe the following
rules: 

\begin{itemize}
\item Filenames are case sensitive, so you must use the correct case.  
\item To exclude a directory, you must not have a trailing slash on the 
   directory name.  
\item If you have spaces in your filename, you must enclose the entire name 
   in double-quote characters ("). Trying to use a backslash before  the space
   will not work.  
\item If you are using the old Exclude syntax (noted below), you may  not
   specify a drive letter in the exclude. The new syntax noted  above should work
   fine including driver letters. 
\end{itemize}

Thanks to Thiago Lima for summarizing the above items for us. If you are
having difficulties getting includes or excludes to work, you might want to
try using the {\bf estimate job=xxx listing} command documented in the 
\ilink{Console chapter}{estimate} of this manual. 

On Win32 systems, if you move a directory or file or rename a file into the
set of files being backed up, and a Full backup has already been made, Bacula
will not know there are new files to be saved during an Incremental or
Differential backup (blame Microsoft, not me). To avoid this problem, please
{\bf copy} any new directory or files into the backup area. If you do not have
enough disk to copy the directory or files, move them, but then initiate a
Full backup. 


\paragraph*{A Windows Example FileSet}
\index[general]{FileSet!Windows Example }
\index[general]{Windows Example FileSet }
\addcontentsline{toc}{paragraph}{Windows Example FileSet}

The following example was contributed by Russell Howe. Please note that
for presentation purposes, the lines beginning with Data and Internet 
have been wrapped and should included on the previous line with one
space.

\footnotesize
\begin{verbatim}
This is my Windows 2000 fileset:
FileSet {
 Name = "Windows 2000"
 Include {
  Options {
   signature = MD5
   Exclude = yes
   IgnoreCase = yes
   # Exclude Mozilla-based programs' file caches
   WildDir = "[A-Z]:/Documents and Settings/*/Application 
Data/*/Profiles/*/*/Cache"
   WildDir = "[A-Z]:/Documents and Settings/*/Application 
Data/*/Profiles/*/*/Cache.Trash"
   WildDir = "[A-Z]:/Documents and Settings/*/Application
Data/*/Profiles/*/*/ImapMail"

   # Exclude user's registry files - they're always in use anyway.
   WildFile = "[A-Z]:/Documents and Settings/*/Local Settings/Application
Data/Microsoft/Windows/usrclass.*"
   WildFile = "[A-Z]:/Documents and Settings/*/ntuser.*"

   # Exclude directories full of lots and lots of useless little files
   WildDir = "[A-Z]:/Documents and Settings/*/Cookies"
   WildDir = "[A-Z]:/Documents and Settings/*/Recent"
   WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/History"
   WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temp"
   WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temporary
Internet Files"

   # These are always open and unable to be backed up
   WildFile = "[A-Z]:/Documents and Settings/All Users/Application
Data/Microsoft/Network/Downloader/qmgr[01].dat"

   # Some random bits of Windows we want to ignore
   WildFile = "[A-Z]:/WINNT/security/logs/scepol.log"
   WildDir = "[A-Z]:/WINNT/system32/config"
   WildDir = "[A-Z]:/WINNT/msdownld.tmp"
   WildDir = "[A-Z]:/WINNT/Internet Logs"
   WildDir = "[A-Z]:/WINNT/$Nt*Uninstall*"
   WildDir = "[A-Z]:/WINNT/sysvol"
   WildFile = "[A-Z]:/WINNT/cluster/CLUSDB"
   WildFile = "[A-Z]:/WINNT/cluster/CLUSDB.LOG"
   WildFile = "[A-Z]:/WINNT/NTDS/edb.log"
   WildFile = "[A-Z]:/WINNT/NTDS/ntds.dit"
   WildFile = "[A-Z]:/WINNT/NTDS/temp.edb"
   WildFile = "[A-Z]:/WINNT/ntfrs/jet/log/edb.log"
   WildFile = "[A-Z]:/WINNT/ntfrs/jet/ntfrs.jdb"
   WildFile = "[A-Z]:/WINNT/ntfrs/jet/temp/tmp.edb"
   WildFile = "[A-Z]:/WINNT/system32/CPL.CFG"
   WildFile = "[A-Z]:/WINNT/system32/dhcp/dhcp.mdb"
   WildFile = "[A-Z]:/WINNT/system32/dhcp/j50.log"
   WildFile = "[A-Z]:/WINNT/system32/dhcp/tmp.edb"
   WildFile = "[A-Z]:/WINNT/system32/LServer/edb.log"
   WildFile = "[A-Z]:/WINNT/system32/LServer/TLSLic.edb"
   WildFile = "[A-Z]:/WINNT/system32/LServer/tmp.edb"
   WildFile = "[A-Z]:/WINNT/system32/wins/j50.log"
   WildFile = "[A-Z]:/WINNT/system32/wins/wins.mdb"
   WildFile = "[A-Z]:/WINNT/system32/wins/winstmp.mdb"

   # Temporary directories & files
   WildDir = "[A-Z]:/WINNT/Temp"
   WildDir = "[A-Z]:/temp"
   WildFile = "*.tmp"
   WildDir = "[A-Z]:/tmp"
   WildDir = "[A-Z]:/var/tmp"

   # Recycle bins
   WildDir = "[A-Z]:/RECYCLER"

   # Swap files
   WildFile = "[A-Z]:/pagefile.sys"

   # These are programs and are easier to reinstall than restore from
   # backup
   WildDir = "[A-Z]:/cygwin"
   WildDir = "[A-Z]:/Program Files/Grisoft"
   WildDir = "[A-Z]:/Program Files/Java"
   WildDir = "[A-Z]:/Program Files/Java Web Start"
   WildDir = "[A-Z]:/Program Files/JavaSoft"
   WildDir = "[A-Z]:/Program Files/Microsoft Office"
   WildDir = "[A-Z]:/Program Files/Mozilla Firefox"
   WildDir = "[A-Z]:/Program Files/Mozilla Thunderbird"
   WildDir = "[A-Z]:/Program Files/mozilla.org"
   WildDir = "[A-Z]:/Program Files/OpenOffice*"
  }

  # Our Win2k boxen all have C: and D: as the main hard drives.
  File = "C:/"
  File = "D:/"
 }
}
\end{verbatim}
\normalsize

Note, the three line of the above Exclude were split to fit on the document
page, they should be written on a single line in real use. 

\paragraph*{Windows NTFS Naming Considerations}
\index[general]{Windows NTFS Naming Considerations }
\index[general]{Considerations!Windows NTFS Naming }
\addcontentsline{toc}{paragraph}{Windows NTFS Naming Considerations}

NTFS filenames containing Unicode characters should now be supported
as of version 1.37.30 or later.

\subsubsection*{Testing Your FileSet}
\index[general]{FileSet!Testing Your }
\index[general]{Testing Your FileSet }
\addcontentsline{toc}{subsection}{Testing Your FileSet}

If you wish to get an idea of what your FileSet will really backup or if your
exclusion rules will work correctly, you can test it by using the {\bf
estimate} command in the Console program. See the 
\ilink{estimate command}{estimate} in the Console chapter of this
manual.