Running POPFile 0.1.x on Mac OS X

30 October 2003 - POPFile 0.1x - Mac OS X 10.2 - artz-net.de home

The current HOW-TO for POPFile 0.22.x

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.

2. Downloading

2.1 POPFile

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

2.2 MIME-Base64 perl module

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 Apple Developer Tools

You will also need the Apple Developer Tools (a huge download of about 300MB) to build and install POPFile on your computer. However, if your Mac came with Mac OS X preinstalled, chances are that you already have the Developer Tools somewhere on your disks (look inside the Applications/Utilities folder for an installer called 'Install Developer Tools'). Be careful, though: do not try to install old Developer Tools for 10.1.x on 10.2.x.

3. Preparing to Install

3.1 Creating an install directory

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 use Stuffit Expander to unpack the files you just downloaded. Two new folders will be created in your download folder:

drwxr-xr-x 15 michael admin 510 Feb 18 17:49 MIME-Base64-2.16
drwxr-xr-x 14 michael admin 476 Feb 18 17:46 popfile-0.1x.x Folder

4. Installation

4.1 Installing the Apple Developer Tools

Double-click the Developer Tools installer and follow the usual installer routine. If you are short on disk space, I suggest you deselect the documentation and the example files and you will save about 350MB of disk space.

4.2 Installing the MIME-Base64 perl module

Installing the perl module should be very easy. Note, however, that it is important to do this step first, before you try to install and run POPFile. Open a Terminal window and type 'cd'. Now drop the expanded folder onto the Terminal window and press 'enter'.

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

sudo perl Makefile.PL [enter]
(enter your password) [enter]
sudo make [enter]
sudo make test [enter]
sudo make install [enter]

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 and you are ready to install POPFile.

4.3 Installing POPFile

Open the "popfile-0.1x.x" folder and copy all files to '/Library/POPfile/'. [Note: The next step is no longer neccessary as of popfile 0.18.1] Now open the file '/Library/POPfile/popfile.pl' in a text editor (TextEdit, BBEdit, pico etc.) and change the text on line 54:

Old: require v5.6.1;
New: require v5.6.0;

Save and close the file.

4.4 Testing your installation

You could now start up POPFile with the following command:

cd /Library/POPfile/ [enter]
sudo perl popfile.pl [enter]
(enter your password) [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'.

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

{
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':

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

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

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

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

/Library/StartupItems/popfile/Resources/English.lproj/

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">
<dict>
<key>Starting popfile</key>
<string>Starting popfile</string>
<key>Stopping popfile</key>
<string>Stopping popfile</string>
</dict>
</plist>

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

5. Setting Permissions

Open a Terminal window and type:

cd /Library/StartupItems [enter]
sudo chown -R root.admin popfile [enter]
(enter your password) [enter]
cd popfile/ [enter]
sudo chmod 754 popfile [enter]
sudo 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:

sudo /Library/StartupItems/popfile/popfile start [enter]
(enter your password) [enter]

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.

© 2003 - Michael Artz (web2006 at artz-net.de)
http://www.artz-net.de/popfile/