Configure Postfix Multi-Instance Control Safely

You will configure the control path for a Postfix multi-instance setup, identify one instance without starting it, and understand when postfix acts on every instance or only one. Allow about 20 minutes for configuration review. Starting or stopping mail services needs root access and can interrupt delivery, so this guide keeps the operational examples deliberately cautious.

The examples match Postfix 3.8.6-1ubuntu0.1 from the installed Ubuntu package. The local postfix-wrapper(5) page describes the API and the simple wrapper shipped with Postfix. It is not a complete recipe for inventing a mail topology: each instance still needs valid, separate configuration, queue and data directories.

1. Confirm the installed defaults

First inspect the command and the compiled defaults. These are read-only checks and normally need no elevated privileges, although a restricted installation may require an administrator account:

$ command -v postfix
/usr/sbin/postfix
$ postconf -h config_directory
/etc/postfix
$ postconf -h daemon_directory
/usr/lib/postfix/sbin

Your paths may differ. The default Postfix instance is mandatory. Its config_directory is the anchor from which the multi-instance manager finds the additional instances.

Checkpoint: do not continue until you know which main.cf is the default one and have a backup or version-controlled copy of any configuration you will edit.

2. Understand the two control modes

With an empty multi_instance_directories, postfix remains in ordinary single-instance mode. When that parameter contains one or more configuration directories, Postfix invokes the command named by multi_instance_wrapper. The wrapper then runs the requested operation for the instances.

The shipped simple wrapper is usually installed below the daemon directory. Check the exact path instead of assuming it:

$ postconf -h daemon_directory
/usr/lib/postfix/sbin
$ test -x "$(postconf -h daemon_directory)/postfix-wrapper" && echo wrapper-found
wrapper-found

A successful test prints the checkpoint text. If it prints nothing, stop and investigate the package installation. Do not point multi_instance_wrapper at a guessed path.

3. Set the primary instance's manager parameters

Editing /etc/postfix/main.cf is a service configuration change and requires root. The following values show the shape of a small setup with one additional instance. Replace /etc/postfix-test with a real configuration directory that has its own compatible main.cf and master.cf:

# postconf -e 'multi_instance_wrapper = $daemon_directory/postfix-wrapper'
# postconf -e 'multi_instance_directories = /etc/postfix-test'
# postconf -h multi_instance_wrapper
$daemon_directory/postfix-wrapper
# postconf -h multi_instance_directories
/etc/postfix-test

The parameter value is a comma-separated list in Postfix configuration, although the command-line display can vary with the number of entries. Add directories only after checking their ownership, permissions and queue paths. Never put an arbitrary directory in this list: it becomes a candidate for administrator-controlled mail operations.

To undo this specific change, remove the parameters from the primary main.cf or set the directory list back to its previous value, then run postfix check as root before any service restart. Keep the backup until the single-instance behaviour has been confirmed.

4. Keep new instances disabled while testing

Every instance has its own main.cf. The safety default for multi_instance_enable is no. Leave it at that value while checking paths and permissions:

$ postconf -c /etc/postfix-test -h multi_instance_enable
no
$ postconf -c /etc/postfix-test -h config_directory
/etc/postfix-test

A disabled instance can be managed directly with postfix -c, but the multi-instance manager will not start or stop it as a running member. For a manager start, the documented behaviour is to run check for a disabled instance so configuration problems can still be reported. Commands that require a running service, such as stop, flush or reload, are skipped for disabled instances.

Checkpoint: run a configuration check for the default instance first, then the test instance. These commands can inspect configuration without starting Postfix, but use root if the installation's permissions require it:

# postfix check
# postfix -c /etc/postfix-test check

Fix every reported path, permission or syntax error before enabling anything. The default instance owns shared executables and documentation, so it should be checked and updated before dependent instances.

5. Inspect all instances without starting them

Once the primary configuration lists the secondary directory, ask Postfix for status. This is a privileged control command on the installed system:

# postfix status

The output is host-specific. The useful result is an enumeration of the configured instances and their states, not a particular line of text. An empty or unexpected list means the wrapper or directory list is not doing what you expect. Do not compensate by repeatedly running start.

To operate on one instance only, give its configuration directory with -c:

# postfix -c /etc/postfix-test check

The -c option takes precedence over the MAIL_CONFIG environment variable. Postfix exports MAIL_CONFIG to child processes so nested commands stay with the selected instance. This single-instance path is also how the wrapper avoids recursively invoking the multi-instance manager.

6. Enable and start only after the checks pass

Enabling an instance changes service behaviour. Confirm its queue and data directories, ports, identities and delivery routes before doing it. The following command is the explicit point of no return for automatic multi-instance control:

# postconf -c /etc/postfix-test -e 'multi_instance_enable = yes'
# postfix check
# postfix -c /etc/postfix-test check

Only after both checks succeed should you consider a start. Starting the default command can affect every enabled instance:

# postfix start
# postfix status

For a first run, start the selected instance instead:

# postfix -c /etc/postfix-test start
# postfix -c /etc/postfix-test status

If the new instance must be taken back out of manager control, stop it explicitly, set multi_instance_enable = no, and verify its status. Keep the primary directory list unchanged only if you still want it available for manual tests.