5.3. Logging to external destinations

Entries in the buffer can also be sent on to external destinations, such as via email or syslog. Support for triggering SNMP traps may be provided in a future software release.

You can set these differently for each log target. There is inevitably a slight lag between the event happening and the log message being sent on, and in some cases, such as email, you can deliberately delay the sending of logs to avoid getting an excessive number of emails.

If an external logging system cannot keep up with the rate logs are generated then log entries can be lost. The fastest type of external logging is using syslog which should manage to keep up in pretty much all cases.

5.3.1. Syslog

The FB2900 supports sending of log entries across a network to a syslog server. Syslog is described in RFC5424, and the FB2900 includes microsecond resolution time stamps, the hostname (from system settings) and a module name in entries sent via syslog. Syslog logging is very quick as there is no reply, and syslog servers can be easily set up on most operating systems, particularly Unix-like systems such as Linux.

Note

Older syslog servers will typically show time and hostname twice, and will need upgrading.

The module name refers to which part of the system caused the log entry, and is also shown in all other types of logging such as web and console.

To enable log messages to be sent to a syslog server, you need to create a syslog object that is a child of the log target (log) object. You must then specify the DNS name or IP address of your syslog server by setting the server attribute on the syslog object. You can also set the facility and/or severity values using these attributes :-

  • facility : the 'facility' to be used in the syslog messages - when syslog entries are generated by subsystems or processes in a general-purpose operating system, the facility typically identifies the message source ; where the commonly used facility identifiers are not suitable, the "local0" thru "local7" identifiers can be used. If the facility attribute is not set, it defaults to LOCAL0
  • severity : the severity value to be used in the syslog messages - if not set, the severity defaults to NOTICE

The FB2900 normally uses the 'standard' syslog port number of 514, but if necessary, you can change this by setting the port attribute value.

5.3.2. Email

You can cause logs to be sent by e-mail by creating an email object that is a child of the log target (log) object.

An important aspect of emailed logs is that they have a delay and a hold-off. The delay means that the email is not sent immediately because often a cluster of events happen over a short period and it is sensible to wait for several log lines for an event before e-mailing.

The hold-off period is the time that the FB2900 waits after sending an e-mail, before sending another. Having a hold-off period means you don't get an excessive number of e-mails ; since the logging system is initially storing event messages in RAM, the e-mail that is sent after the hold-off period will contain any messages that were generated during the hold-off period.

The following aspects of the e-mail process can be configured :-

  • subject : you can either specify the subject, by setting the subject attribute value, or you can allow the FB2900 to create a subject based on the first line of the log message
  • e-mail addresses : as to be expected, you must specify a target e-mail address, using the to attribute. You can optionally specify a From: address, by setting the from atttribute, or you can allow the FB2900 to create an address based on the unit's serial number
  • outgoing mail server : the FB2900 normally sends e-mail directly to the Mail eXchanger (MX) host for the domain, but you can optionally specify an outgoing mail server ('smart host') to use instead, by setting the server attribute
  • SMTP port number : the FB2900 defaults to using TCP port 25 to perform the SMTP mail transfer, but if necessary you can set the port attribute to specify which port number to use
  • retry delay : if an attempt to send the e-mail fails, the FB2900 will wait before re-trying ; the default wait period is 10 minutes, but you can change this by setting the retry attribute

An example of a simple log target with e-mailing is available in a factory reset configuration - the associated XML is shown below, from which you can see that in many cases, you only need to specify the to attribute (the comment attribute is an optional, general comment field) :-

 <log name="fb-support"
      comment="Log target for sending logs to FireBrick support team">
  <email to="crashlog@firebrick.ltd.uk"
         comment="Crash logs emailed to FireBrick Support team"/>
 </log>

      

A profile can be used to stop emails at certain times, and when the email logging is back on an active profile it tries to catch up any entries still in the RAM buffer if possible.

5.3.2.1. E-mail process logging

Since the process of e-mailing can itself encounter problems, it is possible to request that the process itself be logged via the usual log target mechanism. This is done by specifying one or more of the log, log-debug and log-error attributes.

Note

We recommend that you avoid setting these attributes such that specify the log-target containing the email object, otherwise you are likely to continually receive e-mails as each previous e-mail process log will trigger another e-mail - the hold-off will limit the rate of these mails though.