Provided by: perdition_2.2-3ubuntu2_amd64 bug

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@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: <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@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)