source: server/mail/exim.xml@ 9164647

<?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 exim-download-http   "https://ftp.exim.org/pub/exim/exim4/exim-&exim-version;.tar.xz">

  <!ENTITY exim-download-ftp    "ftp://ftp.exim.org/pub/exim/exim4/exim-&exim-version;.tar.xz">
  <!-- if above don't work, please use one of the official mirrors at
       http://www.exim.org/mirmon/ftp_mirrors.html -->
  <!ENTITY exim-md5sum          "0d10d5b10f2af77ec8c2c2fe5be6c1ad">
  <!ENTITY exim-size            "1.8 MB">
  <!ENTITY exim-buildsize       "20 MB">
  <!ENTITY exim-time            "0.3 SBU">

  <!ENTITY exim-daemon-version  "&exim-version;-2">
]>

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


  <title>Exim-&exim-version;</title>

  <indexterm zone="exim">
    <primary sortas="a-Exim">Exim</primary>
  </indexterm>

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

    <para>
      The <application>Exim</application> package contains a Mail
      Transport Agent written by the University of Cambridge, released
      under the GNU Public License.
    </para>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&exim-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&exim-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &exim-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &exim-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &exim-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &exim-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Additional formats of the documentation (text-based docs are
          shipped with the sources) can be downloaded by following the links
          shown at <ulink url="https://exim.org/docs.html"/>.
        </para>
      </listitem>
<!-- Applied in 4.96
      <listitem>
        <para>
          Required patch when building with <application>PAM</application> support:
          <ulink url="&patch-root;/exim-&exim-version;-call_pam-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Required patch to build with openssl-3:
          <ulink url="&patch-root;/exim-&exim-version;-openssl3_fix-1.patch"/>
        </para>
      </listitem>
-->
    </itemizedlist>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libnsl"/> and
      <xref linkend="pcre2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <ulink url="https://sourceforge.net/projects/tdb">TDB</ulink>
      (alternative to GDBM, built in LFS),
      <xref linkend="cyrus-sasl"/>,
      <xref linkend="libidn"/>,
      <xref linkend="linux-pam"/>,
      <xref linkend="mariadb"/> or
      <ulink url="https://www.mysql.com/">MySQL</ulink>,
      <xref linkend="openldap"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="postgresql"/>,
      <xref linkend="sqlite"/>,
      <xref linkend="x-window-system"/>,
      <ulink url="https://github.com/heimdal/heimdal">Heimdal GSSAPI</ulink>, and
      <ulink url="http://www.trusteddomain.org/opendmarc/">OpenDMARC</ulink>
    </para>

  </sect2>

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

    <para>
      Before building <application>Exim</application>, as the
      <systemitem class="username">root</systemitem> user you should create
      the group and user <systemitem class="username">exim</systemitem> which
      will run the <command>exim</command> daemon:
    </para>

<screen role="root"><userinput>groupadd -g 31 exim &amp;&amp;
useradd -d /dev/null -c "Exim Daemon" -g exim -s /bin/false -u 31 exim</userinput></screen>

<!-- Applied in 4.96
    <para>
      If you want to build with <application>PAM</application> support, apply the following patch:
    </para>

<screen><userinput>patch -Np2 -i ../exim-&exim-version;-call_pam-1.patch</userinput></screen>

    <para>
      Apply a patch required for building against openssl version 3:
    </para>

<screen><userinput>patch -Np2 -i ../exim-&exim-version;-openssl3_fix-1.patch</userinput></screen>
-->

    <para>
      Configure <application>Exim</application> with the following commands:
    </para>

<screen><userinput>sed -e 's,^BIN_DIR.*$,BIN_DIRECTORY=/usr/sbin,'    \
    -e 's,^CONF.*$,CONFIGURE_FILE=/etc/exim.conf,' \
    -e 's,^EXIM_USER.*$,EXIM_USER=exim,'           \
    -e '/# SUPPORT_TLS=yes/s,^#,,'                   \
    -e '/# USE_OPENSSL/s,^#,,'                       \
    -e 's,^EXIM_MONITOR,#EXIM_MONITOR,' src/EDITME > Local/Makefile &amp;&amp;

