NOTE
This man page may be out of date. Please see the Adminis_
trator's Guideincluded in the distribution or on the
Qpopper web site at www.qpopper.org/documentation.html

DESCRIPTION
Qpopper is a POP3 server to enable POP3clients to read
and download mail. This server implements the POP protocol
defined in RFC 1939 and the RFC 2449 extensions. This
implementation runs on a variety of Unix platforms,
including Linux.

The server also enables clients to sendmail using XTND
XMIT, which is processed via sendmail(8).

OPTIONS
[address][:][port]
If compiled asa standalone daemon (instead of
being run from inetd), you can can specify the IP
address and/or port number to bind to at run-time
as parameter 1, e.g., 'popper 199.46.50.7:8110 -S'
or 'popper 8110 -S -T600'. If not specified, the
IP address defaults to all available. The default
port is110 except when _DEBUG (not simply DEBUG)
is defined, then it is 8765.

See the Administrator's Guide file for more infor
mation on standalone mode.

-b bulldir
Turns on the bulletinfeature and specifies the
bulletin directory path.The command line over
rides the compiled value if it is defined. To
enable bulletins by default and specify a default
bulletindirectory during compilation, include the
--enable-bulletins=bull-directory flag when running
./configure. The usual bulletin directory is
/var/spool/bulls.
A bulletin database can be used to trackthe bul
letins instead of the users' home directory. This
feature is enabled byincluding the--enable-
bulldb=bull-directory flag when running ./config
ure.

-c Downcases user names. This permits users to con
figure their clients with user names in UPPER or
MiXeD case, and still login, assuming their actual
user name is all lower case.

-d Turns on debug logging if compiled (pass --enable-
debugging to ./configure). All debugging informa
tion issaved using syslog(8).If this option is
used, it should be first, so that debug records are
generated for subsequent options.

-D drac-host
If compiled with --enable-drac, specifies the drac
host. Defaults to localhost.

Remember neither Expire nor Login Delay is enforced
by qpopper; Sysadminshave to implement them by
some other means. However, you can enforce EXPIRE
0 (no retention at all) by using the --enable-auto-
delete flag with ./configure. This causes messages
to be automatically deleted after they are down
loaded.

-k Enables Kerberos authentication when qpopper has
been compiled with --with-kerberos5.You must
already have libraries that support Kerberos.

-K service
The specified Kerberos service is used instead of
the compiled-invalue. The default is rcmd, but
pop is also common.

-l 0|1|2
Sets TLS/SSL handling. Must have compiled with
OpenSSL or SSL Plus.

0 is the default. TLS/SSL is not supported.
1 enables the STLS command. This permits a client
to attempt TLS/SSL negotiation after connecting.

2 Causes Qpopper to attempt TLS negotiation whena
client first connects. This is for alternate-port
support.

-p 0|1|2|3|4
Sets plain-text password handling options. To use
this option, you must have an alternative to plain-
text passwords available, such as APOP.

0 is the default, which permitsplain-text pass
words only for those users who are not in the APOP
database.

1 disables plain-text passwords for all users, even
those who are not in the APOP database.

2 permits plain-text passwords for all users, even
those who are in the APOP database (this allows
clients to fall back on plain-text authentication
if they do not support APOP).

3 allows plain-text passwords only for connections
on the loop-back (127.*.*.*) address.

4 permits plain-text passwords only if TLS/SSL has
been negotiated for the session (requires an exe
cutable compiled with OpenSSL or SSL Plus).

-R Disables reverse lookups on client IP addresses.

-t trace-file
Turns on debug logging if compiled (pass --enable-
debugging to ./configure) and writes the trace
information in trace-file using fprintf(3V). If
this option is used, it should be first, so that
debug records are generated for subsequent options.

-s Turns onstatistics logging using syslog(8) or
trace-file. At the end of each popper session, the
following information is logged:username, number
of messages deleted, number of bytes deleted, num
ber of message left on server, number of bytes left
on server.

-S Enables server mode. This mode reduces disk I/O
and disk space usage when popper is used on a sys
tem that serves POP only users exclusively.

When the server is waiting for a command to arrive
from the client, it times out after thespecified
number of seconds and terminates the session. This
avoids having popper processes hang forever waiting
for command input from clients which have termi
nated abnormally or are hung.

A small value is ok for small to medium networks
where the network delay is within a few seconds.
In this case 15-30 seconds is not unreasonable.
Networkswith large delays in sending packets
(e.g., SLIP links) may require a larger value. In
this case 300 seconds (5 minutes) is not unreason
able.

Note that RFC 1939 requires a minimum of 600 second
(10 minutes).

-u After a user authenticates, process options from a
file called .qpopper-options inthe user's home
directory. This file can be owned by and writable
by the user.

