Squid 3.0.STABLE8 release notes

Squid Developers

$Id: release-3.0.sgml,v 1.30.2.5 2008/02/28 00:26:31 amosjeffries Exp $
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.

1. Notice

The Squid Team are pleased to announce the release of Squid-3.0.STABLE8.

This new release is available for download from http://www.squid-cache.org/Versions/v3/3.0/ or the mirrors.

A large number of the show-stopper bugs have been fixed along with general improvements to the ICAP support and additional Languages.

We welcome feedback and bug reports. If you find a bug, please see http://wiki.squid-cache.org/SquidFaq/TroubleShooting#head-7067fc0034ce967e67911becaabb8c95a34d576d for how to submit a report with a stack trace.

2. Known issues

Although this release is deemed good enough for use in many setups, please note the existence of open bugs against Squid-3.0.

3. Changes since earlier STABLE releases of Squid-3.0

The 3.0 change history can be viewed here.

4. Changes since Squid-2.6

4.1 Major new features

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

The most important of these are:

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:

icap_enable on
icap_service service_req reqmod_precache 1 icap://127.0.0.1:1344/request
icap_service service_resp respmod_precache 0 icap://127.0.0.1:1344/response
icap_class class_req service_req
icap_class class_resp service_resp
icap_access class_req allow all
icap_access class_resp allow all

Please see squid.conf.default for more details about these and many other icap_* options.

Squid supports pre-cache request and pre-cache response vectoring points. The following ICAP features are supported: message preview, 204 responses outside of preview, request satisfaction, X-Transfer-* negotiation, persistent ICAP connections, client IP/credentials sharing, and optional bypass of certain service failures.

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.

More information about ICAP can be found from the ICAP-forum website http://www.icap-forum.org

Edge Side Includes (ESI)

ESI is an open specification of an markup language enabling reverse proxies to perform some simple XML based processing, offloading the final page assembly from the webserver and similar tasks.

More information about ESI can be found from the ESI website http://www.esi.org

4.2 2.6 features not found in Squid-3.0

Some of the features found in Squid-2.6 is not available in Squid-3. Some have been dropped as they are not needed. Some have not yet been forward-ported to Squid-3 and may appear in a later release.

4.3 Logging changes

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.

See http://www.squid-cache.org/Doc/FAQ/FAQ-6.html#ss6.7 for a definition of all log types.

4.4 Changes to squid.conf

There have been many changes to Squid's configuration file since Squid-2.6.

This section gives a thorough account of those changes in three categories:

New tags

minimum_icp_query_timeout (msec)

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.
        

esi_parser libxml2|expat|custom

Default: custom

ESI markup is not strictly XML compatible. The custom ESI parser
will give higher performance, but cannot handle non ASCII character
encodings.
        

email_err_data on|off

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_precache 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
        

icap_class

Default: none

Defines an ICAP service chain. If there are multiple services per
vectoring point, they are processed in the specified order.

icap_class classname servicename...

Example:
icap_class class_1 service_1 service_2
icap class class_2 service_1 service_3
        

icap_access

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.
        

Changes to existing tags

http_port

New options:

    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'.
        

Removed options:

    urlgroup=, not yet ported to Squid-3.
    
    no-connection-auth, not yet ported to Squid-3.
        

https_port

Removed options:

    urlgroup=, not yet ported to Squid-3.
        

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.

        

Removed options:

    monitorurl, monitorsize etc, not yet ported to Squid-3

    connection-auth=, not yet ported to Squid-3
        

cache_dir

Common options

    no-store, replaces the older read-only option

    min-size, not yet ported to Squid-3
        

COSS file system:

    The coss file store is experimental, and still lacks much
    of the functionality found in 2.6.

    overwrite-percent=n, not yet ported to Squid-3.

    max-stripe-waste=n, not yet ported to Squid-3.

    membufs=n, not yet ported to Squid-3.

    maxfullbufs=n, not yet ported to Squid-3.
        

auth_param

Removed Basic auth option

    blankpasswor, not yet ported to squid-3.
    auth_param basic concurrency 0
        

Removed digest options:

    concurrency, not yet ported to Squid-3.
        

external_acl_type

New format specifications:

    %URI          Requested URI

    %PATH         Requested URL path
        

Removed format specifications:

    %ACL, not yet ported to Squid-3

    %DATA, not yet ported to Squid-3
        

New result keywords:

     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.

New types:

    acl aclname http_status 200 301 500- 400-403 ...     # status code in reply

        

Removed types:

    acl aclname urllogin [-i] [^a-zA-Z0-9] ...      # regex matching on URL login field

    acl urlgroup group1 ...
        # match against the urlgroup as indicated by redirectors

        

short_icon_urls

New default:

    Default: on
    (Old default: off)
        

delay_class

