.\" Copyright (c) 1999 Ian Freislich
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	$Id: popd.conf.5,v 1.6 2003/01/24 12:01:25 ianf Exp $
.\"
.Dd November 1, 2002
.Dt POPD.CONF 5
.Os
.Sh NAME
.Nm popd.conf
.Nd POP3 daemon configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for the
.Xr popd 8
daemon.
The file is comprised of several sections
into which configuration options
are logically grouped.
.Pp
Comments are allowed in the file
and any line fragment starting with
.Sq Li \&#
until the end of the line are ignored.
.Sh THE GLOBAL SECTION:
.Ss Syntax
.Bd -literal
[debug_mode:		(true|false);]
[interactive_debug:	(true|false);]
[disable_uidl:		(true|false);]
[etc_directory:		path;]
[inactivity_timeout:	seconds;]
[default_realm:		text;]
[virtual_server:	(true|false);]
[virtual_user:		username;]
[local_users:		(true|false);]
[fascist_logging:	(true|false);]
[command_logging:	(true|false);]
.Ed
.Ss Definition and usage
.Bl -tag -width indent
.It debug_mode
If set to true will prevent
the server from daemonising.
All other configuration will be observed.
The server will open sockets
if required
and will log details
of each connection
and the resulting child process
to
.Xr syslog 3
Defaults to False.
.It interactive_debug
If set to true
the server will not open any sockets.
All other configuration will be observed.
Interaction will the server
will take place on standard input
and output.
Defaults to False.
.It disable_uidl
Controls access to the optional UIDL command.
Defaults to False.
.It disable_top
Controls access to the optional TOP command.
Defaults to False.
.It etc_directory
Specify the path to the directory
where the server should find
its password
and secrets files.
defaults to
.Pa /usr/local/etc
.It inactivity_timeout
The timeout in seconds that the server should exit serving a connection.
Defaults to 600.
.It virtual_server
The server is to run in virtual mode.
All usernames must be in the format
.Sq Li username@domain .
The domain is used
to identify users in different realms
and those realms'
respective storage areas
in the message store.
Defaults to false.
.It default_realm
Append default_realm
to the username
if no domain
is supplied by the user.
This option is not set by default.
.It virtual_user
When running in virtual mode
or if users are not local
and once the client
has been successfully authenticated,
the server will setuid
to the supplied username
for the remainder of the session.
Defaults to
.Sq mailnull .
.It local_users
Specify whether POP3 users local users or not.
The server will setuid
to the virtual user
after successful authentication
if set to false.
Defaults to true.
.It fascist_logging
This option instructs the server
to log all input
it recieves verbatum
to syslog.
B
Passwords, usernames,
all commands
and all other input will be logged.
You have been warned.
It is useful however
when trying to determine
if users
are doing something stupid.
.It command_logging
This option instructs
the server to log all commands
and their arguments
after authentication to syslog.
Logging takes place
after input has been parsed,
so all output
from this logging method is
.Sq cooked .
.El
.Pp
.Sh THE AUTHENTICATION SECTION
.Ss Syntax
.Bd -literal
[authentication: {
	[check_passwords:	(true|false);]
	[apop_secrets:		path;]
	[virtual_passwords:	path;]
	[radius_server: {
		host:		(FQDN|IP Address);
		[port:		number;]
		secret:		text;
		[timeout:	seconds;]
		[tries:		number;]
	}]
}]
.Ed
.Ss Definition and usage
.Bl -tag -width indent
.It check_passwords
This option directs the server
to check user supplied passwords.
When set to false,
any supplied password
will be accepted without checking.
Defaults to true.
.It apop_secrets
The path including the file name
of the APOP secrets database
relative to the configured etc directory.
If no APOP secret database is configured,
the APOP command will be disabled.
This file is a Berkeley DB
with fully qualified usernames
.Sq Li username@domain
or
.Sq Li username
depending on whether the server
is running in virtual mode
as the key
and the secret as the data.
Unset by default.
.It virtual_passwords
The path including the file name
of the password database
for authentication in virtual mode.
This file is a Berkeley DB
with fully qualified usernames
.Sq Li username@domain
as the key
and the
.Xr crypt 3
encrypted password as the data.
The path is relative
to the configured etc directory
and the filename defaults to passwd.db.
.It radius_server
This option may be specified
more than once
to configure alternative RADIUS servers.
If more than one RADIUS server is specified,
they will be tried in round-robin fashion
until a valid response is received,
or until each server's tries limit
has been reached.
.Pp
The server will set the
.Li NAS-Port-Type
attribute in the RADIUS authentication request to
.Li Virtual .
.Pp
NOTE: Livingston originally did not approach IANA
for port numbers for RADIUS
and instead chose ports 1645/1646.
Different official numbers
have since been assigned
to RADIUS
and as a result,
some confusion may arise
because the server will use /etc/services
to determine the default port.
.Bl -tag -width indent
.It host
The fully qualified domain name
or IP address of the RADIUS server.
A host must be specified.
.It port
The port number
on which the RADIUS server listens.
Defaults to
.Li radius
in
.Pa /etc/services .
.It secret
The shared secret.
.It timeout
Time in seconds that the server
has to reply to the authentication request
before another request is made.
Defaults to 3 seconds.
.It tries
The number of repeated authentication requests
to make before giving up.
Defaults to 3.
.El
.El
.Pp
.Sh THE LISTEN SECTION
.Ss Syntax
.Bd -literal
[listen: {
	[address_family:	(inet4|inet6);]
	[port:			(text|number);]
	[address:		IP Address;]
}]
.Ed
.Ss Definition and usage
.Bl -tag -width indent
.It address_family
Specify which address family
the server should use.
If omitted the server will attempt
to use all available families.
.It port
The port on which the server should listen.
Defaults to
.Sq Li pop3 .
.It address
The address on which the server should listen.
Defaults to the wildcard address.
.El
.Pp
.Sh THE PROXY SECTION
.Ss Syntax
.Bd -literal
[pop3_proxy: {
	[proxy:		(true|false);]
	[proxy_port:	number;]
	[proxy_address:	IP Address;]
.Ed
.It proxy
The server should opperate
in POP3 proxy mode
if set to true.
For this option to work correctly
at least one RADIUS server
should be specified
in the authentication section.
The reply attributes
.Li Login-IP-Host ,
and optionally
.Li Login-TCP-Port
and
.Li Reply-Message
specify the destination host,
and optionally the port
to which this session will proxied.
The optional
.Li Reply-Message
contains the username
and password seperated by a
.Sq \&:
that the server
should use to establish
the proxied session.
Should no destination port be specified,
the pop3 port will be used.
.Pp
If authentication is successful,
the fully qualified username
and the supplied password
will be sent to the server
specified in the RADIUS reply.
Defaults to false.
.It proxy_port
Allows a default port to be specified.
This port will be used if none is given in the RADIUS reply.
Defaults to 110.
.It proxy_address
Allows a default address to be specified.
This address will be used if none is given in the RADIUS reply.
Defaults to 0.0.0.0.
.Pp
.Sh THE MAIL SECTION
.Ss Syntax
.Bd -literal
[mail: {
	[bulletins:	path;]
	[spool:		path;]
	[format:	(mailbox|maildir|maildircompat|mailidx);]
	[hash_depth:	number;]
	[wire_format:	(true|false);]
	[expire_after:	time offset;]
	[remove_after:	time offset;]
	[falsify_uidl:	(true|false);]
	[autodelete:	(true|false);]
	[sort_by:	(delivery_time|message_size);]
}]
.Ed
.Ss Definition and usage
.Bl -tag -width indent
.It bulletins
The path to the bulletins.
The user's realm will be appended to this path when
the server
is run in virtual mode.
The server
will present files in this directory to users
as email messages in their mailbox.
The server
remembers which users have downloaded which messages.
.It spool
Change the mail spool directory base
from which the user's mailbox path
is determined.
The default is
.Pa /var/mail .
.It format
Specify which of 4 supported mailbox
formats the server should use.
maildircompat is provided
for compatibility with the previous
and incorrect implimentation
of maildir in prior versions of the server.
The default is
.Sq Li mailbox .
.It hash_depth
A depth of 2 would append
.Pa /f/fo
to the mail spool base for the user
.Li foo .
A depth of 5 would append
.Pa /f/fo/foo/foo/foo
and
.Pa /f/fo/foo/foob/foobar
for the users
.Li foo
and
.Li foobar
respectively.
The default value is 0.
.It wire_format
The mail spool is stored in
.Sq wire format .
Each line has a <CR><LF> at the end,
and where the termination character
.Sq \&.
would appear it is represented by
.Sq .. .
Defaults to false.
.It expire_after
Set the expiry time for messages
in the user's mailbox to
.Ar expire_time .
The unit of time defaults to seconds,
but may also contain the following characters:
[sSmhHdDwWMyY],
s or S for seconds,
m  for minutes,
h or H for hours,
d or D for days,
w or W for weeks,
M for months
and y or Y for years.
For example,
a value of 10w5d will set time to 10 weeks and 5 days.
.It remove_after
Sumarily remove messages older than
the remove time
from the mailbox on QUIT.
The format of time is the same
as for the expire_after option.
.It falsify_uidl
Falsify UIDL information
for messages older than the expiry cutoff.
.It autodelete
Autodelete messages
from the user's mailbox
on QUIT
that are older than the specified expiry cutoff.
Connection drops will not result in these messages being deleted.
This option makes the server
treat those messages retrieved by RETR
that satisfy the expiry criterion
as if they have also been deleted by the DELE command.
Default is false.
.It sort_by
Instructs the server
to sort messages presented to the user
by the LIST
and UIDL commands
in ascending order
by either the delivery time
or the size of the message.
Defaults to delivery time.
.El
.Pp
.Sh THE SSL SECTION
.Ss Syntax
.Bd -literal
[ssl: {
	certificate:	path;
	private_key:	path;
	[ssl_mode:	(ssl_server|ssl_proxy|ssl_both);]
}]
.Ed
.Ss Definition and usage
.It certificate
The name of the file containing the ssl cert.
This file is located in the
configured etc directory.
Defaults to
.Pa popd_cert.pem .
.It private_key
The name of the file containing the ssl private key.
This file is located in the
configured etc directory.
Defaults to
.Pa popd_key.pem .
.It ssl_mode
Enable SSL support for the POP3 server,
the proxied connection
or both.
The server
must be compiled with -DUSE_SSL for this option.
.El
.Pp
.Sh EXAMPLE
What follows is an example configuration file
with the compile time defaults.
Lines that are commented out represent options
that are not set by default.
.Bd -literal
debug_mode:		false;
interactive_debug:	false;
disable_uidl:		false;
disable_top:		false;
etc_directory:		/usr/local/etc;
inactivity_timeout:	300;
pop3_proxy:		false;
#default_realm:		testing.com;
virtual_server:		false;
virtual_user:		pop;
local_users:		true;
fascist_logging:	false;
command_logging:	false;
authentication:	{
	check_passwords:	true;
#	apop_secrets:		secrets.db;
	virtual_passwords:	passwd.db;
#	radius: {
#		host:		127.0.0.1;
#		port:		1812;
#		secret:		testing123;
#		timeout:	3;
#		tries:		3;
#	}
}
listen: {
#	address_family:	inet4;
	port:		pop3;
#	address:	192.168.0.1;
}
mail: {
	bulletins:	/var/mail/bulletin;
	spool:		/var/mail;
	format:		mailbox;
	hash_depth:	0;
	wire_format:	false;
#	expire_after:	1w3d;
#	remove_after:	3w1d;
	falsify_uidl:	false;
	autodelete:	false;
}
ssl: {
	certificate:	popd_cert.pem;
	private_key:	popd_key.pem;
#	ssl_mode:	ssl_server; #ssl_proxy|ssl_both
}
.Ed
.Pp
.Sh SEE ALSO
.Xr popd 8
.Pp
.Sh AUTHORS
.Nm
was written by
.An Ian Freislich .
.Pp
Send bug reports to
.An Ian Freislich Aq ian@freislich.nom.za .