Debian Codegraph @

manuals/en/main/configure.tex

raw
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}