Manage Multiple Postfix Instances with postmulti

postmulti runs several Postfix instances on one box, say a public MX plus a submission-only service, without you hand-juggling separate directories. Budget 20 to 30 minutes to inspect an existing installation; a working secondary instance takes longer once its network, queue, logging and delivery settings are factored in.

This describes the Postfix package installed here, version 3.8.6-1ubuntu0.1; the local manual page is the authority for everything below. Multi-instance management has one primary instance, normally /etc/postfix, and any number of secondary instances with their own configuration, queue and data directories.

1. Check the installed command and current list

Start without changing anything, as your normal account:

$ 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 columns are instance name, group, enabled status and configuration directory. A hyphen means 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 mean Postfix is currently running.

2. Turn on multi-instance management

If the list shows only the primary instance, the normal init command adds the manager settings to its main.cf. That is a configuration change and normally needs elevated privileges:

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

It sets multi_instance_enable = yes and a multi_instance_wrapper that calls postmulti -p. It does not create a secondary instance on its own. Check the result before continuing:

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

$ 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, so use paths that are empty or dedicated to this instance. The name must start with postfix-: that lets postmulti derive sensible default directory names, and gives its logs a recognisable identity.

This example asks for a secondary instance called postfix-mumble in group msa. Read the paths carefully 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 has both main.cf and master.cf in it, create imports it as-is, which makes a wrong path especially risky here. 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

Exact spacing in list output varies. To abandon a new instance, first disable and stop it, confirm its queue is empty, then run postmulti -e destroy -i postfix-mumble, and only after checking every directory it touches. Destructive action: destroy removes Postfix-created files and can take main.cf and master.cf with it. It is not an undo button for anything else in those directories.

4. Select instances without guessing

Iterator mode applies one operation to selected instances, and defaults to all of them. Use -i for one name, -g for a group, and - for the primary instance. List first whenever a command could touch more than one mail service:

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

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

$ sudo postmulti -i postfix-mumble -p status

Only use -p start, -p stop or -p reload with a maintenance plan in hand: these affect mail delivery. Postmulti treats start-like, stop-like and control commands differently, and disabled instances are skipped for the relevant operations; stop operations run in reverse iteration order.

5. Run an instance-aware diagnostic

Use -x when the command itself needs Postfix's per-instance environment. This one 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 own configuration directory. Never pass untrusted text as a shell fragment after -x. Keep the command itself fixed, and pass any variable data as quoted arguments where you can.

6. Change status deliberately

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

$ 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 actual service state separately before maintenance, and never assume a disabled instance has no queued messages or running processes.