NAME
mpop - A POP3 client
SYNOPSIS
Mail retrieval mode (default):
mpop [option...] [--] [account...]
mpop --host=host [option...]
Server information mode:
mpop [option...] --serverinfo [account...]
mpop --host=host [option...] --serverinfo
DESCRIPTION
In mail retrieval mode of operation, mpop retrieves mails from one or
more POP3 mailboxes, optionally does some filtering, and delivers them
through a mail delivery agent (MDA) or to maildir folders, mbox files,
or Exchange pickup directories. Mails that were successfully delivered
before will not be retrieved a second time, even if errors occur or
mpop is terminated in the middle of a session.
In server information mode, mpop prints information about one or more
POP3 servers.
If no account names are given on the command line, the one named
default will be used.
EXIT STATUS
The standard sendmail exit codes are used, as defined in sysexits.h.
OPTIONS
Options override configuration file settings, for every used account.
General Options
--version
Print version information. This includes information
about the library used for TLS/SSL support (if any), the
library used for authentication, and the authentication
mechanisms supported by this library.
--help Print help.
-P, --pretend
Print the configuration settings that would be used, but
do not take further action. An asterisk (‘*’) will be
printed instead of your password.
-d, --debug
Print lots of debugging information, including the whole
conversation with the POP3 server. Be careful with this
option: the (potentially dangerous) output will not be
sanitized, and your password may get printed in an easily
decodable format!
This option implies --half-quiet, because the progress
output would interfere with the debugging output.
Changing the mode of operation
-S, --serverinfo
Print information about the POP3 server(s) and exit. This
includes information about supported features
(pipelining, authentication methods, TOP command, ...),
about parameters (time for which mails will not be
deleted, minimum time between logins, ...), and about the
TLS certificate (if TLS is active).
Configuration options
-C, --file=conffile
Use the given file instead of ~/.mpoprc as configuration
file.
--host=hostname
Use this POP3 server with settings from the command line;
do not use any configuration file data. You cannot use
both this option and account names on the command line.
--port=number
Set the port number to connect to. See the port command
below.
--timeout=(off|seconds)
Set a network timeout. See the timeout command below.
--pipelining=(auto|on|off)
Enable or disable POP3 pipelining. See the pipelining
command below.
--auth[=(on|method)]
Set the authentication method to automatic (with "on") or
manually choose an authentication method. See the auth
command below.
--user=[username]
Set or unset the user name for authentication. See the
user command below.
--tls[=(on|off)]
Enable or disable TLS/SSL encryption. See the tls command
below.
--tls-starttls[=(on|off)]
Enable or disable the POP3 STLS command for TLS
encryption. See the tls_starttls command below.
--tls-trust-file=[file]
Set or unset a trust file for TLS encryption. See the
tls_trust_file command below.
--tls-crl-file=[file]
Set or unset a certificate revocation list (CRL) file for
TLS. See the tls_crl_file command below.
--tls-fingerprint=[fingerprint]
Set ot unset the fingerprint of a trusted TLS
certificate. See the tls_fingerprint command below.
--tls-key-file=[file]
Set or unset a key file for TLS encryption. See the
tls_key_file command below.
--tls-cert-file=[file]
Set or unset a cert file for TLS encryption. See the
tls_cert_file command below.
--tls-certcheck[=(on|off)]
Enable or disable server certificate checks for TLS
encryption. See the tls_certcheck command below.
--tls-force-sslv3[=(on|off)]
Force TLS/SSL version SSLv3. See the tls_force_sslv3
command below.
--tls-min-dh-prime-bits=[bits]
Set or unset minimum bit size of the Diffie-Hellmann (DH)
prime. See the tls_min_dh_prime_bits command below.
--tls-priorities=[priorities]
Set or unset TLS priorities. See the tls_priorities
command below.
Options specific to mail retrieval mode
-q, --quiet
Do not print status or progress information.
-Q, --half-quiet
Print status but not progress information.
-a, --all-accounts
Query all accounts in the configuration file.
-A, --auth-only
Authenticate only; do not retrieve mail. Useful for SMTP-
after-POP.
-s, --status-only
Print number and size of mails in each account only; do
not retrieve mail.
-n, --only-new[=(on|off)]
Process only new messages. See the only_new command
below.
-k, --keep[=(on|off)]
Do not delete mails from POP3 servers, regardless of
other options or settings. See the keep command below.
--killsize=(off|size)
Set or unset kill size. See the killsize command below.
--skipsize=(off|size)
Set or unset skip size. See the skipsize command below.
--filter=[program]
Set a filter which will decide whether to retrieve, skip,
or delete each mail by investigating the mail’s headers.
See the filter command below.
--delivery=method,method_arguments...
How to deliver messages received from this account. See
the delivery command below. Note that a comma is used
instead of a blank to separate the method from its
arguments.
--uidls-file=filename
File to store UIDLs in. See the uidls_file command below.
USAGE
mpop normally uses a configuration file (~/.mpoprc by default) that
contains information about your POP3 accounts.
Skip to the EXAMPLES section for a quick start.
The configuration file is a simple text file. Empty lines and comment
lines (whose first non-blank character is ‘#’) are ignored. The file
must have no more permissions than user read/write.
Every other line must contain a command and may contain an argument to
that command.
The argument may be enclosed in double quotes ("), for example if its
first or last character is a blank.
If the first character of a filename is the tilde (~), this tilde will
be replaced by $HOME.
If a command accepts the argument on, it also accepts an empty argument
and treats that as if it was on.
Commands are as follows:
defaults
Set defaults. The following configuration commands will set
default values for all following account definitions.
account name [:account[,...]]
Start a new account definition with the given name. The current
default values are filled in.
If a colon and a list of previously defined accounts is given
after the account name, the new account, with the filled in
default values, will inherit all settings from the accounts in
the list.
host hostname
The POP3 server to retrieve mails from. The argument may be a
host name or a network address. Every account definition must
contain this command.
port number
The port that the POP3 server listens on. The default is 110,
unless TLS without STARTTLS is used, in which case it is 995.
timeout (off|seconds)
Set or unset a network timeout, in seconds. The default is 180
seconds. The argument off means that no timeout will be set,
which means that the operating system default will be used.
pipelining (auto|on|off)
Enable or disable POP3 pipelining. The default is auto, which
means that mpop enables pipelining for POP3 servers that
advertize this capability, and disables it for all other
servers. See also --serverinfo.
It is always safe to disable pipelining. It is not recommended
to force pipelining for servers that are not known to support
it.
Pipelining works by sending up to PIPELINE_MAX commands to the
server, then begin to read its answers, and refill the command
pipeline when the number of unanswered commands drops to
PIPELINE_MIN. PIPELINE_MIN and PIPELINE_MAX are compile time
contants.
delivery method method_arguments...
How to deliver messages received from this account.
delivery mda command
Deliver the mails through a mail delivery agent (MDA).
All occurences of %F in the command will be replaced with
the envelope from address of the current message (or
MAILER-DAEMON if none is found). Note that this address
is guaranteed to contain only letters a-z and A-Z, digits
0-9, and any of ".@_-+/", even though that is only a
subset of what is theoretically allowed in a mail
address. Other characters, including those interpreted by
the shell, are replaced with "_". Nevertheless, you
should put %F into single quotes: '%F'.
Use "delivery mda /usr/bin/procmail -f '%F' -d $USER" for
the procmail MDA.
Use "delivery mda /usr/sbin/sendmail -oi -oem -f '%F' --
$USER" to let your MTA handle the mail.
Use "delivery mda /usr/local/bin/msmtp --host=localhost
--from='%F' -- $USER@‘hostname‘.‘dnsdomainname‘" to pass
the mail to your MTA via SMTP. (This is what fetchmail
does by default.)
delivery maildir directory
Deliver the mails to the given maildir directory. The
directory must exist and it must be a valid maildir
directory; mpop will not create directories. This
delivery type only works on file systems that support
hard links.
delivery mbox mbox-file
Deliver the mails to the given file in mbox format. The
file will be locked with fcntl(2). mpop uses the MBOXRD
mbox format variant; see the documentation of the mbox
format.
delivery exchange directory
Deliver the mails to the given Exchange pickup directory.
The directory must exist.
If the delivery method needs to parse the mail headers for an
envelope from address (the mda method if the command contains
%F, and the mbox method), then it needs to create a temporary
file to store the mail headers (but not the body) in. See
$TMPDIR in the FILES / ENVIRONMENT section.
uidls_file filename
The file to store UIDLs in. These are needed to identify new
messages. %U in the filename will be replaced by the username
of the current account. %H in the filename will be replaced by
the hostname of the current account. If the filename contains
directories that do not exist, mpop will create them. mpop
locks this file for exclusive access when accessing the
associated POP3 account.
The default value is "~/.mpop_uidls/%U_at_%H". You can also use
a single UIDLS file for multiple accounts, but then you cannot
poll more than one of these accounts at the same time.
auth [(on|method)]
This command chooses the POP3 authentication method. With the
argument on, mpop will choose the best one available for you
(see below). This is the default.
You probably need to set a username (with user) and password
(with password). If no password is set but one is needed during
authentication, mpop will try to find it in ~/.netrc. If that
fails, it will try to find it in SYSCONFDIR/netrc (use --version
to find out what SYSCONFDIR is on your platform). If that fails,
it will try to get it from a system specific keyring (if
available). If that fails but a controlling terminal is
available, mpop will prompt you for it.
Currently supported keyrings are the Gnome Keyring and the Mac
OS X Keychain. The script mpop-gnome-tool.py can be used to
manage Gnome Keyring passwords for mpop. To manage Mac OS X
Keychain passwords, use the Keychain Access GUI application. The
account name is same as the mpop user argument. The keychain
item name is pop3://<hostname> where <hostname> matches the mpop
host argument.
Available methods are user, apop, plain, login, cram-md5,
digest-md5, scram-sha-1, gssapi, external, login, and ntlm.
Note that one or more of these methods may be unavailable due to
lack of support in the underlying authentication library. Use
the --version option to find out which methods are supported.
The user, plain and login methods send your authentication data
in cleartext over the net, and the apop and ntlm methods are
vulnerable to attacks. These methods should therefore only be
used together with the tls command.
If you don’t choose the method yourself, mpop chooses the best
secure method that the POP3 server supports. Secure means that
your authentication data will not be sent in cleartext over the
net. For TLS encrypted connections, every authentication method
is secure in this sense. If TLS is not active, only gssapi,
scram-sha-1, digest-md5, and cram-md5 are secure in this sense.
The external method is special: the actual authentication
happens outside of the SMTP protocol, typically by sending a TLS
client certificate (see the tls_cert_file command). The external
method merely confirms that this authentication succeeded for
the given user (or, if no user name is given, confirms that
authentication succeeded). This authentication method is not
chosen automatically; you have to request it manually.
user login
Set your user name for POP3 authentication.
password secret
Set your password for POP3 authentication. If no password is
set but one is needed during authentication, mpop will try to
find it in ~/.netrc. If that fails, it will try to find it in
SYSCONFDIR/netrc (use --version to find out what SYSCONFDIR is
on your platform). If that fails, it will try to get it from a
system specific keychain (if available). If that fails but a
controlling terminal is available, mpop will prompt you for it.
ntlmdomain [domain]
Set a domain for the ntlm authentication method. The default is
to use no domain (equivalent to an empty argument), but some
servers seem to require one, even if it is an arbitrary string.
tls [(on|off)]
This command enables or disables TLS (also known as SSL)
encrypted connections to the POP3 server. Not every server
supports this, and many that support it require the additional
command tls_starttls off.
With TLS/SSL, the connection with the POP3 server will be
protected against eavesdroppers and man-in-the-middle attacks.
To use TLS/SSL, it is required to either use the tls_trust_file
command (highly recommended) or to disable tls_certcheck.
tls_starttls [(on|off)]
This command chooses the TLS/SSL variant: with STARTTLS (on,
default) or POP3-over-TLS (off). Most servers support the latter
variant, which is also commonly referred to as "POP3 with SSL".
tls_trust_file file
This command activates strict server certificate verification.
The filename must be the absolute path name of a file in PEM
format containing one or more certificates of trusted
Certification Authorities (CAs).
On Debian based systems, you can install the ca-certificates
package and use the file /etc/ssl/certs/ca-certificates.crt.
An empty argument disables this feature.
tls_fingerprint [fingerprint]
This command sets or unsets the fingerprint of a particular TLS
certificate. This certificate will then be trusted, regardless
of its contents. This can be used to trust broken certificates
(e.g. with a non-matching hostname) or in situations where
tls_trust_file cannot be used for some reason.
You can give either an SHA1 (recommended) or an MD5 fingerprint
in the format 01:23:45:67:...
You can use --serverinfo --tls --tls-certcheck=off to get the
peer certificate’s fingerprints.
tls_crl_file [file]
This command sets or unsets a certificate revocation list (CRL)
file for TLS, to be used during strict server certificate
verification as enabled by the tls_trust_file command. This
allows the verification procedure to detect revoked
certificates.
tls_key_file file
This command (together with the tls_cert_file command) enables
mpop to send a client certificate to the POP3 server if
requested.
The filename must be the absolute path name of a file in PEM
format containing a private key. Be sure that this file is only
readable by yourself!
An empty argument disables this feature.
tls_cert_file file
This command (together with the tls_key_file command) enables
mpop to send a client certificate to the POP3 server if
requested.
The filename must be the absolute path name of a file in PEM
format containing a certificate.
An empty argument disables this feature.
tls_certcheck [(on|off)]
This command enables or disables checks for the server
certificate.
WARNING: When the checks are disabled, TLS/SSL sessions will be
vulnerable to man-in-the-middle attacks!
tls_force_sslv3 [(on|off)]
Force TLS/SSL version SSLv3. This might be needed to use SSL
with some old and broken servers. Do not use this unless you
have to.
tls_min_dh_prime_bits [bits]
Set or unset the minimum number of Diffie-Hellman (DH) prime
bits that mpop will accept for TLS sessions. The default is set
by the TLS library and can be selected by using an empty
argument to this command. Only lower the default (for example
to 512 bits) if there is no other way to make TLS work with the
remote server.
tls_priorities [priorities]
Set the priorities for TLS sessions. The default is set by the
TLS library and can be selected by using an empty argument to
this command. Currently this command only works with
sufficiently recent GnuTLS releases. See the GnuTLS
documentation of the gnutls_priority_init function for a
description of the priorities string.
only_new [(on|off)]
By default, mpop processes only new messages (new messages are
those that were not already successfully retrieved in an earlier
session). If this option is turned off, mpop will process all
messages.
keep [(on|off)]
Keep all mails on the POP3 server, never delete them. The
default behaviour is to delete mails that have been successfully
retrieved or filtered by kill filters.
killsize (off|size)
Mails larger than the given size will be deleted (unless the
keep command is used, in which case they will just be skipped).
The size argument must be zero or greater. If it is followed by
a ‘k’ or an ‘m’, the size is measured in kibibytes/mebibytes
instead of bytes. Note that some POP3 servers report slightly
incorrect sizes for mails; see NOTES below.
When killsize is set to 0 and keep is set to on, then all mails
are marked as retrieved, but no mail gets deleted from the
server. This can be used to synchronize the UID list on the
client to the UID list on the server.
skipsize (off|size)
Mails larger than the given size will be skipped (not
downloaded). The size argument must be zero or greater. If it
is followed by a ‘k’ or an ‘m’, the size is measured in
kibibytes/mebibytes instead of bytes. Note that some POP3
servers report slightly incorrect sizes for mails; see NOTES
below.
filter [command]
Set a filter which will decide whether to retrieve, skip, or
delete each mail by investigating the mail’s headers. The POP3
server must support the POP3 TOP command for this to work; see
option --serverinfo above. An empty argument disables filtering.
All occurences of %F in the command will be replaced with the
envelope from address of the current message (or MAILER-DAEMON
if none is found). Note that this address is guaranteed to
contain only letters a-z and A-Z, digits 0-9, and any of
".@_-+/", even though that is only a subset of what is
theoretically allowed in a mail address. Other characters,
including those interpreted by the shell, are replaced with "_".
Nevertheless, you should put %F into single quotes: '%F'.
All occurences of %S in the command will be replaced with the
size of the current mail as reported by the POP3 server.
The mail headers (plus the blank line separating the headers
from the body) will be piped to the command. Based on the return
code, mpop decides what to do with the mail:
0: proceed normally; no special action
1: delete the mail; do not retrieve it
2: skip the mail; do not retrieve it
Return codes greater than or equal to 3 mean that an error
occured. The sysexits.h error codes may be used to give
information about the kind of the error, but this is not
necessary.
FILTERING
There are three filtering commands available. They will be executed in
the following order:
killsize
skipsize
filter
If a filtering command applies to a mail, the remaining filters will
not be executed.
EXAMPLES
Configuration file
# Default values for all accounts.
defaults
# Activate TLS.
tls on
# Enable full TLS certificate checks.
tls_trust_file /etc/ssl/certs/ca-certificates.crt
# Use the POP3-over-TLS variant instead of the STARTTLS variant.
# This is often called "POP3 with SSL". Most servers support this.
tls_starttls off
# Use the procmail mail delivery agent.
delivery mda "/usr/bin/procmail -f '%F' -d $USER"
# For Sendmail:
#delivery mda "/usr/sbin/sendmail -oi -oem -f '%F' -- $USER"
# For msmtp (delivery via SMTP):
#delivery mda "/usr/bin/msmtp --host=localhost --from='%F' -- $USER"
# Delivery to a maildir folder:
#delivery maildir ~/Mail/incoming
# Delivery to a MBOX mail folder:
#delivery mbox ~/Mail/new
# Delivery to an Exchange pickup directory:
#delivery exchange c:\exchange\pickup
# Two pop3 mailboxes at the provider.
account provider1
host mx.provider.example
user john_smith
password secret
# Copy the settings from the previous account, and only override the
# settings that differ.
account provider2 : provider1
user joey
password secret2
# A freemail service.
account freemail
host pop.freemail.example
user 1238476
password pass
# Set a default account (optional).
account default : provider1
Manually finding the right CA certificate for tls_trust_file
The following example works as of 2007-04-18.
For the Gmail POP server, you first issue the following command:
mpop --serverinfo --host=pop.gmail.com --tls=on --tls-starttls=off
--tls-certcheck=off
The option --tls-starttls=off is needed for Gmail, but may not be
necessary for other servers. The option --tls-certcheck=off allows mpop
to accept any certificate, so that it can print some information about
it.
According to the output of this command, the issuer of the server
certificate is "Equifax Secure Certificate Authority". This means that
you have to trust the Equifax CA to use full TLS security. You can
download the appropriate certificate from
http://www.geotrust.com/resources/root_certificates/index.asp (Equifax
was bought by GeoTrust). The file you need for the tls_trust_file
command is Equifax_Secure_Certificate_Authority.cer.
The following command should now succeed:
mpop --serverinfo --host=pop.gmail.com --tls=on --tls-starttls=off
--tls-trust-file=Equifax_Secure_Certificate_Authority.cer
Filtering with SpamAssassin
The command filter "/path/to/spamc -c > /dev/null" will delete all
mails that SpamAssassin thinks are spam. Since no message body is
passed to SpamAssassin, you should disable all body-specific tests in
the SpamAssassin configuration file; for example set use_bayes 0.
If your mail provider runs SpamAssassin for you, you just have to check
for the result. The following script can do that when used as an mpop
filter:
#!/bin/sh
if [ "‘grep "^X-Spam-Status: Yes"‘" ]; then
exit 1 # kill this message
else
exit 0 # proceed normally
fi
Since the filter command is passed to a shell, you can also use this
directly:
filter if [ "‘grep "^X-Spam-Status: Yes"‘" ]; then exit 1; else exit 0;
fi
FILES / ENVIRONMENT
~/.mpoprc
Default configuration file.
~/.mpop_uidls
Default directory to store UIDLs files in.
~/.netrc and SYSCONFDIR/netrc
The netrc file contains login information. If a password is not
found in the configuration file, mpop will search it in ~/.netrc
and SYSCONFDIR/netrc before prompting the user for it. The
syntax of netrc files is described in netrc(5) or ftp(1).
$USER, $LOGNAME
These variables override the user’s login name. $LOGNAME is only
used if $USER is unset. The user’s login name is used for
Received headers.
$TMPDIR
Directory to create temporary files in. If this is unset, a
system specific default directory is used.
NOTES
Some POP3 servers still do not support the UIDL command. In this case,
mpop cannot recognize messages that were already successfully
retrieved, and will treat all messages as new. Use the --serverinfo
option to find out if a server supports the UIDL command.
Some POP3 servers count end-of-line characters as two bytes (CRLF)
instead of one (LF), so that the size of a mail as reported by the POP3
server is slightly larger than the actual size. This has the following
consequences: The size filters are not accurate. Do not rely on exact
size filtering. The progress output may display inaccurate (slightly
too low) percentage values for the first mail retrieved from a POP3
server. mpop will detect this after the first mail has been read and
will display corrected values for subsequent mails.
AUTHOR
mpop was written by Martin Lambers <marlam@marlam.de>
Other authors are listed in the AUTHORS file in the source
distribution.
SEE ALSO
procmail(1), spamassassin(1), fetchmail(1), getmail(1), netrc(5) or
ftp(1), mbox(5), fcntl(2)
2010-03