POPFile 0.2.x on Mac OS X

I don't have the time right now to update the installation HOW-TO to version 0.21.0. However, you will find the instructions how to update popfile 0.20.x to 0.21.x written by Ken Edwards here. I will try to update these instructions for the new version in a few days time.

1. What is POPFile?

POPFile is an automatic mail classification tool. Once properly set up and trained, it will work in the background of your computer, scanning mail as it arrives and filing it however you wish. You can give it a simple job, like separating out junk e-mail, or a complicated one - like filing mail into a dozen folders. Think of it as a personal assistant for your inbox.

POPFile makes use of the BSD Subsystem of Mac OS X and you will need to know how to type a few commands in Terminal.app. Don't be afraid, however, it's very easy to set-up POPFile, and once installed all configuration will be done through a very well structured interface in the browser of your choice.

This HOW-TO assumes that you are running Mac OS X 10.3 or later and I have tested POPFile 0.2.x on this version of the Mac OS, only. There should be no problems running POPFile 0.2.x on Mac OS X 10.2.x, though.
However, I upgraded all my Macs to Panther by now, so please don't mail me with Jaguar-specific problems as I will not be able to reproduce them on my machines. Thank you.

I will cover the whole installation process as if installing POPFile for the first time. Steps that can be skipped when upgrading from version 0.1.x are marked accordingly. Please make sure you are logged into Mac OS X as a user with admin privileges.

2. Downloading

2.1 Apple Developer Tools

You will need the Apple Developer Tools to build the BerkelyDB database and the perl modules that are needed by POPFile 0.2.x. The Developer Tools are included with any retail version of Mac OS X 10.3. on CD 4 labeled "Mac OS X Xcode Tools". If you want to save some disk space do a customized install and select just the "Developer Tools Software", the "Mac OS X SDK" and the "BSD SDK".

2.2 POPFile

2.2 MIME-Base64 perl module

Upgraders may skip this step:
POPFile requires the MIME-Base64 perl module to be installed. However, Apple decided not to include this module in OS X. So, go to cpan.org and download the latest MIME-Base64 perl module to your computer.

2.3 Berkeley DB

