source: server/mail/postfix.xml@ be98f1e0

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

  <!ENTITY postfix-download-http " ">
  <!ENTITY postfix-download-ftp  "ftp://ftp.porcupine.org/mirrors/postfix-release/official/postfix-&postfix-version;.tar.gz">
  <!ENTITY postfix-md5sum        "85d1c2b06a469ba6cc61946c7042e40e">
  <!ENTITY postfix-size          "4.5 MB">
  <!ENTITY postfix-buildsize     "203 MB">
  <!ENTITY postfix-time          "0.2 SBU (Using parallelism=4)">
]>

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

  <sect1info>
    <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.
    </para>

    &lfs101_checked;

    <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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/postfix-&postfix-version;-glibc230_fix-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">Postfix Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="db"/>,
      <xref linkend="cyrus-sasl"/>, and
      <xref linkend="libnsl"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="icu"/> for Email Address Internationalization (SMTPUTF8) support,
      <xref linkend="mariadb"/> or <ulink url="http://www.mysql.com/">MySQL</ulink>,
      <xref linkend="openldap"/>,
      <xref linkend="pcre"/>,
      <xref linkend="postgresql"/>,
      <xref linkend="sqlite"/>, and
      <ulink url="http://cr.yp.to/cdb.html">CDB</ulink> or
      <ulink url="http://www.corpit.ru/mjt/tinycdb.html">TinyCDB</ulink>
    </para>

    <para>
      Note that <application>SQLite</application>,
      <application>MySQL</application>, <application>PostgreSQL</application>
      and <application>CDB</application> are only useful if there is a known
      need for them.
    </para>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/postfix"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Postfix</title>

    <sect3>
      <title>Adding Users and Groups</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;
useradd -c "Postfix Daemon User" -d /var/spool/postfix -g postfix \
        -s /bin/false -u 32 postfix &amp;&amp;
chown -v postfix:postfix /var/mail</userinput></screen>
    </sect3>

    <sect3>
      <title>Configuring the Build</title>

      <para>
        The README files are formatted to be read with a pager like
        <application>Less</application> or <application>More</application>.
        If you want to use a text editor, make them legible with the
        following sed:
      </para>

