source: server/mail/postfix.xml@ 3bfd1d6

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

<!ENTITY postfix-download-http "http://www.mirrorspace.org/postfix/official/postfix-&postfix-version;.tar.gz">
<!ENTITY postfix-download-ftp "ftp://ftp.porcupine.org/mirrors/postfix-release/official/postfix-&postfix-version;.tar.gz">
<!ENTITY postfix-size "1.9 MB">
<!ENTITY postfix-buildsize "81 MB">
<!ENTITY postfix-time "0.29 SBU">

]>

<sect1 id="postfix" xreflabel="Postfix-&postfix-version;">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?dbhtml filename="postfix.html"?>
<title>Postfix-&postfix-version;</title>

<sect2>
<title>Introduction to Postfix</title>

<para>The <application>Postfix</application> package contains a Mail
Transport Agent (<acronym>MTA</acronym>). This is useful for sending email 
to other users of your host machine.  It can also be configured to be a 
central mail server for your domain, a mail relay agent or simply a mail 
delivery agent to your local Internet Service Provider
(<acronym>ISP</acronym>).</para>

<sect3><title>Package information</title>
<itemizedlist spacing='compact'>
<listitem><para>Download (HTTP): <ulink
url="&postfix-download-http;"/></para></listitem>
<listitem><para>Download (FTP): <ulink
url="&postfix-download-ftp;"/></para></listitem>
<listitem><para>Download size: &postfix-size;</para></listitem>
<listitem><para>Estimated disk space required:
&postfix-buildsize;</para></listitem>
<listitem><para>Estimated build time:
&postfix-time;</para></listitem></itemizedlist>
</sect3>

<sect3><title><application>Postfix</application> dependencies</title>
<sect4><title>Required</title>
<para><xref linkend="db"/></para></sect4>
<sect4><title>Optional</title>
<para>
<xref linkend="pcre"/>,
<xref linkend="mysql"/>,
<xref linkend="postgresql"/>,
<xref linkend="openldap"/>,
<xref linkend="openssl"/> and
<xref linkend="cyrus-sasl"/>
</para></sect4>
</sect3>

</sect2>

<sect2>
<title>Installation of <application>Postfix</application></title>

<sect3><title>Configuring the build</title>

<para>The <application>Postfix</application> source tree does not contain a 
<filename>configure</filename> script, rather the makefile in the
top-level directory contains a <parameter>makefiles</parameter> target that
regenerates all the other makefiles in the build tree.  If you wish to
use additional software such as a database back-end for virtual users, or
<acronym>TLS</acronym>/<acronym>SSL</acronym> authentication, you'll
need to regenerate the makefiles using one or more of the appropriate
<envar>CCARGS</envar> and <envar>AUXLIBS</envar> settings listed below.</para>

<para>Here is an example that combines the
<acronym>TLS</acronym>/<acronym>SSL</acronym> and
<application>Cyrus-SASL</application> arguments:</para>

<screen><userinput><command>make makefiles \
CCARGS="-DHAS_SSL -DUSE_SASL_AUTH -I/usr/include/openssl -I/usr/include/sasl" \
AUXLIBS="-L/usr/lib -R/usr/lib -lssl -lcrypto -lsasl2"</command></userinput></screen>

<sect4><title>SSL/TLS authentication</title>
<para>To use <acronym>SSL</acronym>/<acronym>TLS</acronym>
authentication with <application>Postfix</application>, you'll first
need to apply a patch availible from 
<ulink url="ftp://ftp.aet.tu-cottbus.de/pub/postfix_tls/pfixtls-0.8.18-2.1.3-0.9.7d.tar.gz"/>.
Unzip the patch tarball, and apply with the following commands:</para>

<screen><userinput><command>patch -p1 &lt; ../pfixtls-0.8.18-2.1.3-0.9.7d/pfixtls.diff</command></userinput></screen>

<para>You will need to pass the following values to the <command>make
makefiles</command> command:</para>

<screen><userinput>CCARGS="-DHAS_SSL -I/usr/include/openssl" \
AUXLIBS="-L/usr/lib -lssl -lcrypto"</userinput></screen>

<para>To use <acronym>SSL</acronym> or <acronym>TLS</acronym> you will
also need <xref linkend="cyrus-sasl"/>.</para>
</sect4>

<sect4><title>Cyrus-SASL</title>
<para>To use <application>Cyrus-SASL</application> with
<application>Postfix</application>, use the following arguments:</para>

