4 \chapter{Customizing the Configuration Files}
5 \label{ConfigureChapter}
6 \index[general]{Files!Customizing the Configuration }
7 \index[general]{Customizing the Configuration Files }
9 When each of the Bacula programs starts, it reads a configuration file
10 specified on the command line or the default {\bf bacula-dir.conf}, {\bf
11 bacula-fd.conf}, {\bf bacula-sd.conf}, or {\bf console.conf} for the Director
12 daemon, the File daemon, the Storage daemon, and the Console program
15 Each service (Director, Client, Storage, Console) has its own configuration
16 file containing a set of Resource definitions. These resources are very
17 similar from one service to another, but may contain different directives
18 (records) depending on the service. For example, in the Director's resource
19 file, the {\bf Director} resource defines the name of the Director, a number
20 of global Director parameters and his password. In the File daemon
21 configuration file, the {\bf Director} resource specifies which Directors are
22 permitted to use the File daemon.
24 Before running Bacula for the first time, you must customize the configuration
25 files for each daemon. Default configuration files will have been created by
26 the installation process, but you will need to modify them to correspond to
27 your system. An overall view of the resources can be seen in the following:
29 \addcontentsline{lof}{figure}{Bacula Objects}
30 \includegraphics{\idir bacula-objects.eps}
33 \section{Character Sets}
34 \index[general]{Character Sets}
35 Bacula is designed to handle most character sets of the world,
36 US ASCII, German, French, Chinese, ... However, it does this by
37 encoding everything in UTF-8, and it expects all configuration files
38 (including those read on Win32 machines) to be in UTF-8 format.
39 UTF-8 is typically the default on Linux machines, but not on all
40 Unix machines, nor on Windows, so you must take some care to ensure
41 that your locale is set properly before starting Bacula.
43 To ensure that Bacula configuration files can be correctly read including
44 foreign characters the {bf LANG} environment variable
45 must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
46 exact syntax may vary a bit from OS to OS, and exactly how you define
47 it will also vary. On most newer Win32 machines, you can use {\bf notepad}
48 to edit the conf files, then choose output encoding UTF-8.
50 Bacula assumes that all filenames are in UTF-8 format on Linux and
51 Unix machines. On Win32 they are in Unicode (UTF-16), and will
52 be automatically converted to UTF-8 format.
54 \section{Resource Directive Format}
55 \index[general]{Resource Directive Format }
56 \index[general]{Format!Resource Directive }
58 Although, you won't need to know the details of all the directives a basic
59 knowledge of Bacula resource directives is essential. Each directive contained
60 within the resource (within the braces) is composed of a keyword followed by
61 an equal sign (=) followed by one or more values. The keywords must be one of
62 the known Bacula resource record keywords, and it may be composed of upper or
63 lower case characters and spaces.
65 Each resource definition MUST contain a Name directive, and may optionally
66 contain a Description directive. The Name directive is used to
67 uniquely identify the resource. The Description directive is (will be) used
68 during display of the Resource to provide easier human recognition. For
75 Description = "Main Bacula Director"
76 WorkingDirectory = "$HOME/bacula/bin/working"
81 Defines the Director resource with the name "MyDir" and a working directory
82 \$HOME/bacula/bin/working. In general, if you want spaces in a name to the
83 right of the first equal sign (=), you must enclose that name within double
84 quotes. Otherwise quotes are not generally necessary because once defined,
85 quoted strings and unquoted strings are all equal.
89 \index[general]{Comments}
91 When reading the configuration file, blank lines are ignored and everything
92 after a hash sign (\#) until the end of the line is taken to be a comment. A
93 semicolon (;) is a logical end of line, and anything after the semicolon is
94 considered as the next statement. If a statement appears on a line by itself,
95 a semicolon is not necessary to terminate it, so generally in the examples in
96 this manual, you will not see many semicolons.
99 \subsection{Upper and Lower Case and Spaces}
100 \index[general]{Spaces!Upper/Lower Case}
101 \index[general]{Upper and Lower Case and Spaces}
103 Case (upper/lower) and spaces are totally ignored in the resource directive
104 keywords (the part before the equal sign).
106 Within the keyword (i.e. before the equal sign), spaces are not significant.
107 Thus the keywords: {\bf name}, {\bf Name}, and {\bf N a m e} are all
110 Spaces after the equal sign and before the first character of the value are
113 In general, spaces within a value are significant (not ignored), and if the
114 value is a name, you must enclose the name in double quotes for the spaces to
115 be accepted. Names may contain up to 127 characters. Currently, a name may
116 contain any ASCII character. Within a quoted string, any character following a
117 backslash (\textbackslash{}) is taken as itself (handy for inserting
118 backslashes and double quotes (")).
120 Please note, however, that Bacula resource names as well as certain other
121 names (e.g. Volume names) must contain only letters (including ISO accented
122 letters), numbers, and a few special characters (space, underscore, ...).
123 All other characters and punctuation are invalid.
126 \subsection{Including other Configuration Files}
127 \index[general]{Including other Configuration Files }
128 \index[general]{Files!Including other Configuration }
129 \index[general]{Using @ to include other files}
130 \index[general]{@{\bf filename}}
132 If you wish to break your configuration file into smaller pieces, you can do
133 so by including other files using the syntax @{\bf filename} where {\bf
134 filename} is the full path and filename of another file. The @filename
135 specification can be given anywhere a primitive token would appear.
137 If you wish include all files in a specific directory, you can use the following:
139 # Include subfiles associated with configuration of clients.
140 # They define the bulk of the Clients, Jobs, and FileSets.
141 # Remember to "reload" the Director after adding a client file.
143 @|"sh -c 'for f in /etc/bacula/clientdefs/*.conf ; do echo @${f} ; done'"
147 \subsection{Recognized Primitive Data Types}
148 \index[general]{Types!Recognized Primitive Data }
149 \index[general]{Recognized Primitive Data Types }
151 When parsing the resource directives, Bacula classifies the data according to
152 the types listed below. The first time you read this, it may appear a bit
153 overwhelming, but in reality, it is all pretty logical and straightforward.
159 A keyword or name consisting of alphanumeric characters, including the
160 hyphen, underscore, and dollar characters. The first character of a {\bf
161 name} must be a letter. A name has a maximum length currently set to 127
162 bytes. Typically keywords appear on the left side of an equal (i.e. they are
163 Bacula keywords -- i.e. Resource names or directive names). Keywords may not
167 \index[fd]{name-string}
168 A name-string is similar to a name, except that the name may be quoted and
169 can thus contain additional characters including spaces. Name strings are
170 limited to 127 characters in length. Name strings are typically used on the
171 right side of an equal (i.e. they are values to be associated with a keyword).
176 A quoted string containing virtually any character including spaces, or a
177 non-quoted string. A string may be of any length. Strings are typically
178 values that correspond to filenames, directories, or system command names. A
179 backslash (\textbackslash{}) turns the next character into itself, so to
180 include a double quote in a string, you precede the double quote with a
181 backslash. Likewise to include a backslash.
184 \index[dir]{directory}
185 A directory is either a quoted or non-quoted string. A directory will be
186 passed to your standard shell for expansion when it is scanned. Thus
187 constructs such as {\bf \$HOME} are interpreted to be their correct values.
190 \index[dir]{password}
191 This is a Bacula password and it is stored internally in MD5 hashed format.
195 A 32 bit integer value. It may be positive or negative.
197 \item [positive integer]
198 \index[dir]{positive integer }
199 A 32 bit positive integer value.
202 \index[dir]{long integer}
203 A 64 bit integer value. Typically these are values such as bytes that can
204 exceed 4 billion and thus require a 64 bit value.
207 \index[dir]{yes or no }
208 Either a {\bf yes} or a {\bf no}.
213 A size specified as bytes. Typically, this is a floating point scientific
214 input format followed by an optional modifier. The floating point input is
215 stored as a 64 bit integer value. If a modifier is present, it must
216 immediately follow the value with no intervening spaces. The following
217 modifiers are permitted:
227 1,048,576 (megabytes)
230 1,000,000 (megabytes)
233 1,073,741,824 (gigabytes)
236 1,000,000,000 (gigabytes)
242 A time or duration specified in seconds. The time is stored internally as
243 a 64 bit integer value, but it is specified in two parts: a number part and
244 a modifier part. The number can be an integer or a floating point number.
245 If it is entered in floating point notation, it will be rounded to the
246 nearest integer. The modifier is mandatory and follows the number part,
247 either with or without intervening spaces. The following modifiers are
266 days (3600*24 seconds)
270 weeks (3600*24*7 seconds)
274 months (3600*24*30 seconds)
277 \index[dir]{quarters }
278 quarters (3600*24*91 seconds)
282 years (3600*24*365 seconds)
285 Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds}
286 may be specified as {\bf sec} or {\bf s}). A specification of {\bf m} will
289 The specification of a time may have as many number/modifier parts as you
294 1 week 2 days 3 hours 10 mins
295 1 month 2 days 30 sec
300 are valid date specifications.
305 \section{Resource Types}
306 \index[general]{Types!Resource }
307 \index[general]{Resource Types }
309 The following table lists all current Bacula resource types. It shows what
310 resources must be defined for each service (daemon). The default configuration
311 files will already contain at least one example of each permitted resource, so
312 you need not worry about creating all these kinds of resources from scratch.
314 \addcontentsline{lot}{table}{Resource Types}
315 \begin{longtable}{|l|l|l|l|l|}
317 \multicolumn{1}{|c| }{\bf Resource } & \multicolumn{1}{c| }{\bf Director } &
318 \multicolumn{1}{c| }{\bf Client } & \multicolumn{1}{c| }{\bf Storage } &
319 \multicolumn{1}{c| }{\bf Console } \\
321 {Autochanger } & {No } & {No } & {Yes } & {No } \\
323 {Catalog } & {Yes } & {No } & {No } & {No } \\
325 {Client } & {Yes } & {Yes } & {No } & {No } \\
327 {Console } & {Yes } & {No } & {No } & {Yes } \\
329 {Device } & {No } & {No } & {Yes } & {No } \\
331 {Director } & {Yes } & {Yes } & {Yes } & {Yes } \\
333 {FileSet } & {Yes } & {No } & {No } & {No } \\
335 {Job } & {Yes } & {No } & {No } & {No } \\
337 {JobDefs } & {Yes } & {No } & {No } & {No } \\
339 {Message } & {Yes } & {Yes } & {Yes } & {No } \\
341 {Pool } & {Yes } & {No } & {No } & {No } \\
343 {Schedule } & {Yes } & {No } & {No } & {No } \\
345 {Storage } & {Yes } & {No } & {Yes } & {No }
350 \section{Names, Passwords and Authorization}
352 \index[general]{Authorization!Names Passwords and }
353 \index[general]{Names, Passwords and Authorization }
354 \index[general]{Passwords}
356 In order for one daemon to contact another daemon, it must authorize itself
357 with a password. In most cases, the password corresponds to a particular name,
358 so both the name and the password must match to be authorized. Passwords are
359 plain text, any text. They are not generated by any special process; just
362 The default configuration files are automatically defined for correct
363 authorization with random passwords. If you add to or modify these files, you
364 will need to take care to keep them consistent.
366 Here is sort of a picture of what names/passwords in which files/Resources
369 \includegraphics{\idir Conf-Diagram.eps}
371 In the left column, you will find the Director, Storage, and Client resources,
372 with their names and passwords -- these are all in {\bf bacula-dir.conf}. In
373 the right column are where the corresponding values should be found in the
374 Console, Storage daemon (SD), and File daemon (FD) configuration files.
376 Please note that the Address, {\bf fd-sd}, that appears in the Storage
377 resource of the Director, preceded with and asterisk in the above example, is
378 passed to the File daemon in symbolic form. The File daemon then resolves it
379 to an IP address. For this reason, you must use either an IP address or a
380 fully qualified name. A name such as {\bf localhost}, not being a fully
381 qualified name, will resolve in the File daemon to the localhost of the File
382 daemon, which is most likely not what is desired. The password used for the
383 File daemon to authorize with the Storage daemon is a temporary password
384 unique to each Job created by the daemons and is not specified in any .conf
387 \section{Detailed Information for each Daemon}
388 \index[general]{Detailed Information for each Daemon }
389 \index[general]{Daemon!Detailed Information for each }
391 The details of each Resource and the directives permitted therein are
392 described in the following chapters.
394 The following configuration files must be defined:
398 \ilink{Console}{ConsoleConfChapter} -- to define the resources for
399 the Console program (user interface to the Director). It defines which
400 Directors are available so that you may interact with them.
402 \ilink{Director}{DirectorChapter} -- to define the resources
403 necessary for the Director. You define all the Clients and Storage daemons
404 that you use in this configuration file.
406 \ilink{Client}{FiledConfChapter} -- to define the resources for
407 each client to be backed up. That is, you will have a separate Client
408 resource file on each machine that runs a File daemon.
410 \ilink{Storage}{StoredConfChapter} -- to define the resources to
411 be used by each Storage daemon. Normally, you will have a single Storage
412 daemon that controls your tape drive or tape drives. However, if you have
413 tape drives on several machines, you will have at least one Storage daemon