doc/release-notes/release-5.sgml

   1 <!doctype linuxdoc system>
   2 <article>
   3 <title>Squid 5.7 release notes</title>
   4 <author>Squid Developers</author>
   5
   6 <abstract>
   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.
  10 </abstract>
  11
  12 <toc>
  13
  14 <sect>Notice
  15 <p>The Squid Team are pleased to announce the release of Squid-5.7.
  16
  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">.
  19
  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.
  22
  23 <sect1>Known issues
  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&amp;product=Squid&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;version=5" name="open bugs against Squid-5">.
  26
  27 <sect1>Changes since earlier releases of Squid-5
  28 <p>
  29 The Squid-5 change history can be <url url="http://www.squid-cache.org/Versions/v5/changesets/" name="viewed here">.
  30
  31
  32 <sect>Major new features since Squid-4
  33 <p>Squid-5 represents a new feature release above Squid-4.
  34
  35 <p>The most important of these new features are:
  36 <itemize>
  37         <item>ICAP Trailers
  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
  44 </itemize>
  45
  46 Most user-facing changes are reflected in squid.conf (see below).
  47
  48
  49 <sect1>ICAP Trailers
  50 <p>Details in <url url="https://datatracker.ietf.org/doc/draft-rousskov-icap-trailers/" name="Draft: ICAP Trailers">
  51
  52 <p>The <em>Trailers</em> feature from HTTP is being proposed for addition to ICAP,
  53    with some modifications.
  54
  55 <p>This implementation complies with version -01 of that draft:
  56 <itemize>
  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
  60                 ICAP response.
  61 </itemize>
  62
  63 <p>For now Squid logs and ignores all parsed ICAP header fields.
  64
  65
  66 <sect1>Happy Eyeballs Update
  67
  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.
  72
  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
  82    resolution timing.
  83
  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.
  87
  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.
  91
  92
  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.
  97
  98 <p>This helper must be used in with the <em>negotiate_kerberos_auth</em> helper in
  99    a Microsft AD or Samba environment.
 100
 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.
 103
 104
 105 <sect1>TrivialDB Support
 106 <p>This release deprecates use of BerkleyDB in favour of TrivialDB.
 107
 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.
 111
 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.
 115
 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.
 120
 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.
 124
 125
 126 <sect1>Loop Detection in Content Delivery Networks
 127 <p>Details in <url url="https://tools.ietf.org/html/rfc8586" name="RFC 8586">
 128
 129 <p>Squid now uses the CDN-Loop header as a source for loop detection.
 130
 131 <p>This header is only relevant to CDN installations. For which the
 132    <em>surrogate_id</em> configuration directive specifies the authoritative
 133    ID.
 134
 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>.
 139
 140
 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.
 144
 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.
 150
 151 <p>HTTPS cache_peers are not yet supported primarily because Squid cannot
 152    yet do TLS-in-TLS.
 153
 154
 155 <sect1>OpenSSL 3.0 Support
 156 <p>Squid-5.7 adds OpenSSL 3.0 support.
 157
 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.
 161
 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.
 164
 165 <p>OpenSSL 3.0 uses new licensing terms.
 166
 167
 168 <sect>Changes to squid.conf since Squid-4
 169 <p>
 170 There have been changes to Squid's configuration file since Squid-4.
 171
 172 This section gives a thorough account of those changes in three categories:
 173
 174 <itemize>
 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">
 178 </itemize>
 179 <p>
 180
 181 <sect1>New directives<label id="newdirectives">
 182 <p>
 183 <descrip>
 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.
 188
 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.
 192
 193         <tag>happy_eyeballs_connect_gap</tag>
 194         <p>New directive to specify the minimum delay between opening spare
 195            connections to any server.
 196
 197         <tag>happy_eyeballs_connect_limit</tag>
 198         <p>New directive to specify the maximum number of spare connections
 199            to any server.
 200
 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.
 205
 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
 209            mechanism.
 210
 211         <tag>mark_client_connection</tag>
 212         <p>New access control to apply a Netfilter CONNMARK value to a TCP client
 213            connection.
 214
 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.
 218
 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.
 223
 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.
 227
 228         <tag>shared_transient_entries_limit</tag>
 229         <p>Replacement for <em>collapsed_forwarding_shared_entries_limit</em>.
 230
 231 </descrip>
 232
 233 <sect1>Changes to existing directives<label id="modifieddirectives">
 234 <p>
 235 <descrip>
 236         <tag>acl</tag>
 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.
 248
 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
 252            requests.
 253         <p>Added support for CP1251 charset conversion when <em>utf8</em> option
 254            is configured.
 255
 256         <tag>authenticate_cache_garbage_interval</tag>
 257         <p>Now disabled when <em>--disable-auth</em> build parameter is used.
 258
 259         <tag>authenticate_ttl</tag>
 260         <p>Now disabled when <em>--disable-auth</em> build parameter is used.
 261
 262         <tag>authenticate_ip_ttl</tag>
 263         <p>Now disabled when <em>--disable-auth</em> build parameter is used.
 264
 265         <tag>deny_info</tag>
 266         <p>New code <em>A</em> to display Squid listening IP address the client
 267            TCP connection was connected to.
 268
 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.
 274
 275         <tag>http_port</tag>
 276         <p>New <em>worker-queues</em> option to have TCP stack maintain dedicated
 277            listening queue for each worker in SMP.
 278
 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.
 287
 288         <tag>logformat</tag>
 289         <p>New <em>ssl::&lt;cert</em> macro code to display received server X.509
 290            certificate in PEM format.
 291         <p>New <em>proxy_protocol::&gt;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
 294            transaction ID.
 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::&lt;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::&gt;negotiated_version</em>
 300             code to indicate the response was received from server using TLS/1.3.
 301         <p>Codes <em>rm</em>, <em>&lt;rm</em> and <em>&gt;rm</em> display "-"
 302            instead of the made-up method NONE.
 303
 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.
 307
 308 </descrip>
 309
 310 <sect1>Removed directives<label id="removeddirectives">
 311 <p>
 312 <descrip>
 313         <tag>clientside_mark</tag>
 314         <p>Replaced by <em>mark_client_packet</em>.
 315
 316         <tag>collapsed_forwarding_shared_entries_limit</tag>
 317         <p>Replaced by <em>shared_transient_entries_limit</em>.
 318
 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.
 325
 326 </descrip>
 327
 328
 329 <sect>Changes to ./configure options since Squid-4
 330 <p>
 331 There have been some changes to Squid's build configuration since Squid-4.
 332
 333 This section gives an account of those changes in three categories:
 334
 335 <itemize>
 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">
 339 </itemize>
 340
 341
 342 <sect1>New options<label id="newoptions">
 343 <p>
 344 <descrip>
 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.
 350
 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.
 357
 358 </descrip>
 359
 360 <sect1>Changes to existing options<label id="modifiedoptions">
 361 <p>
 362 <descrip>
 363         <tag>--disable-optimizations</tag>
 364         <p>No longer implies <em>--disable-inline</em> option (which is removed).
 365
 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.
 369
 370 </descrip>
 371 </p>
 372
 373 <sect1>Removed options<label id="removedoptions">
 374 <p>
 375 <descrip>
 376         <tag>--disable-inline</tag>
 377         <p>Removed. Use compiler flags instead if necessary.
 378
 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.
 382
 383 </descrip>
 384
 385
 386 <sect>Regressions since Squid-2.7
 387
 388 <p>Some squid.conf options which were available in Squid-2.7 are not yet available in Squid-5
 389
 390 <p>If you need something to do then porting one of these from Squid-2 is most welcome.
 391
 392 <sect1>Missing squid.conf options available in Squid-2.7
 393 <p>
 394 <descrip>
 395         <tag>broken_vary_encoding</tag>
 396         <p>Not yet ported from 2.6
 397
 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
 403
 404         <tag>cache_vary</tag>
 405         <p>Not yet ported from 2.6
 406
 407         <tag>error_map</tag>
 408         <p>Not yet ported from 2.6
 409
 410         <tag>external_refresh_check</tag>
 411         <p>Not yet ported from 2.7
 412
 413         <tag>location_rewrite_access</tag>
 414         <p>Not yet ported from 2.6
 415
 416         <tag>location_rewrite_children</tag>
 417         <p>Not yet ported from 2.6
 418
 419         <tag>location_rewrite_concurrency</tag>
 420         <p>Not yet ported from 2.6
 421
 422         <tag>location_rewrite_program</tag>
 423         <p>Not yet ported from 2.6
 424
 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
 429
 430         <tag>refresh_stale_hit</tag>
 431         <p>Not yet ported from 2.7
 432
 433         <tag>update_headers</tag>
 434         <p>Not yet ported from 2.7
 435
 436 </descrip>
 437
 438 <sect>Copyright
 439 <p>
 440 Copyright (C) 1996-2023 The Squid Software Foundation and contributors
 441 <p>
 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.
 445
 446 </article>