TPOP3D.CONF(5) TPOP3D.CONF(5) NNAAMMEE tpop3d.conf - configuration file for ttppoopp33dd(8) SSYYNNOOPPSSIISS ## _c_o_m_m_e_n_t _k_e_y:: _v_a_l_u_e _k_e_y:: _v_a_l_u_e \\ _c_o_n_t_i_n_u_a_t_i_o_n _o_f _v_a_l_u_e ... DDEESSCCRRIIPPTTIIOONN The ttppoopp33dd configuration file, ttppoopp33dd..ccoonnff, consists of a number of _k_e_y: _v_a_l_u_e pairs. Blank lines and comments introduced by `#' are ignored. It is legal for _v_a_l_u_e to be blank. Presently-recognised configuration directives are: GGlloobbaall ooppttiioonnss lliisstteenn--aaddddrreessss: _a_d_d_r_e_s_s[::_p_o_r_t][((_d_o_m_a_i_n))|//_r_e_g_e_x//][;;_t_l_s_-_o_p_t_i_o_n_s] ... Specify an _a_d_d_r_e_s_s and optional _p_o_r_t on which incoming connections are accepted. _d_o_m_a_i_n is the domain name for which the service is operated; alternatively, if mass virtual hosting support is compiled in (the default), then you can specify _r_e_g_e_x, a POSIX extended regular expression contain- ing a single bracketed subexpression, instead of _d_o_m_a_i_n; in this case, the regular expression is applied (in a case-insensitive sense) to the name of the host to which the client has connected, and the matching subexpression is used as the domain name. This only really makes sense if _a_d_d_r_e_s_s is 00..00..00..00 (INADDR_ANY). If neither _d_o_m_a_i_n nor _r_e_g_e_x are given, the portion of the name associated with the given _a_d_d_r_e_s_s following the first `.' is used, or, if no such name can be established, the node- name of the system determined by uunnaammee(2). If any _p_o_r_t is not specified, it is assumed to be 111100 (pop-3), or 999955 (pop-3s) if in `immediate' TLS mode. If ttppoopp33dd has been compiled with support for TLS (`SSL'), then you may specify additional _t_l_s_- _o_p_t_i_o_n_s for each address, in the following form: ttllss==(iimmmmeeddiiaattee|ssttllss),,_c_e_r_t_i_f_i_c_a_t_e[,,_p_r_i_v_a_t_e_-_k_e_y] The first token after ttllss== specifies the mode of TLS operation in use on this address. There are two widely-supported modes of POP-3-over-TLS operation. In the first case, which we call iimmmmeeddiiaattee mode, TLS negotiation is initiated immediately after a connection is received. In this mode, only TLS con- nections can be made to a particular address. In the other mode, the client establishes an unen- crypted TCP connection, then issues the POP-3 com- mand SSTTLLSS to initiate TLS negotiation. We call this ssttllss mode. This mode permits unencrypted and TLS operation on the same address. The cryptographic identity to use for this address is read from the files named by _c_e_r_t_i_f_i_c_a_t_e and _p_r_i_v_a_t_e_-_k_e_y. If only _c_e_r_t_i_f_i_c_a_t_e is given, then both the certificate and the private key should be contained in the one file. If a pass-phrase is required to make use of the certificate or private key, then ttppoopp33dd must be started with the --PP option (see ttppoopp33dd(8)) to read the pass phrase from the terminal. To listen for connections on any interface and the default port, the directive listen-address: 0.0.0.0 is sufficient. To specify a specific domain, use this syntax: listen-address: 12.34.56.78(example.com) 0.0.0.0(example.org) If, alternatively, the machine has numerous inter- faces with names ppoopp33..eexxaammppllee..ccoomm, ppoopp33..eexxaamm-- ppllee..oorrgg, etc., you could specify listen-address: 0.0.0.0/^pop3\.(.*)$/ to accept incoming connections and associate them with the proper domains. Note that for this to work, all interfaces on which connections are to be accepted must have functioning inverse name resolu- tion; also, in this case, ttppoopp33dd will do a name lookup for each incoming connection, which may block in the event of a DNS failure. You may wish to create some other mapping -- perhaps in /etc/hosts -- to ensure that this does not occur. mmaaxx--cchhiillddrreenn: _n_u_m_b_e_r The maximum number of child processes which may be actively serving connections at any given time. Consists of a single number. By default, this is set to 100. aappppeenndd--ddoommaaiinn: (yyeess|ttrruuee) If authentication does not succeed for a given _u_s_e_r_n_a_m_e, retry with _u_s_e_r_n_a_m_e@_d_o_m_a_i_n, where _d_o_m_a_i_n is the domain name associated with the address on which the connection was received. This is intended to be used where multiple virtual domains are served from multiple IP addresses. This option only takes effect when _u_s_e_r_n_a_m_e does not contain a separator, which may be `@', `%', `:' or `!'. See below for a more detailed description. ssttrriipp--ddoommaaiinn: (yyeess|ttrruuee) If authentication does not succeed for a given _u_s_e_r_n_a_m_e, and the _u_s_e_r_n_a_m_e supplied is in the form _u_s_e_r_n_a_m_e@_d_o_m_a_i_n, try the authentication again with a bare _u_s_e_r_n_a_m_e. _d_o_m_a_i_n need not be the domain name associated with the address on which the con- nection was received. This is intended to be used where multiple domains are served by a single authenticator with the same username, such as when _u_s_e_r_n_a_m_e@_d_o_m_a_i_n_._c_o_m and _u_s_e_r_n_a_m_e@_d_o_m_a_i_n_._n_e_t are equivalent and served from the same machine. This option only takes effect when _u_s_e_r_n_a_m_e contains a separator, which may be `@', `%' or `!'. aappoopp--oonnllyy: (yyeess|ttrruuee) Disconnect any client which attempts plaintext USER/PASS authentication. The intention of this option is to discourage users from sending plain- text passwords over the network, so it has no effect when a user is connected over a TLS-secured connection. ttiimmeeoouutt--sseeccoonnddss: _n_u_m_b_e_r This is the number of seconds for which a connec- tion may be idle for before it is closed. If it is set to 0, then timeouts are disabled. The default value is 30 seconds (see the section on BUGS in ttppoopp33dd(8)). If you wish to have ttppoopp33dd comply explicitly with the RFC (which demands a ten-minute timeout), then specify 600 seconds. This may be necessary with some clients which pause randomly whilst downloading messages. lloogg--ffaacciilliittyy: _f_a_c_i_l_i_t_y This selects the `facility' as which ttppoopp33dd emits system log messages. Possible values for _f_a_c_i_l_i_t_y are: mmaaiill, aauutthhpprriivv, ddaaeemmoonn, uusseerr, and llooccaall00 through llooccaall77 inclusive. (Although other possi- bilities are mentioned in ooppeennlloogg(3), they don't make much sense for a POP3 server.) lloogg--ssttddeerrrr: (yyeess|ttrruuee) Send log messages to standard error as well as the system log. This makes sense only when ttppoopp33dd is running with a controlling terminal. nnoo--ddeettaacchh: (yyeess|ttrruuee) Do not detach from controlling terminal. The --dd command-line option to ttppoopp33dd is equivalent to com- bining this and the lloogg--ssttddeerrrr directives. mmaaiillbbooxx: [_m_a_i_l_b_o_x_-_d_r_i_v_e_r:]_p_a_t_h_-_s_p_e_c ... This selects the location, and optionally the type, of the mailbox to use when a user is authenticated. _M_a_i_l_b_o_x_-_d_r_i_v_e_r should be one of the names listed when you execute ttppoopp33dd --hh; if left blank the default (first available) one is used, but this is discouraged as it may vary between builds of tpop3d. _P_a_t_h_-_s_p_e_c should give a path name in the file system; you can use the substitution strings $$((uusseerr)), the username supplied to the POP server by the client; $$((llooccaall__ppaarrtt)), the local part of a client's email address in a virtual-domain authen- tication, $$((ddoommaaiinn)), the domain, and $$((hhoommee)) for the user's home directory. In addition, the syntax $$((ffoooo[[_i_n_d_e_x]])) may be used to select a given letter of the string. 0 is the first character, and -1 the last. This allows the used of `hashed' spool direc- tories; for example, mailbox: bsd:/var/spool/mail/$(user[0])/$(user) If several mailbox locations and types are speci- fied, ttppoopp33dd will try each in turn, stopping when it opens a mailbox or encounters an error other than the mailbox not being present. This means that if your users have both maildir and bsd mailboxes, you can use something like mailbox: maildir:$(home)/Maildir bsd:/var/spool/mail/$(user) to support both. Some authentication drivers will set the mailbox explicitly, overriding this option. Those that do not also have a specific option, of the form aauutthh-- ffoooo--mmaaiillbbooxx:: which overrides the global setting. mmaaiillssppooooll--iinnddeexx:: _p_a_t_h_-_s_p_e_c This selects the location of metadata cache files for BSD mailspools, based on their file names. This option is only available when ttppoopp33dd is compiled with metadata caching enabled, and it is only switched on when this option is specified. _P_a_t_h_-_s_p_e_c gives the location of the metadata cache file, using substitution strings similar to those for the mmaaiillbbooxx option above. In particular, you can use $$((nnaammee)), the full name of the mailspool; $$((ppaatthh)), the directory containing the mailspool; $$((ffiillee)), the file name of the mailspool (the part after the final `/'); and $$((eessccaappeedd__nnaammee)), which is the full name of the mailspool escaped using the HTTP-style %%.... convention so that it does not con- tain any slashes. Examples include: mailspool-index: $(name).tpop3d-index mailspool-index: /var/spool/tpop3d/$(escaped_name) In order to use this facility, ttppoopp33dd must be able to write the metadata cache files to the locations specified. If you choose to use a specific direc- tory for this (for instance, /var/spool/mail or /var/spool/tpop3d), you will need to set appropri- ate permissions. 1777 (as for /tmp) is probably the best choice. ttppoopp33dd will overwrite any file whose name is the same as the specified cache file for a given mailspool; therefore, it is recommended that the mailspool index files be stored in a directory to which users would not customarily have access, for instance /var/spool/tpop3d. mmaaiillddiirr--eexxcclluussiivvee--lloocckk: (yyeess|ttrruuee) Indicates that ttppoopp33dd should attempt to lock maildir mailboxes for exclusive access, so that it more closely follows the behaviour described in RFC1939. Even if not specified, ttppoopp33dd behaves intelligently when a message in a maildir is moved or deleted, so this option is not necessary. ttccpp--wwrraappppeerrss--nnaammee: _n_a_m_e This selects the `daemon name' used by ttppoopp33dd when it tests connections against the TCP Wrappers access-control-mechanism. This corresponds to the part of an entry before the first colon in hosts.allow or hosts.deny. If not specified, this will default to `tpop3d'. This feature is only available if ttppoopp33dd has been compiled with support for TCP Wrappers. ddrraacc--sseerrvveerr: _h_o_s_t_n_a_m_e If specified, gives the name of a server to which ttppoopp33dd should send DRAC notifications about suc- cessful logins. wwhhoossoonn--eennaabbllee: (yyeess|ttrruuee) Enable notification of successful logins to a WHO- SON server as defined in /etc/whoson.conf. ttllss--nnoo--bbuugg--wwoorrkkaarroouunnddss: (yyeess|ttrruuee) Disable workarounds for various bugs in client TLS implementations, as described in SSSSLL__ccttxx__sseett__ooppttiioonnss(3). Only available if ttppoopp33dd has been built with TLS support. OOppttiioonnss rreellaattiinngg ttoo aauutthheennttiiccaattiioonn ttppoopp33dd supports a number of authentication methods, each of which has a number of configurable options, which are given below. Authentication is supported using the conventional USER/PASS method, or the challenge-response APOP method. When a client connects to ttppoopp33dd and attempts authentica- tion, a request is passed to each of a number of config- ured authenticators in turn, until the client is success- fully authenticated or all authenticators have been tried. The information supplied with each request consists of _u_s_e_r, the user name as supplied by the client; _l_o_c_a_l_-_p_a_r_t, the local-part of a virtual-domain email address, and _d_o_m_a_i_n, the domain in which authentication is taking place. By default, _d_o_m_a_i_n is the domain associated with the address to which the client has connected. If the client's supplied username contains one of the characters `@', `%', `:' or `!', it is interpreted as a _l_o_c_a_l_-_p_a_r_t@@_d_o_m_a_i_n combination, and the given _l_o_c_a_l_-_p_a_r_t is used while the given _d_o_m_a_i_n replaces the domain derived from the address to which the client connected. If there is no separator, authentication is first attempted with no _l_o_c_a_l_-_p_a_r_t and the default _d_o_m_a_i_n; if this does not succeed, and the aappppeenndd--ddoommaaiinn global option is set, then authentication will also be attempted with the _l_o_c_a_l_-_p_a_r_t the same as the supplied _u_s_e_r and the default domain. For example, if the client sends the command USER foo to the listener for domain `dom', ttppoopp33dd will try authen- tication with the parameters: _u_s_e_r = foo _l_o_c_a_l_-_p_a_r_t not set _d_o_m_a_i_n = dom If this fails, and aappppeenndd--ddoommaaiinn is set, then a second attempt will be made with: _u_s_e_r = foo _l_o_c_a_l_-_p_a_r_t = foo _d_o_m_a_i_n = dom Otherwise no second attempt is made. If instead the client says: USER foo@bar then authentication will be attempted using: _u_s_e_r = foo@bar _l_o_c_a_l_-_p_a_r_t = foo _d_o_m_a_i_n = bar In this case, no alternative attempt will be made if authentication fails. These global options apply to all authenticators: ppeerrmmiitt--eemmppttyy--ppaasssswwoorrdd: (yyeess|ttrruuee) If enabled, users may log in with an empty pass- word. (Note that their client _m_u_s_t send a space after the PASS command in this case.) oonnllooggiinn--cchhiilldd--wwaaiitt: (yyeess|ttrruuee) If enabled, and the authenticator offers an `onlo- gin' action to be taken when a user logs in, the user's mailbox won't be opened until _a_f_t_e_r the onlogin action completes (otherwise, the child does not block in this way). This is intended to allow you to use the onlogin feature to implement server bulletins and similar features. lloogg--bbaadd--ppaasssswwoorrddss: (yyeess|ttrruuee) Log incorrect passwords supplied by users who fail to log in. Use of this option is an invasion of privacy, but may be useful for debugging client configuration problems. ttppoopp33dd can cache the results of successful login attempts, and re-use them when the same user logs in again. This is probably not useful except for servers which run under very heavy load. Authentication cacheing can only be used for USER/PASS authentication; it has no effect on APOP authentications. The following options control the authentication cache: aauutthhccaacchhee--eennaabbllee: (yyeess|ttrruuee) Enable the cache. It is off by default. aauutthhccaacchhee--eennttrryy--lliiffeettiimmee: _n_u_m_b_e_r The number of seconds for which the results of a successful authentication are cached. The default value is 1 hour (3600 seconds). In order to be use- ful, this value must be much larger than the mean interval between POP sessions by a given client. For instance, if clients check mail every five min- utes, then setting the lifetime to ten minutes will mean that, on average, half of authentications come from the cache and are fast. Setting it to one hour means that eleven out of twelve authentications come from the cache, and so forth. _B_u_t _n_o_t_e _t_h_a_t _t_h_i_s _v_a_l_u_e _a_l_s_o _c_o_n_t_r_o_l_s _h_o_w _l_o_n_g _i_t _t_a_k_e_s _f_o_r _p_a_s_s_w_o_r_d _c_h_a_n_g_e_s _t_o _t_a_k_e _e_f_f_e_c_t_! aauutthhccaacchhee--uussee--cclliieenntt--hhoosstt: (yyeess|ttrruuee) Some authenticators allow you to control authenti- cation based on the IP address of the connected client. By default, the authentication cache ignores this information, so that a client which connects from more than one IP address (for instance, if their DHCP lease changes) can still be authenticated from the cache. But if you have authenticators whose behaviour varies based on client IP address, you must switch this option on, since otherwise the cache will give incorrect results in some cases. PPAAMM aauutthheennttiiccaattiioonn ooppttiioonnss aauutthh--ppaamm uses Pluggable Authentication Modules to authen- ticate conventional (non-virtual-domains) users. aauutthh--ppaamm--eennaabbllee: (yyeess|ttrruuee) Enable authentication using Pluggable Authentica- tion Modules. aauutthh--ppaamm--ffaacciilliittyy: _f_a_c_i_l_i_t_y Sets the PAM facility name used by ttppoopp33dd to _f_a_c_i_l_- _i_t_y. Defaults to ttppoopp33dd. aauutthh--ppaamm--mmaaiill--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) The group name or gid under which access to the mailspool will take place. The default for this option is the primary group of the authenticated user, which may not work. You will normally want to set this to `mail'. aauutthh--ppaamm--mmaaiill--uusseerr: (_u_s_e_r_-_n_a_m_e | _u_i_d) In normal operation, aauutthh--ppaamm will only authenti- cate users who have local accounts (i.e., for whom there exists a passwd entry and a distinct user ID). It is also possible to use PAM to authenticate arbitrary user names. This option names a local user whose credentials are used for users without local accounts who are authenticated by PAM. This option will not be useful in a typical configura- tion. PPaasssswwoorrdd aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with aauutthh-- ppaasssswwdd support. aauutthh--ppaasssswwdd authenticates Unix users by direct lookups in /etc/passwd and, if configured at com- pile time, /etc/shadow. aauutthh--ppaasssswwdd--eennaabbllee: (yyeess|ttrruuee) Enable authentication using /etc/passwd. aauutthh--ppaasssswwdd--mmaaiill--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) The group name or gid under which access to the mailspool will take place. The default for this option is the primary group of the authenticated user, which will probably not work. You will nor- mally want to set this to `mail'. MMyySSQQLL aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled tpop3d with aauutthh-- mmyyssqqll support. aauutthh--mmyyssqqll--eennaabbllee: (yyeess | ttrruuee) Enable MySQL authentication. aauutthh--mmyyssqqll--mmaaiill--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) The group name or gid under which access to the mailspool will take place. The default for this option is the primary group of the UNIX user asso- ciated with the virtual domain. aauutthh--mmyyssqqll--hhoossttnnaammee_: _h_o_s_t_n_a_m_e Host on which to connect to MySQL, by default llooccaallhhoosstt. You may specify several hosts, separated by spaces or tabs. These hosts are tried in order until one is found working. The same database name, username and password are tried on each host. aauutthh--mmyyssqqll--ddaattaabbaassee: _d_a_t_a_b_a_s_e MySQL database to use for authentication. aauutthh--mmyyssqqll--uusseerrnnaammee: _u_s_e_r_n_a_m_e MySQL username used to access the database. aauutthh--mmyyssqqll--ppaasssswwoorrdd: _p_a_s_s_w_o_r_d Password of MySQL user. aauutthh--mmyyssqqll--ppaassss--qquueerryy: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Query template to use for USER/PASS authentication. aauutthh--mmyyssqqll--aappoopp--qquueerryy: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Query template to use for APOP authentication. aauutthh--mmyyssqqll--oonnllooggiinn--qquueerryy: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Query template to use for POP-before-SMTP opera- tion. Since mailbox names are stored in the database, the aauutthh-- mmyyssqqll--mmaaiillbbooxx:: setting is ignored. AA nnoottee oonn MMyySSQQLL aauutthheennttiiccaattiioonn The MySQL authentication scheme is intended to be used with the vmail-sql virtual domains configuration described at _h_t_t_p_:_/_/_w_w_w_._e_x_-_p_a_r_r_o_t_._c_o_m_/_~_c_h_r_i_s_/_v_m_a_i_l_-_s_q_l_/, and by default the queries it uses work with that schema. However, it is also possible to use the aauutthh--mmyyssqqll--ppaassss-- qquueerryy and aauutthh--mmyyssqqll--aappoopp--qquueerryy directives to specify the SQL syntax for a query to use against any database schema. These should specify queries which return the mailbox file location, password hash, Unix user and mailbox type, in that order. The variables $$((uusseerr)), $$((llooccaall__ppaarrtt)) and $$((ddoommaaiinn)) are escaped and substituted into the string, in the same way as for the mailbox path specifications described above. In addition, the numerical IP address to which the client connected is substituted for $$((sseerrvveerr-- hhoosstt)). The nature of password hashes is described more fully in README.auth_mysql in the distribution. If you do not wish to use either of USER/PASS or APOP authentication, specify the value nnoonnee for the relevant configuration directive; otherwise, the default (vmail-sql) query will be used. As an example, if you have a table called users which con- tains fields login, domain, cryptpw and the Maildir mail- boxes for the users are under /path/to/$(domain)/$(local_part), then you could use auth-mysql-pass-query: \ SELECT CONCAT('/path/to/', '$(domain)', \ '/', '$(local_part)'), \ CONCAT('{crypt}', cryptpw), \ 'mail', 'maildir' \ FROM users \ WHERE login = '$(local_part)' \ AND domain = '$(domain)' The aauutthh--mmyyssqqll--oonnllooggiinn--qquueerryy specifies an SQL statement (most likely an INSERT or UPDATE) which is executed after a successful login. This is intended to allow you to insert a record into a database table used to permit relaying in a `POP-before-SMTP' scheme. For this query, the additional value $$((cclliieenntthhoosstt)) indicates the connected client host, as a numeric IP address. This statement will be executed for any successful login, not only aauutthh--mmyyssqqll logins. Note that $$((llooccaall__ppaarrtt)) may not be supplied for a given login, so you should only use it if you are sure that all relevant logins will specify it. See the descrip- tion of authentication, above, for more information. If more flexibility is required, consider using aauutthh--ootthheerr or aauutthh--ppeerrll instead. Note that the username and password supplied in the con- figuration file are privileged information, in the sense that they would allow an arbitrary person to obtain infor- mation from the database if they have access to the machine on which it resides. The corollary to this is that the ttppoopp33dd..ccoonnff file should not be readable by arbi- trary users. PPoossttggrreess aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with aauutthh-- ppggssqqll support. aauutthh--ppggssqqll--eennaabbllee: (yyeess | ttrruuee) Enable Postgres authentication. aauutthh--ppggssqqll--uusseerrnnaammee aauutthh--ppggssqqll--ppaasssswwoorrdd aauutthh--ppggssqqll--ddaattaabbaassee aauutthh--ppggssqqll--hhoossttnnaammee aauutthh--ppggssqqll--ppaassss--qquueerryy aauutthh--ppggssqqll--aappoopp--qquueerryy aauutthh--ppggssqqll--oonnllooggiinn--qquueerryy aauutthh--ppggssqqll--mmaaiill--ggrroouupp Behave like the equivalent aauutthh--mmyyssqqll options. LLDDAAPP aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with sup- port for aauutthh--llddaapp. aauutthh--llddaapp--eennaabbllee: (yyeess | ttrruuee) Enable LDAP authentication. aauutthh--llddaapp--uurrll: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Template giving an LDAP URL indicating the server against which to make authentication requests. Note that the variables $$((uusseerr)), $$((llooccaall__ppaarrtt)) and $$((ddoommaaiinn)) may appear _o_n_l_y in the DN part of the URL. aauutthh--llddaapp--ttllss: (yyeess | ttrruuee) Use an encrypted connection to contact the LDAP server. aauutthh--llddaapp--sseeaarrcchhddnn: _L_D_A_P _s_e_r_v_e_r _u_s_e_r_n_a_m_e DN to use when binding to LDAP server to search for a user. aauutthh--llddaapp--ppaasssswwoorrdd: _L_D_A_P _s_e_r_v_e_r _p_a_s_s_w_o_r_d Password of search user. aauutthh--llddaapp--ffiilltteerr: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Filter template to use when searching for a user's account. aauutthh--llddaapp--ssccooppee: (ssuubbttrreeee|bbaassee|oonneelleevveell) Scope of LDAP searches. If not specified, the default is `subtree'. aauutthh--llddaapp--mmaaiillbbooxx: [_m_a_i_l_b_o_x_-_d_r_i_v_e_r:]_p_a_t_h_-_s_p_e_c ... User mailbox location, as described above. or aauutthh--llddaapp--mmaaiillbbooxx--aattttrr: _a_t_t_r_i_b_u_t_e _n_a_m_e aauutthh--llddaapp--mmbbooxxttyyppee--aattttrr: _a_t_t_r_i_b_u_t_e _n_a_m_e LDAP attributes which contains the name of a user's mailbox, and its type. If the type is not speci- fied, or if the attribute is not present for a given user, the driver will guess that mailbox names which end `/' are of type maildir, otherwise of type bsd. aauutthh--llddaapp--mmaaiill--uusseerr: (_u_s_e_r_-_n_a_m_e | _u_i_d) aauutthh--llddaapp--mmaaiill--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) User and group under which access to the mailbox will take place. or aauutthh--llddaapp--mmaaiill--uusseerr--aattttrr: _a_t_t_r_i_b_u_t_e _n_a_m_e aauutthh--llddaapp--mmaaiill--ggrroouupp--aattttrr: _a_t_t_r_i_b_u_t_e _n_a_m_e LDAP attributes which specify the user and group under which access to the mailbox will take place. AA nnoottee oonn LLDDAAPP aauutthheennttiiccaattiioonn ttppoopp33dd uses a search-bind model for authenticating users against an LDAP server. When a user attempts to log in by supplying a username and password, ttppoopp33dd will attempt to locate an LDAP record for the user by substituting for $$((uusseerr)), $$((llooccaall__ppaarrtt)) and $$((ddoommaaiinn)) in the base DN given by aauutthh--llddaapp--uurrll and in the aauutthh--llddaapp--ffiilltteerr filter tem- plate, binding to the LDAP server as the search user, and querying the LDAP server with this filter. If the search yields exactly one result, then an attempt is made to bind to the server using the credentials supplied by the client. If the bind is successful, then the user is authenticated. Information about the user's account, in particular, the user and group id to use for mailbox access, and the loca- tion and type of the mailbox, may be obtained either from the directory, or from values in the configuration file. FFllaatt ffiillee aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with sup- port for aauutthh--ffllaattffiillee. aauutthh--ffllaattffiillee--eennaabbllee: (yyeess | ttrruuee) Enable flat file authentication. aauutthh--ffllaattffiillee--ppaasssswwdd--ffiillee: _s_u_b_s_t_i_t_u_t_i_o_n _s_t_r_i_n_g Specify the file in which ttppoopp33dd will search for a user's password. aauutthh--ffllaattffiillee--mmaaiill--uusseerr: (_u_s_e_r_-_n_a_m_e | _u_i_d) aauutthh--ffllaattffiillee--mmaaiill--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) User and group under which access to the mailbox will take place. AA nnoottee oonn ffllaatt ffiillee aauutthheennttiiccaattiioonn Flat files used for authentication consist of lines of _u_s_e_r::_p_a_s_s_w_o_r_d_-_h_a_s_h; any other fields following a subse- quent colon are ignored, so that //eettcc//ppaasssswwdd-style files may be used. The specified password hash is interpreted as a hash produced using ccrryypptt(3), unless it is preceded by a hashing scheme in {{}}. aauutthh--ffllaattffiillee may be used for APOP authentication if the password field consists of plaintext passwords preceded by {{ppllaaiinntteexxtt}}. The user and group under which access to the mailbox takes place with aauutthh-- ffllaattffiillee are always as specified in the configuration file. The file to be used is located by substituting for $$((ddoommaaiinn)) in the aauutthh--ffllaattffiillee--ppaasssswwdd--ffiillee filename tem- plate. EExxtteerrnnaall pprrooggrraamm ((``ootthheerr'')) aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with sup- port for aauutthh--ootthheerr. aauutthh--ootthheerr--eennaabbllee: (yyeess | ttrruuee) Enable external program authentication. aauutthh--ootthheerr--pprrooggrraamm: _p_a_t_h Program to use for external authentication; this must be an absolute path and should process requests as described below. aauutthh--ootthheerr--uusseerr: (_u_s_e_r_-_n_a_m_e | _u_i_d) aauutthh--ootthheerr--ggrroouupp: (_g_r_o_u_p_-_n_a_m_e | _g_i_d) The user and group under which to run the authenti- cation program. aauutthh--ootthheerr--ttiimmeeoouutt: _t_i_m_e The timeout in seconds for authentication; may be a fractional value, by default 0.75. AA nnoottee oonn eexxtteerrnnaall pprrooggrraamm aauutthheennttiiccaattiioonn The intention of aauutthh--ootthheerr is to allow administrators to implement custom virtual-domains or other authentication schemes, without having to write C code to implement them. The distribution contains a perl module, TTPPOOPP33DD::::AAuutthh-- DDrriivveerr, which makes it extremely easy to implement a new authentication scheme, and various example scripts. One of the advantages of this is that if you want to implement an authenticator which uses a relational database other than MySQL, then you can use the support in perl's DDBBII library. An external authentication program reads data `packets' structured in the following format on its standard input: _k_e_y\0_v_a_l_u_e\0 ... \0 Defined _k_e_ys are: mmeetthhoodd = (AAPPOOPP | PPAASSSS) Authentication mechanism being attempted. uusseerr = _u_s_e_r_n_a_m_e The username being sent with an APOP or USER com- mand. llooccaall__ppaarrtt = _l_o_c_a_l_-_p_a_r_t (Sent only for virtual-domain authentication.) The local-part of the client's email address. ddoommaaiinn = _d_o_m_a_i_n (Sent only for virtual-domain authentication.) The domain of the client's email address. cclliieenntthhoosstt = _I_P _n_u_m_b_e_r The host from which the client is connected to the POP server. sseerrvveerrhhoosstt = _I_P _n_u_m_b_e_r The address to which the client connected on the POP server. ttiimmeessttaammpp = _t_i_m_e_s_t_a_m_p _s_t_r_i_n_g (APOP only.) The `timestamp' string sent by the server to this client. ddiiggeesstt = _h_e_x _d_i_g_e_s_t (APOP only.) Hex representation of the MD5 digest sent by the client with an APOP command. ppaassss = _p_a_s_s_w_o_r_d (PASS only.) The password sent with a PASS command. In response to an AAPPOOPP or PPAASSSS request, the program should write to standard output `packets' in the format described above. Defined _k_e_ys are: rreessuulltt = (YYEESS | NNOO) Was authentication successful? llooggmmssgg = _s_t_r_i_n_g (Optional.) Specifies a message to be written to the system log. The following apply only if authentication is successful; all but uuiidd and ggiidd are optional: uuiidd = (_u_s_e_r_-_n_a_m_e | _u_i_d) ggiidd = (_g_r_o_u_p_-_n_a_m_e | _g_i_d) The user and group with which to access the mail- spool. Note that the user must have a valid home directory. ddoommaaiinn = _d_o_m_a_i_n The domain in which the user has been authenti- cated. mmaaiillbbooxx = _p_a_t_h Path of this user's mailbox. mmbbooxxttyyppee = _m_a_i_l_b_o_x _d_r_i_v_e_r The type of the mailbox. If the mailbox is not specified, then the normal mechanism (via configuration directives mmaaiillbbooxx:: and aauutthh--ootthheerr-- mmaaiillbbooxx::) is used. Your authentication program will also receive packets describing any successful login. These may be used to implement POP-before-SMTP relaying. Such packets have the form mmeetthhoodd = OONNLLOOGGIINN Indicating that the packet describes a login. uusseerr = _u_s_e_r_n_a_m_e The username as supplied by the client. llooccaall__ppaarrtt = _l_o_c_a_l_-_p_a_r_t ddoommaaiinn = _d_o_m_a_i_n The local-part and domain of the authenticated user. cclliieenntthhoosstt = _I_P _n_u_m_b_e_r The host from which the client is connected to the POP server. The only valid responses to an OONNLLOOGGIINN request are an empty packet or one containing only a llooggmmssgg directive. Note that ttppoopp33dd requires external authentication programs to respond in a timely fashion, since authentication blocks the main daemon; if no response is received within the timeout period specified, then the program will be killed with SSIIGGTTEERRMM; if it fails to expire, SSIIGGKKIILLLL will then be sent. An authentication program should catch SSIIGGTTEERRMM to do any essential cleaning up. Your authentication program must not leak memory or file descriptors; if this is a problem, have it exit after some number of transactions; ttppoopp33dd will restart it automati- cally. PPeerrll aauutthheennttiiccaattiioonn ooppttiioonnss These are only available if you compiled ttppoopp33dd with sup- port for aauutthh--ppeerrll. aauutthh--ppeerrll--eennaabbllee: (yyeess | ttrruuee) Enable authentication via an embedded perl inter- preter. aauutthh--ppeerrll--ssttaarrtt: _p_e_r_l _c_o_d_e Specify a line of perl code to be executed at startup; in most cases, this should be something like auth-perl-start: do '/etc/tpop3d/tpop3d.pl'; aauutthh--ppeerrll--ffiinniisshh: _p_e_r_l _c_o_d_e Specify a line of perl code to be executed when the authentication driver is shut down. aauutthh--ppeerrll--aappoopp: _s_u_b_r_o_u_t_i_n_e _n_a_m_e Specify the name of a perl subroutine which will be called when a request for APOP authentication is received. aauutthh--ppeerrll--ppaassss: _s_u_b_r_o_u_t_i_n_e _n_a_m_e Specify the name of a perl subroutine which will be called when a request for USER/PASS authentication is received. aauutthh--ppeerrll--oonnllooggiinn: _s_u_b_r_o_u_t_i_n_e _n_a_m_e Specify the name of a perl subroutine which will be called after a successful login for POP-before-SMTP operation. AA nnoottee oonn ppeerrll aauutthheennttiiccaattiioonn The perl authentication subroutines named in the configu- ration file should take as their single argument a refer- ence to a hash; this will contain keys and values as listed for aauutthh--ootthheerr above. The subroutines should also return a reference to a hash, indicating results as for aauutthh--ootthheerr. In addition, they may call TTPPOOPP33DD::::pprriinntt__lloogg with a single scalar argument to write a message via ttppoopp33dd's logging facility. The aauutthh--ppeerrll--oonnllooggiinn subrou- tine is called after any successful login (not just logins mediated by aauutthh--ppeerrll) and is intended to be used to implement POP-before-SMTP relaying; the return value from this subroutine is ignored, except for any llooggmmssgg hash element, which is logged in the normal way. Your perl routines must not leak memory (normally not a problem because of perl's garbage collector) or other sys- tem resources. If this is a problem, you could consider forcing ttppoopp33dd to restart every so often by calling kkiillll((11,, $$$$)), but it would probably be preferable to use aauutthh--ootthheerr in this case. FFIILLEESS //eettcc//ttppoopp33dd..ccoonnff SSEEEE AALLSSOO ttppoopp33dd(8), mmyyssqqll(1), hhoossttss..aallllooww(5), hhoossttss..ddeennyy(5), TTPPOOPP33DD::::AAuutthhDDrriivveerr(1), rreeggeexx(7), wwhhoossoonndd(8), wwhhoo-- ssoonn..ccoonnff(5), RRFFCC11993399,, _h_t_t_p_:_/_/_w_w_w_._e_x_-_p_a_r_r_o_t_._c_o_m_/_~_c_h_r_i_s_/_t_p_o_p_3_d_/, _h_t_t_p_:_/_/_w_w_w_._e_x_-_p_a_r_r_o_t_._c_o_m_/_~_c_h_r_i_s_/_v_m_a_i_l_-_s_q_l_/, _h_t_t_p_:_/_/_w_w_w_._m_y_s_q_l_._c_o_m_/, _h_t_t_p_:_/_/_l_i_s_t_s_._b_e_a_s_t_s_._o_r_g_/_p_i_p_e_r_m_a_i_l_/_t_p_o_p_3_d_-_d_i_s_c_u_s_s_/. AAUUTTHHOORR Chris Lightfoot . Portions by Mark Longair and Paul Makepeace. If you have a query about ttppoopp33dd, _p_l_e_a_s_e _d_o _n_o_t _s_e_n_d _m_e _p_e_r_s_o_n_a_l _e_m_a_i_l. Instead, please send it to the ttppoopp33dd mailing list, to which you can subscribe by sending an email with the subject `subscribe' to . There is a mailing list archive at _h_t_t_p_:_/_/_l_i_s_t_s_._b_e_a_s_t_s_._o_r_g_/_p_i_p_e_r_m_a_i_l_/_t_p_o_p_3_d_-_d_i_s_c_u_s_s_/. VVEERRSSIIOONN $Id: tpop3d.conf.5,v 1.48 2003/11/24 20:26:07 chris Exp $ CCOOPPYYIINNGG This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. TPOP3D.CONF(5)