ALIASES(5) File Formats Manual ALIASES(5)
NAME
aliases - Postfix local alias database format
SYNOPSIS
newaliases
postalias -q name [file-type]:[file-name]
DESCRIPTION
The optional aliases(5) table (alias_maps) redirects mail for local re-
cipients. The redirections are processed by the Postfix local(8) deliv-
ery agent. This table is always searched with an email address localpart
(no domain portion).
This is unlike virtual(5) aliasing (virtual_alias_maps) which applies to
all recipients: local(8), virtual, and remote, and which is implemented
by the cleanup(8) daemon. That table is often searched with a full email
address (including domain).
Normally, the aliases(5) table is specified as a text file that serves
as input to the postalias(1) command. The result, an indexed file in dbm
or db format, is used for fast lookup by the mail system. Execute the
command newaliases in order to rebuild the indexed file after changing
the Postfix alias database.
When the table is provided via other means such as NIS, LDAP or SQL, the
same lookups are done as for ordinary indexed files.
Alternatively, the table can be provided as a regular-expression map
where patterns are given as regular expressions. In this case, the
lookups are done in a slightly different way as described below under
"REGULAR EXPRESSION TABLES".
Users can control delivery of their own mail by setting up .forward
files in their home directory. Lines in per-user .forward files have
the same syntax as the right-hand side of aliases(5) entries.
The format of the alias database input file is as follows:
• An alias definition has the form
name: value1, value2, ...
• Empty lines and whitespace-only lines are ignored, as are lines
whose first non-whitespace character is a `#'.
• A logical line starts with non-whitespace text. A line that
starts with whitespace continues a logical line.
The name is a local address (no domain part). Use double quotes when
the name contains any special characters such as whitespace, `#', `:',
or `@'. The name is folded to lowercase, in order to make database
lookups case insensitive.
In addition, when an alias exists for owner-name, this will override the
envelope sender address, so that delivery diagnostics are directed to
owner-name, instead of the originator of the message (for details, see
owner_request_special, expand_owner_alias and reset_owner_alias). This
is typically used to direct delivery errors to the maintainer of a mail-
ing list, who is in a better position to deal with mailing list delivery
problems than the originator of the undelivered mail.
The value contains one or more of the following:
address
Mail is forwarded to address, which is compatible with the RFC
822 standard.
/file/name
Mail is appended to /file/name. For details on how a file is
written see the sections "EXTERNAL FILE DELIVERY" and "DELIVERY
RIGHTS" in the local(8) documentation. Delivery is not limited
to regular files. For example, to dispose of unwanted mail, de-
flect it to /dev/null.
|command
Mail is piped into command. Commands that contain special charac-
ters, such as whitespace, should be enclosed between double
quotes. For details on how a command is executed see "EXTERNAL
COMMAND DELIVERY" and "DELIVERY RIGHTS" in the local(8) documen-
tation.
When the command fails, a limited amount of command output is
mailed back to the sender. The file /usr/include/sysexits.h de-
fines the expected exit status codes. For example, use "|exit 67"
to simulate a "user unknown" error, and "|exit 0" to implement an
expensive black hole.
:include:/file/name
Mail is sent to the destinations listed in the named file. Lines
in :include: files have the same syntax as the right-hand side of
aliases(5) entries.
A destination can be any destination that is described in this
manual page. However, delivery to "|command" and /file/name is
disallowed by default. To enable, edit the allow_mail_to_commands
and allow_mail_to_files configuration parameters.
ADDRESS EXTENSION
When alias database search fails, and the recipient localpart contains
the optional recipient delimiter (e.g., user+foo), the search is re-
peated for the unextended address (e.g., user).
The propagate_unmatched_extensions parameter controls whether an un-
matched address extension (+foo) is propagated to the result of table
lookup.
CASE FOLDING
The local(8) delivery agent always folds the search string to lowercase
before database lookup.
REGULAR EXPRESSION TABLES
This section describes how the table lookups change when the table is
given in the form of regular expressions. For a description of regular
expression lookup table syntax, see regexp_table(5) or pcre_table(5).
NOTE: these formats do not use ":" at the end of a pattern.
Each regular expression is applied to the entire search string. Thus, a
search string user+foo is not broken up into user and foo.
Regular expressions are applied in the order as specified in the table,
until a regular expression is found that matches the search string.
Lookup results are the same as with indexed file lookups. For security
reasons there is no support for $1, $2 etc. substring interpolation.
SECURITY
The local(8) delivery agent disallows regular expression substitution of
$1 etc. in alias_maps, because that would open a security hole.
The local(8) delivery agent will silently ignore requests to use the
proxymap(8) server within alias_maps. Instead it will open the table di-
rectly. Before Postfix version 2.2, the local(8) delivery agent will
terminate with a fatal error.
CONFIGURATION PARAMETERS
The following main.cf parameters are especially relevant. The text be-
low provides only a parameter summary. See postconf(5) for more details
including examples.
alias_database (see 'postconf -d' output)
The alias databases for local(8) delivery that are updated with
"newaliases" or with "sendmail -bi".
alias_maps (see 'postconf -d' output)
Optional lookup tables that are searched only with an email ad-
dress localpart (no domain) and that apply only to local(8) re-
cipients; this is unlike virtual_alias_maps that are often
searched with a full email address (including domain) and that
apply to all recipients: local(8), virtual, and remote.
allow_mail_to_commands (alias, forward)
Restrict local(8) mail delivery to external commands.
allow_mail_to_files (alias, forward)
Restrict local(8) mail delivery to external files.
expand_owner_alias (no)
When delivering to an alias "aliasname" that has an "owner-alias-
name" companion alias, set the envelope sender address to the ex-
pansion of the "owner-aliasname" alias.
propagate_unmatched_extensions (canonical, virtual)
What address lookup tables copy an address extension from the
lookup key to the lookup result.
owner_request_special (yes)
Enable special treatment for owner-listname entries in the
aliases(5) file, and don't split owner-listname and listname-re-
quest address localparts when the recipient_delimiter is set to
"-".
recipient_delimiter (empty)
The set of characters that can separate an email address local-
part, user name, or a .forward file name from its extension.
Available in Postfix version 2.3 and later:
frozen_delivered_to (yes)
Update the local(8) delivery agent's idea of the Delivered-To:
address (see prepend_delivered_header) only once, at the start of
a delivery attempt; do not update the Delivered-To: address while
expanding aliases or .forward files.
STANDARDS
RFC 822 (ARPA Internet Text Messages)
SEE ALSO
local(8), local delivery agent
newaliases(1), create/update alias database
postalias(1), create/update alias database
postconf(5), configuration parameters
README FILES
Use "postconf readme_directory" or "postconf html_directory" to locate
this information.
DATABASE_README, Postfix lookup table overview
LICENSE
The Secure Mailer license must be distributed with this software.
AUTHOR(S)
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
ALIASES(5)
Generated by dwww version 1.16 on Tue Dec 16 04:30:29 CET 2025.