--- /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
projects / bacula / docs / blobdiff