Source Format Enforcement (#532)

[thirdparty/squid.git] / doc / release-notes / release-5.sgml

<!doctype linuxdoc system>
<article>
<title>Squid 5.0.0 release notes</title>
<author>Squid Developers</author>

<abstract>
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.
</abstract>

<toc>

<sect>Notice
<p>The Squid Team are pleased to announce the release of Squid-5.0.0 for testing.

This new release is available for download from <url url="http://www.squid-cache.org/Versions/v5/"> or the
 <url url="http://www.squid-cache.org/Download/http-mirrors.html" name="mirrors">.

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

<p>We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting">
   for how to submit a report with a stack trace.

<sect1>Known issues
<p>Although this release is deemed good enough for use in many setups, please note the existence of 
<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">.

<sect1>Changes since earlier releases of Squid-5
<p>
The Squid-5 change history can be <url url="http://www.squid-cache.org/Versions/v5/changesets/" name="viewed here">.


<sect>Major new features since Squid-4
<p>Squid-5 represents a new feature release above Squid-4.

<p>The most important of these new features are:
<itemize>
	<item>ICAP Trailers
	<item>Happy Eyeballs Update
	<item>Kerberos Group Helper
	<item>TrivialDB Support
</itemize>

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


<sect1>ICAP Trailers
<p>Details in <url url="https://datatracker.ietf.org/doc/draft-rousskov-icap-trailers/" name="Draft: ICAP Trailers">

<p>The <em>Trailers</em> feature from HTTP is being proposed for addition to ICAP,
   with some modifications.

<p>This implementation complies with version -01 of that draft:
<itemize>
	<item>Announces ICAP Trailer support via the ICAP Allow request header field.
	<item>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.
</itemize>

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


<sect1>Happy Eyeballs Update

<p>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.

<p>Instead of obeying <em>dns_v4_first</em> 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
   <em>--disable-ipv6</em>. 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.

<p>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.

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


<sect1>Kerberos Group Helper
<p>This release adds a sample Kerberos group authentication external_acl helper
   called <em>ext_kerberos_sid_group_acl</em>.
   It uses <em>ldapsearch</em> from OpenLDAP to lookup the name of an AD group SID.

<p>This helper must be used in with the <em>negotiate_kerberos_auth</em> helper in
   a Microsft AD or Samba environment.

<p>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.


<sect1>TrivialDB Support
<p>This release deprecates use of BerkleyDB in favour of TrivialDB.

<p>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.

<p>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.

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

<p>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.


<sect>Changes to squid.conf since Squid-4
<p>
There have been changes to Squid's configuration file since Squid-4.

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

<itemize>
	<item><ref id="newdirectives" name="New directives">
	<item><ref id="modifieddirectives" name="Changes to existing directives">
	<item><ref id="removeddirectives" name="Removed directives">
</itemize>
<p>

<sect1>New directives<label id="newdirectives">
<p>
<descrip>
	<tag>auth_schemes</tag>
	<p>New access control to customize authentication schemes presence
	   and order in Squid generated HTTP 401 (Unauthorized) and 407
	   (Proxy Authentication Required) responses.

	<tag>collapsed_forwarding_access</tag>
	<p>New access control to restrict collapsed forwarding to a subset of
	   eligible HTTP, ICP and HTCP requests.

	<tag>mark_client_connection</tag>
	<p>New access control to apply a Netfilter CONNMARK value to a TCP client
	   connection.

	<tag>mark_client_packet</tag>
	<p>New access control to apply a Netfilter MARK value to packets being
	   transmitted on a client TCP connection.

	<tag>response_delay_pool</tag>
	<p>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 <em>Squid-2.8</em> series.

	<tag>response_delay_pool_access</tag>
	<p>New access control to determines whether a specific named response
	   delay pool is used for the HTTP transaction.

</descrip>

<sect1>Changes to existing directives<label id="modifieddirectives">
<p>
<descrip>
	<tag>acl</tag>
	<p>The <em>CONNECT</em> ACL definition is now built-in.
	<p>New <em>annotate_client</em> 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.
	<p>New <em>annotate_transaction</em> 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.
	<p>Replaced <em>clientside_mark</em> with <em>client_connection_mark</em>
	   type to match Netfilter CONNMARK of the client TCP connection.

	<tag>deny_info</tag>
	<p>New code <em>%A</em> to display Squid listening IP address the client
	   TCP connection was connected to.

	<tag>logformat</tag>
	<p>New <em>ssl::&lt;cert</em> macro code to display received server X.509
	   certificate in PEM format.
	<p>New <em>CF</em> value for <em>%Ss</em> code to indicate the response
	   was handled by Collapsed Forwarding.

</descrip>

<sect1>Removed directives<label id="removeddirectives">
<p>
<descrip>
	<tag>clientside_mark</tag>
	<p>Replaced by <em>mark_client_packet</em>.

	<tag>dns_v4_first</tag>
	<p>Removed. The new "Happy Eyeballs" algorithm uses received IP
	   addresses as soon as they are needed.
	<p>Firewall rules prohibiting IPv6 TCP connections remain the preferred
	   configuration method for 'disabling' IPv6 connectivity, with DNS
	   recursive-resolver configuration also available.

</descrip>


<sect>Changes to ./configure options since Squid-4
<p>
There have been some changes to Squid's build configuration since Squid-4.

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

<itemize>
	<item><ref id="newoptions" name="New options">
	<item><ref id="modifiedoptions" name="Changes to existing options">
	<item><ref id="removedoptions" name="Removed options">
</itemize>


<sect1>New options<label id="newoptions">
<p>
<descrip>
	<tag>--without-tdb</tag>
	<p>New option to determine whether TrivialDB support is used, and
	   build against local custom installs.
	<p>Samba TrivialDB is now the preferred database used by the
	   <em>ext_session_acl</em> and <em>ext_time_quota_acl</em> helpers,
	   deprecating use of BerkleyDB.

</descrip>

<sect1>Changes to existing options<label id="modifiedoptions">
<p>
<descrip>
	<tag>--disable-optimizations</tag>
	<p>No longer implies <em>--disable-inline</em> option (which is removed).

</descrip>
</p>

<sect1>Removed options<label id="removedoptions">
<p>
<descrip>
	<tag>--disable-inline</tag>
	<p>Removed. Use compiler flags instead if necessary.

	<tag>-DUSE_CHUNKEDMEMPOOLS=1</tag>
	<p>Removed compiler flag. Use run-time environment variable <em>MEMPOOLS=1</em>
	   to enable chunked memory pools instead.

</descrip>


<sect>Regressions since Squid-2.7

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

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

<sect1>Missing squid.conf options available in Squid-2.7
<p>
<descrip>
	<tag>broken_vary_encoding</tag>
	<p>Not yet ported from 2.6

	<tag>cache_peer</tag>
	<p><em>monitorinterval=</em> not yet ported from 2.6
	<p><em>monitorsize=</em> not yet ported from 2.6
	<p><em>monitortimeout=</em> not yet ported from 2.6
	<p><em>monitorurl=</em> not yet ported from 2.6

	<tag>cache_vary</tag>
	<p>Not yet ported from 2.6

	<tag>error_map</tag>
	<p>Not yet ported from 2.6

	<tag>external_refresh_check</tag>
	<p>Not yet ported from 2.7

	<tag>location_rewrite_access</tag>
	<p>Not yet ported from 2.6

	<tag>location_rewrite_children</tag>
	<p>Not yet ported from 2.6

	<tag>location_rewrite_concurrency</tag>
	<p>Not yet ported from 2.6

	<tag>location_rewrite_program</tag>
	<p>Not yet ported from 2.6

	<tag>refresh_pattern</tag>
	<p><em>stale-while-revalidate=</em> not yet ported from 2.7
	<p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7
	<p><em>negative-ttl=</em> not yet ported from 2.7

	<tag>refresh_stale_hit</tag>
	<p>Not yet ported from 2.7

	<tag>update_headers</tag>
	<p>Not yet ported from 2.7

</descrip>

<sect>Copyright
<p>
Copyright (C) 1996-2020 The Squid Software Foundation and contributors
<p>
Squid software is distributed under GPLv2+ license and includes
contributions from numerous individuals and organizations.
Please see the COPYING and CONTRIBUTORS files for details.

</article>