source: server/mail/postfix.xml@ 1f81eac

<?xml version="1.0" encoding="UTF-8"?>
<!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;

  <!-- editors: upstream postfix is ftp only, some of the mirrors offer
  https - http://www.porcupine.org/mirmon/postfix-source.html lists the
  mirror status, some of the mirrors shown as http are actually https -->
  <!ENTITY postfix-download-http "https://ghostarchive.org/postfix/postfix-release/official/postfix-&postfix-version;.tar.gz">
  <!ENTITY postfix-download-ftp  " ">
  <!ENTITY postfix-md5sum        "3eda9b945ed6cdf11ef58a731c574a04">
  <!ENTITY postfix-size          "4.7 MB">
  <!ENTITY postfix-buildsize     "208 MB">
  <!ENTITY postfix-time          "0.1 SBU (Using parallelism=4)">
]>

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


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

    &lfs122_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="cyrus-sasl"/>,
      <xref linkend="libnsl"/>, and
      <xref linkend="lmdb"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="icu"/> for Email Address Internationalization (SMTPUTF8) support,
      <xref linkend="mariadb"/> or <ulink url="https://www.mysql.com/">MySQL</ulink>,
      <xref linkend="openldap"/>,
      <xref linkend="pcre2"/>,
      <xref linkend="postgresql"/>,
      <xref linkend="sqlite"/>,
      &berkeley-db;, and
      <ulink url="https://cr.yp.to/cdb.html">CDB</ulink> or
      <ulink url="https://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">
      Editor 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>
        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>

      <note>
        <para>
          For all variants of the CCARGS you should ensure that '-DNO_NIS' is
          specified so that the build does not attempt to access an rpcsvc
          header which do not exist in BLFS.  If &berkeley-db; is
          not installed, '-DNO_DB' needs to be specified as well.
        </para>
      </note>

      <para>
        For more details read the readme files.
      </para>

      <para>
        Initialize the <envar>CCARGS</envar> and <envar>AUXLIBS</envar>
        according to the note above:
      </para>

<!-- This package does not accept a space between -D and the argument. -->

<screen><userinput>CCARGS="-DNO_NIS -DNO_DB"
AUXLIBS=""</userinput></screen>

      <para>
        Next, the <envar>CCARGS</envar> and the <envar>AUXLIBS</envar>
        variables are filled with settings depending on the actual
        system configuration. If an optional package is installed but
        should <emphasis>not</emphasis> be included in the
        <application>Postfix</application> build, simply skip the
        corresponding <code>if [ ... ]; then</code> scriptlets.
      </para>

      <sect4>
        <title>Cyrus-SASL</title>

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

<screen><userinput>if [ -r /usr/lib/libsasl2.so ]; then
  CCARGS="$CCARGS -DUSE_SASL_AUTH -DUSE_CYRUS_SASL -I/usr/include/sasl"
  AUXLIBS="$AUXLIBS -lsasl2"
fi</userinput></screen>
      </sect4>

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

<screen><userinput>if [ -r /usr/lib/liblmdb.so ]; then
  CCARGS="$CCARGS -DHAS_LMDB"
  AUXLIBS="$AUXLIBS -llmdb"
fi</userinput></screen>
      </sect4>

      <sect4>
        <title>OpenLDAP</title>

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

<screen><userinput>if [ -r /usr/lib/libldap.so -a -r /usr/lib/liblber.so ]; then
  CCARGS="$CCARGS -DHAS_LDAP"
  AUXLIBS="$AUXLIBS -lldap -llber"
fi</userinput></screen>

      </sect4>

      <sect4>
        <title>Sqlite</title>

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

<screen><userinput>if [ -r /usr/lib/libsqlite3.so ]; then
  CCARGS="$CCARGS -DHAS_SQLITE"
  AUXLIBS="$AUXLIBS -lsqlite3 -lpthread"
fi</userinput></screen>

      </sect4>

      <sect4>
        <title>MySQL</title>

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

