NAME
perdition - POP3 and IMAP4 proxy server
SYNOPSIS
perdition [options]
perdition.pop3 [options]
perdition.pop3s [options]
perdition.imap4 [options]
perdition.imap4s [options]
perdition.imaps [options]
DESCRIPTION
perdition allows users to connect to a content-free POP3 or IMAP4
server that will redirect them to their real POP3 or IMAP4 server
respectively. This enables mail retrieval 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 or IMAP4 proxy especially in firewall
applications.
When a connection is made to perdition in POP3 mode, it reads the USER
and PASS commands 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 enters the USER and PASS
commands. 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 USER and PASS
commands are expected. Similarly in IMAP4 mode, perdition accepts the
LOGIN command and passes the username and password onto the real-server
or authentication.
No IMAP authentication schemes, other than the LOGIN command are
accepted.
When invoked as perdition.pop3, perdition.pop3s, perdition.imap4 or
perdition.imap4s then perdition will run in POP3, POP3S, IMAP4 or
IMAP4S 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.
OPTIONS
-A|--add_domain STATE[,STATE...][,STRIP_DEPTH]:
Appends a domain to the USER based on the IP address connected
to in given state(s). The domain name to append will be the
reverse-lookup of the IP address connected to. If there is no
reverse lookup for this IP address, then a domain will not be
appended. Probably the easiest way to enforce this mapping is to
add entries to /etc/hosts.
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 "")
--authenticate_timeout:
Idle timeout in seconds used while the user is unauthenticated.
Zero for infinite timeout.
-a, --authenticate_in:
User is authenticated by perdition before connection to back-end
server is made. Only available if perdition is compiled with pam
support.
-B, --no_bind_banner:
If bind_address is specified, then the address will be resolved
and the reverse-lookup of this will be used in the greeting.
This option disables this behaviour an reverts to using the
uname to derive the hostname for the greeting.
-b, --bind_address SERVER[,SERVER...]:
Bind to these addresses and ports. interfaces with this address.
Format is as per the --outgoing_server option. If the port is
ommitted, then the listen_port will be used.
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 "")
-C|--connection_logging:
Log interaction between clients, perdition and servers during
authentication phase.
Note: -d|--debug must be specified for this option to take
effect.
--connect_relog SECONDS:
How often to relog the connection. For use in conjunction with
POP and IMAP before SMTP. If zero then the connection will not
be reloged.
(default 300)
-c, --client_server_specification:
Allow USER of the form user<delimiter>server[:port] to specify
the server and port for a user.
-D, --domain_delimiter STRING:
Delimiter between username and domain.
(default "@")
-d, --debug:
Turn on verbose debugging.
-e, --explicit_domain STRING:
With -A, use STRING as the default domain rather than deriving
from the IP address connected to.
(default NULL)
-F, --log_facility FACILITY:
Facility to log to. If the facility has a leading ’/’ then it
will be treated as a file. If is "-" or "+" then log to stdout
or stderr respectively. Otherwise it is assumed to be the name
of a syslog facility. See syslog.conf(5) for valid syslog
facility names.
(default "mail")
Notes: If an error occurs before options are read it may be
logged to stderr. If stdout or stderr is specified as the
facility, then the process will not fork and detach from the
terminal.
-f, --config_file FILENAME:
Name of config file to read. Command line options override
options set in config file.
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", or "pop3s". 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.
-g, --group GROUP:
Group to run as.
(default "nobody")
-h, --help:
Display this message
-I, --capability, --pop_capability, --imap_capability STRING:
Capabilities for the protocol.
When using a POP3 based protocol, the capabilities should be
delimited by two spaces. This is because the capabilities
themselves may contain single spaces. The default is "UIDL
USER".
When using an IMAP4 based protocol, 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 listening for TLS connections then the
capability STLS for POP3 or STARTTLS for IMAP4 will be appended
to the list of capabilities if it is not already present.
Similarly these capabilities will be removed from the list of
capabilities if they are present and perdition is not listening
for TLS connections.
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.
-i, --inetd_mode:
Run in inetd mode
-L, --connection_limit LIMIT:
Maximum number of connections to accept simultaneously. A value
of zero sets no limit on the number of simultaneous connections.
(default 0)
-l, --listen_port PORT_NUMBER|PORT_NAME:
Port to listen on.
The default is 110, 995, 143 and 993 in POP3, POP3S, IMAP4 and
IMAP4S mode respectively.
--login_disabled:
Do not allow users to log in. Also adds LOGINDISABLED to
capability list in IMAP4 and IMAP4S mode.
--log_passwd STATE:
Log the users password, otherwise just report it as "XXXXXX".
(default "never")
fail: log the password on failed connection attepmts.
ok: log the password on successful connection attepmts.
never: never log the password
always: always log the password
--lower_case state[,state...]:
Convert usernames to lower case according the the locale in
given state(s). See A|add_domain for a description of the
states.
(default "(null)")
-M, --map_library FILENAME:
Library to open that provides functions to look up the server
for a user. An empty ("") library means that no library will be
accessed and hence, no lookup will take place.
(default "/usr/lib/libperditiondb_gdbm.so.0")
-m, --map_library_opt STRING:
String option to pass to database access function provided by
the library specified by the map_library directive. The
treatment of this string is up to the library. See
perditiondb(5) for more details of how individual map_libraries
handle this string.
(default "")
--no_daemon:
Do not detach from terminal. Makes no sense if inetd_mode is in
effect.
-n, --no_lookup:
Disable host and port lookup, implies no_bind_banner. Please
note that if this option is enabled, then perdition will not
resolve host or port names returned by popmap lookups, thus,
your popmap must return ip addresses and port numbers.
-O, --ok_line:
Use STRING as the OK line to send to the client. Overridden by
server_resp_line. OK and will be prepended to STRING, and in
IMAP mode a tag will also be prepended to the string.
(default "You are so in")
--server_ok_line:
This option is deprecated and may be removed in a future
release. Use server_resp_line instead. If authentication with
the real-server is successful then send the servers +OK line to
the client, instead of generating one.
-o, --server_resp_line:
If authentication with the real-server is successful then
send the servers response line to the client, instead of
generating one.
-P, --protocol PROTOCOL:
Protocol to use.
(default "POP3") available protocols: "POP3, POP3S,
IMAP4, IMAP4S"
-p, --outgoing_port PORT:
Default real-server port.
See listen_port for defaults.
-s, --outgoing_server SERVER[,SERVER...]:
Define a server to use if a user is not in the popmap.
Format is servername|ip_address[:portname|portnumber].
Multiple servers may be delimited by a ’,’. If multiple
servers are specified then they are used in a round robin
fashion.
(default "")
--pid_file FILENAME:
Path for pidfile. Must be a full path starting with a
’/’. To allow perdition to remove the pid file after the
owner of the perdition process is changed to a non-root
user, it is advised to specify a pid file in a
subdirectory of the system var state directory (usually
/var/run). This subdirectory should be unique to this
perdition invocation and will be created and have its
owner and permissions set to allow perdition to
subsequently removed the pid file.
Empty for no pid file. Not used in inetd mode.
(default <var_state_dir>/<basename>/<basename>.pid)
-S, --strip_domain STATE[,STATE]:
Allow USER of the from user<delimiter>domain where
<delimiter>domain will be striped off in given
state(s).See add_domain for a description of the states.
-t, --timeout SECONDS:
Idle timeout for post-authentication phase. Zero for
infinite timeout.
(default 1800)
-u, --username USERNAME:
User to run as.
(default "nobody")
-U, --username_from_database:
If the servername in the popmap specified in the form:
user<delimiter>domain then use the username given by the
servername. If a servername is given in this form then
the domain will be used as the server to connect to,
regardless of this option.
-q, --quiet:
Only log errors. Overridden by debug
--query_key FORMAT[,FORMAT...]:
Instead of using the username as supplied by the end
user, possibly modified by strip_domain, use the formats
specified. The formats will be used in order to query the
popmap. The result from the first successful lookup will
be used. The format is comprised of a string of
characters, delimited by ’,’. The following escape codes
are valid:
\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.
--ssl_mode MODE:
Use SSL and or TLS for the listening and/or outgoing
connections. A comma delimited list of: none,
ssl_listen, ssl_outgoing, ssl_all, tls_listen,
tls_outgoing, tls_all, tls_listen_force,
tls_outgoing_force, tls_all_force. TLS is defined in RFC
2595.
(default "(null)")
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.
--ssl_ca_chain_file:
Sets the optional all-in-one file where you can assemble
the certificates of Certification Authorities (CA) which
form the certificate chain of the server certificate.
This starts with the issuing CA certificate of the
"ssl_cert_file" certificate and can range up to the root
CA certificate. Such a file is simply the concatenation
of the various PEM-encoded CA Certificate files, usually
in certificate chain order. Overrides ssl_ca_file and
ssl_ca_path.
(default NULL, no CA certificate will be used)
--ssl_ca_file FILENAME:
Certificate Authorities to use when verifying
certificates of real servers. Used for SSL or TLS
outgoing connections. When building the Certificate
Authorities chain, ssl_ca_file is used first, if set, and
then ssl_ca_path, if set. See
SSL_CTX_load_verify_locations(3) for format details.
(default "/etc/perdition/perdition.ca.pem")
--ssl_ca_path PATHNAME:
Certificate Authorities to use when verifying
certificates of real servers. Used for SSL or TLS
outgoing connections. "openssh c_rehash" should be run
in this directory when new certificates are added. When
building the Certificate Authorities chain, ssl_ca_file
is used first, if set, and then ssl_ca_path, if set. See
SSL_CTX_load_verify_locations(3) for details.
(default "/etc/perdition/perdition.ca/")
--ssl_ca_accept_self_signed:
Accept self-signed certificate authorities.
--ssl_cert_file FILENAME:
Certificate to use when listening for SSL or TLS
connections. Should be in PEM format.
(default "/etc/perdition/perdition.crt.pem")
--ssl_cert_accept_self_signed:
Accept self-signed certificates. Used for SSL or TLS
outgoing connections.
--ssl_cert_accept_expired:
Accept expired certificates. This includes server
certificates and certificate authority certificates.
Used for SSL or TLS outgoing connections.
--ssl_cert_accept_not_yet_valid:
Accept certificates that are not yet valid. This includes
server certificates and certificate authority
certificates. Used for SSL or TLS outgoing connections.
--ssl_cert_verify_depth DEPTH:
Chain Depth to recurse to when verifying certificates.
Used for SSL or TLS outgoing connections.
(default 9)
--ssl_key_file FILENAME:
Public key to use when listening for SSL or TLS
connections. Should be in PEM format.
(default "/etc/perdition/perdition.key.pem")
--ssl_listen_ciphers STRING:
Cipher list when listening for SSL or TLS connections as
per ciphers(1). If empty ("") then openssl’s default will
be used.
(default "")
--ssl_outgoing_ciphers STRING:
Cipher list when making outgoing SSL or TLS connections
as per ciphers(1). If empty ("") then openssl’s default
will be used.
(default "")
--ssl_no_cert_verify:
Don’t cryptographically verify the real-server’s
certificate. Used for SSL or TLS outgoing connections.
--ssl_no_cn_verify:
Don’t verify the real-server’s common name with the name
used. to connect to the server. Used for SSL or TLS
outgoing connections.
Notes: Default value for binary flags is off.
If a string argument is empty ("") then the option will
not be used unless noted otherwise.
The defaults given refer to the values if perdition is
compiled with --sysconfdir=/etc as it would for many
binary distributions. For the actual defaults of a given
perdition binary run "perdition --help"
USER DATABASE (POPMAP)
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".
STAND-ALONE MODE
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"
INETD MODE
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
LOCAL AUTHENTICATION
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.
DOMAIN DELIMITER
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.
USER PORT SPECIFICATION
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
IDLE TIMEOUTS
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.
LOOP DETECTION
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.
CONFIGURATION FILE
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
POP BEFORE SMTP
Perdition supports POP before SMTP in both POP3 and IMAP4 mode
by logging having logging the following messages:
When a user connects:
Connect: <source_ip_address>[inetd_pid=<pid>]
When a user is authenticated
Auth: <source_ip_address> user="<username>"
passwprd="<passwowd>" server="<servername"> port="<port>"
status=failed...|ok
When a user disconnects
Close: <source_ip_address> user="<username>" received=<bytes>
sent=<bytes>
LOGGING
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.
SSL/TLS Support
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
FILES
/etc/perdition/perdition.conf
SEE ALSO
perditiondb(5), inetd(8), syslog.conf(5), syslogd(8)
AUTHORS
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 PERDITION(8)