\input texinfo	 @c -*-texinfo-*-
@setfilename mpop.info
@documentlanguage en
@documentencoding UTF-8
@include version.texi
@settitle mpop @value{VERSION}

@c Define new indices: for options (op) and commands (cm)
@defcodeindex op
@defcodeindex cm

@finalout
@copying
This manual was last updated @value{UPDATED} for version
@value{VERSION} of mpop.

Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2018, 2019, 2020, 2021, 2022
Martin Lambers

@quotation
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.
@end quotation
@end copying

@dircategory Individual utilities
@direntry
* mpop: (mpop).		A POP3 client.
@end direntry

@titlepage
@title mpop
@subtitle A POP3 client
@subtitle version @value{VERSION}, @value{UPDATED}
@author Martin Lambers (@email{marlam@@marlam.de})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top mpop
@insertcopying
@end ifnottex

@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.
* Mail retrieval mode::			How to retrieve mail.
* Server information mode::		How to obtain information about
					a POP3 server.
* Filtering::				How to filter mails.
* Examples::				Usage examples.
* Minimal POP3 server (mpopd)::		When and how to use mpopd.
@end menu


@node Introduction
@chapter 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), to a maildir folder, or to an mbox file.
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.
@xref{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,
@dots{}).

Normally, a configuration file contains information about which POP3 server to
use and how to use it, but 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:
@itemize
@item Header based mail filtering: filter junk mail before downloading it
@item Delivery to maildir folders, mbox files, Exchange pickup directories,
or a mail delivery agent (MDA)
@item Very fast POP3 implementation, using command pipelining
@item TLS secured connections (including server certificate verification and
the possibility to send a client certificate)
@item Authentication methods USER/PASS, APOP, PLAIN, LOGIN and CRAM-MD5
(and GSSAPI, SCRAM-SHA-1, SCRAM-SHA-256, DIGEST-MD5, and NTLM when GNU SASL is used)
@item Internationalized Domain Names (IDN)
@end itemize


@node Configuration file
@chapter Configuration file

A suggestion for a suitable configuration file can be generated using the
@samp{--configure} option; see @ref{--configure}.
The default configuration file is @code{~/.mpoprc} or
@code{$XDG_CONFIG_HOME/mpop/config}.  Settings in this file can
be changed by command line options.

