
#include "bacula_template.inc" title="Messages Resource"

<H1>Messages Resource</H1>


<h2><a name="MessageResource"></a>The Messages Resource</h2> The
Messages resource defines how messages are to be handled and
destinations to which they should be sent.
<p>Even though each daemon has a full message handler, 
within the File daemon and the Storage daemon, you will normally
choose to send all the appropriate messages back to the Director. 
This permits all the messages associated with a single Job to
be combined in the Director and sent as a single email message
to the user, or logged together in a single file.

<p>Each message that Bacula generates (i.e.  that each daemon
generates) has an associated type such as INFO, WARNING, ERROR, 
FATAL, etc.
Using the message resource, you can specify which message types you wish
to see and where they should be sent. In addition, a message may be
sent to multiple destinations. For example, you may want all error 
messages both logged as well as sent to you in an email. By defining
multiple messages resources, you can have different message handling
for each type of Job (e.g. Full backups versus Incremental backups).
<p>
In general, messages are attached to a Job and are included
in the Job report. There are some rare cases, where this is not possible,
e.g. when no job is running, or if a communications error occurs
between a daemon and the director. In those cases, the message
may remain in the system, and should be flushed at the end of
the next Job. However, since such messages are not attached
to a Job, any that are mailed will be sent to
<b>/usr/lib/sendmail</b>. On some systems, such as FreeBSD,
if your sendmail is in a different place, you may want
to link it to the the above location.

<p>The records contained in a Messages resource consist of a
<b>destination</b> specification followed by a list of
<b>message-types</b> in the format:
<dl>

<dl>
  <dt>destination = message-type1, message-type2, message-type3, ...</dt>
      <dd></dd>
</dl>
  <p>
  or for those destinations that need and address specification (e.g. email):
<dl>
  <dt>destination = address = message-type1, message-type2, message-type3, ...
      </dt><dd></dd>
</dl>
<p> Where <b>destination</b> is one of a predefined
set of keywords that define where the message is to be sent
(<b>stdout</b>, <b>file</b>, ...), <b>message-type</b> is one of a
predefined set of keywords that define the type of message generated by
<b>Bacula</b> (<b>ERROR</b>, <b>WARNING</b>, <b>FATAL</b>, ...),
and <b>address</b> varies according to the <b>destination</b> keyword,
but is typically and email address or a filename.
</dl>

<p>The following are the list of the possible record definitions
that can be used in a message resource.

<dl>
  <dt>Messages</dt><dd>Start of the Messages records.</dd>
  <dt>Name = &lt;name&gt;</dt><dd>The name of the Messages resource.
      The name you specify here will be used to tie this Messages
      resource to a Job and/or to the daemon.
