Maintain Postfix Alias Databases with postalias

You will turn a Sendmail-format aliases file into the indexed database that Postfix local delivery reads, query it without sending mail, and update or remove entries with a recovery path. The examples were checked with Postfix 3.8.6, installed as package version 3.8.6-1ubuntu0.1.

Allow about fifteen minutes. You need shell access, the postfix package, and permission to read the aliases source. Rebuilding the system map normally requires elevated privileges because the source is commonly /etc/aliases. This guide changes no service configuration and sends no mail.

1. Check the active map and database type

First ask Postfix which aliases file and map type it uses. These are ordinary, read-only commands:

$ postconf -h alias_maps alias_database default_database_type
hash:/etc/aliases
hash:/etc/aliases
hash

Your output may name a different path or type. The first two lines are the important contract: alias_maps is what local delivery looks up, while alias_database is the map maintained by newaliases and related commands. Do not build /etc/aliases.db merely because that is a familiar name. Use the path reported on your host.

Checkpoint: list the database drivers that this installation can use:

$ postconf -m
hash
btree
...

The exact list varies. A type can be queried if it is supported, but postalias can create only the types listed in its manual, including hash, btree, lmdb, cdb, dbm and sdbm where the relevant support is installed.

2. Inspect the source before rebuilding

Read the text file before making its indexed companion. An alias line has a local name, a colon and one or more destinations, for example:

$ sudo sed -n '1,80p' /etc/aliases
postmaster: root
alerts: [email protected]

Use sudo only if your account cannot read the file. Do not put a password, API token or private mailbox address into a guide or a shell history just to test the syntax. Keep the source as the authoritative copy. The database is a generated index, not the place to edit an alias by hand.

Before changing a live file, make a backup and keep it until both the rebuild and a lookup work:

$ sudo cp --preserve=all /etc/aliases /etc/aliases.before-postalias
$ sudo cp --preserve=all /etc/aliases.db /etc/aliases.db.before-postalias

The second command is appropriate for this host's hash map. If your configured type creates .cdb, .lmdb, .pag or .dir files, back up the files that type actually produces. Do not run a blind wildcard copy in a directory containing unrelated Postfix maps.

3. Build the indexed database

After editing the source with your normal editor, rebuild it using the configured default type:

$ sudo postalias /etc/aliases

A successful run normally prints nothing and returns status zero. The command creates the result if it is absent and uses the source file's group and other read permissions. With the local configuration above, the result is /etc/aliases.db.

Checkpoint: verify the file exists and ask postalias for a known key. This performs a lookup only:

$ sudo test -s /etc/aliases.db && echo 'database exists'
database exists
$ postalias -q alerts /etc/aliases
[email protected]

The -q operation writes the first value found. A successful lookup has exit status zero. A missing key produces no value and returns non-zero, so test the status explicitly in a script rather than treating empty output as success.

4. Query keys without affecting mail

Use one exact key with -q when checking a deployment:

$ postalias -q postmaster /etc/aliases
root

Postfix folds lookup keys to lower case by default for fixed-case map types such as hash and btree. Add -f when you deliberately need the key's case preserved while creating or querying a table. It does not control case handling in regular-expression tables.

To query several keys, pass a key of - and provide one key per input line:

$ printf '%s\n' postmaster alerts missing | postalias -q - /etc/aliases
postmaster: root
alerts: [email protected]

The output contains only keys found. The command still returns zero when at least one requested key was found, which is useful for a smoke test but not proof that every expected alias exists.

5. Add entries incrementally

Normal mode recreates a table from the source file and can replace an existing database. Use -i only when you intentionally want to read additional entries from standard input without truncating the existing database:

$ printf '%s\n' 'oncall: [email protected]' | sudo postalias -i /etc/aliases

Incremental mode does not update the text source. The next full rebuild from /etc/aliases can therefore remove the temporary entry. For a durable change, add the line to the source, inspect it, then run the ordinary rebuild in step 3.

Duplicate keys are skipped and reported as warnings. The default protects the first value. -r allows later entries to replace existing entries, while -w ignores attempts to replace them without complaining. Treat both as deliberate policy choices, not routine fixes.

6. Remove an entry carefully

-d removes one entry per map from the indexed database. This is a destructive change to generated state, so back it up first and remember that it does not edit the source file:

$ sudo cp --preserve=all /etc/aliases.db /etc/aliases.db.before-delete
$ sudo postalias -d alerts /etc/aliases
$ postalias -q alerts /etc/aliases
$ printf 'lookup exit status: %s\n' "$?"
lookup exit status: 1

If the lookup should still succeed, restore the database backup and rebuild from the source instead:

$ sudo cp --preserve=all /etc/aliases.db.before-delete /etc/aliases.db
$ postalias -q alerts /etc/aliases
[email protected]

For a permanent removal, delete the line from /etc/aliases with an editor, then rebuild. Do not use -d as a substitute for editing the source.

7. Diagnose a failed rebuild

Non-zero status means the operation failed. Check the source path, permissions and map type before changing Postfix configuration:

$ test -r /etc/aliases && echo readable
$ ls -l /etc/aliases /etc/aliases.db
$ postconf -m | grep '^hash$'
hash

Duplicate warnings are not the same as a successful intended update. Read standard error and inspect the resulting lookup. If the source is edited while a busy service is reading the map, Postfix's local database locking is designed to avoid readers seeing a partial update, but you should still validate the intended aliases before relying on them.

Do not use -p casually: it stops the new file inheriting source permissions and uses default mode 0644. Do not use -o casually either: it keeps root privileges when processing a non-root input file. The normal privilege drop is safer for an ordinary source. -v is for diagnostics and may increase logging when repeated.