diff options
Diffstat (limited to 'html/INSTALL.html')
| -rw-r--r-- | html/INSTALL.html | 1672 |
1 files changed, 1672 insertions, 0 deletions
diff --git a/html/INSTALL.html b/html/INSTALL.html new file mode 100644 index 0000000..2ee35cd --- /dev/null +++ b/html/INSTALL.html @@ -0,0 +1,1672 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<html> + +<head> + +<title>Postfix Installation From Source Code </title> + +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + +</head> + +<body> + +<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix +Installation From Source Code </h1> + +<hr> + +<h2> <a name="1">1 - Purpose of this document</a> </h2> + +<p> If you are using a pre-compiled version of Postfix, you should +start with <a href="BASIC_CONFIGURATION_README.html">BASIC_CONFIGURATION_README</a> and the general documentation +referenced by it. <a href="INSTALL.html">INSTALL</a> is only a bootstrap document to get +Postfix up and running from scratch with the minimal number of +steps; it should not be considered part of the general documentation. +</p> + +<p> This document describes how to build, install and configure a +Postfix system so that it can do one of the following: </p> + +<ul> + +<li> Send mail only, without changing an existing Sendmail +installation. + +<li> Send and receive mail via a virtual host interface, still +without any change to an existing Sendmail installation. + +<li> Run Postfix instead of Sendmail. + +</ul> + +<p> Topics covered in this document: </p> + +<ol> + +<li> <a href="#1">Purpose of this document</a> + +<li> <a href="#2">Typographical conventions</a> + +<li> <a href="#3">Documentation</a> + +<li> <a href="#4">Building on a supported system</a> + +<li> <a href="#5">Porting Postfix to an unsupported system</a> + +<li> <a href="#install">Installing the software after successful +compilation </a> + +<li> <a href="#send_only">Configuring Postfix to send mail +only </a> + +<li> <a href="#send_receive">Configuring Postfix to send and +receive mail via virtual interface </a> + +<li> <a href="#replace">Running Postfix instead of Sendmail</a> + +<li> <a href="#mandatory">Mandatory configuration file edits</a> + +<li> <a href="#hamlet">To chroot or not to chroot</a> + +<li> <a href="#care">Care and feeding of the Postfix system</a> + +</ol> + +<h2> <a name="2">2 - Typographical conventions</a> </h2> + +<p> In the instructions below, a command written as </p> + +<blockquote> +<pre> +# command +</pre> +</blockquote> + +<p> should be executed as the superuser. </p> + +<p> A command written as </p> + +<blockquote> +<pre> +$ command +</pre> +</blockquote> + +<p> should be executed as an unprivileged user. </p> + +<h2> <a name="3">3 - Documentation</a> </h2> + +<p> Documentation is available as README files (start with the file +README_FILES/AAAREADME), as HTML web pages (point your browser to +"html/index.html") and as UNIX-style manual pages. </p> + +<p> You should view the README files with a pager such as more(1) +or less(1), because the files use backspace characters in order to +produce <b>bold</b> font. To print a README file without backspace +characters, use the col(1) command. For example: </p> + +<blockquote> +<pre> +$ col -bx <file | lpr +</pre> +</blockquote> + +<p> In order to view the manual pages before installing Postfix, +point your MANPATH environment variable to the "man" subdirectory; +be sure to use an absolute path. </p> + +<blockquote> +<pre> +$ export MANPATH; MANPATH="`pwd`/man:$MANPATH" +$ setenv MANPATH "`pwd`/man:$MANPATH" +</pre> +</blockquote> + +<p> Of particular interest is the <a href="postconf.5.html">postconf(5)</a> manual page that +lists all the 500+ configuration parameters. The HTML version of +this text makes it easy to navigate around. </p> + +<p> All Postfix source files have their own built-in manual page. +Tools to extract those embedded manual pages are available in the +mantools directory. </p> + +<h2> <a name="4">4 - Building on a supported system</a> </h2> + +<p> Postfix development happens on FreeBSD and MacOS X, with regular +tests on Linux (Fedora, Ubuntu) and Solaris. Support for other +systems relies on feedback from their users, and may not always be +up-to-date. </p> + +<p> OpenBSD is partially supported. The libc resolver does not +implement the documented "internal resolver options which are [...] +set by changing fields in the _res structure" (documented in the +OpenBSD 5.6 resolver(3) manpage). This results in too many DNS +queries, and false positives for queries that should fail. </p> + +<!-- + +<p> At some point in time, a version of Postfix was supported on: </p> + +<blockquote> +<p> +AIX 3.2.5, 4.1.x, 4.2.0, 4.3.x, 5.2 <br> +BSD/OS 2.x, 3.x, 4.x <br> +FreeBSD 2.x .. 9.x <br> +HP-UX 9.x, 10.x, 11.x <br> +IRIX 5.x, 6.x <br> +Linux Debian 1.3.1 and later <br> +Linux RedHat 3.x (January 2004) and later <br> +Linux Slackware 3.x and later <br> +Linux SuSE 5.x and later <br> +Linux Ubuntu 4.10 and later<br> +Mac OS X <br> +NEXTSTEP 3.x <br> +NetBSD 1.x and later <br> +OPENSTEP 4.x <br> +OSF1.V3 - OSF1.V5 (Digital UNIX) <br> +Reliant UNIX 5.x <br> +SunOS 4.1.4 (March 2007) <br> +SunOS 5.4 - 5.10 (Solaris 2.4..10) <br> +Ultrix 4.x (well, that was long ago) <br> +</p> +</blockquote> + +<p> or something closely resemblant. </p> + +--> + +<p> Overview of topics: </p> + +<ul> + +<li><a href="#build_first">4.1 - Getting started</a> + +<li><a href="#build_cc">4.2 - What compiler to use</a> + +<li><a href="#build_pie">4.3 - Building with Postfix position-independent +executables (Postfix ≥ 3.0)</a> + +<li><a href="#build_dll">4.4 - Building with Postfix dynamically-linked +libraries and database plugins (Postfix ≥ 3.0)</a> + +<li><a href="#build_opt">4.5 - Building with optional features</a> + +<li><a href="#build_over">4.6 - Overriding built-in parameter default +settings</a> + +<li><a href="#build_other">4.7 - Overriding other compile-time +features</a> + +<li><a href="#build_proc">4.8 - Support for thousands of processes</a> + +<li><a href="#build_final">4.9 - Compiling Postfix, at last</a> + +</ul> + + +<h3><a name="build_first">4.1 - Getting started</a> </h3> + +<p> On Solaris, the "make" command and other development utilities +are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in your command +search path. If these files do not exist, you need to install the +development packages first. </p> + +<p> If you need to build Postfix for multiple architectures from a +single source-code tree, use the "lndir" command to build a shadow +tree with symbolic links to the source files. </p> + +<p> If at any time in the build process you get messages like: "make: +don't know how to ..." you should be able to recover by running +the following command from the Postfix top-level directory: </p> + +<blockquote> +<pre> +$ make -f Makefile.init makefiles +</pre> +</blockquote> + +<p> If you copied the Postfix source code after building it on another +machine, it is a good idea to cd into the top-level directory and +first do this:</p> + +<blockquote> +<pre> +$ make tidy +</pre> +</blockquote> + +<p> This will get rid of any system dependencies left over from +compiling the software elsewhere. </p> + +<h3><a name="build_cc">4.2 - What compiler to use</a></h3> + +<p> To build with GCC, or with the native compiler if people told me +that is better for your system, just cd into the top-level Postfix +directory of the source tree and type: </p> + +<blockquote> +<pre> +$ make +</pre> +</blockquote> + +<p> To build with a non-default compiler, you need to specify the name +of the compiler. Here are a few examples: </p> + +<blockquote> +<pre> +$ make makefiles CC=/opt/SUNWspro/bin/cc (Solaris) +$ make + +$ make makefiles CC="/opt/ansic/bin/cc -Ae" (HP-UX) +$ make + +$ make makefiles CC="purify cc" +$ make +</pre> +</blockquote> + +<p> and so on. In some cases, optimization will be turned off +automatically. </p> + +<h3><a name="build_pie">4.3 - Building with Postfix position-independent +executables (Postfix ≥ 3.0)</a> </h3> + +<p> On some systems Postfix can be built with Position-Independent +Executables. PIE is used by the ASLR exploit mitigation technique +(ASLR = Address-Space Layout Randomization): </p> + +<blockquote> +<pre> +$ make makefiles pie=yes ...other arguments... +</pre> +</blockquote> + +<p> (Specify "make makefiles pie=no" to explicitly disable Postfix +position-independent executable support). </p> + +<p> Postfix PIE support appears to work on Fedora Core 20, Ubuntu +14.04, FreeBSD 9 and 10, and NetBSD 6 (all with the default system +compilers). </p> + +<p> Whether the "pie=yes" above has any effect depends on the +compiler. Some compilers always produce PIE executables, and some +may even complain that the Postfix build option is redundant. </p> + +<h3><a name="build_dll">4.4 - Building with Postfix dynamically-linked +libraries and database plugins (Postfix ≥ 3.0)</a> </h3> + +<p> Postfix dynamically-linked library and database plugin support +exists for recent versions of Linux, FreeBSD and MacOS X. +Dynamically-linked library builds may become the default at some +point in the future. </p> + +<p> Overview of topics: </p> + +<ul> + +<li><a href="#shared_enable">4.4.1 Turning on Postfix dynamically-linked +library support</a> + +<li><a href="#dynamicmaps_enable">4.4.2 Turning on Postfix database-plugin +support</a> + +<li><a href="#shared_custom">4.4.3 Customizing Postfix dynamically-linked +libraries and database plugins</a> + +<li><a href="#shared_tips">4.4.4 Tips for distribution maintainers</a> + +</ul> + +<p> Note: directories with Postfix dynamically-linked libraries +or database plugins should contain only postfix-related files. +Postfix dynamically-linked libraries and database plugins should +not be installed in a "public" system directory such as /usr/lib +or /usr/local/lib. Linking Postfix dynamically-linked library or +database-plugin files into non-Postfix programs is not supported. +Postfix dynamically-linked libraries and database plugins implement +a Postfix-internal API that changes without maintaining compatibility. +</p> + +<h4><a name="shared_enable"> 4.4.1 Turning on Postfix dynamically-linked +library support </a></h4> + +<p> Postfix can be built with Postfix dynamically-linked libraries +(files typically named <tt>libpostfix-*.so</tt>). Postfix +dynamically-linked libraries add minor run-time overhead and result +in significantly-smaller Postfix executable files. </p> + +<p> Specify "shared=yes" on the "make makefiles" command line to +build Postfix with dynamically-linked library support. </p> + +<blockquote> +<pre> +$ make makefiles shared=yes ...other arguments... +$ make +</pre> +</blockquote> + +<p> (Specify "make makefiles shared=no" to explicitly disable Postfix +dynamically-linked library support). </p> + +<p> This installs dynamically-linked libraries in $<a href="postconf.5.html#shlib_directory">shlib_directory</a>, +typically /usr/lib/postfix or /usr/local/lib/postfix, with file +names libpostfix-<i>name</i>.so, where the <i>name</i> is a source-code +directory name such as "util" or "global". </p> + +<p> See section 4.4.3 "<a href="#shared_custom">Customizing Postfix +dynamically-linked libraries and database plugins</a>" below for +how to customize the Postfix dynamically-linked library location, +including support to upgrade a running mail system safely. </p> + +<h4><a name="dynamicmaps_enable"> 4.4.2 Turning on Postfix +database-plugin support </a></h4> + +<p> Additionally, Postfix can be built to support dynamic loading +of Postfix database clients (database plugins) with the Debian-style +dynamicmaps feature. Postfix 3.0 supports dynamic loading of <a href="CDB_README.html">cdb</a>:, +<a href="ldap_table.5.html">ldap</a>:, <a href="lmdb_table.5.html">lmdb</a>:, <a href="mysql_table.5.html">mysql</a>:, <a href="pcre_table.5.html">pcre</a>:, <a href="pgsql_table.5.html">pgsql</a>:, <a href="DATABASE_README.html#types">sdbm</a>:, and <a href="sqlite_table.5.html">sqlite</a>: database +clients. Dynamic loading is useful when you distribute or install +pre-compiled Postfix packages. </p> + +<p> Specify "dynamicmaps=yes" on the "make makefiles" command line +to build Postfix with support to dynamically load Postfix database +clients with the Debian-style dynamicmaps feature. +</p> + +<blockquote> +<pre> +$ make makefiles dynamicmaps=yes ...other arguments... +$ make +</pre> +</blockquote> + +<p> (Specify "make makefiles dynamicmaps=no" to explicitly disable +Postfix database-plugin support). </p> + +<p> This implicitly enables dynamically-linked library support, +installs the configuration file dynamicmaps.cf in $<a href="postconf.5.html#meta_directory">meta_directory</a> +(usually, /etc/postfix or /usr/local/etc/postfix), and installs +database plugins in $<a href="postconf.5.html#shlib_directory">shlib_directory</a> (see above). Database plugins +are named postfix-<i>type</i>.so where the <i>type</i> is a database +type such as "cdb" or "ldap". </p> + +<blockquote> + +<p> NOTE: The Postfix 3.0 build procedure expects that you specify +database library dependencies with variables named <a href="CDB_README.html">AUXLIBS_CDB</a>, +<a href="LDAP_README.html">AUXLIBS_LDAP</a>, etc. With Postfix 3.0 and later, the old AUXLIBS +variable still supports building a statically-loaded database client, +but only the new <a href="CDB_README.html">AUXLIBS_CDB</a> etc. variables support building a +dynamically-loaded or statically-loaded CDB etc. database client. +See <a href="CDB_README.html">CDB_README</a>, <a href="LDAP_README.html">LDAP_README</a>, etc. for details. </p> + +<p> Failure to follow this advice will defeat the purpose of dynamic +database client loading. Every Postfix executable file will have +database library dependencies. And that was exactly what dynamic +database client loading was meant to avoid. </p> + +</blockquote> + +<p> See the next section for how to customize the location and +version of Postfix database plugins and the location of the file +dynamicmaps.cf. </p> + +<h4><a name="shared_custom"> 4.4.3 Customizing Postfix dynamically-linked +libraries and database plugins </a></h4> + +<h5> Customizing build-time and run-time options for Postfix +dynamically-linked libraries and database plugins </h5> + +<p> The build-time environment variables SHLIB_CFLAGS, SHLIB_RPATH, +and SHLIB_SUFFIX provide control over how Postfix libraries and +plugins are compiled, linked, and named. + +<blockquote> +<pre> +$ make makefiles SHLIB_CFLAGS=flags SHLIB_RPATH=rpath SHLIB_SUFFIX=suffix ...other arguments... +$ make +</pre> +</blockquote> + +<p> See section 4.7 "<a href="#build_other">Overriding other +compile-time features</a>" below for details. </p> + +<h5> Customizing the location of Postfix dynamically-linked libraries +and database plugins </h5> + +<p> As a reminder, the directories with Postfix dynamically-linked +libraries or database plugins should contain only Postfix-related +files. Linking these files into other programs is not supported. +</p> + +<p> To override the default location of Postfix dynamically-linked +libraries and database plugins specify, for example: </p> + +<blockquote> +<pre> +$ make makefiles shared=yes <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix ... +</pre> +</blockquote> + +<p> If you intend to upgrade Postfix without stopping the mail +system, then you should append the Postfix release version to the +<a href="postconf.5.html#shlib_directory">shlib_directory</a> pathname, to eliminate the possibility that programs +will link with dynamically-linked libraries or database plugins +from the wrong Postfix version. For example: </p> + +<blockquote> +<pre> +$ make makefiles shared=yes \ + <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix/MAIL_VERSION ... +</pre> +</blockquote> + +<p> The command "make makefiles name=value..." will replace the +string MAIL_VERSION at the end of a configuration parameter value +with the Postfix release version. Do not try to specify something +like $<a href="postconf.5.html#mail_version">mail_version</a> on this command line. This produces inconsistent +results with different versions of the make(1) command. </p> + +<p> You can change the <a href="postconf.5.html#shlib_directory">shlib_directory</a> setting after Postfix is +built, with "make install" or "make upgrade". However, you may have +to run ldconfig if you change <a href="postconf.5.html#shlib_directory">shlib_directory</a> after Postfix is built +(the symptom is that Postfix programs fail because the run-time +linker cannot find the files libpostfix-*.so). No ldconfig command +is needed if you keep the files libpostfix-*.so in the compiled-in +default $<a href="postconf.5.html#shlib_directory">shlib_directory</a> location. </p> + +<blockquote> +<pre> +# make upgrade <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix ... +# make install <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix ... +</pre> +</blockquote> + +<p> To append the Postfix release version to the pathname if you +intend to upgrade Postfix without stopping the mail system: </p> + +<blockquote> +<pre> +# make upgrade <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix/MAIL_VERSION ... +# make install <a href="postconf.5.html#shlib_directory">shlib_directory</a>=/usr/local/lib/postfix/MAIL_VERSION ... +</pre> +</blockquote> + +<p> See also the comments above for appending MAIL_VERSION with +the "make makefiles" command. </p> + +<h5> Customizing the location of dynamicmaps.cf and other files +</h5> + +<p> The <a href="postconf.5.html#meta_directory">meta_directory</a> parameter has the same default setting as +the <a href="postconf.5.html#config_directory">config_directory</a> parameter, typically /etc/postfix or +/usr/local/etc/postfix. </p> + +<p> You can override the default <a href="postconf.5.html#meta_directory">meta_directory</a> location at compile +time or after Postfix is built. To override the default location +at compile time specify, for example: </p> + +<blockquote> +<pre> +% make makefiles <a href="postconf.5.html#meta_directory">meta_directory</a>=/usr/libexec/postfix ... +</pre> +</blockquote> + +<p> Here is a tip if you want to make a pathname dependent on the +Postfix release version: the command "make makefiles name=value..." +will replace the string MAIL_VERSION at the end of a configuration +parameter value with the Postfix release version. Do not try to +specify something like $<a href="postconf.5.html#mail_version">mail_version</a> on this command line. This +produces inconsistent results with different versions of the make(1) +command. </p> + +<p> You can override the <a href="postconf.5.html#meta_directory">meta_directory</a> setting after Postfix is +built, with "make install" or "make upgrade". </p> + +<blockquote> +<pre> +# make upgrade <a href="postconf.5.html#meta_directory">meta_directory</a>=/usr/libexec/postfix ... +# make install <a href="postconf.5.html#meta_directory">meta_directory</a>=/usr/libexec/postfix ... +</pre> +</blockquote> + +<p> As with the command "make makefiles, the command "make +install/upgrade name=value..." will replace the string MAIL_VERSION +at the end of a configuration parameter value with the Postfix +release version. Do not try to specify something like $<a href="postconf.5.html#mail_version">mail_version</a> +on this command line. This produces inconsistent results with +different versions of the make(1) command. </p> + +<h4><a name="shared_tips"> 4.4.4 Tips for distribution maintainers +</a></h4> + +<ul> + +<li> <p> The <a href="postconf.5.html#shlib_directory">shlib_directory</a> parameter setting also provides the +default directory for database plugin files with a relative pathname +in the file dynamicmaps.cf. </p> + +<li> <p> The <a href="postconf.5.html#meta_directory">meta_directory</a> parameter specifies the location of the +files dynamicmaps.cf, postfix-files, and some multi-instance template +files. The <a href="postconf.5.html#meta_directory">meta_directory</a> parameter has the same default value as +the <a href="postconf.5.html#config_directory">config_directory</a> parameter (typically, /etc/postfix or +/usr/local/etc/postfix). For backwards compatibility with Postfix +2.6 .. 2.11, specify "<a href="postconf.5.html#meta_directory">meta_directory</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>" in <a href="postconf.5.html">main.cf</a> +before installing or upgrading Postfix, or specify "<a href="postconf.5.html#meta_directory">meta_directory</a> += /path/name" on the "make makefiles", "make install" or "make +upgrade" command line. </p> + +<li> <p> The configuration file dynamicmaps.cf will automatically +include files under the directory dynamicmaps.cf.d, just like the +configuration file postfix-files will automatically include files +under the directory postfix-files.d. Thanks to this, you can install +or deinstall a database plugin package without having to edit +postfix-files or dynamicmaps.cf. Instead, you give that plugin its +own configuration files under dynamicmaps.cf.d and postfix-files.d, and +you add or remove those configuration files along with the database +plugin dynamically-linked object. </p> + +<li> <p> Each configuration file under the directory dynamicmaps.cf.d +must have the same format as the configuration file dynamicmaps.cf. +There is no requirement that these configuration file *names* have a +specific format. </p> + +<li> <p> Each configuration file under the directory postfix-files.d +must have the same format as the configuration file postfix-files. +There is no requirement that these configuration file *names* have a +specific format. </p> + +</ul> + +<h3><a name="build_opt">4.5 - Building with optional features</a></h3> + +By default, Postfix builds as a mail system with relatively few +bells and whistles. Support for third-party databases etc. +must be configured when Postfix is compiled. The following documents +describe how to build Postfix with support for optional features: + +<blockquote> +<table border="1"> + +<tr> <th>Optional feature </th> <th>Document </th> <th>Availability</th> +</tr> + +<tr> <td> Berkeley DB database</td> <td><a href="DB_README.html">DB_README</a></td> <td> Postfix +1.0 </td> </tr> + +<tr> <td> LMDB database</td> <td><a href="LMDB_README.html">LMDB_README</a></td> <td> Postfix +2.11 </td> </tr> + +<tr> <td> LDAP database</td> <td><a href="LDAP_README.html">LDAP_README</a></td> <td> Postfix +1.0 </td> </tr> + +<tr> <td> MySQL database</td> <td><a href="MYSQL_README.html">MYSQL_README</a></td> <td> Postfix +1.0 </td> </tr> + +<tr> <td> Perl compatible regular expression</td> <td><a href="PCRE_README.html">PCRE_README</a></td> +<td> Postfix 1.0 </td> </tr> + +<tr> <td> PostgreSQL database</td> <td><a href="PGSQL_README.html">PGSQL_README</a></td> <td> +Postfix 2.0 </td> </tr> + +<tr> <td> SASL authentication </td> <td><a href="SASL_README.html">SASL_README</a></td> <td> +Postfix 1.0 </td> </tr> + +<tr> <td> SQLite database</td> <td><a href="SQLITE_README.html">SQLITE_README</a></td> <td> Postfix +2.8 </td> </tr> + +<tr> <td> STARTTLS session encryption </td> <td><a href="TLS_README.html">TLS_README</a></td> <td> +Postfix 2.2 </td> </tr> + +</table> + +</blockquote> + +<p> Note: IP version 6 support is compiled into Postfix on operating +systems that have IPv6 support. See the <a href="IPV6_README.html">IPV6_README</a> file for details. +</p> + +<h3><a name="build_over">4.6 - Overriding built-in parameter default +settings</a></h3> + +<h4>4.6.1 - Postfix 3.0 and later </h4> + +<p> All Postfix configuration parameters can be changed by editing +a Postfix configuration file, except for one: the parameter that +specifies the location of Postfix configuration files. In order to +build Postfix with a configuration directory other than /etc/postfix, +use: </p> + +<blockquote> +<pre> +$ make makefiles <a href="postconf.5.html#config_directory">config_directory</a>=/some/where ...other arguments... +$ make +</pre> +</blockquote> + +<p> The command "make makefiles name=value ..." will replace the +string MAIL_VERSION at the end of a configuration parameter value +with the Postfix release version. Do not try to specify something +like $<a href="postconf.5.html#mail_version">mail_version</a> on this command line. This produces inconsistent +results with different versions of the make(1) command. </p> + +<p> Parameters whose defaults can be specified in this way are +listed below. See the <a href="postconf.5.html">postconf(5)</a> manpage for a description +(command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> + +<blockquote> + +<table border="1"> + +<tr> <th>parameter name</th> <th>typical default</th> </tr> + +<tr> <td><a href="postconf.5.html#command_directory">command_directory</a></td> <td>/usr/sbin</td> </tr> + +<tr> <td><a href="postconf.5.html#config_directory">config_directory</a></td> <td>/etc/postfix</td> </tr> + +<tr> <td><a href="postconf.5.html#default_database_type">default_database_type</a></td> <td>hash</td> </tr> + +<tr> <td><a href="postconf.5.html#daemon_directory">daemon_directory</a></td> <td>/usr/libexec/postfix</td> </tr> + +<tr> <td><a href="postconf.5.html#data_directory">data_directory</a></td> <td>/var/lib/postfix</td> </tr> + +<tr> <td><a href="postconf.5.html#html_directory">html_directory</a></td> <td>no</td> </tr> + +<tr> <td><a href="postconf.5.html#mail_spool_directory">mail_spool_directory</a></td> <td>/var/mail</td> </tr> + +<tr> <td><a href="postconf.5.html#mailq_path">mailq_path</a></td> <td>/usr/bin/mailq</td> </tr> + +<tr> <td><a href="postconf.5.html#manpage_directory">manpage_directory</a></td> <td>/usr/local/man</td> </tr> + +<tr> <td><a href="postconf.5.html#meta_directory">meta_directory</a></td> <td>/etc/postfix</td> </tr> + +<tr> <td><a href="postconf.5.html#newaliases_path">newaliases_path</a></td> <td>/usr/bin/newaliases</td> </tr> + +<tr> <td><a href="postconf.5.html#openssl_path">openssl_path</a></td> <td>openssl</td> </tr> + +<tr> <td><a href="postconf.5.html#queue_directory">queue_directory</a></td> <td>/var/spool/postfix</td> </tr> + +<tr> <td><a href="postconf.5.html#readme_directory">readme_directory</a></td> <td>no</td> </tr> + +<tr> <td><a href="postconf.5.html#sendmail_path">sendmail_path</a></td> <td>/usr/sbin/sendmail</td> </tr> + +<tr> <td><a href="postconf.5.html#shlib_directory">shlib_directory</a></td> <td>/usr/lib/postfix</td> </tr> + +</table> + +</blockquote> + +<h4>4.6.2 - All Postfix versions </h4> + +<p> All Postfix configuration parameters can be changed by editing +a Postfix configuration file, except for one: the parameter that +specifies the location of Postfix configuration files. In order to +build Postfix with a configuration directory other than /etc/postfix, +use: </p> + +<blockquote> +<pre> +$ make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"' +$ make +</pre> +</blockquote> + +<p> IMPORTANT: Be sure to get the quotes right. These details matter +a lot. </p> + +<p> Parameters whose defaults can be specified in this way are +listed below. See the <a href="postconf.5.html">postconf(5)</a> manpage for a description +(command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> + +<blockquote> + +<table border="1"> + +<tr><th> Macro name </th> <th>default value for</th> <th>typical +default</th> </tr> + +<tr> <td>DEF_COMMAND_DIR</td> <td><a href="postconf.5.html#command_directory">command_directory</a></td> +<td>/usr/sbin</td> </tr> + +<tr> <td>DEF_CONFIG_DIR</td> <td><a href="postconf.5.html#config_directory">config_directory</a></td> +<td>/etc/postfix</td> </tr> + +<tr> <td>DEF_DB_TYPE</td> <td><a href="postconf.5.html#default_database_type">default_database_type</a></td> +<td>hash</td> </tr> + +<tr> <td>DEF_DAEMON_DIR</td> <td><a href="postconf.5.html#daemon_directory">daemon_directory</a></td> +<td>/usr/libexec/postfix</td> </tr> + +<tr> <td>DEF_DATA_DIR</td> <td><a href="postconf.5.html#data_directory">data_directory</a></td> +<td>/var/lib/postfix</td> </tr> + +<tr> <td>DEF_MAILQ_PATH</td> <td><a href="postconf.5.html#mailq_path">mailq_path</a></td> <td>/usr/bin/mailq</td> +</tr> + +<tr> <td>DEF_HTML_DIR</td> <td><a href="postconf.5.html#html_directory">html_directory</a></td> +<td>no</td> </tr> + +<tr> <td>DEF_MANPAGE_DIR</td> <td><a href="postconf.5.html#manpage_directory">manpage_directory</a></td> +<td>/usr/local/man</td> </tr> + +<tr> <td>DEF_NEWALIAS_PATH</td> <td><a href="postconf.5.html#newaliases_path">newaliases_path</a></td> +<td>/usr/bin/newaliases</td> </tr> + +<tr> <td>DEF_QUEUE_DIR</td> <td><a href="postconf.5.html#queue_directory">queue_directory</a></td> +<td>/var/spool/postfix</td> </tr> + +<tr> <td>DEF_README_DIR</td> <td><a href="postconf.5.html#readme_directory">readme_directory</a></td> +<td>no</td> </tr> + +<tr> <td>DEF_SENDMAIL_PATH</td> <td><a href="postconf.5.html#sendmail_path">sendmail_path</a></td> +<td>/usr/sbin/sendmail</td> </tr> + +</table> + +</blockquote> + +<p> Note: the <a href="postconf.5.html#data_directory">data_directory</a> parameter (for caches and pseudo-random +numbers) was introduced with Postfix version 2.5. </p> + +<h3><a name="build_other">4.7 - Overriding other compile-time +features</a></h3> + +<p> The general method to override Postfix compile-time features +is as follows: </p> + +<blockquote> +<pre> +$ make makefiles name=value name=value... +$ make +</pre> +</blockquote> + +<p> The following is an extensive list of names and values. </p> + +<table border="1"> + +<tr> <th colspan="2"> Name/Value </th> <th> Description </th> </tr> + +<tr> <td colspan="2"> AUXLIBS="object_library..."</td> <td> Specifies +one or more non-default object libraries. Postfix 3.0 and later +specify some of their database library dependencies with <a href="CDB_README.html">AUXLIBS_CDB</a>, +<a href="LDAP_README.html">AUXLIBS_LDAP</a>, <a href="LMDB_README.html">AUXLIBS_LMDB</a>, <a href="MYSQL_README.html">AUXLIBS_MYSQL</a>, <a href="PCRE_README.html">AUXLIBS_PCRE</a>, <a href="PGSQL_README.html">AUXLIBS_PGSQL</a>, +<a href="SDBM_README.html">AUXLIBS_SDBM</a>, and <a href="SQLITE_README.html">AUXLIBS_SQLITE</a>, respectively. </td> </tr> + +<tr> <td colspan="2"> CC=compiler_command</td> <td> Specifies a +non-default compiler. On many systems, the default is <tt>gcc</tt>. +</td> </tr> + +<tr> <td colspan="2"> CCARGS="compiler_arguments..."</td> <td> +Specifies non-default compiler arguments, for example, a non-default +<tt>include</tt> directory. The following directives turn +off Postfix features at compile time:</td> </tr> + +<tr> <td> </td> <td> -DNO_DB </td> <td> Do not build with Berkeley +DB support. By default, Berkeley DB support is compiled in on +platforms that are known to support this feature. If you override +this, then you probably should also override DEF_DB_TYPE as described +in section 4.6. </td> </tr> + +<tr> <td> </td> <td> -DNO_DNSSEC </td> <td> Do not build with DNSSEC +support, even if the resolver library appears to support it. </td> +</tr> + +<tr> <td> </td> <td> -DNO_DEVPOLL </td> <td> Do not build with +Solaris <tt>/dev/poll</tt> support. By default, <tt>/dev/poll</tt> +support is compiled in on Solaris versions that are known to support +this feature. </td> </tr> + +<tr> <td> </td> <td> -DNO_EPOLL </td> <td> Do not build with Linux +EPOLL support. By default, EPOLL support is compiled in on platforms +that are known to support this feature. </td> </tr> + +<tr> <td> </td> <td> -DNO_EAI </td> <td> Do not build with EAI +(SMTPUTF8) support. By default, EAI support is compiled in when +the "icuuc" library and header files are found. </td> </tr> + +<tr> <td> </td> <td> -DNO_INLINE </td> <td> Do not require support +for C99 "inline" functions. Instead, implement argument typechecks +for non-printf/scanf-like functions with ternary operators and +unreachable code. </td> </tr> + +<tr> <td> </td> <td> -DNO_IPV6 </td> <td> Do not build with IPv6 +support. By default, IPv6 support is compiled in on platforms that +are known to have IPv6 support. Note: this directive is for debugging +And testing only. It is not guaranteed to work on all platforms. +If you don't want IPv6 support, set "<a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv4" in +<a href="postconf.5.html">main.cf</a>. +</td> </tr> + +<tr> <td> </td> <td> -DNO_KQUEUE </td> <td> Do not build with FreeBSD +/ NetBSD / OpenBSD / MacOSX KQUEUE support. By default, KQUEUE +support is compiled in on platforms that are known to support it. +</td> </tr> + +<tr> <td> </td> <td> -DNO_NIS </td> <td> Do not build with NIS or +NISPLUS support. NIS is not available on some recent Linux +distributions. </td> </tr> + +<tr> <td> </td> <td> -DNO_NISPLUS </td> <td> Do not build with +NISPLUS support. NISPLUS is not available on some recent Solaris +distributions. </td> </tr> + +<tr> <td> </td> <td> -DNO_PCRE </td> <td> Do not build with PCRE +support. By default, PCRE support is compiled in when the +<tt>pcre-config</tt> utility is installed. </td> </tr> + +<tr> <td> </td> <td> -DNO_POSIX_GETPW_R </td> <td> Disable support +for POSIX <tt>getpwnam_r/getpwuid_r</tt>. By default Postfix uses +these where they are known to be available. </td> </tr> + +<tr> <td> </td> <td> -DNO_SIGSETJMP </td> <td> Use +<tt>setjmp()/longjmp()</tt> instead of <tt>sigsetjmp()/siglongjmp()</tt>. +By default, Postfix uses <tt>sigsetjmp()/siglongjmp()</tt> when +they are known to be available. </td> </tr> + +<tr> <td> </td> <td> -DNO_SNPRINTF </td> <td> Use <tt>sprintf()</tt> +instead of <tt>snprintf()</tt>. By default, Postfix uses +<tt>snprintf()</tt> except on ancient systems. </td> </tr> + +<tr> <td colspan="2"> DEBUG=debug_level </td> <td> Specifies a +non-default compiler debugging level. The default is "<tt>-g</tt>". +Specify DEBUG= to turn off debugging. </td> </tr> + +<tr> <td colspan="2"> OPT=optimization_level </td> <td> Specifies +a non-default optimization level. The default is "<tt>-O</tt>". +Specify OPT= to turn off optimization. </td> </tr> + +<tr> <td colspan="2"> POSTFIX_INSTALL_OPTS=-option... </td> <td> +Specifies options for the <tt>postfix-install</tt> command, separated +by whitespace. Currently, the only supported option is +"<tt>-keep-build-mtime</tt>". </td> </tr> + +<tr> <td colspan="2"> SHLIB_CFLAGS=flags </td> <td> Specifies +non-default compiler options for building Postfix dynamically-linked +libraries and database plugins. The typical default is "-fPIC". +</td> </tr> + +<tr> <td colspan="2"> SHLIB_RPATH=rpath </td> <td> Specifies +a non-default runpath for Postfix dynamically-linked libraries. The +typical default is "'-Wl,-rpath,${SHLIB_DIR}'". </td> </tr> + +<tr> <td colspan="2"> SHLIB_SUFFIX=suffix </td> <td> Specifies +a non-default suffix for Postfix dynamically-linked libraries and +database plugins. The typical default is "<tt>.so</tt>". </td> +</tr> + +<tr> <td colspan="2"> WARN="warning_flags..." </td> <td> Specifies +non-default compiler warning options for use when "<tt>make</tt>" +is invoked in a source subdirectory only. </td> +</tr> + +</table> + +<h3><a name="build_proc">4.8 - Support for thousands of processes</a></h3> + +<p> The number of connections that Postfix can manage simultaneously +is limited by the number of processes that it can run. This number +in turn is limited by the number of files and sockets that a single +process can open. For example, the Postfix queue manager has a +separate connection to each delivery process, and the <a href="anvil.8.html">anvil(8)</a> +server has one connection per <a href="smtpd.8.html">smtpd(8)</a> process. </p> + +<p> Postfix version 2.4 and later have no built-in limits on the +number of open files or sockets, when compiled on systems that +support one of the following: </p> + +<ul> + +<li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), + +<li> Solaris 8 /dev/poll, + +<li> Linux 2.6 epoll(4). + +</ul> + + +<p> With other Postfix versions or operating systems, the number +of file descriptors per process is limited by the value of the +FD_SETSIZE macro. If you expect to run more than 1000 mail delivery +processes, you may need to override the definition of the FD_SETSIZE +macro to make select() work correctly: </p> + +<blockquote> +<pre> +$ make makefiles CCARGS=-DFD_SETSIZE=2048 +</pre> +</blockquote> + +<p> Warning: the above has no effect on some Linux versions. +Apparently, on these systems the FD_SETSIZE value can be changed +only by using undocumented interfaces. Currently, that means +including <bits/types.h> directly (which is not allowed) and +overriding the __FD_SETSIZE macro. Beware, undocumented interfaces +can change at any time and without warning. </p> + +<p> But wait, there is more: none of this will work unless the +operating system is configured to handle thousands of connections. +See the <a href="TUNING_README.html">TUNING_README</a> guide for examples of how to increase the +number of open sockets or files. </p> + +<h3><a name="build_final">4.9 - Compiling Postfix, at last</a></h3> + +<p> If the command </p> + +<blockquote> +<pre> +$ make +</pre> +</blockquote> + +<p> is successful, then you can proceed to <a href="#install">install</a> +Postfix (section 6). + +<p> If the command produces compiler error messages, it may be time +to search the web or to ask the postfix-users@postfix.org mailing +list, but be sure to search the mailing list archives first. Some +mailing list archives are linked from <a href="http://www.postfix.org/">http://www.postfix.org/</a>. </p> + +<h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2> + +<p> Each system type that Postfix knows is identified by a unique +name. Examples: SUNOS5, FREEBSD4, and so on. When porting Postfix +to a new system, the first step is to choose a SYSTEMTYPE name for +the new system. You must use a name that includes at least the +major version of the operating system (such as SUNOS4 or LINUX2), +so that different releases of the same system can be supported +without confusion. </p> + +<p> Add a case statement to the "makedefs" shell script in the +source code top-level directory that recognizes the new system +reliably, and that emits the right system-specific information. +Be sure to make the code robust against user PATH settings; if the +system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to +build for the native flavor, instead of the emulated one. </p> + +<p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h +include file. You may have to invent new feature macro names. +Please choose sensible feature macro names such as HAS_DBM or +FIONREAD_IN_SYS_FILIO_H. + +<p> I strongly recommend against using "#ifdef SYSTEMTYPE" in +individual source files. While this may look like the quickest +solution, it will create a mess when newer versions of the same +SYSTEMTYPE need to be supported. You're likely to end up placing +"#ifdef" sections all over the source code again. </p> + +<h2><a name="install">6 - Installing the software after successful +compilation</a></h2> + +<p> This text describes how to install Postfix from source code. +See the <a href="PACKAGE_README.html">PACKAGE_README</a> file if you are building a package for +distribution to other systems. </p> + +<h3>6.1 - Save existing Sendmail binaries</h3> + +<p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing +Sendmail installation with Postfix, you may need to keep the old +sendmail program running for some time in order to flush the mail +queue. </p> + +<ul> + +<li> <p> Some systems implement a mail switch mechanism where +different MTAs (Postfix, Sendmail, etc.) can be installed at the +same time, while only one of them is actually being used. Examples +of such switching mechanisms are the FreeBSD mailwrapper(8) or the +Linux mail switch. In this case you should try to "flip" the switch +to "Postfix" before installing Postfix. </p> + +<li> <p> If your system has no mail switch mechanism, execute the +following commands (your sendmail, newaliases and mailq programs +may be in a different place): </p> + +<pre> +# mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF +# mv /usr/bin/newaliases /usr/bin/newaliases.OFF +# mv /usr/bin/mailq /usr/bin/mailq.OFF +# chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ + /usr/bin/mailq.OFF +</pre> + +</ul> + +<h3>6.2 - Create account and groups</h3> + +<p> Before you install Postfix for the first time you need to +create an account and a group:</p> + +<ul> + +<li> <p> Create a user account "postfix" with a user id and group +id that are not used by any other user account. Preferably, this +is an account that no-one can log into. The account does not need +an executable login shell, and needs no existing home directory. +My password and group file entries look like this: </p> + +<blockquote> +<pre> +/etc/passwd: + postfix:*:12345:12345:postfix:/no/where:/no/shell + +/etc/group: + postfix:*:12345: +</pre> +</blockquote> + +<p> Note: there should be no whitespace before "postfix:". </p> + +<li> <p> Create a group "postdrop" with a group id that is not used +by any other user account. Not even by the postfix user account. +My group file entry looks like: + +<blockquote> +<pre> +/etc/group: + postdrop:*:54321: +</pre> +</blockquote> + +<p> Note: there should be no whitespace before "postdrop:". </p> + +</ul> + +<h3>6.3 - Install Postfix</h3> + +<p> To install or upgrade Postfix from compiled source code, run +one of the following commands as the super-user:</p> + +<blockquote> +<pre> +# make install (interactive version, first time install) + +# make upgrade (non-interactive version, for upgrades) +</pre> +</blockquote> + +<ul> + +<li> <p> The interactive version ("make install") asks for pathnames +for Postfix data and program files, and stores your preferences in +the <a href="postconf.5.html">main.cf</a> file. <b> If you don't want Postfix to overwrite +non-Postfix "sendmail", "mailq" and "newaliases" files, specify +pathnames that end in ".postfix"</b>. </p> + +<li> <p> The non-interactive version ("make upgrade") needs the +/etc/postfix/<a href="postconf.5.html">main.cf</a> file from a previous installation. If the file +does not exist, use interactive installation ("make install") +instead. </p> + +<li> <p> If you specify name=value arguments on the "make install" +or "make upgrade" command line, then these will take precedence +over compiled-in default settings or <a href="postconf.5.html">main.cf</a> settings. </p> + +<p> The command "make install/upgrade name=value ..." will replace +the string MAIL_VERSION at the end of a configuration parameter +value with the Postfix release version. Do not try to specify +something like $<a href="postconf.5.html#mail_version">mail_version</a> on this command line. This produces +inconsistent results with different versions of the make(1) command. +</p> + +</ul> + +<h3>6.4 - Configure Postfix</h3> + +<p> Proceed to the section on how you wish to run Postfix on +your particular machine: </p> + +<ul> + +<li> <p> <a href="#send_only">Send</a> mail only, without changing +an existing Sendmail installation (section 7). </p> + +<li> <p> <a href="#send_receive">Send and receive</a> mail via a +virtual host interface, still without any change to an existing +Sendmail installation (section 8). </p> + +<li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail +(section 9). </p> + +</ul> + +<h2><a name="send_only">7 - Configuring Postfix to send mail +only</a></h2> + +<p> If you are going to use Postfix to send mail only, there is no +need to change your existing sendmail setup. Instead, set up your +mail user agent so that it calls the Postfix sendmail program +directly. </p> + +<p> Follow the instructions in the "<a href="#mandatory">Mandatory +configuration file edits</a>" in section 10, and review the "<a +href="#hamlet">To chroot or not to chroot</a>" text in section +11. </p> + +<p> You MUST comment out the "smtp inet" entry in /etc/postfix/<a href="master.5.html">master.cf</a>, +in order to avoid conflicts with the real sendmail. Put a "#" +character in front of the line that defines the smtpd service: </p> + +<blockquote> +<pre> +/etc/postfix/<a href="master.5.html">master.cf</a>: + #smtp inet n - n - - smtpd +</pre> +</blockquote> + +<p> Start the Postfix system: </p> + +<blockquote> +<pre> +# postfix start +</pre> +</blockquote> + +<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> + +<blockquote> +<pre> +# sendmail -bd -qwhatever +</pre> +</blockquote> + +<p> and watch your maillog file for any error messages. The pathname +is /var/log/maillog, /var/log/mail, /var/log/syslog, or something +else. Typically, the pathname is defined in the /etc/syslog.conf +file. </p> + +<blockquote> +<pre> +$ egrep '(reject|warning|error|fatal|panic):' /some/log/file +</pre> +</blockquote> + +<p> Note: the most important error message is logged first. Later +messages are not as useful. </p> + +<p> In order to inspect the mail queue, use one of the following +commands: </p> + +<blockquote> +<pre> +$ mailq + +$ sendmail -bp + +$ postqueue -p +</pre> +</blockquote> + +<p> See also the "<a href="#care">Care and feeding</a>" section 12 +below. </p> + +<h2><a name="send_receive">8 - Configuring Postfix to send and +receive mail via virtual interface</a></h2> + +<p> Alternatively, you can use the Postfix system to send AND +receive mail while leaving your Sendmail setup intact, by running +Postfix on a virtual interface address. Simply configure your mail +user agent to directly invoke the Postfix sendmail program. </p> + +<p> To create a virtual network interface address, study your +system ifconfig manual page. The command syntax could be any +of: </p> + +<blockquote> +<pre> +# <b>ifconfig le0:1 <address> netmask <mask> up</b> +# <b>ifconfig en0 alias <address> netmask 255.255.255.255</b> +</pre> +</blockquote> + +<p> In the /etc/postfix/<a href="postconf.5.html">main.cf</a> file, I would specify </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#myhostname">myhostname</a> = virtual.host.tld + <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = $<a href="postconf.5.html#myhostname">myhostname</a> + <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a> +</pre> +</blockquote> + +<p> Follow the instructions in the "<a href="#mandatory">Mandatory +configuration file edits</a>" in section 10, and review the "<a +name="#hamlet">To chroot or not to chroot</a>" text in section +11. </p> + +<p> Start the Postfix system: </p> + +<blockquote> +<pre> +# postfix start +</pre> +</blockquote> + +<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> + +<blockquote> +<pre> +# sendmail -bd -qwhatever +</pre> +</blockquote> + +<p> and watch your maillog file for any error messages. The pathname +is /var/log/maillog, /var/log/mail, /var/log/syslog, or something +else. Typically, the pathname is defined in the /etc/syslog.conf +file. </p> + +<blockquote> +<pre> +$ egrep '(reject|warning|error|fatal|panic):' /some/log/file +</pre> +</blockquote> + +<p> Note: the most important error message is logged first. Later +messages are not as useful. </p> + +<p> In order to inspect the mail queue, use one of the following +commands: </p> + +<blockquote> +<pre> +$ mailq + +$ sendmail -bp + +$ postqueue -p +</pre> +</blockquote> + +<p> See also the "<a href="#care">Care and feeding</a>" section 12 +below. </p> + +<h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2> + +<p> Prior to installing Postfix you should <a href="#save">save</a> +any existing sendmail program files as described in section 6. Be +sure to keep the old sendmail running for at least a couple days +to flush any unsent mail. To do so, stop the sendmail daemon and +restart it as: </p> + +<blockquote> +<pre> +# /usr/sbin/sendmail.OFF -q +</pre> +</blockquote> + +<p> Note: this is old sendmail syntax. Newer versions use separate +processes for mail submission and for running the queue. </p> + +<p> After you have visited the "<a href="#mandatory">Mandatory +configuration file edits</a>" section below, you can start the +Postfix system with: </p> + +<blockquote> +<pre> +# postfix start +</pre> +</blockquote> + +<p> or, if you feel nostalgic, use the Postfix sendmail command: </p> + +<blockquote> +<pre> +# sendmail -bd -qwhatever +</pre> +</blockquote> + +<p> and watch your maillog file for any error messages. The pathname +is /var/log/maillog, /var/log/mail, /var/log/syslog, or something +else. Typically, the pathname is defined in the /etc/syslog.conf +file. </p> + +<blockquote> +<pre> +$ egrep '(reject|warning|error|fatal|panic):' /some/log/file +</pre> +</blockquote> + +<p> Note: the most important error message is logged first. Later +messages are not as useful. </p> + +<p> In order to inspect the mail queue, use one of the following +commands: </p> + +<blockquote> +<pre> +$ mailq + +$ sendmail -bp + +$ postqueue -p +</pre> +</blockquote> + +<p> See also the "<a href="#care">Care and feeding</a>" section 12 +below. </p> + +<h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2> + +<p> Note: the material covered in this section is covered in more +detail in the <a href="BASIC_CONFIGURATION_README.html">BASIC_CONFIGURATION_README</a> document. The information +presented below is targeted at experienced system administrators. +</p> + +<h3>10.1 - Postfix configuration files</h3> + +<p> By default, Postfix configuration files are in /etc/postfix. +The two most important files are <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a>; these files +must be owned by root. Giving someone else write permission to +<a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a> (or to their parent directories) means giving +root privileges to that person. </p> + +<p> In /etc/postfix/<a href="postconf.5.html">main.cf</a>, you will have to set up a minimal number +of configuration parameters. Postfix configuration parameters +resemble shell variables, with two important differences: the first +one is that Postfix does not know about quotes like the UNIX shell +does.</p> + +<p> You specify a configuration parameter as: </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + parameter = value +</pre> +</blockquote> + +<p> and you use it by putting a "$" character in front of its name: </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + other_parameter = $parameter +</pre> +</blockquote> + +<p> You can use $parameter before it is given a value (that is the +second main difference with UNIX shell variables). The Postfix +configuration language uses lazy evaluation, and does not look at +a parameter value until it is needed at runtime. </p> + +<p> 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, +execute the following command in order to refresh a running mail +system: </p> + +<blockquote> +<pre> +# postfix reload +</pre> +</blockquote> + +<h3>10.2 - Default domain for unqualified addresses</h3> + +<p> First of all, you must specify what domain will be appended to an +unqualified address (i.e. an address without @domain.tld). The +"<a href="postconf.5.html#myorigin">myorigin</a>" parameter defaults to the local hostname, but that is +probably OK only for very small sites. </p> + +<p> Some examples (use only one): </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <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>") + <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>") +</pre> +</blockquote> + +<h3>10.3 - What domains to receive locally</h3> + +<p> Next you need to specify what mail addresses Postfix should deliver +locally. </p> + +<p> Some examples (use only one): </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <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#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> + <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a> +</pre> +</blockquote> + +<p>The first example is appropriate for a workstation, the second +is appropriate for the mailserver for an entire domain. The third +example should be used when running on a virtual host interface.</p> + +<h3>10.4 - Proxy/NAT interface addresses </h3> + +<p> The <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> parameter specifies all network addresses +that Postfix receives mail on by way of a proxy or network address +translation unit. You may specify symbolic hostnames instead of +network addresses. </p> + +<p> IMPORTANT: You must specify your proxy/NAT external addresses +when your system is a backup MX host for other domains, otherwise +mail delivery loops will happen when the primary MX host is down. +</p> + +<p> Example: host behind NAT box running a backup MX host. </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> = 1.2.3.4 (the proxy/NAT external network address) +</pre> +</blockquote> + +<h3>10.5 - What local clients to relay mail from </h3> + +<p> If your machine is on an open network then you must specify +what client IP addresses are authorized to relay their mail through +your machine into the Internet. The default setting includes all +subnetworks that the machine is attached to. This may give relay +permission to too many clients. My own settings are: </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#mynetworks">mynetworks</a> = 168.100.189.0/28, 127.0.0.0/8 +</pre> +</blockquote> + +<h3>10.6 - What relay destinations to accept from strangers </h3> + +<p> If your machine is on an open network then you must also specify +whether Postfix will forward mail from strangers. The default +setting will forward mail to all domains (and subdomains of) what +is listed in $<a href="postconf.5.html#mydestination">mydestination</a>. This may give relay permission for +too many destinations. Recommended settings (use only one): </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#relay_domains">relay_domains</a> = (do not forward mail from strangers) + <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a> (my domain and subdomains) + <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a>, other.domain.tld, ... +</pre> +</blockquote> + +<h3>10.7 - Optional: configure a smart host for remote delivery</h3> + +<p> If you're behind a firewall, you should set up a <a href="postconf.5.html#relayhost">relayhost</a>. If +you can, specify the organizational domain name so that Postfix +can use DNS lookups, and so that it can fall back to a secondary +MX host when the primary MX host is down. Otherwise just specify +a hard-coded hostname. </p> + +<p> Some examples (use only one): </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#relayhost">relayhost</a> = $<a href="postconf.5.html#mydomain">mydomain</a> + <a href="postconf.5.html#relayhost">relayhost</a> = [mail.$<a href="postconf.5.html#mydomain">mydomain</a>] +</pre> +</blockquote> + +<p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p> + +<p> By default, the SMTP client will do DNS lookups even when you +specify a <a href="postconf.5.html#relayhost">relay host</a>. If your machine has no access to a DNS server, +turn off SMTP client DNS lookups like this: </p> + +<blockquote> +<pre> +/etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> = yes +</pre> +</blockquote> + +<p> The <a href="STANDARD_CONFIGURATION_README.html">STANDARD_CONFIGURATION_README</a> file has more hints and tips for +firewalled and/or dial-up networks. </p> + +<h3>10.8 - Create the aliases database</h3> + +<p> Postfix uses a Sendmail-compatible <a href="aliases.5.html">aliases(5)</a> table to redirect +mail for <a href="local.8.html">local(8)</a> recipients. Typically, this information is kept +in two files: in a text file /etc/aliases and in an indexed file +/etc/aliases.db. The command "postconf <a href="postconf.5.html#alias_maps">alias_maps</a>" will tell you +the exact location of the text file. </p> + +<p> First, be sure to update the text file with aliases for root, +postmaster and "postfix" that forward mail to a real person. Postfix +has a sample aliases file /etc/postfix/aliases that you can adapt +to local conditions. </p> + +<blockquote> +<pre> +/etc/aliases: + root: you + postmaster: root + postfix: root + bin: root + <i>etcetera...</i> +</pre> +</blockquote> + +<p> Note: there should be no whitespace before the ":". </p> + +<p> Finally, build the indexed aliases file with one of the +following commands: </p> + +<blockquote> +<pre> +# newaliases +# sendmail -bi +</pre> +</blockquote> + +<h2><a name="hamlet">11 - To chroot or not to chroot</a></h2> + +<p> Postfix daemon processes can be configured (via <a href="master.5.html">master.cf</a>) to +run in a chroot jail. The processes run at a fixed low privilege +and with access only to the Postfix queue directories (/var/spool/postfix). +This provides a significant barrier against intrusion. The barrier +is not impenetrable, but every little bit helps. </p> + +<p> With the exception of Postfix daemons that deliver mail locally +and/or that execute non-Postfix commands, every Postfix daemon can +run chrooted. </p> + +<p> Sites with high security requirements should consider to chroot +all daemons that talk to the network: the <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a> +processes, and perhaps also the <a href="lmtp.8.html">lmtp(8)</a> client. The author's own +porcupine.org mail server runs all daemons chrooted that can be +chrooted. </p> + +<p> The default /etc/postfix/<a href="master.5.html">master.cf</a> file specifies that no +Postfix daemon runs chrooted. In order to enable chroot operation, +edit the file /etc/postfix/<a href="master.5.html">master.cf</a>. Instructions are in the file. +</p> + +<p> Note that a chrooted daemon resolves all filenames relative to +the Postfix queue directory (/var/spool/postfix). For successful +use of a chroot jail, most UNIX systems require you to bring in +some files or device nodes. The examples/chroot-setup directory +in the source code distribution has a collection of scripts that +help you set up Postfix chroot environments on different operating +systems. </p> + +<p> Additionally, you almost certainly need to configure syslogd +so that it listens on a socket inside the Postfix queue directory. +Examples for specific systems: </p> + +<dl> + +<dt> FreeBSD: </dt> + +<dd> <pre> +# mkdir -p /var/spool/postfix/var/run +# syslogd -l /var/spool/postfix/var/run/log +</pre> </dd> + +<dt> Linux, OpenBSD: </dt> + +<dd> <pre> +# mkdir -p /var/spool/postfix/dev +# syslogd -a /var/spool/postfix/dev/log +</pre> </dd> + +</dl> + +<h2><a name="care">12 - Care and feeding of the Postfix system</a></h2> + +<p> Postfix daemon processes run in the background, and log problems +and normal activity to the syslog daemon. The names of logfiles +are specified in /etc/syslog.conf. At the very least you need +something like: </p> + +<blockquote> +<pre> +/etc/syslog.conf: + mail.err /dev/console + mail.debug /var/log/maillog +</pre> +</blockquote> + +<p> IMPORTANT: the syslogd will not create files. You must create +them before (re)starting syslogd. </p> + +<p> IMPORTANT: on Linux you need to put a "-" character before +the pathname, e.g., -/var/log/maillog, otherwise the syslogd +will use more system resources than Postfix does. </p> + +<p> Hopefully, the number of problems will be small, but it is a good +idea to run every night before the syslog files are rotated: </p> + +<blockquote> +<pre> +# postfix check +# egrep '(reject|warning|error|fatal|panic):' /some/log/file +</pre> +</blockquote> + +<ul> + +<li> <p> The first line (postfix check) causes Postfix to report +file permission/ownership discrepancies. </p> + +<li> <p> The second line looks for problem reports from the mail +software, and reports how effective the relay and junk mail access +blocks are. This may produce a lot of output. You will want to +apply some postprocessing to eliminate uninteresting information. +</p> + +</ul> + +<p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a> +document describes the meaning of the "warning" etc. labels in +Postfix logging. </p> + +</body> + +</html> |