4 \section*{Messages Resource}
5 \label{_ChapterStart15}
6 \index[general]{Resource!Messages}
7 \index[general]{Messages Resource}
8 \addcontentsline{toc}{section}{Messages Resource}
10 \subsection*{The Messages Resource}
11 \label{MessageResource}
12 \index[general]{Resource!Messages}
13 \index[general]{Messages Resource}
14 \addcontentsline{toc}{subsection}{Messages Resource}
16 The Messages resource defines how messages are to be handled and destinations
17 to which they should be sent.
19 Even though each daemon has a full message handler, within the File daemon and
20 the Storage daemon, you will normally choose to send all the appropriate
21 messages back to the Director. This permits all the messages associated with a
22 single Job to be combined in the Director and sent as a single email message
23 to the user, or logged together in a single file.
25 Each message that Bacula generates (i.e. that each daemon generates) has an
26 associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
27 resource, you can specify which message types you wish to see and where they
28 should be sent. In addition, a message may be sent to multiple destinations.
29 For example, you may want all error messages both logged as well as sent to
30 you in an email. By defining multiple messages resources, you can have
31 different message handling for each type of Job (e.g. Full backups versus
34 In general, messages are attached to a Job and are included in the Job report.
35 There are some rare cases, where this is not possible, e.g. when no job is
36 running, or if a communications error occurs between a daemon and the
37 director. In those cases, the message may remain in the system, and should be
38 flushed at the end of the next Job. However, since such messages are not
39 attached to a Job, any that are mailed will be sent to {\bf
40 /usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
41 different place, you may want to link it to the the above location.
43 The records contained in a Messages resource consist of a {\bf destination}
44 specification followed by a list of {\bf message-types} in the format:
48 \item [destination = message-type1, message-type2, message-type3, ... ]
49 \index[dir]{destination}
52 or for those destinations that need and address specification (e.g. email):
56 \item [destination = address = message-type1, message-type2,
58 \index[dir]{destination}
60 Where {\bf destination} is one of a predefined set of keywords that define
61 where the message is to be sent ({\bf stdout}, {\bf file}, ...), {\bf
62 message-type} is one of a predefined set of keywords that define the type of
63 message generated by {\bf Bacula} ({\bf ERROR}, {\bf WARNING}, {\bf FATAL},
64 ...), and {\bf address} varies according to the {\bf destination} keyword, but
65 is typically an email address or a filename.
68 The following are the list of the possible record definitions that can be used
69 in a message resource.
75 Start of the Messages records.
77 \item [Name = \lt{}name\gt{}]
79 The name of the Messages resource. The name you specify here will be used to
80 tie this Messages resource to a Job and/or to the daemon.
83 \item [MailCommand = \lt{}command\gt{}]
84 \index[dir]{MailCommand}
85 In the absence of this resource, Bacula will send all mail using the
88 {\bf mail -s "Bacula Message" \lt{}recipients\gt{}}
90 In many cases, depending on your machine, this command may not work. Using
91 the {\bf MailCommand}, you can specify exactly how to send the mail. During
92 the processing of the {\bf command}, normally specified as a quoted string,
93 the following substitutions will be used:
97 \item \%c = Client's name
98 \item \%d = Director's name
99 \item \%e = Job Exit code (OK, Error, ...)
101 \item \%j = Unique Job name
102 \item \%l = Job level
104 \item \%r = Recipients
105 \item \%t = Job type (e.g. Backup, ...)
108 The following is the command I (Kern) use. Note, the whole command should
109 appear on a single line in the configuration file rather than split as is
110 done here for presentation:
112 {\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f
113 \textbackslash{}"\textbackslash{}(Bacula\textbackslash{})
114 \%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c
115 \%l\textbackslash{}" \%r"}
117 Note, the {\bf bsmtp} program is provided as part of {\bf Bacula}. For
118 additional details, please see the
119 \ilink{ bsmtp -- Customizing Your Email Messages}{bsmtp} section of
120 the Bacula Utility Programs chapter of this manual. Please test any {\bf
121 mailcommand} that you use to ensure that your bsmtp gateway accepts the
122 addressing form that you use. Certain programs such as Exim can be very
123 selective as to what forms are permitted particularly in the from part.
125 \item [OperatorCommand = \lt{}command\gt{}]
126 \index[fd]{OperatorCommand}
127 This resource specification is similar to the {\bf MailCommand} except that
128 it is used for Operator messages. The substitutions performed for the {\bf
129 MailCommand} are also done for this command. Normally, you will set this
130 command to the same value as specified for the {\bf MailCommand}.
132 \item [Debug = \lt{}debug-level\gt{}]
134 This sets the debug message level to the debug level, which is an integer.
135 Higher debug levels cause more debug information to be produced. You are
136 requested not to use this record since it will be deprecated.
138 \item [\lt{}destination\gt{} = \lt{}message-type1\gt{},
139 \lt{}message-type2\gt{}, ...]
140 \index[fd]{\lt{}destination\gt{}}
142 Where {\bf destination} may be one of the following:
148 Send the message to standard output.
152 Send the message to standard error.
155 \index[console]{console}
156 Send the message to the console (Bacula Console). These messages are held
157 until the console program connects to the Director.
160 \item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
161 \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
162 \index[console]{\lt{}destination\gt{}}
164 Where {\bf address} depends on the {\bf destination}, which may be one of the
170 \index[dir]{director}
171 Send the message to the Director whose name is given in the {\bf address}
172 field. Note, in the current implementation, the Director Name is ignored, and
173 the message is sent to the Director that started the Job.
177 Send the message to the filename given in the {\bf address} field. If the
178 file already exists, it will be overwritten.
182 Append the message to the filename given in the {\bf address} field. If the
183 file already exists, it will be appended to. If the file does not exist, it
188 Send the message to the system log (syslog) using the facility specified in
189 the {\bf address} field. Note, for the moment, the {\bf address} field is
190 ignored and the message is always sent to the LOG\_DAEMON facility with
191 level LOG\_ERR. See {\bf man 3 syslog} for more details. Example:
193 syslog = all, !skipped, !saved
198 Send the message to the email addresses that are given as a comma
199 separated list in the {\bf address} field. Mail messages are grouped
200 together during a job and then sent as a single email message when the
201 job terminates. The advantage of this destination is that you are
202 notified about every Job that runs. However, if you backup 5 or 10
203 machines every night, the volume of email messages can be important.
204 Some users use filter programs such as {\bf procmail} to automatically
205 file this email based on the Job termination code (see {\bf
208 \item [mail on error]
209 \index[fd]{mail on error}
210 Send the message to the email addresses that are given as a comma
211 separated list in the {\bf address} field if the Job terminates with an
212 error condition. MailOnError messages are grouped together during a job
213 and then sent as a single email message when the job terminates. This
214 destination differs from the {\bf mail} destination in that if the Job
215 terminates normally, the message is totally discarded (for this
216 destination). If the Job terminates in error, it is emailed. By using
217 other destinations such as {\bf append} you can ensure that even if the
218 Job terminates normally, the output information is saved.
222 Send the message to the email addresses that are specified as a comma
223 separated list in the {\bf address} field. This is similar to {\bf
224 mail} above, except that each message is sent as received. Thus there
225 is one email per message. This is most useful for {\bf mount} messages
226 (see below). \end{description}
228 For any destination, the {\bf message-type} field is a comma separated
229 list of the following types or classes of messages:
235 General information messages.
239 Warning messages. Generally this is some unusual condition but not expected
244 Non-fatal error messages. The job continues running. Any error message should
245 be investigated as it means that something went wrong.
249 Fatal error messages. Fatal errors cause the job to terminate.
252 \index[fd]{terminate}
253 Message generated when the daemon shuts down.
257 Files saved normally.
261 Files not saved because of some error. Usually because the file cannot be
262 accessed (i.e. it does not exist or is not mounted).
266 Files that were skipped because of a user supplied option such as an
267 incremental backup or a file that matches an exclusion pattern. This is
268 not considered an error condition such as the files listed for the {\bf
269 notsaved} type because the configuration file explicitly requests these
270 types of files to be skipped. For example, any unchanged file during an
271 incremental backup, or any subdirectory if the no recursion option is
276 Volume mount or intervention requests from the Storage daemon. These
277 requests require a specific operator intervention for the job to
281 \index[dir]{restored}
282 The {\bf ls} style listing generated for each file restored is sent to
290 \index[fd]{*security}
291 Security info/warning messages principally from unauthorized
297 The following is an example of a valid Messages resource definition, where
298 all messages except files explicitly skipped or daemon termination messages
299 are sent by email to enforcement@sec.com. In addition all mount messages
300 are sent to the operator (i.e. emailed to enforcement@sec.com). Finally
301 all messages other than explicitly skipped files and files saved are sent
308 mail = enforcement@sec.com = all, !skipped, !terminate
309 operator = enforcement@sec.com = mount
310 console = all, !skipped, !saved
315 With the exception of the email address (changed to avoid junk mail from
316 robot's), Kern's Director's Messages resource is as follows. Note, the {\bf
317 mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
318 split for this manual:
324 mailcommand = "bacula/bin/bsmtp -h mail.example.com \
325 -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
326 operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
327 -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
329 MailOnError = security@example.com = all, !skipped, \
331 append = "bacula/bin/log" = all, !skipped, !terminate
332 operator = security@example.com = mount
333 console = all, !skipped, !saved