E-mail

Items that must be configured are:

Recipients address

SetMailAddress=username@hostname

Up to eight addresses are possible, each one at most 63 characters long, each on a seperate line in the configuration file.

TipTIP
 

it is recommended to use numerical IP addresses instead of host names (to avoid DNS lookups).

Relay host / Mail exchanger

SetMailRelay=mail.some_domain.com

You may need this option because some sites don't allow outbound e-mail connections from any arbitrary host. If the recipient is offsite, and your site uses a mail relay host to route outbound e-mails, you need to specify the relay host.

Maximum interval

SetMailTime=86400

You may want to set a maximum interval between any two consecutive e-mails, to be sure that samhain is still 'alive'.

Maximum pending

SetMailNum=10

Messages can be queued to send several messages in one e-mail. You may want to set the the maximum number of messages to queue. (Note: messages of highest priority (alert) are always sent immediately. At most 128 messages can be queued.

Multiple recipients

MailSingle=yes/no

If there are multiple recipients, whether to send a single mail with the recipient list, or send multiple mails. If all recipients are on same domain, a single mail may suffice, otherwise it depends on whether the mail server supports forwarding (for security, most don't).

Subject line

MailSubject=string

Here, string may contain the placeholders %T, %H, %S, and/or %M that will get replaced by the time, hostname, message severity and message text, respectively. The default subject line is equivalent to "%T %H". This option may be useful if you want to send emails to an email-to-sms gateway.

Example:

  [Misc]  
  # 
  # E-mail receipient (offsite in this case). Up to eight addresses,
  # each one at most 63 characters long.
  # 
  SetMailAddress=username@host.some_domain.com 
  # 
  # Need a relay host for outgoing mail. 
  # 
  SetMailRelay=relay.mydomain.com 
  #  
  # Number of pending mails. 
  # 
  SetMailNum=10 
  #  
  # Maximum time between e-mails. 
  # Want a message every day, just to be sure that the 
  # program still runs. 
  # 
  SetMailTime=86400
  #  
  # To all recipients in a single mail. 
  MailSingle=yes 

E-mail reports and their integrity

The subject line contains timestamp and local hostname, which are repeated in the message body. samhain uses its own built-in SMTP code rather than the system mailer, because in case of temporary connection failures, the system mailer (e.g. sendmail) would queue the message on disk, where it may become visible to unauthorized persons.

During temporary connection failures, messages are stored in memory. The maximum number of stored messages is 128. samhain will re-try to mail every hour for at most 48 hours. In conformance with RFC 821, samhain will keep the responsibility for the message delivery until the recipient's mail server has confirmed receipt of the e-mail (except that, as noted above, after 48 hours it will assume a permanent connection failure, i.e. e-mailing will be switched off).

The body of the mail may consist of several messages that were pending on the internal queue (see the Section called Overview of logging facilities>), followed by a signature that is computed from the message and a key. The key is initialized with a random number, and for each e-mail iterated by a hash chain.

The initial key is revealed in the first email sent (obviously, you have to believe that this first e-mail is authentic). This initial key is not transmitted in cleartext, but encrypted with a one-time pad (the Section called Integrity of the executable in the chapter called Security Design>).

The signature is followed by a unique identification string. This is used to identify seperate audit trails (here, a trail is a sequence of e-mails from the same run of samhain), and to enumerate individual e-mails within a trail.

The mail thus looks like:

  -----BEGIN MESSAGE-----
  first message    
  second message    
  ... 
  -----BEGIN SIGNATURE-----
  signature 
  ID TRAIL_ID:hostname 
  -----END MESSAGE-----

TipIntegrity verification
 

To verify the integrity of an e-mail audit trail, a convenience function is provided:

samhain -M /mailbox/file/path

The mailbox file may contain multiple and/or overlapping audit trails from different runs of samhain and/or different clients (hosts).

WarningCAVEATS
 

Verification will fail, if the compiled-in key of the verifying executable is different from the one that generated the message(s) (see the Section called Integrity of the executable in the chapter called Security Design>).

If you use a pre-compiled executable from some binary distribution, be sure to read the Section called Integrity of the executable in the chapter called Security Design> carefully.