1 .\" Copyright 1993-95 by Carl Harris, Jr. Copyright 1996 by Eric S. Raymond
2 .\" All rights reserved.
3 .\" For license terms, see the file COPYING in this directory.
6 fetchmail \- deliver mail fetched from a POP or IMAP server
9 [\fI options \fR] \fI [server-host...]\fR
12 is a batch mail-retrieval/forwarding utility intended to be used over
13 on-demand TCP/IP links (such as SLIP or PPP connections). It fetches
14 mail from remote mail servers and forwards it to your local (client)
15 machine's delivery system. You can then handle the retrieved mail
16 using normal mail user agents such as \fIelm\fR(1) or \fIMail\fR(1).
17 The \fBfetchmail\fR utility can be run in a daemon mode to repeatedly
18 poll one or more systems at a specified interval.
22 program can gather mail from servers supporting any of the common
23 mail-retrieval protocols: POP2 (as specified in RFC 937), POP3 (RFC
24 1725), IMAP2bis (as implemented by the 4.4BSD imapd program), and
25 IMAP4 (as specified by RFC1730). It can use (but does not require)
26 the RPOP and LAST facilities removed from later POP3 versions.
28 As each message is retrieved \fIfetchmail\fR normally delivers it via SMTP to
29 port 25 on the machine it is running on (localhost), just as though it
30 were being passed in over a normal TCP/IP link. The mail will then be
31 delivered locally via your system's MDA (Mail Delivery Agent, usually
32 \fI/usr/lib/sendmail\fR but your system may use a different one such
33 as \fIsmail\fR, \fImmdf\fR, or \fIqmail\fR). All the delivery-control
34 mechanisms (such as \fI.forward\fR files) normally available through
35 your system MDA will therefore work.
39 is controlled by command-line options and a run control file,
40 \fI~/.fetchmailrc\fR, the syntax of which we describe below. Command-line
45 To facilitate the use of
47 In scripts, pipelines, etc., it returns an appropriate exit code upon
48 termination -- see EXIT CODES below.
50 The following options modify the behavior of \fIfetchmail\fR. It is
51 seldom necessary to specify any of these once you have a
52 working \fI.fetchmailrc\fR file set up.
55 Retrieve both old (seen) and new messages from the mailserver. The
56 default is to fetch only messages the server has not marked seen. Note
57 that POP2 retrieval, and POP3 retrieval on servers without the LAST
58 command, behaves as though --all is always on (see KNOWN PROBLEMS below).
60 .B \-S host, --smtphost host
61 Specify an host to forward mail to (other than localhost).
64 You can force mail to be passed to an MDA directly (rather than
65 forwarded to port 25) with the -mda or -m
66 option (this can be useful if you don't want to run sendmail as an
67 SMTP listener for security or other reasons).
68 Some possible MDAs are "/usr/sbin/sendmail -oem %s",
69 "/usr/lib/sendmail -oem %s",
70 "/usr/formail", and "/usr/bin/deliver %s" (if the MDA command contains
71 %s, that escape will be expanded into your username on the client
75 POP3/IMAP only. Delete old (previously retrieved) messages from the mailserver
76 before retrieving new messages.
78 .B \-f pathname, --fetchmailrc pathname
79 Specify a non-default name for the
84 Keep retrieved messages in folder on remote mailserver. Normally, messages
85 are deleted from the folder on the mailserver after they have been retrieved.
88 option causes retrieved messages to remain in your folder on the mailserver.
91 Delete retrieved messages from the remote mailserver. This
92 option forces retrieved mail to be deleted. It may be useful if
93 you have specified a default of \fBnokill\fR in your \fI.fetchmailrc\fR.
95 .B \-p, \--protocol proto
96 Specify the protocol to used when communicating with the remote
97 mailserver. If no protocol is specified,
99 will try each of the supported protocols in turn, terminating after
100 any successful attempt.
102 may be one of the following:
105 IMAP2bis, a compatible subset of IMAP4.
107 Post Office Protocol 2
109 Post Office Protocol 3
111 Use POP3 with MD5 authentication.
113 POP3 with \fI.rhosts\fR processing (not recommended).
117 The option permits you to specify a TCP/IP port to connect on. You
118 will need to specify this in order to use RPOP authentication. Otherwise
119 this option will seldom be necessary as all the supported protocols have
120 well-established default port numbers.
122 .B \-r folder, --remote folder
123 Causes a specified non-default mail folder on the mailserver to be retrieved.
124 The syntax of the folder name is server dependent, as is the default
125 behavior when no folder is specified.
128 Silent mode. Suppresses all progress/status messages that are normally
129 echoed to stderr during a fetch. If both the
133 options are specified, the
135 option takes precedence.
137 .B \-u name, --username name
138 Specifies the user idenfication to be used when logging-in to the mailserver.
139 The appropriate user identification is both server and user-dependent.
140 The default is your login name on the machine that is running
142 See USER AUTHENTICATION below for a complete description.
145 Verbose mode. All control messages passed between
147 and the mailserver are echoed to stderr. Specifying
149 causes normal progress/status messages which would be redundant or meaningless
150 to be modified or omitted.
155 edits RFC-822 address headers (To, From, Cc, Bcc, and Reply-To) in
156 fetched mail so that any mail IDs local to the server are expanded to
157 full addresses (@ and the mail server hostname are appended). This enables
158 replies on the client to get addressed correctly (otherwise your
159 mailer might think they should be addressed to local users on the
160 client machine). This option disables the rewrite.
163 Displays the version information for your copy of
165 No POP connection is made.
166 Instead, for each server specified, all option information
167 that would be computed if
169 were connecting to that server is displayed.
171 Each server name that you specify following the options on the
172 command line will be queried. If you don't specify any servers
173 on the command line, each server in your
175 file will be queried.
177 .SH USER AUTHENTICATION
178 User authentication in
180 is very much like the authentication mechanism of
182 The correct user-id and password depend upon the underlying security
183 system at the mailserver.
185 If the mailserver is a Unix machine on which you have an ordinary user
186 account, your regular login name and password are used with
188 If you use the same login name on both the server and the client machines,
189 you needn't worry about specifying a user-id with the
192 the default behavior is to use your login name on the client machine as the
193 user-id on the server machine. If you use a different login name
194 on the server machine, specify that login name with the
196 option. e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',
201 fetchmail -u jsmith mailgrunt
203 The default behavior of
205 is to prompt you for your mailserver password before the connection is
206 established. This is the safest way to use
208 and ensures that your password will not be compromised. You may also specify
209 your password in your
211 file. This is convenient when using
213 in daemon mode or with scripts.
215 On mailservers that do not provide ordinary user accounts, your user-id and
216 password are usually assigned by the server administrator when you apply for
217 a mailbox on the server. Contact your server administrator if you don't know
218 the correct user-id and password for your mailbox account.
220 POP3 versions up to the RFC1225 version supported an alternate
221 authentication mechanism called RPOP intended to address the security
222 risk inherent in sending unencrypted account passwords across the net
223 (in RFC1460 this facility was replaced with APOP). If you specify the
224 RPOP protocol and a connection port in the privileged range (1..1024),
226 will ship your password entry to the mail server as an RPOP id.
227 (Note: you'll need to be running fetchmail setuid root for RPOP to
230 has to bind to a privileged port locally in order for the mail
231 server to believe it's allowed to bind to a privileged remote port.)
233 RFC1460 introduced APOP authentication. In this variant of POP3,
234 you register an APOP password on your server host (the program
235 to do this with on the server is probably called \fIpopauth\fR(8)). You
236 put the same password in your
240 logs in, it sends a cryptographically secure hash of your password and
241 the server greeting time to the server, which can verify it by
242 checking its authorization database.
251 in daemon mode. You must specify a numeric argument which is a
252 polling interval in seconds.
256 puts itself in background and runs forever, querying each specified
257 host and then sleeping for the given polling interval.
263 will, therefore, poll the hosts described in your
265 file once every fifteen minutes.
267 Only one daemon process is permitted per user; in daemon mode,
269 makes a per-user lockfile to guarantee this. The option
271 will kill a running daemon process.
277 option allows you to redirect status messages emitted while in daemon
278 mode into a specified logfile (follow the option with the logfile name).
279 This is primarily useful for debugging configurations.
280 .SH THE RUN CONTROL FILE
281 The preferred way to set up fetchmail (and the only way if you want to
282 specify a password) is to write a .fetchmailrc file in your home directory.
283 To protect the security of your passwords, your ~/.fetchmailrc may not have
284 more than u+r,u+w permissions;
286 will complain and exit otherwise.
288 Comments begin with a '#' and extend through the end of the line.
289 Otherwise the file consists of a series of server entries.
290 Blank lines between server entries are ignored.
291 Keywords and identifiers are case sensitive.
292 When there is a conflict between the command-line arguments and the
293 arguments in this file, the command-line arguments take precedence.
301 remotename (or remote)
319 All these correspond to the obvious command-line arguments except
320 two: \fBpassword\fR and \fBskip\fR.
322 The \fBpassword\fR option requires a string argument, which is the password
323 to be used with the entry's server.
325 The \fBskip\fR option tells
327 not to query this host unless it is explicitly named on the command
328 line. A host entry with this flag will be skipped when
330 called with no arguments steps through all hosts in the run control file.
331 (This option allows you to experiment with test entries safely.)
333 Legal protocol identifiers are
345 server SERVERNAME protocol PROTOCOL username NAME password PASSWORD
351 server pop.provider.net protocol pop3 username jsmith password secret1
354 Or, using some abbreviations:
357 server pop.provider.net proto pop3 user jsmith password secret1
360 Multiple servers may be listed:
363 server pop.provider.net proto pop3 user jsmith pass secret1
364 server other.provider.net proto pop2 user John.Smith pass My^Hat
367 Other possibilities (note use of \ to escape newline -- this is now
368 optional, not required as in older versions):
371 server pop.provider.net \e
377 If you need to include whitespace in a parameter string, enclose the
378 string in double quotes. Thus:
381 server mail.provider.net
384 pass "u can't krak this"
388 Finally, you may have an initial server description headed by the keyword
389 `defaults' instead of `server' followed by a name. Such a record
390 is interpreted as defaults for all queries to use. It may be overwritten
391 by individual server descriptions. So, you could write:
397 server pop.provider.net \e
399 server mail.provider.net \e
404 To facilitate the use of
406 in shell scripts, an exit code is returned to give an indication
407 of what occurred during a given connection.
409 The exit codes returned by
413 One or more messages were successfully retrieved.
415 There was no mail awaiting retrieval.
417 An error was encountered when attempting to open a socket for the POP
418 connection. If you don't know what a socket is, don't worry about it --
419 just treat this as an 'unrecoverable error'.
421 The user authentication step failed. This usually means that a bad
422 user-id, password, or RPOP id was specified.
424 Some sort of fatal protocol error was detected.
426 There was a syntax error in the arguments to
429 The run control file had bad permissions.
431 There was an error condition reported by the server (POP3 only).
433 Exclusion error. This means
435 either found another copy of itself already running, or failed in such
436 a way that it isn't sure whether another copy is running.
440 run failed while trying to do an SMTP port open or transaction.
442 Something totally undefined occured. This is usually caused by a bug within
444 Do let me know if this happens.
448 queries more than one host, the returned status is that of the last
452 was originated (under the name `popclient') by Carl Harris at Virginia
453 Polytechnic Institute and State University (a.k.a. Virginia Tech).
455 Version 3.0 of popclient was extensively rewritten and improved by
456 Eric S. Raymond <esr@snark.thyrsus.com>. The program's name was
459 to reflect both the presence of IMAP support and the symmetry with sendmail
460 created by the new SMTP forwarding default.
465 default run control file
467 ${TMPDIR}/fetchmail-${HOST}-${USER}
468 lock file to help prevent concurrent runs.
470 For correct initialization,
472 requires either that both the USER and HOME environment variables are
473 correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
474 entry from your user ID.
475 .SH OLD-MESSAGE PROBLEMS
476 The normal mode of \fIfetchmail\fR is to try to download only `new'
477 messages, leaving untouched (and undeleted) messages you have already
478 read directly on the server (or fetched with a previous \fIfetchmail
479 --keep\fR). But you may find that messages you've already read on the
480 server are being fetched and deleted even when you don't specify
481 --all. There are several reasons this can happen.
483 One could be that you're using POP2. The POP2 protocol includes no
484 representation of `new' or `old' state in messages, so \fIfetchmail\fR
485 must treat all messages as new all the time.
487 Under POP3, blame RFC1725. That late version of the POP3 protocol
488 specification ill-advisedly removed the LAST command, and some POP
489 servers (including the one distributed with at least some versions of
490 SunOS) follow it (you can verify this by invoking \fIfetchmail -v\fR
491 and watching the response to LAST early in the query). The fix is to
492 install an older POP3 server with LAST or switch to an IMAP server.
494 Another potential POP3 problem might be servers that insert messages
496 The IMAP code uses the presence or absence of the server flag \eSeen
497 to decide whether or not a message is new. Under Unix, it counts on
498 your IMAP server to notice the BSD-style Status flags set by mail user
499 agents and set the \Seen flag from them when appropriate. All Unix
500 IMAP servers we know of do this, though it's not specified by the IMAP
501 RFCs. If you ever trip over a server that doesn't, the symptom will
502 be that messages you have already read on your host will look new to
503 the server. In this (unlikely) case, only messages you fetched with
504 \fIfetchmail --keep\fR will be both undeleted and marked old.
505 .SH OTHER KNOWN PROBLEMS
506 Use of any of the supported protocols other than APOP requires that
507 the program send unencrypted passwords over the TCP/IP connection to
508 the mail server. This creates a risk that name/password pairs might
509 be snaffled with a packet sniffer or more sophisticated monitoring
512 The RPOP support is not yet well tested.
514 Send comments, bug reports, gripes, and the like to Eric S. Raymond
517 This program used to be called `popclient' (the name was changed
518 because it supports IMAP now and may well support more remote-fetch
519 protocols such as DMSP in the future).
521 The --stdout, --local, and --limit arguments of previous
522 versions have been removed. Those features did jobs that belonged to
523 your local MDA and mail reader. The job of
525 is to forward local mail to your MDA, not to be one. Saint-Exupery
526 said, "Perfection [in design] is achieved not when there is nothing
527 more to add, but rather when there is nothing more to take away."
528 This program isn't perfect, but it's trying.
530 The --password option of previous (popclient) versions has been removed -- it
531 encouraged people to expose passwords in scripts. Passwords
532 must now be specified either interactively or in your
534 file. The short-form -p option now specifies the protocol to use.
536 The reason the password isn't stored encrypted is because this doesn't
537 actually add protection. Anyone who's acquired permissions to read your
538 fetchmailrc file will be able to run
540 as you anyway -- and if it's
541 your password they're after, they'd be able to use the necessary decoder from
543 itself to get it. All encryption would do in this context is give a
544 false sense of security to people who don't think very hard.
546 mail(1), binmail(1), sendmail(8), popd(8), imapd(8)
547 RFC 937, RFC 1081, RFC 1082, RFC1176, RFC 1225, RFC 1460, RFC 1725.