The Berkeley DB database program is distributed by Sleepycat Software. Go to their download page and download the current Berkeley DB release (either with or without strong encryption, this doesn't matter for the POPFile installation).

2.4 BerkeleyDB perl module

In order to be able to interact with the Berkeley DB, POPFile needs the BerkeleyDB perl module. So, go to cpan.org and download the latest BerkeleyDB perl module to your computer as well.

3. Preparing to Install

3.1 Creating an install directory

Upgraders may skip this step:
I'd suggest you create a new directory in '/Library/' and name it "POPfile". (Note: make sure you are logged in as a user with admin privileges)

3.2 Unpacking your downloads

Simply navigate to your download folder and unpack the files you just downloaded. Four new folders will be created in your download folder:

3.3 Stopping you current POPFile installation (upgraders only)

Go to the POPFile configuration interface at http://127.0.0.1:8080 and click on 'Shutdown POPFile' to stop POPFile.

4. Installation

Please follow these steps exactely in the same order as I have arranged them. The installation will not work otherwise.

4.1 Installing the Apple Developer Tools

Install the Developer Tools first. See the hint in step 2.1 above on how to save some disk space.

Different ways of obtaining root privileges

Many of the following comands need to be executed with root privileges. If you did not activate the root account on your Mac you could use 'sudo' in front of these comands as in 'sudo make install'.
A much easier approach, however, is to become 'root' for a complete terminal session. Just type
sudo -s -H
once, enter you password and you will be root for as long as you keep the current terminal window open. I will assume that you did so from now on.

4.2 Installing the MIME-Base64 perl module

Upgraders may skip this step:
Installing the perl module should be very easy. Open a Terminal window, become root as described above and type 'cd '. Now drop the expanded folder onto the Terminal window and press 'enter'.

Once you have changed into the "MIME-Base64-2.21" folder type the following commands:

If all goes well - you should see a few message on the command line whether the installation worked or not - the perl module should now be installed

4.3 Installing the Berkely DB

Type 'cd ' again and drop the 'db-4.1.25' folder onto you terminal window. Press enter and type the following commands:


cd build_unix [enter]

../dist/configure [enter]

make [enter]

make install [enter]

After the installation has finished - hopefully without any error messages - type the followning:

When you take a look at the directory with the comand 'ls -la' you will notice that we just created a so called symbolic link:

The link 'BerkeleyDB' points to the actual directory 'BerkeleyDB.4.1' with its version number suffix. This has two advantages: You will be able to install the BerkeleyDB perl module in step 4.2 without having to adjust the paths in its 'config.in' file. What is more, you will be able to upgrade to future versions of the Berkeley DB without problems. All you will have to do is point the 'BerkeleyDB' link to the newer directory and all programs that depend on the BerkeleyDB will still be able to find the updated version.

4.4 Installing the BerkelyDB perl module

As of version 0.25 of the BerkeleyDB perl module, the 'config.in' file is broken. The author of the module told me that he will fix this in the next version. In the meantime, open the file 'config.in' in a text editor and make sure that these lines are uncommented:

INCLUDE	= /usr/local/BerkeleyDB/include
LIB	= /usr/local/BerkeleyDB/lib

Do the old 'cd ' & drop trick with the BerkeleyDB-0.25 folder, press enter and type the following:

4.5 Installing POPFile

Finally, the last and easiest step: Open the "popfile-0.2.x" folder and copy all files to '/Library/POPfile/'.

4.4 Testing your installation

A message telling you that POPFile is running should appear on the command line. To quit POPFile and regain control of the command line type 'ctrl c'.

POPFile is now installed. However, you'll probably want POPFile to start at boot time without the need to provide a password. So, there's just one more thing (pardon the pun):

If you're upgrading from POPFile 1.x you can skip the rest and start your new POPFile installation as described in step 5.

4.5 Installing the POPFile StartupItem

It's time to navigate to '/Library/StartupItems/'. Now either download this file which contains a complete startup item which you can unpack and place in '/Library/StartupItems/' and read on here or continue if you want to create the files yourself.

Special note to fink users:

If you used fink to install the MIME-Base64 perl module you will have to add the following lines to your '/Library/StartupItems/popfile/popfile' or automatic startup at system boot will fail:

. /etc/rc.common

#### begin export PERL5LIB for fink

if ( $?PERL5LIB ) then
   PERL5LIB="/sw/lib/perl5:$PERL5LIB"
   export PERL5LIB
else
   PERL5LIB="/sw/lib/perl5"
   export PERL5LIB
fi

#### end export PERL5LIB for fink

if [ "$1" == "start" ]

Thanks to Kevin Horton for this work-around.

Create a folder named 'popfile', open it and create a text file called 'StartupParameters.plist' which contains the following text:

Next comes the actual StartupItem. Create a second text file and call it 'popfile':

Now create a directory named 'Resources', open it and create another directory 'English.lproj'. The path to this directory should be:

The last file you'll need should be called 'Localizable.strings' and needs to be placed in the 'English.lproj' folder:

That's it! All that remains to be done is setting correct permissions for the StartupItem.

5. Setting Permissions

Type the following (remember to become root by typing 'sudo -s -H' first if you closed your terminal window in the meantime):


cd /Library/StartupItems [enter]

chown -R root.admin popfile [enter]

cd popfile/ [enter]

chmod 754 popfile [enter]

chmod 644 StartupParameters.plist [enter]

An alternative method of starting POPFile

If you would like to start POPFile at login (as opposed to system boot) so multiple users can have different buckets and settings, you might want to take a look at POPFile Startup. POPFile Startup will start the POPFile email proxy without any user interaction when the user logs in.

Note: Only users with Administrator privileges can use POPFile Startup. This is because POPFile Startup must use the 'sudo' command to run POPFile as root. Only users with Administrator privileges can run commands as root.

If you want to start up POPFile without rebooting just type this at the command prompt:

6. Configuring and Training POPFile

Open the browser of your choice and go to the POPFile configuration interface at http://127.0.0.1:8080. Start by reading the short introduction on training POPFile and enjoy your soon to be spam free mailbox.

Running POPFile 0.2.x on Mac OS X