1 <!doctype linuxdoc system>
3 <title>Squid 3.4.14 release notes</title>
4 <author>Squid Developers</author>
7 This document contains the release notes for version 3.4 of Squid.
8 Squid is a WWW Cache application developed by the National Laboratory
9 for Applied Network Research and members of the Web Caching community.
16 The Squid Team are pleased to announce the release of Squid-3.4.14.
18 This new release is available for download from <url url="http://www.squid-cache.org/Versions/v3/3.4/"> or the
19 <url url="http://www.squid-cache.org/Download/http-mirrors.html" name="mirrors">.
21 <p>Some interesting new features adding system flexibility have been added along with general improvements all around.
22 While this release is not fully bug-free we believe it is ready for use in production on many systems.
24 <p>We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting">
25 for how to submit a report with a stack trace.
29 Although this release is deemed good enough for use in many setups, please note the existence of
30 <url url="http://bugs.squid-cache.org/buglist.cgi?query_format=advanced&product=Squid&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&version=3.4" name="open bugs against Squid-3.4">.
32 <sect1>Changes since earlier releases of Squid-3.4
34 The 3.4 change history can be <url url="http://www.squid-cache.org/Versions/v3/3.4/changesets/" name="viewed here">.
37 <sect>Major new features since Squid-3.3
38 <p>Squid 3.4 represents a new feature release above 3.3.
40 <p>The most important of these new features are:
42 <item>Helper protocol extensions
43 <item>SSL Server Certificate Validator
45 <item>TPROXY Support for OpenBSD 5.1+ and FreeBSD 9+
46 <item>Transaction Annotations
50 Most user-facing changes are reflected in squid.conf (see below).
53 <sect1>Helper protocol extensions
54 <p>Details at <url url="http://wiki.squid-cache.org/Features/AddonHelpers">.
56 <p>The Squid helper protocol used to communicate with authenticators,
57 URL-rewriters, Redirectors, and External ACL helpers has been updated
60 <p><em>BH</em> status code is now accepted from all helpers to report
61 internal error events separate from <em>ERR</em> rejection code.
62 Permitting Squid to perform recovery operations specific to
63 helper failure instead of a blanket client rejection.
65 <p>Arbitrary key-value pairs can be returned from any helper.
66 Allowing future helpers to be forward- and backward- compatible
67 with this and future versions of Squid.
70 <sect1>SSL Server Certificate Validator
71 <p>Details at <url url="http://wiki.squid-cache.org/Features/SslServerCertValidator">.
73 <p>The helper consulted after the internal OpenSSL validation, regardless of the
74 validation results. The helper will receive:
77 <item>the origin server certificate (chain),
78 <item>the intended domain name, and
79 <item>a list of OpenSSL validation errors (if any).
82 <p>If the helper decides to honor an OpenSSL error or report another validation
83 error(s), the helper will return:
86 <item>A list of certificates.
87 <item>A list of items consists the the validation error name (see <em>%err_name</em>
88 error page macro and <em>%err_details</em> code for <em>logformat</em>), error reason
89 (<em>%ssl_lib_error macro</em>), and the offending certificate.
92 <p>The returned information mimics what the internal OpenSSL-based validation code
93 collects now. Returned errors, if any, are fed to <em>sslproxy_cert_error</em>,
94 triggering the existing SSL error processing code.
96 <p>The helper invocation controlled by the <em>sslcrtvalidator_program</em> and
97 <em>sslcrtvalidator_children</em> configurations options which are similar to the
98 <em>ssl_crtd</em> related options.
102 <p>Details at <url url="http://wiki.squid-cache.org/Features/StoreID">.
104 <p>This feature is a redesigned equivalent to the Squid-2.7 feature known as StoreURL-rewrite.
106 <p><em>Notice</em> that this is not a direct portage of the Squid-2.7 feature so behaviour
107 differences do exist. Although the new feature works in similar enough ways that the old
108 helper scripts used for Squid-2.7 are expected to work in this and later versions of Squid.
110 <p>Squid traditionally uses the requested URL as an index key ID to locate objects in cache.
111 It is not the only key possible and the Store-ID feature exposes an API for external
112 helpers to provide Squid with an alternative key name for any URL.
114 <p>When any client request is received which requires a cache lookup the URL is passed to
115 a helper specified with the <em>store_id_program</em> directive to check for an alternative
116 Store ID. This allows the helper to identify URLs which refer to duplicate resources and
117 de-duplicate the cache content. <em>store_id_access</em> is provided to allow ACL-based
118 tuning of which traffic gets sent to the helper and reduce overheads.
120 <p>One subtle and noteworthy difference between Squid-2 and Squid-3 which is highlighted by
121 this feature is that <em>refresh_pattern</em> applies its regex argument against the Store
122 ID key and not the transaction URL. So using the Store-ID feature to alter the value
123 affects which <em>refresh_pattern</em> directive will be matched.
125 <p>Store-ID helpers bundled with Squid can be built with the --enable-storeid-rewrite-helpers
126 option which is added in this version. Currently there is a <em>file</em> helper
130 <sect1>TPROXY Support for OpenBSD 5.1+ and FreeBSD 9+
131 <p>Details at <url url="http://wiki.squid-cache.org/ConfigExamples/Intercept/OpenBsdPf">.
133 <p>The Packet Filter (PF) firewall in OpenBSD 4.4 and later offers traffic interception
134 using several very simple methods. One of which is the <em>divert-to</em> rule type
135 which acts as a simple routing diversion instead of performing NAT packet alterations.
137 <p>The IP Firewall (IPFW) on FreeBSD 9+ contains a port of the Linux Netfilter TPROXY feature.
139 <p>This version of Squid adds support for these features through the ./configure
140 options --enable-pf-transparent and --enable-ipfw-transparent when Squid is built on
141 systems with the required support. No special extras are required to enable
142 <em>http_port ... tproxy</em> configuration to work.
144 <p>NOTE: To resolve NAT lookup issues on recent PF firewall versions the code behind
145 <em>./configure --enable-pf-transparent</em> has been altered and is expected to
146 break on the version of PF firewall shipped with BSD systems such as NetBSD and FreeBSD
147 which do not yet support the getsockname() API.
148 These systems require <em>--with-nat-devpf</em> to enable /dev/pf support when using PF firewall.
151 <sect1>Transaction Annotations
152 <p>Previously the only annotation methods available were ICAP/eCAP HTTP header insertions
153 or external ACL <em>tag=</em> result code. Each of which had only limited possibilities
154 for use and little or no correlation.
156 <p>It is now possible to add annotations to a client transaction from several sources:
158 <item> Directly from squid.conf using the <em>note</em> directive with
159 ACL-based selection of which annotation is linked to any
160 particular transaction.
162 <item> By configured helper processes returning a key=value pair.
163 The key name becomes the annotation name.
166 <p>Annotations on the transaction can be passed to ICAP services or eCAP modules using the
167 <em>adaptation_meta</em> directive to send them as headers.
168 They can also be logged using the <em>%note</em> log format code in custom logs. With
169 the new helper response syntax changes this means all helper response key=value details
170 such as URL-rewrite or store-id changes, external ACL tag etc. are now able to be logged.
172 <p>Annotations which are already assigned to a transaction can be checked using an ACL test
173 of the new <em>note</em> ACL type. This can match a particular note by name and value,
174 of for any notes with a given name.
176 <p>NOTE: not all helper interfaces are yet enabled to convert key=value into annotations
177 and the external ACL interface does not yet send annotations to the helper.
181 <p>The internal DNS component of Squid now supports multicast DNS (mDNS) resolution in
182 accordance with RFC 6762.
184 <p>The <em>dns_multicast_local</em> directive must be set to <em>on</em> to enable this
187 <p>The multicast DNS group IP addresses for IPv4 and IPv6 resolving are added to the set
188 of available DNS resolvers and used automatically for domain names ending in <em>.local</em>
189 and reverse-DNS lookups before attempting a secondary resolution on the configured
190 resolvers. Domains without <em>.local</em> are resolved using only the configured resolvers.
192 <p>Statistics for multicast DNS resolution can be found on the <em>idns</em> cache manager
195 <p><em>NOTE</em> that the external DNS helper interface is now deprecated and has been
196 removed from future Squid versions. Any installations still using it for local hostname
197 resolution need to upgrade to mDNS resolution with this Squid version.
200 <sect>Changes to squid.conf since Squid-3.3
202 There have been changes to Squid's configuration file since Squid-3.3.
204 <p>Squid supports reading configuration option parameters from external
205 files using the syntax <em>parameters("/path/filename")</em>. For example:
207 acl whitelist dstdomain parameters("/etc/squid/whitelist.txt")
210 <p>There have also been changes to individual directives in the config file.
212 This section gives a thorough account of those changes in three categories:
215 <item><ref id="newtags" name="New tags">
216 <item><ref id="modifiedtags" name="Changes to existing tags">
217 <item><ref id="removedtags" name="Removed tags">
221 <sect1>New tags<label id="newtags">
224 <tag>configuration_includes_quoted_values</tag>
225 <p>Whether Squid supports directive parameters with spaces, quotes, and other
226 special characters. Surround such parameters with "double quotes" and
227 also set this directive on/off around the relevant squid.conf line(s)
228 making use of such quoting.
230 <tag>dns_multicast_local</tag>
231 <p>Use multicast DNS for <em>.local</em> domains and reverse-DNS resolution.
234 <p>Use ACLs to annotate a transaction with customized annotations
235 which can be logged in access.log
237 <tag>spoof_client_ip</tag>
238 <p>Access control to determine whether to disable the TPROXY spoofing on upstream traffic.
240 <tag>sslcrtvalidator_children</tag>
241 <p>Specifies the settings for how many SSL server certificate
242 validator helpers are run and when they are started.
244 <tag>sslcrtvalidator_program</tag>
245 <p>Specifies the location of a SSL server certificate validator helper.
247 <tag>store_id_access</tag>
248 <p>Whether the URL for a given request is passed to the Store-ID helper process.
249 Used to improve StoreID performance by quickly eliminating helper delays using ACL tests.
250 <p>Ported equivalent to <em>storeurl_access</em> from 2.7
252 <tag>store_id_bypass</tag>
253 <p>Whether the StoreID helper may be bypassed when overloaded.
255 <tag>store_id_children</tag>
256 <p>Controls the number of StoreID helper processes.
257 <p>Options <em>startup=N</em>, <em>idle=N</em>, <em>concurrency=N</em>
259 <item>startup=N allow finer tuning of how many helpers are started initially.
260 <item>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.
261 <item>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.
264 <tag>store_id_rewrite_program</tag>
265 <p>A helper program to provide cache storage internal key ID value for a request.
266 <p>Ported equivalent to <em>storeurl_rewrite_program</em> from 2.7
270 <sect1>Changes to existing tags<label id="modifiedtags">
273 <tag>access_log</tag>
274 <p>Configuration syntax extended to support name=value options.
275 <em>New Syntax:</em> access_log module:place [option ...] [acl ...]
276 <p>New option <em>logformat=</em> to specify the logging format name.
277 <p>New option <em>buffer-size=</em> to specify how large the log buffer
278 for this log is to be when <em>buffered_logs</em> is enabled.
279 <p>New option <em>on-error=</em> to specify what handling is to be done
280 if the logging module encounters a non-recoverable error writing logs.
281 With the value <em>die</em> (the default) Squid halts operation.
282 With the value <em>drop</em> Squid drops log lines and continue running.
285 <p>New test type <em>server_cert_fingerprint</em> to match against
286 server SSL certificate fingerprint.
287 <p>New test type <em>note</em> to match against transaction annotations
288 by name and value, or just by name.
289 <p>New test type <em>any-of</em> to match if any one of a set of named ACLs.
290 <p>New test type <em>all-of</em> to match against all of a set of named ACLs.
292 <tag>auth_param</tag>
293 <p>New result code <em>BH</em> to signal helper internal errors
294 available in all authentication schemes.
295 <p>New key <em>message=</em> for error message details in all authentication schemes.
296 <p>New result code <em>OK</em> and key <em>ha1=</em> in Digest authentication.
297 <p>New result codes <em>OK</em>, <em>ERR</em> replace result codes <em>AF</em>,
298 and <em>NA</em> in NTLM and Negotiate authentication.
299 <p>New key <em>token=</em> for NTLM and Negotiate authentication <em>OK</em> responses.
300 <p>Details at <url url="http://wiki.squid-cache.org/Features/AddonHelpers">.
302 <tag>external_acl_type</tag>
303 <p>Deprecated <em>protocol=3.0</em> option. No longer necessary.
304 <p>New result code <em>BH</em> to signal helper internal errors
305 <p>Details at <url url="http://wiki.squid-cache.org/Features/AddonHelpers">.
308 <p>Support IPv6 for <em>intercept</em> mode. Requires ip6tables support on Linux,
309 PF support on OpenBSD and IPFW support on FreeBSD. Squid will no longer complain
310 about misconfiguration if IPv6 support is missing, we now rely on the firewall
311 tools reporting misconfiguration when the NAT rules are created.
312 <p>Support <em>tproxy</em> mode traffic on BSD systems with BINDANY support
313 (OpenBSD 5+, FreeBSD 9+ so far).
314 <p>Changed build options behind <em>intercept</em> traffic mode handling on BSD.
315 see <em>--enable-pf-transparent</em> for more details.
318 <p>New format code <em>%note</em> to log a transaction annotation linked to the
319 transaction by ICAP, eCAP, a helper, or the <em>note</em> squid.conf directive.
320 <p>New format code <em>%>qos</em> to log client connection TOS/DSCP value set by Squid.
321 <p>New format code <em>%<qos</em> to log server connection TOS/DSCP value set by Squid.
322 <p>New format code <em>%>nfmark</em> to log client connection netfilter mark set by Squid.
323 <p>New format code <em>%<nfmark</em> to log server connection netfilter mark set by Squid.
325 <tag>pipeline_prefetch</tag>
326 <p>Updated to take a numeric count of prefetched pipeline requests instead of ON/OFF.
328 <tag>refresh_pattern</tag>
329 <p><em>NOTE:</em> the regular expression pattern operates on the cache Store-ID value.
330 Which by default is identical to the requested URL, but may differ for some
331 objects if the Store-ID feature is in use.
333 <tag>unlinkd_program</tag>
334 <p>New helper response format utilizing result codes <em>OK</em> and <em>BH</em>,
335 to signal helper lookup results. Also, key-value response values to return
336 multiple values to Squid.
337 <p>Details at <url url="http://wiki.squid-cache.org/Features/AddonHelpers">.
339 <tag>url_rewrite_program</tag>
340 <p>New helper response format utilizing result codes <em>OK</em>, <em>ERR</em>,
341 and <em>BH</em> to signal helper lookup results. Also, key-value response
342 values to return multiple values to Squid.
343 <p>Details at <url url="http://wiki.squid-cache.org/Features/AddonHelpers">.
347 <sect1>Removed tags<label id="removedtags">
350 <tag>log_access</tag>
351 <p>Removed. Use access_log with ACLs instead
354 <p>Removed. Use icap_log with ACLs instead
356 <tag>storeurl_access</tag>
357 <p>Replaced by <em>store_id_access</em>.
359 <tag>storeurl_rewrite_children</tag>
360 <p>Replaced by <em>store_id_children</em>.
362 <tag>storeurl_rewrite_concurrency</tag>
363 <p>Replaced by <em>store_id_children</em> with <em>concurrency=N</em> option.
365 <tag>storeurl_rewrite_program</tag>
366 <p>Replaced by <em>store_id_program</em>.
371 <sect>Changes to ./configure options since Squid-3.3
373 There have been some changes to Squid's build configuration since Squid-3.3.
375 This section gives an account of those changes in three categories:
378 <item><ref id="newoptions" name="New options">
379 <item><ref id="modifiedoptions" name="Changes to existing options">
380 <item><ref id="removedoptions" name="Removed options">
384 <sect1>New options<label id="newoptions">
387 <tag>--enable-storeid-rewrite-helpers</tag>
388 <p>New option to control which Store-ID helpers are built. As with other
389 helper options use --disable-* to prevent any helpers building and
390 omit to get all helper auto-detected.
391 <p>Currenly only a helper using <em>file</em> for backend is provided.
393 <tag>--disable-arch-native</tag>
394 <p>New option to disable use of -march=native compiler flag.
395 <p>The new flag auto-enables CPU-specific optimizations in GCC and is
396 required by Clang++ v3.2 for correct 64-bit environment detection.
397 It does not always work well however, so this build option is provided
398 to remove it when necessary.
400 <tag>--with-nat-devpf</tag>
401 <p>New option to alter the behaviour of <em>http_port ... intercept</em> option
403 <p>When this option is used Squid performs the /dev/pf lookups required to
404 support PF <em>rdr-to</em> rules. Otherwise Squid will perform perform the
405 getsockname() API calls to support PF <em>divert-to</em> rules.
406 <p>NOTE: systems such as NetBSD and FreeBSD which do not yet support
407 the getsockname() API in recent PF versions require this option.
411 <sect1>Changes to existing options<label id="modifiedoptions">
414 <tag>--enable-pf-transparent</tag>
415 <p>NAT table support updated to use the getsockname() API provided by the
416 latest PF versions <em>divert-to</em>. This allows <em>http_port</em>
417 in squid.conf to support both <em>intercept</em> and <em>tproxy</em> traffic
418 and to silence NAT lookup failure messages on recent BSD.
419 <p>NOTE: systems such as NetBSD and FreeBSD which do not yet support
420 the getsockname() API in recent PF versions require <em>--with-nat-devpf</em>
421 to re-enable /dev/pf support when using PF firewall.
423 <tag>--disable-translation</tag>
424 <p>Default changed to prevent translating error page templates during build.
425 Use --enable-translation to explicitly build and install the templates.
426 <p>The latest pre-translated templates can be downloaded from <url url="http://www.squid-cache.org/Versions/langpack/">
431 <sect1>Removed options<label id="removedoptions">
434 <p><em>There are no removed ./configure options in Squid-3.4.</em>
439 <sect>Regressions since Squid-2.7
441 <p>Some squid.conf options which were available in Squid-2.7 are not yet available in Squid-3.4
443 <p>If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.
445 <sect1>Missing squid.conf options available in Squid-2.7
448 <tag>broken_vary_encoding</tag>
449 <p>Not yet ported from 2.6
452 <p><em>COSS</em> storage type is lacking stability fixes from 2.6
453 <p>COSS <em>overwrite-percent=</em> option not yet ported from 2.6
454 <p>COSS <em>max-stripe-waste=</em> option not yet ported from 2.6
455 <p>COSS <em>membufs=</em> option not yet ported from 2.6
456 <p>COSS <em>maxfullbufs=</em> option not yet ported from 2.6
458 <tag>cache_peer</tag>
459 <p><em>idle=</em> not yet ported from 2.7
460 <p><em>monitorinterval=</em> not yet ported from 2.6
461 <p><em>monitorsize=</em> not yet ported from 2.6
462 <p><em>monitortimeout=</em> not yet ported from 2.6
463 <p><em>monitorurl=</em> not yet ported from 2.6
465 <tag>cache_vary</tag>
466 <p>Not yet ported from 2.6
468 <tag>collapsed_forwarding</tag>
469 <p>Not yet ported from 2.6
472 <p>Not yet ported from 2.6
474 <tag>external_refresh_check</tag>
475 <p>Not yet ported from 2.7
477 <tag>location_rewrite_access</tag>
478 <p>Not yet ported from 2.6
480 <tag>location_rewrite_children</tag>
481 <p>Not yet ported from 2.6
483 <tag>location_rewrite_concurrency</tag>
484 <p>Not yet ported from 2.6
486 <tag>location_rewrite_program</tag>
487 <p>Not yet ported from 2.6
489 <tag>refresh_pattern</tag>
490 <p><em>stale-while-revalidate=</em> not yet ported from 2.7
491 <p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7
492 <p><em>negative-ttl=</em> not yet ported from 2.7
494 <tag>refresh_stale_hit</tag>
495 <p>Not yet ported from 2.7
497 <tag>update_headers</tag>
498 <p>Not yet ported from 2.7
504 Copyright (C) 1996-2015 The Squid Software Foundation and contributors
506 Squid software is distributed under GPLv2+ license and includes
507 contributions from numerous individuals and organizations.
508 Please see the COPYING and CONTRIBUTORS files for details.