thanks.tex doesn't include the French translator yet, if I'm not mistaken

[bacula/docs] / docs / manual-fr / dirdconf.tex

%%
%%

\section*{Configurer le Director}
\label{_ChapterStart40}
\index[general]{Director!Configurer le }
\index[general]{Configurer le Director }
\addcontentsline{toc}{section}{Configurer le Director}

Parmi tous les fichiers de configuration requis pour ex\'ecuter {\bf Bacula},
celui du Director est le plus compliqu\'e, et c'est celui que vous modifierez
le plus souvent, en ajoutant des clients ou en modifiant les FileSets. 

Pour une discussion g\'en\'erale concernant les fichiers et ressources ainsi
que les types de donn\'ees reconnus par {\bf Bacula}, veuillez consulter le
chapitre 
\ilink{Configuration}{_ChapterStart16} de ce manuel. 

\subsection*{Les types de ressources du Director}
\index[general]{Les types de ressources du Director }
\index[general]{Director!Les types de ressources du }
\addcontentsline{toc}{subsection}{Les types de ressources du Director}

Les types de ressources du Director sont : 

Job, JobDefs, Client, Storage, Catalog, Schedule, FileSet, Pool, Director, et
Messages. Nous les pr\'esentons ici dans l'ordre le plus logique (relativement
au fichier de configuration du Director) : 

\begin{itemize}
\item 
   \ilink{Director}{DirectorResource4} -- Pour d\'efinir le nom du
   Director et son  mot de passe pour l'authentification du programme Console. Il
ne doit y avoir qu'une seule  d\'efinition de ressource Director dans le
fichier de configuration.  Si vouc avez soit {\bf /dev/random} soit {\bf bc}
sur votre machine, Bacula g\'en\`erera  un mot de passe al\'eatoire lors du
processus de configuration, sinon, il sera laiss\'e blanc. 
\item 
   \ilink{Job}{JobResource} -- Pour d\'efinir les Jobs de types
   sauvegarde et restauration,  et pour lier les ressources Client, FileSet et
Schedules \`a utiliser conjointement pour chaque Job. 
\item 
   \ilink{JobDefs}{JobDefsResource} -- Ressource optionnelle pour
   fournir des valeurs par d\'efaut  pour les ressources Job. 
\item 
   \ilink{Schedule}{ScheduleResource} -- Pour d\'efinir le moment
   o\`u un Job doit \^etre lanc\'e  automatiquement par le {\it scheduler}
interne de Bacula. 
\item 
   \ilink{FileSet}{FileSetResource} -- Pour d\'efinir l'ensemble des
   fichiers \`a sauvegarder  pour chaque client. 
\item 
   \ilink{Client}{ClientResource2} -- Pour d\'efinir quel Client est
   \`a sauvegarder. 
\item 
   \ilink{Storage}{StorageResource2} -- Pour d\'efinir sur quel
   p\'eriph\'erique physique les  volumes seront mont\'es.  
\item 
   \ilink{Pool}{PoolResource} -- Pour d\'efinir quel pool de volumes
   peut \^etre  utilis\'e pour un Job donn\'e 
\item 
   \ilink{Catalog}{CatalogResource} -- Pour d\'efinir la base de
   donn\'ees o\`u conserver les listes  des fichiers sauvegard\'es et des volumes
o\`u ils ont \'et\'e sauvegard\'es.  
\item 
   \ilink{Messages}{_ChapterStart15} -- Pour d\'efinir les
   destinataires (ou les fichiers de logs) des messages d'erreur et 
d'information.  
\end{itemize}

\section*{La ressource Director}
\label{DirectorResource4}
\index[general]{Director!La ressource }
\index[general]{La ressource Director }
\addcontentsline{toc}{section}{La ressource Director}

La ressource Director d\'efinit les attributs du Director ex\'ecut\'e sur le
r\'eseau. Dans l'impl\'ementation actuelle, il n'y a qu'une ressource
Director, mais la r\'ealisation finale contiendra plusieurs Directors pour
maintenir la redondance de la base des indexes et m\'edia. 

\begin{description}

\item [Director]
   \index[dir]{Director }
   D\'ebut de la ressource Director. Une ressource Director et une seule doit
\^etre d\'efinie. 

\item [Name = \lt{}name\gt{}]
   \index[dir]{Name  }
   Le nom du Director utilis\'e par l'administrateur syst\`eme. Cette directive
est requise  

\item [Description = \lt{}text\gt{}]
   \index[dir]{Description  }
   Le champ texte contient une description du Director qui sera affich\'ee  dans
l'interface graphique. Cette directive est optionnelle.  

\item [Password = \lt{}UA-password\gt{}]
   \index[dir]{Password  }
   Sp\'ecifie le mot de passe qui doit \^etre fourni par la Console Bacula par
d\'efaut  pour \^etre autoris\'ee. Le m\^eme mot de passe doit appara{\^\i}tre
dans la ressource {\bf Director} du fichier de  configuration de la console.
Pour plus de s\'ecurit\'e, le mot de passe ne transite jamais sur le r\'eseau,
l'authentification se fait via un \'echange de type {\it challenge-response}
d'un {\it hash code} cr\'e\'e avec le mot  de passe. Cette directive est
requise. Si vous disposez de {\bf /dev/random} ou {\bf bc} sur votre machine,
Bacula  g\'en\`erera un mot de passe al\'eatoire lors du processus
d'installation, sinon il sera laiss\'e blanc et vous devrez en d\'efinir  un
manuellement.  

\item [Messages = \lt{}Messages-resource-name\gt{}]
   \index[console]{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.  

\item [Working Directory = \lt{}Directory\gt{}]
   \index[console]{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.  Standard shell expansion of the {\bf
Directory}  is done when the configuration file is read so that values such 
as {\bf \$HOME} will be properly expanded. This directive is required.  

\item [Pid Directory = \lt{}Directory\gt{}]
   \index[fd]{Pid Directory  }
   This directive  is mandatory and specifies a directory in which the Director 
may put its process Id file files. The process Id file is used to  shutdown
Bacula and to prevent multiple copies of  Bacula from running simultaneously. 
Standard shell expansion of the {\bf Directory}  is done when the
configuration file is read so that values such  as {\bf \$HOME} will be
properly expanded.  

Typically on Linux systems, you will set this to:  {\bf /var/run}. If you are
not installing Bacula in the  system directories, you can use the {\bf Working
Directory} as  defined above.  This directive is required.  

\item [QueryFile = \lt{}Path\gt{}]
   \index[dir]{QueryFile  }
   This directive  is mandatory and specifies a directory and file in which the
Director  can find the canned SQL statements for the {\bf Query} command of 
the Console. Standard shell expansion of the {\bf Path} is done  when the
configuration file is read so that values such as  {\bf \$HOME} will be
properly expanded. This directive is required.  
\label{DirMaxConJobs}

\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
   \index[fd]{Maximum Concurrent Jobs  }
   where \lt{}number\gt{}  is the maximum number of total Director Jobs that
should run  concurrently. The default is set to 1, but you may set it to a 
larger number.  

Please  note that the Volume format becomes much more complicated with 
multiple simultaneous jobs, consequently, restores can take much  longer if
Bacula must sort through interleaved volume blocks from  multiple simultaneous
jobs. This can be avoided by having each  simultaneously running job write to
a different volume or  by using data spooling, which will first spool the data
to disk simultaneously, then write each spool file to the  volume in
sequence.  

There may also still be some cases where directives such as  {\bf Maximum
Volume Jobs} are not properly synchronized with  multiple simultaneous jobs
(subtle timing issues can arise),  so careful testing is recommended. 

At the current time,  there is no configuration parameter set or limit the
number  console connections. A maximum of five simultaneous console 
connections are permitted.  

For more details on getting concurrent jobs to run, please  see 
\ilink{Running Concurrent Jobs}{ConcurrentJobs} in the Tips chapter
of this manual.  

\item [FD Connect Timeout = \lt{}time\gt{}]
   \index[console]{FD Connect Timeout  }
   where {\bf 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 30 minutes. 

\item [SD Connect Timeout = \lt{}time\gt{}]
   \index[console]{SD Connect Timeout  }
   where {\bf 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 30 minutes. 

\item [DirAddresses = \lt{}IP-address-specification\gt{}]
   \index[console]{DirAddresses  }
   Specify the ports and addresses on which the Director daemon will  listen for
Bacula Console connections. Probably the simplest way  to explain is to show
an example: 

\footnotesize
\begin{verbatim}
 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{verbatim}
\normalsize

where ip, ip4, ip6, addr, and port are all keywords. Note, that  the address
can be specified as either a dotted quadruple, or  IPv6 colon notation, or as
a symbolic name (only in the ip specification).  Also, port can be specified
as a number or as the mnemonic value from  the /etc/services file.  If a port
is not specified, the default will be used. If an ip  section is specified,
the resolution can be made either by IPv4 or  IPv6. If ip4 is specified, then
only IPv4 resolutions will be permitted,  and likewise with ip6. 

\item [DIRport = \lt{}port-number\gt{}]
   \index[console]{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 9101, so  normally this directive need not be specified.  This
directive is not needed if you specify DirAddresses. 

\item [DirAddress = \lt{}IP-Address\gt{}]
   \index[console]{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 {\bf
IP-Address},  which is either a domain name or an 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 is not needed if you
specify a DirAddresses  (not plural). 
\end{description}

The following is an example of a valid Director resource definition: 

\footnotesize
\begin{verbatim}
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{verbatim}
\normalsize

\section*{The Job Resource}
\label{JobResource}
\index[general]{Resource!Job }
\index[general]{Job Resource }
\addcontentsline{toc}{section}{Job Resource}

The Job resource defines a Job (Backup, Restore, ...) that Bacula must
perform. Each Job resource definition contains the names of the Clients and
their FileSets to backup or restore, 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. 

Only a single type ({\bf Backup}, {\bf Restore}, ...) can be specified for any
job. If you want to backup multiple FileSets on the same Client or multiple
Clients, you must define a Job for each one. 

\begin{description}

\item [Job]
   \index[console]{Job }
   Start of the Job resource. At least one Job  resource is required. 

\item [Name = \lt{}name\gt{}]
   \index[console]{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. 

\item [Type = \lt{}job-type\gt{}]
   \index[console]{Type  }
   The {\bf Type} directive specifies  the Job type, which may be one of the
following: {\bf Backup},  {\bf Restore}, {\bf Verify}, or {\bf Admin}. This
directive  is required. Within a particular Job Type, there are also Levels 
as discussed in the next item.  

\begin{description}

\item [Backup]
   \index[console]{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[console]{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.  

\item [Verify]
   \index[console]{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]
   \index[fd]{Admin }
   Run a 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. 
\end{description}

\label{Level}

\item {\bf Level = \lt{}job-level\gt{}}
   \index[fd]{Level  }
   The Level directive specifies  the default Job level to be run. Each different
Job Type (Backup, Restore, ...) has a different set of Levels  that can be
specified. The Level is normally overridden  by a different value that is
specified in the {\bf Schedule}  resource. This directive is not required, but
must be specified either  by a {\bf Level} directive or as a override
specified in the  {\bf Schedule} resource.  

For a {\bf Backup} Job, the Level may be one of the  following:  

\begin{description}

\item [Full]
   \index[fd]{Full }
   is all files in the FileSet whether or not they  have changed.  

\item [Incremental]
   \index[fd]{Incremental }
   is all files that have changed since the  last successful backup of the
specified FileSet. If the  Director cannot find a previous Full backup then
the job will be  upgraded into a Full backup. When the Director looks for a 
``suitable'' 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).  
   \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.  

Please note that some  virus scanning software may change st\_ctime while
doing the  scan. For exaple, if the the virus scanning program attempts  to
reset the access time (st\_atime), which Bacula does not use,  it will cause
st\_ctime to change and hence Bacula will backup  the file during an
Incremental or Differential backup. In the  case of Sophos virus scanning, you
can prevent it from  resetting the access time (st\_atime) and hence changing 
st\_ctime by using the {\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.  However, to remove deleted
files from the catalog during  a Incremental backup is quite a time consuming
process  and not currently implemented in Bacula. 

\item [Differential]
   \index[fd]{Differential }
   is all files that have changed since the  last successful Full backup of the
specified FileSet.  If the Director cannot find a previous Full backup or a 
suitable Full backup, then the Differential job will be  upgraded into a Full
backup. When the Director looks for  a ``suitable'' 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).  
   \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 attributs
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. As with the 
Incremental option, you shouldensure 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 adjstments to the time between the server and the  client
so that the times Bacula uses are synchronized.  

When Bacula does an 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. 
\end{description}

For a {\bf Restore} Job, no level need be specified.  

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

\begin{description}

\item [InitCatalog]
   \index[fd]{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 Bacula}. 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]
   \index[fd]{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.  

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 [VolumeToCatalog]
   \index[fd]{VolumeToCatalog }
   This level causes Bacula to read  the file attribute data written to the
Volume from the last Job.  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 Catalog} 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). 

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[fd]{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 {\bf VerifyJob}
directive. This level differs from the  {\bf Catalog} level described above by
the fact that it  compare not 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{description}

\item {\bf Verify Job = \lt{}Job-Resource-Name\gt{}}
   \index[fd]{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} Bacula 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. 

\item {\bf JobDefs = \lt{}JobDefs-Resource-Name\gt{}}
   \index[fd]{JobDefs  }
   If a JobDefs-Resource-Name  is specified, all the values contained in the
named 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 JobDefs 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 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
bacula-dir.conf  file. 

\item {\bf Bootstrap = \lt{}bootstrap-file\gt{}}
   \index[dir]{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 {\bf Restore} 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 of the {\bf bootstrap} file, please see  
\ilink{Restoring Files with the Bootstrap File}{_ChapterStart43} 
chapter of this manual. 

\item {\bf 
   \label{writebootstrap}
   Write Bootstrap =  \lt{}bootstrap-file-specification\gt{}}
\index[fd]{a name }
The  {\bf writebootstrap} directive specifies a file name where  Bacula will
write a {\bf bootstrap} file for each Backup job  run. Thus this directive
applies only to 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 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.  

If the {\bf bootstrap-file-specification} begins with a  vertical bar (|),
Bacula will use the specification as the  name of a program to which it will
pipe the bootstrap record.  It could for example be a shell script that emails
you the  bootstrap record. 

For more details on using this file,  please see the chapter entitled 
\ilink{The Bootstrap File}{_ChapterStart43} of this manual. 

\item {\bf Client = \lt{}client-resource-name\gt{}}
   \index[fd]{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  
\ilink{Client Resource section}{ClientResource2} of this chapter.
This directive is required. 

\item {\bf FileSet = \lt{}FileSet-resource-name\gt{}}
   \index[fd]{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, ...).  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. 

\item {\bf Messages = \lt{}messages-resource-name\gt{}}
   \index[dir]{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}{_ChapterStart15} Chapter of this 
manual. This directive is required. 

\item {\bf Pool = \lt{}pool-resource-name\gt{}}
   \index[dir]{Pool  }
   The Pool directive defines  the pool of Volumes where your data can be backed
up. Many Bacula  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 
\ilink{Pool Resource section}{PoolResource} of this chapter. This
resource is required. 

\item {\bf Full Backup Pool = \lt{}pool-resource-name\gt{}  }
   \index[dir]{Full Backup Pool  }
   The {\it Full Backup Pool} specifies a Pool to be used for  Full backups. It
will override any Pool specification during a  Full backup. This resource is
optional. 

\item {\bf Differential Backup Pool = \lt{}pool-resource-name\gt{}  }
   \index[dir]{Differential Backup Pool  }
   The {\it Differential Backup Pool} specifies a Pool to be used for 
Differential backups. It will override any Pool specification during a 
Differentia backup. This resource is optional. 

\item {\bf Incremental Backup Pool = \lt{}pool-resource-name\gt{}  }
   \index[dir]{Incremental Backup Pool  }
   The {\it Incremental Backup Pool} specifies a Pool to be used for  Incremental
backups. It will override any Pool specification during a  Incremental backup.
This resource is optional. 

\item {\bf Schedule = \lt{}schedule-name\gt{}}
   \index[dir]{Schedule  }
   The Schedule directive defines  what schedule is to be used for the Job. The
schedule 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. For additional 
details, see the 
\ilink{Schedule Resource Chapter}{ScheduleResource} of this
manual.  If a Schedule resource is specified, the job will be run according to
the schedule specified. If no Schedule resource is specified for the  Job,
the job must be manually started 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. 

\item {\bf Storage = \lt{}storage-resource-name\gt{}}
   \index[dir]{Storage  }
   The Storage directive  defines the name of the storage services where you want
to backup  the FileSet data. For additional details, see the 
\ilink{Storage Resource Chapter}{StorageResource2} of this manual.
 This directive is required.  

\item {\bf Max Start Delay = \lt{}time\gt{}}
   \index[sd]{Max Start Delay  }
   The time specifies  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 0 which indicates  no limit. 

\item {\bf Max Run Time = \lt{}time\gt{}}
   \index[sd]{Max Run Time  }
   The time specifies  maximum allowed time that a job may run, counted from the
when  the job starts ({\bf not} necessarily the same as when the job  was
scheduled). This directive is implemented only in version 1.33  and later. 

\item {\bf Max Wait Time = \lt{}time\gt{}}
   \index[sd]{Max Wait Time  }
   The time specifies  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).
This directive is implemented only in version 1.33  and later. Note, the
implementation is not yet complete, so  this directive does not yet work
correctly. 

\item {\bf Prune Jobs = \lt{}yes|no\gt{}}
   \index[fd]{Prune Jobs  }
   Normally, pruning of Jobs  from the Catalog is specified on a Client by Client
basis in the  Client resource with the {\bf AutoPrune} directive. If this 
directive is specified (not normally) and the value is {\bf yes}, it  will
override the value specified in the Client resource.  The default is {\bf no}.


\item {\bf Prune Files = \lt{}yes|no\gt{}}
   \index[fd]{Prune Files  }
   Normally, pruning of Files  from the Catalog is specified on a Client by
Client basis in the  Client resource with the {\bf AutoPrune} directive. If
this  directive is specified (not normally) and the value is {\bf yes}, it 
will override the value specified in the Client resource.  The default is {\bf
no}. 

\item {\bf Prune Volumes = \lt{}yes|no\gt{}}
   \index[fd]{Prune Volumes  }
   Normally, pruning of Volumes  from the Catalog is specified on a Client by
Client basis in the  Client resource with the {\bf AutoPrune} directive. If
this  directive is specified (not normally) and the value is {\bf yes}, it 
will override the value specified in the Client resource.  The default is {\bf
no}. 

\item {\bf Run Before Job = \lt{}command\gt{}}
   \index[fd]{Run Before Job  }
   The specified {\bf command}  is run as an external program prior to running
the current Job. Any  output sent by the job 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. 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. In addition, the command string  is parsed then
feed to the execvp() function, which means that the  path will be searched to
execute your specified command, but there  is no shell interpretation, as a
consequence, if you  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:  

\footnotesize
\begin{verbatim}
    %% = %
    %c = Client's name
    %d = Director's name
    %i = JobId
    %e = Job Exit Status
    %j = Unique Job name
    %l = Job Level
    %n = Job name
    %t = Job type
    %v = Volume name
    
\end{verbatim}
\normalsize

As of version 1.30, Bacula checks the exit status of the RunBeforeJob 
program. If it is non-zero, the job will be error terminated.  Lutz Kittler
has pointed out that this 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
insert on Wednesday before leaving will  be used.  

\item {\bf Run After Job = \lt{}command\gt{}}
   \index[fd]{Run After Job  }
   The specified {\bf command}  is run as an external program after the current
job terminates.  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, the current  Bacula job will terminate in error.  Before
submitting the specified command to the operating system,  Bacula performs
character substitution as described above  for the {\bf Run Before Job}
directive.  

An example of the use of this command is given in the  
\ilink{Tips Chapter}{JobNotification} of this manual.  As of version
1.30, Bacula checks the exit status of the RunAfter  program. If it is
non-zero, the job will be terminated in error.  

\item {\bf Client Run Before Job = \lt{}command\gt{}}
   \index[fd]{Client Run Before Job  }
   This command  is the same as {\bf Run Before Job} except that it is  run on
the client machine. The same restrictions apply to  Unix systems as noted
above for the {\bf Run Before Job}. In  addition, for a Windows client on
version 1.33 and above, please  take careful note that you must ensure a
correct path to your  script, and the script or program can be a .com, .exe or
a .bat  file. However, if you specify a path, you must also specify  the full
extension. Unix like commands will not work unless you  have installed and
properly configured Cygwin in addition to  and separately from Bacula.  

{\bf Special Windows Considerations}
The command can be anything that cmd.exe or command.com will  recognize as a
executable file. Specifiying the executable's  extention is optional, unless
there is an ambiguity. (i.e.  ls.bat, ls.exe)  

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

System environment varaible can be called out using the \%var\%  syntax and
used as either part of the command name or  arguments.  

When specifiying a full path to an executable if the path or  executable name
contains whitespace or special characters they  will need to be quoted.
Arguments containing whitespace or  special characters will also have to be
quoted. 

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

The special characters \&()[]\{\}\^{}=;!'+,`\~{} will need to be quoted  if
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:  

   ClientRunBeforeJob = ``c:/bacula/bin/systemstate.bat''  

