Squid 3.2.0.1 release notes

Squid Developers


This document contains the release notes for version 3.2 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

2. Major new features since Squid-3.1

3. Changes to squid.conf since Squid-3.1

4. Changes to ./configure options since Squid-3.1

5. Options Removed since Squid-2

6. Regressions since Squid-2.7


1. Notice

The Squid Team are pleased to announce the release of Squid-3.2.0.1 for testing.

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

While this release is not deemed ready for production use, we believe it is ready for wider testing by the community.

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.

1.1 Known issues

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

1.2 Changes since earlier releases of Squid-3.2

The 3.2 change history can be viewed here.

2. Major new features since Squid-3.1

Squid 3.2 represents a new feature release above 3.1.

The most important of these new features are:

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

2.1 SMP scalability

The new "workers" squid.conf option can be used to launch multiple worker processes and utilize multiple CPU cores. The overall intent is to make multiple workers look like one to an outside observer, while providing knobs to customize each worker behavior if needed.

By default, all worker processes are configured identically and do what a single Squid instance would have done. Squid.conf macro substitutions and conditionals (see below) can be used to customize individual worker configurations. In the paragraphs below, "can share" implies "will share by default".

Workers can share HTTP, HTTPS, SNMP, ICP, and HTCP listening addresses. Configuration related to ICP and HTCP clients must be adjusted to avoid source address conflicts: Modify the IP address and/or the port used for the protocol. Workers do not share DNS addresses by default because the OS assigns each worker a unique DNS port.

Workers can share logs.

Workers cannot share caches, for now. Cache_dir options must be adjusted to point each disk-caching worker to its own disk area. ICP and HTCP responses are based on the responding worker cache state. Overall, SMP Squid behaves as a Squid farm behind a load-balancer with no cache affinity awareness. This is perfect for non-caching Squids but inappropriate for Squids that must coordinate caching activities (in-between environments are in a gray area requiring case-by-case analysis).

Cache manager and SNMP statistics are reported from a worker point of view, for now.

Startup, reconfiguration, shutdown, and log rotation are handled as for a monolithic Squid. Abnormally terminated workers are restarted while other workers continue serving traffic.

Squid.conf macros and conditionals

Added support for process_name and process_number macros as well as simple if-statement conditionals in squid.conf. These features allow individual worker customization in SMP mode. For details, search for "Conditional configuration" and "SMP-Related Macros" sections in squid.conf.documented.

2.2 Helper Multiplexer

The helper multiplexer's purpose is to relieve some of the burden Squid has when dealing with slow helpers. It does so by acting as a middleman between squid and the actual helpers, talking to Squid via the multiplexed concurrent variant of the helper protocol and to the helpers via the non-concurrent variant.

Helpers are started on demand, and in theory the muxer can handle up to 1k helpers per instance. It's up to squid to decide how many helpers to start.

The muxer knows nothing about the actual messages being passed around, and as such can't really (yet?) compensate for broken helpers. It is not yet able to manage dying helpers, but it will.

To configure the multiplexer add its binary name (usually /usr/share/libexec/helper-mux.pl) in front of the name of whichever helper is being multiplexed. It takes the helper binary path and parameters as its own command parameters. The concurrency setting already existing in Squid is used to configure how many child helpers it may run.

For example, a traditional configration is

        url_rewrite_program /your/redirector.sh
        url_rewrite_children 5
   
the alternative multiplexer configuration is:
        url_rewrite_program /usr/share/libexec/helper-mux.pl /your/redirector.sh
        url_rewrite_children 1 concurrency=5
   

Helpers which are already concurrent protocol enabled gain little benefit from the multiplexer on most systems. However on some systems where Squid spawning helpers causes excess memory usage the reduction in direct helper spawned by Squid can result in a great reduction in resource use.

The helper can be controlled using various signals:

2.3 Helpers On-Demand

Traditionally Squid has been configured with a fixed number of helpers and started them during it's start and reconfigure phases. This forces the hard configuration problem of how many helpers will be needed to be solved before starting Squid in production use.

The on-demand helpers feature allows greater flexibility and resolves this problem by allowing maximum, initial and idle thresholds to be configured. Squid will start the initial set during start and reconfigure phases. However over the operational use new helpers up to the maxium will be started as load demands. The idle threshold determins how many more helpers to start if the currently running set is not enough to handle current request loads.

For example, a traditional configration is

        auth_param ntlm /usr/libexec/squid/ntlm_auth
        auth_param ntlm children 200
   
the alternative on-demand configuration could be:
        auth_param ntlm /usr/libexec/squid/ntlm_auth
        auth_param ntlm children 200 startup=10 idle=2
   

The example still permits up to 200 helpers to be running at once under peak traffic loads. But only starts 10 when Squid is initialized resulting in a faster boot up. When client requests threaten to overload the running helpers an additional 2 will be started.

