getmail Frequently Asked Questions
Author: Charles Cazabon

## getmail Frequently Asked Questions (FAQ)

These are the Frequently Asked Questions about getmail. If your question is not answered here or in the documentation, please subscribe to the mailing list.

### About this document

The official location of this document is http://www.qcc.ca/~charlesc/software/getmail-3.0/docs.html. For easy navigation, all headings in the HTML version of this document are links to their parent heading.

### Table of Contents

1. About getmail
2. Error messages
3. getmail configuration
4. Other errors
5. How do I …

### About getmail

#### What is getmail?

getmail is a POP3 mail retriever, with support for both ordinary and domain (or multidrop) POP3 mailboxes. It is written in Python, and licensed under the GNU General Public License version 2.

#### Why did you write getmail? Why not just use fetchmail?

I do not like some of the design choices which were made with fetchmail. getmail does things a little differently, and for my purposes, better. In addition, most people find getmail easier to configure and use than fetchmail. Perhaps most importantly, getmail goes to great lengths to ensure that mail is never lost, while fetchmail (in its default configuration) frequently loses mail, causes mail loops, bounces legitimate messages, and causes many other problems.

In addition, fetchmail has a long history of security problems:

- versions released before 20 June 2001 contain a buffer overflow, which can be remotely exploited (see www.securityfocus.com/bid/2877 for details). getmail is not vulnerable to buffer overflows, because buffers in Python are dynamically sized.
- Another remotely-exploitable security hole discovered in fetchmail in June 2002; versions prior to 5.9.10 (released in June 2002) are exploitable.
- Reading fetchmail's UPDATES file, it appears that another security problem was fixed in 5.9.12, where a server could crash fetchmail on 64-bit platforms. Also worrying is a mention that it includes a fix for "password shrouding".
- Another remotely-exploitable security hole in fetchmail discovered in September 2002; this hole lets an attacker run arbitrary code on the victim's computer.
- Another remotely-exploitable security hole in fetchmail discovered in December 2002; once again, a remote attacker can run arbitrary code on the machine running fetchmail in its default configuration. See this advisory for details.
- January 2003: More buffer overflows in fetchmail let attackers run arbitrary code.
- October 2003: Anyone can cause fetchmail to crash by sending you a message. Other problems are here, and I might have missed some.

I've given up even trying to stay abreast of the various security holes in fetchmail.

But don't just take my word for it.

getmail users have not had to worry about any of these security holes.

#### How can I get support for getmail?

getmail is Free Software. As such, it comes with no warranty. However, I will do my best to support getmail on a voluntary basis through the getmail mailing list.

If you are using getmail in a commercial or other environment where problems cost money, consider contacting me privately for commercial support.

If you have questions about getmail, the first step is to read the documentation, and the remainder of the Frequently Asked Questions. If your question isn't answered there, search the getmail mailing list archives at http://marc.theaimsgroup.com/?l=getmail&r=1&w=2.

If you still haven't found an answer to your question, please subscribe to the mailing list by sending a blank email to <getmail-subscribe @ discworld.dnsalias.org>. If you post your question there, I will see it. As an additional bonus, your question may be answered by another member of the list.

#### I think I found a bug! How do I report it?

Ideally, you should join the mailing list. Send your bug report there. You should include the following information:

- getmail version
- Python version
- any error message which getmail displayed
- the output from running getmail with your normal options plus --dump
- if your problem is getmail not determining the proper local recipient, please include the output of running getmail with your normal options plus --trace, showing the retrieval of one problematic message.

If you absolutely cannot sign up for the mailing list, send the report to me directly. I may not be able to respond to all reports privately, but I will try to address any bugs I find out about this way.

#### Does getmail support virus scanning of retrieved messages?

Yes, getmail can use external MDAs which do absolutely any type of message scanning, filtering, etc. Also see this question about how to do this.

#### Does getmail rewrite mail headers when it retrieves mail?

No—rewriting message header fields is bad. getmail will add a new Received: header field and a new Delivered-To: header field, but does not rewrite existing headers. You can disable the creation of these header fields.

#### How does getmail decide what local recipients to deliver a message to?

This is a two-step process.

1. getmail first tries to find who the message was originally addressed to using one of two methods:
   - If you have enabled SPDS *ENV support, getmail will retrieve the original envelope of the message from an SPDS-enabled server (i.e. Demon provides this).
   - Envelope recipient address method. If the MTA running on the POP3 servers is sensible, it will record the envelope recipient address in a new header field at the top of the message. You can then tell getmail to find it using the envelope_recipient directive.
2. getmail will then compare each address found above to any configured local recipient address patterns. If a pattern matches, getmail will deliver the message to that target. If no patterns match, or if you have not configured getmail to reconstruct the original envelope, the message is delivered to the default delivery instruction (postmaster directive).

### Error Messages

#### getmail fails with a message "AttributeError: 'module' object has no attribute 'fsync'

This is not a problem with getmail; it is a well-known bug in the Python 2.3.1 distribution. Downgrade to Python version 2.3.0 or before, or upgrade to 2.3.2, which should fix the problem.

