Postfix logging to file or stdout

-------------------------------------------------------------------------------

Overview

Postfix supports its own logging system as an alternative to syslog (which
remains the default). This is available with Postfix version 3.4 or later.

Topics covered in this document:

  * Configuring logging to file
  * Configuring logging to stdout
  * Rotating logs
  * Limitations

Configuring logging to file

Logging to file solves a usability problem for MacOS, and eliminates multiple
problems for systemd-based systems.

 1. Add the following line to master.cf if not already present (note: there
    must be no whitespace at the start of the line):

        postlog   unix-dgram n  -       n       -       1       postlogd

    Note: the service type "unix-dgram" was introduced with Postfix 3.4. Remove
    the above line before backing out to an older Postfix version.

 2. Configure Postfix to write logging, to, for example, /var/log/postfix.log.
    See also the "Logfile rotation" section below for logfile management.

    In the example below, specifying maillog_file_permissions is optional
    (Postfix 3.9 and later). The default value is 0600, i.e., only the super-
    user can access the file; the value 0644 also adds 'group' and 'other' read
    access.

        # postfix stop
        # postconf maillog_file=/var/log/postfix.log
        # postconf maillog_file_permissions=0644 # (Postfix 3.9 and later)
        # postfix start

    By default, the logfile name must start with "/var" or "/dev/stdout" (the
    list of allowed prefixes is configured with the maillog_file_prefixes
    parameter). This safety mechanism limits the damage from a single
    configuration mistake.

Configuring logging to stdout

Logging to stdout is useful when Postfix runs in a container, as it eliminates
a syslogd dependency.

 1. Add the following line to master.cf if not already present (note: there
    must be no whitespace at the start of the line):

        postlog   unix-dgram n  -       n       -       1       postlogd

    Note: the service type "unix-dgram" was introduced with Postfix 3.4. Remove
    the above line before backing out to an older Postfix version.

 2. Configure main.cf with "maillog_file = /dev/stdout".

 3. Start Postfix with "postfix start-fg".

Rotating logs

The command "postfix logrotate" may be run by hand or by a cronjob. It logs all
errors, and reports errors to stderr if run from a terminal. This command
implements the following steps:

  * Rename the current logfile by appending a suffix that contains the date and
    time. This suffix is configured with the maillog_file_rotate_suffix
    parameter (default: %Y%m%d-%H%M%S).

  * Reload Postfix so that postlogd(8) immediately closes the old logfile.

  * After a brief pause, compress the old logfile. The compression program is
    configured with the maillog_file_compressor parameter (default: gzip).

  * The next time it logs an event, postlogd(8) will create a new logfile, with
    permissions specified with the maillog_file_permissions parameter (default:
    0600).

Notes:

  * This command will not rotate a logfile with a pathname under the /dev
    directory, such as /dev/stdout.

  * This command does not (yet) remove old logfiles.

Limitations

Background:

  * Postfix consists of a number of daemon programs that run in the background,
    as well as non-daemon programs for local mail submission or Postfix
    management.

  * Logging to the Postfix logfile or stdout requires the Postfix postlogd(8)
    service. This ensures that simultaneous logging from different programs
    will not get mixed up.

  * All Postfix programs can log to syslog, but not all programs have
    sufficient privileges to use the Postfix logging service, and many non-
    daemon programs must not log to stdout as that would corrupt their output.

Limitations:

  * Non-daemon Postfix programs will log errors to syslogd(8) before they have
    processed command-line options and main.cf parameters.

  * If Postfix is down, the non-daemon programs postfix(1), postsuper(1),
    postmulti(1), and postlog(1), will log directly to $maillog_file. These
    programs expect to run with root privileges, for example during Postfix
    start-up, reload, or shutdown.

  * Other non-daemon Postfix programs will never write directly to
    $maillog_file (also, logging to stdout would interfere with the operation
    of some of these programs). These programs can log to postlogd(8) if they
    are run by the super-user, or if their executable file has set-gid
    permission. Do not set this permission on programs other than postdrop(1),
    postqueue(1), and (Postfix >= 3.7) postlog(1).

