summaryrefslogtreecommitdiffstats
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--INSTALL1162
1 files changed, 1162 insertions, 0 deletions
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..10e6940
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,1162 @@
+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. |
+||______________________________|_____________________________________________|
+|| |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
+
+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.
+