-U After a user authenticates, process options froma
file called .<user>.qpopper-options in the spool
directory, where <user> is the user name. This
file should not be owned by nor writable by the
user.

-v Report the current version and exit.

Processing Options are described below.

Processing Options
Here are some options the values of which areannounced
to clients. Syntax of the options is:

opt=value,...

This sets option opt to be value. Multiple options can be
specified at one instance and are comma separated.

The following are the options supported:
login_delay
expire

Config-File Options
You can set Qpopper run-time options either from the com
mand line or in a configuration file.
Configuration files use different option names and a dif
ferent syntax than the command-line (because command-line
options are limited to one character).

In other words the line starts with set or reset, then an
option name, and either ends there or has an = followed by
a value.

A comment line starts with #. The restof the line is
ignored. You can also use # to end any line. Everything
else on the line is a comment.

Note that reset can only be used withboolean options.
The = and the value are omitted when reset is used. When
set is used with a boolean option, you can omit the = and
value if you wish (it defaults to true), or you can use
any of the four values true, false, 1, or 0.

Some options are "restricted", meaning that they can't be
used in a .qpopper-options file in a user's home directory
and/or in a <user>.qpopper-options file in the spool
directory.

Type: Boolean
Equivalent switch: "-R" (Sense reversed!)
Restricted:not valid in a configuration file in the
user's home directory nor in the spool directory.

Sense reversed from command-line switch. Using -R is
the same as 'SET REVERSE-LOOKUP = FALSE'.

server-mode
Type: Boolean
Equivalent switch: "-S"
Restricted: no

statistics
Type: Boolean
Equivalent switch: "-s"
Restricted: no

timeout
Type: Integer
Equivalent switch: "-T timeout"
Restricted: no

tls-support
Type: Mnemonic
Equivalent switch: "-l"
Values:

default
TLS/SSL not supported.

none (same as default).

stls Enables support for the STLS command.

alternate-port
Enables alternate-port TLS/SSL.
Restricted:not valid in a configuration file in the
user's home directory nor in the spool directory.

Only valid if compiled with OpenSSL or SSL Plus.

tracefile
Type: Name
Equivalent switch: "-t logfile"
Restricted: no

Only valid if compiled with --enable-debug.

spool-options
Type: Integer
Equivalent switch: "-U"
Restricted: not valid in a configuration file in the
user's home directory nor in the spool directory.

user-options
Type: Integer
Equivalent switch: "-u"
Restricted:not valid in a configuration file in the
user's home directory nor in the spool directory.

BULLETINS
The bulletin feature gives system administrators a way to
send important announcements to all POP users without hav
ing to do mass mailings.

The bulletin directory containsone file perbulletin.
Each file contains a single mail message with a header and
body in normal mailbox format. The first line of each such
bulletin must be a "From " line. The easiest way for
sysadmins to create such bulletins is to mail themselves a
copy of the bulletin using the account to which they want
replies to be sent, then use their mailprogram to save
the message to a file in the bulletin directory in mailbox
format. The bulletin directory must be world readable.

The name of each bulletin file begins with the bulletin
number, and may optionally continue with any other charac
ters. E.g., the file name of bulletin number 23might be
"23.pophost_down_sunday".

Popper creates a file named .popbull in the home directory
of each user. This file contains a single linerecording
the highest numbered bulletin received by the user.

Each time a POP client connects to the server, any new
bulletins which the user has not received previously are
automatically appended to the user's mail.

When abulletin is copied, the "To" header line is
replaced by "To: username@thishost ", and any"Status:"
header lines are deleted. Otherwise, the bulletin is
copied as is.

When a new user checks for mailthe first time, popper
creates the .popbull file in the user's home directory and
seeds it with the current maximum bulletin number. Thus
new users do not get old bulletins.
Type: Integer
Equivalent switch: "-U"
Restricted: not valid in a configuration file in the
user's home directory nor in the spool directory.

user-options
Type: Integer
Equivalent switch: "-u"
Restricted:not valid in a configuration file in the
user's home directory nor in the spool directory.

BULLETINS
The bulletin feature gives system administrators a way to
send important announcements to all POP users without hav
ing to do mass mailings.

The bulletin directory containsone file perbulletin.
Each file contains a single mail message with a header and
body in normal mailbox format. The first line of each such
bulletin must be a "From " line. The easiest way for
sysadmins to create such bulletins is to mail themselves a
copy of the bulletin using the account to which they want
replies to be sent, then use their mailprogram to save
the message to a file in the bulletin directory in mailbox
format. The bulletin directory must be world readable.

