Author: Adrian Chadd <adrian@squid-cache.org>

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

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

<abstract>
This document contains the release notes for version 3.1 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-3.1.0.9 for testing.

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

A large number of the show-stopper bugs have been fixed along with general improvements to the ICAP support.
While this release is not deemed ready for production use, we believe it is ready for wider testing by the community.

We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/TroubleShooting#head-7067fc0034ce967e67911becaabb8c95a34d576d"> 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://www.squid-cache.org/bugs/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;target_milestone=3.1&amp;long_desc_type=allwordssubstr&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;status_whiteboard_type=allwordssubstr&amp;status_whiteboard=&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;emailtype1=substring&amp;email1=&amp;emailtype2=substring&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=bugs.bug_severity&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=" name="open bugs against Squid-3.1">.

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

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

The most important of these new features are:

<itemize>
	<item>New Version Numbering System
	<item>Minimal squid.conf improvements
	<item>Native IPv6 Support
	<item>Error Page Localization
	<item>Connection Pinning (for NTLM Auth Passthrough)
	<item>Quality of Service (QoS) Flow support
	<item>SSL Bump (for HTTPS Filtering and Adaptation)
	<item>eCAP Adaptation Module support
</itemize>

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

<sect1>New Version Numbering System

<p>Begining with 3.1 the Squid Developers are trialling a new release numbering system.

<p>We have decided, based on input from interested users to drop the Squid-2 terminology of
   (DEVEL, PRE, RC, and STABLE) from the release package names.
These are replaced with a simpler 3-tier system based around the natural code development cycle.

<p>Daily generated snapshots of all current versions are provided as testing (old DEVEL) and bug-fix releases.
These are numbered from their last release with a date appended.
Snapshots generated from 3.HEAD continue to be highly volatile.

<p>Regular feature releases from Squid-3 will be branched out as sub-versions. Such as this Squid-3.1.

<p>All this is previous policy you should be accustomed to. Now we get to the new numbering change.

<p>Initial branch packages will be generated with a 3.X.0.Z version as testing packages.
Packages and Snapshots generated with these 3-dot numbers are expected to be relatively stable regarding feature behaviors.
Suitable for testing, but without any guarantees under production loads. This replaces both the old PRE and RC packages.

<p>If a large number of bugs are found several *.0.Z packages may be attempted before any is considered production-ready.

<p>When one of these Squid-3.X.0.Z packages passes our bug-free standards a 3.X.Y numbered release will be made.

<p>We can only hope enough testing has been done to consider these ready for production use.
As always we are fully dependent on people testing the previous packages and reporting all bugs.

<p>In support of all this are several squid-dev process changes which have been worked out over the last year.

<itemize>
<item>We no longer accept new features into branches.
     Those are reserved for the next feature release.
     The cycle for major releases is hoped to be fast enough to suit some peoples needs for new features
     and others need for stability in the branched releases.

<item>We now audit and vote on all feature and major code additions.
     Requiring at least two sets of developer eyes on any new features before they are committed to 3.HEAD.
     Vastly reducing the number of bugs in all code.

<item>We have implemented and continue to add more testing infrastructure.
</itemize>


<sect1>Minimal squid.conf improvements

<p>squid.conf has undergone a facelift.

<p>Don't worry, few operational changes have been made.
Older configs from are still expected to run in 3.1 with only the usual minor
changes seen between major release. Details on those are listed below.

<p>New users will be relieved to see a short 32-line or less squid.conf on clean installs.
Many of the options have reasonable defaults but had previously needed them explicitly configured!
These are now proper built-in defaults and no longer need to be in squid.conf unless changed.

<p>All of the option documentation has been offloaded to another file <em>squid.conf.documented</em> which
contains a fully documented set of options previously cluttering up squid.conf itself.

<p>Package maintainers are provided with a second file squid.conf.default which as always contains the default
config options provided on a clean install.


<sect1>Internet Protocol version 6 (IPv6)

<p>Squid 3.1 supports IPv6.
   Details in <url url="http://wiki.squid-cache.org/Features/IPv6" name="The Squid wiki">

