1 <!doctype linuxdoc system>
3 <title>Squid 3.1.23 release notes</title>
4 <author>Squid Developers</author>
7 This document contains the release notes for version 3.1 of Squid.
8 Squid is a WWW Cache application developed by the National Laboratory
9 for Applied Network Research and members of the Web Caching community.
16 The Squid Team are pleased to announce the release of Squid-3.1.23
18 This new release is available for download from <url url="http://www.squid-cache.org/Versions/v3/3.1/"> or the <url url="http://www.squid-cache.org/Download/http-mirrors.html" name="mirrors">.
20 A large number of the show-stopper bugs have been fixed along with general improvements to the ICAP support.
21 While this release is not fully bug-free we believe it is ready for use in production on many systems.
23 We welcome feedback and bug reports. If you find a new bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting"> for how to submit a report with a stack trace and other required details. Additional information is also very welcome on other open bugs.
27 Although this release is deemed good enough for use in many setups, please note the existence of
28 <url url="http://bugs.squid-cache.org/buglist.cgi?query_format=advanced&target_milestone=3.1&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&cmdtype=doit&order=bugs.bug_severity" name="open bugs against Squid-3.1">.
30 <p>Some issues to note as currently known in this release which are not able to be fixed in the 3.1 series are:
33 <item>The lack of some features available in Squid-2.x series. See the regression sections below for full details.
34 <item>eCAP library version 0.2.0 and later are not supported. See eCAP section below for details.
35 <item>CVE-2009-0801 : NAT interception vulnerability to malicious clients. This is fixed in 3.2 series.
36 Some attempts have been made to port for 3.1, but the unreliability of NAT handling in 3.1 makes this unsafe.
39 <p>Currently known issues which only depends on available developer time and may still be resolved in a future 3.1 release are:
42 <item>Windows support is still largely missing.
43 <item>AIX support for building with the IBM compiler is broken.
44 <item>OpenSSL 1.0.0 support is incomplete.
48 <sect1>Changes since earlier releases of Squid-3.1
50 The 3.1 change history can be <url url="http://www.squid-cache.org/Versions/v3/3.1/changesets/" name="viewed here">.
52 <sect>Major new features since Squid-3.0
54 Squid 3.1 represents a new feature release above 3.0.
56 The most important of these new features are:
59 <item>New Version Numbering System
60 <item>Minimal squid.conf improvements
61 <item>Native IPv6 Support
62 <item>Error Page Localization
63 <item>Connection Pinning (for NTLM Auth Passthrough)
64 <item>Quality of Service (QoS) Flow support
65 <item>SSL Bump (for HTTPS Filtering and Adaptation)
66 <item>eCAP Adaptation Module support
67 <item>ICAP Bypass and Retry enhancements
68 <item>ICY streaming protocol support
69 <item>Dynamic SSL Certificate Generation (3.1.13 and later)
72 Most user-facing changes are reflected in squid.conf (see below).
74 <sect1>New Version Numbering System
76 <p>Begining with 3.1 the Squid Developers are using a new release numbering system.
78 <p>We have decided, based on input from interested users to drop the Squid-2 terminology of
79 (DEVEL, PRE, RC, and STABLE) from the release package names.
80 These are replaced with a simpler 3-tier system based around the natural code development cycle.
82 <p>Daily generated snapshots of all current versions are provided as testing (old DEVEL) and bug-fix releases.
83 These are numbered from their last release with a date appended.
84 Snapshots generated from 3.HEAD continue to be highly volatile.
86 <p>Regular feature releases from Squid-3 will be branched out as sub-versions. Such as this Squid-3.1.
88 <p>All this is previous policy you should be accustomed to. Now we get to the new numbering change.
90 <p>Initial branch packages will be generated with a 3.X.0.Z version as beta testing packages.
91 Packages and Snapshots generated with these 3-dot numbers are expected to be relatively stable regarding feature behaviors.
92 Suitable for testing, but without any guarantees under production loads. This replaces both the old PRE and RC packages.
94 <p>If a large number of bugs are found several *.0.Z packages may be attempted before any is fully frozen for production use.
95 To be frozen as stable the code must be compiling well and have passed a period of 14 days with no new bugs reported against
96 the new code added in that release.
98 <p>When one of these Squid-3.X.0.Z packages passes those criteria a 3.X.Y numbered release will be made.
100 <p>We can only hope enough testing has been done to consider these ready for production use.
101 As always we are fully dependent on people testing the previous packages and reporting all bugs.
103 <p>In support of all this are several squid-dev process changes which have been worked out over the last year.
106 <item>We no longer accept new features into branches.
107 Those are reserved for the next feature release.
108 The cycle for major releases is hoped to be fast enough to suit some peoples needs for new features
109 and others need for stability in the branched releases.
111 <item>We now audit and vote on all feature and major code additions.
112 Requiring at least two sets of developer eyes on any new features before they are committed to 3.HEAD.
113 Vastly reducing the number of bugs in all code.
115 <item>We have implemented and continue to add more testing infrastructure.
119 <sect1>Minimal squid.conf improvements
121 <p>squid.conf has undergone a facelift.
123 <p>Don't worry, few operational changes have been made.
124 Older configs from Squid 2.x and 3.0 are still expected to run in 3.1 with only the usual minor
125 changes seen between major release. Details on those are listed below.
127 <p>New users will be relieved to see a very short squid.conf on clean installs.
128 Many of the options have reasonable defaults but had previously needed them explicitly configured!
129 These are now proper built-in defaults and no longer need to be in squid.conf unless changed.
131 <p>All of the option documentation has been offloaded to another file <em>squid.conf.documented</em> which
132 contains a fully documented set of available options previously cluttering up squid.conf itself.
134 <p>Package maintainers are provided with a second file squid.conf.default which as always contains the default
135 config options provided on a clean install.
137 <p>We are also providing online copies of configuration documentation.
138 Updated live to match the latest release of each Squid series, and a combined global version.
139 This is available on <url url="http://www.squid-cache.org/Doc/config/" name="the Squid website">
142 <sect1>Internet Protocol version 6 (IPv6)
144 <p>Squid 3.1 supports IPv6.
145 Details in <url url="http://wiki.squid-cache.org/Features/IPv6" name="The Squid wiki">
147 <sect2>New Features for IPv6
149 <p>Squid handles localhost values seperately. For the purpose of ACLs and also external
150 connections ::1 is considered a seperate IP from 127.0.0.1. This means all ACL which
151 define behaviour for localhost may need ::1/128 included.
153 <p>Pinger has been upgraded to perform both ICMP and ICMPv6 as required.
154 As a result of this and due to a change in the binary protocol format between them,
155 new builds of Squid are no longer backwards-compatible with old pinger binaries.
156 You will need to perform "make install-pinger" again after installing Squid.
158 <p>Peer and Client SNMP tables have been altered to handle IPv6 addresses.
159 As a side effect of this the long-missing fix to show seperate named peers on one IP
160 has been integrated. Making the SNMP peer table now produce correct output.
161 The table structure change is identical for both IPv4-only and Dual modes but with
162 IPv4-only simply not including any IPv6 entries. This means any third-party SNMP
163 software which hard coded the MIB paths needs to be upgraded for this Squid release.
164 Details can be found in the wiki <url url="http://wiki.squid-cache.org/Features/Snmp#Squid_OIDs" name="SNMP feature page">.
166 <sect2>Limitations of IPv6 Support
168 <p>In this release there is incomplete split-stack support. This means that OS which do not provide
169 IP stacks based on the KAME stack with Hybrid extensions to do IPv4-mapping cannot use full IPv6
170 with Squid. From 3.1.6 the automatic capability detection will enable these abilities:
172 <item>open both IPv4 and IPv6 versions of http_port for client connections where applicable.
173 <item>perform DNS to both IPv4 and IPv6 DNS servers.
174 <item>permit IPv6-only snmp_incoming_address and snmp_outgoing_address to be configured.
175 <item>permit IPv6 server connection provided tcp_outgoing_address has been configured (see below).
177 <p><em>NOTE:</em> ICAP, SNMP, ICP and HTCP are not yet opening double ports so they will only run as IPv4-only or IPv6-only.
179 <p>Specify a specific tcp_outgoing_address and the clients who match its ACL are limited
180 to the IPv4 or IPv6 network that address belongs to. They are not permitted over the
181 IPv4-IPv6 boundary. Some ACL voodoo can however be applied to explicitly route the
182 IPv6/IPv4 bound traffic (DIRECT access) out an appropriate interface.
183 See the squid.conf documentation for further details.
185 <p>WCCP is not available (neither version 1 or 2).
186 It remains built into Squid for use with IPv4 traffic but IPv6 cannot use it.
188 <p>Pseudo-Transparent Interception is done via NAT at the OS level and is not available in IPv6.
189 Squid will ensure that any port set with transparent or intercept options be an IPv4-only
190 listening address. Wildcard can still be used but will not open as an IPv6.
191 To ensure that Squid can accept IPv6 traffic on its default port, an alternative should
192 be chosen to handle transparently intercepted traffic.
195 http_port 8080 intercept
198 <p>Real transparent Interception (TPROXY) may be able to perform IPv6 interception.
199 However this currently still needs patching of kernels older than 2.6.37.
200 Squid will attempt to discover support on startup and may permit or deny IPv6 wildcard for
201 tproxy flagged ports depending on your system.
203 <p>The bundled NTLM Auth helper is IPv4-native between itself and the NTLM server.
204 A new one will be needed for IPv6 traffic between the helper and server.
206 <p>The bundled RADIUS Auth helper is IPv4-native, both in traffic between and data storage
207 with the RADIUS server. A new helper will be needed for IPv6 RADIUS protocol.
210 <sect1>Error Page Localization
212 <p>Details in <url url="http://wiki.squid-cache.org/Translations" name="The Squid wiki">
216 <p>The error pages presented by Squid may now be localized per-request to match the visitors local preferred language.
218 <p>The error_directory option in squid.conf needs to be removed.
220 <p>For best coverage of languages, using the latest language pack of error files is recommended.
221 Updates can be downloaded from <url url="http://www.squid-cache.org/Versions/langpack/" name="www.squid-cache.org/Versions/langpack/">
223 <p>The Squid developers are interested in making Squid available in a wide variety of languages.
224 Contribution of new languages is encouraged.
226 <sect2>CSS Stylesheet controls
228 <p>To further enhance the visitor experience all new translations have embeded CSS hooks for scalable per-site localization of the display.
230 <p>CSS display is controlled by updating the errorpage.css file installed into Squids configuration directory
231 or the <em>err_page_stylesheet</em> option in squid.conf.
233 <p>Custom error pages can also embed the CSS content by adding the <em>%l</em> tag to their headers.
236 <sect1>Connection Pinning (for NTLM Auth Passthrough)
238 <p>Details in <url url="http://wiki.squid-cache.org/Features/ConnPin" name="The Squid wiki">
240 <p>Squid 3.1 includes the much asked for Connection Pinning feature from Squid 2.6.
242 <p>This feature is often called 'NTLM Passthru' since it is a giant workaround which permits Web servers to use
243 Microsoft NTLM Authentication instead of HTTP standard authentication through a web proxy.
246 <sect1>Quality of Service (QoS) Flow support
248 <p>Details in <url url="http://wiki.squid-cache.org/Features/QualityOfService" name="The Squid wiki">
250 <p>Zero Penalty Hit created a patch to set QoS markers on outgoing traffic.
253 <item>Allows you to select a TOS/Diffserv value to mark local hits.
254 <item>Allows you to select a TOS/Diffserv value to mark peer hits.
255 <item>Allows you to selectively mark only sibling or parent requests
256 <item>Allows any HTTP response towards clients to have the TOS value of the response coming from
257 the remote server preserved.
258 For this to work correctly, you will need to patch your linux kernel with the TOS preserving ZPH patch.
259 The kernel patch can be downloaded from <url url="http://zph.bratcheda.org" name="http://zph.bratcheda.org">
260 <item>Allows you to mask certain bits in the TOS received from the remote server,
261 before copying the value to the TOS send towards clients.
264 <sect2>Squid Configuration
265 <p>Squid 3.1 needs to be configured with <em>--enable-zph-qos</em> for the ZPH QoS controls to be available.
267 <p>The configuration options for Squid 2.7 and 3.1 are based on different ZPH patches.
268 The two releases configuration differs and only the TOS mode settings are directly translatable.
271 <item><em>qos_flows local-hit=0xff</em> Responses found as a HIT in the local cache
272 <item><em>qos_flows sibling-hit=0xff</em> Responses found as a HIT in a sibling peer
273 <item><em>qos_flows parent-hit=0xff</em> Responses found as a HIT in a parent peer
276 <p>The lines above are separated for documentation. qos_flows may be configured with all options on one line, or separated as shown.
277 Also options may be repeated as many times as desired. Only the final configured value for any option will be used.
279 <p>The legacy <em>Option</em> and <em>Priority</em> modes available in Squid-2.7 are no longer supported.
282 <sect1>SSL Bump (for HTTPS Filtering and Adaptation)
284 <p>Details in <url url="http://wiki.squid-cache.org/Features/SslBump" name="The Squid wiki">
286 <p>Squid-in-the-middle decryption and encryption of CONNECT tunneled SSL traffic,
287 using configurable client- and server-side certificates.
288 While decrypted, the traffic can be inspected using ICAP.
290 <p>Squid 3.1 releases limit SSL Bump to CONNECT requests and requires that clients are
291 configured to explicitly use the proxy in their browser settings or via WPAD/PAC
292 configuration. Use of interception for port 443 is not officially supported, despite
293 being known to work under certain limited networking circumstances.
295 <sect1> Dynamic SSL Certificate Generation
296 <p> SslBump users know how many certificate warnings a single complex site
297 (using dedicated image, style, and/or advertisement servers for embedded content)
298 can generate. The warnings are legitimate and are caused by Squid-provided site
299 certificate. Two things may be wrong with that certificate:
301 <item> Squid certificate is not signed by a trusted authority.
302 <item> Squid certificate name does not match the site domain name.
304 Squid can do nothing about (A), but in most targeted environments, users will
305 trust the "man in the middle" authority and install the corresponding root
308 <p>To avoid mismatch (B), the DynamicSslCert feature concentrates on generating
309 site certificates that match the requested site domain name. Please note that
310 the browser site name check does not really add much security in an SslBump
311 environment where the user already trusts the "man in the middle". The check
312 only adds warnings and creates page rendering problems in browsers that try to
313 reduce the number of warnings by blocking some embedded content.
315 <sect1>eCAP Adaptation Module support
317 <p>Details in <url url="http://wiki.squid-cache.org/Features/eCAP" name="The Squid wiki">
319 <p>eCAP provides a way to integrate CAP modules directly into Squid without the need for
320 a c-icap server wrapper. This enables faster processing.
322 <p>Currently known and available eCAP modules are listed in the wiki feature page on eCAP.
324 <p><em>Known Issue:</em> libecap version 0.0.3 (exactly) is required to build this series
325 of Squid. Other versions of libecap contain significant interface differences.
328 <sect1>ICAP Bypass and Retry enhancements
330 <p>Details in <url url="http://wiki.squid-cache.org/Features/ICAP" name="The Squid wiki">
332 <p>ICAP is now extended with full bypass and dynamic chain routing to handle multiple
335 <sect2>ICAP Adaptation Service Sets and Chains
337 <p>An adaptation service set contains similar, interchangeable services. No more
338 than one service is successfully applied. If one service is down or fails,
339 Squid can use another service. Think "hot standby" or "spare" ICAP servers.
341 <p>Sets may seem similar to the existing "service bypass" feature, but they allow
342 the failed adaptation to be retried and succeed if a replacement service is
343 available. The services in a set may be all optional or all essential,
344 depending on whether ignoring the entire set is acceptable. The mixture of
345 optional and essential services in a set is supported, but yields results that
346 may be difficult for a human to anticipate or interpret. Squid warns when it
347 detects such a mixture.
349 <p>When performing adaptations with a set, failures at a service (optional or
350 essential, does not matter) are retried with a different service if possible.
351 If there are no more replacement services left to try, the failure is treated
352 depending on whether the last service tried was optional or essential: Squid
353 either tries to ignore the failure and proceed or terminates the master
356 <p>An adaptation chain is a list of different services applied one after another,
357 forming an adaptation pipeline. Services in a chain may be optional or
358 essential. When performing adaptations, failures at an optional service are
359 ignored as if the service did not exist in the chain.
361 <p>Request satisfaction terminates the adaptation chain.
363 <p>When forming a set or chain for a given transaction, optional down services are ignored as if they did not exist.
365 <p>ICAP and eCAP services can be mixed and matched in an adaptation set or chain.
367 <sect2>Dynamically form adaptation chains based on the ICAP X-Next-Services header.
369 <p>If an ICAP service with the routing=1 option in squid.conf returns an ICAP
370 X-Next-Services response header during a successful REQMOD or RESPMOD
371 transaction, Squid abandons the original adaptation plan and forms a new
372 adaptation chain consisting of services identified in the X-Next-Services
373 header value (using a comma-separated list of adaptation service names from
374 squid.conf). The dynamically created chain is destroyed once the new plan is
375 completed or replaced.
377 <p>This feature is useful when a custom adaptation service knows which other
378 services are applicable to the message being adapted.
380 <p>Limit adaptation iterations to adaptation_service_iteration_limit to protect
381 Squid from infinite adaptation loops caused by ICAP services constantly
382 including themselves in the dynamic adaptation chain they request. When the
383 limit is exceeded, the master transaction fails. The default limit of 16
384 should be large enough to not require an explicit configuration in most
385 environments yet may be small enough to limit side-effects of loops.
388 <sect1>ICY streaming protocol support
389 <p>Squid-3.1 adds native support for streaming protocol ICY.
390 Also commonly known as SHOUTcast multimedia streams.
392 <p>This protocol uses port 80 and violates RFC 2616 by using an HTTP/1.1 compliant request and non-HTTP reply
393 to start the stream transaction. If the reply is handled according to HTTP/1.1 RFC-compliance requirements
394 the audio stream becomes jerky and contains regular 'popping' sounds.
396 <p>Squid now processes the ICY replies natively according to the ICY requirements, not HTTP/1.1 requirements.
397 The streamed data is not cacheable. All processing and access controls may be applied the same as for HTTP.
399 <sect2>squid.conf change
400 <p>Squid-2 contained a hack using the <em>update_http0.9</em> squid.conf option to work around the
401 unusual replies. This option is now obsolete.
403 <p>The <em>proto</em> ACL type only matches <em>ICY</em> once the reply has been received, before that the processing
404 is only aware on an HTTP request. So the ACL will match <em>HTTP</em> in <em>http_access</em> and <em>ICY</em> in
405 <em>http_reply_access</em>.
408 <sect>Changes to squid.conf since Squid-3.0
410 There have been changes to Squid's configuration file since Squid-3.0.
412 This section gives a thorough account of those changes in three categories:
415 <item><ref id="newtags" name="New tags">
416 <item><ref id="modifiedtags" name="Changes to existing tags">
417 <item><ref id="removedtags" name="Removed tags">
422 <sect1>New tags<label id="newtags">
425 <tag>acl_uses_indirect_client</tag>
426 <p>Whether to use any result found by follow_x_forwarded_for in further ACL processing.
429 Controls whether the indirect client address
430 (see follow_x_forwarded_for) is used instead of the
431 direct client address in acl matching.
434 <tag>adaptation_access</tag>
435 <p>Sends an HTTP transaction to an ICAP or eCAP adaptation service.
437 adaptation_access service_name allow|deny [!]aclname...
438 adaptation_access set_name allow|deny [!]aclname...
440 At each supported vectoring point, the adaptation_access
441 statements are processed in the order they appear in this
442 configuration file. Statements pointing to the following services
443 are ignored (i.e., skipped without checking their ACL):
445 - services serving different vectoring points
446 - "broken-but-bypassable" services
447 - "up" services configured to ignore such transactions
448 (e.g., based on the ICAP Transfer-Ignore header).
450 When a set_name is used, all services in the set are checked
451 using the same rules, to find the first applicable one. See
452 adaptation_service_set for details.
454 If an access list is checked and there is a match, the
455 processing stops: For an "allow" rule, the corresponding
456 adaptation service is used for the transaction. For a "deny"
457 rule, no adaptation service is activated.
459 It is currently not possible to apply more than one adaptation
460 service at the same vectoring point to the same HTTP transaction.
463 <tag>adaptation_masterx_shared_names</tag>
465 For each master transaction (i.e., the HTTP request and response
466 sequence, including all related ICAP and eCAP exchanges), Squid
467 maintains a table of metadata. The table entries are (name, value)
468 pairs shared among eCAP and ICAP exchanges. The table is destroyed
469 with the master transaction.
471 This option specifies the table entry names that Squid must accept
472 from and forward to the adaptation transactions.
474 An ICAP REQMOD or RESPMOD transaction may set an entry in the
475 shared table by returning an ICAP header field with a name
476 specified in adaptation_masterx_shared_names. Squid will store
477 and forward that ICAP header field to subsequent ICAP
478 transactions within the same master transaction scope.
480 Only one shared entry name is supported at this time.
483 <tag>adaptation_service_chain</tag>
485 Configures a list of complementary services that will be applied
486 one-by-one, forming an adaptation chain or pipeline. This is useful
487 when Squid must perform different adaptations on the same message.
489 adaptation_service_chain chain_name service_name1 svc_name2 ...
491 The named services are used in the chain declaration order. The first
492 applicable adaptation service from the chain is used first. The next
493 applicable service is applied to the successful adaptation results of
494 the previous service in the chain.
496 When adaptation starts, broken services are ignored as if they were
497 not a part of the chain. A broken service is a down optional service.
499 Request satisfaction terminates the adaptation chain because Squid
500 does not currently allow declaration of RESPMOD services at the
501 "reqmod_precache" vectoring point (see icap_service or ecap_service).
503 The services in a chain must be attached to the same vectoring point
504 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
506 A chain may contain a mix of optional and essential services. If an
507 essential adaptation fails (or the failure cannot be bypassed for
508 other reasons), the master transaction fails. Otherwise, the failure
509 is bypassed as if the failed adaptation service was not in the chain.
512 <tag>adaptation_service_iteration_limit</tag>
514 Limits the number of iterations allowed when applying adaptation
515 services to a message. If your longest adaptation set or chain
516 may have more than 16 services, increase the limit beyond its
517 default value of 16. If detecting infinite iteration loops sooner
518 is critical, make the iteration limit match the actual number
519 of services in your longest adaptation set or chain.
521 Infinite adaptation loops are most likely with routing services.
524 <tag>adaptation_service_set</tag>
526 Configures an ordered set of similar, redundant services. This is
527 useful when hot standby or backup adaptation servers are available.
529 adaptation_service_set set_name service_name1 service_name2 ...
531 The named services are used in the set declaration order. The first
532 applicable adaptation service from the set is used first. The next
533 applicable service is tried if and only if the transaction with the
534 previous service fails and the message waiting to be adapted is still
537 When adaptation starts, broken services are ignored as if they were
538 not a part of the set. A broken service is a down optional service.
540 The services in a set must be attached to the same vectoring point
541 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
543 If all services in a set are optional then adaptation failures are
544 bypassable. If all services in the set are essential, then a
545 transaction failure with one service may still be retried using
546 another service from the set, but when all services fail, the master
547 transaction fails as well.
549 A set may contain a mix of optional and essential services, but that
550 is likely to lead to surprising results because broken services become
551 ignored (see above), making previously bypassable failures fatal.
552 Technically, it is the bypassability of the last failed service that
556 <tag>adapted_http_access</tag>
557 <p>New name for <em>http_access2</em>. This form includes access control
558 of ICAP and eCAP adaptations as well as the URL-rewriter alterations.
560 <tag>chunked_request_body_max_size</tag>
561 <p>New option to enable handing of broken HTTP/1.1 clients sending chunk requests.
563 A broken or confused HTTP/1.1 client may send a chunked HTTP
564 request to Squid. Squid does not have full support for that
565 feature yet. To cope with such requests, Squid buffers the
566 entire request and then dechunks request body to create a
567 plain HTTP/1.0 request with a known content length. The plain
568 request is then used by the rest of Squid code as usual.
570 The option value specifies the maximum size of the buffer used
571 to hold the request before the conversion. If the chunked
572 request size exceeds the specified limit, the conversion
573 fails, and the client receives an "unsupported request" error,
574 as if dechunking was disabled.
576 Dechunking is enabled by default. To disable conversion of
577 chunked requests, set the maximum to zero.
579 Request dechunking feature and this option in particular are a
580 temporary hack. When chunking requests and responses are fully
581 supported, there will be no need to buffer a chunked request.
584 <tag>client_request_buffer_max_size</tag>
585 <p>New directive added with squid-3.1.10 to set limits on the amount of buffer space allocated
586 for receiving upload and request data from clients.
588 <tag>delay_pool_uses_indirect_client</tag>
589 <p>Whether to use any result found by follow_x_forwarded_for in delay_pool assignment.
592 Controls whether the indirect client address
593 (see follow_x_forwarded_for) is used instead of the
594 direct client address in delay pools.
597 <tag>dns_v4_fallback</tag>
598 <p>New option to prevent Squid from always looking up IPv4 regardless of whether IPv6 addresses are found.
599 Squid will follow a policy of prefering IPv6 links, keeping the IPv4 only as a safety net behind IPv6.
601 Standard practice with DNS is to lookup either A or AAAA records
602 and use the results if it succeeds. Only looking up the other if
603 the first attempt fails or otherwise produces no results.
605 That policy however will cause Squid to produce error pages for some
606 servers that advertise AAAA but are unreachable over IPv6.
608 If this is ON Squid will always lookup both AAAA and A, using both.
609 If this is OFF Squid will lookup AAAA and only try A if none found.
611 WARNING: There are some possibly unwanted side-effects with this on:
612 *) Doubles the load placed by Squid on the DNS network.
613 *) May negatively impact connection delay times.
616 <tag>dns_v4_first</tag>
617 <p>Added in 3.1.16. Controls whether IPv4 or IPv6 connection is
618 attempted first when contacting servers and peers.
620 <tag>ecap_enable</tag>
621 <p>Controls whether eCAP support is enabled. Default: OFF
623 <tag>ecap_service</tag>
624 <p>Defines a single eCAP service
626 ecap_service servicename vectoring_point bypass service_url
628 vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
629 This specifies at which point of transaction processing the
630 eCAP service should be activated. *_postcache vectoring points
631 are not yet supported.
634 If set to 1, the eCAP service is treated as optional. If the
635 service cannot be reached or malfunctions, Squid will try to
636 ignore any errors and process the message as if the service
637 was not enabled. No all eCAP errors can be bypassed.
638 If set to 0, the eCAP service is treated as essential and all
639 eCAP errors will result in an error page returned to the
642 service_url = ecap://vendor/service_name?custom&cgi=style&parameters=optional
645 ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block
646 ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg
649 <tag>err_page_stylesheet</tag>
650 <p>New option to configure location for CSS stylesheet controlling error page display.
652 <tag>error_default_language</tag>
653 <p>New option to replace the old configure option --enable-default-err-language
654 New translations can be downloaded from http://www.squid-cache.org/Versions/langpack/
656 Set the default language which Squid will send error pages in
657 if no existing translation matches the clients language
660 If unset (default) generic English will be used.
663 <tag>error_log_languages</tag>
666 Log to cache.log what languages users are attempting to
667 auto-negotiate for translations.
669 Successful negotiations are not logged. Only failures
670 have meaning to indicate that Squid may need an upgrade
671 of its error page translations.
674 <tag>follow_x_forwarded_for</tag>
675 <p>Enable processing of the X-Forwarded-for header for various administration tasks.
677 Allowing or Denying the X-Forwarded-For header to be followed to
678 find the original source of a request.
680 Requests may pass through a chain of several other proxies
681 before reaching us. The X-Forwarded-For header will contain a
682 comma-separated list of the IP addresses in the chain, with the
683 rightmost address being the most recent.
685 If a request reaches us from a source that is allowed by this
686 configuration item, then we consult the X-Forwarded-For header
687 to see where that host received the request from. If the
688 X-Forwarded-For header contains multiple addresses, and if
689 acl_uses_indirect_client is on, then we continue backtracking
690 until we reach an address for which we are not allowed to
691 follow the X-Forwarded-For header, or until we reach the first
692 address in the list. (If acl_uses_indirect_client is off, then
693 it's impossible to backtrack through more than one level of
694 X-Forwarded-For addresses.)
696 The end result of this process is an IP address that we will
697 refer to as the indirect client address. This address may
698 be treated as the client address for access control, delay
699 pools and logging, depending on the acl_uses_indirect_client,
700 delay_pool_uses_indirect_client and log_uses_indirect_client
703 SECURITY CONSIDERATIONS:
704 Any host for which we follow the X-Forwarded-For header
705 can place incorrect information in the header, and Squid
706 will use the incorrect information as if it were the
707 source address of the request. This may enable remote
708 hosts to bypass any access control restrictions that are
709 based on the client's source addresses.
713 acl localhost src 127.0.0.1
714 acl my_other_proxy srcdomain .proxy.example.com
715 follow_x_forwarded_for allow localhost
716 follow_x_forwarded_for allow my_other_proxy
720 <p>New directive added with squid-3.1.11 to control whether Squid uses EPRT extension
721 for efficient NAT handling and IPv6 protocol support in FTP.
724 <p>New directive to control whether Squid uses EPSV extension for
725 efficient NAT handling and IPv6 protocol support in FTP.
727 <tag>ftp_epsv_all</tag>
728 <p>New directive to control whether Squid uses "EPSV ALL" extension for
729 efficient NAT handling and IPv6 protocol support in FTP.
731 <tag>forward_max_tries</tag>
732 <p>Controls how many different forward paths Squid will try
733 before giving up. Default: 10
736 <p>New option to write ICAP log files record ICAP transaction summaries, one line per
737 transaction. Similar to access.log.
739 The icap_log option format is:
740 icap_log <filepath> [<logformat name> [acl acl ...]]
741 icap_log none [acl acl ...]]
743 Please see access_log option documentation for details. The two
744 kinds of logs share the overall configuration approach and many
747 ICAP processing of a single HTTP message or transaction may
748 require multiple ICAP transactions. In such cases, multiple
749 ICAP transaction log lines will correspond to a single access
752 ICAP log uses logformat codes that make sense for an ICAP
753 transaction. Header-related codes are applied to the HTTP header
754 embedded in an ICAP server response, with the following caveats:
755 For REQMOD, there is no HTTP response header unless the ICAP
756 server performed request satisfaction. For RESPMOD, the HTTP
757 request header is the header sent to the ICAP server. For
758 OPTIONS, there are no HTTP headers.
760 The following format codes are also available for ICAP logs:
762 icap::<A ICAP server IP address. Similar to <A.
764 icap::<service_name ICAP service name from the icap_service
765 option in Squid configuration file.
767 icap::ru ICAP Request-URI. Similar to ru.
769 icap::rm ICAP request method (REQMOD, RESPMOD, or
770 OPTIONS). Similar to existing rm.
772 icap::>st Bytes sent to the ICAP server (TCP payload
773 only; i.e., what Squid writes to the socket).
775 icap::<st Bytes received from the ICAP server (TCP
776 payload only; i.e., what Squid reads from
779 icap::tr Transaction response time (in
780 milliseconds). The timer starts when
781 the ICAP transaction is created and
782 stops when the transaction is completed.
785 icap::tio Transaction I/O time (in milliseconds). The
786 timer starts when the first ICAP request
787 byte is scheduled for sending. The timers
788 stops when the last byte of the ICAP response
791 icap::to Transaction outcome: ICAP_ERR* for all
792 transaction errors, ICAP_OPT for OPTION
793 transactions, ICAP_ECHO for 204
794 responses, ICAP_MOD for message
795 modification, and ICAP_SAT for request
796 satisfaction. Similar to Ss.
798 icap::Hs ICAP response status code. Similar to Hs.
800 icap::>h ICAP request header(s). Similar to >h.
802 icap::<h ICAP response header(s). Similar to <h.
804 The default ICAP log format, which can be used without an explicit
805 definition, is called icap_squid:
807 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
810 <tag>icap_retry</tag>
811 <p>New option to determine which retriable ICAP transactions are
814 Transactions that received a complete ICAP response
815 and did not have to consume or produce HTTP bodies to receive
816 that response are usually retriable.
818 icap_retry allow|deny [!]aclname ...
820 Squid automatically retries some ICAP I/O timeouts and errors
821 due to persistent connection race conditions.
824 <tag>icap_retry_limit</tag>
826 Limits the number of retries allowed. When set to zero (default),
827 no retries are allowed.
829 Communication errors due to persistent connection race
830 conditions are unavoidable, automatically retried, and do not
831 count against this limit.
834 <tag>ignore_expect_100</tag>
835 <p>Ported from 2.7. Requires --enable-http-violations
836 Prevents 417 errors being sent to broken HTTP/1.1 non-compliant clients.
839 <p>New option to import entire secondary configuration files into squid.conf.
841 Squid will follow the files immediately and insert all their content
842 as if it was at that position in squid.conf. As per squid.conf some
843 options are order-specific within the config as a whole.
845 A few layers of include are allowed, but too many are confusing and
846 Squid will enforce an include depth of 16 files.
849 include /path/to/file1 /path/to/file2
852 <tag>loadable_modules</tag>
853 <p>Instructs Squid to load the specified dynamic module(s) or activate
857 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
860 <tag>log_icap aclname [aclname ...]</tag>
862 This options allows you to control which requests get logged
863 to icap.log. See the icap_log directive for ICAP log details.
866 <tag>log_uses_indirect_client</tag>
867 <p>Whether to use any result found by follow_x_forwarded_for in access.log.
870 Controls whether the indirect client address
871 (see follow_x_forwarded_for) is used instead of the
872 direct client address in the access log.
875 <tag>max_filedescriptors</tag>
878 <tag>netdb_filename</tag>
880 A filename where Squid stores it's netdb state between restarts.
881 To disable, enter "none".
884 <tag>pinger_enable</tag>
885 <p>New option to enable/disable the ICMP pinger helper with a reconfigure instead of a full rebuild.
887 Control whether the pinger is active at run-time.
888 Enables turning ICMP pinger on and off with a simple squid -k reconfigure.
889 default is off when --enable-icmp is compiled in.
892 <tag>qos_flows local-hit= sibling-hit= parent-hit=</tag>
894 Allows you to select a TOS/DSCP value to mark outgoing
895 connections with, based on where the reply was sourced.
897 TOS values really only have local significance - so you should
898 know what you're specifying. For more information, see RFC2474,
899 RFC2475, and RFC3260.
901 The TOS/DSCP byte must be exactly that - octet value 0x00-0xFF.
902 Note that in practice often only multiples of 4 is usable as the
903 two rightmost bits have been redefined for use by ECN (RFC 3168
906 Note that in practice often only values up to 0xFC are usable,
907 and only in multiple of 4, as the two rightmost bits have been
908 redefined for use by ECN (RFC3168).
910 This setting is configured by setting the source TOS values:
912 local-hit=0xFF Value to mark local cache hits.
914 sibling-hit=0xFF Value to mark hits from sibling peers.
916 parent-hit=0xFF Value to mark hits from parent peers.
919 NOTE: 'miss' preserve feature is only possible on Linux at this time.
921 For the following to work correctly, you will need to patch your
922 linux kernel with the TOS preserving ZPH patch.
923 The kernel patch can be downloaded from http://zph.bratcheda.org
925 disable-preserve-miss
926 If set, any HTTP response towards clients will
927 have the TOS value of the response comming from the
928 remote server masked with the value of miss-mask.
930 Allows you to mask certain bits in the TOS received from the
931 remote server, before copying the value to the TOS sent
933 Default: 0xFF (TOS from server is not changed).
936 <tag>reply_header_replace</tag>
937 <p>This option allows you to change the contents of reply headers.
939 In Squid 2 header_replace (now deprecated) worked for both requests
940 and replies, while in Squid 3 it only did respect request headers.
941 This option brings back the functionality to replace the contents of
942 reply headers. Consult the documentation for usage details.
945 <tag>request_header_replace</tag>
946 <p>This option allows you to change the contents of request headers.
948 To be consistent with the naming changes of header_access in Squid 3
949 (header_access has been split into two options request_header_access
950 and reply_header_access), header_replace (now deprecated) is being
951 replaced by request_header_replace.
955 <p>New Access control for which CONNECT requests to an http_port
956 marked with an ssl-bump flag are actually "bumped". Please
957 see the ssl-bump flag of an http_port option for more details
958 about decoding proxied SSL connections.
959 DEFAULT: No requests are bumped.
962 # Example: Bump all requests except those originating from localhost and
963 # those going to webax.com or example.com sites.
965 # acl broken_sites dstdomain .webax.com
966 # acl broken_sites dstdomain .example.com
967 # ssl_bump deny localhost
968 # ssl_bump deny broken_sites
972 <tag>sslcrtd_program</tag>
973 <p>Specify the location and options of the executable for ssl_crtd process.
975 <tag>sslcrtd_children</tag>
976 <p> Configures the number of sslcrtd processes to spawn
978 <tag>sslproxy_cert_error</tag>
979 <p>New Access Control to selectively bypass server certificate validation errors.
980 DEFAULT: None bypassed.
982 For example, the following lines will bypass all validation errors
983 when talking to servers located at 172.16.0.0/16. All other
984 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
986 acl BrokenServersAtTrustedIP dst 172.16.0.0/16
987 sslproxy_cert_error allow BrokenServersAtTrustedIP
988 sslproxy_cert_error deny all
990 This option must use fast ACL expressions only. Expressions that use
991 external lookups or communication result in unpredictable behavior or
994 Without this option, all server certificate validation errors
995 terminate the transaction. Bypassing validation errors is dangerous
996 because an error usually implies that the server cannot be trusted and
997 the connection may be insecure.
1003 <sect1>Changes to existing tags<label id="modifiedtags">
1007 <p>New preset <em>ipv6</em> available in the src and dst ACL matching all of the public IPv6 network space.
1008 <p>New preset <em>ipv4</em> available in the src and dst ACL matching all of IPv4 network space.
1009 <p>New acl type myportname, matching the name of the http_port or https_port where the request was accepted.
1010 <p>New acl type tag, matching the tag= returned from the external_acl_type helper.
1011 <p>New acl type peername, matching against a named cache_peer entry where the request will be attempted first.
1012 NP: peername currently is limited to only match the first peer possible.
1014 acl aclname dst ipv6 # request for IPv6-enabled site
1015 acl aclname src ipv6 # request from IPv6 address
1016 acl aclname dst ipv4 # request for IPv4 site
1017 acl aclname src ipv4 # request from IPv4 address
1018 acl aclname myportname 3128 ... # http(s)_port name
1019 acl aclname peername myPeer ... # cache_peer ... name=myPeer
1020 acl aclname tag value ... # tag= option from external ACL
1023 <tag>auth_param ntlm, basic, digest</tag>
1024 <p>BASIC, DIGEST: New parameter option <em>utf8 on|off</em> to permit helpers to selectively process UTF-8 characters even though
1025 HTTP accepts only ISO-8859-1.</p>
1026 <p>NCSA authenticator updated in 3.1.15 to alert if passwords with more than 8 characters are used with DES encryption method.
1027 <p>NTLM: The helper binary bundled with Squid under the name <em>ntlm_auth</em> has been renamed to accurately reflect
1028 its real behavior and to prevent confusion with the more useful Samba helper using the same name.
1029 <p>Despite being used for NTLM, the helper does not in fact provide true NTLM function. What it does provide is
1030 SMB LanManager authentication through the NTLM interface without the need for a domain controller. Thus the
1031 new name is <em>ntlm_smb_lm_auth</em>.
1032 <p>WARNING: due to the name clash with Samba helper, admin should be careful to only update their squid.conf if the
1033 Squid bundled binary is used and needed. If the Samba helper is in use, the squid.conf should not be altered.
1035 <tag>balance_on_multiple_ip</tag>
1036 <p>The previous default behavour (rotate per-request) of this setting causes failover clashes with IPv6 built-in mechanisms.
1037 It has thus been turned off by default. Making the 'best choice' IP continue in use for any hostname until it encounters a connection failure and failover drops to the next known IP.
1039 Modern IP resolvers in Squid sort lookup results by preferred access.
1040 By default Squid will use these IP in order and only rotates to
1041 the next listed when the most preffered fails.
1043 Some load balancing servers based on round robin DNS have been
1044 found not to preserve user session state across requests
1045 to different IP addresses.
1047 Enabling this directive Squid rotates IP's per request.
1051 <p>Removed the 'QUERY' acl and 'cache deny QUERY' entries.
1052 Replaced by new refresh_pattern instead.
1054 <tag>cache_dir</tag>
1055 <p>Default changed to 256MB in-memory cache.
1056 see cache_mem and maximum_object_size_in_memory for size parameters.
1057 <p>'null' storage type dropped. In-memory cache is always present. Remove all cache_dir options to prevent on-disk caching.
1059 <tag>cache_mem</tag>
1060 <p>Default size increased to 256MB.
1062 <tag>cache_peer htcp-no-clr htcp-no-purge-clr htcp-only-clr htcp-forward-clr connection-auth[=on|off|auto] connect-fail-limit=N multicast-siblings no-tproxy</tag>
1065 use 'htcp-no-clr' to send HTCP to the neighbor but without
1066 sending any CLR requests. This cannot be used with
1069 use 'htcp-no-purge-clr' to send HTCP to the neighbor
1070 including CLRs but only when they do not result from
1073 use 'htcp-only-clr' to send HTCP to the neighbor but ONLY
1074 CLR requests. This cannot be used with htcp-no-clr.
1076 use 'htcp-forward-clr' to forward any HTCP CLR requests
1077 this proxy receives to the peer.
1079 use 'connection-auth=off' to tell Squid that this peer does
1080 not support Microsoft connection oriented authentication,
1081 and any such challenges received from there should be
1082 ignored. Default is 'auto' to automatically determine the
1085 use 'connect-fail-limit=nn' to specify how many times
1086 connecting to a peer must fail before it is marked as
1087 down. Default is 10.
1089 use 'no-tproxy' to specify that requests passed to this peer
1090 are not to have the client IP spoofed. For use to prevent
1091 packet routing issues with a cluster of peers behind WCCPv2.
1093 multicast-siblings ported from 2.7
1096 <tag>cache_store_log</tag>
1097 <p>Default changed to OFF. Matching long-standing developer recommendations.
1099 <tag>debug_options rotate=</tag>
1100 <p>New parameter rotate=N to control number of cache.log rotations independent of other logs.
1102 <tag>deny_info</tag>
1103 <p>Support 307 status for redirecting CONNECT tunnels with HTTPS traffic.
1105 <tag>error_directory</tag>
1106 <p>Now an optional entry in squid.conf. If present it will force all visitors to receive the error pages
1107 contained in the directory it points at. If absent, error page localization will be given a chance.
1109 If you wish to create your own versions of the default
1110 error files to customize them to suit your company COPY
1111 the error/template files to another directory and point
1114 WARNING: This option will disable multi-language support
1115 on error pages if used.
1118 <tag>external_acl_type</tag>
1119 <p>New options 'ipv4' and 'ipv6' are added to set the IPv4/v6 protocol between Squid and its helpers.
1120 Please be aware of some limits to these options. These options only affect the transport protocol used
1121 to send data to and from the helpers. Squid in IPv6-mode may still send %SRC addresses in IPv4 or IPv6
1122 format, so all helpers will need to be checked and converted to cope with such information cleanly.
1124 ipv4 / ipv6 IP protocol used to communicate with this helper.
1125 The default is to auto-detect IPv6 and use it when available.
1127 <p>New header input format specifiers. To seperate Request and Reply headers when both passed back.
1129 %>{Header} HTTP request header
1130 %>{Hdr:member} HTTP request header list member
1131 %>{Hdr:;member} HTTP request header list member using ; as
1132 list separator. ; can be any non-alphanumeric
1135 %<{Header} HTTP reply header
1136 %<{Hdr:member} HTTP reply header list member
1137 %<{Hdr:;member} HTTP reply header list member using ; as
1138 list separator. ; can be any non-alphanumeric
1140 %% The percent symbol (available from 3.1.17)
1143 <tag>forwarded_for</tag>
1144 <p>New setting options. transparent, truncate, delete.
1146 If set to "transparent", Squid will not alter the
1147 X-Forwarded-For header in any way.
1149 If set to "delete", Squid will delete the entire
1150 X-Forwarded-For header.
1152 If set to "truncate", Squid will remove all existing
1153 X-Forwarded-For entries, and place the client IP as the sole entry.
1156 <tag>header_replace</tag>
1157 <p>Deprecated. Use request_header_replace or reply_header_replace instead.
1159 <tag>hierarchy_stoplist</tag>
1160 <p>Default value altered to no content, allowing dynamic websites to be fetched through peers.
1162 <tag>http_port transparent intercept ssl-bump connection-auth[=on|off] ignore-cc</tag>
1163 <p>Option 'transparent' is being deprecated in favour of 'intercept' which more clearly identifies what the option does.
1164 For now option 'tproxy' remains with old behaviour meaning fully-invisible proxy using TPROXY support.</p>
1167 intercept Rename of old 'transparent' option to indicate proper functionality.
1169 allow-direct Allow direct forwarding in accelerator mode. Normally
1170 accelerated requests are denied direct forwarding as if
1171 never_direct was used.
1173 connection-auth[=on|off]
1174 use connection-auth=off to tell Squid to prevent
1175 forwarding Microsoft connection oriented authentication
1176 (NTLM, Negotiate and Kerberos)
1178 keepalive[=idle,interval,timeout]
1179 Enable TCP keepalive probes of idle connections
1180 idle is the initial time before TCP starts probing
1181 the connection, interval how often to probe, and
1182 timeout the time before giving up.
1184 ignore-cc Ignore request Cache-Control headers.
1186 Warning: This option violates HTTP specifications if
1187 used in non-accelerator setups.
1189 ssl-bump Intercept each CONNECT request matching ssl_bump ACL,
1190 establish secure connection with the client and with
1191 the server, decrypt HTTP messages as they pass through
1192 Squid, and treat them as unencrypted HTTP messages,
1193 becoming the man-in-the-middle.
1195 When this option is enabled, additional options become
1196 available to specify SSL-related properties of the
1197 client-side connection: cert, key, version, cipher,
1198 options, clientca, cafile, capath, crlfile, dhparams,
1199 sslflags, and sslcontext. See the https_port directive
1200 for more information on these options.
1202 The ssl_bump option is required to fully enable
1203 the SSL Bump feature.
1206 <tag>https_port intercept ssl-bump connection-auth[=on|off]</tag>
1207 <p>New port options. see http_port.
1209 <tag>icap_service bypass=on|off|1|0 routing=on|off|1|0 ipv6=on|off</tag>
1210 <p>New options 'bypass=', 'routing=' and 'ipv6='.
1213 If set to 'on' or '1', the ICAP service is treated as
1214 optional. If the service cannot be reached or malfunctions,
1215 Squid will try to ignore any errors and process the message as
1216 if the service was not enabled. No all ICAP errors can be
1217 bypassed. If set to 0, the ICAP service is treated as
1218 essential and all ICAP errors will result in an error page
1219 returned to the HTTP client.
1221 Bypass is off by default: services are treated as essential.
1224 If set to 'on' or '1', the ICAP service is allowed to
1225 dynamically change the current message adaptation plan by
1226 returning a chain of services to be used next. The services
1227 are specified using the X-Next-Services ICAP response header
1228 value, formatted as a comma-separated list of service names.
1229 Each named service should be configured in squid.conf and
1230 should have the same method and vectoring point as the current
1231 ICAP transaction. Services violating these rules are ignored.
1232 An empty X-Next-Services value results in an empty plan which
1233 ends the current adaptation.
1235 Routing is not allowed by default: the ICAP X-Next-Services
1236 response header is ignored.
1239 Only has effect on split-stack systems. The default on those systems
1240 is to use IPv4-only connections. When set to 'on' this option will
1241 make Squid use IPv6-only connections to contact this ICAP service.
1244 <tag>logfile_rotate</tag>
1245 <p>No longer controls cache.log rotation. Use debug_options rotate=N instead.
1247 <tag>logformat</tag>
1248 <p>New log format tag sets %icap::* %adapt::* for adaptation information.
1249 <p>%Hs tag deprecated and replaced by request/reply specific >Hs and <Hs
1250 <p>New <em>%<la</em> Local IP address of the last server or peer connection. Ported from 2.7 where it is called <em>%oa</em>.
1251 <p>New <em>%<lp</em> Local port number of the last server or peer connection.
1252 <p>New <em>%>ha</em> to log HTTP request headers after adaptation and redirection.
1253 <p>HTTP request/reply format tags may now be optionally prefixed with http::.
1254 Old forms will be deprecated in some as yet undecided future release.
1256 dt Total time spent making DNS lookups (milliseconds)
1258 [http::]>ha The HTTP request headers after adaptation and redirection.
1259 [http::]>Hs HTTP status code sent to the client
1260 [http::]<Hs HTTP status code received from the next hop
1261 [http::]>sh Received HTTP request headers size
1262 [http::]<sh Sent HTTP reply headers size
1263 [http::]<pt Peer response time in milliseconds. The timer starts
1264 when the last request byte is sent to the next hop
1265 and stops when the last response byte is received.
1266 [http::]<tt Total server-side time in milliseconds. The timer
1267 starts with the first connect request (or write I/O)
1268 sent to the first selected peer. The timer stops
1269 with the last I/O with the last peer.
1271 If ICAP is enabled, the following two codes become available (as
1272 well as ICAP log codes documented with the icap_log option):
1274 icap::tt Total ICAP processing time for the HTTP
1275 transaction. The timer ticks when ICAP
1276 ACLs are checked and when ICAP
1277 transaction is in progress.
1279 icap::<last_h The header of the last ICAP response
1280 related to the HTTP transaction. Like
1281 <h, accepts an optional header name
1282 argument. Will not change semantics
1283 when multiple ICAP transactions per HTTP
1284 transaction are supported.
1286 If adaptation is enabled the following two codes become available:
1288 adapt::sum_trs Summed adaptation transaction response
1289 times recorded as a comma-separated list in
1290 the order of transaction start time. Each time
1291 value is recorded as an integer number,
1292 representing response time of one or more
1293 adaptation (ICAP or eCAP) transaction in
1294 milliseconds. When a failed transaction is
1295 being retried or repeated, its time is not
1296 logged individually but added to the
1297 replacement (next) transaction.
1299 adapt::all_trs All adaptation transaction response times.
1300 Same as adaptation_strs but response times of
1301 individual transactions are never added
1302 together. Instead, all transaction response
1303 times are recorded individually.
1305 You can prefix adapt::*_trs format codes with adaptation
1306 service name in curly braces to record response time(s) specific
1307 to that service. For example: %{my_service}adapt::sum_trs
1310 <tag>maximum_object_size_in_memory</tag>
1311 <p>Default size limit increased to 512KB.
1313 <tag>memory_pools_limit</tag>
1314 <p>Memory limits have been revised and corrected from 3.1.4 onwards.
1315 <p>Please check and update your squid.conf to use the text <em>none</em> for no limit instead of the old 0 (zero).
1316 <p>All users upgrading need to be aware that from Squid-3.3 setting this option to 0 (zero) will mean zero bytes of memory get pooled.
1318 <tag>negative_ttl</tag>
1319 <p>New default of 0 seconds. To prevent negative-caching of failure messages unless explicitly
1320 permitted by the message generating web server.
1321 <p>Changing this is an RFC 2616 violation and now requires --enable-http-violations
1323 <tag>refresh_pattern</tag>
1324 <p>New option 'ignore-must-revalidate'.
1326 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
1327 headers received from a server. Doing this VIOLATES
1328 the HTTP standard. Enabling this feature could make you
1329 liable for problems which it causes.
1331 <p>New set of basic patterns. These should always be listed after any custom patterns.
1332 They ensure RFC compliance with certain protocol and request handling in the absence
1333 of accurate Cache-Control: and Expires: information.
1335 refresh_pattern ^ftp: 1440 20% 10080
1336 refresh_pattern ^gopher: 1440 0% 1440
1337 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
1338 refresh_pattern . 0 20% 4320
1341 <tag>reply_header_max_size</tag>
1342 <p>Default limit increased to 64KB for RFC 2616 compliance.
1344 <tag>request_header_max_size</tag>
1345 <p>Default limit increased to 64KB for RFC 2616 compliance.
1347 <tag>tcp_outgoing_address</tag>
1348 <p>This option causes some problems when bridging IPv4 and IPv6. A workaround has been provided.
1350 Squid is built with a capability of bridging the IPv4 and IPv6 internets.
1351 tcp_outgoing_address as previously used breaks this bridging by forcing
1352 all outbound traffic through a certain IPv4 which may be on the wrong
1353 side of the IPv4/IPv6 boundary.
1355 To operate with tcp_outgoing_address and keep the bridging benefits
1356 an additional ACL needs to be used which ensures the IPv6-bound traffic
1357 is never forced or permitted out the IPv4 interface.
1359 acl to_ipv6 dst ipv6
1360 http_access allow to_ipv6 !all
1362 tcp_outgoing_address 2002::c001 good_service_net to_ipv6
1363 tcp_outgoing_address 10.0.0.2 good_service_net !to_ipv6
1365 tcp_outgoing_address 2002::beef normal_service_net to_ipv6
1366 tcp_outgoing_address 10.0.0.1 normal_service_net !to_ipv6
1368 tcp_outgoing_address 2002::1 to_ipv6
1369 tcp_outgoing_address 10.0.0.3 !to_ipv6
1372 <tag>wccp2_assignment_method hash mask</tag>
1373 <p>Method names now accepted. Replacing the old magic numbers.
1374 '1' becomes 'hash' and '2' becomes 'mask'
1376 <tag>wccp2_forwarding_method gre l2</tag>
1377 <p>Method names now accepted. Replacing the old magic numbers.
1378 '1' becomes 'gre' and '2' becomes 'l2'
1380 <tag>wccp2_return_method gre l2</tag>
1381 <p>Method names now accepted. Replacing the old magic numbers.
1382 '1' becomes 'gre' and '2' becomes 'l2'
1387 <sect1>Removed tags<label id="removedtags">
1391 <tag>dns_testnames</tag>
1392 <p>Obsolete. This feature is no longer relevant to modern networks and was causing boot problems.
1393 The -D command line option used previously to suppress these tests is also obsolete.
1395 <tag>extension_methods</tag>
1396 <p>Obsolete. All possible methods are now accepted and handled properly.</p>
1398 <tag>icap_class</tag>
1399 <p>Replaced by adaptation_service_set.</p>
1401 <tag>icap_access</tag>
1402 <p>Replaced by adaptation_access.</p>
1407 <sect>Changes to ./configure options since Squid-3.0
1409 There have been some changes to Squid's build configuration since Squid-3.0.
1411 This section gives an account of those changes in three categories:
1414 <item><ref id="newoptions" name="New options">
1415 <item><ref id="modifiedoptions" name="Changes to existing options">
1416 <item><ref id="removedoptions" name="Removed options">
1420 <sect1>New options<label id="newoptions">
1423 <tag>--enable-ecap</tag>
1424 <p>Build with support for loadable content adaptation modules.
1425 Cannot be used with --disable-loadable-modules.
1427 <tag>--enable-follow-x-forwarded-for</tag>
1428 <p>Support following the X-Forwarded-For HTTP header for determining the
1429 original or indirect client when a request has been forwarded through other
1432 <tag>--enable-ssl-crtd</tag>
1433 <p>Prevent Squid from direct generation of SSL private key and
1434 certificate request and instead enables the <em>ssl_crtd</em> processes.
1436 <tag>--enable-zph-qos</tag>
1437 <p>Build with support for ZPH Quality of Service controls
1439 <tag>--disable-auto-locale</tag>
1440 <p>Disable error page localization for visitors.
1441 <p>error_directory option is required if this option is used.
1443 <tag>--disable-ipv6</tag>
1444 <p>Build without IPv6 support. The default is to auto-detect system capabilities
1445 and use IPv6 when possible.
1447 <tag>--disable-loadable-modules</tag>
1448 <p>Build without support for loadable modules.
1450 <tag>--disable-strict-error-checking</tag>
1451 <p>Build Squid without advanced compiler error checking (without the -Werror option).
1452 This only affects the building process, enabling it to complete despite some
1453 possibly serious issues.
1454 Please do not use lightly, and please report the build issues which make it needed
1455 to the Squid developers before doing so.
1457 <tag>--disable-translation</tag>
1458 <p>Prevent Squid generating localized error page templates and manuals when built.
1459 Which is usually tried, but may not be needed.
1460 <p>This is an optimization for building fast when localization is not needed
1461 or localization tools are not available.
1462 <p>A copy of the latest translated files can instead be downloaded from
1463 <url url="http://www.squid-cache.org/Versions/langpack/" name="http://www.squid-cache.org/Versions/langpack/">
1465 <tag>--with-logdir=PATH</tag>
1466 <p>Allow build-time configuration of Default location for Squid logs.
1468 <tag>--with-pidfile=PATH</tag>
1469 <p>Allow build-time configuration of Default location and name of squid.pid file.
1471 <tag>--with-po2html=PATH</tag>
1472 <p>Absolute path to po2html executable.
1473 Default is to automatically detect the binary.
1475 <tag>--without-libcap</tag>
1476 <p>Build without libcap support. The default is to auto-detect system capabilities
1477 and enable support when possible.
1478 <p>NOTE: Disabling this or building without libcap support will break TPROXY support.
1482 <sect1>Changes to existing options<label id="modifiedoptions">
1485 <tag>--enable-shared[=PKGS]</tag>
1486 <p>Default changed to yes.
1488 <tag>--enable-linux-netfilter</tag>
1489 <p>This option now enables support for all three netfilter interception targets.
1490 <p>Adding TPROXY version 4+ support to Squid through the netfilter TPROXY target.
1491 This options requires a linux kernel 2.6.25 or later for embeded netfilter TPROXY targets.
1492 <p>Older REDIRECT and DNAT targets work as before on HTTP ports marked 'intercept'.
1494 <tag>--enable-linux-tproxy</tag>
1495 <p>Deprecated. Remains only to support old TPROXY version 2.2 installations.
1496 Scheduled for complete removal in Squid 3.2
1498 <tag>--enable-ntlm-auth-helpers</tag>
1499 <p>Helper previously built by <em>SMB</em> is now built by <em>smb_lm</em>.
1500 It also has a new squid.conf name for usage, see <em>auth_param</em> above for details.
1502 <tag>--disable-internl-dns</tag>
1503 <p>Better support for Linux using the external DNS helper.
1504 The helper will now compile and work with dns_nameservers on more variants of Linux than previously.
1505 It is still deprecated however and use of this option should be avoided as much as possible.
1507 <tag>--with-aio</tag>
1508 <p>Deprecated. POSIX AIO is now auto-detected and enabled.
1509 Use --without-aio to disable, but only if you really have to.
1511 <tag>--with-pthreads</tag>
1512 <p>Deprecated. pthreads library is now auto-detected and enabled.
1513 Use --without-pthreads to disable, but only if you really have to.
1518 <sect1>Removed options<label id="removedoptions">
1521 <tag>--enable-default-err-language</tag>
1522 <p>Replaced by error_default_language squid.conf option
1524 <tag>--enable-err-languages</tag>
1525 <p>Removed. All languages used now for error page localization.
1527 <tag>--disable-carp</tag>
1528 <p>Removed. CARP is required by several peering algoithms. Disabling is not useful.
1530 <tag>--disable-mempools</tag>
1531 <p>Replaced by memory_pools squid.conf option.
1535 <sect>Options Removed since Squid-2
1537 <p>Some squid.conf and ./configure options which were available in Squid-2.6 and Squid-2.7 are made obsolete in Squid-3.1.
1539 <sect1>Removed squid.conf options since Squid-2.7
1542 <tag>auth_param</tag>
1543 <p><em>blankpassword</em> option for basic scheme removed.
1545 <tag>cache_peer</tag>
1546 <p><em>http11</em> Obsolete.
1548 <tag>external_acl_type</tag>
1549 <p>Format tag <em>%{Header}</em> replaced by <em>%>{Header}</em>
1550 <p>Format tag <em>%{Header:member}</em> replaced by <em>%>{Header:member}</em>
1552 <tag>header_access</tag>
1553 <p>Replaced by <em>request_header_access</em> and <em>reply_header_access</em>
1555 <tag>http_access2</tag>
1556 <p>Replaced by <em>adapted_http_access</em>
1558 <tag>http_port</tag>
1559 <p><em>no-connection-auth</em> replaced by <em>connection-auth=[on|off]</em>. Default is ON.
1560 <p><em>transparent</em> option replaced by <em>intercept</em>
1562 <tag>httpd_accel_no_pmtu_disc</tag>
1563 <p>Replaced by <em>http_port disable-pmtu-discovery=</em> option
1565 <tag>incoming_rate</tag>
1568 <tag>logformat</tag>
1569 <p><em>%oa</em> tag replaced by <em>%<la</em>
1571 <tag>redirector_bypass</tag>
1572 <p>Replaced by <em>url_rewrite_bypass</em>
1574 <tag>server_http11</tag>
1577 <tag>upgrade_http0.9</tag>
1578 <p>Obsolete. ICY protocol streaming support added natively.
1580 <tag>zph_local</tag>
1581 <p>Replaced by <em>qos_flows local-hit=</em>
1586 <tag>zph_option</tag>
1589 <tag>zph_parent</tag>
1590 <p>Replaced by <em>qos_flows parent-hit=</em>
1592 <tag>zph_sibling</tag>
1593 <p>Replaced by <em>qos_flows sibling-hit=</em>
1597 <sect1>Removed squid.conf options since Squid-2.6
1600 <tag>cache_dir</tag>
1601 <p><em>read-only</em> option replaced by <em>no-store</em>.
1605 <sect1>Removed ./configure options since Squid-2.7
1608 <tag>--enable-coss-aio-ops</tag>
1611 <tag>--enable-devpoll</tag>
1612 <p>Replaced by automatic detection.
1614 <tag>--enable-dlmalloc=LIB</tag>
1617 <tag>--enable-epoll</tag>
1618 <p>Replaced by automatic detection.
1620 <tag>--enable-forward-log</tag>
1623 <tag>--enable-heap-replacement</tag>
1626 <tag>--enable-htcp</tag>
1627 <p>Obsolete. Enabled by default.
1629 <tag>--enable-large-cache-files</tag>
1632 <tag>--enable-mempool-debug</tag>
1635 <tag>--enable-multicast-miss</tag>
1638 <tag>--enable-poll</tag>
1639 <p>Replaced by automatic detection.
1641 <tag>--enable-select</tag>
1642 <p>Replaced by automatic detection.
1644 <tag>--enable-select-simple</tag>
1645 <p>Replaced by automatic detection.
1647 <tag>--enable-snmp</tag>
1648 <p>Obsolete. Enabled by default.
1650 <tag>--enable-truncate</tag>
1653 <tag>--disable-kqueue</tag>
1654 <p>Obsolete. Disabled by default.
1659 <sect>Regressions since Squid-2.7
1661 <p>Some squid.conf and ./configure options which were available in Squid-2.7 are not yet available in Squid-3.1
1663 <p>If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.
1665 <sect1>Missing squid.conf options available in Squid-2.7
1669 <p><em>urllogin</em> option not yet ported from 2.6
1670 <p><em>urlgroup</em> option not yet ported from 2.6
1672 <tag>auth_param digest</tag>
1673 <p><em>concurrency</em> option not yet ported from Squid-2
1675 <tag>authenticate_ip_shortcircuit_access</tag>
1676 <p>Not yet ported from 2.7
1678 <tag>authenticate_ip_shortcircuit_ttl</tag>
1679 <p>Not yet ported from 2.7
1681 <tag>broken_vary_encoding</tag>
1682 <p>Not yet ported from 2.6
1684 <tag>cache_dir</tag>
1685 <p><em>min-size</em> option not yet ported from Squid-2
1686 <p><em>COSS</em> storage type is lacking stability fixes from 2.6
1687 <p>COSS <em>overwrite-percent=</em> option not yet ported from 2.6
1688 <p>COSS <em>max-stripe-waste=</em> option not yet ported from 2.6
1689 <p>COSS <em>membufs=</em> option not yet ported from 2.6
1690 <p>COSS <em>maxfullbufs=</em> option not yet ported from 2.6
1692 <tag>cache_peer</tag>
1693 <p><em>idle=</em> not yet ported from 2.7
1694 <p><em>monitorinterval=</em> not yet ported from 2.6
1695 <p><em>monitorsize=</em> not yet ported from 2.6
1696 <p><em>monitortimeout=</em> not yet ported from 2.6
1697 <p><em>monitorurl=</em> not yet ported from 2.6
1699 <tag>cache_vary</tag>
1700 <p>Not yet ported from 2.6
1702 <tag>collapsed_forwarding</tag>
1703 <p>Not yet ported from 2.6
1705 <tag>error_map</tag>
1706 <p>Not yet ported from 2.6
1708 <tag>external_acl_type</tag>
1709 <p><em>%ACL</em> format tag not yet ported from 2.6
1710 <p><em>%DATA</em> format tag not yet ported from 2.6
1712 <tag>external_refresh_check</tag>
1713 <p>Not yet ported from 2.7
1715 <tag>http_port</tag>
1716 <p><em>act-as-origin</em> not yet ported from 2.7
1717 <p><em>http11</em> not yet ported from 2.7
1718 <p><em>urlgroup=</em> not yet ported from 2.6
1720 <tag>ignore_ims_on_miss</tag>
1721 <p>Not yet ported from 2.7
1723 <tag>location_rewrite_access</tag>
1724 <p>Not yet ported from 2.6
1726 <tag>location_rewrite_children</tag>
1727 <p>Not yet ported from 2.6
1729 <tag>location_rewrite_concurrency</tag>
1730 <p>Not yet ported from 2.6
1732 <tag>location_rewrite_program</tag>
1733 <p>Not yet ported from 2.6
1735 <tag>logfile_daemon</tag>
1736 <p>Not yet ported from 2.7.
1738 <tag>logformat</tag>
1739 <p><em>%sn</em> tag not yet ported from 2.7
1741 <tag>max_stale</tag>
1742 <p>Not yet ported from 2.7
1744 <tag>refresh_pattern</tag>
1745 <p><em>stale-while-revalidate=</em> not yet ported from 2.7
1746 <p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7
1747 <p><em>max-stale=</em> not yet ported from 2.7
1748 <p><em>negative-ttl=</em> not yet ported from 2.7
1750 <tag>refresh_stale_hit</tag>
1751 <p>Not yet ported from 2.7
1753 <tag>storeurl_access</tag>
1754 <p>Not yet ported from 2.7
1756 <tag>storeurl_rewrite_children</tag>
1757 <p>Not yet ported from 2.7
1759 <tag>storeurl_rewrite_concurrency</tag>
1760 <p>Not yet ported from 2.7
1762 <tag>storeurl_rewrite_program</tag>
1763 <p>Not yet ported from 2.7
1765 <tag>update_headers</tag>
1766 <p>Not yet ported from 2.7
1768 <tag>zero_buffers</tag>
1769 <p>Not yet ported from 2.7
1773 <sect1>Missing ./configure options available in Squid-2.7
1776 <tag>--without-system-md5</tag>
1782 Copyright (C) 1996-2018 The Squid Software Foundation and contributors
1784 Squid software is distributed under GPLv2+ license and includes
1785 contributions from numerous individuals and organizations.
1786 Please see the COPYING and CONTRIBUTORS files for details.