4 \label{MessageResource}
5 \label{_ChapterStart15}
6 \chapter{Messages Resource}
7 \index[general]{Resource!Messages}
8 \index[general]{Messages Resource}
10 The Messages resource defines how messages are to be handled and destinations
11 to which they should be sent.
13 Even though each daemon has a full message handler, within the File daemon and
14 the Storage daemon, you will normally choose to send all the appropriate
15 messages back to the Director. This permits all the messages associated with a
16 single Job to be combined in the Director and sent as a single email message
17 to the user, or logged together in a single file.
19 Each message that Bacula generates (i.e. that each daemon generates) has an
20 associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
21 resource, you can specify which message types you wish to see and where they
22 should be sent. In addition, a message may be sent to multiple destinations.
23 For example, you may want all error messages both logged as well as sent to
24 you in an email. By defining multiple messages resources, you can have
25 different message handling for each type of Job (e.g. Full backups versus
28 In general, messages are attached to a Job and are included in the Job report.
29 There are some rare cases, where this is not possible, e.g. when no job is
30 running, or if a communications error occurs between a daemon and the
31 director. In those cases, the message may remain in the system, and should be
32 flushed at the end of the next Job. However, since such messages are not
33 attached to a Job, any that are mailed will be sent to {\bf
34 /usr/lib/sendmail}. On some systems, such as FreeBSD, if your sendmail is in a
35 different place, you may want to link it to the the above location.
37 The records contained in a Messages resource consist of a {\bf destination}
38 specification followed by a list of {\bf message-types} in the format:
42 \item [destination = message-type1, message-type2, message-type3, ... ]
43 \index[dir]{destination}
46 or for those destinations that need and address specification (e.g. email):
50 \item [destination = address = message-type1, message-type2,
52 \index[dir]{destination}
54 Where {\bf destination} is one of a predefined set of keywords that define
55 where the message is to be sent ({\bf stdout}, {\bf file}, ...), {\bf
56 message-type} is one of a predefined set of keywords that define the type of
57 message generated by {\bf Bacula} ({\bf ERROR}, {\bf WARNING}, {\bf FATAL},
58 ...), and {\bf address} varies according to the {\bf destination} keyword, but
59 is typically an email address or a filename.
62 The following are the list of the possible record definitions that can be used
63 in a message resource.
69 Start of the Messages records.
71 \item [Name = \lt{}name\gt{}]
73 The name of the Messages resource. The name you specify here will be used to
74 tie this Messages resource to a Job and/or to the daemon.
77 \item [MailCommand = \lt{}command\gt{}]
78 \index[dir]{MailCommand}
79 In the absence of this resource, Bacula will send all mail using the
82 {\bf mail -s "Bacula Message" \lt{}recipients\gt{}}
84 In many cases, depending on your machine, this command may not work. Using
85 the {\bf MailCommand}, you can specify exactly how to send the mail. During
86 the processing of the {\bf command}, normally specified as a quoted string,
87 the following substitutions will be used:
91 \item \%c = Client's name
92 \item \%d = Director's name
93 \item \%e = Job Exit code (OK, Error, ...)
95 \item \%j = Unique Job name
98 \item \%r = Recipients
99 \item \%t = Job type (e.g. Backup, ...)
102 The following is the command I (Kern) use. Note, the whole command should
103 appear on a single line in the configuration file rather than split as is
104 done here for presentation:
106 {\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f
107 \textbackslash{}"\textbackslash{}(Bacula\textbackslash{})
108 \%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c
109 \%l\textbackslash{}" \%r"}
111 Note, the {\bf bsmtp} program is provided as part of {\bf Bacula}. For
112 additional details, please see the
113 \ilink{ bsmtp -- Customizing Your Email Messages}{bsmtp} section of
114 the Bacula Utility Programs chapter of this manual. Please test any {\bf
115 mailcommand} that you use to ensure that your bsmtp gateway accepts the
116 addressing form that you use. Certain programs such as Exim can be very
117 selective as to what forms are permitted particularly in the from part.
119 \item [OperatorCommand = \lt{}command\gt{}]
120 \index[fd]{OperatorCommand}
121 This resource specification is similar to the {\bf MailCommand} except that
122 it is used for Operator messages. The substitutions performed for the {\bf
123 MailCommand} are also done for this command. Normally, you will set this
124 command to the same value as specified for the {\bf MailCommand}.
126 \item [Debug = \lt{}debug-level\gt{}]
128 This sets the debug message level to the debug level, which is an integer.
129 Higher debug levels cause more debug information to be produced. You are
130 requested not to use this record since it will be deprecated.
132 \item [\lt{}destination\gt{} = \lt{}message-type1\gt{},
133 \lt{}message-type2\gt{}, ...]
134 \index[fd]{\lt{}destination\gt{}}
136 Where {\bf destination} may be one of the following:
142 Send the message to standard output.
146 Send the message to standard error.
149 \index[console]{console}
150 Send the message to the console (Bacula Console). These messages are held
151 until the console program connects to the Director.
154 \item {\bf \lt{}destination\gt{} = \lt{}address\gt{} =
155 \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...}
156 \index[console]{\lt{}destination\gt{}}
158 Where {\bf address} depends on the {\bf destination}, which may be one of the
164 \index[dir]{director}
165 Send the message to the Director whose name is given in the {\bf address}
166 field. Note, in the current implementation, the Director Name is ignored, and
167 the message is sent to the Director that started the Job.
171 Send the message to the filename given in the {\bf address} field. If the
172 file already exists, it will be overwritten.
176 Append the message to the filename given in the {\bf address} field. If the
177 file already exists, it will be appended to. If the file does not exist, it
182 Send the message to the system log (syslog) using the facility specified in
183 the {\bf address} field. Note, for the moment, the {\bf address} field is
184 ignored and the message is always sent to the LOG\_DAEMON facility with
185 level LOG\_ERR. See {\bf man 3 syslog} for more details. Example:
187 syslog = all, !skipped, !saved
192 Send the message to the email addresses that are given as a comma
193 separated list in the {\bf address} field. Mail messages are grouped
194 together during a job and then sent as a single email message when the
195 job terminates. The advantage of this destination is that you are
196 notified about every Job that runs. However, if you backup five or ten
197 machines every night, the volume of email messages can be important.
198 Some users use filter programs such as {\bf procmail} to automatically
199 file this email based on the Job termination code (see {\bf
202 \item [mail on error]
203 \index[fd]{mail on error}
204 Send the message to the email addresses that are given as a comma
205 separated list in the {\bf address} field if the Job terminates with an
206 error condition. MailOnError messages are grouped together during a job
207 and then sent as a single email message when the job terminates. This
208 destination differs from the {\bf mail} destination in that if the Job
209 terminates normally, the message is totally discarded (for this
210 destination). If the Job terminates in error, it is emailed. By using
211 other destinations such as {\bf append} you can ensure that even if the
212 Job terminates normally, the output information is saved.
214 \item [mail on success]
215 \index[fd]{mail on success}
216 Send the message to the email addresses that are given as a comma
217 separated list in the {\bf address} field if the Job terminates
218 normally (no error condition). MailOnSuccess messages are grouped
219 together during a job and then sent as a single email message when the
220 job terminates. This destination differs from the {\bf mail}
221 destination in that if the Job terminates abnormally, the message is
222 totally discarded (for this destination). If the Job terminates in
223 normally, it is emailed.
228 Send the message to the email addresses that are specified as a comma
229 separated list in the {\bf address} field. This is similar to {\bf
230 mail} above, except that each message is sent as received. Thus there
231 is one email per message. This is most useful for {\bf mount} messages
232 (see below). \end{description}
234 For any destination, the {\bf message-type} field is a comma separated
235 list of the following types or classes of messages:
241 General information messages.
245 Warning messages. Generally this is some unusual condition but not expected
250 Non-fatal error messages. The job continues running. Any error message should
251 be investigated as it means that something went wrong.
255 Fatal error messages. Fatal errors cause the job to terminate.
258 \index[fd]{terminate}
259 Message generated when the daemon shuts down.
263 Files saved normally.
267 Files not saved because of some error. Usually because the file cannot be
268 accessed (i.e. it does not exist or is not mounted).
272 Files that were skipped because of a user supplied option such as an
273 incremental backup or a file that matches an exclusion pattern. This is
274 not considered an error condition such as the files listed for the {\bf
275 notsaved} type because the configuration file explicitly requests these
276 types of files to be skipped. For example, any unchanged file during an
277 incremental backup, or any subdirectory if the no recursion option is
282 Volume mount or intervention requests from the Storage daemon. These
283 requests require a specific operator intervention for the job to
287 \index[dir]{restored}
288 The {\bf ls} style listing generated for each file restored is sent to
296 \index[fd]{*security}
297 Security info/warning messages principally from unauthorized
303 The following is an example of a valid Messages resource definition, where
304 all messages except files explicitly skipped or daemon termination messages
305 are sent by email to enforcement@sec.com. In addition all mount messages
306 are sent to the operator (i.e. emailed to enforcement@sec.com). Finally
307 all messages other than explicitly skipped files and files saved are sent
314 mail = enforcement@sec.com = all, !skipped, !terminate
315 operator = enforcement@sec.com = mount
316 console = all, !skipped, !saved
321 With the exception of the email address (changed to avoid junk mail from
322 robot's), Kern's Director's Messages resource is as follows. Note, the {\bf
323 mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
324 split for this manual:
330 mailcommand = "bacula/bin/bsmtp -h mail.example.com \
331 -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
332 operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
333 -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
335 MailOnError = security@example.com = all, !skipped, \
337 append = "bacula/bin/log" = all, !skipped, !terminate
338 operator = security@example.com = mount
339 console = all, !skipped, !saved