The Squid Team are pleased to announce the release of Squid-3.0.PRE5 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://www.squid-cache.org/Doc/FAQ/FAQ-11.html#ss11.19 for how to submit a report with a stack trace.
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.
The change history can be viewed here.
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:
Most user-facing changes are reflected in squid.conf (see below).
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:
The requested object was cached but STALE. The IMS query for the object resulted in "304 not 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.
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:
Default: none The openssl engine to use. You will need to set this if you would like to use hardware SSL acceleration for example.
Default: none Client SSL Certificate to use when proxying https:// URLs
Default: none Client SSL Key to use when proxying https:// URLs
Default: 1 SSL version level to use when proxying https:// URLs
Default: none SSL engine options to use when proxying https:// URLs
Default: none SSL cipher list to use when proxying https:// URLs
Default: none file containing CA certificates to use when verifying server certificates while proxying https:// URLs
Default: none directory containing CA certificates to use when verifying server certificates while proxying https:// URLs
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.
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.
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.
Default: 10 seconds Controls how often the ICP pings are sent to siblings that have background-ping set.
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
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.
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.
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.
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.
Default: off Suppress Squid version string info in HTTP headers and HTML error pages.
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.
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.
Default: custom ESI markup is not strictly XML compatible. The custom ESI parser will give higher performance, but cannot handle non ASCII character encodings.
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>
Default: on If set (default), Squid will include a Via header in requests and replies as required by RFC2616.
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.
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).
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).
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.
Default: off If you want to enable the ICAP module support, set this to on.
Default: off Set this to 'on' if you want to enable the ICAP preview feature in Squid.
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.
Default: 60 The default TTL value for ICAP OPTIONS responses that don't have an Options-TTL header.
Default: on Whether or not Squid should use persistent connections to an ICAP server.
Default: off This adds the header "X-Client-IP" to ICAP requests.
Default: off This adds the header "X-Client-Username" to ICAP requests if proxy access is authentified.
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
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
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
New options:
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'.
New options:
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
New options:
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.
Removed options:
carp-load-factor
COSS stripe file:
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.
Takes an optional log format:
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.
New alias: 'url_rewrite_program'
New alias: 'url_rewrite_children'
New alias: 'url_rewrite_host_header'
New option for basic scheme:
"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
Removed NTLM options:
"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
New NTLM option:
"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.
New options:
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
New format specifications:
%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
New keywords:
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.
Removed option:
protocol=3.0 Use URL-escaped strings instead of quoting
New options:
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.
New default:
Default: 5 minutes (Old default: 1 minute)
New types:
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.
Removed types:
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,}
New default:
Default: on (Old default: off)
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).
Replaced by the defaultsite= or vport=0 (in case of virtual) http_port options
Replaced by vport http(s)_port option
Replaced by cache_peer originserver based request forwarding making this option obsolete.
Obsolete, no longer needed.
This has been replaced by the vhost http(s)_port option
This has been replaced by the disable-pmtu-discovery=.. http_port option
This has been replaced by request_header_access and reply_header_access