# 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).