.TH IN.MDPOP3D 8 "12 Dec 2000" "System Daemons" .SH NAME mdpop3d, in.mdpop3d \- Post Office Protocol version 3 daemon for Maildirs. .SH SYNOPSYS \fBmdpop3d\fR [\fIoptions\fR] .SH DESCRIPTION .PP This implementation of POP3 daemon works with qmail-stype Maildirs, typically in user's home directories. It is very small and simple but have all required for pop3 daemon features. .PP \fBmdpop3d\fR can be used in two modes: it can work with mail storage only, providing only transaction stage of POP3 protocol, and it optionally can provide simple authentication. In this way it differ from e.g. qmail-pop3d, as by default this \fBmdpop3d\fR will work for most situatuons without additional support programs. For many sites with regular users this is sufficient. .PP \fBmdpop3d\fR can authenticate users using PAM or using plain unix \fBgetpwnam\fR(3) and \fBgetspnam\fR(3) methods, depending on compilation options. For PAM, service name used is \fBpop3\fR and may be changed by \fB-p\fR option. .PP If PAM support is enabled, \fBmdpop3d\fR can be compiled with support of \fBAPOP\fR command (note that this command is available only with PAM, and only if specially compiled in and if activated in command line). APOP implementation requires special PAM module capable of checking client-provided md5 hash against user's password. \fBmdpop3d\fR simply passes md5hash from client and server-generated timestamp to PAM library in place of a password (see USAGE section below), and some PAM module should be able to use this information to check client-supplied credentials. .PP When \fBmdpop3d\fR authenticates user itself (the default), it will by default look to \fBMaildir\fR subdirectory in user's home directory as returned by \fBgetpwent\fR(3) call (usually this info stored in /etc/passwd file). This default directory name may be changed by \fB-m\fR option or by \fBMAILDIR\fR environment variable. .SH OPTIONS .PP \fBmdpop3d\fR accepts the following command-line options: .IP "\fB-t \fItimeout\fR" set timeout value. If there will be no activity for this number of secounds, \fBmdpop3d\fR will terminate session without any changes in mail directory. This timeout applies also to output: if \fBmdpop3d\fR will not be able to write a line to client in this time, it will also terminate session. Default value is 60 (1 minute), that should be more than enouth for almost all situations. POP protocol is not a long-running protocol like e.g. IMAP, so timeout seemed to be reasonable here. .IP \fB-c\fR commit maildir on error/timeout. If this option given, \fBmdpop3d\fR will execute implicit QUIT command on any client communication error (i.e. timeout, closed connection etc). This way, messages marked as deleted will be removed from disk even without QUIT command. This violates protocol, but can help with broken mail clients on slow unstable dialup links, where client can loop forewer trying to retrieve all the messages at one session (this is known to be the case for some versions of M$ OutGluck). .IP "\fB-m \fImaildir\fR" look to this \fImaildir\fR subdirectory inside user's home directory instead of default \fBMaildir\fR for user's mail. This option is \fInot\fR ignored in pre-authenticated mode (\fB-a\fR or \fB-u\fR options), the only difference is that \fBmdpop3d\fR will chdir to this directory from current invocation directory, not from user's home. To specify current directory (or home dir itself), use `\fB-m.\fR' (i.e. use `.' for maildir). See also \fBMAILDIR\fR environment variable (this option takes precedence). .IP \fB-a\fR request pre-authenticated mode. \fBmdpop3d\fR goes to transaction state upon invocation, and tries to open Maildir (subject to \fB-m\fR option and \fBMAILDIR\fR environment variable) \fIin current working directory\fR. Authentication procedure in this case should be performed by the calling program, together with all required \fBsetuid\fR(2) etc calls. This is the only mode of operation supported by qmail-pop3d alone. \fBmdpop3d\fR will run under whatether user- and group-id as calling process. Unless \fB-u\fR option is also given, \fBmdpop3d\fR will use value of \fBLOGNAME\fR environment variable as a user name for logging purposes, or, if this variable is not set, it will derermine logged in user by a call to \fBgetpwuid\fR(). .IP "\fB-u \fIusername\fR" similar to \fB-a\fR option (\fBmdpop3d\fR will go to transaction state), but provides also username for logging purposes. With this option, \fB-a\fR is useless. .IP "\fB-r \fIhost\fR" specifies host name or ip address of client, used for logging purposes and as \fBPAM_RHOST\fR if compiled with PAM support. The same effect have \fBTCPREMOTEIP\fR or \fBREMOTE_HOST\fR environment variables. If not given, \fBmdpop3d\fR will try to determine client ip address itself using \fBgetpeername\fR(2). .IP "\fB-R \fIhostvar\fR" this options names environment variable that holds remote host name or ip address, instead of \fBTCPREMOTEIP\fR and \fBREMOTE_HOST\fR. If this option given and no \fIhostvar\fR variable exists, \fBmdpop3d\fR will refuse to start. .IP \fB-q\fR be somewhat quiet. Normally \fBmdpop3d\fR logs all connections and disconnections via syslog at \fBLOG_INFO\fR priority. With this option it omits this exactly logging (but it still logs error conditions). .IP \fB-n\fR this is mostly debugging option. With this, \fBmdpop3d\fR will not move messages from \fBnew/\fR directory in maildir to \fBcur/\fR directory. If this is only one program used for mail retrieval, then this saves some number of system work that may be noticable on heavily loaded machine. \fBmdpop3d\fR still looks to \fBcur/\fR directory if it exists, and will remove deleted messages from both directories. .IP \fB-d\fR requests debugging. With this, all data \fIreceived\fR from client will be logged via syslog with \fBLOG_DEBUG\fR priority. Note that this data will \fInot\fR contain user's passwords (all text for the PASS command will be replaced by ""). .IP "\fB-p \fIservice\fR" use PAM service name \fIservice\fR instead of default \fBpop3\fR. May be useful for e.g. supporting ip-based virtual pop service (setup separate PAM configs for each local ip address). Not valid if \fBmdpop3d\fR was compiled without PAM support. .IP \fB-A\fR enable APOP command. This option valid only if \fBmdpop3d\fR was compiled with both PAM and APOP support. .IP "\fB-T \fIhtag\fR" enable APOP command and use \fIhtag\fR for generating server-side APOP tag (timestamp), placing this \fIhtag\fR after at (@) sign. RFC1939 recommends that server-side timestamp constructed in the following form , where HTAG is FQDN of a server. By default (if only \fB-A\fR option is given), \fBmdpop3d\fR will use \fBgethostname\fR() call to determine this \fIhtag\fR. This option valid only if \fBmdpop3d\fR was compiled with both PAM and APOP support. .IP \fB-V\fR if this option given, \fBmdpop3d\fR will print version information and exit. If compiled with PAM or APOP support, this will be indicated. .SH ENVIRONMENT .PP \fBmdpop3d\fR may use some environment variables. Since this program should be invoked in some "friendly" environment (i.e. \fBinetd\fR(8) or some other daemon), and because environment used for non-critical tasks (mostly logging), usage of environment variables is safe. .IP "\fBTCPREMOTEIP\fR, \fBREMOTE_HOST\fR" if set and not empty, will be used as an ip address of client accessing service (\fBmdpop3d\fR uses first of those that is available). Some inetd implementations sets one of this variables when invoking programs (one such implementation is courier tcpd), and some other programs may set them as well (e.g. \fBstunnel\fR(8)). Command-line option \fB-h\fR has precedence. The only usage of this address is for logging purposes, and, if \fBmdpop3d\fR compiled with PAM support, address will become \fBPAM_RHOST\fR PAM item. .IP \fBLOGNAME\fR when \fBmdpop3d\fR invoked with \fB-a\fR option, this variable, if set, used as a username of logged in (and authenticated by calling program) user. The only usage of this username is for logging purposes. Command line option \fB-u\fR have precedence here. Note that this variable will be used \fIonly\fR in pre-authenticated mode. .IP \fBMAILDIR\fR look to this directory for user's mail (\fBMaildir\fR by default). May be overwritten by \fB-m\fR option. .SH USAGE .PP Typically \fBmdpop3d\fR will be invoked directly by \fBinetd\fR(8) daemon, like this: pop3 stream tcp nowait root /usr/sbin/in.mdpop3d mdpop3d This is all that needed for usual functionality to serve regular unix users's mails. Also, \fBmdpop3d\fR may be invoked by some authenticator program, with correct userid, correct current directory and providing \fB-a\fR option. If you're familiar with qmail, than the \fBqmail-popup\fR(8) program is the best reference for this. .PP \fBmdpop3d\fR will always serve only \fIone\fR request, it is not a long-running process. Then client issues QUIT command, or when there is timeout or client disconnect condition, or if \fBmdpop3d\fR failed to authenticate user, it will terminate session and exit. .PP If APOP support was compiled in (requires also PAM support) and enabled in command line (with \fB-A\fR option), \fBmdpop3d\fR will accept and handle APOP command. This is alternative of using USER and PASS command that avoids transmission of passwords in cleartext over network, but also requires that cleartext password to be known by server. In order to use/enable APOP command, one should provide some PAM module that will have access to original client's password and can compute md5 hash from it and a timestamp string supplied by \fBmdpop3d\fR and compare computed value with client-supplied md5 hash. After receiving APOP command, \fBmdpop3d\fR will check if it is syntactically correct (by ensuring that supplied md5 hash value consists of exactly 32 lowercase hexadecimal digits), and will call pam library providing the string "APOP", space, this md5 hash as received from client, space and server-generated timestamp string, all in place of a password. For example, "password" provided to PAM may look like this: APOP 0123456789abcdef0123456789abcdef <12.3456@host> PAM module can check if password have this form ("APOP " prefix should be sufficient) and handle it accordingly. Example PAM config entry that support both APOP and USER/PASS: auth sufficient pam_apop.so auth required pam_unix.so ... In this case, pam_apop module should check if password starts with "APOP ", then obtain original password, compute md5 hash from timestamp string and this password and compare with supplied hash, and then return either success or failure. If it doesn't starts with "APOP ", then this module should return PAM_IGNORE, so that request will be processed by pam_unix module. .PP Note that such hypotetic pam_apop module is very site-dependant and \fInot\fR provided with \fBmdpop3d\fR. I would be glad to hear if anyone ever use the APOP feature at all... .PP If \fBmdpop3d\fR compiled with PAM support, it is trivial to support "virtual" maildirs using only one system account. For this, PAM module should be written that will check client-supplied credentials (username and password), and sets PAM_USER to the owner of virtual mail storage and $MAILDIR environment (either using \fBpam_putenv\fR() or \fBsetenv\fR()) to point to maildir for a user relative to mail owner home. With this, \fBmdpop3d\fR can be used for both virtual mail storage and for regular user's maildirs simultaneously, having properly configured PAM module stacking. Please refer to PAM documentation for further details. To support many virtual domains, one can form POP3 username using both name of a user \fIand\fR domain name. Again, such a module does not provided with \fBmdpop3d\fR (yet), while it can be of general use. .SH PROTOCOL .PP \fBmdpop3d\fR supports the following POP3 commands: .IP NOOP no operation .IP "USER \fIuser\fR" specifies username (not valid in transaction state) .IP "PASS \fIpassword\fR" specifies user's password (valid only after USER) .IP "APOP \fIuser md5digest\fR" alternative way to specify user credentials. This command recognized only if APOP support compiled in and activated in command line (\fB-A\fR option). .IP QUIT terminates session. In transaction state \fRmdpop3d\fR will update maildir. .IP "LIST [\fImsgno\fR]" get size of message \fImsgno\fR or for all messages .IP "UIDL [\fImsgno\fR]" return unique identifier(s) for message(s) .IP "TOP \fImsgno lines\fR" return headers of message \fImsgno\fR and at most \fIlines\fR lines of body .IP "RETR \fImsgno\fR" return (retrieve) message \fImsgno\fR .IP "DELE \fImsgno\fR" marks message \fImsgno\fR as deleted .IP RSET reset message deleted flags from all previously deleted messages .IP CAPA list of server's capabilities. Currently, \fBmdpop3d\fR lists UIDL, TOP and USER as a responce. .PP When responding to client's commands, \fBmdpop3d\fR is somewhat quiet. For example almost all positive responces consists of just three characters \fB+OK\fR followed by CR, LF pair, no additional information used. POP3 used almost by software clients, not humans, and that additional info will always be discarded. .SH BUGS .PP When using own implementation of password checking (via \fBgetpwnam\fR(3) et al), password aging is not checked, and userid also (thus, \fBmdpop3d\fR will allow user with uid=0 and/or expired password to log in) -- only minimal checking done. This can be easily "cured" by using PAM that is far more preferable method anyway. .PP Any possible message from PAM discarded completely. This really isn't a bug in this daemon itself, but in difficulties communicating of non-interactive application uses predefined protocol with pam framework. On any error in pam \fBmdpop3d\fR responds with generic "login incorrect" message. .PP \fBmdpop3d\fR will \fInot\fR allow user to log in with empty password, and there is no way to tell it to do so. This may be considered a bug, but I mostly disagree. .PP POP protocol transmits plaintext passwords over network. For unsecure networks this may be not acceptable. As a workaround there may be some "autheticator" that sets up a secure (encrypted) connection and calls this \fBmdpop3d\fR program. One example of this is ssl wrapper such as \fBstunnel\fR(8). .PP \fBmdpop3d\fR reports incorrect message size(s). It uses message file size as returned by \fBstat\fR(2) system call as a message size, but this does not includes extra carriage return (CR) character at the end of each line, as required by POP3 protocol. It is a protocol violation, but I think that it isn't a (serious) issue. Many other pop3 daemons do the same. .PP \fBmdpop3d\fR will refuse to work with files in Maildir that have very long names and thus may overflow static \fBmdpop3d\fR buffer. Such a files will be silently ignored. Currently limit of filename is about 1018 characters, that should be sufficient for all environments where \fBmdpop3d\fR will run. .SH "SEE ALSO" mail(1), qmail-pop3d(8), sendmail(8), inetd(8), stunnel(8), rfc1939 (Post Office Protocol - Version 3), rfc2449 (POP3 Extension Mechanism) .SH LICENSE .PP This software can be distributed under the terms of the GNU General Public License (GPL) version 2 or any further version. .SH AUTHOR .PP This software and manual page has been written by Michael Tokarev, mjt@corpit.ru.