qpopper(8) Local qpopper(8)
26 April 2010
NAME
qpopper -- POP3 server (v4.1)
SYNOPSIS
/usr/local/lib/popper [ [ address ] [ : ] [ port ] ]
[ -b buildir ] [ -c ] [ -d ] [ -D drac-host ]
[ -e login_delay=nn,expire=nn ] [ -f config-file ]
[ -k ] [ -K service ] [ -l0|1|2 ] [ -p0|1|2|3|4 ]
[ -R ] [ -s ] [ -S ] [ -t trace-file ] [ -T timeout ]
[ -u ] [ -U ] [ -v ] [ -V ] [ -x ] [ -y log-facility ]
NOTE
This man page may be out of date. Please see the Administrator's
Guide included in the distribution or on the Qpopper web site at
www.qpopper.org/documentation.html
DESCRIPTION
Qpopper is a POP3 server to enable POP3 clients 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 send mail using XTND XMIT, which is
processed via sendmail(8).
OPTIONS
[address][:][port]
If compiled as a 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 IPv6 support
is compiled in, address can be also IPv6 address by enclosing the
address with `[' and `]'. If not specified, the IP address
defaults to all available. The default port is 110 except when
_DEBUG (not simply DEBUG) is defined, then it is 8765.
See the Administrator's Guide file for more information on
standalone mode.
-b bulldir
Turns on the bulletin feature and specifies the bulletin
directory path. The command line overrides the compiled value if
it is defined. To enable bulletins by default and specify a
default bulletin directory 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 track the bulletins instead of
the users' home directory. This feature is enabled by including
- 1 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
the --enable-bulldb=bull-directory flag when running ./configure.
-c Downcases user names. This permits users to configure 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 information is saved 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.
-e x=value,...
Sets POP3 extensions. Sets x to the specified value. Used to
include Login Delay and/or Expire response tags to the CAPA
command.
Remember neither Expire nor Login Delay is enforced by qpopper;
Sysadmins have 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 downloaded.
-f config-file
Reads additional run-time options from config-file. See Config-
File Options for option names and syntax.
-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-in
value. 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 when a client first
connects. This is for alternate-port support.
- 2 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
-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 permits plain-text passwords only for
those users who are not in the APOP database.
1 disables plain-text passwords for all APOP database.
2 permits plain-text passwords for all database (this allows
clients to fall back on plain-text authentication if they do not
support APOP).
3 allows plain-text passwords only for address.
4 permits plain-text passwords only if TLS/SSL has been
negotiated for the session (requires an executable 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 on statistics 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,
number 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 system that serves POP only users
exclusively.
-T timeout
option changes the default compiled value POP_TIMEOUT for
terminating a session with a pop client.
When the server is waiting for a command to arrive from the
client, it times out after the specified number of seconds and
terminates the session. This avoids having popper processes hang
forever waiting for command input from clients which have
terminated 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. Networks with large delays in
- 3 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
sending packets (e.g., SLIP links) may require a larger value.
In this case 300 seconds (5 minutes) is not unreasonable.
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 in the user's home directory. This file can be
owned by and writable by the user.
-U After a user authenticates, process options from a 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.
-V Report the current version and exit.
-x Disable use of XTND XMIT. NOTE: Administrators are strongly
encouraged to disable XTND XMIT in favor of mechanisms such as
SMTP AUTH.
-y log-facility
Processing Options are described below.
Processing Options
Here are some options the values of which are announced 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 command line or
in a configuration file.
Configuration files use different option names and a different syntax
than the command-line (because command-line options are limited to one
character).
The general syntax of the config file (in ABNF) is:
config-line ::= comment-line / reset-line / set-line
comment-line ::= "#" <comment-text to end of line>
- 4 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
reset-line ::= "reset" boolean-option
set-line ::= implicit-set / explicit-set
explicit-set ::= "set" option "=" value
implicit-set ::= "set" boolean-option
option ::= boolean-option / integer-option /
string-option / mnemonic-option
value ::= "true" / "false" / integer / name
string ::= <"> 1*255 CHAR <">
CHAR ::= <any printable character except space or tab>
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 rest of 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 with boolean 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.
The following are the command line options you can use:
announce-login-delay
Type: Integer
Equivalent switch: "-elogin_delay=xx"
Restricted: no
announce-expire
Type: Integer
Equivalent switch: "-e expire=xxx"
Restricted: no
bulldir
Type: Name
Equivalent switch: "-b bulldir"
Restricted: no
- 5 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
bulldb-nonfatal
Type: Boolean
Equivalent switch: "-B"
Restricted: no
Only valid if compiled with --enable-bulldb.
clear-text-password
Type: Mnemonic
Equivalent switch: "-p0|1|2|3|4"
Values:
default
Permits clear-text passwords for any user not in the APOP
database.
never
Clear-text passwords are never permitted. Users not in the
APOP database are unable to use Qpopper.
always
Clear-text passwords are always permitted, even for users in
the APOP database.
local
Clear-text passwords are permitted only when the client
connects through the local interface (127.*.*.*).
tls Clear-text passwords are permitted when TLS/SSL has been
negotiated for the session. Available only if compiled with
OpenSSL or SSL Plus.
ssl (Same as tls).
Restricted: not valid in a configuration file in the user's home
directory nor in the spool directory.
config-file
Type: Name
Equivalent switch: "-f config-file"
Restricted: no
debug
Type: Boolean
Equivalent switch: "-d debug
Restricted: no
Only valid if compiled with --enable-debug.
downcase-user
Type: Boolean
Equivalent switch: "-c"
- 6 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
Restricted: not valid in a configuration file in the user's home
directory nor in the spool directory.
drac-host
Type: Name
Equivalent switch: "-D drac-host"
Restricted: no
Only valid if compiled with --enable-drac
kerberos
Type: Boolean
Equivalent switch: "-k"
Restricted: not valid in a configuration file in the user's home
directory nor in the spool directory.
Only valid if compiled with --enable-kerberos5 or -DKERBEROS
kerberos-service
Type: Name
Equivalent switch: "-K service-name"
Restricted: not valid in a configuration file in the user's home
directory nor in the spool directory.
Only valid if compiled with --enable-kerberos5 or -DKERBEROS
mail-lock-check
Type: Integer
Equivalent switch: "-L msgs"
Restricted: no
reverse-lookup
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
- 7 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
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.
xtnd-xmit
Type: Boolean
Equivalent switch: "-x"
Restricted: not valid in a configuration file in the user's home
directory nor in the spool directory.
- 8 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
BULLETINS
The bulletin feature gives system administrators a way to send
important announcements to all POP users without having to do mass
mailings.
The bulletin directory contains one file per bulletin. 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 mail program 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 characters. E.g., the file name
of bulletin number 23 might be "23.pophost_down_sunday".
Popper creates a file named .popbull in the home directory of each
user. This file contains a single line recording 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 a bulletin 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 mail the 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 by default, and the bulletin directory
specified, by including the --enable-bulletins=bull-directory flag
when running ./configure.
To use a database instead of .popbull files in users' home directories
for tracking the highest bulletin seen by a 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, include
the --with-new-bulls flag when running ./configure. For example, --
with-new-bulls=10 says that new users get at most ten bulletins.
- 9 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
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 and
password 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 warning
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 transaction state. The server
makes a temporary copy of the user's maildrop which is used for all
subsequent transactions (unless running in server mode ). These
include the bulk of POP commands to 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 activities. 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 priority "debug". The default log file
is /usr/spool/mqueue/POPlog. These can be changed, if desired. On
systems with 4.2 syslogging all messages are logged to the local log
file, usually /usr/spool/mqueue/syslog.
DEBUGGING
Qpopper logs 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. Alternatively, the "-t <file-name>" option places
- 10 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
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 a shell 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:
%telnet pop.qualcomm.com 110
Trying...
Connected to pop.qualcomm.com.
Escape character is '^]'.
+OK QPOP (version 3.0) at pop.qualcomm.com starting.
quit
+OK Pop server at pop.qualcomm.com signing off.
Connection closed by foreign host.
EXTENSIONS
The server implements several extended commands.
XTND XMIT: Sends a mail message using /usr/lib/sendmail.
XTND XLIST header [num]: Extracts and returns the specified header
line for the specified message number. If the "num" parameter is
missing, returns the header line for all the messages which are not
currently marked for deletion.
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 support XMANGLE, add "-
no-mime" to the user name. For example, if the userid is "mary",
enter it in the client as "mary-no-mime".
FILES
/var/mail mail files
/etc/inetd.conf pop program invocation
/etc/syslog.conf logging specifications
/var/spool/bulls bulletins
- 11 - Formatted: October 27, 2025
qpopper(8) Local qpopper(8)
26 April 2010
~/.popbull largest bulletin number seen by user
SEE ALSO
inetd(8), inetd.conf(4), sendmail(8)
AUTHORS
Randall Gelles, Praveen Yaramada, Laurence Lundblade, Mark Erickson,
Bob Campbell, Edward Moy, Austin Shelton, Marshall T Rose, and cast of
thousands at Rand, UDel, UCI, QUALCOMM Incorporated and the Internet
user community.
- 12 - Formatted: October 27, 2025
