---

Web www.fiveanddime.net

Qpopper
Administrator's Guide
Qpopper Version 4.0

---

This manual was written for use with the Qpopper software version 4.0. This manual and the Qpopper software de-
scribed in it are copyrighted, with all rights reserved. This manual and the Qpopper software may not be copied, except
as otherwise provided in the software license or as expressly permitted in writing by QUALCOMM Incorporated.
Copyright © 2001 by QUALCOMM Incorporated. All rights reserved.
Qpopper is a trademark of QUALCOMM Incorporated.
SSL Plus is a trademark and Security Builder® is a registered trademark of Certicom Incorporated.
QUALCOMM is a registered trademark and registered service mark of QUALCOMM Incorporated.
Microsoft, Outlook, Outlook Express, and Windows are either registered trademarks or trademarks of Microsoft In-
corporated in the United States and/or other countries.
Adobe, Acrobat, and Acrobat Exchange are registered trademarks of Adobe Systems Incorporated.
Apple and the Apple logo are registered trademarks, and QuickTime is a trademark of Apple Computer, Inc.
Netscape, Netscape Communicator, and Netscape Messenger are registered trademarks of the Netscape Communica-
tions Corporation in the United States and other countries. Netscape's logos and Netscape product and service names
are also trademarks of Netscape Communications Corporation, which may be registered in other countries.
All other trademarks and service marks are the property of their respective owners.
This product includes software developed by the University of California, Berkeley and its contributors. This product
includes software developed by the Victoria University of Wellington, New Zealand. Use of the Qpopper software
and other software and fonts accompanying your license (the "Software") and its documentation are governed by the
terms set forth in your license. Such use is at your sole risk. The Software and its documentation (including this man-
ual), and QUALCOMM's software maintenance and extended maintenance, if applicable, are provided "AS IS" and
without warranty of any kind and QUALCOMM AND ITS LICENSORS (HEREINAFTER COLLECTIVELY RE-
FERRED TO AS "QUALCOMM") EXPRESSLY DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, IN-
CLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE AND AGAINST INFRINGEMENT. QUALCOMM DOES NOT WARRANT
THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET YOUR REQUIREMENTS, OR THAT
THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS
IN THE SOFTWARE WILL BE CORRECTED. FURTHERMORE, QUALCOMM DOES NOT WARRANT OR
MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFT-
WARE OR ITS DOCUMENTATION IN TERMS OF THEIR CORRECTNESS, ACCURACY, RELIABILITY, OR
OTHERWISE. NO ORAL OR WRITTEN INFORMATION OR ADVICE GIVEN BY QUALCOMM OR A QUAL-
COMM AUTHORIZED REPRESENTATIVE SHALL CREATE A WARRANTY OR IN ANY WAY INCREASE
THE SCOPE OF THIS WARRANTY. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IM-
PLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY.
UNDER NO CIRCUMSTANCES INCLUDING NEGLIGENCE, SHALL QUALCOMM, ITS LICENSORS OR
THEIR DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS BE LIABLE FOR ANY INCIDENTAL, SPECIAL
OR CONSEQUENTIAL DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS, LOSS OF PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION AND THE LIKE) ARISING OUT OF THE
USE OR INABILITY TO USE THE SOFTWARE OR ITS DOCUMENTATION, EVEN IF QUALCOMM OR A
QUALCOMM AUTHORIZED REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY
FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE LIMITATION OR EXCLUSION MAY
NOT APPLY.
In no event shall QUALCOMM's total liability to you for all damages, losses, and causes of action (whether in contract,
tort, including negligence, or otherwise) exceed the amount paid for the Software and its documentation.

---

Acknowledgments
Qpopper is the work of many individuals and organization around the world. The original work was done at UC Ber-
keley around 1991 and many have contributed since. QUALCOMM has maintained, enhanced, and distributed Qpop-
per since 1993. While we don't have an accurate collection of the names of all, their contributions are appreciated.
Qpopper 4.0 was developed by Randall Gellens. This guide was written by Randall Gellens, Gigi Miller, Scott Antho-
ny, and Armand Rouleau. Thanks to all the users Qpopper, whose suggestions have made it a much better program
than it otherwise would have been.
November 2001
PM80-48468-1x1

---

---

Contents
Contents
5
Introducing Qpopper
7
Introduction
7
File Names and Commands in this Manual
7
Foundation
7
Getting Help
8
Technical Support
8
Mailing Lists
8
Other Resources
8
Installing and Setting Up Qpopper
9
What you need to do
9
Installing Qpopper
9
Make Commands
10
Uninstalling Qpopper
10
Configuring Qpopper
10
Configure Options
11
Run-Time Command Line Options
21
Run-Time Options from a Configuration File
27
Enabling Server Mode
40
Enabling Standalone Mode
42
Using Macros
43
Qpopper Notes
46
Operating System-Specific
47
Managing Qpopper
48
Security and Authentication
48
APOP
48
TLS/SSL Encryption
49
Obtaining TLS/SSL and Cryptographic Libraries
49
Creating a Security Certificate
49
Setting TLS/SSL Options
50
PAM
51
Kerberos
52
Using Bulletins
52
Enabling Bulletins
52
Writing Bulletins
53
Working with Bulletins
54
Configuring Bulletins for New Users
54
Performance
56
Performance
56
Troubleshooting
60
Troubleshooting
60
QUALCOMM Incorporated
5

---

Contents
Glossary
62
QUALCOMM Incorporated
6

---

Introducing Qpopper
Introduction
Welcome to Qpopper! Qpopper enables a UNIX/Linux machine to act as a Post Office
Protocol version 3 (POP) server. POP allows email clients, such as Eudora, to pick up the
user's messages. Qpopper is the most widely-used POP server.
Important. To use Qpopper, you should have a comprehensive knowledge of UNIX/Linux
systems and how they operate.
Qpopper is normally used with standard UNIX mail transfer and delivery agents such as
Sendmail or Smail. Qpopper follows UNIX/Linux conventions for mailbox (spool) location,
locking, etc.
This server is fully compliant with RFC 1939 (which defines the POP protocol) and RFC
2449 (which defines the POP extension mechanism and the extended response codes),
and works with all known POP clients, such as Eudora.
Qpopper supports the latest standards and provides a large number of features, such as
bulletins, enhanced support for wireless devices, Authenticated Post Office Protocol
(APOP), integration with Pluggable Authentication Modules (PAM) and packages such as
Kerberos versions 4 or 5, Dynamic Relay Access Control (DRAC), etc. Qpopper also works
with security packages such as OpenSSL or Certicom's SSL Plus to provide Transport
Layer Security/Secure Sockets Layer (TLS/SSL) encryption of all traffic to and from the
email client. Qpopper 4.0 includes enhanced performance features and easier administra-
tion.
You can always get the latest release of Qpopper at <http://www.qpopper.org>.
This manual applies to Qpopper 4.0.
File Names and Commands in this Manual
In this manual, actual file and directory names appear like this. If the file name
includes a variable part (such as a user name), the variable part is in italics, for example, a
temporary spool file is called .user.pop. Commands you type are formatted like this.
Foundation
Qpopper's goals are security, stability, safety, features, and performance.
Qpopper has multiple levels of protection against common security vulnerabilities, such as
buffer overruns.
Qpopper takes extra precautions to guard against spool corruption, even if there is a
system crash or power failure during an update of the software.
QUALCOMM Incorporated
7

---

Qpopper LX User Manual
Getting Help
You can also indicate when some precautions are not required, for example, if your users
do not access mail using shell accounts. This allows Qpopper to run at maximum perfor-
mance levels.
Getting Help
Technical Support
Many of your questions can be answered by looking in this guide, particularly in the Trou-
bleshooting section. In addition, the Qpopper web site at <http://www.qpopper.org>has a
variety of resources, including a Frequently Asked Questions (FAQ) page.
Mailing Lists
An unofficial public mailing list exists for Qpopper administrators, such as yourself. To
subscribe, type the word subscribe as the body of an email message and send it to:
qpopper-request@lists.pensive.org. This mailing list also receives official announcements
from QUALCOMM about Qpopper.
There is also a low volume mailing list that exists solely for official announcements from
QUALCOMM about Qpopper. To subscribe to it, type the word subscribe as the body of
an email message and send to: qpopper-announce-request@rohan.qualcomm.com
Other Resources
There is a man page for Qpopper. To display it, type man qpopper on the command line.
However, all the information in the man page, and much more, is contained in this docu-
ment.
To make suggestions to improve Qpopper, write to qpopper-suggest@qualcomm.com
To report bugs in Qpopper, write to qpopper-bugs@qualcomm.com
QUALCOMM Incorporated
8

---

What you need to do
Qpopper LX User Manual
Installing and Setting Up Qpopper
What you need to do
Before you can install Qpopper on your UNIX/Linux operating system, you must install and
configure an SMTP server and local delivery agent, such as Sendmail or Smail.
Installing Qpopper
Important. In the mail spool directory, some systems have symbolic links from
/usr/mail to /usr/spool/mail. Make sure you check this before installing Qpopper.
To install Qpopper, do the following:
1
Download the Qpopper software from <http://www.qpopper.org>. This is a single file
(called a distribution) which contains the source code, scripts, and documentation in a
compressed format (also known as a compressed archive or tarball). The name of the
file is qpopper, followed by the release, an optional -no-test, and ends in
.tar.gz. The .tar means this is a single file that contains multiple files and directo-
ries, while the .gz means this single file also is compressed to save space. If you
choose the name with -no-test, it is a smaller version that omits the test directories
and scripts.
The distribution for Qpopper 4.0 is called qpopper4.0.tar.gz. or
qpopper4.0-no-test.tar.gz
2
Uncompress the files by typing gunzip qpopper4.0.tar.gz
3
Unpack the files by typing tar xvf qpopper4.0.tar. The unpacked files will then be
placed in a new directory called qpopper4.0.
4
Change to the qpopper4.0 directory by typing cd qpopper4.0.
5
On the command line, type ./configure.
Add any other configure flags as needed or desired.
6
On the command line, type make. Running make builds Qpopper for your operating
system.
7
Copy the resulting Qpopper executable to a public location. The executable is called
popper and can be found in the popper subdirectory. Normally, typing make install
does this for you.
Although there is no required location, many system administrators prefer
/usr/local/lib, and this is used in example lines (such as /etc/inetd.conf
lines).
If you modify Qpopper, be sure to edit the file popper/banner.h and add a string.
QUALCOMM Incorporated
9

---

