.\"	$OpenBSD: popa3d.8,v 1.7 2003/05/13 17:17:22 camield Exp $
.\"
.\" Copyright (c) 2001-2003 Camiel Dobbelaar (cd@sentia.nl)
.\" 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 ``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 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.
.\"
.Dd August 15, 2001
.Dt POPA3D 8
.Os
.Sh NAME
.Nm popa3d
.Nd "Post Office Protocol (POP3) server"
.Sh SYNOPSIS
.Nm
.Op Fl D | V
.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 mail reader 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.
.It Fl V
Show version information and exit.
.Pp
.El
.Pp
Alternatively,
.Nm
can be used through
.Xr inetd 8 .
This requires the following entry to be activated in
.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.
Additionally,
.Nm
does not permit null passwords and will refuse to serve mail for
root (uid 0) users.
.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