Fetchmail | Official Red Hat Linux Administrators Guide

Fetchmail is a program that can retrieve email from remote servers for on-demand TCP/IP connections. Many users appreciate the ability to separate the process of downloading their messages located on a remote server from the process of reading and organizing their email in an MUA. Designed with the needs of dial-up users in mind, Fetchmail will connect and quickly download all of your email messages to your mail spool file using any number of protocols, including POP3 and IMAP. It can even forward your email messages to an SMTP server, if necessary.

Before attempting to use Fetchmail, be sure that it is installed on your system. If it is not, you can install it using the fetchmail RPM on the Red Hat Linux CD-ROMs. Fetchmail is configured for each user through the use of a .fetchmailrc file in the user’s home directory. A program bundled with Fetchmail, called fetchmailconf, is very helpful for configuring a basic .fetchmailrc file that you can customize at will. Using preferences in the .fetchmailrc file, Fetchmail will check for email on a remote server and retrieve it, attempting to deliver it to port 25 on the local machine, using the local MTA to place the email in the correct user’s spool file. If Procmail is available, it can then be used to filter the email and place it in a mailbox so that it can be read with an MUA.

Fetchmail Configuration Options

Although it is possible to pass all options on the command line necessary to check for email on a remote server when executing Fetchmail, using a .fetchmailrc file is much easier. All of your configuration options go in the .fetchmailrc file, but you can override them at the time Fetchmail is run by specifying that option on the command line.

A user’s .fetchmailrc file is divided into three particular types of configuration options:

Global options — Gives Fetchmail instructions that control the operation of the program or provide settings for every connection that checks for email.
Server options — Specifies necessary information about the server being polled, such as the hostname, as well as preferences you would like to see enforced with a particular email server, such as the port to check or number of seconds to wait before timing out. These options affect every user option used with that server.
User options — Contains information, such as username and password, necessary to authenticate and check for email using a particular email server.

Global options go at the top of the .fetchmailrc file, followed by one or more server options, each of which designates a different email server that Fetchmail should check. User options follow server options for each user account you would like to check on that email server. Like server options, multiple user options may be specified for use with a particular server, such as when you would like to check multiple email accounts on the same server.

Server options are called into service in the .fetchmailrc file by the use of a special option verb, poll or skip, that precedes any of the server information. The poll action tells Fetchmail to use this server option when it is run, which actually checks it for email using the various user options. Any server options after a skip action, however, are not checked unless you specify this server’s hostname when Fetchmail is invoked. The skip option allows you to set up test configurations in .fetchmailrc and check using that server only when specifically desired, without affecting any currently working configurations.

A sample .fetchmailrc file looks like this:

set postmaster "user1"
 set bounce-mail poll pop.domain.com proto pop3     user 'user1' there with password 'secret' is user1 here poll mail.domain2.com     user 'user5' there with password 'secret2' is user1 here     user 'user7' there with password 'secret3' is user1 here

In this example, the global options are set so the user is sent email as a last resort (postmaster option) and all email errors are sent to the postmaster instead of the sender (bounce-mail option). The set action tells Fetchmail that this line contains a global option. Then, two email servers are specified, one set to check using POP3, and the other for trying various protocols to find one that works. Two users are checked using the second server option, but all email found for any users is sent to user1’s mail spool. This allows multiple mailboxes to be checked on multiple servers, while appearing in a single MUA inbox. Each user’s specific information begins with the user action.

Note

You do not have to place your password in the .fetchmailrc file. You can omit the password with the password password section. Fetchmail will then ask for your password when it is started with the fetchmail command.

While you can set up your .fetchmailrc file manually, it is much easier to let the included fetch-mailconf program do it for you. However, when testing new configurations, it is usually easier to edit the .fetchmailrc file directly.

As expected with a program that services such a mature network service as email and uses so many protocols, Fetchmail contains many different global, server, and local options. Many of these options are rarely used or apply to very specific situations only. The fetchmail man page explains each of these options in detail. The most common ones are listed here.

