+++ /dev/null
-%%
-%%
-
-\chapter{Messages Resource}
-\label{MessagesChapter}
-\index[general]{Resource!Messages}
-\index[general]{Messages Resource}
-
-The Messages resource defines how messages are to be handled and destinations
-to which they should be sent.
-
-Even though each daemon has a full message handler, within the File daemon and
-the Storage daemon, you will normally choose to send all the appropriate
-messages back to the Director. This permits all the messages associated with
-a single Job to be combined in the Director and sent as a single email message
-to the user, or logged together in a single file.
-
-Each message that Bacula generates (i.e. that each daemon generates) has an
-associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
-resource, you can specify which message types you wish to see and where they
-should be sent. In addition, a message may be sent to multiple destinations.
-For example, you may want all error messages both logged as well as sent to
-you in an email. By defining multiple messages resources, you can have
-different message handling for each type of Job (e.g. Full backups versus
-Incremental backups).
-
-In general, messages are attached to a Job and are included in the Job report.
-There are some rare cases, where this is not possible, e.g. when no job is
-running, or if a communications error occurs between a daemon and the
-director. In those cases, the message may remain in the system, and should be
-flushed at the end of the next Job. However, since such messages are not
-attached to a Job, any that are mailed will be sent to {\bf
-/usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
-different place, you may want to link it to the the above location.
-
-The records contained in a Messages resource consist of a {\bf destination}
-specification followed by a list of {\bf message-types} in the format:
-
-\begin{description}
-
-\item [destination = message-type1, message-type2, message-type3, ... ]
-\index[dir]{destination}
-\end{description}
-
-or for those destinations that need and address specification (e.g. email):
-
-\begin{description}
-
-\item [destination = address = message-type1, message-type2,
- message-type3, ... ]
-\index[dir]{destination}
-
- Where {\bf destination} is one of a predefined set of keywords that define
- where the message is to be sent ({\bf stdout}, {\bf file}, ...), {\bf
- message-type} is one of a predefined set of keywords that define the type of
- message generated by {\bf Bacula} ({\bf ERROR}, {\bf WARNING}, {\bf FATAL},
- ...), and {\bf address} varies according to the {\bf destination} keyword, but
- is typically an email address or a filename.
-\end{description}
-
-The following are the list of the possible record definitions that can be used
-in a message resource.
-
-\begin{description}
-
-\item [Messages]
-\index[dir]{Messages}
- Start of the Messages records.
-
-\item [Name = \lt{}name\gt{}]
-\index[dir]{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 = \lt{}command\gt{}]
-\index[dir]{MailCommand}
- In the absence of this resource, Bacula will send all mail using the
- following command:
-
-{\bf mail -s "Bacula Message" \lt{}recipients\gt{}}
-
-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 \%i = Job Id
-\item \%j = Unique Job name
-\item \%l = Job level
-\item \%n = Job name
-\item \%r = Recipients
-\item \%t = Job type (e.g. Backup, ...)
-\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}.
-
-The following is the command I (Kern) use. Note, the whole command should
-appear on a single line in the configuration file rather than split as is
-done here for presentation:
-
-{\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f
-\textbackslash{}"\textbackslash{}(Bacula\textbackslash{})
-\%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c
-\%l\textbackslash{}" \%r"}
-
-The {\bf bsmtp} program is provided as part of {\bf Bacula}. For
-additional details, please see the
-\ilink{ bsmtp -- Customizing Your Email Messages}{bsmtp} section of
-the Bacula Utility Programs chapter of this manual. Please test any {\bf
-mailcommand} that you use to ensure that your bsmtp 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 = \lt{}command\gt{}]
-\index[fd]{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 [\lt{}destination\gt{} = \lt{}message-type1\gt{},
- \lt{}message-type2\gt{}, ...]
- \index[fd]{\lt{}destination\gt{}}
-
-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 (Bacula Console). These messages are held
-until the console program connects to the Director.
-\end{description}
-
-\item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
- \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
- \index[console]{\lt{}destination\gt{}}
-
-Where {\bf address} depends on the {\bf destination}.
-
-The {\bf destination} may be one of the following:
-
-\begin{description}
-
-\item [director]
- \index[dir]{director}
- \index[general]{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]
-\index[dir]{file}
-\index[general]{file}
- Send the message to the filename given in the {\bf address} field. If the
- file already exists, it will be overwritten.
-
-\item [append]
-\index[dir]{append}
-\index[general]{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]
-\index[general]{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:
-
-\begin{verbatim}
- syslog = all, !skipped
-\end{verbatim}
-
- Although the {\bf syslog} destination is not used in the default Bacula
- config files, in certain cases where Bacula 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 Bacula output (normally {\bf
- /var/log/syslog}).
-
-\item [mail]
- \index[general]{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 five or ten
- machines every night, the volume of email messages can be important.
- 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]
- \index[general]{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]
- \index[general]{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]
- \index[general]{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]
- \index[general]{console}
- Send the message to the Bacula console.
-
-\item [stdout]
- \index[general]{stdout}
- Send the message to the standard output (normally not used).
-
-\item [stderr]
- \index[general]{stderr}
- Send the message to the standard error output (normally not used).
-
-\item [catalog]
- \index[general]{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. Bacula will prune the Log records associated
- with a Job when the Job records are pruned. Otherwise, Bacula
- never uses these records internally, so this destination is only
- used for special purpose programs (e.g. {\bf bweb}).
-
-\end{description}
-
- For any destination, the {\bf message-type} field is a comma separated
- list of the following types or classes of messages:
-
-\begin{description}
-
-\item [info]
- \index[general]{info}
- General information messages.
-
-\item [warning]
- \index[general]{warning}
- Warning messages. Generally this is some unusual condition but not expected
- to be serious.
-
-\item [error]
- \index[general]{error}
- Non-fatal error messages. The job continues running. Any error message should
- be investigated as it means that something went wrong.
-
-\item [fatal]
- \index[general]{fatal}
- Fatal error messages. Fatal errors cause the job to terminate.
-
-\item [terminate]
- \index[general]{terminate}
- Message generated when the daemon shuts down.
-
-\item [notsaved]
- \index[fd]{notsaved}
- \index[general]{notsaved}
- Files not saved because of some error. Usually because the file cannot be
- accessed (i.e. it does not exist or is not mounted).
-
-\item [skipped]
- \index[fd]{skipped}
- \index[general]{skipped}
- Files that were skipped because of a user supplied option such as an
- incremental backup or a file that matches an exclusion pattern. This is
- not considered an error condition such as the files listed for the {\bf
- notsaved} type because the configuration file explicitly requests these
- types of files to be skipped. For example, any unchanged file during an
- incremental backup, or any subdirectory if the no recursion option is
- specified.
-
-\item [mount]
- \index[dir]{mount}
- \index[general]{mount}
- Volume mount or intervention requests from the Storage daemon. These
- requests require a specific operator intervention for the job to
- continue.
-
-\item [restored]
- \index[fd]{restored}
- \index[general]{restored}
- The {\bf ls} style listing generated for each file restored is sent to
- this message class.
-
-\item [all]
- \index[general]{all}
- All message types.
-
-\item [security]
- \index[general]{security}
- Security info/warning messages principally from unauthorized
- connection attempts.
-
-\item [alert]
- \index[general]{alert}
- Alert messages. These are messages generated by tape alerts.
-
-\item [volmgmt]
- \index[general]{volmgmt}
- Volume management messages. Currently there are no volume mangement
- messages generated.
-\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 enforcement@sec.com. In addition all mount messages
-are sent to the operator (i.e. emailed to enforcement@sec.com). Finally
-all messages other than explicitly skipped files and files saved are sent
-to the console:
-
-\footnotesize
-\begin{verbatim}
-Messages {
- Name = Standard
- mail = enforcement@sec.com = all, !skipped, !terminate
- operator = enforcement@sec.com = mount
- console = all, !skipped, !saved
-}
-\end{verbatim}
-\normalsize
-
-With the exception of the email address (changed to avoid junk mail from
-robot's), an example Director's Messages resource is as follows. Note, the {\bf
-mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
-split for this manual:
-
-\footnotesize
-\begin{verbatim}
-Messages {
- Name = Standard
- mailcommand = "bacula/bin/bsmtp -h mail.example.com \
- -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
- operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
- -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
- for %j\" %r"
- MailOnError = security@example.com = all, !skipped, \
- !terminate
- append = "bacula/bin/log" = all, !skipped, !terminate
- operator = security@example.com = mount
- console = all, !skipped, !saved
-}
-\end{verbatim}
-\normalsize