Squid 3.0.STABLE26 release notes

Squid Developers

This document contains the release notes for version 3.0 of Squid.
Squid is a WWW Cache application developed by the National Laboratory
for Applied Network Research and members of the Web Caching community.

Squid 3.0 represents a major rewrite of Squid and has a number of new features.

The most important of these are:

Code converted to C++, with significant internal restructuring and rewrites.

ICAP implementation (RFC 3507 and www.icap-forum.org)

Edge Side Includes (ESI) implementation (www.esi.org)

Most user-facing changes are reflected in squid.conf (see below).

Internet Content Adaptation Protocol (ICAP)

Squid 3.0 supports ICAP/1.0. To enable ICAP support, use the --enable-icap-client ./configure option and icap_enable squid.conf option. You will also need to configure ICAP services in your squid.conf using icap_service, icap_class, and icap_access options. The following example instructs Squid to talk to two ICAP services, one for request and one for response adaptation:

No more than one ICAP service can be applied to an HTTP message. In other words, chaining or load balancing multiple services is not yet supported.

Proxy-directed data trickling and patience pages are not supported yet.

Following ICAP requirements, Squid never performs HTTP message adaptation without a successful and fresh ICAP OPTIONS response on file. A REQMOD or RESPMOD request will not be sent to a configured ICAP service until Squid receives a valid OPTIONS response from that service. If a service malfunctions or goes down, Squid may stop talking to the service for a while. Several squid.conf options can be used to tune the failure bypass algorithm (e.g., icap_service_failure_limit and icap_service_revival_delay).

The bypass parameter of the icap_service squid.conf option determines whether Squid will try to bypass service failures. Most connectivity and preview-stage failures can be bypassed.

access.log

The TCP_REFRESH_HIT and TCP_REFRESH_MISS log types have been replaced because they were misleading (all refreshes need to query the origin server, so they could never be hits). The following log types have been introduced to replace them:

TCP_REFRESH_UNMODIFIED

The requested object was cached but STALE. The IMS query for the object resulted in "304 not modified".

TCP_REFRESH_MODIFIED

The requested object was cached but STALE. The IMS query returned the new content.

This Squid version can run on Windows as a system service using the Cygwin emulation environment,
or can be compiled in Windows native mode using the MinGW + MSYS development environment. Windows NT 4 SP4 and later are supported.
On Windows 2000 and later the service is configured to use the Windows Service Recovery option
restarting automatically after 60 seconds.

Usage

Some new command line options were added for the Windows service support:

The service installation is made with -i command line switch, it's possible to use -f switch at
the same time for specify a different config-file settings for the Squid Service that will be
stored on the Windows Registry.

A new -n switch specify the Windows Service Name, so multiple Squid instance are allowed.
"Squid" is the default when the switch is not used.

So, to install the service, the syntax is:

squid -i [-f file] [-n name]

Service uninstallation is made with -r command line switch with the appropriate -n switch.

The -k switch family must be used with the appropriate -f and -n switches, so the syntax is:

squid -k command [-f file] -n service-name

where service-name is the name specified with -n options at service install time.

To use the Squid original command line, the new -O switch must be used ONCE, the syntax is:

squid -O cmdline [-n service-name]

If multiple service command line options must be specified, use quote. The -n switch is
needed only when a non default service name is in use.

Don't use the "Start parameters" in the Windows 2000/XP/2003 Service applet: they are
specific to Windows services functionality and Squid is not designed for understand they.

In the following example the command line of the "squidsvc" Squid service is set to "-D -u 3130":

squid -O "-D -u 3130" -n squidsvc

PSAPI.DLL (Process Status Helper) Considerations

The process status helper functions make it easier for you to obtain information about
processes and device drivers running on Microsoft? Windows NT?/Windows? 2000. These
functions are available in PSAPI.DLL, which is distributed in the Microsoft? Platform
Software Development Kit (SDK). The same information is generally available through the
performance data in the registry, but it is more difficult to get to it. PSAPI.DLL is
freely redistributable.

PSAPI.DLL is available only on Windows NT, 2000, XP and 2003. The implementation in Squid is
aware of this, and try to use it only on the right platform.

On Windows 2000 and later it is available installing the Windows Support Tools, located on the
Support\Tools folder of the installation Windows CD-ROM.

Registry DNS lookup

On Windows platforms, if no value is specified in the dns_nameservers option on
squid.conf or in the /etc/resolv.conf file, the list of DNS name servers are
taken from the Windows registry, both static and dynamic DHCP configurations
are supported.

Compatibility Notes

It's recommended to use '/' char in Squid paths instead of '\'

