Go to the first, previous, next, last section, table of contents.

51. Log files

Exim writes three different logs, referred to as the main log, the reject log, and the panic log.

The logs may be written to local files, or to syslog, or both. However, it should be noted that many syslog implementations use UDP as a transport, and are therefore unreliable in the sense that messages are not guaranteed to arrive at the loghost, nor is the ordering of messages necessarily maintained. It has also been reported that on large log files (tens of megabytes) you may need to tweak syslog to prevent it syncing the file with each write -- on Linux this has been seen to make syslog take 90% plus of CPU time.

The destination for Exim's logs is configured by setting LOG_FILE_PATH in `Local/Makefile' or by setting log_file_path in the run time configuration. This latter string is expanded, so it can contain, for example, references to the host name:

log_file_path = /var/log/$primary_hostname/exim_%slog

It is generally advisable, however, to set the string in `Local/Makefile' rather than at run time, because then the setting is available right from the start of Exim's execution. Otherwise, if there's something it wants to log before it has read the configuration file (for example, an error in the configuration file) it will not use the path you want, and may not be able to log at all.

The value of LOG_FILE_PATH or log_file_path is a colon-separated list, currently limited to at most two items. This is one option where the facility for changing a list separator may not be used. The list must always be colon-separated. If an item in the list is `syslog' then syslog is used; otherwise the item must either be an absolute path, containing `%s' at the point where `main', `reject', or `panic' is to be inserted, or be empty, implying the use of the default path, which is `log/%slog' in the spool directory. The default path is used if nothing is specified. Here are some examples of possible settings:

LOG_FILE_PATH=syslog                      syslog only
LOG_FILE_PATH=:syslog                     syslog and default path
LOG_FILE_PATH=syslog : /usr/log/exim_%s   syslog and specified path
LOG_FILE_PATH=/usr/log/exim_%s            specified path only

If there are more than two paths in the list, the first is used and a panic error is logged.

51.1 Logging to local files

A utility script called exicyclog which renames and compresses the main and reject logs each time it is called is provided for use with logs written to local files. The maximum number of old logs to keep can be set. It is suggested this is run as a daily cron job. A Perl script called eximstats which does simple analysis of main log files is also provided. See chapter 53 for details of both these utilities.

An Exim delivery process opens the main log when it first needs to write to it, and it keeps the file open in case subsequent entries are required -- for example, if a number of different deliveries are being done for the same message. However, remote SMTP deliveries can take a long time, and this means that the file may be kept open long after it is renamed if exicyclog or something similar is being used to rename log files on a regular basis. To ensure that a switch of log files is noticed as soon as possible, Exim calls stat() on the main log's name before reusing an open file, and if the file does not exist, or its inode has changed, the old file is closed and Exim tries to open the main log from scratch. Thus, an old log file may remain open for quite some time, but no Exim processes should write to it once it has been renamed.

51.2 Logging to syslog

The use of syslog does not change what Exim logs or the format of its messages. The same strings are written to syslog as to log files. The syslog `facility' is set to LOG_MAIL, and the program name to `exim'. On systems that permit it (all except ULTRIX) the LOG_PID flag is set so that the syslog() call adds the pid as well as the time and host name to each line. The three log streams are mapped onto syslog priorities as follows:

Many log lines are written to both mainlog and rejectlog, so there will be duplicates if these are routed by syslog to the same place.

