diff options
Diffstat (limited to 'manuals/en/main/configure.tex')
| -rw-r--r-- | manuals/en/main/configure.tex | 1065 |
1 files changed, 0 insertions, 1065 deletions
diff --git a/manuals/en/main/configure.tex b/manuals/en/main/configure.tex deleted file mode 100644 index bd5cac7..0000000 --- a/manuals/en/main/configure.tex +++ /dev/null @@ -1,1065 +0,0 @@ -\chapter{Customizing the Configuration} -\label{ConfigureChapter} -\index[general]{Customizing the Configuration} - -Each Bareos component (Director, Client, Storage, Console) has its own configuration -containing a set of resource definitions. These resources are very -similar from one service to another, but may contain different directives -(records) depending on the component. For example, in the Director configuration, -the \nameref{DirectorResourceDirector} defines the name of the Director, a number -of global Director parameters and his password. In the File daemon -configuration, the \nameref{ClientResourceDirector} specifies which Directors are -permitted to use the File daemon. - -If you install all Bareos daemons (Director, Storage and File Daemon) onto one system, -the Bareos package tries its best to generate a working configuration as a basis for your individual configuration. - -The details of each resource and the directives permitted therein are -described in the following chapters. - -The following configuration files must be present: - -\begin{itemize} -\item - \nameref{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 - \nameref{StoredConfChapter} -- to define the resources to - be used by each Storage daemon. Normally, you will have a single Storage - daemon that controls your disk storage or tape drives. However, if you have - tape drives on several machines, you will have at least one Storage daemon - per machine. -\item - \nameref{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 - \nameref{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. -\end{itemize} - - -\section{Configuration Path Layout} -\label{sec:ConfigurationPathLayout} -\index[general]{Configuration!Directories} -\index[general]{Configuration!Subdirectories} - -When a Bareos component starts, it reads its configuration. -In Bareos $<$ 16.2.2 only configuration files (which optionally can include other files) are supported. -Since Bareos \sinceVersion{}{Subdirectory Configuration Scheme}{16.2.2} also configuration subdirectories are supported. - -\subsubsection{Naming} - -In this section, the following naming is used: - -\begin{itemize} - \item \path|$CONFIGDIR|\hide{$} refers to the base configuration directory. - Bareos Linux packages use \configPathUnix. - \item A component is one of the following Bareos programs: - \begin{itemize} - \item bareos-dir - \item bareos-sd - \item bareos-fd - \item bareos-traymonitor - \item bconsole - \item bat (only legacy config file: bat.conf) - \item Bareos tools, like \nameref{sec:VolumeUtilityCommands} and others. - \end{itemize} - \item \path|$COMPONENT|\hide{$} refers to one of the listed components. -% -% \item Legacy config file (still fully supported, with some -% limitation when using the configuration API): -% \begin{itemize} -% \item \path|$CONFIGDIR/$COMPONENT.conf| -% \end{itemize} -\end{itemize} - -\subsection{What configuration will be used?} -\label{sec:ConfigurationFileOrConfigurationSubDirectories} - -When starting a Bareos component, it will look for its configuration. -Bareos components allow the configuration file/directory to be specified as a command line parameter \path|-c $PATH|\hide{$}. - -\begin{itemize} - \item configuration path parameter is not given (default) - \begin{itemize} - \item \path|$CONFIGDIR/$COMPONENT.conf| is a file - \begin{itemize} - \item the configuration is read from the file \path|$CONFIGDIR/$COMPONENT.conf| - \end{itemize} - \item \path|$CONFIGDIR/$COMPONENT.d/| is a directory - \begin{itemize} - \item the configuration is read from \path|$CONFIGDIR/$COMPONENT.d/*/*.conf| (subdirectory configuration) - \end{itemize} - \end{itemize} - \item configuration path parameter is given (\path|-c $PATH|) - \begin{itemize} - \item \path|$PATH| is a file - \begin{itemize} - \item the configuration is read from the file specified in \path|$PATH| - \end{itemize} - \item \path|$PATH| is a directory - \begin{itemize} - \item the configuration is read from \path|$PATH/$COMPONENT.d/*/*.conf| (subdirectory configuration) - \end{itemize} - \end{itemize} -\end{itemize} - -As the \path|$CONFIGDIR|\hide{$} differs between platforms or is overwritten by the path parameter, -the documentation will often refer to the configuration without the leading path -(e.g. \path|$COMPONENT.d/*/*.conf|\hide{$} instead of \path|$CONFIGDIR/$COMPONENT.d/*/*.conf|). - -\begin{center} -\includegraphics[width=0.8\linewidth]{\idir bareos-read-configuration} -\end{center} - - -When subdirectory configuration is used, -all files matching \path|$PATH/$COMPONENT.d/*/*.conf| will be read, see \nameref{sec:ConfigurationSubdirectories}. - -\paragraph{Relation between Bareos components and configuration} - -\begin{center} -\begin{tabular}{ l || l | l } -Bareos component & -\shortstack[l]{Configuration File \\ (default path on Unix)} & -\shortstack[l]{Subdirectory Configuration Scheme\\ (default path on Unix) \\ since Bareos $>=$ 16.2.2} \\ -\hline -\hline - -bareos-dir & \file{bareos-dir.conf} & \file{bareos-dir.d} \\ -\nameref{DirectorChapter} & (\configFileDirUnix) & (\configDirectoryDirUnix) \\ -\hline - -bareos-sd & \file{bareos-sd.conf} & \file{bareos-sd.d} \\ -\nameref{StoredConfChapter} & (\configFileSdUnix) & (\configDirectorySdUnix) \\ -\hline - -bareos-fd & \file{bareos-fd.conf} & \file{bareos-fd.d} \\ -\nameref{FiledConfChapter} & (\configFileFdUnix) & (\configDirectoryFdUnix) \\ -\hline - -bconsole & \file{bconsole.conf} & \file{bconsole.d} \\ -\nameref{ConsoleConfChapter} & (\configFileBconsoleUnix) & (\configDirectoryBconsoleUnix) \\ -\hline - -bareos-traymonitor & \file{tray-monitor.conf} & \file{tray-monitor.d} \\ -\nameref{sec:MonitorConfig} & (\configFileTrayMonitorUnix) & (\configDirectoryTrayMonitorUnix) \\ -\hline - -bat & \file{bat.conf} & (not supported) \\ - & ({\configFileBatUnix}) & \\ -\hline - -\nameref{sec:VolumeUtilityCommands} & \file{bareos-sd.conf} & \file{bareos-sd.d} \\ -(use the bareos-sd configuration) & (\configFileSdUnix) & (\configDirectorySdUnix) \\ - -\end{tabular} -\end{center} - - - -\subsection{Subdirectory Configuration Scheme} -\label{sec:SubdirectoryConfigurationScheme} -\label{sec:ConfigurationSubdirectories} -% ConfigurationIncludeDirectory is referenced from the Bareos code. -\label{ConfigurationIncludeDirectory} - -If the subdirectory configuration is used, instead of a single configuration file, -all files matching \path|$COMPONENT.d/*/*.conf|\hide{$} are read as a configuration, -see \nameref{sec:ConfigurationFileOrConfigurationSubDirectories}. - -\subsubsection{Reason for the Subdirectory Configuration Scheme} - -In Bareos $<$ 16.2.2, Bareos uses one configuration file per component. - -Most larger Bareos environments split their configuration into separate -files, making it easier to manage the configuration. - -Also some extra packages (bareos-webui, plugins, ...) require a configuration, -which must be included into the \bareosDir or \bareosSd configuration. -The subdirectory approach makes it easier to add or modify the configuration resources of different Bareos packages. - -The Bareos \ilink{configure}{sec:bcommandConfigure} command -requires a configuration directory structure, as provided by the subdirectory approach. - -From Bareos \sinceVersion{}{Subdirectory Configuration Scheme used as Default}{16.2.4} on, -new installations will use configuration subdirectories by default. - - -\subsubsection{Resource file conventions} - \label{sec:ConfigurationResourceFileConventions} - -\begin{itemize} -\item Each configuration resource has to use its own configuration file. -\item The path of a resource file is \path|$COMPONENT.d/$RESOURCETYPE/$RESOURCENAME.conf|. -\item The name of the configuration file is identical with the resource name: - \begin{itemize} - \item e.g. - \begin{itemize} - \item \path|bareos-dir.d/director/bareos-dir.conf| - \item \path|bareos-dir.d/pool/Full.conf| - \end{itemize} - \item Exceptions: - \begin{itemize} - \item The resource file \path|bareos-fd.d/client/myself.conf| always has the file name \path|myself.conf|, - while the name is normally set to the hostname of the system. - \end{itemize} - \end{itemize} -\item Example resource files: - \begin{itemize} - \item Additional packages can contain configuration files that are automatically included. However, most additional configuration resources require configuration. When a resource file requires configuration, it has to be included as an example file: - \begin{itemize} - \item \path|$CONFIGDIR/$COMPONENT.d/$RESOURCE/$NAME.conf.example| - \item For example, the \bareosWebui entails one config resource and one config resource example for the \bareosDir: - \begin{itemize} - \item \path|$CONFIGDIR/bareos-director.d/profile/webui-admin.conf| - \item \path|$CONFIGDIR/bareos-director.d/console/admin.conf.example|\hide{$} - \end{itemize} - \end{itemize} - \end{itemize} -\item \hypertarget{sec:deleteConfigurationResourceFiles}Disable/remove configuration resource files: - \begin{itemize} - \item Normally you should not remove resources that are already in use (jobs, clients, ...). Instead you should disable them by adding the directive \configline{Enable = no}. Otherwise you take the risk that orphaned entries are kept in the Bareos catalog. However, if a resource has not been used or all references have been cleared from the database, they can also be removed from the configuration. - \warning{If you want to remove a configuration resource that is part of a Bareos package, - replace the resource configuration file by an empty file. - This prevents the resource from reappearing in the course of a package update.} - \end{itemize} -\end{itemize} - - - -\subsubsection{Using Subdirectories Configuration Scheme} - -\paragraph{New installation} - -\begin{itemize} - \item The Subdirectories Configuration Scheme is used - by default from Bareos \sinceVersion{}{Subdirectory Configuration Scheme used as Default}{16.2.4} onwards. - \item They will be usable immediately after installing a Bareos component. - \item If additional packages entail example configuration files (\path|$NAME.conf.example|), - copy them to \path|$NAME.conf|, modify it as required and reload or restart the component. -\end{itemize} - -\paragraph{Updates from Bareos $<$ 16.2.4} - \label{sec:UpdateToConfigurationSubdirectories} - -\begin{itemize} -\item When updating to a Bareos version containing the Subdirectories Configuration, - the existing configuration will not be touched and is still the default configuration. - \begin{itemize} - \item \warning{Problems can occur if you have implemented an own wildcard mechanism to load your configuration - from the same subdirectories as used by the new packages (\path|$CONFIGDIR/$COMPONENT.d/*/*.conf|). - In this case, newly installed configuration resource files can alter - your current configuration by adding resources.} - Best create a copy of your configuration directory before updating Bareos - and modify your existing configuration file to use that other directory. - \end{itemize} -\item As long as the old configuration file (\path|$CONFIGDIR/$COMPONENT.conf|) exists, it will be used. -\item The correct way of migrating to the new configuration scheme would be - to split the configuration file into resources, - store them in the resource directories and then remove the original configuration file. - \begin{itemize} - \item For migrating the \bareosDir configuration, the script \bareosMigrateConfigSh exists. - Being called, it connects via \command{bconsole} to a running \bareosDir and creates subdirectories with the resource configuration files. - \begin{commands}{\bareosMigrateConfigSh} -# prepare temporary directory -mkdir /tmp/baroes-dir.d -cd /tmp/baroes-dir.d - -# download migration script -wget https://raw.githubusercontent.com/bareos/bareos-contrib/master/misc/bareos-migrate-config/bareos-migrate-config.sh - -# execute the script -bash bareos-migrate-config.sh - -# backup old configuration -mv /etc/bareos/bareos-dir.conf /etc/bareos/bareos-dir.conf.bak -mv /etc/bareos/bareos-dir.d /etc/bareos/bareos-dir.d.bak - -# make sure, that all packaged configuration resources exists, -# otherwise they will be added when updating Bareos. -for i in `find /etc/bareos/bareos-dir.d.bak/ -name *.conf -type f -printf "%P\n"`; do touch "$i"; done - -# install newly generated configuration -cp -a /tmp/bareos-dir.d /etc/bareos/ - \end{commands} - Restart the \bareosDir and verify your configuration. - Also make sure, that all resource configuration files coming from Bareos packages exists, in doubt as empty files, see \hyperlink{sec:deleteConfigurationResourceFiles}{remove configuration resource files}. - - \item Another way, without splitting the configuration into resource files is: - \begin{itemize} - \item \begin{commands}{move configuration to subdirectory} -mkdir $CONFIGDIR/$COMPONENT.d/migrate && mv $CONFIGDIR/$COMPONENT.conf $CONFIGDIR/$COMPONENT.d/migrate - \end{commands} - \item Resources defined in both, the new configuration directory scheme - and the old configuration file, must be removed from one of the places, - best from the old configuration file, - after verifying that the settings are identical with the new settings. - \end{itemize} - \end{itemize} -\end{itemize} - -\section{Configuration File Format} - -A configuration file consists of one or more resources (see \nameref{sec:ConfigurationResourceFormat}). - -Bareos programs can work with -\begin{itemize} - \item all resources defined in one configuration file - \item configuration files that include other configuration files (see \nameref{Includes}) - \item \nameref{sec:ConfigurationSubdirectories}, where each configuration file contains exactly one resource definition -\end{itemize} - - - -\subsection{Character Sets} -\index[general]{Character Sets} -Bareos 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 Bareos. - -\index[general]{Windows!Configuration Files!UTF-8} -To ensure that Bareos configuration files can be correctly read including -foreign characters, the {\bf LANG} environment variable -must end in {\bf .UTF-8}. A full example is {\bf en\_US.UTF-8}. The -exact syntax may vary a bit from OS to OS, so that the way you have to define -it will differ from the example. On most newer Win32 machines you can use \command{notepad} -to edit the conf files, then choose output encoding UTF-8. - -Bareos assumes that all filenames are in UTF-8 format on Linux and -Unix machines. On Win32 they are in Unicode (UTF-16) and will hence -be automatically converted to UTF-8 format. - -\subsection{Comments} -\label{Comments} -\index[general]{Configuration!Comments} - -When reading a configuration, blank lines are ignored and everything -after a hash sign (\#) until the end of the line is taken to be a comment. - -\subsection{Semicolons} -A semicolon (;) is a logical end of line and anything after the semicolon is -considered as the next statement. If a statement appears on a line by itself, -a semicolon is not necessary to terminate it, so generally in the examples in -this manual, you will not see many semicolons. - -\subsection{Including other Configuration Files} -\label{Includes} -\index[general]{Including other Configuration Files} -\index[general]{Files!Including other Configuration} -\index[general]{Configuration!Including Files} - -If you wish to break your configuration file into smaller pieces, you can do -so by including other files using the syntax \configdirective{@filename} -where \file{filename} is the full path and filename of another file. -The \configdirective{@filename} -specification can be given anywhere a primitive token would appear. - -\begin{bconfig}{include a configuration file} -@/etc/bareos/extra/clients.conf -\end{bconfig} - -Since Bareos \sinceVersion{}{Including configuration files by wildcard}{16.2.1} wildcards in pathes are supported: -\begin{bconfig}{include multiple configuration files} -@/etc/bareos/extra/*.conf -\end{bconfig} - -% Before -% this could be archived by -% If you wish include all files in a specific directory, you can use the following: -% \begin{bconfig}{include configuration files} -% # Include subfiles associated with configuration of clients. -% # They define the bulk of the Clients, Jobs, and FileSets. -% # Remember to "reload" the Director after adding a client file. -% # -% @|"sh -c 'for f in /etc/bareos/clientdefs/*.conf ; do echo @${f} ; done'" -% \end{bconfig} -% \hide{$} - -By using \configdirective{@|command} it is also possible to include the output of a script as a configuration: -\begin{bconfig}{use the output of a script as configuration} -@|"/etc/bareos/generate_configuration_to_stdout.sh" -\end{bconfig} -or if a parameter should be used: -\begin{bconfig}{use the output of a script with parameter as a configuration} -@|"sh -c '/etc/bareos/generate_client_configuration_to_stdout.sh clientname=client1.example.com'" -\end{bconfig} -The scripts are called at the start of the daemon. You should use this with care. - - -\section{Resource} -\label{sec:ConfigurationResourceFormat} -\index[general]{Configuration!Resource} - -A resource is defined as the resource type (see \nameref{ResTypes}), -followed by an open brace (\path|{|), a number of \nameref{sec:ConfigurationResourceDirective}s, and ended by a closing brace (\path|}|) - -\hide{ -\begin{bconfig}{Resource} -$RESOURCETYPE { - Name = $RESOURCENAME - $KEY1 = $VALUE1 - $KEY2 = $VALUE2 -} -\end{bconfig} -} - -Each resource definition MUST contain a \configdirective{Name} directive. -It can contain a \configdirective{Description} directive. -The \configdirective{Name} directive is used to -uniquely identify the resource. -The \configdirective{Description} directive can be used -during the display of the Resource to provide easier human recognition. For -example: - -\begin{bconfig}{Resource example} -Director { - Name = "bareos-dir" - Description = "Main Bareos Director" - Query File = "/usr/lib/bareos/scripts/query.sql" -} -\end{bconfig} - -defines the Director resource with the name \parameter{bareos-dir} and a query file \file{/usr/lib/bareos/scripts/query.sql}. - -\index[general]{Configuration!Naming Convention} - -When naming resources, for some resource types naming conventions should be applied: -\begin{description} - \item[Client] names should be postfixed with \name{-fd} - \item[Storage] names should be postfixed with \name{-sd} - \item[Director] names should be postfixed with \name{-dir} -\end{description} -These conventions helps a lot when reading log messages. - - -\subsection{Resource Directive} -\label{sec:ConfigurationResourceDirective} - -Each directive contained -within the resource (within the curly braces \path|{}|) is composed of a \nameref{sec:ConfigurationResourceDirectiveKeyword} followed by -an equal sign (=) followed by a \nameref{sec:ConfigurationResourceDirectiveValue}. The keywords must be one of -the known Bareos resource record keywords. - - -\subsection{Resource Directive Keyword} -\label{sec:ConfigurationResourceDirectiveKeyword} - -A resource directive keyword is the part before the equal sign (\path|=|) in a \nameref{sec:ConfigurationResourceDirective}. -The following sections will list all available directives by Bareos component resources. - -\subsubsection{Upper and Lower Case and Spaces} - -Case (upper/lower) and spaces are ignored in the resource directive -keywords. - -Within the keyword (i.e. before the equal sign), spaces are not significant. -Thus the keywords: {\bf name}, {\bf Name}, and {\bf N a m e} are all -identical. - - -\subsection{Resource Directive Value} -\label{sec:ConfigurationResourceDirectiveValue} - -A resource directive value is the part after the equal sign (\path|=|) in a \nameref{sec:ConfigurationResourceDirective}. - -\subsubsection{Spaces} - -Spaces after the equal sign and before the first character of the value are -ignored. Other spaces within a value may be significant (not ignored) -and may require quoting. - - -\subsubsection{Quotes} -\label{sec:Quotes} -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. - - Within a quoted string, any character following a -backslash (\textbackslash{}) is taken as itself (handy for inserting -backslashes and double quotes (")). - -\warning{If the configure directive is used to define a number, the number is never to be put between surrounding quotes. -This is even true if the number is specified together with its unit, like \parameter{365 days}}. - -\subsubsection{Numbers} - -Numbers are not to be quoted, see \nameref{sec:Quotes}. -Also do not prepend numbers by zeros (0), as these are not parsed in the expected manner (write 1 instead of 01). - -\subsubsection{Data Types} -\index[general]{Configuration!Data Types} -\index[general]{Data Type} -\label{DataTypes} - -When parsing the resource directives, Bareos classifies the data according to -the types listed below. - -\begin{description} - -\item [acl] - \index[general]{Data Type!acl} - \label{DataTypeAcl} -This directive defines what is permitted to be accessed. -It does this by using a list of regular expressions, separated by commas (\argument{,}) -or using multiple directives. -If \argument{!} is prepended, the expression is negated. -The special keyword \parameter{*all*} allows unrestricted access. - -Depending on the type of the ACL, the regular expressions can be either resource names, paths or console commands. - -Since Bareos \sinceVersion{dir}{ACL: strict regular expression handling}{16.2.4} regular expression are handled more strictly. Before also substring matches has been accepted. - -\label{sec:CommandAclExample} -For clarification, we demonstrate the usage of ACLs by some examples for \linkResourceDirective{Dir}{Console}{Command ACL}: -\begin{bconfig}{Allow only the help command} -Command ACL = help -\end{bconfig} - -\begin{bconfig}{Allow the help and the list command} -Command ACL = help, list -\end{bconfig} - -\begin{bconfig}{Allow the help and the (not existing) iDoNotExist command} -Command ACL = help, iDoNotExist -\end{bconfig} - -\begin{bconfig}{Allow all commands (special keyword)} -Command ACL = *all* -\end{bconfig} - -\begin{bconfig}{Allow all commands except sqlquery and commands starting with u} -Command ACL = !sqlquery, !u.*, *all* -\end{bconfig} - -Same: -\begin{bconfig}{Some as above. Specifying it in multiple lines doesn't change the meaning} -Command ACL = !sqlquery, !u.* -Command ACL = *all* -\end{bconfig} - -\begin{bconfig}{Additional deny the setip and setdebug commands} -Command ACL = !sqlquery -Command ACL = !u.* -Comamnd ACL = !set(ip|debug) -Comamnd ACL = *all* -\end{bconfig} - -\warning{ -ACL checking stops at the first match. So the following definition allows all commands, which might not be what you expected: -} -\begin{bconfig}{Wrong: Allows all commands} -# WARNING: this configuration ignores !sqlquery, as *all* is matched before. -Command ACL = *all*, !sqlquery -\end{bconfig} - -\item [auth-type] - \index[general]{Data Type!auth-type} - \label{DataTypeAuthType} -Specifies the authentication type that must be supplied when connecting to -a backup protocol that uses a specific authentication type. -Currently only used for \nameref{NDMPResource}. - -The following values are allowed: -\begin{description} -\item[None] - Use no password -\item[Clear] - Use clear text password -\item[MD5] - Use MD5 hashing -\end{description} - - -\item [integer] - \index[general]{Data Type!integer} - \label{DataTypeInteger} - A 32 bit integer value. It may be positive or negative. - - Don't use quotes around the number, see \nameref{sec:Quotes}. - - -\item [long integer] - \index[general]{Data Type!long integer} - \label{DataTypeLongInteger} - A 64 bit integer value. Typically these are values such as bytes that can -exceed 4 billion and thus require a 64 bit value. - - Don't use quotes around the number, see \nameref{sec:Quotes}. - -\item [job protocol] - \index[general]{Data Type!job protocol} - \label{DataTypeJobProtocol} - -The protocol to run a the job. -Following protocols are available: -\begin{description} - \item[Native] Native Bareos job protocol. - \item[NDMP] Deprecated. Alias for \NdmpBareos. - \item[NDMP\_BAREOS] Since Bareos \sinceVersion{dir}{NDMP BAREOS}{17.2.3}. See \nameref{sec:NdmpBareos}. - \item[NDMP\_NATIVE] Since Bareos \sinceVersion{dir}{NDMP NATIVE}{17.2.3}. See \nameref{sec:NdmpNative}. -\end{description} - - - -\item [name] - \index[general]{Data Type!name} - \label{DataTypeName} - 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 -bytes. - -Please note that Bareos resource names as well as certain other -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. - - -\item [password] - \index[general]{Data Type!password} - \label{DataTypePassword} - This is a Bareos password and it is stored internally in MD5 hashed format. - - -% \item [path] -% \index[general]{Data Type!path} -% \label{DataTypePath} -% File name, including path. - -\item [path] - \index[general]{Data Type!path} - \label{DataTypeDirectory} - A path is either a quoted or non-quoted string. A path 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. -The path can either reference to a file or a directory. - - -\item [positive integer] - \index[general]{Data Type!positive integer} - \label{DataTypePositiveInteger} - A 32 bit positive integer value. - - Don't use quotes around the number, see \nameref{sec:Quotes}. - - -\item [speed] - \index[general]{Data Type!speed} - \label{DataTypeSpeed} - The speed parameter can be specified as k/s, kb/s, m/s or mb/s. - - Don't use quotes around the parameter, see \nameref{sec:Quotes}. - - -\item [string] - \index[general]{Data Type!string} - \label{DataTypeString} - 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 (\textbackslash{}) turns the next character into itself, so to -include a double quote in a string, you precede the double quote with a -backslash. Likewise to include a backslash. - - -\item [string-list] - \index[general]{Data Type!string list} - \label{DataTypeStringList} - Multiple strings, specified in multiple directives, or in a single directive, separated by commas (\textbf{,}). - -\item [strname] - \index[general]{Data Type!strname} - \label{DataTypeStrname} -is similar to a \dtName, except that the name may be quoted and -can thus contain additional characters including spaces. - - -\item [net-address] - \index[general]{Data Type!net-address} - \label{DataTypeNetAddress} -is either a domain name or an IP address specified as a -dotted quadruple in string or quoted string format. -This directive only permits a single address to be specified. -The \dtNetPort\ must be specificly separated. -If multiple net-addresses are needed, please assess if it is also possible to specify \dtNetAddresses\ (plural). - - -\item [net-addresses] - \index[general]{Data Type!net-addresses} - \label{DataTypeNetAddresses} -Specify a set of net-addresses and net-ports. -Probably the simplest way to explain -this is to show an example: - -\begin{bconfig}{net-addresses} -Addresses = { - ip = { addr = 1.2.3.4; port = 1205;} - ipv4 = { - addr = 1.2.3.4; port = http;} - ipv6 = { - addr = 1.2.3.4; - port = 1205; - } - ip = { - addr = 1.2.3.4 - port = 1205 - } - ip = { addr = 1.2.3.4 } - ip = { addr = 201:220:222::2 } - ip = { - addr = server.example.com - } -} -\end{bconfig} - -where ip, ip4, ip6, addr, and port are all keywords. Note, that the address -can be specified as either a dotted quadruple, or in IPv6 colon notation, or as -a symbolic name (only in the ip specification). Also, the port can be specified -as a number or as the mnemonic value from the \file{/etc/services} file. If a port -is not specified, the default one will be used. If an ip section is specified, -the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then -only IPv4 resolutions will be permitted, and likewise with ip6. - - -\item [net-port] - \index[general]{Data Type!net-port} - \label{DataTypeNetPort} - Specify a network port (a positive integer). - - Don't use quotes around the parameter, see \nameref{sec:Quotes}. - - -\item [resource] - \index[general]{Data Type!resource} - \label{DataTypeRes} -A resource defines a relation to the name of another resource. - - -\item [size] - \index[general]{Data Type!size} - \label{DataTypeSize} - \label{Size1} -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 -immediately follow the value with no intervening spaces. The following -modifiers are permitted: - -\begin{description} -\item [k] - 1,024 (kilobytes) - -\item [kb] - 1,000 (kilobytes) - -\item [m] - 1,048,576 (megabytes) - -\item [mb] - 1,000,000 (megabytes) - -\item [g] - 1,073,741,824 (gigabytes) - -\item [gb] - 1,000,000,000 (gigabytes) -\end{description} - - Don't use quotes around the parameter, see \nameref{sec:Quotes}. - - -\item [time] - \index[general]{Data Type!time} - \label{DataTypeTime} - \label{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} - -\item [minutes] - \index[dir]{minutes} (60 seconds) - -\item [hours] - \index[dir]{hours} (3600 seconds) - -\item [days] - \index[dir]{days} (3600*24 seconds) - -\item [weeks] - \index[dir]{weeks} (3600*24*7 seconds) - -\item [months] - \index[dir]{months} (3600*24*30 seconds) - -\item [quarters] - \index[dir]{quarters} (3600*24*91 seconds) - -\item [years] - \index[dir]{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. - -The specification of a time may have as many number/modifier parts as you -wish. For example: - -\footnotesize -\begin{verbatim} -1 week 2 days 3 hours 10 mins -1 month 2 days 30 sec -\end{verbatim} -\normalsize - -are valid date specifications. - - Don't use quotes around the parameter, see \nameref{sec:Quotes}. - - -\item [audit-command-list] - \index[general]{Data Type!audit command list} - \label{DataTypeAuditCommandList} - Specifies the commands that should be logged on execution (audited). - E.g. -\begin{bconfig}{} -Audit Events = label -Audit Events = restore -\end{bconfig} - Based on the type \dtStringList. - - - -\item [\yesno] - \index[general]{Data Type!\yesno} - \index[general]{Data Type!boolean} - \label{DataTypeYesNo} - Either a \parameter{yes} or a \parameter{no} (or \parameter{true} or \parameter{false}). - - -\end{description} - - - - -\subsubsection{Variable Expansion} - \label{VarsChapter} - -Depending on the directive, Bareos will expand to the following variables: - -\paragraph{Variable Expansion on Volume Labels} -\label{sec:VariableExpansionVolumeLabels} - -When labeling a new volume (see \linkResourceDirective{Dir}{Pool}{Label Format}), following Bareos internal variables can be used: - -\begin{tabular}{p{2cm}p{7cm}} -\textbf{Internal Variable} & \textbf{Description} \\ -\variable{$Year} & Year \\ -\variable{$Month} & Month: 1-12 \\ -\variable{$Day} & Day: 1-31 \\ -\variable{$Hour} & Hour: 0-24 \\ -\variable{$Minute} & Minute: 0-59 \\ -\variable{$Second} & Second: 0-59 \\ -\variable{$WeekDay} & Day of the week: 0-6, using 0 for Sunday\\ -\variable{$Job} & Name of the Job \\ -\variable{$Dir} & Name of the Director \\ -\variable{$Level} & Job Level \\ -\variable{$Type} & Job Type \\ -\variable{$JobId} & JobId \\ -\variable{$JobName} & unique name of a job\\ -\variable{$Storage} & Name of the Storage Daemon\\ -\variable{$Client} & Name of the Clients \\ -\variable{$NumVols} & Numbers of volumes in the pool\\ -\variable{$Pool} & Name of the Pool \\ -\variable{$Catalog} & Name of the Catalog\\ -\variable{$MediaType} & Type of the media -\end{tabular} -\hide{$} - -Additional, normal environment variables can be used, e.g. -\variable{$HOME} oder \variable{$HOSTNAME}. - -With the exception of Job specific variables, you can trigger the variable expansion -by using the \ilink{var command}{var}. - - - -\paragraph{Variable Expansion in Autochanger Commands} - -At the configuration of autochanger commands the following variables can be used: - - -\begin{tabular}{p{2cm}p{7cm}} -\textbf{Variable} & \textbf{Description} \\ -\parameter{\%a} & Archive Device Name\\ -\parameter{\%c} & Changer Device Name\\ -\parameter{\%d} & Changer Drive Index\\ -\parameter{\%f} & Client's Name\\ -\parameter{\%j} & Job Name\\ -\parameter{\%o} & Command\\ -\parameter{\%s} & Slot Base 0\\ -\parameter{\%S} & Slot Base 1\\ -\parameter{\%v} & Volume Name -\end{tabular} - - - -\paragraph{Variable Expansion in Mount Commands} - -At the configuration of mount commands the following variables can be used: - - - -\begin{tabular}{p{2cm}p{7cm}} -\textbf{Variable} & \textbf{Description} \\ -\parameter{\%a} & Archive Device Name\\ -\parameter{\%e} & Erase\\ -\parameter{\%n} & Part Number\\ -\parameter{\%m} & Mount Point\\ -\parameter{\%v} & Last Part Name -\end{tabular} - - - -\paragraph{Variable Expansion on RunScripts} - -Variable Expansion on RunScripts is described at \linkResourceDirective{Dir}{Job}{Run Script}. - - - -\paragraph{Variable Expansion in Mail and Operator Commands} - -At the configuration of mail and operator commands the following variables can be used: - -\begin{tabular}{p{2cm}p{7cm}} -\textbf{Variable} & \textbf{Description} \\ -\parameter{\%c} & Client's Name\\ -\parameter{\%d} & Director's Name\\ -\parameter{\%e} & Job Exit Code\\ -\parameter{\%i} & JobId\\ -\parameter{\%j} & Unique Job Id\\ -\parameter{\%l} & Job Level\\ -\parameter{\%n} & Unadorned Job Name\\ -\parameter{\%s} & Since Time\\ -\parameter{\%t} & Job Type (Backup, ...)\\ -\parameter{\%r} & Recipients\\ -\parameter{\%v} & Read Volume Name\\ -\parameter{\%V} & Write Volume Name\\ -\parameter{\%b} & Job Bytes\\ -\parameter{\%B} & Job Bytes in human readable format \\ -\parameter{\%F} & Job Files -\end{tabular} - - -\subsection{Resource Types} -\index[general]{Types!Resource} -\index[general]{Resource Types} -\label{ResTypes} - -% TODO: is ths section really useful or should it be removed? - -The following table lists all current Bareos resource types. It shows what -resources must be defined for each service (daemon). The default configuration -files will already contain at least one example of each permitted resource. - -\addcontentsline{lot}{table}{Resource Types} -\begin{longtable}{|l||c|c|c|c|} - \hline -\multicolumn{1}{|c|| }{\bf Resource } & -\multicolumn{1}{c| }{ \ilink{Director}{DirectorConfChapter} } & -\multicolumn{1}{c| }{ \ilink{Client}{FiledConfChapter} } & -\multicolumn{1}{c| }{ \ilink{Storage}{StoredConfChapter} } & -\multicolumn{1}{c| }{ \ilink{Console}{ConsoleConfChapter} } \\ - \hline - \hline -{Autochanger} & & & \cmlink{StorageResourceAutochanger} & \\ -\hline -{Catalog } & \cmlink{DirectorResourceCatalog} & & & \\ - \hline -{Client } & \cmlink{DirectorResourceClient} & \cmlink{ClientResourceClient} & & \\ - \hline -{Console } & \cmlink{DirectorResourceConsole} & & & \cmlink{ConsoleResourceConsole} \\ - \hline -{Device } & & & \cmlink{StorageResourceDevice} & \\ - \hline -{Director } & \cmlink{DirectorResourceDirector} & \cmlink{ClientResourceDirector} & \cmlink{StorageResourceDirector} & \cmlink{ConsoleResourceDirector} \\ - \hline -{FileSet } & \cmlink{DirectorResourceFileSet} & & & \\ - \hline -{Job} & \cmlink{DirectorResourceJob} & & & \\ - \hline -{JobDefs } & \cmlink{DirectorResourceJobDefs} & & & \\ - \hline -{Message } & \cmlink{ResourceMessages} & \cmlink{ResourceMessages} & \cmlink{ResourceMessages} & \\ - \hline -{NDMP } & & & \cmlink{StorageResourceNDMP} & \\ - \hline -{Pool } & \cmlink{DirectorResourcePool} & & & \\ - \hline -{Profile} & \cmlink{DirectorResourceProfile} & & & \\ - \hline -{Schedule } & \cmlink{DirectorResourceSchedule} & & & \\ - \hline -{Storage } & \cmlink{DirectorResourceStorage} & & \cmlink{StorageResourceStorage} & \\ -\hline -\end{longtable} - -\section{Names, Passwords and Authorization} -\label{Names} -\index[general]{Authorization!Names and Passwords} -\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. 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 -will need to take care to keep them consistent. - -\label{sec:resource-relation} -\begin{figure}[htbp] -\begin{center} -\includegraphics[width=0.8\textwidth]{\idir Conf-Diagram} -\caption{Relation between resource names and passwords} -%references to this label do not work reliably -%\label{fig:password} -\end{center} -\end{figure} - -%The diagram \ref{fig:password} illustrates what names/passwords in which resources -%must match up. - -In the left column, you can see the Director, Storage, and Client resources and their corresponding names and passwords -- these are all in \file{bareos-dir.conf}. In -the right column the corresponding values in the -Console, Storage daemon (SD), and File daemon (FD) configuration files are shown. - -Please note that the address \host{fw-sd}, that appears in the Storage -resource of the Director, -is passed to the File daemon in symbolic form. The File daemon then resolves it -to an IP address. For this reason you must use either an IP address or a -resolvable fully qualified name. A name such as \host{localhost}, not being a fully -qualified name, will resolve in the File daemon to the \host{localhost} of the File -daemon, which is most likely not what is desired. The password used for the -File daemon to authorize with the Storage daemon is a temporary password -unique to each Job created by the daemons and is not specified in any .conf -file. |