Using POPFile on Mac OS X Platforms

POPFile v1.1.0 comes with the first official Mac OS X installer! You can now install POPFile on your Mac easily. POPFile v1.1.3 is compatible with Mac OS X 10.10 (Yosemite).

System Requirements

You'll need several things to get started with POPFile on Mac OS X.

  • Mac OS X 10.3.9 or later.
  • The latest POPFile release.
    Note: there are three versions of Mac OS X installer. One is for Mac OS X 10.7 (Lion), one is for Mac OS X 10.6 (Snow Leopard) and the other is for older versions of Mac OS X.
  • An e-mail account that uses the POP3 protocol (most accounts do, although you can't use POPFile with web-based services like Hotmail and Yahoo! Mail without extra software. See Configuring Proxies & Firewalls).
  • Approximately 12.2MB free disk space is required for the default installation created by the Mac OS X installer.
  • POPFile itself occupies about 3.8MB.
  • POPFile is written in Perl and requires some extra Perl modules so the installer installs the modules which occupies approximately 4.4MB. These modules are compiled in the Universal binary format, which means that POPFile will run natively on both PPC and Intel Macs.
  • The installer installs the 'Nihongo' parser (Kakasi) used to analyse the Japanese text.
  • The installer also installs XMLRPC module, NNTP/SMTP proxies and IMAP module.
  • The SSL Support is no longer an option. POPFile installer will install the modules which are needed to use SSL connections.
  • The word lists (called the corpus) used to classify your email will take some additional space depending on how much mail you use to train POPFile and how many buckets you create. POPFile keeps a temporary copy of recent mail (the Message History) for a few days to make it easy to correct any classification errors so some extra space is required for these recent messages. For some users only a few extra MB will be sufficient for the corpus and Message History, for others an additional 100 MB may be required.

Installation

  1. Download the Mac OS X installer from the POPFile Download Page.
  2. Run POPFile-x.x.x.pkg and follow the installation instructions.
  3. POPFile will be installed in /Library/POPFile/ and it will be automatically launched in background.
    Important note: Nothing will appear on your screen! To check if it's running correctly, read the “Accessing POPFile” section below.
  4. Configure buckets. See Bucket Setup.
    Important note: The Mac OS X installer does not create any bucket on your installation unlike the Windows installer. You need to create at least two buckets before using it.
  5. Configure your email client. See Configuring Specific Mail Clients.

Accessing POPFile

  • POPFile doesn't have a traditional interface like most programs - you access it through your web browser. Don't worry - unless you say otherwise, no-one outside your machine can access it.
  • If you get an error message, check that POPFile is really running, and that you have the port number correct (it should be 8080, but if you changed it, you'll also need to change that in the web address you're going to.)

Utility scripts included in the installer package

The installer package includes several utility scripts written in AppleScript. You can copy them to your hard drive.

  • start-popfile - Launch POPFile (in background). Requires root privilege.
  • stop-popfile - Stop POPFile. Requires root privilege.
  • open-popfile-ui - Open POPFile UI with your default web browser.
  • start-popfile-with-console - Lanuch POPFile in the Terminal.app. Useful for debugging.
  • custom-data-folder - Choose custom data folder and run POPFile using the chosen data folder.
  • uninstall-popfile - Remove POPFile program and data files (corpus and configuration files) from your Mac.

Uninstalling

  1. Run the 'uninstall-popfile' script mentioned above.
    Note: The uninstaller will remove not only POPFile program but also the corpus and configuration files. If you want to use them later, please backup them before uninstalling.

Installing POPfile MANUALLY on Mac OS X 10.4.x (Tiger) or later

This procedure shows you how to install POPfile on Mac OS X 10.4.x or later systems, and how to create a startup item that will start POPfile each time you reboot the system.

As of Mac OS X 10.4, Mac OS X comes with Perl and SQLite3 installed. So you'll simply need to install Xcode, a few Perl library packages, and a startup item.

To run POPfile in Mac OS X 10.4.x or later, you'll need to install:

  • Apple's Xcode developer tools — to compile and install some Perl library packages
  • Perl library packages — that POPfile uses to classify email
  • POPfile startup item — to automatically start POPfile whenever you restart your computer

Note: Because setting up CPAN, a Perl package manager, or Fink, another package manager, on a virgin system can complicate matters, we'll stick with the source and do it the old-school way to avoid complications.

Note: To edit scripts or configuration files, use a plain text editor (like the command-line editor,vi, or the GUI editor TextWrangler). Make sure the text file content is plain text.

TIP: On the command line, ~ means “your home directory”. So ~/Desktop/packages means /Users/yourusername/Desktop/packages.

Step By Step Instructions

NOTE: You should be logged into an administrator account for this procedure.

Installing the system requirements

  1. Install Xcode from the CD/DVD that came with your Mac. You may also download it from here: Apple Xcode Web Page
  2. Download the cross-platform version of POPFile from here: Cross-Platform POPfile
  3. Download these Perl library packages (from the CPAN Web Site) and place them all into a folder on your desktop named “packages”:
  4. Install each of the Perl library packages you downloaded in the previous step:
    1. Open a terminal window if one is not already open.
    2. Enter the command to change the working directory to the “packages” folder on your desktop:
      cd ~/Desktop/packages
    3. Enter the command to expand the package (where name is the name of the package):
      tar xzvf name.tar.gz
    4. Enter the command to change the working directory to the expanded package folder (where name is the name of the expanded package folder):
      cd name
    5. Enter the command to build the GCC make file from the Perl make file:
      perl MakeFile.PL
    6. Enter the command to compile the project:
      make


      Note: If you compile any of these packages and it outputs an error starting out with something like: Can't locate DBD/SQLite2.pm in @INC, that means that package depends on other Perl library packages. The dependency package name is right after the word “locate” (in this example, it is DBD::SQLite2).

    7. Enter the command to install the library package into your system:
      sudo make install

Installing POPFile

  1. Enter the command to create a folder to hold POPfile (we suggest ~/Library/POPfile):
    mkdir ~/Library/POPfile


    Note: While this folder can reside anywhere, we suggest you create it somewhere in your home directory so that if you back up your home directory, POPfile gets backed up as well. We assume you have used the location ~/Library/POPfile for the rest of this procedure.

  2. Copy or move the POPfile ZIP archive into ~/Library/POPfile folder you just created.
  3. Expand the POPfile ZIP archive archive in the ~/Library/POPfile folder. You should now have a bunch of files in ~/Library/POPfile - one of which is popfile.pl.
    Note: If the POPfile ZIP archive expands into a sub-folder in ~/Library/POPfile, move all items into ~/Library/POPfile and get rid of the sub-folder.

Test your POPfile installation

  1. Open a terminal window if one is not already open.
  2. Enter the command to change the working directory to the ~/Library/POPfile folder:
    cd ~/Library/POPfile
  3. Enter the command to start POPfile manually:
    sudo perl popfile.pl
  4. Watch the output in the terminal. If POPfile is installed properly, you should not see any errors.
    Note: If you start POPfile and it outputs an error starting out with something like: Can't locate DBD/SQLite2.pm in @INC, that means you still need to install one or more Perl library packages. The package name is right after the word “locate” (in this example, the Perl library package you need to install is DBD::SQLite2).
    Note 2: If you see following error,
    Couldn't start the pop3 proxy because POPFile could not bind to the
    listen port 110. This could be because there is another service
    using that port or because you do not have the right privileges on
    your system (On Unix systems this can happen if you are not root
    and the port you specified is less than 1024). 

    you may need to run POPFile as root (use sudo) or change the POP3 and the UI port greater than 1024. To change the port settings, use following command (this command will change the POP3 port to 1110 and the UI port to 9090):

    perl popfile.pl --set pop3_port=1110 --set html_port=9090

    For more information about the command-line options, see POPFile Command Line and Advanced Options

  1. Type Control-C into the terminal window to stop POPfile and exit to the command prompt.

At this point POPfile is installed properly, but will not start up automatically every time you reboot.

Creating a POPfile Startup Item for Mac OS X 10.10 (Yosemite)

  1. Create the Mac OS X POPFile LaunchDaemons file:
  2. Create a plain text file named "popfile.plist" in the /Library/LaunchDaeons folder with this content:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    	<key>Disabled</key>
    	<false />
    	<key>EnvironmentVariables</key>
    	<dict>
    		<key>ITAIJIDICTPATH</key>
    		<string>/Library/POPFile/kakasi/itaijidict</string>
    		<key>KANWADICTPATH</key>
    		<string>/Library/POPFile/kakasi/kanwadict</string>
    		<key>MECABRC</key>
    		<string>/Library/POPFile/mecab/etc/mecabrc</string>
    		<key>POPFILE_ROOT</key>
    		<string>/Library/POPFile/</string>
    		<key>POPFILE_USER</key>
    		<string>/Library/POPFile/</string>
    		<key>VERSIONER_PERL_VERSION</key>
    		<string>5.18</string>
    	</dict>
    	<key>StandardErrorPath</key>
    	<string>/Library/Logs/POPFile/error.log</string>
    	<key>StandardOutPath</key>
    	<string>/Library/Logs/POPFile/console.log</string>
    	<key>Label</key>
    	<string>org.getpopfile.popfile</string>
    	<key>KeepAlive</key>
    	<false />
    	<key>RunAtLoad</key>
    	<true />
    	<key>ProgramArguments</key>
    	<array>
    		<string>/usr/bin/perl</string>
    		<string>-I/Library/POPFile/lib</string>
    		<string>/Library/POPFile/popfile.pl</string>
    		<string>-logger_logdir</string>
    		<string>/Library/Logs/POPFile/</string>
    	</array>
    </dict>
    </plist>
    
  3. In a terminal window, enter these commands:
    cd /Library/LaunchDaemons
    sudo chown root:wheel popfile.plist
    sudo chmod 644 popfile.plist
    sudo launchctl load /Library/LaunchDaemons/popfile.plist
    
  4. Finally, to start up POPFile without rebooting enter this terminal command:
    sudo launchctl start org.getpopfile.popfile

Creating a POPfile Startup Item for Mac OS X 10.9 (Mavericks or before)

NOTE: You should be logged into an administrator account for this procedure.

  1. Create the Mac OS X POPfile startup item:
  2. Enter this command to create the folder /Library/StartupItems/POPfile:
    sudo mkdir -p /Library/StartupItems/POPfile
  3. Create a plain text file named "StartupParameters.plist" in the /Library/StartupItems/POPfile folder with this content:
    {
    	Description		= "POPfile mail classification proxy";
    	Provides		= ("popfile");
    	Requires		= ("Network");
    	Uses			= ("Disks", "Network Time", "IPServices");
    	OrderPreference  	= "Last";
    	Messages =
    	{
    		start = "Starting POPfile";
    		stop  = "Stopping POPfile";
    	};
    }
  4. Create a plain text file named “POPfile” in the /Library/StartupItems/POPfile/ folder with this content:
    #!/bin/sh
    #
    # POPfile - startup script
    #
    # For this to work POPfile should be in /Library/POPfile
    #
    . /etc/rc.common
     
    PFPATH='/Users/yourusername/Library/POPfile'
     
    if [ "$1" == "start" ]
    then
    	pid=$( ps -axww | grep popfile.pl | grep -v grep | awk '{ print $1 }' )
    	if ! [ $pid ]; then
    		ConsoleMessage "Starting POPfile mail classification proxy"
    		cd "$PFPATH"
    		perl popfile.pl > /dev/null 2>&1 &
     
    	fi
     
    elif [ "$1" == "stop" ]
    then
    	pid=$( ps -axww | grep popfile.pl | grep -v grep | awk '{ print $1 }' )
    	if [ $pid ]; then  
    		ConsoleMessage "Stopping POPfile mail classification proxy"		
    		kill -6 $pid
    	fi
     
    elif [ "$1" == "restart" ]
    then
    	pid=$( ps -axww | grep popfile.pl | grep -v grep | awk '{ print $1 }' )
    	ConsoleMessage "Restarting POPfile mail classification proxy"
    	kill -6 $pid
    	cd "$PFPATH"
    	perl popfile.pl > /dev/null 2>&1 &
    fi
  5. Create a plain text file named “Localizable.strings” in the /Library/StartupItems/POPfile/Resources/English.lproj/ folder with this content:
    <?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>
  6. You should now have this hierarchy of folders and files:
    /Library/ 
      StartupItems/ 
        POPfile/ 
          POPfile 
          StartupParameters.plist 
          Resources/ 
            English.lproj/ 
            Localizable.strings
  7. In a terminal window, enter these commands:
    cd /Library/StartupItems
    sudo chown -R root:wheel POPfile
    cd POPfile
    sudo chmod 754 POPfile
    sudo chmod 644 StartupParameters.plist
  8. Finally, to start up POPFile without rebooting enter this terminal command:
    sudo /Library/StartupItems/POPfile/POPfile start

TODO: Add details about the relationship between POPfile, DBD::SQlite2, and the SQLite3 command-line tool included with Mac OS X 10.4.x.

TODO: Add instructions to edit the popfile.cfg file and change the bayes_dbconnect property to dbi:SQLite2:dbname=$dbname to speed up POPfile launch times.

RevisedStartupItem

 
howtos/macosx.txt · Last modified: 2015/04/11 12:07 by amatubu

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License