Quickstart Guide - Qpopper on FreeBSD |
| Home | Protocols | POP3 | |
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.
There are three different authentication sources:
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.
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:
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
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!
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
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.
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 []:[email protected] 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/[email protected] 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.
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"
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.
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/[email protected]
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/[email protected]
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/[email protected]
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/[email protected]
i:/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Security/CN=VanEmery.Com IT Services/[email protected]
---
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/[email protected]
issuer=/C=TW/ST=Taipei County/L=Nankang/O=VanEmery.Com/OU=Security/CN=VanEmery.Com IT Services/[email protected]
---
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.
This FreeBSD Qpopper installation was successfully tested with the following e-mail clients:
When testing, you will also want to look at your logs. Qpopper uses /var/log/maillog. This file is automatically rotated.
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.