.\"	$OpenBSD: popa3d.8,v 1.4 2001/09/24 19:08:01 camield Exp $
.Dd August 15, 2001
.Dt POPA3D 8
.Os
.Sh NAME
.Nm popa3d
.Nd "Post Office Protocol server"
.Sh SYNOPSIS
.Nm
.Op Fl D
.Sh DESCRIPTION
.Nm
is a POP3 server.
It offers network access to user mailboxes through the POP3 protocol.
The server uses the 
.Tn TCP
protocol
and listens at the port specified in the
.Dq pop3
service specification; see
.Xr services 5 .
.Pp
A POP3 server operates on local mailboxes on behalf of its remote
users.
Users can connect at any time to check their mailbox and fetch the
mail that has accumulated.
The advantage of this ``pull'' approach is that any user with a simple
POP3-capable mailreader program can receive mail, eschewing the need
for a full-fledged Mail Transfer Agent (MTA) and a permanent network
connection.
.Pp
Note that POP3 can only be used to retrieve mail, not to send it.
To send mail, the SMTP protocol is commonly used; see
.Xr sendmail 8 .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl D
With this option set,
.Nm
will detach and become a daemon, accepting connections on the pop3
port and forking child processes to handle them.
This has lower overhead than starting
.Nm
from
.Xr inetd 8
and is thus useful on busy servers to reduce load.
.Pp
In this mode
.Nm
also does quite a few checks to significantly reduce the impact of
connection flood attacks.
.Pp
.El
.Pp
Alternatively,
.Nm
can be used through
.Xr inetd 8 .
This requires the following entry to be added to
.Pa /etc/inetd.conf :
.Pp
.Pa pop3 stream tcp nowait root /usr/sbin/popa3d popa3d
.Pp
or, using
.Xr tcpd 8
for TCP-wrappers access control:
.Pp
.Pa pop3 stream tcp nowait root /usr/libexec/tcpd /usr/sbin/popa3d
.Pp
For access to a mailbox through the POP3 service, the username must
be in the password database and the password field must not be
empty.
Authentication for super-users like root will always fail, even if the
password is correct.
.Sh COMMANDS
A normal POP3 session progresses through three states: authorization,
transaction and update.
.Pp
After the TCP connection opens, the client must authenticate itself
to the server in the authorization state.
The following commands are supported in the authorization state.
All commands are case-insensitive.
.Bl -column "Command    " -offset indent
.It Sy Command Ta Sy Description
.It USER name Ta "authenticate as user ``name''"
.It PASS string Ta "authenticate using password ``string''"
.It QUIT Ta "quit; do not enter update state"
.El
.Pp
When authorization is successful, the server enters the transaction
state.
The client can now list and retrieve messages or mark messages for
deletion.
The following commands are supported in the transaction state.
.Bl -column "Command    " -offset indent
.It Sy Command Ta Sy Description
.It DELE msg Ta "mark message for deletion"
.It LAST Ta "show highest message number accessed (obsolete)"
.It LIST [msg] Ta "list message number and size"
.It NOOP Ta "do nothing" 
.It QUIT Ta "quit; enter update state"
.It RETR msg Ta "retrieve message"
.It RSET Ta "clear deletion marks"
.It STAT Ta "return total number of messages and total size"
.It TOP msg n Ta "show top n lines of message body"
.It UIDL [msg] Ta "list message number and digest"
.El
.Pp
When the client issues the QUIT command in the transaction state,
the server enters the update state.
All messages that were marked for deletion are now removed.
The server then closes the connection.
.Sh FILES
.Bl -tag -width Ds
.It Pa /var/mail
User mail spools
.It Pa /etc/hosts.allow, /etc/hosts.deny
TCP-wrappers access controls may be defined here as described in
.Xr hosts_access 5 .
Valid if
.Nm
is started in daemon-mode, or if
.Nm
is running through
.Xr inetd 8
and is used in combination with
.Xr tcpd 8 .
.El
.Sh SEE ALSO
.Xr inetd 8 ,
.Xr sendmail 8
.Pp
Official Internet Protocol Standard
.%T STD 53 ,
also known as
.%T RFC 1939 .
.Pp
http://www.openwall.com/popa3d/
.Sh HISTORY
.Nm
first appeared in
.Ox 3.0 .
.Sh CAVEATS
POP3 authenticates using cleartext passwords.
.Sh AUTHORS
Solar Designer
.Aq solar@openwall.com