TPOP3D.CONF(5)TPOP3D.CONF(5)NAMEtpop3d.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 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
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 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:
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 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
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 interfaces with
names pop3.example.com, pop3.example.org, etc., you could spec‐
ify
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 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
occur.
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
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 connec‐
tion was received. This is intended to be used where multiple
domains are served by a single authenticator with the same user‐
name, 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 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'
between 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.conf(5).
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 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,
$(domain), the domain, and $(home) for the user's home direc‐
tory. 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 directo‐
ries; 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
encounters an error other than the mailbox not being present.
This means that if your users have both maildir and bsd mail‐
boxes, 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.
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
final `/'); 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
appropriate 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
instance /var/spool/tpop3d.
mailspool-no-dotfile-locking: (yes|true)
By default tpop3d will try to lock a mailspool for exclusive
access 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 particu‐
lar, 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 possibility.
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
tpop3d.conf.
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
stat().
Message filenames are by default set correct by reasonable
recent 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-
ids.
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
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 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
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 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
fails.
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
case.)
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
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 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
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 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‐
port.
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‐
rot.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 contains fields
login, domain, cryptpw and the Maildir mailboxes 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 success‐
ful 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
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 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
access 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‐
port.
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 support 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 `sub‐
tree'.
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 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
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 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‐
cated.
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-
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 pass‐
word.
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 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
$(domain) 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-
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 authentication pro‐
gram.
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
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 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-
perl.
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/tpop3d.pl';
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-
gdbm.
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
password.
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
authentication request. The former should give slight better
performance on heavy loaded servers, the latter is easier to
handle. 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
place.
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.
FILES
/usr/local/etc/tpop3d.conf
SEE ALSOtpop3d(8), mysql(1), hosts.allow(5), hosts.deny(5), TPOP3D::Auth‐
Driver(1), regex(7), whosond(8), whoson.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 ar‐
chive at
http://lists.beasts.org/pipermail/tpop3d-discuss/.
VERSION
$Id$
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 MER‐
CHANTABILITY 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)
