source: networking/mailnews/fetchmail.xml@ ebccba3

<?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 fetchmail-download-http "&sourceforge-dl;/fetchmail/fetchmail-&fetchmail-version;.tar.xz">
  <!ENTITY fetchmail-download-ftp  " ">
  <!ENTITY fetchmail-md5sum        "61db4f95af4f1a5f95e7ea632928d48d">
  <!ENTITY fetchmail-size          "1.1 MB">
  <!ENTITY fetchmail-buildsize     "15 MB including tests">
  <!ENTITY fetchmail-time          "0.1 SBU including tests">
]>

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


  <title>Fetchmail-&fetchmail-version;</title>

  <indexterm zone="fetchmail">
    <primary sortas="a-Fetchmail">Fetchmail</primary>
  </indexterm>

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

    <para>
      The <application>Fetchmail</application> package contains a mail
      retrieval program. It retrieves mail from remote mail servers and
      forwards it to the local (client) machine's delivery system, so it can
      then be read by normal mail user agents.
    </para>

    &lfs113_checked;

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

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      a local MDA (<xref linkend="procmail"/>)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <!-- hesiod was at ftp://athena-dist.mit.edu/pub/ATHENA/hesiod/ but that
      is dead. Debian had 3.2.1, git hub has a very old 3.1.
      libintl is part of gettext so enabled by default on LFS -->
      <xref linkend="mitkrb"/> and
      <ulink url="http://www.citi.umich.edu/projects/nfsv4/linux/">libgssapi</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (for running fetchmailconf)</bridgehead>
    <para role="optional">
      <xref linkend="python3"/>, built after
      <xref linkend="tk"/>, with the
      <ulink url="https://python-future.org/">py-future</ulink> package
    </para>

  </sect2>

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

    <para>
      Create a dedicated user for the fetchmail program.
      Issue the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>useradd -c "Fetchmail User" -d /dev/null -g nogroup \
        -s /bin/false -u 38 fetchmail</userinput></screen>

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

<screen><userinput>PYTHON=python3 \
./configure --prefix=/usr \
            --enable-fallback=procmail &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>.
    </para>


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

<screen role='root'><userinput>make install                                  &amp;&amp;
chown -v fetchmail:nogroup /usr/bin/fetchmail</userinput></screen>

  </sect2>

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

    <para>
      <parameter>PYTHON=python3</parameter>: a version of Python is
      <emphasis>required</emphasis>, but only used to install a module to allow
      fetchmailconf to be run. That module is unmaintained and should not be
      used.
    </para>

    <para>
      <parameter>--enable-fallback=procmail</parameter>: This tells
      <application>Fetchmail</application> to hand incoming mail to
      <application>Procmail</application> for delivery, if the port 25 mail
      server is not present or not responding.
    </para>

  </sect2>

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

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

      <para>
        <filename>~/.fetchmailrc</filename>
      </para>

      <indexterm zone="fetchmail fetchmail-config">
        <primary sortas="e-AA.fetchmailrc">~/.fetchmailrc</primary>
      </indexterm>

    </sect3>

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

      <note>
        <para>
          If you are connecting to a mailserver that supports SSL/TLS-wrapped
          or "implicit" mode on a dedicated port (default 993) you should use
          <command>fetchmail --ssl</command> or add the option 'ssl' in an
          rcfile.
        </para>
      </note>

<screen><userinput>cat &gt; ~/.fetchmailrc &lt;&lt; "EOF"
<literal>
# The logfile needs to exist when fetchmail is invoked, otherwise it will
# dump the details to the screen. As with all logs, you will need to rotate
# or clear it from time to time.
set logfile fetchmail.log
set no bouncemail
# You probably want to set your local username as the postmaster
set postmaster <replaceable>&lt;username&gt;</replaceable>

poll SERVERNAME :
    user <replaceable>&lt;isp_username&gt;</replaceable> pass <replaceable>&lt;password&gt;</replaceable>;
    mda "/usr/bin/procmail -f %F -d %T";</literal>
EOF

touch ~/fetchmail.log       &amp;&amp;
chmod -v 0600 ~/.fetchmailrc</userinput></screen>

      <para>
        This is an example configuration that should suffice for most people.
        You can add as many users and servers as you need using the same syntax.
      </para>

      <para>
        <command>man fetchmail</command>: Look for the section near the bottom
        named <emphasis>CONFIGURATION EXAMPLES</emphasis>. It gives some quick
        examples. There are countless other configuration options once you get
        used to it.
      </para>

      <para>
        If you expect to receive very little mail you can invoke fetchmail
        when you wish to receive any incoming mail. More commonly, it is either
        invoked in daemon mode with the <literal>-d</literal> option either on
        the command line, or in <filename>.fetchmailrc</filename> (see 'DAEMON
        MODE' in man fetchmailconf), or alternatively it is invoked from a
        cron job.
      </para>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>fetchmail and fetchmailconf</seg>
        <seg>None</seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="fetchmail-prog">
        <term><command>fetchmail</command></term>
        <listitem>
          <para>
            when executed as a user, this will source
            <filename>~/.fetchmailrc</filename> and download the appropriate
            mail
          </para>
          <indexterm zone="fetchmail fetchmail-prog">
            <primary sortas="b-fetchmail">fetchmail</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="fetchmailconf">
        <term><command>fetchmailconf</command></term>
        <listitem>
          <para>
            is intended to assist you in setting up and editing a
            <filename>~/.fetchmailrc</filename> configuration file, by using
            a <application>Tk</application> GUI interface. It is written for
            <application>Python</application> and the Tkinter module but is
            labelled with a WARNING that it needs to be updated
            for fetchmail 6.4's SSL options and other recent new options
          </para>
          <!-- keep this description commented but fetchmailconf
               has been updated in the last months (June 2020). It can use
               Python 3, with the help of the "past" module.
          <para>
            is an unmaintained GUI command to assist in creating a
            <filename>~/.fetchmailrc</filename> configuration file and
            should not be used.
          </para>-->
          <indexterm zone="fetchmail fetchmailconf">
            <primary sortas="b-fetchmailconf">fetchmailconf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>