# Squid 5.7 release notes

## Squid Developers

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

- 1.1 Known issues
- 1.2 Changes since earlier releases of Squid-5

## 2. Major new features since Squid-4

- 2.1 ICAP Trailers
- 2.2 Happy Eyeballs Update
- 2.3 Kerberos Group Helper
- 2.4 TrivialDB Support
- 2.5 Loop Detection in Content Delivery Networks
- 2.6 Peering support for SSL-Bump
- 2.7 OpenSSL 3.0 Support

## 3. Changes to squid.conf since Squid-4

- 3.1 New directives
- 3.2 Changes to existing directives
- 3.3 Removed directives

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

- 4.1 New options
- 4.2 Changes to existing options
- 4.3 Removed options

## 5. Regressions since Squid-2.7

- 5.1 Missing squid.conf options available in Squid-2.7

## 6. Copyright

## 1. Notice

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

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

We welcome feedback and bug reports. If you find a bug, please see http://wiki.squid-cache.org/SquidFaq/BugReporting 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-5.

## 1.2 Changes since earlier releases of Squid-5

The Squid-5 change history can be viewed here.

## 2. Major new features since Squid-4

Squid-5 represents a new feature release above Squid-4.

The most important of these new features are:

- ICAP Trailers
- Happy Eyeballs Update
- Kerberos Group Helper
- TrivialDB Support
- RFC 8586: Loop Detection in Content Delivery Networks
- Peering support for SSL-Bump
- OpenSSL 3.0 Support

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

## 2.1 ICAP Trailers

Details in Draft: ICAP Trailers

The Trailers feature from HTTP is being proposed for addition to ICAP, with some modifications.

This implementation complies with version -01 of that draft:

- Announces ICAP Trailer support via the ICAP Allow request header field.
- Parses the ICAP response trailer if and only if the ICAP server signals its presence by sending both Trailer header and Allow/trailers in the ICAP response.

For now Squid logs and ignores all parsed ICAP header fields.

## 2.2 Happy Eyeballs Update

Squid now uses a received IP address as soon as it is needed for request forwarding instead of waiting for all of the potential forwarding destinations to be fully resolved (i.e. complete both IPv4 and IPv6 domain name resolution) before beginning to forward the request.

Instead of obeying dns_v4_first settings, IP family usage order is now primarily controlled by DNS response time: If a DNS AAAA response comes first while Squid is waiting for an IP address, then Squid will use the received IPv6 address(es) first. For previously cached IPs, Squid tries IPv6 addresses first. To control IP address families used by Squid, admins are expected to use firewalls, DNS recursive-resolver configuration, and/or --disable-ipv6. When planning you configuration changes, please keep in mind that the upcoming Happy Eyeballs improvements will favor faster TCP connection establishment, decreasing the impact of DNS resolution timing.

These Happy Eyeballs changes do not affect peer selection: Squid still does not move on to the next selected destination until all IP addresses for the previous destination have been received and tried.

The Cache Manager mgr:ipcache report no longer contains "IPcache Entries In Use" but that info is now available as "cbdata ipcache_entry" row on the mgr:mem page.

## 2.3 Kerberos Group Helper

This release adds a sample Kerberos group authentication external_acl helper called ext_kerberos_sid_group_acl. It uses ldapsearch from OpenLDAP to lookup the name of an AD group SID.

This helper must be used in with the negotiate_kerberos_auth helper in a Microsft AD or Samba environment.

It reads from the standard input the domain username and a list of group SIDs and tries to match the group SIDs to the AD group SIDs.

## 2.4 TrivialDB Support

This release deprecates use of BerkleyDB in favour of TrivialDB.

The BerkleyDB library code has been moved under a copyright licence which causes problems for many OS distributors. The result of that is that most are no longer providing the latest security supported libdb version.

TrivialDB by comparison has better OS support and security updates along with functionality differences that resolve some long standing issues libdb suffered with parallel concurrent access to the database.

