POPD(8)

NAME
popd - POP3 daemon

SYNOPSIS
popd [-46dxDFNPUVW] [-a Virtual_password_file] [-b bind_address] [-c ssl_certfile] [-e etc_dir] [-k ssl_keyfile] [-m mail_dir] [-n hash_depth] [-p POP3_port] [ -r RADIUS_server RADIUS_secret [port [timeout [tries]]]] [-s server|proxy|both] [-t secs] [-u virtual_mail user] [-A default_realm] [-B bulletin_dir] [-E expire_secs] [-M mailbox|maildir|maildircompat|mailidx] [-R remove_secs] [-S APOP_secret_database]

DESCRIPTION
The popd server is a fast, RFC1939 compliant POP3 server rivalling ls(1) for command line options.

popd allows mail for users in multiple domains to be served from one server in virtual mode. It also allows for mail to be expired from the server (when users collect mail older than a specified time), falsification of UIDL information and removal of old mail.

popd currently supports the following mail store schemas:

1.  Each message in the mailbox is a separate file and the mailbox is a directory.

2.  The mailbox is a file and all messages are in that file.

3.  The mailbox is a file and all messages are in that file. The messages in this file are stored in ‘wire format’. Each line has a <CR><LF> at the end, and where the termination character ‘’. would appear, it is represented by ‘..’. This file has a binary index.

This manual page refers to 1 as Mail Dir Format, 2 as Mail Box Format and 3 as Mail Index Format.

The d, n and V options give some control over the mail store directory structure.

For systems wanting to run mail for many domains it is possible to serve, for example, fred@bar.net's mail from /var/mail/bar.net/fred/ or /var/mail/bar.net/f/fr/fred depending on the values of ‘n’.

popd will use one of four schemes to authenticate users. By default popd will use the system password files if no RADIUS server has been configured or if it is not run in virtual mode. If popd is run in virtual mode, it will use the Virtual_password_file. If a RADIUS_server has been configured, popd will use RADIUS for password authentication. However, popd will always use the APOP_secret_database for all authentication requests using the APOP command.

popd also facilitates the process of sending system-wide notices to users with the bulletin feature. Bulletins are delivered to users at dowload time from files in the bulletin directory. Once the user has downloaded the bulletin, the user is not presented with that bulletin again.

The path to the bulletins is constructed as follows: in normal operation bulletin_dir and in virtual operation bulletin_dir/realm.

If popd is handed a an open socket on stdin and stdout, popd will not daemonise. In other words if popd is launched from inetd(8) it will not daemonise, but configuration options will still be observed.

The following options are available:

-4  Listen on IPv4 only. popd must be compiled with -DUSE_IPV6 for this option to work.

-6  Listen on IPv6 only. popd must be compiled with -DUSE_IPV6 for this option to work.

-a Virtual_password_file
    Use Virtual_password_file as the password file for authentication in virtual mode. This file is a Berkeley DB with the full the fully qualified username username@domain as the key and the crypt(3) encrypted password as the data. The path is relative to the specified etc_dir directory and the filename defaults to passwd.db.

-b bind_address
    Bind to bind_address where bind_address is an IP address. By default popd will bind to the wildcard address.

-c ssl_certfile
    The name of the file containing the ssl cert. This file is located in the etc_dir. Defaults to popd_cert.pem. popd must be compile with -DUSE_SSL for this option.

-d  Run in an interactive debug mode and do not daemonise or fork.

-e etc_dir
    etc_dir is the directory where the virtual password file and APOP secrets database are stored. Defaults to /usr/local/etc.

-k ssl_keyfile
    The name of the file containing the ssl private key. This file is located in the etc_dir. Defaults to popd_key.pem. popd must be compile with -DUSE_SSL for this option.

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

-n hash_depth
    Set the hash depth for the mail spool to 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.

-p POP3_port
    When in daemon or debug mode, listen on (numeric) POP3_port for incoming connections. Defaults to port pop3/tcp from /etc/services.

-r RADIUS_server RADIUS_secret
    [port [timeout [tries]]] Use RADIUS_server with secret RADIUS_secret for authentication of all login attempts. port, timeout, and tries optionally specify the RADIUS port, the timeout in seconds for each request and the maximum number of request retransmissions that may be made to the RADIUS server. If no values are specified, the default value for port will be applied from /etc/services, timeout and tries will default to 3 seconds and 3 tries respectively. popd will set the NAS-Port-Type attribute in the RADIUS authentication request to Virtual.

    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.

    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 popd uses /etc/services to determine port numbers for services.

-s server|proxy|both
    Enable SSL support for the POP3 server, the proxied connection or both. popd must be compiled with -DUSE_SSL for this option.

