SquidMan 3.

1 ReadMe
Whats New Since v3.0
The bundled version of Squid has been upgraded to 3.1.12.

If youre upgrading from SquidMan 2.5 or earlier, you should note that starting with version 3.0 of SquidMan (and the corresponding upgrade to Squid 3.1) a new Squid template is required. This is due to changes in squid itself, and it is unlikely that older templates will work unmodified. You will be prompted during the upgrade that the template needs to be changed. If you have customised the template, be sure to save a copy of your old template before upgrading to Squid 3.1 so that you can manually migrate any changes to the new template. If you subsequently downgrade to an earlier version of SquidMan, it will detect and offer to downgrade the installed version of Squid, but it will not offer to downgrade the template. You just do this manually by resetting the template in the Template pane of SquidMans preferences window.

About This Software

SquidMan is a MacOS X graphical manager for the Squid proxy cache. It is designed to operate as a "personal" proxy server.

What is a Caching Proxy Server?

A proxy server is a server that handles protocol requests (such as HTTP and FTP requests) on behalf of other applications. Often, proxy servers are used in conjunction with firewalls, so that hosts on the inside of the firewall are prevented from accessing external servers, and instead they direct their requests through the proxy server. This simplifies the set up of the firewall, and in general makes the internal hosts less susceptible to attacks from external hosts. A caching proxy server adds the ability to keep copies of the content it has downloaded on behalf of its clients. When a client requests a document that is already in the cache, the proxy server can return the cached version instead of downloading the original version a second time. This is often much faster than re-downloading the original content, and can also save network

bandwidth. Caching proxy servers use various techniques to ensure that cached version is not returned if the external version has changed since the copy was cached. Typically, caching can save 20-30% of the bandwidth, and improve browsing speeds (particularly when the connection to the Internet is not as fast). Some proxy servers are configured to require authentication - that is, users on client systems must authenticate themselves to the proxy server (typically with a username and password) before the proxy server will pass their requests on to external hosts. This mechanism ensures that the system administrator can monitor the downloading habits of the users, which may be important from a security or resource allocation perspective. Squid is a sophisticated and powerful open source caching proxy server that has been ported to a number of operating systems, and it compiles and runs on MacOS X. Squid configuration is managed through a text file, and can be quite complex. SquidMan is designed to make it very easy to install and run Squid as a personal caching proxy server.

Why run Squid on MacOS X?

Typically, Squid is used on central servers and is managed by an IT department in conjunction with an organization-wide firewall, but there are two reasons why it is useful to run Squid on a MacOS X system. First, if the caching feature is enabled it is useful as a tool for saving bandwidth and boosting browsing speed, particularly if the speed of your network connection is not great (for example, if you connect to the internet over a slow modem link). Second, and perhaps more importantly, there are a number of component parts of MacOS X that use HTTP to access external web resources. For example, the MacOS X Help system will consult servers at Apple if the computer has an active connection to the Internet when help topics are opened, to see if the help content has been updated and hence is more recent than the help already stored on the computer. Another service that uses HTTP is the Software Update mechanism. In MacOS X 10.2, many of these services would not operate through a parent proxy server that required authentication, since they had no way to prompt you for your proxy-server username and password, and Apple had not provided a mechanism to specify this in any of the system preference panes. This changed with the release of MacOS X 10.3, which added support for authenticating proxy servers, although there are still a number of applications that do not play well with proxy servers that require authentication. When running Squid on your own computer, your local Squid can provide your username and password to the "upstream" proxy server. If all your internal HTTP requests are directed to your local Squid server, they will all be automatically authenticated to the parent proxy, and hence those services (such as Software Update and Help) that normally fail will work.

SquidMan is not an Anonymising Proxy Server

When you browse to web sites on the internet, the web site provider knows the IP address that you have connected to the internet from, and can use this information to attempt to build a profile of you or your activities. They can potentially pass this information on to law enforcement agencies, government agencies, or other groups that might have an interest in knowing who you are and/or what you are doing on the internet. Anonymising proxy servers are proxy servers out on the internet that act as a third party on your behalf. The intention is that you route all of your browsing traffic through an anonymising proxy server, and therefore traffic that you generate now appears to web site providers to come from the proxy service provider, rather than from your own computer. In theory, this helps you maintain a degree of anonymity. Of course, you are still relying on the proxy service provider to keep information about your browsing habits private, and not release them to third parties. SquidMan is designed to run squid inside your home or work network, on your own computer. Any traffic you generate that gets routed through your local Squid instance will still originate from your computer. Using SquidMan does not in and of itself provide any anonymity.

System Requirements
To use SquidMan 3.0 you need MacOS X 10.4 or later. (Use SquidMan 1.61 for if you are still running MacOS X 10.2, or SquidMan 1.8 if you are still running MacOS X 10.3). SquidMan should run acceptably on systems with as little as 1G of RAM. If you use the caching feature of Squid, you'll need a minimum of 500M of disk space for the cache, and more if you configure a larger cache size. For most users, SquidMan requires an active Internet connection (specifically, Squid may not run if it is unable to resolve DNS addresses). Knowledgeable users may be able to circumvent this restriction (for example, by installing their own DNS server).