NOTE: if no startup and idle values are specified the traditional behaviour of starting the maximum number of helpers will occur.

2.4 Helper Name Changes

To improve the understanding of what each helper does and where it should be used the helper binaries which are bundled with Squid have undergone a naming change in this release.

Below is a list of the old helper names and what their names have changed to. For several helpers the directory name used in --enable-X-helpers configure option has also changed.

Basic Authentication protocol helpers

Digest Authentication protocol helpers

External ACL helpers

Negotiate Authentication protocol helpers

NTLM Authentication protocol helpers

URL re-write helpers

This group of helpers have been bundled to demonstrate how to code URL re-writers:

2.5 Multi-Lingual manuals

The man(8) and man(1) pages bundled with Squid are now provided online for all versions and beginning with 3.2 they are available in languages other than english.

Details in The Squid wiki

3.1 began the Internationalization of Squid with the public facing error pages. This move begins the Localization of the internal administrator facing manuals.

2.6 Solaris 10 pthreads Support (Experimental)

Automatic detection and use of the pthreads library available from Solaris 10

The result of this addition means that faster more efficient AUFS cache storage mechanisims are now available in Solaris 10.

Support is experimental at this stage due to lack of feedback on the results of enabling it. We recommend giving AUFS a try for faster disk storage and encourage feedback.

2.7 Surrogate/1.0 protocol extensions to HTTP

The Surrogate extensions to HTTP protocol enable an origin web server to specify separate cache controls for a reverse proxy acting on its behalf. Previously this was closely tied with the ESI feature support in Squid. This release opens Surrogate support to all reverse proxies.

Reverse proxy requests sent on to the web server include the HTTP header Surrogate-Capabilities: specifying the capabilities of the reverse proxy along with an ID which can be used to target reponses with a Surrogate-Control: HTTP header used instead of the Cache-Control: header.

The default surrogate ID is generated automatically from the Squid site-unique hostname as found by the automatic detection or manual configuration of visible_hostname although can be configured separately with the httpd_accel_surrogate_id option.

Security Considerations: Websites sould be careful of accepting any surrogate ID. Older releases of Squid leak the Surrogate-Control headers to external servers. This 3.2 series of Squid will now prevent this leakage of its own ID destined responses, however it is possible and for some uses desirable to receive external reverse-proxies Surrogate-Capabilities: headers.

NOTE: Several operating system distributions historically package Squid with a forced value of visible_hostname localhost. If this is done on a Surrogate enabled install a manual re-configuration is required to prevent an unacceptable surrogate ID of 'localhost' being generated.

2.8 Logging Infrastructure Updated

The advanced logging modules introduced in Squid-2.7 are now available from Squid-3.2.

This feature is documented at http://wiki.squid-cache.org/Features/LogModules

The new infrastructure currently supports several different channels types (modules) ranging from direct filesystem logging (stdio, daemon) to network logging (syslog, UDP and TCP). The daemon logging interface allows for a custom helper to be written to process logs in real-time.

Upgrading: the access_log was previously logge via what is now called the stdio module. This is still supported and used by default if no module is named. For best performance particularly in SMP environments we recommend the daemon be used. The provided log_file_daemon helper performs the traditional logging to local filesystem.

Additional to this the cache.log can now be limited to a smaller number of files stored. Traditionally cache.log.N has been fixed at the same number of rotated files as access.log.N through the logfile_rotate setting. The debug_options setting can now be used to configure the number of debug cache.log files to rotate through with a rotate=N option. This is particularly useful for logging a single cache.log at relatively high debug levels on a high-traffic system. Or one which is required to store a long period of access.log and needs to conserve disk space.

3. Changes to squid.conf since Squid-3.1

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

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

3.1 New tags

adapted_http_access

Access control based on altered HTTP request following adaptation alterations (ICAP, eCAP, URL rewriter). An upgraded drop-in replacement for http_access2 found in Squid-2.

else

Part of conditional SMP support syyntax. see if

endif

Part of conditional SMP support syyntax. see if

eui_lookup

Whether to lookup the EUI or MAC address of a connected client.

if

New conditional syntax for SMP multiple-worker. If-statements can be used to make configuration directives depend on conditions.

The else part is optional. The keywords if, else and endif must be typed on their own lines, as if they were regular configuration directives.

memory_cache_mode

Controls which objects to keep in the memory cache (cache_mem)

        'always'  Keep most recently fetched objects in memory (default)
        
        'disk'    Only disk cache hits are kept in memory, which means
                  an object must first be cached on disk and then hit
                  a second time before cached in memory.
        
        network   Only objects fetched from network is kept in memory
        

logfile_daemon

Ported from 2.7. Specify the file I/O daemon helper to run for logging.