rather than DOS/Windows form:  

ClientRunBeforeJob =
``c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}systemstate.bat''
INCORRECT 
\end{enumerate}

\item {\bf Client Run After Job = \lt{}command\gt{}}
   \index[fd]{Client Run After Job  }
   This command  is the same as {\bf Run After Job} except that it is  run on the
client machine. Note, please see the notes above  in {\bf Client Run Before
Job} concerning Windows clients. 

\item {\bf Rerun Failed Levels = \lt{}yes|no\gt{}}
   \index[fd]{Rerun Failed Levels  }
   If this directive  is set to {\bf yes} (default 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. 

\item {\bf Spool Data = \lt{}yes|no\gt{}}
   \index[fd]{Spool Data  }
   If this directive is set  to {\bf yes} (default no), the Storage daemon will
be requested  to spool the data for this Job to disk rather than write it 
directly to tape. Once all the data arrives or the spool file  maximum sizes
are reached, the data will be despooled and written  to tape. When this
directive is set to yes, the Spool Attributes  is also automatically set to
yes. Spooling data prevents tape  shoe-shine (start and stop) during
Incremental saves. This option  should not be used if you are writing to a
disk file. 

\item {\bf Spool Attributes = \lt{}yes|no\gt{}}
   \index[fd]{Spool Attributes  }
   The default is set to  {\bf no}, which means that 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  {\bf 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. The default is {\bf no}. 

\item {\bf Where = \lt{}directory\gt{}}
   \index[dir]{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/bacula-restores}. This is to prevent
accidental overwriting  of your files. 

\item {\bf Replace = \lt{}replace-option\gt{}}
   \index[dir]{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 {\bf replace-option}:  

\begin{description}

\item [always]
   \index[dir]{always }
   when the file to be restored already exists,  it is deleted then replaced by
the copy backed up.  

\item [ifnewer]
   \index[fd]{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[fd]{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[fd]{never }
   if the backed up file already exists, Bacula skips  restoring this file.  
\end{description}

\item {\bf Prefix Links=\lt{}yes|no\gt{}}
   \index[fd]{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. 

\item {\bf Maximum Concurrent Jobs = \lt{}number\gt{}}
   \index[dir]{Maximum Concurrent Jobs  }
   where \lt{}number\gt{}  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 1, but you may set it to a larger number.  We strongly
recommend that you read the WARNING documented under  
\ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the Director's
resource.  

\item {\bf Reschedule On Error = \lt{}yes|no\gt{}}
   \index[dir]{Reschedule On Error  }
   If this directive is enabled,  and the job terminates in error, the job will
be rescheduled as determined  by the {\bf Reschedule Interval} and {\bf
Reschedule Times} directives.  If you cancel the job, it will not be
rescheduled. The default is  {\bf 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.  

\item {\bf Reschedule Interval = \lt{}time-specification\gt{}}
   \index[dir]{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. 

\item {\bf Reschedule Times = \lt{}count\gt{}}
   \index[dir]{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.  
\label{Priority}

\item {\bf Priority = \lt{}number\gt{}}
   \index[dir]{Priority  }
   This directive permits you  to control the order in which your jobs 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.  

The default priority is 10.  

If you want to run concurrent jobs, which is not recommended, you should  keep
these points in mind:  

\begin{itemize}
\item To run concurrent jobs,  you must set Maximum Concurrent Jobs = 2 in 5
   or 6 distinct places:  in bacula-dir.conf in the Director, the Job, the
   Client, the Storage  resources; in bacula-fd in the FileDaemon (or Client)
resource,  and in bacula-sd.conf in the Storage resource. If any one  is
missing, it will throttle the jobs to one at a time.  
\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 Maximum Concurrent Jobs settings  would otherwise allow two jobs to run
simultaneously.  
\item Suppose that bacula is running a priority 2 job and 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 is best  not to start them
at exactly the same time, because Bacula  must examine them one at a time. If
by chance Bacula treats  a lower priority first, then it will run before your
high  priority jobs. To avoid this, start any higher priority  a few seconds
before lower ones. This insures that Bacula  will examine the jobs in the
correct order, and that your  priority scheme will be respected.  
\label{WritePartAfterJob}

\item {\bf Write Part After Job = \lt{}yes|no\gt{}}
   \index[sd]{Write Part After Job  }
   If this directive is  set to {\bf yes} (default {\bf no}), a new part file
will be created  after the job is finished.  

It should be set to {\bf 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  everytime a part is written. So, if you run
several jobs each after another, you could  set this directive to {\bf no} for
all jobs, except the last one, to avoid wasting too much  space, but to ensure
that the data is written to the medium when all jobs are finished.  

It is ignored with tape and FIFO devices.  
\end{description}

The following is an example of a valid Job resource definition: 

\footnotesize
\begin{verbatim}
Job {
  Name = "Minou"
  Type = Backup
  Level = Incremental                 # default
  Client = Minou
  FileSet="Minou Full Set"
  Storage = DLTDrive
  Pool = Default
  Schedule = "MinouWeeklyCycle"
  Messages = Standard
}
\end{verbatim}
\normalsize

\section*{The JobDefs Resource}
\label{JobDefsResource}
\index[general]{JobDefs Resource }
\index[general]{Resource!JobDefs }
\addcontentsline{toc}{section}{JobDefs Resource}

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
be mentioned in each Job. 

\section*{The Schedule Resource}
\label{ScheduleResource}
\index[general]{Resource!Schedule }
\index[general]{Schedule Resource }
\addcontentsline{toc}{section}{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 may only
be run manually. In general, you specify an action to be taken and when. 

\begin{description}

\item [Schedule]
   \index[sd]{Schedule }
   Start of the Schedule directives. No {\bf Schedule}  resource is required, but
you will need at least one if you want  Jobs to be automatically started. 

\item [Name = \lt{}name\gt{}]
   \index[sd]{Name  }
   The name of the schedule being defined.  The Name directive is required. 

\item [Run = \lt{}Job-overrides\gt{} \lt{}Date-time-specification\gt{}  ]
   \index[sd]{Run  }
   The Run directive defines when a Job is to be run,  and what overrides if any
to apply. You may specify multiple  {\bf run} directives within a {\bf
Schedule} resource. If you  do, they will all be applied (i.e. multiple
schedules). If you  have two {\bf Run} directives that start at the same time,
two  Jobs will start at the same time (well, within one second of  each
other).  

The {\bf Job-overrides} permit overriding the Level, the  Storage, the
Messages, and the Pool specifications  provided in the Job resource. In
addition, the  FullPool, the IncrementalPool, and the  DifferentialPool
specifications permit overriding the  Pool specification according to what
backup Job Level is  in effect.  

By the use of overrides, you  may customize a particular Job. For example, you
may specify a  Messages override for your Incremental backups that  outputs
messages to a log file, but for your weekly or monthly  Full backups, you may
send the output by email by using  a different Messages override.  

{\bf Job-overrides} are specified as:  {\bf keyword=value} where the keyword
is Level, Storage,  Messages, Pool, FullPool, DifferentialPool, or
IncrementalPool, and  the {\bf value} is as defined on the respective
directive formats for  the Job resource. You may specify multiple {\bf
Job-overrides} on  one {\bf Run} directive by separating them with one or more
spaces or  by separating them with a trailing comma.  For example:  

\begin{description}

\item [Level=Full]
   \index[sd]{Level }
   is all files in the FileSet whether or not  they have changed.  

\item [Level=Incremental]
   \index[sd]{Level }
   is all files that have changed since  the last backup.  

\item [Pool=Weekly]
   \index[sd]{Pool }
   specifies to use the Pool named {\bf Weekly}.  

\item [Storage=DLT\_Drive]
   \index[sd]{Storage }
   specifies to use {\bf DLT\_Drive} for  the storage device.  

\item [Messages=Verbose]
   \index[sd]{Messages }
   specifies to use the {\bf Verbose}  message resource for the Job.  

\item [FullPool=Full]
   \index[sd]{FullPool }
   specifies to use the Pool named {\bf Full}  if the job is a full backup, or is
upgraded from another type  to a full backup.  

\item [DifferentialPool=Differential]
   \index[sd]{DifferentialPool }
   specifies to use the Pool  named {\bf Differential} if the job is a
differential  backup.  

\item [IncrementalPool=Incremental]
   \index[sd]{IncrementalPool }
   specifies to use the Pool  named {\bf Incremental} if the job is an
incremental  backup.  

\item [SpoolData=yes|no]
   \index[sd]{SpoolData }
   tells Bacula to request the Storage  daemon to spool data to a disk file
before putting it on  tape.  

\item [WritePartAfterJob=yes|no]
   \index[sd]{WritePartAfterJob }
   tells Bacula to request the Storage  daemon to write the current part file to
the device when the job  is finished (see 
\ilink{Write Part After Job directive in the Job
resource}{WritePartAfterJob}).  
\end{description}

{\bf 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 specifing 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 {\bf month}, {\bf day}, {\bf hour}, and  {\bf
minute} the Job is to be run. Of these four items to be specified,  {\bf day}
is special in that you may either specify a day of the month  such as 1, 2,
... 31, or you may specify a day of the week such  as Monday, Tuesday, ...
Sunday. Finally, you may also specify a  week qualifier to restrict the
schedule to the first, second, third,  fourth, or fifth week of the month.  

For example, if you specify only a day of the week, such as {\bf Tuesday}  the
Job will be run every hour of every Tuesday of every Month. That  is the {\bf
month} and {\bf 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 {\bf run}  specifications each
with a different minute.  

The date/time to run the Job can be specified in the following way  in
pseudo-BNF:  

\footnotesize
\begin{verbatim}
<void-keyword>    = on
<at-keyword>      = at
<week-keyword>    = 1st | 2nd | 3rd | 4th | 5th | first |
                    second | third | forth | fifth
<wday-keyword>    = sun | mon | tue | wed | thu | fri | sat |
                    sunday | monday | tuesday | wednesday |
                    thursday | friday
<week-of-year-keyword> = w00 | w01 | ... w52 | w53
<month-keyword>   = jan | feb | mar | apr | may | jun | jul |
                    aug | sep | oct | nov | dec | january |
                    february | ... | december
<daily-keyword>   = daily
<weekly-keyword>  = weekly
<monthly-keyword> = monthly
<hourly-keyword>  = hourly
<digit>           = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0
<number>          = <digit> | <digit><number>
<12hour>          = 0 | 1 | 2 | ... 12
<hour>            = 0 | 1 | 2 | ... 23
<minute>          = 0 | 1 | 2 | ... 59
<day>             = 1 | 2 | ... 31
<time>            = <hour>:<minute> |
                    <12hour>:<minute>am |
                    <12hour>:<minute>pm
<time-spec>       = <at-keyword> <time> |
                    <hourly-keyword>
<date-keyword>    = <void-keyword>  <weekly-keyword>
<day-range>       = <day>-<day>
<month-range>     = <month-keyword>-<month-keyword>
<wday-range>      = <wday-keyword>-<wday-keyword>
<range>           = <day-range> | <month-range> |
                          <wday-range>
<date>            = <date-keyword> | <day> | <range>
<date-spec>       = <date> | <date-spec>
<day-spec>        = <day> | <wday-keyword> |
                    <day-range> | <wday-range> |
                    <daily-keyword>
<day-spec>        = <day> | <wday-keyword> |
                    <week-keyword> <wday-keyword>
<month-spec>      = <month-keyword> | <month-range> |
                    <monthly-keyword>
<date-time-spec>  = <month-spec> <day-spec> <time-spec>
\end{verbatim}
\normalsize

\end{description}

Note, the Week of Year specification wnn follows the ISO standard definition
of the week of the year, where Week 1 is the week in which the first Thursday
of the year occurs, or alternatively, the week which contains the 4th of
January. Weeks are numbered w01 to w53. w00 for Bacula is the week that
precedes the first ISO week (i.e. has the first few days of the year if any
occur before Thursday). w00 is not defined by the ISO specification. A week
starts with Monday and ends with Sunday. 

An example schedule resource that is named {\bf WeeklyCycle} and runs a job
with level full each Sunday at 1:05am and an incremental job Monday through
Saturday at 1:05am is: 

\footnotesize
\begin{verbatim}
Schedule {
  Name = "WeeklyCycle"
  Run = Level=Full sun at 1:05
  Run = Level=Incremental mon-sat at 1:05
}
\end{verbatim}
\normalsize

An example of a possible monthly cycle is as follows: 

\footnotesize
\begin{verbatim}
Schedule {
  Name = "MonthlyCycle"
  Run = Level=Full Pool=Monthly 1st sun at 1:05
  Run = Level=Differential 2nd-5th sun at 1:05
  Run = Level=Incremental Pool=Daily mon-sat at 1:05
}
\end{verbatim}
\normalsize

The first of every month: 

\footnotesize
\begin{verbatim}
Schedule {
  Name = "First"
  Run = Level=Full on 1 at 1:05
  Run = Level=Incremental on 2-31 at 1:05
}
\end{verbatim}
\normalsize

Every 10 minutes: 

\footnotesize
\begin{verbatim}
Schedule {
  Name = "TenMinutes"
  Run = Level=Full hourly at 0:05
  Run = Level=Full hourly at 0:15
  Run = Level=Full hourly at 0:25
  Run = Level=Full hourly at 0:35
  Run = Level=Full hourly at 0:45
  Run = Level=Full hourly at 0:55
}
\end{verbatim}
\normalsize

\subsection*{Technical Notes on Schedules}
\index[general]{Schedules!Technical Notes on }
\index[general]{Technical Notes on Schedules }
\addcontentsline{toc}{subsection}{Technical Notes on Schedules}

Internally Bacula keeps a schedule as a bit mask. There are six masks and a
minute field to each schedule. The masks are hour, day of the month (mday),
month, day of the week (wday), week of the month (wom), and week of the year
(woy). The schedule is initialized to have the bits of each of these masks
set, which means that at the beginning of every hour, the job will run. When
you specify a month for the first time, the mask will be cleared and the bit
corresponding to your selected month will be selected. If you specify a second
month, the bit corresponding to it will also be added to the mask. Thus when
Bacula checks the masks to see if the bits are set corresponding to the
current time, your job will run only in the two months you have set. Likewise,
if you set a time (hour), the hour mask will be cleared, and the hour you
specify will be set in the bit mask and the minutes will be stored in the
minute field. 

For any schedule you have defined, you can see how these bits are set by doing
a {\bf show schedules} command in the Console program. Please note that the
bit mask is zero based, and Sunday is the first day of the week (bit zero). 

\section*{The FileSet Resource}
\label{FileSetResource}
\index[general]{Resource!FileSet }
\index[general]{FileSet Resource }
\addcontentsline{toc}{section}{FileSet Resource}

The FileSet resource defines what files are to be included in a backup job. At
least one {\bf FileSet} resource is required for each backup Job. It consists
of a list of files or directories to be included, a list of files or
directories to be excluded and the various backup options such as compression,
encryption, and signatures that are to be applied to each file. 

Any change to the list of the included files will cause Bacula to
automatically create a new FileSet (defined by the name and an MD5 checksum of
the Include contents). Each time a new FileSet is created, Bacula will ensure
that the first backup is always a Full save. 

\begin{description}

\item [FileSet]
   \index[dir]{FileSet }
   Start of the FileSet resource. At least one {\bf FileSet}  resource must be
defined. 

\item [Name = \lt{}name\gt{}]
   \index[dir]{Name  }
   The name of the FileSet resource.  This directive is required. 

\item [Ignore FileSet Changes = \lt{}yes|no\gt{}
   ]
   \index[dir]{Ignore FileSet Changes  }
If this directive is set to {\bf yes}, any changes you make to the  FileSet
Include or Exclude lists will be ignored and not cause Bacula  to immediately
perform a Full backup. The default is {\bf no}, in which  case, if you change
the Include or Exclude, Bacula will force a Full  backup to ensure that
everything is properly backed up. It is not recommended  to set this directive
to yes. This directive is available in Bacula  version 1.35.4 or later. 

\item [{Include \ \{ [ Options \{\lt{}file-options\gt{}\} ...]
   \lt{}file-list\gt{} \} 
   }]
\index[dir]{Include \  \{ [ Options \{\lt{}file-options\gt{}\} ...]
\lt{}file-list\gt{} \}  }

\item [Options \ \{ \lt{}file-options\gt{} \} 
   ]
   \index[dir]{Options \  \{ \lt{}file-options\gt{} \}  }

\item [Exclude \ \{ \lt{}file-list\gt{} \}]
   \index[dir]{Exclude \  \{ \lt{}file-list\gt{} \} }

The Include resource must contain a list of directories and/or files to be
processed in the backup job. Normally, all files found in all subdirectories
of any directory in the Include File list will be backed up. The Include
resource may also oner more Options resources that specify options such as
compression to be applied to all or any subset of the files found for backup. 

There can be any number of {\bf Include} resources within the FileSet, each
having its own list of directories or files to be backed up and the backup
options defined by one or more Options resources. The {\bf file-list} consists
of one file or directory name per line. Directory names should be specified
without a trailing slash. 

You should always specify a full path for every directory and file that you
list in the FileSet. In addition, on Windows machines, you should {\bf always}
prefix the directory or filename with the drive specification (e.g. {\bf
c:/xxx}) using Unix directory name separators (forward slash). 

Bacula's default for processing directories is to recursively descend in the
directory saving all files and subdirectories. Bacula will not by default
cross filesystems (or mount points in Unix parlance). This means that if you
specify the root partition (e.g. {\bf /}), Bacula will save only the root
partition and not any of the other mounted filesystems. Similarly on Windows
systems, you must explicitly specify each of the drives you want saved (e.g.
{\bf c:/} and {\bf d:/} ...). In addition, at least for Windows systems, you
will most likely want to enclose each specification within double quotes
particularly if the directory (or file) name contains spaces. The {\bf df}
command on Unix systems will show you which mount points you must specify to
save everything. See below for an example. 

Take special care not to include a directory twice or Bacula will backup the
same files two times wasting a lot of space on your archive device. Including
a directory twice is very easy to do. For example: 

\footnotesize
\begin{verbatim}
  Include {
    File = /
    File = /usr
    Options { compression=GZIP }
  }
\end{verbatim}
\normalsize

on a Unix system where /usr is a subdirectory (rather than a mounted
filesystem) will cause /usr to be backed up twice. In this case, on Bacula
versions prior to 1.32f-5-09Mar04 due to a bug, you will not be able to
restore hard linked files that were backed up twice. 

If you have used Bacula prior to version 1.34.3, you will note three things in
the new FileSet syntax: 

\begin{enumerate}
\item There is no equal sign (=) after the include and before  the opening
   brace (\{). 
\item Each directory (or filename) to be backed up is preceded by a {\bf File
   =}.  Previously they were simply listed on separate lines. 
\item The options that previously appeared on the Include line now  must be
   specified within their own Options resource. 
   \end{enumerate}

The Options resource is optional, but when specified, it will contain a list
of {\bf keyword=value} options to be applied to the file-list. Multiple
Options resources may be specified one after another. As the files are found
in the specified directories, the Options will applied to the filenames to
determine if and how the file should be backed up. The Options resources are
applied in the order they are specified in the FileSet until the first one
that matches. An Options resource that does not contain a {\bf wild} directive
(wild-card specification, see below) is assumed to match any filename. This is
important to understand, because once Bacula determine that the Options
matches the file under consideration, that file will be saved without looking
at any other Options resources that may be present. This means that any wild
cards must appear before an Option resource without wild cards. 

If for some reason, Bacula applies all the Options resources to a file under
consideration for backup, but there are no matches (generally because of wild
cards that don't match), Bacula as a default will then backup the file. This
is quite logical if you consider the case of no Options, where you want
everything to be backed up. However, one additional point is that in the case
that no match was found, Bacula will use the options found in the last Options
resource. As a consequence, if you want a particular set of ``default''
options, you should put them in an Options resource after any other Options. 

The directives within an Options resource may be one of the following: 

\begin{description}

\item [compression=GZIP]
   \index[fd]{compression }
   All files saved will be software  compressed using the GNU ZIP compression
format. The  compression is done on a file by file basis by the File daemon. 
If there is a problem reading the tape in a  single record of a file, it will
at most affect that file and none  of the other files on the tape. Normally
this option is {\bf not} needed  if you have a modern tape drive as the drive
will do its own  compression. In fact, if you specify software compression at
the  same time you have hardware compression turned on, your files  may
actually take more space on the volume.  

Software compression is very important if you are writing  your Volumes to a
file, and it can also be helpful if you have a  fast computer but a slow
network.  

Specifying {\bf GZIP} uses the default compression level six  (i.e. {\bf GZIP}
is identical to {\bf GZIP6}). If you  want a different compression level (1
through 9), you can specify  it by appending the level number with no
intervening spaces  to {\bf GZIP}. Thus {\bf compression=GZIP1} would give
minimum  compression but the fastest algorithm, and {\bf compression=GZIP9} 
would give the highest level of compression, but requires more  computation.
According to the GZIP documentation, compression levels  greater than 6
generally give very little extra compression and are  rather CPU intensive. 

\item [signature=SHA1]
   \index[fd]{signature }
   An SHA1 signature will be computed for all  The SHA1 algorithm is purported to
be some  what slower than the MD5 algorithm, but at the same time is 
significantly better from a cryptographic point of view (i.e.  much fewer
collisions, much lower probability of being hacked.)  It adds four more bytes
than the MD5 signature.  We strongly recommend that either this option  or MD5
be specified as a default for all files. Note, only  one of the two options
MD5 or SHA1 can be computed for any  file. 

\item [signature=MD5]
   \index[fd]{signature }
   An MD5 signature will be computed for all  files saved. Adding this option
generates about 5\% extra overhead  for each file saved. In addition to the
additional CPU time,  the MD5 signature adds 16 more bytes per file to your
catalog.  We strongly recommend that this option or the SHA1 option  be
specified as a default for all files. 

\item [verify=\lt{}options\gt{}]
   \index[fd]{verify }
   The options letters specified are used  when running a {\bf Verify
Level=Catalog} as well as the  {\bf DiskToCatalog} level job. The options
letters may be any  combination of the following:  

\begin{description}

\item [i]
   compare the inodes  

\item [p]
   compare the permission bits  

\item [n]
   compare the number of links  

\item [u]
   compare the user id  

\item [g]
   compare the group id  

\item [s]
   compare the size  

\item [a]
   compare the access time  

\item [m]
   compare the modification time (st\_mtime)  

\item [c]
   compare the change time (st\_ctime)  

\item [s]
   report file size decreases  

\item [5]
   compare the MD5 signature  

\item [1]
   compare the SHA1 signature  
   \end{description}

A useful set of general options on the {\bf Level=Catalog}  or {\bf
Level=DiskToCatalog}  verify is {\bf pins5} i.e. compare permission bits,
inodes, number  of links, size, and MD5 changes. 

\item {\bf onefs=yes|no}
   \index[fd]{onefs }
   If set to {\bf yes} (the default), {\bf Bacula}  will remain on a single file
system. That is it will not backup  file systems that are mounted on a
subdirectory.  If you wish to backup multiple filesystems, you can  explicitly
list each file system you want saved.  Otherwise, if you set the onefs option
to {\bf no}, Bacula will backup  all mounted file systems (i.e. traverse mount
points) that  are found within the {\bf FileSet}. Thus if  you have NFS or
Samba file systems mounted on a directory listed  in your FileSet, they will
also be backed up. Normally, it is  preferable to set {\bf onefs=yes} and to
explicitly name  each filesystem you want backed up. Explicitly naming  the
filesystems you want backed up avoids the possibility  of getting into a
infinite loop recursing filesystems.  See the example below for more details. 
\label{portable}

\item {\bf portable=yes|no}
   \index[dir]{portable }
   If set to {\bf yes} (default is  {\bf no}), the Bacula File daemon will backup
Win32 files  in a portable format, but not all Win32 file attributes  will be
saved and restored. By default, this option is set to  {\bf no}, which means
that on Win32 systems, the data will  be backed up using Windows API calls and
on WinNT/2K/XP,  all the security and ownership attributes will be properly
backed up  (and restored). However this format is not portable to other 
systems -- e.g. Unix, Win95/98/Me. When backing up Unix systems, this  option
is ignored, and unless you have a specific need to  have portable backups, we
recommend accept the default  ({\bf no}) so that the maximum information
concerning  your files is saved. 

\item {\bf recurse=yes|no}
   \index[fd]{recurse }
   If set to {\bf yes} (the default),  Bacula will recurse (or descend) into all
subdirectories  found unless the directory is explicitly excluded  using an
{\bf exclude} definition.  If you set {\bf recurse=no}, Bacula will save the 
subdirectory entries, but not descend into the  subdirectories, and thus will
not save the files or  directories contained in the subdirectories. Normally,
you  will want the default ({\bf yes}). 

\item {\bf sparse=yes|no}
   \index[dir]{sparse }
   Enable special code that checks for sparse files  such as created by ndbm. The
default is {\bf no}, so no checks  are made for sparse files. You may specify
{\bf sparse=yes} even  on files that are not sparse file. No harm will be
done, but there  will be a small additional overhead to check for buffers of 
all zero, and a small additional amount of space on the output  archive will
be used to save the seek address of each non-zero  record read.  

{\bf Restrictions:} Bacula reads files in 32K buffers.  If the whole buffer is
zero, it will be treated as a sparse  block and not written to tape. However,
if any part of the buffer  is non-zero, the whole buffer will be written to
tape, possibly  including some disk sectors (generally 4098 bytes) that are
all  zero. As a consequence, Bacula's detection of sparse blocks is in  32K
increments rather than the system block size. If anyone  considers this to be
a real problem, please send in a request  for change with the reason. The
sparse code was first  implemented in version 1.27.  

If you are not familiar with sparse files, an example is  say a file where you
wrote 512 bytes at address zero, then  512 bytes at address 1 million. The
operating system will  allocate only two blocks, and the empty space or hole 
will have nothing allocated. However, when you read the  sparse file and read
the addresses where nothing was written,  the OS will return all zeros as if
the space were allocated,  and if you backup such a file, a lot of space will
be used  to write zeros to the volume. Worse yet, when you restore  the file,
all the previously empty space will now be allocated  using much more disk
space. By turning on the {\bf sparse}  option, Bacula will specifically look
for empty space in  the file, and any empty space will not be written to the
Volume,  nor will it be restored. The price to pay for this is that  Bacula
must search each block it reads before writing it.  On a slow system, this may
be important. If you suspect  you have sparse files, you should benchmark the
difference  or set sparse for only those files that are really sparse. 
\label{readfifo}

\item {\bf readfifo=yes|no}
   \index[fd]{readfifo }
   If enabled, tells the Client to  read the data on a backup and write the data
on a restore  to any FIFO (pipe) that is explicitly mentioned  in the FileSet.
In this case, you must have a program already  running that writes into the
FIFO for a backup or reads  from the FIFO on a restore. This can be
accomplished with  the {\bf RunBeforeJob} directive. If this is not the case, 
Bacula will hang indefinitely on reading/writing the FIFO.  When this is not
enabled (default), the Client simply  saves the directory entry for the FIFO. 

\item {\bf mtimeonly=yes|no}
   \index[dir]{mtimeonly }
   If enabled, tells the Client that  the selection of files during Incremental
and Differential  backups should based only on the st\_mtime value in the
stat()  packet. The default is {\bf no} which means that the  selection of
files to be backed up will be based on both the  st\_mtime and the st\_ctime
values. In general, it is not  recommended to use this option. 

\item {\bf keepatime=yes|no}
   \index[dir]{keepatime }
   The default is {\bf no}. When  enabled, Bacula will reset the st\_atime
(access time) field  of files that it backs up to their value prior to the 
backup. This option is not generally recommended as there  are very few
programs that use st\_atime, and the backup  overhead is increased because of
the additional system  call necessary to reset the times. (I'm not sure this 
works on Win32). 

\item {\bf wild=\lt{}string\gt{}}
   \index[dir]{wild }
   Specifies a wild-card string  to be applied to the Files. Note, if {\bf
Exclude} is  not enabled, the wild-card will select which files are to  be
included. If {\bf Exclude=yes} is specified, the wild-card  will select which
files are to be excluded. Multiple wild-card  directives may be specified, and
they will be applied in turn  until the first one that matches. 

\item {\bf regex=\lt{}string\gt{}}
   \index[dir]{regex }
   Specifies a POSIX extended  regular expression to be applied to the Files.
This  directive is available in version 1.35 and later. If  {\bf Exclude} is
not enabled, the regex will select which  files are to be included. If {\bf
Exclude=yes} is  specified, the regex will select which files are to be 
excluded. Multiple regex directives may be specified  within an Options
resource, and  they will be applied in turn until the first one that  matches.


\item {\bf exclude=yes|no}
   \index[dir]{exclude }
   The default is {\bf no}. When  enabled, any files matched within the Options
will be  excluded from the backup. 
\label{ACLSupport}

\item {\bf aclsupport=yes|no}
   \index[dir]{aclsupport }
   The default is {\bf no}.  If this option is set to yes, and you have the POSIX
{\bf libacl} installed on your system, Bacula will backup the  file and
directory UNIX Access Control Lists (ACL) as defined  in IEEE Std 1003.1e
draft 17 and ``POSIX.1e''  (abandoned). This feature is available on UNIX only
and  depends on the ACL library. Bacula is automatically compiled  with ACL
support if the {\bf libacl} library is installed on  your system (shown in
config.out). While restoring the files  Bacula will try to restore the ACLs,
if there is no ACL  support available on the system, Bacula restores the files
and  directories but not the ACL information. Please note, if you  backup an
EXT3 or XFS filesystem with ACLs, then you restore  them to a different
filesystem (perhaps reiserfs) that does  not have ACLs, the ACLs will be
ignored. 
\end{description}

{\bf \lt{}file-list\gt{}} is a list of directory and/or filename names
specified with a {\bf File =} directive. To include names containing spaces,
enclose the name between double-quotes. 

There are a number of special cases when specifying directories and files in a
{\bf file-list}. They are: 

\begin{itemize}
\item Any name preceded by an at-sign (@) is assumed to be the  name of a
   file, which contains a list of files each preceded by a  ``File =''. The named
   file is read once when  the configuration file is parsed during the Director
startup.  Note, that the file is read on the Director's machine  and not on
the Client's. In fact, the @filename can  appear anywhere within the conf file
where a token  would be read, and the contents of the named file will be 
logically inserted in the place of the @filename. What  must be in the file
depends on the location the @filename  is specified in the conf file.  
\item Any name beginning with a vertical bar (|) is  assumed to be the name of
   a program. This program will be executed  on the Director's machine at the
   time the Job starts (not  when the Director reads the configuration file), and
any output  from that program will be assumed to be a list of files or 
directories, one per line, to be included. This allows you to  have a job that
for example includes all the local partitions even  if you change the
partitioning by adding a disk. In general, you will  need to prefix your
command or commands with a {\bf sh -c} so that  they are invoked by a shell.
This will not be the case if you are  invoking a script as in the second
example below. Also, you must  take care to escape (precede with a
\textbackslash{}) wild-cards, shell character, and to  ensure that any spaces
in your command are escaped as well.  If you use a single quotes (') within a
double quote  (``), Bacula will treat everything between the single  quotes as
one field so it will not be necessary to escape  the spaces. In general,
getting all the quotes and escapes  correct is a real pain as you can see by
the next example.  As a consequence, it is often easier to put everything in a
file and simply use the file name within Bacula. In that  case the {\bf sh
-c} will not be necessary providing the  first line of the file is {\bf
\#!/bin/sh}. 

As an  example: 

\footnotesize
\begin{verbatim}
 
Include {
   Options { signature = SHA1 }
   File = "|sh -c 'df -l | grep \"^/dev/hd[ab]\" | grep -v \".*/tmp\" \
      | awk \"{print \\$6}\"'"
}
\end{verbatim}
\normalsize

will produce a list of all the local partitions on a RedHat Linux  system.
Note, the above line was split, but should normally  be written on one line. 
Quoting is a real problem because you must quote for Bacula  which consists of
preceding every \textbackslash{} and every '' with a \textbackslash{}, and 
you must also quote for the shell command. In the end, it is probably  easier
just to execute a small file with: 

\footnotesize
\begin{verbatim}
Include {
  Options {
    signature=MD5
  }
  File = "|my_partitions"
}
\end{verbatim}
\normalsize

where my\_partitions has: 

\footnotesize
\begin{verbatim}
#!/bin/sh
df -l | grep "^/dev/hd[ab]" | grep -v ".*/tmp" \
      | awk "{print \$6}"
\end{verbatim}
\normalsize

If the vertical bar (|) in front of my\_partitions  is preceded by a backslash
as in \textbackslash{}|,  the program will be executed on the Client's machine
instead  of on the Director's machine -- (this is implemented but  not
thoroughly tested, and is reported to work on Windows). Please  note that if
the filename is given within quotes, you will need to  use two slashes. An
example, provided by John Donagher, that backs  up all the local UFS
partitions on a remote system is: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "All local partitions"
  Include {
    Options { signature=SHA1; onefs=yes; }
    File = "\\|bash -c \"df -klF ufs | tail +2 | awk '{print \$6}'\""
  }
}
\end{verbatim}
\normalsize

Note, it requires two backslash characters after the double quote (one
preserves  the next one). If you are a Linux user, just change the {\bf ufs}
to  {\bf ext3} (or your preferred filesystem type) and you will be in 
business.  
\item Any file-list item preceded by a less-than sign (\lt{})  will be taken
   to be a file. This file will be read on the  Director's machine at the time
   the Job starts, and the  data will be assumed to be a list of directories or
files,  one per line, to be included. The names should not be  quoted even if
they contain spaces. This feature allows you to  modify the external file and
change what will be saved  without stopping and restarting Bacula as would be 
necessary if using the @ modifier noted above. 

If you  precede the less-than sign (\lt{}) with a backslash as in 
\textbackslash{}\lt{}, the file-list will be read on the Client machine 
instead of on the Director's machine. Please note that if  the filename is
given within quotes, you will need to use  two slashes.  
\item If you explicitly specify a block device such as {\bf /dev/hda1},  then
   Bacula (starting with version 1.28) will assume that this  is a raw partition
   to be backed up. In this case, you are strongly  urged to specify a {\bf
sparse=yes} include option, otherwise, you  will save the whole partition
rather than just the actual data that  the partition contains. For example: 

\footnotesize
\begin{verbatim}
Include {
  Options { signature=MD5; sparse=yes }
  File = /dev/hd6
}
\end{verbatim}
\normalsize

will backup the data in device /dev/hd6.  

Ludovic Strappazon has pointed out that this feature can be  used to backup a
full Microsoft Windows disk. Simply boot into  the system using a Linux Rescue
disk, then load a statically  linked Bacula as described in the 
\ilink{ Disaster Recovery Using Bacula}{_ChapterStart38} chapter of
this manual. Then  save the whole disk partition. In the case of a disaster,
you  can then restore the desired partition by again booting with  the rescue
disk and doing a restore of the partition. 
\item If you explicitly specify a FIFO device name (created with mkfifo),  and
   you add the option {\bf readfifo=yes} as an option, Bacula  will read the FIFO
   and back its data up to the Volume. For  example: 

\footnotesize
\begin{verbatim}
Include {
  Options {
    signature=SHA1
    readfifo=yes
  }
  File = /home/abc/fifo
}
\end{verbatim}
\normalsize

if {\bf /home/abc/fifo} is a fifo device, Bacula will  open the fifo, read it,
and store all data thus obtained  on the Volume. Please note, you must have a
process on  the system that is writing into the fifo, or Bacula will  hang,
and after one minute of waiting, Bacula will give up  and go on to the next
file. The data read can be anything  since Bacula treats it as a stream.  

This feature can be an excellent way to do a  ``hot'' backup of a very large
database. You can  use the {\bf RunBeforeJob} to create the fifo and to  start
a program that dynamically reads your database and  writes it to the fifo.
Bacula will then write it to the  Volume.  

During the restore operation, the inverse is true,  after Bacula creates the
fifo if there was any data stored  with it (no need to explicitly list it or
add any  options), that data will be written back to the fifo. As  a
consequence, if any such FIFOs exist in the fileset to  be restored, you must
ensure that there is a reader  program or Bacula will block, and after one
minute, Bacula  will time out the write to the fifo and move on to the  next
file. 
\end{itemize}

\end{description}

The following is an example of a valid FileSet resource definition. Note, the
first Include pulls in the contents of the file {\bf /etc/backup.list} when
Bacula is started (i.e. the @). 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Full Set"
  Include {
    Options {
      Compression=GZIP
      signature=SHA1
      Sparse = yes
    }
    File = @/etc/backup.list
  }
  Include {
     Options {
        wild = *.o
        Exclude = yes
     }
     File = /root/myfile
     File = /usr/lib/another_file
  }
}
\end{verbatim}
\normalsize

Note, in the above example, all the files contained in /etc/backup.list will
be compressed with GZIP compression, an SHA1 signature will be computed on the
file's contents (its data), and sparse file handling will apply. 

The two directories /root/myfile and /usr/lib/another\_file will also be saved
without any options, but all files in those directories with the extension
{\bf .o} will be excluded. 

Suppose you want to save everything except {\bf /tmp} on your system. Doing a
{\bf df} command, you get the following output: 

\footnotesize
\begin{verbatim}
[kern@rufus k]$ df
Filesystem      1k-blocks      Used Available Use% Mounted on
/dev/hda5         5044156    439232   4348692  10% /
/dev/hda1           62193      4935     54047   9% /boot
/dev/hda9        20161172   5524660  13612372  29% /home
/dev/hda2           62217      6843     52161  12% /rescue
/dev/hda8         5044156     42548   4745376   1% /tmp
/dev/hda6         5044156   2613132   2174792  55% /usr
none               127708         0    127708   0% /dev/shm
//minimatou/c$   14099200   9895424   4203776  71% /mnt/mmatou
lmatou:/          1554264    215884   1258056  15% /mnt/matou
lmatou:/home      2478140   1589952    760072  68% /mnt/matou/home
lmatou:/usr       1981000   1199960    678628  64% /mnt/matou/usr
lpmatou:/          995116    484112    459596  52% /mnt/pmatou
lpmatou:/home    19222656   2787880  15458228  16% /mnt/pmatou/home
lpmatou:/usr      2478140   2038764    311260  87% /mnt/pmatou/usr
deuter:/          4806936     97684   4465064   3% /mnt/deuter
deuter:/home      4806904    280100   4282620   7% /mnt/deuter/home
deuter:/files    44133352  27652876  14238608  67% /mnt/deuter/files
\end{verbatim}
\normalsize

If you specify only {\bf /} in your Include list, Bacula will only save the
Filesystem {\bf /dev/hda5}. To save all file systems except {\bf /tmp} with
out including any of the Samba or NFS mounted systems, and explicitly
excluding a /tmp, /proc, .journal, and .autofsck, which you will not want to
be saved and restored, you can use the following: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = Include_example
  Include {
    Options {
       wild = /proc
       wild = /tmp
       wild = \.journal
       wild = \.autofsck
       exclude = yes
    }
    File = /
    File = /boot
    File = /home
    File = /rescue
    File = /usr
  }
}
\end{verbatim}
\normalsize

Since /tmp is on its own filesystem and it was not explicitly named in the
Include list, it is not really needed in the exclude list. It is better to
list it in the Exclude list for clarity, and in case the disks are changed so
that it is no longer in its own partition. 

Please be aware that allowing Bacula to traverse or change file systems can be
{\bf very} dangerous. For example, with the following: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Bad example"
  Include {
    Options { onefs=no }
    File = /mnt/matou
  }
}
\end{verbatim}
\normalsize

you will be backing up an NFS mounted partition ({\bf /mnt/matou}), and since
{\bf onefs} is set to {\bf no}, Bacula will traverse file systems. Now if {\bf
/mnt/matou} has the current machine's file systems mounted, as is often the
case, you will get yourself into a recursive loop and the backup will never
end. 

The following FileSet definition will backup a raw partition: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "RawPartition"
  Include {
    Options { sparse=yes }
    File = /dev/hda2
  }
}
\end{verbatim}
\normalsize

While backing up and restoring a raw partition, you should ensure that no
other process including the system is writing to that partition. As a
precaution, you are strongly urged to ensure that the raw partition is not
mounted or is mounted read-only. If necessary, this can be done using the {\bf
RunBeforeJob} directive. 
\label{win32}

\subsection*{Windows Considerations for FileSets}
\index[general]{FileSets!Windows Considerations for }
\index[general]{Windows Considerations for FileSets }
\addcontentsline{toc}{subsection}{Windows Considerations for FileSets}

If you are entering Windows file names, the directory path may be preceded by
the drive and a colon (as in c:). However, the path separators must be
specified in Unix convention (i.e. forward slash (/)). If you wish to include
a quote in a file name, precede the quote with a backslash
(\textbackslash{}\textbackslash{}). For example you might use the following
for a Windows machine to backup the ``My Documents'' directory: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = "Windows Set"
  Include {
    Options {
       wild = *.obj
       wild = *.exe
       exclude = yes
     }
     File = "c:/My Documents"
  }
}
\end{verbatim}
\normalsize

For exclude lists to work correctly on Windows, you must observe the following
rules: 

\begin{itemize}
\item Filenames are case sensitive, so you must use the correct case.  
\item To exclude a directory, you must not have a trailing slash on the 
   directory name.  
\item If you have spaces in your filename, you must enclose the entire name 
   in double-quote characters (``). Trying to use a backslash before  the space
   will not work.  
\item If you are using the old Exclude syntax (noted below), you may  not
   specify a drive letter in the exclude. The new syntax noted  above should work
   fine including driver letters. 
\end{itemize}

Thanks to Thiago Lima for summarizing the above items for us. If you are
having difficulties getting includes or excludes to work, you might want to
try using the {\bf estimate job=xxx listing} command documented in the 
\ilink{Console chapter}{estimate} of this manual. 

On Win32 systems, if you move a directory or file or rename a file into the
set of files being backed up, and a Full backup has already been made, Bacula
will not know there are new files to be saved during an Incremental or
Differential backup (blame Microsoft, not me). To avoid this problem, please
{\bf copy} any new directory or files into the backup area. If you do not have
enough disk to copy the directory or files, move them, but then initiate a
Full backup. 

\subsubsection*{Excluding Files and Directories}
\index[general]{Directories!Excluding Files and }
\index[general]{Excluding Files and Directories }
\addcontentsline{toc}{subsubsection}{Excluding Files and Directories}

You may also include full filenames or directory names in addition to using
wild-cards and {\bf Exclude=yes} in the Options resource as specified above by
simply including the files to be excluded in an Exclude resource within the
FileSet. For example: 

\footnotesize
\begin{verbatim}
FileSet {
  Name = Exclusion_example
  Include {
    Options {
      Signature = SHA1
    }
    File = /
    File = /boot
    File = /home
    File = /rescue
    File = /usr
  }
  Exclude {
    File = /proc
    File = /tmp
    File = .journal
    File = .autofsck
  }
}
\end{verbatim}
\normalsize

\subsection*{A Windows Example FileSet}
\index[general]{FileSet!Windows Example }
\index[general]{Windows Example FileSet }
\addcontentsline{toc}{subsection}{Windows Example FileSet}

The following example was contributed by Phil Stracchino: 

\footnotesize
\begin{verbatim}
This is my Windows 2000 fileset:
FileSet {
  Name = "Windows 2000 Full Set"
  Include {
    Options {
       signature=MD5
    }
    File = c:/
  }
  Exclude {
# Most of these files are excluded not because we don't want
#  them, but because Win2K won't allow them to be backed up
#  except via proprietary Win32 API calls.
    File = "/Documents and Settings/*/Application Data/*/Profiles/
           */*/Cache/*"
    File = "/Documents and Settings/*/Local Settings/Application Data/
           Microsoft/Windows/[Uu][Ss][Rr][Cc][Ll][Aa][Ss][Ss].*"
    File = "/Documents and Settings/*/[Nn][Tt][Uu][Ss][Ee][Rr].*"
    File = "/Documents and Settings/*/Cookies/*"
    File = "/Documents and Settings/*/Local Settings/History/*"
    File = "/Documents and Settings/*/Local Settings/
           Temporary Internet Files/*"
    File = "/Documents and Settings/*/Local Settings/Temp/*"
    File = "/WINNT/CSC"
    File = "/WINNT/security/logs/scepol.log"
    File = "/WINNT/system32/config/*"
    File = "/WINNT/msdownld.tmp/*"
    File = "/WINNT/Internet Logs/*"
    File = "/WINNT/$Nt*Uninstall*"
    File = "/WINNT/Temp/*"
    File = "/temp/*"
    File = "/tmp/*"
    File = "/pagefile.sys"
  }
}
\end{verbatim}
\normalsize

Note, the three line of the above Exclude were split to fit on the document
page, they should be written on a single line in real use. 

\subsection*{The Old FileSet Resource}
\index[general]{Resource!Old FileSet }
\index[general]{Old FileSet Resource }
\addcontentsline{toc}{subsection}{Old FileSet Resource}

The old pre-version 1.34.3 FileSet Resource has been deprecated but will still
work. You are encouraged to convert to using the new form since the old code
will be removed in version 1.37. 

\subsection*{Testing Your FileSet}
\index[general]{FileSet!Testing Your }
\index[general]{Testing Your FileSet }
\addcontentsline{toc}{subsection}{Testing Your FileSet}

If you wish to get an idea of what your FileSet will really backup or if your
exclusion rules will work correctly, you can test it by using the {\bf
estimate} command in the Console program. See the 
\ilink{estimate command}{estimate} in the Console chapter of this
manual. 

\subsection*{Windows NTFS Naming Considerations}
\index[general]{Windows NTFS Naming Considerations }
\index[general]{Considerations!Windows NTFS Naming }
\addcontentsline{toc}{subsection}{Windows NTFS Naming Considerations}

NTFS filenames containing Unicode characters (i.e. \gt{} 0xFF) cannot be
explicitly named at the moment. You must include such names by naming a higher
level directory or a drive letter that does not contain Unicode characters. 

\section*{The Client Resource}
\label{ClientResource2}
\index[general]{Resource!Client }
\index[general]{Client Resource }
\addcontentsline{toc}{section}{Client Resource}

The Client resource defines the attributes of the Clients that are served by
this Director; that is the machines that are to be backed up. You will need
one Client resource definition for each machine to be backed up. 

\begin{description}

\item [Client (or FileDaemon)]
   \index[dir]{Client (or FileDaemon) }
   Start of the Client directives.  

\item [Name = \lt{}name\gt{}]
   \index[dir]{Name  }
   The client name which will be used in the  Job resource directive or in the
console run command.  This directive is required.  

\item [Address = \lt{}address\gt{}]
   \index[console]{Address  }
   Where the address is a host  name, a fully qualified domain name, or a network
address in  dotted quad notation for a Bacula File server daemon.  This
directive is required. 

\item [FD Port = \lt{}port-number\gt{}]
   \index[console]{FD Port  }
   Where the port is a port  number at which the Bacula File server daemon can be
contacted.  The default is 9102. 

\item [Catalog = \lt{}Catalog-resource-name\gt{}]
   \index[console]{Catalog  }
   This specifies the  name of the catalog resource to be used for this Client. 
This directive is required.  

\item [Password = \lt{}password\gt{}]
   \index[console]{Password  }
   This is the password to be  used when establishing a connection with the File
services, so  the Client configuration file on the machine to be backed up
must  have the same password defined for this Director. This directive is 
required.  If you have either {\bf /dev/random}  {\bf bc} on your machine,
Bacula will generate a random  password during the configuration process,
otherwise it will  be left blank. 
\label{FileRetention}

\item [File Retention = \lt{}time-period-specification\gt{}  ]
   \index[fd]{File Retention  }
   The File Retention directive defines the length of time that  Bacula will keep
File records in the Catalog database.  When this time period expires, and if
{\bf AutoPrune} is set to  {\bf yes} Bacula will prune (remove) File records
that  are older than the specified File Retention period. Note, this  affects
only records in the catalog database. It does not  effect your archive
backups.  

File records  may actually be retained for a shorter period than you specify
on  this directive if you specify either a shorter {\bf Job Retention}  or
shorter {\bf Volume Retention} period. The shortest  retention period of the
three takes precedence.  The time may be expressed in seconds, minutes, 
hours, days, weeks, months, quarters, or years. See the 
\ilink{ Configuration chapter}{Time} of this  manual for
additional details of time specification. 

The  default is 60 days. 
\label{JobRetention}

\item [Job Retention = \lt{}time-period-specification\gt{}  ]
   \index[fd]{Job Retention  }
   The Job Retention directive defines the length of time that  Bacula will keep
Job records in the Catalog database.  When this time period expires, and if
{\bf AutoPrune} is set to  {\bf yes} Bacula will prune (remove) Job records
that are  older than the specified File Retention period. As with the other 
retention periods, this affects only records in the catalog and  not data in
your archive backup.  

If a Job  record is selected for pruning, all associated File and JobMedia 
records will also be pruned regardless of the File Retention  period set. As a
consequence, you normally will set the File  retention period to be less than
the Job retention period. The  Job retention period can actually be less than
the value you  specify here if you set the {\bf Volume Retention} directive in
the  Pool resource to a smaller duration. This is because the Job  retention
period and the Volume retention period are  independently applied, so the
smaller of the two takes  precedence.  

The Job retention period is specified as seconds,  minutes, hours, days,
weeks, months,  quarters, or years.  See the 
\ilink{ Configuration chapter}{Time} of this manual for
additional details of  time specification.  

The default is 180 days.  
\label{AutoPrune}

\item [AutoPrune = \lt{}yes|no\gt{}]
   \index[fd]{AutoPrune  }
   If AutoPrune is set to  {\bf yes} (default), Bacula (version 1.20 or greater)
will  automatically apply the File retention period and the Job  retention
period for the Client at the end of the Job.  If you set {\bf AutoPrune = no},
pruning will not be done,  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).  

\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
   \index[fd]{Maximum Concurrent Jobs  }
   where \lt{}number\gt{}  is the maximum number of Jobs with the current Client
that  can run concurrently. Note, this directive limits only Jobs  for Clients
with the same name as the resource in which it appears. Any  other
restrictions on the maximum concurrent jobs such as in  the Director, Job, or
Storage resources will also apply in addition to  any limit specified here.
The  default is set to 1, but you may set it to a larger number.  We strongly
recommend that you read the WARNING documented under  
\ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the Director's
resource.  

\item [*Priority = \lt{}number\gt{}]
   \index[fd]{*Priority  }
   The number specifies the  priority of this client relative to other clients
that the  Director is processing simultaneously. The priority can range  from
1 to 1000. The clients are ordered such that the smaller  number priorities
are performed first (not currently  implemented). 
\end{description}

The following is an example of a valid Client resource definition: 

\footnotesize
\begin{verbatim}
Client {
  Name = Minimatou
  Address = minimatou
  Catalog = MySQL
  Password = very_good
}
\end{verbatim}
\normalsize

\section*{The Storage Resource}
\label{StorageResource2}
\index[general]{Resource!Storage }
\index[general]{Storage Resource }
\addcontentsline{toc}{section}{Storage Resource}

The Storage resource defines which Storage daemons are available for use by
the Director. 

\begin{description}

\item [Storage]
   \index[fd]{Storage }
   Start of the Storage resources. At least one  storage resource must be
specified. 

\item [Name = \lt{}name\gt{}]
   \index[sd]{Name  }
   The name of the storage resource. This  name appears on the Storage directive
specified in the Job directive and  is required. 

\item [Address = \lt{}address\gt{}]
   \index[sd]{Address  }
   Where the address is a host name,  a {\bf fully qualified domain name}, or an
{\bf IP address}. Please note  that the \lt{}address\gt{} as specified here
will be transmitted to  the File daemon who will then use it to contact the
Storage daemon. Hence,  it is {\bf not}, a good idea to use {\bf localhost} as
the  name but rather a fully qualified machine name or an IP address.  This
directive is required. 

\item [SD Port = \lt{}port\gt{}]
   \index[sd]{SD Port  }
   Where port is the port to use to  contact the storage daemon for information
and to start jobs.  This same port number must appear in the Storage resource
of the  Storage daemon's configuration file. The default is 9103. 

\item [Password = \lt{}password\gt{}]
   \index[sd]{Password  }
   This is the password to be used  when establishing a connection with the
Storage services. This  same password also must appear in the Director
resource of the Storage  daemon's configuration file. This directive is
required.  If you have either {\bf /dev/random}  {\bf bc} on your machine,
Bacula will generate a random  password during the configuration process,
otherwise it will  be left blank. 

\item [Device = \lt{}device-name\gt{}]
   \index[sd]{Device  }
   This directive specifies the name  of the device to be used to for the
storage. This name is not the  physical device name, but the logical device
name as defined on the  {\bf Name} directive contained in the {\bf Device}
resource  definition of the {\bf Storage daemon} configuration file.  You can
specify any name you would like (even the device name if  you prefer) up to a
maximum of 127 characters in length.  The physical device name associated with
this device is specified in  the {\bf Storage daemon} configuration file (as
{\bf Archive  Device}). Please take care not to define two different  Storage
resource directives in the Director that point to the  same Device in the
Storage daemon. Doing so may cause the  Storage daemon to block (or hang)
attempting to open the  same device that is already open. This directive is
required. 

\item [Media Type = \lt{}MediaType\gt{}]
   \index[fd]{Media Type  }
   This directive specifies the  Media Type to be used to store the data. This is
an arbitrary  string of characters up to 127 maximum that you define. It can 
be anything you want. However, it is best to  make it descriptive of the
storage media (e.g. File, DAT, ''HP  DLT8000``, 8mm, ...). In addition, it is
essential that you  make the {\bf Media Type} specification unique for each
storage  media type. If you have two DDS-4 drives that have incompatible 
formats, or if you have a DDS-4 drive and a DDS-4 autochanger,  you almost
certainly should specify different {\bf Media Types}.  During a restore,
assuming a {\bf DDS-4} Media Type is associated  with the Job, Bacula can
decide to use any Storage  daemon that support Media Type {\bf DDS-4} and on
any drive  supports it. If you want to tie Bacula to using a single Storage 
daemon or drive, you must specify a unique Media Type for that drive.  This is
an important point that should be carefully understood. You  can find more on
this subject in the 
\ilink{Basic Volume Management}{_ChapterStart39} chapter of this
manual.  

The {\bf MediaType} specified here, {\bf must}  correspond to the {\bf Media
Type} specified in the {\bf Device}  resource of the {\bf Storage daemon}
configuration file.  This directive is required, and it is used by the
Director and the  Storage daemon to ensure that a Volume automatically
selected from  the Pool corresponds to the physical device. If a Storage
daemon  handles multiple devices (e.g. will write to various file Volumes  on
different partitions), this directive allows you to specify exactly  which
device.  

As mentioned above, the value specified in the Director's Storage  resource
must agree with the value specified in the Device resource in  the {\bf
Storage daemon's} configuration file. It is also an  additional check so  that
you don't try to write data for a DLT onto an 8mm device. 
\label{Autochanger1}

\item [Autochanger = \lt{}yes|no\gt{}  ]
   \index[fd]{Autochanger  }
   If you specify {\bf yes}  for this command (the default is {\bf no}), when you
use the {\bf label}  command or the {\bf add} command to create a new Volume,
{\bf Bacula}  will also request the Autochanger Slot number. This simplifies 
creating database entries for Volumes in an autochanger. If you forget  to
specify the Slot, the autochanger will not be used. However, you  may modify
the Slot associated with a Volume at any time  by using the {\bf update
volume} command in the console program.  When {\bf autochanger} is enabled,
the algorithm used by  Bacula to search for available volumes will be modified
to  consider only Volumes that are known to be in the autochanger's  magazine.
If no {\bf in changer} volume is found, Bacula will  attempt recycling,
pruning, ..., and if still no volume is found,  Bacula will search for any
volume whether or not in the magazine.  By privileging in changer volumes,
this procedure minimizes  operator intervention.  The default is {\bf no}.  

For the autochanger to be  used, you must also specify {\bf Autochanger = yes}
in the  
\ilink{Device Resource}{Autochanger}  in the Storage daemon's
configuration file as well as other  important Storage daemon configuration
information.  Please consult the 
\ilink{ Using Autochangers}{_ChapterStart18} manual of this
chapter for the details of  using autochangers. 

\item [Maximum Concurrent Jobs = \lt{}number\gt{}]
   \index[fd]{Maximum Concurrent Jobs  }
   where \lt{}number\gt{}  is the maximum number of Jobs with the current Storage
resource that  can run concurrently. Note, this directive limits only Jobs 
for Jobs using this Storage daemon. Any  other restrictions on the maximum
concurrent jobs such as in  the Director, Job, or Client resources will also
apply in addition to  any limit specified here. The  default is set to 1, but
you may set it to a larger number.  We strongly recommend that you read the
WARNING documented under  
\ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the Director's
resource.  

While it is possible to set the Director's, Job's, or Client's  maximum
concurrent jobs greater than one, you should take great  care in setting the
Storage daemon's greater than one. By keeping  this directive set to one, you
will avoid having two jobs simultaneously  write to the same Volume. Although
this is supported, it is not  currently recommended.  
\end{description}

The following is an example of a valid Storage resource definition: 

\footnotesize
\begin{verbatim}
# Definition of tape storage device
Storage {
  Name = DLTDrive
  Address = lpmatou
  Password = storage_password # password for Storage daemon
  Device = "HP DLT 80"    # same as Device in Storage daemon
  Media Type = DLT8000    # same as MediaType in Storage daemon
}
\end{verbatim}
\normalsize

\section*{The Pool Resource}
\label{PoolResource}
\index[general]{Resource!Pool }
\index[general]{Pool Resource }
\addcontentsline{toc}{section}{Pool Resource}

The Pool resource defines the set of storage Volumes (tapes or files) to be
used by Bacula to write the data. By configuring different Pools, you can
determine which set of Volumes (media) receives the backup data. This permits,
for example, to store all full backup data on one set of Volumes and all
incremental backups on another set of Volumes. Alternatively, you could assign
a different set of Volumes to each machine that you backup. This is most
easily done by defining multiple Pools. 

Another important aspect of a Pool is that it contains the default attributes
(Maximum Jobs, Retention Period, Recycle flag, ...) that will be given to a
Volume when it is created. This avoids the need for you to answer a large
number of questions when labeling a new Volume. Each of these attributes can
later be changed on a Volume by Volume basis using the {\bf update} command in
the console program. Note that you must explicitly specify which Pool Bacula
is to use with each Job. Bacula will not automatically search for the correct
Pool. 

Most often in Bacula installations all backups for all machines (Clients) go
to a single set of Volumes. In this case, you will probably only use the {\bf
Default} Pool. If your backup strategy calls for you to mount a different tape
each day, you will probably want to define a separate Pool for each day. For
more information on this subject, please see the 
\ilink{Backup Strategies}{_ChapterStart3} chapter of this
manual. 

To use a Pool, there are three distinct steps. First the Pool must be defined
in the Director's configuration file. Then the Pool must be written to the
Catalog database. This is done automatically by the Director each time that it
starts, or alternatively can be done using the {\bf create} command in the
console program. Finally, if you change the Pool definition in the Director's
configuration file and restart Bacula, the pool will be updated alternatively
you can use the {\bf update pool} console command to refresh the database
image. It is this database image rather than the Director's resource image
that is used for the default Volume attributes. Note, for the pool to be
automatically created or updated, it must be explicitly referenced by a Job
resource. 

Next the physical media must be labeled. The labeling can either be done with
the {\bf label} command in the {\bf console} program or using the {\bf btape}
program. The preferred method is to use the {\bf label} command in the {\bf
console} program. 

Finally, you must add Volume names (and their attributes) to the Pool. For
Volumes to be used by Bacula they must be of the same {\bf Media Type} as the
archive device specified for the job (i.e. if you are going to back up to a
DLT device, the Pool must have DLT volumes defined since 8mm volumes cannot be
mounted on a DLT drive). The {\bf Media Type} has particular importance if you
are backing up to files. When running a Job, you must explicitly specify which
Pool to use. Bacula will then automatically select the next Volume to use from
the Pool, but it will ensure that the {\bf Media Type} of any Volume selected
from the Pool is identical to that required by the Storage resource you have
specified for the Job. 

If you use the {\bf label} command in the console program to label the
Volumes, they will automatically be added to the Pool, so this last step is
not normally required. 

It is also possible to add Volumes to the database without explicitly labeling
the physical volume. This is done with the {\bf add} console command. 

As previously mentioned, each time Bacula starts, it scans all the Pools
associated with each Catalog, and if the database record does not already
exist, it will be created from the Pool Resource definition. {\bf Bacula}
probably should do an {\bf update pool} if you change the Pool definition, but
currently, you must do this manually using the {\bf update pool} command in
the Console program. 

The Pool Resource defined in the Director's configuration file
(bacula-dir.conf) may contain the following directives: 

\begin{description}

\item [Pool]
   \index[dir]{Pool }
   Start of the Pool resource. There must  be at least one Pool resource defined.


\item [Name = \lt{}name\gt{}]
   \index[dir]{Name  }
   The name of the pool.  For most applications, you will use the default pool 
name {\bf Default}. This directive is required.  

\item [Number of Volumes = \lt{}number\gt{}]
   \index[dir]{Number of Volumes  }
   This directive specifies  the number of volumes (tapes or files) contained in
the pool.  Normally, it is defined and updated automatically by the  Bacula
catalog handling routines. 
\label{MaxVolumes}

\item [Maximum Volumes = \lt{}number\gt{}]
   \index[dir]{Maximum Volumes  }
   This directive specifies the  maximum number of volumes (tapes or files)
contained in the pool.  This directive is optional, if omitted or set to zero,
any number  of volumes will be permitted. In general, this directive is useful
for Autochangers where there is a fixed number of Volumes, or  for File
storage where you wish to ensure that the backups made to  disk files do not
become too numerous or consume too much space.  

\item [Pool Type = \lt{}type\gt{}]
   \index[dir]{Pool Type  }
   This directive defines the pool  type, which corresponds to the type of Job
being run. It is  required and may be one of the following:  

\begin{itemize}
\item [Backup]  
\item [*Archive]  
\item [*Cloned]  
\item [*Migration]  
\item [*Copy]  
\item [*Save]  
   \end{itemize}

\item [Use Volume Once = \lt{}yes|no\gt{}]
   \index[dir]{Use Volume Once  }
   This directive  if set to {\bf yes} specifies that each volume is to be  used
only once. This is most useful when the Media is a  file and you want a new
file for each backup that is  done. The default is {\bf no} (i.e. use volume
any  number of times). This directive will most likely be phased out 
(deprecated), so you are recommended to use {\bf Maximum Volume Jobs = 1} 
instead.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  

\item [Maximum Volume Jobs = \lt{}positive-integer\gt{}]
   \index[fd]{Maximum Volume Jobs  }
   This directive specifies  the maximum number of Jobs that can be written to
the Volume. If  you specify zero (the default), there is no limit. Otherwise, 
when the number of Jobs backed up to the Volume equals {\bf positive-integer} 
the Volume will be marked {\bf Used}. When the Volume is marked  {\bf Used} it
can no longer be used for appending Jobs, much like  the {\bf Full} status but
it can be recycled if recycling is enabled.  By setting {\bf
MaximumVolumeJobs} to one, you get the same  effect as setting {\bf
UseVolumeOnce = yes}.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  

\item [Maximum Volume Files = \lt{}positive-integer\gt{}]
   \index[fd]{Maximum Volume Files  }
   This directive specifies  the maximum number of files that can be written to
the Volume. If  you specify zero (the default), there is no limit. Otherwise, 
when the number of files written to the Volume equals {\bf positive-integer} 
the Volume will be marked {\bf Used}. When the Volume is marked  {\bf Used} it
can no longer be used for appending Jobs, much like  the {\bf Full} status but
it can be recycled if recycling is enabled.  This value is checked and the
{\bf Used} status is set only  at the end of a job that writes to the
particular volume.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  

\item [Maximum Volume Bytes = \lt{}size\gt{}]
   \index[fd]{Maximum Volume Bytes  }
   This directive specifies  the maximum number of bytes that can be written to
the Volume. If  you specify zero (the default), there is no limit except the 
physical size of the Volume. Otherwise,  when the number of bytes written to
the Volume equals {\bf size}  the Volume will be marked {\bf Used}. When the
Volume is marked  {\bf Used} it can no longer be used for appending Jobs, much
like  the {\bf Full} status but it can be recycled if recycling is enabled. 
This value is checked and the {\bf Used} status set while  the job is writing
to the particular volume.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  

\item [Volume Use Duration = \lt{}time-period-specification\gt{}]
   \index[fd]{Volume Use Duration  }
   The Volume Use Duration directive defines the time period that  the Volume can
be written beginning from the time of first data  write to the Volume. If the
time-period specified is zero (the  default), the Volume can be written
indefinitely. Otherwise,  when the time period from the first write to the
volume (the  first Job written) exceeds the time-period-specification, the 
Volume will be marked {\bf Used}, which means that no more  Jobs can be
appended to the Volume, but it may be recycled if  recycling is enabled.  

You might use this directive, for example, if you have a Volume  used for
Incremental backups, and Volumes used for Weekly Full  backups. Once the Full
backup is done, you will want to use a  different Incremental Volume. This can
be accomplished by setting  the Volume Use Duration for the Incremental Volume
to six days.  I.e. it will be used for the 6 days following a Full save, then 
a different Incremental volume will be used.  

This value is checked and the {\bf Used} status is set only  at the end of a
job that writes to the particular volume, which  means that even though the
use duration may have expired, the  catalog entry will not be updated until
the next job that  uses this volume is run.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  

\item [Catalog Files = \lt{}yes|no\gt{}]
   \index[fd]{Catalog Files  }
   This directive  defines whether or not you want the names of the files  that
were saved to be put into the catalog. The default  is {\bf yes}. The
advantage of specifying {\bf Catalog Files = No}  is that you will have a
significantly smaller Catalog database. The  disadvantage is that you will not
be able to produce a Catalog listing  of the files backed up for each Job
(this is often called Browsing).  Also, without the File entries in the
catalog, you will not be  able to use the Console {\bf restore} command nor
any other  command that references File entries.  
\label{PoolAutoPrune}

\item [AutoPrune = \lt{}yes|no\gt{}]
   \index[fd]{AutoPrune  }
   If AutoPrune is set to  {\bf yes} (default), Bacula (version 1.20 or greater)
will  automatically apply the Volume Retention period when new Volume  is
needed and no appendable Volumes exist in the Pool. Volume  pruning causes
expired Jobs (older than the {\bf Volume  Retention} period) to be deleted
from the Catalog and permits  possible recycling of the Volume.  
\label{VolRetention}

\item [Volume Retention = \lt{}time-period-specification\gt{}]
   \index[fd]{Volume Retention  }
   The  Volume Retention directive defines the length of time that {\bf Bacula} 
will keep Job records associated with the Volume in the Catalog  database.
When this time period expires, and if {\bf AutoPrune}  is set to {\bf yes}
Bacula will prune (remove) Job  records that are older than the specified
Volume Retention period.  All File records associated with pruned Jobs are
also pruned.  The time may be specified as seconds,  minutes, hours, days,
weeks, months, quarters, or years.  The {\bf Volume Retention} applied
independently to the  {\bf Job Retention} and the {\bf File Retention} periods
defined in the Client resource. This means that the shorter  period is the
one that applies. Note, that when the  {\bf Volume Retention} period has been
reached, it will  prune both the Job and the File records.  

The default is 365 days. Note, this directive sets the default  value for each
Volume entry in the Catalog when the Volume is  created. The value in the 
catalog may be later individually changed for each Volume using  the Console
program.  

By defining multiple Pools with different Volume Retention periods,  you may
effectively have a set of tapes that is recycled weekly,  another Pool of
tapes that is recycled monthly and so on. However,  one must keep in mind that
if your {\bf Volume Retention} period  is too short, it may prune the last
valid Full backup, and hence  until the next Full backup is done, you will not
have a complete  backup of your system, and in addition, the next Incremental 
or Differential backup will be promoted to a Full backup. As  a consequence,
the minimum {\bf Volume Retention} period should be at  twice the interval of
your Full backups. This means that if you  do a Full backup once a month, the
minimum Volume retention  period should be two months.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  
\label{PoolRecycle}

\item [Recycle = \lt{}yes|no\gt{}]
   \index[fd]{Recycle  }
   This directive specifies the  default for recycling Purged Volumes. If it is
set to {\bf yes}  and Bacula needs a volume but finds none that are 
appendable, it will search for Purged Volumes (i.e. volumes  with all the Jobs
and Files expired and thus deleted from  the Catalog). If the Volume is
recycled, all previous data  written to that Volume will be overwritten.  

Please note that the value defined by this directive in the  bacula-dir.conf
file is the default value used when a Volume  is created. Once the volume is
created, changing the value  in the bacula-dir.conf file will not change what
is stored  for the Volume. To change the value for an existing Volume  you
must use the {\bf update} command in the Console.  
\label{RecycleOldest}

\item [Recycle Oldest Volume = \lt{}yes|no\gt{}]
   \index[fd]{Recycle Oldest Volume  }
   This directive  instructs the Director to search for the oldest used  Volume
in the Pool when another Volume is requested by  the Storage daemon and none
are available.  The catalog is then {\bf pruned} respecting the retention 
periods of all Files and Jobs written to this Volume.  If all Jobs are pruned
(i.e. the volume is Purged), then  the Volume is recycled and will be used as
the next  Volume to be written. This directive respects any Job,  File, or
Volume retention periods that you may have specified,  and as such it is {\bf
much} better to use this directive  than the Purge Oldest Volume.  

This directive can be useful if you have  a fixed number of Volumes in the
Pool and you want to  cycle through them and you have specified the correct 
retention periods.  
\label{RecycleCurrent}

\item [Recycle Current Volume = \lt{}yes|no\gt{}]
   \index[fd]{Recycle Current Volume  }
   If  Bacula needs a new Volume, this directive instructs Bacula  to Prune the
volume respecting the Job and File  retention periods.  If all Jobs are pruned
(i.e. the volume is Purged), then  the Volume is recycled and will be used as
the next  Volume to be written. This directive respects any Job,  File, or
Volume retention periods that you may have specified,  and thus it is {\bf
much} better to use it rather  than the Purge Oldest Volume directive.  

This directive can be useful if you have:  a fixed number of Volumes in the
Pool, you want to  cycle through them, and you have specified  retention
periods that prune Volumes before  you have cycled through the Volume in the
Pool.  
\label{PurgeOldest}

\item [Purge Oldest Volume = \lt{}yes|no\gt{}]
   \index[fd]{Purge Oldest Volume  }
   This directive  instructs the Director to search for the oldest used  Volume
in the Pool when another Volume is requested by  the Storage daemon and none
are available.  The catalog is then {\bf purged} irrespective of retention 
periods of all Files and Jobs written to this Volume.  The Volume is then
recycled and will be used as the next  Volume to be written. This directive
overrides any Job,  File, or Volume retention periods that you may have
specified.  

This directive can be useful if you have  a fixed number of Volumes in the
Pool and you want to  cycle through them and when all Volumes are full, but
you don't  want to worry about setting proper retention periods. However,  by
using this option you risk losing valuable data.  

{\bf Please be aware that {\bf Purge Oldest Volume} disregards  all retention
periods.} If you have only a single Volume  defined and you turn this variable
on, that Volume will always  be immediately overwritten when it fills! So at a
minimum,  ensure that you have a decent number of Volumes in your Pool  before
running any jobs. If you want retention periods to apply  do not use this
directive. To specify a retention period,  use the {\bf Volume Retention}
directive (see above).  

I highly recommend against using this directive, because it is  sure that some
day, Bacula will recycle a Volume that contains  current data. 

\item [Accept Any Volume = \lt{}yes|no\gt{}]
   \index[fd]{Accept Any Volume  }
   This directive  specifies whether or not any volume from the Pool may  be used
for backup. The default is {\bf yes} as of version  1.27 and later. If it is
{\bf no} then only the first  writable volume in the Pool will be accepted for
writing backup  data, thus Bacula will fill each Volume sequentially  in turn
before using any other appendable volume in the  Pool. If this is {\bf no} and
you mount a volume out  of order, Bacula will not accept it. If this  is {\bf
yes} any appendable volume from the pool  mounted will be accepted.  

If your tape backup procedure dictates that you manually  mount the next
volume, you will almost certainly want to be  sure this directive is turned
on.  

If you are going on vacation and you think the current volume  may not have
enough room on it, you can simply label a new tape  and leave it in the drive,
and assuming that {\bf Accept Any Volume}  is {\bf yes} Bacula will begin
writing on it. When you return  from vacation, simply remount the last tape,
and Bacula will  continue writing on it until it is full. Then you can remount
 your vacation tape and Bacula will fill it in turn.  

\item [Cleaning Prefix = \lt{}string\gt{}]
   \index[fd]{Cleaning Prefix  }
   This directive defines  a prefix string, which if it matches the beginning of 
a Volume name during labeling of a Volume, the Volume  will be defined with
the VolStatus set to {\bf Cleaning} and  thus Bacula will never attempt to use
this tape. This  is primarily for use with autochangers that accept barcodes 
where the convention is that barcodes beginning with {\bf CLN}  are treated as
cleaning tapes.  
\label{Label}

\item [Label Format = \lt{}format\gt{}]
   \index[fd]{Label Format  }
   This directive specifies the  format of the labels contained in this pool. The
format directive  is used as a sort of template to create new Volume names
during  automatic Volume labeling.  

The {\bf format} should be specified in double quotes, and  consists of
letters, numbers and the special characters  hyphen ({\bf -}), underscore
({\bf \_}), colon ({\bf :}), and  period ({\bf .}), which are the legal
characters for a Volume  name. The {\bf format} should be enclosed in  double
quotes ('').  

In addition, the format may contain a number of variable expansion  characters
which will be expanded by a complex algorithm allowing  you to create Volume
names of many different formats. In all  cases, the expansion process must
resolve to the set of characters  noted above that are legal Volume names.
Generally, these  variable expansion characters begin with a dollar sign ({\bf
\$})  or a left bracket ({\bf [}). If you specify variable expansion 
characters, you should always enclose the format with double  quote characters
({\bf ``}). For more details on variable expansion,  please see the 
\ilink{Variable Expansion}{_ChapterStart50} Chapter of  this manual.  

If no variable expansion characters are found in the string,  the Volume name
will be formed from the {\bf format} string  appended with the number of
volumes in the pool plus one, which  will be edited as four digits with
leading zeros. For example,  with a {\bf Label Format = ''File-``}, the first
volumes will be  named {\bf File-0001}, {\bf File-0002}, ...  

With the exception of Job specific variables, you can test  your {\bf
LabelFormat} by using the 
\ilink{ var command}{var} the Console Chapter of this manual.  

In almost all cases, you should enclose the format specification  (part after
the equal sign) in double quotes.  
\end{description}

In order for a Pool to be used during a Backup Job, the Pool must have at
least one Volume associated with it. Volumes are created for a Pool using the
{\bf label} or the {\bf add} commands in the {\bf Bacula Console}, program. In
addition to adding Volumes to the Pool (i.e. putting the Volume names in the
Catalog database), the physical Volume must be labeled with valid Bacula
software volume label before {\bf Bacula} will accept the Volume. This will be
automatically done if you use the {\bf label} command. Bacula can
automatically label Volumes if instructed to do so, but this feature is not
yet fully implemented. 

The following is an example of a valid Pool resource definition: 

\footnotesize
\begin{verbatim}
 
Pool {
  Name = Default
  Pool Type = Backup
}
\end{verbatim}
\normalsize

\section*{The Catalog Resource}
\label{CatalogResource}
\index[general]{Resource!Catalog }
\index[general]{Catalog Resource }
\addcontentsline{toc}{section}{Catalog Resource}

The Catalog Resource defines what catalog to use for the current job.
Currently, Bacula can only handle a single database server (SQLite, MySQL,
built-in) that is defined when configuring {\bf Bacula}. However, there may be
as many Catalogs (databases) defined as you wish. For example, you may want
each Client to have its own Catalog database, or you may want backup jobs to
use one database and verify or restore jobs to use another database. 

\begin{description}

\item [Catalog]
   \index[console]{Catalog }
   Start of the Catalog resource.  At least one Catalog resource must be defined.


\item [Name = \lt{}name\gt{}]
   \index[console]{Name  }
   The name of the Catalog. No  necessary relation to the database server name.
This name  will be specified in the Client resource directive indicating  that
all catalog data for that Client is maintained in this  Catalog. This
directive is required.  

\item [password = \lt{}password\gt{}]
   \index[console]{password  }
   This specifies the password  to use when logging into the database. This
directive is required.  

\item [DB Name = \lt{}name\gt{}]
   \index[console]{DB Name  }
   This specifies the name of the  database. If you use multiple catalogs
(databases), you specify  which one here. If you are using an external
database server  rather than the internal one, you must specify a name that 
is known to the server (i.e. you explicitly created the  Bacula tables using
this name. This directive is  required. 

\item [user = \lt{}user\gt{}]
   \index[console]{user  }
   This specifies what user name  to use to log into the database. This directive
is required.  

\item [DB Socket = \lt{}socket-name\gt{}]
   \index[console]{DB Socket  }
   This is the name of  a socket to use on the local host to connect to the
database.  This directive is used only by MySQL and is ignored by  SQLite.
Normally, if neither {\bf DB Socket} or {\bf DB Address}  are specified, MySQL
will use the default socket.  

\item [DB Address = \lt{}address\gt{}]
   \index[console]{DB Address  }
   This is the host address  of the database server. Normally, you would specify
this instead  of {\bf DB Socket} if the database server is on another machine.
In that case, you will also specify {\bf DB Port}. This directive  is used
only by MySQL and is ignored by SQLite if provided.  This directive is
optional.  

\item [DB Port = \lt{}port\gt{}]
   \index[console]{DB Port  }
   This defines the port to  be used in conjunction with {\bf DB Address} to
access the  database if it is on another machine. This directive is used  only
by MySQL and is ignored by SQLite if provided. This  directive is optional.  

\item [Multiple Connections = \lt{}yes|no\gt{}]
   \index[console]{Multiple Connections  }
   By default, this  directive is set to no. In that case, each job that uses the
same Catalog will use a single connection to the catalog. It will  be shared,
and Bacula will allow only one Job at a time to  communicate. If you set this
directive to yes, Bacula will  permit multiple connections to the database,
and the database  must be multi-thread capable. For SQLite and PostgreSQL,
this is  no problem. For MySQL, you must be *very* careful to have the 
multi-thread version of the client library loaded on your system.  When this
directive is set yes, each Job will have a separate  connection to the
database, and the database will control the  interaction between the different
Jobs. This can significantly  speed up the database operations if you are
running multiple  simultaneous jobs. In addition, for SQLite and PostgreSQL,
Bacula  will automatically enable transactions. This can significantly  speed
up insertion of attributes in the database either for  a single Job or
multiple simultaneous Jobs.  

This directive has not been tested. Please test carefully  before running it
in production and report back your results.  
\end{description}

The following is an example of a valid Catalog resource definition: 

\footnotesize
\begin{verbatim}
Catalog
{
  Name = SQLite
  dbname = bacula;
  user = bacula;
  password = ""                       # no password = no security
}
\end{verbatim}
\normalsize

or for a Catalog on another machine: 

\footnotesize
\begin{verbatim}
Catalog
{
  Name = MySQL
  dbname = bacula
  user = bacula
  password = ""
  DB Address = remote.acme.com
  DB Port = 1234
}
\end{verbatim}
\normalsize

\section*{The Messages Resource}
\label{MessagesResource2}
\index[general]{Resource!Messages }
\index[general]{Messages Resource }
\addcontentsline{toc}{section}{Messages Resource}

For the details of the Messages Resource, please see the 
\ilink{Messages Resource Chapter}{_ChapterStart15} of this
manual. 

\section*{The Console Resource}
\label{ConsoleResource1}
\index[general]{Console Resource }
\index[general]{Resource!Console }
\addcontentsline{toc}{section}{Console Resource}

As of Bacula version 1.33 and higher, there are three different kinds of
consoles, which the administrator or user can use to interact with the
Director. These three kinds of consoles comprise three different security
levels. 

\begin{itemize}
\item The first console type is an {\bf anonymous} or {\bf default}  console,
   which  has full privileges. There is no console resource necessary  for this
   type since the password is specified in the Director's  resource and
consequently such consoles do not have an  name as defined on a {\bf Name =}
directive. This is the kind of  console that was initially implemented in
versions prior to 1.33  and remains valid. Typically you would use it only for
 administrators.  
\item The second type of console, and new to version 1.33 and  higher is a
   ''named`` console defined within  a Console resource in both the Director's
   configuration file and in  the Console's configuration file. Both the names
and the passwords  in these two entries must match much as is the case for 
Client programs.  

This second type of console begins with absolutely no  privileges except those
explicitly specified in the Director's  Console resource. Thus you can have
multiple Consoles with  different names and passwords, sort of like multiple
users, each  with different privileges. As a  default, these consoles can do
absolutely nothing -- no commands  what so ever. You give them privileges or
rather access  to commands and resources by specifying access  control lists
in the Director's Console resource. The ACLs are  specified by a directive
followed by a list of access names.  Examples of this are shown below.  
\item The third type of console is similar to the above mentioned  one in that
   it requires a Console resource definition in both  the Director and the
   Console. In addition, if the console name,  provided on the {\bf Name =}
directive, is the same as a Client  name, that console is permitted to use the
{\bf SetIP}  command to change the Address directive in the  Director's client
resource to the IP address of the Console. This  permits portables or other
machines using DHCP (non-fixed IP addresses)  to ''notify`` the Director of
their current IP address.  
\end{itemize}

The Console resource is optional and need not be specified. The following
directives are permited within the Director's configuration resource: 

\begin{description}

\item [Name = \lt{}name\gt{}]
   \index[console]{Name  }
   The name of the console. This  name must match the name specified in the
Console's configuration  resource (much as is the case with Client
definitions).  

\item [Password = \lt{}password\gt{}]
   \index[console]{Password  }
   Specifies the password that  must be supplied for a named Bacula Console to be
authorized. The same  password must appear in the {\bf Console} resource of
the Console  configuration file. For added security, the password is never 
actually passed across the network but rather a challenge response  hash code
created with the password. This directive is required.  If you have either
{\bf /dev/random}  {\bf bc} on your machine, Bacula will generate a random 
password during the configuration process, otherwise it will  be left blank. 

\item [JobACL = \lt{}name-list\gt{}]
   \index[console]{JobACL  }
   This directive is used to  specify a list of Job resource names that can be
accessed by  the console. Without this directive, the console cannot access 
any of the Director's Job resources. Multiple Job resource names  may be
specified by separating them with commas, and/or by specifying  multiple
JobACL directives. For example, the directive  may be specified as:  

\footnotesize
\begin{verbatim}
    JobACL = kernsave, "Backup client 1", "Backup client 2"
    JobACL = "RestoreFiles"
    
\end{verbatim}
\normalsize

With the above specification, the console can access the Director's  resources
for the four jobs named on the JobACL directives,  but for no others.  

\item [ClientACL = \lt{}name-list\gt{}]
   \index[console]{ClientACL  }
   This directive is used to  specify a list of Client resource names that can be
accessed by  the console.  

\item [StorageACL = \lt{}name-list\gt{}]
   \index[console]{StorageACL  }
   This directive is used to  specify a list of Storage resource names that can
be accessed by  the console.  

\item [ScheduleACL = \lt{}name-list\gt{}]
   \index[console]{ScheduleACL  }
   This directive is used to  specify a list of Schedule resource names that can
be accessed by  the console.  

\item [PoolACL = \lt{}name-list\gt{}]
   \index[console]{PoolACL  }
   This directive is used to  specify a list of Pool resource names that can be
accessed by  the console.  

\item [FileSetACL = \lt{}name-list\gt{}]
   \index[console]{FileSetACL  }
   This directive is used to  specify a list of FileSet resource names that can
be accessed by  the console.  

\item [CatalogACL = \lt{}name-list\gt{}]
   \index[console]{CatalogACL  }
   This directive is used to  specify a list of Catalog resource names that can
be accessed by  the console.  

\item [CommandACL = \lt{}name-list\gt{}]
   \index[console]{CommandACL  }
   This directive is used to  specify a list of of console commands that can be
executed by  the console. 
\end{description}

Aside from Director resource names and console command names, the special
keyword {\bf *all*} can be specified in any of the above access control lists.
When this keyword is present, any resource or command name (which ever is
appropriate) will be accepted. For an example configuration file, please see
the 
\ilink{Console Configuration}{_ChapterStart36} chapter of this
manual. 

\section*{The Counter Resource}
\label{CounterResource}
\index[general]{Resource!Counter }
\index[general]{Counter Resource }
\addcontentsline{toc}{section}{Counter Resource}

The Counter Resource defines a counter variable that can be accessed by
variable expansion used for creating Volume labels with the {\bf LabelFormat}
directive. See the 
\ilink{LabelFormat}{Label} directive in this chapter for more
details. 

\begin{description}

\item [Counter]
   \index[console]{Counter }
   Start of the Counter resource.  Counter directives are optional. 

\item [Name = \lt{}name\gt{}]
   \index[console]{Name  }
   The name of the Counter.  This is the name you will use in the variable
expansion  to reference the counter value.  

\item [Minimum = \lt{}integer\gt{}]
   \index[console]{Minimum  }
   This specifies the minimum  value that the counter can have. It also becomes
the default.  If not supplied, zero is assumed.  

\item [Maximum = \lt{}integer\gt{}]
   \index[console]{Maximum  }
   This is the maximum value  value that the counter can have. If not specified
or set to  zero, the counter can have a maximum value of 2,147,483,648  (2 to
the 31 power). When the counter is incremented past  this value, it is reset
to the Minimum.  

\item [*WrapCounter = \lt{}counter-name\gt{}]
   \index[console]{*WrapCounter  }
   If this value  is specified, when the counter is incremented past the maximum 
and thus reset to the minimum, the counter specified on the  {\bf WrapCounter}
is incremented. (This is not currently  implemented). 

\item [Catalog = \lt{}catalog-name\gt{}]
   \index[console]{Catalog  }
   If this directive is  specified, the counter and its values will be saved in 
the specified catalog. If this directive is not present, the  counter will be
redefined each time that Bacula is started. 
\end{description}

\section*{ A Complete Example Director Configuration File}
\label{SampleDirectorConfiguration}
\index[general]{File!Complete Example Director Configuration }
\index[general]{Complete Example Director Configuration File }
\addcontentsline{toc}{section}{Complete Example Director Configuration File}

An example Director configuration file might be the following: 

\footnotesize
\begin{verbatim}
#
# Default Bacula Director Configuration file
#
#  The only thing that MUST be changed is to add one or more
#   file or directory names in the Include directive of the
#   FileSet resource.
#
#  For Bacula release 1.15 (5 March 2002) -- redhat
#
#  You might also want to change the default email address
#   from root to your address.  See the "mail" and "operator"
#   directives in the Messages resource.
#
Director {                            # define myself
  Name = rufus-dir
  QueryFile = "/home/kern/bacula/bin/query.sql"
  WorkingDirectory = "/home/kern/bacula/bin/working"
  PidDirectory = "/home/kern/bacula/bin/working"
  Password = "XkSfzu/Cf/wX4L8Zh4G4/yhCbpLcz3YVdmVoQvU3EyF/"
}
# Define the backup Job
Job {
  Name = "NightlySave"
  Type = Backup
  Level = Incremental                 # default
  Client=rufus-fd
  FileSet="Full Set"
  Schedule = "WeeklyCycle"
  Storage = DLTDrive
  Messages = Standard
  Pool = Default
}
Job {
  Name = "Restore"
  Type = Restore
  Client=rufus-fd
  FileSet="Full Set"
  Where = /tmp/bacula-restores
  Storage = DLTDrive
  Messages = Standard
  Pool = Default
}
   
# List of files to be backed up
FileSet {
  Name = "Full Set"
  Include {
    Options { signature=SHA1 }
#
#  Put your list of files here, one per line or include an
#    external list with:
#
#    @file-name
#
#  Note: / backs up everything
  File = /
  }
  Exclude { }
}
# When to do the backups
Schedule {
  Name = "WeeklyCycle"
  Run = Full sun at 1:05
  Run = Incremental mon-sat at 1:05
}
# Client (File Services) to backup
Client {
  Name = rufus-fd
  Address = rufus
  Catalog = MyCatalog
  Password = "MQk6lVinz4GG2hdIZk1dsKE/LxMZGo6znMHiD7t7vzF+"
  File Retention = 60d      # sixty day file retention
  Job Retention = 1y        # 1 year Job retention
  AutoPrune = yes           # Auto apply retention periods
}
# Definition of DLT tape storage device
Storage {
  Name = DLTDrive
  Address = rufus
  Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
  Device = "HP DLT 80"      # same as Device in Storage daemon
  Media Type = DLT8000      # same as MediaType in Storage daemon
}
# Definition of DDS tape storage device
Storage {
  Name = SDT-10000
  Address = rufus
  Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
  Device = SDT-10000        # same as Device in Storage daemon
  Media Type = DDS-4        # same as MediaType in Storage daemon
}
# Definition of 8mm tape storage device
Storage {
  Name = "8mmDrive"
  Address = rufus
  Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
  Device = "Exabyte 8mm"
  MediaType = "8mm"
}
# Definition of file storage device
Storage {
  Name = File
  Address = rufus
  Password = "jMeWZvfikUHvt3kzKVVPpQ0ccmV6emPnF2cPYFdhLApQ"
  Device = FileStorage
  Media Type = File
}
# Generic catalog service
Catalog {
  Name = MyCatalog
  dbname = bacula; user = bacula; password = ""
}
# Reasonable message delivery -- send most everything to
#   the email address and to the console
Messages {
  Name = Standard
  mail = root@localhost = all, !skipped, !terminate
  operator = root@localhost = mount
  console = all, !skipped, !saved
}
    
# Default pool definition
Pool {
  Name = Default
  Pool Type = Backup
  AutoPrune = yes
  Recycle = yes
}
#
# Restricted console used by tray-monitor to get the status of the director
#
Console {
  Name = Monitor
  Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR"
  CommandACL = status, .status
}
\end{verbatim}
\normalsize