director-resource-job-definitions.tex

\defDirective{Dir}{Job}{Accurate}{}{}{%
\label{accuratemode}%
\label{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"), Bareos 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.

When doing \ilink{VirtualFull}{VirtualFull} backups, it is advised to use the accurate mode,
otherwise the VirtualFull might contain already deleted files.

However, using the accurate mode has also disadvantages:
\begin{itemize}
    \item 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.

\end{itemize}


}

\defDirective{Dir}{Job}{Add Prefix}{}{}{%
This directive applies only to a Restore job and specifies a prefix to the
directory name of all files being restored.  This will use \ilink{File
Relocation}{filerelocation} feature.
}

\defDirective{Dir}{Job}{Add Suffix}{}{}{%
This directive applies only to a Restore job and specifies a suffix to all
files being restored.  This will use \ilink{File Relocation}{filerelocation}
feature.

Using \texttt{Add Suffix=.old}, \texttt{/etc/passwd} will be restored to
\texttt{/etc/passwsd.old}
}

\defDirective{Dir}{Job}{Allow Duplicate Jobs}{}{}{%
\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.5\textwidth]{\idir duplicate-real}
  \caption{Allow Duplicate Jobs usage}
  \label{fig:allowduplicatejobs}
\end{figure}%
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.

If this directive is enabled duplicate jobs will be run.  If
the directive is set to \parameter{no} then only one job of a given name
may run at one time.
The action that Bareos takes to ensure only
one job runs is determined by the directives
\begin{itemize}
    \item \linkResourceDirective{Dir}{Job}{Cancel Lower Level Duplicates}
    \item \linkResourceDirective{Dir}{Job}{Cancel Queued Duplicates}
    \item \linkResourceDirective{Dir}{Job}{Cancel Running Duplicates}
\end{itemize}

If none of these directives is set to \parameter{yes}, {\bf Allow Duplicate Jobs} is set to \parameter{no} and two jobs
are present, then the current job (the second one started)
will be cancelled.
}

\defDirective{Dir}{Job}{Allow Higher Duplicates}{}{}{%
}

\defDirective{Dir}{Job}{Allow Mixed Priority}{}{}{%
When
set to \parameter{yes}, 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.
}


\defDirective{Dir}{Job}{Backup Format}{}{}{%
The backup format used for protocols which support multiple formats.
By default, it uses the Bareos \parameter{Native} Backup format.
Other protocols,
like NDMP supports different backup formats for instance:
\begin{itemize}
\item Dump
\item Tar
\item SMTape
\end{itemize}
}

\defDirective{Dir}{Job}{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 \ilink{Base Job
chapter}{basejobs} for more information.
}

\defDirective{Dir}{Job}{Bootstrap}{}{}{%
The Bootstrap directive specifies a bootstrap file that, if provided,
will be used during {\bf Restore} Jobs and is ignored in other Job
types.  The {\bf bootstrap} file contains the list of tapes to be used
in a 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 Restore job
from the console, this value can be changed.

If you use the \ilink{restore}{bcommandRestore} command in the Console program, to start a
restore job, the {\bf bootstrap} file will be created automatically from
the files you select to be restored.

For additional details see \nameref{BootstrapChapter} chapter.
}

\defDirective{Dir}{Job}{Cancel Lower Level Duplicates}{}{}{%
If \linkResourceDirective{Dir}{Job}{Allow Duplicate Jobs} is set to \parameter{no} and this
directive is set to \parameter{yes}, Bareos 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.
If the levels of the duplicated
jobs are the same, nothing is done and the directives
\linkResourceDirective{Dir}{Job}{Cancel Queued Duplicates} and \linkResourceDirective{Dir}{Job}{Cancel Running Duplicates}
will be examined.
}

\defDirective{Dir}{Job}{Cancel Queued Duplicates}{}{}{%
If \linkResourceDirective{Dir}{Job}{Allow Duplicate Jobs} is set to \parameter{no} and
if this directive is set to \parameter{yes} any job that is
already queued to run but not yet running will be canceled.
}

\defDirective{Dir}{Job}{Cancel Running Duplicates}{}{}{%
If \linkResourceDirective{Dir}{Job}{Allow Duplicate Jobs} is set to \parameter{no} and
if this directive is set to \parameter{yes} any job that is already running
will be canceled.
}

\defDirective{Dir}{Job}{Catalog}{}{13.4.0}{%
This specifies the name of the catalog resource to be used for this Job.
When a catalog is defined in a Job it will override the definition in
the client.
}

