diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 1166 |
1 files changed, 1166 insertions, 0 deletions
@@ -0,0 +1,1166 @@ +Postfix Installation From Source Code + +------------------------------------------------------------------------------- + +1 - Purpose of this document + +If you are using a pre-compiled version of Postfix, you should start with +BASIC_CONFIGURATION_README and the general documentation referenced by it. +INSTALL 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. + +This document describes how to build, install and configure a Postfix system so +that it can do one of the following: + + * Send mail only, without changing an existing Sendmail installation. + * Send and receive mail via a virtual host interface, still without any + change to an existing Sendmail installation. + * Run Postfix instead of Sendmail. + +Topics covered in this document: + + 1. Purpose of this document + 2. Typographical conventions + 3. Documentation + 4. Building on a supported system + 5. Porting Postfix to an unsupported system + 6. Installing the software after successful compilation + 7. Configuring Postfix to send mail only + 8. Configuring Postfix to send and receive mail via virtual interface + 9. Running Postfix instead of Sendmail +10. Mandatory configuration file edits +11. To chroot or not to chroot +12. Care and feeding of the Postfix system + +2 - Typographical conventions + +In the instructions below, a command written as + + # command + +should be executed as the superuser. + +A command written as + + $ command + +should be executed as an unprivileged user. + +3 - Documentation + +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. + +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 bold font. To +print a README file without backspace characters, use the col(1) command. For +example: + + $ col -bx <file | lpr + +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. + + $ export MANPATH; MANPATH="`pwd`/man:$MANPATH" + $ setenv MANPATH "`pwd`/man:$MANPATH" + +Of particular interest is the postconf(5) manual page that lists all the 500+ +configuration parameters. The HTML version of this text makes it easy to +navigate around. + +All Postfix source files have their own built-in manual page. Tools to extract +those embedded manual pages are available in the mantools directory. + +4 - Building on a supported system + +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. + +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. + +Overview of topics: + + * 4.1 - Getting started + * 4.2 - What compiler to use + * 4.3 - Building with Postfix position-independent executables (Postfix >= + 3.0) + * 4.4 - Building with Postfix dynamically-linked libraries and database + plugins (Postfix >= 3.0) + * 4.5 - Building with optional features + * 4.6 - Overriding built-in parameter default settings + * 4.7 - Overriding other compile-time features + * 4.8 - Support for thousands of processes + * 4.9 - Compiling Postfix, at last + +4.1 - Getting started + +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. + +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. + +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: + + $ make -f Makefile.init makefiles + +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: + + $ make tidy + +This will get rid of any system dependencies left over from compiling the +software elsewhere. + +4.2 - What compiler to use + +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: + + $ make + +To build with a non-default compiler, you need to specify the name of the +compiler. Here are a few examples: + + $ 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 + +and so on. In some cases, optimization will be turned off automatically. + +4.3 - Building with Postfix position-independent executables (Postfix >= 3.0) + +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): + + $ make makefiles pie=yes ...other arguments... + +(Specify "make makefiles pie=no" to explicitly disable Postfix position- +independent executable support). + +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). + +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. + +4.4 - Building with Postfix dynamically-linked libraries and database plugins +(Postfix >= 3.0) + +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. + +Overview of topics: + + * 4.4.1 Turning on Postfix dynamically-linked library support + * 4.4.2 Turning on Postfix database-plugin support + * 4.4.3 Customizing Postfix dynamically-linked libraries and database plugins + * 4.4.4 Tips for distribution maintainers + +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. + +4.4.1 Turning on Postfix dynamically-linked library support + +Postfix can be built with Postfix dynamically-linked libraries (files typically +named libpostfix-*.so). Postfix dynamically-linked libraries add minor run-time +overhead and result in significantly-smaller Postfix executable files. + +Specify "shared=yes" on the "make makefiles" command line to build Postfix with +dynamically-linked library support. + + $ make makefiles shared=yes ...other arguments... + $ make + +(Specify "make makefiles shared=no" to explicitly disable Postfix dynamically- +linked library support). + +This installs dynamically-linked libraries in $shlib_directory, typically /usr/ +lib/postfix or /usr/local/lib/postfix, with file names libpostfix-name.so, +where the name is a source-code directory name such as "util" or "global". + +See section 4.4.3 "Customizing Postfix dynamically-linked libraries and +database plugins" below for how to customize the Postfix dynamically-linked +library location, including support to upgrade a running mail system safely. + +4.4.2 Turning on Postfix database-plugin support + +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 cdb:, ldap:, lmdb:, mysql:, pcre:, +pgsql:, sdbm:, and sqlite: database clients. Dynamic loading is useful when you +distribute or install pre-compiled Postfix packages. + +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. + + $ make makefiles dynamicmaps=yes ...other arguments... + $ make + +(Specify "make makefiles dynamicmaps=no" to explicitly disable Postfix +database-plugin support). + +This implicitly enables dynamically-linked library support, installs the +configuration file dynamicmaps.cf in $meta_directory (usually, /etc/postfix or +/usr/local/etc/postfix), and installs database plugins in $shlib_directory (see +above). Database plugins are named postfix-type.so where the type is a database +type such as "cdb" or "ldap". + + NOTE: The Postfix 3.0 build procedure expects that you specify database + library dependencies with variables named AUXLIBS_CDB, AUXLIBS_LDAP, etc. + With Postfix 3.0 and later, the old AUXLIBS variable still supports + building a statically-loaded database client, but only the new AUXLIBS_CDB + etc. variables support building a dynamically-loaded or statically-loaded + CDB etc. database client. See CDB_README, LDAP_README, etc. for details. + + 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. + +See the next section for how to customize the location and version of Postfix +database plugins and the location of the file dynamicmaps.cf. + +4.4.3 Customizing Postfix dynamically-linked libraries and database plugins + +Customizing build-time and run-time options for Postfix dynamically-linked +libraries and database plugins + +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. + + $ make makefiles SHLIB_CFLAGS=flags SHLIB_RPATH=rpath SHLIB_SUFFIX=suffix + ...other arguments... + $ make + +See section 4.7 "Overriding other compile-time features" below for details. + +Customizing the location of Postfix dynamically-linked libraries and database +plugins + +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. + +To override the default location of Postfix dynamically-linked libraries and +database plugins specify, for example: + + $ make makefiles shared=yes shlib_directory=/usr/local/lib/postfix ... + +If you intend to upgrade Postfix without stopping the mail system, then you +should append the Postfix release version to the shlib_directory pathname, to +eliminate the possibility that programs will link with dynamically-linked +libraries or database plugins from the wrong Postfix version. For example: + + $ make makefiles shared=yes \ + shlib_directory=/usr/local/lib/postfix/MAIL_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 $mail_version on this command line. This +produces inconsistent results with different versions of the make(1) command. + +You can change the shlib_directory setting after Postfix is built, with "make +install" or "make upgrade". However, you may have to run ldconfig if you change +shlib_directory 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 $shlib_directory location. + + # make upgrade shlib_directory=/usr/local/lib/postfix ... + # make install shlib_directory=/usr/local/lib/postfix ... + +To append the Postfix release version to the pathname if you intend to upgrade +Postfix without stopping the mail system: + + # make upgrade shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... + # make install shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... + +See also the comments above for appending MAIL_VERSION with the "make +makefiles" command. + +Customizing the location of dynamicmaps.cf and other files + +The meta_directory parameter has the same default setting as the +config_directory parameter, typically /etc/postfix or /usr/local/etc/postfix. + +You can override the default meta_directory location at compile time or after +Postfix is built. To override the default location at compile time specify, for +example: + + % make makefiles meta_directory=/usr/libexec/postfix ... + +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 $mail_version on this +command line. This produces inconsistent results with different versions of the +make(1) command. + +You can override the meta_directory setting after Postfix is built, with "make +install" or "make upgrade". + + # make upgrade meta_directory=/usr/libexec/postfix ... + # make install meta_directory=/usr/libexec/postfix ... + +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 $mail_version on this command line. This produces +inconsistent results with different versions of the make(1) command. + +4.4.4 Tips for distribution maintainers + + * The shlib_directory parameter setting also provides the default directory + for database plugin files with a relative pathname in the file + dynamicmaps.cf. + + * The meta_directory parameter specifies the location of the files + dynamicmaps.cf, postfix-files, and some multi-instance template files. The + meta_directory parameter has the same default value as the config_directory + parameter (typically, /etc/postfix or /usr/local/etc/postfix). For + backwards compatibility with Postfix 2.6 .. 2.11, specify "meta_directory = + $daemon_directory" in main.cf before installing or upgrading Postfix, or + specify "meta_directory = /path/name" on the "make makefiles", "make + install" or "make upgrade" command line. + + * 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. + + * 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. + + * 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. + +4.5 - Building with optional features + +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: + + _____________________________________________________________ + |Optional feature |Document |Availability| + |__________________________________|_____________|____________| + |Berkeley DB database |DB_README |Postfix 1.0 | + |__________________________________|_____________|____________| + |LMDB database |LMDB_README |Postfix 2.11| + |__________________________________|_____________|____________| + |LDAP database |LDAP_README |Postfix 1.0 | + |__________________________________|_____________|____________| + |MySQL database |MYSQL_README |Postfix 1.0 | + |__________________________________|_____________|____________| + |Perl compatible regular expression|PCRE_README |Postfix 1.0 | + |__________________________________|_____________|____________| + |PostgreSQL database |PGSQL_README |Postfix 2.0 | + |__________________________________|_____________|____________| + |SASL authentication |SASL_README |Postfix 1.0 | + |__________________________________|_____________|____________| + |SQLite database |SQLITE_README|Postfix 2.8 | + |__________________________________|_____________|____________| + |STARTTLS session encryption |TLS_README |Postfix 2.2 | + |__________________________________|_____________|____________| + +Note: IP version 6 support is compiled into Postfix on operating systems that +have IPv6 support. See the IPV6_README file for details. + +4.6 - Overriding built-in parameter default settings + +4.6.1 - Postfix 3.0 and later + +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: + + $ make makefiles config_directory=/some/where ...other arguments... + $ make + +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 $mail_version on this +command line. This produces inconsistent results with different versions of the +make(1) command. + +Parameters whose defaults can be specified in this way are listed below. See +the postconf(5) manpage for a description (command: "nroff -man man/man5/ +postconf.5 | less"). + + __________________________________________ + |parameter name |typical default | + |_____________________|____________________| + |command_directory |/usr/sbin | + |_____________________|____________________| + |config_directory |/etc/postfix | + |_____________________|____________________| + |default_database_type|hash | + |_____________________|____________________| + |daemon_directory |/usr/libexec/postfix| + |_____________________|____________________| + |data_directory |/var/lib/postfix | + |_____________________|____________________| + |html_directory |no | + |_____________________|____________________| + |mail_spool_directory |/var/mail | + |_____________________|____________________| + |mailq_path |/usr/bin/mailq | + |_____________________|____________________| + |manpage_directory |/usr/local/man | + |_____________________|____________________| + |meta_directory |/etc/postfix | + |_____________________|____________________| + |newaliases_path |/usr/bin/newaliases | + |_____________________|____________________| + |openssl_path |openssl | + |_____________________|____________________| + |queue_directory |/var/spool/postfix | + |_____________________|____________________| + |readme_directory |no | + |_____________________|____________________| + |sendmail_path |/usr/sbin/sendmail | + |_____________________|____________________| + |shlib_directory |/usr/lib/postfix | + |_____________________|____________________| + +4.6.2 - All Postfix versions + +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: + + $ make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"' + $ make + +IMPORTANT: Be sure to get the quotes right. These details matter a lot. + +Parameters whose defaults can be specified in this way are listed below. See +the postconf(5) manpage for a description (command: "nroff -man man/man5/ +postconf.5 | less"). + + ____________________________________________________________ + |Macro name |default value for |typical default | + |_________________|_____________________|____________________| + |DEF_COMMAND_DIR |command_directory |/usr/sbin | + |_________________|_____________________|____________________| + |DEF_CONFIG_DIR |config_directory |/etc/postfix | + |_________________|_____________________|____________________| + |DEF_DB_TYPE |default_database_type|hash | + |_________________|_____________________|____________________| + |DEF_DAEMON_DIR |daemon_directory |/usr/libexec/postfix| + |_________________|_____________________|____________________| + |DEF_DATA_DIR |data_directory |/var/lib/postfix | + |_________________|_____________________|____________________| + |DEF_MAILQ_PATH |mailq_path |/usr/bin/mailq | + |_________________|_____________________|____________________| + |DEF_HTML_DIR |html_directory |no | + |_________________|_____________________|____________________| + |DEF_MANPAGE_DIR |manpage_directory |/usr/local/man | + |_________________|_____________________|____________________| + |DEF_NEWALIAS_PATH|newaliases_path |/usr/bin/newaliases | + |_________________|_____________________|____________________| + |DEF_QUEUE_DIR |queue_directory |/var/spool/postfix | + |_________________|_____________________|____________________| + |DEF_README_DIR |readme_directory |no | + |_________________|_____________________|____________________| + |DEF_SENDMAIL_PATH|sendmail_path |/usr/sbin/sendmail | + |_________________|_____________________|____________________| + +Note: the data_directory parameter (for caches and pseudo-random numbers) was +introduced with Postfix version 2.5. + +4.7 - Overriding other compile-time features + +The general method to override Postfix compile-time features is as follows: + + $ make makefiles name=value name=value... + $ make + +The following is an extensive list of names and values. + + _____________________________________________________________________________ +|Name/Value |Description | +|_______________________________|_____________________________________________| +| |Specifies one or more non-default object | +| |libraries. Postfix 3.0 and later specify some| +| |of their database library dependencies with | +|AUXLIBS="object_library..." |AUXLIBS_CDB, AUXLIBS_LDAP, AUXLIBS_LMDB, | +| |AUXLIBS_MYSQL, AUXLIBS_PCRE, AUXLIBS_PGSQL, | +| |AUXLIBS_SDBM, and AUXLIBS_SQLITE, | +| |respectively. | +|_______________________________|_____________________________________________| +|CC=compiler_command |Specifies a non-default compiler. On many | +| |systems, the default is gcc. | +|_______________________________|_____________________________________________| +| |Specifies non-default compiler arguments, for| +|CCARGS="compiler_arguments..." |example, a non-default include directory. The| +| |following directives turn off Postfix | +| |features at compile time: | +|_______________________________|_____________________________________________| +|| |Do not build with Berkeley DB support. By | +|| |default, Berkeley DB support is compiled in | +||-DNO_DB |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. | +||______________________________|_____________________________________________| +||-DNO_DNSSEC |Do not build with DNSSEC support, even if the| +|| |resolver library appears to support it. | +||______________________________|_____________________________________________| +|| |Do not build with Solaris /dev/poll support. | +||-DNO_DEVPOLL |By default, /dev/poll support is compiled in | +|| |on Solaris versions that are known to support| +|| |this feature. | +||______________________________|_____________________________________________| +|| |Do not build with Linux EPOLL support. By | +||-DNO_EPOLL |default, EPOLL support is compiled in on | +|| |platforms that are known to support this | +|| |feature. | +||______________________________|_____________________________________________| +|| |Do not build with EAI (SMTPUTF8) support. By | +||-DNO_EAI |default, EAI support is compiled in when the | +|| |"icuuc" library and header files are found. | +||______________________________|_____________________________________________| +|| |Do not require support for C99 "inline" | +|| |functions. Instead, implement argument | +||-DNO_INLINE |typechecks for non-printf/scanf-like | +|| |functions with ternary operators and | +|| |unreachable code. | +||______________________________|_____________________________________________| +|| |Do not build with IPv6 support. By default, | +|| |IPv6 support is compiled in on platforms that| +|| |are known to have IPv6 support. Note: this | +||-DNO_IPV6 |directive is for debugging And testing only. | +|| |It is not guaranteed to work on all | +|| |platforms. If you don't want IPv6 support, | +|| |set "inet_protocols = ipv4" in main.cf. | +||______________________________|_____________________________________________| +|| |Do not build with FreeBSD / NetBSD / OpenBSD | +||-DNO_KQUEUE |/ MacOSX KQUEUE support. By default, KQUEUE | +|| |support is compiled in on platforms that are | +|| |known to support it. | +||______________________________|_____________________________________________| +|| |Do not build with NIS or NISPLUS support. NIS| +||-DNO_NIS |is not available on some recent Linux | +|| |distributions. | +||______________________________|_____________________________________________| +|| |Do not build with NISPLUS support. NISPLUS is| +||-DNO_NISPLUS |not available on some recent Solaris | +|| |distributions. | +||______________________________|_____________________________________________| +|| |Do not build with PCRE support. By default, | +||-DNO_PCRE |PCRE support is compiled in when the pcre- | +|| |config utility is installed. | +||______________________________|_____________________________________________| +|| |Disable support for POSIX getpwnam_r/ | +||-DNO_POSIX_GETPW_R |getpwuid_r. By default Postfix uses these | +|| |where they are known to be available. | +||______________________________|_____________________________________________| +||-DNO_RES_NCALLS |Do not build with the threadsafe resolver(5) | +|| |API (res_ninit() etc.). | +||______________________________|_____________________________________________| +|| |Use setjmp()/longjmp() instead of sigsetjmp | +||-DNO_SIGSETJMP |()/siglongjmp(). By default, Postfix uses | +|| |sigsetjmp()/siglongjmp() when they are known | +|| |to be available. | +||______________________________|_____________________________________________| +|| |Use sprintf() instead of snprintf(). By | +||-DNO_SNPRINTF |default, Postfix uses snprintf() except on | +|| |ancient systems. | +||______________________________|_____________________________________________| +| |Specifies a non-default compiler debugging | +|DEBUG=debug_level |level. The default is "-g". Specify DEBUG= to| +| |turn off debugging. | +|_______________________________|_____________________________________________| +| |Specifies a non-default optimization level. | +|OPT=optimization_level |The default is "-O". Specify OPT= to turn off| +| |optimization. | +|_______________________________|_____________________________________________| +| |Specifies options for the postfix-install | +|POSTFIX_INSTALL_OPTS=-option...|command, separated by whitespace. Currently, | +| |the only supported option is "-keep-build- | +| |mtime". | +|_______________________________|_____________________________________________| +| |Specifies non-default compiler options for | +|SHLIB_CFLAGS=flags |building Postfix dynamically-linked libraries| +| |and database plugins. The typical default is | +| |"-fPIC". | +|_______________________________|_____________________________________________| +| |Specifies a non-default runpath for Postfix | +|SHLIB_RPATH=rpath |dynamically-linked libraries. The typical | +| |default is "'-Wl,-rpath,${SHLIB_DIR}'". | +|_______________________________|_____________________________________________| +| |Specifies a non-default suffix for Postfix | +|SHLIB_SUFFIX=suffix |dynamically-linked libraries and database | +| |plugins. The typical default is ".so". | +|_______________________________|_____________________________________________| +| |Specifies non-default compiler warning | +|WARN="warning_flags..." |options for use when "make" is invoked in a | +| |source subdirectory only. | +|_______________________________|_____________________________________________| + +4.8 - Support for thousands of processes + +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 anvil(8) server has one connection per smtpd(8) process. + +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: + + * BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), + * Solaris 8 /dev/poll, + * Linux 2.6 epoll(4). + +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: + + $ make makefiles CCARGS=-DFD_SETSIZE=2048 + +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. + +But wait, there is more: none of this will work unless the operating system is +configured to handle thousands of connections. See the TUNING_README guide for +examples of how to increase the number of open sockets or files. + +4.9 - Compiling Postfix, at last + +If the command + + $ make + +is successful, then you can proceed to install Postfix (section 6). + +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 +http://www.postfix.org/. + +5 - Porting Postfix to an unsupported system + +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. + +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. + +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. + +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. + +6 - Installing the software after successful compilation + +This text describes how to install Postfix from source code. See the +PACKAGE_README file if you are building a package for distribution to other +systems. + +6.1 - Save existing Sendmail binaries + +IMPORTANT: 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. + + * 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. + + * If your system has no mail switch mechanism, execute the following commands + (your sendmail, newaliases and mailq programs may be in a different place): + + # 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 + +6.2 - Create account and groups + +Before you install Postfix for the first time you need to create an account and +a group: + + * 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: + + /etc/passwd: + postfix:*:12345:12345:postfix:/no/where:/no/shell + + /etc/group: + postfix:*:12345: + + Note: there should be no whitespace before "postfix:". + + * 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: + + /etc/group: + postdrop:*:54321: + + Note: there should be no whitespace before "postdrop:". + +6.3 - Install Postfix + +To install or upgrade Postfix from compiled source code, run one of the +following commands as the super-user: + + # make install (interactive version, first time install) + + # make upgrade (non-interactive version, for upgrades) + + * The interactive version ("make install") asks for pathnames for Postfix + data and program files, and stores your preferences in the main.cf file. If + you don't want Postfix to overwrite non-Postfix "sendmail", "mailq" and + "newaliases" files, specify pathnames that end in ".postfix". + + * The non-interactive version ("make upgrade") needs the /etc/postfix/main.cf + file from a previous installation. If the file does not exist, use + interactive installation ("make install") instead. + + * 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 main.cf settings. + + 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 $mail_version on this + command line. This produces inconsistent results with different versions of + the make(1) command. + +6.4 - Configure Postfix + +Proceed to the section on how you wish to run Postfix on your particular +machine: + + * Send mail only, without changing an existing Sendmail installation (section + 7). + + * Send and receive mail via a virtual host interface, still without any + change to an existing Sendmail installation (section 8). + + * Run Postfix instead of Sendmail (section 9). + +7 - Configuring Postfix to send mail only + +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. + +Follow the instructions in the "Mandatory configuration file edits" in section +10, and review the "To chroot or not to chroot" text in section 11. + +You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, in order +to avoid conflicts with the real sendmail. Put a "#" character in front of the +line that defines the smtpd service: + + /etc/postfix/master.cf: + #smtp inet n - n - - smtpd + +Start the Postfix system: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +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. + + $ egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + $ mailq + + $ sendmail -bp + + $ postqueue -p + +See also the "Care and feeding" section 12 below. + +8 - Configuring Postfix to send and receive mail via virtual interface + +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. + +To create a virtual network interface address, study your system ifconfig +manual page. The command syntax could be any of: + + # ifconfig le0:1 <address> netmask <mask> up + # ifconfig en0 alias <address> netmask 255.255.255.255 + +In the /etc/postfix/main.cf file, I would specify + + /etc/postfix/main.cf: + myhostname = virtual.host.tld + inet_interfaces = $myhostname + mydestination = $myhostname + +Follow the instructions in the "Mandatory configuration file edits" in section +10, and review the "To chroot or not to chroot" text in section 11. + +Start the Postfix system: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +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. + + $ egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + $ mailq + + $ sendmail -bp + + $ postqueue -p + +See also the "Care and feeding" section 12 below. + +9 - Running Postfix instead of Sendmail + +Prior to installing Postfix you should save 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: + + # /usr/sbin/sendmail.OFF -q + +Note: this is old sendmail syntax. Newer versions use separate processes for +mail submission and for running the queue. + +After you have visited the "Mandatory configuration file edits" section below, +you can start the Postfix system with: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +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. + + $ egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + $ mailq + + $ sendmail -bp + + $ postqueue -p + +See also the "Care and feeding" section 12 below. + +10 - Mandatory configuration file edits + +Note: the material covered in this section is covered in more detail in the +BASIC_CONFIGURATION_README document. The information presented below is +targeted at experienced system administrators. + +10.1 - Postfix configuration files + +By default, Postfix configuration files are in /etc/postfix. The two most +important files are main.cf and master.cf; these files must be owned by root. +Giving someone else write permission to main.cf or master.cf (or to their +parent directories) means giving root privileges to that person. + +In /etc/postfix/main.cf, you will have to set up a minimal number of +configuration parameters. Postfix configuration parameters resemble shell +variables, with two important differences: the first one is that Postfix does +not know about quotes like the UNIX shell does. + +You specify a configuration parameter as: + + /etc/postfix/main.cf: + parameter = value + +and you use it by putting a "$" character in front of its name: + + /etc/postfix/main.cf: + other_parameter = $parameter + +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. + +Whenever you make a change to the main.cf or master.cf file, execute the +following command in order to refresh a running mail system: + + # postfix reload + +10.2 - Default domain for unqualified addresses + +First of all, you must specify what domain will be appended to an unqualified +address (i.e. an address without @domain.tld). The "myorigin" parameter +defaults to the local hostname, but that is probably OK only for very small +sites. + +Some examples (use only one): + + /etc/postfix/main.cf: + myorigin = $myhostname (send mail as "user@$myhostname") + myorigin = $mydomain (send mail as "user@$mydomain") + +10.3 - What domains to receive locally + +Next you need to specify what mail addresses Postfix should deliver locally. + +Some examples (use only one): + + /etc/postfix/main.cf: + mydestination = $myhostname, localhost.$mydomain, localhost + mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain + mydestination = $myhostname + +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. + +10.4 - Proxy/NAT interface addresses + +The proxy_interfaces 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. + +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. + +Example: host behind NAT box running a backup MX host. + + /etc/postfix/main.cf: + proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) + +10.5 - What local clients to relay mail from + +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: + + /etc/postfix/main.cf: + mynetworks = 168.100.189.0/28, 127.0.0.0/8 + +10.6 - What relay destinations to accept from strangers + +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 $mydestination. This may +give relay permission for too many destinations. Recommended settings (use only +one): + + /etc/postfix/main.cf: + relay_domains = (do not forward mail from strangers) + relay_domains = $mydomain (my domain and subdomains) + relay_domains = $mydomain, other.domain.tld, ... + +10.7 - Optional: configure a smart host for remote delivery + +If you're behind a firewall, you should set up a relayhost. 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. + +Some examples (use only one): + + /etc/postfix/main.cf: + relayhost = $mydomain + relayhost = [mail.$mydomain] + +The form enclosed with [] eliminates DNS MX lookups. + +By default, the SMTP client will do DNS lookups even when you specify a relay +host. If your machine has no access to a DNS server, turn off SMTP client DNS +lookups like this: + + /etc/postfix/main.cf: + disable_dns_lookups = yes + +The STANDARD_CONFIGURATION_README file has more hints and tips for firewalled +and/or dial-up networks. + +10.8 - Create the aliases database + +Postfix uses a Sendmail-compatible aliases(5) table to redirect mail for local +(8) 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 +alias_maps" will tell you the exact location of the text file. + +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. + + /etc/aliases: + root: you + postmaster: root + postfix: root + bin: root + etcetera... + +Note: there should be no whitespace before the ":". + +Finally, build the indexed aliases file with one of the following commands: + + # newaliases + # sendmail -bi + # postalias /etc/aliases (pathname is system dependent!) + +11 - To chroot or not to chroot + +Postfix daemon processes can be configured (via master.cf) 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. + +With the exception of Postfix daemons that deliver mail locally and/or that +execute non-Postfix commands, every Postfix daemon can run chrooted. + +Sites with high security requirements should consider to chroot all daemons +that talk to the network: the smtp(8) and smtpd(8) processes, and perhaps also +the lmtp(8) client. The author's own porcupine.org mail server runs all daemons +chrooted that can be chrooted. + +The default /etc/postfix/master.cf file specifies that no Postfix daemon runs +chrooted. In order to enable chroot operation, edit the file /etc/postfix/ +master.cf. Instructions are in the file. + +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. + +Additionally, you almost certainly need to configure syslogd so that it listens +on a socket inside the Postfix queue directory. Examples for specific systems: + +FreeBSD: + + # mkdir -p /var/spool/postfix/var/run + # syslogd -l /var/spool/postfix/var/run/log + +Linux, OpenBSD: + + # mkdir -p /var/spool/postfix/dev + # syslogd -a /var/spool/postfix/dev/log + +12 - Care and feeding of the Postfix system + +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: + + /etc/syslog.conf: + mail.err /dev/console + mail.debug /var/log/maillog + +IMPORTANT: the syslogd will not create files. You must create them before +(re)starting syslogd. + +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. + +Hopefully, the number of problems will be small, but it is a good idea to run +every night before the syslog files are rotated: + + # postfix check + # egrep '(reject|warning|error|fatal|panic):' /some/log/file + + * The first line (postfix check) causes Postfix to report file permission/ + ownership discrepancies. + + * 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. + +The DEBUG_README document describes the meaning of the "warning" etc. labels in +Postfix logging. + |