A configuration file is a simple text file. Empty lines and comment lines
(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 a file name starts with the tilde (~), this tilde will be replaced by
@code{$HOME}.

If a command accepts the argument @samp{on}, it also accepts an empty argument
and treats that as if it was @samp{on}.

Commands are organized in accounts. Each account starts with the @samp{account}
command and defines the settings for one POP3 account.

@xref{Examples}.

@section General commands

@table @samp
@anchor{defaults}
@item defaults
@cmindex defaults
Set defaults. The following commands will set default values for all following
account definitions.
@anchor{account}
@item account @var{name} [ : @var{account}[,@dots{}] ]
@cmindex account
Start a new account definition with the given name. The current default values
are filled in (see @ref{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.
@anchor{eval}
@item eval [@var{cmd}]
@cmindex eval
Replace the current configuration file line with the first line of the output
(stdout) of the command @var{cmd}. This can be used to decrypt settings or to
create them via scripts. For example, @code{eval echo host localhost} replaces
the current line with @code{host localhost}.@*
Note that every @samp{eval} line will be evaluated when the configuration
file is read.@*
Note that for passwords you can also use the @ref{passwordeval} command instead
of @code{eval password cmd}. This has the advantage that the command is only
evaluated if needed.
@anchor{host}
@item host @var{hostname}
@cmindex host
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.
@anchor{port}
@item port @var{number}
@cmindex port
The port that the POP3 server listens on. The default is 110 ("pop3"), unless
TLS without STARTTLS is used, in which case it is 995 ("pop3s").
@anchor{source_ip}
@item source_ip [@var{IP}]
@cmindex source_ip
Set a source IP address to bind the outgoing connection to. Useful only in
special cases on multi-home systems. An empty argument disables this.
@anchor{proxy_host}
@item proxy_host [@var{IP}|@var{hostname}]
@cmindex proxy_host
Use a SOCKS proxy. All network traffic will go through this proxy host,
including DNS queries, except for a DNS query that might be necessary to
resolve the proxy host name itself (this can be avoided by using an IP address
as proxy host name). An empty argument disables proxy usage.
The supported SOCKS protocol version is 5. If you plan to use this with Tor,
see also @ref{Using mpop with Tor}.
@anchor{proxy_port}
@item proxy_port [@var{number}]
@cmindex proxy_port
Set the port number for the proxy host. An empty @samp{number} argument resets
this to the default port, which is 1080 ("socks").
@anchor{socket}
@item socket [@var{socketname}]
@cmindex socket
Set the file name of a unix domain socket to connect to. This overrides
both @samp{host}/@samp{port} and @samp{proxy_host}/@samp{proxy_port}.
@anchor{timeout}
@item timeout (off|@var{seconds})
@cmindex timeout
Set or unset a network timeout, in seconds. The default is 180 seconds. The
argument @samp{off} means that no timeout will be set, which means that the
operating system default will be used.
@anchor{pipelining}
@item pipelining (auto|on|off)
@cmindex pipelining
Enable or disable POP3 pipelining. You should never need to change the default
setting, which is @samp{auto}: mpop enables pipelining for POP3 servers that
advertise this capability, and disables it for all other servers.  Pipelining
can speed up a POP3 session substantially.
@end table

@section Authentication commands

@xref{Authentication}.

@table @samp
@anchor{auth}
@item auth [(on|@var{method})]
@cmindex auth
Choose an authentication method. The default argument @samp{on} chooses a
method automatically.
Accepted methods are
@samp{scram-sha-256-plus}, @samp{scram-sha-1-plus}, @samp{scram-sha-256}, @samp{scram-sha-1},
@samp{user}, @samp{apop}, @samp{plain},
@samp{gssapi}, @samp{external}, @samp{oauthbearer},
@samp{cram-md5}, @samp{digest-md5}, @samp{login}, @samp{ntlm}, and @samp{xoauth2}.
@anchor{user}
@item user [@var{username}]
@cmindex user
Set the user name for authentication. An empty argument unsets the user name.
@anchor{password}
@item password [@var{secret}]
@cmindex password
Set the password for authentication. An empty argument unsets the password.
Consider using the @samp{passwordeval} command or a key ring instead of this
command, to avoid storing cleartext passwords in the configuration file.
@anchor{passwordeval}
@item passwordeval [@var{cmd}]
@cmindex passwordeval
Set the password for authentication to the output (stdout) of the command
@var{cmd}.
This can be used e.g. to decrypt password files on the fly or to query key
rings, and thus to avoid storing cleartext passwords.
@anchor{ntlmdomain}
@item ntlmdomain [@var{ntlmdomain}]
@cmindex ntlmdomain
Set a domain for the @samp{ntlm} authentication method. This is obsolete.
@end table

@section TLS commands

@xref{Transport Layer Security}.

@table @samp
@anchor{tls}
@item tls [(on|off)]
@cmindex tls
Enable or disable TLS (also known as SSL) for secured connections.
@anchor{tls_starttls}
@item tls_starttls [(on|off)]
@cmindex tls_starttls
Choose the TLS variant: start TLS from within the session (@samp{on}, default),
or tunnel the session through TLS (@samp{off}).
@anchor{tls_trust_file}
@item tls_trust_file [@var{file}]
@cmindex tls_trust_file
Activate server certificate verification using a list of trusted Certification
Authorities (CAs). The default is the special value @samp{system}, which selects the
system default. An empty argument disables trust in CAs.
If you select a file, it must be in PEM format, and you should also use
@samp{tls_crl_file}.
@anchor{tls_crl_file}
@item tls_crl_file [@var{file}]
@cmindex tls_crl_file
This sets a certificate revocation list (CRL) file for TLS, to check
for revoked certificates (an empty argument, which is the default, disables this).@*
OCSP is an alternative to CRL files.
When GnuTLS is used, stapled OCSP information will be checked automatically,
and the MustStaple TLS extension is supported, however no manual OCSP queries
will be sent when stapled OCSP information is missing. With other TLS
libraries, behavior may be different.
@anchor{tls_fingerprint}
@item tls_fingerprint [@var{fingerprint}]
@cmindex tls_fingerprint
Set the fingerprint of a single certificate to accept for TLS. This certificate
will be trusted regardless of its contents (this overrides @samp{tls_trust_file}).
The fingerprint should be of type SHA256, but can for backwards compatibility
also be of type SHA1 or MD5 (please avoid this).
The format should be @code{01:23:45:67:@dots{}}.
Use @samp{--serverinfo --tls --tls-certcheck=off --tls-fingerprint=}
to get the server certificate fingerprint.
@anchor{tls_key_file}
@item tls_key_file [@var{file}]
@cmindex tls_key_file
Send a client certificate to the server (use this together with
@samp{tls_cert_file}).
The file must contain the private key of a certificate in PEM format. An empty
argument disables this feature.
@anchor{tls_cert_file}
@item tls_cert_file [@var{file}]
@cmindex tls_cert_file
Send a client certificate to the server (use this together with
@samp{tls_key_file}).
The file must contain a certificate in PEM format. An empty argument disables
this feature.
@anchor{tls_certcheck}
@item tls_certcheck [(on|off)]
@cmindex tls_certcheck
Enable or disable checks of the server certificate. They are enabled by default.@*
Disabling them will override @samp{tls_trust_file} and @samp{tls_fingerprint}.
WARNING: When the checks are disabled, TLS sessions will not be secure!
@anchor{tls_priorities}
@item tls_priorities [@var{priorities}]
@cmindex tls_priorities
Set priorities for TLS session parameters. The default is set by the TLS library and
can be selected by using an empty argument to this command. The interpretation of the
@var{priorities} string depends on the TLS library. Use @samp{--version} to find out
which TLS library you use.@*
For GnuTLS, see the section on Priority Strings in the manual.@*
For libtls, the @var{priorites} string is a space-separated list of parameter strings
prefixed with either @code{PROTOCOLS=}, @code{CIPHERS=}, or @code{ECDHECURVES=}.
These parameter strings will be passed to the functions @samp{tls_config_parse_protocols},
@samp{tls_config_set_ciphers}, and @samp{tls_config_set_ecdhecurves}.
Unrecognized parts of the @var{priorities} string will be ignored. Example:
@code{PROTOCOLS=TLSv1.3 CIPHERS=ECDHE-RSA-AES128-SHA256 ECDHECURVES=P-384}.
@anchor{tls_host_override}
@item tls_host_override [@var{host}]
@cmindex tls_host_override
By default, TLS host verification uses the host name given by the @samp{host} command.
This command allows one to use a different host name for verification. This is only
useful in special cases.
@anchor{tls_min_dh_prime_bits}
@item tls_min_dh_prime_bits [@var{bits}]
@cmindex tls_min_dh_prime_bits
Deprecated, use @samp{tls_priorities} instead.
Set or unset the minimum number of Diffie-Hellman (DH) prime bits accepted 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.
@end table

@section Commands specific to mail retrieval mode

@xref{Mail retrieval mode}.

@table @samp
@anchor{delivery}
@item delivery @var{method} @var{method_arguments@dots{}}
@cmindex delivery
How to deliver messages received from this account.
@itemize
@item delivery mda @var{command}@*
Deliver the mails through a mail delivery agent (MDA).@*
All occurrences of @code{%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 @code{a-z} and
@code{A-Z}, digits @code{0-9}, and any of @code{.@@_-+/}, 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
@code{_}. Nevertheless, you should put @code{%F} into single quotes:
@code{'%F'}.@*
Use @code{delivery mda "/usr/bin/procmail -f '%F' -d $USER"} for the procmail
MDA.@*
Use @code{delivery mda "/usr/sbin/sendmail -oi -oem -f '%F' -- $USER"} to let
your MTA handle the mail.@*
Use @code{delivery mda /usr/local/bin/msmtp --host=localhost --from='%F' --
$USER@@`hostname`.`dnsdomainname`"} to pass the mail to your MTA via SMTP.
@item delivery maildir @var{directory}@*
Deliver the mails to the given maildir directory. The directory must exist and
it must have the maildir subdirectories @samp{cur}, @samp{new}, and @samp{tmp};
mpop will not create directories. This delivery type only works on file systems
that support hard links.
@item delivery mbox @var{mbox-file}@*
Deliver the mails to the given file in mbox format. The file will be locked
with @code{fcntl(2)}. mpop uses the MBOXRD mbox format variant; see the
documentation of the mbox format.
@item delivery exchange @var{directory}@*
Deliver the mails to the given Exchange pickup directory. The directory must
exist.
@end itemize
If the delivery method needs to parse the mail headers for an envelope from
address (the mda method if the command contains @code{%F}, and the mbox method),
then it needs to create a temporary file to store the mail headers (but not the
body).
@anchor{uidls_file}
@item uidls_file @var{filename}
@cmindex uidls_file
The file to store UIDLs in. These are needed to identify new messages.
@code{%U} in the filename will be replaced by the username of the current
account. @code{%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 @code{~/.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.
@anchor{only_new}
@item only_new [(on|off)]
@cmindex only_new
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.
@anchor{keep}
@item keep [(on|off)]
@cmindex keep
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.
@anchor{killsize}
@item killsize (off|@var{size})
@cmindex killsize
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. @xref{Filtering}.@*
When @samp{killsize} is set to 0 and @samp{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.
@anchor{skipsize}
@item skipsize (off|@var{size})
@cmindex skipsize
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. @xref{Filtering}.
@anchor{filter}
@item filter [@var{COMMAND}]
@cmindex filter
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 @ref{Server information mode}. An empty argument
disables filtering.@*
All occurrences of @code{%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 @code{a-z} and
@code{A-Z}, digits @code{0-9}, and any of @code{.@@_-+/}, 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
@code{_}. Nevertheless, you should put @code{%F} into single quotes:
@code{'%F'}.@*
All occurrences of @code{%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:
@itemize
@item 0: proceed normally; no special action
@item 1: delete the mail; do not retrieve it
@item 2: skip the mail; do not retrieve it
@end itemize
Return codes greater than or equal to 3 mean that an error occurred.  The
@code{sysexits.h} error codes may be used to give information about the kind of
the error, but this is not necessary. @xref{Filtering}.
@anchor{received_header}
@item received_header [(on|off)]
@cmindex received_header
Enable or disable adding a 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.
@end table


@node Invocation
@chapter Invocation

@section Synopsis

@itemize
@item Mail retrieval mode (default):@*
@code{mpop [@var{option}@dots{}] [--] [@var{account}@dots{}]}@*
@item Configuration mode:@*
@code{mpop --configure @var{mailaddress}}@*
@item Server information mode:@*
@code{mpop [@var{option}@dots{}] --serverinfo [@var{account}@dots{}]}@*
@end itemize

mpop is usually run with one or more accounts as parameters. If no account
is provided, an account named @samp{default} is used if it exist. Alternatively,
@code{mpop -a} will use all accounts defined in the configuration file.

This can be automated by running mpop from @code{cron(8)}.

@section Exit code

The standard exit codes from @code{sysexits.h} are used.

@anchor{Files}
@section Files
@table @samp
@item @code{~/.mpoprc} or @code{$XDG_CONFIG_HOME/mpop/config}.
The default user configuration file.
@item @code{~/.mpop_uidls}
Default directory to store UIDLs files in.
@item @code{~/.netrc} and @code{SYSCONFDIR/netrc}
The @code{netrc} file contains login information. Before prompting for a
password, msmtp will search it in ~/.netrc and SYSCONFDIR/netrc.
@end table

@anchor{Environment}
@section Environment
@table @samp
@item @code{$USER}, @code{$LOGNAME}
These variables override the user's login name. @code{$LOGNAME} is only used if
@code{$USER} is unset. The user's login name is used for @code{Received}
headers.
@end table

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

@subsection General options
@table @samp
@item --version
@opindex --version
Print version information, including information about the libraries used.
@item --help
@opindex --help
Print help.
@item -P
@itemx --pretend
@opindex -P
@opindex --pretend
Print the configuration settings that would be used, but do not take further
action.  An asterisk ('*') will be printed instead of the password.
@item -d
@itemx --debug
@opindex -d
@opindex --debug
Print lots of debugging information, including the whole conversation with the
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 @option{--half-quiet}, because the debugging output would
otherwise interfere with the progress output.
@end table

@subsection Changing the mode of operation
@table @samp
@anchor{--configure}
@item --configure=@var{mailaddress}
@opindex --configure
Generate a configuration for the given mail address and print it. This can be
modified or copied unchanged to the configuration file.
Note that this only works for mail domains that publish appropriate SRV records;
see RFC 8314.
@anchor{--serverinfo}
@item -S
@itemx --serverinfo
@opindex -S
@opindex --serverinfo
Print information about the POP3 server and exit. This includes information
about supported features (pipelining, authentication methods, TOP command,
@dots{}), about parameters (time for which mails will not be deleted, minimum
time between logins, @dots{}), and about the TLS certificate (if TLS is
active).
@xref{Server information mode}.
@end table

@subsection Configuration options
Most options in this category correspond to a configuration file command.
Please refer to @ref{Configuration file} for detailed information.
@table @samp
@item -C @var{filename}
@itemx --file=@var{filename}
@opindex -C
@opindex --file
Use the given file instead of @code{~/.mpoprc} or
@code{XDG_CONFIG_HOME/mpop/config} as the configuration file.
@item --host=@var{hostname}
@opindex --host
Use this 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.
@item --port=@var{number}
@opindex --port
Set the port number. @xref{port}.
@item --source-ip=[@var{IP}]
@opindex --source-ip
Set or unset an IP address to bind the socket to. @xref{source_ip}.
@item --proxy-host=[@var{IP}|@var{hostname}]
@opindex --proxy-host
Set or unset a SOCKS proxy to use. @xref{proxy_host}.
@item --proxy-port=[@var{number}]
@opindex --proxy-port
Set or unset a port number for the proxy host. @xref{proxy_port}.
@item --socket=[@var{socketname}]
@opindex --socket
Set or unset a local unix domain socket name to connect to. @xref{socket}.
@item --timeout=(off|@var{seconds})
@opindex --timeout
Set or unset a network timeout, in seconds. @xref{timeout}.
@anchor{--pipelining}
@item --pipelining=(auto|on|off)
@opindex --pipelining
Enable or disable POP3 pipelining. @xref{pipelining}.
@anchor{--received_header}
@item --received-header[=(on|off)]
@opindex --received-header
Enable or disable the Received header. @xref{received_header}.
@anchor{--auth}
@item --auth[=(on|@var{method})]
@opindex --auth
Set the authentication method to automatic (with @samp{on}) or manually choose an
authentication method. @xref{auth}.
@anchor{--user}
@item --user=[@var{username}]
@opindex --user
Set or unset the user name for authentication. @xref{user}.
@anchor{--passwordeval}
@item --passwordeval=[@var{eval}]
@opindex --passwordeval
Evaluate password for authentication. @xref{passwordeval}.
@item --tls[=(on|off)]
@opindex --tls
Enable or disable TLS/SSL. @xref{tls}.
@anchor{--tls-starttls}
@item --tls-starttls[=(on|off)]
@opindex --tls-starttls
Enable or disable STARTTLS for TLS. @xref{tls_starttls}.
@anchor{--tls-trust-file}
@item --tls-trust-file=[@var{file}]
@opindex --tls-trust-file
Set or unset a trust file for TLS. @xref{tls_trust_file}.
@anchor{--tls-crl-file}
@item --tls-crl-file=[@var{file}]
@opindex --tls-crl-file
Deprecated. Set or unset a certificate revocation list (CRL) file for TLS.
@xref{tls_crl_file}.
@anchor{--tls-fingerprint}
@item --tls-fingerprint=[@var{fingerprint}]
@opindex --tls-fingerprint
Set ot unset the fingerprint of a trusted TLS certificate.
@xref{tls_fingerprint}.
@anchor{--tls-key-file}
@item --tls-key-file=[@var{file}]
@opindex --tls-key-file
Set or unset a key file for TLS. @xref{tls_key_file}.
@anchor{--tls-cert-file}
@item --tls-cert-file=[@var{file}]
@opindex --tls-cert-file
Set or unset a cert file for TLS. @xref{tls_cert_file}.
@anchor{--tls-certcheck}
@item --tls-certcheck[=(on|off)]
@opindex --tls-certcheck
Enable or disable server certificate checks for TLS.
@xref{tls_certcheck}.
@anchor{--tls-priorities}
@item --tls-priorities=[@var{priorities}]
@opindex --tls-priorities
Set or unset TLS priorities. @xref{tls_priorities}.
@anchor{--tls-host-override}
@item --tls-host-override=[@var{host}]
@opindex --tls-host-override
Set or unset override for TLS host verification. @xref{tls_host_override}.
@anchor{--tls-min-dh-prime-bits}
@item --tls-min-dh-prime-bits=[@var{bits}]
@opindex --tls-min-dh-prime-bits
Deprecated, use @samp{--tls-priorities} instead.
Set or unset minimum bit size of the Diffie-Hellman (DH) prime.
@xref{tls_min_dh_prime_bits}.
@end table

@subsection Options specific to mail retrieval mode
@table @samp
@anchor{--quiet}
@item -q
@itemx --quiet
@opindex -q
@opindex --quiet
Do not print status or progress information.
@anchor{--half-quiet}
@item -Q
@itemx --half-quiet
@opindex -Q
@opindex --half-quiet
Print status but not progress information.
@anchor{--all-accounts}
@item -a
@itemx --all-accounts
@opindex -a
@opindex --all-accounts
Query all accounts in the configuration file.
@anchor{--auth-only}
@item -A
@itemx --auth-only
@opindex -A
@opindex --auth-only
Authenticate only; do not retrieve mail. Useful for SMTP-after-POP.
@anchor{--status-only}
@item -s
@itemx --status-only
@opindex -s
@opindex --status-only
Print number and size of mails in each account only; do not retrieve mail.
@anchor{--only-new}
@item -n
@itemx --only-new[=(on|off)]
@opindex --only-new
Process only new messages. @xref{only_new}.
@anchor{--keep}
@item -k
@itemx --keep[=(on|off)]
@opindex --keep
Do not delete mails from POP3 servers, regardless of other options or settings.
@xref{keep}.
@anchor{--killsize}
@item --killsize=(off|@var{size})
@opindex --killsize
Set or unset kill size. @xref{killsize}.
@anchor{--skipsize}
@item --skipsize=(off|@var{size})
@opindex --skipsize
Set or unset skip size. @xref{skipsize}.
@anchor{--filter}
@item --filter=[@var{command}]
@opindex --filter
Set a filter which will decide whether to retrieve, skip, or delete each mail by
investigating the mail's headers. @xref{filter}.
@anchor{--delivery}
@item --delivery=@var{method},@var{method_arguments@dots{}}
@opindex --delivery
How to deliver messages received from this account. @xref{delivery}. Note that a
comma is used instead of a blank to separate the method from its arguments.
@anchor{--uidls-file}
@item --uidls-file=@var{filename}
@opindex --uidls-file
File to store UIDLs in. @xref{uidls_file}.
@end table


@node Transport Layer Security
@chapter Transport Layer Security

Transport Layer Security (TLS)
"@dots{} 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" (quote from RFC2246).

A server can use TLS in one of two modes:
@itemize
@item Via a STARTTLS command@*
The session starts with the normal protocol initialization, and TLS is then
started using the protocol's STARTTLS command.
@item Immediately@*
TLS is initialized before the normal protocol initialization. This requires a
separate port.
@end itemize
The first mode is the default, but you can switch to the second mode by disabling
@ref{tls_starttls}.

When TLS is started, the server sends a certificate to identify itself. To
verify the server identity, a client program is expected to check that the
certificate is formally correct and that it was issued by a Certificate
Authority (CA) that the user trusts. (There can also be certificate chains with
intermediate CAs.)

The list of trusted CAs is specified using the @ref{tls_trust_file} command.
The default value ist @samp{system} and chooses the system-wide default, but you can
also choose the trusted CAs yourself.

A fundamental problem with this is that you need to trust CAs.
Like any other organization, a CA can be incompetent, malicious, subverted by
bad people, or forced by government agencies to compromise end users without
telling them. All of these things happened and continue to happen worldwide.
The idea to have central organizations that have to be trusted for your
communication to be secure is fundamentally broken.

Instead of putting trust in a CA, you can choose to trust only a single
certificate for the server you want to connect to. For that purpose, specify
the certificate fingerprint with @ref{tls_fingerprint}. This makes sure that no
man-in-the-middle can fake the identity of the server by presenting you a
fraudulent certificate issued by some CA that happens to be in your trust list.
However, you have to update the fingerprint whenever the server certificate
changes, and you have to make sure that the change is legitimate each time,
e.g. when the old certificate expired. This is inconvenient, but it's the price
to pay.

Information about a server certificate can be obtained with @samp{--serverinfo
--tls --tls-certcheck=off}. This includes the issuer CA of the certificate (so
you can trust that CA via @samp{tls_trust_file}), and the fingerprint of the
certificate (so you can trust that particular certificate via
@samp{tls_fingerprint}).
@xref{Server information mode}.

If you need to fine tune TLS parameters, have a look at the
@ref{tls_priorities} command.

@anchor{Client Certificates}
@section Client Certificates

TLS also allows the server to verify the identity of the client. For this
purpose, the client has to present a certificate issued by a CA that the server
trusts. To present that certificate, the client also needs the matching key
file. You can set the certificate and key files using @ref{tls_cert_file} and
@ref{tls_key_file}. This mechanism can also be used to authenticate users, so
that traditional user / password authentication is not necessary anymore. See the
EXTERNAL mechanism in @ref{Authentication}.

@example
# Enable TLS
tls on
# Enable TLS client certificates
tls_cert_file /path/to/client_cert
tls_key_file /path/to/client_key
# Enable authentication via the EXTERNAL mechanism (optional; depends on server)
# The user name is empty because the server should get it from the client cert
auth external
user ""
@end example

You can also use client certificates stored on some external authentication
device by specifying GnuTLS device URIs in @ref{tls_cert_file} and
@ref{tls_key_file}. You can find the correct URIs using @code{p11tool
--list-privkeys --login} (p11tool is bundled with GnuTLS). If your device
requires a PIN to access the data, you can specify that using one of the
password mechanisms (e.g. @ref{passwordeval}, @ref{password}). 

@example
tls_cert_file pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=00000000;token=PIV_II%20%28PIV%20Card%20Holder%20pin%29;id=%01;object=Certificate%20for%20PIV%20Authentication;type=cert
tls_key_file  pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=00000000;token=PIV_II%20%28PIV%20Card%20Holder%20pin%29;id=%01;object=PIV%20AUTH%20key;type=private
passwordeval  gpg2 --no-tty -q -d ~/.smart-card-pin.gpg
@end example


@node Authentication
@chapter Authentication

POP3 servers require a client to authenticate before retrieving mail.

Usually a user name and a password are used for authentication. The user name
specified in the configuration file with the @ref{user} command. There are five
different methods to specify the password:
@enumerate
@item Add the password to the system key ring.@*
Currently supported key rings are the Gnome key ring and the Mac OS X Keychain.
For the Gnome key ring, use the command @samp{secret-tool} (part of Gnome's
libsecret) to store passwords:
@example
$ secret-tool store --label=mpop \
  host pop.freemail.example \
  service pop3 \
  user joe.smith
@end example
On Mac OS X, use the following command:
@example
security add-internet-password -s pop.freemail.example -r pop3 -a joe.smith -w
@end example
In both examples, replace pop.freemail.example with the POP3 server name, and
joe.smith with your user name.
@item Store the password in an encrypted files, and use @ref{passwordeval}
to specify a command to decrypt that file, e.g. using GnuPG. @xref{Examples}.
@item Store the password in the configuration file using the @ref{password} command.
(Usually it is not considered a good idea to store passwords in cleartext files.
If you do it anyway, you must make sure that the file can only be read by yourself.)
@item Store the password in @file{~/.netrc}. This method is probably obsolete.
@item Type the password into the terminal when it is required.
@end enumerate
It is recommended to use method 1 or 2.

Multiple authentication methods exist. Most servers support only some of them.

The following user / password methods are supported:
@itemize
@item @samp{SCRAM-SHA-1} and @samp{SCRAM-SHA-1-PLUS}@*
A method that avoids cleartext passwords and requires the server to prove that
it is in posession of the (hashed and salted) password, which prevents some
man-in-the-middle-attacks. The @samp{-PLUS} variant additionally uses TLS channel
binding information for even better security guarantees.
@item @samp{SCRAM-SHA-256} and @samp{SCRAM-SHA-256-PLUS}@*
Same as the SCRAM-SHA-1 methods, but with a stronger hash function.
@item @samp{USER}@*
A simple cleartext method supported by all servers.
@item @samp{PLAIN}@*
Another simple cleartext method supported by almost all servers.
@item @samp{APOP}@*
An obsolete method that avoids cleartext passwords, but is not considered
secure anymore.
@item @samp{CRAM-MD5}@*
An obsolete method that avoids cleartext passwords, but is not considered
secure anymore.
@item @samp{DIGEST-MD5}@*
An overcomplicated obsolete method that avoids cleartext passwords, but is not
considered secure anymore.
@item @samp{LOGIN}@*
A non-standard cleartext method similar to (but worse than) PLAIN.
@item @samp{NTLM}@*
An obscure non-standard method that is now considered broken. It sometimes requires
a special domain parameter passed via @ref{ntlmdomain}. Do not use it.
@end itemize

If no method is specified, mpop will autoselect one based on security
benefits.  With TLS, the order is @samp{SCRAM-SHA-256-PLUS},
@samp{SCRAM-SHA-1-PLUS}, @samp{SCRAM-SHA-256}, @samp{SCRAM-SHA-1},
@samp{PLAIN}, @samp{APOP}, @samp{USER}, followed by some of the obsolete methods if nothing else is
available. Without TLS, only @samp{SCRAM-SHA-256} and @samp{SCRAM-SHA-1}
are considered.

There are currently three authentication methods that are not based on user /
password information and have to be chosen manually:
@itemize
@item @samp{OAUTHBEARER} or its predecessor @samp{XOAUTH2}@*
An OAuth2 token from the mail provider is used as the password.
See the documentation of your mail provider for details on how to get this
token. The @samp{passwordeval} command can be used to pass the regularly changing
tokens into mpop from a script or an environment variable.
@item @samp{EXTERNAL}@*
The authentication happens outside of the protocol, typically by sending a TLS
client certificate (see @ref{Client Certificates}).@*
The EXTERNAL method merely confirms that this authentication succeeded; it does
not perform the authentication. Thus it may not be necessary to use it for
authentication to succeed, and if the server does not support the EXTERNAL
method, this does not mean that it does not support authentication with TLS
client certificates.
@item @samp{GSSAPI}@*
With this method, the Kerberos framework takes care of secure authentication.
Only a user name is required.
@end itemize

It depends on the underlying authentication library and its version whether a
particular method is supported or not. Use @option{--version} to find out which
methods are supported by your version.


@node Mail retrieval mode
@chapter 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 @ref{delivery} command
or @ref{--delivery} option.

While retrieving the mail, mpop displays approximate progress information,
which can be turned off with the @ref{--half-quiet} or @ref{--quiet} options.

If the delivery succeeded, the mail is deleted from the POP3 server by default.
The @ref{keep} command and @ref{--keep} option prevent the deletion of mails.
Some POP3 servers will delete mails without any user interaction. See EXPIRE in
@ref{Server information mode}. Mpop can do nothing about that.

If you do not want to download certain mails, but skip them or delete them
directly, you can do filtering based on the mail headers. @xref{Filtering}.

If you just want to know if you have new mails (and how many), use the
@ref{--status-only} option.

If you just want to authenticate to the POP3 server, but do not want to look at
your mails, use the @ref{--auth-only} option. 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 for example if the delivery method transmits the mail to an SMTP
server, but can be disabled with the @ref{received_header} command. Mpop does
not change the contents of the mail in any other way.


@node Server information mode
@chapter 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:
@itemize
@item IMPLEMENTATION@*
The implementation string of the POP3 server.
@item CAPA@*
Support for the POP3 CAPA command. The server sends a list of its capabilities
in response to this command.
@item PIPELINING@*
Support for POP3 pipelining. @xref{pipelining}.
@item TOP@*
Support for the POP3 TOP command. This is needed for header based filtering to
work. @xref{Filtering}.
@item UIDL@*
Support for the POP3 UIDL command. This is needed to distinguish between new and
already retrieved messages.
@item 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.
@item EXPIRE@*
The time after which old mails are deleted by the POP3 server.
@itemize
@item NEVER: The POP3 server will not delete mail without the user requesting
it.
@item 0: The POP3 server will not keep mails; all mails will be deleted after
they have been downloaded, regardless of the user's wishes.
@item @var{number}: The number of days that the POP3 server will keep mails
before deleting them without user interaction.
@end itemize
@item STARTTLS@*
@xref{Transport Layer Security}.
@item AUTH@*
@xref{Authentication}.
@item 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:
@itemize
@item @code{[LOGIN-DELAY]}: The login delay period hast not yet expired.
@item @code{[IN-USE]}: Authentication succeeded but the mailbox is currently
in use, possibly by another POP3 session.
@end itemize
@item 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:
@itemize
@item @code{[LOGIN-DELAY]}: The login delay period hast not yet expired.
@item @code{[IN-USE]}: Authentication succeeded but the mailbox is currently
in use, possibly by another POP3 session.
@item @code{[SYS/TEMP]}: Temporary system failure; try again later.
@item @code{[SYS/PERM]}: Permanent system failure; ask the administrator.
@item @code{[AUTH]}: Incorrect user name or password or some other problem with
the user's credentials.
@end itemize
@end itemize

If TLS is activated for server information mode, the following information will
be printed about the POP3 server's TLS certificate (if available):
@itemize
@item Owner information
@itemize
@item Common Name
@item Organization
@item Organizational unit
@item Locality
@item State or Province
@item Country
@end itemize
@item Issuer information
@itemize
@item Common Name
@item Organization
@item Organizational unit
@item Locality
@item State or Province
@item Country
@end itemize
@item General
@itemize
@item Activation time
@item Expiration time
@item SHA256 fingerprint
@item SHA1 fingerprint (deprecated)
@end itemize
@end itemize


@node Filtering
@chapter Filtering

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

@enumerate
@item @samp{killsize}
@item @samp{skipsize}
@item @samp{filter}
@end enumerate

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

The POP3 server must support the POP3 TOP command
(@ref{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:
@itemize
@item 0: retrieve the mail
@item 1: delete the mail; do not retrieve it
@item 2: skip the mail; do not retrieve it
@end itemize
Return codes greater than or equal to 3 mean that an error occurred.
The @code{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. @xref{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 @emph{exact} size filtering.


@node Examples
@chapter Examples

@menu
* A configuration file::
* Filtering with SpamAssassin::
* Using mpop with Tor::
@end menu

@node A configuration file
@section A configuration file

@example
# Example for a user configuration file ~/.mpoprc
#
# This file focusses on TLS, authentication, and the mail delivery method.
# Features not used here include mail filtering, timeouts, SOCKS proxies,
# TLS parameters, and more.


# Set default values for all following accounts.
defaults

# Always use TLS.
tls on

# Set a list of trusted CAs for TLS. The default is to use system settings, but
# you can select your own file.
#tls_trust_file /etc/ssl/certs/ca-certificates.crt

# Deliver mail to an MBOX mail file:
delivery mbox ~/Mail/inbox
# Deliver mail to a maildir folder:
#delivery maildir ~/Mail/incoming
# Deliver mail via procmail:
#delivery mda "/usr/bin/procmail -f '%F' -d $USER"
# Deliver mail via the local SMTP server:
#delivery mda "/usr/bin/msmtp --host=localhost --from='%F' -- $USER"
# Deliver mail to an Exchange pickup directory:
#delivery exchange c:\exchange\pickup

# Use an UIDLS file in ~/.local/share instead of ~/.mpop_uidls
uidls_file ~/.local/share/%U_at_%H


# A freemail service
account freemail

# Host name of the POP3 server
host pop.freemail.example

# As an alternative to tls_trust_file, you can use tls_fingerprint
# to pin a single certificate. You have to update the fingerprint when the
# server certificate changes, but an attacker cannot trick you into accepting
# a fraudulent certificate. Get the fingerprint with
# $ mpop --serverinfo --tls --tls-certcheck=off --host=pop.freemail.example
#tls_fingerprint 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33

# Authentication. The password is given using one of five methods, see below.
user joe.smith

# Password method 1: Add the password to the system keyring, and let mpop get
# it automatically. To set the keyring password using Gnome's libsecret:
# $ secret-tool store --label=mpop \
#   host pop.freemail.example \
#   service pop3 \
#   user joe.smith

# Password method 2: Store the password in an encrypted file, and tell mpop
# which command to use to decrypt it. This is usually used with GnuPG, as in
# this example. Usually gpg-agent will ask once for the decryption password.
passwordeval gpg2 --no-tty -q -d ~/.mpop-password.gpg

# Password method 3: Store the password directly in this file. Usually it is not
# a good idea to store passwords in cleartext files. If you do it anyway, at
# least make sure that this file can only be read by yourself.
#password secret123

# Password method 4: Store the password in ~/.netrc. This method is probably not
# relevant anymore.

# Password method 5: Do not specify a password. Mpop will then prompt you for
# it. This means you need to be able to type into a terminal when mpop runs.


# A second mail box at the same freemail service
account freemail2 : freemail
user joey


# The POP3 server of your ISP
account isp
host mail.isp.example
auth on
user 12345
# Your ISP 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
account default : freemail
@end example


@node Filtering with SpamAssassin
@section Filtering with SpamAssassin

Use the following to delete all mails that SpamAssassin classifies as spam:
@example
filter "/path/to/spamc -c > /dev/null"
@end example
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:
@example
#!/bin/sh
if [ "`grep "^X-Spam-Status: Yes"`" ]; then
    exit 1  # kill this message
else
    exit 0  # proceed normally
fi
@end example
Since the filter command is passed to a shell, all shell constructs are usable,
so you can also use this directly:
@example
filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi
@end example


@node Using mpop with Tor
@section Using mpop with Tor
Use the following settings:
@example
proxy_host 127.0.0.1
proxy_port 9050
tls on
@end example
Use an IP address as proxy host name, so that mpop does not leak a DNS query
when resolving it.@*
TLS is required to prevent exit hosts from reading your POP3 session. You also
need @ref{tls_trust_file} or @ref{tls_fingerprint} to check the server
identity.


@node Minimal POP3 server (mpopd)
@chapter Minimal POP3 server (mpopd)

Mpopd is a minimal POP3 server that delivers mails from a local mailbox in maildir
format. It can be used by end users as a way to handle incoming mail via mpop with
mail clients that insist on using POP3 (see @ref{Example using mpopd to
handle incoming mail for a POP3-based mail client}).

Mpopd listens on 127.0.0.1 port 1100 by default, but can also run without its
own network sockets in inetd mode, where it handles a single POP3 session on
standard input / output.

To prevent abuse, mpopd will allow only a limited number of concurrent POP3
sessions, and if an authentication failure occurrs, future authentication
requests in any POP3 session will (for a limited duration) only be answered
after a small delay.

Mpopd works fine with other programs delivering additional mails into the
maildir folders it serves via POP3, but it expects to be the only program to
remove or alter mails in these folders. You can e.g. use mpop to deliver new
mails into the maildir folder, but you cannot use a mail client to work on the
maildir folder at the same time as mpopd.

Mpopd handles the following options:
@table @samp
@item --version
Print version information
@item --help
Print help.
@item --inetd
Start single POP3 session on stdin/stdout
@item --interface=@var{ip}
Listen on the given IPv6 or IPv4 address instead of 127.0.0.1
@item --port=@var{number}
Listen on the given port number instead of 1100
@item --log=@var{none}|@var{syslog}|@var{filename}
Set logging: none (default), syslog, or logging to the given file.
@item --auth=@var{user}[,@var{passwordeval}]
Require authentication with this user name. The password will be
retrieved from the given @var{passwordeval} command (this works 
just like @ref{passwordeval} in msmtp) or, if none is given,
from the key ring or, if that fails, from a prompt.
@item --maildir=@var{dir}
Use this maildir as the mailbox.
@end table

@node Example using mpopd to handle incoming mail for a POP3-based mail client
@section Example: using mpopd to handle incoming mail for a POP3-based mail client

Some mail clients cannot get incoming mail from local files and
instead insist on using a POP3 server. You can configure mpopd to be that
POP3 server and serve your incoming mail from a local maildir folder.

(Similarly, some mail clients cannot send outgoing mail via a program such
as msmtp and instead insist on using an SMTP server.
You can configure msmtpd to be that SMTP
server and hand the mail over to msmtp. See the
@url{https://marlam.de/msmtp/msmtp.html#Example_003a-using-msmtpd-to-handle-outgoing-mail-for-an-SMTP_002dbased-mail-client, corresponding section in the msmtp manual}.)

For this purpose, mpopd should listen on an unprivileged port, e.g. 1100 (the default).
A mailbox is defined using first the @samp{--auth} option to set a user name and password
and then using the @samp{--maildir} option to specify the maildir folder that holds the incoming mail.
Multiple such option pairs can be used to define multiple mailboxes, e.g. from different remote mail accounts.
Programs such as mpop can deliver new mail into the maildir folders at any time, but as long as mpopd is
running no other programs may alter or remove mails from these folders.

Let's use the user name @var{mpopd-user}. You have two options to manage the password:
@enumerate
@item Store the password in your key ring, e.g. with
@example
secret-tool store --label=mpopd host localhost service pop3 user mpopd-user
@end example
In this case, use the mpopd option @samp{--auth=mpopd-user}.
@item Store the password in an encrypted file and use the passwordeval
mechanism. Example for gpg:
@example
mpopd ... --auth=mpopd-user,'gpg -q -d ~/.mpopd-password.gpg'
@end example
@end enumerate

The complete command then is (using the keyring):
@example
mpopd --auth=mpopd-user --maildir=/path/to/your/maildir/folder
@end example

The mail client software must then be configured to use @samp{localhost} at
port @samp{1100} for incoming mail via POP3, and to use authentication with
user @samp{mpopd-user} and the password you chose. The mail client will
probably complain that the POP3 server does not support TLS, but in this
special case that is ok since all communication between your mail client and
mpopd will stay on the local machine.

@bye
