1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title> Postfix Basic Configuration </title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body>
<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Basic Configuration </h1>
<hr>
<h2> Introduction </h2>
<p> Postfix has several hundred configuration parameters that are
controlled via the main.cf file. Fortunately, all parameters have
sensible default values. In many cases, you need to configure only
two or three parameters before you can start to play with the mail
system. Here's a quick introduction to the syntax: </p>
<ul>
<li> <p> <a href="#syntax">Postfix configuration files</a></p>
</ul>
<p> The text below assumes that you already have Postfix installed
on the system, either by compiling the source code yourself (as
described in the INSTALL file) or by installing an already compiled
version. </p>
<p> This document covers basic Postfix configuration. Information
about how to configure Postfix for specific applications such as
mailhub, firewall or dial-up client can be found in the
STANDARD_CONFIGURATION_README file. But don't go there until you
already have covered the material presented below. </p>
<p> The first parameters of interest specify the machine's identity
and role in the network. </p>
<ul>
<li> <p> <a href="#myorigin"> What domain name to use in outbound mail </a> </p>
<li> <p> <a href="#mydestination"> What domains to receive mail for </a> </p>
<li> <p> <a href="#relay_from"> What clients to relay mail from </a> </p>
<li> <p> <a href="#relay_to"> What destinations to relay mail to </a> </p>
<li> <p> <a href="#relayhost"> What delivery method: direct or
indirect </a> </p>
</ul>
<p> The default values for many other configuration parameters are
derived from just these. </p>
<p> The next parameter of interest controls the amount of mail sent
to the local postmaster: </p>
<ul>
<li> <p> <a href="#notify"> What trouble to report to the postmaster
</a> </p>
</ul>
<p> Be sure to set the following correctly if you're behind a proxy or
network address translator, and you are running a backup MX host
for some other domain: </p>
<ul>
<li> <p> <a href="#proxy_interfaces"> Proxy/NAT external network
addresses </a> </p>
</ul>
<p> Postfix daemon processes run in the background, and log problems
and normal activity to the syslog daemon. Here are a few things
that you need to be aware of: </p>
<ul>
<li> <p> <a href="#syslog_howto"> What you need to know about
Postfix logging </a> </p>
</ul>
<p> If your machine has unusual security requirements you may
want to run Postfix daemon processes inside a chroot environment. </p>
<ul>
<li> <p> <a href="#chroot_setup"> Running Postfix daemon processes
chrooted </a> </p>
</ul>
<p> If you run Postfix on a virtual network interface, or if your
machine runs other mailers on virtual interfaces, you'll have to
look at the other parameters listed here as well: </p>
<ul>
<li> <p> <a href="#myhostname"> My own hostname </a> </p>
<li> <p> <a href="#mydomain"> My own domain name </a> </p>
<li> <p> <a href="#inet_interfaces"> My own network addresses </a> </p>
</ul>
<h2> <a name="syntax">Postfix configuration files</a></h2>
<p> By default, Postfix configuration files are in /etc/postfix.
The two most important files are main.cf and master.cf; these files
must be owned by root. Giving someone else write permission to
main.cf or master.cf (or to their parent directories) means giving
root privileges to that person. </p>
<p> In /etc/postfix/main.cf you will have to set up a minimal number
of configuration parameters. Postfix configuration parameters
resemble shell variables, with two important differences: the first
one is that Postfix does not know about quotes like the UNIX shell
does.</p>
<p> You specify a configuration parameter as: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
parameter = value
</pre>
</blockquote>
<p> and you use it by putting a "$" character in front of its name: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
other_parameter = $parameter
</pre>
</blockquote>
<p> You can use $parameter before it is given a value (that is the
second main difference with UNIX shell variables). The Postfix
configuration language uses lazy evaluation, and does not look at
a parameter value until it is needed at runtime. </p>
<p> Postfix uses database files for access control, address rewriting
and other purposes. The DATABASE_README file gives an introduction
to how Postfix works with Berkeley DB, LDAP or SQL and other types.
Here is a common example of how Postfix invokes a database: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
virtual_alias_maps = hash:/etc/postfix/virtual
</pre>
</blockquote>
<p> Whenever you make a change to the main.cf or master.cf file,
execute the following command as root in order to refresh a running
mail system: </p>
<blockquote>
<pre>
# postfix reload
</pre>
</blockquote>
<h2> <a name="myorigin"> What domain name to use in outbound mail </a> </h2>
<p> The myorigin parameter specifies the domain that appears in
mail that is posted on this machine. The default is to use the
local machine name, $myhostname, which defaults to the name of the
machine. Unless you are running a really small site, you probably
want to change that into $mydomain, which defaults to the parent
domain of the machine name. </p>
<p> For the sake of consistency between sender and recipient addresses,
myorigin also specifies the domain name that is appended
to an unqualified recipient address. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
myorigin = $myhostname (default: send mail as "user@$myhostname")
myorigin = $mydomain (probably desirable: "user@$mydomain")
</pre>
</blockquote>
<h2><a name="mydestination"> What domains to receive mail for </a>
</h2>
<p> The mydestination parameter specifies what domains this
machine will deliver locally, instead of forwarding to another
machine. The default is to receive mail for the machine itself.
See the VIRTUAL_README file for how to configure Postfix for
hosted domains. </p>
<p> You can specify zero or more domain names, "/file/name" patterns
and/or "type:table" lookup tables (such as hash:, btree:, nis:, ldap:,
or mysql:), separated by whitespace and/or commas. A "/file/name"
pattern is replaced by its contents; "type:table" requests that a
table lookup is done and merely tests for existence: the lookup
result is ignored. </p>
<p> IMPORTANT: If your machine is a mail server for its entire
domain, you must list $mydomain as well. </p>
<p> Example 1: default setting. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mydestination = $myhostname localhost.$mydomain localhost
</pre>
</blockquote>
<p> Example 2: domain-wide mail server. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mydestination = $myhostname localhost.$mydomain localhost $mydomain
</pre>
</blockquote>
<p> Example 3: host with multiple DNS A records. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mydestination = $myhostname localhost.$mydomain localhost
www.$mydomain ftp.$mydomain
</pre>
</blockquote>
<p> Caution: in order to avoid mail delivery loops, you must list all
hostnames of the machine, including $myhostname, and localhost.$mydomain. </p>
<h2> <a name="relay_from"> What clients to relay mail from </a> </h2>
<p> By default, Postfix will forward mail from clients in authorized
network blocks to any destination. Authorized networks are defined
with the mynetworks configuration parameter. The current default is to
authorize the local machine only. Prior to Postfix 3.0, the default
was to authorize all clients in the IP subnetworks that the local
machine is attached to. </p>
<p> Postfix can also be configured to relay mail from "mobile"
clients that send mail from outside an authorized network block.
This is explained in the SASL_README and TLS_README documents. </p>
<p> IMPORTANT: If your machine is connected to a wide area network
then the "mynetworks_style = host" setting may be too friendly. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mynetworks_style = subnet (not safe on a wide area network)
mynetworks_style = host (authorize local machine only)
mynetworks = 127.0.0.0/8 (authorize local machine only)
mynetworks = 127.0.0.0/8 168.100.189.2/32 (authorize local machine)
mynetworks = 127.0.0.0/8 168.100.189.2/28 (authorize local networks)
</pre>
</blockquote>
<p> You can specify the trusted networks in the main.cf file, or
you can let Postfix do the work for you. The default is to let
Postfix do the work. The result depends on the mynetworks_style
parameter value.
<ul>
<li> <p> Specify "mynetworks_style = host" when Postfix should
forward mail from only the local machine. </p>
<li> <p> Specify "mynetworks_style = subnet" (the default) when
Postfix should forward mail from SMTP clients in the same IP
subnetworks as the local machine. On Linux, this works correctly
only with interfaces specified with the "ifconfig" command. </p>
<li> <p> Specify "mynetworks_style = class" when Postfix should
forward mail from 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.
</p>
</ul>
<p> Alternatively, you can specify the mynetworks list by hand,
in which case Postfix ignores the mynetworks_style setting.
To specify the list of trusted networks by hand, specify network
blocks in CIDR (network/mask) notation, for example: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mynetworks = 168.100.189.0/28, 127.0.0.0/8
</pre>
</blockquote>
<p> You can also specify the absolute pathname of a pattern file instead
of listing the patterns in the main.cf file. </p>
<h2> <a name="relay_to"> What destinations to relay mail to </a> </h2>
<p> By default, Postfix will forward mail from strangers (clients outside
authorized networks) to authorized remote destinations only.
Authorized remote
destinations are defined with the relay_domains configuration
parameter. The default is to authorize all domains (and subdomains)
of the domains listed with the mydestination parameter. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
relay_domains = $mydestination (default)
relay_domains = (safe: never forward mail from strangers)
relay_domains = $mydomain (forward mail to my domain and subdomains)
</pre>
</blockquote>
<h2> <a name="relayhost"> What delivery method: direct or
indirect </a> </h2>
<p> By default, Postfix tries to deliver mail directly to the
Internet. Depending on your local conditions this may not be possible
or desirable. For example, your system may be turned off outside
office hours, it may be behind a firewall, or it may be connected
via a provider who does not allow direct mail to the Internet. In
those cases you need to configure Postfix to deliver mail indirectly
via a relay host. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
relayhost = (default: direct delivery to Internet)
relayhost = $mydomain (deliver via local mailhub)
relayhost = [mail.$mydomain] (deliver via local mailhub)
relayhost = [mail.isp.tld] (deliver via provider mailhub)
</pre>
</blockquote>
<p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups.
Don't worry if you don't know what that means. Just be sure to
specify the <tt>[]</tt> around the mailhub hostname that your ISP
gave to you, otherwise mail may be mis-delivered. </p>
<p> The STANDARD_CONFIGURATION_README file has more hints and tips
for firewalled and/or dial-up networks. </p>
<h2> <a name="notify"> What trouble to report to the postmaster</a> </h2>
<p> You should set up a postmaster alias in the aliases(5) table
that directs mail to a human person. The postmaster address is
required to exist, so that people can report mail delivery problems.
While you're updating the aliases(5) table, be sure to direct mail
for the super-user to a human person too. </p>
<blockquote>
<pre>
/etc/aliases:
postmaster: you
root: you
</pre>
</blockquote>
<p> Execute the command "newaliases" after changing the aliases
file. Instead of /etc/aliases, your alias file may be located
elsewhere. Use the command "postconf alias_maps" to find out.</p>
<p> The Postfix system reports problems to the postmaster alias.
You may not be interested in all types of trouble reports, so this
reporting mechanism is configurable. The default is to report only
serious problems (resource, software) to postmaster: </p>
<p> Default setting: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
notify_classes = resource, software
</pre>
</blockquote>
<p> The meaning of the classes is as follows: </p>
<blockquote>
<dl>
<dt> bounce </dt> <dd> Inform the postmaster of undeliverable
mail. Either send the postmaster a copy of undeliverable mail that
is returned to the sender, or send a transcript of the SMTP session
when Postfix rejected mail. For privacy reasons, the postmaster
copy of undeliverable mail is truncated after the original message
headers. This implies "2bounce" (see below). See also the
luser_relay feature. The notification is sent to the address
specified with the bounce_notice_recipient configuration parameter
(default: postmaster). </dd>
<dt> 2bounce </dt> <dd> When Postfix is unable to return undeliverable
mail to the sender, send it to the postmaster instead (without
truncating the message after the primary headers). The notification
is sent to the address specified with the 2bounce_notice_recipient
configuration parameter (default: postmaster). </dd>
<dt> delay </dt> <dd> Inform the postmaster of delayed mail. In
this case, the postmaster receives message headers only. The
notification is sent to the address specified with the
delay_notice_recipient configuration parameter (default: postmaster).
</dd>
<dt> policy </dt> <dd> Inform the postmaster of client requests
that were rejected because of (UCE) policy restrictions. The
postmaster receives a transcript of the SMTP session. The notification
is sent to the address specified with the error_notice_recipient
configuration parameter (default: postmaster). </dd>
<dt> protocol </dt> <dd> Inform the postmaster of protocol errors
(client or server side) or attempts by a client to execute
unimplemented commands. The postmaster receives a transcript of
the SMTP session. The notification is sent to the address specified
with the error_notice_recipient configuration parameter (default:
postmaster). </dd>
<dt> resource </dt> <dd> Inform the postmaster of mail not delivered
due to resource problems (for example, queue file write errors).
The notification is sent to the address specified with the
error_notice_recipient configuration parameter (default: postmaster).
</dd>
<dt> software </dt> <dd> Inform the postmaster of mail not delivered
due to software problems. The notification is sent to the address
specified with the error_notice_recipient configuration parameter
(default: postmaster). </dd>
</dl>
</blockquote>
<h2><a name="proxy_interfaces"> Proxy/NAT external network
addresses</a> </h2>
<p> Some mail servers are connected to the Internet via a network
address translator (NAT) or proxy. This means that systems on the
Internet connect to the address of the NAT or proxy, instead of
connecting to the network address of the mail server. The NAT or
proxy forwards the connection to the network address of the mail
server, but Postfix does not know this. </p>
<p> If you run a Postfix server behind a proxy or NAT, you need to
configure the proxy_interfaces parameter and specify all the external
proxy or NAT addresses that Postfix receives mail on. You may
specify symbolic hostnames instead of network addresses. </p>
<p> IMPORTANT: You must specify your proxy/NAT external 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.
</p>
<p> Example: host behind NAT box running a backup MX host. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address)
</pre>
</blockquote>
<h2> <a name="syslog_howto"> What you need to know about
Postfix logging </a> </h2>
<p> Postfix daemon processes run in the background, and log problems
and normal activity to the syslog daemon. The syslogd process sorts
events by class and severity, and appends them to logfiles. The
logging classes, levels and logfile names are usually specified in
/etc/syslog.conf. At the very least you need something like: </p>
<blockquote>
<pre>
/etc/syslog.conf:
mail.err /dev/console
mail.debug /var/log/maillog
</pre>
</blockquote>
<p> After changing the syslog.conf file, send a "HUP" signal to
the syslogd process. </p>
<p> IMPORTANT: many syslogd implementations will not create files.
You must create files before (re)starting syslogd. </p>
<p> IMPORTANT: on Linux you need to put a "-" character before the
pathname, e.g., -/var/log/maillog, otherwise the syslogd process
will use more system resources than Postfix. </p>
<p> Hopefully, the number of problems will be small, but it is a good
idea to run every night before the syslog files are rotated: </p>
<blockquote>
<pre>
# postfix check
# egrep '(reject|warning|error|fatal|panic):' /some/log/file
</pre>
</blockquote>
<ul>
<li> <p> The first line (postfix check) causes Postfix to report
file permission/ownership discrepancies. </p>
<li> <p> The second line looks for problem reports from the mail
software, and reports how effective the relay and junk mail access
blocks are. This may produce a lot of output. You will want to
apply some postprocessing to eliminate uninteresting information.
</p>
</ul>
<p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a>
document describes the meaning of the "warning" etc. labels in
Postfix logging. </p>
<h2> <a name="chroot_setup"> Running Postfix daemon processes
chrooted </a> </h2>
<p> Postfix daemon processes can be configured (via the master.cf
file) to run in a chroot jail. The processes run at a fixed low
privilege and with file system access limited to the Postfix queue
directories (/var/spool/postfix). This provides a significant
barrier against intrusion. The barrier is not impenetrable (chroot
limits file system access only), but every little bit helps.</p>
<p>With the exception of Postfix daemons that deliver mail locally
and/or that execute non-Postfix commands, every Postfix daemon can
run chrooted.</p>
<p>Sites with high security requirements should consider to chroot
all daemons that talk to the network: the smtp(8) and smtpd(8)
processes, and perhaps also the lmtp(8) client. The author's own
porcupine.org mail server runs all daemons chrooted that can be
chrooted. </p>
<p>The default /etc/postfix/master.cf file specifies that no Postfix
daemon runs chrooted. In order to enable chroot operation, edit
the file /etc/postfix/master.cf, and follow instructions in the
file. When you're finished, execute "postfix reload" to make the
change effective. </p>
<p>Note that a chrooted daemon resolves all filenames relative to
the Postfix queue directory (/var/spool/postfix). For successful
use of a chroot jail, most UNIX systems require you to bring in
some files or device nodes. The examples/chroot-setup directory in
the source code distribution has a collection of scripts that help
you set up Postfix chroot environments on different operating
systems.</p>
<p> Additionally, you almost certainly need to configure syslogd
so that it listens on a socket inside the Postfix queue directory.
Examples of syslogd command line options that achieve this for
specific systems: </p>
<p> FreeBSD: <tt>syslogd -l /var/spool/postfix/var/run/log</tt> </p>
<p> Linux, OpenBSD: <tt>syslogd -a /var/spool/postfix/dev/log</tt> </p>
<h2><a name="myhostname"> My own hostname </a> </h2>
<p> The myhostname parameter specifies the fully-qualified domain
name of the machine running the Postfix system. $myhostname
appears as the default value in many other Postfix configuration
parameters. </p>
<p> By default, myhostname is set to the local machine name. If
your local machine name is not in fully-qualified domain name form,
or if you run Postfix on a virtual interface, you will have to
specify the fully-qualified domain name that the mail system should
use. </p>
<p> Alternatively, if you specify mydomain in main.cf, then Postfix
will use its value to generate a fully-qualified default value
for the myhostname parameter. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
myhostname = host.local.domain (machine name is not FQDN)
myhostname = host.virtual.domain (virtual interface)
myhostname = virtual.domain (virtual interface)
</pre>
</blockquote>
<h2><a name="mydomain"> My own domain name</a> </h2>
<p> The mydomain parameter specifies the parent domain of
$myhostname. By default, it is derived from $myhostname
by stripping off the first part (unless the result would be a
top-level domain). </p>
<p> Conversely, if you specify mydomain in main.cf, then Postfix
will use its value to generate a fully-qualified default value
for the myhostname parameter. </p>
<p> Examples (specify only one of the following): </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
mydomain = local.domain
mydomain = virtual.domain (virtual interface)
</pre>
</blockquote>
<h2><a name="inet_interfaces">My own network addresses</a> </h2>
<p>The inet_interfaces parameter specifies all network interface
addresses that the Postfix system should listen on; mail addressed
to "user@[network address]" will be delivered locally,
as if it is addressed to a domain listed in $mydestination.</p>
<p> You can override the inet_interfaces setting in the Postfix
master.cf file by prepending an IP address to a server name. </p>
<p> The default is to listen on all active interfaces. If you run
mailers on virtual interfaces, you will have to specify what
interfaces to listen on. </p>
<p> IMPORTANT: If you run MTAs on virtual interfaces you must
specify explicit inet_interfaces values for the MTA that receives
mail for the machine itself: this MTA should never listen on the
virtual interfaces or you would have a mailer loop when a virtual
MTA is down. </p>
<p> Example: default setting. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
inet_interfaces = all
</pre>
</blockquote>
<p> Example: host running one or more virtual mailers. For
each Postfix instance, specify only one of the following. </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
inet_interfaces = virtual.host.tld (virtual Postfix)
inet_interfaces = $myhostname localhost... (non-virtual Postfix)
</pre>
</blockquote>
<p> Note: you need to stop and start Postfix after changing this
parameter. </p>
</body>
</html>
|