Exim's log lines can sometimes be very long, and some of its rejectlog entries contain multiple lines when headers are included. To cope with both these cases, entries written to syslog are split into separate syslog() calls at each internal newline, and also after a maximum of 1000 characters. To make it easy to re-assemble them later, each component of a split entry starts with a string of the form `[<n>/<m>]' or `[<n>\<m>]' where <n> is the component number and <m> is the total number of components in the entry. The / delimiter is used when the line was split because it was too long; if it was split because of an internal newline, the \ delimiter is used. For example, supposing the length limit to be 70 instead of 1000, the following would be the result of a typical rejection message to mainlog (LOG_INFO), each line in addition being preceded by the time, host name, and pid as added by syslog:

$smc{[1/3] 1999-09-16 16:09:43 11RdAL-0006pc-00 rejected from [] (ph10):
[2/3]  syntax error in 'From' header when scanning for sender: missing or ma
[3/3] lformed local part in "<>" (envelope sender is <ph10@cam.ac.uk>)}

The same error might cause the following lines to "rejectlog" (LOG_NOTICE):

$smc{[1/14] 1999-09-16 16:09:43 11RdAL-0006pc-00 rejected from [] (ph10):
[2/14]  syntax error in 'From' header when scanning for sender: missing or ma
[3\14] lformed local part in "<>" (envelope sender is <ph10@cam.ac.uk>)
[4\14] Recipients: ph10@some.domain.cam.ac.uk
[5\14] P Received: from [] (ident=ph10)
[6\14]        by xxxxx.cam.ac.uk with smtp (Exim 3.10 #27)
[7\14]        id 11RdAL-0006pc-00
[8\14]        for ph10@cam.ac.uk; Thu, 16 Sep 1999 16:09:43 +0100
[9\14] F From: <>
[10\14]   Subject: this is a test header
[11\14]   X-something: this is another header
[12\14] I Message-Id: <E11RdAL-0006pc-00@xxxxx.cam.ac.uk>
[13\14] B Bcc:
[14/14]   Date: Thu, 16 Sep 1999 16:09:43 +0100}

Log lines that are neither too long nor contain newlines are written to syslog without modification, for example:

1999-09-16 16:09:47 SMTP connection from [] closed by QUIT

The times added by syslog are normally the same as Exim's time stamps (though in a different format, and without the year) but can sometimes be different.

If only syslog is being used, the Exim monitor is unable to provide a log tail display, unless syslog is routing mainlog to a file on the local host and the environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it is.

51.3 Logging message reception

The format of the single-line entry in the main log that is written for every message received is shown in the example below, which is split over several lines in order to fit it on the page:

1995-10-31 08:57:53 0tACW1-0005MB-00 <= kryten@dwarf.fict.book
  H=mailer.fict.book [] U=exim
  P=smtp S=5678 id=<incoming message id>

The H and U fields identify the remote host and record the RFC 1413 identity of the user that sent the message, if one was received. The number given in square brackets is the IP address of the sending host. If there is just a single host name in the H field, as above, it has been verified to correspond to the IP address (see the host_lookup option). If the name is in parentheses, it was the name quoted by the remote host in the SMTP HELO or EHLO command, and has not been verified. If verification yields a different name to that given for HELO or EHLO, the verified name appears first, followed by the HELO or EHLO name in parentheses.

Misconfigured hosts (and mail forgers) sometimes put an IP address, with or without brackets, in the HELO or EHLO command, leading to entries in the log containing things like

H=( []
H=([]) []

which can be confusing. Only the final address in square brackets can be relied on. For locally generated messages, the H field is omitted, and the U field contains the login name of the caller of Exim.

For all messages, the P field specifies the protocol used to receive the message. This is set to `asmtp' for messages received from hosts which have authenticated themselves using the SMTP AUTH command. In this case there is an additional item A= followed by the name of the authenticator that was used. If an authenticated identification was set up by the authenticator's server_set_id option, this is logged too, separated by a colon from the authenticator name.

The id field records the existing message id, if present. The size of the received message is given by the S field. When the message is delivered, headers may get removed or added, so that the size of delivered copies of the message may not correspond with this value (and indeed may be different to each other).

If the log_received_sender option is on, the unrewritten original sender of a message is added to the end of the log line that records the message's arrival, after the word `from'. If the log_received_recipients option is on, a list of all the recipients of a message is added to the log line, preceded by the word `for'. This happens after any unqualified addresses are qualified, but before any rewriting is done. If the log_subject option is on, the subject of the message is added to the log line, preceded by `T=' (T for `topic', since S is already used for `size').

A delivery error message is shown with the sender address `<>', and if it is a locally-generated error message, this is normally followed by an item of the form

R=<message id>

which is a reference to the local identification of the message that caused the error message to be sent.

51.4 Logging deliveries

The format of the single-line entry in the main log that is written for every delivery is shown in one of the examples below, for local and remote deliveries, respectively. Each example has been split into two lines in order to fit it on the page:

1995-10-31 08:59:13 0tACW1-0005MB-00 => marv <marv@hitch.fict.book>
  D=localuser T=local_delivery
1995-10-31 09:00:10 0tACW1-0005MB-00 => monk@holistic.fict.book
  R=lookuphost T=smtp H=holistic.fict.book []

For ordinary local deliveries, the original address is given in angle brackets after the final delivery address, which might be a pipe or a file. If intermediate address(es) exist between the original and the final address, the last of these is given in parentheses after the final address. However, log_all_parents can be set to cause all intermediate addresses to be logged.

If a shadow transport was run after a successful local delivery, the log line for the successful delivery has an item added on the end, of the form

