# Squid 3.0.PRE7 release notes

## Squid Developers

$Id: release-3.0.html,v 1.7 2007/08/28 00:00:00 hno Exp $

This document contains the release notes for version 3.0 of Squid. Squid is a WWW Cache application developed by the National Laboratory for Applied Network Research and members of the Web Caching community.

## 1. Notice

The Squid Team are pleased to announce the release of Squid-3.0.PRE7 for pre-release testing.

This new release is available for download from http://www.squid-cache.org/Versions/v3/3.0/ or the 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 http://wiki.squid-cache.org/SquidFaq/TroubleShooting#head-7067fc0034ce967e67911becaabb8c95a34d576d for how to submit a report with a stack trace.

## 2. Known issues

Although this release is deemed good enough for testing in many setups, please note the existence of open bugs against Squid-3.0.

In particular, ESI may still be too buggy for meaningful testing at this stage.

## 3. Changes since earlier PRE releases of Squid-3.0

The 3.0 change history can be viewed here.

## 4. Changes since Squid-2.6

## 4.1 Major new features

Squid 3.0 represents a major rewrite of Squid and has a number of new features.

The most important of these are:

- Edge Side Include implementation (www.esi.org)
- ICAP implementation (www.i-cap.org)
- Finer control over cacheability (refresh_pattern)

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

## 4.2 2.6 features not found in Squid-3.0

Some of the features found in Squid-2.6 is not available in Squid-3. Some has been dropped as they are not needed. Some has not yet been forward-ported to Squid-3 and may appear in a later release.

- refresh_stale_hit option. Not yet ported.
- ability to follow X-Forwarded-For. Not yet ported.
- Full caching of Vary/ETag using If-None-Match. Only basic Vary cache supported. Not yet ported.
- Mapping of server error messages. Not yet ported.
- http_access2 access directive. Not yet ported.
- Location header rewrites. Not yet ported.
- umask directive. Not yet ported.
- wais_relay. Feature dropped as it's equivalent to cache_peer + cache_peer_access.
- urlgroup. Not yet ported.
- collapsed forwarding. Not yet ported.

## 4.3 Logging changes

### access.log

The TCP_REFRESH_HIT and TCP_REFRESH_MISS log types have been replaced because they were misleading (all refreshes need to query the origin server, so they could never be hits). The following log types have been introduced to replace them:

TCP_REFRESH_UNMODIFIED

  The requested object was cached but STALE. The IMS query for the object resulted in "304 not modified".

TCP_REFRESH_MODIFIED

  The requested object was cached but STALE. The IMS query returned the new content.

See http://www.squid-cache.org/Doc/FAQ/FAQ-6.html#ss6.7 for a definition of all log types.

## 4.4 Changes to squid.conf

There have been many changes to Squid's configuration file since Squid-2.6.

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

- New tags
- Changes to existing tags
- Removed tags

### New tags

minimum_icp_query_timeout (msec)

      Default: 5

      Normally the ICP query timeout is determined dynamically.  But
      sometimes it can lead to very small timeouts, even lower than
      the normal latency variance on your link due to traffic.
      Use this option to put an lower limit on the dynamic timeout
      value.  Do NOT use this option to always use a fixed (instead
      of a dynamic) timeout value. To set a fixed timeout see the
      'icp_query_timeout' directive.

background_ping_rate

      Default: 10 seconds

      Controls how often the ICP pings are sent to siblings that
      have background-ping set.