Qpopper LX User Manual
Make Commands
Make Commands
s
make
Compiles Qpopper. If using APOP (see "APOP" on page 49), also compiles popauth.
If --enable-poppassd used with ./configure, also compiles poppassd in the pass-
word directory.
Note that you must run ./configure before make.
s
make install
Copies the Qpopper executable and man pages to a standard location. If using APOP,
also copies popauth. If --enable-poppassd specified with ./configure, also copies
poppassd.
You need to be user root to do this.
s
make clean
Deletes all executables and compiled object code.
s
make realclean
Deletes all executables and compiled object code, plus configuration information and
temporary files. Use this before ./configure when you want to be certain that you are
starting off fresh.
Uninstalling Qpopper
To uninstall Qpopper, remove the inetd.conf line, and delete the Qpopper executable
and directories.
Configuring Qpopper
You can run Qpopper in either Internet daemon (inetd) mode or standalone mode. In inetd
mode, Qpopper is controlled by inetd. Standalone mode requires that you leave the server
running all the time.
If using standalone mode, configure your system to launch Qpopper at start-up. See
section "Enabling Standalone Mode" on page 43 for more information.
If you are not going to use standalone mode, modify your /etc/inetd.conf file to
contain the line below. You may have to modify it to include any desired command-line
flags and where you decided to place the Qpopper executable, if not /usr/local/lib:
pop3 stream tcp nowait root /usr/local/lib/popper qpopper -s
Note. If you have a great number of users connecting the server, you may need to
increase the inetd timeout value to prevent it from assuming that popper is looping,
which otherwise causes it to kill Qpopper and write a log entry noting service looping. You
can increase the global inetd timeout by passing inetd a command line argument. On
some systems, you can alter the timeout for Qpopper by changing nowait to
nowait.timeout, for example, nowait.400.
If your OS does not have an inetd.conf file, then it may use the configuration file
/etc/servers. Enter the following option:
QUALCOMM Incorporated
10

---