\defDirective{Dir}{Job}{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
\nameref{DirectorResourceClient} of this chapter.
This directive is required
For versions before 13.3.0, this directive is required for all Jobtypes.
For \sinceVersion{dir}{Director Job Resource isn't required for Copy or Migrate jobs}{13.3.0}
it is required for all Jobtypes but Copy or Migrate jobs.
}

\defDirective{Dir}{Job}{Client Run After Job}{}{}{%
This is a shortcut for the \linkResourceDirective{Dir}{Job}{Run Script} resource,
that run on the client after a backup job.
}

\defDirective{Dir}{Job}{Client Run Before Job}{}{}{%
This is basically a shortcut for the \linkResourceDirective{Dir}{Job}{Run Script} resource,
that run on the client before the backup job.

\warning{For compatibility reasons, with this shortcut, the command is executed
directly when the client receive 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 \linkResourceDirective{Dir}{Job}{Run Script} syntax.}
}

\defDirective{Dir}{Job}{Description}{}{}{
}

\defDirective{Dir}{Job}{Differential Backup Pool}{}{}{%
The Differential Backup Pool specifies a Pool to be used for
Differential backups.  
It will override any \linkResourceDirective{Dir}{Job}{Pool} specification during a
Differential backup.
}

\defDirective{Dir}{Job}{Differential Max Runtime}{}{}{%
The time specifies the maximum allowed time that a Differential backup job may
run, counted from when the job starts ({\bf not} necessarily the same as when
the job was scheduled).
}

\defDirective{Dir}{Job}{Differential Max Wait Time}{}{}{%
This directive has been deprecated in favor of
\linkResourceDirective{Dir}{Job}{Differential Max Runtime}.
}

\defDirective{Dir}{Job}{Dir Plugin Options}{}{}{%
These settings are plugin specific, see \nameref{dirPlugins}.
}

\defDirective{Dir}{Job}{Enabled}{}{}{%
This directive allows you to enable or disable automatic execution
  via the scheduler of a Job.
}

\defDirective{Dir}{Job}{FD Plugin Options}{}{}{%
These settings are plugin specific, see \nameref{fdPlugins}.
}

\defDirective{Dir}{Job}{File History Size}{}{}{%
When using NDMP and \linkResourceDirective{Dir}{Job}{Save File History} is enabled,
this directives controls the size of the internal temporary database (LMDB)
to translate NDMP file and directory information into Bareos file and directory information.

\configdirective{File History Size} must be greater the number of directories + files of this NDMP backup job.

\warning{This uses a large memory mapped file (\configdirective{File History Size} $* 256 \Longrightarrow$ around 2,3 GB for the \configdirective{File History Size = 10000000}).
On 32-bit systems or if a memory limit for the user running the \bareosDir (normally \user{bareos}) exists
(verify by \command{su - bareos -s /bin/sh -c "ulimit -a"}), this may fail.}
}

\defDirective{Dir}{Job}{File Set}{}{}{%
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, ...).  Only a
single FileSet resource may be specified in any one Job.  For additional
details, see the \ilink{FileSet Resource section}{FileSetResource} of
this chapter.
This directive is required (For versions before 13.3.0 for all Jobtypes
and for versions after that for all Jobtypes but Copy and Migrate).
}

\defDirective{Dir}{Job}{Full Backup Pool}{}{}{%
The Full Backup Pool specifies a Pool to be used for Full backups.
It will override any \linkResourceDirective{Dir}{Job}{Pool} specification during a Full backup.
}

\defDirective{Dir}{Job}{Full Max Runtime}{}{}{%
The time specifies the maximum allowed time that a Full backup job may
run, counted from when the job starts ({\bf not} necessarily the same as when
the job was scheduled).
}

\defDirective{Dir}{Job}{Full Max Wait Time}{}{}{%
This directive has been deprecated in favor of
\linkResourceDirective{Dir}{Job}{Full Max Runtime}.
}

\defDirective{Dir}{Job}{Incremental Backup Pool}{}{}{%
The Incremental Backup Pool specifies a Pool to be used for
Incremental backups.  It will override any \linkResourceDirective{Dir}{Job}{Pool} specification during an
Incremental backup.
}

\defDirective{Dir}{Job}{Incremental Max Runtime}{}{}{%
The time specifies the maximum allowed time that an Incremental backup job may
run, counted from when the job starts, ({\bf not} necessarily the same as when
the job was scheduled).
}

\defDirective{Dir}{Job}{Incremental Max Wait Time}{}{}{%
This directive has been deprecated in favor of
\linkResourceDirective{Dir}{Job}{Incremental Max Runtime}
}

\defDirective{Dir}{Job}{Job Defs}{}{}{%
If a \ilink{Job Defs}{DirectorResourceJobDefs} resource name is specified,
all the values contained in the
named \ilink{Job Defs}{DirectorResourceJobDefs} 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 \ilink{Job Defs}{DirectorResourceJobDefs} resource.
The use of
this directive permits writing much more compact Job resources where the
bulk of the directives are defined in one or more \ilink{Job Defs}{DirectorResourceJobDefs}.
This is particularly useful if you have many similar Jobs but with minor
variations such as different Clients.
To structure the configuration even more, \ilink{Job Defs}{DirectorResourceJobDefs} themselves can also refer to other \ilink{Job Defs}{DirectorResourceJobDefs}.
}

\defDirective{Dir}{Job}{Job To Verify}{}{}{
}