tproxy_uses_indirect_client

Controls whether the indirect client address found in the X-Forwarded-For header is used for spoofing instead of the directly connected client address. Requires both --enable-follow-x-forwarded-for and --enable-linux-netfilter

workers

Number of main Squid processes or "workers" to fork and maintain. In SMP mode, each worker does nearly all what a single Squid daemon does (e.g., listen on http_port and forward HTTP requests).

        0: "no daemon" mode, like running "squid -N ..."
        1: "no SMP" mode, start one main Squid process daemon (default)
        N: start N main Squid process daemons (i.e., SMP mode)
        

3.2 Changes to existing tags

access_log

New stdio module to send log data directly from Squid to a disk file. This is the historic behaviour of Squid before logging modules were introduced, and remains the default used when no module is selected. It is recommended to upgrade logging to the faster daemon: module.

New daemon module to send each log line as text data to a file I/O daemon handling the slow disk I/O. New installs, or installs with no logs configured explicitly will use this module by default.

New tcp module to send each log line as text data to a TCP receiver.

New udp module to send each log line as text data to a UDP receiver.

acl random

New type random. Pseudo-randomly match requests based on a configured probability.

auth_param

New options for Basic, Digest, NTLM, Negotiate children settings. startup=N determins minimum number of helper processes used. idle=N determines how many helper to retain as buffer against sudden traffic loads. concurrency=N previously called auth_param ... concurrency as a separate option.

Removed Basic, Digest, NTLM, Negotiate auth_param ... concurrency setting option.

deny_info

Support URL format tags. For dynamically generated URL in denial redirect.

external_acl_type

New format tags and option parameters:

%SRCEUI48 EUI-48 / MAC address of client from ARP lookup.

%SRCEUI64 EUI-64 of clients with SLAAC address.

children-max=N determins maximum number of helper processes used.

children-startup=N determins minimum number of helper processes used.

children-idle=N determines how many helper to retain as buffer against sudden traffic loads.

Deprecated children=N in favor of children-max=N.

logformat

%>lp Local TCP port used by transactions with http servers.

%sn Unique sequence number per log line. Ported from 2.7

%<eui EUI logging (EUI-48 / MAC address for IPv4, EUI-64 for IPv6) Both EUI forms are logged in the same field. Type can be identified by length or byte delimiter.

memory_pools_limit

Memory limits have been revised and corrected from 3.1.4 onwards.

Please check and update your squid.conf to use the text none for no limit instead of the old 0 (zero).

All users upgrading need to be aware that from Squid-3.3 setting this option to 0 (zero) will mean zero bytes of memory get pooled.

windows_ipaddrchangemonitor

Now only available to be set in Windows builds.

url_rewrite_children

New options startup=N, idle=N, concurrency=N

3.3 Removed tags

ftp_list_width

Obsolete.

url_rewrite_concurrency

Replaced by url_rewrite_children ... concurrency=N option.

4. Changes to ./configure options since Squid-3.1

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

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

4.1 New options

--enable-auth-basic[=HELPERS]

Specified without any parameters all helpers will be auto-built.

With an explicit empty list ="" protocol suport will be built but no helpers.

With an explicit list protocol support and just those helpers will be built.

--enable-auth-digest[=HELPERS]

Specified without any parameters all helpers will be auto-built.

With an explicit empty list ="" protocol suport will be built but no helpers.

With an explicit list protocol support and just those helpers will be built.

--enable-auth-negotiate

Specified without any parameters all helpers will be auto-built.

With an explicit empty list ="" protocol suport will be built but no helpers.

With an explicit list protocol support and just those helpers will be built.

--enable-auth-ntlm

Specified without any parameters all helpers will be auto-built.

With an explicit empty list ="" protocol suport will be built but no helpers.

With an explicit list protocol support and just those helpers will be built.

--enable-eui

Enable Support for handling EUI operations. This includes ARP lookups for MAC (EUI-48) addresses and the ACL arp type tests.

--enable-log-daemon-helpers

Build helpers for logging I/O.

--enable-url-rewrite-helpers

Build helpers for some basic URL-rewrite actions. For use by url_rewrite_program. If omitted or set to =all then all bundled helpers that are able to build will be built. If set to a specific list of helpers then only those helpers will build. Currently one demo helper fake is provided in shell and C++ forms to demonstrate the helper protocol usage and provide exemplar code.

4.2 Changes to existing options

--enable-auth

No longer takes a list of arguments. This option now is restricted to building with or without for authentication.

The new --enable-auth-X/--disable-auth-X parameters determine which authentication protocols and helpers are built.

4.3 Removed options

--enable-arp-acl

Replaced by --enable-eui

--enable-auth-basic-helpers

replaced by --enable-auth-basic.

--enable-auth-digest-helpers

replaced by --enable-auth-digest.

