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