Paths with spaces (like 'C:\Programs Files\Squid) are NOT supported by Squid

When using ACL like 'acl aclname acltype "file"' the file must be in DOS text
format (CR+LF) and the full Windows path must be specified, for example:

acl blocklist url_regex -i "c:/squid/etc/blocked1.txt"

The Windows equivalent of '/dev/null' is 'NUL'

Squid doesn't know how to run external helpers based on scripts, like .bat, .cmd,
.vbs, .pl, etc. So in squid.conf the interpreter path must be always specified, for example:

When Squid runs in command line mode, the launching user account must have administrative privilege on the system

"Start parameters" in the Windows 2000/XP/2003 Service applet cannot be used

Building with MinGW, when the configure option --enable-truncate is used, Squid cannot run on Windows NT, only Windows 2000 and later are supported

On Windows Vista and later, User Account Control (UAC) must be disabled before running service installation

Known Limitations

Squid features not operational:

DISKD: still needs to be ported

WCCP: cannot work because user space GRE support on Windows is missing

Transparent Proxy: missing Windows non commercial interception driver

Some code sections can make blocking calls.

Some external helpers may not work.

File Descriptors number hard-limited to 2048 when building with MinGW.

Building Squid on Windows

A reasonably recent release of
Cygwin or
MinGW is needed.
The usage of the Cygwin environment is very similar to other Unix/Linux environments, and -devel version of libraries must be installed.
For the MinGW environment, the packages MSYS, MinGW and msysDTK must be installed. Some additional libraries and tools must be downloaded separately:

Default: 5
Normally the ICP query timeout is determined dynamically. But
sometimes it can lead to very small timeouts, even lower than
the normal latency variance on your link due to traffic.
Use this option to put an lower limit on the dynamic timeout
value. Do NOT use this option to always use a fixed (instead
of a dynamic) timeout value. To set a fixed timeout see the
'icp_query_timeout' directive.

background_ping_rate

Default: 10 seconds
Controls how often the ICP pings are sent to siblings that
have background-ping set.

httpd_accel_surrogate_id

Default: unset
Surrogates (http://www.esi.org/architecture_spec_1.0.html)
need an identification token to allow control targeting. Because
a farm of surrogates may all perform the same tasks, they may share
an identification token.

http_accel_surrogate_remote on|off

Default: off
Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
Set this to on to have squid behave as a remote surrogate.

Default: on
If enabled, information about the occurred error will be
included in the mailto links of the ERR pages (if %W is set)
so that the email body contains the data.
Syntax is <A HREF="mailto:%w%W">%w</A>

refresh_all_ims on|off

Default: off
When you enable this option, squid will always check
the origin server for an update when a client sends an
If-Modified-Since request. Many browsers use IMS
requests when the user requests a reload, and this
ensures those clients receive the latest version.
By default (off), squid may return a Not Modified response
based on the age of the cached version.

request_header_access

Replaces the header_access directive of Squid-2.6 and earlier, but applies to requests only.

reply_header_access

Replaces the header_access directive of Squid-2.6 and earlier, but applies to replies only.

icap_enable on|off

Default: off
If you want to enable the ICAP module support, set this to on.

icap_preview_enable on|off

Default: off
Set this to 'on' if you want to enable the ICAP preview
feature in Squid.

icap_preview_size

Default: -1
The default size of preview data to be sent to the ICAP server.
-1 means no preview. This value might be overwritten on a per server
basis by OPTIONS requests.

icap_default_options_ttl (seconds)

Default: 60
The default TTL value for ICAP OPTIONS responses that don't have
an Options-TTL header.

icap_persistent_connections on|off

Default: on
Whether or not Squid should use persistent connections to
an ICAP server.

icap_send_client_ip on|off

Default: off
This adds the header "X-Client-IP" to ICAP requests.

icap_send_client_username on|off

Default: off
This adds the header "X-Client-Username" to ICAP requests
if proxy access is authentified.

icap_service

Default: none
Defines a single ICAP service
icap_service servicename vectoring_point bypass service_url
vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
This specifies at which point of request processing the ICAP
service should be plugged in.
bypass = 1|0
If set to 1 and the ICAP server cannot be reached, the request will go
through without being processed by an ICAP server
service_url = icap://servername:port/service
Note: reqmod_postcache and respmod_postcache is not yet implemented
Example:
icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod
icap_service service_2 respmod_precache 0 icap://icap2.mydomain.net:1344/respmod

Default: none
Redirects a request through an ICAP service class, depending
on given acls
icap_access classname allow|deny [!]aclname...
The icap_access statements are processed in the order they appear in
this configuration file. If an access list matches, the processing stops.
For an "allow" rule, the specified class is used for the request. A "deny"
rule simply stops processing without using the class. You can also use the
special classname "None".
For backward compatibility, it is also possible to use services
directly here.
Example:
icap_access class_1 allow all

accept_filter

The name of an accept(2) filter to install on Squid's
listen socket(s). This feature is perhaps specific to
FreeBSD and requires support in the kernel.
The 'httpready' filter delays delivering new connections
to Squid until a full HTTP request has been received.
See the accf_http(9) man page.

include

New option to import entire secondary configuration files into squid.conf.

Squid will follow the files immediately and insert all their content
as if it was at that position in squid.conf. As per squid.conf some
options are order-specific within the config as a whole.
A few layers of include are allowed, but too many are confusing and
squid will enforce an include depth of 16 files.
Syntax:
include /path/to/file1 /path/to/file2

acl myportname

New acl type myportname, matching the name of the http(s)_port where the request was accepted

acl aclname myportname 3128 ... # http(s)_port name

umask

Ported from 2.6. Behaviour identical.

Minimum umask which should be enforced while the proxy
is running, in addition to the umask set at startup.
For a traditional octal representation of umasks, start
your value with 0.

disable-pmtu-discovery=
Control Path-MTU discovery usage:
off lets OS decide on what to do (default).
transparent disable PMTU discovery when transparent support is enabled.
always disable always PMTU discovery.
In many setups of transparently intercepting proxies Path-MTU
discovery can not work on traffic towards the clients. This is
the case when the intercepting device does not fully track
connections and fails to forward ICMP must fragment messages
to the cache server. If you have such setup and experience that
certain clients sporadically hang or never complete requests set
disable-pmtu-discovery option to 'transparent'.

cache_peer

New options:

basetime=n
background-ping
weighted-round-robin
use 'basetime=n' to specify a base amount to
be subtracted from round trip times of parents.
It is subtracted before division by weight in calculating
which parent to fectch from. If the rtt is less than the
base time the rtt is set to a minimal value.
use 'background-ping' to only send ICP queries to this
neighbor infrequently. This is used to keep the neighbor
round trip time updated and is usually used in
conjunction with weighted-round-robin.
use 'weighted-round-robin' to define a set of parents
which should be used in a round-robin fashion with the
frequency of each parent being based on the round trip
time. Closer parents are used more often.
Usually used for background-ping parents.

cache_dir

Common options no-store, replaces the older read-only option

auth_param

NCSA authenticator updated in 3.0.STALE26 to alert if passwords with more
than 8 characters are used with DES encryption method.

tag= Apply a tag to a request (for both ERR and OK results)
Only sets a tag, does not alter existing tags.

refresh_pattern

New options:

ignore-no-store
refresh-ims
ignore-no-store ignores any ``Cache-control: no-store''
headers received from a server. Doing this VIOLATES
the HTTP standard. Enabling this feature could make you
liable for problems which it causes.
refresh-ims causes squid to contact the origin server
when a client issues an If-Modified-Since request. This
ensures that the client will receive an updated version
if one is available.

acl

The 'all' ACL is now provided as a built-in. Warnings will be displayed if any attempt is made to redefine it.

class 4 Everything in a class 3 delay pool, with an
additional limit on a per user basis. This
only takes effect if the username is established
in advance - by forcing authentication in your
http_access rules.
class 5 Requests are grouped according their tag (see
external_acl's tag= reply).

Don't compile Squid with compiler optimizations enabled.
Optimization is good for production builds, but not
good for debugging. During development, use
--disable-optimizations to reduce compilation times
and allow easier debugging. This option implicitly
also enables --disable-inline

--disable-inline

Don't compile trivial methods as inline. Squid
is coded with much of the code able to be inlined.
Inlining is good for production builds, but not
good for development. During development, use
--disable-inline to reduce compilation times and
allow incremental builds to be quick. For
production builds, or load tests, use
--enable-inline to have squid make all trivial
methods inlinable by the compiler.

--enable-debug-cbdata

Provide some debug information in cbdata

--enable-disk-io=\"list of modules\"

Build support for the list of disk I/O modules.
The default is only to build the "Blocking" module.
See src/DiskIO for a list of available modules, or
Programmers Guide for details on how to build your
custom disk module.

Disable memPools. Note that this option now simply sets the
default behaviour. Specific classes can override this at runtime, and
only lib/MemPool.c needs to be altered to change the squid-wide
default for all classes.

--enable-cpu-profiling

This option allows you to see which internal functions
in Squid are consuming how much CPU. Compiles in probes
that measure time spent in probed functions. Needs
source modifications to add new probes. This is meant
for developers to assist in performance optimisations
of Squid internal functions.

If you are not developer and not interested in the stats
you shouldn't enable this, as overhead added, although
small, is still overhead. See lib/Profiler.c for more.

--with-gnu-ld

Assume the C compiler uses GNU ld. The default is to auto-detect.

--with-pic

Try to use only PIC/non-PIC objects. The default is to use both.

--with-tags[=TAGS]

Include additional configurations. The default is automatic.

--with-default-user=USER

Sets the default System User account for squid permissions.
The default is 'nobody' as in other releases of squid.

--with-cppunit-basedir=[PATH]

Path where the cppunit headers and libraries are found
for unit testing. The default is automatic detection.

NOTE: Since 3.0-PRE6 and 2.6STABLE14 squid no longer comes
bundled with CPPUnit. Compile-time validation will be disabled
if it is not installed on your system.