<screen><userinput>CCARGS="-DUSE_SASL_AUTH -I/usr/include/sasl" \
AUXLIBS="-L/usr/lib -R/usr/lib -lsasl2"</userinput></screen>
</sect4>

<sect4><title>OpenLDAP</title>
<para>To use <application>OpenLDAP</application> with 
<application>Postfix</application>, use the following arguments:</para>

<screen><userinput>CCARGS="-I/usr/include -DHAS_LDAP" \
AUXLIBS="-L/usr/lib -lldap -llber"</userinput></screen>
</sect4>

<sect4><title>MySQL</title>
<para>To use <application>MySQL</application> with
<application>Postfix</application>, use the following arguments:</para>

<screen><userinput>CCARGS="-DHAS_MYSQL -I/usr/include/mysql" \
AUXLIBS="-L/usr/lib -lmysqlclient -lz -lm"</userinput></screen>
</sect4>

<sect4><title>PostgreSQL</title>
<para>To use <application>PostgreSQL</application> with
<application>Postfix</application>, use the following arguments:</para>

<screen><userinput>CCARGS="-DHAS_PGSQL -I/usr/include/postgresql" \
AUXLIBS="-L/usr/lib -lpq -lz -lm"</userinput></screen>
</sect4>

</sect3>

<sect3><title>Installing Postfix</title>

<para>Before you compile the program, you need to create users and groups that
will be expected to be in place when the install script executes.  Add the
users and groups with the following commands:</para>

<screen><userinput><command>groupadd postfix &amp;&amp;
groupadd postdrop &amp;&amp;
groupadd -g 65534 nogroup &amp;&amp;
useradd -c postfix -d /dev/null -g postfix -s /bin/false postfix &amp;&amp;
useradd -c nobody -d /home -g nogroup -s /bin/bash -u 65534 nobody &amp;&amp;
chown postfix:postfix /var/mail</command></userinput></screen>

<para>Install <application>Postfix</application> by running the
following commands:</para>

<screen><userinput><command>make &amp;&amp;
sh postfix-install daemon_directory=/usr/sbin \
                   manpage_directory=/usr/share/man \
                   sample_directory=/usr/share/doc/postfix \
                   -non-interactive</command></userinput></screen>

<para>The final installation step is to install the program's documentation with
the following commands:</para>

