Documentation for if2k v2 for Mac OS X Tiger

Overview

 
The Internet Filter - If2k
For Mac OS X 10.4

Turner and Sons Productions, Inc.
www.internetfilter.com

Technical support: <tech@internetfilter.com>


The Internet Filter If2k system for Macintosh





The Internet Filter If2k system for Macintosh OS X 10.4 is an easy to use and effective way to control access to web content on any web browser available for Mac OS X. 


• It can block known bad websites, websites with links to bad websites, and can block every website except those in a 'good' list if you want.
• It includes a database of 750,000 known pornography urls and sophisticated phrase filtering to block most other pornography websites.
• It can censor web page content and off-site images. 
• It allows you to customize the bad site lists, good site lists, and bad phrases list.
• It allows you to fully customize the message that appears when a website or image is blocked.
• It can read its settings and database from a remote website automatically on a timed schedule, allowing easy administration of multiple computers.



System Requirements


The filter was designed for Mac-OS X v10.4.1  Newer versions of OS X 10.4 should work fine, but OS X 10.5 will probably require a new version of the filter.

The filter, once installed, requires about 90 megabytes of hard disk space which includes the bad url databases which are expanded for very fast lookup.

The filter typically uses 20 megabytes of ram when running and very minimal cpu overhead.

The filter listens on 127.0.0.1 port 8000.  If you have any other software which uses port 8000, you will have to change the settings in that software.

The filter bypasses any HTTP proxy that is set in your computer's "System Preferences"->"Network"->"Proxies" settings.  If your network installation requires access via an external proxy, you must set the proxy and port in the "If2k Settings" application in the "Remote Settings" window.

Disk Image Contents

The "If2k Settings" application allows you to install, uninstall, and change the filter settings. You will want to drag and drop this icon to your computer so you can run it later.

Installation and Un-Installation

Installation


You require administrator privileges on the computer to install the If2k filter kernel.

Double-click on the "If2k Settings" application and click the 'Install' button on the main window. Follow the standard Apple Installer prompts to install it.  The filter can only install on your main system partition. 

You do not need to reboot your computer after you install the filter.

Once it is installed, the default settings of the filter are active for any web accesses.  You may want to customize these settings, or at least you should change the default password.  You can do this by running the "If2k Settings" application.

On the default installation, the filter's features are fully enabled, but the filter itself will expire in about a month unless you purchase and install an If2k license from us.  When the filter expires, no web accesses will be allowed unless you either un-install the filter or purchase and install a license.




Un-installation


To un-install the filter, you must have administrator access on the computer.

Double-click on the "If2k Settings" application icon and click the 'Uninstall' Button. Once the If2kSystem is un-installed, you must reboot your computer.  The un-installation process will not delete any copies of the "If2k Settings" application or ReadMe files that you have copied to your hard disk. You can drag these files to your trash if you wish to remove them.

Configuration

To configure the Internet Filter, you must run the If2k Settings application.

Starting the Settings Application

Run If2k Settings


Double click on the "If2k Settings" application to configure the filter. You will be presented with the following window which is mostly disabled until you login to the filter:








Logging In



Before you are allowed to make any changes to the filter settings, you must 'login' to the filter by entering the filter password and pressing the 'Login' button.  When you first install the filter, the password is initially set to 'password'.  Press the 'Login' Button and the controls in the window will become enabled like so:





 


Overview of the controls of the main window:


The "Apply" button sends all your settings to the filter.

The "Change Password" button allows you to change the filter password.

The "Enable Filtering" switch allows you to enable or disable the filter completely.

The "Allow Override" switch allows the user to manually override the filter.

The "Customize" button allows you to customize the filter blocking behaviour and block notification style.

The "Remote Settings" button allows you to set the filter to read the filter settings and url database from an external website

The "License" button allows you to view and load an Internet Filter license when you purchase the filter.

The "Bad URLs", "Good URLs", and "Phrases" tab allows you to view and edit your customized URL lists. These lists do not include the built in list of 450,000 bad urls.

Setting the Filter Password

It is highly recommended that you create a new password for the filter system when you first install the filter.  To do this, login to the filter and press the "Change Password" button. The following window will appear:





Enter in your new password and click on the "Apply" button.  From now on you will need to enter this password to login the filter.  Do not lose this password - If you do, you will need administration privileges to un-install the filter, reboot, and re-install the filter and all your settings will be lost.

Block Page Configuration

When a website is blocked, the typical block page looks like this:





In the "Customization Window" you may customize most aspects of this internally generated page - The title, image, link, and text. Or, you may create your own web page on your own website and tell the filter to use it instead.




Changing blocking settings and block page style


When you click on the "Customize" button, the following window will appear:





Overview of the controls of the "Customization Settings" window:

The "Apply" button accepts your settings. You will need to press the "Apply" button in the main window to tell the filter about your new settings.

The "Cancel" button closes the window without accepting your settings.

The "Block Bad Sites" switch when checked causes the filter to block any website that is listed in the bad URLs list.

The "Block Unknown" switch when checked causes the filter to block all websites that are not in your good URLs list.

The "Censor bad URLs in content" switch when checked causes the filter to censor any links to bad URLs in an unknown website.

The "Censor bad phrases in content" switch when checked causes the filter to censor any phrases that match any phrases in the "Phrases" list.

The "Content match count before blocking" field allows you to specify how many censored matches are allowed in an unknown website before the filter blocks the entire page.

