| 1 |
\chapter{Customizing the Configuration Files} |
| 2 |
\label{blb:ConfigureChapter} |
| 3 |
\index[general]{Files!Customizing the Configuration} |
| 4 |
\index[general]{Customizing the Configuration Files} |
| 5 |
|
| 6 |
When each of the \bacula{} programs starts, it reads a configuration file |
| 7 |
specified on the command line or the default \bfilename{bacula-dir.conf}, \bfilename{bacula-fd.conf}, |
| 8 |
\bfilename{bacula-sd.conf}, or \bfilename{console.conf} for the Director |
| 9 |
daemon, the File daemon, the Storage daemon, and the Console program |
| 10 |
respectively. |
| 11 |
|
| 12 |
Each service (Director, Client, Storage, Console) has its own configuration |
| 13 |
file containing a set of Resource definitions. These resources are very |
| 14 |
similar from one service to another, but may contain different directives |
| 15 |
(records) depending on the service. For example, in the Director's resource |
| 16 |
file, the \textbf{\bresourcename{Director}} resource defines the name of the Director, a number |
| 17 |
of global Director parameters and his password. In the File daemon |
| 18 |
configuration file, the \textbf{\bresourcename{Director}} resource specifies which Directors are |
| 19 |
permitted to use the File daemon. |
| 20 |
|
| 21 |
Before running \bacula{} for the first time, you must customize the configuration |
| 22 |
files for each daemon. Default configuration files will have been created by |
| 23 |
the installation process, but you will need to modify them to correspond to |
| 24 |
your system. An overall view of the resources can be seen in the following: |
| 25 |
|
| 26 |
\bimageH{bacula-objects}{\bacula{} Objects}{blb:figconfig:baculaobjects} |
| 27 |
\label{blb:ResFormat} |
| 28 |
|
| 29 |
\section{Character Sets} |
| 30 |
\index[general]{Character Sets} |
| 31 |
\bacula{} is designed to handle most character sets of the world, |
| 32 |
US ASCII, German, French, Chinese, \ldots{} However, it does this by |
| 33 |
encoding everything in UTF-8, and it expects all configuration files |
| 34 |
(including those read on Win32 machines) to be in UTF-8 format. |
| 35 |
UTF-8 is typically the default on Linux machines, but not on all |
| 36 |
Unix machines, nor on Windows, so you must take some care to ensure |
| 37 |
that your locale is set properly before starting \bacula{}. |
| 38 |
|
| 39 |
To ensure that \bacula{} configuration files can be correctly read including |
| 40 |
foreign characters the \textbf{LANG} environment variable |
| 41 |
must end in \textbf{.UTF-8}. An full example is \textbf{en\_US.UTF-8}. The |
| 42 |
exact syntax may vary a bit from \acs{OS} to \acs{OS}, and exactly how you define |
| 43 |
it will also vary. On most newer Win32 machines, you can use \btool{notepad} |
| 44 |
to edit the conf files, then choose output encoding UTF-8. |
| 45 |
|
| 46 |
\bacula{} assumes that all filenames are in UTF-8 format on Linux and |
| 47 |
Unix machines. On Win32 they are in Unicode (UTF-16), and will |
| 48 |
be automatically converted to UTF-8 format. |
| 49 |
|
| 50 |
\section{Resource Directive Format} |
| 51 |
\index[general]{Resource Directive Format} |
| 52 |
\index[general]{Format!Resource Directive} |
| 53 |
|
| 54 |
Although, you won't need to know the details of all the directives a basic |
| 55 |
knowledge of \bacula{} resource directives is essential. Each directive contained |
| 56 |
within the resource (within the braces) is composed of a keyword followed by |
| 57 |
an equal sign (=) followed by one or more values. The keywords must be one of |
| 58 |
the known \bacula{} resource record keywords, and it may be composed of upper or |
| 59 |
lower case characters and spaces. |
| 60 |
|
| 61 |
Each resource definition MUST contain a Name directive, and may optionally |
| 62 |
contain a Description directive. The Name directive is used to |
| 63 |
uniquely identify the resource. The Description directive is (will be) used |
| 64 |
during display of the Resource to provide easier human recognition. For |
| 65 |
example: |
| 66 |
|
| 67 |
\begin{bVerbatim} |
| 68 |
Director { |
| 69 |
Name = "MyDir" |
| 70 |
Description = "Main Bacula Director" |
| 71 |
WorkingDirectory = "$HOME/bacula/bin/working" |
| 72 |
} |
| 73 |
\end{bVerbatim} |
| 74 |
|
| 75 |
Defines the Director resource with the name "MyDir" and a working directory |
| 76 |
\bdirectoryname{\$HOME/bacula/bin/working}. In general, if you want spaces in a name to the |
| 77 |
right of the first equal sign (=), you must enclose that name within double |
| 78 |
quotes. Otherwise quotes are not generally necessary because once defined, |
| 79 |
quoted strings and unquoted strings are all equal. |
| 80 |
|
| 81 |
\label{blb:Comments} |
| 82 |
\subsection{Comments} |
| 83 |
\index[general]{Comments} |
| 84 |
|
| 85 |
When reading the configuration file, blank lines are ignored and everything |
| 86 |
after a hash sign (\#) until the end of the line is taken to be a comment. A |
| 87 |
semicolon (;) is a logical end of line, and anything after the semicolon is |
| 88 |
considered as the next statement. If a statement appears on a line by itself, |
| 89 |
a semicolon is not necessary to terminate it, so generally in the examples in |
| 90 |
this manual, you will not see many semicolons. |
| 91 |
\label{blb:Case1} |
| 92 |
|
| 93 |
\subsection{Upper and Lower Case and Spaces} |
| 94 |
\index[general]{Spaces!Upper/Lower Case} |
| 95 |
\index[general]{Upper and Lower Case and Spaces} |
| 96 |
|
| 97 |
Case (upper/lower) and spaces are totally ignored in the resource directive |
| 98 |
keywords (the part before the equal sign). |
| 99 |
|
| 100 |
Within the keyword (i.e. before the equal sign), spaces are not significant. |
| 101 |
Thus the keywords: \textbf{name}, \textbf{Name}, and \textbf{N a m e} are all |
| 102 |
identical. |
| 103 |
|
| 104 |
Spaces after the equal sign and before the first character of the value are |
| 105 |
ignored. |
| 106 |
|
| 107 |
In general, spaces within a value are significant (not ignored), and if the |
| 108 |
value is a name, you must enclose the name in double quotes for the spaces to |
| 109 |
be accepted. Names may contain up to 127 characters. Currently, a name may |
| 110 |
contain any \acs{ASCII} character. Within a quoted string, any character following a |
| 111 |
backslash (\textbackslash{}) is taken as itself (handy for inserting |
| 112 |
backslashes and double quotes (")). |
| 113 |
|
| 114 |
Please note, however, that \bacula{} resource names as well as certain other |
| 115 |
names (e.g. Volume names) must contain only letters (including \acs{ISO} accented |
| 116 |
letters), numbers, and a few special characters (space, underscore, dash, dot, colon). |
| 117 |
All other characters and punctuation are invalid. |
| 118 |
|
| 119 |
\label{blb:Includes} |
| 120 |
\subsection{Including other Configuration Files} |
| 121 |
\index[general]{Including other Configuration Files} |
| 122 |
\index[general]{Files!Including other Configuration} |
| 123 |
\index[general]{Using @ to include other files} |
| 124 |
\index[general]{@\bfilename{filename}} |
| 125 |
|
| 126 |
If you wish to break your configuration file into smaller pieces, you can do |
| 127 |
so by including other files using the syntax @\bfilename{filename} where |
| 128 |
\bfilename{filename} is the full path and filename of another file. The @filename |
| 129 |
specification can be given anywhere a primitive token would appear. |
| 130 |
|
| 131 |
If you wish include all files in a specific directory, you can use the following: |
| 132 |
\begin{bVerbatim} |
| 133 |
# Include subfiles associated with configuration of clients. |
| 134 |
# They define the bulk of the Clients, Jobs, and FileSets. |
| 135 |
# Remember to "reload" the Director after adding a client file. |
| 136 |
# |
| 137 |
@|"sh -c 'for f in /etc/bacula/clientdefs/*.conf ; do echo @${f} ; done'" |
| 138 |
\end{bVerbatim} |
| 139 |
|
| 140 |
\label{blb:DataTypes} |
| 141 |
\subsection{Recognized Primitive Data Types} |
| 142 |
\index[general]{Types!Recognized Primitive Data} |
| 143 |
\index[general]{Recognized Primitive Data Types} |
| 144 |
|
| 145 |
When parsing the resource directives, \bacula{} classifies the data according to |
| 146 |
the types listed below. The first time you read this, it may appear a bit |
| 147 |
overwhelming, but in reality, it is all pretty logical and straightforward. |
| 148 |
|
| 149 |
\begin{bdescription} |
| 150 |
|
| 151 |
\item [name] |
| 152 |
\index[fd]{name} |
| 153 |
A keyword or name consisting of alphanumeric characters, including the |
| 154 |
hyphen, underscore, and dollar characters. The first character of a \textbf{name} |
| 155 |
must be a letter. A name has a maximum length currently set to 127 |
| 156 |
bytes. Typically keywords appear on the left side of an equal (i.e. they are |
| 157 |
\bacula{} keywords -- i.e. Resource names or directive names). Keywords may not |
| 158 |
be quoted. |
| 159 |
|
| 160 |
\item [name-string] |
| 161 |
\index[fd]{name-string} |
| 162 |
A name-string is similar to a name, except that the name may be quoted and |
| 163 |
can thus contain additional characters including spaces. Name strings are |
| 164 |
limited to 127 characters in length. Name strings are typically used on the |
| 165 |
right side of an equal (i.e. they are values to be associated with a keyword). |
| 166 |
|
| 167 |
|
| 168 |
\item [string] |
| 169 |
\index[fd]{string} |
| 170 |
A quoted string containing virtually any character including spaces, or a |
| 171 |
non-quoted string. A string may be of any length. Strings are typically |
| 172 |
values that correspond to filenames, directories, or system command names. A |
| 173 |
backslash (\textbackslash{}) turns the next character into itself, so to |
| 174 |
include a double quote in a string, you precede the double quote with a |
| 175 |
backslash. Likewise to include a backslash. |
| 176 |
|
| 177 |
\item [directory] |
| 178 |
\index[dir]{directory} |
| 179 |
A directory is either a quoted or non-quoted string. A directory will be |
| 180 |
passed to your standard shell for expansion when it is scanned. Thus |
| 181 |
constructs such as \bdirectoryname{\$HOME} are interpreted to be their correct values. |
| 182 |
|
| 183 |
\item [password] |
| 184 |
\index[dir]{password} |
| 185 |
This is a \bacula{} password and it is stored internally in MD5 hashed format. |
| 186 |
|
| 187 |
\item [integer] |
| 188 |
\index[dir]{integer} |
| 189 |
A 32 bit integer value. It may be positive or negative. |
| 190 |
|
| 191 |
\item [positive integer] |
| 192 |
\index[dir]{positive integer} |
| 193 |
A 32 bit positive integer value. |
| 194 |
|
| 195 |
\item [long integer] |
| 196 |
\index[dir]{long integer} |
| 197 |
A 64 bit integer value. Typically these are values such as bytes that can |
| 198 |
exceed 4 billion and thus require a 64 bit value. |
| 199 |
|
| 200 |
\item [\byesorno{}] |
| 201 |
\index[dir]{yes or no} |
| 202 |
Either a \textbf{yes} or a \textbf{no}. |
| 203 |
|
| 204 |
\label{blb:Size1} |
| 205 |
\item [size] |
| 206 |
\index[dir]{size} |
| 207 |
A size specified as bytes. Typically, this is a floating point scientific |
| 208 |
input format followed by an optional modifier. The floating point input is |
| 209 |
stored as a 64 bit integer value. If a modifier is present, it must |
| 210 |
immediately follow the value with no intervening spaces. The following |
| 211 |
modifiers are permitted: |
| 212 |
|
| 213 |
\begin{bdescription} |
| 214 |
\item [k] |
| 215 |
1,024 (kilobytes) |
| 216 |
|
| 217 |
\item [kb] |
| 218 |
1,000 (kilobytes) |
| 219 |
|
| 220 |
\item [m] |
| 221 |
1,048,576 (megabytes) |
| 222 |
|
| 223 |
\item [mb] |
| 224 |
1,000,000 (megabytes) |
| 225 |
|
| 226 |
\item [g] |
| 227 |
1,073,741,824 (gigabytes) |
| 228 |
|
| 229 |
\item [gb] |
| 230 |
1,000,000,000 (gigabytes) |
| 231 |
\end{bdescription} |
| 232 |
|
| 233 |
\label{blb:Time} |
| 234 |
\item [time] |
| 235 |
\index[dir]{time} |
| 236 |
A time or duration specified in seconds. The time is stored internally as |
| 237 |
a 64 bit integer value, but it is specified in two parts: a number part and |
| 238 |
a modifier part. The number can be an integer or a floating point number. |
| 239 |
If it is entered in floating point notation, it will be rounded to the |
| 240 |
nearest integer. The modifier is mandatory and follows the number part, |
| 241 |
either with or without intervening spaces. The following modifiers are |
| 242 |
permitted: |
| 243 |
|
| 244 |
\begin{bdescription} |
| 245 |
|
| 246 |
\item [seconds] |
| 247 |
\index[dir]{seconds} |
| 248 |
seconds |
| 249 |
|
| 250 |
\item [minutes] |
| 251 |
\index[dir]{minutes} |
| 252 |
minutes (60 seconds) |
| 253 |
|
| 254 |
\item [hours] |
| 255 |
\index[dir]{hours} |
| 256 |
hours (3600 seconds) |
| 257 |
|
| 258 |
\item [days] |
| 259 |
\index[dir]{days} |
| 260 |
days (3600*24 seconds) |
| 261 |
|
| 262 |
\item [weeks] |
| 263 |
\index[dir]{weeks} |
| 264 |
weeks (3600*24*7 seconds) |
| 265 |
|
| 266 |
\item [months] |
| 267 |
\index[dir]{months} |
| 268 |
months (3600*24*30 seconds) |
| 269 |
|
| 270 |
\item [quarters] |
| 271 |
\index[dir]{quarters} |
| 272 |
quarters (3600*24*91 seconds) |
| 273 |
|
| 274 |
\item [years] |
| 275 |
\index[dir]{years} |
| 276 |
years (3600*24*365 seconds) |
| 277 |
\end{bdescription} |
| 278 |
|
| 279 |
Any abbreviation of these modifiers is also permitted (i.e. \textbf{seconds} |
| 280 |
may be specified as \textbf{sec} or \textbf{s}). A specification of \textbf{m} will |
| 281 |
be taken as months. |
| 282 |
|
| 283 |
The specification of a time may have as many number/modifier parts as you |
| 284 |
wish. For example: |
| 285 |
|
| 286 |
\begin{bVerbatim} |
| 287 |
1 week 2 days 3 hours 10 mins |
| 288 |
1 month 2 days 30 sec |
| 289 |
|
| 290 |
\end{bVerbatim} |
| 291 |
|
| 292 |
are valid date specifications. |
| 293 |
|
| 294 |
\end{bdescription} |
| 295 |
|
| 296 |
\label{blb:ResTypes} |
| 297 |
\section{Resource Types} |
| 298 |
\index[general]{Types!Resource} |
| 299 |
\index[general]{Resource Types} |
| 300 |
|
| 301 |
The table \vref{blb:director:resource:types} lists all current \bacula{} resource types. It shows what |
| 302 |
resources must be defined for each service (daemon). The default configuration |
| 303 |
files will already contain at least one example of each permitted resource, so |
| 304 |
you need not worry about creating all these kinds of resources from scratch. |
| 305 |
|
| 306 |
\LTXtable{\linewidth}{t-main-resources} |
| 307 |
|
| 308 |
\section{Names, Passwords and Authorization} |
| 309 |
\label{blb:Names} |
| 310 |
\index[general]{Authorization!Names Passwords and} |
| 311 |
\index[general]{Names, Passwords and Authorization} |
| 312 |
\index[general]{Passwords} |
| 313 |
|
| 314 |
In order for one daemon to contact another daemon, it must authorize itself |
| 315 |
with a password. In most cases, the password corresponds to a particular name, |
| 316 |
so both the name and the password must match to be authorized. Passwords are |
| 317 |
plain text, any text. They are not generated by any special process; just |
| 318 |
use random text. |
| 319 |
|
| 320 |
The default configuration files are automatically defined for correct |
| 321 |
authorization with random passwords. If you add to or modify these files, you |
| 322 |
will need to take care to keep them consistent. |
| 323 |
|
| 324 |
Here is sort of a picture of what names/passwords in which files/Resources |
| 325 |
must match up: |
| 326 |
|
| 327 |
\bimageH{Conf-Diagram}{Configuration diagram}{blb:figconfig:configdiagram} |
| 328 |
|
| 329 |
In the left column, you will find the Director, Storage, and Client resources, |
| 330 |
with their names and passwords -- these are all in \bfilename{bacula-dir.conf}. In |
| 331 |
the right column are where the corresponding values should be found in the |
| 332 |
Console, Storage daemon (SD), and File daemon (FD) configuration files. |
| 333 |
|
| 334 |
Please note that the Address, \textbf{fd-sd}, that appears in the Storage |
| 335 |
resource of the Director, preceded with and asterisk in the above example, is |
| 336 |
passed to the File daemon in symbolic form. The File daemon then resolves it |
| 337 |
to an IP address. For this reason, you must use either an IP address or a |
| 338 |
fully qualified name. A name such as \textbf{localhost}, not being a fully |
| 339 |
qualified name, will resolve in the File daemon to the localhost of the File |
| 340 |
daemon, which is most likely not what is desired. The password used for the |
| 341 |
File daemon to authorize with the Storage daemon is a temporary password |
| 342 |
unique to each Job created by the daemons and is not specified in any .conf |
| 343 |
file. |
| 344 |
|
| 345 |
\section{Detailed Information for each Daemon} |
| 346 |
\index[general]{Detailed Information for each Daemon} |
| 347 |
\index[general]{Daemon!Detailed Information for each} |
| 348 |
|
| 349 |
The details of each Resource and the directives permitted therein are |
| 350 |
described in the following chapters. |
| 351 |
|
| 352 |
The following configuration files must be defined: |
| 353 |
|
| 354 |
\begin{bitemize} |
| 355 |
\item |
| 356 |
\bilink{Console}{blb:ConsoleConfChapter} -- to define the resources for |
| 357 |
the Console program (user interface to the Director). It defines which |
| 358 |
Directors are available so that you may interact with them. |
| 359 |
\item |
| 360 |
\bilink{Director}{blb:DirectorChapter} -- to define the resources |
| 361 |
necessary for the Director. You define all the Clients and Storage daemons |
| 362 |
that you use in this configuration file. |
| 363 |
\item |
| 364 |
\bilink{Client}{blb:FiledConfChapter} -- to define the resources for |
| 365 |
each client to be backed up. That is, you will have a separate Client |
| 366 |
resource file on each machine that runs a File daemon. |
| 367 |
\item |
| 368 |
\bilink{Storage}{blb:StoredConfChapter} -- to define the resources to |
| 369 |
be used by each Storage daemon. Normally, you will have a single Storage |
| 370 |
daemon that controls your tape drive or tape drives. However, if you have |
| 371 |
tape drives on several machines, you will have at least one Storage daemon |
| 372 |
per machine. |
| 373 |
\end{bitemize} |