dist/html/PACKAGE_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "https://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Guidelines for Package Builders</title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Guidelines for Package Builders</h1>

<hr>

<h2>Purpose of this document</h2>

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

<h2>General distributions: please provide a small default main.cf
file</h2>

<p> The installed <a href="postconf.5.html">main.cf</a> file must be small. PLEASE resist the
temptation to list all parameters in the <a href="postconf.5.html">main.cf</a> file.  Postfix
is supposed to be easy to configure. Listing all parameters in <a href="postconf.5.html">main.cf</a>
defeats the purpose. It is an invitation for hobbyists to make
random changes without understanding what they do, and gets them
into endless trouble.  </p>

<h2>General distributions: please include README or HTML files</h2>

<p> Please provide the applicable README or HTML files. They are
referenced by the Postfix manual pages and by other files.  Without
README or HTML files, Postfix will be difficult if not impossible
to configure. </p>

<h2>Postfix Installation parameters</h2>

<p> 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 are configurable at compile time, as described in the <a href="INSTALL.html">INSTALL</a>
file. </p>

<h2>Preparing a pre-built package for distribution to other
systems</h2>

<p> 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.
</p>

<p> You can build a pre-built Postfix package as an unprivileged
user. </p>

<p> First compile Postfix. After successful compilation, execute:
</p>

<blockquote> <pre> % <b>make package</b> </pre>
</blockquote>

<p> With Postfix versions before 2.2 you must invoke the post-install
script directly (<tt>% <b>sh post-install</b></tt>). </p>

<p> You will be prompted for installation parameters.  Specify an
install_root directory other than /.  The <a href="postconf.5.html#mail_owner">mail_owner</a> and <a href="postconf.5.html#setgid_group">setgid_group</a>
installation parameter settings will be recorded in the <a href="postconf.5.html">main.cf</a>
file, but they won't take effect until the package is unpacked and
installed on the destination machine. </p>

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

<blockquote>
<pre> % <b>make non-interactive-package install_root=/some/where</b>...
</pre> </blockquote>

<p> With Postfix versions before 2.2 you must invoke the post-install
script directly (<tt>% <b>sh post-install -non-interactive
install_root...</b></tt>). </p>

<p> With Postfix 3.0 and later, the command "make package name=value
..." will replace the string MAIL_VERSION in a configuration parameter
value with the Postfix release version. Do not try to specify
something like $<a href="postconf.5.html#mail_version">mail_version</a> on this command line. This produces
inconsistent results with different versions of the make(1) command.
</p>

<h2>Begin Security Alert</h2>

<p> <b> 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. </b> </p>

<h2>End Security Alert</h2>

<p> Thus, to tar up the pre-built package, take the following steps:
</p>

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

<p>This way you will not include any directories that might cause
trouble upon extraction. </p>

<h2>Installing a pre-built Postfix package</h2>

<ul>

<li> <p> To unpack a pre-built Postfix package, execute the equivalent
of: </p>

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

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

<li> <p> Create the necessary <a href="postconf.5.html#mail_owner">mail_owner</a> account and <a href="postconf.5.html#setgid_group">setgid_group</a>
group for exclusive use by Postfix. </p>

<li> <p> Execute the postfix command to set ownership and permission
of Postfix files and directories, and to update Postfix configuration
files. If necessary, specify any non-default settings for <a href="postconf.5.html#mail_owner">mail_owner</a>
or <a href="postconf.5.html#setgid_group">setgid_group</a> on the postfix command line: </p>

<pre>
# postfix set-permissions upgrade-configuration \
       <a href="postconf.5.html#setgid_group">setgid_group</a>=xxx <a href="postconf.5.html#mail_owner">mail_owner</a>=yyy
</pre>

<p> With Postfix versions before 2.1 you achieve the same result
by invoking the post-install script directly. </p>

</ul>

</body>

</html>