Introduction:

Do you want to run a POP3 server on FreeBSD? One of the most popular POP3 servers, Qualcomm's Qpopper, is available in the FreeBSD ports collection. This is a step-by-step guide to quickly setting up Qpopper on FreeBSD. There are many ways to configure Qpopper. This guide covers configuring Qpopper to handle encrypted POP3 sessions over both TCP port 110 using the STLS method and TCP port 995 (the alternate port) with TLS/SSL. Authentication is done with the standard USER/PASS commands in conjunction with PAM. SASL, APOP, and unencrypted sessions are disabled in this configuration.

Why use Qpopper?

User Authentication:

There are three different authentication sources:

  1. native Kerberos 5
  2. separate POP user database contained in the /usr/local/etc/qpopper/popusers file
  3. Pluggable Authentication Modules (PAM)

PAM can be used to authenticate from many different sources, including /etc/passwd, LDAP, RADIUS, and Kerberos. FreeBSD 4.9 stores its PAM configuration in the /etc/pam.conf file. There is a separate entry for pop3 authentication.

For this Quickstart Guide, we are only going to address using PAM, TLS/SSL, and plaintext passwords to authenticate. TLS/SSL is mandatory. Since we will be allowing STARTTLS (STLS) on port 110 and the alternate port, TCP 995, we will be able to support a wide variety of POP3 e-mail clients without exposing usernames and passwords over the network.

Qpopper can be configured to run as a stand-alone daemon, or it can be configured to run through inetd. This guide uses inetd, because the stand-alone mode is not capable of supporting STLS on port 110 and TLS on port 995 simultaneously. This can only be done through inetd.

Caveats:

The goal of this guide is to get you started quickly with Qpopper. You can then start testing and modifying the configuration to meet your specific needs. For production use, you would need to consider the following:

Assumptions:



Step 1:  Preparing for Software Installation

To insure that you are starting with a secure base system, run cvsup on your ports collection. You may also need rebuild the OS itself using cvsup and other standard FreeBSD tools. In my case, I also compiled and installed a new kernel so that I could enable user quotas in the mail partition.

You will also need to create a directory for user bulletins. It should be readable but not writable for normal users:

bsd# mkdir /var/spool/bulls
bsd# ls -ald /var/spool/bulls
drwxr-xr-x  2 root  wheel  512 Mar 27 00:21 /var/spool/bulls


Step 2:  Installing Qpopper

Qpopper is installed from the FreeBSD ports collection, which is a very simple process. The current version at the time I wrote this was 4.0.5_1. We only need to modify the Makefile for our specific scenario, then run some make commands. Let us edit /usr/ports/mail/qpopper/Makefile, adding the following options so that the configuration arguments look like this:

CONFIGURE_ARGS= --enable-nonauth-file=${POPUSERS_FILE} \
                --without-gdbm \
                --enable-keep-temp-drop \
                --disable-update-abort \
                --enable-bulletins=/var/spool/bulls \
                --enable-log-login \
                --enable-new-bulls=3 \
                --enable-shy \
                --enable-timing \
                --enable-log-facility=LOG_MAIL \
                --with-openssl=/usr/bin/openssl \
                --with-pam=pop3

Note that TLS/SSL is enabled as well as PAM. A complete description of all the configuration arguments is located in the Qpopper Administrator's Guide.

Now we will go ahead and retrieve, configure, compile, and install the software. Here's how:

bsd# make WITHOUT_IPV6=yes WITHOUT_APOP=yes

bsd# make install WITHOUT_APOP=yes

bsd# make clean

Assuming there were no errors, the software is now installed. The server binary should be called /usr/local/libexec/qpopper. There should also be a qpopper manpage. Use the pkginfo command to verify that qpopper is now located in the package database:

bsd# pkg_info | grep qpopper
qpopper-4.0.5_1     Berkeley POP 3 server (now maintained by Qualcomm)

Qpopper runs as user "root". Go ahead and change the permissions on the executable:

bsd# cd /usr/local/libexec
bsd# chmod 550 qpopper
bsd# ls -lh qpopper
-r-xr-x---  1 root  wheel    119K Mar 26 14:23 qpopper

Note that qpopper is only 119 kilobytes in size!


Step 3: Create Qpopper Configuration Files

We need three separate configuration files in order to simultaneously support pop3s on port 995 and STLS on port 110. The configuration files will be placed in the /usr/local/etc/qpopper directory. Here they are:

/usr/local/etc/qpopper/TLS-995.conf:

# Qpopper Configuration File #1
# TCP 995 for those e-mail clients that can't handle STARTTLS (STLS)
 
set tls-support = alternate-port
set config-file = /usr/local/etc/qpopper/qpopper.conf