</dd>
  <a name="mailcommand"></a>
  <dt>MailCommand = &lt;command&gt;</dt><dd>In the absence of this resource,
      Bacula will send all mail using the following command:
      <p><b>mail -s &quot;Bacula Message&quot; &lt;recipients&gt;</b>
      <p>
      In many cases, depending on your machine, this command may not work.
      Using the <b>MailCommand</b>, you can specify exactly how to send
      the mail. During the processing of the <b>command</b>, normally
      specified as a quoted string, the following substitutions will be
      used:
      <ul type="circle">
      <li>%%  = %</li>
      <li>%c = Client's name</li>
      <li>%d = Director's name</li>
      <li>%e = Job Exit code (OK, Error, ...)</li>
      <li>%i = Job Id</li>
      <li>%j = Unique Job name</li>
      <li>%l = Job level</li>
      <li>%n = Job name</li>
      <li>%r = Recipients</li>
      <li>%t = Job type (e.g. Backup, ...)</li>
      </ul>
      <p>
      The following is the command I (Kern) use. Note, the whole
      command should appear on a single line in the configuration file
      rather than split as is done here for presentation:
      <p><b>
      mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.whitehouse.com -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
      </b><p>
      Note, the <b>bsmtp</b> program is provided as part of <b>Bacula</b>.   
      For additional details, please see the <a href="progs.html#bsmtp">
      bsmtp -- Customizing Your Email Messages</a> section of the
      Bacula Utility Programs chapter of this manual.  Please test any 
      <b>mailcommand</b> that you use to ensure that your bsmtp gateway accepts
      the addressing form that you use. Certain program such as Exim can be very
      selective as to what forms are permitted particularly in the from part.
      </dd>
  <dt>OperatorCommand = &lt;command&gt;</dt><dd>This resource specification is
      similar to the <b>MailCommand</b> except that it is used for Operator
      messages. The substitutions performed for the <b>MailCommand</b> are
      also done for this command. Normally, you will set this command to the
      same value as specified for the <b>MailCommand</b>. </dd>

  <dt>Debug = &lt;debug-level&gt;</dt><dd>This sets the debug message level
      to the debug level, which is an integer. Higher debug levels cause more
      debug information to be produced. You are requested not to use this
      record since it will be deprecated. </dd>

  <dt>&lt;destination&gt; = &lt;message-type1&gt;, &lt;message-type2&gt, ...</dt><dd>

  <p>
  Where <b>destination</b> may be one of the following:</dd>

   <dl>
     <dt>stdout</dt><dd>Send the message to standard output.</dd>

     <dt>stderr</dt><dd>Send the message to standard error.</dd>

     <dt>console</dt><dd>Send the message to the console (Bacula Console).
         These messages are held until the console program
         connects to the Director.</dd>

   </dl>


  <dt>&lt;destination&gt; = &lt;address&gt; = &lt;message-type1&gt;, &lt;message-type2&gt, ...</dt><dd>
  <p>
  Where <b>address</b> depends on the <b>destination</b>, which 
  may be one of the following:                   
   <dl>
      <dt>director</dt><dd>Send the message to the Director whose name
         is given in the <b>address</b> field.  Note, in the current
         implementation, the Director Name is ignored, and the message
         is sent to the Director that started the Job.</dd>

      <dt>file</dt><dd>Send the message to the filename given in
          the <b>address</b> field. If the file already exists, it will be
          overwritten.</dd>

      <dt>append</dt><dd>Append the message to the filename given
          in the <b>address</b> field. If the file already exists, it will
          be appended to. If the file does not exist, it will be created.</dd>

      <dt>syslog</dt><dd>Send the message to the system log (syslog)
          using the facility specified in the <b>address</b> field.
          Note, for the moment, the <b>address</b> field is ignored
          and the message is always sent to the <b>LOG_ERR</b> facility.
          </dd>

      <dt>mail</dt><dd>Send the message to the email addresses that are
          given as a comma separated list in the <b>address</b> field.
          Mail messages are grouped together during a job and then
          sent as a single email message when the job terminates.
          The advantage of this destination is that you are notified about
          every Job that runs. However, if you backup 5 or 10 machines every
          night, the volume of email messages can be important. Some users
          use filter programs such as <b>procmail</b> to automatically file
          this email based on the Job termination code (see <b>mailcommand</b>).

      <dt>mail on error<dt><dd>Send the message to the email addresses
          that are given as a comma separated list in the <b>address</b>
          field if the Job terminates with an error condition.
          MailOnError messages are grouped together during a job and
          then sent as a single email message when the job terminates.
          This destination differs from the <b>mail</b> destination in
          that if the Job terminates normally, the message is totally
          discarded (for this destination).  If the Job terminates in
          error, it is emailed.  By using other destinations such as
          <b>append</b> you can ensure that even if the Job terminates
          normally, the output information is saved.

      <dt>operator</dt><dd>Send the message to the email addresses that
          are specified as a comma separated list in the <b>address</b>
          field. This is similar to <b>mail</b> above, except that each
          message is sent as received. Thus there is one email per message.
          This is most useful for <b>mount</b> messages (see below).</dd>

   </dl>
  <p>
  For any destination, the <b>message-type</b> field is a comma
  separated list of the following types or classes of messages:
   <dl>
     <dt>info</dt><dd>General information messages.</dd>

     <dt>warning</dt><dd>Warning messages. Generally this is some
         unusual condition but not expected to be serious. </dd>

     <dt>error</dt><dd>Non-fatal error messages. The job continues running.
         Any error message should be investigated as it means that something
         went wrong.</dd>

     <dt>fatal</dt><dd>Fatal error messages. Fatal errors cause the
        job to terminate.</dd>

     <dt>terminate</dt><dd>Message generated when the daemon shuts down.</dd>

     <dt>saved</dt><dd>Files saved normally.</dd>

     <dt>notsaved</dt><dd>Files not saved because of some error.
         Usually because the file cannot be accessed (i.e.  it does not
         exist or is not mounted).</dd>

     <dt>skipped</dt><dd>Files that were skipped because of a user
         supplied option such as an incremental backup or a file that
         matches an exclusion pattern.  This is not considered an
         error condition such as the files listed for the
         <b>notsaved</b> type because the configuration file
         explicitly requests these types of files to be skipped.  For
         example, any unchanged file during an incremental backup, or
         any subdirectory if the no recursion option is
         specified.</dd>

     <dt>mount</dt><dd>Volume mount or intervention requests from the
         Storage daemon. These requests require a specific operator
         intervention for the job to continue.</dd>

     <dt>restored</dt><dd>The <b>ls</b> style listing generated for each
         file restored is sent to this message class.</dd>

     <dt>all</dt><dd>All message types.</dd>

     <dt>*security</dt><dd>Security info/warning messages (not currently
         implemented).</dd>

   </dl>
</dl>

The following is an example of a valid Messages resource definition,
where all messages except files explicitly skipped or daemon termination
messages are sent by email to enforcement@sec.com.  In addition all mount
messages are sent to the operator (i.e.  emailed to enforcement@sec.com).
Finally all messages other than explicitly skipped files and files saved
are sent to the console:

<pre>
Messages {
  Name = Standard
  mail = enforcement@sec.com = all, !skipped, !terminate
  operator = enforcement@sec.com = mount
  console = all, !skipped, !saved
}
</pre>

<p>
With the exception of the email address (changed to avoid junk mail
from robot's), Kern's Director's Messages resource is as follows.
Note, the <b>mailcommand</b> and <b>operatorcommand</b> are on a single
line -- they had to be split for this manual:
<pre>
Messages {
  Name = Standard
  mailcommand = "bacula/bin/bsmtp -h mail.whitehouse.com \\
    -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r"
  operatorcommand = "bacula/bin/bsmtp -h mail.whitehouse.com \\
    -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \\
        for %j\" %r"
  MailOnError = security@whitehouse.com = all, !skipped, \\
                !terminate
  append = "bacula/bin/log" = all, !skipped, !terminate
  operator = security@whitehouse.com = mount
  console = all, !skipped, !saved
}
</pre>

<page_prev name="Storage Daemon Configuration" url="storedconf.html">
<page_next name="Console Configuration" url="consoleconf.html">
