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

FreeBSD Manual Pages


home | help
TPOP3D.CONF(5)		      File Formats Manual		TPOP3D.CONF(5)

       tpop3d.conf - configuration file	for tpop3d(8)

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

       The  tpop3d  configuration  file,  tpop3d.conf, consists	of a number of
       key: value pairs. Blank lines and comments introduced by	 `#'  are  ig-
       nored. 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 connec-
	      tions are	accepted. domain is the	domain name for	which the ser-
	      vice is operated;	alternatively, if mass virtual hosting support
	      is compiled in (the default), then  you  can  specify  regex,  a
	      POSIX  extended regular expression containing a single bracketed
	      subexpression, instead of	domain;	in this	case, the regular  ex-
	      pression 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 (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 nodename 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:


	      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 imme-
	      diate mode, TLS negotiation is  initiated	 immediately  after  a
	      connection  is  received.	In this	mode, only TLS connections can
	      be made to a particular address. In the other mode,  the	client
	      establishes an unencrypted TCP connection, then issues the POP-3
	      command 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 certifi-
	      cate is given, then both the certificate	and  the  private  key
	      should  be  contained  in	 the one file. If a pass-phrase	is re-
	      quired 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


	      is sufficient. To	specify	a specific domain, use this syntax:


	      If,  alternatively,  the	machine	 has  numerous interfaces with
	      names,,	etc., you could	 spec-


	      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 in-
	      verse name resolution; 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  map-
	      ping  --	perhaps	 in /etc/hosts -- to ensure that this does not

       max-children: number
	      The maximum number of child  processes  which  may  be  actively
	      serving connections at any given time. Consists of a single num-
	      ber. 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. See below	for a more de-
	      tailed 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 au-
	      thentication again with a	bare username.	domain need not	be the
	      domain  name associated with the address on which	the connection
	      was received. This is intended to	be used	where multiple domains
	      are  served  by  a  single authenticator with the	same username,
	      such as when	 and  are
	      equivalent  and  served from the same machine.  This option only
	      takes effect when	username contains a separator,	which  may  be
	      specified	via the	domain-separators config option. (see below)

       domain-separators: string
	      Specify  which  characters  may  be used to separate local_parts
	      from domains in POP3 usernames. The default is "@%!:".

       apop-only: (yes|true)
	      Disconnect any client which attempts plaintext USER/PASS authen-
	      tication.	 The  intention	 of this option	is to discourage users
	      from sending plaintext passwords over the	network, so it has  no
	      effect when a user is connected over a TLS-secured connection.

       lowercase-user: (yes|true)
	      Convert the string provided with the POP3	USER command to	lower-
	      case letters.  This may be usefull  with	case-sensitive	opera-
	      tions  like  authentication  against dbm files or	case-sensitive
	      SQL databases.

       timeout-seconds:	number
	      This is the number of seconds for	which a	connection 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.

       tcp-send-buffer:	number
	      This is the largest number of bytes which	may be `in flight' be-
	      tween  the  server  and  a  client  at any time. Setting this to
	      larger values may	improve	the performance	of tpop3d, but at  the
	      risk  of	timing	out  clients  connected	 by slow networks. You
	      should not set this parameter to anything	larger than the	 time-
	      out  multiplied  by  the	data rate (in bytes per	second)	of the
	      slowest network through which clients will connect to  the  POP3
	      server.  This  is	 set  using  the  SO_SNDBUF socket option; see
	      socket(7)	for more information. The default is 16,384 bytes; set
	      this to 0	to use the system default.

       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 possibilities are mentioned	in openlog(3), they don't make
	      much sense for a POP3 server.)

       log-level: level
	      This  selects  the  `level' at which tpop3d logs system log mes-
	      sages.   Possible	 values	 for  level  are  described  in	  sys-

       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

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

       mailbox:	[mailbox-driver:]path-spec ...
	      This selects the location, and optionally	the type, of the mail-
	      box 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 sub-
	      stitution	 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 authentication, $(do-
	      main), 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 directories; for example,

		mailbox: bsd:/var/spool/mail/$(user[0])/$(user)

	      If  several  mailbox  locations  and types are specified,	tpop3d
	      will try each in turn, stopping when it opens a mailbox  or  en-
	      counters 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

       lowercase-mailbox: (yes|true)
	      Convert the directory/file part  of  the	mailbox	 specification
	      (see above) to lowercase letters,	if retrieved by	an authentica-
	      tion driver. (E.g. due to	a database lookup.)  Usefull  only  in
	      cases where case-sensitive filesystems are in use, of course.

       mailspool-index:	path-spec
	      This  selects the	location of metadata cache files for BSD mail-
	      spools, 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  fi-
	      nal  `/');  and  $(escaped_name),	 which is the full name	of the
	      mailspool	escaped	using the HTTP-style %.. convention so that it
	      does not contain 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	directory   for	 this  (for  instance,
	      /var/spool/mail or /var/spool/tpop3d), you will need to set  ap-
	      propriate	 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	direc-
	      tory  to	which users would not customarily have access, for in-
	      stance /var/spool/tpop3d.

       mailspool-no-dotfile-locking: (yes|true)
	      By default tpop3d	will try to lock a mailspool for exclusive ac-
	      cess  using all methods available	on the local system: fcntl(2),
	      flock(2),	and creating a	lockfile  for  the  mailspool  with  a
	      `.lock' suffix. This option allows you to	switch off the last of
	      these without recompiling	the daemon, and	is recommended if  you
	      are  absolutely  certain that no other programs rely on dotfile-
	      locking to synchronise access to mailspools. In  particular,  if
	      you  use	lockfiles, it is possible for an over-quota user to be
	      unable to	log in to the POP3 server,  because  creation  of  the
	      lockfile is prohibited; switching	on this	option eliminates that

       maildir-exclusive-lock: (yes|true)
	      Indicates	that tpop3d should attempt to lock  maildir  mailboxes
	      for exclusive access, so that it more closely follows the	behav-
	      iour 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.

       maildir-recursion: (yes|true)
	      Tells tpop3d to display messages in IMAP folders as if they were
	      in  the  INBOX. Useful if	you mix	POP3 with IMAP clients such as
	      webmail systems.

       maildir-ignore-folders: [foldername [...]]
	      Specifies	IMAP folders (without the leading dot) that should  be
	      excluded	from  maildir-recursion.  May  be empty; more than one
	      folder should be separated by spaces or  tabs.  Items  beginning
	      with "^" are treated as POSIX Extended Regular Expressions.

	      The default is:
		maildir-ignore-folders:	Trash Sent

       maildir-evaluate-filename: (yes|true)
	      If  enabled, tpop3d tries	to extract information about modifica-
	      tion time	and message size out of	 the  message  filenames  when
	      reading a	maildir. This saves some disk I/O, as we don't have to
	      stat() on	each file. Extraction of information from  the	unique
	      filenames	in a maildir is	NOT common practise, so	use with care!
	      You have to ensure, that message filenames conform to  the  fol-
	      lowing pattern:

	      The message filename has to begin	with the UNIX timestamp	of the
	      time the message was delivered. The size of the message in bytes
	      may  appear anywhere in the filename but has to be preceded with
	      a	unique string, which can be altered by maildir-size-string  in

	      If  a  message  filename	does not conform correctly, tpop3d may
	      misinterprete what it found, allthough if	the filename turns out
	      to  be definately	unusable (e.g. the unique string is not	found,
	      or it doesn't start with digits) it  will	 fall  back  on	 using

	      Message  filenames  are by default set correct by	reasonable re-
	      cent versions of qmail-ldap, exim	users may use the  maildir_tag
	      option of	the appendfile transport to conform.

       maildir-size-string: string
	      Specifies	the unique string tpop3d will search for when evaluat-
	      ing message filenames to find the	messages size.	 See  maildir-
	      evaluate-filename	for information	on how this is used.

	      The default is:
		maildir-size-string: ,S=

       uidl-style: stylename
	      The UIDL command is used by POP3 clients to distinguish messages
	      they allready downloaded from new	ones. If  you  switch  between
	      POP3  server  software  that produce different unique-ids, these
	      clients will download all	messages again.	 To avoid this,	tpop3d
	      supports different unique-id formats.

	      The available formats are:
		tpop3d:	tpop3ds	native format, the default and fallback.
		qmail:	qmail-pop3ds format, uses message-filenames as unique-

       tcp-wrappers-name: name
	      This selects the `daemon name' used by tpop3d when it tests con-
	      nections 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 successful logins.

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

       tls-no-bug-workarounds: (yes|true)
	      Disable  workarounds  for	various	bugs in	client TLS implementa-
	      tions, 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 authentication, a request is passed	to each	of a number of
       configured authenticators in turn, until	the client is successfully au-
       thenticated 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 vir-
       tual-domain email address, and domain, the domain in which  authentica-
       tion  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 lo-
       cal-part	and the	default	domain;	if this	does not succeed, and the  ap-
       pend-domain  global option is set, then authentication will also	be at-
       tempted with the	local-part the same as the supplied user and  the  de-
       fault domain.

       For example, if the client sends	the command
	 USER foo
       to  the	listener for domain `dom', tpop3d will try authentication 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

       These global options apply to all authenticators:

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

       onlogin-child-wait: (yes|true)
	      If enabled, and the authenticator	offers an `onlogin' 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	 simi-
	      lar 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.

       no-commit-on-early-close: (yes|true)
	      Some  POP3 clients (most notably Microsoft `Outlook') will close
	      their connection to the server immediately after issuing a  QUIT
	      command	and  before  receiving	any  response.	Strictly  they
	      oughtn't to do that, and historically if they did, tpop3d	 would
	      abort the	connection and not delete messages for which DELE com-
	      mands had	been issued during the	session.  That	behaviour  has
	      been  changed for	greater	compatibility with broken clients; you
	      can set this option to restore the previous behaviour. Doing  so
	      will  reduce  the	chance that your clients will lose mail	due to
	      flakey network connectivity.

       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 ex-
       cept for	servers	 which	run  under  very  heavy	 load.	Authentication
       cacheing	 can  only be used for USER/PASS authentication; it has	no ef-
       fect on APOP authentications.  The following options  control  the  au-
       thentication 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 au-
	      thentication are cached. The default value is 1 hour (3600  sec-
	      onds).  In  order	 to  be	useful,	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 minutes, then
	      setting the lifetime to ten minutes will mean that, on  average,
	      half  of	authentications	come from the cache and	are fast. Set-
	      ting it to one hour means	that eleven out	of twelve  authentica-
	      tions  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 authentication based on
	      the IP address of	the connected client. By default, the  authen-
	      tication	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	other-
	      wise the cache will give incorrect results in some cases.

   PAM authentication options
       auth-pam	uses Pluggable Authentication Modules to authenticate  conven-
       tional (non-virtual-domains) users.

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

       auth-pam-facility: facility
	      Sets  the	PAM facility name used by tpop3d to facility. 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	authenticate 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 au-
	      thenticate 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 configuration.

   Password authentication options
       These  are  only	available if you compiled tpop3d with auth-passwd sup-
       port.  auth-passwd  authenticates  Unix	users  by  direct  lookups  in
       /etc/passwd and,	if configured at compile 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
	      normally want to set this	to `mail'.

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

       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 associated 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	operation.

       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-par-, 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 re-
       turn  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-

       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  contains	fields
       login,  domain, cryptpw and the Maildir mailboxes for the users are un-
       der /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 ad-
       ditional	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  description  of  au-
       thentication,  above,  for more information. If more flexibility	is re-
       quired, consider	using auth-other or auth-perl instead.

       Note that the username and password supplied in the configuration  file
       are privileged information, in the sense	that they would	allow an arbi-
       trary person to obtain information from the database if they  have  ac-
       cess to the machine on which it resides.	 The corollary to this is that
       the tpop3d.conf file should not be readable by arbitrary	users.

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

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








	      Behave like the equivalent auth-mysql options.

   LDAP	authentication options
       These  are only available if you	compiled tpop3d	with support for auth-

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

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


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


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

       auth-ldap-mail-group-attr: attribute name
	      LDAP attributes which specify the	user and group under which ac-
	      cess 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 template,
       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 authenti-

       Information about the user's account, in	particular, the	user and group
       id to use for mailbox access, and the location and type of the mailbox,
       may be obtained either from the directory, or from values in  the  con-
       figuration file.

   Flat	file authentication options
       These  are only available if you	compiled tpop3d	with support for auth-

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

       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

   A note on flat file authentication
       Flat files used for authentication consist of lines  of	user:password-
       hash;  any  other  fields  following a subsequent 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 authenti-
       cation  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 configu-
       ration file. The	file to	be used	is located by substituting  for	 $(do-
       main) in	the auth-flatfile-passwd-file filename template.

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

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

       auth-other-program: path
	      Program to use for external authentication; this must be an  ab-
	      solute 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 authentication pro-

       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::AuthDriver, 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 command.

       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

       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

       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 mailspool. Note that
	      the user must have a valid home directory.

       domain =	domain
	      The domain in which the user has been authenticated.

       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 config-
       uration 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	relay-
       ing. 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 pro-
       gram 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 automatically.

   Perl	authentication options
       These are only available	if you compiled	tpop3d with support for	 auth-

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

       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 '/usr/local/etc/tpop3d/';

       auth-perl-finish: perl code
	      Specify a	line of	perl code to be	executed when the  authentica-
	      tion 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  configuration  file
       should  take  as	their single argument a	reference 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 subroutine is called after any	successful login  (not
       just logins mediated by auth-perl) and is intended to be	used to	imple-
       ment 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	system 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.

   GNU dbm authentication options
       These are only available	if you compiled	tpop3d with support for	 auth-

       auth-gdbm-enable: (yes |	true)
	      Enable authentication via	a GNU dbm file.

       auth-gdbm-passwd-file: string
	      Specify  the  dbm	 file in which tpop3d will search for a	user's

       auth-gdbm-persistent: (yes | true)
	      Tells whether tpop3d should keep the GDBM	file open (persistent:
	      yes) all the time, or whether it should be reopened for each au-
	      thentication request. The	former should give slight better  per-
	      formance	on  heavy loaded servers, the latter is	easier to han-
	      dle. If you use persistent filehandles, you'll have  to  send  a
	      HUP  signal  to  the listener process every time after replacing
	      the GDBM file.

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

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

   A note on GNU dbm authentication
       The  dbm	 file has to store password hashes as zero-terminated strings.
       The specified password hash is interpreted as  a	 hash  produced	 using
       crypt(3), unless	it is preceded by a hashing scheme in {}. The user and
       group under which access	to the mailbox takes place with	auth-gdbm  are
       always as specified in the configuration	file.


       tpop3d(8),   mysql(1),	hosts.allow(5),	 hosts.deny(5),	 TPOP3D::Auth-
       Driver(1), regex(7), whosond(8),	whoson.conf(5),	RFC1939,,,,

       Chris Lightfoot <>. 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
       <>.  There is a mailing list ar-
       chive at


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



Want to link to this manual page? Use this URL:

home | help