• Welcome
• History
• Installation
• Configuration
• Source
• Help

Installation Procedure

Tested Environments

I developed this solution under the following environment:

• Custom-built Intel Pentium III 450MHz with 128M RAM
• Red Hat Linux version 7.2 (Enigma)
• postfix version 2.0.13 -- SMTP daemon
• vm-pop3d version 1.1.6 -- POP3 daemon
• iptables version 1.2.3 -- Local firewall service
• syslogd version 1.4.1 -- System log daemon
• logrotate version 3.5.9 -- Log file rotation utility
• apache version 2.0.48 -- HTTP daemon (for the HTML reports available from popAuth3's data files)

I am currently using this solution under the following environment:

• Multi-server mail handling scenario (distinct mail gateway; mail policy; mail storage and webmail; and database servers)
• RHEL/CentOS version 4.2 Linux
• postfix version 2.2.4
• courier-imap version 4.0.3.20050702 -- POP3, IMAP, POP3-SSL, IMAP-SSL daemon

At this time, I cannot vouch for whether this solution will work under any other environments, including differing version numbers of the listed programs. If you find success using different modules or versions, please let me know (you can find my obfuscated e-mail address below).

Installation (with a little more History)

I used the following process to install the initial development environment. If you have naver before set up a mail server, you can use this as a walk-through if you wish to duplicate my (functional) environment. However, if you're a seasoned professional and you don't need to read the babbling utterance of a then-amateur, please skip ahead to the popAuth3 installation procedure.

Linux

As my first-ever Linux installation, I did my best to install it as a simple server. I used MS-DOS 6's FDISK utility to wipe the partition tables before dropping in Disk 1 of the Red Hat Enigma ISO distribution and rebooting. Using the installation GUI was simple, but I'll admit that I ended up installing far more than was necessary. Even today, I hope to fully rebuild this machine but I'm left with the problem that it's a production box now. I haven't decided on the best technique to replace the machine without losing mail (nor have I spent much time thinking about it). It's a toss-up against the logic of, "if it ain't broke, don't fix it." The fact is, the mail server is doing everything it needs to do, just fine.

postfix

I believe postfix was near version 1.1.10 when I first encountered it. Installation was relatively painless following the accompanying documentation. I accepted the defaults in all cases. Obviously, I have upgraded postfix -- and my entire network, for that matter -- several times since then. Fortunately, upgrades have been painless thanks to the care taken by the postfix documentation authors. For comprehensive installation instructions, I recommend you read the INSTALL file that comes with the postfix source.

It is worth noting that I have moved the entire collection of postfix regexp/pcre and related .db files into a sub-directory called /etc/postfix/data/. At the very least, you need this directory for popAuth3's main RBL cache file -- particularly if you would like to use the accompanying HTML report tools. So that you can move this file anywhere you like, I have created related variables in the popAuth3 source that enable you to specify where your data files are stored, separate from the remaining postfix configuration files.

You must note that this configuration dictates using smtpd_delay_reject = no in /etc/postfix/main.cf. In other words, reject immediately instead of waiting for postfix's smtpd_recipient_restrictions, as is so common amongst postfix users. In some years of watching for it, I have found that there aren't enough "broken SMTP clients out there" to truly necessitate this delay. By following my technique, popAuth3 is able to perform its duties sooner in the SMTP sequence, thus heading off the "tons of garbage" that would otherwise be sent to syslog. I haven't yet established whether smtpd_delay_reject = no is mandatory for popAuth3 to work in all cases, but I very highly recommend using it instead of smtpd_delay_reject = yes.

vm-pop3d

vm-pop3d was at version 1.1.6 when I first found it and it hasn't changed since. I don't know whether development has stopped on it (the development version 1.1.7 has been in development for at least a couple years), but frankly that doesn't matter. vm-pop3d does everything I needed it to for this scenario. As is typical for me, I accepted the defaults during configuration and installed it verbatim per the recommendations in the included INSTALL text file.

Note that you MUST alter the vm-pop3d source (and recompile) in order for it to work with either popauth or my version, popAuth3! This is because vm-pop3d normally splits user authentication logging across two lines, and popauth only receives those lines FIFO -- one at a time. Check my source code listing for details.

popAuth3

I originally followed Stephen McHenry's instructions to the 'T' and installed his version of popauth (based on Harlann Stenn's popauth2) into /usr/local/sbin/. My version, popAuth3, requires a different installation procedure because it deals with more files and requires very specific output from your MTA to perform its services. The updated installation procedure is as follows (copied and adapted from Stephen McHenry's installation procedure):

1. Get postfix installed and working.
2. Get your choice of a POP daemon installed and working.
3. Get iptables configured and running.
4. Create the following directories for popAuth3's use:
   mkdir /var/spool/popauth/
mkdir /var/spool/popauth/authenticated/
mkdir /var/spool/popauth/fishers/
mkdir /etc/postfix/data/
5. Create a FIFO for popauth in /var/adm/ (create this directory if it does not exist, which was the case with me):
   mkdir /var/adm/
mkfifo /var/adm/popauth.fifo
chmod 0600 /var/adm/popauth.fifo
6. Update /etc/syslog.conf to copy mail log messages to the new popauth.fifo FIFO:
   vim /etc/syslog.conf
Look for:
   mail.* /var/log/maillog
Add IMMEDIATELY ABOVE this line:
   mail.info |/var/adm/popauth.fifo
7. If using SELinux, you must update the local security policy to grant syslog permission to write to this FIFO.
   execute: yum install selinux-policy-targeted-sources selinux-policy-strict-sources
   execute: yum install policycoreutils
   execute: vim /etc/selinux/targeted/src/policy/domains/program/syslogd.te
   add at the end of this file: allow syslogd_t var_t:fifo_file { read write };
   and: allow syslogd_t var_t:fifo_file ioctl;
   save the file, then execute: cd /etc/selinux/targeted/src/policy
   execute: make load
8. Restart syslogd for the changes to take effect:
   service syslog restart
   or: kill -s SIGHUP `cat /var/run/syslogd.pid`
9. Initialize the relay authentication file for postfix's use (in the appropriate directory; mine is located in /etc/postfix/data/ but this example uses /etc/postfix/ because it is more common):
   touch /etc/postfix/data/popauth_checks
postmap /etc/postfix/data/popauth_checks
10. If using a POP daemon other than vm-pop3d with the prescribed code alteration listed below, you must alter the popAuth3 source to properly detect user POP authentications. Refer to the check_triggers() function and replace the regular expression line following # Look for a POP authentication. You will have to become familiar with regular expressions (regexp) -- if you aren't already -- in order to make this change. If you need help with this, please submit the following to me (e-mail address is below), unaltered, and someone will try to help (time permitting). Please do not expect a very fast answer, and understand that a solution may require altering the source of your POP daemon -- particularly if the necessary authentication data is reported across multiple lines.
    1. The name, version, and a download URL for the POP daemon you are using (source preferred to binaries).
    2. The EXACT syslog line that appears in /var/log/maillog when your users authenticate a POP session. Note that, if your POP daemon does not log the user's name, domain, IP address, and authentication result on a single line, you will have to either use a different POP daemon, or alter its source.
11. Copy the popAuth3 source file to /usr/local/sbin/ (or anywhere you see appropriate).
12. Add a startup command to /etc/rc.local that will start the popAuth3 daemon automatically when your machine boots up:
    vim /etc/rc.local
    Add anywhere:
    /usr/local/sbin/popauth &
13. Start the popAuth3 daemon by hand unless you plan to reboot your machine:
    /usr/local/sbin/popauth &
14. Modify /etc/postfix/main.cf to enable your POP-authenticated users to relay mail. See the full version of main.cf that I use below for a complete reference of this configuration that does not put "everything" into smtp_recipient_restrictions.
    Add this variable above your smtpd_*_restrictions classes:
    popauth_checks = hash:/etc/postfix/popauth_checks
    
    Add to the smtpd_client_restrictions, smtpd_sender_restrictions, and smtpd_recipient_restrictions classes (not mandatory, but it helps your users relay if they accidentally get themselves black-listed -- hey, user-error happens), or at least to smtpd_recipient_restrictions:
    check_client_access $popauth_checks
15. Update your various postfix data files to conform to the regular expressions listed in the popAuth3 source for the automatic detection of various events. If you have already been using postfix for a while and you have already established many rejection rules in the various data files, then this may be the longest part of your popAuth3 installation. The popAuth3 regular expressions look for very specific text patterns from syslog to detect the behaviors it is looking for. If your rejection messages do not fit these patterns exactly, then popAuth3 will never trigger the appropriate event handlers. Therefore, it is necessary to alter your data files such that the rejection messages match the appropriate patterns that popAuth3 is looking for. On the other hand, if your rejection messages conform to an invariable standard, but one that can be matched by regular expressions, please feel free to update the popAuth3 source to match them, instead. If you'd rather not deal with the regular expressions, then please make the following changes to your postfix data files, based on these listed events:
    1. RBL Rejections:
       No changes are necessary, except: do not change the default postfix RBL rejection message template.
       
       popAuth3 looks for reject messages like: 554 Service unavailable; Client host [123.123.123.123] blocked using some.rbl.tld; Some RBL authority lookup or explaination;
    2. Repeated connection attempts by black-listed IPs:
       No changes are necessary; this is handled internally by popAuth3 (which is what triggers automatic null-routing).
       
       popAuth3 looks for reject messages like: 554 <RDNS-lookup-name[123.123.123.123]>: Client host rejected: Your IP address has been blacklisted by some.rbl.tld. Visit their website or write <postmaster> to argue. Some RBL authority lookup or explaination;
    3. Sender e-mail address forgery (requires implementation of the "freemail_checks" validation technique -- I lost the URL to the original author and documentation of this technique. I'm certain I encountered this How-To on the mailing.postfix.users newsgroup, but that was a long time ago.):
       Add these classes and variables to the variable list above your smtpd_*_restrictions classes:
       smtpd_restriction_classes = sender_checks
sender_checks = check_client_access hash:/etc/postfix/sender_checks, reject
freemail_checks = hash:/etc/postfix/freemail_checks
       
       Add this to your smtpd_sender_restrictions class (see the sample main.cf file below for proper placement):
       check_sender_access $freemail_checks
       
       Create /etc/postfix/freemail_checks and /etc/postfix/sender_checks to include a list of the free e-mail providers whom you wish to validate RDNS lookups against:
       See the freemail_checks and sender_checks files listed below for a live implementation of this technique (local names and IP Addresses have been substituted).
       
       popAuth3 looks for reject messages like: 554 <fake@freemail-provider.tld>: Sender address rejected: Access denied; from=<fake@freemail-provider.tld> proto=SMTP helo=<usually-fake>
    4. Recipient e-mail address forgery (blocks known spammer and virus/worm e-mail attempts):
       Add this variable to the variable list above your smtpd_*_restrictions classes:
       recipient_checks = pcre:/etc/postfix/recipient_checks
       
       Add this to your smtpd_recipient_restrictions class (see the sample main.cf file below for proper placement):
       check_recipient_access $recipient_checks
       
       popAuth3 looks for reject messages like: 554 <info@domain1.tld>: Recipient address rejected: Access denied; from=<fake@somedomain.tld> to=<info@domain1.tld> proto=SMTP helo=<usually-fake>
    5. EHLO/HELO forgery (prevent others from claiming they are part of your domain name(s) and IP Address(es)):
       Add this variable to the variable list above your smtpd_*_restrictions classes:
       helo_checks = hash:/etc/postfix/helo_checks
       
       Add this to your smtpd_helo_restrictions class (see the sample main.cf file below for proper placement):
       check_helo_access $helo_checks
       
       Add your list of hosted domains and IP addresses to the /etc/postfix/helo_checks file as the example below illustrates. Note that the exact text of the rejection message, excluding the actual domain names, must match.
       
       popAuth3 looks for reject messages like: 554 <123.123.123.123>: Helo command rejected: Your machine is not part of this network. Forgery is not tolerated here.; proto=SMTP helo=<123.123.123.123>
    6. Bad local recipients (prevents others from repeatedly guessing e-mail addresses):
       Add these lines near the top (or where you see fit) of your /etc/postfix/main.cf file:
       soft_bounce = no
unknown_local_recipient_reject_code = 550
       
       Be sure your local_recipient_maps file is up-to-date at all times. This is relatively easy to accomplish if you map your local_recipient_maps file to the virtual_mailbox_maps file with these three lines:
       user_database = hash:/etc/postfix/data/vmailbox
virtual_mailbox_maps = $user_database
local_recipient_maps = $user_database
       
       popAuth3 looks for reject messages like: 550 <fake@domain1.tld>: User unknown in local recipient table; from=<> to=<fake@domain1.tld> proto=ESMTP helo=<usually-fake>
    7. Unauthorized relay attempts:
       No change is necessary. Just be sure your overall postfix configuration rejects unauthorized relay attempts with the stock rejection message, "Relay access denied".
       
       popAuth3 looks for reject messages like: 554 <local.part@domain1.tld>: Relay access denied; from=<user@domain1.tld> to=<local.part@domain1.tld> proto=SMTP helo=<usually-fake>
16. OPTIONAL (but very highly recommended): Install the popAuth3 log file rotation script to /etc/logrotate.d/. If your system does not use logrotate, you should come up with an appropriate mechanism to rotate the popauth.log log file because it will grow endlessly. If unchecked, it will fill up your HDD.
17. OPTIONAL: Install the popAuth3 report scripts. The reports are written for an HTML application, so you will need an http daemon installed. I choose to use Apache, but you are welcome to use anything from which you can run perl scripts.
    1. Get your http daemon installed and working (particularly, be sure it can run perl scripts).
    2. Set up a path for your report scripts. I very highly recommend securing this path from external access (e.g.: in an ACL-protected /var/www/vhosts/com-domain1-tld/admin/ folder). For example, if using Apache, set up a .htaccess file in the same folder that you copy these files (if you don't understand this file, please refer to the Apache documentation):
       AuthType Basic
AuthName "Mail Server Administration"
AuthUserFile /etc/www/auth/com-domain1-mail/passwd
Require valid-user
       
       Be sure to set up that passwd file that is referenced on the AuthUserFile line. For example:
       mkdir /etc/www/
mkdir /etc/www/auth/
mkdir /etc/www/auth/com-domain1-mail/
htpasswd -bc /etc/www/auth/com-domain1-mail/passwd MailAdmin myP@ssword1234
    3. Copy the report source files (all of the *.pl files listed on the Source page as popAuth3 report files) into your secured directory.
    4. Copy the related Cascading Style Sheet files (all of the *.css files listed below) into a /css/ directory for your web site (e.g.: /var/www/vhosts/com-domain1-tld/css/). Alternatively, you can copy the *.css files into the same directory as the *.pl files as long as you update the *.pl source to output the correct path to the *.css files.
    5. If you want to be able to delete cache entries from your browser:
       1. Make the /etc/postfix/data/ directory world-writable so you can edit the rbl_cache file from a web browser:
          chmod o+w /etc/postfix/data
chmod o+w /etc/postfix/data/rbl_cache
       2. Make sure popAuth3 is writing to /etc/postfix/data/rbl_cache by double-checking the path variables in the source (if you closely follow the installation procedure listed above, and leave these variables unchanged when you first install popAuth3, there should be no need for this double-check).
18. OPTIONAL: Install the poplog script for easy monitoring of live popAuth3 activity (just run poplog any time you want to sit and watch popAuth3 do its work -- or catch bugs). Copy poplog to the same directory to which you copied popAuth3 (e.g.: /usr/local/sbin/) and make it executable:
    chmod ug+x /usr/local/sbin/poplog

iptables

The version of RH Linux I installed automatically used ipchains by default, but it also installed iptables anyway. Because iptables is generally the preferred of the two firewalls today, I switched from ipchains to iptables and programmed popAuth3 to match. If you are a die-hard ipchains user, you will have to alter the popAuth3 source to work with your configuration. A firewall that can be updated dynamically via script is necessary for popAuth3 to function unless you edit the source and disable the automatic null-routing facility. Of course, if you don't want the automatic null-routing, then you should consider the simpler popauth and not my version.

Apache

I have written a few report scripts for popAuth3 that are designed to help you monitor what is going on with your mail server. If you prefer to fire-and-forget, then you don't need these reports and you won't need to put an HTTP daemon on your mail server. Red Hat Linux 7.2 came with an earlier httpd version 1.3-something. I have since upgraded to version 2 for no better reason than to gain the experience of upgrading more Linux modules. You are welcome to use any HTTP daemon you like, or none at all. Apache is not necessary to run popAuth3, unless you want to use the HTML reports.