Provided by: perdition_1.19~rc4-4build1_i386 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 and 993 in POP3, POP3S,  IMAP4  and
              IMAP4S mode respectively.

       --login_disabled:
              Do  not  allow  users  to  log  in.   Also adds LOGINDISABLED to
              capability list in IMAP4 and IMAP4S mode.

       --log_passwd STATE:
              Log the users password, otherwise just report it as "XXXXXX".
              (default "never")

              fail: log the password on failed connection 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.   When in debug mode, the password is logged as "XXXXXX"
              unless log_passwd is in effect for the current STATE.

       --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_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)

       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)