Global Options

Each global option should be placed on a single line after a set action.

daemon seconds — Tells Fetchmail to automatically use daemon-mode, where it will stay in the background and poll for mail at the interval specified.
postmaster — Gives Fetchmail a local user to send mail to in case of delivery problems.
syslog — Tells Fetchmail to start logging errors and status messages in the system’s log file. By default, this is /var/log/maillog.

Server Options

Place server options on their own line in .fetchmailrc after a poll or skip action.

auth auth-type — Specifies the type of authentication to be used. By default, password authentication is used, but some protocols support other types of authentication, including kerberos_v5, kerberos_v4, and ssh. If the “any authentication” type is used, Fetchmail will first try methods that do not require a password and then methods that mask your password, and finally it will attempt to send your password in the clear to authenticate to the server.
interval number — Tells Fetchmail to poll only this server every number of times that it checks for email on all configured servers. This option might be used with email servers on which you rarely receive messages.
port port-number — Overrides the default port number for a specified protocol.
proto protocol — Tells Fetchmail to use a specific protocol, such as POP3 or IMAP, to check for messages on this server.
timeout seconds — Configures Fetchmail to give up after a certain interval of server inactivity. If this value is not set, a default of 300 seconds is assumed.

User Options

User options may be placed on their own lines beneath a server option or on the same line as the server option. In either case, the user options follow the user name option (defined below).

fetchall — Orders Fetchmail to download all messages in the queue, including messages that have already been viewed. By default, Fetchmail pulls down new messages only.
fetchlimit number — Allows only a certain number of messages to be retrieved before stopping.
flush — Tells Fetchmail to delete all previously viewed messages in the queue before retrieving new messages.
limit max-number-bytes — Allows you to specify that only messages below a particular size may be retrieved. This option is useful with slow network links, when a large message will take too long to download.
password password — Specifies the password to be used for this user.
preconnect command — Tells Fetchmail to execute the specified command before retrieving messages for this user.
postconnect command — Tells Fetchmail to execute the specified command after retrieving messages for this user.
ssl — Allows Fetchmail to collect the message via an encrypted SSL connection, if the server supports this.
user username — Sets the username used by Fetchmail to retrieve messages. This option should be listed before any other user options.

Fetchmail Command Options

Most of the Fetchmail options that may be used on the command line, when executing the fetchmail command, mirror the .fetchmailrc configuration options. This is done so that Fetchmail may be used with or without a configuration file. Most users will not use these options on the command line, as it is easier to leave them in the .fetchmailrc file to be used automatically whenever Fetchmail is run. However, there are times when you may want to run the fetchmail command with other options for a particular purpose. As any options specified at the command line override configuration file options, you can also issue command options to temporarily override a .fetchmailrc setting that is causing an error.

Informational or Debugging Options

Certain options used after the fetchmail command can provide you with important information.

--configdump — Displays every possible option based on information from .fetchmailrc and Fetchmail defaults. No email is retrieved for any users when this option is used.
-s — Executes Fetchmail in silent mode, preventing any messages, other than error messages, from appearing after the fetchmail command.
-v — Executes Fetchmail in verbose mode, displaying every communication between Fetchmail and the remote email servers.
-V — Causes Fetchmail to display detailed version information, list its global options, and show settings to be used with each user, including the email protocol and authentication method. No email is retrieved for any users when this option is used.

Special Options

These options are occasionally useful for overriding defaults often found in the .fetchmailrc file.

-a — Tells Fetchmail to download all messages from the remote email server, whether new or previously viewed. By default, Fetchmail will download only new messages.
-k — Causes Fetchmail to leave messages on the remote email server after downloading them. This option overrides the default behavior of deleting messages after downloading them.
-l max-number-bytes — Tells Fetchmail to not download any messages over a particular size and to leave them on the remote email server.
--quit — Quits the Fetchmail daemon process.

More commands and .fetchmailrc options can be found on the fetchmail man page.