\defDirective{Dir}{Job}{Level}{}{}{%
The Level directive specifies the default Job level to be run.
Each different \linkResourceDirective{Dir}{Job}{Type} (Backup, Restore, Verify, ...) has a different set of Levels
that can be specified.
The Level is normally overridden by a different
value that is specified in the \nameref{DirectorResourceSchedule}.
This directive is not required,
but must be specified either by this  directive
or as an override specified in the \nameref{DirectorResourceSchedule}.

\begin{description}
    \item [Backup] \hfill \\
        For a {\bf Backup} Job, the Level may be one of the  following:

\begin{description}

\item [Full] \hfill \\
\index[dir]{Full}
When the Level is set to Full all files in the FileSet whether or not
they have changed will be backed up.

\item [Incremental] \hfill \\
\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{itemize}
\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 {\bf Max Full Interval}.
\end{itemize}

If all the above conditions do not hold, the Director will upgrade  the
Incremental to a Full save. Otherwise, the Incremental  backup will be
performed as requested.

The File daemon (Client) decides which files to backup for an
Incremental backup by comparing start time of the prior Job (Full,
Differential, or Incremental) against the time each file was last
"modified" (st\_mtime) and the time its attributes were last
"changed"(st\_ctime).  If the file was modified or its attributes
changed on or after this start time, it will then be backed up.

Some virus scanning software may change st\_ctime while
doing the scan.  For example, if the virus scanning program attempts to
reset the access time (st\_atime), which Bareos does not use, it will
cause st\_ctime to change and hence Bareos will backup the file during
an Incremental or Differential backup.  In the case of Sophos virus
scanning, you can prevent it from resetting the access time (st\_atime)
and hence changing st\_ctime by using the \parameter{--no-reset-atime}
option.  For other software, please see their manual.

When Bareos 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 Bareos 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 (st\_mtime) or their attribute
change time (st\_ctime) changed.  As a consequence, those files will
probably not be backed up by an Incremental or Differential backup which
depend solely on these time stamps.  If you move a directory, and wish
it to be properly backed up, it is generally preferable to copy it, then
delete the original.

However, to manage deleted files or directories changes in the
catalog during an Incremental backup you can use \nameref{accuratemode}.
This is quite memory consuming process.

\item [Differential] \hfill \\
\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{itemize}
\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 {\bf Max Full Interval}.
\end{itemize}

If all the above conditions do not hold, the Director will  upgrade the
Differential to a Full save. Otherwise, the  Differential backup will be
performed as requested.

The File daemon (Client) decides which files to backup for a
differential backup by comparing the start time of the prior Full backup
Job against the time each file was last "modified" (st\_mtime) and the
time its attributes were last "changed" (st\_ctime).  If the file was
modified or its attributes were changed on or after this start time, it
will then be backed up.  The start time used is displayed after the {\bf
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.

When Bareos 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 Bareos 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 Bareos.  It is, however, a planned future feature.

As noted above, if you move a directory rather than copy it, the
files in it do not have their modification time (st\_mtime) or
their attribute change time (st\_ctime) changed.  As a
consequence, those files will probably not be backed up by an
Incremental or Differential backup which depend solely on these
time stamps.  If you move a directory, and wish it to be
properly backed up, it is generally preferable to copy it, then
delete the original. Alternatively, you can move the directory, then
use the {\bf 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 \ilink{accurate mode}{accuratemode}.
This is quite memory consuming process. See  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: 1.  It gives
some redundancy since the old backups could be used if the merged backup
cannot be read.  2.  More importantly, it reduces the number of Volumes
that are needed to do a restore effectively eliminating the need to read
all the volumes on which the preceding Incremental and Differential
backups since the last Full are done.

\item [VirtualFull] \hfill \\
\index[dir]{VirtualFull Backup}%
\label{VirtualFull}%
When the Level is set to VirtualFull, a new Full backup is generated from the last existing Full backup and the matching Differential- and Incremental-Backups. 
It matches this according the
\linkResourceDirective{Dir}{Client}{Name} and \linkResourceDirective{Dir}{FileSet}{Name}.
This means, a new Full backup get created without transfering all the data from the client to the backup server again.
The new Full backup will be stored in the pool defined in \linkResourceDirective{Dir}{Pool}{Next Pool}.
%The process of generating a VirtualFull backup is similar to the process described in \nameref{MigrationChapter}.

\warning{Opposite to the other backup levels, VirtualFull may require read and write access to multiple volumes. In most cases you have to make sure, that Bareos does not try to read and write to the same Volume.}

% move volumes from VFull to Full pool
%echo "list volumes pool=VFull" | bconsole | awk -F '|' '{if ($4 ~ /Full|Used|Append/) { gsub(/^[ \t]+/,"",$3); gsub(/[ \t]+$/,"",$3); print "update volume="$3" pool=Full" }}' | bconsole

\end{description}

    \item [Restore] \hfill \\
        For a {\bf Restore} Job, no level needs to be specified.

    \item [Verify] \hfill \\
        For a {\bf Verify} Job, the Level may be one of the  following:

\begin{description}

\item [InitCatalog] \hfill \\
\index[dir]{InitCatalog}%
does a scan of the specified {\bf 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 {\bf Tripwire} like feature using {\bf
Bareos}.  In other words, it allows you to save the state of a set of
files defined by the {\bf 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 {\bf FileSet} that contains the set of system files that
should not change (e.g.  /sbin, /boot, /lib, /bin, ...).  Normally, you
run the {\bf 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 {\bf Verify} {\bf level = Catalog}.  This
compares the results of your {\bf InitCatalog} with the current state of
the files.

\item [Catalog] \hfill \\
\index[dir]{Catalog}%
Compares the current state of the files against the state previously
saved during an {\bf InitCatalog}.  Any discrepancies are reported.  The
items reported are determined by the {\bf verify} options specified on
the {\bf Include} directive in the specified {\bf FileSet} (see the {\bf
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.

\warning{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 [VolumeToCatalog] \hfill \\
\index[dir]{VolumeToCatalog}%
This level causes Bareos to read the file attribute data written to the
Volume from the last backup Job for the job specified on the {\bf VerifyJob}
directive.  The file attribute data are compared to the
values saved in the Catalog database and any differences are reported.
This is similar to the {\bf 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 (MD5 or
SHA1) are compared, the actual file data is not compared (it is not in
the catalog).

VolumeToCatalog jobs need a client to extract the metadata, but this
client does not have to be the original client. We suggest to use the
client on the backup server itself for maximum performance.

\warning{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] \hfill \\
\index[dir]{DiskToCatalog}%
This level causes Bareos 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
{\bf VerifyJob} directive.  This level differs from the {\bf 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 does not identify files that
have been deleted.
\end{description}

\end{description}
}

\defDirective{Dir}{Job}{Max Diff Interval}{}{}{%
The time specifies the maximum allowed age (counting from start time) of
the most recent successful Differential backup that is required in order to run
Incremental backup jobs. If the most recent Differential backup
is older than this interval, Incremental backups will be
upgraded to Differential backups automatically. If this directive is not present,
or specified as 0, then the age of the previous Differential backup is not
considered.
}

\defDirective{Dir}{Job}{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.
}

\defDirective{Dir}{Job}{Max Run Time}{}{}{%
The time specifies the maximum allowed time that a job may run, counted
from when the job starts, ({\bf not} necessarily the same as when the
job was scheduled).

By default, the watchdog thread will kill any Job that has run more
than 6 days.  The maximum watchdog timeout is independent of \configdirective{Max Run Time}
and cannot be changed.
}

\defDirective{Dir}{Job}{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 no limit.
}

\defDirective{Dir}{Job}{Max Virtual Full Interval}{}{14.4.0}{%
The time specifies the maximum allowed age (counting from start time) of
the most recent successful Virtual Full backup that is required in order to run
Incremental or Differential backup jobs. If the most recent Virtual Full backup
is older than this interval, Incremental and Differential backups will be
upgraded to Virtual Full backups automatically. If this directive is not present,
or specified as 0, then the age of the previous Virtual Full backup is not
considered.
}

\defDirective{Dir}{Job}{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, ({\bf not} necessarily the same as when the job was
scheduled).

\begin{figure}[htbp]
  \centering
  \includegraphics[width=13cm]{\idir different_time}
  \caption{Job time control directives}
  \label{fig:differenttime}
\end{figure}
}

\defDirective{Dir}{Job}{Maximum Bandwidth}{}{}{%
The speed parameter specifies the maximum allowed bandwidth that a job may
use.
}

\defDirective{Dir}{Job}{Maximum Concurrent Jobs}{}{}{%
Specifies 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.

For details, see the \nameref{ConcurrentJobs} chapter.
}

\defDirective{Dir}{Job}{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}.
}

\defDirective{Dir}{Job}{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
\ilink{Messages Resource}{MessagesChapter} Chapter of this manual.  This
directive is required.
}

\defDirective{Dir}{Job}{Name}{}{}{%
The Job name. This name can be specified  on the {\bf 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.

}

\defDirective{Dir}{Job}{Next Pool}{}{}{%
A Next Pool override used for Migration/Copy and Virtual Backup Jobs.
}

\defDirective{Dir}{Job}{Plugin Options}{}{}{
}

\defDirective{Dir}{Job}{Pool}{}{}{%
The Pool directive defines the pool of Volumes where your data can be
backed up.  Many Bareos installations will use only the {\bf 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 \nameref{DirectorResourcePool}
of this chapter.  This directive is required.

In case of a Copy or Migration job,
   this setting determines what Pool will be examined
   for finding JobIds to migrate.  The exception to this is when
   \linkResourceDirective{Dir}{Job}{Selection Type} = SQLQuery, 
   and although a Pool directive must still be
   specified, no Pool is used, unless you specifically include it in the
   SQL query.  Note, in any case, the Pool resource defined by the Pool
   directive must contain a \linkResourceDirective{Dir}{Pool}{Next Pool} = ... directive to define the
   Pool to which the data will be migrated.
}

\defDirective{Dir}{Job}{Prefer Mounted Volumes}{}{}{%
If the Prefer Mounted Volumes directive is set to {\bf 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,
... 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 {\bf 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
{\bf 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 Bareos will be forced to mount Volumes from those Pools
on different drives.
}

\defDirective{Dir}{Job}{Prefix Links}{}{}{%
If a {\bf Where} path prefix is specified for a recovery job, apply it
to absolute links as well.  The default is {\bf No}.  When set to {\bf
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.
}

\defDirective{Dir}{Job}{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 Allow Mixed Priority is set.

If you want to run concurrent jobs you should
keep these points in mind:

\begin{itemize}
\item See \nameref{ConcurrentJobs} on how to setup
concurrent jobs.

\item Bareos 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 Bareos 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 Maximum Concurrent Jobs settings would otherwise allow two jobs
to run simultaneously.

\item Suppose that bareos 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{itemize}

If you have several jobs of different priority, it may not best to start
them at exactly the same time, because Bareos must examine them one at a
time.  If by Bareos 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 Bareos will examine the jobs in the
correct order, and that your priority scheme will be respected.
}

\defDirective{Dir}{Job}{Protocol}{}{}{%
The backup protocol to use to run the Job. If not set it will default
to {\bf Native} currently the director understand the following protocols:
\begin{enumerate}
\item Native - The native Bareos protocol
\item NDMP - The NDMP protocol
\end{enumerate}
}

\defDirective{Dir}{Job}{Prune Files}{}{}{%
Normally, pruning of Files from the Catalog is specified on a Client by
Client basis in \linkResourceDirective{Dir}{Client}{Auto Prune}.
If this directive is specified and the value is \argument{yes},
it will override the value specified in the Client resource.
}

\defDirective{Dir}{Job}{Prune Jobs}{}{}{%
Normally, pruning of Jobs from the Catalog is specified on a Client by
Client basis in \linkResourceDirective{Dir}{Client}{Auto Prune}.
If this directive is specified and the value is \argument{yes},
it will override the value specified in the Client resource.
}

\defDirective{Dir}{Job}{Prune Volumes}{}{}{%
Normally, pruning of Volumes from the Catalog is specified on a Pool by
Pool basis in \linkResourceDirective{Dir}{Pool}{Auto Prune} directive.
Note, this is different from File and Job pruning which is done on a
Client by Client basis.  If this directive is specified
and the value is \argument{yes}, it will override the value specified in the
Pool resource.
}

\defDirective{Dir}{Job}{Purge Migration Job}{}{}{%
  This directive may be added to the Migration Job definition in the Director
  configuration file to purge the job migrated at the end of a migration.
}

\defDirective{Dir}{Job}{Regex Where}{}{}{%
This directive applies only to a Restore job and specifies a regex filename
manipulation of all files being restored.  This will use \ilink{File
Relocation}{filerelocation} feature.

For more informations about how use this option, see
\nameref{regexwhere}.
}

\defDirective{Dir}{Job}{Replace}{}{}{%
This directive applies only to a Restore job and specifies what happens
when Bareos wants to restore a file or directory that already exists.
You have the following options for {\bf replace-option}:

\begin{description}

\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, Bareos skips  restoring this file.
\end{description}
}

\defDirective{Dir}{Job}{Rerun Failed Levels}{}{}{%
If this directive is set to {\bf yes} (default no), and Bareos 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 \linkResourceDirective{Dir}{FileSet}{Ignore File Set Changes} directive is not considered
when checking for failed levels, which means that any FileSet change will
trigger a rerun.
}

\defDirective{Dir}{Job}{Reschedule Interval}{}{}{%
If you have specified {\bf Reschedule On Error = yes} and the job
terminates in error, it will be rescheduled after the interval of time
specified by {\bf time-specification}.  See \ilink{the time
specification formats}{Time} in the Configure chapter for details of
time specifications.  If no interval is specified, the job will not be
rescheduled on error.
}

\defDirective{Dir}{Job}{Reschedule On Error}{}{}{%
If this directive is enabled, and the job terminates in error, the job
will be rescheduled as determined by the \linkResourceDirective{Dir}{Job}{Reschedule Interval} and
\linkResourceDirective{Dir}{Job}{Reschedule Times} directives.
If you cancel the job, it 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.
}

\defDirective{Dir}{Job}{Reschedule Times}{}{}{%
This directive specifies the maximum number of times to reschedule the
job.  If it is set to zero (the default) the job will be rescheduled an
indefinite number of times.
}

\defDirective{Dir}{Job}{Run}{}{}{%
\index[dir]{Clone a Job}%
The Run directive (not to be confused with the Run option in a
Schedule) allows you to start other jobs or to clone the current 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 \bcommand{run}{} command from the console. For
example {\bf storage=DDS-4 ...}.  In addition, there are two special
keywords that permit you to clone the current job. They are {\bf level=\%l}
and {\bf 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:

\bconfigInput{config/DirJobRun1.conf}

A cloned job will not start additional clones, so it is not
possible to recurse.

Jobs started by \linkResourceDirective{Dir}{Job}{Run}
are submitted for running before the original job (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.
It evens ignores \linkResourceDirective{Dir}{Job}{Priority}.

If you are trying to prioritize jobs,
you will find it much easier to do using a \linkResourceDirective{Dir}{Job}{Run Script}
resource or a \linkResourceDirective{Dir}{Job}{Run Before Job} directive.
}

\defDirective{Dir}{Job}{Run After Failed Job}{}{}{%
This is a shortcut for the \linkResourceDirective{Dir}{Job}{Run Script} resource,
that runs a command after a failed job.

If the exit code of the program run is non-zero, Bareos will print a
warning message.

\bconfigInput{config/DirJobRunAfterFailedJob1.conf}
}

\defDirective{Dir}{Job}{Run After Job}{}{}{%
This is a shortcut for the \linkResourceDirective{Dir}{Job}{Run Script} resource,
that runs a command after a successful job (without error or without being canceled).

If the exit code of the program run is
non-zero, Bareos will print a warning message.
}

\defDirective{Dir}{Job}{Run Before Job}{}{}{%
This is a shortcut for the \linkResourceDirective{Dir}{Job}{Run Script} resource,
that runs a command before a job.

If the exit code of the program run is non-zero, the current Bareos job will be
canceled.

\bconfigInput{config/DirJobRunBeforeJob1.conf}

is equivalent to:

\bconfigInput{config/DirJobRunBeforeJob2.conf}
%
% 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.
}

\defDirective{Dir}{Job}{Run Script}{}{}{
The 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 {\bf 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}.

\textbf{Console} options are special commands that are sent to the director instead
of the OS. At this time, console command outputs are redirected to log with
the jobid 0.

You can use following console command: \texttt{delete}, \texttt{disable},
\texttt{enable}, \texttt{estimate}, \texttt{list}, \texttt{llist},
\texttt{memory}, \texttt{prune}, \texttt{purge}, \texttt{reload},
\texttt{status}, \texttt{setdebug}, \texttt{show}, \texttt{time},
\texttt{trace}, \texttt{update}, \texttt{version}, \texttt{.client},
\texttt{.jobs}, \texttt{.pool}, \texttt{.storage}.
See \nameref{sec:bconsole} for
more information. You need to specify needed information on command line, nothing
will be prompted. Example:

\bconfigInput{config/DirJobRunScript1.conf}

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:\\

\begin{center}
\begin{tabular}{|p{0.2\textwidth}|p{0.2\textwidth}|p{0.4\textwidth}|}
\hline
Options         & Value  & Information   \\
\hline
\hline
Runs On Success & \textbf{Yes} {\textbar} No & run if JobStatus is successful\\
\hline
Runs On Failure & Yes {\textbar} \textbf{No} & run if JobStatus isn't successful\\
\hline
Runs On Client  & \textbf{Yes} {\textbar} No & run command on client\\
\hline
Runs When       & \textbf{\variable{Never}} {\textbar} \variable{Before} {\textbar} \variable{After} {\textbar} \variable{Always} {\textbar} \textsl{\variable{AfterVSS}} & When to run\\
\hline
Fail Job On Error & \textbf{Yes} {\textbar} No & Fail job if script returns something different from 0\\
\hline
Command          &       &   External command\\
\hline
Console          &       &   Console command\\
\hline
\end{tabular}
 \end{center}

Any output sent by the command to standard output will be included in the
Bareos job report.  The command string must be a valid program name or name
of a shell script.

\warning{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.
Alternatively, it is possible to use \command{sh -c '...'} in the command
definition to force shell interpretation, see example below.}

Before executing the specified command, Bareos
performs character substitution of the following characters:

\label{character substitution}
\footnotesize
\begin{longtable}{ l l }
    \%\% & \% \\
    \%b & Job Bytes \\
    \%B & Job Bytes in human readable format \\
    \%c & Client's name \\
    \%d & Daemon's name (Such as host-dir or host-fd) \\
    \%D & Director's name (Also valid on file daemon) \\
    \%e & Job Exit Status \\
    \%f & Job FileSet (Only on director side) \\
    \%F & Job Files \\
    \%h & Client address \\
    \%i & Job Id \\
    \%j & Unique Job Id \\
    \%l & Job Level \\
    \%n & Job name \\
    \%p & Pool name (Only on director side) \\
    \%P & Daemon PID \\
    \%s & Since time \\
    \%t & Job type (Backup, ...) \\
    \%v & Read Volume name(s) (Only on director side) \\
    \%V & Write Volume name(s) (Only on director side) \\
    \%w & Storage name (Only on director side) \\
    \%x & Spooling enabled? ("yes" or "no") \\
\end{longtable}
\normalsize

Some character substitutions are not available in all situations. The Job Exit
Status code \%e edits the following values:

\index[dir]{Exit Status}
\begin{itemize}
\item OK
\item Error
\item Fatal Error
\item Canceled
\item Differences
\item Unknown term code
\end{itemize}

   Thus if you edit it on a command line, you will need to enclose
   it within some sort of quotes.


You can use these following shortcuts:\\

\begin{tabular}{|l|c|c|c|c|c}
\hline
Keyword & RunsOnSuccess & RunsOnFailure  & FailJobOnError & Runs On Client & RunsWhen  \\
\hline
\hline
\linkResourceDirective{Dir}{Job}{Run Before Job}         &        &       & Yes     & No     & Before \\
\hline
\linkResourceDirective{Dir}{Job}{Run After Job}          &  Yes   &   No  &         & No     & After  \\
\hline
\linkResourceDirective{Dir}{Job}{Run After Failed Job}   &  No    &  Yes  &         & No     & After  \\
\hline
\linkResourceDirective{Dir}{Job}{Client Run Before Job}  &        &       & Yes     & Yes    & Before \\
\hline
\linkResourceDirective{Dir}{Job}{Client Run After Job}   &  Yes   &   No  &         & Yes    & After  \\
\hline
\end{tabular}

Examples:
\bconfigInput{config/DirJobRunScript2.conf}

{\bf Special Windows Considerations}
\index[general]{Windows!Run Script}

You can run scripts just after snapshots initializations with
\textsl{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 .com, .exe or a .bat file.  If you just put the program
name in then Bareos will search using the same rules that cmd.exe uses
(current directory, Bareos bin directory, and PATH).  It will even try the
different extensions in the same order as cmd.exe.
The command can be anything that cmd.exe or command.com will recognize
as an executable file.

However, if you have slashes in the program name then Bareos 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 Bareos.

The System \%Path\% will be searched for the command.  (under the
environment variable dialog you have have both System Environment and
User Environment, we believe that only the System environment will be
available to bareos-fd, if it is running as a service.)

System environment variables can be referenced with \%var\% and
used as either part of the command name or arguments.

So if you have a script in the Bareos\\bin directory then the following lines
should work fine:

% \footnotesize
%\begin{bconfig}{Windows systemstate Run Script}^^J
%         Client Run Before Job = "systemstate"^^J
% or^^J
%         Client Run Before Job = "systemstate.bat"^^J
% or^^J
%         ClientRunBeforeJob = "\\"C:/Program Files/Bareos/systemstate.bat\\""^^J
%\end{bconfig}
% \normalsize

% \begin{bconfig}{Windows systemstate Run Script}^^J
%         Client Run Before Job = "systemstate"^^J
% or^^J
%         Client Run Before Job = "systemstate.bat"^^J
% or^^J
%         Client Run Before Job = "\\"C:/Program Files/Bareos/systemstate.bat\\""^^J
% \end{bconfig}
\bconfigInput{config/DirJobRunScript3.conf}

% \begin{itemize}
%     \item \path|Client Run Before Job = "systemstate"|
% or
%     \item \path|Client Run Before Job = "systemstate.bat"|
% or
%     \item \path|ClientRunBeforeJob = "\\"C:/Program Files/Bareos/systemstate.bat\\""|
% \end{itemize}

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.

% \footnotesize
% \begin{verbatim}
% ClientRunBeforeJob = "\"C:/Program Files/Software
%      Vendor/Executable\" /arg1 /arg2 \"foo bar\""
% \end{verbatim}
% \normalsize

The special characters \configCharsToQuote
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{enumerate}
\item You might want the ClientRunBeforeJob directive to specify a .bat
      file which runs the actual client-side commands, rather than trying
      to run (for example) regedit /e directly.
\item The batch file should explicitly 'exit 0' on successful completion.
\item The path to the batch file should be specified in Unix form:

    \configline{Client Run Before Job = "c:/bareos/bin/systemstate.bat"}

    rather than DOS/Windows form:

    INCORRECT: \configline{Client Run Before Job = "c:\bareos\bin\systemstate.bat"}
\end{enumerate}

For Win32, please note that there are certain limitations:

\configline{Client Run Before Job = "C:/Program Files/Bareos/bin/pre-exec.bat"}

Lines like the above do not work because there are limitations of
cmd.exe that is used to execute the command.
Bareos prefixes the string you supply with \command{cmd.exe /c}.  To test that
your command works you should type \command{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 .conf 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 /c option.

If /C or /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{enumerate}
\item
If all of the following conditions are met, then quote characters
on the command line are preserved:
\begin{itemize}
\item no /S switch.
\item exactly two quote characters.
\item no special characters between the two quote characters,
where special is one of: \configCharsToQuote
\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{itemize}

\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{enumerate}

% 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:
%
% \footnotesize
% \begin{verbatim}
%  #!/bin/sh
%  # ===== backupdb.sh
%  DIR=/u01/mercuryd
%
%  mkfifo $DIR/dbpipe
%  db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING &
%  sleep 1
% \end{verbatim}
% \normalsize
%
%The following line in the Job resource in the bareos-dir.conf file:
% \footnotesize
% \begin{verbatim}
%  Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t'
% '%l'\""
% \end{verbatim}
% \normalsize
%
% When the job is run, you will get messages from the output of the script
% stating that the backup has started. Even though the command being run is
% backgrounded with \&, the job will block until the "db2 BACKUP DATABASE"
% command, thus the backup stalls.
%
% To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to
% the following:
%
% % \footnotesize
% \begin{verbatim}
%  db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log
% 2>&1 < /dev/null &
% \end{verbatim}
% \normalsize
%
% It is important to redirect the input and outputs of a backgrounded command to
% /dev/null to prevent the script from blocking.
}

\defDirective{Dir}{Job}{Save File History}{}{14.2.0}{%
\index[general]{NDMP!File History}%
Allow disabling storing the file history, as this causes problems problems with some implementations of NDMP (out-of-order metadata).

With \linkResourceDirective{Dir}{Job}{File History Size} the maximum number of files and directories inside a NDMP job can be configured.

\warning{The File History is required to do a single file restore from NDMP backups. With this disabled, only full restores are possible.}
}

\defDirective{Dir}{Job}{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, ...) 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 {\bf Run} directives, which allow you to run the Job at
many different times, and each {\bf 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 \nameref{DirectorResourceSchedule}.
}

\defDirective{Dir}{Job}{SD Plugin Options}{}{}{%
These settings are plugin specific, see \nameref{sdPlugins}.
}

\defDirective{Dir}{Job}{Selection Pattern}{}{}{%
Selection Patterns is only used for Copy and Migration jobs, see \nameref{MigrationChapter}.
The interpretation of its value depends on the selected \linkResourceDirective{Dir}{Job}{Selection Type}.

  For the OldestVolume and SmallestVolume, this
  Selection pattern is not used (ignored).

  For the Client, Volume, and Job
  keywords, this pattern must be a valid regular expression that will filter
  the appropriate item names found in the Pool.

  For the SQLQuery keyword, this pattern must be a valid \command{SELECT} SQL statement
  that returns JobIds.
}

\defDirective{Dir}{Job}{Selection Type}{}{}{%
Selection Type is only used for Copy and Migration jobs, see \nameref{MigrationChapter}.
It determines how a migration job
  will go about selecting what JobIds to migrate. In most cases, it is
  used in conjunction with a \linkResourceDirective{Dir}{Job}{Selection Pattern}
  to give you fine
  control over exactly what JobIds are selected.
  The possible values are:
  \begin{description}
  \item [SmallestVolume] This selection keyword selects the volume with the
        fewest bytes from the Pool to be migrated.  The Pool to be migrated
        is the Pool defined in the Migration Job resource.  The migration
        control job will then start and run one migration backup job for
        each of the Jobs found on this Volume.  The Selection Pattern, if
        specified, is not used.

  \item [OldestVolume] This selection keyword selects the volume with the
        oldest last write time in the Pool to be migrated.  The Pool to be
        migrated is the Pool defined in the Migration Job resource.  The
        migration control job will then start and run one migration backup
        job for each of the Jobs found on this Volume.  The Selection
        Pattern, if specified, is not used.

  \item [Client] The Client selection type, first selects all the Clients
        that have been backed up in the Pool specified by the Migration
        Job resource, then it applies the \linkResourceDirective{Dir}{Job}{Selection Pattern}
        as a regular expression to the list of Client names, giving
        a filtered Client name list.  All jobs that were backed up for those
        filtered (regexed) Clients will be migrated.
        The migration control job will then start and run one migration
        backup job for each of the JobIds found for those filtered Clients.

  \item [Volume] The Volume selection type, first selects all the Volumes
        that have been backed up in the Pool specified by the Migration
        Job resource, then it applies the \linkResourceDirective{Dir}{Job}{Selection Pattern}
        as a regular expression to the list of Volume names, giving
        a filtered Volume list.  All JobIds that were backed up for those
        filtered (regexed) Volumes will be migrated.
        The migration control job will then start and run one migration
        backup job for each of the JobIds found on those filtered Volumes.

  \item [Job] The Job selection type, first selects all the Jobs (as
        defined on the \linkResourceDirective{Dir}{Job}{Name} directive in a Job resource)
        that have been backed up in the Pool specified by the Migration
        Job resource, then it applies the \linkResourceDirective{Dir}{Job}{Selection Pattern}
        as a regular expression to the list of Job names, giving
        a filtered Job name list.  All JobIds that were run for those
        filtered (regexed) Job names will be migrated.  Note, for a given
        Job named, they can be many jobs (JobIds) that ran.
        The migration control job will then start and run one migration
        backup job for each of the Jobs found.

  \item [SQLQuery] The SQLQuery selection type, used the 
        \linkResourceDirective{Dir}{Job}{Selection Pattern}
        as an SQL query to obtain the JobIds to be migrated.
        The Selection Pattern must be a valid SELECT SQL statement for your
        SQL engine, and it must return the JobId as the first field
        of the SELECT.

  \item [PoolOccupancy] This selection type will cause the Migration job
        to compute the total size of the specified pool for all Media Types
        combined. If it exceeds the \linkResourceDirective{Dir}{Pool}{Migration High Bytes} 
        defined in
        the Pool, the Migration job will migrate all JobIds beginning with
        the oldest Volume in the pool (determined by Last Write time) until
        the Pool bytes drop below the \linkResourceDirective{Dir}{Pool}{Migration Low Bytes} 
        defined in the
        Pool. This calculation should be consider rather approximative because
        it is made once by the Migration job before migration is begun, and
        thus does not take into account additional data written into the Pool
        during the migration.  In addition, the calculation of the total Pool
        byte size is based on the Volume bytes saved in the Volume (Media) database
        entries. The bytes calculate for Migration is based on the value stored
        in the Job records of the Jobs to be migrated. These do not include the
        Storage daemon overhead as is in the total Pool size. As a consequence,
        normally, the migration will migrate more bytes than strictly necessary.

  \item [PoolTime] The PoolTime selection type will cause the Migration job to
        look at the time each JobId has been in the Pool since the job ended.
        All Jobs in the Pool longer than the time specified on 
        \linkResourceDirective{Dir}{Pool}{Migration Time}
        directive in the Pool resource will be migrated.

  \item [PoolUncopiedJobs] This selection which copies all jobs from a pool
        to an other pool which were not copied before is available only for copy Jobs.

  \end{description}

}

\defDirective{Dir}{Job}{Spool Attributes}{}{}{%
Is Spool Attributes is disabled, 
the File attributes are
sent by the Storage daemon to the Director as they are stored on tape.
However, if you want to avoid the possibility that database updates will
slow down writing to the tape, you may want to set the value to \parameter{yes}, 
in which case 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.

NOTE: When \linkResourceDirective{Dir}{Job}{Spool Data} is set to yes, Spool Attributes is also
automatically set to yes.

For details, see \nameref{sec:spooling}.
}

\defDirective{Dir}{Job}{Spool Data}{}{}{%
If this directive is set  to \parameter{yes}, 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 data 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, \linkResourceDirective{Dir}{Job}{Spool Attributes} is also
automatically set to yes.

For details, see \nameref{sec:spooling}.
}

\defDirective{Dir}{Job}{Spool Size}{}{}{%
This specifies the maximum spool size for this job.
The default is taken from \linkResourceDirective{Sd}{Device}{Maximum Spool Size} limit.
}

\defDirective{Dir}{Job}{Storage}{}{}{%
The Storage directive defines the name of the storage services where you
want to backup the FileSet data.  For additional details, see the
\nameref{DirectorResourceStorage} 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.
}

\defDirective{Dir}{Job}{Strip Prefix}{}{}{
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
\ilink{File Relocation}{filerelocation} feature.

Using \texttt{Strip Prefix=/etc}, \texttt{/etc/passwd} will be restored to
\texttt{/passwd}

Under Windows, if you want to restore \texttt{c:/files} to \texttt{d:/files},
you can use:

\bconfigInput{config/DirJobStripPrefix1.conf}
}

\defDirective{Dir}{Job}{Type}{}{}{%
The \configdirective{Type} directive specifies the Job type, which is one of the following:

\begin{description}

\item [Backup] \hfill \\
\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] \hfill \\
\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.

{\bf 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 {\bf restore} command
in the console.


\item [Verify] \hfill \\
\index[dir]{Verify}
Run a verify Job. In general, {\bf 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 {\bf verify} as a sort of tripwire  intrusion detection.

\item [Admin] \hfill \\
\index[dir]{Admin}
Run an admin Job. An {\bf Admin} job can  be used to periodically run catalog
pruning, if you  do not want to do it at the end of each {\bf Backup}  Job.
Although an Admin job is recorded in the  catalog, very little data is saved.

\item [Migrate]
   defines the job that is run as being a
   Migration Job.  A Migration Job is a sort of control job and does not have
   any Files associated with it, and in that sense they are more or less like
   an Admin job.  Migration jobs simply check to see if there is anything to
   Migrate then possibly start and control new Backup jobs to migrate the data
   from the specified Pool to another Pool.  Note, any original JobId that
   is migrated will be marked as having been migrated, and the original
   JobId can nolonger be used for restores; all restores will be done from
   the new migrated Job.

\item [Copy]
   defines the job that is run as being a
   Copy Job.  A Copy Job is a sort of control job and does not have
   any Files associated with it, and in that sense they are more or less like
   an Admin job.  Copy jobs simply check to see if there is anything to
   Copy then possibly start and control new Backup jobs to copy the data
   from the specified Pool to another Pool.  Note that when a copy is
   made, the original JobIds are left unchanged. The new copies can not
   be used for restoration unless you specifically choose them by JobId.
   If you subsequently delete a JobId that has a copy, the copy will be
   automatically upgraded to a Backup rather than a Copy, and it will
   subsequently be used for restoration.

\item [Consolidate]
    is used to consolidate Always Incremental Backups jobs, see \nameref{sec:alwaysincremental}.
    It has been introduced in Bareos \sinceVersion{dir}{Job Type Consolidate}{16.2.4}.
\end{description}

Within a particular Job Type, there are also Levels,
see \linkResourceDirective{Dir}{Job}{Level}.
}

\defDirective{Dir}{Job}{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 verify command.  If you specify a {\bf Verify Job} Bareos
will find the last job with that name that ran.  This permits you to run
all your backups, then run Verify jobs on those that you wish to be
verified (most often a {\bf VolumeToCatalog}) so that the tape just
written is re-read.
}

\defDirective{Dir}{Job}{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 {\bf
Where} is not specified or is set to backslash ({\bf /}), the files will
be restored to their original location.  By default, we have set {\bf
Where} in the example configuration files to be {\bf
/tmp/bareos-restores}.  This is to prevent accidental overwriting of
your files.

\warning{To use Where on NDMP backups, please read \nameref{sec:ndmp-where}.}
}

\defDirective{Dir}{Job}{Write Bootstrap}{}{}{%
The {\bf writebootstrap} directive specifies a file name where Bareos
will write a {\bf bootstrap} file for each Backup job run.  This
directive applies only to Backup Jobs.  If the Backup job is a Full
save, Bareos will erase any current contents of the specified file
before writing the bootstrap records.  If the Job is an Incremental
or Differential
save, Bareos 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 {\bf bootstrap-file-specification} begins with a vertical bar
(\textbar), Bareos 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.

Before opening the file or executing the
specified command, Bareos performs
\ilink{character substitution}{character substitution} like in RunScript
directive. To automatically manage your bootstrap files, you can use
this in your {\bf JobDefs} resources:
% \begin{bconfig}{Write Bootstrap Example}^^J
% Job Defs \{^^J
% \ \ Write Bootstrap = "\%c_\%n.bsr"^^J
% \ \ ...^^J
% \}^^J
% \end{bconfig}
\bconfigInput{config/DirJobWriteBootstrap1.conf}

For more details on using this file, please see chapter \nameref{BootstrapChapter}.
}

\defDirective{Dir}{Job}{Write Part After Job}{}{}{
}

\defDirective{Dir}{Job}{Write Verify List}{}{}{
}