This is ../../mpop/doc/mpop.info, produced by makeinfo version 4.13
from ../../mpop/doc/mpop.texi.

This manual was last updated 1 May 2012 for version 1.0.27 of mpop.

   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012  Martin
Lambers

     Copying and distribution of this file, with or without
     modification, are permitted in any medium without royalty provided
     the copyright notice and this notice are preserved. These files
     are offered as-is, without any warranty.

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* mpop: (mpop).		A POP3 client.
END-INFO-DIR-ENTRY


File: mpop.info,  Node: Top,  Next: Introduction,  Up: (dir)

mpop
****

This manual was last updated 1 May 2012 for version 1.0.27 of mpop.

   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012  Martin
Lambers

     Copying and distribution of this file, with or without
     modification, are permitted in any medium without royalty provided
     the copyright notice and this notice are preserved. These files
     are offered as-is, without any warranty.

* Menu:

* Introduction::			Basic concepts.
* Configuration file::			Configuration file commands.
* Invocation::				Command line options.
* Transport Layer Security::		How to use TLS/SSL.
* Authentication::			How to use authentication.
* Pipelining::				How to use POP3 pipelining.
* Defective POP3 servers::		Common defects of POP3 servers.
* Mail retrieval mode::			How to retrieve mail.
* Filtering::				How to filter mails.
* Server information mode::		How to obtain information about
					an POP3 server.
* Examples::				Usage examples.


File: mpop.info,  Node: Introduction,  Next: Configuration file,  Prev: Top,  Up: Top

1 Introduction
**************

mpop is a POP3 client.

   In its default mode of operation, it 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.

   The best way to start is probably to have a look at the Examples
section.  *Note Examples::.

   In addition to the mail retrieval mode, mpop can be used in server
information mode. In this mode, mpop prints as much information as it
can get about a given POP3 server (greeting, supported features, login
delay, maximum mail size, ...).

   Normally, a configuration file contains information about which POP3
server to use and how to use it, but almost all settings can also be
configured on the command line.

   POP3 server information is organized in accounts. Each account
describes one POP3 server: host name, authentication settings, TLS
settings, and so on.  Each configuration file can define multiple
accounts.

   Supported features include:
   * Header based mail filtering: filter junk mail before downloading it

   * Delivery to maildir folders, mbox files, Exchange pickup
     directories, or a mail delivery agent (MDA)

   * Very fast POP3 implementation, using command pipelining

   * Authentication methods USER/PASS, APOP, PLAIN, LOGIN and CRAM-MD5
     (and GSSAPI, SCRAM-SHA-1, DIGEST-MD5, and NTLM when GNU SASL is
     used)

   * TLS encrypted connections (including server certificate
     verification and the possibility to send a client certificate)

   * Support for Internationalized Domain Names (IDN)

   * IPv6 support

   * support for multiple accounts


File: mpop.info,  Node: Configuration file,  Next: Invocation,  Prev: Introduction,  Up: Top

2 Configuration file
********************