ST=<shadow transport name>

If the shadow transport did not succeed, the error message is put in parentheses afterwards.

When a local delivery occurs as a result of routing rather than directing (for example, messages are being batched up for transmission by some other means), the log entry looks more like that for a remote delivery.

For normal remote deliveries, if the log_smtp_confirmation option is on, the response to the final `.' in the SMTP transmission is added to the log line, preceded by `C='. If the final delivery address is not the same as the original address (owing to changes made by routers), the original is shown in angle brackets.

The generation of a reply message by a filter file gets logged as a `delivery' to the addressee, preceded by `>'. The D and T items record the director and transport. For remote deliveries, the router, transport, and host are recorded.

When more than one address is included in a single delivery (for example, two SMTP RCPT commands in one transaction) then the second and subsequent addresses are flagged with `->' instead of `=>'. When two or more messages are delivered down a single SMTP connection, an asterisk follows the IP address in the log lines for the second and subsequent messages.

When the -N debugging option is used to prevent delivery from actually occurring, log entries are flagged with `*>' instead of `=>'.

When a message is discarded as a result of the command `seen finish' being obeyed in a filter file which generates no deliveries, a log entry of the form

1998-12-10 00:50:49 0znuJc-0001UB-00 => discarded
  <low.club@trick4.bridge> D=userforward

is written, to record why no deliveries are logged.

51.5 Deferred deliveries

When a delivery is deferred, a line of the following form is logged:

1995-12-19 16:20:23 0tRiQz-0002Q5-00 == marvin@endrest.book
  T=smtp defer (146): Connection refused

In the case of remote deliveries, the error is the one that was given for the last IP address that was tried. Details of individual SMTP failures are also written to the log, so the above line would be preceded by something like

1995-12-19 16:20:23 0tRiQz-0002Q5-00 Failed to connect to endrest.book
  []: Connection refused

When a deferred address is skipped because its retry time has not been reached, a message is written to the log, but this can be suppressed by changing the log_level option.

51.6 Delivery failures

If a delivery fails, a line of the following form is logged:

1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.film
  <jimtrek99.film>: unknown mail domain

This is followed (eventually) by a line giving the address to which the delivery error has been sent.

51.7 Fake deliveries

If a delivery does not actually take place because the -N options has been used to suppress it, an apparently normal delivery line is written to the log, except that `=>' is replaced by `*>'.

51.8 Completion

A line of the form

1995-10-31 09:00:11 0tACW1-0005MB-00 Completed

is written to the main log when a message is about to be removed from the spool at the end of its processing.

51.9 Other log entries

Various other types of log entry are written from time to time. Most should be self-explanatory. Among the more common are:

51.10 Log level

The log_level configuration option controls the amount of data written to the main log. The higher the number, the more is written. A value of 6 causes all possible messages to appear, though higher levels may get defined in the future. Zero sets a minimal level of logging, with higher levels adding the following, successively:

1   rejections because of policy
    re-addressing by the system filter

2   $t rejections because of message size

3   $t verification failures

4   $t SMTP timeouts
    SMTP connection refusals because too busy
    SMTP unexpected connection loss
    SMTP (dis)connections when log_smtp_connections is set
    SMTP syntax errors when log_smtp_syntax_errors is set
    non-immediate delivery of SMTP messages because of load level,
    or number of connections etc.

5   $t `retry time not reached [for any host]'
    `spool file locked' (i.e. some other process is delivering the message)
    `message is frozen' (when skipping it in a queue run)
    `error message sent to ...'

6   $t invalid HELO and EHLO arguments (see helo_verify)

The default log level is 5, which is on the verbose side. Rejection information is still written to the reject log in all cases.

51.11 Message log

In addition to the four main log files, Exim writes a log file for each message that it handles. The names of these per-message logs are the message ids, and they are kept in the msglog sub-directory of the spool directory. A single line is written to the message log for each delivery attempt for each address. It records either a successful delivery, or the reason (temporary or permanent) for failure. If the log level is 5 or higher, `retry time not reached' messages are also written to individual message logs. If the log level is 4 or less, they are suppressed after the first delivery attempt.

When a local part is expanded by aliasing or a forwarding file, a line is written to the message log when all its child deliveries are completed. SMTP connection failures for each remote host are also logged here. The log is deleted when processing of the message is complete, unless preserve_message_logs is set, but this should be used only with great care because they can fill up your disc very quickly.

Go to the first, previous, next, last section, table of contents.