/usr/local/etc/qpopper/STLS-110.conf:

# Qpopper Configuration File #2
# Runs on TCP 110, uses STARTTLS (STLS) method
 
set tls-support = stls
set config-file = /usr/local/etc/qpopper/qpopper.conf

/usr/local/etc/qpopper/qpopper.conf:

# Qpopper Main Configuration File

set statistics
set downcase-user
set timeout = 180
 
set clear-text-password = tls
set tls-server-cert-file = /etc/mail/certs/pop3cert.pem
set tls-private-key-file = /etc/mail/certs/pop3key.pem

Permissions:

The config files in /usr/local/etc/qpopper/ should be mode 0440 and should be owned by pop:daemon:

bsd# chmod 0440 /usr/local/etc/qpopper/*
bsd# chown pop:daemon *.conf
bsd# ls -l
total 6
-r--r-----  1 pop  daemon  159 Mar 27 00:30 STLS-110.conf
-r--r-----  1 pop  daemon  190 Mar 27 00:30 STLS-995.conf
-r--r-----  1 pop  daemon    0 Mar 27 00:27 popusers
-r--r-----  1 pop  daemon    0 Mar 27 00:27 popusers.sample
-r--r-----  1 pop  daemon  230 Mar 27 00:31 qpopper.conf

On my system, there is a user named "pop" with uid=68, and a group named "daemon" with gid=1. I did not have to manually add these.


Step 4:  Setting Up TLS Keys and Certificates

Since we are setting up a TLS-enabled POP3 server, we need to make crypto keys and certificates. Without them, TLS/SSL will not work.

For this step, you will have to make a decision. You can get a "real" X.509 certificate signed by a Certificate Authority (CA), or you can create your own enterprise-wide CA and sign it yourself. If you are an ISP, you should buy a "real" certificate. If the POP3 server is only for use by your organization, a private (free) certificate may be good enough.

If you want to create your own CA and sign the POP3 server certificate yourself, follow these directions.

We will now generate the private SSL/TLS key for Qpopper. The key cannot be password protected, so you must immediately change its permissions to a restrictive mode.

bsd# cd /root/CA
bsd# openssl genrsa -out pop3key.pem 1024
Generating RSA private key, 1024 bit long modulus
................++++++
...............++++++
e is 65537 (0x10001)

bsd# chmod 0400 pop3key.pem

Now we can generate our Certificate Signing Request:

bsd# openssl req -new -key pop3key.pem -out pop3cert.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:TW
State or Province Name (full name) [Some-State]:Taipei County
Locality Name (eg, city) []:Nankang
Organization Name (eg, company) [Internet Widgits Pty Ltd]:VanEmery.Com
Organizational Unit Name (eg, section) []:Messaging
Common Name (eg, YOUR name) []:bsd.vanemery.com
Email Address []:mm@vanemery.com
 
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Note:  You need to use your server's fully qualified domain name (FQDN) in the Common Name field. If you do not do this, you will have many problems!

Now, you will need to send your Certificate Signing Request (pop3cert.csr) to a CA like Thawte Consulting, or you can sign it yourself with your own CA key. If you are going to do it yourself, then follow these steps:

bsd# cd /root/CA
bsd# openssl x509 -req -in pop3cert.csr -out pop3cert.pem -sha1 -CA my-ca.crt -CAkey my-ca.key -CAcreateserial -days 3650 
Signature ok
subject=/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
Getting CA Private Key
Enter pass phrase for my-ca.key:

bsd# chmod 0400 *
bsd# ls -l
total 12
-r--------  1 root  wheel   749 Mar 12 16:18 pop3cert.csr
-r--------  1 root  wheel  1216 Mar 12 16:23 pop3cert.pem
-r--------  1 root  wheel   887 Mar 12 16:10 pop3key.pem
-r--------  1 root  wheel  1789 Mar 12 15:12 my-ca.crt
-r--------  1 root  wheel  1743 Mar 12 15:07 my-ca.key
-r--------  1 root  wheel     3 Mar 12 16:23 my-ca.srl

To view the completed certficate:


bsd# openssl x509 -in pop3cert.pem -text -noout

Now, copy the signed certificate and private key to the proper directory:

bsd# cp -pv pop3*pem /etc/mail/certs
pop3key.pem -> /etc/mail/certs/pop3key.pem
pop3cert.pem -> /etc/mail/certs/pop3cert.pem
bsd# ls -l /etc/mail/certs
total 5
-r--------  1 root  wheel  1216 Mar 12 16:23 pop3cert.pem
-r--------  1 root  wheel   887 Mar 12 16:10 pop3key.pem

Caution!

