Some overlooked cleanup

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

<!doctype linuxdoc system>
<article>
<title>Squid 3.0.PRE4 release notes</title>
<author>Squid Developers</author>
<date>$Id: release-3.0.sgml,v 1.21 2006/06/19 22:52:58 hno Exp $</date>

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

<toc>

<sect>Notice
<p>
The Squid Team are pleased to announce the release of Squid-3.0.PRE4 for pre-release testing.

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

This is the first PRE release since August 2003, and marks a renewed effort to push Squid-3.0 through to STABLE.

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://www.squid-cache.org/Doc/FAQ/FAQ-11.html#ss11.19"> 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.0&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.0">.

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


<sect>Changes since Squid-2.5.STABLE14
<sect1>Major new features
<p>
Squid 3.0 represents a major rewrite of Squid 2.5 and has a large number of new features.

The most important of these are:

<itemize>
        <item>Edge Side Include implementation (www.esi.org)
        <item>ICAP implementation (www.i-cap.org)
        <item>Better support for reverse proxy setups. The httpd_accel_* directives are now gone, replaced by http(s)_port options and cache_peer based request forwarding
        <item>Better support for SSL
        <item>Better support for external ACLs
        <item>Finer control over cacheability (refresh_pattern)
        <item>Custom log formats and the ability to log different requests to different log files
</itemize>

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

<sect1>Logging changes
<sect2>access.log
<p>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:

<descrip>
        <tag>TCP_REFRESH_UNMODIFIED</tag>
        <p>The requested object was cached but STALE. The IMS query for the object resulted in "304 not modified".
        <tag>TCP_REFRESH_MODIFIED</tag>
        <p>The requested object was cached but STALE. The IMS query returned the new content.
</descrip>
<p>See <url url="http://www.squid-cache.org/Doc/FAQ/FAQ-6.html#ss6.7"> for a definition of all log types.




<sect1>Changes to squid.conf
<p>
There have been many changes to Squid's configuration file since Squid-2.5.

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

<itemize>
        <item><ref id="newtags" name="New tags">
        <item><ref id="modifiedtags" name="Changes to existing tags">
        <item><ref id="removedtags" name="Removed tags">
</itemize>

<p>



<sect2>New tags<label id="newtags">

<p>
<descrip>
        <tag>ssl_engine</tag>
        <verb>
Default: none

The openssl engine to use. You will need to set this if you
would like to use hardware SSL acceleration for example.
        </verb>
        <tag>sslproxy_client_certificate</tag>
        <verb>
Default: none

Client SSL Certificate to use when proxying https:// URLs
        </verb>
        <tag>sslproxy_client_key</tag>
        <verb>
Default: none

Client SSL Key to use when proxying https:// URLs
        </verb>
        <tag>sslproxy_version</tag>
        <verb>
Default: 1

SSL version level to use when proxying https:// URLs
        </verb>
        <tag>sslproxy_options</tag>
        <verb>
Default: none

SSL engine options to use when proxying https:// URLs
        </verb>
        <tag>sslproxy_cipher</tag>
        <verb>
Default: none

SSL cipher list to use when proxying https:// URLs
        </verb>
        <tag>sslproxy_cafile</tag>
        <verb>
Default: none

file containing CA certificates to use when verifying server
certificates while proxying https:// URLs
        </verb>
        <tag>sslproxy_capath</tag>
        <verb>
Default: none

directory containing CA certificates to use when verifying
server certificates while proxying https:// URLs
        </verb>
        <tag>sslproxy_flags</tag>
        <verb>
Default: none

Various flags modifying the use of SSL while proxying https:// URLs:
    DONT_VERIFY_PEER    Accept certificates even if they fail to
verify.
    NO_DEFAULT_CA       Don't use the default CA list built in
to OpenSSL.
        </verb>
        <tag>sslpassword_program</tag>
        <verb>
Default: none

Specify a program used for entering SSL key passphrases
when using encrypted SSL certificate keys. If not specified
keys must either be unencrypted, or Squid started with the -N
option to allow it to query interactively for the passphrase.
        </verb>
        <tag>minimum_icp_query_timeout (msec)</tag>
        <verb>
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.
        </verb>
        <tag>background_ping_rate</tag>
        <verb>