<screen><userinput>if [ -r /usr/lib/libmysqlclient.so ]; then
  CCARGS="$CCARGS -DHAS_MYSQL -I/usr/include/mysql"
  AUXLIBS="$AUXLIBS -lmysqlclient -lz -lm"
fi</userinput></screen>

      </sect4>

      <sect4>
        <title>PostgreSQL</title>

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

<screen><userinput>if [ -r /usr/lib/libpq.so ]; then
  CCARGS="$CCARGS -DHAS_PGSQL -I/usr/include/postgresql"
  AUXLIBS="$AUXLIBS -lpq -lz -lm"
fi</userinput></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>if [ -r <replaceable>&lt;/path/to/CDB&gt;</replaceable>/libcdb.a ]; then
  CCARGS="$CCARGS -DHAS_CDB"
  AUXLIBS="$AUXLIBS <replaceable>&lt;/path/to/CDB&gt;</replaceable>/libcdb.a"
fi</literal></screen>

      </sect4>

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

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

<screen><userinput>if [ -r /usr/lib/libssl.so -a -r /usr/lib/libcrypto.so ]; then
  CCARGS="$CCARGS -DUSE_TLS -I/usr/include/openssl/"
  AUXLIBS="$AUXLIBS -lssl -lcrypto"
fi</userinput></screen>
        <para>
          <application>OpenSSL</application> is installed by LFS so it
          should be always there. The <code>if ... then</code> is here
          just for consistency.
        </para>
      </sect4>

    </sect3>

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

      <para>
        There might be duplicate settings in <envar>AUXLIBS</envar>
        like <code>-lm</code> when both, <application>MariaDB</application>
        and <application>PostgreSQL</application> are used. They do
        not harm. Install <application>Postfix</application> by
        running the following commands:
      </para>

<screen><userinput>make CCARGS="$CCARGS" AUXLIBS="$AUXLIBS" makefiles &amp;&amp;
make</userinput></screen>

    <!-- There is a test suite, 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>

      <para>
        The BLFS editors recommend to use LMDB instead of Berkeley DB for
        Postfix tables.  Add three lines into
        <filename>/etc/postfix/main.cf</filename> to make
        <command>postmap</command> encode the lookup tables in the LMDB
        format by default and to change the default hash setting of the
        alias tables:
      </para>

<screen role="root"><userinput>echo 'default_database_type = lmdb'       &gt;&gt; /etc/postfix/main.cf &amp;&amp;
echo 'alias_database = lmdb:/etc/aliases' &gt;&gt; /etc/postfix/main.cf &amp;&amp;
echo 'alias_maps = lmdb:/etc/aliases'     &gt;&gt; /etc/postfix/main.cf</userinput></screen>

      <para>
        To protect your server against the recent SMTP smuggling attacks,
        additional steps are required. Add two lines into
        <filename>/etc/postfix/main.cf</filename> to disconnect remote SMTP
        clients that send bare newlines in the DATA section, while also
        allowing clients on your network with non-standard SMTP implementations
        to still send mail:
      </para>

<screen role="root"><userinput>echo 'smtpd_forbid_bare_newline = normalize' &gt;&gt; /etc/postfix/main.cf &amp;&amp;
echo 'smtpd_forbid_bare_newline_exclusions = $mynetworks' &gt;&gt; /etc/postfix/main.cf</userinput></screen>

      <para>
        Note that if you are following an online tutorial to configure
        Postfix, the tutorial may refer to a lookup table with
        <literal>hash:/path/to/lookup_table</literal>.  You should replace
        <literal>hash</literal> with <literal>lmdb</literal> in order to use
        a lookup table encoded in the LMDB format.
      </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>
        To ensure that all permissions are set properly, <application>postfix</application>
        provides a tool which is to be run as the
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="nodump"><userinput>/usr/sbin/postfix -c /etc/postfix set-permissions</userinput></screen>

      <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="nodump"><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="nodump"><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>