aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 5eeaa57c56aaace723cef37f5b9d41ad915a7c3e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
			 fetchmail README

fetchmail is a full-featured, robust, well-documented POP2, POP3,
APOP, and IMAP batch mail retrieval/forwarding utility intended to be
used over on-demand TCP/IP links (such as SLIP or PPP connections).
It retrieves mail from remote mail servers and forwards it to your
local (client) machine's delivery system, so it can then be be read by
normal mail user agents such as elm(1) or Mail(1).

The fetchmail code was developed under Linux, but should be readily
portable to other Unix variants (it uses GNU autoconf).  It has also
been ported to QNX; to build under QNX, see the header comments in the
Makefile.

Here are fetchmail's main features.  Those unique to fetchmail
(relative to fetchpop1.9, PopTart-0.9.3, get-mail, gwpop, pimp-1.0,
pop-perl5-1.2, popc, popmail-1.6 and upop) are marked with **.

	*  **POP2, POP3, **APOP, **IMAP2bis, **IMAP4 support.

	** Support for Kerberos user authentication (either MIT or Cygnus).

	** Host is auto-probed for a working server if no protocol is
	   specified for the connection.  Thus you don't need to know
	   what servers are running on your mail host in advance; the
	   verbose option will tell you which one succeeds.

	** Delivery via via SMTP to the client machine's port 25.  This
	   means the retrieved mail automatically goes to the system
	   default MDA as if it were normal sender-initiated SMTP mail.

	** Timeout if server connection is dropped.

	** Support for retrieving and forwarding from multi-drop mailboxes
	   that is guaranteed not to cause mail loops.

	*  Easy control via command line or free-format run control file.

	*  Daemon mode -- fetchmail can be run in background to poll
	   one or more hosts at a specified interval.

	*  From:, To:, Cc:, and Reply-To: headers are rewritten so that 
	   usernames relative to the fetchmail host become fully-qualified
	   Internet addresses.  This enables replies to work correctly.
	   (Would be unique to fetchmail if I hadn't added it to fetchpop.)

	*  Strict conformance to relevant RFCs and good debugging options.
	   You could use fetchmail to test and debug server implementatations.

	*  Carefully written, comprehensive and up-to-date man page describing
	   not only modes of operation but also (**) how to diagnose the most
	   common kinds of problems and what to do about deficient servers

	*  Rugged, simple, and well-tested code -- the author relies on it
           every day and it has never lost mail, not even in experimental
	   versions.

	*  Large user community -- fetchmail has a large user base (the
	   author's beta list includes over a hundred people).  This means
	   feedback is rapid, bugs get found and fixed rapidly.

The fetchmail code appears to be stable and free of bugs affecting
normal operation (that is, retrieving from POP3 or IMAP and forwarding
99via SMTP to sendmail).  It will probably undergo substantial change
only if and when support for a new retrieval protocol or authentication
is added.  See the distribution files NEWS for detailed information on
recent changes and NOTES for design notes.

You can easily fetch the latest version of fetchmail  via FTP from the
following FTP directory:

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

Or you can get it from Eric's home page:

	http://www.ccil.org/~esr

Just chase the link to Eric's Freeware Collection.  Besides fetchmail, it
includes a tasty selection of Web authoring tools, programmer's aids,
graphics libraries, compilers for bizarre languages, games, and 
miscellaneous interesting hacks.  Enjoy!

							-- esr
highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
These are scripts or configuration snippets to help you running
fetchmail in special situations.

Note: you're on your own using these -- the fetchmail team undertakes no
efforts in understanding them, they are just passing them along.
								--esr, ma

This file is currently unsorted. Use your pager's search function when
looking for the description of a particular file in this directory.  --ma

### 0*.html:
Messages from the archives of the old fetchmail-friends mailing list,
for off-line reading.

### maildaemon:
Larry Fahnoe wrote this for driving fetchmail from cron.  It may be useful if
you want to force a PPP link up and then poll for mail at specified times.
I have rearranged it slightly to make it easier to configure.

### novell:

Some mail from Dan Newcombe describing how to write a procmail rule that
will domainify Novell server names.

### login & logout:

These are intended to help if you typically have multiple logins active.
Here's the script composer's original README:

	Please find attached 2 files, ~/.bash_login & ~/.bash_logout
	What these do is try to keep track of WHO is the process/tty
	that ran fetchmail in daemon mode.  I tried to use the bash
	Variable PPID, but when using xterm the PPID is set to the
	xterm's pid not the bash shell's pid so....

	They have been lightly tested.

	Any comments...

 				Hth, JimL <babydr@nwrain.net>

Doug Carter <dougc@canus.com> suggests this instead:

Add the following to your login script. (.ie .bash_profile, .profile, etc)

LOGINS=`who | grep $USER | wc -l`
if [ $LOGINS = 1 ]; then
    /usr/bin/fetchmail > /dev/null 2>&1
fi

Then add the following to your logout script. (.ie .bash_logout, etc)

LOGINS=`who | grep $USER | wc -l`
if [ $LOGINS = 1 ]; then
    /usr/bin/fetchmail -q > /dev/null 2>&1
fi

### ip-up:

A note from James Stevens about using fetchmail in an ip-up script without
disabling timeouts.

### runfetchmail:

A shellscript front end for fetchmail that mails you various statistics on
the downloaded mail and the state of your folders.  A good example of what
you can do with your own front end.

### fetchspool:

If you find that the speed of forwarding to port 25 is limited by the
SMTP listener's speed, it may make sense to locally spool all the mail
first and feed it to sendmail after you hang up the network link.
This shellscript aims to do exactly that.  It would be smarter to
figure out why sendmail is slow, however.

### fetchsetup:

This is a shell script for creating a $HOME/.fetchmailrc file, it will ask
you some questions and based on your answers it will create a .fetchmailrc
file. fetchsetup is linux specific so it may not work on another operating
system.

### mailqueue.pl:

This script will connect to your ISP (if not already connected),
send any outgoing mail and retrieve any incoming mail.  If this
program made the connection, it will also break the connection
when it is done.  By Bill Adams, <bill@evil.inetarena.com>.  The
latest version is carried at <http://evil.inetarena.com/>.

### redhat_rc:

A fetchmail boot-time init file compatible with RedHat 5.1.  It leaves
fetchmail in background to get messages when you connect to your ISP.
The invoked fetchmail expects to find its configuration in
/etc/fetchmailrc, and must include the proper "interface" directive.

### debian_rc:

A fetchmail boot-time init file compatible with Debian.  It leaves
fetchmail in background to get messages when you connect to your ISP.
The invoked fetchmail expects to find its configuration in
/root/.fetchmailrc, and must include the proper "interface" directive.

Matthias Andree adds: note that current Debian packages (as of January
2007) ship with their own init files.

### start_dynamic_ppp:

An admittedly scratchy ip-up script that Ryan Murray wrote to cope with
dynamic PPP addressing.  Will need some customizing.

	http://www.inetarena.com/~badams/linux/programs/mailqueue.pl

### getfetchmail:

Here's a script that gets Eric's most recent fetchmail source rpm,
downloads it and (if the rpm's not broken) rebuilds it.

With fairly simple changes it can be used to download the latest i386 rpm
or tar.gz.

Those who are addicted to having the latest of everything could filter mail
from fetchmail announce through it and get new versions as they're
announced. However, if we all did that, Eric's ftp server might feel a
little stressed.

The script as written works on bash 2.  By John Summerfield
<summer@os2.ami.com.au>.

### zsh-completion:

These commands set up command completion for fetchmail under zsh.
Jay Kominek <jay.kominek@colorado.edu>.

### getmail/gotmail:

These scripts are front ends for fetchmail in daemon mode that can gather
log statistics and generate text or HTML reports.  See README.getmail for
details.  Scripts by Thomas Nesges <ThomaNesges@TNT-Computer.de>.

### fetchmaildistrib:

This script resolves the issue where the sysadmin polls for mail with fetchmail
only at set intervals, but where a user wishes to see his email right
away. The duplication in /etc/fetchmailrc and ~/.fetchmailrc files is
automated with this script; whenever /etc/fetchmailrc is changed, this
script is run to distribute the stuff into all user's ~/.fetchmailrc
files.

### multidrop:

Martijn Lievaart's sendmail hacks to make multidrop reliable.

### domino:

Gustavo Chaves <gustavo@cpqd.com.br> wrote this script to deal with 
the boundary-mismatch bug in Domino (see FAQ item X5).  If you use
this with --mda, the broken boundaries will be fixed and the result
passed to procmail.

### toprocmail:

John Lim Eng Hooi <jleh@mail.com> wrote this script, yet another 
mda plugin, to be used with fetchmail in foreground mode.  It displays
some header lines to stdout in color, passing them (and the rest of the
message content) to procmail.

### preauth-harness:

Emmanuel Dreyfus's Perl test script for exercising IMAP PREAUTH
connections.  You'll have to patch in your username and password.

### sm-hybrid:

Peter 'Rattacresh' Backes sent this patch to improve the behavior of 
sendmail 8.11.0 with multidrop.

### fetchmailnochda.pl

Watchdog script to check whether fetchmail is working in daemon mode.

### mold-remover.py

A short python script to remove old read mail from a pop3 mailserver.
Dovetails with fetchmail with keep option.  Run it as a cron job.

### PopDel.py

PopDel stands for Pop Delete; this program deletes selected email from a
pop mail server. (By Richard Harris, improved by Joshua Crawford.)

### fetchmail.logrotate (added 2007-01-14, --ma)

A logrotate configuration file developped by Daniel Leidert for Debian,
when he wanted to use /var/log/fetchmail instead of the usual syslog.
It probably needs to be adjusted for use on other systems.

### delete-later (added 2007-03-17, --ma)

A MySQL/Tcl/Expect-based client-side script to remove messages at a
certain age.  See delete-later.README for details.
(By Carsten Ralle, Yoo GmbH, Germany.)

### gai (added 2013-02-03, --ma)

A trivial getaddrinfo() program to check the getaddrinfo() call from the
system, as a research tool for the fetchmail developers.