Provided by: perdition_1.17-5build1_i386 bug


       perdition - POP3 and IMAP4 proxy server


       perdition [options]
       perdition.pop3 [options]
       perdition.pop3s [options]
       perdition.imap4 [options]
       perdition.imap4s [options]
       perdition.imaps [options]


       perdition  allows  users  to  connect  to  a content-free POP3 or IMAP4
       server that will redirect them to  their  real  POP3  or  IMAP4  server
       respectively.  This  enables  mail  retrieval  for a domain to be split
       across multiple real mail servers on a per user basis.  This  can  also
       be   used   to  as  a  POP3  or  IMAP4  proxy  especially  in  firewall

       When a connection is made to perdition in POP3 mode, it reads the  USER
       and PASS commands and then refers to its popmap to find the real-server
       that the user’s connection should be forwarded  to.   A  connection  is
       made  to  the  real-server  and perdition then enters the USER and PASS
       commands. If authentication is successful  then  perdition  pipes  data
       between the end-user and the real-server.  If authentication fails then
       the real-server connection is closed and the client connection is reset
       to the state it was in on initial connection. That is new USER and PASS
       commands are expected.  Similarly in IMAP4 mode, perdition accepts  the
       LOGIN command and passes the username and password onto the real-server
       or authentication.

       No IMAP authentication  schemes,  other  than  the  LOGIN  command  are

       When  invoked  as  perdition.pop3,  perdition.pop3s, perdition.imap4 or
       perdition.imap4s then perdition will  run  in  POP3,  POP3S,  IMAP4  or
       IMAP4S  mode  respectively, unless overridden on the command line or in
       the configuration file.  perdition.imaps also runs perdition in  IMAP4S
       mode  and  is provided to get around the truncation of process names in
       the /proc filesystem on Linux which can cause init scripts to  fail  to
       stop perdition correctly.


       -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  would
              become  A  depth of 2 would cause it to become
     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 "")

       -a, --authenticate_in:
              User is authenticated by perdition before connection to back-end
              server is made. Only available if perdition is compiled with pam

       -B, --no_bind_banner:
              If  bind_address is specified, then the address will be resolved
              and the reverse-lookup of this will be  used  in  the  greeting.
              This  option  disables  this  behaviour  an reverts to using the
              uname to derive the hostname for the greeting.

       -b, --bind_address IP_ADDRESS|HOSTNAME:
              Bind  to  interfaces  with  this  address.  In  non-inetd  mode,
              connections  will  only  be  accepted  on  interfaces  with this
              address.  If  NULL  connections  will  be  accepted   from   all
              interfaces.  In  inetd  and non-inetd mode the source address of
              connections to real servers will be this address, if  NULL  then
              the operating system will select a source address.
              (default "")

              Log  interaction  between  clients, perdition and servers during
              authentication phase.

              Note: -d|--debug must be  specified  for  this  option  to  take

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

       -f, --config_file FILENAME:
              Name of config file to  read.   Command  line  options  override
              options set in config file.

              The default is derived as follows:

              The  sysconfig dir ("/etc/perdition" for example) is checked for
              <basename>.conf. If this is  found  then  it  is  used.   So  if
              perdition    is   invoked   as   /usr/sbin/perdition.pop3,   and
              /etc/perdition/perdition.pop3.conf exists then it will be  used.

              Next the sysconfig dir is checked for peridtion.<protocol>.conf,
              where protocol is the ASCII representation of the protocol being
              used,  one  of  "imap4",  "imap4s",  "pop3",  or "pop3s".  So if
              perdition    is    being    run    in    imap4     mode,     and
              /etc/perdition/perdition.imap4.conf  exists,  then  it  is used.
              Note that the protocol name is lowercase.

              Next the sysconfig dir is checked for perdition.conf, if  it  is
              found then it is used.

              If  none  of these files are found then no configuration file is

       -g, --group GROUP:
              Group to run as.
              (default "nobody")

       -h, --help:
              Display this message

       -I, --capability, --pop_capability, --imap_capability STRING:
              Capabilities for the protocol.

              When using a POP3 based protocol,  the  capabilities  should  be
              delimited  by  two  spaces.  This  is  because  the capabilities
              themselves may contain  single  spaces.  The  default  is  "UIDL

              When  using  an  IMAP4 based protocol, this string is taken as a
              string literal that will be returned when a  client  issues  the
              CAPABILITY  command.  As  such  the capabilities should be space
              delimited.  The default is "IMAP4 IMAP4REV1". However, perdition
              does  support RFC 2088 non-synchronising string literals, if the
              real servers also support this then the capability may be set to
              "IMAP4 IMAP4REV1 LITERAL+".

              If   perdition   is  listening  for  TLS  connections  then  the
              capability STLS for POP3 or STARTTLS for IMAP4 will be  appended
              to  the  list  of  capabilities  if  it  is not already present.
              Similarly these capabilities will be removed from  the  list  of
              capabilities  if they are present and perdition is not listening
              for TLS connections.

              Perdition may also manipulate the capability in IMAP mode to add
              and   remove   the  LOGINDISABLED  capability  if  the  no_login
              capability  is  in  effect   or   if   the   ssl_mode   includes
              tls_listen_force or tls_outgoing_force.

       -i, --inetd_mode:
              Run in inetd mode

       -L, --connection_limit LIMIT:
              Maximum  number of connections to accept simultaneously. A value
              of zero sets no limit on the number of simultaneous connections.
              (default 0)

       -l, --listen_port PORT_NUMBER|PORT_NAME:
              Port to listen on.

              The  default  is 110, 995, 143 and 993 in POP3, POP3S, IMAP4 and
              IMAP4S mode respectively.

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

       --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
              (default "(null)")

       -M, --map_library FILENAME:
              Library  to  open  that provides functions to look up the server
              for a user. An empty ("") library means that no library will  be
              accessed and hence, no lookup will take place.
              (default "/usr/lib/")

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

              Do  not detach from terminal. Makes no sense if inetd_mode is in

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

              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
              (default "")

       --pid_file FILENAME:
              Path  for  pidfile.  Must  be a full path starting with a
              ’/’.  To allow perdition to remove the pid file after the
              owner  of  the perdition process is changed to a non-root
              user,  it  is  advised  to  specify  a  pid  file  in   a
              subdirectory  of  the system var state directory (usually
              /var/run). This subdirectory should  be  unique  to  this
              perdition  invocation  and  will  be created and have its
              owner  and  permissions  set  to   allow   perdition   to
              subsequently removed the pid file.
              Empty for no pid file. Not used in inetd mode.
              (default <var_state_dir>/<basename>/<basename>.pid)

       -S, --strip_domain STATE[,STATE]:
              Allow   USER  of  the  from  user<delimiter>domain  where
              <delimiter>domain  will   be   striped   off   in   given
              state(s).See  add_domain for a description of the states.

       -t, --timeout SECONDS:
              Idle timeout. Zero for infinite timeout.
              (default 1800)

       -u, --username USERNAME:
              User to run as.
              (default "nobody")

       -U, --username_from_database:
              If the servername in the popmap specified  in  the  form:
              user<delimiter>domain  then use the username given by the
              servername.  If a servername is given in this  form  then
              the  domain  will  be  used  as the server to connect to,
              regardless of this option.

       -q, --quiet:
              Only log errors. Overridden by debug

       --query_key FORMAT[,FORMAT...]:
              Instead of using the username  as  supplied  by  the  end
              user,  possibly modified by strip_domain, use the formats
              specified. The formats will be used in order to query the
              popmap.  The result from the first successful lookup will
              be  used.  The  format  is  comprised  of  a  string   of
              characters,  delimited by ’,’. The following escape codes
              are valid:

              \U: Long Username, the entire string supplied by
                  the end user, less any effects of
              \u: Short Username, the portion Long Username
                  before the domain delimiter.
              \D: Domain Delimiter, as specified by
              \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.


              Use the supplied username, the default behaviour

              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

              Use the destination IP address

              Escape codes interspersed with literals

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

              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

              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.    Used    in
              conjunction   with   tls_listen,(or   tls_all),   ignored

              tls_outgoing_force:   Do    not    send    authentication
              information   if  TLS  cannot  be  negotiated.   Used  in
              conjunction  with  tls_outgoing  (or  tls_all),   ignored

              tls_all_force:               Short-Hand               for

              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
              (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/")

       --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/")

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

              Accept self-signed certificates.  Used  for  SSL  or  TLS
              outgoing connections.

              Accept   expired   certificates.   This  includes  server
              certificates  and  certificate  authority   certificates.
              Used for SSL or TLS outgoing connections.

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

              Don’t   cryptographically   verify   the    real-server’s
              certificate.  Used for SSL or TLS outgoing connections.

              Don’t  verify the real-server’s common name with the name
              used.  to connect to the server.  Used  for  SSL  or  TLS
              outgoing connections.

       Notes: Default value for binary flags is off.
              If  a  string argument is empty ("") then the option will
              not be used unless noted otherwise.
              The defaults given refer to the values  if  perdition  is
              compiled  with  --sysconfdir=/etc  as  it  would for many
              binary distributions. For the actual defaults of a  given
              perdition binary run "perdition --help"


       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".


       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:


       The file is sourced into the init script so normal  bash  syntax
       applies.  Blank lines are ignored, as is anything after a # on a


       POP3_FLAGS="--ssl_mode tls_listen"
       IMAP4_FLAGS="--ssl_mode tls_listen"
       POP3S_FLAGS="--ssl_mode ssl_listen -p 110"
       IMAP4S_FLAGS="--ssl_mode ssl_listen -p 143"


       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


       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.


       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.


       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


       0 login




       If  there  is  no  input  from the client or back-end server for
       greater than timeout seconds then the connection is closed.  The
       default  timeout  is  1800  seconds  and can be specified on the
       command line with the -t|--timeout option.   A  time  out  of  0
       means  that  timeouts  are  disabled  and  clients  and back-end
       servers can idle indefinitely.


       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


       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


       Perdition supports POP before SMTP in both POP3 and  IMAP4  mode
       by logging having logging the following messages:

       When a user connects:

       Connect: <source_ip_address>[inetd_pid=<pid>]

       When a user is authenticated

       Auth:            <source_ip_address>           user="<username>"
       server="<servername"> port="<port>" status=failed|ok

       When a user disconnects

       Close:  <source_ip_address>  user="<username>"  received=<bytes>


       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




       perditiondb(5), inetd(8), syslog.conf(5), syslogd(8)


       Horms <>

       Perditiondb Library Authors
       Frederic Delchambre <>      (MySQL)
       Chris  Stratford: <>           (LDAP and Berkely
       Nathan Neulinger <>              (NIS)

       Contributing Authors
       Daniel Roesen <>
       Clinton Work <>
       Youri <>
       Jeremy Nelson <>
       Wim Bonis <>
       Arvid Requate <arvid@Team.OWL-Online.DE>
       Mikolaj J. Habryn <>
       Ronny Cook <>
       Geoff Mitchell <>
       Willi Langenberger <>
       Matt Prigge <>
       Wolfgang Breyha <>

                                12th June 2003                    PERDITION(8)