PERDITION(8)

📦 version 2.2, in alpine 3.22, alpine 3.23, alpine 3.24, debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 PERDITION(8) 💖

okay bestie, welcome to the PERDITION(8) page from the System Manager's Manual — grab a snack, this one's a whole journey 🍓✨

🦋 NAME 🦋

perdition — a 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 ✨

so like, perdition lets users connect to a content-free POP3, IMAP4 or ManageSieve server that will redirect them to their real POP3, IMAP4 or ManageSieve server respectively. the way that works is it lets mail retrieval and sieve management for a domain be split across multiple real mail servers on a per user basis 👑

it can also be used 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 user's 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. no cap 😭

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. iykyk 🙈

💅 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 the 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 it 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:

  1. 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.
  2. 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.
  3. 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\""

…and the default for that one is genuinely unhinged, so here it is in full, no edits:

(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 — the library perdition opens to get the ✨functions✨ that look up which server a user belongs to. If you hand it an empty string (""), then no library gets opened at all, which means no lookup happens, periodt. (default /usr/lib/libperditiondb_gdbm.so.0)
  • -m, --map_library_opt STRING — a string you yeet into the database access function that the library from map_library provides. What happens to this string is entirely up to the library, so don't come for perdition about it. Peep perditiondb(5) for how each individual map_library handles it. (default "")
  • --no_daemon — do NOT detach from the terminal, bestie. You stay right here, in this window, with me. Also: this makes zero sense if inetd_mode is in effect. 🫶
  • -n, --no_lookup — turns off host and port lookup, and it implies no_bind_banner. Big heads up tho: if you enable this, perdition will not resolve the host or port names that popmap lookups hand back, so your popmap must return actual IP addresses and port numbers. No hostnames, no vibes-based guessing. 💀
  • -O, --ok_line — use STRING as the OK line that gets sent to the client. This gets overridden by server_resp_line. The literal OK will be prepended to STRING, and in IMAP mode a tag also gets prepended to the string. (default You are so in — iconic behaviour honestly 👑)
  • --server_ok_line — deprecated, and it might get removed in a future release. Use server_resp_line instead, fr fr. What it does: if authentication with the real-server succeeds, then send the server's +OK line to the client instead of generating one.
  • -o, --server_resp_line — if authentication with the real-server succeeds, send the server's response line to the client instead of generating one. That's the whole thing. Clean. ✨
  • -P, --protocol PROTOCOL — which protocol we're speaking. (default POP3) Available protocols: POP3, POP3S, IMAP4, IMAP4S
  • -p, --outgoing_port PORT — the default real-server port. Scroll up to listen_port for the defaults, bestie.
  • -s, --outgoing_server SERVER[,SERVER...] — defines a server to use when a user isn't in the popmap. Format is servername|ip_address[:portname|portnumber]. You can stack multiple servers by separating them with a ,. And if you do list multiple servers, they get used in a round robin fashion. (default "")
  • --pid_file FILENAME — path for the pidfile. It must be a full path starting with a /. Now listen: so that perdition can remove the pid file after the owner of the perdition process has been changed to a non-root user, you're advised to specify a pid file in a subdirectory of the system var state directory (usually /var/run). That subdirectory should be unique to this perdition invocation, and it will be created, with its owner and permissions set so perdition can subsequently remove the pid file. Empty means 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, " ". That's deprecated now, and it is not valid to mix delimiters. Pick one and commit, okay?

The default capability is UIDL.USER.

If perdition is running with an ssl_mode that includes 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 if it is present and perdition is not running with an ssl_mode that includes ssl_listen. Symmetry, we love to see it. 🦋

  • -S, --strip_domain STATE[,STATE] — allows USER of the form user<delimiter>domain, where <delimiter>domain gets stripped off in the given state(s). See add_domain for a description of the states. ✂️
  • -t, --timeout SECONDS — idle timeout for the post-authentication phase. Zero means infinite timeout. (default 1800)
  • --tcp_keepalive — turns on TCP Keep-Alive (see RFC 1122). This switches on TCP Keep-Alive for both incoming connections from clients and the connections made out to the real POP3, IMAP4 or managesieve server. (default is disabled)
  • -u, --username USERNAME — the user to run as. (default nobody)
  • -U, --username_from_database — if the servername in the popmap is specified in the form user<delimiter>domain, then use the username given by the servername. And heads up: if a servername is given in this form, then the domain will be used as the server to connect to, regardless of this option. Like, it just does that. 🫠
  • -q, --quiet — only log errors. Gets 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 you specify here. The formats get used in order to query the popmap, and the result from the first successful lookup is the one that wins. The format is a string of characters, delimited by ,. These 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 \

Because , is the delimiter between formats, it cannot appear within a format. Every other character that isn't one of the escape codes above and isn't , is treated as a literal.

🌟 Examples 🌟

Use the supplied username, the default behaviour

\U

Use the user portion of the supplied username, and 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. Just so you know before you get attached. 🥲

  • --ssl_mode MODE — use SSL and/or TLS for the listening and/or outgoing connections. It's 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 at all — it's the default, bestie.
    • 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. You should run "openssh c_rehash" 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 — bestie, this one lets you accept certificates that are not yet valid — like, they exist, they're just not in their era yet. Covers server certs and certificate authority certs. For SSL or TLS outgoing connections only. 🦋
  • --ssl_cert_verify_depth DEPTH — how deep down the chain we recurse when verifying certs. Chain Depth, fr fr. For SSL or TLS outgoing connections.
    • default: 9
  • --ssl_key_file FILENAME — the public key we use when we're the one listening for SSL or TLS connections. Should be PEM format, no exceptions. 👑
    • default: "/etc/perdition/perdition.key.pem"
  • --ssl_listen_ciphers STRING — cipher list for when you're listening for SSL or TLS connections, as per ciphers(1). If it's empty ("") then openssl's default gets used instead. iykyk.
    • default: ""
  • --ssl_outgoing_ciphers STRING — same deal but for when you're making outgoing SSL or TLS connections, as per ciphers(1). Empty ("") means openssl's default steps in.
    • default: ""
  • --ssl_no_cert_verify — do NOT cryptographically verify the certificates. For SSL or TLS outgoing connections. 💀
  • --ssl_no_client_cert_verify — do NOT cryptographically verify the end-user's certificate. For SSL or TLS outgoing connections.
  • --ssl_no_cn_verify — do NOT verify the real-server's common name against the name used to connect to the server. For SSL or TLS outgoing connections.
  • --ssl_passphrase_fd N — the file descriptor we read the certificate passphrase from. Only the first line gets read, periodt. You may only specify one of ssl_passphrase_fd and ssl_passphrase_file — pick a lane.
    • default: 0
  • --ssl_passphrase_file FILENAME — a file to read the certificate passphrase from. Again, only the first line gets read. And again, 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). Empty ("") → openssl's default. (Yes bestie, this one showed up twice in the original and we are NOT skipping it. Every detail stays. 💅)
    • default: ""
  • --ssl_outgoing_ciphers STRING — cipher list when making outgoing SSL or TLS connections, as per ciphers(1). Empty ("") → openssl's default.
    • default: ""
  • --ssl_no_cert_verify — don't cryptographically verify the certificates. SSL or TLS outgoing connections.
  • --ssl_no_client_cert_verify — don't cryptographically verify the end-user's certificate. SSL or TLS outgoing connections.
  • --ssl_no_cn_verify — don't verify the real-server's common name against the name used to connect to the server. SSL or TLS outgoing connections.
  • --ssl_passphrase_fd N — file descriptor to read the certificate passphrase from. First line only. Only one of ssl_passphrase_fd and ssl_passphrase_file may be specified.
    • default: 0
  • --ssl_listen_min_proto_version PROTOCOL_VERSIONS — the minimum SSL/TLS protocol version permitted when accepting incoming connections. May not be empty (""). 🚫
    • valid protocol versions are: sslv3, tlsv1, tlsv1.1 and tlsv1.2
    • default: "tlsv1"
  • --ssl_outgoing_min_proto_version PROTOCOL_VERSIONS — the minimum SSL/TLS protocol version permitted when making outgoing connections. May not be empty ("").
    • valid protocol versions are: sslv3, tlsv1, tlsv1.1 and tlsv1.2
    • default: "tlsv1"
  • --ssl_listen_max_proto_version PROTOCOL_VERSIONS — the maximum SSL/TLS protocol version permitted when accepting incoming connections. If it's empty ("") then openssl's default gets used.
    • valid protocol versions are: sslv3, tlsv1, tlsv1.1 and tlsv1.2
    • default: ""
  • --ssl_outgoing_max_proto_version PROTOCOL_VERSIONS — the maximum SSL/TLS protocol version permitted when making outgoing connections. Empty ("") → openssl's default.
    • 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, bestie, read these:

  • 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 be for many binary distributions. For the actual defaults of a given perdition binary, run perdition --help. 🔍

