4 \chapter{Messages Resource}
5 \label{MessagesChapter}
6 \index[general]{Resource!Messages}
7 \index[general]{Messages Resource}
9 The Messages resource defines how messages are to be handled and destinations
10 to which they should be sent.
12 Even though each daemon has a full message handler, within the File daemon and
13 the Storage daemon, you will normally choose to send all the appropriate
14 messages back to the Director. This permits all the messages associated with
15 a single Job to be combined in the Director and sent as a single email message
16 to the user, or logged together in a single file.
18 Each message that Bacula generates (i.e. that each daemon generates) has an
19 associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
20 resource, you can specify which message types you wish to see and where they
21 should be sent. In addition, a message may be sent to multiple destinations.
22 For example, you may want all error messages both logged as well as sent to
23 you in an email. By defining multiple messages resources, you can have
24 different message handling for each type of Job (e.g. Full backups versus
27 In general, messages are attached to a Job and are included in the Job report.
28 There are some rare cases, where this is not possible, e.g. when no job is
29 running, or if a communications error occurs between a daemon and the
30 director. In those cases, the message may remain in the system, and should be
31 flushed at the end of the next Job. However, since such messages are not
32 attached to a Job, any that are mailed will be sent to {\bf
33 /usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
34 different place, you may want to link it to the the above location.
36 The records contained in a Messages resource consist of a {\bf destination}
37 specification followed by a list of {\bf message-types} in the format:
41 \item [destination = message-type1, message-type2, message-type3, ... ]
42 \index[dir]{destination}
45 or for those destinations that need and address specification (e.g. email):
49 \item [destination = address = message-type1, message-type2,
51 \index[dir]{destination}
53 Where {\bf destination} is one of a predefined set of keywords that define
54 where the message is to be sent ({\bf stdout}, {\bf file}, ...), {\bf
55 message-type} is one of a predefined set of keywords that define the type of
56 message generated by {\bf Bacula} ({\bf ERROR}, {\bf WARNING}, {\bf FATAL},
57 ...), and {\bf address} varies according to the {\bf destination} keyword, but
58 is typically an email address or a filename.
61 The following are the list of the possible record definitions that can be used
62 in a message resource.
68 Start of the Messages records.
70 \item [Name = \lt{}name\gt{}]
72 The name of the Messages resource. The name you specify here will be used to
73 tie this Messages resource to a Job and/or to the daemon.
76 \item [MailCommand = \lt{}command\gt{}]
77 \index[dir]{MailCommand}
78 In the absence of this resource, Bacula will send all mail using the
81 {\bf mail -s "Bacula Message" \lt{}recipients\gt{}}
83 In many cases, depending on your machine, this command may not work.
84 However, by using the {\bf MailCommand}, you can specify exactly how to
85 send the mail. During the processing of the {\bf command} part, normally
86 specified as a quoted string, the following substitutions will be used:
92 %d = Daemon's name (Such as host-dir or host-fd)
93 %D = Director's name (Also valid on file daemon)
95 %f = Job FileSet (Only on director side)
102 %p = Pool name (Only on director side)
103 %P = Current PID process
105 %t = Job type (Backup, ...)
106 %v = Volume name (Only on director side)
107 %w = Storage name (Only on director side)
108 %x = Spooling enabled? ("yes" or "no")
111 Please note: any {\bf MailCommand} directive must be specified
112 in the {\bf Messages} resource {\bf before} the desired
113 {\bf Mail}, {\bf MailOnSuccess}, or {\bf MailOnError}
114 directive. In fact, each of those directives may be preceded by
115 a different {\bf MailCommand}.
117 The following is the command I (Kern) use. Note, the whole command should
118 appear on a single line in the configuration file rather than split as is
119 done here for presentation:
121 {\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f
122 \textbackslash{}"\textbackslash{}(Bacula\textbackslash{})
123 \%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c
124 \%l\textbackslash{}" \%r"}
126 The {\bf bsmtp} program is provided as part of {\bf Bacula}. For
127 additional details, please see the
128 \borgxrlink{bsmtp -- Customizing Your Email Messages}{bsmtp}{utility}{section} of
129 the Bacula Utility Programs chapter of this manual. Please test any {\bf
130 mailcommand} that you use to ensure that your bsmtp gateway accepts the
131 addressing form that you use. Certain programs such as Exim can be very
132 selective as to what forms are permitted particularly in the from part.
134 \item [OperatorCommand = \lt{}command\gt{}]
135 \index[fd]{OperatorCommand}
136 This resource specification is similar to the {\bf MailCommand} except that
137 it is used for Operator messages. The substitutions performed for the {\bf
138 MailCommand} are also done for this command. Normally, you will set this
139 command to the same value as specified for the {\bf MailCommand}.
140 The {\bf OperatorCommand} directive must appear in the {\bf Messages}
141 resource before the {\bf Operator} directive.
143 \item [\lt{}destination\gt{} = \lt{}message-type1\gt{},
144 \lt{}message-type2\gt{}, ...]
145 \index[fd]{\lt{}destination\gt{}}
147 Where {\bf destination} may be one of the following:
153 Send the message to standard output.
157 Send the message to standard error.
160 \index[console]{console}
161 Send the message to the console (Bacula Console). These messages are held
162 until the console program connects to the Director.
165 \item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
166 \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
167 \index[console]{\lt{}destination\gt{}}
169 Where {\bf address} depends on the {\bf destination}.
171 The {\bf destination} may be one of the following:
176 \index[dir]{director}
177 \index[general]{director}
178 Send the message to the Director whose name is given in the {\bf address}
179 field. Note, in the current implementation, the Director Name is ignored, and
180 the message is sent to the Director that started the Job.
184 \index[general]{file}
185 Send the message to the filename given in the {\bf address} field. If the
186 file already exists, it will be overwritten.
190 \index[general]{append}
191 Append the message to the filename given in the {\bf address} field. If the
192 file already exists, it will be appended to. If the file does not exist, it
196 \index[general]{syslog}
197 Send the message to the system log (syslog) using the facility specified in
198 the {\bf address} field. Note, for the moment, the {\bf address} field is
199 ignored and the message is always sent to the LOG\_DAEMON facility with
200 level LOG\_ERR. See {\bf man 3 syslog} for more details. Example:
203 syslog = all, !skipped
206 Although the {\bf syslog} destination is not used in the default Bacula
207 config files, in certain cases where Bacula encounters errors in trying
208 to deliver a message, as a last resort, it will send it to the system
209 {\bf syslog} to prevent loss of the message, so you might occassionally
210 check the {\bf syslog} for Bacula output (normally {\bf
214 \index[general]{mail}
215 Send the message to the email addresses that are given as a comma
216 separated list in the {\bf address} field. Mail messages are grouped
217 together during a job and then sent as a single email message when the
218 job terminates. The advantage of this destination is that you are
219 notified about every Job that runs. However, if you backup five or ten
220 machines every night, the volume of email messages can be important.
221 Some users use filter programs such as {\bf procmail} to automatically
222 file this email based on the Job termination code (see {\bf
225 \item [mail on error]
226 \index[general]{mail on error}
227 Send the message to the email addresses that are given as a comma
228 separated list in the {\bf address} field if the Job terminates with an
229 error condition. MailOnError messages are grouped together during a job
230 and then sent as a single email message when the job terminates. This
231 destination differs from the {\bf mail} destination in that if the Job
232 terminates normally, the message is totally discarded (for this
233 destination). If the Job terminates in error, it is emailed. By using
234 other destinations such as {\bf append} you can ensure that even if the
235 Job terminates normally, the output information is saved.
237 \item [mail on success]
238 \index[general]{mail on success}
239 Send the message to the email addresses that are given as a comma
240 separated list in the {\bf address} field if the Job terminates
241 normally (no error condition). MailOnSuccess messages are grouped
242 together during a job and then sent as a single email message when the
243 job terminates. This destination differs from the {\bf mail}
244 destination in that if the Job terminates abnormally, the message is
245 totally discarded (for this destination). If the Job terminates
246 normally, it is emailed.
249 \index[general]{operator}
250 Send the message to the email addresses that are specified as a comma
251 separated list in the {\bf address} field. This is similar to {\bf
252 mail} above, except that each message is sent as received. Thus there
253 is one email per message. This is most useful for {\bf mount} messages
257 \index[general]{console}
258 Send the message to the Bacula console.
261 \index[general]{stdout}
262 Send the message to the standard output (normally not used).
265 \index[general]{stderr}
266 Send the message to the standard error output (normally not used).
269 \index[general]{catalog}
270 Send the message to the Catalog database. The message will be
271 written to the table named {\bf Log} and a timestamp field will
272 also be added. This permits Job Reports and other messages to
273 be recorded in the Catalog so that they can be accessed by
274 reporting software. Bacula will prune the Log records associated
275 with a Job when the Job records are pruned. Otherwise, Bacula
276 never uses these records internally, so this destination is only
277 used for special purpose programs (e.g. {\bf bweb}).
281 For any destination, the {\bf message-type} field is a comma separated
282 list of the following types or classes of messages:
287 \index[general]{info}
288 General information messages.
291 \index[general]{warning}
292 Warning messages. Generally this is some unusual condition but not expected
296 \index[general]{error}
297 Non-fatal error messages. The job continues running. Any error message should
298 be investigated as it means that something went wrong.
301 \index[general]{fatal}
302 Fatal error messages. Fatal errors cause the job to terminate.
305 \index[general]{terminate}
306 Message generated when the daemon shuts down.
310 \index[general]{notsaved}
311 Files not saved because of some error. Usually because the file cannot be
312 accessed (i.e. it does not exist or is not mounted).
316 \index[general]{skipped}
317 Files that were skipped because of a user supplied option such as an
318 incremental backup or a file that matches an exclusion pattern. This is
319 not considered an error condition such as the files listed for the {\bf
320 notsaved} type because the configuration file explicitly requests these
321 types of files to be skipped. For example, any unchanged file during an
322 incremental backup, or any subdirectory if the no recursion option is
327 \index[general]{mount}
328 Volume mount or intervention requests from the Storage daemon. These
329 requests require a specific operator intervention for the job to
334 \index[general]{restored}
335 The {\bf ls} style listing generated for each file restored is sent to
343 \index[general]{security}
344 Security info/warning messages principally from unauthorized
348 \index[general]{alert}
349 Alert messages. These are messages generated by tape alerts.
352 \index[general]{volmgmt}
353 Volume management messages. Currently there are no volume mangement
359 The following is an example of a valid Messages resource definition, where
360 all messages except files explicitly skipped or daemon termination messages
361 are sent by email to enforcement@sec.com. In addition all mount messages
362 are sent to the operator (i.e. emailed to enforcement@sec.com). Finally
363 all messages other than explicitly skipped files and files saved are sent
370 mail = enforcement@sec.com = all, !skipped, !terminate
371 operator = enforcement@sec.com = mount
372 console = all, !skipped, !saved
377 With the exception of the email address (changed to avoid junk mail from
378 robot's), an example Director's Messages resource is as follows. Note, the {\bf
379 mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
380 split for this manual:
386 mailcommand = "bacula/bin/bsmtp -h mail.example.com \
387 -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
388 operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
389 -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
391 MailOnError = security@example.com = all, !skipped, \
393 append = "bacula/bin/log" = all, !skipped, !terminate
394 operator = security@example.com = mount
395 console = all, !skipped, !saved