Debian Codegraph @

manuals/en/main/messagesres.tex

raw
1 \chapter{Messages Resource}
2 \label{blb:MessagesChapter}
3 \index[general]{Resource!Messages}
4 \index[general]{Messages Resource}
5
6 The Messages resource defines how messages are to be handled and destinations
7 to which they should be sent.
8
9 Even though each daemon has a full message handler, within the File daemon and
10 the Storage daemon, you will normally choose to send all the appropriate
11 messages back to the Director. This permits all the messages associated with
12 a single Job to be combined in the Director and sent as a single email message
13 to the user, or logged together in a single file.
14
15 Each message that \bacula{} generates (i.e. that each daemon generates) has an
16 associated type such as INFO, WARNING, ERROR, FATAL, etc. Using the message
17 resource, you can specify which message types you wish to see and where they
18 should be sent. In addition, a message may be sent to multiple destinations.
19 For example, you may want all error messages both logged as well as sent to
20 you in an email. By defining multiple messages resources, you can have
21 different message handling for each type of Job (e.g. Full backups versus
22 Incremental backups).
23
24 In general, messages are attached to a Job and are included in the Job report.
25 There are some rare cases, where this is not possible, e.g. when no job is
26 running, or if a communications error occurs between a daemon and the
27 director. In those cases, the message may remain in the system, and should be
28 flushed at the end of the next Job. However, since such messages are not
29 attached to a Job, any that are mailed will be sent to \btool{/usr/lib/sendmail}.
30 On some systems, such as FreeBSD, if your sendmail is in a
31 different place, you may want to link it to the the above location.
32
33 The records contained in a Messages resource consist of a \textbf{destination}
34 specification followed by a list of \textbf{message-types} in the format:
35
36 \begin{bdescription}
37
38 \item [destination = message-type1, message-type2, message-type3, \ldots{} ]
39 \index[dir]{destination}
40 \end{bdescription}
41
42 or for those destinations that need and address specification (e.g. email):
43
44 \begin{bdescription}
45
46 \item [destination = address = message-type1, message-type2,
47 message-type3, \ldots{} ]
48 \index[dir]{destination}
49
50 Where \textbf{destination} is one of a predefined set of keywords that define
51 where the message is to be sent (\textbf{stdout}, \textbf{file}, \ldots{}),
52 \textbf{message-type} is one of a predefined set of keywords that define the type of
53 message generated by \textbf{\bacula{}} (\textbf{ERROR}, \textbf{WARNING}, \textbf{FATAL},
54 \ldots{}), and \textbf{address} varies according to the \textbf{destination} keyword, but
55 is typically an email address or a filename.
56 \end{bdescription}
57
58 The following are the list of the possible record definitions that can be used
59 in a message resource.
60
61 \begin{bdescription}
62
63 \item [Messages]
64 \index[dir]{Messages}
65 Start of the Messages records.
66
67 \bwebdoc{:Messages:Name}
68 \item [Name = \bbracket{name}]
69 \index[dir]{Name}
70 The name of the Messages resource. The name you specify here will be used to
71 tie this Messages resource to a Job and/or to the daemon.
72
73 \bwebdoc{:Messages:MailCommand}
74 \label{blb:mailcommand}
75 \item [MailCommand = \bbracket{command}]
76 \index[dir]{MailCommand}
77 In the absence of this resource, \bacula{} will send all mail using the
78 following command:
79
80 \btool{mail -s "\bacula{} Message" \bbracket{recipients}}
81
82 In many cases, depending on your machine, this command may not work.
83 However, by using the \textbf{MailCommand}, you can specify exactly how to
84 send the mail. During the processing of the \textbf{command} part, normally
85 specified as a quoted string, the following substitutions will be used:
86
87 \begin{bVerbatim}
88 %% = %
89 %b = Job Bytes
90 %c = Client's name
91 %C = If the job is a Cloned job (Only on director side)
92 %d = Daemon's name (Such as host-dir or host-fd)
93 %D = Director's name (Also valid on file daemon)
94 %e = Job Exit Status
95 %E = Non-fatal Job Errors
96 %f = Job FileSet (Only on director side)
97 %F = Job Files
98 %h = Client address
99 %i = JobId
100 %I = Migration/Copy JobId (Only in Copy/Migrate Jobs)
101 %j = Unique Job id
102 %l = Job Level
103 %n = Job name
104 %o = Job Priority
105 %p = Pool name (Only on director side)
106 %P = Current PID process
107 %r = Recipients
108 %R = Read Bytes
109 %s = Since time
110 %S = Previous Job name (Only on file daemon side)
111 %t = Job type (Backup, ...)
112 %v = Volume name (Only on director side)
113 %w = Storage name (Only on director side)
114 %x = Spooling enabled? ("yes" or "no")
115 \end{bVerbatim}
116
117 Please note: any \textbf{MailCommand} directive must be specified
118 in the \textbf{Messages} resource \textbf{before} the desired
119 \textbf{Mail}, \textbf{MailOnSuccess}, or \textbf{MailOnError}
120 directive. In fact, each of those directives may be preceded by
121 a different \textbf{MailCommand}.
122
123 The following is an example. Note, the whole command should
124 appear on a single line in the configuration file rather than split as is
125 done here for presentation:
126
127 \textbf{mailcommand = "/opt/bacula/bin/bsmtp -h mail.example.com -f
128 \textbackslash{}"\textbackslash{}(Bacula\textbackslash{}) \%r
129 \textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c \%l\textbackslash{}" \%r\textbackslash{}"}
130
131 The \btool{bsmtp} program is provided as part of \textbf{\bacula{}}. For
132 additional details, please see the
133 \bxlink{bsmtp -- Customizing Your Email Messages}{blb:bsmtp}{utility}{section} of
134 the \butilityman{}. Please test any
135 \textbf{mailcommand} that you use to ensure that your bsmtp gateway accepts the
136 addressing form that you use. Certain programs such as \btool{Exim} can be very
137 selective as to what forms are permitted particularly in the from part.
138 Be careful, most of the samples use \textbf{\%r} in the sender part of
139 the \textbf{mailcommand}. This is a convenient way to setup the sender and
140 the recipient at once. When you configure multiple recipients
141 (separated by a comma) you must replace the \textbf{\%r}
142 in the sender part with only one valid email address.
143
144 \bwebdoc{:Messages:OperatorCommand}
145 \item [OperatorCommand = \bbracket{command}]
146 \index[fd]{OperatorCommand}
147 This resource specification is similar to the \textbf{MailCommand} except that
148 it is used for Operator messages. The substitutions performed for the
149 \textbf{MailCommand} are also done for this command. Normally, you will set this
150 command to the same value as specified for the \textbf{MailCommand}.
151 The \textbf{OperatorCommand} directive must appear in the \textbf{Messages}
152 resource before the \textbf{Operator} directive.
153
154 \bwebdoc{:Messages:End}
155 \item [\bbracket{destination} = \bbracket{message-type1},
156 \bbracket{message-type2}, \ldots{}]
157 \index[fd]{\bbracket{destination}}
158
159 Where \textbf{destination} may be one of the following:
160
161 \begin{bdescription}
162
163 \item [stdout]
164 \index[fd]{stdout}
165 Send the message to standard output.
166
167 \item [stderr]
168 \index[fd]{stderr}
169 Send the message to standard error.
170
171 \item [console]
172 \index[console]{console}
173 Send the message to the console (\bacula{} Console). These messages are held
174 until the console program connects to the Director.
175 \end{bdescription}
176
177 \item \textbf{\bbracket{destination} = \bbracket{address} =
178 \bbracket{message-type1}, \bbracket{message-type2}, \ldots{}}
179 \index[console]{\bbracket{destination}}
180
181 Where \textbf{address} depends on the \textbf{destination}.
182
183 The \textbf{destination} may be one of the following:
184
185 \begin{bdescription}
186
187 \bwebdoc{:Messages:Director}
188 \item [director]
189 \index[dir]{director}
190 \index[general]{director}
191 Send the message to the Director whose name is given in the \textbf{address}
192 field. Note, in the current implementation, the Director Name is ignored, and
193 the message is sent to the Director that started the Job.
194
195 \bwebdoc{:Messages:File}
196 \item [file]
197 \index[dir]{file}
198 \index[general]{file}
199 Send the message to the filename given in the \textbf{address} field. If the
200 file already exists, it will be overwritten.
201
202 \bwebdoc{:Messages:Append}
203 \item [append]
204 \index[dir]{append}
205 \index[general]{append}
206 Append the message to the filename given in the \textbf{address} field. If the
207 file already exists, it will be appended to. If the file does not exist, it
208 will be created.
209
210 \bwebdoc{:Messages:Syslog}
211 \item [syslog]
212 \index[general]{syslog}
213 Send the message to the system log (syslog) using the facility specified in
214 the \textbf{address} field. Note, for the moment, the \textbf{address} field is
215 ignored and the message is always sent to the LOG\_DAEMON facility with
216 level LOG\_ERR. See \btool{man 3 syslog} for more details. Example:
217
218 \begin{bVerbatim}
219 syslog = all, !skipped
220 \end{bVerbatim}
221
222 Although the \textbf{syslog} destination is not used in the default \bacula{}
223 config files, in certain cases where \bacula{} encounters errors in trying
224 to deliver a message, as a last resort, it will send it to the system
225 \textbf{syslog} to prevent loss of the message, so you might occassionally
226 check the \textbf{syslog} for \bacula{} output (normally \bfilename{var/log/syslog}).
227
228 \bwebdoc{:Messages:Mail}
229 \item [mail]
230 \index[general]{mail}
231 Send the message to the email addresses that are given as a comma
232 separated list in the \textbf{address} field. Mail messages are grouped
233 together during a job and then sent as a single email message when the
234 job terminates. The advantage of this destination is that you are
235 notified about every Job that runs. However, if you backup five or ten
236 machines every night, the volume of email messages can be important.
237 Some users use filter programs such as \bfilename{procmail} to automatically
238 file this email based on the Job termination code (see \textbf{mailcommand}).
239
240 \bwebdoc{:Messages:MailOnError}
241 \item [mail on error]
242 \index[general]{mail on error}
243 Send the message to the email addresses that are given as a comma
244 separated list in the \textbf{address} field if the Job terminates with an
245 error condition. MailOnError messages are grouped together during a job
246 and then sent as a single email message when the job terminates. This
247 destination differs from the \textbf{mail} destination in that if the Job
248 terminates normally, the message is totally discarded (for this
249 destination). If the Job terminates in error, it is emailed. By using
250 other destinations such as \textbf{append} you can ensure that even if the
251 Job terminates normally, the output information is saved.
252
253 \bwebdoc{:Messages:MailOnSuccess}
254 \item [mail on success]
255 \index[general]{mail on success}
256 Send the message to the email addresses that are given as a comma
257 separated list in the \textbf{address} field if the Job terminates
258 normally (no error condition). MailOnSuccess messages are grouped
259 together during a job and then sent as a single email message when the
260 job terminates. This destination differs from the \textbf{mail}
261 destination in that if the Job terminates abnormally, the message is
262 totally discarded (for this destination). If the Job terminates
263 normally, it is emailed.
264
265 \bwebdoc{:Messages:Operator}
266 \item [operator]
267 \index[general]{operator}
268 Send the message to the email addresses that are specified as a comma
269 separated list in the \textbf{address} field. This is similar to
270 \textbf{mail} above, except that each message is sent as received. Thus there
271 is one email per message. This is most useful for \textbf{mount} messages
272 (see below).
273
274 \bwebdoc{:Messages:Console}
275 \item [console]
276 \index[general]{console}
277 Send the message to the \bacula{} console.
278
279 \bwebdoc{:Messages:Catalog}
280 \item [catalog]
281 \index[general]{catalog}
282 Send the message to the Catalog database. The message will be
283 written to the table named \textbf{Log} and a timestamp field will
284 also be added. This permits Job Reports and other messages to
285 be recorded in the Catalog so that they can be accessed by
286 reporting software. \bacula{} will prune the Log records associated
287 with a Job when the Job records are pruned. Otherwise, \bacula{}
288 never uses these records internally, so this destination is only
289 used for special purpose programs (e.g. \textbf{Bweb}).
290 \bwebdoc{:Messages:End}
291
292 \item [stdout]
293 \index[general]{stdout}
294 Send the message to the standard output (normally not used).
295
296 \item [stderr]
297 \index[general]{stderr}
298 Send the message to the standard error output (normally not used).
299
300
301 \end{bdescription}
302 For any destination, the \textbf{message-type} field is a comma separated
303 list of the following types or classes of messages:
304
305 \begin{bdescription}
306
307 \item [events]
308 \index[general]{events}
309 Event messages. ex: Daemon startup/shutdown, Console login/logout,
310 commands... This class of message is not included in the \texttt{all} message
311 type. Specific events can be specified in the form \texttt{events.string}. Each
312 destination directive can support up to 10 sub events.
313
314 \item [info]
315 \index[general]{info}
316 General information messages.
317
318 \item [warning]
319 \index[general]{warning}
320 Warning messages. Generally this is some unusual condition but not expected
321 to be serious.
322
323 \item [error]
324 \index[general]{error}
325 Non-fatal error messages. The job continues running. Any error message should
326 be investigated as it means that something went wrong.
327
328 \item [fatal]
329 \index[general]{fatal}
330 Fatal error messages. Fatal errors cause the job to terminate.
331
332 \item [terminate]
333 \index[general]{terminate}
334 Message generated when the daemon shuts down.
335
336 \item [notsaved]
337 \index[fd]{notsaved}
338 \index[general]{notsaved}
339 Files not saved because of some error. Usually because the file cannot be
340 accessed (i.e. it does not exist or is not mounted).
341
342 \item [skipped]
343 \index[fd]{skipped}
344 \index[general]{skipped}
345 Files that were skipped because of a user supplied option such as an
346 incremental backup or a file that matches an exclusion pattern. This is
347 not considered an error condition such as the files listed for the
348 \textbf{notsaved} type because the configuration file explicitly requests these
349 types of files to be skipped. For example, any unchanged file during an
350 incremental backup, or any subdirectory if the no recursion option is
351 specified.
352
353 \item [mount]
354 \index[dir]{mount}
355 \index[general]{mount}
356 Volume mount or intervention requests from the Storage daemon. These
357 requests require a specific operator intervention for the job to
358 continue.
359
360 \item [restored]
361 \index[fd]{restored}
362 \index[general]{restored}
363 The \textbf{ls} style listing generated for each file restored is sent to
364 this message class.
365
366 \item [saved]
367 \index[fd]{saved}
368 \index[general]{saved}
369 The \textbf{ls} style listing generated for each file saved is sent to
370 this message class.
371
372 \item [all]
373 \index[general]{all}
374 All message types except debug, events and saved.
375
376 \item [security]
377 \index[general]{security}
378 Security info/warning messages principally from unauthorized
379 connection attempts.
380
381 \item [alert]
382 \index[general]{alert}
383 Alert messages. These are messages generated by tape alerts.
384
385 \item [volmgmt]
386 \index[general]{volmgmt}
387 Volume management messages. Currently there are no volume mangement
388 messages generated.
389 \end{bdescription}
390
391 \end{bdescription}
392
393 The following is an example of a valid Messages resource definition, where
394 all messages except files explicitly skipped or daemon termination messages
395 are sent by email to \bref{mailto:[email protected]}{[email protected]}.
396 In addition all mount messages are sent to the operator (i.e. emailed
397 to \bref{mailto:[email protected]}{[email protected]}). Finally
398 all messages other than explicitly skipped files and files saved are sent
399 to the console:
400
401 \begin{bVerbatim}
402 Messages {
403 Name = Standard
404 mail = [email protected] = all, !skipped, !terminate
405 operator = [email protected] = mount
406 console = all, !skipped, !saved
407 catalog = all
408 }
409 \end{bVerbatim}
410
411 With the exception of the email address (changed to avoid junk mail from
412 robot's), an example Director's Messages resource is as follows. Note, the
413 \textbf{mailcommand} and \textbf{operatorcommand} are on a single line -- they had to be
414 split for this manual:
415
416 \begin{bVerbatim}
417 Messages {
418 Name = Standard
419 mailcommand = "bacula/bin/bsmtp -h mail.example.com \
420 -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
421 operatorcommand = "bacula/bin/bsmtp -h mail.example.com \
422 -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \
423 for %j\" %r"
424 MailOnError = [email protected] = all, !skipped, \
425 !terminate
426 append = "bacula/working/log" = all, !skipped, !terminate
427 operator = [email protected] = mount
428 console = all, !skipped, !saved
429 }
430 \end{bVerbatim}
431
432 \label{MessagesEvent}
433 The following is an example of a valid Messages resource definition where
434 Bacula will keep track of the user activity. It is often called ``Auditing''.
435
436 \begin{bVerbatim}
437 Messages {
438 Name = Standard
439 console = all, !skipped, !saved
440 append = bacula/working/bacula.log = all
441
442 catalog = all, events
443 append = bacula/working/audit.log = events, !events.bweb
444 }
445 \end{bVerbatim}
446