The ext_session_acl and ext_time_quota_acl helpers may now be built with either libdb or libtdb. Preferring libtdb if both are enabled or auto-detected at build time. Use the --without-tdb build option to retain BerkleyDB support.

Please note that the database formats are not guaranteed to be identical. So when migrating it is recommended to erase the database file(s) and use the helpers functionality to rebuild it as needed.

## 2.5 Loop Detection in Content Delivery Networks

Details in RFC 8586

Squid now uses the CDN-Loop header as a source for loop detection.

This header is only relevant to CDN installations. For which the surrogate_id configuration directive specifies the authoritative ID.

Squid does not add this header by default, preferring to use the Via mechanism instead. Administrators may add it to requests with the request_header_add directive or remove with request_header_remove.

## 2.6 Peering support for SSL-Bump

Squid now supports forwarding of bumped, re-encrypted HTTPS requests through a cache_peer using a standard HTTP CONNECT tunnel.

No support for triggering client authentication when a cache_peer configuration instructs the bumping Squid to relay authentication info contained in client CONNECT request. The bumping Squid still responds with HTTP 200 (Connection Established) to the client CONNECT request (to see TLS client handshake) before selecting the cache_peer.

HTTPS cache_peers are not yet supported primarily because Squid cannot yet do TLS-in-TLS.

## 2.7 OpenSSL 3.0 Support

Squid-5.7 adds OpenSSL 3.0 support.

This version of Squid does not add any of the new features provided by OpenSSL 3.0. It only contains support for features already supported by prior versions of Squid using new APIs provided by OpenSSL 3.0.

Notably the libssl custom Engine feature has been deprecated by OpenSSL 3.0 and new Providers replacement is not supported by this Squid.

OpenSSL 3.0 uses new licensing terms.

## 3. Changes to squid.conf since Squid-4

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

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

- New directives
- Changes to existing directives
- Removed directives

## 3.1 New directives

auth_schemes

  New access control to customize authentication schemes presence and order in Squid generated HTTP 401 (Unauthorized) and 407 (Proxy Authentication Required) responses.

collapsed_forwarding_access

  New access control to restrict collapsed forwarding to a subset of eligible HTTP, ICP and HTCP requests.

happy_eyeballs_connect_gap

  New directive to specify the minimum delay between opening spare connections to any server.

happy_eyeballs_connect_limit

  New directive to specify the maximum number of spare connections to any server.

happy_eyeballs_connect_timeout

  New directive to specify the minimum delay between opening a primary to-server connection and opening a spare to-server connection for the same transaction.

http_upgrade_request_protocols

  New directive to control client-initiated and server-confirmed switching from HTTP to another protocol using HTTP/1.1 Upgrade mechanism.

mark_client_connection

  New access control to apply a Netfilter CONNMARK value to a TCP client connection.

mark_client_packet

  New access control to apply a Netfilter MARK value to packets being transmitted on a client TCP connection.

response_delay_pool

  New access control to configure client response bandwidth limits. This feature is a port and update of the class 6 / Client Delay Pools feature planned for the abandoned Squid-2.8 series.

response_delay_pool_access

  New access control to determines whether a specific named response delay pool is used for the HTTP transaction.

shared_transient_entries_limit

  Replacement for collapsed_forwarding_shared_entries_limit.

## 3.2 Changes to existing directives

acl

  The CONNECT ACL definition is now built-in.

  New annotate_client type to annotate a client TCP connection. These annotations can be used by other ACLs, logs or helpers and persist until the client TCP connection is closed.

  New annotate_transaction type to annotate an HTTP transaction. Annotations can be used by other ACLs or helpers and persist until logging of the HTTP transaction is completed.

  New value GeneratingCONNECT for the at_step type to match when Squid is about to send a CONNECT request to a cache peer.

  Replaced clientside_mark with client_connection_mark type to match Netfilter CONNMARK of the client TCP connection.

auth_param

  New reservation-timeout= option to allow NTLM and Negotiate helpers to forget about clients with outstanding authentication requests.

  Added support for CP1251 charset conversion when utf8 option is configured.

