Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PERDITION(8)		    System Manager's Manual		  PERDITION(8)

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 Man-
       ageSieve	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 con-
       nection is made to the real-server and perdition	then passes on the au-
       thentication  credentials.  If authentication is	successful then	perdi-
       tion pipes data between the end-user and	the real-server.  If authenti-
       cation  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.	perdi-
       tion.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 re-
	      verse-lookup of the IP address connected to. If there is no  re-
	      verse  lookup for	this IP	address, then a	domain will not	be ap-
	      pended. 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  de-
	      faults to	1, which would mean that www.au.vergenet.net would be-
	      come au.vergenet.net. A depth of 2 would cause it	to become ver-
	      genet.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 ef-
	      fect.

       --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	facil-
	      ity 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	facil-
	      ity, then	the process will not fork and detach from  the	termi-
	      nal.

       -f, --config_file FILENAME:
	      Name  of config file to read.  Command line options override op-
	      tions 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	perdi-
	      tion is invoked  as  /usr/sbin/perdition.pop3,  and  /etc/perdi-
	      tion/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 "manage-
	      sieve".  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 capa-
	      bilities should be  space	 delimited.   The  default  is	"IMAP4
	      IMAP4REV1".  However,  perdition	does support RFC 2088 non-syn-
	      chronising string	literals, if the  real	servers	 also  support
	      this  then  the  capability  may be set to "IMAP4	IMAP4REV1 LIT-
	      ERAL+".

	      If perdition is running with  ssl_mode  includes	to  ssl_listen
	      then the capability STARTTLS will	be appended to the list	of ca-
	      pabilities if it is not already present. Similarly this capabil-
	      ity 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 capabil-
	      ity 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	 capa-
	      bility 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 ef-
	      fect.

       --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 dou-
	      ble space	delimited.

	      If  perdition  is	 running  with ssl_mode	includes to ssl_listen
	      then the capability STARTTLS will	be appended to the list	of ca-
	      pabilities  if it	is not already present.	Similary this capabil-
	      ity 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 en-
	      coded-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	treat-
	      ment 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 re-
	      solve  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  re-
	      lease.   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 re-
	      moved 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 capa-
	      bilities 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 <delim-
	      iter>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<de-
	      limiter>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, pos-
	      sibly 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 fol-
	      lowing 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 connec-
	      tions.  A	comma delimited	list of: none, ssl_listen,  ssl_outgo-
	      ing,   ssl_all,	tls_listen,  tls_outgoing,  tls_all,  tls_lis-
	      ten_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_outgo-
	      ing_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 sim-
	      ply  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 cer-
	      tificates	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 ci-
	      phers(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  connec-
	      tions.

       --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 ci-
	      phers(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  connec-
	      tions.

       --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	incom-
	      ming 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	incom-
	      maxg 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 distribu-
	      tions. 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	perdi-
       tion 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	alter-
       nate  port  can be specified with the -l|--listen_port command line op-
       tion. 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 (De-
       bian) 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 us-
       ing /etc/hosts.allow and	/etc/hosts.deny.  Sample  /etc/inetd.conf  en-
       tries 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 au-
       thenticate 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 de-
       limiter 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<delim-
       iter>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.	 --authentica-
       tion_timeout  is	 used  before the user has been	successfully authenti-
       cated 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  ef-
       fect.

LOOP DETECTION
       The greeting that perdition displays when accepting an incoming connec-
       tion 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	perdi-
       tion is connecting to itself and	a "Re-Authentication Failure"  is  re-
       turned 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, with-
       out the leading - or --.	 Blank lines are ignored, as is	 anything  in-
       cluding 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 es-
       caped 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 log-
       ging 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="<authori-
       sation_id>"   authentication_id="<authentication_id>"  password="<pass-
       word>"  server="<servername>:<port>"   protocol=<protocol>   server-se-
       cure=SECURE_STATUS status=failed...|ok

       When a user disconnects

       Close:	<from_to>   authorisation_id="<authorisation_id>"  authentica-
       tion_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 sys-
       tems. If	the -q|--quiet command line option or configuration  file  di-
       rective	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  follow-
       ing 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 us-
       ing 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 us-
       ing POP3	on port	110 (the default POP3 port) the	following are  equiva-
       lent.

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

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USER DATABASE (POPMAP) | STAND-ALONE MODE | INETD MODE | LOCAL AUTHENTICATION | DOMAIN DELIMITER | USER PORT SPECIFICATION | IDLE TIMEOUTS | LOOP DETECTION | CONFIGURATION FILE | POP BEFORE SMTP | LOGGING | SSL/TLS Support | Mixed-mode configurations | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=perdition&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help