(As of 20 October 2004, this particular guide is listed in
FreeBSD's /usr/ports/UPDATING as a reference.)

The aim of this QND guide is to get you up and running quickly with getmail. There will be far more how than why here.

Getmail is aimed to be a replacement for fetchmail. Many people consider it faster and more secure than fetchmail. My personal experience has been that it seems to at least be a little faster.

Getmail will require that python is installed. Most distributions have python so it is rare that this will be problem.

Note that this page is about getmail version 4.x. Debian and some others, as of October 2004 are still using version 3.x For information about 3.x please see my getmail 3.x page.

1.) Do you have getmail?

If you get a response like /usr/bin/getmail or /usr/local/bin/getmail, you can skip to step 3. Otherwise, continue with step 2.

2.) Installing getmail

FreeBSD's ports or Gentoo's portage will install getmail for you. If you've downloaded the tarball then untar it somewhere and cd to the directory that is created. Using version 4.2.2 as an example

tar xzf getmail-4.2.2.tar.gz
cd getmail-4.2.2
python setup.py build
python setup.py install

4.) Configuring getmail

Now we will edit our new getmailrc file. This example is for FreeBSD which has maildrop in /usr/local/bin. Some Linux distributions will have maildrop in /usr/bin. If that's the case then change the /usr/local/bin/maildrop to /usr/bin/maildrop.

(I use maildrop as my example because it's what I use--many others use procmail.)

For user john, with an email address of john@isp.com, email user name john, a password of 1234, and an ISP whose pop server name is pserver.isp.com, we would like our getmailrc to look like this.

[options]
verbose = 0
delete = True

[retriever]
type = SimplePOP3Retriever
server = pserver.isp.com
username = john
password = 1234



[destination]
type = MDA_external
path = /usr/local/bin/maildrop
unixfrom = True

Note the line for maildrop. The above is for a FreeBSD machine, where maildrop is in /usr/local/bin. If you are using Linux, then it may be in /usr/bin. To find out simply type at a command prompt

and adjust your getmailrc accordingly. (The same holds for procmail, or any other external MDA)

As gmail becomes more and more popular, folks are often making use of its pop download feature, enabling you to receive gmail email on your normal client.

As gmail uses SSL the above configuration would work save for the SimplePop3Retriever line. For a gmail account, you want, assuming your gmail account is john@gmail.com with a password of 1234

[options]
verbose = 0
delete = True

[retriever]
type = SimplePOP3SSLRetriever
server = pop.gmail.com
username = john
password = 1234

[destination]
type = MDA_external
path = /usr/local/bin/maildrop
unixfrom = True

If one examines the docs, (/usr/local/share/doc/getmail/configuration.txt or configuration.html in FreeBSD) one finds that the default for the unixfrom line is false. However, some MDA's expect it. Both maildrop and procmail need it.

5.) Testing Getmail

If all is set up successfully, you should see it polling your pop server and retrieving your mail. Unlike fetchmail, getmail doesn't have a daemon option, so if you want it to poll your server at regular intervals, you will have to add a crontab entry. The man 5 crontab page explains things rather clearly, but a quick example.

On most systems, a user can edit his own crontab. So as user john you would do

crontab -e

This will open up your default text editor. Type in

*/5 * * * * /usr/local/bin/getmail

That will set getmail to run every 5 minutes. If you wish to change the interval you want to change the 5 to however many minutes you wish.

If for some reason, you aren't able to edit your own crontab then as root or with root privilege

One quick note of warning. If you wanted the job to run every two hours and made a crontab like this

* */2 * * * 

it would be running every minute. The correct way to specify the job to run every two hours would be

0 */2 * * *

With FreeBSD 5.1 and 5.2, I ran into an issue where getmail would either not run at all, or I would get a permission denied from crontab. This is mentioned on getmail's home page. The problem is that crontab has a shorter $PATH. The file (in FreeBSD) /usr/local/bin/getmail is simply a shell script. The top line read

#!/usr/bin/env python2.3 

I had to change that to reflect the complete path to python

#!/usr/bin/env /usr/local/bin/python2.3 

This solved that problem.

(As of late October, in FreeBSD that has been fixed. The first line gives the path to python and needs no modification.)

As of December, 2004, in FreeBSD 5.3 at least, if you have the most recent versions of both getmail and python, a DeprecationWarning regarding use of the "strict" keyword gets printed. If you have sendmail or another MTA sending you system messages, this will send you a message each time getmail retrieves mail.

To avoid this warning you can edit your crontab to read

*/5 * * * * /usr/local/bin/getmail > /dev/null 2>&1

With getmail 4.x each account will need a separate getmailrc file. If, for instance, one gets their home and work mail, create a getmailrc-home and getmailrc-work rc file. Put both of them in your .getmail directory and then, call getmail with

getmail -rgetmailrc-home -rgetmailrc-work

Note that getmail is going to look in ~/.getmail for the rcfiles, so as long as both files are in that directory, you don't need to specify their full path. They don't have to be called getmailrc-home, etc, you can simply call them home and work. If you don't specify the rcfile name, getmail looks for a ~/.getmail/getmailrc file. Therefore, whether you call it getmailrc-home or just home, you'll get an error unless you specify the rcfile as shown above.

If there is a non-fatal error, it will retrieve the mail but not delete it from the server. This is probably a Good Thing.(TM) For example, in ArchLinux, where I don't have spamassassin, I used my .mailfilter file from my BSD box, where I do have it. Getmail noted that there was no spamassissin and it went to STDERR. The message was retrieved, but remained on the server.

Another time, back when I used procmail, the issue was a simple mistype in my rc.lists, having put a capital letter o instead of the numeral zero in one of my rules. Procmail noted this, wrote to STDERR and getmail would retrieve the messages, but not delete them from the server, retrieving them each time it polled for mail.

In each case, once I fixed the error in my MDA's configuration file getmail deleted messages from the server as I wished.

References