--enable-auth-negotiate-helpers

replaced by --enable-auth-negotiate.

--enable-auth-ntlm-helpers

replaced by --enable-auth-ntlm.

5. Options Removed since Squid-2

Some squid.conf and ./configure options which were available in Squid-2.6 and Squid-2.7 are made obsolete in Squid-3.2.

5.1 Removed squid.conf options since Squid-2.7

auth_param

blankpassword option for basic scheme removed.

cache_peer

http11 Obsolete.

external_acl_type

Format tag %{Header} replaced by %>{Header}

Format tag %{Header:member} replaced by %>{Header:member}

header_access

Replaced by request_header_access and reply_header_access

http_port

no-connection-auth replaced by connection-auth=[on|off]. Default is ON.

transparent option replaced by intercept

http11 obsolete.

http_access2

Replaced by adapted_http_access

httpd_accel_no_pmtu_disc

Replaced by http_port disable-pmtu-discovery= option

incoming_rate

Obsolete.

redirector_bypass

Replaced by url_rewrite_bypass

server_http11

Obsolete.

upgrade_http0.9

Obsolete.

zph_local

Replaced by qos_flows local-hit=

zph_mode

Obsolete.

zph_option

Obsolete.

zph_parent

Replaced by qos_flows parent-hit=

zph_sibling

Replaced by qos_flows sibling-hit=

5.2 Removed squid.conf options since Squid-2.6

cache_dir

read-only option replaced by no-store.

5.3 Removed ./configure options since Squid-2.7

--enable-coss-aio-ops

Obsolete.

--enable-devpoll

Replaced by automatic detection.

--enable-dlmalloc=LIB

Obsolete.

--enable-epoll

Replaced by automatic detection.

--enable-forward-log

Obsolete.

--enable-heap-replacement

Obsolete.

--enable-htcp

Obsolete. Enabled by default.

--enable-large-cache-files

Obsolete.

--enable-mempool-debug

Obsolete.

--enable-multicast-miss

Obsolete.

--enable-poll

Replaced by automatic detection.

--enable-select

Replaced by automatic detection.

--enable-select-simple

Replaced by automatic detection.

--enable-snmp

Obsolete. Enabled by default.

--enable-truncate

Obsolete.

--disable-kqueue

Obsolete. Disabled by default.

6. Regressions since Squid-2.7

Some squid.conf and ./configure options which were available in Squid-2.7 are not yet available in Squid-3.2

If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.

6.1 Missing squid.conf options available in Squid-2.7

acl

urllogin option not yet ported from 2.6

urlgroup option not yet ported from 2.6

authenticate_ip_shortcircuit_access

Not yet ported from 2.7

authenticate_ip_shortcircuit_ttl

Not yet ported from 2.7

broken_vary_encoding

Not yet ported from 2.6

cache_dir

min-size option not yet ported from Squid-2

COSS storage type is lacking stability fixes from 2.6

COSS overwrite-percent= option not yet ported from 2.6

COSS max-stripe-waste= option not yet ported from 2.6

COSS membufs= option not yet ported from 2.6

COSS maxfullbufs= option not yet ported from 2.6

cache_peer

idle= not yet ported from 2.7

monitorinterval= not yet ported from 2.6

monitorsize= not yet ported from 2.6

monitortimeout= not yet ported from 2.6

monitorurl= not yet ported from 2.6

cache_vary

Not yet ported from 2.6

collapsed_forwarding

Not yet ported from 2.6

error_map

Not yet ported from 2.6

external_acl_type

%ACL format tag not yet ported from 2.6

%DATA format tag not yet ported from 2.6

external_refresh_check

Not yet ported from 2.7

http_port

act-as-origin not yet ported from 2.7

urlgroup= not yet ported from 2.6

ignore_ims_on_miss

Not yet ported from 2.7

location_rewrite_access

Not yet ported from 2.6

location_rewrite_children

Not yet ported from 2.6

location_rewrite_concurrency

Not yet ported from 2.6

location_rewrite_program

Not yet ported from 2.6

logformat

%oa tag not yet ported from 2.7

max_stale

Not yet ported from 2.7

refresh_pattern

stale-while-revalidate= not yet ported from 2.7

ignore-stale-while-revalidate= not yet ported from 2.7

max-stale= not yet ported from 2.7

negative-ttl= not yet ported from 2.7

refresh_stale_hit

Not yet ported from 2.7

storeurl_access

Not yet ported from 2.7

storeurl_rewrite_children

Not yet ported from 2.7

storeurl_rewrite_concurrency

Not yet ported from 2.7

storeurl_rewrite_program

Not yet ported from 2.7

update_headers

Not yet ported from 2.7

zero_buffers

Not yet ported from 2.7

6.2 Missing ./configure options available in Squid-2.7

--without-system-md5