Operate Postfix Safely and Test a Socketmap Lookup

By the end of this guide you will be able to inspect the installed Postfix service, check its configuration, reload it after a change, and query a socketmap table without sending mail. The examples match Postfix 3.8.6, the version installed on the reference machine.

Allow about 10 minutes if Postfix is already configured. You need a shell account with sudo access for service control, and you should know the configuration directory used by the instance. The postfix command is for the superuser. A lookup with postmap -q is a separate operation and normally does not need root access if the socket permits your user to connect.

1. Confirm the version and current state

Start with read-only checks. The package query identifies the distribution package, while postconf reports the Postfix version compiled into the executable.

dpkg-query -W -f='${Package} ${Version}\n' postfix
postconf -h mail_version
sudo postfix status
printf 'postfix status exit code: %s\n' "$?"

On the reference system the first two commands report package version 3.8.6-1ubuntu0.1 and mail version 3.8.6. The status command prints no useful text on a healthy installation; its exit status is zero when Postfix is running and non-zero when it is stopped. Do not mistake a non-zero status for a configuration diagnosis. Run the check in the next step.

2. Check the configuration and permissions

Run postfix check before starting or reloading the service. It warns about ownership and permissions, and creates missing Postfix directories. That directory creation is a state change, so run it with care on a machine where the configuration path is managed by another system.

sudo postfix check

A successful run usually returns to the prompt without a summary. Warnings identify the path or permission that needs attention. Inspect the effective paths when a warning is surprising:

postconf -h config_directory
postconf -h queue_directory
postconf -h daemon_directory
postconf -h meta_directory

The main configuration normally lives in main.cf and the daemon service definitions in master.cf. Postfix 3.x can share executable and metadata directories between instances, so avoid assuming every file is below the configuration directory.

3. Apply a configuration change with reload

Edit the relevant configuration using your normal change-control process, then reload the running service. Reload tells Postfix to re-read its configuration and lets running processes terminate at their earliest convenience.

sudo postfix check
sudo postfix reload
sudo postfix status

The final command should have a zero exit status. If the check fails, fix the reported file or permission and run it again before reloading. If the reload itself fails, examine the mail log and the service manager status for the host.

Do not use a stop followed by a start merely to apply a configuration change. The manual specifically recommends reload for this case. If you need to undo a configuration edit, restore the previous version from your change-control copy, run sudo postfix check, and reload again.

4. Use the service controls deliberately

These commands affect mail service availability. Check the target host and instance before running them.

The command also supports start-fg for foreground operation, but it is intended for a specific deployment arrangement and requires multi-instance support to be disabled. Do not use it as a casual replacement for a service manager.

5. Select another Postfix instance

Use -c when the instance has a different configuration directory. The directory must contain the relevant Postfix configuration files.

sudo postfix -c /etc/postfix-secondary check
sudo postfix -c /etc/postfix-secondary status

On Postfix 2.6 and later, -c restricts the command and descendant commands to that instance. This matters on a host with multi-instance configuration: leaving out the option can operate on the default instance instead.

For temporary diagnostics, add -v for verbose logging. The -D option is only for postfix start and runs daemons under the configured debugger, so do not add it to normal service commands.

6. Query a socketmap without delivering mail

A socketmap is a read-only Postfix table client. It can support address rewriting, mail routing or policy lookup through a separate service. It is not the same as the Postfix queue and a query does not submit a message.

For a TCP socketmap, the table name is socketmap:inet:host:port:name. For a UNIX-domain socket, use socketmap:unix:pathname:name. The final name is sent as the socketmap name in the request.

postmap -q '[email protected]' \
  'socketmap:inet:127.0.0.1:9999:aliases'

postmap -q '[email protected]' \
  'socketmap:unix:/run/example-socketmap.sock:aliases'

For a batch, pass a hyphen as the query and redirect a file. Each input line becomes a lookup request.

postmap -q - \
  'socketmap:unix:/run/example-socketmap.sock:aliases' \
  < ./addresses-to-check.txt

A successful service returns a value after OK . A missing key is represented by NOTFOUND . TEMP, TIMEOUT and PERM indicate a failed request with an optional reason. The protocol sends one netstring request and receives one netstring reply, so a server that speaks plain unframed text will not work.

Postfix does not manufacture partial search keys for socketmaps. For example, it will not keep shortening an address into a bare domain or an email address without its localpart. Build the exact lookup keys your service expects and test them individually.

7. Keep socketmaps outside the trust boundary

The socketmap connection and server are unauthenticated. Do not use this table for passwords, authorisation decisions or other security-sensitive information. A TCP socket should be restricted to the required interface and firewall scope, and a UNIX socket should have deliberate ownership and permissions. If the lookup result affects who may relay mail, use an authenticated and integrity-protected design instead.

The installed Postfix 3.8.6 manual documents a maximum socketmap reply of 100000 characters. Later upstream manuals add configurable query and reply limits, but those settings are not present in the local manpage and should not be assumed on this host. Keep replies small and test against the version you deploy.