The name of each bulletin file begins with the bulletin
number, and may optionally continue with any other charac
ters. E.g., the file name of bulletin number 23might be
"23.pophost_down_sunday".

Popper creates a file named .popbull in the home directory
of each user. This file contains a single linerecording
the highest numbered bulletin received by the user.

Each time a POP client connects to the server, any new
bulletins which the user has not received previously are
automatically appended to the user's mail.

When abulletin is copied, the "To" header line is
replaced by "To: username@thishost ", and any"Status:"
header lines are deleted. Otherwise, the bulletin is
copied as is.

When a new user checks for mailthe first time, popper
creates the .popbull file in the user's home directory and
seeds it with the current maximum bulletin number. Thus
new users do not get old bulletins.
Bulletins can be enabled bydefault, and the bulletin
directory specified, by including the --enable-bul
letins=bull-directory flag when running ./configure.

To use a database instead of .popbull files in users' home
directories for tracking the highest bulletin seen bya
user, include the --enable-bulldb=bull-directory flag when
running ./configure. You must also create two empty files
in the bulletin directory, called bulldb.pag and
bulldb.dir. When a bulletin database is used, qpopper
checks for and uses any .popbull files in the user's home
directory, to provide continuity.

To specify the maximum number of bulletins sent to new
users, includethe --with-new-bulls flag when running
./configure. For example, --with-new-bulls=10 says that
new users get at most ten bulletins.

THE POP TRANSACTION CYCLE
The Qpopper server is a single program (called popper)
that is launched by inetd when it gets a service request
on the POP TCP port. (The official port number specified
in RFC 1939 for POP version 3 is port 110. However, some
POP3 clients attempt to contact the server at port 109,
the POP version 2 port.Unless you are running both POP2
and POP3 servers, you can simply define both ports for use
by the POP3 server. This is explained in the installation
instructions later on.)

The qpopper program initializes and verifies that the peer
IP address is registered in the local domain (unless the
-R command-line option is used), logging a warning message
when a connection is made with a client whose IP address
does not have a canonical name.For systems using BSD 4.3
bind, it also checks to see if a canonical name lookup for
the client returns the same peer IP address, logging a
warning message if it does not.

The server enters the authorization state, during which
the client must correctly identify itself by providing a
valid Unix userid andpassword on the server's host
machine (or successfully authenticate using APOP or AUTH).
No other exchanges are allowed during this state (other
than a request to quit.) If authentication fails, a warn
ing message is logged and the session ends.

Once the user is identified, qpopper changes its user and
group ids to match that of the user and enters the trans
action state. The server makes a temporary copy of the

user's maildrop which is used for all subsequent transac
tions (unless running in server mode ).These include the
bulk of POP commandsto retrieve mail, delete mail,
undelete mail, and so forth.

When the client quits, the server enters the final update
state, during which the network connection is terminated
and the user's maildrop is updated with the (possibly)
modified temporary maildrop.

LOGGING
The POP server uses syslog to keep a record of its activi
ties. On systems with BSD 4.3 syslogging, the server logs
(by default) to the "local0" facility at priority "notice"
for all messages except debugging which is logged at pri
ority "debug". The defaultlog file is
/usr/spool/mqueue/POPlog. These can be changed, if
desired. On systems with 4.2 syslogging all messages are
logged to the locallogfile, usually
/usr/spool/mqueue/syslog.

DEBUGGING
Qpopperlogs debugging information when the -d parameter
is specified after its invocation in the inetd.conf file.
Care should be exercised in using this option since it
generates considerable output in the syslog file. Alter
natively, the "-t <file-name>" option places debugging
information into file "<file-name>" using fprintf instead
of syslog.

For SunOS version 3.5, the popper program is launched by
inetd from /etc/servers. This file does not allow you to
specify command line arguments.Therefore, if you want to
enable debugging, you can specify ashell script in
/etc/servers to be launched instead of popper and in this
script call popper with the desired arguments.

You can confirm that the POP server is running on Unix by
telneting to port 110 (or 109 if you set it up that way).
For example:

XTND XLIST header [num]: Extracts and returns the speci
fied header line for the specified message number. If the
"num" parameter is missing, returns theheaderline for
all the messages which are not currently marked for dele
tion.

XMANGLE: Can be used as a modifier to the TOP, RETR, LIST
commands. The result is to condense MIME messages into a
single part. For example:

RETR 10 XMANGLE(text=html;headers=to:,cc:,from:,date:)
results in transforming message 10 into a single part of
content-type text/html with only those headers which were
requested.

Qpopper also supports the "-no-mime" user name hack. As a
way to enable MIME-mangling with clients that do not sup
port XMANGLE, add "-no-mime" to the user name. For exam
ple, if the userid is "mary", enter it in the client as
"mary-no-mime".