New delay classes:

    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).
        

htcp_port

New default to require the feature to be enabled in squid.conf:

    Default: 0 (disabled)
    (Old default: 4827)
        

icp_port

New default to require the feature to be enabled in squid.conf:

    Default: 0 (disabled)
    (Old default: 3130)
        

snmp_port

New default to require the feature to be enabled in squid.conf:

    Default: 0 (disabled)
    (Old default: 3401)
        

logformat

New format tags:

    rp      Request URL-Path excluding hostname

    et      Tag returned by external acl

    <sH     Reply high offset sent

    <sS     Upstream object size
        

reply_body_max_size

Syntax changed:

    reply_body_max_size size [acl acl...]
        

allow/deny no longer used.

url_rewrite_program

No urlgroup support in either requests or responese

auth_param

fake_auth helper for NTLM now accepts the '-S' parameter to strip NTLM domain off the username string. This is useful for class 4 Delay Pools in Squid 3.x

Removed tags

broken_vary_encoding

Not yet ported to Squid-3.

cache_vary

Not yet ported to Squid-3.

collapsed_forwarding

Not yet ported to Squid-3.

follow_x_forwarded_for

Not yet ported to Squid-3.

*_uses_indirect_client

Not yet ported to Squid-3.

error_map

Not yet ported to Squid-3.

header_access

This has been replaced by request_header_access and reply_header_access

http_access2

Not yet ported to Squid-3.

httpd_accel_no_pmtu_disc

Replaced by disable-pmtu-discovery http_port option

location_rewrite_*

Not yet ported to Squid-3.

refresh_stale_hit

Not yet ported to Squid-3.

wais_relay_*

equivalent to cache_peer + cache_peer_access.

4.5 Changes to ./configure Options

There have been some changes to Squid's build configuration since Squid-2.6.

This section gives an account of those changes in three categories:

New options

--enable-shared[=PKGS]

Build shared libraries. The default is to build without.

--enable-static[=PKGS]

Build static libraries. The default is on.

--enable-fast-install[=PKGS]

Optimize for fast installation
        default: yes

--disable-libtool-lock

Avoid locking (might break parallel builds)

--disable-optimizations

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.

--enable-esi

Enable ESI for accelerators. Requires libexpat. Enabling ESI will cause squid to follow the Edge Acceleration Specification (www.esi.org). This causes squid to IGNORE client Cache-Control headers.

DO NOT use this in a squid configured as a web proxy, ONLY use it in a squid configured for webserver acceleration.

--enable-icap-client

Enable the ICAP client.

--disable-snmp

Disable SNMP monitoring support which is now built by default.

--disable-htcp

Disable HTCP protocol support which is now built by default.

--enable-kqueue

Enable kqueue() support. Marked as experimental in 3.0.

--enable-ipfw-transparent

Enable Transparent Proxy support for systems using FreeBSD IPFW style redirection.

--disable-mempools

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.

Changes to existing options

--enable-carp

CARP support is now built by default. --disable-carp can be used to build without it.

--enable-htcp

HTCP protocol support is now built by default. Use --disable-htcp to build without it.

--enable-snmp

SNMP monitoring is now build by default. Use --disable-snmp to build without it.

--enable-heap-replacement

Please use --enable-removal-policies directive instead.

--with-maxfd=N

Replaced by --with-filedescriptors=N

Override maximum number of filedescriptors. Useful if you build as another user who is not privileged to use the number of filedescriptors you want the resulting binary to support

--enable-select

Deprecated. Automatic checks will enable best I/O loop method available.

--enable-epoll

Deprecated. Automatic checks will enable best I/O loop method available.

--enable-poll

Deprecated. Automatic checks will enable best I/O loop method available.

--enable-kqueue

kqueue support is marked Experimental in Squid 3.0. Known to have some issues under load.

Not yet available options

These configure options have not yet been ported to Squid-3. If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.

--enable-devpoll

Support for Solaris /dev/poll

--enable-select-simple

Basic POSIX select() loop without any binary fd_set optimizations.

--enable-follow-x-forwarded-for

Support following the X-Forwarded-For HTTP header for determining the client IP address

Removed options

The following configure options have been removed.

--enable-dlmalloc

Most OS:es have good malloc implementations these days, and the version we used to ship with Squid was very very old..

--enable-mempool-debug

Debug option, not needed and therefore removed.

--enable-forward-log

Rarely used extra log file. Removed.

--enable-multicast-miss

Rarely used feature, and multicast ICP acheives almost the same result. Removed.

--enable-coss-aio-ops

Specific to the COSS implementation in Squid-2

--enable-large-cache-files

Now enabled by default. Configure option was redundant and therefore removed.

--enable-truncate

Known to cause race conditions where cache objects may get corrupted, and this for at most a marginal performance improvement. Removed.