POPD.CONF(5)

NAME
popd.conf - POP3 daemon configuration file

DESCRIPTION
popd.conf is the configuration file for the popd(8) daemon. The file is comprised of several sections into which configuration options are logically grouped.

Comments are allowed in the file and any line fragment starting with ‘#’ until the end of the line are ignored.

THE GLOBAL SECTION:

  Syntax

    [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);]

  Definition and usage

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 syslog(3) Defaults to False.

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.

disable_uidl
    Controls access to the optional UIDL command. Defaults to False.

disable_top
    Controls access to the optional TOP command. Defaults to False.

etc_directory
    Specify the path to the directory where the server should find its password and secrets files. defaults to /usr/local/etc

inactivity_timeout
    The timeout in seconds that the server should exit serving a connection. Defaults to 600.

virtual_server
    The server is to run in virtual mode. All usernames must be in the format ‘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.

default_realm
    Append default_realm to the username if no domain is supplied by the user. This option is not set by default.

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 ‘mailnull’.

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.

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.

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 ‘cooked’.

THE AUTHENTICATION SECTION

  Syntax

    [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;]
    	}]
    }]

  Definition and usage

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.

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 ‘username@domain’ or ‘username’ depending on whether the server is running in virtual mode as the key and the secret as the data. Unset by default.

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 ‘username@domain’ as the key and the crypt(3) encrypted password as the data. The path is relative to the configured etc directory and the filename defaults to passwd.db.

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.

    The server will set the NAS-Port-Type attribute in the RADIUS authentication request to Virtual.

    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.

    host
        The fully qualified domain name or IP address of the RADIUS server. A host must be specified.

    port
        The port number on which the RADIUS server listens. Defaults to radius in /etc/services.

    secret
        The shared secret.

    timeout
        Time in seconds that the server has to reply to the authentication request before another request is made. Defaults to 3 seconds.

    tries
        The number of repeated authentication requests to make before giving up. Defaults to 3.

THE LISTEN SECTION

  Syntax

    [listen: {
    	[address_family:	(inet4|inet6);]
    	[port:			(text|number);]
    	[address:		IP Address;]
    }]

  Definition and usage

address_family
    Specify which address family the server should use. If omitted the server will attempt to use all available families.

port
    The port on which the server should listen. Defaults to ‘pop3’.

address
    The address on which the server should listen. Defaults to the wildcard address.

THE PROXY SECTION

  Syntax

    [pop3_proxy: {
    	[proxy:		(true|false);]
    	[proxy_port:	number;]
    	[proxy_address:	IP Address;]

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 Login-IP-Host, and optionally Login-TCP-Port and Reply-Message specify the destination host, and optionally the port to which this session will proxied. The optional Reply-Message contains the username and password seperated by a ‘’: that the server should use to establish the proxied session. Should no destination port be specified, the pop3 port will be used.

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. Allows a default port to be specified. This port will be used if none is given in the RADIUS reply. Defaults to 110. 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.

THE MAIL SECTION

  Syntax

    [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);]
    }]

  Definition and usage

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.

spool
    Change the mail spool directory base from which the user's mailbox path is determined. The default is /var/mail.

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 ‘mailbox’.

hash_depth
    A depth of 2 would append /f/fo to the mail spool base for the user foo. A depth of 5 would append /f/fo/foo/foo/foo and /f/fo/foo/foob/foobar for the users foo and foobar respectively. The default value is 0.

wire_format
    The mail spool is stored in ‘wire format’. Each line has a <CR><LF> at the end, and where the termination character ‘’. would appear it is represented by ‘..’. Defaults to false.

expire_after
    Set the expiry time for messages in the user's mailbox to 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.

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.

falsify_uidl
    Falsify UIDL information for messages older than the expiry cutoff.

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.

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.

THE SSL SECTION

  Syntax

    [ssl: {
    	certificate:	path;
    	private_key:	path;
    	[ssl_mode:	(ssl_server|ssl_proxy|ssl_both);]
    }]

  Definition and usage
The name of the file containing the ssl cert. This file is located in the configured etc directory. Defaults to popd_cert.pem. The name of the file containing the ssl private key. This file is located in the configured etc directory. Defaults to popd_key.pem. Enable SSL support for the POP3 server, the proxied connection or both. The server must be compiled with -DUSE_SSL for this option.

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.

    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
    }

SEE ALSO
popd(8)

AUTHORS
popd.conf was written by Ian Freislich.

Send bug reports to Ian Freislich <ian@freislich.nom.za>.