1 <!doctype linuxdoc system>
3 <title>Squid 5.7 release notes</title>
4 <author>Squid Developers</author>
7 This document contains the release notes for version 5 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.
15 <p>The Squid Team are pleased to announce the release of Squid-5.7.
17 This new release is available for download from <url url="http://www.squid-cache.org/Versions/v5/"> or the
18 <url url="http://www.squid-cache.org/Download/http-mirrors.html" name="mirrors">.
20 <p>We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting">
21 for how to submit a report with a stack trace.
24 <p>Although this release is deemed good enough for use in many setups, please note the existence of
25 <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=5" name="open bugs against Squid-5">.
27 <sect1>Changes since earlier releases of Squid-5
29 The Squid-5 change history can be <url url="http://www.squid-cache.org/Versions/v5/changesets/" name="viewed here">.
32 <sect>Major new features since Squid-4
33 <p>Squid-5 represents a new feature release above Squid-4.
35 <p>The most important of these new features are:
38 <item>Happy Eyeballs Update
39 <item>Kerberos Group Helper
40 <item>TrivialDB Support
41 <item>RFC 8586: Loop Detection in Content Delivery Networks
42 <item>Peering support for SSL-Bump
43 <item>OpenSSL 3.0 Support
46 Most user-facing changes are reflected in squid.conf (see below).
50 <p>Details in <url url="https://datatracker.ietf.org/doc/draft-rousskov-icap-trailers/" name="Draft: ICAP Trailers">
52 <p>The <em>Trailers</em> feature from HTTP is being proposed for addition to ICAP,
53 with some modifications.
55 <p>This implementation complies with version -01 of that draft:
57 <item>Announces ICAP Trailer support via the ICAP Allow request header field.
58 <item>Parses the ICAP response trailer if and only if the ICAP server signals
59 its presence by sending both Trailer header and Allow/trailers in the
63 <p>For now Squid logs and ignores all parsed ICAP header fields.
66 <sect1>Happy Eyeballs Update
68 <p>Squid now uses a received IP address as soon as it is needed for request
69 forwarding instead of waiting for all of the potential forwarding
70 destinations to be fully resolved (i.e. complete both IPv4 and IPv6 domain
71 name resolution) before beginning to forward the request.
73 <p>Instead of obeying <em>dns_v4_first</em> settings, IP family usage order is
74 now primarily controlled by DNS response time: If a DNS AAAA response comes
75 first while Squid is waiting for an IP address, then Squid will use the
76 received IPv6 address(es) first. For previously cached IPs, Squid tries
77 IPv6 addresses first. To control IP address families used by Squid, admins
78 are expected to use firewalls, DNS recursive-resolver configuration, and/or
79 <em>--disable-ipv6</em>. When planning you configuration changes, please
80 keep in mind that the upcoming Happy Eyeballs improvements will favor
81 faster TCP connection establishment, decreasing the impact of DNS
84 <p>These Happy Eyeballs changes do not affect peer selection: Squid still does
85 not move on to the next selected destination until all IP addresses for the
86 previous destination have been received and tried.
88 <p>The Cache Manager <em>mgr:ipcache</em> report no longer contains
89 "IPcache Entries In Use" but that info is now available as
90 "cbdata ipcache_entry" row on the <em>mgr:mem</em> page.
93 <sect1>Kerberos Group Helper
94 <p>This release adds a sample Kerberos group authentication external_acl helper
95 called <em>ext_kerberos_sid_group_acl</em>.
96 It uses <em>ldapsearch</em> from OpenLDAP to lookup the name of an AD group SID.
98 <p>This helper must be used in with the <em>negotiate_kerberos_auth</em> helper in
99 a Microsft AD or Samba environment.
101 <p>It reads from the standard input the domain username and a list of group SIDs
102 and tries to match the group SIDs to the AD group SIDs.
105 <sect1>TrivialDB Support
106 <p>This release deprecates use of BerkleyDB in favour of TrivialDB.
108 <p>The BerkleyDB library code has been moved under a copyright licence which
109 causes problems for many OS distributors. The result of that is that most
110 are no longer providing the latest security supported libdb version.
112 <p>TrivialDB by comparison has better OS support and security updates along
113 with functionality differences that resolve some long standing issues
114 libdb suffered with parallel concurrent access to the database.
116 <p>The <em>ext_session_acl</em> and <em>ext_time_quota_acl</em> helpers may
117 now be built with either libdb or libtdb. Preferring libtdb if both are
118 enabled or auto-detected at build time. Use the <em>--without-tdb</em>
119 build option to retain BerkleyDB support.
121 <p>Please note that the database formats are not guaranteed to be identical.
122 So when migrating it is recommended to erase the database file(s) and use
123 the helpers functionality to rebuild it as needed.
126 <sect1>Loop Detection in Content Delivery Networks
127 <p>Details in <url url="https://tools.ietf.org/html/rfc8586" name="RFC 8586">
129 <p>Squid now uses the CDN-Loop header as a source for loop detection.
131 <p>This header is only relevant to CDN installations. For which the
132 <em>surrogate_id</em> configuration directive specifies the authoritative
135 <p>Squid does not add this header by default, preferring to use the
136 Via mechanism instead. Administrators may add it to requests
137 with the <em>request_header_add</em> directive or remove with
138 <em>request_header_remove</em>.
141 <sect1>Peering support for SSL-Bump
142 <p>Squid now supports forwarding of bumped, re-encrypted HTTPS requests through
143 a <em>cache_peer</em> using a standard HTTP CONNECT tunnel.
145 <p>No support for triggering client authentication when a <em>cache_peer</em>
146 configuration instructs the bumping Squid to relay authentication info
147 contained in client CONNECT request. The bumping Squid still responds
148 with HTTP 200 (Connection Established) to the client CONNECT request (to
149 see TLS client handshake) <em>before</em> selecting the cache_peer.
151 <p>HTTPS cache_peers are not yet supported primarily because Squid cannot
155 <sect1>OpenSSL 3.0 Support
156 <p>Squid-5.7 adds OpenSSL 3.0 support.
158 <p>This version of Squid does not add any of the new features provided by
159 OpenSSL 3.0. It only contains support for features already supported by prior
160 versions of Squid using new APIs provided by OpenSSL 3.0.
162 <p>Notably the libssl custom Engine feature has been deprecated by OpenSSL 3.0
163 and new Providers replacement is not supported by this Squid.
165 <p>OpenSSL 3.0 uses new licensing terms.
168 <sect>Changes to squid.conf since Squid-4
170 There have been changes to Squid's configuration file since Squid-4.
172 This section gives a thorough account of those changes in three categories:
175 <item><ref id="newdirectives" name="New directives">
176 <item><ref id="modifieddirectives" name="Changes to existing directives">
177 <item><ref id="removeddirectives" name="Removed directives">
181 <sect1>New directives<label id="newdirectives">
184 <tag>auth_schemes</tag>
185 <p>New access control to customize authentication schemes presence
186 and order in Squid generated HTTP 401 (Unauthorized) and 407
187 (Proxy Authentication Required) responses.
189 <tag>collapsed_forwarding_access</tag>
190 <p>New access control to restrict collapsed forwarding to a subset of
191 eligible HTTP, ICP and HTCP requests.
193 <tag>happy_eyeballs_connect_gap</tag>
194 <p>New directive to specify the minimum delay between opening spare
195 connections to any server.
197 <tag>happy_eyeballs_connect_limit</tag>
198 <p>New directive to specify the maximum number of spare connections
201 <tag>happy_eyeballs_connect_timeout</tag>
202 <p>New directive to specify the minimum delay between opening a
203 primary to-server connection and opening a spare to-server
204 connection for the same transaction.
206 <tag>http_upgrade_request_protocols</tag>
207 <p>New directive to control client-initiated and server-confirmed
208 switching from HTTP to another protocol using HTTP/1.1 Upgrade
211 <tag>mark_client_connection</tag>
212 <p>New access control to apply a Netfilter CONNMARK value to a TCP client
215 <tag>mark_client_packet</tag>
216 <p>New access control to apply a Netfilter MARK value to packets being
217 transmitted on a client TCP connection.
219 <tag>response_delay_pool</tag>
220 <p>New access control to configure client response bandwidth limits.
221 This feature is a port and update of the class 6 / Client Delay Pools
222 feature planned for the abandoned <em>Squid-2.8</em> series.
224 <tag>response_delay_pool_access</tag>
225 <p>New access control to determines whether a specific named response
226 delay pool is used for the HTTP transaction.
228 <tag>shared_transient_entries_limit</tag>
229 <p>Replacement for <em>collapsed_forwarding_shared_entries_limit</em>.
233 <sect1>Changes to existing directives<label id="modifieddirectives">
237 <p>The <em>CONNECT</em> ACL definition is now built-in.
238 <p>New <em>annotate_client</em> type to annotate a client TCP connection.
239 These annotations can be used by other ACLs, logs or helpers and
240 persist until the client TCP connection is closed.
241 <p>New <em>annotate_transaction</em> type to annotate an HTTP transaction.
242 Annotations can be used by other ACLs or helpers and persist until
243 logging of the HTTP transaction is completed.
244 <p>New value <em>GeneratingCONNECT</em> for the <em>at_step</em> type to
245 match when Squid is about to send a CONNECT request to a cache peer.
246 <p>Replaced <em>clientside_mark</em> with <em>client_connection_mark</em>
247 type to match Netfilter CONNMARK of the client TCP connection.
249 <tag>auth_param</tag>
250 <p>New <em>reservation-timeout=</em> option to allow NTLM and Negotiate
251 helpers to forget about clients with outstanding authentication
253 <p>Added support for CP1251 charset conversion when <em>utf8</em> option
256 <tag>authenticate_cache_garbage_interval</tag>
257 <p>Now disabled when <em>--disable-auth</em> build parameter is used.
259 <tag>authenticate_ttl</tag>
260 <p>Now disabled when <em>--disable-auth</em> build parameter is used.
262 <tag>authenticate_ip_ttl</tag>
263 <p>Now disabled when <em>--disable-auth</em> build parameter is used.
266 <p>New code <em>A</em> to display Squid listening IP address the client
267 TCP connection was connected to.
269 <tag>esi_parser</tag>
270 <p>Squid-4 removal of the custom parser introduced a bug which caused
271 the default ESI parser library to be unpredictable. Squid-5.5 release
272 restores the documented default of libxml2 as most preferred, with
273 libexpat as alternative.
276 <p>New <em>worker-queues</em> option to have TCP stack maintain dedicated
277 listening queue for each worker in SMP.
279 <tag>https_port</tag>
280 <p>New <em>worker-queues</em> option to have TCP stack maintain dedicated
281 listening queue for each worker in SMP.
282 <p>New <em>CONDITIONAL_AUTH</em> flag for <em>sslflags=</em> option to
283 request client certificate(s) but not reject clients without any.
284 <p>Squid-5.5 will no longer use <em>tls-clientca=</em> certificates
285 as possible intermediary CA for the server CA certificate chain when
286 OpenSSL library supports <em>SSL_MODE_NO_AUTO_CHAIN</em> mode.
289 <p>New <em>ssl::<cert</em> macro code to display received server X.509
290 certificate in PEM format.
291 <p>New <em>proxy_protocol::>h</em> code to display received PROXY
292 protocol version 2 TLV values.
293 <p>New <em>master_xaction</em> code to display Squids internal
295 <p>New <em>CF</em> value for <em>Ss</em> code to indicate the response
296 was handled by Collapsed Forwarding.
297 <p>New <em>TLS/1.3</em> value for <em>ssl::<negotiated_version</em>
298 code to indicate the request was received from client using TLS/1.3.
299 <p>New <em>TLS/1.3</em> value for <em>ssl::>negotiated_version</em>
300 code to indicate the response was received from server using TLS/1.3.
301 <p>Codes <em>rm</em>, <em><rm</em> and <em>>rm</em> display "-"
302 instead of the made-up method NONE.
304 <tag>ssl_engine</tag>
305 <p>OpenSSL 3.0 deprecates the Engine feature. This directive is
306 only supported when Squid is built for older OpenSSL versions.
310 <sect1>Removed directives<label id="removeddirectives">
313 <tag>clientside_mark</tag>
314 <p>Replaced by <em>mark_client_packet</em>.
316 <tag>collapsed_forwarding_shared_entries_limit</tag>
317 <p>Replaced by <em>shared_transient_entries_limit</em>.
319 <tag>dns_v4_first</tag>
320 <p>Removed. The new "Happy Eyeballs" algorithm uses received IP
321 addresses as soon as they are needed.
322 <p>Firewall rules prohibiting IPv6 TCP connections remain the preferred
323 configuration method for 'disabling' IPv6 connectivity, with DNS
324 recursive-resolver configuration also available.
329 <sect>Changes to ./configure options since Squid-4
331 There have been some changes to Squid's build configuration since Squid-4.
333 This section gives an account of those changes in three categories:
336 <item><ref id="newoptions" name="New options">
337 <item><ref id="modifiedoptions" name="Changes to existing options">
338 <item><ref id="removedoptions" name="Removed options">
342 <sect1>New options<label id="newoptions">
345 <tag>--without-ldap</tag>
346 <p>New option to determine whether LDAP support is used, and
347 build against local custom installs.
348 <p>This will prevent all helper binaries depending on LDAP
349 from being auto-built.
351 <tag>--without-tdb</tag>
352 <p>New option to determine whether TrivialDB support is used, and
353 build against local custom installs.
354 <p>Samba TrivialDB is now the preferred database used by the
355 <em>ext_session_acl</em> and <em>ext_time_quota_acl</em> helpers,
356 deprecating use of BerkleyDB.
360 <sect1>Changes to existing options<label id="modifiedoptions">
363 <tag>--disable-optimizations</tag>
364 <p>No longer implies <em>--disable-inline</em> option (which is removed).
366 <tag>--enable-external-acl-helpers</tag>
367 <p>New helper type <em>kerberos_sid_group</em> to match <em>group=</em>
368 annotations AD Domain group SID.
373 <sect1>Removed options<label id="removedoptions">
376 <tag>--disable-inline</tag>
377 <p>Removed. Use compiler flags instead if necessary.
379 <tag>-DUSE_CHUNKEDMEMPOOLS=1</tag>
380 <p>Removed compiler flag. Use run-time environment variable <em>MEMPOOLS=1</em>
381 to enable chunked memory pools instead.
386 <sect>Regressions since Squid-2.7
388 <p>Some squid.conf options which were available in Squid-2.7 are not yet available in Squid-5
390 <p>If you need something to do then porting one of these from Squid-2 is most welcome.
392 <sect1>Missing squid.conf options available in Squid-2.7
395 <tag>broken_vary_encoding</tag>
396 <p>Not yet ported from 2.6
398 <tag>cache_peer</tag>
399 <p><em>monitorinterval=</em> not yet ported from 2.6
400 <p><em>monitorsize=</em> not yet ported from 2.6
401 <p><em>monitortimeout=</em> not yet ported from 2.6
402 <p><em>monitorurl=</em> not yet ported from 2.6
404 <tag>cache_vary</tag>
405 <p>Not yet ported from 2.6
408 <p>Not yet ported from 2.6
410 <tag>external_refresh_check</tag>
411 <p>Not yet ported from 2.7
413 <tag>location_rewrite_access</tag>
414 <p>Not yet ported from 2.6
416 <tag>location_rewrite_children</tag>
417 <p>Not yet ported from 2.6
419 <tag>location_rewrite_concurrency</tag>
420 <p>Not yet ported from 2.6
422 <tag>location_rewrite_program</tag>
423 <p>Not yet ported from 2.6
425 <tag>refresh_pattern</tag>
426 <p><em>stale-while-revalidate=</em> not yet ported from 2.7
427 <p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7
428 <p><em>negative-ttl=</em> not yet ported from 2.7
430 <tag>refresh_stale_hit</tag>
431 <p>Not yet ported from 2.7
433 <tag>update_headers</tag>
434 <p>Not yet ported from 2.7
440 Copyright (C) 1996-2023 The Squid Software Foundation and contributors
442 Squid software is distributed under GPLv2+ license and includes
443 contributions from numerous individuals and organizations.
444 Please see the COPYING and CONTRIBUTORS files for details.