
#include "bacula_template.inc" title="Bacula Configuration" num=6


<h1>Customizing the Configuration Files</h1>

When each of the Bacula programs starts, it reads a configuration 
file specified on the command line or the default <b>bacula-dir.conf</b>, 
<b>bacula-fd.conf</b>, <b>bacula-sd.conf</b>, or <b>console.conf</b> for
the Director daemon, the File daemon, the Storage daemon, and
the Console program respectively.
<p>
Each service (Director, Client, Storage, Console) has its own
configuration file containing a set of Resource definitions. These
resources  are very similar from one service to another, but may
contain different directives (records) depending on the service.  For example,
in the Director's resource file, the <b>Director</b> resource
defines the name of the Director, a number of global Director
parameters and his password. In the File daemon configuration
file, the <b>Director</b> resource specifies which Directors
are permitted to use the File daemon.
<p>
Before running Bacula for the first time, you must customize the
configuration files for each daemon.  Default configuration
files will have been created by the installation process, but
you will need to modify them to correspond to your system.
An overall view of the resources can be seen in the following:
<p> 
<img src="bacula-objects.png">
<br>
<font size=-1>
(thanks to Aristedes Maniatis for the above graphic)
</font>

<a name="ResFormat"></a>
<h2>Resource Directive Format</h2>
Although, you won't need to know the details of all the directives 
a basic knowledge of Bacula resource directives is essential.
Each directive contained within the resource (within the braces)
is composed of a keyword followed by an equal sign (=) followed by
one or more values. The keywords must be one of the known Bacula
resource record keywords, and it may be composed of upper or lower
case characters and spaces.
<p>Each resource definition MUST contain a Name directive, and may
optionally contain a Description directive (or record).  The Name
directive is used to uniquely identify the resource.  The
Description directive is (will be) used during display of the
Resource to provide easier human recognition.  For
example:
<pre>
Director {
  Name = &quot;MyDir&quot;
  Description = &quot;Main Bacula Director&quot;
  WorkingDirectory = "$HOME/bacula/bin/working"
}
</pre>
Defines the Director resource with the name &quot;MyDir&quot; and
a working directory $HOME/bacula/bin/working. In general, if you want
spaces in a name to the right of the first equal sign (=),
you must enclose that name within double quotes. Otherwise
quotes are not generally necessary because once defined, quoted strings
and unquoted strings are all equal.  

