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 -----------------------------------------------------------------------------
178 This is used to define parameters for the various authentication
179 schemes supported by Squid.
181 format: auth_param scheme parameter [setting]
183 The order in which authentication schemes are presented to the client is
184 dependent on the order the scheme first appears in config file. IE
185 has a bug (it's not RFC 2617 compliant) in that it will use the basic
186 scheme if basic is the first entry presented, even if more secure
187 schemes are presented. For now use the order in the recommended
188 settings section below. If other browsers have difficulties (don't
189 recognize the schemes offered even if you are using basic) either
190 put basic first, or disable the other schemes (by commenting out their
193 Once an authentication scheme is fully configured, it can only be
194 shutdown by shutting squid down and restarting. Changes can be made on
195 the fly and activated with a reconfigure. I.E. You can change to a
196 different helper, but not unconfigure the helper completely.
198 Please note that while this directive defines how Squid processes
199 authentication it does not automatically activate authentication.
200 To use authentication you must in addition make use of ACLs based
201 on login name in http_access (proxy_auth, proxy_auth_regex or
202 external with %LOGIN used in the format tag). The browser will be
203 challenged for authentication on the first such acl encountered
204 in http_access processing and will also be re-challenged for new
205 login credentials if the request is being denied by a proxy_auth
208 WARNING: authentication can't be used in a transparently intercepting
209 proxy as the client then thinks it is talking to an origin server and
210 not the proxy. This is a limitation of bending the TCP/IP protocol to
211 transparently intercepting port 80, not a limitation in Squid.
212 Ports flagged 'transparent', 'intercept', or 'tproxy' have
213 authentication disabled.
215 === Parameters for the basic scheme follow. ===
218 Specify the command for the external authenticator. Such a program
219 reads a line containing "username password" and replies "OK" or
220 "ERR" in an endless loop. "ERR" responses may optionally be followed
221 by a error description available as %m in the returned error page.
222 If you use an authenticator, make sure you have 1 acl of type
225 By default, the basic authentication scheme is not used unless a
226 program is specified.
228 If you want to use the traditional NCSA proxy authentication, set
229 this line to something like
231 auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
234 HTTP uses iso-latin-1 as characterset, while some authentication
235 backends such as LDAP expects UTF-8. If this is set to on Squid will
236 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
237 username & password to the helper.
239 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
240 The maximum number of authenticator processes to spawn. If you start too few
241 Squid will have to wait for them to process a backlog of credential
242 verifications, slowing it down. When password verifications are
243 done via a (slow) network you are likely to need lots of
244 authenticator processes.
246 The startup= and idle= options permit some skew in the exact amount
247 run. A minimum of startup=N will begin during startup and reconfigure.
248 Squid will start more in groups of up to idle=N in an attempt to meet
249 traffic needs and to keep idle=N free above those traffic needs up to
252 The concurrency= option sets the number of concurrent requests the
253 helper can process. The default of 0 is used for helpers who only
254 supports one request at a time. Setting this to a number greater than
255 0 changes the protocol used to include a channel number first on the
256 request/response line, allowing multiple requests to be sent to the
257 same helper in parallell without wating for the response.
258 Must not be set unless it's known the helper supports this.
260 auth_param basic children 20 startup=0 idle=1
263 Specifies the realm name which is to be reported to the
264 client for the basic proxy authentication scheme (part of
265 the text the user will see when prompted their username and
266 password). There is no default.
267 auth_param basic realm Squid proxy-caching web server
269 "credentialsttl" timetolive
270 Specifies how long squid assumes an externally validated
271 username:password pair is valid for - in other words how
272 often the helper program is called for that user. Set this
273 low to force revalidation with short lived passwords. Note
274 setting this high does not impact your susceptibility
275 to replay attacks unless you are using an one-time password
276 system (such as SecureID). If you are using such a system,
277 you will be vulnerable to replay attacks unless you also
278 use the max_user_ip ACL in an http_access rule.
280 "casesensitive" on|off
281 Specifies if usernames are case sensitive. Most user databases are
282 case insensitive allowing the same username to be spelled using both
283 lower and upper case letters, but some are case sensitive. This
284 makes a big difference for user_max_ip ACL processing and similar.
285 auth_param basic casesensitive off
287 === Parameters for the digest scheme follow ===
290 Specify the command for the external authenticator. Such
291 a program reads a line containing "username":"realm" and
292 replies with the appropriate H(A1) value hex encoded or
293 ERR if the user (or his H(A1) hash) does not exists.
294 See rfc 2616 for the definition of H(A1).
295 "ERR" responses may optionally be followed by a error description
296 available as %m in the returned error page.
298 By default, the digest authentication scheme is not used unless a
299 program is specified.
301 If you want to use a digest authenticator, set this line to
304 auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass
307 HTTP uses iso-latin-1 as characterset, while some authentication
308 backends such as LDAP expects UTF-8. If this is set to on Squid will
309 translate the HTTP iso-latin-1 charset to UTF-8 before sending the
310 username & password to the helper.
312 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
313 The maximum number of authenticator processes to spawn (default 5).
314 If you start too few Squid will have to wait for them to
315 process a backlog of H(A1) calculations, slowing it down.
316 When the H(A1) calculations are done via a (slow) network
317 you are likely to need lots of authenticator processes.
319 The startup= and idle= options permit some skew in the exact amount
320 run. A minimum of startup=N will begin during startup and reconfigure.
321 Squid will start more in groups of up to idle=N in an attempt to meet
322 traffic needs and to keep idle=N free above those traffic needs up to
325 The concurrency= option sets the number of concurrent requests the
326 helper can process. The default of 0 is used for helpers who only
327 supports one request at a time. Setting this to a number greater than
328 0 changes the protocol used to include a channel number first on the
329 request/response line, allowing multiple requests to be sent to the
330 same helper in parallell without wating for the response.
331 Must not be set unless it's known the helper supports this.
333 auth_param digest children 20 startup=0 idle=1
336 Specifies the realm name which is to be reported to the
337 client for the digest proxy authentication scheme (part of
338 the text the user will see when prompted their username and
339 password). There is no default.
340 auth_param digest realm Squid proxy-caching web server
342 "nonce_garbage_interval" timeinterval
343 Specifies the interval that nonces that have been issued
344 to client_agent's are checked for validity.
346 "nonce_max_duration" timeinterval
347 Specifies the maximum length of time a given nonce will be
350 "nonce_max_count" number
351 Specifies the maximum number of times a given nonce can be
354 "nonce_strictness" on|off
355 Determines if squid requires strict increment-by-1 behavior
356 for nonce counts, or just incrementing (off - for use when
357 useragents generate nonce counts that occasionally miss 1
358 (ie, 1,2,4,6)). Default off.
360 "check_nonce_count" on|off
361 This directive if set to off can disable the nonce count check
362 completely to work around buggy digest qop implementations in
363 certain mainstream browser versions. Default on to check the
364 nonce count to protect from authentication replay attacks.
366 "post_workaround" on|off
367 This is a workaround to certain buggy browsers who sends
368 an incorrect request digest in POST requests when reusing
369 the same nonce as acquired earlier on a GET request.
371 === NTLM scheme options follow ===
374 Specify the command for the external NTLM authenticator.
375 Such a program reads exchanged NTLMSSP packets with
376 the browser via Squid until authentication is completed.
377 If you use an NTLM authenticator, make sure you have 1 acl
378 of type proxy_auth. By default, the NTLM authenticator_program
381 auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
383 "children" numberofchildren [startup=N] [idle=N]
384 The maximum number of authenticator processes to spawn (default 5).
385 If you start too few Squid will have to wait for them to
386 process a backlog of credential verifications, slowing it
387 down. When credential verifications are done via a (slow)
388 network you are likely to need lots of authenticator
391 The startup= and idle= options permit some skew in the exact amount
392 run. A minimum of startup=N will begin during startup and reconfigure.
393 Squid will start more in groups of up to idle=N in an attempt to meet
394 traffic needs and to keep idle=N free above those traffic needs up to
397 auth_param ntlm children 20 startup=0 idle=1
400 If you experience problems with PUT/POST requests when using the
401 Negotiate authentication scheme then you can try setting this to
402 off. This will cause Squid to forcibly close the connection on
403 the initial requests where the browser asks which schemes are
404 supported by the proxy.
406 auth_param ntlm keep_alive on
408 === Options for configuring the NEGOTIATE auth-scheme follow ===
411 Specify the command for the external Negotiate authenticator.
412 This protocol is used in Microsoft Active-Directory enabled setups with
413 the Microsoft Internet Explorer or Mozilla Firefox browsers.
414 Its main purpose is to exchange credentials with the Squid proxy
415 using the Kerberos mechanisms.
416 If you use a Negotiate authenticator, make sure you have at least
417 one acl of type proxy_auth active. By default, the negotiate
418 authenticator_program is not used.
419 The only supported program for this role is the ntlm_auth
420 program distributed as part of Samba, version 4 or later.
422 auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
424 "children" numberofchildren [startup=N] [idle=N]
425 The maximum number of authenticator processes to spawn (default 5).
426 If you start too few Squid will have to wait for them to
427 process a backlog of credential verifications, slowing it
428 down. When crendential verifications are done via a (slow)
429 network you are likely to need lots of authenticator
432 The startup= and idle= options permit some skew in the exact amount
433 run. A minimum of startup=N will begin during startup and reconfigure.
434 Squid will start more in groups of up to idle=N in an attempt to meet
435 traffic needs and to keep idle=N free above those traffic needs up to
438 auth_param negotiate children 20 startup=0 idle=1
441 If you experience problems with PUT/POST requests when using the
442 Negotiate authentication scheme then you can try setting this to
443 off. This will cause Squid to forcibly close the connection on
444 the initial requests where the browser asks which schemes are
445 supported by the proxy.
447 auth_param negotiate keep_alive on
452 #Recommended minimum configuration per scheme:
453 #auth_param negotiate program <uncomment and complete this line to activate>
454 #auth_param negotiate children 20 startup=0 idle=1
455 #auth_param negotiate keep_alive on
457 #auth_param ntlm program <uncomment and complete this line to activate>
458 #auth_param ntlm children 20 startup=0 idle=1
459 #auth_param ntlm keep_alive on
461 #auth_param digest program <uncomment and complete this line>
462 #auth_param digest children 20 startup=0 idle=1
463 #auth_param digest realm Squid proxy-caching web server
464 #auth_param digest nonce_garbage_interval 5 minutes
465 #auth_param digest nonce_max_duration 30 minutes
466 #auth_param digest nonce_max_count 50
468 #auth_param basic program <uncomment and complete this line>
469 #auth_param basic children 5 startup=5 idle=1
470 #auth_param basic realm Squid proxy-caching web server
471 #auth_param basic credentialsttl 2 hours
474 NAME: authenticate_cache_garbage_interval
477 LOC: Config.authenticateGCInterval
479 The time period between garbage collection across the username cache.
480 This is a tradeoff between memory utilization (long intervals - say
481 2 days) and CPU (short intervals - say 1 minute). Only change if you
485 NAME: authenticate_ttl
488 LOC: Config.authenticateTTL
490 The time a user & their credentials stay in the logged in
491 user cache since their last request. When the garbage
492 interval passes, all user credentials that have passed their
493 TTL are removed from memory.
496 NAME: authenticate_ip_ttl
498 LOC: Config.authenticateIpTTL
501 If you use proxy authentication and the 'max_user_ip' ACL,
502 this directive controls how long Squid remembers the IP
503 addresses associated with each user. Use a small value
504 (e.g., 60 seconds) if your users might change addresses
505 quickly, as is the case with dialups. You might be safe
506 using a larger value (e.g., 2 hours) in a corporate LAN
507 environment with relatively static address assignments.
512 -----------------------------------------------------------------------------
515 NAME: external_acl_type
516 TYPE: externalAclHelper
517 LOC: Config.externalAclHelperList
520 This option defines external acl classes using a helper program
521 to look up the status
523 external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
527 ttl=n TTL in seconds for cached results (defaults to 3600
530 TTL for cached negative lookups (default same
533 Maximum number of acl helper processes spawned to service
534 external acl lookups of this type. (default 20)
536 Minimum number of acl helper processes to spawn during
537 startup and reconfigure to service external acl lookups
538 of this type. (default 0)
540 Number of acl helper processes to keep ahead of traffic
541 loads. Squid will spawn this many at once whenever load
542 rises above the capabilities of existing processes.
543 Up to the value of children-max. (default 1)
544 concurrency=n concurrency level per process. Only used with helpers
545 capable of processing more than one query at a time.
546 cache=n limit the result cache size, default is unbounded.
547 grace=n Percentage remaining of TTL where a refresh of a
548 cached entry should be initiated without needing to
549 wait for a new reply. (default is for no grace period)
550 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
551 ipv4 / ipv6 IP-mode used to communicate to this helper.
552 For compatability with older configurations and helpers
553 the default is currently 'ipv4'.
555 FORMAT specifications
557 %LOGIN Authenticated user login name
558 %EXT_USER Username from external acl
559 %IDENT Ident user name
561 %SRCPORT Client source port
564 %PROTO Requested protocol
566 %PATH Requested URL path
567 %METHOD Request method
568 %MYADDR Squid interface address
569 %MYPORT Squid http_port number
570 %PATH Requested URL-path (including query-string if any)
571 %USER_CERT SSL User certificate in PEM format
572 %USER_CERTCHAIN SSL User certificate chain in PEM format
573 %USER_CERT_xx SSL User certificate subject attribute xx
574 %USER_CA_xx SSL User certificate issuer attribute xx
576 %>{Header} HTTP request header "Header"
578 HTTP request header "Hdr" list member "member"
580 HTTP request header list member using ; as
581 list separator. ; can be any non-alphanumeric
584 %<{Header} HTTP reply header "Header"
586 HTTP reply header "Hdr" list member "member"
588 HTTP reply header list member using ; as
589 list separator. ; can be any non-alphanumeric
592 In addition to the above, any string specified in the referencing
593 acl will also be included in the helper request line, after the
594 specified formats (see the "acl external" directive)
596 The helper receives lines per the above format specification,
597 and returns lines starting with OK or ERR indicating the validity
598 of the request and optionally followed by additional keywords with
601 General result syntax:
603 OK/ERR keyword=value ...
607 user= The users name (login)
608 password= The users password (for login= cache_peer option)
609 message= Message describing the reason. Available as %o
611 tag= Apply a tag to a request (for both ERR and OK results)
612 Only sets a tag, does not alter existing tags.
613 log= String to be logged in access.log. Available as
614 %ea in logformat specifications
616 If protocol=3.0 (the default) then URL escaping is used to protect
617 each value in both requests and responses.
619 If using protocol=2.5 then all values need to be enclosed in quotes
620 if they may contain whitespace, or the whitespace escaped using \.
621 And quotes or \ characters within the keyword value must be \ escaped.
623 When using the concurrency= option the protocol is changed by
624 introducing a query channel tag infront of the request/response.
625 The query channel tag is a number between 0 and concurrency-1.
633 Defining an Access List
635 Every access list definition must begin with an aclname and acltype,
636 followed by either type-specific arguments or a quoted filename that
639 acl aclname acltype argument ...
640 acl aclname acltype "file" ...
642 When using "file", the file should contain one item per line.
644 By default, regular expressions are CASE-SENSITIVE. To make
645 them case-insensitive, use the -i option.
647 Some acl types require suspending the current request in order
648 to access some external data source.
649 Those which do are marked with the tag [slow], those which
650 don't are marked as [fast].
651 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
652 for further information
654 ***** ACL TYPES AVAILABLE *****
656 acl aclname src ip-address/netmask ... # clients IP address [fast]
657 acl aclname src addr1-addr2/netmask ... # range of addresses [fast]
658 acl aclname dst ip-address/netmask ... # URL host's IP address [slow]
659 acl aclname myip ip-address/netmask ... # local socket IP address [fast]
661 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
662 # The arp ACL requires the special configure option --enable-arp-acl.
663 # Furthermore, the ARP ACL code is not portable to all operating systems.
664 # It works on Linux, Solaris, Windows, FreeBSD, and some
665 # other *BSD variants.
668 # NOTE: Squid can only determine the MAC address for clients that are on
669 # the same subnet. If the client is on a different subnet,
670 # then Squid cannot find out its MAC address.
672 acl aclname srcdomain .foo.com ...
673 # reverse lookup, from client IP [slow]
674 acl aclname dstdomain .foo.com ...
675 # Destination server from URL [fast]
676 acl aclname srcdom_regex [-i] \.foo\.com ...
677 # regex matching client name [slow]
678 acl aclname dstdom_regex [-i] \.foo\.com ...
679 # regex matching server [fast]
681 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
682 # based URL is used and no match is found. The name "none" is used
683 # if the reverse lookup fails.
685 acl aclname src_as number ...
686 acl aclname dst_as number ...
688 # Except for access control, AS numbers can be used for
689 # routing of requests to specific caches. Here's an
690 # example for routing all requests for AS#1241 and only
691 # those to mycache.mydomain.net:
692 # acl asexample dst_as 1241
693 # cache_peer_access mycache.mydomain.net allow asexample
694 # cache_peer_access mycache_mydomain.net deny all
696 acl aclname peername myPeer ...
698 # match against a named cache_peer entry
699 # set unique name= on cache_peer lines for reliable use.
701 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
711 # h1:m1 must be less than h2:m2
713 acl aclname url_regex [-i] ^http:// ...
714 # regex matching on whole URL [fast]
715 acl aclname urlpath_regex [-i] \.gif$ ...
716 # regex matching on URL path [fast]
718 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
720 acl aclname myport 3128 ... # local socket TCP port [fast]
721 acl aclname myportname 3128 ... # http(s)_port name [fast]
723 acl aclname proto HTTP FTP ... # request protocol [fast]
725 acl aclname method GET POST ... # HTTP request method [fast]
727 acl aclname http_status 200 301 500- 400-403 ...
728 # status code in reply [fast]
730 acl aclname browser [-i] regexp ...
731 # pattern match on User-Agent header (see also req_header below) [fast]
733 acl aclname referer_regex [-i] regexp ...
734 # pattern match on Referer header [fast]
735 # Referer is highly unreliable, so use with care
737 acl aclname ident username ...
738 acl aclname ident_regex [-i] pattern ...
739 # string match on ident output [slow]
740 # use REQUIRED to accept any non-null ident.
742 acl aclname proxy_auth [-i] username ...
743 acl aclname proxy_auth_regex [-i] pattern ...
744 # perform http authentication challenge to the client and match against
745 # supplied credentials [slow]
747 # takes a list of allowed usernames.
748 # use REQUIRED to accept any valid username.
750 # Will use proxy authentication in forward-proxy scenarios, and plain
751 # http authenticaiton in reverse-proxy scenarios
753 # NOTE: when a Proxy-Authentication header is sent but it is not
754 # needed during ACL checking the username is NOT logged
757 # NOTE: proxy_auth requires a EXTERNAL authentication program
758 # to check username/password combinations (see
759 # auth_param directive).
761 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
762 # as the browser needs to be configured for using a proxy in order
763 # to respond to proxy authentication.
765 acl aclname snmp_community string ...
766 # A community string to limit access to your SNMP Agent [fast]
769 # acl snmppublic snmp_community public
771 acl aclname maxconn number
772 # This will be matched when the client's IP address has
773 # more than <number> TCP connections established. [fast]
774 # NOTE: This only measures direct TCP links so X-Forwarded-For
775 # indirect clients are not counted.
777 acl aclname max_user_ip [-s] number
778 # This will be matched when the user attempts to log in from more
779 # than <number> different ip addresses. The authenticate_ip_ttl
780 # parameter controls the timeout on the ip entries. [fast]
781 # If -s is specified the limit is strict, denying browsing
782 # from any further IP addresses until the ttl has expired. Without
783 # -s Squid will just annoy the user by "randomly" denying requests.
784 # (the counter is reset each time the limit is reached and a
786 # NOTE: in acceleration mode or where there is mesh of child proxies,
787 # clients may appear to come from multiple addresses if they are
788 # going through proxy farms, so a limit of 1 may cause user problems.
790 acl aclname random probability
791 # Pseudo-randomly match requests. Based on the probability given.
792 # Probability may be written as a decimal (0.333), fraction (1/3)
793 # or ratio of matches:non-matches (3:5).
795 acl aclname req_mime_type [-i] mime-type ...
796 # regex match against the mime type of the request generated
797 # by the client. Can be used to detect file upload or some
798 # types HTTP tunneling requests [fast]
799 # NOTE: This does NOT match the reply. You cannot use this
800 # to match the returned file type.
802 acl aclname req_header header-name [-i] any\.regex\.here
803 # regex match against any of the known request headers. May be
804 # thought of as a superset of "browser", "referer" and "mime-type"
807 acl aclname rep_mime_type [-i] mime-type ...
808 # regex match against the mime type of the reply received by
809 # squid. Can be used to detect file download or some
810 # types HTTP tunneling requests. [fast]
811 # NOTE: This has no effect in http_access rules. It only has
812 # effect in rules that affect the reply data stream such as
815 acl aclname rep_header header-name [-i] any\.regex\.here
816 # regex match against any of the known reply headers. May be
817 # thought of as a superset of "browser", "referer" and "mime-type"
820 acl aclname external class_name [arguments...]
821 # external ACL lookup via a helper class defined by the
822 # external_acl_type directive [slow]
824 acl aclname user_cert attribute values...
825 # match against attributes in a user SSL certificate
826 # attribute is one of DN/C/O/CN/L/ST [fast]
828 acl aclname ca_cert attribute values...
829 # match against attributes a users issuing CA SSL certificate
830 # attribute is one of DN/C/O/CN/L/ST [fast]
832 acl aclname ext_user username ...
833 acl aclname ext_user_regex [-i] pattern ...
834 # string match on username returned by external acl helper [slow]
835 # use REQUIRED to accept any non-null user name.
837 acl aclname tag tagvalue ...
838 # string match on tag returned by external acl helper [slow]
840 acl aclname hier_code codename ...
841 # string match against squid hierarchy code(s); [fast]
842 # e.g., DIRECT, PARENT_HIT, NONE, etc.
844 # NOTE: This has no effect in http_access rules. It only has
845 # effect in rules that affect the reply data stream such as
849 acl macaddress arp 09:00:2b:23:45:67
850 acl myexample dst_as 1241
851 acl password proxy_auth REQUIRED
852 acl fileupload req_mime_type -i ^multipart/form-data$
853 acl javascript rep_mime_type -i ^application/x-javascript$
857 # Recommended minimum configuration:
859 acl manager proto cache_object
860 acl localhost src 127.0.0.1/32 ::1
861 acl to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
863 # Example rule allowing access from your local networks.
864 # Adapt to list your (internal) IP networks from where browsing
866 acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
867 acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
868 acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
869 acl localnet src fc00::/7 # RFC 4193 local private network range
870 acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
872 acl SSL_ports port 443
873 acl Safe_ports port 80 # http
874 acl Safe_ports port 21 # ftp
875 acl Safe_ports port 443 # https
876 acl Safe_ports port 70 # gopher
877 acl Safe_ports port 210 # wais
878 acl Safe_ports port 1025-65535 # unregistered ports
879 acl Safe_ports port 280 # http-mgmt
880 acl Safe_ports port 488 # gss-http
881 acl Safe_ports port 591 # filemaker
882 acl Safe_ports port 777 # multiling http
883 acl CONNECT method CONNECT
887 NAME: follow_x_forwarded_for
889 IFDEF: FOLLOW_X_FORWARDED_FOR
890 LOC: Config.accessList.followXFF
891 DEFAULT_IF_NONE: deny all
893 Allowing or Denying the X-Forwarded-For header to be followed to
894 find the original source of a request.
896 Requests may pass through a chain of several other proxies
897 before reaching us. The X-Forwarded-For header will contain a
898 comma-separated list of the IP addresses in the chain, with the
899 rightmost address being the most recent.
901 If a request reaches us from a source that is allowed by this
902 configuration item, then we consult the X-Forwarded-For header
903 to see where that host received the request from. If the
904 X-Forwarded-For header contains multiple addresses, we continue
905 backtracking until we reach an address for which we are not allowed
906 to follow the X-Forwarded-For header, or until we reach the first
907 address in the list. For the purpose of ACL used in the
908 follow_x_forwarded_for directive the src ACL type always matches
909 the address we are testing and srcdomain matches its rDNS.
911 The end result of this process is an IP address that we will
912 refer to as the indirect client address. This address may
913 be treated as the client address for access control, ICAP, delay
914 pools and logging, depending on the acl_uses_indirect_client,
915 icap_uses_indirect_client, delay_pool_uses_indirect_client,
916 log_uses_indirect_client and tproxy_uses_indirect_client options.
918 This clause only supports fast acl types.
919 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
921 SECURITY CONSIDERATIONS:
923 Any host for which we follow the X-Forwarded-For header
924 can place incorrect information in the header, and Squid
925 will use the incorrect information as if it were the
926 source address of the request. This may enable remote
927 hosts to bypass any access control restrictions that are
928 based on the client's source addresses.
932 acl localhost src 127.0.0.1
933 acl my_other_proxy srcdomain .proxy.example.com
934 follow_x_forwarded_for allow localhost
935 follow_x_forwarded_for allow my_other_proxy
938 NAME: acl_uses_indirect_client
941 IFDEF: FOLLOW_X_FORWARDED_FOR
943 LOC: Config.onoff.acl_uses_indirect_client
945 Controls whether the indirect client address
946 (see follow_x_forwarded_for) is used instead of the
947 direct client address in acl matching.
949 NOTE: maxconn ACL considers direct TCP links and indirect
950 clients will always have zero. So no match.
953 NAME: delay_pool_uses_indirect_client
956 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
958 LOC: Config.onoff.delay_pool_uses_indirect_client
960 Controls whether the indirect client address
961 (see follow_x_forwarded_for) is used instead of the
962 direct client address in delay pools.
965 NAME: log_uses_indirect_client
968 IFDEF: FOLLOW_X_FORWARDED_FOR
970 LOC: Config.onoff.log_uses_indirect_client
972 Controls whether the indirect client address
973 (see follow_x_forwarded_for) is used instead of the
974 direct client address in the access log.
977 NAME: tproxy_uses_indirect_client
980 IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
982 LOC: Config.onoff.tproxy_uses_indirect_client
984 Controls whether the indirect client address
985 (see follow_x_forwarded_for) is used instead of the
986 direct client address when spoofing the outgoing client.
988 This has no effect on requests arriving in non-tproxy
991 SECURITY WARNING: Usage of this option is dangerous
992 and should not be used trivially. Correct configuration
993 of folow_x_forewarded_for with a limited set of trusted
994 sources is required to prevent abuse of your proxy.
999 LOC: Config.accessList.http
1000 DEFAULT_IF_NONE: deny all
1002 Allowing or Denying access based on defined access lists
1004 Access to the HTTP port:
1005 http_access allow|deny [!]aclname ...
1007 NOTE on default values:
1009 If there are no "access" lines present, the default is to deny
1012 If none of the "access" lines cause a match, the default is the
1013 opposite of the last line in the list. If the last line was
1014 deny, the default is allow. Conversely, if the last line
1015 is allow, the default will be deny. For these reasons, it is a
1016 good idea to have an "deny all" entry at the end of your access
1017 lists to avoid potential confusion.
1019 This clause supports both fast and slow acl types.
1020 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1025 # Recommended minimum Access Permission configuration:
1027 # Only allow cachemgr access from localhost
1028 http_access allow manager localhost
1029 http_access deny manager
1031 # Deny requests to certain unsafe ports
1032 http_access deny !Safe_ports
1034 # Deny CONNECT to other than secure SSL ports
1035 http_access deny CONNECT !SSL_ports
1037 # We strongly recommend the following be uncommented to protect innocent
1038 # web applications running on the proxy server who think the only
1039 # one who can access services on "localhost" is a local user
1040 #http_access deny to_localhost
1043 # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
1046 # Example rule allowing access from your local networks.
1047 # Adapt localnet in the ACL section to list your (internal) IP networks
1048 # from where browsing should be allowed
1049 http_access allow localnet
1050 http_access allow localhost
1052 # And finally deny all other access to this proxy
1053 http_access deny all
1057 NAME: adapted_http_access http_access2
1059 LOC: Config.accessList.adapted_http
1062 Allowing or Denying access based on defined access lists
1064 Essentially identical to http_access, but runs after redirectors
1065 and ICAP/eCAP adaptation. Allowing access control based on their
1068 If not set then only http_access is used.
1071 NAME: http_reply_access
1073 LOC: Config.accessList.reply
1076 Allow replies to client requests. This is complementary to http_access.
1078 http_reply_access allow|deny [!] aclname ...
1080 NOTE: if there are no access lines present, the default is to allow
1083 If none of the access lines cause a match the opposite of the
1084 last line will apply. Thus it is good practice to end the rules
1085 with an "allow all" or "deny all" entry.
1087 This clause supports both fast and slow acl types.
1088 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1093 LOC: Config.accessList.icp
1094 DEFAULT_IF_NONE: deny all
1096 Allowing or Denying access to the ICP port based on defined
1099 icp_access allow|deny [!]aclname ...
1101 See http_access for details
1103 This clause only supports fast acl types.
1104 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1106 # Allow ICP queries from local networks only
1107 #icp_access allow localnet
1108 #icp_access deny all
1114 LOC: Config.accessList.htcp
1115 DEFAULT_IF_NONE: deny all
1117 Allowing or Denying access to the HTCP port based on defined
1120 htcp_access allow|deny [!]aclname ...
1122 See http_access for details
1124 NOTE: The default if no htcp_access lines are present is to
1125 deny all traffic. This default may cause problems with peers
1126 using the htcp option.
1128 This clause only supports fast acl types.
1129 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1131 # Allow HTCP queries from local networks only
1132 #htcp_access allow localnet
1133 #htcp_access deny all
1136 NAME: htcp_clr_access
1139 LOC: Config.accessList.htcp_clr
1140 DEFAULT_IF_NONE: deny all
1142 Allowing or Denying access to purge content using HTCP based
1143 on defined access lists
1145 htcp_clr_access allow|deny [!]aclname ...
1147 See http_access for details
1149 This clause only supports fast acl types.
1150 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1152 # Allow HTCP CLR requests from trusted peers
1153 acl htcp_clr_peer src 172.16.1.2
1154 htcp_clr_access allow htcp_clr_peer
1159 LOC: Config.accessList.miss
1162 Use to force your neighbors to use you as a sibling instead of
1163 a parent. For example:
1165 acl localclients src 172.16.0.0/16
1166 miss_access allow localclients
1167 miss_access deny !localclients
1169 This means only your local clients are allowed to fetch
1170 MISSES and all other clients can only fetch HITS.
1172 By default, allow all clients who passed the http_access rules
1173 to fetch MISSES from us.
1175 This clause only supports fast acl types.
1176 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1179 NAME: ident_lookup_access
1182 DEFAULT_IF_NONE: deny all
1183 LOC: Ident::TheConfig.identLookup
1185 A list of ACL elements which, if matched, cause an ident
1186 (RFC 931) lookup to be performed for this request. For
1187 example, you might choose to always perform ident lookups
1188 for your main multi-user Unix boxes, but not for your Macs
1189 and PCs. By default, ident lookups are not performed for
1192 To enable ident lookups for specific client addresses, you
1193 can follow this example:
1195 acl ident_aware_hosts src 198.168.1.0/24
1196 ident_lookup_access allow ident_aware_hosts
1197 ident_lookup_access deny all
1199 Only src type ACL checks are fully supported. A srcdomain
1200 ACL might work at times, but it will not always provide
1203 This clause only supports fast acl types.
1204 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1207 NAME: reply_body_max_size
1208 COMMENT: size [acl acl...]
1211 LOC: Config.ReplyBodySize
1213 This option specifies the maximum size of a reply body. It can be
1214 used to prevent users from downloading very large files, such as
1215 MP3's and movies. When the reply headers are received, the
1216 reply_body_max_size lines are processed, and the first line where
1217 all (if any) listed ACLs are true is used as the maximum body size
1220 This size is checked twice. First when we get the reply headers,
1221 we check the content-length value. If the content length value exists
1222 and is larger than the allowed size, the request is denied and the
1223 user receives an error message that says "the request or reply
1224 is too large." If there is no content-length, and the reply
1225 size exceeds this limit, the client's connection is just closed
1226 and they will receive a partial reply.
1228 WARNING: downstream caches probably can not detect a partial reply
1229 if there is no content-length header, so they will cache
1230 partial responses and give them out as hits. You should NOT
1231 use this option if you have downstream caches.
1233 WARNING: A maximum size smaller than the size of squid's error messages
1234 will cause an infinite loop and crash squid. Ensure that the smallest
1235 non-zero value you use is greater that the maximum header size plus
1236 the size of your largest error page.
1238 If you set this parameter none (the default), there will be
1241 Configuration Format is:
1242 reply_body_max_size SIZE UNITS [acl ...]
1244 reply_body_max_size 10 MB
1250 -----------------------------------------------------------------------------
1253 NAME: http_port ascii_port
1254 TYPE: http_port_list
1256 LOC: Config.Sockaddr.http
1258 Usage: port [mode] [options]
1259 hostname:port [mode] [options]
1260 1.2.3.4:port [mode] [options]
1262 The socket addresses where Squid will listen for HTTP client
1263 requests. You may specify multiple socket addresses.
1264 There are three forms: port alone, hostname with port, and
1265 IP address with port. If you specify a hostname or IP
1266 address, Squid binds the socket to that specific
1267 address. Most likely, you do not need to bind to a specific
1268 address, so you can use the port number alone.
1270 If you are running Squid in accelerator mode, you
1271 probably want to listen on port 80 also, or instead.
1273 The -a command line option may be used to specify additional
1274 port(s) where Squid listens for proxy request. Such ports will
1275 be plain proxy ports with no options.
1277 You may specify multiple socket addresses on multiple lines.
1281 intercept Support for IP-Layer interception of
1282 outgoing requests without browser settings.
1283 NP: disables authentication and IPv6 on the port.
1285 tproxy Support Linux TPROXY for spoofing outgoing
1286 connections using the client IP address.
1287 NP: disables authentication and maybe IPv6 on the port.
1289 accel Accelerator mode. Also needs at least one of
1290 vhost / vport / defaultsite.
1292 ssl-bump Intercept each CONNECT request matching ssl_bump ACL,
1293 establish secure connection with the client and with
1294 the server, decrypt HTTP messages as they pass through
1295 Squid, and treat them as unencrypted HTTP messages,
1296 becoming the man-in-the-middle.
1298 The ssl_bump option is required to fully enable
1299 the SslBump feature.
1301 Omitting the mode flag causes default forward proxy mode to be used.
1304 Accelerator Mode Options:
1306 allow-direct Allow direct forwarding in accelerator mode. Normally
1307 accelerated requests are denied direct forwarding as if
1308 never_direct was used.
1310 defaultsite=domainname
1311 What to use for the Host: header if it is not present
1312 in a request. Determines what site (not origin server)
1313 accelerators should consider the default.
1316 vhost Using the Host header for virtual domain support.
1317 Also uses the port as specified in Host: header.
1319 vport IP based virtual host support. Using the http_port number
1320 in passed on Host: headers.
1322 vport=NN Uses the specified port number rather than the
1325 protocol= Protocol to reconstruct accelerated requests with.
1326 Defaults to http://.
1328 ignore-cc Ignore request Cache-Control headers.
1330 Warning: This option violates HTTP specifications if
1331 used in non-accelerator setups.
1334 SSL Bump Mode Options:
1336 cert= Path to SSL certificate (PEM format).
1338 key= Path to SSL private key file (PEM format)
1339 if not specified, the certificate file is
1340 assumed to be a combined certificate and
1343 version= The version of SSL/TLS supported
1344 1 automatic (default)
1349 cipher= Colon separated list of supported ciphers.
1351 options= Various SSL engine options. The most important
1353 NO_SSLv2 Disallow the use of SSLv2
1354 NO_SSLv3 Disallow the use of SSLv3
1355 NO_TLSv1 Disallow the use of TLSv1
1356 SINGLE_DH_USE Always create a new key when using
1357 temporary/ephemeral DH key exchanges
1358 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1359 documentation for a complete list of options.
1361 clientca= File containing the list of CAs to use when
1362 requesting a client certificate.
1364 cafile= File containing additional CA certificates to
1365 use when verifying client certificates. If unset
1366 clientca will be used.
1368 capath= Directory containing additional CA certificates
1369 and CRL lists to use when verifying client certificates.
1371 crlfile= File of additional CRL lists to use when verifying
1372 the client certificate, in addition to CRLs stored in
1373 the capath. Implies VERIFY_CRL flag below.
1375 dhparams= File containing DH parameters for temporary/ephemeral
1378 sslflags= Various flags modifying the use of SSL:
1380 Don't request client certificates
1381 immediately, but wait until acl processing
1382 requires a certificate (not yet implemented).
1384 Don't use the default CA lists built in
1387 Don't allow for session reuse. Each connection
1388 will result in a new SSL session.
1390 Verify CRL lists when accepting client
1393 Verify CRL lists for all certificates in the
1394 client certificate chain.
1396 sslcontext= SSL session ID context identifier.
1398 generate-host-certificates[=<on|off>]
1399 Dynamically create SSL server certificates for the
1400 destination hosts of bumped CONNECT requests.When
1401 enabled, the cert and key options are used to sign
1402 generated certificates. Otherwise generated
1403 certificate will be selfsigned.
1404 If there is CA certificate life time of generated
1405 certificate equals lifetime of CA certificate. If
1406 generated certificate is selfsigned lifetime is three
1408 This option is enabled by default when SslBump is used.
1409 See the sslBump option above for more information.
1411 dynamic_cert_mem_cache_size=SIZE
1412 Approximate total RAM size spent on cached generated
1413 certificates. If set to zero, caching is disabled. The
1414 default value is 4MB. An average XXX-bit certificate
1415 consumes about XXX bytes of RAM.
1419 connection-auth[=on|off]
1420 use connection-auth=off to tell Squid to prevent
1421 forwarding Microsoft connection oriented authentication
1422 (NTLM, Negotiate and Kerberos)
1424 disable-pmtu-discovery=
1425 Control Path-MTU discovery usage:
1426 off lets OS decide on what to do (default).
1427 transparent disable PMTU discovery when transparent
1429 always disable always PMTU discovery.
1431 In many setups of transparently intercepting proxies
1432 Path-MTU discovery can not work on traffic towards the
1433 clients. This is the case when the intercepting device
1434 does not fully track connections and fails to forward
1435 ICMP must fragment messages to the cache server. If you
1436 have such setup and experience that certain clients
1437 sporadically hang or never complete requests set
1438 disable-pmtu-discovery option to 'transparent'.
1440 name= Specifies a internal name for the port. Defaults to
1441 the port specification (port or addr:port)
1443 tcpkeepalive[=idle,interval,timeout]
1444 Enable TCP keepalive probes of idle connections.
1445 In seconds; idle is the initial time before TCP starts
1446 probing the connection, interval how often to probe, and
1447 timeout the time before giving up.
1449 If you run Squid on a dual-homed machine with an internal
1450 and an external interface we recommend you to specify the
1451 internal address:port in http_port. This way Squid will only be
1452 visible on the internal address.
1456 # Squid normally listens to port 3128
1457 http_port @DEFAULT_HTTP_PORT@
1463 TYPE: https_port_list
1465 LOC: Config.Sockaddr.https
1467 Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...]
1469 The socket address where Squid will listen for HTTPS client
1472 This is really only useful for situations where you are running
1473 squid in accelerator mode and you want to do the SSL work at the
1476 You may specify multiple socket addresses on multiple lines,
1477 each with their own SSL certificate and/or options.
1481 accel Accelerator mode. Also needs at least one of
1482 defaultsite or vhost.
1484 defaultsite= The name of the https site presented on
1485 this port. Implies accel.
1487 vhost Accelerator mode using Host header for virtual
1488 domain support. Requires a wildcard certificate
1489 or other certificate valid for more than one domain.
1492 protocol= Protocol to reconstruct accelerated requests with.
1495 cert= Path to SSL certificate (PEM format).
1497 key= Path to SSL private key file (PEM format)
1498 if not specified, the certificate file is
1499 assumed to be a combined certificate and
1502 version= The version of SSL/TLS supported
1503 1 automatic (default)
1508 cipher= Colon separated list of supported ciphers.
1510 options= Various SSL engine options. The most important
1512 NO_SSLv2 Disallow the use of SSLv2
1513 NO_SSLv3 Disallow the use of SSLv3
1514 NO_TLSv1 Disallow the use of TLSv1
1515 SINGLE_DH_USE Always create a new key when using
1516 temporary/ephemeral DH key exchanges
1517 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1518 documentation for a complete list of options.
1520 clientca= File containing the list of CAs to use when
1521 requesting a client certificate.
1523 cafile= File containing additional CA certificates to
1524 use when verifying client certificates. If unset
1525 clientca will be used.
1527 capath= Directory containing additional CA certificates
1528 and CRL lists to use when verifying client certificates.
1530 crlfile= File of additional CRL lists to use when verifying
1531 the client certificate, in addition to CRLs stored in
1532 the capath. Implies VERIFY_CRL flag below.
1534 dhparams= File containing DH parameters for temporary/ephemeral
1537 sslflags= Various flags modifying the use of SSL:
1539 Don't request client certificates
1540 immediately, but wait until acl processing
1541 requires a certificate (not yet implemented).
1543 Don't use the default CA lists built in
1546 Don't allow for session reuse. Each connection
1547 will result in a new SSL session.
1549 Verify CRL lists when accepting client
1552 Verify CRL lists for all certificates in the
1553 client certificate chain.
1555 sslcontext= SSL session ID context identifier.
1557 vport Accelerator with IP based virtual host support.
1559 vport=NN As above, but uses specified port number rather
1560 than the https_port number. Implies accel.
1562 name= Specifies a internal name for the port. Defaults to
1563 the port specification (port or addr:port)
1567 NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
1570 LOC: Ip::Qos::TheConfig.tosToServer
1572 Allows you to select a TOS/Diffserv value for packets outgoing
1573 on the server side, based on an ACL.
1575 tcp_outgoing_tos ds-field [!]aclname ...
1577 Example where normal_service_net uses the TOS value 0x00
1578 and good_service_net uses 0x20
1580 acl normal_service_net src 10.0.0.0/24
1581 acl good_service_net src 10.0.1.0/24
1582 tcp_outgoing_tos 0x00 normal_service_net
1583 tcp_outgoing_tos 0x20 good_service_net
1585 TOS/DSCP values really only have local significance - so you should
1586 know what you're specifying. For more information, see RFC2474,
1587 RFC2475, and RFC3260.
1589 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
1590 "default" to use whatever default your host has. Note that in
1591 practice often only multiples of 4 is usable as the two rightmost bits
1592 have been redefined for use by ECN (RFC 3168 section 23.1).
1594 Processing proceeds in the order specified, and stops at first fully
1598 NAME: clientside_tos
1601 LOC: Ip::Qos::TheConfig.tosToClient
1603 Allows you to select a TOS/Diffserv value for packets being transmitted
1604 on the client-side, based on an ACL.
1606 clientside_tos ds-field [!]aclname ...
1608 Example where normal_service_net uses the TOS value 0x00
1609 and good_service_net uses 0x20
1611 acl normal_service_net src 10.0.0.0/24
1612 acl good_service_net src 10.0.1.0/24
1613 clientside_tos 0x00 normal_service_net
1614 clientside_tos 0x20 good_service_net
1616 Note: This feature is incompatible with qos_flows. Any TOS values set here
1617 will be overwritten by TOS values in qos_flows.
1620 NAME: tcp_outgoing_mark
1624 LOC: Ip::Qos::TheConfig.nfmarkToServer
1626 Allows you to apply a Netfilter mark value to outgoing packets
1627 on the server side, based on an ACL.
1629 tcp_outgoing_mark mark-value [!]aclname ...
1631 Example where normal_service_net uses the mark value 0x00
1632 and good_service_net uses 0x20
1634 acl normal_service_net src 10.0.0.0/24
1635 acl good_service_net src 10.0.1.0/24
1636 tcp_outgoing_mark 0x00 normal_service_net
1637 tcp_outgoing_mark 0x20 good_service_net
1640 NAME: clientside_mark
1644 LOC: Ip::Qos::TheConfig.nfmarkToClient
1646 Allows you to apply a Netfilter mark value to packets being transmitted
1647 on the client-side, based on an ACL.
1649 clientside_mark mark-value [!]aclname ...
1651 Example where normal_service_net uses the mark value 0x00
1652 and good_service_net uses 0x20
1654 acl normal_service_net src 10.0.0.0/24
1655 acl good_service_net src 10.0.1.0/24
1656 clientside_mark 0x00 normal_service_net
1657 clientside_mark 0x20 good_service_net
1659 Note: This feature is incompatible with qos_flows. Any mark values set here
1660 will be overwritten by mark values in qos_flows.
1667 LOC: Ip::Qos::TheConfig
1669 Allows you to select a TOS/DSCP value to mark outgoing
1670 connections with, based on where the reply was sourced. For
1671 platforms using netfilter, allows you to set a netfilter mark
1672 value instead of, or in addition to, a TOS value.
1674 TOS values really only have local significance - so you should
1675 know what you're specifying. For more information, see RFC2474,
1676 RFC2475, and RFC3260.
1678 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
1679 in practice often only multiples of 4 is usable as the two rightmost bits
1680 have been redefined for use by ECN (RFC 3168 section 23.1).
1682 Mark values can be any unsigned 32-bit integer value.
1684 This setting is configured by setting the following values:
1686 tos|mark Whether to set TOS or netfilter mark values
1688 local-hit=0xFF Value to mark local cache hits.
1690 sibling-hit=0xFF Value to mark hits from sibling peers.
1692 parent-hit=0xFF Value to mark hits from parent peers.
1694 miss=0xFF Value to mark cache misses. Takes precedence
1695 over the preserve-miss feature (see below).
1697 The TOS variant of the following features are only possible on Linux
1698 and require your kernel to be patched with the TOS preserving ZPH
1699 patch, available from http://zph.bratcheda.org
1700 No patch is needed to preserve the netfilter mark, which will work
1701 with all variants of netfilter.
1703 disable-preserve-miss
1704 This option disables the preservation of the TOS or netfilter
1705 mark. By default, the existing TOS or netfilter mark value of
1706 the response coming from the remote server will be retained
1707 and masked with miss-mark.
1708 NOTE: in the case of a netfilter mark, the mark must be set on
1709 the connection (using the CONNMARK target) not on the packet
1713 Allows you to mask certain bits in the TOS or mark value
1714 received from the remote server, before copying the value to
1715 the TOS sent towards clients.
1716 Default for tos: 0xFF (TOS from server is not changed).
1717 Default for mark: 0xFFFFFFFF (mark from server is not changed).
1719 All of these features require the --enable-zph-qos compilation flag
1720 (enabled by default). Netfilter marking also requires the
1721 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
1722 libcap 2.09+ (--with-libcap).
1726 NAME: tcp_outgoing_address
1729 LOC: Config.accessList.outgoing_address
1731 Allows you to map requests to different outgoing IP addresses
1732 based on the username or source address of the user making
1735 tcp_outgoing_address ipaddr [[!]aclname] ...
1737 Example where requests from 10.0.0.0/24 will be forwarded
1738 with source address 10.1.0.1, 10.0.2.0/24 forwarded with
1739 source address 10.1.0.2 and the rest will be forwarded with
1740 source address 10.1.0.3.
1742 acl normal_service_net src 10.0.0.0/24
1743 acl good_service_net src 10.0.2.0/24
1744 tcp_outgoing_address 10.1.0.1 normal_service_net
1745 tcp_outgoing_address 10.1.0.2 good_service_net
1746 tcp_outgoing_address 10.1.0.3
1748 Processing proceeds in the order specified, and stops at first fully
1751 Note: The use of this directive using client dependent ACLs is
1752 incompatible with the use of server side persistent connections. To
1753 ensure correct results it is best to set server_persistent_connections
1754 to off when using this directive in such configurations.
1756 Note: The use of this directive to set a local IP on outgoing TCP links
1757 is incompatible with using TPROXY to set client IP out outbound TCP links.
1758 When needing to contact peers use the no-tproxy cache_peer option to
1759 re-enable normal forwarding such as this.
1763 Squid is built with a capability of bridging the IPv4 and IPv6
1765 tcp_outgoing_address as exampled above breaks this bridging by forcing
1766 all outbound traffic through a certain IPv4 which may be on the wrong
1767 side of the IPv4/IPv6 boundary.
1769 To operate with tcp_outgoing_address and keep the bridging benefits
1770 an additional ACL needs to be used which ensures the IPv6-bound traffic
1771 is never forced or permitted out the IPv4 interface.
1773 # IPv6 destination test along with a dummy access control to perofrm the required DNS
1774 # This MUST be place before any ALLOW rules.
1775 acl to_ipv6 dst ipv6
1776 http_access deny ipv6 !all
1778 tcp_outgoing_address 2001:db8::c001 good_service_net to_ipv6
1779 tcp_outgoing_address 10.1.0.2 good_service_net !to_ipv6
1781 tcp_outgoing_address 2001:db8::beef normal_service_net to_ipv6
1782 tcp_outgoing_address 10.1.0.1 normal_service_net !to_ipv6
1784 tcp_outgoing_address 2001:db8::1 to_ipv6
1785 tcp_outgoing_address 10.1.0.3 !to_ipv6
1788 'dst ipv6' bases its selection assuming DIRECT access.
1789 If peers are used the peername ACL are needed to select outgoing
1790 address which can link to the peer.
1792 'dst ipv6' is a slow ACL. It will only work here if 'dst' is used
1793 previously in the http_access rules to locate the destination IP.
1794 Some more magic may be needed for that:
1795 http_access allow to_ipv6 !all
1796 (meaning, allow if to IPv6 but not from anywhere ;)
1802 -----------------------------------------------------------------------------
1805 NAME: ssl_unclean_shutdown
1809 LOC: Config.SSL.unclean_shutdown
1811 Some browsers (especially MSIE) bugs out on SSL shutdown
1818 LOC: Config.SSL.ssl_engine
1821 The OpenSSL engine to use. You will need to set this if you
1822 would like to use hardware SSL acceleration for example.
1825 NAME: sslproxy_client_certificate
1828 LOC: Config.ssl_client.cert
1831 Client SSL Certificate to use when proxying https:// URLs
1834 NAME: sslproxy_client_key
1837 LOC: Config.ssl_client.key
1840 Client SSL Key to use when proxying https:// URLs
1843 NAME: sslproxy_version
1846 LOC: Config.ssl_client.version
1849 SSL version level to use when proxying https:// URLs
1852 NAME: sslproxy_options
1855 LOC: Config.ssl_client.options
1858 SSL engine options to use when proxying https:// URLs
1860 The most important being:
1862 NO_SSLv2 Disallow the use of SSLv2
1863 NO_SSLv3 Disallow the use of SSLv3
1864 NO_TLSv1 Disallow the use of TLSv1
1866 Always create a new key when using
1867 temporary/ephemeral DH key exchanges
1869 These options vary depending on your SSL engine.
1870 See the OpenSSL SSL_CTX_set_options documentation for a
1871 complete list of possible options.
1874 NAME: sslproxy_cipher
1877 LOC: Config.ssl_client.cipher
1880 SSL cipher list to use when proxying https:// URLs
1882 Colon separated list of supported ciphers.
1885 NAME: sslproxy_cafile
1888 LOC: Config.ssl_client.cafile
1891 file containing CA certificates to use when verifying server
1892 certificates while proxying https:// URLs
1895 NAME: sslproxy_capath
1898 LOC: Config.ssl_client.capath
1901 directory containing CA certificates to use when verifying
1902 server certificates while proxying https:// URLs
1908 LOC: Config.accessList.ssl_bump
1911 This ACL controls which CONNECT requests to an http_port
1912 marked with an sslBump flag are actually "bumped". Please
1913 see the sslBump flag of an http_port option for more details
1914 about decoding proxied SSL connections.
1916 By default, no requests are bumped.
1918 See also: http_port sslBump
1920 This clause only supports fast acl types.
1921 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1924 # Example: Bump all requests except those originating from localhost and
1925 # those going to webax.com or example.com sites.
1927 acl localhost src 127.0.0.1/32
1928 acl broken_sites dstdomain .webax.com
1929 acl broken_sites dstdomain .example.com
1930 ssl_bump deny localhost
1931 ssl_bump deny broken_sites
1935 NAME: sslproxy_flags
1938 LOC: Config.ssl_client.flags
1941 Various flags modifying the use of SSL while proxying https:// URLs:
1942 DONT_VERIFY_PEER Accept certificates that fail verification.
1943 For refined control, see sslproxy_cert_error.
1944 NO_DEFAULT_CA Don't use the default CA list built in
1949 NAME: sslproxy_cert_error
1952 LOC: Config.ssl_client.cert_error
1955 Use this ACL to bypass server certificate validation errors.
1957 For example, the following lines will bypass all validation errors
1958 when talking to servers located at 172.16.0.0/16. All other
1959 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
1961 acl BrokenServersAtTrustedIP dst 172.16.0.0/16
1962 sslproxy_cert_error allow BrokenServersAtTrustedIP
1963 sslproxy_cert_error deny all
1965 This clause only supports fast acl types.
1966 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1967 Using slow acl types may result in server crashes
1969 Without this option, all server certificate validation errors
1970 terminate the transaction. Bypassing validation errors is dangerous
1971 because an error usually implies that the server cannot be trusted and
1972 the connection may be insecure.
1974 See also: sslproxy_flags and DONT_VERIFY_PEER.
1976 Default setting: sslproxy_cert_error deny all
1981 NAME: sslpassword_program
1984 LOC: Config.Program.ssl_password
1987 Specify a program used for entering SSL key passphrases
1988 when using encrypted SSL certificate keys. If not specified
1989 keys must either be unencrypted, or Squid started with the -N
1990 option to allow it to query interactively for the passphrase.
1992 The key file name is given as argument to the program allowing
1993 selection of the right password if you have multiple encrypted
1998 OPTIONS RELATING TO EXTERNAL SSL_CRTD
1999 -----------------------------------------------------------------------------
2002 NAME: sslcrtd_program
2005 DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
2006 LOC: Ssl::TheConfig.ssl_crtd
2008 Specify the location and options of the executable for ssl_crtd process.
2009 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
2010 For more information use:
2011 @DEFAULT_SSL_CRTD@ -h
2014 NAME: sslcrtd_children
2015 TYPE: HelperChildConfig
2017 DEFAULT: 32 startup=5 idle=1
2018 LOC: Ssl::TheConfig.ssl_crtdChildren
2020 The maximum number of processes spawn to service ssl server.
2021 The maximum this may be safely set to is 32.
2023 The startup= and idle= options allow some measure of skew in your
2028 Sets the minimum number of processes to spawn when Squid
2029 starts or reconfigures. When set to zero the first request will
2030 cause spawning of the first child process to handle it.
2032 Starting too few children temporary slows Squid under load while it
2033 tries to spawn enough additional processes to cope with traffic.
2037 Sets a minimum of how many processes Squid is to try and keep available
2038 at all times. When traffic begins to rise above what the existing
2039 processes can handle this many more will be spawned up to the maximum
2040 configured. A minimum setting of 1 is required.
2042 You must have at least one ssl_crtd process.
2046 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
2047 -----------------------------------------------------------------------------
2055 To specify other caches in a hierarchy, use the format:
2057 cache_peer hostname type http-port icp-port [options]
2062 # hostname type port port options
2063 # -------------------- -------- ----- ----- -----------
2064 cache_peer parent.foo.net parent 3128 3130 default
2065 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
2066 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
2067 cache_peer example.com parent 80 0 no-query default
2068 cache_peer cdn.example.com sibling 3128 0
2070 type: either 'parent', 'sibling', or 'multicast'.
2072 proxy-port: The port number where the peer accept HTTP requests.
2073 For other Squid proxies this is usually 3128
2074 For web servers this is usually 80
2076 icp-port: Used for querying neighbor caches about objects.
2077 Set to 0 if the peer does not support ICP or HTCP.
2078 See ICP and HTCP options below for additional details.
2081 ==== ICP OPTIONS ====
2083 You MUST also set icp_port and icp_access explicitly when using these options.
2084 The defaults will prevent peer traffic using ICP.
2087 no-query Disable ICP queries to this neighbor.
2090 Indicates the named peer is a member of a multicast group.
2091 ICP queries will not be sent directly to the peer, but ICP
2092 replies will be accepted from it.
2094 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
2095 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
2098 To only send ICP queries to this neighbor infrequently.
2099 This is used to keep the neighbor round trip time updated
2100 and is usually used in conjunction with weighted-round-robin.
2103 ==== HTCP OPTIONS ====
2105 You MUST also set htcp_port and htcp_access explicitly when using these options.
2106 The defaults will prevent peer traffic using HTCP.
2109 htcp Send HTCP, instead of ICP, queries to the neighbor.
2110 You probably also want to set the "icp-port" to 4827
2111 instead of 3130. This directive accepts a comma separated
2112 list of options described below.
2114 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
2116 htcp=no-clr Send HTCP to the neighbor but without
2117 sending any CLR requests. This cannot be used with
2120 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
2121 This cannot be used with no-clr.
2124 Send HTCP to the neighbor including CLRs but only when
2125 they do not result from PURGE requests.
2128 Forward any HTCP CLR requests this proxy receives to the peer.
2131 ==== PEER SELECTION METHODS ====
2133 The default peer selection method is ICP, with the first responding peer
2134 being used as source. These options can be used for better load balancing.
2137 default This is a parent cache which can be used as a "last-resort"
2138 if a peer cannot be located by any of the peer-selection methods.
2139 If specified more than once, only the first is used.
2141 round-robin Load-Balance parents which should be used in a round-robin
2142 fashion in the absence of any ICP queries.
2143 weight=N can be used to add bias.
2145 weighted-round-robin
2146 Load-Balance parents which should be used in a round-robin
2147 fashion with the frequency of each parent being based on the
2148 round trip time. Closer parents are used more often.
2149 Usually used for background-ping parents.
2150 weight=N can be used to add bias.
2152 carp Load-Balance parents which should be used as a CARP array.
2153 The requests will be distributed among the parents based on the
2154 CARP load balancing hash function based on their weight.
2156 userhash Load-balance parents based on the client proxy_auth or ident username.
2158 sourcehash Load-balance parents based on the client source IP.
2161 To be used only for cache peers of type "multicast".
2162 ALL members of this multicast group have "sibling"
2163 relationship with it, not "parent". This is to a mulicast
2164 group when the requested object would be fetched only from
2165 a "parent" cache, anyway. It's useful, e.g., when
2166 configuring a pool of redundant Squid proxies, being
2167 members of the same multicast group.
2170 ==== PEER SELECTION OPTIONS ====
2172 weight=N use to affect the selection of a peer during any weighted
2173 peer-selection mechanisms.
2174 The weight must be an integer; default is 1,
2175 larger weights are favored more.
2176 This option does not affect parent selection if a peering
2177 protocol is not in use.
2179 basetime=N Specify a base amount to be subtracted from round trip
2181 It is subtracted before division by weight in calculating
2182 which parent to fectch from. If the rtt is less than the
2183 base time the rtt is set to a minimal value.
2185 ttl=N Specify a TTL to use when sending multicast ICP queries
2187 Only useful when sending to a multicast group.
2188 Because we don't accept ICP replies from random
2189 hosts, you must configure other group members as
2190 peers with the 'multicast-responder' option.
2192 no-delay To prevent access to this neighbor from influencing the
2195 digest-url=URL Tell Squid to fetch the cache digest (if digests are
2196 enabled) for this host from the specified URL rather
2197 than the Squid default location.
2200 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
2202 originserver Causes this parent to be contacted as an origin server.
2203 Meant to be used in accelerator setups when the peer
2207 Set the Host header of requests forwarded to this peer.
2208 Useful in accelerator setups where the server (peer)
2209 expects a certain domain name but clients may request
2210 others. ie example.com or www.example.com
2212 no-digest Disable request of cache digests.
2215 Disables requesting ICMP RTT database (NetDB).
2218 ==== AUTHENTICATION OPTIONS ====
2221 If this is a personal/workgroup proxy and your parent
2222 requires proxy authentication.
2224 Note: The string can include URL escapes (i.e. %20 for
2225 spaces). This also means % must be written as %%.
2228 Send login details received from client to this peer.
2229 Both Proxy- and WWW-Authorization headers are passed
2230 without alteration to the peer.
2231 Authentication is not required by Squid for this to work.
2233 Note: This will pass any form of authentication but
2234 only Basic auth will work through a proxy unless the
2235 connection-auth options are also used.
2237 login=PASS Send login details received from client to this peer.
2238 Authentication is not required by this option.
2240 If there are no client-provided authentication headers
2241 to pass on, but username and password are available
2242 from an external ACL user= and password= result tags
2243 they may be sent instead.
2245 Note: To combine this with proxy_auth both proxies must
2246 share the same user database as HTTP only allows for
2247 a single login (one for proxy, one for origin server).
2248 Also be warned this will expose your users proxy
2249 password to the peer. USE WITH CAUTION
2252 Send the username to the upstream cache, but with a
2253 fixed password. This is meant to be used when the peer
2254 is in another administrative domain, but it is still
2255 needed to identify each user.
2256 The star can optionally be followed by some extra
2257 information which is added to the username. This can
2258 be used to identify this proxy to the peer, similar to
2259 the login=username:password option above.
2262 If this is a personal/workgroup proxy and your parent
2263 requires a secure proxy authentication.
2264 The first principal from the default keytab or defined by
2265 the environment variable KRB5_KTNAME will be used.
2267 login=NEGOTIATE:principal_name
2268 If this is a personal/workgroup proxy and your parent
2269 requires a secure proxy authentication.
2270 The principal principal_name from the default keytab or
2271 defined by the environment variable KRB5_KTNAME will be
2274 connection-auth=on|off
2275 Tell Squid that this peer does or not support Microsoft
2276 connection oriented authentication, and any such
2277 challenges received from there should be ignored.
2278 Default is auto to automatically determine the status
2282 ==== SSL / HTTPS / TLS OPTIONS ====
2284 ssl Encrypt connections to this peer with SSL/TLS.
2286 sslcert=/path/to/ssl/certificate
2287 A client SSL certificate to use when connecting to
2290 sslkey=/path/to/ssl/key
2291 The private SSL key corresponding to sslcert above.
2292 If 'sslkey' is not specified 'sslcert' is assumed to
2293 reference a combined file containing both the
2294 certificate and the key.
2297 The SSL version to use when connecting to this peer
2298 1 = automatic (default)
2303 sslcipher=... The list of valid SSL ciphers to use when connecting
2306 ssloptions=... Specify various SSL engine options:
2307 NO_SSLv2 Disallow the use of SSLv2
2308 NO_SSLv3 Disallow the use of SSLv3
2309 NO_TLSv1 Disallow the use of TLSv1
2310 See src/ssl_support.c or the OpenSSL documentation for
2311 a more complete list.
2313 sslcafile=... A file containing additional CA certificates to use
2314 when verifying the peer certificate.
2316 sslcapath=... A directory containing additional CA certificates to
2317 use when verifying the peer certificate.
2319 sslcrlfile=... A certificate revocation list file to use when
2320 verifying the peer certificate.
2322 sslflags=... Specify various flags modifying the SSL implementation:
2325 Accept certificates even if they fail to
2328 Don't use the default CA list built in
2331 Don't verify the peer certificate
2332 matches the server name
2334 ssldomain= The peer name as advertised in it's certificate.
2335 Used for verifying the correctness of the received peer
2336 certificate. If not specified the peer hostname will be
2340 Enable the "Front-End-Https: On" header needed when
2341 using Squid as a SSL frontend in front of Microsoft OWA.
2342 See MS KB document Q307347 for details on this header.
2343 If set to auto the header will only be added if the
2344 request is forwarded as a https:// URL.
2347 ==== GENERAL OPTIONS ====
2350 A peer-specific connect timeout.
2351 Also see the peer_connect_timeout directive.
2353 connect-fail-limit=N
2354 How many times connecting to a peer must fail before
2355 it is marked as down. Default is 10.
2357 allow-miss Disable Squid's use of only-if-cached when forwarding
2358 requests to siblings. This is primarily useful when
2359 icp_hit_stale is used by the sibling. To extensive use
2360 of this option may result in forwarding loops, and you
2361 should avoid having two-way peerings with this option.
2362 For example to deny peer usage on requests from peer
2363 by denying cache_peer_access if the source is a peer.
2365 max-conn=N Limit the amount of connections Squid may open to this
2368 name=xxx Unique name for the peer.
2369 Required if you have multiple peers on the same host
2370 but different ports.
2371 This name can be used in cache_peer_access and similar
2372 directives to dentify the peer.
2373 Can be used by outgoing access controls through the
2376 no-tproxy Do not use the client-spoof TPROXY support when forwarding
2377 requests to this peer. Use normal address selection instead.
2379 proxy-only objects fetched from the peer will not be stored locally.
2383 NAME: cache_peer_domain cache_host_domain
2388 Use to limit the domains for which a neighbor cache will be
2391 cache_peer_domain cache-host domain [domain ...]
2392 cache_peer_domain cache-host !domain
2394 For example, specifying
2396 cache_peer_domain parent.foo.net .edu
2398 has the effect such that UDP query packets are sent to
2399 'bigserver' only when the requested object exists on a
2400 server in the .edu domain. Prefixing the domainname
2401 with '!' means the cache will be queried for objects
2404 NOTE: * Any number of domains may be given for a cache-host,
2405 either on the same or separate lines.
2406 * When multiple domains are given for a particular
2407 cache-host, the first matched domain is applied.
2408 * Cache hosts with no domain restrictions are queried
2410 * There are no defaults.
2411 * There is also a 'cache_peer_access' tag in the ACL
2415 NAME: cache_peer_access
2420 Similar to 'cache_peer_domain' but provides more flexibility by
2423 cache_peer_access cache-host allow|deny [!]aclname ...
2425 The syntax is identical to 'http_access' and the other lists of
2426 ACL elements. See the comments for 'http_access' below, or
2427 the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
2430 NAME: neighbor_type_domain
2431 TYPE: hostdomaintype
2435 usage: neighbor_type_domain neighbor parent|sibling domain domain ...
2437 Modifying the neighbor type for specific domains is now
2438 possible. You can treat some domains differently than the
2439 default neighbor type specified on the 'cache_peer' line.
2440 Normally it should only be necessary to list domains which
2441 should be treated differently because the default neighbor type
2442 applies for hostnames which do not match domains listed here.
2445 cache_peer cache.foo.org parent 3128 3130
2446 neighbor_type_domain cache.foo.org sibling .com .net
2447 neighbor_type_domain cache.foo.org sibling .au .de
2450 NAME: dead_peer_timeout
2454 LOC: Config.Timeout.deadPeer
2456 This controls how long Squid waits to declare a peer cache
2457 as "dead." If there are no ICP replies received in this
2458 amount of time, Squid will declare the peer dead and not
2459 expect to receive any further ICP replies. However, it
2460 continues to send ICP queries, and will mark the peer as
2461 alive upon receipt of the first subsequent ICP reply.
2463 This timeout also affects when Squid expects to receive ICP
2464 replies from peers. If more than 'dead_peer' seconds have
2465 passed since the last ICP reply was received, Squid will not
2466 expect to receive an ICP reply on the next query. Thus, if
2467 your time between requests is greater than this timeout, you
2468 will see a lot of requests sent DIRECT to origin servers
2469 instead of to your parents.
2472 NAME: forward_max_tries
2475 LOC: Config.forward_max_tries
2477 Controls how many different forward paths Squid will try
2478 before giving up. See also forward_timeout.
2481 NAME: hierarchy_stoplist
2484 LOC: Config.hierarchy_stoplist
2486 A list of words which, if found in a URL, cause the object to
2487 be handled directly by this cache. In other words, use this
2488 to not query neighbor caches for certain objects. You may
2489 list this option multiple times.
2490 Note: never_direct overrides this option.
2493 # We recommend you to use at least the following line.
2494 hierarchy_stoplist cgi-bin ?
2499 MEMORY CACHE OPTIONS
2500 -----------------------------------------------------------------------------
2507 LOC: Config.memMaxSize
2509 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
2510 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
2511 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
2512 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
2514 'cache_mem' specifies the ideal amount of memory to be used
2516 * In-Transit objects
2518 * Negative-Cached objects
2520 Data for these objects are stored in 4 KB blocks. This
2521 parameter specifies the ideal upper limit on the total size of
2522 4 KB blocks allocated. In-Transit objects take the highest
2525 In-transit objects have priority over the others. When
2526 additional space is needed for incoming data, negative-cached
2527 and hot objects will be released. In other words, the
2528 negative-cached and hot objects will fill up any unused space
2529 not needed for in-transit objects.
2531 If circumstances require, this limit will be exceeded.
2532 Specifically, if your incoming request rate requires more than
2533 'cache_mem' of memory to hold in-transit objects, Squid will
2534 exceed this limit to satisfy the new requests. When the load
2535 decreases, blocks will be freed until the high-water mark is
2536 reached. Thereafter, blocks will be used to store hot
2540 NAME: maximum_object_size_in_memory
2544 LOC: Config.Store.maxInMemObjSize
2546 Objects greater than this size will not be attempted to kept in
2547 the memory cache. This should be set high enough to keep objects
2548 accessed frequently in memory to improve performance whilst low
2549 enough to keep larger objects from hoarding cache_mem.
2552 NAME: memory_cache_mode
2557 Controls which objects to keep in the memory cache (cache_mem)
2559 always Keep most recently fetched objects in memory (default)
2561 disk Only disk cache hits are kept in memory, which means
2562 an object must first be cached on disk and then hit
2563 a second time before cached in memory.
2565 network Only objects fetched from network is kept in memory
2568 NAME: memory_replacement_policy
2570 LOC: Config.memPolicy
2573 The memory replacement policy parameter determines which
2574 objects are purged from memory when memory space is needed.
2576 See cache_replacement_policy for details.
2581 -----------------------------------------------------------------------------
2584 NAME: cache_replacement_policy
2586 LOC: Config.replPolicy
2589 The cache replacement policy parameter determines which
2590 objects are evicted (replaced) when disk space is needed.
2592 lru : Squid's original list based LRU policy
2593 heap GDSF : Greedy-Dual Size Frequency
2594 heap LFUDA: Least Frequently Used with Dynamic Aging
2595 heap LRU : LRU policy implemented using a heap
2597 Applies to any cache_dir lines listed below this.
2599 The LRU policies keeps recently referenced objects.
2601 The heap GDSF policy optimizes object hit rate by keeping smaller
2602 popular objects in cache so it has a better chance of getting a
2603 hit. It achieves a lower byte hit rate than LFUDA though since
2604 it evicts larger (possibly popular) objects.
2606 The heap LFUDA policy keeps popular objects in cache regardless of
2607 their size and thus optimizes byte hit rate at the expense of
2608 hit rate since one large, popular object will prevent many
2609 smaller, slightly less popular objects from being cached.
2611 Both policies utilize a dynamic aging mechanism that prevents
2612 cache pollution that can otherwise occur with frequency-based
2613 replacement policies.
2615 NOTE: if using the LFUDA replacement policy you should increase
2616 the value of maximum_object_size above its default of 4096 KB to
2617 to maximize the potential byte hit rate improvement of LFUDA.
2619 For more information about the GDSF and LFUDA cache replacement
2620 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
2621 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
2627 LOC: Config.cacheSwap
2631 cache_dir Type Directory-Name Fs-specific-data [options]
2633 You can specify multiple cache_dir lines to spread the
2634 cache among different disk partitions.
2636 Type specifies the kind of storage system to use. Only "ufs"
2637 is built by default. To enable any of the other storage systems
2638 see the --enable-storeio configure option.
2640 'Directory' is a top-level directory where cache swap
2641 files will be stored. If you want to use an entire disk
2642 for caching, this can be the mount-point directory.
2643 The directory must exist and be writable by the Squid
2644 process. Squid will NOT create this directory for you.
2646 In SMP configurations, cache_dir must not precede the workers option
2647 and should use configuration macros or conditionals to give each
2648 worker interested in disk caching a dedicated cache directory.
2652 "ufs" is the old well-known Squid storage format that has always
2655 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
2657 'Mbytes' is the amount of disk space (MB) to use under this
2658 directory. The default is 100 MB. Change this to suit your
2659 configuration. Do NOT put the size of your disk drive here.
2660 Instead, if you want Squid to use the entire disk drive,
2661 subtract 20% and use that value.
2663 'L1' is the number of first-level subdirectories which
2664 will be created under the 'Directory'. The default is 16.
2666 'L2' is the number of second-level subdirectories which
2667 will be created under each first-level directory. The default
2670 The aufs store type:
2672 "aufs" uses the same storage format as "ufs", utilizing
2673 POSIX-threads to avoid blocking the main Squid process on
2674 disk-I/O. This was formerly known in Squid as async-io.
2676 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
2678 see argument descriptions under ufs above
2680 The diskd store type:
2682 "diskd" uses the same storage format as "ufs", utilizing a
2683 separate process to avoid blocking the main Squid process on
2686 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
2688 see argument descriptions under ufs above
2690 Q1 specifies the number of unacknowledged I/O requests when Squid
2691 stops opening new files. If this many messages are in the queues,
2692 Squid won't open new files. Default is 64
2694 Q2 specifies the number of unacknowledged messages when Squid
2695 starts blocking. If this many messages are in the queues,
2696 Squid blocks until it receives some replies. Default is 72
2698 When Q1 < Q2 (the default), the cache directory is optimized
2699 for lower response time at the expense of a decrease in hit
2700 ratio. If Q1 > Q2, the cache directory is optimized for
2701 higher hit ratio at the expense of an increase in response
2704 The coss store type:
2706 NP: COSS filesystem in Squid-3 has been deemed too unstable for
2707 production use and has thus been removed from this release.
2708 We hope that it can be made usable again soon.
2710 block-size=n defines the "block size" for COSS cache_dir's.
2711 Squid uses file numbers as block numbers. Since file numbers
2712 are limited to 24 bits, the block size determines the maximum
2713 size of the COSS partition. The default is 512 bytes, which
2714 leads to a maximum cache_dir size of 512<<24, or 8 GB. Note
2715 you should not change the coss block size after Squid
2716 has written some objects to the cache_dir.
2718 The coss file store has changed from 2.5. Now it uses a file
2719 called 'stripe' in the directory names in the config - and
2720 this will be created by squid -z.
2724 no-store, no new objects should be stored to this cache_dir
2726 min-size=n, refers to the min object size in bytes this cache_dir
2727 will accept. It's used to restrict a cache_dir to only store
2728 large objects (e.g. aufs) while other storedirs are optimized
2729 for smaller objects (e.g. COSS). Defaults to 0.
2731 max-size=n, refers to the max object size in bytes this cache_dir
2732 supports. It is used to select the cache_dir to store the object.
2733 Note: To make optimal use of the max-size limits you should order
2734 the cache_dir lines with the smallest max-size value first and the
2735 ones with no max-size specification last.
2737 Note for coss, max-size must be less than COSS_MEMBUF_SZ,
2738 which can be changed with the --with-coss-membuf-size=N configure
2742 # Uncomment and adjust the following to add a disk cache directory.
2743 #cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
2747 NAME: store_dir_select_algorithm
2749 LOC: Config.store_dir_select_algorithm
2752 Set this to 'round-robin' as an alternative.
2755 NAME: max_open_disk_fds
2757 LOC: Config.max_open_disk_fds
2760 To avoid having disk as the I/O bottleneck Squid can optionally
2761 bypass the on-disk cache if more than this amount of disk file
2762 descriptors are open.
2764 A value of 0 indicates no limit.
2767 NAME: minimum_object_size
2771 LOC: Config.Store.minObjectSize
2773 Objects smaller than this size will NOT be saved on disk. The
2774 value is specified in kilobytes, and the default is 0 KB, which
2775 means there is no minimum.
2778 NAME: maximum_object_size
2782 LOC: Config.Store.maxObjectSize
2784 Objects larger than this size will NOT be saved on disk. The
2785 value is specified in kilobytes, and the default is 4MB. If
2786 you wish to get a high BYTES hit ratio, you should probably
2787 increase this (one 32 MB object hit counts for 3200 10KB
2788 hits). If you wish to increase speed more than your want to
2789 save bandwidth you should leave this low.
2791 NOTE: if using the LFUDA replacement policy you should increase
2792 this value to maximize the byte hit rate improvement of LFUDA!
2793 See replacement_policy below for a discussion of this policy.
2796 NAME: cache_swap_low
2797 COMMENT: (percent, 0-100)
2800 LOC: Config.Swap.lowWaterMark
2803 NAME: cache_swap_high
2804 COMMENT: (percent, 0-100)
2807 LOC: Config.Swap.highWaterMark
2810 The low- and high-water marks for cache object replacement.
2811 Replacement begins when the swap (disk) usage is above the
2812 low-water mark and attempts to maintain utilization near the
2813 low-water mark. As swap utilization gets close to high-water
2814 mark object eviction becomes more aggressive. If utilization is
2815 close to the low-water mark less replacement is done each time.
2817 Defaults are 90% and 95%. If you have a large cache, 5% could be
2818 hundreds of MB. If this is the case you may wish to set these
2819 numbers closer together.
2824 -----------------------------------------------------------------------------
2834 logformat <name> <format specification>
2836 Defines an access log format.
2838 The <format specification> is a string with embedded % format codes
2840 % format codes all follow the same basic structure where all but
2841 the formatcode is optional. Output strings are automatically escaped
2842 as required according to their context and the output format
2843 modifiers are usually not needed, but can be specified if an explicit
2844 output format is desired.
2846 % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
2848 " output in quoted string format
2849 [ output in squid text log format as used by log_mime_hdrs
2850 # output in URL quoted format
2854 width field width. If starting with 0 the
2855 output is zero padded
2856 {arg} argument such as header name etc
2860 % a literal % character
2861 sn Unique sequence number per log line entry
2862 err_code The ID of an error response served by Squid or
2863 a similar internal error identifier.
2864 err_detail Additional err_code-dependent error information.
2866 Connection related format codes:
2868 >a Client source IP address
2870 >p Client source port
2871 >eui Client EUI (MAC address, EUI-48 or EUI-64 identifier)
2872 <A Server IP address or peer name
2873 la Local IP address (http_port)
2874 lp Local port number (http_port)
2875 <lp Local port number of the last server or peer connection
2877 Time related format codes:
2879 ts Seconds since epoch
2880 tu subsecond time (milliseconds)
2881 tl Local time. Optional strftime format argument
2882 default %d/%b/%Y:%H:%M:%S %z
2883 tg GMT time. Optional strftime format argument
2884 default %d/%b/%Y:%H:%M:%S %z
2885 tr Response time (milliseconds)
2886 dt Total time spent making DNS lookups (milliseconds)
2888 HTTP cache related format codes:
2890 [http::]>h Original request header. Optional header name argument
2891 on the format header[:[separator]element]
2892 [http::]>ha The HTTP request headers after adaptation and redirection.
2893 Optional header name argument as for >h
2894 [http::]<h Reply header. Optional header name argument
2896 [http::]un User name
2897 [http::]ul User name from authentication
2898 [http::]ui User name from ident
2899 [http::]us User name from SSL
2900 [http::]ue User name from external acl helper
2901 [http::]>Hs HTTP status code sent to the client
2902 [http::]<Hs HTTP status code received from the next hop
2903 [http::]<bs Number of HTTP-equivalent message body bytes
2904 received from the next hop, excluding chunked
2905 transfer encoding and control messages.
2906 Generated FTP/Gopher listings are treated as
2908 [http::]Ss Squid request status (TCP_MISS etc)
2909 [http::]Sh Squid hierarchy status (DEFAULT_PARENT etc)
2910 [http::]mt MIME content type
2911 [http::]rm Request method (GET/POST etc)
2912 [http::]ru Request URL
2913 [http::]rp Request URL-Path excluding hostname
2914 [http::]rv Request protocol version
2915 [http::]et Tag returned by external acl
2916 [http::]ea Log string returned by external acl
2917 [http::]<st Sent reply size including HTTP headers
2918 [http::]>st Received request size including HTTP headers. In the
2919 case of chunked requests the chunked encoding metadata
2921 [http::]>sh Received HTTP request headers size
2922 [http::]<sh Sent HTTP reply headers size
2923 [http::]st Request+Reply size including HTTP headers
2924 [http::]<sH Reply high offset sent
2925 [http::]<sS Upstream object size
2926 [http::]<pt Peer response time in milliseconds. The timer starts
2927 when the last request byte is sent to the next hop
2928 and stops when the last response byte is received.
2929 [http::]<tt Total server-side time in milliseconds. The timer
2930 starts with the first connect request (or write I/O)
2931 sent to the first selected peer. The timer stops
2932 with the last I/O with the last peer.
2934 If ICAP is enabled, the following two codes become available (as
2935 well as ICAP log codes documented with the icap_log option):
2937 icap::tt Total ICAP processing time for the HTTP
2938 transaction. The timer ticks when ICAP
2939 ACLs are checked and when ICAP
2940 transaction is in progress.
2942 icap::<last_h The header of the last ICAP response
2943 related to the HTTP transaction. Like
2944 <h, accepts an optional header name
2945 argument. Will not change semantics
2946 when multiple ICAP transactions per HTTP
2947 transaction are supported.
2949 If adaptation is enabled the following two codes become available:
2951 adapt::sum_trs Summed adaptation transaction response
2952 times recorded as a comma-separated list in
2953 the order of transaction start time. Each time
2954 value is recorded as an integer number,
2955 representing response time of one or more
2956 adaptation (ICAP or eCAP) transaction in
2957 milliseconds. When a failed transaction is
2958 being retried or repeated, its time is not
2959 logged individually but added to the
2960 replacement (next) transaction. See also:
2963 adapt::all_trs All adaptation transaction response times.
2964 Same as adaptation_strs but response times of
2965 individual transactions are never added
2966 together. Instead, all transaction response
2967 times are recorded individually.
2969 You can prefix adapt::*_trs format codes with adaptation
2970 service name in curly braces to record response time(s) specific
2971 to that service. For example: %{my_service}adapt::sum_trs
2973 The default formats available (which do not need re-defining) are:
2975 logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt
2976 logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
2977 logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
2978 logformat referrer %ts.%03tu %>a %{Referer}>h %ru
2979 logformat useragent %>a [%tl] "%{User-Agent}>h"
2981 When the log_mime_hdrs directive is set to ON. The squid, common and combined
2982 formats have a safely encoded copy of the mime headers appended to each line
2983 within a pair of brackets.
2985 The common and combined formats are not quite true to the Apache definition.
2986 The logs from Squid contain an extra status and hierarchy code appended.
2989 NAME: access_log cache_access_log
2991 LOC: Config.Log.accesslogs
2992 DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
2994 These files log client request activities. Has a line every HTTP or
2995 ICP request. The format is:
2996 access_log <module>:<place> [<logformat name> [acl acl ...]]
2997 access_log none [acl acl ...]]
2999 Will log to the specified module:place using the specified format (which
3000 must be defined in a logformat directive) those entries which match
3001 ALL the acl's specified (which must be defined in acl clauses).
3002 If no acl is specified, all requests will be logged to this destination.
3004 ===== Modules Currently available =====
3006 none Do not log any requests matching these ACL.
3007 Do not specify Place or logformat name.
3009 stdio Write each log line to disk immediately at the completion of
3011 Place: the filename and path to be written.
3013 daemon Very similar to stdio. But instead of writing to disk the log
3014 line is passed to a daemon helper for asychronous handling instead.
3015 Place: varies depending on the daemon.
3017 log_file_daemon Place: the file name and path to be written.
3019 syslog To log each request via syslog facility.
3020 Place: The syslog facility and priority level for these entries.
3021 Place Format: facility.priority
3023 where facility could be any of:
3024 authpriv, daemon, local0 ... local7 or user.
3026 And priority could be any of:
3027 err, warning, notice, info, debug.
3029 udp To send each log line as text data to a UDP receiver.
3030 Place: The destination host name or IP and port.
3031 Place Format: \\host:port
3033 tcp To send each log line as text data to a TCP receiver.
3034 Place: The destination host name or IP and port.
3035 Place Format: \\host:port
3038 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
3044 LOC: Config.Log.icaplogs
3047 ICAP log files record ICAP transaction summaries, one line per
3050 The icap_log option format is:
3051 icap_log <filepath> [<logformat name> [acl acl ...]]
3052 icap_log none [acl acl ...]]
3054 Please see access_log option documentation for details. The two
3055 kinds of logs share the overall configuration approach and many
3058 ICAP processing of a single HTTP message or transaction may
3059 require multiple ICAP transactions. In such cases, multiple
3060 ICAP transaction log lines will correspond to a single access
3063 ICAP log uses logformat codes that make sense for an ICAP
3064 transaction. Header-related codes are applied to the HTTP header
3065 embedded in an ICAP server response, with the following caveats:
3066 For REQMOD, there is no HTTP response header unless the ICAP
3067 server performed request satisfaction. For RESPMOD, the HTTP
3068 request header is the header sent to the ICAP server. For
3069 OPTIONS, there are no HTTP headers.
3071 The following format codes are also available for ICAP logs:
3073 icap::<A ICAP server IP address. Similar to <A.
3075 icap::<service_name ICAP service name from the icap_service
3076 option in Squid configuration file.
3078 icap::ru ICAP Request-URI. Similar to ru.
3080 icap::rm ICAP request method (REQMOD, RESPMOD, or
3081 OPTIONS). Similar to existing rm.
3083 icap::>st Bytes sent to the ICAP server (TCP payload
3084 only; i.e., what Squid writes to the socket).
3086 icap::<st Bytes received from the ICAP server (TCP
3087 payload only; i.e., what Squid reads from
3090 icap::<bs Number of message body bytes received from the
3091 ICAP server. ICAP message body, if any, usually
3092 includes encapsulated HTTP message headers and
3093 possibly encapsulated HTTP message body. The
3094 HTTP body part is dechunked before its size is
3097 icap::tr Transaction response time (in
3098 milliseconds). The timer starts when
3099 the ICAP transaction is created and
3100 stops when the transaction is completed.
3103 icap::tio Transaction I/O time (in milliseconds). The
3104 timer starts when the first ICAP request
3105 byte is scheduled for sending. The timers
3106 stops when the last byte of the ICAP response
3109 icap::to Transaction outcome: ICAP_ERR* for all
3110 transaction errors, ICAP_OPT for OPTION
3111 transactions, ICAP_ECHO for 204
3112 responses, ICAP_MOD for message
3113 modification, and ICAP_SAT for request
3114 satisfaction. Similar to Ss.
3116 icap::Hs ICAP response status code. Similar to Hs.
3118 icap::>h ICAP request header(s). Similar to >h.
3120 icap::<h ICAP response header(s). Similar to <h.
3122 The default ICAP log format, which can be used without an explicit
3123 definition, is called icap_squid:
3125 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
3127 See also: logformat, log_icap, and %icap::<last_h
3130 NAME: logfile_daemon
3132 DEFAULT: @DEFAULT_LOGFILED@
3133 LOC: Log::TheConfig.logfile_daemon
3135 Specify the path to the logfile-writing daemon. This daemon is
3136 used to write the access and store logs, if configured.
3138 Squid sends a number of commands to the log daemon:
3139 L<data>\n - logfile data
3144 r<n>\n - set rotate count to <n>
3145 b<n>\n - 1 = buffer output, 0 = don't buffer output
3147 No responses is expected.
3152 LOC: Config.accessList.log
3154 COMMENT: allow|deny acl acl...
3156 This options allows you to control which requests gets logged
3157 to access.log (see access_log directive). Requests denied for
3158 logging will also not be accounted for in performance counters.
3160 This clause only supports fast acl types.
3161 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3167 LOC: Config.accessList.icap
3170 This options allows you to control which requests get logged
3171 to icap.log. See the icap_log directive for ICAP log details.
3174 NAME: cache_store_log
3177 LOC: Config.Log.store
3179 Logs the activities of the storage manager. Shows which
3180 objects are ejected from the cache, and which objects are
3181 saved and for how long. To disable, enter "none" or remove the line.
3182 There are not really utilities to analyze this data, so you can safely
3186 cache_store_log @DEFAULT_STORE_LOG@
3189 NAME: cache_swap_state cache_swap_log
3191 LOC: Config.Log.swap
3194 Location for the cache "swap.state" file. This index file holds
3195 the metadata of objects saved on disk. It is used to rebuild
3196 the cache during startup. Normally this file resides in each
3197 'cache_dir' directory, but you may specify an alternate
3198 pathname here. Note you must give a full filename, not just
3199 a directory. Since this is the index for the whole object
3200 list you CANNOT periodically rotate it!
3202 If %s can be used in the file name it will be replaced with a
3203 a representation of the cache_dir name where each / is replaced
3204 with '.'. This is needed to allow adding/removing cache_dir
3205 lines when cache_swap_log is being used.
3207 If have more than one 'cache_dir', and %s is not used in the name
3208 these swap logs will have names such as:
3214 The numbered extension (which is added automatically)
3215 corresponds to the order of the 'cache_dir' lines in this
3216 configuration file. If you change the order of the 'cache_dir'
3217 lines in this file, these index files will NOT correspond to
3218 the correct 'cache_dir' entry (unless you manually rename
3219 them). We recommend you do NOT use this option. It is
3220 better to keep these index files in each 'cache_dir' directory.
3223 NAME: logfile_rotate
3226 LOC: Config.Log.rotateNumber
3228 Specifies the number of logfile rotations to make when you
3229 type 'squid -k rotate'. The default is 10, which will rotate
3230 with extensions 0 through 9. Setting logfile_rotate to 0 will
3231 disable the file name rotation, but the logfiles are still closed
3232 and re-opened. This will enable you to rename the logfiles
3233 yourself just before sending the rotate signal.
3235 Note, the 'squid -k rotate' command normally sends a USR1
3236 signal to the running squid process. In certain situations
3237 (e.g. on Linux with Async I/O), USR1 is used for other
3238 purposes, so -k rotate uses another signal. It is best to get
3239 in the habit of using 'squid -k rotate' instead of 'kill -USR1
3242 Note, from Squid-3.1 this option has no effect on the cache.log,
3243 that log can be rotated separately by using debug_options
3246 NAME: emulate_httpd_log
3249 Replace this with an access_log directive using the format 'common' or 'combined'.
3252 NAME: log_ip_on_direct
3256 LOC: Config.onoff.log_ip_on_direct
3258 Log the destination IP address in the hierarchy log tag when going
3259 direct. Earlier Squid versions logged the hostname here. If you
3260 prefer the old way set this to off.
3265 DEFAULT: @DEFAULT_MIME_TABLE@
3266 LOC: Config.mimeTablePathname
3268 Pathname to Squid's MIME table. You shouldn't need to change
3269 this, but the default file contains examples and formatting
3270 information if you do.
3276 LOC: Config.onoff.log_mime_hdrs
3279 The Cache can record both the request and the response MIME
3280 headers for each HTTP transaction. The headers are encoded
3281 safely and will appear as two bracketed fields at the end of
3282 the access log (for either the native or httpd-emulated log
3283 formats). To enable this logging set log_mime_hdrs to 'on'.
3289 Replace this with an access_log directive using the format 'useragent'.
3292 NAME: referer_log referrer_log
3295 Replace this with an access_log directive using the format 'referrer'.
3300 DEFAULT: @DEFAULT_PID_FILE@
3301 LOC: Config.pidFilename
3303 A filename to write the process-id to. To disable, enter "none".
3309 Remove this option from your config. To log FQDN use %>A in the log format.
3312 NAME: client_netmask
3314 LOC: Config.Addrs.client_netmask
3317 A netmask for client addresses in logfiles and cachemgr output.
3318 Change this to protect the privacy of your cache clients.
3319 A netmask of 255.255.255.0 will log all IP's in that range with
3320 the last digit set to '0'.
3326 Use a regular access.log with ACL limiting it to MISS events.
3329 NAME: strip_query_terms
3331 LOC: Config.onoff.strip_query_terms
3334 By default, Squid strips query terms from requested URLs before
3335 logging. This protects your user's privacy.
3342 LOC: Config.onoff.buffered_logs
3344 cache.log log file is written with stdio functions, and as such
3345 it can be buffered or unbuffered. By default it will be unbuffered.
3346 Buffering it can speed up the writing slightly (though you are
3347 unlikely to need to worry unless you run with tons of debugging
3348 enabled in which case performance will suffer badly anyway..).
3351 NAME: netdb_filename
3353 DEFAULT: @DEFAULT_NETDB_FILE@
3354 LOC: Config.netdbFilename
3357 A filename where Squid stores it's netdb state between restarts.
3358 To disable, enter "none".
3362 OPTIONS FOR TROUBLESHOOTING
3363 -----------------------------------------------------------------------------
3368 DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
3369 LOC: Debug::cache_log
3371 Cache logging file. This is where general information about
3372 your cache's behavior goes. You can increase the amount of data
3373 logged to this file and how often its rotated with "debug_options"
3379 LOC: Debug::debugOptions
3381 Logging options are set as section,level where each source file
3382 is assigned a unique section. Lower levels result in less
3383 output, Full debugging (level 9) can result in a very large
3384 log file, so be careful.
3386 The magic word "ALL" sets debugging levels for all sections.
3387 We recommend normally running with "ALL,1".
3389 The rotate=N option can be used to keep more or less of these logs
3390 than would otherwise be kept by logfile_rotate.
3391 For most uses a single log should be enough to monitor current
3392 events affecting Squid.
3397 LOC: Config.coredump_dir
3398 DEFAULT_IF_NONE: none
3400 By default Squid leaves core files in the directory from where
3401 it was started. If you set 'coredump_dir' to a directory
3402 that exists, Squid will chdir() to that directory at startup
3403 and coredump files will be left there.
3407 # Leave coredumps in the first cache dir
3408 coredump_dir @DEFAULT_SWAP_DIR@
3414 OPTIONS FOR FTP GATEWAYING
3415 -----------------------------------------------------------------------------
3421 LOC: Config.Ftp.anon_user
3423 If you want the anonymous login password to be more informative
3424 (and enable the use of picky ftp servers), set this to something
3425 reasonable for your domain, like wwwuser@somewhere.net
3427 The reason why this is domainless by default is the
3428 request can be made on the behalf of a user in any domain,
3429 depending on how the cache is used.
3430 Some ftp server also validate the email address is valid
3431 (for example perl.com).
3437 LOC: Config.Ftp.passive
3439 If your firewall does not allow Squid to use passive
3440 connections, turn off this option.
3442 Use of ftp_epsv_all option requires this to be ON.
3448 LOC: Config.Ftp.epsv_all
3450 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
3452 NATs may be able to put the connection on a "fast path" through the
3453 translator, as the EPRT command will never be used and therefore,
3454 translation of the data portion of the segments will never be needed.
3456 When a client only expects to do two-way FTP transfers this may be
3458 If squid finds that it must do a three-way FTP transfer after issuing
3459 an EPSV ALL command, the FTP session will fail.
3461 If you have any doubts about this option do not use it.
3462 Squid will nicely attempt all other connection methods.
3464 Requires ftp_passive to be ON (default) for any effect.
3470 LOC: Config.Ftp.epsv
3472 FTP Protocol extensions permit the use of a special "EPSV" command.
3474 NATs may be able to put the connection on a "fast path" through the
3475 translator using EPSV, as the EPRT command will never be used
3476 and therefore, translation of the data portion of the segments
3477 will never be needed.
3479 Turning this OFF will prevent EPSV being attempted.
3480 WARNING: Doing so will convert Squid back to the old behavior with all
3481 the related problems with external NAT devices/layers.
3483 Requires ftp_passive to be ON (default) for any effect.
3489 LOC: Config.Ftp.eprt
3491 FTP Protocol extensions permit the use of a special "EPRT" command.
3493 This extension provides a protocol neutral alternative to the
3494 IPv4-only PORT command. When supported it enables active FTP data
3495 channels over IPv6 and efficient NAT handling.
3497 Turning this OFF will prevent EPRT being attempted and will skip
3498 straight to using PORT for IPv4 servers.
3500 Some devices are known to not handle this extension correctly and
3501 may result in crashes. Devices which suport EPRT enough to fail
3502 cleanly will result in Squid attempting PORT anyway. This directive
3503 should only be disabled when EPRT results in device failures.
3505 WARNING: Doing so will convert Squid back to the old behavior with all
3506 the related problems with external NAT devices/layers and IPv4-only FTP.
3509 NAME: ftp_sanitycheck
3512 LOC: Config.Ftp.sanitycheck
3514 For security and data integrity reasons Squid by default performs
3515 sanity checks of the addresses of FTP data connections ensure the
3516 data connection is to the requested server. If you need to allow
3517 FTP connections to servers using another IP address for the data
3518 connection turn this off.
3521 NAME: ftp_telnet_protocol
3524 LOC: Config.Ftp.telnet
3526 The FTP protocol is officially defined to use the telnet protocol
3527 as transport channel for the control connection. However, many
3528 implementations are broken and does not respect this aspect of
3531 If you have trouble accessing files with ASCII code 255 in the
3532 path or similar problems involving this ASCII code you can
3533 try setting this directive to off. If that helps, report to the
3534 operator of the FTP server in question that their FTP server
3535 is broken and does not follow the FTP standard.
3539 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
3540 -----------------------------------------------------------------------------
3545 DEFAULT: @DEFAULT_DISKD@
3546 LOC: Config.Program.diskd
3548 Specify the location of the diskd executable.
3549 Note this is only useful if you have compiled in
3550 diskd as one of the store io modules.
3553 NAME: unlinkd_program
3556 DEFAULT: @DEFAULT_UNLINKD@
3557 LOC: Config.Program.unlinkd
3559 Specify the location of the executable for file deletion process.
3562 NAME: pinger_program
3564 DEFAULT: @DEFAULT_PINGER@
3565 LOC: Config.pinger.program
3568 Specify the location of the executable for the pinger process.
3574 LOC: Config.pinger.enable
3577 Control whether the pinger is active at run-time.
3578 Enables turning ICMP pinger on and off with a simple
3579 squid -k reconfigure.
3584 OPTIONS FOR URL REWRITING
3585 -----------------------------------------------------------------------------
3588 NAME: url_rewrite_program redirect_program
3590 LOC: Config.Program.redirect
3593 Specify the location of the executable for the URL rewriter.
3594 Since they can perform almost any function there isn't one included.
3596 For each requested URL rewriter will receive on line with the format
3598 URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
3600 In the future, the rewriter interface will be extended with
3601 key=value pairs ("kvpairs" shown above). Rewriter programs
3602 should be prepared to receive and possibly ignore additional
3603 whitespace-separated tokens on each input line.
3605 And the rewriter may return a rewritten URL. The other components of
3606 the request line does not need to be returned (ignored if they are).
3608 The rewriter can also indicate that a client-side redirect should
3609 be performed to the new URL. This is done by prefixing the returned
3610 URL with "301:" (moved permanently) or 302: (moved temporarily).
3612 By default, a URL rewriter is not used.
3615 NAME: url_rewrite_children redirect_children
3616 TYPE: HelperChildConfig
3617 DEFAULT: 20 startup=0 idle=1 concurrency=0
3618 LOC: Config.redirectChildren
3620 The maximum number of redirector processes to spawn. If you limit
3621 it too few Squid will have to wait for them to process a backlog of
3622 URLs, slowing it down. If you allow too many they will use RAM
3623 and other system resources noticably.
3625 The startup= and idle= options allow some measure of skew in your
3630 Sets a minimum of how many processes are to be spawned when Squid
3631 starts or reconfigures. When set to zero the first request will
3632 cause spawning of the first child process to handle it.
3634 Starting too few will cause an initial slowdown in traffic as Squid
3635 attempts to simultaneously spawn enough processes to cope.
3639 Sets a minimum of how many processes Squid is to try and keep available
3640 at all times. When traffic begins to rise above what the existing
3641 processes can handle this many more will be spawned up to the maximum
3642 configured. A minimum setting of 1 is required.
3646 The number of requests each redirector helper can handle in
3647 parallel. Defaults to 0 which indicates the redirector
3648 is a old-style single threaded redirector.
3650 When this directive is set to a value >= 1 then the protocol
3651 used to communicate with the helper is modified to include
3652 a request ID in front of the request/response. The request
3653 ID from the request must be echoed back with the response
3657 NAME: url_rewrite_host_header redirect_rewrites_host_header
3660 LOC: Config.onoff.redir_rewrites_host
3662 By default Squid rewrites any Host: header in redirected
3663 requests. If you are running an accelerator this may
3664 not be a wanted effect of a redirector.
3666 WARNING: Entries are cached on the result of the URL rewriting
3667 process, so be careful if you have domain-virtual hosts.
3670 NAME: url_rewrite_access redirector_access
3673 LOC: Config.accessList.redirector
3675 If defined, this access list specifies which requests are
3676 sent to the redirector processes. By default all requests
3679 This clause supports both fast and slow acl types.
3680 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3683 NAME: url_rewrite_bypass redirector_bypass
3685 LOC: Config.onoff.redirector_bypass
3688 When this is 'on', a request will not go through the
3689 redirector if all redirectors are busy. If this is 'off'
3690 and the redirector queue grows too large, Squid will exit
3691 with a FATAL error and ask you to increase the number of
3692 redirectors. You should only enable this if the redirectors
3693 are not critical to your caching system. If you use
3694 redirectors for access control, and you enable this option,
3695 users may have access to pages they should not
3696 be allowed to request.
3700 OPTIONS FOR TUNING THE CACHE
3701 -----------------------------------------------------------------------------
3704 NAME: cache no_cache
3707 LOC: Config.accessList.noCache
3709 A list of ACL elements which, if matched and denied, cause the request to
3710 not be satisfied from the cache and the reply to not be cached.
3711 In other words, use this to force certain objects to never be cached.
3713 You must use the words 'allow' or 'deny' to indicate whether items
3714 matching the ACL should be allowed or denied into the cache.
3716 Default is to allow all to be cached.
3718 This clause supports both fast and slow acl types.
3719 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3725 LOC: Config.maxStale
3728 This option puts an upper limit on how stale content Squid
3729 will serve from the cache if cache validation fails.
3730 Can be overriden by the refresh_pattern max-stale option.
3733 NAME: refresh_pattern
3734 TYPE: refreshpattern
3738 usage: refresh_pattern [-i] regex min percent max [options]
3740 By default, regular expressions are CASE-SENSITIVE. To make
3741 them case-insensitive, use the -i option.
3743 'Min' is the time (in minutes) an object without an explicit
3744 expiry time should be considered fresh. The recommended
3745 value is 0, any higher values may cause dynamic applications
3746 to be erroneously cached unless the application designer
3747 has taken the appropriate actions.
3749 'Percent' is a percentage of the objects age (time since last
3750 modification age) an object without explicit expiry time
3751 will be considered fresh.
3753 'Max' is an upper limit on how long objects without an explicit
3754 expiry time will be considered fresh.
3756 options: override-expire
3762 ignore-must-revalidate
3769 override-expire enforces min age even if the server
3770 sent an explicit expiry time (e.g., with the
3771 Expires: header or Cache-Control: max-age). Doing this
3772 VIOLATES the HTTP standard. Enabling this feature
3773 could make you liable for problems which it causes.
3775 Note: override-expire does not enforce staleness - it only extends
3776 freshness / min. If the server returns a Expires time which
3777 is longer than your max time, Squid will still consider
3778 the object fresh for that period of time.
3780 override-lastmod enforces min age even on objects
3781 that were modified recently.
3783 reload-into-ims changes client no-cache or ``reload''
3784 to If-Modified-Since requests. Doing this VIOLATES the
3785 HTTP standard. Enabling this feature could make you
3786 liable for problems which it causes.
3788 ignore-reload ignores a client no-cache or ``reload''
3789 header. Doing this VIOLATES the HTTP standard. Enabling
3790 this feature could make you liable for problems which
3793 ignore-no-cache ignores any ``Pragma: no-cache'' and
3794 ``Cache-control: no-cache'' headers received from a server.
3795 The HTTP RFC never allows the use of this (Pragma) header
3796 from a server, only a client, though plenty of servers
3799 ignore-no-store ignores any ``Cache-control: no-store''
3800 headers received from a server. Doing this VIOLATES
3801 the HTTP standard. Enabling this feature could make you
3802 liable for problems which it causes.
3804 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
3805 headers received from a server. Doing this VIOLATES
3806 the HTTP standard. Enabling this feature could make you
3807 liable for problems which it causes.
3809 ignore-private ignores any ``Cache-control: private''
3810 headers received from a server. Doing this VIOLATES
3811 the HTTP standard. Enabling this feature could make you
3812 liable for problems which it causes.
3814 ignore-auth caches responses to requests with authorization,
3815 as if the originserver had sent ``Cache-control: public''
3816 in the response header. Doing this VIOLATES the HTTP standard.
3817 Enabling this feature could make you liable for problems which
3820 refresh-ims causes squid to contact the origin server
3821 when a client issues an If-Modified-Since request. This
3822 ensures that the client will receive an updated version
3823 if one is available.
3825 store-stale stores responses even if they don't have explicit
3826 freshness or a validator (i.e., Last-Modified or an ETag)
3827 present, or if they're already stale. By default, Squid will
3828 not cache such responses because they usually can't be
3829 reused. Note that such responses will be stale by default.
3831 max-stale=NN provide a maximum staleness factor. Squid won't
3832 serve objects more stale than this even if it failed to
3833 validate the object. Default: use the max_stale global limit.
3835 Basically a cached object is:
3837 FRESH if expires < now, else STALE
3839 FRESH if lm-factor < percent, else STALE
3843 The refresh_pattern lines are checked in the order listed here.
3844 The first entry which matches is used. If none of the entries
3845 match the default will be used.
3847 Note, you must uncomment all the default lines if you want
3848 to change one. The default setting is only active if none is
3853 # Add any of your own refresh_pattern entries above these.
3854 refresh_pattern ^ftp: 1440 20% 10080
3855 refresh_pattern ^gopher: 1440 0% 1440
3856 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
3857 refresh_pattern . 0 20% 4320
3861 NAME: quick_abort_min
3865 LOC: Config.quickAbort.min
3868 NAME: quick_abort_max
3872 LOC: Config.quickAbort.max
3875 NAME: quick_abort_pct
3879 LOC: Config.quickAbort.pct
3881 The cache by default continues downloading aborted requests
3882 which are almost completed (less than 16 KB remaining). This
3883 may be undesirable on slow (e.g. SLIP) links and/or very busy
3884 caches. Impatient users may tie up file descriptors and
3885 bandwidth by repeatedly requesting and immediately aborting
3888 When the user aborts a request, Squid will check the
3889 quick_abort values to the amount of data transfered until
3892 If the transfer has less than 'quick_abort_min' KB remaining,
3893 it will finish the retrieval.
3895 If the transfer has more than 'quick_abort_max' KB remaining,
3896 it will abort the retrieval.
3898 If more than 'quick_abort_pct' of the transfer has completed,
3899 it will finish the retrieval.
3901 If you do not want any retrieval to continue after the client
3902 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
3905 If you want retrievals to always continue if they are being
3906 cached set 'quick_abort_min' to '-1 KB'.
3909 NAME: read_ahead_gap
3910 COMMENT: buffer-size
3912 LOC: Config.readAheadGap
3915 The amount of data the cache will buffer ahead of what has been
3916 sent to the client when retrieving an object from another server.
3920 IFDEF: USE_HTTP_VIOLATIONS
3923 LOC: Config.negativeTtl
3926 Set the Default Time-to-Live (TTL) for failed requests.
3927 Certain types of failures (such as "connection refused" and
3928 "404 Not Found") are able to be negatively-cached for a short time.
3929 Modern web servers should provide Expires: header, however if they
3930 do not this can provide a minimum TTL.
3931 The default is not to cache errors with unknown expiry details.
3933 Note that this is different from negative caching of DNS lookups.
3935 WARNING: Doing this VIOLATES the HTTP standard. Enabling
3936 this feature could make you liable for problems which it
3940 NAME: positive_dns_ttl
3943 LOC: Config.positiveDnsTtl
3946 Upper limit on how long Squid will cache positive DNS responses.
3947 Default is 6 hours (360 minutes). This directive must be set
3948 larger than negative_dns_ttl.
3951 NAME: negative_dns_ttl
3954 LOC: Config.negativeDnsTtl
3957 Time-to-Live (TTL) for negative caching of failed DNS lookups.
3958 This also sets the lower cache limit on positive lookups.
3959 Minimum value is 1 second, and it is not recommendable to go
3960 much below 10 seconds.
3963 NAME: range_offset_limit
3964 COMMENT: size [acl acl...]
3966 LOC: Config.rangeOffsetLimit
3969 usage: (size) [units] [[!]aclname]
3971 Sets an upper limit on how far (number of bytes) into the file
3972 a Range request may be to cause Squid to prefetch the whole file.
3973 If beyond this limit, Squid forwards the Range request as it is and
3974 the result is NOT cached.
3976 This is to stop a far ahead range request (lets say start at 17MB)
3977 from making Squid fetch the whole object up to that point before
3978 sending anything to the client.
3980 Multiple range_offset_limit lines may be specified, and they will
3981 be searched from top to bottom on each request until a match is found.
3982 The first match found will be used. If no line matches a request, the
3983 default limit of 0 bytes will be used.
3985 'size' is the limit specified as a number of units.
3987 'units' specifies whether to use bytes, KB, MB, etc.
3988 If no units are specified bytes are assumed.
3990 A size of 0 causes Squid to never fetch more than the
3991 client requested. (default)
3993 A size of 'none' causes Squid to always fetch the object from the
3994 beginning so it may cache the result. (2.0 style)
3996 'aclname' is the name of a defined ACL.
3998 NP: Using 'none' as the byte value here will override any quick_abort settings
3999 that may otherwise apply to the range request. The range request will
4000 be fully fetched from start to finish regardless of the client
4001 actions. This affects bandwidth usage.
4004 NAME: minimum_expiry_time
4007 LOC: Config.minimum_expiry_time
4010 The minimum caching time according to (Expires - Date)
4011 Headers Squid honors if the object can't be revalidated
4012 defaults to 60 seconds. In reverse proxy environments it
4013 might be desirable to honor shorter object lifetimes. It
4014 is most likely better to make your server return a
4015 meaningful Last-Modified header however. In ESI environments
4016 where page fragments often have short lifetimes, this will
4017 often be best set to 0.
4020 NAME: store_avg_object_size
4024 LOC: Config.Store.avgObjectSize
4026 Average object size, used to estimate number of objects your
4027 cache can hold. The default is 13 KB.
4030 NAME: store_objects_per_bucket
4033 LOC: Config.Store.objectsPerBucket
4035 Target number of objects per bucket in the store hash table.
4036 Lowering this value increases the total number of buckets and
4037 also the storage maintenance rate. The default is 20.
4042 -----------------------------------------------------------------------------
4045 NAME: request_header_max_size
4049 LOC: Config.maxRequestHeaderSize
4051 This specifies the maximum size for HTTP headers in a request.
4052 Request headers are usually relatively small (about 512 bytes).
4053 Placing a limit on the request header size will catch certain
4054 bugs (for example with persistent connections) and possibly
4055 buffer-overflow or denial-of-service attacks.
4058 NAME: reply_header_max_size
4062 LOC: Config.maxReplyHeaderSize
4064 This specifies the maximum size for HTTP headers in a reply.
4065 Reply headers are usually relatively small (about 512 bytes).
4066 Placing a limit on the reply header size will catch certain
4067 bugs (for example with persistent connections) and possibly
4068 buffer-overflow or denial-of-service attacks.
4071 NAME: request_body_max_size
4075 LOC: Config.maxRequestBodySize
4077 This specifies the maximum size for an HTTP request body.
4078 In other words, the maximum size of a PUT/POST request.
4079 A user who attempts to send a request with a body larger
4080 than this limit receives an "Invalid Request" error message.
4081 If you set this parameter to a zero (the default), there will
4082 be no limit imposed.
4085 NAME: client_request_buffer_max_size
4089 LOC: Config.maxRequestBufferSize
4091 This specifies the maximum buffer size of a client request.
4092 It prevents squid eating too much memory when somebody uploads
4096 NAME: chunked_request_body_max_size
4100 LOC: Config.maxChunkedRequestBodySize
4102 A broken or confused HTTP/1.1 client may send a chunked HTTP
4103 request to Squid. Squid does not have full support for that
4104 feature yet. To cope with such requests, Squid buffers the
4105 entire request and then dechunks request body to create a
4106 plain HTTP/1.0 request with a known content length. The plain
4107 request is then used by the rest of Squid code as usual.
4109 The option value specifies the maximum size of the buffer used
4110 to hold the request before the conversion. If the chunked
4111 request size exceeds the specified limit, the conversion
4112 fails, and the client receives an "unsupported request" error,
4113 as if dechunking was disabled.
4115 Dechunking is enabled by default. To disable conversion of
4116 chunked requests, set the maximum to zero.
4118 Request dechunking feature and this option in particular are a
4119 temporary hack. When chunking requests and responses are fully
4120 supported, there will be no need to buffer a chunked request.
4124 IFDEF: USE_HTTP_VIOLATIONS
4127 LOC: Config.accessList.brokenPosts
4129 A list of ACL elements which, if matched, causes Squid to send
4130 an extra CRLF pair after the body of a PUT/POST request.
4132 Some HTTP servers has broken implementations of PUT/POST,
4133 and rely on an extra CRLF pair sent by some WWW clients.
4135 Quote from RFC2616 section 4.1 on this matter:
4137 Note: certain buggy HTTP/1.0 client implementations generate an
4138 extra CRLF's after a POST request. To restate what is explicitly
4139 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
4140 a request with an extra CRLF.
4142 This clause only supports fast acl types.
4143 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4146 acl buggy_server url_regex ^http://....
4147 broken_posts allow buggy_server
4150 NAME: icap_uses_indirect_client
4153 IFDEF: FOLLOW_X_FORWARDED_FOR&&ICAP_CLIENT
4155 LOC: Adaptation::Icap::TheConfig.icap_uses_indirect_client
4157 Controls whether the indirect client address
4158 (see follow_x_forwarded_for) instead of the
4159 direct client address is passed to an ICAP
4160 server as "X-Client-IP".
4164 IFDEF: USE_HTTP_VIOLATIONS
4168 LOC: Config.onoff.via
4170 If set (default), Squid will include a Via header in requests and
4171 replies as required by RFC2616.
4177 LOC: Config.onoff.ie_refresh
4180 Microsoft Internet Explorer up until version 5.5 Service
4181 Pack 1 has an issue with transparent proxies, wherein it
4182 is impossible to force a refresh. Turning this on provides
4183 a partial fix to the problem, by causing all IMS-REFRESH
4184 requests from older IE versions to check the origin server
4185 for fresh content. This reduces hit ratio by some amount
4186 (~10% in my experience), but allows users to actually get
4187 fresh content when they want it. Note because Squid
4188 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
4189 of 5.5 is unchanged from old versions of Squid (i.e. a
4190 forced refresh is impossible). Newer versions of IE will,
4191 hopefully, continue to have the new behavior and will be
4192 handled based on that assumption. This option defaults to
4193 the old Squid behavior, which is better for hit ratios but
4194 worse for clients using IE, if they need to be able to
4195 force fresh content.
4198 NAME: vary_ignore_expire
4201 LOC: Config.onoff.vary_ignore_expire
4204 Many HTTP servers supporting Vary gives such objects
4205 immediate expiry time with no cache-control header
4206 when requested by a HTTP/1.0 client. This option
4207 enables Squid to ignore such expiry times until
4208 HTTP/1.1 is fully implemented.
4210 WARNING: If turned on this may eventually cause some
4211 varying objects not intended for caching to get cached.
4214 NAME: request_entities
4216 LOC: Config.onoff.request_entities
4219 Squid defaults to deny GET and HEAD requests with request entities,
4220 as the meaning of such requests are undefined in the HTTP standard
4221 even if not explicitly forbidden.
4223 Set this directive to on if you have clients which insists
4224 on sending request entities in GET or HEAD requests. But be warned
4225 that there is server software (both proxies and web servers) which
4226 can fail to properly process this kind of request which may make you
4227 vulnerable to cache pollution attacks if enabled.
4230 NAME: request_header_access
4231 IFDEF: USE_HTTP_VIOLATIONS
4232 TYPE: http_header_access[]
4233 LOC: Config.request_header_access
4236 Usage: request_header_access header_name allow|deny [!]aclname ...
4238 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4239 this feature could make you liable for problems which it
4242 This option replaces the old 'anonymize_headers' and the
4243 older 'http_anonymizer' option with something that is much
4244 more configurable. This new method creates a list of ACLs
4245 for each header, allowing you very fine-tuned header
4248 This option only applies to request headers, i.e., from the
4249 client to the server.
4251 You can only specify known headers for the header name.
4252 Other headers are reclassified as 'Other'. You can also
4253 refer to all the headers with 'All'.
4255 For example, to achieve the same behavior as the old
4256 'http_anonymizer standard' option, you should use:
4258 request_header_access From deny all
4259 request_header_access Referer deny all
4260 request_header_access Server deny all
4261 request_header_access User-Agent deny all
4262 request_header_access WWW-Authenticate deny all
4263 request_header_access Link deny all
4265 Or, to reproduce the old 'http_anonymizer paranoid' feature
4268 request_header_access Allow allow all
4269 request_header_access Authorization allow all
4270 request_header_access WWW-Authenticate allow all
4271 request_header_access Proxy-Authorization allow all
4272 request_header_access Proxy-Authenticate allow all
4273 request_header_access Cache-Control allow all
4274 request_header_access Content-Encoding allow all
4275 request_header_access Content-Length allow all
4276 request_header_access Content-Type allow all
4277 request_header_access Date allow all
4278 request_header_access Expires allow all
4279 request_header_access Host allow all
4280 request_header_access If-Modified-Since allow all
4281 request_header_access Last-Modified allow all
4282 request_header_access Location allow all
4283 request_header_access Pragma allow all
4284 request_header_access Accept allow all
4285 request_header_access Accept-Charset allow all
4286 request_header_access Accept-Encoding allow all
4287 request_header_access Accept-Language allow all
4288 request_header_access Content-Language allow all
4289 request_header_access Mime-Version allow all
4290 request_header_access Retry-After allow all
4291 request_header_access Title allow all
4292 request_header_access Connection allow all
4293 request_header_access All deny all
4295 although many of those are HTTP reply headers, and so should be
4296 controlled with the reply_header_access directive.
4298 By default, all headers are allowed (no anonymizing is
4302 NAME: reply_header_access
4303 IFDEF: USE_HTTP_VIOLATIONS
4304 TYPE: http_header_access[]
4305 LOC: Config.reply_header_access
4308 Usage: reply_header_access header_name allow|deny [!]aclname ...
4310 WARNING: Doing this VIOLATES the HTTP standard. Enabling
4311 this feature could make you liable for problems which it
4314 This option only applies to reply headers, i.e., from the
4315 server to the client.
4317 This is the same as request_header_access, but in the other
4320 This option replaces the old 'anonymize_headers' and the
4321 older 'http_anonymizer' option with something that is much
4322 more configurable. This new method creates a list of ACLs
4323 for each header, allowing you very fine-tuned header
4326 You can only specify known headers for the header name.
4327 Other headers are reclassified as 'Other'. You can also
4328 refer to all the headers with 'All'.
4330 For example, to achieve the same behavior as the old
4331 'http_anonymizer standard' option, you should use:
4333 reply_header_access From deny all
4334 reply_header_access Referer deny all
4335 reply_header_access Server deny all
4336 reply_header_access User-Agent deny all
4337 reply_header_access WWW-Authenticate deny all
4338 reply_header_access Link deny all
4340 Or, to reproduce the old 'http_anonymizer paranoid' feature
4343 reply_header_access Allow allow all
4344 reply_header_access Authorization allow all
4345 reply_header_access WWW-Authenticate allow all
4346 reply_header_access Proxy-Authorization allow all
4347 reply_header_access Proxy-Authenticate allow all
4348 reply_header_access Cache-Control allow all
4349 reply_header_access Content-Encoding allow all
4350 reply_header_access Content-Length allow all
4351 reply_header_access Content-Type allow all
4352 reply_header_access Date allow all
4353 reply_header_access Expires allow all
4354 reply_header_access Host allow all
4355 reply_header_access If-Modified-Since allow all
4356 reply_header_access Last-Modified allow all
4357 reply_header_access Location allow all
4358 reply_header_access Pragma allow all
4359 reply_header_access Accept allow all
4360 reply_header_access Accept-Charset allow all
4361 reply_header_access Accept-Encoding allow all
4362 reply_header_access Accept-Language allow all
4363 reply_header_access Content-Language allow all
4364 reply_header_access Mime-Version allow all
4365 reply_header_access Retry-After allow all
4366 reply_header_access Title allow all
4367 reply_header_access Connection allow all
4368 reply_header_access All deny all
4370 although the HTTP request headers won't be usefully controlled
4371 by this directive -- see request_header_access for details.
4373 By default, all headers are allowed (no anonymizing is
4377 NAME: header_replace
4378 IFDEF: USE_HTTP_VIOLATIONS
4379 TYPE: http_header_replace[]
4380 LOC: Config.request_header_access
4383 Usage: header_replace header_name message
4384 Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
4386 This option allows you to change the contents of headers
4387 denied with header_access above, by replacing them with
4388 some fixed string. This replaces the old fake_user_agent
4391 This only applies to request headers, not reply headers.
4393 By default, headers are removed if denied.
4396 NAME: relaxed_header_parser
4397 COMMENT: on|off|warn
4399 LOC: Config.onoff.relaxed_header_parser
4402 In the default "on" setting Squid accepts certain forms
4403 of non-compliant HTTP messages where it is unambiguous
4404 what the sending application intended even if the message
4405 is not correctly formatted. The messages is then normalized
4406 to the correct form when forwarded by Squid.
4408 If set to "warn" then a warning will be emitted in cache.log
4409 each time such HTTP error is encountered.
4411 If set to "off" then such HTTP errors will cause the request
4412 or response to be rejected.
4417 -----------------------------------------------------------------------------
4420 NAME: forward_timeout
4423 LOC: Config.Timeout.forward
4426 This parameter specifies how long Squid should at most attempt in
4427 finding a forwarding path for the request before giving up.
4430 NAME: connect_timeout
4433 LOC: Config.Timeout.connect
4436 This parameter specifies how long to wait for the TCP connect to
4437 the requested server or peer to complete before Squid should
4438 attempt to find another path where to forward the request.
4441 NAME: peer_connect_timeout
4444 LOC: Config.Timeout.peer_connect
4447 This parameter specifies how long to wait for a pending TCP
4448 connection to a peer cache. The default is 30 seconds. You
4449 may also set different timeout values for individual neighbors
4450 with the 'connect-timeout' option on a 'cache_peer' line.
4456 LOC: Config.Timeout.read
4459 The read_timeout is applied on server-side connections. After
4460 each successful read(), the timeout will be extended by this
4461 amount. If no data is read again after this amount of time,
4462 the request is aborted and logged with ERR_READ_TIMEOUT. The
4463 default is 15 minutes.
4469 LOC: Config.Timeout.write
4472 This timeout is tracked for all connections that have data
4473 available for writing and are waiting for the socket to become
4474 ready. After each successful write, the timeout is extended by
4475 the configured amount. If Squid has data to write but the
4476 connection is not ready for the configured duration, the
4477 transaction associated with the connection is terminated. The
4478 default is 15 minutes.
4481 NAME: request_timeout
4483 LOC: Config.Timeout.request
4486 How long to wait for an HTTP request after initial
4487 connection establishment.
4490 NAME: persistent_request_timeout
4492 LOC: Config.Timeout.persistent_request
4495 How long to wait for the next HTTP request on a persistent
4496 connection after the previous request completes.
4499 NAME: client_lifetime
4502 LOC: Config.Timeout.lifetime
4505 The maximum amount of time a client (browser) is allowed to
4506 remain connected to the cache process. This protects the Cache
4507 from having a lot of sockets (and hence file descriptors) tied up
4508 in a CLOSE_WAIT state from remote clients that go away without
4509 properly shutting down (either because of a network failure or
4510 because of a poor client implementation). The default is one
4513 NOTE: The default value is intended to be much larger than any
4514 client would ever need to be connected to your cache. You
4515 should probably change client_lifetime only as a last resort.
4516 If you seem to have many client connections tying up
4517 filedescriptors, we recommend first tuning the read_timeout,
4518 request_timeout, persistent_request_timeout and quick_abort values.
4521 NAME: half_closed_clients
4523 LOC: Config.onoff.half_closed_clients
4526 Some clients may shutdown the sending side of their TCP
4527 connections, while leaving their receiving sides open. Sometimes,
4528 Squid can not tell the difference between a half-closed and a
4529 fully-closed TCP connection.
4531 By default, Squid will immediately close client connections when
4532 read(2) returns "no more data to read."
4534 Change this option to 'on' and Squid will keep open connections
4535 until a read(2) or write(2) on the socket returns an error.
4536 This may show some benefits for reverse proxies. But if not
4537 it is recommended to leave OFF.
4542 LOC: Config.Timeout.pconn
4545 Timeout for idle persistent connections to servers and other
4552 LOC: Ident::TheConfig.timeout
4555 Maximum time to wait for IDENT lookups to complete.
4557 If this is too high, and you enabled IDENT lookups from untrusted
4558 users, you might be susceptible to denial-of-service by having
4559 many ident requests going at once.
4562 NAME: shutdown_lifetime
4565 LOC: Config.shutdownLifetime
4568 When SIGTERM or SIGHUP is received, the cache is put into
4569 "shutdown pending" mode until all active sockets are closed.
4570 This value is the lifetime to set for all open descriptors
4571 during shutdown mode. Any active clients after this many
4572 seconds will receive a 'timeout' message.
4576 ADMINISTRATIVE PARAMETERS
4577 -----------------------------------------------------------------------------
4583 LOC: Config.adminEmail
4585 Email-address of local cache manager who will receive
4586 mail if the cache dies. The default is "webmaster."
4592 LOC: Config.EmailFrom
4594 From: email-address for mail sent when the cache dies.
4595 The default is to use 'appname@unique_hostname'.
4596 Default appname value is "squid", can be changed into
4597 src/globals.h before building squid.
4603 LOC: Config.EmailProgram
4605 Email program used to send mail if the cache dies.
4606 The default is "mail". The specified program must comply
4607 with the standard Unix mail syntax:
4608 mail-program recipient < mailfile
4610 Optional command line options can be specified.
4613 NAME: cache_effective_user
4615 DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
4616 LOC: Config.effectiveUser
4618 If you start Squid as root, it will change its effective/real
4619 UID/GID to the user specified below. The default is to change
4620 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
4621 see also; cache_effective_group
4624 NAME: cache_effective_group
4627 LOC: Config.effectiveGroup
4629 Squid sets the GID to the effective user's default group ID
4630 (taken from the password file) and supplementary group list
4631 from the groups membership.
4633 If you want Squid to run with a specific GID regardless of
4634 the group memberships of the effective user then set this
4635 to the group (or GID) you want Squid to run as. When set
4636 all other group privileges of the effective user are ignored
4637 and only this GID is effective. If Squid is not started as
4638 root the user starting Squid MUST be member of the specified
4641 This option is not recommended by the Squid Team.
4642 Our preference is for administrators to configure a secure
4643 user account for squid with UID/GID matching system policies.
4646 NAME: httpd_suppress_version_string
4650 LOC: Config.onoff.httpd_suppress_version_string
4652 Suppress Squid version string info in HTTP headers and HTML error pages.
4655 NAME: visible_hostname
4657 LOC: Config.visibleHostname
4660 If you want to present a special hostname in error messages, etc,
4661 define this. Otherwise, the return value of gethostname()
4662 will be used. If you have multiple caches in a cluster and
4663 get errors about IP-forwarding you must set them to have individual
4664 names with this setting.
4667 NAME: unique_hostname
4669 LOC: Config.uniqueHostname
4672 If you want to have multiple machines with the same
4673 'visible_hostname' you must give each machine a different
4674 'unique_hostname' so forwarding loops can be detected.
4677 NAME: hostname_aliases
4679 LOC: Config.hostnameAliases
4682 A list of other DNS names your cache has.
4690 Minimum umask which should be enforced while the proxy
4691 is running, in addition to the umask set at startup.
4693 For a traditional octal representation of umasks, start
4698 OPTIONS FOR THE CACHE REGISTRATION SERVICE
4699 -----------------------------------------------------------------------------
4701 This section contains parameters for the (optional) cache
4702 announcement service. This service is provided to help
4703 cache administrators locate one another in order to join or
4704 create cache hierarchies.
4706 An 'announcement' message is sent (via UDP) to the registration
4707 service by Squid. By default, the announcement message is NOT
4708 SENT unless you enable it with 'announce_period' below.
4710 The announcement message includes your hostname, plus the
4711 following information from this configuration file:
4717 All current information is processed regularly and made
4718 available on the Web at http://www.ircache.net/Cache/Tracker/.
4721 NAME: announce_period
4723 LOC: Config.Announce.period
4726 This is how frequently to send cache announcements. The
4727 default is `0' which disables sending the announcement
4730 To enable announcing your cache, just set an announce period.
4733 announce_period 1 day
4738 DEFAULT: tracker.ircache.net
4739 LOC: Config.Announce.host
4745 LOC: Config.Announce.file
4751 LOC: Config.Announce.port
4753 announce_host and announce_port set the hostname and port
4754 number where the registration message will be sent.
4756 Hostname will default to 'tracker.ircache.net' and port will
4757 default default to 3131. If the 'filename' argument is given,
4758 the contents of that file will be included in the announce
4763 HTTPD-ACCELERATOR OPTIONS
4764 -----------------------------------------------------------------------------
4767 NAME: httpd_accel_surrogate_id
4770 LOC: Config.Accel.surrogate_id
4772 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
4773 need an identification token to allow control targeting. Because
4774 a farm of surrogates may all perform the same tasks, they may share
4775 an identification token.
4777 The default ID is the visible_hostname
4780 NAME: http_accel_surrogate_remote
4784 LOC: Config.onoff.surrogate_is_remote
4786 Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
4787 Set this to on to have squid behave as a remote surrogate.
4791 IFDEF: USE_SQUID_ESI
4792 COMMENT: libxml2|expat|custom
4794 LOC: ESIParser::Type
4797 ESI markup is not strictly XML compatible. The custom ESI parser
4798 will give higher performance, but cannot handle non ASCII character
4803 DELAY POOL PARAMETERS
4804 -----------------------------------------------------------------------------
4808 TYPE: delay_pool_count
4810 IFDEF: USE_DELAY_POOLS
4813 This represents the number of delay pools to be used. For example,
4814 if you have one class 2 delay pool and one class 3 delays pool, you
4815 have a total of 2 delay pools.
4819 TYPE: delay_pool_class
4821 IFDEF: USE_DELAY_POOLS
4824 This defines the class of each delay pool. There must be exactly one
4825 delay_class line for each delay pool. For example, to define two
4826 delay pools, one of class 2 and one of class 3, the settings above
4830 delay_pools 4 # 4 delay pools
4831 delay_class 1 2 # pool 1 is a class 2 pool
4832 delay_class 2 3 # pool 2 is a class 3 pool
4833 delay_class 3 4 # pool 3 is a class 4 pool
4834 delay_class 4 5 # pool 4 is a class 5 pool
4836 The delay pool classes are:
4838 class 1 Everything is limited by a single aggregate
4841 class 2 Everything is limited by a single aggregate
4842 bucket as well as an "individual" bucket chosen
4843 from bits 25 through 32 of the IPv4 address.
4845 class 3 Everything is limited by a single aggregate
4846 bucket as well as a "network" bucket chosen
4847 from bits 17 through 24 of the IP address and a
4848 "individual" bucket chosen from bits 17 through
4849 32 of the IPv4 address.
4851 class 4 Everything in a class 3 delay pool, with an
4852 additional limit on a per user basis. This
4853 only takes effect if the username is established
4854 in advance - by forcing authentication in your
4857 class 5 Requests are grouped according their tag (see
4858 external_acl's tag= reply).
4860 NOTE: If an IP address is a.b.c.d
4861 -> bits 25 through 32 are "d"
4862 -> bits 17 through 24 are "c"
4863 -> bits 17 through 32 are "c * 256 + d"
4865 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
4866 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
4870 TYPE: delay_pool_access
4872 IFDEF: USE_DELAY_POOLS
4875 This is used to determine which delay pool a request falls into.
4877 delay_access is sorted per pool and the matching starts with pool 1,
4878 then pool 2, ..., and finally pool N. The first delay pool where the
4879 request is allowed is selected for the request. If it does not allow
4880 the request to any pool then the request is not delayed (default).
4882 For example, if you want some_big_clients in delay
4883 pool 1 and lotsa_little_clients in delay pool 2:
4886 delay_access 1 allow some_big_clients
4887 delay_access 1 deny all
4888 delay_access 2 allow lotsa_little_clients
4889 delay_access 2 deny all
4890 delay_access 3 allow authenticated_clients
4893 NAME: delay_parameters
4894 TYPE: delay_pool_rates
4896 IFDEF: USE_DELAY_POOLS
4899 This defines the parameters for a delay pool. Each delay pool has
4900 a number of "buckets" associated with it, as explained in the
4901 description of delay_class. For a class 1 delay pool, the syntax is:
4903 delay_parameters pool aggregate
4905 For a class 2 delay pool:
4907 delay_parameters pool aggregate individual
4909 For a class 3 delay pool:
4911 delay_parameters pool aggregate network individual
4913 For a class 4 delay pool:
4915 delay_parameters pool aggregate network individual user
4917 For a class 5 delay pool:
4919 delay_parameters pool tag
4921 The variables here are:
4923 pool a pool number - ie, a number between 1 and the
4924 number specified in delay_pools as used in
4927 aggregate the "delay parameters" for the aggregate bucket
4930 individual the "delay parameters" for the individual
4931 buckets (class 2, 3).
4933 network the "delay parameters" for the network buckets
4936 user the delay parameters for the user buckets
4939 tag the delay parameters for the tag buckets
4942 A pair of delay parameters is written restore/maximum, where restore is
4943 the number of bytes (not bits - modem and network speeds are usually
4944 quoted in bits) per second placed into the bucket, and maximum is the
4945 maximum number of bytes which can be in the bucket at any time.
4947 For example, if delay pool number 1 is a class 2 delay pool as in the
4948 above example, and is being used to strictly limit each host to 64kbps
4949 (plus overheads), with no overall limit, the line is:
4951 delay_parameters 1 -1/-1 8000/8000
4953 Note that the figure -1 is used to represent "unlimited".
4955 And, if delay pool number 2 is a class 3 delay pool as in the above
4956 example, and you want to limit it to a total of 256kbps (strict limit)
4957 with each 8-bit network permitted 64kbps (strict limit) and each
4958 individual host permitted 4800bps with a bucket maximum size of 64kb
4959 to permit a decent web page to be downloaded at a decent speed
4960 (if the network is not being limited due to overuse) but slow down
4961 large downloads more significantly:
4963 delay_parameters 2 32000/32000 8000/8000 600/8000
4965 There must be one delay_parameters line for each delay pool.
4967 Finally, for a class 4 delay pool as in the example - each user will
4968 be limited to 128Kb no matter how many workstations they are logged into.:
4970 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
4973 NAME: delay_initial_bucket_level
4974 COMMENT: (percent, 0-100)
4977 IFDEF: USE_DELAY_POOLS
4978 LOC: Config.Delay.initial
4980 The initial bucket percentage is used to determine how much is put
4981 in each bucket when squid starts, is reconfigured, or first notices
4982 a host accessing it (in class 2 and class 3, individual hosts and
4983 networks only have buckets associated with them once they have been
4988 CLIENT DELAY POOL PARAMETERS
4989 -----------------------------------------------------------------------------
4992 NAME: client_delay_pools
4993 TYPE: client_delay_pool_count
4995 IFDEF: USE_DELAY_POOLS
4996 LOC: Config.ClientDelay
4998 This option specifies the number of client delay pools used. It must
4999 preceed other client_delay_* options.
5002 client_delay_pools 2
5005 NAME: client_delay_initial_bucket_level
5006 COMMENT: (percent, 0-no_limit)
5009 IFDEF: USE_DELAY_POOLS
5010 LOC: Config.ClientDelay.initial
5012 This option determines the initial bucket size as a percentage of
5013 max_bucket_size from client_delay_parameters. Buckets are created
5014 at the time of the "first" connection from the matching IP. Idle
5015 buckets are periodically deleted up.
5017 You can specify more than 100 percent but note that such "oversized"
5018 buckets are not refilled until their size goes down to max_bucket_size
5019 from client_delay_parameters.
5022 client_delay_initial_bucket_level 50
5025 NAME: client_delay_parameters
5026 TYPE: client_delay_pool_rates
5028 IFDEF: USE_DELAY_POOLS
5029 LOC: Config.ClientDelay
5032 This option configures client-side bandwidth limits using the
5035 client_delay_parameters pool speed_limit max_bucket_size
5037 pool is an integer ID used for client_delay_access matching.
5039 speed_limit is bytes added to the bucket per second.
5041 max_bucket_size is the maximum size of a bucket, enforced after any
5042 speed_limit additions.
5044 Please see the delay_parameters option for more information and
5048 client_delay_parameters 1 1024 2048
5049 client_delay_parameters 2 51200 16384
5052 NAME: client_delay_access
5053 TYPE: client_delay_pool_access
5055 IFDEF: USE_DELAY_POOLS
5056 LOC: Config.ClientDelay
5059 This option determines the client-side delay pool for the
5062 client_delay_access pool_ID allow|deny acl_name
5064 All client_delay_access options are checked in their pool ID
5065 order, starting with pool 1. The first checked pool with allowed
5066 request is selected for the request. If no ACL matches or there
5067 are no client_delay_access options, the request bandwidth is not
5070 The ACL-selected pool is then used to find the
5071 client_delay_parameters for the request. Client-side pools are
5072 not used to aggregate clients. Clients are always aggregated
5073 based on their source IP addresses (one bucket per source IP).
5075 Please see delay_access for more examples.
5078 client_delay_access 1 allow low_rate_network
5079 client_delay_access 2 allow vips_network
5083 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
5084 -----------------------------------------------------------------------------
5089 LOC: Config.Wccp.router
5093 Use this option to define your WCCP ``home'' router for
5096 wccp_router supports a single WCCP(v1) router
5098 wccp2_router supports multiple WCCPv2 routers
5100 only one of the two may be used at the same time and defines
5101 which version of WCCP to use.
5105 TYPE: IpAddress_list
5106 LOC: Config.Wccp2.router
5110 Use this option to define your WCCP ``home'' router for
5113 wccp_router supports a single WCCP(v1) router
5115 wccp2_router supports multiple WCCPv2 routers
5117 only one of the two may be used at the same time and defines
5118 which version of WCCP to use.
5123 LOC: Config.Wccp.version
5127 This directive is only relevant if you need to set up WCCP(v1)
5128 to some very old and end-of-life Cisco routers. In all other
5129 setups it must be left unset or at the default setting.
5130 It defines an internal version in the WCCP(v1) protocol,
5131 with version 4 being the officially documented protocol.
5133 According to some users, Cisco IOS 11.2 and earlier only
5134 support WCCP version 3. If you're using that or an earlier
5135 version of IOS, you may need to change this value to 3, otherwise
5136 do not specify this parameter.
5139 NAME: wccp2_rebuild_wait
5141 LOC: Config.Wccp2.rebuildwait
5145 If this is enabled Squid will wait for the cache dir rebuild to finish
5146 before sending the first wccp2 HereIAm packet
5149 NAME: wccp2_forwarding_method
5151 LOC: Config.Wccp2.forwarding_method
5155 WCCP2 allows the setting of forwarding methods between the
5156 router/switch and the cache. Valid values are as follows:
5158 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5159 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
5161 Currently (as of IOS 12.4) cisco routers only support GRE.
5162 Cisco switches only support the L2 redirect assignment method.
5165 NAME: wccp2_return_method
5167 LOC: Config.Wccp2.return_method
5171 WCCP2 allows the setting of return methods between the
5172 router/switch and the cache for packets that the cache
5173 decides not to handle. Valid values are as follows:
5175 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
5176 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
5178 Currently (as of IOS 12.4) cisco routers only support GRE.
5179 Cisco switches only support the L2 redirect assignment.
5181 If the "ip wccp redirect exclude in" command has been
5182 enabled on the cache interface, then it is still safe for
5183 the proxy server to use a l2 redirect method even if this
5184 option is set to GRE.
5187 NAME: wccp2_assignment_method
5189 LOC: Config.Wccp2.assignment_method
5193 WCCP2 allows the setting of methods to assign the WCCP hash
5194 Valid values are as follows:
5196 hash - Hash assignment
5197 mask - Mask assignment
5199 As a general rule, cisco routers support the hash assignment method
5200 and cisco switches support the mask assignment method.
5205 LOC: Config.Wccp2.info
5206 DEFAULT_IF_NONE: standard 0
5209 WCCP2 allows for multiple traffic services. There are two
5210 types: "standard" and "dynamic". The standard type defines
5211 one service id - http (id 0). The dynamic service ids can be from
5212 51 to 255 inclusive. In order to use a dynamic service id
5213 one must define the type of traffic to be redirected; this is done
5214 using the wccp2_service_info option.
5216 The "standard" type does not require a wccp2_service_info option,
5217 just specifying the service id will suffice.
5219 MD5 service authentication can be enabled by adding
5220 "password=<password>" to the end of this service declaration.
5224 wccp2_service standard 0 # for the 'web-cache' standard service
5225 wccp2_service dynamic 80 # a dynamic service type which will be
5226 # fleshed out with subsequent options.
5227 wccp2_service standard 0 password=foo
5230 NAME: wccp2_service_info
5231 TYPE: wccp2_service_info
5232 LOC: Config.Wccp2.info
5236 Dynamic WCCPv2 services require further information to define the
5237 traffic you wish to have diverted.
5241 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
5242 priority=<priority> ports=<port>,<port>..
5244 The relevant WCCPv2 flags:
5245 + src_ip_hash, dst_ip_hash
5246 + source_port_hash, dst_port_hash
5247 + src_ip_alt_hash, dst_ip_alt_hash
5248 + src_port_alt_hash, dst_port_alt_hash
5251 The port list can be one to eight entries.
5255 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
5256 priority=240 ports=80
5258 Note: the service id must have been defined by a previous
5259 'wccp2_service dynamic <id>' entry.
5264 LOC: Config.Wccp2.weight
5268 Each cache server gets assigned a set of the destination
5269 hash proportional to their weight.
5274 LOC: Config.Wccp.address
5281 LOC: Config.Wccp2.address
5285 Use this option if you require WCCP to use a specific
5288 The default behavior is to not bind to any specific address.
5292 PERSISTENT CONNECTION HANDLING
5293 -----------------------------------------------------------------------------
5295 Also see "pconn_timeout" in the TIMEOUTS section
5298 NAME: client_persistent_connections
5300 LOC: Config.onoff.client_pconns
5304 NAME: server_persistent_connections
5306 LOC: Config.onoff.server_pconns
5309 Persistent connection support for clients and servers. By
5310 default, Squid uses persistent connections (when allowed)
5311 with its clients and servers. You can use these options to
5312 disable persistent connections with clients and/or servers.
5315 NAME: persistent_connection_after_error
5317 LOC: Config.onoff.error_pconns
5320 With this directive the use of persistent connections after
5321 HTTP errors can be disabled. Useful if you have clients
5322 who fail to handle errors on persistent connections proper.
5325 NAME: detect_broken_pconn
5327 LOC: Config.onoff.detect_broken_server_pconns
5330 Some servers have been found to incorrectly signal the use
5331 of HTTP/1.0 persistent connections even on replies not
5332 compatible, causing significant delays. This server problem
5333 has mostly been seen on redirects.
5335 By enabling this directive Squid attempts to detect such
5336 broken replies and automatically assume the reply is finished
5337 after 10 seconds timeout.
5341 CACHE DIGEST OPTIONS
5342 -----------------------------------------------------------------------------
5345 NAME: digest_generation
5346 IFDEF: USE_CACHE_DIGESTS
5348 LOC: Config.onoff.digest_generation
5351 This controls whether the server will generate a Cache Digest
5352 of its contents. By default, Cache Digest generation is
5353 enabled if Squid is compiled with --enable-cache-digests defined.
5356 NAME: digest_bits_per_entry
5357 IFDEF: USE_CACHE_DIGESTS
5359 LOC: Config.digest.bits_per_entry
5362 This is the number of bits of the server's Cache Digest which
5363 will be associated with the Digest entry for a given HTTP
5364 Method and URL (public key) combination. The default is 5.
5367 NAME: digest_rebuild_period
5368 IFDEF: USE_CACHE_DIGESTS
5371 LOC: Config.digest.rebuild_period
5374 This is the wait time between Cache Digest rebuilds.
5377 NAME: digest_rewrite_period
5379 IFDEF: USE_CACHE_DIGESTS
5381 LOC: Config.digest.rewrite_period
5384 This is the wait time between Cache Digest writes to
5388 NAME: digest_swapout_chunk_size
5391 IFDEF: USE_CACHE_DIGESTS
5392 LOC: Config.digest.swapout_chunk_size
5395 This is the number of bytes of the Cache Digest to write to
5396 disk at a time. It defaults to 4096 bytes (4KB), the Squid
5400 NAME: digest_rebuild_chunk_percentage
5401 COMMENT: (percent, 0-100)
5402 IFDEF: USE_CACHE_DIGESTS
5404 LOC: Config.digest.rebuild_chunk_percentage
5407 This is the percentage of the Cache Digest to be scanned at a
5408 time. By default it is set to 10% of the Cache Digest.
5413 -----------------------------------------------------------------------------
5418 LOC: Config.Port.snmp
5422 The port number where Squid listens for SNMP requests. To enable
5423 SNMP support set this to a suitable port number. Port number
5424 3401 is often used for the Squid SNMP agent. By default it's
5425 set to "0" (disabled)
5433 LOC: Config.accessList.snmp
5434 DEFAULT_IF_NONE: deny all
5437 Allowing or denying access to the SNMP port.
5439 All access to the agent is denied by default.
5442 snmp_access allow|deny [!]aclname ...
5444 This clause only supports fast acl types.
5445 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5447 snmp_access allow snmppublic localhost
5448 snmp_access deny all
5451 NAME: snmp_incoming_address
5453 LOC: Config.Addrs.snmp_incoming
5458 NAME: snmp_outgoing_address
5460 LOC: Config.Addrs.snmp_outgoing
5464 Just like 'udp_incoming_address', but for the SNMP port.
5466 snmp_incoming_address is used for the SNMP socket receiving
5467 messages from SNMP agents.
5468 snmp_outgoing_address is used for SNMP packets returned to SNMP
5471 The default snmp_incoming_address is to listen on all
5472 available network interfaces.
5474 If snmp_outgoing_address is not set it will use the same socket
5475 as snmp_incoming_address. Only change this if you want to have
5476 SNMP replies sent using another address than where this Squid
5477 listens for SNMP queries.
5479 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
5480 the same value since they both use port 3401.
5485 -----------------------------------------------------------------------------
5488 NAME: icp_port udp_port
5491 LOC: Config.Port.icp
5493 The port number where Squid sends and receives ICP queries to
5494 and from neighbor caches. The standard UDP port for ICP is 3130.
5495 Default is disabled (0).
5498 icp_port @DEFAULT_ICP_PORT@
5505 LOC: Config.Port.htcp
5507 The port number where Squid sends and receives HTCP queries to
5508 and from neighbor caches. To turn it on you want to set it to
5509 4827. By default it is set to "0" (disabled).
5515 NAME: log_icp_queries
5519 LOC: Config.onoff.log_udp
5521 If set, ICP queries are logged to access.log. You may wish
5522 do disable this if your ICP load is VERY high to speed things
5523 up or to simplify log analysis.
5526 NAME: udp_incoming_address
5528 LOC:Config.Addrs.udp_incoming
5531 udp_incoming_address is used for UDP packets received from other
5534 The default behavior is to not bind to any specific address.
5536 Only change this if you want to have all UDP queries received on
5537 a specific interface/address.
5539 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
5540 modules. Altering it will affect all of them in the same manner.
5542 see also; udp_outgoing_address
5544 NOTE, udp_incoming_address and udp_outgoing_address can not
5545 have the same value since they both use the same port.
5548 NAME: udp_outgoing_address
5550 LOC: Config.Addrs.udp_outgoing
5553 udp_outgoing_address is used for UDP packets sent out to other
5556 The default behavior is to not bind to any specific address.
5558 Instead it will use the same socket as udp_incoming_address.
5559 Only change this if you want to have UDP queries sent using another
5560 address than where this Squid listens for UDP queries from other
5563 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
5564 modules. Altering it will affect all of them in the same manner.
5566 see also; udp_incoming_address
5568 NOTE, udp_incoming_address and udp_outgoing_address can not
5569 have the same value since they both use the same port.
5576 LOC: Config.onoff.icp_hit_stale
5578 If you want to return ICP_HIT for stale cache objects, set this
5579 option to 'on'. If you have sibling relationships with caches
5580 in other administrative domains, this should be 'off'. If you only
5581 have sibling relationships with caches under your control,
5582 it is probably okay to set this to 'on'.
5583 If set to 'on', your siblings should use the option "allow-miss"
5584 on their cache_peer lines for connecting to you.
5587 NAME: minimum_direct_hops
5590 LOC: Config.minDirectHops
5592 If using the ICMP pinging stuff, do direct fetches for sites
5593 which are no more than this many hops away.
5596 NAME: minimum_direct_rtt
5599 LOC: Config.minDirectRtt
5601 If using the ICMP pinging stuff, do direct fetches for sites
5602 which are no more than this many rtt milliseconds away.
5608 LOC: Config.Netdb.low
5614 LOC: Config.Netdb.high
5616 The low and high water marks for the ICMP measurement
5617 database. These are counts, not percents. The defaults are
5618 900 and 1000. When the high water mark is reached, database
5619 entries will be deleted until the low mark is reached.
5622 NAME: netdb_ping_period
5624 LOC: Config.Netdb.period
5627 The minimum period for measuring a site. There will be at
5628 least this much delay between successive pings to the same
5629 network. The default is five minutes.
5636 LOC: Config.onoff.query_icmp
5638 If you want to ask your peers to include ICMP data in their ICP
5639 replies, enable this option.
5641 If your peer has configured Squid (during compilation) with
5642 '--enable-icmp' that peer will send ICMP pings to origin server
5643 sites of the URLs it receives. If you enable this option the
5644 ICP replies from that peer will include the ICMP data (if available).
5645 Then, when choosing a parent cache, Squid will choose the parent with
5646 the minimal RTT to the origin server. When this happens, the
5647 hierarchy field of the access.log will be
5648 "CLOSEST_PARENT_MISS". This option is off by default.
5651 NAME: test_reachability
5655 LOC: Config.onoff.test_reachability
5657 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
5658 instead of ICP_MISS if the target host is NOT in the ICMP
5659 database, or has a zero RTT.
5662 NAME: icp_query_timeout
5666 LOC: Config.Timeout.icp_query
5668 Normally Squid will automatically determine an optimal ICP
5669 query timeout value based on the round-trip-time of recent ICP
5670 queries. If you want to override the value determined by
5671 Squid, set this 'icp_query_timeout' to a non-zero value. This
5672 value is specified in MILLISECONDS, so, to use a 2-second
5673 timeout (the old default), you would write:
5675 icp_query_timeout 2000
5678 NAME: maximum_icp_query_timeout
5682 LOC: Config.Timeout.icp_query_max
5684 Normally the ICP query timeout is determined dynamically. But
5685 sometimes it can lead to very large values (say 5 seconds).
5686 Use this option to put an upper limit on the dynamic timeout
5687 value. Do NOT use this option to always use a fixed (instead
5688 of a dynamic) timeout value. To set a fixed timeout see the
5689 'icp_query_timeout' directive.
5692 NAME: minimum_icp_query_timeout
5696 LOC: Config.Timeout.icp_query_min
5698 Normally the ICP query timeout is determined dynamically. But
5699 sometimes it can lead to very small timeouts, even lower than
5700 the normal latency variance on your link due to traffic.
5701 Use this option to put an lower limit on the dynamic timeout
5702 value. Do NOT use this option to always use a fixed (instead
5703 of a dynamic) timeout value. To set a fixed timeout see the
5704 'icp_query_timeout' directive.
5707 NAME: background_ping_rate
5711 LOC: Config.backgroundPingRate
5713 Controls how often the ICP pings are sent to siblings that
5714 have background-ping set.
5718 MULTICAST ICP OPTIONS
5719 -----------------------------------------------------------------------------
5724 LOC: Config.mcast_group_list
5727 This tag specifies a list of multicast groups which your server
5728 should join to receive multicasted ICP queries.
5730 NOTE! Be very careful what you put here! Be sure you
5731 understand the difference between an ICP _query_ and an ICP
5732 _reply_. This option is to be set only if you want to RECEIVE
5733 multicast queries. Do NOT set this option to SEND multicast
5734 ICP (use cache_peer for that). ICP replies are always sent via
5735 unicast, so this option does not affect whether or not you will
5736 receive replies from multicast group members.
5738 You must be very careful to NOT use a multicast address which
5739 is already in use by another group of caches.
5741 If you are unsure about multicast, please read the Multicast
5742 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
5744 Usage: mcast_groups 239.128.16.128 224.0.1.20
5746 By default, Squid doesn't listen on any multicast groups.
5749 NAME: mcast_miss_addr
5750 IFDEF: MULTICAST_MISS_STREAM
5752 LOC: Config.mcast_miss.addr
5755 If you enable this option, every "cache miss" URL will
5756 be sent out on the specified multicast address.
5758 Do not enable this option unless you are are absolutely
5759 certain you understand what you are doing.
5762 NAME: mcast_miss_ttl
5763 IFDEF: MULTICAST_MISS_STREAM
5765 LOC: Config.mcast_miss.ttl
5768 This is the time-to-live value for packets multicasted
5769 when multicasting off cache miss URLs is enabled. By
5770 default this is set to 'site scope', i.e. 16.
5773 NAME: mcast_miss_port
5774 IFDEF: MULTICAST_MISS_STREAM
5776 LOC: Config.mcast_miss.port
5779 This is the port number to be used in conjunction with
5783 NAME: mcast_miss_encode_key
5784 IFDEF: MULTICAST_MISS_STREAM
5786 LOC: Config.mcast_miss.encode_key
5787 DEFAULT: XXXXXXXXXXXXXXXX
5789 The URLs that are sent in the multicast miss stream are
5790 encrypted. This is the encryption key.
5793 NAME: mcast_icp_query_timeout
5797 LOC: Config.Timeout.mcast_icp_query
5799 For multicast peers, Squid regularly sends out ICP "probes" to
5800 count how many other peers are listening on the given multicast
5801 address. This value specifies how long Squid should wait to
5802 count all the replies. The default is 2000 msec, or 2
5807 INTERNAL ICON OPTIONS
5808 -----------------------------------------------------------------------------
5811 NAME: icon_directory
5813 LOC: Config.icons.directory
5814 DEFAULT: @DEFAULT_ICON_DIR@
5816 Where the icons are stored. These are normally kept in
5820 NAME: global_internal_static
5822 LOC: Config.onoff.global_internal_static
5825 This directive controls is Squid should intercept all requests for
5826 /squid-internal-static/ no matter which host the URL is requesting
5827 (default on setting), or if nothing special should be done for
5828 such URLs (off setting). The purpose of this directive is to make
5829 icons etc work better in complex cache hierarchies where it may
5830 not always be possible for all corners in the cache mesh to reach
5831 the server generating a directory listing.
5834 NAME: short_icon_urls
5836 LOC: Config.icons.use_short_names
5839 If this is enabled Squid will use short URLs for icons.
5840 If disabled it will revert to the old behavior of including
5841 it's own name and port in the URL.
5843 If you run a complex cache hierarchy with a mix of Squid and
5844 other proxies you may need to disable this directive.
5849 -----------------------------------------------------------------------------
5852 NAME: error_directory
5854 LOC: Config.errorDirectory
5857 If you wish to create your own versions of the default
5858 error files to customize them to suit your company copy
5859 the error/template files to another directory and point
5862 WARNING: This option will disable multi-language support
5863 on error pages if used.
5865 The squid developers are interested in making squid available in
5866 a wide variety of languages. If you are making translations for a
5867 language that Squid does not currently provide please consider
5868 contributing your translation back to the project.
5869 http://wiki.squid-cache.org/Translations
5871 The squid developers working on translations are happy to supply drop-in
5872 translated error files in exchange for any new language contributions.
5875 NAME: error_default_language
5876 IFDEF: USE_ERR_LOCALES
5878 LOC: Config.errorDefaultLanguage
5881 Set the default language which squid will send error pages in
5882 if no existing translation matches the clients language
5885 If unset (default) generic English will be used.
5887 The squid developers are interested in making squid available in
5888 a wide variety of languages. If you are interested in making
5889 translations for any language see the squid wiki for details.
5890 http://wiki.squid-cache.org/Translations
5893 NAME: error_log_languages
5894 IFDEF: USE_ERR_LOCALES
5896 LOC: Config.errorLogMissingLanguages
5899 Log to cache.log what languages users are attempting to
5900 auto-negotiate for translations.
5902 Successful negotiations are not logged. Only failures
5903 have meaning to indicate that Squid may need an upgrade
5904 of its error page translations.
5907 NAME: err_page_stylesheet
5909 LOC: Config.errorStylesheet
5910 DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
5912 CSS Stylesheet to pattern the display of Squid default error pages.
5914 For information on CSS see http://www.w3.org/Style/CSS/
5919 LOC: Config.errHtmlText
5922 HTML text to include in error messages. Make this a "mailto"
5923 URL to your admin address, or maybe just a link to your
5924 organizations Web page.
5926 To include this in your error messages, you must rewrite
5927 the error template files (found in the "errors" directory).
5928 Wherever you want the 'err_html_text' line to appear,
5929 insert a %L tag in the error template file.
5932 NAME: email_err_data
5935 LOC: Config.onoff.emailErrData
5938 If enabled, information about the occurred error will be
5939 included in the mailto links of the ERR pages (if %W is set)
5940 so that the email body contains the data.
5941 Syntax is <A HREF="mailto:%w%W">%w</A>
5946 LOC: Config.denyInfoList
5949 Usage: deny_info err_page_name acl
5950 or deny_info http://... acl
5951 or deny_info TCP_RESET acl
5953 This can be used to return a ERR_ page for requests which
5954 do not pass the 'http_access' rules. Squid remembers the last
5955 acl it evaluated in http_access, and if a 'deny_info' line exists
5956 for that ACL Squid returns a corresponding error page.
5958 The acl is typically the last acl on the http_access deny line which
5959 denied access. The exceptions to this rule are:
5960 - When Squid needs to request authentication credentials. It's then
5961 the first authentication related acl encountered
5962 - When none of the http_access lines matches. It's then the last
5963 acl processed on the last http_access line.
5965 NP: If providing your own custom error pages with error_directory
5966 you may also specify them by your custom file name:
5967 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
5969 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
5970 may be specified by prefixing the file name with the code and a colon.
5971 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
5973 Alternatively you can tell Squid to reset the TCP connection
5974 by specifying TCP_RESET.
5976 Or you can specify an error URL or URL pattern. The browsers will
5977 get redirected to the specified URL after formatting tags have
5978 been replaced. Redirect will be done with 302 or 307 according to
5979 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
5980 the URL. e.g. 303:http://example.com/
5983 %a - username (if available. Password NOT included)
5986 %E - Error description
5988 %H - Request domain name
5989 %i - Client IP Address
5991 %o - Message result from external ACL helper
5992 %p - Request Port number
5993 %P - Request Protocol name
5994 %R - Request URL path
5995 %T - Timestamp in RFC 1123 format
5996 %U - Full canonical URL from client
5997 (HTTPS URLs terminate with *)
5998 %u - Full canonical URL from client
5999 %w - Admin email from squid.conf
6000 %% - Literal percent (%) code
6005 OPTIONS INFLUENCING REQUEST FORWARDING
6006 -----------------------------------------------------------------------------
6009 NAME: nonhierarchical_direct
6011 LOC: Config.onoff.nonhierarchical_direct
6014 By default, Squid will send any non-hierarchical requests
6015 (matching hierarchy_stoplist or not cacheable request type) direct
6018 If you set this to off, Squid will prefer to send these
6019 requests to parents.
6021 Note that in most configurations, by turning this off you will only
6022 add latency to these request without any improvement in global hit
6025 If you are inside an firewall see never_direct instead of
6031 LOC: Config.onoff.prefer_direct
6034 Normally Squid tries to use parents for most requests. If you for some
6035 reason like it to first try going direct and only use a parent if
6036 going direct fails set this to on.
6038 By combining nonhierarchical_direct off and prefer_direct on you
6039 can set up Squid to use a parent as a backup path if going direct
6042 Note: If you want Squid to use parents for all requests see
6043 the never_direct directive. prefer_direct only modifies how Squid
6044 acts on cacheable requests.
6049 LOC: Config.accessList.AlwaysDirect
6052 Usage: always_direct allow|deny [!]aclname ...
6054 Here you can use ACL elements to specify requests which should
6055 ALWAYS be forwarded by Squid to the origin servers without using
6056 any peers. For example, to always directly forward requests for
6057 local servers ignoring any parents or siblings you may have use
6060 acl local-servers dstdomain my.domain.net
6061 always_direct allow local-servers
6063 To always forward FTP requests directly, use
6066 always_direct allow FTP
6068 NOTE: There is a similar, but opposite option named
6069 'never_direct'. You need to be aware that "always_direct deny
6070 foo" is NOT the same thing as "never_direct allow foo". You
6071 may need to use a deny rule to exclude a more-specific case of
6072 some other rule. Example:
6074 acl local-external dstdomain external.foo.net
6075 acl local-servers dstdomain .foo.net
6076 always_direct deny local-external
6077 always_direct allow local-servers
6079 NOTE: If your goal is to make the client forward the request
6080 directly to the origin server bypassing Squid then this needs
6081 to be done in the client configuration. Squid configuration
6082 can only tell Squid how Squid should fetch the object.
6084 NOTE: This directive is not related to caching. The replies
6085 is cached as usual even if you use always_direct. To not cache
6086 the replies see the 'cache' directive.
6088 This clause supports both fast and slow acl types.
6089 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6094 LOC: Config.accessList.NeverDirect
6097 Usage: never_direct allow|deny [!]aclname ...
6099 never_direct is the opposite of always_direct. Please read
6100 the description for always_direct if you have not already.
6102 With 'never_direct' you can use ACL elements to specify
6103 requests which should NEVER be forwarded directly to origin
6104 servers. For example, to force the use of a proxy for all
6105 requests, except those in your local domain use something like:
6107 acl local-servers dstdomain .foo.net
6108 never_direct deny local-servers
6109 never_direct allow all
6111 or if Squid is inside a firewall and there are local intranet
6112 servers inside the firewall use something like:
6114 acl local-intranet dstdomain .foo.net
6115 acl local-external dstdomain external.foo.net
6116 always_direct deny local-external
6117 always_direct allow local-intranet
6118 never_direct allow all
6120 This clause supports both fast and slow acl types.
6121 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6125 ADVANCED NETWORKING OPTIONS
6126 -----------------------------------------------------------------------------
6129 NAME: incoming_icp_average
6132 LOC: Config.comm_incoming.icp_average
6135 NAME: incoming_http_average
6138 LOC: Config.comm_incoming.http_average
6141 NAME: incoming_dns_average
6144 LOC: Config.comm_incoming.dns_average
6147 NAME: min_icp_poll_cnt
6150 LOC: Config.comm_incoming.icp_min_poll
6153 NAME: min_dns_poll_cnt
6156 LOC: Config.comm_incoming.dns_min_poll
6159 NAME: min_http_poll_cnt
6162 LOC: Config.comm_incoming.http_min_poll
6164 Heavy voodoo here. I can't even believe you are reading this.
6165 Are you crazy? Don't even think about adjusting these unless
6166 you understand the algorithms in comm_select.c first!
6172 LOC: Config.accept_filter
6176 The name of an accept(2) filter to install on Squid's
6177 listen socket(s). This feature is perhaps specific to
6178 FreeBSD and requires support in the kernel.
6180 The 'httpready' filter delays delivering new connections
6181 to Squid until a full HTTP request has been received.
6182 See the accf_http(9) man page for details.
6184 The 'dataready' filter delays delivering new connections
6185 to Squid until there is some data to process.
6186 See the accf_dataready(9) man page for details.
6190 The 'data' filter delays delivering of new connections
6191 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
6192 You may optionally specify a number of seconds to wait by
6193 'data=N' where N is the number of seconds. Defaults to 30
6194 if not specified. See the tcp(7) man page for details.
6197 accept_filter httpready
6202 NAME: client_ip_max_connections
6204 LOC: Config.client_ip_max_connections
6207 Set an absolute limit on the number of connections a single
6208 client IP can use. Any more than this and Squid will begin to drop
6209 new connections from the client until it closes some links.
6211 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
6212 connections from the client. For finer control use the ACL access controls.
6214 Requires client_db to be enabled (the default).
6216 WARNING: This may noticably slow down traffic received via external proxies
6217 or NAT devices and cause them to rebound error messages back to their clients.
6220 NAME: tcp_recv_bufsize
6224 LOC: Config.tcpRcvBufsz
6226 Size of receive buffer to set for TCP sockets. Probably just
6227 as easy to change your kernel's default. Set to zero to use
6228 the default buffer size.
6233 -----------------------------------------------------------------------------
6240 LOC: Adaptation::Icap::TheConfig.onoff
6243 If you want to enable the ICAP module support, set this to on.
6246 NAME: icap_connect_timeout
6249 LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
6252 This parameter specifies how long to wait for the TCP connect to
6253 the requested ICAP server to complete before giving up and either
6254 terminating the HTTP transaction or bypassing the failure.
6256 The default for optional services is peer_connect_timeout.
6257 The default for essential services is connect_timeout.
6258 If this option is explicitly set, its value applies to all services.
6261 NAME: icap_io_timeout
6265 LOC: Adaptation::Icap::TheConfig.io_timeout_raw
6268 This parameter specifies how long to wait for an I/O activity on
6269 an established, active ICAP connection before giving up and
6270 either terminating the HTTP transaction or bypassing the
6273 The default is read_timeout.
6276 NAME: icap_service_failure_limit
6277 COMMENT: limit [in memory-depth time-units]
6278 TYPE: icap_service_failure_limit
6280 LOC: Adaptation::Icap::TheConfig
6283 The limit specifies the number of failures that Squid tolerates
6284 when establishing a new TCP connection with an ICAP service. If
6285 the number of failures exceeds the limit, the ICAP service is
6286 not used for new ICAP requests until it is time to refresh its
6289 A negative value disables the limit. Without the limit, an ICAP
6290 service will not be considered down due to connectivity failures
6291 between ICAP OPTIONS requests.
6293 Squid forgets ICAP service failures older than the specified
6294 value of memory-depth. The memory fading algorithm
6295 is approximate because Squid does not remember individual
6296 errors but groups them instead, splitting the option
6297 value into ten time slots of equal length.
6299 When memory-depth is 0 and by default this option has no
6300 effect on service failure expiration.
6302 Squid always forgets failures when updating service settings
6303 using an ICAP OPTIONS transaction, regardless of this option
6307 # suspend service usage after 10 failures in 5 seconds:
6308 icap_service_failure_limit 10 in 5 seconds
6311 NAME: icap_service_revival_delay
6314 LOC: Adaptation::Icap::TheConfig.service_revival_delay
6317 The delay specifies the number of seconds to wait after an ICAP
6318 OPTIONS request failure before requesting the options again. The
6319 failed ICAP service is considered "down" until fresh OPTIONS are
6322 The actual delay cannot be smaller than the hardcoded minimum
6323 delay of 30 seconds.
6326 NAME: icap_preview_enable
6330 LOC: Adaptation::Icap::TheConfig.preview_enable
6333 The ICAP Preview feature allows the ICAP server to handle the
6334 HTTP message by looking only at the beginning of the message body
6335 or even without receiving the body at all. In some environments,
6336 previews greatly speedup ICAP processing.
6338 During an ICAP OPTIONS transaction, the server may tell Squid what
6339 HTTP messages should be previewed and how big the preview should be.
6340 Squid will not use Preview if the server did not request one.
6342 To disable ICAP Preview for all ICAP services, regardless of
6343 individual ICAP server OPTIONS responses, set this option to "off".
6345 icap_preview_enable off
6348 NAME: icap_preview_size
6351 LOC: Adaptation::Icap::TheConfig.preview_size
6354 The default size of preview data to be sent to the ICAP server.
6355 -1 means no preview. This value might be overwritten on a per server
6356 basis by OPTIONS requests.
6359 NAME: icap_206_enable
6363 LOC: Adaptation::Icap::TheConfig.allow206_enable
6366 206 (Partial Content) responses is an ICAP extension that allows the
6367 ICAP agents to optionally combine adapted and original HTTP message
6368 content. The decision to combine is postponed until the end of the
6369 ICAP response. Squid supports Partial Content extension by default.
6371 Activation of the Partial Content extension is negotiated with each
6372 ICAP service during OPTIONS exchange. Most ICAP servers should handle
6373 negotation correctly even if they do not support the extension, but
6374 some might fail. To disable Partial Content support for all ICAP
6375 services and to avoid any negotiation, set this option to "off".
6381 NAME: icap_default_options_ttl
6384 LOC: Adaptation::Icap::TheConfig.default_options_ttl
6387 The default TTL value for ICAP OPTIONS responses that don't have
6388 an Options-TTL header.
6391 NAME: icap_persistent_connections
6395 LOC: Adaptation::Icap::TheConfig.reuse_connections
6398 Whether or not Squid should use persistent connections to
6402 NAME: icap_send_client_ip
6406 LOC: Adaptation::Icap::TheConfig.send_client_ip
6409 This adds the header "X-Client-IP" to ICAP requests.
6412 NAME: icap_send_client_username
6416 LOC: Adaptation::Icap::TheConfig.send_client_username
6419 This sends authenticated HTTP client username (if available) to
6420 the ICAP service. The username value is encoded based on the
6421 icap_client_username_encode option and is sent using the header
6422 specified by the icap_client_username_header option.
6425 NAME: icap_client_username_header
6428 LOC: Adaptation::Icap::TheConfig.client_username_header
6429 DEFAULT: X-Client-Username
6431 ICAP request header name to use for send_client_username.
6434 NAME: icap_client_username_encode
6438 LOC: Adaptation::Icap::TheConfig.client_username_encode
6441 Whether to base64 encode the authenticated client username.
6445 TYPE: icap_service_type
6447 LOC: Adaptation::Icap::TheConfig
6450 Defines a single ICAP service using the following format:
6452 icap_service service_name vectoring_point [options] service_url
6455 an opaque identifier which must be unique in squid.conf
6457 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
6458 This specifies at which point of transaction processing the
6459 ICAP service should be activated. *_postcache vectoring points
6460 are not yet supported.
6462 service_url: icap://servername:port/servicepath
6463 ICAP server and service location.
6465 ICAP does not allow a single service to handle both REQMOD and RESPMOD
6466 transactions. Squid does not enforce that requirement. You can specify
6467 services with the same service_url and different vectoring_points. You
6468 can even specify multiple identical services as long as their
6469 service_names differ.
6472 Service options are separated by white space. ICAP services support
6473 the following name=value options:
6476 If set to 'on' or '1', the ICAP service is treated as
6477 optional. If the service cannot be reached or malfunctions,
6478 Squid will try to ignore any errors and process the message as
6479 if the service was not enabled. No all ICAP errors can be
6480 bypassed. If set to 0, the ICAP service is treated as
6481 essential and all ICAP errors will result in an error page
6482 returned to the HTTP client.
6484 Bypass is off by default: services are treated as essential.
6487 If set to 'on' or '1', the ICAP service is allowed to
6488 dynamically change the current message adaptation plan by
6489 returning a chain of services to be used next. The services
6490 are specified using the X-Next-Services ICAP response header
6491 value, formatted as a comma-separated list of service names.
6492 Each named service should be configured in squid.conf and
6493 should have the same method and vectoring point as the current
6494 ICAP transaction. Services violating these rules are ignored.
6495 An empty X-Next-Services value results in an empty plan which
6496 ends the current adaptation.
6498 Routing is not allowed by default: the ICAP X-Next-Services
6499 response header is ignored.
6502 Only has effect on split-stack systems. The default on those systems
6503 is to use IPv4-only connections. When set to 'on' this option will
6504 make Squid use IPv6-only connections to contact this ICAP service.
6506 Older icap_service format without optional named parameters is
6507 deprecated but supported for backward compatibility.
6510 icap_service svcBlocker reqmod_precache bypass=0 icap://icap1.mydomain.net:1344/reqmod
6511 icap_service svcLogger reqmod_precache routing=on icap://icap2.mydomain.net:1344/respmod
6515 TYPE: icap_class_type
6520 This deprecated option was documented to define an ICAP service
6521 chain, even though it actually defined a set of similar, redundant
6522 services, and the chains were not supported.
6524 To define a set of redundant services, please use the
6525 adaptation_service_set directive. For service chains, use
6526 adaptation_service_chain.
6530 TYPE: icap_access_type
6535 This option is deprecated. Please use adaptation_access, which
6536 has the same ICAP functionality, but comes with better
6537 documentation, and eCAP support.
6542 -----------------------------------------------------------------------------
6549 LOC: Adaptation::Ecap::TheConfig.onoff
6552 Controls whether eCAP support is enabled.
6556 TYPE: ecap_service_type
6558 LOC: Adaptation::Ecap::TheConfig
6561 Defines a single eCAP service
6563 ecap_service servicename vectoring_point bypass service_url
6565 vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
6566 This specifies at which point of transaction processing the
6567 eCAP service should be activated. *_postcache vectoring points
6568 are not yet supported.
6570 If set to 1, the eCAP service is treated as optional. If the
6571 service cannot be reached or malfunctions, Squid will try to
6572 ignore any errors and process the message as if the service
6573 was not enabled. No all eCAP errors can be bypassed.
6574 If set to 0, the eCAP service is treated as essential and all
6575 eCAP errors will result in an error page returned to the
6577 service_url = ecap://vendor/service_name?custom&cgi=style¶meters=optional
6580 ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block
6581 ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg
6584 NAME: loadable_modules
6586 IFDEF: USE_LOADABLE_MODULES
6587 LOC: Config.loadable_module_names
6590 Instructs Squid to load the specified dynamic module(s) or activate
6591 preloaded module(s).
6593 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
6597 MESSAGE ADAPTATION OPTIONS
6598 -----------------------------------------------------------------------------
6601 NAME: adaptation_service_set
6602 TYPE: adaptation_service_set_type
6603 IFDEF: USE_ADAPTATION
6608 Configures an ordered set of similar, redundant services. This is
6609 useful when hot standby or backup adaptation servers are available.
6611 adaptation_service_set set_name service_name1 service_name2 ...
6613 The named services are used in the set declaration order. The first
6614 applicable adaptation service from the set is used first. The next
6615 applicable service is tried if and only if the transaction with the
6616 previous service fails and the message waiting to be adapted is still
6619 When adaptation starts, broken services are ignored as if they were
6620 not a part of the set. A broken service is a down optional service.
6622 The services in a set must be attached to the same vectoring point
6623 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
6625 If all services in a set are optional then adaptation failures are
6626 bypassable. If all services in the set are essential, then a
6627 transaction failure with one service may still be retried using
6628 another service from the set, but when all services fail, the master
6629 transaction fails as well.
6631 A set may contain a mix of optional and essential services, but that
6632 is likely to lead to surprising results because broken services become
6633 ignored (see above), making previously bypassable failures fatal.
6634 Technically, it is the bypassability of the last failed service that
6637 See also: adaptation_access adaptation_service_chain
6640 adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
6641 adaptation service_set svcLogger loggerLocal loggerRemote
6644 NAME: adaptation_service_chain
6645 TYPE: adaptation_service_chain_type
6646 IFDEF: USE_ADAPTATION
6651 Configures a list of complementary services that will be applied
6652 one-by-one, forming an adaptation chain or pipeline. This is useful
6653 when Squid must perform different adaptations on the same message.
6655 adaptation_service_chain chain_name service_name1 svc_name2 ...
6657 The named services are used in the chain declaration order. The first
6658 applicable adaptation service from the chain is used first. The next
6659 applicable service is applied to the successful adaptation results of
6660 the previous service in the chain.
6662 When adaptation starts, broken services are ignored as if they were
6663 not a part of the chain. A broken service is a down optional service.
6665 Request satisfaction terminates the adaptation chain because Squid
6666 does not currently allow declaration of RESPMOD services at the
6667 "reqmod_precache" vectoring point (see icap_service or ecap_service).
6669 The services in a chain must be attached to the same vectoring point
6670 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
6672 A chain may contain a mix of optional and essential services. If an
6673 essential adaptation fails (or the failure cannot be bypassed for
6674 other reasons), the master transaction fails. Otherwise, the failure
6675 is bypassed as if the failed adaptation service was not in the chain.
6677 See also: adaptation_access adaptation_service_set
6680 adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
6683 NAME: adaptation_access
6684 TYPE: adaptation_access_type
6685 IFDEF: USE_ADAPTATION
6689 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
6691 adaptation_access service_name allow|deny [!]aclname...
6692 adaptation_access set_name allow|deny [!]aclname...
6694 At each supported vectoring point, the adaptation_access
6695 statements are processed in the order they appear in this
6696 configuration file. Statements pointing to the following services
6697 are ignored (i.e., skipped without checking their ACL):
6699 - services serving different vectoring points
6700 - "broken-but-bypassable" services
6701 - "up" services configured to ignore such transactions
6702 (e.g., based on the ICAP Transfer-Ignore header).
6704 When a set_name is used, all services in the set are checked
6705 using the same rules, to find the first applicable one. See
6706 adaptation_service_set for details.
6708 If an access list is checked and there is a match, the
6709 processing stops: For an "allow" rule, the corresponding
6710 adaptation service is used for the transaction. For a "deny"
6711 rule, no adaptation service is activated.
6713 It is currently not possible to apply more than one adaptation
6714 service at the same vectoring point to the same HTTP transaction.
6716 See also: icap_service and ecap_service
6719 adaptation_access service_1 allow all
6722 NAME: adaptation_service_iteration_limit
6724 IFDEF: USE_ADAPTATION
6725 LOC: Adaptation::Config::service_iteration_limit
6728 Limits the number of iterations allowed when applying adaptation
6729 services to a message. If your longest adaptation set or chain
6730 may have more than 16 services, increase the limit beyond its
6731 default value of 16. If detecting infinite iteration loops sooner
6732 is critical, make the iteration limit match the actual number
6733 of services in your longest adaptation set or chain.
6735 Infinite adaptation loops are most likely with routing services.
6737 See also: icap_service routing=1
6740 NAME: adaptation_masterx_shared_names
6742 IFDEF: USE_ADAPTATION
6743 LOC: Adaptation::Config::masterx_shared_name
6746 For each master transaction (i.e., the HTTP request and response
6747 sequence, including all related ICAP and eCAP exchanges), Squid
6748 maintains a table of metadata. The table entries are (name, value)
6749 pairs shared among eCAP and ICAP exchanges. The table is destroyed
6750 with the master transaction.
6752 This option specifies the table entry names that Squid must accept
6753 from and forward to the adaptation transactions.
6755 An ICAP REQMOD or RESPMOD transaction may set an entry in the
6756 shared table by returning an ICAP header field with a name
6757 specified in adaptation_masterx_shared_names. Squid will store
6758 and forward that ICAP header field to subsequent ICAP
6759 transactions within the same master transaction scope.
6761 Only one shared entry name is supported at this time.
6764 # share authentication information among ICAP services
6765 adaptation_masterx_shared_names X-Subscriber-ID
6771 LOC: Adaptation::Icap::TheConfig.repeat
6772 DEFAULT_IF_NONE: deny all
6774 This ACL determines which retriable ICAP transactions are
6775 retried. Transactions that received a complete ICAP response
6776 and did not have to consume or produce HTTP bodies to receive
6777 that response are usually retriable.
6779 icap_retry allow|deny [!]aclname ...
6781 Squid automatically retries some ICAP I/O timeouts and errors
6782 due to persistent connection race conditions.
6784 See also: icap_retry_limit
6787 NAME: icap_retry_limit
6790 LOC: Adaptation::Icap::TheConfig.repeat_limit
6793 Limits the number of retries allowed. When set to zero (default),
6794 no retries are allowed.
6796 Communication errors due to persistent connection race
6797 conditions are unavoidable, automatically retried, and do not
6798 count against this limit.
6800 See also: icap_retry
6806 -----------------------------------------------------------------------------
6809 NAME: check_hostnames
6812 LOC: Config.onoff.check_hostnames
6814 For security and stability reasons Squid can check
6815 hostnames for Internet standard RFC compliance. If you want
6816 Squid to perform these checks turn this directive on.
6819 NAME: allow_underscore
6822 LOC: Config.onoff.allow_underscore
6824 Underscore characters is not strictly allowed in Internet hostnames
6825 but nevertheless used by many sites. Set this to off if you want
6826 Squid to be strict about the standard.
6827 This check is performed only when check_hostnames is set to on.
6830 NAME: cache_dns_program
6832 IFDEF: USE_DNSSERVERS
6833 DEFAULT: @DEFAULT_DNSSERVER@
6834 LOC: Config.Program.dnsserver
6836 Specify the location of the executable for dnslookup process.
6840 TYPE: HelperChildConfig
6841 IFDEF: USE_DNSSERVERS
6842 DEFAULT: 32 startup=1 idle=1
6843 LOC: Config.dnsChildren
6845 The maximum number of processes spawn to service DNS name lookups.
6846 If you limit it too few Squid will have to wait for them to process
6847 a backlog of requests, slowing it down. If you allow too many they
6848 will use RAM and other system resources noticably.
6849 The maximum this may be safely set to is 32.
6851 The startup= and idle= options allow some measure of skew in your
6856 Sets a minimum of how many processes are to be spawned when Squid
6857 starts or reconfigures. When set to zero the first request will
6858 cause spawning of the first child process to handle it.
6860 Starting too few will cause an initial slowdown in traffic as Squid
6861 attempts to simultaneously spawn enough processes to cope.
6865 Sets a minimum of how many processes Squid is to try and keep available
6866 at all times. When traffic begins to rise above what the existing
6867 processes can handle this many more will be spawned up to the maximum
6868 configured. A minimum setting of 1 is required.
6871 NAME: dns_retransmit_interval
6874 LOC: Config.Timeout.idns_retransmit
6875 IFDEF: !USE_DNSSERVERS
6877 Initial retransmit interval for DNS queries. The interval is
6878 doubled each time all configured DNS servers have been tried.
6884 LOC: Config.Timeout.idns_query
6885 IFDEF: !USE_DNSSERVERS
6887 DNS Query timeout. If no response is received to a DNS query
6888 within this time all DNS servers for the queried domain
6889 are assumed to be unavailable.
6892 NAME: dns_packet_max
6895 LOC: Config.dns.packet_max
6896 IFDEF: !USE_DNSSERVERS
6898 Maximum number of bytes packet size to advertise via EDNS.
6899 Set to "none" to disable EDNS large packet support.
6901 For legacy reasons DNS UDP replies will default to 512 bytes which
6902 is too small for many responses. EDNS provides a means for Squid to
6903 negotiate receiving larger responses back immediately without having
6904 to failover with repeat requests. Responses larger than this limit
6905 will retain the old behaviour of failover to TCP DNS.
6907 Squid has no real fixed limit internally, but allowing packet sizes
6908 over 1500 bytes requires network jumbogram support and is usually not
6911 WARNING: The RFC also indicates that some older resolvers will reply
6912 with failure of the whole request if the extension is added. Some
6913 resolvers have already been identified which will reply with mangled
6914 EDNS response on occasion. Usually in response to many-KB jumbogram
6915 sizes being advertised by Squid.
6916 Squid will currently treat these both as an unable-to-resolve domain
6917 even if it would be resolvable without EDNS.
6924 LOC: Config.onoff.res_defnames
6926 Normally the RES_DEFNAMES resolver option is disabled
6927 (see res_init(3)). This prevents caches in a hierarchy
6928 from interpreting single-component hostnames locally. To allow
6929 Squid to handle single-component names, enable this option.
6932 NAME: dns_nameservers
6935 LOC: Config.dns_nameservers
6937 Use this if you want to specify a list of DNS name servers
6938 (IP addresses) to use instead of those given in your
6939 /etc/resolv.conf file.
6940 On Windows platforms, if no value is specified here or in
6941 the /etc/resolv.conf file, the list of DNS name servers are
6942 taken from the Windows registry, both static and dynamic DHCP
6943 configurations are supported.
6945 Example: dns_nameservers 10.0.0.1 192.172.0.4
6950 DEFAULT: @DEFAULT_HOSTS@
6951 LOC: Config.etcHostsPath
6953 Location of the host-local IP name-address associations
6954 database. Most Operating Systems have such a file on different
6956 - Un*X & Linux: /etc/hosts
6957 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
6958 (%SystemRoot% value install default is c:\winnt)
6959 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
6960 (%SystemRoot% value install default is c:\windows)
6961 - Windows 9x/Me: %windir%\hosts
6962 (%windir% value is usually c:\windows)
6963 - Cygwin: /etc/hosts
6965 The file contains newline-separated definitions, in the
6966 form ip_address_in_dotted_form name [name ...] names are
6967 whitespace-separated. Lines beginning with an hash (#)
6968 character are comments.
6970 The file is checked at startup and upon configuration.
6971 If set to 'none', it won't be checked.
6972 If append_domain is used, that domain will be added to
6973 domain-local (i.e. not containing any dot character) host
6979 LOC: Config.appendDomain
6982 Appends local domain name to hostnames without any dots in
6983 them. append_domain must begin with a period.
6985 Be warned there are now Internet names with no dots in
6986 them using only top-domain names, so setting this may
6987 cause some Internet sites to become unavailable.
6990 append_domain .yourdomain.com
6993 NAME: ignore_unknown_nameservers
6995 LOC: Config.onoff.ignore_unknown_nameservers
6998 By default Squid checks that DNS responses are received
6999 from the same IP addresses they are sent to. If they
7000 don't match, Squid ignores the response and writes a warning
7001 message to cache.log. You can allow responses from unknown
7002 nameservers by setting this option to 'off'.
7005 NAME: dns_v4_fallback
7008 LOC: Config.onoff.dns_require_A
7010 Standard practice with DNS is to lookup either A or AAAA records
7011 and use the results if it succeeds. Only looking up the other if
7012 the first attempt fails or otherwise produces no results.
7014 That policy however will cause squid to produce error pages for some
7015 servers that advertise AAAA but are unreachable over IPv6.
7017 If this is ON squid will always lookup both AAAA and A, using both.
7018 If this is OFF squid will lookup AAAA and only try A if none found.
7020 WARNING: There are some possibly unwanted side-effects with this on:
7021 *) Doubles the load placed by squid on the DNS network.
7022 *) May negatively impact connection delay times.
7026 COMMENT: (number of entries)
7029 LOC: Config.ipcache.size
7036 LOC: Config.ipcache.low
7043 LOC: Config.ipcache.high
7045 The size, low-, and high-water marks for the IP cache.
7048 NAME: fqdncache_size
7049 COMMENT: (number of entries)
7052 LOC: Config.fqdncache.size
7054 Maximum number of FQDN cache entries.
7059 -----------------------------------------------------------------------------
7066 LOC: Config.onoff.mem_pools
7068 If set, Squid will keep pools of allocated (but unused) memory
7069 available for future use. If memory is a premium on your
7070 system and you believe your malloc library outperforms Squid
7071 routines, disable this.
7074 NAME: memory_pools_limit
7078 LOC: Config.MemPools.limit
7080 Used only with memory_pools on:
7081 memory_pools_limit 50 MB
7083 If set to a non-zero value, Squid will keep at most the specified
7084 limit of allocated (but unused) memory in memory pools. All free()
7085 requests that exceed this limit will be handled by your malloc
7086 library. Squid does not pre-allocate any memory, just safe-keeps
7087 objects that otherwise would be free()d. Thus, it is safe to set
7088 memory_pools_limit to a reasonably high value even if your
7089 configuration will use less memory.
7091 If set to none, Squid will keep all memory it can. That is, there
7092 will be no limit on the total amount of memory used for safe-keeping.
7094 To disable memory allocation optimization, do not set
7095 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
7097 An overhead for maintaining memory pools is not taken into account
7098 when the limit is checked. This overhead is close to four bytes per
7099 object kept. However, pools may actually _save_ memory because of
7100 reduced memory thrashing in your malloc library.
7104 COMMENT: on|off|transparent|truncate|delete
7107 LOC: opt_forwarded_for
7109 If set to "on", Squid will append your client's IP address
7110 in the HTTP requests it forwards. By default it looks like:
7112 X-Forwarded-For: 192.1.2.3
7114 If set to "off", it will appear as
7116 X-Forwarded-For: unknown
7118 If set to "transparent", Squid will not alter the
7119 X-Forwarded-For header in any way.
7121 If set to "delete", Squid will delete the entire
7122 X-Forwarded-For header.
7124 If set to "truncate", Squid will remove all existing
7125 X-Forwarded-For entries, and place the client IP as the sole entry.
7128 NAME: cachemgr_passwd
7129 TYPE: cachemgrpasswd
7131 LOC: Config.passwd_list
7133 Specify passwords for cachemgr operations.
7135 Usage: cachemgr_passwd password action action ...
7137 Some valid actions are (see cache manager menu for a full list):
7177 * Indicates actions which will not be performed without a
7178 valid password, others can be performed if not listed here.
7180 To disable an action, set the password to "disable".
7181 To allow performing an action without a password, set the
7184 Use the keyword "all" to set the same password for all actions.
7187 cachemgr_passwd secret shutdown
7188 cachemgr_passwd lesssssssecret info stats/objects
7189 cachemgr_passwd disable all
7196 LOC: Config.onoff.client_db
7198 If you want to disable collecting per-client statistics,
7199 turn off client_db here.
7202 NAME: refresh_all_ims
7206 LOC: Config.onoff.refresh_all_ims
7208 When you enable this option, squid will always check
7209 the origin server for an update when a client sends an
7210 If-Modified-Since request. Many browsers use IMS
7211 requests when the user requests a reload, and this
7212 ensures those clients receive the latest version.
7214 By default (off), squid may return a Not Modified response
7215 based on the age of the cached version.
7218 NAME: reload_into_ims
7219 IFDEF: USE_HTTP_VIOLATIONS
7223 LOC: Config.onoff.reload_into_ims
7225 When you enable this option, client no-cache or ``reload''
7226 requests will be changed to If-Modified-Since requests.
7227 Doing this VIOLATES the HTTP standard. Enabling this
7228 feature could make you liable for problems which it
7231 see also refresh_pattern for a more selective approach.
7234 NAME: maximum_single_addr_tries
7236 LOC: Config.retry.maxtries
7239 This sets the maximum number of connection attempts for a
7240 host that only has one address (for multiple-address hosts,
7241 each address is tried once).
7243 The default value is one attempt, the (not recommended)
7244 maximum is 255 tries. A warning message will be generated
7245 if it is set to a value greater than ten.
7247 Note: This is in addition to the request re-forwarding which
7248 takes place if Squid fails to get a satisfying response.
7251 NAME: retry_on_error
7253 LOC: Config.retry.onerror
7256 If set to on Squid will automatically retry requests when
7257 receiving an error response. This is mainly useful if you
7258 are in a complex cache hierarchy to work around access
7262 NAME: as_whois_server
7264 LOC: Config.as_whois_server
7265 DEFAULT: whois.ra.net
7267 WHOIS server to query for AS numbers. NOTE: AS numbers are
7268 queried only when Squid starts up, not for every request.
7273 LOC: Config.onoff.offline
7276 Enable this option and Squid will never try to validate cached
7280 NAME: uri_whitespace
7281 TYPE: uri_whitespace
7282 LOC: Config.uri_whitespace
7285 What to do with requests that have whitespace characters in the
7288 strip: The whitespace characters are stripped out of the URL.
7289 This is the behavior recommended by RFC2396.
7290 deny: The request is denied. The user receives an "Invalid
7292 allow: The request is allowed and the URI is not changed. The
7293 whitespace characters remain in the URI. Note the
7294 whitespace is passed to redirector processes if they
7296 encode: The request is allowed and the whitespace characters are
7297 encoded according to RFC1738. This could be considered
7298 a violation of the HTTP/1.1
7299 RFC because proxies are not allowed to rewrite URI's.
7300 chop: The request is allowed and the URI is chopped at the
7301 first whitespace. This might also be considered a
7307 LOC: Config.chroot_dir
7310 Specifies a directory where Squid should do a chroot() while
7311 initializing. This also causes Squid to fully drop root
7312 privileges after initializing. This means, for example, if you
7313 use a HTTP port less than 1024 and try to reconfigure, you may
7314 get an error saying that Squid can not open the port.
7317 NAME: balance_on_multiple_ip
7319 LOC: Config.onoff.balance_on_multiple_ip
7322 Modern IP resolvers in squid sort lookup results by preferred access.
7323 By default squid will use these IP in order and only rotates to
7324 the next listed when the most preffered fails.
7326 Some load balancing servers based on round robin DNS have been
7327 found not to preserve user session state across requests
7328 to different IP addresses.
7330 Enabling this directive Squid rotates IP's per request.
7333 NAME: pipeline_prefetch
7335 LOC: Config.onoff.pipeline_prefetch
7338 To boost the performance of pipelined requests to closer
7339 match that of a non-proxied environment Squid can try to fetch
7340 up to two requests in parallel from a pipeline.
7342 Defaults to off for bandwidth management and access logging
7346 NAME: high_response_time_warning
7349 LOC: Config.warnings.high_rptm
7352 If the one-minute median response time exceeds this value,
7353 Squid prints a WARNING with debug level 0 to get the
7354 administrators attention. The value is in milliseconds.
7357 NAME: high_page_fault_warning
7359 LOC: Config.warnings.high_pf
7362 If the one-minute average page fault rate exceeds this
7363 value, Squid prints a WARNING with debug level 0 to get
7364 the administrators attention. The value is in page faults
7368 NAME: high_memory_warning
7370 LOC: Config.warnings.high_memory
7373 If the memory usage (as determined by mallinfo) exceeds
7374 this amount, Squid prints a WARNING with debug level 0 to get
7375 the administrators attention.
7378 NAME: sleep_after_fork
7379 COMMENT: (microseconds)
7381 LOC: Config.sleep_after_fork
7384 When this is set to a non-zero value, the main Squid process
7385 sleeps the specified number of microseconds after a fork()
7386 system call. This sleep may help the situation where your
7387 system reports fork() failures due to lack of (virtual)
7388 memory. Note, however, if you have a lot of child
7389 processes, these sleep delays will add up and your
7390 Squid will not service requests for some amount of time
7391 until all the child processes have been started.
7392 On Windows value less then 1000 (1 milliseconds) are
7396 NAME: windows_ipaddrchangemonitor
7397 IFDEF: _SQUID_MSWIN_
7401 LOC: Config.onoff.WIN32_IpAddrChangeMonitor
7403 On Windows Squid by default will monitor IP address changes and will
7404 reconfigure itself after any detected event. This is very useful for
7405 proxies connected to internet with dial-up interfaces.
7406 In some cases (a Proxy server acting as VPN gateway is one) it could be
7407 desiderable to disable this behaviour setting this to 'off'.
7408 Note: after changing this, Squid service must be restarted.
7413 IFDEF: USE_SQUID_EUI
7415 LOC: Eui::TheConfig.euiLookup
7417 Whether to lookup the EUI or MAC address of a connected client.
7420 NAME: max_filedescriptors max_filedesc
7423 LOC: Config.max_filedescriptors
7425 The maximum number of filedescriptors supported.
7427 The default "0" means Squid inherits the current ulimit setting.
7429 Note: Changing this requires a restart of Squid. Also
7430 not all comm loops supports large values.
7438 Number of main Squid processes or "workers" to fork and maintain.
7439 0: "no daemon" mode, like running "squid -N ..."
7440 1: "no SMP" mode, start one main Squid process daemon (default)
7441 N: start N main Squid process daemons (i.e., SMP mode)
7443 In SMP mode, each worker does nearly all what a single Squid daemon
7444 does (e.g., listen on http_port and forward HTTP requests).
7447 NAME: cpu_affinity_map
7448 TYPE: CpuAffinityMap
7449 LOC: Config.cpuAffinityMap
7452 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
7454 Sets 1:1 mapping between Squid processes and CPU cores. For example,
7456 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
7458 affects processes 1 through 4 only and places them on the first
7459 four even cores, starting with core #1.
7461 CPU cores are numbered starting from 1. Requires support for
7462 sched_getaffinity(2) and sched_setaffinity(2) system calls.
7464 Multiple cpu_affinity_map options are merged.