Installing The Software

To install SquidMan, drag the application to the Applications folder on your start up volume (or any other location). The first time you run SquidMan, it will detect that the Squid proxy cache software is not installed, and you will be asked to authenticate as an administrative user. Once you do this, the Squid application will be installed in the directory /usr/local/squid. If you have been using a previous version of SquidMan, the new version should detect that an older version of Squid is installed, and offer to upgrade it. You may also be warned that the Squid template needs to be upgraded (this is the basic squid configuration that is adjusted by SquidMan according to the preferences that you set). Generally speaking, you should always use the template and version of squid bundled with SquidMan, as different release may be incompatible.

Setting SquidMan Preferences

The first time you run SquidMan, it will display a preferences dialog. You can also access this dialog anytime SquidMan is running by choosing the Preferences option from the SquidMan menu. The Preferences dialog is divided into five panes, as described next.

The General Preferences Tab

This tab is where the general preferences for SquidMan are set.

The General Preferences Tab

HTTP Port This is where you specify the port that Squid listens to for incoming HTTP connections (from client applications such as web browsers, normally running on your computer). Although most port numbers can be used, it is common to use either port 3128, or port 8080 for proxy servers, and you should use one of these unless you have a special reason not to. The port number should be greater than 1024, as port numbers lower than this require root privilege (which is not supported by SquidMan). Visible Hostname This specifies the hostname that Squid will display in error messages that are sent to web browsers. If you do not specify a value here, "localhost" will be used. Cache Size This menu allows you to turn caching off, and specify a cache size. Caching is useful in many instances, and can improve general browsing performance, particularly if your internet connection is slow, but note that it will use some disk space.

Maximum Object Size This specifies the largest sized object that Squid will store in the cache. The Squid documentation suggests if you wish to increase speed more than you want to save bandwidth, you should leave this low. Rotate Logs As Squid accesses documents on behalf of your web browser, it logs its activity in several log files. These files grow and should be "rotated" periodically. This menu allows you specify whether SquidMan should rotate the logs every time it launches Squid, or whether you will rotate the logs manually (through the Tools menu item). Start Squid on Launch Check this box to cause SquidMan to automatically start the Squid proxy cache when SquidMan itself is started. This option exists so that you can add SquidMan to your "Login Items" preference pane, and have Squid start automatically when you log in to your computer. Optionally, you can specify a delay between SquidMan being launched, and Squid being started. This capability exists in case your Internet connection is also started at login time, and extra time is needed for it to start before Squid tries to access the network. Finally you can also have SquidMan quit after launching Squid by checking the "and then quit" box. If you select this option, and later want to run SquidMan without it quitting (for example, to edit the preferences), hold down the option key as you launch SquidMan. Quit Squid on Logout After being started by SquidMan, Squid will continue to run even after you quit SquidMan, and normally it will continue to run even after you log out. For a computer that is only ever used by a single user, this is often the best option, but if the computer is shared among several individuals it may be appropriate to have Squid terminate on logout. If you check the "Quit Squid on Logout" checkbox, a separate background program ("SquidQuitter") is started. This program is messaged by MacOS X on logout, and it attempts to kill the Squid process started by SquidMan (occasionally this may fail, and you may have to manually kill the Squid process). Show Errors produced by Squid At times, Squid may be unable to start (for example, if the network is down, and Squid is unable to resolve DNS addresses, or if another copy of Squid is already running). If you check this box, SquidMan will open a window that displays any unexpected text output by the Squid process as is starts. Even without checking this option, you can check Squid output using the Squid Messages option in the Squid menu (Command-E).

The Parent Preferences Tab

If your network connection is behind a firewall, and your IT support group requires that to use a centrally-managed proxy server, you need to specify that proxy server's details on this tab.

The Parent Preferences Tab

Use a parent proxy server Enable this checkbox if you must (or wish to) connect to a proxy server elsewhere on the network. Hostname This should be the hostname or IP address of the parent proxy server. Port
This is the port number that the parent proxy server listens for requests on. Typically this will be port 8080, but you should consult your IT support group or Help Desk if you are unsure of the value.

Parent requires authentication If the proxy server you have nominated as your parent requires you to authenticate yourself, check this box. Username & Password If the proxy server you have nominated as your parent requires you to authenticate yourself, enter your username and password for the parent proxy server in these fields. SquidMan stores the password securely in the MacOS X Keychain, but if you leave the password field empty SquidMan will prompt you to enter the password before it starts Squid.

The Client Preferences Tab

The version of Squid installed by SquidMan is the full Squid application that is capable of providing proxy services for hundreds of clients. Use the Clients pane to specify the addresses of computers for which you will provide proxy services. Most users will leave these fields empty, but you can specify single IP addresses or addresses with network masks here.

The Client Preferences Tab

The Direct Preferences Tab

