| PERDITION(8) | System Manager's Manual | PERDITION(8) |
perdition - POP3 and IMAP4 proxy server
perdition [options]
perdition.pop3 [options]
perdition.pop3s [options]
perdition.imap4 [options]
perdition.imap4s [options]
perdition.imaps [options]
perdition.managesieve [options]
perdition allows users to connect to a content-free POP3, IMAP4 or ManageSieve server that will redirect them to their real POP3, IMAP4 or ManageSieve server respectively. This enables mail retrieval and sieve management for a domain to be split across multiple real mail servers on a per user basis. This can also be used to as a POP3, IMAP4 and ManageSieve proxy especially in firewall applications. And as a method of migrating users to new servers.
When a connection is made to perdition in POP3 mode, it reads the users authentication credentials and then refers to its popmap to find the real-server that the user's connection should be forwarded to. A connection is made to the real-server and perdition then passes on the authentication credentials. If authentication is successful then perdition pipes data between the end-user and the real-server. If authentication fails then the real-server connection is closed and the client connection is reset to the state it was in on initial connection. That is new authentication credentials are expected.
N.B: No IMAP authentication schemes, other than the LOGIN command are accepted.
When invoked as perdition.pop3, perdition.pop3s, perdition.imap4, perdition.imap4s or perdition.managesieve then perdition will run in POP3, POP3S, IMAP4, IMAP4S or MANAGESIEVE mode respectively, unless overridden on the command line or in the configuration file. perdition.imaps also runs perdition in IMAP4S mode and is provided to get around the truncation of process names in the /proc filesystem on Linux which can cause init scripts to fail to stop perdition correctly.
The valid states are servername_lookup, local_authentication, remote_login and all
servername_lookup: Append the domain to the username for lookup of username in Popmap. Will not take effect if client_server_specification is in effect.
local_authentication: Append the domain to the username for use in local authentication. Only has effect if authenticate_in is in effect.
remote_login: Send the username with the domain appended to the real-server for authentication.
all: Short-Hand for all of above states.
The domain may also have leading levels striped, essentially to convert a hostname to a domain name. The depth of the strip defaults to 1, which would mean that www.au.vergenet.net would become au.vergenet.net. A depth of 2 would cause it to become vergenet.net and so forth. A depth of 0 leaves the name unchanged. The depth and may be specified by appending ",STRIP_DEPTH" to the state. For compatibility reasons the default depth is 1.
e.g. all,2
(the default value for add_domain is "")
In non-inetd mode, connections will only be accepted to the listed servers. If un-set connections will be accepted on all addresses on the listen_port.
(default "")
Note: -d|--debug must be specified for this option to take effect.
The default is derived as follows:
The sysconfig dir ("/etc/perdition" for example) is checked for <basename>.conf. If this is found then it is used. So if perdition is invoked as /usr/sbin/perdition.pop3, and /etc/perdition/perdition.pop3.conf exists then it will be used.
Next the sysconfig dir is checked for peridtion.<protocol>.conf, where protocol is the ASCII representation of the protocol being used, one of "imap4", "imap4s", "pop3", "pop3s" or "managesieve". So if perdition is being run in imap4 mode, and /etc/perdition/perdition.imap4.conf exists, then it is used. Note that the protocol name is lowercase.
Next the sysconfig dir is checked for perdition.conf, if it is found then it is used.
If none of these files are found then no configuration file is used.
This string is taken as a string literal that will be returned when a client issues the CAPABILITY command. As such the capabilities should be space delimited. The default is "IMAP4 IMAP4REV1". However, perdition does support RFC 2088 non-synchronising string literals, if the real servers also support this then the capability may be set to "IMAP4 IMAP4REV1 LITERAL+".
If perdition is running with ssl_mode includes to ssl_listen then the capability STARTTLS will be appended to the list of capabilities if it is not already present. Similarly this capability will be removed from the list of capabilities if present and perdition is not running with an ssl_mode that includes to ssl_listen.
Perdition may also manipulate the capability in IMAP mode to add and remove the LOGINDISABLED capability if the no_login capability is in effect or if the ssl_mode includes tls_listen_force or tls_outgoing_force.
The default is 110, 995, 143, 993 and 4190 for POP3, POP3S, IMAP4, IMAP4S and MANAGESIEVE mode respectively.
fail: log the password on failed connection attempts.
ok: log the password on successful connection attempts.
never: never log the password
always: always log the password
Note: -d|--debug must be specified for this option to take effect.
This string is taken as a string literal that will be returned when a client connects or issues the CAPABILITY command. As such the capabilities should be quoted, using escape char \, and double space delimited.
If perdition is running with ssl_mode includes to ssl_listen then the capability STARTTLS will be appended to the list of capabilities if it is not already present. Similary this capability will be removed from the list of capabilities if present and perdition is not running with an ssl_mode that includes to ssl_listen.
Examples
Two options, each with a value
"\"OPTION1\" \"VALUE\" \"OPTION2\"
\"VALUE\""
Two options, but only one with a value
"\"OPTION1\" \"OPTION2\"
\"VALUE\""
(default ""IMPLEMENTATION" "perdition" "SIEVE" "comparator-i; octet comparator-i;ascii-casemap fileinto reject envelope encoded-character vacation subaddress comparator-i;ascii-numeric relational regex imap4flags copy include variables body enotify environment mailbox date" "SASL" "PLAIN" "NOTIFY" "mailto" "VERSION" "1.19-rc2"")
The capabilities should be delimited by a '.' spaces. Up until perdition 1.18 the delimiter was two spaces, " ". This is now deprecated and it is not valid to mix delimiters.
The default capability is "UIDL.USER".
If perdition is running with ssl_mode includes to ssl_listen then the capability STLS will be appended to the list of capabilities if it is not already present. Similarly this capability will be removed from the list of capabilities it is present and perdition is not running with an ssl_mode that includes to ssl_listen.
\U: Long Username, the entire string supplied by
the end user, less any effects of
--strip_domain.
\u: Short Username, the portion Long Username
before the domain delimiter.
\D: Domain Delimiter, as specified by
--domain_delimiter
\d: Domain the portion Long Username after the
domain delimiter.
\i: Source IP address of the connection
\I: Destination IP address of the connection
\p: Source port of the connection
\P: Destination port of the connection
\\: Literal \
As a ',' is the delimiter between formats, it cannot appear within a format. All other characters other than the escape codes above, and ',' are treated as literals.
Examples
Use the supplied username, the default behaviour
\U
Use the user portion of the supplied username, if this doesn't
work try the domain portion of the supplied username preceded by the
domain delimiter
\u,\D\d
Use the destination IP address
\I
Escape codes interspersed with literals
\u\da_domain,\da_domain
The options below relate to SSL/TLS support. They are not available if perdition is compiled without SSL support.
none: Do not use SSL or TLS for any connections. This is the same as providing no option, the default.
ssl_listen: When listening for incoming connections they will be treated as SSL connections.
ssl_outgoing: Use SSL to connect to real pop/imap servers.
ssl_all: Short-Hand for ssl_listen,ssl_outgoing.
tls_listen: When listening for incoming connections they will be treated as TLS connections.
tls_outgoing: Use TLS to connect to real pop/imap servers.
tls_all: Short-Hand for tls_listen,tls_outgoing.
tls_listen_force: Do not accept plain text authentication. In IMAP4 and IMAP4S mode, the LOGINDISABLED capability until TLS has been initialised by the client issuing a STARTTLS. In all modes mode plain-text authentication is ignored. Also sets tls_listen.
tls_outgoing_force: Do not send authentication information if TLS cannot be negotiated. Also sets tls_outgoing.
tls_all_force: Short-Hand for tls_listen_force,tls_outgoing_force.
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "tlsv1")
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "tlsv1")
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "")
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "")
For information on mechanisms for resolving users to a host and port and information on the -M|--map_library and -m|--map_library_opt flags, please see perditiondb(5).
Note that by specifying an map library no map lookups will occur and all connections will use the -s|--outgoing_server. In this way perdition can be configured as a "pure proxy".
Normally perdition will bind to a port, and listen for connections. The default port is 110 in POP3 mode and 143 in IMAP4 mode, an alternate port can be specified with the -l|--listen_port command line option. In this mode perdition will fork to manage clients.
Stand-Alone Mode: Debian and RPM Installation
In the Debian and RPM distributions perdition can be started and stopped in stand-alone mode using:
/etc/init.d/perdition start
/etc/init.d/perdition stop
Editing /etc/sysconfig/perdition (RPM) or /etc/default/perdition (Debian) allows control of whether perdition will be started in POP3 mode, IMAP4 mode or both (or neither).
The syntax for this file is:
RUN_PERDITION=[yes|no] FLAGS="flags" POP3=[yes|no] POP3_FLAGS="flags" POP3S=[yes|no] POP3S_FLAGS="flags" IMAP4=[yes|no] IMAP4_FLAGS="flags" IMAP4S=[yes|no] IMAP4S_FLAGS="flags"
The file is sourced into the init script so normal bash syntax applies. Blank lines are ignored, as is anything after a # on a line.
e.g.
RUN_PERDITION=yes POP3=on POP3_FLAGS="--ssl_mode tls_listen" POP3S=on IMAP4_FLAGS="--ssl_mode tls_listen" IMAP4=on POP3S_FLAGS="--ssl_mode ssl_listen -p 110" IMAP4S=on IMAP4S_FLAGS="--ssl_mode ssl_listen -p 143"
Perdition can be used in conjunction with inetd. This enables perdition to benefit from tcpd where access can be controlled to some extent using /etc/hosts.allow and /etc/hosts.deny. Sample /etc/inetd.conf entries follow:
pop3 stream tcp nowait root /usr/sbin/tcpd
/usr/sbin/perdition.pop3 -i
pop3s stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdition.pop3s -i
imap2 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdition.imap4 -i
imaps stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdition.imap4s -i
inetd should then be restarted
If perdition has been compiled against libpam, it may be set up to authenticate the user locally once the USER and PASS commands are entered by specifying the -a|--authenticate_in option on the command line. This authentication happens before the connection to the foreign server is made and must succeed for a connection to the foreign server to be made.
This authentication uses PAM and a sample pam configuration file for perdition can be found in etc/pam.d/perdition in the source tree. This should be dropped into /etc/pam.d.
A multi character domain delimiter can be set using the -d|--domain delimiter option. This sets the delimiter used in conjunction with the -S|--strip_domain and -c|--client_server_specification options.
If perdition is invoked with the -c|--client_server_specification flag then the user may optionally specify the server and port that perdition should connect to for the client using the syntax user<delimiter>host[:port].
Example:
IMAP4 0 login henry@that.host:143 POP3 user james@other.host
Perdition allows two idle timeouts to be configured. --authentication_timeout is used before the user has been successfully authenticated with the back-end server. And after that --timeout is used.
The default value for both timeouts is is 1800. A timeout value of 0 means that the timeouts are disabled and clients and back-end servers can idle indefinitely, though in practice a TCP timeout will be in effect.
The greeting that perdition displays when accepting an incoming connection is "+OK POP3 Ready <hostname>" or "* OK IMAP4 Ready <hostname>" in POP3 and IMAP4 modes respectively. If when perdition connects to the back-end server the greeting string matches the greeting string of the perdition process making the connection then it is assumed that perdition is connecting to itself and a "Re-Authentication Failure" is returned to the client.
The format of a line of the configuration file is:
<key> <value>
Key is either a short or long option as per perdition -h|--help, without the leading - or --. Blank lines are ignored, as is anything including and after a # (hash) on a line. If a \ precedes a new line then the lines will be concatenated. IF a \ precedes any other character, including a # (hash) it will be treated as a literal. Anything inside single quotes (') will be treated as a literal. Anything other than a (') inside double quotes (") will be treated as a literal. Whitespace in keys must be escaped or quoted. Whitespace in values need not be escaped or quoted.
Options that do not make sense in the configuration file such as h|help and f|config_file are ignored. Options specified on the command line override the options in this file.
Example configuration File.
# perdition.conf l 110 #Short option used as key group mail #Long option used as key a #Option with no argument
Perdition supports POP before SMTP in both POP3 and IMAP4 mode by logging having logging the following messages:
When a user connects:
Connect: <from_to> [inetd_pid=<pid>]
When a user is authenticated
Auth: <from_to> client-secure=SECURE_STATUS authorisation_id="<authorisation_id>" authentication_id="<authentication_id>" password="<password>" server="<servername>:<port>" protocol=<protocol> server-secure=SECURE_STATUS status=failed...|ok
When a user disconnects
Close: <from_to> authorisation_id="<authorisation_id>" authentication_id="<authentication_id>" received=<bytes> sent=<bytes>
Where:
from_to is <src_ip_address>:<src_port>-><dest_ip_address>:<dest_port>
SECURE_STATUS is one of:
ssl: Uses SSL/TLS from the beginning of the connection. That is, IMAPS or POP3S.
starttls: A STARTTLS or STLS command has been issued and SSL/TLS was subsequently negotiated.
Note that if the message is logged before SSL/TLS negotiation completed then the status will be plaintext. Even if the connection would have used starttls if successful. For example, if connecting to the real-server fails.
plaintext: SSL/TLS is not in use.
By default, logs are logged via syslog using the facility mail. You should inspect /etc/syslog.conf to find where these logs are written. Under Debian these logs will be written to /var/log/mail.log, under Red Hat 7.x these logs will be written to /var/log/maillog, under Solaris 8 these logs will be written to /var/log/syslog. Normally each session will have two perdition log entries. Logs are prepended, depending on syslog with the date, host, and perdition[<pid>]: .
Fatal errors are also logged with a priority of err. In stand-alone mode the startup parameters are logged on initialisation. If the -d|--debug command line option or configuration file directive is used then startup parameters are logged regardless of other configuration directives and in both stand-alone and identd mode additional debugging messages are logged with a priority of debug. As the flag implies, this is useful for debugging but is probably too verbose for production systems. If the -q|--quiet command line option or configuration file directive is used, only errors will be logged. This is overridden by -d|--debug.
Perdition supports using SSLv2 and SSLv3 to encrypt sessions between end users and perdition and sessions between perdition and real servers. SSL may be used for either, both or none of these classes of connections.
The public key and certificate files should be in PEM format. As a quick guide, the files may be generated using openssl with the following command:
openssl req -new -x509 -nodes \
-out perdition.crt.pem -keyout perdition.key.pem -days 365
Perdition can be used in a mixed-mode where the end-users connect to perdition using SSL and then perdition connects to the real-servers using palin-text. Or vice versa. This is achieved using --ssl_mode and at least one of -l|--listen_port and -p|--outgoing_port. When running this kind of configuration -P|--protocol values of IMAP and IMAPS are equivalent and likewise POP3 and POP3S are equivalent.
For example, to accept connections from end-users using POP3S on port 995 (the default POP3S port) and communicate with the real-servers using POP3 on port 110 (the default POP3 port) the following are equivalent.
--ssl_mode=ssl_listen --protocol=POP3S --outgoing_port=110
and
--ssl_mode=ssl_listen --protocol=POP3 --incoming_port=995
Perdition is not able to listen for connections from end-users using POP3/POP3S and communicate with real-servers using IMAP4/IMAP4S or vice-versa.
Lead
Horms <horms@verge.net.au>
Perditiondb Library Authors
Frederic Delchambre <dedel@freegates.be> (MySQL)
Chris Stratford: <chriss@uk.uu.net> (LDAP and Berkeley DB)
Nathan Neulinger <nneul@umr.edu> (NIS)
Contributing Authors
Daniel Roesen <droesen@entire-systems.com>
Clinton Work <work@scripty.com>
Youri <ya@linkline.be>
Jeremy Nelson <jnelson@optusnet.com.au>
Wim Bonis <bonis@solution-service.de>
Arvid Requate <arvid@Team.OWL-Online.DE>
Mikolaj J. Habryn <dichro@rcpt.to>
Ronny Cook <ronny@asiaonline.net>
Geoff Mitchell <g.mitchell@videonetworks.com>
Willi Langenberger <wlang@wu-wien.ac.at>
Matt Prigge <mprigge@pobox.com>
Wolfgang Breyha <wolfgang.breyha@uta.at>
| 12th June 2003 |