The "Block Page Title" field allows you to set the HTML title of the block page.

The "Block Page Image" field allows you to set the image that is displayed in the block page. It defaults to "blocked1.jpg" which is stored internal to the filter. You may set this to any external URL of an image, for example:  "http://www.yourwebsite/yourblockedimage.jpg"

The "Block Page Image Link" field allows you to set the HTML link that the block page image links to.  It defaults to "http://www.internetfilter.com/".

The "Block Page Text" field allows you to set the text that is displayed below the "Block Page Image".

The "Block Page URL" field allows you to use an entirely different external block page.  When this is set to any url other than "block.html", the filter will redirect bad sites to this url instead of displaying the internally generated block page.

The "Redirect Images on bad sites" when checked tells the filter to replace any JPG,GIF, and PNG images that are located on known bad websites to the URLs specified via the "Redirect JPG images to", "Redirect GIF images to", and "Redirect PNG images to" fields.  You may enter any full urls of external images in these fields.

Loading a License File

Click on the "License" button in the main window. The following window will appear:





This window allows you to load a new license file.  You may not edit any of these fields.

When you purchase the filter, you will be sent a text file containing the license information.  Save this text file to your disk and click the "Load" button in this window.  Select the license file and press the "Ok" button. You should see your specific license information in the window. Press the "Apply" button and the license information will be stored. Press the "Apply" button in the main window to send this information to the filter.

Remote Settings

When you click on the "Remote Settings" button in the main window, the following window will appear:





Overview of the controls of the "Remote Settings" window:

The "Apply" button accepts your settings. You will need to press the "Apply" button in the main window to tell the filter about your new settings.

The "Cancel" button closes the window without accepting your settings.

The "HTTP Proxy to use" field allows you to set the filter to perform all web accesses via an external proxy.  You will need to set this field if your network setup requires access via an external HTTP proxy.

The "Remote Database URL" field tells the filter to read the good URL, bad URL and phrase database from an external website URL.

The "Remote Settings URL" field tells the filter to read the global filter settings from the specified text file external website URL.

The "Update Rate In Minutes" field, if non-zero, tells the filter to load the external settings and database at the specified rate.

Using Remote URL Databases

If you want the filter to load the custom lists from an external website, you must manually create 3 text files:


• 01badurl.txt    - Your list of bad urls
• 01goodurl.txt    - Your list of good urls
• 01badphr.txt    - Your list of bad phrases

Upload these files to a directory in your intranet or internet website, and enter in the full URL of this directory in the "Remote Database URL" field in the "Remote Settings" window and specify a non-zero number of minutes for the filter to reload them in the "Update Rate In Minutes" field.

The filter will access your website automatically to see if the files have been modified.  If they have been modified, the filter will download your database files and install them on the client computer.




Using Remote Settings


The Remote Settings feature is for advanced users of the filter. The URL specified in the "Remote Settings URL" field of the "Remote Settings" window must be a text file which contains the filter settings.  To create this file, contact <jeffk@internetfilter.com> for details.

Problems and Solutions

Problem:     The filter installed but web browsing does not work at all.

Solutions:    


1. Check to make sure you are not running any other server that listens to port 8000.
2. If you had just un-installed the filter and re-installed it, you must reboot your computer.
3. Check if the filter license has expired.
4. Check your Mac OS X version via "About this mac..." in the Apple menu and contact <jeffk@internetfilter.com>



---


Problem:     The filter is blocking a website that shouldn't be blocked.

Solutions:    

1. Add the URL of the website to the "Good URLs" list.



---


Problem:     The filter is not blocking a website that should be blocked

Solutions:    


1. Add the URL of the website to the "Bad URLs" list.
2. Make sure the "Enable Filtering" switch is checked.
3. Make sure the "Block Bad Sites" switch is checked.



---


Problem:     Forgotten filter password

Solutions:    
    Un-install the filter, reboot, and re-install the filter. All your settings will be gone.



---




 

Technical Information

The If2kSystem.pkg installs everything into the system directory:


    /Library/StartupItems/if2k


All of the files relating to the filter are stored in this directory and are not visible or modifiable by any normal users on the computer. You can access these files only via the command-line as the root user. ie: you must have administrator access and use the command line utility "sudo" to access them.

The filter daemon, if2kd, runs on system startup, before anyone logs into the computer.  It listens to the TCP/IP address 127.0.0.1:8000 and writes its process id to the file "/var/run/if2kd.pid" and any log entries to the file "/var/log/if2kd.log".

The filter's settings are stored in text files in the /Library/StartupItems/if2k directory:


• install.txt - installation settings  
  
• additional.txt - customization settings
• license.txt - the filter license

The "additional.txt" file can be copied and put on an external website for use with the "Remote Settings URL" setting.

Any files in the directory "/Library/StartupItems/if2k/web/"available via the filter's built-in web server running at "http://127.0.0.1:8000/"

The directory "/Library/StartupItems/if2k/db/" contains the user's URL and phrase database files.

The directory "/Library/StartupItems/if2k/predb/" contains the built-in URL and phrase database files, in both raw text form (*.txt) and in pre-compiled form (*.txt.pre).

The directory "/Library/StartupItems/if2k/bin/" contains the system programs:

• if2kd - the filter daemon
  
• if2k_uninstall.sh - the filter uninstall script
• if2ktigerext.kext - the filter kernel extension
• if2k_precompile_all - command line program that reads all the *.txt files in the predb directory and creates the pre-compiled *.txt.pre files.