diff --git a/manuals/en/main/bareos.sty b/manuals/en/main/bareos.sty index 413d40a..9bc2732 100644 --- a/manuals/en/main/bareos.sty +++ b/manuals/en/main/bareos.sty @@ -47,6 +47,7 @@ \csdef{dtNetAddress}{\ilink{net-address}{DataTypeNetAddress}} \csdef{dtNetAddresses}{\ilink{net-addresses}{DataTypeNetAddresses}} \csdef{dtNetPort}{\ilink{net-port}{DataTypeNetPort}} +\csdef{dtMessages}{({\lt}address{\gt} =) {\lt}message-type1{\gt}, {\lt}message-type2{\gt}, ... } \csdef{dtPassword}{\ilink{password}{DataTypePassword}} \csdef{dtPath}{\ilink{path}{DataTypePath}} % use csdef instead of newcommand, because command contains numbers diff --git a/manuals/en/main/config/MessagesMailCommand1.conf b/manuals/en/main/config/MessagesMailCommand1.conf new file mode 100644 index 0000000..c19b443 --- /dev/null +++ b/manuals/en/main/config/MessagesMailCommand1.conf @@ -0,0 +1 @@ +Mail Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) \%r\" -s \"Bareos: \%t \%e of \%c \%l\" \%r" diff --git a/manuals/en/main/dirdconf.tex b/manuals/en/main/dirdconf.tex index 888c17f..5f7c069 100644 --- a/manuals/en/main/dirdconf.tex +++ b/manuals/en/main/dirdconf.tex @@ -650,8 +650,7 @@ \section{Messages Resource} \index[general]{Messages Resource} For the details of the Messages Resource, please see the -\ilink{Messages Resource Chapter}{MessagesChapter} of this -manual. +\nameref{MessagesChapter} of this manual. \section{Console Resource} \label{DirectorResourceConsole} diff --git a/manuals/en/main/messagesres.tex b/manuals/en/main/messagesres.tex index dd780fd..0060e8b 100644 --- a/manuals/en/main/messagesres.tex +++ b/manuals/en/main/messagesres.tex @@ -1,5 +1,3 @@ -%% -%% \chapter{Messages Resource} \label{MessagesChapter} @@ -38,7 +36,6 @@ \chapter{Messages Resource} specification followed by a list of {\bf message-types} in the format: \begin{description} - \item [destination = message-type1, message-type2, message-type3, ... ] \index[dir]{Messages!destination} \end{description} @@ -62,218 +59,14 @@ \chapter{Messages Resource} in a message resource. \input{autogenerated/director-resource-messages-table.tex} +\input{resource-messages-definitions.tex} +\input{autogenerated/director-resource-messages-description.tex} -\begin{description} - -\item [Messages] \hfill \\ -\index[dir]{Messages} -Start of the Messages records. - -\item [Name = {\textless}name{\textgreater}] \hfill \\ -\index[dir]{Messages!Name} -The name of the Messages resource. The name you specify here will be used to -tie this Messages resource to a Job and/or to the daemon. - -\label{mailcommand} -\item [MailCommand = {\textless}command{\textgreater}] \hfill \\ -\index[dir]{Messages!MailCommand} -In the absence of this resource, Bareos will send all mail using the -following command: - -{\bf mail -s "Bareos Message" {\textless}recipients{\textgreater}} - -In many cases, depending on your machine, this command may not work. -However, by using the {\bf MailCommand}, you can specify exactly how to -send the mail. During the processing of the {\bf command} part, normally -specified as a quoted string, the following substitutions will be used: - -\begin{itemize} -\item \%\% = \% -\item \%c = Client's name -\item \%d = Director's name -\item \%e = Job Exit code (OK, Error, ...) -\item \%h = Client address -\item \%i = Job Id -\item \%j = Unique Job name -\item \%l = Job level -\item \%n = Job name -\item \%r = Recipients -\item \%s = Since time -\item \%t = Job type (e.g. Backup, ...) -\item \%v = Read Volume name (Only on director side) -\item \%V = Write Volume name (Only on director side) -\end{itemize} - -Please note: any {\bf MailCommand} directive must be specified -in the {\bf Messages} resource {\bf before} the desired -{\bf Mail}, {\bf MailOnSuccess}, or {\bf MailOnError} -directive. In fact, each of those directives may be preceded by -a different {\bf MailCommand}. - -A default installation will use the program {\bf bsmtp} as {\bf mailcommand}. -The program {\bf bsmtp} is provided by Bareos and unifies the usage of a mail client -to a certain degree: - - -\path|mailcommand = "/usr/sbin/bsmtp -h mail.example.com -f -\textbackslash{}"\textbackslash{}(Bareos\textbackslash{}) -\%r\textbackslash{}" -s \textbackslash{}"Bareos: \%t \%e of \%c -\%l\textbackslash{}" \%r"| - -The {\bf bsmtp} program is provided as part of {\bf Bareos}. For -additional details, please see the -\ilink{bsmtp -- Customizing Your Email Messages}{bsmtp} section of -the Bareos Utility Programs chapter of this manual. -Please test any {\bf mailcommand} that you use to ensure that your smtp gateway accepts the -addressing form that you use. Certain programs such as Exim can be very -selective as to what forms are permitted particularly in the from part. - -\item [OperatorCommand = {\textless}command{\textgreater}] \hfill \\ -\index[dir]{OperatorCommand} -This resource specification is similar to the {\bf MailCommand} except that -it is used for Operator messages. The substitutions performed for the {\bf -MailCommand} are also done for this command. Normally, you will set this -command to the same value as specified for the {\bf MailCommand}. -The {\bf OperatorCommand} directive must appear in the {\bf Messages} -resource before the {\bf Operator} directive. - -% \item [{\textless}destination{\textgreater} = {\textless}message-type1{\textgreater}, -% {\textless}message-type2{\textgreater}, ...] \hfill \\ -% \index[fd]{{\textless}destination{\textgreater}} -% where {\bf destination} may be one of the following: -% -% \begin{description} -% \item [stdout] -% \index[fd]{stdout} -% Send the message to standard output. -% -% \item [stderr] -% \index[fd]{stderr} -% Send the message to standard error. -% -% \item [console] -% \index[console]{console} -% Send the message to the console (Bareos Console). These messages are held -% until the console program connects to the Director. -% \end{description} - -\item[{\textless}destination{\textgreater} ( = {\textless}address{\textgreater} ) = -{\textless}message-type1{\textgreater}, {\textless}message-type2{\textgreater}, ...] \hfill \\ -\index[console]{{\textless}destination{\textgreater}} -where {\bf address} depends on the {\bf destination}. - -The {\bf destination} may be one of the following: - -\begin{description} - -\item [director] \hfill \\ -\index[general]{Messages!director} -Send the message to the Director whose name is given in the {\bf address} -field. Note, in the current implementation, the Director Name is ignored, and -the message is sent to the Director that started the Job. - -\item [file] \hfill \\ -\index[general]{Messages!file} -Send the message to the filename given in the {\bf address} field. If the -file already exists, it will be overwritten. - -\item [append] \hfill \\ -\index[general]{Messages!append} -Append the message to the filename given in the {\bf address} field. If the -file already exists, it will be appended to. If the file does not exist, it -will be created. - -\item [syslog] \hfill \\ -\index[general]{Messages!syslog} -Send the message to the system log (syslog) using the facility specified in -the {\bf address} field. Note, for the moment, the {\bf address} field is -ignored and the message is always sent to the LOG\_DAEMON facility with -level LOG\_ERR. See {\bf man 3 syslog} for more details. Example: - -%\TODO{right? address is missing} -\begin{verbatim} -syslog = all, !skipped -\end{verbatim} - -Although the {\bf syslog} destination is not used in the default Bareos -config files, in certain cases where Bareos encounters errors in trying -to deliver a message, as a last resort, it will send it to the system -{\bf syslog} to prevent loss of the message, so you might occassionally -check the {\bf syslog} for Bareos output (normally {\bf -/var/log/syslog}). - -\item [mail] \hfill \\ -\index[general]{Messages!mail} -Send the message to the email addresses that are given as a comma -separated list in the {\bf address} field. Mail messages are grouped -together during a job and then sent as a single email message when the -job terminates. The advantage of this destination is that you are -notified about every Job that runs. However, if you backup mutliple -machines every night, the number of email messages can be annoying. -Some users use filter programs such as {\bf procmail} to automatically -file this email based on the Job termination code (see {\bf -mailcommand}). - -\item [mail on error] \hfill \\ -\index[general]{Messages!mail on error} -Send the message to the email addresses that are given as a comma -separated list in the {\bf address} field if the Job terminates with an -error condition. MailOnError messages are grouped together during a job -and then sent as a single email message when the job terminates. This -destination differs from the {\bf mail} destination in that if the Job -terminates normally, the message is totally discarded (for this -destination). If the Job terminates in error, it is emailed. By using -other destinations such as {\bf append} you can ensure that even if the -Job terminates normally, the output information is saved. - -\item [mail on success] \hfill \\ -\index[general]{Messages!mail on success} -Send the message to the email addresses that are given as a comma -separated list in the {\bf address} field if the Job terminates -normally (no error condition). MailOnSuccess messages are grouped -together during a job and then sent as a single email message when the -job terminates. This destination differs from the {\bf mail} -destination in that if the Job terminates abnormally, the message is -totally discarded (for this destination). If the Job terminates -normally, it is emailed. - -\item [operator] \hfill \\ -\index[general]{Messages!operator} -Send the message to the email addresses that are specified as a comma -separated list in the {\bf address} field. This is similar to {\bf -mail} above, except that each message is sent as received. Thus there -is one email per message. This is most useful for {\bf mount} messages -(see below). - -\item [console] \hfill \\ - \index[general]{Messages!console} - Send the message to the Bareos console. These messages are held - until the console program connects to the Director. - -\item [stdout] \hfill \\ - \index[general]{Messages!stdout} - Send the message to the standard output (normally not used). - -\item [stderr] \hfill \\ - \index[general]{Messages!stderr} - Send the message to the standard error output (normally not used). - -\item [catalog] \hfill \\ -\index[general]{Messages!catalog} -Send the message to the Catalog database. The message will be -written to the table named {\bf Log} and a timestamp field will -also be added. This permits Job Reports and other messages to -be recorded in the Catalog so that they can be accessed by -reporting software. Bareos will prune the Log records associated -with a Job when the Job records are pruned. Otherwise, Bareos -never uses these records internally, so this destination is only -used for special purpose programs (e.g. frontend programs). - -\end{description} +\section{Message Types} +\label{MessageTypes} For any destination, the {\bf message-type} field is a comma separated list of the following types or classes of messages: -\label{MessageTypes} \begin{description} @@ -351,8 +144,6 @@ \chapter{Messages Resource} \end{description} -\end{description} - The following is an example of a valid Messages resource definition, where all messages except files explicitly skipped or daemon termination messages are sent by email to backupoperator@example.com. In addition all mount messages @@ -360,30 +151,26 @@ \chapter{Messages Resource} all messages other than explicitly skipped files and files saved are sent to the console: -\footnotesize -\begin{verbatim} +\begin{bconfig}{Message resource} Messages { Name = Standard - mail = backupoperator@example.com = all, !skipped, !terminate - operator = backupoperator@example.com = mount - console = all, !skipped, !saved + Mail = backupoperator@example.com = all, !skipped, !terminate + Operator = backupoperator@example.com = mount + Console = all, !skipped, !saved } -\end{verbatim} -\normalsize +\end{bconfig} With the exception of the email address, an example Director's Messages resource is as follows: -\footnotesize -\begin{verbatim} +\begin{bconfig}{Message resource} Messages { Name = Standard - mailcommand = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: %t %e of %c %l\" %r" - operatorcommand = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: Intervention needed for %j\" %r" - MailOnError = backupoperator@example.com = all, !skipped, !terminate - append = "/var/log/bareos/bareos.log" = all, !skipped, !terminate - operator = backupoperator@example.com = mount - console = all, !skipped, !saved + Mail Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: %t %e of %c %l\" %r" + Operator Command = "/usr/sbin/bsmtp -h mail.example.com -f \"\(Bareos\) %r\" -s \"Bareos: Intervention needed for %j\" %r" + Mail On Error = backupoperator@example.com = all, !skipped, !terminate + Append = "/var/log/bareos/bareos.log" = all, !skipped, !terminate + Operator = backupoperator@example.com = mount + Console = all, !skipped, !saved } -\end{verbatim} -\normalsize +\end{bconfig} diff --git a/manuals/en/main/resource-messages-definitions.tex b/manuals/en/main/resource-messages-definitions.tex new file mode 100644 index 0000000..14d9e87 --- /dev/null +++ b/manuals/en/main/resource-messages-definitions.tex @@ -0,0 +1,165 @@ +\defDirective{Dir}{Messages}{Append}{}{}{% +Append the message to the filename given in the {\bf address} field. If the +file already exists, it will be appended to. If the file does not exist, it +will be created. +} + +\defDirective{Dir}{Messages}{Catalog}{}{}{% +Send the message to the Catalog database. The message will be +written to the table named {\bf Log} and a timestamp field will +also be added. This permits Job Reports and other messages to +be recorded in the Catalog so that they can be accessed by +reporting software. Bareos will prune the Log records associated +with a Job when the Job records are pruned. Otherwise, Bareos +never uses these records internally, so this destination is only +used for special purpose programs (e.g. frontend programs). +} + +\defDirective{Dir}{Messages}{Console}{}{}{% +Send the message to the Bareos console. These messages are held +until the console program connects to the Director. +} + +\defDirective{Dir}{Messages}{Description}{}{}{% +} + +\defDirective{Dir}{Messages}{Director}{}{}{% +Send the message to the Director whose name is given in the {\bf address} +field. Note, in the current implementation, the Director Name is ignored, and +the message is sent to the Director that started the Job. +} + +\defDirective{Dir}{Messages}{File}{}{}{% +Send the message to the filename given in the {\bf address} field. If the +file already exists, it will be overwritten. +} + +\defDirective{Dir}{Messages}{Mail}{}{}{% +Send the message to the email addresses that are given as a comma +separated list in the {\bf address} field. Mail messages are grouped +together during a job and then sent as a single email message when the +job terminates. The advantage of this destination is that you are +notified about every Job that runs. However, if you backup mutliple +machines every night, the number of email messages can be annoying. +Some users use filter programs such as {\bf procmail} to automatically +file this email based on the Job termination code (see {\bf +mailcommand}). +} + +\defDirective{Dir}{Messages}{Mail Command}{}{}{% +\label{mailcommand}% +In the absence of this resource, Bareos will send all mail using the +following command: + +{\bf mail -s "Bareos Message" {\textless}recipients{\textgreater}} + +In many cases, depending on your machine, this command may not work. +However, by using the {\bf MailCommand}, you can specify exactly how to +send the mail. During the processing of the {\bf command} part, normally +specified as a quoted string, the following substitutions will be used: + +\begin{itemize} +\item \%\% = \% +\item \%c = Client's name +\item \%d = Director's name +\item \%e = Job Exit code (OK, Error, ...) +\item \%h = Client address +\item \%i = Job Id +\item \%j = Unique Job name +\item \%l = Job level +\item \%n = Job name +\item \%r = Recipients +\item \%s = Since time +\item \%t = Job type (e.g. Backup, ...) +\item \%v = Read Volume name (Only on director side) +\item \%V = Write Volume name (Only on director side) +\end{itemize} + +Please note: any \configdirective{Mail Command} directive must be specified +in the {\bf Messages} resource {\bf before} the desired +\linkResourceDirective{Dir}{Messages}{Mail}, \linkResourceDirective{Dir}{Messages}{Mail On Success} +or \linkResourceDirective{Dir}{Messages}{Mail On Error} +directive. In fact, each of those directives may be preceded by +a different \configdirective{Mail Command}. + +A default installation will use the program {\bf bsmtp} as \configdirective{Mail Command}. +The program \command{bsmtp} is provided by Bareos and unifies the usage of a mail client +to a certain degree: + +\bconfigInput{config/MessagesMailCommand1.conf} + +The \command{bsmtp} program is provided as part of Bareos. For +additional details, please see the +\nameref{bsmtp} section. +Please test any \configdirective{Mail Command} that you use to ensure that your smtp gateway accepts the +addressing form that you use. Certain programs such as Exim can be very +selective as to what forms are permitted particularly in the from part. +} + +\defDirective{Dir}{Messages}{Mail On Error}{}{}{% +Send the message to the email addresses that are given as a comma +separated list in the {\bf address} field if the Job terminates with an +error condition. MailOnError messages are grouped together during a job +and then sent as a single email message when the job terminates. This +destination differs from the {\bf mail} destination in that if the Job +terminates normally, the message is totally discarded (for this +destination). If the Job terminates in error, it is emailed. By using +other destinations such as {\bf append} you can ensure that even if the +Job terminates normally, the output information is saved. +} + +\defDirective{Dir}{Messages}{Mail On Success}{}{}{% +Send the message to the email addresses that are given as a comma +separated list in the {\bf address} field if the Job terminates +normally (no error condition). MailOnSuccess messages are grouped +together during a job and then sent as a single email message when the +job terminates. This destination differs from the {\bf mail} +destination in that if the Job terminates abnormally, the message is +totally discarded (for this destination). If the Job terminates +normally, it is emailed. +} + +\defDirective{Dir}{Messages}{Name}{}{}{% +The name of the Messages resource. The name you specify here will be used to +tie this Messages resource to a Job and/or to the daemon. +} + +\defDirective{Dir}{Messages}{Operator}{}{}{% +Send the message to the email addresses that are specified as a comma +separated list in the {\bf address} field. This is similar to {\bf +mail} above, except that each message is sent as received. Thus there +is one email per message. This is most useful for {\bf mount} messages +(see below). +} + +\defDirective{Dir}{Messages}{Operator Command}{}{}{% +This resource specification is similar to the \linkResourceDirective{Dir}{Messages}{Mail Command} except that +it is used for Operator messages. The substitutions performed for the +\linkResourceDirective{Dir}{Messages}{Mail Command} +are also done for this command. Normally, you will set this +command to the same value as specified for the \linkResourceDirective{Dir}{Messages}{Mail Command}. +The \configdirective{Operator Command} directive must appear in the {\bf Messages} +resource before the \linkResourceDirective{Dir}{Messages}{Operator} directive. +} + +\defDirective{Dir}{Messages}{Stderr}{}{}{% +Send the message to the standard error output (normally not used). +} + +\defDirective{Dir}{Messages}{Stdout}{}{}{% +Send the message to the standard output (normally not used). +} + +\defDirective{Dir}{Messages}{Syslog}{}{}{% +Send the message to the system log (syslog) using the facility specified in +the {\bf address} field. Note, for the moment, the {\bf address} field is +ignored and the message is always sent to the \parameter{LOG_DAEMON} facility with +level \parameter{LOG_ERR}. See \command{man 3 syslog} for more details. + +Although the {\bf syslog} destination is not used in the default Bareos +config files, in certain cases where Bareos encounters errors in trying +to deliver a message, as a last resort, it will send it to the system +{\bf syslog} to prevent loss of the message, so you might occassionally +check the {\bf syslog} for Bareos output. +} +