TPOP3D.CONF(5)                                     TPOP3D.CONF(5)



NAME
       tpop3d.conf - configuration file for tpop3d(8)

SYNOPSIS
       # comment
       key: value
       key: value          \
           continuation of value
         ...

DESCRIPTION
       The  tpop3d configuration file, tpop3d.conf, consists of a
       number of  key: value  pairs.  Blank  lines  and  comments
       introduced by `#' are ignored. It is legal for value to be
       blank.

       Presently-recognised configuration directives are:

   Global options
       listen-address: address[:port][(domain)|/regex/][;tls-options] ...
              Specify an  address  and  optional  port  on  which
              incoming  connections  are  accepted. domain 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
              regex, a POSIX extended regular expression contain-
              ing a single bracketed  subexpression,  instead  of
              domain;  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 address is
              0.0.0.0 (INADDR_ANY). If neither domain  nor  regex
              are  given, the portion of the name associated with
              the given address following the first `.' is  used,
              or,  if  no such name can be established, the node-
              name of the system determined by uname(2).  If  any
              port  is  not  specified,  it  is assumed to be 110
              (pop-3), or 995  (pop-3s)  if  in  `immediate'  TLS
              mode.

              If  tpop3d  has  been compiled with support for TLS
              (`SSL'),  then  you  may  specify  additional  tls-
              options for each address, in the following form:

                tls=(immediate|stls),certificate[,private-key]

              The  first  token  after tls= 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  immediate  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 STLS to initiate TLS negotiation. We call this
              stls  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 certificate and
              private-key. If only  certificate  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 tpop3d must be started with the -P option
              (see  tpop3d(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  pop3.example.com,  pop3.exam-
              ple.org, 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, tpop3d  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.

       max-children: number
              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.

       append-domain: (yes|true)
              If  authentication  does  not  succeed  for a given
              username, retry with username@domain, where  domain
              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 username does not contain a
              separator, which may be `@', `%', `:' or  `!'.  See
              below for a more detailed description.

       strip-domain: (yes|true)
              If  authentication  does  not  succeed  for a given
              username, and the username supplied is in the  form
              username@domain,  try the authentication again with
              a bare username.  domain 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
              username@domain.com   and  username@domain.net  are
              equivalent and served from the same machine.   This
              option  only  takes effect when username contains a
              separator, which may be `@', `%' or `!'.

       apop-only: (yes|true)
              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.

       timeout-seconds: number
              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
              tpop3d(8)).  If  you  wish  to  have  tpop3d 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.

       log-facility: facility
              This  selects  the `facility' as which tpop3d emits
              system log messages.  Possible values for  facility
              are:  mail,  authpriv,  daemon,  user,  and  local0
              through local7 inclusive.  (Although  other  possi-
              bilities  are  mentioned  in openlog(3), they don't
              make much sense for a POP3 server.)

       log-stderr: (yes|true)
              Send log messages to standard error as well as  the
              system  log.  This  makes sense only when tpop3d is
              running with a controlling terminal.

       no-detach: (yes|true)
              Do not detach from  controlling  terminal.  The  -d
              command-line option to tpop3d is equivalent to com-
              bining this and the log-stderr directives.

       mailbox: [mailbox-driver:]path-spec ...
              This selects the location, and optionally the type,
              of the mailbox to use when a user is authenticated.
              Mailbox-driver should be one of  the  names  listed
              when  you  execute  tpop3d  -h;  if  left blank the
              default (first available) one is used, but this  is
              discouraged  as  it  may  vary  between  builds  of
              tpop3d. Path-spec should give a path  name  in  the
              file  system;  you can use the substitution strings
              $(user), the username supplied to the POP server by
              the  client;  $(local_part),  the  local  part of a
              client's email address in a virtual-domain  authen-
              tication,  $(domain),  the  domain, and $(home) for
              the user's home directory. In addition, the  syntax
              $(foo[index])  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,  tpop3d  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 auth-
              foo-mailbox: which overrides the global setting.

       mailspool-index: path-spec
              This selects the location of metadata  cache  files
              for BSD mailspools, based on their file names. This
              option is only available when  tpop3d  is  compiled
              with  metadata  caching  enabled,  and  it  is only
              switched on when this option is specified.

              Path-spec gives the location of the metadata  cache
              file,  using  substitution strings similar to those
              for the mailbox option above.  In  particular,  you
              can  use  $(name),  the full name of the mailspool;
              $(path), the directory  containing  the  mailspool;
              $(file),  the  file name of the mailspool (the part
              after the final `/'); and $(escaped_name), 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, tpop3d 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.  tpop3d 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.

       maildir-exclusive-lock: (yes|true)
              Indicates  that  tpop3d  should  attempt  to   lock
              maildir  mailboxes for exclusive access, so that it
              more closely follows  the  behaviour  described  in
              RFC1939.  Even  if  not  specified,  tpop3d behaves
              intelligently when a message in a maildir is  moved
              or deleted, so this option is not necessary.

       tcp-wrappers-name: name
              This  selects the `daemon name' used by tpop3d 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 tpop3d has been compiled with support
              for TCP Wrappers.

       drac-server: hostname
              If specified, gives the name of a server  to  which
              tpop3d  should  send  DRAC notifications about suc-
              cessful logins.

       whoson-enable: (yes|true)
              Enable notification of successful logins to a  WHO-
              SON server as defined in /etc/whoson.conf.

       tls-no-bug-workarounds: (yes|true)
              Disable  workarounds for various bugs in client TLS
              implementations,       as       described        in
              SSL_ctx_set_options(3).  Only  available  if tpop3d
              has been built with TLS support.


   Options relating to authentication
       tpop3d 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 tpop3d 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
       user, the user name as supplied by the client; local-part,
       the local-part of  a  virtual-domain  email  address,  and
       domain,  the  domain  in  which  authentication  is taking
       place. By default, domain 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
       local-part@domain combination, and the given local-part is
       used while the given domain replaces  the  domain  derived
       from the address to which the client connected.

       If   there   is  no  separator,  authentication  is  first
       attempted with no local-part and the  default  domain;  if
       this does not succeed, and the append-domain global option
       is set, then authentication will also  be  attempted  with
       the  local-part  the  same  as  the  supplied user and the
       default domain.

       For example, if the client sends the command
         USER foo
       to the listener for domain `dom', tpop3d will try  authen-
       tication with the parameters:
         user       = foo
         local-part   not set
         domain     = dom
       If  this  fails,  and  append-domain is set, then a second
       attempt will be made with:
         user       = foo
         local-part = foo
         domain     = dom
       Otherwise no second attempt is made.

       If instead the client says:
         USER foo@bar
       then authentication will be attempted using:
         user       = foo@bar
         local-part = foo
         domain     = bar
       In this case, no  alternative  attempt  will  be  made  if
       authentication fails.

       These global options apply to all authenticators:

       permit-empty-password: (yes|true)
              If  enabled,  users  may log in with an empty pass-
              word. (Note that their client  must  send  a  space
              after the PASS command in this case.)

       onlogin-child-wait: (yes|true)
              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 after 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.

       log-bad-passwords: (yes|true)
              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.

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

       authcache-enable: (yes|true)
              Enable the cache. It is off by default.

       authcache-entry-lifetime: number
              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.  But  note  that
              this  value  also  controls  how  long it takes for
              password changes to take effect!

       authcache-use-client-host: (yes|true)
              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.


   PAM authentication options
       auth-pam uses Pluggable Authentication Modules to  authen-
       ticate conventional (non-virtual-domains) users.

       auth-pam-enable: (yes|true)
              Enable  authentication  using Pluggable Authentica-
              tion Modules.

       auth-pam-facility: facility
              Sets the PAM facility name used by tpop3d to facil-
              ity. Defaults to tpop3d.

       auth-pam-mail-group: (group-name | gid)
              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'.

       auth-pam-mail-user: (user-name | uid)
              In  normal  operation, auth-pam 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.


   Password authentication options
       These are only available if you compiled tpop3d with auth-
       passwd support. auth-passwd authenticates  Unix  users  by
       direct  lookups  in /etc/passwd and, if configured at com-
       pile time, /etc/shadow.

       auth-passwd-enable: (yes|true)
              Enable authentication using /etc/passwd.

       auth-passwd-mail-group: (group-name | gid)
              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'.


   MySQL authentication options
       These are only available if you compiled tpop3d with auth-
       mysql support.

       auth-mysql-enable: (yes | true)
              Enable MySQL authentication.

       auth-mysql-mail-group: (group-name | gid)
              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.

       auth-mysql-hostname: hostname
              Host on which  to  connect  to  MySQL,  by  default
              localhost. 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.

       auth-mysql-database: database
              MySQL database to use for authentication.

       auth-mysql-username: username
              MySQL username used to access the database.

       auth-mysql-password: password
              Password of MySQL user.

       auth-mysql-pass-query: substitution string
              Query template to use for USER/PASS authentication.

       auth-mysql-apop-query: substitution string
              Query template to use for APOP authentication.

       auth-mysql-onlogin-query: substitution string
              Query  template  to  use for POP-before-SMTP opera-
              tion.

       Since mailbox names are stored in the database, the  auth-
       mysql-mailbox: setting is ignored.


   A note on MySQL authentication
       The  MySQL  authentication  scheme  is intended to be used
       with the vmail-sql virtual domains configuration described
       at   http://www.ex-parrot.com/~chris/vmail-sql/,   and  by
       default the queries it uses work with that schema.

       However, it is also possible to use  the  auth-mysql-pass-
       query  and auth-mysql-apop-query 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  $(user),  $(local_part)  and
       $(domain) 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 $(server-
       host).

       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  none 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  auth-mysql-onlogin-query  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 $(clienthost) indicates the connected
       client  host, as a numeric IP address. This statement will
       be executed for any successful login, not only  auth-mysql
       logins.  Note that $(local_part) 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 auth-other or
       auth-perl 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 tpop3d.conf file should not be readable by arbi-
       trary users.


   Postgres authentication options
       These are only available if you compiled tpop3d with auth-
       pgsql support.

       auth-pgsql-enable: (yes | true)
              Enable Postgres authentication.

       auth-pgsql-username

       auth-pgsql-password

       auth-pgsql-database

       auth-pgsql-hostname

       auth-pgsql-pass-query

       auth-pgsql-apop-query

       auth-pgsql-onlogin-query

       auth-pgsql-mail-group
              Behave like the equivalent auth-mysql options.



   LDAP authentication options
       These  are only available if you compiled tpop3d with sup-
       port for auth-ldap.

       auth-ldap-enable: (yes | true)
              Enable LDAP authentication.

       auth-ldap-url: substitution string
              Template giving an LDAP URL indicating  the  server
              against which to make authentication requests. Note
              that  the  variables  $(user),  $(local_part)   and
              $(domain)  may  appear  only  in the DN part of the
              URL.

       auth-ldap-tls: (yes | true)
              Use an encrypted connection  to  contact  the  LDAP
              server.

       auth-ldap-searchdn: LDAP server username
              DN to use when binding to LDAP server to search for
              a user.

       auth-ldap-password: LDAP server password
              Password of search user.

       auth-ldap-filter: substitution string
              Filter template to use when searching for a  user's
              account.

       auth-ldap-scope: (subtree|base|onelevel)
              Scope  of  LDAP  searches.  If  not  specified, the
              default is `subtree'.

       auth-ldap-mailbox: [mailbox-driver:]path-spec ...
              User mailbox location, as described above.

                  or

       auth-ldap-mailbox-attr: attribute name

       auth-ldap-mboxtype-attr: attribute name
              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.

       auth-ldap-mail-user: (user-name | uid)

       auth-ldap-mail-group: (group-name | gid)
              User  and  group  under which access to the mailbox
              will take place.

                  or

       auth-ldap-mail-user-attr: attribute name

       auth-ldap-mail-group-attr: attribute name
              LDAP attributes which specify the  user  and  group
              under  which access to the mailbox will take place.


   A note on LDAP authentication
       tpop3d 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, tpop3d will attempt  to
       locate  an  LDAP  record  for the user by substituting for
       $(user), $(local_part) and $(domain) in the base DN  given
       by  auth-ldap-url  and in the auth-ldap-filter 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.


   Flat file authentication options
       These are only available if you compiled tpop3d with  sup-
       port for auth-flatfile.

       auth-flatfile-enable: (yes | true)
              Enable flat file authentication.

       auth-flatfile-passwd-file: substitution string
              Specify  the file in which tpop3d will search for a
              user's password.

       auth-flatfile-mail-user: (user-name | uid)

       auth-flatfile-mail-group: (group-name | gid)
              User and group under which access  to  the  mailbox
              will take place.


   A note on flat file authentication
       Flat  files  used  for  authentication consist of lines of
       user:password-hash; any other fields  following  a  subse-
       quent  colon  are ignored, so that /etc/passwd-style files
       may be used. The specified password hash is interpreted as
       a hash produced using crypt(3), unless it is preceded by a
       hashing scheme in {}. auth-flatfile may be used  for  APOP
       authentication if the password field consists of plaintext
       passwords preceded by  {plaintext}.  The  user  and  group
       under  which  access to the mailbox takes place with auth-
       flatfile are always  as  specified  in  the  configuration
       file.  The  file to be used is located by substituting for
       $(domain) in the auth-flatfile-passwd-file  filename  tem-
       plate.


   External program (`other') authentication options
       These  are only available if you compiled tpop3d with sup-
       port for auth-other.

       auth-other-enable: (yes | true)
              Enable external program authentication.

       auth-other-program: path
              Program to use for  external  authentication;  this
              must   be  an  absolute  path  and  should  process
              requests as described below.

       auth-other-user: (user-name | uid)

       auth-other-group: (group-name | gid)
              The user and group under which to run the authenti-
              cation program.


       auth-other-timeout: time
              The timeout in seconds for authentication; may be a
              fractional value, by default 0.75.


   A note on external program authentication
       The intention of auth-other 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, TPOP3D::Auth-
       Driver, 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 DBI library.

       An  external  authentication  program reads data `packets'
       structured in the following format on its standard input:

         key\0value\0 ... \0

       Defined keys are:

       method = (APOP | PASS)
              Authentication mechanism being attempted.

       user = username
              The username being sent with an APOP or  USER  com-
              mand.

       local_part = local-part
              (Sent  only for virtual-domain authentication.) The
              local-part of the client's email address.

       domain = domain
              (Sent only for virtual-domain authentication.)  The
              domain of the client's email address.

       clienthost = IP number
              The  host from which the client is connected to the
              POP server.

       serverhost = IP number
              The address to which the client  connected  on  the
              POP server.

       timestamp = timestamp string
              (APOP  only.)  The  `timestamp'  string sent by the
              server to this client.

       digest = hex digest
              (APOP only.) Hex representation of the  MD5  digest
              sent by the client with an APOP command.

       pass = password
              (PASS only.) The password sent with a PASS command.

       In response to an APOP or PASS request, the program should
       write to standard output `packets' in the format described
       above. Defined keys are:

       result = (YES | NO)
              Was authentication successful?

       logmsg = string
              (Optional.) Specifies a message to  be  written  to
              the system log.

       The  following apply only if authentication is successful;
       all but uid and gid are optional:

       uid = (user-name | uid)

       gid = (group-name | gid)
              The user and group with which to access  the  mail-
              spool.  Note  that  the user must have a valid home
              directory.

       domain = domain
              The domain in which the  user  has  been  authenti-
              cated.

       mailbox = path
              Path of this user's mailbox.

       mboxtype = mailbox driver
              The type of the mailbox.

       If the mailbox is not specified, then the normal mechanism
       (via configuration  directives  mailbox:  and  auth-other-
       mailbox:) 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

       method = ONLOGIN
              Indicating that the packet describes a login.

       user = username
              The username as supplied by the client.

       local_part = local-part

       domain = domain
              The local-part  and  domain  of  the  authenticated
              user.

       clienthost = IP number
              The  host from which the client is connected to the
              POP server.


       The only valid responses to  an  ONLOGIN  request  are  an
       empty packet or one containing only a logmsg directive.

       Note that tpop3d 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  SIGTERM; if it fails to expire, SIGKILL will
       then be  sent.  An  authentication  program  should  catch
       SIGTERM 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; tpop3d will restart it automati-
       cally.


   Perl authentication options
       These are only available if you compiled tpop3d with  sup-
       port for auth-perl.

       auth-perl-enable: (yes | true)
              Enable  authentication  via an embedded perl inter-
              preter.

       auth-perl-start: perl code
              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';

       auth-perl-finish: perl code
              Specify a line of perl code to be executed when the
              authentication driver is shut down.

       auth-perl-apop: subroutine name
              Specify the name of a perl subroutine which will be
              called when a request for  APOP  authentication  is
              received.

       auth-perl-pass: subroutine name
              Specify the name of a perl subroutine which will be
              called when a request for USER/PASS  authentication
              is received.

       auth-perl-onlogin: subroutine name
              Specify the name of a perl subroutine which will be
              called after a successful login for POP-before-SMTP
              operation.


   A note on perl authentication
       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 auth-other above. The subroutines  should  also
       return  a  reference  to a hash, indicating results as for
       auth-other. In addition, they may  call  TPOP3D::print_log
       with  a  single  scalar  argument  to  write a message via
       tpop3d's logging facility. The  auth-perl-onlogin  subrou-
       tine is called after any successful login (not just logins
       mediated by auth-perl) and  is  intended  to  be  used  to
       implement  POP-before-SMTP relaying; the return value from
       this subroutine is ignored, except  for  any  logmsg  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 tpop3d  to  restart  every  so  often  by  calling
       kill(1,  $$),  but  it would probably be preferable to use
       auth-other in this case.


FILES
       /etc/tpop3d.conf


SEE ALSO
       tpop3d(8),   mysql(1),   hosts.allow(5),    hosts.deny(5),
       TPOP3D::AuthDriver(1),    regex(7),    whosond(8),    who-
       son.conf(5), RFC1939,
       http://www.ex-parrot.com/~chris/tpop3d/,
       http://www.ex-parrot.com/~chris/vmail-sql/,
       http://www.mysql.com/,
       http://lists.beasts.org/pipermail/tpop3d-discuss/.


AUTHOR
       Chris Lightfoot <chris@ex-parrot.com>.  Portions  by  Mark
       Longair and Paul Makepeace.

       If  you  have  a query about tpop3d, please do not send me
       personal email. Instead, please  send  it  to  the  tpop3d
       mailing  list,  to  which  you can subscribe by sending an
       email with the subject `subscribe' to
       <tpop3d-discuss-request@lists.beasts.org>.  There   is   a
       mailing list archive at
       http://lists.beasts.org/pipermail/tpop3d-discuss/.


VERSION
       $Id: tpop3d.conf.5,v 1.48 2003/11/24 20:26:07 chris Exp $


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