-t secs
    Time out connections after secs seconds of inactivity. Defaults to 300 seconds.

-u virtual_mail_user
    When running in virtual mode and once the client has been successfully authenticated, popd will setuid to virtual_mail_user for the remainder of the session. Defaults to pop.

-x  Places the daemon in debug mode (does not fork and exit). Connection information and PIDs of spawned children from incoming connections are written to STDOUT. If the -d option is set popd does not listen on the specified port, instead runs in interactive mode.

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

-B bulletin_dir
    The path to the bulletins. The user's realm will be appended to this path when popd is run in virtual mode. popd will present files in this directory to users as email messages in their mailbox. popd remembers which users have downloaded which messages.

-D  Autodelete messages from the user's mailbox on QUIT that are older than the specified time. See the -E option. Connection drops will not result in these messages being deleted. This option makes popd treat those messages retrieved by RETR that satisfy the expiry criterion as if they have also been deleted by the DELE command. Default is off.

-E expire_time
    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.

-F  Falsify UIDL information for messages older than -E time. Use this option in conjunction with -E and -D to force users to download old email which will then be autodeleted.

-M mailbox|maildir|maildircompat|mailidx
    Specify which of 4 supported mailbox formats popd should use. maildircompat is provided for compatibility with the previous and incorrect implimentation of maildir in prior versions of popd. Default is mailbox.

-N  Authenticate all sessions without performing password checking.

-P  popd will run as a POP3 proxy. This option requires the use of a RADIUS server and 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 popd 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.

-R remove_time
    Sumarily remove messages older than remove_time from the mailbox on QUIT. The format of time is the same as for the -E option.

-S APOP_secret_database
    The filename of the APOP_secret_database in the configured etc directory. If no APOP_secret_database is configured, the APOP command will be disabled. This file is a Berkeley DB with the fully qualified username username@domain or username depending on whether popd is running in virtual mode as the key and the secret as the data.

-U  Disable the UIDL command.

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

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

    The path to the user's mailbox is composed using the folowing schema: take the base directory, add the domain part of the username, add the hash structure if required and add the username.

FILES
/etc/services
    Translation of service names to port numbers.
etc_dir/passwd.db
    Password file for virtual POP3 server.
etc_dir/secrets.db
    APOP secrets database.
bulletin_dir/file1 ...
    The bulletins to users
bulletin_dir/domain/file1 ...
    The bulletins to users

EXAMPLES

1.  Vanilla configuration. Daemonise and listen on the pop3 port as in /etc/services and serve user's mail out of /var/mail. Authenticate using the system password files.

        # popd

2.  POP3 Proxy configuration. The radius server needs to be configured to return the required attributes for each user so that the proxy can connect to the correct server on the correct port.

    A default realm may be set to make the POP3 Proxy correctly qualify usernames for authentication.

        # popd -P -r "radius1 secret 1645"

3.  In the following example popd will run in virtual mode with a default realm of foo.com. Mail older that 10 weeks will be deleted on retrieval and mail older than 20 weeks will be sumarily removed. It will also falsflify UIDL information for messages older than 10 weeks.

    popd will authenticate using RADIUS on port 1645 with a 3 second timeout and 3 retries on each attempt.

    The mailbox is in Message Store Format.

        # popd -D -E10w -R20w -F -V -M -A foo.com \
        	-r "radius1 secret 1645"

4.  An example perl program makesecrets.pl is supplied to aid the construction of the APOP_secret_database. This program may be modified to build the Virtual_password_file, which has the same format as the APOP_secret_database.

SEE ALSO
setuid(2), sysexits(3), libradius(3) Network Working Group, Post Office Protocol - Version 3, RFC1939.

DIAGNOSTICS
Exit status as defined in sysexits(3) are returned.

popd reports status messages, warnings and errors via syslog(3) using the LOG_DAEMON facility. Warnings and errors are logged using the LOG_NOTICE and LOG_CRIT priorities, while connections, authentication and sessions are logged at LOG_INFO.

BUGS
This code should be fairly stable. We've been running it in production for the past 2 years.

Bulletins don't work in this release; I haven't yet figured out how to impliment them in the new mailbox API.

Please, when you send bug reports, send them to me directly and DO NOT CARBON COPY ANY MAILING LISTS WITH MY ADDRESS. Some lists are piped into usenet and I'm still fighting 10+ SPAMs a day from the last person that did this to me.

HISTORY
popd was originally written for UUNET South Africa in 1999.

AUTHORS
popd was written by Ian Freislich.

Send bug reports to Ian Freislich <ianf@za.uu.net>.