git.sur5r.net Git - bacula/docs/blob - docs/manuals/en/main/configure.tex

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