Merged from trunk.

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

<!doctype linuxdoc system>
<article>
<title>Squid 3.1.PRE1 release notes</title>
<author>Squid Developers</author>
<date>$Id: release-3.1.sgml,v 1.6 2008/01/17 10:09:05 hno Exp $</date>

<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.PRE1 for pre-release 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.

<sect>Known issues
<p>
Although this release is deemed good enough for testing 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">.

<sect>Changes since earlier PRE 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>Changes since Squid-3.0

<sect1>Major new features
<p>
Squid 3.1 represents a new feature release above 3.0.

The most important of these new features are:

<itemize>
	<item>IPv6 Support
	<item>Error Page Localization
</itemize>

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

<sect2>Internet Protocol version 6 (IPv6)

<p>Squid 3.1 supports IPv6. To enable IPv6 support, use the ./configure --enable-ipv6 option

<sect3>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>--with-localhost-ipv6 option is provided for Pure-IPv6 setups who do not want to be
 bothered by the localhost vagaries. It will enable logics to map all localhost traffic
 through ::1 unless an IPv4-only link is required.

<p>Additional ./configure --with-ipv4-mapped option is provided for OS that require a socket setting
 to accept IPv4 addresses on IPv6 sockets, squid performs v4-mapping on these addresses
 It is intended primarily to be used for Windows Vista builds.

<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 IP6 entries. This means any third-party SNMP
 software which hard coded the MIB paths needs to be upgraded for this Squid release.


<sect3>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 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 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 transparent traffic.
<verb>
   http_port 3128
   http_port 8080 transparent
</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.


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

<p>Squid needs to be build with the --enable-auto-locale option. And 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.
   Contributions of new languages is encouraged.
   Details at <url url="http://wiki.squid-cache.org/Translations" named="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.
<descrip>

<tag>Usage</tag>

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

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.

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.

So, to install the service, the syntax is: 

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

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

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.

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

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.

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>
</descrip>

<descrip>
<tag>PSAPI.DLL (Process Status Helper) Considerations</tag>

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