Debian Codegraph @

manuals/en/main/fileset.tex

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