<sect2>New Features for IPv6

<p>Squid handles localhost values seperately. For the purpose of ACLs and also external
 connections ::1 is considered a seperate IP from 127.0.0.1. This means all ACL which
 define behaviour for localhost may need ::1/128 included.

<p>Pinger has been upgraded to perform both ICMP and ICMPv6 as required.
 As a result of this and due to a change in the binary protocol format between them,
 new builds of squid are no longer backwards-compatible with old pinger binaries.
 You will need to perform "make install-pinger" again after installing squid.

<p>Peer and Client SNMP tables have been altered to handle IPv6 addresses.
 As a side effect of this the long-missing fix to show seperate named peers on one IP
 has been integrated. Making the SNMP peer table now produce correct output.
 The table structure change is identical for both IPv4-only and Dual modes but with
 IPv4-only simply not including any IPv6 entries. This means any third-party SNMP
 software which hard coded the MIB paths needs to be upgraded for this Squid release.


<sect2>Limitations of IPv6 Support

<p>Specify a specific tcp_outgoing_address and the clients who match its ACL are limited
 to the IPv4 or IPv6 network that address belongs to. They are not permitted over the
 IPv4-IPv6 boundary. Some ACL voodoo can however be applied to explicitly route the
 IPv6/IPv4 bound traffic (DIRECT access) out an appropriate interface.
<verb>
    acl toIP6 dst ipv6
    tcp_outgoing_address 2001::1 toIP6
    tcp_outgoing_address 10.0.0.1 !toIP6
</verb>

<p>WCCP is not available (neither version 1 or 2). It remains built into squid for use with IPv4 traffic but IPv6 cannot use it.

<p>Transparent Interception is done via NAT at the OS level and is not available in IPv6.
   Squid will ensure that any port set with transparent, intercept, or tproxy options be an IPv4-only
   listening address. Wildcard can still be used but will not open as an IPv6.
   To ensure that squid can accept IPv6 traffic on its default port, an alternative should
   be chosen to handle transparently intercepted traffic.
<verb>
   http_port 3128
   http_port 8080 intercept
</verb>

<p>The bundled NTLM Auth helper is IPv4-native between itself and the NTLM server.
   A new one will be needed for IPv6 traffic between the helper and server.

<p>The bundled RADIUS Auth helper is IPv4-native, both in traffic between and data storage
   with the RADIUS server. A new helper will be needed for IPv6 RADIUS protocol.


<sect1>Error Page Localization

<p>Details in <url url="http://wiki.squid-cache.org/Translations" name="The Squid wiki">

<sect2>Localization

<p>The error pages presented by squid may now be localized per-request to match the visitors local preferred language.

<p>The error_directory option in squid.conf needs to be removed.

<p>For best coverage of languages, using the latest language pack of error files is recommended.
Updates can be downloaded from <url url="http://www.squid-cahch.org/Versions/langpack/" name="www.squid-cache.org/Versions/langpack/">

<p>The squid developers are interested in making squid available in a wide variety of languages.
   Contribution of new languages is encouraged.

<sect2>CSS Stylesheet controls

<p>To further enhance the visitor experience all new translations have embeded CSS hooks for scalable per-site localization of the display.

<p>CSS display is controlled by updating the errorpage.css file installed into Squids configuration directory
   or the <em>err_page_stylesheet</em> option in squid.conf.

<p>Custom error pages can also embed the CSS content by adding the <em>%l</em> tag to their headers.


<sect1>Connection Pinning (for NTLM Auth Passthrough)

<p>Details in <url url="http://wiki.squid-cache.org/Features/ConnPinn" name="The Squid wiki">

<p>Squid 3.1 includes the much asked for Connection Pinning feature from Squid 2.6.

<p>This feature is often called 'NTLM Passthru' since it is a giant workaround which permits Web servers to use
Microsoft NTLM Authentication instead of HTTP standard authentication through a web proxy.


<sect1>Quality of Service (QoS) Flow support

<p>Details in <url url="http://wiki.squid-cache.org/Features/QualityOfService" name="The Squid wiki">

