]> git.ipfire.org Git - thirdparty/squid.git/blame - src/cf.data.pre
Polished names, comments, and code formatting.
[thirdparty/squid.git] / src / cf.data.pre
CommitLineData
9cef6668 1#
6845f129 2# SQUID Web Proxy Cache http://www.squid-cache.org/
9cef6668 3# ----------------------------------------------------------
4#
2b6662ba 5# Squid is the result of efforts by numerous individuals from
6# the Internet community; see the CONTRIBUTORS file for full
7# details. Many organizations have provided support for Squid's
8# development; see the SPONSORS file for full details. Squid is
9# Copyrighted (C) 2000 by the Regents of the University of
10# California; see the COPYRIGHT file for full details. Squid
11# incorporates software developed and/or copyrighted by other
12# sources; see the CREDITS file for full details.
9cef6668 13#
14# This program is free software; you can redistribute it and/or modify
15# it under the terms of the GNU General Public License as published by
16# the Free Software Foundation; either version 2 of the License, or
17# (at your option) any later version.
96d88dcb 18#
9cef6668 19# This program is distributed in the hope that it will be useful,
20# but WITHOUT ANY WARRANTY; without even the implied warranty of
21# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22# GNU General Public License for more details.
96d88dcb 23#
9cef6668 24# You should have received a copy of the GNU General Public License
25# along with this program; if not, write to the Free Software
26# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
27#
28
0f74202c 29COMMENT_START
ad12fb4b 30 WELCOME TO @SQUID@
cccac0a2 31 ----------------------------
5945964d
AJ
32
33 This is the documentation for the Squid configuration file.
34 This documentation can also be found online at:
35 http://www.squid-cache.org/Doc/config/
36
37 You may wish to look at the Squid home page and wiki for the
38 FAQ and other documentation:
39 http://www.squid-cache.org/
40 http://wiki.squid-cache.org/SquidFaq
41 http://wiki.squid-cache.org/ConfigExamples
42
43 This documentation shows what the defaults for various directives
44 happen to be. If you don't need to change the default, you should
45 leave the line out of your squid.conf in most cases.
46
47 In some cases "none" refers to no default setting at all,
48 while in other cases it refers to the value of the option
49 - the comments for that keyword indicate if this is the case.
debd9a31 50
cccac0a2 51COMMENT_END
3a278cb8 52
592a09dc 53COMMENT_START
54 Configuration options can be included using the "include" directive.
5945964d 55 Include takes a list of files to include. Quoting and wildcards are
592a09dc 56 supported.
57
58 For example,
59
60 include /path/to/included/file/squid.acl.config
61
62 Includes can be nested up to a hard-coded depth of 16 levels.
63 This arbitrary restriction is to prevent recursive include references
64 from causing Squid entering an infinite loop whilst trying to load
65 configuration files.
d4a3e179
AR
66
67
5735d30b
AR
68 Conditional configuration
69
70 If-statements can be used to make configuration directives
71 depend on conditions:
72
73 if <CONDITION>
74 ... regular configuration directives ...
75 [else
76 ... regular configuration directives ...]
77 endif
78
79 The else part is optional. The keywords "if", "else", and "endif"
80 must be typed on their own lines, as if they were regular
81 configuration directives.
82
5945964d
AJ
83 NOTE: An else-if condition is not supported.
84
5735d30b
AR
85 These individual conditions types are supported:
86
87 true
88 Always evaluates to true.
89 false
90 Always evaluates to false.
91 <integer> = <integer>
92 Equality comparison of two integer numbers.
93
94
d4a3e179
AR
95 SMP-Related Macros
96
97 The following SMP-related preprocessor macros can be used.
98
99 ${process_name} expands to the current Squid process "name"
100 (e.g., squid1, squid2, or cache1).
101
102 ${process_number} expands to the current Squid process
103 identifier, which is an integer number (e.g., 1, 2, 3) unique
104 across all Squid processes.
592a09dc 105COMMENT_END
106
76f44481
AJ
107# Options Removed in 3.2
108NAME: ignore_expect_100
109TYPE: obsolete
110DOC_START
111 Remove this line. The HTTP/1.1 feature is now fully supported by default.
112DOC_END
113
6e095b46
AJ
114NAME: dns_v4_fallback
115TYPE: obsolete
116DOC_START
117 Remove this line.
118DOC_END
119
76f44481
AJ
120NAME: ftp_list_width
121TYPE: obsolete
122DOC_START
123 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
124DOC_END
125
126NAME: url_rewrite_concurrency
127TYPE: obsolete
128DOC_START
129 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead.
130DOC_END
131
132# Options Removed in 3.1
133NAME: dns_testnames
134TYPE: obsolete
135DOC_START
136 Remove this line. DNS is no longer tested on startup.
137DOC_END
138
139NAME: extension_methods
140TYPE: obsolete
141DOC_START
142 Remove this line. All valid methods for HTTP are accepted by default.
143DOC_END
144
145# 2.7 Options Removed/Replaced in 3.1
146NAME: incoming_rate
147TYPE: obsolete
148DOC_NONE
149
150NAME: server_http11
151TYPE: obsolete
152DOC_START
153 Remove this line. HTTP/1.1 is supported by default.
154DOC_END
155
156NAME: upgrade_http0.9
157TYPE: obsolete
158DOC_START
159 Remove this line. ICY/1.0 streaming protocol is supported by default.
160DOC_END
161
162NAME: zph_local zph_mode zph_option zph_parent zph_sibling
163TYPE: obsolete
164DOC_START
165 Alter these entries. Use the qos_flows directive instead.
166DOC_END
167
168# Options Removed in 3.0
169NAME: header_access
170TYPE: obsolete
171DOC_START
172 Since squid-3.0 replace with request_header_access or reply_header_access
173 depending on whether you wish to match client requests or server replies.
174DOC_END
175
176NAME: httpd_accel_no_pmtu_disc
177TYPE: obsolete
178DOC_START
179 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
180DOC_END
181
5473c134 182COMMENT_START
41bd17a4 183 OPTIONS FOR AUTHENTICATION
5473c134 184 -----------------------------------------------------------------------------
185COMMENT_END
186
41bd17a4 187NAME: auth_param
188TYPE: authparam
2f1431ea 189IFDEF: USE_AUTH
5817ee13 190LOC: Auth::TheConfig
cccac0a2 191DEFAULT: none
192DOC_START
41bd17a4 193 This is used to define parameters for the various authentication
194 schemes supported by Squid.
cccac0a2 195
41bd17a4 196 format: auth_param scheme parameter [setting]
cccac0a2 197
41bd17a4 198 The order in which authentication schemes are presented to the client is
199 dependent on the order the scheme first appears in config file. IE
200 has a bug (it's not RFC 2617 compliant) in that it will use the basic
201 scheme if basic is the first entry presented, even if more secure
202 schemes are presented. For now use the order in the recommended
203 settings section below. If other browsers have difficulties (don't
204 recognize the schemes offered even if you are using basic) either
205 put basic first, or disable the other schemes (by commenting out their
206 program entry).
cccac0a2 207
41bd17a4 208 Once an authentication scheme is fully configured, it can only be
209 shutdown by shutting squid down and restarting. Changes can be made on
210 the fly and activated with a reconfigure. I.E. You can change to a
211 different helper, but not unconfigure the helper completely.
cccac0a2 212
41bd17a4 213 Please note that while this directive defines how Squid processes
214 authentication it does not automatically activate authentication.
215 To use authentication you must in addition make use of ACLs based
216 on login name in http_access (proxy_auth, proxy_auth_regex or
217 external with %LOGIN used in the format tag). The browser will be
218 challenged for authentication on the first such acl encountered
219 in http_access processing and will also be re-challenged for new
220 login credentials if the request is being denied by a proxy_auth
221 type acl.
cccac0a2 222
41bd17a4 223 WARNING: authentication can't be used in a transparently intercepting
224 proxy as the client then thinks it is talking to an origin server and
225 not the proxy. This is a limitation of bending the TCP/IP protocol to
226 transparently intercepting port 80, not a limitation in Squid.
b3567eb5
FC
227 Ports flagged 'transparent', 'intercept', or 'tproxy' have
228 authentication disabled.
cccac0a2 229
41bd17a4 230 === Parameters for the basic scheme follow. ===
cccac0a2 231
41bd17a4 232 "program" cmdline
233 Specify the command for the external authenticator. Such a program
234 reads a line containing "username password" and replies "OK" or
235 "ERR" in an endless loop. "ERR" responses may optionally be followed
236 by a error description available as %m in the returned error page.
b3567eb5
FC
237 If you use an authenticator, make sure you have 1 acl of type
238 proxy_auth.
cccac0a2 239
41bd17a4 240 By default, the basic authentication scheme is not used unless a
241 program is specified.
cccac0a2 242
41bd17a4 243 If you want to use the traditional NCSA proxy authentication, set
244 this line to something like
307b83b7 245
41bd17a4 246 auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
9e7dbc51 247
d2a89ac1
AJ
248 "utf8" on|off
249 HTTP uses iso-latin-1 as characterset, while some authentication
250 backends such as LDAP expects UTF-8. If this is set to on Squid will
251 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
252 username & password to the helper.
253
7353861b 254 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
48d54e4d 255 The maximum number of authenticator processes to spawn. If you start too few
41bd17a4 256 Squid will have to wait for them to process a backlog of credential
257 verifications, slowing it down. When password verifications are
258 done via a (slow) network you are likely to need lots of
259 authenticator processes.
48d54e4d
AJ
260
261 The startup= and idle= options permit some skew in the exact amount
64d2327b
AJ
262 run. A minimum of startup=N will begin during startup and reconfigure.
263 Squid will start more in groups of up to idle=N in an attempt to meet
48d54e4d
AJ
264 traffic needs and to keep idle=N free above those traffic needs up to
265 the maximum.
266
7353861b
HN
267 The concurrency= option sets the number of concurrent requests the
268 helper can process. The default of 0 is used for helpers who only
269 supports one request at a time. Setting this to a number greater than
270 0 changes the protocol used to include a channel number first on the
271 request/response line, allowing multiple requests to be sent to the
272 same helper in parallell without wating for the response.
41bd17a4 273 Must not be set unless it's known the helper supports this.
7353861b
HN
274
275 auth_param basic children 20 startup=0 idle=1
0fdafae7 276
41bd17a4 277 "realm" realmstring
278 Specifies the realm name which is to be reported to the
279 client for the basic proxy authentication scheme (part of
280 the text the user will see when prompted their username and
281 password). There is no default.
282 auth_param basic realm Squid proxy-caching web server
d1b63fc8 283
41bd17a4 284 "credentialsttl" timetolive
285 Specifies how long squid assumes an externally validated
286 username:password pair is valid for - in other words how
287 often the helper program is called for that user. Set this
288 low to force revalidation with short lived passwords. Note
289 setting this high does not impact your susceptibility
290 to replay attacks unless you are using an one-time password
291 system (such as SecureID). If you are using such a system,
292 you will be vulnerable to replay attacks unless you also
293 use the max_user_ip ACL in an http_access rule.
cccac0a2 294
41bd17a4 295 "casesensitive" on|off
296 Specifies if usernames are case sensitive. Most user databases are
297 case insensitive allowing the same username to be spelled using both
298 lower and upper case letters, but some are case sensitive. This
299 makes a big difference for user_max_ip ACL processing and similar.
300 auth_param basic casesensitive off
cccac0a2 301
41bd17a4 302 === Parameters for the digest scheme follow ===
cccac0a2 303
41bd17a4 304 "program" cmdline
305 Specify the command for the external authenticator. Such
306 a program reads a line containing "username":"realm" and
307 replies with the appropriate H(A1) value hex encoded or
308 ERR if the user (or his H(A1) hash) does not exists.
309 See rfc 2616 for the definition of H(A1).
310 "ERR" responses may optionally be followed by a error description
311 available as %m in the returned error page.
cccac0a2 312
41bd17a4 313 By default, the digest authentication scheme is not used unless a
314 program is specified.
b8c0c06d 315
41bd17a4 316 If you want to use a digest authenticator, set this line to
317 something like
cccac0a2 318
7ce93108 319 auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass
cccac0a2 320
d2a89ac1
AJ
321 "utf8" on|off
322 HTTP uses iso-latin-1 as characterset, while some authentication
323 backends such as LDAP expects UTF-8. If this is set to on Squid will
324 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
325 username & password to the helper.
326
7353861b 327 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
48d54e4d 328 The maximum number of authenticator processes to spawn (default 5).
41bd17a4 329 If you start too few Squid will have to wait for them to
330 process a backlog of H(A1) calculations, slowing it down.
331 When the H(A1) calculations are done via a (slow) network
332 you are likely to need lots of authenticator processes.
48d54e4d
AJ
333
334 The startup= and idle= options permit some skew in the exact amount
64d2327b
AJ
335 run. A minimum of startup=N will begin during startup and reconfigure.
336 Squid will start more in groups of up to idle=N in an attempt to meet
48d54e4d
AJ
337 traffic needs and to keep idle=N free above those traffic needs up to
338 the maximum.
339
7353861b
HN
340 The concurrency= option sets the number of concurrent requests the
341 helper can process. The default of 0 is used for helpers who only
342 supports one request at a time. Setting this to a number greater than
343 0 changes the protocol used to include a channel number first on the
344 request/response line, allowing multiple requests to be sent to the
345 same helper in parallell without wating for the response.
346 Must not be set unless it's known the helper supports this.
347
48d54e4d 348 auth_param digest children 20 startup=0 idle=1
cccac0a2 349
41bd17a4 350 "realm" realmstring
351 Specifies the realm name which is to be reported to the
352 client for the digest proxy authentication scheme (part of
353 the text the user will see when prompted their username and
354 password). There is no default.
355 auth_param digest realm Squid proxy-caching web server
cccac0a2 356
41bd17a4 357 "nonce_garbage_interval" timeinterval
358 Specifies the interval that nonces that have been issued
359 to client_agent's are checked for validity.
cccac0a2 360
41bd17a4 361 "nonce_max_duration" timeinterval
362 Specifies the maximum length of time a given nonce will be
363 valid for.
cccac0a2 364
41bd17a4 365 "nonce_max_count" number
366 Specifies the maximum number of times a given nonce can be
367 used.
cccac0a2 368
41bd17a4 369 "nonce_strictness" on|off
370 Determines if squid requires strict increment-by-1 behavior
371 for nonce counts, or just incrementing (off - for use when
372 useragents generate nonce counts that occasionally miss 1
373 (ie, 1,2,4,6)). Default off.
cccac0a2 374
41bd17a4 375 "check_nonce_count" on|off
376 This directive if set to off can disable the nonce count check
377 completely to work around buggy digest qop implementations in
378 certain mainstream browser versions. Default on to check the
379 nonce count to protect from authentication replay attacks.
cccac0a2 380
41bd17a4 381 "post_workaround" on|off
382 This is a workaround to certain buggy browsers who sends
383 an incorrect request digest in POST requests when reusing
384 the same nonce as acquired earlier on a GET request.
cccac0a2 385
41bd17a4 386 === NTLM scheme options follow ===
cccac0a2 387
41bd17a4 388 "program" cmdline
389 Specify the command for the external NTLM authenticator.
390 Such a program reads exchanged NTLMSSP packets with
391 the browser via Squid until authentication is completed.
392 If you use an NTLM authenticator, make sure you have 1 acl
393 of type proxy_auth. By default, the NTLM authenticator_program
394 is not used.
cccac0a2 395
41bd17a4 396 auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
cccac0a2 397
48d54e4d
AJ
398 "children" numberofchildren [startup=N] [idle=N]
399 The maximum number of authenticator processes to spawn (default 5).
41bd17a4 400 If you start too few Squid will have to wait for them to
401 process a backlog of credential verifications, slowing it
402 down. When credential verifications are done via a (slow)
403 network you are likely to need lots of authenticator
404 processes.
cccac0a2 405
48d54e4d 406 The startup= and idle= options permit some skew in the exact amount
64d2327b
AJ
407 run. A minimum of startup=N will begin during startup and reconfigure.
408 Squid will start more in groups of up to idle=N in an attempt to meet
48d54e4d
AJ
409 traffic needs and to keep idle=N free above those traffic needs up to
410 the maximum.
411
412 auth_param ntlm children 20 startup=0 idle=1
cccac0a2 413
41bd17a4 414 "keep_alive" on|off
415 If you experience problems with PUT/POST requests when using the
416 Negotiate authentication scheme then you can try setting this to
417 off. This will cause Squid to forcibly close the connection on
418 the initial requests where the browser asks which schemes are
419 supported by the proxy.
cccac0a2 420
41bd17a4 421 auth_param ntlm keep_alive on
cccac0a2 422
41bd17a4 423 === Options for configuring the NEGOTIATE auth-scheme follow ===
cccac0a2 424
41bd17a4 425 "program" cmdline
426 Specify the command for the external Negotiate authenticator.
427 This protocol is used in Microsoft Active-Directory enabled setups with
428 the Microsoft Internet Explorer or Mozilla Firefox browsers.
429 Its main purpose is to exchange credentials with the Squid proxy
430 using the Kerberos mechanisms.
b3567eb5
FC
431 If you use a Negotiate authenticator, make sure you have at least
432 one acl of type proxy_auth active. By default, the negotiate
433 authenticator_program is not used.
41bd17a4 434 The only supported program for this role is the ntlm_auth
435 program distributed as part of Samba, version 4 or later.
cccac0a2 436
41bd17a4 437 auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
cccac0a2 438
48d54e4d
AJ
439 "children" numberofchildren [startup=N] [idle=N]
440 The maximum number of authenticator processes to spawn (default 5).
41bd17a4 441 If you start too few Squid will have to wait for them to
442 process a backlog of credential verifications, slowing it
443 down. When crendential verifications are done via a (slow)
444 network you are likely to need lots of authenticator
445 processes.
48d54e4d
AJ
446
447 The startup= and idle= options permit some skew in the exact amount
64d2327b
AJ
448 run. A minimum of startup=N will begin during startup and reconfigure.
449 Squid will start more in groups of up to idle=N in an attempt to meet
48d54e4d
AJ
450 traffic needs and to keep idle=N free above those traffic needs up to
451 the maximum.
452
453 auth_param negotiate children 20 startup=0 idle=1
d3803853 454
41bd17a4 455 "keep_alive" on|off
456 If you experience problems with PUT/POST requests when using the
457 Negotiate authentication scheme then you can try setting this to
458 off. This will cause Squid to forcibly close the connection on
459 the initial requests where the browser asks which schemes are
460 supported by the proxy.
527ee50d 461
41bd17a4 462 auth_param negotiate keep_alive on
cccac0a2 463
e0855596
AJ
464
465 Examples:
466
41bd17a4 467#Recommended minimum configuration per scheme:
468#auth_param negotiate program <uncomment and complete this line to activate>
48d54e4d 469#auth_param negotiate children 20 startup=0 idle=1
41bd17a4 470#auth_param negotiate keep_alive on
e0855596 471#
41bd17a4 472#auth_param ntlm program <uncomment and complete this line to activate>
48d54e4d 473#auth_param ntlm children 20 startup=0 idle=1
41bd17a4 474#auth_param ntlm keep_alive on
e0855596 475#
41bd17a4 476#auth_param digest program <uncomment and complete this line>
48d54e4d 477#auth_param digest children 20 startup=0 idle=1
41bd17a4 478#auth_param digest realm Squid proxy-caching web server
479#auth_param digest nonce_garbage_interval 5 minutes
480#auth_param digest nonce_max_duration 30 minutes
481#auth_param digest nonce_max_count 50
e0855596 482#
41bd17a4 483#auth_param basic program <uncomment and complete this line>
6f4d3ed6 484#auth_param basic children 5 startup=5 idle=1
41bd17a4 485#auth_param basic realm Squid proxy-caching web server
486#auth_param basic credentialsttl 2 hours
41bd17a4 487DOC_END
cccac0a2 488
41bd17a4 489NAME: authenticate_cache_garbage_interval
490TYPE: time_t
491DEFAULT: 1 hour
492LOC: Config.authenticateGCInterval
493DOC_START
494 The time period between garbage collection across the username cache.
495 This is a tradeoff between memory utilization (long intervals - say
496 2 days) and CPU (short intervals - say 1 minute). Only change if you
497 have good reason to.
498DOC_END
cccac0a2 499
41bd17a4 500NAME: authenticate_ttl
501TYPE: time_t
502DEFAULT: 1 hour
503LOC: Config.authenticateTTL
504DOC_START
505 The time a user & their credentials stay in the logged in
506 user cache since their last request. When the garbage
507 interval passes, all user credentials that have passed their
508 TTL are removed from memory.
509DOC_END
cccac0a2 510
41bd17a4 511NAME: authenticate_ip_ttl
512TYPE: time_t
513LOC: Config.authenticateIpTTL
514DEFAULT: 0 seconds
515DOC_START
516 If you use proxy authentication and the 'max_user_ip' ACL,
517 this directive controls how long Squid remembers the IP
518 addresses associated with each user. Use a small value
519 (e.g., 60 seconds) if your users might change addresses
520 quickly, as is the case with dialups. You might be safe
521 using a larger value (e.g., 2 hours) in a corporate LAN
522 environment with relatively static address assignments.
523DOC_END
cccac0a2 524
3d1e3e43 525COMMENT_START
526 ACCESS CONTROLS
527 -----------------------------------------------------------------------------
528COMMENT_END
529
41bd17a4 530NAME: external_acl_type
531TYPE: externalAclHelper
532LOC: Config.externalAclHelperList
cccac0a2 533DEFAULT: none
cccac0a2 534DOC_START
41bd17a4 535 This option defines external acl classes using a helper program
536 to look up the status
cccac0a2 537
41bd17a4 538 external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
cccac0a2 539
41bd17a4 540 Options:
cccac0a2 541
41bd17a4 542 ttl=n TTL in seconds for cached results (defaults to 3600
543 for 1 hour)
544 negative_ttl=n
545 TTL for cached negative lookups (default same
546 as ttl)
48d54e4d
AJ
547 children-max=n
548 Maximum number of acl helper processes spawned to service
549 external acl lookups of this type. (default 20)
550 children-startup=n
551 Minimum number of acl helper processes to spawn during
552 startup and reconfigure to service external acl lookups
553 of this type. (default 0)
554 children-idle=n
555 Number of acl helper processes to keep ahead of traffic
556 loads. Squid will spawn this many at once whenever load
557 rises above the capabilities of existing processes.
558 Up to the value of children-max. (default 1)
41bd17a4 559 concurrency=n concurrency level per process. Only used with helpers
560 capable of processing more than one query at a time.
48d54e4d 561 cache=n limit the result cache size, default is unbounded.
41bd17a4 562 grace=n Percentage remaining of TTL where a refresh of a
563 cached entry should be initiated without needing to
48d54e4d 564 wait for a new reply. (default is for no grace period)
41bd17a4 565 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
91e64de9
AJ
566 ipv4 / ipv6 IP protocol used to communicate with this helper.
567 The default is to auto-detect IPv6 and use it when available.
cccac0a2 568
41bd17a4 569 FORMAT specifications
cccac0a2 570
41bd17a4 571 %LOGIN Authenticated user login name
99e4ad67
JB
572 %EXT_USER Username from previous external acl
573 %EXT_LOG Log details from previous external acl
574 %EXT_TAG Tag from previous external acl
41bd17a4 575 %IDENT Ident user name
576 %SRC Client IP
577 %SRCPORT Client source port
578 %URI Requested URI
579 %DST Requested host
580 %PROTO Requested protocol
581 %PORT Requested port
582 %PATH Requested URL path
583 %METHOD Request method
584 %MYADDR Squid interface address
585 %MYPORT Squid http_port number
586 %PATH Requested URL-path (including query-string if any)
587 %USER_CERT SSL User certificate in PEM format
588 %USER_CERTCHAIN SSL User certificate chain in PEM format
589 %USER_CERT_xx SSL User certificate subject attribute xx
590 %USER_CA_xx SSL User certificate issuer attribute xx
7b0ca1e8 591
c68c9682 592 %>{Header} HTTP request header "Header"
7b0ca1e8 593 %>{Hdr:member}
c68c9682 594 HTTP request header "Hdr" list member "member"
7b0ca1e8 595 %>{Hdr:;member}
41bd17a4 596 HTTP request header list member using ; as
597 list separator. ; can be any non-alphanumeric
598 character.
cccac0a2 599
c68c9682 600 %<{Header} HTTP reply header "Header"
7b0ca1e8 601 %<{Hdr:member}
c68c9682 602 HTTP reply header "Hdr" list member "member"
7b0ca1e8
AJ
603 %<{Hdr:;member}
604 HTTP reply header list member using ; as
605 list separator. ; can be any non-alphanumeric
606 character.
607
0db8942f
AJ
608 %% The percent sign. Useful for helpers which need
609 an unchanging input format.
610
41bd17a4 611 In addition to the above, any string specified in the referencing
612 acl will also be included in the helper request line, after the
613 specified formats (see the "acl external" directive)
cccac0a2 614
41bd17a4 615 The helper receives lines per the above format specification,
616 and returns lines starting with OK or ERR indicating the validity
617 of the request and optionally followed by additional keywords with
618 more details.
cccac0a2 619
41bd17a4 620 General result syntax:
cccac0a2 621
41bd17a4 622 OK/ERR keyword=value ...
cccac0a2 623
41bd17a4 624 Defined keywords:
cccac0a2 625
41bd17a4 626 user= The users name (login)
627 password= The users password (for login= cache_peer option)
628 message= Message describing the reason. Available as %o
629 in error pages
630 tag= Apply a tag to a request (for both ERR and OK results)
631 Only sets a tag, does not alter existing tags.
632 log= String to be logged in access.log. Available as
633 %ea in logformat specifications
934b03fc 634
41bd17a4 635 If protocol=3.0 (the default) then URL escaping is used to protect
636 each value in both requests and responses.
6a566b9c 637
41bd17a4 638 If using protocol=2.5 then all values need to be enclosed in quotes
639 if they may contain whitespace, or the whitespace escaped using \.
640 And quotes or \ characters within the keyword value must be \ escaped.
1e5562e3 641
41bd17a4 642 When using the concurrency= option the protocol is changed by
643 introducing a query channel tag infront of the request/response.
644 The query channel tag is a number between 0 and concurrency-1.
cccac0a2 645DOC_END
646
41bd17a4 647NAME: acl
648TYPE: acl
649LOC: Config.aclList
cf1c09f6
CT
650IFDEF USE_SSL
651DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED
652DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID
653DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH
654DEFAULT: ssl::certUntrusted ssl_error X509_V_ERR_INVALID_CA X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY X509_V_ERR_CERT_UNTRUSTED
655DEFAULT: ssl::certSelfSigned ssl_error X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
656ENDIF
1f5bd0a4 657DEFAULT: all src all
b8a25eaa
AJ
658DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
659DEFAULT: localhost src 127.0.0.1/32 ::1
660DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
661DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
cccac0a2 662DOC_START
41bd17a4 663 Defining an Access List
cccac0a2 664
375eeb3b
AJ
665 Every access list definition must begin with an aclname and acltype,
666 followed by either type-specific arguments or a quoted filename that
667 they are read from.
cccac0a2 668
375eeb3b
AJ
669 acl aclname acltype argument ...
670 acl aclname acltype "file" ...
cccac0a2 671
375eeb3b 672 When using "file", the file should contain one item per line.
cccac0a2 673
ae315d9c
AJ
674 By default, regular expressions are CASE-SENSITIVE.
675 To make them case-insensitive, use the -i option. To return case-sensitive
676 use the +i option between patterns, or make a new ACL line without -i.
cccac0a2 677
b3567eb5
FC
678 Some acl types require suspending the current request in order
679 to access some external data source.
680 Those which do are marked with the tag [slow], those which
681 don't are marked as [fast].
682 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
683 for further information
e988aa40
AJ
684
685 ***** ACL TYPES AVAILABLE *****
686
1e40905d
AJ
687 acl aclname src ip-address/mask ... # clients IP address [fast]
688 acl aclname src addr1-addr2/mask ... # range of addresses [fast]
689 acl aclname dst ip-address/mask ... # URL host's IP address [slow]
690 acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
cccac0a2 691
41bd17a4 692 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
693 # The arp ACL requires the special configure option --enable-arp-acl.
694 # Furthermore, the ARP ACL code is not portable to all operating systems.
b3567eb5
FC
695 # It works on Linux, Solaris, Windows, FreeBSD, and some
696 # other *BSD variants.
697 # [fast]
41bd17a4 698 #
699 # NOTE: Squid can only determine the MAC address for clients that are on
b3567eb5
FC
700 # the same subnet. If the client is on a different subnet,
701 # then Squid cannot find out its MAC address.
702
703 acl aclname srcdomain .foo.com ...
704 # reverse lookup, from client IP [slow]
705 acl aclname dstdomain .foo.com ...
e38c7724 706 # Destination server from URL [fast]
b3567eb5
FC
707 acl aclname srcdom_regex [-i] \.foo\.com ...
708 # regex matching client name [slow]
709 acl aclname dstdom_regex [-i] \.foo\.com ...
e38c7724 710 # regex matching server [fast]
b3567eb5 711 #
41bd17a4 712 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
713 # based URL is used and no match is found. The name "none" is used
714 # if the reverse lookup fails.
9bc73deb 715
375eeb3b
AJ
716 acl aclname src_as number ...
717 acl aclname dst_as number ...
b3567eb5 718 # [fast]
e988aa40
AJ
719 # Except for access control, AS numbers can be used for
720 # routing of requests to specific caches. Here's an
721 # example for routing all requests for AS#1241 and only
722 # those to mycache.mydomain.net:
723 # acl asexample dst_as 1241
724 # cache_peer_access mycache.mydomain.net allow asexample
725 # cache_peer_access mycache_mydomain.net deny all
7f7db318 726
6db78a1a 727 acl aclname peername myPeer ...
b3567eb5 728 # [fast]
6db78a1a
AJ
729 # match against a named cache_peer entry
730 # set unique name= on cache_peer lines for reliable use.
731
375eeb3b 732 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
b3567eb5 733 # [fast]
375eeb3b
AJ
734 # day-abbrevs:
735 # S - Sunday
736 # M - Monday
737 # T - Tuesday
738 # W - Wednesday
739 # H - Thursday
740 # F - Friday
741 # A - Saturday
742 # h1:m1 must be less than h2:m2
743
b3567eb5
FC
744 acl aclname url_regex [-i] ^http:// ...
745 # regex matching on whole URL [fast]
746 acl aclname urlpath_regex [-i] \.gif$ ...
747 # regex matching on URL path [fast]
e988aa40 748
b3567eb5
FC
749 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
750 # ranges are alloed
1e40905d
AJ
751 acl aclname localport 3128 ... # TCP port the client connected to [fast]
752 # NP: for interception mode this is usually '80'
753
b3567eb5 754 acl aclname myportname 3128 ... # http(s)_port name [fast]
e988aa40 755
b3567eb5
FC
756 acl aclname proto HTTP FTP ... # request protocol [fast]
757
758 acl aclname method GET POST ... # HTTP request method [fast]
e988aa40 759
b3567eb5
FC
760 acl aclname http_status 200 301 500- 400-403 ...
761 # status code in reply [fast]
e988aa40 762
375eeb3b 763 acl aclname browser [-i] regexp ...
b3567eb5 764 # pattern match on User-Agent header (see also req_header below) [fast]
e988aa40 765
375eeb3b 766 acl aclname referer_regex [-i] regexp ...
b3567eb5 767 # pattern match on Referer header [fast]
41bd17a4 768 # Referer is highly unreliable, so use with care
e988aa40 769
375eeb3b 770 acl aclname ident username ...
41bd17a4 771 acl aclname ident_regex [-i] pattern ...
b3567eb5 772 # string match on ident output [slow]
41bd17a4 773 # use REQUIRED to accept any non-null ident.
cf5cc17e 774
41bd17a4 775 acl aclname proxy_auth [-i] username ...
776 acl aclname proxy_auth_regex [-i] pattern ...
b3567eb5
FC
777 # perform http authentication challenge to the client and match against
778 # supplied credentials [slow]
779 #
780 # takes a list of allowed usernames.
41bd17a4 781 # use REQUIRED to accept any valid username.
782 #
b3567eb5
FC
783 # Will use proxy authentication in forward-proxy scenarios, and plain
784 # http authenticaiton in reverse-proxy scenarios
785 #
41bd17a4 786 # NOTE: when a Proxy-Authentication header is sent but it is not
787 # needed during ACL checking the username is NOT logged
788 # in access.log.
789 #
790 # NOTE: proxy_auth requires a EXTERNAL authentication program
791 # to check username/password combinations (see
792 # auth_param directive).
793 #
e988aa40
AJ
794 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
795 # as the browser needs to be configured for using a proxy in order
41bd17a4 796 # to respond to proxy authentication.
8e8d4f30 797
41bd17a4 798 acl aclname snmp_community string ...
b3567eb5 799 # A community string to limit access to your SNMP Agent [fast]
41bd17a4 800 # Example:
801 #
802 # acl snmppublic snmp_community public
934b03fc 803
41bd17a4 804 acl aclname maxconn number
805 # This will be matched when the client's IP address has
55d0fae8
AJ
806 # more than <number> TCP connections established. [fast]
807 # NOTE: This only measures direct TCP links so X-Forwarded-For
808 # indirect clients are not counted.
1e5562e3 809
41bd17a4 810 acl aclname max_user_ip [-s] number
811 # This will be matched when the user attempts to log in from more
812 # than <number> different ip addresses. The authenticate_ip_ttl
b3567eb5 813 # parameter controls the timeout on the ip entries. [fast]
41bd17a4 814 # If -s is specified the limit is strict, denying browsing
815 # from any further IP addresses until the ttl has expired. Without
816 # -s Squid will just annoy the user by "randomly" denying requests.
817 # (the counter is reset each time the limit is reached and a
818 # request is denied)
819 # NOTE: in acceleration mode or where there is mesh of child proxies,
820 # clients may appear to come from multiple addresses if they are
821 # going through proxy farms, so a limit of 1 may cause user problems.
cccac0a2 822
cb1b906f
AJ
823 acl aclname random probability
824 # Pseudo-randomly match requests. Based on the probability given.
825 # Probability may be written as a decimal (0.333), fraction (1/3)
826 # or ratio of matches:non-matches (3:5).
827
375eeb3b 828 acl aclname req_mime_type [-i] mime-type ...
41bd17a4 829 # regex match against the mime type of the request generated
830 # by the client. Can be used to detect file upload or some
b3567eb5 831 # types HTTP tunneling requests [fast]
41bd17a4 832 # NOTE: This does NOT match the reply. You cannot use this
833 # to match the returned file type.
cccac0a2 834
41bd17a4 835 acl aclname req_header header-name [-i] any\.regex\.here
836 # regex match against any of the known request headers. May be
837 # thought of as a superset of "browser", "referer" and "mime-type"
b3567eb5 838 # ACL [fast]
cccac0a2 839
375eeb3b 840 acl aclname rep_mime_type [-i] mime-type ...
41bd17a4 841 # regex match against the mime type of the reply received by
842 # squid. Can be used to detect file download or some
b3567eb5 843 # types HTTP tunneling requests. [fast]
41bd17a4 844 # NOTE: This has no effect in http_access rules. It only has
845 # effect in rules that affect the reply data stream such as
846 # http_reply_access.
cccac0a2 847
41bd17a4 848 acl aclname rep_header header-name [-i] any\.regex\.here
849 # regex match against any of the known reply headers. May be
850 # thought of as a superset of "browser", "referer" and "mime-type"
b3567eb5 851 # ACLs [fast]
cccac0a2 852
375eeb3b 853 acl aclname external class_name [arguments...]
41bd17a4 854 # external ACL lookup via a helper class defined by the
b3567eb5 855 # external_acl_type directive [slow]
cccac0a2 856
41bd17a4 857 acl aclname user_cert attribute values...
858 # match against attributes in a user SSL certificate
b3567eb5 859 # attribute is one of DN/C/O/CN/L/ST [fast]
cccac0a2 860
41bd17a4 861 acl aclname ca_cert attribute values...
862 # match against attributes a users issuing CA SSL certificate
b3567eb5 863 # attribute is one of DN/C/O/CN/L/ST [fast]
cccac0a2 864
41bd17a4 865 acl aclname ext_user username ...
866 acl aclname ext_user_regex [-i] pattern ...
b3567eb5 867 # string match on username returned by external acl helper [slow]
41bd17a4 868 # use REQUIRED to accept any non-null user name.
b3567eb5 869
0ab50441 870 acl aclname tag tagvalue ...
b3567eb5 871 # string match on tag returned by external acl helper [slow]
cccac0a2 872
bbaf2685
AJ
873 acl aclname hier_code codename ...
874 # string match against squid hierarchy code(s); [fast]
875 # e.g., DIRECT, PARENT_HIT, NONE, etc.
876 #
877 # NOTE: This has no effect in http_access rules. It only has
878 # effect in rules that affect the reply data stream such as
879 # http_reply_access.
880
cf1c09f6
CT
881IFDEF USE_SSL
882 acl aclname ssl_error errorname
883 # match against SSL certificate validation error [fast]
cf1c09f6 884 #
7a957a93
AR
885 # For valid error names see in @DEFAULT_ERROR_DIR@/templates/error-details.txt
886 # template file.
cf1c09f6 887 #
7a957a93
AR
888 # The following can be used as shortcuts for certificate properties:
889 # [ssl::]certHasExpired: the "not after" field is in the past
890 # [ssl::]certNotYetValid: the "not before" field is in the future
891 # [ssl::]certUntrusted: The certificate issuer is not to be trusted.
892 # [ssl::]certSelfSigned: The certificate is self signed.
893 # [ssl::]certDomainMismatch: The certificate CN domain does not
894 # match the name the name of the host we are connecting to.
895 #
896 # The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch,
897 # ssl::certUntrusted, and ssl::certSelfSigned can also be used as
898 # predefined ACLs, just like the 'all' ACL.
899 #
900 # NOTE: The ssl_error ACL is only supported with sslproxy_cert_error,
901 # sslproxy_cert_sign, and sslproxy_cert_adapt options.
cf1c09f6
CT
902ENDIF
903
e0855596
AJ
904 Examples:
905 acl macaddress arp 09:00:2b:23:45:67
906 acl myexample dst_as 1241
907 acl password proxy_auth REQUIRED
908 acl fileupload req_mime_type -i ^multipart/form-data$
909 acl javascript rep_mime_type -i ^application/x-javascript$
cccac0a2 910
41bd17a4 911NOCOMMENT_START
e0855596
AJ
912#
913# Recommended minimum configuration:
914#
e0855596 915
ee776778 916# Example rule allowing access from your local networks.
917# Adapt to list your (internal) IP networks from where browsing
918# should be allowed
919acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
920acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
921acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
055421ee
AJ
922acl localnet src fc00::/7 # RFC 4193 local private network range
923acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
e0855596 924
41bd17a4 925acl SSL_ports port 443
926acl Safe_ports port 80 # http
927acl Safe_ports port 21 # ftp
928acl Safe_ports port 443 # https
929acl Safe_ports port 70 # gopher
930acl Safe_ports port 210 # wais
931acl Safe_ports port 1025-65535 # unregistered ports
932acl Safe_ports port 280 # http-mgmt
933acl Safe_ports port 488 # gss-http
934acl Safe_ports port 591 # filemaker
935acl Safe_ports port 777 # multiling http
936acl CONNECT method CONNECT
937NOCOMMENT_END
938DOC_END
cccac0a2 939
3d674977
AJ
940NAME: follow_x_forwarded_for
941TYPE: acl_access
942IFDEF: FOLLOW_X_FORWARDED_FOR
943LOC: Config.accessList.followXFF
3d674977
AJ
944DEFAULT_IF_NONE: deny all
945DOC_START
946 Allowing or Denying the X-Forwarded-For header to be followed to
947 find the original source of a request.
948
949 Requests may pass through a chain of several other proxies
950 before reaching us. The X-Forwarded-For header will contain a
951 comma-separated list of the IP addresses in the chain, with the
952 rightmost address being the most recent.
953
954 If a request reaches us from a source that is allowed by this
955 configuration item, then we consult the X-Forwarded-For header
956 to see where that host received the request from. If the
2bf4e8fa
AJ
957 X-Forwarded-For header contains multiple addresses, we continue
958 backtracking until we reach an address for which we are not allowed
959 to follow the X-Forwarded-For header, or until we reach the first
960 address in the list. For the purpose of ACL used in the
961 follow_x_forwarded_for directive the src ACL type always matches
962 the address we are testing and srcdomain matches its rDNS.
3d674977
AJ
963
964 The end result of this process is an IP address that we will
965 refer to as the indirect client address. This address may
57d76dd4 966 be treated as the client address for access control, ICAP, delay
3d674977 967 pools and logging, depending on the acl_uses_indirect_client,
96d64448
AJ
968 icap_uses_indirect_client, delay_pool_uses_indirect_client,
969 log_uses_indirect_client and tproxy_uses_indirect_client options.
3d674977 970
b3567eb5
FC
971 This clause only supports fast acl types.
972 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
973
3d674977
AJ
974 SECURITY CONSIDERATIONS:
975
976 Any host for which we follow the X-Forwarded-For header
977 can place incorrect information in the header, and Squid
978 will use the incorrect information as if it were the
979 source address of the request. This may enable remote
980 hosts to bypass any access control restrictions that are
981 based on the client's source addresses.
982
983 For example:
984
985 acl localhost src 127.0.0.1
986 acl my_other_proxy srcdomain .proxy.example.com
987 follow_x_forwarded_for allow localhost
988 follow_x_forwarded_for allow my_other_proxy
989DOC_END
990
991NAME: acl_uses_indirect_client
992COMMENT: on|off
993TYPE: onoff
994IFDEF: FOLLOW_X_FORWARDED_FOR
995DEFAULT: on
996LOC: Config.onoff.acl_uses_indirect_client
997DOC_START
998 Controls whether the indirect client address
999 (see follow_x_forwarded_for) is used instead of the
1000 direct client address in acl matching.
55d0fae8
AJ
1001
1002 NOTE: maxconn ACL considers direct TCP links and indirect
1003 clients will always have zero. So no match.
3d674977
AJ
1004DOC_END
1005
1006NAME: delay_pool_uses_indirect_client
1007COMMENT: on|off
1008TYPE: onoff
9a0a18de 1009IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
3d674977
AJ
1010DEFAULT: on
1011LOC: Config.onoff.delay_pool_uses_indirect_client
1012DOC_START
1013 Controls whether the indirect client address
1014 (see follow_x_forwarded_for) is used instead of the
1015 direct client address in delay pools.
1016DOC_END
1017
1018NAME: log_uses_indirect_client
1019COMMENT: on|off
1020TYPE: onoff
1021IFDEF: FOLLOW_X_FORWARDED_FOR
1022DEFAULT: on
1023LOC: Config.onoff.log_uses_indirect_client
1024DOC_START
1025 Controls whether the indirect client address
1026 (see follow_x_forwarded_for) is used instead of the
1027 direct client address in the access log.
1028DOC_END
1029
96d64448
AJ
1030NAME: tproxy_uses_indirect_client
1031COMMENT: on|off
1032TYPE: onoff
1033IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
4d7ab5a2 1034DEFAULT: off
96d64448
AJ
1035LOC: Config.onoff.tproxy_uses_indirect_client
1036DOC_START
1037 Controls whether the indirect client address
1038 (see follow_x_forwarded_for) is used instead of the
1039 direct client address when spoofing the outgoing client.
4d7ab5a2
AJ
1040
1041 This has no effect on requests arriving in non-tproxy
1042 mode ports.
1043
1044 SECURITY WARNING: Usage of this option is dangerous
1045 and should not be used trivially. Correct configuration
b01a2238 1046 of follow_x_forewarded_for with a limited set of trusted
4d7ab5a2 1047 sources is required to prevent abuse of your proxy.
96d64448
AJ
1048DOC_END
1049
41bd17a4 1050NAME: http_access
1051TYPE: acl_access
1052LOC: Config.accessList.http
41bd17a4 1053DEFAULT_IF_NONE: deny all
1054DOC_START
1055 Allowing or Denying access based on defined access lists
cccac0a2 1056
41bd17a4 1057 Access to the HTTP port:
1058 http_access allow|deny [!]aclname ...
cccac0a2 1059
41bd17a4 1060 NOTE on default values:
cccac0a2 1061
41bd17a4 1062 If there are no "access" lines present, the default is to deny
1063 the request.
cccac0a2 1064
41bd17a4 1065 If none of the "access" lines cause a match, the default is the
1066 opposite of the last line in the list. If the last line was
1067 deny, the default is allow. Conversely, if the last line
1068 is allow, the default will be deny. For these reasons, it is a
51ae86b2
HN
1069 good idea to have an "deny all" entry at the end of your access
1070 lists to avoid potential confusion.
cccac0a2 1071
b3567eb5
FC
1072 This clause supports both fast and slow acl types.
1073 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1074
41bd17a4 1075NOCOMMENT_START
e0855596
AJ
1076
1077#
1078# Recommended minimum Access Permission configuration:
41bd17a4 1079#
1080# Only allow cachemgr access from localhost
3c722b3a 1081http_access allow localhost manager
41bd17a4 1082http_access deny manager
e0855596
AJ
1083
1084# Deny requests to certain unsafe ports
41bd17a4 1085http_access deny !Safe_ports
e0855596
AJ
1086
1087# Deny CONNECT to other than secure SSL ports
41bd17a4 1088http_access deny CONNECT !SSL_ports
e0855596 1089
41bd17a4 1090# We strongly recommend the following be uncommented to protect innocent
1091# web applications running on the proxy server who think the only
1092# one who can access services on "localhost" is a local user
1093#http_access deny to_localhost
e0855596 1094
41bd17a4 1095#
1096# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
e0855596 1097#
c8f4eac4 1098
ee776778 1099# Example rule allowing access from your local networks.
1100# Adapt localnet in the ACL section to list your (internal) IP networks
1101# from where browsing should be allowed
1102http_access allow localnet
afb33856 1103http_access allow localhost
7d90757b 1104
41bd17a4 1105# And finally deny all other access to this proxy
1106http_access deny all
1107NOCOMMENT_END
1108DOC_END
7d90757b 1109
533493da
AJ
1110NAME: adapted_http_access http_access2
1111TYPE: acl_access
1112LOC: Config.accessList.adapted_http
1113DEFAULT: none
1114DOC_START
1115 Allowing or Denying access based on defined access lists
1116
1117 Essentially identical to http_access, but runs after redirectors
1118 and ICAP/eCAP adaptation. Allowing access control based on their
1119 output.
1120
1121 If not set then only http_access is used.
1122DOC_END
1123
41bd17a4 1124NAME: http_reply_access
1125TYPE: acl_access
1126LOC: Config.accessList.reply
1127DEFAULT: none
1128DOC_START
1129 Allow replies to client requests. This is complementary to http_access.
cccac0a2 1130
41bd17a4 1131 http_reply_access allow|deny [!] aclname ...
cccac0a2 1132
41bd17a4 1133 NOTE: if there are no access lines present, the default is to allow
1134 all replies
1a224843 1135
41bd17a4 1136 If none of the access lines cause a match the opposite of the
1137 last line will apply. Thus it is good practice to end the rules
1138 with an "allow all" or "deny all" entry.
b3567eb5
FC
1139
1140 This clause supports both fast and slow acl types.
1141 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
cccac0a2 1142DOC_END
1143
41bd17a4 1144NAME: icp_access
1145TYPE: acl_access
1146LOC: Config.accessList.icp
41bd17a4 1147DEFAULT_IF_NONE: deny all
5473c134 1148DOC_START
41bd17a4 1149 Allowing or Denying access to the ICP port based on defined
1150 access lists
5473c134 1151
41bd17a4 1152 icp_access allow|deny [!]aclname ...
5473c134 1153
41bd17a4 1154 See http_access for details
1155
b3567eb5
FC
1156 This clause only supports fast acl types.
1157 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
e0855596
AJ
1158
1159# Allow ICP queries from local networks only
df2eec10
AJ
1160#icp_access allow localnet
1161#icp_access deny all
5473c134 1162DOC_END
1163
41bd17a4 1164NAME: htcp_access
1165IFDEF: USE_HTCP
1166TYPE: acl_access
1167LOC: Config.accessList.htcp
41bd17a4 1168DEFAULT_IF_NONE: deny all
5473c134 1169DOC_START
41bd17a4 1170 Allowing or Denying access to the HTCP port based on defined
1171 access lists
5473c134 1172
41bd17a4 1173 htcp_access allow|deny [!]aclname ...
5473c134 1174
41bd17a4 1175 See http_access for details
5473c134 1176
0b48417e 1177 NOTE: The default if no htcp_access lines are present is to
1178 deny all traffic. This default may cause problems with peers
18191440 1179 using the htcp option.
0b48417e 1180
b3567eb5
FC
1181 This clause only supports fast acl types.
1182 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
e0855596
AJ
1183
1184# Allow HTCP queries from local networks only
df2eec10
AJ
1185#htcp_access allow localnet
1186#htcp_access deny all
41bd17a4 1187DOC_END
5473c134 1188
41bd17a4 1189NAME: htcp_clr_access
1190IFDEF: USE_HTCP
1191TYPE: acl_access
1192LOC: Config.accessList.htcp_clr
41bd17a4 1193DEFAULT_IF_NONE: deny all
1194DOC_START
1195 Allowing or Denying access to purge content using HTCP based
1196 on defined access lists
5473c134 1197
41bd17a4 1198 htcp_clr_access allow|deny [!]aclname ...
5473c134 1199
41bd17a4 1200 See http_access for details
5473c134 1201
b3567eb5
FC
1202 This clause only supports fast acl types.
1203 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
e0855596
AJ
1204
1205# Allow HTCP CLR requests from trusted peers
41bd17a4 1206acl htcp_clr_peer src 172.16.1.2
1207htcp_clr_access allow htcp_clr_peer
5473c134 1208DOC_END
1209
41bd17a4 1210NAME: miss_access
1211TYPE: acl_access
1212LOC: Config.accessList.miss
b8a25eaa 1213DEFAULT: none
5473c134 1214DOC_START
0b4fb91a
AJ
1215 Determins whether network access is permitted when satisfying a request.
1216
1217 For example;
1218 to force your neighbors to use you as a sibling instead of
1219 a parent.
5473c134 1220
41bd17a4 1221 acl localclients src 172.16.0.0/16
1222 miss_access allow localclients
1223 miss_access deny !localclients
5473c134 1224
0b4fb91a
AJ
1225 This means only your local clients are allowed to fetch relayed/MISS
1226 replies from the network and all other clients can only fetch cached
1227 objects (HITs).
1228
5473c134 1229
0b4fb91a
AJ
1230 The default for this setting allows all clients who passed the
1231 http_access rules to relay via this proxy.
b3567eb5
FC
1232
1233 This clause only supports fast acl types.
1234 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
41bd17a4 1235DOC_END
1236
1237NAME: ident_lookup_access
1238TYPE: acl_access
1239IFDEF: USE_IDENT
41bd17a4 1240DEFAULT_IF_NONE: deny all
4daaf3cb 1241LOC: Ident::TheConfig.identLookup
5473c134 1242DOC_START
41bd17a4 1243 A list of ACL elements which, if matched, cause an ident
1244 (RFC 931) lookup to be performed for this request. For
1245 example, you might choose to always perform ident lookups
1246 for your main multi-user Unix boxes, but not for your Macs
1247 and PCs. By default, ident lookups are not performed for
1248 any requests.
5473c134 1249
41bd17a4 1250 To enable ident lookups for specific client addresses, you
1251 can follow this example:
5473c134 1252
4daaf3cb 1253 acl ident_aware_hosts src 198.168.1.0/24
41bd17a4 1254 ident_lookup_access allow ident_aware_hosts
1255 ident_lookup_access deny all
5473c134 1256
4daaf3cb 1257 Only src type ACL checks are fully supported. A srcdomain
41bd17a4 1258 ACL might work at times, but it will not always provide
1259 the correct result.
b3567eb5
FC
1260
1261 This clause only supports fast acl types.
1262 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
41bd17a4 1263DOC_END
5473c134 1264
5b0f5383 1265NAME: reply_body_max_size
1266COMMENT: size [acl acl...]
1267TYPE: acl_b_size_t
1268DEFAULT: none
1269LOC: Config.ReplyBodySize
1270DOC_START
1271 This option specifies the maximum size of a reply body. It can be
1272 used to prevent users from downloading very large files, such as
1273 MP3's and movies. When the reply headers are received, the
1274 reply_body_max_size lines are processed, and the first line where
1275 all (if any) listed ACLs are true is used as the maximum body size
1276 for this reply.
1277
1278 This size is checked twice. First when we get the reply headers,
1279 we check the content-length value. If the content length value exists
1280 and is larger than the allowed size, the request is denied and the
1281 user receives an error message that says "the request or reply
1282 is too large." If there is no content-length, and the reply
1283 size exceeds this limit, the client's connection is just closed
1284 and they will receive a partial reply.
1285
1286 WARNING: downstream caches probably can not detect a partial reply
1287 if there is no content-length header, so they will cache
1288 partial responses and give them out as hits. You should NOT
1289 use this option if you have downstream caches.
1290
1291 WARNING: A maximum size smaller than the size of squid's error messages
1292 will cause an infinite loop and crash squid. Ensure that the smallest
1293 non-zero value you use is greater that the maximum header size plus
1294 the size of your largest error page.
1295
1296 If you set this parameter none (the default), there will be
1297 no limit imposed.
3bc32f2f
AJ
1298
1299 Configuration Format is:
1300 reply_body_max_size SIZE UNITS [acl ...]
1301 ie.
1302 reply_body_max_size 10 MB
1303
5b0f5383 1304DOC_END
1305
1306COMMENT_START
1307 NETWORK OPTIONS
1308 -----------------------------------------------------------------------------
1309COMMENT_END
1310
1311NAME: http_port ascii_port
65d448bc 1312TYPE: PortCfg
5b0f5383 1313DEFAULT: none
1314LOC: Config.Sockaddr.http
1315DOC_START
c7b1dd5d
AJ
1316 Usage: port [mode] [options]
1317 hostname:port [mode] [options]
1318 1.2.3.4:port [mode] [options]
5b0f5383 1319
1320 The socket addresses where Squid will listen for HTTP client
1321 requests. You may specify multiple socket addresses.
1322 There are three forms: port alone, hostname with port, and
1323 IP address with port. If you specify a hostname or IP
1324 address, Squid binds the socket to that specific
c7b1dd5d 1325 address. Most likely, you do not need to bind to a specific
5b0f5383 1326 address, so you can use the port number alone.
1327
1328 If you are running Squid in accelerator mode, you
1329 probably want to listen on port 80 also, or instead.
1330
1331 The -a command line option may be used to specify additional
1332 port(s) where Squid listens for proxy request. Such ports will
1333 be plain proxy ports with no options.
1334
1335 You may specify multiple socket addresses on multiple lines.
1336
c7b1dd5d 1337 Modes:
5b0f5383 1338
e77bdb4e 1339 intercept Support for IP-Layer interception of
5b0f5383 1340 outgoing requests without browser settings.
13b5cd0c 1341 NP: disables authentication and IPv6 on the port.
5b0f5383 1342
1343 tproxy Support Linux TPROXY for spoofing outgoing
1344 connections using the client IP address.
6f05d9c8 1345 NP: disables authentication and maybe IPv6 on the port.
5b0f5383 1346
7f45065d 1347 accel Accelerator / reverse proxy mode
5b0f5383 1348
caf3666d 1349 ssl-bump For each CONNECT request allowed by ssl_bump ACLs,
c7b1dd5d 1350 establish secure connection with the client and with
caf3666d 1351 the server, decrypt HTTPS messages as they pass through
c7b1dd5d
AJ
1352 Squid, and treat them as unencrypted HTTP messages,
1353 becoming the man-in-the-middle.
1354
7a957a93 1355 The ssl_bump option is required to fully enable
caf3666d 1356 bumping of CONNECT requests.
c7b1dd5d
AJ
1357
1358 Omitting the mode flag causes default forward proxy mode to be used.
1359
1360
1361 Accelerator Mode Options:
1362
5b0f5383 1363 defaultsite=domainname
1364 What to use for the Host: header if it is not present
1365 in a request. Determines what site (not origin server)
1366 accelerators should consider the default.
5b0f5383 1367
cf673853 1368 no-vhost Disable using HTTP/1.1 Host header for virtual domain support.
5b0f5383 1369
1370 protocol= Protocol to reconstruct accelerated requests with.
7f45065d
HN
1371 Defaults to http for http_port and https for
1372 https_port
5b0f5383 1373
cf673853
AJ
1374 vport Virtual host port support. Using the http_port number
1375 instead of the port passed on Host: headers.
5b0f5383 1376
cf673853
AJ
1377 vport=NN Virtual host port support. Using the specified port
1378 number instead of the port passed on Host: headers.
5b0f5383 1379
7f45065d
HN
1380 act-as-origin
1381 Act as if this Squid is the origin server.
1382 This currently means generate new Date: and Expires:
1383 headers on HIT instead of adding Age:.
5b0f5383 1384
432bc83c
HN
1385 ignore-cc Ignore request Cache-Control headers.
1386
7f45065d 1387 WARNING: This option violates HTTP specifications if
432bc83c
HN
1388 used in non-accelerator setups.
1389
7f45065d
HN
1390 allow-direct Allow direct forwarding in accelerator mode. Normally
1391 accelerated requests are denied direct forwarding as if
1392 never_direct was used.
1393
1394 WARNING: this option opens accelerator mode to security
1395 vulnerabilities usually only affecting in interception
1396 mode. Make sure to protect forwarding with suitable
1397 http_access rules when using this.
1398
c7b1dd5d
AJ
1399
1400 SSL Bump Mode Options:
859741ed
AJ
1401 In addition to these options ssl-bump requires TLS/SSL options.
1402
1403 generate-host-certificates[=<on|off>]
1404 Dynamically create SSL server certificates for the
1405 destination hosts of bumped CONNECT requests.When
1406 enabled, the cert and key options are used to sign
1407 generated certificates. Otherwise generated
1408 certificate will be selfsigned.
1409 If there is a CA certificate lifetime of the generated
1410 certificate equals lifetime of the CA certificate. If
1411 generated certificate is selfsigned lifetime is three
1412 years.
1413 This option is enabled by default when ssl-bump is used.
1414 See the ssl-bump option above for more information.
1415
1416 dynamic_cert_mem_cache_size=SIZE
1417 Approximate total RAM size spent on cached generated
1418 certificates. If set to zero, caching is disabled. The
1419 default value is 4MB. An average XXX-bit certificate
1420 consumes about XXX bytes of RAM.
1421
1422 TLS / SSL Options:
c7b1dd5d
AJ
1423
1424 cert= Path to SSL certificate (PEM format).
1425
1426 key= Path to SSL private key file (PEM format)
1427 if not specified, the certificate file is
1428 assumed to be a combined certificate and
1429 key file.
1430
1431 version= The version of SSL/TLS supported
1432 1 automatic (default)
1433 2 SSLv2 only
1434 3 SSLv3 only
3d96b0e8
AJ
1435 4 TLSv1.0 only
1436 5 TLSv1.1 only
1437 6 TLSv1.2 only
c7b1dd5d
AJ
1438
1439 cipher= Colon separated list of supported ciphers.
bebdc6fb
AJ
1440 NOTE: some ciphers such as EDH ciphers depend on
1441 additional settings. If those settings are
1442 omitted the ciphers may be silently ignored
1443 by the OpenSSL library.
c7b1dd5d 1444
943c5f16 1445 options= Various SSL implementation options. The most important
c7b1dd5d 1446 being:
3d96b0e8
AJ
1447 NO_SSLv2 Disallow the use of SSLv2
1448 NO_SSLv3 Disallow the use of SSLv3
1449 NO_TLSv1 Disallow the use of TLSv1.0
1450 NO_TLSv1_1 Disallow the use of TLSv1.1
1451 NO_TLSv1_2 Disallow the use of TLSv1.2
c7b1dd5d
AJ
1452 SINGLE_DH_USE Always create a new key when using
1453 temporary/ephemeral DH key exchanges
943c5f16
HN
1454 ALL Enable various bug workarounds
1455 suggested as "harmless" by OpenSSL
1456 Be warned that this reduces SSL/TLS
1457 strength to some attacks.
bebdc6fb
AJ
1458 See OpenSSL SSL_CTX_set_options documentation for a
1459 complete list of options.
c7b1dd5d
AJ
1460
1461 clientca= File containing the list of CAs to use when
1462 requesting a client certificate.
1463
1464 cafile= File containing additional CA certificates to
1465 use when verifying client certificates. If unset
1466 clientca will be used.
1467
1468 capath= Directory containing additional CA certificates
1469 and CRL lists to use when verifying client certificates.
1470
1471 crlfile= File of additional CRL lists to use when verifying
1472 the client certificate, in addition to CRLs stored in
1473 the capath. Implies VERIFY_CRL flag below.
1474
1475 dhparams= File containing DH parameters for temporary/ephemeral
bebdc6fb
AJ
1476 DH key exchanges. See OpenSSL documentation for details
1477 on how to create this file.
1478 WARNING: EDH ciphers will be silently disabled if this
1479 option is not set.
c7b1dd5d
AJ
1480
1481 sslflags= Various flags modifying the use of SSL:
1482 DELAYED_AUTH
1483 Don't request client certificates
1484 immediately, but wait until acl processing
1485 requires a certificate (not yet implemented).
1486 NO_DEFAULT_CA
1487 Don't use the default CA lists built in
1488 to OpenSSL.
1489 NO_SESSION_REUSE
1490 Don't allow for session reuse. Each connection
1491 will result in a new SSL session.
1492 VERIFY_CRL
1493 Verify CRL lists when accepting client
1494 certificates.
1495 VERIFY_CRL_ALL
1496 Verify CRL lists for all certificates in the
1497 client certificate chain.
1498
1499 sslcontext= SSL session ID context identifier.
1500
c7b1dd5d
AJ
1501 Other Options:
1502
6b185b50
AJ
1503 connection-auth[=on|off]
1504 use connection-auth=off to tell Squid to prevent
1505 forwarding Microsoft connection oriented authentication
d67acb4e
AJ
1506 (NTLM, Negotiate and Kerberos)
1507
5b0f5383 1508 disable-pmtu-discovery=
1509 Control Path-MTU discovery usage:
1510 off lets OS decide on what to do (default).
1511 transparent disable PMTU discovery when transparent
1512 support is enabled.
1513 always disable always PMTU discovery.
1514
1515 In many setups of transparently intercepting proxies
1516 Path-MTU discovery can not work on traffic towards the
1517 clients. This is the case when the intercepting device
1518 does not fully track connections and fails to forward
1519 ICMP must fragment messages to the cache server. If you
1520 have such setup and experience that certain clients
1521 sporadically hang or never complete requests set
1522 disable-pmtu-discovery option to 'transparent'.
1523
81b6e9a7 1524 name= Specifies a internal name for the port. Defaults to
1525 the port specification (port or addr:port)
1526
68924b6d 1527 tcpkeepalive[=idle,interval,timeout]
fb6c6dbe
AJ
1528 Enable TCP keepalive probes of idle connections.
1529 In seconds; idle is the initial time before TCP starts
1530 probing the connection, interval how often to probe, and
b2130d58 1531 timeout the time before giving up.
1532
5b0f5383 1533 If you run Squid on a dual-homed machine with an internal
1534 and an external interface we recommend you to specify the
1535 internal address:port in http_port. This way Squid will only be
1536 visible on the internal address.
1537
1538NOCOMMENT_START
e0855596 1539
5b0f5383 1540# Squid normally listens to port 3128
1541http_port @DEFAULT_HTTP_PORT@
1542NOCOMMENT_END
1543DOC_END
1544
1545NAME: https_port
1546IFDEF: USE_SSL
65d448bc 1547TYPE: PortCfg
5b0f5383 1548DEFAULT: none
1549LOC: Config.Sockaddr.https
1550DOC_START
7f45065d 1551 Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...]
5b0f5383 1552
859741ed
AJ
1553 The socket address where Squid will listen for client requests made
1554 over TLS or SSL connections. Commonly referred to as HTTPS.
5b0f5383 1555
859741ed
AJ
1556 This is most useful for situations where you are running squid in
1557 accelerator mode and you want to do the SSL work at the accelerator level.
5b0f5383 1558
1559 You may specify multiple socket addresses on multiple lines,
1560 each with their own SSL certificate and/or options.
1561
7f45065d 1562 Modes:
5b0f5383 1563
7f45065d 1564 accel Accelerator / reverse proxy mode
5b0f5383 1565
379e8c1c
AR
1566 tproxy Support Linux TPROXY for spoofing outgoing
1567 connections using the client IP address.
1568 NP: disables authentication and maybe IPv6 on the port.
1569
caf3666d 1570 ssl-bump For each intercepted connection allowed by ssl_bump
7a957a93 1571 ACLs, establish a secure connection with the client and with
caf3666d 1572 the server, decrypt HTTPS messages as they pass through
379e8c1c
AR
1573 Squid, and treat them as unencrypted HTTP messages,
1574 becoming the man-in-the-middle.
1575
caf3666d
AR
1576 An "ssl_bump server-first" match is required to
1577 fully enable bumping of intercepted SSL connections.
379e8c1c
AR
1578
1579 Requires tproxy.
1580
7f45065d 1581 Omitting the mode flag causes default forward proxy mode to be used.
5b0f5383 1582
5b0f5383 1583
7f45065d
HN
1584 See http_port for a list of generic options
1585
1586
1587 SSL Options:
5b0f5383 1588
1589 cert= Path to SSL certificate (PEM format).
1590
1591 key= Path to SSL private key file (PEM format)
1592 if not specified, the certificate file is
1593 assumed to be a combined certificate and
1594 key file.
1595
1596 version= The version of SSL/TLS supported
1597 1 automatic (default)
1598 2 SSLv2 only
1599 3 SSLv3 only
1600 4 TLSv1 only
1601
1602 cipher= Colon separated list of supported ciphers.
1603
1604 options= Various SSL engine options. The most important
1605 being:
1606 NO_SSLv2 Disallow the use of SSLv2
1607 NO_SSLv3 Disallow the use of SSLv3
1608 NO_TLSv1 Disallow the use of TLSv1
1609 SINGLE_DH_USE Always create a new key when using
1610 temporary/ephemeral DH key exchanges
1611 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1612 documentation for a complete list of options.
1613
1614 clientca= File containing the list of CAs to use when
1615 requesting a client certificate.
1616
1617 cafile= File containing additional CA certificates to
1618 use when verifying client certificates. If unset
1619 clientca will be used.
1620
1621 capath= Directory containing additional CA certificates
1622 and CRL lists to use when verifying client certificates.
1623
1624 crlfile= File of additional CRL lists to use when verifying
1625 the client certificate, in addition to CRLs stored in
1626 the capath. Implies VERIFY_CRL flag below.
1627
1628 dhparams= File containing DH parameters for temporary/ephemeral
1629 DH key exchanges.
1630
1631 sslflags= Various flags modifying the use of SSL:
1632 DELAYED_AUTH
1633 Don't request client certificates
1634 immediately, but wait until acl processing
1635 requires a certificate (not yet implemented).
1636 NO_DEFAULT_CA
1637 Don't use the default CA lists built in
1638 to OpenSSL.
1639 NO_SESSION_REUSE
1640 Don't allow for session reuse. Each connection
1641 will result in a new SSL session.
1642 VERIFY_CRL
1643 Verify CRL lists when accepting client
1644 certificates.
1645 VERIFY_CRL_ALL
1646 Verify CRL lists for all certificates in the
1647 client certificate chain.
1648
1649 sslcontext= SSL session ID context identifier.
1650
379e8c1c
AR
1651 generate-host-certificates[=<on|off>]
1652 Dynamically create SSL server certificates for the
1653 destination hosts of bumped SSL requests.When
1654 enabled, the cert and key options are used to sign
1655 generated certificates. Otherwise generated
1656 certificate will be selfsigned.
1657 If there is CA certificate life time of generated
1658 certificate equals lifetime of CA certificate. If
1659 generated certificate is selfsigned lifetime is three
1660 years.
1661 This option is enabled by default when SslBump is used.
1662 See the sslBump option above for more information.
1663
1664 dynamic_cert_mem_cache_size=SIZE
1665 Approximate total RAM size spent on cached generated
1666 certificates. If set to zero, caching is disabled. The
1667 default value is 4MB. An average XXX-bit certificate
1668 consumes about XXX bytes of RAM.
1669
859741ed 1670 See http_port for a list of available options.
5b0f5383 1671DOC_END
1672
41bd17a4 1673NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
1674TYPE: acl_tos
5473c134 1675DEFAULT: none
425de4c8 1676LOC: Ip::Qos::TheConfig.tosToServer
5473c134 1677DOC_START
425de4c8
AJ
1678 Allows you to select a TOS/Diffserv value for packets outgoing
1679 on the server side, based on an ACL.
5473c134 1680
41bd17a4 1681 tcp_outgoing_tos ds-field [!]aclname ...
cccac0a2 1682
41bd17a4 1683 Example where normal_service_net uses the TOS value 0x00
7def7206 1684 and good_service_net uses 0x20
cccac0a2 1685
864a62b5
AJ
1686 acl normal_service_net src 10.0.0.0/24
1687 acl good_service_net src 10.0.1.0/24
2c73de90 1688 tcp_outgoing_tos 0x00 normal_service_net
41bd17a4 1689 tcp_outgoing_tos 0x20 good_service_net
fa38076e 1690
41bd17a4 1691 TOS/DSCP values really only have local significance - so you should
575cb927
AJ
1692 know what you're specifying. For more information, see RFC2474,
1693 RFC2475, and RFC3260.
cccac0a2 1694
41bd17a4 1695 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
1696 "default" to use whatever default your host has. Note that in
864a62b5
AJ
1697 practice often only multiples of 4 is usable as the two rightmost bits
1698 have been redefined for use by ECN (RFC 3168 section 23.1).
cccac0a2 1699
41bd17a4 1700 Processing proceeds in the order specified, and stops at first fully
1701 matching line.
cccac0a2 1702DOC_END
1703
41bd17a4 1704NAME: clientside_tos
1705TYPE: acl_tos
cccac0a2 1706DEFAULT: none
425de4c8
AJ
1707LOC: Ip::Qos::TheConfig.tosToClient
1708DOC_START
1709 Allows you to select a TOS/Diffserv value for packets being transmitted
1710 on the client-side, based on an ACL.
1711
1712 clientside_tos ds-field [!]aclname ...
1713
1714 Example where normal_service_net uses the TOS value 0x00
1715 and good_service_net uses 0x20
1716
1717 acl normal_service_net src 10.0.0.0/24
1718 acl good_service_net src 10.0.1.0/24
1719 clientside_tos 0x00 normal_service_net
1720 clientside_tos 0x20 good_service_net
1721
1722 Note: This feature is incompatible with qos_flows. Any TOS values set here
1723 will be overwritten by TOS values in qos_flows.
1724DOC_END
1725
1726NAME: tcp_outgoing_mark
1727TYPE: acl_nfmark
11e8cfe3 1728IFDEF: SO_MARK&&USE_LIBCAP
425de4c8
AJ
1729DEFAULT: none
1730LOC: Ip::Qos::TheConfig.nfmarkToServer
1731DOC_START
1732 Allows you to apply a Netfilter mark value to outgoing packets
1733 on the server side, based on an ACL.
1734
1735 tcp_outgoing_mark mark-value [!]aclname ...
1736
1737 Example where normal_service_net uses the mark value 0x00
1738 and good_service_net uses 0x20
1739
1740 acl normal_service_net src 10.0.0.0/24
1741 acl good_service_net src 10.0.1.0/24
1742 tcp_outgoing_mark 0x00 normal_service_net
1743 tcp_outgoing_mark 0x20 good_service_net
1744DOC_END
1745
1746NAME: clientside_mark
1747TYPE: acl_nfmark
11e8cfe3 1748IFDEF: SO_MARK&&USE_LIBCAP
425de4c8
AJ
1749DEFAULT: none
1750LOC: Ip::Qos::TheConfig.nfmarkToClient
cccac0a2 1751DOC_START
425de4c8
AJ
1752 Allows you to apply a Netfilter mark value to packets being transmitted
1753 on the client-side, based on an ACL.
1754
1755 clientside_mark mark-value [!]aclname ...
1756
1757 Example where normal_service_net uses the mark value 0x00
1758 and good_service_net uses 0x20
1759
1760 acl normal_service_net src 10.0.0.0/24
1761 acl good_service_net src 10.0.1.0/24
1762 clientside_mark 0x00 normal_service_net
1763 clientside_mark 0x20 good_service_net
1764
1765 Note: This feature is incompatible with qos_flows. Any mark values set here
1766 will be overwritten by mark values in qos_flows.
41bd17a4 1767DOC_END
cccac0a2 1768
575cb927
AJ
1769NAME: qos_flows
1770TYPE: QosConfig
425de4c8 1771IFDEF: USE_QOS_TOS
575cb927 1772DEFAULT: none
b7ac5457 1773LOC: Ip::Qos::TheConfig
7172612f 1774DOC_START
575cb927 1775 Allows you to select a TOS/DSCP value to mark outgoing
425de4c8
AJ
1776 connections with, based on where the reply was sourced. For
1777 platforms using netfilter, allows you to set a netfilter mark
1778 value instead of, or in addition to, a TOS value.
7172612f 1779
575cb927
AJ
1780 TOS values really only have local significance - so you should
1781 know what you're specifying. For more information, see RFC2474,
1782 RFC2475, and RFC3260.
7172612f 1783
425de4c8
AJ
1784 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
1785 in practice often only multiples of 4 is usable as the two rightmost bits
1786 have been redefined for use by ECN (RFC 3168 section 23.1).
1787
1788 Mark values can be any unsigned 32-bit integer value.
7172612f 1789
425de4c8
AJ
1790 This setting is configured by setting the following values:
1791
1792 tos|mark Whether to set TOS or netfilter mark values
575cb927
AJ
1793
1794 local-hit=0xFF Value to mark local cache hits.
1795
1796 sibling-hit=0xFF Value to mark hits from sibling peers.
1797
1798 parent-hit=0xFF Value to mark hits from parent peers.
1799
a29d2a95
AB
1800 miss=0xFF[/mask] Value to mark cache misses. Takes precedence
1801 over the preserve-miss feature (see below), unless
1802 mask is specified, in which case only the bits
1803 specified in the mask are written.
575cb927 1804
425de4c8
AJ
1805 The TOS variant of the following features are only possible on Linux
1806 and require your kernel to be patched with the TOS preserving ZPH
1807 patch, available from http://zph.bratcheda.org
1808 No patch is needed to preserve the netfilter mark, which will work
1809 with all variants of netfilter.
575cb927 1810
575cb927 1811 disable-preserve-miss
425de4c8
AJ
1812 This option disables the preservation of the TOS or netfilter
1813 mark. By default, the existing TOS or netfilter mark value of
1814 the response coming from the remote server will be retained
1815 and masked with miss-mark.
1816 NOTE: in the case of a netfilter mark, the mark must be set on
1817 the connection (using the CONNMARK target) not on the packet
1818 (MARK target).
575cb927
AJ
1819
1820 miss-mask=0xFF
425de4c8
AJ
1821 Allows you to mask certain bits in the TOS or mark value
1822 received from the remote server, before copying the value to
1823 the TOS sent towards clients.
1824 Default for tos: 0xFF (TOS from server is not changed).
1825 Default for mark: 0xFFFFFFFF (mark from server is not changed).
1826
1827 All of these features require the --enable-zph-qos compilation flag
1828 (enabled by default). Netfilter marking also requires the
1829 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
1830 libcap 2.09+ (--with-libcap).
7172612f 1831
7172612f
AJ
1832DOC_END
1833
41bd17a4 1834NAME: tcp_outgoing_address
1835TYPE: acl_address
1836DEFAULT: none
1837LOC: Config.accessList.outgoing_address
1838DOC_START
1839 Allows you to map requests to different outgoing IP addresses
1840 based on the username or source address of the user making
1841 the request.
7f7db318 1842
41bd17a4 1843 tcp_outgoing_address ipaddr [[!]aclname] ...
c33aa074 1844
2dd51400
AJ
1845 For example;
1846 Forwarding clients with dedicated IPs for certain subnets.
9197cd13 1847
2dd51400
AJ
1848 acl normal_service_net src 10.0.0.0/24
1849 acl good_service_net src 10.0.2.0/24
1850
1851 tcp_outgoing_address 2001:db8::c001 good_service_net
1852 tcp_outgoing_address 10.1.0.2 good_service_net
1853
1854 tcp_outgoing_address 2001:db8::beef normal_service_net
1855 tcp_outgoing_address 10.1.0.1 normal_service_net
1856
1857 tcp_outgoing_address 2001:db8::1
1858 tcp_outgoing_address 10.1.0.3
9197cd13 1859
41bd17a4 1860 Processing proceeds in the order specified, and stops at first fully
1861 matching line.
cccac0a2 1862
2dd51400
AJ
1863 Squid will add an implicit IP version test to each line.
1864 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.
1865 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.
1866
1867
1868 NOTE: The use of this directive using client dependent ACLs is
41bd17a4 1869 incompatible with the use of server side persistent connections. To
1870 ensure correct results it is best to set server_persistent_connections
1871 to off when using this directive in such configurations.
cc192b50 1872
2dd51400 1873 NOTE: The use of this directive to set a local IP on outgoing TCP links
4ed968be 1874 is incompatible with using TPROXY to set client IP out outbound TCP links.
2dd51400
AJ
1875 When needing to contact peers use the no-tproxy cache_peer option and the
1876 client_dst_passthru directive re-enable normal forwarding such as this.
cc192b50 1877
cccac0a2 1878DOC_END
6db78a1a 1879
90529125
AJ
1880NAME: host_verify_strict
1881TYPE: onoff
1882DEFAULT: off
1883LOC: Config.onoff.hostStrictVerify
1884DOC_START
d8821934
AR
1885 Regardless of this option setting, when dealing with intercepted
1886 traffic, Squid always verifies that the destination IP address matches
2962f8b8 1887 the Host header domain or IP (called 'authority form URL').
d8821934
AR
1888
1889 This enforcement is performed to satisfy a MUST-level requirement in
1890 RFC 2616 section 14.23: "The Host field value MUST represent the naming
1891 authority of the origin server or gateway given by the original URL".
2962f8b8
AJ
1892
1893 When set to ON:
1894 Squid always responds with an HTTP 409 (Conflict) error
1895 page and logs a security warning if there is no match.
1896
1897 Squid verifies that the destination IP address matches
1898 the Host header for forward-proxy and reverse-proxy traffic
1899 as well. For those traffic types, Squid also enables the
1900 following checks, comparing the corresponding Host header
1901 and Request-URI components:
1902
1903 * The host names (domain or IP) must be identical,
1904 but valueless or missing Host header disables all checks.
1905 For the two host names to match, both must be either IP
1906 or FQDN.
1907
1908 * Port numbers must be identical, but if a port is missing
1909 the scheme-default port is assumed.
1910
1911
1912 When set to OFF (the default):
1913 Squid allows suspicious requests to continue but logs a
1914 security warning and blocks caching of the response.
1915
1916 * Forward-proxy traffic is not checked at all.
1917
1918 * Reverse-proxy traffic is not checked at all.
1919
1920 * Intercepted traffic which passes verification is handled
1921 normally.
1922
1923 For now it also forces suspicious requests to go DIRECT to the
1924 original destination, overriding client_dst_passthru for
1925 intercepted requests which fail Host: verification.
1926
1927 For now suspicious intercepted CONNECT requests are always
1928 responded to with an HTTP 409 (Conflict) error page.
90529125
AJ
1929DOC_END
1930
bfe4e2fe
AJ
1931NAME: client_dst_passthru
1932TYPE: onoff
1933DEFAULT: on
1934LOC: Config.onoff.client_dst_passthru
1935DOC_START
1936 With NAT or TPROXY intercepted traffic Squid may pass the request
1937 directly to the original client destination IP or seek a faster
1938 source.
1939
1940 This option (on by default) prevents cache_peer and alternative DNS
1941 entries being used on intercepted traffic. Both of which lead to
1942 the security vulnerability outlined below.
1943
1944 SECURITY WARNING:
1945
1946 This directive should only be disabled if cache_peer are required.
1947
1948 As described in CVE-2009-0801 when the Host: header alone is used
1949 to determine the destination of a request it becomes trivial for
1950 malicious scripts on remote websites to bypass browser same-origin
1951 security policy and sandboxing protections.
1952
1953 The cause of this is that such applets are allowed to perform their
1954 own HTTP stack, in which case the same-origin policy of the browser
1955 sandbox only verifies that the applet tries to contact the same IP
1956 as from where it was loaded at the IP level. The Host: header may
1957 be different from the connected IP and approved origin.
6b185b50 1958
cccac0a2 1959DOC_END
1960
41bd17a4 1961COMMENT_START
1962 SSL OPTIONS
1963 -----------------------------------------------------------------------------
1964COMMENT_END
1965
1966NAME: ssl_unclean_shutdown
1967IFDEF: USE_SSL
cccac0a2 1968TYPE: onoff
1969DEFAULT: off
41bd17a4 1970LOC: Config.SSL.unclean_shutdown
cccac0a2 1971DOC_START
41bd17a4 1972 Some browsers (especially MSIE) bugs out on SSL shutdown
1973 messages.
cccac0a2 1974DOC_END
1975
41bd17a4 1976NAME: ssl_engine
1977IFDEF: USE_SSL
cccac0a2 1978TYPE: string
41bd17a4 1979LOC: Config.SSL.ssl_engine
1980DEFAULT: none
cccac0a2 1981DOC_START
41bd17a4 1982 The OpenSSL engine to use. You will need to set this if you
1983 would like to use hardware SSL acceleration for example.
cccac0a2 1984DOC_END
1985
41bd17a4 1986NAME: sslproxy_client_certificate
1987IFDEF: USE_SSL
cccac0a2 1988DEFAULT: none
41bd17a4 1989LOC: Config.ssl_client.cert
1990TYPE: string
cccac0a2 1991DOC_START
41bd17a4 1992 Client SSL Certificate to use when proxying https:// URLs
cccac0a2 1993DOC_END
1994
41bd17a4 1995NAME: sslproxy_client_key
1996IFDEF: USE_SSL
cccac0a2 1997DEFAULT: none
41bd17a4 1998LOC: Config.ssl_client.key
1999TYPE: string
cccac0a2 2000DOC_START
41bd17a4 2001 Client SSL Key to use when proxying https:// URLs
cccac0a2 2002DOC_END
2003
41bd17a4 2004NAME: sslproxy_version
2005IFDEF: USE_SSL
2006DEFAULT: 1
2007LOC: Config.ssl_client.version
2008TYPE: int
cccac0a2 2009DOC_START
41bd17a4 2010 SSL version level to use when proxying https:// URLs
3d96b0e8
AJ
2011
2012 The versions of SSL/TLS supported:
2013
2014 1 automatic (default)
2015 2 SSLv2 only
2016 3 SSLv3 only
2017 4 TLSv1.0 only
2018 5 TLSv1.1 only
2019 6 TLSv1.2 only
cccac0a2 2020DOC_END
2021
41bd17a4 2022NAME: sslproxy_options
2023IFDEF: USE_SSL
2024DEFAULT: none
2025LOC: Config.ssl_client.options
2026TYPE: string
cccac0a2 2027DOC_START
943c5f16 2028 SSL implementation options to use when proxying https:// URLs
ab202e4c
AJ
2029
2030 The most important being:
2031
3d96b0e8
AJ
2032 NO_SSLv2 Disallow the use of SSLv2
2033 NO_SSLv3 Disallow the use of SSLv3
2034 NO_TLSv1 Disallow the use of TLSv1.0
2035 NO_TLSv1_1 Disallow the use of TLSv1.1
2036 NO_TLSv1_2 Disallow the use of TLSv1.2
943c5f16
HN
2037 SINGLE_DH_USE
2038 Always create a new key when using temporary/ephemeral
2039 DH key exchanges
2040 SSL_OP_NO_TICKET
2041 Disable use of RFC5077 session tickets. Some servers
2042 may have problems understanding the TLS extension due
2043 to ambiguous specification in RFC4507.
2044 ALL Enable various bug workarounds suggested as "harmless"
2045 by OpenSSL. Be warned that this may reduce SSL/TLS
2046 strength to some attacks.
ab202e4c 2047
ab202e4c
AJ
2048 See the OpenSSL SSL_CTX_set_options documentation for a
2049 complete list of possible options.
cccac0a2 2050DOC_END
2051
41bd17a4 2052NAME: sslproxy_cipher
2053IFDEF: USE_SSL
2054DEFAULT: none
2055LOC: Config.ssl_client.cipher
2056TYPE: string
cccac0a2 2057DOC_START
41bd17a4 2058 SSL cipher list to use when proxying https:// URLs
ab202e4c
AJ
2059
2060 Colon separated list of supported ciphers.
cccac0a2 2061DOC_END
2062
41bd17a4 2063NAME: sslproxy_cafile
2064IFDEF: USE_SSL
2065DEFAULT: none
2066LOC: Config.ssl_client.cafile
2067TYPE: string
cccac0a2 2068DOC_START
41bd17a4 2069 file containing CA certificates to use when verifying server
2070 certificates while proxying https:// URLs
cccac0a2 2071DOC_END
0976f8db 2072
41bd17a4 2073NAME: sslproxy_capath
2074IFDEF: USE_SSL
5473c134 2075DEFAULT: none
41bd17a4 2076LOC: Config.ssl_client.capath
2077TYPE: string
5473c134 2078DOC_START
41bd17a4 2079 directory containing CA certificates to use when verifying
2080 server certificates while proxying https:// URLs
5473c134 2081DOC_END
2082
4c9da963 2083NAME: ssl_bump
2084IFDEF: USE_SSL
caf3666d 2085TYPE: sslproxy_ssl_bump
4c9da963 2086LOC: Config.accessList.ssl_bump
2087DEFAULT: none
2088DOC_START
caf3666d
AR
2089 This option is consulted when a CONNECT request is received on
2090 an http_port (or a new connection is intercepted at an
2091 https_port), provided that port was configured with an ssl-bump
2092 flag. The subsequent data on the connection is either treated as
2093 HTTPS and decrypted OR tunneled at TCP level without decryption,
2094 depending on the first bumping "mode" which ACLs match.
2095
2096 ssl_bump <mode> [!]acl ...
2097
2098 The following bumping modes are supported:
2099
2100 client-first
2101 Allow bumping of the connection. Establish a secure connection
2102 with the client first, then connect to the server. This old mode
2103 does not allow Squid to mimic server SSL certificate and does
2104 not work with intercepted SSL connections.
2105
2106 server-first
2107 Allow bumping of the connection. Establish a secure connection
2108 with the server first, then establish a secure connection with
2109 the client, using a mimicked server certificate. Works with both
2110 CONNECT requests and intercepted SSL connections.
2111
2112 none
2113 Become a TCP tunnel without decoding the connection.
2114 Works with both CONNECT requests and intercepted SSL
2115 connections. This is the default behavior when no
2116 ssl_bump option is given or no ssl_bump ACLs match.
2117
2118 By default, no connections are bumped.
2119
2120 The first matching ssl_bump option wins. If no ACLs match, the
2121 connection is not bumped. Unlike most allow/deny ACL lists, ssl_bump
2122 does not have an implicit "negate the last given option" rule. You
2123 must make that rule explicit if you convert old ssl_bump allow/deny
2124 rules that rely on such an implicit rule.
4c9da963 2125
e0c0d54c 2126 This clause supports both fast and slow acl types.
b3567eb5 2127 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
e0855596 2128
caf3666d
AR
2129 See also: http_port ssl-bump, https_port ssl-bump
2130
e0855596 2131
caf3666d
AR
2132 # Example: Bump all requests except those originating from
2133 # localhost and those going to example.com.
e0855596 2134
e0855596 2135 acl broken_sites dstdomain .example.com
caf3666d
AR
2136 ssl_bump none localhost
2137 ssl_bump none broken_sites
2138 ssl_bump server-first all
4c9da963 2139DOC_END
2140
41bd17a4 2141NAME: sslproxy_flags
2142IFDEF: USE_SSL
2143DEFAULT: none
2144LOC: Config.ssl_client.flags
2145TYPE: string
5473c134 2146DOC_START
41bd17a4 2147 Various flags modifying the use of SSL while proxying https:// URLs:
4c9da963 2148 DONT_VERIFY_PEER Accept certificates that fail verification.
2149 For refined control, see sslproxy_cert_error.
41bd17a4 2150 NO_DEFAULT_CA Don't use the default CA list built in
2151 to OpenSSL.
5473c134 2152DOC_END
2153
4c9da963 2154NAME: sslproxy_cert_error
2155IFDEF: USE_SSL
2156DEFAULT: none
2157LOC: Config.ssl_client.cert_error
2158TYPE: acl_access
2159DOC_START
2160 Use this ACL to bypass server certificate validation errors.
2161
2162 For example, the following lines will bypass all validation errors
3b8f558c 2163 when talking to servers for example.com. All other
4c9da963 2164 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
2165
a87bfd3b
AR
2166 acl BrokenButTrustedServers dstdomain example.com
2167 sslproxy_cert_error allow BrokenButTrustedServers
4c9da963 2168 sslproxy_cert_error deny all
2169
b3567eb5
FC
2170 This clause only supports fast acl types.
2171 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2172 Using slow acl types may result in server crashes
4c9da963 2173
2174 Without this option, all server certificate validation errors
2175 terminate the transaction. Bypassing validation errors is dangerous
2176 because an error usually implies that the server cannot be trusted and
2177 the connection may be insecure.
2178
2179 See also: sslproxy_flags and DONT_VERIFY_PEER.
2180
e0855596 2181 Default setting: sslproxy_cert_error deny all
4c9da963 2182DOC_END
2183
aebe6888
CT
2184NAME: sslproxy_cert_sign
2185IFDEF: USE_SSL
2186DEFAULT: none
10d914f6
CT
2187POSTSCRIPTUM: signUntrusted ssl::certUntrusted
2188POSTSCRIPTUM: signSelf ssl::certSelfSigned
2189POSTSCRIPTUM: signTrusted all
aebe6888
CT
2190TYPE: sslproxy_cert_sign
2191LOC: Config.ssl_client.cert_sign
2192DOC_START
2193
69742b76 2194 sslproxy_cert_sign <signing algorithm> acl ...
aebe6888 2195
69742b76 2196 The following certificate signing algorithms are supported:
aebe6888 2197 signTrusted
69742b76
AR
2198 Sign using the configured CA certificate which is usually
2199 placed in and trusted by end-user browsers. This is the
2200 default for trusted origin server certificates.
aebe6888 2201 signUntrusted
69742b76
AR
2202 Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error.
2203 This is the default for untrusted origin server certificates
2204 that are not self-signed (see ssl::certUntrusted).
aebe6888 2205 signSelf
69742b76 2206 Sign using a self-signed certificate with the right CN to
aebe6888 2207 generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the
69742b76
AR
2208 browser. This is the default for self-signed origin server
2209 certificates (see ssl::certSelfSigned).
aebe6888 2210
cf1c09f6
CT
2211 This clause only supports fast acl types.
2212
69742b76
AR
2213 When sslproxy_cert_sign acl(s) match, Squid uses the corresponding
2214 signing algorithm to generate the certificate and ignores all
2215 subsequent sslproxy_cert_sign options (the first match wins). If no
2216 acl(s) match, the default signing algorithm is determined by errors
2217 detected when obtaining and validating the origin server certificate.
cf1c09f6 2218
4b0d23b7
CT
2219 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2220 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2221 CONNECT request that carries a domain name. In all other cases (CONNECT
2222 to an IP address or an intercepted SSL connection), Squid cannot detect
2223 the domain mismatch at certificate generation time when
2224 bump-server-first is used.
aebe6888
CT
2225DOC_END
2226
fb2178bb
CT
2227NAME: sslproxy_cert_adapt
2228IFDEF: USE_SSL
2229DEFAULT: none
2230TYPE: sslproxy_cert_adapt
2231LOC: Config.ssl_client.cert_adapt
2232DOC_START
2233
2234 sslproxy_cert_adapt <adaptation algorithm> acl ...
2235
69742b76 2236 The following certificate adaptation algorithms are supported:
fb2178bb 2237 setValidAfter
69742b76
AR
2238 Sets the "Not After" property to the "Not After" property of
2239 the CA certificate used to sign generated certificates.
fb2178bb 2240 setValidBefore
69742b76
AR
2241 Sets the "Not Before" property to the "Not Before" property of
2242 the CA certificate used to sign generated certificates.
2243 setCommonName or setCommonName{CN}
2244 Sets Subject.CN property to the host name specified as a
2245 CN parameter or, if no explicit CN parameter was specified,
2246 extracted from the CONNECT request. It is a misconfiguration
2247 to use setCommonName without an explicit parameter for
2248 intercepted or tproxied SSL connections.
fb2178bb 2249
cf1c09f6
CT
2250 This clause only supports fast acl types.
2251
69742b76
AR
2252 Squid first groups sslproxy_cert_adapt options by adaptation algorithm.
2253 Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the
2254 corresponding adaptation algorithm to generate the certificate and
2255 ignores all subsequent sslproxy_cert_adapt options in that algorithm's
2256 group (i.e., the first match wins within each algorithm group). If no
2257 acl(s) match, the default mimicking action takes place.
cf1c09f6 2258
4b0d23b7
CT
2259 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2260 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2261 CONNECT request that carries a domain name. In all other cases (CONNECT
2262 to an IP address or an intercepted SSL connection), Squid cannot detect
2263 the domain mismatch at certificate generation time when
2264 bump-server-first is used.
fb2178bb
CT
2265DOC_END
2266
41bd17a4 2267NAME: sslpassword_program
2268IFDEF: USE_SSL
2269DEFAULT: none
2270LOC: Config.Program.ssl_password
2271TYPE: string
5473c134 2272DOC_START
41bd17a4 2273 Specify a program used for entering SSL key passphrases
2274 when using encrypted SSL certificate keys. If not specified
2275 keys must either be unencrypted, or Squid started with the -N
2276 option to allow it to query interactively for the passphrase.
7acb9ddd
HN
2277
2278 The key file name is given as argument to the program allowing
2279 selection of the right password if you have multiple encrypted
2280 keys.
5473c134 2281DOC_END
2282
95d2589c
CT
2283COMMENT_START
2284 OPTIONS RELATING TO EXTERNAL SSL_CRTD
2285 -----------------------------------------------------------------------------
2286COMMENT_END
2287
2288NAME: sslcrtd_program
2289TYPE: eol
2290IFDEF: USE_SSL_CRTD
2291DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
2292LOC: Ssl::TheConfig.ssl_crtd
2293DOC_START
2294 Specify the location and options of the executable for ssl_crtd process.
2295 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
2296 For more information use:
2297 @DEFAULT_SSL_CRTD@ -h
2298DOC_END
2299
2300NAME: sslcrtd_children
2301TYPE: HelperChildConfig
2302IFDEF: USE_SSL_CRTD
2303DEFAULT: 32 startup=5 idle=1
2304LOC: Ssl::TheConfig.ssl_crtdChildren
2305DOC_START
2306 The maximum number of processes spawn to service ssl server.
2307 The maximum this may be safely set to is 32.
2308
2309 The startup= and idle= options allow some measure of skew in your
2310 tuning.
2311
2312 startup=N
2313
2314 Sets the minimum number of processes to spawn when Squid
2315 starts or reconfigures. When set to zero the first request will
2316 cause spawning of the first child process to handle it.
2317
2318 Starting too few children temporary slows Squid under load while it
2319 tries to spawn enough additional processes to cope with traffic.
2320
2321 idle=N
2322
2323 Sets a minimum of how many processes Squid is to try and keep available
2324 at all times. When traffic begins to rise above what the existing
2325 processes can handle this many more will be spawned up to the maximum
2326 configured. A minimum setting of 1 is required.
2327
2328 You must have at least one ssl_crtd process.
2329DOC_END
2330
cccac0a2 2331COMMENT_START
41bd17a4 2332 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
cccac0a2 2333 -----------------------------------------------------------------------------
2334COMMENT_END
2335
41bd17a4 2336NAME: cache_peer
2337TYPE: peer
2338DEFAULT: none
2339LOC: Config.peers
cccac0a2 2340DOC_START
41bd17a4 2341 To specify other caches in a hierarchy, use the format:
2b94f655 2342
41bd17a4 2343 cache_peer hostname type http-port icp-port [options]
2b94f655 2344
41bd17a4 2345 For example,
2b94f655 2346
41bd17a4 2347 # proxy icp
2348 # hostname type port port options
2349 # -------------------- -------- ----- ----- -----------
2b94f655 2350 cache_peer parent.foo.net parent 3128 3130 default
41bd17a4 2351 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
2352 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
2e9993e1 2353 cache_peer example.com parent 80 0 default
2b94f655
AJ
2354 cache_peer cdn.example.com sibling 3128 0
2355
2356 type: either 'parent', 'sibling', or 'multicast'.
2357
2358 proxy-port: The port number where the peer accept HTTP requests.
2359 For other Squid proxies this is usually 3128
2360 For web servers this is usually 80
2361
2362 icp-port: Used for querying neighbor caches about objects.
2363 Set to 0 if the peer does not support ICP or HTCP.
2364 See ICP and HTCP options below for additional details.
2365
2366
2367 ==== ICP OPTIONS ====
2368
2369 You MUST also set icp_port and icp_access explicitly when using these options.
2370 The defaults will prevent peer traffic using ICP.
2371
2372
2373 no-query Disable ICP queries to this neighbor.
2374
2375 multicast-responder
2376 Indicates the named peer is a member of a multicast group.
2377 ICP queries will not be sent directly to the peer, but ICP
2378 replies will be accepted from it.
2379
2380 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
2381 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
2382
2383 background-ping
2384 To only send ICP queries to this neighbor infrequently.
2385 This is used to keep the neighbor round trip time updated
2386 and is usually used in conjunction with weighted-round-robin.
2387
2388
2389 ==== HTCP OPTIONS ====
2390
2391 You MUST also set htcp_port and htcp_access explicitly when using these options.
2392 The defaults will prevent peer traffic using HTCP.
2393
2394
2395 htcp Send HTCP, instead of ICP, queries to the neighbor.
2396 You probably also want to set the "icp-port" to 4827
18191440
AJ
2397 instead of 3130. This directive accepts a comma separated
2398 list of options described below.
2b94f655 2399
18191440 2400 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
2b94f655 2401
18191440 2402 htcp=no-clr Send HTCP to the neighbor but without
2b94f655 2403 sending any CLR requests. This cannot be used with
18191440 2404 only-clr.
2b94f655 2405
18191440
AJ
2406 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
2407 This cannot be used with no-clr.
2b94f655 2408
18191440 2409 htcp=no-purge-clr
2b94f655
AJ
2410 Send HTCP to the neighbor including CLRs but only when
2411 they do not result from PURGE requests.
2412
18191440 2413 htcp=forward-clr
2b94f655
AJ
2414 Forward any HTCP CLR requests this proxy receives to the peer.
2415
2416
2417 ==== PEER SELECTION METHODS ====
2418
2419 The default peer selection method is ICP, with the first responding peer
2420 being used as source. These options can be used for better load balancing.
2421
2422
2423 default This is a parent cache which can be used as a "last-resort"
2424 if a peer cannot be located by any of the peer-selection methods.
2425 If specified more than once, only the first is used.
2426
2427 round-robin Load-Balance parents which should be used in a round-robin
2428 fashion in the absence of any ICP queries.
2429 weight=N can be used to add bias.
2430
2431 weighted-round-robin
2432 Load-Balance parents which should be used in a round-robin
2433 fashion with the frequency of each parent being based on the
2434 round trip time. Closer parents are used more often.
2435 Usually used for background-ping parents.
2436 weight=N can be used to add bias.
2437
2438 carp Load-Balance parents which should be used as a CARP array.
2439 The requests will be distributed among the parents based on the
2440 CARP load balancing hash function based on their weight.
2441
2442 userhash Load-balance parents based on the client proxy_auth or ident username.
2443
2444 sourcehash Load-balance parents based on the client source IP.
8a368316
AJ
2445
2446 multicast-siblings
2447 To be used only for cache peers of type "multicast".
2448 ALL members of this multicast group have "sibling"
2e9993e1 2449 relationship with it, not "parent". This is to a multicast
8a368316
AJ
2450 group when the requested object would be fetched only from
2451 a "parent" cache, anyway. It's useful, e.g., when
2452 configuring a pool of redundant Squid proxies, being
2453 members of the same multicast group.
2b94f655
AJ
2454
2455
2456 ==== PEER SELECTION OPTIONS ====
2457
2458 weight=N use to affect the selection of a peer during any weighted
2459 peer-selection mechanisms.
2460 The weight must be an integer; default is 1,
2461 larger weights are favored more.
2462 This option does not affect parent selection if a peering
2463 protocol is not in use.
2464
2465 basetime=N Specify a base amount to be subtracted from round trip
2466 times of parents.
2467 It is subtracted before division by weight in calculating
2468 which parent to fectch from. If the rtt is less than the
2469 base time the rtt is set to a minimal value.
2470
3c72389f
AJ
2471 ttl=N Specify a TTL to use when sending multicast ICP queries
2472 to this address.
2b94f655
AJ
2473 Only useful when sending to a multicast group.
2474 Because we don't accept ICP replies from random
2475 hosts, you must configure other group members as
2476 peers with the 'multicast-responder' option.
2477
2478 no-delay To prevent access to this neighbor from influencing the
2479 delay pools.
2480
2481 digest-url=URL Tell Squid to fetch the cache digest (if digests are
2482 enabled) for this host from the specified URL rather
2483 than the Squid default location.
2484
2485
de03b596
FC
2486 ==== CARP OPTIONS ====
2487
2488 carp-key=key-specification
2489 use a different key than the full URL to hash against the peer.
2490 the key-specification is a comma-separated list of the keywords
2491 scheme, host, port, path, params
2492 Order is not important.
2493
2b94f655
AJ
2494 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
2495
2496 originserver Causes this parent to be contacted as an origin server.
2497 Meant to be used in accelerator setups when the peer
2498 is a web server.
2499
2500 forceddomain=name
2501 Set the Host header of requests forwarded to this peer.
2502 Useful in accelerator setups where the server (peer)
2503 expects a certain domain name but clients may request
2504 others. ie example.com or www.example.com
2505
2506 no-digest Disable request of cache digests.
2507
2508 no-netdb-exchange
2509 Disables requesting ICMP RTT database (NetDB).
2510
2511
2512 ==== AUTHENTICATION OPTIONS ====
2513
2514 login=user:password
2515 If this is a personal/workgroup proxy and your parent
2516 requires proxy authentication.
2517
2518 Note: The string can include URL escapes (i.e. %20 for
2519 spaces). This also means % must be written as %%.
2520
11e4c5e5
AJ
2521 login=PASSTHRU
2522 Send login details received from client to this peer.
2523 Both Proxy- and WWW-Authorization headers are passed
2524 without alteration to the peer.
2525 Authentication is not required by Squid for this to work.
2526
2527 Note: This will pass any form of authentication but
2528 only Basic auth will work through a proxy unless the
2529 connection-auth options are also used.
ee0b94f4 2530
2b94f655
AJ
2531 login=PASS Send login details received from client to this peer.
2532 Authentication is not required by this option.
11e4c5e5 2533
2b94f655
AJ
2534 If there are no client-provided authentication headers
2535 to pass on, but username and password are available
ee0b94f4
HN
2536 from an external ACL user= and password= result tags
2537 they may be sent instead.
2b94f655
AJ
2538
2539 Note: To combine this with proxy_auth both proxies must
2540 share the same user database as HTTP only allows for
2541 a single login (one for proxy, one for origin server).
2542 Also be warned this will expose your users proxy
2543 password to the peer. USE WITH CAUTION
2544
2545 login=*:password
2546 Send the username to the upstream cache, but with a
2547 fixed password. This is meant to be used when the peer
2548 is in another administrative domain, but it is still
2549 needed to identify each user.
2550 The star can optionally be followed by some extra
2551 information which is added to the username. This can
2552 be used to identify this proxy to the peer, similar to
2553 the login=username:password option above.
2554
9ca29d23
AJ
2555 login=NEGOTIATE
2556 If this is a personal/workgroup proxy and your parent
2557 requires a secure proxy authentication.
2558 The first principal from the default keytab or defined by
2559 the environment variable KRB5_KTNAME will be used.
2560
63f03f79
PL
2561 WARNING: The connection may transmit requests from multiple
2562 clients. Negotiate often assumes end-to-end authentication
2563 and a single-client. Which is not strictly true here.
2564
9ca29d23
AJ
2565 login=NEGOTIATE:principal_name
2566 If this is a personal/workgroup proxy and your parent
2567 requires a secure proxy authentication.
2568 The principal principal_name from the default keytab or
2569 defined by the environment variable KRB5_KTNAME will be
2570 used.
2571
63f03f79
PL
2572 WARNING: The connection may transmit requests from multiple
2573 clients. Negotiate often assumes end-to-end authentication
2574 and a single-client. Which is not strictly true here.
2575
2b94f655
AJ
2576 connection-auth=on|off
2577 Tell Squid that this peer does or not support Microsoft
2578 connection oriented authentication, and any such
2579 challenges received from there should be ignored.
2580 Default is auto to automatically determine the status
2581 of the peer.
2582
2583
2584 ==== SSL / HTTPS / TLS OPTIONS ====
2585
2586 ssl Encrypt connections to this peer with SSL/TLS.
2587
2588 sslcert=/path/to/ssl/certificate
2589 A client SSL certificate to use when connecting to
2590 this peer.
2591
2592 sslkey=/path/to/ssl/key
2593 The private SSL key corresponding to sslcert above.
2594 If 'sslkey' is not specified 'sslcert' is assumed to
2595 reference a combined file containing both the
2596 certificate and the key.
2597
3d96b0e8 2598 sslversion=1|2|3|4|5|6
2b94f655
AJ
2599 The SSL version to use when connecting to this peer
2600 1 = automatic (default)
2601 2 = SSL v2 only
2602 3 = SSL v3 only
3d96b0e8
AJ
2603 4 = TLS v1.0 only
2604 5 = TLS v1.1 only
2605 6 = TLS v1.2 only
2b94f655
AJ
2606
2607 sslcipher=... The list of valid SSL ciphers to use when connecting
2608 to this peer.
2609
943c5f16
HN
2610 ssloptions=... Specify various SSL implementation options:
2611
3d96b0e8
AJ
2612 NO_SSLv2 Disallow the use of SSLv2
2613 NO_SSLv3 Disallow the use of SSLv3
2614 NO_TLSv1 Disallow the use of TLSv1.0
2615 NO_TLSv1_1 Disallow the use of TLSv1.1
2616 NO_TLSv1_2 Disallow the use of TLSv1.2
943c5f16
HN
2617 SINGLE_DH_USE
2618 Always create a new key when using
2619 temporary/ephemeral DH key exchanges
2620 ALL Enable various bug workarounds
2621 suggested as "harmless" by OpenSSL
2622 Be warned that this reduces SSL/TLS
2623 strength to some attacks.
2624
2625 See the OpenSSL SSL_CTX_set_options documentation for a
2626 more complete list.
2b94f655
AJ
2627
2628 sslcafile=... A file containing additional CA certificates to use
2629 when verifying the peer certificate.
2630
2631 sslcapath=... A directory containing additional CA certificates to
2632 use when verifying the peer certificate.
2633
2634 sslcrlfile=... A certificate revocation list file to use when
2635 verifying the peer certificate.
2636
2637 sslflags=... Specify various flags modifying the SSL implementation:
2638
41bd17a4 2639 DONT_VERIFY_PEER
2640 Accept certificates even if they fail to
2641 verify.
2642 NO_DEFAULT_CA
2643 Don't use the default CA list built in
2644 to OpenSSL.
2645 DONT_VERIFY_DOMAIN
2646 Don't verify the peer certificate
2647 matches the server name
2b94f655
AJ
2648
2649 ssldomain= The peer name as advertised in it's certificate.
2650 Used for verifying the correctness of the received peer
2651 certificate. If not specified the peer hostname will be
2652 used.
2653
2654 front-end-https
2655 Enable the "Front-End-Https: On" header needed when
2656 using Squid as a SSL frontend in front of Microsoft OWA.
2657 See MS KB document Q307347 for details on this header.
2658 If set to auto the header will only be added if the
2659 request is forwarded as a https:// URL.
2660
2661
2662 ==== GENERAL OPTIONS ====
2663
2664 connect-timeout=N
2665 A peer-specific connect timeout.
2666 Also see the peer_connect_timeout directive.
2667
2668 connect-fail-limit=N
2669 How many times connecting to a peer must fail before
2670 it is marked as down. Default is 10.
2671
2672 allow-miss Disable Squid's use of only-if-cached when forwarding
2673 requests to siblings. This is primarily useful when
2674 icp_hit_stale is used by the sibling. To extensive use
2675 of this option may result in forwarding loops, and you
2676 should avoid having two-way peerings with this option.
2677 For example to deny peer usage on requests from peer
2678 by denying cache_peer_access if the source is a peer.
2679
2680 max-conn=N Limit the amount of connections Squid may open to this
2681 peer. see also
2682
2683 name=xxx Unique name for the peer.
2684 Required if you have multiple peers on the same host
2685 but different ports.
2686 This name can be used in cache_peer_access and similar
2687 directives to dentify the peer.
2688 Can be used by outgoing access controls through the
2689 peername ACL type.
2690
b0758e04
AJ
2691 no-tproxy Do not use the client-spoof TPROXY support when forwarding
2692 requests to this peer. Use normal address selection instead.
2693
2b94f655
AJ
2694 proxy-only objects fetched from the peer will not be stored locally.
2695
41bd17a4 2696DOC_END
cccac0a2 2697
41bd17a4 2698NAME: cache_peer_domain cache_host_domain
2699TYPE: hostdomain
2700DEFAULT: none
2701LOC: none
2702DOC_START
2703 Use to limit the domains for which a neighbor cache will be
2704 queried. Usage:
cccac0a2 2705
41bd17a4 2706 cache_peer_domain cache-host domain [domain ...]
2707 cache_peer_domain cache-host !domain
cccac0a2 2708
41bd17a4 2709 For example, specifying
cccac0a2 2710
41bd17a4 2711 cache_peer_domain parent.foo.net .edu
cccac0a2 2712
41bd17a4 2713 has the effect such that UDP query packets are sent to
2714 'bigserver' only when the requested object exists on a
2715 server in the .edu domain. Prefixing the domainname
2716 with '!' means the cache will be queried for objects
2717 NOT in that domain.
cccac0a2 2718
41bd17a4 2719 NOTE: * Any number of domains may be given for a cache-host,
2720 either on the same or separate lines.
2721 * When multiple domains are given for a particular
2722 cache-host, the first matched domain is applied.
2723 * Cache hosts with no domain restrictions are queried
2724 for all requests.
2725 * There are no defaults.
2726 * There is also a 'cache_peer_access' tag in the ACL
2727 section.
2728DOC_END
dd9b1776 2729
41bd17a4 2730NAME: cache_peer_access
2731TYPE: peer_access
2732DEFAULT: none
2733LOC: none
2734DOC_START
2735 Similar to 'cache_peer_domain' but provides more flexibility by
2736 using ACL elements.
cccac0a2 2737
41bd17a4 2738 cache_peer_access cache-host allow|deny [!]aclname ...
dd9b1776 2739
41bd17a4 2740 The syntax is identical to 'http_access' and the other lists of
2741 ACL elements. See the comments for 'http_access' below, or
e314b7b9 2742 the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
41bd17a4 2743DOC_END
dd9b1776 2744
41bd17a4 2745NAME: neighbor_type_domain
2746TYPE: hostdomaintype
2747DEFAULT: none
2748LOC: none
2749DOC_START
2750 usage: neighbor_type_domain neighbor parent|sibling domain domain ...
cccac0a2 2751
41bd17a4 2752 Modifying the neighbor type for specific domains is now
11e3fa1c 2753 possible. You can treat some domains differently than the
41bd17a4 2754 default neighbor type specified on the 'cache_peer' line.
2755 Normally it should only be necessary to list domains which
2756 should be treated differently because the default neighbor type
2757 applies for hostnames which do not match domains listed here.
6bf4f823 2758
41bd17a4 2759EXAMPLE:
dbe3992d 2760 cache_peer cache.foo.org parent 3128 3130
41bd17a4 2761 neighbor_type_domain cache.foo.org sibling .com .net
2762 neighbor_type_domain cache.foo.org sibling .au .de
2763DOC_END
6bf4f823 2764
41bd17a4 2765NAME: dead_peer_timeout
2766COMMENT: (seconds)
2767DEFAULT: 10 seconds
2768TYPE: time_t
2769LOC: Config.Timeout.deadPeer
2770DOC_START
2771 This controls how long Squid waits to declare a peer cache
2772 as "dead." If there are no ICP replies received in this
2773 amount of time, Squid will declare the peer dead and not
2774 expect to receive any further ICP replies. However, it
2775 continues to send ICP queries, and will mark the peer as
2776 alive upon receipt of the first subsequent ICP reply.
699acd19 2777
41bd17a4 2778 This timeout also affects when Squid expects to receive ICP
2779 replies from peers. If more than 'dead_peer' seconds have
2780 passed since the last ICP reply was received, Squid will not
2781 expect to receive an ICP reply on the next query. Thus, if
2782 your time between requests is greater than this timeout, you
2783 will see a lot of requests sent DIRECT to origin servers
2784 instead of to your parents.
2785DOC_END
cccac0a2 2786
437823b4
AJ
2787NAME: forward_max_tries
2788DEFAULT: 10
2789TYPE: int
2790LOC: Config.forward_max_tries
2791DOC_START
2792 Controls how many different forward paths Squid will try
2793 before giving up. See also forward_timeout.
31ef19cd
AJ
2794
2795 NOTE: connect_retries (default: none) can make each of these
2796 possible forwarding paths be tried multiple times.
437823b4
AJ
2797DOC_END
2798
41bd17a4 2799NAME: hierarchy_stoplist
2800TYPE: wordlist
2801DEFAULT: none
2802LOC: Config.hierarchy_stoplist
2803DOC_START
2804 A list of words which, if found in a URL, cause the object to
2805 be handled directly by this cache. In other words, use this
2806 to not query neighbor caches for certain objects. You may
2807 list this option multiple times.
e0855596 2808
3387b5a4
AJ
2809 Example:
2810 hierarchy_stoplist cgi-bin ?
2811
2812 Note: never_direct overrides this option.
6b698a21 2813DOC_END
0976f8db 2814
41bd17a4 2815COMMENT_START
2816 MEMORY CACHE OPTIONS
2817 -----------------------------------------------------------------------------
2818COMMENT_END
2819
2820NAME: cache_mem
2821COMMENT: (bytes)
2822TYPE: b_size_t
df2eec10 2823DEFAULT: 256 MB
41bd17a4 2824LOC: Config.memMaxSize
6b698a21 2825DOC_START
41bd17a4 2826 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
2827 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
2828 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
2829 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
2830
2831 'cache_mem' specifies the ideal amount of memory to be used
2832 for:
2833 * In-Transit objects
2834 * Hot Objects
2835 * Negative-Cached objects
2836
2837 Data for these objects are stored in 4 KB blocks. This
2838 parameter specifies the ideal upper limit on the total size of
2839 4 KB blocks allocated. In-Transit objects take the highest
2840 priority.
2841
2842 In-transit objects have priority over the others. When
2843 additional space is needed for incoming data, negative-cached
2844 and hot objects will be released. In other words, the
2845 negative-cached and hot objects will fill up any unused space
2846 not needed for in-transit objects.
2847
2848 If circumstances require, this limit will be exceeded.
2849 Specifically, if your incoming request rate requires more than
2850 'cache_mem' of memory to hold in-transit objects, Squid will
2851 exceed this limit to satisfy the new requests. When the load
2852 decreases, blocks will be freed until the high-water mark is
2853 reached. Thereafter, blocks will be used to store hot
2854 objects.
29f35ca5
AR
2855
2856 If shared memory caching is enabled, Squid does not use the shared
2857 cache space for in-transit objects, but they still consume as much
2858 local memory as they need. For more details about the shared memory
2859 cache, see memory_cache_shared.
6b698a21 2860DOC_END
0976f8db 2861
41bd17a4 2862NAME: maximum_object_size_in_memory
2863COMMENT: (bytes)
2864TYPE: b_size_t
df2eec10 2865DEFAULT: 512 KB
41bd17a4 2866LOC: Config.Store.maxInMemObjSize
6b698a21 2867DOC_START
41bd17a4 2868 Objects greater than this size will not be attempted to kept in
2869 the memory cache. This should be set high enough to keep objects
2870 accessed frequently in memory to improve performance whilst low
2871 enough to keep larger objects from hoarding cache_mem.
6b698a21 2872DOC_END
0976f8db 2873
57af1e3f
AR
2874NAME: memory_cache_shared
2875COMMENT: on|off
2876TYPE: YesNoNone
2877LOC: Config.memShared
2878DEFAULT: none
70f856bc 2879DEFAULT_DOC: "on" where supported if doing memory caching with multiple SMP workers.
57af1e3f
AR
2880DOC_START
2881 Controls whether the memory cache is shared among SMP workers.
2882
70f856bc
AR
2883 The shared memory cache is meant to occupy cache_mem bytes and replace
2884 the non-shared memory cache, although some entities may still be
2885 cached locally by workers for now (e.g., internal and in-transit
2886 objects may be served from a local memory cache even if shared memory
2887 caching is enabled).
2888
65b81b27 2889 By default, the memory cache is shared if and only if all of the
70f856bc
AR
2890 following conditions are satisfied: Squid runs in SMP mode with
2891 multiple workers, cache_mem is positive, and Squid environment
2892 supports required IPC primitives (e.g., POSIX shared memory segments
2893 and GCC-style atomic operations).
2894
2895 To avoid blocking locks, shared memory uses opportunistic algorithms
2896 that do not guarantee that every cachable entity that could have been
2897 shared among SMP workers will actually be shared.
2898
2899 Currently, entities exceeding 32KB in size cannot be shared.
57af1e3f
AR
2900DOC_END
2901
ea21d497
HN
2902NAME: memory_cache_mode
2903TYPE: memcachemode
2904LOC: Config
2905DEFAULT: always
ff4b33f4 2906DOC_START
ea21d497 2907 Controls which objects to keep in the memory cache (cache_mem)
ff4b33f4 2908
ea21d497
HN
2909 always Keep most recently fetched objects in memory (default)
2910
2911 disk Only disk cache hits are kept in memory, which means
2912 an object must first be cached on disk and then hit
2913 a second time before cached in memory.
2914
2915 network Only objects fetched from network is kept in memory
ff4b33f4
HN
2916DOC_END
2917
41bd17a4 2918NAME: memory_replacement_policy
2919TYPE: removalpolicy
2920LOC: Config.memPolicy
2921DEFAULT: lru
6b698a21 2922DOC_START
41bd17a4 2923 The memory replacement policy parameter determines which
2924 objects are purged from memory when memory space is needed.
7f7db318 2925
41bd17a4 2926 See cache_replacement_policy for details.
2927DOC_END
6b698a21 2928
41bd17a4 2929COMMENT_START
2930 DISK CACHE OPTIONS
2931 -----------------------------------------------------------------------------
2932COMMENT_END
6b698a21 2933
41bd17a4 2934NAME: cache_replacement_policy
2935TYPE: removalpolicy
2936LOC: Config.replPolicy
2937DEFAULT: lru
2938DOC_START
2939 The cache replacement policy parameter determines which
2940 objects are evicted (replaced) when disk space is needed.
6b698a21 2941
41bd17a4 2942 lru : Squid's original list based LRU policy
2943 heap GDSF : Greedy-Dual Size Frequency
2944 heap LFUDA: Least Frequently Used with Dynamic Aging
2945 heap LRU : LRU policy implemented using a heap
6b698a21 2946
41bd17a4 2947 Applies to any cache_dir lines listed below this.
7f7db318 2948
41bd17a4 2949 The LRU policies keeps recently referenced objects.
0976f8db 2950
41bd17a4 2951 The heap GDSF policy optimizes object hit rate by keeping smaller
2952 popular objects in cache so it has a better chance of getting a
2953 hit. It achieves a lower byte hit rate than LFUDA though since
2954 it evicts larger (possibly popular) objects.
0976f8db 2955
41bd17a4 2956 The heap LFUDA policy keeps popular objects in cache regardless of
2957 their size and thus optimizes byte hit rate at the expense of
2958 hit rate since one large, popular object will prevent many
2959 smaller, slightly less popular objects from being cached.
0976f8db 2960
41bd17a4 2961 Both policies utilize a dynamic aging mechanism that prevents
2962 cache pollution that can otherwise occur with frequency-based
2963 replacement policies.
7d90757b 2964
41bd17a4 2965 NOTE: if using the LFUDA replacement policy you should increase
2966 the value of maximum_object_size above its default of 4096 KB to
2967 to maximize the potential byte hit rate improvement of LFUDA.
dc1af3cf 2968
41bd17a4 2969 For more information about the GDSF and LFUDA cache replacement
2970 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
2971 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
6b698a21 2972DOC_END
0976f8db 2973
41bd17a4 2974NAME: cache_dir
2975TYPE: cachedir
2976DEFAULT: none
41bd17a4 2977LOC: Config.cacheSwap
6b698a21 2978DOC_START
41bd17a4 2979 Usage:
0976f8db 2980
41bd17a4 2981 cache_dir Type Directory-Name Fs-specific-data [options]
0976f8db 2982
41bd17a4 2983 You can specify multiple cache_dir lines to spread the
2984 cache among different disk partitions.
0976f8db 2985
41bd17a4 2986 Type specifies the kind of storage system to use. Only "ufs"
2987 is built by default. To enable any of the other storage systems
2988 see the --enable-storeio configure option.
0976f8db 2989
41bd17a4 2990 'Directory' is a top-level directory where cache swap
2991 files will be stored. If you want to use an entire disk
2992 for caching, this can be the mount-point directory.
2993 The directory must exist and be writable by the Squid
2994 process. Squid will NOT create this directory for you.
0976f8db 2995
acf69d74
AJ
2996 In SMP configurations, cache_dir must not precede the workers option
2997 and should use configuration macros or conditionals to give each
2998 worker interested in disk caching a dedicated cache directory.
2999
41bd17a4 3000 The ufs store type:
0976f8db 3001
41bd17a4 3002 "ufs" is the old well-known Squid storage format that has always
3003 been there.
0976f8db 3004
41bd17a4 3005 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
0976f8db 3006
41bd17a4 3007 'Mbytes' is the amount of disk space (MB) to use under this
3008 directory. The default is 100 MB. Change this to suit your
3009 configuration. Do NOT put the size of your disk drive here.
3010 Instead, if you want Squid to use the entire disk drive,
3011 subtract 20% and use that value.
0976f8db 3012
56fba4d0 3013 'L1' is the number of first-level subdirectories which
41bd17a4 3014 will be created under the 'Directory'. The default is 16.
0976f8db 3015
56fba4d0 3016 'L2' is the number of second-level subdirectories which
41bd17a4 3017 will be created under each first-level directory. The default
3018 is 256.
0976f8db 3019
41bd17a4 3020 The aufs store type:
7f7db318 3021
41bd17a4 3022 "aufs" uses the same storage format as "ufs", utilizing
3023 POSIX-threads to avoid blocking the main Squid process on
3024 disk-I/O. This was formerly known in Squid as async-io.
38f9c547 3025
41bd17a4 3026 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
38f9c547 3027
41bd17a4 3028 see argument descriptions under ufs above
38f9c547 3029
41bd17a4 3030 The diskd store type:
38f9c547 3031
41bd17a4 3032 "diskd" uses the same storage format as "ufs", utilizing a
3033 separate process to avoid blocking the main Squid process on
3034 disk-I/O.
4c3ef9b2 3035
41bd17a4 3036 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
0976f8db 3037
41bd17a4 3038 see argument descriptions under ufs above
0976f8db 3039
41bd17a4 3040 Q1 specifies the number of unacknowledged I/O requests when Squid
3041 stops opening new files. If this many messages are in the queues,
3042 Squid won't open new files. Default is 64
0976f8db 3043
41bd17a4 3044 Q2 specifies the number of unacknowledged messages when Squid
3045 starts blocking. If this many messages are in the queues,
3046 Squid blocks until it receives some replies. Default is 72
0976f8db 3047
41bd17a4 3048 When Q1 < Q2 (the default), the cache directory is optimized
3049 for lower response time at the expense of a decrease in hit
3050 ratio. If Q1 > Q2, the cache directory is optimized for
3051 higher hit ratio at the expense of an increase in response
3052 time.
0976f8db 3053
2e55f083 3054 The rock store type:
e2851fe7 3055
df881a0f 3056 cache_dir rock Directory-Name Mbytes <max-size=bytes> [options]
e2851fe7 3057
2e55f083 3058 The Rock Store type is a database-style storage. All cached
e2851fe7
AR
3059 entries are stored in a "database" file, using fixed-size slots,
3060 one entry per slot. The database size is specified in MB. The
3061 slot size is specified in bytes using the max-size option. See
3062 below for more info on the max-size option.
3063
43ebbac3
AR
3064 swap-timeout=msec: Squid will not start writing a miss to or
3065 reading a hit from disk if it estimates that the swap operation
3066 will take more than the specified number of milliseconds. By
3067 default and when set to zero, disables the disk I/O time limit
3068 enforcement. Ignored when using blocking I/O module because
3069 blocking synchronous I/O does not allow Squid to estimate the
3070 expected swap wait time.
3071
df881a0f 3072 max-swap-rate=swaps/sec: Artificially limits disk access using
1e614370 3073 the specified I/O rate limit. Swap out requests that
df881a0f 3074 would cause the average I/O rate to exceed the limit are
1e614370
DK
3075 delayed. Individual swap in requests (i.e., hits or reads) are
3076 not delayed, but they do contribute to measured swap rate and
3077 since they are placed in the same FIFO queue as swap out
3078 requests, they may wait longer if max-swap-rate is smaller.
3079 This is necessary on file systems that buffer "too
df881a0f
AR
3080 many" writes and then start blocking Squid and other processes
3081 while committing those writes to disk. Usually used together
3082 with swap-timeout to avoid excessive delays and queue overflows
3083 when disk demand exceeds available disk "bandwidth". By default
3084 and when set to zero, disables the disk I/O rate limit
3085 enforcement. Currently supported by IpcIo module only.
3086
3087
41bd17a4 3088 The coss store type:
0976f8db 3089
db263d62
AJ
3090 NP: COSS filesystem in Squid-3 has been deemed too unstable for
3091 production use and has thus been removed from this release.
3092 We hope that it can be made usable again soon.
3093
41bd17a4 3094 block-size=n defines the "block size" for COSS cache_dir's.
3095 Squid uses file numbers as block numbers. Since file numbers
3096 are limited to 24 bits, the block size determines the maximum
3097 size of the COSS partition. The default is 512 bytes, which
3098 leads to a maximum cache_dir size of 512<<24, or 8 GB. Note
3099 you should not change the coss block size after Squid
3100 has written some objects to the cache_dir.
0976f8db 3101
41bd17a4 3102 The coss file store has changed from 2.5. Now it uses a file
3103 called 'stripe' in the directory names in the config - and
3104 this will be created by squid -z.
0976f8db 3105
41bd17a4 3106 Common options:
0976f8db 3107
41bd17a4 3108 no-store, no new objects should be stored to this cache_dir
0976f8db 3109
b6662ffd
AJ
3110 min-size=n, refers to the min object size in bytes this cache_dir
3111 will accept. It's used to restrict a cache_dir to only store
3112 large objects (e.g. aufs) while other storedirs are optimized
3113 for smaller objects (e.g. COSS). Defaults to 0.
3114
00a6e30a
HN
3115 max-size=n, refers to the max object size in bytes this cache_dir
3116 supports. It is used to select the cache_dir to store the object.
41bd17a4 3117 Note: To make optimal use of the max-size limits you should order
3118 the cache_dir lines with the smallest max-size value first and the
3119 ones with no max-size specification last.
0976f8db 3120
41bd17a4 3121 Note for coss, max-size must be less than COSS_MEMBUF_SZ,
3122 which can be changed with the --with-coss-membuf-size=N configure
3123 option.
bebc043b 3124NOCOMMENT_START
e0855596
AJ
3125
3126# Uncomment and adjust the following to add a disk cache directory.
3127#cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
bebc043b 3128NOCOMMENT_END
6b698a21 3129DOC_END
0976f8db 3130
41bd17a4 3131NAME: store_dir_select_algorithm
3132TYPE: string
3133LOC: Config.store_dir_select_algorithm
3134DEFAULT: least-load
6b698a21 3135DOC_START
41bd17a4 3136 Set this to 'round-robin' as an alternative.
6b698a21 3137DOC_END
0976f8db 3138
41bd17a4 3139NAME: max_open_disk_fds
3140TYPE: int
3141LOC: Config.max_open_disk_fds
3142DEFAULT: 0
6b698a21 3143DOC_START
41bd17a4 3144 To avoid having disk as the I/O bottleneck Squid can optionally
3145 bypass the on-disk cache if more than this amount of disk file
3146 descriptors are open.
3147
3148 A value of 0 indicates no limit.
6b698a21 3149DOC_END
0976f8db 3150
41bd17a4 3151NAME: minimum_object_size
6b698a21 3152COMMENT: (bytes)
47f6e231 3153TYPE: b_int64_t
6b698a21 3154DEFAULT: 0 KB
41bd17a4 3155LOC: Config.Store.minObjectSize
6b698a21 3156DOC_START
41bd17a4 3157 Objects smaller than this size will NOT be saved on disk. The
3158 value is specified in kilobytes, and the default is 0 KB, which
3159 means there is no minimum.
6b698a21 3160DOC_END
0976f8db 3161
41bd17a4 3162NAME: maximum_object_size
3163COMMENT: (bytes)
3164TYPE: b_int64_t
3165DEFAULT: 4096 KB
3166LOC: Config.Store.maxObjectSize
777831e0 3167DOC_START
41bd17a4 3168 Objects larger than this size will NOT be saved on disk. The
3169 value is specified in kilobytes, and the default is 4MB. If
3170 you wish to get a high BYTES hit ratio, you should probably
3171 increase this (one 32 MB object hit counts for 3200 10KB
3172 hits). If you wish to increase speed more than your want to
3173 save bandwidth you should leave this low.
777831e0 3174
41bd17a4 3175 NOTE: if using the LFUDA replacement policy you should increase
3176 this value to maximize the byte hit rate improvement of LFUDA!
3177 See replacement_policy below for a discussion of this policy.
6b698a21 3178DOC_END
0976f8db 3179
41bd17a4 3180NAME: cache_swap_low
3181COMMENT: (percent, 0-100)
5473c134 3182TYPE: int
41bd17a4 3183DEFAULT: 90
3184LOC: Config.Swap.lowWaterMark
3185DOC_NONE
3186
3187NAME: cache_swap_high
3188COMMENT: (percent, 0-100)
3189TYPE: int
3190DEFAULT: 95
3191LOC: Config.Swap.highWaterMark
6b698a21 3192DOC_START
41bd17a4 3193
3194 The low- and high-water marks for cache object replacement.
3195 Replacement begins when the swap (disk) usage is above the
3196 low-water mark and attempts to maintain utilization near the
3197 low-water mark. As swap utilization gets close to high-water
3198 mark object eviction becomes more aggressive. If utilization is
3199 close to the low-water mark less replacement is done each time.
3200
3201 Defaults are 90% and 95%. If you have a large cache, 5% could be
3202 hundreds of MB. If this is the case you may wish to set these
3203 numbers closer together.
6b698a21 3204DOC_END
0976f8db 3205
5473c134 3206COMMENT_START
41bd17a4 3207 LOGFILE OPTIONS
5473c134 3208 -----------------------------------------------------------------------------
3209COMMENT_END
0976f8db 3210
41bd17a4 3211NAME: logformat
3212TYPE: logformat
20efa1c2 3213LOC: Log::TheConfig
5473c134 3214DEFAULT: none
6b698a21 3215DOC_START
41bd17a4 3216 Usage:
0976f8db 3217
41bd17a4 3218 logformat <name> <format specification>
0976f8db 3219
41bd17a4 3220 Defines an access log format.
6b698a21 3221
41bd17a4 3222 The <format specification> is a string with embedded % format codes
5473c134 3223
41bd17a4 3224 % format codes all follow the same basic structure where all but
3225 the formatcode is optional. Output strings are automatically escaped
3226 as required according to their context and the output format
3227 modifiers are usually not needed, but can be specified if an explicit
3228 output format is desired.
6b698a21 3229
41bd17a4 3230 % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
0976f8db 3231
41bd17a4 3232 " output in quoted string format
3233 [ output in squid text log format as used by log_mime_hdrs
3234 # output in URL quoted format
3235 ' output as-is
5473c134 3236
41bd17a4 3237 - left aligned
c32c6db7
AR
3238
3239 width minimum and/or maximum field width:
3240 [width_min][.width_max]
e2851fe7
AR
3241 When minimum starts with 0, the field is zero-padded.
3242 String values exceeding maximum width are truncated.
c32c6db7 3243
41bd17a4 3244 {arg} argument such as header name etc
5473c134 3245
41bd17a4 3246 Format codes:
5473c134 3247
3ff65596 3248 % a literal % character
f4b68e1a
AJ
3249 sn Unique sequence number per log line entry
3250 err_code The ID of an error response served by Squid or
3251 a similar internal error identifier.
3252 err_detail Additional err_code-dependent error information.
3253
3254 Connection related format codes:
3255
41bd17a4 3256 >a Client source IP address
3257 >A Client FQDN
3258 >p Client source port
8652f8e7
AJ
3259 >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier)
3260 >la Local IP address the client connected to
3261 >lp Local port number the client connected to
3262
28417506
CT
3263 la Local listening IP address the client connection was connected to.
3264 lp Local listening port number the client connection was connected to.
3265
8652f8e7
AJ
3266 <a Server IP address of the last server or peer connection
3267 <A Server FQDN or peer name
3268 <p Server port number of the last server or peer connection
c3a082ae 3269 <la Local IP address of the last server or peer connection
152e24b3 3270 <lp Local port number of the last server or peer connection
f4b68e1a
AJ
3271
3272 Time related format codes:
3273
41bd17a4 3274 ts Seconds since epoch
3275 tu subsecond time (milliseconds)
3276 tl Local time. Optional strftime format argument
3ff65596 3277 default %d/%b/%Y:%H:%M:%S %z
41bd17a4 3278 tg GMT time. Optional strftime format argument
3ff65596 3279 default %d/%b/%Y:%H:%M:%S %z
41bd17a4 3280 tr Response time (milliseconds)
3ff65596
AR
3281 dt Total time spent making DNS lookups (milliseconds)
3282
8652f8e7
AJ
3283 Access Control related format codes:
3284
3285 et Tag returned by external acl
3286 ea Log string returned by external acl
3287 un User name (any available)
3288 ul User name from authentication
3289 ue User name from external acl helper
3290 ui User name from ident
3291 us User name from SSL
3292
3293 HTTP related format codes:
3ff65596 3294
ca2e92d8 3295 [http::]>h Original request header. Optional header name argument
3ff65596 3296 on the format header[:[separator]element]
6fca33e0
CT
3297 [http::]>ha The HTTP request headers after adaptation and redirection.
3298 Optional header name argument as for >h
3ff65596
AR
3299 [http::]<h Reply header. Optional header name argument
3300 as for >h
3ff65596
AR
3301 [http::]>Hs HTTP status code sent to the client
3302 [http::]<Hs HTTP status code received from the next hop
bae917ac
CT
3303 [http::]<bs Number of HTTP-equivalent message body bytes
3304 received from the next hop, excluding chunked
3305 transfer encoding and control messages.
3306 Generated FTP/Gopher listings are treated as
3307 received bodies.
3ff65596
AR
3308 [http::]mt MIME content type
3309 [http::]rm Request method (GET/POST etc)
f025622f
AJ
3310 [http::]>rm Request method from client
3311 [http::]<rm Request method sent to server or peer
3312 [http::]ru Request URL from client (historic, filtered for logging)
3313 [http::]>ru Request URL from client
3314 [http::]<ru Request URL sent to server or peer
3ff65596 3315 [http::]rp Request URL-Path excluding hostname
f025622f
AJ
3316 [http::]>rp Request URL-Path excluding hostname from client
3317 [http::]<rp Request URL-Path excluding hostname sento to server or peer
3ff65596 3318 [http::]rv Request protocol version
f025622f
AJ
3319 [http::]>rv Request protocol version from client
3320 [http::]<rv Request protocol version sent to server or peer
3ff65596
AR
3321 [http::]<st Sent reply size including HTTP headers
3322 [http::]>st Received request size including HTTP headers. In the
3323 case of chunked requests the chunked encoding metadata
3324 are not included
3325 [http::]>sh Received HTTP request headers size
3326 [http::]<sh Sent HTTP reply headers size
3327 [http::]st Request+Reply size including HTTP headers
3328 [http::]<sH Reply high offset sent
3329 [http::]<sS Upstream object size
3330 [http::]<pt Peer response time in milliseconds. The timer starts
3331 when the last request byte is sent to the next hop
3332 and stops when the last response byte is received.
3333 [http::]<tt Total server-side time in milliseconds. The timer
3334 starts with the first connect request (or write I/O)
3335 sent to the first selected peer. The timer stops
3336 with the last I/O with the last peer.
3337
8652f8e7
AJ
3338 Squid handling related format codes:
3339
3340 Ss Squid request status (TCP_MISS etc)
3341 Sh Squid hierarchy status (DEFAULT_PARENT etc)
3342
5038f9d8 3343 If ICAP is enabled, the following code becomes available (as
3ff65596
AR
3344 well as ICAP log codes documented with the icap_log option):
3345
3346 icap::tt Total ICAP processing time for the HTTP
3347 transaction. The timer ticks when ICAP
3348 ACLs are checked and when ICAP
3349 transaction is in progress.
3350
5038f9d8 3351 If adaptation is enabled the following three codes become available:
3ff65596 3352
5038f9d8
AR
3353 adapt::<last_h The header of the last ICAP response or
3354 meta-information from the last eCAP
3355 transaction related to the HTTP transaction.
3356 Like <h, accepts an optional header name
3357 argument.
3ff65596
AR
3358
3359 adapt::sum_trs Summed adaptation transaction response
3360 times recorded as a comma-separated list in
3361 the order of transaction start time. Each time
3362 value is recorded as an integer number,
3363 representing response time of one or more
3364 adaptation (ICAP or eCAP) transaction in
3365 milliseconds. When a failed transaction is
3366 being retried or repeated, its time is not
3367 logged individually but added to the
3368 replacement (next) transaction. See also:
3369 adapt::all_trs.
3370
3371 adapt::all_trs All adaptation transaction response times.
3372 Same as adaptation_strs but response times of
3373 individual transactions are never added
3374 together. Instead, all transaction response
3375 times are recorded individually.
3376
3377 You can prefix adapt::*_trs format codes with adaptation
3378 service name in curly braces to record response time(s) specific
3379 to that service. For example: %{my_service}adapt::sum_trs
5473c134 3380
7d9acc3c
AJ
3381 The default formats available (which do not need re-defining) are:
3382
bd85ea1f
AJ
3383logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
3384logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
3385logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
20efa1c2
AJ
3386logformat referrer %ts.%03tu %>a %{Referer}>h %ru
3387logformat useragent %>a [%tl] "%{User-Agent}>h"
3388
8652f8e7
AJ
3389 NOTE: When the log_mime_hdrs directive is set to ON.
3390 The squid, common and combined formats have a safely encoded copy
3391 of the mime headers appended to each line within a pair of brackets.
3392
3393 NOTE: The common and combined formats are not quite true to the Apache definition.
3394 The logs from Squid contain an extra status and hierarchy code appended.
20efa1c2 3395
5473c134 3396DOC_END
3397
41bd17a4 3398NAME: access_log cache_access_log
3399TYPE: access_log
3400LOC: Config.Log.accesslogs
82b7abe3 3401DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
5473c134 3402DOC_START
41bd17a4 3403 These files log client request activities. Has a line every HTTP or
3404 ICP request. The format is:
82b7abe3 3405 access_log <module>:<place> [<logformat name> [acl acl ...]]
41bd17a4 3406 access_log none [acl acl ...]]
82b7abe3
AJ
3407
3408 Will log to the specified module:place using the specified format (which
41bd17a4 3409 must be defined in a logformat directive) those entries which match
3410 ALL the acl's specified (which must be defined in acl clauses).
82b7abe3
AJ
3411 If no acl is specified, all requests will be logged to this destination.
3412
3413 ===== Modules Currently available =====
3414
bb7a1781 3415 none Do not log any requests matching these ACL.
82b7abe3
AJ
3416 Do not specify Place or logformat name.
3417
3418 stdio Write each log line to disk immediately at the completion of
3419 each request.
3420 Place: the filename and path to be written.
3421
3422 daemon Very similar to stdio. But instead of writing to disk the log
3423 line is passed to a daemon helper for asychronous handling instead.
3424 Place: varies depending on the daemon.
3425
3426 log_file_daemon Place: the file name and path to be written.
3427
3428 syslog To log each request via syslog facility.
3429 Place: The syslog facility and priority level for these entries.
3430 Place Format: facility.priority
5473c134 3431
82b7abe3
AJ
3432 where facility could be any of:
3433 authpriv, daemon, local0 ... local7 or user.
5473c134 3434
82b7abe3
AJ
3435 And priority could be any of:
3436 err, warning, notice, info, debug.
3437
3438 udp To send each log line as text data to a UDP receiver.
3439 Place: The destination host name or IP and port.
f4fc8610 3440 Place Format: //host:port
df2eec10 3441
2bf4e8fa
AJ
3442 tcp To send each log line as text data to a TCP receiver.
3443 Place: The destination host name or IP and port.
f4fc8610 3444 Place Format: //host:port
df2eec10
AJ
3445
3446 Default:
82b7abe3 3447 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
41bd17a4 3448DOC_END
5473c134 3449
3ff65596
AR
3450NAME: icap_log
3451TYPE: access_log
3452IFDEF: ICAP_CLIENT
3453LOC: Config.Log.icaplogs
3454DEFAULT: none
3455DOC_START
3456 ICAP log files record ICAP transaction summaries, one line per
3457 transaction.
3458
3459 The icap_log option format is:
3460 icap_log <filepath> [<logformat name> [acl acl ...]]
3461 icap_log none [acl acl ...]]
3462
3463 Please see access_log option documentation for details. The two
3464 kinds of logs share the overall configuration approach and many
3465 features.
3466
3467 ICAP processing of a single HTTP message or transaction may
3468 require multiple ICAP transactions. In such cases, multiple
3469 ICAP transaction log lines will correspond to a single access
3470 log line.
3471
3472 ICAP log uses logformat codes that make sense for an ICAP
3473 transaction. Header-related codes are applied to the HTTP header
3474 embedded in an ICAP server response, with the following caveats:
3475 For REQMOD, there is no HTTP response header unless the ICAP
3476 server performed request satisfaction. For RESPMOD, the HTTP
3477 request header is the header sent to the ICAP server. For
3478 OPTIONS, there are no HTTP headers.
3479
3480 The following format codes are also available for ICAP logs:
3481
3482 icap::<A ICAP server IP address. Similar to <A.
3483
3484 icap::<service_name ICAP service name from the icap_service
3485 option in Squid configuration file.
3486
3487 icap::ru ICAP Request-URI. Similar to ru.
3488
3489 icap::rm ICAP request method (REQMOD, RESPMOD, or
3490 OPTIONS). Similar to existing rm.
3491
3492 icap::>st Bytes sent to the ICAP server (TCP payload
3493 only; i.e., what Squid writes to the socket).
3494
3495 icap::<st Bytes received from the ICAP server (TCP
3496 payload only; i.e., what Squid reads from
3497 the socket).
3498
bae917ac
CT
3499 icap::<bs Number of message body bytes received from the
3500 ICAP server. ICAP message body, if any, usually
3501 includes encapsulated HTTP message headers and
3502 possibly encapsulated HTTP message body. The
3503 HTTP body part is dechunked before its size is
3504 computed.
3505
3ff65596
AR
3506 icap::tr Transaction response time (in
3507 milliseconds). The timer starts when
3508 the ICAP transaction is created and
3509 stops when the transaction is completed.
3510 Similar to tr.
3511
3512 icap::tio Transaction I/O time (in milliseconds). The
3513 timer starts when the first ICAP request
3514 byte is scheduled for sending. The timers
3515 stops when the last byte of the ICAP response
3516 is received.
3517
3518 icap::to Transaction outcome: ICAP_ERR* for all
3519 transaction errors, ICAP_OPT for OPTION
3520 transactions, ICAP_ECHO for 204
3521 responses, ICAP_MOD for message
3522 modification, and ICAP_SAT for request
3523 satisfaction. Similar to Ss.
3524
3525 icap::Hs ICAP response status code. Similar to Hs.
3526
3527 icap::>h ICAP request header(s). Similar to >h.
3528
3529 icap::<h ICAP response header(s). Similar to <h.
3530
3531 The default ICAP log format, which can be used without an explicit
3532 definition, is called icap_squid:
3533
3534logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
3535
5038f9d8 3536 See also: logformat, log_icap, and %adapt::<last_h
3ff65596
AR
3537DOC_END
3538
82b7abe3
AJ
3539NAME: logfile_daemon
3540TYPE: string
3541DEFAULT: @DEFAULT_LOGFILED@
3542LOC: Log::TheConfig.logfile_daemon
3543DOC_START
3544 Specify the path to the logfile-writing daemon. This daemon is
3545 used to write the access and store logs, if configured.
14b24caf
HN
3546
3547 Squid sends a number of commands to the log daemon:
3548 L<data>\n - logfile data
3549 R\n - rotate file
3550 T\n - truncate file
dd68402f 3551 O\n - reopen file
14b24caf
HN
3552 F\n - flush file
3553 r<n>\n - set rotate count to <n>
3554 b<n>\n - 1 = buffer output, 0 = don't buffer output
3555
3556 No responses is expected.
82b7abe3
AJ
3557DOC_END
3558
5b0f5383 3559NAME: log_access
3560TYPE: acl_access
3561LOC: Config.accessList.log
3562DEFAULT: none
3563COMMENT: allow|deny acl acl...
3564DOC_START
3565 This options allows you to control which requests gets logged
3566 to access.log (see access_log directive). Requests denied for
3567 logging will also not be accounted for in performance counters.
b3567eb5
FC
3568
3569 This clause only supports fast acl types.
3570 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5b0f5383 3571DOC_END
3572
3ff65596
AR
3573NAME: log_icap
3574TYPE: acl_access
3575IFDEF: ICAP_CLIENT
3576LOC: Config.accessList.icap
3577DEFAULT: none
3578DOC_START
3579 This options allows you to control which requests get logged
3580 to icap.log. See the icap_log directive for ICAP log details.
3581DOC_END
3582
41bd17a4 3583NAME: cache_store_log
3584TYPE: string
df2eec10 3585DEFAULT: none
41bd17a4 3586LOC: Config.Log.store
3587DOC_START
3588 Logs the activities of the storage manager. Shows which
3589 objects are ejected from the cache, and which objects are
df2eec10
AJ
3590 saved and for how long. To disable, enter "none" or remove the line.
3591 There are not really utilities to analyze this data, so you can safely
41bd17a4 3592 disable it.
e0855596
AJ
3593
3594 Example:
3595 cache_store_log @DEFAULT_STORE_LOG@
5473c134 3596DOC_END
3597
41bd17a4 3598NAME: cache_swap_state cache_swap_log
3599TYPE: string
3600LOC: Config.Log.swap
5473c134 3601DEFAULT: none
3602DOC_START
41bd17a4 3603 Location for the cache "swap.state" file. This index file holds
3604 the metadata of objects saved on disk. It is used to rebuild
3605 the cache during startup. Normally this file resides in each
3606 'cache_dir' directory, but you may specify an alternate
3607 pathname here. Note you must give a full filename, not just
3608 a directory. Since this is the index for the whole object
3609 list you CANNOT periodically rotate it!
5473c134 3610
41bd17a4 3611 If %s can be used in the file name it will be replaced with a
3612 a representation of the cache_dir name where each / is replaced
3613 with '.'. This is needed to allow adding/removing cache_dir
3614 lines when cache_swap_log is being used.
5473c134 3615
41bd17a4 3616 If have more than one 'cache_dir', and %s is not used in the name
3617 these swap logs will have names such as:
5473c134 3618
41bd17a4 3619 cache_swap_log.00
3620 cache_swap_log.01
3621 cache_swap_log.02
5473c134 3622
41bd17a4 3623 The numbered extension (which is added automatically)
3624 corresponds to the order of the 'cache_dir' lines in this
3625 configuration file. If you change the order of the 'cache_dir'
3626 lines in this file, these index files will NOT correspond to
3627 the correct 'cache_dir' entry (unless you manually rename
3628 them). We recommend you do NOT use this option. It is
3629 better to keep these index files in each 'cache_dir' directory.
5473c134 3630DOC_END
3631
41bd17a4 3632NAME: logfile_rotate
3633TYPE: int
3634DEFAULT: 10
3635LOC: Config.Log.rotateNumber
5473c134 3636DOC_START
41bd17a4 3637 Specifies the number of logfile rotations to make when you
3638 type 'squid -k rotate'. The default is 10, which will rotate
3639 with extensions 0 through 9. Setting logfile_rotate to 0 will
3640 disable the file name rotation, but the logfiles are still closed
3641 and re-opened. This will enable you to rename the logfiles
3642 yourself just before sending the rotate signal.
5473c134 3643
41bd17a4 3644 Note, the 'squid -k rotate' command normally sends a USR1
3645 signal to the running squid process. In certain situations
3646 (e.g. on Linux with Async I/O), USR1 is used for other
3647 purposes, so -k rotate uses another signal. It is best to get
3648 in the habit of using 'squid -k rotate' instead of 'kill -USR1
3649 <pid>'.
62493678
AJ
3650
3651 Note, from Squid-3.1 this option has no effect on the cache.log,
3652 that log can be rotated separately by using debug_options
41bd17a4 3653DOC_END
5473c134 3654
41bd17a4 3655NAME: emulate_httpd_log
20efa1c2 3656TYPE: obsolete
41bd17a4 3657DOC_START
20efa1c2 3658 Replace this with an access_log directive using the format 'common' or 'combined'.
5473c134 3659DOC_END
3660
41bd17a4 3661NAME: log_ip_on_direct
8652f8e7 3662TYPE: obsolete
5473c134 3663DOC_START
8652f8e7 3664 Remove this option from your config. To log server or peer names use %<A in the log format.
41bd17a4 3665DOC_END
5473c134 3666
41bd17a4 3667NAME: mime_table
3668TYPE: string
3669DEFAULT: @DEFAULT_MIME_TABLE@
3670LOC: Config.mimeTablePathname
3671DOC_START
3672 Pathname to Squid's MIME table. You shouldn't need to change
3673 this, but the default file contains examples and formatting
3674 information if you do.
5473c134 3675DOC_END
3676
41bd17a4 3677NAME: log_mime_hdrs
3678COMMENT: on|off
3679TYPE: onoff
3680LOC: Config.onoff.log_mime_hdrs
3681DEFAULT: off
3682DOC_START
3683 The Cache can record both the request and the response MIME
3684 headers for each HTTP transaction. The headers are encoded
3685 safely and will appear as two bracketed fields at the end of
3686 the access log (for either the native or httpd-emulated log
3687 formats). To enable this logging set log_mime_hdrs to 'on'.
3688DOC_END
5473c134 3689
41bd17a4 3690NAME: useragent_log
20efa1c2 3691TYPE: obsolete
5473c134 3692DOC_START
20efa1c2 3693 Replace this with an access_log directive using the format 'useragent'.
5473c134 3694DOC_END
3695
41bd17a4 3696NAME: referer_log referrer_log
20efa1c2 3697TYPE: obsolete
5473c134 3698DOC_START
20efa1c2 3699 Replace this with an access_log directive using the format 'referrer'.
5473c134 3700DOC_END
3701
41bd17a4 3702NAME: pid_filename
3703TYPE: string
3704DEFAULT: @DEFAULT_PID_FILE@
3705LOC: Config.pidFilename
5473c134 3706DOC_START
41bd17a4 3707 A filename to write the process-id to. To disable, enter "none".
5473c134 3708DOC_END
3709
41bd17a4 3710NAME: log_fqdn
c581e96b 3711TYPE: obsolete
5473c134 3712DOC_START
c581e96b 3713 Remove this option from your config. To log FQDN use %>A in the log format.
5473c134 3714DOC_END
3715
41bd17a4 3716NAME: client_netmask
3717TYPE: address
3718LOC: Config.Addrs.client_netmask
0eb08770 3719DEFAULT: no_addr
5473c134 3720DOC_START
41bd17a4 3721 A netmask for client addresses in logfiles and cachemgr output.
3722 Change this to protect the privacy of your cache clients.
3723 A netmask of 255.255.255.0 will log all IP's in that range with
3724 the last digit set to '0'.
5473c134 3725DOC_END
3726
41bd17a4 3727NAME: forward_log
20efa1c2 3728TYPE: obsolete
5473c134 3729DOC_START
20efa1c2 3730 Use a regular access.log with ACL limiting it to MISS events.
5473c134 3731DOC_END
3732
41bd17a4 3733NAME: strip_query_terms
5473c134 3734TYPE: onoff
41bd17a4 3735LOC: Config.onoff.strip_query_terms
5473c134 3736DEFAULT: on
3737DOC_START
41bd17a4 3738 By default, Squid strips query terms from requested URLs before
3739 logging. This protects your user's privacy.
5473c134 3740DOC_END
3741
41bd17a4 3742NAME: buffered_logs
3743COMMENT: on|off
3744TYPE: onoff
3745DEFAULT: off
3746LOC: Config.onoff.buffered_logs
5473c134 3747DOC_START
41bd17a4 3748 cache.log log file is written with stdio functions, and as such
3749 it can be buffered or unbuffered. By default it will be unbuffered.
3750 Buffering it can speed up the writing slightly (though you are
3751 unlikely to need to worry unless you run with tons of debugging
3752 enabled in which case performance will suffer badly anyway..).
6b698a21 3753DOC_END
0976f8db 3754
2b753521 3755NAME: netdb_filename
3756TYPE: string
221faecb 3757DEFAULT: stdio:@DEFAULT_NETDB_FILE@
2b753521 3758LOC: Config.netdbFilename
fb6a61d1 3759IFDEF: USE_ICMP
2b753521 3760DOC_START
3761 A filename where Squid stores it's netdb state between restarts.
3762 To disable, enter "none".
3763DOC_END
3764
62493678
AJ
3765COMMENT_START
3766 OPTIONS FOR TROUBLESHOOTING
3767 -----------------------------------------------------------------------------
3768COMMENT_END
3769
3770NAME: cache_log
3771TYPE: string
62493678
AJ
3772DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
3773LOC: Debug::cache_log
3774DOC_START
3775 Cache logging file. This is where general information about
3776 your cache's behavior goes. You can increase the amount of data
3777 logged to this file and how often its rotated with "debug_options"
3778DOC_END
3779
3780NAME: debug_options
3781TYPE: eol
47df1aa7 3782DEFAULT: ALL,1
62493678
AJ
3783LOC: Debug::debugOptions
3784DOC_START
3785 Logging options are set as section,level where each source file
3786 is assigned a unique section. Lower levels result in less
3787 output, Full debugging (level 9) can result in a very large
3788 log file, so be careful.
3789
3790 The magic word "ALL" sets debugging levels for all sections.
3791 We recommend normally running with "ALL,1".
3792
47df1aa7
AJ
3793 The rotate=N option can be used to keep more or less of these logs
3794 than would otherwise be kept by logfile_rotate.
62493678
AJ
3795 For most uses a single log should be enough to monitor current
3796 events affecting Squid.
3797DOC_END
3798
3799NAME: coredump_dir
3800TYPE: string
3801LOC: Config.coredump_dir
62493678
AJ
3802DEFAULT_IF_NONE: none
3803DOC_START
3804 By default Squid leaves core files in the directory from where
3805 it was started. If you set 'coredump_dir' to a directory
3806 that exists, Squid will chdir() to that directory at startup
3807 and coredump files will be left there.
3808
3809NOCOMMENT_START
e0855596 3810
62493678
AJ
3811# Leave coredumps in the first cache dir
3812coredump_dir @DEFAULT_SWAP_DIR@
3813NOCOMMENT_END
3814DOC_END
3815
3816
41bd17a4 3817COMMENT_START
3818 OPTIONS FOR FTP GATEWAYING
3819 -----------------------------------------------------------------------------
3820COMMENT_END
3821
3822NAME: ftp_user
3823TYPE: string
3824DEFAULT: Squid@
3825LOC: Config.Ftp.anon_user
6b698a21 3826DOC_START
41bd17a4 3827 If you want the anonymous login password to be more informative
3828 (and enable the use of picky ftp servers), set this to something
3829 reasonable for your domain, like wwwuser@somewhere.net
7f7db318 3830
41bd17a4 3831 The reason why this is domainless by default is the
3832 request can be made on the behalf of a user in any domain,
3833 depending on how the cache is used.
3834 Some ftp server also validate the email address is valid
3835 (for example perl.com).
6b698a21 3836DOC_END
0976f8db 3837
41bd17a4 3838NAME: ftp_passive
3839TYPE: onoff
3840DEFAULT: on
3841LOC: Config.Ftp.passive
6b698a21 3842DOC_START
41bd17a4 3843 If your firewall does not allow Squid to use passive
3844 connections, turn off this option.
a689bd4e 3845
3846 Use of ftp_epsv_all option requires this to be ON.
3847DOC_END
3848
3849NAME: ftp_epsv_all
3850TYPE: onoff
3851DEFAULT: off
3852LOC: Config.Ftp.epsv_all
3853DOC_START
3854 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
3855
3856 NATs may be able to put the connection on a "fast path" through the
3857 translator, as the EPRT command will never be used and therefore,
3858 translation of the data portion of the segments will never be needed.
3859
b3567eb5
FC
3860 When a client only expects to do two-way FTP transfers this may be
3861 useful.
a689bd4e 3862 If squid finds that it must do a three-way FTP transfer after issuing
3863 an EPSV ALL command, the FTP session will fail.
3864
3865 If you have any doubts about this option do not use it.
3866 Squid will nicely attempt all other connection methods.
3867
51ee534d
AJ
3868 Requires ftp_passive to be ON (default) for any effect.
3869DOC_END
3870
3871NAME: ftp_epsv
3872TYPE: onoff
3873DEFAULT: on
3874LOC: Config.Ftp.epsv
3875DOC_START
3876 FTP Protocol extensions permit the use of a special "EPSV" command.
3877
3878 NATs may be able to put the connection on a "fast path" through the
b3567eb5
FC
3879 translator using EPSV, as the EPRT command will never be used
3880 and therefore, translation of the data portion of the segments
3881 will never be needed.
51ee534d
AJ
3882
3883 Turning this OFF will prevent EPSV being attempted.
3884 WARNING: Doing so will convert Squid back to the old behavior with all
3885 the related problems with external NAT devices/layers.
3886
3887 Requires ftp_passive to be ON (default) for any effect.
41bd17a4 3888DOC_END
9e7dbc51 3889
63ee5443
AJ
3890NAME: ftp_eprt
3891TYPE: onoff
3892DEFAULT: on
3893LOC: Config.Ftp.eprt
3894DOC_START
3895 FTP Protocol extensions permit the use of a special "EPRT" command.
3896
3897 This extension provides a protocol neutral alternative to the
3898 IPv4-only PORT command. When supported it enables active FTP data
3899 channels over IPv6 and efficient NAT handling.
3900
3901 Turning this OFF will prevent EPRT being attempted and will skip
3902 straight to using PORT for IPv4 servers.
3903
3904 Some devices are known to not handle this extension correctly and
3905 may result in crashes. Devices which suport EPRT enough to fail
3906 cleanly will result in Squid attempting PORT anyway. This directive
3907 should only be disabled when EPRT results in device failures.
3908
3909 WARNING: Doing so will convert Squid back to the old behavior with all
3910 the related problems with external NAT devices/layers and IPv4-only FTP.
3911DOC_END
3912
41bd17a4 3913NAME: ftp_sanitycheck
3914TYPE: onoff
3915DEFAULT: on
3916LOC: Config.Ftp.sanitycheck
3917DOC_START
3918 For security and data integrity reasons Squid by default performs
3919 sanity checks of the addresses of FTP data connections ensure the
3920 data connection is to the requested server. If you need to allow
3921 FTP connections to servers using another IP address for the data
3922 connection turn this off.
3923DOC_END
9e7dbc51 3924
41bd17a4 3925NAME: ftp_telnet_protocol
3926TYPE: onoff
3927DEFAULT: on
3928LOC: Config.Ftp.telnet
3929DOC_START
3930 The FTP protocol is officially defined to use the telnet protocol
3931 as transport channel for the control connection. However, many
3932 implementations are broken and does not respect this aspect of
3933 the FTP protocol.
3934
3935 If you have trouble accessing files with ASCII code 255 in the
3936 path or similar problems involving this ASCII code you can
3937 try setting this directive to off. If that helps, report to the
3938 operator of the FTP server in question that their FTP server
3939 is broken and does not follow the FTP standard.
3940DOC_END
3941
3942COMMENT_START
3943 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
3944 -----------------------------------------------------------------------------
3945COMMENT_END
3946
3947NAME: diskd_program
3948TYPE: string
3949DEFAULT: @DEFAULT_DISKD@
3950LOC: Config.Program.diskd
3951DOC_START
3952 Specify the location of the diskd executable.
3953 Note this is only useful if you have compiled in
3954 diskd as one of the store io modules.
3955DOC_END
3956
3957NAME: unlinkd_program
3958IFDEF: USE_UNLINKD
3959TYPE: string
3960DEFAULT: @DEFAULT_UNLINKD@
3961LOC: Config.Program.unlinkd
3962DOC_START
3963 Specify the location of the executable for file deletion process.
3964DOC_END
3965
3966NAME: pinger_program
3967TYPE: string
3968DEFAULT: @DEFAULT_PINGER@
cc192b50 3969LOC: Config.pinger.program
41bd17a4 3970IFDEF: USE_ICMP
3971DOC_START
3972 Specify the location of the executable for the pinger process.
3973DOC_END
3974
cc192b50 3975NAME: pinger_enable
3976TYPE: onoff
3977DEFAULT: on
3978LOC: Config.pinger.enable
3979IFDEF: USE_ICMP
3980DOC_START
3981 Control whether the pinger is active at run-time.
b3567eb5
FC
3982 Enables turning ICMP pinger on and off with a simple
3983 squid -k reconfigure.
cc192b50 3984DOC_END
3985
3986
41bd17a4 3987COMMENT_START
3988 OPTIONS FOR URL REWRITING
3989 -----------------------------------------------------------------------------
3990COMMENT_END
3991
3992NAME: url_rewrite_program redirect_program
3993TYPE: wordlist
3994LOC: Config.Program.redirect
3995DEFAULT: none
3996DOC_START
2c7aad89 3997 Specify the location of the executable URL rewriter to use.
41bd17a4 3998 Since they can perform almost any function there isn't one included.
3999
2c7aad89 4000 For each requested URL, the rewriter will receive on line with the format
41bd17a4 4001
c71adec1 4002 URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
4003
4004 In the future, the rewriter interface will be extended with
4005 key=value pairs ("kvpairs" shown above). Rewriter programs
4006 should be prepared to receive and possibly ignore additional
4007 whitespace-separated tokens on each input line.
41bd17a4 4008
4009 And the rewriter may return a rewritten URL. The other components of
4010 the request line does not need to be returned (ignored if they are).
4011
4012 The rewriter can also indicate that a client-side redirect should
4013 be performed to the new URL. This is done by prefixing the returned
2c7aad89 4014 URL with "301:" (moved permanently) or 302: (moved temporarily), etc.
41bd17a4 4015
4016 By default, a URL rewriter is not used.
4017DOC_END
4018
4019NAME: url_rewrite_children redirect_children
48d54e4d 4020TYPE: HelperChildConfig
5b708d95 4021DEFAULT: 20 startup=0 idle=1 concurrency=0
41bd17a4 4022LOC: Config.redirectChildren
4023DOC_START
48d54e4d
AJ
4024 The maximum number of redirector processes to spawn. If you limit
4025 it too few Squid will have to wait for them to process a backlog of
4026 URLs, slowing it down. If you allow too many they will use RAM
4027 and other system resources noticably.
4028
4029 The startup= and idle= options allow some measure of skew in your
4030 tuning.
4031
4032 startup=
4033
4034 Sets a minimum of how many processes are to be spawned when Squid
4035 starts or reconfigures. When set to zero the first request will
4036 cause spawning of the first child process to handle it.
4037
4038 Starting too few will cause an initial slowdown in traffic as Squid
4039 attempts to simultaneously spawn enough processes to cope.
4040
4041 idle=
4042
4043 Sets a minimum of how many processes Squid is to try and keep available
4044 at all times. When traffic begins to rise above what the existing
4045 processes can handle this many more will be spawned up to the maximum
4046 configured. A minimum setting of 1 is required.
4047
4048 concurrency=
41bd17a4 4049
41bd17a4 4050 The number of requests each redirector helper can handle in
4051 parallel. Defaults to 0 which indicates the redirector
4052 is a old-style single threaded redirector.
6a171502
AJ
4053
4054 When this directive is set to a value >= 1 then the protocol
4055 used to communicate with the helper is modified to include
4056 a request ID in front of the request/response. The request
4057 ID from the request must be echoed back with the response
4058 to that request.
41bd17a4 4059DOC_END
4060
4061NAME: url_rewrite_host_header redirect_rewrites_host_header
4062TYPE: onoff
4063DEFAULT: on
4064LOC: Config.onoff.redir_rewrites_host
4065DOC_START
3ce33807
AJ
4066 To preserve same-origin security policies in browsers and
4067 prevent Host: header forgery by redirectors Squid rewrites
4068 any Host: header in redirected requests.
4069
4070 If you are running an accelerator this may not be a wanted
4071 effect of a redirector. This directive enables you disable
4072 Host: alteration in reverse-proxy traffic.
4073
41bd17a4 4074 WARNING: Entries are cached on the result of the URL rewriting
4075 process, so be careful if you have domain-virtual hosts.
3ce33807
AJ
4076
4077 WARNING: Squid and other software verifies the URL and Host
4078 are matching, so be careful not to relay through other proxies
4079 or inspecting firewalls with this disabled.
41bd17a4 4080DOC_END
4081
4082NAME: url_rewrite_access redirector_access
4083TYPE: acl_access
4084DEFAULT: none
4085LOC: Config.accessList.redirector
4086DOC_START
4087 If defined, this access list specifies which requests are
4088 sent to the redirector processes. By default all requests
4089 are sent.
b3567eb5
FC
4090
4091 This clause supports both fast and slow acl types.
4092 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
41bd17a4 4093DOC_END
4094
4095NAME: url_rewrite_bypass redirector_bypass
4096TYPE: onoff
4097LOC: Config.onoff.redirector_bypass
4098DEFAULT: off
4099DOC_START
4100 When this is 'on', a request will not go through the
4101 redirector if all redirectors are busy. If this is 'off'
4102 and the redirector queue grows too large, Squid will exit
4103 with a FATAL error and ask you to increase the number of
4104 redirectors. You should only enable this if the redirectors
4105 are not critical to your caching system. If you use
4106 redirectors for access control, and you enable this option,
4107 users may have access to pages they should not
4108 be allowed to request.
4109DOC_END
4110
4111COMMENT_START
4112 OPTIONS FOR TUNING THE CACHE
4113 -----------------------------------------------------------------------------
4114COMMENT_END
4115
f04b37d8 4116NAME: cache no_cache
4117TYPE: acl_access
4118DEFAULT: none
4119LOC: Config.accessList.noCache
41bd17a4 4120DOC_START
240887f0 4121 A list of ACL elements which, if matched and denied, cause the request to
f04b37d8 4122 not be satisfied from the cache and the reply to not be cached.
4123 In other words, use this to force certain objects to never be cached.
41bd17a4 4124
240887f0 4125 You must use the words 'allow' or 'deny' to indicate whether items
4126 matching the ACL should be allowed or denied into the cache.
f04b37d8 4127
240887f0 4128 Default is to allow all to be cached.
b3567eb5
FC
4129
4130 This clause supports both fast and slow acl types.
4131 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
41bd17a4 4132DOC_END
4133
570d3f75
AJ
4134NAME: max_stale
4135COMMENT: time-units
4136TYPE: time_t
4137LOC: Config.maxStale
4138DEFAULT: 1 week
4139DOC_START
4140 This option puts an upper limit on how stale content Squid
4141 will serve from the cache if cache validation fails.
4142 Can be overriden by the refresh_pattern max-stale option.
4143DOC_END
4144
41bd17a4 4145NAME: refresh_pattern
4146TYPE: refreshpattern
4147LOC: Config.Refresh
4148DEFAULT: none
4149DOC_START
4150 usage: refresh_pattern [-i] regex min percent max [options]
9e7dbc51 4151
6b698a21 4152 By default, regular expressions are CASE-SENSITIVE. To make
4153 them case-insensitive, use the -i option.
9e7dbc51 4154
41bd17a4 4155 'Min' is the time (in minutes) an object without an explicit
4156 expiry time should be considered fresh. The recommended
4157 value is 0, any higher values may cause dynamic applications
4158 to be erroneously cached unless the application designer
4159 has taken the appropriate actions.
9e7dbc51 4160
41bd17a4 4161 'Percent' is a percentage of the objects age (time since last
4162 modification age) an object without explicit expiry time
4163 will be considered fresh.
5b807763 4164
41bd17a4 4165 'Max' is an upper limit on how long objects without an explicit
4166 expiry time will be considered fresh.
9e7dbc51 4167
41bd17a4 4168 options: override-expire
4169 override-lastmod
4170 reload-into-ims
4171 ignore-reload
4172 ignore-no-cache
4173 ignore-no-store
4ca08219 4174 ignore-must-revalidate
41bd17a4 4175 ignore-private
4176 ignore-auth
570d3f75 4177 max-stale=NN
41bd17a4 4178 refresh-ims
3d8b6ba4 4179 store-stale
a0ec9f68 4180
41bd17a4 4181 override-expire enforces min age even if the server
9b2ad080
HN
4182 sent an explicit expiry time (e.g., with the
4183 Expires: header or Cache-Control: max-age). Doing this
4184 VIOLATES the HTTP standard. Enabling this feature
4185 could make you liable for problems which it causes.
6468fe10 4186
04925576
AJ
4187 Note: override-expire does not enforce staleness - it only extends
4188 freshness / min. If the server returns a Expires time which
4189 is longer than your max time, Squid will still consider
4190 the object fresh for that period of time.
4191
41bd17a4 4192 override-lastmod enforces min age even on objects
4193 that were modified recently.
934b03fc 4194
41bd17a4 4195 reload-into-ims changes client no-cache or ``reload''
4196 to If-Modified-Since requests. Doing this VIOLATES the
4197 HTTP standard. Enabling this feature could make you
4198 liable for problems which it causes.
dba79ac5 4199
41bd17a4 4200 ignore-reload ignores a client no-cache or ``reload''
4201 header. Doing this VIOLATES the HTTP standard. Enabling
4202 this feature could make you liable for problems which
4203 it causes.
9bc73deb 4204
41bd17a4 4205 ignore-no-cache ignores any ``Pragma: no-cache'' and
4206 ``Cache-control: no-cache'' headers received from a server.
4207 The HTTP RFC never allows the use of this (Pragma) header
4208 from a server, only a client, though plenty of servers
4209 send it anyway.
4210
4211 ignore-no-store ignores any ``Cache-control: no-store''
4212 headers received from a server. Doing this VIOLATES
4213 the HTTP standard. Enabling this feature could make you
4214 liable for problems which it causes.
4215
4ca08219
AJ
4216 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
4217 headers received from a server. Doing this VIOLATES
4218 the HTTP standard. Enabling this feature could make you
4219 liable for problems which it causes.
4220
41bd17a4 4221 ignore-private ignores any ``Cache-control: private''
4222 headers received from a server. Doing this VIOLATES
4223 the HTTP standard. Enabling this feature could make you
4224 liable for problems which it causes.
4225
4226 ignore-auth caches responses to requests with authorization,
4227 as if the originserver had sent ``Cache-control: public''
4228 in the response header. Doing this VIOLATES the HTTP standard.
4229 Enabling this feature could make you liable for problems which
4230 it causes.
4231
4232 refresh-ims causes squid to contact the origin server
4233 when a client issues an If-Modified-Since request. This
4234 ensures that the client will receive an updated version
4235 if one is available.
4236
3d8b6ba4
AJ
4237 store-stale stores responses even if they don't have explicit
4238 freshness or a validator (i.e., Last-Modified or an ETag)
4239 present, or if they're already stale. By default, Squid will
4240 not cache such responses because they usually can't be
4241 reused. Note that such responses will be stale by default.
4242
570d3f75
AJ
4243 max-stale=NN provide a maximum staleness factor. Squid won't
4244 serve objects more stale than this even if it failed to
4245 validate the object. Default: use the max_stale global limit.
4246
41bd17a4 4247 Basically a cached object is:
4248
4249 FRESH if expires < now, else STALE
4250 STALE if age > max
4251 FRESH if lm-factor < percent, else STALE
4252 FRESH if age < min
4253 else STALE
4254
4255 The refresh_pattern lines are checked in the order listed here.
4256 The first entry which matches is used. If none of the entries
4257 match the default will be used.
4258
4259 Note, you must uncomment all the default lines if you want
4260 to change one. The default setting is only active if none is
4261 used.
4262
41bd17a4 4263NOCOMMENT_START
e0855596
AJ
4264
4265# Add any of your own refresh_pattern entries above these.
41bd17a4 4266refresh_pattern ^ftp: 1440 20% 10080
4267refresh_pattern ^gopher: 1440 0% 1440
89db45fa 4268refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
41bd17a4 4269refresh_pattern . 0 20% 4320
4270NOCOMMENT_END
4271DOC_END
4272
4273NAME: quick_abort_min
4274COMMENT: (KB)
4275TYPE: kb_int64_t
4276DEFAULT: 16 KB
4277LOC: Config.quickAbort.min
4278DOC_NONE
4279
4280NAME: quick_abort_max
4281COMMENT: (KB)
4282TYPE: kb_int64_t
4283DEFAULT: 16 KB
4284LOC: Config.quickAbort.max
4285DOC_NONE
4286
4287NAME: quick_abort_pct
4288COMMENT: (percent)
4289TYPE: int
4290DEFAULT: 95
4291LOC: Config.quickAbort.pct
4292DOC_START
4293 The cache by default continues downloading aborted requests
4294 which are almost completed (less than 16 KB remaining). This
4295 may be undesirable on slow (e.g. SLIP) links and/or very busy
4296 caches. Impatient users may tie up file descriptors and
4297 bandwidth by repeatedly requesting and immediately aborting
4298 downloads.
4299
4300 When the user aborts a request, Squid will check the
4301 quick_abort values to the amount of data transfered until
4302 then.
4303
4304 If the transfer has less than 'quick_abort_min' KB remaining,
4305 it will finish the retrieval.
4306
4307 If the transfer has more than 'quick_abort_max' KB remaining,
4308 it will abort the retrieval.
4309
4310 If more than 'quick_abort_pct' of the transfer has completed,
4311 it will finish the retrieval.
4312
4313 If you do not want any retrieval to continue after the client
4314 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
4315 to '0 KB'.
4316
4317 If you want retrievals to always continue if they are being
4318 cached set 'quick_abort_min' to '-1 KB'.
4319DOC_END
60d096f4 4320
41bd17a4 4321NAME: read_ahead_gap
4322COMMENT: buffer-size
4323TYPE: b_int64_t
4324LOC: Config.readAheadGap
4325DEFAULT: 16 KB
4326DOC_START
4327 The amount of data the cache will buffer ahead of what has been
4328 sent to the client when retrieving an object from another server.
4329DOC_END
53e738c6 4330
41bd17a4 4331NAME: negative_ttl
626096be 4332IFDEF: USE_HTTP_VIOLATIONS
41bd17a4 4333COMMENT: time-units
4334TYPE: time_t
4335LOC: Config.negativeTtl
ac9cc053 4336DEFAULT: 0 seconds
41bd17a4 4337DOC_START
ac9cc053
AJ
4338 Set the Default Time-to-Live (TTL) for failed requests.
4339 Certain types of failures (such as "connection refused" and
4340 "404 Not Found") are able to be negatively-cached for a short time.
4341 Modern web servers should provide Expires: header, however if they
4342 do not this can provide a minimum TTL.
4343 The default is not to cache errors with unknown expiry details.
4344
4345 Note that this is different from negative caching of DNS lookups.
39956c7c
AJ
4346
4347 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4348 this feature could make you liable for problems which it
4349 causes.
41bd17a4 4350DOC_END
53e738c6 4351
41bd17a4 4352NAME: positive_dns_ttl
4353COMMENT: time-units
4354TYPE: time_t
4355LOC: Config.positiveDnsTtl
4356DEFAULT: 6 hours
4357DOC_START
4358 Upper limit on how long Squid will cache positive DNS responses.
4359 Default is 6 hours (360 minutes). This directive must be set
4360 larger than negative_dns_ttl.
4361DOC_END
c4ab8329 4362
41bd17a4 4363NAME: negative_dns_ttl
4364COMMENT: time-units
4365TYPE: time_t
4366LOC: Config.negativeDnsTtl
4367DEFAULT: 1 minutes
4368DOC_START
4369 Time-to-Live (TTL) for negative caching of failed DNS lookups.
4370 This also sets the lower cache limit on positive lookups.
4371 Minimum value is 1 second, and it is not recommendable to go
4372 much below 10 seconds.
4373DOC_END
7df0bfd7 4374
41bd17a4 4375NAME: range_offset_limit
11e3fa1c
AJ
4376COMMENT: size [acl acl...]
4377TYPE: acl_b_size_t
41bd17a4 4378LOC: Config.rangeOffsetLimit
11e3fa1c 4379DEFAULT: none
41bd17a4 4380DOC_START
11e3fa1c
AJ
4381 usage: (size) [units] [[!]aclname]
4382
4383 Sets an upper limit on how far (number of bytes) into the file
4384 a Range request may be to cause Squid to prefetch the whole file.
4385 If beyond this limit, Squid forwards the Range request as it is and
4386 the result is NOT cached.
4387
41bd17a4 4388 This is to stop a far ahead range request (lets say start at 17MB)
4389 from making Squid fetch the whole object up to that point before
4390 sending anything to the client.
11e3fa1c
AJ
4391
4392 Multiple range_offset_limit lines may be specified, and they will
4393 be searched from top to bottom on each request until a match is found.
4394 The first match found will be used. If no line matches a request, the
4395 default limit of 0 bytes will be used.
4396
4397 'size' is the limit specified as a number of units.
4398
4399 'units' specifies whether to use bytes, KB, MB, etc.
4400 If no units are specified bytes are assumed.
4401
4402 A size of 0 causes Squid to never fetch more than the
ab275c7b 4403 client requested. (default)
11e3fa1c
AJ
4404
4405 A size of 'none' causes Squid to always fetch the object from the
41bd17a4 4406 beginning so it may cache the result. (2.0 style)
11e3fa1c
AJ
4407
4408 'aclname' is the name of a defined ACL.
4409
4410 NP: Using 'none' as the byte value here will override any quick_abort settings
4411 that may otherwise apply to the range request. The range request will
ab275c7b
AJ
4412 be fully fetched from start to finish regardless of the client
4413 actions. This affects bandwidth usage.
41bd17a4 4414DOC_END
d95b862f 4415
41bd17a4 4416NAME: minimum_expiry_time
4417COMMENT: (seconds)
4418TYPE: time_t
4419LOC: Config.minimum_expiry_time
4420DEFAULT: 60 seconds
4421DOC_START
4422 The minimum caching time according to (Expires - Date)
4423 Headers Squid honors if the object can't be revalidated
649fa918 4424 defaults to 60 seconds. In reverse proxy environments it
41bd17a4 4425 might be desirable to honor shorter object lifetimes. It
4426 is most likely better to make your server return a
4427 meaningful Last-Modified header however. In ESI environments
4428 where page fragments often have short lifetimes, this will
4429 often be best set to 0.
4430DOC_END
c68e9c6b 4431
41bd17a4 4432NAME: store_avg_object_size
58d5c5dd
DK
4433COMMENT: (bytes)
4434TYPE: b_int64_t
41bd17a4 4435DEFAULT: 13 KB
4436LOC: Config.Store.avgObjectSize
4437DOC_START
4438 Average object size, used to estimate number of objects your
4439 cache can hold. The default is 13 KB.
cccac0a2 4440DOC_END
4441
41bd17a4 4442NAME: store_objects_per_bucket
4443TYPE: int
4444DEFAULT: 20
4445LOC: Config.Store.objectsPerBucket
4446DOC_START
4447 Target number of objects per bucket in the store hash table.
4448 Lowering this value increases the total number of buckets and
4449 also the storage maintenance rate. The default is 20.
4450DOC_END
4451
4452COMMENT_START
4453 HTTP OPTIONS
4454 -----------------------------------------------------------------------------
4455COMMENT_END
4456
f04b37d8 4457NAME: request_header_max_size
4458COMMENT: (KB)
4459TYPE: b_size_t
df2eec10 4460DEFAULT: 64 KB
f04b37d8 4461LOC: Config.maxRequestHeaderSize
4462DOC_START
4463 This specifies the maximum size for HTTP headers in a request.
4464 Request headers are usually relatively small (about 512 bytes).
4465 Placing a limit on the request header size will catch certain
4466 bugs (for example with persistent connections) and possibly
4467 buffer-overflow or denial-of-service attacks.
4468DOC_END
4469
4470NAME: reply_header_max_size
4471COMMENT: (KB)
4472TYPE: b_size_t
df2eec10 4473DEFAULT: 64 KB
f04b37d8 4474LOC: Config.maxReplyHeaderSize
4475DOC_START
4476 This specifies the maximum size for HTTP headers in a reply.
4477 Reply headers are usually relatively small (about 512 bytes).
4478 Placing a limit on the reply header size will catch certain
4479 bugs (for example with persistent connections) and possibly
4480 buffer-overflow or denial-of-service attacks.
4481DOC_END
4482
4483NAME: request_body_max_size
4484COMMENT: (bytes)
4485TYPE: b_int64_t
4486DEFAULT: 0 KB
4487LOC: Config.maxRequestBodySize
4488DOC_START
4489 This specifies the maximum size for an HTTP request body.
4490 In other words, the maximum size of a PUT/POST request.
4491 A user who attempts to send a request with a body larger
4492 than this limit receives an "Invalid Request" error message.
4493 If you set this parameter to a zero (the default), there will
4494 be no limit imposed.
4495DOC_END
4496
1368d115
CT
4497NAME: client_request_buffer_max_size
4498COMMENT: (bytes)
4499TYPE: b_size_t
4500DEFAULT: 512 KB
4501LOC: Config.maxRequestBufferSize
4502DOC_START
4503 This specifies the maximum buffer size of a client request.
4504 It prevents squid eating too much memory when somebody uploads
4505 a large file.
4506DOC_END
4507
3ff65596
AR
4508NAME: chunked_request_body_max_size
4509COMMENT: (bytes)
4510TYPE: b_int64_t
4511DEFAULT: 64 KB
4512LOC: Config.maxChunkedRequestBodySize
4513DOC_START
4514 A broken or confused HTTP/1.1 client may send a chunked HTTP
4515 request to Squid. Squid does not have full support for that
4516 feature yet. To cope with such requests, Squid buffers the
4517 entire request and then dechunks request body to create a
4518 plain HTTP/1.0 request with a known content length. The plain
4519 request is then used by the rest of Squid code as usual.
4520
4521 The option value specifies the maximum size of the buffer used
4522 to hold the request before the conversion. If the chunked
4523 request size exceeds the specified limit, the conversion
4524 fails, and the client receives an "unsupported request" error,
4525 as if dechunking was disabled.
4526
4527 Dechunking is enabled by default. To disable conversion of
4528 chunked requests, set the maximum to zero.
4529
4530 Request dechunking feature and this option in particular are a
4531 temporary hack. When chunking requests and responses are fully
4532 supported, there will be no need to buffer a chunked request.
4533DOC_END
4534
41bd17a4 4535NAME: broken_posts
626096be 4536IFDEF: USE_HTTP_VIOLATIONS
cccac0a2 4537TYPE: acl_access
cccac0a2 4538DEFAULT: none
41bd17a4 4539LOC: Config.accessList.brokenPosts
cccac0a2 4540DOC_START
41bd17a4 4541 A list of ACL elements which, if matched, causes Squid to send
4542 an extra CRLF pair after the body of a PUT/POST request.
cccac0a2 4543
41bd17a4 4544 Some HTTP servers has broken implementations of PUT/POST,
4545 and rely on an extra CRLF pair sent by some WWW clients.
cccac0a2 4546
41bd17a4 4547 Quote from RFC2616 section 4.1 on this matter:
cccac0a2 4548
41bd17a4 4549 Note: certain buggy HTTP/1.0 client implementations generate an
4550 extra CRLF's after a POST request. To restate what is explicitly
4551 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
4552 a request with an extra CRLF.
cccac0a2 4553
b3567eb5
FC
4554 This clause only supports fast acl types.
4555 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4556
41bd17a4 4557Example:
4558 acl buggy_server url_regex ^http://....
4559 broken_posts allow buggy_server
4560DOC_END
cccac0a2 4561
22fff3bf 4562NAME: adaptation_uses_indirect_client icap_uses_indirect_client
57d76dd4
AJ
4563COMMENT: on|off
4564TYPE: onoff
22fff3bf 4565IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION
57d76dd4 4566DEFAULT: on
22fff3bf 4567LOC: Adaptation::Config::use_indirect_client
57d76dd4 4568DOC_START
ea3ae478
AR
4569 Controls whether the indirect client IP address (instead of the direct
4570 client IP address) is passed to adaptation services.
4571
4572 See also: follow_x_forwarded_for adaptation_send_client_ip
57d76dd4
AJ
4573DOC_END
4574
41bd17a4 4575NAME: via
626096be 4576IFDEF: USE_HTTP_VIOLATIONS
41bd17a4 4577COMMENT: on|off
4578TYPE: onoff
4579DEFAULT: on
4580LOC: Config.onoff.via
4581DOC_START
4582 If set (default), Squid will include a Via header in requests and
4583 replies as required by RFC2616.
4584DOC_END
4cc6eb12 4585
41bd17a4 4586NAME: ie_refresh
4587COMMENT: on|off
4588TYPE: onoff
4589LOC: Config.onoff.ie_refresh
4590DEFAULT: off
4591DOC_START
4592 Microsoft Internet Explorer up until version 5.5 Service
4593 Pack 1 has an issue with transparent proxies, wherein it
4594 is impossible to force a refresh. Turning this on provides
4595 a partial fix to the problem, by causing all IMS-REFRESH
4596 requests from older IE versions to check the origin server
4597 for fresh content. This reduces hit ratio by some amount
4598 (~10% in my experience), but allows users to actually get
4599 fresh content when they want it. Note because Squid
4600 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
4601 of 5.5 is unchanged from old versions of Squid (i.e. a
4602 forced refresh is impossible). Newer versions of IE will,
4603 hopefully, continue to have the new behavior and will be
4604 handled based on that assumption. This option defaults to
4605 the old Squid behavior, which is better for hit ratios but
4606 worse for clients using IE, if they need to be able to
4607 force fresh content.
4608DOC_END
b9d7fe3e 4609
41bd17a4 4610NAME: vary_ignore_expire
4611COMMENT: on|off
4612TYPE: onoff
4613LOC: Config.onoff.vary_ignore_expire
4614DEFAULT: off
4615DOC_START
4616 Many HTTP servers supporting Vary gives such objects
4617 immediate expiry time with no cache-control header
4618 when requested by a HTTP/1.0 client. This option
4619 enables Squid to ignore such expiry times until
4620 HTTP/1.1 is fully implemented.
7e73cd78
AJ
4621
4622 WARNING: If turned on this may eventually cause some
4623 varying objects not intended for caching to get cached.
cccac0a2 4624DOC_END
c4ab8329 4625
41bd17a4 4626NAME: request_entities
4627TYPE: onoff
4628LOC: Config.onoff.request_entities
4629DEFAULT: off
4630DOC_START
4631 Squid defaults to deny GET and HEAD requests with request entities,
4632 as the meaning of such requests are undefined in the HTTP standard
4633 even if not explicitly forbidden.
0976f8db 4634
41bd17a4 4635 Set this directive to on if you have clients which insists
4636 on sending request entities in GET or HEAD requests. But be warned
4637 that there is server software (both proxies and web servers) which
4638 can fail to properly process this kind of request which may make you
4639 vulnerable to cache pollution attacks if enabled.
cccac0a2 4640DOC_END
6b53c392 4641
41bd17a4 4642NAME: request_header_access
626096be 4643IFDEF: USE_HTTP_VIOLATIONS
41bd17a4 4644TYPE: http_header_access[]
4645LOC: Config.request_header_access
cccac0a2 4646DEFAULT: none
cccac0a2 4647DOC_START
41bd17a4 4648 Usage: request_header_access header_name allow|deny [!]aclname ...
0976f8db 4649
41bd17a4 4650 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4651 this feature could make you liable for problems which it
4652 causes.
0976f8db 4653
41bd17a4 4654 This option replaces the old 'anonymize_headers' and the
4655 older 'http_anonymizer' option with something that is much
4656 more configurable. This new method creates a list of ACLs
4657 for each header, allowing you very fine-tuned header
4658 mangling.
934b03fc 4659
41bd17a4 4660 This option only applies to request headers, i.e., from the
4661 client to the server.
5401aa8d 4662
41bd17a4 4663 You can only specify known headers for the header name.
4664 Other headers are reclassified as 'Other'. You can also
4665 refer to all the headers with 'All'.
5401aa8d 4666
41bd17a4 4667 For example, to achieve the same behavior as the old
4668 'http_anonymizer standard' option, you should use:
5401aa8d 4669
41bd17a4 4670 request_header_access From deny all
4671 request_header_access Referer deny all
4672 request_header_access Server deny all
4673 request_header_access User-Agent deny all
4674 request_header_access WWW-Authenticate deny all
4675 request_header_access Link deny all
5401aa8d 4676
41bd17a4 4677 Or, to reproduce the old 'http_anonymizer paranoid' feature
4678 you should use:
5401aa8d 4679
41bd17a4 4680 request_header_access Allow allow all
4681 request_header_access Authorization allow all
4682 request_header_access WWW-Authenticate allow all
4683 request_header_access Proxy-Authorization allow all
4684 request_header_access Proxy-Authenticate allow all
4685 request_header_access Cache-Control allow all
4686 request_header_access Content-Encoding allow all
4687 request_header_access Content-Length allow all
4688 request_header_access Content-Type allow all
4689 request_header_access Date allow all
4690 request_header_access Expires allow all
4691 request_header_access Host allow all
4692 request_header_access If-Modified-Since allow all
4693 request_header_access Last-Modified allow all
4694 request_header_access Location allow all
4695 request_header_access Pragma allow all
4696 request_header_access Accept allow all
4697 request_header_access Accept-Charset allow all
4698 request_header_access Accept-Encoding allow all
4699 request_header_access Accept-Language allow all
4700 request_header_access Content-Language allow all
4701 request_header_access Mime-Version allow all
4702 request_header_access Retry-After allow all
4703 request_header_access Title allow all
4704 request_header_access Connection allow all
41bd17a4 4705 request_header_access All deny all
5401aa8d 4706
41bd17a4 4707 although many of those are HTTP reply headers, and so should be
4708 controlled with the reply_header_access directive.
5401aa8d 4709
41bd17a4 4710 By default, all headers are allowed (no anonymizing is
4711 performed).
5401aa8d 4712DOC_END
4713
41bd17a4 4714NAME: reply_header_access
626096be 4715IFDEF: USE_HTTP_VIOLATIONS
41bd17a4 4716TYPE: http_header_access[]
4717LOC: Config.reply_header_access
cccac0a2 4718DEFAULT: none
4719DOC_START
41bd17a4 4720 Usage: reply_header_access header_name allow|deny [!]aclname ...
934b03fc 4721
41bd17a4 4722 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4723 this feature could make you liable for problems which it
4724 causes.
934b03fc 4725
41bd17a4 4726 This option only applies to reply headers, i.e., from the
4727 server to the client.
934b03fc 4728
41bd17a4 4729 This is the same as request_header_access, but in the other
4730 direction.
6b53c392 4731
41bd17a4 4732 This option replaces the old 'anonymize_headers' and the
4733 older 'http_anonymizer' option with something that is much
4734 more configurable. This new method creates a list of ACLs
4735 for each header, allowing you very fine-tuned header
4736 mangling.
cccac0a2 4737
41bd17a4 4738 You can only specify known headers for the header name.
4739 Other headers are reclassified as 'Other'. You can also
4740 refer to all the headers with 'All'.
cccac0a2 4741
41bd17a4 4742 For example, to achieve the same behavior as the old
4743 'http_anonymizer standard' option, you should use:
cccac0a2 4744
41bd17a4 4745 reply_header_access From deny all
4746 reply_header_access Referer deny all
4747 reply_header_access Server deny all
4748 reply_header_access User-Agent deny all
4749 reply_header_access WWW-Authenticate deny all
4750 reply_header_access Link deny all
cccac0a2 4751
41bd17a4 4752 Or, to reproduce the old 'http_anonymizer paranoid' feature
4753 you should use:
cccac0a2 4754
41bd17a4 4755 reply_header_access Allow allow all
4756 reply_header_access Authorization allow all
4757 reply_header_access WWW-Authenticate allow all
4758 reply_header_access Proxy-Authorization allow all
4759 reply_header_access Proxy-Authenticate allow all
4760 reply_header_access Cache-Control allow all
4761 reply_header_access Content-Encoding allow all
4762 reply_header_access Content-Length allow all
4763 reply_header_access Content-Type allow all
4764 reply_header_access Date allow all
4765 reply_header_access Expires allow all
4766 reply_header_access Host allow all
4767 reply_header_access If-Modified-Since allow all
4768 reply_header_access Last-Modified allow all
4769 reply_header_access Location allow all
4770 reply_header_access Pragma allow all
4771 reply_header_access Accept allow all
4772 reply_header_access Accept-Charset allow all
4773 reply_header_access Accept-Encoding allow all
4774 reply_header_access Accept-Language allow all
4775 reply_header_access Content-Language allow all
4776 reply_header_access Mime-Version allow all
4777 reply_header_access Retry-After allow all
4778 reply_header_access Title allow all
4779 reply_header_access Connection allow all
41bd17a4 4780 reply_header_access All deny all
cccac0a2 4781
41bd17a4 4782 although the HTTP request headers won't be usefully controlled
4783 by this directive -- see request_header_access for details.
cccac0a2 4784
41bd17a4 4785 By default, all headers are allowed (no anonymizing is
4786 performed).
cccac0a2 4787DOC_END
4788
75e4f2ea 4789NAME: request_header_replace header_replace
626096be 4790IFDEF: USE_HTTP_VIOLATIONS
41bd17a4 4791TYPE: http_header_replace[]
4792LOC: Config.request_header_access
cccac0a2 4793DEFAULT: none
41bd17a4 4794DOC_START
75e4f2ea
MB
4795 Usage: request_header_replace header_name message
4796 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
cccac0a2 4797
41bd17a4 4798 This option allows you to change the contents of headers
75e4f2ea
MB
4799 denied with request_header_access above, by replacing them
4800 with some fixed string. This replaces the old fake_user_agent
41bd17a4 4801 option.
cccac0a2 4802
41bd17a4 4803 This only applies to request headers, not reply headers.
cccac0a2 4804
41bd17a4 4805 By default, headers are removed if denied.
4806DOC_END
cccac0a2 4807
75e4f2ea
MB
4808NAME: reply_header_replace
4809IFDEF: USE_HTTP_VIOLATIONS
4810TYPE: http_header_replace[]
4811LOC: Config.reply_header_access
4812DEFAULT: none
4813DOC_START
4814 Usage: reply_header_replace header_name message
4815 Example: reply_header_replace Server Foo/1.0
4816
4817 This option allows you to change the contents of headers
4818 denied with reply_header_access above, by replacing them
4819 with some fixed string.
4820
4821 This only applies to reply headers, not request headers.
4822
4823 By default, headers are removed if denied.
4824DOC_END
4825
41bd17a4 4826NAME: relaxed_header_parser
4827COMMENT: on|off|warn
4828TYPE: tristate
4829LOC: Config.onoff.relaxed_header_parser
4830DEFAULT: on
4831DOC_START
4832 In the default "on" setting Squid accepts certain forms
4833 of non-compliant HTTP messages where it is unambiguous
4834 what the sending application intended even if the message
4835 is not correctly formatted. The messages is then normalized
4836 to the correct form when forwarded by Squid.
cccac0a2 4837
41bd17a4 4838 If set to "warn" then a warning will be emitted in cache.log
4839 each time such HTTP error is encountered.
cccac0a2 4840
41bd17a4 4841 If set to "off" then such HTTP errors will cause the request
4842 or response to be rejected.
4843DOC_END
7d90757b 4844
41bd17a4 4845COMMENT_START
4846 TIMEOUTS
4847 -----------------------------------------------------------------------------
4848COMMENT_END
4849
4850NAME: forward_timeout
4851COMMENT: time-units
4852TYPE: time_t
4853LOC: Config.Timeout.forward
4854DEFAULT: 4 minutes
4855DOC_START
4856 This parameter specifies how long Squid should at most attempt in
4857 finding a forwarding path for the request before giving up.
cccac0a2 4858DOC_END
4859
41bd17a4 4860NAME: connect_timeout
4861COMMENT: time-units
4862TYPE: time_t
4863LOC: Config.Timeout.connect
4864DEFAULT: 1 minute
057f5854 4865DOC_START
41bd17a4 4866 This parameter specifies how long to wait for the TCP connect to
4867 the requested server or peer to complete before Squid should
4868 attempt to find another path where to forward the request.
057f5854 4869DOC_END
4870
41bd17a4 4871NAME: peer_connect_timeout
4872COMMENT: time-units
4873TYPE: time_t
4874LOC: Config.Timeout.peer_connect
4875DEFAULT: 30 seconds
cccac0a2 4876DOC_START
41bd17a4 4877 This parameter specifies how long to wait for a pending TCP
4878 connection to a peer cache. The default is 30 seconds. You
4879 may also set different timeout values for individual neighbors
4880 with the 'connect-timeout' option on a 'cache_peer' line.
4881DOC_END
7f7db318 4882
41bd17a4 4883NAME: read_timeout
4884COMMENT: time-units
4885TYPE: time_t
4886LOC: Config.Timeout.read
4887DEFAULT: 15 minutes
4888DOC_START
4889 The read_timeout is applied on server-side connections. After
4890 each successful read(), the timeout will be extended by this
4891 amount. If no data is read again after this amount of time,
4892 the request is aborted and logged with ERR_READ_TIMEOUT. The
4893 default is 15 minutes.
4894DOC_END
cccac0a2 4895
5ef5e5cc
AJ
4896NAME: write_timeout
4897COMMENT: time-units
4898TYPE: time_t
4899LOC: Config.Timeout.write
4900DEFAULT: 15 minutes
4901DOC_START
4902 This timeout is tracked for all connections that have data
4903 available for writing and are waiting for the socket to become
4904 ready. After each successful write, the timeout is extended by
4905 the configured amount. If Squid has data to write but the
4906 connection is not ready for the configured duration, the
4907 transaction associated with the connection is terminated. The
4908 default is 15 minutes.
4909DOC_END
4910
41bd17a4 4911NAME: request_timeout
4912TYPE: time_t
4913LOC: Config.Timeout.request
4914DEFAULT: 5 minutes
4915DOC_START
6b2a2108 4916 How long to wait for complete HTTP request headers after initial
41bd17a4 4917 connection establishment.
4918DOC_END
cccac0a2 4919
97b32442 4920NAME: client_idle_pconn_timeout persistent_request_timeout
41bd17a4 4921TYPE: time_t
97b32442 4922LOC: Config.Timeout.clientIdlePconn
41bd17a4 4923DEFAULT: 2 minutes
4924DOC_START
4925 How long to wait for the next HTTP request on a persistent
97b32442 4926 client connection after the previous request completes.
41bd17a4 4927DOC_END
cccac0a2 4928
41bd17a4 4929NAME: client_lifetime
4930COMMENT: time-units
4931TYPE: time_t
4932LOC: Config.Timeout.lifetime
4933DEFAULT: 1 day
4934DOC_START
4935 The maximum amount of time a client (browser) is allowed to
4936 remain connected to the cache process. This protects the Cache
4937 from having a lot of sockets (and hence file descriptors) tied up
4938 in a CLOSE_WAIT state from remote clients that go away without
4939 properly shutting down (either because of a network failure or
4940 because of a poor client implementation). The default is one
4941 day, 1440 minutes.
7d90757b 4942
41bd17a4 4943 NOTE: The default value is intended to be much larger than any
4944 client would ever need to be connected to your cache. You
4945 should probably change client_lifetime only as a last resort.
4946 If you seem to have many client connections tying up
4947 filedescriptors, we recommend first tuning the read_timeout,
4948 request_timeout, persistent_request_timeout and quick_abort values.
cccac0a2 4949DOC_END
4950
41bd17a4 4951NAME: half_closed_clients
4952TYPE: onoff
4953LOC: Config.onoff.half_closed_clients
0c2f5c4f 4954DEFAULT: off
4eb368f9 4955DOC_START
41bd17a4 4956 Some clients may shutdown the sending side of their TCP
4957 connections, while leaving their receiving sides open. Sometimes,
4958 Squid can not tell the difference between a half-closed and a
0c2f5c4f
AJ
4959 fully-closed TCP connection.
4960
4961 By default, Squid will immediately close client connections when
4962 read(2) returns "no more data to read."
4963
abdf1651 4964 Change this option to 'on' and Squid will keep open connections
0c2f5c4f
AJ
4965 until a read(2) or write(2) on the socket returns an error.
4966 This may show some benefits for reverse proxies. But if not
4967 it is recommended to leave OFF.
4eb368f9 4968DOC_END
4969
97b32442 4970NAME: server_idle_pconn_timeout pconn_timeout
41bd17a4 4971TYPE: time_t
97b32442 4972LOC: Config.Timeout.serverIdlePconn
41bd17a4 4973DEFAULT: 1 minute
cccac0a2 4974DOC_START
41bd17a4 4975 Timeout for idle persistent connections to servers and other
4976 proxies.
4977DOC_END
cccac0a2 4978
41bd17a4 4979NAME: ident_timeout
4980TYPE: time_t
4981IFDEF: USE_IDENT
4daaf3cb 4982LOC: Ident::TheConfig.timeout
41bd17a4 4983DEFAULT: 10 seconds
4984DOC_START
4985 Maximum time to wait for IDENT lookups to complete.
cccac0a2 4986
41bd17a4 4987 If this is too high, and you enabled IDENT lookups from untrusted
4988 users, you might be susceptible to denial-of-service by having
4989 many ident requests going at once.
cccac0a2 4990DOC_END
4991
41bd17a4 4992NAME: shutdown_lifetime
4993COMMENT: time-units
4994TYPE: time_t
4995LOC: Config.shutdownLifetime
4996DEFAULT: 30 seconds
cccac0a2 4997DOC_START
41bd17a4 4998 When SIGTERM or SIGHUP is received, the cache is put into
4999 "shutdown pending" mode until all active sockets are closed.
5000 This value is the lifetime to set for all open descriptors
5001 during shutdown mode. Any active clients after this many
5002 seconds will receive a 'timeout' message.
cccac0a2 5003DOC_END
0976f8db 5004
cccac0a2 5005COMMENT_START
5006 ADMINISTRATIVE PARAMETERS
5007 -----------------------------------------------------------------------------
5008COMMENT_END
5009
5010NAME: cache_mgr
5011TYPE: string
5012DEFAULT: webmaster
5013LOC: Config.adminEmail
5014DOC_START
5015 Email-address of local cache manager who will receive
5016 mail if the cache dies. The default is "webmaster."
5017DOC_END
5018
abacf776 5019NAME: mail_from
5020TYPE: string
5021DEFAULT: none
5022LOC: Config.EmailFrom
5023DOC_START
5024 From: email-address for mail sent when the cache dies.
5025 The default is to use 'appname@unique_hostname'.
b8c0c06d 5026 Default appname value is "squid", can be changed into
abacf776 5027 src/globals.h before building squid.
5028DOC_END
5029
d084bf20 5030NAME: mail_program
5031TYPE: eol
5032DEFAULT: mail
5033LOC: Config.EmailProgram
5034DOC_START
5035 Email program used to send mail if the cache dies.
846a5e31 5036 The default is "mail". The specified program must comply
d084bf20 5037 with the standard Unix mail syntax:
846a5e31 5038 mail-program recipient < mailfile
5039
d084bf20 5040 Optional command line options can be specified.
5041DOC_END
5042
cccac0a2 5043NAME: cache_effective_user
5044TYPE: string
5483d916 5045DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
cccac0a2 5046LOC: Config.effectiveUser
e3d74828 5047DOC_START
5048 If you start Squid as root, it will change its effective/real
5049 UID/GID to the user specified below. The default is to change
5483d916 5050 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
64e288bd 5051 see also; cache_effective_group
e3d74828 5052DOC_END
5053
cccac0a2 5054NAME: cache_effective_group
5055TYPE: string
5056DEFAULT: none
5057LOC: Config.effectiveGroup
5058DOC_START
64e288bd 5059 Squid sets the GID to the effective user's default group ID
5060 (taken from the password file) and supplementary group list
5061 from the groups membership.
5062
e3d74828 5063 If you want Squid to run with a specific GID regardless of
5064 the group memberships of the effective user then set this
5065 to the group (or GID) you want Squid to run as. When set
64e288bd 5066 all other group privileges of the effective user are ignored
e3d74828 5067 and only this GID is effective. If Squid is not started as
64e288bd 5068 root the user starting Squid MUST be member of the specified
e3d74828 5069 group.
64e288bd 5070
5071 This option is not recommended by the Squid Team.
5072 Our preference is for administrators to configure a secure
5073 user account for squid with UID/GID matching system policies.
cccac0a2 5074DOC_END
5075
d3caee79 5076NAME: httpd_suppress_version_string
5077COMMENT: on|off
5078TYPE: onoff
5079DEFAULT: off
5080LOC: Config.onoff.httpd_suppress_version_string
5081DOC_START
5082 Suppress Squid version string info in HTTP headers and HTML error pages.
5083DOC_END
5084
cccac0a2 5085NAME: visible_hostname
5086TYPE: string
5087LOC: Config.visibleHostname
5088DEFAULT: none
5089DOC_START
5090 If you want to present a special hostname in error messages, etc,
7f7db318 5091 define this. Otherwise, the return value of gethostname()
cccac0a2 5092 will be used. If you have multiple caches in a cluster and
5093 get errors about IP-forwarding you must set them to have individual
5094 names with this setting.
5095DOC_END
5096
cccac0a2 5097NAME: unique_hostname
5098TYPE: string
5099LOC: Config.uniqueHostname
5100DEFAULT: none
5101DOC_START
5102 If you want to have multiple machines with the same
7f7db318 5103 'visible_hostname' you must give each machine a different
5104 'unique_hostname' so forwarding loops can be detected.
cccac0a2 5105DOC_END
5106
cccac0a2 5107NAME: hostname_aliases
5108TYPE: wordlist
5109LOC: Config.hostnameAliases
5110DEFAULT: none
5111DOC_START
7f7db318 5112 A list of other DNS names your cache has.
cccac0a2 5113DOC_END
0976f8db 5114
c642c141
AJ
5115NAME: umask
5116TYPE: int
5117LOC: Config.umask
5118DEFAULT: 027
5119DOC_START
5120 Minimum umask which should be enforced while the proxy
5121 is running, in addition to the umask set at startup.
5122
5123 For a traditional octal representation of umasks, start
5124 your value with 0.
5125DOC_END
5126
cccac0a2 5127COMMENT_START
5128 OPTIONS FOR THE CACHE REGISTRATION SERVICE
5129 -----------------------------------------------------------------------------
5130
5131 This section contains parameters for the (optional) cache
5132 announcement service. This service is provided to help
5133 cache administrators locate one another in order to join or
5134 create cache hierarchies.
5135
5136 An 'announcement' message is sent (via UDP) to the registration
5137 service by Squid. By default, the announcement message is NOT
5138 SENT unless you enable it with 'announce_period' below.
5139
5140 The announcement message includes your hostname, plus the
5141 following information from this configuration file:
5142
5143 http_port
5144 icp_port
5145 cache_mgr
5146
5147 All current information is processed regularly and made
5148 available on the Web at http://www.ircache.net/Cache/Tracker/.
5149COMMENT_END
5150
5151NAME: announce_period
5152TYPE: time_t
5153LOC: Config.Announce.period
5154DEFAULT: 0
5155DOC_START
5156 This is how frequently to send cache announcements. The
5157 default is `0' which disables sending the announcement
5158 messages.
5159
e0855596 5160 To enable announcing your cache, just set an announce period.
cccac0a2 5161
e0855596
AJ
5162 Example:
5163 announce_period 1 day
cccac0a2 5164DOC_END
5165
cccac0a2 5166NAME: announce_host
5167TYPE: string
5168DEFAULT: tracker.ircache.net
5169LOC: Config.Announce.host
5170DOC_NONE
5171
5172NAME: announce_file
5173TYPE: string
5174DEFAULT: none
5175LOC: Config.Announce.file
5176DOC_NONE
5177
5178NAME: announce_port
ae870270 5179TYPE: u_short
cccac0a2 5180DEFAULT: 3131
5181LOC: Config.Announce.port
5182DOC_START
5183 announce_host and announce_port set the hostname and port
5184 number where the registration message will be sent.
5185
5186 Hostname will default to 'tracker.ircache.net' and port will
5187 default default to 3131. If the 'filename' argument is given,
5188 the contents of that file will be included in the announce
5189 message.
5190DOC_END
5191
8d6275c0 5192COMMENT_START
5193 HTTPD-ACCELERATOR OPTIONS
5194 -----------------------------------------------------------------------------
5195COMMENT_END
5196
cccac0a2 5197NAME: httpd_accel_surrogate_id
cccac0a2 5198TYPE: string
b2b40d8c 5199DEFAULT: none
cccac0a2 5200LOC: Config.Accel.surrogate_id
cccac0a2 5201DOC_START
5202 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
5203 need an identification token to allow control targeting. Because
5204 a farm of surrogates may all perform the same tasks, they may share
5205 an identification token.
b2b40d8c
AJ
5206
5207 The default ID is the visible_hostname
cccac0a2 5208DOC_END
5209
5210NAME: http_accel_surrogate_remote
cccac0a2 5211COMMENT: on|off
5212TYPE: onoff
5213DEFAULT: off
5214LOC: Config.onoff.surrogate_is_remote
5215DOC_START
5216 Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
5217 Set this to on to have squid behave as a remote surrogate.
5218DOC_END
5219
5220NAME: esi_parser
f41735ea 5221IFDEF: USE_SQUID_ESI
964b44c3 5222COMMENT: libxml2|expat|custom
cccac0a2 5223TYPE: string
5224LOC: ESIParser::Type
5225DEFAULT: custom
5226DOC_START
5227 ESI markup is not strictly XML compatible. The custom ESI parser
5228 will give higher performance, but cannot handle non ASCII character
5229 encodings.
5230DOC_END
0976f8db 5231
9edd9041 5232COMMENT_START
8d6275c0 5233 DELAY POOL PARAMETERS
9edd9041 5234 -----------------------------------------------------------------------------
5235COMMENT_END
5236
5237NAME: delay_pools
5238TYPE: delay_pool_count
5239DEFAULT: 0
9a0a18de 5240IFDEF: USE_DELAY_POOLS
9edd9041 5241LOC: Config.Delay
5242DOC_START
5243 This represents the number of delay pools to be used. For example,
5244 if you have one class 2 delay pool and one class 3 delays pool, you
5245 have a total of 2 delay pools.
5246DOC_END
5247
5248NAME: delay_class
5249TYPE: delay_pool_class
5250DEFAULT: none
9a0a18de 5251IFDEF: USE_DELAY_POOLS
9edd9041 5252LOC: Config.Delay
5253DOC_START
5254 This defines the class of each delay pool. There must be exactly one
5255 delay_class line for each delay pool. For example, to define two
5256 delay pools, one of class 2 and one of class 3, the settings above
5257 and here would be:
5258
b1fb3348
AJ
5259 Example:
5260 delay_pools 4 # 4 delay pools
5261 delay_class 1 2 # pool 1 is a class 2 pool
5262 delay_class 2 3 # pool 2 is a class 3 pool
5263 delay_class 3 4 # pool 3 is a class 4 pool
5264 delay_class 4 5 # pool 4 is a class 5 pool
9edd9041 5265
5266 The delay pool classes are:
5267
5268 class 1 Everything is limited by a single aggregate
5269 bucket.
5270
5271 class 2 Everything is limited by a single aggregate
5272 bucket as well as an "individual" bucket chosen
b1fb3348 5273 from bits 25 through 32 of the IPv4 address.
9edd9041 5274
5275 class 3 Everything is limited by a single aggregate
5276 bucket as well as a "network" bucket chosen
5277 from bits 17 through 24 of the IP address and a
5278 "individual" bucket chosen from bits 17 through
b1fb3348 5279 32 of the IPv4 address.
9edd9041 5280
5281 class 4 Everything in a class 3 delay pool, with an
5282 additional limit on a per user basis. This
5283 only takes effect if the username is established
5284 in advance - by forcing authentication in your
5285 http_access rules.
5286
5287 class 5 Requests are grouped according their tag (see
5288 external_acl's tag= reply).
5289
0b68481a
AJ
5290
5291 Each pool also requires a delay_parameters directive to configure the pool size
5292 and speed limits used whenever the pool is applied to a request. Along with
5293 a set of delay_access directives to determine when it is used.
5294
9edd9041 5295 NOTE: If an IP address is a.b.c.d
5296 -> bits 25 through 32 are "d"
5297 -> bits 17 through 24 are "c"
5298 -> bits 17 through 32 are "c * 256 + d"
b1fb3348
AJ
5299
5300 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
5301 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
9edd9041 5302DOC_END
5303
5304NAME: delay_access
5305TYPE: delay_pool_access
5306DEFAULT: none
9a0a18de 5307IFDEF: USE_DELAY_POOLS
9edd9041 5308LOC: Config.Delay
5309DOC_START
5310 This is used to determine which delay pool a request falls into.
5311
5312 delay_access is sorted per pool and the matching starts with pool 1,
5313 then pool 2, ..., and finally pool N. The first delay pool where the
5314 request is allowed is selected for the request. If it does not allow
5315 the request to any pool then the request is not delayed (default).
5316
5317 For example, if you want some_big_clients in delay
5318 pool 1 and lotsa_little_clients in delay pool 2:
5319
5320Example:
5321 delay_access 1 allow some_big_clients
5322 delay_access 1 deny all
5323 delay_access 2 allow lotsa_little_clients
5324 delay_access 2 deny all
5325 delay_access 3 allow authenticated_clients
5326DOC_END
5327
5328NAME: delay_parameters
5329TYPE: delay_pool_rates
5330DEFAULT: none
9a0a18de 5331IFDEF: USE_DELAY_POOLS
9edd9041 5332LOC: Config.Delay
5333DOC_START
5334 This defines the parameters for a delay pool. Each delay pool has
5335 a number of "buckets" associated with it, as explained in the
0b68481a 5336 description of delay_class.
9edd9041 5337
0b68481a
AJ
5338 For a class 1 delay pool, the syntax is:
5339 delay_pools pool 1
5340 delay_parameters pool aggregate
9edd9041 5341
5342 For a class 2 delay pool:
0b68481a
AJ
5343 delay_pools pool 2
5344 delay_parameters pool aggregate individual
9edd9041 5345
5346 For a class 3 delay pool:
0b68481a
AJ
5347 delay_pools pool 3
5348 delay_parameters pool aggregate network individual
9edd9041 5349
5350 For a class 4 delay pool:
0b68481a
AJ
5351 delay_pools pool 4
5352 delay_parameters pool aggregate network individual user
9edd9041 5353
5354 For a class 5 delay pool:
0b68481a
AJ
5355 delay_pools pool 5
5356 delay_parameters pool tagrate
9edd9041 5357
0b68481a 5358 The option variables are:
9edd9041 5359
5360 pool a pool number - ie, a number between 1 and the
5361 number specified in delay_pools as used in
5362 delay_class lines.
5363
fdb47ac6 5364 aggregate the speed limit parameters for the aggregate bucket
9edd9041 5365 (class 1, 2, 3).
5366
fdb47ac6 5367 individual the speed limit parameters for the individual
9edd9041 5368 buckets (class 2, 3).
5369
fdb47ac6 5370 network the speed limit parameters for the network buckets
9edd9041 5371 (class 3).
5372
fdb47ac6 5373 user the speed limit parameters for the user buckets
9edd9041 5374 (class 4).
5375
fdb47ac6 5376 tagrate the speed limit parameters for the tag buckets
9edd9041 5377 (class 5).
5378
5379 A pair of delay parameters is written restore/maximum, where restore is
5380 the number of bytes (not bits - modem and network speeds are usually
5381 quoted in bits) per second placed into the bucket, and maximum is the
5382 maximum number of bytes which can be in the bucket at any time.
5383
0b68481a
AJ
5384 There must be one delay_parameters line for each delay pool.
5385
5386
9edd9041 5387 For example, if delay pool number 1 is a class 2 delay pool as in the
0b68481a 5388 above example, and is being used to strictly limit each host to 64Kbit/sec
9edd9041 5389 (plus overheads), with no overall limit, the line is:
5390
0b68481a
AJ
5391 delay_parameters 1 -1/-1 8000/8000
5392
5393 Note that 8 x 8000 KByte/sec -> 64Kbit/sec.
9edd9041 5394
5395 Note that the figure -1 is used to represent "unlimited".
5396
0b68481a 5397
9edd9041 5398 And, if delay pool number 2 is a class 3 delay pool as in the above
0b68481a
AJ
5399 example, and you want to limit it to a total of 256Kbit/sec (strict limit)
5400 with each 8-bit network permitted 64Kbit/sec (strict limit) and each
5401 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits
9edd9041 5402 to permit a decent web page to be downloaded at a decent speed
5403 (if the network is not being limited due to overuse) but slow down
5404 large downloads more significantly:
5405
0b68481a
AJ
5406 delay_parameters 2 32000/32000 8000/8000 600/8000
5407
5408 Note that 8 x 32000 KByte/sec -> 256Kbit/sec.
5409 8 x 8000 KByte/sec -> 64Kbit/sec.
5410 8 x 600 Byte/sec -> 4800bit/sec.
9edd9041 5411
9edd9041 5412
5413 Finally, for a class 4 delay pool as in the example - each user will
0b68481a 5414 be limited to 128Kbits/sec no matter how many workstations they are logged into.:
9edd9041 5415
0b68481a 5416 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
9edd9041 5417DOC_END
5418
5419NAME: delay_initial_bucket_level
5420COMMENT: (percent, 0-100)
ae870270 5421TYPE: u_short
9edd9041 5422DEFAULT: 50
9a0a18de 5423IFDEF: USE_DELAY_POOLS
9edd9041 5424LOC: Config.Delay.initial
5425DOC_START
5426 The initial bucket percentage is used to determine how much is put
5427 in each bucket when squid starts, is reconfigured, or first notices
5428 a host accessing it (in class 2 and class 3, individual hosts and
5429 networks only have buckets associated with them once they have been
5430 "seen" by squid).
5431DOC_END
5432
b4cd430a
CT
5433COMMENT_START
5434 CLIENT DELAY POOL PARAMETERS
5435 -----------------------------------------------------------------------------
5436COMMENT_END
5437
5438NAME: client_delay_pools
5439TYPE: client_delay_pool_count
5440DEFAULT: 0
9a0a18de 5441IFDEF: USE_DELAY_POOLS
b4cd430a
CT
5442LOC: Config.ClientDelay
5443DOC_START
5444 This option specifies the number of client delay pools used. It must
5445 preceed other client_delay_* options.
5446
5447Example:
5448 client_delay_pools 2
5449DOC_END
5450
5451NAME: client_delay_initial_bucket_level
5452COMMENT: (percent, 0-no_limit)
ae870270 5453TYPE: u_short
b4cd430a 5454DEFAULT: 50
9a0a18de 5455IFDEF: USE_DELAY_POOLS
b4cd430a
CT
5456LOC: Config.ClientDelay.initial
5457DOC_START
5458 This option determines the initial bucket size as a percentage of
5459 max_bucket_size from client_delay_parameters. Buckets are created
5460 at the time of the "first" connection from the matching IP. Idle
5461 buckets are periodically deleted up.
5462
5463 You can specify more than 100 percent but note that such "oversized"
5464 buckets are not refilled until their size goes down to max_bucket_size
5465 from client_delay_parameters.
5466
5467Example:
5468 client_delay_initial_bucket_level 50
5469DOC_END
5470
5471NAME: client_delay_parameters
5472TYPE: client_delay_pool_rates
5473DEFAULT: none
9a0a18de 5474IFDEF: USE_DELAY_POOLS
b4cd430a
CT
5475LOC: Config.ClientDelay
5476DOC_START
5477
5478 This option configures client-side bandwidth limits using the
5479 following format:
5480
5481 client_delay_parameters pool speed_limit max_bucket_size
5482
5483 pool is an integer ID used for client_delay_access matching.
5484
5485 speed_limit is bytes added to the bucket per second.
5486
5487 max_bucket_size is the maximum size of a bucket, enforced after any
5488 speed_limit additions.
5489
5490 Please see the delay_parameters option for more information and
5491 examples.
5492
5493Example:
5494 client_delay_parameters 1 1024 2048
5495 client_delay_parameters 2 51200 16384
5496DOC_END
5497
5498NAME: client_delay_access
5499TYPE: client_delay_pool_access
5500DEFAULT: none
9a0a18de 5501IFDEF: USE_DELAY_POOLS
b4cd430a
CT
5502LOC: Config.ClientDelay
5503DOC_START
5504
5505 This option determines the client-side delay pool for the
5506 request:
5507
5508 client_delay_access pool_ID allow|deny acl_name
5509
5510 All client_delay_access options are checked in their pool ID
5511 order, starting with pool 1. The first checked pool with allowed
5512 request is selected for the request. If no ACL matches or there
5513 are no client_delay_access options, the request bandwidth is not
5514 limited.
5515
5516 The ACL-selected pool is then used to find the
5517 client_delay_parameters for the request. Client-side pools are
5518 not used to aggregate clients. Clients are always aggregated
5519 based on their source IP addresses (one bucket per source IP).
5520
5521 Please see delay_access for more examples.
5522
5523Example:
5524 client_delay_access 1 allow low_rate_network
5525 client_delay_access 2 allow vips_network
5526DOC_END
5527
cccac0a2 5528COMMENT_START
8d6275c0 5529 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
cccac0a2 5530 -----------------------------------------------------------------------------
5531COMMENT_END
5532
8d6275c0 5533NAME: wccp_router
5534TYPE: address
5535LOC: Config.Wccp.router
0eb08770 5536DEFAULT: any_addr
8d6275c0 5537IFDEF: USE_WCCP
e313ab0a
AJ
5538DOC_START
5539 Use this option to define your WCCP ``home'' router for
5540 Squid.
5541
5542 wccp_router supports a single WCCP(v1) router
5543
5544 wccp2_router supports multiple WCCPv2 routers
5545
5546 only one of the two may be used at the same time and defines
5547 which version of WCCP to use.
5548DOC_END
df2eec10 5549
8d6275c0 5550NAME: wccp2_router
9fb4efad 5551TYPE: IpAddress_list
8d6275c0 5552LOC: Config.Wccp2.router
cccac0a2 5553DEFAULT: none
8d6275c0 5554IFDEF: USE_WCCPv2
cccac0a2 5555DOC_START
8d6275c0 5556 Use this option to define your WCCP ``home'' router for
5557 Squid.
cccac0a2 5558
8d6275c0 5559 wccp_router supports a single WCCP(v1) router
cccac0a2 5560
8d6275c0 5561 wccp2_router supports multiple WCCPv2 routers
cccac0a2 5562
8d6275c0 5563 only one of the two may be used at the same time and defines
5564 which version of WCCP to use.
5565DOC_END
5566
5567NAME: wccp_version
cccac0a2 5568TYPE: int
8d6275c0 5569LOC: Config.Wccp.version
5570DEFAULT: 4
5571IFDEF: USE_WCCP
cccac0a2 5572DOC_START
8d6275c0 5573 This directive is only relevant if you need to set up WCCP(v1)
5574 to some very old and end-of-life Cisco routers. In all other
5575 setups it must be left unset or at the default setting.
5576 It defines an internal version in the WCCP(v1) protocol,
5577 with version 4 being the officially documented protocol.
cccac0a2 5578
8d6275c0 5579 According to some users, Cisco IOS 11.2 and earlier only
5580 support WCCP version 3. If you're using that or an earlier
5581 version of IOS, you may need to change this value to 3, otherwise
5582 do not specify this parameter.
cccac0a2 5583DOC_END
5584
8d6275c0 5585NAME: wccp2_rebuild_wait
5586TYPE: onoff
5587LOC: Config.Wccp2.rebuildwait
5588DEFAULT: on
5589IFDEF: USE_WCCPv2
5590DOC_START
5591 If this is enabled Squid will wait for the cache dir rebuild to finish
5592 before sending the first wccp2 HereIAm packet
5593DOC_END
cccac0a2 5594
8d6275c0 5595NAME: wccp2_forwarding_method
e313ab0a 5596TYPE: wccp2_method
8d6275c0 5597LOC: Config.Wccp2.forwarding_method
451c4786 5598DEFAULT: gre
8d6275c0 5599IFDEF: USE_WCCPv2
cccac0a2 5600DOC_START
699acd19 5601 WCCP2 allows the setting of forwarding methods between the
8d6275c0 5602 router/switch and the cache. Valid values are as follows:
cccac0a2 5603
451c4786
AJ
5604 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5605 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
cccac0a2 5606
8d6275c0 5607 Currently (as of IOS 12.4) cisco routers only support GRE.
5608 Cisco switches only support the L2 redirect assignment method.
cccac0a2 5609DOC_END
5610
8d6275c0 5611NAME: wccp2_return_method
e313ab0a 5612TYPE: wccp2_method
8d6275c0 5613LOC: Config.Wccp2.return_method
451c4786 5614DEFAULT: gre
8d6275c0 5615IFDEF: USE_WCCPv2
cccac0a2 5616DOC_START
699acd19 5617 WCCP2 allows the setting of return methods between the
8d6275c0 5618 router/switch and the cache for packets that the cache
5619 decides not to handle. Valid values are as follows:
cccac0a2 5620
451c4786
AJ
5621 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5622 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
cccac0a2 5623
8d6275c0 5624 Currently (as of IOS 12.4) cisco routers only support GRE.
5625 Cisco switches only support the L2 redirect assignment.
cccac0a2 5626
699acd19 5627 If the "ip wccp redirect exclude in" command has been
8d6275c0 5628 enabled on the cache interface, then it is still safe for
5629 the proxy server to use a l2 redirect method even if this
5630 option is set to GRE.
cccac0a2 5631DOC_END
5632
8d6275c0 5633NAME: wccp2_assignment_method
451c4786 5634TYPE: wccp2_amethod
8d6275c0 5635LOC: Config.Wccp2.assignment_method
451c4786 5636DEFAULT: hash
8d6275c0 5637IFDEF: USE_WCCPv2
cccac0a2 5638DOC_START
8d6275c0 5639 WCCP2 allows the setting of methods to assign the WCCP hash
5640 Valid values are as follows:
cccac0a2 5641
451c4786 5642 hash - Hash assignment
bb7a1781 5643 mask - Mask assignment
cccac0a2 5644
8d6275c0 5645 As a general rule, cisco routers support the hash assignment method
5646 and cisco switches support the mask assignment method.
5647DOC_END
cccac0a2 5648
8d6275c0 5649NAME: wccp2_service
5650TYPE: wccp2_service
5651LOC: Config.Wccp2.info
8d6275c0 5652DEFAULT_IF_NONE: standard 0
5653IFDEF: USE_WCCPv2
5654DOC_START
5655 WCCP2 allows for multiple traffic services. There are two
5656 types: "standard" and "dynamic". The standard type defines
5657 one service id - http (id 0). The dynamic service ids can be from
5658 51 to 255 inclusive. In order to use a dynamic service id
5659 one must define the type of traffic to be redirected; this is done
5660 using the wccp2_service_info option.
5661
5662 The "standard" type does not require a wccp2_service_info option,
5663 just specifying the service id will suffice.
5664
5665 MD5 service authentication can be enabled by adding
5666 "password=<password>" to the end of this service declaration.
5667
5668 Examples:
5669
5670 wccp2_service standard 0 # for the 'web-cache' standard service
5671 wccp2_service dynamic 80 # a dynamic service type which will be
5672 # fleshed out with subsequent options.
5673 wccp2_service standard 0 password=foo
8d6275c0 5674DOC_END
5675
5676NAME: wccp2_service_info
5677TYPE: wccp2_service_info
5678LOC: Config.Wccp2.info
5679DEFAULT: none
5680IFDEF: USE_WCCPv2
5681DOC_START
5682 Dynamic WCCPv2 services require further information to define the
5683 traffic you wish to have diverted.
5684
5685 The format is:
5686
5687 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
5688 priority=<priority> ports=<port>,<port>..
5689
5690 The relevant WCCPv2 flags:
5691 + src_ip_hash, dst_ip_hash
005fe566 5692 + source_port_hash, dst_port_hash
8d6275c0 5693 + src_ip_alt_hash, dst_ip_alt_hash
5694 + src_port_alt_hash, dst_port_alt_hash
5695 + ports_source
5696
5697 The port list can be one to eight entries.
5698
5699 Example:
5700
5701 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
5702 priority=240 ports=80
5703
5704 Note: the service id must have been defined by a previous
5705 'wccp2_service dynamic <id>' entry.
5706DOC_END
5707
5708NAME: wccp2_weight
5709TYPE: int
5710LOC: Config.Wccp2.weight
5711DEFAULT: 10000
5712IFDEF: USE_WCCPv2
5713DOC_START
5714 Each cache server gets assigned a set of the destination
5715 hash proportional to their weight.
5716DOC_END
5717
5718NAME: wccp_address
5719TYPE: address
5720LOC: Config.Wccp.address
5721DEFAULT: 0.0.0.0
5722IFDEF: USE_WCCP
5723DOC_NONE
df2eec10 5724
8d6275c0 5725NAME: wccp2_address
5726TYPE: address
5727LOC: Config.Wccp2.address
5728DEFAULT: 0.0.0.0
5729IFDEF: USE_WCCPv2
5730DOC_START
5731 Use this option if you require WCCP to use a specific
5732 interface address.
5733
5734 The default behavior is to not bind to any specific address.
5735DOC_END
5736
5737COMMENT_START
5738 PERSISTENT CONNECTION HANDLING
5739 -----------------------------------------------------------------------------
5740
5741 Also see "pconn_timeout" in the TIMEOUTS section
5742COMMENT_END
5743
5744NAME: client_persistent_connections
5745TYPE: onoff
5746LOC: Config.onoff.client_pconns
5747DEFAULT: on
5748DOC_NONE
5749
5750NAME: server_persistent_connections
5751TYPE: onoff
5752LOC: Config.onoff.server_pconns
5753DEFAULT: on
5754DOC_START
5755 Persistent connection support for clients and servers. By
5756 default, Squid uses persistent connections (when allowed)
5757 with its clients and servers. You can use these options to
5758 disable persistent connections with clients and/or servers.
5759DOC_END
5760
5761NAME: persistent_connection_after_error
5762TYPE: onoff
5763LOC: Config.onoff.error_pconns
0fccfb7f 5764DEFAULT: on
8d6275c0 5765DOC_START
5766 With this directive the use of persistent connections after
5767 HTTP errors can be disabled. Useful if you have clients
5768 who fail to handle errors on persistent connections proper.
5769DOC_END
5770
5771NAME: detect_broken_pconn
5772TYPE: onoff
5773LOC: Config.onoff.detect_broken_server_pconns
5774DEFAULT: off
5775DOC_START
5776 Some servers have been found to incorrectly signal the use
5777 of HTTP/1.0 persistent connections even on replies not
5778 compatible, causing significant delays. This server problem
5779 has mostly been seen on redirects.
5780
5781 By enabling this directive Squid attempts to detect such
5782 broken replies and automatically assume the reply is finished
5783 after 10 seconds timeout.
5784DOC_END
5785
5786COMMENT_START
5787 CACHE DIGEST OPTIONS
5788 -----------------------------------------------------------------------------
5789COMMENT_END
5790
5791NAME: digest_generation
5792IFDEF: USE_CACHE_DIGESTS
5793TYPE: onoff
5794LOC: Config.onoff.digest_generation
5795DEFAULT: on
5796DOC_START
5797 This controls whether the server will generate a Cache Digest
5798 of its contents. By default, Cache Digest generation is
13e917b5 5799 enabled if Squid is compiled with --enable-cache-digests defined.
8d6275c0 5800DOC_END
5801
5802NAME: digest_bits_per_entry
5803IFDEF: USE_CACHE_DIGESTS
5804TYPE: int
5805LOC: Config.digest.bits_per_entry
5806DEFAULT: 5
5807DOC_START
5808 This is the number of bits of the server's Cache Digest which
5809 will be associated with the Digest entry for a given HTTP
5810 Method and URL (public key) combination. The default is 5.
5811DOC_END
5812
5813NAME: digest_rebuild_period
5814IFDEF: USE_CACHE_DIGESTS
5815COMMENT: (seconds)
5816TYPE: time_t
5817LOC: Config.digest.rebuild_period
5818DEFAULT: 1 hour
5819DOC_START
749ceff8 5820 This is the wait time between Cache Digest rebuilds.
8d6275c0 5821DOC_END
5822
5823NAME: digest_rewrite_period
5824COMMENT: (seconds)
5825IFDEF: USE_CACHE_DIGESTS
5826TYPE: time_t
5827LOC: Config.digest.rewrite_period
5828DEFAULT: 1 hour
5829DOC_START
749ceff8 5830 This is the wait time between Cache Digest writes to
8d6275c0 5831 disk.
5832DOC_END
5833
5834NAME: digest_swapout_chunk_size
5835COMMENT: (bytes)
5836TYPE: b_size_t
5837IFDEF: USE_CACHE_DIGESTS
5838LOC: Config.digest.swapout_chunk_size
5839DEFAULT: 4096 bytes
5840DOC_START
5841 This is the number of bytes of the Cache Digest to write to
5842 disk at a time. It defaults to 4096 bytes (4KB), the Squid
5843 default swap page.
5844DOC_END
5845
5846NAME: digest_rebuild_chunk_percentage
5847COMMENT: (percent, 0-100)
5848IFDEF: USE_CACHE_DIGESTS
5849TYPE: int
5850LOC: Config.digest.rebuild_chunk_percentage
5851DEFAULT: 10
5852DOC_START
5853 This is the percentage of the Cache Digest to be scanned at a
5854 time. By default it is set to 10% of the Cache Digest.
5855DOC_END
5856
1db9eacd 5857COMMENT_START
5473c134 5858 SNMP OPTIONS
1db9eacd 5859 -----------------------------------------------------------------------------
5860COMMENT_END
5861
5473c134 5862NAME: snmp_port
ae870270 5863TYPE: u_short
5473c134 5864LOC: Config.Port.snmp
87630341 5865DEFAULT: 0
5473c134 5866IFDEF: SQUID_SNMP
8d6275c0 5867DOC_START
87630341 5868 The port number where Squid listens for SNMP requests. To enable
5869 SNMP support set this to a suitable port number. Port number
5870 3401 is often used for the Squid SNMP agent. By default it's
5871 set to "0" (disabled)
e0855596
AJ
5872
5873 Example:
5874 snmp_port 3401
8d6275c0 5875DOC_END
5876
5473c134 5877NAME: snmp_access
5878TYPE: acl_access
5879LOC: Config.accessList.snmp
5473c134 5880DEFAULT_IF_NONE: deny all
5881IFDEF: SQUID_SNMP
8d6275c0 5882DOC_START
5473c134 5883 Allowing or denying access to the SNMP port.
8d6275c0 5884
5473c134 5885 All access to the agent is denied by default.
5886 usage:
8d6275c0 5887
5473c134 5888 snmp_access allow|deny [!]aclname ...
8d6275c0 5889
b3567eb5
FC
5890 This clause only supports fast acl types.
5891 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5473c134 5892Example:
5893 snmp_access allow snmppublic localhost
5894 snmp_access deny all
cccac0a2 5895DOC_END
5896
5473c134 5897NAME: snmp_incoming_address
5898TYPE: address
5899LOC: Config.Addrs.snmp_incoming
0eb08770 5900DEFAULT: any_addr
5473c134 5901IFDEF: SQUID_SNMP
5902DOC_NONE
df2eec10 5903
5473c134 5904NAME: snmp_outgoing_address
5905TYPE: address
5906LOC: Config.Addrs.snmp_outgoing
0eb08770 5907DEFAULT: no_addr
5473c134 5908IFDEF: SQUID_SNMP
cccac0a2 5909DOC_START
df2eec10 5910 Just like 'udp_incoming_address', but for the SNMP port.
cccac0a2 5911
5473c134 5912 snmp_incoming_address is used for the SNMP socket receiving
5913 messages from SNMP agents.
5914 snmp_outgoing_address is used for SNMP packets returned to SNMP
5915 agents.
cccac0a2 5916
0eb08770 5917 The default snmp_incoming_address is to listen on all
5473c134 5918 available network interfaces.
cccac0a2 5919
0eb08770
HN
5920 If snmp_outgoing_address is not set it will use the same socket
5921 as snmp_incoming_address. Only change this if you want to have
5922 SNMP replies sent using another address than where this Squid
5923 listens for SNMP queries.
cccac0a2 5924
5473c134 5925 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
5926 the same value since they both use port 3401.
cccac0a2 5927DOC_END
5928
5473c134 5929COMMENT_START
5930 ICP OPTIONS
5931 -----------------------------------------------------------------------------
5932COMMENT_END
5933
5934NAME: icp_port udp_port
ae870270 5935TYPE: u_short
5473c134 5936DEFAULT: 0
5937LOC: Config.Port.icp
cccac0a2 5938DOC_START
5473c134 5939 The port number where Squid sends and receives ICP queries to
5940 and from neighbor caches. The standard UDP port for ICP is 3130.
5941 Default is disabled (0).
e0855596
AJ
5942
5943 Example:
5944 icp_port @DEFAULT_ICP_PORT@
cccac0a2 5945DOC_END
5946
5473c134 5947NAME: htcp_port
5948IFDEF: USE_HTCP
ae870270 5949TYPE: u_short
87630341 5950DEFAULT: 0
5473c134 5951LOC: Config.Port.htcp
cccac0a2 5952DOC_START
5473c134 5953 The port number where Squid sends and receives HTCP queries to
87630341 5954 and from neighbor caches. To turn it on you want to set it to
5955 4827. By default it is set to "0" (disabled).
e0855596
AJ
5956
5957 Example:
5958 htcp_port 4827
cccac0a2 5959DOC_END
5960
5961NAME: log_icp_queries
5962COMMENT: on|off
5963TYPE: onoff
5964DEFAULT: on
5965LOC: Config.onoff.log_udp
5966DOC_START
5967 If set, ICP queries are logged to access.log. You may wish
5968 do disable this if your ICP load is VERY high to speed things
5969 up or to simplify log analysis.
5970DOC_END
5971
5473c134 5972NAME: udp_incoming_address
5973TYPE: address
5974LOC:Config.Addrs.udp_incoming
0eb08770 5975DEFAULT: any_addr
8524d4b2 5976DOC_START
5977 udp_incoming_address is used for UDP packets received from other
5978 caches.
5979
5980 The default behavior is to not bind to any specific address.
5981
5982 Only change this if you want to have all UDP queries received on
5983 a specific interface/address.
5984
5985 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
5986 modules. Altering it will affect all of them in the same manner.
5987
5988 see also; udp_outgoing_address
5989
5990 NOTE, udp_incoming_address and udp_outgoing_address can not
5991 have the same value since they both use the same port.
5992DOC_END
cccac0a2 5993
5473c134 5994NAME: udp_outgoing_address
5995TYPE: address
5996LOC: Config.Addrs.udp_outgoing
0eb08770 5997DEFAULT: no_addr
cccac0a2 5998DOC_START
8524d4b2 5999 udp_outgoing_address is used for UDP packets sent out to other
5473c134 6000 caches.
cccac0a2 6001
5473c134 6002 The default behavior is to not bind to any specific address.
cccac0a2 6003
8524d4b2 6004 Instead it will use the same socket as udp_incoming_address.
6005 Only change this if you want to have UDP queries sent using another
6006 address than where this Squid listens for UDP queries from other
5473c134 6007 caches.
6008
8524d4b2 6009 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
6010 modules. Altering it will affect all of them in the same manner.
6011
6012 see also; udp_incoming_address
6013
5473c134 6014 NOTE, udp_incoming_address and udp_outgoing_address can not
8524d4b2 6015 have the same value since they both use the same port.
cccac0a2 6016DOC_END
6017
3d1e3e43 6018NAME: icp_hit_stale
6019COMMENT: on|off
6020TYPE: onoff
6021DEFAULT: off
6022LOC: Config.onoff.icp_hit_stale
6023DOC_START
6024 If you want to return ICP_HIT for stale cache objects, set this
6025 option to 'on'. If you have sibling relationships with caches
6026 in other administrative domains, this should be 'off'. If you only
6027 have sibling relationships with caches under your control,
6028 it is probably okay to set this to 'on'.
6029 If set to 'on', your siblings should use the option "allow-miss"
6030 on their cache_peer lines for connecting to you.
6031DOC_END
6032
5473c134 6033NAME: minimum_direct_hops
cccac0a2 6034TYPE: int
5473c134 6035DEFAULT: 4
6036LOC: Config.minDirectHops
cccac0a2 6037DOC_START
5473c134 6038 If using the ICMP pinging stuff, do direct fetches for sites
6039 which are no more than this many hops away.
cccac0a2 6040DOC_END
6041
5473c134 6042NAME: minimum_direct_rtt
6043TYPE: int
6044DEFAULT: 400
6045LOC: Config.minDirectRtt
cccac0a2 6046DOC_START
5473c134 6047 If using the ICMP pinging stuff, do direct fetches for sites
6048 which are no more than this many rtt milliseconds away.
cccac0a2 6049DOC_END
6050
cccac0a2 6051NAME: netdb_low
6052TYPE: int
6053DEFAULT: 900
6054LOC: Config.Netdb.low
6055DOC_NONE
6056
6057NAME: netdb_high
6058TYPE: int
6059DEFAULT: 1000
6060LOC: Config.Netdb.high
6061DOC_START
6062 The low and high water marks for the ICMP measurement
6063 database. These are counts, not percents. The defaults are
6064 900 and 1000. When the high water mark is reached, database
6065 entries will be deleted until the low mark is reached.
6066DOC_END
6067
cccac0a2 6068NAME: netdb_ping_period
6069TYPE: time_t
6070LOC: Config.Netdb.period
6071DEFAULT: 5 minutes
6072DOC_START
6073 The minimum period for measuring a site. There will be at
6074 least this much delay between successive pings to the same
6075 network. The default is five minutes.
6076DOC_END
6077
cccac0a2 6078NAME: query_icmp
6079COMMENT: on|off
6080TYPE: onoff
6081DEFAULT: off
6082LOC: Config.onoff.query_icmp
6083DOC_START
6084 If you want to ask your peers to include ICMP data in their ICP
6085 replies, enable this option.
6086
6087 If your peer has configured Squid (during compilation) with
7f7db318 6088 '--enable-icmp' that peer will send ICMP pings to origin server
6089 sites of the URLs it receives. If you enable this option the
cccac0a2 6090 ICP replies from that peer will include the ICMP data (if available).
6091 Then, when choosing a parent cache, Squid will choose the parent with
6092 the minimal RTT to the origin server. When this happens, the
6093 hierarchy field of the access.log will be
6094 "CLOSEST_PARENT_MISS". This option is off by default.
6095DOC_END
6096
6097NAME: test_reachability
6098COMMENT: on|off
6099TYPE: onoff
6100DEFAULT: off
6101LOC: Config.onoff.test_reachability
6102DOC_START
6103 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
6104 instead of ICP_MISS if the target host is NOT in the ICMP
6105 database, or has a zero RTT.
6106DOC_END
6107
5473c134 6108NAME: icp_query_timeout
6109COMMENT: (msec)
6110DEFAULT: 0
6111TYPE: int
6112LOC: Config.Timeout.icp_query
4c3ef9b2 6113DOC_START
5473c134 6114 Normally Squid will automatically determine an optimal ICP
6115 query timeout value based on the round-trip-time of recent ICP
6116 queries. If you want to override the value determined by
6117 Squid, set this 'icp_query_timeout' to a non-zero value. This
6118 value is specified in MILLISECONDS, so, to use a 2-second
6119 timeout (the old default), you would write:
4c3ef9b2 6120
5473c134 6121 icp_query_timeout 2000
4c3ef9b2 6122DOC_END
6123
5473c134 6124NAME: maximum_icp_query_timeout
6125COMMENT: (msec)
6126DEFAULT: 2000
6127TYPE: int
6128LOC: Config.Timeout.icp_query_max
cccac0a2 6129DOC_START
5473c134 6130 Normally the ICP query timeout is determined dynamically. But
6131 sometimes it can lead to very large values (say 5 seconds).
6132 Use this option to put an upper limit on the dynamic timeout
6133 value. Do NOT use this option to always use a fixed (instead
6134 of a dynamic) timeout value. To set a fixed timeout see the
6135 'icp_query_timeout' directive.
cccac0a2 6136DOC_END
6137
5473c134 6138NAME: minimum_icp_query_timeout
6139COMMENT: (msec)
6140DEFAULT: 5
6141TYPE: int
6142LOC: Config.Timeout.icp_query_min
cccac0a2 6143DOC_START
5473c134 6144 Normally the ICP query timeout is determined dynamically. But
6145 sometimes it can lead to very small timeouts, even lower than
6146 the normal latency variance on your link due to traffic.
6147 Use this option to put an lower limit on the dynamic timeout
6148 value. Do NOT use this option to always use a fixed (instead
6149 of a dynamic) timeout value. To set a fixed timeout see the
6150 'icp_query_timeout' directive.
cccac0a2 6151DOC_END
6152
5473c134 6153NAME: background_ping_rate
6154COMMENT: time-units
6155TYPE: time_t
6156DEFAULT: 10 seconds
6157LOC: Config.backgroundPingRate
cccac0a2 6158DOC_START
5473c134 6159 Controls how often the ICP pings are sent to siblings that
6160 have background-ping set.
cccac0a2 6161DOC_END
6162
5473c134 6163COMMENT_START
6164 MULTICAST ICP OPTIONS
6165 -----------------------------------------------------------------------------
6166COMMENT_END
6167
6168NAME: mcast_groups
6169TYPE: wordlist
6170LOC: Config.mcast_group_list
8c01ada0 6171DEFAULT: none
6172DOC_START
5473c134 6173 This tag specifies a list of multicast groups which your server
6174 should join to receive multicasted ICP queries.
8c01ada0 6175
5473c134 6176 NOTE! Be very careful what you put here! Be sure you
6177 understand the difference between an ICP _query_ and an ICP
6178 _reply_. This option is to be set only if you want to RECEIVE
6179 multicast queries. Do NOT set this option to SEND multicast
6180 ICP (use cache_peer for that). ICP replies are always sent via
6181 unicast, so this option does not affect whether or not you will
6182 receive replies from multicast group members.
8c01ada0 6183
5473c134 6184 You must be very careful to NOT use a multicast address which
6185 is already in use by another group of caches.
8c01ada0 6186
5473c134 6187 If you are unsure about multicast, please read the Multicast
6188 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
8c01ada0 6189
5473c134 6190 Usage: mcast_groups 239.128.16.128 224.0.1.20
8c01ada0 6191
5473c134 6192 By default, Squid doesn't listen on any multicast groups.
6193DOC_END
8c01ada0 6194
5473c134 6195NAME: mcast_miss_addr
6196IFDEF: MULTICAST_MISS_STREAM
6197TYPE: address
6198LOC: Config.mcast_miss.addr
0eb08770 6199DEFAULT: no_addr
5473c134 6200DOC_START
6201 If you enable this option, every "cache miss" URL will
6202 be sent out on the specified multicast address.
cccac0a2 6203
5473c134 6204 Do not enable this option unless you are are absolutely
6205 certain you understand what you are doing.
cccac0a2 6206DOC_END
6207
5473c134 6208NAME: mcast_miss_ttl
6209IFDEF: MULTICAST_MISS_STREAM
ae870270 6210TYPE: u_short
5473c134 6211LOC: Config.mcast_miss.ttl
6212DEFAULT: 16
cccac0a2 6213DOC_START
5473c134 6214 This is the time-to-live value for packets multicasted
6215 when multicasting off cache miss URLs is enabled. By
6216 default this is set to 'site scope', i.e. 16.
6217DOC_END
cccac0a2 6218
5473c134 6219NAME: mcast_miss_port
6220IFDEF: MULTICAST_MISS_STREAM
ae870270 6221TYPE: u_short
5473c134 6222LOC: Config.mcast_miss.port
6223DEFAULT: 3135
6224DOC_START
6225 This is the port number to be used in conjunction with
6226 'mcast_miss_addr'.
6227DOC_END
cccac0a2 6228
5473c134 6229NAME: mcast_miss_encode_key
6230IFDEF: MULTICAST_MISS_STREAM
6231TYPE: string
6232LOC: Config.mcast_miss.encode_key
6233DEFAULT: XXXXXXXXXXXXXXXX
6234DOC_START
6235 The URLs that are sent in the multicast miss stream are
6236 encrypted. This is the encryption key.
6237DOC_END
8c01ada0 6238
5473c134 6239NAME: mcast_icp_query_timeout
6240COMMENT: (msec)
6241DEFAULT: 2000
6242TYPE: int
6243LOC: Config.Timeout.mcast_icp_query
6244DOC_START
6245 For multicast peers, Squid regularly sends out ICP "probes" to
6246 count how many other peers are listening on the given multicast
6247 address. This value specifies how long Squid should wait to
6248 count all the replies. The default is 2000 msec, or 2
6249 seconds.
cccac0a2 6250DOC_END
6251
5473c134 6252COMMENT_START
6253 INTERNAL ICON OPTIONS
6254 -----------------------------------------------------------------------------
6255COMMENT_END
6256
cccac0a2 6257NAME: icon_directory
6258TYPE: string
6259LOC: Config.icons.directory
6260DEFAULT: @DEFAULT_ICON_DIR@
6261DOC_START
6262 Where the icons are stored. These are normally kept in
6263 @DEFAULT_ICON_DIR@
6264DOC_END
6265
f024c970 6266NAME: global_internal_static
6267TYPE: onoff
6268LOC: Config.onoff.global_internal_static
6269DEFAULT: on
6270DOC_START
6271 This directive controls is Squid should intercept all requests for
6272 /squid-internal-static/ no matter which host the URL is requesting
6273 (default on setting), or if nothing special should be done for
6274 such URLs (off setting). The purpose of this directive is to make
6275 icons etc work better in complex cache hierarchies where it may
6276 not always be possible for all corners in the cache mesh to reach
6277 the server generating a directory listing.
6278DOC_END
6279
5473c134 6280NAME: short_icon_urls
6281TYPE: onoff
6282LOC: Config.icons.use_short_names
6283DEFAULT: on
6284DOC_START
6285 If this is enabled Squid will use short URLs for icons.
6286 If disabled it will revert to the old behavior of including
6287 it's own name and port in the URL.
6288
6289 If you run a complex cache hierarchy with a mix of Squid and
6290 other proxies you may need to disable this directive.
6291DOC_END
6292
6293COMMENT_START
6294 ERROR PAGE OPTIONS
6295 -----------------------------------------------------------------------------
6296COMMENT_END
6297
6298NAME: error_directory
6299TYPE: string
6300LOC: Config.errorDirectory
43000484 6301DEFAULT: none
5473c134 6302DOC_START
6303 If you wish to create your own versions of the default
43000484
AJ
6304 error files to customize them to suit your company copy
6305 the error/template files to another directory and point
6306 this tag at them.
6307
6308 WARNING: This option will disable multi-language support
6309 on error pages if used.
5473c134 6310
6311 The squid developers are interested in making squid available in
6312 a wide variety of languages. If you are making translations for a
43000484 6313 language that Squid does not currently provide please consider
5473c134 6314 contributing your translation back to the project.
43000484
AJ
6315 http://wiki.squid-cache.org/Translations
6316
6317 The squid developers working on translations are happy to supply drop-in
6318 translated error files in exchange for any new language contributions.
6319DOC_END
6320
6321NAME: error_default_language
6322IFDEF: USE_ERR_LOCALES
6323TYPE: string
6324LOC: Config.errorDefaultLanguage
6325DEFAULT: none
6326DOC_START
6327 Set the default language which squid will send error pages in
6328 if no existing translation matches the clients language
6329 preferences.
6330
6331 If unset (default) generic English will be used.
6332
6333 The squid developers are interested in making squid available in
6334 a wide variety of languages. If you are interested in making
6335 translations for any language see the squid wiki for details.
6336 http://wiki.squid-cache.org/Translations
5473c134 6337DOC_END
6338
c411820c
AJ
6339NAME: error_log_languages
6340IFDEF: USE_ERR_LOCALES
6341TYPE: onoff
6342LOC: Config.errorLogMissingLanguages
6343DEFAULT: on
6344DOC_START
6345 Log to cache.log what languages users are attempting to
6346 auto-negotiate for translations.
6347
6348 Successful negotiations are not logged. Only failures
6349 have meaning to indicate that Squid may need an upgrade
0c49f10e 6350 of its error page translations.
c411820c
AJ
6351DOC_END
6352
5b52cb6c
AJ
6353NAME: err_page_stylesheet
6354TYPE: string
6355LOC: Config.errorStylesheet
6356DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
6357DOC_START
6358 CSS Stylesheet to pattern the display of Squid default error pages.
6359
6360 For information on CSS see http://www.w3.org/Style/CSS/
6361DOC_END
6362
5473c134 6363NAME: err_html_text
6364TYPE: eol
6365LOC: Config.errHtmlText
6366DEFAULT: none
6367DOC_START
6368 HTML text to include in error messages. Make this a "mailto"
6369 URL to your admin address, or maybe just a link to your
6370 organizations Web page.
6371
6372 To include this in your error messages, you must rewrite
6373 the error template files (found in the "errors" directory).
6374 Wherever you want the 'err_html_text' line to appear,
6375 insert a %L tag in the error template file.
6376DOC_END
6377
6378NAME: email_err_data
6379COMMENT: on|off
6380TYPE: onoff
6381LOC: Config.onoff.emailErrData
6382DEFAULT: on
6383DOC_START
6384 If enabled, information about the occurred error will be
6385 included in the mailto links of the ERR pages (if %W is set)
6386 so that the email body contains the data.
6387 Syntax is <A HREF="mailto:%w%W">%w</A>
6388DOC_END
6389
6390NAME: deny_info
6391TYPE: denyinfo
6392LOC: Config.denyInfoList
6393DEFAULT: none
6394DOC_START
6395 Usage: deny_info err_page_name acl
6396 or deny_info http://... acl
43000484 6397 or deny_info TCP_RESET acl
5473c134 6398
6399 This can be used to return a ERR_ page for requests which
6400 do not pass the 'http_access' rules. Squid remembers the last
6401 acl it evaluated in http_access, and if a 'deny_info' line exists
6402 for that ACL Squid returns a corresponding error page.
6403
6404 The acl is typically the last acl on the http_access deny line which
6405 denied access. The exceptions to this rule are:
6406 - When Squid needs to request authentication credentials. It's then
6407 the first authentication related acl encountered
6408 - When none of the http_access lines matches. It's then the last
6409 acl processed on the last http_access line.
3af10ac0
AR
6410 - When the decision to deny access was made by an adaptation service,
6411 the acl name is the corresponding eCAP or ICAP service_name.
5473c134 6412
43000484
AJ
6413 NP: If providing your own custom error pages with error_directory
6414 you may also specify them by your custom file name:
6415 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
5473c134 6416
aed9a15b
AJ
6417 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
6418 may be specified by prefixing the file name with the code and a colon.
6419 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
6420
5473c134 6421 Alternatively you can tell Squid to reset the TCP connection
6422 by specifying TCP_RESET.
15b02e9a
AJ
6423
6424 Or you can specify an error URL or URL pattern. The browsers will
aed9a15b
AJ
6425 get redirected to the specified URL after formatting tags have
6426 been replaced. Redirect will be done with 302 or 307 according to
6427 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
6428 the URL. e.g. 303:http://example.com/
15b02e9a
AJ
6429
6430 URL FORMAT TAGS:
6431 %a - username (if available. Password NOT included)
6432 %B - FTP path URL
6433 %e - Error number
6434 %E - Error description
6435 %h - Squid hostname
6436 %H - Request domain name
6437 %i - Client IP Address
6438 %M - Request Method
6439 %o - Message result from external ACL helper
6440 %p - Request Port number
6441 %P - Request Protocol name
6442 %R - Request URL path
6443 %T - Timestamp in RFC 1123 format
6444 %U - Full canonical URL from client
6445 (HTTPS URLs terminate with *)
6446 %u - Full canonical URL from client
6447 %w - Admin email from squid.conf
e4a8468d 6448 %x - Error name
15b02e9a
AJ
6449 %% - Literal percent (%) code
6450
5473c134 6451DOC_END
6452
6453COMMENT_START
6454 OPTIONS INFLUENCING REQUEST FORWARDING
6455 -----------------------------------------------------------------------------
6456COMMENT_END
6457
6458NAME: nonhierarchical_direct
e72a0ec0 6459TYPE: onoff
5473c134 6460LOC: Config.onoff.nonhierarchical_direct
e72a0ec0 6461DEFAULT: on
6462DOC_START
5473c134 6463 By default, Squid will send any non-hierarchical requests
6464 (matching hierarchy_stoplist or not cacheable request type) direct
6465 to origin servers.
e72a0ec0 6466
5473c134 6467 If you set this to off, Squid will prefer to send these
6468 requests to parents.
0b0cfcf2 6469
5473c134 6470 Note that in most configurations, by turning this off you will only
6471 add latency to these request without any improvement in global hit
6472 ratio.
0b0cfcf2 6473
5473c134 6474 If you are inside an firewall see never_direct instead of
6475 this directive.
8d6275c0 6476DOC_END
0b0cfcf2 6477
5473c134 6478NAME: prefer_direct
8d6275c0 6479TYPE: onoff
5473c134 6480LOC: Config.onoff.prefer_direct
8d6275c0 6481DEFAULT: off
6482DOC_START
5473c134 6483 Normally Squid tries to use parents for most requests. If you for some
6484 reason like it to first try going direct and only use a parent if
6485 going direct fails set this to on.
0b0cfcf2 6486
5473c134 6487 By combining nonhierarchical_direct off and prefer_direct on you
6488 can set up Squid to use a parent as a backup path if going direct
6489 fails.
6490
6491 Note: If you want Squid to use parents for all requests see
6492 the never_direct directive. prefer_direct only modifies how Squid
6493 acts on cacheable requests.
cccac0a2 6494DOC_END
6495
5473c134 6496NAME: always_direct
8d6275c0 6497TYPE: acl_access
5473c134 6498LOC: Config.accessList.AlwaysDirect
0b0cfcf2 6499DEFAULT: none
0b0cfcf2 6500DOC_START
5473c134 6501 Usage: always_direct allow|deny [!]aclname ...
0b0cfcf2 6502
5473c134 6503 Here you can use ACL elements to specify requests which should
6504 ALWAYS be forwarded by Squid to the origin servers without using
6505 any peers. For example, to always directly forward requests for
6506 local servers ignoring any parents or siblings you may have use
6507 something like:
0b0cfcf2 6508
5473c134 6509 acl local-servers dstdomain my.domain.net
6510 always_direct allow local-servers
0b0cfcf2 6511
5473c134 6512 To always forward FTP requests directly, use
f16fbc82 6513
5473c134 6514 acl FTP proto FTP
6515 always_direct allow FTP
cccac0a2 6516
5473c134 6517 NOTE: There is a similar, but opposite option named
6518 'never_direct'. You need to be aware that "always_direct deny
6519 foo" is NOT the same thing as "never_direct allow foo". You
6520 may need to use a deny rule to exclude a more-specific case of
6521 some other rule. Example:
8d6275c0 6522
5473c134 6523 acl local-external dstdomain external.foo.net
6524 acl local-servers dstdomain .foo.net
6525 always_direct deny local-external
6526 always_direct allow local-servers
8d6275c0 6527
5473c134 6528 NOTE: If your goal is to make the client forward the request
6529 directly to the origin server bypassing Squid then this needs
6530 to be done in the client configuration. Squid configuration
6531 can only tell Squid how Squid should fetch the object.
8d6275c0 6532
5473c134 6533 NOTE: This directive is not related to caching. The replies
6534 is cached as usual even if you use always_direct. To not cache
b3567eb5 6535 the replies see the 'cache' directive.
5473c134 6536
b3567eb5
FC
6537 This clause supports both fast and slow acl types.
6538 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
cccac0a2 6539DOC_END
0976f8db 6540
5473c134 6541NAME: never_direct
6542TYPE: acl_access
6543LOC: Config.accessList.NeverDirect
6544DEFAULT: none
8d6275c0 6545DOC_START
5473c134 6546 Usage: never_direct allow|deny [!]aclname ...
6547
6548 never_direct is the opposite of always_direct. Please read
6549 the description for always_direct if you have not already.
6550
6551 With 'never_direct' you can use ACL elements to specify
6552 requests which should NEVER be forwarded directly to origin
6553 servers. For example, to force the use of a proxy for all
6554 requests, except those in your local domain use something like:
6555
6556 acl local-servers dstdomain .foo.net
5473c134 6557 never_direct deny local-servers
6558 never_direct allow all
6559
6560 or if Squid is inside a firewall and there are local intranet
6561 servers inside the firewall use something like:
6562
6563 acl local-intranet dstdomain .foo.net
6564 acl local-external dstdomain external.foo.net
6565 always_direct deny local-external
6566 always_direct allow local-intranet
6567 never_direct allow all
6568
b3567eb5
FC
6569 This clause supports both fast and slow acl types.
6570 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
8d6275c0 6571DOC_END
0976f8db 6572
5473c134 6573COMMENT_START
6574 ADVANCED NETWORKING OPTIONS
6575 -----------------------------------------------------------------------------
6576COMMENT_END
6577
65d448bc 6578NAME: incoming_udp_average incoming_icp_average
cccac0a2 6579TYPE: int
6580DEFAULT: 6
65d448bc
AJ
6581LOC: Config.comm_incoming.udp.average
6582DOC_START
6583 Heavy voodoo here. I can't even believe you are reading this.
6584 Are you crazy? Don't even think about adjusting these unless
6585 you understand the algorithms in comm_select.c first!
6586DOC_END
cccac0a2 6587
65d448bc 6588NAME: incoming_tcp_average incoming_http_average
cccac0a2 6589TYPE: int
6590DEFAULT: 4
65d448bc
AJ
6591LOC: Config.comm_incoming.tcp.average
6592DOC_START
6593 Heavy voodoo here. I can't even believe you are reading this.
6594 Are you crazy? Don't even think about adjusting these unless
6595 you understand the algorithms in comm_select.c first!
6596DOC_END
cccac0a2 6597
6598NAME: incoming_dns_average
6599TYPE: int
6600DEFAULT: 4
65d448bc
AJ
6601LOC: Config.comm_incoming.dns.average
6602DOC_START
6603 Heavy voodoo here. I can't even believe you are reading this.
6604 Are you crazy? Don't even think about adjusting these unless
6605 you understand the algorithms in comm_select.c first!
6606DOC_END
cccac0a2 6607
65d448bc 6608NAME: min_udp_poll_cnt min_icp_poll_cnt
cccac0a2 6609TYPE: int
6610DEFAULT: 8
65d448bc
AJ
6611LOC: Config.comm_incoming.udp.min_poll
6612DOC_START
6613 Heavy voodoo here. I can't even believe you are reading this.
6614 Are you crazy? Don't even think about adjusting these unless
6615 you understand the algorithms in comm_select.c first!
6616DOC_END
cccac0a2 6617
6618NAME: min_dns_poll_cnt
6619TYPE: int
6620DEFAULT: 8
65d448bc
AJ
6621LOC: Config.comm_incoming.dns.min_poll
6622DOC_START
6623 Heavy voodoo here. I can't even believe you are reading this.
6624 Are you crazy? Don't even think about adjusting these unless
6625 you understand the algorithms in comm_select.c first!
6626DOC_END
cccac0a2 6627
65d448bc 6628NAME: min_tcp_poll_cnt min_http_poll_cnt
cccac0a2 6629TYPE: int
6630DEFAULT: 8
65d448bc 6631LOC: Config.comm_incoming.tcp.min_poll
cccac0a2 6632DOC_START
5473c134 6633 Heavy voodoo here. I can't even believe you are reading this.
6634 Are you crazy? Don't even think about adjusting these unless
6635 you understand the algorithms in comm_select.c first!
6636DOC_END
6637
6638NAME: accept_filter
5473c134 6639TYPE: string
6640DEFAULT: none
6641LOC: Config.accept_filter
6642DOC_START
0b4d4be5 6643 FreeBSD:
6644
5473c134 6645 The name of an accept(2) filter to install on Squid's
6646 listen socket(s). This feature is perhaps specific to
6647 FreeBSD and requires support in the kernel.
6648
6649 The 'httpready' filter delays delivering new connections
2324cda2 6650 to Squid until a full HTTP request has been received.
0b4d4be5 6651 See the accf_http(9) man page for details.
6652
6653 The 'dataready' filter delays delivering new connections
6654 to Squid until there is some data to process.
6655 See the accf_dataready(9) man page for details.
6656
6657 Linux:
6658
6659 The 'data' filter delays delivering of new connections
6660 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
6661 You may optionally specify a number of seconds to wait by
6662 'data=N' where N is the number of seconds. Defaults to 30
6663 if not specified. See the tcp(7) man page for details.
5473c134 6664EXAMPLE:
0b4d4be5 6665# FreeBSD
5473c134 6666accept_filter httpready
0b4d4be5 6667# Linux
6668accept_filter data
5473c134 6669DOC_END
6670
ab2ecb0e
AJ
6671NAME: client_ip_max_connections
6672TYPE: int
6673LOC: Config.client_ip_max_connections
6674DEFAULT: -1
6675DOC_START
6676 Set an absolute limit on the number of connections a single
6677 client IP can use. Any more than this and Squid will begin to drop
6678 new connections from the client until it closes some links.
6679
6680 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
6681 connections from the client. For finer control use the ACL access controls.
6682
6683 Requires client_db to be enabled (the default).
6684
6685 WARNING: This may noticably slow down traffic received via external proxies
6686 or NAT devices and cause them to rebound error messages back to their clients.
6687DOC_END
6688
5473c134 6689NAME: tcp_recv_bufsize
6690COMMENT: (bytes)
6691TYPE: b_size_t
6692DEFAULT: 0 bytes
6693LOC: Config.tcpRcvBufsz
6694DOC_START
6695 Size of receive buffer to set for TCP sockets. Probably just
6696 as easy to change your kernel's default. Set to zero to use
6697 the default buffer size.
6698DOC_END
6699
6700COMMENT_START
6701 ICAP OPTIONS
6702 -----------------------------------------------------------------------------
6703COMMENT_END
6704
6705NAME: icap_enable
6706TYPE: onoff
6707IFDEF: ICAP_CLIENT
6708COMMENT: on|off
26cc52cb 6709LOC: Adaptation::Icap::TheConfig.onoff
5473c134 6710DEFAULT: off
6711DOC_START
53e738c6 6712 If you want to enable the ICAP module support, set this to on.
5473c134 6713DOC_END
6714
6715NAME: icap_connect_timeout
6716TYPE: time_t
6717DEFAULT: none
26cc52cb 6718LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
5473c134 6719IFDEF: ICAP_CLIENT
6720DOC_START
6721 This parameter specifies how long to wait for the TCP connect to
6722 the requested ICAP server to complete before giving up and either
6723 terminating the HTTP transaction or bypassing the failure.
6724
6725 The default for optional services is peer_connect_timeout.
6726 The default for essential services is connect_timeout.
6727 If this option is explicitly set, its value applies to all services.
6728DOC_END
6729
6730NAME: icap_io_timeout
6731COMMENT: time-units
6732TYPE: time_t
6733DEFAULT: none
26cc52cb 6734LOC: Adaptation::Icap::TheConfig.io_timeout_raw
5473c134 6735IFDEF: ICAP_CLIENT
6736DOC_START
6737 This parameter specifies how long to wait for an I/O activity on
6738 an established, active ICAP connection before giving up and
6739 either terminating the HTTP transaction or bypassing the
6740 failure.
6741
6742 The default is read_timeout.
6743DOC_END
6744
6745NAME: icap_service_failure_limit
8277060a
CT
6746COMMENT: limit [in memory-depth time-units]
6747TYPE: icap_service_failure_limit
5473c134 6748IFDEF: ICAP_CLIENT
8277060a 6749LOC: Adaptation::Icap::TheConfig
5473c134 6750DEFAULT: 10
6751DOC_START
6752 The limit specifies the number of failures that Squid tolerates
6753 when establishing a new TCP connection with an ICAP service. If
6754 the number of failures exceeds the limit, the ICAP service is
6755 not used for new ICAP requests until it is time to refresh its
8277060a 6756 OPTIONS.
5473c134 6757
6758 A negative value disables the limit. Without the limit, an ICAP
6759 service will not be considered down due to connectivity failures
6760 between ICAP OPTIONS requests.
8277060a
CT
6761
6762 Squid forgets ICAP service failures older than the specified
6763 value of memory-depth. The memory fading algorithm
6764 is approximate because Squid does not remember individual
6765 errors but groups them instead, splitting the option
6766 value into ten time slots of equal length.
6767
6768 When memory-depth is 0 and by default this option has no
6769 effect on service failure expiration.
6770
6771 Squid always forgets failures when updating service settings
6772 using an ICAP OPTIONS transaction, regardless of this option
6773 setting.
6774
6775 For example,
6776 # suspend service usage after 10 failures in 5 seconds:
6777 icap_service_failure_limit 10 in 5 seconds
cccac0a2 6778DOC_END
6779
5473c134 6780NAME: icap_service_revival_delay
cccac0a2 6781TYPE: int
5473c134 6782IFDEF: ICAP_CLIENT
26cc52cb 6783LOC: Adaptation::Icap::TheConfig.service_revival_delay
5473c134 6784DEFAULT: 180
cccac0a2 6785DOC_START
5473c134 6786 The delay specifies the number of seconds to wait after an ICAP
6787 OPTIONS request failure before requesting the options again. The
6788 failed ICAP service is considered "down" until fresh OPTIONS are
6789 fetched.
cccac0a2 6790
5473c134 6791 The actual delay cannot be smaller than the hardcoded minimum
6792 delay of 30 seconds.
cccac0a2 6793DOC_END
6794
5473c134 6795NAME: icap_preview_enable
cccac0a2 6796TYPE: onoff
5473c134 6797IFDEF: ICAP_CLIENT
6798COMMENT: on|off
26cc52cb 6799LOC: Adaptation::Icap::TheConfig.preview_enable
ac7a62f9 6800DEFAULT: on
cccac0a2 6801DOC_START
ac7a62f9 6802 The ICAP Preview feature allows the ICAP server to handle the
6803 HTTP message by looking only at the beginning of the message body
6804 or even without receiving the body at all. In some environments,
6805 previews greatly speedup ICAP processing.
6806
6807 During an ICAP OPTIONS transaction, the server may tell Squid what
6808 HTTP messages should be previewed and how big the preview should be.
6809 Squid will not use Preview if the server did not request one.
6810
6811 To disable ICAP Preview for all ICAP services, regardless of
6812 individual ICAP server OPTIONS responses, set this option to "off".
6813Example:
6814icap_preview_enable off
cccac0a2 6815DOC_END
6816
5473c134 6817NAME: icap_preview_size
6818TYPE: int
6819IFDEF: ICAP_CLIENT
26cc52cb 6820LOC: Adaptation::Icap::TheConfig.preview_size
5473c134 6821DEFAULT: -1
cccac0a2 6822DOC_START
53e738c6 6823 The default size of preview data to be sent to the ICAP server.
6824 -1 means no preview. This value might be overwritten on a per server
6825 basis by OPTIONS requests.
cccac0a2 6826DOC_END
6827
83c51da9
CT
6828NAME: icap_206_enable
6829TYPE: onoff
6830IFDEF: ICAP_CLIENT
6831COMMENT: on|off
6832LOC: Adaptation::Icap::TheConfig.allow206_enable
6833DEFAULT: on
6834DOC_START
6835 206 (Partial Content) responses is an ICAP extension that allows the
6836 ICAP agents to optionally combine adapted and original HTTP message
6837 content. The decision to combine is postponed until the end of the
6838 ICAP response. Squid supports Partial Content extension by default.
6839
6840 Activation of the Partial Content extension is negotiated with each
6841 ICAP service during OPTIONS exchange. Most ICAP servers should handle
6842 negotation correctly even if they do not support the extension, but
6843 some might fail. To disable Partial Content support for all ICAP
6844 services and to avoid any negotiation, set this option to "off".
6845
6846 Example:
6847 icap_206_enable off
6848DOC_END
6849
5473c134 6850NAME: icap_default_options_ttl
6851TYPE: int
6852IFDEF: ICAP_CLIENT
26cc52cb 6853LOC: Adaptation::Icap::TheConfig.default_options_ttl
5473c134 6854DEFAULT: 60
cccac0a2 6855DOC_START
53e738c6 6856 The default TTL value for ICAP OPTIONS responses that don't have
5473c134 6857 an Options-TTL header.
cccac0a2 6858DOC_END
6859
5473c134 6860NAME: icap_persistent_connections
6861TYPE: onoff
6862IFDEF: ICAP_CLIENT
6863COMMENT: on|off
26cc52cb 6864LOC: Adaptation::Icap::TheConfig.reuse_connections
5473c134 6865DEFAULT: on
cccac0a2 6866DOC_START
5473c134 6867 Whether or not Squid should use persistent connections to
6868 an ICAP server.
cccac0a2 6869DOC_END
6870
22fff3bf 6871NAME: adaptation_send_client_ip icap_send_client_ip
5473c134 6872TYPE: onoff
22fff3bf 6873IFDEF: USE_ADAPTATION
5473c134 6874COMMENT: on|off
22fff3bf 6875LOC: Adaptation::Config::send_client_ip
5473c134 6876DEFAULT: off
cccac0a2 6877DOC_START
ea3ae478
AR
6878 If enabled, Squid shares HTTP client IP information with adaptation
6879 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests.
6880 For eCAP, Squid sets the libecap::metaClientIp transaction option.
6881
6882 See also: adaptation_uses_indirect_client
cccac0a2 6883DOC_END
6884
22fff3bf 6885NAME: adaptation_send_username icap_send_client_username
5473c134 6886TYPE: onoff
22fff3bf 6887IFDEF: USE_ADAPTATION
5473c134 6888COMMENT: on|off
22fff3bf 6889LOC: Adaptation::Config::send_username
5473c134 6890DEFAULT: off
cccac0a2 6891DOC_START
5473c134 6892 This sends authenticated HTTP client username (if available) to
22fff3bf
AR
6893 the adaptation service.
6894
6895 For ICAP, the username value is encoded based on the
5473c134 6896 icap_client_username_encode option and is sent using the header
6897 specified by the icap_client_username_header option.
cccac0a2 6898DOC_END
6899
5473c134 6900NAME: icap_client_username_header
cccac0a2 6901TYPE: string
5473c134 6902IFDEF: ICAP_CLIENT
26cc52cb 6903LOC: Adaptation::Icap::TheConfig.client_username_header
5473c134 6904DEFAULT: X-Client-Username
cccac0a2 6905DOC_START
db49f682 6906 ICAP request header name to use for adaptation_send_username.
cccac0a2 6907DOC_END
6908
5473c134 6909NAME: icap_client_username_encode
cccac0a2 6910TYPE: onoff
5473c134 6911IFDEF: ICAP_CLIENT
6912COMMENT: on|off
26cc52cb 6913LOC: Adaptation::Icap::TheConfig.client_username_encode
5473c134 6914DEFAULT: off
cccac0a2 6915DOC_START
5473c134 6916 Whether to base64 encode the authenticated client username.
cccac0a2 6917DOC_END
6918
5473c134 6919NAME: icap_service
6920TYPE: icap_service_type
6921IFDEF: ICAP_CLIENT
26cc52cb 6922LOC: Adaptation::Icap::TheConfig
5473c134 6923DEFAULT: none
cccac0a2 6924DOC_START
a22e6cd3 6925 Defines a single ICAP service using the following format:
cccac0a2 6926
c25c2836 6927 icap_service id vectoring_point uri [option ...]
7d90757b 6928
c25c2836
CT
6929 id: ID
6930 an opaque identifier or name which is used to direct traffic to
6931 this specific service. Must be unique among all adaptation
6932 services in squid.conf.
a22e6cd3
AR
6933
6934 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
f3db09e2 6935 This specifies at which point of transaction processing the
6936 ICAP service should be activated. *_postcache vectoring points
6937 are not yet supported.
a22e6cd3 6938
c25c2836 6939 uri: icap://servername:port/servicepath
a22e6cd3
AR
6940 ICAP server and service location.
6941
6942 ICAP does not allow a single service to handle both REQMOD and RESPMOD
6943 transactions. Squid does not enforce that requirement. You can specify
6944 services with the same service_url and different vectoring_points. You
6945 can even specify multiple identical services as long as their
6946 service_names differ.
6947
6948
6949 Service options are separated by white space. ICAP services support
6950 the following name=value options:
6951
6952 bypass=on|off|1|0
6953 If set to 'on' or '1', the ICAP service is treated as
6954 optional. If the service cannot be reached or malfunctions,
6955 Squid will try to ignore any errors and process the message as
6956 if the service was not enabled. No all ICAP errors can be
6957 bypassed. If set to 0, the ICAP service is treated as
6958 essential and all ICAP errors will result in an error page
6959 returned to the HTTP client.
6960
6961 Bypass is off by default: services are treated as essential.
6962
6963 routing=on|off|1|0
6964 If set to 'on' or '1', the ICAP service is allowed to
6965 dynamically change the current message adaptation plan by
6966 returning a chain of services to be used next. The services
6967 are specified using the X-Next-Services ICAP response header
6968 value, formatted as a comma-separated list of service names.
e2851fe7
AR
6969 Each named service should be configured in squid.conf. Other
6970 services are ignored. An empty X-Next-Services value results
6971 in an empty plan which ends the current adaptation.
6972
6973 Dynamic adaptation plan may cross or cover multiple supported
6974 vectoring points in their natural processing order.
a22e6cd3
AR
6975
6976 Routing is not allowed by default: the ICAP X-Next-Services
6977 response header is ignored.
6978
e6713f4e
AJ
6979 ipv6=on|off
6980 Only has effect on split-stack systems. The default on those systems
6981 is to use IPv4-only connections. When set to 'on' this option will
6982 make Squid use IPv6-only connections to contact this ICAP service.
6983
2dba5b8e
CT
6984 on-overload=block|bypass|wait|force
6985 If the service Max-Connections limit has been reached, do
6986 one of the following for each new ICAP transaction:
6987 * block: send an HTTP error response to the client
6988 * bypass: ignore the "over-connected" ICAP service
6989 * wait: wait (in a FIFO queue) for an ICAP connection slot
6990 * force: proceed, ignoring the Max-Connections limit
6991
6992 In SMP mode with N workers, each worker assumes the service
6993 connection limit is Max-Connections/N, even though not all
6994 workers may use a given service.
6995
6996 The default value is "bypass" if service is bypassable,
6997 otherwise it is set to "wait".
6998
6999
7000 max-conn=number
7001 Use the given number as the Max-Connections limit, regardless
7002 of the Max-Connections value given by the service, if any.
7003
a22e6cd3
AR
7004 Older icap_service format without optional named parameters is
7005 deprecated but supported for backward compatibility.
5473c134 7006
5473c134 7007Example:
c25c2836
CT
7008icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0
7009icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on
cccac0a2 7010DOC_END
7011
5473c134 7012NAME: icap_class
7013TYPE: icap_class_type
7014IFDEF: ICAP_CLIENT
21a26d31 7015LOC: none
5473c134 7016DEFAULT: none
cccac0a2 7017DOC_START
a22e6cd3 7018 This deprecated option was documented to define an ICAP service
62c7f90e
AR
7019 chain, even though it actually defined a set of similar, redundant
7020 services, and the chains were not supported.
5473c134 7021
62c7f90e 7022 To define a set of redundant services, please use the
a22e6cd3
AR
7023 adaptation_service_set directive. For service chains, use
7024 adaptation_service_chain.
cccac0a2 7025DOC_END
7026
5473c134 7027NAME: icap_access
7028TYPE: icap_access_type
7029IFDEF: ICAP_CLIENT
21a26d31 7030LOC: none
cccac0a2 7031DEFAULT: none
cccac0a2 7032DOC_START
a22e6cd3 7033 This option is deprecated. Please use adaptation_access, which
62c7f90e
AR
7034 has the same ICAP functionality, but comes with better
7035 documentation, and eCAP support.
cccac0a2 7036DOC_END
7037
57afc994
AR
7038COMMENT_START
7039 eCAP OPTIONS
7040 -----------------------------------------------------------------------------
7041COMMENT_END
7042
21a26d31
AR
7043NAME: ecap_enable
7044TYPE: onoff
7045IFDEF: USE_ECAP
7046COMMENT: on|off
574b508c 7047LOC: Adaptation::Ecap::TheConfig.onoff
21a26d31
AR
7048DEFAULT: off
7049DOC_START
7050 Controls whether eCAP support is enabled.
7051DOC_END
7052
7053NAME: ecap_service
7054TYPE: ecap_service_type
7055IFDEF: USE_ECAP
574b508c 7056LOC: Adaptation::Ecap::TheConfig
21a26d31
AR
7057DEFAULT: none
7058DOC_START
7059 Defines a single eCAP service
7060
c25c2836 7061 ecap_service id vectoring_point uri [option ...]
21a26d31 7062
c25c2836
CT
7063 id: ID
7064 an opaque identifier or name which is used to direct traffic to
7065 this specific service. Must be unique among all adaptation
7066 services in squid.conf.
7067
7068 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
21a26d31
AR
7069 This specifies at which point of transaction processing the
7070 eCAP service should be activated. *_postcache vectoring points
7071 are not yet supported.
c25c2836
CT
7072
7073 uri: ecap://vendor/service_name?custom&cgi=style&parameters=optional
7074 Squid uses the eCAP service URI to match this configuration
7075 line with one of the dynamically loaded services. Each loaded
7076 eCAP service must have a unique URI. Obtain the right URI from
7077 the service provider.
7078
7079
7080 Service options are separated by white space. eCAP services support
7081 the following name=value options:
7082
7083 bypass=on|off|1|0
7084 If set to 'on' or '1', the eCAP service is treated as optional.
7085 If the service cannot be reached or malfunctions, Squid will try
7086 to ignore any errors and process the message as if the service
21a26d31 7087 was not enabled. No all eCAP errors can be bypassed.
c25c2836
CT
7088 If set to 'off' or '0', the eCAP service is treated as essential
7089 and all eCAP errors will result in an error page returned to the
21a26d31 7090 HTTP client.
c25c2836
CT
7091
7092 Bypass is off by default: services are treated as essential.
7093
7094 routing=on|off|1|0
7095 If set to 'on' or '1', the eCAP service is allowed to
7096 dynamically change the current message adaptation plan by
7097 returning a chain of services to be used next.
7098
7099 Dynamic adaptation plan may cross or cover multiple supported
7100 vectoring points in their natural processing order.
7101
7102 Routing is not allowed by default.
7103
7104 Older ecap_service format without optional named parameters is
7105 deprecated but supported for backward compatibility.
7106
21a26d31
AR
7107
7108Example:
c25c2836
CT
7109ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off
7110ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on
21a26d31
AR
7111DOC_END
7112
57afc994
AR
7113NAME: loadable_modules
7114TYPE: wordlist
7115IFDEF: USE_LOADABLE_MODULES
7116LOC: Config.loadable_module_names
7117DEFAULT: none
7118DOC_START
7119 Instructs Squid to load the specified dynamic module(s) or activate
7120 preloaded module(s).
7121Example:
7122loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
7123DOC_END
7124
62c7f90e
AR
7125COMMENT_START
7126 MESSAGE ADAPTATION OPTIONS
7127 -----------------------------------------------------------------------------
7128COMMENT_END
7129
7130NAME: adaptation_service_set
7131TYPE: adaptation_service_set_type
7132IFDEF: USE_ADAPTATION
7133LOC: none
7134DEFAULT: none
7135DOC_START
7136
a22e6cd3
AR
7137 Configures an ordered set of similar, redundant services. This is
7138 useful when hot standby or backup adaptation servers are available.
7139
7140 adaptation_service_set set_name service_name1 service_name2 ...
7141
7142 The named services are used in the set declaration order. The first
7143 applicable adaptation service from the set is used first. The next
7144 applicable service is tried if and only if the transaction with the
7145 previous service fails and the message waiting to be adapted is still
7146 intact.
62c7f90e 7147
a22e6cd3
AR
7148 When adaptation starts, broken services are ignored as if they were
7149 not a part of the set. A broken service is a down optional service.
62c7f90e 7150
a22e6cd3
AR
7151 The services in a set must be attached to the same vectoring point
7152 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
7153
7154 If all services in a set are optional then adaptation failures are
7155 bypassable. If all services in the set are essential, then a
7156 transaction failure with one service may still be retried using
7157 another service from the set, but when all services fail, the master
7158 transaction fails as well.
7159
7160 A set may contain a mix of optional and essential services, but that
7161 is likely to lead to surprising results because broken services become
7162 ignored (see above), making previously bypassable failures fatal.
7163 Technically, it is the bypassability of the last failed service that
7164 matters.
7165
7166 See also: adaptation_access adaptation_service_chain
62c7f90e
AR
7167
7168Example:
7169adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
7170adaptation service_set svcLogger loggerLocal loggerRemote
7171DOC_END
7172
a22e6cd3
AR
7173NAME: adaptation_service_chain
7174TYPE: adaptation_service_chain_type
7175IFDEF: USE_ADAPTATION
7176LOC: none
7177DEFAULT: none
7178DOC_START
7179
7180 Configures a list of complementary services that will be applied
7181 one-by-one, forming an adaptation chain or pipeline. This is useful
7182 when Squid must perform different adaptations on the same message.
7183
7184 adaptation_service_chain chain_name service_name1 svc_name2 ...
7185
7186 The named services are used in the chain declaration order. The first
7187 applicable adaptation service from the chain is used first. The next
7188 applicable service is applied to the successful adaptation results of
7189 the previous service in the chain.
7190
7191 When adaptation starts, broken services are ignored as if they were
7192 not a part of the chain. A broken service is a down optional service.
7193
7194 Request satisfaction terminates the adaptation chain because Squid
7195 does not currently allow declaration of RESPMOD services at the
7196 "reqmod_precache" vectoring point (see icap_service or ecap_service).
7197
7198 The services in a chain must be attached to the same vectoring point
7199 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
7200
7201 A chain may contain a mix of optional and essential services. If an
7202 essential adaptation fails (or the failure cannot be bypassed for
7203 other reasons), the master transaction fails. Otherwise, the failure
7204 is bypassed as if the failed adaptation service was not in the chain.
7205
7206 See also: adaptation_access adaptation_service_set
7207
7208Example:
7209adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
7210DOC_END
7211
62c7f90e
AR
7212NAME: adaptation_access
7213TYPE: adaptation_access_type
7214IFDEF: USE_ADAPTATION
7215LOC: none
7216DEFAULT: none
7217DOC_START
7218 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
7219
7220 adaptation_access service_name allow|deny [!]aclname...
7221 adaptation_access set_name allow|deny [!]aclname...
7222
7223 At each supported vectoring point, the adaptation_access
7224 statements are processed in the order they appear in this
7225 configuration file. Statements pointing to the following services
7226 are ignored (i.e., skipped without checking their ACL):
7227
7228 - services serving different vectoring points
7229 - "broken-but-bypassable" services
7230 - "up" services configured to ignore such transactions
7231 (e.g., based on the ICAP Transfer-Ignore header).
7232
7233 When a set_name is used, all services in the set are checked
7234 using the same rules, to find the first applicable one. See
7235 adaptation_service_set for details.
7236
7237 If an access list is checked and there is a match, the
7238 processing stops: For an "allow" rule, the corresponding
7239 adaptation service is used for the transaction. For a "deny"
7240 rule, no adaptation service is activated.
7241
7242 It is currently not possible to apply more than one adaptation
7243 service at the same vectoring point to the same HTTP transaction.
7244
7245 See also: icap_service and ecap_service
7246
7247Example:
7248adaptation_access service_1 allow all
7249DOC_END
7250
a22e6cd3
AR
7251NAME: adaptation_service_iteration_limit
7252TYPE: int
7253IFDEF: USE_ADAPTATION
7254LOC: Adaptation::Config::service_iteration_limit
7255DEFAULT: 16
7256DOC_START
7257 Limits the number of iterations allowed when applying adaptation
7258 services to a message. If your longest adaptation set or chain
7259 may have more than 16 services, increase the limit beyond its
7260 default value of 16. If detecting infinite iteration loops sooner
7261 is critical, make the iteration limit match the actual number
7262 of services in your longest adaptation set or chain.
7263
7264 Infinite adaptation loops are most likely with routing services.
7265
7266 See also: icap_service routing=1
7267DOC_END
7268
3ff65596
AR
7269NAME: adaptation_masterx_shared_names
7270TYPE: string
7271IFDEF: USE_ADAPTATION
7272LOC: Adaptation::Config::masterx_shared_name
7273DEFAULT: none
7274DOC_START
7275 For each master transaction (i.e., the HTTP request and response
7276 sequence, including all related ICAP and eCAP exchanges), Squid
7277 maintains a table of metadata. The table entries are (name, value)
7278 pairs shared among eCAP and ICAP exchanges. The table is destroyed
7279 with the master transaction.
7280
7281 This option specifies the table entry names that Squid must accept
7282 from and forward to the adaptation transactions.
7283
7284 An ICAP REQMOD or RESPMOD transaction may set an entry in the
7285 shared table by returning an ICAP header field with a name
6666da11
AR
7286 specified in adaptation_masterx_shared_names.
7287
7288 An eCAP REQMOD or RESPMOD transaction may set an entry in the
7289 shared table by implementing the libecap::visitEachOption() API
7290 to provide an option with a name specified in
7291 adaptation_masterx_shared_names.
5038f9d8
AR
7292
7293 Squid will store and forward the set entry to subsequent adaptation
3ff65596
AR
7294 transactions within the same master transaction scope.
7295
7296 Only one shared entry name is supported at this time.
7297
7298Example:
7299# share authentication information among ICAP services
7300adaptation_masterx_shared_names X-Subscriber-ID
7301DOC_END
7302
71be37e0
CT
7303NAME: adaptation_meta
7304TYPE: adaptation_meta_type
7305IFDEF: USE_ADAPTATION
7306LOC: Adaptation::Config::metaHeaders
7307DEFAULT: none
7308DOC_START
7309 This option allows Squid administrator to add custom ICAP request
7310 headers or eCAP options to Squid ICAP requests or eCAP transactions.
7311 Use it to pass custom authentication tokens and other
7312 transaction-state related meta information to an ICAP/eCAP service.
7313
7314 The addition of a meta header is ACL-driven:
7315 adaptation_meta name value [!]aclname ...
7316
7317 Processing for a given header name stops after the first ACL list match.
7318 Thus, it is impossible to add two headers with the same name. If no ACL
7319 lists match for a given header name, no such header is added. For
7320 example:
7321
7322 # do not debug transactions except for those that need debugging
7323 adaptation_meta X-Debug 1 needs_debugging
7324
7325 # log all transactions except for those that must remain secret
7326 adaptation_meta X-Log 1 !keep_secret
7327
7328 # mark transactions from users in the "G 1" group
7329 adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1
7330
7331 The "value" parameter may be a regular squid.conf token or a "double
7332 quoted string". Within the quoted string, use backslash (\) to escape
7333 any character, which is currently only useful for escaping backslashes
7334 and double quotes. For example,
7335 "this string has one backslash (\\) and two \"quotes\""
7336DOC_END
7337
3ff65596
AR
7338NAME: icap_retry
7339TYPE: acl_access
7340IFDEF: ICAP_CLIENT
7341LOC: Adaptation::Icap::TheConfig.repeat
3ff65596
AR
7342DEFAULT_IF_NONE: deny all
7343DOC_START
7344 This ACL determines which retriable ICAP transactions are
7345 retried. Transactions that received a complete ICAP response
7346 and did not have to consume or produce HTTP bodies to receive
7347 that response are usually retriable.
7348
7349 icap_retry allow|deny [!]aclname ...
7350
7351 Squid automatically retries some ICAP I/O timeouts and errors
7352 due to persistent connection race conditions.
7353
7354 See also: icap_retry_limit
7355DOC_END
7356
7357NAME: icap_retry_limit
7358TYPE: int
7359IFDEF: ICAP_CLIENT
7360LOC: Adaptation::Icap::TheConfig.repeat_limit
7361DEFAULT: 0
7362DOC_START
7363 Limits the number of retries allowed. When set to zero (default),
7364 no retries are allowed.
7365
7366 Communication errors due to persistent connection race
7367 conditions are unavoidable, automatically retried, and do not
7368 count against this limit.
7369
7370 See also: icap_retry
7371DOC_END
7372
7373
5473c134 7374COMMENT_START
7375 DNS OPTIONS
7376 -----------------------------------------------------------------------------
7377COMMENT_END
7378
7379NAME: check_hostnames
cccac0a2 7380TYPE: onoff
cccac0a2 7381DEFAULT: off
5473c134 7382LOC: Config.onoff.check_hostnames
cccac0a2 7383DOC_START
5473c134 7384 For security and stability reasons Squid can check
7385 hostnames for Internet standard RFC compliance. If you want
7386 Squid to perform these checks turn this directive on.
cccac0a2 7387DOC_END
7388
5473c134 7389NAME: allow_underscore
cccac0a2 7390TYPE: onoff
cccac0a2 7391DEFAULT: on
5473c134 7392LOC: Config.onoff.allow_underscore
cccac0a2 7393DOC_START
5473c134 7394 Underscore characters is not strictly allowed in Internet hostnames
7395 but nevertheless used by many sites. Set this to off if you want
7396 Squid to be strict about the standard.
7397 This check is performed only when check_hostnames is set to on.
cccac0a2 7398DOC_END
7399
5473c134 7400NAME: cache_dns_program
cccac0a2 7401TYPE: string
f64091a7 7402IFDEF: USE_DNSHELPER
5473c134 7403DEFAULT: @DEFAULT_DNSSERVER@
7404LOC: Config.Program.dnsserver
cccac0a2 7405DOC_START
5473c134 7406 Specify the location of the executable for dnslookup process.
cccac0a2 7407DOC_END
7408
5473c134 7409NAME: dns_children
48d54e4d 7410TYPE: HelperChildConfig
f64091a7 7411IFDEF: USE_DNSHELPER
48d54e4d 7412DEFAULT: 32 startup=1 idle=1
5473c134 7413LOC: Config.dnsChildren
58850d15 7414DOC_START
48d54e4d
AJ
7415 The maximum number of processes spawn to service DNS name lookups.
7416 If you limit it too few Squid will have to wait for them to process
7417 a backlog of requests, slowing it down. If you allow too many they
7418 will use RAM and other system resources noticably.
7419 The maximum this may be safely set to is 32.
7420
7421 The startup= and idle= options allow some measure of skew in your
7422 tuning.
7423
7424 startup=
7425
7426 Sets a minimum of how many processes are to be spawned when Squid
7427 starts or reconfigures. When set to zero the first request will
7428 cause spawning of the first child process to handle it.
7429
7430 Starting too few will cause an initial slowdown in traffic as Squid
7431 attempts to simultaneously spawn enough processes to cope.
7432
7433 idle=
7434
7435 Sets a minimum of how many processes Squid is to try and keep available
7436 at all times. When traffic begins to rise above what the existing
7437 processes can handle this many more will be spawned up to the maximum
7438 configured. A minimum setting of 1 is required.
58850d15 7439DOC_END
7440
5473c134 7441NAME: dns_retransmit_interval
fd0f51c4 7442TYPE: time_msec
5473c134 7443DEFAULT: 5 seconds
7444LOC: Config.Timeout.idns_retransmit
f64091a7 7445IFDEF: !USE_DNSHELPER
cccac0a2 7446DOC_START
5473c134 7447 Initial retransmit interval for DNS queries. The interval is
7448 doubled each time all configured DNS servers have been tried.
cccac0a2 7449DOC_END
7450
5473c134 7451NAME: dns_timeout
fd0f51c4 7452TYPE: time_msec
a541c34e 7453DEFAULT: 30 seconds
5473c134 7454LOC: Config.Timeout.idns_query
f64091a7 7455IFDEF: !USE_DNSHELPER
cccac0a2 7456DOC_START
5473c134 7457 DNS Query timeout. If no response is received to a DNS query
7458 within this time all DNS servers for the queried domain
7459 are assumed to be unavailable.
cccac0a2 7460DOC_END
7461
e210930b
AJ
7462NAME: dns_packet_max
7463TYPE: b_ssize_t
7464DEFAULT: none
7465LOC: Config.dns.packet_max
f64091a7 7466IFDEF: !USE_DNSHELPER
e210930b
AJ
7467DOC_START
7468 Maximum number of bytes packet size to advertise via EDNS.
7469 Set to "none" to disable EDNS large packet support.
7470
7471 For legacy reasons DNS UDP replies will default to 512 bytes which
7472 is too small for many responses. EDNS provides a means for Squid to
7473 negotiate receiving larger responses back immediately without having
7474 to failover with repeat requests. Responses larger than this limit
7475 will retain the old behaviour of failover to TCP DNS.
7476
7477 Squid has no real fixed limit internally, but allowing packet sizes
7478 over 1500 bytes requires network jumbogram support and is usually not
7479 necessary.
7480
7481 WARNING: The RFC also indicates that some older resolvers will reply
7482 with failure of the whole request if the extension is added. Some
7483 resolvers have already been identified which will reply with mangled
7484 EDNS response on occasion. Usually in response to many-KB jumbogram
7485 sizes being advertised by Squid.
7486 Squid will currently treat these both as an unable-to-resolve domain
7487 even if it would be resolvable without EDNS.
7488DOC_END
7489
5473c134 7490NAME: dns_defnames
7491COMMENT: on|off
cccac0a2 7492TYPE: onoff
cccac0a2 7493DEFAULT: off
5473c134 7494LOC: Config.onoff.res_defnames
cccac0a2 7495DOC_START
5473c134 7496 Normally the RES_DEFNAMES resolver option is disabled
7497 (see res_init(3)). This prevents caches in a hierarchy
7498 from interpreting single-component hostnames locally. To allow
7499 Squid to handle single-component names, enable this option.
cccac0a2 7500DOC_END
7501
5473c134 7502NAME: dns_nameservers
7503TYPE: wordlist
7504DEFAULT: none
7505LOC: Config.dns_nameservers
cccac0a2 7506DOC_START
5473c134 7507 Use this if you want to specify a list of DNS name servers
7508 (IP addresses) to use instead of those given in your
7509 /etc/resolv.conf file.
7510 On Windows platforms, if no value is specified here or in
7511 the /etc/resolv.conf file, the list of DNS name servers are
7512 taken from the Windows registry, both static and dynamic DHCP
7513 configurations are supported.
cccac0a2 7514
5473c134 7515 Example: dns_nameservers 10.0.0.1 192.172.0.4
cccac0a2 7516DOC_END
7517
5473c134 7518NAME: hosts_file
cccac0a2 7519TYPE: string
5473c134 7520DEFAULT: @DEFAULT_HOSTS@
7521LOC: Config.etcHostsPath
cccac0a2 7522DOC_START
5473c134 7523 Location of the host-local IP name-address associations
7524 database. Most Operating Systems have such a file on different
7525 default locations:
7526 - Un*X & Linux: /etc/hosts
7527 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
7528 (%SystemRoot% value install default is c:\winnt)
7529 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
7530 (%SystemRoot% value install default is c:\windows)
7531 - Windows 9x/Me: %windir%\hosts
7532 (%windir% value is usually c:\windows)
7533 - Cygwin: /etc/hosts
cccac0a2 7534
5473c134 7535 The file contains newline-separated definitions, in the
7536 form ip_address_in_dotted_form name [name ...] names are
7537 whitespace-separated. Lines beginning with an hash (#)
7538 character are comments.
cccac0a2 7539
5473c134 7540 The file is checked at startup and upon configuration.
7541 If set to 'none', it won't be checked.
7542 If append_domain is used, that domain will be added to
7543 domain-local (i.e. not containing any dot character) host
7544 definitions.
cccac0a2 7545DOC_END
7546
5473c134 7547NAME: append_domain
7548TYPE: string
7549LOC: Config.appendDomain
7550DEFAULT: none
6a2f3fcf 7551DOC_START
5473c134 7552 Appends local domain name to hostnames without any dots in
7553 them. append_domain must begin with a period.
7554
7555 Be warned there are now Internet names with no dots in
7556 them using only top-domain names, so setting this may
7557 cause some Internet sites to become unavailable.
7558
7559Example:
7560 append_domain .yourdomain.com
6a2f3fcf 7561DOC_END
7562
5473c134 7563NAME: ignore_unknown_nameservers
7564TYPE: onoff
7565LOC: Config.onoff.ignore_unknown_nameservers
df6fd596 7566DEFAULT: on
f64091a7 7567IFDEF: !USE_DNSHELPER
df6fd596 7568DOC_START
5473c134 7569 By default Squid checks that DNS responses are received
7570 from the same IP addresses they are sent to. If they
7571 don't match, Squid ignores the response and writes a warning
7572 message to cache.log. You can allow responses from unknown
7573 nameservers by setting this option to 'off'.
df6fd596 7574DOC_END
7575
5a0da9ec
AJ
7576NAME: dns_v4_first
7577TYPE: onoff
7578DEFAULT: off
7579LOC: Config.dns.v4_first
f64091a7 7580IFDEF: !USE_DNSHELPER
5a0da9ec
AJ
7581DOC_START
7582 With the IPv6 Internet being as fast or faster than IPv4 Internet
7583 for most networks Squid prefers to contact websites over IPv6.
7584
7585 This option reverses the order of preference to make Squid contact
7586 dual-stack websites over IPv4 first. Squid will still perform both
7587 IPv6 and IPv4 DNS lookups before connecting.
7588
7589 WARNING:
7590 This option will restrict the situations under which IPv6
7591 connectivity is used (and tested). Hiding network problems
7592 which would otherwise be detected and warned about.
7593DOC_END
7594
6bc15a4f 7595NAME: ipcache_size
7596COMMENT: (number of entries)
7597TYPE: int
7598DEFAULT: 1024
7599LOC: Config.ipcache.size
7600DOC_NONE
7601
7602NAME: ipcache_low
7603COMMENT: (percent)
7604TYPE: int
7605DEFAULT: 90
7606LOC: Config.ipcache.low
7607DOC_NONE
7608
7609NAME: ipcache_high
7610COMMENT: (percent)
7611TYPE: int
7612DEFAULT: 95
7613LOC: Config.ipcache.high
7614DOC_START
7615 The size, low-, and high-water marks for the IP cache.
7616DOC_END
7617
7618NAME: fqdncache_size
7619COMMENT: (number of entries)
7620TYPE: int
7621DEFAULT: 1024
7622LOC: Config.fqdncache.size
7623DOC_START
7624 Maximum number of FQDN cache entries.
7625DOC_END
7626
a58ff010 7627COMMENT_START
5473c134 7628 MISCELLANEOUS
a58ff010 7629 -----------------------------------------------------------------------------
7630COMMENT_END
7631
5473c134 7632NAME: memory_pools
a58ff010 7633COMMENT: on|off
5473c134 7634TYPE: onoff
7635DEFAULT: on
7636LOC: Config.onoff.mem_pools
a58ff010 7637DOC_START
5473c134 7638 If set, Squid will keep pools of allocated (but unused) memory
7639 available for future use. If memory is a premium on your
7640 system and you believe your malloc library outperforms Squid
7641 routines, disable this.
a58ff010 7642DOC_END
7643
5473c134 7644NAME: memory_pools_limit
7645COMMENT: (bytes)
70be1349 7646TYPE: b_int64_t
5473c134 7647DEFAULT: 5 MB
7648LOC: Config.MemPools.limit
ec1245f8 7649DOC_START
5473c134 7650 Used only with memory_pools on:
7651 memory_pools_limit 50 MB
ec1245f8 7652
5473c134 7653 If set to a non-zero value, Squid will keep at most the specified
7654 limit of allocated (but unused) memory in memory pools. All free()
7655 requests that exceed this limit will be handled by your malloc
7656 library. Squid does not pre-allocate any memory, just safe-keeps
7657 objects that otherwise would be free()d. Thus, it is safe to set
7658 memory_pools_limit to a reasonably high value even if your
7659 configuration will use less memory.
ec1245f8 7660
89646bd7 7661 If set to none, Squid will keep all memory it can. That is, there
5473c134 7662 will be no limit on the total amount of memory used for safe-keeping.
ec1245f8 7663
5473c134 7664 To disable memory allocation optimization, do not set
70be1349 7665 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
5473c134 7666
7667 An overhead for maintaining memory pools is not taken into account
7668 when the limit is checked. This overhead is close to four bytes per
7669 object kept. However, pools may actually _save_ memory because of
7670 reduced memory thrashing in your malloc library.
ec1245f8 7671DOC_END
7672
5473c134 7673NAME: forwarded_for
67c06f0d
AJ
7674COMMENT: on|off|transparent|truncate|delete
7675TYPE: string
5473c134 7676DEFAULT: on
7677LOC: opt_forwarded_for
5f8252d2 7678DOC_START
67c06f0d
AJ
7679 If set to "on", Squid will append your client's IP address
7680 in the HTTP requests it forwards. By default it looks like:
5f8252d2 7681
5473c134 7682 X-Forwarded-For: 192.1.2.3
7683
67c06f0d 7684 If set to "off", it will appear as
5473c134 7685
7686 X-Forwarded-For: unknown
67c06f0d
AJ
7687
7688 If set to "transparent", Squid will not alter the
7689 X-Forwarded-For header in any way.
7690
7691 If set to "delete", Squid will delete the entire
7692 X-Forwarded-For header.
7693
7694 If set to "truncate", Squid will remove all existing
dd68402f 7695 X-Forwarded-For entries, and place the client IP as the sole entry.
5f8252d2 7696DOC_END
7697
5473c134 7698NAME: cachemgr_passwd
7699TYPE: cachemgrpasswd
7700DEFAULT: none
7701LOC: Config.passwd_list
5f8252d2 7702DOC_START
5473c134 7703 Specify passwords for cachemgr operations.
5f8252d2 7704
5473c134 7705 Usage: cachemgr_passwd password action action ...
7706
7707 Some valid actions are (see cache manager menu for a full list):
7708 5min
7709 60min
7710 asndb
7711 authenticator
7712 cbdata
7713 client_list
7714 comm_incoming
7715 config *
7716 counters
7717 delay
7718 digest_stats
7719 dns
7720 events
7721 filedescriptors
7722 fqdncache
7723 histograms
7724 http_headers
7725 info
7726 io
7727 ipcache
7728 mem
7729 menu
7730 netdb
7731 non_peers
7732 objects
7733 offline_toggle *
7734 pconn
7735 peer_select
b360c477 7736 reconfigure *
5473c134 7737 redirector
7738 refresh
7739 server_list
7740 shutdown *
7741 store_digest
7742 storedir
7743 utilization
7744 via_headers
7745 vm_objects
7746
7747 * Indicates actions which will not be performed without a
7748 valid password, others can be performed if not listed here.
7749
7750 To disable an action, set the password to "disable".
7751 To allow performing an action without a password, set the
7752 password to "none".
7753
7754 Use the keyword "all" to set the same password for all actions.
7755
7756Example:
7757 cachemgr_passwd secret shutdown
7758 cachemgr_passwd lesssssssecret info stats/objects
7759 cachemgr_passwd disable all
5f8252d2 7760DOC_END
7761
5473c134 7762NAME: client_db
a58ff010 7763COMMENT: on|off
5473c134 7764TYPE: onoff
7765DEFAULT: on
7766LOC: Config.onoff.client_db
a58ff010 7767DOC_START
5473c134 7768 If you want to disable collecting per-client statistics,
7769 turn off client_db here.
a58ff010 7770DOC_END
7771
5473c134 7772NAME: refresh_all_ims
7773COMMENT: on|off
7774TYPE: onoff
7775DEFAULT: off
7776LOC: Config.onoff.refresh_all_ims
a58ff010 7777DOC_START
5473c134 7778 When you enable this option, squid will always check
7779 the origin server for an update when a client sends an
7780 If-Modified-Since request. Many browsers use IMS
7781 requests when the user requests a reload, and this
7782 ensures those clients receive the latest version.
a58ff010 7783
5473c134 7784 By default (off), squid may return a Not Modified response
7785 based on the age of the cached version.
78e8cfc4 7786DOC_END
7787
5473c134 7788NAME: reload_into_ims
626096be 7789IFDEF: USE_HTTP_VIOLATIONS
12b91c99 7790COMMENT: on|off
5473c134 7791TYPE: onoff
7792DEFAULT: off
7793LOC: Config.onoff.reload_into_ims
12b91c99 7794DOC_START
5473c134 7795 When you enable this option, client no-cache or ``reload''
7796 requests will be changed to If-Modified-Since requests.
7797 Doing this VIOLATES the HTTP standard. Enabling this
7798 feature could make you liable for problems which it
7799 causes.
7800
7801 see also refresh_pattern for a more selective approach.
12b91c99 7802DOC_END
7803
31ef19cd 7804NAME: connect_retries
5473c134 7805TYPE: int
31ef19cd
AJ
7806LOC: Config.connect_retries
7807DEFAULT: 0
a58ff010 7808DOC_START
aed188fd
AJ
7809 This sets the maximum number of connection attempts made for each
7810 TCP connection. The connect_retries attempts must all still
7811 complete within the connection timeout period.
31ef19cd
AJ
7812
7813 The default is not to re-try if the first connection attempt fails.
7814 The (not recommended) maximum is 10 tries.
5473c134 7815
31ef19cd
AJ
7816 A warning message will be generated if it is set to a too-high
7817 value and the configured value will be over-ridden.
5473c134 7818
31ef19cd
AJ
7819 Note: These re-tries are in addition to forward_max_tries
7820 which limit how many different addresses may be tried to find
7821 a useful server.
a58ff010 7822DOC_END
7823
5473c134 7824NAME: retry_on_error
a58ff010 7825TYPE: onoff
5473c134 7826LOC: Config.retry.onerror
a58ff010 7827DEFAULT: off
7828DOC_START
aea8548b
AJ
7829 If set to ON Squid will automatically retry requests when
7830 receiving an error response with status 403 (Forbidden),
7831 500 (Internal Error), 501 or 503 (Service not available).
7832 Status 502 and 504 (Gateway errors) are always retried.
7833
7834 This is mainly useful if you are in a complex cache hierarchy to
7835 work around access control errors.
7836
7837 NOTE: This retry will attempt to find another working destination.
7838 Which is different from the server which just failed.
5f8252d2 7839DOC_END
7840
5473c134 7841NAME: as_whois_server
5f8252d2 7842TYPE: string
5473c134 7843LOC: Config.as_whois_server
7844DEFAULT: whois.ra.net
5f8252d2 7845DOC_START
5473c134 7846 WHOIS server to query for AS numbers. NOTE: AS numbers are
7847 queried only when Squid starts up, not for every request.
5f8252d2 7848DOC_END
7849
5473c134 7850NAME: offline_mode
5f8252d2 7851TYPE: onoff
5473c134 7852LOC: Config.onoff.offline
5f8252d2 7853DEFAULT: off
7854DOC_START
5473c134 7855 Enable this option and Squid will never try to validate cached
7856 objects.
a58ff010 7857DOC_END
7858
5473c134 7859NAME: uri_whitespace
7860TYPE: uri_whitespace
7861LOC: Config.uri_whitespace
7862DEFAULT: strip
a58ff010 7863DOC_START
5473c134 7864 What to do with requests that have whitespace characters in the
7865 URI. Options:
a58ff010 7866
5473c134 7867 strip: The whitespace characters are stripped out of the URL.
7868 This is the behavior recommended by RFC2396.
7869 deny: The request is denied. The user receives an "Invalid
7870 Request" message.
7871 allow: The request is allowed and the URI is not changed. The
7872 whitespace characters remain in the URI. Note the
7873 whitespace is passed to redirector processes if they
7874 are in use.
7875 encode: The request is allowed and the whitespace characters are
7876 encoded according to RFC1738. This could be considered
7877 a violation of the HTTP/1.1
7878 RFC because proxies are not allowed to rewrite URI's.
7879 chop: The request is allowed and the URI is chopped at the
7880 first whitespace. This might also be considered a
7881 violation.
7882DOC_END
a58ff010 7883
5473c134 7884NAME: chroot
7885TYPE: string
7886LOC: Config.chroot_dir
a58ff010 7887DEFAULT: none
7888DOC_START
9f37c18a 7889 Specifies a directory where Squid should do a chroot() while
2d89f399
HN
7890 initializing. This also causes Squid to fully drop root
7891 privileges after initializing. This means, for example, if you
7892 use a HTTP port less than 1024 and try to reconfigure, you may
7893 get an error saying that Squid can not open the port.
5473c134 7894DOC_END
a58ff010 7895
5473c134 7896NAME: balance_on_multiple_ip
7897TYPE: onoff
7898LOC: Config.onoff.balance_on_multiple_ip
cc192b50 7899DEFAULT: off
5473c134 7900DOC_START
cc192b50 7901 Modern IP resolvers in squid sort lookup results by preferred access.
7902 By default squid will use these IP in order and only rotates to
7903 the next listed when the most preffered fails.
7904
5473c134 7905 Some load balancing servers based on round robin DNS have been
7906 found not to preserve user session state across requests
7907 to different IP addresses.
a58ff010 7908
cc192b50 7909 Enabling this directive Squid rotates IP's per request.
a58ff010 7910DOC_END
7911
5473c134 7912NAME: pipeline_prefetch
7913TYPE: onoff
7914LOC: Config.onoff.pipeline_prefetch
7915DEFAULT: off
a58ff010 7916DOC_START
5473c134 7917 To boost the performance of pipelined requests to closer
7918 match that of a non-proxied environment Squid can try to fetch
7919 up to two requests in parallel from a pipeline.
a58ff010 7920
5473c134 7921 Defaults to off for bandwidth management and access logging
7922 reasons.
a0e23afd
AJ
7923
7924 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication.
5473c134 7925DOC_END
a58ff010 7926
5473c134 7927NAME: high_response_time_warning
7928TYPE: int
7929COMMENT: (msec)
7930LOC: Config.warnings.high_rptm
7931DEFAULT: 0
7932DOC_START
7933 If the one-minute median response time exceeds this value,
7934 Squid prints a WARNING with debug level 0 to get the
7935 administrators attention. The value is in milliseconds.
a58ff010 7936DOC_END
7937
5473c134 7938NAME: high_page_fault_warning
7939TYPE: int
7940LOC: Config.warnings.high_pf
7941DEFAULT: 0
cc9f92d4 7942DOC_START
5473c134 7943 If the one-minute average page fault rate exceeds this
7944 value, Squid prints a WARNING with debug level 0 to get
7945 the administrators attention. The value is in page faults
7946 per second.
7947DOC_END
cc9f92d4 7948
5473c134 7949NAME: high_memory_warning
7950TYPE: b_size_t
7951LOC: Config.warnings.high_memory
904971da 7952DEFAULT: 0 KB
5473c134 7953DOC_START
7954 If the memory usage (as determined by mallinfo) exceeds
904971da 7955 this amount, Squid prints a WARNING with debug level 0 to get
5473c134 7956 the administrators attention.
7957DOC_END
cc9f92d4 7958
5473c134 7959NAME: sleep_after_fork
7960COMMENT: (microseconds)
7961TYPE: int
7962LOC: Config.sleep_after_fork
7963DEFAULT: 0
7964DOC_START
7965 When this is set to a non-zero value, the main Squid process
7966 sleeps the specified number of microseconds after a fork()
7967 system call. This sleep may help the situation where your
7968 system reports fork() failures due to lack of (virtual)
7969 memory. Note, however, if you have a lot of child
7970 processes, these sleep delays will add up and your
7971 Squid will not service requests for some amount of time
7972 until all the child processes have been started.
7973 On Windows value less then 1000 (1 milliseconds) are
7974 rounded to 1000.
cc9f92d4 7975DOC_END
7976
b6696974 7977NAME: windows_ipaddrchangemonitor
6b0516c6 7978IFDEF: _SQUID_MSWIN_
b6696974
GS
7979COMMENT: on|off
7980TYPE: onoff
7981DEFAULT: on
7982LOC: Config.onoff.WIN32_IpAddrChangeMonitor
7983DOC_START
7984 On Windows Squid by default will monitor IP address changes and will
7985 reconfigure itself after any detected event. This is very useful for
7986 proxies connected to internet with dial-up interfaces.
7987 In some cases (a Proxy server acting as VPN gateway is one) it could be
7988 desiderable to disable this behaviour setting this to 'off'.
7989 Note: after changing this, Squid service must be restarted.
7990DOC_END
7991
a98c2da5
AJ
7992NAME: eui_lookup
7993TYPE: onoff
7994IFDEF: USE_SQUID_EUI
7995DEFAULT: on
7996LOC: Eui::TheConfig.euiLookup
7997DOC_START
7998 Whether to lookup the EUI or MAC address of a connected client.
7999DOC_END
8000
f3f0f563
AJ
8001NAME: max_filedescriptors max_filedesc
8002TYPE: int
8003DEFAULT: 0
8004LOC: Config.max_filedescriptors
8005DOC_START
8006 The maximum number of filedescriptors supported.
8007
8008 The default "0" means Squid inherits the current ulimit setting.
8009
8010 Note: Changing this requires a restart of Squid. Also
8011 not all comm loops supports large values.
8012DOC_END
8013
13aeac35 8014NAME: workers
007d775d 8015TYPE: int
13aeac35 8016LOC: Config.workers
007d775d
AR
8017DEFAULT: 1
8018DOC_START
13aeac35 8019 Number of main Squid processes or "workers" to fork and maintain.
007d775d
AR
8020 0: "no daemon" mode, like running "squid -N ..."
8021 1: "no SMP" mode, start one main Squid process daemon (default)
13aeac35
AR
8022 N: start N main Squid process daemons (i.e., SMP mode)
8023
b87f6632
AR
8024 In SMP mode, each worker does nearly all what a single Squid daemon
8025 does (e.g., listen on http_port and forward HTTP requests).
007d775d
AR
8026DOC_END
8027
96c2bb61
AR
8028NAME: cpu_affinity_map
8029TYPE: CpuAffinityMap
8030LOC: Config.cpuAffinityMap
8031DEFAULT: none
8032DOC_START
8033 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
8034
8035 Sets 1:1 mapping between Squid processes and CPU cores. For example,
8036
8037 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
8038
8039 affects processes 1 through 4 only and places them on the first
8040 four even cores, starting with core #1.
8041
8042 CPU cores are numbered starting from 1. Requires support for
8043 sched_getaffinity(2) and sched_setaffinity(2) system calls.
8044
8045 Multiple cpu_affinity_map options are merged.
8046
8047 See also: workers
8048DOC_END
8049
cccac0a2 8050EOF