Route Postfix Mail Logs to a File with postlogd

You will configure Postfix to write its internal log records to a chosen file through postlogd, verify the service definition and output, and return to the previous empty setting if the result is not what you want. These examples use Postfix 3.8.6 from the installed postfix package on this machine.

Allow about fifteen minutes. You need a shell, access to the Postfix configuration, and a directory with enough free space for the log. Reading configuration is an ordinary command. Changing main.cf, reloading Postfix and reading a root-owned log may require elevated privileges. This guide does not rotate, delete or truncate an existing log.

1. Check the installed version and service

Start with read-only checks so you know which installation you are changing:

$ dpkg-query -W -f='${Package} ${Version}\n' postfix
postfix 3.8.6-1ubuntu0.1
$ postconf -h config_directory
/etc/postfix
$ postconf -M postlog
postlog    unix-dgram n  -       n       -       1       postlogd

The last line is the master.cf service entry. It tells Postfix to provide the postlog Unix datagram service using the postlogd server. You normally do not start postlogd by hand, and the installed server is under /usr/lib/postfix/sbin/postlogd, not on the ordinary command path.

Checkpoint: if postconf -M postlog prints no service, stop here and inspect the local master.cf. Do not invent a service definition from an example copied from another Postfix release.

2. Inspect the current logging setting

Ask postconf for the effective value of maillog_file:

$ postconf -h maillog_file

An empty line means that this setting is not selecting a Postfix logfile. It does not mean that every Postfix diagnostic disappears: programs can still use the system logging service, and early messages can go to syslog before configuration has been processed. The postlogd service becomes relevant when maillog_file is non-empty.

Choose a path that is reserved for Postfix logging. The example below uses /var/log/postfix/postfix.log; replace it with the path required by your host's logging policy. Before changing anything, check whether the file already exists:

$ sudo ls -l /var/log/postfix/postfix.log
ls: cannot access '/var/log/postfix/postfix.log': No such file or directory

The error above is safe and expected when this is a new destination. If a file already exists, do not assume it is disposable. Confirm its owner, contents and rotation policy before pointing Postfix at it.

3. Set a new logfile

Make the configuration change with elevated privileges:

$ sudo postconf -e 'maillog_file = /var/log/postfix/postfix.log'

postconf -e updates the Postfix configuration rather than requiring you to edit spacing or parameter ordering by hand. It does not create a useful log record by itself. Check the stored value immediately:

$ postconf -h maillog_file
/var/log/postfix/postfix.log

Checkpoint: if the value is not exactly the path you intended, fix it before reloading. The shell redirection examples in this guide are not involved, so an existing logfile has not been truncated.

4. Reload Postfix to pick up the change

Reload the Postfix service as root:

$ sudo postfix reload
postfix/postfix-script: refreshing the Postfix mail system

The installed manual says that configuration changes are picked up automatically because postlogd processes run for a limited time, and that postfix reload speeds up the change. A reload is the explicit checkpoint: it asks the running Postfix installation to reread its configuration. It is not a replacement for testing a service after a broader configuration change.

Do not treat a successful reload as proof that the file is receiving records. Check the service and the destination:

$ postconf -M postlog
postlog    unix-dgram n  -       n       -       1       postlogd
$ sudo ls -l /var/log/postfix/postfix.log
-rw------- 1 postfix postfix 0 Sep 26 12:00 /var/log/postfix/postfix.log

The size and timestamp are host-specific. A zero-byte file immediately after reload is not a failure; it may simply mean that no Postfix action has produced a record yet.

5. Generate and verify one safe record

Use a normal Postfix administrative query to exercise the installation without sending mail:

$ postconf myhostname
myhost.example.invalid
$ sudo tail -n 20 /var/log/postfix/postfix.log

The first command only reads configuration and may not create a log entry. For a stronger check, perform the routine Postfix operation you actually need to observe, then inspect the file. For example, after an ordinary postfix status or a controlled queue operation, run:

$ sudo tail -n 20 /var/log/postfix/postfix.log
Sep 26 12:01:14 myhost postfix/postfix-script[1234]: the Postfix mail system is running

Exact timestamps, process IDs, hostname and wording vary. The useful result is a new record in the configured file. If there is no record, check postfix status, the system journal or syslog, the file's ownership and the free space on its filesystem. Do not make the file world-writable to get past a permission error.

6. Undo the change without deleting the log

Disabling this destination is reversible, but it does not remove the file or its historical records. Set the parameter back to an empty value and reload:

$ sudo postconf -e 'maillog_file ='
$ sudo postfix reload
$ postconf -h maillog_file

Keep the old logfile until you have checked your retention requirements. Removing it with sudo rm would be an irreversible data change and is not part of undoing the Postfix setting. If you need to preserve records elsewhere, copy or rotate the file using your normal logging process before removing anything.

Common traps

• postlogd is an internal server. Do not run its binary as if it were a command-line logger; Postfix invokes it through the postlog service in master.cf.
• An empty maillog_file disables this file destination. It does not promise that all diagnostics use the same route, especially before programs process their configuration.
• Only postfix, postsuper, postmulti and postlog are documented as writing directly to $maillog_file when Postfix is down. Other non-daemon programs depend on the internal service and privilege rules.
• Do not add set-gid permission to arbitrary Postfix programs. The manual limits that exception to postdrop, postqueue and, from Postfix 3.7, postlog.