EditPageHistoryDiffInfoLikePages

Annotated edit history of popclient(1) version 1, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	fetchmail
		2	!!!fetchmail
		3	NAME
		4	SYNOPSIS
		5	YOUR FRIENDLY DEBIAN MAINTAINER WARNS
		6	DESCRIPTION
		7	GENERAL OPERATION
		8	USER AUTHENTICATION AND ENCRYPTION
		9	DAEMON MODE
		10	ADMINISTRATIVE OPTIONS
		11	RETRIEVAL FAILURE MODES
		12	SPAM FILTERING
		13	SMTP/ESMTP ERROR HANDLING
		14	THE RUN CONTROL FILE
		15	INTERACTION WITH RFC 822
		16	CONFIGURATION EXAMPLES
		17	THE USE AND ABUSE OF MULTIDROP MAILBOXES
		18	EXIT CODES
		19	FILES
		20	ENVIRONMENT
		21	SIGNALS
		22	BUGS AND KNOWN PROBLEMS
		23	AUTHOR
		24	SEE ALSO
		25	APPLICABLE STANDARDS
		26	----
		27	!!NAME
		28
		29
		30	fetchmail - fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
		31	!!SYNOPSIS
		32
		33
		34	__fetchmail__ [[''option...'']
		35	[[''mailserver...'']__
		36	fetchmailconf__
		37	!!YOUR FRIENDLY DEBIAN MAINTAINER WARNS
		38
		39
		40	fetchmailconf has a blacklist of known-troublesome servers.
		41	Use it. Also, you must remember that fetchmail ''will''
		42	discard mail if your MTA returns error codes 552 or 553, or
		43	any of the ''antispam'' error codes. The only way to
		44	avoid that is the ''keep'' fetchmail option. By default,
		45	codes 571, 550, 501 and 554 are in the ''antispam'' list.
		46	You have been warned.
		47	!!DESCRIPTION
		48
		49
		50	''fetchmail'' is a mail-retrieval and forwarding utility;
		51	it fetches mail from remote mailservers and forwards it to
		52	your local (client) machine's delivery system. You can then
		53	handle the retrieved mail using normal mail user agents such
		54	as mutt(1), elm(1) or ''Mail''(1). The
		55	''fetchmail'' utility can be run in a daemon mode to
		56	repeatedly poll one or more systems at a specified
		57	interval.
		58
		59
		60	The ''fetchmail'' program can gather mail from servers
		61	supporting any of the common mail-retrieval protocols: POP2,
		62	POP3, IMAP2bis, IMAP4, and IMAPrev1. It can also use the
		63	ESMTP ETRN extension and ODMR. (The RFCs describing all
		64	these protocols are listed at the end of this manual
		65	page.)
		66
		67
		68	While ''fetchmail'' is primarily intended to be used over
		69	on-demand TCP/IP links (such as SLIP or PPP connections), it
		70	may also be useful as a message transfer agent for sites
		71	which refuse for security reasons to permit
		72	(sender-initiated) SMTP transactions with
		73	sendmail.
		74
		75
		76	As each message is retrieved ''fetchmail'' normally
		77	delivers it via SMTP to port 25 on the machine it is running
		78	on (localhost), just as though it were being passed in over
		79	a normal TCP/IP link. The mail will then be delivered
		80	locally via your system's MDA (Mail Delivery Agent, usually
		81	sendmail(8) but your system may use a different one
		82	such as ''smail'', ''mmdf'', ''exim'', or
		83	''qmail''). All the delivery-control mechanisms (such as
		84	''.forward'' files) normally available through your
		85	system MDA and local delivery agents will therefore
		86	work.
		87
		88
		89	If no port 25 listener is available, you must configure
		90	Debian fetchmail explicitly to use an MDA.
		91
		92
		93	If the program ''fetchmailconf'' is available, it will
		94	assist you in setting up and editing a fetchmailrc
		95	configuration. It runs under X and requires that the
		96	language Python and the Tk toolkit be present on your
		97	system. If you are first setting up fetchmail for
		98	single-user mode, it is recommended that you use Novice
		99	mode. Expert mode provides complete control of fetchmail
		100	configuration, including the multidrop features. In either
		101	case, the `Autoprobe' button will tell you the most capable
		102	protocol a given mailserver supports, and warn you of
		103	potential problems with that server.
		104	!!GENERAL OPERATION
		105
		106
		107	The behavior of ''fetchmail'' is controlled by
		108	command-line options and a run control file,
		109	''~/.fetchmailrc'', the syntax of which we describe in a
		110	later section (this file is what the ''fetchmailconf''
		111	program edits). Command-line options override
		112	''~/.fetchmailrc'' declarations.
		113
		114
		115	Each server name that you specify following the options on
		116	the command line will be queried. If you don't specify any
		117	servers on the command line, each `poll' entry in your
		118	''~/.fetchmailrc'' file will be queried.
		119
		120
		121	To facilitate the use of ''fetchmail'' in scripts and
		122	pipelines, it returns an appropriate exit code upon
		123	termination -- see EXIT CODES below.
		124
		125
		126	The following options modify the behavior of
		127	''fetchmail''. It is seldom necessary to specify any of
		128	these once you have a working ''.fetchmailrc'' file set
		129	up.
		130
		131
		132	Almost all options have a corresponding keyword which can be
		133	used to declare them in a ''fetchmailrc''
		134	file.
		135
		136
		137	Some special options are not covered here, but are
		138	documented instead in sections on AUTHENTICATION and DAEMON
		139	MODE which follow.
		140
		141
		142	__General Options__
		143
		144
		145	__-V, --version__
		146
		147
		148	Displays the version information for your copy of
		149	''fetchmail.'' No mail fetch is performed. Instead, for
		150	each server specified, all the option information that would
		151	be computed if ''fetchmail'' were connecting to that
		152	server is displayed. Any non-printables in passwords or
		153	other string names are shown as backslashed C-like escape
		154	sequences. This option is useful for verifying that your
		155	options are set the way you want them.
		156
		157
		158	__-c, --check__
		159
		160
		161	Return a status code to indicate whether there is mail
		162	waiting, without actually fetching or deleting mail (see
		163	EXIT CODES below). This option turns off daemon mode (in
		164	which it would be useless). It doesn't play well with
		165	queries to multiple sites, and doesn't work with ETRN or
		166	ODMR. It will return a false positive if you leave read but
		167	undeleted mail in your server mailbox and your fetch
		168	protocol can't tell kept messages from new ones. This means
		169	it will work with IMAP, not work with POP2, and may
		170	occasionally flake out under POP3.
		171
		172
		173	__-s, --silent__
		174
		175
		176	Silent mode. Suppresses all progress/status messages that
		177	are normally echoed to standard error during a fetch (but
		178	does not suppress actual error messages). The --verbose
		179	option overrides this.
		180
		181
		182	__-v, --verbose__
		183
		184
		185	Verbose mode. All control messages passed between
		186	''fetchmail'' and the mailserver are echoed to stdout.
		187	Overrides --silent. Doubling this option (-v -v) causes
		188	extra diagnostic information to be printed.
		189
		190
		191	__Disposal Options__
		192
		193
		194	__-a, --all__
		195
		196
		197	(Keyword: fetchall) Retrieve both old (seen) and new
		198	messages from the mailserver. The default is to fetch only
		199	messages the server has not marked seen. Under POP3, this
		200	option also forces the use of RETR rather than TOP. Note
		201	that POP2 retrieval behaves as though --all is always on
		202	(see RETRIEVAL FAILURE MODES below) and this option does not
		203	work with ETRN or ODMR.
		204
		205
		206	__-k, --keep__
		207
		208
		209	(Keyword: keep) Keep retrieved messages on the remote
		210	mailserver. Normally, messages are deleted from the folder
		211	on the mailserver after they have been retrieved. Specifying
		212	the __keep__ option causes retrieved messages to remain
		213	in your folder on the mailserver. This option does not work
		214	with ETRN or ODMR.
		215
		216
		217	__-K, --nokeep__
		218
		219
		220	(Keyword: nokeep) Delete retrieved messages from the remote
		221	mailserver. This option forces retrieved mail to be deleted.
		222	It may be useful if you have specified a default of
		223	__keep__ in your ''.fetchmailrc''. This option is
		224	forced on with ETRN and ODMR.
		225
		226
		227	__-F, --flush__
		228
		229
		230	POP3/IMAP only. Delete old (previously retrieved) messages
		231	from the mailserver before retrieving new messages. This
		232	option does not work with ETRN or ODMR. Warning: if your
		233	local MTA hangs and fetchmail is aborted, the next time you
		234	run fetchmail, it will delete mail that was never delivered
		235	to you. What you probably want is the default setting: if
		236	you don't specify `-k', then fetchmail will automatically
		237	delete messages after successful delivery.
		238
		239
		240	__Protocol and Query Options__
		241
		242
		243	__-p, --protocol __
		244
		245
		246	(Keyword: proto[[col]) Specify the protocol to use when
		247	communicating with the remote mailserver. If no protocol is
		248	specified, the default is AUTO. ''proto'' may be one of
		249	the following:
		250
		251
		252	AUTO
		253
		254
		255	Tries IMAP, POP3, and POP2 (skipping any of these for which
		256	support has not been compiled in).
		257
		258
		259	POP2
		260
		261
		262	Post Office Protocol 2
		263
		264
		265	POP3
		266
		267
		268	Post Office Protocol 3
		269
		270
		271	APOP
		272
		273
		274	Use POP3 with old-fashioned MD5-challenge
		275	authentication.
		276
		277
		278	RPOP
		279
		280
		281	Use POP3 with RPOP authentication.
		282
		283
		284	KPOP
		285
		286
		287	Use POP3 with Kerberos V4 authentication on port
		288	1109.
		289
		290
		291	SDPS
		292
		293
		294	Use POP3 with Demon Internet's SDPS extensions.
		295
		296
		297	IMAP
		298
		299
		300	IMAP2bis, IMAP4, or IMAP4rev1 (''fetchmail'' autodetects
		301	their capabilities).
		302
		303
		304	ETRN
		305
		306
		307	Use the ESMTP ETRN option.
		308
		309
		310	ODMR
		311
		312
		313	Use the the On-Demand Mail Relay ESMTP profile.
		314
		315
		316	All these alternatives work in basically the same way
		317	(communicating with standard server daemons to fetch mail
		318	already delivered to a mailbox on the server) except ETRN
		319	and ODMR. The ETRN mode allows you to ask a compliant ESMTP
		320	server (such as BSD sendmail at release 8.8.0 or higher) to
		321	immediately open a sender-SMTP connection to your client
		322	machine and begin forwarding any items addressed to your
		323	client machine in the server's queue of undelivered mail.
		324	The ODMR mode requires an ODMR-capable server and works
		325	similarly to ETRN, except that it does not require the
		326	client machine to have a static DNS.
		327
		328
		329	__-U, --uidl__
		330
		331
		332	(Keyword: uidl) Force UIDL use (effective only with POP3).
		333	Force client-side tracking of `newness' of messages (UIDL
		334	stands for ``unique ID listing'' and is described in
		335	RFC1725). Use with `keep' to use a mailbox as a baby news
		336	drop for a group of users.
		337
		338
		339	__-P, --port __
		340
		341
		342	(Keyword: port) The port option permits you to specify a
		343	TCP/IP port to connect on. This option will seldom be
		344	necessary as all the supported protocols have
		345	well-established default port numbers.
		346
		347
		348	__--principal __
		349
		350
		351	(Keyword: principal) The principal option permits you to
		352	specify a service principal for mutual authentication. This
		353	is applicable to POP3 or IMAP with Kerberos
		354	authentication.
		355
		356
		357	__-t, --timeout __
		358
		359
		360	(Keyword: timeout) The timeout option allows you to set a
		361	server-nonresponse timeout in seconds. If a mailserver does
		362	not send a greeting message or respond to commands for the
		363	given number of seconds, ''fetchmail'' will hang up on
		364	it. Without such a timeout ''fetchmail'' might hang up
		365	indefinitely trying to fetch mail from a down host. This
		366	would be particularly annoying for a ''fetchmail''
		367	running in background. There is a default timeout which
		368	fetchmail -V will report. If a given connection receives too
		369	many timeouts in succession, fetchmail will consider it
		370	wedged and stop retrying, the calkling user will be notified
		371	by email if this happens.
		372
		373
		374	__--plugin __
		375
		376
		377	(Keyword: plugin) The plugin option allows you to use an
		378	external program to establish the TCP connection. This is
		379	useful if you want to use socks, SSL, ssh, or need some
		380	special firewalling setup. The program will be looked up in
		381	$PATH and can optionally be passed the hostname and port as
		382	arguments using
		383
		384
		385	__--plugout __
		386
		387
		388	(Keyword: plugout) Identical to the plugin option above, but
		389	this one is used for the SMTP connections (which will
		390	probably not need it, so it has been separated from
		391	plugin).
		392
		393
		394	__-r __
		395
		396
		397	(Keyword: folder[[s]) Causes a specified non-default mail
		398	folder on the mailserver (or comma-separated list of
		399	folders) to be retrieved. The syntax of the folder name is
		400	server-dependent. This option is not available under POP3,
		401	ETRN, or ODMR.
		402
		403
		404	__--tracepolls__
		405
		406
		407	(Keyword: tracepolls) Tell fetchail to poll trace
		408	information in the form `polling %s account %s' to the
		409	Received line it generates, where the %s parts are replaced
		410	by the user's remote name and the poll label (the Received
		411	header also normally includes the server's truename). This
		412	can be used to facilate mail filtering based on the account
		413	it is being received from.
		414
		415
		416	__--ssl__
		417
		418
		419	(Keyword: ssl) Causes the connection to the mail server to
		420	be encrypted via SSL. Connect to the server using the
		421	specified base protocol over a connection secured by SSL.
		422	SSL support must be present at the server. If no port is
		423	specified, the connection is attempted to the well known
		424	port of the SSL version of the base protocol. This is
		425	generally a different port than the port used by the base
		426	protocol. For IMAP, this is port 143 for the clear protocol
		427	and port 993 for the SSL secured protocol.
		428
		429
		430	__--sslcert __
		431
		432
		433	(Keyword: sslcert) Specifies the file name of the client
		434	side public SSL certificate. Some SSL encrypted servers may
		435	require client side keys and certificates for
		436	authentication. In most cases, this is optional. This
		437	specifies the location of the public key certificate to be
		438	presented to the server at the time the SSL session is
		439	established. It is not required (but may be provided) if the
		440	server does not require it. Some servers may require it,
		441	some servers may request it but not require it, and some
		442	servers may not request it at all. It may be the same file
		443	as the private key (combined key and certificate file) but
		444	this is not recommended.
		445
		446
		447	__--sslkey __
		448
		449
		450	(Keyword: sslkey) Specifies the file name of the client side
		451	private SSL key. Some SSL encrypted servers may require
		452	client side keys and certificates for authentication. In
		453	most cases, this is optional. This specifies the location of
		454	the private key used to sign transactions with the server at
		455	the time the SSL session is established. It is not required
		456	(but may be provided) if the server does not require it.
		457	Some servers may require it, some servers may request it but
		458	not require it, and some servers may not request it at all.
		459	It may be the same file as the public key (combined key and
		460	certificate file) but this is not recommended. If a password
		461	is required to unlock the key, it will be prompted for at
		462	the time just prior to establishing the session to the
		463	server. This can cause some complications in daemon
		464	mode.
		465
		466
		467	__--sslproto __
		468
		469
		470	(Keyword: sslproto) Forces an ssl protocol. Possible values
		471	are `__ssl2__', `__ssl3__' and `__tls1__'. Try this
		472	if the default handshake does not work for your
		473	server.
		474
		475
		476	__--sslcertck__
		477
		478
		479	(Keyword: sslcertck) Causes fetchmail to strictly check the
		480	server certificate against a set of local trusted
		481	certificates (see the __sslcertpath__ option). If the
		482	server certificate is not signed by one of the trusted ones
		483	(directly or indirectly), the SSL connection will fail. This
		484	checking should prevent man-in-the-middle attacks against
		485	the SSL connection. Note that CRLs are seemingly not
		486	currently supported by OpenSSL in certificate verification!
		487	Your system clock should be reasonably accurate when using
		488	this option!
		489
		490
		491	__--sslcertpath __
		492
		493
		494	(Keyword: sslcertpath) Sets the directory fetchmail uses to
		495	look up local certificates. The default is your OpenSSL
		496	default one. The directory must be hashed as OpenSSL expects
		497	it - every time you add or modify a certificate in the
		498	directory, you need to use the __c_rehash__ tool (which
		499	comes with OpenSSL in the tools/ subdirectory).
		500
		501
		502	__--sslfingerprint__
		503
		504
		505	(Keyword: sslfingerprint) Specify the fingerprint of the
		506	server key (an MD5 hash of the key) in hexadecimal notation
		507	with colons separating groups of two digits. The letter hex
		508	digits must be in upper case. This is the default format
		509	OpenSSL uses, and the one fetchmail uses to report the
		510	fingerprint when an SSL connection is established. When this
		511	is specified, fetchmail will compare the server key
		512	fingerprint with the given one, and the connection will fail
		513	if they do not match. This can be used to prevent
		514	man-in-the-middle attacks.
		515
		516
		517	__Delivery Control Options__
		518
		519
		520	__-S
		521	__
		522
		523
		524	(Keyword: smtp[[host]) Specify a hunt list of hosts to
		525	forward mail to (one or more hostnames, comma-separated).
		526	Hosts are tried in list order; the first one that is up
		527	becomes the forwarding target for the current run. Normally,
		528	`localhost' is added to the end of the list as an invisible
		529	default. However, when using Kerberos authentication, the
		530	FQDN of the machine running fetchmail is added to the end of
		531	the list as an invisible default. Each hostname may have a
		532	port number following the host name. The port number is
		533	separated from the host name by a slash; the default port is
		534	25 (or ``smtp'' under IPv6). If you specify an absolute
		535	pathname (beginning with a /), it will be interpreted as the
		536	name of a UNIX socket accepting LMTP connections (such as is
		537	supported by the Cyrus IMAP daemon) Example:
		538
		539
		540	--smtphost
		541	server1,server2/2525,server3,/var/imap/socket/lmtp
		542
		543
		544	This option can be used with ODMR, and will make fetchmail a
		545	relay between the ODMR server and SMTP or LMTP
		546	receiver.
		547
		548
		549	__--fetchdomains __
		550
		551
		552	(Keyword: fetchdomains) In ETRN or ODMR mode, this option
		553	specifies the list of domains the server should ship mail
		554	for once the connection is turned around. The default is the
		555	FQDN of the machine running fetchmail.
		556
		557
		558	__-D
		559	__
		560
		561
		562	(Keyword: smtpaddress) Specify the domain to be appended to
		563	addresses in RCPT TO lines shipped to SMTP. The name of the
		564	SMTP server (as specified by --smtphost, or defaulted to
		565
		566
		567	__--smtpname __
		568
		569
		570	(Keyword: smtpname) Specify the domain and user to be put in
		571	RCPT TO lines shipped to SMTP. The default user is the
		572	current local user.
		573
		574
		575	__-Z
		576	__
		577
		578
		579	(Keyword: antispam) Specifies the list of numeric SMTP
		580	errors that are to be interpreted as a spam-block response
		581	from the listener. A value of -1 disables this option. For
		582	the command-line option, the list values should be
		583	comma-separated.
		584
		585
		586	__-m
		587	__
		588
		589
		590	(Keyword: mda) You can force mail to be passed to an MDA
		591	directly (rather than forwarded to port 25) with the -mda or
		592	-m option. To avoid losing mail, use this option only with
		593	MDAs like procmail or sendmail that return a nonzero status
		594	on disk-full and other resource-exhaustion errors; the
		595	nonzero status tells fetchmail that delivery failed and
		596	prevents the message from being deleted off the server. If
		597	''fetchmail'' is running as root, it sets its userid to
		598	that of the target user while delivering mail through an
		599	MDA. Some possible MDAs are
		600	''not'' use an MDA invocation like
		601	''
		602
		603
		604	__--lmtp__
		605
		606
		607	(Keyword: lmtp) Cause delivery via LMTP (Local Mail Transfer
		608	Protocol). A service port ''must'' be explicitly
		609	specified (with a slash suffix) on each host in the smtphost
		610	hunt list if this option is selected; the default port 25
		611	will (in accordance with RFC 2033) not be
		612	accepted.
		613
		614
		615	__--bsmtp __
		616
		617
		618	(keyword: bsmtp) Append fetched mail to a BSMTP file. This
		619	simply contains the SMTP commands that would normally be
		620	generated by fetchmail when passing mail to an SMTP listener
		621	daemon. An argument of `-' causes the mail to be written to
		622	standard output. Note that fetchmail's reconstruction of
		623	MAIL FROM and RCPT TO lines is not guaranteed correct; the
		624	caveats discussed under THE USE AND ABUSE OF MULTIDROP
		625	MAILBOXES below apply.
		626
		627
		628	__Resource Limit Control Options__
		629
		630
		631	__-l
		632	__
		633
		634
		635	(Keyword: limit) Takes a maximum octet size argument.
		636	Messages larger than this size will not be fetched and will
		637	be left on the server (in foreground sessions, the progress
		638	messages will note that they are
		639
		640
		641	__-w
		642	__
		643
		644
		645	(Keyword: warnings) Takes an interval in seconds. When you
		646	call ''fetchmail'' with a `limit' option in daemon mode,
		647	this controls the interval at which warnings about oversized
		648	messages are mailed to the calling user (or the user
		649	specified by the `postmaster' option). One such notification
		650	is always mailed at the end of the the first poll that the
		651	oversized message is detected. Thereafter, renotification is
		652	suppressed until after the warning interval elapses (it will
		653	take place at the end of the first following
		654	poll).
		655
		656
		657	__-b
		658	__
		659
		660
		661	(Keyword: batchlimit) Specify the maximum number of messages
		662	that will be shipped to an SMTP listener before the
		663	connection is deliberately torn down and rebuilt (defaults
		664	to 0, meaning no limit). An explicit --batchlimit of 0
		665	overrides any limits set in your run control file. While
		666	sendmail(8) normally initiates delivery of a message
		667	immediately after receiving the message terminator, some
		668	SMTP listeners are not so prompt. MTAs like qmail(8)
		669	and smail(8) may wait till the delivery socket is
		670	shut down to deliver. This may produce annoying delays when
		671	''fetchmail'' is processing very large batches. Setting
		672	the batch limit to some nonzero size will prevent these
		673	delays. This option does not work with ETRN or
		674	ODMR.
		675
		676
		677	__-B
		678	__
		679
		680
		681	(Keyword: fetchlimit) Limit the number of messages accepted
		682	from a given server in a single poll. By default there is no
		683	limit. An explicit --fetchlimit of 0 overrides any limits
		684	set in your run control file. This option does not work with
		685	ETRN or ODMR.
		686
		687
		688	__-e
		689	__
		690
		691
		692	(keyword: expunge) Arrange for deletions to be made final
		693	after a given number of messages. Under POP2 or POP3,
		694	fetchmail cannot make deletions final without sending QUIT
		695	and ending the session -- with this option on, fetchmail
		696	will break a long mail retrieval session into multiple
		697	subsessions, sending QUIT after each sub-session. This is a
		698	good defense against line drops on POP3 servers that do not
		699	do the equivalent of a QUIT on hangup. Under IMAP,
		700	''fetchmail'' normally issues an EXPUNGE command after
		701	each deletion in order to force the deletion to be done
		702	immediately. This is safest when your connection to the
		703	server is flaky and expensive, as it avoids resending
		704	duplicate mail after a line hit. However, on large mailboxes
		705	the overhead of re-indexing after every message can slam the
		706	server pretty hard, so if your connection is reliable it is
		707	good to do expunges less frequently. Also note that some
		708	servers enforce a delay of a few seconds after each quit, so
		709	fetchmail may not be able to get back in immediately after
		710	an expunge -- you may see
		711	''fetchmail'' to only issue expunges on every Nth
		712	delete. An argument of zero suppresses expunges entirely (so
		713	no expunges at all will be done until the end of run). This
		714	option does not work with ETRN or ODMR.
		715
		716
		717	__Authentication Options__
		718
		719
		720	__-u __
		721
		722
		723	(Keyword: user[[name]) Specifies the user identification to
		724	be used when logging in to the mailserver. The appropriate
		725	user identification is both server and user-dependent. The
		726	default is your login name on the client machine that is
		727	running ''fetchmail.'' See USER AUTHENTICATION below for
		728	a complete description.
		729
		730
		731	__-I
		732	__
		733
		734
		735	(Keyword: interface) Require that a specific interface
		736	device be up and have a specific local or remote IP address
		737	(or range) before polling. Frequently ''fetchmail'' is
		738	used over a transient point-to-point TCP/IP link established
		739	directly to a mailserver via SLIP or PPP. That is a
		740	relatively secure channel. But when other TCP/IP routes to
		741	the mailserver exist (e.g. when the link is connected to an
		742	alternate ISP), your username and password may be vulnerable
		743	to snooping (especially when daemon mode automatically polls
		744	for mail, shipping a clear password over the net at
		745	predictable intervals). The --interface option may be used
		746	to prevent this. When the specified link is not up or is not
		747	connected to a matching IP address, polling will be skipped.
		748	The format is:
		749
		750
		751	interface/iii.iii.iii.iii/mmm.mmm.mmm.mmm
		752
		753
		754	The field before the first slash is the interface name (i.e.
		755	sl0, ppp0 etc.). The field before the second slash is the
		756	acceptable IP address. The field after the second slash is a
		757	mask which specifies a range of IP addresses to accept. If
		758	no mask is present 255.255.255.255 is assumed (i.e. an exact
		759	match). This option is currently only supported under Linux
		760	and FreeBSD. Please see the __monitor__ section for below
		761	for FreeBSD specific information.
		762
		763
		764	__-M
		765	__
		766
		767
		768	(Keyword: monitor) Daemon mode can cause transient links
		769	which are automatically taken down after a period of
		770	inactivity (e.g. PPP links) to remain up indefinitely. This
		771	option identifies a system TCP/IP interface to be monitored
		772	for activity. After each poll interval, if the link is up
		773	but no other activity has occurred on the link, then the
		774	poll will be skipped. However, when fetchmail is woken up by
		775	a signal, the monitor check is skipped and the poll goes
		776	through unconditionally. This option is currently only
		777	supported under Linux and FreeBSD. For the __monitor__
		778	and __interface__ options to work for non root users
		779	under FreeBSD, the fetchmail binary must be installed SGID
		780	kmem. This would be a security hole, but fetchmail runs with
		781	the effective GID set to that of the kmem group ''only''
		782	when interface data is being collected.
		783
		784
		785	__--auth __
		786
		787
		788	(Keyword: auth[[enticate]) This option permits you to specify
		789	an authentication type (see USER AUTHENTICATION below for
		790	details). The possible values are __any__,
		791	`__password__', `__kerberos_v5__' and
		792	`__kerberos__' (or, for excruciating exactness,
		793	`__kerberos_v4__'), gssapi, ''cram-md5'', ''otp'',
		794	''ntlm'', and __ssh__. When __any__ (the default)
		795	is specified, fetchmail tries first methods that don't
		796	require a password (GSSAPI, KERBEROS_IV); then it looks for
		797	methods that mask your password (CRAM-MD5, X-OTP, NTLM); and
		798	only if the server doesn't support any of those will it ship
		799	your password en clair. Other values may be used to force
		800	various authentication methods (__ssh__ suppresses
		801	authentication). Any value other than ''password'',
		802	''cram-md5'', ''ntlm'' or ''otp'' suppresses
		803	fetchmail's normal inquiry for a password. Specify
		804	''ssh'' when you are using an end-to-end secure
		805	connection such as an ssh tunnel; specify gssapi or
		806	__kerberos_v4__ if you are using a protocol variant that
		807	employs GSSAPI or K4. Choosing KPOP protocol automatically
		808	selects Kerberos authentication. This option does not work
		809	with ETRN.
		810
		811
		812	__Miscellaneous Options__
		813
		814
		815	__-f
		816	__
		817
		818
		819	Specify a non-default name for the ''~/.fetchmailrc'' run
		820	control file. The pathname argument must be either
		821	''
		822
		823
		824	__-i
		825	__
		826
		827
		828	(Keyword: idfile) Specify an alternate name for the
		829	.fetchids file used to save POP3 UIDs.
		830
		831
		832	__-n, --norewrite__
		833
		834
		835	(Keyword: no rewrite) Normally, ''fetchmail'' edits
		836	RFC-822 address headers (To, From, Cc, Bcc, and Reply-To) in
		837	fetched mail so that any mail IDs local to the server are
		838	expanded to full addresses (@ and the mailserver hostname
		839	are appended). This enables replies on the client to get
		840	addressed correctly (otherwise your mailer might think they
		841	should be addressed to local users on the client machine!).
		842	This option disables the rewrite. (This option is provided
		843	to pacify people who are paranoid about having an MTA edit
		844	mail headers and want to know they can prevent it, but it is
		845	generally not a good idea to actually turn off rewrite.)
		846	When using ETRN or ODMR, the rewrite option is
		847	ineffective.
		848
		849
		850	__-E __
		851
		852
		853	(Keyword: envelope) This option changes the header
		854	''fetchmail'' assumes will carry a copy of the mail's
		855	envelope address. Normally this is `X-Envelope-To' but as
		856	this header is not standard, practice varies. See the
		857	discussion of multidrop address handling below. As a special
		858	case, `envelope
		859	''.fetchmailrc'' file.
		860
		861
		862	__-Q
		863	__
		864
		865
		866	(Keyword: qvirtual) The string prefix assigned to this
		867	option will be removed from the user name found in the
		868	header specified with the ''envelope'' option
		869	(''before'' doing multidrop name mapping or localdomain
		870	checking, if either is applicable). This option is useful if
		871	you are using ''fetchmail'' to collect the mail for an
		872	entire domain and your ISP (or your mail redirection
		873	provider) is using qmail. One of the basic features of qmail
		874	is the
		875
		876
		877	`Delivered-To:'
		878
		879
		880	message header. Whenever qmail delivers a message to a local
		881	mailbox it puts the username and hostname of the envelope
		882	recipient on this line. The major reason for this is to
		883	prevent mail loops. To set up qmail to batch mail for a
		884	disconnected site the ISP-mailhost will have normally put
		885	that site in its `Virtualhosts' control file so it will add
		886	a prefix to all mail addresses for this site. This results
		887	in mail sent to 'username@userhost.userdom.dom.com' having a
		888	`Delivered-To:' line of the form:
		889
		890
		891	Delivered-To:
		892	mbox-userstr-username@userhost.userdom.dom.com
		893
		894
		895	The ISP can make the 'mbox-userstr-' prefix anything they
		896	choose but a string matching the user host name is likely.
		897	By using the option `envelope Delivered-To:' you can make
		898	fetchmail reliably identify the original envelope recipient,
		899	but you have to strip the `mbox-userstr-' prefix to deliver
		900	to the correct user. This is what this option is
		901	for.
		902
		903
		904	__--configdump__
		905
		906
		907	Parse the ''~/.fetchmailrc'' file, interpret any
		908	command-line options specified, and dump a configuration
		909	report to standard output. The configuration report is a
		910	data structure assignment in the language Python. This
		911	option is meant to be used with an interactive
		912	''~/.fetchmailrc'' editor like ''fetchmailconf'',
		913	written in Python.
		914	!!USER AUTHENTICATION AND ENCRYPTION
		915
		916
		917	All modes except ETRN require authentication of the client
		918	to the server. Normal user authentication in
		919	''fetchmail'' is very much like the authentication
		920	mechanism of ftp(1). The correct user-id and password
		921	depend upon the underlying security system at the
		922	mailserver.
		923
		924
		925	If the mailserver is a Unix machine on which you have an
		926	ordinary user account, your regular login name and password
		927	are used with ''fetchmail.'' If you use the same login
		928	name on both the server and the client machines, you needn't
		929	worry about specifying a user-id with the __-u__ option
		930	-- the default behavior is to use your login name on the
		931	client machine as the user-id on the server machine. If you
		932	use a different login name on the server machine, specify
		933	that login name with the __-u__ option. e.g. if your
		934	login name is 'jsmith' on a machine named 'mailgrunt', you
		935	would start ''fetchmail'' as follows:
		936
		937
		938	fetchmail -u jsmith mailgrunt
		939
		940
		941	The default behavior of ''fetchmail'' is to prompt you
		942	for your mailserver password before the connection is
		943	established. This is the safest way to use ''fetchmail''
		944	and ensures that your password will not be compromised. You
		945	may also specify your password in your ''~/.fetchmailrc''
		946	file. This is convenient when using ''fetchmail'' in
		947	daemon mode or with scripts.
		948
		949
		950	If you do not specify a password, and ''fetchmail''
		951	cannot extract one from your ''~/.fetchmailrc'' file, it
		952	will look for a ''~/.netrc'' file in your home directory
		953	before requesting one interactively; if an entry matching
		954	the mailserver is found in that file, the password will be
		955	used. Fetchmail first looks for a match on poll name; if it
		956	finds none, it checks for a match on via name. See the
		957	ftp(1) man page for details of the syntax of the
		958	''~/.netrc'' file. (This feature may allow you to avoid
		959	duplicating password information in more than one
		960	file.)
		961
		962
		963	On mailservers that do not provide ordinary user accounts,
		964	your user-id and password are usually assigned by the server
		965	administrator when you apply for a mailbox on the server.
		966	Contact your server administrator if you don't know the
		967	correct user-id and password for your mailbox
		968	account.
		969
		970
		971	Early versions of POP3 (RFC1081, RFC1225) supported a crude
		972	form of independent authentication using the ''rhosts''
		973	file on the mailserver side. Under this RPOP variant, a
		974	fixed per-user ID equivalent to a password was sent in clear
		975	over a link to a reserved port, with the command RPOP rather
		976	than PASS to alert the server that it should do special
		977	checking. RPOP is supported by ''fetchmail'' (you can
		978	specify `protocol RPOP' to have the program send `RPOP'
		979	rather than `PASS') but its use is strongly discouraged.
		980	This facility was vulnerable to spoofing and was withdrawn
		981	in RFC1460.
		982
		983
		984	RFC1460 introduced APOP authentication. In this variant of
		985	POP3, you register an APOP password on your server host (the
		986	program to do this with on the server is probably called
		987	popauth(8)). You put the same password in your
		988	''~/.fetchmailrc'' file. Each time ''fetchmail'' logs
		989	in, it sends a cryptographically secure hash of your
		990	password and the server greeting time to the server, which
		991	can verify it by checking its authorization
		992	database.
		993
		994
		995	If your ''fetchmail'' was built with Kerberos support and
		996	you specify Kerberos authentication (either with --auth or
		997	the ''.fetchmailrc'' option __authenticate
		998	kerberos_v4__) it will try to get a Kerberos ticket from
		999	the mailserver at the start of each query. Note: if either
		1000	the pollnane or via name is `hesiod', fetchmail will try to
		1001	use Hesiod to look up the mailserver.
		1002
		1003
		1004	If you use POP3 or IMAP with GSSAPI authentication,
		1005	''fetchmail'' will expect the server to have RFC1731- or
		1006	RFC1734-conformant GSSAPI capability, and will use it.
		1007	Currently this has only been tested over Kerberos V, so
		1008	you're expected to already have a ticket-granting ticket.
		1009	You may pass a username different from your principal name
		1010	using the standard __--user__ command or by the
		1011	''.fetchmailrc'' option __user__.
		1012
		1013
		1014	If your IMAP daemon returns the PREAUTH response in its
		1015	greeting line, fetchmail will notice this and skip the
		1016	normal authentication step. This can be useful, e.g. if you
		1017	start imapd explicitly using ssh. In this case you can
		1018	declare the authentication value `ssh' on that site entry to
		1019	stop ''.fetchmail'' from asking you for a password when
		1020	it starts up.
		1021
		1022
		1023	If you are using POP3, and the server issues a
		1024	one-time-password challenge conforming to RFC1938,
		1025	''fetchmail'' will use your password as a pass phrase to
		1026	generate the required response. This avoids sending secrets
		1027	over the net unencrypted.
		1028
		1029
		1030	Compuserve's RPA authentication (similar to APOP) is
		1031	supported. If you compile in the support, ''fetchmail''
		1032	will try to perform an RPA pass-phrase authentication
		1033	instead of sending over the password en clair if it detects
		1034	''
		1035
		1036
		1037	If you are using IMAP, Microsoft's NTLM authentication (used
		1038	by Microsoft Exchange) is supported. If you compile in the
		1039	support, ''fetchmail'' will try to perform an NTLM
		1040	authentication (instead of sending over the password en
		1041	clair) whenever the server returns AUTH=NTLM in its
		1042	capability response. Specify a user option value that looks
		1043	like `user@domain': the part to the left of the @ will be
		1044	passed as the username and the part to the right as the NTLM
		1045	domain.
		1046
		1047
		1048	If you are using IPsec, the -T (--netsec) option can be used
		1049	to pass an IP security request to be used when outgoing IP
		1050	connections are initialized. You can also do this using the
		1051	`netsec' server option in the .fetchmailrc file. In either
		1052	case, the option value is a string in the format accepted by
		1053	the net_security_strtorequest() function of the inet6_apps
		1054	library.
		1055
		1056
		1057	You can access SSL encrypted services by specifying the
		1058	--ssl option. You can also do this using the
		1059
		1060
		1061	When connecting to an SSL encrypted server, the server
		1062	presents a certificate to the client for validation. The
		1063	certificate is checked to verify that the common name in the
		1064	certificate matches the name of the server being contacted
		1065	and that the effective and expiration dates in the
		1066	certificate indicate that it is currently valid. If any of
		1067	these checks fail, a warning message is printed, but the
		1068	connection continues. The server certificate does not need
		1069	to be signed by any specific Certifying Authority and may be
		1070	a
		1071
		1072
		1073	Some SSL encrypted servers may request a client side
		1074	certificate. A client side public SSL certificate and
		1075	private SSL key may be specified. If requested by the
		1076	server, the client certificate is sent to the server for
		1077	validation. Some servers may require a valid client
		1078	certificate and may refuse connections if a certificate is
		1079	not provided or if the certificate is not valid. Some
		1080	servers may require client side certificates be signed by a
		1081	recognized Certifying Authority. The format for the key
		1082	files and the certificate files is that required by the
		1083	underlying SSL libraries (OpenSSL in the general
		1084	case).
		1085
		1086
		1087	A word of care about the use of SSL: While above mentioned
		1088	setup with self-signed server certificates retrieved over
		1089	the wires can protect you from a passive eavesdropper it
		1090	doesn't help against an active attacker. It's clearly an
		1091	improvement over sending the passwords in clear but you
		1092	should be aware that a man-in-the-middle attack is trivially
		1093	possible (in particular with tools such as dsniff,
		1094	http://www.monkey.org/~dugsong/dsniff/). Use of an ssh
		1095	tunnel (see below for some examples) is preferable if you
		1096	care seriously about the security of your
		1097	mailbox.
		1098
		1099
		1100	__fetchmail__ also supports authentication to the ESMTP
		1101	server on the client side according to RFC 2554. You can
		1102	specify a name/password pair to be used with the keywords
		1103	`esmtpname' and `esmtppassword'; the former defaults to the
		1104	username of the calling user.
		1105	!!DAEMON MODE
		1106
		1107
		1108	The __--daemon __ or __-d
		1109	__ option runs ''fetchmail'' in daemon
		1110	mode. You must specify a numeric argument which is a polling
		1111	interval in seconds.
		1112
		1113
		1114	In daemon mode, ''fetchmail'' puts itself in background
		1115	and runs forever, querying each specified host and then
		1116	sleeping for the given polling interval.
		1117
		1118
		1119	Simply invoking
		1120
		1121
		1122	fetchmail -d 900
		1123
		1124
		1125	will, therefore, poll all the hosts described in your
		1126	''~/.fetchmailrc'' file (except those explicitly excluded
		1127	with the `skip' verb) once every fifteen
		1128	minutes.
		1129
		1130
		1131	It is possible to set a polling interval in your
		1132	''~/.fetchmailrc'' file by saying `set daemon
		1133	''
		1134
		1135
		1136	Only one daemon process is permitted per user; in daemon
		1137	mode, ''fetchmail'' makes a per-user lockfile to
		1138	guarantee this.
		1139
		1140
		1141	Normally, calling fetchmail with a daemon in the background
		1142	sends a wakeup signal to the daemon, forcing it to poll
		1143	mailservers immediately. (The wakeup signal is SIGHUP if
		1144	fetchmail is running as root, SIGUSR1 otherwise.) The wakeup
		1145	action also clears any `wedged' flags indicating that
		1146	connections have wedged due to failed authentication or
		1147	multiple timeouts.
		1148
		1149
		1150	The option __--quit__ will kill a running daemon process
		1151	instead of waking it up (if there is no such process,
		1152	''fetchmail'' notifies you). If the --quit option is the
		1153	only command-line option, that's all there is to
		1154	it.
		1155
		1156
		1157	The quit option may also be mixed with other command-line
		1158	options; its effect is to kill any running daemon before
		1159	doing what the other options specify in combination with the
		1160	rc file.
		1161
		1162
		1163	The __-L __ or __--logfile
		1164	__ option (keyword: set logfile) allows
		1165	you to redirect status messages emitted while detached into
		1166	a specified logfile (follow the option with the logfile
		1167	name). The logfile is opened for append, so previous
		1168	messages aren't deleted. This is primarily useful for
		1169	debugging configurations.
		1170
		1171
		1172	The __--syslog__ option (keyword: set syslog) allows you
		1173	to redirect status and error messages emitted to the
		1174	syslog(3) system daemon if available. Messages are
		1175	logged with an id of __fetchmail__, the facility
		1176	__LOG_MAIL__, and priorities __LOG_ERR__,
		1177	__LOG_ALERT__ or __LOG_INFO__. This option is intended
		1178	for logging status and error messages which indicate the
		1179	status of the daemon and the results while fetching mail
		1180	from the server(s). Error messages for command line options
		1181	and parsing the ''.fetchmailrc'' file are still written
		1182	to stderr, or to the specified log file. The
		1183	__--nosyslog__ option turns off use of syslog(3),
		1184	assuming it's turned on in the ''~/.fetchmailrc'' file,
		1185	or that the __-L__ or __--logfile __
		1186	option was used.
		1187
		1188
		1189	The __-N__ or --nodetach option suppresses backgrounding
		1190	and detachment of the daemon process from its control
		1191	terminal. This is primarily useful for debugging. Note that
		1192	this also causes the logfile option to be ignored (though
		1193	perhaps it shouldn't).
		1194
		1195
		1196	Note that while running in daemon mode polling a POP2 or
		1197	IMAP2bis server, transient errors (such as DNS failures or
		1198	sendmail delivery refusals) may force the fetchall option on
		1199	for the duration of the next polling cycle. This is a
		1200	robustness feature. It means that if a message is fetched
		1201	(and thus marked seen by the mailserver) but not delivered
		1202	locally due to some transient error, it will be re-fetched
		1203	during the next poll cycle. (The IMAP logic doesn't delete
		1204	messages until they're delivered, so this problem does not
		1205	arise.)
		1206
		1207
		1208	If you touch or change the ''~/.fetchmailrc'' file while
		1209	fetchmail is running in daemon mode, this will be detected
		1210	at the beginning of the next poll cycle. When a changed
		1211	''~/.fetchmailrc'' is detected, fetchmail rereads it and
		1212	restarts from scratch (using exec(2); no state information
		1213	is retained in the new instance). Note also that if you
		1214	break the ''~/.fetchmailrc'' file's syntax, the new
		1215	instance will softly and silently vanish away on
		1216	startup.
		1217	!!ADMINISTRATIVE OPTIONS
		1218
		1219
		1220	The __--postmaster __ option (keyword: set
		1221	postmaster) specifies the last-resort username to which
		1222	multidrop mail is to be forwarded if no matching local
		1223	recipient can be found. Normally this is just the user who
		1224	invoked fetchmail. If the invoking user is root, then the
		1225	default of this option is the user `postmaster'. Setting
		1226	postmaster to the empty string causes such mail to be
		1227	discarded.
		1228
		1229
		1230	The __--nobounce__ option suppresses the normal action of
		1231	bouncing errors back to the sender in an RFC1894-conformant
		1232	error message. If nobounce is on, the message will go to the
		1233	postmaster instead.
		1234
		1235
		1236	The __--invisible__ option (keyword: set invisible) tries
		1237	to make fetchmail invisible. Normally, fetchmail behaves
		1238	like any other MTA would -- it generates a Received header
		1239	into each message describing its place in the chain of
		1240	transmission, and tells the MTA it forwards to that the mail
		1241	came from the machine fetchmail itself is running on. If the
		1242	invisible option is on, the Received header is suppressed
		1243	and fetchmail tries to spoof the MTA it forwards to into
		1244	thinking it came directly from the mailserver
		1245	host.
		1246
		1247
		1248	The __--showdots__ option (keyword: set showdots) forces
		1249	fetchmail to show progress dots even if the current tty is
		1250	not stdout (for example logfiles). Starting with fetchmail
		1251	version 5.3.0, progress dots are only shown on stdout by
		1252	default.
		1253
		1254
		1255	By specifying the __--tracepolls__ option, you can ask
		1256	fetchmail to add information to the Received header on the
		1257	form
		1258	__.fetchmailrc'', this is called
		1259	`tracepolls'.
		1260	!!RETRIEVAL FAILURE MODES
		1261
		1262
		1263	The protocols ''fetchmail'' uses to talk to mailservers
		1264	are next to bulletproof. In normal operation forwarding to
		1265	port 25, no message is ever deleted (or even marked for
		1266	deletion) on the host until the SMTP listener on the client
		1267	side has acknowledged to ''fetchmail'' that the message
		1268	has been either accepted for delivery or rejected due to a
		1269	spam block.
		1270
		1271
		1272	When forwarding to an MDA, however, there is more
		1273	possibility of error. Some MDAs are `safe' and reliably
		1274	return a nonzero status on any delivery error, even one due
		1275	to temporary resource limits. The well-known
		1276	procmail(1) program is like this; so are most
		1277	programs designed as mail transport agents, such as
		1278	sendmail(1), and exim(1). These programs give
		1279	back a reliable positive acknowledgement and can be used
		1280	with the mda option with no risk of mail loss. Unsafe MDAs,
		1281	though, may return 0 even on delivery failure. If this
		1282	happens, you will lose mail.
		1283
		1284
		1285	The normal mode of ''fetchmail'' is to try to download
		1286	only `new' messages, leaving untouched (and undeleted)
		1287	messages you have already read directly on the server (or
		1288	fetched with a previous ''fetchmail --keep''). But you
		1289	may find that messages you've already read on the server are
		1290	being fetched (and deleted) even when you don't specify
		1291	--all. There are several reasons this can
		1292	happen.
		1293
		1294
		1295	One could be that you're using POP2. The POP2 protocol
		1296	includes no representation of `new' or `old' state in
		1297	messages, so ''fetchmail'' must treat all messages as new
		1298	all the time. But POP2 is obsolete, so this is
		1299	unlikely.
		1300
		1301
		1302	Under POP3, blame RFC1725. That version of the POP3 protocol
		1303	specification removed the LAST command, and some POP servers
		1304	follow it (you can verify this by invoking ''fetchmail
		1305	-v'' to the mailserver and watching the response to LAST
		1306	early in the query). The ''fetchmail'' code tries to
		1307	compensate by using POP3's UID feature, storing the
		1308	identifiers of messages seen in each session until the next
		1309	session, in the ''.fetchids'' file. But this doesn't
		1310	track messages seen with other clients, or read directly
		1311	with a mailer on the host but not deleted afterward. A
		1312	better solution would be to switch to IMAP.
		1313
		1314
		1315	Another potential POP3 problem might be servers that insert
		1316	messages in the middle of mailboxes (some VMS
		1317	implementations of mail are rumored to do this). The
		1318	''fetchmail'' code assumes that new messages are appended
		1319	to the end of the mailbox; when this is not true it may
		1320	treat some old messages as new and vice versa. The only real
		1321	fix for this problem is to switch to IMAP.
		1322
		1323
		1324	Yet another POP3 problem is that if they can't make
		1325	tempfiles in the user's home directory, some POP3 servers
		1326	will hand back an undocumented response that causes
		1327	fetchmail to spuriously report
		1328
		1329
		1330	The IMAP code uses the presence or absence of the server
		1331	flag Seen to decide whether or not a message is new. Under
		1332	Unix, it counts on your IMAP server to notice the BSD-style
		1333	Status flags set by mail user agents and set the Seen flag
		1334	from them when appropriate. All Unix IMAP servers we know of
		1335	do this, though it's not specified by the IMAP RFCs. If you
		1336	ever trip over a server that doesn't, the symptom will be
		1337	that messages you have already read on your host will look
		1338	new to the server. In this (unlikely) case, only messages
		1339	you fetched with ''fetchmail --keep'' will be both
		1340	undeleted and marked old.
		1341
		1342
		1343	In ETRN and ODMR modes, ''fetchmail'' does not actually
		1344	retrieve messages; instead, it asks the server's SMTP
		1345	listener to start a queue flush to the client via SMTP.
		1346	Therefore it sends only undelivered messages.
		1347	!!SPAM FILTERING
		1348
		1349
		1350	Many SMTP listeners allow administrators to set up `spam
		1351	filters' that block unsolicited email from specified
		1352	domains. A MAIL FROM or DATA line that triggers this feature
		1353	will elicit an SMTP response which (unfortunately) varies
		1354	according to the listener.
		1355
		1356
		1357	Newer versions of ''sendmail'' return an error code of
		1358	571. This return value is blessed by RFC1893 as
		1359	''
		1360
		1361
		1362	According to current drafts of the replacement for RFC821,
		1363	the correct thing to return in this situation is 550
		1364
		1365
		1366	The ''exim'' MTA returns 501
		1367	''
		1368
		1369
		1370	The ''postfix'' MTA runs 554 as an antispam
		1371	response.
		1372
		1373
		1374	The ''fetchmail'' code recognizes and discards the
		1375	message on any of a list of responses that defaults to [[571,
		1376	550, 501, 554] but can be set with the `antispam' option.
		1377	This is one of the ''only'' three circumstance under
		1378	which fetchmail ever discards mail (the others are the 552
		1379	and 553 errors described below, and the suppression of
		1380	multidropped messages with a message-ID already
		1381	seen).
		1382
		1383
		1384	If ''fetchmail'' is fetching from an IMAP server, the
		1385	antispam response will be detected and the message rejected
		1386	immediately after the headers have been fetched, without
		1387	reading the message body. Thus, you won't pay for
		1388	downloading spam message bodies.
		1389
		1390
		1391	If the ''spambounce'' option is on, mail that is
		1392	spam-blocked triggers an RFC1892 bounce message informing
		1393	the originator that we do not accept mail from
		1394	it.
		1395	!!SMTP/ESMTP ERROR HANDLING
		1396
		1397
		1398	Besides the spam-blocking described above, fetchmail takes
		1399	special actions on the following SMTP/ESMTP error
		1400	responses
		1401
		1402
		1403	452 (insufficient system storage)
		1404
		1405
		1406	Leave the message in the server mailbox for later
		1407	retrieval.
		1408
		1409
		1410	552 (message exceeds fixed maximum message
		1411	size)
		1412
		1413
		1414	Delete the message from the server. Send bounce-mail to the
		1415	originator.
		1416
		1417
		1418	553 (invalid sending domain)
		1419
		1420
		1421	Delete the message from the server. Don't even try to send
		1422	bounce-mail to the originator.
		1423
		1424
		1425	Other errors trigger bounce mail back to the
		1426	originator.
		1427	!!THE RUN CONTROL FILE
		1428
		1429
		1430	The preferred way to set up fetchmail is to write a
		1431	''.fetchmailrc'' file in your home directory (you may do
		1432	this directly, with a text editor, or indirectly via
		1433	''fetchmailconf''). When there is a conflict between the
		1434	command-line arguments and the arguments in this file, the
		1435	command-line arguments take precedence.
		1436
		1437
		1438	To protect the security of your passwords, when --version is
		1439	not on your ''~/.fetchmailrc'' may not have more than
		1440	0600 (u=rw,g=,o=) permissions; ''fetchmail'' will
		1441	complain and exit otherwise.
		1442
		1443
		1444	You may read the ''.fetchmailrc'' file as a list of
		1445	commands to be executed when ''fetchmail'' is called with
		1446	no arguments.
		1447
		1448
		1449	__Run Control Syntax__
		1450
		1451
		1452	Comments begin with a '#' and extend through the end of the
		1453	line. Otherwise the file consists of a series of server
		1454	entries or global option statements in a free-format,
		1455	token-oriented syntax.
		1456
		1457
		1458	There are four kinds of tokens: grammar keywords, numbers
		1459	(i.e. decimal digit sequences), unquoted strings, and quoted
		1460	strings. A quoted string is bounded by double quotes and may
		1461	contain whitespace (and quoted digits are treated as a
		1462	string). An unquoted string is any whitespace-delimited
		1463	token that is neither numeric, string quoted nor contains
		1464	the special characters `,', `;', `:', or `='.
		1465
		1466
		1467	Any amount of whitespace separates tokens in server entries,
		1468	but is otherwise ignored. You may use standard C-style
		1469	escapes (n, t, b, octal, and hex) to embed non-printable
		1470	characters or string delimiters in strings.
		1471
		1472
		1473	Each server entry consists of one of the keywords `poll' or
		1474	`skip', followed by a server name, followed by server
		1475	options, followed by any number of user descriptions. Note:
		1476	the most common cause of syntax errors is mixing up user and
		1477	server options.
		1478
		1479
		1480	For backward compatibility, the word `server' is a synonym
		1481	for `poll'.
		1482
		1483
		1484	You can use the noise keywords `and', `with', `has',
		1485	`wants', and `options' anywhere in an entry to make it
		1486	resemble English. They're ignored, but but can make entries
		1487	much easier to read at a glance. The punctuation characters
		1488	':', ';' and ',' are also ignored.
		1489
		1490
		1491	__Poll vs. Skip__
		1492
		1493
		1494	The `poll' verb tells fetchmail to query this host when it
		1495	is run with no arguments. The `skip' verb tells
		1496	''fetchmail'' not to poll this host unless it is
		1497	explicitly named on the command line. (The `skip' verb
		1498	allows you to experiment with test entries safely, or easily
		1499	disable entries for hosts that are temporarily
		1500	down.)
		1501
		1502
		1503	__Keyword/Option Summary__
		1504
		1505
		1506	Here are the legal options. Keyword suffixes enclosed in
		1507	square brackets are optional. Those corresponding to
		1508	command-line options are followed by `-' and the appropriate
		1509	option letter.
		1510
		1511
		1512	Here are the legal global options:
		1513
		1514
		1515	Here are the legal server options:
		1516
		1517
		1518	Here are the legal user options:
		1519
		1520
		1521	Remember that all user options must ''follow'' all server options.
		1522
		1523
		1524	In the .fetchmailrc file, the `envelope' string argument may
		1525	be preceded by a whitespace-separated number. This number,
		1526	if specified, is the number of such headers to skip (that
		1527	is, an argument of 1 selects the second header of the given
		1528	type). This is sometime useful for ignoring bogus Received
		1529	headers created by an ISP's local delivery
		1530	agent.
		1531
		1532
		1533	__Keywords Not Corresponding To Option
		1534	Switches__
		1535
		1536
		1537	The `folder' and `smtphost' options (unlike their
		1538	command-line equivalents) can take a space- or
		1539	comma-separated list of names following them.
		1540
		1541
		1542	All options correspond to the obvious command-line
		1543	arguments, except the following: `via', `interval', `aka',
		1544	`is', `to', `dns'/`no dns', `checkalias'/`no checkalias',
		1545	`password', `preconnect', `postconnect', `localdomains',
		1546	`stripcr'/`no stripcr', `forcecr'/`no forcecr',
		1547	`pass8bits'/`no pass8bits' `dropstatus/no dropstatus',
		1548	`dropdelivered/no dropdelivered', `mimedecode/no
		1549	mimedecode', `idle/no idle', and `no envelope'.
		1550
		1551
		1552	The `via' option is for if you want to have more than one
		1553	configuration pointing at the same site. If it is present,
		1554	the string argument will be taken as the actual DNS name of
		1555	the mailserver host to query. This will override the
		1556	argument of poll, which can then simply be a distinct label
		1557	for the configuration (e.g. what you would give on the
		1558	command line to explicitly query this host).
		1559
		1560
		1561	The `interval' option (which takes a numeric argument)
		1562	allows you to poll a server less frequently than the basic
		1563	poll interval. If you say `interval N' the server this
		1564	option is attached to will only be queried every N poll
		1565	intervals.
		1566
		1567
		1568	The `is' or `to' keywords associate the following local
		1569	(client) name(s) (or server-name to client-name mappings
		1570	separated by =) with the mailserver user name in the entry.
		1571	If an is/to list has `*' as its last name, unrecognized
		1572	names are simply passed through.
		1573
		1574
		1575	A single local name can be used to support redirecting your
		1576	mail when your username on the client machine is different
		1577	from your name on the mailserver. When there is only a
		1578	single local name, mail is forwarded to that local username
		1579	regardless of the message's Received, To, Cc, and Bcc
		1580	headers. In this case ''fetchmail'' never does DNS
		1581	lookups.
		1582
		1583
		1584	When there is more than one local name (or name mapping) the
		1585	''fetchmail'' code does look at the Received, To, Cc, and
		1586	Bcc headers of retrieved mail (this is `multidrop mode'). It
		1587	looks for addresses with hostname parts that match your poll
		1588	name or your `via', `aka' or `localdomains' options, and
		1589	usually also for hostname parts which DNS tells it are
		1590	aliases of the mailserver. See the discussion of `dns',
		1591	`checkalias', `localdomains', and `aka' for details on how
		1592	matching addresses are handled.
		1593
		1594
		1595	If ''fetchmail'' cannot match any mailserver usernames or
		1596	localdomain addresses, the mail will be bounced. Normally it
		1597	will be bounced to the sender, but if `nobounce' is on it
		1598	will go to the postmaster (which in turn defaults to being
		1599	the calling user).
		1600
		1601
		1602	The `dns' option (normally on) controls the way addresses
		1603	from multidrop mailboxes are checked. On, it enables logic
		1604	to check each host address that doesn't match an `aka' or
		1605	`localdomains' declaration by looking it up with DNS. When a
		1606	mailserver username is recognized attached to a matching
		1607	hostname part, its local mapping is added to the list of
		1608	local recipients.
		1609
		1610
		1611	The `checkalias' option (normally off) extends the lookups
		1612	performed by the `dns' keyword in multidrop mode, providing
		1613	a way to cope with remote MTAs that identify themselves
		1614	using their canonical name, while they're polled using an
		1615	alias. When such a server is polled, checks to extract the
		1616	envelope address fail, and ''fetchmail'' reverts to
		1617	delivery using the To/Cc/Bcc headers (See below `Header vs.
		1618	Envelope addresses'). Specifying this option instructs
		1619	''fetchmail'' to retrieve all the IP addresses associated
		1620	with both the poll name and the name used by the remote MTA
		1621	and to do a comparison of the IP addresses. This comes in
		1622	handy in situations where the remote server undergoes
		1623	frequent canonical name changes, that would otherwise
		1624	require modifications to the rcfile. `checkalias' has no
		1625	effect if `no dns' is specified in the rcfile.
		1626
		1627
		1628	The `aka' option is for use with multidrop mailboxes. It
		1629	allows you to pre-declare a list of DNS aliases for a
		1630	server. This is an optimization hack that allows you to
		1631	trade space for speed. When ''fetchmail'', while
		1632	processing a multidrop mailbox, grovels through message
		1633	headers looking for names of the mailserver, pre-declaring
		1634	common ones can save it from having to do DNS lookups. Note:
		1635	the names you give as arguments to `aka' are matched as
		1636	suffixes -- if you specify (say) `aka netaxs.com', this will
		1637	match not just a hostnamed netaxs.com, but any hostname that
		1638	ends with `.netaxs.com'; such as (say) pop3.netaxs.com and
		1639	mail.netaxs.com.
		1640
		1641
		1642	The `localdomains' option allows you to declare a list of
		1643	domains which fetchmail should consider local. When
		1644	fetchmail is parsing address lines in multidrop modes, and a
		1645	trailing segment of a host name matches a declared local
		1646	domain, that address is passed through to the listener or
		1647	MDA unaltered (local-name mappings are ''not''
		1648	applied).
		1649
		1650
		1651	If you are using `localdomains', you may also need to
		1652	specify `no envelope', which disables ''fetchmail'''s
		1653	normal attempt to deduce an envelope address from the
		1654	Received line or X-Envelope-To header or whatever header has
		1655	been previously set by `envelope'. If you set `no envelope'
		1656	in the defaults entry it is possible to undo that in
		1657	individual entries by using `envelope
		1658	''
		1659
		1660
		1661	The __password__ option requires a string argument, which
		1662	is the password to be used with the entry's
		1663	server.
		1664
		1665
		1666	The `preconnect' keyword allows you to specify a shell
		1667	command to be executed just before each time
		1668	''fetchmail'' establishes a mailserver connection. This
		1669	may be useful if you are attempting to set up secure POP
		1670	connections with the aid of ssh(1). If the command
		1671	returns a nonzero status, the poll of that mailserver will
		1672	be aborted.
		1673
		1674
		1675	Similarly, the `postconnect' keyword similarly allows you to
		1676	specify a shell command to be executed just after each time
		1677	a mailserver connection is taken down.
		1678
		1679
		1680	The `forcecr' option controls whether lines terminated by LF
		1681	only are given CRLF termination before forwarding. Strictly
		1682	speaking RFC821 requires this, but few MTAs enforce the
		1683	requirement it so this option is normally off (only one such
		1684	MTA, qmail, is in significant use at time of
		1685	writing).
		1686
		1687
		1688	The `stripcr' option controls whether carriage returns are
		1689	stripped out of retrieved mail before it is forwarded. It is
		1690	normally not necessary to set this, because it defaults to
		1691	`on' (CR stripping enabled) when there is an MDA declared
		1692	but `off' (CR stripping disabled) when forwarding is via
		1693	SMTP. If `stripcr' and `forcecr' are both on, `stripcr' will
		1694	override.
		1695
		1696
		1697	The `pass8bits' option exists to cope with Microsoft mail
		1698	programs that stupidly slap a
		1699	fetchmail'' declares BODY=7BIT to an
		1700	ESMTP-capable listener; this causes problems for messages
		1701	actually using 8-bit ISO or KOI-8 character sets, which will
		1702	be garbled by having the high bits of all characters
		1703	stripped. If `pass8bits' is on, ''fetchmail'' is forced
		1704	to declare BODY=8BITMIME to any ESMTP-capable listener. If
		1705	the listener is 8-bit-clean (as all the major ones now are)
		1706	the right thing will probably result.
		1707
		1708
		1709	The `dropstatus' option controls whether nonempty Status and
		1710	X-Mozilla-Status lines are retained in fetched mail (the
		1711	default) or discarded. Retaining them allows your MUA to see
		1712	what messages (if any) were marked seen on the server. On
		1713	the other hand, it can confuse some new-mail notifiers,
		1714	which assume that anything with a Status line in it has been
		1715	seen. (Note: the empty Status lines inserted by some buggy
		1716	POP servers are unconditionally discarded.)
		1717
		1718
		1719	The `dropdelivered' option controls wether Delivered-To
		1720	headers will be kept in fetched mail (the default) or
		1721	discarded. These headers are added by Qmail and Postfix
		1722	mailservers in order to avoid mail loops but may get in your
		1723	way if you try to
		1724
		1725
		1726	The `mimedecode' option controls whether MIME messages using
		1727	the quoted-printable encoding are automatically converted
		1728	into pure 8-bit data. If you are delivering mail to an
		1729	ESMTP-capable, 8-bit-clean listener (that includes all of
		1730	the major MTAs like sendmail), then this will automatically
		1731	convert quoted-printable message headers and data into 8-bit
		1732	data, making it easier to understand when reading mail. If
		1733	your e-mail programs know how to deal with MIME messages,
		1734	then this option is not needed. The mimedecode option is off
		1735	by default, because doing RFC2047 conversion on headers
		1736	throws away character-set information and can lead to bad
		1737	results if the encoding of the headers differs from the body
		1738	encoding.
		1739
		1740
		1741	The `idle' option is usable only with IMAP servers
		1742	supporting the RFC2177 IDLE command extension. If it is
		1743	enabled, and fetchmail detects that IDLE is supported, an
		1744	IDLE will be issued at the end of each poll. This will tell
		1745	the IMAP server to hold the connection open and notify the
		1746	client when new mail is available. If you need to poll a
		1747	link frequently, IDLE can save bandwidth by eliminating
		1748	TCP/IP connects and LOGIN/LOGOUT sequences. On the other
		1749	hand, an IDLE connection will eat almost all of your
		1750	fetchmail's time, because it will never drop the connection
		1751	and allow other pools to occur unless the server times out
		1752	the IDLE. It also doesn't work with multiple folders; only
		1753	the first folder will ever be polled.
		1754
		1755
		1756	The `properties' option is an extension mechanism. It takes
		1757	a string argument, which is ignored by fetchmail itself. The
		1758	string argument may be used to store configuration
		1759	information for scripts which require it. In particular, the
		1760	output of `--configdump' option will make properties
		1761	associated with a user entry readily available to a Python
		1762	script.
		1763
		1764
		1765	__Miscellaneous Run Control Options__
		1766
		1767
		1768	The words `here' and `there' have useful English-like
		1769	significance. Normally `user eric is esr' would mean that
		1770	mail for the remote user `eric' is to be delivered to `esr',
		1771	but you can make this clearer by saying `user eric there is
		1772	esr here', or reverse it by saying `user esr here is eric
		1773	there'
		1774
		1775
		1776	Legal protocol identifiers for use with the `protocol'
		1777	keyword are:
		1778
		1779
		1780	auto (or AUTO) pop2 (or POP2) pop3 (or POP3) sdps (or SDPS)
		1781	imap (or IMAP) apop (or APOP) kpop (or KPOP)
		1782
		1783
		1784	Legal authentication types are `any', `password',
		1785	`kerberos', 'kereberos_v5' and `gssapi', `cram-md5', `otp',
		1786	`ntlm', `ssh`. The `password' type specifies authentication
		1787	by normal transmission of a password (the password may be
		1788	plaintext or subject to protocol-specific encryption as in
		1789	APOP); `kerberos' tells ''fetchmail'' to try to get a
		1790	Kerberos ticket at the start of each query instead, and send
		1791	an arbitrary string as the password; and `gssapi' tells
		1792	fetchmail to use GSSAPI authentication. See the description
		1793	of the `auth' keyword for more.
		1794
		1795
		1796	Specifying `kpop' sets POP3 protocol over port 1109 with
		1797	Kerberos V4 authentication. These defaults may be overridden
		1798	by later options.
		1799
		1800
		1801	There are currently four global option statements; `set
		1802	logfile' followed by a string sets the same global specified
		1803	by --logfile. A command-line --logfile option will override
		1804	this. Also, `set daemon' sets the poll interval as --daemon
		1805	does. This can be overridden by a command-line --daemon
		1806	option; in particular --daemon 0 can be used to force
		1807	foreground operation. The `set postmaster' statement sets
		1808	the address to which multidrop mail defaults if there are no
		1809	local matches. Finally, `set syslog' sends log messages to
		1810	syslogd(8).
		1811	!!INTERACTION WITH RFC 822
		1812
		1813
		1814	When trying to determine the originating address of a
		1815	message, fetchmail looks through headers in the following
		1816	order:
		1817
		1818
		1819	Return-Path: Resent-Sender: (ignored if it doesn't contain
		1820	an @ or !) Sender: (ignored if it doesn't contain an @ or !)
		1821	Resent-From: From: Reply-To: Apparently-From:
		1822
		1823
		1824	The originating address is used for logging, and to set the
		1825	MAIL FROM address when forwarding to SMTP. This order is
		1826	intended to cope gracefully with receiving mailing list
		1827	messages in multidrop mode. The intent is that if a local
		1828	address doesn't exist, the bounce message won't be returned
		1829	blindly to the author or to the list itself, but rather to
		1830	the list manager (which is less annoying).
		1831
		1832
		1833	In multidrop mode, destination headers are processed as
		1834	follows: First, fetchmail looks for the Received: header (or
		1835	whichever one is specified by the `envelope' option) to
		1836	determine the local recipient address. If the mail is
		1837	addressed to more than one recipient, the Received line
		1838	won't contain any information regarding recipient
		1839	addresses.
		1840
		1841
		1842	Then fetchmail looks for the Resent-To:, Resent-Cc:, and
		1843	Resent-Bcc: lines. If they exists, they should contain the
		1844	final recipients and have precedence over their To:/Cc:/Bcc:
		1845	counterparts. If the Resent-* lines doesn't exist, the To:,
		1846	Cc:, Bcc: and Apparently-To: lines are looked for. (The
		1847	presence of a Resent-To: is taken to imply that the person
		1848	referred by the To: address has already received the
		1849	original copy of the mail).
		1850	!!CONFIGURATION EXAMPLES
		1851
		1852
		1853	Note that although there are password declarations in a good
		1854	many of the examples below, this is mainly for illustrative
		1855	purposes. We recommend stashing account/password pairs in
		1856	your $HOME/.netrc file, where they can be used not just by
		1857	fetchmail but by ftp(1) and other programs.
		1858
		1859
		1860	Basic format is:
		1861
		1862
		1863	poll SERVERNAME protocol PROTOCOL username NAME password PASSWORD
		1864	Example:
		1865
		1866
		1867	poll pop.provider.net protocol pop3 username
		1868	Or, using some abbreviations:
		1869
		1870
		1871	poll pop.provider.net proto pop3 user
		1872	Multiple servers may be listed:
		1873
		1874
		1875	poll pop.provider.net proto pop3 user
		1876	Here's a version of those two with more whitespace and some noise words:
		1877
		1878
		1879	poll pop.provider.net proto pop3
		1880	user
		1881	This version is much easier to read and doesn't cost significantly more (parsing is done only once, at startup time).
		1882
		1883
		1884	If you need to include whitespace in a parameter string,
		1885	enclose the string in double quotes. Thus:
		1886
		1887
		1888	poll mail.provider.net with proto pop3:
		1889	user
		1890	You may have an initial server description headed by the keyword `defaults' instead of `poll' followed by a name. Such a record is interpreted as defaults for all queries to use. It may be overwritten by individual server descriptions. So, you could write:
		1891
		1892
		1893	defaults proto pop3
		1894	user
		1895	It's possible to specify more than one user per server (this is only likely to be useful when running fetchmail in daemon mode as root). The `user' keyword leads off a user description, and every user specification in a multi-user entry must include it. Here's an example:
		1896
		1897
		1898	poll pop.provider.net proto pop3 port 3111
		1899	user
		1900	This associates the local username `smith' with the pop.provider.net username `jsmith' and the local username `jjones' with the pop.provider.net username `jones'. Mail for `jones' is kept on the server after download.
		1901
		1902
		1903	Here's what a simple retrieval configuration for a
		1904	multi-drop mailbox looks like:
		1905
		1906
		1907	poll pop.provider.net:
		1908	user maildrop with pass secret1 to golux 'hurkle'='happy' snark here
		1909	This says that the mailbox of account `maildrop' on the server is a multi-drop box, and that messages in it should be parsed for the server user names `golux', `hurkle', and `snark'. It further specifies that `golux' and `snark' have the same name on the client as on the server, but mail for server user `hurkle' should be delivered to client user `happy'.
		1910
		1911
		1912	Here's an example of another kind of multidrop
		1913	connection:
		1914
		1915
		1916	poll pop.provider.net localdomains loonytoons.org toons.org:
		1917	user maildrop with pass secret1 to * here
		1918	This also says that the mailbox of account `maildrop' on the server is a multi-drop box. It tells fetchmail that any address in the loonytoons.org or toons.org domains (including subdomain addresses like `joe@daffy.loonytoons.org') should be passed through to the local SMTP listener without modification. Be careful of mail loops if you do this!
		1919
		1920
		1921	Here's an example configuration using ssh and the plugin
		1922	option. The queries are made directly on the stdin and
		1923	stdout of imapd via ssh. Note that in this setup, IMAP
		1924	authentication can be skipped.
		1925
		1926
		1927	poll mailhost.net with proto imap:
		1928	plugin
		1929	!!THE USE AND ABUSE OF MULTIDROP MAILBOXES
		1930
		1931
		1932	Use the multiple-local-recipients feature with caution -- it
		1933	can bite. All multidrop features are ineffective in ETRN and
		1934	ODMR modes.
		1935
		1936
		1937	Also, note that in multidrop mode duplicate mails are
		1938	suppressed. A piece of mail is considered duplicate if it
		1939	has the same message-ID as the message immediately preceding
		1940	and more than one addressee. Such runs of messages may be
		1941	generated when copies of a message addressed to multiple
		1942	users are delivered to a multidrop box.
		1943
		1944
		1945	__Header vs. Envelope addresses__
		1946
		1947
		1948	The fundamental problem is that by having your mailserver
		1949	toss several peoples' mail in a single maildrop box, you may
		1950	have thrown away potentially vital information about who
		1951	each piece of mail was actually addressed to (the `envelope
		1952	address', as opposed to the header addresses in the RFC822
		1953	To/Cc/Bcc headers). This `envelope address' is the address
		1954	you need in order to reroute mail properly.
		1955
		1956
		1957	Sometimes ''fetchmail'' can deduce the envelope address.
		1958	If the mailserver MTA is ''sendmail'' and the item of
		1959	mail had just one recipient, the MTA will have written a
		1960	`by/for' clause that gives the envelope addressee into its
		1961	Received header. But this doesn't work reliably for other
		1962	MTAs, nor if there is more than one recipient. By default,
		1963	''fetchmail'' looks for envelope addresses in these
		1964	lines; you can restore this default with -E
		1965	''
		1966
		1967
		1968	Alternatively, some SMTP listeners and/or mail servers
		1969	insert a header in each message containing a copy of the
		1970	envelope addresses. This header (when it exists) is often
		1971	`X-Envelope-To'. Fetchmail's assumption about this can be
		1972	changed with the -E or `envelope' option. Note that writing
		1973	an envelope header of this kind exposes the names of
		1974	recipients (including blind-copy recipients) to all
		1975	receivers of the messages; it is therefore regarded by some
		1976	administrators as a security/privacy problem.
		1977
		1978
		1979	A slight variation of the `X-Envelope-To' header is the
		1980	`Delivered-To' put by qmail to avoid mail loops. It will
		1981	probably prefix the user name with a string that normally
		1982	matches the user's domain. To remove this prefix you can use
		1983	the -Q or `qvirtual' option.
		1984
		1985
		1986	Sometimes, unfortunately, neither of these methods works.
		1987	When they all fail, fetchmail must fall back on the contents
		1988	of To/Cc/Bcc headers to try to determine recipient
		1989	addressees -- and these are not reliable. In particular,
		1990	mailing-list software often ships mail with only the list
		1991	broadcast address in the To header.
		1992
		1993
		1994	When ''fetchmail'' cannot deduce a recipient address that
		1995	is local, and the intended recipient address was anyone
		1996	other than fetchmail's invoking user, mail will get lost.
		1997	This is what makes the multidrop feature risky.
		1998
		1999
		2000	A related problem is that when you blind-copy a mail
		2001	message, the Bcc information is carried ''only'' as
		2002	envelope address (it's not put in the headers fetchmail can
		2003	see unless there is an X-Envelope header). Thus,
		2004	blind-copying to someone who gets mail over a fetchmail link
		2005	will fail unless the the mailserver host routinely writes
		2006	X-Envelope or an equivalent header into messages in your
		2007	maildrop.
		2008
		2009
		2010	__Good Ways To Use Multidrop Mailboxes__
		2011
		2012
		2013	Multiple local names can be used to administer a mailing
		2014	list from the client side of a ''fetchmail'' collection.
		2015	Suppose your name is `esr', and you want to both pick up
		2016	your own mail and maintain a mailing list called (say)
		2017	''
		2018
		2019
		2020	On your server, you can alias `fetchmail-friends' to `esr';
		2021	then, in your ''.fetchmailrc'', declare `to esr
		2022	fetchmail-friends here'. Then, when mail including
		2023	`fetchmail-friends' as a local address gets fetched, the
		2024	list name will be appended to the list of recipients your
		2025	SMTP listener sees. Therefore it will undergo alias
		2026	expansion locally. Be sure to include `esr' in the local
		2027	alias expansion of fetchmail-friends, or you'll never see
		2028	mail sent only to the list. Also be sure that your listener
		2029	has the
		2030	''
		2031
		2032
		2033	This trick is not without its problems, however. You'll
		2034	begin to see this when a message comes in that is addressed
		2035	only to a mailing list you do ''not'' have declared as a
		2036	local name. Each such message will feature an
		2037	`X-Fetchmail-Warning' header which is generated because
		2038	fetchmail cannot find a valid local name in the recipient
		2039	addresses. Such messages default (as was described above) to
		2040	being sent to the local user running ''fetchmail'', but
		2041	the program has no way to know that that's actually the
		2042	right thing.
		2043
		2044
		2045	__Bad Ways To Abuse Multidrop Mailboxes__
		2046
		2047
		2048	Multidrop mailboxes and ''fetchmail'' serving multiple
		2049	users in daemon mode do not mix. The problem, again, is mail
		2050	from mailing lists, which typically does not have an
		2051	individual recipient address on it. Unless ''fetchmail''
		2052	can deduce an envelope address, such mail will only go to
		2053	the account running fetchmail (probably root). Also,
		2054	blind-copied users are very likely never to see their mail
		2055	at all.
		2056
		2057
		2058	If you're tempted to use ''fetchmail'' to retrieve mail
		2059	for multiple users from a single mail drop via POP or IMAP,
		2060	think again (and reread the section on header and envelope
		2061	addresses above). It would be smarter to just let the mail
		2062	sit in the mailserver's queue and use fetchmail's ETRN or
		2063	ODMR modes to trigger SMTP sends periodically (of course,
		2064	this means you have to poll more frequently than the
		2065	mailserver's expiry period). If you can't arrange this, try
		2066	setting up a UUCP feed.
		2067
		2068
		2069	If you absolutely ''must'' use multidrop for this
		2070	purpose, make sure your mailserver writes an
		2071	envelope-address header that fetchmail can see. Otherwise
		2072	you ''will'' lose mail and it ''will'' come back to
		2073	haunt you.
		2074
		2075
		2076	__Speeding Up Multidrop Checking__
		2077
		2078
		2079	Normally, when multiple users are declared ''fetchmail''
		2080	extracts recipient addresses as described above and checks
		2081	each host part with DNS to see if it's an alias of the
		2082	mailserver. If so, the name mappings described in the to ...
		2083	here declaration are done and the mail locally
		2084	delivered.
		2085
		2086
		2087	This is the safest but also slowest method. To speed it up,
		2088	pre-declare mailserver aliases with `aka'; these are checked
		2089	before DNS lookups are done. If you're certain your aka list
		2090	contains __all__ DNS aliases of the mailserver (and all
		2091	MX names pointing at it) you can declare `no dns' to
		2092	suppress DNS lookups entirely and ''only'' match against
		2093	the aka list.
		2094	!!EXIT CODES
		2095
		2096
		2097	To facilitate the use of ''fetchmail'' in shell scripts,
		2098	an exit code is returned to give an indication of what
		2099	occurred during a given connection.
		2100
		2101
		2102	The exit codes returned by ''fetchmail'' are as
		2103	follows:
		2104
		2105
		2106	0
		2107
		2108
		2109	One or more messages were successfully retrieved (or, if the
		2110	-c option was selected, were found waiting but not
		2111	retrieved).
		2112
		2113
		2114	1
		2115
		2116
		2117	There was no mail awaiting retrieval. (There may have been
		2118	old mail still on the server but not selected for
		2119	retrieval.)
		2120
		2121
		2122	2
		2123
		2124
		2125	An error was encountered when attempting to open a socket to
		2126	retrieve mail. If you don't know what a socket is, don't
		2127	worry about it -- just treat this as an 'unrecoverable
		2128	error'. This error can also be because a protocol fetchmail
		2129	wants to use is not listed in /etc/services.
		2130
		2131
		2132	3
		2133
		2134
		2135	The user authentication step failed. This usually means that
		2136	a bad user-id, password, or APOP id was specified. Or it may
		2137	mean that you tried to run fetchmail under circumstances
		2138	where it did not have standard input attached to a terminal
		2139	and could not prompt for a missing password.
		2140
		2141
		2142	4
		2143
		2144
		2145	Some sort of fatal protocol error was detected.
		2146
		2147
		2148	5
		2149
		2150
		2151	There was a syntax error in the arguments to
		2152	''fetchmail.''
		2153
		2154
		2155	6
		2156
		2157
		2158	The run control file had bad permissions.
		2159
		2160
		2161	7
		2162
		2163
		2164	There was an error condition reported by the server. Can
		2165	also fire if ''fetchmail'' timed out while waiting for
		2166	the server.
		2167
		2168
		2169	8
		2170
		2171
		2172	Client-side exclusion error. This means ''fetchmail''
		2173	either found another copy of itself already running, or
		2174	failed in such a way that it isn't sure whether another copy
		2175	is running.
		2176
		2177
		2178	9
		2179
		2180
		2181	The user authentication step failed because the server
		2182	responded
		2183
		2184
		2185	10
		2186
		2187
		2188	The ''fetchmail'' run failed while trying to do an SMTP
		2189	port open or transaction.
		2190
		2191
		2192	11
		2193
		2194
		2195	Fatal DNS error. Fetchmail encountered an error while
		2196	performing a DNS lookup at startup and could not
		2197	proceed.
		2198
		2199
		2200	12
		2201
		2202
		2203	BSMTP batch file could not be opened.
		2204
		2205
		2206	13
		2207
		2208
		2209	Poll terminated by a fetch limit (see the --fetchlimit
		2210	option).
		2211
		2212
		2213	14
		2214
		2215
		2216	Server busy indication.
		2217
		2218
		2219	23
		2220
		2221
		2222	Internal error. You should see a message on standard error
		2223	with details.
		2224
		2225
		2226	When ''fetchmail'' queries more than one host, return
		2227	status is 0 if ''any'' query successfully retrieved mail.
		2228	Otherwise the returned error status is that of the last host
		2229	queried.
		2230	!!FILES
		2231
		2232
		2233	~/.fetchmailrc
		2234
		2235
		2236	default run control file
		2237
		2238
		2239	~/.fetchids
		2240
		2241
		2242	default location of file associating hosts with last message
		2243	IDs seen (used only with newer RFC1725-compliant POP3
		2244	servers supporting the UIDL command).
		2245
		2246
		2247	~/.fetchmail.pid
		2248
		2249
		2250	lock file to help prevent concurrent runs (non-root
		2251	mode).
		2252
		2253
		2254	~/.netrc
		2255
		2256
		2257	your FTP run control file, which (if present) will be
		2258	searched for passwords as a last resort before prompting for
		2259	one interactively.
		2260
		2261
		2262	/var/run/fetchmail.pid
		2263
		2264
		2265	lock file to help prevent concurrent runs (root mode, Linux
		2266	systems).
		2267
		2268
		2269	/etc/fetchmail.pid
		2270
		2271
		2272	lock file to help prevent concurrent runs (root mode,
		2273	systems without /var/run).
		2274	!!ENVIRONMENT
		2275
		2276
		2277	If the FETCHMAILUSER variable is set, it is used as the name
		2278	of the calling user (default local name) for purposes such
		2279	as mailing error notifications. Otherwise, if either the
		2280	LOGNAME or USER variable is correctly set (e.g. the
		2281	corresponding UID matches the session user ID) then that
		2282	name is used as the default local name. Otherwise
		2283	getpwuid(3) must be able to retrieve a password entry
		2284	for the session ID (this elaborate logic is designed to
		2285	handle the case of multiple names per userid
		2286	gracefully).
		2287
		2288
		2289	If the environment variable FETCHMAILHOME is set to a valid
		2290	and existing directory name, the .fetchmailrc and .fetchids
		2291	and .fetchmail.pid files are put there instead of in the
		2292	invoking user's home directory (and lose the leading dots on
		2293	theirt names). The .netrc file is looked for in the the
		2294	invoking user's home directory regardless of FETCHMAILHOME's
		2295	setting.
		2296	!!SIGNALS
		2297
		2298
		2299	If a ''fetchmail'' daemon is running as root, SIGHUP
		2300	wakes it up from its sleep phase and forces a poll of all
		2301	non-skipped servers (this is in accordance with the usual
		2302	conventions for system daemons).
		2303
		2304
		2305	If ''fetchmail'' is running in daemon mode as non-root,
		2306	use SIGUSR1 to wake it (this is so SIGHUP due to logout can
		2307	retain the default action of killing it).
		2308
		2309
		2310	Running ''fetchmail'' in foreground while a background
		2311	fetchmail is running will do whichever of these is
		2312	appropriate to wake it up.
		2313	!!BUGS AND KNOWN PROBLEMS
		2314
		2315
		2316	The mda and plugin options interact badly. In order to
		2317	collect error status from the MDA, fetchmail has to change
		2318	its normal signal handling so that dead plugin processes
		2319	don't get reaped until the end of the poll cycle. This can
		2320	cause resource starvation if too many zombies accumulate. So
		2321	either don't deliver to a MDA using plugins or risk being
		2322	overrun by an army of undead.
		2323
		2324
		2325	The RFC822 address parser used in multidrop mode chokes on
		2326	some @-addresses that are technically legal but bizarre.
		2327	Strange uses of quoting and embedded comments are likely to
		2328	confuse it.
		2329
		2330
		2331	In a message with multiple envelope headers, only the last
		2332	one processed will be visible to fetchmail. To get around
		2333	this, use a mailserver-side filter that consolidates the
		2334	contents of all envelope headers into a single one
		2335	(procmail, mailagent, or maildrop can be programmed to do
		2336	this fairly easily).
		2337
		2338
		2339	Use of some of these protocols requires that the program
		2340	send unencrypted passwords over the TCP/IP connection to the
		2341	mailserver. This creates a risk that name/password pairs
		2342	might be snaffled with a packet sniffer or more
		2343	sophisticated monitoring software. Under Linux and FreeBSD,
		2344	the --interface option can be used to restrict polling to
		2345	availability of a specific interface device with a specific
		2346	local or remote IP address, but snooping is still possible
		2347	if (a) either host has a network device that can be opened
		2348	in promiscuous mode, or (b) the intervening network link can
		2349	be tapped. We recommend the use of ssh(1) tunnelling
		2350	to not only shroud your passwords but encrypt the entire
		2351	conversation.
		2352
		2353
		2354	Use of the %F or %T escapes in an mda option could open a
		2355	security hole, because they pass text manipulable by an
		2356	attacker to a shell command. Potential shell characters are
		2357	replaced by `_' before execution. The hole is further
		2358	reduced by the fact that fetchmail temporarily discards any
		2359	suid privileges it may have while running the MDA. For
		2360	maximum safety, however, don't use an mda command containing
		2361	%F or %T when fetchmail is run from the root account
		2362	itself.
		2363
		2364
		2365	Fetchmail's method of sending bouncemail and spam bounces
		2366	requires that port 25 of localhost be available for sending
		2367	mail via SMTP.
		2368
		2369
		2370	If you modify a ''~/.fetchmailrc'' while a background
		2371	instance is running and break the syntax, the background
		2372	instance will die silently. Unfortunately, it can't die
		2373	noisily because we don't yet know whether syslog should be
		2374	enabled.
		2375
		2376
		2377	The -f - option (reading a configuration from stdin) is
		2378	incompatible with the plugin option.
		2379
		2380
		2381	The UIDL code is generally flaky and tends to lose its state
		2382	on errors and line drops (so that old messages are re-seen).
		2383	If this happens to you, switch to IMAP4.
		2384
		2385
		2386	The `principal' option only handles Kerberos IV, not
		2387	V.
		2388
		2389
		2390	Send comments, bug reports, gripes, and the like to the
		2391	fetchmail-friends list
		2392	!!AUTHOR
		2393
		2394
		2395	Eric S. Raymond
		2396	popclient'', by Carl Harris
		2397	''
		2398	!!SEE ALSO
		2399
		2400
		2401	mutt(1), elm(1), mail(1), sendmail(8), popd(8), imapd(8),
		2402	netrc(5)
		2403	!!APPLICABLE STANDARDS
		2404
		2405
		2406	SMTP/ESMTP:
		2407
		2408
		2409	RFC 821, RFC2821, RFC 1869, RFC 1652, RFC 1870, RFC 1983,
		2410	RFC 1985, RFC 2554
		2411
		2412
		2413	mail:
		2414
		2415
		2416	RFC 822, RFC2822, RFC 1123, RFC 1892, RFC 1894
		2417
		2418
		2419	POP2:
		2420
		2421
		2422	RFC 937
		2423
		2424
		2425	POP3:
		2426
		2427
		2428	RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC1734, RFC 1939,
		2429	RFC 1957, RFC2195, RFC 2449
		2430
		2431
		2432	APOP:
		2433
		2434
		2435	RFC 1460, RFC 1725, RFC 1939
		2436
		2437
		2438	RPOP:
		2439
		2440
		2441	RFC 1081, RFC 1225
		2442
		2443
		2444	IMAP2/IMAP2BIS:
		2445
		2446
		2447	RFC 1176, RFC 1732
		2448
		2449
		2450	IMAP4/IMAP4rev1:
		2451
		2452
		2453	RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061, RFC 2195,
		2454	RFC 2177, RFC 2683
		2455
		2456
		2457	ETRN:
		2458
		2459
		2460	RFC 1985
		2461
		2462
		2463	ODMR/ATRN:
		2464
		2465
		2466	RFC 2645
		2467
		2468
		2469	OTP:
		2470
		2471
		2472	RFC 1938
		2473
		2474
		2475	LMTP:
		2476
		2477
		2478	RFC 2033
		2479
		2480
		2481	GSSAPI:
		2482
		2483
		2484	RFC 1508
		2485	----