4. E-mail
Prev Chapter 4. Configuration of logging facilities Next

4. E-mail

It is possible to define email recipients at compile-time, but it is also possible to define recipients, or aliases (lists of recipients) in the configuration file. Each recipient (list) definition starts with either:

SetMailAddress= recipient

or:

SetMailAlias= listname: addresslist

Filters and/or a threshold severity for the recipient (list) may follow. The definition of a recipient is ended (a) explicitely when terminated with the line CloseAddress , or (b) implicitely when another recipient (list) definition is started.

Items that can/must be configured are:

Recipients address

SetMailAddress= username@hostname

Each address must on a separate line in the configuration file.

[Tip]Tip

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

Recipients address list

SetMailAlias= listname: addresslist

Define an alias for a list of (already defined) recipients. The format is listname":" addresslist, where addresses in addresslist can be separated by comma, tab, or space. Logging threshold and filters (see below) can be set for a list as for an individual recipient, but will take effect only for email that is specifically targeted at the list (e.g. via a per-queue rule in the logfile monitoring module).

Logging threshold

SetAddrSeverity= severity

This defines a logging threshold severity for the last defined recipient (list). The syntax is the same as for MailSeverity .

[Note]MailSeverity and SetAddrSeverity

The MailSeverity setting in the [Log] section defines an upper bound for all recipients. Messages not included by the MailSeverity setting will never be emailed.

NOT Filter

SetMailFilterNot= list_of_regexes

Defines a filtering condition for the last defined recipient (list). If there is no recipient (list) defined yet, it applies to the compiled-in recipients.

List items are POSIX regular expressions. As whitespace (blank or tab) is a valid separator in a list, strings with whitespace must be enclosed in single or double quotes. If a string begins with a double quote, enclose it in single quotes (and vice versa).

If used, then NONE of the regular expressions in list can occur in a message, otherwise it will not be sent by email.

AND Filter

SetMailFilterAnd= list

[Note]Order of evaluation

AND conditions are evaluated after all NOT conditions.

If used, then ALL strings in list must occur in a message, otherwise it will not be sent by email. The syntax is the same as for SetMailFilterNot .

OR Filter

SetMailFilterOr= list

[Note]Order of evaluation

OR conditions are evaluated after all AND conditions.

If used, then AT LEAST ONE of the strings in list must occur in a message, otherwise it will not be sent by email. The syntax is the same as for SetMailFilterNot .

Closing a recipient (list) definition

CloseAddress

This explicitely closes the definition of a recipient (list). However, this is optional syntactic sugar (i.e. not really required), since recipient (list) definitions are closed implicitely by the beginning of another recipient (list) definition (i.e. SetMailAddress or SetMailAlias ).

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.

Sender

SetMailSender= string

Here, string is the address that is inserted in the From: field. If a name without domain is given (i.e. without '@xyz.tld'), the FQDN of the local host will be added automatically.

SMTP port

SetMailPort= port_number

This option allows to specify a custom port for SMTP (the default is 25).

Example: 

	[Misc]  
	#
	# Do not send messages about added files, and startup messages.
	# We have no recipient defined yet, thus this applies to
	# compiled-in recipients only (if there are any).
	#
	SetMailFilterNot = 'POLICY ADDED', START
	# 
	# E-mail recipient (offsite in this case). 
	# 
	SetMailAddress=username@host.some_domain.com
	SetMailFilterNot = LOGKEY
	CloseAddress
	# 
	# 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
	#
	# Do not send messages about added files, and startup messages
	#
	SetMailFilterNot = 'POLICY ADDED', START
	#
	# To all recipients in a single mail. 
	MailSingle=yes

4.1. 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 Section 2 ), 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 ( Section 2 ).

The signature is followed by a unique identification string. This is used to identify separate 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-----
[Tip]Integrity 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).

[Warning]CAVEATS

Verification will fail, if the compiled-in key of the verifying executable is different from the one that generated the message(s) (see Section 2 ).

If you use a pre-compiled executable from some binary distribution, be sure to read Section 2 carefully.

Prev Up Next
3. Activating logging facilities and filtering messages Home 5. Log file