1
PPoossttffiixx BBaassiicc CCoonnffiigguurraattiioonn
3
-------------------------------------------------------------------------------
5
IInnttrroodduuccttiioonn
7
Postfix has several hundred configuration parameters that are controlled via
8
the main.cf file. Fortunately, all parameters have sensible default values. In
9
many cases, you need to configure only two or three parameters before you can
10
start to play with the mail system. Here's a quick introduction to the syntax:
12
* Postfix configuration files
14
The text below assumes that you already have Postfix installed on the system,
15
either by compiling the source code yourself (as described in the INSTALL file)
16
or by installing an already compiled version.
18
This document covers basic Postfix configuration. Information about how to
19
configure Postfix for specific applications such as mailhub, firewall or dial-
20
up client can be found in the STANDARD_CONFIGURATION_README file. But don't go
21
there until you already have covered the material presented below.
23
The first parameters of interest specify the machine's identity and role in the
26
* What domain name to use in outbound mail
28
* What domains to receive mail for
30
* What clients to relay mail from
32
* What destinations to relay mail to
34
* What delivery method: direct or indirect
36
The default values for many other configuration parameters are derived from
39
The next parameter of interest controls the amount of mail sent to the local
42
* What trouble to report to the postmaster
44
Be sure to set the following correctly if you're behind a proxy or network
45
address translator, and you are running a backup MX host for some other domain:
47
* Proxy/NAT external network addresses
49
Postfix daemon processes run in the background, and log problems and normal
50
activity to the syslog daemon. Here are a few things that you need to be aware
53
* What you need to know about Postfix logging
55
If your machine has unusual security requirements you may want to run Postfix
56
daemon processes inside a chroot environment.
58
* Running Postfix daemon processes chrooted
60
If you run Postfix on a virtual network interface, or if your machine runs
61
other mailers on virtual interfaces, you'll have to look at the other
62
parameters listed here as well:
68
* My own network addresses
70
PPoossttffiixx ccoonnffiigguurraattiioonn ffiilleess
72
By default, Postfix configuration files are in /etc/postfix. The two most
73
important files are main.cf and master.cf; these files must be owned by root.
74
Giving someone else write permission to main.cf or master.cf (or to their
75
parent directories) means giving root privileges to that person.
77
In /etc/postfix/main.cf you will have to set up a minimal number of
78
configuration parameters. Postfix configuration parameters resemble shell
79
variables, with two important differences: the first one is that Postfix does
80
not know about quotes like the UNIX shell does.
82
You specify a configuration parameter as:
87
and you use it by putting a "$" character in front of its name:
90
other_parameter = $parameter
92
You can use $parameter before it is given a value (that is the second main
93
difference with UNIX shell variables). The Postfix configuration language uses
94
lazy evaluation, and does not look at a parameter value until it is needed at
97
Postfix uses database files for access control, address rewriting and other
98
purposes. The DATABASE_README file gives an introduction to how Postfix works
99
with Berkeley DB, LDAP or SQL and other types. Here is a common example of how
100
Postfix invokes a database:
102
/etc/postfix/main.cf:
103
virtual_alias_maps = hash:/etc/postfix/virtual
105
Whenever you make a change to the main.cf or master.cf file, execute the
106
following command as root in order to refresh a running mail system:
110
WWhhaatt ddoommaaiinn nnaammee ttoo uussee iinn oouuttbboouunndd mmaaiill
112
The myorigin parameter specifies the domain that appears in mail that is posted
113
on this machine. The default is to use the local machine name, $myhostname,
114
which defaults to the name of the machine. Unless you are running a really
115
small site, you probably want to change that into $mydomain, which defaults to
116
the parent domain of the machine name.
118
For the sake of consistency between sender and recipient addresses, myorigin
119
also specifies the domain name that is appended to an unqualified recipient
122
Examples (specify only one of the following):
124
/etc/postfix/main.cf:
125
myorigin = $myhostname (default: send mail as "user@$myhostname")
126
myorigin = $mydomain (probably desirable: "user@$mydomain")
128
WWhhaatt ddoommaaiinnss ttoo rreecceeiivvee mmaaiill ffoorr
130
The mydestination parameter specifies what domains this machine will deliver
131
locally, instead of forwarding to another machine. The default is to receive
132
mail for the machine itself. See the VIRTUAL_README file for how to configure
133
Postfix for hosted domains.
135
You can specify zero or more domain names, "/file/name" patterns and/or "type:
136
table" lookup tables (such as hash:, btree:, nis:, ldap:, or mysql:), separated
137
by whitespace and/or commas. A "/file/name" pattern is replaced by its
138
contents; "type:table" requests that a table lookup is done and merely tests
139
for existence: the lookup result is ignored.
141
IMPORTANT: If your machine is a mail server for its entire domain, you must
142
list $mydomain as well.
144
Example 1: default setting.
146
/etc/postfix/main.cf:
147
mydestination = $myhostname localhost.$mydomain localhost
149
Example 2: domain-wide mail server.
151
/etc/postfix/main.cf:
152
mydestination = $myhostname localhost.$mydomain localhost $mydomain
154
Example 3: host with multiple DNS A records.
156
/etc/postfix/main.cf:
157
mydestination = $myhostname localhost.$mydomain localhost
158
www.$mydomain ftp.$mydomain
160
Caution: in order to avoid mail delivery loops, you must list all hostnames of
161
the machine, including $myhostname, and localhost.$mydomain.
163
WWhhaatt cclliieennttss ttoo rreellaayy mmaaiill ffrroomm
165
By default, Postfix will forward mail from clients in authorized network blocks
166
to any destination. Authorized networks are defined with the mynetworks
167
configuration parameter. The default is to authorize all clients in the IP
168
subnetworks that the local machine is attached to.
170
IMPORTANT: If your machine is connected to a wide area network then your
171
default mynetworks setting may be too friendly.
173
Examples (specify only one of the following):
175
/etc/postfix/main.cf:
176
mynetworks_style = subnet (default: authorize subnetworks)
177
mynetworks_style = host (safe: authorize local machine only)
178
mynetworks = 127.0.0.0/8 (safe: authorize local machine only)
179
mynetworks = 127.0.0.0/8 168.100.189.2/32 (authorize local machine)
181
You can specify the trusted networks in the main.cf file, or you can let
182
Postfix do the work for you. The default is to let Postfix do the work. The
183
result depends on the mynetworks_style parameter value.
185
* Specify "mynetworks_style = host" when Postfix should forward mail from
186
only the local machine.
188
* Specify "mynetworks_style = subnet" (the default) when Postfix should
189
forward mail from SMTP clients in the same IP subnetworks as the local
190
machine. On Linux, this works correctly only with interfaces specified with
191
the "ifconfig" command.
193
* Specify "mynetworks_style = class" when Postfix should forward mail from
194
SMTP clients in the same IP class A/B/C networks as the local machine.
195
Don't do this with a dialup site - it would cause Postfix to "trust" your
196
entire provider's network. Instead, specify an explicit mynetworks list by
197
hand, as described below.
199
Alternatively, you can specify the mynetworks list by hand, in which case
200
Postfix ignores the mynetworks_style setting. To specify the list of trusted
201
networks by hand, specify network blocks in CIDR (network/mask) notation, for
204
/etc/postfix/main.cf:
205
mynetworks = 168.100.189.0/28, 127.0.0.0/8
207
You can also specify the absolute pathname of a pattern file instead of listing
208
the patterns in the main.cf file.
210
WWhhaatt ddeessttiinnaattiioonnss ttoo rreellaayy mmaaiill ttoo
212
By default, Postfix will forward mail from strangers (clients outside
213
authorized networks) to authorized destinations only. Authorized destinations
214
are defined with the relay_domains configuration parameter. The default is to
215
authorize all domains (and subdomains) of the domains listed with the
216
mydestination parameter.
218
Examples (specify only one of the following):
220
/etc/postfix/main.cf:
221
relay_domains = $mydestination (default)
222
relay_domains = (safe: never forward mail from strangers)
223
relay_domains = $mydomain (forward mail to my domain and subdomains)
225
WWhhaatt ddeelliivveerryy mmeetthhoodd:: ddiirreecctt oorr iinnddiirreecctt
227
By default, Postfix tries to deliver mail directly to the Internet. Depending
228
on your local conditions this may not be possible or desirable. For example,
229
your system may be turned off outside office hours, it may be behind a
230
firewall, or it may be connected via a provider who does not allow direct mail
231
to the Internet. In those cases you need to configure Postfix to deliver mail
232
indirectly via a relay host.
234
Examples (specify only one of the following):
236
/etc/postfix/main.cf:
237
relayhost = (default: direct delivery to Internet)
238
relayhost = $mydomain (deliver via local mailhub)
239
relayhost = [mail.$mydomain] (deliver via local mailhub)
240
relayhost = [mail.isp.tld] (deliver via provider mailhub)
242
The form enclosed with [] eliminates DNS MX lookups. Don't worry if you don't
243
know what that means.
245
The STANDARD_CONFIGURATION_README file has more hints and tips for firewalled
246
and/or dial-up networks.
248
WWhhaatt ttrroouubbllee ttoo rreeppoorrtt ttoo tthhee ppoossttmmaasstteerr
250
You should set up a postmaster alias in the aliases(5) table that directs mail
251
to a human person. The postmaster address is required to exist, so that people
252
can report mail delivery problems. While you're updating the aliases(5) table,
253
be sure to direct mail for the super-user to a human person too.
259
Execute the command "newaliases" after changing the aliases file. Instead of /
260
etc/aliases, your alias file may be located elsewhere. Use the command
261
"postconf alias_maps" to find out.
263
The Postfix system reports problems to the postmaster alias. You may not be
264
interested in all types of trouble reports, so this reporting mechanism is
265
configurable. The default is to report only serious problems (resource,
266
software) to postmaster:
270
/etc/postfix/main.cf:
271
notify_classes = resource, software
273
The meaning of the classes is as follows:
276
Inform the postmaster of undeliverable mail. Either send the postmaster
277
a copy of undeliverable mail that is returned to the sender, or send a
278
transcript of the SMTP session when Postfix rejected mail. For privacy
279
reasons, the postmaster copy of undeliverable mail is truncated after
280
the original message headers. This implies "2bounce" (see below). See
281
also the luser_relay feature. The notification is sent to the address
282
specified with the bounce_notice_recipient configuration parameter
283
(default: postmaster).
285
When Postfix is unable to return undeliverable mail to the sender, send
286
it to the postmaster instead (without truncating the message after the
287
primary headers). The notification is sent to the address specified
288
with the 2bounce_notice_recipient configuration parameter (default:
291
Inform the postmaster of delayed mail. In this case, the postmaster
292
receives message headers only. The notification is sent to the address
293
specified with the delay_notice_recipient configuration parameter
294
(default: postmaster).
296
Inform the postmaster of client requests that were rejected because of
297
(UCE) policy restrictions. The postmaster receives a transcript of the
298
SMTP session. The notification is sent to the address specified with
299
the error_notice_recipient configuration parameter (default:
302
Inform the postmaster of protocol errors (client or server side) or
303
attempts by a client to execute unimplemented commands. The postmaster
304
receives a transcript of the SMTP session. The notification is sent to
305
the address specified with the error_notice_recipient configuration
306
parameter (default: postmaster).
308
Inform the postmaster of mail not delivered due to resource problems
309
(for example, queue file write errors). The notification is sent to the
310
address specified with the error_notice_recipient configuration
311
parameter (default: postmaster).
313
Inform the postmaster of mail not delivered due to software problems.
314
The notification is sent to the address specified with the
315
error_notice_recipient configuration parameter (default: postmaster).
317
PPrrooxxyy//NNAATT eexxtteerrnnaall nneettwwoorrkk aaddddrreesssseess
319
Some mail servers are connected to the Internet via a network address
320
translator (NAT) or proxy. This means that systems on the Internet connect to
321
the address of the NAT or proxy, instead of connecting to the network address
322
of the mail server. The NAT or proxy forwards the connection to the network
323
address of the mail server, but Postfix does not know this.
325
If you run a Postfix server behind a proxy or NAT, you need to configure the
326
proxy_interfaces parameter and specify all the external proxy or NAT addresses
327
that Postfix receives mail on. You may specify symbolic hostnames instead of
330
IMPORTANT: You must specify your proxy/NAT external addresses when your system
331
is a backup MX host for other domains, otherwise mail delivery loops will
332
happen when the primary MX host is down.
334
Example: host behind NAT box running a backup MX host.
336
/etc/postfix/main.cf:
337
proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address)
339
WWhhaatt yyoouu nneeeedd ttoo kknnooww aabboouutt PPoossttffiixx llooggggiinngg
341
Postfix daemon processes run in the background, and log problems and normal
342
activity to the syslog daemon. The syslogd process sorts events by class and
343
severity, and appends them to logfiles. The logging classes, levels and logfile
344
names are usually specified in /etc/syslog.conf. At the very least you need
348
mail.err /dev/console
349
mail.debug /var/log/maillog
351
After changing the syslog.conf file, send a "HUP" signal to the syslogd
354
IMPORTANT: many syslogd implementations will not create files. You must create
355
files before (re)starting syslogd.
357
IMPORTANT: on Linux you need to put a "-" character before the pathname, e.g.,
358
-/var/log/maillog, otherwise the syslogd process will use more system resources
361
Hopefully, the number of problems will be small, but it is a good idea to run
362
every night before the syslog files are rotated:
365
# egrep '(reject|warning|error|fatal|panic):' /some/log/file
367
* The first line (postfix check) causes Postfix to report file permission/
368
ownership discrepancies.
370
* The second line looks for problem reports from the mail software, and
371
reports how effective the relay and junk mail access blocks are. This may
372
produce a lot of output. You will want to apply some postprocessing to
373
eliminate uninteresting information.
375
The DEBUG_README document describes the meaning of the "warning" etc. labels in
378
RRuunnnniinngg PPoossttffiixx ddaaeemmoonn pprroocceesssseess cchhrrooootteedd
380
Postfix daemon processes can be configured (via the master.cf file) to run in a
381
chroot jail. The processes run at a fixed low privilege and with file system
382
access limited to the Postfix queue directories (/var/spool/postfix). This
383
provides a significant barrier against intrusion. The barrier is not
384
impenetrable (chroot limits file system access only), but every little bit
387
With the exception of Postfix daemons that deliver mail locally and/or that
388
execute non-Postfix commands, every Postfix daemon can run chrooted.
390
Sites with high security requirements should consider to chroot all daemons
391
that talk to the network: the smtp(8) and smtpd(8) processes, and perhaps also
392
the lmtp(8) client. The author's own porcupine.org mail server runs all daemons
393
chrooted that can be chrooted.
395
The default /etc/postfix/master.cf file specifies that no Postfix daemon runs
396
chrooted. In order to enable chroot operation, edit the file /etc/postfix/
397
master.cf, and follow instructions in the file. When you're finished, execute
398
"postfix reload" to make the change effective.
400
Note that a chrooted daemon resolves all filenames relative to the Postfix
401
queue directory (/var/spool/postfix). For successful use of a chroot jail, most
402
UNIX systems require you to bring in some files or device nodes. The examples/
403
chroot-setup directory in the source code distribution has a collection of
404
scripts that help you set up Postfix chroot environments on different operating
407
Additionally, you almost certainly need to configure syslogd so that it listens
408
on a socket inside the Postfix queue directory. Examples of syslogd command
409
line options that achieve this for specific systems:
411
FreeBSD: syslogd -l /var/spool/postfix/var/run/log
413
Linux, OpenBSD: syslogd -a /var/spool/postfix/dev/log
415
MMyy oowwnn hhoossttnnaammee
417
The myhostname parameter specifies the fully-qualified domain name of the
418
machine running the Postfix system. $myhostname appears as the default value in
419
many other Postfix configuration parameters.
421
By default, myhostname is set to the local machine name. If your local machine
422
name is not in fully-qualified domain name form, or if you run Postfix on a
423
virtual interface, you will have to specify the fully-qualified domain name
424
that the mail system should use.
426
Alternatively, if you specify mydomain in main.cf, then Postfix will use its
427
value to generate a fully-qualified default value for the myhostname parameter.
429
Examples (specify only one of the following):
431
/etc/postfix/main.cf:
432
myhostname = host.local.domain (machine name is not FQDN)
433
myhostname = host.virtual.domain (virtual interface)
434
myhostname = virtual.domain (virtual interface)
436
MMyy oowwnn ddoommaaiinn nnaammee
438
The mydomain parameter specifies the parent domain of $myhostname. By default,
439
it is derived from $myhostname by stripping off the first part (unless the
440
result would be a top-level domain).
442
Conversely, if you specify mydomain in main.cf, then Postfix will use its value
443
to generate a fully-qualified default value for the myhostname parameter.
445
Examples (specify only one of the following):
447
/etc/postfix/main.cf:
448
mydomain = local.domain
449
mydomain = virtual.domain (virtual interface)
451
MMyy oowwnn nneettwwoorrkk aaddddrreesssseess
453
The inet_interfaces parameter specifies all network interface addresses that
454
the Postfix system should listen on; mail addressed to "user@[network address]"
455
will be delivered locally, as if it is addressed to a domain listed in
458
You can override the inet_interfaces setting in the Postfix master.cf file by
459
prepending an IP address to a server name.
461
The default is to listen on all active interfaces. If you run mailers on
462
virtual interfaces, you will have to specify what interfaces to listen on.
464
IMPORTANT: If you run MTAs on virtual interfaces you must specify explicit
465
inet_interfaces values for the MTA that receives mail for the machine itself:
466
this MTA should never listen on the virtual interfaces or you would have a
467
mailer loop when a virtual MTA is down.
469
Example: default setting.
471
/etc/postfix/main.cf:
472
inet_interfaces = all
474
Example: host running one or more virtual mailers. For each Postfix instance,
475
specify only one of the following.
477
/etc/postfix/main.cf:
478
inet_interfaces = virtual.host.tld (virtual Postfix)
479
inet_interfaces = $myhostname localhost... (non-virtual Postfix)
481
Note: you need to stop and start Postfix after changing this parameter.
added
removed
README_FILES/BASIC_CONFIGURATION_README