If it exists and is readable, a user configuration file will be loaded
(`~/.mpoprc' by default).  This file must have no more permissions than
user read/write.  Configuration file settings can be changed by command
line options.

   A configuration file is a simple text file. Empty lines and comment
lines (whose first non-blank character is '#') are ignored. Every other
line must contain a command and may contain an argument to that command.
The argument may be enclosed in double quotes (").

   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 form groups. Each group starts with the `account' command
and defines the settings for one POP3 server.

   *Note Examples::.

2.1 General commands
====================

`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 (see *note defaults::).
     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. *Note
     Pipelining::.

`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.

2.2 Authentication commands
===========================

*Note Authentication::.

`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.  Accepted methods are `user',
     `apop', `plain', `scram-sha-1', `cram-md5', `gssapi', `digest-md5',
     `external', `login', and `ntlm'.  *Note Authentication::.
`user [USERNAME]'
     Set your user name for POP3 authentication. An empty argument
     unsets the user name.

`password [SECRET]'
     Set your password for POP3 authentication. An empty argument
     unsets the 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 keyring (if available). If that fails, mpop will
     prompt you for it.  *Note Authentication::.

`passwordeval [EVAL]'
     Set your password for authentication to the output (stdout) of the
     execution of EVAL.

`ntlmdomain [NTLMDOMAIN]'
     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.

2.3 TLS commands
================

*Note Transport Layer Security::.

`tls [(on|off)]'
     This command enables or disables TLS/SSL encrypted connections to
     the POP3 server. Not every server supports TLS, and many that
     support it require the `tls_starttls off' command.
     To use TLS/SSL, it is required to either use the `tls_trust_file'
     command (highly recommended) or to disable `tls_certcheck'.  *Note
     Transport Layer Security::.

`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".
     *Note Transport Layer Security::.

`tls_trust_file [FILE]'
     This command activates strict server certificate verification.
     The given file must contain one or more certificates of trusted
     Certification Authorities (CAs) in PEM format.
     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.  *Note Transport Layer
     Security::.

`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 *note tls_trust_file:: command.
     This allows the verification procedure to detect revoked
     certificates.  *Note Transport Layer Security::.

`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.
     *Note Transport Layer Security::.

`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 file must contain the private key of a certificate in PEM
     format.  An empty argument disables this feature.  *Note Transport
     Layer Security::.

`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 file must contain a certificate in PEM format.  An empty
     argument disables this feature.  *Note Transport Layer Security::.

`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!  *Note Transport Layer
     Security::.

`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.
     *Note Transport Layer Security::.

`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.  *Note
     Transport Layer Security::.

`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.  *Note Transport Layer Security::.

2.4 Commands specific to mail retrieval mode
============================================

*Note Mail retrieval mode::.

`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 *note Environment / Files::.

`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.

`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
     behavior is to delete mails that have been successfully delivered
     or filtered by kill filters.

`killsize (off|SIZE)'
     Mails larger than the given size will be deleted, not downloaded
     (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. *Note Filtering::.
     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. *Note Filtering::.

`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
     *note Server information mode::. 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
     occurred.  The `sysexits.h' error codes may be used to give
     information about the kind of the error, but this is not
     necessary. *Note Filtering::.


File: mpop.info,  Node: Invocation,  Next: Transport Layer Security,  Prev: Configuration file,  Up: Top

3 Invocation
************

3.1 Synopsis
============

   * Mail retrieval mode (default):
     `mpop [OPTION...] [--] [ACCOUNT...]'
   * Server information mode:
     `mpop [OPTION...] --serverinfo [ACCOUNT...]'

3.2 Exit code
=============

The standard exit codes from `sysexits.h' are used.

3.3 Environment / Files
=======================

``~/.mpoprc''
     The default user 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' before prompting the user for it. The syntax of
     `netrc' files is described in the `netrc(5)' or `ftp(1)' manual
     page.

``$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.

3.4 Options
===========

Options override configuration file settings. The following options are
accepted:

3.4.1 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
     the 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 debugging output
     would otherwise interfere with the progress output.

3.4.2 Changing the mode of operation
------------------------------------

`-S'
`--serverinfo'
     Print information about the POP3 server 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).  *Note Server information
     mode::.

3.4.3 Configuration options
---------------------------

Most options in this category correspond to a configuration file
command.  Please refer to *note Configuration file:: for detailed
information.
`-C FILENAME'
`--file=FILENAME'
     Use the given file instead of `~/.mpoprc' as the configuration
     file.

`--host=HOSTNAME'
     Use this POP3 server with settings from the command line; do not
     use any configuration file data. This option disables loading of
     the configuration file. You cannot use both this option and
     account names on the command line.

`--port=NUMBER'
     Set the port number to connect to. *Note port::.

`--timeout=(off|SECONDS)'
     Set or unset a network timeout, in seconds. *Note timeout::.

`--pipelining=(auto|on|off)'
     Enable or disable POP3 pipelining. *Note pipelining::.

`--received-header[=(on|off)]'
     Enable or disable the Received header. *Note received_header::.

`--auth[=(on|METHOD)]'
     Set the authentication method to automatic (with "on") or manually
     choose an authentication method. *Note auth::.

`--user=[USERNAME]'
     Set or unset the user name for authentication. *Note user::.

`--passwordeval=[EVAL]'
     Evaluate password for authentication. *Note passwordeval::.

`--tls[=(on|off)]'
     Enable or disable TLS/SSL. *Note tls::.

`--tls-starttls[=(on|off)]'
     Enable or disable STARTTLS for TLS encryption. *Note
     tls_starttls::.

`--tls-trust-file=[FILE]'
     Set or unset a trust file for TLS encryption. *Note
     tls_trust_file::.

`--tls-crl-file=[FILE]'
     Set or unset a certificate revocation list (CRL) file for TLS.
     *Note tls_crl_file::.

`--tls-fingerprint=[FINGERPRINT]'
     Set ot unset the fingerprint of a trusted TLS certificate.  *Note
     tls_fingerprint::.

`--tls-key-file=[FILE]'
     Set or unset a key file for TLS encryption. *Note tls_key_file::.

`--tls-cert-file=[FILE]'
     Set or unset a cert file for TLS encryption. *Note tls_cert_file::.

`--tls-certcheck[=(on|off)]'
     Enable or disable server certificate checks for TLS encryption.
     *Note tls_certcheck::.

`--tls-force-sslv3=(on|off)]'
     Force TLS/SSL version SSLv3. *Note tls_force_sslv3::.

`--tls-min-dh-prime-bits=[BITS]'
     Set or unset minimum bit size of the Diffie-Hellman (DH) prime.
     *Note tls_min_dh_prime_bits::.

`--tls-priorities=[PRIORITIES]'
     Set or unset TLS priorities. *Note tls_priorities::.

3.4.4 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. *Note only_new::.

`-k'
`--keep[=(on|off)]'
     Do not delete mails from POP3 servers, regardless of other options
     or settings.  *Note keep::.

`--killsize=(off|SIZE)'
     Set or unset kill size. *Note killsize::.

`--skipsize=(off|SIZE)'
     Set or unset skip size. *Note skipsize::.

`--filter=[COMMAND]'
     Set a filter which will decide whether to retrieve, skip, or
     delete each mail by investigating the mail's headers. *Note
     filter::.

`--delivery=METHOD,METHOD_ARGUMENTS...'
     How to deliver messages received from this account. *Note
     delivery::. 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. *Note uidls_file::.


File: mpop.info,  Node: Transport Layer Security,  Next: Authentication,  Prev: Invocation,  Up: Top

4 Transport Layer Security
**************************

Transport Layer Security (TLS) is a new name for Secure Socket Layer
(SSL).  The TLS 1.0 protocol is an updated version of the SSL 3.0
protocol. TLS and SSL mean the same thing.

   Quoting from RFC2246 - the TLS 1.0 protocol specification:
"The TLS protocol provides communications privacy over the Internet.
The protocol allows client/server applications to communicate in a way
that is designed to prevent eavesdropping, tampering, or message
forgery."

   POP3 servers can use TLS in one of two modes:
   * Immediately
     This is known as POP3 tunneled through TLS. The default port for
     this mode is 995 (pop3s). This is what most servers support, and
     is often simply called "POP3 with SSL".

   * Via the STARTTLS POP3 command
     The POP3 session begins normally. The client sends the STLS
     command when it wishes to begin TLS encryption. The default port
     for this mode is the default POP3 port: 110 (pop3).
   mpop can switch between these modes with the `tls_starttls' command
(see *note tls_starttls::) command or the `--tls-starttls' option (see
*note --tls-starttls::).

   When TLS is started, the server sends a certificate to identify
itself. This certificate contains information about the certificate
owner, the certificate issuer, and the activation and expiration times
of the certificate.  This information can be displayed in server
information mode.  *Note Server information mode::.

   To use TLS, it is required to either enable full server certificate
verification using the `tls_trust_file' command or `--tls-trust-file'
option, or to trust one particular peer certificate using the
`tls_fingerprint' command or `--tls-fingerprint' option, or to disable
all certificate checks using `tls_certcheck off' or
`--tls-certcheck=off'.  WARNING: When certificate checks are disabled,
TLS/SSL sessions are vulnerable to man-in-the-middle attacks!  See
*note tls_trust_file::, *note --tls-trust-file::, *note
tls_fingerprint::, *note --tls-fingerprint::, *note tls_certcheck::,
*note --tls-certcheck::.

   If your system has a file that collects all system-wide trusted CA
certificates, it is easiest to just use this in the `defaults' section
of your configuration file. On Debian-based systems, for example, the
adequate command would be `tls_trust_file
/etc/ssl/certs/ca-certificates.crt'.

   But you can also find out manually which CA certificate you need to
trust. First, issue the following command:
     $ mpop --serverinfo --host=pop.example.com --tls=on --tls-certcheck=off
   The option `--tls-certcheck=off' allows mpop to accept any
certificate, so that it can print some information about it. The output
of this command tells you the common name of the server certificate
issuer. You have to trust this issuer to use full TLS security. Usually
you can find the CA certificate on the issuer's homepage. With this CA
certificate, the following should succeed:
     $ mpop --serverinfo --host=pop.example.com --tls=on \
       --tls-trust-file=ca_cert.txt

   If the server requests it, the client can send a certificate, too.
This allows the server to verify the identity of the client. See the
EXTERNAL mechanism in *note Authentication::. The
`tls_key_file'/`tls_cert_file' commands or the
`--tls-key-file'/`--tls-cert-file' options can be used to set a client
certificate. See *note tls_key_file::/*note --tls-key-file::, *note
tls_cert_file::/*note --tls-cert-file::.  Note that GnuTLS will only
send a client certificate if it matches one of the CAs advertised by
the server. If you set a client certificate but it is not sent to the
server, probably does not match any CA that the server trusts.

   If you need to fine tune TLS parameters or have problems connecting
to your server, have a look at the *note tls_force_sslv3::, *note
tls_min_dh_prime_bits::, and *note tls_priorities:: commands.


File: mpop.info,  Node: Authentication,  Next: Pipelining,  Prev: Transport Layer Security,  Up: Top

5 Authentication
****************

POP3 servers require a client to authenticate itself before it is
allowed to retrieve mail.

   Multiple authentication methods exist. Most POP3 servers support
only some of them.  Some methods send authentication data in plain text
(or nearly plain text) to the server, and some others are vulnerable to
attacks. These methods should only be used when TLS is active to
prevent others from stealing the password. *Note Transport Layer
Security::.

   By default, mpop chooses a method automatically, and it will never
choose one that puts the authentication data at risk. See below for
details.

   mpop supports the following authentication methods:
   * `USER'
     This authentication method needs a user name and a password.  Both
     are send in plain text. All POP3 servers support this
     authentication method.

   * `PLAIN'
     This authentication method needs a user name and a password.  Both
     are send in BASE64 encoding, which can be easily decoded to plain
     text.

   * `APOP'
     This authentication method needs a user name and a password.  The
     authentication data is not sent in plain text, but APOP is
     vulnerable to man-in-the-middle attacks. This method should not be
     used unless TLS is active.

   * `SCRAM-SHA-1'
     This authentication method needs a user name and a password.  The
     authentication data is not sent in plain text, which means this
     method can safely be used without TLS.

   * `CRAM-MD5'
     This authentication method needs a user name and a password.  The
     authentication data is not sent in plain text, which means this
     method can safely be used without TLS.

   * `GSSAPI'
     This authentication method needs a user name. The Kerberos
     framework takes care of secure authentication, therefore this
     method can safely be used without TLS.

   * `EXTERNAL'
     This is a special authentication method: The actual authentication
     happens outside of the POP3 protocol, typically by sending a TLS
     client certificate (see *note Transport Layer Security::).
     The EXTERNAL method merely confirms that this authentication
     succeeded for the given user (or, if no user name is given,
     confirms that authentication succeeded). Thus it may not be
     necessary for authentication to use this method, and if the server
     does not support the EXTERNAL method, this does not mean that it
     does not support authentication with TLS client certificates.
     This authentication method is not chosen automatically; you have
     to request it manually.
     Note: (SMTP) Sendmail 8.12.11 advertises the EXTERNAL mechanism
     only after a TLS client certificate has been send. It seems to
     ignore the optional user name.  Does anyone know more about this?

   * `DIGEST-MD5'
     This is an obsolete authentication method needs a user name and a
     password.  The authentication data is not sent in plain text, but
     the encryption based on MD5 is not considered secure anymore.

   * `LOGIN'
     This is a non-standard authentication method similar to (but worse
     than) PLAIN.  It needs a user name and a password, both of which
     are send in BASE64 encoding, which can be easily decoded to plain
     text.

   * `NTLM'
     This is an obscure non-standard authentication method. It needs a
     user name and a password and in some cases a special domain
     parameter (see *note ntlmdomain::).  The authentication data is
     not send in plain text, but since NTLM is not an open standard, it
     should be considered broken and insecure.

   It depends on the underlying authentication library and its version
whether a particular method is supported or not. Use `--version' to
find out which methods are supported by your version of mpop.

   Authentication data can be set with the `user' and `password'
commands or with the `--user' option. See *note user::, *note
password::, *note --user::.  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 keyring (if available). If that
fails, 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.

   The authentication method can be chosen with the `auth' command or
`--auth' option, but it is usually sufficient to just use the `on'
argument to let mpop choose the method itself. See *note auth::, *note
--auth::.

   If mpop chooses the method itself, it will never choose an insecure
method.  If TLS is active, all methods are considered secure in this
context, because the connection to the server is protected by TLS. If
TLS is not active, only the SCRAM-SHA-1, CRAM-MD5, and GSSAPI methods
are considered secure in this context, because all the others methods
put the authentication data at risk.

   If you really want to risk your authentication data, you have to
force mpop to do that by manually setting the authentication method
while TLS is off.


File: mpop.info,  Node: Pipelining,  Next: Defective POP3 servers,  Prev: Authentication,  Up: Top

6 Pipelining
************

A POP3 client that sends multiple POP3 commands at once to a POP3
server before starting to read the server's answers is using POP3
pipelining. Since the client does not have to wait for the server's
answer before sending the next command, and the server does not have to
wait for the next command from the client, pipelining can speed up a
POP3 session substantially.

   Pipelining in mpop 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
constants.

   By default, mpop will enable pipelining automatically if the server
supports the CAPA command and advertizes the pipelining capability, and
disable it for all other servers. *Note Server information mode::.

   You can change this behaviour with the `pipelining' command or
`--pipelining' option. See *note pipelining::, *note --pipelining::. It
is always safe to disable pipelining. It is not recommended to force
pipelining for servers that are not known to support it.


File: mpop.info,  Node: Defective POP3 servers,  Next: Mail retrieval mode,  Prev: Pipelining,  Up: Top

7 Defective POP3 servers
************************

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.


File: mpop.info,  Node: Mail retrieval mode,  Next: Filtering,  Prev: Defective POP3 servers,  Up: Top

8 Mail retrieval mode
*********************

In this mode, mpop retrieves mail from one or more POP3 servers. It
delivers each of them using the method that was given with the
`delivery' command or `--delivery' option. See *note delivery::, *note
--delivery::.

   While retrieving the mail, mpop displays approximate progress
information, which can be turned off with the `--half-quiet' or
`--quiet' options; see *note --half-quiet::, *note --quiet::.

   If the delivery succeeded, the mail is deleted from the POP3 server
by default.  The `keep' command and `--keep' option can prevent the
deletion of mails; see *note keep::, *note --keep::.

   _Important note:_ Some POP3 servers will delete mails without any
user interaction. See EXPIRE in *note Server information mode::. mpop
can do nothing about that.

   If you don't want to download certain mails, but skip them or delete
them directly, you can do filtering based on the mail headers. *Note
Filtering::.

   If you just want to know if you have new mails (and how many), use
the `--status-only' option. *Note --status-only::.

   If you just want to authenticate to the POP3 server, but don't want
to look at your mails, use the `--auth-only' option. *Note
--auth-only::. This can be useful for sending mail through SMTP servers
that require SMTP-after-POP (aka POP-before-SMTP).

   Before mpop delivers a mail, it prepends a Received header to it.
This is necessary if the delivery method transmits the mail to an SMTP
server, for example. mpop does not change the contents of the mail in
any other way.


File: mpop.info,  Node: Server information mode,  Next: Examples,  Prev: Filtering,  Up: Top

9 Server information mode
*************************

In server information mode, mpop prints as much information about the
POP3 server as it can get and then exits.

   The POP3 features that can be detected are:
   * IMPLEMENTATION
     The implementation string of the POP3 server.

   * CAPA
     Support for the POP3 CAPA command. The server sends a list of its
     capabilities in response to this command.

   * PIPELINING
     Support for POP3 pipelining. *Note Pipelining::.

   * TOP
     Support for the POP3 TOP command. This is needed for header based
     filtering to work. *Note Filtering::.

   * UIDL
     Support for the POP3 UIDL command. This is needed to distinguish
     between new and already retrieved messages.

   * LOGIN-DELAY
     The minimum time between two POP3 sessions. The server may refuse
     a POP3 session if the last one was active less than this time
     period ago.

   * EXPIRE
     The time after which old mails are deleted by the POP3 server.
        * NEVER: The POP3 server will not delete mail without the user
          requesting it.

        * 0: The POP3 server will not keep mails; all mails will be
          deleted after they have been downloaded, regardless of the
          user's wishes.

        * NUMBER: The number of days that the POP3 server will keep
          mails before deleting them without user interaction.

   * STARTTLS
     *Note Transport Layer Security::.

   * AUTH
     *Note Authentication::.

   * RESP-CODES
     If authentication fails and the POP3 server issues an error
     message beginning with a square bracket, this message will include
     additional information about the source of the error:
        * `[LOGIN-DELAY]': The login delay period hast not yet expired.

        * `[IN-USE]': Authentication succeeded but the mailbox is
          currently in use, possibly by another POP3 session.

   * AUTH-RESP-CODE
     If authentication fails and the POP3 server issues an error
     message beginning with a square bracket, this message will include
     additional information about the source of the error:
        * `[LOGIN-DELAY]': The login delay period hast not yet expired.

        * `[IN-USE]': Authentication succeeded but the mailbox is
          currently in use, possibly by another POP3 session.

        * `[SYS/TEMP]': Temporary system failure; try again later.

        * `[SYS/PERM]': Permanent system failure; ask the administrator.

        * `[AUTH]': Incorrect user name or password or some other
          problem with the user's credentials.

   If TLS is activated for server information mode, the following
information will be printed about the POP3 server's TLS certificate (if
available):
   * Owner information
        * Common Name

        * Organization

        * Organizational unit

        * Locality

        * State or Province

        * Country

   * Issuer information
        * Common Name

        * Organization

        * Organizational unit

        * Locality

        * State or Province

        * Country

   * General
        * Activation time

        * Expiration time

        * SHA1 fingerprint

        * MD5 fingerprint


File: mpop.info,  Node: Filtering,  Next: Server information mode,  Prev: Mail retrieval mode,  Up: Top

10 Filtering
************

There are three filtering commands available. They will be executed in
the following order:

  1. `killsize'

  2. `skipsize'

  3. `filter'

   If a filtering command applies to a mail, the remaining filters will
not be executed.

   The POP3 server must support the POP3 TOP command (*note Server
information mode::) for filtering with a filter command: It is used to
read the mail headers (plus the blank line separating the header from
the body) and pipe them to the filter command.

   Note that, if the filter decides that the mail should be retrieved,
the complete mail has to be downloaded, including the headers, so the
headers will be downloaded twice. This is because there's no way in
POP3 to download just the mail body. Sometimes this overhead surpasses
the savings of the filtering.

   The filter command looks at the mail headers and signals with its
exit code what mpop should do with the mail:
   * 0: retrieve the mail

   * 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 occurred.
The `sysexits.h' error codes may be used to give information about the
kind of the error, but this is optional.

   Since the filter command will be passed to a shell, you can use all
shell command constructs in addition to just calling a script or
program. This allows flexible filter constructs. *Note Filtering with
SpamAssassin::.

   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. The filters use the
size values reported by the POP3 server since they cannot know the
actual size in advance. Thus you cannot rely on _exact_ size filtering.


File: mpop.info,  Node: Examples,  Prev: Server information mode,  Up: Top

11 Examples
***********

* Menu:

* A configuration file::
* Filtering with SpamAssassin::


File: mpop.info,  Node: A configuration file,  Next: Filtering with SpamAssassin,  Up: Examples

11.1 A 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 also known as "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

     # The service runs SpamAssassin, so test each mail for the "X-Spam-Status: Yes"
     # header, and delete all mails with this header before downloading them.
     filter   if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi


     #
     # Set a default account (optional).
     #

     account default : provider1


File: mpop.info,  Node: Filtering with SpamAssassin,  Prev: A configuration file,  Up: Examples

11.2 Filtering with SpamAssassin
================================

Use the following to delete all mails that SpamAssassin classifies as
spam:
     filter "/path/to/spamc -c > /dev/null"
   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, all shell constructs
are usable, so you can also use this directly:
     filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi



Tag Table:
Node: Top609
Node: Introduction1625
Node: Configuration file3562
Ref: defaults4593
Ref: account4729
Ref: host5107
Ref: port5287
Ref: timeout5436
Ref: pipelining5662
Ref: received_header5917
Ref: auth6399
Ref: user6760
Ref: password6873
Ref: passwordeval7542
Ref: ntlmdomain7661
Ref: tls7964
Ref: tls_starttls8352
Ref: tls_trust_file8627
Ref: tls_crl_file9063
Ref: tls_fingerprint9402
Ref: tls_key_file10009
Ref: tls_cert_file10336
Ref: tls_certcheck10639
Ref: tls_force_sslv310895
Ref: tls_min_dh_prime_bits11105
Ref: tls_priorities11525
Ref: delivery12070
Ref: uidls_file14285
Ref: only_new14933
Ref: keep15176
Ref: killsize15371
Ref: skipsize16043
Ref: filter16391
Node: Invocation17915
Ref: Environment / Files18318
Ref: --serverinfo20209
Ref: --pipelining21337
Ref: --received_header21427
Ref: --auth21528
Ref: --user21676
Ref: --passwordeval21763
Ref: --tls-starttls21918
Ref: --tls-trust-file22026
Ref: --tls-crl-file22133
Ref: --tls-fingerprint22253
Ref: --tls-key-file22383
Ref: --tls-cert-file22479
Ref: --tls-certcheck22578
Ref: --tls-force-sslv322705
Ref: --tls-min-dh-prime-bits22795
Ref: --tls-priorities22934
Ref: --quiet23118
Ref: --half-quiet23184
Ref: --all-accounts23253
Ref: --auth-only23327
Ref: --status-only23420
Ref: --only-new23527
Ref: --keep23607
Ref: --killsize23738
Ref: --skipsize23810
Ref: --filter23882
Ref: --delivery24050
Ref: --uidls-file24264
Node: Transport Layer Security24338
Node: Authentication28353
Node: Pipelining34087
Node: Defective POP3 servers35337
Node: Mail retrieval mode36300
Node: Server information mode37977
Node: Filtering41250
Node: Examples43169
Node: A configuration file43339
Node: Filtering with SpamAssassin45224

End Tag Table


Local Variables:
coding: utf-8
End:
