Manage Postfix Instances Safely with postmulti

You will inspect the Postfix instances known to this host, enable multi-instance management when appropriate, and run a control command against one selected instance or group. Allow 20 to 30 minutes for an existing installation. Creating a working secondary mail instance needs more time for its network, queue, logging and delivery settings.

This guide describes the Postfix package installed on this machine, version 3.8.6-1ubuntu0.1. The installed manual page is the authority for the commands below. Multi-instance management has a primary instance, normally /etc/postfix, and secondary instances with separate configuration, queue and data directories.

1. Check the installed command and current list

Start without changing configuration. Run this as your normal account first:

$ command -v postmulti
/usr/sbin/postmulti
$ dpkg-query -W -f='\${Package} \${Version}\n' postfix
postfix 3.8.6-1ubuntu0.1
$ postmulti -l
-               -               y         /etc/postfix

The list columns are the instance name, group, enabled status and configuration directory. A hyphen means that the primary instance has no assigned name or group. An enabled value of y means the instance is eligible for operations through the multi-instance manager; it does not prove that Postfix is currently running.

Checkpoint: do not create anything until you can identify the primary directory and have a clear name for each secondary instance.

2. Enable multi-instance management

If the list contains only the primary instance, the normal initialisation command adds the manager settings to the primary main.cf. This is a configuration change and normally requires elevated privileges:

$ sudo cp --preserve=all /etc/postfix/main.cf /etc/postfix/main.cf.postmulti-backup
$ sudo postmulti -e init -v

The command sets multi_instance_enable = yes and a multi_instance_wrapper that calls postmulti -p. It does not create a secondary instance. Inspect the result before continuing:

$ postconf -h multi_instance_enable
yes
$ postconf -h multi_instance_wrapper
\${command_directory}/postmulti -p --

Do not run initialisation casually on a production mail server. If the change is wrong, stop and compare the file with the backup. A simple recovery is to restore the backup during a planned maintenance window, then check the file and Postfix configuration before restarting or reloading any service:

$ sudo cp --preserve=all /etc/postfix/main.cf.postmulti-backup /etc/postfix/main.cf
$ sudo postconf -n

3. Create a named secondary instance

Creation changes the primary configuration and creates private directories. Choose paths that are empty or dedicated to this instance. The name must start with postfix-; naming the instance lets postmulti derive sensible default directory names and gives logs a useful identity.

The following example asks for a secondary instance called postfix-mumble in group msa. Review the paths before pressing Enter:

$ sudo postmulti -I postfix-mumble -G msa -e create \
    config_directory=/etc/postfix-mumble \
    queue_directory=/var/spool/postfix-mumble \
    data_directory=/var/lib/postfix-mumble

If a configuration directory already contains both main.cf and master.cf, create imports it as-is. That makes an accidental path selection especially risky. Check the registered instance and its generated configuration:

$ postmulti -l -i postfix-mumble
postfix-mumble  msa             y         /etc/postfix-mumble
$ sudo postconf -c /etc/postfix-mumble -h multi_instance_name multi_instance_group multi_instance_enable
postfix-mumble
msa
yes

The exact spacing in list output varies. If you need to abandon a new instance, first disable and stop it, confirm that its queue is empty, then use postmulti -e destroy -i postfix-mumble only after checking every directory. Destroy removes Postfix-created files and can remove main.cf and master.cf; it is not an undo button for unrelated files.

4. Select instances without guessing

Iterator mode applies one operation to selected instances. The default is all instances. Use -i for one name, -g for a group, and - to select the primary instance. List first when a command could affect more than one mail service:

$ postmulti -l -g msa
$ postmulti -i postfix-mumble -l
postfix-mumble  msa             y         /etc/postfix-mumble

To run a Postfix control command, use -p. This example asks only the named instance for status and normally does not alter its configuration:

$ sudo postmulti -i postfix-mumble -p status

Use -p start, -p stop or -p reload only with a maintenance plan. These commands can affect mail delivery. Postmulti treats start-like, stop-like and control commands differently: disabled instances are skipped for the relevant operations, and stop operations use reverse iteration order.

5. Run an instance-aware diagnostic

Use -x when the command itself needs Postfix's per-instance environment. The following is read-only and prints the configuration directory and instance name:

$ postmulti -i - -x sh -c 'printf "MAIL_CONFIG=%s\n" "$MAIL_CONFIG"; printf "multi_instance_name=%s\n" "$multi_instance_name"'
MAIL_CONFIG=/etc/postfix
multi_instance_name=

In a secondary instance, MAIL_CONFIG points at that instance's configuration directory. Do not pass untrusted text as a shell fragment after -x. Keep the command fixed and pass data as quoted arguments where possible.

6. Change status deliberately

disable changes only the selected instance's multi_instance_enable setting. It prevents the instance being started, stopped or controlled through the multi-instance manager, although an explicit postfix -c CONFIG_DIRECTORY command can still operate it:

$ sudo postmulti -e disable -i postfix-mumble
$ postmulti -l -i postfix-mumble
postfix-mumble  msa             n         /etc/postfix-mumble
$ sudo postmulti -e enable -i postfix-mumble

Disabling is not the same as stopping. Check the service state separately before maintenance, and do not assume that a disabled instance has no queued messages or running processes.