Purpose of this document
========================

This document has hints and tips for those who manage their own
Postfix distribution for internal use, and for those who maintain
Postfix distributions for general use.

General distributions: please provide a small default main.cf file
==================================================================

The installed main.cf file must be small. PLEASE resist the temptation
to list all 100 million Postfix parameters in the main.cf file.
Postfix is supposed to be easy to configure. Listing all 100 million
parameters in main.cf defeats the purpose.

General distributions: please include the sample configuration files
====================================================================

Please provide the sample-xxx files. If these files are not installed
in the same directory as main.cf, PLEASE update the notice at the
top of main.cf that advises the user of the existence of the
sample-xxx files. Without the sample-xxx files, Postfix will be
much more difficult to configure.

Postfix Installation parameters
===============================

Postfix installation is controlled by a dozen installation parameters.
See the postfix-install and post-install files for details.  Most
parameters have system-dependent default settings that aren't
configurable at compile time. This will hopefully be rectified in
a later release.

Preparing a pre-built package for distribution to other systems
===============================================================

You can build a Postfix package on a machine that does not have
Postfix installed on it. All you need is Postfix source code and
a compilation environment that is compatible with the target system.

You can build a pre-built Postfix package as an unprivileged user,
but the result will be cleaner if you build the package as root.

After successful Postfix compilation, execute:

    % sh postfix-install

You will be prompted for installation parameters.  Specify an
install_root directory other than /.  The mail_owner and setgid_group
installation parameter settings will be recorded in the main.cf
file, but they won't take effect until the package is unpacked and
installed on the destination machine.

If you want to fully automate this process, specify all the
non-default installation parameters on the command line:

    % sh postfix-install -non-interactive install_root=/some/where ...

Begin Security Alert.
---------------------

When building an archive for distribution, be sure to archive only
files and symbolic links, not their parent directories.  Otherwise,
unpacking a pre-built Postfix package may mess up permission and/or
ownership of system directories such as / /etc /usr /usr/bin /var
/var/spool and so on. This is especially an issue if you executed
postfix-install (see above) as an unprivileged user.

End Security Alert.
-------------------

Thus, to tar up the pre-built package, take the following steps:

    % cd INSTALL_ROOT
    % rm -f SOMEWHERE/outputfile
    % find . \! -type d -print | xargs tar rf SOMEWHERE/outputfile
    % gzip SOMEWHERE/outputfile

This way you will not include any directories that might cause trouble
upon extraction.

Installing a pre-built Postfix package
======================================

To unpack a pre-built Postfix package, execute the equivalent of:

    # umask 022
    # gzip -d <outputfile.tar.gz | (cd / ; tar xvpf -)

The umask command is necessary for getting the correct permissions
on non-Postfix directories that need to be created in the process.

Create the necessary mail_owner account and setgid_group group for
exclusive use by Postfix.

Execute the post-install script in the Postfix configuration
directory to set ownership and permission of Postfix files and
directories. Specify any non-default settings for mail_owner or
setgid_group on the post-install command line:

    # sh post-install upgrade-package setgid_group=xxx mail_owner=yyy

This will also update the main.cf and master.cf files if necessary.