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=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 18Installation From Source Code </h1> 19 20<hr> 21 22<h2> <a name="1">1 - Purpose of this document</a> </h2> 23 24<p> If you are using a pre-compiled version of Postfix, you should 25start with BASIC_CONFIGURATION_README and the general documentation 26referenced by it. INSTALL is only a bootstrap document to get 27Postfix up and running from scratch with the minimal number of 28steps; it should not be considered part of the general documentation. 29</p> 30 31<p> This document describes how to build, install and configure a 32Postfix system so that it can do one of the following: </p> 33 34<ul> 35 36<li> Send mail only, without changing an existing Sendmail 37installation. 38 39<li> Send and receive mail via a virtual host interface, still 40without any change to an existing Sendmail installation. 41 42<li> Run Postfix instead of Sendmail. 43 44</ul> 45 46<p> Topics covered in this document: </p> 47 48<ol> 49 50<li> <a href="#1">Purpose of this document</a> 51 52<li> <a href="#2">Typographical conventions</a> 53 54<li> <a href="#3">Documentation</a> 55 56<li> <a href="#4">Building on a supported system</a> 57 58<li> <a href="#5">Porting Postfix to an unsupported system</a> 59 60<li> <a href="#install">Installing the software after successful 61compilation </a> 62 63<li> <a href="#send_only">Configuring Postfix to send mail 64only </a> 65 66<li> <a href="#send_receive">Configuring Postfix to send and 67receive mail via virtual interface </a> 68 69<li> <a href="#replace">Running Postfix instead of Sendmail</a> 70 71<li> <a href="#mandatory">Mandatory configuration file edits</a> 72 73<li> <a href="#hamlet">To chroot or not to chroot</a> 74 75<li> <a href="#care">Care and feeding of the Postfix system</a> 76 77</ol> 78 79<h2> <a name="2">2 - Typographical conventions</a> </h2> 80 81<p> In the instructions below, a command written as </p> 82 83<blockquote> 84<pre> 85# command 86</pre> 87</blockquote> 88 89<p> should be executed as the superuser. </p> 90 91<p> A command written as </p> 92 93<blockquote> 94<pre> 95$ command 96</pre> 97</blockquote> 98 99<p> should be executed as an unprivileged user. </p> 100 101<h2> <a name="3">3 - Documentation</a> </h2> 102 103<p> Documentation is available as README files (start with the file 104README_FILES/AAAREADME), as HTML web pages (point your browser to 105"html/index.html") and as UNIX-style manual pages. </p> 106 107<p> You should view the README files with a pager such as more(1) 108or less(1), because the files use backspace characters in order to 109produce <b>bold</b> font. To print a README file without backspace 110characters, use the col(1) command. For example: </p> 111 112<blockquote> 113<pre> 114$ col -bx <file | lpr 115</pre> 116</blockquote> 117 118<p> In order to view the manual pages before installing Postfix, 119point your MANPATH environment variable to the "man" subdirectory; 120be sure to use an absolute path. </p> 121 122<blockquote> 123<pre> 124$ export MANPATH; MANPATH="`pwd`/man:$MANPATH" 125$ setenv MANPATH "`pwd`/man:$MANPATH" 126</pre> 127</blockquote> 128 129<p> Of particular interest is the postconf(5) manual page that 130lists all the 500+ configuration parameters. The HTML version of 131this text makes it easy to navigate around. </p> 132 133<p> All Postfix source files have their own built-in manual page. 134Tools to extract those embedded manual pages are available in the 135mantools directory. </p> 136 137<h2> <a name="4">4 - Building on a supported system</a> </h2> 138 139<p> Postfix development happens on FreeBSD and MacOS X, with regular 140tests on Linux (Fedora, Ubuntu) and Solaris. Support for other 141systems relies on feedback from their users, and may not always be 142up-to-date. </p> 143 144<p> OpenBSD is partially supported. The libc resolver does not 145implement the documented "internal resolver options which are [...] 146set by changing fields in the _res structure" (documented in the 147OpenBSD 5.6 resolver(3) manpage). This results in too many DNS 148queries, and false positives for queries that should fail. </p> 149 150<!-- 151 152<p> At some point in time, a version of Postfix was supported on: </p> 153 154<blockquote> 155<p> 156AIX 3.2.5, 4.1.x, 4.2.0, 4.3.x, 5.2 <br> 157BSD/OS 2.x, 3.x, 4.x <br> 158FreeBSD 2.x .. 9.x <br> 159HP-UX 9.x, 10.x, 11.x <br> 160IRIX 5.x, 6.x <br> 161Linux Debian 1.3.1 and later <br> 162Linux RedHat 3.x (January 2004) and later <br> 163Linux Slackware 3.x and later <br> 164Linux SuSE 5.x and later <br> 165Linux Ubuntu 4.10 and later<br> 166Mac OS X <br> 167NEXTSTEP 3.x <br> 168NetBSD 1.x and later <br> 169OPENSTEP 4.x <br> 170OSF1.V3 - OSF1.V5 (Digital UNIX) <br> 171Reliant UNIX 5.x <br> 172SunOS 4.1.4 (March 2007) <br> 173SunOS 5.4 - 5.10 (Solaris 2.4..10) <br> 174Ultrix 4.x (well, that was long ago) <br> 175</p> 176</blockquote> 177 178<p> or something closely resemblant. </p> 179 180--> 181 182<p> Overview of topics: </p> 183 184<ul> 185 186<li><a href="#build_first">4.1 - Getting started</a> 187 188<li><a href="#build_cc">4.2 - What compiler to use</a> 189 190<li><a href="#build_pie">4.3 - Building with Postfix position-independent 191executables (Postfix ≥ 3.0)</a> 192 193<li><a href="#build_dll">4.4 - Building with Postfix dynamically-linked 194libraries and database plugins (Postfix ≥ 3.0)</a> 195 196<li><a href="#build_opt">4.5 - Building with optional features</a> 197 198<li><a href="#build_over">4.6 - Overriding built-in parameter default 199settings</a> 200 201<li><a href="#build_other">4.7 - Overriding other compile-time 202features</a> 203 204<li><a href="#build_proc">4.8 - Support for thousands of processes</a> 205 206<li><a href="#build_final">4.9 - Compiling Postfix, at last</a> 207 208</ul> 209 210 211<h3><a name="build_first">4.1 - Getting started</a> </h3> 212 213<p> On Solaris, the "make" command and other development utilities 214are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in your command 215search path. If these files do not exist, you need to install the 216development packages first. </p> 217 218<p> If you need to build Postfix for multiple architectures from a 219single source-code tree, use the "lndir" command to build a shadow 220tree with symbolic links to the source files. </p> 221 222<p> If at any time in the build process you get messages like: "make: 223don't know how to ..." you should be able to recover by running 224the following command from the Postfix top-level directory: </p> 225 226<blockquote> 227<pre> 228$ make -f Makefile.init makefiles 229</pre> 230</blockquote> 231 232<p> If you copied the Postfix source code after building it on another 233machine, it is a good idea to cd into the top-level directory and 234first do this:</p> 235 236<blockquote> 237<pre> 238$ make tidy 239</pre> 240</blockquote> 241 242<p> This will get rid of any system dependencies left over from 243compiling the software elsewhere. </p> 244 245<h3><a name="build_cc">4.2 - What compiler to use</a></h3> 246 247<p> To build with GCC, or with the native compiler if people told me 248that is better for your system, just cd into the top-level Postfix 249directory of the source tree and type: </p> 250 251<blockquote> 252<pre> 253$ make 254</pre> 255</blockquote> 256 257<p> To build with a non-default compiler, you need to specify the name 258of the compiler. Here are a few examples: </p> 259 260<blockquote> 261<pre> 262$ make makefiles CC=/opt/SUNWspro/bin/cc (Solaris) 263$ make 264 265$ make makefiles CC="/opt/ansic/bin/cc -Ae" (HP-UX) 266$ make 267 268$ make makefiles CC="purify cc" 269$ make 270</pre> 271</blockquote> 272 273<p> and so on. In some cases, optimization will be turned off 274automatically. </p> 275 276<h3><a name="build_pie">4.3 - Building with Postfix position-independent 277executables (Postfix ≥ 3.0)</a> </h3> 278 279<p> On some systems Postfix can be built with Position-Independent 280Executables. PIE is used by the ASLR exploit mitigation technique 281(ASLR = Address-Space Layout Randomization): </p> 282 283<blockquote> 284<pre> 285$ make makefiles pie=yes ...other arguments... 286</pre> 287</blockquote> 288 289<p> (Specify "make makefiles pie=no" to explicitly disable Postfix 290position-independent executable support). </p> 291 292<p> Postfix PIE support appears to work on Fedora Core 20, Ubuntu 29314.04, FreeBSD 9 and 10, and NetBSD 6 (all with the default system 294compilers). </p> 295 296<p> Whether the "pie=yes" above has any effect depends on the 297compiler. Some compilers always produce PIE executables, and some 298may even complain that the Postfix build option is redundant. </p> 299 300<h3><a name="build_dll">4.4 - Building with Postfix dynamically-linked 301libraries and database plugins (Postfix ≥ 3.0)</a> </h3> 302 303<p> Postfix dynamically-linked library and database plugin support 304exists for recent versions of Linux, FreeBSD and MacOS X. 305Dynamically-linked library builds may become the default at some 306point in the future. </p> 307 308<p> Overview of topics: </p> 309 310<ul> 311 312<li><a href="#shared_enable">4.4.1 Turning on Postfix dynamically-linked 313library support</a> 314 315<li><a href="#dynamicmaps_enable">4.4.2 Turning on Postfix database-plugin 316support</a> 317 318<li><a href="#shared_custom">4.4.3 Customizing Postfix dynamically-linked 319libraries and database plugins</a> 320 321<li><a href="#shared_tips">4.4.4 Tips for distribution maintainers</a> 322 323</ul> 324 325<p> Note: directories with Postfix dynamically-linked libraries 326or database plugins should contain only postfix-related files. 327Postfix dynamically-linked libraries and database plugins should 328not be installed in a "public" system directory such as /usr/lib 329or /usr/local/lib. Linking Postfix dynamically-linked library or 330database-plugin files into non-Postfix programs is not supported. 331Postfix dynamically-linked libraries and database plugins implement 332a Postfix-internal API that changes without maintaining compatibility. 333</p> 334 335<h4><a name="shared_enable"> 4.4.1 Turning on Postfix dynamically-linked 336library support </a></h4> 337 338<p> Postfix can be built with Postfix dynamically-linked libraries 339(files typically named <tt>libpostfix-*.so</tt>). Postfix 340dynamically-linked libraries add minor run-time overhead and result 341in significantly-smaller Postfix executable files. </p> 342 343<p> Specify "shared=yes" on the "make makefiles" command line to 344build Postfix with dynamically-linked library support. </p> 345 346<blockquote> 347<pre> 348$ make makefiles shared=yes ...other arguments... 349$ make 350</pre> 351</blockquote> 352 353<p> (Specify "make makefiles shared=no" to explicitly disable Postfix 354dynamically-linked library support). </p> 355 356<p> This installs dynamically-linked libraries in $shlib_directory, 357typically /usr/lib/postfix or /usr/local/lib/postfix, with file 358names libpostfix-<i>name</i>.so, where the <i>name</i> is a source-code 359directory name such as "util" or "global". </p> 360 361<p> See section 4.4.3 "<a href="#shared_custom">Customizing Postfix 362dynamically-linked libraries and database plugins</a>" below for 363how to customize the Postfix dynamically-linked library location, 364including support to upgrade a running mail system safely. </p> 365 366<h4><a name="dynamicmaps_enable"> 4.4.2 Turning on Postfix 367database-plugin support </a></h4> 368 369<p> Additionally, Postfix can be built to support dynamic loading 370of Postfix database clients (database plugins) with the Debian-style 371dynamicmaps feature. Postfix 3.0 supports dynamic loading of cdb:, 372ldap:, lmdb:, mysql:, pcre:, pgsql:, sdbm:, and sqlite: database 373clients. Dynamic loading is useful when you distribute or install 374pre-compiled Postfix packages. </p> 375 376<p> Specify "dynamicmaps=yes" on the "make makefiles" command line 377to build Postfix with support to dynamically load Postfix database 378clients with the Debian-style dynamicmaps feature. 379</p> 380 381<blockquote> 382<pre> 383$ make makefiles dynamicmaps=yes ...other arguments... 384$ make 385</pre> 386</blockquote> 387 388<p> (Specify "make makefiles dynamicmaps=no" to explicitly disable 389Postfix database-plugin support). </p> 390 391<p> This implicitly enables dynamically-linked library support, 392installs the configuration file dynamicmaps.cf in $meta_directory 393(usually, /etc/postfix or /usr/local/etc/postfix), and installs 394database plugins in $shlib_directory (see above). Database plugins 395are named postfix-<i>type</i>.so where the <i>type</i> is a database 396type such as "cdb" or "ldap". </p> 397 398<blockquote> 399 400<p> NOTE: The Postfix 3.0 build procedure expects that you specify 401database library dependencies with variables named AUXLIBS_CDB, 402AUXLIBS_LDAP, etc. With Postfix 3.0 and later, the old AUXLIBS 403variable still supports building a statically-loaded database client, 404but only the new AUXLIBS_CDB etc. variables support building a 405dynamically-loaded or statically-loaded CDB etc. database client. 406See CDB_README, LDAP_README, etc. for details. </p> 407 408<p> Failure to follow this advice will defeat the purpose of dynamic 409database client loading. Every Postfix executable file will have 410database library dependencies. And that was exactly what dynamic 411database client loading was meant to avoid. </p> 412 413</blockquote> 414 415<p> See the next section for how to customize the location and 416version of Postfix database plugins and the location of the file 417dynamicmaps.cf. </p> 418 419<h4><a name="shared_custom"> 4.4.3 Customizing Postfix dynamically-linked 420libraries and database plugins </a></h4> 421 422<h5> Customizing build-time and run-time options for Postfix 423dynamically-linked libraries and database plugins </h5> 424 425<p> The build-time environment variables SHLIB_CFLAGS, SHLIB_RPATH, 426and SHLIB_SUFFIX provide control over how Postfix libraries and 427plugins are compiled, linked, and named. 428 429<blockquote> 430<pre> 431$ make makefiles SHLIB_CFLAGS=flags SHLIB_RPATH=rpath SHLIB_SUFFIX=suffix ...other arguments... 432$ make 433</pre> 434</blockquote> 435 436<p> See section 4.7 "<a href="#build_other">Overriding other 437compile-time features</a>" below for details. </p> 438 439<h5> Customizing the location of Postfix dynamically-linked libraries 440and database plugins </h5> 441 442<p> As a reminder, the directories with Postfix dynamically-linked 443libraries or database plugins should contain only Postfix-related 444files. Linking these files into other programs is not supported. 445</p> 446 447<p> To override the default location of Postfix dynamically-linked 448libraries and database plugins specify, for example: </p> 449 450<blockquote> 451<pre> 452$ make makefiles shared=yes shlib_directory=/usr/local/lib/postfix ... 453</pre> 454</blockquote> 455 456<p> If you intend to upgrade Postfix without stopping the mail 457system, then you should append the Postfix release version to the 458shlib_directory pathname, to eliminate the possibility that programs 459will link with dynamically-linked libraries or database plugins 460from the wrong Postfix version. For example: </p> 461 462<blockquote> 463<pre> 464$ make makefiles shared=yes \ 465 shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 466</pre> 467</blockquote> 468 469<p> The command "make makefiles name=value..." will replace the 470string MAIL_VERSION at the end of a configuration parameter value 471with the Postfix release version. Do not try to specify something 472like $mail_version on this command line. This produces inconsistent 473results with different versions of the make(1) command. </p> 474 475<p> You can change the shlib_directory setting after Postfix is 476built, with "make install" or "make upgrade". However, you may have 477to run ldconfig if you change shlib_directory after Postfix is built 478(the symptom is that Postfix programs fail because the run-time 479linker cannot find the files libpostfix-*.so). No ldconfig command 480is needed if you keep the files libpostfix-*.so in the compiled-in 481default $shlib_directory location. </p> 482 483<blockquote> 484<pre> 485# make upgrade shlib_directory=/usr/local/lib/postfix ... 486# make install shlib_directory=/usr/local/lib/postfix ... 487</pre> 488</blockquote> 489 490<p> To append the Postfix release version to the pathname if you 491intend to upgrade Postfix without stopping the mail system: </p> 492 493<blockquote> 494<pre> 495# make upgrade shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 496# make install shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 497</pre> 498</blockquote> 499 500<p> See also the comments above for appending MAIL_VERSION with 501the "make makefiles" command. </p> 502 503<h5> Customizing the location of dynamicmaps.cf and other files 504</h5> 505 506<p> The meta_directory parameter has the same default setting as 507the config_directory parameter, typically /etc/postfix or 508/usr/local/etc/postfix. </p> 509 510<p> You can override the default meta_directory location at compile 511time or after Postfix is built. To override the default location 512at compile time specify, for example: </p> 513 514<blockquote> 515<pre> 516% make makefiles meta_directory=/usr/libexec/postfix ... 517</pre> 518</blockquote> 519 520<p> Here is a tip if you want to make a pathname dependent on the 521Postfix release version: the command "make makefiles name=value..." 522will replace the string MAIL_VERSION at the end of a configuration 523parameter value with the Postfix release version. Do not try to 524specify something like $mail_version on this command line. This 525produces inconsistent results with different versions of the make(1) 526command. </p> 527 528<p> You can override the meta_directory setting after Postfix is 529built, with "make install" or "make upgrade". </p> 530 531<blockquote> 532<pre> 533# make upgrade meta_directory=/usr/libexec/postfix ... 534# make install meta_directory=/usr/libexec/postfix ... 535</pre> 536</blockquote> 537 538<p> As with the command "make makefiles", the command "make 539install/upgrade name=value..." will replace the string MAIL_VERSION 540at the end of a configuration parameter value with the Postfix 541release version. Do not try to specify something like $mail_version 542on this command line. This produces inconsistent results with 543different versions of the make(1) command. </p> 544 545<h4><a name="shared_tips"> 4.4.4 Tips for distribution maintainers 546</a></h4> 547 548<ul> 549 550<li> <p> The shlib_directory parameter setting also provides the 551default directory for database plugin files with a relative pathname 552in the file dynamicmaps.cf. </p> 553 554<li> <p> The meta_directory parameter specifies the location of the 555files dynamicmaps.cf, postfix-files, and some multi-instance template 556files. The meta_directory parameter has the same default value as 557the config_directory parameter (typically, /etc/postfix or 558/usr/local/etc/postfix). For backwards compatibility with Postfix 5592.6 .. 2.11, specify "meta_directory = $daemon_directory" in main.cf 560before installing or upgrading Postfix, or specify "meta_directory 561= /path/name" on the "make makefiles", "make install" or "make 562upgrade" command line. </p> 563 564<li> <p> The configuration file dynamicmaps.cf will automatically 565include files under the directory dynamicmaps.cf.d, just like the 566configuration file postfix-files will automatically include files 567under the directory postfix-files.d. Thanks to this, you can install 568or deinstall a database plugin package without having to edit 569postfix-files or dynamicmaps.cf. Instead, you give that plugin its 570own configuration files under dynamicmaps.cf.d and postfix-files.d, and 571you add or remove those configuration files along with the database 572plugin dynamically-linked object. </p> 573 574<li> <p> Each configuration file under the directory dynamicmaps.cf.d 575must have the same format as the configuration file dynamicmaps.cf. 576There is no requirement that these configuration file *names* have a 577specific format. </p> 578 579<li> <p> Each configuration file under the directory postfix-files.d 580must have the same format as the configuration file postfix-files. 581There is no requirement that these configuration file *names* have a 582specific format. </p> 583 584</ul> 585 586<h3><a name="build_opt">4.5 - Building with optional features</a></h3> 587 588By default, Postfix builds as a mail system with relatively few 589bells and whistles. Support for third-party databases etc. 590must be configured when Postfix is compiled. The following documents 591describe how to build Postfix with support for optional features: 592 593<blockquote> 594<table border="1"> 595 596<tr> <th>Optional feature </th> <th>Document </th> <th>Availability</th> 597</tr> 598 599<tr> <td> Berkeley DB database</td> <td>DB_README</td> <td> Postfix 6001.0 </td> </tr> 601 602<tr> <td> LMDB database</td> <td>LMDB_README</td> <td> Postfix 6032.11 </td> </tr> 604 605<tr> <td> LDAP database</td> <td>LDAP_README</td> <td> Postfix 6061.0 </td> </tr> 607 608<tr> <td> MySQL database</td> <td>MYSQL_README</td> <td> Postfix 6091.0 </td> </tr> 610 611<tr> <td> Perl compatible regular expression</td> <td>PCRE_README</td> 612<td> Postfix 1.0 </td> </tr> 613 614<tr> <td> PostgreSQL database</td> <td>PGSQL_README</td> <td> 615Postfix 2.0 </td> </tr> 616 617<tr> <td> SASL authentication </td> <td>SASL_README</td> <td> 618Postfix 1.0 </td> </tr> 619 620<tr> <td> SQLite database</td> <td>SQLITE_README</td> <td> Postfix 6212.8 </td> </tr> 622 623<tr> <td> STARTTLS session encryption </td> <td>TLS_README</td> <td> 624Postfix 2.2 </td> </tr> 625 626</table> 627 628</blockquote> 629 630<p> Note: IP version 6 support is compiled into Postfix on operating 631systems that have IPv6 support. See the IPV6_README file for details. 632</p> 633 634<h3><a name="build_over">4.6 - Overriding built-in parameter default 635settings</a></h3> 636 637<h4>4.6.1 - Postfix 3.0 and later </h4> 638 639<p> All Postfix configuration parameters can be changed by editing 640a Postfix configuration file, except for one: the parameter that 641specifies the location of Postfix configuration files. In order to 642build Postfix with a configuration directory other than /etc/postfix, 643use: </p> 644 645<blockquote> 646<pre> 647$ make makefiles config_directory=/some/where ...other arguments... 648$ make 649</pre> 650</blockquote> 651 652<p> The command "make makefiles name=value ..." will replace the 653string MAIL_VERSION at the end of a configuration parameter value 654with the Postfix release version. Do not try to specify something 655like $mail_version on this command line. This produces inconsistent 656results with different versions of the make(1) command. </p> 657 658<p> Parameters whose defaults can be specified in this way are 659listed below. See the postconf(5) manpage for a description 660(command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 661 662<blockquote> 663 664<table border="1"> 665 666<tr> <th>parameter name</th> <th>typical default</th> </tr> 667 668<tr> <td>command_directory</td> <td>/usr/sbin</td> </tr> 669 670<tr> <td>config_directory</td> <td>/etc/postfix</td> </tr> 671 672<tr> <td>default_database_type</td> <td>hash</td> </tr> 673 674<tr> <td>daemon_directory</td> <td>/usr/libexec/postfix</td> </tr> 675 676<tr> <td>data_directory</td> <td>/var/lib/postfix</td> </tr> 677 678<tr> <td>html_directory</td> <td>no</td> </tr> 679 680<tr> <td>mail_spool_directory</td> <td>/var/mail</td> </tr> 681 682<tr> <td>mailq_path</td> <td>/usr/bin/mailq</td> </tr> 683 684<tr> <td>manpage_directory</td> <td>/usr/local/man</td> </tr> 685 686<tr> <td>meta_directory</td> <td>/etc/postfix</td> </tr> 687 688<tr> <td>newaliases_path</td> <td>/usr/bin/newaliases</td> </tr> 689 690<tr> <td>openssl_path</td> <td>openssl</td> </tr> 691 692<tr> <td>queue_directory</td> <td>/var/spool/postfix</td> </tr> 693 694<tr> <td>readme_directory</td> <td>no</td> </tr> 695 696<tr> <td>sendmail_path</td> <td>/usr/sbin/sendmail</td> </tr> 697 698<tr> <td>shlib_directory</td> <td>/usr/lib/postfix</td> </tr> 699 700</table> 701 702</blockquote> 703 704<h4>4.6.2 - All Postfix versions </h4> 705 706<p> All Postfix configuration parameters can be changed by editing 707a Postfix configuration file, except for one: the parameter that 708specifies the location of Postfix configuration files. In order to 709build Postfix with a configuration directory other than /etc/postfix, 710use: </p> 711 712<blockquote> 713<pre> 714$ make makefiles CCARGS="-DDEF_CONFIG_DIR=\\\"/some/where\\\"" 715$ make 716</pre> 717</blockquote> 718 719<p> IMPORTANT: Be sure to get the quotes right. These details matter 720a lot. </p> 721 722<p> Parameters whose defaults can be specified in this way are 723listed below. See the postconf(5) manpage for a description 724(command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 725 726<blockquote> 727 728<table border="1"> 729 730<tr><th> Macro name </th> <th>default value for</th> <th>typical 731default</th> </tr> 732 733<tr> <td>DEF_COMMAND_DIR</td> <td>command_directory</td> 734<td>/usr/sbin</td> </tr> 735 736<tr> <td>DEF_CONFIG_DIR</td> <td>config_directory</td> 737<td>/etc/postfix</td> </tr> 738 739<tr> <td>DEF_DB_TYPE</td> <td>default_database_type</td> 740<td>hash</td> </tr> 741 742<tr> <td>DEF_DAEMON_DIR</td> <td>daemon_directory</td> 743<td>/usr/libexec/postfix</td> </tr> 744 745<tr> <td>DEF_DATA_DIR</td> <td>data_directory</td> 746<td>/var/db/postfix</td> </tr> 747 748<tr> <td>DEF_MAILQ_PATH</td> <td>mailq_path</td> <td>/usr/bin/mailq</td> 749</tr> 750 751<tr> <td>DEF_HTML_DIR</td> <td>html_directory</td> 752<td>no</td> </tr> 753 754<tr> <td>DEF_MANPAGE_DIR</td> <td>manpage_directory</td> 755<td>/usr/local/man</td> </tr> 756 757<tr> <td>DEF_NEWALIAS_PATH</td> <td>newaliases_path</td> 758<td>/usr/bin/newaliases</td> </tr> 759 760<tr> <td>DEF_QUEUE_DIR</td> <td>queue_directory</td> 761<td>/var/spool/postfix</td> </tr> 762 763<tr> <td>DEF_README_DIR</td> <td>readme_directory</td> 764<td>no</td> </tr> 765 766<tr> <td>DEF_SENDMAIL_PATH</td> <td>sendmail_path</td> 767<td>/usr/sbin/sendmail</td> </tr> 768 769</table> 770 771</blockquote> 772 773<p> Note: the data_directory parameter (for caches and pseudo-random 774numbers) was introduced with Postfix version 2.5. </p> 775 776<h3><a name="build_other">4.7 - Overriding other compile-time 777features</a></h3> 778 779<p> The general method to override Postfix compile-time features 780is as follows: </p> 781 782<blockquote> 783<pre> 784$ make makefiles name=value name=value... 785$ make 786</pre> 787</blockquote> 788 789<p> The following is an extensive list of names and values. </p> 790 791<table border="1"> 792 793<tr> <th colspan="2"> Name/Value </th> <th> Description </th> </tr> 794 795<tr> <td colspan="2"> AUXLIBS="object_library..."</td> <td> Specifies 796one or more non-default object libraries. Postfix 3.0 and later 797specify some of their database library dependencies with AUXLIBS_CDB, 798AUXLIBS_LDAP, AUXLIBS_LMDB, AUXLIBS_MYSQL, AUXLIBS_PCRE, AUXLIBS_PGSQL, 799AUXLIBS_SDBM, and AUXLIBS_SQLITE, respectively. </td> </tr> 800 801<tr> <td colspan="2"> CC=compiler_command</td> <td> Specifies a 802non-default compiler. On many systems, the default is <tt>gcc</tt>. 803</td> </tr> 804 805<tr> <td colspan="2"> CCARGS="compiler_arguments..."</td> <td> 806Specifies non-default compiler arguments, for example, a non-default 807<tt>include</tt> directory. The following directives turn 808off Postfix features at compile time:</td> </tr> 809 810<tr> <td> </td> <td> -DNO_DB </td> <td> Do not build with Berkeley 811DB support. By default, Berkeley DB support is compiled in on 812platforms that are known to support this feature. If you override 813this, then you probably should also override DEF_DB_TYPE as described 814in section 4.6. </td> </tr> 815 816<tr> <td> </td> <td> -DNO_DNSSEC </td> <td> Do not build with DNSSEC 817support, even if the resolver library appears to support it. </td> 818</tr> 819 820<tr> <td> </td> <td> -DNO_DEVPOLL </td> <td> Do not build with 821Solaris <tt>/dev/poll</tt> support. By default, <tt>/dev/poll</tt> 822support is compiled in on Solaris versions that are known to support 823this feature. </td> </tr> 824 825<tr> <td> </td> <td> -DNO_EPOLL </td> <td> Do not build with Linux 826EPOLL support. By default, EPOLL support is compiled in on platforms 827that are known to support this feature. </td> </tr> 828 829<tr> <td> </td> <td> -DNO_EAI </td> <td> Do not build with EAI 830(SMTPUTF8) support. By default, EAI support is compiled in when 831the "icuuc" library and header files are found. </td> </tr> 832 833<tr> <td> </td> <td> -DNO_INLINE </td> <td> Do not require support 834for C99 "inline" functions. Instead, implement argument typechecks 835for non-printf/scanf-like functions with ternary operators and 836unreachable code. </td> </tr> 837 838<tr> <td> </td> <td> -DNO_IPV6 </td> <td> Do not build with IPv6 839support. By default, IPv6 support is compiled in on platforms that 840are known to have IPv6 support. Note: this directive is for debugging 841and testing only. It is not guaranteed to work on all platforms. 842If you don't want IPv6 support, set "inet_protocols = ipv4" in 843main.cf. 844</td> </tr> 845 846<tr> <td> </td> <td> -DNO_KQUEUE </td> <td> Do not build with FreeBSD 847/ NetBSD / OpenBSD / MacOSX KQUEUE support. By default, KQUEUE 848support is compiled in on platforms that are known to support it. 849</td> </tr> 850 851<tr> <td> </td> <td> -DNO_NIS </td> <td> Do not build with NIS or 852NISPLUS support. NIS is not available on some recent Linux 853distributions. </td> </tr> 854 855<tr> <td> </td> <td> -DNO_NISPLUS </td> <td> Do not build with 856NISPLUS support. NISPLUS is not available on some recent Solaris 857distributions. </td> </tr> 858 859<tr> <td> </td> <td> -DNO_PCRE </td> <td> Do not build with PCRE 860support. By default, PCRE support is compiled in when the 861<tt>pcre-config</tt> utility is installed. </td> </tr> 862 863<tr> <td> </td> <td> -DNO_POSIX_GETPW_R </td> <td> Disable support 864for POSIX <tt>getpwnam_r/getpwuid_r</tt>. By default Postfix uses 865these where they are known to be available. </td> </tr> 866 867<tr> <td> </td> <td> -DNO_RES_NCALLS </td> <td> Do not build with 868the threadsafe resolver(5) API (res_ninit() etc.). </td> </tr> 869 870<tr> <td> </td> <td> -DNO_SIGSETJMP </td> <td> Use 871<tt>setjmp()/longjmp()</tt> instead of <tt>sigsetjmp()/siglongjmp()</tt>. 872By default, Postfix uses <tt>sigsetjmp()/siglongjmp()</tt> when 873they are known to be available. </td> </tr> 874 875<tr> <td> </td> <td> -DNO_SNPRINTF </td> <td> Use <tt>sprintf()</tt> 876instead of <tt>snprintf()</tt>. By default, Postfix uses 877<tt>snprintf()</tt> except on ancient systems. </td> </tr> 878 879<tr> <td colspan="2"> DEBUG=debug_level </td> <td> Specifies a 880non-default compiler debugging level. The default is "<tt>-g</tt>". 881Specify DEBUG= to turn off debugging. </td> </tr> 882 883<tr> <td colspan="2"> OPT=optimization_level </td> <td> Specifies 884a non-default optimization level. The default is "<tt>-O</tt>". 885Specify OPT= to turn off optimization. </td> </tr> 886 887<tr> <td colspan="2"> POSTFIX_INSTALL_OPTS=-option... </td> <td> 888Specifies options for the <tt>postfix-install</tt> command, separated 889by whitespace. Currently, the only supported option is 890"<tt>-keep-build-mtime</tt>". </td> </tr> 891 892<tr> <td colspan="2"> SHLIB_CFLAGS=flags </td> <td> Specifies 893non-default compiler options for building Postfix dynamically-linked 894libraries and database plugins. The typical default is "-fPIC". 895</td> </tr> 896 897<tr> <td colspan="2"> SHLIB_RPATH=rpath </td> <td> Specifies 898a non-default runpath for Postfix dynamically-linked libraries. The 899typical default is "'-Wl,-rpath,${SHLIB_DIR}'". </td> </tr> 900 901<tr> <td colspan="2"> SHLIB_SUFFIX=suffix </td> <td> Specifies 902a non-default suffix for Postfix dynamically-linked libraries and 903database plugins. The typical default is "<tt>.so</tt>". </td> 904</tr> 905 906<tr> <td colspan="2"> WARN="warning_flags..." </td> <td> Specifies 907non-default compiler warning options for use when "<tt>make</tt>" 908is invoked in a source subdirectory only. </td> 909</tr> 910 911</table> 912 913<h3><a name="build_proc">4.8 - Support for thousands of processes</a></h3> 914 915<p> The number of connections that Postfix can manage simultaneously 916is limited by the number of processes that it can run. This number 917in turn is limited by the number of files and sockets that a single 918process can open. For example, the Postfix queue manager has a 919separate connection to each delivery process, and the anvil(8) 920server has one connection per smtpd(8) process. </p> 921 922<p> Postfix version 2.4 and later have no built-in limits on the 923number of open files or sockets, when compiled on systems that 924support one of the following: </p> 925 926<ul> 927 928<li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), 929 930<li> Solaris 8 /dev/poll, 931 932<li> Linux 2.6 epoll(4). 933 934</ul> 935 936 937<p> With other Postfix versions or operating systems, the number 938of file descriptors per process is limited by the value of the 939FD_SETSIZE macro. If you expect to run more than 1000 mail delivery 940processes, you may need to override the definition of the FD_SETSIZE 941macro to make select() work correctly: </p> 942 943<blockquote> 944<pre> 945$ make makefiles CCARGS=-DFD_SETSIZE=2048 946</pre> 947</blockquote> 948 949<p> Warning: the above has no effect on some Linux versions. 950Apparently, on these systems the FD_SETSIZE value can be changed 951only by using undocumented interfaces. Currently, that means 952including <bits/types.h> directly (which is not allowed) and 953overriding the __FD_SETSIZE macro. Beware, undocumented interfaces 954can change at any time and without warning. </p> 955 956<p> But wait, there is more: none of this will work unless the 957operating system is configured to handle thousands of connections. 958See the TUNING_README guide for examples of how to increase the 959number of open sockets or files. </p> 960 961<h3><a name="build_final">4.9 - Compiling Postfix, at last</a></h3> 962 963<p> If the command </p> 964 965<blockquote> 966<pre> 967$ make 968</pre> 969</blockquote> 970 971<p> is successful, then you can proceed to <a href="#install">install</a> 972Postfix (section 6). 973 974<p> If the command produces compiler error messages, it may be time 975to search the web or to ask the postfix-users@postfix.org mailing 976list, but be sure to search the mailing list archives first. Some 977mailing list archives are linked from http://www.postfix.org/. </p> 978 979<h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2> 980 981<p> Each system type that Postfix knows is identified by a unique 982name. Examples: SUNOS5, FREEBSD4, and so on. When porting Postfix 983to a new system, the first step is to choose a SYSTEMTYPE name for 984the new system. You must use a name that includes at least the 985major version of the operating system (such as SUNOS4 or LINUX2), 986so that different releases of the same system can be supported 987without confusion. </p> 988 989<p> Add a case statement to the "makedefs" shell script in the 990source code top-level directory that recognizes the new system 991reliably, and that emits the right system-specific information. 992Be sure to make the code robust against user PATH settings; if the 993system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to 994build for the native flavor, instead of the emulated one. </p> 995 996<p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h 997include file. You may have to invent new feature macro names. 998Please choose sensible feature macro names such as HAS_DBM or 999FIONREAD_IN_SYS_FILIO_H. 1000 1001<p> I strongly recommend against using "#ifdef SYSTEMTYPE" in 1002individual source files. While this may look like the quickest 1003solution, it will create a mess when newer versions of the same 1004SYSTEMTYPE need to be supported. You're likely to end up placing 1005"#ifdef" sections all over the source code again. </p> 1006 1007<h2><a name="install">6 - Installing the software after successful 1008compilation</a></h2> 1009 1010<p> This text describes how to install Postfix from source code. 1011See the PACKAGE_README file if you are building a package for 1012distribution to other systems. </p> 1013 1014<h3>6.1 - Save existing Sendmail binaries</h3> 1015 1016<p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing 1017Sendmail installation with Postfix, you may need to keep the old 1018sendmail program running for some time in order to flush the mail 1019queue. </p> 1020 1021<ul> 1022 1023<li> <p> Some systems implement a mail switch mechanism where 1024different MTAs (Postfix, Sendmail, etc.) can be installed at the 1025same time, while only one of them is actually being used. Examples 1026of such switching mechanisms are the FreeBSD mailwrapper(8) or the 1027Linux mail switch. In this case you should try to "flip" the switch 1028to "Postfix" before installing Postfix. </p> 1029 1030<li> <p> If your system has no mail switch mechanism, execute the 1031following commands (your sendmail, newaliases and mailq programs 1032may be in a different place): </p> 1033 1034<pre> 1035# mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF 1036# mv /usr/bin/newaliases /usr/bin/newaliases.OFF 1037# mv /usr/bin/mailq /usr/bin/mailq.OFF 1038# chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ 1039 /usr/bin/mailq.OFF 1040</pre> 1041 1042</ul> 1043 1044<h3>6.2 - Create account and groups</h3> 1045 1046<p> Before you install Postfix for the first time you need to 1047create an account and a group:</p> 1048 1049<ul> 1050 1051<li> <p> Create a user account "postfix" with a user id and group 1052id that are not used by any other user account. Preferably, this 1053is an account that no-one can log into. The account does not need 1054an executable login shell, and needs no existing home directory. 1055My password and group file entries look like this: </p> 1056 1057<blockquote> 1058<pre> 1059/etc/passwd: 1060 postfix:*:12345:12345:postfix:/no/where:/no/shell 1061 1062/etc/group: 1063 postfix:*:12345: 1064</pre> 1065</blockquote> 1066 1067<p> Note: there should be no whitespace before "postfix:". </p> 1068 1069<li> <p> Create a group "postdrop" with a group id that is not used 1070by any other user account. Not even by the postfix user account. 1071My group file entry looks like: 1072 1073<blockquote> 1074<pre> 1075/etc/group: 1076 postdrop:*:54321: 1077</pre> 1078</blockquote> 1079 1080<p> Note: there should be no whitespace before "postdrop:". </p> 1081 1082</ul> 1083 1084<h3>6.3 - Install Postfix</h3> 1085 1086<p> To install or upgrade Postfix from compiled source code, run 1087one of the following commands as the super-user:</p> 1088 1089<blockquote> 1090<pre> 1091# make install (interactive version, first time install) 1092 1093# make upgrade (non-interactive version, for upgrades) 1094</pre> 1095</blockquote> 1096 1097<ul> 1098 1099<li> <p> The interactive version ("make install") asks for pathnames 1100for Postfix data and program files, and stores your preferences in 1101the main.cf file. <b> If you don't want Postfix to overwrite 1102non-Postfix "sendmail", "mailq" and "newaliases" files, specify 1103pathnames that end in ".postfix"</b>. </p> 1104 1105<li> <p> The non-interactive version ("make upgrade") needs the 1106/etc/postfix/main.cf file from a previous installation. If the file 1107does not exist, use interactive installation ("make install") 1108instead. </p> 1109 1110<li> <p> If you specify name=value arguments on the "make install" 1111or "make upgrade" command line, then these will take precedence 1112over compiled-in default settings or main.cf settings. </p> 1113 1114<p> The command "make install/upgrade name=value ..." will replace 1115the string MAIL_VERSION at the end of a configuration parameter 1116value with the Postfix release version. Do not try to specify 1117something like $mail_version on this command line. This produces 1118inconsistent results with different versions of the make(1) command. 1119</p> 1120 1121</ul> 1122 1123<h3>6.4 - Configure Postfix</h3> 1124 1125<p> Proceed to the section on how you wish to run Postfix on 1126your particular machine: </p> 1127 1128<ul> 1129 1130<li> <p> <a href="#send_only">Send</a> mail only, without changing 1131an existing Sendmail installation (section 7). </p> 1132 1133<li> <p> <a href="#send_receive">Send and receive</a> mail via a 1134virtual host interface, still without any change to an existing 1135Sendmail installation (section 8). </p> 1136 1137<li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail 1138(section 9). </p> 1139 1140</ul> 1141 1142<h2><a name="send_only">7 - Configuring Postfix to send mail 1143only</a></h2> 1144 1145<p> If you are going to use Postfix to send mail only, there is no 1146need to change your existing sendmail setup. Instead, set up your 1147mail user agent so that it calls the Postfix sendmail program 1148directly. </p> 1149 1150<p> Follow the instructions in the "<a href="#mandatory">Mandatory 1151configuration file edits</a>" in section 10, and review the "<a 1152href="#hamlet">To chroot or not to chroot</a>" text in section 115311. </p> 1154 1155<p> You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, 1156in order to avoid conflicts with the real sendmail. Put a "#" 1157character in front of the line that defines the smtpd service: </p> 1158 1159<blockquote> 1160<pre> 1161/etc/postfix/master.cf: 1162 #smtp inet n - n - - smtpd 1163</pre> 1164</blockquote> 1165 1166<p> Start the Postfix system: </p> 1167 1168<blockquote> 1169<pre> 1170# postfix start 1171</pre> 1172</blockquote> 1173 1174<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1175 1176<blockquote> 1177<pre> 1178# sendmail -bd -qwhatever 1179</pre> 1180</blockquote> 1181 1182<p> and watch your maillog file for any error messages. The pathname 1183is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1184else. Typically, the pathname is defined in the /etc/syslog.conf 1185file. </p> 1186 1187<blockquote> 1188<pre> 1189$ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1190</pre> 1191</blockquote> 1192 1193<p> Note: the most important error message is logged first. Later 1194messages are not as useful. </p> 1195 1196<p> In order to inspect the mail queue, use one of the following 1197commands: </p> 1198 1199<blockquote> 1200<pre> 1201$ mailq 1202 1203$ sendmail -bp 1204 1205$ postqueue -p 1206</pre> 1207</blockquote> 1208 1209<p> See also the "<a href="#care">Care and feeding</a>" section 12 1210below. </p> 1211 1212<h2><a name="send_receive">8 - Configuring Postfix to send and 1213receive mail via virtual interface</a></h2> 1214 1215<p> Alternatively, you can use the Postfix system to send AND 1216receive mail while leaving your Sendmail setup intact, by running 1217Postfix on a virtual interface address. Simply configure your mail 1218user agent to directly invoke the Postfix sendmail program. </p> 1219 1220<p> To create a virtual network interface address, study your 1221system ifconfig manual page. The command syntax could be any 1222of: </p> 1223 1224<blockquote> 1225<pre> 1226# <b>ifconfig le0:1 <address> netmask <mask> up</b> 1227# <b>ifconfig en0 alias <address> netmask 255.255.255.255</b> 1228</pre> 1229</blockquote> 1230 1231<p> In the /etc/postfix/main.cf file, I would specify </p> 1232 1233<blockquote> 1234<pre> 1235/etc/postfix/main.cf: 1236 myhostname = virtual.host.tld 1237 inet_interfaces = $myhostname 1238 mydestination = $myhostname 1239</pre> 1240</blockquote> 1241 1242<p> Follow the instructions in the "<a href="#mandatory">Mandatory 1243configuration file edits</a>" in section 10, and review the "<a 1244href="#hamlet">To chroot or not to chroot</a>" text in section 124511. </p> 1246 1247<p> Start the Postfix system: </p> 1248 1249<blockquote> 1250<pre> 1251# postfix start 1252</pre> 1253</blockquote> 1254 1255<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1256 1257<blockquote> 1258<pre> 1259# sendmail -bd -qwhatever 1260</pre> 1261</blockquote> 1262 1263<p> and watch your maillog file for any error messages. The pathname 1264is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1265else. Typically, the pathname is defined in the /etc/syslog.conf 1266file. </p> 1267 1268<blockquote> 1269<pre> 1270$ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1271</pre> 1272</blockquote> 1273 1274<p> Note: the most important error message is logged first. Later 1275messages are not as useful. </p> 1276 1277<p> In order to inspect the mail queue, use one of the following 1278commands: </p> 1279 1280<blockquote> 1281<pre> 1282$ mailq 1283 1284$ sendmail -bp 1285 1286$ postqueue -p 1287</pre> 1288</blockquote> 1289 1290<p> See also the "<a href="#care">Care and feeding</a>" section 12 1291below. </p> 1292 1293<h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2> 1294 1295<p> Prior to installing Postfix you should <a href="#save">save</a> 1296any existing sendmail program files as described in section 6. Be 1297sure to keep the old sendmail running for at least a couple days 1298to flush any unsent mail. To do so, stop the sendmail daemon and 1299restart it as: </p> 1300 1301<blockquote> 1302<pre> 1303# /usr/sbin/sendmail.OFF -q 1304</pre> 1305</blockquote> 1306 1307<p> Note: this is old sendmail syntax. Newer versions use separate 1308processes for mail submission and for running the queue. </p> 1309 1310<p> After you have visited the "<a href="#mandatory">Mandatory 1311configuration file edits</a>" section below, you can start the 1312Postfix system with: </p> 1313 1314<blockquote> 1315<pre> 1316# postfix start 1317</pre> 1318</blockquote> 1319 1320<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1321 1322<blockquote> 1323<pre> 1324# sendmail -bd -qwhatever 1325</pre> 1326</blockquote> 1327 1328<p> and watch your maillog file for any error messages. The pathname 1329is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1330else. Typically, the pathname is defined in the /etc/syslog.conf 1331file. </p> 1332 1333<blockquote> 1334<pre> 1335$ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1336</pre> 1337</blockquote> 1338 1339<p> Note: the most important error message is logged first. Later 1340messages are not as useful. </p> 1341 1342<p> In order to inspect the mail queue, use one of the following 1343commands: </p> 1344 1345<blockquote> 1346<pre> 1347$ mailq 1348 1349$ sendmail -bp 1350 1351$ postqueue -p 1352</pre> 1353</blockquote> 1354 1355<p> See also the "<a href="#care">Care and feeding</a>" section 12 1356below. </p> 1357 1358<h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2> 1359 1360<p> Note: the material covered in this section is covered in more 1361detail in the BASIC_CONFIGURATION_README document. The information 1362presented below is targeted at experienced system administrators. 1363</p> 1364 1365<h3>10.1 - Postfix configuration files</h3> 1366 1367<p> By default, Postfix configuration files are in /etc/postfix. 1368The two most important files are main.cf and master.cf; these files 1369must be owned by root. Giving someone else write permission to 1370main.cf or master.cf (or to their parent directories) means giving 1371root privileges to that person. </p> 1372 1373<p> In /etc/postfix/main.cf, you will have to set up a minimal number 1374of configuration parameters. Postfix configuration parameters 1375resemble shell variables, with two important differences: the first 1376one is that Postfix does not know about quotes like the UNIX shell 1377does.</p> 1378 1379<p> You specify a configuration parameter as: </p> 1380 1381<blockquote> 1382<pre> 1383/etc/postfix/main.cf: 1384 parameter = value 1385</pre> 1386</blockquote> 1387 1388<p> and you use it by putting a "$" character in front of its name: </p> 1389 1390<blockquote> 1391<pre> 1392/etc/postfix/main.cf: 1393 other_parameter = $parameter 1394</pre> 1395</blockquote> 1396 1397<p> You can use $parameter before it is given a value (that is the 1398second main difference with UNIX shell variables). The Postfix 1399configuration language uses lazy evaluation, and does not look at 1400a parameter value until it is needed at runtime. </p> 1401 1402<p> Whenever you make a change to the main.cf or master.cf file, 1403execute the following command in order to refresh a running mail 1404system: </p> 1405 1406<blockquote> 1407<pre> 1408# postfix reload 1409</pre> 1410</blockquote> 1411 1412<h3>10.2 - Default domain for unqualified addresses</h3> 1413 1414<p> First of all, you must specify what domain will be appended to an 1415unqualified address (i.e. an address without @domain.tld). The 1416"myorigin" parameter defaults to the local hostname, but that is 1417probably OK only for very small sites. </p> 1418 1419<p> Some examples (use only one): </p> 1420 1421<blockquote> 1422<pre> 1423/etc/postfix/main.cf: 1424 myorigin = $myhostname (send mail as "user@$myhostname") 1425 myorigin = $mydomain (send mail as "user@$mydomain") 1426</pre> 1427</blockquote> 1428 1429<h3>10.3 - What domains to receive locally</h3> 1430 1431<p> Next you need to specify what mail addresses Postfix should deliver 1432locally. </p> 1433 1434<p> Some examples (use only one): </p> 1435 1436<blockquote> 1437<pre> 1438/etc/postfix/main.cf: 1439 mydestination = $myhostname, localhost.$mydomain, localhost 1440 mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain 1441 mydestination = $myhostname 1442</pre> 1443</blockquote> 1444 1445<p>The first example is appropriate for a workstation, the second 1446is appropriate for the mailserver for an entire domain. The third 1447example should be used when running on a virtual host interface.</p> 1448 1449<h3>10.4 - Proxy/NAT interface addresses </h3> 1450 1451<p> The proxy_interfaces parameter specifies all network addresses 1452that Postfix receives mail on by way of a proxy or network address 1453translation unit. You may specify symbolic hostnames instead of 1454network addresses. </p> 1455 1456<p> IMPORTANT: You must specify your proxy/NAT external addresses 1457when your system is a backup MX host for other domains, otherwise 1458mail delivery loops will happen when the primary MX host is down. 1459</p> 1460 1461<p> Example: host behind NAT box running a backup MX host. </p> 1462 1463<blockquote> 1464<pre> 1465/etc/postfix/main.cf: 1466 proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) 1467</pre> 1468</blockquote> 1469 1470<h3>10.5 - What local clients to relay mail from </h3> 1471 1472<p> If your machine is on an open network then you must specify 1473what client IP addresses are authorized to relay their mail through 1474your machine into the Internet. The default setting includes all 1475subnetworks that the machine is attached to. This may give relay 1476permission to too many clients. My own settings are: </p> 1477 1478<blockquote> 1479<pre> 1480/etc/postfix/main.cf: 1481 mynetworks = 168.100.189.0/28, 127.0.0.0/8 1482</pre> 1483</blockquote> 1484 1485<h3>10.6 - What relay destinations to accept from strangers </h3> 1486 1487<p> If your machine is on an open network then you must also specify 1488whether Postfix will forward mail from strangers. The default 1489setting will forward mail to all domains (and subdomains of) what 1490is listed in $mydestination. This may give relay permission for 1491too many destinations. Recommended settings (use only one): </p> 1492 1493<blockquote> 1494<pre> 1495/etc/postfix/main.cf: 1496 relay_domains = (do not forward mail from strangers) 1497 relay_domains = $mydomain (my domain and subdomains) 1498 relay_domains = $mydomain, other.domain.tld, ... 1499</pre> 1500</blockquote> 1501 1502<h3>10.7 - Optional: configure a smart host for remote delivery</h3> 1503 1504<p> If you're behind a firewall, you should set up a relayhost. If 1505you can, specify the organizational domain name so that Postfix 1506can use DNS lookups, and so that it can fall back to a secondary 1507MX host when the primary MX host is down. Otherwise just specify 1508a hard-coded hostname. </p> 1509 1510<p> Some examples (use only one): </p> 1511 1512<blockquote> 1513<pre> 1514/etc/postfix/main.cf: 1515 relayhost = $mydomain 1516 relayhost = [mail.$mydomain] 1517</pre> 1518</blockquote> 1519 1520<p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p> 1521 1522<p> By default, the SMTP client will do DNS lookups even when you 1523specify a relay host. If your machine has no access to a DNS server, 1524turn off SMTP client DNS lookups like this: </p> 1525 1526<blockquote> 1527<pre> 1528/etc/postfix/main.cf: 1529 disable_dns_lookups = yes 1530</pre> 1531</blockquote> 1532 1533<p> The STANDARD_CONFIGURATION_README file has more hints and tips for 1534firewalled and/or dial-up networks. </p> 1535 1536<h3>10.8 - Create the aliases database</h3> 1537 1538<p> Postfix uses a Sendmail-compatible aliases(5) table to redirect 1539mail for local(8) recipients. Typically, this information is kept 1540in two files: in a text file /etc/aliases and in an indexed file 1541/etc/aliases.db. The command "postconf alias_maps" will tell you 1542the exact location of the text file. </p> 1543 1544<p> First, be sure to update the text file with aliases for root, 1545postmaster and "postfix" that forward mail to a real person. Postfix 1546has a sample aliases file /etc/postfix/aliases that you can adapt 1547to local conditions. </p> 1548 1549<blockquote> 1550<pre> 1551/etc/aliases: 1552 root: you 1553 postmaster: root 1554 postfix: root 1555 bin: root 1556 <i>etcetera...</i> 1557</pre> 1558</blockquote> 1559 1560<p> Note: there should be no whitespace before the ":". </p> 1561 1562<p> Finally, build the indexed aliases file with one of the 1563following commands: </p> 1564 1565<blockquote> 1566<pre> 1567# newaliases 1568# sendmail -bi 1569# postalias /etc/aliases (pathname is system dependent!) 1570</pre> 1571</blockquote> 1572 1573<h2><a name="hamlet">11 - To chroot or not to chroot</a></h2> 1574 1575<p> Postfix daemon processes can be configured (via master.cf) to 1576run in a chroot jail. The processes run at a fixed low privilege 1577and with access only to the Postfix queue directories (/var/spool/postfix). 1578This provides a significant barrier against intrusion. The barrier 1579is not impenetrable, but every little bit helps. </p> 1580 1581<p> With the exception of Postfix daemons that deliver mail locally 1582and/or that execute non-Postfix commands, every Postfix daemon can 1583run chrooted. </p> 1584 1585<p> Sites with high security requirements should consider to chroot 1586all daemons that talk to the network: the smtp(8) and smtpd(8) 1587processes, and perhaps also the lmtp(8) client. The author's own 1588porcupine.org mail server runs all daemons chrooted that can be 1589chrooted. </p> 1590 1591<p> The default /etc/postfix/master.cf file specifies that no 1592Postfix daemon runs chrooted. In order to enable chroot operation, 1593edit the file /etc/postfix/master.cf. Instructions are in the file. 1594</p> 1595 1596<p> Note that a chrooted daemon resolves all filenames relative to 1597the Postfix queue directory (/var/spool/postfix). For successful 1598use of a chroot jail, most UNIX systems require you to bring in 1599some files or device nodes. The examples/chroot-setup directory 1600in the source code distribution has a collection of scripts that 1601help you set up Postfix chroot environments on different operating 1602systems. </p> 1603 1604<p> Additionally, you almost certainly need to configure syslogd 1605so that it listens on a socket inside the Postfix queue directory. 1606Examples for specific systems: </p> 1607 1608<dl> 1609 1610<dt> FreeBSD: </dt> 1611 1612<dd> <pre> 1613# mkdir -p /var/spool/postfix/var/run 1614# syslogd -l /var/spool/postfix/var/run/log 1615</pre> </dd> 1616 1617<dt> Linux, OpenBSD: </dt> 1618 1619<dd> <pre> 1620# mkdir -p /var/spool/postfix/dev 1621# syslogd -a /var/spool/postfix/dev/log 1622</pre> </dd> 1623 1624</dl> 1625 1626<h2><a name="care">12 - Care and feeding of the Postfix system</a></h2> 1627 1628<p> Postfix daemon processes run in the background, and log problems 1629and normal activity to the syslog daemon. The names of logfiles 1630are specified in /etc/syslog.conf. At the very least you need 1631something like: </p> 1632 1633<blockquote> 1634<pre> 1635/etc/syslog.conf: 1636 mail.err /dev/console 1637 mail.debug /var/log/maillog 1638</pre> 1639</blockquote> 1640 1641<p> IMPORTANT: the syslogd will not create files. You must create 1642them before (re)starting syslogd. </p> 1643 1644<p> IMPORTANT: on Linux you need to put a "-" character before 1645the pathname, e.g., -/var/log/maillog, otherwise the syslogd 1646will use more system resources than Postfix does. </p> 1647 1648<p> Hopefully, the number of problems will be small, but it is a good 1649idea to run every night before the syslog files are rotated: </p> 1650 1651<blockquote> 1652<pre> 1653# postfix check 1654# grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1655</pre> 1656</blockquote> 1657 1658<ul> 1659 1660<li> <p> The first line (postfix check) causes Postfix to report 1661file permission/ownership discrepancies. </p> 1662 1663<li> <p> The second line looks for problem reports from the mail 1664software, and reports how effective the relay and junk mail access 1665blocks are. This may produce a lot of output. You will want to 1666apply some postprocessing to eliminate uninteresting information. 1667</p> 1668 1669</ul> 1670 1671<p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a> 1672document describes the meaning of the "warning" etc. labels in 1673Postfix logging. </p> 1674 1675</body> 1676 1677</html> 1678
