%%
%%
-\section*{Customizing the Configuration Files}
-\label{_ChapterStart16}
+\chapter{Customizing the Configuration Files}
+\label{ConfigureChapter}
\index[general]{Files!Customizing the Configuration }
\index[general]{Customizing the Configuration Files }
-\addcontentsline{toc}{section}{Customizing the Configuration Files}
When each of the Bacula programs starts, it reads a configuration file
specified on the command line or the default {\bf bacula-dir.conf}, {\bf
(thanks to Aristides Maniatis for the above graphic)
\label{ResFormat}
-\subsection*{Resource Directive Format}
+\section{Character Sets}
+\index[general]{Character Sets}
+Bacula is designed to handle most character sets of the world,
+US ASCII, German, French, Chinese, ... However, it does this by
+encoding everything in UTF-8, and it expects all configuration files
+(including those read on Win32 machines) to be in UTF-8 format.
+UTF-8 is typically the default on Linux machines, but not on all
+Unix machines, nor on Windows, so you must take some care to ensure
+that your locale is set properly before starting Bacula.
+
+To ensure that Bacula configuration files can be correctly read including
+foreign characters the {bf LANG} environment variable
+must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The
+exact syntax may vary a bit from OS to OS, and exactly how you define
+it will also vary. On most newer Win32 machines, you can use {\bf notepad}
+to edit the conf files, then choose output encoding UTF-8.
+
+Bacula assumes that all filenames are in UTF-8 format on Linux and
+Unix machines. On Win32 they are in Unicode (UTF-16), and will
+be automatically converted to UTF-8 format.
+
+\section{Resource Directive Format}
\index[general]{Resource Directive Format }
\index[general]{Format!Resource Directive }
-\addcontentsline{toc}{subsection}{Resource Directive Format}
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
lower case characters and spaces.
Each resource definition MUST contain a Name directive, and may optionally
-contain a Description directive (or record). The Name directive is used to
+contain a Description directive. 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:
\end{verbatim}
\normalsize
-Defines the Director resource with the name ``MyDir'' and a working directory
+Defines the Director resource with the name "MyDir" 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.
-\label{Comments}
+quoted strings and unquoted strings are all equal.
-\subsubsection*{Comments}
-\index[general]{Comments }
-\addcontentsline{toc}{subsubsection}{Comments}
+\label{Comments}
+\subsection{Comments}
+\index[general]{Comments}
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
this manual, you will not see many semicolons.
\label{Case1}
-\subsubsection*{Upper and Lower Case and Spaces}
-\index[general]{Spaces!Upper and Lower Case and }
-\index[general]{Upper and Lower Case and Spaces }
-\addcontentsline{toc}{subsubsection}{Upper and Lower Case and Spaces}
+\subsection{Upper and Lower Case and Spaces}
+\index[general]{Spaces!Upper/Lower Case}
+\index[general]{Upper and Lower Case and Spaces}
Case (upper/lower) and spaces are totally ignored in the resource directive
keywords (the part before the equal sign).
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 (\textbackslash{}) is taken as itself (handy for inserting
-blackslashes and double quotes (``).
+backslashes and double quotes (")).
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.
-\label{Includes}
+names (e.g. Volume names) must contain only letters (including ISO accented
+letters), numbers, and a few special characters (space, underscore, ...).
+All other characters and punctuation are invalid.
-\subsubsection*{Including other Configuration Files}
+\label{Includes}
+\subsection{Including other Configuration Files}
\index[general]{Including other Configuration Files }
\index[general]{Files!Including other Configuration }
-\addcontentsline{toc}{subsubsection}{Including other Configuration Files}
+\index[general]{Using @ to include other files}
+\index[general]{@{\bf filename}}
If you wish to break your configuration file into smaller pieces, you can do
so by including other files using the syntax @{\bf filename} where {\bf
filename} is the full path and filename of another file. The @filename
-specification can be given anywhere a primitive token would appear.
-\label{DataTypes}
+specification can be given anywhere a primitive token would appear.
-\subsubsection*{Recognized Primitive Data Types}
+\label{DataTypes}
+\subsection{Recognized Primitive Data Types}
\index[general]{Types!Recognized Primitive Data }
\index[general]{Recognized Primitive Data Types }
-\addcontentsline{toc}{subsubsection}{Recognized Primitive Data Types}
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
\begin{description}
\item [name]
- \index[fd]{name }
+ \index[fd]{name}
A keyword or name consisting of alphanumeric characters, including the
hyphen, underscore, and dollar characters. The first character of a {\bf
name} must be a letter. A name has a maximum length currently set to 127
be quoted.
\item [name-string]
- \index[fd]{name-string }
+ \index[fd]{name-string}
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.
+right side of an equal (i.e. they are values to be associated with a keyword).
\item [string]
- \index[fd]{string }
+ \index[fd]{string}
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. Likewise to include a backslash.
\item [directory]
- \index[dir]{directory }
+ \index[dir]{directory}
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 {\bf \$HOME} are interpreted to be their correct values.
\item [password]
- \index[dir]{password }
- This is a Bacula password and it is stored internally in MD5 hashed format.
+ \index[dir]{password}
+ This is a Bacula password and it is stored internally in MD5 hashed format.
\item [integer]
- \index[dir]{integer }
- A 32 bit integer value. It may be positive or negative.
+ \index[dir]{integer}
+ A 32 bit integer value. It may be positive or negative.
\item [positive integer]
\index[dir]{positive integer }
A 32 bit positive integer value.
\item [long integer]
- \index[dir]{long integer }
+ \index[dir]{long integer}
A 64 bit integer value. Typically these are values such as bytes that can
exceed 4 billion and thus require a 64 bit value.
\item [yes|no]
- \index[dir]{yes|no }
+ \index[dir]{yes or no }
Either a {\bf yes} or a {\bf no}.
-\item [
- \label{Size1}
- size]
-\index[dir]{a name }
+\label{Size1}
+\item [size]
+\index[dir]{size}
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
modifiers are permitted:
\begin{description}
-
\item [k]
1,024 (kilobytes)
\item [gb]
1,000,000,000 (gigabytes)
- \end{description}
-
-\item {\bf
- \label{Time}
- time}
-\index[dir]{a name }
-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:
+\end{description}
+
+\label{Time}
+\item [time]
+\index[dir]{time}
+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 modifier is mandatory and follows the number part,
+either with or without intervening spaces. The following modifiers are
+permitted:
\begin{description}
\item [seconds]
- \index[dir]{seconds }
- seconds
+ \index[dir]{seconds}
+ seconds
\item [minutes]
- \index[dir]{minutes }
+ \index[dir]{minutes}
minutes (60 seconds)
\item [hours]
hours (3600 seconds)
\item [days]
- \index[dir]{days }
+ \index[dir]{days}
days (3600*24 seconds)
\item [weeks]
- \index[dir]{weeks }
- weeks (3600*24*7 seconds)
+ \index[dir]{weeks}
+ weeks (3600*24*7 seconds)
\item [months]
\index[dir]{months }
years (3600*24*365 seconds)
\end{description}
-Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds} may
-be specified as {\bf sec} or {\bf s}. A specification of {\bf m} will be
-taken as months.
+Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds}
+may be specified as {\bf sec} or {\bf s}). A specification of {\bf m} will
+be taken as months.
-The specification of a time may have as many number/modifier parts as you wish.
-For example:
+The specification of a time may have as many number/modifier parts as you
+wish. For example:
\footnotesize
\begin{verbatim}
\end{verbatim}
\normalsize
-are valid date specifications (beginning with version 1.35.1).
+are valid date specifications.
-Note! in Bacula version 1.31 and below, the modifier was optional. It is now
-mandatory.
\end{description}
\label{ResTypes}
-
-\subsection*{Resource Types}
+\section{Resource Types}
\index[general]{Types!Resource }
\index[general]{Resource Types }
-\addcontentsline{toc}{subsection}{Resource Types}
The following table lists all current Bacula resource types. It shows what
resources must be defined for each service (daemon). The default configuration
\multicolumn{1}{c| }{\bf Client } & \multicolumn{1}{c| }{\bf Storage } &
\multicolumn{1}{c| }{\bf Console } \\
\hline
+{Autochanger } & {No } & {No } & {Yes } & {No } \\
+\hline
{Catalog } & {Yes } & {No } & {No } & {No } \\
\hline
{Client } & {Yes } & {Yes } & {No } & {No } \\
\end{longtable}
-\subsection*{Names, Passwords and Authorization}
+\section{Names, Passwords and Authorization}
\label{Names}
\index[general]{Authorization!Names Passwords and }
\index[general]{Names, Passwords and Authorization }
-\addcontentsline{toc}{subsection}{Names, Passwords and Authorization}
+\index[general]{Passwords}
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.
+so both the name and the password must match to be authorized. Passwords are
+plain text, any text. They are not generated by any special process; just
+use random text.
The default configuration files are automatically defined for correct
authorization with random passwords. If you add to or modify these files, you
unique to each Job created by the daemons and is not specified in any .conf
file.
-\subsection*{Detailed Information for each Daemon}
+\section{Detailed Information for each Daemon}
\index[general]{Detailed Information for each Daemon }
\index[general]{Daemon!Detailed Information for each }
-\addcontentsline{toc}{subsection}{Detailed Information for each Daemon}
The details of each Resource and the directives permitted therein are
described in the following chapters.
\begin{itemize}
\item
- \ilink{Console}{_ChapterStart36} -- to define the resources for
+ \ilink{Console}{ConsoleConfChapter} -- 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.
\item
- \ilink{Director}{_ChapterStart40} -- to define the resources
+ \ilink{Director}{DirectorChapter} -- to define the resources
necessary for the Director. You define all the Clients and Storage daemons
that you use in this configuration file.
\item
- \ilink{Client}{_ChapterStart25} -- to define the resources for
+ \ilink{Client}{FiledConfChapter} -- 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.
\item
- \ilink{Storage}{_ChapterStart31} -- to define the resources to
+ \ilink{Storage}{StoredConfChapter} -- 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
projects / bacula / docs / blobdiff