Configuring Qpopper
Qpopper LX User Manual
pop3 tcp /usr/local/lib/popper qpopper -s
On all systems, your /etc/services file needs to include the following line:
pop3
110/tcp
# Post Office
Note. Be sure to remove (or comment out) any lines from /etc/services which have
the same port (110) and remove (or comment out) any corresponding lines from
/etc/inetd.conf or you may have problems, such as address already in use errors.
Restart inetd with a kill -HUP inetdpid (some systems can use inetd -c).
On Linux, you can use ps x | grep inetd to find the PID of inetd. On many flavors of UNIX,
you can use ps -e | grep inetd. On AIX, use refresh -s inetd Note that you need to be
user root to do this.
If you are running NIS, please don't forget to update your maps.
Note that you also need to copy the man pages. Generally, this requires that you copy
man/*.8 to /usr/man/man8. Normally, typing make install does this automatically.
Configure Options
The following options (flags) can be passed to ./configure to enable compile-time
changes:
An italicized variable after an = sign indicates that a specific value may be entered here. In
most cases, if you do not enter a specific value, a default value is used. For example, if
you see ---enable-apop=path, path indicates that you may specify the path, such as:
--enable-apop= /etc/pop.auth
Many compile-time options can be overridden at run-time by setting a configuration file
option, or in some cases, a command-line flag.
Configuration File
Type this option...
This happens...
Option
--disable-status
When disabled, Qpopper does not
update-status-
--enable-status
update the read/unread status of
headers
(default)
messages (a feature relied on by
some mail clients) and also does
not save the message's unique
identifier (UID). This forces the UID
for every message to be
recalculated, using more CPU but
potentially less I/O.
See "Performance" on page 57 for
more information.
--disable-old-spool-
When disabled, Qpopper doesn't
check-old-spool-loc
loc
check for old .user.pop files in
--enable-old-spool-
old locations when HASH_SPOOL or
loc (default)
HOMEDIRMAIL is used. This speeds
things up.
QUALCOMM Incorporated
11

---

Qpopper LX User Manual
Configuring Qpopper
Configuration File
Type this option...
This happens...
Option
--enable-any-
Enabling permits use of any
kerberos-principal
Kerberos principle in client
--disable-any-
authentication.
kerberos-principal
(default)
--enable-apop=path
Enable this option to use APOP.
--disable-apop
This value is the location of the
(default)
authorization database. Users
found in this database may not use
user/pass authentication (since
they are found in the APOP
database) unless you use the -p
command-line flag or the
clear-text-password configuration
file option to authorize it.
The default path is
/etc/pop.auth.
See "APOP" on page 49 for
instructions and configure options.
--enable-auth-file=
Enable this option to specify a file
auth-file
path
that permits only users listed in the
--disable-auth-file
file to have Qpopper access. The
(default)
format is a list of user names, one
per line.
--enable-auto-delete
When enabled, Qpopper
auto-delete
--disable-auto-delete
automatically and unconditionally
(default)
deletes messages that have been
downloaded using the RETR
command (the normal command
for accessing messages).
Caution. This
option could result
in lost mail. Be
sure to inform
your users that
the option is in
effect before
enabling it.
QUALCOMM Incorporated
12

---

Configuring Qpopper
Qpopper LX User Manual
Configuration File
Type this option...
This happens...
Option
--enable-bulldb=path
When enabled, Qpopper uses a
--disable-bulldb
central database located in the
(default)
bulletin directory (instead of a file
in the user's home directory) to
keep track of which bulletins the
user has seen. This feature uses
the user's .popbull file the first
time for backwards compatibility.
Specify the path if an alternate
location for the bulletin database is
desired. See "Using Bulletins" on
page 53 for details. Also see
"Performance" on page 57 for
more information.
Enabling this option also enables
bulletins in general.
--enable-bulletins=
Enable bulletins and sets the path
bulldir
path
for the bulletin directory (default is
--disable-bulletins
/var/spool/bulls). See "Using
(default)
Bulletins" on page 53 for details.
This is the compiled value as
opposed to the command line or
configuration file option that
enables bulletins. This makes
bulletins the default regardless of
the command line or configuration
file options.
--enable-debugging
Enables verbose logging when
--disable-debugging
used with the -d or -t command
(default)
line flag or the debug or tracefile
configuration file option. Enable
this if you are having problems
figuring out why Qpopper is not
working. Remember that it can
generate a lot of output, and log
files on busy systems expand
quickly.
--enable-cache-dir=
Specifies the location of the user's
cache-dir
path
cache files, which are used to
--disable-cache-dir
speed up Qpopper performance in
(default)
server mode. The default is the
same directory as for temporary
spool files (see
--enable-temp-drop-dir).
QUALCOMM Incorporated
13

---

Qpopper LX User Manual
Configuring Qpopper
Configuration File
Type this option...
This happens...
Option
--disable-check-hash
When disabled, Qpopper doesn't
check-hash-dir
-dir
check for or create the hashed
--enable-check-hash-
spool directories. Disable if you
dir (default)
precreate the directories.
Has no effect either way unless
you also use --enable-hash-spool.
--disable-check-pw-
Disabling prevents Qpopper from
check-password-
max
checking for expired passwords.
expired
--enable-check-pw-
max (default)
--enable-group-bulls
Shows bulletins by groups (group
group-bulletins
--disable-group-bulls
name is second element in bulletin
(default)
name). See "Using Bulletins" on
page 53.
--enable-hash-spool
When enabled, the subdirectory
hash-spool
=1
for the mail spools is determined
--enable-hash-spool
from the user name by either
=2
hashing the first four characters or
by using directories equal to the
--disable-hash-spool
first letter and the second letter (if
(default)
any). For example, if the spool
directory is /var/mail, the spool
file for user maida would be:
/var/mail/maida
HASH_SPOOL not set
/var/mail/o/maida
HASH_SPOOL=1
/var/mail/m/a/maida
HASH_SPOOL=2
See "Performance" on page 57 for
more information.
--enable-home-dir-
If mail is spooled into the user's
home-dir-mail
mail=file
home directory, set this to be the
correct file name for your system.
--disable-home-dir-
The default file name is .mail.
mail (default)
--enable-home-dir-
Causes the .user.pop and the
home-dir-misc
misc
.user.cache files to be placed in
the user's home directory.
--disable-home-dir-
misc (default)
QUALCOMM Incorporated
14

---

Configuring Qpopper
Qpopper LX User Manual
Configuration File
Type this option...
This happens...
Option
--enable-keep-temp-
Keep the .user.pop file (the
keep-temp-drop
drop
temporary drop file). Normally this
--disable-keep
file is deleted when the session
(default)
ends. Some sites like to retain it to
determine the last time a user has
accessed his or her mail.
--enable-ksockinst
Uses getsockinst() for
--disable-ksockinst
Kerberos instance.
(default)
--enable-kuserok
Uses kuserok() to vet Kerberos
--disable-kuserok
users.
(default)
--enable-log-facility=
Specifies the log facility. Default is
log-facility
name
LOG_LOCAL0 or LOG_MAIL,
--disable-log-facility
depending on the operating
system. Note that the value you
pick must exist in the system's
log.h file, and be typed exactly
as it appears there.
--enable-log-login
When defined, Qpopper logs
log-login
--disable-log-login
successful authentications.
(default)
--enable-low-debug
Sets the _DEBUG macro (not the
--disable-low-debug
same as simply DEBUG) for
(default)
low-level debugging. Also turns off
compiler optimizations. Don't do
this unless you know what you're
doing.
--enable-new-bulls=
New users receive only the single
max-bulletins
number
newest bulletin by default. This
--disable-new-bulls
value sets the number of bulletins
(default)
for new Qpopper users. For
example, pass
--enable-new-bulls=10 to give new
users a maximum of ten bulletins.
See section "Using Bulletins" on
page 53 for details.
--enable-nonauth-file
Define this value to specify a file
nonauth-file
=path
that excludes listed users. The
--disable-nonauth-
format is a list of user IDs, one per
file (default)
line. Users appearing in the file are
unable to use Qpopper.
QUALCOMM Incorporated
15

---

Qpopper LX User Manual
Configuring Qpopper
Configuration File
Type this option...
This happens...
Option
--enable-old-uidl
Generates message unique
old-style-uid
--disable-old-uidl
identifiers (UIDs) using old (pre-3.x)
(default)
style encoding. This is useful only
if you also use --disable-status,
have existing users with old
(pre-3.x) spool files, and you want
to keep the UIDs the same.
--disable-
Turns off all compiler
optimizations
optimizations. This is generally
--enable-
only useful when running under a
optimizations
debugger.
(default)
--enable-popbulldir=
Specifies an alternate location for
path
users' .popbull files. See section
--disable-popbulldir
"Using Bulletins" on page 53 for
(default)
details.
--enable-poppassd
Running make creates the
--disable-poppassd
poppassd executable as well as
(default)
popper. This is a password-
changing daemon
--enable-popuid=pop
This value is the username of the
--disable-popuid
owner of the APOP database. See
(default)
"APOP" on page 49 for details.
--enable-scram=path
Includes scram capability in the
--disable-scram
APOP database file (default path is
(default)
/etc/pop.auth). This is not
recommended.
--enable-secure-nis-
Add this definition if you are
plus
running Secure Network
--disable-secure-nis-
Information Systems (NIS+).
plus (default)
--enable-server-
Enables server mode by default.
server-mode
mode
See section "Enabling Server
--disable-server-
Mode" on page 41 for details. Also
mode (default)
see "Performance" on page 57 for
more information.
QUALCOMM Incorporated
16

---

Configuring Qpopper
Qpopper LX User Manual
Configuration File
Type this option...
This happens...
Option
--enable-server-
Sets server mode to off for users
group-no-server-mode
mode-
who are members of the specified
group-exclude=
group. See section "Enabling
group
Server Mode" on page 41 for
--disable-server-
details. Also "Performance" on
mode-
page 57 for more information.
group-exclude
(default)
--enable-server-
Sets server mode to on for users
group-server-mode
mode-
who are members of the specified
group-include=
group. It may also be helpful to
group
disable shell access to these
--disable-server-
users, thus ensuring that only
mode-
Qpopper and the local delivery
group-include
agent access the user's spool file.
(default)
See section "Enabling Server
Mode" on page 41 for details. Also
see "Performance" on page 57 for
more information.
--enable-shy
Enable if you don't want Qpopper
shy
--disable-shy
to display its version in the POP
(default)
protocol banner or CAPA
IMPLEMENTATION response of
unauthenticated users.
Some sites believe this improves
security since it avoids advertising
that an old version (perhaps with
known vulnerabilities) is being
used. Others feel is makes the site
more likely to be attacked, since it
also avoids advertising when
running a secure version.
--enable-specialauth
This needs to be enabled if your
--disable-specialauth
system supports special
authorization mechanisms like
shadow passwords or special
crypt programs. However, this is
usually set correctly by
./configure. Disable this if you
keep passwords in /etc/passwd.
QUALCOMM Incorporated
17

---

Qpopper LX User Manual
Configuring Qpopper
Configuration File
Type this option...
This happens...
Option
--enable-spool-dir=
Allows you to specify the directory
spool-dir
directory
for mail spool files, such as
/var/mail or
/var/spool/mail. If not
specified, ./configure
searches for it.
--enable-standalone
Creates a standalone daemon
--disable-standalone
instead of one to be run out of
(default)
inetd.
You can specify an IP address
and/or port number to bind to as
parameter 1, for example, popper
199.46.50.7:8110 -S or popper
8110 -S -T600. If not specified, the
IP address defaults to all that are
available. The default port is 110,
except when _DEBUG (not simply
DEBUG) is defined, when it is 8765.
See "Enabling Standalone Mode"
on page 43 for more information.
Also see "Performance" on page
57 for more information.
--enable-temp-drop-
Specifies an alternate directory for
temp-dir
dir=path
temporary mail drop files. The
--disable-temp-drop-
default is the spool directory. See
dir
"Performance" on page 57 for
more information.
--enable-timing
Writes timing information to log at
timing
--disable-timing
session end. Includes whole
(default)
seconds (elapsed) for
authentication, initialization, and
cleanup.
--enable-uw-kludge
Checks for and hides status
uw-kluge
--disable-uw-kludge
messages created by Universify of
(default)
Washington software.
QUALCOMM Incorporated
18

---

Configuring Qpopper
Qpopper LX User Manual
Configuration File
Type this option...
This happens...
Option
--with-drac=lib-path
Enables use of DRAC. Specify path
--without-drac
to DRAC libraries or leave blank if
(default)
installed in usual place. DRAC is a
method of authorizing SMTP
sessions for IP addresses which
have recently authenticated using
POP. This can be useful for clients
which do not support SMTP AUTH,
but the long term solution is SMTP
AUTH.
--disable-update-
By default, Qpopper enters update
update-on-abort
abort
state on a session abort. Disabling
--enable-update-
this option causes Qpopper to
abort (default)
ignore any deletions if the session
is aborted.
Note that RFC 1939, section 6
prohibits the Qpopper default
behavior, but experience showed
that otherwise users on noisy lines
were often unable to delete their
mail. Disable this option to inhibit
the default behavior, and obey RFC
1939.
QUALCOMM Incorporated
19

---

Qpopper LX User Manual
Configuring Qpopper
Configuration File
Type this option...
This happens...
Option
--with-kerberos5=
Enable to use Kerberos version 5
directory
libraries. Or, use this and also
--without-kerberos5=
define KRB4 if you want to use
directory (default)
Kerberos version 4 libraries. For
Kerberos 4, you must also update
the makefile so you can load the
appropriate libraries (-lkrb). This
option works only if you have
Kerberos headers and libraries
installed.
If you want to use the kuserok()
function to vet users, pass
--enable-kuserok to
./configure.
If you want to accept any Kerberos
principal in the client request, pass
--enable-any-kerberos-principal.
If your system has the
getsockinst() function, pass
--enable-ksockinst. It retrieves the
IP address of the local end of a
connection and looks up the host
name. Kerberos then uses that
host name. This allows Kerberos
to use different instances for
different virtual addresses on the
same machine.
You can also define
KERBEROS_SERVICE to specify
which Kerberos service to use.
The default is rcmd. However, the
use of pop is common. The -K
service command-line or
kerberos-service configuration file
option can be used instead of the
KERBEROS_SERVICE define.
You can remove
KRB5_KRB4_COMPAT from
config.h if you are using the
Kerberos 5 libraries and want to
disable backwards compatibility
with a Kerberos 4 server.
Define NO_CROSSREALM if desired.
You can obtain a Kerberos engine
for your system from the MIT
Kerberos Distribution Page. Go to
the following site:
<http://web.mit.edu/kerberos/www
/index.html>
QUALCOMM Incorporated
20

---

Configuring Qpopper
Qpopper LX User Manual
Configuration File
Type this option...
This happens...
Option
--with-openssl=path
Uses the OpenSSL library for
--without-openssl
SSL/TLS support. You can obtain
(default)
the OpenSSL library and utilities
from <http://www.openssl.org>
--with-sslplus=path
Uses the SSL Plus library from
--without-sslplus
Certicom for SSL/TLS support.
(default)
--with-gdbm
Normally, ./configure uses
--without-gdbm
gdbm if installed on the system.
You can override this by using this
option.
--with-sslplus-crypto
Uses Security Builder® from
=path
Certicom for TLS/SSL cryptography.
--without-sslplus-
crypto (default)
--with-pam=
Define if you want to use PAM for
servicename
authentication. The default service
--without-pam
name is pop3.
(default)
--enable-warnings
Enables additional compiler
--disable-warnings
warnings. Use this if you don't trust
(default)
the Qpopper authors :-).
Run-Time Command Line Options
You can set Qpopper run-time options either from the command line or a configuration file.
Some systems have limitations on the length or number of command line options in
inetd.conf. (For example, the Solaris INETD.CONF man page states that no more than
five options are permitted.) You can use configuration files for run-time options to get
around this limit or to set options on a per-user basis. Also, some run-time options can
only be set from a configuration file. Use the -f, -u, and -U command-line options to cause
Qpopper to use a configuration file. See the following section "Run-Time Options from a
Configuration File" on page 27 for details.
In the following table are the run-time options and their descriptions for Qpopper:
Values in italics indicate a variable, for example, in -D drac-host, drac-host is the variable.
QUALCOMM Incorporated
21

---

Qpopper LX User Manual
Configuring Qpopper
Enter the name or IP address of the DRAC host after -D. The option might be:
-D foo.example.org
Equivalent
Type this option...
Description
Configuration File
Option
-b bulldir
Specific location of the bulletin
bulldir
directory. Overrides the compiled
value, if any.
See "Using Bulletins" on page 53 for
more information.
-B
If compiled with --enable-bulldb (see
bulldb-nonfatal
--enable-bulldb) in the "Configure
Options" on page 11, this option
allows sessions to proceed even if the
bulletin database can't be opened.
This allows users to get their mail, but
may mean some users won't see
bulletins for some time or even at all.
-c
Changes uppercase user names to
downcase-user
lowercase. This permits users to
configure their clients with user
names in UPPER or MiXeD case.
They can still login assuming their
actual user name is all lowercase.
-C
When set, domains are trimmed from
trim-domain
user names before use. For example,
if a user named maida enters her
login name in her POP client as
maida@example.org, Qpopper treats
this as just maida.
-d
Enables debug logging if
debug
--enable-debugging used
with./configure). Output is in
syslog. If this option is used, it should
be first, so that debug records are
generated for subsequent options.
-D drac-host
If./configure used with
drac-host
--with-drac, this option specifies the
DRAC host. Defaults to localhost.
QUALCOMM Incorporated
22

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Configuration File
Option
-e login_delay=delay,
Sets POP3 extensions. This option
announce-expire
expire=expire
announces the login-delay and expire
announce-login-delay
response tags to the CAPA command.
By default the expire field is expire
never, and the login delay is 0.
Except for expire 0 or expire never,
these are not enforced by Qpopper.
Sysadmins have to implement them
by some other means.
-f config-file
Reads additional run-time options
config-file
from the specified file. See the
following section "Run-Time Options
from a Configuration File" on page 27
for option names and syntax.
Caution. There are
no restrictions on
which options may
appear in files speci-
fied with the -f
command-line flag or
the config-file config-
uration file option in
files chained from -f,
so be certain that the
specified file is not
writable by users.
-F
When updating the spool at the end of
fast-update
a session, this option instructs
Qpopper to rename the temporary file
to the spool instead of copying it. This
reduces I/O at session end by a third,
but is likely to break programs such
as biff or the shell's mail check
feature. Use this option only if
such programs are not used. It is
safest to only enable this option when
users do not have shell access to the
mail server.
See "Performance" on page 57 for
more information.
-k
If --enable-kerberos5 used with
kerberos
./configure, this option enables
Kerberos support.
QUALCOMM Incorporated
23

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Configuration File
Option
-K service name
If --enable-kerberos5 used with
kerberos-service
./configure, this option specifies
the Kerberos service to use (same as
the compile time kerberos_service
define). The default is rcmd, although
the use of pop is popular.
-l 0
Specifies TLS/SSL support.
tls-support
-l 1
·0
The default. TLS/SSL is not
-l 2
supported.
Only available
·1
Enables support for the STLS
when./configure
command. This permits TLS/SSL
was run with
negotiations on the standard (or any)
--with-openssl or
port, allowing the same port to be
--with-sslplus.
used by TLS/SSL and regular clients.
·2
Enables alternate-port TLS/SSL.
Some older clients require this. (The
usual port for alternate-port TLS/SSL
with pop is 995.)
-L lock-refresh
Checks if the mail lock needs to be
mail-lock-check
refreshed every this many messages.
You normally do not need to adjust
this. See "Performance" on page 57
for more information.
QUALCOMM Incorporated
24

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Configuration File
Option
-p 0
Sets clear text handling options when
clear-text-password
-p 1
APOP is available.
-p 2
·0
The default. Clear text passwords
are permitted for all users except
-p 3
those in the APOP database (who must
-p 4
use APOP).
·1
Clear text passwords are never
permitted for any user (users not in
the APOP database cannot login).
·2
Clear text passwords are always
permitted (even if an APOP entry
exists), which allows them to be used
as a fallback.
·3
They are permitted on the local
interface (127.*.*.*) only.
·4
Permits clear text passwords only
if TLS/SSL has been negotiated for the
session.
See "Security and Authentication" on
page 49 for more information.
-R
Disables the reverse lookups on client
reverse-lookup
IP addresses.
-s
Enables statistics logging. After each
statistics
session ends, a statistics record is
written to the log. This record
resembles the following example:
randy 0 0 1 385
randy.examp.org 192.168.2.4
in which
Username:
randy
Deleted messages:
0
Deleted octets:
0
Messages left on server:
1
Octets left on server:
385
Name of client machine:
randy.examp.org
IP address of client machine:
192.168.2.4
-S
Enables server mode by default. See
server-mode
"Enabling Server Mode" on page 41
for details.
QUALCOMM Incorporated
25

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Configuration File
Option
-t logfile
Enables debug logging if
tracefile
--enable-debugging used with
./configure. Output is written to
the file specified as logfile. If this
option is used, it should be first, so
that debug records are generated for
subsequent options.
You can also use this when you didn't
pass --enable-debugging to
./configure, which causes log
messages to be written to logfile
instead of syslog.
-T timeout
You can change the timeout for client
timeout
reads. The default is 120 seconds.
Qpopper terminates the connection
with the client if no input is received in
this many seconds. RFC 1939 states
that this timeout should be 600
seconds (10 minutes). However, ideal
settings in some cases are between
30 and 120 seconds.
-u
Reads additional run-time options
user-options
from a file named.qpopper-
options in the user's home directory,
if present. See the following section
"Run-Time Options from a
Configuration File" on page 27 for
option names and syntax.
-U
Same as above, but the file is called
spool-options
user.qpopper-options and is in
the spool directory. This file should
not be owned by nor writable by
the user. Use this to set options on a
user-specific basis that you don't want
the user to change.
-y
Specifies the log facility that Qpopper
log-facility
uses.
Note that this does not apply to
popauth, nor to the daemon in
standalone mode. Both of these
continue to use the compile-time
default.
QUALCOMM Incorporated
26

---

Configuring Qpopper
Qpopper LX User Manual
Run-Time Options from a Configuration File
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 Backus-Naur form (BNF)) is:
config-line
::= comment-line / reset-line / set-line
comment-line
::= "#" <comment-text to end of line>
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 / string / mnemonic
string
::= "1*255CHAR"
CHAR
::= any printable character except space or tab
In other words, a line starts with set or reset, then an option name, and either ends there
(for Boolean options) or has an equal sign (=) followed by a value. You can put spaces or
tabs around each element.
A comment line starts with a pound sign (#). The rest of the line is ignored. (Everything
else on the line is a comment.)
Note that reset can be used only 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 have restrictions indicating 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.
In the following table are the command line options you can use:
Note that an italicized variable after a = sign indicates that the correct value can be
entered here.
QUALCOMM Incorporated
27

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
announce-expire
This integer option announces the
-eexpire=xx
EXPIRE response tags to the CAPA
command.
This option is permitted in all
configuration files. However, except
for expire 0 or expire never, it is not
enforced by Qpopper. Sysadmins
have to implement them by some
other means.
By default, the expire field is expire
never.
announce-login-delay
This integer option announces the
-elogin_delay=xx
LOGIN-DELAY response tag to the CAPA
command.
A minimum login delay is not currently
enforced by Qpopper.
This option is permitted in all
configuration files.
Default: none
auto-delete
This Boolean option, when set,
none
causes Qpopper to automatically and
unconditionally deletes messages
that have been downloaded using the
RETR command (the normal command
for accessing messages).
Caution. This option
could result in lost
mail. Be sure to
inform your users that
the option is in effect
before enabling it.
QUALCOMM Incorporated
28

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
bulldb-max-retires
Sets the maximum number of
none
Only valid if
attempts to lock the bulletins
database. You normally do not need
./configure run with
--enable-bulldb
to adjust this.
The value should only be changed if
you know if your system has
usleep(3C) or not. On systems with
usleep(3C), this can be a large
value (the default is 75). On systems
without usleep(3C), this should
remain small (the default is 10).
This integer option is permitted in all
configuration files.
Default: > 5 or 10
bulldb-nonfatal
If ./configure was run with
-B
Only valid if compiled with
--enable-bulldb (see --enable-bulldb
--enable-bulldb
in the "Configure Options" on page
11), this option allows sessions to
proceed even if the bulletin database
can't be opened. This allows users to
get their mail, but may mean some
users won't see bulletins for a time or
even at all.
This Boolean option is permitted in all
configuration files.
Default: false
bulldir
Specific location of the bulletin
-b bulldir
directory. Overrides the compiled
value, if any.
See "Using Bulletins" on page 53 for
more information.
This is a string option and is permitted
in all configuration files.
cache-dir
Set this to the full path to the directory
none
for cache files if you do not want user
cache files to be in the same directory
as temporary drop files.
Note the use of /tmp is not
recommended because a system
reboot deletes these files.
Default: Temp drop directory
QUALCOMM Incorporated
29

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
cache-name
The name of the cache file. You
none
should not normally set this option.
Default: .%s.cache
chunky-writes
By default, Qpopper aggregates data
none
to be sent to clients into large chunks.
This may be faster or slower,
depending on the specifics of both the
client and server hardware and
networking stacks as well as network
elements in between (such as
routers). Also, some networking
stacks do their own aggregation.
Under congested network conditions,
larger packets increase the effects of
lost packets and thus client or server
timeouts, which may cause POP
timeout or EOF errors.
When TLS/SSL is in effect, smaller
packets increase the overhead
needed to send data, which may
result in worse performance.
You can adjust the Qpopper behavior
by setting this option. The values are:
· default Always send large chunks
· always Same as default
· never Never aggregate data into
large chunks
· tls Only aggregate data into large
chunks when TLS/SSL has been
negotiated for the session
·ss Same as tls
Default: default
QUALCOMM Incorporated
30

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
clear-text-password
Sets clear text handling options.
The permitted values are:
· default
Clear text passwords are
-p 0
permitted for all users, except those in
the APOP database (who are thus
required to use APOP).
· never
Clear text passwords are
-p 1
never permitted. Users not in the
APOP database cannot use Qpopper.
· always
Clear text passwords are
-p 2
always permitted, even for users in
the APOP database. This allows them
to be used as a fallback when an
APOP client is temporarily not
available.
-p 3
· local
Clear text passwords are
permitted on the local interface only
(127.*.*.*).
· tls
Clear text passwords are
permitted when
-p 4
TLS/SSL has been
negotiated for the session.
· ssl
(same as tls).
The tls and ssl values are only valid if
--with-openssl or --with-sslplus was
used with ./configure.
This mnemonic option is not permitted
in a configuration file in the user's
home directory nor in the spool
directory.
Default: default
QUALCOMM Incorporated
31

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
config-file
Reads additional run-time options
-f config-file
from the specified file. This string
option is permitted in all configuration
files.
Caution. There are
no restrictions on
which options may
appear in files speci-
fied with the -f
command-line flag or
the config-file config-
uration file option in
files chained from -f.
Be certain that the file
specified with -f or in
any files it chains to
are not writable by
users.
debug
Enables debug logging. Output is in
-d debug
Only valid if
syslog. If this option is used, it should
be first, so that debug records are
./configure was run
with --enable-debugging
generated for subsequent options.
This Boolean option is permitted in all
configuration files.
Default: false
downcase-user
Changes uppercase user names to
-c
lowercase. This permits users to
configure their clients with user
names in UPPER or MiXeD case.
They can then login, assuming their
actual user name is all lowercase.
This Boolean option is not permitted
in configuration files specific to a user
(those in a user's home directory or in
the spool directory).
Default: false
drac-host
This option specifies the drac host.
-D drac-host
Only valid if compiled with
This string option is permitted in all
--with-drac
configuration files.
Defaults to localhost.
QUALCOMM Incorporated
32

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
fast-update
When updating the spool at the end of
-F
.
a session, this option instructs
Qpopper to rename the temporary file
to the spool instead of copying it. This
reduces I/O at session end by a third,
but is likely to break programs such
as biff or the shell's mail check
feature. Use this option only if such
programs are not used. It is safest
to only enable this option when users
do not have shell access to the mail
server.
Default: false
See "Performance" on page 57 for
more information.
This Boolean option is permitted in all
configuration files.
home-dir-mail
If mail is spooled into the user's home
none
directory, set this to be the correct file
name for your system. The default file
name is .mail.
This string option is not permitted in
configuration files specific to a user
(those in a user's home directory or in
the spool directory).
home-dir-misc
Causes the .user.pop and the
none
.user.cache files to be placed in
the user's home directory.
This Boolean option is not permitted
in configuration files specific to a user
(those in a user's home directory or in
the spool directory).
kerberos
This option enables Kerberos support.
-k
Only valid if
This Boolean option is not permitted
./configure run with
in configuration files specific to a user
--enable-kerberos5
(those in a user's home directory or in
the spool directory).
QUALCOMM Incorporated
33

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
kerberos-service
This option specifies the Kerberos
-K service-name
Only valid if
service to use (same as the compile
/configure
run with
time KERBEROS_SERVICE define). The
--enable-kerberos5
default is rcmd, although the use of
pop is popular.
This Boolean option is not permitted
in configuration files specific to a user
(those in a user's home directory or in
the spool directory).
log-facility
Specifies the log facility that Qpopper
y
uses.
Note that this does not apply to
popauth, nor to the daemon in
standalone mode. These continue to
use the compile-time default.
Values are:
· mail Qpopper logs to LOG_MAIL
facility.
· local0 Qpopper logs to
LOG_LOCAL0 facility.
· local1 Qpopper logs to
LOG_LOCAL1 facility.
· local2 Qpopper logs to
LOG_LOCAL2 facility.
· local3 Qpopper logs to
LOG_LOCAL3 facility.
· local4 Qpopper logs to
LOG_LOCAL4 facility.
· local5 Qpopper logs to
LOG_LOCAL5 facility.
· local6 Qpopper logs to
LOG_LOCAL6 facility.
· local7 Qpopper logs to
LOG_LOCAL7 facility.
Default: determined at compile time,
usually local1 or mail, depending on
the operating system.
QUALCOMM Incorporated
34

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
log-login
When set, Qpopper logs successful
none
authentications using the specified
string. Within the string, an
occurrence of %0 is replaced with the
Qpopper version, %1 with the user
name, %2 with the user's host name,
and %3 with the user's IP address.
Default: none, unless
--enable-log-login used with
./configure, in which case (v%0)
POP login by user \%1\ at (%2) %3 is
used.
mail-command
Set this to the full path to sendmail or
none
other such program used to submit
new messages. Qpopper uses this to
implement XTND XMIT.
The default is determined at compile
time. An example is
/usr/sbin/sendmail
mail-lock-check
Checks if the mail lock needs to be
-L msgs
refreshed every this many messages.
You normally do not need to adjust
this. See "Performance" on page 57
for more information.
This integer option is permitted in all
configuration files.
Default: 5000
max-bulletins
Specifies the maximum number of old
none
bulletins seen by new users.
Default: 1
no-atomic-open
When set, Qpopper uses a method of
none
opening lock files that may work over
NFS. This has not been thoroughly
tested.
Default: false
QUALCOMM Incorporated
35

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
reverse-lookup
Disables the reverse lookups on client
-R (Sense
Sense reversed from
IP addresses.
reversed)
command-line switch.
This Boolean option is not permitted
Using -R is the
in configuration files specific to a user
same as set
(those in a user's home directory or in
reverse-lookup =
the spool directory).
false.
Default: true
server-mode
Enables server mode by default. See
-S
section server mode for details.
This Boolean option is permitted in all
configuration files.
The default is determined at compile
time.
spool-dir
Set this to the full path to the mail
none
spool directory. The default is
determined at compile time. An
example is /var/spool/mail
spool-options
Reads additional run-time options
-U
from a file named
username.qpopper-options in
the spool directory.
This is a Boolean option and is not
permitted in configuration file in the
user's home directory.
QUALCOMM Incorporated
36

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
statistics
Enables statistics logging. After each
-s
session ends, a statistics record is
written to the log. This record
resembles the following example:
stats randy 0 0 1 385
randy.example.org
192.168.2.4
in which
Username:
randy
Deleted messages:
0
Deleted octets:
0
Messages left on server:
1
Octets left on server:
385
Name of client machine:
randy.example.org
IP address of client machine:
192.168.2.4
This is a Boolean option that is
permitted in all configuration files.
Default: false
temp-dir
Set this to the full path to the directory
none
to be used for temp drop files if you do
not want.user.pop (temporary drop
files) to be located in the spool
directory.
Note that use of /tmp is not
recommended because a system
reboot deletes these files. This could
cause lost mail.
Default: spool directory
temp-name
The name of the temporary drop files.
none
You should not normally set the
option.
Default: .%s.pop
QUALCOMM Incorporated
37

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
timeout
You can change the timeout for client
-T timeout
reads. Qpopper terminates the
connection with the client if no input is
received in this many seconds. RFC
1939 states that this timeout should
be 600 seconds (10 minutes).
However, ideal settings in some
cases are between 30 and 120
seconds.
This integer option is permitted in all
configuration files.
The default is 120 seconds.
tls-cipher-list
Specifies the permitted cipher suites.
none
See the OpenSSL documentation for
Only valid when
syntax. You normally do not need to
--with-openssl used with
set this.
./configure
This string option is not permitted in a
configuration file in the user's home
directory nor in the spool directory.
tls-identity-file
Specifies a file which contains the
none
server's TLS/SSL certificate and
Only valid if
encrypted private key.
./configure used with
--with-sslplus
This string option is not permitted in a
configuration file in the user's home
directory nor in the spool directory.
tls-passphrase
Specifies the passphrase to decrypt
none
the server's private key (in the identify
Only valid if
file).
./configure used with
--with-sslplus
This string option is not permitted in a
configuration file in the user's home
directory nor in the spool directory.
QUALCOMM Incorporated
38

---

Configuring Qpopper
Qpopper LX User Manual
Equivalent
Type this option...
Description
Command Line
Option
tls-private-key-file
Specifies a file which contains the
none
server's TLS/SSL private key.
Only valid if
./configure used with
Note. This private
--with-openssl
key must not be
encrypted.
If the private key is contained in the
same file as the certificate (as
specified with tls-server-cert-file), you
do not need to specify this option.
This string option is not permitted in a
configuration file in the user's home
directory nor in the spool directory.
tls-server-cert-file
Specifies a file which contains the
none
server's TLS/SSL certificate. This file
Only valid if
may also contain the server's
./configure used with
unencrypted private key.
--with-openssl
This string option is not permitted in a
configuration file in the user's home
directory nor in the spool directory.
tls-support
Specifies TLS/SSL support. The
Only valid when
permitted values are:
--with-openssl or
·default
TLS/SSL is not supported.
--with-sslplus used with
-l 0
./configure
·none
(SAME AS DEFAULT)
·stls
Enables support for the STLS
-l 1
command. This permits TLS/SSL
negotiations on the standard (or any)
port, allowing the same port to be
used by TLS/SSL and regular clients.
·alternate-port
Enables
-l 2
alternate-port TLS/SSL. Some older
clients require this. (The usual port for
alternate-port TLS/SSL with pop is
995.)
This mnemonic option is not permitted
in a configuration file specific to a user
(in the user's home directory or in the
spool directory.)
Default: default
QUALCOMM Incorporated
39

---

Qpopper LX User Manual
Configuring Qpopper
Equivalent
Type this option...
Description
Command Line
Option
tls-version
Restricts the version of TLS/SSL
none
recognized in session negotiations.
Only valid when
You normally do not need to set this.
--with-openssl used with
./configure
Supported values are:
·default
(same as SSLv23)
·SSLv2
Forces Qpopper only to
understand SSLv2 client hello
messages.
·SSLv3
Forces Qpopper only to
understand SSLv3 client hello
messages. This especially means that
it does not understand SSLv2 client
hello messages, which are widely
used for compatibility reasons.
·TLSv1
Forces Qpopper only to
understand TLSv1 client hello
messages. This especially means that
it does not understand SSLv2 client
hello messages, which are widely
used for compatibility reasons. It also
does not understand SSLv3 client
hello messages.
·SSLv23
Allows Qpopper to
understand SSLv2, SSLv3, and
TLSv1 client hello messages. This is
the best choice when compatibility is
a concern. This is the default value.
·all
(same as SSLv23)
This mnemonic option is not permitted
in a configuration file in the user's
home directory nor in the spool
directory.
Default: default
QUALCOMM Incorporated
40

---

Equivalent
Type this option...
Description
Command Line
Option
tracefile
Enables debug logging if
-t logfile
--enable-debugging used with
./configure). All debug and
standard log records are written to the
specified file. If this option is used, it
should be first, so that debug records
are generated for subsequent options.
If used without --enable-debugging,
redirects all log messages to the
specified file.
This string option is permitted in all
configuration files.
trim-domain
When set, domains are trimmed from
-C
user names before use. For example,
if a user named maida enters her
login name in her POP client as
maida@example.org, Qpopper treats
this as just maida.
This Boolean option is not valid in
configuration files specific to a user
(those in a home directory or the
spool directory).
Default: false
user-options
Reads additional run-time options
-u
from a file named .qpopper-
options in the user's home directory,
if present.
This Boolean option is not permitted
in a configuration file in the user's
home directory nor in the spool
directory.
Default: false
Enabling Server Mode
Server mode reduces Qpopper's I/O usage for sessions where users download and delete
all their mail, or when they leave all their mail on the server (in other words, sessions
where they delete all messages or no messages). Server mode can only be used when
Qpopper and the local delivery agent are the only processes which alter the mail spool.
Do not enable server mode for users who telnet to the mail server and access the
mail spool directly, or run local programs which access the mail spool.
QUALCOMM Incorporated
41

---

Qpopper LX User Manual
Enabling Server Mode
Server mode is ideal for situations where a system acts only as a mail server; where users
do not have shell accounts.
You can enable or disable server mode on a user-by-user basis, by users' group member-
ship, for all users, or any combination.
In normal (non-server) mode, Qpopper starts a session by locking the mail spool, copying
all messages to a temporary file, zeroing the mail spool, then unlocking it. At the end of the
session all non-deleted messages (plus any new ones that arrived during the session) are
copied back to the spool. By working from a temporary copy of the mail spool, Qpopper
operates at the highest safety level, at the cost of extra I/O.
In server mode, Qpopper starts a session by scanning the mail spool instead of copying it.
It works from the mail spool during the session. If at the end of the session all messages
are deleted, or no changes have been made to the state of the spool or its messages,
Qpopper avoids having to do any copying at all.
Because most POP clients download and delete all messages by default, enabling server
mode can save a lot of server I/O. Even when users turn on leave mail on server in their
POP client, most sessions do not result in any changes, again potentially saving a lot of I/O.
Qpopper further reduces I/O at the start of a session by avoiding the initial scan of the
spool in many cases where server mode is used. This can result in a mail-check time of
well under a second, versus a minute or more for very large spools.
You can decrease the situations in which Qpopper needs to copy and update the spool at
the end of a session by using the --disable-status configure flag, or the
update-status-headers configuration file option. However, this increases CPU usage and
prevents Qpopper from keeping track of which messages have been downloaded, a
feature relied upon by some clients. This also prevents Qpopper from storing the unique
identifier (UID) of each message in an X-UIDL: header, forcing it to recalculate it when
needed. It also prevents Qpopper from writing Status: headers.
You can enable server mode on a per-user basis. Just set the default for all users at
compile or run time. You can indicate that certain users will use Qpopper in server mode
or not, regardless of the defaults.
To specify server mode as a default for all users at compile time, do the following:
s
Run the configure script, adding --enable-servermode.
To specify server mode as a default for all users at run time, do the following:
s
Use the -S run-time option or the server-mode option in a configuration file.
To indicate that users of a specific group should use server mode, regardless of the
default, do the following:
s
Run the configure script, adding --enable-server-mode-group-include=group where
group is the name of the group, or use the group-sever-mode option in a configuration
file. Users who are members of this group will use server mode. (It may also be conve-
nient to disable shell access to users in this group, to prevent them from accessing the
spool other than through POP).
To indicate that users of a specific group should not use server mode, regardless of the
default, do the following:
QUALCOMM Incorporated
42

---

Enabling Standalone Mode
Qpopper LX User Manual
s
Run the configure script, adding --enable-server-mode-group-exclude=group where
group is the name of the group, or use the group-no-server-mode option in a configura-
tion file. Users who are members of this group will not use server mode.
To set server mode on or off for a specific user, do the following:
s
Place a file called .qpopper-options in the user's home directory, set the
server-mode option in this file, and use the -u command-line option or include the
user-options option in a configuration file. You can also use a file called
.user.qpopper-options in the spool directory, with the -U command-line option or
spool-options configuration file option.
The determination of server mode is in the following order:
s
Compile-time default (--enable-server-mode)
s
Run-time default (-S or server-mode)
s
Compile-time inclusion group (--enable-server-mode-group-include=group) that the
user is a member of
s
Run-time inclusion group (group-server-mode)
s
Compile-time exclusion group (--enable-server-mode-group-exclude=group) that
the user is a member of
s
Run-time exclusion group (group-no-server-mode)
s
User-specific .qpopper-options file in the home directory or
.user.qpopper-options in the spool directory.
Enabling Standalone Mode
Normally, Qpopper is launched from inetd (or a similar program). However, you can build a
version of Qpopper that operates as a standalone daemon if you prefer. Operating
Qpopper in standalone mode may result in better performance, but you may lose the
ability for access control and load throttling. To enable standalone mode, use the
--enable-standalone flag with ./configure.
To enable Qpopper's standalone mode, do the following:
1
On the command line, type ./configure --enable-standalone (plus any other desired
options)
2
Configure Qpopper to be launched on system start-up. If desired, specify the IP
address and/or port number to bind to at run-time as parameter 1, for example, 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 is 110 except when _DEBUG (not simply DEBUG) is
defined, then it is 8765.
QUALCOMM Incorporated
43

---

Qpopper LX User Manual
Using Macros
Using Macros
There are a large number of options which can be modified at compile time. The ones
which are generally useful can be set by using a flag with ./configure, for example
--enable-debugging for DEBUG, which is the recommended way. Many of these can also be
adjusted using run-time options.
The obscure ones have to be set manually. To do so, edit config.h after running
./configure. To set a macro, add or change a #define line. For example, to set macro
FOO, add #define FOO.
The following table lists Qpopper macros, a description and the corresponding configure
flags used to set the macro:
Macro
Description
Configure flag
MMDF_SEP_CHAR
A line that starts with this
none
Default is '\001'
character is considered an
(<CTL>-A)
MMDF separator. The rest of
the line is copied as the
separator regardless of its
value.
BULLDIR
See "Configure Options" on
--enable-bulldb=path
page 11 for a description.
NEWBULLCNT
See "Configure Options" on
--enable-new-bulls=number
page 11 for a description.
OFF_T
If OFF_T is not typed for you,
none
then set this definition to a type
that lseek and ftruncate and
expect it as an offset
parameter. UID_T, GID_T, and
PID_T are also available for
portability.
BLOCK_UID
Qpopper prevents access by
none
users with a UID at or below this
value. This is because normally
low UIDs are only used for root
and daemon processes, which
should never be checking mail.
Attempts to do so may indicate
a security attack.
The default value is 10. This
indicates that root and other
users with UID values of 10 and
under are not able to login via
Qpopper.
POP_FACILITY
See "Configure Options" on
--enable-log-facility=name
page 11 for a description.
QUALCOMM Incorporated
44

---

Using Macros
Qpopper LX User Manual
Macro
Description
Configure flag
KERBEROS
See "Configure Options" on
--with-kerberos5=directory
page 11 for a description.
AUTHFILE
See "Configure Options" on
--enable-auth-file=path
page 11 for a description.
NONAUTHFILE
See "Configure Options" on
--enable-nonauth-file=path
page 11 for a description.
SPEC_POP_AUTH
See "Configure Options" on
--enable-specialauth
page 11 for a description.
RPOP
This feature allows the POP
none
client to use the hosts.equiv
and.rhosts files for
system/user validation. This
feature is not recommended
since it can easily be defeated
and thus create a serious
security risk.
SECURENISPLUS
See "Configure Options" on
--enable-secure-nis-plus
page 11 for a description.
DEBUG
See "Configure Options" on
--enable-debugging
page 11 for a description.
SETPROCTITLE
This definition controls whether
none
setproctitle() should be
used to display user, host, and
status in the process title. Your
operating system must support
this feature. Set automatically
by./configure.
KEEP_TEMP_DROP
See "Configure Options" on
--enable-keep-temp-drop
page 11 for a description.
BIND43
BIND 4.3 is a domain name
none
service. Set automatically
by./configure.
SYSLOG42
Qpopper defaults to BSD 4.3
none
syslog.
HOMEDIRMAIL
See "Configure Options" on
--enable-home-dir-mail=Mailbox
page 11 for a description.
APOP=
See "Configure Options" on
--enable-APOP=path
"/etc/pop.auth"
page 11 for a description.
QUALCOMM Incorporated
45

---

Qpopper LX User Manual
Using Macros
Macro
Description
Configure flag
POPUID=pop
See "Configure Options" on
--enable-popuid=pop
page 11 for a description.
GNUPASS
This definition specifies the use
none
of the modified GNU
getpass() routine which
allows longer than 8 character
passwords to be entered when
using popauth. There is also a
definition within popauth
(NO_GETLINE) if you compile
this code, and it complains if it
doesn't have a getline
routine.
CONTENT_LENGTH
If your local delivery agent
none
inserts a Content-Length:
header into the message,
define this option. This is
usually set automatically for
most systems.
SERVER_MODE
See "Configure Options" on
==enable-server-mode
page 11 for a description.
NO_STATUS
See "Configure Options" on
--disable-status
page 11 for a description.
NOUPDATEONABORT
See "Configure Options" on
--disable-update-abort
page 11 for a description.
HASH_SPOOL=(1|2)
See "Configure Options" on
--enable-hash-spool
page 11 for a description.
BULLDB
See "Configure Options" on
--enable-bulldb=path
page 11 for a description.
CHECK_SHELL
Enable this compile time
none
feature to lock out users via the
shell value. A user shell of
/POPPER/ANY/SHELL allows
the user access but blocks
other programs that check
shells.
GDBM
This value uses the GNU
none
GDBM library instead of
NDBM.
_DEBUG
This permits popper to be run
--enable-low-debug
from a shell, for hard-core and
heavy debugging.
QUALCOMM Incorporated
46

---

Qpopper Notes
Qpopper LX User Manual
Macro
Description
Configure flag
LOG_LOGIN
See "Configure Options" on
--enable-log-login
page 11 for a description.
AUTO_DELETE
See "Configure Options" on
--enable-auto-delete
page 11 for a description.
SHY
See "Configure Options" on
--enable-shy
page 11 for a description.
USE_PAM
See "Configure Options" on
--with-pam=service name
page 11 for a description.
TRACE_MSG_
Define if you want to include
none
BODY
message bodies in trace
information written with the -t or
-d run-time option.
Qpopper Notes
s
Qpopper uses the standard system authentication routines (which generally use
/etc/passwd and /etc/shadow) to validate the user name in any mode (user/pass,
kerberos, APOP) because the mail spool file must be owned by someone. The owner-
ship relationships generally reside in /etc/passwd. Therefore, a user name must
generally exist in both the passwd file as well as any of the other files associated with
other authentication methods.
s
When Qpopper is running, it moves your mail spool file to a file called .user.pop in
the temporary spool location (mail spool directory is the default). /tmp can be an alter-
native location but is not recommended for security reasons. A system reboot will clear
the files in /tmp. For performance reasons, a system administrator who has 1000+
users can create a separate spool directory, such as /usr/spool/poptemp, for
Qpopper files. You can specify this directory to Qpopper by using the
--enable-temp-drop-dir option when running./configure. Permissions should be the
same as your mailspool with the same owner and group.
s
Your spool directory needs to have ownership and permissions set correctly. Normally,
this directory has owner root and group mail, and is set drwxrwxr-x or drwxr-
wxrwt. (The second form sets the sticky bit to prevent non-owners from deleting or
renaming files.)
s
By default, Qpopper sets its group ID to the group of the spool directory before setting
its UID to that of the user and giving up root privileges. Thus, by making the spool direc-
tory group mail and making it group writable, Qpopper is able to create and modify the
user's spool and the dot-lock file. Since no users are part of the mail group, this is
secure.
s
-no-mime--As a way to enable MIME-mangling (reduce multipart MIME messages to a
single text part, no attachments) with clients that do not support XMANGLE, add
-no-mime to the user name. For example, if the user name is mary, enter it in the client
as mary-no-mime.
s
Do not use Qpopper over NFS. (But see no-atomic-open on page 35.)
QUALCOMM Incorporated
47

---

Qpopper LX User Manual
Operating System-Specific
Operating System-Specific
s
SCO--Some versions of SCO use the crypt_d library, others the crypt_i library. This
distribution assumes crypt_d. SCO requires loading the Standard and TCP/IP develop-
ment environments to get the sockets and crypt libraries.
Also, if you wish to use the elf binaries (to use dynamic instead of static linkage for C
run-time functions), you need to edit the Makefiles so that the LIBS line is:
-lnsl -lsocket -lcrypt -lprot -lm -lx -ltinfo and the CFLAGS line has -s -O -belf. (-s indi-
cates strip the symbols (you can omit this if you choose), -belf indicates use elf bina-
ries.)
s
IRIX--The default spool directory is /usr/mail; some systems use /usr/spool/mail.
s
FreeBSD--This requires the crypt library for password comparisons.
s
OSF/1--If you are not using enhanced security (shadow passwords), then don't use
--enable-specialauth. Otherwise, you receive a link error stating that
set_auth_parameters() is not defined.
s
A/UX-- A/UX does not support the sticky bit, so the default directory is /tmp. If you
want to support shadow passwords, you need to use --enable-specialauth
with./configure. A shadow password library is also required. You can find one on
jagubox.gsfc.nasa.gov. A/UX requires GCC and libUTIL.a, also available on jagubox to
build some versions of Qpopper.
s
NCR--You may need to increase STRTHRESH, for example, a 600 user system
needs to increase from 0x200000 to 0x600000.
s
NeXT--You should probably use NetInfo Manager available under Next Admin to
change your services file.
QUALCOMM Incorporated
48

---

Managing Qpopper
Security and Authentication
In addition to the standard username and password, Qpopper can use APOP, Kerberos
(version 4 or 5), or any PAM method. Qpopper can also use TLS/SSL to encrypt the authen-
tication exchange.
Caution. To avoid the danger of sending clear text passwords over the network, use
APOP, Kerberos, or TLS/SSL.
APOP
In APOP, the server issues a challenge, and the email client sends a response which
proves it knows the password, without sending the actual password. Both the challenge
and the response contain a random element, which prevents the response from being
used by an interceptor.
APOP requires dbm or gdbm libraries to exist on the system. gdbm is a GNU's version of
dbm, which can be obtained from any of GNU's distribution sites.
To setup APOP authentication, do the following:
1
Create a user account, for example POP, to be used for administering the APOP users.
2
Choose a location where popauth will place the authentication files, typically
/etc/pop.auth.
Caution. Make sure this is read/write accessible only to the administering account
pop.
3
Run the configure script with the --enable-apop and --with-popuid flags, for example
./configure --enable-apop=/etc/pop.auth --enable-popuid=pop
The first flag is the location of the authentication files; the second specifies the admin-
istering account that owns the authentication database.
4
Run make, this should produce executable files popauth and popper.
5
Move the executable files to a public location (normally you can run make install as
root to do this).
6
Change the owner on popauth to the administering account (for example, pop) and
set suid, for example:
chown pop /usr/local/lib/popauth
chmod u+s /usr/local/lib/popauth
7
Initialize the authentication database files by running the following command as root:
popauth -init
QUALCOMM Incorporated
49

---

Qpopper LX User Manual
Security and Authentication
8
New users can be added by root or the administering user (for example, pop) with
the following command: popauth -user user
Or removed with the following command: popauth -delete user
Other users can add themselves or change their password with the following
command: popauth
9
Scripts or other non-interactive processes can add or change the password for a user
with the following command:
popauth -user user password
TLS/SSL Encryption
TLS/SSL allows all communications between Qpopper and an email client which supports
TLS/SSL (such as Eudora) to be encrypted. This includes the contents of messages as well
as authentications. TLS/SSL can keep confidential information or passwords from being
intercepted in transit.
Note. TLS/SSL does not provide end-to-end encryption of email messages, not does it
prevent or detect forged mail. But it can prevent passwords and mail messages from being
seen by a network eavesdropper.
To use TLS/SSL, you must have /dev/urandom installed on your system. See your vendor
if you need to obtain this.You also need TLS/SSL and cryptographic libraries, plus a security
certificate and a public-private key pair. You also need to set TLS/SSL options, which indi-
cate how you want Qpopper to support TLS/SSL (alternate port or STLS) and specify the
certificate and private key.
If you use precompiled versions of Qpopper, you do not need to obtain TLS/SSL and cryp-
tographic libraries. You can skip right to the section about getting your certificate.
Obtaining TLS/SSL and Cryptographic Libraries
Qpopper works with the TLS/SSL and cryptographic libraries in the free OpenSSL package
(available at <http://www.openssl.org>) as well as SSL Plus and Security Builder® from
Certicom (see <http://www.certicom.com>).
1
Obtain the libraries from either source
2
Install the libraries on your system (follow the instructions that came with the libraries)
3
Run./configure, adding --with-openssl if you installed the OpenSSL libraries, or
--with-sslplus if you installed the SSL Plus libraries. (Add any other desired ./configure
flags). For example:
./configure --with-openssl --enable-specialauth --enable-timing
Creating a Security Certificate
To create a certificate signed by a Certificate Authority using OpenSSL, follow these steps:
QUALCOMM Incorporated
50

---

Security and Authentication
Qpopper LX User Manual
1
Create or choose a directory for the certificates and your private key. Because the
private key is stored decrypted, it is very important that only user root has access to
this directory. Assuming you choose /etc/mail/certs (which works as long as you
do not have a user named certs), type the following three commands:
mkdir -p -m665 /etc/mail/certs
chown root:mail /etc/mail/certs
chmod 660 /etc/mail/certs
2
Use openssl to create a public-private key pair and a certificate signing request (csr).
For example, the following command (this text should be entered at a command
prompt as one line):
/usr/local/ssl/bin/openssl req -new -nodes -out req.pem -keyout
/etc/mail/certs/cert.pem
When you run openssl it prompts you for several items of information. It is very
important that you properly answer these prompts; the default explanation in the
prompt may not be accurate. It asks you:
s
Country Name -- Supply the ISO-standard two-letter code for your country.
s
State or Province Name --Type the full name of your state or province.
s
Locality Name --Type the full name of your city or municipal area.
s
Organization Name -- Type the legal name of your company or organization.
s
Organizational Unit Name -- Type the name of your division or section of your
company.
s
Common Name -- Type the fully-qualified host name of the mail server host. Do
not type your personal name, even if the openssl prompt directs you to type it.
This must be the same name that a client enters to get to your server.
s
Email Address -- This should be your email address, or that of an institutional role
(such as postmaster).
3
Ensure that the file which now contains the private key (and will later contain the
signed certificate) is owned by and only accessible by root. For example, the following
two commands:
chmod 600 /etc/mail/certs/cert.pem
chown root:0 /etc/mail/certs/cert.pem
4
Send the certificate signing request (file req.pem) to your Certificate Authority for
signing. You will receive back a signed request. Assuming this signed request is in a
file called signed_req.pem, concatenate it to the private key generated earlier:
cat signed_req.pem >> /etc/mail/certs/cert.pem
If you are using SSL Plus, see its documentation.
Setting TLS/SSL Options
After obtaining the TLS/SSL libraries, creating your private/public key pair, and obtaining
your security certificate, you need to set certain TLS/SSL options. These options indicate
how you want Qpopper to support TLS/SSL (alternate port or STLS), and specify the certifi-
cate and private key files.
QUALCOMM Incorporated
51

---

Qpopper LX User Manual
Security and Authentication
1
Create a configuration file for Qpopper. You can locate this file anywhere you choose.
For example, /etc/mail/pop/qpopper.config. Put the paths to the private key
and signed certificate in this file, and enable either alternate-port or STLS. For example,
using the above file names and STLS with OpenSSL:
set tls-support = stls
set tls-server-cert-file = /etc/mail/certs/cert.pem
If you want to enable both alternate-port and STLS, you can do this with three configura-
tion files. One file contains the set tls-support = stls command, and a second
file contains the set tls-support = alternate-port command. Both files also
contain one other command, which instructs Qpopper to read the third configuration
file, for example, set config-file = /etc/mail/pop/qpopper-tls.config.
Set all other options in this third file. Then use the -f run-time option to cause Qpopper
to read either of the first two files.
If you are using OpenSSL, you need to set tls-server-cert-file. If your private key is in a
separate file, you also need to set tls-private-key-file. (In any case, the private key must
not be encrypted.) Caution: Because your private key is in the clear, be certain the file
is owned by root and no other users or groups have access.
If you are using SSL Plus, you need to set tls-identity-file and tls-passphrase. With SSL
Plus, your certificate and private key need to be in one file (called an identity file), and
the private key must be encrypted. You specify the passphrase to decrypt the private
key with the tls-passphrase option. Caution: Because your passphrase is in the clear
in the configuration file, be certain that the configuration file is owned by root and no
other users or groups have access.
2
Use the -f config-file-path command-line option to tell Qpopper to read the configura-
tion file. For example, -f /etc/mail/pop/qpopper-stls.config.
PAM
PAM is an architecture which allows the use of various authentication modules with
different applications. It is available on many platforms, including Linux and Solaris.
To use PAM, add the --with-pam=service-name flag when running./configure. If you
omit service-name it defaults to pop3.
You must then create a file in /etc/pam.d with the same name as specified for
service-name, for example, /etc/pam.d/pop3. This file contains the rules for authenti-
cating using Qpopper. See your PAM documentation for more details.
An example of such a file is:
#%PAM-1.0
auth
required
/lib/security/pam_pwdb.so shadow
account
required
/lib/security/pam_pwdb.so
password
required
/lib/security/pam_cracklib.so
password
required
/lib/security/pam_pwdb.so nullok
use_authtok md5 shadow
session
required
/lib/security/pam_pwdb.so
QUALCOMM Incorporated
52

---

Kerberos
Kerberos is a mechanism for secure authentication over untrustworthy networks. For more
information, see the MIT Kerberos pages at <http://web.mit.edu/kerberos/www/>.
Caution. If you use Kerberos with Qpopper, be sure to obtain updated libraries that
address CERT Advisory CA-2000-06 (see
<http://www.cert.org/advisories/CA-2000-06.html>).
To use Kerberos with Qpopper, first obtain and install Kerberos libraries. We recommend
using Kerberos version 5. To use Qpopper with Kerberos version 5, add the
--with-kerberos5 flag to your./configure command.
Using Bulletins
Bulletins can be used to send messages to all POP users. Bulletins are placed as plain text
files in a specified format under a directory known to the server. Each bulletin has a name
which starts with a unique, ascending number. Qpopper orders the bulletins by this
number, and keeps track of which ones each user has seen. By default, new users get
only the single most recent bulletin, but you can override this.
You can further classify bulletins by which group of users is to receive them.
Bulletins have two main advantages over simply sending an email to all users. First, the
work of copying the bulletins is spread out over time, as each user checks mail. Second,
new users get bulletins.
You must first enable bulletins, then write them.
Enabling Bulletins
To enable bulletins, do the following:
1
Choose the directory where the bulletins reside, usually /var/spool/bulls. The
directory should be readable but not writable with user privileges, or make the permis-
sions the same as the spool directory, for greater security.
2
Run./configure with the flag --enable-bulletins in addition to any other options. For
example: ./configure --enable-bulletins=/var/spool/bulls. Note that if you keep
bulletins in /var/spool/bulls, you don't have to specify this, since it is the default
location.
3
Run make and install as usual.
4
Use the command line option -b to override the compiled value for the bulletin direc-
tory, if desired.
If you want to use a central database instead of an individual file in the user's home direc-
tories to track which bulletins have been seen by which user, follow the instructions later in
this section.
QUALCOMM Incorporated
53

---

Writing Bulletins
To write a bulletin, do the following:
1
Create the bulletins as files. One easy way to do this is to use an email program (such
as Eudora) and simply send yourself email, then do a save as to save the messages in
files. You'll need to edit the files to add a "From " separator line, as described here.
2
Place the bulletins as files in the bulletins directory. The files should be readable, but
not writable to everyone. You can chose readable file names for bulletins using the
number.string form, for example, 00001.Bulletin_one,
00002.four_hour_Downtime_2-4-98, 00003.Quota-Revisions.
3
Ensure that each bulletin starts with a unique and ascending order number. The
number portion of each new filename should be one plus the largest bulletin number in
the directory. (So if the current largest bulletin number is 00083, use 00084 for the next
bulletin.)
Caution. You cannot recycle the bulletin numbers.
You can limit bulletins to certain groups by using the --enable-group-bulls option
with./configure or the group-bulletins configuration file option, and by inserting the
group name as the second element in the bulletin file name.
For example, the bulletin 001.staff.new_program_installed would be seen
only by members of the staff group.
4
Write the bulletin's header. Bulletins must be in the same format as messages in the
mailspool. You must write the bulletin in the following format as shown in this example.
From qpop Wed Nov
9 13:31:08 1994
Date: Wed, 9 Nov 1994 13:31:07 -0800 (PST)
To: user@localhost
From: POP Administrator <postmaster@localhost>
Subject: Example bulletin
The first line must start with From and a space. It must be complete with address and
date. An incorrect From line could cause the message to get concatenated to the
previous message. Note that Qpopper replaces the To: line when the bulletin is copied
to the user's mail spool.
5
Write the bulletin's message. There must an empty line (a line with just a new-line char-
acter, no spaces or tabs) between the header and message body, for example.
From qpop Wed Nov
9 13:31:08 1994
Date: Wed, 9 Nov 1994 13:31:07 -0800 (PST)
To: user@localhost
From: POP Administrator <postmaster@localhost>
Subject: Example bulletin
The system will be down for maintenance
between 12 Midnight and 6 A.M. on November 30.
This bulletin is appended to the mailspool when the user checks his/her mail.
If you remove a file later on, it won't be seen by users who haven't checked their mail since
you created the bulletin.
QUALCOMM Incorporated
54

---

Qpopper LX User Manual
Using Bulletins
Note. Try to preserve the RFC 822 header format, especially date format. Failure to do so
may cause email clients not to parse header information correctly.
Working with Bulletins
At the start of a POP session (after user authentication), Qpopper copies unread bulletins
placed in the bulletins directory to the user's message spool. Qpopper figures out the last
bulletin seen by the user by placing in the user's home directory a file called.popbull.
This file contains the number of the last bulletin seen by the user. Any bulletin in the bulle-
tins directory with a number greater than the one in .popbull is copied to the user's
message spool.
A bulletin database can be used to track the bulletins instead of .popbull files in the
users' home directory. This feature is enabled by using the
--enable-bulldb=/var/spool/bulls option instead of the --enable-bulletins option with
./configure.
If you use the bulletin database feature, it reads old .popbull files if they exist (but does
not update them).
If you have a busy server, using a central database may impose concurrency issues. If too
many users retrieve their mail at the same time, it may be difficult for some users to obtain
write access to the bulletins database. By default, this results in an error.
If your system has the usleep(3) function, this is detected by the configure script, and
should help the problem of multiple users. Even so, there is still a possibility that you may
have a problem on an extremely busy server. If you want to use a bulletin database
anyway (to avoid problems with users who lack a home directory or who exceed disk
quota for their home directory), you can adjust the bulletin database behavior with
run-time options.
Using the -B or bulldb-nonfatal option allows the POP session to continue even if the bulle-
tins database can't be opened. As a result, your users will get their mail, but may not see
some bulletins for possibly a long time, or even at all.
You can also set the maximum times Qpopper tries to lock the database with the
bulldb-max-retries option. When the database is in use by another user, Qpopper tries
repeatedly to access it, pausing for an amount of time between attempts. On systems with
the usleep(3) function, this amount of time is a small random number of microseconds
(somewhere between 1 microsecond and half a second), and the default value for
bulldb-max-retries is 75. This usually results in a maximum delay well under a minute. On
systems without the usleep(3) function, Qpopper waits between one and
bulldb-max-retries seconds, which by default is 10. This may result in a maximum delay
under two minutes, with far fewer attempts, and therefore less chance of success. To see
if your system has the usleep(3) function, try man usleep or fgrep -i usleep config.h
after running./configure. If you see #define HAVE_USLEEP 1 then you have the
usleep(3) function.
QUALCOMM Incorporated
55

---

Configuring Bulletins for New Users
New users receive the single newest user bulletin by default. You can override this and
specify how many bulletins new users should get (they will get that many of the newest
bulletins). For example, pass --enable-new-bulls=10 to./configure to give new users a
maximum of ten bulletins, or add set max-bulletins=10 to a configuration file.
QUALCOMM Incorporated
56

---

Qpopper LX User Manual
Performance
Performance
Performance
Performance, that is, the hardware resources (such as CPU time and I/O bandwidth)
needed to service a given number of users in a set amount of time, depends on many
factors outside the scope of this manual. For example, your users' characteristics make a
very big difference. Some users receive very little mail, check mail infrequently (perhaps
every few days), and download and delete all their mail on each mail check. Other users
receive massive amounts of email, keep all their mail on the server, and check mail
constantly.
The type of hardware you use also has a very large impact. Generally speaking, SCSI or
Firewire disk systems consume much less CPU per I/O and permit simultaneous I/O on
separate channels. They are thus generally better suited for servers.
However, there are compile-time and run-time options which can affect Qpopper's perfor-
mance.
In general, most administrators who are concerned about performance attempt to reduce
the I/O needs of Qpopper.
The first option to consider for performance is server mode. Server mode reduces I/O in
sessions in which all mail is deleted (the default with man email clients) or all mail is left on
the server. It is safest when your users do not have shell access to the server. Server
mode can be enabled for all users, all users who belong to a certain group, users who do
not belong to a specified group, or on a user-by-user basis. See "Enabling Server Mode"
on page 41 for more information.
Qpopper offers faster session start-ups when using server mode. In may cases, session
start-ups with very large spools can be reduced to a few milliseconds from up to a minute
(or even more).
Qpopper also offers the fast-update option which reduces I/O by a third during spool
updates. Caution: use of this option is likely to break programs such as biff(1) or the
shell's mail check feature. Only enable if such programs are not used. To be safe, don't set
this option for users who have shell access to the system. This option is set with the -F
command-line flag or the fast-update configure file option. Fast update is ideal for situa-
tions where a system acts only as a mail server.
In most UNIX/Linux systems, opening a file within a directory requires that the list of file
names contained in the directory be read serially, until the desired file is found or all
names have been read. This can result in a significant performance penalty when a large
number of files exist in any directory. With email, this is most striking in the spool directory.
There are several things you can do to resolve this. A fairly easy method tells Qpopper to
use a different directory for the temporary spool files it creates. This action alone can
reduce the number of hits on your spool directory enough to make a difference. To use this
method, decide on and create the new directory (make sure it has the same permissions
QUALCOMM Incorporated
57

---

Performance
Qpopper LX User Manual
and ownership as the spool directory). Then use the --enable-temp-drop-dir=path flag
with./configure, specifying the directory as path, or add set temp-dir=path to a
configuration file.
You might also want to switch to hashed spool directories. Normally, the spool files for all
users are located in the spool directory. With hashed spool directories, there is an extra
layer or two of directories. This reduces the number of files in any one directory.
Qpopper supports the two most popular methods for hashed spool directories, called,
imaginatively, method 1 and method 2 (or just 1 and 2).
To enable hashed spool directories, use --enable-hash-spool=1 or --enable-hash-spool=2
with./configure, or add set hash-spool=1 or set hash-spool=2 to a configura-
tion file.
When enabled, the subdirectory for a mail spool is determined from the user name by
either hashing the first four characters (adding and then modulus 26) or by using directo-
ries equal to the first letter and the second letter (if any). For example, if the spool directory
is /var/mail, the spool file for user maida would be:
/var/mail/maida
HASH_SPOOL not set
/var/mail/o/maida
method 1
/var/mail/m/a/maida
method 2
By default, when hashed spools are enabled, Qpopper checks whether or not the subdi-
rectory or subdirectories exist for a user every time that user logs in. If the directory or
directories do not exist, Qpopper creates them. This can be helpful when first moving to
hashed spools but is unnecessary and a waste of time if the directories exist. Use the
--disable-hash-dir-check flag with./configure or add reset check-hash-spool to a
configuration file to prevent this.
Caution. If you disable this check, be sure to precreate all hashed spool subdirectories, or
Qpopper (or the local delivery agent) may crash when trying to deliver mail to users whose
containing directory does not yet exist.
Instead of hashed spool directories, some sites prefer to place mail spools in the user's
home directory, typically in a file called.mail. This can avoid the problem of too many
spools in one directory but does require that each user have a home directory. There may
also be problems with users who exceed quota or have too many files in their home direc-
tory. This feature is called home directory mail, and is enabled by passing
--enable-home-dir-mail=file to./configure. If you use the default file name of.mail,
you don't need the =file part. You can also add set home-dir-mail=file to a configu-
ration file.
Note that the home-dir-mail option only affects the spool file. If you want the .user.pop
and the .user.cache files to be placed in the user's home directory as well, set the
home-dir-misc option, either by passing --enable-home-dir-misc to ./configure, or by
adding set home-dir-misc to a configuration file.
When either hashed spool directories or home directory mail is used, by default Qpopper
checks whether or not old temporary mail spool files exist in the spool directory. (This
could happen if a very old version of Qpopper was used and was terminated before it
could cleanup). This check is a waste of time in virtually all cases, but Qpopper is
QUALCOMM Incorporated
58

---

Qpopper LX User Manual
Performance
designed to protect the safety of mail. You can turn off this check and save time by
passing --disable-old-spool-loc to./configure, or adding reset
check-old-spool-loc in a configuration file.
For example, your ./configure command might look like:
./configure --enable-hash-spool=2 --disable-hash-dir-check
--disable-old-spool-loc --enable-specialauth
or, in a configuration file:
set hash-spool = 2
reset check-hash-spool
Adding reset update-status-headers to a configuration file, or use of the
--disable-status ./configure flag prevents Qpopper from creating or updating Status:
and X-UIDL: headers. Combined with server mode, this further reduces I/O in sessions in
which all mail is left on the server, and new mail has arrived. However, it also prevents
Qpopper from keeping track of which messages have been downloaded, a feature relied
upon by some email clients. In addition, it forces Qpopper to recalculate the unique identi-
fier (UID) of each message, which increases CPU usage.
By default, Qpopper aggregates data to be sent to clients into large chunks. For example,
an entire 1024-byte mail message might be sent in one packet. This may be faster or
slower, depending on specifics of both the client and server hardware and networking
stacks, as well as network elements in between (such as routers). Also, some networking
stacks do their own aggregation.
Under congested network conditions, larger packets may increase the incidence of lost
packets and thus client or server timeouts, leading to POP timeout or EOF errors.
When TSL/SSL is in effect, smaller packets increase the overhead needed to send data,
which may result in worse performance.
You can adjust the Qpopper behavior by setting the chunky-writes configuration file option.
See "chunky-writes" on page 30 for details.
Standalone mode may offer better performance than using inetd, but be aware that you
may lose capabilities such as load throttling, address filtering, etc. Standalone mode is
enabled with the --enable-standalone./configure flag. See "Enabling Standalone
mode" on page 43 for more information.
Disabling reverse lookups avoids whatever overhead is incurred by the reverse DNS
lookup. However, it may make your logs harder to read. Use the -R command-line switch
or the reverse-lookups configuration file option.
You can adjust the frequency with which Qpopper calls kernel routines to check whether
or not the mail lock needs to be refreshed during session start-up and shutdown. This is
done with the -L command-line or mail-lock-check configuration file option; however, this
option is probably not necessary in most cases. The option specifies the number of
messages to be processed during initialization and cleanup before checking whether or
not the mail lock needs refreshing. The default is 500. The value must be small enough to
be processed in 60 seconds.
QUALCOMM Incorporated
59

---

Qpopper LX User Manual
Performance
QUALCOMM Incorporated
60

---

Troubleshooting
Qpopper LX User Manual
Troubleshooting
Troubleshooting
The first step in troubleshooting Qpopper is to try and telnet in to it. Generally, the
easiest way to do this is to telnet from the host where you just installed Qpopper to
itself. You need to specify the POP3 port in the telnet command. So, if you just installed
Qpopper on a host called penguin, enter the following command: telnet penguin pop3.
inetd is not servicing the POP3 port if you receive one of the following error messages:
connect: Connection refused
connect: Connection closed
If you receive the first message, check your services file and make sure the port name
pop3 is exactly the same as the one in inetd.conf. Also, it can indicate that you have
not reset inetd (kill -HUP inetd PID) (some systems can use inetd -c).
If you receive the second message, this indicates that inetd has the correct port
assigned to Qpopper, but th