1PERDITION(8) System Manager's Manual PERDITION(8)
2
6 perdition - POP3 and IMAP4 proxy server
7
9 perdition [options]
10 perdition.pop3 [options]
11 perdition.pop3s [options]
12 perdition.imap4 [options]
13 perdition.imap4s [options]
14 perdition.imaps [options]
15 perdition.managesieve [options]
16
19 perdition allows users to connect to a content-free POP3, IMAP4 or Man‐
20 ageSieve server that will redirect them to their real POP3, IMAP4 or
21 ManageSieve server respectively. This enables mail retrieval and sieve
22 management for a domain to be split across multiple real mail servers
23 on a per user basis. This can also be used to as a POP3, IMAP4 and
24 ManageSieve proxy especially in firewall applications. And as a method
25 of migrating users to new servers.
26 When a connection is made to perdition in POP3 mode, it reads the users
28 authentication credentials and then refers to its popmap to find the
29 real-server that the user's connection should be forwarded to. A con‐
30 nection is made to the real-server and perdition then passes on the
31 authentication credentials. If authentication is successful then perdi‐
32 tion pipes data between the end-user and the real-server. If authenti‐
33 cation fails then the real-server connection is closed and the client
34 connection is reset to the state it was in on initial connection. That
35 is new authentication credentials are expected.
36 N.B: No IMAP authentication schemes, other than the LOGIN command are
38 accepted.
39 When invoked as perdition.pop3, perdition.pop3s, perdition.imap4,
41 perdition.imap4s or perdition.managesieve then perdition will run in
42 POP3, POP3S, IMAP4, IMAP4S or MANAGESIEVE mode respectively, unless
43 overridden on the command line or in the configuration file. perdi‐
44 tion.imaps also runs perdition in IMAP4S mode and is provided to get
45 around the truncation of process names in the /proc filesystem on Linux
46 which can cause init scripts to fail to stop perdition correctly.
47
50 -A|--add_domain STATE[,STATE...][,STRIP_DEPTH]:
51 Appends a domain to the USER based on the IP address connected
52 to in given state(s). The domain name to append will be the
53 reverse-lookup of the IP address connected to. If there is no
54 reverse lookup for this IP address, then a domain will not be
55 appended. Probably the easiest way to enforce this mapping is to
56 add entries to /etc/hosts.
57 The valid states are servername_lookup, local_authentication,
59 remote_login and all
60 servername_lookup: Append the domain to the username for lookup
62 of username in Popmap. Will not take effect if
63 client_server_specification is in effect.
64 local_authentication: Append the domain to the username for use
66 in local authentication. Only has effect if authenticate_in is
67 in effect.
68 remote_login: Send the username with the domain appended to the
70 real-server for authentication.
71 all: Short-Hand for all of above states.
73 The domain may also have leading levels striped, essentially to
75 convert a hostname to a domain name. The depth of the strip
76 defaults to 1, which would mean that www.au.vergenet.net would
77 become au.vergenet.net. A depth of 2 would cause it to become
78 vergenet.net and so forth. A depth of 0 leaves the name
79 unchanged. The depth and may be specified by appending
80 ",STRIP_DEPTH" to the state. For compatibility reasons the
81 default depth is 1.
82 e.g. all,2
84 (the default value for add_domain is "")
86 --authenticate_timeout:
88 Idle timeout in seconds used while the user is unauthenticated.
89 Zero for infinite timeout.
90 -a, --authenticate_in:
92 User is authenticated by perdition before connection to back-end
93 server is made. Only available if perdition is compiled with pam
94 support.
95 -B, --no_bind_banner:
97 Use the hostname derived from usname in the banner. In inetd
98 mode this is always the case. In non-inetd mode if this option
99 is not in effect then the IP address used to accept a connection
100 will be used and if -n|--no_loookup is not in effect it will be
101 resolved.
102 -b, --bind_address SERVER[,SERVER...]:
104 Bind to these addresses and ports. interfaces with this address.
105 Format is as per the --outgoing_server option. If the port is
106 omitted, then the listen_port will be used.
107 In non-inetd mode, connections will only be accepted to the
109 listed servers. If un-set connections will be accepted on all
110 addresses on the listen_port.
111 (default "")
113 -C|--connection_logging:
115 Log interaction between clients, perdition and servers during
116 authentication phase.
117 Note: -d|--debug must be specified for this option to take
119 effect.
120 --connect_relog SECONDS:
122 How often to relog the connection. For use in conjunction with
123 POP and IMAP before SMTP. If zero then the connection will not
124 be reloged.
125 (default 300)
126 -c, --client_server_specification:
128 Allow USER of the form user<delimiter>server[:port] to specify
129 the server and port for a user.
130 -D, --domain_delimiter STRING:
132 Delimiter between username and domain.
133 (default "@")
134 -d, --debug:
136 Turn on verbose debugging.
137 -e, --explicit_domain STRING:
139 With -A, use STRING as the default domain rather than deriving
140 from the IP address connected to.
141 (default NULL)
142 -F, --log_facility FACILITY:
144 Facility to log to. If the facility has a leading '/' then it
145 will be treated as a file. If is "-" or "+" then log to stdout
146 or stderr respectively. Otherwise it is assumed to be the name
147 of a syslog facility. See syslog.conf(5) for valid syslog facil‐
148 ity names.
149 (default "mail")
150 Notes: If an error occurs before options are read it may be
151 logged to stderr. If stdout or stderr is specified as the facil‐
152 ity, then the process will not fork and detach from the termi‐
153 nal.
154 -f, --config_file FILENAME:
156 Name of config file to read. Command line options override
157 options set in config file.
158 The default is derived as follows:
160 The sysconfig dir ("/etc/perdition" for example) is checked for
162 <basename>.conf. If this is found then it is used. So if perdi‐
163 tion is invoked as /usr/sbin/perdition.pop3, and /etc/perdi‐
164 tion/perdition.pop3.conf exists then it will be used.
165 Next the sysconfig dir is checked for peridtion.<protocol>.conf,
167 where protocol is the ASCII representation of the protocol being
168 used, one of "imap4", "imap4s", "pop3", "pop3s" or "manage‐
169 sieve". So if perdition is being run in imap4 mode, and
170 /etc/perdition/perdition.imap4.conf exists, then it is used.
171 Note that the protocol name is lowercase.
172 Next the sysconfig dir is checked for perdition.conf, if it is
174 found then it is used.
175 If none of these files are found then no configuration file is
177 used.
178 -g, --group GROUP:
180 Group to run as.
181 (default "nobody")
182 -h, --help:
184 Display this message
185 -I, --capability STRING:
187 Deprecated in favour of --pop_capability and --imap_capability
188 --imap_capability STRING:
190 Capabilities for IMAP3 and IMAP4S
191 This string is taken as a string literal that will be returned
193 when a client issues the CAPABILITY command. As such the capa‐
194 bilities should be space delimited. The default is "IMAP4
195 IMAP4REV1". However, perdition does support RFC 2088 non-syn‐
196 chronising string literals, if the real servers also support
197 this then the capability may be set to "IMAP4 IMAP4REV1 LIT‐
198 ERAL+".
199 If perdition is running with ssl_mode includes to ssl_listen
201 then the capability STARTTLS will be appended to the list of
202 capabilities if it is not already present. Similarly this capa‐
203 bility will be removed from the list of capabilities if present
204 and perdition is not running with an ssl_mode that includes to
205 ssl_listen.
206 Perdition may also manipulate the capability in IMAP mode to add
208 and remove the LOGINDISABLED capability if the no_login capabil‐
209 ity is in effect or if the ssl_mode includes tls_listen_force or
210 tls_outgoing_force.
211 -i, --inetd_mode:
213 Run in inetd mode
214 -L, --connection_limit LIMIT:
216 Maximum number of connections to accept simultaneously. A value
217 of zero sets no limit on the number of simultaneous connections.
218 (default 0)
219 -l, --listen_port PORT_NUMBER|PORT_NAME:
221 Port to listen on.
222 The default is 110, 995, 143, 993 and 4190 for POP3, POP3S,
224 IMAP4, IMAP4S and MANAGESIEVE mode respectively.
225 --login_disabled:
227 Do not allow users to log in. Also adds LOGINDISABLED to capa‐
228 bility list in IMAP4 and IMAP4S mode.
229 --log_passwd STATE:
231 Log the users password.
232 (default "never")
233 fail: log the password on failed connection attempts.
235 ok: log the password on successful connection attempts.
237 never: never log the password
239 always: always log the password
241 Note: -d|--debug must be specified for this option to take
243 effect.
244 --lower_case state[,state...]:
246 Convert usernames to lower case according the the locale in
247 given state(s). See A|add_domain for a description of the
248 states.
249 (default "(null)")
250 --managesieve_capability STRING:
252 Capabilities for ManageSieve
253 This string is taken as a string literal that will be returned
255 when a client connects or issues the CAPABILITY command. As such
256 the capabilities should be quoted, using escape char \, and dou‐
257 ble space delimited.
258 If perdition is running with ssl_mode includes to ssl_listen
260 then the capability STARTTLS will be appended to the list of
261 capabilities if it is not already present. Similary this capa‐
262 bility will be removed from the list of capabilities if present
263 and perdition is not running with an ssl_mode that includes to
264 ssl_listen.
265 Examples
267 Two options, each with a value
269 "\"OPTION1\" \"VALUE\" \"OPTION2\" \"VALUE\""
270 Two options, but only one with a value
272 "\"OPTION1\" \"OPTION2\" \"VALUE\""
273 (default ""IMPLEMENTATION" "perdition" "SIEVE" "comparator-i;
275 octet comparator-i;ascii-casemap fileinto reject envelope
276 encoded-character vacation subaddress comparator-i;ascii-numeric
277 relational regex imap4flags copy include variables body enotify
278 environment mailbox date" "SASL" "PLAIN" "NOTIFY" "mailto"
279 "VERSION" "1.19-rc2"")
280 -M, --map_library FILENAME:
282 Library to open that provides functions to look up the server
283 for a user. An empty ("") library means that no library will be
284 accessed and hence, no lookup will take place.
285 (default "/usr/lib/libperditiondb_gdbm.so.0")
286 -m, --map_library_opt STRING:
288 String option to pass to database access function provided by
289 the library specified by the map_library directive. The treat‐
290 ment of this string is up to the library. See perditiondb(5) for
291 more details of how individual map_libraries handle this string.
292 (default "")
293 --no_daemon:
295 Do not detach from terminal. Makes no sense if inetd_mode is in
296 effect.
297 -n, --no_lookup:
299 Disable host and port lookup, implies no_bind_banner. Please
300 note that if this option is enabled, then perdition will not
301 resolve host or port names returned by popmap lookups, thus,
302 your popmap must return ip addresses and port numbers.
303 -O, --ok_line:
305 Use STRING as the OK line to send to the client. Overridden by
306 server_resp_line. OK and will be prepended to STRING, and in
307 IMAP mode a tag will also be prepended to the string.
308 (default "You are so in")
309 --server_ok_line:
311 This option is deprecated and may be removed in a future
312 release. Use server_resp_line instead. If authentication with
313 the real-server is successful then send the servers +OK line to
314 the client, instead of generating one.
315 -o, --server_resp_line:
318 If authentication with the real-server is successful then
319 send the servers response line to the client, instead of
320 generating one.
321 -P, --protocol PROTOCOL:
323 Protocol to use.
324 (default "POP3") available protocols: "POP3, POP3S,
325 IMAP4, IMAP4S"
326 -p, --outgoing_port PORT:
328 Default real-server port.
329 See listen_port for defaults.
330 -s, --outgoing_server SERVER[,SERVER...]:
332 Define a server to use if a user is not in the popmap.
333 Format is servername|ip_address[:portname|portnumber].
334 Multiple servers may be delimited by a ','. If multiple
335 servers are specified then they are used in a round robin
336 fashion.
337 (default "")
338 --pid_file FILENAME:
340 Path for pidfile. Must be a full path starting with a
341 '/'. To allow perdition to remove the pid file after the
342 owner of the perdition process is changed to a non-root
343 user, it is advised to specify a pid file in a subdirec‐
344 tory of the system var state directory (usually
345 /var/run). This subdirectory should be unique to this
346 perdition invocation and will be created and have its
347 owner and permissions set to allow perdition to subse‐
348 quently removed the pid file.
349 Empty for no pid file. Not used in inetd mode.
350 (default <var_state_dir>/<basename>/<basename>.pid)
351 --pop_capability STRING:
353 Capabilities for POP3 and POP3S
354 The capabilities should be delimited by a '.' spaces. Up
356 until perdition 1.18 the delimiter was two spaces, " ".
357 This is now deprecated and it is not valid to mix delim‐
358 iters.
359 The default capability is "UIDL.USER".
361 If perdition is running with ssl_mode includes to
363 ssl_listen then the capability STLS will be appended to
364 the list of capabilities if it is not already present.
365 Similarly this capability will be removed from the list
366 of capabilities it is present and perdition is not run‐
367 ning with an ssl_mode that includes to ssl_listen.
368 -S, --strip_domain STATE[,STATE]:
370 Allow USER of the from user<delimiter>domain where
371 <delimiter>domain will be striped off in given
372 state(s).See add_domain for a description of the states.
373 -t, --timeout SECONDS:
375 Idle timeout for post-authentication phase. Zero for
376 infinite timeout.
377 (default 1800)
378 --tcp_keepalive:
380 Turn on TCP Keep-Alive (see RFC 1122). This will turn on
381 TCP Keep-Alive for both incoming connections from clients
382 as well as connections made to the real POP3, IMAP4 or
383 managesieve server.
384 (default is disabled)
385 -u, --username USERNAME:
387 User to run as.
388 (default "nobody")
389 -U, --username_from_database:
391 If the servername in the popmap specified in the form:
392 user<delimiter>domain then use the username given by the
393 servername. If a servername is given in this form then
394 the domain will be used as the server to connect to,
395 regardless of this option.
396 -q, --quiet:
398 Only log errors. Overridden by debug
399 --query_key FORMAT[,FORMAT...]:
401 Instead of using the username as supplied by the end
402 user, possibly modified by strip_domain, use the formats
403 specified. The formats will be used in order to query the
404 popmap. The result from the first successful lookup will
405 be used. The format is comprised of a string of charac‐
406 ters, delimited by ','. The following escape codes are
407 valid:
408 \U: Long Username, the entire string supplied by
410 the end user, less any effects of
411 --strip_domain.
412 \u: Short Username, the portion Long Username
413 before the domain delimiter.
414 \D: Domain Delimiter, as specified by
415 --domain_delimiter
416 \d: Domain the portion Long Username after the
417 domain delimiter.
418 \i: Source IP address of the connection
419 \I: Destination IP address of the connection
420 \p: Source port of the connection
421 \P: Destination port of the connection
422 \\: Literal \
423 As a ',' is the delimiter between formats, it cannot
425 appear within a format. All other characters other than
426 the escape codes above, and ',' are treated as literals.
427 Examples
429 Use the supplied username, the default behaviour
431 \U
432 Use the user portion of the supplied username, if this
434 doesn't work try the domain portion of the supplied user‐
435 name preceded by the domain delimiter
436 \u,\D\d
437 Use the destination IP address
439 \I
440 Escape codes interspersed with literals
442 \u\da_domain,\da_domain
443 The options below relate to SSL/TLS support. They are not
445 available if perdition is compiled without SSL support.
446 --ssl_mode MODE:
448 Use SSL and or TLS for the listening and/or outgoing con‐
449 nections. A comma delimited list of: none, ssl_listen,
450 ssl_outgoing, ssl_all, tls_listen, tls_outgoing, tls_all,
451 tls_listen_force, tls_outgoing_force, tls_all_force. TLS
452 is defined in RFC 2595.
453 (default "(null)")
454 none: Do not use SSL or TLS for any connections. This is
456 the same as providing no option, the default.
457 ssl_listen: When listening for incoming connections they
459 will be treated as SSL connections.
460 ssl_outgoing: Use SSL to connect to real pop/imap
462 servers.
463 ssl_all: Short-Hand for ssl_listen,ssl_outgoing.
465 tls_listen: When listening for incoming connections they
467 will be treated as TLS connections.
468 tls_outgoing: Use TLS to connect to real pop/imap
470 servers.
471 tls_all: Short-Hand for tls_listen,tls_outgoing.
473 tls_listen_force: Do not accept plain text authentica‐
475 tion. In IMAP4 and IMAP4S mode, the LOGINDISABLED capa‐
476 bility until TLS has been initialised by the client issu‐
477 ing a STARTTLS. In all modes mode plain-text authentica‐
478 tion is ignored. Also sets tls_listen.
479 tls_outgoing_force: Do not send authentication informa‐
481 tion if TLS cannot be negotiated. Also sets tls_outgo‐
482 ing.
483 tls_all_force: Short-Hand for tls_listen_force,tls_outgo‐
485 ing_force.
486 --ssl_ca_chain_file:
488 Sets the optional all-in-one file where you can assemble
489 the certificates of Certification Authorities (CA) which
490 form the certificate chain of the server certificate.
491 This starts with the issuing CA certificate of the
492 "ssl_cert_file" certificate and can range up to the root
493 CA certificate. Such a file is simply the concatenation
494 of the various PEM-encoded CA Certificate files, usually
495 in certificate chain order. Overrides ssl_ca_file and
496 ssl_ca_path.
497 (default NULL, no CA certificate will be used)
498 --ssl_ca_file FILENAME:
500 Certificate Authorities to use when verifying certifi‐
501 cates of real servers. Used for SSL or TLS outgoing con‐
502 nections. When building the Certificate Authorities
503 chain, ssl_ca_file is used first, if set, and then
504 ssl_ca_path, if set. See SSL_CTX_load_verify_loca‐
505 tions(3) for format details.
506 (default "/etc/perdition/perdition.ca.pem")
507 --ssl_ca_path PATHNAME:
509 Certificate Authorities to use when verifying certifi‐
510 cates of real servers. Used for SSL or TLS outgoing con‐
511 nections. "openssh c_rehash" should be run in this
512 directory when new certificates are added. When building
513 the Certificate Authorities chain, ssl_ca_file is used
514 first, if set, and then ssl_ca_path, if set. See
515 SSL_CTX_load_verify_locations(3) for details.
516 (default "/etc/perdition/perdition.ca/")
517 --ssl_ca_accept_self_signed:
519 Accept self-signed certificate authorities.
520 --ssl_cert_file FILENAME:
522 Certificate to use when listening for SSL or TLS connec‐
523 tions. Should be in PEM format.
524 (default "/etc/perdition/perdition.crt.pem")
525 --ssl_dh_params_file FILENAME:
527 Diffie-Hellman parameters to use when offering EDH
528 ciphersuites to clients. Should be in PEM format.
529 (default: look for DH parameters in ssl_cert_file)
530 --ssl_cert_accept_self_signed:
532 Accept self-signed certificates. Used for SSL or TLS
533 outgoing connections.
534 --ssl_cert_accept_expired:
536 Accept expired certificates. This includes server cer‐
537 tificates and certificate authority certificates. Used
538 for SSL or TLS outgoing connections.
539 --ssl_cert_accept_not_yet_valid:
541 Accept certificates that are not yet valid. This includes
542 server certificates and certificate authority certifi‐
543 cates. Used for SSL or TLS outgoing connections.
544 --ssl_cert_verify_depth DEPTH:
546 Chain Depth to recurse to when verifying certificates.
547 Used for SSL or TLS outgoing connections.
548 (default 9)
549 --ssl_key_file FILENAME:
551 Public key to use when listening for SSL or TLS connec‐
552 tions. Should be in PEM format.
553 (default "/etc/perdition/perdition.key.pem")
554 --ssl_listen_ciphers STRING:
556 Cipher list when listening for SSL or TLS connections as
557 per ciphers(1). If empty ("") then openssl's default will
558 be used.
559 (default "")
560 --ssl_outgoing_ciphers STRING:
562 Cipher list when making outgoing SSL or TLS connections
563 as per ciphers(1). If empty ("") then openssl's default
564 will be used.
565 (default "")
566 --ssl_no_cert_verify:
568 Don't cryptographically verify the certificates. Used
569 for SSL or TLS outgoing connections.
570 --ssl_no_client_cert_verify:
572 Don't cryptographically verify the end-user's certifi‐
573 cate. Used for SSL or TLS outgoing connections.
574 --ssl_no_cn_verify:
576 Don't verify the real-server's common name with the name
577 used. to connect to the server. Used for SSL or TLS out‐
578 going connections.
579 --ssl_passphrase_fd N:
581 File descriptor to read the passphrase for the certifi‐
582 cate from. Only the first line will be read. Only one
583 of ssl_passphrase_fd and ssl_passphrase_file may be spec‐
584 ified. (default 0)
585 --ssl_passphrase_file FILENAME:
587 File to read the passphrase for the certificate from.
588 Only the first line will be read. Only one of
589 ssl_passphrase_fd and ssl_passphrase_file may be speci‐
590 fied. (default NULL, no file)
591 --ssl_listen_ciphers STRING:
593 Cipher list when listening for SSL or TLS connections as
594 per ciphers(1). If empty ("") then openssl's default will
595 be used.
596 (default "")
597 --ssl_outgoing_ciphers STRING:
599 Cipher list when making outgoing SSL or TLS connections
600 as per ciphers(1). If empty ("") then openssl's default
601 will be used.
602 (default "")
603 --ssl_no_cert_verify:
605 Don't cryptographically verify the certificates. Used
606 for SSL or TLS outgoing connections.
607 --ssl_no_client_cert_verify:
609 Don't cryptographically verify the end-user's certifi‐
610 cate. Used for SSL or TLS outgoing connections.
611 --ssl_no_cn_verify:
613 Don't verify the real-server's common name with the name
614 used. to connect to the server. Used for SSL or TLS out‐
615 going connections.
616 --ssl_passphrase_fd N:
618 File descriptor to read the passphrase for the certifi‐
619 cate from. Only the first line will be read. Only one
620 of ssl_passphrase_fd and ssl_passphrase_file may be spec‐
621 ified. (default 0)
622 --ssl_listen_min_proto_version PROTOCOL_VERSIONS:
624 Minimum permited SSL/TLS protocol version when accepting
625 incomming connections. May not be empty ("").
626 The valid protocol versions are sslv3, tlsv1, tlsv1.1 and
628 tlsv1.2.
629 (default "tlsv1")
631 --ssl_outgoing_min_proto_version PROTOCOL_VERSIONS:
633 Minimum permited SSL/TLS protocol version when making
634 outgoing connections. May not be empty ("").
635 The valid protocol versions are sslv3, tlsv1, tlsv1.1 and
637 tlsv1.2.
638 (default "tlsv1")
640 --ssl_listen_max_proto_version PROTOCOL_VERSIONS:
642 Maximum permited SSL/TLS protocol version when accepting
643 incommaxg connections. If empty ("") then openssl's
644 default will be used.
645 The valid protocol versions are sslv3, tlsv1, tlsv1.1 and
647 tlsv1.2.
648 (default "")
650 --ssl_outgoing_max_proto_version PROTOCOL_VERSIONS:
652 Maximum permited SSL/TLS protocol version when making
653 outgoing connections. If empty ("") then openssl's
654 default will be used.
655 The valid protocol versions are sslv3, tlsv1, tlsv1.1 and
657 tlsv1.2.
658 (default "")
660 --ssl_listen_compression:
662 Allow SSL/TLS compression when accepting incoming connec‐
663 tions.
664 --ssl_outgoing_compression:
666 Allow SSL/TLS compression when making outgoing connec‐
667 tions.
668 --ssl_no_cipher_server_preference:
670 Disable SSL/TLS cipher server preference when accepting
671 incoming connections.
672 Notes: Default value for binary flags is off.
674 If a string argument is empty ("") then the option will
675 not be used unless noted otherwise.
676 The defaults given refer to the values if perdition is
677 compiled with --sysconfdir=/etc as it would for many
678 binary distributions. For the actual defaults of a given
679 perdition binary run "perdition --help"
680
682 For information on mechanisms for resolving users to a host and
683 port and information on the -M|--map_library and
684 -m|--map_library_opt flags, please see perditiondb(5).
685 Note that by specifying an map library no map lookups will occur
687 and all connections will use the -s|--outgoing_server. In this
688 way perdition can be configured as a "pure proxy".
689
691 Normally perdition will bind to a port, and listen for connec‐
692 tions. The default port is 110 in POP3 mode and 143 in IMAP4
693 mode, an alternate port can be specified with the -l|--lis‐
694 ten_port command line option. In this mode perdition will fork
695 to manage clients.
696 Stand-Alone Mode: Debian and RPM Installation
698 In the Debian and RPM distributions perdition can be started and
700 stopped in stand-alone mode using:
701 /etc/init.d/perdition start
703 /etc/init.d/perdition stop
704 Editing /etc/sysconfig/perdition (RPM) or /etc/default/perdition
706 (Debian) allows control of whether perdition will be started in
707 POP3 mode, IMAP4 mode or both (or neither).
708 The syntax for this file is:
710 RUN_PERDITION=[yes|no]
712 FLAGS="flags"
713 POP3=[yes|no]
714 POP3_FLAGS="flags"
715 POP3S=[yes|no]
716 POP3S_FLAGS="flags"
717 IMAP4=[yes|no]
718 IMAP4_FLAGS="flags"
719 IMAP4S=[yes|no]
720 IMAP4S_FLAGS="flags"
721 The file is sourced into the init script so normal bash syntax
723 applies. Blank lines are ignored, as is anything after a # on a
724 line.
725 e.g.
727 RUN_PERDITION=yes
729 POP3=on
730 POP3_FLAGS="--ssl_mode tls_listen"
731 POP3S=on
732 IMAP4_FLAGS="--ssl_mode tls_listen"
733 IMAP4=on
734 POP3S_FLAGS="--ssl_mode ssl_listen -p 110"
735 IMAP4S=on
736 IMAP4S_FLAGS="--ssl_mode ssl_listen -p 143"
737
739 Perdition can be used in conjunction with inetd. This enables
740 perdition to benefit from tcpd where access can be controlled to
741 some extent using /etc/hosts.allow and /etc/hosts.deny. Sample
742 /etc/inetd.conf entries follow:
743 pop3 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdi‐
745 tion.pop3 -i
746 pop3s stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdi‐
747 tion.pop3s -i
748 imap2 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdi‐
749 tion.imap4 -i
750 imaps stream tcp nowait root /usr/sbin/tcpd /usr/sbin/perdi‐
751 tion.imap4s -i
752 inetd should then be restarted
754
756 If perdition has been compiled against libpam, it may be set up
757 to authenticate the user locally once the USER and PASS commands
758 are entered by specifying the -a|--authenticate_in option on the
759 command line. This authentication happens before the connection
760 to the foreign server is made and must succeed for a connection
761 to the foreign server to be made.
762 This authentication uses PAM and a sample pam configuration file
764 for perdition can be found in etc/pam.d/perdition in the source
765 tree. This should be dropped into /etc/pam.d.
766
768 A multi character domain delimiter can be set using the
769 -d|--domain delimiter option. This sets the delimiter used in
770 conjunction with the -S|--strip_domain and
771 -c|--client_server_specification options.
772
774 If perdition is invoked with the -c|--client_server_specifica‐
775 tion flag then the user may optionally specify the server and
776 port that perdition should connect to for the client using the
777 syntax user<delimiter>host[:port].
778 Example:
780 IMAP4
781 0 login henry@that.host:143
783 POP3
785 user james@other.host
787
789 Perdition allows two idle timeouts to be configured. --authenti‐
790 cation_timeout is used before the user has been successfully
791 authenticated with the back-end server. And after that --timeout
792 is used.
793 The default value for both timeouts is is 1800. A timeout value
795 of 0 means that the timeouts are disabled and clients and
796 back-end servers can idle indefinitely, though in practice a TCP
797 timeout will be in effect.
798
800 The greeting that perdition displays when accepting an incoming
801 connection is "+OK POP3 Ready <hostname>" or "* OK IMAP4 Ready
802 <hostname>" in POP3 and IMAP4 modes respectively. If when perdi‐
803 tion connects to the back-end server the greeting string matches
804 the greeting string of the perdition process making the connec‐
805 tion then it is assumed that perdition is connecting to itself
806 and a "Re-Authentication Failure" is returned to the client.
807
809 The format of a line of the configuration file is:
810 <key> <value>
812 Key is either a short or long option as per perdition -h|--help,
814 without the leading - or --. Blank lines are ignored, as is
815 anything including and after a # (hash) on a line. If a \ pre‐
816 cedes a new line then the lines will be concatenated. IF a \
817 precedes any other character, including a # (hash) it will be
818 treated as a literal. Anything inside single quotes (') will be
819 treated as a literal. Anything other than a (') inside double
820 quotes (") will be treated as a literal. Whitespace in keys must
821 be escaped or quoted. Whitespace in values need not be escaped
822 or quoted.
823 Options that do not make sense in the configuration file such as
825 h|help and f|config_file are ignored. Options specified on the
826 command line override the options in this file.
827 Example configuration File.
829 # perdition.conf
830 l 110 #Short option used as key
831 group mail #Long option used as key
832 a #Option with no argument
833
835 Perdition supports POP before SMTP in both POP3 and IMAP4 mode
836 by logging having logging the following messages:
837 When a user connects:
839 Connect: <from_to> [inetd_pid=<pid>]
841 When a user is authenticated
843 Auth: <from_to> client-secure=SECURE_STATUS authorisa‐
845 tion_id="<authorisation_id>" authentication_id="<authentica‐
846 tion_id>" password="<password>" server="<servername>:<port>"
847 protocol=<protocol> server-secure=SECURE_STATUS sta‐
848 tus=failed...|ok
849 When a user disconnects
851 Close: <from_to> authorisation_id="<authorisation_id>" authenti‐
853 cation_id="<authentication_id>" received=<bytes> sent=<bytes>
854 Where:
857 from_to is
859 <src_ip_address>:<src_port>-><dest_ip_address>:<dest_port>
860 SECURE_STATUS is one of:
863 ssl: Uses SSL/TLS from the beginning of the connection. That
866 is, IMAPS or POP3S.
867 starttls: A STARTTLS or STLS command has been issued and SSL/TLS
870 was subsequently negotiated.
871 Note that if the message is logged before SSL/TLS negotiation
873 completed then the status will be plaintext. Even if the connec‐
874 tion would have used starttls if successful. For example, if
875 connecting to the real-server fails.
876 plaintext: SSL/TLS is not in use.
879
882 By default, logs are logged via syslog using the facility mail.
883 You should inspect /etc/syslog.conf to find where these logs are
884 written. Under Debian these logs will be written to
885 /var/log/mail.log, under Red Hat 7.x these logs will be written
886 to /var/log/maillog, under Solaris 8 these logs will be written
887 to /var/log/syslog. Normally each session will have two perdi‐
888 tion log entries. Logs are prepended, depending on syslog with
889 the date, host, and perdition[<pid>]: .
890 Fatal errors are also logged with a priority of err. In
892 stand-alone mode the startup parameters are logged on initiali‐
893 sation. If the -d|--debug command line option or configuration
894 file directive is used then startup parameters are logged
895 regardless of other configuration directives and in both
896 stand-alone and identd mode additional debugging messages are
897 logged with a priority of debug. As the flag implies, this is
898 useful for debugging but is probably too verbose for production
899 systems. If the -q|--quiet command line option or configuration
900 file directive is used, only errors will be logged. This is
901 overridden by -d|--debug.
902
904 Perdition supports using SSLv2 and SSLv3 to encrypt sessions
905 between end users and perdition and sessions between perdition
906 and real servers. SSL may be used for either, both or none of
907 these classes of connections.
908 The public key and certificate files should be in PEM format.
910 As a quick guide, the files may be generated using openssl with
911 the following command:
912 openssl req -new -x509 -nodes \
914 -out perdition.crt.pem -keyout perdition.key.pem -days 365
915
917 Perdition can be used in a mixed-mode where the end-users con‐
918 nect to perdition using SSL and then perdition connects to the
919 real-servers using palin-text. Or vice versa. This is achieved
920 using --ssl_mode and at least one of -l|--listen_port and
921 -p|--outgoing_port. When running this kind of configuration
922 -P|--protocol values of IMAP and IMAPS are equivalent and like‐
923 wise POP3 and POP3S are equivalent.
924 For example, to accept connections from end-users using POP3S on
926 port 995 (the default POP3S port) and communicate with the real-
927 servers using POP3 on port 110 (the default POP3 port) the fol‐
928 lowing are equivalent.
929 --ssl_mode=ssl_listen --protocol=POP3S --outgoing_port=110
931 and
933 --ssl_mode=ssl_listen --protocol=POP3 --incoming_port=995
935 Perdition is not able to listen for connections from end-users
937 using POP3/POP3S and communicate with real-servers using
938 IMAP4/IMAP4S or vice-versa.
939
941 /etc/perdition/perdition.conf
942
944 perditiondb(5), inetd(8), syslog.conf(5), syslogd(8)
945
947 Lead
948 Horms <horms@verge.net.au>
949 Perditiondb Library Authors
951 Frederic Delchambre <dedel@freegates.be> (MySQL)
952 Chris Stratford: <chriss@uk.uu.net> (LDAP and Berkeley
953 DB)
954 Nathan Neulinger <nneul@umr.edu> (NIS)
955 Contributing Authors
957 Daniel Roesen <droesen@entire-systems.com>
958 Clinton Work <work@scripty.com>
959 Youri <ya@linkline.be>
960 Jeremy Nelson <jnelson@optusnet.com.au>
961 Wim Bonis <bonis@solution-service.de>
962 Arvid Requate <arvid@Team.OWL-Online.DE>
963 Mikolaj J. Habryn <dichro@rcpt.to>
964 Ronny Cook <ronny@asiaonline.net>
965 Geoff Mitchell <g.mitchell@videonetworks.com>
966 Willi Langenberger <wlang@wu-wien.ac.at>
967 Matt Prigge <mprigge@pobox.com>
968 Wolfgang Breyha <wolfgang.breyha@uta.at>
969 12th June 2003 PERDITION(8)