--- /dev/null
+-%
+%%
+
+\section{The FileSet Resource}
+\label{FileSetResource}
+\index[general]{Resource!FileSet}
+\index[general]{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.
+
+Bacula is designed to handle most character sets of the world,
+US ASCII, German, French, Chinese, ... However, it does this by
+encoding everything in UTF-8, and it expects all configuration files
+(including those read on Win32 machines) to be in UTF-8 format.
+UTF-8 is typically the default on Linux machines, but not on all
+Unix machines, nor on Windows, so you must take some care to ensure
+that your locale is set properly before starting Bacula.
+On most modern Win32 machines, you can edit the conf files with {\bf
+notebook} and choose output encoding UTF-8.
+
+To ensure that Bacula configuration files can be correctly read including
+foreign characters the {bf LANG} environment variable
+must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
+exact syntax may vary a bit from OS to OS, and exactly how you define
+it will also vary.
+
+Bacula assumes that all filenames are in UTF-8 format on Linux and
+Unix machines. On Win32 they are in Unicode (UTF-16), and will
+be automatically converted to UTF-8 format.
+
+
+\begin{description}
+
+\item [FileSet]
+\index[dir]{FileSet}
+\index[dir]{Directive!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}
+\index[dir]{Directive!Name}
+ The name of the FileSet resource. This directive is required.
+
+\item [Ignore FileSet Changes = \lt{}yes\vb{}no\gt{}]
+\index[dir]{Ignore FileSet Changes}
+\index[dir]{Directive!Ignore FileSet Changes}
+ Normally, if you modify the FileSet Include or Exclude lists,
+ the next backup will be forced to a Full so that Bacula can
+ guarantee that any additions or deletions are properly saved.
+
+ We strongly recommend against setting this directive to yes,
+ since doing so may cause you to have an incomplete set of backups.
+
+ If this directive is set to {\bf yes}, any changes you make to the
+ FileSet Include or Exclude lists, will not force a Full during
+ subsequent backups.
+
+ 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.
+
+\item [Enable VSS = \lt{}yes\vb{}no\gt{}]
+\index[dir]{Enable VSS}
+\index[dir]{Directive!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 yes}. 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{} \} }
+\index[dir]{Directive!Include}
+
+\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{} \} }
+\index[dir]{Directive!Exclude}
+
+
+\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 when processing the file-list for backup. Please see
+below for more details concerning Options resources.
+
+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.
+
+Windows users, please take note to specify directories (even c:/...) in
+Unix path notation. If you use Windows conventions, you will most likely
+not be able to restore your files due to the fact that the Windows
+path separator was defined as an escape character long before Windows
+existed, and Bacula adheres to that convention (i.e. \\ means the next character
+appears as itself).
+
+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
+(e.g. {\bf c:/xxx}) using Unix directory name separators
+(forward slash). The drive letter itself can be upper or lower case (e.g.
+c:/xxx or C:/xxx).
+
+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
+wildcard and regular expression pattern matching parts of the
+Options resources are checked in the order they are specified in the
+FileSet until the first one that matches. Once one matches, the
+compression and other flags within the Options specification will
+apply to the pattern matched.
+
+A key point is that in the absence of an Option or no other Option is
+matched, every file is accepted for backing up. This means that if
+you want to exclude something, you must explicitly specify an Option
+with an {\bf exclude = yes} and some pattern matching.
+
+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 checks 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 clause is specified,
+where you want everything to be backed up, and it is important to keep in mind
+when excluding as mentioned above.
+
+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.
+
+You find yourself using a lot of Regex statements, which will cost quite a lot
+of CPU time, we recommend you simplify them if you can, or better yet
+convert them to Wild statements which are much more efficient.
+
+The directives within an Options resource may be one of the following:
+
+\begin{description}
+
+\item [compression=GZIP]
+\index[dir]{compression}
+\index[dir]{Directive!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 6 (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 six generally give very little extra
+ compression and are rather CPU intensive.
+
+ You can overwrite this option per Storage resource with
+ \ilink{AllowCompression}{AllowCompression} option.
+
+\item [signature=SHA1]
+\index[dir]{signature}
+\index[dir]{SHA1}
+\index[dir]{Directive!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[dir]{signature}
+\index[dir]{MD5}
+\index[dir]{Directive!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[basejob=\lt{}options\gt{}]
+\index[dir]{basejob}
+\index[dir]{Directive!basejob}
+
+The options letters specified are used when running a {\bf Backup Level=Full}
+with BaseJobs. The options letters are the same than in the \textbf{verify=}
+option below.
+
+\item[accurate=\lt{}options\gt{}]
+\index[dir]{accurate}
+\index[dir]{Directive!accurate}
+ The options letters specified are used when running a {\bf Backup
+ Level=Incremental/Differential} in Accurate mode. The options
+ letters are the same than in the \textbf{verify=} option below.
+
+\item [verify=\lt{}options\gt{}]
+\index[dir]{verify}
+\index[dir]{Directive!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 d}
+ 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\vb{}no]
+\index[dir]{onefs}
+\index[dir]{Directive!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: /misc is a different filesystem. Will not descend from / into /misc
+rufus-fd: /net is a different filesystem. Will not descend from / into /net
+rufus-fd: /var/lib/nfs/rpc_pipefs is a different filesystem. Will not descend from /var/lib/nfs into /var/lib/nfs/rpc_pipefs
+rufus-fd: /selinux is a different filesystem. Will not descend from / into /selinux
+rufus-fd: /sys is a different filesystem. Will not descend from / into /sys
+rufus-fd: /dev is a different filesystem. Will not descend from / into /dev
+rufus-fd: /home is a different filesystem. Will not descend from / into /home
+\end{verbatim}
+\normalsize
+
+ Note: in previous versions of Bacula, the above message was of the form:
+
+\footnotesize
+\begin{verbatim}
+Filesystem change prohibited. Will not descend into /misc
+\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 possibility is to
+ use {\bf onefs=no} and to set {\bf 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 that "/home is a different filesystem" when
+ Bacula is processing the {\bf /} directory. This message does not
+ indicate an error. This message means that while examining the
+ {\bf File =} referred to in the second part of the message, Bacula will
+ not descend into the directory mentioned in the first part of the message.
+ However, it is possible that the separate filesystem will be backed up
+ despite the message. For example, consider the following FileSet:
+
+\footnotesize
+\begin{verbatim}
+ File = /
+ File = /var
+\end{verbatim}
+\normalsize
+
+ where {\bf /var} is a separate filesystem. In this example, you will get a
+ message saying that Bacula will not decend from {\bf /} into {\bf /var}. But
+ it is important to realise that Bacula will descend into {\bf /var} from the
+ second File directive shown above. In effect, the warning is bogus,
+ but it is supplied to alert you to possible omissions from your FileSet. In
+ this example, {\bf /var} will be backed up. If you changed the FileSet such
+ that it did not specify {\bf /var}, then {\bf /var} will not be backed up.
+
+
+\item [honor nodump flag=\lt{}yes\vb{}no\gt{}]
+\index[dir]{honornodumpflag}
+\index[dir]{Directive!honornodumpflag}
+ If your file system supports the {\bf nodump} flag (e. g. most
+ BSD-derived systems) Bacula will honor the setting of the flag
+ when this option is set to {\bf yes}. Files having this flag set
+ will not be included in the backup and will not show up in the
+ catalog. For directories with the {\bf nodump} flag set recursion
+ is turned off and the directory will be listed in the catalog.
+ If the {\bf honor nodump flag} option is not defined
+ or set to {\bf no} every file and directory will be eligible for
+ backup.
+
+
+\label{portable}
+\item [portable=yes\vb{}no]
+\index[dir]{portable}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{recurse}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{sparse}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{readfifo}
+\index[dir]{Directive!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 [noatime=yes\vb{}no]
+\index[dir]{noatime}
+\index[dir]{Directive!noatime}
+ If enabled, and if your Operating System supports the O\_NOATIME file
+ open flag, Bacula will open all files to be backed up with this option.
+ It makes it possible to read a file without updating the inode atime
+ (and also without the inode ctime update which happens if you try to set
+ the atime back to its previous value). It also prevents a race
+ condition when two programs are reading the same file, but only one does
+ not want to change the atime. It's most useful for backup programs and
+ file integrity checkers (and bacula can fit on both categories).
+
+ This option is particularly useful for sites where users are sensitive
+ to their MailBox file access time. It replaces both the {\bf keepatime}
+ option without the inconveniences of that option (see below).
+
+ If your Operating System does not support this option, it will be
+ silently ignored by Bacula.
+
+
+\item [mtimeonly=yes\vb{}no]
+\index[dir]{mtimeonly}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{keepatime}
+\index[dir]{Directive!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 [checkfilechanges=yes\vb{}no]
+\index[dir]{checkfilechanges}
+\index[dir]{Directive!checkfilechanges}
+ On versions 2.0.4 or greater,
+ if enabled, the Client will check size, age of each file after
+ their backup to see if they have changed during backup. If time
+ or size mismatch, an error will raise.
+
+\begin{verbatim}
+ zog-fd: Client1.2007-03-31_09.46.21 Error: /tmp/test mtime changed during backup.
+\end{verbatim}
+
+ In general, it is recommended to use this option.
+
+\item [hardlinks=yes\vb{}no]
+\index[dir]{hardlinks}
+\index[dir]{Directive!hardlinks}
+ When enabled (default), this directive will cause hard links 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}
+\index[dir]{Directive!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.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ It is recommended to enclose the string in double quotes.
+
+\item [wilddir=\lt{}string\gt{}]
+\index[dir]{wilddir}
+\index[dir]{Directive!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 to be
+ included. If {\bf Exclude=yes} is specified, the wild-card will select
+ which directories 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.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ An example of excluding with the WildDir option on Win32 machines is
+ presented below.
+
+\item [wildfile=\lt{}string\gt{}]
+\index[dir]{wildfile}
+\index[dir]{Directive!wildfile}
+ Specifies a wild-card string to be applied to non-directories. That
+ is no directory entries will be matched by this directive.
+ However, note that the match is done against the full path and filename,
+ so your wild-card string must take into account that filenames
+ are preceded by the full path.
+ 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.
+
+ You may want to test your expressions prior to running your
+ backup by using the bwild program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+ An example of excluding with the WildFile option on Win32 machines is
+ presented below.
+
+
+\item [regex=\lt{}string\gt{}]
+\index[dir]{regex}
+\index[dir]{Directive!regex}
+ Specifies a POSIX extended regular expression to be applied to the
+ filenames and directory names, which include the full path. 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.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bwild} chapter of this manual for
+ more. You can also test your full FileSet definition by using
+ the \ilink{estimate}{estimate} command in the Console
+ chapter of this manual.
+
+ You find yourself using a lot of Regex statements, which will cost quite a lot
+ of CPU time, we recommend you simplify them if you can, or better yet
+ convert them to Wild statements which are much more efficient.
+
+
+\item [regexfile=\lt{}string\gt{}]
+\index[dir]{regexfile}
+\index[dir]{Directive!regexfile}
+ Specifies a POSIX extended regular expression to be applied to
+ non-directories. No directories will be matched by this directive.
+ However, note that the match is done against the full path and
+ filename, so your regex string must take into account that filenames
+ are preceded by the full path.
+ 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.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bregex} chapter of this manual for
+ more.
+
+
+\item [regexdir=\lt{}string\gt{}]
+\index[dir]{regexdir}
+\index[dir]{Directive!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.
+
+ The regex libraries differ from one operating system to
+ another, and in addition, regular expressions are complicated,
+ so you may want to test your expressions prior to running your
+ backup by using the bregex program. Please see the
+ \ilink{Utilities}{bregex} chapter of this manual for
+ more.
+
+
+\item [exclude=yes\vb{}no]
+\index[dir]{exclude}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{aclsupport}
+\index[dir]{Directive!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\vb{}no]
+\index[dir]{ignore case}
+\index[dir]{Directive!ignore case}
+ The default is {\bf no}. On Windows systems, you will almost surely
+ want to set this to {\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}
+\index[dir]{Directive!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 [DriveType=Windows-drive-type]
+\index[dir]{DriveType}
+\index[dir]{Directive!DriveType}
+ This option is effective only on Windows machines and is
+ somewhat similar to the Unix/Linux {\bf fstype} described
+ above, except that it allows you to select what Windows
+ drive types you want to allow. By default all drive
+ types are accepted.
+
+ The permitted drivetype names are:
+
+ removable, fixed, remote, cdrom, ramdisk
+
+ You may have multiple Driveype directives, and thus permit matching
+ of multiple drive types within a single Options resource. If
+ the type specified on the drivetype 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 Unix/Linux systems.
+
+
+\item [hfsplussupport=yes\vb{}no]
+\index[dir]{hfsplussupport}
+\index[dir]{Directive!hfsplussupport}
+ This option allows you to turn on support for Mac OSX HFS plus
+ finder information.
+
+\item [strippath=\lt{}integer\gt{}]
+\index[dir]{strippath}
+\index[dir]{Directive!strippath}
+ This option will cause {\bf integer} paths to be stripped from
+ the front of the full path/filename being backed up. This can
+ be useful if you are migrating data from another vendor or if
+ you have taken a snapshot into some subdirectory. This directive
+ can cause your filenames to be overlayed with regular backup data,
+ so should be used only by experts and with great care.
+\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. Wild-cards are not interpreted
+in file-lists. They can only be specified in Options resources.
+
+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 (\vb) 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. Before submitting the
+ specified command bacula will performe
+ \ilink{character substitution}{character substitution}.
+
+ 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 Red Hat 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 Red Hat Linux normally only ext2 and ext3, you can backup
+ all local filesystems 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 (see
+ below for doing it on the Client 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. Note, the {bf /dev/hd6} must be
+ the raw partition itself. Bacula will not back it up as a raw device if
+ you specify a symbolic link to a raw device such as my be created by the
+ LVM Snapshot utilities.
+
+ 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}{RescueChapter} 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.
+
+\item A file-list may not contain wild-cards. Use directives in the
+ Options resource if you wish to specify wild-cards or regular expression
+ matching.
+
+\item
+\index[general]{IgnoreDir}
+The {\bf ExcludeDirContaining = \lt{}filename\gt{}} is a directive that
+can be added to the Include section of the FileSet resource. If the specified
+filename ({\bf filename-string}) is found on the Client in any directory to be
+backed up, the whole directory will be ignored (not backed up). For example:
+
+\begin{verbatim}
+ # List of files to be backed up
+ FileSet {
+ Name = "MyFileSet"
+ Include {
+ Options {
+ signature = MD5
+ }
+ File = /home
+ Exclude Dir Containing = .excludeme
+ }
+ }
+\end{verbatim}
+
+But in /home, there may be hundreds of directories of users and some
+people want to indicate that they don't want to have certain
+directories backed up. For example, with the above FileSet, if
+the user or sysadmin creates a file named {\bf .excludeme} in
+specific directories, such as
+
+\begin{verbatim}
+ /home/user/www/cache/.excludeme
+ /home/user/temp/.excludeme
+\end{verbatim}
+
+then Bacula will not backup the two directories named:
+
+\begin{verbatim}
+ /home/user/www/cache
+ /home/user/temp
+\end{verbatim}
+
+NOTE: subdirectories will not be backed up. That is, the directive
+applies to the two directories in question and any children (be they
+files, directories, etc).
+
+\end{itemize}
+
+\section{FileSet Examples}
+\index[general]{Examples!FileSet }
+\index[general]{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 following:
+
+\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.
+
+As a final example, let's say that you have only one or two
+subdirectories of /home that you want to backup. For example,
+you want to backup only subdirectories beginning with the letter
+a and the letter b -- i.e. /home/a* and /home/b*. Now, you might first
+try:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ wilddir = "/home/a*"
+ wilddir = "/home/b*"
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+The problem is that the above will include everything in /home. To get
+things to work correctly, you need to start with the idea of exclusion
+instead of inclusion. So, you could simply exclude all directories
+except the two you want to use:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ RegexDir = "^/home/[c-z]"
+ exclude = yes
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+And assuming that all subdirectories start with a lowercase letter, this
+would work.
+
+An alternative would be to include the two subdirectories desired and
+exclude everything else:
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "Full Set"
+ Include {
+ Options {
+ wilddir = "/home/a*"
+ wilddir = "/home/b*"
+ }
+ Options {
+ RegexDir = ".*"
+ exclude = yes
+ }
+ File = /home
+ }
+}
+\end{verbatim}
+\normalsize
+
+
+The following example shows how to back up only the My Pictures directory inside
+the My Documents directory for all users in C:/Documents and Settings, i.e.
+everything matching the pattern:
+
+C:/Documents and Settings/*/My Documents/My Pictures/*
+
+To understand how this can be achieved, there are two important points to
+remember:
+
+Firstly, Bacula walks over the filesystem depth-first starting from the File =
+lines. It stops descending when a directory is excluded, so you must include
+all ancestor directories of each directory containing files to be included.
+
+Secondly, each directory and file is compared to the Options clauses in the
+order they appear in the FileSet. When a match is found, no further clauses
+are compared and the directory or file is either included or excluded.
+
+The FileSet resource definition below implements this by including specifc
+directories and files and excluding everything else.
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = "AllPictures"
+
+ Include {
+
+ File = "C:/Documents and Settings"
+
+ Options {
+ signature = SHA1
+ verify = s1
+ IgnoreCase = yes
+
+ # Include all users' directories so we reach the inner ones. Unlike a
+ # WildDir pattern ending in *, this RegExDir only matches the top-level
+ # directories and not any inner ones.
+ RegExDir = "^C:/Documents and Settings/[^/]+$"
+
+ # Ditto all users' My Documents directories.
+ WildDir = "C:/Documents and Settings/*/My Documents"
+
+ # Ditto all users' My Documents/My Pictures directories.
+ WildDir = "C:/Documents and Settings/*/My Documents/My Pictures"
+
+ # Include the contents of the My Documents/My Pictures directories and
+ # any subdirectories.
+ Wild = "C:/Documents and Settings/*/My Documents/My Pictures/*"
+ }
+
+ Options {
+ Exclude = yes
+ IgnoreCase = yes
+
+ # Exclude everything else, in particular any files at the top level and
+ # any other directories or files in the users' directories.
+ Wild = "C:/Documents and Settings/*"
+ }
+ }
+}
+\end{verbatim}
+\normalsize
+
+\section{Backing up Raw Partitions}
+\index[general]{Backing up!Partitions }
+\index[general]{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.
+
+
+\section{Excluding Files and Directories}
+\index[general]{Directories!Excluding Files and }
+\index[general]{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}
+\section{Windows FileSets}
+\index[general]{Windows FileSets }
+\index[general]{FileSets!Windows }
+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 }
+
+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 }
+
+NTFS filenames containing Unicode characters should now be supported
+as of version 1.37.30 or later.
+
+\section{Testing Your FileSet}
+\index[general]{FileSet!Testing Your }
+\index[general]{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}{estimate} in the Console chapter of this
+manual.
+
+As an example, suppose you add the following test FileSet:
+
+\footnotesize
+\begin{verbatim}
+FileSet {
+ Name = Test
+ Include {
+ File = /home/xxx/test
+ Options {
+ regex = ".*\.c$"
+ }
+ }
+}
+\end{verbatim}
+\normalsize
+
+You could then add some test files to the directory {\bf /home/xxx/test}
+and use the following command in the console:
+
+\footnotesize
+\begin{verbatim}
+estimate job=<any-job-name> listing client=<desired-client> fileset=Test
+\end{verbatim}
+\normalsize
+
+to give you a listing of all files that match.
projects / bacula / docs / blobdiff