From 1d7e0d63183dd11b7d35220e748648d98ff0fa8f Mon Sep 17 00:00:00 2001
From: Amos Jeffries <squid3@treenet.co.nz>
Date: Sat, 2 Jan 2010 18:37:54 +1300
Subject: [PATCH] Release notes for helper-mux

---
 doc/release-notes/release-3.2.html | 369 +++++++----------------------
 doc/release-notes/release-3.2.sgml |  51 +++-
 2 files changed, 139 insertions(+), 281 deletions(-)

diff --git a/doc/release-notes/release-3.2.html b/doc/release-notes/release-3.2.html
index 57c7e85d7d..f6cc73d6f8 100644
--- a/doc/release-notes/release-3.2.html
+++ b/doc/release-notes/release-3.2.html
@@ -24,52 +24,41 @@ for Applied Network Research and members of the Web Caching community.</EM>
 <H2><A NAME="toc2">2.</A> <A HREF="#s2">Major new features since Squid-3.1</A></H2>
 
 <UL>
-<LI><A NAME="toc2.1">2.1</A> <A HREF="#ss2.1">Helper Name Changes</A>
-<LI><A NAME="toc2.2">2.2</A> <A HREF="#ss2.2">Multi-Lingual manuals</A>
-<LI><A NAME="toc2.3">2.3</A> <A HREF="#ss2.3">Solaris 10 pthreads Support (Experimental)</A>
+<LI><A NAME="toc2.1">2.1</A> <A HREF="#ss2.1">Helper Multiplexer</A>
+<LI><A NAME="toc2.2">2.2</A> <A HREF="#ss2.2">Helper Name Changes</A>
+<LI><A NAME="toc2.3">2.3</A> <A HREF="#ss2.3">Multi-Lingual manuals</A>
+<LI><A NAME="toc2.4">2.4</A> <A HREF="#ss2.4">Solaris 10 pthreads Support (Experimental)</A>
 </UL>
 <P>
-<H2><A NAME="toc3">3.</A> <A HREF="#s3">Windows support</A></H2>
+<H2><A NAME="toc3">3.</A> <A HREF="#s3">Changes to squid.conf since Squid-3.1</A></H2>
 
 <UL>
-<LI><A NAME="toc3.1">3.1</A> <A HREF="#ss3.1">Usage</A>
-<LI><A NAME="toc3.2">3.2</A> <A HREF="#ss3.2">PSAPI.DLL (Process Status Helper) Considerations</A>
-<LI><A NAME="toc3.3">3.3</A> <A HREF="#ss3.3">Registry DNS lookup</A>
-<LI><A NAME="toc3.4">3.4</A> <A HREF="#ss3.4">Compatibility Notes</A>
-<LI><A NAME="toc3.5">3.5</A> <A HREF="#ss3.5">Known Limitations</A>
-<LI><A NAME="toc3.6">3.6</A> <A HREF="#ss3.6">Building Squid on Windows</A>
-<LI><A NAME="toc3.7">3.7</A> <A HREF="#ss3.7">Using cache manager on Windows:</A>
+<LI><A NAME="toc3.1">3.1</A> <A HREF="#ss3.1">New tags</A>
+<LI><A NAME="toc3.2">3.2</A> <A HREF="#ss3.2">Changes to existing tags</A>
+<LI><A NAME="toc3.3">3.3</A> <A HREF="#ss3.3">Removed tags</A>
 </UL>
 <P>
-<H2><A NAME="toc4">4.</A> <A HREF="#s4">Changes to squid.conf since Squid-3.1</A></H2>
+<H2><A NAME="toc4">4.</A> <A HREF="#s4">Changes to ./configure options since Squid-3.1</A></H2>
 
 <UL>
-<LI><A NAME="toc4.1">4.1</A> <A HREF="#ss4.1">New tags</A>
-<LI><A NAME="toc4.2">4.2</A> <A HREF="#ss4.2">Changes to existing tags</A>
-<LI><A NAME="toc4.3">4.3</A> <A HREF="#ss4.3">Removed tags</A>
+<LI><A NAME="toc4.1">4.1</A> <A HREF="#ss4.1">New options</A>
+<LI><A NAME="toc4.2">4.2</A> <A HREF="#ss4.2">Changes to existing options</A>
+<LI><A NAME="toc4.3">4.3</A> <A HREF="#ss4.3">Removed options</A>
 </UL>
 <P>
