source: server/mail/postfix.xml@ f00d92ee

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/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-md5sum "bcaa4aac80595d04c60c72844203a04d">
  <!ENTITY postfix-size "1.9 MB">
  <!ENTITY postfix-buildsize "81 MB">
  <!ENTITY postfix-time "0.29 SBU">
]>

<sect1 id="postfix" xreflabel="Postfix-&postfix-version;">
  <?dbhtml filename="postfix.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Postfix-&postfix-version;</title>

  <indexterm zone="postfix">
    <primary sortas="a-Postfix">Postfix</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Postfix</title>

    <para>The <application>Postfix</application> package contains a Mail
    Transport Agent (MTA). 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 (ISP).</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <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 MD5 sum: &postfix-md5sum;</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>

    <bridgehead renderas="sect3">Postfix Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para><xref linkend="db"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para><xref linkend="pcre"/>,
    <xref linkend="mysql"/>,
    <xref linkend="postgresql"/>,
    <xref linkend="openldap"/>,
    <xref linkend="openssl"/> and
    <xref linkend="cyrus-sasl"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Postfix</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 <option>makefiles</option> 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
      TLS/SSL authentication, you will 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 TLS/SSL and
      <application>Cyrus-SASL</application> arguments:</para>

<screen><userinput>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"</userinput></screen>

      <sect4>
        <title>SSL/TLS Authentication</title>

        <para>To use SSL/TLS authentication with
        <application>Postfix</application>, you will 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 it with the following commands:</para>

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

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

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

        <para>To use SSL or TLS 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><literal>CCARGS="-DUSE_SASL_AUTH -I/usr/include/sasl" \
AUXLIBS="-L/usr/lib -R/usr/lib -lsasl2"</literal></screen>

      </sect4>

      <sect4>
        <title>OpenLDAP</title>

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

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

      </sect4>

      <sect4>
        <title>MySQL</title>

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

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

      </sect4>

      <sect4>
        <title>PostgreSQL</title>

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

<screen><literal>CCARGS="-DHAS_PGSQL -I/usr/include/postgresql" \
AUXLIBS="-L/usr/lib -lpq -lz -lm"</literal></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 during the installation.
      Add the users and groups with the following commands issued by the
      <systemitem class='username'>root</systemitem> user:</para>

<screen role="root"><userinput>groupadd -g 32 postfix &amp;&amp;
groupadd -g 33 postdrop &amp;&amp;
groupadd -g 99 nogroup &amp;&amp;
useradd -c "Postfix Daemon User" -d /dev/null -g postfix \
    -s /bin/false -u 32 postfix &amp;&amp;
useradd -c "Unprivileged Nobody" -d /dev/null -g nogroup \
    -s /bin/false -u 99 nobody &amp;&amp;
chown -v postfix:postfix /var/mail</userinput></screen>

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

<screen role="root"><userinput>make</userinput></screen>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role='root'><userinput>sh postfix-install daemon_directory=/usr/sbin \
                   manpage_directory=/usr/share/man \
                   sample_directory=/usr/share/doc/postfix \
                   -non-interactive</userinput></screen>

      <para>The final installation step is to install the program's documentation
      with the following commands (again, as the 
      <systemitem class="username">root</systemitem> user):</para>

<screen role="root"><userinput>install -v -d /usr/share/doc/postfix &amp;&amp;
cp -v -rf html/* /usr/share/doc/postfix</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="commands">
    <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 role="configuration">
    <title>Configuring Postfix</title>

    <sect3 id="postfix-config">
      <title>Config Files</title>

      <para><filename>/etc/aliases</filename>,
      <filename>/etc/postfix/main.cf</filename>, and
      <filename>/etc/postfix/master.cf</filename></para>

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

    </sect3>

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

<screen role="root"><userinput>cat &gt;&gt; /etc/aliases &lt;&lt; "EOF"
<literal># Begin /etc/aliases

MAILER-DAEMON:    postmaster
postmaster:       root

root:             LOGIN
# End /etc/aliases</literal>
EOF</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 <systemitem class="username">root</systemitem> 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 <command>sed</command> 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 role="root"><userinput>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</userinput></screen>

    </sect3>

    <sect3 id="postfix-init">
      <title>Boot 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 role="root"><userinput>make install-postfix</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</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>None</seg>
        <seg>/etc/postfix and /usr/share/doc/postfix</seg>
      </seglistitem>
    </segmentedlist>

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

      <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 user's mail directories.</para>
          <indexterm zone="postfix virtual">
            <primary sortas="b-virtual">virtual</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>