When using an upstream proxy (that is, a parent proxy), you can use the Direct pane to specify which hosts and domains your local Squid should directly connect to (bypassing the parent proxy). Typically your local domain name is entered here so that intranet requests aren't forwarded to your external proxy server, but are fetched directly by the local Squid server.

The Direct Preferences Tab

The Template Preferences Tab

When it starts (or restarts) Squid, SquidMan builds a Squid configuration file using the various preferences that have been specified by the user. This file (as squid.conf) is stored in the user's ~/Library/Preferences directory, and SquidMan then starts the Squid program, passing the location of the configuration file as a parameter on the Squid command-line.

The Template Preferences Tab

The "template" version of the configuration file, from which the final configuration file is built, can be viewed and edited if necessary in the "Template" tab of the SquidMan preferences. The template contains a number of substitution strings (eg., %PARENTPROXY%) that are replaced by values from the SquidMan preferences. You can edit the template to modify many aspects of Squid's operations. You might want to do this to tune the Squid configuration for your system. Note - don't edit the template unless you have some knowledge of how to configure Squid. It is possible to stop Squid working if you don't specify the template settings correctly, of if you delete or modify the substitution strings. If you do modify the template, you can restore it to the "factory default condition" using the "Reset to default" button on the template preferences pane.

Configuring Your System

Before your computer will use the local Squid proxy server, you need to set the appropriate values in the Network pane of the System Preferences. Normally, you would set the proxy server address for each of the FTP, Web Proxy (HTTP) and Secure Web Proxy to 127.0.0.1 - a special IP address that represents your computer. In each case, you should set the port to the same port that you entered into the SquidMan "General" preferences tab. A typical configuration for MacOS X 10.3 is shown below (the options and appearance are almost identical in MacOS X 10.4):

MacOS X 10.3 Network Preference Settings to use Squid

A typical configuration for MacOS X 10.5 and 10.6 would look as follows (note that you have to click the "Advanced" button to get to these options):

MacOS X 10.5 Network Preference Settings to use Squid

Uninstalling Squid
To uninstall Squid, choose the "Uninstall" command from the SquidMan menu. This will remove the Squid installation (in /usr/local/squid) as well as the squid log and cache files in the current user's home directories. Once these files are removed, SquidMan will quit. If you no longer require SquidMan on your computer, you can then drag the SquidMan application file to the Trash.

Credits
The icon used for SquidMan was designed by Samuel Krueger ("pixeljerk") (who the author has been unable to contact, but according to archives of his web site, his icons are free for use on non-commercial software). If you know Sam (or are Sam) thanks where can I make a donation? SquidMan includes a precompiled version of Squid to simplify installation and configuration. You can find more information about Squid, including the source code at: http://www.squid-cache.org Squid is Copyright 2000 the Regents of the University of California. Squid is released under the GNU General Public Licence. You can find more information about the Free Software Foundation at: http://www.gnu.org

Feedback
Feedback and reproducible bugs are welcome. Please contact the author via e-mail at: adg@mac.com Please note that it may not be possible to answer all emails about SquidMan, as the author also has a fulltime job.

Release History
1.0 1.1 1.5 2002 10 May, 2003 24 Oct, 2003 Various beta versions were developed and released to friends and colleagues during 2002, each adding more features based on user feedback. First public release. Significant upgrade, including Squid 2.5STABLE3. Many new and updated preferences, including the ability to edit the Squid configuration template. Relocated log and cache files from /tmp to ~/Library. A number of performance improvements. Tested against MacOS X 10.2 and MacOS X 10.3. Fixed some cosmetic issues with help balloons. Properly creates the cache and log directories if they don't exist at launch. Fixed some bugs that can occur when two users try to run Squid at the same time. Switched the "Preferences" command key from ";" to ",", fixed a bug that can prevent SquidMan detecting that Squid has started on MacOS X 10.3. Upgraded to Squid 2.5STABLE7 Rebuilt the Squid binaries so they will run on MacOS X 10.2 Upgraded to Squid 2.5STABLE13, now a Universal Binary. Dropped support for MacOS X 10.2. Squid is now compiled with support for delay pools. Added some more options for cache size and object size. Cleaned up some of the version-upgrade code. Upgraded to Squid 2.6STABLE16, added support for MacOX 10.5, dropped support for MacOS X 10.3. Upgraded to Squid 3.0STABLE16. Fixed a long-standing problem where SquidMan would sometimes say Squid was not running, when in fact it was. Upgraded to Squid 3.1.1. Added an Uninstall menu command. Relocated the Squid logs to ~/Library/Log/squid. Some code cleanup and bug fixes. Upgraded to Squid 3.1.12.

1.51 25 Oct, 2003 1.52 25 Nov, 2003 1.6 10 Jan, 2005 1.61 11 Jan, 2005 1.8 10 May, 2006 2.0 2.5 3.0 3.1 22 Nov, 2007 4 July, 2009 22 May, 2010 21 May, 2011

Disclaimer
This software is supplied "as is, where is", and is provided in good faith. You choose to use it at your own risk. While welcoming suggestions for improvement, the author accepts no responsibility for losses incurred, and offers no guarantees about the suitability of the software for any specific purpose.