-<H2><A NAME="toc5">5.</A> <A HREF="#s5">Changes to ./configure options since Squid-3.1</A></H2>
+<H2><A NAME="toc5">5.</A> <A HREF="#s5">Options Removed since Squid-2</A></H2>
 
 <UL>
-<LI><A NAME="toc5.1">5.1</A> <A HREF="#ss5.1">New options</A>
-<LI><A NAME="toc5.2">5.2</A> <A HREF="#ss5.2">Changes to existing options</A>
-<LI><A NAME="toc5.3">5.3</A> <A HREF="#ss5.3">Removed options</A>
+<LI><A NAME="toc5.1">5.1</A> <A HREF="#ss5.1">Removed squid.conf options since Squid-2.7</A>
+<LI><A NAME="toc5.2">5.2</A> <A HREF="#ss5.2">Removed squid.conf options since Squid-2.6</A>
+<LI><A NAME="toc5.3">5.3</A> <A HREF="#ss5.3">Removed ./configure options since Squid-2.7</A>
 </UL>
 <P>
-<H2><A NAME="toc6">6.</A> <A HREF="#s6">Options Removed since Squid-2</A></H2>
+<H2><A NAME="toc6">6.</A> <A HREF="#s6">Regressions since Squid-2.7</A></H2>
 
 <UL>
-<LI><A NAME="toc6.1">6.1</A> <A HREF="#ss6.1">Removed squid.conf options since Squid-2.7</A>
-<LI><A NAME="toc6.2">6.2</A> <A HREF="#ss6.2">Removed squid.conf options since Squid-2.6</A>
-<LI><A NAME="toc6.3">6.3</A> <A HREF="#ss6.3">Removed ./configure options since Squid-2.7</A>
-</UL>
-<P>
-<H2><A NAME="toc7">7.</A> <A HREF="#s7">Regressions since Squid-2.7</A></H2>
-
-<UL>
-<LI><A NAME="toc7.1">7.1</A> <A HREF="#ss7.1">Missing squid.conf options available in Squid-2.7</A>
-<LI><A NAME="toc7.2">7.2</A> <A HREF="#ss7.2">Missing ./configure options available in Squid-2.7</A>
+<LI><A NAME="toc6.1">6.1</A> <A HREF="#ss6.1">Missing squid.conf options available in Squid-2.7</A>
+<LI><A NAME="toc6.2">6.2</A> <A HREF="#ss6.2">Missing ./configure options available in Squid-2.7</A>
 </UL>
 
 <HR>
@@ -101,6 +90,7 @@ for Applied Network Research and members of the Web Caching community.</EM>
 
 <P>The most important of these new features are:
 <UL>
+<LI>Helper Multiplexer</LI>
 <LI>Helper Name Changes</LI>
 <LI>Multi-Lingual manuals</LI>
 <LI>Solaris 10 pthreads Support (Experimental)</LI>
@@ -108,7 +98,54 @@ for Applied Network Research and members of the Web Caching community.</EM>
 </P>
 <P>Most user-facing changes are reflected in squid.conf (see below).</P>
 
-<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Helper Name Changes</A>
+<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Helper Multiplexer</A>
+</H2>
+
+<P>The helper multiplexer's purpose is to relieve some of the burden
+Squid has when dealing with slow helpers. It does so by acting as a
+middleman between squid and the actual helpers, talking to Squid via
+the multiplexed concurrent variant of the helper protocol and to the
+helpers via the non-concurrent variant.</P>
+
+<P>Helpers are started on demand, and in theory the muxer can handle up to
+1k helpers per instance. It's up to squid to decide how many helpers
+to start.</P>
+
+<P>The muxer knows nothing about the actual messages being passed around,
+and as such can't really (yet?) compensate for broken helpers.
+It is not yet able to manage dying helpers, but it will.</P>
+
+<P>To configure the multiplexer add its binary name (usually /usr/share/libexec/helper-mux.pl)
+in front of the name of whichever helper is being multiplexed. It takes the helper binary
+path and parameters as its own command parameters. The <EM>concurrency</EM> setting already
+existing in Squid is used to configure how many child helpers it may run.</P>
+
+<P>For example, a traditional configration is
+<PRE>
+        url_rewrite_program /your/redirector.sh
+        url_rewrite_children 5
+   
+</PRE>
+
+the alternative multiplexer configuration is:
+<PRE>
+        url_rewrite_program /usr/share/libexec/helper-mux.pl /your/redirector.sh
+        url_rewrite_children 1 concurrency=5
+   
+</PRE>
+</P>
+
+<P>Helpers which are already concurrent protocol enabled gain little benefit from the multiplexer
+on most systems. However on some systems where Squid spawning helpers causes excess memory usage
+the reduction in direct helper spawned by Squid can result in a great reduction in resource use.</P>
+
+<P>The helper can be controlled using various signals:
+<UL>
+<LI>SIGHUP: dump the state of all helpers to STDERR</LI>
+</UL>
+</P>
+
+<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Helper Name Changes</A>
 </H2>
 
 <P>To improve the understanding of what each helper does and where it should be used the helper binaries