<a name="Comments"></a>
<h3>Comments</h3> 
When reading the configuration file, blank lines are
ignored and everything after a hash sign (#) until the end of the line
is taken to be a comment.  A semicolon (;) is a logical end of line, and
anything after the semicolon is considered as the next statement.
If a statement appears on a line by itself, a semicolon is not necessary
to terminate it, so generally in the examples in this manual, you will
not see many semicolons.

<a name="Case"></a>
<h3>Upper and Lower Case and Spaces</h3>
Case (upper/lower) and spaces are totally ignored in the resource 
directive keywords (the part before the equal sign). 
<p>
Within the keyword (i.e. before the equal sign), spaces are
not significant. Thus the keywords: <b>name</b>, <b>Name</b>,
and <b>N a m e</b> are all identical.
<p>Spaces after the equal sign and before the first character of
the value are ignored.

<p>In general, spaces within a value are significant (not ignored),
and if the value is a name, you must enclose the name in double
quotes for the spaces to be accepted. Names may contain up to 127
characters. Currently, a name may contain any ASCII character. 
Within a quoted string, any character following a backslash (\) is taken as
itself (handy for inserting blackslashes and double quotes (&quot;).  
<p>Please note, however, that Bacula resource names as well as certain
other names (e.g.  Volume names) will in the future be severely limited
to permit only letters (including ISO accented letters), numbers, and a
few special characters (space, underscore, ...).  All other characters
and punctuation will be illegal.

<a name"Includes"></a>
<h3>Including other Configuration Files</h3>
If you wish to break your configuration file into smaller
pieces, you can do so by including other files using the
syntax @<b>filename</b> where <b>filename</b> is the full
path and filename of another file. The @filename specification
can be given anywhere a primitive token would appear. 

<a name="DataTypes"></a>
<h3>Recognized Primitive Data Types</h3>
When parsing the resource directives, Bacula classifies
the data according to the types listed below. The first time
you read this, it may appear a bit overwhelming, but in 
reality, it is all pretty logical and straight forward.
<dl>
 <dt>name</dt><dd>A keyword or name consisting of alpha
   numeric characters, including the hyphen, underscore, and dollar
   characters. The first character of a <b>name</b> must be
   a letter.
   A name has a maximum length currently set to 127 bytes.
   Typically keywords appear on the left side of an equal (i.e.
   they are Bacula keywords -- i.e. Resource names or 
   directive names). Keywords may not be quoted.
   </dd>

 <dt>name-string</dt><dd>A name-string is similar to a name,
   except that the name may be quoted and can thus contain
   additional characters including spaces. Name strings
   are limited to 127 characters in length. Name strings
   are typically used on the right side of an equal (i.e.
   they are values to be associated with a keyword.</dd>

 <dt>string</dt><dd>A quoted string containing virtually any
   character including spaces, or a non-quoted string. A
   string may be of any length. Strings are typically values 
   that correspond to filenames, directories, or system
   command names.  A backslash (\) turns the next character into
   itself, so to include a double quote in a string, you precede the
   double quote with a backslash.  Likewise to include a backslash.

 <dt>directory</dt><dd>A directory is either a quoted or
   non-quoted string. A directory will be passed to your
   standard shell for expansion when it is scanned. Thus
   constructs such as <b>$HOME</b> are interpreted to be
   their correct values.</dd>

 <dt>password</dt><dd>This is a Bacula password and
   it is stored internally in MD5 hashed format.</dd>

 <dt>integer</dt><dd>A 32 bit integer value. It may be positive
   or negative.</dd>

 <dt>positive integer</dt><dd>A 32 bit positive integer value.</dd>

 <dt>long integer</dt><dd>A 64 bit integer value. Typically these
    are values such as bytes that can exceed 4 billion and thus
    require a 64 bit value.</dd>

 <dt>yes/no</dt><dd>Either a <b>yes</b> or a <b>no</b>.</dd>

 <dt><a name="Size">size</a></dt><dd>A size specified as bytes. Typically, this is
   a floating point scientific input format followed by an optional modifier. The
   floating point input is stored as a 64 bit integer value.
   If a modifier is present, it must immediately follow the
   value with no intervening spaces. The following modifiers are permitted:</dd>
   <p>
   <dl>
   <dt>k</dt><dd>1,024 (kilobytes)</dd>
   <dt>kb</dt><dd>1,000 (kilobytes)</dd>
   <dt>m</dt><dd>1,048,576 (megabytes)</dd> 
   <dt>mb</dt><dd>1,000,000 (megabytes)</dd> 
   <dt>g</dt><dd>1,073,741,824 (gigabytes) </dd>
   <dt>gb</dt><dd>1,000,000,000 (gigabytes) </dd>
   </dl>
   </dd>
   <p>

 <dt><a name="Time">time</a></dt><dd>A time or duration specified in seconds.
   The time is stored internally as a 64 bit integer value, but
   it is specified in two parts: a number part and a modifier part.
   The number can be an integer or a floating point number. If it
   is entered in floating point notation, it will be rounded to
   the nearest integer. 
   The modifer is mandatory and follows the number part,
   either with or without intervening spaces.
   The following modifiers are permitted:</dd><p>
   <dl>
   <dt>seconds</dt><dd>seconds</dd>
   <dt>minutes</dt><dd>minutes (60 seconds)</dd> 
   <dt>hours</dt><dd>hours (3600 seconds)</dd>
   <dt>days</dt><dd>days (3600*24 seconds)</dd>
   <dt>weeks</dt><dd>weeks (3600*24*7 seconds)</dd>
   <dt>months</dt><dd>months (3600*24*30 seconds)</dd>
   <dt>quarters</dt><dd>quarters (3600*24*91 seconds)</dd>
   <dt>years</dt><dd>years (3600*24*365 seconds)</dd>
   </dl>
   <p>
   Any abbreviation of these modifiers is also permitted (i.e.
   <b>seconds</b>  may be specified as <b>sec</b>  or <b>s</b>.
   A specification of <b>m</b>  will be taken as months.
   <p>The specification of a time my have as may number/modifier
   parts as you wish. For example:
   <pre>
1 week 2 days 3 hours 10 mins
1 month 2 days 30 sec 
   </pre>
   are valid date specifications (beginning with version 1.35.1).
   <p>
   Note! in Bacula version 1.31 and below, the modifier was optional.
   It is now manditory.
   </dd>
</dl>

     
<a name="ResTypes"></a>
<h2>Resource Types</h2>
The following table lists all current Bacula resource types.
It shows what resources must be defined for
each service (daemon). The default configuration files will
already contain at least one example of each permitted
resource, so you need not worry about creating all
these kinds of resources from scratch.
<p>

<table cellspacing="4" cellpadding="4" border="5">

<tr> <th>Resource</th> <th>Director</th> <th>Client</th> <th>Storage</th> <th>Console</th></tr>
<tr> <td>Catalog</td>  <td>Yes</td> <td>No</td>   <td>No</td>  <td>No</td> </tr>
<tr> <td>Client</td>   <td>Yes</td> <td>Yes</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>Console</td>  <td>Yes</td>  <td>No</td>  <td>No</td>  <td>Yes</td> </tr>
<tr> <td>Device</td>   <td>No</td>   <td>No</td>  <td>Yes</td> <td>No</td> </tr>
<tr> <td>Director</td> <td>Yes</td>  <td>Yes</td> <td>Yes</td> <td>Yes</td> </tr>
<tr> <td>FileSet</td>  <td>Yes</td>  <td>No</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>Job</td>      <td>Yes</td>  <td>No</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>JobDefs</td>  <td>Yes</td>  <td>No</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>Message</td>  <td>Yes</td>  <td>Yes</td> <td>Yes</td> <td>No</td> </tr>
<tr> <td>Pool</td>     <td>Yes</td>  <td>No</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>Schedule</td> <td>Yes</td>  <td>No</td>  <td>No</td>  <td>No</td> </tr>
<tr> <td>Storage</td>  <td>Yes</td>  <td>No</td>  <td>Yes</td> <td>No</td> </tr>

</table>
<p>
<p>

<h1><a name="Names">Names, Passwords and Authorization</a></h1>
In order for one daemon to contact another daemon, it must
authorize itself with a password. In most cases, the password
corresponds to a particular name, so both the name and the
password must match to be authorized.
<p>The default configuration files are automatically defined
for correct authorization with random passwords. If you add to
or modify these files, you will need to take care to keep
them consistent.                       
<p>
Here is sort of a picture of what names/passwords in which
files/Resources must match up:
<pre>
Director -- bacula-dir.conf:       Console -- bconsole.conf
Director {                         Director {
  Name = fw-dir   <========|====>    Name = fw-dir
  Password = aaa  <=============>    Pasword = aaa 
  ...                      |         ...
}                          |       }
                           |
                           |       ======================
                           |       SD -- bacula-sd.conf
Storage {                  |       Device {
  Name = fw-sd             |         ...
  Device = DDS-4    <============>   Name = DDS-4
  MediaType = DDS-4 <============>   MediaType = DDS-4
 *Address = fd-sd          |         ...
  Password = bbb  <=====|  |       }
  ...                   |  |       Director {
}                       |  |===>     Name = fw-dir
                        |======>     Password = bbb
                           |       }
                           |
                           |       =====================
                           |       FD -- bacula-fd.conf
Client {                   |       Director {
  Name = fw-fd             |===>     Name = fw-dir
  Password = ccc  <============>     Password = ccc
  ...                                ...
}                                  }
</pre>
In the left column, you will find the Director, Storage, and
Client resources, with their names and passwords -- these
are all in <b>bacula-dir.conf</b>.  In the right column
are where the corresponding values should be found in the
Console, Storage daemon (SD), and File daemon (FD) configuration
files.                                              
<p>Please note that the Address, <b>fd-sd</b>, that appears in the Storage         
resource of the Director, preceded with 
and asterisk in the above example, is passed
to the File daemon in symbolic form. The File daemon then
resolves it to an IP address. For this reason, you
must use either an IP address or a fully qualified name. A name
such as <b>localhost</b>, not being a fully qualified name,
will resolve in the File daemon to the
localhost of the File daemon, which is most likely not what
is desired. The password used for the File daemon to authorize 
with the Storage daemon is a temporary password unique to
each Job created by the daemons and is not specified in any .conf file.

<p>
<h2>Detailed Information for each Daemon</h2>
The details of each Resource and the directives permitted therein are
described in the following chapters.  
<p>
The following configuration files must be defined:
<ul> 
   <li><a href="consoleconf.html">Console</a> -- to define the resources for
       the Console program (user interface to the Director).
       It defines which Directors are
       available so that you may interact with them. </li>
  <li><a href="dirdconf.html">Director</a> -- to define the resources
      necessary for the Director. You define all the Clients
      and Storage daemons that you use in this configuration file.
      </li>
  <li><a href="filedconf.html">Client</a> -- to define the resources for
      each client to be backed up. That is, you will have a separate
      Client resource file on each machine that runs a File daemon. </li> 
  <li><a href="storedconf.html">Storage</a> -- to define the resources to
       be used by each Storage daemon. Normally, you will have
       a single Storage daemon that controls your tape drive or tape
       drives. However, if you have tape drives on several  machines,
       you will have at least one Storage daemon per machine.
       </li>
</ul>

<page_prev name="Installing Bacula" url="install.html">
<page_next name="Director Configuration" url="dirdconf.html">