#### getmail complains about "incomplete format string" …

Double any percent signs you have in your getmailrc file—i.e., if your password is foo%bar, then actually specify it as foo%%bar.

#### getmail complains about "error in getmailrc file (expected option value, got … )"

You have a syntax error in your getmailrc file. Empty option values are not allowed. If you want to specify an empty string as an option value, you have to quote it:

    foo = ""

#### getmail complains about "configuration error in getmailrc file (/path/to/getmailrc): file is group- or world-writable". What's wrong?

Your getmailrc configuration file is group- or world-writable. For security reasons, getmail refuses to run with a group- or world-writable getmailrc file. Change the permissions on that file.

#### getmail complains about "Configuration error (local directives require use_*env or envelope_recipient to identify envelope recipient)". What's wrong?

The account configuration in question contains local directives, but you haven't told getmail how to determine the original envelope recipient address of the message. To use multidrop mode, you must either enable use_*env (if your mailhost supports it) or tell getmail which header field the envelope recipient address is recorded in by the mailhost's MTA using the envelope_recipient directive.

#### getmail complains about "Configuration error (no matching header fields (something))". What's wrong?

You've used the envelope_recipient directive to enable domain mailbox operation, but a retrieved message didn't contain the header field you specified. To use multidrop mode, you must either enable use_*env (if your mailhost supports it) or tell getmail which header field the envelope recipient address is recorded in by the mailhost's MTA using the envelope_recipient directive.

#### getmail complains about "Delivery error (refuse to deliver to commands as root)". What's wrong?

You're running getmail as user "root" (UID 0) and trying to have getmail run an external command. The documentation says don't do that.

### getmail configuration

#### What is a "domain mailbox"?

A domain (or multidrop) mailbox is a POP3 mailbox which receives mail for all users in a given domain. Normal mailboxes contain mail for a single user (like jason@myisp.co.uk); some Internet Service Providers which provide webhosting or other services will provide a POP3 mailbox which receives mail for all addresses in a given domain (i.e. mail for service@smallcompany.net, sales@smallcompany.net, and indeed anything @smallcompany.net ends up in the same POP3 mailbox).

getmail provides a method of retrieving mail from a domain mailbox and distributing it among the various users automatically. See the documentation sections on header field pattern matching delivery targets, envelope recipient address field specification, default delivery target, and POP3 domain mailboxes.

#### Do I have to run sendmail or another MTA to use getmail?

No. getmail delivers directly to Maildirs or via arbitrary MDAs, and never injects mail via SMTP, so no MTA is necessary. P.S. If you're currently running sendmail, consider switching to qmail if you need a full MTA, or nullmailer if you relay all your mail through your ISP's smarthost. Both of them are better and more secure than sendmail.

#### I've got a simple POP3 account. Do I need "local=…" configuration variables?

No, you don't need them. They might be useful to you if the MTA on the POP3 server supports extension addresses (i.e. qmail) and records the envelope recipient address properly. But in general, you will only need to use a postmaster directive.

### Other getmail errors

#### I've configured getmail to deliver to my Maildir, but it won't do it. Why?

Double-check your getmailrc file. Maildir delivery targets must include a trailing slash.

#### I've configured getmail to deliver to my mbox file, but it won't do it. Why?

getmail 3.x does not have native mbox support, as all mbox-capable MDAs on a given system must use the same locking mechanism and support the same mbox subtype. You can use getmail's command delivery mechanism to deliver through an external mbox-aware MDA (see the next paragraph) if you must, but consider using maildirs instead.

getmail includes getmail_mbox, an mbox delivery agent you can use in this fashion. It supports mboxrd-format mbox files and uses flock-style locking. Make sure these are the correct types for your system before using it, as all mbox-handling programs on a system must use the same types and values.

To use getmail_mbox to deliver to mbox files, specify it as an external MDA. It takes the path to the mbox file as a commandline argument, as follows:

    getmail_mbox /path/to/mbox

Example uses:

    postmaster = "|/path/to/getmail_mbox /path/to/mbox"
    local = "^joe@.*$,|/path/to/getmail_mbox /home/joe/mbox"
    local = "^sam@.*$,|/path/to/getmail_mbox /home/sam/mbox"

#### I've configured getmail to deliver to a command (external MDA), but it complains that the command exited 0 but wrote to stderr. Why?

Command deliveries must exit 0 and not write anything to stderr to be considered a successful delivery. If you know your MDA can write to stderr on success, give your command a --quiet option (if it supports it) or discard or redirect stderr in the command specification of the delivery target.

#### Why does getmail retrieve all my messages when I've told it to only retrieve new mail?

Your POP3 mail server is probably broken. getmail requires that the server support the POP3 UIDL command to uniquely identify messages. If the server doesn't support it, getmail cannot tell which messages it has already seen, and therefore retrieves all messages.

### How do I …

#### How do I stop getmail adding a Delivered-To: header to email?

Use the no_delivered_to configuration directive.

#### How do I stop getmail adding a Received: header to email?

Use the no_received configuration directive.

