1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix Installation From Source Code </title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 11 12</head> 13 14<body> 15 16<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 17Installation From Source Code </h1> 18 19<hr> 20 21<h2> <a name="1">1 - Purpose of this document</a> </h2> 22 23<p> If you are using a pre-compiled version of Postfix, you should 24start with BASIC_CONFIGURATION_README and the general documentation 25referenced by it. INSTALL is only a bootstrap document to get 26Postfix up and running from scratch with the minimal number of 27steps; it should not be considered part of the general documentation. 28</p> 29 30<p> This document describes how to build, install and configure a 31Postfix system so that it can do one of the following: </p> 32 33<ul> 34 35<li> Send mail only, without changing an existing Sendmail 36installation. 37 38<li> Send and receive mail via a virtual host interface, still 39without any change to an existing Sendmail installation. 40 41<li> Run Postfix instead of Sendmail. 42 43</ul> 44 45<p> Topics covered in this document: </p> 46 47<ol> 48 49<li> <a href="#1">Purpose of this document</a> 50 51<li> <a href="#2">Typographical conventions</a> 52 53<li> <a href="#3">Documentation</a> 54 55<li> <a href="#4">Building on a supported system</a> 56 57<li> <a href="#5">Porting Postfix to an unsupported system</a> 58 59<li> <a href="#install">Installing the software after successful 60compilation </a> 61 62<li> <a href="#send_only">Configuring Postfix to send mail 63only </a> 64 65<li> <a href="#send_receive">Configuring Postfix to send and 66receive mail via virtual interface </a> 67 68<li> <a href="#replace">Running Postfix instead of Sendmail</a> 69 70<li> <a href="#mandatory">Mandatory configuration file edits</a> 71 72<li> <a href="#hamlet">To chroot or not to chroot</a> 73 74<li> <a href="#care">Care and feeding of the Postfix system</a> 75 76</ol> 77 78<h2> <a name="2">2 - Typographical conventions</a> </h2> 79 80<p> In the instructions below, a command written as </p> 81 82<blockquote> 83<pre> 84# command 85</pre> 86</blockquote> 87 88<p> should be executed as the superuser. </p> 89 90<p> A command written as </p> 91 92<blockquote> 93<pre> 94% command 95</pre> 96</blockquote> 97 98<p> should be executed as an unprivileged user. </p> 99 100<h2> <a name="3">3 - Documentation</a> </h2> 101 102<p> Documentation is available as README files (start with the file 103README_FILES/AAAREADME), as HTML web pages (point your browser to 104"html/index.html") and as UNIX-style manual pages. </p> 105 106<p> You should view the README files with a pager such as more(1) 107or less(1), because the files use backspace characters in order to 108produce <b>bold</b> font. To print a README file without backspace 109characters, use the col(1) command. For example: </p> 110 111<blockquote> 112<pre> 113% col -bx <file | lpr 114</pre> 115</blockquote> 116 117<p> In order to view the manual pages before installing Postfix, 118point your MANPATH environment variable to the "man" subdirectory; 119be sure to use an absolute path. </p> 120 121<blockquote> 122<pre> 123% export MANPATH; MANPATH="`pwd`/man:$MANPATH" 124% setenv MANPATH "`pwd`/man:$MANPATH" 125</pre> 126</blockquote> 127 128<p> Of particular interest is the postconf(5) manual page that 129lists all the 500+ configuration parameters. The HTML version of 130this text makes it easy to navigate around. </p> 131 132<p> All Postfix source files have their own built-in manual page. 133Tools to extract those embedded manual pages are available in the 134mantools directory. </p> 135 136<h2> <a name="4">4 - Building on a supported system</a> </h2> 137 138<p> At some point in time, a version of Postfix was supported on: </p> 139 140<blockquote> 141<p> 142AIX 3.2.5, 4.1.x, 4.2.0, 4.3.x, 5.2 <br> 143BSD/OS 2.x, 3.x, 4.x <br> 144Darwin 1.x <br> 145FreeBSD 2.x, 3.x, 4.x, 5.x <br> 146HP-UX 9.x, 10.x, 11.x <br> 147IRIX 5.x, 6.x <br> 148Linux Debian 1.3.1, 2.x, 3.x <br> 149Linux RedHat 3.x (January 2004) - 9.x <br> 150Linux Slackware 3.x, 4.x, 7.x <br> 151Linux SuSE 5.x, 6.x, 7.x <br> 152Linux Ubuntu 4.10..7.04<br> 153Mac OS X <br> 154NEXTSTEP 3.x <br> 155NetBSD 1.x <br> 156OPENSTEP 4.x <br> 157OSF1.V3 - OSF1.V5 (Digital UNIX) <br> 158Reliant UNIX 5.x <br> 159Rhapsody 5.x <br> 160SunOS 4.1.4 (March 2007) <br> 161SunOS 5.4 - 5.10 (Solaris 2.4..10) <br> 162Ultrix 4.x (well, that was long ago) <br> 163</p> 164</blockquote> 165 166<p> or something closely resemblant. </p> 167 168<h3>4.1 - Getting started</h3> 169 170<p> On Solaris, the "make" command and other utilities for software 171development are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in 172your command search path. If these files do not exist, install the 173development packages first. See the Solaris FAQ item "<a 174href="http://www.science.uva.nl/pub/solaris/solaris2.html#q6.2">Which 175packages do I need to install to support a C compiler?</a>". </p> 176 177<p> If you need to build Postfix for multiple architectures, use the 178"lndir" command to build a shadow tree with symbolic links to the 179source files. "lndir" is part of X11R6. </p> 180 181<p> If at any time in the build process you get messages like: "make: 182don't know how to ..." you should be able to recover by running 183the following command from the Postfix top-level directory: </p> 184 185<blockquote> 186<pre> 187% make -f Makefile.init makefiles 188</pre> 189</blockquote> 190 191<p> If you copied the Postfix source code after building it on another 192machine, it is a good idea to cd into the top-level directory and 193first do this:</p> 194 195<blockquote> 196<pre> 197% make tidy 198</pre> 199</blockquote> 200 201<p> This will get rid of any system dependencies left over from 202compiling the software elsewhere. </p> 203 204<h3>4.2 - What compiler to use</h3> 205 206<p> To build with GCC, or with the native compiler if people told me 207that is better for your system, just cd into the top-level Postfix 208directory of the source tree and type: </p> 209 210<blockquote> 211<pre> 212% make 213</pre> 214</blockquote> 215 216<p> To build with a non-default compiler, you need to specify the name 217of the compiler. Here are a few examples: </p> 218 219<blockquote> 220<pre> 221% make makefiles CC=/opt/SUNWspro/bin/cc (Solaris) 222% make 223 224% make makefiles CC="/opt/ansic/bin/cc -Ae" (HP-UX) 225% make 226 227% make makefiles CC="purify cc" 228% make 229</pre> 230</blockquote> 231 232<p> and so on. In some cases, optimization is turned off automatically. </p> 233 234<h3>4.3 - Building with optional extensions</h3> 235 236By default, Postfix builds as a mail system with relatively few 237bells and whistles. Support for third-party databases etc. 238must be configured when Postfix is compiled. The following documents describe how to build Postfix with support for extensions: 239 240<blockquote> 241<table border="1"> 242 243<tr> <th>Postfix extension </th> <th>Document </th> <th>Availability</th> 244</tr> 245 246<tr> <td> Berkeley DB database</td> <td>DB_README</td> <td> Postfix 2471.0 </td> </tr> 248 249<tr> <td> LDAP database</td> <td>LDAP_README</td> <td> Postfix 2501.0 </td> </tr> 251 252<tr> <td> MySQL database</td> <td>MYSQL_README</td> <td> Postfix 2531.0 </td> </tr> 254 255<tr> <td> Perl compatible regular expression</td> <td>PCRE_README</td> 256<td> Postfix 1.0 </td> </tr> 257 258<tr> <td> PostgreSQL database</td> <td>PGSQL_README</td> <td> 259Postfix 2.0 </td> </tr> 260 261<tr> <td> SASL authentication </td> <td>SASL_README</td> <td> 262Postfix 1.0 </td> </tr> 263 264<tr> <td> STARTTLS session encryption </td> <td>TLS_README</td> <td> 265Postfix 2.2 </td> </tr> 266 267</table> 268 269</blockquote> 270 271<p> Note: IP version 6 support is compiled into Postfix on operating 272systems that have IPv6 support. See the IPV6_README file for details. 273</p> 274 275<h3>4.4 - Overriding built-in parameter default settings</h3> 276 277<p> All Postfix configuration parameters can be changed by editing 278a Postfix configuration file, except for one: the parameter that 279specifies the location of Postfix configuration files. In order to 280build Postfix with a configuration directory other than /etc/postfix, 281use: </p> 282 283<blockquote> 284<pre> 285% make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"' 286% make 287</pre> 288</blockquote> 289 290<p> IMPORTANT: Be sure to get the quotes right. These details matter 291a lot. </p> 292 293<p> Parameters whose defaults can be specified in this way are: </p> 294 295<blockquote> 296 297<table border="1"> 298 299<tr><th> Macro name </th> <th>default value for</th> <th>typical 300default</th> </tr> 301 302<tr> <td>DEF_COMMAND_DIR</td> <td>command_directory</td> 303<td>/usr/sbin</td> </tr> 304 305<tr> <td>DEF_CONFIG_DIR</td> <td>config_directory</td> 306<td>/etc/postfix</td> </tr> 307 308<tr> <td>DEF_DAEMON_DIR</td> <td>daemon_directory</td> 309<td>/usr/libexec/postfix</td> </tr> 310 311<tr> <td>DEF_DATA_DIR</td> <td>data_directory</td> 312<td>/var/db/postfix</td> </tr> 313 314<tr> <td>DEF_MAILQ_PATH</td> <td>mailq_path</td> <td>/usr/bin/mailq</td> 315</tr> 316 317<tr> <td>DEF_HTML_DIR</td> <td>html_directory</td> 318<td>no</td> </tr> 319 320<tr> <td>DEF_MANPAGE_DIR</td> <td>manpage_directory</td> 321<td>/usr/local/man</td> </tr> 322 323<tr> <td>DEF_NEWALIAS_PATH</td> <td>newaliases_path</td> 324<td>/usr/bin/newaliases</td> </tr> 325 326<tr> <td>DEF_QUEUE_DIR</td> <td>queue_directory</td> 327<td>/var/spool/postfix</td> </tr> 328 329<tr> <td>DEF_README_DIR</td> <td>readme_directory</td> 330<td>no</td> </tr> 331 332<tr> <td>DEF_SENDMAIL_PATH</td> <td>sendmail_path</td> 333<td>/usr/sbin/sendmail</td> </tr> 334 335</table> 336 337</blockquote> 338 339<p> Note: the data_directory parameter (for caches and pseudo-random 340numbers) was introduced with Postfix version 2.5. </p> 341 342<h3>4.5 - Support for thousands of processes</h3> 343 344<p> The number of connections that Postfix can manage simultaneously 345is limited by the number of processes that it can run. This number 346in turn is limited by the number of files and sockets that a single 347process can open. For example, the Postfix queue manager has a 348separate connection to each delivery process, and the anvil(8) 349server has one connection per smtpd(8) process. </p> 350 351<p> Postfix version 2.4 and later have no built-in limits on the 352number of open files or sockets, when compiled on systems that 353support one of the following: </p> 354 355<ul> 356 357<li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), 358 359<li> Solaris 8 /dev/poll, 360 361<li> Linux 2.6 epoll(4). 362 363</ul> 364 365 366<p> With other Postfix versions or operating systems, the number 367of file descriptors per process is limited by the value of the 368FD_SETSIZE macro. If you expect to run more than 1000 mail delivery 369processes, you may need to override the definition of the FD_SETSIZE 370macro to make select() work correctly: </p> 371 372<blockquote> 373<pre> 374% make makefiles CCARGS=-DFD_SETSIZE=2048 375</pre> 376</blockquote> 377 378<p> Warning: the above has no effect on some Linux versions. 379Apparently, on these systems the FD_SETSIZE value can be changed 380only by using undocumented interfaces. Currently, that means 381including <bits/types.h> directly (which is not allowed) and 382overriding the __FD_SETSIZE macro. Beware, undocumented interfaces 383can change at any time and without warning. </p> 384 385<p> But wait, there is more: none of this will work unless the 386operating system is configured to handle thousands of connections. 387See the TUNING_README guide for examples of how to increase the 388number of open sockets or files. </p> 389 390<h3>4.6 - Compiling Postfix, at last</h3> 391 392<p> If the command </p> 393 394<blockquote> 395<pre> 396% make 397</pre> 398</blockquote> 399 400<p> is successful, then you can proceed to <a href="#install">install</a> 401Postfix (section 6). 402 403<p> If the command produces compiler error messages, it may be time 404to search the web or to ask the postfix-users@postfix.org mailing 405list, but be sure to search the mailing list archives first. Some 406mailing list archives are linked from http://www.postfix.org/. </p> 407 408<h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2> 409 410<p> Each system type that Postfix knows is identified by a unique 411name. Examples: SUNOS5, FREEBSD4, and so on. When porting Postfix 412to a new system, the first step is to choose a SYSTEMTYPE name for 413the new system. You must use a name that includes at least the 414major version of the operating system (such as SUNOS4 or LINUX2), 415so that different releases of the same system can be supported 416without confusion. </p> 417 418<p> Add a case statement to the "makedefs" shell script in the 419source code top-level directory that recognizes the new system 420reliably, and that emits the right system-specific information. 421Be sure to make the code robust against user PATH settings; if the 422system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to 423build for the native flavor, instead of the emulated one. </p> 424 425<p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h 426include file. You may have to invent new feature macro names. 427Please choose sensible feature macro names such as HAS_DBM or 428FIONREAD_IN_SYS_FILIO_H. 429 430<p> I strongly recommend against using "#ifdef SYSTEMTYPE" in 431individual source files. While this may look like the quickest 432solution, it will create a mess when newer versions of the same 433SYSTEMTYPE need to be supported. You're likely to end up placing 434"#ifdef" sections all over the source code again. </p> 435 436<h2><a name="install">6 - Installing the software after successful 437compilation</a></h2> 438 439<p> This text describes how to install Postfix from source code. 440See the PACKAGE_README file if you are building a package for 441distribution to other systems. </p> 442 443<h3>6.1 - Save existing Sendmail binaries</h3> 444 445<p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing 446Sendmail installation with Postfix, you may need to keep the old 447sendmail program running for some time in order to flush the mail 448queue. </p> 449 450<ul> 451 452<li> <p> Some systems implement a mail switch mechanism where 453different MTAs (Postfix, Sendmail, etc.) can be installed at the 454same time, while only one of them is actually being used. Examples 455of such switching mechanisms are the FreeBSD mailwrapper(8) or the 456Linux mail switch. In this case you should try to "flip" the switch 457to "Postfix" before installing Postfix. </p> 458 459<li> <p> If your system has no mail switch mechanism, execute the 460following commands (your sendmail, newaliases and mailq programs 461may be in a different place): </p> 462 463<pre> 464# mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF 465# mv /usr/bin/newaliases /usr/bin/newaliases.OFF 466# mv /usr/bin/mailq /usr/bin/mailq.OFF 467# chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ 468 /usr/bin/mailq.OFF 469</pre> 470 471</ul> 472 473<h3>6.2 - Create account and groups</h3> 474 475<p> Before you install Postfix for the first time you need to 476create an account and a group:</p> 477 478<ul> 479 480<li> <p> Create a user account "postfix" with a user id and group 481id that are not used by any other user account. Preferably, this 482is an account that no-one can log into. The account does not need 483an executable login shell, and needs no existing home directory. 484My password and group file entries look like this: </p> 485 486<blockquote> 487<pre> 488/etc/passwd: 489 postfix:*:12345:12345:postfix:/no/where:/no/shell 490 491/etc/group: 492 postfix:*:12345: 493</pre> 494</blockquote> 495 496<p> Note: there should be no whitespace before "postfix:". </p> 497 498<li> <p> Create a group "postdrop" with a group id that is not used 499by any other user account. Not even by the postfix user account. 500My group file entry looks like: 501 502<blockquote> 503<pre> 504/etc/group: 505 postdrop:*:54321: 506</pre> 507</blockquote> 508 509<p> Note: there should be no whitespace before "postdrop:". </p> 510 511</ul> 512 513<h3>6.3 - Install Postfix</h3> 514 515<p> To install or upgrade Postfix from compiled source code, run 516one of the following commands as the super-user:</p> 517 518<blockquote> 519<pre> 520# make install (interactive version, first time install) 521 522# make upgrade (non-interactive version, for upgrades) 523</pre> 524</blockquote> 525 526<ul> 527 528<li> <p> The interactive version ("make install") asks for pathnames 529for Postfix data and program files, and stores your preferences in 530the main.cf file. <b> If you don't want Postfix to overwrite 531non-Postfix "sendmail", "mailq" and "newaliases" files, specify 532pathnames that end in ".postfix"</b>. </p> 533 534<li> <p> The non-interactive version ("make upgrade") needs the 535/etc/postfix/main.cf file from a previous installation. If the file 536does not exist, use interactive installation ("make install") 537instead. </p> 538 539</ul> 540 541<h3>6.4 - Configure Postfix</h3> 542 543<p> Proceed to the section on how you wish to run Postfix on 544your particular machine: </p> 545 546<ul> 547 548<li> <p> <a href="#send_only">Send</a> mail only, without changing 549an existing Sendmail installation (section 7). </p> 550 551<li> <p> <a href="#send_receive">Send and receive</a> mail via a 552virtual host interface, still without any change to an existing 553Sendmail installation (section 8). </p> 554 555<li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail 556(section 9). </p> 557 558</ul> 559 560<h2><a name="send_only">7 - Configuring Postfix to send mail 561only</a></h2> 562 563<p> If you are going to use Postfix to send mail only, there is no 564need to change your existing sendmail setup. Instead, set up your 565mail user agent so that it calls the Postfix sendmail program 566directly. </p> 567 568<p> Follow the instructions in the "<a href="#mandatory">Mandatory 569configuration file edits</a>" in section 10, and review the "<a 570href="#hamlet">To chroot or not to chroot</a>" text in section 57111. </p> 572 573<p> You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, 574in order to avoid conflicts with the real sendmail. Put a "#" 575character in front of the line that defines the smtpd service: </p> 576 577<blockquote> 578<pre> 579/etc/postfix/master.cf: 580 #smtp inet n - n - - smtpd 581</pre> 582</blockquote> 583 584<p> Start the Postfix system: </p> 585 586<blockquote> 587<pre> 588# postfix start 589</pre> 590</blockquote> 591 592<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 593 594<blockquote> 595<pre> 596# sendmail -bd -qwhatever 597</pre> 598</blockquote> 599 600<p> and watch your maillog file for any error messages. The pathname 601is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 602else. Typically, the pathname is defined in the /etc/syslog.conf 603file. </p> 604 605<blockquote> 606<pre> 607% egrep '(reject|warning|error|fatal|panic):' /some/log/file 608</pre> 609</blockquote> 610 611<p> Note: the most important error message is logged first. Later 612messages are not as useful. </p> 613 614<p> In order to inspect the mail queue, use one of the following 615commands: </p> 616 617<blockquote> 618<pre> 619% mailq 620 621% sendmail -bp 622 623% postqueue -p 624</pre> 625</blockquote> 626 627<p> See also the "<a href="#care">Care and feeding</a>" section 12 628below. </p> 629 630<h2><a name="send_receive">8 - Configuring Postfix to send and 631receive mail via virtual interface</a></h2> 632 633<p> Alternatively, you can use the Postfix system to send AND 634receive mail while leaving your Sendmail setup intact, by running 635Postfix on a virtual interface address. Simply configure your mail 636user agent to directly invoke the Postfix sendmail program. </p> 637 638<p> To create a virtual network interface address, study your 639system ifconfig manual page. The command syntax could be any 640of: </p> 641 642<blockquote> 643<pre> 644# <b>ifconfig le0:1 <address> netmask <mask> up</b> 645# <b>ifconfig en0 alias <address> netmask 255.255.255.255</b> 646</pre> 647</blockquote> 648 649<p> In the /etc/postfix/main.cf file, I would specify </p> 650 651<blockquote> 652<pre> 653/etc/postfix/main.cf: 654 myhostname = virtual.host.tld 655 inet_interfaces = $myhostname 656 mydestination = $myhostname 657</pre> 658</blockquote> 659 660<p> Follow the instructions in the "<a href="#mandatory">Mandatory 661configuration file edits</a>" in section 10, and review the "<a 662name="#hamlet">To chroot or not to chroot</a>" text in section 66311. </p> 664 665<p> Start the Postfix system: </p> 666 667<blockquote> 668<pre> 669# postfix start 670</pre> 671</blockquote> 672 673<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 674 675<blockquote> 676<pre> 677# sendmail -bd -qwhatever 678</pre> 679</blockquote> 680 681<p> and watch your maillog file for any error messages. The pathname 682is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 683else. Typically, the pathname is defined in the /etc/syslog.conf 684file. </p> 685 686<blockquote> 687<pre> 688% egrep '(reject|warning|error|fatal|panic):' /some/log/file 689</pre> 690</blockquote> 691 692<p> Note: the most important error message is logged first. Later 693messages are not as useful. </p> 694 695<p> In order to inspect the mail queue, use one of the following 696commands: </p> 697 698<blockquote> 699<pre> 700% mailq 701 702% sendmail -bp 703 704% postqueue -p 705</pre> 706</blockquote> 707 708<p> See also the "<a href="#care">Care and feeding</a>" section 12 709below. </p> 710 711<h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2> 712 713<p> Prior to installing Postfix you should <a href="#save">save</a> 714any existing sendmail program files as described in section 6. Be 715sure to keep the old sendmail running for at least a couple days 716to flush any unsent mail. To do so, stop the sendmail daemon and 717restart it as: </p> 718 719<blockquote> 720<pre> 721# /usr/sbin/sendmail.OFF -q 722</pre> 723</blockquote> 724 725<p> Note: this is old sendmail syntax. Newer versions use separate 726processes for mail submission and for running the queue. </p> 727 728<p> After you have visited the "<a href="#mandatory">Mandatory 729configuration file edits</a>" section below, you can start the 730Postfix system with: </p> 731 732<blockquote> 733<pre> 734# postfix start 735</pre> 736</blockquote> 737 738<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 739 740<blockquote> 741<pre> 742# sendmail -bd -qwhatever 743</pre> 744</blockquote> 745 746<p> and watch your maillog file for any error messages. The pathname 747is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 748else. Typically, the pathname is defined in the /etc/syslog.conf 749file. </p> 750 751<blockquote> 752<pre> 753% egrep '(reject|warning|error|fatal|panic):' /some/log/file 754</pre> 755</blockquote> 756 757<p> Note: the most important error message is logged first. Later 758messages are not as useful. </p> 759 760<p> In order to inspect the mail queue, use one of the following 761commands: </p> 762 763<blockquote> 764<pre> 765% mailq 766 767% sendmail -bp 768 769% postqueue -p 770</pre> 771</blockquote> 772 773<p> See also the "<a href="#care">Care and feeding</a>" section 12 774below. </p> 775 776<h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2> 777 778<p> Note: the material covered in this section is covered in more 779detail in the BASIC_CONFIGURATION_README document. The information 780presented below is targeted at experienced system administrators. 781</p> 782 783<h3>10.1 - Postfix configuration files</h3> 784 785<p> By default, Postfix configuration files are in /etc/postfix. 786The two most important files are main.cf and master.cf; these files 787must be owned by root. Giving someone else write permission to 788main.cf or master.cf (or to their parent directories) means giving 789root privileges to that person. </p> 790 791<p> In /etc/postfix/main.cf, you will have to set up a minimal number 792of configuration parameters. Postfix configuration parameters 793resemble shell variables, with two important differences: the first 794one is that Postfix does not know about quotes like the UNIX shell 795does.</p> 796 797<p> You specify a configuration parameter as: </p> 798 799<blockquote> 800<pre> 801/etc/postfix/main.cf: 802 parameter = value 803</pre> 804</blockquote> 805 806<p> and you use it by putting a "$" character in front of its name: </p> 807 808<blockquote> 809<pre> 810/etc/postfix/main.cf: 811 other_parameter = $parameter 812</pre> 813</blockquote> 814 815<p> You can use $parameter before it is given a value (that is the 816second main difference with UNIX shell variables). The Postfix 817configuration language uses lazy evaluation, and does not look at 818a parameter value until it is needed at runtime. </p> 819 820<p> Whenever you make a change to the main.cf or master.cf file, 821execute the following command in order to refresh a running mail 822system: </p> 823 824<blockquote> 825<pre> 826# postfix reload 827</pre> 828</blockquote> 829 830<h3>10.2 - Default domain for unqualified addresses</h3> 831 832<p> First of all, you must specify what domain will be appended to an 833unqualified address (i.e. an address without @domain.tld). The 834"myorigin" parameter defaults to the local hostname, but that is 835probably OK only for very small sites. </p> 836 837<p> Some examples (use only one): </p> 838 839<blockquote> 840<pre> 841/etc/postfix/main.cf: 842 myorigin = $myhostname (send mail as "user@$myhostname") 843 myorigin = $mydomain (send mail as "user@$mydomain") 844</pre> 845</blockquote> 846 847<h3>10.3 - What domains to receive locally</h3> 848 849<p> Next you need to specify what mail addresses Postfix should deliver 850locally. </p> 851 852<p> Some examples (use only one): </p> 853 854<blockquote> 855<pre> 856/etc/postfix/main.cf: 857 mydestination = $myhostname, localhost.$mydomain, localhost 858 mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain 859 mydestination = $myhostname 860</pre> 861</blockquote> 862 863<p>The first example is appropriate for a workstation, the second 864is appropriate for the mailserver for an entire domain. The third 865example should be used when running on a virtual host interface.</p> 866 867<h3>10.4 - Proxy/NAT interface addresses </h3> 868 869<p> The proxy_interfaces parameter specifies all network addresses 870that Postfix receives mail on by way of a proxy or network address 871translation unit. You may specify symbolic hostnames instead of 872network addresses. </p> 873 874<p> IMPORTANT: You must specify your proxy/NAT external addresses 875when your system is a backup MX host for other domains, otherwise 876mail delivery loops will happen when the primary MX host is down. 877</p> 878 879<p> Example: host behind NAT box running a backup MX host. </p> 880 881<blockquote> 882<pre> 883/etc/postfix/main.cf: 884 proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) 885</pre> 886</blockquote> 887 888<h3>10.5 - What local clients to relay mail from </h3> 889 890<p> If your machine is on an open network then you must specify 891what client IP addresses are authorized to relay their mail through 892your machine into the Internet. The default setting includes all 893subnetworks that the machine is attached to. This may give relay 894permission to too many clients. My own settings are: </p> 895 896<blockquote> 897<pre> 898/etc/postfix/main.cf: 899 mynetworks = 168.100.189.0/28, 127.0.0.0/8 900</pre> 901</blockquote> 902 903<h3>10.6 - What relay destinations to accept from strangers </h3> 904 905<p> If your machine is on an open network then you must also specify 906whether Postfix will forward mail from strangers. The default 907setting will forward mail to all domains (and subdomains of) what 908is listed in $mydestination. This may give relay permission for 909too many destinations. Recommended settings (use only one): </p> 910 911<blockquote> 912<pre> 913/etc/postfix/main.cf: 914 relay_domains = (do not forward mail from strangers) 915 relay_domains = $mydomain (my domain and subdomains) 916 relay_domains = $mydomain, other.domain.tld, ... 917</pre> 918</blockquote> 919 920<h3>10.7 - Optional: configure a smart host for remote delivery</h3> 921 922<p> If you're behind a firewall, you should set up a relayhost. If 923you can, specify the organizational domain name so that Postfix 924can use DNS lookups, and so that it can fall back to a secondary 925MX host when the primary MX host is down. Otherwise just specify 926a hard-coded hostname. </p> 927 928<p> Some examples (use only one): </p> 929 930<blockquote> 931<pre> 932/etc/postfix/main.cf: 933 relayhost = $mydomain 934 relayhost = [mail.$mydomain] 935</pre> 936</blockquote> 937 938<p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p> 939 940<p> By default, the SMTP client will do DNS lookups even when you 941specify a relay host. If your machine has no access to a DNS server, 942turn off SMTP client DNS lookups like this: </p> 943 944<blockquote> 945<pre> 946/etc/postfix/main.cf: 947 disable_dns_lookups = yes 948</pre> 949</blockquote> 950 951<p> The STANDARD_CONFIGURATION_README file has more hints and tips for 952firewalled and/or dial-up networks. </p> 953 954<h3>10.8 - Create the aliases database</h3> 955 956<p> Postfix uses a Sendmail-compatible aliases(5) table to redirect 957mail for local(8) recipients. Typically, this information is kept 958in two files: in a text file /etc/aliases and in an indexed file 959/etc/aliases.db. The command "postconf alias_maps" will tell you 960the exact location of the text file. </p> 961 962<p> First, be sure to update the text file with aliases for root, 963postmaster and "postfix" that forward mail to a real person. Postfix 964has a sample aliases file /etc/postfix/aliases that you can adapt 965to local conditions. </p> 966 967<blockquote> 968<pre> 969/etc/aliases: 970 root: you 971 postmaster: root 972 postfix: root 973 bin: root 974 <i>etcetera...</i> 975</pre> 976</blockquote> 977 978<p> Note: there should be no whitespace before the ":". </p> 979 980<p> Finally, build the indexed aliases file with one of the 981following commands: </p> 982 983<blockquote> 984<pre> 985# newaliases 986# sendmail -bi 987</pre> 988</blockquote> 989 990<h2><a name="hamlet">11 - To chroot or not to chroot</a></h2> 991 992<p> Postfix daemon processes can be configured (via master.cf) to 993run in a chroot jail. The processes run at a fixed low privilege 994and with access only to the Postfix queue directories (/var/spool/postfix). 995This provides a significant barrier against intrusion. The barrier 996is not impenetrable, but every little bit helps. </p> 997 998<p> With the exception of Postfix daemons that deliver mail locally 999and/or that execute non-Postfix commands, every Postfix daemon can 1000run chrooted. </p> 1001 1002<p> Sites with high security requirements should consider to chroot 1003all daemons that talk to the network: the smtp(8) and smtpd(8) 1004processes, and perhaps also the lmtp(8) client. The author's own 1005porcupine.org mail server runs all daemons chrooted that can be 1006chrooted. </p> 1007 1008<p> The default /etc/postfix/master.cf file specifies that no 1009Postfix daemon runs chrooted. In order to enable chroot operation, 1010edit the file /etc/postfix/master.cf. Instructions are in the file. 1011</p> 1012 1013<p> Note that a chrooted daemon resolves all filenames relative to 1014the Postfix queue directory (/var/spool/postfix). For successful 1015use of a chroot jail, most UNIX systems require you to bring in 1016some files or device nodes. The examples/chroot-setup directory 1017in the source code distribution has a collection of scripts that 1018help you set up Postfix chroot environments on different operating 1019systems. </p> 1020 1021<p> Additionally, you almost certainly need to configure syslogd 1022so that it listens on a socket inside the Postfix queue directory. 1023Examples for specific systems: </p> 1024 1025<dl> 1026 1027<dt> FreeBSD: </dt> 1028 1029<dd> <pre> 1030# mkdir -p /var/spool/postfix/var/run 1031# syslogd -l /var/spool/postfix/var/run/log 1032</pre> </dd> 1033 1034<dt> Linux, OpenBSD: </dt> 1035 1036<dd> <pre> 1037# mkdir -p /var/spool/postfix/dev 1038# syslogd -a /var/spool/postfix/dev/log 1039</pre> </dd> 1040 1041</dl> 1042 1043<h2><a name="care">12 - Care and feeding of the Postfix system</a></h2> 1044 1045<p> Postfix daemon processes run in the background, and log problems 1046and normal activity to the syslog daemon. The names of logfiles 1047are specified in /etc/syslog.conf. At the very least you need 1048something like: </p> 1049 1050<blockquote> 1051<pre> 1052/etc/syslog.conf: 1053 mail.err /dev/console 1054 mail.debug /var/log/maillog 1055</pre> 1056</blockquote> 1057 1058<p> IMPORTANT: the syslogd will not create files. You must create 1059them before (re)starting syslogd. </p> 1060 1061<p> IMPORTANT: on Linux you need to put a "-" character before 1062the pathname, e.g., -/var/log/maillog, otherwise the syslogd 1063will use more system resources than Postfix does. </p> 1064 1065<p> Hopefully, the number of problems will be small, but it is a good 1066idea to run every night before the syslog files are rotated: </p> 1067 1068<blockquote> 1069<pre> 1070# postfix check 1071# egrep '(reject|warning|error|fatal|panic):' /some/log/file 1072</pre> 1073</blockquote> 1074 1075<ul> 1076 1077<li> <p> The first line (postfix check) causes Postfix to report 1078file permission/ownership discrepancies. </p> 1079 1080<li> <p> The second line looks for problem reports from the mail 1081software, and reports how effective the relay and junk mail access 1082blocks are. This may produce a lot of output. You will want to 1083apply some postprocessing to eliminate uninteresting information. 1084</p> 1085 1086</ul> 1087 1088<p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a> 1089document describes the meaning of the "warning" etc. labels in 1090Postfix logging. </p> 1091 1092</body> 1093 1094</html> 1095