2 # SQUID Web Proxy Cache http://www.squid-cache.org/
3 # ----------------------------------------------------------
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.
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.
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.
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.
31 ----------------------------
33 This is the default Squid configuration file. You may wish
34 to look at the Squid home page (http://www.squid-cache.org/)
35 for the FAQ and other documentation.
37 The default Squid config file shows what the defaults for
38 various options happen to be. If you don't need to change the
39 default, you shouldn't uncomment the line. Doing so may cause
40 run-time problems. In some cases "none" refers to no default
41 setting at all, while in other cases it refers to a valid
42 option - the comments for that keyword indicate if this is the
48 Configuration options can be included using the "include" directive.
49 Include takes a list of files to include. Quoting and wildcards is
54 include /path/to/included/file/squid.acl.config
56 Includes can be nested up to a hard-coded depth of 16 levels.
57 This arbitrary restriction is to prevent recursive include references
58 from causing Squid entering an infinite loop whilst trying to load
62 Conditional configuration
64 If-statements can be used to make configuration directives
68 ... regular configuration directives ...
70 ... regular configuration directives ...]
73 The else part is optional. The keywords "if", "else", and "endif"
74 must be typed on their own lines, as if they were regular
75 configuration directives.
77 These individual conditions types are supported:
80 Always evaluates to true.
82 Always evaluates to false.
84 Equality comparison of two integer numbers.
89 The following SMP-related preprocessor macros can be used.
91 ${process_name} expands to the current Squid process "name"
92 (e.g., squid1, squid2, or cache1).
94 ${process_number} expands to the current Squid process
95 identifier, which is an integer number (e.g., 1, 2, 3) unique
96 across all Squid processes.
99 # Options Removed in 3.2
100 NAME: ignore_expect_100
103 Remove this line. The HTTP/1.1 feature is now fully supported by default.
109 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
112 NAME: url_rewrite_concurrency
115 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead.
118 # Options Removed in 3.1
122 Remove this line. DNS is no longer tested on startup.
125 NAME: extension_methods
128 Remove this line. All valid methods for HTTP are accepted by default.
131 # 2.7 Options Removed/Replaced in 3.1
139 Remove this line. HTTP/1.1 is supported by default.
142 NAME: upgrade_http0.9
145 Remove this line. ICY/1.0 streaming protocol is supported by default.
148 NAME: zph_local zph_mode zph_option zph_parent zph_sibling
151 Alter these entries. Use the qos_flows directive instead.
154 # Options Removed in 3.0
158 Since squid-3.0 replace with request_header_access or reply_header_access
159 depending on whether you wish to match client requests or server replies.
162 NAME: httpd_accel_no_pmtu_disc
165 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
169 OPTIONS FOR AUTHENTICATION
170 -----------------------------------------------------------------------------
179 This is used to define parameters for the various authentication
180 schemes supported by Squid.
182 format: auth_param scheme parameter [setting]
184 The order in which authentication schemes are presented to the client is
185 dependent on the order the scheme first appears in config file. IE
186 has a bug (it's not RFC 2617 compliant) in that it will use the basic
187 scheme if basic is the first entry presented, even if more secure
188 schemes are presented. For now use the order in the recommended
189 settings section below. If other browsers have difficulties (don't
190 recognize the schemes offered even if you are using basic) either
191 put basic first, or disable the other schemes (by commenting out their
194 Once an authentication scheme is fully configured, it can only be
195 shutdown by shutting squid down and restarting. Changes can be made on
196 the fly and activated with a reconfigure. I.E. You can change to a
197 different helper, but not unconfigure the helper completely.
199 Please note that while this directive defines how Squid processes
200 authentication it does not automatically activate authentication.
201 To use authentication you must in addition make use of ACLs based
202 on login name in http_access (proxy_auth, proxy_auth_regex or
203 external with %LOGIN used in the format tag). The browser will be
204 challenged for authentication on the first such acl encountered
205 in http_access processing and will also be re-challenged for new
206 login credentials if the request is being denied by a proxy_auth
209 WARNING: authentication can't be used in a transparently intercepting
210 proxy as the client then thinks it is talking to an origin server and
211 not the proxy. This is a limitation of bending the TCP/IP protocol to
212 transparently intercepting port 80, not a limitation in Squid.
213 Ports flagged 'transparent', 'intercept', or 'tproxy' have
214 authentication disabled.
216 === Parameters for the basic scheme follow. ===
219 Specify the command for the external authenticator. Such a program
220 reads a line containing "username password" and replies "OK" or
221 "ERR" in an endless loop. "ERR" responses may optionally be followed
222 by a error description available as %m in the returned error page.
223 If you use an authenticator, make sure you have 1 acl of type
226 By default, the basic authentication scheme is not used unless a
227 program is specified.
229 If you want to use the traditional NCSA proxy authentication, set
230 this line to something like
232 auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
235 HTTP uses iso-latin-1 as characterset, while some authentication
236 backends such as LDAP expects UTF-8. If this is set to on Squid will
237 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
238 username & password to the helper.
240 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
241 The maximum number of authenticator processes to spawn. If you start too few
242 Squid will have to wait for them to process a backlog of credential
243 verifications, slowing it down. When password verifications are
244 done via a (slow) network you are likely to need lots of
245 authenticator processes.
247 The startup= and idle= options permit some skew in the exact amount
248 run. A minimum of startup=N will begin during startup and reconfigure.
249 Squid will start more in groups of up to idle=N in an attempt to meet
250 traffic needs and to keep idle=N free above those traffic needs up to
253 The concurrency= option sets the number of concurrent requests the
254 helper can process. The default of 0 is used for helpers who only
255 supports one request at a time. Setting this to a number greater than
256 0 changes the protocol used to include a channel number first on the
257 request/response line, allowing multiple requests to be sent to the
258 same helper in parallell without wating for the response.
259 Must not be set unless it's known the helper supports this.
261 auth_param basic children 20 startup=0 idle=1
264 Specifies the realm name which is to be reported to the
265 client for the basic proxy authentication scheme (part of
266 the text the user will see when prompted their username and
267 password). There is no default.
268 auth_param basic realm Squid proxy-caching web server
270 "credentialsttl" timetolive
271 Specifies how long squid assumes an externally validated
272 username:password pair is valid for - in other words how
273 often the helper program is called for that user. Set this
274 low to force revalidation with short lived passwords. Note
275 setting this high does not impact your susceptibility
276 to replay attacks unless you are using an one-time password
277 system (such as SecureID). If you are using such a system,
278 you will be vulnerable to replay attacks unless you also
279 use the max_user_ip ACL in an http_access rule.
281 "casesensitive" on|off
282 Specifies if usernames are case sensitive. Most user databases are
283 case insensitive allowing the same username to be spelled using both
284 lower and upper case letters, but some are case sensitive. This
285 makes a big difference for user_max_ip ACL processing and similar.
286 auth_param basic casesensitive off
288 === Parameters for the digest scheme follow ===
291 Specify the command for the external authenticator. Such
292 a program reads a line containing "username":"realm" and
293 replies with the appropriate H(A1) value hex encoded or
294 ERR if the user (or his H(A1) hash) does not exists.
295 See rfc 2616 for the definition of H(A1).
296 "ERR" responses may optionally be followed by a error description
297 available as %m in the returned error page.
299 By default, the digest authentication scheme is not used unless a
300 program is specified.
302 If you want to use a digest authenticator, set this line to
305 auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass
308 HTTP uses iso-latin-1 as characterset, while some authentication
309 backends such as LDAP expects UTF-8. If this is set to on Squid will
310 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
311 username & password to the helper.
313 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
314 The maximum number of authenticator processes to spawn (default 5).
315 If you start too few Squid will have to wait for them to
316 process a backlog of H(A1) calculations, slowing it down.
317 When the H(A1) calculations are done via a (slow) network
318 you are likely to need lots of authenticator processes.
320 The startup= and idle= options permit some skew in the exact amount
321 run. A minimum of startup=N will begin during startup and reconfigure.
322 Squid will start more in groups of up to idle=N in an attempt to meet
323 traffic needs and to keep idle=N free above those traffic needs up to
326 The concurrency= option sets the number of concurrent requests the
327 helper can process. The default of 0 is used for helpers who only
328 supports one request at a time. Setting this to a number greater than
329 0 changes the protocol used to include a channel number first on the
330 request/response line, allowing multiple requests to be sent to the
331 same helper in parallell without wating for the response.
332 Must not be set unless it's known the helper supports this.
334 auth_param digest children 20 startup=0 idle=1
337 Specifies the realm name which is to be reported to the
338 client for the digest proxy authentication scheme (part of
339 the text the user will see when prompted their username and
340 password). There is no default.
341 auth_param digest realm Squid proxy-caching web server
343 "nonce_garbage_interval" timeinterval
344 Specifies the interval that nonces that have been issued
345 to client_agent's are checked for validity.
347 "nonce_max_duration" timeinterval
348 Specifies the maximum length of time a given nonce will be
351 "nonce_max_count" number
352 Specifies the maximum number of times a given nonce can be
355 "nonce_strictness" on|off
356 Determines if squid requires strict increment-by-1 behavior
357 for nonce counts, or just incrementing (off - for use when
358 useragents generate nonce counts that occasionally miss 1
359 (ie, 1,2,4,6)). Default off.
361 "check_nonce_count" on|off
362 This directive if set to off can disable the nonce count check
363 completely to work around buggy digest qop implementations in
364 certain mainstream browser versions. Default on to check the
365 nonce count to protect from authentication replay attacks.
367 "post_workaround" on|off
368 This is a workaround to certain buggy browsers who sends
369 an incorrect request digest in POST requests when reusing
370 the same nonce as acquired earlier on a GET request.
372 === NTLM scheme options follow ===
375 Specify the command for the external NTLM authenticator.
376 Such a program reads exchanged NTLMSSP packets with
377 the browser via Squid until authentication is completed.
378 If you use an NTLM authenticator, make sure you have 1 acl
379 of type proxy_auth. By default, the NTLM authenticator_program
382 auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
384 "children" numberofchildren [startup=N] [idle=N]
385 The maximum number of authenticator processes to spawn (default 5).
386 If you start too few Squid will have to wait for them to
387 process a backlog of credential verifications, slowing it
388 down. When credential verifications are done via a (slow)
389 network you are likely to need lots of authenticator
392 The startup= and idle= options permit some skew in the exact amount
393 run. A minimum of startup=N will begin during startup and reconfigure.
394 Squid will start more in groups of up to idle=N in an attempt to meet
395 traffic needs and to keep idle=N free above those traffic needs up to
398 auth_param ntlm children 20 startup=0 idle=1
401 If you experience problems with PUT/POST requests when using the
402 Negotiate authentication scheme then you can try setting this to
403 off. This will cause Squid to forcibly close the connection on
404 the initial requests where the browser asks which schemes are
405 supported by the proxy.
407 auth_param ntlm keep_alive on
409 === Options for configuring the NEGOTIATE auth-scheme follow ===
412 Specify the command for the external Negotiate authenticator.
413 This protocol is used in Microsoft Active-Directory enabled setups with
414 the Microsoft Internet Explorer or Mozilla Firefox browsers.
415 Its main purpose is to exchange credentials with the Squid proxy
416 using the Kerberos mechanisms.
417 If you use a Negotiate authenticator, make sure you have at least
418 one acl of type proxy_auth active. By default, the negotiate
419 authenticator_program is not used.
420 The only supported program for this role is the ntlm_auth
421 program distributed as part of Samba, version 4 or later.
423 auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
425 "children" numberofchildren [startup=N] [idle=N]
426 The maximum number of authenticator processes to spawn (default 5).
427 If you start too few Squid will have to wait for them to
428 process a backlog of credential verifications, slowing it
429 down. When crendential verifications are done via a (slow)
430 network you are likely to need lots of authenticator
433 The startup= and idle= options permit some skew in the exact amount
434 run. A minimum of startup=N will begin during startup and reconfigure.
435 Squid will start more in groups of up to idle=N in an attempt to meet
436 traffic needs and to keep idle=N free above those traffic needs up to
439 auth_param negotiate children 20 startup=0 idle=1
442 If you experience problems with PUT/POST requests when using the
443 Negotiate authentication scheme then you can try setting this to
444 off. This will cause Squid to forcibly close the connection on
445 the initial requests where the browser asks which schemes are
446 supported by the proxy.
448 auth_param negotiate keep_alive on
453 #Recommended minimum configuration per scheme:
454 #auth_param negotiate program <uncomment and complete this line to activate>
455 #auth_param negotiate children 20 startup=0 idle=1
456 #auth_param negotiate keep_alive on
458 #auth_param ntlm program <uncomment and complete this line to activate>
459 #auth_param ntlm children 20 startup=0 idle=1
460 #auth_param ntlm keep_alive on
462 #auth_param digest program <uncomment and complete this line>
463 #auth_param digest children 20 startup=0 idle=1
464 #auth_param digest realm Squid proxy-caching web server
465 #auth_param digest nonce_garbage_interval 5 minutes
466 #auth_param digest nonce_max_duration 30 minutes
467 #auth_param digest nonce_max_count 50
469 #auth_param basic program <uncomment and complete this line>
470 #auth_param basic children 5 startup=5 idle=1
471 #auth_param basic realm Squid proxy-caching web server
472 #auth_param basic credentialsttl 2 hours
475 NAME: authenticate_cache_garbage_interval
478 LOC: Config.authenticateGCInterval
480 The time period between garbage collection across the username cache.
481 This is a tradeoff between memory utilization (long intervals - say
482 2 days) and CPU (short intervals - say 1 minute). Only change if you
486 NAME: authenticate_ttl
489 LOC: Config.authenticateTTL
491 The time a user & their credentials stay in the logged in
492 user cache since their last request. When the garbage
493 interval passes, all user credentials that have passed their
494 TTL are removed from memory.
497 NAME: authenticate_ip_ttl
499 LOC: Config.authenticateIpTTL
502 If you use proxy authentication and the 'max_user_ip' ACL,
503 this directive controls how long Squid remembers the IP
504 addresses associated with each user. Use a small value
505 (e.g., 60 seconds) if your users might change addresses
506 quickly, as is the case with dialups. You might be safe
507 using a larger value (e.g., 2 hours) in a corporate LAN
508 environment with relatively static address assignments.
513 -----------------------------------------------------------------------------
516 NAME: external_acl_type
517 TYPE: externalAclHelper
518 LOC: Config.externalAclHelperList
521 This option defines external acl classes using a helper program
522 to look up the status
524 external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
528 ttl=n TTL in seconds for cached results (defaults to 3600
531 TTL for cached negative lookups (default same
534 Maximum number of acl helper processes spawned to service
535 external acl lookups of this type. (default 20)
537 Minimum number of acl helper processes to spawn during
538 startup and reconfigure to service external acl lookups
539 of this type. (default 0)
541 Number of acl helper processes to keep ahead of traffic
542 loads. Squid will spawn this many at once whenever load
543 rises above the capabilities of existing processes.
544 Up to the value of children-max. (default 1)
545 concurrency=n concurrency level per process. Only used with helpers
546 capable of processing more than one query at a time.
547 cache=n limit the result cache size, default is unbounded.
548 grace=n Percentage remaining of TTL where a refresh of a
549 cached entry should be initiated without needing to
550 wait for a new reply. (default is for no grace period)
551 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
552 ipv4 / ipv6 IP-mode used to communicate to this helper.
553 For compatability with older configurations and helpers
554 the default is currently 'ipv4'.
556 FORMAT specifications
558 %LOGIN Authenticated user login name
559 %EXT_USER Username from previous external acl
560 %EXT_LOG Log details from previous external acl
561 %EXT_TAG Tag from previous external acl
562 %IDENT Ident user name
564 %SRCPORT Client source port
567 %PROTO Requested protocol
569 %PATH Requested URL path
570 %METHOD Request method
571 %MYADDR Squid interface address
572 %MYPORT Squid http_port number
573 %PATH Requested URL-path (including query-string if any)
574 %USER_CERT SSL User certificate in PEM format
575 %USER_CERTCHAIN SSL User certificate chain in PEM format
576 %USER_CERT_xx SSL User certificate subject attribute xx
577 %USER_CA_xx SSL User certificate issuer attribute xx
579 %>{Header} HTTP request header "Header"
581 HTTP request header "Hdr" list member "member"
583 HTTP request header list member using ; as
584 list separator. ; can be any non-alphanumeric
587 %<{Header} HTTP reply header "Header"
589 HTTP reply header "Hdr" list member "member"
591 HTTP reply header list member using ; as
592 list separator. ; can be any non-alphanumeric
595 In addition to the above, any string specified in the referencing
596 acl will also be included in the helper request line, after the
597 specified formats (see the "acl external" directive)
599 The helper receives lines per the above format specification,
600 and returns lines starting with OK or ERR indicating the validity
601 of the request and optionally followed by additional keywords with
604 General result syntax:
606 OK/ERR keyword=value ...
610 user= The users name (login)
611 password= The users password (for login= cache_peer option)
612 message= Message describing the reason. Available as %o
614 tag= Apply a tag to a request (for both ERR and OK results)
615 Only sets a tag, does not alter existing tags.
616 log= String to be logged in access.log. Available as
617 %ea in logformat specifications
619 If protocol=3.0 (the default) then URL escaping is used to protect
620 each value in both requests and responses.
622 If using protocol=2.5 then all values need to be enclosed in quotes
623 if they may contain whitespace, or the whitespace escaped using \.
624 And quotes or \ characters within the keyword value must be \ escaped.
626 When using the concurrency= option the protocol is changed by
627 introducing a query channel tag infront of the request/response.
628 The query channel tag is a number between 0 and concurrency-1.
636 Defining an Access List
638 Every access list definition must begin with an aclname and acltype,
639 followed by either type-specific arguments or a quoted filename that
642 acl aclname acltype argument ...
643 acl aclname acltype "file" ...
645 When using "file", the file should contain one item per line.
647 By default, regular expressions are CASE-SENSITIVE.
648 To make them case-insensitive, use the -i option. To return case-sensitive
649 use the +i option between patterns, or make a new ACL line without -i.
651 Some acl types require suspending the current request in order
652 to access some external data source.
653 Those which do are marked with the tag [slow], those which
654 don't are marked as [fast].
655 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
656 for further information
658 ***** ACL TYPES AVAILABLE *****
660 acl aclname src ip-address/mask ... # clients IP address [fast]
661 acl aclname src addr1-addr2/mask ... # range of addresses [fast]
662 acl aclname dst ip-address/mask ... # URL host's IP address [slow]
663 acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
665 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
666 # The arp ACL requires the special configure option --enable-arp-acl.
667 # Furthermore, the ARP ACL code is not portable to all operating systems.
668 # It works on Linux, Solaris, Windows, FreeBSD, and some
669 # other *BSD variants.
672 # NOTE: Squid can only determine the MAC address for clients that are on
673 # the same subnet. If the client is on a different subnet,
674 # then Squid cannot find out its MAC address.
676 acl aclname srcdomain .foo.com ...
677 # reverse lookup, from client IP [slow]
678 acl aclname dstdomain .foo.com ...
679 # Destination server from URL [fast]
680 acl aclname srcdom_regex [-i] \.foo\.com ...
681 # regex matching client name [slow]
682 acl aclname dstdom_regex [-i] \.foo\.com ...
683 # regex matching server [fast]
685 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
686 # based URL is used and no match is found. The name "none" is used
687 # if the reverse lookup fails.
689 acl aclname src_as number ...
690 acl aclname dst_as number ...
692 # Except for access control, AS numbers can be used for
693 # routing of requests to specific caches. Here's an
694 # example for routing all requests for AS#1241 and only
695 # those to mycache.mydomain.net:
696 # acl asexample dst_as 1241
697 # cache_peer_access mycache.mydomain.net allow asexample
698 # cache_peer_access mycache_mydomain.net deny all
700 acl aclname peername myPeer ...
702 # match against a named cache_peer entry
703 # set unique name= on cache_peer lines for reliable use.
705 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
715 # h1:m1 must be less than h2:m2
717 acl aclname url_regex [-i] ^http:// ...
718 # regex matching on whole URL [fast]
719 acl aclname urlpath_regex [-i] \.gif$ ...
720 # regex matching on URL path [fast]
722 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
724 acl aclname localport 3128 ... # TCP port the client connected to [fast]
725 # NP: for interception mode this is usually '80'
727 acl aclname myportname 3128 ... # http(s)_port name [fast]
729 acl aclname proto HTTP FTP ... # request protocol [fast]
731 acl aclname method GET POST ... # HTTP request method [fast]
733 acl aclname http_status 200 301 500- 400-403 ...
734 # status code in reply [fast]
736 acl aclname browser [-i] regexp ...
737 # pattern match on User-Agent header (see also req_header below) [fast]
739 acl aclname referer_regex [-i] regexp ...
740 # pattern match on Referer header [fast]
741 # Referer is highly unreliable, so use with care
743 acl aclname ident username ...
744 acl aclname ident_regex [-i] pattern ...
745 # string match on ident output [slow]
746 # use REQUIRED to accept any non-null ident.
748 acl aclname proxy_auth [-i] username ...
749 acl aclname proxy_auth_regex [-i] pattern ...
750 # perform http authentication challenge to the client and match against
751 # supplied credentials [slow]
753 # takes a list of allowed usernames.
754 # use REQUIRED to accept any valid username.
756 # Will use proxy authentication in forward-proxy scenarios, and plain
757 # http authenticaiton in reverse-proxy scenarios
759 # NOTE: when a Proxy-Authentication header is sent but it is not
760 # needed during ACL checking the username is NOT logged
763 # NOTE: proxy_auth requires a EXTERNAL authentication program
764 # to check username/password combinations (see
765 # auth_param directive).
767 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
768 # as the browser needs to be configured for using a proxy in order
769 # to respond to proxy authentication.
771 acl aclname snmp_community string ...
772 # A community string to limit access to your SNMP Agent [fast]
775 # acl snmppublic snmp_community public
777 acl aclname maxconn number
778 # This will be matched when the client's IP address has
779 # more than <number> TCP connections established. [fast]
780 # NOTE: This only measures direct TCP links so X-Forwarded-For
781 # indirect clients are not counted.
783 acl aclname max_user_ip [-s] number
784 # This will be matched when the user attempts to log in from more
785 # than <number> different ip addresses. The authenticate_ip_ttl
786 # parameter controls the timeout on the ip entries. [fast]
787 # If -s is specified the limit is strict, denying browsing
788 # from any further IP addresses until the ttl has expired. Without
789 # -s Squid will just annoy the user by "randomly" denying requests.
790 # (the counter is reset each time the limit is reached and a
792 # NOTE: in acceleration mode or where there is mesh of child proxies,
793 # clients may appear to come from multiple addresses if they are
794 # going through proxy farms, so a limit of 1 may cause user problems.
796 acl aclname random probability
797 # Pseudo-randomly match requests. Based on the probability given.
798 # Probability may be written as a decimal (0.333), fraction (1/3)
799 # or ratio of matches:non-matches (3:5).
801 acl aclname req_mime_type [-i] mime-type ...
802 # regex match against the mime type of the request generated
803 # by the client. Can be used to detect file upload or some
804 # types HTTP tunneling requests [fast]
805 # NOTE: This does NOT match the reply. You cannot use this
806 # to match the returned file type.
808 acl aclname req_header header-name [-i] any\.regex\.here
809 # regex match against any of the known request headers. May be
810 # thought of as a superset of "browser", "referer" and "mime-type"
813 acl aclname rep_mime_type [-i] mime-type ...
814 # regex match against the mime type of the reply received by
815 # squid. Can be used to detect file download or some
816 # types HTTP tunneling requests. [fast]
817 # NOTE: This has no effect in http_access rules. It only has
818 # effect in rules that affect the reply data stream such as
821 acl aclname rep_header header-name [-i] any\.regex\.here
822 # regex match against any of the known reply headers. May be
823 # thought of as a superset of "browser", "referer" and "mime-type"
826 acl aclname external class_name [arguments...]
827 # external ACL lookup via a helper class defined by the
828 # external_acl_type directive [slow]
830 acl aclname user_cert attribute values...
831 # match against attributes in a user SSL certificate
832 # attribute is one of DN/C/O/CN/L/ST [fast]
834 acl aclname ca_cert attribute values...
835 # match against attributes a users issuing CA SSL certificate
836 # attribute is one of DN/C/O/CN/L/ST [fast]
838 acl aclname ext_user username ...
839 acl aclname ext_user_regex [-i] pattern ...
840 # string match on username returned by external acl helper [slow]
841 # use REQUIRED to accept any non-null user name.
843 acl aclname tag tagvalue ...
844 # string match on tag returned by external acl helper [slow]
846 acl aclname hier_code codename ...
847 # string match against squid hierarchy code(s); [fast]
848 # e.g., DIRECT, PARENT_HIT, NONE, etc.
850 # NOTE: This has no effect in http_access rules. It only has
851 # effect in rules that affect the reply data stream such as
855 acl macaddress arp 09:00:2b:23:45:67
856 acl myexample dst_as 1241
857 acl password proxy_auth REQUIRED
858 acl fileupload req_mime_type -i ^multipart/form-data$
859 acl javascript rep_mime_type -i ^application/x-javascript$
863 # Recommended minimum configuration:
865 acl manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
866 acl localhost src 127.0.0.1/32 ::1
867 acl to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
869 # Example rule allowing access from your local networks.
870 # Adapt to list your (internal) IP networks from where browsing
872 acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
873 acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
874 acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
875 acl localnet src fc00::/7 # RFC 4193 local private network range
876 acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
878 acl SSL_ports port 443
879 acl Safe_ports port 80 # http
880 acl Safe_ports port 21 # ftp
881 acl Safe_ports port 443 # https
882 acl Safe_ports port 70 # gopher
883 acl Safe_ports port 210 # wais
884 acl Safe_ports port 1025-65535 # unregistered ports
885 acl Safe_ports port 280 # http-mgmt
886 acl Safe_ports port 488 # gss-http
887 acl Safe_ports port 591 # filemaker
888 acl Safe_ports port 777 # multiling http
889 acl CONNECT method CONNECT
893 NAME: follow_x_forwarded_for
895 IFDEF: FOLLOW_X_FORWARDED_FOR
896 LOC: Config.accessList.followXFF
897 DEFAULT_IF_NONE: deny all
899 Allowing or Denying the X-Forwarded-For header to be followed to
900 find the original source of a request.
902 Requests may pass through a chain of several other proxies
903 before reaching us. The X-Forwarded-For header will contain a
904 comma-separated list of the IP addresses in the chain, with the
905 rightmost address being the most recent.
907 If a request reaches us from a source that is allowed by this
908 configuration item, then we consult the X-Forwarded-For header
909 to see where that host received the request from. If the
910 X-Forwarded-For header contains multiple addresses, we continue
911 backtracking until we reach an address for which we are not allowed
912 to follow the X-Forwarded-For header, or until we reach the first
913 address in the list. For the purpose of ACL used in the
914 follow_x_forwarded_for directive the src ACL type always matches
915 the address we are testing and srcdomain matches its rDNS.
917 The end result of this process is an IP address that we will
918 refer to as the indirect client address. This address may
919 be treated as the client address for access control, ICAP, delay
920 pools and logging, depending on the acl_uses_indirect_client,
921 icap_uses_indirect_client, delay_pool_uses_indirect_client,
922 log_uses_indirect_client and tproxy_uses_indirect_client options.
924 This clause only supports fast acl types.
925 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
927 SECURITY CONSIDERATIONS:
929 Any host for which we follow the X-Forwarded-For header
930 can place incorrect information in the header, and Squid
931 will use the incorrect information as if it were the
932 source address of the request. This may enable remote
933 hosts to bypass any access control restrictions that are
934 based on the client's source addresses.
938 acl localhost src 127.0.0.1
939 acl my_other_proxy srcdomain .proxy.example.com
940 follow_x_forwarded_for allow localhost
941 follow_x_forwarded_for allow my_other_proxy
944 NAME: acl_uses_indirect_client
947 IFDEF: FOLLOW_X_FORWARDED_FOR
949 LOC: Config.onoff.acl_uses_indirect_client
951 Controls whether the indirect client address
952 (see follow_x_forwarded_for) is used instead of the
953 direct client address in acl matching.
955 NOTE: maxconn ACL considers direct TCP links and indirect
956 clients will always have zero. So no match.
959 NAME: delay_pool_uses_indirect_client
962 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
964 LOC: Config.onoff.delay_pool_uses_indirect_client
966 Controls whether the indirect client address
967 (see follow_x_forwarded_for) is used instead of the
968 direct client address in delay pools.
971 NAME: log_uses_indirect_client
974 IFDEF: FOLLOW_X_FORWARDED_FOR
976 LOC: Config.onoff.log_uses_indirect_client
978 Controls whether the indirect client address
979 (see follow_x_forwarded_for) is used instead of the
980 direct client address in the access log.
983 NAME: tproxy_uses_indirect_client
986 IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
988 LOC: Config.onoff.tproxy_uses_indirect_client
990 Controls whether the indirect client address
991 (see follow_x_forwarded_for) is used instead of the
992 direct client address when spoofing the outgoing client.
994 This has no effect on requests arriving in non-tproxy
997 SECURITY WARNING: Usage of this option is dangerous
998 and should not be used trivially. Correct configuration
999 of folow_x_forewarded_for with a limited set of trusted
1000 sources is required to prevent abuse of your proxy.
1005 LOC: Config.accessList.http
1006 DEFAULT_IF_NONE: deny all
1008 Allowing or Denying access based on defined access lists
1010 Access to the HTTP port:
1011 http_access allow|deny [!]aclname ...
1013 NOTE on default values:
1015 If there are no "access" lines present, the default is to deny
1018 If none of the "access" lines cause a match, the default is the
1019 opposite of the last line in the list. If the last line was
1020 deny, the default is allow. Conversely, if the last line
1021 is allow, the default will be deny. For these reasons, it is a
1022 good idea to have an "deny all" entry at the end of your access
1023 lists to avoid potential confusion.
1025 This clause supports both fast and slow acl types.
1026 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1031 # Recommended minimum Access Permission configuration:
1033 # Only allow cachemgr access from localhost
1034 http_access allow localhost manager
1035 http_access deny manager
1037 # Deny requests to certain unsafe ports
1038 http_access deny !Safe_ports
1040 # Deny CONNECT to other than secure SSL ports
1041 http_access deny CONNECT !SSL_ports
1043 # We strongly recommend the following be uncommented to protect innocent
1044 # web applications running on the proxy server who think the only
1045 # one who can access services on "localhost" is a local user
1046 #http_access deny to_localhost
1049 # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
1052 # Example rule allowing access from your local networks.
1053 # Adapt localnet in the ACL section to list your (internal) IP networks
1054 # from where browsing should be allowed
1055 http_access allow localnet
1056 http_access allow localhost
1058 # And finally deny all other access to this proxy
1059 http_access deny all
1063 NAME: adapted_http_access http_access2
1065 LOC: Config.accessList.adapted_http
1068 Allowing or Denying access based on defined access lists
1070 Essentially identical to http_access, but runs after redirectors
1071 and ICAP/eCAP adaptation. Allowing access control based on their
1074 If not set then only http_access is used.
1077 NAME: http_reply_access
1079 LOC: Config.accessList.reply
1082 Allow replies to client requests. This is complementary to http_access.
1084 http_reply_access allow|deny [!] aclname ...
1086 NOTE: if there are no access lines present, the default is to allow
1089 If none of the access lines cause a match the opposite of the
1090 last line will apply. Thus it is good practice to end the rules
1091 with an "allow all" or "deny all" entry.
1093 This clause supports both fast and slow acl types.
1094 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1099 LOC: Config.accessList.icp
1100 DEFAULT_IF_NONE: deny all
1102 Allowing or Denying access to the ICP port based on defined
1105 icp_access allow|deny [!]aclname ...
1107 See http_access for details
1109 This clause only supports fast acl types.
1110 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1112 # Allow ICP queries from local networks only
1113 #icp_access allow localnet
1114 #icp_access deny all
1120 LOC: Config.accessList.htcp
1121 DEFAULT_IF_NONE: deny all
1123 Allowing or Denying access to the HTCP port based on defined
1126 htcp_access allow|deny [!]aclname ...
1128 See http_access for details
1130 NOTE: The default if no htcp_access lines are present is to
1131 deny all traffic. This default may cause problems with peers
1132 using the htcp option.
1134 This clause only supports fast acl types.
1135 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1137 # Allow HTCP queries from local networks only
1138 #htcp_access allow localnet
1139 #htcp_access deny all
1142 NAME: htcp_clr_access
1145 LOC: Config.accessList.htcp_clr
1146 DEFAULT_IF_NONE: deny all
1148 Allowing or Denying access to purge content using HTCP based
1149 on defined access lists
1151 htcp_clr_access allow|deny [!]aclname ...
1153 See http_access for details
1155 This clause only supports fast acl types.
1156 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1158 # Allow HTCP CLR requests from trusted peers
1159 acl htcp_clr_peer src 172.16.1.2
1160 htcp_clr_access allow htcp_clr_peer
1165 LOC: Config.accessList.miss
1168 Use to force your neighbors to use you as a sibling instead of
1169 a parent. For example:
1171 acl localclients src 172.16.0.0/16
1172 miss_access allow localclients
1173 miss_access deny !localclients
1175 This means only your local clients are allowed to fetch
1176 MISSES and all other clients can only fetch HITS.
1178 By default, allow all clients who passed the http_access rules
1179 to fetch MISSES from us.
1181 This clause only supports fast acl types.
1182 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1185 NAME: ident_lookup_access
1188 DEFAULT_IF_NONE: deny all
1189 LOC: Ident::TheConfig.identLookup
1191 A list of ACL elements which, if matched, cause an ident
1192 (RFC 931) lookup to be performed for this request. For
1193 example, you might choose to always perform ident lookups
1194 for your main multi-user Unix boxes, but not for your Macs
1195 and PCs. By default, ident lookups are not performed for
1198 To enable ident lookups for specific client addresses, you
1199 can follow this example:
1201 acl ident_aware_hosts src 198.168.1.0/24
1202 ident_lookup_access allow ident_aware_hosts
1203 ident_lookup_access deny all
1205 Only src type ACL checks are fully supported. A srcdomain
1206 ACL might work at times, but it will not always provide
1209 This clause only supports fast acl types.
1210 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1213 NAME: reply_body_max_size
1214 COMMENT: size [acl acl...]
1217 LOC: Config.ReplyBodySize
1219 This option specifies the maximum size of a reply body. It can be
1220 used to prevent users from downloading very large files, such as
1221 MP3's and movies. When the reply headers are received, the
1222 reply_body_max_size lines are processed, and the first line where
1223 all (if any) listed ACLs are true is used as the maximum body size
1226 This size is checked twice. First when we get the reply headers,
1227 we check the content-length value. If the content length value exists
1228 and is larger than the allowed size, the request is denied and the
1229 user receives an error message that says "the request or reply
1230 is too large." If there is no content-length, and the reply
1231 size exceeds this limit, the client's connection is just closed
1232 and they will receive a partial reply.
1234 WARNING: downstream caches probably can not detect a partial reply
1235 if there is no content-length header, so they will cache
1236 partial responses and give them out as hits. You should NOT
1237 use this option if you have downstream caches.
1239 WARNING: A maximum size smaller than the size of squid's error messages
1240 will cause an infinite loop and crash squid. Ensure that the smallest
1241 non-zero value you use is greater that the maximum header size plus
1242 the size of your largest error page.
1244 If you set this parameter none (the default), there will be
1247 Configuration Format is:
1248 reply_body_max_size SIZE UNITS [acl ...]
1250 reply_body_max_size 10 MB
1256 -----------------------------------------------------------------------------
1259 NAME: http_port ascii_port
1260 TYPE: http_port_list
1262 LOC: Config.Sockaddr.http
1264 Usage: port [mode] [options]
1265 hostname:port [mode] [options]
1266 1.2.3.4:port [mode] [options]
1268 The socket addresses where Squid will listen for HTTP client
1269 requests. You may specify multiple socket addresses.
1270 There are three forms: port alone, hostname with port, and
1271 IP address with port. If you specify a hostname or IP
1272 address, Squid binds the socket to that specific
1273 address. Most likely, you do not need to bind to a specific
1274 address, so you can use the port number alone.
1276 If you are running Squid in accelerator mode, you
1277 probably want to listen on port 80 also, or instead.
1279 The -a command line option may be used to specify additional
1280 port(s) where Squid listens for proxy request. Such ports will
1281 be plain proxy ports with no options.
1283 You may specify multiple socket addresses on multiple lines.
1287 intercept Support for IP-Layer interception of
1288 outgoing requests without browser settings.
1289 NP: disables authentication and IPv6 on the port.
1291 tproxy Support Linux TPROXY for spoofing outgoing
1292 connections using the client IP address.
1293 NP: disables authentication and maybe IPv6 on the port.
1295 accel Accelerator mode. Also needs at least one of
1296 vhost / vport / defaultsite.
1298 ssl-bump Intercept each CONNECT request matching ssl_bump ACL,
1299 establish secure connection with the client and with
1300 the server, decrypt HTTP messages as they pass through
1301 Squid, and treat them as unencrypted HTTP messages,
1302 becoming the man-in-the-middle.
1304 The ssl_bump option is required to fully enable
1305 the SslBump feature.
1307 Omitting the mode flag causes default forward proxy mode to be used.
1310 Accelerator Mode Options:
1312 allow-direct Allow direct forwarding in accelerator mode. Normally
1313 accelerated requests are denied direct forwarding as if
1314 never_direct was used.
1316 defaultsite=domainname
1317 What to use for the Host: header if it is not present
1318 in a request. Determines what site (not origin server)
1319 accelerators should consider the default.
1322 vhost Using the Host header for virtual domain support.
1323 Also uses the port as specified in Host: header.
1325 vport IP based virtual host support. Using the http_port number
1326 in passed on Host: headers.
1328 vport=NN Uses the specified port number rather than the
1331 protocol= Protocol to reconstruct accelerated requests with.
1332 Defaults to http://.
1335 Act as if this Squid is the origin server.
1336 This currently means generate new Date: and Expires:
1337 headers on HIT instead of adding Age:.
1339 ignore-cc Ignore request Cache-Control headers.
1341 Warning: This option violates HTTP specifications if
1342 used in non-accelerator setups.
1345 SSL Bump Mode Options:
1347 cert= Path to SSL certificate (PEM format).
1349 key= Path to SSL private key file (PEM format)
1350 if not specified, the certificate file is
1351 assumed to be a combined certificate and
1354 version= The version of SSL/TLS supported
1355 1 automatic (default)
1360 cipher= Colon separated list of supported ciphers.
1362 options= Various SSL engine options. The most important
1364 NO_SSLv2 Disallow the use of SSLv2
1365 NO_SSLv3 Disallow the use of SSLv3
1366 NO_TLSv1 Disallow the use of TLSv1
1367 SINGLE_DH_USE Always create a new key when using
1368 temporary/ephemeral DH key exchanges
1369 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1370 documentation for a complete list of options.
1372 clientca= File containing the list of CAs to use when
1373 requesting a client certificate.
1375 cafile= File containing additional CA certificates to
1376 use when verifying client certificates. If unset
1377 clientca will be used.
1379 capath= Directory containing additional CA certificates
1380 and CRL lists to use when verifying client certificates.
1382 crlfile= File of additional CRL lists to use when verifying
1383 the client certificate, in addition to CRLs stored in
1384 the capath. Implies VERIFY_CRL flag below.
1386 dhparams= File containing DH parameters for temporary/ephemeral
1389 sslflags= Various flags modifying the use of SSL:
1391 Don't request client certificates
1392 immediately, but wait until acl processing
1393 requires a certificate (not yet implemented).
1395 Don't use the default CA lists built in
1398 Don't allow for session reuse. Each connection
1399 will result in a new SSL session.
1401 Verify CRL lists when accepting client
1404 Verify CRL lists for all certificates in the
1405 client certificate chain.
1407 sslcontext= SSL session ID context identifier.
1409 generate-host-certificates[=<on|off>]
1410 Dynamically create SSL server certificates for the
1411 destination hosts of bumped CONNECT requests.When
1412 enabled, the cert and key options are used to sign
1413 generated certificates. Otherwise generated
1414 certificate will be selfsigned.
1415 If there is CA certificate life time of generated
1416 certificate equals lifetime of CA certificate. If
1417 generated certificate is selfsigned lifetime is three
1419 This option is enabled by default when SslBump is used.
1420 See the sslBump option above for more information.
1422 dynamic_cert_mem_cache_size=SIZE
1423 Approximate total RAM size spent on cached generated
1424 certificates. If set to zero, caching is disabled. The
1425 default value is 4MB. An average XXX-bit certificate
1426 consumes about XXX bytes of RAM.
1430 connection-auth[=on|off]
1431 use connection-auth=off to tell Squid to prevent
1432 forwarding Microsoft connection oriented authentication
1433 (NTLM, Negotiate and Kerberos)
1435 disable-pmtu-discovery=
1436 Control Path-MTU discovery usage:
1437 off lets OS decide on what to do (default).
1438 transparent disable PMTU discovery when transparent
1440 always disable always PMTU discovery.
1442 In many setups of transparently intercepting proxies
1443 Path-MTU discovery can not work on traffic towards the
1444 clients. This is the case when the intercepting device
1445 does not fully track connections and fails to forward
1446 ICMP must fragment messages to the cache server. If you
1447 have such setup and experience that certain clients
1448 sporadically hang or never complete requests set
1449 disable-pmtu-discovery option to 'transparent'.
1451 name= Specifies a internal name for the port. Defaults to
1452 the port specification (port or addr:port)
1454 tcpkeepalive[=idle,interval,timeout]
1455 Enable TCP keepalive probes of idle connections.
1456 In seconds; idle is the initial time before TCP starts
1457 probing the connection, interval how often to probe, and
1458 timeout the time before giving up.
1460 If you run Squid on a dual-homed machine with an internal
1461 and an external interface we recommend you to specify the
1462 internal address:port in http_port. This way Squid will only be
1463 visible on the internal address.
1467 # Squid normally listens to port 3128
1468 http_port @DEFAULT_HTTP_PORT@
1474 TYPE: https_port_list
1476 LOC: Config.Sockaddr.https
1478 Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...]
1480 The socket address where Squid will listen for HTTPS client
1483 This is really only useful for situations where you are running
1484 squid in accelerator mode and you want to do the SSL work at the
1487 You may specify multiple socket addresses on multiple lines,
1488 each with their own SSL certificate and/or options.
1492 accel Accelerator mode. Also needs at least one of
1493 defaultsite or vhost.
1495 defaultsite= The name of the https site presented on
1496 this port. Implies accel.
1498 vhost Accelerator mode using Host header for virtual
1499 domain support. Requires a wildcard certificate
1500 or other certificate valid for more than one domain.
1503 protocol= Protocol to reconstruct accelerated requests with.
1506 cert= Path to SSL certificate (PEM format).
1508 key= Path to SSL private key file (PEM format)
1509 if not specified, the certificate file is
1510 assumed to be a combined certificate and
1513 version= The version of SSL/TLS supported
1514 1 automatic (default)
1519 cipher= Colon separated list of supported ciphers.
1521 options= Various SSL engine options. The most important
1523 NO_SSLv2 Disallow the use of SSLv2
1524 NO_SSLv3 Disallow the use of SSLv3
1525 NO_TLSv1 Disallow the use of TLSv1
1526 SINGLE_DH_USE Always create a new key when using
1527 temporary/ephemeral DH key exchanges
1528 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1529 documentation for a complete list of options.
1531 clientca= File containing the list of CAs to use when
1532 requesting a client certificate.
1534 cafile= File containing additional CA certificates to
1535 use when verifying client certificates. If unset
1536 clientca will be used.
1538 capath= Directory containing additional CA certificates
1539 and CRL lists to use when verifying client certificates.
1541 crlfile= File of additional CRL lists to use when verifying
1542 the client certificate, in addition to CRLs stored in
1543 the capath. Implies VERIFY_CRL flag below.
1545 dhparams= File containing DH parameters for temporary/ephemeral
1548 sslflags= Various flags modifying the use of SSL:
1550 Don't request client certificates
1551 immediately, but wait until acl processing
1552 requires a certificate (not yet implemented).
1554 Don't use the default CA lists built in
1557 Don't allow for session reuse. Each connection
1558 will result in a new SSL session.
1560 Verify CRL lists when accepting client
1563 Verify CRL lists for all certificates in the
1564 client certificate chain.
1566 sslcontext= SSL session ID context identifier.
1568 vport Accelerator with IP based virtual host support.
1570 vport=NN As above, but uses specified port number rather
1571 than the https_port number. Implies accel.
1573 name= Specifies a internal name for the port. Defaults to
1574 the port specification (port or addr:port)
1578 NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
1581 LOC: Ip::Qos::TheConfig.tosToServer
1583 Allows you to select a TOS/Diffserv value for packets outgoing
1584 on the server side, based on an ACL.
1586 tcp_outgoing_tos ds-field [!]aclname ...
1588 Example where normal_service_net uses the TOS value 0x00
1589 and good_service_net uses 0x20
1591 acl normal_service_net src 10.0.0.0/24
1592 acl good_service_net src 10.0.1.0/24
1593 tcp_outgoing_tos 0x00 normal_service_net
1594 tcp_outgoing_tos 0x20 good_service_net
1596 TOS/DSCP values really only have local significance - so you should
1597 know what you're specifying. For more information, see RFC2474,
1598 RFC2475, and RFC3260.
1600 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
1601 "default" to use whatever default your host has. Note that in
1602 practice often only multiples of 4 is usable as the two rightmost bits
1603 have been redefined for use by ECN (RFC 3168 section 23.1).
1605 Processing proceeds in the order specified, and stops at first fully
1609 NAME: clientside_tos
1612 LOC: Ip::Qos::TheConfig.tosToClient
1614 Allows you to select a TOS/Diffserv value for packets being transmitted
1615 on the client-side, based on an ACL.
1617 clientside_tos ds-field [!]aclname ...
1619 Example where normal_service_net uses the TOS value 0x00
1620 and good_service_net uses 0x20
1622 acl normal_service_net src 10.0.0.0/24
1623 acl good_service_net src 10.0.1.0/24
1624 clientside_tos 0x00 normal_service_net
1625 clientside_tos 0x20 good_service_net
1627 Note: This feature is incompatible with qos_flows. Any TOS values set here
1628 will be overwritten by TOS values in qos_flows.
1631 NAME: tcp_outgoing_mark
1633 IFDEF: SO_MARK&&USE_LIBCAP
1635 LOC: Ip::Qos::TheConfig.nfmarkToServer
1637 Allows you to apply a Netfilter mark value to outgoing packets
1638 on the server side, based on an ACL.
1640 tcp_outgoing_mark mark-value [!]aclname ...
1642 Example where normal_service_net uses the mark value 0x00
1643 and good_service_net uses 0x20
1645 acl normal_service_net src 10.0.0.0/24
1646 acl good_service_net src 10.0.1.0/24
1647 tcp_outgoing_mark 0x00 normal_service_net
1648 tcp_outgoing_mark 0x20 good_service_net
1651 NAME: clientside_mark
1653 IFDEF: SO_MARK&&USE_LIBCAP
1655 LOC: Ip::Qos::TheConfig.nfmarkToClient
1657 Allows you to apply a Netfilter mark value to packets being transmitted
1658 on the client-side, based on an ACL.
1660 clientside_mark mark-value [!]aclname ...
1662 Example where normal_service_net uses the mark value 0x00
1663 and good_service_net uses 0x20
1665 acl normal_service_net src 10.0.0.0/24
1666 acl good_service_net src 10.0.1.0/24
1667 clientside_mark 0x00 normal_service_net
1668 clientside_mark 0x20 good_service_net
1670 Note: This feature is incompatible with qos_flows. Any mark values set here
1671 will be overwritten by mark values in qos_flows.
1678 LOC: Ip::Qos::TheConfig
1680 Allows you to select a TOS/DSCP value to mark outgoing
1681 connections with, based on where the reply was sourced. For
1682 platforms using netfilter, allows you to set a netfilter mark
1683 value instead of, or in addition to, a TOS value.
1685 TOS values really only have local significance - so you should
1686 know what you're specifying. For more information, see RFC2474,
1687 RFC2475, and RFC3260.
1689 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
1690 in practice often only multiples of 4 is usable as the two rightmost bits
1691 have been redefined for use by ECN (RFC 3168 section 23.1).
1693 Mark values can be any unsigned 32-bit integer value.
1695 This setting is configured by setting the following values:
1697 tos|mark Whether to set TOS or netfilter mark values
1699 local-hit=0xFF Value to mark local cache hits.
1701 sibling-hit=0xFF Value to mark hits from sibling peers.
1703 parent-hit=0xFF Value to mark hits from parent peers.
1705 miss=0xFF Value to mark cache misses. Takes precedence
1706 over the preserve-miss feature (see below).
1708 The TOS variant of the following features are only possible on Linux
1709 and require your kernel to be patched with the TOS preserving ZPH
1710 patch, available from http://zph.bratcheda.org
1711 No patch is needed to preserve the netfilter mark, which will work
1712 with all variants of netfilter.
1714 disable-preserve-miss
1715 This option disables the preservation of the TOS or netfilter
1716 mark. By default, the existing TOS or netfilter mark value of
1717 the response coming from the remote server will be retained
1718 and masked with miss-mark.
1719 NOTE: in the case of a netfilter mark, the mark must be set on
1720 the connection (using the CONNMARK target) not on the packet
1724 Allows you to mask certain bits in the TOS or mark value
1725 received from the remote server, before copying the value to
1726 the TOS sent towards clients.
1727 Default for tos: 0xFF (TOS from server is not changed).
1728 Default for mark: 0xFFFFFFFF (mark from server is not changed).
1730 All of these features require the --enable-zph-qos compilation flag
1731 (enabled by default). Netfilter marking also requires the
1732 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
1733 libcap 2.09+ (--with-libcap).
1737 NAME: tcp_outgoing_address
1740 LOC: Config.accessList.outgoing_address
1742 Allows you to map requests to different outgoing IP addresses
1743 based on the username or source address of the user making
1746 tcp_outgoing_address ipaddr [[!]aclname] ...
1749 Forwarding clients with dedicated IPs for certain subnets.
1751 acl normal_service_net src 10.0.0.0/24
1752 acl good_service_net src 10.0.2.0/24
1754 tcp_outgoing_address 2001:db8::c001 good_service_net
1755 tcp_outgoing_address 10.1.0.2 good_service_net
1757 tcp_outgoing_address 2001:db8::beef normal_service_net
1758 tcp_outgoing_address 10.1.0.1 normal_service_net
1760 tcp_outgoing_address 2001:db8::1
1761 tcp_outgoing_address 10.1.0.3
1763 Processing proceeds in the order specified, and stops at first fully
1766 Squid will add an implicit IP version test to each line.
1767 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.
1768 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.
1771 NOTE: The use of this directive using client dependent ACLs is
1772 incompatible with the use of server side persistent connections. To
1773 ensure correct results it is best to set server_persistent_connections
1774 to off when using this directive in such configurations.
1776 NOTE: The use of this directive to set a local IP on outgoing TCP links
1777 is incompatible with using TPROXY to set client IP out outbound TCP links.
1778 When needing to contact peers use the no-tproxy cache_peer option and the
1779 client_dst_passthru directive re-enable normal forwarding such as this.
1785 -----------------------------------------------------------------------------
1788 NAME: ssl_unclean_shutdown
1792 LOC: Config.SSL.unclean_shutdown
1794 Some browsers (especially MSIE) bugs out on SSL shutdown
1801 LOC: Config.SSL.ssl_engine
1804 The OpenSSL engine to use. You will need to set this if you
1805 would like to use hardware SSL acceleration for example.
1808 NAME: sslproxy_client_certificate
1811 LOC: Config.ssl_client.cert
1814 Client SSL Certificate to use when proxying https:// URLs
1817 NAME: sslproxy_client_key
1820 LOC: Config.ssl_client.key
1823 Client SSL Key to use when proxying https:// URLs
1826 NAME: sslproxy_version
1829 LOC: Config.ssl_client.version
1832 SSL version level to use when proxying https:// URLs
1835 NAME: sslproxy_options
1838 LOC: Config.ssl_client.options
1841 SSL engine options to use when proxying https:// URLs
1843 The most important being:
1845 NO_SSLv2 Disallow the use of SSLv2
1846 NO_SSLv3 Disallow the use of SSLv3
1847 NO_TLSv1 Disallow the use of TLSv1
1849 Always create a new key when using
1850 temporary/ephemeral DH key exchanges
1852 These options vary depending on your SSL engine.
1853 See the OpenSSL SSL_CTX_set_options documentation for a
1854 complete list of possible options.
1857 NAME: sslproxy_cipher
1860 LOC: Config.ssl_client.cipher
1863 SSL cipher list to use when proxying https:// URLs
1865 Colon separated list of supported ciphers.
1868 NAME: sslproxy_cafile
1871 LOC: Config.ssl_client.cafile
1874 file containing CA certificates to use when verifying server
1875 certificates while proxying https:// URLs
1878 NAME: sslproxy_capath
1881 LOC: Config.ssl_client.capath
1884 directory containing CA certificates to use when verifying
1885 server certificates while proxying https:// URLs
1891 LOC: Config.accessList.ssl_bump
1894 This ACL controls which CONNECT requests to an http_port
1895 marked with an sslBump flag are actually "bumped". Please
1896 see the sslBump flag of an http_port option for more details
1897 about decoding proxied SSL connections.
1899 By default, no requests are bumped.
1901 See also: http_port ssl-bump
1903 This clause supports both fast and slow acl types.
1904 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1907 # Example: Bump all requests except those originating from localhost and
1908 # those going to webax.com or example.com sites.
1910 acl localhost src 127.0.0.1/32
1911 acl broken_sites dstdomain .webax.com
1912 acl broken_sites dstdomain .example.com
1913 ssl_bump deny localhost
1914 ssl_bump deny broken_sites
1918 NAME: sslproxy_flags
1921 LOC: Config.ssl_client.flags
1924 Various flags modifying the use of SSL while proxying https:// URLs:
1925 DONT_VERIFY_PEER Accept certificates that fail verification.
1926 For refined control, see sslproxy_cert_error.
1927 NO_DEFAULT_CA Don't use the default CA list built in
1931 NAME: sslproxy_cert_error
1934 LOC: Config.ssl_client.cert_error
1937 Use this ACL to bypass server certificate validation errors.
1939 For example, the following lines will bypass all validation errors
1940 when talking to servers located at 172.16.0.0/16. All other
1941 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
1943 acl BrokenServersAtTrustedIP dst 172.16.0.0/16
1944 sslproxy_cert_error allow BrokenServersAtTrustedIP
1945 sslproxy_cert_error deny all
1947 This clause only supports fast acl types.
1948 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1949 Using slow acl types may result in server crashes
1951 Without this option, all server certificate validation errors
1952 terminate the transaction. Bypassing validation errors is dangerous
1953 because an error usually implies that the server cannot be trusted and
1954 the connection may be insecure.
1956 See also: sslproxy_flags and DONT_VERIFY_PEER.
1958 Default setting: sslproxy_cert_error deny all
1961 NAME: sslpassword_program
1964 LOC: Config.Program.ssl_password
1967 Specify a program used for entering SSL key passphrases
1968 when using encrypted SSL certificate keys. If not specified
1969 keys must either be unencrypted, or Squid started with the -N
1970 option to allow it to query interactively for the passphrase.
1972 The key file name is given as argument to the program allowing
1973 selection of the right password if you have multiple encrypted
1978 OPTIONS RELATING TO EXTERNAL SSL_CRTD
1979 -----------------------------------------------------------------------------
1982 NAME: sslcrtd_program
1985 DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
1986 LOC: Ssl::TheConfig.ssl_crtd
1988 Specify the location and options of the executable for ssl_crtd process.
1989 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
1990 For more information use:
1991 @DEFAULT_SSL_CRTD@ -h
1994 NAME: sslcrtd_children
1995 TYPE: HelperChildConfig
1997 DEFAULT: 32 startup=5 idle=1
1998 LOC: Ssl::TheConfig.ssl_crtdChildren
2000 The maximum number of processes spawn to service ssl server.
2001 The maximum this may be safely set to is 32.
2003 The startup= and idle= options allow some measure of skew in your
2008 Sets the minimum number of processes to spawn when Squid
2009 starts or reconfigures. When set to zero the first request will
2010 cause spawning of the first child process to handle it.
2012 Starting too few children temporary slows Squid under load while it
2013 tries to spawn enough additional processes to cope with traffic.
2017 Sets a minimum of how many processes Squid is to try and keep available
2018 at all times. When traffic begins to rise above what the existing
2019 processes can handle this many more will be spawned up to the maximum
2020 configured. A minimum setting of 1 is required.
2022 You must have at least one ssl_crtd process.
2026 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
2027 -----------------------------------------------------------------------------
2035 To specify other caches in a hierarchy, use the format:
2037 cache_peer hostname type http-port icp-port [options]
2042 # hostname type port port options
2043 # -------------------- -------- ----- ----- -----------
2044 cache_peer parent.foo.net parent 3128 3130 default
2045 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
2046 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
2047 cache_peer example.com parent 80 0 no-query default
2048 cache_peer cdn.example.com sibling 3128 0
2050 type: either 'parent', 'sibling', or 'multicast'.
2052 proxy-port: The port number where the peer accept HTTP requests.
2053 For other Squid proxies this is usually 3128
2054 For web servers this is usually 80
2056 icp-port: Used for querying neighbor caches about objects.
2057 Set to 0 if the peer does not support ICP or HTCP.
2058 See ICP and HTCP options below for additional details.
2061 ==== ICP OPTIONS ====
2063 You MUST also set icp_port and icp_access explicitly when using these options.
2064 The defaults will prevent peer traffic using ICP.
2067 no-query Disable ICP queries to this neighbor.
2070 Indicates the named peer is a member of a multicast group.
2071 ICP queries will not be sent directly to the peer, but ICP
2072 replies will be accepted from it.
2074 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
2075 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
2078 To only send ICP queries to this neighbor infrequently.
2079 This is used to keep the neighbor round trip time updated
2080 and is usually used in conjunction with weighted-round-robin.
2083 ==== HTCP OPTIONS ====
2085 You MUST also set htcp_port and htcp_access explicitly when using these options.
2086 The defaults will prevent peer traffic using HTCP.
2089 htcp Send HTCP, instead of ICP, queries to the neighbor.
2090 You probably also want to set the "icp-port" to 4827
2091 instead of 3130. This directive accepts a comma separated
2092 list of options described below.
2094 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
2096 htcp=no-clr Send HTCP to the neighbor but without
2097 sending any CLR requests. This cannot be used with
2100 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
2101 This cannot be used with no-clr.
2104 Send HTCP to the neighbor including CLRs but only when
2105 they do not result from PURGE requests.
2108 Forward any HTCP CLR requests this proxy receives to the peer.
2111 ==== PEER SELECTION METHODS ====
2113 The default peer selection method is ICP, with the first responding peer
2114 being used as source. These options can be used for better load balancing.
2117 default This is a parent cache which can be used as a "last-resort"
2118 if a peer cannot be located by any of the peer-selection methods.
2119 If specified more than once, only the first is used.
2121 round-robin Load-Balance parents which should be used in a round-robin
2122 fashion in the absence of any ICP queries.
2123 weight=N can be used to add bias.
2125 weighted-round-robin
2126 Load-Balance parents which should be used in a round-robin
2127 fashion with the frequency of each parent being based on the
2128 round trip time. Closer parents are used more often.
2129 Usually used for background-ping parents.
2130 weight=N can be used to add bias.
2132 carp Load-Balance parents which should be used as a CARP array.
2133 The requests will be distributed among the parents based on the
2134 CARP load balancing hash function based on their weight.
2136 userhash Load-balance parents based on the client proxy_auth or ident username.
2138 sourcehash Load-balance parents based on the client source IP.
2141 To be used only for cache peers of type "multicast".
2142 ALL members of this multicast group have "sibling"
2143 relationship with it, not "parent". This is to a mulicast
2144 group when the requested object would be fetched only from
2145 a "parent" cache, anyway. It's useful, e.g., when
2146 configuring a pool of redundant Squid proxies, being
2147 members of the same multicast group.
2150 ==== PEER SELECTION OPTIONS ====
2152 weight=N use to affect the selection of a peer during any weighted
2153 peer-selection mechanisms.
2154 The weight must be an integer; default is 1,
2155 larger weights are favored more.
2156 This option does not affect parent selection if a peering
2157 protocol is not in use.
2159 basetime=N Specify a base amount to be subtracted from round trip
2161 It is subtracted before division by weight in calculating
2162 which parent to fectch from. If the rtt is less than the
2163 base time the rtt is set to a minimal value.
2165 ttl=N Specify a TTL to use when sending multicast ICP queries
2167 Only useful when sending to a multicast group.
2168 Because we don't accept ICP replies from random
2169 hosts, you must configure other group members as
2170 peers with the 'multicast-responder' option.
2172 no-delay To prevent access to this neighbor from influencing the
2175 digest-url=URL Tell Squid to fetch the cache digest (if digests are
2176 enabled) for this host from the specified URL rather
2177 than the Squid default location.
2180 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
2182 originserver Causes this parent to be contacted as an origin server.
2183 Meant to be used in accelerator setups when the peer
2187 Set the Host header of requests forwarded to this peer.
2188 Useful in accelerator setups where the server (peer)
2189 expects a certain domain name but clients may request
2190 others. ie example.com or www.example.com
2192 no-digest Disable request of cache digests.
2195 Disables requesting ICMP RTT database (NetDB).
2198 ==== AUTHENTICATION OPTIONS ====
2201 If this is a personal/workgroup proxy and your parent
2202 requires proxy authentication.
2204 Note: The string can include URL escapes (i.e. %20 for
2205 spaces). This also means % must be written as %%.
2208 Send login details received from client to this peer.
2209 Both Proxy- and WWW-Authorization headers are passed
2210 without alteration to the peer.
2211 Authentication is not required by Squid for this to work.
2213 Note: This will pass any form of authentication but
2214 only Basic auth will work through a proxy unless the
2215 connection-auth options are also used.
2217 login=PASS Send login details received from client to this peer.
2218 Authentication is not required by this option.
2220 If there are no client-provided authentication headers
2221 to pass on, but username and password are available
2222 from an external ACL user= and password= result tags
2223 they may be sent instead.
2225 Note: To combine this with proxy_auth both proxies must
2226 share the same user database as HTTP only allows for
2227 a single login (one for proxy, one for origin server).
2228 Also be warned this will expose your users proxy
2229 password to the peer. USE WITH CAUTION
2232 Send the username to the upstream cache, but with a
2233 fixed password. This is meant to be used when the peer
2234 is in another administrative domain, but it is still
2235 needed to identify each user.
2236 The star can optionally be followed by some extra
2237 information which is added to the username. This can
2238 be used to identify this proxy to the peer, similar to
2239 the login=username:password option above.
2242 If this is a personal/workgroup proxy and your parent
2243 requires a secure proxy authentication.
2244 The first principal from the default keytab or defined by
2245 the environment variable KRB5_KTNAME will be used.
2247 login=NEGOTIATE:principal_name
2248 If this is a personal/workgroup proxy and your parent
2249 requires a secure proxy authentication.
2250 The principal principal_name from the default keytab or
2251 defined by the environment variable KRB5_KTNAME will be
2254 connection-auth=on|off
2255 Tell Squid that this peer does or not support Microsoft
2256 connection oriented authentication, and any such
2257 challenges received from there should be ignored.
2258 Default is auto to automatically determine the status
2262 ==== SSL / HTTPS / TLS OPTIONS ====
2264 ssl Encrypt connections to this peer with SSL/TLS.
2266 sslcert=/path/to/ssl/certificate
2267 A client SSL certificate to use when connecting to
2270 sslkey=/path/to/ssl/key
2271 The private SSL key corresponding to sslcert above.
2272 If 'sslkey' is not specified 'sslcert' is assumed to
2273 reference a combined file containing both the
2274 certificate and the key.
2277 The SSL version to use when connecting to this peer
2278 1 = automatic (default)
2283 sslcipher=... The list of valid SSL ciphers to use when connecting
2286 ssloptions=... Specify various SSL engine options:
2287 NO_SSLv2 Disallow the use of SSLv2
2288 NO_SSLv3 Disallow the use of SSLv3
2289 NO_TLSv1 Disallow the use of TLSv1
2290 See src/ssl_support.c or the OpenSSL documentation for
2291 a more complete list.
2293 sslcafile=... A file containing additional CA certificates to use
2294 when verifying the peer certificate.
2296 sslcapath=... A directory containing additional CA certificates to
2297 use when verifying the peer certificate.
2299 sslcrlfile=... A certificate revocation list file to use when
2300 verifying the peer certificate.
2302 sslflags=... Specify various flags modifying the SSL implementation:
2305 Accept certificates even if they fail to
2308 Don't use the default CA list built in
2311 Don't verify the peer certificate
2312 matches the server name
2314 ssldomain= The peer name as advertised in it's certificate.
2315 Used for verifying the correctness of the received peer
2316 certificate. If not specified the peer hostname will be
2320 Enable the "Front-End-Https: On" header needed when
2321 using Squid as a SSL frontend in front of Microsoft OWA.
2322 See MS KB document Q307347 for details on this header.
2323 If set to auto the header will only be added if the
2324 request is forwarded as a https:// URL.
2327 ==== GENERAL OPTIONS ====
2330 A peer-specific connect timeout.
2331 Also see the peer_connect_timeout directive.
2333 connect-fail-limit=N
2334 How many times connecting to a peer must fail before
2335 it is marked as down. Default is 10.
2337 allow-miss Disable Squid's use of only-if-cached when forwarding
2338 requests to siblings. This is primarily useful when
2339 icp_hit_stale is used by the sibling. To extensive use
2340 of this option may result in forwarding loops, and you
2341 should avoid having two-way peerings with this option.
2342 For example to deny peer usage on requests from peer
2343 by denying cache_peer_access if the source is a peer.
2345 max-conn=N Limit the amount of connections Squid may open to this
2348 name=xxx Unique name for the peer.
2349 Required if you have multiple peers on the same host
2350 but different ports.
2351 This name can be used in cache_peer_access and similar
2352 directives to dentify the peer.
2353 Can be used by outgoing access controls through the
2356 no-tproxy Do not use the client-spoof TPROXY support when forwarding
2357 requests to this peer. Use normal address selection instead.
2359 proxy-only objects fetched from the peer will not be stored locally.
2363 NAME: cache_peer_domain cache_host_domain
2368 Use to limit the domains for which a neighbor cache will be
2371 cache_peer_domain cache-host domain [domain ...]
2372 cache_peer_domain cache-host !domain
2374 For example, specifying
2376 cache_peer_domain parent.foo.net .edu
2378 has the effect such that UDP query packets are sent to
2379 'bigserver' only when the requested object exists on a
2380 server in the .edu domain. Prefixing the domainname
2381 with '!' means the cache will be queried for objects
2384 NOTE: * Any number of domains may be given for a cache-host,
2385 either on the same or separate lines.
2386 * When multiple domains are given for a particular
2387 cache-host, the first matched domain is applied.
2388 * Cache hosts with no domain restrictions are queried
2390 * There are no defaults.
2391 * There is also a 'cache_peer_access' tag in the ACL
2395 NAME: cache_peer_access
2400 Similar to 'cache_peer_domain' but provides more flexibility by
2403 cache_peer_access cache-host allow|deny [!]aclname ...
2405 The syntax is identical to 'http_access' and the other lists of
2406 ACL elements. See the comments for 'http_access' below, or
2407 the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
2410 NAME: neighbor_type_domain
2411 TYPE: hostdomaintype
2415 usage: neighbor_type_domain neighbor parent|sibling domain domain ...
2417 Modifying the neighbor type for specific domains is now
2418 possible. You can treat some domains differently than the
2419 default neighbor type specified on the 'cache_peer' line.
2420 Normally it should only be necessary to list domains which
2421 should be treated differently because the default neighbor type
2422 applies for hostnames which do not match domains listed here.
2425 cache_peer cache.foo.org parent 3128 3130
2426 neighbor_type_domain cache.foo.org sibling .com .net
2427 neighbor_type_domain cache.foo.org sibling .au .de
2430 NAME: dead_peer_timeout
2434 LOC: Config.Timeout.deadPeer
2436 This controls how long Squid waits to declare a peer cache
2437 as "dead." If there are no ICP replies received in this
2438 amount of time, Squid will declare the peer dead and not
2439 expect to receive any further ICP replies. However, it
2440 continues to send ICP queries, and will mark the peer as
2441 alive upon receipt of the first subsequent ICP reply.
2443 This timeout also affects when Squid expects to receive ICP
2444 replies from peers. If more than 'dead_peer' seconds have
2445 passed since the last ICP reply was received, Squid will not
2446 expect to receive an ICP reply on the next query. Thus, if
2447 your time between requests is greater than this timeout, you
2448 will see a lot of requests sent DIRECT to origin servers
2449 instead of to your parents.
2452 NAME: forward_max_tries
2455 LOC: Config.forward_max_tries
2457 Controls how many different forward paths Squid will try
2458 before giving up. See also forward_timeout.
2460 NOTE: connect_retries (default: none) can make each of these
2461 possible forwarding paths be tried multiple times.
2464 NAME: hierarchy_stoplist
2467 LOC: Config.hierarchy_stoplist
2469 A list of words which, if found in a URL, cause the object to
2470 be handled directly by this cache. In other words, use this
2471 to not query neighbor caches for certain objects. You may
2472 list this option multiple times.
2473 Note: never_direct overrides this option.
2476 # We recommend you to use at least the following line.
2477 hierarchy_stoplist cgi-bin ?
2482 MEMORY CACHE OPTIONS
2483 -----------------------------------------------------------------------------
2490 LOC: Config.memMaxSize
2492 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
2493 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
2494 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
2495 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
2497 'cache_mem' specifies the ideal amount of memory to be used
2499 * In-Transit objects
2501 * Negative-Cached objects
2503 Data for these objects are stored in 4 KB blocks. This
2504 parameter specifies the ideal upper limit on the total size of
2505 4 KB blocks allocated. In-Transit objects take the highest
2508 In-transit objects have priority over the others. When
2509 additional space is needed for incoming data, negative-cached
2510 and hot objects will be released. In other words, the
2511 negative-cached and hot objects will fill up any unused space
2512 not needed for in-transit objects.
2514 If circumstances require, this limit will be exceeded.
2515 Specifically, if your incoming request rate requires more than
2516 'cache_mem' of memory to hold in-transit objects, Squid will
2517 exceed this limit to satisfy the new requests. When the load
2518 decreases, blocks will be freed until the high-water mark is
2519 reached. Thereafter, blocks will be used to store hot
2523 NAME: maximum_object_size_in_memory
2527 LOC: Config.Store.maxInMemObjSize
2529 Objects greater than this size will not be attempted to kept in
2530 the memory cache. This should be set high enough to keep objects
2531 accessed frequently in memory to improve performance whilst low
2532 enough to keep larger objects from hoarding cache_mem.
2535 NAME: memory_cache_mode
2540 Controls which objects to keep in the memory cache (cache_mem)
2542 always Keep most recently fetched objects in memory (default)
2544 disk Only disk cache hits are kept in memory, which means
2545 an object must first be cached on disk and then hit
2546 a second time before cached in memory.
2548 network Only objects fetched from network is kept in memory
2551 NAME: memory_replacement_policy
2553 LOC: Config.memPolicy
2556 The memory replacement policy parameter determines which
2557 objects are purged from memory when memory space is needed.
2559 See cache_replacement_policy for details.
2564 -----------------------------------------------------------------------------
2567 NAME: cache_replacement_policy
2569 LOC: Config.replPolicy
2572 The cache replacement policy parameter determines which
2573 objects are evicted (replaced) when disk space is needed.
2575 lru : Squid's original list based LRU policy
2576 heap GDSF : Greedy-Dual Size Frequency
2577 heap LFUDA: Least Frequently Used with Dynamic Aging
2578 heap LRU : LRU policy implemented using a heap
2580 Applies to any cache_dir lines listed below this.
2582 The LRU policies keeps recently referenced objects.
2584 The heap GDSF policy optimizes object hit rate by keeping smaller
2585 popular objects in cache so it has a better chance of getting a
2586 hit. It achieves a lower byte hit rate than LFUDA though since
2587 it evicts larger (possibly popular) objects.
2589 The heap LFUDA policy keeps popular objects in cache regardless of
2590 their size and thus optimizes byte hit rate at the expense of
2591 hit rate since one large, popular object will prevent many
2592 smaller, slightly less popular objects from being cached.
2594 Both policies utilize a dynamic aging mechanism that prevents
2595 cache pollution that can otherwise occur with frequency-based
2596 replacement policies.
2598 NOTE: if using the LFUDA replacement policy you should increase
2599 the value of maximum_object_size above its default of 4096 KB to
2600 to maximize the potential byte hit rate improvement of LFUDA.
2602 For more information about the GDSF and LFUDA cache replacement
2603 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
2604 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
2610 LOC: Config.cacheSwap
2614 cache_dir Type Directory-Name Fs-specific-data [options]
2616 You can specify multiple cache_dir lines to spread the
2617 cache among different disk partitions.
2619 Type specifies the kind of storage system to use. Only "ufs"
2620 is built by default. To enable any of the other storage systems
2621 see the --enable-storeio configure option.
2623 'Directory' is a top-level directory where cache swap
2624 files will be stored. If you want to use an entire disk
2625 for caching, this can be the mount-point directory.
2626 The directory must exist and be writable by the Squid
2627 process. Squid will NOT create this directory for you.
2629 In SMP configurations, cache_dir must not precede the workers option
2630 and should use configuration macros or conditionals to give each
2631 worker interested in disk caching a dedicated cache directory.
2635 "ufs" is the old well-known Squid storage format that has always
2638 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
2640 'Mbytes' is the amount of disk space (MB) to use under this
2641 directory. The default is 100 MB. Change this to suit your
2642 configuration. Do NOT put the size of your disk drive here.
2643 Instead, if you want Squid to use the entire disk drive,
2644 subtract 20% and use that value.
2646 'L1' is the number of first-level subdirectories which
2647 will be created under the 'Directory'. The default is 16.
2649 'L2' is the number of second-level subdirectories which
2650 will be created under each first-level directory. The default
2653 The aufs store type:
2655 "aufs" uses the same storage format as "ufs", utilizing
2656 POSIX-threads to avoid blocking the main Squid process on
2657 disk-I/O. This was formerly known in Squid as async-io.
2659 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
2661 see argument descriptions under ufs above
2663 The diskd store type:
2665 "diskd" uses the same storage format as "ufs", utilizing a
2666 separate process to avoid blocking the main Squid process on
2669 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
2671 see argument descriptions under ufs above
2673 Q1 specifies the number of unacknowledged I/O requests when Squid
2674 stops opening new files. If this many messages are in the queues,
2675 Squid won't open new files. Default is 64
2677 Q2 specifies the number of unacknowledged messages when Squid
2678 starts blocking. If this many messages are in the queues,
2679 Squid blocks until it receives some replies. Default is 72
2681 When Q1 < Q2 (the default), the cache directory is optimized
2682 for lower response time at the expense of a decrease in hit
2683 ratio. If Q1 > Q2, the cache directory is optimized for
2684 higher hit ratio at the expense of an increase in response
2687 The coss store type:
2689 NP: COSS filesystem in Squid-3 has been deemed too unstable for
2690 production use and has thus been removed from this release.
2691 We hope that it can be made usable again soon.
2693 block-size=n defines the "block size" for COSS cache_dir's.
2694 Squid uses file numbers as block numbers. Since file numbers
2695 are limited to 24 bits, the block size determines the maximum
2696 size of the COSS partition. The default is 512 bytes, which
2697 leads to a maximum cache_dir size of 512<<24, or 8 GB. Note
2698 you should not change the coss block size after Squid
2699 has written some objects to the cache_dir.
2701 The coss file store has changed from 2.5. Now it uses a file
2702 called 'stripe' in the directory names in the config - and
2703 this will be created by squid -z.
2707 no-store, no new objects should be stored to this cache_dir
2709 min-size=n, refers to the min object size in bytes this cache_dir
2710 will accept. It's used to restrict a cache_dir to only store
2711 large objects (e.g. aufs) while other storedirs are optimized
2712 for smaller objects (e.g. COSS). Defaults to 0.
2714 max-size=n, refers to the max object size in bytes this cache_dir
2715 supports. It is used to select the cache_dir to store the object.
2716 Note: To make optimal use of the max-size limits you should order
2717 the cache_dir lines with the smallest max-size value first and the
2718 ones with no max-size specification last.
2720 Note for coss, max-size must be less than COSS_MEMBUF_SZ,
2721 which can be changed with the --with-coss-membuf-size=N configure
2725 # Uncomment and adjust the following to add a disk cache directory.
2726 #cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
2730 NAME: store_dir_select_algorithm
2732 LOC: Config.store_dir_select_algorithm
2735 Set this to 'round-robin' as an alternative.
2738 NAME: max_open_disk_fds
2740 LOC: Config.max_open_disk_fds
2743 To avoid having disk as the I/O bottleneck Squid can optionally
2744 bypass the on-disk cache if more than this amount of disk file
2745 descriptors are open.
2747 A value of 0 indicates no limit.
2750 NAME: minimum_object_size
2754 LOC: Config.Store.minObjectSize
2756 Objects smaller than this size will NOT be saved on disk. The
2757 value is specified in kilobytes, and the default is 0 KB, which
2758 means there is no minimum.
2761 NAME: maximum_object_size
2765 LOC: Config.Store.maxObjectSize
2767 Objects larger than this size will NOT be saved on disk. The
2768 value is specified in kilobytes, and the default is 4MB. If
2769 you wish to get a high BYTES hit ratio, you should probably
2770 increase this (one 32 MB object hit counts for 3200 10KB
2771 hits). If you wish to increase speed more than your want to
2772 save bandwidth you should leave this low.
2774 NOTE: if using the LFUDA replacement policy you should increase
2775 this value to maximize the byte hit rate improvement of LFUDA!
2776 See replacement_policy below for a discussion of this policy.
2779 NAME: cache_swap_low
2780 COMMENT: (percent, 0-100)
2783 LOC: Config.Swap.lowWaterMark
2786 NAME: cache_swap_high
2787 COMMENT: (percent, 0-100)
2790 LOC: Config.Swap.highWaterMark
2793 The low- and high-water marks for cache object replacement.
2794 Replacement begins when the swap (disk) usage is above the
2795 low-water mark and attempts to maintain utilization near the
2796 low-water mark. As swap utilization gets close to high-water
2797 mark object eviction becomes more aggressive. If utilization is
2798 close to the low-water mark less replacement is done each time.
2800 Defaults are 90% and 95%. If you have a large cache, 5% could be
2801 hundreds of MB. If this is the case you may wish to set these
2802 numbers closer together.
2807 -----------------------------------------------------------------------------
2817 logformat <name> <format specification>
2819 Defines an access log format.
2821 The <format specification> is a string with embedded % format codes
2823 % format codes all follow the same basic structure where all but
2824 the formatcode is optional. Output strings are automatically escaped
2825 as required according to their context and the output format
2826 modifiers are usually not needed, but can be specified if an explicit
2827 output format is desired.
2829 % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
2831 " output in quoted string format
2832 [ output in squid text log format as used by log_mime_hdrs
2833 # output in URL quoted format
2837 width field width. If starting with 0 the
2838 output is zero padded
2839 {arg} argument such as header name etc
2843 % a literal % character
2844 sn Unique sequence number per log line entry
2845 err_code The ID of an error response served by Squid or
2846 a similar internal error identifier.
2847 err_detail Additional err_code-dependent error information.
2849 Connection related format codes:
2851 >a Client source IP address
2853 >p Client source port
2854 >eui Client EUI (MAC address, EUI-48 or EUI-64 identifier)
2855 <A Server IP address or peer name
2856 la Local IP address (http_port)
2857 lp Local port number (http_port)
2858 <la Local IP address of the last server or peer connection
2859 <lp Local port number of the last server or peer connection
2861 Time related format codes:
2863 ts Seconds since epoch
2864 tu subsecond time (milliseconds)
2865 tl Local time. Optional strftime format argument
2866 default %d/%b/%Y:%H:%M:%S %z
2867 tg GMT time. Optional strftime format argument
2868 default %d/%b/%Y:%H:%M:%S %z
2869 tr Response time (milliseconds)
2870 dt Total time spent making DNS lookups (milliseconds)
2872 HTTP cache related format codes:
2874 [http::]>h Original request header. Optional header name argument
2875 on the format header[:[separator]element]
2876 [http::]>ha The HTTP request headers after adaptation and redirection.
2877 Optional header name argument as for >h
2878 [http::]<h Reply header. Optional header name argument
2880 [http::]un User name
2881 [http::]ul User name from authentication
2882 [http::]ui User name from ident
2883 [http::]us User name from SSL
2884 [http::]ue User name from external acl helper
2885 [http::]>Hs HTTP status code sent to the client
2886 [http::]<Hs HTTP status code received from the next hop
2887 [http::]<bs Number of HTTP-equivalent message body bytes
2888 received from the next hop, excluding chunked
2889 transfer encoding and control messages.
2890 Generated FTP/Gopher listings are treated as
2892 [http::]Ss Squid request status (TCP_MISS etc)
2893 [http::]Sh Squid hierarchy status (DEFAULT_PARENT etc)
2894 [http::]mt MIME content type
2895 [http::]rm Request method (GET/POST etc)
2896 [http::]>rm Request method from client
2897 [http::]<rm Request method sent to server or peer
2898 [http::]ru Request URL from client (historic, filtered for logging)
2899 [http::]>ru Request URL from client
2900 [http::]<ru Request URL sent to server or peer
2901 [http::]rp Request URL-Path excluding hostname
2902 [http::]>rp Request URL-Path excluding hostname from client
2903 [http::]<rp Request URL-Path excluding hostname sento to server or peer
2904 [http::]rv Request protocol version
2905 [http::]>rv Request protocol version from client
2906 [http::]<rv Request protocol version sent to server or peer
2907 [http::]et Tag returned by external acl
2908 [http::]ea Log string returned by external acl
2909 [http::]<st Sent reply size including HTTP headers
2910 [http::]>st Received request size including HTTP headers. In the
2911 case of chunked requests the chunked encoding metadata
2913 [http::]>sh Received HTTP request headers size
2914 [http::]<sh Sent HTTP reply headers size
2915 [http::]st Request+Reply size including HTTP headers
2916 [http::]<sH Reply high offset sent
2917 [http::]<sS Upstream object size
2918 [http::]<pt Peer response time in milliseconds. The timer starts
2919 when the last request byte is sent to the next hop
2920 and stops when the last response byte is received.
2921 [http::]<tt Total server-side time in milliseconds. The timer
2922 starts with the first connect request (or write I/O)
2923 sent to the first selected peer. The timer stops
2924 with the last I/O with the last peer.
2926 If ICAP is enabled, the following code becomes available (as
2927 well as ICAP log codes documented with the icap_log option):
2929 icap::tt Total ICAP processing time for the HTTP
2930 transaction. The timer ticks when ICAP
2931 ACLs are checked and when ICAP
2932 transaction is in progress.
2934 If adaptation is enabled the following three codes become available:
2936 adapt::<last_h The header of the last ICAP response or
2937 meta-information from the last eCAP
2938 transaction related to the HTTP transaction.
2939 Like <h, accepts an optional header name
2942 adapt::sum_trs Summed adaptation transaction response
2943 times recorded as a comma-separated list in
2944 the order of transaction start time. Each time
2945 value is recorded as an integer number,
2946 representing response time of one or more
2947 adaptation (ICAP or eCAP) transaction in
2948 milliseconds. When a failed transaction is
2949 being retried or repeated, its time is not
2950 logged individually but added to the
2951 replacement (next) transaction. See also:
2954 adapt::all_trs All adaptation transaction response times.
2955 Same as adaptation_strs but response times of
2956 individual transactions are never added
2957 together. Instead, all transaction response
2958 times are recorded individually.
2960 You can prefix adapt::*_trs format codes with adaptation
2961 service name in curly braces to record response time(s) specific
2962 to that service. For example: %{my_service}adapt::sum_trs
2964 The default formats available (which do not need re-defining) are:
2966 logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt
2967 logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
2968 logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
2969 logformat referrer %ts.%03tu %>a %{Referer}>h %ru
2970 logformat useragent %>a [%tl] "%{User-Agent}>h"
2972 When the log_mime_hdrs directive is set to ON. The squid, common and combined
2973 formats have a safely encoded copy of the mime headers appended to each line
2974 within a pair of brackets.
2976 The common and combined formats are not quite true to the Apache definition.
2977 The logs from Squid contain an extra status and hierarchy code appended.
2980 NAME: access_log cache_access_log
2982 LOC: Config.Log.accesslogs
2983 DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
2985 These files log client request activities. Has a line every HTTP or
2986 ICP request. The format is:
2987 access_log <module>:<place> [<logformat name> [acl acl ...]]
2988 access_log none [acl acl ...]]
2990 Will log to the specified module:place using the specified format (which
2991 must be defined in a logformat directive) those entries which match
2992 ALL the acl's specified (which must be defined in acl clauses).
2993 If no acl is specified, all requests will be logged to this destination.
2995 ===== Modules Currently available =====
2997 none Do not log any requests matching these ACL.
2998 Do not specify Place or logformat name.
3000 stdio Write each log line to disk immediately at the completion of
3002 Place: the filename and path to be written.
3004 daemon Very similar to stdio. But instead of writing to disk the log
3005 line is passed to a daemon helper for asychronous handling instead.
3006 Place: varies depending on the daemon.
3008 log_file_daemon Place: the file name and path to be written.
3010 syslog To log each request via syslog facility.
3011 Place: The syslog facility and priority level for these entries.
3012 Place Format: facility.priority
3014 where facility could be any of:
3015 authpriv, daemon, local0 ... local7 or user.
3017 And priority could be any of:
3018 err, warning, notice, info, debug.
3020 udp To send each log line as text data to a UDP receiver.
3021 Place: The destination host name or IP and port.
3022 Place Format: \\host:port
3024 tcp To send each log line as text data to a TCP receiver.
3025 Place: The destination host name or IP and port.
3026 Place Format: \\host:port
3029 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
3035 LOC: Config.Log.icaplogs
3038 ICAP log files record ICAP transaction summaries, one line per
3041 The icap_log option format is:
3042 icap_log <filepath> [<logformat name> [acl acl ...]]
3043 icap_log none [acl acl ...]]
3045 Please see access_log option documentation for details. The two
3046 kinds of logs share the overall configuration approach and many
3049 ICAP processing of a single HTTP message or transaction may
3050 require multiple ICAP transactions. In such cases, multiple
3051 ICAP transaction log lines will correspond to a single access
3054 ICAP log uses logformat codes that make sense for an ICAP
3055 transaction. Header-related codes are applied to the HTTP header
3056 embedded in an ICAP server response, with the following caveats:
3057 For REQMOD, there is no HTTP response header unless the ICAP
3058 server performed request satisfaction. For RESPMOD, the HTTP
3059 request header is the header sent to the ICAP server. For
3060 OPTIONS, there are no HTTP headers.
3062 The following format codes are also available for ICAP logs:
3064 icap::<A ICAP server IP address. Similar to <A.
3066 icap::<service_name ICAP service name from the icap_service
3067 option in Squid configuration file.
3069 icap::ru ICAP Request-URI. Similar to ru.
3071 icap::rm ICAP request method (REQMOD, RESPMOD, or
3072 OPTIONS). Similar to existing rm.
3074 icap::>st Bytes sent to the ICAP server (TCP payload
3075 only; i.e., what Squid writes to the socket).
3077 icap::<st Bytes received from the ICAP server (TCP
3078 payload only; i.e., what Squid reads from
3081 icap::<bs Number of message body bytes received from the
3082 ICAP server. ICAP message body, if any, usually
3083 includes encapsulated HTTP message headers and
3084 possibly encapsulated HTTP message body. The
3085 HTTP body part is dechunked before its size is
3088 icap::tr Transaction response time (in
3089 milliseconds). The timer starts when
3090 the ICAP transaction is created and
3091 stops when the transaction is completed.
3094 icap::tio Transaction I/O time (in milliseconds). The
3095 timer starts when the first ICAP request
3096 byte is scheduled for sending. The timers
3097 stops when the last byte of the ICAP response
3100 icap::to Transaction outcome: ICAP_ERR* for all
3101 transaction errors, ICAP_OPT for OPTION
3102 transactions, ICAP_ECHO for 204
3103 responses, ICAP_MOD for message
3104 modification, and ICAP_SAT for request
3105 satisfaction. Similar to Ss.
3107 icap::Hs ICAP response status code. Similar to Hs.
3109 icap::>h ICAP request header(s). Similar to >h.
3111 icap::<h ICAP response header(s). Similar to <h.
3113 The default ICAP log format, which can be used without an explicit
3114 definition, is called icap_squid:
3116 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
3118 See also: logformat, log_icap, and %adapt::<last_h
3121 NAME: logfile_daemon
3123 DEFAULT: @DEFAULT_LOGFILED@
3124 LOC: Log::TheConfig.logfile_daemon
3126 Specify the path to the logfile-writing daemon. This daemon is
3127 used to write the access and store logs, if configured.
3129 Squid sends a number of commands to the log daemon:
3130 L<data>\n - logfile data
3135 r<n>\n - set rotate count to <n>
3136 b<n>\n - 1 = buffer output, 0 = don't buffer output
3138 No responses is expected.
3143 LOC: Config.accessList.log
3145 COMMENT: allow|deny acl acl...
3147 This options allows you to control which requests gets logged
3148 to access.log (see access_log directive). Requests denied for
3149 logging will also not be accounted for in performance counters.
3151 This clause only supports fast acl types.
3152 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3158 LOC: Config.accessList.icap
3161 This options allows you to control which requests get logged
3162 to icap.log. See the icap_log directive for ICAP log details.
3165 NAME: cache_store_log
3168 LOC: Config.Log.store
3170 Logs the activities of the storage manager. Shows which
3171 objects are ejected from the cache, and which objects are
3172 saved and for how long. To disable, enter "none" or remove the line.
3173 There are not really utilities to analyze this data, so you can safely
3177 cache_store_log @DEFAULT_STORE_LOG@
3180 NAME: cache_swap_state cache_swap_log
3182 LOC: Config.Log.swap
3185 Location for the cache "swap.state" file. This index file holds
3186 the metadata of objects saved on disk. It is used to rebuild
3187 the cache during startup. Normally this file resides in each
3188 'cache_dir' directory, but you may specify an alternate
3189 pathname here. Note you must give a full filename, not just
3190 a directory. Since this is the index for the whole object
3191 list you CANNOT periodically rotate it!
3193 If %s can be used in the file name it will be replaced with a
3194 a representation of the cache_dir name where each / is replaced
3195 with '.'. This is needed to allow adding/removing cache_dir
3196 lines when cache_swap_log is being used.
3198 If have more than one 'cache_dir', and %s is not used in the name
3199 these swap logs will have names such as:
3205 The numbered extension (which is added automatically)
3206 corresponds to the order of the 'cache_dir' lines in this
3207 configuration file. If you change the order of the 'cache_dir'
3208 lines in this file, these index files will NOT correspond to
3209 the correct 'cache_dir' entry (unless you manually rename
3210 them). We recommend you do NOT use this option. It is
3211 better to keep these index files in each 'cache_dir' directory.
3214 NAME: logfile_rotate
3217 LOC: Config.Log.rotateNumber
3219 Specifies the number of logfile rotations to make when you
3220 type 'squid -k rotate'. The default is 10, which will rotate
3221 with extensions 0 through 9. Setting logfile_rotate to 0 will
3222 disable the file name rotation, but the logfiles are still closed
3223 and re-opened. This will enable you to rename the logfiles
3224 yourself just before sending the rotate signal.
3226 Note, the 'squid -k rotate' command normally sends a USR1
3227 signal to the running squid process. In certain situations
3228 (e.g. on Linux with Async I/O), USR1 is used for other
3229 purposes, so -k rotate uses another signal. It is best to get
3230 in the habit of using 'squid -k rotate' instead of 'kill -USR1
3233 Note, from Squid-3.1 this option has no effect on the cache.log,
3234 that log can be rotated separately by using debug_options
3237 NAME: emulate_httpd_log
3240 Replace this with an access_log directive using the format 'common' or 'combined'.
3243 NAME: log_ip_on_direct
3247 LOC: Config.onoff.log_ip_on_direct
3249 Log the destination IP address in the hierarchy log tag when going
3250 direct. Earlier Squid versions logged the hostname here. If you
3251 prefer the old way set this to off.
3256 DEFAULT: @DEFAULT_MIME_TABLE@
3257 LOC: Config.mimeTablePathname
3259 Pathname to Squid's MIME table. You shouldn't need to change
3260 this, but the default file contains examples and formatting
3261 information if you do.
3267 LOC: Config.onoff.log_mime_hdrs
3270 The Cache can record both the request and the response MIME
3271 headers for each HTTP transaction. The headers are encoded
3272 safely and will appear as two bracketed fields at the end of
3273 the access log (for either the native or httpd-emulated log
3274 formats). To enable this logging set log_mime_hdrs to 'on'.
3280 Replace this with an access_log directive using the format 'useragent'.
3283 NAME: referer_log referrer_log
3286 Replace this with an access_log directive using the format 'referrer'.
3291 DEFAULT: @DEFAULT_PID_FILE@
3292 LOC: Config.pidFilename
3294 A filename to write the process-id to. To disable, enter "none".
3300 Remove this option from your config. To log FQDN use %>A in the log format.
3303 NAME: client_netmask
3305 LOC: Config.Addrs.client_netmask
3308 A netmask for client addresses in logfiles and cachemgr output.
3309 Change this to protect the privacy of your cache clients.
3310 A netmask of 255.255.255.0 will log all IP's in that range with
3311 the last digit set to '0'.
3317 Use a regular access.log with ACL limiting it to MISS events.
3320 NAME: strip_query_terms
3322 LOC: Config.onoff.strip_query_terms
3325 By default, Squid strips query terms from requested URLs before
3326 logging. This protects your user's privacy.
3333 LOC: Config.onoff.buffered_logs
3335 cache.log log file is written with stdio functions, and as such
3336 it can be buffered or unbuffered. By default it will be unbuffered.
3337 Buffering it can speed up the writing slightly (though you are
3338 unlikely to need to worry unless you run with tons of debugging
3339 enabled in which case performance will suffer badly anyway..).
3342 NAME: netdb_filename
3344 DEFAULT: @DEFAULT_NETDB_FILE@
3345 LOC: Config.netdbFilename
3348 A filename where Squid stores it's netdb state between restarts.
3349 To disable, enter "none".
3353 OPTIONS FOR TROUBLESHOOTING
3354 -----------------------------------------------------------------------------
3359 DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
3360 LOC: Debug::cache_log
3362 Cache logging file. This is where general information about
3363 your cache's behavior goes. You can increase the amount of data
3364 logged to this file and how often its rotated with "debug_options"
3370 LOC: Debug::debugOptions
3372 Logging options are set as section,level where each source file
3373 is assigned a unique section. Lower levels result in less
3374 output, Full debugging (level 9) can result in a very large
3375 log file, so be careful.
3377 The magic word "ALL" sets debugging levels for all sections.
3378 We recommend normally running with "ALL,1".
3380 The rotate=N option can be used to keep more or less of these logs
3381 than would otherwise be kept by logfile_rotate.
3382 For most uses a single log should be enough to monitor current
3383 events affecting Squid.
3388 LOC: Config.coredump_dir
3389 DEFAULT_IF_NONE: none
3391 By default Squid leaves core files in the directory from where
3392 it was started. If you set 'coredump_dir' to a directory
3393 that exists, Squid will chdir() to that directory at startup
3394 and coredump files will be left there.
3398 # Leave coredumps in the first cache dir
3399 coredump_dir @DEFAULT_SWAP_DIR@
3405 OPTIONS FOR FTP GATEWAYING
3406 -----------------------------------------------------------------------------
3412 LOC: Config.Ftp.anon_user
3414 If you want the anonymous login password to be more informative
3415 (and enable the use of picky ftp servers), set this to something
3416 reasonable for your domain, like wwwuser@somewhere.net
3418 The reason why this is domainless by default is the
3419 request can be made on the behalf of a user in any domain,
3420 depending on how the cache is used.
3421 Some ftp server also validate the email address is valid
3422 (for example perl.com).
3428 LOC: Config.Ftp.passive
3430 If your firewall does not allow Squid to use passive
3431 connections, turn off this option.
3433 Use of ftp_epsv_all option requires this to be ON.
3439 LOC: Config.Ftp.epsv_all
3441 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
3443 NATs may be able to put the connection on a "fast path" through the
3444 translator, as the EPRT command will never be used and therefore,
3445 translation of the data portion of the segments will never be needed.
3447 When a client only expects to do two-way FTP transfers this may be
3449 If squid finds that it must do a three-way FTP transfer after issuing
3450 an EPSV ALL command, the FTP session will fail.
3452 If you have any doubts about this option do not use it.
3453 Squid will nicely attempt all other connection methods.
3455 Requires ftp_passive to be ON (default) for any effect.
3461 LOC: Config.Ftp.epsv
3463 FTP Protocol extensions permit the use of a special "EPSV" command.
3465 NATs may be able to put the connection on a "fast path" through the
3466 translator using EPSV, as the EPRT command will never be used
3467 and therefore, translation of the data portion of the segments
3468 will never be needed.
3470 Turning this OFF will prevent EPSV being attempted.
3471 WARNING: Doing so will convert Squid back to the old behavior with all
3472 the related problems with external NAT devices/layers.
3474 Requires ftp_passive to be ON (default) for any effect.
3480 LOC: Config.Ftp.eprt
3482 FTP Protocol extensions permit the use of a special "EPRT" command.
3484 This extension provides a protocol neutral alternative to the
3485 IPv4-only PORT command. When supported it enables active FTP data
3486 channels over IPv6 and efficient NAT handling.
3488 Turning this OFF will prevent EPRT being attempted and will skip
3489 straight to using PORT for IPv4 servers.
3491 Some devices are known to not handle this extension correctly and
3492 may result in crashes. Devices which suport EPRT enough to fail
3493 cleanly will result in Squid attempting PORT anyway. This directive
3494 should only be disabled when EPRT results in device failures.
3496 WARNING: Doing so will convert Squid back to the old behavior with all
3497 the related problems with external NAT devices/layers and IPv4-only FTP.
3500 NAME: ftp_sanitycheck
3503 LOC: Config.Ftp.sanitycheck
3505 For security and data integrity reasons Squid by default performs
3506 sanity checks of the addresses of FTP data connections ensure the
3507 data connection is to the requested server. If you need to allow
3508 FTP connections to servers using another IP address for the data
3509 connection turn this off.
3512 NAME: ftp_telnet_protocol
3515 LOC: Config.Ftp.telnet
3517 The FTP protocol is officially defined to use the telnet protocol
3518 as transport channel for the control connection. However, many
3519 implementations are broken and does not respect this aspect of
3522 If you have trouble accessing files with ASCII code 255 in the
3523 path or similar problems involving this ASCII code you can
3524 try setting this directive to off. If that helps, report to the
3525 operator of the FTP server in question that their FTP server
3526 is broken and does not follow the FTP standard.
3530 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
3531 -----------------------------------------------------------------------------
3536 DEFAULT: @DEFAULT_DISKD@
3537 LOC: Config.Program.diskd
3539 Specify the location of the diskd executable.
3540 Note this is only useful if you have compiled in
3541 diskd as one of the store io modules.
3544 NAME: unlinkd_program
3547 DEFAULT: @DEFAULT_UNLINKD@
3548 LOC: Config.Program.unlinkd
3550 Specify the location of the executable for file deletion process.
3553 NAME: pinger_program
3555 DEFAULT: @DEFAULT_PINGER@
3556 LOC: Config.pinger.program
3559 Specify the location of the executable for the pinger process.
3565 LOC: Config.pinger.enable
3568 Control whether the pinger is active at run-time.
3569 Enables turning ICMP pinger on and off with a simple
3570 squid -k reconfigure.
3575 OPTIONS FOR URL REWRITING
3576 -----------------------------------------------------------------------------
3579 NAME: url_rewrite_program redirect_program
3581 LOC: Config.Program.redirect
3584 Specify the location of the executable URL rewriter to use.
3585 Since they can perform almost any function there isn't one included.
3587 For each requested URL, the rewriter will receive on line with the format
3589 URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
3591 In the future, the rewriter interface will be extended with
3592 key=value pairs ("kvpairs" shown above). Rewriter programs
3593 should be prepared to receive and possibly ignore additional
3594 whitespace-separated tokens on each input line.
3596 And the rewriter may return a rewritten URL. The other components of
3597 the request line does not need to be returned (ignored if they are).
3599 The rewriter can also indicate that a client-side redirect should
3600 be performed to the new URL. This is done by prefixing the returned
3601 URL with "301:" (moved permanently) or 302: (moved temporarily), etc.
3603 By default, a URL rewriter is not used.
3606 NAME: url_rewrite_children redirect_children
3607 TYPE: HelperChildConfig
3608 DEFAULT: 20 startup=0 idle=1 concurrency=0
3609 LOC: Config.redirectChildren
3611 The maximum number of redirector processes to spawn. If you limit
3612 it too few Squid will have to wait for them to process a backlog of
3613 URLs, slowing it down. If you allow too many they will use RAM
3614 and other system resources noticably.
3616 The startup= and idle= options allow some measure of skew in your
3621 Sets a minimum of how many processes are to be spawned when Squid
3622 starts or reconfigures. When set to zero the first request will
3623 cause spawning of the first child process to handle it.
3625 Starting too few will cause an initial slowdown in traffic as Squid
3626 attempts to simultaneously spawn enough processes to cope.
3630 Sets a minimum of how many processes Squid is to try and keep available
3631 at all times. When traffic begins to rise above what the existing
3632 processes can handle this many more will be spawned up to the maximum
3633 configured. A minimum setting of 1 is required.
3637 The number of requests each redirector helper can handle in
3638 parallel. Defaults to 0 which indicates the redirector
3639 is a old-style single threaded redirector.
3641 When this directive is set to a value >= 1 then the protocol
3642 used to communicate with the helper is modified to include
3643 a request ID in front of the request/response. The request
3644 ID from the request must be echoed back with the response
3648 NAME: url_rewrite_host_header redirect_rewrites_host_header
3651 LOC: Config.onoff.redir_rewrites_host
3653 By default Squid rewrites any Host: header in redirected
3654 requests. If you are running an accelerator this may
3655 not be a wanted effect of a redirector.
3657 WARNING: Entries are cached on the result of the URL rewriting
3658 process, so be careful if you have domain-virtual hosts.
3661 NAME: url_rewrite_access redirector_access
3664 LOC: Config.accessList.redirector
3666 If defined, this access list specifies which requests are
3667 sent to the redirector processes. By default all requests
3670 This clause supports both fast and slow acl types.
3671 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3674 NAME: url_rewrite_bypass redirector_bypass
3676 LOC: Config.onoff.redirector_bypass
3679 When this is 'on', a request will not go through the
3680 redirector if all redirectors are busy. If this is 'off'
3681 and the redirector queue grows too large, Squid will exit
3682 with a FATAL error and ask you to increase the number of
3683 redirectors. You should only enable this if the redirectors
3684 are not critical to your caching system. If you use
3685 redirectors for access control, and you enable this option,
3686 users may have access to pages they should not
3687 be allowed to request.
3691 OPTIONS FOR TUNING THE CACHE
3692 -----------------------------------------------------------------------------
3695 NAME: cache no_cache
3698 LOC: Config.accessList.noCache
3700 A list of ACL elements which, if matched and denied, cause the request to
3701 not be satisfied from the cache and the reply to not be cached.
3702 In other words, use this to force certain objects to never be cached.
3704 You must use the words 'allow' or 'deny' to indicate whether items
3705 matching the ACL should be allowed or denied into the cache.
3707 Default is to allow all to be cached.
3709 This clause supports both fast and slow acl types.
3710 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3716 LOC: Config.maxStale
3719 This option puts an upper limit on how stale content Squid
3720 will serve from the cache if cache validation fails.
3721 Can be overriden by the refresh_pattern max-stale option.
3724 NAME: refresh_pattern
3725 TYPE: refreshpattern
3729 usage: refresh_pattern [-i] regex min percent max [options]
3731 By default, regular expressions are CASE-SENSITIVE. To make
3732 them case-insensitive, use the -i option.
3734 'Min' is the time (in minutes) an object without an explicit
3735 expiry time should be considered fresh. The recommended
3736 value is 0, any higher values may cause dynamic applications
3737 to be erroneously cached unless the application designer
3738 has taken the appropriate actions.
3740 'Percent' is a percentage of the objects age (time since last
3741 modification age) an object without explicit expiry time
3742 will be considered fresh.
3744 'Max' is an upper limit on how long objects without an explicit
3745 expiry time will be considered fresh.
3747 options: override-expire
3753 ignore-must-revalidate
3760 override-expire enforces min age even if the server
3761 sent an explicit expiry time (e.g., with the
3762 Expires: header or Cache-Control: max-age). Doing this
3763 VIOLATES the HTTP standard. Enabling this feature
3764 could make you liable for problems which it causes.
3766 Note: override-expire does not enforce staleness - it only extends
3767 freshness / min. If the server returns a Expires time which
3768 is longer than your max time, Squid will still consider
3769 the object fresh for that period of time.
3771 override-lastmod enforces min age even on objects
3772 that were modified recently.
3774 reload-into-ims changes client no-cache or ``reload''
3775 to If-Modified-Since requests. Doing this VIOLATES the
3776 HTTP standard. Enabling this feature could make you
3777 liable for problems which it causes.
3779 ignore-reload ignores a client no-cache or ``reload''
3780 header. Doing this VIOLATES the HTTP standard. Enabling
3781 this feature could make you liable for problems which
3784 ignore-no-cache ignores any ``Pragma: no-cache'' and
3785 ``Cache-control: no-cache'' headers received from a server.
3786 The HTTP RFC never allows the use of this (Pragma) header
3787 from a server, only a client, though plenty of servers
3790 ignore-no-store ignores any ``Cache-control: no-store''
3791 headers received from a server. Doing this VIOLATES
3792 the HTTP standard. Enabling this feature could make you
3793 liable for problems which it causes.
3795 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
3796 headers received from a server. Doing this VIOLATES
3797 the HTTP standard. Enabling this feature could make you
3798 liable for problems which it causes.
3800 ignore-private ignores any ``Cache-control: private''
3801 headers received from a server. Doing this VIOLATES
3802 the HTTP standard. Enabling this feature could make you
3803 liable for problems which it causes.
3805 ignore-auth caches responses to requests with authorization,
3806 as if the originserver had sent ``Cache-control: public''
3807 in the response header. Doing this VIOLATES the HTTP standard.
3808 Enabling this feature could make you liable for problems which
3811 refresh-ims causes squid to contact the origin server
3812 when a client issues an If-Modified-Since request. This
3813 ensures that the client will receive an updated version
3814 if one is available.
3816 store-stale stores responses even if they don't have explicit
3817 freshness or a validator (i.e., Last-Modified or an ETag)
3818 present, or if they're already stale. By default, Squid will
3819 not cache such responses because they usually can't be
3820 reused. Note that such responses will be stale by default.
3822 max-stale=NN provide a maximum staleness factor. Squid won't
3823 serve objects more stale than this even if it failed to
3824 validate the object. Default: use the max_stale global limit.
3826 Basically a cached object is:
3828 FRESH if expires < now, else STALE
3830 FRESH if lm-factor < percent, else STALE
3834 The refresh_pattern lines are checked in the order listed here.
3835 The first entry which matches is used. If none of the entries
3836 match the default will be used.
3838 Note, you must uncomment all the default lines if you want
3839 to change one. The default setting is only active if none is
3844 # Add any of your own refresh_pattern entries above these.
3845 refresh_pattern ^ftp: 1440 20% 10080
3846 refresh_pattern ^gopher: 1440 0% 1440
3847 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
3848 refresh_pattern . 0 20% 4320
3852 NAME: quick_abort_min
3856 LOC: Config.quickAbort.min
3859 NAME: quick_abort_max
3863 LOC: Config.quickAbort.max
3866 NAME: quick_abort_pct
3870 LOC: Config.quickAbort.pct
3872 The cache by default continues downloading aborted requests
3873 which are almost completed (less than 16 KB remaining). This
3874 may be undesirable on slow (e.g. SLIP) links and/or very busy
3875 caches. Impatient users may tie up file descriptors and
3876 bandwidth by repeatedly requesting and immediately aborting
3879 When the user aborts a request, Squid will check the
3880 quick_abort values to the amount of data transfered until
3883 If the transfer has less than 'quick_abort_min' KB remaining,
3884 it will finish the retrieval.
3886 If the transfer has more than 'quick_abort_max' KB remaining,
3887 it will abort the retrieval.
3889 If more than 'quick_abort_pct' of the transfer has completed,
3890 it will finish the retrieval.
3892 If you do not want any retrieval to continue after the client
3893 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
3896 If you want retrievals to always continue if they are being
3897 cached set 'quick_abort_min' to '-1 KB'.
3900 NAME: read_ahead_gap
3901 COMMENT: buffer-size
3903 LOC: Config.readAheadGap
3906 The amount of data the cache will buffer ahead of what has been
3907 sent to the client when retrieving an object from another server.
3911 IFDEF: USE_HTTP_VIOLATIONS
3914 LOC: Config.negativeTtl
3917 Set the Default Time-to-Live (TTL) for failed requests.
3918 Certain types of failures (such as "connection refused" and
3919 "404 Not Found") are able to be negatively-cached for a short time.
3920 Modern web servers should provide Expires: header, however if they
3921 do not this can provide a minimum TTL.
3922 The default is not to cache errors with unknown expiry details.
3924 Note that this is different from negative caching of DNS lookups.
3926 WARNING: Doing this VIOLATES the HTTP standard. Enabling
3927 this feature could make you liable for problems which it
3931 NAME: positive_dns_ttl
3934 LOC: Config.positiveDnsTtl
3937 Upper limit on how long Squid will cache positive DNS responses.
3938 Default is 6 hours (360 minutes). This directive must be set
3939 larger than negative_dns_ttl.
3942 NAME: negative_dns_ttl
3945 LOC: Config.negativeDnsTtl
3948 Time-to-Live (TTL) for negative caching of failed DNS lookups.
3949 This also sets the lower cache limit on positive lookups.
3950 Minimum value is 1 second, and it is not recommendable to go
3951 much below 10 seconds.
3954 NAME: range_offset_limit
3955 COMMENT: size [acl acl...]
3957 LOC: Config.rangeOffsetLimit
3960 usage: (size) [units] [[!]aclname]
3962 Sets an upper limit on how far (number of bytes) into the file
3963 a Range request may be to cause Squid to prefetch the whole file.
3964 If beyond this limit, Squid forwards the Range request as it is and
3965 the result is NOT cached.
3967 This is to stop a far ahead range request (lets say start at 17MB)
3968 from making Squid fetch the whole object up to that point before
3969 sending anything to the client.
3971 Multiple range_offset_limit lines may be specified, and they will
3972 be searched from top to bottom on each request until a match is found.
3973 The first match found will be used. If no line matches a request, the
3974 default limit of 0 bytes will be used.
3976 'size' is the limit specified as a number of units.
3978 'units' specifies whether to use bytes, KB, MB, etc.
3979 If no units are specified bytes are assumed.
3981 A size of 0 causes Squid to never fetch more than the
3982 client requested. (default)
3984 A size of 'none' causes Squid to always fetch the object from the
3985 beginning so it may cache the result. (2.0 style)
3987 'aclname' is the name of a defined ACL.
3989 NP: Using 'none' as the byte value here will override any quick_abort settings
3990 that may otherwise apply to the range request. The range request will
3991 be fully fetched from start to finish regardless of the client
3992 actions. This affects bandwidth usage.
3995 NAME: minimum_expiry_time
3998 LOC: Config.minimum_expiry_time
4001 The minimum caching time according to (Expires - Date)
4002 Headers Squid honors if the object can't be revalidated
4003 defaults to 60 seconds. In reverse proxy environments it
4004 might be desirable to honor shorter object lifetimes. It
4005 is most likely better to make your server return a
4006 meaningful Last-Modified header however. In ESI environments
4007 where page fragments often have short lifetimes, this will
4008 often be best set to 0.
4011 NAME: store_avg_object_size
4015 LOC: Config.Store.avgObjectSize
4017 Average object size, used to estimate number of objects your
4018 cache can hold. The default is 13 KB.
4021 NAME: store_objects_per_bucket
4024 LOC: Config.Store.objectsPerBucket
4026 Target number of objects per bucket in the store hash table.
4027 Lowering this value increases the total number of buckets and
4028 also the storage maintenance rate. The default is 20.
4033 -----------------------------------------------------------------------------
4036 NAME: request_header_max_size
4040 LOC: Config.maxRequestHeaderSize
4042 This specifies the maximum size for HTTP headers in a request.
4043 Request headers are usually relatively small (about 512 bytes).
4044 Placing a limit on the request header size will catch certain
4045 bugs (for example with persistent connections) and possibly
4046 buffer-overflow or denial-of-service attacks.
4049 NAME: reply_header_max_size
4053 LOC: Config.maxReplyHeaderSize
4055 This specifies the maximum size for HTTP headers in a reply.
4056 Reply headers are usually relatively small (about 512 bytes).
4057 Placing a limit on the reply header size will catch certain
4058 bugs (for example with persistent connections) and possibly
4059 buffer-overflow or denial-of-service attacks.
4062 NAME: request_body_max_size
4066 LOC: Config.maxRequestBodySize
4068 This specifies the maximum size for an HTTP request body.
4069 In other words, the maximum size of a PUT/POST request.
4070 A user who attempts to send a request with a body larger
4071 than this limit receives an "Invalid Request" error message.
4072 If you set this parameter to a zero (the default), there will
4073 be no limit imposed.
4076 NAME: client_request_buffer_max_size
4080 LOC: Config.maxRequestBufferSize
4082 This specifies the maximum buffer size of a client request.
4083 It prevents squid eating too much memory when somebody uploads
4087 NAME: chunked_request_body_max_size
4091 LOC: Config.maxChunkedRequestBodySize
4093 A broken or confused HTTP/1.1 client may send a chunked HTTP
4094 request to Squid. Squid does not have full support for that
4095 feature yet. To cope with such requests, Squid buffers the
4096 entire request and then dechunks request body to create a
4097 plain HTTP/1.0 request with a known content length. The plain
4098 request is then used by the rest of Squid code as usual.
4100 The option value specifies the maximum size of the buffer used
4101 to hold the request before the conversion. If the chunked
4102 request size exceeds the specified limit, the conversion
4103 fails, and the client receives an "unsupported request" error,
4104 as if dechunking was disabled.
4106 Dechunking is enabled by default. To disable conversion of
4107 chunked requests, set the maximum to zero.
4109 Request dechunking feature and this option in particular are a
4110 temporary hack. When chunking requests and responses are fully
4111 supported, there will be no need to buffer a chunked request.
4115 IFDEF: USE_HTTP_VIOLATIONS
4118 LOC: Config.accessList.brokenPosts
4120 A list of ACL elements which, if matched, causes Squid to send
4121 an extra CRLF pair after the body of a PUT/POST request.
4123 Some HTTP servers has broken implementations of PUT/POST,
4124 and rely on an extra CRLF pair sent by some WWW clients.
4126 Quote from RFC2616 section 4.1 on this matter:
4128 Note: certain buggy HTTP/1.0 client implementations generate an
4129 extra CRLF's after a POST request. To restate what is explicitly
4130 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
4131 a request with an extra CRLF.
4133 This clause only supports fast acl types.
4134 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4137 acl buggy_server url_regex ^http://....
4138 broken_posts allow buggy_server
4141 NAME: adaptation_uses_indirect_client icap_uses_indirect_client
4144 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION
4146 LOC: Adaptation::Config::use_indirect_client
4148 Controls whether the indirect client IP address (instead of the direct
4149 client IP address) is passed to adaptation services.
4151 See also: follow_x_forwarded_for adaptation_send_client_ip
4155 IFDEF: USE_HTTP_VIOLATIONS
4159 LOC: Config.onoff.via
4161 If set (default), Squid will include a Via header in requests and
4162 replies as required by RFC2616.
4168 LOC: Config.onoff.ie_refresh
4171 Microsoft Internet Explorer up until version 5.5 Service
4172 Pack 1 has an issue with transparent proxies, wherein it
4173 is impossible to force a refresh. Turning this on provides
4174 a partial fix to the problem, by causing all IMS-REFRESH
4175 requests from older IE versions to check the origin server
4176 for fresh content. This reduces hit ratio by some amount
4177 (~10% in my experience), but allows users to actually get
4178 fresh content when they want it. Note because Squid
4179 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
4180 of 5.5 is unchanged from old versions of Squid (i.e. a
4181 forced refresh is impossible). Newer versions of IE will,
4182 hopefully, continue to have the new behavior and will be
4183 handled based on that assumption. This option defaults to
4184 the old Squid behavior, which is better for hit ratios but
4185 worse for clients using IE, if they need to be able to
4186 force fresh content.
4189 NAME: vary_ignore_expire
4192 LOC: Config.onoff.vary_ignore_expire
4195 Many HTTP servers supporting Vary gives such objects
4196 immediate expiry time with no cache-control header
4197 when requested by a HTTP/1.0 client. This option
4198 enables Squid to ignore such expiry times until
4199 HTTP/1.1 is fully implemented.
4201 WARNING: If turned on this may eventually cause some
4202 varying objects not intended for caching to get cached.
4205 NAME: request_entities
4207 LOC: Config.onoff.request_entities
4210 Squid defaults to deny GET and HEAD requests with request entities,
4211 as the meaning of such requests are undefined in the HTTP standard
4212 even if not explicitly forbidden.
4214 Set this directive to on if you have clients which insists
4215 on sending request entities in GET or HEAD requests. But be warned
4216 that there is server software (both proxies and web servers) which
4217 can fail to properly process this kind of request which may make you
4218 vulnerable to cache pollution attacks if enabled.
4221 NAME: request_header_access
4222 IFDEF: USE_HTTP_VIOLATIONS
4223 TYPE: http_header_access[]
4224 LOC: Config.request_header_access
4227 Usage: request_header_access header_name allow|deny [!]aclname ...
4229 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4230 this feature could make you liable for problems which it
4233 This option replaces the old 'anonymize_headers' and the
4234 older 'http_anonymizer' option with something that is much
4235 more configurable. This new method creates a list of ACLs
4236 for each header, allowing you very fine-tuned header
4239 This option only applies to request headers, i.e., from the
4240 client to the server.
4242 You can only specify known headers for the header name.
4243 Other headers are reclassified as 'Other'. You can also
4244 refer to all the headers with 'All'.
4246 For example, to achieve the same behavior as the old
4247 'http_anonymizer standard' option, you should use:
4249 request_header_access From deny all
4250 request_header_access Referer deny all
4251 request_header_access Server deny all
4252 request_header_access User-Agent deny all
4253 request_header_access WWW-Authenticate deny all
4254 request_header_access Link deny all
4256 Or, to reproduce the old 'http_anonymizer paranoid' feature
4259 request_header_access Allow allow all
4260 request_header_access Authorization allow all
4261 request_header_access WWW-Authenticate allow all
4262 request_header_access Proxy-Authorization allow all
4263 request_header_access Proxy-Authenticate allow all
4264 request_header_access Cache-Control allow all
4265 request_header_access Content-Encoding allow all
4266 request_header_access Content-Length allow all
4267 request_header_access Content-Type allow all
4268 request_header_access Date allow all
4269 request_header_access Expires allow all
4270 request_header_access Host allow all
4271 request_header_access If-Modified-Since allow all
4272 request_header_access Last-Modified allow all
4273 request_header_access Location allow all
4274 request_header_access Pragma allow all
4275 request_header_access Accept allow all
4276 request_header_access Accept-Charset allow all
4277 request_header_access Accept-Encoding allow all
4278 request_header_access Accept-Language allow all
4279 request_header_access Content-Language allow all
4280 request_header_access Mime-Version allow all
4281 request_header_access Retry-After allow all
4282 request_header_access Title allow all
4283 request_header_access Connection allow all
4284 request_header_access All deny all
4286 although many of those are HTTP reply headers, and so should be
4287 controlled with the reply_header_access directive.
4289 By default, all headers are allowed (no anonymizing is
4293 NAME: reply_header_access
4294 IFDEF: USE_HTTP_VIOLATIONS
4295 TYPE: http_header_access[]
4296 LOC: Config.reply_header_access
4299 Usage: reply_header_access header_name allow|deny [!]aclname ...
4301 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4302 this feature could make you liable for problems which it
4305 This option only applies to reply headers, i.e., from the
4306 server to the client.
4308 This is the same as request_header_access, but in the other
4311 This option replaces the old 'anonymize_headers' and the
4312 older 'http_anonymizer' option with something that is much
4313 more configurable. This new method creates a list of ACLs
4314 for each header, allowing you very fine-tuned header
4317 You can only specify known headers for the header name.
4318 Other headers are reclassified as 'Other'. You can also
4319 refer to all the headers with 'All'.
4321 For example, to achieve the same behavior as the old
4322 'http_anonymizer standard' option, you should use:
4324 reply_header_access From deny all
4325 reply_header_access Referer deny all
4326 reply_header_access Server deny all
4327 reply_header_access User-Agent deny all
4328 reply_header_access WWW-Authenticate deny all
4329 reply_header_access Link deny all
4331 Or, to reproduce the old 'http_anonymizer paranoid' feature
4334 reply_header_access Allow allow all
4335 reply_header_access Authorization allow all
4336 reply_header_access WWW-Authenticate allow all
4337 reply_header_access Proxy-Authorization allow all
4338 reply_header_access Proxy-Authenticate allow all
4339 reply_header_access Cache-Control allow all
4340 reply_header_access Content-Encoding allow all
4341 reply_header_access Content-Length allow all
4342 reply_header_access Content-Type allow all
4343 reply_header_access Date allow all
4344 reply_header_access Expires allow all
4345 reply_header_access Host allow all
4346 reply_header_access If-Modified-Since allow all
4347 reply_header_access Last-Modified allow all
4348 reply_header_access Location allow all
4349 reply_header_access Pragma allow all
4350 reply_header_access Accept allow all
4351 reply_header_access Accept-Charset allow all
4352 reply_header_access Accept-Encoding allow all
4353 reply_header_access Accept-Language allow all
4354 reply_header_access Content-Language allow all
4355 reply_header_access Mime-Version allow all
4356 reply_header_access Retry-After allow all
4357 reply_header_access Title allow all
4358 reply_header_access Connection allow all
4359 reply_header_access All deny all
4361 although the HTTP request headers won't be usefully controlled
4362 by this directive -- see request_header_access for details.
4364 By default, all headers are allowed (no anonymizing is
4368 NAME: request_header_replace header_replace
4369 IFDEF: USE_HTTP_VIOLATIONS
4370 TYPE: http_header_replace[]
4371 LOC: Config.request_header_access
4374 Usage: request_header_replace header_name message
4375 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
4377 This option allows you to change the contents of headers
4378 denied with request_header_access above, by replacing them
4379 with some fixed string. This replaces the old fake_user_agent
4382 This only applies to request headers, not reply headers.
4384 By default, headers are removed if denied.
4387 NAME: reply_header_replace
4388 IFDEF: USE_HTTP_VIOLATIONS
4389 TYPE: http_header_replace[]
4390 LOC: Config.reply_header_access
4393 Usage: reply_header_replace header_name message
4394 Example: reply_header_replace Server Foo/1.0
4396 This option allows you to change the contents of headers
4397 denied with reply_header_access above, by replacing them
4398 with some fixed string.
4400 This only applies to reply headers, not request headers.
4402 By default, headers are removed if denied.
4405 NAME: relaxed_header_parser
4406 COMMENT: on|off|warn
4408 LOC: Config.onoff.relaxed_header_parser
4411 In the default "on" setting Squid accepts certain forms
4412 of non-compliant HTTP messages where it is unambiguous
4413 what the sending application intended even if the message
4414 is not correctly formatted. The messages is then normalized
4415 to the correct form when forwarded by Squid.
4417 If set to "warn" then a warning will be emitted in cache.log
4418 each time such HTTP error is encountered.
4420 If set to "off" then such HTTP errors will cause the request
4421 or response to be rejected.
4426 -----------------------------------------------------------------------------
4429 NAME: forward_timeout
4432 LOC: Config.Timeout.forward
4435 This parameter specifies how long Squid should at most attempt in
4436 finding a forwarding path for the request before giving up.
4439 NAME: connect_timeout
4442 LOC: Config.Timeout.connect
4445 This parameter specifies how long to wait for the TCP connect to
4446 the requested server or peer to complete before Squid should
4447 attempt to find another path where to forward the request.
4450 NAME: peer_connect_timeout
4453 LOC: Config.Timeout.peer_connect
4456 This parameter specifies how long to wait for a pending TCP
4457 connection to a peer cache. The default is 30 seconds. You
4458 may also set different timeout values for individual neighbors
4459 with the 'connect-timeout' option on a 'cache_peer' line.
4465 LOC: Config.Timeout.read
4468 The read_timeout is applied on server-side connections. After
4469 each successful read(), the timeout will be extended by this
4470 amount. If no data is read again after this amount of time,
4471 the request is aborted and logged with ERR_READ_TIMEOUT. The
4472 default is 15 minutes.
4478 LOC: Config.Timeout.write
4481 This timeout is tracked for all connections that have data
4482 available for writing and are waiting for the socket to become
4483 ready. After each successful write, the timeout is extended by
4484 the configured amount. If Squid has data to write but the
4485 connection is not ready for the configured duration, the
4486 transaction associated with the connection is terminated. The
4487 default is 15 minutes.
4490 NAME: request_timeout
4492 LOC: Config.Timeout.request
4495 How long to wait for an HTTP request after initial
4496 connection establishment.
4499 NAME: persistent_request_timeout
4501 LOC: Config.Timeout.persistent_request
4504 How long to wait for the next HTTP request on a persistent
4505 connection after the previous request completes.
4508 NAME: client_lifetime
4511 LOC: Config.Timeout.lifetime
4514 The maximum amount of time a client (browser) is allowed to
4515 remain connected to the cache process. This protects the Cache
4516 from having a lot of sockets (and hence file descriptors) tied up
4517 in a CLOSE_WAIT state from remote clients that go away without
4518 properly shutting down (either because of a network failure or
4519 because of a poor client implementation). The default is one
4522 NOTE: The default value is intended to be much larger than any
4523 client would ever need to be connected to your cache. You
4524 should probably change client_lifetime only as a last resort.
4525 If you seem to have many client connections tying up
4526 filedescriptors, we recommend first tuning the read_timeout,
4527 request_timeout, persistent_request_timeout and quick_abort values.
4530 NAME: half_closed_clients
4532 LOC: Config.onoff.half_closed_clients
4535 Some clients may shutdown the sending side of their TCP
4536 connections, while leaving their receiving sides open. Sometimes,
4537 Squid can not tell the difference between a half-closed and a
4538 fully-closed TCP connection.
4540 By default, Squid will immediately close client connections when
4541 read(2) returns "no more data to read."
4543 Change this option to 'on' and Squid will keep open connections
4544 until a read(2) or write(2) on the socket returns an error.
4545 This may show some benefits for reverse proxies. But if not
4546 it is recommended to leave OFF.
4551 LOC: Config.Timeout.pconn
4554 Timeout for idle persistent connections to servers and other
4561 LOC: Ident::TheConfig.timeout
4564 Maximum time to wait for IDENT lookups to complete.
4566 If this is too high, and you enabled IDENT lookups from untrusted
4567 users, you might be susceptible to denial-of-service by having
4568 many ident requests going at once.
4571 NAME: shutdown_lifetime
4574 LOC: Config.shutdownLifetime
4577 When SIGTERM or SIGHUP is received, the cache is put into
4578 "shutdown pending" mode until all active sockets are closed.
4579 This value is the lifetime to set for all open descriptors
4580 during shutdown mode. Any active clients after this many
4581 seconds will receive a 'timeout' message.
4585 ADMINISTRATIVE PARAMETERS
4586 -----------------------------------------------------------------------------
4592 LOC: Config.adminEmail
4594 Email-address of local cache manager who will receive
4595 mail if the cache dies. The default is "webmaster."
4601 LOC: Config.EmailFrom
4603 From: email-address for mail sent when the cache dies.
4604 The default is to use 'appname@unique_hostname'.
4605 Default appname value is "squid", can be changed into
4606 src/globals.h before building squid.
4612 LOC: Config.EmailProgram
4614 Email program used to send mail if the cache dies.
4615 The default is "mail". The specified program must comply
4616 with the standard Unix mail syntax:
4617 mail-program recipient < mailfile
4619 Optional command line options can be specified.
4622 NAME: cache_effective_user
4624 DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
4625 LOC: Config.effectiveUser
4627 If you start Squid as root, it will change its effective/real
4628 UID/GID to the user specified below. The default is to change
4629 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
4630 see also; cache_effective_group
4633 NAME: cache_effective_group
4636 LOC: Config.effectiveGroup
4638 Squid sets the GID to the effective user's default group ID
4639 (taken from the password file) and supplementary group list
4640 from the groups membership.
4642 If you want Squid to run with a specific GID regardless of
4643 the group memberships of the effective user then set this
4644 to the group (or GID) you want Squid to run as. When set
4645 all other group privileges of the effective user are ignored
4646 and only this GID is effective. If Squid is not started as
4647 root the user starting Squid MUST be member of the specified
4650 This option is not recommended by the Squid Team.
4651 Our preference is for administrators to configure a secure
4652 user account for squid with UID/GID matching system policies.
4655 NAME: httpd_suppress_version_string
4659 LOC: Config.onoff.httpd_suppress_version_string
4661 Suppress Squid version string info in HTTP headers and HTML error pages.
4664 NAME: visible_hostname
4666 LOC: Config.visibleHostname
4669 If you want to present a special hostname in error messages, etc,
4670 define this. Otherwise, the return value of gethostname()
4671 will be used. If you have multiple caches in a cluster and
4672 get errors about IP-forwarding you must set them to have individual
4673 names with this setting.
4676 NAME: unique_hostname
4678 LOC: Config.uniqueHostname
4681 If you want to have multiple machines with the same
4682 'visible_hostname' you must give each machine a different
4683 'unique_hostname' so forwarding loops can be detected.
4686 NAME: hostname_aliases
4688 LOC: Config.hostnameAliases
4691 A list of other DNS names your cache has.
4699 Minimum umask which should be enforced while the proxy
4700 is running, in addition to the umask set at startup.
4702 For a traditional octal representation of umasks, start
4707 OPTIONS FOR THE CACHE REGISTRATION SERVICE
4708 -----------------------------------------------------------------------------
4710 This section contains parameters for the (optional) cache
4711 announcement service. This service is provided to help
4712 cache administrators locate one another in order to join or
4713 create cache hierarchies.
4715 An 'announcement' message is sent (via UDP) to the registration
4716 service by Squid. By default, the announcement message is NOT
4717 SENT unless you enable it with 'announce_period' below.
4719 The announcement message includes your hostname, plus the
4720 following information from this configuration file:
4726 All current information is processed regularly and made
4727 available on the Web at http://www.ircache.net/Cache/Tracker/.
4730 NAME: announce_period
4732 LOC: Config.Announce.period
4735 This is how frequently to send cache announcements. The
4736 default is `0' which disables sending the announcement
4739 To enable announcing your cache, just set an announce period.
4742 announce_period 1 day
4747 DEFAULT: tracker.ircache.net
4748 LOC: Config.Announce.host
4754 LOC: Config.Announce.file
4760 LOC: Config.Announce.port
4762 announce_host and announce_port set the hostname and port
4763 number where the registration message will be sent.
4765 Hostname will default to 'tracker.ircache.net' and port will
4766 default default to 3131. If the 'filename' argument is given,
4767 the contents of that file will be included in the announce
4772 HTTPD-ACCELERATOR OPTIONS
4773 -----------------------------------------------------------------------------
4776 NAME: httpd_accel_surrogate_id
4779 LOC: Config.Accel.surrogate_id
4781 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
4782 need an identification token to allow control targeting. Because
4783 a farm of surrogates may all perform the same tasks, they may share
4784 an identification token.
4786 The default ID is the visible_hostname
4789 NAME: http_accel_surrogate_remote
4793 LOC: Config.onoff.surrogate_is_remote
4795 Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
4796 Set this to on to have squid behave as a remote surrogate.
4800 IFDEF: USE_SQUID_ESI
4801 COMMENT: libxml2|expat|custom
4803 LOC: ESIParser::Type
4806 ESI markup is not strictly XML compatible. The custom ESI parser
4807 will give higher performance, but cannot handle non ASCII character
4812 DELAY POOL PARAMETERS
4813 -----------------------------------------------------------------------------
4817 TYPE: delay_pool_count
4819 IFDEF: USE_DELAY_POOLS
4822 This represents the number of delay pools to be used. For example,
4823 if you have one class 2 delay pool and one class 3 delays pool, you
4824 have a total of 2 delay pools.
4828 TYPE: delay_pool_class
4830 IFDEF: USE_DELAY_POOLS
4833 This defines the class of each delay pool. There must be exactly one
4834 delay_class line for each delay pool. For example, to define two
4835 delay pools, one of class 2 and one of class 3, the settings above
4839 delay_pools 4 # 4 delay pools
4840 delay_class 1 2 # pool 1 is a class 2 pool
4841 delay_class 2 3 # pool 2 is a class 3 pool
4842 delay_class 3 4 # pool 3 is a class 4 pool
4843 delay_class 4 5 # pool 4 is a class 5 pool
4845 The delay pool classes are:
4847 class 1 Everything is limited by a single aggregate
4850 class 2 Everything is limited by a single aggregate
4851 bucket as well as an "individual" bucket chosen
4852 from bits 25 through 32 of the IPv4 address.
4854 class 3 Everything is limited by a single aggregate
4855 bucket as well as a "network" bucket chosen
4856 from bits 17 through 24 of the IP address and a
4857 "individual" bucket chosen from bits 17 through
4858 32 of the IPv4 address.
4860 class 4 Everything in a class 3 delay pool, with an
4861 additional limit on a per user basis. This
4862 only takes effect if the username is established
4863 in advance - by forcing authentication in your
4866 class 5 Requests are grouped according their tag (see
4867 external_acl's tag= reply).
4870 Each pool also requires a delay_parameters directive to configure the pool size
4871 and speed limits used whenever the pool is applied to a request. Along with
4872 a set of delay_access directives to determine when it is used.
4874 NOTE: If an IP address is a.b.c.d
4875 -> bits 25 through 32 are "d"
4876 -> bits 17 through 24 are "c"
4877 -> bits 17 through 32 are "c * 256 + d"
4879 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
4880 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
4884 TYPE: delay_pool_access
4886 IFDEF: USE_DELAY_POOLS
4889 This is used to determine which delay pool a request falls into.
4891 delay_access is sorted per pool and the matching starts with pool 1,
4892 then pool 2, ..., and finally pool N. The first delay pool where the
4893 request is allowed is selected for the request. If it does not allow
4894 the request to any pool then the request is not delayed (default).
4896 For example, if you want some_big_clients in delay
4897 pool 1 and lotsa_little_clients in delay pool 2:
4900 delay_access 1 allow some_big_clients
4901 delay_access 1 deny all
4902 delay_access 2 allow lotsa_little_clients
4903 delay_access 2 deny all
4904 delay_access 3 allow authenticated_clients
4907 NAME: delay_parameters
4908 TYPE: delay_pool_rates
4910 IFDEF: USE_DELAY_POOLS
4913 This defines the parameters for a delay pool. Each delay pool has
4914 a number of "buckets" associated with it, as explained in the
4915 description of delay_class.
4917 For a class 1 delay pool, the syntax is:
4919 delay_parameters pool aggregate
4921 For a class 2 delay pool:
4923 delay_parameters pool aggregate individual
4925 For a class 3 delay pool:
4927 delay_parameters pool aggregate network individual
4929 For a class 4 delay pool:
4931 delay_parameters pool aggregate network individual user
4933 For a class 5 delay pool:
4935 delay_parameters pool tagrate
4937 The option variables are:
4939 pool a pool number - ie, a number between 1 and the
4940 number specified in delay_pools as used in
4943 aggregate the speed limit parameters for the aggregate bucket
4946 individual the speed limit parameters for the individual
4947 buckets (class 2, 3).
4949 network the speed limit parameters for the network buckets
4952 user the speed limit parameters for the user buckets
4955 tagrate the speed limit parameters for the tag buckets
4958 A pair of delay parameters is written restore/maximum, where restore is
4959 the number of bytes (not bits - modem and network speeds are usually
4960 quoted in bits) per second placed into the bucket, and maximum is the
4961 maximum number of bytes which can be in the bucket at any time.
4963 There must be one delay_parameters line for each delay pool.
4966 For example, if delay pool number 1 is a class 2 delay pool as in the
4967 above example, and is being used to strictly limit each host to 64Kbit/sec
4968 (plus overheads), with no overall limit, the line is:
4970 delay_parameters 1 -1/-1 8000/8000
4972 Note that 8 x 8000 KByte/sec -> 64Kbit/sec.
4974 Note that the figure -1 is used to represent "unlimited".
4977 And, if delay pool number 2 is a class 3 delay pool as in the above
4978 example, and you want to limit it to a total of 256Kbit/sec (strict limit)
4979 with each 8-bit network permitted 64Kbit/sec (strict limit) and each
4980 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits
4981 to permit a decent web page to be downloaded at a decent speed
4982 (if the network is not being limited due to overuse) but slow down
4983 large downloads more significantly:
4985 delay_parameters 2 32000/32000 8000/8000 600/8000
4987 Note that 8 x 32000 KByte/sec -> 256Kbit/sec.
4988 8 x 8000 KByte/sec -> 64Kbit/sec.
4989 8 x 600 Byte/sec -> 4800bit/sec.
4992 Finally, for a class 4 delay pool as in the example - each user will
4993 be limited to 128Kbits/sec no matter how many workstations they are logged into.:
4995 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
4998 NAME: delay_initial_bucket_level
4999 COMMENT: (percent, 0-100)
5002 IFDEF: USE_DELAY_POOLS
5003 LOC: Config.Delay.initial
5005 The initial bucket percentage is used to determine how much is put
5006 in each bucket when squid starts, is reconfigured, or first notices
5007 a host accessing it (in class 2 and class 3, individual hosts and
5008 networks only have buckets associated with them once they have been
5013 CLIENT DELAY POOL PARAMETERS
5014 -----------------------------------------------------------------------------
5017 NAME: client_delay_pools
5018 TYPE: client_delay_pool_count
5020 IFDEF: USE_DELAY_POOLS
5021 LOC: Config.ClientDelay
5023 This option specifies the number of client delay pools used. It must
5024 preceed other client_delay_* options.
5027 client_delay_pools 2
5030 NAME: client_delay_initial_bucket_level
5031 COMMENT: (percent, 0-no_limit)
5034 IFDEF: USE_DELAY_POOLS
5035 LOC: Config.ClientDelay.initial
5037 This option determines the initial bucket size as a percentage of
5038 max_bucket_size from client_delay_parameters. Buckets are created
5039 at the time of the "first" connection from the matching IP. Idle
5040 buckets are periodically deleted up.
5042 You can specify more than 100 percent but note that such "oversized"
5043 buckets are not refilled until their size goes down to max_bucket_size
5044 from client_delay_parameters.
5047 client_delay_initial_bucket_level 50
5050 NAME: client_delay_parameters
5051 TYPE: client_delay_pool_rates
5053 IFDEF: USE_DELAY_POOLS
5054 LOC: Config.ClientDelay
5057 This option configures client-side bandwidth limits using the
5060 client_delay_parameters pool speed_limit max_bucket_size
5062 pool is an integer ID used for client_delay_access matching.
5064 speed_limit is bytes added to the bucket per second.
5066 max_bucket_size is the maximum size of a bucket, enforced after any
5067 speed_limit additions.
5069 Please see the delay_parameters option for more information and
5073 client_delay_parameters 1 1024 2048
5074 client_delay_parameters 2 51200 16384
5077 NAME: client_delay_access
5078 TYPE: client_delay_pool_access
5080 IFDEF: USE_DELAY_POOLS
5081 LOC: Config.ClientDelay
5084 This option determines the client-side delay pool for the
5087 client_delay_access pool_ID allow|deny acl_name
5089 All client_delay_access options are checked in their pool ID
5090 order, starting with pool 1. The first checked pool with allowed
5091 request is selected for the request. If no ACL matches or there
5092 are no client_delay_access options, the request bandwidth is not
5095 The ACL-selected pool is then used to find the
5096 client_delay_parameters for the request. Client-side pools are
5097 not used to aggregate clients. Clients are always aggregated
5098 based on their source IP addresses (one bucket per source IP).
5100 Please see delay_access for more examples.
5103 client_delay_access 1 allow low_rate_network
5104 client_delay_access 2 allow vips_network
5108 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
5109 -----------------------------------------------------------------------------
5114 LOC: Config.Wccp.router
5118 Use this option to define your WCCP ``home'' router for
5121 wccp_router supports a single WCCP(v1) router
5123 wccp2_router supports multiple WCCPv2 routers
5125 only one of the two may be used at the same time and defines
5126 which version of WCCP to use.
5130 TYPE: IpAddress_list
5131 LOC: Config.Wccp2.router
5135 Use this option to define your WCCP ``home'' router for
5138 wccp_router supports a single WCCP(v1) router
5140 wccp2_router supports multiple WCCPv2 routers
5142 only one of the two may be used at the same time and defines
5143 which version of WCCP to use.
5148 LOC: Config.Wccp.version
5152 This directive is only relevant if you need to set up WCCP(v1)
5153 to some very old and end-of-life Cisco routers. In all other
5154 setups it must be left unset or at the default setting.
5155 It defines an internal version in the WCCP(v1) protocol,
5156 with version 4 being the officially documented protocol.
5158 According to some users, Cisco IOS 11.2 and earlier only
5159 support WCCP version 3. If you're using that or an earlier
5160 version of IOS, you may need to change this value to 3, otherwise
5161 do not specify this parameter.
5164 NAME: wccp2_rebuild_wait
5166 LOC: Config.Wccp2.rebuildwait
5170 If this is enabled Squid will wait for the cache dir rebuild to finish
5171 before sending the first wccp2 HereIAm packet
5174 NAME: wccp2_forwarding_method
5176 LOC: Config.Wccp2.forwarding_method
5180 WCCP2 allows the setting of forwarding methods between the
5181 router/switch and the cache. Valid values are as follows:
5183 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5184 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
5186 Currently (as of IOS 12.4) cisco routers only support GRE.
5187 Cisco switches only support the L2 redirect assignment method.
5190 NAME: wccp2_return_method
5192 LOC: Config.Wccp2.return_method
5196 WCCP2 allows the setting of return methods between the
5197 router/switch and the cache for packets that the cache
5198 decides not to handle. Valid values are as follows:
5200 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5201 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
5203 Currently (as of IOS 12.4) cisco routers only support GRE.
5204 Cisco switches only support the L2 redirect assignment.
5206 If the "ip wccp redirect exclude in" command has been
5207 enabled on the cache interface, then it is still safe for
5208 the proxy server to use a l2 redirect method even if this
5209 option is set to GRE.
5212 NAME: wccp2_assignment_method
5214 LOC: Config.Wccp2.assignment_method
5218 WCCP2 allows the setting of methods to assign the WCCP hash
5219 Valid values are as follows:
5221 hash - Hash assignment
5222 mask - Mask assignment
5224 As a general rule, cisco routers support the hash assignment method
5225 and cisco switches support the mask assignment method.
5230 LOC: Config.Wccp2.info
5231 DEFAULT_IF_NONE: standard 0
5234 WCCP2 allows for multiple traffic services. There are two
5235 types: "standard" and "dynamic". The standard type defines
5236 one service id - http (id 0). The dynamic service ids can be from
5237 51 to 255 inclusive. In order to use a dynamic service id
5238 one must define the type of traffic to be redirected; this is done
5239 using the wccp2_service_info option.
5241 The "standard" type does not require a wccp2_service_info option,
5242 just specifying the service id will suffice.
5244 MD5 service authentication can be enabled by adding
5245 "password=<password>" to the end of this service declaration.
5249 wccp2_service standard 0 # for the 'web-cache' standard service
5250 wccp2_service dynamic 80 # a dynamic service type which will be
5251 # fleshed out with subsequent options.
5252 wccp2_service standard 0 password=foo
5255 NAME: wccp2_service_info
5256 TYPE: wccp2_service_info
5257 LOC: Config.Wccp2.info
5261 Dynamic WCCPv2 services require further information to define the
5262 traffic you wish to have diverted.
5266 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
5267 priority=<priority> ports=<port>,<port>..
5269 The relevant WCCPv2 flags:
5270 + src_ip_hash, dst_ip_hash
5271 + source_port_hash, dst_port_hash
5272 + src_ip_alt_hash, dst_ip_alt_hash
5273 + src_port_alt_hash, dst_port_alt_hash
5276 The port list can be one to eight entries.
5280 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
5281 priority=240 ports=80
5283 Note: the service id must have been defined by a previous
5284 'wccp2_service dynamic <id>' entry.
5289 LOC: Config.Wccp2.weight
5293 Each cache server gets assigned a set of the destination
5294 hash proportional to their weight.
5299 LOC: Config.Wccp.address
5306 LOC: Config.Wccp2.address
5310 Use this option if you require WCCP to use a specific
5313 The default behavior is to not bind to any specific address.
5317 PERSISTENT CONNECTION HANDLING
5318 -----------------------------------------------------------------------------
5320 Also see "pconn_timeout" in the TIMEOUTS section
5323 NAME: client_persistent_connections
5325 LOC: Config.onoff.client_pconns
5329 NAME: server_persistent_connections
5331 LOC: Config.onoff.server_pconns
5334 Persistent connection support for clients and servers. By
5335 default, Squid uses persistent connections (when allowed)
5336 with its clients and servers. You can use these options to
5337 disable persistent connections with clients and/or servers.
5340 NAME: persistent_connection_after_error
5342 LOC: Config.onoff.error_pconns
5345 With this directive the use of persistent connections after
5346 HTTP errors can be disabled. Useful if you have clients
5347 who fail to handle errors on persistent connections proper.
5350 NAME: detect_broken_pconn
5352 LOC: Config.onoff.detect_broken_server_pconns
5355 Some servers have been found to incorrectly signal the use
5356 of HTTP/1.0 persistent connections even on replies not
5357 compatible, causing significant delays. This server problem
5358 has mostly been seen on redirects.
5360 By enabling this directive Squid attempts to detect such
5361 broken replies and automatically assume the reply is finished
5362 after 10 seconds timeout.
5366 CACHE DIGEST OPTIONS
5367 -----------------------------------------------------------------------------
5370 NAME: digest_generation
5371 IFDEF: USE_CACHE_DIGESTS
5373 LOC: Config.onoff.digest_generation
5376 This controls whether the server will generate a Cache Digest
5377 of its contents. By default, Cache Digest generation is
5378 enabled if Squid is compiled with --enable-cache-digests defined.
5381 NAME: digest_bits_per_entry
5382 IFDEF: USE_CACHE_DIGESTS
5384 LOC: Config.digest.bits_per_entry
5387 This is the number of bits of the server's Cache Digest which
5388 will be associated with the Digest entry for a given HTTP
5389 Method and URL (public key) combination. The default is 5.
5392 NAME: digest_rebuild_period
5393 IFDEF: USE_CACHE_DIGESTS
5396 LOC: Config.digest.rebuild_period
5399 This is the wait time between Cache Digest rebuilds.
5402 NAME: digest_rewrite_period
5404 IFDEF: USE_CACHE_DIGESTS
5406 LOC: Config.digest.rewrite_period
5409 This is the wait time between Cache Digest writes to
5413 NAME: digest_swapout_chunk_size
5416 IFDEF: USE_CACHE_DIGESTS
5417 LOC: Config.digest.swapout_chunk_size
5420 This is the number of bytes of the Cache Digest to write to
5421 disk at a time. It defaults to 4096 bytes (4KB), the Squid
5425 NAME: digest_rebuild_chunk_percentage
5426 COMMENT: (percent, 0-100)
5427 IFDEF: USE_CACHE_DIGESTS
5429 LOC: Config.digest.rebuild_chunk_percentage
5432 This is the percentage of the Cache Digest to be scanned at a
5433 time. By default it is set to 10% of the Cache Digest.
5438 -----------------------------------------------------------------------------
5443 LOC: Config.Port.snmp
5447 The port number where Squid listens for SNMP requests. To enable
5448 SNMP support set this to a suitable port number. Port number
5449 3401 is often used for the Squid SNMP agent. By default it's
5450 set to "0" (disabled)
5458 LOC: Config.accessList.snmp
5459 DEFAULT_IF_NONE: deny all
5462 Allowing or denying access to the SNMP port.
5464 All access to the agent is denied by default.
5467 snmp_access allow|deny [!]aclname ...
5469 This clause only supports fast acl types.
5470 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5472 snmp_access allow snmppublic localhost
5473 snmp_access deny all
5476 NAME: snmp_incoming_address
5478 LOC: Config.Addrs.snmp_incoming
5483 NAME: snmp_outgoing_address
5485 LOC: Config.Addrs.snmp_outgoing
5489 Just like 'udp_incoming_address', but for the SNMP port.
5491 snmp_incoming_address is used for the SNMP socket receiving
5492 messages from SNMP agents.
5493 snmp_outgoing_address is used for SNMP packets returned to SNMP
5496 The default snmp_incoming_address is to listen on all
5497 available network interfaces.
5499 If snmp_outgoing_address is not set it will use the same socket
5500 as snmp_incoming_address. Only change this if you want to have
5501 SNMP replies sent using another address than where this Squid
5502 listens for SNMP queries.
5504 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
5505 the same value since they both use port 3401.
5510 -----------------------------------------------------------------------------
5513 NAME: icp_port udp_port
5516 LOC: Config.Port.icp
5518 The port number where Squid sends and receives ICP queries to
5519 and from neighbor caches. The standard UDP port for ICP is 3130.
5520 Default is disabled (0).
5523 icp_port @DEFAULT_ICP_PORT@
5530 LOC: Config.Port.htcp
5532 The port number where Squid sends and receives HTCP queries to
5533 and from neighbor caches. To turn it on you want to set it to
5534 4827. By default it is set to "0" (disabled).
5540 NAME: log_icp_queries
5544 LOC: Config.onoff.log_udp
5546 If set, ICP queries are logged to access.log. You may wish
5547 do disable this if your ICP load is VERY high to speed things
5548 up or to simplify log analysis.
5551 NAME: udp_incoming_address
5553 LOC:Config.Addrs.udp_incoming
5556 udp_incoming_address is used for UDP packets received from other
5559 The default behavior is to not bind to any specific address.
5561 Only change this if you want to have all UDP queries received on
5562 a specific interface/address.
5564 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
5565 modules. Altering it will affect all of them in the same manner.
5567 see also; udp_outgoing_address
5569 NOTE, udp_incoming_address and udp_outgoing_address can not
5570 have the same value since they both use the same port.
5573 NAME: udp_outgoing_address
5575 LOC: Config.Addrs.udp_outgoing
5578 udp_outgoing_address is used for UDP packets sent out to other
5581 The default behavior is to not bind to any specific address.
5583 Instead it will use the same socket as udp_incoming_address.
5584 Only change this if you want to have UDP queries sent using another
5585 address than where this Squid listens for UDP queries from other
5588 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
5589 modules. Altering it will affect all of them in the same manner.
5591 see also; udp_incoming_address
5593 NOTE, udp_incoming_address and udp_outgoing_address can not
5594 have the same value since they both use the same port.
5601 LOC: Config.onoff.icp_hit_stale
5603 If you want to return ICP_HIT for stale cache objects, set this
5604 option to 'on'. If you have sibling relationships with caches
5605 in other administrative domains, this should be 'off'. If you only
5606 have sibling relationships with caches under your control,
5607 it is probably okay to set this to 'on'.
5608 If set to 'on', your siblings should use the option "allow-miss"
5609 on their cache_peer lines for connecting to you.
5612 NAME: minimum_direct_hops
5615 LOC: Config.minDirectHops
5617 If using the ICMP pinging stuff, do direct fetches for sites
5618 which are no more than this many hops away.
5621 NAME: minimum_direct_rtt
5624 LOC: Config.minDirectRtt
5626 If using the ICMP pinging stuff, do direct fetches for sites
5627 which are no more than this many rtt milliseconds away.
5633 LOC: Config.Netdb.low
5639 LOC: Config.Netdb.high
5641 The low and high water marks for the ICMP measurement
5642 database. These are counts, not percents. The defaults are
5643 900 and 1000. When the high water mark is reached, database
5644 entries will be deleted until the low mark is reached.
5647 NAME: netdb_ping_period
5649 LOC: Config.Netdb.period
5652 The minimum period for measuring a site. There will be at
5653 least this much delay between successive pings to the same
5654 network. The default is five minutes.
5661 LOC: Config.onoff.query_icmp
5663 If you want to ask your peers to include ICMP data in their ICP
5664 replies, enable this option.
5666 If your peer has configured Squid (during compilation) with
5667 '--enable-icmp' that peer will send ICMP pings to origin server
5668 sites of the URLs it receives. If you enable this option the
5669 ICP replies from that peer will include the ICMP data (if available).
5670 Then, when choosing a parent cache, Squid will choose the parent with
5671 the minimal RTT to the origin server. When this happens, the
5672 hierarchy field of the access.log will be
5673 "CLOSEST_PARENT_MISS". This option is off by default.
5676 NAME: test_reachability
5680 LOC: Config.onoff.test_reachability
5682 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
5683 instead of ICP_MISS if the target host is NOT in the ICMP
5684 database, or has a zero RTT.
5687 NAME: icp_query_timeout
5691 LOC: Config.Timeout.icp_query
5693 Normally Squid will automatically determine an optimal ICP
5694 query timeout value based on the round-trip-time of recent ICP
5695 queries. If you want to override the value determined by
5696 Squid, set this 'icp_query_timeout' to a non-zero value. This
5697 value is specified in MILLISECONDS, so, to use a 2-second
5698 timeout (the old default), you would write:
5700 icp_query_timeout 2000
5703 NAME: maximum_icp_query_timeout
5707 LOC: Config.Timeout.icp_query_max
5709 Normally the ICP query timeout is determined dynamically. But
5710 sometimes it can lead to very large values (say 5 seconds).
5711 Use this option to put an upper limit on the dynamic timeout
5712 value. Do NOT use this option to always use a fixed (instead
5713 of a dynamic) timeout value. To set a fixed timeout see the
5714 'icp_query_timeout' directive.
5717 NAME: minimum_icp_query_timeout
5721 LOC: Config.Timeout.icp_query_min
5723 Normally the ICP query timeout is determined dynamically. But
5724 sometimes it can lead to very small timeouts, even lower than
5725 the normal latency variance on your link due to traffic.
5726 Use this option to put an lower limit on the dynamic timeout
5727 value. Do NOT use this option to always use a fixed (instead
5728 of a dynamic) timeout value. To set a fixed timeout see the
5729 'icp_query_timeout' directive.
5732 NAME: background_ping_rate
5736 LOC: Config.backgroundPingRate
5738 Controls how often the ICP pings are sent to siblings that
5739 have background-ping set.
5743 MULTICAST ICP OPTIONS
5744 -----------------------------------------------------------------------------
5749 LOC: Config.mcast_group_list
5752 This tag specifies a list of multicast groups which your server
5753 should join to receive multicasted ICP queries.
5755 NOTE! Be very careful what you put here! Be sure you
5756 understand the difference between an ICP _query_ and an ICP
5757 _reply_. This option is to be set only if you want to RECEIVE
5758 multicast queries. Do NOT set this option to SEND multicast
5759 ICP (use cache_peer for that). ICP replies are always sent via
5760 unicast, so this option does not affect whether or not you will
5761 receive replies from multicast group members.
5763 You must be very careful to NOT use a multicast address which
5764 is already in use by another group of caches.
5766 If you are unsure about multicast, please read the Multicast
5767 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
5769 Usage: mcast_groups 239.128.16.128 224.0.1.20
5771 By default, Squid doesn't listen on any multicast groups.
5774 NAME: mcast_miss_addr
5775 IFDEF: MULTICAST_MISS_STREAM
5777 LOC: Config.mcast_miss.addr
5780 If you enable this option, every "cache miss" URL will
5781 be sent out on the specified multicast address.
5783 Do not enable this option unless you are are absolutely
5784 certain you understand what you are doing.
5787 NAME: mcast_miss_ttl
5788 IFDEF: MULTICAST_MISS_STREAM
5790 LOC: Config.mcast_miss.ttl
5793 This is the time-to-live value for packets multicasted
5794 when multicasting off cache miss URLs is enabled. By
5795 default this is set to 'site scope', i.e. 16.
5798 NAME: mcast_miss_port
5799 IFDEF: MULTICAST_MISS_STREAM
5801 LOC: Config.mcast_miss.port
5804 This is the port number to be used in conjunction with
5808 NAME: mcast_miss_encode_key
5809 IFDEF: MULTICAST_MISS_STREAM
5811 LOC: Config.mcast_miss.encode_key
5812 DEFAULT: XXXXXXXXXXXXXXXX
5814 The URLs that are sent in the multicast miss stream are
5815 encrypted. This is the encryption key.
5818 NAME: mcast_icp_query_timeout
5822 LOC: Config.Timeout.mcast_icp_query
5824 For multicast peers, Squid regularly sends out ICP "probes" to
5825 count how many other peers are listening on the given multicast
5826 address. This value specifies how long Squid should wait to
5827 count all the replies. The default is 2000 msec, or 2
5832 INTERNAL ICON OPTIONS
5833 -----------------------------------------------------------------------------
5836 NAME: icon_directory
5838 LOC: Config.icons.directory
5839 DEFAULT: @DEFAULT_ICON_DIR@
5841 Where the icons are stored. These are normally kept in
5845 NAME: global_internal_static
5847 LOC: Config.onoff.global_internal_static
5850 This directive controls is Squid should intercept all requests for
5851 /squid-internal-static/ no matter which host the URL is requesting
5852 (default on setting), or if nothing special should be done for
5853 such URLs (off setting). The purpose of this directive is to make
5854 icons etc work better in complex cache hierarchies where it may
5855 not always be possible for all corners in the cache mesh to reach
5856 the server generating a directory listing.
5859 NAME: short_icon_urls
5861 LOC: Config.icons.use_short_names
5864 If this is enabled Squid will use short URLs for icons.
5865 If disabled it will revert to the old behavior of including
5866 it's own name and port in the URL.
5868 If you run a complex cache hierarchy with a mix of Squid and
5869 other proxies you may need to disable this directive.
5874 -----------------------------------------------------------------------------
5877 NAME: error_directory
5879 LOC: Config.errorDirectory
5882 If you wish to create your own versions of the default
5883 error files to customize them to suit your company copy
5884 the error/template files to another directory and point
5887 WARNING: This option will disable multi-language support
5888 on error pages if used.
5890 The squid developers are interested in making squid available in
5891 a wide variety of languages. If you are making translations for a
5892 language that Squid does not currently provide please consider
5893 contributing your translation back to the project.
5894 http://wiki.squid-cache.org/Translations
5896 The squid developers working on translations are happy to supply drop-in
5897 translated error files in exchange for any new language contributions.
5900 NAME: error_default_language
5901 IFDEF: USE_ERR_LOCALES
5903 LOC: Config.errorDefaultLanguage
5906 Set the default language which squid will send error pages in
5907 if no existing translation matches the clients language
5910 If unset (default) generic English will be used.
5912 The squid developers are interested in making squid available in
5913 a wide variety of languages. If you are interested in making
5914 translations for any language see the squid wiki for details.
5915 http://wiki.squid-cache.org/Translations
5918 NAME: error_log_languages
5919 IFDEF: USE_ERR_LOCALES
5921 LOC: Config.errorLogMissingLanguages
5924 Log to cache.log what languages users are attempting to
5925 auto-negotiate for translations.
5927 Successful negotiations are not logged. Only failures
5928 have meaning to indicate that Squid may need an upgrade
5929 of its error page translations.
5932 NAME: err_page_stylesheet
5934 LOC: Config.errorStylesheet
5935 DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
5937 CSS Stylesheet to pattern the display of Squid default error pages.
5939 For information on CSS see http://www.w3.org/Style/CSS/
5944 LOC: Config.errHtmlText
5947 HTML text to include in error messages. Make this a "mailto"
5948 URL to your admin address, or maybe just a link to your
5949 organizations Web page.
5951 To include this in your error messages, you must rewrite
5952 the error template files (found in the "errors" directory).
5953 Wherever you want the 'err_html_text' line to appear,
5954 insert a %L tag in the error template file.
5957 NAME: email_err_data
5960 LOC: Config.onoff.emailErrData
5963 If enabled, information about the occurred error will be
5964 included in the mailto links of the ERR pages (if %W is set)
5965 so that the email body contains the data.
5966 Syntax is <A HREF="mailto:%w%W">%w</A>
5971 LOC: Config.denyInfoList
5974 Usage: deny_info err_page_name acl
5975 or deny_info http://... acl
5976 or deny_info TCP_RESET acl
5978 This can be used to return a ERR_ page for requests which
5979 do not pass the 'http_access' rules. Squid remembers the last
5980 acl it evaluated in http_access, and if a 'deny_info' line exists
5981 for that ACL Squid returns a corresponding error page.
5983 The acl is typically the last acl on the http_access deny line which
5984 denied access. The exceptions to this rule are:
5985 - When Squid needs to request authentication credentials. It's then
5986 the first authentication related acl encountered
5987 - When none of the http_access lines matches. It's then the last
5988 acl processed on the last http_access line.
5989 - When the decision to deny access was made by an adaptation service,
5990 the acl name is the corresponding eCAP or ICAP service_name.
5992 NP: If providing your own custom error pages with error_directory
5993 you may also specify them by your custom file name:
5994 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
5996 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
5997 may be specified by prefixing the file name with the code and a colon.
5998 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
6000 Alternatively you can tell Squid to reset the TCP connection
6001 by specifying TCP_RESET.
6003 Or you can specify an error URL or URL pattern. The browsers will
6004 get redirected to the specified URL after formatting tags have
6005 been replaced. Redirect will be done with 302 or 307 according to
6006 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
6007 the URL. e.g. 303:http://example.com/
6010 %a - username (if available. Password NOT included)
6013 %E - Error description
6015 %H - Request domain name
6016 %i - Client IP Address
6018 %o - Message result from external ACL helper
6019 %p - Request Port number
6020 %P - Request Protocol name
6021 %R - Request URL path
6022 %T - Timestamp in RFC 1123 format
6023 %U - Full canonical URL from client
6024 (HTTPS URLs terminate with *)
6025 %u - Full canonical URL from client
6026 %w - Admin email from squid.conf
6028 %% - Literal percent (%) code
6033 OPTIONS INFLUENCING REQUEST FORWARDING
6034 -----------------------------------------------------------------------------
6037 NAME: nonhierarchical_direct
6039 LOC: Config.onoff.nonhierarchical_direct
6042 By default, Squid will send any non-hierarchical requests
6043 (matching hierarchy_stoplist or not cacheable request type) direct
6046 If you set this to off, Squid will prefer to send these
6047 requests to parents.
6049 Note that in most configurations, by turning this off you will only
6050 add latency to these request without any improvement in global hit
6053 If you are inside an firewall see never_direct instead of
6059 LOC: Config.onoff.prefer_direct
6062 Normally Squid tries to use parents for most requests. If you for some
6063 reason like it to first try going direct and only use a parent if
6064 going direct fails set this to on.
6066 By combining nonhierarchical_direct off and prefer_direct on you
6067 can set up Squid to use a parent as a backup path if going direct
6070 Note: If you want Squid to use parents for all requests see
6071 the never_direct directive. prefer_direct only modifies how Squid
6072 acts on cacheable requests.
6077 LOC: Config.accessList.AlwaysDirect
6080 Usage: always_direct allow|deny [!]aclname ...
6082 Here you can use ACL elements to specify requests which should
6083 ALWAYS be forwarded by Squid to the origin servers without using
6084 any peers. For example, to always directly forward requests for
6085 local servers ignoring any parents or siblings you may have use
6088 acl local-servers dstdomain my.domain.net
6089 always_direct allow local-servers
6091 To always forward FTP requests directly, use
6094 always_direct allow FTP
6096 NOTE: There is a similar, but opposite option named
6097 'never_direct'. You need to be aware that "always_direct deny
6098 foo" is NOT the same thing as "never_direct allow foo". You
6099 may need to use a deny rule to exclude a more-specific case of
6100 some other rule. Example:
6102 acl local-external dstdomain external.foo.net
6103 acl local-servers dstdomain .foo.net
6104 always_direct deny local-external
6105 always_direct allow local-servers
6107 NOTE: If your goal is to make the client forward the request
6108 directly to the origin server bypassing Squid then this needs
6109 to be done in the client configuration. Squid configuration
6110 can only tell Squid how Squid should fetch the object.
6112 NOTE: This directive is not related to caching. The replies
6113 is cached as usual even if you use always_direct. To not cache
6114 the replies see the 'cache' directive.
6116 This clause supports both fast and slow acl types.
6117 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6122 LOC: Config.accessList.NeverDirect
6125 Usage: never_direct allow|deny [!]aclname ...
6127 never_direct is the opposite of always_direct. Please read
6128 the description for always_direct if you have not already.
6130 With 'never_direct' you can use ACL elements to specify
6131 requests which should NEVER be forwarded directly to origin
6132 servers. For example, to force the use of a proxy for all
6133 requests, except those in your local domain use something like:
6135 acl local-servers dstdomain .foo.net
6136 never_direct deny local-servers
6137 never_direct allow all
6139 or if Squid is inside a firewall and there are local intranet
6140 servers inside the firewall use something like:
6142 acl local-intranet dstdomain .foo.net
6143 acl local-external dstdomain external.foo.net
6144 always_direct deny local-external
6145 always_direct allow local-intranet
6146 never_direct allow all
6148 This clause supports both fast and slow acl types.
6149 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6153 ADVANCED NETWORKING OPTIONS
6154 -----------------------------------------------------------------------------
6157 NAME: incoming_icp_average
6160 LOC: Config.comm_incoming.icp_average
6163 NAME: incoming_http_average
6166 LOC: Config.comm_incoming.http_average
6169 NAME: incoming_dns_average
6172 LOC: Config.comm_incoming.dns_average
6175 NAME: min_icp_poll_cnt
6178 LOC: Config.comm_incoming.icp_min_poll
6181 NAME: min_dns_poll_cnt
6184 LOC: Config.comm_incoming.dns_min_poll
6187 NAME: min_http_poll_cnt
6190 LOC: Config.comm_incoming.http_min_poll
6192 Heavy voodoo here. I can't even believe you are reading this.
6193 Are you crazy? Don't even think about adjusting these unless
6194 you understand the algorithms in comm_select.c first!
6200 LOC: Config.accept_filter
6204 The name of an accept(2) filter to install on Squid's
6205 listen socket(s). This feature is perhaps specific to
6206 FreeBSD and requires support in the kernel.
6208 The 'httpready' filter delays delivering new connections
6209 to Squid until a full HTTP request has been received.
6210 See the accf_http(9) man page for details.
6212 The 'dataready' filter delays delivering new connections
6213 to Squid until there is some data to process.
6214 See the accf_dataready(9) man page for details.
6218 The 'data' filter delays delivering of new connections
6219 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
6220 You may optionally specify a number of seconds to wait by
6221 'data=N' where N is the number of seconds. Defaults to 30
6222 if not specified. See the tcp(7) man page for details.
6225 accept_filter httpready
6230 NAME: client_ip_max_connections
6232 LOC: Config.client_ip_max_connections
6235 Set an absolute limit on the number of connections a single
6236 client IP can use. Any more than this and Squid will begin to drop
6237 new connections from the client until it closes some links.
6239 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
6240 connections from the client. For finer control use the ACL access controls.
6242 Requires client_db to be enabled (the default).
6244 WARNING: This may noticably slow down traffic received via external proxies
6245 or NAT devices and cause them to rebound error messages back to their clients.
6248 NAME: tcp_recv_bufsize
6252 LOC: Config.tcpRcvBufsz
6254 Size of receive buffer to set for TCP sockets. Probably just
6255 as easy to change your kernel's default. Set to zero to use
6256 the default buffer size.
6261 -----------------------------------------------------------------------------
6268 LOC: Adaptation::Icap::TheConfig.onoff
6271 If you want to enable the ICAP module support, set this to on.
6274 NAME: icap_connect_timeout
6277 LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
6280 This parameter specifies how long to wait for the TCP connect to
6281 the requested ICAP server to complete before giving up and either
6282 terminating the HTTP transaction or bypassing the failure.
6284 The default for optional services is peer_connect_timeout.
6285 The default for essential services is connect_timeout.
6286 If this option is explicitly set, its value applies to all services.
6289 NAME: icap_io_timeout
6293 LOC: Adaptation::Icap::TheConfig.io_timeout_raw
6296 This parameter specifies how long to wait for an I/O activity on
6297 an established, active ICAP connection before giving up and
6298 either terminating the HTTP transaction or bypassing the
6301 The default is read_timeout.
6304 NAME: icap_service_failure_limit
6305 COMMENT: limit [in memory-depth time-units]
6306 TYPE: icap_service_failure_limit
6308 LOC: Adaptation::Icap::TheConfig
6311 The limit specifies the number of failures that Squid tolerates
6312 when establishing a new TCP connection with an ICAP service. If
6313 the number of failures exceeds the limit, the ICAP service is
6314 not used for new ICAP requests until it is time to refresh its
6317 A negative value disables the limit. Without the limit, an ICAP
6318 service will not be considered down due to connectivity failures
6319 between ICAP OPTIONS requests.
6321 Squid forgets ICAP service failures older than the specified
6322 value of memory-depth. The memory fading algorithm
6323 is approximate because Squid does not remember individual
6324 errors but groups them instead, splitting the option
6325 value into ten time slots of equal length.
6327 When memory-depth is 0 and by default this option has no
6328 effect on service failure expiration.
6330 Squid always forgets failures when updating service settings
6331 using an ICAP OPTIONS transaction, regardless of this option
6335 # suspend service usage after 10 failures in 5 seconds:
6336 icap_service_failure_limit 10 in 5 seconds
6339 NAME: icap_service_revival_delay
6342 LOC: Adaptation::Icap::TheConfig.service_revival_delay
6345 The delay specifies the number of seconds to wait after an ICAP
6346 OPTIONS request failure before requesting the options again. The
6347 failed ICAP service is considered "down" until fresh OPTIONS are
6350 The actual delay cannot be smaller than the hardcoded minimum
6351 delay of 30 seconds.
6354 NAME: icap_preview_enable
6358 LOC: Adaptation::Icap::TheConfig.preview_enable
6361 The ICAP Preview feature allows the ICAP server to handle the
6362 HTTP message by looking only at the beginning of the message body
6363 or even without receiving the body at all. In some environments,
6364 previews greatly speedup ICAP processing.
6366 During an ICAP OPTIONS transaction, the server may tell Squid what
6367 HTTP messages should be previewed and how big the preview should be.
6368 Squid will not use Preview if the server did not request one.
6370 To disable ICAP Preview for all ICAP services, regardless of
6371 individual ICAP server OPTIONS responses, set this option to "off".
6373 icap_preview_enable off
6376 NAME: icap_preview_size
6379 LOC: Adaptation::Icap::TheConfig.preview_size
6382 The default size of preview data to be sent to the ICAP server.
6383 -1 means no preview. This value might be overwritten on a per server
6384 basis by OPTIONS requests.
6387 NAME: icap_206_enable
6391 LOC: Adaptation::Icap::TheConfig.allow206_enable
6394 206 (Partial Content) responses is an ICAP extension that allows the
6395 ICAP agents to optionally combine adapted and original HTTP message
6396 content. The decision to combine is postponed until the end of the
6397 ICAP response. Squid supports Partial Content extension by default.
6399 Activation of the Partial Content extension is negotiated with each
6400 ICAP service during OPTIONS exchange. Most ICAP servers should handle
6401 negotation correctly even if they do not support the extension, but
6402 some might fail. To disable Partial Content support for all ICAP
6403 services and to avoid any negotiation, set this option to "off".
6409 NAME: icap_default_options_ttl
6412 LOC: Adaptation::Icap::TheConfig.default_options_ttl
6415 The default TTL value for ICAP OPTIONS responses that don't have
6416 an Options-TTL header.
6419 NAME: icap_persistent_connections
6423 LOC: Adaptation::Icap::TheConfig.reuse_connections
6426 Whether or not Squid should use persistent connections to
6430 NAME: adaptation_send_client_ip icap_send_client_ip
6432 IFDEF: USE_ADAPTATION
6434 LOC: Adaptation::Config::send_client_ip
6437 If enabled, Squid shares HTTP client IP information with adaptation
6438 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests.
6439 For eCAP, Squid sets the libecap::metaClientIp transaction option.
6441 See also: adaptation_uses_indirect_client
6444 NAME: adaptation_send_username icap_send_client_username
6446 IFDEF: USE_ADAPTATION
6448 LOC: Adaptation::Config::send_username
6451 This sends authenticated HTTP client username (if available) to
6452 the adaptation service.
6454 For ICAP, the username value is encoded based on the
6455 icap_client_username_encode option and is sent using the header
6456 specified by the icap_client_username_header option.
6459 NAME: icap_client_username_header
6462 LOC: Adaptation::Icap::TheConfig.client_username_header
6463 DEFAULT: X-Client-Username
6465 ICAP request header name to use for adaptation_send_username.
6468 NAME: icap_client_username_encode
6472 LOC: Adaptation::Icap::TheConfig.client_username_encode
6475 Whether to base64 encode the authenticated client username.
6479 TYPE: icap_service_type
6481 LOC: Adaptation::Icap::TheConfig
6484 Defines a single ICAP service using the following format:
6486 icap_service service_name vectoring_point [options] service_url
6489 an opaque identifier which must be unique in squid.conf
6491 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
6492 This specifies at which point of transaction processing the
6493 ICAP service should be activated. *_postcache vectoring points
6494 are not yet supported.
6496 service_url: icap://servername:port/servicepath
6497 ICAP server and service location.
6499 ICAP does not allow a single service to handle both REQMOD and RESPMOD
6500 transactions. Squid does not enforce that requirement. You can specify
6501 services with the same service_url and different vectoring_points. You
6502 can even specify multiple identical services as long as their
6503 service_names differ.
6506 Service options are separated by white space. ICAP services support
6507 the following name=value options:
6510 If set to 'on' or '1', the ICAP service is treated as
6511 optional. If the service cannot be reached or malfunctions,
6512 Squid will try to ignore any errors and process the message as
6513 if the service was not enabled. No all ICAP errors can be
6514 bypassed. If set to 0, the ICAP service is treated as
6515 essential and all ICAP errors will result in an error page
6516 returned to the HTTP client.
6518 Bypass is off by default: services are treated as essential.
6521 If set to 'on' or '1', the ICAP service is allowed to
6522 dynamically change the current message adaptation plan by
6523 returning a chain of services to be used next. The services
6524 are specified using the X-Next-Services ICAP response header
6525 value, formatted as a comma-separated list of service names.
6526 Each named service should be configured in squid.conf and
6527 should have the same method and vectoring point as the current
6528 ICAP transaction. Services violating these rules are ignored.
6529 An empty X-Next-Services value results in an empty plan which
6530 ends the current adaptation.
6532 Routing is not allowed by default: the ICAP X-Next-Services
6533 response header is ignored.
6536 Only has effect on split-stack systems. The default on those systems
6537 is to use IPv4-only connections. When set to 'on' this option will
6538 make Squid use IPv6-only connections to contact this ICAP service.
6540 on-overload=block|bypass|wait|force
6541 If the service Max-Connections limit has been reached, do
6542 one of the following for each new ICAP transaction:
6543 * block: send an HTTP error response to the client
6544 * bypass: ignore the "over-connected" ICAP service
6545 * wait: wait (in a FIFO queue) for an ICAP connection slot
6546 * force: proceed, ignoring the Max-Connections limit
6548 In SMP mode with N workers, each worker assumes the service
6549 connection limit is Max-Connections/N, even though not all
6550 workers may use a given service.
6552 The default value is "bypass" if service is bypassable,
6553 otherwise it is set to "wait".
6557 Use the given number as the Max-Connections limit, regardless
6558 of the Max-Connections value given by the service, if any.
6560 Older icap_service format without optional named parameters is
6561 deprecated but supported for backward compatibility.
6564 icap_service svcBlocker reqmod_precache bypass=0 icap://icap1.mydomain.net:1344/reqmod
6565 icap_service svcLogger reqmod_precache routing=on icap://icap2.mydomain.net:1344/respmod
6569 TYPE: icap_class_type
6574 This deprecated option was documented to define an ICAP service
6575 chain, even though it actually defined a set of similar, redundant
6576 services, and the chains were not supported.
6578 To define a set of redundant services, please use the
6579 adaptation_service_set directive. For service chains, use
6580 adaptation_service_chain.
6584 TYPE: icap_access_type
6589 This option is deprecated. Please use adaptation_access, which
6590 has the same ICAP functionality, but comes with better
6591 documentation, and eCAP support.
6596 -----------------------------------------------------------------------------
6603 LOC: Adaptation::Ecap::TheConfig.onoff
6606 Controls whether eCAP support is enabled.
6610 TYPE: ecap_service_type
6612 LOC: Adaptation::Ecap::TheConfig
6615 Defines a single eCAP service
6617 ecap_service servicename vectoring_point bypass service_url
6619 vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
6620 This specifies at which point of transaction processing the
6621 eCAP service should be activated. *_postcache vectoring points
6622 are not yet supported.
6624 If set to 1, the eCAP service is treated as optional. If the
6625 service cannot be reached or malfunctions, Squid will try to
6626 ignore any errors and process the message as if the service
6627 was not enabled. No all eCAP errors can be bypassed.
6628 If set to 0, the eCAP service is treated as essential and all
6629 eCAP errors will result in an error page returned to the
6631 service_url = ecap://vendor/service_name?custom&cgi=style¶meters=optional
6634 ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block
6635 ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg
6638 NAME: loadable_modules
6640 IFDEF: USE_LOADABLE_MODULES
6641 LOC: Config.loadable_module_names
6644 Instructs Squid to load the specified dynamic module(s) or activate
6645 preloaded module(s).
6647 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
6651 MESSAGE ADAPTATION OPTIONS
6652 -----------------------------------------------------------------------------
6655 NAME: adaptation_service_set
6656 TYPE: adaptation_service_set_type
6657 IFDEF: USE_ADAPTATION
6662 Configures an ordered set of similar, redundant services. This is
6663 useful when hot standby or backup adaptation servers are available.
6665 adaptation_service_set set_name service_name1 service_name2 ...
6667 The named services are used in the set declaration order. The first
6668 applicable adaptation service from the set is used first. The next
6669 applicable service is tried if and only if the transaction with the
6670 previous service fails and the message waiting to be adapted is still
6673 When adaptation starts, broken services are ignored as if they were
6674 not a part of the set. A broken service is a down optional service.
6676 The services in a set must be attached to the same vectoring point
6677 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
6679 If all services in a set are optional then adaptation failures are
6680 bypassable. If all services in the set are essential, then a
6681 transaction failure with one service may still be retried using
6682 another service from the set, but when all services fail, the master
6683 transaction fails as well.
6685 A set may contain a mix of optional and essential services, but that
6686 is likely to lead to surprising results because broken services become
6687 ignored (see above), making previously bypassable failures fatal.
6688 Technically, it is the bypassability of the last failed service that
6691 See also: adaptation_access adaptation_service_chain
6694 adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
6695 adaptation service_set svcLogger loggerLocal loggerRemote
6698 NAME: adaptation_service_chain
6699 TYPE: adaptation_service_chain_type
6700 IFDEF: USE_ADAPTATION
6705 Configures a list of complementary services that will be applied
6706 one-by-one, forming an adaptation chain or pipeline. This is useful
6707 when Squid must perform different adaptations on the same message.
6709 adaptation_service_chain chain_name service_name1 svc_name2 ...
6711 The named services are used in the chain declaration order. The first
6712 applicable adaptation service from the chain is used first. The next
6713 applicable service is applied to the successful adaptation results of
6714 the previous service in the chain.
6716 When adaptation starts, broken services are ignored as if they were
6717 not a part of the chain. A broken service is a down optional service.
6719 Request satisfaction terminates the adaptation chain because Squid
6720 does not currently allow declaration of RESPMOD services at the
6721 "reqmod_precache" vectoring point (see icap_service or ecap_service).
6723 The services in a chain must be attached to the same vectoring point
6724 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
6726 A chain may contain a mix of optional and essential services. If an
6727 essential adaptation fails (or the failure cannot be bypassed for
6728 other reasons), the master transaction fails. Otherwise, the failure
6729 is bypassed as if the failed adaptation service was not in the chain.
6731 See also: adaptation_access adaptation_service_set
6734 adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
6737 NAME: adaptation_access
6738 TYPE: adaptation_access_type
6739 IFDEF: USE_ADAPTATION
6743 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
6745 adaptation_access service_name allow|deny [!]aclname...
6746 adaptation_access set_name allow|deny [!]aclname...
6748 At each supported vectoring point, the adaptation_access
6749 statements are processed in the order they appear in this
6750 configuration file. Statements pointing to the following services
6751 are ignored (i.e., skipped without checking their ACL):
6753 - services serving different vectoring points
6754 - "broken-but-bypassable" services
6755 - "up" services configured to ignore such transactions
6756 (e.g., based on the ICAP Transfer-Ignore header).
6758 When a set_name is used, all services in the set are checked
6759 using the same rules, to find the first applicable one. See
6760 adaptation_service_set for details.
6762 If an access list is checked and there is a match, the
6763 processing stops: For an "allow" rule, the corresponding
6764 adaptation service is used for the transaction. For a "deny"
6765 rule, no adaptation service is activated.
6767 It is currently not possible to apply more than one adaptation
6768 service at the same vectoring point to the same HTTP transaction.
6770 See also: icap_service and ecap_service
6773 adaptation_access service_1 allow all
6776 NAME: adaptation_service_iteration_limit
6778 IFDEF: USE_ADAPTATION
6779 LOC: Adaptation::Config::service_iteration_limit
6782 Limits the number of iterations allowed when applying adaptation
6783 services to a message. If your longest adaptation set or chain
6784 may have more than 16 services, increase the limit beyond its
6785 default value of 16. If detecting infinite iteration loops sooner
6786 is critical, make the iteration limit match the actual number
6787 of services in your longest adaptation set or chain.
6789 Infinite adaptation loops are most likely with routing services.
6791 See also: icap_service routing=1
6794 NAME: adaptation_masterx_shared_names
6796 IFDEF: USE_ADAPTATION
6797 LOC: Adaptation::Config::masterx_shared_name
6800 For each master transaction (i.e., the HTTP request and response
6801 sequence, including all related ICAP and eCAP exchanges), Squid
6802 maintains a table of metadata. The table entries are (name, value)
6803 pairs shared among eCAP and ICAP exchanges. The table is destroyed
6804 with the master transaction.
6806 This option specifies the table entry names that Squid must accept
6807 from and forward to the adaptation transactions.
6809 An ICAP REQMOD or RESPMOD transaction may set an entry in the
6810 shared table by returning an ICAP header field with a name
6811 specified in adaptation_masterx_shared_names.
6813 An eCAP REQMOD or RESPMOD transaction may set an entry in the
6814 shared table by implementing the libecap::visitEachOption() API
6815 to provide an option with a name specified in
6816 adaptation_masterx_shared_names.
6818 Squid will store and forward the set entry to subsequent adaptation
6819 transactions within the same master transaction scope.
6821 Only one shared entry name is supported at this time.
6824 # share authentication information among ICAP services
6825 adaptation_masterx_shared_names X-Subscriber-ID
6831 LOC: Adaptation::Icap::TheConfig.repeat
6832 DEFAULT_IF_NONE: deny all
6834 This ACL determines which retriable ICAP transactions are
6835 retried. Transactions that received a complete ICAP response
6836 and did not have to consume or produce HTTP bodies to receive
6837 that response are usually retriable.
6839 icap_retry allow|deny [!]aclname ...
6841 Squid automatically retries some ICAP I/O timeouts and errors
6842 due to persistent connection race conditions.
6844 See also: icap_retry_limit
6847 NAME: icap_retry_limit
6850 LOC: Adaptation::Icap::TheConfig.repeat_limit
6853 Limits the number of retries allowed. When set to zero (default),
6854 no retries are allowed.
6856 Communication errors due to persistent connection race
6857 conditions are unavoidable, automatically retried, and do not
6858 count against this limit.
6860 See also: icap_retry
6866 -----------------------------------------------------------------------------
6869 NAME: check_hostnames
6872 LOC: Config.onoff.check_hostnames
6874 For security and stability reasons Squid can check
6875 hostnames for Internet standard RFC compliance. If you want
6876 Squid to perform these checks turn this directive on.
6879 NAME: allow_underscore
6882 LOC: Config.onoff.allow_underscore
6884 Underscore characters is not strictly allowed in Internet hostnames
6885 but nevertheless used by many sites. Set this to off if you want
6886 Squid to be strict about the standard.
6887 This check is performed only when check_hostnames is set to on.
6890 NAME: cache_dns_program
6892 IFDEF: USE_DNSSERVERS
6893 DEFAULT: @DEFAULT_DNSSERVER@
6894 LOC: Config.Program.dnsserver
6896 Specify the location of the executable for dnslookup process.
6900 TYPE: HelperChildConfig
6901 IFDEF: USE_DNSSERVERS
6902 DEFAULT: 32 startup=1 idle=1
6903 LOC: Config.dnsChildren
6905 The maximum number of processes spawn to service DNS name lookups.
6906 If you limit it too few Squid will have to wait for them to process
6907 a backlog of requests, slowing it down. If you allow too many they
6908 will use RAM and other system resources noticably.
6909 The maximum this may be safely set to is 32.
6911 The startup= and idle= options allow some measure of skew in your
6916 Sets a minimum of how many processes are to be spawned when Squid
6917 starts or reconfigures. When set to zero the first request will
6918 cause spawning of the first child process to handle it.
6920 Starting too few will cause an initial slowdown in traffic as Squid
6921 attempts to simultaneously spawn enough processes to cope.
6925 Sets a minimum of how many processes Squid is to try and keep available
6926 at all times. When traffic begins to rise above what the existing
6927 processes can handle this many more will be spawned up to the maximum
6928 configured. A minimum setting of 1 is required.
6931 NAME: dns_retransmit_interval
6934 LOC: Config.Timeout.idns_retransmit
6935 IFDEF: !USE_DNSSERVERS
6937 Initial retransmit interval for DNS queries. The interval is
6938 doubled each time all configured DNS servers have been tried.
6944 LOC: Config.Timeout.idns_query
6945 IFDEF: !USE_DNSSERVERS
6947 DNS Query timeout. If no response is received to a DNS query
6948 within this time all DNS servers for the queried domain
6949 are assumed to be unavailable.
6952 NAME: dns_packet_max
6955 LOC: Config.dns.packet_max
6956 IFDEF: !USE_DNSSERVERS
6958 Maximum number of bytes packet size to advertise via EDNS.
6959 Set to "none" to disable EDNS large packet support.
6961 For legacy reasons DNS UDP replies will default to 512 bytes which
6962 is too small for many responses. EDNS provides a means for Squid to
6963 negotiate receiving larger responses back immediately without having
6964 to failover with repeat requests. Responses larger than this limit
6965 will retain the old behaviour of failover to TCP DNS.
6967 Squid has no real fixed limit internally, but allowing packet sizes
6968 over 1500 bytes requires network jumbogram support and is usually not
6971 WARNING: The RFC also indicates that some older resolvers will reply
6972 with failure of the whole request if the extension is added. Some
6973 resolvers have already been identified which will reply with mangled
6974 EDNS response on occasion. Usually in response to many-KB jumbogram
6975 sizes being advertised by Squid.
6976 Squid will currently treat these both as an unable-to-resolve domain
6977 even if it would be resolvable without EDNS.
6984 LOC: Config.onoff.res_defnames
6986 Normally the RES_DEFNAMES resolver option is disabled
6987 (see res_init(3)). This prevents caches in a hierarchy
6988 from interpreting single-component hostnames locally. To allow
6989 Squid to handle single-component names, enable this option.
6992 NAME: dns_nameservers
6995 LOC: Config.dns_nameservers
6997 Use this if you want to specify a list of DNS name servers
6998 (IP addresses) to use instead of those given in your
6999 /etc/resolv.conf file.
7000 On Windows platforms, if no value is specified here or in
7001 the /etc/resolv.conf file, the list of DNS name servers are
7002 taken from the Windows registry, both static and dynamic DHCP
7003 configurations are supported.
7005 Example: dns_nameservers 10.0.0.1 192.172.0.4
7010 DEFAULT: @DEFAULT_HOSTS@
7011 LOC: Config.etcHostsPath
7013 Location of the host-local IP name-address associations
7014 database. Most Operating Systems have such a file on different
7016 - Un*X & Linux: /etc/hosts
7017 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
7018 (%SystemRoot% value install default is c:\winnt)
7019 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
7020 (%SystemRoot% value install default is c:\windows)
7021 - Windows 9x/Me: %windir%\hosts
7022 (%windir% value is usually c:\windows)
7023 - Cygwin: /etc/hosts
7025 The file contains newline-separated definitions, in the
7026 form ip_address_in_dotted_form name [name ...] names are
7027 whitespace-separated. Lines beginning with an hash (#)
7028 character are comments.
7030 The file is checked at startup and upon configuration.
7031 If set to 'none', it won't be checked.
7032 If append_domain is used, that domain will be added to
7033 domain-local (i.e. not containing any dot character) host
7039 LOC: Config.appendDomain
7042 Appends local domain name to hostnames without any dots in
7043 them. append_domain must begin with a period.
7045 Be warned there are now Internet names with no dots in
7046 them using only top-domain names, so setting this may
7047 cause some Internet sites to become unavailable.
7050 append_domain .yourdomain.com
7053 NAME: ignore_unknown_nameservers
7055 LOC: Config.onoff.ignore_unknown_nameservers
7058 By default Squid checks that DNS responses are received
7059 from the same IP addresses they are sent to. If they
7060 don't match, Squid ignores the response and writes a warning
7061 message to cache.log. You can allow responses from unknown
7062 nameservers by setting this option to 'off'.
7065 NAME: dns_v4_fallback
7068 LOC: Config.onoff.dns_require_A
7070 Standard practice with DNS is to lookup either A or AAAA records
7071 and use the results if it succeeds. Only looking up the other if
7072 the first attempt fails or otherwise produces no results.
7074 That policy however will cause squid to produce error pages for some
7075 servers that advertise AAAA but are unreachable over IPv6.
7077 If this is ON squid will always lookup both AAAA and A, using both.
7078 If this is OFF squid will lookup AAAA and only try A if none found.
7080 WARNING: There are some possibly unwanted side-effects with this on:
7081 *) Doubles the load placed by squid on the DNS network.
7082 *) May negatively impact connection delay times.
7086 COMMENT: (number of entries)
7089 LOC: Config.ipcache.size
7096 LOC: Config.ipcache.low
7103 LOC: Config.ipcache.high
7105 The size, low-, and high-water marks for the IP cache.
7108 NAME: fqdncache_size
7109 COMMENT: (number of entries)
7112 LOC: Config.fqdncache.size
7114 Maximum number of FQDN cache entries.
7119 -----------------------------------------------------------------------------
7126 LOC: Config.onoff.mem_pools
7128 If set, Squid will keep pools of allocated (but unused) memory
7129 available for future use. If memory is a premium on your
7130 system and you believe your malloc library outperforms Squid
7131 routines, disable this.
7134 NAME: memory_pools_limit
7138 LOC: Config.MemPools.limit
7140 Used only with memory_pools on:
7141 memory_pools_limit 50 MB
7143 If set to a non-zero value, Squid will keep at most the specified
7144 limit of allocated (but unused) memory in memory pools. All free()
7145 requests that exceed this limit will be handled by your malloc
7146 library. Squid does not pre-allocate any memory, just safe-keeps
7147 objects that otherwise would be free()d. Thus, it is safe to set
7148 memory_pools_limit to a reasonably high value even if your
7149 configuration will use less memory.
7151 If set to none, Squid will keep all memory it can. That is, there
7152 will be no limit on the total amount of memory used for safe-keeping.
7154 To disable memory allocation optimization, do not set
7155 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
7157 An overhead for maintaining memory pools is not taken into account
7158 when the limit is checked. This overhead is close to four bytes per
7159 object kept. However, pools may actually _save_ memory because of
7160 reduced memory thrashing in your malloc library.
7164 COMMENT: on|off|transparent|truncate|delete
7167 LOC: opt_forwarded_for
7169 If set to "on", Squid will append your client's IP address
7170 in the HTTP requests it forwards. By default it looks like:
7172 X-Forwarded-For: 192.1.2.3
7174 If set to "off", it will appear as
7176 X-Forwarded-For: unknown
7178 If set to "transparent", Squid will not alter the
7179 X-Forwarded-For header in any way.
7181 If set to "delete", Squid will delete the entire
7182 X-Forwarded-For header.
7184 If set to "truncate", Squid will remove all existing
7185 X-Forwarded-For entries, and place the client IP as the sole entry.
7188 NAME: cachemgr_passwd
7189 TYPE: cachemgrpasswd
7191 LOC: Config.passwd_list
7193 Specify passwords for cachemgr operations.
7195 Usage: cachemgr_passwd password action action ...
7197 Some valid actions are (see cache manager menu for a full list):
7237 * Indicates actions which will not be performed without a
7238 valid password, others can be performed if not listed here.
7240 To disable an action, set the password to "disable".
7241 To allow performing an action without a password, set the
7244 Use the keyword "all" to set the same password for all actions.
7247 cachemgr_passwd secret shutdown
7248 cachemgr_passwd lesssssssecret info stats/objects
7249 cachemgr_passwd disable all
7256 LOC: Config.onoff.client_db
7258 If you want to disable collecting per-client statistics,
7259 turn off client_db here.
7262 NAME: refresh_all_ims
7266 LOC: Config.onoff.refresh_all_ims
7268 When you enable this option, squid will always check
7269 the origin server for an update when a client sends an
7270 If-Modified-Since request. Many browsers use IMS
7271 requests when the user requests a reload, and this
7272 ensures those clients receive the latest version.
7274 By default (off), squid may return a Not Modified response
7275 based on the age of the cached version.
7278 NAME: reload_into_ims
7279 IFDEF: USE_HTTP_VIOLATIONS
7283 LOC: Config.onoff.reload_into_ims
7285 When you enable this option, client no-cache or ``reload''
7286 requests will be changed to If-Modified-Since requests.
7287 Doing this VIOLATES the HTTP standard. Enabling this
7288 feature could make you liable for problems which it
7291 see also refresh_pattern for a more selective approach.
7294 NAME: connect_retries
7296 LOC: Config.connect_retries
7299 This sets the maximum number of connection attempts made for each
7300 TCP connection. The connect_retries attempts must all still
7301 complete within the connection timeout period.
7303 The default is not to re-try if the first connection attempt fails.
7304 The (not recommended) maximum is 10 tries.
7306 A warning message will be generated if it is set to a too-high
7307 value and the configured value will be over-ridden.
7309 Note: These re-tries are in addition to forward_max_tries
7310 which limit how many different addresses may be tried to find
7314 NAME: retry_on_error
7316 LOC: Config.retry.onerror
7319 If set to on Squid will automatically retry requests when
7320 receiving an error response. This is mainly useful if you
7321 are in a complex cache hierarchy to work around access
7325 NAME: as_whois_server
7327 LOC: Config.as_whois_server
7328 DEFAULT: whois.ra.net
7330 WHOIS server to query for AS numbers. NOTE: AS numbers are
7331 queried only when Squid starts up, not for every request.
7336 LOC: Config.onoff.offline
7339 Enable this option and Squid will never try to validate cached
7343 NAME: uri_whitespace
7344 TYPE: uri_whitespace
7345 LOC: Config.uri_whitespace
7348 What to do with requests that have whitespace characters in the
7351 strip: The whitespace characters are stripped out of the URL.
7352 This is the behavior recommended by RFC2396.
7353 deny: The request is denied. The user receives an "Invalid
7355 allow: The request is allowed and the URI is not changed. The
7356 whitespace characters remain in the URI. Note the
7357 whitespace is passed to redirector processes if they
7359 encode: The request is allowed and the whitespace characters are
7360 encoded according to RFC1738. This could be considered
7361 a violation of the HTTP/1.1
7362 RFC because proxies are not allowed to rewrite URI's.
7363 chop: The request is allowed and the URI is chopped at the
7364 first whitespace. This might also be considered a
7370 LOC: Config.chroot_dir
7373 Specifies a directory where Squid should do a chroot() while
7374 initializing. This also causes Squid to fully drop root
7375 privileges after initializing. This means, for example, if you
7376 use a HTTP port less than 1024 and try to reconfigure, you may
7377 get an error saying that Squid can not open the port.
7380 NAME: balance_on_multiple_ip
7382 LOC: Config.onoff.balance_on_multiple_ip
7385 Modern IP resolvers in squid sort lookup results by preferred access.
7386 By default squid will use these IP in order and only rotates to
7387 the next listed when the most preffered fails.
7389 Some load balancing servers based on round robin DNS have been
7390 found not to preserve user session state across requests
7391 to different IP addresses.
7393 Enabling this directive Squid rotates IP's per request.
7396 NAME: pipeline_prefetch
7398 LOC: Config.onoff.pipeline_prefetch
7401 To boost the performance of pipelined requests to closer
7402 match that of a non-proxied environment Squid can try to fetch
7403 up to two requests in parallel from a pipeline.
7405 Defaults to off for bandwidth management and access logging
7408 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication.
7411 NAME: high_response_time_warning
7414 LOC: Config.warnings.high_rptm
7417 If the one-minute median response time exceeds this value,
7418 Squid prints a WARNING with debug level 0 to get the
7419 administrators attention. The value is in milliseconds.
7422 NAME: high_page_fault_warning
7424 LOC: Config.warnings.high_pf
7427 If the one-minute average page fault rate exceeds this
7428 value, Squid prints a WARNING with debug level 0 to get
7429 the administrators attention. The value is in page faults
7433 NAME: high_memory_warning
7435 LOC: Config.warnings.high_memory
7438 If the memory usage (as determined by mallinfo) exceeds
7439 this amount, Squid prints a WARNING with debug level 0 to get
7440 the administrators attention.
7443 NAME: sleep_after_fork
7444 COMMENT: (microseconds)
7446 LOC: Config.sleep_after_fork
7449 When this is set to a non-zero value, the main Squid process
7450 sleeps the specified number of microseconds after a fork()
7451 system call. This sleep may help the situation where your
7452 system reports fork() failures due to lack of (virtual)
7453 memory. Note, however, if you have a lot of child
7454 processes, these sleep delays will add up and your
7455 Squid will not service requests for some amount of time
7456 until all the child processes have been started.
7457 On Windows value less then 1000 (1 milliseconds) are
7461 NAME: windows_ipaddrchangemonitor
7462 IFDEF: _SQUID_MSWIN_
7466 LOC: Config.onoff.WIN32_IpAddrChangeMonitor
7468 On Windows Squid by default will monitor IP address changes and will
7469 reconfigure itself after any detected event. This is very useful for
7470 proxies connected to internet with dial-up interfaces.
7471 In some cases (a Proxy server acting as VPN gateway is one) it could be
7472 desiderable to disable this behaviour setting this to 'off'.
7473 Note: after changing this, Squid service must be restarted.
7478 IFDEF: USE_SQUID_EUI
7480 LOC: Eui::TheConfig.euiLookup
7482 Whether to lookup the EUI or MAC address of a connected client.
7485 NAME: max_filedescriptors max_filedesc
7488 LOC: Config.max_filedescriptors
7490 The maximum number of filedescriptors supported.
7492 The default "0" means Squid inherits the current ulimit setting.
7494 Note: Changing this requires a restart of Squid. Also
7495 not all comm loops supports large values.
7503 Number of main Squid processes or "workers" to fork and maintain.
7504 0: "no daemon" mode, like running "squid -N ..."
7505 1: "no SMP" mode, start one main Squid process daemon (default)
7506 N: start N main Squid process daemons (i.e., SMP mode)
7508 In SMP mode, each worker does nearly all what a single Squid daemon
7509 does (e.g., listen on http_port and forward HTTP requests).
7512 NAME: cpu_affinity_map
7513 TYPE: CpuAffinityMap
7514 LOC: Config.cpuAffinityMap
7517 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
7519 Sets 1:1 mapping between Squid processes and CPU cores. For example,
7521 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
7523 affects processes 1 through 4 only and places them on the first
7524 four even cores, starting with core #1.
7526 CPU cores are numbered starting from 1. Requires support for
7527 sched_getaffinity(2) and sched_setaffinity(2) system calls.
7529 Multiple cpu_affinity_map options are merged.