#### How do I make getmail deliver messages to a program?

Specify the delivery target as |path-to-command. You should probably use full paths (e.g. /usr/bin/maildrop). As a basic security precaution, getmail will refuse to deliver to programs if it is running as root.

Warning: if you don't know what you're doing, you can shoot yourself in the foot with this option.

#### How do I make getmail deliver messages by re-injecting with SMTP?

You don't. getmail doesn't do this, to prevent lost mail, mail loops, and bounces if getmail or your Mail Transfer Agent is misconfigured. getmail has native support for delivering to qmail-style Maildirs and commands (pipe delivery). Therefore you shouldn't need to re-inject retrieved messages.

If you absolutely must inject retrieved messages into an MTA, it is possible to do this knowing no more than what is included in the getmail documentation. If you know enough about mail to avoid the pitfalls mentioned above, you don't need my help figuring out how.

#### How do I make getmail use SSL / talk to an SSL-wrapped POP3 server (POP3S)?

Use the SSL utility stunnel to set up an SSL tunnel from a port on your machine to the SSL-wrapped POP3 port (typically TCP port 995) on the mailserver. Then configure getmail to connect to the local end of the tunnel.

The easiest way to do this is to use a tiny shellscript wrapper which sets up the tunnel and then runs getmail. An example would be:

    #!/bin/sh
    /usr/sbin/stunnel -c -D 4 -d 8110 -r 192.168.2.3:995
    getmail

The above script sets up a tunnel from port 8110 on localhost to port 995 on the mailserver at 192.168.2.3. You would then use the following getmailrc configuration:

    [SSL-wrapped access to my mail]
    server = localhost
    port = 8110
    username = me
    password = mypassword

Note that there are security considerations with this configuration, as with all configurations. For instance, do not configure getmail to connect to a port that another local user might have already set up a listener on; stunnel could fail to set up the tunnel, and if the other user had set up a POP3 listener, getmail would send your credentials to it. You could set up the tunnel on a privileged port to prevent non-privileged local users from mounting this type of attack.

#### How do I run getmail in "daemon" mode?

Use your system's cron utility to run getmail periodically if you wish to have mail retrieved automatically at intervals. This is precisely what cron is designed to do; there's no need to add special code to getmail to do this.

Keep in mind that cron usually runs user cron jobs in a simpler environment than the user has in a login shell. In particular, $PATH is frequently much shorter. If your getmail shell script wrapper has `which python` or similar in it, you might need to explicitly set $PATH or change the wrapper to point explicitly to the Python interpreter.

#### How do I use SpamAssassin (or another spam-filtering solution) with getmail?

Use it as an external MDA, which getmail supports. getmail user "Frankye" contributed a working SpamAssassin setup in this list message. Also see his (and others') contributions in this thread about spam filtering.

#### How do I use TMDA with getmail?

TMDA is the Tagged Message Delivery Agent, an excercise in preventing spam from ever reaching your inbox.

To make getmail export the environment variables which TMDA needs, you must use local directives in your getmailrc file. You can then optionally set the extension_sep and extension_depth directives.

For example, if getmail determines the envelope recipient to be domain-user-ext1-ext2@otherdomain.tld, extension_sep is set to -, and extension_depth is set to 1, then getmail will set EXT to user-ext1-ext2. If extension_depth is 2, it will instead set EXT to ext1-ext2.

TMDA renames existing Delivered-To: header fields to Old-Delivered-To:. Previous versions (0.55 through 0.57 or so) instead tried to strip recent Delivered-To: fields and may have required disabling getmail's addition of new Delivered-To: header fields.

You will need a wrapper around TMDA to use in a command delivery target which conditionally delivers the message based on TMDA's exit code. getmail does not include such a wrapper; you will need to write it or find it yourself.

Note that getmail will only be able to determine the envelope recipient address (and extension part of that address) reliably if the MTA at the POP3 server is configured to record the envelope recipient in a message header field (i.e. as qmail does with Delivered-To:), and you have configured getmail to only look at that header field with the envelope_recipient directive, or if your ISP supports the SPDS *ENV extension and you have configured getmail to use it.

If anyone has concrete experience using getmail and TMDA together, please feel free to send instructions or your wrapper script to me; I personally do not use a filtering MDA and therefore have no experience making TMDA work with getmail.

#### How do I do virus scanning of retrieved messages with getmail?

You can do this in hundreds of different ways. There are many threads in the mailing list archive dealing specifically with this topic; please read at least all of February 2003, including this thread, before posting to the mailing list.

#### How do I do message filtering with getmail?

The best way is to use a program designed specifically to do message filtering, like a filtering MDA. The best-known example of a filtering MDA is procmail, but I don't recommend using it. maildrop is much easier to use.

getmail can invoke arbitrary programs as external MDAs, so you can also write your own filters as you choose. A simple example, changing all occurrences of the string "stupid" to "XXXXXX" and using safecat to deliver the resulting filtered message to a Maildir might be to specify a delivery target of

    |/bin/sed 's/stupid/XXXXXX/g' | safecat ./Maildir/tmp ./Maildir/new

.