Provided by: mpop_1.0.28-1_amd64 
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.
--received-header[=(on|off)]
Enable or disable the Received header. See the received_header 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.
--passwordeval=[eval]
Set your password for authentication to the output (stdout) of the execution
of eval.
--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.
received_header [(on|off)]
Enable or disable the Received header. By default, mpop prepends a Received header
to the mail during delivery. This is required by the RFCs if the mail is
subsequently further delivered e.g. via SMTP, and it is a good idea in all other
cases. Nevertheless, if you absolutely have to, you can disable the Received header
with this command.
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. First, if passwordeval is set, it will evaluate that command. If passwordeval
is not set, mpop will try to find the password 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.
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, scram-sha-1, cram-md5, gssapi, external,
digest-md5, 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, digest-md5, 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, 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. First, if passwordeval is set, it
will evaluate that command. If passwordeval is not set, mpop will try to find the
password 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.
passwordeval [eval]
Set your password for authentication to the output (stdout) of the execution of
eval.
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
passwordeval gpg -d ~/.mpop.password.gpg
# Set a default account (optional).
account default : provider1
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)
2013-04 MPOP(1)