<p>Zero Penalty Hit created a patch to set QoS markers on outgoing traffic.

<itemize>
	<item>Allows you to select a TOS/Diffserv value to mark local hits.
	<item>Allows you to select a TOS/Diffserv value to mark peer hits.
	<item>Allows you to selectively mark only sibling or parent requests
	<item>Allows any HTTP response towards clients to have the TOS value of the response coming from
		the remote server preserved.
		For this to work correctly, you will need to patch your linux kernel with the TOS preserving ZPH patch.
		The kernel patch can be downloaded from <url url="http://zph.bratcheda.org" name="http://zph.bratcheda.org">
	<item>Allows you to mask certain bits in the TOS received from the remote server,
		before copying the value to the TOS send towards clients.
</itemize>

<sect2>Squid Configuration
<p>Squid 3.1 needs to be configured with --enable-zph-qos for the ZPH QoS controls to be available.

<p>The configuration options for 2.7 and 3.1 are based on different ZPH patches.
The two releases configuration differs and only the TOS mode settings are directly translatable.

<itemize>
<item><em>qos_flows local-hit=0xff</em>		Responses found as a HIT in the local cache
<item><em>qos_flows sibling-hit=0xff</em>	Responses found as a HIT in a sibling peer
<item><em>qos_flows parent-hit=0xff</em>	Responses found as a HIT in a parent peer
</itemize>

<p>The lines above are spearated for documentation. qos_flows may be configured with all options on one line, or separated as shown.
Also options may be repeated as many times as desired. Only the final configured value for any option will be used.

<p>The legacy <em>Option</em> and <em>Priority</em> modes available in Squid-2.7 are no longer supported.


<sect1>SSL Bump (for HTTPS Filtering and Adaptation)

<p>Details in <url url="http://wiki.squid-cache.org/Features/SslBump" name="The Squid wiki">

<p>Squid-in-the-middle decryption and encryption of straight CONNECT and transparently redirected SSL traffic,
using configurable client- and server-side certificates.
While decrypted, the traffic can be inspected using ICAP.


<sect1>eCAP Adaptation Module support

<p>Details in <url url="http://wiki.squid-cache.org/Features/eCAP" name="The Squid wiki">


<sect>Windows support
<P>This Squid version can run on Windows as a system service using the Cygwin emulation environment, 
or can be compiled in Windows native mode using the MinGW + MSYS development environment. Windows NT 4 SP4 and later are supported.<newline>
On Windows 2000 and later the service is configured to use the Windows Service Recovery option
restarting automatically after 60 seconds.

<sect1>Usage

<p>Some new command line options were added for the Windows service support:<newline>

<p>The service installation is made with -i command line switch, it's possible to use -f switch at
the same time for specify a different config-file settings for the Squid Service that will be
stored on the Windows Registry.

<p>A new -n switch specify the Windows Service Name, so multiple Squid instance are allowed.
<em/"Squid"/ is the default when the switch is not used.

<p>So, to install the service, the syntax is: 

<verb>squid -i [-f file] [-n name]</verb>

<p>Service uninstallation is made with -r command line switch with the appropriate -n switch.

<p>The -k switch family must be used with the appropriate -f and -n switches, so the syntax is: 

<verb>squid -k command [-f file] -n service-name</verb>
where <em/service-name/ is the name specified with -n options at service install time.

<p>To use the Squid original command line, the new -O switch must be used ONCE, the syntax is: 

<verb>squid -O cmdline [-n service-name]</verb>
<p>If multiple service command line options must be specified, use quote. The -n switch is
needed only when a non default service name is in use.

<p>Don't use the "Start parameters" in the Windows 2000/XP/2003 Service applet: they are
specific to Windows services functionality and Squid is not designed for understand they.

<p>In the following example the command line of the "squidsvc" Squid service is set to "-D -u 3130": 

<verb>squid -O "-D -u 3130" -n squidsvc</verb>

<sect1>PSAPI.DLL (Process Status Helper) Considerations

<p>The process status helper functions make it easier for you to obtain information about