Content-type: text/html; charset=UTF-8
Man page of PERDITION
PERDITION
Section: Maintenance Commands (8) Updated: 12th June 2003 Index
Return to Main Contents
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]
perdition.managesieve [options]
DESCRIPTION
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.
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:
-
Use the hostname derived from usname in the banner. In inetd mode this is
always the case. In non-inetd mode if this option is not in effect then the
IP address used to accept a connection will be used and if
-n|--no_loookup is not in effect it will be resolved.
- -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
omitted, 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", "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.
- -g, --group GROUP:
-
Group to run as.
(default "nobody")
- -h, --help:
-
Display this message
- -I, --capability STRING:
-
Deprecated in favour of --pop_capability and --imap_capability
- --imap_capability STRING:
-
Capabilities for IMAP3 and IMAP4S
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.
- -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, 993 and 4190 for POP3, POP3S, IMAP4,
IMAP4S and MANAGESIEVE 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.
(default "never")
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.
- --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)")
- --managesieve_capability STRING:
-
Capabilities for ManageSieve
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"")
- -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)
- --pop_capability STRING:
-
Capabilities for POP3 and POP3S
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.
- -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)
- --tcp_keepalive:
-
Turn on TCP Keep-Alive (see RFC 1122). This will turn on TCP Keep-Alive
for both incoming connections from clients as well as connections made to
the real POP3, IMAP4 or managesieve server.
(default is disabled)
- -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_dh_params_file FILENAME:
-
Diffie-Hellman parameters to use when offering EDH ciphersuites to clients.
Should be in PEM format.
(default: look for DH parameters in ssl_cert_file)
- --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 certificates.
Used for SSL or TLS outgoing connections.
- --ssl_no_client_cert_verify:
-
Don't cryptographically verify the end-user'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.
- --ssl_passphrase_fd N:
-
File descriptor to read the passphrase for the certificate from.
Only the first line will be read.
Only one of ssl_passphrase_fd and ssl_passphrase_file may
be specified.
(default 0)
- --ssl_passphrase_file FILENAME:
-
File to read the passphrase for the certificate from.
Only the first line will be read.
Only one of ssl_passphrase_fd and ssl_passphrase_file may
be specified.
(default NULL, no file)
- --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 certificates.
Used for SSL or TLS outgoing connections.
- --ssl_no_client_cert_verify:
-
Don't cryptographically verify the end-user'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.
- --ssl_passphrase_fd N:
-
File descriptor to read the passphrase for the certificate from.
Only the first line will be read.
Only one of ssl_passphrase_fd and ssl_passphrase_file may
be specified.
(default 0)
- --ssl_listen_min_proto_version PROTOCOL_VERSIONS:
-
Minimum permited SSL/TLS protocol version when accepting incomming
connections. May not be empty ("").
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "tlsv1")
- --ssl_outgoing_min_proto_version PROTOCOL_VERSIONS:
-
Minimum permited SSL/TLS protocol version when making outgoing
connections. May not be empty ("").
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "tlsv1")
- --ssl_listen_max_proto_version PROTOCOL_VERSIONS:
-
Maximum permited SSL/TLS protocol version when accepting incommaxg
connections. If empty ("") then openssl's default will be used.
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "")
- --ssl_outgoing_max_proto_version PROTOCOL_VERSIONS:
-
Maximum permited SSL/TLS protocol version when making outgoing
connections. If empty ("") then openssl's default will be used.
The valid protocol versions are sslv3, tlsv1, tlsv1.1 and tlsv1.2.
(default "")
- --ssl_listen_compression:
-
Allow SSL/TLS compression when accepting incoming connections.
- --ssl_outgoing_compression:
-
Allow SSL/TLS compression when making outgoing connections.
- --ssl_no_cipher_server_preference:
-
Disable SSL/TLS cipher server preference when accepting incoming 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 at that.host:143
POP3
user james at 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: <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.
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
Mixed-mode configurations
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.
FILES
- /etc/perdition/perdition.conf
-
SEE ALSO
perditiondb(5), inetd(8), syslog.conf(5), syslogd(8)
AUTHORS
Lead
Horms <horms at verge.net.au>
Perditiondb Library Authors
Frederic Delchambre <dedel at freegates.be> (MySQL)
Chris Stratford: <chriss at uk.uu.net> (LDAP and Berkeley DB)
Nathan Neulinger <nneul at umr.edu> (NIS)
Contributing Authors
Daniel Roesen <droesen at entire-systems.com>
Clinton Work <work at scripty.com>
Youri <ya at linkline.be>
Jeremy Nelson <jnelson at optusnet.com.au>
Wim Bonis <bonis at solution-service.de>
Arvid Requate <arvid at Team.OWL-Online.DE>
Mikolaj J. Habryn <dichro at rcpt.to>
Ronny Cook <ronny at asiaonline.net>
Geoff Mitchell <g.mitchell at videonetworks.com>
Willi Langenberger <wlang at wu-wien.ac.at>
Matt Prigge <mprigge at pobox.com>
Wolfgang Breyha <wolfgang.breyha at uta.at>
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- USER DATABASE (POPMAP)
-
- STAND-ALONE MODE
-
- INETD MODE
-
- LOCAL AUTHENTICATION
-
- DOMAIN DELIMITER
-
- USER PORT SPECIFICATION
-
- IDLE TIMEOUTS
-
- LOOP DETECTION
-
- CONFIGURATION FILE
-
- POP BEFORE SMTP
-
- LOGGING
-
- SSL/TLS Support
-
- Mixed-mode configurations
-
- FILES
-
- SEE ALSO
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 10:21:55 GMT, November 01, 2016
|