httpd_accel_surrogate_id

      Default: unset

      Surrogates (http://www.esi.org/architecture_spec_1.0.html)
      need an identification token to allow control targeting. Because
      a farm of surrogates may all perform the same tasks, they may share
      an identification token.

http_accel_surrogate_remote on|off

      Default: off

      Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
      Set this to on to have squid behave as a remote surrogate.

esi_parser libxml2|expat|custom

      Default: custom

      ESI markup is not strictly XML compatible. The custom ESI parser
      will give higher performance, but cannot handle non ASCII character
      encodings.

email_err_data on|off

      Default: on

      If enabled, information about the occurred error will be
      included in the mailto links of the ERR pages (if %W is set)
      so that the email body contains the data.
      Syntax is <A HREF="mailto:%w%W">%w</A>

refresh_all_ims on|off

      Default: off

      When you enable this option, squid will always check
      the origin server for an update when a client sends an
      If-Modified-Since request.  Many browsers use IMS
      requests when the user requests a reload, and this
      ensures those clients receive the latest version.

      By default (off), squid may return a Not Modified response
      based on the age of the cached version.

request_header_access

  Replaces the header_access directive of Squid-2.6 and earlier, but applies to requests only.

reply_header_access

  Replaces the header_access directive of Squid-2.6 and earlier, but applies to replies only.

icap_enable on|off

      Default: off

      If you want to enable the ICAP module support, set this to on.

icap_preview_enable on|off

      Default: off

      Set this to 'on' if you want to enable the ICAP preview
      feature in Squid.

icap_preview_size

      Default: -1

      The default size of preview data to be sent to the ICAP server.
      -1 means no preview. This value might be overwritten on a per server
      basis by OPTIONS requests.

icap_default_options_ttl (seconds)

      Default: 60

      The default TTL value for ICAP OPTIONS responses that don't have
      an Options-TTL header.

icap_persistent_connections on|off

      Default: on

      Whether or not Squid should use persistent connections to
      an ICAP server.

icap_send_client_ip on|off

      Default: off

      This adds the header "X-Client-IP" to ICAP requests.

icap_send_client_username on|off

      Default: off

      This adds the header "X-Client-Username" to ICAP requests
      if proxy access is authentified.

icap_service

      Default: none

      Defines a single ICAP service

      icap_service servicename vectoring_point bypass service_url

      vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
      This specifies at which point of request processing the ICAP
      service should be plugged in.
      bypass = 1|0
      If set to 1 and the ICAP server cannot be reached, the request will go
      through without being processed by an ICAP server
      service_url = icap://servername:port/service

      Note: reqmod_precache and respmod_postcache is not yet implemented

      Example:
      icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod
      icap_service service_2 respmod_precache 0 icap://icap2.mydomain.net:1344/respmod

icap_class

      Default: none

      Defines an ICAP service chain. If there are multiple services per
      vectoring point, they are processed in the specified order.

      icap_class classname servicename...

      Example:
      icap_class class_1 service_1 service_2
      icap class class_2 service_1 service_3

icap_access

      Default: none

      Redirects a request through an ICAP service class, depending
      on given acls

      icap_access classname allow|deny [!]aclname...

      The icap_access statements are processed in the order they appear in
      this configuration file. If an access list matches, the processing stops.
      For an "allow" rule, the specified class is used for the request. A "deny"
      rule simply stops processing without using the class. You can also use the
      special classname "None".

      For backward compatibility, it is also possible to use services
      directly here.

      Example:
      icap_access class_1 allow all

accept_filter

      The name of an accept(2) filter to install on Squid's
      listen socket(s).  This feature is perhaps specific to
      FreeBSD and requires support in the kernel.

      The 'httpready' filter delays delivering new connections
      to Squid until a full HTTP request has been received.
      See the accf_http(9) man page.

### Changes to existing tags

http_port

  New options:

          disable-pmtu-discovery=
            Control Path-MTU discovery usage:
              off          lets OS decide on what to do (default).
              transparent  disable PMTU discovery when transparent support is enabled.
              always       disable always PMTU discovery.

          In many setups of transparently intercepting proxies Path-MTU
          discovery can not work on traffic towards the clients. This is
          the case when the intercepting device does not fully track
          connections and fails to forward ICMP must fragment messages
          to the cache server. If you have such setup and experience that
          certain clients sporadically hang or never complete requests set
          disable-pmtu-discovery option to 'transparent'.

  Removed options:

          urlgroup=, not yet ported to Squid-3.

          no-connection-auth, not yet ported to Squid-3.

https_port

  Removed options:

          urlgroup=, not yet ported to Squid-3.

cache_peer

  New options:

           basetime=n

           background-ping

           weighted-round-robin

           use 'basetime=n' to specify a base amount to
           be subtracted from round trip times of parents.
           It is subtracted before division by weight in calculating
           which parent to fectch from. If the rtt is less than the
           base time the rtt is set to a minimal value.

           use 'background-ping' to only send ICP queries to this
           neighbor infrequently. This is used to keep the neighbor
           round trip time updated and is usually used in
           conjunction with weighted-round-robin.

           use 'weighted-round-robin' to define a set of parents
           which should be used in a round-robin fashion with the
           frequency of each parent being based on the round trip
           time. Closer parents are used more often.
           Usually used for background-ping parents.

  Removed options:

          userhash, not yet ported to Squid-3

          sourcehash, not yet ported to Squid-2

          monitorurl, monitorsize etc, not yet ported to Squid-3

          connection-auth=, not yet ported to Squid-3

cache_dir

  Common options

          no-store, replaces the older read-only option

          min-size, not yet portedto Squid-3

  COSS file system:

          The coss file store is experimental, and still lacks much
          of the functionality found in 2.6.

          overwrite-percent=n, not yet ported to Squid-3.

          max-stripe-waste=n, not yet ported to Squid-3.

          membufs=n, not yet ported to Squid-3.

          maxfullbufs=n, not yet ported to Squid-3.

auth_param

  Removed Basic auth option

          blankpasswor, not yet ported to squid-3.
          auth_param basic concurrency 0

  Removed digest options:

          concurrency, not yet ported to Squid-3.

external_acl_type

  New format specifications:

          %URI          Requested URI

          %PATH         Requested URL path

  Removed format specifications:

          %ACL, not yet ported to Squid-3

          %DATA, not yet ported to Squid-3

  New result keywords:

           tag=  Apply a tag to a request (for both ERR and OK results)
                 Only sets a tag, does not alter existing tags.

refresh_pattern

  New options:

          ignore-no-store
          refresh-ims

          ignore-no-store ignores any ``Cache-control: no-store''
          headers received from a server. Doing this VIOLATES
          the HTTP standard. Enabling this feature could make you
          liable for problems which it causes.

          refresh-ims causes squid to contact the origin server
          when a client issues an If-Modified-Since request. This
          ensures that the client will receive an updated version
          if one is available.

acl

  New types:

          acl aclname http_status 200 301 500- 400-403 ...     # status code in reply

  Removed types:

          acl aclname urllogin [-i] [^a-zA-Z0-9] ...      # regex matching on URL login field

          acl urlgroup group1 ...
              # match against the urlgroup as indicated by redirectors

short_icon_urls

  New default:

          Default: on
          (Old default: off)

delay_class

  New delay classes:

          class 4 Everything in a class 3 delay pool, with an
          additional limit on a per user basis. This
          only takes effect if the username is established
          in advance - by forcing authentication in your
          http_access rules.

          class 5 Requests are grouped according their tag (see
          external_acl's tag= reply).

htcp_port

  New default to require the feature to be enabled in squid.conf:

          Default: 0 (disabled)
          (Old default: 4827)

icp_port

  New default to require the feature to be enabled in squid.conf:

          Default: 0 (disabled)
          (Old default: 3130)

snmp_port

  New default to require the feature to be enabled in squid.conf:

          Default: 0 (disabled)
          (Old default: 3401)

logformat

  New format tags:

          rp      Request URL-Path excluding hostname

          et      Tag returned by external acl

          <sH     Reply high offset sent

          <sS     Upstream object size

  Removed format tags:

          >st     Request size including HTTP headers, not yet ported to Squid-3.

          st      Request+Reply size including HTTP headers, not yet ported to Squid-3.

reply_body_max_size

  Syntax changed:

          reply_body_max_size size [acl acl...]

  allow/deny no longer used.

url_rewrite_program

  No urlgroup support in either requests or responese

### Removed tags

broken_vary_encoding

  Not yet ported to Squid-3.

cache_vary

  Not yet ported to Squid-3.

collapsed_forwarding

  Not yet ported to Squid-3.

follow_x_forwarded_for

  Not yet ported to Squid-3.

*_uses_indirect_client

  Not yet ported to Squid-3.

error_map

  Not yet ported to Squid-3.

header_access

  This has been replaced by request_header_access and reply_header_access

http_access2

  Not yet ported to Squid-3.

httpd_accel_no_pmtu_disc

  Replaced by disable-pmtu-discovery http_port option

location_rewrite_*

  Not yet ported to Squid-3.

refresh_stale_hit

  Not yet ported to Squid-3.

umask

  Not yet ported to Squid-3.

wais_relay_*

  equivalent to cache_peer + cache_peer_access.