Now that you are finished, you need to make backups of all the certificates and keys. CDs and floppies are good for this purpose. You may want to make paper copies, too. The certs and keys should then be locked up in a safe place.


Step 5:  Configure Inetd to Launch Qpopper

Since the POP3 server runs from inetd, you will need to make some configuration changes and then restart/start inetd. Make the following changes to /etc/inetd.conf:

#
# Qpopper pop3 server
#
pop3   stream  tcp  nowait  root  /usr/local/libexec/qpopper  qpopper -f /usr/local/etc/qpopper/STLS-110.conf
pop3s  stream  tcp  nowait  root  /usr/local/libexec/qpopper  qpopper -f /usr/local/etc/qpopper/TLS-995.conf

Make sure that any unnecessary services are commented out.

Now, we need to make sure that inetd starts automatically during system startup. If the statement inetd_enable="NO" is found in the /etc/rc.conf file, then remove it or comment it out like this:


#inetd_enable="NO"

Restart (or start) Inetd:

If inetd is already running, simply issue a "killall -HUP inetd" command. If inetd is not running, then start it manually:


bsd# /usr/sbin/inetd -wW

The -wW flags turn on TCP wrappers support. You can increase the security of servers started by inetd by configuring TCP wrappers.


Step 6:  Test POP3 Server Functionality:

Make sure that your server is listening on TCP port 110 (pop3) and 995 (pop3s):

bsd# netstat -p tcp -an
Active Internet connections (including servers)
Proto Recv-Q Send-Q  Local Address          Foreign Address        (state)
tcp4       0      0  *.587                  *.*                    LISTEN
tcp4       0      0  *.25                   *.*                    LISTEN
tcp4       0      0  *.995                  *.*                    LISTEN
tcp4       0      0  *.110                  *.*                    LISTEN

Add a local Unix test user account. For this example, I added an account with username="perry" and password="mason21". If this user does not need shell access, you can give the account the /sbin/nologin shell. It may also be a good idea to keep POP3-only user accounts in a specific range of UIDs and GIDs, like 2000-2999. Since we are using PAM, the Unix username/passwd will be the same as the POP3 username/password

Now, use the telnet command to test the server on port 110. Once you connect, you can issue POP3 commands and view the responses:

bsd# telnet bsd.vanemery.com 110
Trying 192.168.1.2...
Connected to bsd.vanemery.com.
Escape character is '^]'.
+OK ready
CAPA
+OK Capability list follows
TOP
USER
LOGIN-DELAY 0
EXPIRE 0
UIDL
RESP-CODES
AUTH-RESP-CODE
X-MANGLE
X-MACRO
X-LOCALTIME Fri, 26 Mar 2004 23:48:45 +0800
STLS
.
AUTH
+OK Supported SASL mechanisms:
X-NONE-SO-USE-APOP-OR-STLS
.
USER perry
-ERR [AUTH] You must use TLS/SSL or stronger authentication such as APOP to connect to this server
QUIT
+OK Pop server at bsd.vanemery.com signing off.
Connection closed by foreign host.

Now, use the openssl s_client utility to test the server on port 995. One you connect, you can issue POP3 commands and view the responses:

bsd# openssl s_client -connect bsd.vanemery.com:995
CONNECTED(00000003)
depth=0 /C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 /C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
verify error:num=27:certificate not trusted
verify return:1
depth=0 /C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Certificate chain
 0 s:/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
   i:/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Security/CN=VanEmery.Com IT Services/emailAddress=km@vanemery.com
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDVjCCAj4CAQEwDQYJKoZIhvcNAQEFBQAwgbQxCzAJBgNVBAYTAlRXMRYwFAYD
VQQIEw1UYWlwZWkgQ291bnR5MRAwDgYDVQQHEwdOYW5rYW5nMRUwEwYDVQQKEwxW
YW5FbWVyeS5Db20xGjAYBgNVBAsTEVNlY3VyaXR5IFNlcnZpY2VzMSEwHwYDVQQD
ExhWYW5FbWVyeS5Db20gSVQgU2VydmljZXMxJTAjBgkqhkiG9w0BCQEWFmtleW1h
c3RlckB2YW5lbWVyeS5jb20wHhcNMDQwMzEyMDgyMzQzWhcNMTQwMzEwMDgyMzQz
WjCBsDELMAkGA1UEBhMCVFcxFjAUBgNVBAgTDVRhaXBlaSBDb3VudHkxEDAOBgNV
BAcTB05hbmthbmcxFTATBgNVBAoTDFZhbkVtZXJ5LkNvbTEbMBkGA1UECxMSTWVz
c2FnaW5nIERpdmlzaW9uMRswGQYDVQQDExJic2Q0OS52YW5lbWVyeS5jb20xJjAk
BgkqhkiG9w0BCQEWF3Bvc3RtYXN0ZXJAdmFuZW1lcnkuY29tMIGfMA0GCSqGSIb3
DQEBAQUAA4GNADCBiQKBgQCwY9KsKlcaS+Cx9bfDu/Orq9APRZunPRgPsd8frddE
IG8p+c0VEfH4vajqA0mh/mxUD8V3QNRKMNiBha8oBhFbYi52xOgsqttv4eV48+Ak
FJXEjBxCp47hpoBKPuxCcInNcXyut3S3ahYEkbS8g5Yy61117tDnH97Nht038/Tz
zwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCGHDm234u0HhMdiYZxkRhiCzwcrcg1
Dhct+7ddPPGpIQE5rYCGgjy4e2KRFMQDpyCEhFtaivk4Iv6wV1gaWFPmlQTma0WC
5CYdbnNDJwHPOKpCpmjQGk4UGalTyA/OIMPquyomwofX0NlYP80pQ+qfA8OvqjsW
2vv/SGpHp7yImC+Cj0FVd3sYvo5aS8n+TE4e3lf6v2aHfBC4jsdp9YA4ryvJ+8io
eGRhob0oQANzNXbxn+bwzpVfsYWAdzt5E3f1tXArXgNoTAF4tQkYeC8iPsI+DN8t
u+EXgrI/z951nMs8mkoWQYAmPfGIeW0XVAKtRN5v2E1GGyI2EaeCuDw0
-----END CERTIFICATE-----
subject=/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Messaging/CN=bsd.vanemery.com/emailAddress=mm@vanemery.com
issuer=/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Security/CN=VanEmery.Com IT Services/emailAddress=km@vanemery.com
---
No client certificate CA names sent
---
SSL handshake has read 1020 bytes and written 340 bytes
---
New, TLSv1/SSLv3, Cipher is AES256-SHA
Server public key is 1024 bit
SSL-Session:
    Protocol  : TLSv1
    Cipher    : AES256-SHA
    Session-ID: 6AD169BABBFEBF8900B80292082A57DDD0D15B1AE1892B6CF5E092EAB43B7616
    Session-ID-ctx:
    Master-Key: 932F0FF6203C5299455558E8EF239D4D127E562F02044AEF87D89520B481136F4A99DDB24CB5763C3E0FB9F5765A2297
    Key-Arg   : None
    Start Time: 1080316206
    Timeout   : 300 (sec)
    Verify return code: 21 (unable to verify the first certificate)
---
+OK ready
CAPA
+OK Capability list follows
TOP
USER
LOGIN-DELAY 0
EXPIRE 0
UIDL
RESP-CODES
AUTH-RESP-CODE
X-MANGLE
X-MACRO
X-LOCALTIME Fri, 26 Mar 2004 23:50:18 +0800
.
AUTH
+OK Supported SASL mechanisms:
X-NONE-SO-USE-APOP-OR-STLS
.
USER perry
+OK Password required for perry.
PASS mason21
+OK perry has 13 visible messages (0 hidden) in 30603 octets.
STAT
+OK 13 30603
NOOP
+OK no big woop
LIST
+OK 13 visible messages (30603 octets)
1 1050
2 1019
3 1002
4 917
5 21998
6 925
7 944
8 943
9 361
10 361
11 361
12 361
13 361
.
QUIT
+OK Pop server at bsd.vanemery.com signing off.
closed

You will now want to test your TLS-enabled POP3 server from another host on your network. Make an account with the proper username, password, and server hostname/IP address. You will then need to configure the mail client for TLS connections to port 995 and/or port 110 with STLS. Configure the mail client to use the "plain text" authentication method, not APOP, AUTH, or SASL. Since the plaintext username and password are encrypted by TLS/SSL, they are not exposed to the network. While you are testing, you will also probably want to configure the mail client to leave the messages on the server.

When your client connects for the first time, you may get a warning if you signed your own certificates. This can usually be handled by viewing the certificate and then clicking a button that causes the e-mail client to trust the certificate. Now, you should be able to view your e-mail.

If you need to perform any debugging, running s_client and issuing the commands manually is a good method. Another good method is configuring and using fetchmail with the -vv option, which gives you a detailed account of what is happening during POP3 sessions.

E-mail Clients Tested:

This FreeBSD Qpopper installation was successfully tested with the following e-mail clients:

Log Files:

When testing, you will also want to look at your logs. Qpopper uses /var/log/maillog. This file is automatically rotated.





Final Notes:

Qpopper has lots of performance tuning and configuration options. You will have to read the Qpopper documentation and do some experimenting to configure the server perfectly for your environment. Using bulletins properly also takes some reading and testing.


More Information:






| Home | Protocols | POP3 |