| 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 |
|