@@ -168,7 +205,7 @@ which are bundled with Squid have undergone a naming change in this release.</P>
 </P>
 
 
-<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Multi-Lingual manuals</A>
+<H2><A NAME="ss2.3">2.3</A> <A HREF="#toc2.3">Multi-Lingual manuals</A>
 </H2>
 
 <P>The man(8) and man(1) pages bundled with Squid are now provided online for all
@@ -180,236 +217,12 @@ versions and beginning with 3.2 they are available in languages other than engli
 <P>3.1 began the Internationalization of Squid with the public facing error pages.
 This move begins the Localization of the internal administrator facing manuals.</P>
 
-<H2><A NAME="ss2.3">2.3</A> <A HREF="#toc2.3">Solaris 10 pthreads Support (Experimental)</A>
+<H2><A NAME="ss2.4">2.4</A> <A HREF="#toc2.4">Solaris 10 pthreads Support (Experimental)</A>
 </H2>
 
 <P>Automatic detection and use of the pthreads library available from Solaris 10</P>
 
-
-<H2><A NAME="s3">3.</A> <A HREF="#toc3">Windows support</A></H2>
-
-<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.<BR>
-On Windows 2000 and later the service is configured to use the Windows Service Recovery option
-restarting automatically after 60 seconds.</P>
-
-<H2><A NAME="ss3.1">3.1</A> <A HREF="#toc3.1">Usage</A>
-</H2>
-
-<P>Some new command line options were added for the Windows service support:<BR></P>
-
-<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>
-
-<P>A new -n switch specify the Windows Service Name, so multiple Squid instance are allowed.
-<EM>"Squid"</EM> is the default when the switch is not used.</P>
-
-<P>So, to install the service, the syntax is: </P>
-<P>
-<PRE>
-squid -i [-f file] [-n name]
-</PRE>
-</P>
-
-<P>Service uninstallation is made with -r command line switch with the appropriate -n switch.</P>
-
-<P>The -k switch family must be used with the appropriate -f and -n switches, so the syntax is: </P>
-<P>
-<PRE>
-squid -k command [-f file] -n service-name
-</PRE>
-
-where <EM>service-name</EM> is the name specified with -n options at service install time.</P>
-
-<P>To use the Squid original command line, the new -O switch must be used ONCE, the syntax is: </P>
-<P>
-<PRE>
-squid -O cmdline [-n service-name]
-</PRE>
-</P>
-<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>
-
-<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>
-
-<P>In the following example the command line of the "squidsvc" Squid service is set to "-D -u 3130": </P>
-<P>
-<PRE>
-squid -O "-u 3130" -n squidsvc
-</PRE>
-</P>
-
-<H2><A NAME="ss3.2">3.2</A> <A HREF="#toc3.2">PSAPI.DLL (Process Status Helper) Considerations</A>
-</H2>
-
-<P>The process status helper functions make it easier for you to obtain information about
-processes and device drivers running on Microsoft® Windows NT®/Windows® 2000. These
-functions are available in PSAPI.DLL, which is distributed in the Microsoft® Platform
-Software Development Kit (SDK). The same information is generally available through the
-performance data in the registry, but it is more difficult to get to it. PSAPI.DLL is
-freely redistributable.</P>
-
-<P>PSAPI.DLL is available only on Windows NT, 2000, XP and 2003. The implementation in Squid is
-aware of this, and try to use it only on the right platform.</P>
-
-<P>On Windows NT PSAPI.DLL can be found as component of many applications, if you need it,
-you can find it on Windows NT Resource KIT. If you have problem, it can be
-downloaded from here:
-<A HREF="http://download.microsoft.com/download/platformsdk/Redist/4.0.1371.1/NT4/EN-US/psinst.EXE">http://download.microsoft.com/download/platformsdk/Redist/4.0.1371.1/NT4/EN-US/psinst.EXE</A></P>
-
-<P>On Windows 2000 and later it is available installing the Windows Support Tools, located on the
-Support\Tools folder of the installation Windows CD-ROM.</P>
-
-<H2><A NAME="ss3.3">3.3</A> <A HREF="#toc3.3">Registry DNS lookup</A>
-</H2>
-
-<P>On Windows platforms, if no value is specified in the <EM>dns_nameservers</EM> option on
-squid.conf or in the /etc/resolv.conf file, the list of DNS name servers are
-taken from the Windows registry, both static and dynamic DHCP configurations
-are supported.</P>
-
-<H2><A NAME="ss3.4">3.4</A> <A HREF="#toc3.4">Compatibility Notes</A>
-</H2>
-
-<P>
-<UL>
-<LI>It's recommended to use '/' char in Squid paths instead of '\'</LI>
-<LI>Paths with spaces (like 'C:\Programs Files\Squid) are NOT supported by Squid</LI>
-<LI>When using ACL like 'acl aclname acltype "file"' the file must be in DOS text
-format (CR+LF) and the full Windows path must be specified, for example:
-
-<PRE>
-acl blocklist url_regex -i "c:/squid/etc/blocked1.txt"
-</PRE>
-
-</LI>
-<LI>The Windows equivalent of '/dev/null' is 'NUL'</LI>
-<LI>Squid doesn't know how to run external helpers based on scripts, like .bat, .cmd,
-.vbs, .pl, etc. So in squid.conf the interpreter path must be always specified, for example:
-
-<PRE>
-redirect_program c:/perl/bin/perl.exe c:/squid/libexec/redir.pl
-redirect_program c:/winnt/system32/cmd.exe /C c:/squid/libexec/redir.cmd
-</PRE>
-</LI>
-<LI>When Squid runs in command line mode, the launching user account must have administrative privilege on the system</LI>
-<LI>"Start parameters" in the Windows 2000/XP/2003 Service applet cannot be used</LI>
-<LI>On Windows Vista and later, User Account Control (UAC) must be disabled before running service installation</LI>
-</UL>
-</P>
-
-
-<H2><A NAME="ss3.5">3.5</A> <A HREF="#toc3.5">Known Limitations</A>
-</H2>
-
-<P>
-<UL>
-<LI>Squid features not operational:<BR>
-<UL>
-<LI>DISKD: still needs to be ported<BR></LI>
-<LI>WCCP: cannot work because user space GRE support on Windows is missing<BR></LI>
-<LI>Transparent Proxy: missing Windows non commercial interception driver<BR></LI>
-</UL>
-</LI>
-<LI>Some code sections can make blocking calls.</LI>
-<LI>Some external helpers may not work.</LI>
-<LI>File Descriptors number hard-limited to 2048 when building with MinGW.</LI>
-</UL>
-</P>
-
-<H2><A NAME="ss3.6">3.6</A> <A HREF="#toc3.6">Building Squid on Windows</A>
-</H2>
-
-<P>A reasonably recent release of 
-<A HREF="http://www.cygwin.com/">Cygwin</A> or 
-<A HREF="http://www.mingw.org/">MinGW</A> is needed.<BR>
-The usage of the Cygwin environment is very similar to other Unix/Linux environments, and -devel version of libraries must be installed.<BR>
-For the MinGW environment, the packages MSYS, MinGW and msysDTK must be installed. Some additional libraries and tools must be downloaded separately:<BR><BR>
-OpenSSL: 
-<A HREF="http://www.slproweb.com/products/Win32OpenSSL.html">Shining Light Productions Win32 OpenSSL</A><BR>
-libcrypt: 
-<A HREF="http://sourceforge.net/projects/mingwrep/">MinGW packages repository</A><BR>
-db-1.85: 
-<A HREF="http://tinycobol.org/download.html">TinyCOBOL download area</A><BR>
-When running configure, --disable-wccp and --disable-wccpv2 options should always specified to avoid compile errors.<BR>
-<UL>
-<LI>New configure options:<BR>
-<UL>
-<LI>--enable-win32-service<BR></LI>
-</UL>
-</LI>
-<LI>Updated configure options:<BR>
-<UL>
-<LI>--enable-arp-acl<BR></LI>
-<LI>--enable-default-hostsfile<BR></LI>
-</UL>
-</LI>
-<LI>Unsupported configure options:<BR>
-<UL>
-<LI>--enable-coss-aio-ops: On Windows Posix AIO is not available<BR></LI>
-<LI>--with-large-files: No suitable build environment is available on both Cygwin and MinGW, but --enable-large-files works fine<BR></LI>
-</UL>
-</LI>
-<LI>Recommended configure minimal options for Windows:<BR>
-<UL>
-<LI>--prefix=c:/squid --disable-wccp --disable-wccpv2 --enable-win32-service --enable-default-hostsfile=none</LI>
-</UL>
-</LI>
-</UL>
-<BR>
-Before build Squid with SSL support, some operations are needed (in the following example OpenSSL is installed in C:\OpenSSL and MinGW in C:\MinGW):
-<UL>
-<LI>Copy C:\OpenSSL\lib\MinGW content to C:\MinGW\lib<BR></LI>
-<LI>Copy C:\OpenSSL\include\openssl content to C:\MinGW\include\openssl<BR></LI>
-<LI>Rename C:\MinGW\lib\ssleay32.a to C:\MinGW\lib\libssleay32.a<BR></LI>
-</UL>
-</P>
-
-<H2><A NAME="ss3.7">3.7</A> <A HREF="#toc3.7">Using cache manager on Windows:</A>
-</H2>
-
-<P>On Windows, cache manager (cachemgr.cgi) can be used with Microsoft IIS or Apache.<BR>
-Some specific configuration could be needed:<BR>
-<UL>
-<LI>IIS 6 (Windows 2003):<BR>
-<UL>
-<LI>On IIS 6.0 all CGI extensions are denied by default for security reason, so the following configuration is needed:<BR>
-<UL>
-<LI>Create a cgi-bin Directory</LI>
-<LI>Define the cgi-bin IIS Virtual Directory with read and CGI execute IIS
-permissions, ASP scripts are not needed. This automatically defines a
-cgi-bin IIS web application </LI>
-<LI>Copy cachemgr.cgi into cgi-bin directory and look to file permissions:
-the IIS system account and SYSTEM must be able to read and execute the file</LI>
-<LI>In IIS manager go to Web Service extensions and add a new Web Service
-Extension called <EM>"Squid Cachemgr"</EM>, add the cachemgr.cgi file and set the
-extension status to <EM>Allowed</EM></LI>
-</UL>
-</LI>
-</UL>
-</LI>
-<LI>Apache:<BR>
-<UL>
-<LI>On Windows, cachemgr.cgi needs to create a temporary file, so Apache must be instructed
-to pass the TMP and TEMP Windows environment variables to CGI applications:<BR>
-<PRE>
-ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/"
-&lt;Location /squid/cgi-bin/cachemgr.cgi&gt;
-    PassEnv TMP TEMP
-    Order allow,deny
-    Allow from workstation.example.com
-&lt;/Location&gt;
-</PRE>
-</LI>
-</UL>
-</LI>
-</UL>
-</P>
-
-
-<H2><A NAME="s4">4.</A> <A HREF="#toc4">Changes to squid.conf since Squid-3.1</A></H2>
+<H2><A NAME="s3">3.</A> <A HREF="#toc3">Changes to squid.conf since Squid-3.1</A></H2>
 
 <P>There have been changes to Squid's configuration file since Squid-3.1.</P>
 <P>This section gives a thorough account of those changes in three categories:</P>
@@ -426,7 +239,7 @@ ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/"
 
 
 
-<H2><A NAME="newtags"></A> <A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">New tags</A>
+<H2><A NAME="newtags"></A> <A NAME="ss3.1">3.1</A> <A HREF="#toc3.1">New tags</A>
 </H2>
 
 <P>
@@ -454,7 +267,7 @@ ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/"
 </DL>
 </P>
 
-<H2><A NAME="modifiedtags"></A> <A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">Changes to existing tags</A>
+<H2><A NAME="modifiedtags"></A> <A NAME="ss3.2">3.2</A> <A HREF="#toc3.2">Changes to existing tags</A>
 </H2>
 
 <P>
@@ -490,17 +303,19 @@ Both EUI forms are logged in the same field. Type can be identified by length or
 <P>Now only available to be set in Windows builds.</P>
 
 <DT><B>url_rewrite_children</B><DD>
-
-<DT><B>New options <EM>startup=N</EM>, <EM>idle=N</EM>, <EM>concurrency=N</EM></B><DD>
-<P>startup=N allow finer tuning of how many helpers are started initially.</P>
-<P>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.</P>
-<P>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.</P>
+<P>New options <EM>startup=N</EM>, <EM>idle=N</EM>, <EM>concurrency=N</EM>
+<UL>
+<LI>startup=N allow finer tuning of how many helpers are started initially.</LI>
+<LI>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.</LI>
+<LI>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.</LI>
+</UL>
+</P>
 
 </DL>
 </P>
 
 
-<H2><A NAME="removedtags"></A> <A NAME="ss4.3">4.3</A> <A HREF="#toc4.3">Removed tags</A>
+<H2><A NAME="removedtags"></A> <A NAME="ss3.3">3.3</A> <A HREF="#toc3.3">Removed tags</A>
 </H2>
 
 <P>
@@ -515,7 +330,7 @@ Both EUI forms are logged in the same field. Type can be identified by length or
 </P>
 
 
-<H2><A NAME="s5">5.</A> <A HREF="#toc5">Changes to ./configure options since Squid-3.1</A></H2>
+<H2><A NAME="s4">4.</A> <A HREF="#toc4">Changes to ./configure options since Squid-3.1</A></H2>
 
 <P>There have been some changes to Squid's build configuration since Squid-3.1.</P>
 <P>This section gives an account of those changes in three categories:</P>
@@ -531,7 +346,7 @@ Both EUI forms are logged in the same field. Type can be identified by length or
 </P>
 
 
-<H2><A NAME="newoptions"></A> <A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">New options</A>
+<H2><A NAME="newoptions"></A> <A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">New options</A>
 </H2>
 
 <P>
@@ -550,7 +365,7 @@ the helper protocol usage and provide exemplar code.</P>
 </DL>
 </P>
 
-<H2><A NAME="modifiedoptions"></A> <A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Changes to existing options</A>
+<H2><A NAME="modifiedoptions"></A> <A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">Changes to existing options</A>
 </H2>
 
 <P>
@@ -560,7 +375,7 @@ the helper protocol usage and provide exemplar code.</P>
 
 </DL>
 </P>
-<H2><A NAME="removedoptions"></A> <A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Removed options</A>
+<H2><A NAME="removedoptions"></A> <A NAME="ss4.3">4.3</A> <A HREF="#toc4.3">Removed options</A>
 </H2>
 
 <P>
@@ -572,11 +387,11 @@ the helper protocol usage and provide exemplar code.</P>
 </P>
 
 
-<H2><A NAME="s6">6.</A> <A HREF="#toc6">Options Removed since Squid-2</A></H2>
+<H2><A NAME="s5">5.</A> <A HREF="#toc5">Options Removed since Squid-2</A></H2>
 
 <P>Some squid.conf and ./configure options which were available in Squid-2.6 and Squid-2.7 are made obsolete in Squid-3.2.</P>
 
-<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Removed squid.conf options since Squid-2.7</A>
+<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">Removed squid.conf options since Squid-2.7</A>
 </H2>
 
 <P>
@@ -625,7 +440,7 @@ the helper protocol usage and provide exemplar code.</P>
 </DL>
 </P>
 
-<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Removed squid.conf options since Squid-2.6</A>
+<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Removed squid.conf options since Squid-2.6</A>
 </H2>
 
 <P>
@@ -636,7 +451,7 @@ the helper protocol usage and provide exemplar code.</P>
 </DL>
 </P>
 
-<H2><A NAME="ss6.3">6.3</A> <A HREF="#toc6.3">Removed ./configure options since Squid-2.7</A>
+<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Removed ./configure options since Squid-2.7</A>
 </H2>
 
 <P>
@@ -693,13 +508,13 @@ the helper protocol usage and provide exemplar code.</P>
 </P>
 
 
-<H2><A NAME="s7">7.</A> <A HREF="#toc7">Regressions since Squid-2.7</A></H2>
+<H2><A NAME="s6">6.</A> <A HREF="#toc6">Regressions since Squid-2.7</A></H2>
 
 <P>Some squid.conf and ./configure options which were available in Squid-2.7 are not yet available in Squid-3.2</P>
 
 <P>If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.</P>
 
-<H2><A NAME="ss7.1">7.1</A> <A HREF="#toc7.1">Missing squid.conf options available in Squid-2.7</A>
+<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Missing squid.conf options available in Squid-2.7</A>
 </H2>
 
 <P>
@@ -818,7 +633,7 @@ the helper protocol usage and provide exemplar code.</P>
 </DL>
 </P>
 
-<H2><A NAME="ss7.2">7.2</A> <A HREF="#toc7.2">Missing ./configure options available in Squid-2.7</A>
+<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Missing ./configure options available in Squid-2.7</A>
 </H2>
 
 <P>
diff --git a/doc/release-notes/release-3.2.sgml b/doc/release-notes/release-3.2.sgml
index 5f6ac08c12..c136476dfa 100644
--- a/doc/release-notes/release-3.2.sgml
+++ b/doc/release-notes/release-3.2.sgml
@@ -34,6 +34,7 @@ The 3.2 change history can be <url url="http://www.squid-cache.org/Versions/v3/3
 
 <p>The most important of these new features are:
 <itemize>
+	<item>Helper Multiplexer
 	<item>Helper Name Changes
 	<item>Multi-Lingual manuals
 	<item>Solaris 10 pthreads Support (Experimental)
@@ -41,6 +42,46 @@ The 3.2 change history can be <url url="http://www.squid-cache.org/Versions/v3/3
 
 Most user-facing changes are reflected in squid.conf (see below).
 
+<sect1>Helper Multiplexer
+<p>The helper multiplexer's purpose is to relieve some of the burden
+   Squid has when dealing with slow helpers. It does so by acting as a
+   middleman between squid and the actual helpers, talking to Squid via
+   the multiplexed concurrent variant of the helper protocol and to the
+   helpers via the non-concurrent variant.
+
+<p>Helpers are started on demand, and in theory the muxer can handle up to
+   1k helpers per instance. It's up to squid to decide how many helpers
+   to start.
+
+<p>The muxer knows nothing about the actual messages being passed around,
+   and as such can't really (yet?) compensate for broken helpers.
+   It is not yet able to manage dying helpers, but it will.
+
+<p>To configure the multiplexer add its binary name (usually /usr/share/libexec/helper-mux.pl)
+   in front of the name of whichever helper is being multiplexed. It takes the helper binary
+   path and parameters as its own command parameters. The <em>concurrency</em> setting already
+   existing in Squid is used to configure how many child helpers it may run.
+
+<p>For example, a traditional configration is
+   <verb>
+	url_rewrite_program /your/redirector.sh
+	url_rewrite_children 5
+   </verb>
+   the alternative multiplexer configuration is:
+   <verb>
+	url_rewrite_program /usr/share/libexec/helper-mux.pl /your/redirector.sh
+	url_rewrite_children 1 concurrency=5
+   </verb>
+
+<p>Helpers which are already concurrent protocol enabled gain little benefit from the multiplexer
+   on most systems. However on some systems where Squid spawning helpers causes excess memory usage
+   the reduction in direct helper spawned by Squid can result in a great reduction in resource use.
+
+<p>The helper can be controlled using various signals:
+   <itemize>
+	<item>SIGHUP: dump the state of all helpers to STDERR
+   </itemize>
+
 <sect1>Helper Name Changes
 
 <p>To improve the understanding of what each helper does and where it should be used the helper binaries
@@ -168,10 +209,12 @@ This section gives a thorough account of those changes in three categories:
 	<p>Now only available to be set in Windows builds.
 
 	<tag>url_rewrite_children</tag>
-	<tag>New options <em>startup=N</em>, <em>idle=N</em>, <em>concurrency=N</em>
-	<p>startup=N allow finer tuning of how many helpers are started initially.
-	<p>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.
-	<p>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.
+	<p>New options <em>startup=N</em>, <em>idle=N</em>, <em>concurrency=N</em>
+	<itemize>
+		<item>startup=N allow finer tuning of how many helpers are started initially.
+		<item>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.
+		<item>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.
+	</itemize>
 
 </descrip>
 
-- 
2.47.3