Fetchmail

Fetchmail is an MTA which retrieves email from remote servers and delivers it to the local MTA. 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 connects and quickly downloads all of the email messages to the mail spool file using any number of protocols, including POP3 and IMAP. It can even forward email messages to an SMTP server, if necessary.

Fetchmail is configured for each user through the use of a .fetchmailrc file in the user's home directory.

Using preferences in the .fetchmailrc file, Fetchmail checks for email on a remote server and downloads it. It then delivers 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 is launched to filter the email and place it in a mailbox so that it can be read by an MUA.

Fetchmail Configuration Options

Although it is possible to pass all necessary options on the command line to check for email on a remote server when executing Fetchmail, using a .fetchmailrc file is much easier. Place any desired configuration options in the .fetchmailrc file for those options to be used each time the fetchmail command is issued. It is possible to override these at the time Fetchmail is run by specifying that option on the command line.

A user's .fetchmailrc file contains three classes 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 for specific email servers, such as the port to check or number of seconds to wait before timing out. These options affect every user using that server.
user options - Contains information, such as username and password, necessary to authenticate and check for email using a specified email server.

Global options appear at the top of the .fetchmailrc file, followed by one or more server options, each of which designate a different email server that Fetchmail should check. User options follow server options for each user account checking that email server. Like server options, multiple user options may be specified for use with a particular server as well as 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 checks for email using the specified user options. Any server options after a skip action, however, are not checked unless this server's hostname is specified when Fetchmail is invoked. The skip option is useful when testing configurations in .fetchmailrc because it only checks skipped servers when specifically invoked, and does not affect any currently working configurations.

A sample .fetchmailrc file looks similar to the following example:

set postmaster "user1"
set bouncemail
 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 specify that the user is sent email as a last resort (postmaster option) and all email errors are sent to the postmaster instead of the sender (bouncemail 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, 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 user 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.

Users are not required to place their password in the .fetchmailrc file. Omitting the with password '<password>' section causes Fetchmail to ask for a password when it is launched.

Fetchmail has numerous global, server, and local options. Many of these options are rarely used or only apply to very specific situations. The fetchmail man page explains each option in detail, but 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> - Specifies daemon-mode, where Fetchmail stays in the background. Replace <seconds> with the number of seconds Fetchmail is to wait before polling the server.

postmaster - Specifies a local user to send mail to in case of delivery problems.
syslog - Specifies the log file for errors and status messages. By default, this is /var/log/maillog.

Server Options

Server options must be placed on their own line in .fetchmailrc after a poll or skip action.

auth <auth-type> - Replace <auth-type> with 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 first tries methods that do not require a password, then methods that mask the password, and finally attempts to send the password unencrypted to authenticate to the server.

interval <number> - Polls the specified server every <number> of times that it checks for email on all configured servers. This option is generally used for email servers where the user rarely receives messages.
port <port-number> - Replace <port-number> with the port number. This value overrides the default port number for the specified protocol.
proto <protocol> - Replace <protocol> with the protocol, such as pop3 or imap, to use when checking for messages on the server.
timeout <seconds> - Replace <seconds> with the number of seconds of server inactivity after which Fetchmail gives up on a connection attempt. 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 defined options must follow the user option (defined below).

fetchall - Orders Fetchmail to download all messages in the queue, including messages that have already been viewed. By default, Fetchmail only pulls down new messages.

fetchlimit <number> - Replace <number> with the number of messages to be retrieved before stopping.
flush - Deletes all previously viewed messages in the queue before retrieving new messages.
limit <max-number-bytes> - Replace <max-number-bytes> with the maximum size in bytes that messages are allowed to be when retrieved by Fetchmail. This option is useful with slow network links, when a large message takes too long to download.
password '<password>' - Replace <password> with the user's password.
preconnect "<command>" - Replace <command> with a command to be executed before retrieving messages for the user.
postconnect "<command>" - Replace <command> with a command to be executed after retrieving messages for the user.
ssl - Activates SSL encryption.
user "<username>" - Replace <username> with the username used by Fetchmail to retrieve messages. This option must precede all other user options.

Fetchmail Command Options

Most Fetchmail options used on the command line when executing the fetchmail command mirror the .fetchmailrc configuration options. In this way, Fetchmail may be used with or without a configuration file. These options are not used on the command line by most users because it is easier to leave them in the .fetchmailrc file.

There may be times when it is desirable to run the fetchmail command with other options for a particular purpose. It is possible to issue command options to temporarily override a .fetchmailrc setting that is causing an error, as any options specified at the command line override configuration file options.

Informational or Debugging Options

Certain options used after the fetchmail command can supply important information.

--configdump - Displays every possible option based on information from .fetchmailrc and Fetchmail defaults. No email is retrieved for any users when using this option.

-s - Executes Fetchmail in silent mode, preventing any messages, other than errors, from appearing after the fetchmail command.
-v - Executes Fetchmail in verbose mode, displaying every communication between Fetchmail and remote email servers.
-V - Displays detailed version information, lists its global options, and shows settings to be used with each user, including the email protocol and authentication method. No email is retrieved for any users when using this option.

Special Options

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

-a - Fetchmail downloads all messages from the remote email server, whether new or previously viewed. By default, Fetchmail only downloads new messages.

-k - Fetchmail leaves the 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> - Fetchmail does not download any messages over a particular size and leaves them on the remote email server.
--quit - Quits the Fetchmail daemon process.

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