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 \- retrieve mail from a mailserver using POP2, POP3, APOP, or IMAP
9 [\fI options \fR] \fI [server-host...]\fR
12 is a batch mail retrieval utility intended to be used over on-demand
13 TCP/IP links (such as SLIP or PPP connections). It fetches mail from
14 remote mail servers and forwards it to your local (client) machine's
15 delivery system, where it can then be be read by normal mail user
16 agents such as \fIelm\fR(1) or \fIMail\fR(1).
20 program can gather mail from servers supporting POP2 (as specified in RFC
21 937), POP3 (RFC 1725), IMAP2bis (as implemented by the 4.4BSD imapd
22 program), and IMAP4 (RFC1730). It can use (but does not require) the
23 RPOP and LAST facilities removed from later POP3 versions.
27 is controlled by comand-line options and a run control file,
29 the syntax of which we describe below. Command-line options override
33 To facilitate the use of
35 in scripts, pipelines, etc, it returns an appropriate exit code upon
36 termination -- see EXIT CODES below.
38 Each server name that you specify (following the options on the
39 command line) will be queried. If you don't specify any servers
40 on the command line, each server in your
45 Use Post Office Protocol version 2 (POP2). See also the
50 Use Post Office Protocol version 3 (POP3). See also the
55 POP3 only. Retrieve both old (previously retrieved) and new messages from
58 .B \-S host, --smtphost host
59 Specify an SMTP forwarding host (other than localhost). Normally
60 fetched mail is delivered by SMTP over a socket to the client machine
62 is running on (this simulates the way mail would
63 be delivered to the client by a normal Internet TCP/IP connection).
64 With this option you can specify another host to deliver to.
67 Specify a mail delivery agent to use. See OUTPUT OPTIONS below for a
70 .B \-o folder, --local folder
71 Causes retrieved messages to be appended to file named by the folder
72 argument. See OUTPUT OPTIONS below for a complete description.
75 Causes retrieved messages to be written to stdout instead of a mail folder.
76 See OUTPUT OPTIONS below for a complete description. You may not specify
81 options on the same command line.
84 POP3/IMAP only. Delete old (previously retrieved) messages from the mailserver
85 before retrieving new messages.
87 .B \-f pathname, --fetchmailrc pathname
88 Specify an alternate name for the .fetchmailrc run control file.
91 Keep retrieved messages in folder on remote mailserver. Normally, messages
92 are deleted from the folder on the mailserver after they have been retrieved
95 was compiled with the KEEP_IS_DEFAULT option). Specifying the
97 option causes retrieved messages to remain in your folder on the mailserver.
100 Delete retrieved messages from the remote mailserver. If
102 is compiled with the KEEP_IS_DEFAULT option, the
104 option forces retrieved mail to be deleted.
106 .B \-l lines, --limit lines
107 POP3 and IMAP only. Retrieve no more than the specified number of
108 lines (POP3) or characters (IMAP) of each message body (plus message
111 option is implied by the
113 option -- i.e. messages downloaded with the
115 option remain on the remote mailserver.
117 .B \-p, \--protocol proto
118 Specify the protocol to used when communicating with the remote
119 mailserver. If no protocol is specified,
121 will try each of the supported protocols in turn, terminating after
122 any successful attempt.
124 may be one of the following:
127 IMAP2bis, a compatible subset of IMAP4.
129 Post Office Protocol 2
131 Post Office Protocol 3
133 Use POP3 with MD5 authentication.
137 The option permits you to specify a TCP/IP port to connect on. You
138 will need to specify this in order to use RPOP authentication. Otherwise
139 this option will seldom be necessary as all the supported protocols have
140 well-established default port numbers.
142 .B \-r folder, --remote folder
143 Causes an alternate mail folder on the mailserver to be retrieved.
144 The syntax of the folder name is server dependent, as is the default
145 behavior when no folder is specified. Fortunately, most POP2 and IMAP
146 servers have a reasonable default behavior, so use of this option
147 should be limited to fairly specialized applications. POP3 does not
148 support a folder specification in the protocol.
151 option is used in conjunction with the POP3 protocol, the remote folder
152 specification is ignored.
155 Silent mode. Suppresses all progress/status messages that are normally
156 echoed to stderr during a POP connection. If both the
160 options are specified, the
162 option takes precedence.
164 .B \-u name, --username name
165 Specifies the user idenfication to be used when logging-in to the mailserver.
166 The appropriate user identification is both server and user-dependent.
167 The default is your login name on the machine that is running
169 See USER AUTHENTICATION below for a complete description.
172 Verbose mode. All control messages passed between
174 and the mailserver are echoed to stderr. Specifying
176 causes normal progress/status messages which would be redundant or meaningless
177 to be modified or omitted.
182 edits RFC-822 address headers (To, From, Cc, Bcc, and Reply-To) in
183 fetched mail so that any mail IDs local to the server are expanded to
184 full addresses (@ and the POP host name are appended). This enables
185 replies on the client to get addressed correctly (otherwise your
186 mailer might think they should be addressed to local users on the
187 client machine). This option disables the rewrite.
190 Displays the version information for your copy of
192 No POP connection is made.
193 Instead, for each server specified, all option information
194 that would be computed if
196 were connecting to that server is displayed.
198 .SH USER AUTHENTICATION
199 User authentication in
201 is very much like the authentication mechanism of
203 The correct user-id and password depend upon the underlying security
204 system at the mailserver.
206 If the mailserver is a Unix machine on which you have an ordinary user
207 account, your regular login name and password are used with
209 If you use the same login name on both the server and the client machines,
210 you needn't worry about specifying a user-id with the
213 the default behavior will use your login name on the client machine as the
214 user-id on the server machine. If you use a different login name
215 on the server machine, specify that login name with the
217 option. e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',
222 fetchmail -u jsmith mailgrunt
224 The default behavior of
226 is to prompt you for your mailserver password before the POP connection is
227 established. This is the safest way to use
229 and ensures that your password will not be compromised. You may also specify
230 your password in your
232 file. This is convenient when using
234 in daemon mode or with scripts.
236 On mailservers that do not provide ordinary user accounts, your user-id and
237 password are usually assigned by the server administrator when you apply for
238 a mailbox on the server. Contact your server administrator if you don't know
239 the correct user-id and password for your mailbox account.
241 POP3 versions up to the RFC1225 version supported an alternate
242 authentication mechanism called RPOP intended to remove the security
243 risk inherent in sending unencrypted account passwords across the net
244 (in RFC1460 this facility was replaced with APOP). If you specify the
245 RPOP protocol and a connection port in the privileged range (1..1024),
247 ship your password entry to the mail server as an RPOP id.
248 (Note: you'll need to be running fetchmail setuid root for RPOP to
251 has to bind to a privileged port locally in order for the mail
252 server to believe it's allowed to bind to a privileged remote port.)
254 RFC1460 introduced APOP authentication. In this variant of POP3,
255 you register an APOP password on your server host (the program
256 to do this with on the server is probably called \fIpopauth\fR(8)). You
257 put the same password in your
261 logs in, it sends a cryptographically secure hash of your password and
262 the server greeting time to the server, which can verify it by
263 checking its authorization database.
266 The default behavior of
268 is to ship mail via SMTP to port 25 on the machine it is running on
269 (localhost), just as though it were being passed in over a normal TCP/IP link.
270 This normally results in the mail being delivered locally via your
271 system's default MDA (Mail Delivery Agent, usually
273 but your system may use a different MDA).
275 You can force mail to be passed to an MDA directly with the -mda or -m
276 option. Some possible MDAs are "/usr/lib/sendmail -oem %s",
277 "/usr/formail", and "/usr/bin/deliver %s" (if the MDA string contains
278 %s, that escape will be expanded into your username on the client
279 machine). This shouldn't be necessary unless for some reason you
280 want to bypass your system's default MDA.
284 option, you can specify a mail folder to which retrieved
285 messages will be appended;
287 always writes the retrieved messages using Unix mail folder format so
288 the folder will be parsed correctly by Unix mail programs such as
293 If you prefer, for example, to have your POP
294 mail from a machine called 'mailgrunt' stored in the
296 file in your home directory, you would start
300 fetchmail \-o $HOME/mbox mailgrunt
302 Note that the folder specified with
304 is write-locked while fetchmail is writing to it,
307 can be used in a shell pipeline by using the
309 option. In this mode,
311 writes the retrieved messages to stdout, instead of a mail folder. This would
312 allow you, for instance, to pass the incoming mail through a filter that
313 discards mail marked as 'Precedence: junk'. Suppose you've written an AWK
314 script called 'dumpjunk.awk' to implement a junk mail filter. The appropriate
315 syntax to retrieve your mail from 'mailgrunt', pass it through the filter,
316 and write it to a folder called 'realmail' in your home directory would be:
319 fetchmail -c mailgrunt | awk -f dumpjunk.awk >$HOME/realmail
322 The progress/status messages written to stderr when the
324 option has not been specified, do not interfere with the message stream, which
325 is written to stdout. You may even use
329 together without corrupting the message stream. It is a good idea to use the
333 to insure that your messages will not be lost if part of the shell pipeline
334 does not function incorrectly. The safest bet would be something like:
337 fetchmail -k -c mailgrunt | myfilter >$HOME/filtered.mail
343 fetchmail -c mailgrunt > /dev/null
346 when you're sure the messages were correctly processed by 'myfilter'.
355 in daemon mode. You must specify a numeric argument which is a
356 polling interval in seconds.
360 puts itself in background and runs forever, querying each specified
361 host and then sleeping for the given polling interval.
367 will, therefore, poll the hosts described in your
369 file once every fifteen minutes.
371 Only one daemon process is permitted per user; in daemon mode,
373 makes a per-user lockfile to guarantee this. The option
375 will kill a running daemon process.
381 option allows you to redirect status messages emitted while in daemon
382 mode into a specified logfile (follow the option with the logfile name).
383 This is primarily useful for debugging configurations.
384 .SH THE RUN CONTROL FILE
385 The preferred way to set up fetchmail (and the only way if you want to
386 specify a password) is to write a .fetchmailrc file in your home directory.
387 To protect the security of your passwords, your ~/.fetchmailrc may not have
388 more than u+r,u+w permissions;
390 will complain and exit otherwise.
392 Comments begin with a '#' and extend through the end of the line.
393 Otherwise the file consists of a series of server entries.
394 Blank lines between server entries are ignored.
395 Keywords and identifiers are case sensitive.
396 When there is a conflict between the command-line arguments and the
397 arguments in this file, the command-line arguments take precedence.
405 remotefolder (or remote)
406 localfolder (or local)
421 All these correspond to the obvuious command-line arguments except
422 two: \fBpassword\fR and \fBskip\fR.
424 The \fBpassword\fR option requires a string argument, which is the password
425 to be used with the entry's server.
427 The \fBskip\fR option tells
429 not to query this host unless it is explicitly named on the command
430 line. A host entry with this flag will be skipped when
432 called with no arguments steps through all hosts in the run control file.
433 (This option allows you to experiment with test entries safely.)
435 Legal protocol identifiers are
447 server SERVERNAME protocol PROTOCOL username NAME password PASSWORD
453 server pop.provider.net protocol pop3 username jsmith password secret1
456 Or, using some abbreviations:
459 server pop.provider.net proto pop3 user jsmith password secret1
462 Multiple servers may be listed:
465 server pop.provider.net proto pop3 user jsmith pass secret1
466 server other.provider.net proto pop2 user John.Smith pass My^Hat
469 Other possibilities (note use of \ to escape newline -- this is all
470 one server definition.
473 server pop.provider.net \e
480 If you need to include whitespace in a parameter string, enclose the
481 string in double quotes. Thus:
484 server mail.provider.net \e
490 Finally, you may have an initial server description headed by the keyword
491 `defaults' instead of `server' followed by a name. Such a record
492 is interpreted as defaults for all quries to use. It may be overwritten
493 by individual server descriptions. So, you could write:
500 server pop.provider.net \e
502 server mail.provider.net \e
506 To facilitate the use of
508 in shell scripts and the like, an exit code is returned to give an indication
509 of what occured during a given POP connection. The exit code can be tested
510 by the script and appropriate action taken.
512 A simple example follows. This Bourne shell script executes
514 and, if some messages were successfully retrieved from a mailserver retrieved
515 from the command line, it starts the
517 utility to read those messages. Otherwise, it prints a brief message, and
526 echo "No mail to read."
530 The exit codes returned by
534 One or more messages were successfully retrieved.
536 There was no mail awaiting retrieval.
538 An error was encountered when attempting to open a socket for the POP
539 connection. If you don't know what a socket is, don't worry about it --
540 just treat this as an 'unrecoverable error'.
542 The user authentication step failed. This usually means that a bad
543 user-id, password, or RPOP id was specified.
545 Some sort of fatal protocol error was detected.
547 There was a syntax error in the arguments to
550 Some kind of I/O woes occurred when writing to the local folder.
552 There was an error condition reported by the server (POP3 only).
554 Exclusion error. This means
556 either found another copy of itself already running, or failed in such
557 a way that it isn't sure whether another copy is running.
561 run failed while trying to do an SMTP port open or transaction.
563 Something totally undefined occured. This is usually caused by a bug within
565 Do let me know if this happens.
569 queries more than one host, the returned status is that of the last
573 was originated (under the name `popclient') by Carl Harris at Virginia
574 Polytechnic Institute and State University (a.k.a. Virginia Tech).
575 Version 3.0 of popclient was extensively rewritten and improved by
576 Eric S. Raymond <esr@snark.thyrsus.com>. The program's name was
579 to reflect both the presence of IMAP support and the symmetry with sendmail
580 created by the new SMTP forwarding default.
585 default run control file
587 ${TMPDIR}/fetchmail-${HOST}-${USER}
588 lock file to help prevent concurrent runs.
590 For correct initialization,
592 requires either that both the USER and HOME environment variables are
593 correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
594 entry from your user ID.
596 Use of any of the supported protocols other than APOP requires that
597 the program send unencrypted passwords over the TCP/IP connection to
598 the mail server. This creates a risk that name/password pairs might
599 be snaffled with a packet sniffer or more sophisticated monitoring
602 Running more than one concurrent instance of
604 on the same mailbox may cause messages to be lost or remain unfetched.
605 (This is a design problem of the POP2, POP3 and IMAP2bis protocols.)
607 If, using POP3, you find that messages you've already read on the
608 server are being fetched, blame RFC1725. That late version pf the
609 POP3 protocol specification ill-advisedly removed the LAST command, and
610 some servers (including the one distributed with at least some
611 versions of SunOS) follow it (you can verify this by invoking
613 and watching the response to LAST early in the query). The fix is to
614 install an older POP3 server with LAST or switch to an IMAP server.
616 The RPOP support is not yet well tested.
618 Send comments, bug reports, gripes, and the like to Eric S. Raymond
621 This program used to be called `popclient' (the name was changed
622 because it supports IMAP now and may well support more remote-fetch
623 protocols such as DMSP in the future).
625 The --password option of previous (popclient) versions has been removed -- it
626 encouraged people to expose passwords in scripts. Passwords
627 must now be specified either interactively or in your
629 file. The short-form -p option now specifies the protocol to use.
631 The reason the password isn't stored encrypted is because this doesn't
632 actually add protection. Anyone who's acquired permissions to read your
633 fetchmailrc file will be able to run
635 as you anyway -- and if it's
636 your password they're after, they'd be able to use the necessary decoder from
638 itself to get it. All encryption would do in this context is give a
639 false sense of security to people who don't think very hard.
641 mail(1), binmail(1), sendmail(8), popd(8), imapd(8)
642 RFC 937, RFC 1081, RFC 1082, RFC 1225, RFC 1460, RFC 1725.