From 5e61585d76ae77fd5e9e96ebabb57afa4d74880d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 14:06:34 +0200 Subject: Adding upstream version 3.5.24. Signed-off-by: Daniel Baumann --- proto/INSTALL.html | 1672 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1672 insertions(+) create mode 100644 proto/INSTALL.html (limited to 'proto/INSTALL.html') diff --git a/proto/INSTALL.html b/proto/INSTALL.html new file mode 100644 index 0000000..984528c --- /dev/null +++ b/proto/INSTALL.html @@ -0,0 +1,1672 @@ + + + + + + +Postfix Installation From Source Code + + + + + + + +

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:

+ + + +

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

+ +

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:

+ + + +

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 +

+ + + +

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_typehash
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_directoryno
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_directoryno
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
AUXLIBS="object_library..." Specifies +one or more non-default object libraries. Postfix 3.0 and later +specify some of their database library dependencies with 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. +
CCARGS="compiler_arguments..." +Specifies non-default compiler arguments, for example, a non-default +include directory. The following directives turn +off Postfix features at compile time:
-DNO_DB Do not build with Berkeley +DB support. By default, Berkeley DB support is compiled in on +platforms that are known to support this feature. If you override +this, then you probably should also override DEF_DB_TYPE as described +in section 4.6.
-DNO_DNSSEC Do not build with DNSSEC +support, even if the resolver library appears to support it.
-DNO_DEVPOLL Do not build with +Solaris /dev/poll support. By default, /dev/poll +support is compiled in on Solaris versions that are known to support +this feature.
-DNO_EPOLL Do not build with Linux +EPOLL support. By default, EPOLL support is compiled in on platforms +that are known to support this feature.
-DNO_EAI Do not build with EAI +(SMTPUTF8) support. By default, EAI support is compiled in when +the "icuuc" library and header files are found.
-DNO_INLINE Do not require support +for C99 "inline" functions. Instead, implement argument typechecks +for non-printf/scanf-like functions with ternary operators and +unreachable code.
-DNO_IPV6 Do not build with IPv6 +support. By default, IPv6 support is compiled in on platforms that +are known to have IPv6 support. Note: this directive is for debugging +And testing only. It is not guaranteed to work on all platforms. +If you don't want IPv6 support, set "inet_protocols = ipv4" in +main.cf. +
-DNO_KQUEUE Do not build with FreeBSD +/ NetBSD / OpenBSD / MacOSX KQUEUE support. By default, KQUEUE +support is compiled in on platforms that are known to support it. +
-DNO_NIS Do not build with NIS or +NISPLUS support. NIS is not available on some recent Linux +distributions.
-DNO_NISPLUS Do not build with +NISPLUS support. NISPLUS is not available on some recent Solaris +distributions.
-DNO_PCRE Do not build with PCRE +support. By default, PCRE support is compiled in when the +pcre-config utility is installed.
-DNO_POSIX_GETPW_R Disable support +for POSIX getpwnam_r/getpwuid_r. By default Postfix uses +these where they are known to be available.
-DNO_SIGSETJMP Use +setjmp()/longjmp() instead of sigsetjmp()/siglongjmp(). +By default, Postfix uses sigsetjmp()/siglongjmp() when +they are known to be available.
-DNO_SNPRINTF Use sprintf() +instead of snprintf(). By default, Postfix uses +snprintf() except on ancient systems.
DEBUG=debug_level Specifies a +non-default compiler debugging level. The default is "-g". +Specify DEBUG= to turn off debugging.
OPT=optimization_level Specifies +a non-default optimization level. The default is "-O". +Specify OPT= to turn off optimization.
POSTFIX_INSTALL_OPTS=-option... +Specifies options for the postfix-install command, separated +by whitespace. Currently, the only supported option is +"-keep-build-mtime".
SHLIB_CFLAGS=flags Specifies +non-default compiler options for building Postfix dynamically-linked +libraries and database plugins. The typical default is "-fPIC". +
SHLIB_RPATH=rpath Specifies +a non-default runpath for Postfix dynamically-linked libraries. The +typical default is "'-Wl,-rpath,${SHLIB_DIR}'".
SHLIB_SUFFIX=suffix Specifies +a non-default suffix for Postfix dynamically-linked libraries and +database plugins. The typical default is ".so".
WARN="warning_flags..." Specifies +non-default compiler warning 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:

+ + + + +

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.

+ + + +

6.2 - Create account and groups

+ +

Before you install Postfix for the first time you need to +create an account and a group:

+ + + +

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)
+
+
+ + + +

6.4 - Configure Postfix

+ +

Proceed to the section on how you wish to run Postfix on +your particular machine:

+ + + +

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 DEBUG_README +document describes the meaning of the "warning" etc. labels in +Postfix logging.

+ + + + -- cgit v1.2.3