<screen><userinput><command>install -d /usr/share/doc/postfix &amp;&amp;
cp -rf html/* /usr/share/doc/postfix</command></userinput></screen>
</sect3></sect2>

<sect2>
<title>Command explanations</title>

<para><command>sh postfix-install ... -non-interactive</command> : This keeps
the install script from asking any questions, thereby accepting default
destination directories in all but the three cases explicitly mentioned.</para>

<para><command>make makefiles</command> :  This command rebuilds the
makefiles throughout the source tree to use the options contained in the
<envar>CCARGS</envar> and <envar>AUXLIBS</envar> variables.</para>

</sect2>

<sect2>
<title>Configuring <application>Postfix</application></title>

<sect3><title>Config files</title>
<para><filename>/etc/aliases</filename>,
<filename>/etc/postfix/main.cf</filename> and
<filename>/etc/postfix/master.cf</filename></para>
</sect3>

<sect3><title>Configuration Information</title>

<screen><userinput><command>cat &gt;&gt; /etc/aliases &lt;&lt; "EOF"</command>
# Begin /etc/aliases

MAILER-DAEMON:    postmaster
postmaster:       root

root:             LOGIN
# End /etc/aliases
<command>EOF</command></userinput></screen>

<note><para>To protect an existing <filename>/etc/aliases</filename> file, the
above command appends these aliases to it if it exists. This file should be
checked and duplicate aliases removed, if present.</para></note>

<para>The <filename>/etc/aliases</filename> file that was just created or
appended, the <filename>main.cf</filename> and the
<filename>master.cf</filename> must be personalized for your system. The
<filename>aliases</filename> file needs your non-root login identity so mail
addressed to root can be forwarded to you at the user level. The
<filename>main.cf</filename> file needs your fully qualified hostname. All of
these edits can be done with sed commands entered into the console with
appropriate substitutions of your non-root login name for
<replaceable>[user]</replaceable> and your fully qualified hostname for
<replaceable>[localhost.localdomain]</replaceable>. You will find the
<filename>main.cf</filename> file is self documenting, so load it into your
editor to make the changes you need for your situation.</para>

<screen><userinput><command>sed -i "s/LOGIN/<replaceable>[user]</replaceable>/" /etc/aliases &amp;&amp;
sed -i "s/#myhostname = host.domain.tld/myhostname = \ 
        <replaceable>[localhost.localdomain]</replaceable>/" /etc/postfix/main.cf &amp;&amp;
/usr/bin/newaliases &amp;&amp;
/usr/sbin/postfix start</command></userinput></screen></sect3>

<sect3><title>Postfix init.d script</title>

<para>To automate the running of Postfix at startup, install the 
<filename>/etc/rc.d/init.d/postfix</filename> init script included in the 
<xref linkend="intro-important-bootscripts"/> package.</para>

<screen><userinput><command>make install-postfix</command></userinput></screen>

</sect3>

</sect2>

<sect2>
<title>Contents</title>

<para>The <application>Postfix</application> package contains 
<command>bounce</command>, <command>cleanup</command>, 
<command>error</command>, <command>flush</command>, 
<command>lmtp</command>, <command>local</command>, 
<command>mailq</command>, <command>master</command>, 
<command>newaliases</command>, <command>nqmgr</command>, 
<command>pickup</command>, <command>pipe</command>, 
<command>postalias</command>, <command>postcat</command>,
<command>postconf</command>, <command>postdrop</command>,
<command>postfix</command>, <command>postkick</command>,
<command>postlock</command>, <command>postlog</command>,
<command>postmap</command>, <command>postqueue</command>,
<command>postsuper</command>, <command>qmgr</command>, 
<command>qmqpd</command>, <command>sendmail</command>,
<command>showq</command>, <command>smtp</command>, 
<command>smtpd</command>, <command>spawn</command>, 
<command>trivial-rewrite</command>, and <command>virtual</command>.</para>

</sect2>

<sect2><title>Description</title>

<sect3><title>postfix</title>
<para><command>postfix</command> is the program that starts and stops the mail 
delivery system.</para></sect3>

<sect3><title>master</title>
<para><command>master</command> is the resident process that runs
<filename>bounce</filename>, <filename>cleanup</filename>,
<filename>error</filename>, <filename>flush</filename>, 
<filename>lmtp</filename>, <filename>local</filename>,
<filename>nqmgr</filename>, <filename>pickup</filename>,
<filename>pipe</filename>, <filename>qmgr</filename>,
<filename>qmqpd</filename>, <filename>showq</filename>,
<filename>smtp</filename>, <filename>smtpd</filename>,
<filename>spawn</filename>, <filename>trivial-rewrite</filename> and
<filename>virtual</filename> on demand. These programs are not designed to 
work as user commands.</para></sect3>

<sect3><title>postqueue</title>
<para><command>postqueue</command> implements the
<application>Postfix</application> user interface for 
queue management.  It implements all the operations that are traditionally 
available via the <command>sendmail</command> command.</para></sect3>

<sect3><title>sendmail</title>
<para><command>sendmail</command> implements the
<application>Postfix</application> to
<application>Sendmail</application> compatibility interface.  
<filename class="symlink">mailq</filename> and <filename
class="symlink">newaliases</filename> are symlinks to 
<command>sendmail</command>.</para></sect3>

<sect3><title>showq</title>
<para><command>showq</command> will emulate the <filename
class="symlink">mailq</filename> command when the
<application>Postfix</application> mail system is 
not running.</para></sect3>

<sect3><title>postsuper</title>
<para><command>postsuper</command> does maintenance jobs on the
<application>Postfix</application> queue.</para></sect3>

<sect3><title>postalias</title>
<para><command>postalias</command> creates, queries or updates
<application>Postfix</application> alias 
databases.</para></sect3>

<sect3><title>postcat</title>
<para><command>postcat</command> prints the contents of a
<application>Postfix</application> queue file in human-readable 
form.</para></sect3>

<sect3><title>postconf</title>
<para><command>postconf</command> prints or changes the value of configuration 
parameters.</para></sect3>

<sect3><title>postdrop</title>
<para><command>postdrop</command> creates a file in the maildrop directory and 
copies its standard input to the file.</para></sect3>

<sect3><title>postkick</title>
<para><command>postkick</command> makes the mail system private
<acronym>IPC</acronym> accessible for use in shell 
scripts.</para></sect3>

<sect3><title>postlock</title>
<para><command>postlock</command> locks a file for exclusive access and 
executes a command on that file.</para></sect3>

<sect3><title>postlog</title>
<para><command>postlog</command> implements a logging interface for use in 
shell scripts.</para></sect3>

<sect3><title>postmap</title>
<para><command>postmap</command> creates, queries or updates
<application>Postfix</application> lookup tables.</para></sect3>

</sect2>

</sect1>