authenticate_cache_garbage_interval

  Now disabled when --disable-auth build parameter is used.

authenticate_ttl

  Now disabled when --disable-auth build parameter is used.

authenticate_ip_ttl

  Now disabled when --disable-auth build parameter is used.

deny_info

  New code A to display Squid listening IP address the client TCP connection was connected to.

esi_parser

  Squid-4 removal of the custom parser introduced a bug which caused the default ESI parser library to be unpredictable. Squid-5.5 release restores the documented default of libxml2 as most preferred, with libexpat as alternative.

http_port

  New worker-queues option to have TCP stack maintain dedicated listening queue for each worker in SMP.

https_port

  New worker-queues option to have TCP stack maintain dedicated listening queue for each worker in SMP.

  New CONDITIONAL_AUTH flag for sslflags= option to request client certificate(s) but not reject clients without any.

  Squid-5.5 will no longer use tls-clientca= certificates as possible intermediary CA for the server CA certificate chain when OpenSSL library supports SSL_MODE_NO_AUTO_CHAIN mode.

logformat

  New ssl::<cert macro code to display received server X.509 certificate in PEM format.

  New proxy_protocol::>h code to display received PROXY protocol version 2 TLV values.

  New master_xaction code to display Squids internal transaction ID.

  New CF value for Ss code to indicate the response was handled by Collapsed Forwarding.

  New TLS/1.3 value for ssl::>negotiated_version code to indicate the request was received from client using TLS/1.3.

  New TLS/1.3 value for ssl::<negotiated_version code to indicate the response was received from server using TLS/1.3.

  Codes rm, <rm and >rm display "-" instead of the made-up method NONE.

ssl_engine

  OpenSSL 3.0 deprecates the Engine feature. This directive is only supported when Squid is built for older OpenSSL versions.

## 3.3 Removed directives

clientside_mark

  Replaced by mark_client_packet.

collapsed_forwarding_shared_entries_limit

  Replaced by shared_transient_entries_limit.

dns_v4_first

  Removed. The new "Happy Eyeballs" algorithm uses received IP addresses as soon as they are needed.

  Firewall rules prohibiting IPv6 TCP connections remain the preferred configuration method for 'disabling' IPv6 connectivity, with DNS recursive-resolver configuration also available.

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

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

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

- New options
- Changes to existing options
- Removed options

## 4.1 New options

--without-tdb

  New option to determine whether TrivialDB support is used, and build against local custom installs.

  Samba TrivialDB is now the preferred database used by the ext_session_acl and ext_time_quota_acl helpers, deprecating use of BerkleyDB.

## 4.2 Changes to existing options

--disable-optimizations

  No longer implies --disable-inline option (which is removed).

--enable-external-acl-helpers

  New helper type kerberos_sid_group to match group= annotations AD Domain group SID.

## 4.3 Removed options

--disable-inline

  Removed. Use compiler flags instead if necessary.

-DUSE_CHUNKEDMEMPOOLS=1

  Removed compiler flag. Use run-time environment variable MEMPOOLS=1 to enable chunked memory pools instead.

## 5. Regressions since Squid-2.7

Some squid.conf options which were available in Squid-2.7 are not yet available in Squid-5

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

## 5.1 Missing squid.conf options available in Squid-2.7

broken_vary_encoding

  Not yet ported from 2.6

cache_peer

  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

error_map

  Not yet ported from 2.6

external_refresh_check

  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

refresh_pattern

  stale-while-revalidate= not yet ported from 2.7

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

  negative-ttl= not yet ported from 2.7

refresh_stale_hit

  Not yet ported from 2.7

update_headers

  Not yet ported from 2.7

## 6. Copyright

Copyright (C) 1996-2022 The Squid Software Foundation and contributors

Squid software is distributed under GPLv2+ license and includes contributions from numerous individuals and organizations. Please see the COPYING and CONTRIBUTORS files for details.