🗄️ USER DATABASE (POPMAP) 🗄️

For the tea on how users get resolved to a host and port, plus everything about the -M|--map_library and -m|--map_library_opt flags, go read perditiondb(5). It's giving required reading. 📚

Note that by specifying a map library, no map lookups will occur and all connections will use the -s|--outgoing_server. Which means perdition can be configured as a "pure proxy". slay.

🌈 STAND-ALONE MODE 🌈

Normally perdition binds to a port and listens for connections. The default port is 110 in POP3 mode and 143 in IMAP4 mode, and you can pick a different one with the -l|--listen_port command line option. In this mode perdition forks to manage clients. Fork fork fork. 🍴

🎀 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) lets you control whether perdition will be started in POP3 mode, IMAP4 mode, both, or neither. Main character energy is choosing.

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, and so 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 lets perdition 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. Don't forget the restart, bestie, it will simply not work and you will be sad. 😭

🔐 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 it must succeed for a connection to the foreign server to be made. No pass, no proxy. 🫶

This authentication uses PAM, and a sample pam configuration file for perdition can be found in etc/pam.d/perdition in the source tree. That one 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. Teamwork, honestly.

🌸 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]. The user gets to choose their own destiny. iconic.

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. Two eras, two timeouts. ✨

The default value for both timeouts is 1800. A timeout value of 0 means 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. Not the self-love we were rooting for. 💀

📝 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. Command line wins, always. 👑

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 🦋

Okay bestie, so Perdition supports POP before SMTP in both POP3 and IMAP4 mode by 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 🔥

👑 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>

And that's the whole page, bestie! This was perdition(8), dated 12th June 2003. Go forth and proxy securely 💅✨🫶

📦 where this page comes from