# Squid 2.7.STABLE2 release notes

## Squid Developers

$Id$

This document contains the release notes for version 2.7 of Squid. Squid is a WWW Cache application developed by the Web Caching community.

## 1. Key changes from squid 2.6

## 2. Changes to squid.conf

- 2.1 Added directives
- 2.2 Changed directives
- 2.3 Removed directives

## 3. Known issues & limitations

- 3.1 Known issues
- 3.2 Known limitations

## 4. Windows support

- 4.1 Usage
- 4.2 PSAPI.DLL (Process Status Helper) Considerations
- 4.3 Registry DNS lookup
- 4.4 Compatibility Notes
- 4.5 Known Limitations:
- 4.6 Using cache manager on Windows:

## 5. Key changes in squid-2.7.STABLE2

## 1. Key changes from squid 2.6

This section describes the main news since the 2.6 release

- Experimental support for HTTP/1.1, mainly targeted at reverse proxy installations. Not yet HTTP/1.1 compliant hoewever.
- A number of performance improvements; including request/reply parser, eliminating various redundant data copies and some completely rewritten sections.
- Support for WAIS has been removed.
- "act-as-origin" option for http_port - Squid can now emulate an origin server when acting as an accelerator.
- "min-size" option for cache_dir - the minimum object size to store in a cache directory. Previously objects of any size up to a "max-size" maximum size would be considered as candidated for storing in a store_dir; this option allows the administrator to tune various stores for small and large objects rather than trying to tune it for both.
- Support for Solaris /dev/poll for network IO - more efficient than poll() or select() and backwards compatible to Solaris 7. This must be manually enabled during configure by specifying "--enable-devpoll".
- Support for FreeBSD accept filters. Use "accept_filter httpready" in squid.conf to enable this.
- A semi-modular logging framework has been introduced, which both allows for more efficient non-blocking logging with the supplied logging daemon, but also allows for third-party modules to intercept the squid logs and process them. An example "UDP" logging helper, thanks to the Wikimedia Foundation, is included.
- Support for rewriting URLs into canonical forms when storing and retrieving objects. A common practice seen in Content Delivery Networks is to serve the same content from a variety of different URLs or hosts; this makes efficient caching difficult. The store URL rewriting framework allows the administrator to rewrite a variety of URLs into one canonical form, so matching content from a variety of sources can be stored and retrieved as if they came from the same source, whilst still fetching the content from the original destination. See the "storeurl_rewrite_program" option for more information, and http://wiki.squid-cache.org/Features/StoreURLRewrite for some examples.
- Object revalidation can now occur in the background. Cache validation can now occur in the background without requiring an active client to drive it. Stale content being revalidated can be served in situ whilst the object is being refreshed. See the "max_stale" and "refresh_pattern" options for more information.
- introduce a new option, "zero_buffers", which controls whether Squid will zero the memory used for buffers and other data structures before use. This may or may not improve performance on specific workloads.
- Cache authentication based on source IP address. This reduces the pressure on external authenticators which may not be able to keep up under high load - NTLM/winbind is a good example of this. See the "authenticate_ip_shortcircuit_access" and "authenticate_ip_shortcircuit_ttl" options for more information.
- Support for configuration file includes has been added. "include" can now be used to include a configuration file or a glob of configuration files in a directory.
- The default rules to not cache dynamic content from cgi-bin and query URLs have been altered. Previously, the "cache" ACL was used to mark requests as non-cachable - this is enforced even on dynamic content which returns cachability information. This has changed in Squid-2.7 to use the default refresh pattern. Dynamic content is now cached if it is marked as cachable. You should remove the default configuration lines with QUERY (acl, and cache) and replace them with the correct refresh_pattern entries.
- Accelerator mode support cleaned up to behave more consistent when combining multiple accelerator mode options
- Zero Penalty Hit support, allowing cache misses to be marked by custom TOS/priority values, useful when using packet shaping/prioritization outside Squid and needing to separate cache hits from misses.

## 2. Changes to squid.conf

This release has a number of changes and additions to squid.conf

## 2.1 Added directives

acl myportname

  new acl matching the incoming port name

authenticate_ip_shortcircuit_ttl
authenticate_ip_shortcircuit_access

  controls the new IP based authentication cache.

zph_mode
zph_local
zph_sibling
zph_parent
zph_option

  controls the Zero Penalty Hit support

update_headers

  optimization to skip updating on-disk headers

logfile_daemon

  new log file daemon support

netdb_filename

  sas hardcoded to the first cache_dir

storeurl_rewrite_program
storeurl_rewrite_children
storeurl_rewrite_concurrency
storeurl_access

  controls the new store URL rewrite functionality

rewrite_access
rewrite

  controls the new builtin URL rewrite functionality

max_stale
server_http11
ignore_expect_100

  Experimental HTTP/1.1 support knobs

external_refresh_check

  new helper to allow custom cache validations in accelerator setups

ignore_ims_on_miss

  optimization mainly targeted for accelerator setups

max_filedescriptors

  can now be set runtime. Was previously hardcoded at build time and further limited by ulimit

accept_filter

  optimization to avoid waking Squid up until a request has been received

incoming_rate

  new tuning knob for high traffic conditions

zero_buffers

  tuning knob to disable a new optimization

## 2.2 Changed directives

cache

  Suggested defaults modified

cache_dir

  the "read-only" option has been renamed to "no-store" to better reflect the functionality

