Global Postfix configuration file. This file lists only a subset
of all parameters. For the syntax, and for a complete parameter
list, see the postconf(5) manual page (command: âman 5 postconfâ).
For common configuration examples, see BASIC_CONFIGURATION_README
and STANDARD_CONFIGURATION_README. To find these documents, use
the command âpostconf html_directory readme_directoryâ, or go to
For best results, change no more than 2-3 parameters at a time,
and test if Postfix still works after every change.
SOFT BOUNCE
The soft_bounce parameter provides a limited safety net for
testing. When soft_bounce is enabled, mail will remain queued that
would otherwise bounce. This parameter disables locally-generated
bounces, and prevents the SMTP server from rejecting mail permanently
(by changing 5xx replies into 4xx replies). However, soft_bounce
is no cure for address rewriting mistakes or mail routing mistakes.
#soft_bounce = no
LOCAL PATHNAME INFORMATION
The queue_directory specifies the location of the Postfix queue.
This is also the root directory of Postfix daemons that run chrooted.
See the files in examples/chroot-setup for setting up Postfix chroot
environments on different UNIX systems.
queue_directory = /var/spool/postfix
The command_directory parameter specifies the location of all
postXXX commands.
command_directory = /usr/sbin
The daemon_directory parameter specifies the location of all Postfix
daemon programs (i.e. programs listed in the master.cf file). This
directory must be owned by root.
daemon_directory = /usr/libexec/postfix
The data_directory parameter specifies the location of Postfix-writable
data files (caches, random numbers). This directory must be owned
by the mail_owner account (see below).
data_directory = /var/lib/postfix
QUEUE AND PROCESS OWNERSHIP
The mail_owner parameter specifies the owner of the Postfix queue
and of most Postfix daemon processes. Specify the name of a user
account THAT DOES NOT SHARE ITS USER OR GROUP ID WITH OTHER ACCOUNTS
AND THAT OWNS NO OTHER FILES OR PROCESSES ON THE SYSTEM. In
particular, donât specify nobody or daemon. PLEASE USE A DEDICATED
USER.
mail_owner = postfix
The default_privs parameter specifies the default rights used by
the local delivery agent for delivery to external file or command.
These rights are used in the absence of a recipient user context.
DO NOT SPECIFY A PRIVILEGED USER OR THE POSTFIX OWNER.
#default_privs = nobody
INTERNET HOST AND DOMAIN NAMES
The myhostname parameter specifies the internet hostname of this
mail system. The default is to use the fully-qualified domain name
from gethostname(). $myhostname is used as a default value for many
other configuration parameters.
#myhostname = host.domain.tld
#myhostname = virtual.domain.tld
The mydomain parameter specifies the local internet domain name.
The default is to use $myhostname minus the first component.
$mydomain is used as a default value for many other configuration
parameters.
#mydomain = domain.tld
SENDING MAIL
The myorigin parameter specifies the domain that locally-posted
mail appears to come from. The default is to append $myhostname,
which is fine for small sites. If you run a domain with multiple
machines, you should (1) change this to $mydomain and (2) set up
a domain-wide alias database that aliases each user to
user@that.users.mailhost.
For the sake of consistency between sender and recipient addresses,
myorigin also specifies the default domain name that is appended
to recipient addresses that have no @domain part.
#myorigin = $myhostname
#myorigin = $mydomain
RECEIVING MAIL
The inet_interfaces parameter specifies the network interface
addresses that this mail system receives mail on. By default,
the software claims all active interfaces on the machine. The
parameter also controls delivery of mail to user@[ip.address].
See also the proxy_interfaces parameter, for network addresses that
are forwarded to us via a proxy or network address translator.
Note: you need to stop/start Postfix when this parameter changes.
#inet_interfaces = all
#inet_interfaces = $myhostname
#inet_interfaces = $myhostname, localhost
inet_interfaces = localhost
Enable IPv4, and IPv6 if supported
inet_protocols = all
The proxy_interfaces parameter specifies the network interface
addresses that this mail system receives mail on by way of a
proxy or network address translation unit. This setting extends
the address list specified with the inet_interfaces parameter.
You must specify your proxy/NAT addresses when your system is a
backup MX host for other domains, otherwise mail delivery loops
will happen when the primary MX host is down.
#proxy_interfaces =
#proxy_interfaces = 1.2.3.4
The mydestination parameter specifies the list of domains that this
machine considers itself the final destination for.
These domains are routed to the delivery agent specified with the
local_transport parameter setting. By default, that is the UNIX
compatible delivery agent that lookups all recipients in /etc/passwd
and /etc/aliases or their equivalent.
The default is $myhostname + localhost.$mydomain. On a mail domain
gateway, you should also include $mydomain.
Do not specify the names of virtual domains - those domains are
specified elsewhere (see VIRTUAL_README).
Do not specify the names of domains that this machine is backup MX
host for. Specify those names via the relay_domains settings for
the SMTP server, or use permit_mx_backup if you are lazy (see
STANDARD_CONFIGURATION_README).
The local machine is always the final destination for mail addressed
to user@[the.net.work.address] of an interface that the mail system
receives mail on (see the inet_interfaces parameter).
Specify a list of host or domain names, /file/name or type:table
patterns, separated by commas and/or whitespace. A /file/name
pattern is replaced by its contents; a type:table is matched when
a name matches a lookup key (the right-hand side is ignored).
Continue long lines by starting the next line with whitespace.
See also below, section âREJECTING MAIL FOR UNKNOWN LOCAL USERSâ.
mydestination = $myhostname, localhost.$mydomain, localhost
#mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain
#mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain,
mail.$mydomain, www.$mydomain, ftp.$mydomain
REJECTING MAIL FOR UNKNOWN LOCAL USERS
The local_recipient_maps parameter specifies optional lookup tables
with all names or addresses of users that are local with respect
to $mydestination, $inet_interfaces or $proxy_interfaces.
If this parameter is defined, then the SMTP server will reject
mail for unknown local users. This parameter is defined by default.
To turn off local recipient checking in the SMTP server, specify
local_recipient_maps = (i.e. empty).
The default setting assumes that you use the default Postfix local
delivery agent for local delivery. You need to update the
local_recipient_maps setting if:
- You define $mydestination domain recipients in files other than
/etc/passwd, /etc/aliases, or the $virtual_alias_maps files.
For example, you define $mydestination domain recipients in
the $virtual_mailbox_maps files.
- You redefine the local delivery agent in master.cf.
- You redefine the âlocal_transportâ setting in main.cf.
- You use the âluser_relayâ, âmailbox_transportâ, or âfallback_transportâ
feature of the Postfix local delivery agent (see local(8)).
Details are described in the LOCAL_RECIPIENT_README file.
Beware: if the Postfix SMTP server runs chrooted, you probably have
to access the passwd file via the proxymap service, in order to
overcome chroot restrictions. The alternative, having a copy of
the system passwd file in the chroot jail is just not practical.
The right-hand side of the lookup tables is conveniently ignored.
In the left-hand side, specify a bare username, an @domain.tld
wild-card, or specify a user@domain.tld address.
#local_recipient_maps = unix:passwd.byname $alias_maps
#local_recipient_maps = proxy:unix:passwd.byname $alias_maps
#local_recipient_maps =
The unknown_local_recipient_reject_code specifies the SMTP server
response code when a recipient domain matches $mydestination or
${proxy,inet}_interfaces, while $local_recipient_maps is non-empty
and the recipient address or address local-part is not found.
The default setting is 550 (reject mail) but it is safer to start
with 450 (try again later) until you are certain that your
local_recipient_maps settings are OK.
unknown_local_recipient_reject_code = 550
TRUST AND RELAY CONTROL
The mynetworks parameter specifies the list of âtrustedâ SMTP
clients that have more privileges than âstrangersâ.
In particular, âtrustedâ SMTP clients are allowed to relay mail
through Postfix. See the smtpd_recipient_restrictions parameter
in postconf(5).
You can specify the list of âtrustedâ network addresses by hand
or you can let Postfix do it for you (which is the default).
By default (mynetworks_style = subnet), Postfix âtrustsâ SMTP
clients in the same IP subnetworks as the local machine.
On Linux, this does works correctly only with interfaces specified
with the âifconfigâ command.
Specify âmynetworks_style = classâ when Postfix should âtrustâ SMTP
clients in the same IP class A/B/C networks as the local machine.
Donât do this with a dialup site - it would cause Postfix to âtrustâ
your entire providerâs network. Instead, specify an explicit
mynetworks list by hand, as described below.
Specify âmynetworks_style = hostâ when Postfix should âtrustâ
only the local machine.
#mynetworks_style = class
#mynetworks_style = subnet
#mynetworks_style = host
Alternatively, you can specify the mynetworks list by hand, in
which case Postfix ignores the mynetworks_style setting.
Specify an explicit list of network/netmask patterns, where the
mask specifies the number of bits in the network part of a host
address.
You can also specify the absolute pathname of a pattern file instead
of listing the patterns here. Specify type:table for table-based lookups
(the value on the table right-hand side is not used).
#mynetworks = 168.100.189.0/28, 127.0.0.0/8
#mynetworks = $config_directory/mynetworks
#mynetworks = hash:/etc/postfix/network_table
The relay_domains parameter restricts what destinations this system will
relay mail to. See the smtpd_recipient_restrictions description in
postconf(5) for detailed information.
By default, Postfix relays mail
- from âtrustedâ clients (IP address matches $mynetworks) to any destination,
- from âuntrustedâ clients to destinations that match $relay_domains or
subdomains thereof, except addresses with sender-specified routing.
The default relay_domains value is $mydestination.
In addition to the above, the Postfix SMTP server by default accepts mail
that Postfix is final destination for:
- destinations that match $inet_interfaces or $proxy_interfaces,
- destinations that match $mydestination
- destinations that match $virtual_alias_domains,
- destinations that match $virtual_mailbox_domains.
These destinations do not need to be listed in $relay_domains.
Specify a list of hosts or domains, /file/name patterns or type:name
lookup tables, separated by commas and/or whitespace. Continue
long lines by starting the next line with whitespace. A file name
is replaced by its contents; a type:name table is matched when a
(parent) domain appears as lookup key.
NOTE: Postfix will not automatically forward mail for domains that
list this system as their primary or backup MX host. See the
permit_mx_backup restriction description in postconf(5).
#relay_domains = $mydestination
INTERNET OR INTRANET
The relayhost parameter specifies the default host to send mail to
when no entry is matched in the optional transport(5) table. When
no relayhost is given, mail is routed directly to the destination.
On an intranet, specify the organizational domain name. If your
internal DNS uses no MX records, specify the name of the intranet
gateway host instead.
In the case of SMTP, specify a domain, host, host:port, [host]:port,
[address] or [address]:port; the form [host] turns off MX lookups.
If youâre connected via UUCP, see also the default_transport parameter.
#relayhost = $mydomain
#relayhost = [gateway.my.domain]
#relayhost = [mailserver.isp.tld]
#relayhost = uucphost
#relayhost = [an.ip.add.ress]
REJECTING UNKNOWN RELAY USERS
The relay_recipient_maps parameter specifies optional lookup tables
with all addresses in the domains that match $relay_domains.
If this parameter is defined, then the SMTP server will reject
mail for unknown relay users. This feature is off by default.
The right-hand side of the lookup tables is conveniently ignored.
In the left-hand side, specify an @domain.tld wild-card, or specify
a user@domain.tld address.
#relay_recipient_maps = hash:/etc/postfix/relay_recipients
INPUT RATE CONTROL
The in_flow_delay configuration parameter implements mail input
flow control. This feature is turned on by default, although it
still needs further development (itâs disabled on SCO UNIX due
to an SCO bug).
A Postfix process will pause for $in_flow_delay seconds before
accepting a new message, when the message arrival rate exceeds the
message delivery rate. With the default 100 SMTP server process
limit, this limits the mail inflow to 100 messages a second more
than the number of messages delivered per second.
Specify 0 to disable the feature. Valid delays are 0âŚ10.
#in_flow_delay = 1s
ADDRESS REWRITING
The ADDRESS_REWRITING_README document gives information about
address masquerading or other forms of address rewriting including
username->Firstname.Lastname mapping.
ADDRESS REDIRECTION (VIRTUAL DOMAIN)
The VIRTUAL_README document gives information about the many forms
of domain hosting that Postfix supports.
âUSER HAS MOVEDâ BOUNCE MESSAGES
See the discussion in the ADDRESS_REWRITING_README document.
TRANSPORT MAP
See the discussion in the ADDRESS_REWRITING_README document.
ALIAS DATABASE
The alias_maps parameter specifies the list of alias databases used
by the local delivery agent. The default list is system dependent.
On systems with NIS, the default is to search the local alias
database, then the NIS alias database. See aliases(5) for syntax
details.
If you change the alias database, run âpostalias /etc/aliasesâ (or
wherever your system stores the mail alias file), or simply run
ânewaliasesâ to build the necessary DBM or DB file.
It will take a minute or so before changes become visible. Use
âpostfix reloadâ to eliminate the delay.
#alias_maps = dbm:/etc/aliases
alias_maps = hash:/etc/aliases
#alias_maps = hash:/etc/aliases, nis:mail.aliases
#alias_maps = netinfo:/aliases
The alias_database parameter specifies the alias database(s) that
are built with ânewaliasesâ or âsendmail -biâ. This is a separate
configuration parameter, because alias_maps (see above) may specify
tables that are not necessarily all under control by Postfix.
#alias_database = dbm:/etc/aliases
#alias_database = dbm:/etc/mail/aliases
alias_database = hash:/etc/aliases
#alias_database = hash:/etc/aliases, hash:/opt/majordomo/aliases
ADDRESS EXTENSIONS (e.g., user+foo)
The recipient_delimiter parameter specifies the separator between
user names and address extensions (user+foo). See canonical(5),
local(8), relocated(5) and virtual(5) for the effects this has on
aliases, canonical, virtual, relocated and .forward file lookups.
Basically, the software tries user+foo and .forward+foo before
trying user and .forward.
#recipient_delimiter = +
DELIVERY TO MAILBOX
The home_mailbox parameter specifies the optional pathname of a
mailbox file relative to a userâs home directory. The default
mailbox file is /var/spool/mail/user or /var/mail/user. Specify
âMaildir/â for qmail-style delivery (the / is required).
#home_mailbox = Mailbox
#home_mailbox = Maildir/
The mail_spool_directory parameter specifies the directory where
UNIX-style mailboxes are kept. The default setting depends on the
system type.
#mail_spool_directory = /var/mail
#mail_spool_directory = /var/spool/mail
The mailbox_command parameter specifies the optional external
command to use instead of mailbox delivery. The command is run as
the recipient with proper HOME, SHELL and LOGNAME environment settings.
Exception: delivery for root is done as $default_user.
Other environment variables of interest: USER (recipient username),
EXTENSION (address extension), DOMAIN (domain part of address),
and LOCAL (the address localpart).
Unlike other Postfix configuration parameters, the mailbox_command
parameter is not subjected to $parameter substitutions. This is to
make it easier to specify shell syntax (see example below).
Avoid shell meta characters because they will force Postfix to run
an expensive shell process. Procmail alone is expensive enough.
IF YOU USE THIS TO DELIVER MAIL SYSTEM-WIDE, YOU MUST SET UP AN
ALIAS THAT FORWARDS MAIL FOR ROOT TO A REAL USER.
#mailbox_command = /some/where/procmail
#mailbox_command = /some/where/procmail -a â$EXTENSIONâ
The mailbox_transport specifies the optional transport in master.cf
to use after processing aliases and .forward files. This parameter
has precedence over the mailbox_command, fallback_transport and
luser_relay parameters.
Specify a string of the form transport:nexthop, where transport is
the name of a mail delivery transport defined in master.cf. The
:nexthop part is optional. For more details see the sample transport
configuration file.
NOTE: if you use this feature for accounts not in the UNIX password
file, then you must update the âlocal_recipient_mapsâ setting in
the main.cf file, otherwise the SMTP server will reject mail for
non-UNIX accounts with âUser unknown in local recipient tableâ.
Cyrus IMAP over LMTP. Specify ``lmtpunix cmd=âlmtpdâ
listen=â/var/imap/socket/lmtpâ prefork=0ââ in cyrus.conf.
#mailbox_transport = lmtp:unix:/var/lib/imap/socket/lmtp
If using the cyrus-imapd IMAP server deliver local mail to the IMAP
server using LMTP (Local Mail Transport Protocol), this is prefered
over the older cyrus deliver program by setting the
mailbox_transport as below:
mailbox_transport = lmtp:unix:/var/lib/imap/socket/lmtp
The efficiency of LMTP delivery for cyrus-imapd can be enhanced via
these settings.
local_destination_recipient_limit = 300
local_destination_concurrency_limit = 5
Of course you should adjust these settings as appropriate for the
capacity of the hardware you are using. The recipient limit setting
can be used to take advantage of the single instance message store
capability of Cyrus. The concurrency limit can be used to control
how many simultaneous LMTP sessions will be permitted to the Cyrus
message store.
Cyrus IMAP via command line. Uncomment the âcyrusâŚpipeâ and
subsequent line in master.cf.
#mailbox_transport = cyrus
The fallback_transport specifies the optional transport in master.cf
to use for recipients that are not found in the UNIX passwd database.
This parameter has precedence over the luser_relay parameter.
Specify a string of the form transport:nexthop, where transport is
the name of a mail delivery transport defined in master.cf. The
:nexthop part is optional. For more details see the sample transport
configuration file.
NOTE: if you use this feature for accounts not in the UNIX password
file, then you must update the âlocal_recipient_mapsâ setting in
the main.cf file, otherwise the SMTP server will reject mail for
non-UNIX accounts with âUser unknown in local recipient tableâ.
#fallback_transport = lmtp:unix:/var/lib/imap/socket/lmtp
#fallback_transport =
The luser_relay parameter specifies an optional destination address
for unknown recipients. By default, mail for unknown@$mydestination,
unknown@[$inet_interfaces] or unknown@[$proxy_interfaces] is returned
as undeliverable.
The following expansions are done on luser_relay: $user (recipient
username), $shell (recipient shell), $home (recipient home directory),
$recipient (full recipient address), $extension (recipient address
extension), $domain (recipient domain), $local (entire recipient
localpart), $recipient_delimiter. Specify ${name?value} or
${name:value} to expand value only when $name does (does not) exist.
luser_relay works only for the default Postfix local delivery agent.
NOTE: if you use this feature for accounts not in the UNIX password
file, then you must specify âlocal_recipient_maps =â (i.e. empty) in
the main.cf file, otherwise the SMTP server will reject mail for
non-UNIX accounts with âUser unknown in local recipient tableâ.
#luser_relay = $user@other.host
#luser_relay = $local@other.host
#luser_relay = admin+$local
JUNK MAIL CONTROLS
The controls listed here are only a very small subset. The file
SMTPD_ACCESS_README provides an overview.
The header_checks parameter specifies an optional table with patterns
that each logical message header is matched against, including
headers that span multiple physical lines.
By default, these patterns also apply to MIME headers and to the
headers of attached messages. With older Postfix versions, MIME and
attached message headers were treated as body text.
For details, see âman header_checksâ.
#header_checks = regexp:/etc/postfix/header_checks
FAST ETRN SERVICE
Postfix maintains per-destination logfiles with information about
deferred mail, so that mail can be flushed quickly with the SMTP
âETRN domain.tldâ command, or by executing âsendmail -qRdomain.tldâ.
See the ETRN_README document for a detailed description.
The fast_flush_domains parameter controls what destinations are
eligible for this service. By default, they are all domains that
this server is willing to relay mail to.
#fast_flush_domains = $relay_domains
SHOW SOFTWARE VERSION OR NOT
The smtpd_banner parameter specifies the text that follows the 220
code in the SMTP serverâs greeting banner. Some people like to see
the mail version advertised. By default, Postfix shows no version.
You MUST specify $myhostname at the start of the text. That is an
RFC requirement. Postfix itself does not care.
#smtpd_banner = $myhostname ESMTP $mail_name
#smtpd_banner = $myhostname ESMTP $mail_name ($mail_version)
PARALLEL DELIVERY TO THE SAME DESTINATION
How many parallel deliveries to the same user or domain? With local
delivery, it does not make sense to do massively parallel delivery
to the same user, because mailbox updates must happen sequentially,
and expensive pipelines in .forward files can cause disasters when
too many are run at the same time. With SMTP deliveries, 10
simultaneous connections to the same domain could be sufficient to
raise eyebrows.
Each message delivery transport has its XXX_destination_concurrency_limit
parameter. The default is $default_destination_concurrency_limit for
most delivery transports. For the local delivery agent the default is 2.
#local_destination_concurrency_limit = 2
#default_destination_concurrency_limit = 20
DEBUGGING CONTROL
The debug_peer_level parameter specifies the increment in verbose
logging level when an SMTP client or server host name or address
matches a pattern in the debug_peer_list parameter.
debug_peer_level = 2
The debug_peer_list parameter specifies an optional list of domain
or network patterns, /file/name patterns or type:name tables. When
an SMTP client or server host name or address matches a pattern,
increase the verbose logging level by the amount specified in the
debug_peer_level parameter.
#debug_peer_list = 127.0.0.1
#debug_peer_list = some.domain
The debugger_command specifies the external command that is executed
when a Postfix daemon program is run with the -D option.
Use âcommand ⌠& sleep 5â so that the debugger can attach before
the process marches on. If you use an X-based debugger, be sure to
set up your XAUTHORITY environment variable before starting Postfix.
debugger_command =
PATH=/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin
ddd $daemon_directory/$process_name $process_id & sleep 5
If you canât use X, use this to capture the call stack when a
daemon crashes. The result is in a file in the configuration
directory, and is named after the process name and the process ID.
debugger_command =
PATH=/bin:/usr/bin:/usr/local/bin; export PATH; (echo cont;
echo where) | gdb $daemon_directory/$process_name $process_id 2>&1
>$config_directory/$process_name.$process_id.log & sleep 5
Another possibility is to run gdb under a detached screen session.
To attach to the screen sesssion, su root and run "screen -r
<id_string>" where <id_string> uniquely matches one of the detached
sessions (from âscreen -listâ).
debugger_command =
PATH=/bin:/usr/bin:/sbin:/usr/sbin; export PATH; screen
-dmS $process_name gdb $daemon_directory/$process_name
$process_id & sleep 1
INSTALL-TIME CONFIGURATION INFORMATION
The following parameters are used when installing a new Postfix version.
sendmail_path: The full pathname of the Postfix sendmail command.
This is the Sendmail-compatible mail posting interface.
sendmail_path = /usr/sbin/sendmail.postfix
newaliases_path: The full pathname of the Postfix newaliases command.
This is the Sendmail-compatible command to build alias databases.
newaliases_path = /usr/bin/newaliases.postfix
mailq_path: The full pathname of the Postfix mailq command. This
is the Sendmail-compatible mail queue listing command.
mailq_path = /usr/bin/mailq.postfix
setgid_group: The group for mail submission and queue management
commands. This must be a group name with a numerical group ID that
is not shared with other accounts, not even with the Postfix account.
setgid_group = postdrop
html_directory: The location of the Postfix HTML documentation.
html_directory = no
manpage_directory: The location of the Postfix on-line manual pages.
manpage_directory = /usr/share/man
sample_directory: The location of the Postfix sample configuration files.
This parameter is obsolete as of Postfix 2.1.
sample_directory = /usr/share/doc/postfix-2.10.1/samples
readme_directory: The location of the Postfix README files.
readme_directory = /usr/share/doc/postfix-2.10.1/README_FILES