Of all the configuration files needed to run Bacula, the Director's is the most complicated, and the one that you will need to modify the most often as you add clients or modify the FileSets.
For a general discussion of configuration files and resources including the data types recognized by Bacula. Please see the Configuration chapter of this manual.
Director resource type may be one of the following:
Job, JobDefs, Client, Storage, Catalog, Schedule, FileSet, Pool, Director, or Messages. We present them here in the most logical order for defining them:
The Director resource defines the attributes of the Directors running on the network. In the current implementation, there is only a single Director resource, but the final design will contain multiple Directors to maintain index and media database redundancy.
If you have specified a Director user and/or a Director group on your ./configure line with --with-dir-user and/or --with-dir-group the Working Directory owner and group will be set to those values.
Typically on Linux systems, you will set this to: /var/run. If you are not installing Bacula in the system directories, you can use the Working Directory as defined above. This directive is required.
Please note that the Volume format becomes much more complicated with multiple simultaneous jobs, consequently, restores can take much longer if Bacula must sort through interleaved volume blocks from multiple simultaneous jobs. This can be avoided by having each simultaneously running job write to a different volume or by using data spooling, which will first spool the data to disk simultaneously, then write each spool file to the volume in sequence.
There may also still be some cases where directives such as Maximum Volume Jobs are not properly synchronized with multiple simultaneous jobs (subtle timing issues can arise), so careful testing is recommended.
At the current time, there is no configuration parameter set to limit the number of console connections. A maximum of five simultaneous console connections are permitted.
For more details on getting concurrent jobs to run, please see Running Concurrent Jobs in the Tips chapter of this manual.
DirAddresses = { ip = {
addr = 1.2.3.4; port = 1205;}
ipv4 = {
addr = 1.2.3.4; port = http;}
ipv6 = {
addr = 1.2.3.4;
port = 1205;
}
ip = {
addr = 1.2.3.4
port = 1205
}
ip = {
addr = 1.2.3.4
}
ip = {
addr = 201:220:222::2
}
ip = {
addr = bluedot.thun.net
}
}
where ip, ip4, ip6, addr, and port are all keywords. Note, that the address can be specified as either a dotted quadruple, or IPv6 colon notation, or as a symbolic name (only in the ip specification). Also, port can be specified as a number or as the mnemonic value from the /etc/services file. If a port is not specified, the default will be used. If an ip section is specified, the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then only IPv4 resolutions will be permitted, and likewise with ip6.
Please note that if you use the DirAddresses directive, you must not use either a DirPort or a DirAddress directive in the same resource.
The following is an example of a valid Director resource definition:
Director {
Name = HeadMan
WorkingDirectory = "$HOME/bacula/bin/working"
Password = UA_password
PidDirectory = "$HOME/bacula/bin/working"
QueryFile = "$HOME/bacula/bin/query.sql"
Messages = Standard
}
The Job resource defines a Job (Backup, Restore, ...) that Bacula must perform. Each Job resource definition contains the name of a Client and a FileSet to backup, the Schedule for the Job, where the data are to be stored, and what media Pool can be used. In effect, each Job resource must specify What, Where, How, and When or FileSet, Storage, Backup/Restore/Level, and Schedule respectively. Note, the FileSet must be specified for a restore job for historical reasons, but it is no longer used.
Only a single type (Backup, Restore, ...) can be specified for any job. If you want to backup multiple FileSets on the same Client or multiple Clients, you must define a Job for each one.
When the job actually runs, the unique Job Name will consist of the name you specify here followed by the date and time the job was scheduled for execution. This directive is required.
For a Backup Job, the Level may be one of the following:
If all the above conditions do not hold, the Director will upgrade the Incremental to a Full save. Otherwise, the Incremental backup will be performed as requested.
The File daemon (Client) decides which files to backup for an Incremental backup by comparing start time of the prior Job (Full, Differential, or Incremental) against the time each file was last "modified" (st_mtime) and the time its attributes were last "changed"(st_ctime). If the file was modified or its attributes changed on or after this start time, it will then be backed up.
Some virus scanning software may change st_ctime while
doing the scan. For example, if the virus scanning program attempts to
reset the access time (st_atime), which Bacula does not use, it will
cause st_ctime to change and hence Bacula will backup the file during
an Incremental or Differential backup. In the case of Sophos virus
scanning, you can prevent it from resetting the access time (st_atime)
and hence changing st_ctime by using the --no-reset-atime
option. For other software, please see their manual.
When Bacula does an Incremental backup, all modified files that are still on the system are backed up. However, any file that has been deleted since the last Full backup remains in the Bacula catalog, which means that if between a Full save and the time you do a restore, some files are deleted, those deleted files will also be restored. The deleted files will no longer appear in the catalog after doing another Full save. However, to remove deleted files from the catalog during an Incremental backup is quite a time consuming process and not currently implemented in Bacula.
In addition, if you move a directory rather than copy it, the files in it do not have their modification time (st_mtime) or their attribute change time (st_ctime) changed. As a consequence, those files will probably not be backed up by an Incremental or Differential backup which depend solely on these time stamps. If you move a directory, and wish it to be properly backed up, it is generally preferable to copy it, then delete the original.
If all the above conditions do not hold, the Director will upgrade the Differential to a Full save. Otherwise, the Differential backup will be performed as requested.
The File daemon (Client) decides which files to backup for a differential backup by comparing the start time of the prior Full backup Job against the time each file was last "modified" (st_mtime) and the time its attributes were last "changed" (st_ctime). If the file was modified or its attributes were changed on or after this start time, it will then be backed up. The start time used is displayed after the Since on the Job report. In rare cases, using the start time of the prior backup may cause some files to be backed up twice, but it ensures that no change is missed. As with the Incremental option, you should ensure that the clocks on your server and client are synchronized or as close as possible to avoid the possibility of a file being skipped. Note, on versions 1.33 or greater Bacula automatically makes the necessary adjustments to the time between the server and the client so that the times Bacula uses are synchronized.
When Bacula does a Differential backup, all modified files that are still on the system are backed up. However, any file that has been deleted since the last Full backup remains in the Bacula catalog, which means that if between a Full save and the time you do a restore, some files are deleted, those deleted files will also be restored. The deleted files will no longer appear in the catalog after doing another Full save. However, to remove deleted files from the catalog during a Differential backup is quite a time consuming process and not currently implemented in Bacula. It is, however, a planned future feature.
As noted above, if you move a directory rather than copy it, the files in it do not have their modification time (st_mtime) or their attribute change time (st_ctime) changed. As a consequence, those files will probably not be backed up by an Incremental or Differential backup which depend solely on these time stamps. If you move a directory, and wish it to be properly backed up, it is generally preferable to copy it, then delete the original. Alternatively, you can move the directory, then use the touch program to update the timestamps.
Every once and a while, someone asks why we need Differential backups as long as Incremental backups pickup all changed files. There are possibly many answers to this question, but the one that is the most important for me is that a Differential backup effectively merges all the Incremental and Differential backups since the last Full backup into a single Differential backup. This has two effects: 1. It gives some redundancy since the old backups could be used if the merged backup cannot be read. 2. More importantly, it reduces the number of Volumes that are needed to do a restore effectively eliminating the need to read all the volumes on which the preceding Incremental and Differential backups since the last Full are done.
For a Restore Job, no level needs to be specified.
For a Verify Job, the Level may be one of the following:
Please note! If you run two Verify Catalog jobs on the same client at the same time, the results will certainly be incorrect. This is because Verify Catalog modifies the Catalog database while running in order to track new files.
Please note! If you run two Verify VolumeToCatalog jobs on the same client at the same time, the results will certainly be incorrect. This is because the Verify VolumeToCatalog modifies the Catalog database while running.
This command can be very useful if you have disk problems because it will compare the current state of your disk against the last successful backup, which may be several jobs.
Note, the current implementation (1.32c) does not identify files that have been deleted.
If you use the Restore command in the Console program, to start a restore job, the bootstrap file will be created automatically from the files you select to be restored.
For additional details of the bootstrap file, please see Restoring Files with the Bootstrap File chapter of this manual.
Using this feature, permits you to constantly have a bootstrap file that can recover the current state of your system. Normally, the file specified should be a mounted drive on another machine, so that if your hard disk is lost, you will immediately have a bootstrap record available. Alternatively, you should copy the bootstrap file to another machine after it is updated.
If the bootstrap-file-specification begins with a vertical bar (|), Bacula will use the specification as the name of a program to which it will pipe the bootstrap record. It could for example be a shell script that emails you the bootstrap record.
For more details on using this file, please see the chapter entitled The Bootstrap File of this manual.
If the directive is set to no, the Storage daemon will prefer finding an unused drive, otherwise, each job started will append to the same Volume (assuming the Pool is the same for all jobs). Setting Prefer Mounted Volumes to no can be useful for those sites particularly with multiple drive autochangers that prefer to maximumize backup throughput at the expense of using additional drives and Volumes. As an optimization, when using multiple drives, you will probably want to start each of your jobs one after another with approximately 5 second intervals. This will help ensure that each night, the same drive (Volume) is selected for the same job, otherwise, when you do a restore, you may find the files spread over many more Volumes than necessary.
The specified command is run as an external program prior or after the current Job. This directive is optional.
You can use following options :
| Options | Value | Default | Informations |
| Runs On Success | Yes/No | Yes | Run command if JobStatus is successful |
| Runs On Failure | Yes/No | No | Run command if JobStatus isn't successful |
| Runs On Client | Yes/No | Yes | Run command on client |
| Runs When | Before|After|Always | Never | When run commands |
| Abort Job On Error | Yes/No | Yes | Abort job if script return something different from 0 |
| Command | Path to your script |
Any output sent by the command to standard output will be included in the Bacula job report. The command string must be a valid program name or name of a shell script.
In addition, the command string is parsed then fed to the execvp() function, which means that the path will be searched to execute your specified command, but there is no shell interpretation, as a consequence, if you invoke complicated commands or want any shell features such as redirection or piping, you must call a shell script and do it inside that script.
Before submitting the specified command to the operating system, Bacula performs character substitution of the following characters:
%% = %
%c = Client's name
%d = Director's name
%e = Job Exit Status
%i = JobId
%j = Unique Job id
%l = Job Level
%n = Job name
%s = Since time
%t = Job type (Backup, ...)
%v = Volume name
The Job Exit Status code %e edits the following values:
Thus if you edit it on a command line, you will need to enclose it within some sort of quotes.
You can use these following shortcuts :
| Keyword | RunsOnSuccess | RunsOnFailure | AbortJobOnError | Runs On Client | RunsWhen |
| Run Before Job | Yes | No | Before | ||
| Run After Job | Yes | No | No | After | |
| Run After Failed Job | No | Yes | No | After | |
| Client Run Before Job | Yes | Yes | Before | ||
| Client Run After Job | Yes | No | Yes | After | |
| Client Run After Failed Job | No | Yes | Yes | After |
Example :
RunScript {
RunsWhen = Before
AbortJobOnError = No
Command = "/etc/init.d/apache stop"
}
RunScript {
RunsWhen = After
RunsOnFailure = yes
Command = "/etc/init.d/apache start"
}
Special Windows Considerations
In addition, for a Windows client on version 1.33 and above, please take careful note that you must ensure a correct path to your script. The script or program can be a .com, .exe or a .bat file. However, if you specify a path, you must also specify the full extension. Unix like commands will not work unless you have installed and properly configured Cygwin in addition to and separately from Bacula.
The command can be anything that cmd.exe or command.com will recognize as an executable file. Specifying the executable's extension is optional, unless there is an ambiguity. (i.e. ls.bat, ls.exe)
The System %Path% will be searched for the command. (under the environment variable dialog you have have both System Environment and User Environment, we believe that only the System environment will be available to bacula-fd, if it is running as a service.)
System environment variables can be referenced with %var% and used as either part of the command name or arguments.
ClientRunBeforeJob = "\"C:/Program Files/Software
Vendor/Executable\" /arg1 /arg2 \"foo bar\""
The special characters &()[]{}^=;!'+,`~ will need to be quoted if they are part of a filename or argument.
If someone is logged in, a blank "command" window running the commands will be present during the execution of the command.
Some Suggestions from Phil Stracchino for running on Win32 machines with the native Win32 File daemon:
ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat"
rather than DOS/Windows form:
ClientRunBeforeJob =
"c:\bacula\bin\systemstate.bat" INCORRECT
The following example of the use of the Client Run Before Job directive was
submitted by a user:
You could write a shell script to back up a DB2 database to a FIFO. The shell
script is:
#!/bin/sh # ===== backupdb.sh DIR=/u01/mercuryd mkfifo $DIR/dbpipe db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING & sleep 1
The following line in the Job resource in the bacula-dir.conf file:
Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t' '%l'\""
When the job is run, you will get messages from the output of the script stating that the backup has started. Even though the command being run is backgrounded with &, the job will block until the "db2 BACKUP DATABASE" command, thus the backup stalls.
To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to the following:
db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log 2>&1 < /dev/null &
It is important to redirect the input and outputs of a backgrounded command to /dev/null to prevent the script from blocking.
Run Before Job = "echo test"it's equivalent to :
RunScript {
Command = "echo test"
RunsOnClient = No
RunsWhen = Before
}
Lutz Kittler has pointed out that using the RunBeforJob directive can be a simple way to modify your schedules during a holiday. For example, suppose that you normally do Full backups on Fridays, but Thursday and Friday are holidays. To avoid having to change tapes between Thursday and Friday when no one is in the office, you can create a RunBeforeJob that returns a non-zero status on Thursday and zero on all other days. That way, the Thursday job will not run, and on Friday the tape you inserted on Wednesday before leaving will be used.
An example of the use of this directive is given in the Tips Chapter of this manual.
See the Run After Failed Job if you want to run a script after the job has terminated with any non-normal status.
RunScript {
Command = "echo test"
RunsWhen = After
RunsOnFailure = yes
RunsOnClient = no
RunsOnSuccess = yes # default, you can drop this line
}
An example of the use of this directive is given in the Tips Chapter of this manual.
This specification can be useful for portables, laptops, or other machines that are not always connected to the network or switched on.
The part after the equal sign must be enclosed in double quotes, and can contain any string or set of options (overrides) that you can specify when entering the Run command from the console. For example storage=DDS-4 .... In addition, there are two special keywords that permit you to clone the current job. They are level=%l and since=%s. The %l in the level keyword permits entering the actual level of the current job and the %s in the since keyword permits putting the same time for comparison as used on the current job. Note, in the case of the since keyword, the %s must be enclosed in double quotes, and thus they must be preceded by a backslash since they are already inside quotes. For example:
run = "Nightly-backup level=%s since=\"%s\" storage=DDS-4"
A cloned job will not start additional clones, so it is not possible to recurse.
The priority only affects waiting jobs that are queued to run, not jobs that are already running. If one or more jobs of priority 2 are already running, and a new job is scheduled with priority 1, the currently running priority 2 jobs must complete before the priority 1 job is run.
The default priority is 10.
If you want to run concurrent jobs you should keep these points in mind:
If you have several jobs of different priority, it may not best to start them at exactly the same time, because Bacula must examine them one at a time. If by Bacula starts a lower priority job first, then it will run before your high priority jobs. If you experience this problem, you may avoid it by starting any higher priority jobs a few seconds before lower priority ones. This insures that Bacula will examine the jobs in the correct order, and that your priority scheme will be respected.
It should be set to yes when writing to devices that require mount (for example DVD), so you are sure that the current part, containing this job's data, is written to the device, and that no data is left in the temporary file on the hard disk. However, on some media, like DVD+R and DVD-R, a lot of space (about 10Mb) is lost every time a part is written. So, if you run several jobs each after another, you could set this directive to no for all jobs, except the last one, to avoid wasting too much space, but to ensure that the data is written to the medium when all jobs are finished.
It is ignored with tape and FIFO devices.
The following is an example of a valid Job resource definition:
Job {
Name = "Minou"
Type = Backup
Level = Incremental # default
Client = Minou
FileSet="Minou Full Set"
Storage = DLTDrive
Pool = Default
Schedule = "MinouWeeklyCycle"
Messages = Standard
}
The JobDefs resource permits all the same directives that can appear in a Job resource. However, a JobDefs resource does not create a Job, rather it can be referenced within a Job to provide defaults for that Job. This permits you to concisely define several nearly identical Jobs, each one referencing a JobDefs resource which contains the defaults. Only the changes from the defaults need to be mentioned in each Job.
The Schedule resource provides a means of automatically scheduling a Job as well as the ability to override the default Level, Pool, Storage and Messages resources. If a Schedule resource is not referenced in a Job, the Job can only be run manually. In general, you specify an action to be taken and when.
The Job-overrides permit overriding the Level, the Storage, the Messages, and the Pool specifications provided in the Job resource. In addition, the FullPool, the IncrementalPool, and the DifferentialPool specifications permit overriding the Pool specification according to what backup Job Level is in effect.
By the use of overrides, you may customize a particular Job. For example, you may specify a Messages override for your Incremental backups that outputs messages to a log file, but for your weekly or monthly Full backups, you may send the output by email by using a different Messages override.
Job-overrides are specified as: keyword=value where the keyword is Level, Storage, Messages, Pool, FullPool, DifferentialPool, or IncrementalPool, and the value is as defined on the respective directive formats for the Job resource. You may specify multiple Job-overrides on one Run directive by separating them with one or more spaces or by separating them with a trailing comma. For example:
Date-time-specification determines when the Job is to be run. The specification is a repetition, and as a default Bacula is set to run a job at the beginning of the hour of every hour of every day of every week of every month of every year. This is not normally what you want, so you must specify or limit when you want the job to run. Any specification given is assumed to be repetitive in nature and will serve to override or limit the default repetition. This is done by specifying masks or times for the hour, day of the month, day of the week, week of the month, week of the year, and month when you want the job to run. By specifying one or more of the above, you can define a schedule to repeat at almost any frequency you want.
Basically, you must supply a month, day, hour, and minute the Job is to be run. Of these four items to be specified, day is special in that you may either specify a day of the month such as 1, 2, ... 31, or you may specify a day of the week such as Monday, Tuesday, ... Sunday. Finally, you may also specify a week qualifier to restrict the schedule to the first, second, third, fourth, or fifth week of the month.
For example, if you specify only a day of the week, such as Tuesday the Job will be run every hour of every Tuesday of every Month. That is the month and hour remain set to the defaults of every month and all hours.
Note, by default with no other specification, your job will run at the beginning of every hour. If you wish your job to run more than once in any given hour, you will need to specify multiple run specifications each with a different minute.
The date/time to run the Job can be specified in the following way in pseudo-BNF:
<void-keyword> = on
<at-keyword> = at
<week-keyword> = 1st | 2nd | 3rd | 4th | 5th | first |
second | third | forth | fifth
<wday-keyword> = sun | mon | tue | wed | thu | fri | sat |
sunday | monday | tuesday | wednesday |
thursday | friday | saturday
<week-of-year-keyword> = w00 | w01 | ... w52 | w53
<month-keyword> = jan | feb | mar | apr | may | jun | jul |
aug | sep | oct | nov | dec | january |
february | ... | december
<daily-keyword> = daily
<weekly-keyword> = weekly
<monthly-keyword> = monthly
<hourly-keyword> = hourly
<digit> = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0
<number> = <digit> | <digit><number>
<12hour> = 0 | 1 | 2 | ... 12
<hour> = 0 | 1 | 2 | ... 23
<minute> = 0 | 1 | 2 | ... 59
<day> = 1 | 2 | ... 31
<time> = <hour>:<minute> |
<12hour>:<minute>am |
<12hour>:<minute>pm
<time-spec> = <at-keyword> <time> |
<hourly-keyword>
<date-keyword> = <void-keyword> <weekly-keyword>
<day-range> = <day>-<day>
<month-range> = <month-keyword>-<month-keyword>
<wday-range> = <wday-keyword>-<wday-keyword>
<range> = <day-range> | <month-range> |
<wday-range>
<date> = <date-keyword> | <day> | <range>
<date-spec> = <date> | <date-spec>
<day-spec> = <day> | <wday-keyword> |
<day-range> | <wday-range> |
<daily-keyword>
<day-spec> = <day> | <wday-keyword> |
<day> | <wday-range> |
<week-keyword> <wday-keyword> |
<week-keyword> <wday-range>
<month-spec> = <month-keyword> | <month-range> |
<monthly-keyword>
<date-time-spec> = <month-spec> <day-spec> <time-spec>
Note, the Week of Year specification wnn follows the ISO standard definition of the week of the year, where Week 1 is the week in which the first Thursday of the year occurs, or alternatively, the week which contains the 4th of January. Weeks are numbered w01 to w53. w00 for Bacula is the week that precedes the first ISO week (i.e. has the first few days of the year if any occur before Thursday). w00 is not defined by the ISO specification. A week starts with Monday and ends with Sunday.
An example schedule resource that is named WeeklyCycle and runs a job with level full each Sunday at 1:05am and an incremental job Monday through Saturday at 1:05am is:
Schedule {
Name = "WeeklyCycle"
Run = Level=Full sun at 1:05
Run = Level=Incremental mon-sat at 1:05
}
An example of a possible monthly cycle is as follows:
Schedule {
Name = "MonthlyCycle"
Run = Level=Full Pool=Monthly 1st sun at 1:05
Run = Level=Differential 2nd-5th sun at 1:05
Run = Level=Incremental Pool=Daily mon-sat at 1:05
}
The first of every month:
Schedule {
Name = "First"
Run = Level=Full on 1 at 1:05
Run = Level=Incremental on 2-31 at 1:05
}
Every 10 minutes:
Schedule {
Name = "TenMinutes"
Run = Level=Full hourly at 0:05
Run = Level=Full hourly at 0:15
Run = Level=Full hourly at 0:25
Run = Level=Full hourly at 0:35
Run = Level=Full hourly at 0:45
Run = Level=Full hourly at 0:55
}
Internally Bacula keeps a schedule as a bit mask. There are six masks and a minute field to each schedule. The masks are hour, day of the month (mday), month, day of the week (wday), week of the month (wom), and week of the year (woy). The schedule is initialized to have the bits of each of these masks set, which means that at the beginning of every hour, the job will run. When you specify a month for the first time, the mask will be cleared and the bit corresponding to your selected month will be selected. If you specify a second month, the bit corresponding to it will also be added to the mask. Thus when Bacula checks the masks to see if the bits are set corresponding to the current time, your job will run only in the two months you have set. Likewise, if you set a time (hour), the hour mask will be cleared, and the hour you specify will be set in the bit mask and the minutes will be stored in the minute field.
For any schedule you have defined, you can see how these bits are set by doing a show schedules command in the Console program. Please note that the bit mask is zero based, and Sunday is the first day of the week (bit zero).
-
The FileSet resource defines what files are to be included or excluded in a backup job. A FileSet resource is required for each backup Job. It consists of a list of files or directories to be included, a list of files or directories to be excluded and the various backup options such as compression, encryption, and signatures that are to be applied to each file.
Any change to the list of the included files will cause Bacula to automatically create a new FileSet (defined by the name and an MD5 checksum of the Include/Exclude contents). Each time a new FileSet is created, Bacula will ensure that the next backup is always a Full save.
The Include resource must contain a list of directories and/or files to be processed in the backup job. Normally, all files found in all subdirectories of any directory in the Include File list will be backed up. Note, see below for the definition of <file-list>. The Include resource may also contain one or more Options resources that specify options such as compression to be applied to all or any subset of the files found when processing the file-list for backup. Please see below for more details concerning Options resources.
There can be any number of Include resources within the FileSet, each having its own list of directories or files to be backed up and the backup options defined by one or more Options resources. The file-list consists of one file or directory name per line. Directory names should be specified without a trailing slash with Unix path notation.
Windows users, please take note to specify directories (even c:/...) in
Unix path notation. If you use Windows conventions, you will most likely
not be able to restore your files due to the fact that the Windows
path separator was defined as an escape character long before Windows
existed, and Bacula adheres to that convention (i.e.
means the next character
appears as itself).
You should always specify a full path for every directory and file that you list in the FileSet. In addition, on Windows machines, you should always prefix the directory or filename with the drive specification in lower case (e.g. c:/xxx) using Unix directory name separators (forward slash).
Bacula's default for processing directories is to recursively descend in the directory saving all files and subdirectories. Bacula will not by default cross filesystems (or mount points in Unix parlance). This means that if you specify the root partition (e.g. /), Bacula will save only the root partition and not any of the other mounted filesystems. Similarly on Windows systems, you must explicitly specify each of the drives you want saved (e.g. c:/ and d:/ ...). In addition, at least for Windows systems, you will most likely want to enclose each specification within double quotes particularly if the directory (or file) name contains spaces. The df command on Unix systems will show you which mount points you must specify to save everything. See below for an example.
Take special care not to include a directory twice or Bacula will backup the same files two times wasting a lot of space on your archive device. Including a directory twice is very easy to do. For example:
Include {
File = /
File = /usr
Options { compression=GZIP }
}
on a Unix system where /usr is a subdirectory (rather than a mounted filesystem) will cause /usr to be backed up twice. In this case, on Bacula versions prior to 1.32f-5-09Mar04 due to a bug, you will not be able to restore hard linked files that were backed up twice.
If you have used Bacula prior to version 1.36.3, you will note three things in the new FileSet syntax:
The Options resource is optional, but when specified, it will contain a list of keyword=value options to be applied to the file-list. See below for the definition of file-list. Multiple Options resources may be specified one after another. As the files are found in the specified directories, the Options will applied to the filenames to determine if and how the file should be backed up. The wildcard and regular expression pattern matching parts of the Options resources are checked in the order they are specified in the FileSet until the first one that matches. Once one matches, the compression and other flags within the Options specification will apply to the pattern matched.
A key point is that in the absence of an Option or no other Option is matched, every file is accepted for backing up. This means that if you want to exclude something, you must explicitly specify an Option with an exclude = yes and some pattern matching.
Once Bacula determines that the Options resource matches the file under consideration, that file will be saved without looking at any other Options resources that may be present. This means that any wild cards must appear before an Options resource without wild cards.
If for some reason, Bacula checks all the Options resources to a file under consideration for backup, but there are no matches (generally because of wild cards that don't match), Bacula as a default will then backup the file. This is quite logical if you consider the case of no Options clause is specified, where you want everything to be backed up, and it is important to keep in mind when excluding as mentioned above.
However, one additional point is that in the case that no match was found, Bacula will use the options found in the last Options resource. As a consequence, if you want a particular set of "default" options, you should put them in an Options resource after any other Options.
It is a good idea to put all your wild-card and regex expressions inside double quotes to prevent conf file scanning problems.
This is perhaps a bit overwhelming, so there are a number of examples included below to illustrate how this works.
The directives within an Options resource may be one of the following:
Software compression is very important if you are writing your Volumes to a file, and it can also be helpful if you have a fast computer but a slow network, otherwise it is generally better to rely your tape drive's hardware compression. As noted above, it is not generally a good idea to do both software and hardware compression.
Specifying GZIP uses the default compression level six (i.e. GZIP is identical to GZIP6). If you want a different compression level (1 through 9), you can specify it by appending the level number with no intervening spaces to GZIP. Thus compression=GZIP1 would give minimum compression but the fastest algorithm, and compression=GZIP9 would give the highest level of compression, but requires more computation. According to the GZIP documentation, compression levels greater than 6 generally give very little extra compression and are rather CPU intensive.
A useful set of general options on the Level=Catalog or Level=DiskToCatalog verify is pins5 i.e. compare permission bits, inodes, number of links, size, and MD5 changes.
rufus-fd: Filesystem change prohibited. Will not descend into /misc rufus-fd: Filesystem change prohibited. Will not descend into /net rufus-fd: Filesystem change prohibited. Will not descend into /var/lib/nfs/rpc_pipefs rufus-fd: Filesystem change prohibited. Will not descend into /selinux rufus-fd: Filesystem change prohibited. Will not descend into /sys rufus-fd: Filesystem change prohibited. Will not descend into /dev rufus-fd: Filesystem change prohibited. Will not descend into /homeIf you wish to backup multiple filesystems, you can explicitly list each filesystem you want saved. Otherwise, if you set the onefs option to no, Bacula will backup all mounted file systems (i.e. traverse mount points) that are found within the FileSet. Thus if you have NFS or Samba file systems mounted on a directory listed in your FileSet, they will also be backed up. Normally, it is preferable to set onefs=yes and to explicitly name each filesystem you want backed up. Explicitly naming the filesystems you want backed up avoids the possibility of getting into a infinite loop recursing filesystems. Another possibility is to use onefs=no and to set fstype=ext2, .... See the example below for more details.
If you think that Bacula should be backing up a particular directory and it is not, and you have onefs=no set, before you complain, please do:
stat / stat <filesystem>
where you replace filesystem with the one in question. If the Device: number is different for / and for your filesystem, then they are on different filesystems. E.g.
stat / File: `/' Size: 4096 Blocks: 16 IO Block: 4096 directory Device: 302h/770d Inode: 2 Links: 26 Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root) Access: 2005-11-10 12:28:01.000000000 +0100 Modify: 2005-09-27 17:52:32.000000000 +0200 Change: 2005-09-27 17:52:32.000000000 +0200 stat /net File: `/home' Size: 4096 Blocks: 16 IO Block: 4096 directory Device: 308h/776d Inode: 2 Links: 7 Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root) Access: 2005-11-10 12:28:02.000000000 +0100 Modify: 2005-11-06 12:36:48.000000000 +0100 Change: 2005-11-06 12:36:48.000000000 +0100
Also be aware that even if you include /home in your list of files to backup, as you most likely should, you will get the informational message about Filesystem change prohibited when Bacula is processing the / directory.
Restrictions: Bacula reads files in 32K buffers. If the whole buffer is zero, it will be treated as a sparse block and not written to tape. However, if any part of the buffer is non-zero, the whole buffer will be written to tape, possibly including some disk sectors (generally 4098 bytes) that are all zero. As a consequence, Bacula's detection of sparse blocks is in 32K increments rather than the system block size. If anyone considers this to be a real problem, please send in a request for change with the reason.
If you are not familiar with sparse files, an example is say a file where you wrote 512 bytes at address zero, then 512 bytes at address 1 million. The operating system will allocate only two blocks, and the empty space or hole will have nothing allocated. However, when you read the sparse file and read the addresses where nothing was written, the OS will return all zeros as if the space were allocated, and if you backup such a file, a lot of space will be used to write zeros to the volume. Worse yet, when you restore the file, all the previously empty space will now be allocated using much more disk space. By turning on the sparse option, Bacula will specifically look for empty space in the file, and any empty space will not be written to the Volume, nor will it be restored. The price to pay for this is that Bacula must search each block it reads before writing it. On a slow system, this may be important. If you suspect you have sparse files, you should benchmark the difference or set sparse for only those files that are really sparse.
Unfortunately, when Bacula runs a RunBeforeJob, it waits until that script terminates, and if the script accesses the FIFO to write into the it, the Bacula job will block and everything will stall. However, Vladimir Stavrinov as supplied tip that allows this feature to work correctly. He simply adds the following to the beginning of the RunBeforeJob script:
exec > /dev/null
Note, if you use this feature, when Bacula resets the access time, the change time (st_ctime) will automatically be modified by the system, so on the next incremental job, the file will be backed up even if it has not changed. As a consequence, you will probably also want to use mtimeonly = yes as well as keepatime (thanks to Rudolf Cejka for this tip).
You may want to test your expressions prior to running your backup by using the bwild program. Please see the UtilitiesChapter chapter of this manual for more. You can also test your full FileSet definition by using the estimate command in the Console chapter of this manual. It is recommended to enclose the string in double quotes.
It is recommended to enclose the string in double quotes.
You may want to test your expressions prior to running your backup by using the bwild program. Please see the UtilitiesChapter chapter of this manual for more. You can also test your full FileSet definition by using the estimate command in the Console chapter of this manual. An example of excluding with the WildDir option on Win32 machines is presented below.
It is recommended to enclose the string in double quotes.
You may want to test your expressions prior to running your backup by using the bwild program. Please see the UtilitiesChapter chapter of this manual for more. You can also test your full FileSet definition by using the estimate command in the Console chapter of this manual. An example of excluding with the WildFile option on Win32 machines is presented below.
It is recommended to enclose the string in double quotes.
The regex libraries differ from one operating system to another, and in addition, regular expressions are complicated, so you may want to test your expressions prior to running your backup by using the bregex program. Please see the UtilitiesChapter chapter of this manual for more. You can also test your full FileSet definition by using the estimate command in the Console chapter of this manual.
It is recommended to enclose the string in double quotes.
The regex libraries differ from one operating system to another, and in addition, regular expressions are complicated, so you may want to test your expressions prior to running your backup by using the bregex program. Please see the UtilitiesChapter chapter of this manual for more.
It is recommended to enclose the string in double quotes.
The regex libraries differ from one operating system to another, and in addition, regular expressions are complicated, so you may want to test your expressions prior to running your backup by using the bregex program. Please see the UtilitiesChapter chapter of this manual for more.
ext2, jfs, ntfs, proc, reiserfs, xfs, usbdevfs, sysfs, smbfs, iso9660. For ext3 systems, use ext2.
You may have multiple Fstype directives, and thus permit matching of multiple filesystem types within a single Options resource. If the type specified on the fstype directive does not match the filesystem for a particular directive, that directory will not be backed up. This directive can be used to prevent backing up non-local filesystems. Normally, when you use this directive, you would also set onefs=no so that Bacula will traverse filesystems.
This option is not implemented in Win32 systems.
<file-list> is a list of directory and/or filename names specified with a File = directive. To include names containing spaces, enclose the name between double-quotes. Wild-cards are not interpreted in file-lists. They can only be specified in Options resources.
There are a number of special cases when specifying directories and files in a file-list. They are:
Include {
Options { compression=GZIP }
@/home/files/my-files
}
This allows you to have a job that, for example, includes all the local
partitions even if you change the partitioning by adding a disk. The
examples below show you how to do this. However, please note two
things:
1. if you want the local filesystems, you probably should be
using the new fstype directive, which was added in version 1.36.3
and set onefs=no.
2. the exact syntax of the command needed in the examples below is very system dependent. For example, on recent Linux systems, you may need to add the -P option, on FreeBSD systems, the options will be different as well.
In general, you will need to prefix your command or commands with a sh -c so that they are invoked by a shell. This will not be the case if you are invoking a script as in the second example below. Also, you must take care to escape (precede with a \) wild-cards, shell character, and to ensure that any spaces in your command are escaped as well. If you use a single quotes (') within a double quote ("), Bacula will treat everything between the single quotes as one field so it will not be necessary to escape the spaces. In general, getting all the quotes and escapes correct is a real pain as you can see by the next example. As a consequence, it is often easier to put everything in a file and simply use the file name within Bacula. In that case the sh -c will not be necessary providing the first line of the file is #!/bin/sh.
As an example:
Include {
Options { signature = SHA1 }
File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
| awk \"{print \\$6}\"'"
}
will produce a list of all the local partitions on a RedHat Linux system. Note, the above line was split, but should normally be written on one line. Quoting is a real problem because you must quote for Bacula which consists of preceding every \ and every " with a \, and you must also quote for the shell command. In the end, it is probably easier just to execute a small file with:
Include {
Options {
signature=MD5
}
File = "|my_partitions"
}
where my_partitions has:
#!/bin/sh
df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
| awk "{print \$6}"
If the vertical bar (|) in front of my_partitions is preceded by a backslash as in \|, the program will be executed on the Client's machine instead of on the Director's machine. Please note that if the filename is given within quotes, you will need to use two slashes. An example, provided by John Donagher, that backs up all the local UFS partitions on a remote system is:
FileSet {
Name = "All local partitions"
Include {
Options { signature=SHA1; onefs=yes; }
File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
}
}
The above requires two backslash characters after the double quote (one preserves the next one). If you are a Linux user, just change the ufs to ext3 (or your preferred filesystem type), and you will be in business.
If you know what filesystems you have mounted on your system, e.g. for RedHat Linux normally only ext2 and ext3, you can backup all local fileystems using something like:
Include {
Options { signature = SHA1; onfs=no; fstype=ext2 }
File = /
}
Include {
Options { signature = SHA1 }
File = "</home/files/local-filelist"
}
If you precede the less-than sign (<) with a backslash as in \<, the file-list will be read on the Client machine instead of on the Director's machine. Please note that if the filename is given within quotes, you will need to use two slashes.
Include {
Options { signature = SHA1 }
File = "\\</home/xxx/filelist-on-client"
}
Include {
Options { signature=MD5; sparse=yes }
File = /dev/hd6
}
will backup the data in device /dev/hd6.
Ludovic Strappazon has pointed out that this feature can be used to backup a full Microsoft Windows disk. Simply boot into the system using a Linux Rescue disk, then load a statically linked Bacula as described in the Disaster Recovery Using Bacula chapter of this manual. Then save the whole disk partition. In the case of a disaster, you can then restore the desired partition by again booting with the rescue disk and doing a restore of the partition.
Include {
Options {
signature=SHA1
readfifo=yes
}
File = /home/abc/fifo
}
if /home/abc/fifo is a fifo device, Bacula will open the fifo, read it, and store all data thus obtained on the Volume. Please note, you must have a process on the system that is writing into the fifo, or Bacula will hang, and after one minute of waiting, Bacula will give up and go on to the next file. The data read can be anything since Bacula treats it as a stream.
This feature can be an excellent way to do a "hot" backup of a very large database. You can use the RunBeforeJob to create the fifo and to start a program that dynamically reads your database and writes it to the fifo. Bacula will then write it to the Volume. Be sure to read the readfifo section that gives a tip to ensure that the RunBeforeJob does not block Bacula.
During the restore operation, the inverse is true, after Bacula creates the fifo if there was any data stored with it (no need to explicitly list it or add any options), that data will be written back to the fifo. As a consequence, if any such FIFOs exist in the fileset to be restored, you must ensure that there is a reader program or Bacula will block, and after one minute, Bacula will time out the write to the fifo and move on to the next file.
The following is an example of a valid FileSet resource definition. Note, the first Include pulls in the contents of the file /etc/backup.list when Bacula is started (i.e. the @), and that file must have each filename to be backed up preceded by a File = and on a separate line.
FileSet {
Name = "Full Set"
Include {
Options {
Compression=GZIP
signature=SHA1
Sparse = yes
}
@/etc/backup.list
}
Include {
Options {
wildfile = "*.o"
wildfile = "*.exe"
Exclude = yes
}
File = /root/myfile
File = /usr/lib/another_file
}
}
In the above example, all the files contained in /etc/backup.list will be compressed with GZIP compression, an SHA1 signature will be computed on the file's contents (its data), and sparse file handling will apply.
The two directories /root/myfile and /usr/lib/another_file will also be saved without any options, but all files in those directories with the extensions .o and .exe will be excluded.
Let's say that you now want to exclude the directory /tmp. The simplest way to do so is to add an exclude directive that lists /tmp. The example above would then become:
FileSet {
Name = "Full Set"
Include {
Options {
Compression=GZIP
signature=SHA1
Sparse = yes
}
@/etc/backup.list
}
Include {
Options {
wildfile = "*.o"
wildfile = "*.exe"
Exclude = yes
}
File = /root/myfile
File = /usr/lib/another_file
}
Exclude {
File = /tmp
}
}
You can add wild-cards to the File directives listed in the Exclude directory, but you need to take care because if you exclude a directory, it and all files and directories below it will also be excluded.
Now lets take a slight variation on the above and suppose you want to save all your whole filesystem except /tmp. The problem that comes up is that Bacula will not normally cross from one filesystem to another. Doing a df command, you get the following output:
[kern@rufus k]$ df Filesystem 1k-blocks Used Available Use% Mounted on /dev/hda5 5044156 439232 4348692 10% / /dev/hda1 62193 4935 54047 9% /boot /dev/hda9 20161172 5524660 13612372 29% /home /dev/hda2 62217 6843 52161 12% /rescue /dev/hda8 5044156 42548 4745376 1% /tmp /dev/hda6 5044156 2613132 2174792 55% /usr none 127708 0 127708 0% /dev/shm //minimatou/c$ 14099200 9895424 4203776 71% /mnt/mmatou lmatou:/ 1554264 215884 1258056 15% /mnt/matou lmatou:/home 2478140 1589952 760072 68% /mnt/matou/home lmatou:/usr 1981000 1199960 678628 64% /mnt/matou/usr lpmatou:/ 995116 484112 459596 52% /mnt/pmatou lpmatou:/home 19222656 2787880 15458228 16% /mnt/pmatou/home lpmatou:/usr 2478140 2038764 311260 87% /mnt/pmatou/usr deuter:/ 4806936 97684 4465064 3% /mnt/deuter deuter:/home 4806904 280100 4282620 7% /mnt/deuter/home deuter:/files 44133352 27652876 14238608 67% /mnt/deuter/files
And we see that there are a number of separate filesystems (/ /boot /home /rescue /tmp and /usr not to mention mounted systems). If you specify only / in your Include list, Bacula will only save the Filesystem /dev/hda5. To save all filesystems except /tmp with out including any of the Samba or NFS mounted systems, and explicitly excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to be saved and restored, you can use the following:
FileSet {
Name = Include_example
Include {
Options {
wilddir = /proc
wilddir = /tmp
wildfile = "/.journal"
wildfile = "/.autofsck"
exclude = yes
}
File = /
File = /boot
File = /home
File = /rescue
File = /usr
}
}
Since /tmp is on its own filesystem and it was not explicitly named in the Include list, it is not really needed in the exclude list. It is better to list it in the Exclude list for clarity, and in case the disks are changed so that it is no longer in its own partition.
Now, lets assume you only want to backup .Z and .gz files and nothing else. This is a bit trickier because Bacula by default will select everything to backup, so we must exclude everything but .Z and .gz files. If we take the first example above and make the obvious modifications to it, we might come up with a FileSet that looks like this:
FileSet {
Name = "Full Set"
Include { !!!!!!!!!!!!
Options { This
wildfile = "*.Z" example
wildfile = "*.gz" doesn't
work
} !!!!!!!!!!!!
File = /myfile
}
}
The *.Z and *.gz files will indeed be backed up, but all other files that are not matched by the Options directives will automatically be backed up too (i.e. that is the default rule).
To accomplish what we want, we must explicitly exclude all other files. We do this with the following:
FileSet {
Name = "Full Set"
Include {
Options {
wildfile = "*.Z"
wildfile = "*.gz"
}
Options {