cache_peer

  new multicast-siblings option, enabling multicast ICP sibling relations

  new idle=n option to keep a minimum pool of idle connections

  new http11 option to enable experimental HTTP/1.1 support

external_acl_type

  New %URI format tag

acl

  Suggested defaults cleaned up, defines a new "localnet" acl with RFC1918 addresses

  new "myportname" acl type matching the http_port name

icp_access

  Suggested defaults cleaned up, now requires configuration to use ICP

htcp_access

  Suggested defaults cleaned up, now requires configuration to use HTCP

http_access

  Suggested defaults cleaned up, using a new "localnet" acl.

http_port

  Accelerator mode options cleaned up (accel, defaultsite, vport, vhost and combinations thereof)

  new "allow-direct" option

  new "act-as-origin" option

  new "http11" option (experimental)

  new "name=" option

  nee "keepalive=" option

https_port

  See http_port.

logformat

  New format codes: oa (Our outgoing IP address), rp (Request URL-Path), sn (Unique sequence number)

refresh_pattern

  Several new options: stale-while-revalidate, ignore-stale-while-revalidate, max-stale, negative-ttl

  Suggested defaults adjusted to match the changes in the cache directive.

url_rewrite_program

  Future protocol change adding key=value pairs after the requests

forwarded_for

  Has several new modes, allowing one to finetune how/if the requesting client IP should be forwarded in X-Forwarded-For

## 2.3 Removed directives

incoming_icp_average
incoming_http_average
incoming_dns_average
min_icp_poll_cnt
min_dns_poll_cnt
min_http_poll_cnt

  the above tuning knobs no longer have any effect and has been removed.

## 3. Known issues & limitations

There is a few known issues and limitations in this release of Squid

## 3.1 Known issues

- Bug #2248 storeurl_rewrite mismatched when object stored on memory
- Bug #2112 Squid does not send If-None-Match tag for cache revalidation
- Bug #2160 Cache hits on objects with headers > 4KB

## 3.2 Known limitations

- Bug #1059: mime.conf and referenced icons must be within chroot
- Bug #692: tcp_outgoing_address using an ident ACL does not work
- Bug #581: acl max_user_ip and multiple authentication schemes
- Bug #528: miss_access fails on "slow" acl types such as dst.
- Bug #513: squid -F is starting server sockets to early
- Bug #457: does not handle swap.state corruption properly
- Bug #410: unstable if runs out of disk space
- Bug #355: diskd may appear slow on low loads

## 4. Windows support

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.

On Windows 2000 and later the service is configured to use the Windows Service Recovery option restarting automatically after 60 seconds.

## 4.1 Usage

Some new command line options was added for the Windows service support:

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. "Squid" is the default when the switch is not used.

So, to install the service, the syntax is:

    squid -i [-f file] [-n name]

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:

    squid -k command [-f file] -n service-name

where 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:

    squid -O cmdline [-n service-name]

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":

    squid -O "-D -u 3130" -n squidsvc

## 4.2 PSAPI.DLL (Process Status Helper) Considerations

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.

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.

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: http://download.microsoft.com/download/platformsdk/Redist/4.0.1371.1/NT4/EN-US/psinst.EXE

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.

## 4.3 Registry DNS lookup

On Windows platforms, if no value is specified in the dns_nameservers 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.

## 4.4 Compatibility Notes

- It's recommended to use '/' char in Squid paths instead of '\'
- Paths with spaces (like 'C:\Programs Files\Squid) are NOT supported by Squid
- Include wildcard patterns in squid.conf are NOT supported on Windows
- 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:

      acl blocklist url_regex -i "c:/squid/etc/blocked1.txt"

- The Windows equivalent of '/dev/null' is 'NUL'
- 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:

      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

- When Squid runs in command line mode, the launching user account must have administrative privilege on the system
- "Start parameters" in the Windows 2000/XP/2003 Service applet cannot be used
- Building with MinGW, when the configure option --enable-truncate is used, Squid cannot run on Windows NT, only Windows 2000 and later are supported

## 4.5 Known Limitations:

- DISKD: still needs to be ported
- WCCP: cannot work because user space GRE support on Windows is missing
- Transparent Proxy: missing Windows non commercial interception driver
- Some code sections can make blocking calls.
- Some external helpers may not work.
- File Descriptors number hard-limited to 2048 when building with MinGW.

## 4.6 Using cache manager on Windows:

On Windows, cache manager (cachemgr.cgi) can be used with Microsoft IIS or Apache. Some specific configuration could be needed:

### IIS 6 (Windows 2003)

On IIS 6.0 all CGI extensions are denied by default for security reason, so the following configuration is needed:

- Create a cgi-bin Directory
- 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
- 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
- In IIS manager go to Web Service extensions and add a new Web Service Extension called "Squid Cachemgr", add the cachemgr.cgi file and set the extension status to Allowed

### Apache:

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:

    ScriptAlias /squid/cgi-bin/ "c:/squid/libexec/"
    <Location /squid/cgi-bin/cachemgr.cgi>
        PassEnv TMP TEMP
        Order allow,deny
        Allow from workstation.example.com
    </Location>

## 5. Key changes in squid-2.7.STABLE2

- Compile error if --enable-delaypools used
- Bug #1893: Variant invalidation support removed again, caused a lot content to not get cached.
- Bug #2350: Linux Capabilities version mismatch causing startup crash on newer kernels
- See also the list of squid-2.7.STABLE2 changes and the ChangeLog file for details.