<screen><userinput>sed -i 's/.\x08//g' README_FILES/*</userinput></screen>
<!--
      <para>
        Apply a patch to allow <application>Postfix</application> to compile
        on <application>Glibc-2.30</application> where some macros were
        dropped:
      </para>

<screen><userinput>patch -Np1 -i ../postfix-&postfix-version;-glibc230_fix-1.patch</userinput></screen>
-->
      <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>
        For more details read the readme files.
      </para>
<!-- We reverted to Berkeley DB-5.3.28 and that is handled
       <para>
         The current version of <xref linkend="db"/> is not recognised by a
         hard-coded test for known versions. To build with this version use the
         following sed:
      </para>

<screen><userinput>sed -i 's/DB_VERSION_MAJOR == 6 .*||/DB_VERSION_MAJOR &gt; 4 ||/' \
  src/util/dict_db.c</userinput></screen>
-->
      <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 -DUSE_CYRUS_SASL -I/usr/include/sasl'
AUXLIBS='-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='-DHAS_LDAP'
AUXLIBS='-lldap -llber'</literal></screen>

      </sect4>

      <sect4>
        <title>Sqlite</title>

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

<screen><literal>CCARGS='-DHAS_SQLITE'
AUXLIBS='-lsqlite3 -lpthread'</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='-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='-lpq -lz -lm'</literal></screen>

      </sect4>

      <sect4>
        <title>CDB/TinyCDB</title>

        <para>
          To use <application>CDB</application> or
          <application>TinyCDB</application> with
          <application>Postfix</application>, use the following arguments:
        </para>

<screen><literal>CCARGS='-DHAS_CDB'
AUXLIBS='<replaceable>&lt;/path/to/CDB&gt;</replaceable>/libcdb.a'</literal></screen>

      </sect4>

      <sect4>
        <title>StartTLS Authentication</title>

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

<screen><literal>CCARGS='-DUSE_TLS -I/usr/include/openssl/'
AUXLIBS='-lssl -lcrypto'</literal></screen>
      </sect4>

    </sect3>

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

      <para>
        If you have <application>Cyrus SASL</application> and
        <application>OpenSSL</application> installed, install
        <application>Postfix</application> by running the following commands:
      </para>

<screen><userinput>make CCARGS="-DUSE_TLS -I/usr/include/openssl/                     \
             -DUSE_SASL_AUTH -DUSE_CYRUS_SASL -I/usr/include/sasl" \
     AUXLIBS="-lssl -lcrypto -lsasl2"                              \
     makefiles &amp;&amp;
make</userinput></screen>

    <!-- There is a testsuite, but it fails a lot. It seems to need
         the host to be specifically setup for the tests.
         Run with `make tests' and `make root_tests' -->
    <para>
      This package does not come with a useful test suite.
    </para>

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

<!-- dev note: sh postfix-install -non-interactive install_root=<DESTDIR> ... -->

<screen role="root"><userinput>sh postfix-install -non-interactive \
   daemon_directory=/usr/lib/postfix \
   manpage_directory=/usr/share/man \
   html_directory=/usr/share/doc/postfix-&postfix-version;/html \
   readme_directory=/usr/share/doc/postfix-&postfix-version;/readme</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

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

    <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 few cases. If the
      <option>html_directory</option> and <option>readme_directory</option>
      options are not set then the documentation will not be installed.
    </para>

    <para>
      <option>CCARGS="-DNO_EAI ..."</option>: this will turn off SMTPUTF8
      support, for example  if the rest of your email address infrastructure
      cannot handle UTF-8 email addresses and message header values.
    </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>

      <para>
        Create (or append to an existing) <filename>/etc/aliases</filename>
        with the following command. Change
        <replaceable>&lt;LOGIN&gt;</replaceable> to your non-root login
        identity so mail addressed to
        <systemitem class="username">root</systemitem> can be forwarded to you.
        As the <systemitem class="username">root</systemitem> user:
      </para>

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

MAILER-DAEMON:    postmaster
postmaster:       root

root:             <replaceable>&lt;LOGIN&gt;</replaceable>
# End /etc/aliases</literal>
EOF</userinput></screen>

      <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/postfix/main.cf</filename> and
          <filename>/etc/postfix/master.cf</filename> files must be personalized
          for your system. The <filename>main.cf</filename> file needs your
          fully qualified hostname. You will find that
          <filename>main.cf</filename> is self documenting, so load it into your
          editor to make the changes you need for your situation.
        </para>
      </note>

      <note>
        <para>
          <application>Postfix</application> can also be set up to
          run in a chroot jail. See the file in the source
          <filename>examples/chroot-setup/LINUX2</filename> for details.
        </para>
      </note>

      <para>
        If you have an existing configuration, you can run the
        <command>postfix</command> utility to add any necessary definitions to
        your existing files. As the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>/usr/sbin/postfix upgrade-configuration</userinput></screen>

      <para>
        Before starting <application>Postfix</application>, you should check
        that your configuration and file permissions will work properly. Run the
        following commands as the <systemitem class="username">root</systemitem>
        user to check and start your <application>Postfix</application> server:
      </para>

<screen role="root"><userinput>/usr/sbin/postfix check &amp;&amp;
/usr/sbin/postfix start</userinput></screen>

    </sect3>

    <sect3 id="postfix-init">
      <title><phrase revision="sysv">Boot Script</phrase>
             <phrase revision="systemd">Systemd Unit</phrase></title>

      <para>
        To automate the running of Postfix at startup, install the
        <phrase revision="sysv"><filename>/etc/rc.d/init.d/postfix</filename>
        init script</phrase>
        <phrase revision="systemd"><filename>postfix.service</filename>
        unit</phrase> included in the
        <xref linkend="bootscripts" revision="sysv"/>
        <xref linkend="systemd-units" revision="systemd"/> 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>
          mailq (symlink), newaliases (symlink), postalias, postcat, postconf,
          postdrop, postfix, postkick, postlock, postlog, postmap, postmulti,
          postqueue, postsuper, and sendmail
        </seg>
        <seg>
          None
        </seg>
        <seg>
          /{etc,usr/lib}/postfix,
          /usr/share/doc/postfix-&postfix-version; and
          /var/{lib,spool}/postfix
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <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="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="postalias">
        <term><command>postalias</command></term>
        <listitem>
          <para>
            is a utility for <application>Postfix</application> alias database
            maintenance
          </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 files from the
            <application>Postfix</application> queue 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 its 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>
            is the <application>Postfix</application> control program
          </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="postmulti">
        <term><command>postmulti</command></term>
        <listitem>
          <para>
            is the <application>Postfix</application> multi-instance manager.
            It allows a system administrator to manage multiple
            <application>Postfix</application> instances on a single host
          </para>
          <indexterm zone="postfix postmulti">
            <primary sortas="b-postmulti">postmulti</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="sendmail-postfix">
        <term><command>sendmail</command></term>
        <listitem>
          <para>
            is 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>

    </variablelist>

  </sect2>

</sect1>