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 documentation for the Squid configuration file.
34 This documentation can also be found online at:
35 http://www.squid-cache.org/Doc/config/
37 You may wish to look at the Squid home page and wiki for the
38 FAQ and other documentation:
39 http://www.squid-cache.org/
40 http://wiki.squid-cache.org/SquidFaq
41 http://wiki.squid-cache.org/ConfigExamples
43 This documentation shows what the defaults for various directives
44 happen to be. If you don't need to change the default, you should
45 leave the line out of your squid.conf in most cases.
47 In some cases "none" refers to no default setting at all,
48 while in other cases it refers to the value of the option
49 - the comments for that keyword indicate if this is the case.
54 Configuration options can be included using the "include" directive.
55 Include takes a list of files to include. Quoting and wildcards are
60 include /path/to/included/file/squid.acl.config
62 Includes can be nested up to a hard-coded depth of 16 levels.
63 This arbitrary restriction is to prevent recursive include references
64 from causing Squid entering an infinite loop whilst trying to load
67 Values with byte units
69 Squid accepts size units on some size related directives. All
70 such directives are documented with a default value displaying
73 Units accepted by Squid are:
75 KB - Kilobyte (1024 bytes)
79 Values with spaces, quotes, and other special characters
81 Squid supports directive parameters with spaces, quotes, and other
82 special characters. Surround such parameters with "double quotes". Use
83 the configuration_includes_quoted_values directive to enable or
86 Squid supports reading configuration option parameters from external
87 files using the syntax:
88 parameters("/path/filename")
90 acl whitelist dstdomain parameters("/etc/squid/whitelist.txt")
92 Conditional configuration
94 If-statements can be used to make configuration directives
98 ... regular configuration directives ...
100 ... regular configuration directives ...]
103 The else part is optional. The keywords "if", "else", and "endif"
104 must be typed on their own lines, as if they were regular
105 configuration directives.
107 NOTE: An else-if condition is not supported.
109 These individual conditions types are supported:
112 Always evaluates to true.
114 Always evaluates to false.
115 <integer> = <integer>
116 Equality comparison of two integer numbers.
121 The following SMP-related preprocessor macros can be used.
123 ${process_name} expands to the current Squid process "name"
124 (e.g., squid1, squid2, or cache1).
126 ${process_number} expands to the current Squid process
127 identifier, which is an integer number (e.g., 1, 2, 3) unique
128 across all Squid processes of the current service instance.
130 ${service_name} expands into the current Squid service instance
131 name identifier which is provided by -n on the command line.
135 # options still not yet ported from 2.7 to 3.x
136 NAME: broken_vary_encoding
139 This option is not yet supported by Squid-3.
145 This option is not yet supported by Squid-3.
151 This option is not yet supported by Squid-3.
154 NAME: external_refresh_check
157 This option is not yet supported by Squid-3.
160 NAME: location_rewrite_program location_rewrite_access location_rewrite_children location_rewrite_concurrency
163 This option is not yet supported by Squid-3.
166 NAME: refresh_stale_hit
169 This option is not yet supported by Squid-3.
172 # Options removed in 3.5
173 NAME: hierarchy_stoplist
176 Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use.
182 Remove this line. Use acls with access_log directives to control access logging
188 Remove this line. Use acls with icap_log directives to control icap logging
191 # Options Removed in 3.3
192 NAME: ignore_ims_on_miss
195 Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'.
198 # Options Removed in 3.2
199 NAME: dns_v4_fallback
202 Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant.
205 NAME: emulate_httpd_log
208 Replace this with an access_log directive using the format 'common' or 'combined'.
214 Use a regular access.log with ACL limiting it to MISS events.
220 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
223 NAME: ignore_expect_100
226 Remove this line. The HTTP/1.1 feature is now fully supported by default.
232 Remove this option from your config. To log FQDN use %>A in the log format.
235 NAME: log_ip_on_direct
238 Remove this option from your config. To log server or peer names use %<A in the log format.
241 NAME: maximum_single_addr_tries
244 Replaced by connect_retries. The behaviour has changed, please read the documentation before altering.
247 NAME: referer_log referrer_log
250 Replace this with an access_log directive using the format 'referrer'.
256 Remove this line. The feature is supported by default in storage types where update is implemented.
259 NAME: url_rewrite_concurrency
262 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead.
268 Replace this with an access_log directive using the format 'useragent'.
271 # Options Removed in 3.1
275 Remove this line. DNS is no longer tested on startup.
278 NAME: extension_methods
281 Remove this line. All valid methods for HTTP are accepted by default.
284 # 2.7 Options Removed/Replaced in 3.2
289 # 2.7 Options Removed/Replaced in 3.1
297 Remove this line. HTTP/1.1 is supported by default.
300 NAME: upgrade_http0.9
303 Remove this line. ICY/1.0 streaming protocol is supported by default.
306 NAME: zph_local zph_mode zph_option zph_parent zph_sibling
309 Alter these entries. Use the qos_flows directive instead.
312 # Options Removed in 3.0
316 Since squid-3.0 replace with request_header_access or reply_header_access
317 depending on whether you wish to match client requests or server replies.
320 NAME: httpd_accel_no_pmtu_disc
323 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
326 NAME: wais_relay_host
329 Replace this line with 'cache_peer' configuration.
332 NAME: wais_relay_port
335 Replace this line with 'cache_peer' configuration.
339 OPTIONS FOR AUTHENTICATION
340 -----------------------------------------------------------------------------
349 This is used to define parameters for the various authentication
350 schemes supported by Squid.
352 format: auth_param scheme parameter [setting]
354 The order in which authentication schemes are presented to the client is
355 dependent on the order the scheme first appears in config file. IE
356 has a bug (it's not RFC 2617 compliant) in that it will use the basic
357 scheme if basic is the first entry presented, even if more secure
358 schemes are presented. For now use the order in the recommended
359 settings section below. If other browsers have difficulties (don't
360 recognize the schemes offered even if you are using basic) either
361 put basic first, or disable the other schemes (by commenting out their
364 Once an authentication scheme is fully configured, it can only be
365 shutdown by shutting squid down and restarting. Changes can be made on
366 the fly and activated with a reconfigure. I.E. You can change to a
367 different helper, but not unconfigure the helper completely.
369 Please note that while this directive defines how Squid processes
370 authentication it does not automatically activate authentication.
371 To use authentication you must in addition make use of ACLs based
372 on login name in http_access (proxy_auth, proxy_auth_regex or
373 external with %LOGIN used in the format tag). The browser will be
374 challenged for authentication on the first such acl encountered
375 in http_access processing and will also be re-challenged for new
376 login credentials if the request is being denied by a proxy_auth
379 WARNING: authentication can't be used in a transparently intercepting
380 proxy as the client then thinks it is talking to an origin server and
381 not the proxy. This is a limitation of bending the TCP/IP protocol to
382 transparently intercepting port 80, not a limitation in Squid.
383 Ports flagged 'transparent', 'intercept', or 'tproxy' have
384 authentication disabled.
386 === Parameters common to all schemes. ===
389 Specifies the command for the external authenticator.
391 By default, each authentication scheme is not used unless a
392 program is specified.
394 See http://wiki.squid-cache.org/Features/AddonHelpers for
395 more details on helper operations and creating your own.
398 Specifies a string to be append to request line format for
399 the authentication helper. "Quoted" format values may contain
400 spaces and logformat %macros. In theory, any logformat %macro
401 can be used. In practice, a %macro expands as a dash (-) if
402 the helper request is sent before the required macro
403 information is available to Squid.
405 By default, Squid uses request formats provided in
406 scheme-specific examples below (search for %credentials).
408 The expanded key_extras value is added to the Squid credentials
409 cache and, hence, will affect authentication. It can be used to
410 autenticate different users with identical user names (e.g.,
411 when user authentication depends on http_port).
413 Avoid adding frequently changing information to key_extras. For
414 example, if you add user source IP, and it changes frequently
415 in your environment, then max_user_ip ACL is going to treat
416 every user+IP combination as a unique "user", breaking the ACL
417 and wasting a lot of memory on those user records. It will also
418 force users to authenticate from scratch whenever their IP
422 Specifies the protection scope (aka realm name) which is to be
423 reported to the client for the authentication scheme. It is
424 commonly part of the text the user will see when prompted for
425 their username and password.
427 For Basic the default is "Squid proxy-caching web server".
428 For Digest there is no default, this parameter is mandatory.
429 For NTLM and Negotiate this parameter is ignored.
431 "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
433 The maximum number of authenticator processes to spawn. If
434 you start too few Squid will have to wait for them to process
435 a backlog of credential verifications, slowing it down. When
436 password verifications are done via a (slow) network you are
437 likely to need lots of authenticator processes.
439 The startup= and idle= options permit some skew in the exact
440 amount run. A minimum of startup=N will begin during startup
441 and reconfigure. Squid will start more in groups of up to
442 idle=N in an attempt to meet traffic needs and to keep idle=N
443 free above those traffic needs up to the maximum.
445 The concurrency= option sets the number of concurrent requests
446 the helper can process. The default of 0 is used for helpers
447 who only supports one request at a time. Setting this to a
448 number greater than 0 changes the protocol used to include a
449 channel ID field first on the request/response line, allowing
450 multiple requests to be sent to the same helper in parallel
451 without waiting for the response.
453 Concurrency must not be set unless it's known the helper
454 supports the input format with channel-ID fields.
456 NOTE: NTLM and Negotiate schemes do not support concurrency
457 in the Squid code module even though some helpers can.
460 IF HAVE_AUTH_MODULE_BASIC
461 === Basic authentication parameters ===
464 HTTP uses iso-latin-1 as character set, while some
465 authentication backends such as LDAP expects UTF-8. If this is
466 set to on Squid will translate the HTTP iso-latin-1 charset to
467 UTF-8 before sending the username and password to the helper.
469 "credentialsttl" timetolive
470 Specifies how long squid assumes an externally validated
471 username:password pair is valid for - in other words how
472 often the helper program is called for that user. Set this
473 low to force revalidation with short lived passwords.
475 NOTE: setting this high does not impact your susceptibility
476 to replay attacks unless you are using an one-time password
477 system (such as SecureID). If you are using such a system,
478 you will be vulnerable to replay attacks unless you also
479 use the max_user_ip ACL in an http_access rule.
481 "casesensitive" on|off
482 Specifies if usernames are case sensitive. Most user databases
483 are case insensitive allowing the same username to be spelled
484 using both lower and upper case letters, but some are case
485 sensitive. This makes a big difference for user_max_ip ACL
486 processing and similar.
489 IF HAVE_AUTH_MODULE_DIGEST
490 === Digest authentication parameters ===
493 HTTP uses iso-latin-1 as character set, while some
494 authentication backends such as LDAP expects UTF-8. If this is
495 set to on Squid will translate the HTTP iso-latin-1 charset to
496 UTF-8 before sending the username and password to the helper.
498 "nonce_garbage_interval" timeinterval
499 Specifies the interval that nonces that have been issued
500 to client_agent's are checked for validity.
502 "nonce_max_duration" timeinterval
503 Specifies the maximum length of time a given nonce will be
506 "nonce_max_count" number
507 Specifies the maximum number of times a given nonce can be
510 "nonce_strictness" on|off
511 Determines if squid requires strict increment-by-1 behavior
512 for nonce counts, or just incrementing (off - for use when
513 user agents generate nonce counts that occasionally miss 1
514 (ie, 1,2,4,6)). Default off.
516 "check_nonce_count" on|off
517 This directive if set to off can disable the nonce count check
518 completely to work around buggy digest qop implementations in
519 certain mainstream browser versions. Default on to check the
520 nonce count to protect from authentication replay attacks.
522 "post_workaround" on|off
523 This is a workaround to certain buggy browsers who send an
524 incorrect request digest in POST requests when reusing the
525 same nonce as acquired earlier on a GET request.
528 IF HAVE_AUTH_MODULE_NEGOTIATE
529 === Negotiate authentication parameters ===
532 If you experience problems with PUT/POST requests when using
533 the this authentication scheme then you can try setting this
534 to off. This will cause Squid to forcibly close the connection
535 on the initial request where the browser asks which schemes
536 are supported by the proxy.
539 IF HAVE_AUTH_MODULE_NTLM
540 === NTLM authentication parameters ===
543 If you experience problems with PUT/POST requests when using
544 the this authentication scheme then you can try setting this
545 to off. This will cause Squid to forcibly close the connection
546 on the initial request where the browser asks which schemes
547 are supported by the proxy.
550 === Example Configuration ===
552 This configuration displays the recommended authentication scheme
553 order from most to least secure with recommended minimum configuration
554 settings for each scheme:
556 #auth_param negotiate program <uncomment and complete this line to activate>
557 #auth_param negotiate children 20 startup=0 idle=1
558 #auth_param negotiate keep_alive on
560 #auth_param digest program <uncomment and complete this line to activate>
561 #auth_param digest children 20 startup=0 idle=1
562 #auth_param digest realm Squid proxy-caching web server
563 #auth_param digest nonce_garbage_interval 5 minutes
564 #auth_param digest nonce_max_duration 30 minutes
565 #auth_param digest nonce_max_count 50
567 #auth_param ntlm program <uncomment and complete this line to activate>
568 #auth_param ntlm children 20 startup=0 idle=1
569 #auth_param ntlm keep_alive on
571 #auth_param basic program <uncomment and complete this line>
572 #auth_param basic children 5 startup=5 idle=1
573 #auth_param basic realm Squid proxy-caching web server
574 #auth_param basic credentialsttl 2 hours
577 NAME: authenticate_cache_garbage_interval
580 LOC: Config.authenticateGCInterval
582 The time period between garbage collection across the username cache.
583 This is a trade-off between memory utilization (long intervals - say
584 2 days) and CPU (short intervals - say 1 minute). Only change if you
588 NAME: authenticate_ttl
591 LOC: Config.authenticateTTL
593 The time a user & their credentials stay in the logged in
594 user cache since their last request. When the garbage
595 interval passes, all user credentials that have passed their
596 TTL are removed from memory.
599 NAME: authenticate_ip_ttl
601 LOC: Config.authenticateIpTTL
604 If you use proxy authentication and the 'max_user_ip' ACL,
605 this directive controls how long Squid remembers the IP
606 addresses associated with each user. Use a small value
607 (e.g., 60 seconds) if your users might change addresses
608 quickly, as is the case with dialup. You might be safe
609 using a larger value (e.g., 2 hours) in a corporate LAN
610 environment with relatively static address assignments.
615 -----------------------------------------------------------------------------
618 NAME: external_acl_type
619 TYPE: externalAclHelper
620 LOC: Config.externalAclHelperList
623 This option defines external acl classes using a helper program
624 to look up the status
626 external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
630 ttl=n TTL in seconds for cached results (defaults to 3600
633 TTL for cached negative lookups (default same
636 Maximum number of acl helper processes spawned to service
637 external acl lookups of this type. (default 20)
639 Minimum number of acl helper processes to spawn during
640 startup and reconfigure to service external acl lookups
641 of this type. (default 0)
643 Number of acl helper processes to keep ahead of traffic
644 loads. Squid will spawn this many at once whenever load
645 rises above the capabilities of existing processes.
646 Up to the value of children-max. (default 1)
647 concurrency=n concurrency level per process. Only used with helpers
648 capable of processing more than one query at a time.
649 cache=n limit the result cache size, default is 262144.
650 grace=n Percentage remaining of TTL where a refresh of a
651 cached entry should be initiated without needing to
652 wait for a new reply. (default is for no grace period)
653 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
654 ipv4 / ipv6 IP protocol used to communicate with this helper.
655 The default is to auto-detect IPv6 and use it when available.
657 FORMAT specifications
659 %LOGIN Authenticated user login name
660 %EXT_USER Username from previous external acl
661 %EXT_LOG Log details from previous external acl
662 %EXT_TAG Tag from previous external acl
663 %IDENT Ident user name
665 %SRCPORT Client source port
668 %PROTO Requested URL scheme
670 %PATH Requested URL path
671 %METHOD Request method
672 %MYADDR Squid interface address
673 %MYPORT Squid http_port number
674 %PATH Requested URL-path (including query-string if any)
675 %USER_CERT SSL User certificate in PEM format
676 %USER_CERTCHAIN SSL User certificate chain in PEM format
677 %USER_CERT_xx SSL User certificate subject attribute xx
678 %USER_CA_CERT_xx SSL User certificate issuer attribute xx
680 %>{Header} HTTP request header "Header"
682 HTTP request header "Hdr" list member "member"
684 HTTP request header list member using ; as
685 list separator. ; can be any non-alphanumeric
688 %<{Header} HTTP reply header "Header"
690 HTTP reply header "Hdr" list member "member"
692 HTTP reply header list member using ; as
693 list separator. ; can be any non-alphanumeric
696 %ACL The name of the ACL being tested.
697 %DATA The ACL arguments. If not used then any arguments
698 is automatically added at the end of the line
700 NOTE: this will encode the arguments as one token,
701 whereas the default will pass each separately.
703 %% The percent sign. Useful for helpers which need
704 an unchanging input format.
707 General request syntax:
709 [channel-ID] FORMAT-values [acl-values ...]
712 FORMAT-values consists of transaction details expanded with
713 whitespace separation per the config file FORMAT specification
714 using the FORMAT macros listed above.
716 acl-values consists of any string specified in the referencing
717 config 'acl ... external' line. see the "acl external" directive.
719 Request values sent to the helper are URL escaped to protect
720 each value in requests against whitespaces.
722 If using protocol=2.5 then the request sent to the helper is not
723 URL escaped to protect against whitespace.
725 NOTE: protocol=3.0 is deprecated as no longer necessary.
727 When using the concurrency= option the protocol is changed by
728 introducing a query channel tag in front of the request/response.
729 The query channel tag is a number between 0 and concurrency-1.
730 This value must be echoed back unchanged to Squid as the first part
731 of the response relating to its request.
734 The helper receives lines expanded per the above format specification
735 and for each input line returns 1 line starting with OK/ERR/BH result
736 code and optionally followed by additional keywords with more details.
739 General result syntax:
741 [channel-ID] result keyword=value ...
743 Result consists of one of the codes:
746 the ACL test produced a match.
749 the ACL test does not produce a match.
752 An internal error occurred in the helper, preventing
753 a result being identified.
755 The meaning of 'a match' is determined by your squid.conf
756 access control configuration. See the Squid wiki for details.
760 user= The users name (login)
762 password= The users password (for login= cache_peer option)
764 message= Message describing the reason for this response.
765 Available as %o in error pages.
766 Useful on (ERR and BH results).
768 tag= Apply a tag to a request. Only sets a tag once,
769 does not alter existing tags.
771 log= String to be logged in access.log. Available as
772 %ea in logformat specifications.
774 clt_conn_tag= Associates a TAG with the client TCP connection.
775 Please see url_rewrite_program related documentation for
778 Any keywords may be sent on any response whether OK, ERR or BH.
780 All response keyword values need to be a single token with URL
781 escaping, or enclosed in double quotes (") and escaped using \ on
782 any double quotes or \ characters within the value. The wrapping
783 double quotes are removed before the value is interpreted by Squid.
784 \r and \n are also replace by CR and LF.
786 Some example key values:
790 user="J. \"Bob\" Smith"
797 DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED
798 DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID
799 DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH
800 DEFAULT: ssl::certUntrusted ssl_error X509_V_ERR_INVALID_CA X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY X509_V_ERR_CERT_UNTRUSTED
801 DEFAULT: ssl::certSelfSigned ssl_error X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
804 DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
805 DEFAULT: localhost src 127.0.0.1/32 ::1
806 DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
807 DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
809 Defining an Access List
811 Every access list definition must begin with an aclname and acltype,
812 followed by either type-specific arguments or a quoted filename that
815 acl aclname acltype argument ...
816 acl aclname acltype "file" ...
818 When using "file", the file should contain one item per line.
820 Some acl types supports options which changes their default behaviour.
821 The available options are:
823 -i,+i By default, regular expressions are CASE-SENSITIVE. To make them
824 case-insensitive, use the -i option. To return case-sensitive
825 use the +i option between patterns, or make a new ACL line
828 -n Disable lookups and address type conversions. If lookup or
829 conversion is required because the parameter type (IP or
830 domain name) does not match the message address type (domain
831 name or IP), then the ACL would immediately declare a mismatch
832 without any warnings or lookups.
834 -- Used to stop processing all options, in the case the first acl
835 value has '-' character as first character (for example the '-'
836 is a valid domain name)
838 Some acl types require suspending the current request in order
839 to access some external data source.
840 Those which do are marked with the tag [slow], those which
841 don't are marked as [fast].
842 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
843 for further information
845 ***** ACL TYPES AVAILABLE *****
847 acl aclname src ip-address/mask ... # clients IP address [fast]
848 acl aclname src addr1-addr2/mask ... # range of addresses [fast]
849 acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow]
850 acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
852 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
853 # The arp ACL requires the special configure option --enable-arp-acl.
854 # Furthermore, the ARP ACL code is not portable to all operating systems.
855 # It works on Linux, Solaris, Windows, FreeBSD, and some
856 # other *BSD variants.
859 # NOTE: Squid can only determine the MAC address for clients that are on
860 # the same subnet. If the client is on a different subnet,
861 # then Squid cannot find out its MAC address.
863 acl aclname srcdomain .foo.com ...
864 # reverse lookup, from client IP [slow]
865 acl aclname dstdomain [-n] .foo.com ...
866 # Destination server from URL [fast]
867 acl aclname srcdom_regex [-i] \.foo\.com ...
868 # regex matching client name [slow]
869 acl aclname dstdom_regex [-n] [-i] \.foo\.com ...
870 # regex matching server [fast]
872 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
873 # based URL is used and no match is found. The name "none" is used
874 # if the reverse lookup fails.
876 acl aclname src_as number ...
877 acl aclname dst_as number ...
879 # Except for access control, AS numbers can be used for
880 # routing of requests to specific caches. Here's an
881 # example for routing all requests for AS#1241 and only
882 # those to mycache.mydomain.net:
883 # acl asexample dst_as 1241
884 # cache_peer_access mycache.mydomain.net allow asexample
885 # cache_peer_access mycache_mydomain.net deny all
887 acl aclname peername myPeer ...
889 # match against a named cache_peer entry
890 # set unique name= on cache_peer lines for reliable use.
892 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
902 # h1:m1 must be less than h2:m2
904 acl aclname url_regex [-i] ^http:// ...
905 # regex matching on whole URL [fast]
906 acl aclname urllogin [-i] [^a-zA-Z0-9] ...
907 # regex matching on URL login field
908 acl aclname urlpath_regex [-i] \.gif$ ...
909 # regex matching on URL path [fast]
911 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
913 acl aclname localport 3128 ... # TCP port the client connected to [fast]
914 # NP: for interception mode this is usually '80'
916 acl aclname myportname 3128 ... # *_port name [fast]
918 acl aclname proto HTTP FTP ... # request protocol [fast]
920 acl aclname method GET POST ... # HTTP request method [fast]
922 acl aclname http_status 200 301 500- 400-403 ...
923 # status code in reply [fast]
925 acl aclname browser [-i] regexp ...
926 # pattern match on User-Agent header (see also req_header below) [fast]
928 acl aclname referer_regex [-i] regexp ...
929 # pattern match on Referer header [fast]
930 # Referer is highly unreliable, so use with care
932 acl aclname ident username ...
933 acl aclname ident_regex [-i] pattern ...
934 # string match on ident output [slow]
935 # use REQUIRED to accept any non-null ident.
937 acl aclname proxy_auth [-i] username ...
938 acl aclname proxy_auth_regex [-i] pattern ...
939 # perform http authentication challenge to the client and match against
940 # supplied credentials [slow]
942 # takes a list of allowed usernames.
943 # use REQUIRED to accept any valid username.
945 # Will use proxy authentication in forward-proxy scenarios, and plain
946 # http authenticaiton in reverse-proxy scenarios
948 # NOTE: when a Proxy-Authentication header is sent but it is not
949 # needed during ACL checking the username is NOT logged
952 # NOTE: proxy_auth requires a EXTERNAL authentication program
953 # to check username/password combinations (see
954 # auth_param directive).
956 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
957 # as the browser needs to be configured for using a proxy in order
958 # to respond to proxy authentication.
960 acl aclname snmp_community string ...
961 # A community string to limit access to your SNMP Agent [fast]
964 # acl snmppublic snmp_community public
966 acl aclname maxconn number
967 # This will be matched when the client's IP address has
968 # more than <number> TCP connections established. [fast]
969 # NOTE: This only measures direct TCP links so X-Forwarded-For
970 # indirect clients are not counted.
972 acl aclname max_user_ip [-s] number
973 # This will be matched when the user attempts to log in from more
974 # than <number> different ip addresses. The authenticate_ip_ttl
975 # parameter controls the timeout on the ip entries. [fast]
976 # If -s is specified the limit is strict, denying browsing
977 # from any further IP addresses until the ttl has expired. Without
978 # -s Squid will just annoy the user by "randomly" denying requests.
979 # (the counter is reset each time the limit is reached and a
981 # NOTE: in acceleration mode or where there is mesh of child proxies,
982 # clients may appear to come from multiple addresses if they are
983 # going through proxy farms, so a limit of 1 may cause user problems.
985 acl aclname random probability
986 # Pseudo-randomly match requests. Based on the probability given.
987 # Probability may be written as a decimal (0.333), fraction (1/3)
988 # or ratio of matches:non-matches (3:5).
990 acl aclname req_mime_type [-i] mime-type ...
991 # regex match against the mime type of the request generated
992 # by the client. Can be used to detect file upload or some
993 # types HTTP tunneling requests [fast]
994 # NOTE: This does NOT match the reply. You cannot use this
995 # to match the returned file type.
997 acl aclname req_header header-name [-i] any\.regex\.here
998 # regex match against any of the known request headers. May be
999 # thought of as a superset of "browser", "referer" and "mime-type"
1002 acl aclname rep_mime_type [-i] mime-type ...
1003 # regex match against the mime type of the reply received by
1004 # squid. Can be used to detect file download or some
1005 # types HTTP tunneling requests. [fast]
1006 # NOTE: This has no effect in http_access rules. It only has
1007 # effect in rules that affect the reply data stream such as
1008 # http_reply_access.
1010 acl aclname rep_header header-name [-i] any\.regex\.here
1011 # regex match against any of the known reply headers. May be
1012 # thought of as a superset of "browser", "referer" and "mime-type"
1015 acl aclname external class_name [arguments...]
1016 # external ACL lookup via a helper class defined by the
1017 # external_acl_type directive [slow]
1019 acl aclname user_cert attribute values...
1020 # match against attributes in a user SSL certificate
1021 # attribute is one of DN/C/O/CN/L/ST [fast]
1023 acl aclname ca_cert attribute values...
1024 # match against attributes a users issuing CA SSL certificate
1025 # attribute is one of DN/C/O/CN/L/ST [fast]
1027 acl aclname ext_user username ...
1028 acl aclname ext_user_regex [-i] pattern ...
1029 # string match on username returned by external acl helper [slow]
1030 # use REQUIRED to accept any non-null user name.
1032 acl aclname tag tagvalue ...
1033 # string match on tag returned by external acl helper [fast]
1034 # DEPRECATED. Only the first tag will match with this ACL.
1035 # Use the 'note' ACL instead for handling multiple tag values.
1037 acl aclname hier_code codename ...
1038 # string match against squid hierarchy code(s); [fast]
1039 # e.g., DIRECT, PARENT_HIT, NONE, etc.
1041 # NOTE: This has no effect in http_access rules. It only has
1042 # effect in rules that affect the reply data stream such as
1043 # http_reply_access.
1045 acl aclname note name [value ...]
1046 # match transaction annotation [fast]
1047 # Without values, matches any annotation with a given name.
1048 # With value(s), matches any annotation with a given name that
1049 # also has one of the given values.
1050 # Names and values are compared using a string equality test.
1051 # Annotation sources include note and adaptation_meta directives
1052 # as well as helper and eCAP responses.
1054 acl aclname adaptation_service service ...
1055 # Matches the name of any icap_service, ecap_service,
1056 # adaptation_service_set, or adaptation_service_chain that Squid
1057 # has used (or attempted to use) for the master transaction.
1058 # This ACL must be defined after the corresponding adaptation
1059 # service is named in squid.conf. This ACL is usable with
1060 # adaptation_meta because it starts matching immediately after
1061 # the service has been selected for adaptation.
1064 acl aclname ssl_error errorname
1065 # match against SSL certificate validation error [fast]
1067 # For valid error names see in @DEFAULT_ERROR_DIR@/templates/error-details.txt
1070 # The following can be used as shortcuts for certificate properties:
1071 # [ssl::]certHasExpired: the "not after" field is in the past
1072 # [ssl::]certNotYetValid: the "not before" field is in the future
1073 # [ssl::]certUntrusted: The certificate issuer is not to be trusted.
1074 # [ssl::]certSelfSigned: The certificate is self signed.
1075 # [ssl::]certDomainMismatch: The certificate CN domain does not
1076 # match the name the name of the host we are connecting to.
1078 # The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch,
1079 # ssl::certUntrusted, and ssl::certSelfSigned can also be used as
1080 # predefined ACLs, just like the 'all' ACL.
1082 # NOTE: The ssl_error ACL is only supported with sslproxy_cert_error,
1083 # sslproxy_cert_sign, and sslproxy_cert_adapt options.
1085 acl aclname server_cert_fingerprint [-sha1] fingerprint
1086 # match against server SSL certificate fingerprint [fast]
1088 # The fingerprint is the digest of the DER encoded version
1089 # of the whole certificate. The user should use the form: XX:XX:...
1090 # Optional argument specifies the digest algorithm to use.
1091 # The SHA1 digest algorithm is the default and is currently
1092 # the only algorithm supported (-sha1).
1094 acl aclname any-of acl1 acl2 ...
1095 # match any one of the acls [fast or slow]
1096 # The first matching ACL stops further ACL evaluation.
1098 # ACLs from multiple any-of lines with the same name are ORed.
1099 # For example, A = (a1 or a2) or (a3 or a4) can be written as
1100 # acl A any-of a1 a2
1101 # acl A any-of a3 a4
1103 # This group ACL is fast if all evaluated ACLs in the group are fast
1104 # and slow otherwise.
1106 acl aclname all-of acl1 acl2 ...
1107 # match all of the acls [fast or slow]
1108 # The first mismatching ACL stops further ACL evaluation.
1110 # ACLs from multiple all-of lines with the same name are ORed.
1111 # For example, B = (b1 and b2) or (b3 and b4) can be written as
1112 # acl B all-of b1 b2
1113 # acl B all-of b3 b4
1115 # This group ACL is fast if all evaluated ACLs in the group are fast
1116 # and slow otherwise.
1119 acl macaddress arp 09:00:2b:23:45:67
1120 acl myexample dst_as 1241
1121 acl password proxy_auth REQUIRED
1122 acl fileupload req_mime_type -i ^multipart/form-data$
1123 acl javascript rep_mime_type -i ^application/x-javascript$
1127 # Recommended minimum configuration:
1130 # Example rule allowing access from your local networks.
1131 # Adapt to list your (internal) IP networks from where browsing
1133 acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
1134 acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
1135 acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
1136 acl localnet src fc00::/7 # RFC 4193 local private network range
1137 acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
1139 acl SSL_ports port 443
1140 acl Safe_ports port 80 # http
1141 acl Safe_ports port 21 # ftp
1142 acl Safe_ports port 443 # https
1143 acl Safe_ports port 70 # gopher
1144 acl Safe_ports port 210 # wais
1145 acl Safe_ports port 1025-65535 # unregistered ports
1146 acl Safe_ports port 280 # http-mgmt
1147 acl Safe_ports port 488 # gss-http
1148 acl Safe_ports port 591 # filemaker
1149 acl Safe_ports port 777 # multiling http
1150 acl CONNECT method CONNECT
1154 NAME: proxy_protocol_access
1156 LOC: Config.accessList.proxyProtocol
1158 DEFAULT_DOC: all TCP connections to ports with require-proxy-header will be denied
1160 Determine which client proxies can be trusted to provide correct
1161 information regarding real client IP address using PROXY protocol.
1163 Requests may pass through a chain of several other proxies
1164 before reaching us. The original source details may by sent in:
1165 * HTTP message Forwarded header, or
1166 * HTTP message X-Forwarded-For header, or
1167 * PROXY protocol connection header.
1169 This directive is solely for validating new PROXY protocol
1170 connections received from a port flagged with require-proxy-header.
1171 It is checked only once after TCP connection setup.
1173 A deny match results in TCP connection closure.
1175 An allow match is required for Squid to permit the corresponding
1176 TCP connection, before Squid even looks for HTTP request headers.
1177 If there is an allow match, Squid starts using PROXY header information
1178 to determine the source address of the connection for all future ACL
1179 checks, logging, etc.
1181 SECURITY CONSIDERATIONS:
1183 Any host from which we accept client IP details can place
1184 incorrect information in the relevant header, and Squid
1185 will use the incorrect information as if it were the
1186 source address of the request. This may enable remote
1187 hosts to bypass any access control restrictions that are
1188 based on the client's source addresses.
1190 This clause only supports fast acl types.
1191 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1194 NAME: follow_x_forwarded_for
1196 IFDEF: FOLLOW_X_FORWARDED_FOR
1197 LOC: Config.accessList.followXFF
1198 DEFAULT_IF_NONE: deny all
1199 DEFAULT_DOC: X-Forwarded-For header will be ignored.
1201 Determine which client proxies can be trusted to provide correct
1202 information regarding real client IP address.
1204 Requests may pass through a chain of several other proxies
1205 before reaching us. The original source details may by sent in:
1206 * HTTP message Forwarded header, or
1207 * HTTP message X-Forwarded-For header, or
1208 * PROXY protocol connection header.
1210 PROXY protocol connections are controlled by the proxy_protocol_access
1211 directive which is checked before this.
1213 If a request reaches us from a source that is allowed by this
1214 directive, then we trust the information it provides regarding
1215 the IP of the client it received from (if any).
1217 For the purpose of ACLs used in this directive the src ACL type always
1218 matches the address we are testing and srcdomain matches its rDNS.
1220 On each HTTP request Squid checks for X-Forwarded-For header fields.
1221 If found the header values are iterated in reverse order and an allow
1222 match is required for Squid to continue on to the next value.
1223 The verification ends when a value receives a deny match, cannot be
1224 tested, or there are no more values to test.
1225 NOTE: Squid does not yet follow the Forwarded HTTP header.
1227 The end result of this process is an IP address that we will
1228 refer to as the indirect client address. This address may
1229 be treated as the client address for access control, ICAP, delay
1230 pools and logging, depending on the acl_uses_indirect_client,
1231 icap_uses_indirect_client, delay_pool_uses_indirect_client,
1232 log_uses_indirect_client and tproxy_uses_indirect_client options.
1234 This clause only supports fast acl types.
1235 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1237 SECURITY CONSIDERATIONS:
1239 Any host from which we accept client IP details can place
1240 incorrect information in the relevant header, and Squid
1241 will use the incorrect information as if it were the
1242 source address of the request. This may enable remote
1243 hosts to bypass any access control restrictions that are
1244 based on the client's source addresses.
1248 acl localhost src 127.0.0.1
1249 acl my_other_proxy srcdomain .proxy.example.com
1250 follow_x_forwarded_for allow localhost
1251 follow_x_forwarded_for allow my_other_proxy
1254 NAME: acl_uses_indirect_client
1257 IFDEF: FOLLOW_X_FORWARDED_FOR
1259 LOC: Config.onoff.acl_uses_indirect_client
1261 Controls whether the indirect client address
1262 (see follow_x_forwarded_for) is used instead of the
1263 direct client address in acl matching.
1265 NOTE: maxconn ACL considers direct TCP links and indirect
1266 clients will always have zero. So no match.
1269 NAME: delay_pool_uses_indirect_client
1272 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
1274 LOC: Config.onoff.delay_pool_uses_indirect_client
1276 Controls whether the indirect client address
1277 (see follow_x_forwarded_for) is used instead of the
1278 direct client address in delay pools.
1281 NAME: log_uses_indirect_client
1284 IFDEF: FOLLOW_X_FORWARDED_FOR
1286 LOC: Config.onoff.log_uses_indirect_client
1288 Controls whether the indirect client address
1289 (see follow_x_forwarded_for) is used instead of the
1290 direct client address in the access log.
1293 NAME: tproxy_uses_indirect_client
1296 IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
1298 LOC: Config.onoff.tproxy_uses_indirect_client
1300 Controls whether the indirect client address
1301 (see follow_x_forwarded_for) is used instead of the
1302 direct client address when spoofing the outgoing client.
1304 This has no effect on requests arriving in non-tproxy
1307 SECURITY WARNING: Usage of this option is dangerous
1308 and should not be used trivially. Correct configuration
1309 of follow_x_forewarded_for with a limited set of trusted
1310 sources is required to prevent abuse of your proxy.
1313 NAME: spoof_client_ip
1315 LOC: Config.accessList.spoof_client_ip
1317 DEFAULT_DOC: Allow spoofing on all TPROXY traffic.
1319 Control client IP address spoofing of TPROXY traffic based on
1320 defined access lists.
1322 spoof_client_ip allow|deny [!]aclname ...
1324 If there are no "spoof_client_ip" lines present, the default
1325 is to "allow" spoofing of any suitable request.
1327 Note that the cache_peer "no-tproxy" option overrides this ACL.
1329 This clause supports fast acl types.
1330 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1335 LOC: Config.accessList.http
1336 DEFAULT_IF_NONE: deny all
1337 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1339 Allowing or Denying access based on defined access lists
1341 To allow or deny a message received on an HTTP, HTTPS, or FTP port:
1342 http_access allow|deny [!]aclname ...
1344 NOTE on default values:
1346 If there are no "access" lines present, the default is to deny
1349 If none of the "access" lines cause a match, the default is the
1350 opposite of the last line in the list. If the last line was
1351 deny, the default is allow. Conversely, if the last line
1352 is allow, the default will be deny. For these reasons, it is a
1353 good idea to have an "deny all" entry at the end of your access
1354 lists to avoid potential confusion.
1356 This clause supports both fast and slow acl types.
1357 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1362 # Recommended minimum Access Permission configuration:
1364 # Deny requests to certain unsafe ports
1365 http_access deny !Safe_ports
1367 # Deny CONNECT to other than secure SSL ports
1368 http_access deny CONNECT !SSL_ports
1370 # Only allow cachemgr access from localhost
1371 http_access allow localhost manager
1372 http_access deny manager
1374 # We strongly recommend the following be uncommented to protect innocent
1375 # web applications running on the proxy server who think the only
1376 # one who can access services on "localhost" is a local user
1377 #http_access deny to_localhost
1380 # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
1383 # Example rule allowing access from your local networks.
1384 # Adapt localnet in the ACL section to list your (internal) IP networks
1385 # from where browsing should be allowed
1386 http_access allow localnet
1387 http_access allow localhost
1389 # And finally deny all other access to this proxy
1390 http_access deny all
1394 NAME: adapted_http_access http_access2
1396 LOC: Config.accessList.adapted_http
1398 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1400 Allowing or Denying access based on defined access lists
1402 Essentially identical to http_access, but runs after redirectors
1403 and ICAP/eCAP adaptation. Allowing access control based on their
1406 If not set then only http_access is used.
1409 NAME: http_reply_access
1411 LOC: Config.accessList.reply
1413 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1415 Allow replies to client requests. This is complementary to http_access.
1417 http_reply_access allow|deny [!] aclname ...
1419 NOTE: if there are no access lines present, the default is to allow
1422 If none of the access lines cause a match the opposite of the
1423 last line will apply. Thus it is good practice to end the rules
1424 with an "allow all" or "deny all" entry.
1426 This clause supports both fast and slow acl types.
1427 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1432 LOC: Config.accessList.icp
1434 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1436 Allowing or Denying access to the ICP port based on defined
1439 icp_access allow|deny [!]aclname ...
1441 NOTE: The default if no icp_access lines are present is to
1442 deny all traffic. This default may cause problems with peers
1445 This clause only supports fast acl types.
1446 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1448 # Allow ICP queries from local networks only
1449 #icp_access allow localnet
1450 #icp_access deny all
1456 LOC: Config.accessList.htcp
1458 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1460 Allowing or Denying access to the HTCP port based on defined
1463 htcp_access allow|deny [!]aclname ...
1465 See also htcp_clr_access for details on access control for
1466 cache purge (CLR) HTCP messages.
1468 NOTE: The default if no htcp_access lines are present is to
1469 deny all traffic. This default may cause problems with peers
1470 using the htcp option.
1472 This clause only supports fast acl types.
1473 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1475 # Allow HTCP queries from local networks only
1476 #htcp_access allow localnet
1477 #htcp_access deny all
1480 NAME: htcp_clr_access
1483 LOC: Config.accessList.htcp_clr
1485 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1487 Allowing or Denying access to purge content using HTCP based
1488 on defined access lists.
1489 See htcp_access for details on general HTCP access control.
1491 htcp_clr_access allow|deny [!]aclname ...
1493 This clause only supports fast acl types.
1494 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1496 # Allow HTCP CLR requests from trusted peers
1497 acl htcp_clr_peer src 192.0.2.2 2001:DB8::2
1498 htcp_clr_access allow htcp_clr_peer
1499 htcp_clr_access deny all
1504 LOC: Config.accessList.miss
1506 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1508 Determins whether network access is permitted when satisfying a request.
1511 to force your neighbors to use you as a sibling instead of
1514 acl localclients src 192.0.2.0/24 2001:DB8::a:0/64
1515 miss_access deny !localclients
1516 miss_access allow all
1518 This means only your local clients are allowed to fetch relayed/MISS
1519 replies from the network and all other clients can only fetch cached
1522 The default for this setting allows all clients who passed the
1523 http_access rules to relay via this proxy.
1525 This clause only supports fast acl types.
1526 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1529 NAME: ident_lookup_access
1533 DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched.
1534 LOC: Ident::TheConfig.identLookup
1536 A list of ACL elements which, if matched, cause an ident
1537 (RFC 931) lookup to be performed for this request. For
1538 example, you might choose to always perform ident lookups
1539 for your main multi-user Unix boxes, but not for your Macs
1540 and PCs. By default, ident lookups are not performed for
1543 To enable ident lookups for specific client addresses, you
1544 can follow this example:
1546 acl ident_aware_hosts src 198.168.1.0/24
1547 ident_lookup_access allow ident_aware_hosts
1548 ident_lookup_access deny all
1550 Only src type ACL checks are fully supported. A srcdomain
1551 ACL might work at times, but it will not always provide
1554 This clause only supports fast acl types.
1555 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1558 NAME: reply_body_max_size
1559 COMMENT: size [acl acl...]
1562 DEFAULT_DOC: No limit is applied.
1563 LOC: Config.ReplyBodySize
1565 This option specifies the maximum size of a reply body. It can be
1566 used to prevent users from downloading very large files, such as
1567 MP3's and movies. When the reply headers are received, the
1568 reply_body_max_size lines are processed, and the first line where
1569 all (if any) listed ACLs are true is used as the maximum body size
1572 This size is checked twice. First when we get the reply headers,
1573 we check the content-length value. If the content length value exists
1574 and is larger than the allowed size, the request is denied and the
1575 user receives an error message that says "the request or reply
1576 is too large." If there is no content-length, and the reply
1577 size exceeds this limit, the client's connection is just closed
1578 and they will receive a partial reply.
1580 WARNING: downstream caches probably can not detect a partial reply
1581 if there is no content-length header, so they will cache
1582 partial responses and give them out as hits. You should NOT
1583 use this option if you have downstream caches.
1585 WARNING: A maximum size smaller than the size of squid's error messages
1586 will cause an infinite loop and crash squid. Ensure that the smallest
1587 non-zero value you use is greater that the maximum header size plus
1588 the size of your largest error page.
1590 If you set this parameter none (the default), there will be
1593 Configuration Format is:
1594 reply_body_max_size SIZE UNITS [acl ...]
1596 reply_body_max_size 10 MB
1602 -----------------------------------------------------------------------------
1605 NAME: http_port ascii_port
1610 Usage: port [mode] [options]
1611 hostname:port [mode] [options]
1612 1.2.3.4:port [mode] [options]
1614 The socket addresses where Squid will listen for HTTP client
1615 requests. You may specify multiple socket addresses.
1616 There are three forms: port alone, hostname with port, and
1617 IP address with port. If you specify a hostname or IP
1618 address, Squid binds the socket to that specific
1619 address. Most likely, you do not need to bind to a specific
1620 address, so you can use the port number alone.
1622 If you are running Squid in accelerator mode, you
1623 probably want to listen on port 80 also, or instead.
1625 The -a command line option may be used to specify additional
1626 port(s) where Squid listens for proxy request. Such ports will
1627 be plain proxy ports with no options.
1629 You may specify multiple socket addresses on multiple lines.
1633 intercept Support for IP-Layer interception of
1634 outgoing requests without browser settings.
1635 NP: disables authentication and IPv6 on the port.
1637 tproxy Support Linux TPROXY for spoofing outgoing
1638 connections using the client IP address.
1639 NP: disables authentication and maybe IPv6 on the port.
1641 accel Accelerator / reverse proxy mode
1643 ssl-bump For each CONNECT request allowed by ssl_bump ACLs,
1644 establish secure connection with the client and with
1645 the server, decrypt HTTPS messages as they pass through
1646 Squid, and treat them as unencrypted HTTP messages,
1647 becoming the man-in-the-middle.
1649 The ssl_bump option is required to fully enable
1650 bumping of CONNECT requests.
1652 Omitting the mode flag causes default forward proxy mode to be used.
1655 Accelerator Mode Options:
1657 defaultsite=domainname
1658 What to use for the Host: header if it is not present
1659 in a request. Determines what site (not origin server)
1660 accelerators should consider the default.
1662 no-vhost Disable using HTTP/1.1 Host header for virtual domain support.
1664 protocol= Protocol to reconstruct accelerated and intercepted
1665 requests with. Defaults to HTTP/1.1 for http_port and
1666 HTTPS/1.1 for https_port.
1667 When an unsupported value is configured Squid will
1668 produce a FATAL error.
1669 Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1
1671 vport Virtual host port support. Using the http_port number
1672 instead of the port passed on Host: headers.
1674 vport=NN Virtual host port support. Using the specified port
1675 number instead of the port passed on Host: headers.
1678 Act as if this Squid is the origin server.
1679 This currently means generate new Date: and Expires:
1680 headers on HIT instead of adding Age:.
1682 ignore-cc Ignore request Cache-Control headers.
1684 WARNING: This option violates HTTP specifications if
1685 used in non-accelerator setups.
1687 allow-direct Allow direct forwarding in accelerator mode. Normally
1688 accelerated requests are denied direct forwarding as if
1689 never_direct was used.
1691 WARNING: this option opens accelerator mode to security
1692 vulnerabilities usually only affecting in interception
1693 mode. Make sure to protect forwarding with suitable
1694 http_access rules when using this.
1697 SSL Bump Mode Options:
1698 In addition to these options ssl-bump requires TLS/SSL options.
1700 generate-host-certificates[=<on|off>]
1701 Dynamically create SSL server certificates for the
1702 destination hosts of bumped CONNECT requests.When
1703 enabled, the cert and key options are used to sign
1704 generated certificates. Otherwise generated
1705 certificate will be selfsigned.
1706 If there is a CA certificate lifetime of the generated
1707 certificate equals lifetime of the CA certificate. If
1708 generated certificate is selfsigned lifetime is three
1710 This option is enabled by default when ssl-bump is used.
1711 See the ssl-bump option above for more information.
1713 dynamic_cert_mem_cache_size=SIZE
1714 Approximate total RAM size spent on cached generated
1715 certificates. If set to zero, caching is disabled. The
1716 default value is 4MB.
1720 cert= Path to SSL certificate (PEM format).
1722 key= Path to SSL private key file (PEM format)
1723 if not specified, the certificate file is
1724 assumed to be a combined certificate and
1727 version= The version of SSL/TLS supported
1728 1 automatic (default)
1735 cipher= Colon separated list of supported ciphers.
1736 NOTE: some ciphers such as EDH ciphers depend on
1737 additional settings. If those settings are
1738 omitted the ciphers may be silently ignored
1739 by the OpenSSL library.
1741 options= Various SSL implementation options. The most important
1743 NO_SSLv2 Disallow the use of SSLv2
1744 NO_SSLv3 Disallow the use of SSLv3
1745 NO_TLSv1 Disallow the use of TLSv1.0
1746 NO_TLSv1_1 Disallow the use of TLSv1.1
1747 NO_TLSv1_2 Disallow the use of TLSv1.2
1748 SINGLE_DH_USE Always create a new key when using
1749 temporary/ephemeral DH key exchanges
1750 ALL Enable various bug workarounds
1751 suggested as "harmless" by OpenSSL
1752 Be warned that this reduces SSL/TLS
1753 strength to some attacks.
1754 See OpenSSL SSL_CTX_set_options documentation for a
1755 complete list of options.
1757 clientca= File containing the list of CAs to use when
1758 requesting a client certificate.
1760 cafile= File containing additional CA certificates to
1761 use when verifying client certificates. If unset
1762 clientca will be used.
1764 capath= Directory containing additional CA certificates
1765 and CRL lists to use when verifying client certificates.
1767 crlfile= File of additional CRL lists to use when verifying
1768 the client certificate, in addition to CRLs stored in
1769 the capath. Implies VERIFY_CRL flag below.
1771 dhparams= File containing DH parameters for temporary/ephemeral
1772 DH key exchanges. See OpenSSL documentation for details
1773 on how to create this file.
1774 WARNING: EDH ciphers will be silently disabled if this
1777 sslflags= Various flags modifying the use of SSL:
1779 Don't request client certificates
1780 immediately, but wait until acl processing
1781 requires a certificate (not yet implemented).
1783 Don't use the default CA lists built in
1786 Don't allow for session reuse. Each connection
1787 will result in a new SSL session.
1789 Verify CRL lists when accepting client
1792 Verify CRL lists for all certificates in the
1793 client certificate chain.
1795 sslcontext= SSL session ID context identifier.
1799 connection-auth[=on|off]
1800 use connection-auth=off to tell Squid to prevent
1801 forwarding Microsoft connection oriented authentication
1802 (NTLM, Negotiate and Kerberos)
1804 disable-pmtu-discovery=
1805 Control Path-MTU discovery usage:
1806 off lets OS decide on what to do (default).
1807 transparent disable PMTU discovery when transparent
1809 always disable always PMTU discovery.
1811 In many setups of transparently intercepting proxies
1812 Path-MTU discovery can not work on traffic towards the
1813 clients. This is the case when the intercepting device
1814 does not fully track connections and fails to forward
1815 ICMP must fragment messages to the cache server. If you
1816 have such setup and experience that certain clients
1817 sporadically hang or never complete requests set
1818 disable-pmtu-discovery option to 'transparent'.
1820 name= Specifies a internal name for the port. Defaults to
1821 the port specification (port or addr:port)
1823 tcpkeepalive[=idle,interval,timeout]
1824 Enable TCP keepalive probes of idle connections.
1825 In seconds; idle is the initial time before TCP starts
1826 probing the connection, interval how often to probe, and
1827 timeout the time before giving up.
1829 require-proxy-header
1830 Require PROXY protocol version 1 or 2 connections.
1831 The proxy_protocol_access is required to whitelist
1832 downstream proxies which can be trusted.
1834 If you run Squid on a dual-homed machine with an internal
1835 and an external interface we recommend you to specify the
1836 internal address:port in http_port. This way Squid will only be
1837 visible on the internal address.
1841 # Squid normally listens to port 3128
1842 http_port @DEFAULT_HTTP_PORT@
1852 Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...]
1854 The socket address where Squid will listen for client requests made
1855 over TLS or SSL connections. Commonly referred to as HTTPS.
1857 This is most useful for situations where you are running squid in
1858 accelerator mode and you want to do the SSL work at the accelerator level.
1860 You may specify multiple socket addresses on multiple lines,
1861 each with their own SSL certificate and/or options.
1865 accel Accelerator / reverse proxy mode
1867 intercept Support for IP-Layer interception of
1868 outgoing requests without browser settings.
1869 NP: disables authentication and IPv6 on the port.
1871 tproxy Support Linux TPROXY for spoofing outgoing
1872 connections using the client IP address.
1873 NP: disables authentication and maybe IPv6 on the port.
1875 ssl-bump For each intercepted connection allowed by ssl_bump
1876 ACLs, establish a secure connection with the client and with
1877 the server, decrypt HTTPS messages as they pass through
1878 Squid, and treat them as unencrypted HTTP messages,
1879 becoming the man-in-the-middle.
1881 An "ssl_bump server-first" match is required to
1882 fully enable bumping of intercepted SSL connections.
1884 Requires tproxy or intercept.
1886 Omitting the mode flag causes default forward proxy mode to be used.
1889 See http_port for a list of generic options
1894 cert= Path to SSL certificate (PEM format).
1896 key= Path to SSL private key file (PEM format)
1897 if not specified, the certificate file is
1898 assumed to be a combined certificate and
1901 version= The version of SSL/TLS supported
1902 1 automatic (default)
1907 cipher= Colon separated list of supported ciphers.
1909 options= Various SSL engine options. The most important
1911 NO_SSLv2 Disallow the use of SSLv2
1912 NO_SSLv3 Disallow the use of SSLv3
1913 NO_TLSv1 Disallow the use of TLSv1
1914 SINGLE_DH_USE Always create a new key when using
1915 temporary/ephemeral DH key exchanges
1916 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1917 documentation for a complete list of options.
1919 clientca= File containing the list of CAs to use when
1920 requesting a client certificate.
1922 cafile= File containing additional CA certificates to
1923 use when verifying client certificates. If unset
1924 clientca will be used.
1926 capath= Directory containing additional CA certificates
1927 and CRL lists to use when verifying client certificates.
1929 crlfile= File of additional CRL lists to use when verifying
1930 the client certificate, in addition to CRLs stored in
1931 the capath. Implies VERIFY_CRL flag below.
1933 dhparams= File containing DH parameters for temporary/ephemeral
1936 sslflags= Various flags modifying the use of SSL:
1938 Don't request client certificates
1939 immediately, but wait until acl processing
1940 requires a certificate (not yet implemented).
1942 Don't use the default CA lists built in
1945 Don't allow for session reuse. Each connection
1946 will result in a new SSL session.
1948 Verify CRL lists when accepting client
1951 Verify CRL lists for all certificates in the
1952 client certificate chain.
1954 sslcontext= SSL session ID context identifier.
1956 generate-host-certificates[=<on|off>]
1957 Dynamically create SSL server certificates for the
1958 destination hosts of bumped SSL requests.When
1959 enabled, the cert and key options are used to sign
1960 generated certificates. Otherwise generated
1961 certificate will be selfsigned.
1962 If there is CA certificate life time of generated
1963 certificate equals lifetime of CA certificate. If
1964 generated certificate is selfsigned lifetime is three
1966 This option is enabled by default when SslBump is used.
1967 See the sslBump option above for more information.
1969 dynamic_cert_mem_cache_size=SIZE
1970 Approximate total RAM size spent on cached generated
1971 certificates. If set to zero, caching is disabled. The
1972 default value is 4MB.
1974 See http_port for a list of available options.
1982 Enables Native FTP proxy by specifying the socket address where Squid
1983 listens for FTP client requests. See http_port directive for various
1984 ways to specify the listening address and mode.
1986 Usage: ftp_port address [mode] [options]
1988 WARNING: This is a new, experimental, complex feature that has seen
1989 limited production exposure. Some Squid modules (e.g., caching) do not
1990 currently work with native FTP proxying, and many features have not
1991 even been tested for compatibility. Test well before deploying!
1993 Native FTP proxying differs substantially from proxying HTTP requests
1994 with ftp:// URIs because Squid works as an FTP server and receives
1995 actual FTP commands (rather than HTTP requests with FTP URLs).
1997 Native FTP commands accepted at ftp_port are internally converted or
1998 wrapped into HTTP-like messages. The same happens to Native FTP
1999 responses received from FTP origin servers. Those HTTP-like messages
2000 are shoveled through regular access control and adaptation layers
2001 between the FTP client and the FTP origin server. This allows Squid to
2002 examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP
2003 mechanisms when shoveling wrapped FTP messages. For example,
2004 http_access and adaptation_access directives are used.
2008 intercept Same as http_port intercept. The FTP origin address is
2009 determined based on the intended destination of the
2010 intercepted connection.
2012 tproxy Support Linux TPROXY for spoofing outgoing
2013 connections using the client IP address.
2014 NP: disables authentication and maybe IPv6 on the port.
2016 By default (i.e., without an explicit mode option), Squid extracts the
2017 FTP origin address from the login@origin parameter of the FTP USER
2018 command. Many popular FTP clients support such native FTP proxying.
2022 name=token Specifies an internal name for the port. Defaults to
2023 the port address. Usable with myportname ACL.
2026 Enables tracking of FTP directories by injecting extra
2027 PWD commands and adjusting Request-URI (in wrapping
2028 HTTP requests) to reflect the current FTP server
2029 directory. Tracking is disabled by default.
2031 protocol=FTP Protocol to reconstruct accelerated and intercepted
2032 requests with. Defaults to FTP. No other accepted
2033 values have been tested with. An unsupported value
2034 results in a FATAL error. Accepted values are FTP,
2035 HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1).
2037 Other http_port modes and options that are not specific to HTTP and
2038 HTTPS may also work.
2041 NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
2044 LOC: Ip::Qos::TheConfig.tosToServer
2046 Allows you to select a TOS/Diffserv value for packets outgoing
2047 on the server side, based on an ACL.
2049 tcp_outgoing_tos ds-field [!]aclname ...
2051 Example where normal_service_net uses the TOS value 0x00
2052 and good_service_net uses 0x20
2054 acl normal_service_net src 10.0.0.0/24
2055 acl good_service_net src 10.0.1.0/24
2056 tcp_outgoing_tos 0x00 normal_service_net
2057 tcp_outgoing_tos 0x20 good_service_net
2059 TOS/DSCP values really only have local significance - so you should
2060 know what you're specifying. For more information, see RFC2474,
2061 RFC2475, and RFC3260.
2063 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
2064 "default" to use whatever default your host has. Note that in
2065 practice often only multiples of 4 is usable as the two rightmost bits
2066 have been redefined for use by ECN (RFC 3168 section 23.1).
2068 Processing proceeds in the order specified, and stops at first fully
2071 Only fast ACLs are supported.
2074 NAME: clientside_tos
2077 LOC: Ip::Qos::TheConfig.tosToClient
2079 Allows you to select a TOS/Diffserv value for packets being transmitted
2080 on the client-side, based on an ACL.
2082 clientside_tos ds-field [!]aclname ...
2084 Example where normal_service_net uses the TOS value 0x00
2085 and good_service_net uses 0x20
2087 acl normal_service_net src 10.0.0.0/24
2088 acl good_service_net src 10.0.1.0/24
2089 clientside_tos 0x00 normal_service_net
2090 clientside_tos 0x20 good_service_net
2092 Note: This feature is incompatible with qos_flows. Any TOS values set here
2093 will be overwritten by TOS values in qos_flows.
2096 NAME: tcp_outgoing_mark
2098 IFDEF: SO_MARK&&USE_LIBCAP
2100 LOC: Ip::Qos::TheConfig.nfmarkToServer
2102 Allows you to apply a Netfilter mark value to outgoing packets
2103 on the server side, based on an ACL.
2105 tcp_outgoing_mark mark-value [!]aclname ...
2107 Example where normal_service_net uses the mark value 0x00
2108 and good_service_net uses 0x20
2110 acl normal_service_net src 10.0.0.0/24
2111 acl good_service_net src 10.0.1.0/24
2112 tcp_outgoing_mark 0x00 normal_service_net
2113 tcp_outgoing_mark 0x20 good_service_net
2115 Only fast ACLs are supported.
2118 NAME: clientside_mark
2120 IFDEF: SO_MARK&&USE_LIBCAP
2122 LOC: Ip::Qos::TheConfig.nfmarkToClient
2124 Allows you to apply a Netfilter mark value to packets being transmitted
2125 on the client-side, based on an ACL.
2127 clientside_mark mark-value [!]aclname ...
2129 Example where normal_service_net uses the mark value 0x00
2130 and good_service_net uses 0x20
2132 acl normal_service_net src 10.0.0.0/24
2133 acl good_service_net src 10.0.1.0/24
2134 clientside_mark 0x00 normal_service_net
2135 clientside_mark 0x20 good_service_net
2137 Note: This feature is incompatible with qos_flows. Any mark values set here
2138 will be overwritten by mark values in qos_flows.
2145 LOC: Ip::Qos::TheConfig
2147 Allows you to select a TOS/DSCP value to mark outgoing
2148 connections to the client, based on where the reply was sourced.
2149 For platforms using netfilter, allows you to set a netfilter mark
2150 value instead of, or in addition to, a TOS value.
2152 By default this functionality is disabled. To enable it with the default
2153 settings simply use "qos_flows mark" or "qos_flows tos". Default
2154 settings will result in the netfilter mark or TOS value being copied
2155 from the upstream connection to the client. Note that it is the connection
2156 CONNMARK value not the packet MARK value that is copied.
2158 It is not currently possible to copy the mark or TOS value from the
2159 client to the upstream connection request.
2161 TOS values really only have local significance - so you should
2162 know what you're specifying. For more information, see RFC2474,
2163 RFC2475, and RFC3260.
2165 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
2166 in practice often only multiples of 4 is usable as the two rightmost bits
2167 have been redefined for use by ECN (RFC 3168 section 23.1).
2169 Mark values can be any unsigned 32-bit integer value.
2171 This setting is configured by setting the following values:
2173 tos|mark Whether to set TOS or netfilter mark values
2175 local-hit=0xFF Value to mark local cache hits.
2177 sibling-hit=0xFF Value to mark hits from sibling peers.
2179 parent-hit=0xFF Value to mark hits from parent peers.
2181 miss=0xFF[/mask] Value to mark cache misses. Takes precedence
2182 over the preserve-miss feature (see below), unless
2183 mask is specified, in which case only the bits
2184 specified in the mask are written.
2186 The TOS variant of the following features are only possible on Linux
2187 and require your kernel to be patched with the TOS preserving ZPH
2188 patch, available from http://zph.bratcheda.org
2189 No patch is needed to preserve the netfilter mark, which will work
2190 with all variants of netfilter.
2192 disable-preserve-miss
2193 This option disables the preservation of the TOS or netfilter
2194 mark. By default, the existing TOS or netfilter mark value of
2195 the response coming from the remote server will be retained
2196 and masked with miss-mark.
2197 NOTE: in the case of a netfilter mark, the mark must be set on
2198 the connection (using the CONNMARK target) not on the packet
2202 Allows you to mask certain bits in the TOS or mark value
2203 received from the remote server, before copying the value to
2204 the TOS sent towards clients.
2205 Default for tos: 0xFF (TOS from server is not changed).
2206 Default for mark: 0xFFFFFFFF (mark from server is not changed).
2208 All of these features require the --enable-zph-qos compilation flag
2209 (enabled by default). Netfilter marking also requires the
2210 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
2211 libcap 2.09+ (--with-libcap).
2215 NAME: tcp_outgoing_address
2218 DEFAULT_DOC: Address selection is performed by the operating system.
2219 LOC: Config.accessList.outgoing_address
2221 Allows you to map requests to different outgoing IP addresses
2222 based on the username or source address of the user making
2225 tcp_outgoing_address ipaddr [[!]aclname] ...
2228 Forwarding clients with dedicated IPs for certain subnets.
2230 acl normal_service_net src 10.0.0.0/24
2231 acl good_service_net src 10.0.2.0/24
2233 tcp_outgoing_address 2001:db8::c001 good_service_net
2234 tcp_outgoing_address 10.1.0.2 good_service_net
2236 tcp_outgoing_address 2001:db8::beef normal_service_net
2237 tcp_outgoing_address 10.1.0.1 normal_service_net
2239 tcp_outgoing_address 2001:db8::1
2240 tcp_outgoing_address 10.1.0.3
2242 Processing proceeds in the order specified, and stops at first fully
2245 Squid will add an implicit IP version test to each line.
2246 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.
2247 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.
2250 NOTE: The use of this directive using client dependent ACLs is
2251 incompatible with the use of server side persistent connections. To
2252 ensure correct results it is best to set server_persistent_connections
2253 to off when using this directive in such configurations.
2255 NOTE: The use of this directive to set a local IP on outgoing TCP links
2256 is incompatible with using TPROXY to set client IP out outbound TCP links.
2257 When needing to contact peers use the no-tproxy cache_peer option and the
2258 client_dst_passthru directive re-enable normal forwarding such as this.
2262 NAME: host_verify_strict
2265 LOC: Config.onoff.hostStrictVerify
2267 Regardless of this option setting, when dealing with intercepted
2268 traffic, Squid always verifies that the destination IP address matches
2269 the Host header domain or IP (called 'authority form URL').
2271 This enforcement is performed to satisfy a MUST-level requirement in
2272 RFC 2616 section 14.23: "The Host field value MUST represent the naming
2273 authority of the origin server or gateway given by the original URL".
2276 Squid always responds with an HTTP 409 (Conflict) error
2277 page and logs a security warning if there is no match.
2279 Squid verifies that the destination IP address matches
2280 the Host header for forward-proxy and reverse-proxy traffic
2281 as well. For those traffic types, Squid also enables the
2282 following checks, comparing the corresponding Host header
2283 and Request-URI components:
2285 * The host names (domain or IP) must be identical,
2286 but valueless or missing Host header disables all checks.
2287 For the two host names to match, both must be either IP
2290 * Port numbers must be identical, but if a port is missing
2291 the scheme-default port is assumed.
2294 When set to OFF (the default):
2295 Squid allows suspicious requests to continue but logs a
2296 security warning and blocks caching of the response.
2298 * Forward-proxy traffic is not checked at all.
2300 * Reverse-proxy traffic is not checked at all.
2302 * Intercepted traffic which passes verification is handled
2303 according to client_dst_passthru.
2305 * Intercepted requests which fail verification are sent
2306 to the client original destination instead of DIRECT.
2307 This overrides 'client_dst_passthru off'.
2309 For now suspicious intercepted CONNECT requests are always
2310 responded to with an HTTP 409 (Conflict) error page.
2315 As described in CVE-2009-0801 when the Host: header alone is used
2316 to determine the destination of a request it becomes trivial for
2317 malicious scripts on remote websites to bypass browser same-origin
2318 security policy and sandboxing protections.
2320 The cause of this is that such applets are allowed to perform their
2321 own HTTP stack, in which case the same-origin policy of the browser
2322 sandbox only verifies that the applet tries to contact the same IP
2323 as from where it was loaded at the IP level. The Host: header may
2324 be different from the connected IP and approved origin.
2328 NAME: client_dst_passthru
2331 LOC: Config.onoff.client_dst_passthru
2333 With NAT or TPROXY intercepted traffic Squid may pass the request
2334 directly to the original client destination IP or seek a faster
2335 source using the HTTP Host header.
2337 Using Host to locate alternative servers can provide faster
2338 connectivity with a range of failure recovery options.
2339 But can also lead to connectivity trouble when the client and
2340 server are attempting stateful interactions unaware of the proxy.
2342 This option (on by default) prevents alternative DNS entries being
2343 located to send intercepted traffic DIRECT to an origin server.
2344 The clients original destination IP and port will be used instead.
2346 Regardless of this option setting, when dealing with intercepted
2347 traffic Squid will verify the Host: header and any traffic which
2348 fails Host verification will be treated as if this option were ON.
2350 see host_verify_strict for details on the verification process.
2355 -----------------------------------------------------------------------------
2358 NAME: ssl_unclean_shutdown
2362 LOC: Config.SSL.unclean_shutdown
2364 Some browsers (especially MSIE) bugs out on SSL shutdown
2371 LOC: Config.SSL.ssl_engine
2374 The OpenSSL engine to use. You will need to set this if you
2375 would like to use hardware SSL acceleration for example.
2378 NAME: sslproxy_client_certificate
2381 LOC: Config.ssl_client.cert
2384 Client SSL Certificate to use when proxying https:// URLs
2387 NAME: sslproxy_client_key
2390 LOC: Config.ssl_client.key
2393 Client SSL Key to use when proxying https:// URLs
2396 NAME: sslproxy_version
2399 DEFAULT_DOC: automatic SSL/TLS version negotiation
2400 LOC: Config.ssl_client.version
2403 SSL version level to use when proxying https:// URLs
2405 The versions of SSL/TLS supported:
2407 1 automatic (default)
2415 NAME: sslproxy_options
2418 LOC: Config.ssl_client.options
2421 SSL implementation options to use when proxying https:// URLs
2423 The most important being:
2425 NO_SSLv2 Disallow the use of SSLv2
2426 NO_SSLv3 Disallow the use of SSLv3
2427 NO_TLSv1 Disallow the use of TLSv1.0
2428 NO_TLSv1_1 Disallow the use of TLSv1.1
2429 NO_TLSv1_2 Disallow the use of TLSv1.2
2431 Always create a new key when using temporary/ephemeral
2434 Disable use of RFC5077 session tickets. Some servers
2435 may have problems understanding the TLS extension due
2436 to ambiguous specification in RFC4507.
2437 ALL Enable various bug workarounds suggested as "harmless"
2438 by OpenSSL. Be warned that this may reduce SSL/TLS
2439 strength to some attacks.
2441 See the OpenSSL SSL_CTX_set_options documentation for a
2442 complete list of possible options.
2445 NAME: sslproxy_cipher
2448 LOC: Config.ssl_client.cipher
2451 SSL cipher list to use when proxying https:// URLs
2453 Colon separated list of supported ciphers.
2456 NAME: sslproxy_cafile
2459 LOC: Config.ssl_client.cafile
2462 file containing CA certificates to use when verifying server
2463 certificates while proxying https:// URLs
2466 NAME: sslproxy_capath
2469 LOC: Config.ssl_client.capath
2472 directory containing CA certificates to use when verifying
2473 server certificates while proxying https:// URLs
2476 NAME: sslproxy_session_ttl
2479 LOC: Config.SSL.session_ttl
2482 Sets the timeout value for SSL sessions
2485 NAME: sslproxy_session_cache_size
2488 LOC: Config.SSL.sessionCacheSize
2491 Sets the cache size to use for ssl session
2496 TYPE: sslproxy_ssl_bump
2497 LOC: Config.accessList.ssl_bump
2498 DEFAULT_DOC: Does not bump unless rules are present in squid.conf
2501 This option is consulted when a CONNECT request is received on
2502 an http_port (or a new connection is intercepted at an
2503 https_port), provided that port was configured with an ssl-bump
2504 flag. The subsequent data on the connection is either treated as
2505 HTTPS and decrypted OR tunneled at TCP level without decryption,
2506 depending on the first bumping "mode" which ACLs match.
2508 ssl_bump <mode> [!]acl ...
2510 The following bumping modes are supported:
2513 Allow bumping of the connection. Establish a secure connection
2514 with the client first, then connect to the server. This old mode
2515 does not allow Squid to mimic server SSL certificate and does
2516 not work with intercepted SSL connections.
2519 Allow bumping of the connection. Establish a secure connection
2520 with the server first, then establish a secure connection with
2521 the client, using a mimicked server certificate. Works with both
2522 CONNECT requests and intercepted SSL connections.
2525 Become a TCP tunnel without decoding the connection.
2526 Works with both CONNECT requests and intercepted SSL
2527 connections. This is the default behavior when no
2528 ssl_bump option is given or no ssl_bump ACLs match.
2530 By default, no connections are bumped.
2532 The first matching ssl_bump option wins. If no ACLs match, the
2533 connection is not bumped. Unlike most allow/deny ACL lists, ssl_bump
2534 does not have an implicit "negate the last given option" rule. You
2535 must make that rule explicit if you convert old ssl_bump allow/deny
2536 rules that rely on such an implicit rule.
2538 This clause supports both fast and slow acl types.
2539 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2541 See also: http_port ssl-bump, https_port ssl-bump
2544 # Example: Bump all requests except those originating from
2545 # localhost or those going to example.com.
2547 acl broken_sites dstdomain .example.com
2548 ssl_bump none localhost
2549 ssl_bump none broken_sites
2550 ssl_bump server-first all
2553 NAME: sslproxy_flags
2556 LOC: Config.ssl_client.flags
2559 Various flags modifying the use of SSL while proxying https:// URLs:
2560 DONT_VERIFY_PEER Accept certificates that fail verification.
2561 For refined control, see sslproxy_cert_error.
2562 NO_DEFAULT_CA Don't use the default CA list built in
2566 NAME: sslproxy_cert_error
2569 DEFAULT_DOC: Server certificate errors terminate the transaction.
2570 LOC: Config.ssl_client.cert_error
2573 Use this ACL to bypass server certificate validation errors.
2575 For example, the following lines will bypass all validation errors
2576 when talking to servers for example.com. All other
2577 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
2579 acl BrokenButTrustedServers dstdomain example.com
2580 sslproxy_cert_error allow BrokenButTrustedServers
2581 sslproxy_cert_error deny all
2583 This clause only supports fast acl types.
2584 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2585 Using slow acl types may result in server crashes
2587 Without this option, all server certificate validation errors
2588 terminate the transaction to protect Squid and the client.
2590 SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed
2591 but should not happen unless your OpenSSL library is buggy.
2594 Bypassing validation errors is dangerous because an
2595 error usually implies that the server cannot be trusted
2596 and the connection may be insecure.
2598 See also: sslproxy_flags and DONT_VERIFY_PEER.
2601 NAME: sslproxy_cert_sign
2604 POSTSCRIPTUM: signUntrusted ssl::certUntrusted
2605 POSTSCRIPTUM: signSelf ssl::certSelfSigned
2606 POSTSCRIPTUM: signTrusted all
2607 TYPE: sslproxy_cert_sign
2608 LOC: Config.ssl_client.cert_sign
2611 sslproxy_cert_sign <signing algorithm> acl ...
2613 The following certificate signing algorithms are supported:
2616 Sign using the configured CA certificate which is usually
2617 placed in and trusted by end-user browsers. This is the
2618 default for trusted origin server certificates.
2621 Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error.
2622 This is the default for untrusted origin server certificates
2623 that are not self-signed (see ssl::certUntrusted).
2626 Sign using a self-signed certificate with the right CN to
2627 generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the
2628 browser. This is the default for self-signed origin server
2629 certificates (see ssl::certSelfSigned).
2631 This clause only supports fast acl types.
2633 When sslproxy_cert_sign acl(s) match, Squid uses the corresponding
2634 signing algorithm to generate the certificate and ignores all
2635 subsequent sslproxy_cert_sign options (the first match wins). If no
2636 acl(s) match, the default signing algorithm is determined by errors
2637 detected when obtaining and validating the origin server certificate.
2639 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2640 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2641 CONNECT request that carries a domain name. In all other cases (CONNECT
2642 to an IP address or an intercepted SSL connection), Squid cannot detect
2643 the domain mismatch at certificate generation time when
2644 bump-server-first is used.
2647 NAME: sslproxy_cert_adapt
2650 TYPE: sslproxy_cert_adapt
2651 LOC: Config.ssl_client.cert_adapt
2654 sslproxy_cert_adapt <adaptation algorithm> acl ...
2656 The following certificate adaptation algorithms are supported:
2659 Sets the "Not After" property to the "Not After" property of
2660 the CA certificate used to sign generated certificates.
2663 Sets the "Not Before" property to the "Not Before" property of
2664 the CA certificate used to sign generated certificates.
2666 setCommonName or setCommonName{CN}
2667 Sets Subject.CN property to the host name specified as a
2668 CN parameter or, if no explicit CN parameter was specified,
2669 extracted from the CONNECT request. It is a misconfiguration
2670 to use setCommonName without an explicit parameter for
2671 intercepted or tproxied SSL connections.
2673 This clause only supports fast acl types.
2675 Squid first groups sslproxy_cert_adapt options by adaptation algorithm.
2676 Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the
2677 corresponding adaptation algorithm to generate the certificate and
2678 ignores all subsequent sslproxy_cert_adapt options in that algorithm's
2679 group (i.e., the first match wins within each algorithm group). If no
2680 acl(s) match, the default mimicking action takes place.
2682 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2683 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2684 CONNECT request that carries a domain name. In all other cases (CONNECT
2685 to an IP address or an intercepted SSL connection), Squid cannot detect
2686 the domain mismatch at certificate generation time when
2687 bump-server-first is used.
2690 NAME: sslpassword_program
2693 LOC: Config.Program.ssl_password
2696 Specify a program used for entering SSL key passphrases
2697 when using encrypted SSL certificate keys. If not specified
2698 keys must either be unencrypted, or Squid started with the -N
2699 option to allow it to query interactively for the passphrase.
2701 The key file name is given as argument to the program allowing
2702 selection of the right password if you have multiple encrypted
2707 OPTIONS RELATING TO EXTERNAL SSL_CRTD
2708 -----------------------------------------------------------------------------
2711 NAME: sslcrtd_program
2714 DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
2715 LOC: Ssl::TheConfig.ssl_crtd
2717 Specify the location and options of the executable for ssl_crtd process.
2718 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
2719 For more information use:
2720 @DEFAULT_SSL_CRTD@ -h
2723 NAME: sslcrtd_children
2724 TYPE: HelperChildConfig
2726 DEFAULT: 32 startup=5 idle=1
2727 LOC: Ssl::TheConfig.ssl_crtdChildren
2729 The maximum number of processes spawn to service ssl server.
2730 The maximum this may be safely set to is 32.
2732 The startup= and idle= options allow some measure of skew in your
2737 Sets the minimum number of processes to spawn when Squid
2738 starts or reconfigures. When set to zero the first request will
2739 cause spawning of the first child process to handle it.
2741 Starting too few children temporary slows Squid under load while it
2742 tries to spawn enough additional processes to cope with traffic.
2746 Sets a minimum of how many processes Squid is to try and keep available
2747 at all times. When traffic begins to rise above what the existing
2748 processes can handle this many more will be spawned up to the maximum
2749 configured. A minimum setting of 1 is required.
2751 You must have at least one ssl_crtd process.
2754 NAME: sslcrtvalidator_program
2758 LOC: Ssl::TheConfig.ssl_crt_validator
2760 Specify the location and options of the executable for ssl_crt_validator
2763 Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ...
2766 ttl=n TTL in seconds for cached results. The default is 60 secs
2767 cache=n limit the result cache size. The default value is 2048
2770 NAME: sslcrtvalidator_children
2771 TYPE: HelperChildConfig
2773 DEFAULT: 32 startup=5 idle=1 concurrency=1
2774 LOC: Ssl::TheConfig.ssl_crt_validator_Children
2776 The maximum number of processes spawn to service SSL server.
2777 The maximum this may be safely set to is 32.
2779 The startup= and idle= options allow some measure of skew in your
2784 Sets the minimum number of processes to spawn when Squid
2785 starts or reconfigures. When set to zero the first request will
2786 cause spawning of the first child process to handle it.
2788 Starting too few children temporary slows Squid under load while it
2789 tries to spawn enough additional processes to cope with traffic.
2793 Sets a minimum of how many processes Squid is to try and keep available
2794 at all times. When traffic begins to rise above what the existing
2795 processes can handle this many more will be spawned up to the maximum
2796 configured. A minimum setting of 1 is required.
2800 The number of requests each certificate validator helper can handle in
2801 parallel. A value of 0 indicates the certficate validator does not
2802 support concurrency. Defaults to 1.
2804 When this directive is set to a value >= 1 then the protocol
2805 used to communicate with the helper is modified to include
2806 a request ID in front of the request/response. The request
2807 ID from the request must be echoed back with the response
2810 You must have at least one ssl_crt_validator process.
2814 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
2815 -----------------------------------------------------------------------------
2823 To specify other caches in a hierarchy, use the format:
2825 cache_peer hostname type http-port icp-port [options]
2830 # hostname type port port options
2831 # -------------------- -------- ----- ----- -----------
2832 cache_peer parent.foo.net parent 3128 3130 default
2833 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
2834 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
2835 cache_peer example.com parent 80 0 default
2836 cache_peer cdn.example.com sibling 3128 0
2838 type: either 'parent', 'sibling', or 'multicast'.
2840 proxy-port: The port number where the peer accept HTTP requests.
2841 For other Squid proxies this is usually 3128
2842 For web servers this is usually 80
2844 icp-port: Used for querying neighbor caches about objects.
2845 Set to 0 if the peer does not support ICP or HTCP.
2846 See ICP and HTCP options below for additional details.
2849 ==== ICP OPTIONS ====
2851 You MUST also set icp_port and icp_access explicitly when using these options.
2852 The defaults will prevent peer traffic using ICP.
2855 no-query Disable ICP queries to this neighbor.
2858 Indicates the named peer is a member of a multicast group.
2859 ICP queries will not be sent directly to the peer, but ICP
2860 replies will be accepted from it.
2862 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
2863 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
2866 To only send ICP queries to this neighbor infrequently.
2867 This is used to keep the neighbor round trip time updated
2868 and is usually used in conjunction with weighted-round-robin.
2871 ==== HTCP OPTIONS ====
2873 You MUST also set htcp_port and htcp_access explicitly when using these options.
2874 The defaults will prevent peer traffic using HTCP.
2877 htcp Send HTCP, instead of ICP, queries to the neighbor.
2878 You probably also want to set the "icp-port" to 4827
2879 instead of 3130. This directive accepts a comma separated
2880 list of options described below.
2882 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
2884 htcp=no-clr Send HTCP to the neighbor but without
2885 sending any CLR requests. This cannot be used with
2888 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
2889 This cannot be used with no-clr.
2892 Send HTCP to the neighbor including CLRs but only when
2893 they do not result from PURGE requests.
2896 Forward any HTCP CLR requests this proxy receives to the peer.
2899 ==== PEER SELECTION METHODS ====
2901 The default peer selection method is ICP, with the first responding peer
2902 being used as source. These options can be used for better load balancing.
2905 default This is a parent cache which can be used as a "last-resort"
2906 if a peer cannot be located by any of the peer-selection methods.
2907 If specified more than once, only the first is used.
2909 round-robin Load-Balance parents which should be used in a round-robin
2910 fashion in the absence of any ICP queries.
2911 weight=N can be used to add bias.
2913 weighted-round-robin
2914 Load-Balance parents which should be used in a round-robin
2915 fashion with the frequency of each parent being based on the
2916 round trip time. Closer parents are used more often.
2917 Usually used for background-ping parents.
2918 weight=N can be used to add bias.
2920 carp Load-Balance parents which should be used as a CARP array.
2921 The requests will be distributed among the parents based on the
2922 CARP load balancing hash function based on their weight.
2924 userhash Load-balance parents based on the client proxy_auth or ident username.
2926 sourcehash Load-balance parents based on the client source IP.
2929 To be used only for cache peers of type "multicast".
2930 ALL members of this multicast group have "sibling"
2931 relationship with it, not "parent". This is to a multicast
2932 group when the requested object would be fetched only from
2933 a "parent" cache, anyway. It's useful, e.g., when
2934 configuring a pool of redundant Squid proxies, being
2935 members of the same multicast group.
2938 ==== PEER SELECTION OPTIONS ====
2940 weight=N use to affect the selection of a peer during any weighted
2941 peer-selection mechanisms.
2942 The weight must be an integer; default is 1,
2943 larger weights are favored more.
2944 This option does not affect parent selection if a peering
2945 protocol is not in use.
2947 basetime=N Specify a base amount to be subtracted from round trip
2949 It is subtracted before division by weight in calculating
2950 which parent to fectch from. If the rtt is less than the
2951 base time the rtt is set to a minimal value.
2953 ttl=N Specify a TTL to use when sending multicast ICP queries
2955 Only useful when sending to a multicast group.
2956 Because we don't accept ICP replies from random
2957 hosts, you must configure other group members as
2958 peers with the 'multicast-responder' option.
2960 no-delay To prevent access to this neighbor from influencing the
2963 digest-url=URL Tell Squid to fetch the cache digest (if digests are
2964 enabled) for this host from the specified URL rather
2965 than the Squid default location.
2968 ==== CARP OPTIONS ====
2970 carp-key=key-specification
2971 use a different key than the full URL to hash against the peer.
2972 the key-specification is a comma-separated list of the keywords
2973 scheme, host, port, path, params
2974 Order is not important.
2976 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
2978 originserver Causes this parent to be contacted as an origin server.
2979 Meant to be used in accelerator setups when the peer
2983 Set the Host header of requests forwarded to this peer.
2984 Useful in accelerator setups where the server (peer)
2985 expects a certain domain name but clients may request
2986 others. ie example.com or www.example.com
2988 no-digest Disable request of cache digests.
2991 Disables requesting ICMP RTT database (NetDB).
2994 ==== AUTHENTICATION OPTIONS ====
2997 If this is a personal/workgroup proxy and your parent
2998 requires proxy authentication.
3000 Note: The string can include URL escapes (i.e. %20 for
3001 spaces). This also means % must be written as %%.
3004 Send login details received from client to this peer.
3005 Both Proxy- and WWW-Authorization headers are passed
3006 without alteration to the peer.
3007 Authentication is not required by Squid for this to work.
3009 Note: This will pass any form of authentication but
3010 only Basic auth will work through a proxy unless the
3011 connection-auth options are also used.
3013 login=PASS Send login details received from client to this peer.
3014 Authentication is not required by this option.
3016 If there are no client-provided authentication headers
3017 to pass on, but username and password are available
3018 from an external ACL user= and password= result tags
3019 they may be sent instead.
3021 Note: To combine this with proxy_auth both proxies must
3022 share the same user database as HTTP only allows for
3023 a single login (one for proxy, one for origin server).
3024 Also be warned this will expose your users proxy
3025 password to the peer. USE WITH CAUTION
3028 Send the username to the upstream cache, but with a
3029 fixed password. This is meant to be used when the peer
3030 is in another administrative domain, but it is still
3031 needed to identify each user.
3032 The star can optionally be followed by some extra
3033 information which is added to the username. This can
3034 be used to identify this proxy to the peer, similar to
3035 the login=username:password option above.
3038 If this is a personal/workgroup proxy and your parent
3039 requires a secure proxy authentication.
3040 The first principal from the default keytab or defined by
3041 the environment variable KRB5_KTNAME will be used.
3043 WARNING: The connection may transmit requests from multiple
3044 clients. Negotiate often assumes end-to-end authentication
3045 and a single-client. Which is not strictly true here.
3047 login=NEGOTIATE:principal_name
3048 If this is a personal/workgroup proxy and your parent
3049 requires a secure proxy authentication.
3050 The principal principal_name from the default keytab or
3051 defined by the environment variable KRB5_KTNAME will be
3054 WARNING: The connection may transmit requests from multiple
3055 clients. Negotiate often assumes end-to-end authentication
3056 and a single-client. Which is not strictly true here.
3058 connection-auth=on|off
3059 Tell Squid that this peer does or not support Microsoft
3060 connection oriented authentication, and any such
3061 challenges received from there should be ignored.
3062 Default is auto to automatically determine the status
3066 ==== SSL / HTTPS / TLS OPTIONS ====
3068 ssl Encrypt connections to this peer with SSL/TLS.
3070 sslcert=/path/to/ssl/certificate
3071 A client SSL certificate to use when connecting to
3074 sslkey=/path/to/ssl/key
3075 The private SSL key corresponding to sslcert above.
3076 If 'sslkey' is not specified 'sslcert' is assumed to
3077 reference a combined file containing both the
3078 certificate and the key.
3080 sslversion=1|2|3|4|5|6
3081 The SSL version to use when connecting to this peer
3082 1 = automatic (default)
3089 sslcipher=... The list of valid SSL ciphers to use when connecting
3092 ssloptions=... Specify various SSL implementation options:
3094 NO_SSLv2 Disallow the use of SSLv2
3095 NO_SSLv3 Disallow the use of SSLv3
3096 NO_TLSv1 Disallow the use of TLSv1.0
3097 NO_TLSv1_1 Disallow the use of TLSv1.1
3098 NO_TLSv1_2 Disallow the use of TLSv1.2
3100 Always create a new key when using
3101 temporary/ephemeral DH key exchanges
3102 ALL Enable various bug workarounds
3103 suggested as "harmless" by OpenSSL
3104 Be warned that this reduces SSL/TLS
3105 strength to some attacks.
3107 See the OpenSSL SSL_CTX_set_options documentation for a
3110 sslcafile=... A file containing additional CA certificates to use
3111 when verifying the peer certificate.
3113 sslcapath=... A directory containing additional CA certificates to
3114 use when verifying the peer certificate.
3116 sslcrlfile=... A certificate revocation list file to use when
3117 verifying the peer certificate.
3119 sslflags=... Specify various flags modifying the SSL implementation:
3122 Accept certificates even if they fail to
3125 Don't use the default CA list built in
3128 Don't verify the peer certificate
3129 matches the server name
3131 ssldomain= The peer name as advertised in it's certificate.
3132 Used for verifying the correctness of the received peer
3133 certificate. If not specified the peer hostname will be
3137 Enable the "Front-End-Https: On" header needed when
3138 using Squid as a SSL frontend in front of Microsoft OWA.
3139 See MS KB document Q307347 for details on this header.
3140 If set to auto the header will only be added if the
3141 request is forwarded as a https:// URL.
3144 ==== GENERAL OPTIONS ====
3147 A peer-specific connect timeout.
3148 Also see the peer_connect_timeout directive.
3150 connect-fail-limit=N
3151 How many times connecting to a peer must fail before
3152 it is marked as down. Standby connection failures
3153 count towards this limit. Default is 10.
3155 allow-miss Disable Squid's use of only-if-cached when forwarding
3156 requests to siblings. This is primarily useful when
3157 icp_hit_stale is used by the sibling. To extensive use
3158 of this option may result in forwarding loops, and you
3159 should avoid having two-way peerings with this option.
3160 For example to deny peer usage on requests from peer
3161 by denying cache_peer_access if the source is a peer.
3163 max-conn=N Limit the number of concurrent connections the Squid
3164 may open to this peer, including already opened idle
3165 and standby connections. There is no peer-specific
3166 connection limit by default.
3168 A peer exceeding the limit is not used for new
3169 requests unless a standby connection is available.
3171 max-conn currently works poorly with idle persistent
3172 connections: When a peer reaches its max-conn limit,
3173 and there are idle persistent connections to the peer,
3174 the peer may not be selected because the limiting code
3175 does not know whether Squid can reuse those idle
3178 standby=N Maintain a pool of N "hot standby" connections to an
3179 UP peer, available for requests when no idle
3180 persistent connection is available (or safe) to use.
3181 By default and with zero N, no such pool is maintained.
3182 N must not exceed the max-conn limit (if any).
3184 At start or after reconfiguration, Squid opens new TCP
3185 standby connections until there are N connections
3186 available and then replenishes the standby pool as
3187 opened connections are used up for requests. A used
3188 connection never goes back to the standby pool, but
3189 may go to the regular idle persistent connection pool
3190 shared by all peers and origin servers.
3192 Squid never opens multiple new standby connections
3193 concurrently. This one-at-a-time approach minimizes
3194 flooding-like effect on peers. Furthermore, just a few
3195 standby connections should be sufficient in most cases
3196 to supply most new requests with a ready-to-use
3199 Standby connections obey server_idle_pconn_timeout.
3200 For the feature to work as intended, the peer must be
3201 configured to accept and keep them open longer than
3202 the idle timeout at the connecting Squid, to minimize
3203 race conditions typical to idle used persistent
3204 connections. Default request_timeout and
3205 server_idle_pconn_timeout values ensure such a
3208 name=xxx Unique name for the peer.
3209 Required if you have multiple peers on the same host
3210 but different ports.
3211 This name can be used in cache_peer_access and similar
3212 directives to dentify the peer.
3213 Can be used by outgoing access controls through the
3216 no-tproxy Do not use the client-spoof TPROXY support when forwarding
3217 requests to this peer. Use normal address selection instead.
3218 This overrides the spoof_client_ip ACL.
3220 proxy-only objects fetched from the peer will not be stored locally.
3224 NAME: cache_peer_domain cache_host_domain
3229 Use to limit the domains for which a neighbor cache will be
3233 cache_peer_domain cache-host domain [domain ...]
3234 cache_peer_domain cache-host !domain
3236 For example, specifying
3238 cache_peer_domain parent.foo.net .edu
3240 has the effect such that UDP query packets are sent to
3241 'bigserver' only when the requested object exists on a
3242 server in the .edu domain. Prefixing the domainname
3243 with '!' means the cache will be queried for objects
3246 NOTE: * Any number of domains may be given for a cache-host,
3247 either on the same or separate lines.
3248 * When multiple domains are given for a particular
3249 cache-host, the first matched domain is applied.
3250 * Cache hosts with no domain restrictions are queried
3252 * There are no defaults.
3253 * There is also a 'cache_peer_access' tag in the ACL
3257 NAME: cache_peer_access
3262 Similar to 'cache_peer_domain' but provides more flexibility by
3266 cache_peer_access cache-host allow|deny [!]aclname ...
3268 The syntax is identical to 'http_access' and the other lists of
3269 ACL elements. See the comments for 'http_access' below, or
3270 the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
3273 NAME: neighbor_type_domain
3274 TYPE: hostdomaintype
3276 DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer.
3279 Modify the cache_peer neighbor type when passing requests
3280 about specific domains to the peer.
3283 neighbor_type_domain neighbor parent|sibling domain domain ...
3286 cache_peer foo.example.com parent 3128 3130
3287 neighbor_type_domain foo.example.com sibling .au .de
3289 The above configuration treats all requests to foo.example.com as a
3290 parent proxy unless the request is for a .au or .de ccTLD domain name.
3293 NAME: dead_peer_timeout
3297 LOC: Config.Timeout.deadPeer
3299 This controls how long Squid waits to declare a peer cache
3300 as "dead." If there are no ICP replies received in this
3301 amount of time, Squid will declare the peer dead and not
3302 expect to receive any further ICP replies. However, it
3303 continues to send ICP queries, and will mark the peer as
3304 alive upon receipt of the first subsequent ICP reply.
3306 This timeout also affects when Squid expects to receive ICP
3307 replies from peers. If more than 'dead_peer' seconds have
3308 passed since the last ICP reply was received, Squid will not
3309 expect to receive an ICP reply on the next query. Thus, if
3310 your time between requests is greater than this timeout, you
3311 will see a lot of requests sent DIRECT to origin servers
3312 instead of to your parents.
3315 NAME: forward_max_tries
3318 LOC: Config.forward_max_tries
3320 Controls how many different forward paths Squid will try
3321 before giving up. See also forward_timeout.
3323 NOTE: connect_retries (default: none) can make each of these
3324 possible forwarding paths be tried multiple times.
3328 MEMORY CACHE OPTIONS
3329 -----------------------------------------------------------------------------
3336 LOC: Config.memMaxSize
3338 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
3339 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
3340 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
3341 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
3343 'cache_mem' specifies the ideal amount of memory to be used
3345 * In-Transit objects
3347 * Negative-Cached objects
3349 Data for these objects are stored in 4 KB blocks. This
3350 parameter specifies the ideal upper limit on the total size of
3351 4 KB blocks allocated. In-Transit objects take the highest
3354 In-transit objects have priority over the others. When
3355 additional space is needed for incoming data, negative-cached
3356 and hot objects will be released. In other words, the
3357 negative-cached and hot objects will fill up any unused space
3358 not needed for in-transit objects.
3360 If circumstances require, this limit will be exceeded.
3361 Specifically, if your incoming request rate requires more than
3362 'cache_mem' of memory to hold in-transit objects, Squid will
3363 exceed this limit to satisfy the new requests. When the load
3364 decreases, blocks will be freed until the high-water mark is
3365 reached. Thereafter, blocks will be used to store hot
3368 If shared memory caching is enabled, Squid does not use the shared
3369 cache space for in-transit objects, but they still consume as much
3370 local memory as they need. For more details about the shared memory
3371 cache, see memory_cache_shared.
3374 NAME: maximum_object_size_in_memory
3378 LOC: Config.Store.maxInMemObjSize
3380 Objects greater than this size will not be attempted to kept in
3381 the memory cache. This should be set high enough to keep objects
3382 accessed frequently in memory to improve performance whilst low
3383 enough to keep larger objects from hoarding cache_mem.
3386 NAME: memory_cache_shared
3389 LOC: Config.memShared
3391 DEFAULT_DOC: "on" where supported if doing memory caching with multiple SMP workers.
3393 Controls whether the memory cache is shared among SMP workers.
3395 The shared memory cache is meant to occupy cache_mem bytes and replace
3396 the non-shared memory cache, although some entities may still be
3397 cached locally by workers for now (e.g., internal and in-transit
3398 objects may be served from a local memory cache even if shared memory
3399 caching is enabled).
3401 By default, the memory cache is shared if and only if all of the
3402 following conditions are satisfied: Squid runs in SMP mode with
3403 multiple workers, cache_mem is positive, and Squid environment
3404 supports required IPC primitives (e.g., POSIX shared memory segments
3405 and GCC-style atomic operations).
3407 To avoid blocking locks, shared memory uses opportunistic algorithms
3408 that do not guarantee that every cachable entity that could have been
3409 shared among SMP workers will actually be shared.
3411 Currently, entities exceeding 32KB in size cannot be shared.
3414 NAME: memory_cache_mode
3418 DEFAULT_DOC: Keep the most recently fetched objects in memory
3420 Controls which objects to keep in the memory cache (cache_mem)
3422 always Keep most recently fetched objects in memory (default)
3424 disk Only disk cache hits are kept in memory, which means
3425 an object must first be cached on disk and then hit
3426 a second time before cached in memory.
3428 network Only objects fetched from network is kept in memory
3431 NAME: memory_replacement_policy
3433 LOC: Config.memPolicy
3436 The memory replacement policy parameter determines which
3437 objects are purged from memory when memory space is needed.
3439 See cache_replacement_policy for details on algorithms.
3444 -----------------------------------------------------------------------------
3447 NAME: cache_replacement_policy
3449 LOC: Config.replPolicy
3452 The cache replacement policy parameter determines which
3453 objects are evicted (replaced) when disk space is needed.
3455 lru : Squid's original list based LRU policy
3456 heap GDSF : Greedy-Dual Size Frequency
3457 heap LFUDA: Least Frequently Used with Dynamic Aging
3458 heap LRU : LRU policy implemented using a heap
3460 Applies to any cache_dir lines listed below this directive.
3462 The LRU policies keeps recently referenced objects.
3464 The heap GDSF policy optimizes object hit rate by keeping smaller
3465 popular objects in cache so it has a better chance of getting a
3466 hit. It achieves a lower byte hit rate than LFUDA though since
3467 it evicts larger (possibly popular) objects.
3469 The heap LFUDA policy keeps popular objects in cache regardless of
3470 their size and thus optimizes byte hit rate at the expense of
3471 hit rate since one large, popular object will prevent many
3472 smaller, slightly less popular objects from being cached.
3474 Both policies utilize a dynamic aging mechanism that prevents
3475 cache pollution that can otherwise occur with frequency-based
3476 replacement policies.
3478 NOTE: if using the LFUDA replacement policy you should increase
3479 the value of maximum_object_size above its default of 4 MB to
3480 to maximize the potential byte hit rate improvement of LFUDA.
3482 For more information about the GDSF and LFUDA cache replacement
3483 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
3484 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
3487 NAME: minimum_object_size
3491 DEFAULT_DOC: no limit
3492 LOC: Config.Store.minObjectSize
3494 Objects smaller than this size will NOT be saved on disk. The
3495 value is specified in bytes, and the default is 0 KB, which
3496 means all responses can be stored.
3499 NAME: maximum_object_size
3503 LOC: Config.Store.maxObjectSize
3505 Set the default value for max-size parameter on any cache_dir.
3506 The value is specified in bytes, and the default is 4 MB.
3508 If you wish to get a high BYTES hit ratio, you should probably
3509 increase this (one 32 MB object hit counts for 3200 10KB
3512 If you wish to increase hit ratio more than you want to
3513 save bandwidth you should leave this low.
3515 NOTE: if using the LFUDA replacement policy you should increase
3516 this value to maximize the byte hit rate improvement of LFUDA!
3517 See cache_replacement_policy for a discussion of this policy.
3523 DEFAULT_DOC: No disk cache. Store cache ojects only in memory.
3524 LOC: Config.cacheSwap
3527 cache_dir Type Directory-Name Fs-specific-data [options]
3529 You can specify multiple cache_dir lines to spread the
3530 cache among different disk partitions.
3532 Type specifies the kind of storage system to use. Only "ufs"
3533 is built by default. To enable any of the other storage systems
3534 see the --enable-storeio configure option.
3536 'Directory' is a top-level directory where cache swap
3537 files will be stored. If you want to use an entire disk
3538 for caching, this can be the mount-point directory.
3539 The directory must exist and be writable by the Squid
3540 process. Squid will NOT create this directory for you.
3542 In SMP configurations, cache_dir must not precede the workers option
3543 and should use configuration macros or conditionals to give each
3544 worker interested in disk caching a dedicated cache directory.
3547 ==== The ufs store type ====
3549 "ufs" is the old well-known Squid storage format that has always
3553 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
3555 'Mbytes' is the amount of disk space (MB) to use under this
3556 directory. The default is 100 MB. Change this to suit your
3557 configuration. Do NOT put the size of your disk drive here.
3558 Instead, if you want Squid to use the entire disk drive,
3559 subtract 20% and use that value.
3561 'L1' is the number of first-level subdirectories which
3562 will be created under the 'Directory'. The default is 16.
3564 'L2' is the number of second-level subdirectories which
3565 will be created under each first-level directory. The default
3569 ==== The aufs store type ====
3571 "aufs" uses the same storage format as "ufs", utilizing
3572 POSIX-threads to avoid blocking the main Squid process on
3573 disk-I/O. This was formerly known in Squid as async-io.
3576 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
3578 see argument descriptions under ufs above
3581 ==== The diskd store type ====
3583 "diskd" uses the same storage format as "ufs", utilizing a
3584 separate process to avoid blocking the main Squid process on
3588 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
3590 see argument descriptions under ufs above
3592 Q1 specifies the number of unacknowledged I/O requests when Squid
3593 stops opening new files. If this many messages are in the queues,
3594 Squid won't open new files. Default is 64
3596 Q2 specifies the number of unacknowledged messages when Squid
3597 starts blocking. If this many messages are in the queues,
3598 Squid blocks until it receives some replies. Default is 72
3600 When Q1 < Q2 (the default), the cache directory is optimized
3601 for lower response time at the expense of a decrease in hit
3602 ratio. If Q1 > Q2, the cache directory is optimized for
3603 higher hit ratio at the expense of an increase in response
3607 ==== The rock store type ====
3610 cache_dir rock Directory-Name Mbytes [options]
3612 The Rock Store type is a database-style storage. All cached
3613 entries are stored in a "database" file, using fixed-size slots.
3614 A single entry occupies one or more slots.
3616 If possible, Squid using Rock Store creates a dedicated kid
3617 process called "disker" to avoid blocking Squid worker(s) on disk
3618 I/O. One disker kid is created for each rock cache_dir. Diskers
3619 are created only when Squid, running in daemon mode, has support
3620 for the IpcIo disk I/O module.
3622 swap-timeout=msec: Squid will not start writing a miss to or
3623 reading a hit from disk if it estimates that the swap operation
3624 will take more than the specified number of milliseconds. By
3625 default and when set to zero, disables the disk I/O time limit
3626 enforcement. Ignored when using blocking I/O module because
3627 blocking synchronous I/O does not allow Squid to estimate the
3628 expected swap wait time.
3630 max-swap-rate=swaps/sec: Artificially limits disk access using
3631 the specified I/O rate limit. Swap out requests that
3632 would cause the average I/O rate to exceed the limit are
3633 delayed. Individual swap in requests (i.e., hits or reads) are
3634 not delayed, but they do contribute to measured swap rate and
3635 since they are placed in the same FIFO queue as swap out
3636 requests, they may wait longer if max-swap-rate is smaller.
3637 This is necessary on file systems that buffer "too
3638 many" writes and then start blocking Squid and other processes
3639 while committing those writes to disk. Usually used together
3640 with swap-timeout to avoid excessive delays and queue overflows
3641 when disk demand exceeds available disk "bandwidth". By default
3642 and when set to zero, disables the disk I/O rate limit
3643 enforcement. Currently supported by IpcIo module only.
3645 slot-size=bytes: The size of a database "record" used for
3646 storing cached responses. A cached response occupies at least
3647 one slot and all database I/O is done using individual slots so
3648 increasing this parameter leads to more disk space waste while
3649 decreasing it leads to more disk I/O overheads. Should be a
3650 multiple of your operating system I/O page size. Defaults to
3651 16KBytes. A housekeeping header is stored with each slot and
3652 smaller slot-sizes will be rejected. The header is smaller than
3656 ==== COMMON OPTIONS ====
3658 no-store no new objects should be stored to this cache_dir.
3660 min-size=n the minimum object size in bytes this cache_dir
3661 will accept. It's used to restrict a cache_dir
3662 to only store large objects (e.g. AUFS) while
3663 other stores are optimized for smaller objects
3667 max-size=n the maximum object size in bytes this cache_dir
3669 The value in maximum_object_size directive sets
3670 the default unless more specific details are
3671 available (ie a small store capacity).
3673 Note: To make optimal use of the max-size limits you should order
3674 the cache_dir lines with the smallest max-size value first.
3678 # Uncomment and adjust the following to add a disk cache directory.
3679 #cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
3683 NAME: store_dir_select_algorithm
3685 LOC: Config.store_dir_select_algorithm
3688 How Squid selects which cache_dir to use when the response
3689 object will fit into more than one.
3691 Regardless of which algorithm is used the cache_dir min-size
3692 and max-size parameters are obeyed. As such they can affect
3693 the selection algorithm by limiting the set of considered
3700 This algorithm is suited to caches with similar cache_dir
3701 sizes and disk speeds.
3703 The disk with the least I/O pending is selected.
3704 When there are multiple disks with the same I/O load ranking
3705 the cache_dir with most available capacity is selected.
3707 When a mix of cache_dir sizes are configured the faster disks
3708 have a naturally lower I/O loading and larger disks have more
3709 capacity. So space used to store objects and data throughput
3710 may be very unbalanced towards larger disks.
3715 This algorithm is suited to caches with unequal cache_dir
3718 Each cache_dir is selected in a rotation. The next suitable
3721 Available cache_dir capacity is only considered in relation
3722 to whether the object will fit and meets the min-size and
3723 max-size parameters.
3725 Disk I/O loading is only considered to prevent overload on slow
3726 disks. This algorithm does not spread objects by size, so any
3727 I/O loading per-disk may appear very unbalanced and volatile.
3729 If several cache_dirs use similar min-size, max-size, or other
3730 limits to to reject certain responses, then do not group such
3731 cache_dir lines together, to avoid round-robin selection bias
3732 towards the first cache_dir after the group. Instead, interleave
3733 cache_dir lines from different groups. For example:
3735 store_dir_select_algorithm round-robin
3736 cache_dir rock /hdd1 ... min-size=100000
3737 cache_dir rock /ssd1 ... max-size=99999
3738 cache_dir rock /hdd2 ... min-size=100000
3739 cache_dir rock /ssd2 ... max-size=99999
3740 cache_dir rock /hdd3 ... min-size=100000
3741 cache_dir rock /ssd3 ... max-size=99999
3744 NAME: max_open_disk_fds
3746 LOC: Config.max_open_disk_fds
3748 DEFAULT_DOC: no limit
3750 To avoid having disk as the I/O bottleneck Squid can optionally
3751 bypass the on-disk cache if more than this amount of disk file
3752 descriptors are open.
3754 A value of 0 indicates no limit.
3757 NAME: cache_swap_low
3758 COMMENT: (percent, 0-100)
3761 LOC: Config.Swap.lowWaterMark
3763 The low-water mark for cache object replacement.
3764 Replacement begins when the swap (disk) usage is above the
3765 low-water mark and attempts to maintain utilization near the
3766 low-water mark. As swap utilization gets close to high-water
3767 mark object eviction becomes more aggressive. If utilization is
3768 close to the low-water mark less replacement is done each time.
3770 Defaults are 90% and 95%. If you have a large cache, 5% could be
3771 hundreds of MB. If this is the case you may wish to set these
3772 numbers closer together.
3774 See also cache_swap_high
3777 NAME: cache_swap_high
3778 COMMENT: (percent, 0-100)
3781 LOC: Config.Swap.highWaterMark
3783 The high-water mark for cache object replacement.
3784 Replacement begins when the swap (disk) usage is above the
3785 low-water mark and attempts to maintain utilization near the
3786 low-water mark. As swap utilization gets close to high-water
3787 mark object eviction becomes more aggressive. If utilization is
3788 close to the low-water mark less replacement is done each time.
3790 Defaults are 90% and 95%. If you have a large cache, 5% could be
3791 hundreds of MB. If this is the case you may wish to set these
3792 numbers closer together.
3794 See also cache_swap_low
3799 -----------------------------------------------------------------------------
3806 DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in.
3810 logformat <name> <format specification>
3812 Defines an access log format.
3814 The <format specification> is a string with embedded % format codes
3816 % format codes all follow the same basic structure where all but
3817 the formatcode is optional. Output strings are automatically escaped
3818 as required according to their context and the output format
3819 modifiers are usually not needed, but can be specified if an explicit
3820 output format is desired.
3822 % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
3824 " output in quoted string format
3825 [ output in squid text log format as used by log_mime_hdrs
3826 # output in URL quoted format
3831 width minimum and/or maximum field width:
3832 [width_min][.width_max]
3833 When minimum starts with 0, the field is zero-padded.
3834 String values exceeding maximum width are truncated.
3836 {arg} argument such as header name etc
3840 % a literal % character
3841 sn Unique sequence number per log line entry
3842 err_code The ID of an error response served by Squid or
3843 a similar internal error identifier.
3844 err_detail Additional err_code-dependent error information.
3845 note The annotation specified by the argument. Also
3846 logs the adaptation meta headers set by the
3847 adaptation_meta configuration parameter.
3848 If no argument given all annotations logged.
3849 The argument may include a separator to use with
3852 By default, multiple note values are separated with ","
3853 and multiple notes are separated with "\r\n".
3854 When logging named notes with %{name}note, the
3855 explicitly configured separator is used between note
3856 values. When logging all notes with %note, the
3857 explicitly configured separator is used between
3858 individual notes. There is currently no way to
3859 specify both value and notes separators when logging
3860 all notes with %note.
3862 Connection related format codes:
3864 >a Client source IP address
3866 >p Client source port
3867 >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier)
3868 >la Local IP address the client connected to
3869 >lp Local port number the client connected to
3870 >qos Client connection TOS/DSCP value set by Squid
3871 >nfmark Client connection netfilter mark set by Squid
3873 la Local listening IP address the client connection was connected to.
3874 lp Local listening port number the client connection was connected to.
3876 <a Server IP address of the last server or peer connection
3877 <A Server FQDN or peer name
3878 <p Server port number of the last server or peer connection
3879 <la Local IP address of the last server or peer connection
3880 <lp Local port number of the last server or peer connection
3881 <qos Server connection TOS/DSCP value set by Squid
3882 <nfmark Server connection netfilter mark set by Squid
3884 Time related format codes:
3886 ts Seconds since epoch
3887 tu subsecond time (milliseconds)
3888 tl Local time. Optional strftime format argument
3889 default %d/%b/%Y:%H:%M:%S %z
3890 tg GMT time. Optional strftime format argument
3891 default %d/%b/%Y:%H:%M:%S %z
3892 tr Response time (milliseconds)
3893 dt Total time spent making DNS lookups (milliseconds)
3894 tS Approximate master transaction start time in
3895 <full seconds since epoch>.<fractional seconds> format.
3896 Currently, Squid considers the master transaction
3897 started when a complete HTTP request header initiating
3898 the transaction is received from the client. This is
3899 the same value that Squid uses to calculate transaction
3900 response time when logging %tr to access.log. Currently,
3901 Squid uses millisecond resolution for %tS values,
3902 similar to the default access.log "current time" field
3905 Access Control related format codes:
3907 et Tag returned by external acl
3908 ea Log string returned by external acl
3909 un User name (any available)
3910 ul User name from authentication
3911 ue User name from external acl helper
3912 ui User name from ident
3913 us User name from SSL
3914 credentials Client credentials. The exact meaning depends on
3915 the authentication scheme: For Basic authentication,
3916 it is the password; for Digest, the realm sent by the
3917 client; for NTLM and Negotiate, the client challenge
3918 or client credentials prefixed with "YR " or "KK ".
3920 HTTP related format codes:
3924 [http::]rm Request method (GET/POST etc)
3925 [http::]>rm Request method from client
3926 [http::]<rm Request method sent to server or peer
3927 [http::]ru Request URL from client (historic, filtered for logging)
3928 [http::]>ru Request URL from client
3929 [http::]<ru Request URL sent to server or peer
3930 [http::]>rs Request URL scheme from client
3931 [http::]<rs Request URL scheme sent to server or peer
3932 [http::]>rd Request URL domain from client
3933 [http::]>rd Request URL domain sent to server or peer
3934 [http::]>rP Request URL port from client
3935 [http::]<rP Request URL port sent to server or peer
3936 [http::]rp Request URL path excluding hostname
3937 [http::]>rp Request URL path excluding hostname from client
3938 [http::]<rp Request URL path excluding hostname sent to server or peer
3939 [http::]rv Request protocol version
3940 [http::]>rv Request protocol version from client
3941 [http::]<rv Request protocol version sent to server or peer
3943 [http::]>h Original received request header.
3944 Usually differs from the request header sent by
3945 Squid, although most fields are often preserved.
3946 Accepts optional header field name/value filter
3947 argument using name[:[separator]element] format.
3948 [http::]>ha Received request header after adaptation and
3949 redirection (pre-cache REQMOD vectoring point).
3950 Usually differs from the request header sent by
3951 Squid, although most fields are often preserved.
3952 Optional header name argument as for >h
3957 [http::]<Hs HTTP status code received from the next hop
3958 [http::]>Hs HTTP status code sent to the client
3960 [http::]<h Reply header. Optional header name argument
3963 [http::]mt MIME content type
3968 [http::]st Total size of request + reply traffic with client
3969 [http::]>st Total size of request received from client.
3970 Excluding chunked encoding bytes.
3971 [http::]<st Total size of reply sent to client (after adaptation)
3973 [http::]>sh Size of request headers received from client
3974 [http::]<sh Size of reply headers sent to client (after adaptation)
3976 [http::]<sH Reply high offset sent
3977 [http::]<sS Upstream object size
3979 [http::]<bs Number of HTTP-equivalent message body bytes
3980 received from the next hop, excluding chunked
3981 transfer encoding and control messages.
3982 Generated FTP/Gopher listings are treated as
3988 [http::]<pt Peer response time in milliseconds. The timer starts
3989 when the last request byte is sent to the next hop
3990 and stops when the last response byte is received.
3991 [http::]<tt Total server-side time in milliseconds. The timer
3992 starts with the first connect request (or write I/O)
3993 sent to the first selected peer. The timer stops
3994 with the last I/O with the last peer.
3996 Squid handling related format codes:
3998 Ss Squid request status (TCP_MISS etc)
3999 Sh Squid hierarchy status (DEFAULT_PARENT etc)
4001 SSL-related format codes:
4003 ssl::bump_mode SslBump decision for the transaction:
4005 For CONNECT requests that initiated bumping of
4006 a connection and for any request received on
4007 an already bumped connection, Squid logs the
4008 corresponding SslBump mode ("server-first" or
4009 "client-first"). See the ssl_bump option for
4010 more information about these modes.
4012 A "none" token is logged for requests that
4013 triggered "ssl_bump" ACL evaluation matching
4014 either a "none" rule or no rules at all.
4016 In all other cases, a single dash ("-") is
4019 If ICAP is enabled, the following code becomes available (as
4020 well as ICAP log codes documented with the icap_log option):
4022 icap::tt Total ICAP processing time for the HTTP
4023 transaction. The timer ticks when ICAP
4024 ACLs are checked and when ICAP
4025 transaction is in progress.
4027 If adaptation is enabled the following three codes become available:
4029 adapt::<last_h The header of the last ICAP response or
4030 meta-information from the last eCAP
4031 transaction related to the HTTP transaction.
4032 Like <h, accepts an optional header name
4035 adapt::sum_trs Summed adaptation transaction response
4036 times recorded as a comma-separated list in
4037 the order of transaction start time. Each time
4038 value is recorded as an integer number,
4039 representing response time of one or more
4040 adaptation (ICAP or eCAP) transaction in
4041 milliseconds. When a failed transaction is
4042 being retried or repeated, its time is not
4043 logged individually but added to the
4044 replacement (next) transaction. See also:
4047 adapt::all_trs All adaptation transaction response times.
4048 Same as adaptation_strs but response times of
4049 individual transactions are never added
4050 together. Instead, all transaction response
4051 times are recorded individually.
4053 You can prefix adapt::*_trs format codes with adaptation
4054 service name in curly braces to record response time(s) specific
4055 to that service. For example: %{my_service}adapt::sum_trs
4057 If SSL is enabled, the following formating codes become available:
4059 %ssl::>cert_subject The Subject field of the received client
4060 SSL certificate or a dash ('-') if Squid has
4061 received an invalid/malformed certificate or
4062 no certificate at all. Consider encoding the
4063 logged value because Subject often has spaces.
4065 %ssl::>cert_issuer The Issuer field of the received client
4066 SSL certificate or a dash ('-') if Squid has
4067 received an invalid/malformed certificate or
4068 no certificate at all. Consider encoding the
4069 logged value because Issuer often has spaces.
4071 The default formats available (which do not need re-defining) are:
4073 logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
4074 logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
4075 logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
4076 logformat referrer %ts.%03tu %>a %{Referer}>h %ru
4077 logformat useragent %>a [%tl] "%{User-Agent}>h"
4079 NOTE: When the log_mime_hdrs directive is set to ON.
4080 The squid, common and combined formats have a safely encoded copy
4081 of the mime headers appended to each line within a pair of brackets.
4083 NOTE: The common and combined formats are not quite true to the Apache definition.
4084 The logs from Squid contain an extra status and hierarchy code appended.
4088 NAME: access_log cache_access_log
4090 LOC: Config.Log.accesslogs
4091 DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
4093 Configures whether and how Squid logs HTTP and ICP transactions.
4094 If access logging is enabled, a single line is logged for every
4095 matching HTTP or ICP request. The recommended directive formats are:
4097 access_log <module>:<place> [option ...] [acl acl ...]
4098 access_log none [acl acl ...]
4100 The following directive format is accepted but may be deprecated:
4101 access_log <module>:<place> [<logformat name> [acl acl ...]]
4103 In most cases, the first ACL name must not contain the '=' character
4104 and should not be equal to an existing logformat name. You can always
4105 start with an 'all' ACL to work around those restrictions.
4107 Will log to the specified module:place using the specified format (which
4108 must be defined in a logformat directive) those entries which match
4109 ALL the acl's specified (which must be defined in acl clauses).
4110 If no acl is specified, all requests will be logged to this destination.
4112 ===== Available options for the recommended directive format =====
4114 logformat=name Names log line format (either built-in or
4115 defined by a logformat directive). Defaults
4118 buffer-size=64KB Defines approximate buffering limit for log
4119 records (see buffered_logs). Squid should not
4120 keep more than the specified size and, hence,
4121 should flush records before the buffer becomes
4122 full to avoid overflows under normal
4123 conditions (the exact flushing algorithm is
4124 module-dependent though). The on-error option
4125 controls overflow handling.
4127 on-error=die|drop Defines action on unrecoverable errors. The
4128 'drop' action ignores (i.e., does not log)
4129 affected log records. The default 'die' action
4130 kills the affected worker. The drop action
4131 support has not been tested for modules other
4134 ===== Modules Currently available =====
4136 none Do not log any requests matching these ACL.
4137 Do not specify Place or logformat name.
4139 stdio Write each log line to disk immediately at the completion of
4141 Place: the filename and path to be written.
4143 daemon Very similar to stdio. But instead of writing to disk the log
4144 line is passed to a daemon helper for asychronous handling instead.
4145 Place: varies depending on the daemon.
4147 log_file_daemon Place: the file name and path to be written.
4149 syslog To log each request via syslog facility.
4150 Place: The syslog facility and priority level for these entries.
4151 Place Format: facility.priority
4153 where facility could be any of:
4154 authpriv, daemon, local0 ... local7 or user.
4156 And priority could be any of:
4157 err, warning, notice, info, debug.
4159 udp To send each log line as text data to a UDP receiver.
4160 Place: The destination host name or IP and port.
4161 Place Format: //host:port
4163 tcp To send each log line as text data to a TCP receiver.
4164 Lines may be accumulated before sending (see buffered_logs).
4165 Place: The destination host name or IP and port.
4166 Place Format: //host:port
4169 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
4175 LOC: Config.Log.icaplogs
4178 ICAP log files record ICAP transaction summaries, one line per
4181 The icap_log option format is:
4182 icap_log <filepath> [<logformat name> [acl acl ...]]
4183 icap_log none [acl acl ...]]
4185 Please see access_log option documentation for details. The two
4186 kinds of logs share the overall configuration approach and many
4189 ICAP processing of a single HTTP message or transaction may
4190 require multiple ICAP transactions. In such cases, multiple
4191 ICAP transaction log lines will correspond to a single access
4194 ICAP log uses logformat codes that make sense for an ICAP
4195 transaction. Header-related codes are applied to the HTTP header
4196 embedded in an ICAP server response, with the following caveats:
4197 For REQMOD, there is no HTTP response header unless the ICAP
4198 server performed request satisfaction. For RESPMOD, the HTTP
4199 request header is the header sent to the ICAP server. For
4200 OPTIONS, there are no HTTP headers.
4202 The following format codes are also available for ICAP logs:
4204 icap::<A ICAP server IP address. Similar to <A.
4206 icap::<service_name ICAP service name from the icap_service
4207 option in Squid configuration file.
4209 icap::ru ICAP Request-URI. Similar to ru.
4211 icap::rm ICAP request method (REQMOD, RESPMOD, or
4212 OPTIONS). Similar to existing rm.
4214 icap::>st Bytes sent to the ICAP server (TCP payload
4215 only; i.e., what Squid writes to the socket).
4217 icap::<st Bytes received from the ICAP server (TCP
4218 payload only; i.e., what Squid reads from
4221 icap::<bs Number of message body bytes received from the
4222 ICAP server. ICAP message body, if any, usually
4223 includes encapsulated HTTP message headers and
4224 possibly encapsulated HTTP message body. The
4225 HTTP body part is dechunked before its size is
4228 icap::tr Transaction response time (in
4229 milliseconds). The timer starts when
4230 the ICAP transaction is created and
4231 stops when the transaction is completed.
4234 icap::tio Transaction I/O time (in milliseconds). The
4235 timer starts when the first ICAP request
4236 byte is scheduled for sending. The timers
4237 stops when the last byte of the ICAP response
4240 icap::to Transaction outcome: ICAP_ERR* for all
4241 transaction errors, ICAP_OPT for OPTION
4242 transactions, ICAP_ECHO for 204
4243 responses, ICAP_MOD for message
4244 modification, and ICAP_SAT for request
4245 satisfaction. Similar to Ss.
4247 icap::Hs ICAP response status code. Similar to Hs.
4249 icap::>h ICAP request header(s). Similar to >h.
4251 icap::<h ICAP response header(s). Similar to <h.
4253 The default ICAP log format, which can be used without an explicit
4254 definition, is called icap_squid:
4256 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
4258 See also: logformat, log_icap, and %adapt::<last_h
4261 NAME: logfile_daemon
4263 DEFAULT: @DEFAULT_LOGFILED@
4264 LOC: Log::TheConfig.logfile_daemon
4266 Specify the path to the logfile-writing daemon. This daemon is
4267 used to write the access and store logs, if configured.
4269 Squid sends a number of commands to the log daemon:
4270 L<data>\n - logfile data
4275 r<n>\n - set rotate count to <n>
4276 b<n>\n - 1 = buffer output, 0 = don't buffer output
4278 No responses is expected.
4281 NAME: stats_collection
4283 LOC: Config.accessList.stats_collection
4285 DEFAULT_DOC: Allow logging for all transactions.
4286 COMMENT: allow|deny acl acl...
4288 This options allows you to control which requests gets accounted
4289 in performance counters.
4291 This clause only supports fast acl types.
4292 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4295 NAME: cache_store_log
4298 LOC: Config.Log.store
4300 Logs the activities of the storage manager. Shows which
4301 objects are ejected from the cache, and which objects are
4302 saved and for how long.
4303 There are not really utilities to analyze this data, so you can safely
4304 disable it (the default).
4306 Store log uses modular logging outputs. See access_log for the list
4307 of modules supported.
4310 cache_store_log stdio:@DEFAULT_STORE_LOG@
4311 cache_store_log daemon:@DEFAULT_STORE_LOG@
4314 NAME: cache_swap_state cache_swap_log
4316 LOC: Config.Log.swap
4318 DEFAULT_DOC: Store the journal inside its cache_dir
4320 Location for the cache "swap.state" file. This index file holds
4321 the metadata of objects saved on disk. It is used to rebuild
4322 the cache during startup. Normally this file resides in each
4323 'cache_dir' directory, but you may specify an alternate
4324 pathname here. Note you must give a full filename, not just
4325 a directory. Since this is the index for the whole object
4326 list you CANNOT periodically rotate it!
4328 If %s can be used in the file name it will be replaced with a
4329 a representation of the cache_dir name where each / is replaced
4330 with '.'. This is needed to allow adding/removing cache_dir
4331 lines when cache_swap_log is being used.
4333 If have more than one 'cache_dir', and %s is not used in the name
4334 these swap logs will have names such as:
4340 The numbered extension (which is added automatically)
4341 corresponds to the order of the 'cache_dir' lines in this
4342 configuration file. If you change the order of the 'cache_dir'
4343 lines in this file, these index files will NOT correspond to
4344 the correct 'cache_dir' entry (unless you manually rename
4345 them). We recommend you do NOT use this option. It is
4346 better to keep these index files in each 'cache_dir' directory.
4349 NAME: logfile_rotate
4352 LOC: Config.Log.rotateNumber
4354 Specifies the number of logfile rotations to make when you
4355 type 'squid -k rotate'. The default is 10, which will rotate
4356 with extensions 0 through 9. Setting logfile_rotate to 0 will
4357 disable the file name rotation, but the logfiles are still closed
4358 and re-opened. This will enable you to rename the logfiles
4359 yourself just before sending the rotate signal.
4361 Note, the 'squid -k rotate' command normally sends a USR1
4362 signal to the running squid process. In certain situations
4363 (e.g. on Linux with Async I/O), USR1 is used for other
4364 purposes, so -k rotate uses another signal. It is best to get
4365 in the habit of using 'squid -k rotate' instead of 'kill -USR1
4368 Note, from Squid-3.1 this option is only a default for cache.log,
4369 that log can be rotated separately by using debug_options.
4374 DEFAULT: @DEFAULT_MIME_TABLE@
4375 LOC: Config.mimeTablePathname
4377 Path to Squid's icon configuration file.
4379 You shouldn't need to change this, but the default file contains
4380 examples and formatting information if you do.
4386 LOC: Config.onoff.log_mime_hdrs
4389 The Cache can record both the request and the response MIME
4390 headers for each HTTP transaction. The headers are encoded
4391 safely and will appear as two bracketed fields at the end of
4392 the access log (for either the native or httpd-emulated log
4393 formats). To enable this logging set log_mime_hdrs to 'on'.
4398 DEFAULT: @DEFAULT_PID_FILE@
4399 LOC: Config.pidFilename
4401 A filename to write the process-id to. To disable, enter "none".
4404 NAME: client_netmask
4406 LOC: Config.Addrs.client_netmask
4408 DEFAULT_DOC: Log full client IP address
4410 A netmask for client addresses in logfiles and cachemgr output.
4411 Change this to protect the privacy of your cache clients.
4412 A netmask of 255.255.255.0 will log all IP's in that range with
4413 the last digit set to '0'.
4416 NAME: strip_query_terms
4418 LOC: Config.onoff.strip_query_terms
4421 By default, Squid strips query terms from requested URLs before
4422 logging. This protects your user's privacy and reduces log size.
4424 When investigating HIT/MISS or other caching behaviour you
4425 will need to disable this to see the full URL used by Squid.
4432 LOC: Config.onoff.buffered_logs
4434 Whether to write/send access_log records ASAP or accumulate them and
4435 then write/send them in larger chunks. Buffering may improve
4436 performance because it decreases the number of I/Os. However,
4437 buffering increases the delay before log records become available to
4438 the final recipient (e.g., a disk file or logging daemon) and,
4439 hence, increases the risk of log records loss.
4441 Note that even when buffered_logs are off, Squid may have to buffer
4442 records if it cannot write/send them immediately due to pending I/Os
4443 (e.g., the I/O writing the previous log record) or connectivity loss.
4445 Currently honored by 'daemon' and 'tcp' access_log modules only.
4448 NAME: netdb_filename
4450 DEFAULT: stdio:@DEFAULT_NETDB_FILE@
4451 LOC: Config.netdbFilename
4454 Where Squid stores it's netdb journal.
4455 When enabled this journal preserves netdb state between restarts.
4457 To disable, enter "none".
4461 OPTIONS FOR TROUBLESHOOTING
4462 -----------------------------------------------------------------------------
4467 DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
4468 LOC: Debug::cache_log
4470 Squid administrative logging file.
4472 This is where general information about Squid behavior goes. You can
4473 increase the amount of data logged to this file and how often it is
4474 rotated with "debug_options"
4480 DEFAULT_DOC: Log all critical and important messages.
4481 LOC: Debug::debugOptions
4483 Logging options are set as section,level where each source file
4484 is assigned a unique section. Lower levels result in less
4485 output, Full debugging (level 9) can result in a very large
4486 log file, so be careful.
4488 The magic word "ALL" sets debugging levels for all sections.
4489 The default is to run with "ALL,1" to record important warnings.
4491 The rotate=N option can be used to keep more or less of these logs
4492 than would otherwise be kept by logfile_rotate.
4493 For most uses a single log should be enough to monitor current
4494 events affecting Squid.
4499 LOC: Config.coredump_dir
4500 DEFAULT_IF_NONE: none
4501 DEFAULT_DOC: Use the directory from where Squid was started.
4503 By default Squid leaves core files in the directory from where
4504 it was started. If you set 'coredump_dir' to a directory
4505 that exists, Squid will chdir() to that directory at startup
4506 and coredump files will be left there.
4510 # Leave coredumps in the first cache dir
4511 coredump_dir @DEFAULT_SWAP_DIR@
4517 OPTIONS FOR FTP GATEWAYING
4518 -----------------------------------------------------------------------------
4524 LOC: Config.Ftp.anon_user
4526 If you want the anonymous login password to be more informative
4527 (and enable the use of picky FTP servers), set this to something
4528 reasonable for your domain, like wwwuser@somewhere.net
4530 The reason why this is domainless by default is the
4531 request can be made on the behalf of a user in any domain,
4532 depending on how the cache is used.
4533 Some FTP server also validate the email address is valid
4534 (for example perl.com).
4540 LOC: Config.Ftp.passive
4542 If your firewall does not allow Squid to use passive
4543 connections, turn off this option.
4545 Use of ftp_epsv_all option requires this to be ON.
4551 LOC: Config.Ftp.epsv_all
4553 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
4555 NATs may be able to put the connection on a "fast path" through the
4556 translator, as the EPRT command will never be used and therefore,
4557 translation of the data portion of the segments will never be needed.
4559 When a client only expects to do two-way FTP transfers this may be
4561 If squid finds that it must do a three-way FTP transfer after issuing
4562 an EPSV ALL command, the FTP session will fail.
4564 If you have any doubts about this option do not use it.
4565 Squid will nicely attempt all other connection methods.
4567 Requires ftp_passive to be ON (default) for any effect.
4573 LOC: Config.accessList.ftp_epsv
4575 FTP Protocol extensions permit the use of a special "EPSV" command.
4577 NATs may be able to put the connection on a "fast path" through the
4578 translator using EPSV, as the EPRT command will never be used
4579 and therefore, translation of the data portion of the segments
4580 will never be needed.
4582 EPSV is often required to interoperate with FTP servers on IPv6
4583 networks. On the other hand, it may break some IPv4 servers.
4585 By default, EPSV may try EPSV with any FTP server. To fine tune
4586 that decision, you may restrict EPSV to certain clients or servers
4589 ftp_epsv allow|deny al1 acl2 ...
4591 WARNING: Disabling EPSV may cause problems with external NAT and IPv6.
4593 Only fast ACLs are supported.
4594 Requires ftp_passive to be ON (default) for any effect.
4600 LOC: Config.Ftp.eprt
4602 FTP Protocol extensions permit the use of a special "EPRT" command.
4604 This extension provides a protocol neutral alternative to the
4605 IPv4-only PORT command. When supported it enables active FTP data
4606 channels over IPv6 and efficient NAT handling.
4608 Turning this OFF will prevent EPRT being attempted and will skip
4609 straight to using PORT for IPv4 servers.
4611 Some devices are known to not handle this extension correctly and
4612 may result in crashes. Devices which suport EPRT enough to fail
4613 cleanly will result in Squid attempting PORT anyway. This directive
4614 should only be disabled when EPRT results in device failures.
4616 WARNING: Doing so will convert Squid back to the old behavior with all
4617 the related problems with external NAT devices/layers and IPv4-only FTP.
4620 NAME: ftp_sanitycheck
4623 LOC: Config.Ftp.sanitycheck
4625 For security and data integrity reasons Squid by default performs
4626 sanity checks of the addresses of FTP data connections ensure the
4627 data connection is to the requested server. If you need to allow
4628 FTP connections to servers using another IP address for the data
4629 connection turn this off.
4632 NAME: ftp_telnet_protocol
4635 LOC: Config.Ftp.telnet
4637 The FTP protocol is officially defined to use the telnet protocol
4638 as transport channel for the control connection. However, many
4639 implementations are broken and does not respect this aspect of
4642 If you have trouble accessing files with ASCII code 255 in the
4643 path or similar problems involving this ASCII code you can
4644 try setting this directive to off. If that helps, report to the
4645 operator of the FTP server in question that their FTP server
4646 is broken and does not follow the FTP standard.
4650 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
4651 -----------------------------------------------------------------------------
4656 DEFAULT: @DEFAULT_DISKD@
4657 LOC: Config.Program.diskd
4659 Specify the location of the diskd executable.
4660 Note this is only useful if you have compiled in
4661 diskd as one of the store io modules.
4664 NAME: unlinkd_program
4667 DEFAULT: @DEFAULT_UNLINKD@
4668 LOC: Config.Program.unlinkd
4670 Specify the location of the executable for file deletion process.
4673 NAME: pinger_program
4675 DEFAULT: @DEFAULT_PINGER@
4676 LOC: Config.pinger.program
4679 Specify the location of the executable for the pinger process.
4685 LOC: Config.pinger.enable
4688 Control whether the pinger is active at run-time.
4689 Enables turning ICMP pinger on and off with a simple
4690 squid -k reconfigure.
4695 OPTIONS FOR URL REWRITING
4696 -----------------------------------------------------------------------------
4699 NAME: url_rewrite_program redirect_program
4701 LOC: Config.Program.redirect
4704 Specify the location of the executable URL rewriter to use.
4705 Since they can perform almost any function there isn't one included.
4707 For each requested URL, the rewriter will receive on line with the format
4709 [channel-ID <SP>] URL [<SP> extras]<NL>
4711 See url_rewrite_extras on how to send "extras" with optional values to
4713 After processing the request the helper must reply using the following format:
4715 [channel-ID <SP>] result [<SP> kv-pairs]
4717 The result code can be:
4719 OK status=30N url="..."
4720 Redirect the URL to the one supplied in 'url='.
4721 'status=' is optional and contains the status code to send
4722 the client in Squids HTTP response. It must be one of the
4723 HTTP redirect status codes: 301, 302, 303, 307, 308.
4724 When no status is given Squid will use 302.
4726 OK rewrite-url="..."
4727 Rewrite the URL to the one supplied in 'rewrite-url='.
4728 The new URL is fetched directly by Squid and returned to
4729 the client as the response to its request.
4732 When neither of url= and rewrite-url= are sent Squid does
4736 Do not change the URL.
4739 An internal error occurred in the helper, preventing
4740 a result being identified. The 'message=' key name is
4741 reserved for delivering a log message.
4744 In addition to the above kv-pairs Squid also understands the following
4745 optional kv-pairs received from URL rewriters:
4747 Associates a TAG with the client TCP connection.
4748 The TAG is treated as a regular annotation but persists across
4749 future requests on the client connection rather than just the
4750 current request. A helper may update the TAG during subsequent
4751 requests be returning a new kv-pair.
4753 When using the concurrency= option the protocol is changed by
4754 introducing a query channel tag in front of the request/response.
4755 The query channel tag is a number between 0 and concurrency-1.
4756 This value must be echoed back unchanged to Squid as the first part
4757 of the response relating to its request.
4759 WARNING: URL re-writing ability should be avoided whenever possible.
4760 Use the URL redirect form of response instead.
4762 Re-write creates a difference in the state held by the client
4763 and server. Possibly causing confusion when the server response
4764 contains snippets of its view state. Embeded URLs, response
4765 and content Location headers, etc. are not re-written by this
4768 By default, a URL rewriter is not used.
4771 NAME: url_rewrite_children redirect_children
4772 TYPE: HelperChildConfig
4773 DEFAULT: 20 startup=0 idle=1 concurrency=0
4774 LOC: Config.redirectChildren
4776 The maximum number of redirector processes to spawn. If you limit
4777 it too few Squid will have to wait for them to process a backlog of
4778 URLs, slowing it down. If you allow too many they will use RAM
4779 and other system resources noticably.
4781 The startup= and idle= options allow some measure of skew in your
4786 Sets a minimum of how many processes are to be spawned when Squid
4787 starts or reconfigures. When set to zero the first request will
4788 cause spawning of the first child process to handle it.
4790 Starting too few will cause an initial slowdown in traffic as Squid
4791 attempts to simultaneously spawn enough processes to cope.
4795 Sets a minimum of how many processes Squid is to try and keep available
4796 at all times. When traffic begins to rise above what the existing
4797 processes can handle this many more will be spawned up to the maximum
4798 configured. A minimum setting of 1 is required.
4802 The number of requests each redirector helper can handle in
4803 parallel. Defaults to 0 which indicates the redirector
4804 is a old-style single threaded redirector.
4806 When this directive is set to a value >= 1 then the protocol
4807 used to communicate with the helper is modified to include
4808 an ID in front of the request/response. The ID from the request
4809 must be echoed back with the response to that request.
4812 NAME: url_rewrite_host_header redirect_rewrites_host_header
4815 LOC: Config.onoff.redir_rewrites_host
4817 To preserve same-origin security policies in browsers and
4818 prevent Host: header forgery by redirectors Squid rewrites
4819 any Host: header in redirected requests.
4821 If you are running an accelerator this may not be a wanted
4822 effect of a redirector. This directive enables you disable
4823 Host: alteration in reverse-proxy traffic.
4825 WARNING: Entries are cached on the result of the URL rewriting
4826 process, so be careful if you have domain-virtual hosts.
4828 WARNING: Squid and other software verifies the URL and Host
4829 are matching, so be careful not to relay through other proxies
4830 or inspecting firewalls with this disabled.
4833 NAME: url_rewrite_access redirector_access
4836 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
4837 LOC: Config.accessList.redirector
4839 If defined, this access list specifies which requests are
4840 sent to the redirector processes.
4842 This clause supports both fast and slow acl types.
4843 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4846 NAME: url_rewrite_bypass redirector_bypass
4848 LOC: Config.onoff.redirector_bypass
4851 When this is 'on', a request will not go through the
4852 redirector if all the helpers are busy. If this is 'off'
4853 and the redirector queue grows too large, Squid will exit
4854 with a FATAL error and ask you to increase the number of
4855 redirectors. You should only enable this if the redirectors
4856 are not critical to your caching system. If you use
4857 redirectors for access control, and you enable this option,
4858 users may have access to pages they should not
4859 be allowed to request.
4862 NAME: url_rewrite_extras
4863 TYPE: TokenOrQuotedString
4864 LOC: Config.redirector_extras
4865 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
4867 Specifies a string to be append to request line format for the
4868 rewriter helper. "Quoted" format values may contain spaces and
4869 logformat %macros. In theory, any logformat %macro can be used.
4870 In practice, a %macro expands as a dash (-) if the helper request is
4871 sent before the required macro information is available to Squid.
4875 OPTIONS FOR STORE ID
4876 -----------------------------------------------------------------------------
4879 NAME: store_id_program storeurl_rewrite_program
4881 LOC: Config.Program.store_id
4884 Specify the location of the executable StoreID helper to use.
4885 Since they can perform almost any function there isn't one included.
4887 For each requested URL, the helper will receive one line with the format
4889 [channel-ID <SP>] URL [<SP> extras]<NL>
4892 After processing the request the helper must reply using the following format:
4894 [channel-ID <SP>] result [<SP> kv-pairs]
4896 The result code can be:
4899 Use the StoreID supplied in 'store-id='.
4902 The default is to use HTTP request URL as the store ID.
4905 An internal error occured in the helper, preventing
4906 a result being identified.
4908 In addition to the above kv-pairs Squid also understands the following
4909 optional kv-pairs received from URL rewriters:
4911 Associates a TAG with the client TCP connection.
4912 Please see url_rewrite_program related documentation for this
4915 Helper programs should be prepared to receive and possibly ignore
4916 additional whitespace-separated tokens on each input line.
4918 When using the concurrency= option the protocol is changed by
4919 introducing a query channel tag in front of the request/response.
4920 The query channel tag is a number between 0 and concurrency-1.
4921 This value must be echoed back unchanged to Squid as the first part
4922 of the response relating to its request.
4924 NOTE: when using StoreID refresh_pattern will apply to the StoreID
4925 returned from the helper and not the URL.
4927 WARNING: Wrong StoreID value returned by a careless helper may result
4928 in the wrong cached response returned to the user.
4930 By default, a StoreID helper is not used.
4933 NAME: store_id_extras
4934 TYPE: TokenOrQuotedString
4935 LOC: Config.storeId_extras
4936 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
4938 Specifies a string to be append to request line format for the
4939 StoreId helper. "Quoted" format values may contain spaces and
4940 logformat %macros. In theory, any logformat %macro can be used.
4941 In practice, a %macro expands as a dash (-) if the helper request is
4942 sent before the required macro information is available to Squid.
4945 NAME: store_id_children storeurl_rewrite_children
4946 TYPE: HelperChildConfig
4947 DEFAULT: 20 startup=0 idle=1 concurrency=0
4948 LOC: Config.storeIdChildren
4950 The maximum number of StoreID helper processes to spawn. If you limit
4951 it too few Squid will have to wait for them to process a backlog of
4952 requests, slowing it down. If you allow too many they will use RAM
4953 and other system resources noticably.
4955 The startup= and idle= options allow some measure of skew in your
4960 Sets a minimum of how many processes are to be spawned when Squid
4961 starts or reconfigures. When set to zero the first request will
4962 cause spawning of the first child process to handle it.
4964 Starting too few will cause an initial slowdown in traffic as Squid
4965 attempts to simultaneously spawn enough processes to cope.
4969 Sets a minimum of how many processes Squid is to try and keep available
4970 at all times. When traffic begins to rise above what the existing
4971 processes can handle this many more will be spawned up to the maximum
4972 configured. A minimum setting of 1 is required.
4976 The number of requests each storeID helper can handle in
4977 parallel. Defaults to 0 which indicates the helper
4978 is a old-style single threaded program.
4980 When this directive is set to a value >= 1 then the protocol
4981 used to communicate with the helper is modified to include
4982 an ID in front of the request/response. The ID from the request
4983 must be echoed back with the response to that request.
4986 NAME: store_id_access storeurl_rewrite_access
4989 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
4990 LOC: Config.accessList.store_id
4992 If defined, this access list specifies which requests are
4993 sent to the StoreID processes. By default all requests
4996 This clause supports both fast and slow acl types.
4997 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5000 NAME: store_id_bypass storeurl_rewrite_bypass
5002 LOC: Config.onoff.store_id_bypass
5005 When this is 'on', a request will not go through the
5006 helper if all helpers are busy. If this is 'off'
5007 and the helper queue grows too large, Squid will exit
5008 with a FATAL error and ask you to increase the number of
5009 helpers. You should only enable this if the helperss
5010 are not critical to your caching system. If you use
5011 helpers for critical caching components, and you enable this
5012 option, users may not get objects from cache.
5016 OPTIONS FOR TUNING THE CACHE
5017 -----------------------------------------------------------------------------
5020 NAME: cache no_cache
5023 DEFAULT_DOC: By default, this directive is unused and has no effect.
5024 LOC: Config.accessList.noCache
5026 Requests denied by this directive will not be served from the cache
5027 and their responses will not be stored in the cache. This directive
5028 has no effect on other transactions and on already cached responses.
5030 This clause supports both fast and slow acl types.
5031 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5033 This and the two other similar caching directives listed below are
5034 checked at different transaction processing stages, have different
5035 access to response information, affect different cache operations,
5036 and differ in slow ACLs support:
5038 * cache: Checked before Squid makes a hit/miss determination.
5039 No access to reply information!
5040 Denies both serving a hit and storing a miss.
5041 Supports both fast and slow ACLs.
5042 * send_hit: Checked after a hit was detected.
5043 Has access to reply (hit) information.
5044 Denies serving a hit only.
5045 Supports fast ACLs only.
5046 * store_miss: Checked before storing a cachable miss.
5047 Has access to reply (miss) information.
5048 Denies storing a miss only.
5049 Supports fast ACLs only.
5051 If you are not sure which of the three directives to use, apply the
5052 following decision logic:
5054 * If your ACL(s) are of slow type _and_ need response info, redesign.
5055 Squid does not support that particular combination at this time.
5057 * If your directive ACL(s) are of slow type, use "cache"; and/or
5058 * if your directive ACL(s) need no response info, use "cache".
5060 * If you do not want the response cached, use store_miss; and/or
5061 * if you do not want a hit on a cached response, use send_hit.
5067 DEFAULT_DOC: By default, this directive is unused and has no effect.
5068 LOC: Config.accessList.sendHit
5070 Responses denied by this directive will not be served from the cache
5071 (but may still be cached, see store_miss). This directive has no
5072 effect on the responses it allows and on the cached objects.
5074 Please see the "cache" directive for a summary of differences among
5075 store_miss, send_hit, and cache directives.
5077 Unlike the "cache" directive, send_hit only supports fast acl
5078 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5082 # apply custom Store ID mapping to some URLs
5083 acl MapMe dstdomain .c.example.com
5084 store_id_program ...
5085 store_id_access allow MapMe
5087 # but prevent caching of special responses
5088 # such as 302 redirects that cause StoreID loops
5089 acl Ordinary http_status 200-299
5090 store_miss deny MapMe !Ordinary
5092 # and do not serve any previously stored special responses
5093 # from the cache (in case they were already cached before
5094 # the above store_miss rule was in effect).
5095 send_hit deny MapMe !Ordinary
5101 DEFAULT_DOC: By default, this directive is unused and has no effect.
5102 LOC: Config.accessList.storeMiss
5104 Responses denied by this directive will not be cached (but may still
5105 be served from the cache, see send_hit). This directive has no
5106 effect on the responses it allows and on the already cached responses.
5108 Please see the "cache" directive for a summary of differences among
5109 store_miss, send_hit, and cache directives. See the
5110 send_hit directive for a usage example.
5112 Unlike the "cache" directive, store_miss only supports fast acl
5113 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5119 LOC: Config.maxStale
5122 This option puts an upper limit on how stale content Squid
5123 will serve from the cache if cache validation fails.
5124 Can be overriden by the refresh_pattern max-stale option.
5127 NAME: refresh_pattern
5128 TYPE: refreshpattern
5132 usage: refresh_pattern [-i] regex min percent max [options]
5134 By default, regular expressions are CASE-SENSITIVE. To make
5135 them case-insensitive, use the -i option.
5137 'Min' is the time (in minutes) an object without an explicit
5138 expiry time should be considered fresh. The recommended
5139 value is 0, any higher values may cause dynamic applications
5140 to be erroneously cached unless the application designer
5141 has taken the appropriate actions.
5143 'Percent' is a percentage of the objects age (time since last
5144 modification age) an object without explicit expiry time
5145 will be considered fresh.
5147 'Max' is an upper limit on how long objects without an explicit
5148 expiry time will be considered fresh.
5150 options: override-expire
5155 ignore-must-revalidate
5162 override-expire enforces min age even if the server
5163 sent an explicit expiry time (e.g., with the
5164 Expires: header or Cache-Control: max-age). Doing this
5165 VIOLATES the HTTP standard. Enabling this feature
5166 could make you liable for problems which it causes.
5168 Note: override-expire does not enforce staleness - it only extends
5169 freshness / min. If the server returns a Expires time which
5170 is longer than your max time, Squid will still consider
5171 the object fresh for that period of time.
5173 override-lastmod enforces min age even on objects
5174 that were modified recently.
5176 reload-into-ims changes a client no-cache or ``reload''
5177 request for a cached entry into a conditional request using
5178 If-Modified-Since and/or If-None-Match headers, provided the
5179 cached entry has a Last-Modified and/or a strong ETag header.
5180 Doing this VIOLATES the HTTP standard. Enabling this feature
5181 could make you liable for problems which it causes.
5183 ignore-reload ignores a client no-cache or ``reload''
5184 header. Doing this VIOLATES the HTTP standard. Enabling
5185 this feature could make you liable for problems which
5188 ignore-no-store ignores any ``Cache-control: no-store''
5189 headers received from a server. Doing this VIOLATES
5190 the HTTP standard. Enabling this feature could make you
5191 liable for problems which it causes.
5193 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
5194 headers received from a server. Doing this VIOLATES
5195 the HTTP standard. Enabling this feature could make you
5196 liable for problems which it causes.
5198 ignore-private ignores any ``Cache-control: private''
5199 headers received from a server. Doing this VIOLATES
5200 the HTTP standard. Enabling this feature could make you
5201 liable for problems which it causes.
5203 ignore-auth caches responses to requests with authorization,
5204 as if the originserver had sent ``Cache-control: public''
5205 in the response header. Doing this VIOLATES the HTTP standard.
5206 Enabling this feature could make you liable for problems which
5209 refresh-ims causes squid to contact the origin server
5210 when a client issues an If-Modified-Since request. This
5211 ensures that the client will receive an updated version
5212 if one is available.
5214 store-stale stores responses even if they don't have explicit
5215 freshness or a validator (i.e., Last-Modified or an ETag)
5216 present, or if they're already stale. By default, Squid will
5217 not cache such responses because they usually can't be
5218 reused. Note that such responses will be stale by default.
5220 max-stale=NN provide a maximum staleness factor. Squid won't
5221 serve objects more stale than this even if it failed to
5222 validate the object. Default: use the max_stale global limit.
5224 Basically a cached object is:
5226 FRESH if expires < now, else STALE
5228 FRESH if lm-factor < percent, else STALE
5232 The refresh_pattern lines are checked in the order listed here.
5233 The first entry which matches is used. If none of the entries
5234 match the default will be used.
5236 Note, you must uncomment all the default lines if you want
5237 to change one. The default setting is only active if none is
5243 # Add any of your own refresh_pattern entries above these.
5245 refresh_pattern ^ftp: 1440 20% 10080
5246 refresh_pattern ^gopher: 1440 0% 1440
5247 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
5248 refresh_pattern . 0 20% 4320
5252 NAME: quick_abort_min
5256 LOC: Config.quickAbort.min
5259 NAME: quick_abort_max
5263 LOC: Config.quickAbort.max
5266 NAME: quick_abort_pct
5270 LOC: Config.quickAbort.pct
5272 The cache by default continues downloading aborted requests
5273 which are almost completed (less than 16 KB remaining). This
5274 may be undesirable on slow (e.g. SLIP) links and/or very busy
5275 caches. Impatient users may tie up file descriptors and
5276 bandwidth by repeatedly requesting and immediately aborting
5279 When the user aborts a request, Squid will check the
5280 quick_abort values to the amount of data transferred until
5283 If the transfer has less than 'quick_abort_min' KB remaining,
5284 it will finish the retrieval.
5286 If the transfer has more than 'quick_abort_max' KB remaining,
5287 it will abort the retrieval.
5289 If more than 'quick_abort_pct' of the transfer has completed,
5290 it will finish the retrieval.
5292 If you do not want any retrieval to continue after the client
5293 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
5296 If you want retrievals to always continue if they are being
5297 cached set 'quick_abort_min' to '-1 KB'.
5300 NAME: read_ahead_gap
5301 COMMENT: buffer-size
5303 LOC: Config.readAheadGap
5306 The amount of data the cache will buffer ahead of what has been
5307 sent to the client when retrieving an object from another server.
5311 IFDEF: USE_HTTP_VIOLATIONS
5314 LOC: Config.negativeTtl
5317 Set the Default Time-to-Live (TTL) for failed requests.
5318 Certain types of failures (such as "connection refused" and
5319 "404 Not Found") are able to be negatively-cached for a short time.
5320 Modern web servers should provide Expires: header, however if they
5321 do not this can provide a minimum TTL.
5322 The default is not to cache errors with unknown expiry details.
5324 Note that this is different from negative caching of DNS lookups.
5326 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5327 this feature could make you liable for problems which it
5331 NAME: positive_dns_ttl
5334 LOC: Config.positiveDnsTtl
5337 Upper limit on how long Squid will cache positive DNS responses.
5338 Default is 6 hours (360 minutes). This directive must be set
5339 larger than negative_dns_ttl.
5342 NAME: negative_dns_ttl
5345 LOC: Config.negativeDnsTtl
5348 Time-to-Live (TTL) for negative caching of failed DNS lookups.
5349 This also sets the lower cache limit on positive lookups.
5350 Minimum value is 1 second, and it is not recommendable to go
5351 much below 10 seconds.
5354 NAME: range_offset_limit
5355 COMMENT: size [acl acl...]
5357 LOC: Config.rangeOffsetLimit
5360 usage: (size) [units] [[!]aclname]
5362 Sets an upper limit on how far (number of bytes) into the file
5363 a Range request may be to cause Squid to prefetch the whole file.
5364 If beyond this limit, Squid forwards the Range request as it is and
5365 the result is NOT cached.
5367 This is to stop a far ahead range request (lets say start at 17MB)
5368 from making Squid fetch the whole object up to that point before
5369 sending anything to the client.
5371 Multiple range_offset_limit lines may be specified, and they will
5372 be searched from top to bottom on each request until a match is found.
5373 The first match found will be used. If no line matches a request, the
5374 default limit of 0 bytes will be used.
5376 'size' is the limit specified as a number of units.
5378 'units' specifies whether to use bytes, KB, MB, etc.
5379 If no units are specified bytes are assumed.
5381 A size of 0 causes Squid to never fetch more than the
5382 client requested. (default)
5384 A size of 'none' causes Squid to always fetch the object from the
5385 beginning so it may cache the result. (2.0 style)
5387 'aclname' is the name of a defined ACL.
5389 NP: Using 'none' as the byte value here will override any quick_abort settings
5390 that may otherwise apply to the range request. The range request will
5391 be fully fetched from start to finish regardless of the client
5392 actions. This affects bandwidth usage.
5395 NAME: minimum_expiry_time
5398 LOC: Config.minimum_expiry_time
5401 The minimum caching time according to (Expires - Date)
5402 headers Squid honors if the object can't be revalidated.
5403 The default is 60 seconds.
5405 In reverse proxy environments it might be desirable to honor
5406 shorter object lifetimes. It is most likely better to make
5407 your server return a meaningful Last-Modified header however.
5409 In ESI environments where page fragments often have short
5410 lifetimes, this will often be best set to 0.
5413 NAME: store_avg_object_size
5417 LOC: Config.Store.avgObjectSize
5419 Average object size, used to estimate number of objects your
5420 cache can hold. The default is 13 KB.
5422 This is used to pre-seed the cache index memory allocation to
5423 reduce expensive reallocate operations while handling clients
5424 traffic. Too-large values may result in memory allocation during
5425 peak traffic, too-small values will result in wasted memory.
5427 Check the cache manager 'info' report metrics for the real
5428 object sizes seen by your Squid before tuning this.
5431 NAME: store_objects_per_bucket
5434 LOC: Config.Store.objectsPerBucket
5436 Target number of objects per bucket in the store hash table.
5437 Lowering this value increases the total number of buckets and
5438 also the storage maintenance rate. The default is 20.
5443 -----------------------------------------------------------------------------
5446 NAME: request_header_max_size
5450 LOC: Config.maxRequestHeaderSize
5452 This specifies the maximum size for HTTP headers in a request.
5453 Request headers are usually relatively small (about 512 bytes).
5454 Placing a limit on the request header size will catch certain
5455 bugs (for example with persistent connections) and possibly
5456 buffer-overflow or denial-of-service attacks.
5459 NAME: reply_header_max_size
5463 LOC: Config.maxReplyHeaderSize
5465 This specifies the maximum size for HTTP headers in a reply.
5466 Reply headers are usually relatively small (about 512 bytes).
5467 Placing a limit on the reply header size will catch certain
5468 bugs (for example with persistent connections) and possibly
5469 buffer-overflow or denial-of-service attacks.
5472 NAME: request_body_max_size
5476 DEFAULT_DOC: No limit.
5477 LOC: Config.maxRequestBodySize
5479 This specifies the maximum size for an HTTP request body.
5480 In other words, the maximum size of a PUT/POST request.
5481 A user who attempts to send a request with a body larger
5482 than this limit receives an "Invalid Request" error message.
5483 If you set this parameter to a zero (the default), there will
5484 be no limit imposed.
5486 See also client_request_buffer_max_size for an alternative
5487 limitation on client uploads which can be configured.
5490 NAME: client_request_buffer_max_size
5494 LOC: Config.maxRequestBufferSize
5496 This specifies the maximum buffer size of a client request.
5497 It prevents squid eating too much memory when somebody uploads
5501 NAME: chunked_request_body_max_size
5505 LOC: Config.maxChunkedRequestBodySize
5507 A broken or confused HTTP/1.1 client may send a chunked HTTP
5508 request to Squid. Squid does not have full support for that
5509 feature yet. To cope with such requests, Squid buffers the
5510 entire request and then dechunks request body to create a
5511 plain HTTP/1.0 request with a known content length. The plain
5512 request is then used by the rest of Squid code as usual.
5514 The option value specifies the maximum size of the buffer used
5515 to hold the request before the conversion. If the chunked
5516 request size exceeds the specified limit, the conversion
5517 fails, and the client receives an "unsupported request" error,
5518 as if dechunking was disabled.
5520 Dechunking is enabled by default. To disable conversion of
5521 chunked requests, set the maximum to zero.
5523 Request dechunking feature and this option in particular are a
5524 temporary hack. When chunking requests and responses are fully
5525 supported, there will be no need to buffer a chunked request.
5529 IFDEF: USE_HTTP_VIOLATIONS
5532 DEFAULT_DOC: Obey RFC 2616.
5533 LOC: Config.accessList.brokenPosts
5535 A list of ACL elements which, if matched, causes Squid to send
5536 an extra CRLF pair after the body of a PUT/POST request.
5538 Some HTTP servers has broken implementations of PUT/POST,
5539 and rely on an extra CRLF pair sent by some WWW clients.
5541 Quote from RFC2616 section 4.1 on this matter:
5543 Note: certain buggy HTTP/1.0 client implementations generate an
5544 extra CRLF's after a POST request. To restate what is explicitly
5545 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
5546 a request with an extra CRLF.
5548 This clause only supports fast acl types.
5549 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5552 acl buggy_server url_regex ^http://....
5553 broken_posts allow buggy_server
5556 NAME: adaptation_uses_indirect_client icap_uses_indirect_client
5559 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION
5561 LOC: Adaptation::Config::use_indirect_client
5563 Controls whether the indirect client IP address (instead of the direct
5564 client IP address) is passed to adaptation services.
5566 See also: follow_x_forwarded_for adaptation_send_client_ip
5570 IFDEF: USE_HTTP_VIOLATIONS
5574 LOC: Config.onoff.via
5576 If set (default), Squid will include a Via header in requests and
5577 replies as required by RFC2616.
5583 LOC: Config.onoff.ie_refresh
5586 Microsoft Internet Explorer up until version 5.5 Service
5587 Pack 1 has an issue with transparent proxies, wherein it
5588 is impossible to force a refresh. Turning this on provides
5589 a partial fix to the problem, by causing all IMS-REFRESH
5590 requests from older IE versions to check the origin server
5591 for fresh content. This reduces hit ratio by some amount
5592 (~10% in my experience), but allows users to actually get
5593 fresh content when they want it. Note because Squid
5594 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
5595 of 5.5 is unchanged from old versions of Squid (i.e. a
5596 forced refresh is impossible). Newer versions of IE will,
5597 hopefully, continue to have the new behavior and will be
5598 handled based on that assumption. This option defaults to
5599 the old Squid behavior, which is better for hit ratios but
5600 worse for clients using IE, if they need to be able to
5601 force fresh content.
5604 NAME: vary_ignore_expire
5607 LOC: Config.onoff.vary_ignore_expire
5610 Many HTTP servers supporting Vary gives such objects
5611 immediate expiry time with no cache-control header
5612 when requested by a HTTP/1.0 client. This option
5613 enables Squid to ignore such expiry times until
5614 HTTP/1.1 is fully implemented.
5616 WARNING: If turned on this may eventually cause some
5617 varying objects not intended for caching to get cached.
5620 NAME: request_entities
5622 LOC: Config.onoff.request_entities
5625 Squid defaults to deny GET and HEAD requests with request entities,
5626 as the meaning of such requests are undefined in the HTTP standard
5627 even if not explicitly forbidden.
5629 Set this directive to on if you have clients which insists
5630 on sending request entities in GET or HEAD requests. But be warned
5631 that there is server software (both proxies and web servers) which
5632 can fail to properly process this kind of request which may make you
5633 vulnerable to cache pollution attacks if enabled.
5636 NAME: request_header_access
5637 IFDEF: USE_HTTP_VIOLATIONS
5638 TYPE: http_header_access
5639 LOC: Config.request_header_access
5641 DEFAULT_DOC: No limits.
5643 Usage: request_header_access header_name allow|deny [!]aclname ...
5645 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5646 this feature could make you liable for problems which it
5649 This option replaces the old 'anonymize_headers' and the
5650 older 'http_anonymizer' option with something that is much
5651 more configurable. A list of ACLs for each header name allows
5652 removal of specific header fields under specific conditions.
5654 This option only applies to outgoing HTTP request headers (i.e.,
5655 headers sent by Squid to the next HTTP hop such as a cache peer
5656 or an origin server). The option has no effect during cache hit
5657 detection. The equivalent adaptation vectoring point in ICAP
5658 terminology is post-cache REQMOD.
5660 The option is applied to individual outgoing request header
5661 fields. For each request header field F, Squid uses the first
5662 qualifying sets of request_header_access rules:
5664 1. Rules with header_name equal to F's name.
5665 2. Rules with header_name 'Other', provided F's name is not
5666 on the hard-coded list of commonly used HTTP header names.
5667 3. Rules with header_name 'All'.
5669 Within that qualifying rule set, rule ACLs are checked as usual.
5670 If ACLs of an "allow" rule match, the header field is allowed to
5671 go through as is. If ACLs of a "deny" rule match, the header is
5672 removed and request_header_replace is then checked to identify
5673 if the removed header has a replacement. If no rules within the
5674 set have matching ACLs, the header field is left as is.
5676 For example, to achieve the same behavior as the old
5677 'http_anonymizer standard' option, you should use:
5679 request_header_access From deny all
5680 request_header_access Referer deny all
5681 request_header_access User-Agent deny all
5683 Or, to reproduce the old 'http_anonymizer paranoid' feature
5686 request_header_access Authorization allow all
5687 request_header_access Proxy-Authorization allow all
5688 request_header_access Cache-Control allow all
5689 request_header_access Content-Length allow all
5690 request_header_access Content-Type allow all
5691 request_header_access Date allow all
5692 request_header_access Host allow all
5693 request_header_access If-Modified-Since allow all
5694 request_header_access Pragma allow all
5695 request_header_access Accept allow all
5696 request_header_access Accept-Charset allow all
5697 request_header_access Accept-Encoding allow all
5698 request_header_access Accept-Language allow all
5699 request_header_access Connection allow all
5700 request_header_access All deny all
5702 HTTP reply headers are controlled with the reply_header_access directive.
5704 By default, all headers are allowed (no anonymizing is performed).
5707 NAME: reply_header_access
5708 IFDEF: USE_HTTP_VIOLATIONS
5709 TYPE: http_header_access
5710 LOC: Config.reply_header_access
5712 DEFAULT_DOC: No limits.
5714 Usage: reply_header_access header_name allow|deny [!]aclname ...
5716 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5717 this feature could make you liable for problems which it
5720 This option only applies to reply headers, i.e., from the
5721 server to the client.
5723 This is the same as request_header_access, but in the other
5724 direction. Please see request_header_access for detailed
5727 For example, to achieve the same behavior as the old
5728 'http_anonymizer standard' option, you should use:
5730 reply_header_access Server deny all
5731 reply_header_access WWW-Authenticate deny all
5732 reply_header_access Link deny all
5734 Or, to reproduce the old 'http_anonymizer paranoid' feature
5737 reply_header_access Allow allow all
5738 reply_header_access WWW-Authenticate allow all
5739 reply_header_access Proxy-Authenticate allow all
5740 reply_header_access Cache-Control allow all
5741 reply_header_access Content-Encoding allow all
5742 reply_header_access Content-Length allow all
5743 reply_header_access Content-Type allow all
5744 reply_header_access Date allow all
5745 reply_header_access Expires allow all
5746 reply_header_access Last-Modified allow all
5747 reply_header_access Location allow all
5748 reply_header_access Pragma allow all
5749 reply_header_access Content-Language allow all
5750 reply_header_access Retry-After allow all
5751 reply_header_access Title allow all
5752 reply_header_access Content-Disposition allow all
5753 reply_header_access Connection allow all
5754 reply_header_access All deny all
5756 HTTP request headers are controlled with the request_header_access directive.
5758 By default, all headers are allowed (no anonymizing is
5762 NAME: request_header_replace header_replace
5763 IFDEF: USE_HTTP_VIOLATIONS
5764 TYPE: http_header_replace
5765 LOC: Config.request_header_access
5768 Usage: request_header_replace header_name message
5769 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
5771 This option allows you to change the contents of headers
5772 denied with request_header_access above, by replacing them
5773 with some fixed string.
5775 This only applies to request headers, not reply headers.
5777 By default, headers are removed if denied.
5780 NAME: reply_header_replace
5781 IFDEF: USE_HTTP_VIOLATIONS
5782 TYPE: http_header_replace
5783 LOC: Config.reply_header_access
5786 Usage: reply_header_replace header_name message
5787 Example: reply_header_replace Server Foo/1.0
5789 This option allows you to change the contents of headers
5790 denied with reply_header_access above, by replacing them
5791 with some fixed string.
5793 This only applies to reply headers, not request headers.
5795 By default, headers are removed if denied.
5798 NAME: request_header_add
5799 TYPE: HeaderWithAclList
5800 LOC: Config.request_header_add
5803 Usage: request_header_add field-name field-value acl1 [acl2] ...
5804 Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
5806 This option adds header fields to outgoing HTTP requests (i.e.,
5807 request headers sent by Squid to the next HTTP hop such as a
5808 cache peer or an origin server). The option has no effect during
5809 cache hit detection. The equivalent adaptation vectoring point
5810 in ICAP terminology is post-cache REQMOD.
5812 Field-name is a token specifying an HTTP header name. If a
5813 standard HTTP header name is used, Squid does not check whether
5814 the new header conflicts with any existing headers or violates
5815 HTTP rules. If the request to be modified already contains a
5816 field with the same name, the old field is preserved but the
5817 header field values are not merged.
5819 Field-value is either a token or a quoted string. If quoted
5820 string format is used, then the surrounding quotes are removed
5821 while escape sequences and %macros are processed.
5823 In theory, all of the logformat codes can be used as %macros.
5824 However, unlike logging (which happens at the very end of
5825 transaction lifetime), the transaction may not yet have enough
5826 information to expand a macro when the new header value is needed.
5827 And some information may already be available to Squid but not yet
5828 committed where the macro expansion code can access it (report
5829 such instances!). The macro will be expanded into a single dash
5830 ('-') in such cases. Not all macros have been tested.
5832 One or more Squid ACLs may be specified to restrict header
5833 injection to matching requests. As always in squid.conf, all
5834 ACLs in an option ACL list must be satisfied for the insertion
5835 to happen. The request_header_add option supports fast ACLs
5844 This option used to log custom information about the master
5845 transaction. For example, an admin may configure Squid to log
5846 which "user group" the transaction belongs to, where "user group"
5847 will be determined based on a set of ACLs and not [just]
5848 authentication information.
5849 Values of key/value pairs can be logged using %{key}note macros:
5851 note key value acl ...
5852 logformat myFormat ... %{key}note ...
5855 NAME: relaxed_header_parser
5856 COMMENT: on|off|warn
5858 LOC: Config.onoff.relaxed_header_parser
5861 In the default "on" setting Squid accepts certain forms
5862 of non-compliant HTTP messages where it is unambiguous
5863 what the sending application intended even if the message
5864 is not correctly formatted. The messages is then normalized
5865 to the correct form when forwarded by Squid.
5867 If set to "warn" then a warning will be emitted in cache.log
5868 each time such HTTP error is encountered.
5870 If set to "off" then such HTTP errors will cause the request
5871 or response to be rejected.
5874 NAME: collapsed_forwarding
5877 LOC: Config.onoff.collapsed_forwarding
5880 This option controls whether Squid is allowed to merge multiple
5881 potentially cachable requests for the same URI before Squid knows
5882 whether the response is going to be cachable.
5884 This feature is disabled by default: Enabling collapsed forwarding
5885 needlessly delays forwarding requests that look cachable (when they are
5886 collapsed) but then need to be forwarded individually anyway because
5887 they end up being for uncachable content. However, in some cases, such
5888 as accelleration of highly cachable content with periodic or groupped
5889 expiration times, the gains from collapsing [large volumes of
5890 simultenous refresh requests] outweigh losses from such delays.
5895 -----------------------------------------------------------------------------
5898 NAME: forward_timeout
5901 LOC: Config.Timeout.forward
5904 This parameter specifies how long Squid should at most attempt in
5905 finding a forwarding path for the request before giving up.
5908 NAME: connect_timeout
5911 LOC: Config.Timeout.connect
5914 This parameter specifies how long to wait for the TCP connect to
5915 the requested server or peer to complete before Squid should
5916 attempt to find another path where to forward the request.
5919 NAME: peer_connect_timeout
5922 LOC: Config.Timeout.peer_connect
5925 This parameter specifies how long to wait for a pending TCP
5926 connection to a peer cache. The default is 30 seconds. You
5927 may also set different timeout values for individual neighbors
5928 with the 'connect-timeout' option on a 'cache_peer' line.
5934 LOC: Config.Timeout.read
5937 The read_timeout is applied on server-side connections. After
5938 each successful read(), the timeout will be extended by this
5939 amount. If no data is read again after this amount of time,
5940 the request is aborted and logged with ERR_READ_TIMEOUT. The
5941 default is 15 minutes.
5947 LOC: Config.Timeout.write
5950 This timeout is tracked for all connections that have data
5951 available for writing and are waiting for the socket to become
5952 ready. After each successful write, the timeout is extended by
5953 the configured amount. If Squid has data to write but the
5954 connection is not ready for the configured duration, the
5955 transaction associated with the connection is terminated. The
5956 default is 15 minutes.
5959 NAME: request_timeout
5961 LOC: Config.Timeout.request
5964 How long to wait for complete HTTP request headers after initial
5965 connection establishment.
5968 NAME: client_idle_pconn_timeout persistent_request_timeout
5970 LOC: Config.Timeout.clientIdlePconn
5973 How long to wait for the next HTTP request on a persistent
5974 client connection after the previous request completes.
5977 NAME: ftp_client_idle_timeout
5979 LOC: Config.Timeout.ftpClientIdle
5982 How long to wait for an FTP request on a connection to Squid ftp_port.
5983 Many FTP clients do not deal with idle connection closures well,
5984 necessitating a longer default timeout than client_idle_pconn_timeout
5985 used for incoming HTTP requests.
5988 NAME: client_lifetime
5991 LOC: Config.Timeout.lifetime
5994 The maximum amount of time a client (browser) is allowed to
5995 remain connected to the cache process. This protects the Cache
5996 from having a lot of sockets (and hence file descriptors) tied up
5997 in a CLOSE_WAIT state from remote clients that go away without
5998 properly shutting down (either because of a network failure or
5999 because of a poor client implementation). The default is one
6002 NOTE: The default value is intended to be much larger than any
6003 client would ever need to be connected to your cache. You
6004 should probably change client_lifetime only as a last resort.
6005 If you seem to have many client connections tying up
6006 filedescriptors, we recommend first tuning the read_timeout,
6007 request_timeout, persistent_request_timeout and quick_abort values.
6010 NAME: half_closed_clients
6012 LOC: Config.onoff.half_closed_clients
6015 Some clients may shutdown the sending side of their TCP
6016 connections, while leaving their receiving sides open. Sometimes,
6017 Squid can not tell the difference between a half-closed and a
6018 fully-closed TCP connection.
6020 By default, Squid will immediately close client connections when
6021 read(2) returns "no more data to read."
6023 Change this option to 'on' and Squid will keep open connections
6024 until a read(2) or write(2) on the socket returns an error.
6025 This may show some benefits for reverse proxies. But if not
6026 it is recommended to leave OFF.
6029 NAME: server_idle_pconn_timeout pconn_timeout
6031 LOC: Config.Timeout.serverIdlePconn
6034 Timeout for idle persistent connections to servers and other
6041 LOC: Ident::TheConfig.timeout
6044 Maximum time to wait for IDENT lookups to complete.
6046 If this is too high, and you enabled IDENT lookups from untrusted
6047 users, you might be susceptible to denial-of-service by having
6048 many ident requests going at once.
6051 NAME: shutdown_lifetime
6054 LOC: Config.shutdownLifetime
6057 When SIGTERM or SIGHUP is received, the cache is put into
6058 "shutdown pending" mode until all active sockets are closed.
6059 This value is the lifetime to set for all open descriptors
6060 during shutdown mode. Any active clients after this many
6061 seconds will receive a 'timeout' message.
6065 ADMINISTRATIVE PARAMETERS
6066 -----------------------------------------------------------------------------
6072 LOC: Config.adminEmail
6074 Email-address of local cache manager who will receive
6075 mail if the cache dies. The default is "webmaster".
6081 LOC: Config.EmailFrom
6083 From: email-address for mail sent when the cache dies.
6084 The default is to use 'squid@unique_hostname'.
6086 See also: unique_hostname directive.
6092 LOC: Config.EmailProgram
6094 Email program used to send mail if the cache dies.
6095 The default is "mail". The specified program must comply
6096 with the standard Unix mail syntax:
6097 mail-program recipient < mailfile
6099 Optional command line options can be specified.
6102 NAME: cache_effective_user
6104 DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
6105 LOC: Config.effectiveUser
6107 If you start Squid as root, it will change its effective/real
6108 UID/GID to the user specified below. The default is to change
6109 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
6110 see also; cache_effective_group
6113 NAME: cache_effective_group
6116 DEFAULT_DOC: Use system group memberships of the cache_effective_user account
6117 LOC: Config.effectiveGroup
6119 Squid sets the GID to the effective user's default group ID
6120 (taken from the password file) and supplementary group list
6121 from the groups membership.
6123 If you want Squid to run with a specific GID regardless of
6124 the group memberships of the effective user then set this
6125 to the group (or GID) you want Squid to run as. When set
6126 all other group privileges of the effective user are ignored
6127 and only this GID is effective. If Squid is not started as
6128 root the user starting Squid MUST be member of the specified
6131 This option is not recommended by the Squid Team.
6132 Our preference is for administrators to configure a secure
6133 user account for squid with UID/GID matching system policies.
6136 NAME: httpd_suppress_version_string
6140 LOC: Config.onoff.httpd_suppress_version_string
6142 Suppress Squid version string info in HTTP headers and HTML error pages.
6145 NAME: visible_hostname
6147 LOC: Config.visibleHostname
6149 DEFAULT_DOC: Automatically detect the system host name
6151 If you want to present a special hostname in error messages, etc,
6152 define this. Otherwise, the return value of gethostname()
6153 will be used. If you have multiple caches in a cluster and
6154 get errors about IP-forwarding you must set them to have individual
6155 names with this setting.
6158 NAME: unique_hostname
6160 LOC: Config.uniqueHostname
6162 DEFAULT_DOC: Copy the value from visible_hostname
6164 If you want to have multiple machines with the same
6165 'visible_hostname' you must give each machine a different
6166 'unique_hostname' so forwarding loops can be detected.
6169 NAME: hostname_aliases
6171 LOC: Config.hostnameAliases
6174 A list of other DNS names your cache has.
6182 Minimum umask which should be enforced while the proxy
6183 is running, in addition to the umask set at startup.
6185 For a traditional octal representation of umasks, start
6190 OPTIONS FOR THE CACHE REGISTRATION SERVICE
6191 -----------------------------------------------------------------------------
6193 This section contains parameters for the (optional) cache
6194 announcement service. This service is provided to help
6195 cache administrators locate one another in order to join or
6196 create cache hierarchies.
6198 An 'announcement' message is sent (via UDP) to the registration
6199 service by Squid. By default, the announcement message is NOT
6200 SENT unless you enable it with 'announce_period' below.
6202 The announcement message includes your hostname, plus the
6203 following information from this configuration file:
6209 All current information is processed regularly and made
6210 available on the Web at http://www.ircache.net/Cache/Tracker/.
6213 NAME: announce_period
6215 LOC: Config.Announce.period
6217 DEFAULT_DOC: Announcement messages disabled.
6219 This is how frequently to send cache announcements.
6221 To enable announcing your cache, just set an announce period.
6224 announce_period 1 day
6229 DEFAULT: tracker.ircache.net
6230 LOC: Config.Announce.host
6232 Set the hostname where announce registration messages will be sent.
6234 See also announce_port and announce_file
6240 LOC: Config.Announce.file
6242 The contents of this file will be included in the announce
6243 registration messages.
6249 LOC: Config.Announce.port
6251 Set the port where announce registration messages will be sent.
6253 See also announce_host and announce_file
6257 HTTPD-ACCELERATOR OPTIONS
6258 -----------------------------------------------------------------------------
6261 NAME: httpd_accel_surrogate_id
6264 DEFAULT_DOC: visible_hostname is used if no specific ID is set.
6265 LOC: Config.Accel.surrogate_id
6267 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
6268 need an identification token to allow control targeting. Because
6269 a farm of surrogates may all perform the same tasks, they may share
6270 an identification token.
6273 NAME: http_accel_surrogate_remote
6277 LOC: Config.onoff.surrogate_is_remote
6279 Remote surrogates (such as those in a CDN) honour the header
6280 "Surrogate-Control: no-store-remote".
6282 Set this to on to have squid behave as a remote surrogate.
6286 IFDEF: USE_SQUID_ESI
6287 COMMENT: libxml2|expat|custom
6289 LOC: ESIParser::Type
6292 ESI markup is not strictly XML compatible. The custom ESI parser
6293 will give higher performance, but cannot handle non ASCII character
6298 DELAY POOL PARAMETERS
6299 -----------------------------------------------------------------------------
6303 TYPE: delay_pool_count
6305 IFDEF: USE_DELAY_POOLS
6308 This represents the number of delay pools to be used. For example,
6309 if you have one class 2 delay pool and one class 3 delays pool, you
6310 have a total of 2 delay pools.
6312 See also delay_parameters, delay_class, delay_access for pool
6313 configuration details.
6317 TYPE: delay_pool_class
6319 IFDEF: USE_DELAY_POOLS
6322 This defines the class of each delay pool. There must be exactly one
6323 delay_class line for each delay pool. For example, to define two
6324 delay pools, one of class 2 and one of class 3, the settings above
6328 delay_pools 4 # 4 delay pools
6329 delay_class 1 2 # pool 1 is a class 2 pool
6330 delay_class 2 3 # pool 2 is a class 3 pool
6331 delay_class 3 4 # pool 3 is a class 4 pool
6332 delay_class 4 5 # pool 4 is a class 5 pool
6334 The delay pool classes are:
6336 class 1 Everything is limited by a single aggregate
6339 class 2 Everything is limited by a single aggregate
6340 bucket as well as an "individual" bucket chosen
6341 from bits 25 through 32 of the IPv4 address.
6343 class 3 Everything is limited by a single aggregate
6344 bucket as well as a "network" bucket chosen
6345 from bits 17 through 24 of the IP address and a
6346 "individual" bucket chosen from bits 17 through
6347 32 of the IPv4 address.
6349 class 4 Everything in a class 3 delay pool, with an
6350 additional limit on a per user basis. This
6351 only takes effect if the username is established
6352 in advance - by forcing authentication in your
6355 class 5 Requests are grouped according their tag (see
6356 external_acl's tag= reply).
6359 Each pool also requires a delay_parameters directive to configure the pool size
6360 and speed limits used whenever the pool is applied to a request. Along with
6361 a set of delay_access directives to determine when it is used.
6363 NOTE: If an IP address is a.b.c.d
6364 -> bits 25 through 32 are "d"
6365 -> bits 17 through 24 are "c"
6366 -> bits 17 through 32 are "c * 256 + d"
6368 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
6369 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
6371 This clause only supports fast acl types.
6372 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6374 See also delay_parameters and delay_access.
6378 TYPE: delay_pool_access
6380 DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool.
6381 IFDEF: USE_DELAY_POOLS
6384 This is used to determine which delay pool a request falls into.
6386 delay_access is sorted per pool and the matching starts with pool 1,
6387 then pool 2, ..., and finally pool N. The first delay pool where the
6388 request is allowed is selected for the request. If it does not allow
6389 the request to any pool then the request is not delayed (default).
6391 For example, if you want some_big_clients in delay
6392 pool 1 and lotsa_little_clients in delay pool 2:
6394 delay_access 1 allow some_big_clients
6395 delay_access 1 deny all
6396 delay_access 2 allow lotsa_little_clients
6397 delay_access 2 deny all
6398 delay_access 3 allow authenticated_clients
6400 See also delay_parameters and delay_class.
6404 NAME: delay_parameters
6405 TYPE: delay_pool_rates
6407 IFDEF: USE_DELAY_POOLS
6410 This defines the parameters for a delay pool. Each delay pool has
6411 a number of "buckets" associated with it, as explained in the
6412 description of delay_class.
6414 For a class 1 delay pool, the syntax is:
6416 delay_parameters pool aggregate
6418 For a class 2 delay pool:
6420 delay_parameters pool aggregate individual
6422 For a class 3 delay pool:
6424 delay_parameters pool aggregate network individual
6426 For a class 4 delay pool:
6428 delay_parameters pool aggregate network individual user
6430 For a class 5 delay pool:
6432 delay_parameters pool tagrate
6434 The option variables are:
6436 pool a pool number - ie, a number between 1 and the
6437 number specified in delay_pools as used in
6440 aggregate the speed limit parameters for the aggregate bucket
6443 individual the speed limit parameters for the individual
6444 buckets (class 2, 3).
6446 network the speed limit parameters for the network buckets
6449 user the speed limit parameters for the user buckets
6452 tagrate the speed limit parameters for the tag buckets
6455 A pair of delay parameters is written restore/maximum, where restore is
6456 the number of bytes (not bits - modem and network speeds are usually
6457 quoted in bits) per second placed into the bucket, and maximum is the
6458 maximum number of bytes which can be in the bucket at any time.
6460 There must be one delay_parameters line for each delay pool.
6463 For example, if delay pool number 1 is a class 2 delay pool as in the
6464 above example, and is being used to strictly limit each host to 64Kbit/sec
6465 (plus overheads), with no overall limit, the line is:
6467 delay_parameters 1 -1/-1 8000/8000
6469 Note that 8 x 8000 KByte/sec -> 64Kbit/sec.
6471 Note that the figure -1 is used to represent "unlimited".
6474 And, if delay pool number 2 is a class 3 delay pool as in the above
6475 example, and you want to limit it to a total of 256Kbit/sec (strict limit)
6476 with each 8-bit network permitted 64Kbit/sec (strict limit) and each
6477 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits
6478 to permit a decent web page to be downloaded at a decent speed
6479 (if the network is not being limited due to overuse) but slow down
6480 large downloads more significantly:
6482 delay_parameters 2 32000/32000 8000/8000 600/8000
6484 Note that 8 x 32000 KByte/sec -> 256Kbit/sec.
6485 8 x 8000 KByte/sec -> 64Kbit/sec.
6486 8 x 600 Byte/sec -> 4800bit/sec.
6489 Finally, for a class 4 delay pool as in the example - each user will
6490 be limited to 128Kbits/sec no matter how many workstations they are logged into.:
6492 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
6495 See also delay_class and delay_access.
6499 NAME: delay_initial_bucket_level
6500 COMMENT: (percent, 0-100)
6503 IFDEF: USE_DELAY_POOLS
6504 LOC: Config.Delay.initial
6506 The initial bucket percentage is used to determine how much is put
6507 in each bucket when squid starts, is reconfigured, or first notices
6508 a host accessing it (in class 2 and class 3, individual hosts and
6509 networks only have buckets associated with them once they have been
6514 CLIENT DELAY POOL PARAMETERS
6515 -----------------------------------------------------------------------------
6518 NAME: client_delay_pools
6519 TYPE: client_delay_pool_count
6521 IFDEF: USE_DELAY_POOLS
6522 LOC: Config.ClientDelay
6524 This option specifies the number of client delay pools used. It must
6525 preceed other client_delay_* options.
6528 client_delay_pools 2
6530 See also client_delay_parameters and client_delay_access.
6533 NAME: client_delay_initial_bucket_level
6534 COMMENT: (percent, 0-no_limit)
6537 IFDEF: USE_DELAY_POOLS
6538 LOC: Config.ClientDelay.initial
6540 This option determines the initial bucket size as a percentage of
6541 max_bucket_size from client_delay_parameters. Buckets are created
6542 at the time of the "first" connection from the matching IP. Idle
6543 buckets are periodically deleted up.
6545 You can specify more than 100 percent but note that such "oversized"
6546 buckets are not refilled until their size goes down to max_bucket_size
6547 from client_delay_parameters.
6550 client_delay_initial_bucket_level 50
6553 NAME: client_delay_parameters
6554 TYPE: client_delay_pool_rates
6556 IFDEF: USE_DELAY_POOLS
6557 LOC: Config.ClientDelay
6560 This option configures client-side bandwidth limits using the
6563 client_delay_parameters pool speed_limit max_bucket_size
6565 pool is an integer ID used for client_delay_access matching.
6567 speed_limit is bytes added to the bucket per second.
6569 max_bucket_size is the maximum size of a bucket, enforced after any
6570 speed_limit additions.
6572 Please see the delay_parameters option for more information and
6576 client_delay_parameters 1 1024 2048
6577 client_delay_parameters 2 51200 16384
6579 See also client_delay_access.
6583 NAME: client_delay_access
6584 TYPE: client_delay_pool_access
6586 DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool.
6587 IFDEF: USE_DELAY_POOLS
6588 LOC: Config.ClientDelay
6590 This option determines the client-side delay pool for the
6593 client_delay_access pool_ID allow|deny acl_name
6595 All client_delay_access options are checked in their pool ID
6596 order, starting with pool 1. The first checked pool with allowed
6597 request is selected for the request. If no ACL matches or there
6598 are no client_delay_access options, the request bandwidth is not
6601 The ACL-selected pool is then used to find the
6602 client_delay_parameters for the request. Client-side pools are
6603 not used to aggregate clients. Clients are always aggregated
6604 based on their source IP addresses (one bucket per source IP).
6606 This clause only supports fast acl types.
6607 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6608 Additionally, only the client TCP connection details are available.
6609 ACLs testing HTTP properties will not work.
6611 Please see delay_access for more examples.
6614 client_delay_access 1 allow low_rate_network
6615 client_delay_access 2 allow vips_network
6618 See also client_delay_parameters and client_delay_pools.
6622 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
6623 -----------------------------------------------------------------------------
6628 LOC: Config.Wccp.router
6630 DEFAULT_DOC: WCCP disabled.
6633 Use this option to define your WCCP ``home'' router for
6636 wccp_router supports a single WCCP(v1) router
6638 wccp2_router supports multiple WCCPv2 routers
6640 only one of the two may be used at the same time and defines
6641 which version of WCCP to use.
6645 TYPE: IpAddress_list
6646 LOC: Config.Wccp2.router
6648 DEFAULT_DOC: WCCPv2 disabled.
6651 Use this option to define your WCCP ``home'' router for
6654 wccp_router supports a single WCCP(v1) router
6656 wccp2_router supports multiple WCCPv2 routers
6658 only one of the two may be used at the same time and defines
6659 which version of WCCP to use.
6664 LOC: Config.Wccp.version
6668 This directive is only relevant if you need to set up WCCP(v1)
6669 to some very old and end-of-life Cisco routers. In all other
6670 setups it must be left unset or at the default setting.
6671 It defines an internal version in the WCCP(v1) protocol,
6672 with version 4 being the officially documented protocol.
6674 According to some users, Cisco IOS 11.2 and earlier only
6675 support WCCP version 3. If you're using that or an earlier
6676 version of IOS, you may need to change this value to 3, otherwise
6677 do not specify this parameter.
6680 NAME: wccp2_rebuild_wait
6682 LOC: Config.Wccp2.rebuildwait
6686 If this is enabled Squid will wait for the cache dir rebuild to finish
6687 before sending the first wccp2 HereIAm packet
6690 NAME: wccp2_forwarding_method
6692 LOC: Config.Wccp2.forwarding_method
6696 WCCP2 allows the setting of forwarding methods between the
6697 router/switch and the cache. Valid values are as follows:
6699 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
6700 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
6702 Currently (as of IOS 12.4) cisco routers only support GRE.
6703 Cisco switches only support the L2 redirect assignment method.
6706 NAME: wccp2_return_method
6708 LOC: Config.Wccp2.return_method
6712 WCCP2 allows the setting of return methods between the
6713 router/switch and the cache for packets that the cache
6714 decides not to handle. Valid values are as follows:
6716 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
6717 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
6719 Currently (as of IOS 12.4) cisco routers only support GRE.
6720 Cisco switches only support the L2 redirect assignment.
6722 If the "ip wccp redirect exclude in" command has been
6723 enabled on the cache interface, then it is still safe for
6724 the proxy server to use a l2 redirect method even if this
6725 option is set to GRE.
6728 NAME: wccp2_assignment_method
6730 LOC: Config.Wccp2.assignment_method
6734 WCCP2 allows the setting of methods to assign the WCCP hash
6735 Valid values are as follows:
6737 hash - Hash assignment
6738 mask - Mask assignment
6740 As a general rule, cisco routers support the hash assignment method
6741 and cisco switches support the mask assignment method.
6746 LOC: Config.Wccp2.info
6747 DEFAULT_IF_NONE: standard 0
6748 DEFAULT_DOC: Use the 'web-cache' standard service.
6751 WCCP2 allows for multiple traffic services. There are two
6752 types: "standard" and "dynamic". The standard type defines
6753 one service id - http (id 0). The dynamic service ids can be from
6754 51 to 255 inclusive. In order to use a dynamic service id
6755 one must define the type of traffic to be redirected; this is done
6756 using the wccp2_service_info option.
6758 The "standard" type does not require a wccp2_service_info option,
6759 just specifying the service id will suffice.
6761 MD5 service authentication can be enabled by adding
6762 "password=<password>" to the end of this service declaration.
6766 wccp2_service standard 0 # for the 'web-cache' standard service
6767 wccp2_service dynamic 80 # a dynamic service type which will be
6768 # fleshed out with subsequent options.
6769 wccp2_service standard 0 password=foo
6772 NAME: wccp2_service_info
6773 TYPE: wccp2_service_info
6774 LOC: Config.Wccp2.info
6778 Dynamic WCCPv2 services require further information to define the
6779 traffic you wish to have diverted.
6783 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
6784 priority=<priority> ports=<port>,<port>..
6786 The relevant WCCPv2 flags:
6787 + src_ip_hash, dst_ip_hash
6788 + source_port_hash, dst_port_hash
6789 + src_ip_alt_hash, dst_ip_alt_hash
6790 + src_port_alt_hash, dst_port_alt_hash
6793 The port list can be one to eight entries.
6797 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
6798 priority=240 ports=80
6800 Note: the service id must have been defined by a previous
6801 'wccp2_service dynamic <id>' entry.
6806 LOC: Config.Wccp2.weight
6810 Each cache server gets assigned a set of the destination
6811 hash proportional to their weight.
6816 LOC: Config.Wccp.address
6818 DEFAULT_DOC: Address selected by the operating system.
6821 Use this option if you require WCCPv2 to use a specific
6824 The default behavior is to not bind to any specific address.
6829 LOC: Config.Wccp2.address
6831 DEFAULT_DOC: Address selected by the operating system.
6834 Use this option if you require WCCP to use a specific
6837 The default behavior is to not bind to any specific address.
6841 PERSISTENT CONNECTION HANDLING
6842 -----------------------------------------------------------------------------
6844 Also see "pconn_timeout" in the TIMEOUTS section
6847 NAME: client_persistent_connections
6849 LOC: Config.onoff.client_pconns
6852 Persistent connection support for clients.
6853 Squid uses persistent connections (when allowed). You can use
6854 this option to disable persistent connections with clients.
6857 NAME: server_persistent_connections
6859 LOC: Config.onoff.server_pconns
6862 Persistent connection support for servers.
6863 Squid uses persistent connections (when allowed). You can use
6864 this option to disable persistent connections with servers.
6867 NAME: persistent_connection_after_error
6869 LOC: Config.onoff.error_pconns
6872 With this directive the use of persistent connections after
6873 HTTP errors can be disabled. Useful if you have clients
6874 who fail to handle errors on persistent connections proper.
6877 NAME: detect_broken_pconn
6879 LOC: Config.onoff.detect_broken_server_pconns
6882 Some servers have been found to incorrectly signal the use
6883 of HTTP/1.0 persistent connections even on replies not
6884 compatible, causing significant delays. This server problem
6885 has mostly been seen on redirects.
6887 By enabling this directive Squid attempts to detect such
6888 broken replies and automatically assume the reply is finished
6889 after 10 seconds timeout.
6893 CACHE DIGEST OPTIONS
6894 -----------------------------------------------------------------------------
6897 NAME: digest_generation
6898 IFDEF: USE_CACHE_DIGESTS
6900 LOC: Config.onoff.digest_generation
6903 This controls whether the server will generate a Cache Digest
6904 of its contents. By default, Cache Digest generation is
6905 enabled if Squid is compiled with --enable-cache-digests defined.
6908 NAME: digest_bits_per_entry
6909 IFDEF: USE_CACHE_DIGESTS
6911 LOC: Config.digest.bits_per_entry
6914 This is the number of bits of the server's Cache Digest which
6915 will be associated with the Digest entry for a given HTTP
6916 Method and URL (public key) combination. The default is 5.
6919 NAME: digest_rebuild_period
6920 IFDEF: USE_CACHE_DIGESTS
6923 LOC: Config.digest.rebuild_period
6926 This is the wait time between Cache Digest rebuilds.
6929 NAME: digest_rewrite_period
6931 IFDEF: USE_CACHE_DIGESTS
6933 LOC: Config.digest.rewrite_period
6936 This is the wait time between Cache Digest writes to
6940 NAME: digest_swapout_chunk_size
6943 IFDEF: USE_CACHE_DIGESTS
6944 LOC: Config.digest.swapout_chunk_size
6947 This is the number of bytes of the Cache Digest to write to
6948 disk at a time. It defaults to 4096 bytes (4KB), the Squid
6952 NAME: digest_rebuild_chunk_percentage
6953 COMMENT: (percent, 0-100)
6954 IFDEF: USE_CACHE_DIGESTS
6956 LOC: Config.digest.rebuild_chunk_percentage
6959 This is the percentage of the Cache Digest to be scanned at a
6960 time. By default it is set to 10% of the Cache Digest.
6965 -----------------------------------------------------------------------------
6970 LOC: Config.Port.snmp
6972 DEFAULT_DOC: SNMP disabled.
6975 The port number where Squid listens for SNMP requests. To enable
6976 SNMP support set this to a suitable port number. Port number
6977 3401 is often used for the Squid SNMP agent. By default it's
6978 set to "0" (disabled)
6986 LOC: Config.accessList.snmp
6988 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
6991 Allowing or denying access to the SNMP port.
6993 All access to the agent is denied by default.
6996 snmp_access allow|deny [!]aclname ...
6998 This clause only supports fast acl types.
6999 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7002 snmp_access allow snmppublic localhost
7003 snmp_access deny all
7006 NAME: snmp_incoming_address
7008 LOC: Config.Addrs.snmp_incoming
7010 DEFAULT_DOC: Accept SNMP packets from all machine interfaces.
7013 Just like 'udp_incoming_address', but for the SNMP port.
7015 snmp_incoming_address is used for the SNMP socket receiving
7016 messages from SNMP agents.
7018 The default snmp_incoming_address is to listen on all
7019 available network interfaces.
7022 NAME: snmp_outgoing_address
7024 LOC: Config.Addrs.snmp_outgoing
7026 DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system.
7029 Just like 'udp_outgoing_address', but for the SNMP port.
7031 snmp_outgoing_address is used for SNMP packets returned to SNMP
7034 If snmp_outgoing_address is not set it will use the same socket
7035 as snmp_incoming_address. Only change this if you want to have
7036 SNMP replies sent using another address than where this Squid
7037 listens for SNMP queries.
7039 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
7040 the same value since they both use the same port.
7045 -----------------------------------------------------------------------------
7048 NAME: icp_port udp_port
7051 DEFAULT_DOC: ICP disabled.
7052 LOC: Config.Port.icp
7054 The port number where Squid sends and receives ICP queries to
7055 and from neighbor caches. The standard UDP port for ICP is 3130.
7058 icp_port @DEFAULT_ICP_PORT@
7065 DEFAULT_DOC: HTCP disabled.
7066 LOC: Config.Port.htcp
7068 The port number where Squid sends and receives HTCP queries to
7069 and from neighbor caches. To turn it on you want to set it to
7076 NAME: log_icp_queries
7080 LOC: Config.onoff.log_udp
7082 If set, ICP queries are logged to access.log. You may wish
7083 do disable this if your ICP load is VERY high to speed things
7084 up or to simplify log analysis.
7087 NAME: udp_incoming_address
7089 LOC:Config.Addrs.udp_incoming
7091 DEFAULT_DOC: Accept packets from all machine interfaces.
7093 udp_incoming_address is used for UDP packets received from other
7096 The default behavior is to not bind to any specific address.
7098 Only change this if you want to have all UDP queries received on
7099 a specific interface/address.
7101 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
7102 modules. Altering it will affect all of them in the same manner.
7104 see also; udp_outgoing_address
7106 NOTE, udp_incoming_address and udp_outgoing_address can not
7107 have the same value since they both use the same port.
7110 NAME: udp_outgoing_address
7112 LOC: Config.Addrs.udp_outgoing
7114 DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system.
7116 udp_outgoing_address is used for UDP packets sent out to other
7119 The default behavior is to not bind to any specific address.
7121 Instead it will use the same socket as udp_incoming_address.
7122 Only change this if you want to have UDP queries sent using another
7123 address than where this Squid listens for UDP queries from other
7126 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
7127 modules. Altering it will affect all of them in the same manner.
7129 see also; udp_incoming_address
7131 NOTE, udp_incoming_address and udp_outgoing_address can not
7132 have the same value since they both use the same port.
7139 LOC: Config.onoff.icp_hit_stale
7141 If you want to return ICP_HIT for stale cache objects, set this
7142 option to 'on'. If you have sibling relationships with caches
7143 in other administrative domains, this should be 'off'. If you only
7144 have sibling relationships with caches under your control,
7145 it is probably okay to set this to 'on'.
7146 If set to 'on', your siblings should use the option "allow-miss"
7147 on their cache_peer lines for connecting to you.
7150 NAME: minimum_direct_hops
7153 LOC: Config.minDirectHops
7155 If using the ICMP pinging stuff, do direct fetches for sites
7156 which are no more than this many hops away.
7159 NAME: minimum_direct_rtt
7163 LOC: Config.minDirectRtt
7165 If using the ICMP pinging stuff, do direct fetches for sites
7166 which are no more than this many rtt milliseconds away.
7172 LOC: Config.Netdb.low
7174 The low water mark for the ICMP measurement database.
7176 Note: high watermark controlled by netdb_high directive.
7178 These watermarks are counts, not percents. The defaults are
7179 (low) 900 and (high) 1000. When the high water mark is
7180 reached, database entries will be deleted until the low
7187 LOC: Config.Netdb.high
7189 The high water mark for the ICMP measurement database.
7191 Note: low watermark controlled by netdb_low directive.
7193 These watermarks are counts, not percents. The defaults are
7194 (low) 900 and (high) 1000. When the high water mark is
7195 reached, database entries will be deleted until the low
7199 NAME: netdb_ping_period
7201 LOC: Config.Netdb.period
7204 The minimum period for measuring a site. There will be at
7205 least this much delay between successive pings to the same
7206 network. The default is five minutes.
7213 LOC: Config.onoff.query_icmp
7215 If you want to ask your peers to include ICMP data in their ICP
7216 replies, enable this option.
7218 If your peer has configured Squid (during compilation) with
7219 '--enable-icmp' that peer will send ICMP pings to origin server
7220 sites of the URLs it receives. If you enable this option the
7221 ICP replies from that peer will include the ICMP data (if available).
7222 Then, when choosing a parent cache, Squid will choose the parent with
7223 the minimal RTT to the origin server. When this happens, the
7224 hierarchy field of the access.log will be
7225 "CLOSEST_PARENT_MISS". This option is off by default.
7228 NAME: test_reachability
7232 LOC: Config.onoff.test_reachability
7234 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
7235 instead of ICP_MISS if the target host is NOT in the ICMP
7236 database, or has a zero RTT.
7239 NAME: icp_query_timeout
7242 DEFAULT_DOC: Dynamic detection.
7244 LOC: Config.Timeout.icp_query
7246 Normally Squid will automatically determine an optimal ICP
7247 query timeout value based on the round-trip-time of recent ICP
7248 queries. If you want to override the value determined by
7249 Squid, set this 'icp_query_timeout' to a non-zero value. This
7250 value is specified in MILLISECONDS, so, to use a 2-second
7251 timeout (the old default), you would write:
7253 icp_query_timeout 2000
7256 NAME: maximum_icp_query_timeout
7260 LOC: Config.Timeout.icp_query_max
7262 Normally the ICP query timeout is determined dynamically. But
7263 sometimes it can lead to very large values (say 5 seconds).
7264 Use this option to put an upper limit on the dynamic timeout
7265 value. Do NOT use this option to always use a fixed (instead
7266 of a dynamic) timeout value. To set a fixed timeout see the
7267 'icp_query_timeout' directive.
7270 NAME: minimum_icp_query_timeout
7274 LOC: Config.Timeout.icp_query_min
7276 Normally the ICP query timeout is determined dynamically. But
7277 sometimes it can lead to very small timeouts, even lower than
7278 the normal latency variance on your link due to traffic.
7279 Use this option to put an lower limit on the dynamic timeout
7280 value. Do NOT use this option to always use a fixed (instead
7281 of a dynamic) timeout value. To set a fixed timeout see the
7282 'icp_query_timeout' directive.
7285 NAME: background_ping_rate
7289 LOC: Config.backgroundPingRate
7291 Controls how often the ICP pings are sent to siblings that
7292 have background-ping set.
7296 MULTICAST ICP OPTIONS
7297 -----------------------------------------------------------------------------
7302 LOC: Config.mcast_group_list
7305 This tag specifies a list of multicast groups which your server
7306 should join to receive multicasted ICP queries.
7308 NOTE! Be very careful what you put here! Be sure you
7309 understand the difference between an ICP _query_ and an ICP
7310 _reply_. This option is to be set only if you want to RECEIVE
7311 multicast queries. Do NOT set this option to SEND multicast
7312 ICP (use cache_peer for that). ICP replies are always sent via
7313 unicast, so this option does not affect whether or not you will
7314 receive replies from multicast group members.
7316 You must be very careful to NOT use a multicast address which
7317 is already in use by another group of caches.
7319 If you are unsure about multicast, please read the Multicast
7320 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
7322 Usage: mcast_groups 239.128.16.128 224.0.1.20
7324 By default, Squid doesn't listen on any multicast groups.
7327 NAME: mcast_miss_addr
7328 IFDEF: MULTICAST_MISS_STREAM
7330 LOC: Config.mcast_miss.addr
7332 DEFAULT_DOC: disabled.
7334 If you enable this option, every "cache miss" URL will
7335 be sent out on the specified multicast address.
7337 Do not enable this option unless you are are absolutely
7338 certain you understand what you are doing.
7341 NAME: mcast_miss_ttl
7342 IFDEF: MULTICAST_MISS_STREAM
7344 LOC: Config.mcast_miss.ttl
7347 This is the time-to-live value for packets multicasted
7348 when multicasting off cache miss URLs is enabled. By
7349 default this is set to 'site scope', i.e. 16.
7352 NAME: mcast_miss_port
7353 IFDEF: MULTICAST_MISS_STREAM
7355 LOC: Config.mcast_miss.port
7358 This is the port number to be used in conjunction with
7362 NAME: mcast_miss_encode_key
7363 IFDEF: MULTICAST_MISS_STREAM
7365 LOC: Config.mcast_miss.encode_key
7366 DEFAULT: XXXXXXXXXXXXXXXX
7368 The URLs that are sent in the multicast miss stream are
7369 encrypted. This is the encryption key.
7372 NAME: mcast_icp_query_timeout
7376 LOC: Config.Timeout.mcast_icp_query
7378 For multicast peers, Squid regularly sends out ICP "probes" to
7379 count how many other peers are listening on the given multicast
7380 address. This value specifies how long Squid should wait to
7381 count all the replies. The default is 2000 msec, or 2
7386 INTERNAL ICON OPTIONS
7387 -----------------------------------------------------------------------------
7390 NAME: icon_directory
7392 LOC: Config.icons.directory
7393 DEFAULT: @DEFAULT_ICON_DIR@
7395 Where the icons are stored. These are normally kept in
7399 NAME: global_internal_static
7401 LOC: Config.onoff.global_internal_static
7404 This directive controls is Squid should intercept all requests for
7405 /squid-internal-static/ no matter which host the URL is requesting
7406 (default on setting), or if nothing special should be done for
7407 such URLs (off setting). The purpose of this directive is to make
7408 icons etc work better in complex cache hierarchies where it may
7409 not always be possible for all corners in the cache mesh to reach
7410 the server generating a directory listing.
7413 NAME: short_icon_urls
7415 LOC: Config.icons.use_short_names
7418 If this is enabled Squid will use short URLs for icons.
7419 If disabled it will revert to the old behavior of including
7420 it's own name and port in the URL.
7422 If you run a complex cache hierarchy with a mix of Squid and
7423 other proxies you may need to disable this directive.
7428 -----------------------------------------------------------------------------
7431 NAME: error_directory
7433 LOC: Config.errorDirectory
7435 DEFAULT_DOC: Send error pages in the clients preferred language
7437 If you wish to create your own versions of the default
7438 error files to customize them to suit your company copy
7439 the error/template files to another directory and point
7442 WARNING: This option will disable multi-language support
7443 on error pages if used.
7445 The squid developers are interested in making squid available in
7446 a wide variety of languages. If you are making translations for a
7447 language that Squid does not currently provide please consider
7448 contributing your translation back to the project.
7449 http://wiki.squid-cache.org/Translations
7451 The squid developers working on translations are happy to supply drop-in
7452 translated error files in exchange for any new language contributions.
7455 NAME: error_default_language
7456 IFDEF: USE_ERR_LOCALES
7458 LOC: Config.errorDefaultLanguage
7460 DEFAULT_DOC: Generate English language pages.
7462 Set the default language which squid will send error pages in
7463 if no existing translation matches the clients language
7466 If unset (default) generic English will be used.
7468 The squid developers are interested in making squid available in
7469 a wide variety of languages. If you are interested in making
7470 translations for any language see the squid wiki for details.
7471 http://wiki.squid-cache.org/Translations
7474 NAME: error_log_languages
7475 IFDEF: USE_ERR_LOCALES
7477 LOC: Config.errorLogMissingLanguages
7480 Log to cache.log what languages users are attempting to
7481 auto-negotiate for translations.
7483 Successful negotiations are not logged. Only failures
7484 have meaning to indicate that Squid may need an upgrade
7485 of its error page translations.
7488 NAME: err_page_stylesheet
7490 LOC: Config.errorStylesheet
7491 DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
7493 CSS Stylesheet to pattern the display of Squid default error pages.
7495 For information on CSS see http://www.w3.org/Style/CSS/
7500 LOC: Config.errHtmlText
7503 HTML text to include in error messages. Make this a "mailto"
7504 URL to your admin address, or maybe just a link to your
7505 organizations Web page.
7507 To include this in your error messages, you must rewrite
7508 the error template files (found in the "errors" directory).
7509 Wherever you want the 'err_html_text' line to appear,
7510 insert a %L tag in the error template file.
7513 NAME: email_err_data
7516 LOC: Config.onoff.emailErrData
7519 If enabled, information about the occurred error will be
7520 included in the mailto links of the ERR pages (if %W is set)
7521 so that the email body contains the data.
7522 Syntax is <A HREF="mailto:%w%W">%w</A>
7527 LOC: Config.denyInfoList
7530 Usage: deny_info err_page_name acl
7531 or deny_info http://... acl
7532 or deny_info TCP_RESET acl
7534 This can be used to return a ERR_ page for requests which
7535 do not pass the 'http_access' rules. Squid remembers the last
7536 acl it evaluated in http_access, and if a 'deny_info' line exists
7537 for that ACL Squid returns a corresponding error page.
7539 The acl is typically the last acl on the http_access deny line which
7540 denied access. The exceptions to this rule are:
7541 - When Squid needs to request authentication credentials. It's then
7542 the first authentication related acl encountered
7543 - When none of the http_access lines matches. It's then the last
7544 acl processed on the last http_access line.
7545 - When the decision to deny access was made by an adaptation service,
7546 the acl name is the corresponding eCAP or ICAP service_name.
7548 NP: If providing your own custom error pages with error_directory
7549 you may also specify them by your custom file name:
7550 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
7552 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
7553 may be specified by prefixing the file name with the code and a colon.
7554 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
7556 Alternatively you can tell Squid to reset the TCP connection
7557 by specifying TCP_RESET.
7559 Or you can specify an error URL or URL pattern. The browsers will
7560 get redirected to the specified URL after formatting tags have
7561 been replaced. Redirect will be done with 302 or 307 according to
7562 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
7563 the URL. e.g. 303:http://example.com/
7566 %a - username (if available. Password NOT included)
7569 %E - Error description
7571 %H - Request domain name
7572 %i - Client IP Address
7574 %o - Message result from external ACL helper
7575 %p - Request Port number
7576 %P - Request Protocol name
7577 %R - Request URL path
7578 %T - Timestamp in RFC 1123 format
7579 %U - Full canonical URL from client
7580 (HTTPS URLs terminate with *)
7581 %u - Full canonical URL from client
7582 %w - Admin email from squid.conf
7584 %% - Literal percent (%) code
7589 OPTIONS INFLUENCING REQUEST FORWARDING
7590 -----------------------------------------------------------------------------
7593 NAME: nonhierarchical_direct
7595 LOC: Config.onoff.nonhierarchical_direct
7598 By default, Squid will send any non-hierarchical requests
7599 (not cacheable request type) direct to origin servers.
7601 When this is set to "off", Squid will prefer to send these
7602 requests to parents.
7604 Note that in most configurations, by turning this off you will only
7605 add latency to these request without any improvement in global hit
7608 This option only sets a preference. If the parent is unavailable a
7609 direct connection to the origin server may still be attempted. To
7610 completely prevent direct connections use never_direct.
7615 LOC: Config.onoff.prefer_direct
7618 Normally Squid tries to use parents for most requests. If you for some
7619 reason like it to first try going direct and only use a parent if
7620 going direct fails set this to on.
7622 By combining nonhierarchical_direct off and prefer_direct on you
7623 can set up Squid to use a parent as a backup path if going direct
7626 Note: If you want Squid to use parents for all requests see
7627 the never_direct directive. prefer_direct only modifies how Squid
7628 acts on cacheable requests.
7631 NAME: cache_miss_revalidate
7635 LOC: Config.onoff.cache_miss_revalidate
7637 RFC 7232 defines a conditional request mechanism to prevent
7638 response objects being unnecessarily transferred over the network.
7639 If that mechanism is used by the client and a cache MISS occurs
7640 it can prevent new cache entries being created.
7642 This option determines whether Squid on cache MISS will pass the
7643 client revalidation request to the server or tries to fetch new
7644 content for caching. It can be useful while the cache is mostly
7645 empty to more quickly have the cache populated by generating
7646 non-conditional GETs.
7648 When set to 'on' (default), Squid will pass all client If-* headers
7649 to the server. This permits server responses without a cacheable
7650 payload to be delivered and on MISS no new cache entry is created.
7652 When set to 'off' and if the request is cacheable, Squid will
7653 remove the clients If-Modified-Since and If-None-Match headers from
7654 the request sent to the server. This requests a 200 status response
7655 from the server to create a new cache entry with.
7660 LOC: Config.accessList.AlwaysDirect
7662 DEFAULT_DOC: Prevent any cache_peer being used for this request.
7664 Usage: always_direct allow|deny [!]aclname ...
7666 Here you can use ACL elements to specify requests which should
7667 ALWAYS be forwarded by Squid to the origin servers without using
7668 any peers. For example, to always directly forward requests for
7669 local servers ignoring any parents or siblings you may have use
7672 acl local-servers dstdomain my.domain.net
7673 always_direct allow local-servers
7675 To always forward FTP requests directly, use
7678 always_direct allow FTP
7680 NOTE: There is a similar, but opposite option named
7681 'never_direct'. You need to be aware that "always_direct deny
7682 foo" is NOT the same thing as "never_direct allow foo". You
7683 may need to use a deny rule to exclude a more-specific case of
7684 some other rule. Example:
7686 acl local-external dstdomain external.foo.net
7687 acl local-servers dstdomain .foo.net
7688 always_direct deny local-external
7689 always_direct allow local-servers
7691 NOTE: If your goal is to make the client forward the request
7692 directly to the origin server bypassing Squid then this needs
7693 to be done in the client configuration. Squid configuration
7694 can only tell Squid how Squid should fetch the object.
7696 NOTE: This directive is not related to caching. The replies
7697 is cached as usual even if you use always_direct. To not cache
7698 the replies see the 'cache' directive.
7700 This clause supports both fast and slow acl types.
7701 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7706 LOC: Config.accessList.NeverDirect
7708 DEFAULT_DOC: Allow DNS results to be used for this request.
7710 Usage: never_direct allow|deny [!]aclname ...
7712 never_direct is the opposite of always_direct. Please read
7713 the description for always_direct if you have not already.
7715 With 'never_direct' you can use ACL elements to specify
7716 requests which should NEVER be forwarded directly to origin
7717 servers. For example, to force the use of a proxy for all
7718 requests, except those in your local domain use something like:
7720 acl local-servers dstdomain .foo.net
7721 never_direct deny local-servers
7722 never_direct allow all
7724 or if Squid is inside a firewall and there are local intranet
7725 servers inside the firewall use something like:
7727 acl local-intranet dstdomain .foo.net
7728 acl local-external dstdomain external.foo.net
7729 always_direct deny local-external
7730 always_direct allow local-intranet
7731 never_direct allow all
7733 This clause supports both fast and slow acl types.
7734 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7738 ADVANCED NETWORKING OPTIONS
7739 -----------------------------------------------------------------------------
7742 NAME: incoming_udp_average incoming_icp_average
7745 LOC: Config.comm_incoming.udp.average
7747 Heavy voodoo here. I can't even believe you are reading this.
7748 Are you crazy? Don't even think about adjusting these unless
7749 you understand the algorithms in comm_select.c first!
7752 NAME: incoming_tcp_average incoming_http_average
7755 LOC: Config.comm_incoming.tcp.average
7757 Heavy voodoo here. I can't even believe you are reading this.
7758 Are you crazy? Don't even think about adjusting these unless
7759 you understand the algorithms in comm_select.c first!
7762 NAME: incoming_dns_average
7765 LOC: Config.comm_incoming.dns.average
7767 Heavy voodoo here. I can't even believe you are reading this.
7768 Are you crazy? Don't even think about adjusting these unless
7769 you understand the algorithms in comm_select.c first!
7772 NAME: min_udp_poll_cnt min_icp_poll_cnt
7775 LOC: Config.comm_incoming.udp.min_poll
7777 Heavy voodoo here. I can't even believe you are reading this.
7778 Are you crazy? Don't even think about adjusting these unless
7779 you understand the algorithms in comm_select.c first!
7782 NAME: min_dns_poll_cnt
7785 LOC: Config.comm_incoming.dns.min_poll
7787 Heavy voodoo here. I can't even believe you are reading this.
7788 Are you crazy? Don't even think about adjusting these unless
7789 you understand the algorithms in comm_select.c first!
7792 NAME: min_tcp_poll_cnt min_http_poll_cnt
7795 LOC: Config.comm_incoming.tcp.min_poll
7797 Heavy voodoo here. I can't even believe you are reading this.
7798 Are you crazy? Don't even think about adjusting these unless
7799 you understand the algorithms in comm_select.c first!
7805 LOC: Config.accept_filter
7809 The name of an accept(2) filter to install on Squid's
7810 listen socket(s). This feature is perhaps specific to
7811 FreeBSD and requires support in the kernel.
7813 The 'httpready' filter delays delivering new connections
7814 to Squid until a full HTTP request has been received.
7815 See the accf_http(9) man page for details.
7817 The 'dataready' filter delays delivering new connections
7818 to Squid until there is some data to process.
7819 See the accf_dataready(9) man page for details.
7823 The 'data' filter delays delivering of new connections
7824 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
7825 You may optionally specify a number of seconds to wait by
7826 'data=N' where N is the number of seconds. Defaults to 30
7827 if not specified. See the tcp(7) man page for details.
7830 accept_filter httpready
7835 NAME: client_ip_max_connections
7837 LOC: Config.client_ip_max_connections
7839 DEFAULT_DOC: No limit.
7841 Set an absolute limit on the number of connections a single
7842 client IP can use. Any more than this and Squid will begin to drop
7843 new connections from the client until it closes some links.
7845 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
7846 connections from the client. For finer control use the ACL access controls.
7848 Requires client_db to be enabled (the default).
7850 WARNING: This may noticably slow down traffic received via external proxies
7851 or NAT devices and cause them to rebound error messages back to their clients.
7854 NAME: tcp_recv_bufsize
7858 DEFAULT_DOC: Use operating system TCP defaults.
7859 LOC: Config.tcpRcvBufsz
7861 Size of receive buffer to set for TCP sockets. Probably just
7862 as easy to change your kernel's default.
7863 Omit from squid.conf to use the default buffer size.
7868 -----------------------------------------------------------------------------
7875 LOC: Adaptation::Icap::TheConfig.onoff
7878 If you want to enable the ICAP module support, set this to on.
7881 NAME: icap_connect_timeout
7884 LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
7887 This parameter specifies how long to wait for the TCP connect to
7888 the requested ICAP server to complete before giving up and either
7889 terminating the HTTP transaction or bypassing the failure.
7891 The default for optional services is peer_connect_timeout.
7892 The default for essential services is connect_timeout.
7893 If this option is explicitly set, its value applies to all services.
7896 NAME: icap_io_timeout
7900 DEFAULT_DOC: Use read_timeout.
7901 LOC: Adaptation::Icap::TheConfig.io_timeout_raw
7904 This parameter specifies how long to wait for an I/O activity on
7905 an established, active ICAP connection before giving up and
7906 either terminating the HTTP transaction or bypassing the
7910 NAME: icap_service_failure_limit
7911 COMMENT: limit [in memory-depth time-units]
7912 TYPE: icap_service_failure_limit
7914 LOC: Adaptation::Icap::TheConfig
7917 The limit specifies the number of failures that Squid tolerates
7918 when establishing a new TCP connection with an ICAP service. If
7919 the number of failures exceeds the limit, the ICAP service is
7920 not used for new ICAP requests until it is time to refresh its
7923 A negative value disables the limit. Without the limit, an ICAP
7924 service will not be considered down due to connectivity failures
7925 between ICAP OPTIONS requests.
7927 Squid forgets ICAP service failures older than the specified
7928 value of memory-depth. The memory fading algorithm
7929 is approximate because Squid does not remember individual
7930 errors but groups them instead, splitting the option
7931 value into ten time slots of equal length.
7933 When memory-depth is 0 and by default this option has no
7934 effect on service failure expiration.
7936 Squid always forgets failures when updating service settings
7937 using an ICAP OPTIONS transaction, regardless of this option
7941 # suspend service usage after 10 failures in 5 seconds:
7942 icap_service_failure_limit 10 in 5 seconds
7945 NAME: icap_service_revival_delay
7948 LOC: Adaptation::Icap::TheConfig.service_revival_delay
7951 The delay specifies the number of seconds to wait after an ICAP
7952 OPTIONS request failure before requesting the options again. The
7953 failed ICAP service is considered "down" until fresh OPTIONS are
7956 The actual delay cannot be smaller than the hardcoded minimum
7957 delay of 30 seconds.
7960 NAME: icap_preview_enable
7964 LOC: Adaptation::Icap::TheConfig.preview_enable
7967 The ICAP Preview feature allows the ICAP server to handle the
7968 HTTP message by looking only at the beginning of the message body
7969 or even without receiving the body at all. In some environments,
7970 previews greatly speedup ICAP processing.
7972 During an ICAP OPTIONS transaction, the server may tell Squid what
7973 HTTP messages should be previewed and how big the preview should be.
7974 Squid will not use Preview if the server did not request one.
7976 To disable ICAP Preview for all ICAP services, regardless of
7977 individual ICAP server OPTIONS responses, set this option to "off".
7979 icap_preview_enable off
7982 NAME: icap_preview_size
7985 LOC: Adaptation::Icap::TheConfig.preview_size
7987 DEFAULT_DOC: No preview sent.
7989 The default size of preview data to be sent to the ICAP server.
7990 This value might be overwritten on a per server basis by OPTIONS requests.
7993 NAME: icap_206_enable
7997 LOC: Adaptation::Icap::TheConfig.allow206_enable
8000 206 (Partial Content) responses is an ICAP extension that allows the
8001 ICAP agents to optionally combine adapted and original HTTP message
8002 content. The decision to combine is postponed until the end of the
8003 ICAP response. Squid supports Partial Content extension by default.
8005 Activation of the Partial Content extension is negotiated with each
8006 ICAP service during OPTIONS exchange. Most ICAP servers should handle
8007 negotation correctly even if they do not support the extension, but
8008 some might fail. To disable Partial Content support for all ICAP
8009 services and to avoid any negotiation, set this option to "off".
8015 NAME: icap_default_options_ttl
8018 LOC: Adaptation::Icap::TheConfig.default_options_ttl
8021 The default TTL value for ICAP OPTIONS responses that don't have
8022 an Options-TTL header.
8025 NAME: icap_persistent_connections
8029 LOC: Adaptation::Icap::TheConfig.reuse_connections
8032 Whether or not Squid should use persistent connections to
8036 NAME: adaptation_send_client_ip icap_send_client_ip
8038 IFDEF: USE_ADAPTATION
8040 LOC: Adaptation::Config::send_client_ip
8043 If enabled, Squid shares HTTP client IP information with adaptation
8044 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests.
8045 For eCAP, Squid sets the libecap::metaClientIp transaction option.
8047 See also: adaptation_uses_indirect_client
8050 NAME: adaptation_send_username icap_send_client_username
8052 IFDEF: USE_ADAPTATION
8054 LOC: Adaptation::Config::send_username
8057 This sends authenticated HTTP client username (if available) to
8058 the adaptation service.
8060 For ICAP, the username value is encoded based on the
8061 icap_client_username_encode option and is sent using the header
8062 specified by the icap_client_username_header option.
8065 NAME: icap_client_username_header
8068 LOC: Adaptation::Icap::TheConfig.client_username_header
8069 DEFAULT: X-Client-Username
8071 ICAP request header name to use for adaptation_send_username.
8074 NAME: icap_client_username_encode
8078 LOC: Adaptation::Icap::TheConfig.client_username_encode
8081 Whether to base64 encode the authenticated client username.
8085 TYPE: icap_service_type
8087 LOC: Adaptation::Icap::TheConfig
8090 Defines a single ICAP service using the following format:
8092 icap_service id vectoring_point uri [option ...]
8095 an opaque identifier or name which is used to direct traffic to
8096 this specific service. Must be unique among all adaptation
8097 services in squid.conf.
8099 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8100 This specifies at which point of transaction processing the
8101 ICAP service should be activated. *_postcache vectoring points
8102 are not yet supported.
8104 uri: icap://servername:port/servicepath
8105 ICAP server and service location.
8107 ICAP does not allow a single service to handle both REQMOD and RESPMOD
8108 transactions. Squid does not enforce that requirement. You can specify
8109 services with the same service_url and different vectoring_points. You
8110 can even specify multiple identical services as long as their
8111 service_names differ.
8113 To activate a service, use the adaptation_access directive. To group
8114 services, use adaptation_service_chain and adaptation_service_set.
8116 Service options are separated by white space. ICAP services support
8117 the following name=value options:
8120 If set to 'on' or '1', the ICAP service is treated as
8121 optional. If the service cannot be reached or malfunctions,
8122 Squid will try to ignore any errors and process the message as
8123 if the service was not enabled. No all ICAP errors can be
8124 bypassed. If set to 0, the ICAP service is treated as
8125 essential and all ICAP errors will result in an error page
8126 returned to the HTTP client.
8128 Bypass is off by default: services are treated as essential.
8131 If set to 'on' or '1', the ICAP service is allowed to
8132 dynamically change the current message adaptation plan by
8133 returning a chain of services to be used next. The services
8134 are specified using the X-Next-Services ICAP response header
8135 value, formatted as a comma-separated list of service names.
8136 Each named service should be configured in squid.conf. Other
8137 services are ignored. An empty X-Next-Services value results
8138 in an empty plan which ends the current adaptation.
8140 Dynamic adaptation plan may cross or cover multiple supported
8141 vectoring points in their natural processing order.
8143 Routing is not allowed by default: the ICAP X-Next-Services
8144 response header is ignored.
8147 Only has effect on split-stack systems. The default on those systems
8148 is to use IPv4-only connections. When set to 'on' this option will
8149 make Squid use IPv6-only connections to contact this ICAP service.
8151 on-overload=block|bypass|wait|force
8152 If the service Max-Connections limit has been reached, do
8153 one of the following for each new ICAP transaction:
8154 * block: send an HTTP error response to the client
8155 * bypass: ignore the "over-connected" ICAP service
8156 * wait: wait (in a FIFO queue) for an ICAP connection slot
8157 * force: proceed, ignoring the Max-Connections limit
8159 In SMP mode with N workers, each worker assumes the service
8160 connection limit is Max-Connections/N, even though not all
8161 workers may use a given service.
8163 The default value is "bypass" if service is bypassable,
8164 otherwise it is set to "wait".
8168 Use the given number as the Max-Connections limit, regardless
8169 of the Max-Connections value given by the service, if any.
8171 Older icap_service format without optional named parameters is
8172 deprecated but supported for backward compatibility.
8175 icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0
8176 icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on
8180 TYPE: icap_class_type
8185 This deprecated option was documented to define an ICAP service
8186 chain, even though it actually defined a set of similar, redundant
8187 services, and the chains were not supported.
8189 To define a set of redundant services, please use the
8190 adaptation_service_set directive. For service chains, use
8191 adaptation_service_chain.
8195 TYPE: icap_access_type
8200 This option is deprecated. Please use adaptation_access, which
8201 has the same ICAP functionality, but comes with better
8202 documentation, and eCAP support.
8207 -----------------------------------------------------------------------------
8214 LOC: Adaptation::Ecap::TheConfig.onoff
8217 Controls whether eCAP support is enabled.
8221 TYPE: ecap_service_type
8223 LOC: Adaptation::Ecap::TheConfig
8226 Defines a single eCAP service
8228 ecap_service id vectoring_point uri [option ...]
8231 an opaque identifier or name which is used to direct traffic to
8232 this specific service. Must be unique among all adaptation
8233 services in squid.conf.
8235 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8236 This specifies at which point of transaction processing the
8237 eCAP service should be activated. *_postcache vectoring points
8238 are not yet supported.
8240 uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional
8241 Squid uses the eCAP service URI to match this configuration
8242 line with one of the dynamically loaded services. Each loaded
8243 eCAP service must have a unique URI. Obtain the right URI from
8244 the service provider.
8246 To activate a service, use the adaptation_access directive. To group
8247 services, use adaptation_service_chain and adaptation_service_set.
8249 Service options are separated by white space. eCAP services support
8250 the following name=value options:
8253 If set to 'on' or '1', the eCAP service is treated as optional.
8254 If the service cannot be reached or malfunctions, Squid will try
8255 to ignore any errors and process the message as if the service
8256 was not enabled. No all eCAP errors can be bypassed.
8257 If set to 'off' or '0', the eCAP service is treated as essential
8258 and all eCAP errors will result in an error page returned to the
8261 Bypass is off by default: services are treated as essential.
8264 If set to 'on' or '1', the eCAP service is allowed to
8265 dynamically change the current message adaptation plan by
8266 returning a chain of services to be used next.
8268 Dynamic adaptation plan may cross or cover multiple supported
8269 vectoring points in their natural processing order.
8271 Routing is not allowed by default.
8273 Older ecap_service format without optional named parameters is
8274 deprecated but supported for backward compatibility.
8278 ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off
8279 ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on
8282 NAME: loadable_modules
8284 IFDEF: USE_LOADABLE_MODULES
8285 LOC: Config.loadable_module_names
8288 Instructs Squid to load the specified dynamic module(s) or activate
8289 preloaded module(s).
8291 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
8295 MESSAGE ADAPTATION OPTIONS
8296 -----------------------------------------------------------------------------
8299 NAME: adaptation_service_set
8300 TYPE: adaptation_service_set_type
8301 IFDEF: USE_ADAPTATION
8306 Configures an ordered set of similar, redundant services. This is
8307 useful when hot standby or backup adaptation servers are available.
8309 adaptation_service_set set_name service_name1 service_name2 ...
8311 The named services are used in the set declaration order. The first
8312 applicable adaptation service from the set is used first. The next
8313 applicable service is tried if and only if the transaction with the
8314 previous service fails and the message waiting to be adapted is still
8317 When adaptation starts, broken services are ignored as if they were
8318 not a part of the set. A broken service is a down optional service.
8320 The services in a set must be attached to the same vectoring point
8321 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8323 If all services in a set are optional then adaptation failures are
8324 bypassable. If all services in the set are essential, then a
8325 transaction failure with one service may still be retried using
8326 another service from the set, but when all services fail, the master
8327 transaction fails as well.
8329 A set may contain a mix of optional and essential services, but that
8330 is likely to lead to surprising results because broken services become
8331 ignored (see above), making previously bypassable failures fatal.
8332 Technically, it is the bypassability of the last failed service that
8335 See also: adaptation_access adaptation_service_chain
8338 adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
8339 adaptation service_set svcLogger loggerLocal loggerRemote
8342 NAME: adaptation_service_chain
8343 TYPE: adaptation_service_chain_type
8344 IFDEF: USE_ADAPTATION
8349 Configures a list of complementary services that will be applied
8350 one-by-one, forming an adaptation chain or pipeline. This is useful
8351 when Squid must perform different adaptations on the same message.
8353 adaptation_service_chain chain_name service_name1 svc_name2 ...
8355 The named services are used in the chain declaration order. The first
8356 applicable adaptation service from the chain is used first. The next
8357 applicable service is applied to the successful adaptation results of
8358 the previous service in the chain.
8360 When adaptation starts, broken services are ignored as if they were
8361 not a part of the chain. A broken service is a down optional service.
8363 Request satisfaction terminates the adaptation chain because Squid
8364 does not currently allow declaration of RESPMOD services at the
8365 "reqmod_precache" vectoring point (see icap_service or ecap_service).
8367 The services in a chain must be attached to the same vectoring point
8368 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8370 A chain may contain a mix of optional and essential services. If an
8371 essential adaptation fails (or the failure cannot be bypassed for
8372 other reasons), the master transaction fails. Otherwise, the failure
8373 is bypassed as if the failed adaptation service was not in the chain.
8375 See also: adaptation_access adaptation_service_set
8378 adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
8381 NAME: adaptation_access
8382 TYPE: adaptation_access_type
8383 IFDEF: USE_ADAPTATION
8386 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
8388 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
8390 adaptation_access service_name allow|deny [!]aclname...
8391 adaptation_access set_name allow|deny [!]aclname...
8393 At each supported vectoring point, the adaptation_access
8394 statements are processed in the order they appear in this
8395 configuration file. Statements pointing to the following services
8396 are ignored (i.e., skipped without checking their ACL):
8398 - services serving different vectoring points
8399 - "broken-but-bypassable" services
8400 - "up" services configured to ignore such transactions
8401 (e.g., based on the ICAP Transfer-Ignore header).
8403 When a set_name is used, all services in the set are checked
8404 using the same rules, to find the first applicable one. See
8405 adaptation_service_set for details.
8407 If an access list is checked and there is a match, the
8408 processing stops: For an "allow" rule, the corresponding
8409 adaptation service is used for the transaction. For a "deny"
8410 rule, no adaptation service is activated.
8412 It is currently not possible to apply more than one adaptation
8413 service at the same vectoring point to the same HTTP transaction.
8415 See also: icap_service and ecap_service
8418 adaptation_access service_1 allow all
8421 NAME: adaptation_service_iteration_limit
8423 IFDEF: USE_ADAPTATION
8424 LOC: Adaptation::Config::service_iteration_limit
8427 Limits the number of iterations allowed when applying adaptation
8428 services to a message. If your longest adaptation set or chain
8429 may have more than 16 services, increase the limit beyond its
8430 default value of 16. If detecting infinite iteration loops sooner
8431 is critical, make the iteration limit match the actual number
8432 of services in your longest adaptation set or chain.
8434 Infinite adaptation loops are most likely with routing services.
8436 See also: icap_service routing=1
8439 NAME: adaptation_masterx_shared_names
8441 IFDEF: USE_ADAPTATION
8442 LOC: Adaptation::Config::masterx_shared_name
8445 For each master transaction (i.e., the HTTP request and response
8446 sequence, including all related ICAP and eCAP exchanges), Squid
8447 maintains a table of metadata. The table entries are (name, value)
8448 pairs shared among eCAP and ICAP exchanges. The table is destroyed
8449 with the master transaction.
8451 This option specifies the table entry names that Squid must accept
8452 from and forward to the adaptation transactions.
8454 An ICAP REQMOD or RESPMOD transaction may set an entry in the
8455 shared table by returning an ICAP header field with a name
8456 specified in adaptation_masterx_shared_names.
8458 An eCAP REQMOD or RESPMOD transaction may set an entry in the
8459 shared table by implementing the libecap::visitEachOption() API
8460 to provide an option with a name specified in
8461 adaptation_masterx_shared_names.
8463 Squid will store and forward the set entry to subsequent adaptation
8464 transactions within the same master transaction scope.
8466 Only one shared entry name is supported at this time.
8469 # share authentication information among ICAP services
8470 adaptation_masterx_shared_names X-Subscriber-ID
8473 NAME: adaptation_meta
8475 IFDEF: USE_ADAPTATION
8476 LOC: Adaptation::Config::metaHeaders
8479 This option allows Squid administrator to add custom ICAP request
8480 headers or eCAP options to Squid ICAP requests or eCAP transactions.
8481 Use it to pass custom authentication tokens and other
8482 transaction-state related meta information to an ICAP/eCAP service.
8484 The addition of a meta header is ACL-driven:
8485 adaptation_meta name value [!]aclname ...
8487 Processing for a given header name stops after the first ACL list match.
8488 Thus, it is impossible to add two headers with the same name. If no ACL
8489 lists match for a given header name, no such header is added. For
8492 # do not debug transactions except for those that need debugging
8493 adaptation_meta X-Debug 1 needs_debugging
8495 # log all transactions except for those that must remain secret
8496 adaptation_meta X-Log 1 !keep_secret
8498 # mark transactions from users in the "G 1" group
8499 adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1
8501 The "value" parameter may be a regular squid.conf token or a "double
8502 quoted string". Within the quoted string, use backslash (\) to escape
8503 any character, which is currently only useful for escaping backslashes
8504 and double quotes. For example,
8505 "this string has one backslash (\\) and two \"quotes\""
8507 Used adaptation_meta header values may be logged via %note
8508 logformat code. If multiple adaptation_meta headers with the same name
8509 are used during master transaction lifetime, the header values are
8510 logged in the order they were used and duplicate values are ignored
8511 (only the first repeated value will be logged).
8517 LOC: Adaptation::Icap::TheConfig.repeat
8518 DEFAULT_IF_NONE: deny all
8520 This ACL determines which retriable ICAP transactions are
8521 retried. Transactions that received a complete ICAP response
8522 and did not have to consume or produce HTTP bodies to receive
8523 that response are usually retriable.
8525 icap_retry allow|deny [!]aclname ...
8527 Squid automatically retries some ICAP I/O timeouts and errors
8528 due to persistent connection race conditions.
8530 See also: icap_retry_limit
8533 NAME: icap_retry_limit
8536 LOC: Adaptation::Icap::TheConfig.repeat_limit
8538 DEFAULT_DOC: No retries are allowed.
8540 Limits the number of retries allowed.
8542 Communication errors due to persistent connection race
8543 conditions are unavoidable, automatically retried, and do not
8544 count against this limit.
8546 See also: icap_retry
8552 -----------------------------------------------------------------------------
8555 NAME: check_hostnames
8558 LOC: Config.onoff.check_hostnames
8560 For security and stability reasons Squid can check
8561 hostnames for Internet standard RFC compliance. If you want
8562 Squid to perform these checks turn this directive on.
8565 NAME: allow_underscore
8568 LOC: Config.onoff.allow_underscore
8570 Underscore characters is not strictly allowed in Internet hostnames
8571 but nevertheless used by many sites. Set this to off if you want
8572 Squid to be strict about the standard.
8573 This check is performed only when check_hostnames is set to on.
8576 NAME: dns_retransmit_interval
8579 LOC: Config.Timeout.idns_retransmit
8581 Initial retransmit interval for DNS queries. The interval is
8582 doubled each time all configured DNS servers have been tried.
8588 LOC: Config.Timeout.idns_query
8590 DNS Query timeout. If no response is received to a DNS query
8591 within this time all DNS servers for the queried domain
8592 are assumed to be unavailable.
8595 NAME: dns_packet_max
8597 DEFAULT_DOC: EDNS disabled
8599 LOC: Config.dns.packet_max
8601 Maximum number of bytes packet size to advertise via EDNS.
8602 Set to "none" to disable EDNS large packet support.
8604 For legacy reasons DNS UDP replies will default to 512 bytes which
8605 is too small for many responses. EDNS provides a means for Squid to
8606 negotiate receiving larger responses back immediately without having
8607 to failover with repeat requests. Responses larger than this limit
8608 will retain the old behaviour of failover to TCP DNS.
8610 Squid has no real fixed limit internally, but allowing packet sizes
8611 over 1500 bytes requires network jumbogram support and is usually not
8614 WARNING: The RFC also indicates that some older resolvers will reply
8615 with failure of the whole request if the extension is added. Some
8616 resolvers have already been identified which will reply with mangled
8617 EDNS response on occasion. Usually in response to many-KB jumbogram
8618 sizes being advertised by Squid.
8619 Squid will currently treat these both as an unable-to-resolve domain
8620 even if it would be resolvable without EDNS.
8627 DEFAULT_DOC: Search for single-label domain names is disabled.
8628 LOC: Config.onoff.res_defnames
8630 Normally the RES_DEFNAMES resolver option is disabled
8631 (see res_init(3)). This prevents caches in a hierarchy
8632 from interpreting single-component hostnames locally. To allow
8633 Squid to handle single-component names, enable this option.
8636 NAME: dns_multicast_local
8640 DEFAULT_DOC: Search for .local and .arpa names is disabled.
8641 LOC: Config.onoff.dns_mdns
8643 When set to on, Squid sends multicast DNS lookups on the local
8644 network for domains ending in .local and .arpa.
8645 This enables local servers and devices to be contacted in an
8646 ad-hoc or zero-configuration network environment.
8649 NAME: dns_nameservers
8652 DEFAULT_DOC: Use operating system definitions
8653 LOC: Config.dns_nameservers
8655 Use this if you want to specify a list of DNS name servers
8656 (IP addresses) to use instead of those given in your
8657 /etc/resolv.conf file.
8659 On Windows platforms, if no value is specified here or in
8660 the /etc/resolv.conf file, the list of DNS name servers are
8661 taken from the Windows registry, both static and dynamic DHCP
8662 configurations are supported.
8664 Example: dns_nameservers 10.0.0.1 192.172.0.4
8669 DEFAULT: @DEFAULT_HOSTS@
8670 LOC: Config.etcHostsPath
8672 Location of the host-local IP name-address associations
8673 database. Most Operating Systems have such a file on different
8675 - Un*X & Linux: /etc/hosts
8676 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
8677 (%SystemRoot% value install default is c:\winnt)
8678 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
8679 (%SystemRoot% value install default is c:\windows)
8680 - Windows 9x/Me: %windir%\hosts
8681 (%windir% value is usually c:\windows)
8682 - Cygwin: /etc/hosts
8684 The file contains newline-separated definitions, in the
8685 form ip_address_in_dotted_form name [name ...] names are
8686 whitespace-separated. Lines beginning with an hash (#)
8687 character are comments.
8689 The file is checked at startup and upon configuration.
8690 If set to 'none', it won't be checked.
8691 If append_domain is used, that domain will be added to
8692 domain-local (i.e. not containing any dot character) host
8698 LOC: Config.appendDomain
8700 DEFAULT_DOC: Use operating system definitions
8702 Appends local domain name to hostnames without any dots in
8703 them. append_domain must begin with a period.
8705 Be warned there are now Internet names with no dots in
8706 them using only top-domain names, so setting this may
8707 cause some Internet sites to become unavailable.
8710 append_domain .yourdomain.com
8713 NAME: ignore_unknown_nameservers
8715 LOC: Config.onoff.ignore_unknown_nameservers
8718 By default Squid checks that DNS responses are received
8719 from the same IP addresses they are sent to. If they
8720 don't match, Squid ignores the response and writes a warning
8721 message to cache.log. You can allow responses from unknown
8722 nameservers by setting this option to 'off'.
8728 LOC: Config.dns.v4_first
8730 With the IPv6 Internet being as fast or faster than IPv4 Internet
8731 for most networks Squid prefers to contact websites over IPv6.
8733 This option reverses the order of preference to make Squid contact
8734 dual-stack websites over IPv4 first. Squid will still perform both
8735 IPv6 and IPv4 DNS lookups before connecting.
8738 This option will restrict the situations under which IPv6
8739 connectivity is used (and tested). Hiding network problems
8740 which would otherwise be detected and warned about.
8744 COMMENT: (number of entries)
8747 LOC: Config.ipcache.size
8749 Maximum number of DNS IP cache entries.
8756 LOC: Config.ipcache.low
8763 LOC: Config.ipcache.high
8765 The size, low-, and high-water marks for the IP cache.
8768 NAME: fqdncache_size
8769 COMMENT: (number of entries)
8772 LOC: Config.fqdncache.size
8774 Maximum number of FQDN cache entries.
8779 -----------------------------------------------------------------------------
8782 NAME: configuration_includes_quoted_values
8784 TYPE: configuration_includes_quoted_values
8786 LOC: ConfigParser::RecognizeQuotedValues
8788 If set, Squid will recognize each "quoted string" after a configuration
8789 directive as a single parameter. The quotes are stripped before the
8790 parameter value is interpreted or used.
8791 See "Values with spaces, quotes, and other special characters"
8792 section for more details.
8799 LOC: Config.onoff.mem_pools
8801 If set, Squid will keep pools of allocated (but unused) memory
8802 available for future use. If memory is a premium on your
8803 system and you believe your malloc library outperforms Squid
8804 routines, disable this.
8807 NAME: memory_pools_limit
8811 LOC: Config.MemPools.limit
8813 Used only with memory_pools on:
8814 memory_pools_limit 50 MB
8816 If set to a non-zero value, Squid will keep at most the specified
8817 limit of allocated (but unused) memory in memory pools. All free()
8818 requests that exceed this limit will be handled by your malloc
8819 library. Squid does not pre-allocate any memory, just safe-keeps
8820 objects that otherwise would be free()d. Thus, it is safe to set
8821 memory_pools_limit to a reasonably high value even if your
8822 configuration will use less memory.
8824 If set to none, Squid will keep all memory it can. That is, there
8825 will be no limit on the total amount of memory used for safe-keeping.
8827 To disable memory allocation optimization, do not set
8828 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
8830 An overhead for maintaining memory pools is not taken into account
8831 when the limit is checked. This overhead is close to four bytes per
8832 object kept. However, pools may actually _save_ memory because of
8833 reduced memory thrashing in your malloc library.
8837 COMMENT: on|off|transparent|truncate|delete
8840 LOC: opt_forwarded_for
8842 If set to "on", Squid will append your client's IP address
8843 in the HTTP requests it forwards. By default it looks like:
8845 X-Forwarded-For: 192.1.2.3
8847 If set to "off", it will appear as
8849 X-Forwarded-For: unknown
8851 If set to "transparent", Squid will not alter the
8852 X-Forwarded-For header in any way.
8854 If set to "delete", Squid will delete the entire
8855 X-Forwarded-For header.
8857 If set to "truncate", Squid will remove all existing
8858 X-Forwarded-For entries, and place the client IP as the sole entry.
8861 NAME: cachemgr_passwd
8862 TYPE: cachemgrpasswd
8864 DEFAULT_DOC: No password. Actions which require password are denied.
8865 LOC: Config.passwd_list
8867 Specify passwords for cachemgr operations.
8869 Usage: cachemgr_passwd password action action ...
8871 Some valid actions are (see cache manager menu for a full list):
8911 * Indicates actions which will not be performed without a
8912 valid password, others can be performed if not listed here.
8914 To disable an action, set the password to "disable".
8915 To allow performing an action without a password, set the
8918 Use the keyword "all" to set the same password for all actions.
8921 cachemgr_passwd secret shutdown
8922 cachemgr_passwd lesssssssecret info stats/objects
8923 cachemgr_passwd disable all
8930 LOC: Config.onoff.client_db
8932 If you want to disable collecting per-client statistics,
8933 turn off client_db here.
8936 NAME: refresh_all_ims
8940 LOC: Config.onoff.refresh_all_ims
8942 When you enable this option, squid will always check
8943 the origin server for an update when a client sends an
8944 If-Modified-Since request. Many browsers use IMS
8945 requests when the user requests a reload, and this
8946 ensures those clients receive the latest version.
8948 By default (off), squid may return a Not Modified response
8949 based on the age of the cached version.
8952 NAME: reload_into_ims
8953 IFDEF: USE_HTTP_VIOLATIONS
8957 LOC: Config.onoff.reload_into_ims
8959 When you enable this option, client no-cache or ``reload''
8960 requests will be changed to If-Modified-Since requests.
8961 Doing this VIOLATES the HTTP standard. Enabling this
8962 feature could make you liable for problems which it
8965 see also refresh_pattern for a more selective approach.
8968 NAME: connect_retries
8970 LOC: Config.connect_retries
8972 DEFAULT_DOC: Do not retry failed connections.
8974 This sets the maximum number of connection attempts made for each
8975 TCP connection. The connect_retries attempts must all still
8976 complete within the connection timeout period.
8978 The default is not to re-try if the first connection attempt fails.
8979 The (not recommended) maximum is 10 tries.
8981 A warning message will be generated if it is set to a too-high
8982 value and the configured value will be over-ridden.
8984 Note: These re-tries are in addition to forward_max_tries
8985 which limit how many different addresses may be tried to find
8989 NAME: retry_on_error
8991 LOC: Config.retry.onerror
8994 If set to ON Squid will automatically retry requests when
8995 receiving an error response with status 403 (Forbidden),
8996 500 (Internal Error), 501 or 503 (Service not available).
8997 Status 502 and 504 (Gateway errors) are always retried.
8999 This is mainly useful if you are in a complex cache hierarchy to
9000 work around access control errors.
9002 NOTE: This retry will attempt to find another working destination.
9003 Which is different from the server which just failed.
9006 NAME: as_whois_server
9008 LOC: Config.as_whois_server
9009 DEFAULT: whois.ra.net
9011 WHOIS server to query for AS numbers. NOTE: AS numbers are
9012 queried only when Squid starts up, not for every request.
9017 LOC: Config.onoff.offline
9020 Enable this option and Squid will never try to validate cached
9024 NAME: uri_whitespace
9025 TYPE: uri_whitespace
9026 LOC: Config.uri_whitespace
9029 What to do with requests that have whitespace characters in the
9032 strip: The whitespace characters are stripped out of the URL.
9033 This is the behavior recommended by RFC2396 and RFC3986
9034 for tolerant handling of generic URI.
9035 NOTE: This is one difference between generic URI and HTTP URLs.
9037 deny: The request is denied. The user receives an "Invalid
9039 This is the behaviour recommended by RFC2616 for safe
9040 handling of HTTP request URL.
9042 allow: The request is allowed and the URI is not changed. The
9043 whitespace characters remain in the URI. Note the
9044 whitespace is passed to redirector processes if they
9046 Note this may be considered a violation of RFC2616
9047 request parsing where whitespace is prohibited in the
9050 encode: The request is allowed and the whitespace characters are
9051 encoded according to RFC1738.
9053 chop: The request is allowed and the URI is chopped at the
9057 NOTE the current Squid implementation of encode and chop violates
9058 RFC2616 by not using a 301 redirect after altering the URL.
9063 LOC: Config.chroot_dir
9066 Specifies a directory where Squid should do a chroot() while
9067 initializing. This also causes Squid to fully drop root
9068 privileges after initializing. This means, for example, if you
9069 use a HTTP port less than 1024 and try to reconfigure, you may
9070 get an error saying that Squid can not open the port.
9073 NAME: balance_on_multiple_ip
9075 LOC: Config.onoff.balance_on_multiple_ip
9078 Modern IP resolvers in squid sort lookup results by preferred access.
9079 By default squid will use these IP in order and only rotates to
9080 the next listed when the most preffered fails.
9082 Some load balancing servers based on round robin DNS have been
9083 found not to preserve user session state across requests
9084 to different IP addresses.
9086 Enabling this directive Squid rotates IP's per request.
9089 NAME: pipeline_prefetch
9090 TYPE: pipelinePrefetch
9091 LOC: Config.pipeline_max_prefetch
9093 DEFAULT_DOC: Do not pre-parse pipelined requests.
9095 HTTP clients may send a pipeline of 1+N requests to Squid using a
9096 single connection, without waiting for Squid to respond to the first
9097 of those requests. This option limits the number of concurrent
9098 requests Squid will try to handle in parallel. If set to N, Squid
9099 will try to receive and process up to 1+N requests on the same
9100 connection concurrently.
9102 Defaults to 0 (off) for bandwidth management and access logging
9105 NOTE: pipelining requires persistent connections to clients.
9107 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication.
9110 NAME: high_response_time_warning
9113 LOC: Config.warnings.high_rptm
9115 DEFAULT_DOC: disabled.
9117 If the one-minute median response time exceeds this value,
9118 Squid prints a WARNING with debug level 0 to get the
9119 administrators attention. The value is in milliseconds.
9122 NAME: high_page_fault_warning
9124 LOC: Config.warnings.high_pf
9126 DEFAULT_DOC: disabled.
9128 If the one-minute average page fault rate exceeds this
9129 value, Squid prints a WARNING with debug level 0 to get
9130 the administrators attention. The value is in page faults
9134 NAME: high_memory_warning
9136 LOC: Config.warnings.high_memory
9137 IFDEF: HAVE_MSTATS&&HAVE_GNUMALLOC_H
9139 DEFAULT_DOC: disabled.
9141 If the memory usage (as determined by gnumalloc, if available and used)
9142 exceeds this amount, Squid prints a WARNING with debug level 0 to get
9143 the administrators attention.
9145 # TODO: link high_memory_warning to mempools?
9147 NAME: sleep_after_fork
9148 COMMENT: (microseconds)
9150 LOC: Config.sleep_after_fork
9153 When this is set to a non-zero value, the main Squid process
9154 sleeps the specified number of microseconds after a fork()
9155 system call. This sleep may help the situation where your
9156 system reports fork() failures due to lack of (virtual)
9157 memory. Note, however, if you have a lot of child
9158 processes, these sleep delays will add up and your
9159 Squid will not service requests for some amount of time
9160 until all the child processes have been started.
9161 On Windows value less then 1000 (1 milliseconds) are
9165 NAME: windows_ipaddrchangemonitor
9166 IFDEF: _SQUID_WINDOWS_
9170 LOC: Config.onoff.WIN32_IpAddrChangeMonitor
9172 On Windows Squid by default will monitor IP address changes and will
9173 reconfigure itself after any detected event. This is very useful for
9174 proxies connected to internet with dial-up interfaces.
9175 In some cases (a Proxy server acting as VPN gateway is one) it could be
9176 desiderable to disable this behaviour setting this to 'off'.
9177 Note: after changing this, Squid service must be restarted.
9182 IFDEF: USE_SQUID_EUI
9184 LOC: Eui::TheConfig.euiLookup
9186 Whether to lookup the EUI or MAC address of a connected client.
9189 NAME: max_filedescriptors max_filedesc
9192 DEFAULT_DOC: Use operating system limits set by ulimit.
9193 LOC: Config.max_filedescriptors
9195 Reduce the maximum number of filedescriptors supported below
9196 the usual operating system defaults.
9198 Remove from squid.conf to inherit the current ulimit setting.
9200 Note: Changing this requires a restart of Squid. Also
9201 not all I/O types supports large values (eg on Windows).
9208 DEFAULT_DOC: SMP support disabled.
9210 Number of main Squid processes or "workers" to fork and maintain.
9211 0: "no daemon" mode, like running "squid -N ..."
9212 1: "no SMP" mode, start one main Squid process daemon (default)
9213 N: start N main Squid process daemons (i.e., SMP mode)
9215 In SMP mode, each worker does nearly all what a single Squid daemon
9216 does (e.g., listen on http_port and forward HTTP requests).
9219 NAME: cpu_affinity_map
9220 TYPE: CpuAffinityMap
9221 LOC: Config.cpuAffinityMap
9223 DEFAULT_DOC: Let operating system decide.
9225 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
9227 Sets 1:1 mapping between Squid processes and CPU cores. For example,
9229 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
9231 affects processes 1 through 4 only and places them on the first
9232 four even cores, starting with core #1.
9234 CPU cores are numbered starting from 1. Requires support for
9235 sched_getaffinity(2) and sched_setaffinity(2) system calls.
9237 Multiple cpu_affinity_map options are merged.
projects / thirdparty / squid.git / blob