Default: 10 seconds

Controls how often the ICP pings are sent to siblings that
have background-ping set.
        </verb>
        <tag>logformat</tag>
        <verb>
Default: none

Usage:

logformat <name> <format specification>

Defines an access log format.

The <format specification> is a string with embedded % format codes

% format codes all follow the same basic structure where all but
the formatcode is optional. Output strings are automatically escaped
as required according to their context and the output format
modifiers are usually not needed, but can be specified if an explicit
output format is desired.

% ["|[|'|#] [-] [[0]width] [{argument}] formatcode

"       output in quoted string format
[       output in squid text log format as used by log_mime_hdrs
#       output in URL quoted format
'       output as-is

-       left aligned
width   field width. If starting with 0 the
output is zero padded
{arg}   argument such as header name etc

Format codes:

>a      Client source IP address
>A      Client FQDN
<A      Server IP address or peer name
la      Local IP address (http_port)
lp      Local port number (http_port)
ts      Seconds since epoch
tu      subsecond time (milliseconds)
tl      Local time. Optional strftime format argument
default %d/%b/%Y:%H:%M:S %z
tg      GMT time. Optional strftime format argument
default %d/%b/%Y:%H:%M:S %z
tr      Response time (milliseconds)
>h      Request header. Optional header name argument
on the format header[:[separator]element]
<h      Reply header. Optional header name argument
as for >h
un      User name
ul      User login
ui      User ident
ue      User from external acl
Hs      HTTP status code
Ss      Squid request status (TCP_MISS etc)
Sh      Squid hierarchy status (DEFAULT_PARENT etc)
mt      MIME content type
rm      Request method (GET/POST etc)
ru      Request URL
rv      Request protocol version
et      Tag returned by external acl
ea      Log string returned by external acl
<st     Reply size including HTTP headers
<sH     Reply high offset sent
<sS     Upstream object size
%       a literal % character

logformat squid  %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
logformat squidmime  %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h]
logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st %Ss:%Sh
logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
        </verb>
        <tag>check_hostnames on|off</tag>
        <verb>
Default: on

For security and stability reasons Squid by default checks
hostnames for Internet standard RFC compliance. If you do not want
Squid to perform these checks turn this directive off.
        </verb>
        <tag>url_rewrite_concurrency redirect_concurrency</tag>
        <verb>
Default: 0

The number of requests each redirector helper can handle in
parallell. Defaults to 0 which indicates the redirector
is a old-style singlethreaded redirector.
        </verb>
        <tag>read_ahead_gap</tag>
        <verb>
Default: 16 KB

The amount of data the cache will buffer ahead of what has been
sent to the client when retrieving an object from another server.
        </verb>
        <tag>log_access allow|deny acl acl...</tag>
        <verb>
Default: none

This options allows you to control which requests gets logged
to access.log (see access_log directive). Requests denied for
logging will also not be accounted for in performance counters.
        </verb>
        <tag>httpd_suppress_version_string on|off</tag>
        <verb>
Default: off

Suppress Squid version string info in HTTP headers and HTML error pages.
        </verb>
        <tag>httpd_accel_surrogate_id</tag>
        <verb>
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.
        </verb>
        <tag>http_accel_surrogate_remote on|off</tag>
        <verb>
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.
        </verb>
        <tag>esi_parser libxml2|expat|custom</tag>
        <verb>
Default: custom

ESI markup is not strictly XML compatible. The custom ESI parser
will give higher performance, but cannot handle non ASCII character
encodings.
        </verb>
        <tag>email_err_data on|off</tag>
        <verb>
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 &lt;A HREF="mailto:%w%W"&gt;%w&lt;/A&gt;
        </verb>
        <tag>via on|off</tag>
        <verb>
Default: on

If set (default), Squid will include a Via header in requests and
replies as required by RFC2616.
        </verb>
        <tag>refresh_all_ims on|off</tag>
        <verb>
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.
        </verb>
        <tag>request_header_access</tag>
        <verb>
Default: none

Usage: request_header_access header_name allow|deny [!]aclname ...

WARNING: Doing this VIOLATES the HTTP standard.  Enabling
this feature could make you liable for problems which it
causes.

This option replaces the old 'anonymize_headers' and the
older 'http_anonymizer' option with something that is much
more configurable. This new method creates a list of ACLs
for each header, allowing you very fine-tuned header
mangling.

This option only applies to request headers, i.e., from the
client to the server.

You can only specify known headers for the header name.
Other headers are reclassified as 'Other'. You can also
refer to all the headers with 'All'.

For example, to achieve the same behavior as the old
'http_anonymizer standard' option, you should use:

request_header_access From deny all
request_header_access Referer deny all
request_header_access Server deny all
request_header_access User-Agent deny all
request_header_access WWW-Authenticate deny all
request_header_access Link deny all

Or, to reproduce the old 'http_anonymizer paranoid' feature
you should use:

request_header_access Allow allow all
request_header_access Authorization allow all
request_header_access WWW-Authenticate allow all
request_header_access Proxy-Authorization allow all
request_header_access Proxy-Authenticate allow all
request_header_access Cache-Control allow all
request_header_access Content-Encoding allow all
request_header_access Content-Length allow all
request_header_access Content-Type allow all
request_header_access Date allow all
request_header_access Expires allow all
request_header_access Host allow all
request_header_access If-Modified-Since allow all
request_header_access Last-Modified allow all
request_header_access Location allow all
request_header_access Pragma allow all
request_header_access Accept allow all
request_header_access Accept-Charset allow all
request_header_access Accept-Encoding allow all
request_header_access Accept-Language allow all
request_header_access Content-Language allow all
request_header_access Mime-Version allow all
request_header_access Retry-After allow all
request_header_access Title allow all
request_header_access Connection allow all
request_header_access Proxy-Connection allow all
request_header_access All deny all

although many of those are HTTP reply headers, and so should be
controlled with the reply_header_access directive.

By default, all headers are allowed (no anonymizing is
performed).
        </verb>
        <tag>reply_header_access</tag>
        <verb>
Default: none

Usage: reply_header_access header_name allow|deny [!]aclname ...

WARNING: Doing this VIOLATES the HTTP standard.  Enabling
this feature could make you liable for problems which it
causes.

This option only applies to reply headers, i.e., from the
server to the client.

This is the same as request_header_access, but in the other
direction.

This option replaces the old 'anonymize_headers' and the
older 'http_anonymizer' option with something that is much
more configurable. This new method creates a list of ACLs
for each header, allowing you very fine-tuned header
mangling.

You can only specify known headers for the header name.
Other headers are reclassified as 'Other'. You can also
refer to all the headers with 'All'.

For example, to achieve the same behavior as the old
'http_anonymizer standard' option, you should use:

reply_header_access From deny all
reply_header_access Referer deny all
reply_header_access Server deny all
reply_header_access User-Agent deny all
reply_header_access WWW-Authenticate deny all
reply_header_access Link deny all

Or, to reproduce the old 'http_anonymizer paranoid' feature
you should use:

reply_header_access Allow allow all
reply_header_access Authorization allow all
reply_header_access WWW-Authenticate allow all
reply_header_access Proxy-Authorization allow all
reply_header_access Proxy-Authenticate allow all
reply_header_access Cache-Control allow all
reply_header_access Content-Encoding allow all
reply_header_access Content-Length allow all
reply_header_access Content-Type allow all
reply_header_access Date allow all
reply_header_access Expires allow all
reply_header_access Host allow all
reply_header_access If-Modified-Since allow all
reply_header_access Last-Modified allow all
reply_header_access Location allow all
reply_header_access Pragma allow all
reply_header_access Accept allow all
reply_header_access Accept-Charset allow all
reply_header_access Accept-Encoding allow all
reply_header_access Accept-Language allow all
reply_header_access Content-Language allow all
reply_header_access Mime-Version allow all
reply_header_access Retry-After allow all
reply_header_access Title allow all
reply_header_access Connection allow all
reply_header_access Proxy-Connection allow all
reply_header_access All deny all

although the HTTP request headers won't be usefully controlled
by this directive -- see request_header_access for details.

By default, all headers are allowed (no anonymizing is
performed).
        </verb>
        <tag>minimum_expiry_time</tag>
        <verb>
Default: 60 seconds

The minimum caching time according to (Expires - Date)
Headers Squid honors if the object can't be revalidated
defaults to 60 seconds. In reverse proxy enorinments it
might be desirable to honor shorter object lifetimes. It
is most likely better to make your server return a
meaningful Last-Modified header however. In ESI environments
where page fragments often have short lifetimes, this will
often be best set to 0.
        </verb>
        <tag>icap_enable on|off</tag>
        <verb>
Default: off

If you want to enable the ICAP module support, set this to on.
        </verb>
        <tag>icap_preview_enable on|off</tag>
        <verb>
Default: off

Set this to 'on' if you want to enable the ICAP preview
feature in Squid.
        </verb>
        <tag>icap_preview_size</tag>
        <verb>
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.
        </verb>
        <tag>icap_default_options_ttl (seconds)</tag>
        <verb>
Default: 60

The default TTL value for ICAP OPTIONS responses that don't have
an Options-TTL header.
        </verb>
        <tag>icap_persistent_connections on|off</tag>
        <verb>
Default: on

Whether or not Squid should use persistent connections to
an ICAP server.
        </verb>
        <tag>icap_send_client_ip on|off</tag>
        <verb>
Default: off

This adds the header "X-Client-IP" to ICAP requests.
        </verb>
        <tag>icap_send_client_username on|off</tag>
        <verb>
Default: off

This adds the header "X-Client-Username" to ICAP requests
if proxy access is authentified.
        </verb>
        <tag>icap_service</tag>
        <verb>
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
        </verb>
        <tag>icap_class</tag>
        <verb>
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
        </verb>
        <tag>icap_access</tag>
        <verb>
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
        </verb>
</descrip>


<sect2>Changes to existing tags<label id="modifiedtags">
<p>
<descrip>
        <tag>http_port</tag>
        <p>New options:
        <verb>
    transparent  Support for transparent proxies

    accel        Accelerator mode. Also set implicit by the other accelerator directives

    vhost        Accelerator mode using Host header for virtual domain support

    vport        Accelerator with IP based virtual host support

    vport=NN     As above, but uses specified port number rather
                 than the http_port number

    defaultsite= Main web site name for accelerators

    protocol=    Protocol to reconstruct accelerated requests with.
                 Defaults to http

    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'.
        </verb>
        <tag> https_port</tag>
        <p>New options:
        <verb>
    defaultsite= The name of the https site presented on this port

    protocol=    Protocol to reconstruct accelerated requests
                 with. Defaults to https

    options=     Various SSL engine options. The most important
                 being:
    NO_SSLv2  Disallow the use of SSLv2
    NO_SSLv3  Disallow the use of SSLv3
    NO_TLSv1  Disallow the use of TLSv1
    SINGLE_DH_USE Always create a new key when using
                  temporary/ephemeral DH key exchanges
    See src/ssl_support.c or OpenSSL SSL_CTX_set_options
    documentation for a complete list of options

    clientca=    File containing the list of CAs to use when
                 requesting a client certificate

    cafile=      File containing additional CA certificates to
                 use when verifying client certificates. If unset
                 clientca will be used

    capath=      Directory containing additional CA certificates
                 and CRL lists to use when verifying client certificates

    crlfile=     File of additional CRL lists to use when verifying
                 the client certificate, in addition to CRLs stored in
                 the capath. Implies VERIFY_CRL flag below.

    dhparams=    File containing DH parameters for temporary/ephemeral
                 DH key exchanges

    sslflags=    Various flags modifying the use of SSL:
                 DELAYED_AUTH
                    Don't request client certificates
                    immediately, but wait until acl processing
                    requires a certificate (not yet implemented)
                 NO_DEFAULT_CA
                    Don't use the default CA lists built in
                    to OpenSSL
                 NO_SESSION_REUSE
                    Don't allow for session reuse. Each connection
                    will result in a new SSL session.
                 VERIFY_CRL
                    Verify CRL lists when accepting client
                    certificates
                 VERIFY_CRL_ALL
                    Verify CRL lists for all certificates in the
                    client certificate chain

    sslcontext=  SSL session ID context identifier.

    accelAccelerator mode. Also set implicit by the other
    accelerator directives

    vhostAccelerator mode using Host header for virtual
    domain support

    vportAccelerator with IP based virtual host support

    vport=NN     As above, but uses specified port number rather
    than the https_port number
        </verb>
        <tag>cache_peer</tag>
        <p>New options:
        <verb>
     basetime=n
     background-ping
     weighted-round-robin
     carp
     htcp-oldsquid
     originserver
     name=xxx
     forceddomain=name
     ssl
     sslcert=/path/to/ssl/certificate
     sslkey=/path/to/ssl/key
     sslversion=1|2|3|4
     sslcipher=...
     ssloptions=...
     front-end-https[=on|auto]


     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.

     use 'carp' to define a set of parents which should
     be used as a CARP array. The requests will be
     distributed among the parents based on the CARP load
     balancing hash function based on their weigth.

     use 'htcp-oldsquid' to send HTCP to old Squid versions

     'originserver' causes this parent peer to be contacted as
     a origin server. Meant to be used in accelerator setups.

     use 'name=xxx' if you have multiple peers on the same
     host but different ports. This name can be used to
     differentiate the peers in cache_peer_access and similar
     directives.

     use 'forceddomain=name' to forcibly set the Host header
     of requests forwarded to this peer. Useful in accelerator
     setups where the server (peer) expects a certain domain
     name and using redirectors to feed this domainname
     is not feasible.

     use 'ssl' to indicate connections to this peer should
     bs SSL/TLS encrypted.

     use 'sslcert=/path/to/ssl/certificate' to specify a client
     SSL certificate to use when connecting to this peer.

     use 'sslkey=/path/to/ssl/key' to specify the private SSL
     key corresponding to sslcert above. If 'sslkey' is not
     specified 'sslcert' is assumed to reference a
     combined file containing both the certificate and the key.

     use sslversion=1|2|3|4 to specify the SSL version to use
     when connecting to this peer
        1 = automatic (default)
        2 = SSL v2 only
        3 = SSL v3 only
        4 = TLS v1 only

     use sslcipher=... to specify the list of valid SSL chipers
     to use when connecting to this peer

     use ssloptions=... to specify various SSL engine options:
        NO_SSLv2  Disallow the use of SSLv2
        NO_SSLv3  Disallow the use of SSLv3
        NO_TLSv1  Disallow the use of TLSv1
     See src/ssl_support.c or the OpenSSL documentation for
     a more complete list.

     use cafile=... to specify a file containing additional
     CA certificates to use when verifying the peer certificate

     use capath=... to specify a directory containing additional
     CA certificates to use when verifying the peer certificate

     use sslflags=... to specify various flags modifying the
     SSL implementation:
        DONT_VERIFY_PEER
            Accept certificates even if they fail to
            verify.
        NO_DEFAULT_CA
            Don't use the default CA list built in
            to OpenSSL.
        DONT_VERIFY_DOMAIN
            Don't verify the peer certificate
            matches the server name

     use sslname= to specify the peer name as advertised
     in it's certificate. Used for verifying the correctness
     of the received peer certificate. If not specified the
     peer hostname will be used.

     use front-end-https to enable the "Front-End-Https: On"
     header needed when using Squid as a SSL frontend infront
     of Microsoft OWA. See MS KB document Q307347 for details
     on this header. If set to auto the header will
     only be added if the request is forwarded as a https://
     URL.
        </verb>
        <p>Removed options:
        <verb>
    carp-load-factor
        </verb>
        <tag>cache_dir</tag>
        <p>COSS stripe file:
        <verb>
    The coss file store has changed from 2.5. Now it uses a file
    called 'stripe' in the directory names in the config - and
    this will be created by squid -z.
        </verb>
        <tag>access_log cache_access_log</tag>
        <p>Takes an optional log format:
        <verb>
    These files log client request activities. Has a line every HTTP or
    ICP request. The format is:
    access_log <filepath> [<logformat name> [acl acl ...]]
    access_log none [acl acl ...]]

    Will log to the specified file using the specified format (which
    must be defined in a logformat directive) those entries which match
    ALL the acl's specified (which must be defined in acl clauses).
    If no acl is specified, all requests will be logged to this file.

    To disable logging of a request use the filepath "none", in which case
    a logformat name should not be specified.

    To log the request via syslog specify a filepath of "syslog":

    access_log syslog[:facility|priority] [format [acl1 [acl2 ....]]]
    where facility could be any of:
        LOG_AUTHPRIV, LOG_DAEMON, LOG_LOCAL0 .. LOG_LOCAL7 or LOG_USER.

    And priority could be any of:
        LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
        </verb>
        <tag>redirect_program</tag>
        <p>New alias: 'url_rewrite_program'
        <tag>redirect_children</tag>
        <p>New alias: 'url_rewrite_children'
        <tag>redirect_host_header</tag>
        <p>New alias: 'url_rewrite_host_header'
        <tag>auth_param</tag>
        <p>New option for basic scheme:
        <verb>
    "concurrency" concurrency
    The number of concurrent requests the helper can process.
    The default of 0 is used for helpers who only supports
    one request at a time.
    auth_param basic concurrency 0
        </verb>
        <p>Removed NTLM options:
        <verb>
    "max_challenge_reuses" number
    The maximum number of times a challenge given by a ntlm authentication
    helper can be reused. Increasing this number increases your exposure
    to replay attacks on your network. 0 (the default) means use the
    challenge is used only once. See also the max_ntlm_challenge_lifetime
    directive if enabling challenge reuses.
    auth_param ntlm max_challenge_reuses 0

    "max_challenge_lifetime" timespan
    The maximum time period a ntlm challenge is reused over. The
    actual period will be the minimum of this time AND the number of
    reused challenges.
    auth_param ntlm max_challenge_lifetime 2 minutes

    "use_ntlm_negotiate" on|off
    Enables support for NTLM NEGOTIATE packet exchanges with the helper.
    The configured ntlm authenticator must be able to handle NTLM
    NEGOTIATE packet. See the authenticator programs documentation if
    unsure. ntlm_auth from Samba-3.0.2 or later supports the use of this
    option.
    The NEGOTIATE packet is required to support NTLMv2 and a
    number of other negotiable NTLMSSP options, and also makes it
    more likely the negotiation is successful. Enabling this parameter
    will also solve problems encountered when NT domain policies
    restrict users to access only certain workstations. When this is off,
    all users must be allowed to log on the proxy servers too, or they'll
    get "invalid workstation" errors - and access denied - when trying to
    use Squid's services.
    Use of ntlm NEGOTIATE is incompatible with challenge reuse, so
    enabling this parameter will OVERRIDE the max_challenge_reuses and
    max_challenge_lifetime parameters and set them to 0.
    auth_param ntlm use_ntlm_negotiate off
        </verb>
        <p>New NTLM option:
        <verb>
    "keep_alive" on|off
    If you experience problems with PUT/POST requests when using the
    Negotiate authentication scheme then you can try setting this to
    off. This will cause Squid to forcibly close the connection on
    the initial requests where the browser asks which schemes are
    supported by the proxy.
        </verb>
        <tag>external_acl_type</tag>
        <p>New options:
        <verb>
    concurrency=n concurrency level per process. Use 0 for old style
    helpers who can only process a single request at a time.
    
    grace=n       Percentage remaining of TTL where a refresh of a
    cached entry should be initiated without needing to
    wait for a new reply. (default 0 for no grace period)
    protocol=2.5  Compatibility mode for Squid-2.5 external acl helpers
        </verb>
        <p>New format specifications:
        <verb>
    %EXT_USER     Username from external acl
    %SRCPORT      Client source port
    %PATH Requested URL path
    %METHOD       Request method
    %MYADDR       Squid interface address
    %MYPORT       Squid http_port number
    %USER_CERT    SSL User certificate in PEM format
    %USER_CERTCHAIN SSL User certificate chain in PEM format
    %USER_CERT_xx SSL User certificate subject attribute xx
    %USER_CA_xx   SSL User certificate issuer attribute xx
        </verb>
        <p>New keywords:
        <verb>
    user= The users name (login)
    password=     The users password (for login= cache_peer option)
    message=      Message describing the reason. Available as %o
                  in error pages
     tag=  Apply a tag to a request (for both ERR and OK results)
           Only sets a tag, does not alter existing tags.
    log=  String to be logged in access.log. Available as
          %ea in logformat specifications

    Keyword values need to be URL escaped if they may contain
    contain whitespace or quotes.

    In Squid-2.5 compatibility mode quoting using " and \ is used
    instead of URL escaping.
        </verb>
        <p>Removed option:
        <verb>
    protocol=3.0  Use URL-escaped strings instead of quoting
        </verb>
        <tag>refresh_pattern</tag>
        <p>New options:
        <verb>
    ignore-no-cache
    ignore-no-store
    ignore-private
    ignore-auth
    refresh-ims

    ignore-no-cache ignores any ``Pragma: no-cache'' and
    ``Cache-control: no-cache'' headers received from a server.
    The HTTP RFC never allows the use of this (Pragma) header
    from a server, only a client, though plenty of servers
    send it anyway.

    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.

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

    ignore-auth caches responses to requests with authorization,
    irrespective of ``Cache-control'' 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.
        </verb>
        <tag>negative_dns_ttl</tag>
        <p>New default:
        <verb>
    Default: 5 minutes
    (Old default: 1 minute)
        </verb>
        <tag>acl</tag>
        <p>New types:
        <verb>
    acl aclname http_status 200 301 500- 400-403 ...     # status code in reply

    acl aclname user_cert attribute values...
      # match against attributes in a user SSL certificate
      # attribute is one of DN/C/O/CN/L/ST

    acl aclname ca_cert attribute values...
      # match against attributes a users issuing CA SSL certificate
      # attribute is one of DN/C/O/CN/L/ST

    acl aclname ext_user username ...
    acl aclname ext_user_regex [-i] pattern ...
      # string match on username returned by external acl processing
      # use REQUIRED to accept any non-null user name.
        </verb>
        <p>Removed types:
        <verb>
    acl aclname urllogin [-i] [^a-zA-Z0-9] ...      # regex matching on URL login field

    acl aclname req_header header-name [-i] any\.regex\.here
      # regex match against any of the known request headers.  May be
      # thought of as a superset of "browser", "referer" and "mime-type"
      # ACLs.

    acl aclname rep_header header-name [-i] any\.regex\.here
      # regex match against any of the known response headers.
      # Example:
      #
      # acl many_spaces rep_header Content-Disposition -i [[:space:]]{3,}
        </verb>
        <tag>short_icon_urls</tag>
        <p>New default:
        <verb>
    Default: on
    (Old default: off)
        </verb>
        <tag>delay_class</tag>
        <p>New delay classes:
        <verb>
    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).
        </verb>
</descrip>




<sect2>Removed tags<label id="removedtags">
<p>
<descrip>
        <tag>httpd_accel_host</tag>
        Replaced by the defaultsite= or vport=0 (in case of virtual) http_port options
        <tag>httpd_accel_port</tag>
        Replaced by vport http(s)_port option
        <tag>httpd_accel_single_host on|off</tag>
        Replaced by cache_peer originserver based request forwarding
        making this option obsolete.
        <tag>httpd_accel_with_proxy on|off</tag>
        Obsolete, no longer needed.
        <tag>httpd_accel_uses_host_header on|off</tag>
        This has been replaced by the vhost http(s)_port option
        <tag>httpd_accel_no_pmtu_disc on|off</tag>
        This has been replaced by the disable-pmtu-discovery=.. http_port option
        <tag>header_access</tag>
        <p>This has been replaced by request_header_access and reply_header_access
</descrip>


</article>