\chapter{Configuring the Director} \label{blb:DirectorChapter} \index[general]{Director!Configuring the} \index[general]{Configuring the Director} 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 \bilink{Configuration}{blb:ConfigureChapter} chapter of this manual. \section{Director Resource Types} \index[general]{Types!Director Resource} \index[general]{Director Resource Types} Director resource types may be the following: Job, JobDefs, Client, Storage/Autochanger, Catalog, Schedule, FileSet, Pool, Director, Console, Counter, and Messages. We present them here in the most logical order for defining them. Note, everything revolves around a job and is tied to a job in one way or another. \begin{bitemize} \item \bilink{Director}{blb:DirectorResource} -- to define the Director's name and its access password used for authenticating the Console program. Only a single Director resource definition may appear in the Director's configuration file. If you have either \btool{/dev/random} or \btool{bc} on your machine, \bacula{} will generate a random password during the configuration process, otherwise it will be left blank. \item \bilink{Job}{blb:JobResource} -- to define the backup/restore Jobs and to tie together the Client, FileSet and Schedule resources to be used for each Job. Normally, you will have Jobs of different names corresponding to each client (i.\,e., one Job per client, but a different one with a different name for each client). \item \bilink{JobDefs}{blb:JobDefsResource} -- optional resource for providing defaults for Job resources. \item \bilink{Schedule}{blb:ScheduleResource} -- to define when a Job is to be automatically run by \bacula{}'s internal scheduler. You may have any number of Schedules, but each job will reference only one. \item \bilink{FileSet}{blb:FileSetResource} -- to define the set of files to be backed up with each job. You may have any number of FileSets but each Job will reference only one. \item \bilink{Client}{blb:ClientResource2} -- to define what Client is to be backed up. You will generally have multiple Client definitions. Each Job will reference only a single client. \item \bilink{Storage}{blb:StorageResource} (or Autochanger) -- to define on what physical device the Volumes should be mounted. You may have one or more Storage definitions. \item \bilink{Pool}{blb:PoolResource} -- to define the pool of Volumes that can be used for a particular Job.% Most people use a %single default Pool. However, if you have a large number % -- I don't think this is true... If there is a large number of clients or volumes, you may want to have multiple Pools. Pools allow you to restrict a Job (or a Client) to use only a particular set of Volumes. \item \bilink{Catalog}{blb:CatalogResource} -- to define in what database to keep the list of files and the Volume names where they are backed up. Most people only use a single catalog. However, if you want to scale the Director to many clients, multiple catalogs can be helpful. Multiple catalogs require a bit more management because in general you must know what catalog contains what data. Currently, all Pools are defined in each catalog. This restriction will be removed in a later release. % Is the statement above actuall / still true? \item \bilink{Console}{blb:ConsoleResource1} -- to define how the administrator or user can interact with the Director. \item \bilink{Counter}{blb:CounterResource} -- to define a counter variable that can be accessed by variable expansion used for creating Volume labels. \item \bilink{Messages}{blb:MessagesChapter} -- to define where error and information messages are to be sent or logged. You may define multiple different message resources and hence direct particular classes of messages to different users or locations (files, \ldots{}). \end{bitemize} \bwebdoc{blb:DirectorResource} \section{The Director Resource} \index[general]{Director Resource} \index[general]{Resource!Director} 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 a future design may contain multiple Directors to maintain index and media database redundancy. \begin{bdescription} \item [Director] \index[dir]{Director} Start of the Director resource. One and only one director resource must be supplied. \bwebdoc{Director:Director:Name} \item [Name = \bbracket{name}] \index[dir]{Name} \index[dir]{Directive!Name} The director name used by the system administrator. This directive is required. \bwebdoc{Director:Director:Description} \item [Description = \bbracket{text}] \index[dir]{Description} \index[dir]{Directive!Description} The text field contains a description of the Director that will be displayed in the graphical user interface. This directive is optional. \bwebdoc{Director:Director:Password} \item [Password = \bbracket{UA-password}] \index[dir]{Password} \index[dir]{Directive!Password} Specifies the password that must be supplied for the default \bacula{} Console to be authorized. The same password must appear in the \bresourcename{Director} resource of the Console configuration file. For added security, the password is never passed across the network but instead a challenge response hash code created from the password. This directive is required. If you have either \btool{/dev/random} or \btool{bc} on your machine, \bacula{} will generate a random password during the configuration process, otherwise it will be left blank and you must manually supply it. The password is plain text. It is not generated through any special process but as noted above, it is better to use random text for security reasons. \bwebdoc{Director:Director:Messages} \item [Messages = \bbracket{Messages-resource-name}] \index[dir]{Directive!Messages} The messages resource specifies where to deliver Director messages that are not associated with a specific Job. Most messages are specific to a job and will be directed to the Messages resource specified by the job. However, there are a few messages that can occur when no job is running. This directive is required. \bwebdoc{Director:Director:WorkingDirectory} \item [Working Directory = \bbracket{Directory}] \index[dir]{Working Directory} \index[dir]{Directive!Working Directory} This directive is mandatory and specifies a directory in which the Director may put its status files. This directory should be used only by \bacula{} but may be shared by other \bacula{} daemons. However, please note, if this directory is shared with other \bacula{} daemons (the File daemon and Storage daemon), you must ensure that the \bdirectivename{Name} given to each daemon is unique so that the temporary filenames used do not collide. By default the \bacula{} configure process creates unique daemon names by postfixing them with \texttt{-dir}, \texttt{-fd}, and \texttt{-sd}. Standard shell expansion of the \bdirectivename{Working Directory} is done when the configuration file is read so that values such as \textbf{\$HOME} will be properly expanded. This directive is required. The working directory specified must already exist and be readable and writable by the \bacula{} daemon referencing it. If you have specified a Director user and/or a Director group on your \btool{./configure} line with \bkeyword{{-}{-}with-dir-user} and/or \bkeyword{{-}{-}with-dir-group} the Working Directory owner and group will be set to those values. \bwebdoc{Director:Director:PidDirectory} \item [Pid Directory = \bbracket{Directory}] \index[dir]{Pid Directory} \index[dir]{Directive!Pid Directory} This directive is mandatory and specifies a directory in which the Director may put its process Id file. The process Id file is used to shutdown \bacula{} and to prevent multiple copies of \bacula{} from running simultaneously. Standard shell expansion of the \bdirectivename{Pid Directory} is done when the configuration file is read so that values such as \textbf{\$HOME} will be properly expanded. The PID directory specified must already exist and be readable and writable by the \bacula{} daemon referencing it Typically on Linux systems, you will set this to: \bdirectoryname{/var/run}. If you are not installing \bacula{} in the system directories, you can use the \bresourcename{Working Directory} as defined above. This directive is required. \bwebdoc{Director:Director:ScriptsDirectory} \item [Scripts Directory = \bbracket{Directory}] \index[dir]{Scripts Directory} \index[dir]{Directive!Scripts Directory} This directive is optional and, if defined, specifies a directory in which the Director and the Storage daemon will look for many of the scripts that it needs to use during particular operations such as starting/stopping, the \btool{mtx-changer} script, tape alerts, as well as catalog updates. This directory may be shared by other \bacula{} daemons. Standard shell expansion of the directory is done when the configuration file is read so that values such as \textbf{\$HOME} will be properly expanded. \bwebdoc{Director:Director:QueryFile} \item [QueryFile = \bbracket{Path}] \index[dir]{QueryFile} \index[dir]{Directive!QueryFile} This directive is mandatory and specifies a directory and file in which the Director can find the canned \acs{SQL} statements for the \bcommandname{query} command of the Console. Standard shell expansion of the \bbracket{Path} is done when the configuration file is read so that values such as \textbf{\$HOME} will be properly expanded. This directive is required. \bwebdoc{Director:Director:HeartbeatInterval} \item [Heartbeat Interval = \bbracket{time-interval}] \index[dir]{Heartbeat Interval} \index[dir]{Directive!Heartbeat} This directive is optional and if specified will cause the Director to set a keepalive interval (heartbeat) in seconds on each of the sockets it opens for the Client resource. This value will override any specified at the Director level. It is implemented only on systems (Linux, \ldots{}) that provide the \btool{setsockopt} \texttt{TCP\_KEEPIDLE} function. The default value is \bdefaultvalue{300s}. \label{blb:DirMaxConJobs} \bwebdoc{Director:Director:MaximumConcurrentJobs} \item [Maximum Concurrent Jobs = \bbracket{number}] \index[dir]{Maximum Concurrent Jobs} \index[dir]{Directive!Maximum Concurrent Jobs} \index[general]{Simultaneous Jobs} \index[general]{Concurrent Jobs} where \bbracket{number} is the maximum number of total Director Jobs that should run concurrently. The default is set to \bdefaultvalue{20}, but you may set it to a larger number. Every valid connection to any daemon (Director, File daemon, or Storage daemon) results in a Job. This includes connections from \bconsole{}. Thus the number of concurrent Jobs must, in general, be greater than the maximum number of Jobs that you wish to actually run. In general, increasing the number of Concurrent Jobs increases the total throughtput of \bacula{}, because the simultaneous Jobs can all feed data to the Storage daemon and to the Catalog at the same time. However, keep in mind, that the Volume format becomes more complicated with multiple simultaneous jobs, consequently, restores may take longer if \bacula{} must sort through interleaved volume blocks from multiple simultaneous jobs. Though not normally necessary, this can be avoided by having each simultaneous job write to a different volume or by using data spooling, which will first spool the data to disk simultaneously, then write one spool file at a time to the volume thus avoiding excessive interleaving of the different job blocks. \bwebdoc{Director:Director:FdConnectTimeout} \item [FD Connect Timeout = \bbracket{time}] \index[dir]{FD Connect Timeout} \index[dir]{Directive!FD Connect Timeout} where \bbracket{time} is the time that the Director should continue attempting to contact the File daemon to start a job, and after which the Director will cancel the job. The default is \bdefaultvalue{3 minutes}. \bwebdoc{Director:Director:SdConnectTimeout} \item [SD Connect Timeout = \bbracket{time}] \index[dir]{SD Connect Timeout} \index[dir]{Directive!SD Connect Timeout} where \bbracket{time} is the time that the Director should continue attempting to contact the Storage daemon to start a job, and after which the Director will cancel the job. The default is \bdefaultvalue{30 minutes}. \bwebdoc{Director:Director:DirAddresses} \item [DirAddresses = \bbracket{IP-address-specification}] \index[dir]{DirAddresses} \index[dir]{Address} \index[general]{Address} \index[dir]{Directive!DirAddresses} Specify the ports and addresses on which the Director daemon will listen for \bacula{} Console connections. Probably the simplest way to explain this is to show an example: % TODO: IPv6 example needs updating. Also, we should use example.net and % corresponding IP addresses... (ARL) \begin{bVerbatim} 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 } } \end{bVerbatim} 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 \bfilename{/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. \bwebdoc{Director:Director:DirPort} \item [DirPort = \bbracket{port-number}] \index[dir]{DirPort} \index[dir]{Directive!DirPort} Specify the port (a positive integer) on which the Director daemon will listen for \bacula{} Console connections. This same port number must be specified in the Director resource of the Console configuration file. The default is \bdefaultvalue{9101}, so normally this directive need not be specified. This directive should not be used if you specify the DirAddresses (plural) directive. \bwebdoc{Director:Director:DirAddress} \item [DirAddress = \bbracket{IP-Address}] \index[dir]{DirAddress} \index[dir]{Directive!DirAddress} This directive is optional, but if it is specified, it will cause the Director server (for the Console program) to bind to the specified \bbracket{IP-Address}, which is either a domain name or an \acs{IP} address specified as a dotted quadruple in string or quoted string format. If this directive is not specified, the Director will bind to any available address (the default). Note, unlike the DirAddresses specification noted above, this directive only permits a single address to be specified. This directive should not be used if you specify a DirAddresses (plural) directive. \bwebdoc{Director:Director:DirSourceAddress} \item [DirSourceAddress = \bbracket{IP-Address}] \index[fd]{DirSourceAddress} \index[fd]{Directive!DirSourceAddress} This record is optional, and if it is specified, it will cause the Director server (when initiating connections to a storage or file daemon) to source its connections from the specified address. Only a single \acs{IP} address may be specified. If this record is not specified, the Director server will source its outgoing connections according to the system routing table (the default). \bwebdoc{Director:Director:EventsRetention} \item[Events Retention = \bbracket{time}] \index[dir]{EventsRetention} \index[dir]{Directive!EventsRetention} The \bdirectivename{Events Retention} directive defines the length of time that \bacula{} will keep events records in the Catalog database. When this time period expires, and if the user runs the \bcommandname{prune events} command, \bacula{} will prune (remove) Events records that are older than the specified period. See the \bilink{Configuration chapter}{blb:Time} of this manual for additional details of time specifications. The default is \bdefaultvalue{1 month}. \phantomsection \bwebdoc{Director:Director:StatisticsRetention} \item[Statistics Retention = \bbracket{time}] \index[dir]{StatisticsRetention} \label{blb:PruneStatistics} \index[dir]{Directive!StatisticsRetention} The \bdirectivename{Statistics Retention} directive defines the length of time that \bacula{} will keep statistics job records in the Catalog database after the Job End time. (In \btable{JobHistory} table) When this time period expires, and if the user runs the \bcommandname{prune stats} command, \bacula{} will prune (remove) Job records that are older than the specified period. Theses statistics records aren't used for restore purpose, but mainly for capacity planning, billings, etc. See \bilink{Statistics chapter}{blb:UseBaculaCatalogToExtractInformationChapter} for additional information. See the \bilink{Configuration chapter}{blb:Time} of this manual for additional details of time specifications. The default is \bdefaultvalue{5 years}. \bwebdoc{Director:Director:AutoPrune} \item[AutoPrune = \byesorno{}] Normally, pruning of Files from the Catalog is specified on a Client by Client basis in the \bresourcename{Client} resource with the \bdirectivename{AutoPrune} directive. It is also possible to overwrite the Client settings in the \bresourcename{Pool} resource used by jobs, with the \bdirectivename{AutoPrune}, \bdirectivename{PruneFiles} and \bdirectivename{PruneJobs} directives. \smallskip If this directive is specified (not normally) and the value is \bvalue{no}, it will override the value specified in all the \bresourcename{Client} and the \bresourcename{Pool} resources. The default is \bdefaultvalue{yes}. \smallskip If you set \bvalueddirective{AutoPrune}{no}, pruning will not be done automatically, and your Catalog will grow in size each time you run a Job. Pruning affects only information in the catalog and not data stored in the backup archives (on Volumes). The \bcommandname{prune} \bconsolename{} command can be used to prune catalog records respecting the Client and/or the Pool \bdirectivename{FileRetention}, \bdirectivename{JobRetention} and \bdirectivename{VolumeRetention} directives. \bwebdoc{Director:Director:VerId} \item[VerId = \bbracket{string}] \index[dir]{Directive!VerId} where \bbracket{string} is an identifier which can be used for support purpose. This string is displayed using the \bcommandname{version} command. \bwebdoc{Director:Director:MaximumConsoleConnections} \item[MaximumConsoleConnections = \bbracket{number}] \index[dir]{MaximumConsoleConnections} \index[dir]{Directive!MaximumConsoleConnections} \index[dir]{Console} where \bbracket{number} is the maximum number of Console Connections that could run concurrently. The default is set to \bdefaultvalue{20}, but you may set it to a larger number. \bwebdoc{Director:Director:MaximumReloadRequests} \item[MaximumReloadRequests = \bbracket{number}] \index[dir]{MaximumReloadRequests} \index[dir]{Directive!MaximumReloadRequests} \index[dir]{Console} Where \bbracket{number} is the maximum number of \bcommandname{reload} command that can be queued while jobs are running. The default is set to \bdefaultvalue{32} and is usually sufficient. \bwebdoc{Director:Director:CommCompression} \item[CommCompression = \byesorno{}] \index[dir]{CommCompression} \index[dir]{Directive!CommCompression} \index[dir]{Compression} If the two \bacula{} components (DIR, FD, SD, bconsole) have the comm line compression enabled, the line compression will be enabled. The default value is yes. In many cases, the volume of data transmitted across the communications line can be reduced by a factor of three when this directive is \bdefaultvalue{enabled}. In the case that the compression is not effective, \bacula{} turns it off on a record by record basis. \smallskip If you are backing up data that is already compressed the comm line compression will not be effective, and you are likely to end up with an average compression ratio that is very small. In this case, \bacula{} reports \bvalue{None} in the Job report. % Generated by the Makefile with the extract.pl tool from the tls chapter \input{DirectorDirectorTls} \bwebdoc{Director:Director:End} % \bwebdoc{Director:SharedStorage} %\item[SharedStorage = \byesorno{}] % \index[dir]{SharedStorage} % \index[dir]{Directive!SharedStorage} % % The \texttt{Shared Storage} directive is a Bacula Enterprise feature that % allows you to share volumes between different Storage resources. This % directive should be used \textbf{only} if all \texttt{Media Type} are % correctly set across all Devices. % % The \texttt{Shared Storage} directive should be used when using the SAN % Shared Storage plugin or when accessing from the Director Storage resources % directly to Devices of an Autochanger. % % When sharing volumes between different Storage resources, you will % need also to use the \texttt{reset-storageid} script before using the % \texttt{update slots} command. This script can be scheduled once a day in % an Admin job. % %\begin{bVerbatim} % $ /opt/bacula/scripts/reset-storageid MediaType StorageName % $ bconsole % * update slots storage=StorageName drive=0 %\end{bVerbatim} % % Please contact Bacula Systems support to get help on this advanced % configuration. \end{bdescription} The following is an example of a valid Director resource definition: \begin{bVerbatim} Director { Name = HeadMan WorkingDirectory = "$HOME/bacula/bin/working" Password = UA_password PidDirectory = "$HOME/bacula/bin/working" QueryFile = "$HOME/bacula/bin/query.sql" Messages = Standard } \end{bVerbatim} \bwebdoc{blb:JobResource} %$ \section{The Job Resource} \index[general]{Resource!Job} \index[general]{Job Resource} The Job resource defines a Job (Backup, Restore, \ldots{}) 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 (\bjobtype{Backup}, \bjobtype{Restore}, \ldots{}) 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. Note, you define only a single Job to do the Full, Differential, and Incremental backups since the different backup levels are tied together by a unique Job name. Normally, you will have only one Job per Client, but if a client has a really huge number of files (more than several million), you might want to split it into to Jobs each with a different FileSet covering only part of the total files. Multiple Storage daemons are not currently supported for Jobs, so if you do want to use multiple storage daemons, you will need to create a different Job and ensure that for each Job that the combination of Client and FileSet are unique. The Client and FileSet are what \bacula{} uses to restore a client, so if there are multiple Jobs with the same Client and FileSet or multiple Storage daemons that are used, the restore will not work. This problem can be resolved by defining multiple FileSet definitions (the names must be different, but the contents of the FileSets may be the same). \begin{bdescription} \item [Job] \index[dir]{Job} \index[dir]{Directive!Job} Start of the Job resource. At least one Job resource is required. \bwebdoc{Director:Job:Name} \item [Name = \bbracket{name}] \index[dir]{Name} \index[dir]{Directive!Name} The Job name. This name can be specified on the \bcommandname{run} command in the console program to start a job. If the name contains spaces, it must be specified between quotes. It is generally a good idea to give your job the same name as the Client that it will backup. This permits easy identification of jobs. 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. \bwebdoc{Director:Job:Enabled} \item [Enabled = \byesorno{}] \index[dir]{Enable} \index[dir]{Directive!Enable} This directive allows you to enable or disable a \bresourcename{Job} resource. When the resource of the Job is disabled, the Job will no longer be scheduled and it will not be available in the list of Jobs to be run. To be able to use the Job you must \bcommandname{enable} it. \bwebdoc{Director:Job:Tag} \item [Tag = \bbracket{string, string2, string3}] \index[dir]{Tag} \index[dir]{Directive!Tag} The \bdirectivename{Tag} directive specifies a list of tags to create when creating a new Job record. This directive is optional. \bwebdoc{Director:Job:Type} \item [Type = \bbracket{job-type}] \index[dir]{Type} \index[dir]{Directive!Type} The \bdirectivename{Type} directive specifies the Job type, which may be one of the following: \bkeyword{Backup}, \bkeyword{Restore}, \bkeyword{Verify}, or \bkeyword{Admin}. This directive is required. Within a particular Job Type, there are also Levels as discussed in the next item. \begin{bdescription} \item [Backup] \index[dir]{Backup} Run a backup Job. Normally you will have at least one Backup job for each client you want to save. Normally, unless you turn off cataloging, most all the important statistics and data concerning files backed up will be placed in the catalog. \item [Restore] \index[dir]{Restore} Run a restore Job. Normally, you will specify only one Restore job which acts as a sort of prototype that you will modify using the console program in order to perform restores. Although certain basic information from a Restore job is saved in the catalog, it is very minimal compared to the information stored for a Backup job -- for example, no File database entries are generated since no Files are saved. \bjobtype{Restore} jobs cannot be automatically started by the scheduler as is the case for Backup, Verify and Admin jobs. To restore files, you must use the \bcommandname{restore} command in the console. \item [Verify] \index[dir]{Verify} Run a \bjobtype{Verify} Job. In general, \bjobtype{Verify} jobs permit you to compare the contents of the catalog to the file system, or to what was backed up. In addition, to verifying that a tape that was written can be read, you can also use \bjobtype{Verify} as a sort of tripwire intrusion detection. \item [Admin] \index[dir]{Admin} Run an \bjobtype{Admin} Job. Only Director's runscripts will be executed. The Client is not involved in an Admin job, so features such as \bdirectivename{Client Run Before Job} are not available. Although an Admin job is recorded in the catalog, very little data is saved. An Admin job can be used to periodically run catalog pruning, if you do not want to do it at the end of each Backup Job. \item [Migration] \index[dir]{Migration} Run a \bjobtype{Migration} Job (similar to a backup job) that reads data that was previously backed up to a Volume and writes it to another Volume. (See \vref{blb:MigrationChapter}) \item [Copy] \index[dir]{Copy} Run a \bjobtype{Copy} Job that essentially creates two identical copies of the same backup. The \bjobtype{Copy} process is essentially identical to the Migration feature with the exception that the Job that is copied is left unchanged. (See \vref{blb:MigrationChapter}) \end{bdescription} \label{blb:Level} \bwebdoc{Director:Job:Level} \item [Level = \bbracket{job-level}] \index[dir]{Level} \index[dir]{Directive!Level} The Level directive specifies the default Job level to be run. Each different Job Type (Backup, Restore, \ldots{}) has a different set of Levels that can be specified. The Level is normally overridden by a different value that is specified in the \bresourcename{Schedule} resource. This directive is not required, but must be specified either by a \bdirectivename{Level} directive or as an override specified in the \bresourcename{Schedule} resource. For a \bjobtype{Backup} Job, the Level may be one of the following: \begin{bdescription} \item [Full] \index[dir]{Full} When the \bdirectivename{Level} is set to \bvalue{Full} all files in the FileSet whether or not they have changed will be backed up. \item [Incremental] \index[dir]{Incremental} When the Level is set to Incremental all files specified in the FileSet that have changed since the last successful backup of the the same Job using the same FileSet and Client, will be backed up. If the Director cannot find a previous valid Full backup then the job will be upgraded into a Full backup. When the Director looks for a valid backup record in the catalog database, it looks for a previous Job with: \begin{bitemize} \item The same Job name. \item The same Client name. \item The same FileSet (any change to the definition of the FileSet such as adding or deleting a file in the Include or Exclude sections constitutes a different FileSet. \item The Job was a Full, Differential, or Incremental backup. \item The Job terminated normally (i.e. did not fail or was not canceled). \item The Job started no longer ago than \bdirectivename{Max Full Interval}. \end{bitemize} 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'' (\texttt{st\_mtime}) and the time its attributes were last ``changed''(\texttt{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 \texttt{st\_ctime} while doing the scan. For example, if the virus scanning program attempts to reset the access time (\texttt{st\_atime}), which \bacula{} does not use, it will cause \texttt{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 (\texttt{st\_atime}) and hence changing \texttt{st\_ctime} by using the {\bf\verb:--: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. In addition, if you move a directory rather than copy it, the files in it do not have their modification time (\texttt{st\_mtime}) or their attribute change time (\texttt{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. However, to manage deleted files or directories changes in the catalog during an Incremental backup you can use \bhighlight{accurate} mode. This is quite memory consuming process. See \bilink{Accurate mode}{accuratemode} for more details. \item [Differential] \index[dir]{Differential} When the Level is set to Differential all files specified in the FileSet that have changed since the last successful Full backup of the same Job will be backed up. If the Director cannot find a valid previous Full backup for the same Job, FileSet, and Client, backup, then the Differential job will be upgraded into a Full backup. When the Director looks for a valid Full backup record in the catalog database, it looks for a previous Job with: \begin{bitemize} \item The same Job name. \item The same Client name. \item The same FileSet (any change to the definition of the FileSet such as adding or deleting a file in the Include or Exclude sections constitutes a different FileSet. \item The Job was a FULL backup. \item The Job terminated normally (i.e. did not fail or was not canceled). \item The Job started no longer ago than \bdirectivename{Max Full Interval}. \end{bitemize} 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'' (\texttt{st\_mtime}) and the time its attributes were last ``changed'' (\texttt{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 \textbf{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 (\texttt{st\_mtime}) or their attribute change time (\texttt{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 \btool{touch} program to update the timestamps. %% TODO: merge this with incremental However, to manage deleted files or directories changes in the catalog during an Differential backup you can use \bhighlight{accurate} mode. This is quite memory consuming process. See \bilink{Accurate mode}{accuratemode} for more details. 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: \begin{benumerate} \item It gives some redundancy since the old backups could be used if the merged backup cannot be read. \item 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. \end{benumerate} \item [VirtualFull] \index[dir]{VirtualFull} When the backup Level is set to \bvalue{VirtualFull}, \bacula{} will consolidate the previous Full backup plus the most recent Differential backup and any subsequent Incremental backups into a new Full backup. This new Full backup will then be considered as the most recent Full for any future Incremental or Differential backups. The VirtualFull backup is accomplished without contacting the client by reading the previous backup data and writing it to a volume in a different pool. \bacula{}'s virtual backup feature is often called Synthetic Backup or Consolidation in other backup products. \end{bdescription} For a \bjobtype{Restore} Job, no level needs to be specified. For a \bjobtype{Verify} Job, the Level may be one of the following: \begin{bdescription} \item [InitCatalog] \index[dir]{InitCatalog} does a scan of the specified \bdirectivename{FileSet} and stores the file attributes in the Catalog database. Since no file data is saved, you might ask why you would want to do this. It turns out to be a very simple and easy way to have a \textbf{Tripwire} like feature using \bacula{}. In other words, it allows you to save the state of a set of files defined by the \bresourcename{FileSet} and later check to see if those files have been modified or deleted and if any new files have been added. This can be used to detect system intrusion. Typically you would specify a \bresourcename{FileSet} that contains the set of system files that should not change (e.g. /sbin, /boot, /lib, /bin, \ldots{}). Normally, you run the \bkeyword{InitCatalog} level verify one time when your system is first setup, and then once again after each modification (upgrade) to your system. Thereafter, when your want to check the state of your system files, you use a \bjobtype{Verify} \bvalueddirective{level}{Catalog}. This compares the results of your \bkeyword{InitCatalog} with the current state of the files. \item [Catalog] \index[dir]{Catalog} Compares the current state of the files against the state previously saved during an \bkeyword{InitCatalog}. Any discrepancies are reported. The items reported are determined by the \bjobtype{Verify} options specified on the \bdirectivename{Include} directive in the specified \bresourcename{FileSet} (see the \bresourcename{FileSet} resource below for more details). Typically this command will be run once a day (or night) to check for any changes to your system files. 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. \item [Data] \index[dir]{Data} Read back the data stored on volumes and check data attributes such as size and the checksum of all the files. To run the Verify job, it is possible to use the ``jobid'' parameter of the ``run'' command. Please note, the current Verify Data implementation requires specifying the correct Storage resource in the Verify job. The Storage resource can be changed with the bconsole command line and with the menu. It is also possible to use the \texttt{accurate} option to check catalog records at the same time. When using a Verify job with \texttt{level=Data} and \texttt{accurate=yes} can replace the \texttt{level=VolumeToCatalog} option. To run a Verify Job with the \texttt{accurate} option, it is possible to set the option in the Job definition or set use the \texttt{accurate=yes} on the command line. \begin{verbatim} * run job=VerifyData level=Data jobid=10 accurate=yes \end{verbatim} \item [VolumeToCatalog] \index[dir]{VolumeToCatalog} This level causes \bacula{} to read the file attribute data written to the Volume from the last backup Job for the job specified on the \bdirectivename{VerifyJob} directive. The file attribute data are compared to the values saved in the Catalogind database and any differences are reported. This is similar to the \bkeyword{DiskToCatalog} level except that instead of comparing the disk file attributes to the catalog database, the attribute data written to the Volume is read and compared to the catalog database. Although the attribute data including the signatures (\acs{MD}5 or \acs{SHA}1) are compared, the actual file data is not compared (it is not in the catalog). 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. \item [DiskToCatalog] \index[dir]{DiskToCatalog} This level causes \bacula{} to read the files as they currently are on disk, and to compare the current file attributes with the attributes saved in the catalog from the last backup for the job specified on the \bdirectivename{VerifyJob} directive. This level differs from the \bkeyword{VolumeToCatalog} level described above by the fact that it doesn't compare against a previous Verify job but against a previous backup. When you run this level, you must supply the verify options on your Include statements. Those options determine what attribute fields are compared. 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. \end{bdescription} \bwebdoc{Director:Job:Accurate} \item [Accurate = \byesorno{}] \index[dir]{Accurate} In accurate mode, the File daemon knowns exactly which files were present after the last backup. So it is able to handle deleted or renamed files. When restoring a FileSet for a specified date (including ``most recent''), \bacula{} is able to restore exactly the files and directories that existed at the time of the last backup prior to that date including ensuring that deleted files are actually deleted, and renamed directories are restored properly. In this mode, the File daemon must keep data concerning all files in memory. So If you do not have sufficient memory, the backup may either be terribly slow or fail. %% $$ memory = \sum_{i=1}^{n}(strlen(path_i + file_i) + sizeof(CurFile))$$ For 500.000 files (a typical desktop linux system), it will require approximately 64 Megabytes of RAM on your File daemon to hold the required information. \bwebdoc{Director:Job:VerifyJob} \item [Verify Job = \bbracket{Job-Resource-Name}] \index[dir]{Verify Job} \index[dir]{Directive!Verify Job} If you run a verify job without this directive, the last job run will be compared with the catalog, which means that you must immediately follow a backup by a \bcommandname{verify} command. If you specify a \bjobtype{Verify} Job \bacula{} will find the last job with that name that ran. This permits you to run all your backups, then run \bjobtype{Verify} jobs on those that you wish to be verified (most often a \bkeyword{VolumeToCatalog}) so that the tape just written is re-read. \bwebdoc{Director:Job:JobDefs} \item [JobDefs = \bbracket{JobDefs-Resource-Name}] \index[dir]{JobDefs} \index[dir]{Directive!JobDefs} If a \bbracket{JobDefs-Resource-Name} is specified, all the values contained in the named \bresourcename{JobDefs} resource will be used as the defaults for the current Job. Any value that you explicitly define in the current Job resource, will override any defaults specified in the \bresourcename{JobDefs} resource. The use of this directive permits writing much more compact \bresourcename{Job} resources where the bulk of the directives are defined in one or more JobDefs. This is particularly useful if you have many similar Jobs but with minor variations such as different Clients. A simple example of the use of JobDefs is provided in the default \bfilename{bacula-dir.conf} file. \bwebdoc{Director:Job:Bootstrap} \item [Bootstrap = \bbracket{bootstrap-file}] \index[dir]{Bootstrap} \index[dir]{Directive!Bootstrap} The \bdirectivename{Bootstrap} directive specifies a bootstrap file that, if provided, will be used during \bjobtype{Restore} Jobs and is ignored in other Job types. The \bbracket{bootstrap-file} contains the list of tapes to be used in a \bjobtype{Restore} Job as well as which files are to be restored. Specification of this directive is optional, and if specified, it is used only for a restore job. In addition, when running a \bjobtype{Restore} job from the console, this value can be changed. If you use the \bcommandname{restore} command in the \bconsolename{} program, to start a \bjobtype{Restore} job, the \bbracket{bootstrap-file} will be created automatically from the files you select to be restored. For additional details of the \bdirectivename{bootstrap} directive, please see \bilink{Restoring Files with the Bootstrap File}{blb:BootstrapChapter} chapter of this manual. \label{blb:writebootstrap} \bwebdoc{Director:Job:WriteBootstrap} \item [Write Bootstrap = \bbracket{bootstrap-file-specification}] \index[dir]{Write Bootstrap} \index[dir]{Directive!Write Bootstrap} The \bresourcename{writebootstrap} directive specifies a file name where \bacula{} will write a \textbf{bootstrap} file for each Backup job run. This directive applies only to \bjobtype{Backup} Jobs. If the Backup job is a Full save, \bacula{} will erase any current contents of the specified file before writing the bootstrap records. If the Job is an Incremental or Differential save, \bacula{} will append the current bootstrap record to the end of the file. 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. Note, it is a good idea to write a separate bootstrap file for each Job backed up including the job that backs up your catalog database. If the \bbracket{bootstrap-file-specification} begins with a vertical bar (\vb{}), \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. On versions 1.39.22 or greater, before opening the file or executing the specified command, \bacula{} performs \bilink{character substitution}{blb:character substitution} like in RunScript directive. To automatically manage your bootstrap files, you can use this in your \bresourcename{JobDefs} resources: \begin{bVerbatim} JobDefs { Write Bootstrap = "%c_%n.bsr" ... } \end{bVerbatim} For more details on using this file, please see the chapter entitled \bilink{The Bootstrap File}{blb:BootstrapChapter} of this manual. \bwebdoc{Director:Job:Client} \item [Client = \bbracket{client-resource-name}] \index[dir]{Client} \index[dir]{Directive!Client} The Client directive specifies the Client (File daemon) that will be used in the current Job. Only a single Client may be specified in any one Job. The Client runs on the machine to be backed up, and sends the requested files to the Storage daemon for backup, or receives them when restoring. For additional details, see the \bilink{Client Resource section}{blb:ClientResource} of this chapter. This directive is required. \bwebdoc{Director:Job:Fileset} \item [FileSet = \bbracket{FileSet-resource-name}] \index[dir]{FileSet} \index[dir]{Directive!FileSet} The FileSet directive specifies the FileSet that will be used in the current Job. The FileSet specifies which directories (or files) are to be backed up, and what options to use (e.g. compression, \ldots{}). Only a single FileSet resource may be specified in any one Job. For additional details, see the \bilink{FileSet Resource section}{blb:FileSetResource} of this chapter. This directive is required. \bwebdoc{Director:Job:Base} \item [Base = \bbracket{job-resource-name, \ldots{}}] \index[dir]{Base} \index[dir]{Directive!Base} The Base directive permits to specify the list of jobs that will be used during Full backup as base. This directive is optional. See the \bilink{Base Job chapter}{blb:basejobs} for more information. \bwebdoc{Director:Job:Messages} \item [Messages = \bbracket{messages-resource-name}] \index[dir]{Messages} \index[dir]{Directive!Messages} The Messages directive defines what Messages resource should be used for this job, and thus how and where the various messages are to be delivered. For example, you can direct some messages to a log file, and others can be sent by email. For additional details, see the \bilink{Messages Resource}{blb:MessagesChapter} Chapter of this manual. This directive is required. \bwebdoc{Director:Job:SnapshotRetention} \item [Snapshot Retention = \bbracket{time-period-specification}] \index[dir]{Snapshot Retention} \index[dir]{Directive!Snapshot Retention} The Snapshot Retention directive defines the length of time that \bacula{} will keep Snapshots in the Catalog database and on the Client after the Snapshot creation. When this time period expires, and if using the \bcommandname{snapshot prune} command, \bacula{} will prune (remove) Snapshot records that are older than the specified Snapshot Retention period and will contact the FileDaemon to delete Snapshots from the system. The Snapshot retention period is specified as seconds, minutes, hours, days, weeks, months, quarters, or years. See the \bilink{ Configuration chapter}{blb:Time} of this manual for additional details of time specification. The default is \bdefaultvalue{0 seconds}, Snapshots are deleted at the end of the backup. The Job \bdirectivename{SnapshotRetention} directive overwrites the Client \bdirectivename{SnapshotRetention} directive. \bwebdoc{Director:Job:Pool} \item [Pool = \bbracket{pool-resource-name}] \index[dir]{Pool} \index[dir]{Directive!Pool} The Pool directive defines the pool of Volumes where your data can be backed up. Many \bacula{} installations will use only the \bvalue{Default} pool. However, if you want to specify a different set of Volumes for different Clients or different Jobs, you will probably want to use Pools. For additional details, see the \bilink{Pool Resource section}{blb:PoolResource} of this chapter. This directive is required. \bwebdoc{Director:Job:FullBackupPool} \item [Full Backup Pool = \bbracket{pool-resource-name}] \index[dir]{Full Backup Pool} \index[dir]{Directive!Full Backup Pool} The \bdirectivename{Full Backup Pool} specifies a Pool to be used for Full backups. It will override any Pool specification during a Full backup. This directive is optional. \bwebdoc{Director:Job:DifferentialBackupPool} \item [Differential Backup Pool = \bbracket{pool-resource-name}] \index[dir]{Differential Backup Pool} \index[dir]{Directive!Differential Backup Pool} The \bdirectivename{Differential Backup Pool} specifies a Pool to be used for Differential backups. It will override any Pool specification during a Differential backup. This directive is optional. \bwebdoc{Director:Job:IncrementalBackupPool} \item [Incremental Backup Pool = \bbracket{pool-resource-name}] \index[dir]{Incremental Backup Pool} \index[dir]{Directive!Incremental Backup Pool} The \bdirectivename{Incremental Backup Pool} specifies a Pool to be used for Incremental backups. It will override any Pool specification during an Incremental backup. This directive is optional. \bwebdoc{Director:Job:VirtualFullBackupPool} \item [VirtualFull Backup Pool = \bbracket{pool-resource-name}] \index[dir]{VirtualFull Backup Pool} \index[dir]{Directive!VirtualFull Backup Pool} The \bdirectivename{VirtualFull Backup Pool} specifies a Pool to be used for VirtualFull backups. It will override any Pool specification during an VirtualFull backup. This directive is optional. \bwebdoc{Director:Job:BackupsToKeep} \item [BackupsToKeep = \bbracket{number}] \index[dir]{Backups to Keep} \index[dir]{Directive!Backups To Keep} When this directive is present during a Virtual Full (it is ignored for other Job types), it will look for a Full backup that has more subsequent backups than the value specified. In the example below, the Job will simply terminate unless there is a Full back followed by at least 31 backups of either level Differential or Incremental. \begin{bVerbatim} Job { Name = "VFull" Type = Backup Level = VirtualFull Client = "my-fd" File Set = "FullSet" Accurate = Yes Backups To Keep = 30 } \end{bVerbatim} Assuming that the last Full backup is followed by 32 Incremental backups, a Virtual Full will be run that consolidates the Full with the first two Incrementals that were run after the Full. The result is that you will end up with a Full followed by 30 Incremental backups. \bwebdoc{Director:Job:DeleteConsolidatedJobs} \item [DeleteConsolidatedJobs = \bbracket{yes/no}] \index[dir]{Delete Consolidated Jobs} \index[dir]{Directive!Delete Consolidated Jobs} If set to \bvalue{yes}, it will cause any old Job that is consolidated during a Virtual Full to be deleted. In the example above we saw that a Full plus one other job (either an Incremental or Differential) were consolidated into a new Full backup. The original Full plus the other Job consolidated will be deleted. The default value is \bdefaultvalue{no}. \bwebdoc{Director:Job:Schedule} \item [Schedule = \bbracket{schedule-name}] \index[dir]{Schedule} \index[dir]{Directive!Schedule} The Schedule directive defines what schedule is to be used for the Job. The schedule in turn determines when the Job will be automatically started and what Job level (i.e. Full, Incremental, \ldots{}) is to be run. This directive is optional, and if left out, the Job can only be started manually using the Console program. Although you may specify only a single Schedule resource for any one job, the Schedule resource may contain multiple \bdirectivename{Run} directives, which allow you to run the Job at many different times, and each \bdirectivename{Run} directive permits overriding the default Job Level Pool, Storage, and Messages resources. This gives considerable flexibility in what can be done with a single Job. For additional details, see the \bilink{Schedule Resource chapter}{blb:ScheduleResource} of this manual. \bwebdoc{Director:Job:Storage} \item [Storage = \bbracket{storage-resource-name}] \index[dir]{Storage} \index[dir]{Directive!Storage} The Storage directive defines the name of the storage services where you want to backup the FileSet data. For additional details, see the \bilink{Storage Resource Chapter}{blb:StorageResource} of this manual. The Storage resource may also be specified in the Job's Pool resource, in which case the value in the Pool resource overrides any value in the Job. This Storage resource definition is not required by either the Job resource or in the Pool, but it must be specified in one or the other, if not an error will result. Storage can be either specified by an single item or it can be specified as a comma separated list of storages to use according to StorageGroupPolicy. If some number of first storage daemons on the list are unavailable due to network problems, broken or unreachable for some other reason, Bacula will take first available one from the list (which is sorted according to the policy used) which is network reachable and healthy. \bwebdoc{Director:Job:StorageGroupPolicy} \item [StorageGroupPolicy = \bbracket{Storage Group Policy Name}] \index[dir]{StorageGroupPolicy} \index[dir]{Directive!StorageGroupPolicy} Storage Group Policy determines how Storage resources (from the 'Storage' directive) are being choosen from the Storage list. If no StoragePolicy is specified Bacula always tries to use first available Storage from the provided list. Currently supported policies are: \begin{itemize} \item [ListedOrder] - This is the default policy, which uses first available storage from the list provided \item [LeastUsed] - This policy scans all storage daemons from the list and chooses the one with the least number of jobs being currently run \item [FreeSpace] - This policy queries each Storage Daemon in the list for its FreeSpace (as a sum of devices specified in the SD config) and sorts the list according to the FreeSpace returned, so that first item in the list is the SD with the biggest amount of FreeSpace while the last one in the list is the one with the least amount of FreeSpace available. \item [LastBackedUpTo] - This policy ensures that job is backed up to the storage where the same job (of the same level, i.e. Full or Incremental) has been backed up the longest time ago. The goal is to split the jobs to improve redundancy. \item[LastBackupedToStore] - This policy ensures that job is backed up on the storage where the same job (with same level i.e. Full or Incremental) has been backed up to the longest time ago. The goal is to spread the jobs to improve redundancy. \item[FreeSpaceLeastUsed] - This policy ensures that a job is backed up to the storage with the most free space and least running jobs. Within the candidates storages, the least used one will be selected. Candidate storages are determined by the \texttt{StorageGroupPolicyThreshold} Job directive. If MaxFreeSpace is the largest amount of free space for all storages in the group, a storage will be a candidate if its free space is above $$MaxFreeSpace - StorageGroupPolicyThreshold$$. \end{itemize} \bwebdoc{Director:Job:StorageGroupPolicyThreshold} \item [StorageGroupPolicyThreshold = \bbracket{Threshold size}] Used in conjunction with the FreeSpaceLeastUsed StorageGroupePolicy to specify the range of free space Candidate storages. \bwebdoc{Director:Job:MaxStartDelay} \item [Max Start Delay = \bbracket{time}] \index[dir]{Max Start Delay} \index[dir]{Directive!Max Start Delay} The time specifies the maximum delay between the scheduled time and the actual start time for the Job. For example, a job can be scheduled to run at 1:00am, but because other jobs are running, it may wait to run. If the delay is set to 3600 (one hour) and the job has not begun to run by 2:00am, the job will be canceled. This can be useful, for example, to prevent jobs from running during day time hours. The default is \bdefaultvalue{0} which indicates no limit. \bwebdoc{Director:Job:MaxRunTime} \item [Max Run Time = \bbracket{time}] \index[dir]{Max Run Time} \index[dir]{Directive!Max Run Time} The time specifies the maximum allowed time that a job may run, counted from when the job starts, (\textbf{not} necessarily the same as when the job was scheduled). By default, the the watchdog thread will kill any Job that has run more than 200 days. The maximum watchdog timeout is independent of MaxRunTime and cannot be changed. \bwebdoc{Director:Job:IncrementalWaitRunTime} \item [Incremental|Differential Max Wait Time = \bbracket{time}] \index[dir]{Incremental Wait Run Time} \index[dir]{Differential Wait Run Time} \index[dir]{Directive!Differential Max Wait Time} Theses directives have been deprecated in favor of \bdirectivename{Incremental|Differential Max Run Time} since bacula 2.3.18. \bwebdoc{Director:Job:IncrementalMaxRunTime} \item [Incremental Max Run Time = \bbracket{time}] \index[dir]{Incremental Max Run Time} \index[dir]{Directive!Incremental Max Run Time} The time specifies the maximum allowed time that an Incremental backup job may run, counted from when the job starts, (\textbf{not} necessarily the same as when the job was scheduled). \bwebdoc{Director:Job:DifferentialMaxRunTime} \item [Differential Max Run Time = \bbracket{time}] \index[dir]{Differential Max Run Time} \index[dir]{Directive!Differential Max Run Time} The time specifies the maximum allowed time that a Differential backup job may run, counted from when the job starts, (\textbf{not} necessarily the same as when the job was scheduled). \bwebdoc{Director:Job:MaxRunSchedTime} \item [Max Run Sched Time = \bbracket{time}] \index[dir]{Max Run Sched Time} \index[dir]{Directive!Max Run Sched Time} The time specifies the maximum allowed time that a job may run, counted from when the job was scheduled. This can be useful to prevent jobs from running during working hours. We can see it like \texttt{Max Start Delay + Max Run Time}. \bwebdoc{Director:Job:MaxWaitTime} \item [Max Wait Time = \bbracket{time}] \index[dir]{Max Wait Time} \index[dir]{Directive!Max Wait Time} The time specifies the maximum allowed time that a job may block waiting for a resource (such as waiting for a tape to be mounted, or waiting for the storage or file daemons to perform their duties), counted from the when the job starts, (\textbf{not} necessarily the same as when the job was scheduled). This directive works as expected since bacula 2.3.18. \bimageH{different_time}{Job time control directives}{blb:fig:differenttime} \bwebdoc{Director:Job:MaximumSpawnedJobs} \item [Maximum Spawned Jobs = \bbracket{nb}] \index[dir]{Maximum Spawned Jobs} \index[dir]{Directive!Maximum Spawned Jobs} The Job resource now permits specifying a number of \bdirectivename{Maximum Spawn Jobs}. The default is \bdefaultvalue{600}. This directive can be useful if you have big hardware and you do a lot of Migration/Copy jobs which start at the same time. \bwebdoc{Director:Job:MaximumBandwidth} \item [Maximum Bandwidth = \bbracket{speed}] \index[dir]{Maximum Bandwidth} \index[dir]{Directive!Maximum Bandwidth} The speed parameter specifies the maximum allowed bandwidth in \bhighlight{bytes} that a job may use. You may specify the following speed parameter modifiers: \bvalue{kb/s} (1,000 bytes per second), \bvalue{k/s} (1,024 bytes per second), \bvalue{mb/s} (1,000,000 bytes per second), or \bvalue{m/s} (1,048,576 bytes per second). The use of TLS, TLS PSK, CommLine compression and Deduplication can interfer with the value set with the Directive. \bwebdoc{Director:Job:MaxFullInterval} \item [Max Full Interval = \bbracket{time}] \index[dir]{Max Full Interval} \index[dir]{Directive!Max Full Interval} The time specifies the maximum allowed age (counting from start time) of the most recent successful Full backup that is required in order to run Incremental or Differential backup jobs. If the most recent Full backup is older than this interval, Incremental and Differential backups will be upgraded to Full backups automatically. If this directive is not present, or specified as 0, then the age of the previous Full backup is not considered. \bwebdoc{Director:Job:MaxVirtualFullInterval} \item [Max VirtualFull Interval = \bbracket{time}] \index[dir]{Max VirtualFull Interval} \index[dir]{Directive!Max VirtualFull Interval} The time specifies the maximum allowed age (counting from start time) of the most recent successful Full backup that is required in order to run Incremental, Differential or Full backup jobs. If the most recent Full backup is older than this interval, Incremental, Differential and Full backups will be converted to a VirtualFull backup automatically. If this directive is not present, or specified as 0, then the age of the previous Full backup is not considered. \smallskip{} Please note that a VirtualFull job is not a real backup job. A VirtualFull will merge exiting jobs to create a new virtual Full job in the catalog and will copy the exiting data to new volumes. The Client is not used in a VirtualFull job, so when using this directive, the Job that was supposed to run and save recently modified data on the Client will not run. Only the next regular Job defined in the Schedule will backup the data. It will not be possible to restore the data that was modified on the Client between the last Incremental/Differential and the VirtualFull. \label{blb:PreferMountedVolumes} \bwebdoc{Director:Job:PreferMountedVolumes} \item [Prefer Mounted Volumes = \byesorno{}] \index[dir]{Prefer Mounted Volumes} \index[dir]{Directive!Prefer Mounted Volumes} If the Prefer Mounted Volumes directive is set to \bvalue{yes} (default \bdefaultvalue{yes}), the Storage daemon is requested to select either an Autochanger or a drive with a valid Volume already mounted in preference to a drive that is not ready. This means that all jobs will attempt to append to the same Volume (providing the Volume is appropriate -- right Pool, \ldots{} for that job), unless you are using multiple pools. If no drive with a suitable Volume is available, it will select the first available drive. Note, any Volume that has been requested to be mounted, will be considered valid as a mounted volume by another job. This if multiple jobs start at the same time and they all prefer mounted volumes, the first job will request the mount, and the other jobs will use the same volume. If the directive is set to \bvalue{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 with multiple drive autochangers that prefer to maximize backup throughput at the expense of using additional drives and Volumes. This means that the job will prefer to use an unused drive rather than use a drive that is already in use. Despite the above, we recommend against setting this directive to \bvalue{no} since it tends to add a lot of swapping of Volumes between the different drives and can easily lead to deadlock situations in the Storage daemon. We will accept bug reports against it, but we cannot guarantee that we will be able to fix the problem in a reasonable time. A better alternative for using multiple drives is to use multiple pools so that \bacula{} will be forced to mount Volumes from those Pools on different drives. \bwebdoc{Director:Job:PruneJobs} \item [Prune Jobs = \byesorno{}] \index[dir]{Prune Jobs} \index[dir]{Directive!Prune Jobs} Normally, pruning of Jobs from the Catalog is specified on a Client by Client basis in the Client resource with the \bdirectivename{AutoPrune} directive. If this directive is specified (not normally) and the value is \bvalue{yes}, it will override the value specified in the Client resource. The default is \bdefaultvalue{no}. \bwebdoc{Director:Job:PruneFiles} \item [Prune Files = \byesorno{}] \index[dir]{Prune Files} \index[dir]{Directive!Prune Files} Normally, pruning of Files from the Catalog is specified on a Client by Client basis in the Client resource with the \bdirectivename{AutoPrune} directive. If this directive is specified (not normally) and the value is \bvalue{yes}, it will override the value specified in the Client resource. The default is \bdefaultvalue{no}. \bwebdoc{Director:Job:PruneVolumes} \item [Prune Volumes = \byesorno{}] \index[dir]{Prune Volumes} \index[dir]{Directive!Prune Volumes} Normally, pruning of Volumes from the Catalog is specified on a Pool by Pool basis in the Pool resource with the \bdirectivename{AutoPrune} directive. Note, this is different from File and Job pruning which is done on a Client by Client basis. If this directive is specified (not normally) and the value is \bvalue{yes}, it will override the value specified in the Pool resource. The default is \bdefaultvalue{no}. \bwebdoc{Director:Job:Runscript} \item [RunScript \{\bbracket{body-of-runscript}\}] \index[dir]{RunScript} \index[dir]{Directive!Run Script} The \bdirectivename{RunScript} directive behaves like a resource in that it requires opening and closing braces around a number of directives that make up the body of the runscript. The specified \bdirectivename{Command} (see below for details) is run as an external program prior or after the current Job. This is optional. By default, the program is executed on the Client side like in \texttt{ClientRunXXXJob}. \bdirectivename{Console} options are special commands that are sent to the director instead of the \acs{OS}. At this time, console command ouputs are redirected to log with the jobid \bvalue{0}. You can use following console command : \bcommandname{delete}, \bcommandname{disable}, \bcommandname{enable}, \bcommandname{estimate}, \bcommandname{list}, \bcommandname{llist}, \bcommandname{memory}, \bcommandname{prune}, \bcommandname{purge}, \bcommandname{reload}, \bcommandname{status}, \bcommandname{setdebug}, \bcommandname{show}, \bcommandname{time}, \bcommandname{trace}, \bcommandname{update}, \bcommandname{version}, \bcommandname{.client}, \bcommandname{.jobs}, \bcommandname{.pool}, \bcommandname{.storage}. See console chapter for more information. You need to specify needed information on command line, nothing will be prompted. Example : \begin{bVerbatim} Console = "prune files client=%c" Console = "update stats age=3" \end{bVerbatim} You can specify more than one Command/Console option per RunScript. You can use following options may be specified in the body of the runscript: \LTXtable{\linewidth}{t-main-runscript} 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 OS, 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: \label{blb:character substitution} \begin{bVerbatim} %% = % %b = Job Bytes %c = Client's name %C = If the job is a Cloned job (Only on director side) %d = Daemon's name (Such as host-dir or host-fd) %D = Director's name (Also valid on file daemon) %e = Job Exit Status %E = Non-fatal Job Errors %f = Job FileSet (Only on director side) %F = Job Files %h = Client address %i = JobId %I = Migration/Copy JobId (Only in Copy/Migrate Jobs) %j = Unique Job id %l = Job Level %n = Job name %o = Job Priority %p = Pool name (Only on director side) %P = Current PID process %R = Read Bytes %s = Since time %S = Previous Job name (Only on file daemon side) %t = Job type (Backup, ...) %v = Volume name (Only on director side) %w = Storage name (Only on director side) %x = Spooling enabled? ("yes" or "no") \end{bVerbatim} Some character substitutions are not available in all situations. The Job Exit Status code \%e edits the following values: \index[dir]{Exit Status} \begin{bitemize} \item OK \item Error \item Fatal Error \item Canceled \item Differences \item Unknown term code \end{bitemize} Thus if you edit it on a command line, you will need to enclose it within some sort of quotes. \bwebdoc{Director:Job:End} You can use these following shortcuts: \LTXtable{\linewidth}{t-main-runscript-shortcuts} Examples: \begin{bVerbatim} RunScript { RunsWhen = Before FailJobOnError = No Command = "/etc/init.d/apache stop" } RunScript { RunsWhen = After RunsOnFailure = yes Command = "/etc/init.d/apache start" } \end{bVerbatim} %\paragraph \textbf{Notes about ClientRunBeforeJob} For compatibility reasons, with this shortcut, the command is executed directly when the client recieve it. And if the command is in error, other remote runscripts will be discarded. To be sure that all commands will be sent and executed, you have to use RunScript syntax. %\paragraph \textbf{Special Shell Considerations} A ``Command ='' can be one of: \begin{bitemize} \item The full path to an executable program \item The name of an executable program that can be found in the \$PATH \item A \emph{complex} shell command in the form of: "sh -c \textbackslash"your commands go here\textbackslash"" \end{bitemize} %\paragraph \textbf{Special Windows Considerations} You can run scripts just after snapshots initializations with \bkeyword{AfterVSS} keyword. In addition, for a Windows client, please take note that you must ensure a correct path to your script. The script or program can be a \bfilename{.com}, \bfilename{.exe} or a \bfilename{.bat} file. If you just put the program name in then \bacula{} will search using the same rules that \btool{cmd.exe} uses (current directory, \bacula{} bin directory, and \texttt{PATH}). It will even try the different extensions in the same order as \btool{cmd.exe}. The command can be anything that \btool{cmd.exe} or \btool{command.com} will recognize as an executable file. However, if you have slashes in the program name then \bacula{} figures you are fully specifying the name, so you must also explicitly add the three character extension. The command is run in a Win32 environment, so Unix like commands will not work unless you have installed and properly configured Cygwin in addition to and separately from \bacula{}. The System \texttt{\%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 \btool{bacula-fd}, if it is running as a service.) System environment variables can be referenced with \texttt{\%var\%} and used as either part of the command name or arguments. So if you have a script in the \bacula{} \bdirectoryname{\textbackslash{}bin} directory then the following lines should work fine: \begin{bVerbatim} Client Run Before Job = systemstate or Client Run Before Job = systemstate.bat or Client Run Before Job = "systemstate" or Client Run Before Job = "systemstate.bat" or ClientRunBeforeJob = "\"C:/Program Files/Bacula/systemstate.bat\"" \end{bVerbatim} The outer set of quotes is removed when the configuration file is parsed. You need to escape the inner quotes so that they are there when the code that parses the command line for execution runs so it can tell what the program name is. \begin{bVerbatim} ClientRunBeforeJob = "\"C:/Program Files/Software Vendor/Executable\" /arg1 /arg2 \"foo bar\"" \end{bVerbatim} The special characters \begin{bVerbatim} &<>()@^| \end{bVerbatim} 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: \begin{benumerate} \item You might want the ClientRunBeforeJob directive to specify a \bfilename{.bat} file which runs the actual client-side commands, rather than trying to run (for example) \btool{regedit /e} directly. \item The batch file should explicitly ``\texttt{exit 0}'' on successful completion. \item The path to the batch file should be specified in Unix form: \begin{bVerbatim} ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat" \end{bVerbatim} rather than DOS/Windows form: \begin{bVerbatim} ClientRunBeforeJob = "c:\bacula\bin\systemstate.bat" # INCORRECT \end{bVerbatim} \end{benumerate} For Win32, please note that there are certain limitations: \begin{bVerbatim} ClientRunBeforeJob = "C:/Program Files/Bacula/bin/pre-exec.bat" \end{bVerbatim} Lines like the above do not work because there are limitations of \btool{cmd.exe} that is used to execute the command. \bacula{} prefixes the string you supply with \btool{cmd.exe /c }. To test that your command works you should type \btool{cmd /c "C:/Program Files/test.exe"} at a cmd prompt and see what happens. Once the command is correct insert a backslash (\textbackslash{}) before each double quote ("), and then put quotes around the whole thing when putting it in the director's configuration file. You either need to have only one set of quotes or else use the short name and don't put quotes around the command path. Below is the output from cmd's help as it relates to the command line passed to the \texttt{/c} option. If \texttt{/C} or \texttt{/K} is specified, then the remainder of the command line after the switch is processed as a command line, where the following logic is used to process quote (") characters: \begin{benumerate} \item If all of the following conditions are met, then quote characters on the command line are preserved: \begin{bitemize} \item no \texttt{/S} switch. \item exactly two quote characters. \item no special characters between the two quote characters, where special is one of: \begin{bVerbatim} &<>()@^| \end{bVerbatim} \item there are one or more whitespace characters between the the two quote characters. \item the string between the two quote characters is the name of an executable file. \end{bitemize} \item Otherwise, old behavior is to see if the first character is a quote character and if so, strip the leading character and remove the last quote character on the command line, preserving any text after the last quote character. \end{benumerate} 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: \begin{bVerbatim} #!/bin/sh # ===== backupdb.sh DIR=/u01/mercuryd mkfifo $DIR/dbpipe db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING & sleep 1 \end{bVerbatim} The following line in the Job resource in the \bfilename{bacula-dir.conf} file: \begin{bVerbatim} Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t' '%l'\"" \end{bVerbatim} 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 \btool{db2 BACKUP DATABASE} command, thus the backup stalls. To remedy this situation, the ``db2 BACKUP DATABASE'' line should be changed to the following: \begin{bVerbatim} db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log 2>&1 < /dev/null & \end{bVerbatim} It is important to redirect the input and outputs of a backgrounded command to \bdirectoryname{/dev/null} to prevent the script from blocking. \bwebdoc{Director:Job:RunBeforeJob} \item [Run Before Job = \bbracket{command}] \index[dir]{Run Before Job} \index[dir]{Directive!Run Before Job} \index[dir]{Directive!Run Before Job} The specified \bbracket{command} is run as an external program prior to running the current Job. This directive is not required, but if it is defined, and if the exit code of the program run is non-zero, the current \bacula{} job will be canceled. \begin{bVerbatim} Run Before Job = "echo test" \end{bVerbatim} it's equivalent to : \begin{bVerbatim} RunScript { Command = "echo test" RunsOnClient = No RunsWhen = Before } \end{bVerbatim} Lutz Kittler has pointed out that using the RunBeforeJob 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. \bwebdoc{Director:Job:RunAfterJob} \item [Run After Job = \bbracket{Command}] \index[dir]{Run After Job} \index[dir]{Directive!Run After Job} The specified \bbracket{Command} is run as an external program if the current job terminates normally (without error or without being canceled). This directive is not required. If the exit code of the program run is non-zero, \bacula{} will print a warning message. Before submitting the specified command to the operating system, \bacula{} performs character substitution as described above for the \bdirectivename{RunScript} directive. An example of the use of this directive is given in the \bxlink{Tips}{blb:JobNotification}{problems}{chapter} of the \bproblemman{}. See the \textbf{Run After Failed Job} if you want to run a script after the job has terminated with any non-normal status. \bwebdoc{Director:Job:RunAfterJob} \item [Run After Failed Job = \bbracket{Command}] \index[dir]{Run After Job} \index[dir]{Directive!Run After Job} The specified \bbracket{Command} is run as an external program after the current job terminates with any error status. This directive is not required. The command string must be a valid program name or name of a shell script. If the exit code of the program run is non-zero, \bacula{} will print a warning message. Before submitting the specified command to the operating system, \bacula{} performs character substitution as described above for the \bdirectivename{RunScript} directive. Note, if you wish that your script will run regardless of the exit status of the Job, you can use this : \begin{bVerbatim} RunScript { Command = "echo test" RunsWhen = After RunsOnFailure = yes RunsOnClient = no RunsOnSuccess = yes # default, you can drop this line } \end{bVerbatim} An example of the use of this directive is given in the \bxlink{Tips}{blb:JobNotification}{problems}{chapter} of the \bproblemman{}. \bwebdoc{Director:Job:ClientRunBeforeJob} \item [Client Run Before Job = \bbracket{Command}] \index[dir]{Client Run Before Job} \index[dir]{Directive!Client Run Before Job} This directive is the same as \bdirectivename{Run Before Job} except that the program is run on the client machine. The same restrictions apply to Unix systems as noted above for the \bdirectivename{RunScript}. \bdirectivename{ClientRunBeforeJob} can be used with \bjobtype{Backup} and \bjobtype{Restore} jobs. \bwebdoc{Director:Job:ClientRunAfterJob} \item [Client Run After Job = \bbracket{Command}] \index[dir]{Client Run After Job} \index[dir]{Directive!Client Run After Job} The specified \bbracket{Command} is run on the client machine as soon as data spooling is complete in order to allow restarting applications on the client as soon as possible. \bdirectivename{ClientRunBeforeJob} can be used with Backup and Restore jobs. Note, please see the notes above in \bdirectivename{RunScript} concerning Windows clients. \bwebdoc{Director:Job:RerunFailedLevels} \item [Rerun Failed Levels = \byesorno{}] \index[dir]{Rerun Failed Levels} \index[dir]{Directive!Rerun Failed Levels} If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), and \bacula{} detects that a previous job at a higher level (i.e. Full or Differential) has failed, the current job level will be upgraded to the higher level. This is particularly useful for Laptops where they may often be unreachable, and if a prior Full save has failed, you wish the very next backup to be a Full save rather than whatever level it is started as. There are several points that must be taken into account when using this directive: first, a failed job is defined as one that has not terminated normally, which includes any running job of the same name (you need to ensure that two jobs of the same name do not run simultaneously); secondly, the \bdirectivename{Ignore FileSet Changes} directive is not considered when checking for failed levels, which means that any FileSet change will trigger a rerun. \bwebdoc{Director:Job:SpoolData} \item [Spool Data = \byesorno{}] \index[dir]{Spool Data} \index[dir]{Directive!Spool Data} If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), the Storage daemon will be requested to spool the data for this Job to disk rather than write it directly to the Volume (normally a tape). Thus the data is written in large blocks to the Volume rather than small blocks. This directive is particularly useful when running multiple simultaneous backups to tape. Once all the data arrives or the spool files' maximum sizes are reached, the data will be despooled and written to tape. Spooling data prevents interleaving date from several job and reduces or eliminates tape drive stop and start commonly known as ``shoe-shine''. We don't recommend using this option if you are writing to a disk file using this option will probably just slow down the backup jobs. NOTE: When this directive is set to yes, Spool Attributes is also automatically set to yes. \bwebdoc{Director:Job:SpoolAttributes} \item [Spool Attributes = \byesorno{}] \index[dir]{Spool Attributes} \index[dir]{Directive!Spool Attributes} \index[dir]{slow} \index[general]{slow} \index[dir]{Backups!slow} \index[general]{Backups!slow} The default is set to \bdefaultvalue{yes}, the Storage daemon will buffer the File attributes and Storage coordinates to a temporary file in the Working Directory, then when writing the Job data to the tape is completed, the attributes and storage coordinates will be sent to the Director. If set to \bvalue{no} the File attributes are sent by the Storage daemon to the Director as they are stored on tape. NOTE: When Spool Data is set to yes, Spool Attributes is also automatically set to yes. \bwebdoc{Director:Job:SpoolSize} \item [SpoolSize={\it bytes}] \index[dir]{SpoolSize} \index[dir]{Directive!SpoolSize} where the bytes specify the maximum spool size for this job. The default is take from Device Maximum Spool Size limit. This directive is available only in \bacula{} version 2.3.5 or later. \bwebdoc{Director:Job:Where} \item [Where = \bbracket{directory}] \index[dir]{Where} \index[dir]{Directive!Where} This directive applies only to a Restore job and specifies a prefix to the directory name of all files being restored. This permits files to be restored in a different location from which they were saved. If \bdirectivename{Where} is not specified or is set to slash (\bdirectoryname{/}), the files will be restored to their original location. By default, we have set \bdirectivename{Where} in the example configuration files to be \bdirectoryname{/tmp/bacula-restores}. This is to prevent accidental overwriting of your files. \label{blb:confaddprefix} \bwebdoc{Director:Job:AddPrefix} \item [Add Prefix = \bbracket{directory}] \index[dir]{AddPrefix} \index[dir]{Directive!AddPrefix} This directive applies only to a Restore job and specifies a prefix to the directory name of all files being restored. This will use \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later. \bwebdoc{Director:Job:AddSuffix} \item [Add Suffix = \bbracket{extention}] \index[dir]{AddSuffix} \index[dir]{Directive!AddSuffix} This directive applies only to a Restore job and specifies a suffix to all files being restored. This will use \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later. Using \texttt{Add Suffix=.old}, \bfilename{/etc/passwd} will be restored to \bfilename{/etc/passwsd.old} \bwebdoc{Director:Job:StripPrefix} \item [Strip Prefix = \bbracket{directory}] \index[dir]{StripPrefix} \index[dir]{Directive!StripPrefix} This directive applies only to a Restore job and specifies a prefix to remove from the directory name of all files being restored. This will use the \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later. Using \texttt{Strip Prefix=/etc}, \bfilename{/etc/passwd} will be restored to \bfilename{/passwd} Under Windows, if you want to restore \bfilename{c:/files} to \bfilename{d:/files}, you can use : \begin{bVerbatim} Strip Prefix = c: Add Prefix = d: \end{bVerbatim} \bwebdoc{Director:Job:RegexWhere} \item [RegexWhere = \bbracket{expressions}] \index[dir]{RegexWhere} \index[dir]{Directive!RegexWhere} This directive applies only to a Restore job and specifies a regex filename manipulation of all files being restored. This will use \bilink{File Relocation}{blb:filerelocation} feature implemented in \bacula{} 2.1.8 or later. For more informations about how use this option, see \bilink{this}{useregexwhere}. \bwebdoc{Director:Job:Replace} \item [Replace = \bbracket{replace-option}] \index[dir]{Replace} \index[dir]{Directive!Replace} This directive applies only to a Restore job and specifies what happens when \bacula{} wants to restore a file or directory that already exists. You have the following options for \bbracket{replace-option}: \bwebdoc{Director:Job:RestoreClient} \item [RestoreClient = \bbracket{client-resource-name}] \index[dir]{RestoreClient} \index[dir]{Directive!RestoreClient} The RestoreClient directive specifies the default Client (File Daemon) that will be used with the restore job. If this directive is not set then a default restore client will be set to a backup client as usual. It is possible to define a dedicated restore job and run an automatic (scheduled) restore tests of your backups which will be redirected to the restore test Client. \begin{bdescription} \item [always] \index[dir]{always} when the file to be restored already exists, it is deleted and then replaced by the copy that was backed up. This is the default value. \item [ifnewer] \index[dir]{ifnewer} if the backed up file (on tape) is newer than the existing file, the existing file is deleted and replaced by the back up. \item [ifolder] \index[dir]{ifolder} if the backed up file (on tape) is older than the existing file, the existing file is deleted and replaced by the back up. \item [never] \index[dir]{never} if the backed up file already exists, \bacula{} skips restoring this file. \end{bdescription} \bwebdoc{Director:Job:PrefixLinks} \item [Prefix Links=\byesorno{}] \index[dir]{Prefix Links} \index[dir]{Directive!Prefix Links} If a \bdirectoryname{Where} path prefix is specified for a recovery job, apply it to absolute links as well. The default is \bdefaultvalue{no}. When set to \bvalue{yes} then while restoring files to an alternate directory, any absolute soft links will also be modified to point to the new alternate directory. Normally this is what is desired -- i.e. everything is self consistent. However, if you wish to later move the files to their original locations, all files linked with absolute names will be broken. \bwebdoc{Director:Job:MaximumConcurrentJobs} \item [Maximum Concurrent Jobs = \bbracket{number}] \index[dir]{Maximum Concurrent Jobs} \index[dir]{Directive!Maximum Concurrent Jobs} where \bbracket{number} is the maximum number of Jobs from the current Job resource that can run concurrently. Note, this directive limits only Jobs with the same name as the resource in which it appears. Any other restrictions on the maximum concurrent jobs such as in the Director, Client, or Storage resources will also apply in addition to the limit specified here. The default is set to \bdefaultvalue{1}, but you may set it to a larger number. We strongly recommend that you read the WARNING documented under \bilink{ Maximum Concurrent Jobs}{blb:DirMaxConJobs} in the Director's resource. \bwebdoc{Director:Job:RescheduleOnError} \item [Reschedule On Error = \byesorno{}] \index[dir]{Reschedule On Error} \index[dir]{Directive!Reschedule On Error} If this directive is enabled, and the job terminates in error, the job will be rescheduled as determined by the \bdirectivename{Reschedule Interval} and \bdirectivename{Reschedule Times} directives. If you cancel the job, it will not be rescheduled. The default is \bdefaultvalue{no} (i.e. the job will not be rescheduled). This specification can be useful for portables, laptops, or other machines that are not always connected to the network or switched on. \bwebdoc{Director:Job:RescheduleIncompleteJobs} \item [Reschedule Incomplete Jobs = \byesorno{}] \index[dir]{Reschedule Incomplete Jobs} \index[dir]{Directive!Reschedule Incomplete Jobs} If this directive is enabled, and the job terminates in incomplete status, the job will be rescheduled as determined by the \bdirectivename{Reschedule Interval} and \bdirectivename{Reschedule Times} directives. If you cancel the job, it will not be rescheduled. The default is \bdefaultvalue{yes} (i.e. Incomplete jobs will be rescheduled). \bwebdoc{Director:Job:RescheduleInterval} \item [Reschedule Interval = \bbracket{time-specification}] \index[dir]{Reschedule Interval} \index[dir]{Directive!Reschedule Interval} If you have specified \bvalueddirective{Reschedule On Error}{yes} and the job terminates in error, it will be rescheduled after the interval of time specified by \bbracket{time-specification}. See \bilink{the time specification formats}{blb:Time} in the Configure chapter for details of time specifications. If no interval is specified, the job will not be rescheduled on error. The default Reschedule Interval is \bdefaultvalue{30 minutes} (\bdefaultvalue{1800 seconds}). \bwebdoc{Director:Job:RescheduleTimes} \item [Reschedule Times = \bbracket{count}] \index[dir]{Reschedule Times} \index[dir]{Directive!Reschedule Times} This directive specifies the maximum number of times to reschedule the job. If it is set to \bdefaultvalue{zero} (\bdefaultvalue{0}, the default) the job will be rescheduled an indefinite number of times. \bwebdoc{Director:Job:AllowIncompleteJobs} \item [Allow Incomplete Jobs = \byesorno{}] \index[dir]{Allow Incomplete Jobs} \index[dir]{Directive!Allow Incomplete Jobs} If this directive is disabled, and the job terminates in incomplete status, the data of the job will be discarded and the job will be marked in error. Bacula will treat this job like a regular job in error. The default is \bdefaultvalue{yes}. \bwebdoc{Director:Job:AllowDuplicateJobs} \item [Allow Duplicate Jobs = \byesorno{}] \index[general]{Allow Duplicate Jobs} A duplicate job in the sense we use it here means a second or subsequent job with the same name starts. This happens most frequently when the first job runs longer than expected because no tapes are available. The default is \bdefaultvalue{yes}. \bimageH[0.8\linewidth]{duplicate-real}{Allow Duplicate Jobs usage}{blb:fig:allowduplicatejobs} If this directive is enabled duplicate jobs will be run. If the directive is set to \bvalue{no} then only one job of a given name may run at one time, and the action that \bacula{} takes to ensure only one job runs is determined by the other directives (see below). If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and two jobs are present and none of the three directives given below permit cancelling a job, then the current job (the second one started) will be cancelled. \bwebdoc{Director:Job:AllowHigherDuplicates} \item [Allow Higher Duplicates = \byesorno{}] \index[general]{Allow Higher Duplicates} This directive was implemented in version 5.0.0, but does not work as expected. If used, it should always be set to no. In later versions of \bacula{} the directive is disabled (disregarded). \bwebdoc{Director:Job:CancelLowerLevelDuplicates} \item [Cancel Lower Level Duplicates = \byesorno{}] \index[general]{Cancel Lower Level Duplicates} If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and this directive is set to \bvalue{yes}, \bacula{} will choose between duplicated jobs the one with the highest level. For example, it will cancel a previous Incremental to run a Full backup. It works only for Backup jobs. The default is \bdefaultvalue{no}. If the levels of the duplicated jobs are the same, nothing is done and the other Cancel XXX Duplicate directives will be examined. \bwebdoc{Director:Job:CancelQueuedDuplicates} \item [Cancel Queued Duplicates = \byesorno{}] \index[general]{Cancel Queued Duplicates} If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and if this directive is set to \bvalue{yes} any job that is already queued to run but not yet running will be canceled. The default is \bdefaultvalue{no}. \bwebdoc{Director:Job:CancelRunningDuplicates} \item[Cancel Running Duplicates = \byesorno{}] \index[general]{Cancel Running Duplicates} If \bdirectivename{Allow Duplicate Jobs} is set to \bvalue{no} and if this directive is set to \bvalue{yes} any job that is already running will be canceled. The default is \bdefaultvalue{no}. %%\item[DuplicateJobProximity = \bbracket{time-specification}] %%\index[general]{Duplicate Job Proximity} %% This directive permits to determine if two jobs are really duplicated. %% If the first one is running for long time, this is probably not a good %% idea to cancel it. \bwebdoc{Director:Job:Run} \item [Run = \bbracket{job-name}] \index[dir]{Run} \index[dir]{Directive!Run} \index[dir]{Clone a Job} The \bdirectivename{Run} directive (not to be confused with the Run option in a Schedule) allows you to start other jobs or to clone jobs. By using the cloning keywords (see below), you can backup the same data (or almost the same data) to two or more drives at the same time. The \bbracket{job-name} is normally the same name as the current Job resource (thus creating a clone). However, it may be any Job name, so one job may start other related jobs. 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 \bcommandname{run} command from the console. For example \textbf{storage=\acs{DDS}-4 \ldots{}}. In addition, there are two special keywords that permit you to clone the current job. They are \textbf{level=\%l} and \textbf{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: \begin{bVerbatim} run = "Nightly-backup level=%l since=\"%s\" storage=DDS-4" \end{bVerbatim} A cloned job will not start additional clones, so it is not possible to recurse. Please note that all cloned jobs, as specified in the Run directives are submitted for running before the original job is run (while it is being initialized). This means that any clone job will actually start before the original job, and may even block the original job from starting until the original job finishes unless you allow multiple simultaneous jobs. Even if you set a lower priority on the clone job, if no other jobs are running, it will start before the original job. If you are trying to prioritize jobs by using the clone feature (Run directive), you will find it much easier to do using a RunScript resource, or a RunBeforeJob directive. \bwebdoc{Director:Job:Priority} \item [Priority = \bbracket{number}] \index[dir]{Priority} \index[dir]{Directive!Priority} \label{blb:Priority} This directive permits you to control the order in which your jobs will be run by specifying a positive non-zero number. The higher the number, the lower the job priority. Assuming you are not running concurrent jobs, all queued jobs of priority 1 will run before queued jobs of priority 2 and so on, regardless of the original scheduling order. 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, unless \bdirectivename{Allow Mixed Priority} is set. The default priority is \bdefaultvalue{10}. If you want to run concurrent jobs you should keep these points in mind: \begin{bitemize} \item See \bxlink{Running Concurrent Jobs}{blb:ConcurrentJobs}{problems}{section} on how to setup concurrent jobs in the \bproblemman{}. \item \bacula{} concurrently runs jobs of only one priority at a time. It will not simultaneously run a priority 1 and a priority 2 job. \item If \bacula{} is running a priority 2 job and a new priority 1 job is scheduled, it will wait until the running priority 2 job terminates even if the \bdirectivename{Maximum Concurrent Jobs} settings would otherwise allow two jobs to run simultaneously. \item Suppose that bacula is running a priority 2 job and a new priority 1 job is scheduled and queued waiting for the running priority 2 job to terminate. If you then start a second priority 2 job, the waiting priority 1 job will prevent the new priority 2 job from running concurrently with the running priority 2 job. That is: as long as there is a higher priority job waiting to run, no new lower priority jobs will start even if the Maximum Concurrent Jobs settings would normally allow them to run. This ensures that higher priority jobs will be run as soon as possible. \end{bitemize} 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. \label{blb:AllowMixedPriority} \bwebdoc{Director:Job:AllowMixedPriority} \item [Allow Mixed Priority = \byesorno{}] \index[dir]{Allow Mixed Priority} This directive is only implemented in version 2.5 and later. When set to \bvalue{yes} (default \bdefaultvalue{no}), this job may run even if lower priority jobs are already running. This means a high priority job will not have to wait for other jobs to finish before starting. The scheduler will only mix priorities when all running jobs have this set to true. Note that only higher priority jobs will start early. Suppose the director will allow two concurrent jobs, and that two jobs with priority 10 are running, with two more in the queue. If a job with priority 5 is added to the queue, it will be run as soon as one of the running jobs finishes. However, new priority 10 jobs will not be run until the priority 5 job has finished. %%\label{blb:WritePartAfterJob} %% %%\bwebdoc{Director:Job:WritePartAfterJob} %%\item [Write Part After Job = \byesorno{}] %%\index[dir]{Write Part After Job} %%\index[dir]{Directive!Write Part After Job} %% This directive is only implemented in version 1.37 and later. %% If this directive is set to \bvalue{yes} (default \bdefaultvalue{no}), a new part file %% will be created after the job is finished. %% %% It should be set to \bvalue{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 \bvalue{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. %% %% This directive is ignored with tape and FIFO devices. \end{bdescription} The following is an example of a valid Job resource definition: \begin{bVerbatim} Job { Name = "Minou" Type = Backup Level = Incremental # default Client = Minou FileSet="Minou Full Set" Storage = DLTDrive Pool = Default Schedule = "MinouWeeklyCycle" Messages = Standard } \end{bVerbatim} \label{blb:JobDefsResource} \section{The JobDefs Resource} \index[general]{JobDefs Resource} \index[general]{Resource!JobDefs} 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. \label{blb:ScheduleResource} \section{The Schedule Resource} \index[general]{Resource!Schedule} \index[general]{Schedule Resource} 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. \begin{bdescription} \item [Schedule] \index[dir]{Schedule} \index[dir]{Directive!Schedule} Start of the Schedule directives. No \bresourcename{Schedule} resource is required, but you will need at least one if you want Jobs to be automatically started. \bwebdoc{Director:Schedule:Name} \item [Name = \bbracket{name}] \index[dir]{Name} \index[dir]{Directive!Name} The name of the schedule being defined. The Name directive is required. \bwebdoc{Director:Schedule:Enabled} \item [Enabled = \byesorno{}] \index[dir]{Enabled} \index[dir]{Directive!Enabled} This directive allows you to enable or disable the \bresourcename{Schedule} resource. \bwebdoc{Director:Schedule:Run} \item [Run = \bbracket{Job-overrides} \bbracket{Date-time-specification}] \index[dir]{Run} \index[dir]{Directive!Run} The Run directive defines when a Job is to be run, and what overrides if any to apply. You may specify multiple \bdirectivename{Run} directives within a \bresourcename{Schedule} resource. If you do, they will all be applied (i.e. multiple schedules). If you have two \bdirectivename{Run} directives that start at the same time, two Jobs will start at the same time (well, within one second of each other). The \textbf{Job-overrides} permit overriding the Level, the Storage, the Messages, and the Pool specifications provided in the Job resource. In addition, the \bdirectivename{FullPool}, the \bdirectivename{IncrementalPool}, and the \bdirectivename{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. \textbf{Job-overrides} are specified as: \textbf{keyword=value} where the keyword is \bkeyword{Level}, \bkeyword{Storage}, \bkeyword{Messages}, \bkeyword{Pool}, \bkeyword{FullPool}, \bkeyword{DifferentialPool}, or \bkeyword{IncrementalPool}, and the \bvalue{value} is as defined on the respective directive formats for the Job resource. You may specify multiple \textbf{Job-overrides} on one \bdirectivename{Run} directive by separating them with one or more spaces or by separating them with a trailing comma. For example: \bwebdoc{Director:Schedule:End} \begin{bdescription} \item [Level=Full] \index[dir]{Level} \index[dir]{Directive!Level} is all files in the FileSet whether or not they have changed. \item [Level=Incremental] \index[dir]{Level} \index[dir]{Directive!Level} is all files that have changed since the last backup. \item [Pool=Weekly] \index[dir]{Pool} \index[dir]{Directive!Pool} specifies to use the Pool named \textbf{Weekly}. \item [Storage=DLT\_Drive] \index[dir]{Storage} \index[dir]{Directive!Storage} specifies to use \textbf{DLT\_Drive} for the storage device. \item [Messages=Verbose] \index[dir]{Messages} \index[dir]{Directive!Messages} specifies to use the \textbf{Verbose} message resource for the Job. \item [FullPool=Full] \index[dir]{FullPool} \index[dir]{Directive!FullPool} specifies to use the Pool named \textbf{Full} if the job is a full backup, or is upgraded from another type to a Full backup. \item [DifferentialPool=Differential] \index[dir]{DifferentialPool} \index[dir]{Directive!DifferentialPool} specifies to use the Pool named \textbf{Differential} if the job is a differential backup. \item [IncrementalPool=Incremental] \index[dir]{IncrementalPool} \index[dir]{Directive!IncrementalPool} specifies to use the Pool named \textbf{Incremental} if the job is an incremental backup. \item [Next Pool = \bbracket{pool-specification}] The \textbf{Next Pool} directive specifies the pool to which Jobs will be migrated. This directive is used to define the Pool into which the data will be migrated. %% \item [WritePartAfterJob=\byesorno{}] %% \index[dir]{WritePartAfterJob} %% \index[dir]{Directive!WritePartAfterJob} %% tells \bacula{} to request the Storage daemon to write the current part %% file to the device when the job is finished (see %% \bilink{Write Part After Job directive in the Job resource}{blb:WritePartAfterJob}). Please note, %% this directive is implemented only in version 1.37 and later. The %% default is \bdefaultvalue{yes}. We strongly recommend that you keep this set to yes %% otherwise, when the last job has finished one part will remain in the %% spool file and restore may or may not work. \item [Priority = \bbracket{number}] \index[dir]{Priority} \index[dir]{Directive!Priority} This directive permits you to control the order in which your jobs will be run by specifying a positive non-zero number. The higher the number, the lower the job priority. Assuming you are not running concurrent jobs, all queued jobs of priority 1 will run before queued jobs of priority 2 and so on, regardless of the original scheduling order. 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, unless \bdirectivename{Allow Mixed Priority} is set. The default priority is \bdefaultvalue{10}. See \vref{blb:Priority} for more information. \end{bdescription} \label{Date-time-specification} \bbracket{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 \textbf{month}, \textbf{day}, \textbf{hour}, and \textbf{minute} the Job is to be run. Of these four items to be specified, \textbf{day} is special in that you may either specify a day of the month such as \bvalue{1}, \bvalue{2}, \ldots{} \bvalue{31}, or you may specify a day of the week such as \bkeyword{Monday}, \bkeyword{Tuesday}, \ldots{} \bkeyword{Sunday}. Finally, you may also specify a week qualifier to restrict the schedule to the \bkeyword{first}, \bkeyword{second}, \bkeyword{third}, \bkeyword{fourth}, \bkeyword{fifth} or \bkeyword{sixth} week of the month. For example, if you specify only a day of the week, such as \bkeyword{Tuesday} the Job will be run every hour of every Tuesday of every Month. That is the \bkeyword{month} and \bkeyword{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 \bdirectivename{Run} specifications each with a different minute. The date/time to run the Job can be specified in the following way in pseudo-\acs{BNF}: \begin{bVerbatim} = on = at = 1st | 2nd | 3rd | 4th | 5th | 6th | first | second | third | fourth | fifth = sun | mon | tue | wed | thu | fri | sat | sunday | monday | tuesday | wednesday | thursday | friday | saturday = w00 | w01 | ... w52 | w53 = jan | feb | mar | apr | may | jun | jul | aug | sep | oct | nov | dec | january | february | ... | december = daily = weekly = monthly = hourly = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 = | <12hour> = 0 | 1 | 2 | ... 12 = 0 | 1 | 2 | ... 23 = 0 | 1 | 2 | ... 59 = 1 | 2 | ... 31 | lastday