$Id: README,v 1.17 2003/08/05 12:40:41 jt Exp $

Abstract:

This is the README for the Cygwin fetchmail distribution.

Fetchmail is a remote mail retrieval and forwarding utility intended
for use over on-demand TCP/IP links, like SLIP or PPP connections.
Fetchmail supports every remote-mail protocol currently in use on the
Internet (POP2, POP3, RPOP, APOP, KPOP, all IMAPs, ESMTP ETRN, IPv6,
and IPSEC) for retrieval. Then Fetchmail forwards the mail through SMTP
so you can read it through your favorite mail client.

I would like to thank Madoka Machitani for his pre-compiled fetchmail
and procmail binaries and for the patches necessary for proper operation
under Windows 9x/Me.  His work on the Cygwin ports made it much easier
for me to become the Cygwin maintainer.

Requirements:

The following packages or later are required to build and/or execute
Cygwin fetchmail:

    binutils 20030307-1
    cygwin 1.5.1-1
    gcc 3.2-3
    gettext 0.12.1-2
    libintl2 0.12.1-2
    openssl 0.9.7b-2

Install:

There are two major types of Cygwin fetchmail installations -- single
and multiple user.  The single user installation runs under a normal
user account while the multiple user type runs under the LocalSystem
account.

To install fetchmail for a single user, create a fetchmail run control
file, ~/.fetchmailrc, with contents like the following:

    set logfile /var/log/fetchmail.log
    set invisible
    set no bouncemail

    poll "$mailserver"
    protocol $popimap
    username "$username"
    password "$password"
    fetchall
    nokeep
    mda "/usr/bin/procmail -d %T"

where:

    $mailserver is your mail server name
    $popimap is "pop3" or "imap", as appropriate
    $username is your mailserver user name
    $password is your mailserver password

Typically fetchmail is run in daemon mode in order to retrieve one's
mail in the background.  Under Windows NT/2000/XP, Cygwin fetchmail can
be installed as a NT service.  To install Cygwin fetchmail as a service
use the following:

    $ cygrunsrv --install fetchmail --path /usr/bin/fetchmail --env HOME=$HOME --user "$USERDOMAIN\\$USERNAME" --args '--daemon 300 --nodetach' --shutdown

Note the following:

    o the above installs Cygwin fetchmail to run under your normal login
      account instead of the LocalSystem account
    o the account executing cygrunsrv must have local Administrators
      privileges for this command to succeed
    o the $USERDOMAIN\\$USERNAME account must have the "Log on as a service"
      user right for Cygwin fetchmail to start as a NT service

To install fetchmail for multiple users, create a fetchmail run control
file, ~system/.fetchmailrc, with contents like the following:

    set logfile /var/log/fetchmail.log
    set invisible
    set no bouncemail

    poll "$mailserver"
    protocol $popimap
    username "$username1" password "$password1" is "user1"
    username "$username2" password "$password2" is "user2"
    username "$username3" password "$password3" is "user3"
    # add more users as appropriate
    fetchall
    nokeep
    mda "/usr/bin/procmail -d %T"

where:

    $mailserver is your mail server name
    $popimap is "pop3" or "imap", as appropriate
    $usernameN is a mailserver user name
    $passwordN is a mailserver password
    $userN is a local user name

Note that the system home directory, ~system, will only be usable if:

    o the /etc/passwd system entry has been edited to be the following:

      SYSTEM:*:18:18:Local System,U-$COMPUTERNAME\LocalSystem,S-1-5-18:/home/system:/bin/bash

    o the /home/system directory has been created

where:

    $COMPUTERNAME is the local computer name

Under Windows NT/2000/XP, use the following to install Cygwin fetchmail
as a NT service:

    $ cygrunsrv --install fetchmail --path /usr/bin/fetchmail --args '--daemon 300 --nodetach' --shutdown

I do not have access to Windows 9x/Me, so I do not know how to run
fetchmail in daemon mode.  If someone knows how to best accomplish this,
then please post to the Cygwin list and I will update the README
accordingly.

Source:

Although fetchmail builds OOTB under Cygwin, one patch has been applied to
remove the run control file (i.e., ~/.fetchmailrc) permission check so that
fetchmail works under Windows 9x/Me and NT/2000/XP with CYGWIN=nontsec.

Note that this patch is identical to the one found on Madoka Machitani's
web site except that I replaced WIN9X with __CYGWIN__:

    http://www.dd.iij4u.or.jp/~madokam/#fetchmail

I also added the following files to the source archive:

    CYGWIN-PATCHES/README
    CYGWIN-PATCHES/build.sh
    CYGWIN-PATCHES/fetchmail.patch

and renamed the original source archive to match Cygwin's setup.exe
naming conventions.

To restore the fetchmail source to its original state, perform the
following:

    $ cd fetchmail-$version-$package
    $ patch -R -p1 <CYGWIN-PATCHES/fetchmail.patch
    $ rm -fr CYGWIN-PATCHES

where $version is the fetchmail version (e.g., 5.9.13) and $package is the
Cygwin package number.

Build:

This distribution has been configured as follows:

    configure --prefix=/usr --enable-NTLM --with-ssl --enable-fallback=procmail

See CYGWIN-PATCHES/build.sh in the source archive for my exact build
recipe for configuring, making, and packaging this distribution.

Test:

fetchmail does not contain any regression tests.

Issues:

The following are the known Cygwin fetchmail issues:

1. The patch applied to remove the the run control file permission
check is done at compile time -- it would have been better to do this
at run time.  Ultimately (i.e., after 6.0.0), I hope to leverage off of
the following patch:

    http://lists.ccil.org/pipermail/fetchmail-friends/2002-May/002149.html

to solve this issue in a better way.

2. SSL mode is untested and hence, has not been patched for Cygwin
(if necessary).  So, it is *possible* that mail can be corrupted in
a way similar to the non-SSL problem that I have workaround with my
Winsock patch.  Please post to the Cygwin mailing list if you have any
experience with Cygwin fetchmail in SSL mode.

Homepage:

The primary fetchmail web site is:

    http://catb.org/~esr/fetchmail/

Download:

The primary fetchmail ftp site is:

    ftp://ftp.ccil.org/pub/esr/fetchmail

Mailing Lists:

Please report problems, suggestions, etc. dependent on their nature to
one of the following:

    fetchmail-friends@lists.ccil.org
    cygwin@cygwin.com

Maintainer:

    Jason Tishler <jason@tishler.net>