1 \section{The FileSet Resource}
2 \label{FileSetResource}
3 \index[general]{Resource!FileSet}
4 \index[general]{FileSet Resource}
6 The FileSet resource defines what files are to be included or excluded in a
7 backup job. A {\bf FileSet} resource is required for each backup Job. It
8 consists of a list of files or directories to be included, a list of files
9 or directories to be excluded and the various backup options such as
10 compression, encryption, and signatures that are to be applied to each
13 Any change to the list of the included files will cause Bacula to
14 automatically create a new FileSet (defined by the name and an MD5 checksum
15 of the Include/Exclude contents). Each time a new FileSet is created,
16 Bacula will ensure that the next backup is always a Full save.
18 Bacula is designed to handle most character sets of the world,
19 US ASCII, German, French, Chinese, \ldots{} However, it does this by
20 encoding everything in UTF-8, and it expects all configuration files
21 (including those read on Win32 machines) to be in UTF-8 format.
22 UTF-8 is typically the default on Linux machines, but not on all
23 Unix machines, nor on Windows, so you must take some care to ensure
24 that your locale is set properly before starting Bacula.
25 On most modern Win32 machines, you can edit the conf files with {\bf
26 notebook} and choose output encoding UTF-8.
28 To ensure that Bacula configuration files can be correctly read including
29 foreign characters the {bf LANG} environment variable
30 must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
31 exact syntax may vary a bit from OS to OS, and exactly how you define
34 Bacula assumes that all filenames are in UTF-8 format on Linux and
35 Unix machines. On Win32 they are in Unicode (UTF-16), and will
36 be automatically converted to UTF-8 format.
43 \index[dir]{Directive!FileSet}
44 Start of the FileSet resource. One {\bf FileSet} resource must be
45 defined for each Backup job.
47 \label{Director:Fileset:Name}
48 \item [Name = \lt{}name\gt{}]
50 \index[dir]{Directive!Name}
51 The name of the FileSet resource. This directive is required.
53 \label{Director:Fileset:IgnoreFilesetChanges}
54 \item [Ignore FileSet Changes = \lt{}yes\vb{}no\gt{}]
55 \index[dir]{Ignore FileSet Changes}
56 \index[dir]{Directive!Ignore FileSet Changes}
57 Normally, if you modify the FileSet Include or Exclude lists,
58 the next backup will be forced to a Full so that Bacula can
59 guarantee that any additions or deletions are properly saved.
61 We strongly recommend against setting this directive to yes,
62 since doing so may cause you to have an incomplete set of backups.
64 If this directive is set to {\bf yes}, any changes you make to the
65 FileSet Include or Exclude lists, will not force a Full during
68 The default is {\bf no}, in which case, if you change the Include or
69 Exclude, Bacula will force a Full backup to ensure that everything is
72 \label{Director:Fileset:EnableVss}
73 \item [Enable VSS = \lt{}yes\vb{}no\gt{}]
74 \index[dir]{Enable VSS}
75 \index[dir]{Directive!Enable VSS}
76 If this directive is set to {\bf yes} the File daemon will be notified
77 that the user wants to use a Volume Shadow Copy Service (VSS) backup
78 for this job. The default is {\bf yes}. This directive is effective
79 only for VSS enabled Win32 File daemons. It permits a consistent copy
80 of open files to be made for cooperating writer applications, and for
81 applications that are not VSS away, Bacula can at least copy open files.
82 The Volume Shadow Copy will only be done on Windows drives where the
83 drive (e.g. C:, D:, \ldots{}) is explicitly mentioned in a {\bf File}
85 For more information, please see the
86 \ilink{Windows}{VSS} chapter of this manual.
88 \label{Director:Fileset:Include}
89 \item [Include \{ Options \{\lt{}file-options\gt{}\} \ldots{};
90 \lt{}file-list\gt{} \} ]
91 \index[dir]{Include \{ [ Options \{\lt{}file-options\gt{}\} \ldots{}]
92 \lt{}file-list\gt{} \} }
93 \index[dir]{Directive!Include}
95 \item [Options \{ \lt{}file-options\gt{} \} ]
96 \index[dir]{Options \{ \lt{}file-options\gt{} \} }
98 \label{Director:Fileset:Exclude}
99 \item [Exclude \{ \lt{}file-list\gt{} \}]
100 \index[dir]{Exclude \{ \lt{}file-list\gt{} \} }
101 \index[dir]{Directive!Exclude}
103 \label{Director:Fileset:End}
106 The Include resource must contain a list of directories and/or files to be
107 processed in the backup job. Normally, all files found in all
108 subdirectories of any directory in the Include File list will be backed up.
109 Note, see below for the definition of \lt{}file-list\gt{}.
110 The Include resource may also contain one or more Options resources that
111 specify options such as compression to be applied to all or any subset of
112 the files found when processing the file-list for backup. Please see
113 below for more details concerning Options resources.
115 There can be any number of {\bf Include} resources within the FileSet, each
116 having its own list of directories or files to be backed up and the backup
117 options defined by one or more Options resources. The {\bf file-list}
118 consists of one file or directory name per line. Directory names should be
119 specified without a trailing slash with Unix path notation.
121 Windows users, please take note to specify directories (even c:/\ldots{}) in
122 Unix path notation. If you use Windows conventions, you will most likely
123 not be able to restore your files due to the fact that the Windows
124 path separator was defined as an escape character long before Windows
125 existed, and Bacula adheres to that convention (i.e. \\ means the next character
128 You should always specify a full path for every directory and file that you
129 list in the FileSet. In addition, on Windows machines, you should {\bf
130 always} prefix the directory or filename with the drive specification
131 (e.g. {\bf c:/xxx}) using Unix directory name separators
132 (forward slash). The drive letter itself can be upper or lower case (e.g.
135 Bacula's default for processing directories is to recursively descend in
136 the directory saving all files and subdirectories. Bacula will not by
137 default cross filesystems (or mount points in Unix parlance). This means
138 that if you specify the root partition (e.g. {\bf /}), Bacula will save
139 only the root partition and not any of the other mounted filesystems.
140 Similarly on Windows systems, you must explicitly specify each of the
141 drives you want saved (e.g.
142 {\bf c:/} and {\bf d:/} \ldots{}). In addition, at least for Windows systems, you
143 will most likely want to enclose each specification within double quotes
144 particularly if the directory (or file) name contains spaces. The {\bf df}
145 command on Unix systems will show you which mount points you must specify to
146 save everything. See below for an example.
148 Take special care not to include a directory twice or Bacula will backup
149 the same files two times wasting a lot of space on your archive device.
150 Including a directory twice is very easy to do. For example:
155 Options { compression=GZIP }
162 on a Unix system where /usr is a subdirectory (rather than a mounted
163 filesystem) will cause /usr to be backed up twice.
165 Please take note of the following items in the FileSet syntax:
168 \item There is no equal sign (=) after the Include and before the opening
169 brace (\{). The same is true for the Exclude.
170 \item Each directory (or filename) to be included or excluded is preceded by a {\bf File
171 =}. Previously they were simply listed on separate lines.
172 \item The options that previously appeared on the Include line now must be
173 specified within their own Options resource.
174 \item The Exclude resource does not accept Options.
175 \item When using wild-cards or regular expressions, directory names are
176 always terminated with a slash (/) and filenames have no trailing slash.
179 The Options resource is optional, but when specified, it will contain a
180 list of {\bf keyword=value} options to be applied to the file-list.
181 See below for the definition of file-list.
182 Multiple Options resources may be specified one after another. As the
183 files are found in the specified directories, the Options will applied to
184 the filenames to determine if and how the file should be backed up. The
185 wildcard and regular expression pattern matching parts of the
186 Options resources are checked in the order they are specified in the
187 FileSet until the first one that matches. Once one matches, the
188 compression and other flags within the Options specification will
189 apply to the pattern matched.
191 A key point is that in the absence of an Option or no other Option is
192 matched, every file is accepted for backing up. This means that if
193 you want to exclude something, you must explicitly specify an Option
194 with an {\bf exclude = yes} and some pattern matching.
196 Once Bacula determines that the Options resource matches the file under
197 consideration, that file will be saved without looking at any other Options
198 resources that may be present. This means that any wild cards must appear
199 before an Options resource without wild cards.
201 If for some reason, Bacula checks all the Options resources to a file under
202 consideration for backup, but there are no matches (generally because of wild
203 cards that don't match), Bacula as a default will then backup the file. This
204 is quite logical if you consider the case of no Options clause is specified,
205 where you want everything to be backed up, and it is important to keep in mind
206 when excluding as mentioned above.
208 However, one additional point is that in the case that no match was found,
209 Bacula will use the options found in the last Options resource. As a
210 consequence, if you want a particular set of "default" options, you should put
211 them in an Options resource after any other Options.
213 It is a good idea to put all your wild-card and regex expressions inside
214 double quotes to prevent conf file scanning problems.
216 This is perhaps a bit overwhelming, so there are a number of examples included
217 below to illustrate how this works.
219 You find yourself using a lot of Regex statements, which will cost quite a lot
220 of CPU time, we recommend you simplify them if you can, or better yet
221 convert them to Wild statements which are much more efficient.
223 The directives within an Options resource may be one of the following:
227 \item [compression=GZIP]
228 \index[dir]{compression}
229 \index[dir]{Directive!compression}
230 All files saved will be software compressed using the GNU ZIP
231 compression format. The compression is done on a file by file basis by
232 the File daemon. If there is a problem reading the tape in a single
233 record of a file, it will at most affect that file and none of the other
234 files on the tape. Normally this option is {\bf not} needed if you have
235 a modern tape drive as the drive will do its own compression. In fact,
236 if you specify software compression at the same time you have hardware
237 compression turned on, your files may actually take more space on the
240 Software compression is very important if you are writing your Volumes
241 to a file, and it can also be helpful if you have a fast computer but a
242 slow network, otherwise it is generally better to rely your tape drive's
243 hardware compression. As noted above, it is not generally a good idea
244 to do both software and hardware compression.
246 Specifying {\bf GZIP} uses the default compression level 6 (i.e. {\bf
247 GZIP} is identical to {\bf GZIP6}). If you want a different compression
248 level (1 through 9), you can specify it by appending the level number
249 with no intervening spaces to {\bf GZIP}. Thus {\bf compression=GZIP1}
250 would give minimum compression but the fastest algorithm, and {\bf
251 compression=GZIP9} would give the highest level of compression, but
252 requires more computation. According to the GZIP documentation,
253 compression levels greater than six generally give very little extra
254 compression and are rather CPU intensive.
256 You can overwrite this option per Storage resource with
257 \ilink{AllowCompression}{AllowCompression} option.
259 \item [compression=LZO]
260 \index[dir]{compression}
261 \index[dir]{Directive!compression}
262 All files saved will be software compressed using the LZO
263 compression format. The compression is done on a file by file basis by
264 the File daemon. Everything else about GZIP is true for LZO.
266 LZO provides much faster compression and decompression speed but lower
267 compression ratio than GZIP. If your CPU is fast enough you should be able
268 to compress your data without making the backup duration longer.
270 Note that bacula only use one compression level LZO1X-1 specified by LZO.
272 You can overwrite this option per Storage resource with
273 \ilink{AllowCompression}{AllowCompression} option.
275 \item [signature=SHA1]
276 \index[dir]{signature}
278 \index[dir]{Directive!signature}
279 An SHA1 signature will be computed for all The SHA1 algorithm is
280 purported to be some what slower than the MD5 algorithm, but at the same
281 time is significantly better from a cryptographic point of view (i.e.
282 much fewer collisions, much lower probability of being hacked.) It adds
283 four more bytes than the MD5 signature. We strongly recommend that
284 either this option or MD5 be specified as a default for all files.
285 Note, only one of the two options MD5 or SHA1 can be computed for any
288 \item [signature=MD5]
289 \index[dir]{signature}
291 \index[dir]{Directive!signature}
292 An MD5 signature will be computed for all files saved. Adding this
293 option generates about 5\% extra overhead for each file saved. In
294 addition to the additional CPU time, the MD5 signature adds 16 more
295 bytes per file to your catalog. We strongly recommend that this option
296 or the SHA1 option be specified as a default for all files.
299 \item[basejob=\lt{}options\gt{}]
301 \index[dir]{Directive!basejob}
303 The options letters specified are used when running a {\bf Backup Level=Full}
304 with BaseJobs. The options letters are the same than in the \textbf{verify=}
307 \item[accurate=\lt{}options\gt{}]
308 \index[dir]{accurate}
309 \index[dir]{Directive!accurate}
310 The options letters specified are used when running a {\bf Backup
311 Level=Incremental/Differential} in Accurate mode. The options
312 letters are the same than in the \textbf{verify=} option below.
314 \item [verify=\lt{}options\gt{}]
316 \index[dir]{Directive!verify}
317 The options letters specified are used when running a {\bf Verify
318 Level=Catalog} as well as the {\bf DiskToCatalog} level job. The options
319 letters may be any combination of the following:
327 compare the permission bits
330 compare the number of links
342 compare the access time
345 compare the modification time (st\_mtime)
348 compare the change time (st\_ctime)
351 report file size decreases
354 compare the MD5 signature
357 compare the SHA1 signature
360 A useful set of general options on the {\bf Level=Catalog} or {\bf
361 Level=DiskToCatalog} verify is {\bf pins5} i.e. compare permission bits,
362 inodes, number of links, size, and MD5 changes.
364 \item [onefs=yes\vb{}no]
366 \index[dir]{Directive!onefs}
367 If set to {\bf yes} (the default), {\bf Bacula} will remain on a single
368 file system. That is it will not backup file systems that are mounted
369 on a subdirectory. If you are using a *nix system, you may not even be
370 aware that there are several different filesystems as they are often
371 automatically mounted by the OS (e.g. /dev, /net, /sys, /proc, \ldots{}).
372 With Bacula 1.38.0 or later, it will inform you when it decides not to
373 traverse into another filesystem. This can be very useful if you forgot
374 to backup a particular partition. An example of the informational
375 message in the job report is:
379 rufus-fd: /misc is a different filesystem. Will not descend from / into /misc
380 rufus-fd: /net is a different filesystem. Will not descend from / into /net
381 rufus-fd: /var/lib/nfs/rpc_pipefs is a different filesystem. Will not descend from /var/lib/nfs into /var/lib/nfs/rpc_pipefs
382 rufus-fd: /selinux is a different filesystem. Will not descend from / into /selinux
383 rufus-fd: /sys is a different filesystem. Will not descend from / into /sys
384 rufus-fd: /dev is a different filesystem. Will not descend from / into /dev
385 rufus-fd: /home is a different filesystem. Will not descend from / into /home
389 Note: in previous versions of Bacula, the above message was of the form:
393 Filesystem change prohibited. Will not descend into /misc
397 If you wish to backup multiple filesystems, you can explicitly
398 list each filesystem you want saved. Otherwise, if you set the onefs option
399 to {\bf no}, Bacula will backup all mounted file systems (i.e. traverse mount
400 points) that are found within the {\bf FileSet}. Thus if you have NFS or
401 Samba file systems mounted on a directory listed in your FileSet, they will
402 also be backed up. Normally, it is preferable to set {\bf onefs=yes} and to
403 explicitly name each filesystem you want backed up. Explicitly naming the
404 filesystems you want backed up avoids the possibility of getting into a
405 infinite loop recursing filesystems. Another possibility is to
406 use {\bf onefs=no} and to set {\bf fstype=ext2, \ldots{}}.
407 See the example below for more details.
409 If you think that Bacula should be backing up a particular directory
410 and it is not, and you have {\bf onefs=no} set, before you complain,
420 where you replace {\bf filesystem} with the one in question. If the
421 {\bf Device:} number is different for / and for your filesystem, then they
422 are on different filesystems. E.g.
427 Size: 4096 Blocks: 16 IO Block: 4096 directory
428 Device: 302h/770d Inode: 2 Links: 26
429 Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)
430 Access: 2005-11-10 12:28:01.000000000 +0100
431 Modify: 2005-09-27 17:52:32.000000000 +0200
432 Change: 2005-09-27 17:52:32.000000000 +0200
436 Size: 4096 Blocks: 16 IO Block: 4096 directory
437 Device: 308h/776d Inode: 2 Links: 7
438 Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)
439 Access: 2005-11-10 12:28:02.000000000 +0100
440 Modify: 2005-11-06 12:36:48.000000000 +0100
441 Change: 2005-11-06 12:36:48.000000000 +0100
445 Also be aware that even if you include {\bf /home} in your list
446 of files to backup, as you most likely should, you will get the
447 informational message that "/home is a different filesystem" when
448 Bacula is processing the {\bf /} directory. This message does not
449 indicate an error. This message means that while examining the
450 {\bf File =} referred to in the second part of the message, Bacula will
451 not descend into the directory mentioned in the first part of the message.
452 However, it is possible that the separate filesystem will be backed up
453 despite the message. For example, consider the following FileSet:
462 where {\bf /var} is a separate filesystem. In this example, you will get a
463 message saying that Bacula will not decend from {\bf /} into {\bf /var}. But
464 it is important to realise that Bacula will descend into {\bf /var} from the
465 second File directive shown above. In effect, the warning is bogus,
466 but it is supplied to alert you to possible omissions from your FileSet. In
467 this example, {\bf /var} will be backed up. If you changed the FileSet such
468 that it did not specify {\bf /var}, then {\bf /var} will not be backed up.
471 \item [honor nodump flag=\lt{}yes\vb{}no\gt{}]
472 \index[dir]{honornodumpflag}
473 \index[dir]{Directive!honornodumpflag}
474 If your file system supports the {\bf nodump} flag (e. g. most
475 BSD-derived systems) Bacula will honor the setting of the flag
476 when this option is set to {\bf yes}. Files having this flag set
477 will not be included in the backup and will not show up in the
478 catalog. For directories with the {\bf nodump} flag set recursion
479 is turned off and the directory will be listed in the catalog.
480 If the {\bf honor nodump flag} option is not defined
481 or set to {\bf no} every file and directory will be eligible for
486 \item [portable=yes\vb{}no]
487 \index[dir]{portable}
488 \index[dir]{Directive!portable}
489 If set to {\bf yes} (default is {\bf no}), the Bacula File daemon will
490 backup Win32 files in a portable format, but not all Win32 file
491 attributes will be saved and restored. By default, this option is set
492 to {\bf no}, which means that on Win32 systems, the data will be backed
493 up using Windows API calls and on WinNT/2K/XP, all the security and
494 ownership attributes will be properly backed up (and restored). However
495 this format is not portable to other systems -- e.g. Unix, Win95/98/Me.
496 When backing up Unix systems, this option is ignored, and unless you
497 have a specific need to have portable backups, we recommend accept the
498 default ({\bf no}) so that the maximum information concerning your files
501 \item [recurse=yes\vb{}no]
503 \index[dir]{Directive!recurse}
504 If set to {\bf yes} (the default), Bacula will recurse (or descend) into
505 all subdirectories found unless the directory is explicitly excluded
506 using an {\bf exclude} definition. If you set {\bf recurse=no}, Bacula
507 will save the subdirectory entries, but not descend into the
508 subdirectories, and thus will not save the files or directories
509 contained in the subdirectories. Normally, you will want the default
512 \item [sparse=yes\vb{}no]
514 \index[dir]{Directive!sparse}
515 Enable special code that checks for sparse files such as created by
516 ndbm. The default is {\bf no}, so no checks are made for sparse files.
517 You may specify {\bf sparse=yes} even on files that are not sparse file.
518 No harm will be done, but there will be a small additional overhead to
519 check for buffers of all zero, and a small additional amount of space on
520 the output archive will be used to save the seek address of each
521 non-zero record read.
523 {\bf Restrictions:} Bacula reads files in 32K buffers. If the whole
524 buffer is zero, it will be treated as a sparse block and not written to
525 tape. However, if any part of the buffer is non-zero, the whole buffer
526 will be written to tape, possibly including some disk sectors (generally
527 4098 bytes) that are all zero. As a consequence, Bacula's detection of
528 sparse blocks is in 32K increments rather than the system block size.
529 If anyone considers this to be a real problem, please send in a request
530 for change with the reason.
532 If you are not familiar with sparse files, an example is say a file
533 where you wrote 512 bytes at address zero, then 512 bytes at address 1
534 million. The operating system will allocate only two blocks, and the
535 empty space or hole will have nothing allocated. However, when you read
536 the sparse file and read the addresses where nothing was written, the OS
537 will return all zeros as if the space were allocated, and if you backup
538 such a file, a lot of space will be used to write zeros to the volume.
539 Worse yet, when you restore the file, all the previously empty space
540 will now be allocated using much more disk space. By turning on the
541 {\bf sparse} option, Bacula will specifically look for empty space in
542 the file, and any empty space will not be written to the Volume, nor
543 will it be restored. The price to pay for this is that Bacula must
544 search each block it reads before writing it. On a slow system, this
545 may be important. If you suspect you have sparse files, you should
546 benchmark the difference or set sparse for only those files that are
550 \item [readfifo=yes\vb{}no]
551 \index[dir]{readfifo}
552 \index[dir]{Directive!readfifo}
553 If enabled, tells the Client to read the data on a backup and write the
554 data on a restore to any FIFO (pipe) that is explicitly mentioned in the
555 FileSet. In this case, you must have a program already running that
556 writes into the FIFO for a backup or reads from the FIFO on a restore.
557 This can be accomplished with the {\bf RunBeforeJob} directive. If this
558 is not the case, Bacula will hang indefinitely on reading/writing the
559 FIFO. When this is not enabled (default), the Client simply saves the
560 directory entry for the FIFO.
562 Unfortunately, when Bacula runs a RunBeforeJob, it waits until that
563 script terminates, and if the script accesses the FIFO to write
564 into the it, the Bacula job will block and everything will stall.
565 However, Vladimir Stavrinov as supplied tip that allows this feature
566 to work correctly. He simply adds the following to the beginning
567 of the RunBeforeJob script:
573 \item [noatime=yes\vb{}no]
575 \index[dir]{Directive!noatime}
576 If enabled, and if your Operating System supports the O\_NOATIME file
577 open flag, Bacula will open all files to be backed up with this option.
578 It makes it possible to read a file without updating the inode atime
579 (and also without the inode ctime update which happens if you try to set
580 the atime back to its previous value). It also prevents a race
581 condition when two programs are reading the same file, but only one does
582 not want to change the atime. It's most useful for backup programs and
583 file integrity checkers (and bacula can fit on both categories).
585 This option is particularly useful for sites where users are sensitive
586 to their MailBox file access time. It replaces both the {\bf keepatime}
587 option without the inconveniences of that option (see below).
589 If your Operating System does not support this option, it will be
590 silently ignored by Bacula.
593 \item [mtimeonly=yes\vb{}no]
594 \index[dir]{mtimeonly}
595 \index[dir]{Directive!mtimeonly}
596 If enabled, tells the Client that the selection of files during
597 Incremental and Differential backups should based only on the st\_mtime
598 value in the stat() packet. The default is {\bf no} which means that
599 the selection of files to be backed up will be based on both the
600 st\_mtime and the st\_ctime values. In general, it is not recommended
603 \item [keepatime=yes\vb{}no]
604 \index[dir]{keepatime}
605 \index[dir]{Directive!keepatime}
606 The default is {\bf no}. When enabled, Bacula will reset the st\_atime
607 (access time) field of files that it backs up to their value prior to
608 the backup. This option is not generally recommended as there are very
609 few programs that use st\_atime, and the backup overhead is increased
610 because of the additional system call necessary to reset the times.
611 However, for some files, such as mailboxes, when Bacula backs up the
612 file, the user will notice that someone (Bacula) has accessed the
613 file. In this, case keepatime can be useful.
614 (I'm not sure this works on Win32).
616 Note, if you use this feature, when Bacula resets the access time, the
617 change time (st\_ctime) will automatically be modified by the system,
618 so on the next incremental job, the file will be backed up even if
619 it has not changed. As a consequence, you will probably also want
620 to use {\bf mtimeonly = yes} as well as keepatime (thanks to
621 Rudolf Cejka for this tip).
623 \item [checkfilechanges=yes\vb{}no]
624 \index[dir]{checkfilechanges}
625 \index[dir]{Directive!checkfilechanges}
626 On versions 2.0.4 or greater,
627 if enabled, the Client will check size, age of each file after
628 their backup to see if they have changed during backup. If time
629 or size mismatch, an error will raise.
632 zog-fd: Client1.2007-03-31_09.46.21 Error: /tmp/test mtime changed during backup.
635 In general, it is recommended to use this option.
637 \item [hardlinks=yes\vb{}no]
638 \index[dir]{hardlinks}
639 \index[dir]{Directive!hardlinks}
640 When enabled (default), this directive will cause hard links to be
641 backed up. However, the File daemon keeps track of hard linked files and
642 will backup the data only once. The process of keeping track of the
643 hard links can be quite expensive if you have lots of them (tens of
644 thousands or more). This doesn't occur on normal Unix systems, but if
645 you use a program like BackupPC, it can create hundreds of thousands, or
646 even millions of hard links. Backups become very long and the File daemon
647 will consume a lot of CPU power checking hard links. In such a case,
648 set {\bf hardlinks=no} and hard links will not be backed up. Note, using
649 this option will most likely backup more data and on a restore the file
650 system will not be restored identically to the original.
652 \item [wild=\lt{}string\gt{}]
654 \index[dir]{Directive!wild}
655 Specifies a wild-card string to be applied to the filenames and
656 directory names. Note, if {\bf Exclude} is not enabled, the wild-card
657 will select which files are to be included. If {\bf Exclude=yes} is
658 specified, the wild-card will select which files are to be excluded.
659 Multiple wild-card directives may be specified, and they will be applied
660 in turn until the first one that matches. Note, if you exclude a
661 directory, no files or directories below it will be matched.
663 You may want to test your expressions prior to running your
664 backup by using the bwild program. Please see the
665 \bsysxrlink{Utilities}{bwild}{utility}{chapter} of the \utilityman{} for
666 more information. You can also test your full FileSet definition by using
667 the \bsysxrlink{estimate}{estimate}{console}{command} in the \consoleman{}.
668 It is recommended to enclose the string in double quotes.
670 \item [wilddir=\lt{}string\gt{}]
672 \index[dir]{Directive!wilddir}
673 Specifies a wild-card string to be applied to directory names only. No
674 filenames will be matched by this directive. Note, if {\bf Exclude} is
675 not enabled, the wild-card will select directories to be
676 included. If {\bf Exclude=yes} is specified, the wild-card will select
677 which directories are to be excluded. Multiple wild-card directives may be
678 specified, and they will be applied in turn until the first one that
679 matches. Note, if you exclude a directory, no files or directories
680 below it will be matched.
682 It is recommended to enclose the string in double quotes.
684 You may want to test your expressions prior to running your
685 backup by using the bwild program. Please see the
686 \bsysxrlink{Utilities}{bwild}{utility}{chapter} of the \utilityman{} for
687 more information. You can also test your full FileSet definition by using
688 the \bsysxrlink{estimate}{estimate}{console}{command} in the \consoleman{}.
689 An example of excluding with the WildDir option on Win32 machines is
692 \item [wildfile=\lt{}string\gt{}]
693 \index[dir]{wildfile}
694 \index[dir]{Directive!wildfile}
695 Specifies a wild-card string to be applied to non-directories. That
696 is no directory entries will be matched by this directive.
697 However, note that the match is done against the full path and filename,
698 so your wild-card string must take into account that filenames
699 are preceded by the full path.
701 is not enabled, the wild-card will select which files are to be
702 included. If {\bf Exclude=yes} is specified, the wild-card will select
703 which files are to be excluded. Multiple wild-card directives may be
704 specified, and they will be applied in turn until the first one that
707 It is recommended to enclose the string in double quotes.
709 You may want to test your expressions prior to running your
710 backup by using the bwild program. Please see the
711 \bsysxrlink{Utilities}{bwild}{utility}{chapter} of the \utilityman{} for
712 more information. You can also test your full FileSet definition by using
713 the \bsysxrlink{estimate}{estimate}{console}{command} in the \consoleman{}.
714 An example of excluding with the WildFile option on Win32 machines is
718 \item [regex=\lt{}string\gt{}]
720 \index[dir]{Directive!regex}
721 Specifies a POSIX extended regular expression to be applied to the
722 filenames and directory names, which include the full path. If {\bf
723 Exclude} is not enabled, the regex will select which files are to be
724 included. If {\bf Exclude=yes} is specified, the regex will select
725 which files are to be excluded. Multiple regex directives may be
726 specified within an Options resource, and they will be applied in turn
727 until the first one that matches. Note, if you exclude a directory, no
728 files or directories below it will be matched.
730 It is recommended to enclose the string in double quotes.
732 The regex libraries differ from one operating system to
733 another, and in addition, regular expressions are complicated,
734 so you may want to test your expressions prior to running your
735 backup by using the bregex program. Please see the
736 \bsysxrlink{Utilities}{bwild}{utility}{chapter} of the \utilityman{} for
737 more information. You can also test your full FileSet definition by using
738 the \bsysxrlink{estimate}{estimate}{console}{command} in the \consoleman{}.
741 You find yourself using a lot of Regex statements, which will cost quite a
742 lot of CPU time, we recommend you simplify them if you can, or better yet
743 convert them to Wild statements which are much more efficient.
746 \item [regexfile=\lt{}string\gt{}]
747 \index[dir]{regexfile}
748 \index[dir]{Directive!regexfile}
749 Specifies a POSIX extended regular expression to be applied to
750 non-directories. No directories will be matched by this directive.
751 However, note that the match is done against the full path and
752 filename, so your regex string must take into account that filenames
753 are preceded by the full path.
754 If {\bf Exclude} is not enabled, the regex will select which files are
755 to be included. If {\bf Exclude=yes} is specified, the regex will
756 select which files are to be excluded. Multiple regex directives may be
757 specified, and they will be applied in turn until the first one that
760 It is recommended to enclose the string in double quotes.
762 The regex libraries differ from one operating system to
763 another, and in addition, regular expressions are complicated,
764 so you may want to test your expressions prior to running your
765 backup by using the bregex program. Please see the
766 \bsysxrlink{bregex}{bregex}{utility}{command} of the \utilityman{} more.
769 \item [regexdir=\lt{}string\gt{}]
770 \index[dir]{regexdir}
771 \index[dir]{Directive!regexdir}
772 Specifies a POSIX extended regular expression to be applied to directory
773 names only. No filenames will be matched by this directive. Note, if
774 {\bf Exclude} is not enabled, the regex will select directories
775 files are to be included. If {\bf Exclude=yes} is specified, the
776 regex will select which files are to be excluded. Multiple
777 regex directives may be specified, and they will be applied in turn
778 until the first one that matches. Note, if you exclude a directory, no
779 files or directories below it will be matched.
781 It is recommended to enclose the string in double quotes.
783 The regex libraries differ from one operating system to
784 another, and in addition, regular expressions are complicated,
785 so you may want to test your expressions prior to running your
786 backup by using the bregex program. Please see the
787 \bsysxrlink{bregex}{bregex}{utility}{command} of the \utilityman{} more.
790 \item [exclude=yes\vb{}no]
792 \index[dir]{Directive!exclude}
793 The default is {\bf no}. When enabled, any files matched within the
794 Options will be excluded from the backup.
797 \item [aclsupport=yes\vb{}no]
798 \index[dir]{aclsupport}
799 \index[dir]{Directive!aclsupport}
800 The default is {\bf no}. If this option is set to yes, and you have the
801 POSIX {\bf libacl} installed on your Linux system, Bacula will backup the
802 file and directory Unix Access Control Lists (ACL) as defined in IEEE Std
803 1003.1e draft 17 and "POSIX.1e" (abandoned). This feature is
804 available on Unix systems only and requires the Linux ACL library. Bacula is
805 automatically compiled with ACL support if the {\bf libacl} library is
806 installed on your Linux system (shown in config.out). While restoring the
807 files Bacula will try to restore the ACLs, if there is no ACL support
808 available on the system, Bacula restores the files and directories but
809 not the ACL information. Please note, if you backup an EXT3 or XFS
810 filesystem with ACLs, then you restore them to a different filesystem
811 (perhaps reiserfs) that does not have ACLs, the ACLs will be ignored.
813 For other operating systems there is support for either POSIX ACLs or
814 the more extensible NFSv4 ACLs.
816 The ACL stream format between Operation Systems is \textbf{not}
817 compatible so for example an ACL saved on Linux cannot be restored on
820 The following Operating Systems are currently supported:
823 \item AIX (pre-5.3 (POSIX) and post 5.3 (POSIX and NFSv4) ACLs)
825 \item FreeBSD (POSIX and NFSv4/ZFS ACLs)
829 \item Solaris (POSIX and NFSv4/ZFS ACLs)
834 \item [xattrsupport=yes\vb{}no]
835 \index[dir]{xattrsupport}
836 \index[dir]{Directive!xattrsupport}
837 The default is {\bf no}. If this option is set to yes, and your
838 operating system support either so called Extended Attributes or
839 Extensible Attributes Bacula will backup the file and directory
840 XATTR data. This feature is available on UNIX only and depends on
841 support of some specific library calls in libc.
843 The XATTR stream format between Operating Systems is {\bf not}
844 compatible so an XATTR saved on Linux cannot for example be restored
847 On some operating systems ACLs are also stored as Extended Attributes
848 (Linux, Darwin, FreeBSD) Bacula checks if you have the aclsupport
849 option enabled and if so will not save the same info when saving
850 extended attribute information. Thus ACLs are only saved once.
852 The following Operating Systems are currently supported:
855 \item AIX (Extended Attributes)
856 \item Darwin (Extended Attributes)
857 \item FreeBSD (Extended Attributes)
858 \item IRIX (Extended Attributes)
859 \item Linux (Extended Attributes)
860 \item NetBSD (Extended Attributes)
861 \item Solaris (Extended Attributes and Extensible Attributes)
862 \item Tru64 (Extended Attributes)
865 \item [ignore case=yes\vb{}no]
866 \index[dir]{ignore case}
867 \index[dir]{Directive!ignore case}
868 The default is {\bf no}. On Windows systems, you will almost surely
869 want to set this to {\bf yes}. When this directive is set to {\bf yes}
870 all the case of character will be ignored in wild-card and regex
871 comparisons. That is an uppercase A will match a lowercase a.
873 \item [fstype=filesystem-type]
875 \index[dir]{Directive!fstype}
876 This option allows you to select files and directories by the
877 filesystem type. The permitted filesystem-type names are:
879 ext2, jfs, ntfs, proc, reiserfs, xfs, usbdevfs, sysfs, smbfs,
880 iso9660. For ext3 systems, use ext2.
882 You may have multiple Fstype directives, and thus permit matching
883 of multiple filesystem types within a single Options resource. If
884 the type specified on the fstype directive does not match the
885 filesystem for a particular directive, that directory will not be
886 backed up. This directive can be used to prevent backing up
887 non-local filesystems. Normally, when you use this directive, you
888 would also set {\bf onefs=no} so that Bacula will traverse filesystems.
890 This option is not implemented in Win32 systems.
892 \item [DriveType=Windows-drive-type]
893 \index[dir]{DriveType}
894 \index[dir]{Directive!DriveType}
895 This option is effective only on Windows machines and is
896 somewhat similar to the Unix/Linux {\bf fstype} described
897 above, except that it allows you to select what Windows
898 drive types you want to allow. By default all drive
901 The permitted drivetype names are:
903 removable, fixed, remote, cdrom, ramdisk
905 You may have multiple Driveype directives, and thus permit matching
906 of multiple drive types within a single Options resource. If
907 the type specified on the drivetype directive does not match the
908 filesystem for a particular directive, that directory will not be
909 backed up. This directive can be used to prevent backing up
910 non-local filesystems. Normally, when you use this directive, you
911 would also set {\bf onefs=no} so that Bacula will traverse filesystems.
913 This option is not implemented in Unix/Linux systems.
916 \item [hfsplussupport=yes\vb{}no]
917 \index[dir]{hfsplussupport}
918 \index[dir]{Directive!hfsplussupport}
919 This option allows you to turn on support for Mac OSX HFS plus
922 \item [strippath=\lt{}integer\gt{}]
923 \index[dir]{strippath}
924 \index[dir]{Directive!strippath}
925 This option will cause {\bf integer} paths to be stripped from
926 the front of the full path/filename being backed up. This can
927 be useful if you are migrating data from another vendor or if
928 you have taken a snapshot into some subdirectory. This directive
929 can cause your filenames to be overlayed with regular backup data,
930 so should be used only by experts and with great care.
933 {\bf \lt{}file-list\gt{}} is a list of directory and/or filename names
934 specified with a {\bf File =} directive. To include names containing spaces,
935 enclose the name between double-quotes. Wild-cards are not interpreted
936 in file-lists. They can only be specified in Options resources.
938 There are a number of special cases when specifying directories and files in a
939 {\bf file-list}. They are:
942 \item Any name preceded by an at-sign (@) is assumed to be the name of a
943 file, which contains a list of files each preceded by a "File =". The
944 named file is read once when the configuration file is parsed during the
945 Director startup. Note, that the file is read on the Director's machine
946 and not on the Client's. In fact, the @filename can appear anywhere
947 within the conf file where a token would be read, and the contents of
948 the named file will be logically inserted in the place of the @filename.
949 What must be in the file depends on the location the @filename is
950 specified in the conf file. For example:
955 Options { compression=GZIP }
956 @/home/files/my-files
961 \item Any name beginning with a vertical bar (\vb) is assumed to be the name of
962 a program. This program will be executed on the Director's machine at
963 the time the Job starts (not when the Director reads the configuration
964 file), and any output from that program will be assumed to be a list of
965 files or directories, one per line, to be included. Before submitting the
966 specified command bacula will performe
967 \ilink{character substitution}{character substitution}.
969 This allows you to have a job that, for example, includes all the local
970 partitions even if you change the partitioning by adding a disk. The
971 examples below show you how to do this. However, please note two
973 1. if you want the local filesystems, you probably should be
974 using the new {\bf fstype} directive, which was added in version 1.36.3
975 and set {\bf onefs=no}.
978 2. the exact syntax of the command needed in the examples below is very
979 system dependent. For example, on recent Linux systems, you may need to
980 add the -P option, on FreeBSD systems, the options will be different as
983 In general, you will need to prefix your command or commands with a {\bf
984 sh -c} so that they are invoked by a shell. This will not be the case
985 if you are invoking a script as in the second example below. Also, you
986 must take care to escape (precede with a \textbackslash{}) wild-cards,
987 shell character, and to ensure that any spaces in your command are
988 escaped as well. If you use a single quotes (') within a double quote
989 ("), Bacula will treat everything between the single quotes as one field
990 so it will not be necessary to escape the spaces. In general, getting
991 all the quotes and escapes correct is a real pain as you can see by the
992 next example. As a consequence, it is often easier to put everything in
993 a file and simply use the file name within Bacula. In that case the
994 {\bf sh -c} will not be necessary providing the first line of the file
1003 Options { signature = SHA1 }
1004 File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
1005 | awk \"{print \\$6}\"'"
1010 will produce a list of all the local partitions on a Red Hat Linux system.
1011 Note, the above line was split, but should normally be written on one line.
1012 Quoting is a real problem because you must quote for Bacula which consists of
1013 preceding every \textbackslash{} and every " with a \textbackslash{}, and
1014 you must also quote for the shell command. In the end, it is probably easier
1015 just to execute a small file with:
1024 File = "|my_partitions"
1029 where my\_partitions has:
1034 df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
1039 If the vertical bar (\lstinline+|+) in front of my\_partitions is preceded by a
1040 backslash as in \textbackslash{}\lstinline+|+, the program will be executed on the
1041 Client's machine instead of on the Director's machine.
1042 Please note that if the filename is given within quotes, you
1043 will need to use two slashes. An example, provided by John Donagher,
1044 that backs up all the local UFS partitions on a remote system is:
1049 Name = "All local partitions"
1051 Options { signature=SHA1; onefs=yes; }
1052 File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
1058 The above requires two backslash characters after the double quote (one
1059 preserves the next one). If you are a Linux user, just change the {\bf ufs}
1060 to {\bf ext3} (or your preferred filesystem type), and you will be in
1063 If you know what filesystems you have mounted on your system, e.g.
1064 for Red Hat Linux normally only ext2 and ext3, you can backup
1065 all local filesystems using something like:
1071 Options { signature = SHA1; onfs=no; fstype=ext2 }
1078 \item Any file-list item preceded by a less-than sign (\lt{}) will be taken
1079 to be a file. This file will be read on the Director's machine (see
1080 below for doing it on the Client machine) at the time
1081 the Job starts, and the data will be assumed to be a list of directories or
1082 files, one per line, to be included. The names should start in column 1 and
1083 should not be quoted even if they contain spaces. This feature allows you to
1084 modify the external file and change what will be saved without stopping and
1085 restarting Bacula as would be necessary if using the @ modifier noted above.
1091 Options { signature = SHA1 }
1092 File = "</home/files/local-filelist"
1097 If you precede the less-than sign (\lt{}) with a backslash as in
1098 \textbackslash{}\lt{}, the file-list will be read on the Client machine
1099 instead of on the Director's machine. Please note that if the filename
1100 is given within quotes, you will need to use two slashes.
1105 Options { signature = SHA1 }
1106 File = "\\</home/xxx/filelist-on-client"
1111 \item If you explicitly specify a block device such as {\bf /dev/hda1}, then
1112 Bacula (starting with version 1.28) will assume that this is a raw partition
1113 to be backed up. In this case, you are strongly urged to specify a {\bf
1114 sparse=yes} include option, otherwise, you will save the whole partition
1115 rather than just the actual data that the partition contains. For example:
1120 Options { signature=MD5; sparse=yes }
1126 will backup the data in device /dev/hd6. Note, the {bf /dev/hd6} must be
1127 the raw partition itself. Bacula will not back it up as a raw device if
1128 you specify a symbolic link to a raw device such as my be created by the
1129 LVM Snapshot utilities.
1131 Ludovic Strappazon has pointed out that this feature can be used to backup a
1132 full Microsoft Windows disk. Simply boot into the system using a Linux Rescue
1133 disk, then load a statically linked Bacula as described in the
1134 \ilink{ Disaster Recovery Using Bacula}{RescueChapter} chapter of
1135 this manual. Then save the whole disk partition. In the case of a disaster,
1136 you can then restore the desired partition by again booting with the rescue
1137 disk and doing a restore of the partition.
1138 \item If you explicitly specify a FIFO device name (created with mkfifo), and
1139 you add the option {\bf readfifo=yes} as an option, Bacula will read the FIFO
1140 and back its data up to the Volume. For example:
1149 File = /home/abc/fifo
1154 if {\bf /home/abc/fifo} is a fifo device, Bacula will open the fifo,
1155 read it, and store all data thus obtained on the Volume. Please note,
1156 you must have a process on the system that is writing into the fifo, or
1157 Bacula will hang, and after one minute of waiting, Bacula will give up
1158 and go on to the next file. The data read can be anything since Bacula
1159 treats it as a stream.
1161 This feature can be an excellent way to do a "hot" backup of a very
1162 large database. You can use the {\bf RunBeforeJob} to create the fifo
1163 and to start a program that dynamically reads your database and writes
1164 it to the fifo. Bacula will then write it to the Volume. Be sure to
1165 read the \ilink{readfifo section}{readfifo} that gives a
1166 tip to ensure that the RunBeforeJob does not block Bacula.
1168 During the restore operation, the inverse is true, after Bacula creates
1169 the fifo if there was any data stored with it (no need to explicitly
1170 list it or add any options), that data will be written back to the fifo.
1171 As a consequence, if any such FIFOs exist in the fileset to be restored,
1172 you must ensure that there is a reader program or Bacula will block, and
1173 after one minute, Bacula will time out the write to the fifo and move on
1176 \item A file-list may not contain wild-cards. Use directives in the
1177 Options resource if you wish to specify wild-cards or regular expression
1181 \index[general]{IgnoreDir}
1182 The {\bf ExcludeDirContaining = \lt{}filename\gt{}} is a directive that
1183 can be added to the Include section of the FileSet resource. If the specified
1184 filename ({\bf filename-string}) is found on the Client in any directory to be
1185 backed up, the whole directory will be ignored (not backed up). For example:
1188 # List of files to be backed up
1196 Exclude Dir Containing = .excludeme
1201 But in /home, there may be hundreds of directories of users and some
1202 people want to indicate that they don't want to have certain
1203 directories backed up. For example, with the above FileSet, if
1204 the user or sysadmin creates a file named {\bf .excludeme} in
1205 specific directories, such as
1208 /home/user/www/cache/.excludeme
1209 /home/user/temp/.excludeme
1212 then Bacula will not backup the two directories named:
1215 /home/user/www/cache
1219 NOTE: subdirectories will not be backed up. That is, the directive
1220 applies to the two directories in question and any children (be they
1221 files, directories, etc).
1225 \section{FileSet Examples}
1226 \index[general]{Examples!FileSet }
1227 \index[general]{FileSet Examples}
1229 The following is an example of a valid FileSet resource definition. Note,
1230 the first Include pulls in the contents of the file {\bf /etc/backup.list}
1231 when Bacula is started (i.e. the @), and that file must have each filename
1232 to be backed up preceded by a {\bf File =} and on a separate line.
1253 File = /usr/lib/another_file
1259 In the above example, all the files contained in /etc/backup.list will
1260 be compressed with GZIP compression, an SHA1 signature will be computed on the
1261 file's contents (its data), and sparse file handling will apply.
1263 The two directories /root/myfile and /usr/lib/another\_file will also be saved
1264 without any options, but all files in those directories with the extensions
1265 {\bf .o} and {\bf .exe} will be excluded.
1267 Let's say that you now want to exclude the directory /tmp. The simplest way
1268 to do so is to add an exclude directive that lists /tmp. The example
1269 above would then become:
1290 File = /usr/lib/another_file
1293 File = /tmp # don't add trailing /
1300 You can add wild-cards to the File directives listed in the Exclude
1301 directory, but you need to take care because if you exclude a directory,
1302 it and all files and directories below it will also be excluded.
1304 Now lets take a slight variation on the above and suppose
1305 you want to save all your whole filesystem except {\bf /tmp}.
1306 The problem that comes up is that Bacula will not normally
1307 cross from one filesystem to another.
1308 Doing a {\bf df} command, you get the following output:
1313 Filesystem 1k-blocks Used Available Use% Mounted on
1314 /dev/hda5 5044156 439232 4348692 10% /
1315 /dev/hda1 62193 4935 54047 9% /boot
1316 /dev/hda9 20161172 5524660 13612372 29% /home
1317 /dev/hda2 62217 6843 52161 12% /rescue
1318 /dev/hda8 5044156 42548 4745376 1% /tmp
1319 /dev/hda6 5044156 2613132 2174792 55% /usr
1320 none 127708 0 127708 0% /dev/shm
1321 //minimatou/c$ 14099200 9895424 4203776 71% /mnt/mmatou
1322 lmatou:/ 1554264 215884 1258056 15% /mnt/matou
1323 lmatou:/home 2478140 1589952 760072 68% /mnt/matou/home
1324 lmatou:/usr 1981000 1199960 678628 64% /mnt/matou/usr
1325 lpmatou:/ 995116 484112 459596 52% /mnt/pmatou
1326 lpmatou:/home 19222656 2787880 15458228 16% /mnt/pmatou/home
1327 lpmatou:/usr 2478140 2038764 311260 87% /mnt/pmatou/usr
1328 deuter:/ 4806936 97684 4465064 3% /mnt/deuter
1329 deuter:/home 4806904 280100 4282620 7% /mnt/deuter/home
1330 deuter:/files 44133352 27652876 14238608 67% /mnt/deuter/files
1334 And we see that there are a number of separate filesystems (/ /boot
1335 /home /rescue /tmp and /usr not to mention mounted systems).
1336 If you specify only {\bf /} in your Include list, Bacula will only save the
1337 Filesystem {\bf /dev/hda5}. To save all filesystems except {\bf /tmp} with
1338 out including any of the Samba or NFS mounted systems, and explicitly
1339 excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to
1340 be saved and restored, you can use the following:
1345 Name = Include_example
1350 wildfile = "/.journal"
1351 wildfile = "/.autofsck"
1364 Since /tmp is on its own filesystem and it was not explicitly named in the
1365 Include list, it is not really needed in the exclude list. It is better to
1366 list it in the Exclude list for clarity, and in case the disks are changed so
1367 that it is no longer in its own partition.
1369 Now, lets assume you only want to backup .Z and .gz files and nothing
1370 else. This is a bit trickier because Bacula by default will select
1371 everything to backup, so we must exclude everything but .Z and .gz files.
1372 If we take the first example above and make the obvious modifications
1373 to it, we might come up with a FileSet that looks like this:
1379 Include { !!!!!!!!!!!!
1381 wildfile = "*.Z" example
1382 wildfile = "*.gz" doesn't
1391 The *.Z and *.gz files will indeed be backed up, but all other files
1392 that are not matched by the Options directives will automatically
1393 be backed up too (i.e. that is the default rule).
1395 To accomplish what we want, we must explicitly exclude all other files.
1396 We do this with the following:
1417 The "trick" here was to add a RegexFile expression that matches
1418 all files. It does not match directory names, so all directories in
1419 /myfile will be backed up (the directory entry) and any *.Z and *.gz
1420 files contained in them. If you know that certain directories do
1421 not contain any *.Z or *.gz files and you do not want the directory
1422 entries backed up, you will need to explicitly exclude those directories.
1423 Backing up a directory entries is not very expensive.
1425 Bacula uses the system regex library and some of them are
1426 different on different OSes. The above has been reported not to work
1427 on FreeBSD. This can be tested by using the {\bf estimate job=job-name
1428 listing} command in the console and adapting the RegexFile expression
1429 appropriately. In a future version of Bacula, we will supply our own
1430 Regex code to avoid such system dependencies.
1432 Please be aware that allowing Bacula to traverse or change file systems can be
1433 {\bf very} dangerous. For example, with the following:
1438 Name = "Bad example"
1440 Options { onefs=no }
1447 you will be backing up an NFS mounted partition ({\bf /mnt/matou}), and since
1448 {\bf onefs} is set to {\bf no}, Bacula will traverse file systems. Now if {\bf
1449 /mnt/matou} has the current machine's file systems mounted, as is often the
1450 case, you will get yourself into a recursive loop and the backup will never
1453 As a final example, let's say that you have only one or two
1454 subdirectories of /home that you want to backup. For example,
1455 you want to backup only subdirectories beginning with the letter
1456 a and the letter b -- i.e. /home/a* and /home/b*. Now, you might first
1464 wilddir = "/home/a*"
1465 wilddir = "/home/b*"
1473 The problem is that the above will include everything in /home. To get
1474 things to work correctly, you need to start with the idea of exclusion
1475 instead of inclusion. So, you could simply exclude all directories
1476 except the two you want to use:
1483 RegexDir = "^/home/[c-z]"
1492 And assuming that all subdirectories start with a lowercase letter, this
1495 An alternative would be to include the two subdirectories desired and
1496 exclude everything else:
1503 wilddir = "/home/a*"
1504 wilddir = "/home/b*"
1517 The following example shows how to back up only the My Pictures directory inside
1518 the My Documents directory for all users in C:/Documents and Settings, i.e.
1519 everything matching the pattern:
1521 C:/Documents and Settings/*/My Documents/My Pictures/*
1523 To understand how this can be achieved, there are two important points to
1526 Firstly, Bacula walks over the filesystem depth-first starting from the File =
1527 lines. It stops descending when a directory is excluded, so you must include
1528 all ancestor directories of each directory containing files to be included.
1530 Secondly, each directory and file is compared to the Options clauses in the
1531 order they appear in the FileSet. When a match is found, no further clauses
1532 are compared and the directory or file is either included or excluded.
1534 The FileSet resource definition below implements this by including specifc
1535 directories and files and excluding everything else.
1540 Name = "AllPictures"
1544 File = "C:/Documents and Settings"
1551 # Include all users' directories so we reach the inner ones. Unlike a
1552 # WildDir pattern ending in *, this RegExDir only matches the top-level
1553 # directories and not any inner ones.
1554 RegExDir = "^C:/Documents and Settings/[^/]+$"
1556 # Ditto all users' My Documents directories.
1557 WildDir = "C:/Documents and Settings/*/My Documents"
1559 # Ditto all users' My Documents/My Pictures directories.
1560 WildDir = "C:/Documents and Settings/*/My Documents/My Pictures"
1562 # Include the contents of the My Documents/My Pictures directories and
1563 # any subdirectories.
1564 Wild = "C:/Documents and Settings/*/My Documents/My Pictures/*"
1571 # Exclude everything else, in particular any files at the top level and
1572 # any other directories or files in the users' directories.
1573 Wild = "C:/Documents and Settings/*"
1580 \section{Backing up Raw Partitions}
1581 \index[general]{Backing up!Partitions }
1582 \index[general]{Backing up Raw Partitions }
1584 The following FileSet definition will backup a raw partition:
1589 Name = "RawPartition"
1591 Options { sparse=yes }
1598 While backing up and restoring a raw partition, you should ensure that no
1599 other process including the system is writing to that partition. As a
1600 precaution, you are strongly urged to ensure that the raw partition is not
1601 mounted or is mounted read-only. If necessary, this can be done using the {\bf
1602 RunBeforeJob} directive.
1605 \section{Excluding Files and Directories}
1606 \index[general]{Directories!Excluding Files and }
1607 \index[general]{Excluding Files and Directories }
1609 You may also include full filenames or directory names in addition to using
1610 wild-cards and {\bf Exclude=yes} in the Options resource as specified above by
1611 simply including the files to be excluded in an Exclude resource within the
1612 FileSet. It accepts wild-cards pattern, so for a directory, don't add a trailing
1618 Name = Exclusion_example
1631 File = /tmp # Don't add trailing /
1640 \section{Windows FileSets}
1641 \index[general]{Windows FileSets }
1642 \index[general]{FileSets!Windows }
1643 If you are entering Windows file names, the directory path may be preceded by
1644 the drive and a colon (as in c:). However, the path separators must be
1645 specified in Unix convention (i.e. forward slash (/)). If you wish to include
1646 a quote in a file name, precede the quote with a backslash
1647 (\textbackslash{}). For example you might use the following
1648 for a Windows machine to backup the "My Documents" directory:
1653 Name = "Windows Set"
1660 File = "c:/My Documents"
1666 For exclude lists to work correctly on Windows, you must observe the following
1670 \item Filenames are case sensitive, so you must use the correct case.
1671 \item To exclude a directory, you must not have a trailing slash on the
1673 \item If you have spaces in your filename, you must enclose the entire name
1674 in double-quote characters ("). Trying to use a backslash before the space
1676 \item If you are using the old Exclude syntax (noted below), you may not
1677 specify a drive letter in the exclude. The new syntax noted above
1678 should work fine including driver letters.
1681 Thanks to Thiago Lima for summarizing the above items for us. If you are
1682 having difficulties getting includes or excludes to work, you might want to
1683 try using the {\bf estimate job=xxx listing} command documented in the
1684 \bsysxrlink{estimate}{estimate}{console}{command} of \consoleman{}.
1686 On Win32 systems, if you move a directory or file or rename a file into the
1687 set of files being backed up, and a Full backup has already been made, Bacula
1688 will not know there are new files to be saved during an Incremental or
1689 Differential backup (blame Microsoft, not me). To avoid this problem, please
1690 {\bf copy} any new directory or files into the backup area. If you do not have
1691 enough disk to copy the directory or files, move them, but then initiate a
1695 \paragraph*{A Windows Example FileSet}
1696 \index[general]{FileSet!Windows Example }
1697 \index[general]{Windows Example FileSet }
1699 The following example was contributed by Russell Howe. Please note that
1700 for presentation purposes, the lines beginning with Data and Internet
1701 have been wrapped and should included on the previous line with one
1706 This is my Windows 2000 fileset:
1708 Name = "Windows 2000"
1714 # Exclude Mozilla-based programs' file caches
1715 WildDir = "[A-Z]:/Documents and Settings/*/Application
1716 Data/*/Profiles/*/*/Cache"
1717 WildDir = "[A-Z]:/Documents and Settings/*/Application
1718 Data/*/Profiles/*/*/Cache.Trash"
1719 WildDir = "[A-Z]:/Documents and Settings/*/Application
1720 Data/*/Profiles/*/*/ImapMail"
1722 # Exclude user's registry files - they're always in use anyway.
1723 WildFile = "[A-Z]:/Documents and Settings/*/Local Settings/Application
1724 Data/Microsoft/Windows/usrclass.*"
1725 WildFile = "[A-Z]:/Documents and Settings/*/ntuser.*"
1727 # Exclude directories full of lots and lots of useless little files
1728 WildDir = "[A-Z]:/Documents and Settings/*/Cookies"
1729 WildDir = "[A-Z]:/Documents and Settings/*/Recent"
1730 WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/History"
1731 WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temp"
1732 WildDir = "[A-Z]:/Documents and Settings/*/Local Settings/Temporary
1735 # These are always open and unable to be backed up
1736 WildFile = "[A-Z]:/Documents and Settings/All Users/Application
1737 Data/Microsoft/Network/Downloader/qmgr[01].dat"
1739 # Some random bits of Windows we want to ignore
1740 WildFile = "[A-Z]:/WINNT/security/logs/scepol.log"
1741 WildDir = "[A-Z]:/WINNT/system32/config"
1742 WildDir = "[A-Z]:/WINNT/msdownld.tmp"
1743 WildDir = "[A-Z]:/WINNT/Internet Logs"
1744 WildDir = "[A-Z]:/WINNT/$Nt*Uninstall*"
1745 WildDir = "[A-Z]:/WINNT/sysvol"
1746 WildFile = "[A-Z]:/WINNT/cluster/CLUSDB"
1747 WildFile = "[A-Z]:/WINNT/cluster/CLUSDB.LOG"
1748 WildFile = "[A-Z]:/WINNT/NTDS/edb.log"
1749 WildFile = "[A-Z]:/WINNT/NTDS/ntds.dit"
1750 WildFile = "[A-Z]:/WINNT/NTDS/temp.edb"
1751 WildFile = "[A-Z]:/WINNT/ntfrs/jet/log/edb.log"
1752 WildFile = "[A-Z]:/WINNT/ntfrs/jet/ntfrs.jdb"
1753 WildFile = "[A-Z]:/WINNT/ntfrs/jet/temp/tmp.edb"
1754 WildFile = "[A-Z]:/WINNT/system32/CPL.CFG"
1755 WildFile = "[A-Z]:/WINNT/system32/dhcp/dhcp.mdb"
1756 WildFile = "[A-Z]:/WINNT/system32/dhcp/j50.log"
1757 WildFile = "[A-Z]:/WINNT/system32/dhcp/tmp.edb"
1758 WildFile = "[A-Z]:/WINNT/system32/LServer/edb.log"
1759 WildFile = "[A-Z]:/WINNT/system32/LServer/TLSLic.edb"
1760 WildFile = "[A-Z]:/WINNT/system32/LServer/tmp.edb"
1761 WildFile = "[A-Z]:/WINNT/system32/wins/j50.log"
1762 WildFile = "[A-Z]:/WINNT/system32/wins/wins.mdb"
1763 WildFile = "[A-Z]:/WINNT/system32/wins/winstmp.mdb"
1765 # Temporary directories & files
1766 WildDir = "[A-Z]:/WINNT/Temp"
1767 WildDir = "[A-Z]:/temp"
1769 WildDir = "[A-Z]:/tmp"
1770 WildDir = "[A-Z]:/var/tmp"
1773 WildDir = "[A-Z]:/RECYCLER"
1776 WildFile = "[A-Z]:/pagefile.sys"
1778 # These are programs and are easier to reinstall than restore from
1780 WildDir = "[A-Z]:/cygwin"
1781 WildDir = "[A-Z]:/Program Files/Grisoft"
1782 WildDir = "[A-Z]:/Program Files/Java"
1783 WildDir = "[A-Z]:/Program Files/Java Web Start"
1784 WildDir = "[A-Z]:/Program Files/JavaSoft"
1785 WildDir = "[A-Z]:/Program Files/Microsoft Office"
1786 WildDir = "[A-Z]:/Program Files/Mozilla Firefox"
1787 WildDir = "[A-Z]:/Program Files/Mozilla Thunderbird"
1788 WildDir = "[A-Z]:/Program Files/mozilla.org"
1789 WildDir = "[A-Z]:/Program Files/OpenOffice*"
1792 # Our Win2k boxen all have C: and D: as the main hard drives.
1800 Note, the three line of the above Exclude were split to fit on the document
1801 page, they should be written on a single line in real use.
1803 \paragraph*{Windows NTFS Naming Considerations}
1804 \index[general]{Windows NTFS Naming Considerations }
1805 \index[general]{Considerations!Windows NTFS Naming }
1807 NTFS filenames containing Unicode characters should now be supported
1808 as of version 1.37.30 or later.
1810 \section{Testing Your FileSet}
1811 \index[general]{FileSet!Testing Your }
1812 \index[general]{Testing Your FileSet }
1814 If you wish to get an idea of what your FileSet will really backup or if your
1815 exclusion rules will work correctly, you can test it by using the {\bf
1816 estimate} command in the Console program. See the
1817 \bsysxrlink{estimate}{estimate}{console}{command} of \consoleman{}.
1819 As an example, suppose you add the following test FileSet:
1826 File = /home/xxx/test
1835 You could then add some test files to the directory {\bf /home/xxx/test}
1836 and use the following command in the console:
1840 estimate job=<any-job-name> listing client=<desired-client> fileset=Test
1844 to give you a listing of all files that match. In the above
1845 example, it should be only files with names ending in {\textbf .c}.