source: server/mail/postfix.xml@ c27a15a4

<?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>
<indexterm zone="postfix">
<primary sortas="a-Postfix">Postfix</primary></indexterm>

<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 id="postfix-config"><title>Configuration Information</title>
<indexterm zone="postfix postfix-config">
<primary sortas="e-etc-aliases">/etc/aliases</primary></indexterm>
<indexterm zone="postfix postfix-config">
<primary sortas="e-etc-postfix-star">/etc/postfix/*</primary></indexterm>

<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 id="postfix-init"><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>
<indexterm zone="postfix postfix-init"> <primary
sortas="f-postfix">postfix</primary></indexterm>

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

</sect3>

</sect2>

<sect2>
<title>Contents</title>

<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Directories</segtitle>

<seglistitem>
<seg>bounce, cleanup, error, flush, lmtp, local, mailq, master,
newaliases, nqmgr, oqmgr, pickup, pipe, postalias, postcat, postconf,
postdrop, postfix, postkick, postlock, postlog, postmap, postqueue,
postsuper, proxymap, qmgr, qmqpd, sendmail, showq, smtp, smtpd, spawn,
trivial-rewrite, verify, and virtual</seg>
<seg>/etc/postfix and /usr/share/doc/postfix</seg>
</seglistitem>
</segmentedlist>

<!--
</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>
-->

<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>

<varlistentry id="bounce">
<term><command>bounce</command></term>
<listitem><para>A daemon that maintains per-message log files with 
non-delivery status information.</para>
<indexterm zone="postfix bounce">
<primary sortas="b-bounce">bounce</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="cleanup">
<term><command>cleanup</command></term>
<listitem><para>A daemon that processes inbound mail, inserts it into the 
incoming mail queue, and informs the queue manager of its arrival.</para>
<indexterm zone="postfix cleanup">
<primary sortas="b-cleanup">cleanup</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="error">
<term><command>error</command></term>
<listitem><para>A deamon that processes non-delivery requests from the
queue manager.</para>
<indexterm zone="postfix error">
<primary sortas="b-error">error</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="flush">
<term><command>flush</command></term>
<listitem><para>A daemon that maintains a record of deferred mail by 
destination.</para>
<indexterm zone="postfix flush">
<primary sortas="b-flush">flush</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="lmtp">
<term><command>lmtp</command></term>
<listitem><para>A daemon that processes message delivery requests from the 
queue manager.</para>
<indexterm zone="postfix lmtp">
<primary sortas="b-lmtp">lmtp</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="local">
<term><command>local</command></term>
<listitem><para>A daemon that processes delivery requests from the queue 
manager to deliver mail to local recipients.</para>
<indexterm zone="postfix local">
<primary sortas="b-local">local</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="mailq">
<term><command>mailq</command></term>
<listitem><para>A symlink to <filename>sendmail</filename>.</para>
<indexterm zone="postfix mailq">
<primary sortas="b-mailq">mailq</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="master">
<term><command>master</command></term>
<listitem><para>The resident process that runs 
<application>Postfix</application> daemons on demand.</para>
<indexterm zone="postfix master">
<primary sortas="b-master">master</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="newaliases">
<term><command>newaliases</command></term>
<listitem><para>A symlink to <filename>sendmail</filename>.</para>
<indexterm zone="postfix newaliases">
<primary sortas="b-newaliases">newaliases</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="nqmgr">
<term><command>nqmgr</command></term>
<listitem><para>A daemon that awaits the arrival of incoming mail and 
arranges for its delivery.</para>
<indexterm zone="postfix nqmgr">
<primary sortas="b-nqmgr">nqmgr</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="oqmgr">
<term><command>oqmgr</command></term>
<listitem><para>The old style queue manager.  This will be removed 
soon.</para>
<indexterm zone="postfix oqmgr">
<primary sortas="b-oqmgr">oqmgr</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="pickup">
<term><command>pickup</command></term>
<listitem><para>A daemon that waits for hints that new mail has been 
dropped into the maildrop directory, and feeds it into the 
<application>cleanup</application> daemon.</para>
<indexterm zone="postfix pickup">
<primary sortas="b-pickup">pickup</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="pipe">
<term><command>pipe</command></term>
<listitem><para>A daemon that processes requests from the queue
manager to deliver messages to external commands.</para>
<indexterm zone="postfix pipe">
<primary sortas="b-pipe">pipe</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postalias">
<term><command>postalias</command></term>
<listitem><para>Creates or queries one or more
<application>Postfix</application> alias databases, or updates an 
existing one.</para>
<indexterm zone="postfix postalias">
<primary sortas="b-postalias">postalias</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postcat">
<term><command>postcat</command></term>
<listitem><para>Prints the contents of the
<application>named</application> files in human readable format.</para>
<indexterm zone="postfix postcat">
<primary sortas="b-postcat">postcat</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postconf">
<term><command>postconf</command></term>
<listitem><para>Displays or changes the value of
<application>Postfix</application> configuration parameters.</para>
<indexterm zone="postfix postconf">
<primary sortas="b-postconf">postconf</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postdrop">
<term><command>postdrop</command></term>
<listitem><para>Creates a file in the maildrop directory and copies 
it's standard input to the file.</para>
<indexterm zone="postfix postdrop">
<primary sortas="b-postdrop">postdrop</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postfix-bin">
<term><command>postfix</command></term>
<listitem><para>Controls the operation of the
<application>Postfix</application> mail system.</para>
<indexterm zone="postfix postfix-bin">
<primary sortas="b-postfix">postfix</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postkick">
<term><command>postkick</command></term>
<listitem><para>Sends requests to the specified service over a
local transport channel.</para>
<indexterm zone="postfix postkick">
<primary sortas="b-postkick">postkick</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postlock">
<term><command>postlock</command></term>
<listitem><para>Locks a mail folder for exclusive use, and executes 
commands passed to it.</para>
<indexterm zone="postfix postlock">
<primary sortas="b-postlock">postlock</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postlog">
<term><command>postlog</command></term>
<listitem><para>A <application>Postfix</application>-compatible logging 
interface for use in, for example, shell scripts.</para>
<indexterm zone="postfix postlog">
<primary sortas="b-postlog">postlog</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postmap">
<term><command>postmap</command></term>
<listitem><para>Creates or queries one or more Postfix lookup
tables, or updates an existing one.</para>
<indexterm zone="postfix postmap">
<primary sortas="b-postmap">postmap</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postqueue">
<term><command>postqueue</command></term>
<listitem><para>The <application>Postfix</application> user interface for 
queue management.</para>
<indexterm zone="postfix postqueue">
<primary sortas="b-postqueue">postqueue</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="postsuper">
<term><command>postsuper</command></term>
<listitem><para>The <application>Postfix</application> user interface for
superuser queue management.</para>
<indexterm zone="postfix postsuper">
<primary sortas="b-postsuper">postsuper</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="proxymap">
<term><command>proxymap</command></term>
<listitem><para>Provides read-only table lookup services to other
<application>Postfix</application> processes.</para>
<indexterm zone="postfix proxymap">
<primary sortas="b-proxymap">proxymap</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="qmgr">
<term><command>qmgr</command></term>
<listitem><para>A daemon that awaits the arrival of incoming mail and
arranges for its delivery.</para>
<indexterm zone="postfix qmgr">
<primary sortas="b-qmgr">qmgr</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="qmqpd">
<term><command>qmqpd</command></term>
<listitem><para>A daemon that receives one message per connection, and
pipes it through the <application>cleanup</application> daemon, and
places it into the incoming queue.</para>
<indexterm zone="postfix qmqpd">
<primary sortas="b-qmqpd">qmqpd</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="sendmail-postfix">
<term><command>sendmail</command></term>
<listitem><para>The <application>Postfix</application> to
<application>Sendmail</application> compatibility interface.</para>
<indexterm zone="postfix sendmail-postfix">
<primary sortas="b-sendmail">sendmail</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="showq">
<term><command>showq</command></term>
<listitem><para>A daemon that reports the Postfix mail queue status.</para>
<indexterm zone="postfix showq">
<primary sortas="b-showq">showq</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="smtp">
<term><command>smtp</command></term>
<listitem><para>Looks up a list of mail exchanger addresses for the
destination host, sorts the list by preference, and connects to
each listed address until it finds a server that responds.</para>
<indexterm zone="postfix smtp">
<primary sortas="b-smtp">smtp</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="smtpd">
<term><command>smtpd</command></term>
<listitem><para>Accepts network connection requests and performs zero
or more SMTP transactions per connection.</para>
<indexterm zone="postfix smtpd">
<primary sortas="b-smtpd">smtpd</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="spawn">
<term><command>spawn</command></term>
<listitem><para>Listens on a port as specified in the
<application>Postfix</application> <filename>master.cf</filename> file 
and spawns an external  command whenever a connection is established.</para>
<indexterm zone="postfix spawn">
<primary sortas="b-spawn">spawn</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="trivial-rewrite">
<term><command>trivial-rewrite</command></term>
<listitem><para>A daemon that rewrites addresses to standard form.</para>
<indexterm zone="postfix trivial-rewrite">
<primary sortas="b-trivial-rewrite">trivial-rewrite</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="verify">
<term><command>verify</command></term>
<listitem><para>Maintains a record of what recipient addresses are known 
to be deliverable or undeliverable.</para>
<indexterm zone="postfix verify">
<primary sortas="b-verify">verify</primary></indexterm>
</listitem>
</varlistentry>

<varlistentry id="virtual">
<term><command>virtual</command></term>
<listitem><para>Delivers mail to virtual users' mail directories.</para>
<indexterm zone="postfix virtual">
<primary sortas="b-virtual">virtual</primary></indexterm>
</listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>