printf "USE_GDBM = yes\nDBMLIB = -lgdbm\n" >> Local/Makefile
</userinput></screen>

    <para>
      If you want to add <application>Linux PAM</application> support, also run the following commands:
    </para>

<screen role="nodump"><userinput>sed -i '/# SUPPORT_PAM=yes/s,^#,,' Local/Makefile
echo "EXTRALIBS=-lpam" >> Local/Makefile
</userinput></screen>

    <para>
      Build <application>Exim</application> with the following command:
    </para>

<screen><userinput>make</userinput></screen>


    <para>
      This package does not come with a test suite.
    </para>

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

<!-- dev note: make INSTALL_ARG=-no_chown DESTDIR=<DESTDIR> install -->

<screen role="root"><userinput>make install                                    &amp;&amp;
install -v -m644 doc/exim.8 /usr/share/man/man8 &amp;&amp;

install -v -d -m755    /usr/share/doc/exim-&exim-version; &amp;&amp;
install -v -m644 doc/* /usr/share/doc/exim-&exim-version; &amp;&amp;

ln -sfv exim /usr/sbin/sendmail                 &amp;&amp;
install -v -d -m750 -o exim -g exim /var/spool/exim</userinput></screen>

  </sect2>

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

    <para>
      <command>sed -e ... > Local/Makefile</command>: Most of
      <application>Exim</application>'s configuration options are defined
      in <filename>Local/Makefile</filename>, which is created from
      the <filename>src/EDITME</filename> file. This command specifies the
      minimum set of options. Descriptions for the options are listed below.
    </para>

    <para>
      <command>printf ... > Local/Makefile</command>: Setting those
      variables allows to use GDBM instead of the default Berkeley DB. Remove
      this command if you have installed <xref linkend="db"/>.
    </para>

    <para>
      <parameter>BIN_DIRECTORY=/usr/sbin</parameter>: This installs all of
      <application>Exim</application>'s binaries and scripts in
      <filename class='directory'>/usr/sbin</filename>.
    </para>

    <para>
      <parameter>CONFIGURE_FILE=/etc/exim.conf</parameter>: This installs
      <application>Exim</application>'s main configuration file in
      <filename class='directory'>/etc</filename>.
    </para>

    <para>
      <parameter>EXIM_USER=exim</parameter>: This tells
      <application>Exim</application> that after the daemon no longer needs
      <systemitem class="username">root</systemitem> privileges, the process
      needs to hand off the daemon to the <systemitem
      class="username">exim</systemitem> user.
    </para>

    <para>
      <parameter>SUPPORT_TLS=yes</parameter>: This allows to support
      STARTTLS connections. If you use this option, you need to select
      whether <application>OpenSSL</application> or
      <application>GnuTLS</application> is used (see
      <filename>src/EDITME</filename>).
    </para>

    <para>
      <parameter>USE_OPENSSL_PC=openssl</parameter>: This tells the
      build system to use <application>OpenSSL</application>, and to
      find the needed libraries with <application>pkg-config</application>.
    </para>

    <para>
      <parameter>#EXIM_MONITOR</parameter>: This defers building the
      <application>Exim</application> monitor program, as it requires
      <application>X Window System</application> support, by commenting out the
      <parameter>EXIM_MONITOR</parameter> line in the
      <filename>Makefile</filename>. If you wish to build the monitor program,
      omit this <command>sed</command> command and issue the following command
      before building the package (modify
      <filename>Local/eximon.conf</filename>, if necessary):
      <command>cp exim_monitor/EDITME Local/eximon.conf</command>.
    </para>

    <para>
      <command>ln -sfv exim /usr/sbin/sendmail</command>: Creates a link to
      <command>sendmail</command> for applications which need it.
      <application>Exim</application> will accept most
      <application>Sendmail</application> command-line options.
    </para>

    <para>
      <command>install -v -m750 -o exim -g exim /var/spool/exim</command>:
      Since /var/spool is owned by root and this version of
      <command>exim</command> drops
      <systemitem class="username">root</systemitem> privileges early, to run
      as user <systemitem class="username">exim</systemitem>, it cannot create
      the <filename class="directory">/var/spool/exim</filename> directory. As
      a work around, it is created manually.
    </para>

  </sect2>

  <sect2 role="commands">
    <title>Adding Additional Functionality</title>

    <para>
      To utilize some or all of the dependency packages, you'll need to
      modify <filename>Local/Makefile</filename> to include the appropriate
      directives and parameters to link additional libraries before you build
      <application>Exim</application>. <filename>Local/Makefile</filename> is
      heavily commented with instructions on how to do this. Listed below is
      additional information to help you link these dependency packages or
      add additional functionality.
    </para>

    <para>
      If you wish to build and install the
      <filename class='extension'>.info</filename> documentation, refer to
      <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch04.html#SECTinsinfdoc"/>.
    </para>

    <para>
      If you wish to build in Exim's interfaces for calling virus and spam
      scanning software directly from access control lists, uncomment the
      <option>WITH_CONTENT_SCAN=yes</option> parameter and review the
      information found at <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch45.html"/>.
    </para>

    <para>
      To use a backend database other than <application>GDBM
      </application>, see the instructions at <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch04.html#SECTdb"/>.
    </para>

    <para>
      For SSL functionality, see the instructions at <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch04.html#SECTinctlsssl"/>
      and <ulink url="
      https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch42.html"/>.
    </para>

    <para>
      For <application>tcpwrappers</application> functionality, see the
      instructions at <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch04.html#SECID27"/>.
    </para>

    <para>
      For information about adding authentication mechanisms to the
      build, see chapters 33&mdash;41 of <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/index.html"/>.
    </para>

    <para>
      For information about linking <application>Linux-PAM</application>,
      refer to the instructions <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch11.html#SECTexpcond"/>.
    </para>

    <para>
      For information about linking database engine libraries used for
      <application>Exim</application> name lookups, see the instructions at
      <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch09.html"/>.
    </para>

    <para>
      If you wish to add <application>Readline</application> support to
      <application>Exim</application> when invoked in <quote>test
      expansion</quote> (<option>-be</option>) mode, see the information in
      the <option>-be</option> section of <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch05.html#id2525974"/>.
    </para>

    <para>
      You may wish to modify the default configuration and send log files to
      syslog instead of the default
      <filename class='directory'>/var/spool/exim/log</filename> directory. See
      the information at <ulink url=
      "https://exim.org/exim-html-&exim-version;/doc/html/spec_html/ch-log_files.html"/>.
    </para>

    <para>
      A wealth of information can be also found at the <ulink url=
      "https://github.com/Exim/exim/wiki">Exim Wiki</ulink>.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Exim</title>

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

      <para>
        <filename>/etc/exim.conf</filename> and
        <filename>/etc/aliases</filename>
      </para>

      <indexterm zone="exim exim-config">
        <primary sortas="e-etc-exim.conf">/etc/exim.conf</primary>
      </indexterm>

      <indexterm zone="exim exim-config">
        <primary sortas="e-etc-aliases">/etc/aliases</primary>
      </indexterm>

    </sect3>

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

      <para>
        Review the file <filename>/etc/exim.conf</filename>, and modify any
        settings to suit your needs. Note that the default configuration
        assumes that the <filename class="directory">/var/mail</filename>
        directory is world writable, but has the sticky bit set. If you want
        to use the default configuration, issue as the <systemitem
        class="username">root</systemitem> user:
     </para>

<screen role="root"><userinput>chmod -v a+wt /var/mail</userinput></screen>

      <para>
        A default (nothing but comments) <filename>/etc/aliases</filename>
        file is installed during the package installation if this file did not
        exist on your system. Create the necessary aliases and start the
        <application>Exim</application> daemon using the following commands:
      </para>

<screen role="root"><userinput>cat &gt;&gt; /etc/aliases &lt;&lt; "EOF"
<literal>postmaster: root
MAILER-DAEMON: root</literal>
EOF
/usr/sbin/exim -bd -q15m</userinput></screen>

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

      <para>
        The <command>/usr/sbin/exim -bd -q15m</command> command starts
        the <application>Exim</application> daemon with a 15 minute interval
        in processing the mail queue. Adjust this parameter to suit your
        desires.
      </para>
    </sect3>

    <sect3>
      <title>Linux PAM Configuration</title>

      <para>
        If you have built <application>Exim</application> with
        <application>Linux PAM</application> support, you need to create a
        <application>PAM</application> configuration file to get it working
        correctly with BLFS.
      </para>

      <para>
        Issue the following command as the <systemitem
        class="username">root</systemitem> user to create the configuration
        file for <application>Linux PAM</application>:
      </para>

<screen role="root"><userinput>cat &gt; /etc/pam.d/exim &lt;&lt; "EOF"
<literal># Begin /etc/pam.d/exim

auth    include system-auth
account include system-account
session include system-session

# End /etc/pam.d/exim</literal>
EOF</userinput></screen>

    </sect3>

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

      <para>
        To automatically start <command>exim</command> at boot, install the
        <phrase revision="sysv"><filename>/etc/rc.d/init.d/exim</filename>
        init script</phrase>
        <phrase revision="systemd"><filename>exim.service</filename>
        unit</phrase>
        included in the <xref linkend="bootscripts" revision="sysv"/>
        <xref linkend="systemd-units" revision="systemd"/> package:
      </para>

      <indexterm zone="exim exim-init">
        <primary sortas="f-exim">exim</primary>
      </indexterm>

<screen role="root"><userinput>make install-exim</userinput></screen>

      <para revision="sysv">
        The bootscript also starts the <application>Exim</application> daemon
        and dispatches a queue runner process every 15 minutes. Modify the
        <option>-q<replaceable>&lt;time interval&gt;</replaceable></option>
        parameter in <filename>/etc/rc.d/init.d/exim</filename>, if necessary
        for your installation.
      </para>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>exicyclog, exigrep, exim, exim-&exim-daemon-version;, exim_checkaccess,
        exim_dbmbuild, exim_dumpdb, exim_fixdb, exim_lock, exim_tidydb,
        eximstats, exinext, exipick, exiqgrep, exiqsumm, exiwhat, and
        optionally, eximon, eximon.bin, and sendmail (symlink)</seg>
        <seg>None</seg>
        <seg>/usr/share/doc/exim-&exim-version; and /var/spool/exim</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="exicyclog">
        <term><command>exicyclog</command></term>
        <listitem>
          <para>
            cycles <application>Exim</application> log files
          </para>
          <indexterm zone="exim exicyclog">
            <primary sortas="b-exicyclog">exicyclog</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exigrep">
        <term><command>exigrep</command></term>
        <listitem>
          <para>
            searches <application>Exim</application> log files
          </para>
          <indexterm zone="exim exigrep">
            <primary sortas="b-exigrep">exigrep</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim-prog">
        <term><command>exim</command></term>
        <listitem>
          <para>
            is a symlink to the <command>exim-&exim-daemon-version;</command>
            MTA daemon
          </para>
          <indexterm zone="exim exim-prog">
            <primary sortas="b-exim">exim</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim-current_version">
        <term><command>exim-&exim-daemon-version;</command></term>
        <listitem>
          <para>
            is the <application>Exim</application> mail transport agent daemon
          </para>
          <indexterm zone="exim exim-current_version">
            <primary sortas="b-exim-&exim-daemon-version;">exim-&exim-daemon-version;</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_checkaccess">
        <term><command>exim_checkaccess</command></term>
        <listitem>
          <para>
            states whether a given recipient address from a given host is
            acceptable or not
          </para>
          <indexterm zone="exim exim_checkaccess">
            <primary sortas="b-exim_checkaccess">exim_checkaccess</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_dbmbuild">
        <term><command>exim_dbmbuild</command></term>
        <listitem>
          <para>
            creates and rebuilds <application>Exim</application> databases
          </para>
          <indexterm zone="exim exim_dbmbuild">
            <primary sortas="b-exim_dbmbuild">exim_dbmbuild</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_dumpdb">
        <term><command>exim_dumpdb</command></term>
        <listitem>
          <para>
            writes the contents of <application>Exim</application>
            databases to the standard output
          </para>
          <indexterm zone="exim exim_dumpdb">
            <primary sortas="b-exim_dumpdb">exim_dumpdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_fixdb">
        <term><command>exim_fixdb</command></term>
        <listitem>
          <para>
            modifies data in <application>Exim</application> databases
          </para>
          <indexterm zone="exim exim_fixdb">
            <primary sortas="b-exim_fixdb">exim_fixdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_lock">
        <term><command>exim_lock</command></term>
        <listitem>
          <para>
            locks a mailbox file
          </para>
          <indexterm zone="exim exim_lock">
            <primary sortas="b-exim_lock">exim_lock</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exim_tidydb">
        <term><command>exim_tidydb</command></term>
        <listitem>
          <para>
            removes old records from <application>Exim</application>
            databases
          </para>
          <indexterm zone="exim exim_tidydb">
            <primary sortas="b-exim_tidydb">exim_tidydb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="eximstats">
        <term><command>eximstats</command></term>
        <listitem>
          <para>
            generates mail statistics from <application>Exim</application>
            log files
          </para>
          <indexterm zone="exim eximstats">
            <primary sortas="b-eximstats">eximstats</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exinext">
        <term><command>exinext</command></term>
        <listitem>
          <para>
            queries remote host retry times
          </para>
          <indexterm zone="exim exinext">
            <primary sortas="b-exinext">exinext</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exipick">
        <term><command>exipick</command></term>
        <listitem>
          <para>
            selects messages based on various criteria
          </para>
          <indexterm zone="exim exipick">
            <primary sortas="b-exipick">exipick</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exiqgrep">
        <term><command>exiqgrep</command></term>
        <listitem>
          <para>
            is a utility for selective queue listing
          </para>
          <indexterm zone="exim exiqgrep">
            <primary sortas="b-exiqgrep">exiqgrep</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exiqsumm">
        <term><command>exiqsumm</command></term>
        <listitem>
          <para>
            produces a summary of the messages in the mail queue
          </para>
          <indexterm zone="exim exiqsumm">
            <primary sortas="b-exiqsumm">exiqsumm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="exiwhat">
        <term><command>exiwhat</command></term>
        <listitem>
          <para>
            queries running <application>Exim</application>
          processes
          </para>
          <indexterm zone="exim exiwhat">
            <primary sortas="b-exiwhat">exiwhat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="eximon">
        <term><command>eximon</command></term>
        <listitem>
          <para>
            is a start-up shell script for <command>eximon.bin</command>
            used to set the required environment variables before running the
            program
          </para>
          <indexterm zone="exim eximon">
            <primary sortas="b-eximon">eximon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="eximon.bin">
        <term><command>eximon.bin</command></term>
        <listitem>
          <para>
            is a monitor program which displays current information in an
            <application>X</application> window, and also contains a menu
            interface to <application>Exim</application>'s command line
            administration options
          </para>
          <indexterm zone="exim eximon.bin">
            <primary sortas="b-eximon.bin">eximon.bin</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>