1 <!doctype linuxdoc system>
3 <title>Squid 3.2.14 release notes</title>
4 <author>Squid Developers</author>
7 This document contains the release notes for version 3.2 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.2.14.
18 This new release is available for download from <url url="http://www.squid-cache.org/Versions/v3/3.2/"> or the
19 <url url="http://www.squid-cache.org/Download/http-mirrors.html" name="mirrors">.
21 <p>A large number of the show-stopper bugs have been fixed along with general improvements to the IPv6 support.
22 While this release is not fully bug-free we believe it is ready for use in production on many systems.
24 <p>We welcome feedback and bug reports. If you find a bug, please see <url url="http://wiki.squid-cache.org/SquidFaq/BugReporting"> for how to submit a
25 report with a stack trace.
29 Although this release is deemed good enough for use in many setups, please note the existence of
30 <url url="http://bugs.squid-cache.org/buglist.cgi?query_format=advanced&product=Squid&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&version=3.2" name="open bugs against Squid-3.2">.
32 <p>Some issues to note as currently known in this release which are not able to be fixed in the 3.2 series are:
35 <item>TCP logging of access.log does not recover from broken connections well.
36 <item>SSL-Bump not re-wrapping decrypted traffic in CONNECT for peers.
37 <item>Cache Manager reports in txt/plain format even when requested directly via browser.
40 <p>Currently known issues which only depends on available developer time and may still be resolved in a future 3.2 release are:
43 <item>SMP Support still has a number of important bugs needing to be resolved. see the bugs list above for details.
44 <item>Windows support is still incomplete.
45 <item>The lack of some features available in Squid-2.x series. See the regression sections below for full details.
49 <sect1>Changes since earlier releases of Squid-3.2
51 The 3.2 change history can be <url url="http://www.squid-cache.org/Versions/v3/3.2/changesets/" name="viewed here">.
53 <sect>Major new features since Squid-3.1
54 <p>Squid 3.2 represents a new feature release above 3.1.
56 <p>The most important of these new features are:
58 <item>CVE-2009-0801 : NAT interception vulnerability to malicious clients.
59 <item>NCSA helper DES algorithm password limits
61 <item>Helper Multiplexer and On-Demand
62 <item>Helper Name Changes
63 <item>Multi-Lingual manuals
64 <item>Solaris 10 pthreads Support
65 <item>Surrogate/1.0 protocol extensions to HTTP
66 <item>Logging Infrastructure Updated
67 <item>Client Bandwidth Limits
68 <item>Better eCAP support
69 <item>Cache Manager access changes
72 Most user-facing changes are reflected in squid.conf (see below).
75 <sect1>CVE-2009-0801 : NAT interception vulnerability to malicious clients.
76 <p>Details in Advisory <url url="http://www.squid-cache.org/Advisories/SQUID-2011_1.txt" name="SQUID-2011:1">
78 <p>Squid locates the authority-URL details available in an HTTP request as
79 defined by RFC 2616 and validates that all found representations are
80 <em>textually</em> equivalent. In the case of intercepted traffic the
81 client destination IP is also compared to the Host: authority domains
84 <p>When the Host: authority contradicts another authority source Squid will log
85 "SECURITY ALERT: Host: header forgery detected". The response will then be determined
86 by the <url url="http://www.squid-cache.org/Doc/config/host_verify_strict/" name="host_verify_strict">
87 directive. Squid will respond with 409 Conflict error response when strict validation
88 fails and handles the request normally when strict validation succeeds or is OFF (default).
90 <p>Relaying of messages which FAIL non-strict Host: validation are permitted through Squid but
91 only to the original destination IP the client was requesting or to explicit peers. This means
92 DNS lookups to locate alternative DIRECT destinations will not be done.
94 <p>Known Issue: When non-strict validation fails Squid will relay the request, but can only do
95 so safely to the original destination IP the client was contacting. The client original
96 destination IP is lost when relaying to peers in a hierarchy. This means the upstream peers
97 are still at risk of causing same-origin bypass CVE-2009-0801 vulnerability.
98 Developer time is required to implement safe transit of these requests.
99 Please contact squid-dev if you are able to assist or sponsor the development.
102 <sect1>NCSA helper DES algorithm password limits
103 <p>Details in Advisory <url url="http://www.squid-cache.org/Advisories/SQUID-2011_2.txt" name="SQUID-2011:2">
105 <p>The DES algorithm used by the NCSA Basic authentication helper has an
106 limit of 8 bytes but some implementations do not error when truncating
107 longer passwords down to this unsafe level.
109 <p>This both significantly lowers the threshold of difficulty decrypting
110 captured password files and hides from users the fact that the extra bits
111 of their chosen long password is not being utilized.
113 <p>The NCSA helper bundled with Squid will prevent passwords longer than 8
114 characters being sent to the DES algorithm. The MD5 hash algorithm which
115 supports longer than 8 character passwords is also supported by this helper
116 and should be used instead.
119 <sect1>SMP scalability
120 <p>The new "workers" squid.conf option can be used to launch multiple worker
121 processes and utilize multiple CPU cores. The overall intent is to make
122 multiple workers look like one to an outside observer, while providing
123 knobs to customize each worker behavior if needed.
125 <p>By default, all worker processes are configured identically and do what a
126 single Squid instance would have done. Squid.conf macro substitutions and
127 conditionals (see below) can be used to customize individual worker
128 configurations. In the paragraphs below, "can share" implies "will share by
131 <p>Workers can share HTTP, HTTPS, SNMP, ICP, and HTCP listening addresses.
132 Configuration related to ICP and HTCP clients must be adjusted to avoid
133 source address conflicts: Modify the IP address and/or the port used for
134 the protocol. Workers do not share DNS addresses by default because the OS
135 assigns each worker a unique DNS port.
137 <p>Workers can share logs.
139 <p>Workers can share caches. Memory cache is automatically shared when multiple
140 workers are used. Cache_dir are shared when configured with the <em>rock</em>
141 storage type. Cache_dir of other types must be adjusted to point each
142 disk-caching worker to its own disk area. ICP and HTCP responses are based
143 on the responding worker cache state.
145 <p>Cache manager statistics are reported from a worker point of view, for now.
146 Though some reports are combined. SNMP statistics are combined across all
149 <p>Startup, reconfiguration, shutdown, and log rotation are handled as for a
150 monolithic Squid. Abnormally terminated workers are restarted while
151 other workers continue serving traffic.
153 <sect2>Squid.conf macros and conditionals
154 <p>Added support for process_name and process_number macros as well as simple
155 if-statement conditionals in squid.conf. These features allow individual
156 worker customization in SMP mode. For details, search for "Conditional
157 configuration" and "SMP-Related Macros" sections in squid.conf.documented.
160 <sect1>Helper Multiplexer
161 <p>The helper multiplexer's purpose is to relieve some of the burden
162 Squid has when dealing with slow helpers. It does so by acting as a
163 middleman between squid and the actual helpers, talking to Squid via
164 the multiplexed concurrent variant of the helper protocol and to the
165 helpers via the non-concurrent variant.
167 <p>Helpers are started on demand, and in theory the muxer can handle up to
168 1k helpers per instance. It's up to squid to decide how many helpers
171 <p>The muxer knows nothing about the actual messages being passed around,
172 and as such can't really (yet?) compensate for broken helpers.
173 It is not yet able to manage dying helpers, but it will.
175 <p>To configure the multiplexer add its binary name (usually /usr/share/libexec/helper-mux.pl)
176 in front of the name of whichever helper is being multiplexed. It takes the helper binary
177 path and parameters as its own command parameters. The <em>concurrency</em> setting already
178 existing in Squid is used to configure how many child helpers it may run.
180 <p>For example, a traditional configuration is
182 url_rewrite_program /your/redirector.sh
183 url_rewrite_children 5
185 the alternative multiplexer configuration is:
187 url_rewrite_program /usr/share/libexec/helper-mux.pl /your/redirector.sh
188 url_rewrite_children 1 concurrency=5
191 <p>Helpers which are already concurrent protocol enabled gain little benefit from the multiplexer
192 on most systems. However on some systems where Squid spawning helpers causes excess memory usage
193 the reduction in direct helper spawned by Squid can result in a great reduction in resource use.
195 <p>The helper can be controlled using various signals:
197 <item>SIGHUP: dump the state of all helpers to STDERR
201 <sect1>Helpers On-Demand
202 <p>Traditionally Squid has been configured with a fixed number of helpers and started them during
203 it's start and reconfigure phases. This forces the hard configuration problem of how many helpers
204 will be needed to be solved before starting Squid in production use.
206 <p>The on-demand helpers feature allows greater flexibility and resolves this problem by allowing
207 maximum, initial and idle thresholds to be configured. Squid will start the initial set during
208 start and reconfigure phases. However over the operational use new helpers up to the maxium will
209 be started as load demands. The idle threshold determines how many more helpers to start if the
210 currently running set is not enough to handle current request loads.
212 <p>For example, a traditional configuration is
214 auth_param ntlm /usr/libexec/squid/ntlm_auth
215 auth_param ntlm children 200
217 the alternative on-demand configuration could be:
219 auth_param ntlm /usr/libexec/squid/ntlm_auth
220 auth_param ntlm children 200 startup=10 idle=2
223 <p>The example still permits up to 200 helpers to be running at once under peak traffic loads.
224 But only starts 10 when Squid is initialized resulting in a faster boot up.
225 When client requests threaten to overload the running helpers an additional 2 will be started.
227 <p>NOTE: if no <em>startup</em> and <em>idle</em> values are specified the traditional behaviour
228 of starting the maximum number of helpers will occur.
231 <sect1>Helper Name Changes
232 <p>To improve the understanding of what each helper does and where it should be used the helper binaries
233 which are bundled with Squid have undergone a naming change in this release.
235 <p>Below is a list of the old helper names and what their names have changed to.
236 For several helpers the directory name used in --enable-X-helpers configure option has also changed.
238 <sect2>Basic Authentication protocol helpers
240 <item>squid_db_auth - basic_db_auth - Retrieve authentication details from a simple SQL database table.
241 <item>getpwnam_auth - basic_getpwname_auth - Authenticate with local system user accounts.
242 <item>squid_ldap_auth - basic_ldap_auth - Authenticate with LDAP user accounts.
243 <item>MSNT-multi-domain - basic_msnt_multi_domain_auth - Authenticate with any one of multiple Windows Domain Controllers.
244 <item>msnt_auth - basic_msnt_auth - Authenticate with Windows Domain Controllers selected by username.
245 <item>ncsa_auth - basic_ncsa_auth - Authenticate with NCSA httpd-style password file.
246 <item>yp_auth - basic_nis_auth - Authenticate with NIS security system.
247 <item>pam_auth - basic_pam_auth - Authenticate with the system PAM infrastructure.
248 <item>pop3.pl - basic_pop3_auth - Authenticate with a mail server POP3/SMTP credentials.
249 <item>squid_radius_auth - basic_radius_auth - Authenticate with RADIUS.
250 <item>squid_sasl_auth - basic_sasl_auth - Authenticate with SASL.
251 <item>smb_auth - basic_smb_auth - Authenticate with Samba SMB.
252 <item>mswin_sspi - basic_sspi_auth - Authenticate with a Windows Domain Controller using SSPI.
255 <sect2>Digest Authentication protocol helpers
257 <item>digest_pw_auth - digest_file_auth - Authenticate against credentials stored in a simple text file.
260 <sect2>External ACL helpers
262 <item>mswin_check_ad_group - ext_ad_group_acl - Check logged in users Group membership using Active Directory.
263 <item>ip_user_check - ext_file_userip_acl - Restrict users to certain IP addresses, using a text file backend.
264 <item>squid_kerb_ldap - ext_kerberos_ldap_group_acl - Check logged in Kerberos or NTLM users Group membership using LDAP.
265 <item>squid_ldap_group - ext_ldap_group_acl - Check logged in users Group membership using LDAP.
266 <item>mswin_check_lm_group - ext_lm_group_acl - Check logged in users Group membership using LanManager.
267 <item>squid_session - ext_session_acl - Maintain a session cache of client identifiers (usually IP address).
268 This helper has also gone through a version update and now uses more current BerkeleyDB 4.1+ APIs.
269 <item>squid_unix_group - ext_unix_group_acl - Check logged in users Group membership using local UNIX groups.
270 <item>wbinfo_group.pl - ext_wbinfo_group_acl - Check logged in users Group membership using wbinfo.
273 <sect2>Negotiate Authentication protocol helpers
275 <item>squid_kerb_auth - negotiate_kerberos_auth - Authenticate with Kerberos servers.
276 <item>mswin_sspi - negotiate_sspi_auth - Authenticate with a Windows Domain Controller using SSPI.
277 <item>negotiate_wrapper - negotiate_wrapper_auth - Split Negotiate traffic between Kerberos and NTLM helpers.
280 <sect2>NTLM Authentication protocol helpers
282 <item>no_check.pl - Deprecated. - Use the faster and less easily decrypted ntlm_fake_auth instead.
283 <item>fakeauth_auth - ntlm_fake_auth - Perform NTLMSSP to recover the username but don't verify the password.
284 <item>ntlm_auth - ntlm_smb_lm_auth - Perform SMB LanManager domain-less authentication over NTLM protocol.
285 <item>mswin_ntlm_auth - ntlm_sspi_auth - Perform NTLMSSP authentication using Windows native Security Support Provider Interface API.
288 <sect2>URL re-write helpers
289 <p>This group of helpers have been bundled to demonstrate how to code URL re-writers:
291 <item>url_fake_rewrite - Accept various url_rewrite details and log the input.
295 <sect1>Multi-Lingual manuals
296 <p>The man(8) and man(1) pages bundled with Squid are now provided online for all
297 versions and beginning with 3.2 they are available in languages other than English (where translated).
299 <p>Details in <url url="http://wiki.squid-cache.org/Translations" name="The Squid wiki">
301 <p>3.1 began the Internationalization of Squid with the public facing error pages.
302 This move begins the Localization of the internal administrator facing manuals.
305 <sect1>Solaris 10 pthreads Support (Experimental)
306 <p>Automatic detection and use of the pthreads library available from Solaris 10
308 <p>The result of this addition means that faster more efficient AUFS cache storage mechanism
309 is now available in Solaris 10.
311 <p>Support is experimental at this stage due to lack of feedback on the results of enabling it.
312 We recommend giving AUFS a try for faster disk storage and encourage feedback.
315 <sect1>Surrogate/1.0 protocol extensions to HTTP
316 <p>The <em>Surrogate</em> extensions to HTTP protocol enable an origin web server to specify separate
317 cache controls for a reverse proxy acting on its behalf. Previously this was closely tied with the ESI
318 feature support in Squid. This release opens Surrogate support to all reverse proxies.
320 <p>Reverse proxy requests sent on to the web server include the HTTP header <em>Surrogate-Capabilities:</em>
321 specifying the capabilities of the reverse proxy along with an ID which can be used to target responses with
322 a <em>Surrogate-Control:</em> HTTP header used instead of the <em>Cache-Control:</em> header.
324 <p>The default surrogate ID is generated automatically from the Squid site-unique hostname as found by the
325 automatic detection or manual configuration of <em>visible_hostname</em> although can be configured
326 separately with the <em>httpd_accel_surrogate_id</em> option.
328 <p><em>Security Considerations:</em> Websites should be careful of accepting any surrogate ID.
329 Older releases of Squid leak the Surrogate-Control headers to external servers.
330 This 3.2 series of Squid will now prevent this leakage of its own ID destined responses, however it is possible
331 and for some uses desirable to receive external reverse-proxies <em>Surrogate-Capabilities:</em> headers.
333 <p><em>NOTE:</em> Several operating system distributions historically package Squid with a forced value of
334 <em>visible_hostname localhost</em>. If this is done on a Surrogate enabled install a manual re-configuration
335 is required to prevent an unacceptable surrogate ID of 'localhost' being generated.
338 <sect1>Logging Infrastructure Updated
339 <p>The advanced logging modules introduced in Squid-2.7 are now available from Squid-3.2.
341 <p>This feature is documented at http://wiki.squid-cache.org/Features/LogModules
343 <p>The new infrastructure currently supports several different channels types (modules) ranging from
344 direct filesystem logging (stdio, daemon) to network logging (syslog, UDP and TCP). The daemon logging
345 interface allows for a custom helper to be written to process logs in real-time.
347 <p>Upgrading: the <em>access_log</em> and <em>cache_store_log</em> were previously logged via what is
348 now called the <em>stdio</em> module.
349 This is still supported and used by default if no module is named. For best performance particularly in SMP
350 environments we recommend the <em>daemon</em> be used. The provided <em>log_file_daemon</em> helper
351 performs the traditional logging to local filesystem.
353 <p>Additional to this the cache.log can now be limited to a smaller number of files stored.
354 Traditionally cache.log.N has been fixed at the same number of rotated files as access.log.N through the
355 <em>logfile_rotate</em> setting. The <em>debug_options</em> setting can now be used to configure the number
356 of debug cache.log files to rotate through with a <em>rotate=N</em> option. This is particularly useful for
357 logging a single cache.log at relatively high debug levels on a high-traffic system. Or one which is
358 required to store a long period of access.log and needs to conserve disk space.
360 <p>The <em>referer_log</em> and <em>useragent_log</em> directives have been converted to built-in log formats.
361 These logs are now created using an <em>access_log</em> line with the format "referrer" or "useragent".
362 They also now log all client requests, if there was no Referer or User-Agent header a dash (-) is logged.
364 <p>Known Issue: The TCP logging module does not recover from broken connections well.
365 At present it will restart the affected Squid instance if the TCP connection is broken.
368 <sect1> Client Bandwidth Limits
369 <p>In mobile environments, Squid may need to limit Squid-to-client bandwidth
370 available to individual users, identified by their IP addresses. The IP
371 address pool can be as large as a /10 IPv4 network (4 million unique IP
372 addresses) and even larger in IPv6 environments. On the other hand, the code
373 should support thousands of connections coming from a single IP (e.g.,
376 <p>The implementation is based on storing bandwidth-related "bucket" information
377 in the existing "client database" hash (client_db.cc). The old code already
378 assigned each client IP a single ClientInfo object, which satisfies the
379 client-side IP-based bandwidth pooling requirements. The old hash size is
380 increased to support up to 32K concurrent clients if needed.
382 <p>Client-side pools are configured similarly to server-side ones, but there is
383 only one pool class. See client_delay_pools,
384 client_delay_initial_bucket_level, client_delay_parameters, and
385 client_delay_access in squid.conf. The client_delay_access matches the client
386 with delay parameters. It does not pool clients from different IP addresses
389 <p>Special care is taken to provide fair distribution of bandwidth among clients
390 sharing the same bucket (i.e., clients coming from the same IP address).
391 Multiple same-IP clients competing for bandwidth are queued using FIFO
392 algorithm. If a bucket becomes empty, the first client among those sharing
393 the bucket is delayed by 1 second before it can attempt to receive more
394 response data from Squid. This delay may need to be lowered in
395 high-bandwidth environments.
398 <sect1>Better eCAP Suport
399 <p>Support for libecap version 0.2.0 has been added with this series of Squid. Bringing
400 better support for body handling, and logging.
402 <p>Known Issue: Due to API changes in libecap this release of Squid will not build
403 against any older libecap releases.
406 <sect1>Cache Manager access changes
407 <p>The Squid Cache Manager has previously only been accessible under the cache_object://
408 URL scheme. Which has restricted its reporting to tools which can send arbitrary
411 <p>This version of Squid now provides access through the http:// and https:// URL schemes
412 allowing web browsers access without having to use the cachemgr.cgi gateway and enabling
413 the use of HTTPS security were desired.
415 <p>The cache manager is available under the path prefix /squid-internal-mgr/. For example
416 the URL http://example/com/squid-internal-mgr/menu will bring up the manager menu. This
417 means there are some configuration changes required to lock down manager access.
418 The <em>manager</em> ACL needs changing. A built-in definition is now used, equivalent
419 to the following regex pattern:
421 ^(cache_object://|https?://[^/]+/squid-internal-mgr/)
424 <p>The manager prefix /squid-internal-mgr/ with no action attempts to load an optional
425 template MGR_INDEX which may be installed amongst in the Squid error templates.
426 This template is not supplied with Squid but intended to be supplied by separate
427 cache manager applications as their front page embedding all scripts, accessors or
428 redirects required for their initial GUI display.
432 <item>should contain a complete HTML page, with optional client-side scripting.
433 <item>must not contain server-side scripting.
434 <item>will have macro substitution performed on it using the same macros as used by the error page templates.
437 <p>Version 3.2 of the CGI cache manager tool now presents XHR scripted probes to detect
438 proxies presenting these manager index pagess and provides direct HTTP/HTTPS web links
442 <sect>Changes to squid.conf since Squid-3.1
444 There have been changes to Squid's configuration file since Squid-3.1.
446 This section gives a thorough account of those changes in three categories:
449 <item><ref id="newtags" name="New tags">
450 <item><ref id="modifiedtags" name="Changes to existing tags">
451 <item><ref id="removedtags" name="Removed tags">
455 <sect1>New tags<label id="newtags">
458 <tag>adaptation_meta</tag>
459 <p>This option allows Squid administrator to add custom ICAP request
460 headers or eCAP options to Squid ICAP requests or eCAP transactions.
462 <tag>adaptation_send_client_ip</tag>
463 <p>Same as deprecated icap_send_client_ip
464 but applies to both ICAP and eCAP.</p>
466 <tag>adaptation_send_username</tag>
467 <p>Same as deprecated icap_send_client_username
468 but applies to both ICAP and eCAP.</p>
470 <tag>adaptation_uses_indirect_client</tag>
471 <p>Same as deprecated icap_uses_indirect_client
472 but applies to both ICAP and eCAP.</p>
474 <tag>client_delay_pools</tag>
475 <p>New setting for client bandwidth limits to specifies the number
476 of client delay pools used.
478 <tag>client_delay_initial_bucket_level</tag>
479 <p>New setting for client bandwidth limits to determine the initial
480 bucket size as a percentage of max_bucket_size from
481 client_delay_parameters.
483 <tag>client_delay_parameters</tag>
484 <p>New setting for client bandwidth limits to configures client-side
487 <tag>client_delay_access</tag>
488 <p>New setting for client bandwidth limits to determines the
489 client-side delay pool for the request.
491 <tag>client_dst_passthru</tag>
492 <p>New setting to disable extra Host: header security on interception proxies.
493 Impacts cache integrity/reliability and client browser security.
494 <p><em>IMPORTANT:</em> disabling this directive only allows Squid to change the
495 destination IP to another source indicated by Host: domain DNS or
496 cache_peer configuration. It <em>does not</em> affect Host: validation.
498 <tag>client_idle_pconn_timeout</tag>
499 <p>Renamed from <em>persistent_request_timeout</em>.
501 <tag>cpu_affinity_map</tag>
502 <p>New setting for SMP support to map Squid processes onto specific CPU cores.
504 <tag>connect_retries</tag>
505 <p>Replacement for <em>maximum_single_addr_tries</em>, but instead of only applying to hosts with single addresses.
506 This directive applies to all hosts, extending the number of connection attempts to each IP address.
508 <tag>dns_packet_max</tag>
509 <p>New setting to configure maximum number of bytes packet size to advertise via EDNS.
510 Set to "none" (the initial default) to disable EDNS large packet support.
513 <p>Part of conditional SMP support syntax. see <em>if</em>
516 <p>Part of conditional SMP support syntax. see <em>if</em>
518 <tag>eui_lookup</tag>
519 <p>Whether to lookup the EUI or MAC address of a connected client.
521 <tag>host_verify_strict</tag>
522 <p>New option to enable super-strict HTTP and DNS information match.
523 Ensuring the HTTP URI details, DNS records, and TCP connection layers all match in a
524 three-legged security verification. Preventing domain hijacking or malicious poisoning
525 attacks by malicious scripts.
526 <p>The default is to verify only intercepted traffic, to log all issues and let failed
527 traffic through when doing so can be done safely.
529 <tag>icap_206_enable</tag>
530 <p>New option to toggle whether the ICAP 206 (Partial Content) responses extension.
534 <p>New conditional syntax for SMP multiple-worker.
535 If-statements can be used to make configuration directives depend on conditions.
536 <p>The else part is optional. The keywords <em>if</em>, <em>else</em> and <em>endif</em>
537 must be typed on their own lines, as if they were regular configuration directives.
539 <tag>logfile_daemon</tag>
540 <p>Ported from 2.7. Specify the file I/O daemon helper to run for logging.
543 <p>Places an upper limit on how stale content Squid will serve from the cache if cache validation fails
545 <tag>memory_cache_mode</tag>
546 <p>Controls which objects to keep in the memory cache (cache_mem)
548 'always' Keep most recently fetched objects in memory (default)
550 'disk' Only disk cache hits are kept in memory, which means
551 an object must first be cached on disk and then hit
552 a second time before cached in memory.
554 network Only objects fetched from network is kept in memory
557 <tag>memory_cache_shared</tag>
558 <p>Controls whether the memory cache is shared among SMP workers.
559 <p>Currently, entities exceeding 32KB in size cannot be shared.
561 <tag>server_idle_pconn_timeout</tag>
562 <p>Renamed from <em>pconn_timeout</em>.
564 <tag>tproxy_uses_indirect_client</tag>
565 <p>Controls whether the indirect client address found in the X-Forwarded-For
566 header is used for spoofing instead of the directly connected client address.
567 Requires both <em>--enable-follow-x-forwarded-for</em> and <em>--enable-linux-netfilter</em>
570 <p>Number of main Squid processes or "workers" to fork and maintain.
571 In SMP mode, each worker does nearly all what a single Squid daemon
572 does (e.g., listen on http_port and forward HTTP requests).
574 0: "no daemon" mode, like running "squid -N ..."
575 1: "no SMP" mode, start one main Squid process daemon (default)
576 N: start N main Squid process daemons (i.e., SMP mode)
579 <tag>write_timeout</tag>
580 <p>New setting to limit time spent waiting for data writes to be confirmed.
583 <sect1>Changes to existing tags<label id="modifiedtags">
586 <tag>access_log</tag>
587 <p>New <em>stdio</em> module to send log data directly from Squid to a disk file.
588 This is the historic behaviour of Squid before logging modules were introduced, and
589 remains the default used when no module is selected.
590 It is recommended to upgrade logging to the faster <em>daemon:</em> module.
591 <p>New <em>daemon</em> module to send each log line as text data to a file I/O daemon handling the slow disk I/O.
592 New installs, or installs with no logs configured explicitly will use this module by default.
593 <p>New <em>tcp</em> module to send each log line as text data to a TCP receiver.
594 <p>New <em>udp</em> module to send each log line as text data to a UDP receiver.
595 <p>New format <em>referrer</em> to log with the format previously used by referer_log directive.
596 <p>New format <em>useragent</em> to log with the format previously used by useragent_log directive.
598 <tag>acl : random, urllogin</tag>
599 <p>New type <em>random</em>. Pseudo-randomly match requests based on a configured probability.
600 <p>Ported <em>urllogin</em> option from Squid 2.7, to match a regex pattern on the URL login field (if any).
601 <p>The <em>manager</em> ACL requires adjustment to cover new cache manager access. So it has now been
602 built-in as a predefined ACL name matching URLs equivalent to the following regular expression:
604 ^(cache_object://|https?://[^/]+/squid-internal-mgr/)
606 squid.conf containing the old manager definition can expect to see ACL type collisions.
608 <tag>auth_param</tag>
609 <p>New options for Basic, Digest, NTLM, Negotiate <em>children</em> settings.
610 <em>startup=N</em> determines minimum number of helper processes used.
611 <em>idle=N</em> determines how many helper to retain as buffer against sudden traffic loads.
612 <em>concurrency=N</em> previously called <em>auth_param ... concurrency</em> as a separate option.
613 <p>Removed Basic, Digest, NTLM, Negotiate <em>auth_param ... concurrency</em> setting option.
614 <p>Known Issue: NTLM and Negotiate protocols do not support concurrency. When set this option is ignored.
617 <p><em>min-size</em> option ported from Squid-2
619 <tag>cache_peer</tag>
620 <p><em>htcp-*</em> options collapsed into <em>htcp=</em> taking an optional comma-separated list of flags.
621 The old form is deprecated but still accepted.
623 <tag>cache_store_log</tag>
624 <p>Now uses logging modules. Example: stdio:/file/path
625 see <em>access_log</em> for a list of supported modules and their parameters.
627 <tag>clientside_mark</tag>
628 <p>New configuration parameter <em>clientside_mark</em>
629 <p>Allows packets leaving Squid on the client side to be marked with a Netfilter mark value in the same way as the existing clientside_tos feature.
630 <p>This feature is only available for Netfilter environments.
633 <p>Support URL format tags. For dynamically generated URL in denial redirect.
634 <p>Support the full range of 200-599 HTTP status codes.
635 3xx status only available when redirecting to a URI.
636 Other status only available when supplying an error template body.
638 <tag>external_acl_type</tag>
639 <p>New format tags and option parameters:
640 <p><em>%SRCEUI48</em> EUI-48 / MAC address of client from ARP lookup.
641 <p><em>%SRCEUI64</em> EUI-64 of clients with SLAAC address.
642 <p><em>%EXT_LOG</em> log= message returned by previous external ACL calls. An updated version may be returned.
643 <p><em>%EXT_TAG</em> tag= value returned by previous external ACL calls. Tag may not be altered once set.
644 <p><em>children-max=N</em> determines maximum number of helper processes used.
645 <p><em>children-startup=N</em> determines minimum number of helper processes used.
646 <p><em>children-idle=N</em> determines how many helper to retain as buffer against sudden traffic loads.
647 <p>Deprecated <em>children=N</em> in favor of <em>children-max=N</em>.
649 <tag>http_port act-as-origin vhost no-vhost</tag>
650 <p><em>act-as-origin</em> ported from 2.7.
651 This option corrects several HTTP header issues when operating as a reverse proxy and cache.
652 Notably the externally visible aging of objects stored in the server-side cache.
653 <p><em>vhost</em> is deprecated. <em>accel</em> mode, reverse proxy, now defaults to always enable HTTP/1.1 virtual domain support.
654 <p><em>no-vhost</em> option is added to disable the new reverse proxy behaviour.
656 <tag>icap_send_client_ip</tag>
657 <p>Deprecated in favor of adaptation_send_client_ip
658 which applies to both ICAP and eCAP.</p>
660 <tag>icap_send_client_username</tag>
661 <p>Deprecated in favor of adaptation_send_username
662 which applies to both ICAP and eCAP.</p>
664 <tag>icap_uses_indirect_client</tag>
665 <p>Deprecated in favor of adaptation_uses_indirect_client
666 which applies to both ICAP and eCAP.</p>
669 <p><em>%<a</em> Server or Peer IP address from the last server connection (next hop).
670 <p><em>%>bs</em> Number of HTTP-equivalent message body bytes received from the next hop.
671 <p><em>icap::%>bs</em> Number of message body bytes received from the ICAP server.
672 <p><em>%sn</em> Unique sequence number per log line. Ported from 2.7
673 <p><em>%>eui</em> EUI logging (EUI-48 / MAC address for IPv4, EUI-64 for IPv6).
674 Both EUI forms are logged in the same field. Type can be identified by length or byte delimiter.
675 <p><em>%err_code</em> The ID of an error response served by Squid or a similar internal error identifier
676 <p><em>%err_detail</em> Additional err_code-dependent error information.
677 <p><em>%>la</em> Rename of %la to indicate being a client connection detail.
678 <p><em>%>lp</em> Rename of %lp to indicate being a client connection detail.
679 <p><em>%<p</em> Server or Peer port number from the last server connection (next hop).
681 <tag>memory_pools_limit</tag>
682 <p>Memory limits have been revised and corrected from 3.1.4 onwards.
683 <p>Please check and update your squid.conf to use the text <em>none</em> for no limit instead of the old 0 (zero).
684 <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.
687 <p>New options <em>mark</em> and <em>tos</em> and <em>miss</em>
688 <p><em>tos</em> retains the original QOS functionality of the IP header TOS field.
689 <p><em>mark</em> offers the same functionality, but with a netfilter mark value.
690 <p>These options should be placed immediately after qos_flows.
691 <p>The <em>tos</em> value is optional in order to maintain backwards compatability.
692 <p>The preserve-miss functionality is available with the <em>mark</em> option and requires no kernel patching.
693 It does, however, require libnetfilter_conntrack.
694 This will be included by default if available (see the --without-netfilter-conntrack configure option for more details).
695 <p><em>miss</em> sets a value for a cache miss. It is available for both the tos and mark options and takes precedence over the preserve-miss feature.
697 <tag>range_offset_limit</tag>
698 <p>Added ACL support for control over when the limit applies and when it is avoided.
700 <tag>refresh_pattern</tag>
701 <p>New option <em>max-stale=</em> to provide a maximum staleness factor. Squid won't
702 serve objects more stale than this even if it failed to validate the object.
703 <p>Removed option <em>ignore-no-cache</em>. Its commonly desired behaviour is obsoleted
704 by correct HTTP/1.1 Cache-Control:no-cache handling.
706 <tag>reply_header_access</tag>
707 <p>Added support for custom response header names.</p>
709 <tag>request_header_access</tag>
710 <p>Added support for custom request header names.</p>
712 <tag>reply_header_replace</tag>
713 <p>Added support for custom response header names.</p>
715 <tag>request_header_replace</tag>
716 <p>Added support for custom request header names.</p>
718 <tag>tcp_outgoing_address</tag>
719 <p>This parameter is now compatible with persistent server connections.
720 The IPv6 magic 'to_ipv6' hacks needed in 3.1 are now no longer necessary.
722 <tag>tcp_outgoing_mark</tag>
723 <p>New configuration parameter <em>tcp_outgoing_mark</em>
724 <p>Allows packets leaving Squid on the server side to be marked with a Netfilter mark value in the same way as the existing tcp_outgoing_tos feature.
725 <p>This feature is only available for Netfilter environments.
727 <tag>tcp_outgoing_tos</tag>
728 <p>This parameter is now compatible with persistent server connections.
730 <tag>url_rewrite_children</tag>
731 <p>New options <em>startup=N</em>, <em>idle=N</em>, <em>concurrency=N</em>
733 <item>startup=N allow finer tuning of how many helpers are started initially.
734 <item>idle=N allow fine tuning of how many helper to retain as buffer against sudden traffic loads.
735 <item>concurrency=N was previously called url_rewrite_concurrency as a distinct directive.
738 <tag>windows_ipaddrchangemonitor</tag>
739 <p>Now only available to be set in Windows builds.
744 <sect1>Removed tags<label id="removedtags">
747 <tag>chunked_request_body_max_size</tag>
748 <p>Obsolete. Squid is now HTTP/1.1 with support for streaming chunked encoded requests.
750 <tag>dns_v4_fallback</tag>
751 <p>Obsolete. Replaced by DNS parallel lookups.
753 <tag>emulate_httpd_log</tag>
754 <p>Replaced by <em>common</em> format option on an <em>access_log</em> directive.
756 <tag>forward_log</tag>
759 <tag>ftp_list_width</tag>
762 <tag>ignore_expect_100</tag>
766 <p>Obsolete. Replaced by automatic detection of the %>A logformat tag.
768 <tag>log_ip_on_direct</tag>
769 <p>Obsolete. Use a custom log with <em>%<A</em> format tag to receive server FQDN or peer name.
771 <tag>maximum_single_addr_tries</tag>
772 <p>The behaviour controlled by this directive is no longer possible.
773 It has been replaced by <em>connect_retries</em> option which operates a little differently.
775 <tag>pconn_timeout</tag>
776 <p>Renamed to <em>server_idle_pconn_timeout</em>
778 <tag>persistent_request_timeout</tag>
779 <p>Renamed to <em>client_idle_pconn_timeout</em>
781 <tag>referer_log</tag>
782 <p>Replaced by the <em>referrer</em> format option on an <em>access_log</em> directive.
784 <tag>url_rewrite_concurrency</tag>
785 <p>Replaced by url_rewrite_children ... concurrency=N option.
787 <tag>useragent_log</tag>
788 <p>Replaced by the <em>useragent</em> format option on an <em>access_log</em> directive.
792 <sect>Changes to ./configure options since Squid-3.1
794 There have been some changes to Squid's build configuration since Squid-3.1.
796 This section gives an account of those changes in three categories:
799 <item><ref id="newoptions" name="New options">
800 <item><ref id="modifiedoptions" name="Changes to existing options">
801 <item><ref id="removedoptions" name="Removed options">
805 <sect1>New options<label id="newoptions">
808 <tag>--enable-auth-basic[=HELPERS]</tag>
809 <p>Specified without any parameters all helpers will be auto-built.
810 <p>With an explicit empty list <em>=""</em> protocol support will be built but no helpers.
811 <p>With an explicit list protocol support and just those helpers will be built.
813 <tag>--enable-auth-digest[=HELPERS]</tag>
814 <p>Specified without any parameters all helpers will be auto-built.
815 <p>With an explicit empty list <em>=""</em> protocol support will be built but no helpers.
816 <p>With an explicit list protocol support and just those helpers will be built.
818 <tag>--enable-auth-negotiate</tag>
819 <p>Specified without any parameters all helpers will be auto-built.
820 <p>With an explicit empty list <em>=""</em> protocol support will be built but no helpers.
821 <p>With an explicit list protocol support and just those helpers will be built.
823 <tag>--enable-auth-ntlm</tag>
824 <p>Specified without any parameters all helpers will be auto-built.
825 <p>With an explicit empty list <em>=""</em> protocol support will be built but no helpers.
826 <p>With an explicit list protocol support and just those helpers will be built.
828 <tag>--enable-build-info</tag>
829 <p>Add an additional string in the output of "squid -v".
831 <tag>--enable-eui</tag>
832 <p>Enable Support for handling EUI operations.
833 This includes ARP lookups for MAC (EUI-48) addresses and the ACL arp type tests.
835 <tag>--enable-log-daemon-helpers</tag>
836 <p>Build helpers for logging I/O.
838 <tag>--enable-url-rewrite-helpers</tag>
839 <p>Build helpers for some basic URL-rewrite actions. For use by url_rewrite_program.
840 If omitted or set to =all then all bundled helpers that are able to build will be built.
841 If set to a specific list of helpers then only those helpers will build.
842 Currently one demo helper <em>fake</em> is provided in shell and C++ forms to demonstrate
843 the helper protocol usage and provide exemplar code.
845 <tag>--with-swapdir=PATH</tag>
846 <p>Location to display in documentation for the default cache.
847 Updated to indicate /var/cache/squid in accordance with the filesystem layout standards.
848 Squid-3 no longer builds an implicit disk cache at this location, so the change is not expected
849 to have any effect on existing builds other than fixing some mysterious lack of core dumps.
850 The old /var/cache location was often non-writable which blocked core dumps creation.
852 <tag>--without-netfiler-conntrack</tag>
853 <p>Disables the libnetfilter_conntrack library being used for the new qos_flows option <em>mark</em>.
854 default is to auto-detect the library and use where available.
857 <sect1>Changes to existing options<label id="modifiedoptions">
860 <tag>--enable-auth</tag>
861 <p>No longer takes a list of arguments. This option now is restricted to building Squid with or without authentication support.
862 <p>The new <em>--enable-auth-X</em>/<em>--disable-auth-X</em> parameters determine which authentication protocols and helpers are built.
867 <sect1>Removed options<label id="removedoptions">
870 <tag>--enable-arp-acl</tag>
871 <p>Replaced by --enable-eui
873 <tag>--enable-auth-basic-helpers</tag>
874 <p>Replaced by <em>--enable-auth-basic</em>.
876 <tag>--enable-auth-digest-helpers</tag>
877 <p>Replaced by <em>--enable-auth-digest</em>.
879 <tag>--enable-auth-negotiate-helpers</tag>
880 <p>Replaced by <em>--enable-auth-negotiate</em>.
882 <tag>--enable-auth-ntlm-helpers</tag>
883 <p>Replaced by <em>--enable-auth-ntlm</em>.
885 <tag>--enable-referer-log</tag>
888 <tag>--enable-useragent-log</tag>
894 <sect>Options Removed since Squid-2
896 <p>Some squid.conf and ./configure options which were available in Squid-2.6 and Squid-2.7 are made obsolete in Squid-3.2.
898 <sect1>Removed squid.conf options since Squid-2.7
901 <tag>auth_param</tag>
902 <p><em>blankpassword</em> option for basic scheme removed.
904 <tag>authenticate_ip_shortcircuit_access</tag>
905 <p>Not safe for general use.
906 An external_acl_type helper may be used to bypass authentication if that is suitable.
908 <tag>authenticate_ip_shortcircuit_ttl</tag>
909 <p>Not safe for general use.
910 An external_acl_type helper may be used to bypass authentication if that is suitable.
912 <tag>cache_peer</tag>
913 <p>Option <em>http11</em> obsolete.
915 <tag>external_acl_type</tag>
916 <p>Format tag <em>%{Header}</em> replaced by <em>%>{Header}</em>
917 <p>Format tag <em>%{Header:member}</em> replaced by <em>%>{Header:member}</em>
919 <tag>header_access</tag>
920 <p>Replaced by <em>request_header_access</em> and <em>reply_header_access</em>
923 <p>Option <em>no-connection-auth</em> replaced by <em>connection-auth=[on|off]</em>. Default is ON.
924 <p>Option <em>transparent</em> option replaced by <em>intercept</em>
925 <p>Option <em>http11</em> obsolete.
927 <tag>http_access2</tag>
928 <p>Replaced by <em>adapted_http_access</em>
930 <tag>httpd_accel_no_pmtu_disc</tag>
931 <p>Replaced by <em>http_port disable-pmtu-discovery=</em> option
933 <tag>incoming_rate</tag>
936 <tag>redirector_bypass</tag>
937 <p>Replaced by <em>url_rewrite_bypass</em>
939 <tag>server_http11</tag>
942 <tag>update_headers</tag>
943 <p>Obsolete. The experimental actions enabled in 2.7 by this option have been integrated as default
944 actions for the <em>rock</em> storage type and memory caches.
945 The configuration option is no longer necessary and has been dropped.
946 NOTE: It is not yet supported by <em>ufs</em>, <em>aufs</em>, or <em>diskd</em> storage.
948 <tag>upgrade_http0.9</tag>
952 <p>Replaced by <em>qos_flows local-hit=</em>
957 <tag>zph_option</tag>
960 <tag>zph_parent</tag>
961 <p>Replaced by <em>qos_flows parent-hit=</em>
963 <tag>zph_sibling</tag>
964 <p>Replaced by <em>qos_flows sibling-hit=</em>
968 <sect1>Removed squid.conf options since Squid-2.6
972 <p><em>urlgroup</em> type removed. Use <em>myportname</em> type instead.
975 <p><em>read-only</em> option replaced by <em>no-store</em>.
978 <p><em>urlgroup=</em> removed. Use <em>name=</em> feature instead.
980 <tag>zero_buffers</tag>
981 <p>Replaced by native support.
985 <sect1>Removed ./configure options since Squid-2.7
988 <tag>--enable-coss-aio-ops</tag>
991 <tag>--enable-devpoll</tag>
992 <p>Replaced by automatic detection.
994 <tag>--enable-dlmalloc=LIB</tag>
997 <tag>--enable-epoll</tag>
998 <p>Replaced by automatic detection.
1000 <tag>--enable-forward-log</tag>
1003 <tag>--enable-heap-replacement</tag>
1006 <tag>--enable-htcp</tag>
1007 <p>Obsolete. Enabled by default.
1009 <tag>--enable-large-cache-files</tag>
1012 <tag>--enable-mempool-debug</tag>
1015 <tag>--enable-multicast-miss</tag>
1018 <tag>--enable-poll</tag>
1019 <p>Replaced by automatic detection.
1021 <tag>--enable-select</tag>
1022 <p>Replaced by automatic detection.
1024 <tag>--enable-select-simple</tag>
1025 <p>Replaced by automatic detection.
1027 <tag>--enable-snmp</tag>
1028 <p>Obsolete. Enabled by default.
1030 <tag>--enable-truncate</tag>
1033 <tag>--disable-kqueue</tag>
1034 <p>Obsolete. Disabled by default.
1036 <tag>--without-system-md5</tag>
1037 <p>Obsolete. Disabled by default.
1042 <sect>Regressions since Squid-2.7
1044 <p>Some squid.conf and ./configure options which were available in Squid-2.7 are not yet available in Squid-3.2
1046 <p>If you need something to do then porting one of these from Squid-2 to Squid-3 is most welcome.
1048 <sect1>Missing squid.conf options available in Squid-2.7
1051 <tag>broken_vary_encoding</tag>
1052 <p>Not yet ported from 2.6
1054 <tag>cache_dir</tag>
1055 <p><em>COSS</em> storage type is lacking stability fixes from 2.6
1056 <p>COSS <em>overwrite-percent=</em> option not yet ported from 2.6
1057 <p>COSS <em>max-stripe-waste=</em> option not yet ported from 2.6
1058 <p>COSS <em>membufs=</em> option not yet ported from 2.6
1059 <p>COSS <em>maxfullbufs=</em> option not yet ported from 2.6
1061 <tag>cache_peer</tag>
1062 <p><em>idle=</em> not yet ported from 2.7
1063 <p><em>monitorinterval=</em> not yet ported from 2.6
1064 <p><em>monitorsize=</em> not yet ported from 2.6
1065 <p><em>monitortimeout=</em> not yet ported from 2.6
1066 <p><em>monitorurl=</em> not yet ported from 2.6
1068 <tag>cache_vary</tag>
1069 <p>Not yet ported from 2.6
1071 <tag>collapsed_forwarding</tag>
1072 <p>Not yet ported from 2.6
1074 <tag>error_map</tag>
1075 <p>Not yet ported from 2.6
1077 <tag>external_acl_type</tag>
1078 <p><em>%ACL</em> format tag not yet ported from 2.6
1079 <p><em>%DATA</em> format tag not yet ported from 2.6
1081 <tag>external_refresh_check</tag>
1082 <p>Not yet ported from 2.7
1084 <tag>ignore_ims_on_miss</tag>
1085 <p>Not yet ported from 2.7
1087 <tag>location_rewrite_access</tag>
1088 <p>Not yet ported from 2.6
1090 <tag>location_rewrite_children</tag>
1091 <p>Not yet ported from 2.6
1093 <tag>location_rewrite_concurrency</tag>
1094 <p>Not yet ported from 2.6
1096 <tag>location_rewrite_program</tag>
1097 <p>Not yet ported from 2.6
1099 <tag>refresh_pattern</tag>
1100 <p><em>stale-while-revalidate=</em> not yet ported from 2.7
1101 <p><em>ignore-stale-while-revalidate=</em> not yet ported from 2.7
1102 <p><em>negative-ttl=</em> not yet ported from 2.7
1104 <tag>refresh_stale_hit</tag>
1105 <p>Not yet ported from 2.7
1107 <tag>storeurl_access</tag>
1108 <p>Not yet ported from 2.7
1110 <tag>storeurl_rewrite_children</tag>
1111 <p>Not yet ported from 2.7
1113 <tag>storeurl_rewrite_concurrency</tag>
1114 <p>Not yet ported from 2.7
1116 <tag>storeurl_rewrite_program</tag>
1117 <p>Not yet ported from 2.7
1123 Copyright (C) 1996-2016 The Squid Software Foundation and contributors
1125 Squid software is distributed under GPLv2+ license and includes
1126 contributions from numerous individuals and organizations.
1127 Please see the COPYING and CONTRIBUTORS files for details.