Running POPFile 0.22.x on Mac OS X

17 September 2006 - POPFile 0.22.x - Mac OS X 10.3 and 10.4 - home

Archive: The old HOW-TO for POPFile 0.1.x, The old HOW-TO for POPFile 0.20 - 0.21.x

POPFile instructions for Mac OS X in Finnish

This is the updated HOW-TO for running POPFile 0.22.x on Mac OS X.

If you are upgrading from an earlier version please pay special attention to steps 4.6 and 4.7.

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 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.

I have tested the complete procedure on two machines. While one had been running old versions of POPFile before, the other one was a fresh install. Just 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 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

Go to and download the latest universal "non-Windows" version.

2.3 wget

wget is a comand-line client for ftp and http. It is used by the Perl installer to fetch the module sources. Either go to OpenDarwin and download the most recent version from there or use the package from this site.

2.4 SQL-Lite

A precompiled version of the SQL-Lite database program is maintained by Michael Tsai. Go to his SQL-Lite page and download the current SQL-Lite release.

3. Preparing to Install

3.1 Creating an install directory

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 Stopping your current POPFile installation (upgraders only)

Go to the POPFile configuration interface at 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 wget

wget comes in a standard Apple installer package. Just unpack the archive, double click the installer package and follow the instructions. After the installation is finished open a new terminal window, switch to 'root' (see tip above) and type the following:

cd /usr/local/bin/ [enter]
ln -s /opt/local/bin/wget wget [enter]

4.3 Setting 'ftp passive'

Once you have installed wget it's time to adjust an environment variable of your shell program. Since with Mac OS X 10.3 you are most likely using a bash shell you will need to add a line to the file .bashrc in root's home directory:

cd [enter]
echo 'export FTP_PASSIVE=1' >> .bashrc [enter]

[I had missed the '=1' in earlier versions. Thanks to Jos Jansen for the correction.]

4.3 Configuring the CPAN shell

We will be using the built-in installation utility for modules that comes with Perl. This utility, the so-called CPAN shell, downloads, unpacks, compiles and installs perl modules all in one step. To configure the CPAN shell either type

perl -MCPAN -e shell [enter]

and fill in the information the setup program asks for, or download (ctrl-click and save) this text file which is a working configuration file from my system. To install this file, type:

cp /path-to-downloadfolder/ /System/Library/Perl/5.8.1/CPAN/ [enter]

Of course, you will have to replace path-to-downloadfolder with a real path on your system. The easiest way to do that is to type 'cd ' and than drop the file '' onto your Terminal window.

4.4 Installing the perl modules

Now that everything is configured and prepared comes the easy and fun part of the installation:

perl -MCPAN -e shell [enter]

cpan shell -- CPAN exploration and modules installation (v1.76)
ReadLine support available (try 'install Bundle::CPAN')


The prompt you see is the CPAN shell prompt. It's now ready to install. Just paste the following lines into the CPAN shell - one at a time - sit back and watch the automatic installation process (your computer has to be connected to the internet):

install DBI   
install MIME::Base64
install MIME::QuotedPrint   
install Date::Parse   
install HTML::Template   
install HTML::Tagset   
install DBD::SQLite   
install M/MS/MSERGEANT/DBD-SQLite-0.31.tar.gz  
install DBD::SQLite2

If you see something like this during the installation make sure you type 'Y' to be able to continue the installation:

To upgrade a database, download and install both sqlite 2.x and 3.x from and issue:

  sqlite OLD.DB .dump | sqlite3 NEW.DB

DBD::SQLite will NOT automatically upgrade a database for you, and using
this version against an old SQLite database WILL lead to database

Continue? [N] Y
Checking if your kit is complete...
Looks good

Once your're through installing all the modules just type 'quit' to leave the CPAN shell.

4.5 Installing SQL-Lite

Mount the disk-image you downloaded earlier and type the following at the command prompt:

cp /Volumes/SQLite-2.8.13/libsqlite.a /usr/local/lib/
cp /Volumes/SQLite-2.8.13/sqlite /usr/local/bin
cp /Volumes/SQLite-2.8.13/sqlite.h /usr/local/include/

That's it.

4.6 Installing POPFile

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

Important: If you are upgrading from an earlier version please make sure to merge the new files into your existing installation in order to preserve all database files and settings.

4.7 Testing (or upgrading) your installation

You should now start up POPFile with the following command:

cd /Library/POPfile/ [enter]
perl [enter]

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'.

Important: If you are upgrading your installation POPFile will now automatically convert your old database files to SQL-Lite. You must perform this step manually as it will not work from within the startup-item.

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):

4.8 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 at step "5. Setting Permissions" or continue if you want to create the files yourself.

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

Description     = "POPfile mail filter proxy";
Provides        = ("popfile");
Requires        = ("Network");
Uses            = ("Disks", "Network Time", "IPServices");
OrderPreference = "Last";
Messages =
start = "Starting popfile";
stop  = "Stopping popfile";


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

# POPfile - startup script
# For this to work POPfile should be in /Library/POPfile
. /etc/rc.common

if [ "$1" == "start" ]
	pid=$( ps -auxww | grep | grep -v grep | awk '{ print $2 }' )
	if ! [ $pid ]; then
		ConsoleMessage "Starting POPfile POP mail proxy"
		cd /Library/POPfile
		perl > /dev/null 2>&1 &
elif [ "$1" == "stop" ]
	pid=$( ps -auxww | grep | grep -v grep | awk '{ print $2 }' )
	if [ $pid ]; then  
		ConsoleMessage "Stopping POPfile mail proxy"	
		kill -6 $pid

elif [ "$1" == "restart" ]
	pid=$( ps -auxww | grep | grep -v grep | awk '{ print $2 }' )
        ConsoleMessage "Restarting POPfile mail proxy"
        kill -HUP $pid
		cd /Library/POPfile
		perl > /dev/null 2>&1 &

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:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM " file://localhost/System/Library/DTDs/PropertyList.dtd" ; ;>
<plist version="0.9">
<key>Starting popfile</key>
<string>Starting popfile</string>
<key>Stopping popfile</key>
<string>Stopping popfile</string>

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]

You're done! POPFile should now always start at boot time.

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:

/Library/StartupItems/popfile/popfile start [enter]

6. Configuring and Training POPFile

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

Valid HTML 4.0.1 - Valid CSS

© 2006 - Michael Artz (web2006 at