SquidMan 3.

8 ReadMe

What’s New In v3.8

• Compiled and tested on Mac OS X 10.11 (El Capitan).
• Added a new Control menu, with commands and keyboard equivalents for manually starting,
stopping, and restarting squid.
• Added new preference options for the in-memory cache.
• Added a new advanced preferences tab with performance tuning options.
• Fixed a bug that would prevent Squid shutdown on logout if SquidMan was running.
• Upgraded the bundled version of Squid to 3.5.15.

What Was New in v3.6

• Compiled and tested on Mac OS X 10.10 (Yosemite).
• Now uses a version 2 code signature for Yosemite GateKeeper conformance.
• Changed the configuration options for squid to disable SSL support, as the OpenSSL API is
deprecated in OS X. This change does not affect Squid's ability to proxy outgoing SSL
connections, but it does prevent it being used in a reverse proxy configuration over SSL.
• Upgraded the bundled version of Squid to 3.4.9.

If you’re upgrading from some older versions of Squid, you may be prompted that 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 the latest version of Squid 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 downgrade the template. You can do this
manually by resetting the template in the Template pane of SquidMan’s preferences window.
About This Software
SquidMan is a MacOS X graphical manager for the Squid proxy cache. It is designed to operate
primarily 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.8 you need MacOS X 10.6.8 or later on 64-bit hardware (note that this
precludes the use of SquidMan on MacOS X 10.6.x running on Core Duo hardware, such as some
early model iMacs). 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

The General tab is where the basic preferences for SquidMan are set.

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.

Disk Cache Size

This menu allows you to turn disk-based caching of content off, or specify an upper 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.

Memory Cache Size

This menu allows you to specify the size of the in-memory cache, which cannot be turned
off. If you have a lot of memory, and are serving multiple clients, increasing this value may
improve performance.

Maximum Object Size

These menus specify the largest sized object that Squid will store in the disk and in-memory
caches. The Squid documentation suggests if you wish to increase speed more than you
want to save bandwidth, you should leave these 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 the Parent
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 specified as the 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. If you leave the
password field empty SquidMan will prompt you to enter it 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 tab 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 Direct Preferences Tab

When using an upstream proxy (that is, a parent proxy), you can use the Direct tab 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 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" 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 (see the
diagram over the page). 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.
The Advanced Preferences Tab

The Advanced tab provides access to performance tuning settings for Squid. Most users will be
able to ignore these settings – you can find out more about what they do on the official Squid
documentation pages at http://www.squid-cache.org/Doc/config/
Configuring Your System
Before your computer can use your local Squid proxy server, you need to set appropriate values
in the Network pane of the System Preferences Application.

Normally, you would set the proxy server address for the Web Proxy (HTTP) and Secure Web
Proxy (HTTPS) protocols to 127.0.0.1 - a special IP address that represents your computer. You
should also set the port to the same port that you entered into the SquidMan "General"
preferences tab.

A typical configuration for MacOS X 10.11 (El Capitan) would look as follows (note that you have
to click the "Advanced…" button to get to these options):

MacOS X 10.11 El Capitan 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 2002 Various beta versions were developed and released to friends and
colleagues during 2002, each adding more features based on user
feedback.
1.1 10 May, 2003 First public release.
1.5 24 Oct, 2003 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.
1.51 25 Oct, 2003 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.
1.52 25 Nov, 2003 Switched the "Preferences" command key from ";" to ",", fixed a bug that
can prevent SquidMan detecting that Squid has started on MacOS X
10.3.
1.6 10 Jan, 2005 Upgraded to Squid 2.5STABLE7
1.61 11 Jan, 2005 Rebuilt the Squid binaries so they will run on MacOS X 10.2
1.8 10 May, 2006 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.
2.0 22 Nov, 2007 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.
2.5 4 July, 2009 Upgraded to Squid 3.0STABLE16. Fixed a long-standing problem where
SquidMan would sometimes say Squid was not running, when in fact it
was.
3.0 22 May, 2010 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.
3.1 21 May, 2011 Upgraded to Squid 3.1.12.
3.5 6 Oct, 2013 Upgraded to Squid 3.3.8. Dropped support for 32-bit systems. This
version was rewritten to use ARC for memory management, and is
codesigned (a requirement to run properly on Mac OS X 10.9).
3.51 2 Nov, 2013 Upgraded to Squid 3.3.9. Disabled EUI support to stop extensive log
messages relating to it.
3.6 16 Nov, 2014 Upgraded to Squid 3.4.9. Disabled SSL support for reverse proxy.
Codesigned for, and qualified for use on OS X 10.10 (Yosemite). Fixed a
bug that sometimes prevented Squid being updated as part of an upgrade.
3.8 12 Apr, 2016 Upgraded to Squid 3.5.15. Qualified for use on OS X 10.11 (El Capitan).
Added a Control menu, with commands to manually start, stop, and
restart squid. Added new preference options for the in-memory cache,
and a new advanced preferences tab with performance tuning options.
Fixed a bug that would prevent Squid shutdown on logout if SquidMan
was already running.
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.