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.
74 \index[dir]{Messages }
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 {\bf LOG\_ERR} facility.
194 Send the message to the email addresses that are given as a comma separated
195 list in the {\bf address} field. Mail messages are grouped together during a
196 job and then sent as a single email message when the job terminates. The
197 advantage of this destination is that you are notified about every Job that
198 runs. However, if you backup 5 or 10 machines every night, the volume of
199 email messages can be important. Some users use filter programs such as {\bf
200 procmail} to automatically file this email based on the Job termination code
201 (see {\bf mailcommand}).
203 \item [mail on error]
204 \index[fd]{mail on error }
205 Send the message to the email addresses that are given as a comma separated
206 list in the {\bf address} field if the Job terminates with an error
207 condition. MailOnError messages are grouped together during a job and then
208 sent as a single email message when the job terminates. This destination
209 differs from the {\bf mail} destination in that if the Job terminates
210 normally, the message is totally discarded (for this destination). If the Job
211 terminates in error, it is emailed. By using other destinations such as {\bf
212 append} you can ensure that even if the Job terminates normally, the output
213 information is saved.
216 \index[fd]{operator }
217 Send the message to the email addresses that are specified as a comma
218 separated list in the {\bf address} field. This is similar to {\bf mail}
219 above, except that each message is sent as received. Thus there is one email
220 per message. This is most useful for {\bf mount} messages (see below).
223 For any destination, the {\bf message-type} field is a comma separated list
224 of the following types or classes of messages:
230 General information messages.
234 Warning messages. Generally this is some unusual condition but not expected
239 Non-fatal error messages. The job continues running. Any error message should
240 be investigated as it means that something went wrong.
244 Fatal error messages. Fatal errors cause the job to terminate.
247 \index[fd]{terminate }
248 Message generated when the daemon shuts down.
252 Files saved normally.
255 \index[fd]{notsaved }
256 Files not saved because of some error. Usually because the file cannot be
257 accessed (i.e. it does not exist or is not mounted).
261 Files that were skipped because of a user supplied option such as an
262 incremental backup or a file that matches an exclusion pattern. This is not
263 considered an error condition such as the files listed for the {\bf
264 notsaved} type because the configuration file explicitly requests these types
265 of files to be skipped. For example, any unchanged file during an incremental
266 backup, or any subdirectory if the no recursion option is specified.
270 Volume mount or intervention requests from the Storage daemon. These requests
271 require a specific operator intervention for the job to continue.
274 \index[dir]{restored }
275 The {\bf ls} style listing generated for each file restored is sent to this
283 \index[fd]{*security }
284 Security info/warning messages (not currently implemented).
289 The following is an example of a valid Messages resource definition, where all
290 messages except files explicitly skipped or daemon termination messages are
291 sent by email to enforcement@sec.com. In addition all mount messages are sent
292 to the operator (i.e. emailed to enforcement@sec.com). Finally all messages
293 other than explicitly skipped files and files saved are sent to the console:
299 mail = enforcement@sec.com = all, !skipped, !terminate
300 operator = enforcement@sec.com = mount
301 console = all, !skipped, !saved
306 With the exception of the email address (changed to avoid junk mail from
307 robot's), Kern's Director's Messages resource is as follows. Note, the {\bf
308 mailcommand} and {\bf operatorcommand} are on a single line -- they had to be
309 split for this manual:
315 mailcommand = "bacula/bin/bsmtp -h mail.example.com \
316 -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
317 operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
318 -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
320 MailOnError = security@example.com = all, !skipped, \
322 append = "bacula/bin/log" = all, !skipped, !terminate
323 operator = security@example.com = mount
324 console = all, !skipped, !saved