1 ## Copyright (C) 1996-2015 The Squid Software Foundation and contributors
3 ## Squid software is distributed under GPLv2+ license and includes
4 ## contributions from numerous individuals and organizations.
5 ## Please see the COPYING and CONTRIBUTORS files for details.
10 ----------------------------
12 This is the documentation for the Squid configuration file.
13 This documentation can also be found online at:
14 http://www.squid-cache.org/Doc/config/
16 You may wish to look at the Squid home page and wiki for the
17 FAQ and other documentation:
18 http://www.squid-cache.org/
19 http://wiki.squid-cache.org/SquidFaq
20 http://wiki.squid-cache.org/ConfigExamples
22 This documentation shows what the defaults for various directives
23 happen to be. If you don't need to change the default, you should
24 leave the line out of your squid.conf in most cases.
26 In some cases "none" refers to no default setting at all,
27 while in other cases it refers to the value of the option
28 - the comments for that keyword indicate if this is the case.
33 Configuration options can be included using the "include" directive.
34 Include takes a list of files to include. Quoting and wildcards are
39 include /path/to/included/file/squid.acl.config
41 Includes can be nested up to a hard-coded depth of 16 levels.
42 This arbitrary restriction is to prevent recursive include references
43 from causing Squid entering an infinite loop whilst trying to load
46 Values with byte units
48 Squid accepts size units on some size related directives. All
49 such directives are documented with a default value displaying
52 Units accepted by Squid are:
54 KB - Kilobyte (1024 bytes)
58 Values with spaces, quotes, and other special characters
60 Squid supports directive parameters with spaces, quotes, and other
61 special characters. Surround such parameters with "double quotes". Use
62 the configuration_includes_quoted_values directive to enable or
65 Squid supports reading configuration option parameters from external
66 files using the syntax:
67 parameters("/path/filename")
69 acl whitelist dstdomain parameters("/etc/squid/whitelist.txt")
71 Conditional configuration
73 If-statements can be used to make configuration directives
77 ... regular configuration directives ...
79 ... regular configuration directives ...]
82 The else part is optional. The keywords "if", "else", and "endif"
83 must be typed on their own lines, as if they were regular
84 configuration directives.
86 NOTE: An else-if condition is not supported.
88 These individual conditions types are supported:
91 Always evaluates to true.
93 Always evaluates to false.
95 Equality comparison of two integer numbers.
100 The following SMP-related preprocessor macros can be used.
102 ${process_name} expands to the current Squid process "name"
103 (e.g., squid1, squid2, or cache1).
105 ${process_number} expands to the current Squid process
106 identifier, which is an integer number (e.g., 1, 2, 3) unique
107 across all Squid processes of the current service instance.
109 ${service_name} expands into the current Squid service instance
110 name identifier which is provided by -n on the command line.
114 # options still not yet ported from 2.7 to 3.x
115 NAME: broken_vary_encoding
118 This option is not yet supported by Squid-3.
124 This option is not yet supported by Squid-3.
130 This option is not yet supported by Squid-3.
133 NAME: external_refresh_check
136 This option is not yet supported by Squid-3.
139 NAME: location_rewrite_program location_rewrite_access location_rewrite_children location_rewrite_concurrency
142 This option is not yet supported by Squid-3.
145 NAME: refresh_stale_hit
148 This option is not yet supported by Squid-3.
151 # Options removed in 3.6
152 NAME: cache_peer_domain cache_host_domain
155 Replace with dstdomain ACLs and cache_peer_access.
158 # Options removed in 3.5
159 NAME: hierarchy_stoplist
162 Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use.
165 # Options removed in 3.4
169 Remove this line. Use acls with access_log directives to control access logging
175 Remove this line. Use acls with icap_log directives to control icap logging
178 # Options Removed in 3.3
179 NAME: ignore_ims_on_miss
182 Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'.
185 # Options Removed in 3.2
186 NAME: chunked_request_body_max_size
189 Remove this line. Squid is now HTTP/1.1 compliant.
192 NAME: dns_v4_fallback
195 Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant.
198 NAME: emulate_httpd_log
201 Replace this with an access_log directive using the format 'common' or 'combined'.
207 Use a regular access.log with ACL limiting it to MISS events.
213 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
216 NAME: ignore_expect_100
219 Remove this line. The HTTP/1.1 feature is now fully supported by default.
225 Remove this option from your config. To log FQDN use %>A in the log format.
228 NAME: log_ip_on_direct
231 Remove this option from your config. To log server or peer names use %<A in the log format.
234 NAME: maximum_single_addr_tries
237 Replaced by connect_retries. The behaviour has changed, please read the documentation before altering.
240 NAME: referer_log referrer_log
243 Replace this with an access_log directive using the format 'referrer'.
249 Remove this line. The feature is supported by default in storage types where update is implemented.
252 NAME: url_rewrite_concurrency
255 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead.
261 Replace this with an access_log directive using the format 'useragent'.
264 # Options Removed in 3.1
268 Remove this line. DNS is no longer tested on startup.
271 NAME: extension_methods
274 Remove this line. All valid methods for HTTP are accepted by default.
277 # 2.7 Options Removed/Replaced in 3.2
282 # 2.7 Options Removed/Replaced in 3.1
290 Remove this line. HTTP/1.1 is supported by default.
293 NAME: upgrade_http0.9
296 Remove this line. ICY/1.0 streaming protocol is supported by default.
299 NAME: zph_local zph_mode zph_option zph_parent zph_sibling
302 Alter these entries. Use the qos_flows directive instead.
305 # Options Removed in 3.0
309 Since squid-3.0 replace with request_header_access or reply_header_access
310 depending on whether you wish to match client requests or server replies.
313 NAME: httpd_accel_no_pmtu_disc
316 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
319 NAME: wais_relay_host
322 Replace this line with 'cache_peer' configuration.
325 NAME: wais_relay_port
328 Replace this line with 'cache_peer' configuration.
332 OPTIONS FOR AUTHENTICATION
333 -----------------------------------------------------------------------------
342 This is used to define parameters for the various authentication
343 schemes supported by Squid.
345 format: auth_param scheme parameter [setting]
347 The order in which authentication schemes are presented to the client is
348 dependent on the order the scheme first appears in config file. IE
349 has a bug (it's not RFC 2617 compliant) in that it will use the basic
350 scheme if basic is the first entry presented, even if more secure
351 schemes are presented. For now use the order in the recommended
352 settings section below. If other browsers have difficulties (don't
353 recognize the schemes offered even if you are using basic) either
354 put basic first, or disable the other schemes (by commenting out their
357 Once an authentication scheme is fully configured, it can only be
358 shutdown by shutting squid down and restarting. Changes can be made on
359 the fly and activated with a reconfigure. I.E. You can change to a
360 different helper, but not unconfigure the helper completely.
362 Please note that while this directive defines how Squid processes
363 authentication it does not automatically activate authentication.
364 To use authentication you must in addition make use of ACLs based
365 on login name in http_access (proxy_auth, proxy_auth_regex or
366 external with %LOGIN used in the format tag). The browser will be
367 challenged for authentication on the first such acl encountered
368 in http_access processing and will also be re-challenged for new
369 login credentials if the request is being denied by a proxy_auth
372 WARNING: authentication can't be used in a transparently intercepting
373 proxy as the client then thinks it is talking to an origin server and
374 not the proxy. This is a limitation of bending the TCP/IP protocol to
375 transparently intercepting port 80, not a limitation in Squid.
376 Ports flagged 'transparent', 'intercept', or 'tproxy' have
377 authentication disabled.
379 === Parameters common to all schemes. ===
382 Specifies the command for the external authenticator.
384 By default, each authentication scheme is not used unless a
385 program is specified.
387 See http://wiki.squid-cache.org/Features/AddonHelpers for
388 more details on helper operations and creating your own.
391 Specifies a string to be append to request line format for
392 the authentication helper. "Quoted" format values may contain
393 spaces and logformat %macros. In theory, any logformat %macro
394 can be used. In practice, a %macro expands as a dash (-) if
395 the helper request is sent before the required macro
396 information is available to Squid.
398 By default, Squid uses request formats provided in
399 scheme-specific examples below (search for %credentials).
401 The expanded key_extras value is added to the Squid credentials
402 cache and, hence, will affect authentication. It can be used to
403 autenticate different users with identical user names (e.g.,
404 when user authentication depends on http_port).
406 Avoid adding frequently changing information to key_extras. For
407 example, if you add user source IP, and it changes frequently
408 in your environment, then max_user_ip ACL is going to treat
409 every user+IP combination as a unique "user", breaking the ACL
410 and wasting a lot of memory on those user records. It will also
411 force users to authenticate from scratch whenever their IP
415 Specifies the protection scope (aka realm name) which is to be
416 reported to the client for the authentication scheme. It is
417 commonly part of the text the user will see when prompted for
418 their username and password.
420 For Basic the default is "Squid proxy-caching web server".
421 For Digest there is no default, this parameter is mandatory.
422 For NTLM and Negotiate this parameter is ignored.
424 "children" numberofchildren [startup=N] [idle=N] [concurrency=N] [queue-size=N]
426 The maximum number of authenticator processes to spawn. If
427 you start too few Squid will have to wait for them to process
428 a backlog of credential verifications, slowing it down. When
429 password verifications are done via a (slow) network you are
430 likely to need lots of authenticator processes.
432 The startup= and idle= options permit some skew in the exact
433 amount run. A minimum of startup=N will begin during startup
434 and reconfigure. Squid will start more in groups of up to
435 idle=N in an attempt to meet traffic needs and to keep idle=N
436 free above those traffic needs up to the maximum.
438 The concurrency= option sets the number of concurrent requests
439 the helper can process. The default of 0 is used for helpers
440 who only supports one request at a time. Setting this to a
441 number greater than 0 changes the protocol used to include a
442 channel ID field first on the request/response line, allowing
443 multiple requests to be sent to the same helper in parallel
444 without waiting for the response.
446 Concurrency must not be set unless it's known the helper
447 supports the input format with channel-ID fields.
449 The queue-size= option sets the maximum number of queued
450 requests. If the queued requests exceed queue size for more
451 than 3 minutes then squid aborts its operation.
452 The default value is set to 2*numberofchildren/
454 NOTE: NTLM and Negotiate schemes do not support concurrency
455 in the Squid code module even though some helpers can.
458 IF HAVE_AUTH_MODULE_BASIC
459 === Basic authentication parameters ===
462 HTTP uses iso-latin-1 as character set, while some
463 authentication backends such as LDAP expects UTF-8. If this is
464 set to on Squid will translate the HTTP iso-latin-1 charset to
465 UTF-8 before sending the username and password to the helper.
467 "credentialsttl" timetolive
468 Specifies how long squid assumes an externally validated
469 username:password pair is valid for - in other words how
470 often the helper program is called for that user. Set this
471 low to force revalidation with short lived passwords.
473 NOTE: setting this high does not impact your susceptibility
474 to replay attacks unless you are using an one-time password
475 system (such as SecureID). If you are using such a system,
476 you will be vulnerable to replay attacks unless you also
477 use the max_user_ip ACL in an http_access rule.
479 "casesensitive" on|off
480 Specifies if usernames are case sensitive. Most user databases
481 are case insensitive allowing the same username to be spelled
482 using both lower and upper case letters, but some are case
483 sensitive. This makes a big difference for user_max_ip ACL
484 processing and similar.
487 IF HAVE_AUTH_MODULE_DIGEST
488 === Digest authentication parameters ===
491 HTTP uses iso-latin-1 as character set, while some
492 authentication backends such as LDAP expects UTF-8. If this is
493 set to on Squid will translate the HTTP iso-latin-1 charset to
494 UTF-8 before sending the username and password to the helper.
496 "nonce_garbage_interval" timeinterval
497 Specifies the interval that nonces that have been issued
498 to client_agent's are checked for validity.
500 "nonce_max_duration" timeinterval
501 Specifies the maximum length of time a given nonce will be
504 "nonce_max_count" number
505 Specifies the maximum number of times a given nonce can be
508 "nonce_strictness" on|off
509 Determines if squid requires strict increment-by-1 behavior
510 for nonce counts, or just incrementing (off - for use when
511 user agents generate nonce counts that occasionally miss 1
512 (ie, 1,2,4,6)). Default off.
514 "check_nonce_count" on|off
515 This directive if set to off can disable the nonce count check
516 completely to work around buggy digest qop implementations in
517 certain mainstream browser versions. Default on to check the
518 nonce count to protect from authentication replay attacks.
520 "post_workaround" on|off
521 This is a workaround to certain buggy browsers who send an
522 incorrect request digest in POST requests when reusing the
523 same nonce as acquired earlier on a GET request.
526 IF HAVE_AUTH_MODULE_NEGOTIATE
527 === Negotiate authentication parameters ===
530 If you experience problems with PUT/POST requests when using
531 the this authentication scheme then you can try setting this
532 to off. This will cause Squid to forcibly close the connection
533 on the initial request where the browser asks which schemes
534 are supported by the proxy.
537 IF HAVE_AUTH_MODULE_NTLM
538 === NTLM authentication parameters ===
541 If you experience problems with PUT/POST requests when using
542 the this authentication scheme then you can try setting this
543 to off. This will cause Squid to forcibly close the connection
544 on the initial request where the browser asks which schemes
545 are supported by the proxy.
548 === Example Configuration ===
550 This configuration displays the recommended authentication scheme
551 order from most to least secure with recommended minimum configuration
552 settings for each scheme:
554 #auth_param negotiate program <uncomment and complete this line to activate>
555 #auth_param negotiate children 20 startup=0 idle=1
556 #auth_param negotiate keep_alive on
558 #auth_param digest program <uncomment and complete this line to activate>
559 #auth_param digest children 20 startup=0 idle=1
560 #auth_param digest realm Squid proxy-caching web server
561 #auth_param digest nonce_garbage_interval 5 minutes
562 #auth_param digest nonce_max_duration 30 minutes
563 #auth_param digest nonce_max_count 50
565 #auth_param ntlm program <uncomment and complete this line to activate>
566 #auth_param ntlm children 20 startup=0 idle=1
567 #auth_param ntlm keep_alive on
569 #auth_param basic program <uncomment and complete this line>
570 #auth_param basic children 5 startup=5 idle=1
571 #auth_param basic realm Squid proxy-caching web server
572 #auth_param basic credentialsttl 2 hours
575 NAME: authenticate_cache_garbage_interval
578 LOC: Config.authenticateGCInterval
580 The time period between garbage collection across the username cache.
581 This is a trade-off between memory utilization (long intervals - say
582 2 days) and CPU (short intervals - say 1 minute). Only change if you
586 NAME: authenticate_ttl
589 LOC: Config.authenticateTTL
591 The time a user & their credentials stay in the logged in
592 user cache since their last request. When the garbage
593 interval passes, all user credentials that have passed their
594 TTL are removed from memory.
597 NAME: authenticate_ip_ttl
599 LOC: Config.authenticateIpTTL
602 If you use proxy authentication and the 'max_user_ip' ACL,
603 this directive controls how long Squid remembers the IP
604 addresses associated with each user. Use a small value
605 (e.g., 60 seconds) if your users might change addresses
606 quickly, as is the case with dialup. You might be safe
607 using a larger value (e.g., 2 hours) in a corporate LAN
608 environment with relatively static address assignments.
613 -----------------------------------------------------------------------------
616 NAME: external_acl_type
617 TYPE: externalAclHelper
618 LOC: Config.externalAclHelperList
621 This option defines external acl classes using a helper program
622 to look up the status
624 external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
628 ttl=n TTL in seconds for cached results (defaults to 3600
632 TTL for cached negative lookups (default same
635 grace=n Percentage remaining of TTL where a refresh of a
636 cached entry should be initiated without needing to
637 wait for a new reply. (default is for no grace period)
639 cache=n Limit the result cache size, default is 262144.
640 The expanded FORMAT value is used as the cache key, so
641 if the details in FORMAT are highly variable a larger
642 cache may be needed to produce reduction in helper load.
645 Maximum number of acl helper processes spawned to service
646 external acl lookups of this type. (default 20)
649 Minimum number of acl helper processes to spawn during
650 startup and reconfigure to service external acl lookups
651 of this type. (default 0)
654 Number of acl helper processes to keep ahead of traffic
655 loads. Squid will spawn this many at once whenever load
656 rises above the capabilities of existing processes.
657 Up to the value of children-max. (default 1)
659 concurrency=n concurrency level per process. Only used with helpers
660 capable of processing more than one query at a time.
662 queue-size=N The queue-size= option sets the maximum number of queued
663 requests. If the queued requests exceed queue size
665 The default value is set to 2*children-max.
667 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers.
669 ipv4 / ipv6 IP protocol used to communicate with this helper.
670 The default is to auto-detect IPv6 and use it when available.
673 FORMAT specifications
675 %LOGIN Authenticated user login name
676 %EXT_USER Username from previous external acl
677 %EXT_LOG Log details from previous external acl
678 %EXT_TAG Tag from previous external acl
679 %IDENT Ident user name
681 %SRCPORT Client source port
684 %PROTO Requested URL scheme
686 %PATH Requested URL path
687 %METHOD Request method
688 %MYADDR Squid interface address
689 %MYPORT Squid http_port number
690 %PATH Requested URL-path (including query-string if any)
691 %USER_CERT SSL User certificate in PEM format
692 %USER_CERTCHAIN SSL User certificate chain in PEM format
693 %USER_CERT_xx SSL User certificate subject attribute xx
694 %USER_CA_CERT_xx SSL User certificate issuer attribute xx
695 %ssl::>sni SSL client SNI sent to Squid
696 %ssl::<cert_subject SSL server certificate DN
697 %ssl::<cert_issuer SSL server certificate issuer DN
699 %>{Header} HTTP request header "Header"
701 HTTP request header "Hdr" list member "member"
703 HTTP request header list member using ; as
704 list separator. ; can be any non-alphanumeric
707 %<{Header} HTTP reply header "Header"
709 HTTP reply header "Hdr" list member "member"
711 HTTP reply header list member using ; as
712 list separator. ; can be any non-alphanumeric
715 %ACL The name of the ACL being tested.
716 %DATA The ACL arguments. If not used then any arguments
717 is automatically added at the end of the line
719 NOTE: this will encode the arguments as one token,
720 whereas the default will pass each separately.
722 %% The percent sign. Useful for helpers which need
723 an unchanging input format.
726 General request syntax:
728 [channel-ID] FORMAT-values [acl-values ...]
731 FORMAT-values consists of transaction details expanded with
732 whitespace separation per the config file FORMAT specification
733 using the FORMAT macros listed above.
735 acl-values consists of any string specified in the referencing
736 config 'acl ... external' line. see the "acl external" directive.
738 Request values sent to the helper are URL escaped to protect
739 each value in requests against whitespaces.
741 If using protocol=2.5 then the request sent to the helper is not
742 URL escaped to protect against whitespace.
744 NOTE: protocol=3.0 is deprecated as no longer necessary.
746 When using the concurrency= option the protocol is changed by
747 introducing a query channel tag in front of the request/response.
748 The query channel tag is a number between 0 and concurrency-1.
749 This value must be echoed back unchanged to Squid as the first part
750 of the response relating to its request.
753 The helper receives lines expanded per the above format specification
754 and for each input line returns 1 line starting with OK/ERR/BH result
755 code and optionally followed by additional keywords with more details.
758 General result syntax:
760 [channel-ID] result keyword=value ...
762 Result consists of one of the codes:
765 the ACL test produced a match.
768 the ACL test does not produce a match.
771 An internal error occurred in the helper, preventing
772 a result being identified.
774 The meaning of 'a match' is determined by your squid.conf
775 access control configuration. See the Squid wiki for details.
779 user= The users name (login)
781 password= The users password (for login= cache_peer option)
783 message= Message describing the reason for this response.
784 Available as %o in error pages.
785 Useful on (ERR and BH results).
787 tag= Apply a tag to a request. Only sets a tag once,
788 does not alter existing tags.
790 log= String to be logged in access.log. Available as
791 %ea in logformat specifications.
793 clt_conn_tag= Associates a TAG with the client TCP connection.
794 Please see url_rewrite_program related documentation
797 Any keywords may be sent on any response whether OK, ERR or BH.
799 All response keyword values need to be a single token with URL
800 escaping, or enclosed in double quotes (") and escaped using \ on
801 any double quotes or \ characters within the value. The wrapping
802 double quotes are removed before the value is interpreted by Squid.
803 \r and \n are also replace by CR and LF.
805 Some example key values:
809 user="J. \"Bob\" Smith"
816 DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED
817 DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID
818 DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH
819 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
820 DEFAULT: ssl::certSelfSigned ssl_error X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
823 DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
824 DEFAULT: localhost src 127.0.0.1/32 ::1
825 DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
826 DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
828 Defining an Access List
830 Every access list definition must begin with an aclname and acltype,
831 followed by either type-specific arguments or a quoted filename that
834 acl aclname acltype argument ...
835 acl aclname acltype "file" ...
837 When using "file", the file should contain one item per line.
839 Some acl types supports options which changes their default behaviour.
840 The available options are:
842 -i,+i By default, regular expressions are CASE-SENSITIVE. To make them
843 case-insensitive, use the -i option. To return case-sensitive
844 use the +i option between patterns, or make a new ACL line
847 -n Disable lookups and address type conversions. If lookup or
848 conversion is required because the parameter type (IP or
849 domain name) does not match the message address type (domain
850 name or IP), then the ACL would immediately declare a mismatch
851 without any warnings or lookups.
853 -- Used to stop processing all options, in the case the first acl
854 value has '-' character as first character (for example the '-'
855 is a valid domain name)
857 Some acl types require suspending the current request in order
858 to access some external data source.
859 Those which do are marked with the tag [slow], those which
860 don't are marked as [fast].
861 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
862 for further information
864 ***** ACL TYPES AVAILABLE *****
866 acl aclname src ip-address/mask ... # clients IP address [fast]
867 acl aclname src addr1-addr2/mask ... # range of addresses [fast]
868 acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow]
869 acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
871 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
872 # The arp ACL requires the special configure option --enable-arp-acl.
873 # Furthermore, the ARP ACL code is not portable to all operating systems.
874 # It works on Linux, Solaris, Windows, FreeBSD, and some
875 # other *BSD variants.
878 # NOTE: Squid can only determine the MAC address for clients that are on
879 # the same subnet. If the client is on a different subnet,
880 # then Squid cannot find out its MAC address.
882 acl aclname srcdomain .foo.com ...
883 # reverse lookup, from client IP [slow]
884 acl aclname dstdomain [-n] .foo.com ...
885 # Destination server from URL [fast]
886 acl aclname srcdom_regex [-i] \.foo\.com ...
887 # regex matching client name [slow]
888 acl aclname dstdom_regex [-n] [-i] \.foo\.com ...
889 # regex matching server [fast]
891 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
892 # based URL is used and no match is found. The name "none" is used
893 # if the reverse lookup fails.
895 acl aclname src_as number ...
896 acl aclname dst_as number ...
898 # Except for access control, AS numbers can be used for
899 # routing of requests to specific caches. Here's an
900 # example for routing all requests for AS#1241 and only
901 # those to mycache.mydomain.net:
902 # acl asexample dst_as 1241
903 # cache_peer_access mycache.mydomain.net allow asexample
904 # cache_peer_access mycache_mydomain.net deny all
906 acl aclname peername myPeer ...
908 # match against a named cache_peer entry
909 # set unique name= on cache_peer lines for reliable use.
911 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
921 # h1:m1 must be less than h2:m2
923 acl aclname url_regex [-i] ^http:// ...
924 # regex matching on whole URL [fast]
925 acl aclname urllogin [-i] [^a-zA-Z0-9] ...
926 # regex matching on URL login field
927 acl aclname urlpath_regex [-i] \.gif$ ...
928 # regex matching on URL path [fast]
930 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
932 acl aclname localport 3128 ... # TCP port the client connected to [fast]
933 # NP: for interception mode this is usually '80'
935 acl aclname myportname 3128 ... # *_port name [fast]
937 acl aclname proto HTTP FTP ... # request protocol [fast]
939 acl aclname method GET POST ... # HTTP request method [fast]
941 acl aclname http_status 200 301 500- 400-403 ...
942 # status code in reply [fast]
944 acl aclname browser [-i] regexp ...
945 # pattern match on User-Agent header (see also req_header below) [fast]
947 acl aclname referer_regex [-i] regexp ...
948 # pattern match on Referer header [fast]
949 # Referer is highly unreliable, so use with care
951 acl aclname ident username ...
952 acl aclname ident_regex [-i] pattern ...
953 # string match on ident output [slow]
954 # use REQUIRED to accept any non-null ident.
956 acl aclname proxy_auth [-i] username ...
957 acl aclname proxy_auth_regex [-i] pattern ...
958 # perform http authentication challenge to the client and match against
959 # supplied credentials [slow]
961 # takes a list of allowed usernames.
962 # use REQUIRED to accept any valid username.
964 # Will use proxy authentication in forward-proxy scenarios, and plain
965 # http authenticaiton in reverse-proxy scenarios
967 # NOTE: when a Proxy-Authentication header is sent but it is not
968 # needed during ACL checking the username is NOT logged
971 # NOTE: proxy_auth requires a EXTERNAL authentication program
972 # to check username/password combinations (see
973 # auth_param directive).
975 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
976 # as the browser needs to be configured for using a proxy in order
977 # to respond to proxy authentication.
979 acl aclname snmp_community string ...
980 # A community string to limit access to your SNMP Agent [fast]
983 # acl snmppublic snmp_community public
985 acl aclname maxconn number
986 # This will be matched when the client's IP address has
987 # more than <number> TCP connections established. [fast]
988 # NOTE: This only measures direct TCP links so X-Forwarded-For
989 # indirect clients are not counted.
991 acl aclname max_user_ip [-s] number
992 # This will be matched when the user attempts to log in from more
993 # than <number> different ip addresses. The authenticate_ip_ttl
994 # parameter controls the timeout on the ip entries. [fast]
995 # If -s is specified the limit is strict, denying browsing
996 # from any further IP addresses until the ttl has expired. Without
997 # -s Squid will just annoy the user by "randomly" denying requests.
998 # (the counter is reset each time the limit is reached and a
1000 # NOTE: in acceleration mode or where there is mesh of child proxies,
1001 # clients may appear to come from multiple addresses if they are
1002 # going through proxy farms, so a limit of 1 may cause user problems.
1004 acl aclname random probability
1005 # Pseudo-randomly match requests. Based on the probability given.
1006 # Probability may be written as a decimal (0.333), fraction (1/3)
1007 # or ratio of matches:non-matches (3:5).
1009 acl aclname req_mime_type [-i] mime-type ...
1010 # regex match against the mime type of the request generated
1011 # by the client. Can be used to detect file upload or some
1012 # types HTTP tunneling requests [fast]
1013 # NOTE: This does NOT match the reply. You cannot use this
1014 # to match the returned file type.
1016 acl aclname req_header header-name [-i] any\.regex\.here
1017 # regex match against any of the known request headers. May be
1018 # thought of as a superset of "browser", "referer" and "mime-type"
1021 acl aclname rep_mime_type [-i] mime-type ...
1022 # regex match against the mime type of the reply received by
1023 # squid. Can be used to detect file download or some
1024 # types HTTP tunneling requests. [fast]
1025 # NOTE: This has no effect in http_access rules. It only has
1026 # effect in rules that affect the reply data stream such as
1027 # http_reply_access.
1029 acl aclname rep_header header-name [-i] any\.regex\.here
1030 # regex match against any of the known reply headers. May be
1031 # thought of as a superset of "browser", "referer" and "mime-type"
1034 acl aclname external class_name [arguments...]
1035 # external ACL lookup via a helper class defined by the
1036 # external_acl_type directive [slow]
1038 acl aclname user_cert attribute values...
1039 # match against attributes in a user SSL certificate
1040 # attribute is one of DN/C/O/CN/L/ST [fast]
1042 acl aclname ca_cert attribute values...
1043 # match against attributes a users issuing CA SSL certificate
1044 # attribute is one of DN/C/O/CN/L/ST [fast]
1046 acl aclname ext_user username ...
1047 acl aclname ext_user_regex [-i] pattern ...
1048 # string match on username returned by external acl helper [slow]
1049 # use REQUIRED to accept any non-null user name.
1051 acl aclname tag tagvalue ...
1052 # string match on tag returned by external acl helper [fast]
1053 # DEPRECATED. Only the first tag will match with this ACL.
1054 # Use the 'note' ACL instead for handling multiple tag values.
1056 acl aclname hier_code codename ...
1057 # string match against squid hierarchy code(s); [fast]
1058 # e.g., DIRECT, PARENT_HIT, NONE, etc.
1060 # NOTE: This has no effect in http_access rules. It only has
1061 # effect in rules that affect the reply data stream such as
1062 # http_reply_access.
1064 acl aclname note name [value ...]
1065 # match transaction annotation [fast]
1066 # Without values, matches any annotation with a given name.
1067 # With value(s), matches any annotation with a given name that
1068 # also has one of the given values.
1069 # Names and values are compared using a string equality test.
1070 # Annotation sources include note and adaptation_meta directives
1071 # as well as helper and eCAP responses.
1073 acl aclname adaptation_service service ...
1074 # Matches the name of any icap_service, ecap_service,
1075 # adaptation_service_set, or adaptation_service_chain that Squid
1076 # has used (or attempted to use) for the master transaction.
1077 # This ACL must be defined after the corresponding adaptation
1078 # service is named in squid.conf. This ACL is usable with
1079 # adaptation_meta because it starts matching immediately after
1080 # the service has been selected for adaptation.
1083 acl aclname ssl_error errorname
1084 # match against SSL certificate validation error [fast]
1086 # For valid error names see in @DEFAULT_ERROR_DIR@/templates/error-details.txt
1089 # The following can be used as shortcuts for certificate properties:
1090 # [ssl::]certHasExpired: the "not after" field is in the past
1091 # [ssl::]certNotYetValid: the "not before" field is in the future
1092 # [ssl::]certUntrusted: The certificate issuer is not to be trusted.
1093 # [ssl::]certSelfSigned: The certificate is self signed.
1094 # [ssl::]certDomainMismatch: The certificate CN domain does not
1095 # match the name the name of the host we are connecting to.
1097 # The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch,
1098 # ssl::certUntrusted, and ssl::certSelfSigned can also be used as
1099 # predefined ACLs, just like the 'all' ACL.
1101 # NOTE: The ssl_error ACL is only supported with sslproxy_cert_error,
1102 # sslproxy_cert_sign, and sslproxy_cert_adapt options.
1104 acl aclname server_cert_fingerprint [-sha1] fingerprint
1105 # match against server SSL certificate fingerprint [fast]
1107 # The fingerprint is the digest of the DER encoded version
1108 # of the whole certificate. The user should use the form: XX:XX:...
1109 # Optional argument specifies the digest algorithm to use.
1110 # The SHA1 digest algorithm is the default and is currently
1111 # the only algorithm supported (-sha1).
1113 acl aclname at_step step
1114 # match against the current step during ssl_bump evaluation [fast]
1115 # Never matches and should not be used outside the ssl_bump context.
1117 # At each SslBump step, Squid evaluates ssl_bump directives to find
1118 # the next bumping action (e.g., peek or splice). Valid SslBump step
1119 # values and the corresponding ssl_bump evaluation moments are:
1120 # SslBump1: After getting TCP-level and HTTP CONNECT info.
1121 # SslBump2: After getting SSL Client Hello info.
1122 # SslBump3: After getting SSL Server Hello info.
1124 acl aclname any-of acl1 acl2 ...
1125 # match any one of the acls [fast or slow]
1126 # The first matching ACL stops further ACL evaluation.
1128 # ACLs from multiple any-of lines with the same name are ORed.
1129 # For example, A = (a1 or a2) or (a3 or a4) can be written as
1130 # acl A any-of a1 a2
1131 # acl A any-of a3 a4
1133 # This group ACL is fast if all evaluated ACLs in the group are fast
1134 # and slow otherwise.
1136 acl aclname all-of acl1 acl2 ...
1137 # match all of the acls [fast or slow]
1138 # The first mismatching ACL stops further ACL evaluation.
1140 # ACLs from multiple all-of lines with the same name are ORed.
1141 # For example, B = (b1 and b2) or (b3 and b4) can be written as
1142 # acl B all-of b1 b2
1143 # acl B all-of b3 b4
1145 # This group ACL is fast if all evaluated ACLs in the group are fast
1146 # and slow otherwise.
1149 acl macaddress arp 09:00:2b:23:45:67
1150 acl myexample dst_as 1241
1151 acl password proxy_auth REQUIRED
1152 acl fileupload req_mime_type -i ^multipart/form-data$
1153 acl javascript rep_mime_type -i ^application/x-javascript$
1157 # Recommended minimum configuration:
1160 # Example rule allowing access from your local networks.
1161 # Adapt to list your (internal) IP networks from where browsing
1163 acl localnet src 0.0.0.1-0.255.255.255 # RFC 1122 "this" network (LAN)
1164 acl localnet src 10.0.0.0/8 # RFC 1918 local private network (LAN)
1165 acl localnet src 100.64.0.0/10 # RFC 6598 shared address space (CGN)
1166 acl localhet src 169.254.0.0/16 # RFC 3927 link-local (directly plugged) machines
1167 acl localnet src 172.16.0.0/12 # RFC 1918 local private network (LAN)
1168 acl localnet src 192.168.0.0/16 # RFC 1918 local private network (LAN)
1169 acl localnet src fc00::/7 # RFC 4193 local private network range
1170 acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
1172 acl SSL_ports port 443
1173 acl Safe_ports port 80 # http
1174 acl Safe_ports port 21 # ftp
1175 acl Safe_ports port 443 # https
1176 acl Safe_ports port 70 # gopher
1177 acl Safe_ports port 210 # wais
1178 acl Safe_ports port 1025-65535 # unregistered ports
1179 acl Safe_ports port 280 # http-mgmt
1180 acl Safe_ports port 488 # gss-http
1181 acl Safe_ports port 591 # filemaker
1182 acl Safe_ports port 777 # multiling http
1183 acl CONNECT method CONNECT
1187 NAME: proxy_protocol_access
1189 LOC: Config.accessList.proxyProtocol
1191 DEFAULT_DOC: all TCP connections to ports with require-proxy-header will be denied
1193 Determine which client proxies can be trusted to provide correct
1194 information regarding real client IP address using PROXY protocol.
1196 Requests may pass through a chain of several other proxies
1197 before reaching us. The original source details may by sent in:
1198 * HTTP message Forwarded header, or
1199 * HTTP message X-Forwarded-For header, or
1200 * PROXY protocol connection header.
1202 This directive is solely for validating new PROXY protocol
1203 connections received from a port flagged with require-proxy-header.
1204 It is checked only once after TCP connection setup.
1206 A deny match results in TCP connection closure.
1208 An allow match is required for Squid to permit the corresponding
1209 TCP connection, before Squid even looks for HTTP request headers.
1210 If there is an allow match, Squid starts using PROXY header information
1211 to determine the source address of the connection for all future ACL
1212 checks, logging, etc.
1214 SECURITY CONSIDERATIONS:
1216 Any host from which we accept client IP details can place
1217 incorrect information in the relevant header, and Squid
1218 will use the incorrect information as if it were the
1219 source address of the request. This may enable remote
1220 hosts to bypass any access control restrictions that are
1221 based on the client's source addresses.
1223 This clause only supports fast acl types.
1224 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1227 NAME: follow_x_forwarded_for
1229 IFDEF: FOLLOW_X_FORWARDED_FOR
1230 LOC: Config.accessList.followXFF
1231 DEFAULT_IF_NONE: deny all
1232 DEFAULT_DOC: X-Forwarded-For header will be ignored.
1234 Determine which client proxies can be trusted to provide correct
1235 information regarding real client IP address.
1237 Requests may pass through a chain of several other proxies
1238 before reaching us. The original source details may by sent in:
1239 * HTTP message Forwarded header, or
1240 * HTTP message X-Forwarded-For header, or
1241 * PROXY protocol connection header.
1243 PROXY protocol connections are controlled by the proxy_protocol_access
1244 directive which is checked before this.
1246 If a request reaches us from a source that is allowed by this
1247 directive, then we trust the information it provides regarding
1248 the IP of the client it received from (if any).
1250 For the purpose of ACLs used in this directive the src ACL type always
1251 matches the address we are testing and srcdomain matches its rDNS.
1253 On each HTTP request Squid checks for X-Forwarded-For header fields.
1254 If found the header values are iterated in reverse order and an allow
1255 match is required for Squid to continue on to the next value.
1256 The verification ends when a value receives a deny match, cannot be
1257 tested, or there are no more values to test.
1258 NOTE: Squid does not yet follow the Forwarded HTTP header.
1260 The end result of this process is an IP address that we will
1261 refer to as the indirect client address. This address may
1262 be treated as the client address for access control, ICAP, delay
1263 pools and logging, depending on the acl_uses_indirect_client,
1264 icap_uses_indirect_client, delay_pool_uses_indirect_client,
1265 log_uses_indirect_client and tproxy_uses_indirect_client options.
1267 This clause only supports fast acl types.
1268 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1270 SECURITY CONSIDERATIONS:
1272 Any host from which we accept client IP details can place
1273 incorrect information in the relevant header, and Squid
1274 will use the incorrect information as if it were the
1275 source address of the request. This may enable remote
1276 hosts to bypass any access control restrictions that are
1277 based on the client's source addresses.
1281 acl localhost src 127.0.0.1
1282 acl my_other_proxy srcdomain .proxy.example.com
1283 follow_x_forwarded_for allow localhost
1284 follow_x_forwarded_for allow my_other_proxy
1287 NAME: acl_uses_indirect_client
1290 IFDEF: FOLLOW_X_FORWARDED_FOR
1292 LOC: Config.onoff.acl_uses_indirect_client
1294 Controls whether the indirect client address
1295 (see follow_x_forwarded_for) is used instead of the
1296 direct client address in acl matching.
1298 NOTE: maxconn ACL considers direct TCP links and indirect
1299 clients will always have zero. So no match.
1302 NAME: delay_pool_uses_indirect_client
1305 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
1307 LOC: Config.onoff.delay_pool_uses_indirect_client
1309 Controls whether the indirect client address
1310 (see follow_x_forwarded_for) is used instead of the
1311 direct client address in delay pools.
1314 NAME: log_uses_indirect_client
1317 IFDEF: FOLLOW_X_FORWARDED_FOR
1319 LOC: Config.onoff.log_uses_indirect_client
1321 Controls whether the indirect client address
1322 (see follow_x_forwarded_for) is used instead of the
1323 direct client address in the access log.
1326 NAME: tproxy_uses_indirect_client
1329 IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
1331 LOC: Config.onoff.tproxy_uses_indirect_client
1333 Controls whether the indirect client address
1334 (see follow_x_forwarded_for) is used instead of the
1335 direct client address when spoofing the outgoing client.
1337 This has no effect on requests arriving in non-tproxy
1340 SECURITY WARNING: Usage of this option is dangerous
1341 and should not be used trivially. Correct configuration
1342 of follow_x_forewarded_for with a limited set of trusted
1343 sources is required to prevent abuse of your proxy.
1346 NAME: spoof_client_ip
1348 LOC: Config.accessList.spoof_client_ip
1350 DEFAULT_DOC: Allow spoofing on all TPROXY traffic.
1352 Control client IP address spoofing of TPROXY traffic based on
1353 defined access lists.
1355 spoof_client_ip allow|deny [!]aclname ...
1357 If there are no "spoof_client_ip" lines present, the default
1358 is to "allow" spoofing of any suitable request.
1360 Note that the cache_peer "no-tproxy" option overrides this ACL.
1362 This clause supports fast acl types.
1363 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1368 LOC: Config.accessList.http
1369 DEFAULT_IF_NONE: deny all
1370 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1372 Allowing or Denying access based on defined access lists
1374 To allow or deny a message received on an HTTP, HTTPS, or FTP port:
1375 http_access allow|deny [!]aclname ...
1377 NOTE on default values:
1379 If there are no "access" lines present, the default is to deny
1382 If none of the "access" lines cause a match, the default is the
1383 opposite of the last line in the list. If the last line was
1384 deny, the default is allow. Conversely, if the last line
1385 is allow, the default will be deny. For these reasons, it is a
1386 good idea to have an "deny all" entry at the end of your access
1387 lists to avoid potential confusion.
1389 This clause supports both fast and slow acl types.
1390 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1395 # Recommended minimum Access Permission configuration:
1397 # Deny requests to certain unsafe ports
1398 http_access deny !Safe_ports
1400 # Deny CONNECT to other than secure SSL ports
1401 http_access deny CONNECT !SSL_ports
1403 # Only allow cachemgr access from localhost
1404 http_access allow localhost manager
1405 http_access deny manager
1407 # We strongly recommend the following be uncommented to protect innocent
1408 # web applications running on the proxy server who think the only
1409 # one who can access services on "localhost" is a local user
1410 #http_access deny to_localhost
1413 # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
1416 # Example rule allowing access from your local networks.
1417 # Adapt localnet in the ACL section to list your (internal) IP networks
1418 # from where browsing should be allowed
1419 http_access allow localnet
1420 http_access allow localhost
1422 # And finally deny all other access to this proxy
1423 http_access deny all
1427 NAME: adapted_http_access http_access2
1429 LOC: Config.accessList.adapted_http
1431 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1433 Allowing or Denying access based on defined access lists
1435 Essentially identical to http_access, but runs after redirectors
1436 and ICAP/eCAP adaptation. Allowing access control based on their
1439 If not set then only http_access is used.
1442 NAME: http_reply_access
1444 LOC: Config.accessList.reply
1446 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1448 Allow replies to client requests. This is complementary to http_access.
1450 http_reply_access allow|deny [!] aclname ...
1452 NOTE: if there are no access lines present, the default is to allow
1455 If none of the access lines cause a match the opposite of the
1456 last line will apply. Thus it is good practice to end the rules
1457 with an "allow all" or "deny all" entry.
1459 This clause supports both fast and slow acl types.
1460 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1465 LOC: Config.accessList.icp
1467 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1469 Allowing or Denying access to the ICP port based on defined
1472 icp_access allow|deny [!]aclname ...
1474 NOTE: The default if no icp_access lines are present is to
1475 deny all traffic. This default may cause problems with peers
1478 This clause only supports fast acl types.
1479 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1481 # Allow ICP queries from local networks only
1482 #icp_access allow localnet
1483 #icp_access deny all
1489 LOC: Config.accessList.htcp
1491 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1493 Allowing or Denying access to the HTCP port based on defined
1496 htcp_access allow|deny [!]aclname ...
1498 See also htcp_clr_access for details on access control for
1499 cache purge (CLR) HTCP messages.
1501 NOTE: The default if no htcp_access lines are present is to
1502 deny all traffic. This default may cause problems with peers
1503 using the htcp option.
1505 This clause only supports fast acl types.
1506 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1508 # Allow HTCP queries from local networks only
1509 #htcp_access allow localnet
1510 #htcp_access deny all
1513 NAME: htcp_clr_access
1516 LOC: Config.accessList.htcp_clr
1518 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1520 Allowing or Denying access to purge content using HTCP based
1521 on defined access lists.
1522 See htcp_access for details on general HTCP access control.
1524 htcp_clr_access allow|deny [!]aclname ...
1526 This clause only supports fast acl types.
1527 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1529 # Allow HTCP CLR requests from trusted peers
1530 acl htcp_clr_peer src 192.0.2.2 2001:DB8::2
1531 htcp_clr_access allow htcp_clr_peer
1532 htcp_clr_access deny all
1537 LOC: Config.accessList.miss
1539 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1541 Determins whether network access is permitted when satisfying a request.
1544 to force your neighbors to use you as a sibling instead of
1547 acl localclients src 192.0.2.0/24 2001:DB8::a:0/64
1548 miss_access deny !localclients
1549 miss_access allow all
1551 This means only your local clients are allowed to fetch relayed/MISS
1552 replies from the network and all other clients can only fetch cached
1555 The default for this setting allows all clients who passed the
1556 http_access rules to relay via this proxy.
1558 This clause only supports fast acl types.
1559 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1562 NAME: ident_lookup_access
1566 DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched.
1567 LOC: Ident::TheConfig.identLookup
1569 A list of ACL elements which, if matched, cause an ident
1570 (RFC 931) lookup to be performed for this request. For
1571 example, you might choose to always perform ident lookups
1572 for your main multi-user Unix boxes, but not for your Macs
1573 and PCs. By default, ident lookups are not performed for
1576 To enable ident lookups for specific client addresses, you
1577 can follow this example:
1579 acl ident_aware_hosts src 198.168.1.0/24
1580 ident_lookup_access allow ident_aware_hosts
1581 ident_lookup_access deny all
1583 Only src type ACL checks are fully supported. A srcdomain
1584 ACL might work at times, but it will not always provide
1587 This clause only supports fast acl types.
1588 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1591 NAME: reply_body_max_size
1592 COMMENT: size [acl acl...]
1595 DEFAULT_DOC: No limit is applied.
1596 LOC: Config.ReplyBodySize
1598 This option specifies the maximum size of a reply body. It can be
1599 used to prevent users from downloading very large files, such as
1600 MP3's and movies. When the reply headers are received, the
1601 reply_body_max_size lines are processed, and the first line where
1602 all (if any) listed ACLs are true is used as the maximum body size
1605 This size is checked twice. First when we get the reply headers,
1606 we check the content-length value. If the content length value exists
1607 and is larger than the allowed size, the request is denied and the
1608 user receives an error message that says "the request or reply
1609 is too large." If there is no content-length, and the reply
1610 size exceeds this limit, the client's connection is just closed
1611 and they will receive a partial reply.
1613 WARNING: downstream caches probably can not detect a partial reply
1614 if there is no content-length header, so they will cache
1615 partial responses and give them out as hits. You should NOT
1616 use this option if you have downstream caches.
1618 WARNING: A maximum size smaller than the size of squid's error messages
1619 will cause an infinite loop and crash squid. Ensure that the smallest
1620 non-zero value you use is greater that the maximum header size plus
1621 the size of your largest error page.
1623 If you set this parameter none (the default), there will be
1626 Configuration Format is:
1627 reply_body_max_size SIZE UNITS [acl ...]
1629 reply_body_max_size 10 MB
1633 NAME: on_unsupported_protocol
1634 TYPE: on_unsupported_protocol
1635 LOC: Config.accessList.on_unsupported_protocol
1637 DEFAULT_DOC: Respond with an error message to unidentifiable traffic
1639 Determines Squid behavior when encountering strange requests at the
1640 beginning of an accepted TCP connection. This is especially useful in
1641 interception environments where Squid is likely to see connections for
1642 unsupported protocols that Squid should either terminate or tunnel at
1645 on_unsupported_protocol <action> [!]acl ...
1647 The first matching action wins.
1649 Supported actions are:
1651 tunnel: Establish a TCP connection with the intended server and
1652 blindly shovel TCP packets between the client and server.
1654 respond: Respond with an error message, using the transfer protocol
1655 for the Squid port that received the request (e.g., HTTP
1656 for connections intercepted at the http_port). This is the
1659 Currently, this directive is ignored for non-intercepted connections
1660 because Squid cannot know what their intended destination is.
1663 # define what Squid errors indicate receiving non-HTTP traffic:
1664 acl foreignProtocol squid_error ERR_PROTOCOL_UNKNOWN ERR_TOO_BIG
1665 # define what Squid errors indicate receiving nothing:
1666 acl serverTalksFirstProtocol squid_error ERR_REQUEST_START_TIMEOUT
1667 # tunnel everything that does not look like HTTP:
1668 on_unsupported_protocol tunnel foreignProtocol
1669 # tunnel if we think the client waits for the server to talk first:
1670 on_unsupported_protocol tunnel serverTalksFirstProtocol
1671 # in all other error cases, just send an HTTP "error page" response:
1672 on_unsupported_protocol respond all
1674 See also: squid_error ACL
1679 -----------------------------------------------------------------------------
1682 NAME: http_port ascii_port
1687 Usage: port [mode] [options]
1688 hostname:port [mode] [options]
1689 1.2.3.4:port [mode] [options]
1691 The socket addresses where Squid will listen for HTTP client
1692 requests. You may specify multiple socket addresses.
1693 There are three forms: port alone, hostname with port, and
1694 IP address with port. If you specify a hostname or IP
1695 address, Squid binds the socket to that specific
1696 address. Most likely, you do not need to bind to a specific
1697 address, so you can use the port number alone.
1699 If you are running Squid in accelerator mode, you
1700 probably want to listen on port 80 also, or instead.
1702 The -a command line option may be used to specify additional
1703 port(s) where Squid listens for proxy request. Such ports will
1704 be plain proxy ports with no options.
1706 You may specify multiple socket addresses on multiple lines.
1710 intercept Support for IP-Layer interception of
1711 outgoing requests without browser settings.
1712 NP: disables authentication and IPv6 on the port.
1714 tproxy Support Linux TPROXY for spoofing outgoing
1715 connections using the client IP address.
1716 NP: disables authentication and maybe IPv6 on the port.
1718 accel Accelerator / reverse proxy mode
1720 ssl-bump For each CONNECT request allowed by ssl_bump ACLs,
1721 establish secure connection with the client and with
1722 the server, decrypt HTTPS messages as they pass through
1723 Squid, and treat them as unencrypted HTTP messages,
1724 becoming the man-in-the-middle.
1726 The ssl_bump option is required to fully enable
1727 bumping of CONNECT requests.
1729 Omitting the mode flag causes default forward proxy mode to be used.
1732 Accelerator Mode Options:
1734 defaultsite=domainname
1735 What to use for the Host: header if it is not present
1736 in a request. Determines what site (not origin server)
1737 accelerators should consider the default.
1739 no-vhost Disable using HTTP/1.1 Host header for virtual domain support.
1741 protocol= Protocol to reconstruct accelerated and intercepted
1742 requests with. Defaults to HTTP/1.1 for http_port and
1743 HTTPS/1.1 for https_port.
1744 When an unsupported value is configured Squid will
1745 produce a FATAL error.
1746 Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1
1748 vport Virtual host port support. Using the http_port number
1749 instead of the port passed on Host: headers.
1751 vport=NN Virtual host port support. Using the specified port
1752 number instead of the port passed on Host: headers.
1755 Act as if this Squid is the origin server.
1756 This currently means generate new Date: and Expires:
1757 headers on HIT instead of adding Age:.
1759 ignore-cc Ignore request Cache-Control headers.
1761 WARNING: This option violates HTTP specifications if
1762 used in non-accelerator setups.
1764 allow-direct Allow direct forwarding in accelerator mode. Normally
1765 accelerated requests are denied direct forwarding as if
1766 never_direct was used.
1768 WARNING: this option opens accelerator mode to security
1769 vulnerabilities usually only affecting in interception
1770 mode. Make sure to protect forwarding with suitable
1771 http_access rules when using this.
1774 SSL Bump Mode Options:
1775 In addition to these options ssl-bump requires TLS/SSL options.
1777 generate-host-certificates[=<on|off>]
1778 Dynamically create SSL server certificates for the
1779 destination hosts of bumped CONNECT requests.When
1780 enabled, the cert and key options are used to sign
1781 generated certificates. Otherwise generated
1782 certificate will be selfsigned.
1783 If there is a CA certificate lifetime of the generated
1784 certificate equals lifetime of the CA certificate. If
1785 generated certificate is selfsigned lifetime is three
1787 This option is enabled by default when ssl-bump is used.
1788 See the ssl-bump option above for more information.
1790 dynamic_cert_mem_cache_size=SIZE
1791 Approximate total RAM size spent on cached generated
1792 certificates. If set to zero, caching is disabled. The
1793 default value is 4MB.
1797 cert= Path to SSL certificate (PEM format).
1799 key= Path to SSL private key file (PEM format)
1800 if not specified, the certificate file is
1801 assumed to be a combined certificate and
1804 version= The version of SSL/TLS supported
1805 1 automatic (default)
1811 cipher= Colon separated list of supported ciphers.
1812 NOTE: some ciphers such as EDH ciphers depend on
1813 additional settings. If those settings are
1814 omitted the ciphers may be silently ignored
1815 by the OpenSSL library.
1817 options= Various SSL implementation options. The most important
1819 NO_SSLv3 Disallow the use of SSLv3
1820 NO_TLSv1 Disallow the use of TLSv1.0
1821 NO_TLSv1_1 Disallow the use of TLSv1.1
1822 NO_TLSv1_2 Disallow the use of TLSv1.2
1823 SINGLE_DH_USE Always create a new key when using
1824 temporary/ephemeral DH key exchanges
1825 NO_TICKET Disables TLS tickets extension
1826 ALL Enable various bug workarounds
1827 suggested as "harmless" by OpenSSL
1828 Be warned that this reduces SSL/TLS
1829 strength to some attacks.
1830 See OpenSSL SSL_CTX_set_options documentation for a
1831 complete list of options.
1833 clientca= File containing the list of CAs to use when
1834 requesting a client certificate.
1836 cafile= File containing additional CA certificates to
1837 use when verifying client certificates. If unset
1838 clientca will be used.
1840 capath= Directory containing additional CA certificates
1841 and CRL lists to use when verifying client certificates.
1843 crlfile= File of additional CRL lists to use when verifying
1844 the client certificate, in addition to CRLs stored in
1845 the capath. Implies VERIFY_CRL flag below.
1847 dhparams= File containing DH parameters for temporary/ephemeral
1848 DH key exchanges. See OpenSSL documentation for details
1849 on how to create this file.
1850 WARNING: EDH ciphers will be silently disabled if this
1853 sslflags= Various flags modifying the use of SSL:
1855 Don't request client certificates
1856 immediately, but wait until acl processing
1857 requires a certificate (not yet implemented).
1859 Don't use the default CA lists built in
1862 Don't allow for session reuse. Each connection
1863 will result in a new SSL session.
1865 Verify CRL lists when accepting client
1868 Verify CRL lists for all certificates in the
1869 client certificate chain.
1871 sslcontext= SSL session ID context identifier.
1875 connection-auth[=on|off]
1876 use connection-auth=off to tell Squid to prevent
1877 forwarding Microsoft connection oriented authentication
1878 (NTLM, Negotiate and Kerberos)
1880 disable-pmtu-discovery=
1881 Control Path-MTU discovery usage:
1882 off lets OS decide on what to do (default).
1883 transparent disable PMTU discovery when transparent
1885 always disable always PMTU discovery.
1887 In many setups of transparently intercepting proxies
1888 Path-MTU discovery can not work on traffic towards the
1889 clients. This is the case when the intercepting device
1890 does not fully track connections and fails to forward
1891 ICMP must fragment messages to the cache server. If you
1892 have such setup and experience that certain clients
1893 sporadically hang or never complete requests set
1894 disable-pmtu-discovery option to 'transparent'.
1896 name= Specifies a internal name for the port. Defaults to
1897 the port specification (port or addr:port)
1899 tcpkeepalive[=idle,interval,timeout]
1900 Enable TCP keepalive probes of idle connections.
1901 In seconds; idle is the initial time before TCP starts
1902 probing the connection, interval how often to probe, and
1903 timeout the time before giving up.
1905 require-proxy-header
1906 Require PROXY protocol version 1 or 2 connections.
1907 The proxy_protocol_access is required to whitelist
1908 downstream proxies which can be trusted.
1910 If you run Squid on a dual-homed machine with an internal
1911 and an external interface we recommend you to specify the
1912 internal address:port in http_port. This way Squid will only be
1913 visible on the internal address.
1917 # Squid normally listens to port 3128
1918 http_port @DEFAULT_HTTP_PORT@
1928 Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...]
1930 The socket address where Squid will listen for client requests made
1931 over TLS or SSL connections. Commonly referred to as HTTPS.
1933 This is most useful for situations where you are running squid in
1934 accelerator mode and you want to do the SSL work at the accelerator level.
1936 You may specify multiple socket addresses on multiple lines,
1937 each with their own SSL certificate and/or options.
1941 accel Accelerator / reverse proxy mode
1943 intercept Support for IP-Layer interception of
1944 outgoing requests without browser settings.
1945 NP: disables authentication and IPv6 on the port.
1947 tproxy Support Linux TPROXY for spoofing outgoing
1948 connections using the client IP address.
1949 NP: disables authentication and maybe IPv6 on the port.
1951 ssl-bump For each intercepted connection allowed by ssl_bump
1952 ACLs, establish a secure connection with the client and with
1953 the server, decrypt HTTPS messages as they pass through
1954 Squid, and treat them as unencrypted HTTP messages,
1955 becoming the man-in-the-middle.
1957 An "ssl_bump server-first" match is required to
1958 fully enable bumping of intercepted SSL connections.
1960 Requires tproxy or intercept.
1962 Omitting the mode flag causes default forward proxy mode to be used.
1965 See http_port for a list of generic options
1970 cert= Path to SSL certificate (PEM format).
1972 key= Path to SSL private key file (PEM format)
1973 if not specified, the certificate file is
1974 assumed to be a combined certificate and
1977 version= The version of SSL/TLS supported
1978 1 automatic (default)
1982 cipher= Colon separated list of supported ciphers.
1984 options= Various SSL engine options. The most important
1986 NO_SSLv3 Disallow the use of SSLv3
1987 NO_TLSv1 Disallow the use of TLSv1
1988 SINGLE_DH_USE Always create a new key when using
1989 temporary/ephemeral DH key exchanges
1990 See src/ssl_support.c or OpenSSL SSL_CTX_set_options
1991 documentation for a complete list of options.
1993 clientca= File containing the list of CAs to use when
1994 requesting a client certificate.
1996 cafile= File containing additional CA certificates to
1997 use when verifying client certificates. If unset
1998 clientca will be used.
2000 capath= Directory containing additional CA certificates
2001 and CRL lists to use when verifying client certificates.
2003 crlfile= File of additional CRL lists to use when verifying
2004 the client certificate, in addition to CRLs stored in
2005 the capath. Implies VERIFY_CRL flag below.
2007 dhparams= File containing DH parameters for temporary/ephemeral
2010 sslflags= Various flags modifying the use of SSL:
2012 Don't request client certificates
2013 immediately, but wait until acl processing
2014 requires a certificate (not yet implemented).
2016 Don't use the default CA lists built in
2019 Don't allow for session reuse. Each connection
2020 will result in a new SSL session.
2022 Verify CRL lists when accepting client
2025 Verify CRL lists for all certificates in the
2026 client certificate chain.
2028 sslcontext= SSL session ID context identifier.
2030 generate-host-certificates[=<on|off>]
2031 Dynamically create SSL server certificates for the
2032 destination hosts of bumped SSL requests.When
2033 enabled, the cert and key options are used to sign
2034 generated certificates. Otherwise generated
2035 certificate will be selfsigned.
2036 If there is CA certificate life time of generated
2037 certificate equals lifetime of CA certificate. If
2038 generated certificate is selfsigned lifetime is three
2040 This option is enabled by default when SslBump is used.
2041 See the sslBump option above for more information.
2043 dynamic_cert_mem_cache_size=SIZE
2044 Approximate total RAM size spent on cached generated
2045 certificates. If set to zero, caching is disabled. The
2046 default value is 4MB.
2048 See http_port for a list of available options.
2056 Enables Native FTP proxy by specifying the socket address where Squid
2057 listens for FTP client requests. See http_port directive for various
2058 ways to specify the listening address and mode.
2060 Usage: ftp_port address [mode] [options]
2062 WARNING: This is a new, experimental, complex feature that has seen
2063 limited production exposure. Some Squid modules (e.g., caching) do not
2064 currently work with native FTP proxying, and many features have not
2065 even been tested for compatibility. Test well before deploying!
2067 Native FTP proxying differs substantially from proxying HTTP requests
2068 with ftp:// URIs because Squid works as an FTP server and receives
2069 actual FTP commands (rather than HTTP requests with FTP URLs).
2071 Native FTP commands accepted at ftp_port are internally converted or
2072 wrapped into HTTP-like messages. The same happens to Native FTP
2073 responses received from FTP origin servers. Those HTTP-like messages
2074 are shoveled through regular access control and adaptation layers
2075 between the FTP client and the FTP origin server. This allows Squid to
2076 examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP
2077 mechanisms when shoveling wrapped FTP messages. For example,
2078 http_access and adaptation_access directives are used.
2082 intercept Same as http_port intercept. The FTP origin address is
2083 determined based on the intended destination of the
2084 intercepted connection.
2086 tproxy Support Linux TPROXY for spoofing outgoing
2087 connections using the client IP address.
2088 NP: disables authentication and maybe IPv6 on the port.
2090 By default (i.e., without an explicit mode option), Squid extracts the
2091 FTP origin address from the login@origin parameter of the FTP USER
2092 command. Many popular FTP clients support such native FTP proxying.
2096 name=token Specifies an internal name for the port. Defaults to
2097 the port address. Usable with myportname ACL.
2100 Enables tracking of FTP directories by injecting extra
2101 PWD commands and adjusting Request-URI (in wrapping
2102 HTTP requests) to reflect the current FTP server
2103 directory. Tracking is disabled by default.
2105 protocol=FTP Protocol to reconstruct accelerated and intercepted
2106 requests with. Defaults to FTP. No other accepted
2107 values have been tested with. An unsupported value
2108 results in a FATAL error. Accepted values are FTP,
2109 HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1).
2111 Other http_port modes and options that are not specific to HTTP and
2112 HTTPS may also work.
2115 NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
2118 LOC: Ip::Qos::TheConfig.tosToServer
2120 Allows you to select a TOS/Diffserv value for packets outgoing
2121 on the server side, based on an ACL.
2123 tcp_outgoing_tos ds-field [!]aclname ...
2125 Example where normal_service_net uses the TOS value 0x00
2126 and good_service_net uses 0x20
2128 acl normal_service_net src 10.0.0.0/24
2129 acl good_service_net src 10.0.1.0/24
2130 tcp_outgoing_tos 0x00 normal_service_net
2131 tcp_outgoing_tos 0x20 good_service_net
2133 TOS/DSCP values really only have local significance - so you should
2134 know what you're specifying. For more information, see RFC2474,
2135 RFC2475, and RFC3260.
2137 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
2138 "default" to use whatever default your host has. Note that in
2139 practice often only multiples of 4 is usable as the two rightmost bits
2140 have been redefined for use by ECN (RFC 3168 section 23.1).
2142 Processing proceeds in the order specified, and stops at first fully
2145 Only fast ACLs are supported.
2148 NAME: clientside_tos
2151 LOC: Ip::Qos::TheConfig.tosToClient
2153 Allows you to select a TOS/Diffserv value for packets being transmitted
2154 on the client-side, based on an ACL.
2156 clientside_tos ds-field [!]aclname ...
2158 Example where normal_service_net uses the TOS value 0x00
2159 and good_service_net uses 0x20
2161 acl normal_service_net src 10.0.0.0/24
2162 acl good_service_net src 10.0.1.0/24
2163 clientside_tos 0x00 normal_service_net
2164 clientside_tos 0x20 good_service_net
2166 Note: This feature is incompatible with qos_flows. Any TOS values set here
2167 will be overwritten by TOS values in qos_flows.
2170 NAME: tcp_outgoing_mark
2172 IFDEF: SO_MARK&&USE_LIBCAP
2174 LOC: Ip::Qos::TheConfig.nfmarkToServer
2176 Allows you to apply a Netfilter mark value to outgoing packets
2177 on the server side, based on an ACL.
2179 tcp_outgoing_mark mark-value [!]aclname ...
2181 Example where normal_service_net uses the mark value 0x00
2182 and good_service_net uses 0x20
2184 acl normal_service_net src 10.0.0.0/24
2185 acl good_service_net src 10.0.1.0/24
2186 tcp_outgoing_mark 0x00 normal_service_net
2187 tcp_outgoing_mark 0x20 good_service_net
2189 Only fast ACLs are supported.
2192 NAME: clientside_mark
2194 IFDEF: SO_MARK&&USE_LIBCAP
2196 LOC: Ip::Qos::TheConfig.nfmarkToClient
2198 Allows you to apply a Netfilter mark value to packets being transmitted
2199 on the client-side, based on an ACL.
2201 clientside_mark mark-value [!]aclname ...
2203 Example where normal_service_net uses the mark value 0x00
2204 and good_service_net uses 0x20
2206 acl normal_service_net src 10.0.0.0/24
2207 acl good_service_net src 10.0.1.0/24
2208 clientside_mark 0x00 normal_service_net
2209 clientside_mark 0x20 good_service_net
2211 Note: This feature is incompatible with qos_flows. Any mark values set here
2212 will be overwritten by mark values in qos_flows.
2219 LOC: Ip::Qos::TheConfig
2221 Allows you to select a TOS/DSCP value to mark outgoing
2222 connections to the client, based on where the reply was sourced.
2223 For platforms using netfilter, allows you to set a netfilter mark
2224 value instead of, or in addition to, a TOS value.
2226 By default this functionality is disabled. To enable it with the default
2227 settings simply use "qos_flows mark" or "qos_flows tos". Default
2228 settings will result in the netfilter mark or TOS value being copied
2229 from the upstream connection to the client. Note that it is the connection
2230 CONNMARK value not the packet MARK value that is copied.
2232 It is not currently possible to copy the mark or TOS value from the
2233 client to the upstream connection request.
2235 TOS values really only have local significance - so you should
2236 know what you're specifying. For more information, see RFC2474,
2237 RFC2475, and RFC3260.
2239 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
2240 in practice often only multiples of 4 is usable as the two rightmost bits
2241 have been redefined for use by ECN (RFC 3168 section 23.1).
2243 Mark values can be any unsigned 32-bit integer value.
2245 This setting is configured by setting the following values:
2247 tos|mark Whether to set TOS or netfilter mark values
2249 local-hit=0xFF Value to mark local cache hits.
2251 sibling-hit=0xFF Value to mark hits from sibling peers.
2253 parent-hit=0xFF Value to mark hits from parent peers.
2255 miss=0xFF[/mask] Value to mark cache misses. Takes precedence
2256 over the preserve-miss feature (see below), unless
2257 mask is specified, in which case only the bits
2258 specified in the mask are written.
2260 The TOS variant of the following features are only possible on Linux
2261 and require your kernel to be patched with the TOS preserving ZPH
2262 patch, available from http://zph.bratcheda.org
2263 No patch is needed to preserve the netfilter mark, which will work
2264 with all variants of netfilter.
2266 disable-preserve-miss
2267 This option disables the preservation of the TOS or netfilter
2268 mark. By default, the existing TOS or netfilter mark value of
2269 the response coming from the remote server will be retained
2270 and masked with miss-mark.
2271 NOTE: in the case of a netfilter mark, the mark must be set on
2272 the connection (using the CONNMARK target) not on the packet
2276 Allows you to mask certain bits in the TOS or mark value
2277 received from the remote server, before copying the value to
2278 the TOS sent towards clients.
2279 Default for tos: 0xFF (TOS from server is not changed).
2280 Default for mark: 0xFFFFFFFF (mark from server is not changed).
2282 All of these features require the --enable-zph-qos compilation flag
2283 (enabled by default). Netfilter marking also requires the
2284 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
2285 libcap 2.09+ (--with-libcap).
2289 NAME: tcp_outgoing_address
2292 DEFAULT_DOC: Address selection is performed by the operating system.
2293 LOC: Config.accessList.outgoing_address
2295 Allows you to map requests to different outgoing IP addresses
2296 based on the username or source address of the user making
2299 tcp_outgoing_address ipaddr [[!]aclname] ...
2302 Forwarding clients with dedicated IPs for certain subnets.
2304 acl normal_service_net src 10.0.0.0/24
2305 acl good_service_net src 10.0.2.0/24
2307 tcp_outgoing_address 2001:db8::c001 good_service_net
2308 tcp_outgoing_address 10.1.0.2 good_service_net
2310 tcp_outgoing_address 2001:db8::beef normal_service_net
2311 tcp_outgoing_address 10.1.0.1 normal_service_net
2313 tcp_outgoing_address 2001:db8::1
2314 tcp_outgoing_address 10.1.0.3
2316 Processing proceeds in the order specified, and stops at first fully
2319 Squid will add an implicit IP version test to each line.
2320 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.
2321 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.
2324 NOTE: The use of this directive using client dependent ACLs is
2325 incompatible with the use of server side persistent connections. To
2326 ensure correct results it is best to set server_persistent_connections
2327 to off when using this directive in such configurations.
2329 NOTE: The use of this directive to set a local IP on outgoing TCP links
2330 is incompatible with using TPROXY to set client IP out outbound TCP links.
2331 When needing to contact peers use the no-tproxy cache_peer option and the
2332 client_dst_passthru directive re-enable normal forwarding such as this.
2336 NAME: host_verify_strict
2339 LOC: Config.onoff.hostStrictVerify
2341 Regardless of this option setting, when dealing with intercepted
2342 traffic, Squid always verifies that the destination IP address matches
2343 the Host header domain or IP (called 'authority form URL').
2345 This enforcement is performed to satisfy a MUST-level requirement in
2346 RFC 2616 section 14.23: "The Host field value MUST represent the naming
2347 authority of the origin server or gateway given by the original URL".
2350 Squid always responds with an HTTP 409 (Conflict) error
2351 page and logs a security warning if there is no match.
2353 Squid verifies that the destination IP address matches
2354 the Host header for forward-proxy and reverse-proxy traffic
2355 as well. For those traffic types, Squid also enables the
2356 following checks, comparing the corresponding Host header
2357 and Request-URI components:
2359 * The host names (domain or IP) must be identical,
2360 but valueless or missing Host header disables all checks.
2361 For the two host names to match, both must be either IP
2364 * Port numbers must be identical, but if a port is missing
2365 the scheme-default port is assumed.
2368 When set to OFF (the default):
2369 Squid allows suspicious requests to continue but logs a
2370 security warning and blocks caching of the response.
2372 * Forward-proxy traffic is not checked at all.
2374 * Reverse-proxy traffic is not checked at all.
2376 * Intercepted traffic which passes verification is handled
2377 according to client_dst_passthru.
2379 * Intercepted requests which fail verification are sent
2380 to the client original destination instead of DIRECT.
2381 This overrides 'client_dst_passthru off'.
2383 For now suspicious intercepted CONNECT requests are always
2384 responded to with an HTTP 409 (Conflict) error page.
2389 As described in CVE-2009-0801 when the Host: header alone is used
2390 to determine the destination of a request it becomes trivial for
2391 malicious scripts on remote websites to bypass browser same-origin
2392 security policy and sandboxing protections.
2394 The cause of this is that such applets are allowed to perform their
2395 own HTTP stack, in which case the same-origin policy of the browser
2396 sandbox only verifies that the applet tries to contact the same IP
2397 as from where it was loaded at the IP level. The Host: header may
2398 be different from the connected IP and approved origin.
2402 NAME: client_dst_passthru
2405 LOC: Config.onoff.client_dst_passthru
2407 With NAT or TPROXY intercepted traffic Squid may pass the request
2408 directly to the original client destination IP or seek a faster
2409 source using the HTTP Host header.
2411 Using Host to locate alternative servers can provide faster
2412 connectivity with a range of failure recovery options.
2413 But can also lead to connectivity trouble when the client and
2414 server are attempting stateful interactions unaware of the proxy.
2416 This option (on by default) prevents alternative DNS entries being
2417 located to send intercepted traffic DIRECT to an origin server.
2418 The clients original destination IP and port will be used instead.
2420 Regardless of this option setting, when dealing with intercepted
2421 traffic Squid will verify the Host: header and any traffic which
2422 fails Host verification will be treated as if this option were ON.
2424 see host_verify_strict for details on the verification process.
2429 -----------------------------------------------------------------------------
2432 NAME: ssl_unclean_shutdown
2436 LOC: Config.SSL.unclean_shutdown
2438 Some browsers (especially MSIE) bugs out on SSL shutdown
2445 LOC: Config.SSL.ssl_engine
2448 The OpenSSL engine to use. You will need to set this if you
2449 would like to use hardware SSL acceleration for example.
2452 NAME: sslproxy_client_certificate
2455 LOC: Config.ssl_client.cert
2458 Client SSL Certificate to use when proxying https:// URLs
2461 NAME: sslproxy_client_key
2464 LOC: Config.ssl_client.key
2467 Client SSL Key to use when proxying https:// URLs
2470 NAME: sslproxy_version
2473 DEFAULT_DOC: automatic SSL/TLS version negotiation
2474 LOC: Config.ssl_client.version
2477 SSL version level to use when proxying https:// URLs
2479 The versions of SSL/TLS supported:
2481 1 automatic (default)
2488 NAME: sslproxy_options
2491 LOC: Config.ssl_client.options
2494 SSL implementation options to use when proxying https:// URLs
2496 The most important being:
2498 NO_SSLv3 Disallow the use of SSLv3
2499 NO_TLSv1 Disallow the use of TLSv1.0
2500 NO_TLSv1_1 Disallow the use of TLSv1.1
2501 NO_TLSv1_2 Disallow the use of TLSv1.2
2503 Always create a new key when using temporary/ephemeral
2506 Disable use of RFC5077 session tickets. Some servers
2507 may have problems understanding the TLS extension due
2508 to ambiguous specification in RFC4507.
2509 ALL Enable various bug workarounds suggested as "harmless"
2510 by OpenSSL. Be warned that this may reduce SSL/TLS
2511 strength to some attacks.
2513 See the OpenSSL SSL_CTX_set_options documentation for a
2514 complete list of possible options.
2517 NAME: sslproxy_cipher
2520 LOC: Config.ssl_client.cipher
2523 SSL cipher list to use when proxying https:// URLs
2525 Colon separated list of supported ciphers.
2528 NAME: sslproxy_cafile
2531 LOC: Config.ssl_client.cafile
2534 file containing CA certificates to use when verifying server
2535 certificates while proxying https:// URLs
2538 NAME: sslproxy_capath
2541 LOC: Config.ssl_client.capath
2544 directory containing CA certificates to use when verifying
2545 server certificates while proxying https:// URLs
2548 NAME: sslproxy_session_ttl
2551 LOC: Config.SSL.session_ttl
2554 Sets the timeout value for SSL sessions
2557 NAME: sslproxy_session_cache_size
2560 LOC: Config.SSL.sessionCacheSize
2563 Sets the cache size to use for ssl session
2566 NAME: sslproxy_cert_sign_hash
2569 LOC: Config.SSL.certSignHash
2572 Sets the hashing algorithm to use when signing generated certificates.
2573 Valid algorithm names depend on the OpenSSL library used. The following
2574 names are usually available: sha1, sha256, sha512, and md5. Please see
2575 your OpenSSL library manual for the available hashes. By default, Squids
2576 that support this option use sha256 hashes.
2578 Squid does not forcefully purge cached certificates that were generated
2579 with an algorithm other than the currently configured one. They remain
2580 in the cache, subject to the regular cache eviction policy, and become
2581 useful if the algorithm changes again.
2586 TYPE: sslproxy_ssl_bump
2587 LOC: Config.accessList.ssl_bump
2588 DEFAULT_DOC: Become a TCP tunnel without decrypting proxied traffic.
2591 This option is consulted when a CONNECT request is received on
2592 an http_port (or a new connection is intercepted at an
2593 https_port), provided that port was configured with an ssl-bump
2594 flag. The subsequent data on the connection is either treated as
2595 HTTPS and decrypted OR tunneled at TCP level without decryption,
2596 depending on the first matching bumping "action".
2598 ssl_bump <action> [!]acl ...
2600 The following bumping actions are currently supported:
2603 Become a TCP tunnel without decrypting proxied traffic.
2604 This is the default action.
2607 Establish a secure connection with the server and, using a
2608 mimicked server certificate, with the client.
2611 Receive client (step SslBump1) or server (step SslBump2)
2612 certificate while preserving the possibility of splicing the
2613 connection. Peeking at the server certificate (during step 2)
2614 usually precludes bumping of the connection at step 3.
2617 Receive client (step SslBump1) or server (step SslBump2)
2618 certificate while preserving the possibility of bumping the
2619 connection. Staring at the server certificate (during step 2)
2620 usually precludes splicing of the connection at step 3.
2623 Close client and server connections.
2625 Backward compatibility actions available at step SslBump1:
2628 Bump the connection. Establish a secure connection with the
2629 client first, then connect to the server. This old mode does
2630 not allow Squid to mimic server SSL certificate and does not
2631 work with intercepted SSL connections.
2634 Bump the connection. Establish a secure connection with the
2635 server first, then establish a secure connection with the
2636 client, using a mimicked server certificate. Works with both
2637 CONNECT requests and intercepted SSL connections, but does
2638 not allow to make decisions based on SSL handshake info.
2641 Decide whether to bump or splice the connection based on
2642 client-to-squid and server-to-squid SSL hello messages.
2646 Same as the "splice" action.
2648 All ssl_bump rules are evaluated at each of the supported bumping
2649 steps. Rules with actions that are impossible at the current step are
2650 ignored. The first matching ssl_bump action wins and is applied at the
2651 end of the current step. If no rules match, the splice action is used.
2652 See the at_step ACL for a list of the supported SslBump steps.
2654 This clause supports both fast and slow acl types.
2655 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2657 See also: http_port ssl-bump, https_port ssl-bump, and acl at_step.
2660 # Example: Bump all requests except those originating from
2661 # localhost or those going to example.com.
2663 acl broken_sites dstdomain .example.com
2664 ssl_bump splice localhost
2665 ssl_bump splice broken_sites
2669 NAME: sslproxy_flags
2672 LOC: Config.ssl_client.flags
2675 Various flags modifying the use of SSL while proxying https:// URLs:
2676 DONT_VERIFY_PEER Accept certificates that fail verification.
2677 For refined control, see sslproxy_cert_error.
2678 NO_DEFAULT_CA Don't use the default CA list built in
2682 NAME: sslproxy_cert_error
2685 DEFAULT_DOC: Server certificate errors terminate the transaction.
2686 LOC: Config.ssl_client.cert_error
2689 Use this ACL to bypass server certificate validation errors.
2691 For example, the following lines will bypass all validation errors
2692 when talking to servers for example.com. All other
2693 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
2695 acl BrokenButTrustedServers dstdomain example.com
2696 sslproxy_cert_error allow BrokenButTrustedServers
2697 sslproxy_cert_error deny all
2699 This clause only supports fast acl types.
2700 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2701 Using slow acl types may result in server crashes
2703 Without this option, all server certificate validation errors
2704 terminate the transaction to protect Squid and the client.
2706 SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed
2707 but should not happen unless your OpenSSL library is buggy.
2710 Bypassing validation errors is dangerous because an
2711 error usually implies that the server cannot be trusted
2712 and the connection may be insecure.
2714 See also: sslproxy_flags and DONT_VERIFY_PEER.
2717 NAME: sslproxy_cert_sign
2720 POSTSCRIPTUM: signUntrusted ssl::certUntrusted
2721 POSTSCRIPTUM: signSelf ssl::certSelfSigned
2722 POSTSCRIPTUM: signTrusted all
2723 TYPE: sslproxy_cert_sign
2724 LOC: Config.ssl_client.cert_sign
2727 sslproxy_cert_sign <signing algorithm> acl ...
2729 The following certificate signing algorithms are supported:
2732 Sign using the configured CA certificate which is usually
2733 placed in and trusted by end-user browsers. This is the
2734 default for trusted origin server certificates.
2737 Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error.
2738 This is the default for untrusted origin server certificates
2739 that are not self-signed (see ssl::certUntrusted).
2742 Sign using a self-signed certificate with the right CN to
2743 generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the
2744 browser. This is the default for self-signed origin server
2745 certificates (see ssl::certSelfSigned).
2747 This clause only supports fast acl types.
2749 When sslproxy_cert_sign acl(s) match, Squid uses the corresponding
2750 signing algorithm to generate the certificate and ignores all
2751 subsequent sslproxy_cert_sign options (the first match wins). If no
2752 acl(s) match, the default signing algorithm is determined by errors
2753 detected when obtaining and validating the origin server certificate.
2755 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2756 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2757 CONNECT request that carries a domain name. In all other cases (CONNECT
2758 to an IP address or an intercepted SSL connection), Squid cannot detect
2759 the domain mismatch at certificate generation time when
2760 bump-server-first is used.
2763 NAME: sslproxy_cert_adapt
2766 TYPE: sslproxy_cert_adapt
2767 LOC: Config.ssl_client.cert_adapt
2770 sslproxy_cert_adapt <adaptation algorithm> acl ...
2772 The following certificate adaptation algorithms are supported:
2775 Sets the "Not After" property to the "Not After" property of
2776 the CA certificate used to sign generated certificates.
2779 Sets the "Not Before" property to the "Not Before" property of
2780 the CA certificate used to sign generated certificates.
2782 setCommonName or setCommonName{CN}
2783 Sets Subject.CN property to the host name specified as a
2784 CN parameter or, if no explicit CN parameter was specified,
2785 extracted from the CONNECT request. It is a misconfiguration
2786 to use setCommonName without an explicit parameter for
2787 intercepted or tproxied SSL connections.
2789 This clause only supports fast acl types.
2791 Squid first groups sslproxy_cert_adapt options by adaptation algorithm.
2792 Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the
2793 corresponding adaptation algorithm to generate the certificate and
2794 ignores all subsequent sslproxy_cert_adapt options in that algorithm's
2795 group (i.e., the first match wins within each algorithm group). If no
2796 acl(s) match, the default mimicking action takes place.
2798 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2799 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2800 CONNECT request that carries a domain name. In all other cases (CONNECT
2801 to an IP address or an intercepted SSL connection), Squid cannot detect
2802 the domain mismatch at certificate generation time when
2803 bump-server-first is used.
2806 NAME: sslpassword_program
2809 LOC: Config.Program.ssl_password
2812 Specify a program used for entering SSL key passphrases
2813 when using encrypted SSL certificate keys. If not specified
2814 keys must either be unencrypted, or Squid started with the -N
2815 option to allow it to query interactively for the passphrase.
2817 The key file name is given as argument to the program allowing
2818 selection of the right password if you have multiple encrypted
2823 OPTIONS RELATING TO EXTERNAL SSL_CRTD
2824 -----------------------------------------------------------------------------
2827 NAME: sslcrtd_program
2830 DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
2831 LOC: Ssl::TheConfig.ssl_crtd
2833 Specify the location and options of the executable for ssl_crtd process.
2834 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
2835 For more information use:
2836 @DEFAULT_SSL_CRTD@ -h
2839 NAME: sslcrtd_children
2840 TYPE: HelperChildConfig
2842 DEFAULT: 32 startup=5 idle=1
2843 LOC: Ssl::TheConfig.ssl_crtdChildren
2845 The maximum number of processes spawn to service ssl server.
2846 The maximum this may be safely set to is 32.
2848 The startup= and idle= options allow some measure of skew in your
2853 Sets the minimum number of processes to spawn when Squid
2854 starts or reconfigures. When set to zero the first request will
2855 cause spawning of the first child process to handle it.
2857 Starting too few children temporary slows Squid under load while it
2858 tries to spawn enough additional processes to cope with traffic.
2862 Sets a minimum of how many processes Squid is to try and keep available
2863 at all times. When traffic begins to rise above what the existing
2864 processes can handle this many more will be spawned up to the maximum
2865 configured. A minimum setting of 1 is required.
2869 Sets the maximum number of queued requests.
2870 If the queued requests exceed queue size for more than 3 minutes
2871 squid aborts its operation.
2872 The default value is set to 2*numberofchildren.
2874 You must have at least one ssl_crtd process.
2877 NAME: sslcrtvalidator_program
2881 LOC: Ssl::TheConfig.ssl_crt_validator
2883 Specify the location and options of the executable for ssl_crt_validator
2886 Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ...
2889 ttl=n TTL in seconds for cached results. The default is 60 secs
2890 cache=n limit the result cache size. The default value is 2048
2893 NAME: sslcrtvalidator_children
2894 TYPE: HelperChildConfig
2896 DEFAULT: 32 startup=5 idle=1 concurrency=1
2897 LOC: Ssl::TheConfig.ssl_crt_validator_Children
2899 The maximum number of processes spawn to service SSL server.
2900 The maximum this may be safely set to is 32.
2902 The startup= and idle= options allow some measure of skew in your
2907 Sets the minimum number of processes to spawn when Squid
2908 starts or reconfigures. When set to zero the first request will
2909 cause spawning of the first child process to handle it.
2911 Starting too few children temporary slows Squid under load while it
2912 tries to spawn enough additional processes to cope with traffic.
2916 Sets a minimum of how many processes Squid is to try and keep available
2917 at all times. When traffic begins to rise above what the existing
2918 processes can handle this many more will be spawned up to the maximum
2919 configured. A minimum setting of 1 is required.
2923 The number of requests each certificate validator helper can handle in
2924 parallel. A value of 0 indicates the certficate validator does not
2925 support concurrency. Defaults to 1.
2927 When this directive is set to a value >= 1 then the protocol
2928 used to communicate with the helper is modified to include
2929 a request ID in front of the request/response. The request
2930 ID from the request must be echoed back with the response
2935 Sets the maximum number of queued requests.
2936 If the queued requests exceed queue size for more than 3 minutes
2937 squid aborts its operation.
2938 The default value is set to 2*numberofchildren.
2940 You must have at least one ssl_crt_validator process.
2944 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
2945 -----------------------------------------------------------------------------
2953 To specify other caches in a hierarchy, use the format:
2955 cache_peer hostname type http-port icp-port [options]
2960 # hostname type port port options
2961 # -------------------- -------- ----- ----- -----------
2962 cache_peer parent.foo.net parent 3128 3130 default
2963 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
2964 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
2965 cache_peer example.com parent 80 0 default
2966 cache_peer cdn.example.com sibling 3128 0
2968 type: either 'parent', 'sibling', or 'multicast'.
2970 proxy-port: The port number where the peer accept HTTP requests.
2971 For other Squid proxies this is usually 3128
2972 For web servers this is usually 80
2974 icp-port: Used for querying neighbor caches about objects.
2975 Set to 0 if the peer does not support ICP or HTCP.
2976 See ICP and HTCP options below for additional details.
2979 ==== ICP OPTIONS ====
2981 You MUST also set icp_port and icp_access explicitly when using these options.
2982 The defaults will prevent peer traffic using ICP.
2985 no-query Disable ICP queries to this neighbor.
2988 Indicates the named peer is a member of a multicast group.
2989 ICP queries will not be sent directly to the peer, but ICP
2990 replies will be accepted from it.
2992 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
2993 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
2996 To only send ICP queries to this neighbor infrequently.
2997 This is used to keep the neighbor round trip time updated
2998 and is usually used in conjunction with weighted-round-robin.
3001 ==== HTCP OPTIONS ====
3003 You MUST also set htcp_port and htcp_access explicitly when using these options.
3004 The defaults will prevent peer traffic using HTCP.
3007 htcp Send HTCP, instead of ICP, queries to the neighbor.
3008 You probably also want to set the "icp-port" to 4827
3009 instead of 3130. This directive accepts a comma separated
3010 list of options described below.
3012 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
3014 htcp=no-clr Send HTCP to the neighbor but without
3015 sending any CLR requests. This cannot be used with
3018 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
3019 This cannot be used with no-clr.
3022 Send HTCP to the neighbor including CLRs but only when
3023 they do not result from PURGE requests.
3026 Forward any HTCP CLR requests this proxy receives to the peer.
3029 ==== PEER SELECTION METHODS ====
3031 The default peer selection method is ICP, with the first responding peer
3032 being used as source. These options can be used for better load balancing.
3035 default This is a parent cache which can be used as a "last-resort"
3036 if a peer cannot be located by any of the peer-selection methods.
3037 If specified more than once, only the first is used.
3039 round-robin Load-Balance parents which should be used in a round-robin
3040 fashion in the absence of any ICP queries.
3041 weight=N can be used to add bias.
3043 weighted-round-robin
3044 Load-Balance parents which should be used in a round-robin
3045 fashion with the frequency of each parent being based on the
3046 round trip time. Closer parents are used more often.
3047 Usually used for background-ping parents.
3048 weight=N can be used to add bias.
3050 carp Load-Balance parents which should be used as a CARP array.
3051 The requests will be distributed among the parents based on the
3052 CARP load balancing hash function based on their weight.
3054 userhash Load-balance parents based on the client proxy_auth or ident username.
3056 sourcehash Load-balance parents based on the client source IP.
3059 To be used only for cache peers of type "multicast".
3060 ALL members of this multicast group have "sibling"
3061 relationship with it, not "parent". This is to a multicast
3062 group when the requested object would be fetched only from
3063 a "parent" cache, anyway. It's useful, e.g., when
3064 configuring a pool of redundant Squid proxies, being
3065 members of the same multicast group.
3068 ==== PEER SELECTION OPTIONS ====
3070 weight=N use to affect the selection of a peer during any weighted
3071 peer-selection mechanisms.
3072 The weight must be an integer; default is 1,
3073 larger weights are favored more.
3074 This option does not affect parent selection if a peering
3075 protocol is not in use.
3077 basetime=N Specify a base amount to be subtracted from round trip
3079 It is subtracted before division by weight in calculating
3080 which parent to fectch from. If the rtt is less than the
3081 base time the rtt is set to a minimal value.
3083 ttl=N Specify a TTL to use when sending multicast ICP queries
3085 Only useful when sending to a multicast group.
3086 Because we don't accept ICP replies from random
3087 hosts, you must configure other group members as
3088 peers with the 'multicast-responder' option.
3090 no-delay To prevent access to this neighbor from influencing the
3093 digest-url=URL Tell Squid to fetch the cache digest (if digests are
3094 enabled) for this host from the specified URL rather
3095 than the Squid default location.
3098 ==== CARP OPTIONS ====
3100 carp-key=key-specification
3101 use a different key than the full URL to hash against the peer.
3102 the key-specification is a comma-separated list of the keywords
3103 scheme, host, port, path, params
3104 Order is not important.
3106 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
3108 originserver Causes this parent to be contacted as an origin server.
3109 Meant to be used in accelerator setups when the peer
3113 Set the Host header of requests forwarded to this peer.
3114 Useful in accelerator setups where the server (peer)
3115 expects a certain domain name but clients may request
3116 others. ie example.com or www.example.com
3118 no-digest Disable request of cache digests.
3121 Disables requesting ICMP RTT database (NetDB).
3124 ==== AUTHENTICATION OPTIONS ====
3127 If this is a personal/workgroup proxy and your parent
3128 requires proxy authentication.
3130 Note: The string can include URL escapes (i.e. %20 for
3131 spaces). This also means % must be written as %%.
3134 Send login details received from client to this peer.
3135 Both Proxy- and WWW-Authorization headers are passed
3136 without alteration to the peer.
3137 Authentication is not required by Squid for this to work.
3139 Note: This will pass any form of authentication but
3140 only Basic auth will work through a proxy unless the
3141 connection-auth options are also used.
3143 login=PASS Send login details received from client to this peer.
3144 Authentication is not required by this option.
3146 If there are no client-provided authentication headers
3147 to pass on, but username and password are available
3148 from an external ACL user= and password= result tags
3149 they may be sent instead.
3151 Note: To combine this with proxy_auth both proxies must
3152 share the same user database as HTTP only allows for
3153 a single login (one for proxy, one for origin server).
3154 Also be warned this will expose your users proxy
3155 password to the peer. USE WITH CAUTION
3158 Send the username to the upstream cache, but with a
3159 fixed password. This is meant to be used when the peer
3160 is in another administrative domain, but it is still
3161 needed to identify each user.
3162 The star can optionally be followed by some extra
3163 information which is added to the username. This can
3164 be used to identify this proxy to the peer, similar to
3165 the login=username:password option above.
3168 If this is a personal/workgroup proxy and your parent
3169 requires a secure proxy authentication.
3170 The first principal from the default keytab or defined by
3171 the environment variable KRB5_KTNAME will be used.
3173 WARNING: The connection may transmit requests from multiple
3174 clients. Negotiate often assumes end-to-end authentication
3175 and a single-client. Which is not strictly true here.
3177 login=NEGOTIATE:principal_name
3178 If this is a personal/workgroup proxy and your parent
3179 requires a secure proxy authentication.
3180 The principal principal_name from the default keytab or
3181 defined by the environment variable KRB5_KTNAME will be
3184 WARNING: The connection may transmit requests from multiple
3185 clients. Negotiate often assumes end-to-end authentication
3186 and a single-client. Which is not strictly true here.
3188 connection-auth=on|off
3189 Tell Squid that this peer does or not support Microsoft
3190 connection oriented authentication, and any such
3191 challenges received from there should be ignored.
3192 Default is auto to automatically determine the status
3196 ==== SSL / HTTPS / TLS OPTIONS ====
3198 ssl Encrypt connections to this peer with SSL/TLS.
3200 sslcert=/path/to/ssl/certificate
3201 A client SSL certificate to use when connecting to
3204 sslkey=/path/to/ssl/key
3205 The private SSL key corresponding to sslcert above.
3206 If 'sslkey' is not specified 'sslcert' is assumed to
3207 reference a combined file containing both the
3208 certificate and the key.
3210 sslversion=1|3|4|5|6
3211 The SSL version to use when connecting to this peer
3212 1 = automatic (default)
3218 sslcipher=... The list of valid SSL ciphers to use when connecting
3221 ssloptions=... Specify various SSL implementation options:
3223 NO_SSLv3 Disallow the use of SSLv3
3224 NO_TLSv1 Disallow the use of TLSv1.0
3225 NO_TLSv1_1 Disallow the use of TLSv1.1
3226 NO_TLSv1_2 Disallow the use of TLSv1.2
3228 Always create a new key when using
3229 temporary/ephemeral DH key exchanges
3230 ALL Enable various bug workarounds
3231 suggested as "harmless" by OpenSSL
3232 Be warned that this reduces SSL/TLS
3233 strength to some attacks.
3235 See the OpenSSL SSL_CTX_set_options documentation for a
3238 sslcafile=... A file containing additional CA certificates to use
3239 when verifying the peer certificate.
3241 sslcapath=... A directory containing additional CA certificates to
3242 use when verifying the peer certificate.
3244 sslcrlfile=... A certificate revocation list file to use when
3245 verifying the peer certificate.
3247 sslflags=... Specify various flags modifying the SSL implementation:
3250 Accept certificates even if they fail to
3253 Don't use the default CA list built in
3256 Don't verify the peer certificate
3257 matches the server name
3259 ssldomain= The peer name as advertised in it's certificate.
3260 Used for verifying the correctness of the received peer
3261 certificate. If not specified the peer hostname will be
3265 Enable the "Front-End-Https: On" header needed when
3266 using Squid as a SSL frontend in front of Microsoft OWA.
3267 See MS KB document Q307347 for details on this header.
3268 If set to auto the header will only be added if the
3269 request is forwarded as a https:// URL.
3272 ==== GENERAL OPTIONS ====
3275 A peer-specific connect timeout.
3276 Also see the peer_connect_timeout directive.
3278 connect-fail-limit=N
3279 How many times connecting to a peer must fail before
3280 it is marked as down. Standby connection failures
3281 count towards this limit. Default is 10.
3283 allow-miss Disable Squid's use of only-if-cached when forwarding
3284 requests to siblings. This is primarily useful when
3285 icp_hit_stale is used by the sibling. To extensive use
3286 of this option may result in forwarding loops, and you
3287 should avoid having two-way peerings with this option.
3288 For example to deny peer usage on requests from peer
3289 by denying cache_peer_access if the source is a peer.
3291 max-conn=N Limit the number of concurrent connections the Squid
3292 may open to this peer, including already opened idle
3293 and standby connections. There is no peer-specific
3294 connection limit by default.
3296 A peer exceeding the limit is not used for new
3297 requests unless a standby connection is available.
3299 max-conn currently works poorly with idle persistent
3300 connections: When a peer reaches its max-conn limit,
3301 and there are idle persistent connections to the peer,
3302 the peer may not be selected because the limiting code
3303 does not know whether Squid can reuse those idle
3306 standby=N Maintain a pool of N "hot standby" connections to an
3307 UP peer, available for requests when no idle
3308 persistent connection is available (or safe) to use.
3309 By default and with zero N, no such pool is maintained.
3310 N must not exceed the max-conn limit (if any).
3312 At start or after reconfiguration, Squid opens new TCP
3313 standby connections until there are N connections
3314 available and then replenishes the standby pool as
3315 opened connections are used up for requests. A used
3316 connection never goes back to the standby pool, but
3317 may go to the regular idle persistent connection pool
3318 shared by all peers and origin servers.
3320 Squid never opens multiple new standby connections
3321 concurrently. This one-at-a-time approach minimizes
3322 flooding-like effect on peers. Furthermore, just a few
3323 standby connections should be sufficient in most cases
3324 to supply most new requests with a ready-to-use
3327 Standby connections obey server_idle_pconn_timeout.
3328 For the feature to work as intended, the peer must be
3329 configured to accept and keep them open longer than
3330 the idle timeout at the connecting Squid, to minimize
3331 race conditions typical to idle used persistent
3332 connections. Default request_timeout and
3333 server_idle_pconn_timeout values ensure such a
3336 name=xxx Unique name for the peer.
3337 Required if you have multiple peers on the same host
3338 but different ports.
3339 This name can be used in cache_peer_access and similar
3340 directives to dentify the peer.
3341 Can be used by outgoing access controls through the
3344 no-tproxy Do not use the client-spoof TPROXY support when forwarding
3345 requests to this peer. Use normal address selection instead.
3346 This overrides the spoof_client_ip ACL.
3348 proxy-only objects fetched from the peer will not be stored locally.
3352 NAME: cache_peer_access
3357 Use to limit the requests for which a neighbor proxy will be
3358 queried. Peers with no restrictions are queried for all requests.
3361 cache_peer_access cache-host allow|deny [!]aclname ...
3363 The syntax is identical to 'http_access' and the other lists of
3364 ACL elements. See the comments for 'http_access', or the
3365 Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
3368 NAME: neighbor_type_domain
3369 TYPE: hostdomaintype
3371 DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer.
3374 Modify the cache_peer neighbor type when passing requests
3375 about specific domains to the peer.
3378 neighbor_type_domain neighbor parent|sibling domain domain ...
3381 cache_peer foo.example.com parent 3128 3130
3382 neighbor_type_domain foo.example.com sibling .au .de
3384 The above configuration treats all requests to foo.example.com as a
3385 parent proxy unless the request is for a .au or .de ccTLD domain name.
3388 NAME: dead_peer_timeout
3392 LOC: Config.Timeout.deadPeer
3394 This controls how long Squid waits to declare a peer cache
3395 as "dead." If there are no ICP replies received in this
3396 amount of time, Squid will declare the peer dead and not
3397 expect to receive any further ICP replies. However, it
3398 continues to send ICP queries, and will mark the peer as
3399 alive upon receipt of the first subsequent ICP reply.
3401 This timeout also affects when Squid expects to receive ICP
3402 replies from peers. If more than 'dead_peer' seconds have
3403 passed since the last ICP reply was received, Squid will not
3404 expect to receive an ICP reply on the next query. Thus, if
3405 your time between requests is greater than this timeout, you
3406 will see a lot of requests sent DIRECT to origin servers
3407 instead of to your parents.
3410 NAME: forward_max_tries
3413 LOC: Config.forward_max_tries
3415 Controls how many different forward paths Squid will try
3416 before giving up. See also forward_timeout.
3418 NOTE: connect_retries (default: none) can make each of these
3419 possible forwarding paths be tried multiple times.
3423 MEMORY CACHE OPTIONS
3424 -----------------------------------------------------------------------------
3431 LOC: Config.memMaxSize
3433 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
3434 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
3435 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
3436 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
3438 'cache_mem' specifies the ideal amount of memory to be used
3440 * In-Transit objects
3442 * Negative-Cached objects
3444 Data for these objects are stored in 4 KB blocks. This
3445 parameter specifies the ideal upper limit on the total size of
3446 4 KB blocks allocated. In-Transit objects take the highest
3449 In-transit objects have priority over the others. When
3450 additional space is needed for incoming data, negative-cached
3451 and hot objects will be released. In other words, the
3452 negative-cached and hot objects will fill up any unused space
3453 not needed for in-transit objects.
3455 If circumstances require, this limit will be exceeded.
3456 Specifically, if your incoming request rate requires more than
3457 'cache_mem' of memory to hold in-transit objects, Squid will
3458 exceed this limit to satisfy the new requests. When the load
3459 decreases, blocks will be freed until the high-water mark is
3460 reached. Thereafter, blocks will be used to store hot
3463 If shared memory caching is enabled, Squid does not use the shared
3464 cache space for in-transit objects, but they still consume as much
3465 local memory as they need. For more details about the shared memory
3466 cache, see memory_cache_shared.
3469 NAME: maximum_object_size_in_memory
3473 LOC: Config.Store.maxInMemObjSize
3475 Objects greater than this size will not be attempted to kept in
3476 the memory cache. This should be set high enough to keep objects
3477 accessed frequently in memory to improve performance whilst low
3478 enough to keep larger objects from hoarding cache_mem.
3481 NAME: memory_cache_shared
3484 LOC: Config.memShared
3486 DEFAULT_DOC: "on" where supported if doing memory caching with multiple SMP workers.
3488 Controls whether the memory cache is shared among SMP workers.
3490 The shared memory cache is meant to occupy cache_mem bytes and replace
3491 the non-shared memory cache, although some entities may still be
3492 cached locally by workers for now (e.g., internal and in-transit
3493 objects may be served from a local memory cache even if shared memory
3494 caching is enabled).
3496 By default, the memory cache is shared if and only if all of the
3497 following conditions are satisfied: Squid runs in SMP mode with
3498 multiple workers, cache_mem is positive, and Squid environment
3499 supports required IPC primitives (e.g., POSIX shared memory segments
3500 and GCC-style atomic operations).
3502 To avoid blocking locks, shared memory uses opportunistic algorithms
3503 that do not guarantee that every cachable entity that could have been
3504 shared among SMP workers will actually be shared.
3506 Currently, entities exceeding 32KB in size cannot be shared.
3509 NAME: memory_cache_mode
3513 DEFAULT_DOC: Keep the most recently fetched objects in memory
3515 Controls which objects to keep in the memory cache (cache_mem)
3517 always Keep most recently fetched objects in memory (default)
3519 disk Only disk cache hits are kept in memory, which means
3520 an object must first be cached on disk and then hit
3521 a second time before cached in memory.
3523 network Only objects fetched from network is kept in memory
3526 NAME: memory_replacement_policy
3528 LOC: Config.memPolicy
3531 The memory replacement policy parameter determines which
3532 objects are purged from memory when memory space is needed.
3534 See cache_replacement_policy for details on algorithms.
3539 -----------------------------------------------------------------------------
3542 NAME: cache_replacement_policy
3544 LOC: Config.replPolicy
3547 The cache replacement policy parameter determines which
3548 objects are evicted (replaced) when disk space is needed.
3550 lru : Squid's original list based LRU policy
3551 heap GDSF : Greedy-Dual Size Frequency
3552 heap LFUDA: Least Frequently Used with Dynamic Aging
3553 heap LRU : LRU policy implemented using a heap
3555 Applies to any cache_dir lines listed below this directive.
3557 The LRU policies keeps recently referenced objects.
3559 The heap GDSF policy optimizes object hit rate by keeping smaller
3560 popular objects in cache so it has a better chance of getting a
3561 hit. It achieves a lower byte hit rate than LFUDA though since
3562 it evicts larger (possibly popular) objects.
3564 The heap LFUDA policy keeps popular objects in cache regardless of
3565 their size and thus optimizes byte hit rate at the expense of
3566 hit rate since one large, popular object will prevent many
3567 smaller, slightly less popular objects from being cached.
3569 Both policies utilize a dynamic aging mechanism that prevents
3570 cache pollution that can otherwise occur with frequency-based
3571 replacement policies.
3573 NOTE: if using the LFUDA replacement policy you should increase
3574 the value of maximum_object_size above its default of 4 MB to
3575 to maximize the potential byte hit rate improvement of LFUDA.
3577 For more information about the GDSF and LFUDA cache replacement
3578 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
3579 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
3582 NAME: minimum_object_size
3586 DEFAULT_DOC: no limit
3587 LOC: Config.Store.minObjectSize
3589 Objects smaller than this size will NOT be saved on disk. The
3590 value is specified in bytes, and the default is 0 KB, which
3591 means all responses can be stored.
3594 NAME: maximum_object_size
3598 LOC: Config.Store.maxObjectSize
3600 Set the default value for max-size parameter on any cache_dir.
3601 The value is specified in bytes, and the default is 4 MB.
3603 If you wish to get a high BYTES hit ratio, you should probably
3604 increase this (one 32 MB object hit counts for 3200 10KB
3607 If you wish to increase hit ratio more than you want to
3608 save bandwidth you should leave this low.
3610 NOTE: if using the LFUDA replacement policy you should increase
3611 this value to maximize the byte hit rate improvement of LFUDA!
3612 See cache_replacement_policy for a discussion of this policy.
3618 DEFAULT_DOC: No disk cache. Store cache ojects only in memory.
3619 LOC: Config.cacheSwap
3622 cache_dir Type Directory-Name Fs-specific-data [options]
3624 You can specify multiple cache_dir lines to spread the
3625 cache among different disk partitions.
3627 Type specifies the kind of storage system to use. Only "ufs"
3628 is built by default. To enable any of the other storage systems
3629 see the --enable-storeio configure option.
3631 'Directory' is a top-level directory where cache swap
3632 files will be stored. If you want to use an entire disk
3633 for caching, this can be the mount-point directory.
3634 The directory must exist and be writable by the Squid
3635 process. Squid will NOT create this directory for you.
3637 In SMP configurations, cache_dir must not precede the workers option
3638 and should use configuration macros or conditionals to give each
3639 worker interested in disk caching a dedicated cache directory.
3642 ==== The ufs store type ====
3644 "ufs" is the old well-known Squid storage format that has always
3648 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
3650 'Mbytes' is the amount of disk space (MB) to use under this
3651 directory. The default is 100 MB. Change this to suit your
3652 configuration. Do NOT put the size of your disk drive here.
3653 Instead, if you want Squid to use the entire disk drive,
3654 subtract 20% and use that value.
3656 'L1' is the number of first-level subdirectories which
3657 will be created under the 'Directory'. The default is 16.
3659 'L2' is the number of second-level subdirectories which
3660 will be created under each first-level directory. The default
3664 ==== The aufs store type ====
3666 "aufs" uses the same storage format as "ufs", utilizing
3667 POSIX-threads to avoid blocking the main Squid process on
3668 disk-I/O. This was formerly known in Squid as async-io.
3671 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
3673 see argument descriptions under ufs above
3676 ==== The diskd store type ====
3678 "diskd" uses the same storage format as "ufs", utilizing a
3679 separate process to avoid blocking the main Squid process on
3683 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
3685 see argument descriptions under ufs above
3687 Q1 specifies the number of unacknowledged I/O requests when Squid
3688 stops opening new files. If this many messages are in the queues,
3689 Squid won't open new files. Default is 64
3691 Q2 specifies the number of unacknowledged messages when Squid
3692 starts blocking. If this many messages are in the queues,
3693 Squid blocks until it receives some replies. Default is 72
3695 When Q1 < Q2 (the default), the cache directory is optimized
3696 for lower response time at the expense of a decrease in hit
3697 ratio. If Q1 > Q2, the cache directory is optimized for
3698 higher hit ratio at the expense of an increase in response
3702 ==== The rock store type ====
3705 cache_dir rock Directory-Name Mbytes [options]
3707 The Rock Store type is a database-style storage. All cached
3708 entries are stored in a "database" file, using fixed-size slots.
3709 A single entry occupies one or more slots.
3711 If possible, Squid using Rock Store creates a dedicated kid
3712 process called "disker" to avoid blocking Squid worker(s) on disk
3713 I/O. One disker kid is created for each rock cache_dir. Diskers
3714 are created only when Squid, running in daemon mode, has support
3715 for the IpcIo disk I/O module.
3717 swap-timeout=msec: Squid will not start writing a miss to or
3718 reading a hit from disk if it estimates that the swap operation
3719 will take more than the specified number of milliseconds. By
3720 default and when set to zero, disables the disk I/O time limit
3721 enforcement. Ignored when using blocking I/O module because
3722 blocking synchronous I/O does not allow Squid to estimate the
3723 expected swap wait time.
3725 max-swap-rate=swaps/sec: Artificially limits disk access using
3726 the specified I/O rate limit. Swap out requests that
3727 would cause the average I/O rate to exceed the limit are
3728 delayed. Individual swap in requests (i.e., hits or reads) are
3729 not delayed, but they do contribute to measured swap rate and
3730 since they are placed in the same FIFO queue as swap out
3731 requests, they may wait longer if max-swap-rate is smaller.
3732 This is necessary on file systems that buffer "too
3733 many" writes and then start blocking Squid and other processes
3734 while committing those writes to disk. Usually used together
3735 with swap-timeout to avoid excessive delays and queue overflows
3736 when disk demand exceeds available disk "bandwidth". By default
3737 and when set to zero, disables the disk I/O rate limit
3738 enforcement. Currently supported by IpcIo module only.
3740 slot-size=bytes: The size of a database "record" used for
3741 storing cached responses. A cached response occupies at least
3742 one slot and all database I/O is done using individual slots so
3743 increasing this parameter leads to more disk space waste while
3744 decreasing it leads to more disk I/O overheads. Should be a
3745 multiple of your operating system I/O page size. Defaults to
3746 16KBytes. A housekeeping header is stored with each slot and
3747 smaller slot-sizes will be rejected. The header is smaller than
3751 ==== COMMON OPTIONS ====
3753 no-store no new objects should be stored to this cache_dir.
3755 min-size=n the minimum object size in bytes this cache_dir
3756 will accept. It's used to restrict a cache_dir
3757 to only store large objects (e.g. AUFS) while
3758 other stores are optimized for smaller objects
3762 max-size=n the maximum object size in bytes this cache_dir
3764 The value in maximum_object_size directive sets
3765 the default unless more specific details are
3766 available (ie a small store capacity).
3768 Note: To make optimal use of the max-size limits you should order
3769 the cache_dir lines with the smallest max-size value first.
3773 # Uncomment and adjust the following to add a disk cache directory.
3774 #cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
3778 NAME: store_dir_select_algorithm
3780 LOC: Config.store_dir_select_algorithm
3783 How Squid selects which cache_dir to use when the response
3784 object will fit into more than one.
3786 Regardless of which algorithm is used the cache_dir min-size
3787 and max-size parameters are obeyed. As such they can affect
3788 the selection algorithm by limiting the set of considered
3795 This algorithm is suited to caches with similar cache_dir
3796 sizes and disk speeds.
3798 The disk with the least I/O pending is selected.
3799 When there are multiple disks with the same I/O load ranking
3800 the cache_dir with most available capacity is selected.
3802 When a mix of cache_dir sizes are configured the faster disks
3803 have a naturally lower I/O loading and larger disks have more
3804 capacity. So space used to store objects and data throughput
3805 may be very unbalanced towards larger disks.
3810 This algorithm is suited to caches with unequal cache_dir
3813 Each cache_dir is selected in a rotation. The next suitable
3816 Available cache_dir capacity is only considered in relation
3817 to whether the object will fit and meets the min-size and
3818 max-size parameters.
3820 Disk I/O loading is only considered to prevent overload on slow
3821 disks. This algorithm does not spread objects by size, so any
3822 I/O loading per-disk may appear very unbalanced and volatile.
3824 If several cache_dirs use similar min-size, max-size, or other
3825 limits to to reject certain responses, then do not group such
3826 cache_dir lines together, to avoid round-robin selection bias
3827 towards the first cache_dir after the group. Instead, interleave
3828 cache_dir lines from different groups. For example:
3830 store_dir_select_algorithm round-robin
3831 cache_dir rock /hdd1 ... min-size=100000
3832 cache_dir rock /ssd1 ... max-size=99999
3833 cache_dir rock /hdd2 ... min-size=100000
3834 cache_dir rock /ssd2 ... max-size=99999
3835 cache_dir rock /hdd3 ... min-size=100000
3836 cache_dir rock /ssd3 ... max-size=99999
3839 NAME: max_open_disk_fds
3841 LOC: Config.max_open_disk_fds
3843 DEFAULT_DOC: no limit
3845 To avoid having disk as the I/O bottleneck Squid can optionally
3846 bypass the on-disk cache if more than this amount of disk file
3847 descriptors are open.
3849 A value of 0 indicates no limit.
3852 NAME: cache_swap_low
3853 COMMENT: (percent, 0-100)
3856 LOC: Config.Swap.lowWaterMark
3858 The low-water mark for cache object replacement.
3859 Replacement begins when the swap (disk) usage is above the
3860 low-water mark and attempts to maintain utilization near the
3861 low-water mark. As swap utilization gets close to high-water
3862 mark object eviction becomes more aggressive. If utilization is
3863 close to the low-water mark less replacement is done each time.
3865 Defaults are 90% and 95%. If you have a large cache, 5% could be
3866 hundreds of MB. If this is the case you may wish to set these
3867 numbers closer together.
3869 See also cache_swap_high
3872 NAME: cache_swap_high
3873 COMMENT: (percent, 0-100)
3876 LOC: Config.Swap.highWaterMark
3878 The high-water mark for cache object replacement.
3879 Replacement begins when the swap (disk) usage is above the
3880 low-water mark and attempts to maintain utilization near the
3881 low-water mark. As swap utilization gets close to high-water
3882 mark object eviction becomes more aggressive. If utilization is
3883 close to the low-water mark less replacement is done each time.
3885 Defaults are 90% and 95%. If you have a large cache, 5% could be
3886 hundreds of MB. If this is the case you may wish to set these
3887 numbers closer together.
3889 See also cache_swap_low
3894 -----------------------------------------------------------------------------
3901 DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in.
3905 logformat <name> <format specification>
3907 Defines an access log format.
3909 The <format specification> is a string with embedded % format codes
3911 % format codes all follow the same basic structure where all but
3912 the formatcode is optional. Output strings are automatically escaped
3913 as required according to their context and the output format
3914 modifiers are usually not needed, but can be specified if an explicit
3915 output format is desired.
3917 % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
3919 " output in quoted string format
3920 [ output in squid text log format as used by log_mime_hdrs
3921 # output in URL quoted format
3926 width minimum and/or maximum field width:
3927 [width_min][.width_max]
3928 When minimum starts with 0, the field is zero-padded.
3929 String values exceeding maximum width are truncated.
3931 {arg} argument such as header name etc
3935 % a literal % character
3936 sn Unique sequence number per log line entry
3937 err_code The ID of an error response served by Squid or
3938 a similar internal error identifier.
3939 err_detail Additional err_code-dependent error information.
3940 note The annotation specified by the argument. Also
3941 logs the adaptation meta headers set by the
3942 adaptation_meta configuration parameter.
3943 If no argument given all annotations logged.
3944 The argument may include a separator to use with
3947 By default, multiple note values are separated with ","
3948 and multiple notes are separated with "\r\n".
3949 When logging named notes with %{name}note, the
3950 explicitly configured separator is used between note
3951 values. When logging all notes with %note, the
3952 explicitly configured separator is used between
3953 individual notes. There is currently no way to
3954 specify both value and notes separators when logging
3955 all notes with %note.
3957 Connection related format codes:
3959 >a Client source IP address
3961 >p Client source port
3962 >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier)
3963 >la Local IP address the client connected to
3964 >lp Local port number the client connected to
3965 >qos Client connection TOS/DSCP value set by Squid
3966 >nfmark Client connection netfilter mark set by Squid
3968 la Local listening IP address the client connection was connected to.
3969 lp Local listening port number the client connection was connected to.
3971 <a Server IP address of the last server or peer connection
3972 <A Server FQDN or peer name
3973 <p Server port number of the last server or peer connection
3974 <la Local IP address of the last server or peer connection
3975 <lp Local port number of the last server or peer connection
3976 <qos Server connection TOS/DSCP value set by Squid
3977 <nfmark Server connection netfilter mark set by Squid
3979 Time related format codes:
3981 ts Seconds since epoch
3982 tu subsecond time (milliseconds)
3983 tl Local time. Optional strftime format argument
3984 default %d/%b/%Y:%H:%M:%S %z
3985 tg GMT time. Optional strftime format argument
3986 default %d/%b/%Y:%H:%M:%S %z
3987 tr Response time (milliseconds)
3988 dt Total time spent making DNS lookups (milliseconds)
3989 tS Approximate master transaction start time in
3990 <full seconds since epoch>.<fractional seconds> format.
3991 Currently, Squid considers the master transaction
3992 started when a complete HTTP request header initiating
3993 the transaction is received from the client. This is
3994 the same value that Squid uses to calculate transaction
3995 response time when logging %tr to access.log. Currently,
3996 Squid uses millisecond resolution for %tS values,
3997 similar to the default access.log "current time" field
4000 Access Control related format codes:
4002 et Tag returned by external acl
4003 ea Log string returned by external acl
4004 un User name (any available)
4005 ul User name from authentication
4006 ue User name from external acl helper
4007 ui User name from ident
4008 us User name from SSL
4009 credentials Client credentials. The exact meaning depends on
4010 the authentication scheme: For Basic authentication,
4011 it is the password; for Digest, the realm sent by the
4012 client; for NTLM and Negotiate, the client challenge
4013 or client credentials prefixed with "YR " or "KK ".
4015 HTTP related format codes:
4019 [http::]rm Request method (GET/POST etc)
4020 [http::]>rm Request method from client
4021 [http::]<rm Request method sent to server or peer
4022 [http::]ru Request URL from client (historic, filtered for logging)
4023 [http::]>ru Request URL from client
4024 [http::]<ru Request URL sent to server or peer
4025 [http::]>rs Request URL scheme from client
4026 [http::]<rs Request URL scheme sent to server or peer
4027 [http::]>rd Request URL domain from client
4028 [http::]<rd Request URL domain sent to server or peer
4029 [http::]>rP Request URL port from client
4030 [http::]<rP Request URL port sent to server or peer
4031 [http::]rp Request URL path excluding hostname
4032 [http::]>rp Request URL path excluding hostname from client
4033 [http::]<rp Request URL path excluding hostname sent to server or peer
4034 [http::]rv Request protocol version
4035 [http::]>rv Request protocol version from client
4036 [http::]<rv Request protocol version sent to server or peer
4038 [http::]>h Original received request header.
4039 Usually differs from the request header sent by
4040 Squid, although most fields are often preserved.
4041 Accepts optional header field name/value filter
4042 argument using name[:[separator]element] format.
4043 [http::]>ha Received request header after adaptation and
4044 redirection (pre-cache REQMOD vectoring point).
4045 Usually differs from the request header sent by
4046 Squid, although most fields are often preserved.
4047 Optional header name argument as for >h
4052 [http::]<Hs HTTP status code received from the next hop
4053 [http::]>Hs HTTP status code sent to the client
4055 [http::]<h Reply header. Optional header name argument
4058 [http::]mt MIME content type
4063 [http::]st Total size of request + reply traffic with client
4064 [http::]>st Total size of request received from client.
4065 Excluding chunked encoding bytes.
4066 [http::]<st Total size of reply sent to client (after adaptation)
4068 [http::]>sh Size of request headers received from client
4069 [http::]<sh Size of reply headers sent to client (after adaptation)
4071 [http::]<sH Reply high offset sent
4072 [http::]<sS Upstream object size
4074 [http::]<bs Number of HTTP-equivalent message body bytes
4075 received from the next hop, excluding chunked
4076 transfer encoding and control messages.
4077 Generated FTP/Gopher listings are treated as
4083 [http::]<pt Peer response time in milliseconds. The timer starts
4084 when the last request byte is sent to the next hop
4085 and stops when the last response byte is received.
4086 [http::]<tt Total time in milliseconds. The timer
4087 starts with the first connect request (or write I/O)
4088 sent to the first selected peer. The timer stops
4089 with the last I/O with the last peer.
4091 Squid handling related format codes:
4093 Ss Squid request status (TCP_MISS etc)
4094 Sh Squid hierarchy status (DEFAULT_PARENT etc)
4096 SSL-related format codes:
4098 ssl::bump_mode SslBump decision for the transaction:
4100 For CONNECT requests that initiated bumping of
4101 a connection and for any request received on
4102 an already bumped connection, Squid logs the
4103 corresponding SslBump mode ("server-first" or
4104 "client-first"). See the ssl_bump option for
4105 more information about these modes.
4107 A "none" token is logged for requests that
4108 triggered "ssl_bump" ACL evaluation matching
4109 either a "none" rule or no rules at all.
4111 In all other cases, a single dash ("-") is
4114 ssl::>sni SSL client SNI sent to Squid. Available only
4115 after the peek, stare, or splice SSL bumping
4118 If ICAP is enabled, the following code becomes available (as
4119 well as ICAP log codes documented with the icap_log option):
4121 icap::tt Total ICAP processing time for the HTTP
4122 transaction. The timer ticks when ICAP
4123 ACLs are checked and when ICAP
4124 transaction is in progress.
4126 If adaptation is enabled the following three codes become available:
4128 adapt::<last_h The header of the last ICAP response or
4129 meta-information from the last eCAP
4130 transaction related to the HTTP transaction.
4131 Like <h, accepts an optional header name
4134 adapt::sum_trs Summed adaptation transaction response
4135 times recorded as a comma-separated list in
4136 the order of transaction start time. Each time
4137 value is recorded as an integer number,
4138 representing response time of one or more
4139 adaptation (ICAP or eCAP) transaction in
4140 milliseconds. When a failed transaction is
4141 being retried or repeated, its time is not
4142 logged individually but added to the
4143 replacement (next) transaction. See also:
4146 adapt::all_trs All adaptation transaction response times.
4147 Same as adaptation_strs but response times of
4148 individual transactions are never added
4149 together. Instead, all transaction response
4150 times are recorded individually.
4152 You can prefix adapt::*_trs format codes with adaptation
4153 service name in curly braces to record response time(s) specific
4154 to that service. For example: %{my_service}adapt::sum_trs
4156 If SSL is enabled, the following formating codes become available:
4158 %ssl::>cert_subject The Subject field of the received client
4159 SSL certificate or a dash ('-') if Squid has
4160 received an invalid/malformed certificate or
4161 no certificate at all. Consider encoding the
4162 logged value because Subject often has spaces.
4164 %ssl::>cert_issuer The Issuer field of the received client
4165 SSL certificate or a dash ('-') if Squid has
4166 received an invalid/malformed certificate or
4167 no certificate at all. Consider encoding the
4168 logged value because Issuer often has spaces.
4170 The default formats available (which do not need re-defining) are:
4172 logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
4173 logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
4174 logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
4175 logformat referrer %ts.%03tu %>a %{Referer}>h %ru
4176 logformat useragent %>a [%tl] "%{User-Agent}>h"
4178 NOTE: When the log_mime_hdrs directive is set to ON.
4179 The squid, common and combined formats have a safely encoded copy
4180 of the mime headers appended to each line within a pair of brackets.
4182 NOTE: The common and combined formats are not quite true to the Apache definition.
4183 The logs from Squid contain an extra status and hierarchy code appended.
4187 NAME: access_log cache_access_log
4189 LOC: Config.Log.accesslogs
4190 DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
4192 Configures whether and how Squid logs HTTP and ICP transactions.
4193 If access logging is enabled, a single line is logged for every
4194 matching HTTP or ICP request. The recommended directive formats are:
4196 access_log <module>:<place> [option ...] [acl acl ...]
4197 access_log none [acl acl ...]
4199 The following directive format is accepted but may be deprecated:
4200 access_log <module>:<place> [<logformat name> [acl acl ...]]
4202 In most cases, the first ACL name must not contain the '=' character
4203 and should not be equal to an existing logformat name. You can always
4204 start with an 'all' ACL to work around those restrictions.
4206 Will log to the specified module:place using the specified format (which
4207 must be defined in a logformat directive) those entries which match
4208 ALL the acl's specified (which must be defined in acl clauses).
4209 If no acl is specified, all requests will be logged to this destination.
4211 ===== Available options for the recommended directive format =====
4213 logformat=name Names log line format (either built-in or
4214 defined by a logformat directive). Defaults
4217 buffer-size=64KB Defines approximate buffering limit for log
4218 records (see buffered_logs). Squid should not
4219 keep more than the specified size and, hence,
4220 should flush records before the buffer becomes
4221 full to avoid overflows under normal
4222 conditions (the exact flushing algorithm is
4223 module-dependent though). The on-error option
4224 controls overflow handling.
4226 on-error=die|drop Defines action on unrecoverable errors. The
4227 'drop' action ignores (i.e., does not log)
4228 affected log records. The default 'die' action
4229 kills the affected worker. The drop action
4230 support has not been tested for modules other
4233 rotate=N Specifies the number of log file rotations to
4234 make when you run 'squid -k rotate'. The default
4235 is to obey the logfile_rotate directive. Setting
4236 rotate=0 will disable the file name rotation,
4237 but the log files are still closed and re-opened.
4238 This will enable you to rename the logfiles
4239 yourself just before sending the rotate signal.
4240 Only supported by the stdio module.
4242 ===== Modules Currently available =====
4244 none Do not log any requests matching these ACL.
4245 Do not specify Place or logformat name.
4247 stdio Write each log line to disk immediately at the completion of
4249 Place: the filename and path to be written.
4251 daemon Very similar to stdio. But instead of writing to disk the log
4252 line is passed to a daemon helper for asychronous handling instead.
4253 Place: varies depending on the daemon.
4255 log_file_daemon Place: the file name and path to be written.
4257 syslog To log each request via syslog facility.
4258 Place: The syslog facility and priority level for these entries.
4259 Place Format: facility.priority
4261 where facility could be any of:
4262 authpriv, daemon, local0 ... local7 or user.
4264 And priority could be any of:
4265 err, warning, notice, info, debug.
4267 udp To send each log line as text data to a UDP receiver.
4268 Place: The destination host name or IP and port.
4269 Place Format: //host:port
4271 tcp To send each log line as text data to a TCP receiver.
4272 Lines may be accumulated before sending (see buffered_logs).
4273 Place: The destination host name or IP and port.
4274 Place Format: //host:port
4277 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
4283 LOC: Config.Log.icaplogs
4286 ICAP log files record ICAP transaction summaries, one line per
4289 The icap_log option format is:
4290 icap_log <filepath> [<logformat name> [acl acl ...]]
4291 icap_log none [acl acl ...]]
4293 Please see access_log option documentation for details. The two
4294 kinds of logs share the overall configuration approach and many
4297 ICAP processing of a single HTTP message or transaction may
4298 require multiple ICAP transactions. In such cases, multiple
4299 ICAP transaction log lines will correspond to a single access
4302 ICAP log uses logformat codes that make sense for an ICAP
4303 transaction. Header-related codes are applied to the HTTP header
4304 embedded in an ICAP server response, with the following caveats:
4305 For REQMOD, there is no HTTP response header unless the ICAP
4306 server performed request satisfaction. For RESPMOD, the HTTP
4307 request header is the header sent to the ICAP server. For
4308 OPTIONS, there are no HTTP headers.
4310 The following format codes are also available for ICAP logs:
4312 icap::<A ICAP server IP address. Similar to <A.
4314 icap::<service_name ICAP service name from the icap_service
4315 option in Squid configuration file.
4317 icap::ru ICAP Request-URI. Similar to ru.
4319 icap::rm ICAP request method (REQMOD, RESPMOD, or
4320 OPTIONS). Similar to existing rm.
4322 icap::>st Bytes sent to the ICAP server (TCP payload
4323 only; i.e., what Squid writes to the socket).
4325 icap::<st Bytes received from the ICAP server (TCP
4326 payload only; i.e., what Squid reads from
4329 icap::<bs Number of message body bytes received from the
4330 ICAP server. ICAP message body, if any, usually
4331 includes encapsulated HTTP message headers and
4332 possibly encapsulated HTTP message body. The
4333 HTTP body part is dechunked before its size is
4336 icap::tr Transaction response time (in
4337 milliseconds). The timer starts when
4338 the ICAP transaction is created and
4339 stops when the transaction is completed.
4342 icap::tio Transaction I/O time (in milliseconds). The
4343 timer starts when the first ICAP request
4344 byte is scheduled for sending. The timers
4345 stops when the last byte of the ICAP response
4348 icap::to Transaction outcome: ICAP_ERR* for all
4349 transaction errors, ICAP_OPT for OPTION
4350 transactions, ICAP_ECHO for 204
4351 responses, ICAP_MOD for message
4352 modification, and ICAP_SAT for request
4353 satisfaction. Similar to Ss.
4355 icap::Hs ICAP response status code. Similar to Hs.
4357 icap::>h ICAP request header(s). Similar to >h.
4359 icap::<h ICAP response header(s). Similar to <h.
4361 The default ICAP log format, which can be used without an explicit
4362 definition, is called icap_squid:
4364 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
4366 See also: logformat, log_icap, and %adapt::<last_h
4369 NAME: logfile_daemon
4371 DEFAULT: @DEFAULT_LOGFILED@
4372 LOC: Log::TheConfig.logfile_daemon
4374 Specify the path to the logfile-writing daemon. This daemon is
4375 used to write the access and store logs, if configured.
4377 Squid sends a number of commands to the log daemon:
4378 L<data>\n - logfile data
4383 r<n>\n - set rotate count to <n>
4384 b<n>\n - 1 = buffer output, 0 = don't buffer output
4386 No responses is expected.
4389 NAME: stats_collection
4391 LOC: Config.accessList.stats_collection
4393 DEFAULT_DOC: Allow logging for all transactions.
4394 COMMENT: allow|deny acl acl...
4396 This options allows you to control which requests gets accounted
4397 in performance counters.
4399 This clause only supports fast acl types.
4400 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4403 NAME: cache_store_log
4406 LOC: Config.Log.store
4408 Logs the activities of the storage manager. Shows which
4409 objects are ejected from the cache, and which objects are
4410 saved and for how long.
4411 There are not really utilities to analyze this data, so you can safely
4412 disable it (the default).
4414 Store log uses modular logging outputs. See access_log for the list
4415 of modules supported.
4418 cache_store_log stdio:@DEFAULT_STORE_LOG@
4419 cache_store_log daemon:@DEFAULT_STORE_LOG@
4422 NAME: cache_swap_state cache_swap_log
4424 LOC: Config.Log.swap
4426 DEFAULT_DOC: Store the journal inside its cache_dir
4428 Location for the cache "swap.state" file. This index file holds
4429 the metadata of objects saved on disk. It is used to rebuild
4430 the cache during startup. Normally this file resides in each
4431 'cache_dir' directory, but you may specify an alternate
4432 pathname here. Note you must give a full filename, not just
4433 a directory. Since this is the index for the whole object
4434 list you CANNOT periodically rotate it!
4436 If %s can be used in the file name it will be replaced with a
4437 a representation of the cache_dir name where each / is replaced
4438 with '.'. This is needed to allow adding/removing cache_dir
4439 lines when cache_swap_log is being used.
4441 If have more than one 'cache_dir', and %s is not used in the name
4442 these swap logs will have names such as:
4448 The numbered extension (which is added automatically)
4449 corresponds to the order of the 'cache_dir' lines in this
4450 configuration file. If you change the order of the 'cache_dir'
4451 lines in this file, these index files will NOT correspond to
4452 the correct 'cache_dir' entry (unless you manually rename
4453 them). We recommend you do NOT use this option. It is
4454 better to keep these index files in each 'cache_dir' directory.
4457 NAME: logfile_rotate
4460 LOC: Config.Log.rotateNumber
4462 Specifies the default number of logfile rotations to make when you
4463 type 'squid -k rotate'. The default is 10, which will rotate
4464 with extensions 0 through 9. Setting logfile_rotate to 0 will
4465 disable the file name rotation, but the logfiles are still closed
4466 and re-opened. This will enable you to rename the logfiles
4467 yourself just before sending the rotate signal.
4469 Note, from Squid-3.1 this option is only a default for cache.log,
4470 that log can be rotated separately by using debug_options.
4472 Note, from Squid-3.6 this option is only a default for access.log
4473 recorded by stdio: module. Those logs can be rotated separately by
4474 using the rotate=N option on their access_log directive.
4476 Note, the 'squid -k rotate' command normally sends a USR1
4477 signal to the running squid process. In certain situations
4478 (e.g. on Linux with Async I/O), USR1 is used for other
4479 purposes, so -k rotate uses another signal. It is best to get
4480 in the habit of using 'squid -k rotate' instead of 'kill -USR1
4487 DEFAULT: @DEFAULT_MIME_TABLE@
4488 LOC: Config.mimeTablePathname
4490 Path to Squid's icon configuration file.
4492 You shouldn't need to change this, but the default file contains
4493 examples and formatting information if you do.
4499 LOC: Config.onoff.log_mime_hdrs
4502 The Cache can record both the request and the response MIME
4503 headers for each HTTP transaction. The headers are encoded
4504 safely and will appear as two bracketed fields at the end of
4505 the access log (for either the native or httpd-emulated log
4506 formats). To enable this logging set log_mime_hdrs to 'on'.
4511 DEFAULT: @DEFAULT_PID_FILE@
4512 LOC: Config.pidFilename
4514 A filename to write the process-id to. To disable, enter "none".
4517 NAME: client_netmask
4519 LOC: Config.Addrs.client_netmask
4521 DEFAULT_DOC: Log full client IP address
4523 A netmask for client addresses in logfiles and cachemgr output.
4524 Change this to protect the privacy of your cache clients.
4525 A netmask of 255.255.255.0 will log all IP's in that range with
4526 the last digit set to '0'.
4529 NAME: strip_query_terms
4531 LOC: Config.onoff.strip_query_terms
4534 By default, Squid strips query terms from requested URLs before
4535 logging. This protects your user's privacy and reduces log size.
4537 When investigating HIT/MISS or other caching behaviour you
4538 will need to disable this to see the full URL used by Squid.
4545 LOC: Config.onoff.buffered_logs
4547 Whether to write/send access_log records ASAP or accumulate them and
4548 then write/send them in larger chunks. Buffering may improve
4549 performance because it decreases the number of I/Os. However,
4550 buffering increases the delay before log records become available to
4551 the final recipient (e.g., a disk file or logging daemon) and,
4552 hence, increases the risk of log records loss.
4554 Note that even when buffered_logs are off, Squid may have to buffer
4555 records if it cannot write/send them immediately due to pending I/Os
4556 (e.g., the I/O writing the previous log record) or connectivity loss.
4558 Currently honored by 'daemon' and 'tcp' access_log modules only.
4561 NAME: netdb_filename
4563 DEFAULT: stdio:@DEFAULT_NETDB_FILE@
4564 LOC: Config.netdbFilename
4567 Where Squid stores it's netdb journal.
4568 When enabled this journal preserves netdb state between restarts.
4570 To disable, enter "none".
4574 OPTIONS FOR TROUBLESHOOTING
4575 -----------------------------------------------------------------------------
4580 DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
4581 LOC: Debug::cache_log
4583 Squid administrative logging file.
4585 This is where general information about Squid behavior goes. You can
4586 increase the amount of data logged to this file and how often it is
4587 rotated with "debug_options"
4593 DEFAULT_DOC: Log all critical and important messages.
4594 LOC: Debug::debugOptions
4596 Logging options are set as section,level where each source file
4597 is assigned a unique section. Lower levels result in less
4598 output, Full debugging (level 9) can result in a very large
4599 log file, so be careful.
4601 The magic word "ALL" sets debugging levels for all sections.
4602 The default is to run with "ALL,1" to record important warnings.
4604 The rotate=N option can be used to keep more or less of these logs
4605 than would otherwise be kept by logfile_rotate.
4606 For most uses a single log should be enough to monitor current
4607 events affecting Squid.
4612 LOC: Config.coredump_dir
4613 DEFAULT_IF_NONE: none
4614 DEFAULT_DOC: Use the directory from where Squid was started.
4616 By default Squid leaves core files in the directory from where
4617 it was started. If you set 'coredump_dir' to a directory
4618 that exists, Squid will chdir() to that directory at startup
4619 and coredump files will be left there.
4623 # Leave coredumps in the first cache dir
4624 coredump_dir @DEFAULT_SWAP_DIR@
4630 OPTIONS FOR FTP GATEWAYING
4631 -----------------------------------------------------------------------------
4637 LOC: Config.Ftp.anon_user
4639 If you want the anonymous login password to be more informative
4640 (and enable the use of picky FTP servers), set this to something
4641 reasonable for your domain, like wwwuser@somewhere.net
4643 The reason why this is domainless by default is the
4644 request can be made on the behalf of a user in any domain,
4645 depending on how the cache is used.
4646 Some FTP server also validate the email address is valid
4647 (for example perl.com).
4653 LOC: Config.Ftp.passive
4655 If your firewall does not allow Squid to use passive
4656 connections, turn off this option.
4658 Use of ftp_epsv_all option requires this to be ON.
4664 LOC: Config.Ftp.epsv_all
4666 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
4668 NATs may be able to put the connection on a "fast path" through the
4669 translator, as the EPRT command will never be used and therefore,
4670 translation of the data portion of the segments will never be needed.
4672 When a client only expects to do two-way FTP transfers this may be
4674 If squid finds that it must do a three-way FTP transfer after issuing
4675 an EPSV ALL command, the FTP session will fail.
4677 If you have any doubts about this option do not use it.
4678 Squid will nicely attempt all other connection methods.
4680 Requires ftp_passive to be ON (default) for any effect.
4686 LOC: Config.accessList.ftp_epsv
4688 FTP Protocol extensions permit the use of a special "EPSV" command.
4690 NATs may be able to put the connection on a "fast path" through the
4691 translator using EPSV, as the EPRT command will never be used
4692 and therefore, translation of the data portion of the segments
4693 will never be needed.
4695 EPSV is often required to interoperate with FTP servers on IPv6
4696 networks. On the other hand, it may break some IPv4 servers.
4698 By default, EPSV may try EPSV with any FTP server. To fine tune
4699 that decision, you may restrict EPSV to certain clients or servers
4702 ftp_epsv allow|deny al1 acl2 ...
4704 WARNING: Disabling EPSV may cause problems with external NAT and IPv6.
4706 Only fast ACLs are supported.
4707 Requires ftp_passive to be ON (default) for any effect.
4713 LOC: Config.Ftp.eprt
4715 FTP Protocol extensions permit the use of a special "EPRT" command.
4717 This extension provides a protocol neutral alternative to the
4718 IPv4-only PORT command. When supported it enables active FTP data
4719 channels over IPv6 and efficient NAT handling.
4721 Turning this OFF will prevent EPRT being attempted and will skip
4722 straight to using PORT for IPv4 servers.
4724 Some devices are known to not handle this extension correctly and
4725 may result in crashes. Devices which suport EPRT enough to fail
4726 cleanly will result in Squid attempting PORT anyway. This directive
4727 should only be disabled when EPRT results in device failures.
4729 WARNING: Doing so will convert Squid back to the old behavior with all
4730 the related problems with external NAT devices/layers and IPv4-only FTP.
4733 NAME: ftp_sanitycheck
4736 LOC: Config.Ftp.sanitycheck
4738 For security and data integrity reasons Squid by default performs
4739 sanity checks of the addresses of FTP data connections ensure the
4740 data connection is to the requested server. If you need to allow
4741 FTP connections to servers using another IP address for the data
4742 connection turn this off.
4745 NAME: ftp_telnet_protocol
4748 LOC: Config.Ftp.telnet
4750 The FTP protocol is officially defined to use the telnet protocol
4751 as transport channel for the control connection. However, many
4752 implementations are broken and does not respect this aspect of
4755 If you have trouble accessing files with ASCII code 255 in the
4756 path or similar problems involving this ASCII code you can
4757 try setting this directive to off. If that helps, report to the
4758 operator of the FTP server in question that their FTP server
4759 is broken and does not follow the FTP standard.
4763 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
4764 -----------------------------------------------------------------------------
4769 DEFAULT: @DEFAULT_DISKD@
4770 LOC: Config.Program.diskd
4772 Specify the location of the diskd executable.
4773 Note this is only useful if you have compiled in
4774 diskd as one of the store io modules.
4777 NAME: unlinkd_program
4780 DEFAULT: @DEFAULT_UNLINKD@
4781 LOC: Config.Program.unlinkd
4783 Specify the location of the executable for file deletion process.
4786 NAME: pinger_program
4788 DEFAULT: @DEFAULT_PINGER@
4789 LOC: Config.pinger.program
4792 Specify the location of the executable for the pinger process.
4798 LOC: Config.pinger.enable
4801 Control whether the pinger is active at run-time.
4802 Enables turning ICMP pinger on and off with a simple
4803 squid -k reconfigure.
4808 OPTIONS FOR URL REWRITING
4809 -----------------------------------------------------------------------------
4812 NAME: url_rewrite_program redirect_program
4814 LOC: Config.Program.redirect
4817 Specify the location of the executable URL rewriter to use.
4818 Since they can perform almost any function there isn't one included.
4820 For each requested URL, the rewriter will receive on line with the format
4822 [channel-ID <SP>] URL [<SP> extras]<NL>
4824 See url_rewrite_extras on how to send "extras" with optional values to
4826 After processing the request the helper must reply using the following format:
4828 [channel-ID <SP>] result [<SP> kv-pairs]
4830 The result code can be:
4832 OK status=30N url="..."
4833 Redirect the URL to the one supplied in 'url='.
4834 'status=' is optional and contains the status code to send
4835 the client in Squids HTTP response. It must be one of the
4836 HTTP redirect status codes: 301, 302, 303, 307, 308.
4837 When no status is given Squid will use 302.
4839 OK rewrite-url="..."
4840 Rewrite the URL to the one supplied in 'rewrite-url='.
4841 The new URL is fetched directly by Squid and returned to
4842 the client as the response to its request.
4845 When neither of url= and rewrite-url= are sent Squid does
4849 Do not change the URL.
4852 An internal error occurred in the helper, preventing
4853 a result being identified. The 'message=' key name is
4854 reserved for delivering a log message.
4857 In addition to the above kv-pairs Squid also understands the following
4858 optional kv-pairs received from URL rewriters:
4860 Associates a TAG with the client TCP connection.
4861 The TAG is treated as a regular annotation but persists across
4862 future requests on the client connection rather than just the
4863 current request. A helper may update the TAG during subsequent
4864 requests be returning a new kv-pair.
4866 When using the concurrency= option the protocol is changed by
4867 introducing a query channel tag in front of the request/response.
4868 The query channel tag is a number between 0 and concurrency-1.
4869 This value must be echoed back unchanged to Squid as the first part
4870 of the response relating to its request.
4872 WARNING: URL re-writing ability should be avoided whenever possible.
4873 Use the URL redirect form of response instead.
4875 Re-write creates a difference in the state held by the client
4876 and server. Possibly causing confusion when the server response
4877 contains snippets of its view state. Embeded URLs, response
4878 and content Location headers, etc. are not re-written by this
4881 By default, a URL rewriter is not used.
4884 NAME: url_rewrite_children redirect_children
4885 TYPE: HelperChildConfig
4886 DEFAULT: 20 startup=0 idle=1 concurrency=0
4887 LOC: Config.redirectChildren
4889 The maximum number of redirector processes to spawn. If you limit
4890 it too few Squid will have to wait for them to process a backlog of
4891 URLs, slowing it down. If you allow too many they will use RAM
4892 and other system resources noticably.
4894 The startup= and idle= options allow some measure of skew in your
4899 Sets a minimum of how many processes are to be spawned when Squid
4900 starts or reconfigures. When set to zero the first request will
4901 cause spawning of the first child process to handle it.
4903 Starting too few will cause an initial slowdown in traffic as Squid
4904 attempts to simultaneously spawn enough processes to cope.
4908 Sets a minimum of how many processes Squid is to try and keep available
4909 at all times. When traffic begins to rise above what the existing
4910 processes can handle this many more will be spawned up to the maximum
4911 configured. A minimum setting of 1 is required.
4915 The number of requests each redirector helper can handle in
4916 parallel. Defaults to 0 which indicates the redirector
4917 is a old-style single threaded redirector.
4919 When this directive is set to a value >= 1 then the protocol
4920 used to communicate with the helper is modified to include
4921 an ID in front of the request/response. The ID from the request
4922 must be echoed back with the response to that request.
4926 Sets the maximum number of queued requests.
4927 If the queued requests exceed queue size and redirector_bypass
4928 configuration option is set, then redirector is bypassed. Otherwise, if
4929 overloading persists squid may abort its operation.
4930 The default value is set to 2*numberofchildren.
4933 NAME: url_rewrite_host_header redirect_rewrites_host_header
4936 LOC: Config.onoff.redir_rewrites_host
4938 To preserve same-origin security policies in browsers and
4939 prevent Host: header forgery by redirectors Squid rewrites
4940 any Host: header in redirected requests.
4942 If you are running an accelerator this may not be a wanted
4943 effect of a redirector. This directive enables you disable
4944 Host: alteration in reverse-proxy traffic.
4946 WARNING: Entries are cached on the result of the URL rewriting
4947 process, so be careful if you have domain-virtual hosts.
4949 WARNING: Squid and other software verifies the URL and Host
4950 are matching, so be careful not to relay through other proxies
4951 or inspecting firewalls with this disabled.
4954 NAME: url_rewrite_access redirector_access
4957 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
4958 LOC: Config.accessList.redirector
4960 If defined, this access list specifies which requests are
4961 sent to the redirector processes.
4963 This clause supports both fast and slow acl types.
4964 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4967 NAME: url_rewrite_bypass redirector_bypass
4969 LOC: Config.onoff.redirector_bypass
4972 When this is 'on', a request will not go through the
4973 redirector if all the helpers are busy. If this is 'off'
4974 and the redirector queue grows too large, Squid will exit
4975 with a FATAL error and ask you to increase the number of
4976 redirectors. You should only enable this if the redirectors
4977 are not critical to your caching system. If you use
4978 redirectors for access control, and you enable this option,
4979 users may have access to pages they should not
4980 be allowed to request.
4981 This options sets default queue-size option of the url_rewrite_children
4985 NAME: url_rewrite_extras
4986 TYPE: TokenOrQuotedString
4987 LOC: Config.redirector_extras
4988 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
4990 Specifies a string to be append to request line format for the
4991 rewriter helper. "Quoted" format values may contain spaces and
4992 logformat %macros. In theory, any logformat %macro can be used.
4993 In practice, a %macro expands as a dash (-) if the helper request is
4994 sent before the required macro information is available to Squid.
4997 NAME: url_rewrite_timeout
4998 TYPE: UrlHelperTimeout
4999 LOC: Config.onUrlRewriteTimeout
5001 DEFAULT_DOC: Squid waits for the helper response forever
5003 Squid times active requests to redirector. The timeout value and Squid
5004 reaction to a timed out request are configurable using the following
5007 url_rewrite_timeout timeout time-units on_timeout=<action> [response=<quoted-response>]
5009 supported timeout actions:
5010 fail Squid return a ERR_GATEWAY_FAILURE error page
5012 bypass Do not re-write the URL
5014 retry Send the lookup to the helper again
5016 use_configured_response
5017 Use the <quoted-response> as helper response
5021 OPTIONS FOR STORE ID
5022 -----------------------------------------------------------------------------
5025 NAME: store_id_program storeurl_rewrite_program
5027 LOC: Config.Program.store_id
5030 Specify the location of the executable StoreID helper to use.
5031 Since they can perform almost any function there isn't one included.
5033 For each requested URL, the helper will receive one line with the format
5035 [channel-ID <SP>] URL [<SP> extras]<NL>
5038 After processing the request the helper must reply using the following format:
5040 [channel-ID <SP>] result [<SP> kv-pairs]
5042 The result code can be:
5045 Use the StoreID supplied in 'store-id='.
5048 The default is to use HTTP request URL as the store ID.
5051 An internal error occured in the helper, preventing
5052 a result being identified.
5054 In addition to the above kv-pairs Squid also understands the following
5055 optional kv-pairs received from URL rewriters:
5057 Associates a TAG with the client TCP connection.
5058 Please see url_rewrite_program related documentation for this
5061 Helper programs should be prepared to receive and possibly ignore
5062 additional whitespace-separated tokens on each input line.
5064 When using the concurrency= option the protocol is changed by
5065 introducing a query channel tag in front of the request/response.
5066 The query channel tag is a number between 0 and concurrency-1.
5067 This value must be echoed back unchanged to Squid as the first part
5068 of the response relating to its request.
5070 NOTE: when using StoreID refresh_pattern will apply to the StoreID
5071 returned from the helper and not the URL.
5073 WARNING: Wrong StoreID value returned by a careless helper may result
5074 in the wrong cached response returned to the user.
5076 By default, a StoreID helper is not used.
5079 NAME: store_id_extras
5080 TYPE: TokenOrQuotedString
5081 LOC: Config.storeId_extras
5082 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
5084 Specifies a string to be append to request line format for the
5085 StoreId helper. "Quoted" format values may contain spaces and
5086 logformat %macros. In theory, any logformat %macro can be used.
5087 In practice, a %macro expands as a dash (-) if the helper request is
5088 sent before the required macro information is available to Squid.
5091 NAME: store_id_children storeurl_rewrite_children
5092 TYPE: HelperChildConfig
5093 DEFAULT: 20 startup=0 idle=1 concurrency=0
5094 LOC: Config.storeIdChildren
5096 The maximum number of StoreID helper processes to spawn. If you limit
5097 it too few Squid will have to wait for them to process a backlog of
5098 requests, slowing it down. If you allow too many they will use RAM
5099 and other system resources noticably.
5101 The startup= and idle= options allow some measure of skew in your
5106 Sets a minimum of how many processes are to be spawned when Squid
5107 starts or reconfigures. When set to zero the first request will
5108 cause spawning of the first child process to handle it.
5110 Starting too few will cause an initial slowdown in traffic as Squid
5111 attempts to simultaneously spawn enough processes to cope.
5115 Sets a minimum of how many processes Squid is to try and keep available
5116 at all times. When traffic begins to rise above what the existing
5117 processes can handle this many more will be spawned up to the maximum
5118 configured. A minimum setting of 1 is required.
5122 The number of requests each storeID helper can handle in
5123 parallel. Defaults to 0 which indicates the helper
5124 is a old-style single threaded program.
5126 When this directive is set to a value >= 1 then the protocol
5127 used to communicate with the helper is modified to include
5128 an ID in front of the request/response. The ID from the request
5129 must be echoed back with the response to that request.
5133 Sets the maximum number of queued requests.
5134 If the queued requests exceed queue size and store_id_bypass
5135 configuration option is set, then storeID helper is bypassed. Otherwise,
5136 if overloading persists squid may abort its operation.
5137 The default value is set to 2*numberofchildren.
5140 NAME: store_id_access storeurl_rewrite_access
5143 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
5144 LOC: Config.accessList.store_id
5146 If defined, this access list specifies which requests are
5147 sent to the StoreID processes. By default all requests
5150 This clause supports both fast and slow acl types.
5151 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5154 NAME: store_id_bypass storeurl_rewrite_bypass
5156 LOC: Config.onoff.store_id_bypass
5159 When this is 'on', a request will not go through the
5160 helper if all helpers are busy. If this is 'off'
5161 and the helper queue grows too large, Squid will exit
5162 with a FATAL error and ask you to increase the number of
5163 helpers. You should only enable this if the helperss
5164 are not critical to your caching system. If you use
5165 helpers for critical caching components, and you enable this
5166 option, users may not get objects from cache.
5167 This options sets default queue-size option of the store_id_children
5172 OPTIONS FOR TUNING THE CACHE
5173 -----------------------------------------------------------------------------
5176 NAME: cache no_cache
5179 DEFAULT_DOC: By default, this directive is unused and has no effect.
5180 LOC: Config.accessList.noCache
5182 Requests denied by this directive will not be served from the cache
5183 and their responses will not be stored in the cache. This directive
5184 has no effect on other transactions and on already cached responses.
5186 This clause supports both fast and slow acl types.
5187 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5189 This and the two other similar caching directives listed below are
5190 checked at different transaction processing stages, have different
5191 access to response information, affect different cache operations,
5192 and differ in slow ACLs support:
5194 * cache: Checked before Squid makes a hit/miss determination.
5195 No access to reply information!
5196 Denies both serving a hit and storing a miss.
5197 Supports both fast and slow ACLs.
5198 * send_hit: Checked after a hit was detected.
5199 Has access to reply (hit) information.
5200 Denies serving a hit only.
5201 Supports fast ACLs only.
5202 * store_miss: Checked before storing a cachable miss.
5203 Has access to reply (miss) information.
5204 Denies storing a miss only.
5205 Supports fast ACLs only.
5207 If you are not sure which of the three directives to use, apply the
5208 following decision logic:
5210 * If your ACL(s) are of slow type _and_ need response info, redesign.
5211 Squid does not support that particular combination at this time.
5213 * If your directive ACL(s) are of slow type, use "cache"; and/or
5214 * if your directive ACL(s) need no response info, use "cache".
5216 * If you do not want the response cached, use store_miss; and/or
5217 * if you do not want a hit on a cached response, use send_hit.
5223 DEFAULT_DOC: By default, this directive is unused and has no effect.
5224 LOC: Config.accessList.sendHit
5226 Responses denied by this directive will not be served from the cache
5227 (but may still be cached, see store_miss). This directive has no
5228 effect on the responses it allows and on the cached objects.
5230 Please see the "cache" directive for a summary of differences among
5231 store_miss, send_hit, and cache directives.
5233 Unlike the "cache" directive, send_hit only supports fast acl
5234 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5238 # apply custom Store ID mapping to some URLs
5239 acl MapMe dstdomain .c.example.com
5240 store_id_program ...
5241 store_id_access allow MapMe
5243 # but prevent caching of special responses
5244 # such as 302 redirects that cause StoreID loops
5245 acl Ordinary http_status 200-299
5246 store_miss deny MapMe !Ordinary
5248 # and do not serve any previously stored special responses
5249 # from the cache (in case they were already cached before
5250 # the above store_miss rule was in effect).
5251 send_hit deny MapMe !Ordinary
5257 DEFAULT_DOC: By default, this directive is unused and has no effect.
5258 LOC: Config.accessList.storeMiss
5260 Responses denied by this directive will not be cached (but may still
5261 be served from the cache, see send_hit). This directive has no
5262 effect on the responses it allows and on the already cached responses.
5264 Please see the "cache" directive for a summary of differences among
5265 store_miss, send_hit, and cache directives. See the
5266 send_hit directive for a usage example.
5268 Unlike the "cache" directive, store_miss only supports fast acl
5269 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5275 LOC: Config.maxStale
5278 This option puts an upper limit on how stale content Squid
5279 will serve from the cache if cache validation fails.
5280 Can be overriden by the refresh_pattern max-stale option.
5283 NAME: refresh_pattern
5284 TYPE: refreshpattern
5288 usage: refresh_pattern [-i] regex min percent max [options]
5290 By default, regular expressions are CASE-SENSITIVE. To make
5291 them case-insensitive, use the -i option.
5293 'Min' is the time (in minutes) an object without an explicit
5294 expiry time should be considered fresh. The recommended
5295 value is 0, any higher values may cause dynamic applications
5296 to be erroneously cached unless the application designer
5297 has taken the appropriate actions.
5299 'Percent' is a percentage of the objects age (time since last
5300 modification age) an object without explicit expiry time
5301 will be considered fresh.
5303 'Max' is an upper limit on how long objects without an explicit
5304 expiry time will be considered fresh.
5306 options: override-expire
5311 ignore-must-revalidate
5318 override-expire enforces min age even if the server
5319 sent an explicit expiry time (e.g., with the
5320 Expires: header or Cache-Control: max-age). Doing this
5321 VIOLATES the HTTP standard. Enabling this feature
5322 could make you liable for problems which it causes.
5324 Note: override-expire does not enforce staleness - it only extends
5325 freshness / min. If the server returns a Expires time which
5326 is longer than your max time, Squid will still consider
5327 the object fresh for that period of time.
5329 override-lastmod enforces min age even on objects
5330 that were modified recently.
5332 reload-into-ims changes a client no-cache or ``reload''
5333 request for a cached entry into a conditional request using
5334 If-Modified-Since and/or If-None-Match headers, provided the
5335 cached entry has a Last-Modified and/or a strong ETag header.
5336 Doing this VIOLATES the HTTP standard. Enabling this feature
5337 could make you liable for problems which it causes.
5339 ignore-reload ignores a client no-cache or ``reload''
5340 header. Doing this VIOLATES the HTTP standard. Enabling
5341 this feature could make you liable for problems which
5344 ignore-no-store ignores any ``Cache-control: no-store''
5345 headers received from a server. Doing this VIOLATES
5346 the HTTP standard. Enabling this feature could make you
5347 liable for problems which it causes.
5349 ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
5350 headers received from a server. Doing this VIOLATES
5351 the HTTP standard. Enabling this feature could make you
5352 liable for problems which it causes.
5354 ignore-private ignores any ``Cache-control: private''
5355 headers received from a server. Doing this VIOLATES
5356 the HTTP standard. Enabling this feature could make you
5357 liable for problems which it causes.
5359 ignore-auth caches responses to requests with authorization,
5360 as if the originserver had sent ``Cache-control: public''
5361 in the response header. Doing this VIOLATES the HTTP standard.
5362 Enabling this feature could make you liable for problems which
5365 refresh-ims causes squid to contact the origin server
5366 when a client issues an If-Modified-Since request. This
5367 ensures that the client will receive an updated version
5368 if one is available.
5370 store-stale stores responses even if they don't have explicit
5371 freshness or a validator (i.e., Last-Modified or an ETag)
5372 present, or if they're already stale. By default, Squid will
5373 not cache such responses because they usually can't be
5374 reused. Note that such responses will be stale by default.
5376 max-stale=NN provide a maximum staleness factor. Squid won't
5377 serve objects more stale than this even if it failed to
5378 validate the object. Default: use the max_stale global limit.
5380 Basically a cached object is:
5382 FRESH if expires < now, else STALE
5384 FRESH if lm-factor < percent, else STALE
5388 The refresh_pattern lines are checked in the order listed here.
5389 The first entry which matches is used. If none of the entries
5390 match the default will be used.
5392 Note, you must uncomment all the default lines if you want
5393 to change one. The default setting is only active if none is
5399 # Add any of your own refresh_pattern entries above these.
5401 refresh_pattern ^ftp: 1440 20% 10080
5402 refresh_pattern ^gopher: 1440 0% 1440
5403 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
5404 refresh_pattern . 0 20% 4320
5408 NAME: quick_abort_min
5412 LOC: Config.quickAbort.min
5415 NAME: quick_abort_max
5419 LOC: Config.quickAbort.max
5422 NAME: quick_abort_pct
5426 LOC: Config.quickAbort.pct
5428 The cache by default continues downloading aborted requests
5429 which are almost completed (less than 16 KB remaining). This
5430 may be undesirable on slow (e.g. SLIP) links and/or very busy
5431 caches. Impatient users may tie up file descriptors and
5432 bandwidth by repeatedly requesting and immediately aborting
5435 When the user aborts a request, Squid will check the
5436 quick_abort values to the amount of data transferred until
5439 If the transfer has less than 'quick_abort_min' KB remaining,
5440 it will finish the retrieval.
5442 If the transfer has more than 'quick_abort_max' KB remaining,
5443 it will abort the retrieval.
5445 If more than 'quick_abort_pct' of the transfer has completed,
5446 it will finish the retrieval.
5448 If you do not want any retrieval to continue after the client
5449 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
5452 If you want retrievals to always continue if they are being
5453 cached set 'quick_abort_min' to '-1 KB'.
5456 NAME: read_ahead_gap
5457 COMMENT: buffer-size
5459 LOC: Config.readAheadGap
5462 The amount of data the cache will buffer ahead of what has been
5463 sent to the client when retrieving an object from another server.
5467 IFDEF: USE_HTTP_VIOLATIONS
5470 LOC: Config.negativeTtl
5473 Set the Default Time-to-Live (TTL) for failed requests.
5474 Certain types of failures (such as "connection refused" and
5475 "404 Not Found") are able to be negatively-cached for a short time.
5476 Modern web servers should provide Expires: header, however if they
5477 do not this can provide a minimum TTL.
5478 The default is not to cache errors with unknown expiry details.
5480 Note that this is different from negative caching of DNS lookups.
5482 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5483 this feature could make you liable for problems which it
5487 NAME: positive_dns_ttl
5490 LOC: Config.positiveDnsTtl
5493 Upper limit on how long Squid will cache positive DNS responses.
5494 Default is 6 hours (360 minutes). This directive must be set
5495 larger than negative_dns_ttl.
5498 NAME: negative_dns_ttl
5501 LOC: Config.negativeDnsTtl
5504 Time-to-Live (TTL) for negative caching of failed DNS lookups.
5505 This also sets the lower cache limit on positive lookups.
5506 Minimum value is 1 second, and it is not recommendable to go
5507 much below 10 seconds.
5510 NAME: range_offset_limit
5511 COMMENT: size [acl acl...]
5513 LOC: Config.rangeOffsetLimit
5516 usage: (size) [units] [[!]aclname]
5518 Sets an upper limit on how far (number of bytes) into the file
5519 a Range request may be to cause Squid to prefetch the whole file.
5520 If beyond this limit, Squid forwards the Range request as it is and
5521 the result is NOT cached.
5523 This is to stop a far ahead range request (lets say start at 17MB)
5524 from making Squid fetch the whole object up to that point before
5525 sending anything to the client.
5527 Multiple range_offset_limit lines may be specified, and they will
5528 be searched from top to bottom on each request until a match is found.
5529 The first match found will be used. If no line matches a request, the
5530 default limit of 0 bytes will be used.
5532 'size' is the limit specified as a number of units.
5534 'units' specifies whether to use bytes, KB, MB, etc.
5535 If no units are specified bytes are assumed.
5537 A size of 0 causes Squid to never fetch more than the
5538 client requested. (default)
5540 A size of 'none' causes Squid to always fetch the object from the
5541 beginning so it may cache the result. (2.0 style)
5543 'aclname' is the name of a defined ACL.
5545 NP: Using 'none' as the byte value here will override any quick_abort settings
5546 that may otherwise apply to the range request. The range request will
5547 be fully fetched from start to finish regardless of the client
5548 actions. This affects bandwidth usage.
5551 NAME: minimum_expiry_time
5554 LOC: Config.minimum_expiry_time
5557 The minimum caching time according to (Expires - Date)
5558 headers Squid honors if the object can't be revalidated.
5559 The default is 60 seconds.
5561 In reverse proxy environments it might be desirable to honor
5562 shorter object lifetimes. It is most likely better to make
5563 your server return a meaningful Last-Modified header however.
5565 In ESI environments where page fragments often have short
5566 lifetimes, this will often be best set to 0.
5569 NAME: store_avg_object_size
5573 LOC: Config.Store.avgObjectSize
5575 Average object size, used to estimate number of objects your
5576 cache can hold. The default is 13 KB.
5578 This is used to pre-seed the cache index memory allocation to
5579 reduce expensive reallocate operations while handling clients
5580 traffic. Too-large values may result in memory allocation during
5581 peak traffic, too-small values will result in wasted memory.
5583 Check the cache manager 'info' report metrics for the real
5584 object sizes seen by your Squid before tuning this.
5587 NAME: store_objects_per_bucket
5590 LOC: Config.Store.objectsPerBucket
5592 Target number of objects per bucket in the store hash table.
5593 Lowering this value increases the total number of buckets and
5594 also the storage maintenance rate. The default is 20.
5599 -----------------------------------------------------------------------------
5602 NAME: request_header_max_size
5606 LOC: Config.maxRequestHeaderSize
5608 This specifies the maximum size for HTTP headers in a request.
5609 Request headers are usually relatively small (about 512 bytes).
5610 Placing a limit on the request header size will catch certain
5611 bugs (for example with persistent connections) and possibly
5612 buffer-overflow or denial-of-service attacks.
5615 NAME: reply_header_max_size
5619 LOC: Config.maxReplyHeaderSize
5621 This specifies the maximum size for HTTP headers in a reply.
5622 Reply headers are usually relatively small (about 512 bytes).
5623 Placing a limit on the reply header size will catch certain
5624 bugs (for example with persistent connections) and possibly
5625 buffer-overflow or denial-of-service attacks.
5628 NAME: request_body_max_size
5632 DEFAULT_DOC: No limit.
5633 LOC: Config.maxRequestBodySize
5635 This specifies the maximum size for an HTTP request body.
5636 In other words, the maximum size of a PUT/POST request.
5637 A user who attempts to send a request with a body larger
5638 than this limit receives an "Invalid Request" error message.
5639 If you set this parameter to a zero (the default), there will
5640 be no limit imposed.
5642 See also client_request_buffer_max_size for an alternative
5643 limitation on client uploads which can be configured.
5646 NAME: client_request_buffer_max_size
5650 LOC: Config.maxRequestBufferSize
5652 This specifies the maximum buffer size of a client request.
5653 It prevents squid eating too much memory when somebody uploads
5658 IFDEF: USE_HTTP_VIOLATIONS
5661 DEFAULT_DOC: Obey RFC 2616.
5662 LOC: Config.accessList.brokenPosts
5664 A list of ACL elements which, if matched, causes Squid to send
5665 an extra CRLF pair after the body of a PUT/POST request.
5667 Some HTTP servers has broken implementations of PUT/POST,
5668 and rely on an extra CRLF pair sent by some WWW clients.
5670 Quote from RFC2616 section 4.1 on this matter:
5672 Note: certain buggy HTTP/1.0 client implementations generate an
5673 extra CRLF's after a POST request. To restate what is explicitly
5674 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
5675 a request with an extra CRLF.
5677 This clause only supports fast acl types.
5678 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5681 acl buggy_server url_regex ^http://....
5682 broken_posts allow buggy_server
5685 NAME: adaptation_uses_indirect_client icap_uses_indirect_client
5688 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION
5690 LOC: Adaptation::Config::use_indirect_client
5692 Controls whether the indirect client IP address (instead of the direct
5693 client IP address) is passed to adaptation services.
5695 See also: follow_x_forwarded_for adaptation_send_client_ip
5699 IFDEF: USE_HTTP_VIOLATIONS
5703 LOC: Config.onoff.via
5705 If set (default), Squid will include a Via header in requests and
5706 replies as required by RFC2616.
5712 LOC: Config.onoff.ie_refresh
5715 Microsoft Internet Explorer up until version 5.5 Service
5716 Pack 1 has an issue with transparent proxies, wherein it
5717 is impossible to force a refresh. Turning this on provides
5718 a partial fix to the problem, by causing all IMS-REFRESH
5719 requests from older IE versions to check the origin server
5720 for fresh content. This reduces hit ratio by some amount
5721 (~10% in my experience), but allows users to actually get
5722 fresh content when they want it. Note because Squid
5723 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
5724 of 5.5 is unchanged from old versions of Squid (i.e. a
5725 forced refresh is impossible). Newer versions of IE will,
5726 hopefully, continue to have the new behavior and will be
5727 handled based on that assumption. This option defaults to
5728 the old Squid behavior, which is better for hit ratios but
5729 worse for clients using IE, if they need to be able to
5730 force fresh content.
5733 NAME: vary_ignore_expire
5736 LOC: Config.onoff.vary_ignore_expire
5739 Many HTTP servers supporting Vary gives such objects
5740 immediate expiry time with no cache-control header
5741 when requested by a HTTP/1.0 client. This option
5742 enables Squid to ignore such expiry times until
5743 HTTP/1.1 is fully implemented.
5745 WARNING: If turned on this may eventually cause some
5746 varying objects not intended for caching to get cached.
5749 NAME: request_entities
5751 LOC: Config.onoff.request_entities
5754 Squid defaults to deny GET and HEAD requests with request entities,
5755 as the meaning of such requests are undefined in the HTTP standard
5756 even if not explicitly forbidden.
5758 Set this directive to on if you have clients which insists
5759 on sending request entities in GET or HEAD requests. But be warned
5760 that there is server software (both proxies and web servers) which
5761 can fail to properly process this kind of request which may make you
5762 vulnerable to cache pollution attacks if enabled.
5765 NAME: request_header_access
5766 IFDEF: USE_HTTP_VIOLATIONS
5767 TYPE: http_header_access
5768 LOC: Config.request_header_access
5770 DEFAULT_DOC: No limits.
5772 Usage: request_header_access header_name allow|deny [!]aclname ...
5774 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5775 this feature could make you liable for problems which it
5778 This option replaces the old 'anonymize_headers' and the
5779 older 'http_anonymizer' option with something that is much
5780 more configurable. A list of ACLs for each header name allows
5781 removal of specific header fields under specific conditions.
5783 This option only applies to outgoing HTTP request headers (i.e.,
5784 headers sent by Squid to the next HTTP hop such as a cache peer
5785 or an origin server). The option has no effect during cache hit
5786 detection. The equivalent adaptation vectoring point in ICAP
5787 terminology is post-cache REQMOD.
5789 The option is applied to individual outgoing request header
5790 fields. For each request header field F, Squid uses the first
5791 qualifying sets of request_header_access rules:
5793 1. Rules with header_name equal to F's name.
5794 2. Rules with header_name 'Other', provided F's name is not
5795 on the hard-coded list of commonly used HTTP header names.
5796 3. Rules with header_name 'All'.
5798 Within that qualifying rule set, rule ACLs are checked as usual.
5799 If ACLs of an "allow" rule match, the header field is allowed to
5800 go through as is. If ACLs of a "deny" rule match, the header is
5801 removed and request_header_replace is then checked to identify
5802 if the removed header has a replacement. If no rules within the
5803 set have matching ACLs, the header field is left as is.
5805 For example, to achieve the same behavior as the old
5806 'http_anonymizer standard' option, you should use:
5808 request_header_access From deny all
5809 request_header_access Referer deny all
5810 request_header_access User-Agent deny all
5812 Or, to reproduce the old 'http_anonymizer paranoid' feature
5815 request_header_access Authorization allow all
5816 request_header_access Proxy-Authorization allow all
5817 request_header_access Cache-Control allow all
5818 request_header_access Content-Length allow all
5819 request_header_access Content-Type allow all
5820 request_header_access Date allow all
5821 request_header_access Host allow all
5822 request_header_access If-Modified-Since allow all
5823 request_header_access Pragma allow all
5824 request_header_access Accept allow all
5825 request_header_access Accept-Charset allow all
5826 request_header_access Accept-Encoding allow all
5827 request_header_access Accept-Language allow all
5828 request_header_access Connection allow all
5829 request_header_access All deny all
5831 HTTP reply headers are controlled with the reply_header_access directive.
5833 By default, all headers are allowed (no anonymizing is performed).
5836 NAME: reply_header_access
5837 IFDEF: USE_HTTP_VIOLATIONS
5838 TYPE: http_header_access
5839 LOC: Config.reply_header_access
5841 DEFAULT_DOC: No limits.
5843 Usage: reply_header_access header_name allow|deny [!]aclname ...
5845 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5846 this feature could make you liable for problems which it
5849 This option only applies to reply headers, i.e., from the
5850 server to the client.
5852 This is the same as request_header_access, but in the other
5853 direction. Please see request_header_access for detailed
5856 For example, to achieve the same behavior as the old
5857 'http_anonymizer standard' option, you should use:
5859 reply_header_access Server deny all
5860 reply_header_access WWW-Authenticate deny all
5861 reply_header_access Link deny all
5863 Or, to reproduce the old 'http_anonymizer paranoid' feature
5866 reply_header_access Allow allow all
5867 reply_header_access WWW-Authenticate allow all
5868 reply_header_access Proxy-Authenticate allow all
5869 reply_header_access Cache-Control allow all
5870 reply_header_access Content-Encoding allow all
5871 reply_header_access Content-Length allow all
5872 reply_header_access Content-Type allow all
5873 reply_header_access Date allow all
5874 reply_header_access Expires allow all
5875 reply_header_access Last-Modified allow all
5876 reply_header_access Location allow all
5877 reply_header_access Pragma allow all
5878 reply_header_access Content-Language allow all
5879 reply_header_access Retry-After allow all
5880 reply_header_access Title allow all
5881 reply_header_access Content-Disposition allow all
5882 reply_header_access Connection allow all
5883 reply_header_access All deny all
5885 HTTP request headers are controlled with the request_header_access directive.
5887 By default, all headers are allowed (no anonymizing is
5891 NAME: request_header_replace header_replace
5892 IFDEF: USE_HTTP_VIOLATIONS
5893 TYPE: http_header_replace
5894 LOC: Config.request_header_access
5897 Usage: request_header_replace header_name message
5898 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
5900 This option allows you to change the contents of headers
5901 denied with request_header_access above, by replacing them
5902 with some fixed string.
5904 This only applies to request headers, not reply headers.
5906 By default, headers are removed if denied.
5909 NAME: reply_header_replace
5910 IFDEF: USE_HTTP_VIOLATIONS
5911 TYPE: http_header_replace
5912 LOC: Config.reply_header_access
5915 Usage: reply_header_replace header_name message
5916 Example: reply_header_replace Server Foo/1.0
5918 This option allows you to change the contents of headers
5919 denied with reply_header_access above, by replacing them
5920 with some fixed string.
5922 This only applies to reply headers, not request headers.
5924 By default, headers are removed if denied.
5927 NAME: request_header_add
5928 TYPE: HeaderWithAclList
5929 LOC: Config.request_header_add
5932 Usage: request_header_add field-name field-value acl1 [acl2] ...
5933 Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
5935 This option adds header fields to outgoing HTTP requests (i.e.,
5936 request headers sent by Squid to the next HTTP hop such as a
5937 cache peer or an origin server). The option has no effect during
5938 cache hit detection. The equivalent adaptation vectoring point
5939 in ICAP terminology is post-cache REQMOD.
5941 Field-name is a token specifying an HTTP header name. If a
5942 standard HTTP header name is used, Squid does not check whether
5943 the new header conflicts with any existing headers or violates
5944 HTTP rules. If the request to be modified already contains a
5945 field with the same name, the old field is preserved but the
5946 header field values are not merged.
5948 Field-value is either a token or a quoted string. If quoted
5949 string format is used, then the surrounding quotes are removed
5950 while escape sequences and %macros are processed.
5952 In theory, all of the logformat codes can be used as %macros.
5953 However, unlike logging (which happens at the very end of
5954 transaction lifetime), the transaction may not yet have enough
5955 information to expand a macro when the new header value is needed.
5956 And some information may already be available to Squid but not yet
5957 committed where the macro expansion code can access it (report
5958 such instances!). The macro will be expanded into a single dash
5959 ('-') in such cases. Not all macros have been tested.
5961 One or more Squid ACLs may be specified to restrict header
5962 injection to matching requests. As always in squid.conf, all
5963 ACLs in an option ACL list must be satisfied for the insertion
5964 to happen. The request_header_add option supports fast ACLs
5973 This option used to log custom information about the master
5974 transaction. For example, an admin may configure Squid to log
5975 which "user group" the transaction belongs to, where "user group"
5976 will be determined based on a set of ACLs and not [just]
5977 authentication information.
5978 Values of key/value pairs can be logged using %{key}note macros:
5980 note key value acl ...
5981 logformat myFormat ... %{key}note ...
5984 NAME: relaxed_header_parser
5985 COMMENT: on|off|warn
5987 LOC: Config.onoff.relaxed_header_parser
5990 In the default "on" setting Squid accepts certain forms
5991 of non-compliant HTTP messages where it is unambiguous
5992 what the sending application intended even if the message
5993 is not correctly formatted. The messages is then normalized
5994 to the correct form when forwarded by Squid.
5996 If set to "warn" then a warning will be emitted in cache.log
5997 each time such HTTP error is encountered.
5999 If set to "off" then such HTTP errors will cause the request
6000 or response to be rejected.
6003 NAME: collapsed_forwarding
6006 LOC: Config.onoff.collapsed_forwarding
6009 This option controls whether Squid is allowed to merge multiple
6010 potentially cachable requests for the same URI before Squid knows
6011 whether the response is going to be cachable.
6013 This feature is disabled by default: Enabling collapsed forwarding
6014 needlessly delays forwarding requests that look cachable (when they are
6015 collapsed) but then need to be forwarded individually anyway because
6016 they end up being for uncachable content. However, in some cases, such
6017 as accelleration of highly cachable content with periodic or groupped
6018 expiration times, the gains from collapsing [large volumes of
6019 simultenous refresh requests] outweigh losses from such delays.
6024 -----------------------------------------------------------------------------
6027 NAME: forward_timeout
6030 LOC: Config.Timeout.forward
6033 This parameter specifies how long Squid should at most attempt in
6034 finding a forwarding path for the request before giving up.
6037 NAME: connect_timeout
6040 LOC: Config.Timeout.connect
6043 This parameter specifies how long to wait for the TCP connect to
6044 the requested server or peer to complete before Squid should
6045 attempt to find another path where to forward the request.
6048 NAME: peer_connect_timeout
6051 LOC: Config.Timeout.peer_connect
6054 This parameter specifies how long to wait for a pending TCP
6055 connection to a peer cache. The default is 30 seconds. You
6056 may also set different timeout values for individual neighbors
6057 with the 'connect-timeout' option on a 'cache_peer' line.
6063 LOC: Config.Timeout.read
6066 Applied on peer server connections.
6068 After each successful read(), the timeout will be extended by this
6069 amount. If no data is read again after this amount of time,
6070 the request is aborted and logged with ERR_READ_TIMEOUT.
6072 The default is 15 minutes.
6078 LOC: Config.Timeout.write
6081 This timeout is tracked for all connections that have data
6082 available for writing and are waiting for the socket to become
6083 ready. After each successful write, the timeout is extended by
6084 the configured amount. If Squid has data to write but the
6085 connection is not ready for the configured duration, the
6086 transaction associated with the connection is terminated. The
6087 default is 15 minutes.
6090 NAME: request_timeout
6092 LOC: Config.Timeout.request
6095 How long to wait for complete HTTP request headers after initial
6096 connection establishment.
6099 NAME: request_start_timeout
6101 LOC: Config.Timeout.request_start_timeout
6104 How long to wait for the first request byte after initial
6105 connection establishment.
6108 NAME: client_idle_pconn_timeout persistent_request_timeout
6110 LOC: Config.Timeout.clientIdlePconn
6113 How long to wait for the next HTTP request on a persistent
6114 client connection after the previous request completes.
6117 NAME: ftp_client_idle_timeout
6119 LOC: Config.Timeout.ftpClientIdle
6122 How long to wait for an FTP request on a connection to Squid ftp_port.
6123 Many FTP clients do not deal with idle connection closures well,
6124 necessitating a longer default timeout than client_idle_pconn_timeout
6125 used for incoming HTTP requests.
6128 NAME: client_lifetime
6131 LOC: Config.Timeout.lifetime
6134 The maximum amount of time a client (browser) is allowed to
6135 remain connected to the cache process. This protects the Cache
6136 from having a lot of sockets (and hence file descriptors) tied up
6137 in a CLOSE_WAIT state from remote clients that go away without
6138 properly shutting down (either because of a network failure or
6139 because of a poor client implementation). The default is one
6142 NOTE: The default value is intended to be much larger than any
6143 client would ever need to be connected to your cache. You
6144 should probably change client_lifetime only as a last resort.
6145 If you seem to have many client connections tying up
6146 filedescriptors, we recommend first tuning the read_timeout,
6147 request_timeout, persistent_request_timeout and quick_abort values.
6150 NAME: pconn_lifetime
6153 LOC: Config.Timeout.pconnLifetime
6156 Desired maximum lifetime of a persistent connection.
6157 When set, Squid will close a now-idle persistent connection that
6158 exceeded configured lifetime instead of moving the connection into
6159 the idle connection pool (or equivalent). No effect on ongoing/active
6160 transactions. Connection lifetime is the time period from the
6161 connection acceptance or opening time until "now".
6163 This limit is useful in environments with long-lived connections
6164 where Squid configuration or environmental factors change during a
6165 single connection lifetime. If unrestricted, some connections may
6166 last for hours and even days, ignoring those changes that should
6167 have affected their behavior or their existence.
6169 Currently, a new lifetime value supplied via Squid reconfiguration
6170 has no effect on already idle connections unless they become busy.
6172 When set to '0' this limit is not used.
6175 NAME: half_closed_clients
6177 LOC: Config.onoff.half_closed_clients
6180 Some clients may shutdown the sending side of their TCP
6181 connections, while leaving their receiving sides open. Sometimes,
6182 Squid can not tell the difference between a half-closed and a
6183 fully-closed TCP connection.
6185 By default, Squid will immediately close client connections when
6186 read(2) returns "no more data to read."
6188 Change this option to 'on' and Squid will keep open connections
6189 until a read(2) or write(2) on the socket returns an error.
6190 This may show some benefits for reverse proxies. But if not
6191 it is recommended to leave OFF.
6194 NAME: server_idle_pconn_timeout pconn_timeout
6196 LOC: Config.Timeout.serverIdlePconn
6199 Timeout for idle persistent connections to servers and other
6206 LOC: Ident::TheConfig.timeout
6209 Maximum time to wait for IDENT lookups to complete.
6211 If this is too high, and you enabled IDENT lookups from untrusted
6212 users, you might be susceptible to denial-of-service by having
6213 many ident requests going at once.
6216 NAME: shutdown_lifetime
6219 LOC: Config.shutdownLifetime
6222 When SIGTERM or SIGHUP is received, the cache is put into
6223 "shutdown pending" mode until all active sockets are closed.
6224 This value is the lifetime to set for all open descriptors
6225 during shutdown mode. Any active clients after this many
6226 seconds will receive a 'timeout' message.
6230 ADMINISTRATIVE PARAMETERS
6231 -----------------------------------------------------------------------------
6237 LOC: Config.adminEmail
6239 Email-address of local cache manager who will receive
6240 mail if the cache dies. The default is "webmaster".
6246 LOC: Config.EmailFrom
6248 From: email-address for mail sent when the cache dies.
6249 The default is to use 'squid@unique_hostname'.
6251 See also: unique_hostname directive.
6257 LOC: Config.EmailProgram
6259 Email program used to send mail if the cache dies.
6260 The default is "mail". The specified program must comply
6261 with the standard Unix mail syntax:
6262 mail-program recipient < mailfile
6264 Optional command line options can be specified.
6267 NAME: cache_effective_user
6269 DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
6270 LOC: Config.effectiveUser
6272 If you start Squid as root, it will change its effective/real
6273 UID/GID to the user specified below. The default is to change
6274 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
6275 see also; cache_effective_group
6278 NAME: cache_effective_group
6281 DEFAULT_DOC: Use system group memberships of the cache_effective_user account
6282 LOC: Config.effectiveGroup
6284 Squid sets the GID to the effective user's default group ID
6285 (taken from the password file) and supplementary group list
6286 from the groups membership.
6288 If you want Squid to run with a specific GID regardless of
6289 the group memberships of the effective user then set this
6290 to the group (or GID) you want Squid to run as. When set
6291 all other group privileges of the effective user are ignored
6292 and only this GID is effective. If Squid is not started as
6293 root the user starting Squid MUST be member of the specified
6296 This option is not recommended by the Squid Team.
6297 Our preference is for administrators to configure a secure
6298 user account for squid with UID/GID matching system policies.
6301 NAME: httpd_suppress_version_string
6305 LOC: Config.onoff.httpd_suppress_version_string
6307 Suppress Squid version string info in HTTP headers and HTML error pages.
6310 NAME: visible_hostname
6312 LOC: Config.visibleHostname
6314 DEFAULT_DOC: Automatically detect the system host name
6316 If you want to present a special hostname in error messages, etc,
6317 define this. Otherwise, the return value of gethostname()
6318 will be used. If you have multiple caches in a cluster and
6319 get errors about IP-forwarding you must set them to have individual
6320 names with this setting.
6323 NAME: unique_hostname
6325 LOC: Config.uniqueHostname
6327 DEFAULT_DOC: Copy the value from visible_hostname
6329 If you want to have multiple machines with the same
6330 'visible_hostname' you must give each machine a different
6331 'unique_hostname' so forwarding loops can be detected.
6334 NAME: hostname_aliases
6336 LOC: Config.hostnameAliases
6339 A list of other DNS names your cache has.
6347 Minimum umask which should be enforced while the proxy
6348 is running, in addition to the umask set at startup.
6350 For a traditional octal representation of umasks, start
6355 OPTIONS FOR THE CACHE REGISTRATION SERVICE
6356 -----------------------------------------------------------------------------
6358 This section contains parameters for the (optional) cache
6359 announcement service. This service is provided to help
6360 cache administrators locate one another in order to join or
6361 create cache hierarchies.
6363 An 'announcement' message is sent (via UDP) to the registration
6364 service by Squid. By default, the announcement message is NOT
6365 SENT unless you enable it with 'announce_period' below.
6367 The announcement message includes your hostname, plus the
6368 following information from this configuration file:
6374 All current information is processed regularly and made
6375 available on the Web at http://www.ircache.net/Cache/Tracker/.
6378 NAME: announce_period
6380 LOC: Config.Announce.period
6382 DEFAULT_DOC: Announcement messages disabled.
6384 This is how frequently to send cache announcements.
6386 To enable announcing your cache, just set an announce period.
6389 announce_period 1 day
6394 DEFAULT: tracker.ircache.net
6395 LOC: Config.Announce.host
6397 Set the hostname where announce registration messages will be sent.
6399 See also announce_port and announce_file
6405 LOC: Config.Announce.file
6407 The contents of this file will be included in the announce
6408 registration messages.
6414 LOC: Config.Announce.port
6416 Set the port where announce registration messages will be sent.
6418 See also announce_host and announce_file
6422 HTTPD-ACCELERATOR OPTIONS
6423 -----------------------------------------------------------------------------
6426 NAME: httpd_accel_surrogate_id
6429 DEFAULT_DOC: visible_hostname is used if no specific ID is set.
6430 LOC: Config.Accel.surrogate_id
6432 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
6433 need an identification token to allow control targeting. Because
6434 a farm of surrogates may all perform the same tasks, they may share
6435 an identification token.
6438 NAME: http_accel_surrogate_remote
6442 LOC: Config.onoff.surrogate_is_remote
6444 Remote surrogates (such as those in a CDN) honour the header
6445 "Surrogate-Control: no-store-remote".
6447 Set this to on to have squid behave as a remote surrogate.
6451 IFDEF: USE_SQUID_ESI
6452 COMMENT: libxml2|expat|custom
6454 LOC: ESIParser::Type
6457 ESI markup is not strictly XML compatible. The custom ESI parser
6458 will give higher performance, but cannot handle non ASCII character
6463 DELAY POOL PARAMETERS
6464 -----------------------------------------------------------------------------
6468 TYPE: delay_pool_count
6470 IFDEF: USE_DELAY_POOLS
6473 This represents the number of delay pools to be used. For example,
6474 if you have one class 2 delay pool and one class 3 delays pool, you
6475 have a total of 2 delay pools.
6477 See also delay_parameters, delay_class, delay_access for pool
6478 configuration details.
6482 TYPE: delay_pool_class
6484 IFDEF: USE_DELAY_POOLS
6487 This defines the class of each delay pool. There must be exactly one
6488 delay_class line for each delay pool. For example, to define two
6489 delay pools, one of class 2 and one of class 3, the settings above
6493 delay_pools 4 # 4 delay pools
6494 delay_class 1 2 # pool 1 is a class 2 pool
6495 delay_class 2 3 # pool 2 is a class 3 pool
6496 delay_class 3 4 # pool 3 is a class 4 pool
6497 delay_class 4 5 # pool 4 is a class 5 pool
6499 The delay pool classes are:
6501 class 1 Everything is limited by a single aggregate
6504 class 2 Everything is limited by a single aggregate
6505 bucket as well as an "individual" bucket chosen
6506 from bits 25 through 32 of the IPv4 address.
6508 class 3 Everything is limited by a single aggregate
6509 bucket as well as a "network" bucket chosen
6510 from bits 17 through 24 of the IP address and a
6511 "individual" bucket chosen from bits 17 through
6512 32 of the IPv4 address.
6514 class 4 Everything in a class 3 delay pool, with an
6515 additional limit on a per user basis. This
6516 only takes effect if the username is established
6517 in advance - by forcing authentication in your
6520 class 5 Requests are grouped according their tag (see
6521 external_acl's tag= reply).
6524 Each pool also requires a delay_parameters directive to configure the pool size
6525 and speed limits used whenever the pool is applied to a request. Along with
6526 a set of delay_access directives to determine when it is used.
6528 NOTE: If an IP address is a.b.c.d
6529 -> bits 25 through 32 are "d"
6530 -> bits 17 through 24 are "c"
6531 -> bits 17 through 32 are "c * 256 + d"
6533 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
6534 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
6536 This clause only supports fast acl types.
6537 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6539 See also delay_parameters and delay_access.
6543 TYPE: delay_pool_access
6545 DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool.
6546 IFDEF: USE_DELAY_POOLS
6549 This is used to determine which delay pool a request falls into.
6551 delay_access is sorted per pool and the matching starts with pool 1,
6552 then pool 2, ..., and finally pool N. The first delay pool where the
6553 request is allowed is selected for the request. If it does not allow
6554 the request to any pool then the request is not delayed (default).
6556 For example, if you want some_big_clients in delay
6557 pool 1 and lotsa_little_clients in delay pool 2:
6559 delay_access 1 allow some_big_clients
6560 delay_access 1 deny all
6561 delay_access 2 allow lotsa_little_clients
6562 delay_access 2 deny all
6563 delay_access 3 allow authenticated_clients
6565 See also delay_parameters and delay_class.
6569 NAME: delay_parameters
6570 TYPE: delay_pool_rates
6572 IFDEF: USE_DELAY_POOLS
6575 This defines the parameters for a delay pool. Each delay pool has
6576 a number of "buckets" associated with it, as explained in the
6577 description of delay_class.
6579 For a class 1 delay pool, the syntax is:
6581 delay_parameters pool aggregate
6583 For a class 2 delay pool:
6585 delay_parameters pool aggregate individual
6587 For a class 3 delay pool:
6589 delay_parameters pool aggregate network individual
6591 For a class 4 delay pool:
6593 delay_parameters pool aggregate network individual user
6595 For a class 5 delay pool:
6597 delay_parameters pool tagrate
6599 The option variables are:
6601 pool a pool number - ie, a number between 1 and the
6602 number specified in delay_pools as used in
6605 aggregate the speed limit parameters for the aggregate bucket
6608 individual the speed limit parameters for the individual
6609 buckets (class 2, 3).
6611 network the speed limit parameters for the network buckets
6614 user the speed limit parameters for the user buckets
6617 tagrate the speed limit parameters for the tag buckets
6620 A pair of delay parameters is written restore/maximum, where restore is
6621 the number of bytes (not bits - modem and network speeds are usually
6622 quoted in bits) per second placed into the bucket, and maximum is the
6623 maximum number of bytes which can be in the bucket at any time.
6625 There must be one delay_parameters line for each delay pool.
6628 For example, if delay pool number 1 is a class 2 delay pool as in the
6629 above example, and is being used to strictly limit each host to 64Kbit/sec
6630 (plus overheads), with no overall limit, the line is:
6632 delay_parameters 1 none 8000/8000
6634 Note that 8 x 8000 KByte/sec -> 64Kbit/sec.
6636 Note that the word 'none' is used to represent no limit.
6639 And, if delay pool number 2 is a class 3 delay pool as in the above
6640 example, and you want to limit it to a total of 256Kbit/sec (strict limit)
6641 with each 8-bit network permitted 64Kbit/sec (strict limit) and each
6642 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits
6643 to permit a decent web page to be downloaded at a decent speed
6644 (if the network is not being limited due to overuse) but slow down
6645 large downloads more significantly:
6647 delay_parameters 2 32000/32000 8000/8000 600/8000
6649 Note that 8 x 32000 KByte/sec -> 256Kbit/sec.
6650 8 x 8000 KByte/sec -> 64Kbit/sec.
6651 8 x 600 Byte/sec -> 4800bit/sec.
6654 Finally, for a class 4 delay pool as in the example - each user will
6655 be limited to 128Kbits/sec no matter how many workstations they are logged into.:
6657 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
6660 See also delay_class and delay_access.
6664 NAME: delay_initial_bucket_level
6665 COMMENT: (percent, 0-100)
6668 IFDEF: USE_DELAY_POOLS
6669 LOC: Config.Delay.initial
6671 The initial bucket percentage is used to determine how much is put
6672 in each bucket when squid starts, is reconfigured, or first notices
6673 a host accessing it (in class 2 and class 3, individual hosts and
6674 networks only have buckets associated with them once they have been
6679 CLIENT DELAY POOL PARAMETERS
6680 -----------------------------------------------------------------------------
6683 NAME: client_delay_pools
6684 TYPE: client_delay_pool_count
6686 IFDEF: USE_DELAY_POOLS
6687 LOC: Config.ClientDelay
6689 This option specifies the number of client delay pools used. It must
6690 preceed other client_delay_* options.
6693 client_delay_pools 2
6695 See also client_delay_parameters and client_delay_access.
6698 NAME: client_delay_initial_bucket_level
6699 COMMENT: (percent, 0-no_limit)
6702 IFDEF: USE_DELAY_POOLS
6703 LOC: Config.ClientDelay.initial
6705 This option determines the initial bucket size as a percentage of
6706 max_bucket_size from client_delay_parameters. Buckets are created
6707 at the time of the "first" connection from the matching IP. Idle
6708 buckets are periodically deleted up.
6710 You can specify more than 100 percent but note that such "oversized"
6711 buckets are not refilled until their size goes down to max_bucket_size
6712 from client_delay_parameters.
6715 client_delay_initial_bucket_level 50
6718 NAME: client_delay_parameters
6719 TYPE: client_delay_pool_rates
6721 IFDEF: USE_DELAY_POOLS
6722 LOC: Config.ClientDelay
6725 This option configures client-side bandwidth limits using the
6728 client_delay_parameters pool speed_limit max_bucket_size
6730 pool is an integer ID used for client_delay_access matching.
6732 speed_limit is bytes added to the bucket per second.
6734 max_bucket_size is the maximum size of a bucket, enforced after any
6735 speed_limit additions.
6737 Please see the delay_parameters option for more information and
6741 client_delay_parameters 1 1024 2048
6742 client_delay_parameters 2 51200 16384
6744 See also client_delay_access.
6748 NAME: client_delay_access
6749 TYPE: client_delay_pool_access
6751 DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool.
6752 IFDEF: USE_DELAY_POOLS
6753 LOC: Config.ClientDelay
6755 This option determines the client-side delay pool for the
6758 client_delay_access pool_ID allow|deny acl_name
6760 All client_delay_access options are checked in their pool ID
6761 order, starting with pool 1. The first checked pool with allowed
6762 request is selected for the request. If no ACL matches or there
6763 are no client_delay_access options, the request bandwidth is not
6766 The ACL-selected pool is then used to find the
6767 client_delay_parameters for the request. Client-side pools are
6768 not used to aggregate clients. Clients are always aggregated
6769 based on their source IP addresses (one bucket per source IP).
6771 This clause only supports fast acl types.
6772 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6773 Additionally, only the client TCP connection details are available.
6774 ACLs testing HTTP properties will not work.
6776 Please see delay_access for more examples.
6779 client_delay_access 1 allow low_rate_network
6780 client_delay_access 2 allow vips_network
6783 See also client_delay_parameters and client_delay_pools.
6787 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
6788 -----------------------------------------------------------------------------
6793 LOC: Config.Wccp.router
6795 DEFAULT_DOC: WCCP disabled.
6798 Use this option to define your WCCP ``home'' router for
6801 wccp_router supports a single WCCP(v1) router
6803 wccp2_router supports multiple WCCPv2 routers
6805 only one of the two may be used at the same time and defines
6806 which version of WCCP to use.
6810 TYPE: IpAddress_list
6811 LOC: Config.Wccp2.router
6813 DEFAULT_DOC: WCCPv2 disabled.
6816 Use this option to define your WCCP ``home'' router for
6819 wccp_router supports a single WCCP(v1) router
6821 wccp2_router supports multiple WCCPv2 routers
6823 only one of the two may be used at the same time and defines
6824 which version of WCCP to use.
6829 LOC: Config.Wccp.version
6833 This directive is only relevant if you need to set up WCCP(v1)
6834 to some very old and end-of-life Cisco routers. In all other
6835 setups it must be left unset or at the default setting.
6836 It defines an internal version in the WCCP(v1) protocol,
6837 with version 4 being the officially documented protocol.
6839 According to some users, Cisco IOS 11.2 and earlier only
6840 support WCCP version 3. If you're using that or an earlier
6841 version of IOS, you may need to change this value to 3, otherwise
6842 do not specify this parameter.
6845 NAME: wccp2_rebuild_wait
6847 LOC: Config.Wccp2.rebuildwait
6851 If this is enabled Squid will wait for the cache dir rebuild to finish
6852 before sending the first wccp2 HereIAm packet
6855 NAME: wccp2_forwarding_method
6857 LOC: Config.Wccp2.forwarding_method
6861 WCCP2 allows the setting of forwarding methods between the
6862 router/switch and the cache. Valid values are as follows:
6864 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
6865 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
6867 Currently (as of IOS 12.4) cisco routers only support GRE.
6868 Cisco switches only support the L2 redirect assignment method.
6871 NAME: wccp2_return_method
6873 LOC: Config.Wccp2.return_method
6877 WCCP2 allows the setting of return methods between the
6878 router/switch and the cache for packets that the cache
6879 decides not to handle. Valid values are as follows:
6881 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
6882 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
6884 Currently (as of IOS 12.4) cisco routers only support GRE.
6885 Cisco switches only support the L2 redirect assignment.
6887 If the "ip wccp redirect exclude in" command has been
6888 enabled on the cache interface, then it is still safe for
6889 the proxy server to use a l2 redirect method even if this
6890 option is set to GRE.
6893 NAME: wccp2_assignment_method
6895 LOC: Config.Wccp2.assignment_method
6899 WCCP2 allows the setting of methods to assign the WCCP hash
6900 Valid values are as follows:
6902 hash - Hash assignment
6903 mask - Mask assignment
6905 As a general rule, cisco routers support the hash assignment method
6906 and cisco switches support the mask assignment method.
6911 LOC: Config.Wccp2.info
6912 DEFAULT_IF_NONE: standard 0
6913 DEFAULT_DOC: Use the 'web-cache' standard service.
6916 WCCP2 allows for multiple traffic services. There are two
6917 types: "standard" and "dynamic". The standard type defines
6918 one service id - http (id 0). The dynamic service ids can be from
6919 51 to 255 inclusive. In order to use a dynamic service id
6920 one must define the type of traffic to be redirected; this is done
6921 using the wccp2_service_info option.
6923 The "standard" type does not require a wccp2_service_info option,
6924 just specifying the service id will suffice.
6926 MD5 service authentication can be enabled by adding
6927 "password=<password>" to the end of this service declaration.
6931 wccp2_service standard 0 # for the 'web-cache' standard service
6932 wccp2_service dynamic 80 # a dynamic service type which will be
6933 # fleshed out with subsequent options.
6934 wccp2_service standard 0 password=foo
6937 NAME: wccp2_service_info
6938 TYPE: wccp2_service_info
6939 LOC: Config.Wccp2.info
6943 Dynamic WCCPv2 services require further information to define the
6944 traffic you wish to have diverted.
6948 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
6949 priority=<priority> ports=<port>,<port>..
6951 The relevant WCCPv2 flags:
6952 + src_ip_hash, dst_ip_hash
6953 + source_port_hash, dst_port_hash
6954 + src_ip_alt_hash, dst_ip_alt_hash
6955 + src_port_alt_hash, dst_port_alt_hash
6958 The port list can be one to eight entries.
6962 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
6963 priority=240 ports=80
6965 Note: the service id must have been defined by a previous
6966 'wccp2_service dynamic <id>' entry.
6971 LOC: Config.Wccp2.weight
6975 Each cache server gets assigned a set of the destination
6976 hash proportional to their weight.
6981 LOC: Config.Wccp.address
6983 DEFAULT_DOC: Address selected by the operating system.
6986 Use this option if you require WCCPv2 to use a specific
6989 The default behavior is to not bind to any specific address.
6994 LOC: Config.Wccp2.address
6996 DEFAULT_DOC: Address selected by the operating system.
6999 Use this option if you require WCCP to use a specific
7002 The default behavior is to not bind to any specific address.
7006 PERSISTENT CONNECTION HANDLING
7007 -----------------------------------------------------------------------------
7009 Also see "pconn_timeout" in the TIMEOUTS section
7012 NAME: client_persistent_connections
7014 LOC: Config.onoff.client_pconns
7017 Persistent connection support for clients.
7018 Squid uses persistent connections (when allowed). You can use
7019 this option to disable persistent connections with clients.
7022 NAME: server_persistent_connections
7024 LOC: Config.onoff.server_pconns
7027 Persistent connection support for servers.
7028 Squid uses persistent connections (when allowed). You can use
7029 this option to disable persistent connections with servers.
7032 NAME: persistent_connection_after_error
7034 LOC: Config.onoff.error_pconns
7037 With this directive the use of persistent connections after
7038 HTTP errors can be disabled. Useful if you have clients
7039 who fail to handle errors on persistent connections proper.
7042 NAME: detect_broken_pconn
7044 LOC: Config.onoff.detect_broken_server_pconns
7047 Some servers have been found to incorrectly signal the use
7048 of HTTP/1.0 persistent connections even on replies not
7049 compatible, causing significant delays. This server problem
7050 has mostly been seen on redirects.
7052 By enabling this directive Squid attempts to detect such
7053 broken replies and automatically assume the reply is finished
7054 after 10 seconds timeout.
7058 CACHE DIGEST OPTIONS
7059 -----------------------------------------------------------------------------
7062 NAME: digest_generation
7063 IFDEF: USE_CACHE_DIGESTS
7065 LOC: Config.onoff.digest_generation
7068 This controls whether the server will generate a Cache Digest
7069 of its contents. By default, Cache Digest generation is
7070 enabled if Squid is compiled with --enable-cache-digests defined.
7073 NAME: digest_bits_per_entry
7074 IFDEF: USE_CACHE_DIGESTS
7076 LOC: Config.digest.bits_per_entry
7079 This is the number of bits of the server's Cache Digest which
7080 will be associated with the Digest entry for a given HTTP
7081 Method and URL (public key) combination. The default is 5.
7084 NAME: digest_rebuild_period
7085 IFDEF: USE_CACHE_DIGESTS
7088 LOC: Config.digest.rebuild_period
7091 This is the wait time between Cache Digest rebuilds.
7094 NAME: digest_rewrite_period
7096 IFDEF: USE_CACHE_DIGESTS
7098 LOC: Config.digest.rewrite_period
7101 This is the wait time between Cache Digest writes to
7105 NAME: digest_swapout_chunk_size
7108 IFDEF: USE_CACHE_DIGESTS
7109 LOC: Config.digest.swapout_chunk_size
7112 This is the number of bytes of the Cache Digest to write to
7113 disk at a time. It defaults to 4096 bytes (4KB), the Squid
7117 NAME: digest_rebuild_chunk_percentage
7118 COMMENT: (percent, 0-100)
7119 IFDEF: USE_CACHE_DIGESTS
7121 LOC: Config.digest.rebuild_chunk_percentage
7124 This is the percentage of the Cache Digest to be scanned at a
7125 time. By default it is set to 10% of the Cache Digest.
7130 -----------------------------------------------------------------------------
7135 LOC: Config.Port.snmp
7137 DEFAULT_DOC: SNMP disabled.
7140 The port number where Squid listens for SNMP requests. To enable
7141 SNMP support set this to a suitable port number. Port number
7142 3401 is often used for the Squid SNMP agent. By default it's
7143 set to "0" (disabled)
7151 LOC: Config.accessList.snmp
7153 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
7156 Allowing or denying access to the SNMP port.
7158 All access to the agent is denied by default.
7161 snmp_access allow|deny [!]aclname ...
7163 This clause only supports fast acl types.
7164 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7167 snmp_access allow snmppublic localhost
7168 snmp_access deny all
7171 NAME: snmp_incoming_address
7173 LOC: Config.Addrs.snmp_incoming
7175 DEFAULT_DOC: Accept SNMP packets from all machine interfaces.
7178 Just like 'udp_incoming_address', but for the SNMP port.
7180 snmp_incoming_address is used for the SNMP socket receiving
7181 messages from SNMP agents.
7183 The default snmp_incoming_address is to listen on all
7184 available network interfaces.
7187 NAME: snmp_outgoing_address
7189 LOC: Config.Addrs.snmp_outgoing
7191 DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system.
7194 Just like 'udp_outgoing_address', but for the SNMP port.
7196 snmp_outgoing_address is used for SNMP packets returned to SNMP
7199 If snmp_outgoing_address is not set it will use the same socket
7200 as snmp_incoming_address. Only change this if you want to have
7201 SNMP replies sent using another address than where this Squid
7202 listens for SNMP queries.
7204 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
7205 the same value since they both use the same port.
7210 -----------------------------------------------------------------------------
7213 NAME: icp_port udp_port
7216 DEFAULT_DOC: ICP disabled.
7217 LOC: Config.Port.icp
7219 The port number where Squid sends and receives ICP queries to
7220 and from neighbor caches. The standard UDP port for ICP is 3130.
7223 icp_port @DEFAULT_ICP_PORT@
7230 DEFAULT_DOC: HTCP disabled.
7231 LOC: Config.Port.htcp
7233 The port number where Squid sends and receives HTCP queries to
7234 and from neighbor caches. To turn it on you want to set it to
7241 NAME: log_icp_queries
7245 LOC: Config.onoff.log_udp
7247 If set, ICP queries are logged to access.log. You may wish
7248 do disable this if your ICP load is VERY high to speed things
7249 up or to simplify log analysis.
7252 NAME: udp_incoming_address
7254 LOC:Config.Addrs.udp_incoming
7256 DEFAULT_DOC: Accept packets from all machine interfaces.
7258 udp_incoming_address is used for UDP packets received from other
7261 The default behavior is to not bind to any specific address.
7263 Only change this if you want to have all UDP queries received on
7264 a specific interface/address.
7266 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
7267 modules. Altering it will affect all of them in the same manner.
7269 see also; udp_outgoing_address
7271 NOTE, udp_incoming_address and udp_outgoing_address can not
7272 have the same value since they both use the same port.
7275 NAME: udp_outgoing_address
7277 LOC: Config.Addrs.udp_outgoing
7279 DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system.
7281 udp_outgoing_address is used for UDP packets sent out to other
7284 The default behavior is to not bind to any specific address.
7286 Instead it will use the same socket as udp_incoming_address.
7287 Only change this if you want to have UDP queries sent using another
7288 address than where this Squid listens for UDP queries from other
7291 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
7292 modules. Altering it will affect all of them in the same manner.
7294 see also; udp_incoming_address
7296 NOTE, udp_incoming_address and udp_outgoing_address can not
7297 have the same value since they both use the same port.
7304 LOC: Config.onoff.icp_hit_stale
7306 If you want to return ICP_HIT for stale cache objects, set this
7307 option to 'on'. If you have sibling relationships with caches
7308 in other administrative domains, this should be 'off'. If you only
7309 have sibling relationships with caches under your control,
7310 it is probably okay to set this to 'on'.
7311 If set to 'on', your siblings should use the option "allow-miss"
7312 on their cache_peer lines for connecting to you.
7315 NAME: minimum_direct_hops
7318 LOC: Config.minDirectHops
7320 If using the ICMP pinging stuff, do direct fetches for sites
7321 which are no more than this many hops away.
7324 NAME: minimum_direct_rtt
7328 LOC: Config.minDirectRtt
7330 If using the ICMP pinging stuff, do direct fetches for sites
7331 which are no more than this many rtt milliseconds away.
7337 LOC: Config.Netdb.low
7339 The low water mark for the ICMP measurement database.
7341 Note: high watermark controlled by netdb_high directive.
7343 These watermarks are counts, not percents. The defaults are
7344 (low) 900 and (high) 1000. When the high water mark is
7345 reached, database entries will be deleted until the low
7352 LOC: Config.Netdb.high
7354 The high water mark for the ICMP measurement database.
7356 Note: low watermark controlled by netdb_low directive.
7358 These watermarks are counts, not percents. The defaults are
7359 (low) 900 and (high) 1000. When the high water mark is
7360 reached, database entries will be deleted until the low
7364 NAME: netdb_ping_period
7366 LOC: Config.Netdb.period
7369 The minimum period for measuring a site. There will be at
7370 least this much delay between successive pings to the same
7371 network. The default is five minutes.
7378 LOC: Config.onoff.query_icmp
7380 If you want to ask your peers to include ICMP data in their ICP
7381 replies, enable this option.
7383 If your peer has configured Squid (during compilation) with
7384 '--enable-icmp' that peer will send ICMP pings to origin server
7385 sites of the URLs it receives. If you enable this option the
7386 ICP replies from that peer will include the ICMP data (if available).
7387 Then, when choosing a parent cache, Squid will choose the parent with
7388 the minimal RTT to the origin server. When this happens, the
7389 hierarchy field of the access.log will be
7390 "CLOSEST_PARENT_MISS". This option is off by default.
7393 NAME: test_reachability
7397 LOC: Config.onoff.test_reachability
7399 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
7400 instead of ICP_MISS if the target host is NOT in the ICMP
7401 database, or has a zero RTT.
7404 NAME: icp_query_timeout
7407 DEFAULT_DOC: Dynamic detection.
7409 LOC: Config.Timeout.icp_query
7411 Normally Squid will automatically determine an optimal ICP
7412 query timeout value based on the round-trip-time of recent ICP
7413 queries. If you want to override the value determined by
7414 Squid, set this 'icp_query_timeout' to a non-zero value. This
7415 value is specified in MILLISECONDS, so, to use a 2-second
7416 timeout (the old default), you would write:
7418 icp_query_timeout 2000
7421 NAME: maximum_icp_query_timeout
7425 LOC: Config.Timeout.icp_query_max
7427 Normally the ICP query timeout is determined dynamically. But
7428 sometimes it can lead to very large values (say 5 seconds).
7429 Use this option to put an upper limit on the dynamic timeout
7430 value. Do NOT use this option to always use a fixed (instead
7431 of a dynamic) timeout value. To set a fixed timeout see the
7432 'icp_query_timeout' directive.
7435 NAME: minimum_icp_query_timeout
7439 LOC: Config.Timeout.icp_query_min
7441 Normally the ICP query timeout is determined dynamically. But
7442 sometimes it can lead to very small timeouts, even lower than
7443 the normal latency variance on your link due to traffic.
7444 Use this option to put an lower limit on the dynamic timeout
7445 value. Do NOT use this option to always use a fixed (instead
7446 of a dynamic) timeout value. To set a fixed timeout see the
7447 'icp_query_timeout' directive.
7450 NAME: background_ping_rate
7454 LOC: Config.backgroundPingRate
7456 Controls how often the ICP pings are sent to siblings that
7457 have background-ping set.
7461 MULTICAST ICP OPTIONS
7462 -----------------------------------------------------------------------------
7467 LOC: Config.mcast_group_list
7470 This tag specifies a list of multicast groups which your server
7471 should join to receive multicasted ICP queries.
7473 NOTE! Be very careful what you put here! Be sure you
7474 understand the difference between an ICP _query_ and an ICP
7475 _reply_. This option is to be set only if you want to RECEIVE
7476 multicast queries. Do NOT set this option to SEND multicast
7477 ICP (use cache_peer for that). ICP replies are always sent via
7478 unicast, so this option does not affect whether or not you will
7479 receive replies from multicast group members.
7481 You must be very careful to NOT use a multicast address which
7482 is already in use by another group of caches.
7484 If you are unsure about multicast, please read the Multicast
7485 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
7487 Usage: mcast_groups 239.128.16.128 224.0.1.20
7489 By default, Squid doesn't listen on any multicast groups.
7492 NAME: mcast_miss_addr
7493 IFDEF: MULTICAST_MISS_STREAM
7495 LOC: Config.mcast_miss.addr
7497 DEFAULT_DOC: disabled.
7499 If you enable this option, every "cache miss" URL will
7500 be sent out on the specified multicast address.
7502 Do not enable this option unless you are are absolutely
7503 certain you understand what you are doing.
7506 NAME: mcast_miss_ttl
7507 IFDEF: MULTICAST_MISS_STREAM
7509 LOC: Config.mcast_miss.ttl
7512 This is the time-to-live value for packets multicasted
7513 when multicasting off cache miss URLs is enabled. By
7514 default this is set to 'site scope', i.e. 16.
7517 NAME: mcast_miss_port
7518 IFDEF: MULTICAST_MISS_STREAM
7520 LOC: Config.mcast_miss.port
7523 This is the port number to be used in conjunction with
7527 NAME: mcast_miss_encode_key
7528 IFDEF: MULTICAST_MISS_STREAM
7530 LOC: Config.mcast_miss.encode_key
7531 DEFAULT: XXXXXXXXXXXXXXXX
7533 The URLs that are sent in the multicast miss stream are
7534 encrypted. This is the encryption key.
7537 NAME: mcast_icp_query_timeout
7541 LOC: Config.Timeout.mcast_icp_query
7543 For multicast peers, Squid regularly sends out ICP "probes" to
7544 count how many other peers are listening on the given multicast
7545 address. This value specifies how long Squid should wait to
7546 count all the replies. The default is 2000 msec, or 2
7551 INTERNAL ICON OPTIONS
7552 -----------------------------------------------------------------------------
7555 NAME: icon_directory
7557 LOC: Config.icons.directory
7558 DEFAULT: @DEFAULT_ICON_DIR@
7560 Where the icons are stored. These are normally kept in
7564 NAME: global_internal_static
7566 LOC: Config.onoff.global_internal_static
7569 This directive controls is Squid should intercept all requests for
7570 /squid-internal-static/ no matter which host the URL is requesting
7571 (default on setting), or if nothing special should be done for
7572 such URLs (off setting). The purpose of this directive is to make
7573 icons etc work better in complex cache hierarchies where it may
7574 not always be possible for all corners in the cache mesh to reach
7575 the server generating a directory listing.
7578 NAME: short_icon_urls
7580 LOC: Config.icons.use_short_names
7583 If this is enabled Squid will use short URLs for icons.
7584 If disabled it will revert to the old behavior of including
7585 it's own name and port in the URL.
7587 If you run a complex cache hierarchy with a mix of Squid and
7588 other proxies you may need to disable this directive.
7593 -----------------------------------------------------------------------------
7596 NAME: error_directory
7598 LOC: Config.errorDirectory
7600 DEFAULT_DOC: Send error pages in the clients preferred language
7602 If you wish to create your own versions of the default
7603 error files to customize them to suit your company copy
7604 the error/template files to another directory and point
7607 WARNING: This option will disable multi-language support
7608 on error pages if used.
7610 The squid developers are interested in making squid available in
7611 a wide variety of languages. If you are making translations for a
7612 language that Squid does not currently provide please consider
7613 contributing your translation back to the project.
7614 http://wiki.squid-cache.org/Translations
7616 The squid developers working on translations are happy to supply drop-in
7617 translated error files in exchange for any new language contributions.
7620 NAME: error_default_language
7621 IFDEF: USE_ERR_LOCALES
7623 LOC: Config.errorDefaultLanguage
7625 DEFAULT_DOC: Generate English language pages.
7627 Set the default language which squid will send error pages in
7628 if no existing translation matches the clients language
7631 If unset (default) generic English will be used.
7633 The squid developers are interested in making squid available in
7634 a wide variety of languages. If you are interested in making
7635 translations for any language see the squid wiki for details.
7636 http://wiki.squid-cache.org/Translations
7639 NAME: error_log_languages
7640 IFDEF: USE_ERR_LOCALES
7642 LOC: Config.errorLogMissingLanguages
7645 Log to cache.log what languages users are attempting to
7646 auto-negotiate for translations.
7648 Successful negotiations are not logged. Only failures
7649 have meaning to indicate that Squid may need an upgrade
7650 of its error page translations.
7653 NAME: err_page_stylesheet
7655 LOC: Config.errorStylesheet
7656 DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
7658 CSS Stylesheet to pattern the display of Squid default error pages.
7660 For information on CSS see http://www.w3.org/Style/CSS/
7665 LOC: Config.errHtmlText
7668 HTML text to include in error messages. Make this a "mailto"
7669 URL to your admin address, or maybe just a link to your
7670 organizations Web page.
7672 To include this in your error messages, you must rewrite
7673 the error template files (found in the "errors" directory).
7674 Wherever you want the 'err_html_text' line to appear,
7675 insert a %L tag in the error template file.
7678 NAME: email_err_data
7681 LOC: Config.onoff.emailErrData
7684 If enabled, information about the occurred error will be
7685 included in the mailto links of the ERR pages (if %W is set)
7686 so that the email body contains the data.
7687 Syntax is <A HREF="mailto:%w%W">%w</A>
7692 LOC: Config.denyInfoList
7695 Usage: deny_info err_page_name acl
7696 or deny_info http://... acl
7697 or deny_info TCP_RESET acl
7699 This can be used to return a ERR_ page for requests which
7700 do not pass the 'http_access' rules. Squid remembers the last
7701 acl it evaluated in http_access, and if a 'deny_info' line exists
7702 for that ACL Squid returns a corresponding error page.
7704 The acl is typically the last acl on the http_access deny line which
7705 denied access. The exceptions to this rule are:
7706 - When Squid needs to request authentication credentials. It's then
7707 the first authentication related acl encountered
7708 - When none of the http_access lines matches. It's then the last
7709 acl processed on the last http_access line.
7710 - When the decision to deny access was made by an adaptation service,
7711 the acl name is the corresponding eCAP or ICAP service_name.
7713 NP: If providing your own custom error pages with error_directory
7714 you may also specify them by your custom file name:
7715 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
7717 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
7718 may be specified by prefixing the file name with the code and a colon.
7719 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
7721 Alternatively you can tell Squid to reset the TCP connection
7722 by specifying TCP_RESET.
7724 Or you can specify an error URL or URL pattern. The browsers will
7725 get redirected to the specified URL after formatting tags have
7726 been replaced. Redirect will be done with 302 or 307 according to
7727 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
7728 the URL. e.g. 303:http://example.com/
7731 %a - username (if available. Password NOT included)
7734 %E - Error description
7736 %H - Request domain name
7737 %i - Client IP Address
7739 %o - Message result from external ACL helper
7740 %p - Request Port number
7741 %P - Request Protocol name
7742 %R - Request URL path
7743 %T - Timestamp in RFC 1123 format
7744 %U - Full canonical URL from client
7745 (HTTPS URLs terminate with *)
7746 %u - Full canonical URL from client
7747 %w - Admin email from squid.conf
7749 %% - Literal percent (%) code
7754 OPTIONS INFLUENCING REQUEST FORWARDING
7755 -----------------------------------------------------------------------------
7758 NAME: nonhierarchical_direct
7760 LOC: Config.onoff.nonhierarchical_direct
7763 By default, Squid will send any non-hierarchical requests
7764 (not cacheable request type) direct to origin servers.
7766 When this is set to "off", Squid will prefer to send these
7767 requests to parents.
7769 Note that in most configurations, by turning this off you will only
7770 add latency to these request without any improvement in global hit
7773 This option only sets a preference. If the parent is unavailable a
7774 direct connection to the origin server may still be attempted. To
7775 completely prevent direct connections use never_direct.
7780 LOC: Config.onoff.prefer_direct
7783 Normally Squid tries to use parents for most requests. If you for some
7784 reason like it to first try going direct and only use a parent if
7785 going direct fails set this to on.
7787 By combining nonhierarchical_direct off and prefer_direct on you
7788 can set up Squid to use a parent as a backup path if going direct
7791 Note: If you want Squid to use parents for all requests see
7792 the never_direct directive. prefer_direct only modifies how Squid
7793 acts on cacheable requests.
7796 NAME: cache_miss_revalidate
7800 LOC: Config.onoff.cache_miss_revalidate
7802 RFC 7232 defines a conditional request mechanism to prevent
7803 response objects being unnecessarily transferred over the network.
7804 If that mechanism is used by the client and a cache MISS occurs
7805 it can prevent new cache entries being created.
7807 This option determines whether Squid on cache MISS will pass the
7808 client revalidation request to the server or tries to fetch new
7809 content for caching. It can be useful while the cache is mostly
7810 empty to more quickly have the cache populated by generating
7811 non-conditional GETs.
7813 When set to 'on' (default), Squid will pass all client If-* headers
7814 to the server. This permits server responses without a cacheable
7815 payload to be delivered and on MISS no new cache entry is created.
7817 When set to 'off' and if the request is cacheable, Squid will
7818 remove the clients If-Modified-Since and If-None-Match headers from
7819 the request sent to the server. This requests a 200 status response
7820 from the server to create a new cache entry with.
7825 LOC: Config.accessList.AlwaysDirect
7827 DEFAULT_DOC: Prevent any cache_peer being used for this request.
7829 Usage: always_direct allow|deny [!]aclname ...
7831 Here you can use ACL elements to specify requests which should
7832 ALWAYS be forwarded by Squid to the origin servers without using
7833 any peers. For example, to always directly forward requests for
7834 local servers ignoring any parents or siblings you may have use
7837 acl local-servers dstdomain my.domain.net
7838 always_direct allow local-servers
7840 To always forward FTP requests directly, use
7843 always_direct allow FTP
7845 NOTE: There is a similar, but opposite option named
7846 'never_direct'. You need to be aware that "always_direct deny
7847 foo" is NOT the same thing as "never_direct allow foo". You
7848 may need to use a deny rule to exclude a more-specific case of
7849 some other rule. Example:
7851 acl local-external dstdomain external.foo.net
7852 acl local-servers dstdomain .foo.net
7853 always_direct deny local-external
7854 always_direct allow local-servers
7856 NOTE: If your goal is to make the client forward the request
7857 directly to the origin server bypassing Squid then this needs
7858 to be done in the client configuration. Squid configuration
7859 can only tell Squid how Squid should fetch the object.
7861 NOTE: This directive is not related to caching. The replies
7862 is cached as usual even if you use always_direct. To not cache
7863 the replies see the 'cache' directive.
7865 This clause supports both fast and slow acl types.
7866 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7871 LOC: Config.accessList.NeverDirect
7873 DEFAULT_DOC: Allow DNS results to be used for this request.
7875 Usage: never_direct allow|deny [!]aclname ...
7877 never_direct is the opposite of always_direct. Please read
7878 the description for always_direct if you have not already.
7880 With 'never_direct' you can use ACL elements to specify
7881 requests which should NEVER be forwarded directly to origin
7882 servers. For example, to force the use of a proxy for all
7883 requests, except those in your local domain use something like:
7885 acl local-servers dstdomain .foo.net
7886 never_direct deny local-servers
7887 never_direct allow all
7889 or if Squid is inside a firewall and there are local intranet
7890 servers inside the firewall use something like:
7892 acl local-intranet dstdomain .foo.net
7893 acl local-external dstdomain external.foo.net
7894 always_direct deny local-external
7895 always_direct allow local-intranet
7896 never_direct allow all
7898 This clause supports both fast and slow acl types.
7899 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7903 ADVANCED NETWORKING OPTIONS
7904 -----------------------------------------------------------------------------
7907 NAME: incoming_udp_average incoming_icp_average
7910 LOC: Config.comm_incoming.udp.average
7912 Heavy voodoo here. I can't even believe you are reading this.
7913 Are you crazy? Don't even think about adjusting these unless
7914 you understand the algorithms in comm_select.c first!
7917 NAME: incoming_tcp_average incoming_http_average
7920 LOC: Config.comm_incoming.tcp.average
7922 Heavy voodoo here. I can't even believe you are reading this.
7923 Are you crazy? Don't even think about adjusting these unless
7924 you understand the algorithms in comm_select.c first!
7927 NAME: incoming_dns_average
7930 LOC: Config.comm_incoming.dns.average
7932 Heavy voodoo here. I can't even believe you are reading this.
7933 Are you crazy? Don't even think about adjusting these unless
7934 you understand the algorithms in comm_select.c first!
7937 NAME: min_udp_poll_cnt min_icp_poll_cnt
7940 LOC: Config.comm_incoming.udp.min_poll
7942 Heavy voodoo here. I can't even believe you are reading this.
7943 Are you crazy? Don't even think about adjusting these unless
7944 you understand the algorithms in comm_select.c first!
7947 NAME: min_dns_poll_cnt
7950 LOC: Config.comm_incoming.dns.min_poll
7952 Heavy voodoo here. I can't even believe you are reading this.
7953 Are you crazy? Don't even think about adjusting these unless
7954 you understand the algorithms in comm_select.c first!
7957 NAME: min_tcp_poll_cnt min_http_poll_cnt
7960 LOC: Config.comm_incoming.tcp.min_poll
7962 Heavy voodoo here. I can't even believe you are reading this.
7963 Are you crazy? Don't even think about adjusting these unless
7964 you understand the algorithms in comm_select.c first!
7970 LOC: Config.accept_filter
7974 The name of an accept(2) filter to install on Squid's
7975 listen socket(s). This feature is perhaps specific to
7976 FreeBSD and requires support in the kernel.
7978 The 'httpready' filter delays delivering new connections
7979 to Squid until a full HTTP request has been received.
7980 See the accf_http(9) man page for details.
7982 The 'dataready' filter delays delivering new connections
7983 to Squid until there is some data to process.
7984 See the accf_dataready(9) man page for details.
7988 The 'data' filter delays delivering of new connections
7989 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
7990 You may optionally specify a number of seconds to wait by
7991 'data=N' where N is the number of seconds. Defaults to 30
7992 if not specified. See the tcp(7) man page for details.
7995 accept_filter httpready
8000 NAME: client_ip_max_connections
8002 LOC: Config.client_ip_max_connections
8004 DEFAULT_DOC: No limit.
8006 Set an absolute limit on the number of connections a single
8007 client IP can use. Any more than this and Squid will begin to drop
8008 new connections from the client until it closes some links.
8010 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
8011 connections from the client. For finer control use the ACL access controls.
8013 Requires client_db to be enabled (the default).
8015 WARNING: This may noticably slow down traffic received via external proxies
8016 or NAT devices and cause them to rebound error messages back to their clients.
8019 NAME: tcp_recv_bufsize
8023 DEFAULT_DOC: Use operating system TCP defaults.
8024 LOC: Config.tcpRcvBufsz
8026 Size of receive buffer to set for TCP sockets. Probably just
8027 as easy to change your kernel's default.
8028 Omit from squid.conf to use the default buffer size.
8033 -----------------------------------------------------------------------------
8040 LOC: Adaptation::Icap::TheConfig.onoff
8043 If you want to enable the ICAP module support, set this to on.
8046 NAME: icap_connect_timeout
8049 LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
8052 This parameter specifies how long to wait for the TCP connect to
8053 the requested ICAP server to complete before giving up and either
8054 terminating the HTTP transaction or bypassing the failure.
8056 The default for optional services is peer_connect_timeout.
8057 The default for essential services is connect_timeout.
8058 If this option is explicitly set, its value applies to all services.
8061 NAME: icap_io_timeout
8065 DEFAULT_DOC: Use read_timeout.
8066 LOC: Adaptation::Icap::TheConfig.io_timeout_raw
8069 This parameter specifies how long to wait for an I/O activity on
8070 an established, active ICAP connection before giving up and
8071 either terminating the HTTP transaction or bypassing the
8075 NAME: icap_service_failure_limit
8076 COMMENT: limit [in memory-depth time-units]
8077 TYPE: icap_service_failure_limit
8079 LOC: Adaptation::Icap::TheConfig
8082 The limit specifies the number of failures that Squid tolerates
8083 when establishing a new TCP connection with an ICAP service. If
8084 the number of failures exceeds the limit, the ICAP service is
8085 not used for new ICAP requests until it is time to refresh its
8088 A negative value disables the limit. Without the limit, an ICAP
8089 service will not be considered down due to connectivity failures
8090 between ICAP OPTIONS requests.
8092 Squid forgets ICAP service failures older than the specified
8093 value of memory-depth. The memory fading algorithm
8094 is approximate because Squid does not remember individual
8095 errors but groups them instead, splitting the option
8096 value into ten time slots of equal length.
8098 When memory-depth is 0 and by default this option has no
8099 effect on service failure expiration.
8101 Squid always forgets failures when updating service settings
8102 using an ICAP OPTIONS transaction, regardless of this option
8106 # suspend service usage after 10 failures in 5 seconds:
8107 icap_service_failure_limit 10 in 5 seconds
8110 NAME: icap_service_revival_delay
8113 LOC: Adaptation::Icap::TheConfig.service_revival_delay
8116 The delay specifies the number of seconds to wait after an ICAP
8117 OPTIONS request failure before requesting the options again. The
8118 failed ICAP service is considered "down" until fresh OPTIONS are
8121 The actual delay cannot be smaller than the hardcoded minimum
8122 delay of 30 seconds.
8125 NAME: icap_preview_enable
8129 LOC: Adaptation::Icap::TheConfig.preview_enable
8132 The ICAP Preview feature allows the ICAP server to handle the
8133 HTTP message by looking only at the beginning of the message body
8134 or even without receiving the body at all. In some environments,
8135 previews greatly speedup ICAP processing.
8137 During an ICAP OPTIONS transaction, the server may tell Squid what
8138 HTTP messages should be previewed and how big the preview should be.
8139 Squid will not use Preview if the server did not request one.
8141 To disable ICAP Preview for all ICAP services, regardless of
8142 individual ICAP server OPTIONS responses, set this option to "off".
8144 icap_preview_enable off
8147 NAME: icap_preview_size
8150 LOC: Adaptation::Icap::TheConfig.preview_size
8152 DEFAULT_DOC: No preview sent.
8154 The default size of preview data to be sent to the ICAP server.
8155 This value might be overwritten on a per server basis by OPTIONS requests.
8158 NAME: icap_206_enable
8162 LOC: Adaptation::Icap::TheConfig.allow206_enable
8165 206 (Partial Content) responses is an ICAP extension that allows the
8166 ICAP agents to optionally combine adapted and original HTTP message
8167 content. The decision to combine is postponed until the end of the
8168 ICAP response. Squid supports Partial Content extension by default.
8170 Activation of the Partial Content extension is negotiated with each
8171 ICAP service during OPTIONS exchange. Most ICAP servers should handle
8172 negotation correctly even if they do not support the extension, but
8173 some might fail. To disable Partial Content support for all ICAP
8174 services and to avoid any negotiation, set this option to "off".
8180 NAME: icap_default_options_ttl
8183 LOC: Adaptation::Icap::TheConfig.default_options_ttl
8186 The default TTL value for ICAP OPTIONS responses that don't have
8187 an Options-TTL header.
8190 NAME: icap_persistent_connections
8194 LOC: Adaptation::Icap::TheConfig.reuse_connections
8197 Whether or not Squid should use persistent connections to
8201 NAME: adaptation_send_client_ip icap_send_client_ip
8203 IFDEF: USE_ADAPTATION
8205 LOC: Adaptation::Config::send_client_ip
8208 If enabled, Squid shares HTTP client IP information with adaptation
8209 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests.
8210 For eCAP, Squid sets the libecap::metaClientIp transaction option.
8212 See also: adaptation_uses_indirect_client
8215 NAME: adaptation_send_username icap_send_client_username
8217 IFDEF: USE_ADAPTATION
8219 LOC: Adaptation::Config::send_username
8222 This sends authenticated HTTP client username (if available) to
8223 the adaptation service.
8225 For ICAP, the username value is encoded based on the
8226 icap_client_username_encode option and is sent using the header
8227 specified by the icap_client_username_header option.
8230 NAME: icap_client_username_header
8233 LOC: Adaptation::Icap::TheConfig.client_username_header
8234 DEFAULT: X-Client-Username
8236 ICAP request header name to use for adaptation_send_username.
8239 NAME: icap_client_username_encode
8243 LOC: Adaptation::Icap::TheConfig.client_username_encode
8246 Whether to base64 encode the authenticated client username.
8250 TYPE: icap_service_type
8252 LOC: Adaptation::Icap::TheConfig
8255 Defines a single ICAP service using the following format:
8257 icap_service id vectoring_point uri [option ...]
8260 an opaque identifier or name which is used to direct traffic to
8261 this specific service. Must be unique among all adaptation
8262 services in squid.conf.
8264 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8265 This specifies at which point of transaction processing the
8266 ICAP service should be activated. *_postcache vectoring points
8267 are not yet supported.
8269 uri: icap://servername:port/servicepath
8270 ICAP server and service location.
8272 ICAP does not allow a single service to handle both REQMOD and RESPMOD
8273 transactions. Squid does not enforce that requirement. You can specify
8274 services with the same service_url and different vectoring_points. You
8275 can even specify multiple identical services as long as their
8276 service_names differ.
8278 To activate a service, use the adaptation_access directive. To group
8279 services, use adaptation_service_chain and adaptation_service_set.
8281 Service options are separated by white space. ICAP services support
8282 the following name=value options:
8285 If set to 'on' or '1', the ICAP service is treated as
8286 optional. If the service cannot be reached or malfunctions,
8287 Squid will try to ignore any errors and process the message as
8288 if the service was not enabled. No all ICAP errors can be
8289 bypassed. If set to 0, the ICAP service is treated as
8290 essential and all ICAP errors will result in an error page
8291 returned to the HTTP client.
8293 Bypass is off by default: services are treated as essential.
8296 If set to 'on' or '1', the ICAP service is allowed to
8297 dynamically change the current message adaptation plan by
8298 returning a chain of services to be used next. The services
8299 are specified using the X-Next-Services ICAP response header
8300 value, formatted as a comma-separated list of service names.
8301 Each named service should be configured in squid.conf. Other
8302 services are ignored. An empty X-Next-Services value results
8303 in an empty plan which ends the current adaptation.
8305 Dynamic adaptation plan may cross or cover multiple supported
8306 vectoring points in their natural processing order.
8308 Routing is not allowed by default: the ICAP X-Next-Services
8309 response header is ignored.
8312 Only has effect on split-stack systems. The default on those systems
8313 is to use IPv4-only connections. When set to 'on' this option will
8314 make Squid use IPv6-only connections to contact this ICAP service.
8316 on-overload=block|bypass|wait|force
8317 If the service Max-Connections limit has been reached, do
8318 one of the following for each new ICAP transaction:
8319 * block: send an HTTP error response to the client
8320 * bypass: ignore the "over-connected" ICAP service
8321 * wait: wait (in a FIFO queue) for an ICAP connection slot
8322 * force: proceed, ignoring the Max-Connections limit
8324 In SMP mode with N workers, each worker assumes the service
8325 connection limit is Max-Connections/N, even though not all
8326 workers may use a given service.
8328 The default value is "bypass" if service is bypassable,
8329 otherwise it is set to "wait".
8333 Use the given number as the Max-Connections limit, regardless
8334 of the Max-Connections value given by the service, if any.
8336 Older icap_service format without optional named parameters is
8337 deprecated but supported for backward compatibility.
8340 icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0
8341 icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on
8345 TYPE: icap_class_type
8350 This deprecated option was documented to define an ICAP service
8351 chain, even though it actually defined a set of similar, redundant
8352 services, and the chains were not supported.
8354 To define a set of redundant services, please use the
8355 adaptation_service_set directive. For service chains, use
8356 adaptation_service_chain.
8360 TYPE: icap_access_type
8365 This option is deprecated. Please use adaptation_access, which
8366 has the same ICAP functionality, but comes with better
8367 documentation, and eCAP support.
8372 -----------------------------------------------------------------------------
8379 LOC: Adaptation::Ecap::TheConfig.onoff
8382 Controls whether eCAP support is enabled.
8386 TYPE: ecap_service_type
8388 LOC: Adaptation::Ecap::TheConfig
8391 Defines a single eCAP service
8393 ecap_service id vectoring_point uri [option ...]
8396 an opaque identifier or name which is used to direct traffic to
8397 this specific service. Must be unique among all adaptation
8398 services in squid.conf.
8400 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8401 This specifies at which point of transaction processing the
8402 eCAP service should be activated. *_postcache vectoring points
8403 are not yet supported.
8405 uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional
8406 Squid uses the eCAP service URI to match this configuration
8407 line with one of the dynamically loaded services. Each loaded
8408 eCAP service must have a unique URI. Obtain the right URI from
8409 the service provider.
8411 To activate a service, use the adaptation_access directive. To group
8412 services, use adaptation_service_chain and adaptation_service_set.
8414 Service options are separated by white space. eCAP services support
8415 the following name=value options:
8418 If set to 'on' or '1', the eCAP service is treated as optional.
8419 If the service cannot be reached or malfunctions, Squid will try
8420 to ignore any errors and process the message as if the service
8421 was not enabled. No all eCAP errors can be bypassed.
8422 If set to 'off' or '0', the eCAP service is treated as essential
8423 and all eCAP errors will result in an error page returned to the
8426 Bypass is off by default: services are treated as essential.
8429 If set to 'on' or '1', the eCAP service is allowed to
8430 dynamically change the current message adaptation plan by
8431 returning a chain of services to be used next.
8433 Dynamic adaptation plan may cross or cover multiple supported
8434 vectoring points in their natural processing order.
8436 Routing is not allowed by default.
8438 Older ecap_service format without optional named parameters is
8439 deprecated but supported for backward compatibility.
8443 ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off
8444 ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on
8447 NAME: loadable_modules
8449 IFDEF: USE_LOADABLE_MODULES
8450 LOC: Config.loadable_module_names
8453 Instructs Squid to load the specified dynamic module(s) or activate
8454 preloaded module(s).
8456 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
8460 MESSAGE ADAPTATION OPTIONS
8461 -----------------------------------------------------------------------------
8464 NAME: adaptation_service_set
8465 TYPE: adaptation_service_set_type
8466 IFDEF: USE_ADAPTATION
8471 Configures an ordered set of similar, redundant services. This is
8472 useful when hot standby or backup adaptation servers are available.
8474 adaptation_service_set set_name service_name1 service_name2 ...
8476 The named services are used in the set declaration order. The first
8477 applicable adaptation service from the set is used first. The next
8478 applicable service is tried if and only if the transaction with the
8479 previous service fails and the message waiting to be adapted is still
8482 When adaptation starts, broken services are ignored as if they were
8483 not a part of the set. A broken service is a down optional service.
8485 The services in a set must be attached to the same vectoring point
8486 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8488 If all services in a set are optional then adaptation failures are
8489 bypassable. If all services in the set are essential, then a
8490 transaction failure with one service may still be retried using
8491 another service from the set, but when all services fail, the master
8492 transaction fails as well.
8494 A set may contain a mix of optional and essential services, but that
8495 is likely to lead to surprising results because broken services become
8496 ignored (see above), making previously bypassable failures fatal.
8497 Technically, it is the bypassability of the last failed service that
8500 See also: adaptation_access adaptation_service_chain
8503 adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
8504 adaptation service_set svcLogger loggerLocal loggerRemote
8507 NAME: adaptation_service_chain
8508 TYPE: adaptation_service_chain_type
8509 IFDEF: USE_ADAPTATION
8514 Configures a list of complementary services that will be applied
8515 one-by-one, forming an adaptation chain or pipeline. This is useful
8516 when Squid must perform different adaptations on the same message.
8518 adaptation_service_chain chain_name service_name1 svc_name2 ...
8520 The named services are used in the chain declaration order. The first
8521 applicable adaptation service from the chain is used first. The next
8522 applicable service is applied to the successful adaptation results of
8523 the previous service in the chain.
8525 When adaptation starts, broken services are ignored as if they were
8526 not a part of the chain. A broken service is a down optional service.
8528 Request satisfaction terminates the adaptation chain because Squid
8529 does not currently allow declaration of RESPMOD services at the
8530 "reqmod_precache" vectoring point (see icap_service or ecap_service).
8532 The services in a chain must be attached to the same vectoring point
8533 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8535 A chain may contain a mix of optional and essential services. If an
8536 essential adaptation fails (or the failure cannot be bypassed for
8537 other reasons), the master transaction fails. Otherwise, the failure
8538 is bypassed as if the failed adaptation service was not in the chain.
8540 See also: adaptation_access adaptation_service_set
8543 adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
8546 NAME: adaptation_access
8547 TYPE: adaptation_access_type
8548 IFDEF: USE_ADAPTATION
8551 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
8553 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
8555 adaptation_access service_name allow|deny [!]aclname...
8556 adaptation_access set_name allow|deny [!]aclname...
8558 At each supported vectoring point, the adaptation_access
8559 statements are processed in the order they appear in this
8560 configuration file. Statements pointing to the following services
8561 are ignored (i.e., skipped without checking their ACL):
8563 - services serving different vectoring points
8564 - "broken-but-bypassable" services
8565 - "up" services configured to ignore such transactions
8566 (e.g., based on the ICAP Transfer-Ignore header).
8568 When a set_name is used, all services in the set are checked
8569 using the same rules, to find the first applicable one. See
8570 adaptation_service_set for details.
8572 If an access list is checked and there is a match, the
8573 processing stops: For an "allow" rule, the corresponding
8574 adaptation service is used for the transaction. For a "deny"
8575 rule, no adaptation service is activated.
8577 It is currently not possible to apply more than one adaptation
8578 service at the same vectoring point to the same HTTP transaction.
8580 See also: icap_service and ecap_service
8583 adaptation_access service_1 allow all
8586 NAME: adaptation_service_iteration_limit
8588 IFDEF: USE_ADAPTATION
8589 LOC: Adaptation::Config::service_iteration_limit
8592 Limits the number of iterations allowed when applying adaptation
8593 services to a message. If your longest adaptation set or chain
8594 may have more than 16 services, increase the limit beyond its
8595 default value of 16. If detecting infinite iteration loops sooner
8596 is critical, make the iteration limit match the actual number
8597 of services in your longest adaptation set or chain.
8599 Infinite adaptation loops are most likely with routing services.
8601 See also: icap_service routing=1
8604 NAME: adaptation_masterx_shared_names
8606 IFDEF: USE_ADAPTATION
8607 LOC: Adaptation::Config::masterx_shared_name
8610 For each master transaction (i.e., the HTTP request and response
8611 sequence, including all related ICAP and eCAP exchanges), Squid
8612 maintains a table of metadata. The table entries are (name, value)
8613 pairs shared among eCAP and ICAP exchanges. The table is destroyed
8614 with the master transaction.
8616 This option specifies the table entry names that Squid must accept
8617 from and forward to the adaptation transactions.
8619 An ICAP REQMOD or RESPMOD transaction may set an entry in the
8620 shared table by returning an ICAP header field with a name
8621 specified in adaptation_masterx_shared_names.
8623 An eCAP REQMOD or RESPMOD transaction may set an entry in the
8624 shared table by implementing the libecap::visitEachOption() API
8625 to provide an option with a name specified in
8626 adaptation_masterx_shared_names.
8628 Squid will store and forward the set entry to subsequent adaptation
8629 transactions within the same master transaction scope.
8631 Only one shared entry name is supported at this time.
8634 # share authentication information among ICAP services
8635 adaptation_masterx_shared_names X-Subscriber-ID
8638 NAME: adaptation_meta
8640 IFDEF: USE_ADAPTATION
8641 LOC: Adaptation::Config::metaHeaders
8644 This option allows Squid administrator to add custom ICAP request
8645 headers or eCAP options to Squid ICAP requests or eCAP transactions.
8646 Use it to pass custom authentication tokens and other
8647 transaction-state related meta information to an ICAP/eCAP service.
8649 The addition of a meta header is ACL-driven:
8650 adaptation_meta name value [!]aclname ...
8652 Processing for a given header name stops after the first ACL list match.
8653 Thus, it is impossible to add two headers with the same name. If no ACL
8654 lists match for a given header name, no such header is added. For
8657 # do not debug transactions except for those that need debugging
8658 adaptation_meta X-Debug 1 needs_debugging
8660 # log all transactions except for those that must remain secret
8661 adaptation_meta X-Log 1 !keep_secret
8663 # mark transactions from users in the "G 1" group
8664 adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1
8666 The "value" parameter may be a regular squid.conf token or a "double
8667 quoted string". Within the quoted string, use backslash (\) to escape
8668 any character, which is currently only useful for escaping backslashes
8669 and double quotes. For example,
8670 "this string has one backslash (\\) and two \"quotes\""
8672 Used adaptation_meta header values may be logged via %note
8673 logformat code. If multiple adaptation_meta headers with the same name
8674 are used during master transaction lifetime, the header values are
8675 logged in the order they were used and duplicate values are ignored
8676 (only the first repeated value will be logged).
8682 LOC: Adaptation::Icap::TheConfig.repeat
8683 DEFAULT_IF_NONE: deny all
8685 This ACL determines which retriable ICAP transactions are
8686 retried. Transactions that received a complete ICAP response
8687 and did not have to consume or produce HTTP bodies to receive
8688 that response are usually retriable.
8690 icap_retry allow|deny [!]aclname ...
8692 Squid automatically retries some ICAP I/O timeouts and errors
8693 due to persistent connection race conditions.
8695 See also: icap_retry_limit
8698 NAME: icap_retry_limit
8701 LOC: Adaptation::Icap::TheConfig.repeat_limit
8703 DEFAULT_DOC: No retries are allowed.
8705 Limits the number of retries allowed.
8707 Communication errors due to persistent connection race
8708 conditions are unavoidable, automatically retried, and do not
8709 count against this limit.
8711 See also: icap_retry
8717 -----------------------------------------------------------------------------
8720 NAME: check_hostnames
8723 LOC: Config.onoff.check_hostnames
8725 For security and stability reasons Squid can check
8726 hostnames for Internet standard RFC compliance. If you want
8727 Squid to perform these checks turn this directive on.
8730 NAME: allow_underscore
8733 LOC: Config.onoff.allow_underscore
8735 Underscore characters is not strictly allowed in Internet hostnames
8736 but nevertheless used by many sites. Set this to off if you want
8737 Squid to be strict about the standard.
8738 This check is performed only when check_hostnames is set to on.
8741 NAME: dns_retransmit_interval
8744 LOC: Config.Timeout.idns_retransmit
8746 Initial retransmit interval for DNS queries. The interval is
8747 doubled each time all configured DNS servers have been tried.
8753 LOC: Config.Timeout.idns_query
8755 DNS Query timeout. If no response is received to a DNS query
8756 within this time all DNS servers for the queried domain
8757 are assumed to be unavailable.
8760 NAME: dns_packet_max
8762 DEFAULT_DOC: EDNS disabled
8764 LOC: Config.dns.packet_max
8766 Maximum number of bytes packet size to advertise via EDNS.
8767 Set to "none" to disable EDNS large packet support.
8769 For legacy reasons DNS UDP replies will default to 512 bytes which
8770 is too small for many responses. EDNS provides a means for Squid to
8771 negotiate receiving larger responses back immediately without having
8772 to failover with repeat requests. Responses larger than this limit
8773 will retain the old behaviour of failover to TCP DNS.
8775 Squid has no real fixed limit internally, but allowing packet sizes
8776 over 1500 bytes requires network jumbogram support and is usually not
8779 WARNING: The RFC also indicates that some older resolvers will reply
8780 with failure of the whole request if the extension is added. Some
8781 resolvers have already been identified which will reply with mangled
8782 EDNS response on occasion. Usually in response to many-KB jumbogram
8783 sizes being advertised by Squid.
8784 Squid will currently treat these both as an unable-to-resolve domain
8785 even if it would be resolvable without EDNS.
8792 DEFAULT_DOC: Search for single-label domain names is disabled.
8793 LOC: Config.onoff.res_defnames
8795 Normally the RES_DEFNAMES resolver option is disabled
8796 (see res_init(3)). This prevents caches in a hierarchy
8797 from interpreting single-component hostnames locally. To allow
8798 Squid to handle single-component names, enable this option.
8801 NAME: dns_multicast_local
8805 DEFAULT_DOC: Search for .local and .arpa names is disabled.
8806 LOC: Config.onoff.dns_mdns
8808 When set to on, Squid sends multicast DNS lookups on the local
8809 network for domains ending in .local and .arpa.
8810 This enables local servers and devices to be contacted in an
8811 ad-hoc or zero-configuration network environment.
8814 NAME: dns_nameservers
8817 DEFAULT_DOC: Use operating system definitions
8818 LOC: Config.dns_nameservers
8820 Use this if you want to specify a list of DNS name servers
8821 (IP addresses) to use instead of those given in your
8822 /etc/resolv.conf file.
8824 On Windows platforms, if no value is specified here or in
8825 the /etc/resolv.conf file, the list of DNS name servers are
8826 taken from the Windows registry, both static and dynamic DHCP
8827 configurations are supported.
8829 Example: dns_nameservers 10.0.0.1 192.172.0.4
8834 DEFAULT: @DEFAULT_HOSTS@
8835 LOC: Config.etcHostsPath
8837 Location of the host-local IP name-address associations
8838 database. Most Operating Systems have such a file on different
8840 - Un*X & Linux: /etc/hosts
8841 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
8842 (%SystemRoot% value install default is c:\winnt)
8843 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
8844 (%SystemRoot% value install default is c:\windows)
8845 - Windows 9x/Me: %windir%\hosts
8846 (%windir% value is usually c:\windows)
8847 - Cygwin: /etc/hosts
8849 The file contains newline-separated definitions, in the
8850 form ip_address_in_dotted_form name [name ...] names are
8851 whitespace-separated. Lines beginning with an hash (#)
8852 character are comments.
8854 The file is checked at startup and upon configuration.
8855 If set to 'none', it won't be checked.
8856 If append_domain is used, that domain will be added to
8857 domain-local (i.e. not containing any dot character) host
8863 LOC: Config.appendDomain
8865 DEFAULT_DOC: Use operating system definitions
8867 Appends local domain name to hostnames without any dots in
8868 them. append_domain must begin with a period.
8870 Be warned there are now Internet names with no dots in
8871 them using only top-domain names, so setting this may
8872 cause some Internet sites to become unavailable.
8875 append_domain .yourdomain.com
8878 NAME: ignore_unknown_nameservers
8880 LOC: Config.onoff.ignore_unknown_nameservers
8883 By default Squid checks that DNS responses are received
8884 from the same IP addresses they are sent to. If they
8885 don't match, Squid ignores the response and writes a warning
8886 message to cache.log. You can allow responses from unknown
8887 nameservers by setting this option to 'off'.
8893 LOC: Config.dns.v4_first
8895 With the IPv6 Internet being as fast or faster than IPv4 Internet
8896 for most networks Squid prefers to contact websites over IPv6.
8898 This option reverses the order of preference to make Squid contact
8899 dual-stack websites over IPv4 first. Squid will still perform both
8900 IPv6 and IPv4 DNS lookups before connecting.
8903 This option will restrict the situations under which IPv6
8904 connectivity is used (and tested). Hiding network problems
8905 which would otherwise be detected and warned about.
8909 COMMENT: (number of entries)
8912 LOC: Config.ipcache.size
8914 Maximum number of DNS IP cache entries.
8921 LOC: Config.ipcache.low
8928 LOC: Config.ipcache.high
8930 The size, low-, and high-water marks for the IP cache.
8933 NAME: fqdncache_size
8934 COMMENT: (number of entries)
8937 LOC: Config.fqdncache.size
8939 Maximum number of FQDN cache entries.
8944 -----------------------------------------------------------------------------
8947 NAME: configuration_includes_quoted_values
8949 TYPE: configuration_includes_quoted_values
8951 LOC: ConfigParser::RecognizeQuotedValues
8953 If set, Squid will recognize each "quoted string" after a configuration
8954 directive as a single parameter. The quotes are stripped before the
8955 parameter value is interpreted or used.
8956 See "Values with spaces, quotes, and other special characters"
8957 section for more details.
8964 LOC: Config.onoff.mem_pools
8966 If set, Squid will keep pools of allocated (but unused) memory
8967 available for future use. If memory is a premium on your
8968 system and you believe your malloc library outperforms Squid
8969 routines, disable this.
8972 NAME: memory_pools_limit
8976 LOC: Config.MemPools.limit
8978 Used only with memory_pools on:
8979 memory_pools_limit 50 MB
8981 If set to a non-zero value, Squid will keep at most the specified
8982 limit of allocated (but unused) memory in memory pools. All free()
8983 requests that exceed this limit will be handled by your malloc
8984 library. Squid does not pre-allocate any memory, just safe-keeps
8985 objects that otherwise would be free()d. Thus, it is safe to set
8986 memory_pools_limit to a reasonably high value even if your
8987 configuration will use less memory.
8989 If set to none, Squid will keep all memory it can. That is, there
8990 will be no limit on the total amount of memory used for safe-keeping.
8992 To disable memory allocation optimization, do not set
8993 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
8995 An overhead for maintaining memory pools is not taken into account
8996 when the limit is checked. This overhead is close to four bytes per
8997 object kept. However, pools may actually _save_ memory because of
8998 reduced memory thrashing in your malloc library.
9002 COMMENT: on|off|transparent|truncate|delete
9005 LOC: opt_forwarded_for
9007 If set to "on", Squid will append your client's IP address
9008 in the HTTP requests it forwards. By default it looks like:
9010 X-Forwarded-For: 192.1.2.3
9012 If set to "off", it will appear as
9014 X-Forwarded-For: unknown
9016 If set to "transparent", Squid will not alter the
9017 X-Forwarded-For header in any way.
9019 If set to "delete", Squid will delete the entire
9020 X-Forwarded-For header.
9022 If set to "truncate", Squid will remove all existing
9023 X-Forwarded-For entries, and place the client IP as the sole entry.
9026 NAME: cachemgr_passwd
9027 TYPE: cachemgrpasswd
9029 DEFAULT_DOC: No password. Actions which require password are denied.
9030 LOC: Config.passwd_list
9032 Specify passwords for cachemgr operations.
9034 Usage: cachemgr_passwd password action action ...
9036 Some valid actions are (see cache manager menu for a full list):
9076 * Indicates actions which will not be performed without a
9077 valid password, others can be performed if not listed here.
9079 To disable an action, set the password to "disable".
9080 To allow performing an action without a password, set the
9083 Use the keyword "all" to set the same password for all actions.
9086 cachemgr_passwd secret shutdown
9087 cachemgr_passwd lesssssssecret info stats/objects
9088 cachemgr_passwd disable all
9095 LOC: Config.onoff.client_db
9097 If you want to disable collecting per-client statistics,
9098 turn off client_db here.
9101 NAME: refresh_all_ims
9105 LOC: Config.onoff.refresh_all_ims
9107 When you enable this option, squid will always check
9108 the origin server for an update when a client sends an
9109 If-Modified-Since request. Many browsers use IMS
9110 requests when the user requests a reload, and this
9111 ensures those clients receive the latest version.
9113 By default (off), squid may return a Not Modified response
9114 based on the age of the cached version.
9117 NAME: reload_into_ims
9118 IFDEF: USE_HTTP_VIOLATIONS
9122 LOC: Config.onoff.reload_into_ims
9124 When you enable this option, client no-cache or ``reload''
9125 requests will be changed to If-Modified-Since requests.
9126 Doing this VIOLATES the HTTP standard. Enabling this
9127 feature could make you liable for problems which it
9130 see also refresh_pattern for a more selective approach.
9133 NAME: connect_retries
9135 LOC: Config.connect_retries
9137 DEFAULT_DOC: Do not retry failed connections.
9139 This sets the maximum number of connection attempts made for each
9140 TCP connection. The connect_retries attempts must all still
9141 complete within the connection timeout period.
9143 The default is not to re-try if the first connection attempt fails.
9144 The (not recommended) maximum is 10 tries.
9146 A warning message will be generated if it is set to a too-high
9147 value and the configured value will be over-ridden.
9149 Note: These re-tries are in addition to forward_max_tries
9150 which limit how many different addresses may be tried to find
9154 NAME: retry_on_error
9156 LOC: Config.retry.onerror
9159 If set to ON Squid will automatically retry requests when
9160 receiving an error response with status 403 (Forbidden),
9161 500 (Internal Error), 501 or 503 (Service not available).
9162 Status 502 and 504 (Gateway errors) are always retried.
9164 This is mainly useful if you are in a complex cache hierarchy to
9165 work around access control errors.
9167 NOTE: This retry will attempt to find another working destination.
9168 Which is different from the server which just failed.
9171 NAME: as_whois_server
9173 LOC: Config.as_whois_server
9174 DEFAULT: whois.ra.net
9176 WHOIS server to query for AS numbers. NOTE: AS numbers are
9177 queried only when Squid starts up, not for every request.
9182 LOC: Config.onoff.offline
9185 Enable this option and Squid will never try to validate cached
9189 NAME: uri_whitespace
9190 TYPE: uri_whitespace
9191 LOC: Config.uri_whitespace
9194 What to do with requests that have whitespace characters in the
9197 strip: The whitespace characters are stripped out of the URL.
9198 This is the behavior recommended by RFC2396 and RFC3986
9199 for tolerant handling of generic URI.
9200 NOTE: This is one difference between generic URI and HTTP URLs.
9202 deny: The request is denied. The user receives an "Invalid
9204 This is the behaviour recommended by RFC2616 for safe
9205 handling of HTTP request URL.
9207 allow: The request is allowed and the URI is not changed. The
9208 whitespace characters remain in the URI. Note the
9209 whitespace is passed to redirector processes if they
9211 Note this may be considered a violation of RFC2616
9212 request parsing where whitespace is prohibited in the
9215 encode: The request is allowed and the whitespace characters are
9216 encoded according to RFC1738.
9218 chop: The request is allowed and the URI is chopped at the
9222 NOTE the current Squid implementation of encode and chop violates
9223 RFC2616 by not using a 301 redirect after altering the URL.
9228 LOC: Config.chroot_dir
9231 Specifies a directory where Squid should do a chroot() while
9232 initializing. This also causes Squid to fully drop root
9233 privileges after initializing. This means, for example, if you
9234 use a HTTP port less than 1024 and try to reconfigure, you may
9235 get an error saying that Squid can not open the port.
9238 NAME: balance_on_multiple_ip
9240 LOC: Config.onoff.balance_on_multiple_ip
9243 Modern IP resolvers in squid sort lookup results by preferred access.
9244 By default squid will use these IP in order and only rotates to
9245 the next listed when the most preffered fails.
9247 Some load balancing servers based on round robin DNS have been
9248 found not to preserve user session state across requests
9249 to different IP addresses.
9251 Enabling this directive Squid rotates IP's per request.
9254 NAME: pipeline_prefetch
9255 TYPE: pipelinePrefetch
9256 LOC: Config.pipeline_max_prefetch
9258 DEFAULT_DOC: Do not pre-parse pipelined requests.
9260 HTTP clients may send a pipeline of 1+N requests to Squid using a
9261 single connection, without waiting for Squid to respond to the first
9262 of those requests. This option limits the number of concurrent
9263 requests Squid will try to handle in parallel. If set to N, Squid
9264 will try to receive and process up to 1+N requests on the same
9265 connection concurrently.
9267 Defaults to 0 (off) for bandwidth management and access logging
9270 NOTE: pipelining requires persistent connections to clients.
9272 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication.
9275 NAME: high_response_time_warning
9278 LOC: Config.warnings.high_rptm
9280 DEFAULT_DOC: disabled.
9282 If the one-minute median response time exceeds this value,
9283 Squid prints a WARNING with debug level 0 to get the
9284 administrators attention. The value is in milliseconds.
9287 NAME: high_page_fault_warning
9289 LOC: Config.warnings.high_pf
9291 DEFAULT_DOC: disabled.
9293 If the one-minute average page fault rate exceeds this
9294 value, Squid prints a WARNING with debug level 0 to get
9295 the administrators attention. The value is in page faults
9299 NAME: high_memory_warning
9301 LOC: Config.warnings.high_memory
9302 IFDEF: HAVE_MSTATS&&HAVE_GNUMALLOC_H
9304 DEFAULT_DOC: disabled.
9306 If the memory usage (as determined by gnumalloc, if available and used)
9307 exceeds this amount, Squid prints a WARNING with debug level 0 to get
9308 the administrators attention.
9310 # TODO: link high_memory_warning to mempools?
9312 NAME: sleep_after_fork
9313 COMMENT: (microseconds)
9315 LOC: Config.sleep_after_fork
9318 When this is set to a non-zero value, the main Squid process
9319 sleeps the specified number of microseconds after a fork()
9320 system call. This sleep may help the situation where your
9321 system reports fork() failures due to lack of (virtual)
9322 memory. Note, however, if you have a lot of child
9323 processes, these sleep delays will add up and your
9324 Squid will not service requests for some amount of time
9325 until all the child processes have been started.
9326 On Windows value less then 1000 (1 milliseconds) are
9330 NAME: windows_ipaddrchangemonitor
9331 IFDEF: _SQUID_WINDOWS_
9335 LOC: Config.onoff.WIN32_IpAddrChangeMonitor
9337 On Windows Squid by default will monitor IP address changes and will
9338 reconfigure itself after any detected event. This is very useful for
9339 proxies connected to internet with dial-up interfaces.
9340 In some cases (a Proxy server acting as VPN gateway is one) it could be
9341 desiderable to disable this behaviour setting this to 'off'.
9342 Note: after changing this, Squid service must be restarted.
9347 IFDEF: USE_SQUID_EUI
9349 LOC: Eui::TheConfig.euiLookup
9351 Whether to lookup the EUI or MAC address of a connected client.
9354 NAME: max_filedescriptors max_filedesc
9357 DEFAULT_DOC: Use operating system limits set by ulimit.
9358 LOC: Config.max_filedescriptors
9360 Reduce the maximum number of filedescriptors supported below
9361 the usual operating system defaults.
9363 Remove from squid.conf to inherit the current ulimit setting.
9365 Note: Changing this requires a restart of Squid. Also
9366 not all I/O types supports large values (eg on Windows).
9373 DEFAULT_DOC: SMP support disabled.
9375 Number of main Squid processes or "workers" to fork and maintain.
9376 0: "no daemon" mode, like running "squid -N ..."
9377 1: "no SMP" mode, start one main Squid process daemon (default)
9378 N: start N main Squid process daemons (i.e., SMP mode)
9380 In SMP mode, each worker does nearly all what a single Squid daemon
9381 does (e.g., listen on http_port and forward HTTP requests).
9384 NAME: cpu_affinity_map
9385 TYPE: CpuAffinityMap
9386 LOC: Config.cpuAffinityMap
9388 DEFAULT_DOC: Let operating system decide.
9390 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
9392 Sets 1:1 mapping between Squid processes and CPU cores. For example,
9394 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
9396 affects processes 1 through 4 only and places them on the first
9397 four even cores, starting with core #1.
9399 CPU cores are numbered starting from 1. Requires support for
9400 sched_getaffinity(2) and sched_setaffinity(2) system calls.
9402 Multiple cpu_affinity_map options are merged.
9407 NAME: force_request_body_continuation
9409 LOC: Config.accessList.forceRequestBodyContinuation
9411 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
9413 This option controls how Squid handles data upload requests from HTTP
9414 and FTP agents that require a "Please Continue" control message response
9415 to actually send the request body to Squid. It is mostly useful in
9416 adaptation environments.
9418 When Squid receives an HTTP request with an "Expect: 100-continue"
9419 header or an FTP upload command (e.g., STOR), Squid normally sends the
9420 request headers or FTP command information to an adaptation service (or
9421 peer) and waits for a response. Most adaptation services (and some
9422 broken peers) may not respond to Squid at that stage because they may
9423 decide to wait for the HTTP request body or FTP data transfer. However,
9424 that request body or data transfer may never come because Squid has not
9425 responded with the HTTP 100 or FTP 150 (Please Continue) control message
9426 to the request sender yet!
9428 An allow match tells Squid to respond with the HTTP 100 or FTP 150
9429 (Please Continue) control message on its own, before forwarding the
9430 request to an adaptation service or peer. Such a response usually forces
9431 the request sender to proceed with sending the body. A deny match tells
9432 Squid to delay that control response until the origin server confirms
9433 that the request body is needed. Delaying is the default behavior.
projects / thirdparty / squid.git / blob