1 ## Copyright (C) 1996-2016 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 NAME: sslproxy_cafile
161 Remove this line. Use tls_outgoing_options cafile= instead.
164 NAME: sslproxy_capath
167 Remove this line. Use tls_outgoing_options capath= instead.
170 NAME: sslproxy_cipher
173 Remove this line. Use tls_outgoing_options cipher= instead.
176 NAME: sslproxy_client_certificate
179 Remove this line. Use tls_outgoing_options cert= instead.
182 NAME: sslproxy_client_key
185 Remove this line. Use tls_outgoing_options key= instead.
191 Remove this line. Use tls_outgoing_options flags= instead.
194 NAME: sslproxy_options
197 Remove this line. Use tls_outgoing_options options= instead.
200 NAME: sslproxy_version
203 Remove this line. Use tls_outgoing_options options= instead.
206 # Options removed in 3.5
207 NAME: hierarchy_stoplist
210 Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use.
213 # Options removed in 3.4
217 Remove this line. Use acls with access_log directives to control access logging
223 Remove this line. Use acls with icap_log directives to control icap logging
226 # Options Removed in 3.3
227 NAME: ignore_ims_on_miss
230 Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'.
233 # Options Removed in 3.2
234 NAME: chunked_request_body_max_size
237 Remove this line. Squid is now HTTP/1.1 compliant.
240 NAME: dns_v4_fallback
243 Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant.
246 NAME: emulate_httpd_log
249 Replace this with an access_log directive using the format 'common' or 'combined'.
255 Use a regular access.log with ACL limiting it to MISS events.
261 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
264 NAME: ignore_expect_100
267 Remove this line. The HTTP/1.1 feature is now fully supported by default.
273 Remove this option from your config. To log FQDN use %>A in the log format.
276 NAME: log_ip_on_direct
279 Remove this option from your config. To log server or peer names use %<A in the log format.
282 NAME: maximum_single_addr_tries
285 Replaced by connect_retries. The behaviour has changed, please read the documentation before altering.
288 NAME: referer_log referrer_log
291 Replace this with an access_log directive using the format 'referrer'.
297 Remove this line. The feature is supported by default in storage types where update is implemented.
300 NAME: url_rewrite_concurrency
303 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead.
309 Replace this with an access_log directive using the format 'useragent'.
312 # Options Removed in 3.1
316 Remove this line. DNS is no longer tested on startup.
319 NAME: extension_methods
322 Remove this line. All valid methods for HTTP are accepted by default.
325 # 2.7 Options Removed/Replaced in 3.2
330 # 2.7 Options Removed/Replaced in 3.1
338 Remove this line. HTTP/1.1 is supported by default.
341 NAME: upgrade_http0.9
344 Remove this line. ICY/1.0 streaming protocol is supported by default.
347 NAME: zph_local zph_mode zph_option zph_parent zph_sibling
350 Alter these entries. Use the qos_flows directive instead.
353 # Options Removed in 3.0
357 Since squid-3.0 replace with request_header_access or reply_header_access
358 depending on whether you wish to match client requests or server replies.
361 NAME: httpd_accel_no_pmtu_disc
364 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
367 NAME: wais_relay_host
370 Replace this line with 'cache_peer' configuration.
373 NAME: wais_relay_port
376 Replace this line with 'cache_peer' configuration.
381 -----------------------------------------------------------------------------
388 DEFAULT_DOC: SMP support disabled.
390 Number of main Squid processes or "workers" to fork and maintain.
391 0: "no daemon" mode, like running "squid -N ..."
392 1: "no SMP" mode, start one main Squid process daemon (default)
393 N: start N main Squid process daemons (i.e., SMP mode)
395 In SMP mode, each worker does nearly all what a single Squid daemon
396 does (e.g., listen on http_port and forward HTTP requests).
399 NAME: cpu_affinity_map
401 LOC: Config.cpuAffinityMap
403 DEFAULT_DOC: Let operating system decide.
405 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
407 Sets 1:1 mapping between Squid processes and CPU cores. For example,
409 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
411 affects processes 1 through 4 only and places them on the first
412 four even cores, starting with core #1.
414 CPU cores are numbered starting from 1. Requires support for
415 sched_getaffinity(2) and sched_setaffinity(2) system calls.
417 Multiple cpu_affinity_map options are merged.
422 NAME: shared_memory_locking
425 LOC: Config.shmLocking
428 Whether to ensure that all required shared memory is available by
429 "locking" that shared memory into RAM when Squid starts. The
430 alternative is faster startup time followed by slightly slower
431 performance and, if not enough RAM is actually available during
432 runtime, mysterious crashes.
434 SMP Squid uses many shared memory segments. These segments are
435 brought into Squid memory space using an mmap(2) system call. During
436 Squid startup, the mmap() call often succeeds regardless of whether
437 the system has enough RAM. In general, Squid cannot tell whether the
438 kernel applies this "optimistic" memory allocation policy (but
439 popular modern kernels usually use it).
441 Later, if Squid attempts to actually access the mapped memory
442 regions beyond what the kernel is willing to allocate, the
443 "optimistic" kernel simply kills Squid kid with a SIGBUS signal.
444 Some of the memory limits enforced by the kernel are currently
445 poorly understood: We do not know how to detect and check them. This
446 option ensures that the mapped memory will be available.
448 This option may have a positive performance side-effect: Locking
449 memory at start avoids runtime paging I/O. Paging slows Squid down.
451 Locking memory may require a large enough RLIMIT_MEMLOCK OS limit,
452 CAP_IPC_LOCK capability, or equivalent.
456 OPTIONS FOR AUTHENTICATION
457 -----------------------------------------------------------------------------
466 This is used to define parameters for the various authentication
467 schemes supported by Squid.
469 format: auth_param scheme parameter [setting]
471 The order in which authentication schemes are presented to the client is
472 dependent on the order the scheme first appears in config file. IE
473 has a bug (it's not RFC 2617 compliant) in that it will use the basic
474 scheme if basic is the first entry presented, even if more secure
475 schemes are presented. For now use the order in the recommended
476 settings section below. If other browsers have difficulties (don't
477 recognize the schemes offered even if you are using basic) either
478 put basic first, or disable the other schemes (by commenting out their
481 Once an authentication scheme is fully configured, it can only be
482 shutdown by shutting squid down and restarting. Changes can be made on
483 the fly and activated with a reconfigure. I.E. You can change to a
484 different helper, but not unconfigure the helper completely.
486 Please note that while this directive defines how Squid processes
487 authentication it does not automatically activate authentication.
488 To use authentication you must in addition make use of ACLs based
489 on login name in http_access (proxy_auth, proxy_auth_regex or
490 external with %LOGIN used in the format tag). The browser will be
491 challenged for authentication on the first such acl encountered
492 in http_access processing and will also be re-challenged for new
493 login credentials if the request is being denied by a proxy_auth
496 WARNING: authentication can't be used in a transparently intercepting
497 proxy as the client then thinks it is talking to an origin server and
498 not the proxy. This is a limitation of bending the TCP/IP protocol to
499 transparently intercepting port 80, not a limitation in Squid.
500 Ports flagged 'transparent', 'intercept', or 'tproxy' have
501 authentication disabled.
503 === Parameters common to all schemes. ===
506 Specifies the command for the external authenticator.
508 By default, each authentication scheme is not used unless a
509 program is specified.
511 See http://wiki.squid-cache.org/Features/AddonHelpers for
512 more details on helper operations and creating your own.
515 Specifies a string to be append to request line format for
516 the authentication helper. "Quoted" format values may contain
517 spaces and logformat %macros. In theory, any logformat %macro
518 can be used. In practice, a %macro expands as a dash (-) if
519 the helper request is sent before the required macro
520 information is available to Squid.
522 By default, Squid uses request formats provided in
523 scheme-specific examples below (search for %credentials).
525 The expanded key_extras value is added to the Squid credentials
526 cache and, hence, will affect authentication. It can be used to
527 autenticate different users with identical user names (e.g.,
528 when user authentication depends on http_port).
530 Avoid adding frequently changing information to key_extras. For
531 example, if you add user source IP, and it changes frequently
532 in your environment, then max_user_ip ACL is going to treat
533 every user+IP combination as a unique "user", breaking the ACL
534 and wasting a lot of memory on those user records. It will also
535 force users to authenticate from scratch whenever their IP
539 Specifies the protection scope (aka realm name) which is to be
540 reported to the client for the authentication scheme. It is
541 commonly part of the text the user will see when prompted for
542 their username and password.
544 For Basic the default is "Squid proxy-caching web server".
545 For Digest there is no default, this parameter is mandatory.
546 For NTLM and Negotiate this parameter is ignored.
548 "children" numberofchildren [startup=N] [idle=N] [concurrency=N] [queue-size=N]
550 The maximum number of authenticator processes to spawn. If
551 you start too few Squid will have to wait for them to process
552 a backlog of credential verifications, slowing it down. When
553 password verifications are done via a (slow) network you are
554 likely to need lots of authenticator processes.
556 The startup= and idle= options permit some skew in the exact
557 amount run. A minimum of startup=N will begin during startup
558 and reconfigure. Squid will start more in groups of up to
559 idle=N in an attempt to meet traffic needs and to keep idle=N
560 free above those traffic needs up to the maximum.
562 The concurrency= option sets the number of concurrent requests
563 the helper can process. The default of 0 is used for helpers
564 who only supports one request at a time. Setting this to a
565 number greater than 0 changes the protocol used to include a
566 channel ID field first on the request/response line, allowing
567 multiple requests to be sent to the same helper in parallel
568 without waiting for the response.
570 Concurrency must not be set unless it's known the helper
571 supports the input format with channel-ID fields.
573 The queue-size= option sets the maximum number of queued
574 requests. If the queued requests exceed queue size for more
575 than 3 minutes then squid aborts its operation.
576 The default value is set to 2*numberofchildren/
578 NOTE: NTLM and Negotiate schemes do not support concurrency
579 in the Squid code module even though some helpers can.
582 IF HAVE_AUTH_MODULE_BASIC
583 === Basic authentication parameters ===
586 HTTP uses iso-latin-1 as character set, while some
587 authentication backends such as LDAP expects UTF-8. If this is
588 set to on Squid will translate the HTTP iso-latin-1 charset to
589 UTF-8 before sending the username and password to the helper.
591 "credentialsttl" timetolive
592 Specifies how long squid assumes an externally validated
593 username:password pair is valid for - in other words how
594 often the helper program is called for that user. Set this
595 low to force revalidation with short lived passwords.
597 NOTE: setting this high does not impact your susceptibility
598 to replay attacks unless you are using an one-time password
599 system (such as SecureID). If you are using such a system,
600 you will be vulnerable to replay attacks unless you also
601 use the max_user_ip ACL in an http_access rule.
603 "casesensitive" on|off
604 Specifies if usernames are case sensitive. Most user databases
605 are case insensitive allowing the same username to be spelled
606 using both lower and upper case letters, but some are case
607 sensitive. This makes a big difference for user_max_ip ACL
608 processing and similar.
611 IF HAVE_AUTH_MODULE_DIGEST
612 === Digest authentication parameters ===
615 HTTP uses iso-latin-1 as character set, while some
616 authentication backends such as LDAP expects UTF-8. If this is
617 set to on Squid will translate the HTTP iso-latin-1 charset to
618 UTF-8 before sending the username and password to the helper.
620 "nonce_garbage_interval" timeinterval
621 Specifies the interval that nonces that have been issued
622 to client_agent's are checked for validity.
624 "nonce_max_duration" timeinterval
625 Specifies the maximum length of time a given nonce will be
628 "nonce_max_count" number
629 Specifies the maximum number of times a given nonce can be
632 "nonce_strictness" on|off
633 Determines if squid requires strict increment-by-1 behavior
634 for nonce counts, or just incrementing (off - for use when
635 user agents generate nonce counts that occasionally miss 1
636 (ie, 1,2,4,6)). Default off.
638 "check_nonce_count" on|off
639 This directive if set to off can disable the nonce count check
640 completely to work around buggy digest qop implementations in
641 certain mainstream browser versions. Default on to check the
642 nonce count to protect from authentication replay attacks.
644 "post_workaround" on|off
645 This is a workaround to certain buggy browsers who send an
646 incorrect request digest in POST requests when reusing the
647 same nonce as acquired earlier on a GET request.
650 IF HAVE_AUTH_MODULE_NEGOTIATE
651 === Negotiate authentication parameters ===
654 If you experience problems with PUT/POST requests when using
655 the this authentication scheme then you can try setting this
656 to off. This will cause Squid to forcibly close the connection
657 on the initial request where the browser asks which schemes
658 are supported by the proxy.
661 IF HAVE_AUTH_MODULE_NTLM
662 === NTLM authentication parameters ===
665 If you experience problems with PUT/POST requests when using
666 the this authentication scheme then you can try setting this
667 to off. This will cause Squid to forcibly close the connection
668 on the initial request where the browser asks which schemes
669 are supported by the proxy.
672 === Example Configuration ===
674 This configuration displays the recommended authentication scheme
675 order from most to least secure with recommended minimum configuration
676 settings for each scheme:
678 #auth_param negotiate program <uncomment and complete this line to activate>
679 #auth_param negotiate children 20 startup=0 idle=1
680 #auth_param negotiate keep_alive on
682 #auth_param digest program <uncomment and complete this line to activate>
683 #auth_param digest children 20 startup=0 idle=1
684 #auth_param digest realm Squid proxy-caching web server
685 #auth_param digest nonce_garbage_interval 5 minutes
686 #auth_param digest nonce_max_duration 30 minutes
687 #auth_param digest nonce_max_count 50
689 #auth_param ntlm program <uncomment and complete this line to activate>
690 #auth_param ntlm children 20 startup=0 idle=1
691 #auth_param ntlm keep_alive on
693 #auth_param basic program <uncomment and complete this line>
694 #auth_param basic children 5 startup=5 idle=1
695 #auth_param basic realm Squid proxy-caching web server
696 #auth_param basic credentialsttl 2 hours
699 NAME: authenticate_cache_garbage_interval
702 LOC: Config.authenticateGCInterval
704 The time period between garbage collection across the username cache.
705 This is a trade-off between memory utilization (long intervals - say
706 2 days) and CPU (short intervals - say 1 minute). Only change if you
710 NAME: authenticate_ttl
713 LOC: Config.authenticateTTL
715 The time a user & their credentials stay in the logged in
716 user cache since their last request. When the garbage
717 interval passes, all user credentials that have passed their
718 TTL are removed from memory.
721 NAME: authenticate_ip_ttl
723 LOC: Config.authenticateIpTTL
726 If you use proxy authentication and the 'max_user_ip' ACL,
727 this directive controls how long Squid remembers the IP
728 addresses associated with each user. Use a small value
729 (e.g., 60 seconds) if your users might change addresses
730 quickly, as is the case with dialup. You might be safe
731 using a larger value (e.g., 2 hours) in a corporate LAN
732 environment with relatively static address assignments.
737 -----------------------------------------------------------------------------
740 NAME: external_acl_type
741 TYPE: externalAclHelper
742 LOC: Config.externalAclHelperList
745 This option defines external acl classes using a helper program
746 to look up the status
748 external_acl_type name [options] FORMAT /path/to/helper [helper arguments]
752 ttl=n TTL in seconds for cached results (defaults to 3600
756 TTL for cached negative lookups (default same
759 grace=n Percentage remaining of TTL where a refresh of a
760 cached entry should be initiated without needing to
761 wait for a new reply. (default is for no grace period)
763 cache=n The maximum number of entries in the result cache. The
764 default limit is 262144 entries. Each cache entry usually
765 consumes at least 256 bytes. Squid currently does not remove
766 expired cache entries until the limit is reached, so a proxy
767 will sooner or later reach the limit. The expanded FORMAT
768 value is used as the cache key, so if the details in FORMAT
769 are highly variable, a larger cache may be needed to produce
770 reduction in helper load.
773 Maximum number of acl helper processes spawned to service
774 external acl lookups of this type. (default 20)
777 Minimum number of acl helper processes to spawn during
778 startup and reconfigure to service external acl lookups
779 of this type. (default 0)
782 Number of acl helper processes to keep ahead of traffic
783 loads. Squid will spawn this many at once whenever load
784 rises above the capabilities of existing processes.
785 Up to the value of children-max. (default 1)
787 concurrency=n concurrency level per process. Only used with helpers
788 capable of processing more than one query at a time.
790 queue-size=N The queue-size= option sets the maximum number of queued
791 requests. If the queued requests exceed queue size
793 The default value is set to 2*children-max.
795 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers.
797 ipv4 / ipv6 IP protocol used to communicate with this helper.
798 The default is to auto-detect IPv6 and use it when available.
801 FORMAT is a series of %macro codes. See logformat directive for a full list
802 of the accepted codes. Although note that at the time of any external ACL
803 being tested data may not be available and thus some %macro expand to '-'.
805 In addition to the logformat codes; when processing external ACLs these
806 additional macros are made available:
808 %ACL The name of the ACL being tested.
810 %DATA The ACL arguments specified in the referencing config
811 'acl ... external' line, separated by spaces (an
812 "argument string"). see acl external.
814 If there are no ACL arguments %DATA expands to '-'.
816 If you do not specify a DATA macro inside FORMAT,
817 Squid automatically appends %DATA to your FORMAT.
819 By default, Squid applies URL-encoding to each ACL
820 argument inside the argument string. If an explicit
821 encoding modifier is used (e.g., %#DATA), then Squid
822 encodes the whole argument string as a single token
823 (e.g., with %#DATA, spaces between arguments become
826 If SSL is enabled, the following formating codes become available:
828 %USER_CERT SSL User certificate in PEM format
829 %USER_CERTCHAIN SSL User certificate chain in PEM format
830 %USER_CERT_xx SSL User certificate subject attribute xx
831 %USER_CA_CERT_xx SSL User certificate issuer attribute xx
834 NOTE: all other format codes accepted by older Squid versions
838 General request syntax:
840 [channel-ID] FORMAT-values
843 FORMAT-values consists of transaction details expanded with
844 whitespace separation per the config file FORMAT specification
845 using the FORMAT macros listed above.
847 Request values sent to the helper are URL escaped to protect
848 each value in requests against whitespaces.
850 If using protocol=2.5 then the request sent to the helper is not
851 URL escaped to protect against whitespace.
853 NOTE: protocol=3.0 is deprecated as no longer necessary.
855 When using the concurrency= option the protocol is changed by
856 introducing a query channel tag in front of the request/response.
857 The query channel tag is a number between 0 and concurrency-1.
858 This value must be echoed back unchanged to Squid as the first part
859 of the response relating to its request.
862 The helper receives lines expanded per the above format specification
863 and for each input line returns 1 line starting with OK/ERR/BH result
864 code and optionally followed by additional keywords with more details.
867 General result syntax:
869 [channel-ID] result keyword=value ...
871 Result consists of one of the codes:
874 the ACL test produced a match.
877 the ACL test does not produce a match.
880 An internal error occurred in the helper, preventing
881 a result being identified.
883 The meaning of 'a match' is determined by your squid.conf
884 access control configuration. See the Squid wiki for details.
888 user= The users name (login)
890 password= The users password (for login= cache_peer option)
892 message= Message describing the reason for this response.
893 Available as %o in error pages.
894 Useful on (ERR and BH results).
896 tag= Apply a tag to a request. Only sets a tag once,
897 does not alter existing tags.
899 log= String to be logged in access.log. Available as
900 %ea in logformat specifications.
902 clt_conn_tag= Associates a TAG with the client TCP connection.
903 Please see url_rewrite_program related documentation
906 Any keywords may be sent on any response whether OK, ERR or BH.
908 All response keyword values need to be a single token with URL
909 escaping, or enclosed in double quotes (") and escaped using \ on
910 any double quotes or \ characters within the value. The wrapping
911 double quotes are removed before the value is interpreted by Squid.
912 \r and \n are also replace by CR and LF.
914 Some example key values:
918 user="J. \"Bob\" Smith"
925 DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED
926 DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID
927 DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH
928 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
929 DEFAULT: ssl::certSelfSigned ssl_error X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
932 DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
933 DEFAULT: localhost src 127.0.0.1/32 ::1
934 DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
935 DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
937 Defining an Access List
939 Every access list definition must begin with an aclname and acltype,
940 followed by either type-specific arguments or a quoted filename that
943 acl aclname acltype argument ...
944 acl aclname acltype "file" ...
946 When using "file", the file should contain one item per line.
951 Some acl types supports options which changes their default behaviour:
953 -i,+i By default, regular expressions are CASE-SENSITIVE. To make them
954 case-insensitive, use the -i option. To return case-sensitive
955 use the +i option between patterns, or make a new ACL line
958 -n Disable lookups and address type conversions. If lookup or
959 conversion is required because the parameter type (IP or
960 domain name) does not match the message address type (domain
961 name or IP), then the ACL would immediately declare a mismatch
962 without any warnings or lookups.
965 Perform a list membership test, interpreting values as
966 comma-separated token lists and matching against individual
967 tokens instead of whole values.
968 The optional "delimiters" parameter specifies one or more
969 alternative non-alphanumeric delimiter characters.
970 non-alphanumeric delimiter characters.
972 -- Used to stop processing all options, in the case the first acl
973 value has '-' character as first character (for example the '-'
974 is a valid domain name)
976 Some acl types require suspending the current request in order
977 to access some external data source.
978 Those which do are marked with the tag [slow], those which
979 don't are marked as [fast].
980 See http://wiki.squid-cache.org/SquidFaq/SquidAcl
981 for further information
983 ***** ACL TYPES AVAILABLE *****
985 acl aclname src ip-address/mask ... # clients IP address [fast]
986 acl aclname src addr1-addr2/mask ... # range of addresses [fast]
987 acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow]
988 acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
990 acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
992 # The 'arp' ACL code is not portable to all operating systems.
993 # It works on Linux, Solaris, Windows, FreeBSD, and some other
996 # NOTE: Squid can only determine the MAC/EUI address for IPv4
997 # clients that are on the same subnet. If the client is on a
998 # different subnet, then Squid cannot find out its address.
1000 # NOTE 2: IPv6 protocol does not contain ARP. MAC/EUI is either
1001 # encoded directly in the IPv6 address or not available.
1003 acl aclname srcdomain .foo.com ...
1004 # reverse lookup, from client IP [slow]
1005 acl aclname dstdomain [-n] .foo.com ...
1006 # Destination server from URL [fast]
1007 acl aclname srcdom_regex [-i] \.foo\.com ...
1008 # regex matching client name [slow]
1009 acl aclname dstdom_regex [-n] [-i] \.foo\.com ...
1010 # regex matching server [fast]
1012 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
1013 # based URL is used and no match is found. The name "none" is used
1014 # if the reverse lookup fails.
1016 acl aclname src_as number ...
1017 acl aclname dst_as number ...
1019 # Except for access control, AS numbers can be used for
1020 # routing of requests to specific caches. Here's an
1021 # example for routing all requests for AS#1241 and only
1022 # those to mycache.mydomain.net:
1023 # acl asexample dst_as 1241
1024 # cache_peer_access mycache.mydomain.net allow asexample
1025 # cache_peer_access mycache_mydomain.net deny all
1027 acl aclname peername myPeer ...
1029 # match against a named cache_peer entry
1030 # set unique name= on cache_peer lines for reliable use.
1032 acl aclname time [day-abbrevs] [h1:m1-h2:m2]
1042 # h1:m1 must be less than h2:m2
1044 acl aclname url_regex [-i] ^http:// ...
1045 # regex matching on whole URL [fast]
1046 acl aclname urllogin [-i] [^a-zA-Z0-9] ...
1047 # regex matching on URL login field
1048 acl aclname urlpath_regex [-i] \.gif$ ...
1049 # regex matching on URL path [fast]
1051 acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
1053 acl aclname localport 3128 ... # TCP port the client connected to [fast]
1054 # NP: for interception mode this is usually '80'
1056 acl aclname myportname 3128 ... # *_port name [fast]
1058 acl aclname proto HTTP FTP ... # request protocol [fast]
1060 acl aclname method GET POST ... # HTTP request method [fast]
1062 acl aclname http_status 200 301 500- 400-403 ...
1063 # status code in reply [fast]
1065 acl aclname browser [-i] regexp ...
1066 # pattern match on User-Agent header (see also req_header below) [fast]
1068 acl aclname referer_regex [-i] regexp ...
1069 # pattern match on Referer header [fast]
1070 # Referer is highly unreliable, so use with care
1072 acl aclname ident username ...
1073 acl aclname ident_regex [-i] pattern ...
1074 # string match on ident output [slow]
1075 # use REQUIRED to accept any non-null ident.
1077 acl aclname proxy_auth [-i] username ...
1078 acl aclname proxy_auth_regex [-i] pattern ...
1079 # perform http authentication challenge to the client and match against
1080 # supplied credentials [slow]
1082 # takes a list of allowed usernames.
1083 # use REQUIRED to accept any valid username.
1085 # Will use proxy authentication in forward-proxy scenarios, and plain
1086 # http authenticaiton in reverse-proxy scenarios
1088 # NOTE: when a Proxy-Authentication header is sent but it is not
1089 # needed during ACL checking the username is NOT logged
1092 # NOTE: proxy_auth requires a EXTERNAL authentication program
1093 # to check username/password combinations (see
1094 # auth_param directive).
1096 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy
1097 # as the browser needs to be configured for using a proxy in order
1098 # to respond to proxy authentication.
1100 acl aclname snmp_community string ...
1101 # A community string to limit access to your SNMP Agent [fast]
1104 # acl snmppublic snmp_community public
1106 acl aclname maxconn number
1107 # This will be matched when the client's IP address has
1108 # more than <number> TCP connections established. [fast]
1109 # NOTE: This only measures direct TCP links so X-Forwarded-For
1110 # indirect clients are not counted.
1112 acl aclname max_user_ip [-s] number
1113 # This will be matched when the user attempts to log in from more
1114 # than <number> different ip addresses. The authenticate_ip_ttl
1115 # parameter controls the timeout on the ip entries. [fast]
1116 # If -s is specified the limit is strict, denying browsing
1117 # from any further IP addresses until the ttl has expired. Without
1118 # -s Squid will just annoy the user by "randomly" denying requests.
1119 # (the counter is reset each time the limit is reached and a
1120 # request is denied)
1121 # NOTE: in acceleration mode or where there is mesh of child proxies,
1122 # clients may appear to come from multiple addresses if they are
1123 # going through proxy farms, so a limit of 1 may cause user problems.
1125 acl aclname random probability
1126 # Pseudo-randomly match requests. Based on the probability given.
1127 # Probability may be written as a decimal (0.333), fraction (1/3)
1128 # or ratio of matches:non-matches (3:5).
1130 acl aclname req_mime_type [-i] mime-type ...
1131 # regex match against the mime type of the request generated
1132 # by the client. Can be used to detect file upload or some
1133 # types HTTP tunneling requests [fast]
1134 # NOTE: This does NOT match the reply. You cannot use this
1135 # to match the returned file type.
1137 acl aclname req_header header-name [-i] any\.regex\.here
1138 # regex match against any of the known request headers. May be
1139 # thought of as a superset of "browser", "referer" and "mime-type"
1142 acl aclname rep_mime_type [-i] mime-type ...
1143 # regex match against the mime type of the reply received by
1144 # squid. Can be used to detect file download or some
1145 # types HTTP tunneling requests. [fast]
1146 # NOTE: This has no effect in http_access rules. It only has
1147 # effect in rules that affect the reply data stream such as
1148 # http_reply_access.
1150 acl aclname rep_header header-name [-i] any\.regex\.here
1151 # regex match against any of the known reply headers. May be
1152 # thought of as a superset of "browser", "referer" and "mime-type"
1155 acl aclname external class_name [arguments...]
1156 # external ACL lookup via a helper class defined by the
1157 # external_acl_type directive [slow]
1159 acl aclname user_cert attribute values...
1160 # match against attributes in a user SSL certificate
1161 # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]
1163 acl aclname ca_cert attribute values...
1164 # match against attributes a users issuing CA SSL certificate
1165 # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]
1167 acl aclname ext_user username ...
1168 acl aclname ext_user_regex [-i] pattern ...
1169 # string match on username returned by external acl helper [slow]
1170 # use REQUIRED to accept any non-null user name.
1172 acl aclname tag tagvalue ...
1173 # string match on tag returned by external acl helper [fast]
1174 # DEPRECATED. Only the first tag will match with this ACL.
1175 # Use the 'note' ACL instead for handling multiple tag values.
1177 acl aclname hier_code codename ...
1178 # string match against squid hierarchy code(s); [fast]
1179 # e.g., DIRECT, PARENT_HIT, NONE, etc.
1181 # NOTE: This has no effect in http_access rules. It only has
1182 # effect in rules that affect the reply data stream such as
1183 # http_reply_access.
1185 acl aclname note [-m[=delimiters]] name [value ...]
1186 # match transaction annotation [fast]
1187 # Without values, matches any annotation with a given name.
1188 # With value(s), matches any annotation with a given name that
1189 # also has one of the given values.
1190 # If the -m flag is used, then the value of the named
1191 # annotation is interpreted as a list of tokens, and the ACL
1192 # matches individual name=token pairs rather than whole
1193 # name=value pairs. See "ACL Options" above for more info.
1194 # Annotation sources include note and adaptation_meta directives
1195 # as well as helper and eCAP responses.
1197 acl aclname adaptation_service service ...
1198 # Matches the name of any icap_service, ecap_service,
1199 # adaptation_service_set, or adaptation_service_chain that Squid
1200 # has used (or attempted to use) for the master transaction.
1201 # This ACL must be defined after the corresponding adaptation
1202 # service is named in squid.conf. This ACL is usable with
1203 # adaptation_meta because it starts matching immediately after
1204 # the service has been selected for adaptation.
1207 acl aclname ssl_error errorname
1208 # match against SSL certificate validation error [fast]
1210 # For valid error names see in @DEFAULT_ERROR_DIR@/templates/error-details.txt
1213 # The following can be used as shortcuts for certificate properties:
1214 # [ssl::]certHasExpired: the "not after" field is in the past
1215 # [ssl::]certNotYetValid: the "not before" field is in the future
1216 # [ssl::]certUntrusted: The certificate issuer is not to be trusted.
1217 # [ssl::]certSelfSigned: The certificate is self signed.
1218 # [ssl::]certDomainMismatch: The certificate CN domain does not
1219 # match the name the name of the host we are connecting to.
1221 # The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch,
1222 # ssl::certUntrusted, and ssl::certSelfSigned can also be used as
1223 # predefined ACLs, just like the 'all' ACL.
1225 # NOTE: The ssl_error ACL is only supported with sslproxy_cert_error,
1226 # sslproxy_cert_sign, and sslproxy_cert_adapt options.
1228 acl aclname server_cert_fingerprint [-sha1] fingerprint
1229 # match against server SSL certificate fingerprint [fast]
1231 # The fingerprint is the digest of the DER encoded version
1232 # of the whole certificate. The user should use the form: XX:XX:...
1233 # Optional argument specifies the digest algorithm to use.
1234 # The SHA1 digest algorithm is the default and is currently
1235 # the only algorithm supported (-sha1).
1237 acl aclname at_step step
1238 # match against the current step during ssl_bump evaluation [fast]
1239 # Never matches and should not be used outside the ssl_bump context.
1241 # At each SslBump step, Squid evaluates ssl_bump directives to find
1242 # the next bumping action (e.g., peek or splice). Valid SslBump step
1243 # values and the corresponding ssl_bump evaluation moments are:
1244 # SslBump1: After getting TCP-level and HTTP CONNECT info.
1245 # SslBump2: After getting SSL Client Hello info.
1246 # SslBump3: After getting SSL Server Hello info.
1248 acl aclname ssl::server_name .foo.com ...
1249 # matches server name obtained from various sources [fast]
1251 # The server name is obtained during Ssl-Bump steps from such sources
1252 # as CONNECT request URI, client SNI, and SSL server certificate CN.
1253 # During each Ssl-Bump step, Squid may improve its understanding of a
1254 # "true server name". Unlike dstdomain, this ACL does not perform
1257 acl aclname ssl::server_name_regex [-i] \.foo\.com ...
1258 # regex matches server name obtained from various sources [fast]
1260 acl aclname connections_encrypted
1261 # matches transactions with all HTTP messages received over TLS
1262 # transport connections. [fast]
1264 # The master transaction deals with HTTP messages received from
1265 # various sources. All sources used by the master transaction in the
1266 # past are considered by the ACL. The following rules define whether
1267 # a given message source taints the entire master transaction,
1268 # resulting in ACL mismatches:
1270 # * The HTTP client transport connection is not TLS.
1271 # * An adaptation service connection-encryption flag is off.
1272 # * The peer or origin server transport connection is not TLS.
1274 # Caching currently does not affect these rules. This cache ignorance
1275 # implies that only the current HTTP client transport and REQMOD
1276 # services status determine whether this ACL matches a from-cache
1277 # transaction. The source of the cached response does not have any
1278 # effect on future transaction that use the cached response without
1279 # revalidation. This may change.
1281 # DNS, ICP, and HTCP exchanges during the master transaction do not
1282 # affect these rules.
1284 acl aclname any-of acl1 acl2 ...
1285 # match any one of the acls [fast or slow]
1286 # The first matching ACL stops further ACL evaluation.
1288 # ACLs from multiple any-of lines with the same name are ORed.
1289 # For example, A = (a1 or a2) or (a3 or a4) can be written as
1290 # acl A any-of a1 a2
1291 # acl A any-of a3 a4
1293 # This group ACL is fast if all evaluated ACLs in the group are fast
1294 # and slow otherwise.
1296 acl aclname all-of acl1 acl2 ...
1297 # match all of the acls [fast or slow]
1298 # The first mismatching ACL stops further ACL evaluation.
1300 # ACLs from multiple all-of lines with the same name are ORed.
1301 # For example, B = (b1 and b2) or (b3 and b4) can be written as
1302 # acl B all-of b1 b2
1303 # acl B all-of b3 b4
1305 # This group ACL is fast if all evaluated ACLs in the group are fast
1306 # and slow otherwise.
1309 acl macaddress arp 09:00:2b:23:45:67
1310 acl myexample dst_as 1241
1311 acl password proxy_auth REQUIRED
1312 acl fileupload req_mime_type -i ^multipart/form-data$
1313 acl javascript rep_mime_type -i ^application/x-javascript$
1317 # Recommended minimum configuration:
1320 # Example rule allowing access from your local networks.
1321 # Adapt to list your (internal) IP networks from where browsing
1323 acl localnet src 0.0.0.1-0.255.255.255 # RFC 1122 "this" network (LAN)
1324 acl localnet src 10.0.0.0/8 # RFC 1918 local private network (LAN)
1325 acl localnet src 100.64.0.0/10 # RFC 6598 shared address space (CGN)
1326 acl localhet src 169.254.0.0/16 # RFC 3927 link-local (directly plugged) machines
1327 acl localnet src 172.16.0.0/12 # RFC 1918 local private network (LAN)
1328 acl localnet src 192.168.0.0/16 # RFC 1918 local private network (LAN)
1329 acl localnet src fc00::/7 # RFC 4193 local private network range
1330 acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines
1332 acl SSL_ports port 443
1333 acl Safe_ports port 80 # http
1334 acl Safe_ports port 21 # ftp
1335 acl Safe_ports port 443 # https
1336 acl Safe_ports port 70 # gopher
1337 acl Safe_ports port 210 # wais
1338 acl Safe_ports port 1025-65535 # unregistered ports
1339 acl Safe_ports port 280 # http-mgmt
1340 acl Safe_ports port 488 # gss-http
1341 acl Safe_ports port 591 # filemaker
1342 acl Safe_ports port 777 # multiling http
1343 acl CONNECT method CONNECT
1347 NAME: proxy_protocol_access
1349 LOC: Config.accessList.proxyProtocol
1351 DEFAULT_DOC: all TCP connections to ports with require-proxy-header will be denied
1353 Determine which client proxies can be trusted to provide correct
1354 information regarding real client IP address using PROXY protocol.
1356 Requests may pass through a chain of several other proxies
1357 before reaching us. The original source details may by sent in:
1358 * HTTP message Forwarded header, or
1359 * HTTP message X-Forwarded-For header, or
1360 * PROXY protocol connection header.
1362 This directive is solely for validating new PROXY protocol
1363 connections received from a port flagged with require-proxy-header.
1364 It is checked only once after TCP connection setup.
1366 A deny match results in TCP connection closure.
1368 An allow match is required for Squid to permit the corresponding
1369 TCP connection, before Squid even looks for HTTP request headers.
1370 If there is an allow match, Squid starts using PROXY header information
1371 to determine the source address of the connection for all future ACL
1372 checks, logging, etc.
1374 SECURITY CONSIDERATIONS:
1376 Any host from which we accept client IP details can place
1377 incorrect information in the relevant header, and Squid
1378 will use the incorrect information as if it were the
1379 source address of the request. This may enable remote
1380 hosts to bypass any access control restrictions that are
1381 based on the client's source addresses.
1383 This clause only supports fast acl types.
1384 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1387 NAME: follow_x_forwarded_for
1389 IFDEF: FOLLOW_X_FORWARDED_FOR
1390 LOC: Config.accessList.followXFF
1391 DEFAULT_IF_NONE: deny all
1392 DEFAULT_DOC: X-Forwarded-For header will be ignored.
1394 Determine which client proxies can be trusted to provide correct
1395 information regarding real client IP address.
1397 Requests may pass through a chain of several other proxies
1398 before reaching us. The original source details may by sent in:
1399 * HTTP message Forwarded header, or
1400 * HTTP message X-Forwarded-For header, or
1401 * PROXY protocol connection header.
1403 PROXY protocol connections are controlled by the proxy_protocol_access
1404 directive which is checked before this.
1406 If a request reaches us from a source that is allowed by this
1407 directive, then we trust the information it provides regarding
1408 the IP of the client it received from (if any).
1410 For the purpose of ACLs used in this directive the src ACL type always
1411 matches the address we are testing and srcdomain matches its rDNS.
1413 On each HTTP request Squid checks for X-Forwarded-For header fields.
1414 If found the header values are iterated in reverse order and an allow
1415 match is required for Squid to continue on to the next value.
1416 The verification ends when a value receives a deny match, cannot be
1417 tested, or there are no more values to test.
1418 NOTE: Squid does not yet follow the Forwarded HTTP header.
1420 The end result of this process is an IP address that we will
1421 refer to as the indirect client address. This address may
1422 be treated as the client address for access control, ICAP, delay
1423 pools and logging, depending on the acl_uses_indirect_client,
1424 icap_uses_indirect_client, delay_pool_uses_indirect_client,
1425 log_uses_indirect_client and tproxy_uses_indirect_client options.
1427 This clause only supports fast acl types.
1428 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1430 SECURITY CONSIDERATIONS:
1432 Any host from which we accept client IP details can place
1433 incorrect information in the relevant header, and Squid
1434 will use the incorrect information as if it were the
1435 source address of the request. This may enable remote
1436 hosts to bypass any access control restrictions that are
1437 based on the client's source addresses.
1441 acl localhost src 127.0.0.1
1442 acl my_other_proxy srcdomain .proxy.example.com
1443 follow_x_forwarded_for allow localhost
1444 follow_x_forwarded_for allow my_other_proxy
1447 NAME: acl_uses_indirect_client
1450 IFDEF: FOLLOW_X_FORWARDED_FOR
1452 LOC: Config.onoff.acl_uses_indirect_client
1454 Controls whether the indirect client address
1455 (see follow_x_forwarded_for) is used instead of the
1456 direct client address in acl matching.
1458 NOTE: maxconn ACL considers direct TCP links and indirect
1459 clients will always have zero. So no match.
1462 NAME: delay_pool_uses_indirect_client
1465 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS
1467 LOC: Config.onoff.delay_pool_uses_indirect_client
1469 Controls whether the indirect client address
1470 (see follow_x_forwarded_for) is used instead of the
1471 direct client address in delay pools.
1474 NAME: log_uses_indirect_client
1477 IFDEF: FOLLOW_X_FORWARDED_FOR
1479 LOC: Config.onoff.log_uses_indirect_client
1481 Controls whether the indirect client address
1482 (see follow_x_forwarded_for) is used instead of the
1483 direct client address in the access log.
1486 NAME: tproxy_uses_indirect_client
1489 IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER
1491 LOC: Config.onoff.tproxy_uses_indirect_client
1493 Controls whether the indirect client address
1494 (see follow_x_forwarded_for) is used instead of the
1495 direct client address when spoofing the outgoing client.
1497 This has no effect on requests arriving in non-tproxy
1500 SECURITY WARNING: Usage of this option is dangerous
1501 and should not be used trivially. Correct configuration
1502 of follow_x_forwarded_for with a limited set of trusted
1503 sources is required to prevent abuse of your proxy.
1506 NAME: spoof_client_ip
1508 LOC: Config.accessList.spoof_client_ip
1510 DEFAULT_DOC: Allow spoofing on all TPROXY traffic.
1512 Control client IP address spoofing of TPROXY traffic based on
1513 defined access lists.
1515 spoof_client_ip allow|deny [!]aclname ...
1517 If there are no "spoof_client_ip" lines present, the default
1518 is to "allow" spoofing of any suitable request.
1520 Note that the cache_peer "no-tproxy" option overrides this ACL.
1522 This clause supports fast acl types.
1523 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1528 LOC: Config.accessList.http
1529 DEFAULT_IF_NONE: deny all
1530 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1532 Allowing or Denying access based on defined access lists
1534 To allow or deny a message received on an HTTP, HTTPS, or FTP port:
1535 http_access allow|deny [!]aclname ...
1537 NOTE on default values:
1539 If there are no "access" lines present, the default is to deny
1542 If none of the "access" lines cause a match, the default is the
1543 opposite of the last line in the list. If the last line was
1544 deny, the default is allow. Conversely, if the last line
1545 is allow, the default will be deny. For these reasons, it is a
1546 good idea to have an "deny all" entry at the end of your access
1547 lists to avoid potential confusion.
1549 This clause supports both fast and slow acl types.
1550 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1555 # Recommended minimum Access Permission configuration:
1557 # Deny requests to certain unsafe ports
1558 http_access deny !Safe_ports
1560 # Deny CONNECT to other than secure SSL ports
1561 http_access deny CONNECT !SSL_ports
1563 # Only allow cachemgr access from localhost
1564 http_access allow localhost manager
1565 http_access deny manager
1567 # We strongly recommend the following be uncommented to protect innocent
1568 # web applications running on the proxy server who think the only
1569 # one who can access services on "localhost" is a local user
1570 #http_access deny to_localhost
1573 # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
1576 # Example rule allowing access from your local networks.
1577 # Adapt localnet in the ACL section to list your (internal) IP networks
1578 # from where browsing should be allowed
1579 http_access allow localnet
1580 http_access allow localhost
1582 # And finally deny all other access to this proxy
1583 http_access deny all
1587 NAME: adapted_http_access http_access2
1589 LOC: Config.accessList.adapted_http
1591 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1593 Allowing or Denying access based on defined access lists
1595 Essentially identical to http_access, but runs after redirectors
1596 and ICAP/eCAP adaptation. Allowing access control based on their
1599 If not set then only http_access is used.
1602 NAME: http_reply_access
1604 LOC: Config.accessList.reply
1606 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1608 Allow replies to client requests. This is complementary to http_access.
1610 http_reply_access allow|deny [!] aclname ...
1612 NOTE: if there are no access lines present, the default is to allow
1615 If none of the access lines cause a match the opposite of the
1616 last line will apply. Thus it is good practice to end the rules
1617 with an "allow all" or "deny all" entry.
1619 This clause supports both fast and slow acl types.
1620 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1625 LOC: Config.accessList.icp
1627 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1629 Allowing or Denying access to the ICP port based on defined
1632 icp_access allow|deny [!]aclname ...
1634 NOTE: The default if no icp_access lines are present is to
1635 deny all traffic. This default may cause problems with peers
1638 This clause only supports fast acl types.
1639 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1641 # Allow ICP queries from local networks only
1642 #icp_access allow localnet
1643 #icp_access deny all
1649 LOC: Config.accessList.htcp
1651 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1653 Allowing or Denying access to the HTCP port based on defined
1656 htcp_access allow|deny [!]aclname ...
1658 See also htcp_clr_access for details on access control for
1659 cache purge (CLR) HTCP messages.
1661 NOTE: The default if no htcp_access lines are present is to
1662 deny all traffic. This default may cause problems with peers
1663 using the htcp option.
1665 This clause only supports fast acl types.
1666 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1668 # Allow HTCP queries from local networks only
1669 #htcp_access allow localnet
1670 #htcp_access deny all
1673 NAME: htcp_clr_access
1676 LOC: Config.accessList.htcp_clr
1678 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
1680 Allowing or Denying access to purge content using HTCP based
1681 on defined access lists.
1682 See htcp_access for details on general HTCP access control.
1684 htcp_clr_access allow|deny [!]aclname ...
1686 This clause only supports fast acl types.
1687 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1689 # Allow HTCP CLR requests from trusted peers
1690 acl htcp_clr_peer src 192.0.2.2 2001:DB8::2
1691 htcp_clr_access allow htcp_clr_peer
1692 htcp_clr_access deny all
1697 LOC: Config.accessList.miss
1699 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
1701 Determines whether network access is permitted when satisfying a request.
1704 to force your neighbors to use you as a sibling instead of
1707 acl localclients src 192.0.2.0/24 2001:DB8::a:0/64
1708 miss_access deny !localclients
1709 miss_access allow all
1711 This means only your local clients are allowed to fetch relayed/MISS
1712 replies from the network and all other clients can only fetch cached
1715 The default for this setting allows all clients who passed the
1716 http_access rules to relay via this proxy.
1718 This clause only supports fast acl types.
1719 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1722 NAME: ident_lookup_access
1726 DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched.
1727 LOC: Ident::TheConfig.identLookup
1729 A list of ACL elements which, if matched, cause an ident
1730 (RFC 931) lookup to be performed for this request. For
1731 example, you might choose to always perform ident lookups
1732 for your main multi-user Unix boxes, but not for your Macs
1733 and PCs. By default, ident lookups are not performed for
1736 To enable ident lookups for specific client addresses, you
1737 can follow this example:
1739 acl ident_aware_hosts src 198.168.1.0/24
1740 ident_lookup_access allow ident_aware_hosts
1741 ident_lookup_access deny all
1743 Only src type ACL checks are fully supported. A srcdomain
1744 ACL might work at times, but it will not always provide
1747 This clause only supports fast acl types.
1748 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
1751 NAME: reply_body_max_size
1752 COMMENT: size [acl acl...]
1755 DEFAULT_DOC: No limit is applied.
1756 LOC: Config.ReplyBodySize
1758 This option specifies the maximum size of a reply body. It can be
1759 used to prevent users from downloading very large files, such as
1760 MP3's and movies. When the reply headers are received, the
1761 reply_body_max_size lines are processed, and the first line where
1762 all (if any) listed ACLs are true is used as the maximum body size
1765 This size is checked twice. First when we get the reply headers,
1766 we check the content-length value. If the content length value exists
1767 and is larger than the allowed size, the request is denied and the
1768 user receives an error message that says "the request or reply
1769 is too large." If there is no content-length, and the reply
1770 size exceeds this limit, the client's connection is just closed
1771 and they will receive a partial reply.
1773 WARNING: downstream caches probably can not detect a partial reply
1774 if there is no content-length header, so they will cache
1775 partial responses and give them out as hits. You should NOT
1776 use this option if you have downstream caches.
1778 WARNING: A maximum size smaller than the size of squid's error messages
1779 will cause an infinite loop and crash squid. Ensure that the smallest
1780 non-zero value you use is greater that the maximum header size plus
1781 the size of your largest error page.
1783 If you set this parameter none (the default), there will be
1786 Configuration Format is:
1787 reply_body_max_size SIZE UNITS [acl ...]
1789 reply_body_max_size 10 MB
1793 NAME: on_unsupported_protocol
1794 TYPE: on_unsupported_protocol
1795 LOC: Config.accessList.on_unsupported_protocol
1797 DEFAULT_DOC: Respond with an error message to unidentifiable traffic
1799 Determines Squid behavior when encountering strange requests at the
1800 beginning of an accepted TCP connection or the beginning of a bumped
1801 CONNECT tunnel. Controlling Squid reaction to unexpected traffic is
1802 especially useful in interception environments where Squid is likely
1803 to see connections for unsupported protocols that Squid should either
1804 terminate or tunnel at TCP level.
1806 on_unsupported_protocol <action> [!]acl ...
1808 The first matching action wins. Only fast ACLs are supported.
1810 Supported actions are:
1812 tunnel: Establish a TCP connection with the intended server and
1813 blindly shovel TCP packets between the client and server.
1815 respond: Respond with an error message, using the transfer protocol
1816 for the Squid port that received the request (e.g., HTTP
1817 for connections intercepted at the http_port). This is the
1820 Squid expects the following traffic patterns:
1822 http_port: a plain HTTP request
1823 https_port: SSL/TLS handshake followed by an [encrypted] HTTP request
1824 ftp_port: a plain FTP command (no on_unsupported_protocol support yet!)
1825 CONNECT tunnel on http_port: same as https_port
1826 CONNECT tunnel on https_port: same as https_port
1828 Currently, this directive has effect on intercepted connections and
1829 bumped tunnels only. Other cases are not supported because Squid
1830 cannot know the intended destination of other traffic.
1833 # define what Squid errors indicate receiving non-HTTP traffic:
1834 acl foreignProtocol squid_error ERR_PROTOCOL_UNKNOWN ERR_TOO_BIG
1835 # define what Squid errors indicate receiving nothing:
1836 acl serverTalksFirstProtocol squid_error ERR_REQUEST_START_TIMEOUT
1837 # tunnel everything that does not look like HTTP:
1838 on_unsupported_protocol tunnel foreignProtocol
1839 # tunnel if we think the client waits for the server to talk first:
1840 on_unsupported_protocol tunnel serverTalksFirstProtocol
1841 # in all other error cases, just send an HTTP "error page" response:
1842 on_unsupported_protocol respond all
1844 See also: squid_error ACL
1849 -----------------------------------------------------------------------------
1852 NAME: http_port ascii_port
1857 Usage: port [mode] [options]
1858 hostname:port [mode] [options]
1859 1.2.3.4:port [mode] [options]
1861 The socket addresses where Squid will listen for HTTP client
1862 requests. You may specify multiple socket addresses.
1863 There are three forms: port alone, hostname with port, and
1864 IP address with port. If you specify a hostname or IP
1865 address, Squid binds the socket to that specific
1866 address. Most likely, you do not need to bind to a specific
1867 address, so you can use the port number alone.
1869 If you are running Squid in accelerator mode, you
1870 probably want to listen on port 80 also, or instead.
1872 The -a command line option may be used to specify additional
1873 port(s) where Squid listens for proxy request. Such ports will
1874 be plain proxy ports with no options.
1876 You may specify multiple socket addresses on multiple lines.
1880 intercept Support for IP-Layer NAT interception delivering
1881 traffic to this Squid port.
1882 NP: disables authentication on the port.
1884 tproxy Support Linux TPROXY (or BSD divert-to) with spoofing
1885 of outgoing connections using the client IP address.
1886 NP: disables authentication on the port.
1888 accel Accelerator / reverse proxy mode
1890 ssl-bump For each CONNECT request allowed by ssl_bump ACLs,
1891 establish secure connection with the client and with
1892 the server, decrypt HTTPS messages as they pass through
1893 Squid, and treat them as unencrypted HTTP messages,
1894 becoming the man-in-the-middle.
1896 The ssl_bump option is required to fully enable
1897 bumping of CONNECT requests.
1899 Omitting the mode flag causes default forward proxy mode to be used.
1902 Accelerator Mode Options:
1904 defaultsite=domainname
1905 What to use for the Host: header if it is not present
1906 in a request. Determines what site (not origin server)
1907 accelerators should consider the default.
1909 no-vhost Disable using HTTP/1.1 Host header for virtual domain support.
1911 protocol= Protocol to reconstruct accelerated and intercepted
1912 requests with. Defaults to HTTP/1.1 for http_port and
1913 HTTPS/1.1 for https_port.
1914 When an unsupported value is configured Squid will
1915 produce a FATAL error.
1916 Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1
1918 vport Virtual host port support. Using the http_port number
1919 instead of the port passed on Host: headers.
1921 vport=NN Virtual host port support. Using the specified port
1922 number instead of the port passed on Host: headers.
1925 Act as if this Squid is the origin server.
1926 This currently means generate new Date: and Expires:
1927 headers on HIT instead of adding Age:.
1929 ignore-cc Ignore request Cache-Control headers.
1931 WARNING: This option violates HTTP specifications if
1932 used in non-accelerator setups.
1934 allow-direct Allow direct forwarding in accelerator mode. Normally
1935 accelerated requests are denied direct forwarding as if
1936 never_direct was used.
1938 WARNING: this option opens accelerator mode to security
1939 vulnerabilities usually only affecting in interception
1940 mode. Make sure to protect forwarding with suitable
1941 http_access rules when using this.
1944 SSL Bump Mode Options:
1945 In addition to these options ssl-bump requires TLS/SSL options.
1947 generate-host-certificates[=<on|off>]
1948 Dynamically create SSL server certificates for the
1949 destination hosts of bumped CONNECT requests.When
1950 enabled, the cert and key options are used to sign
1951 generated certificates. Otherwise generated
1952 certificate will be selfsigned.
1953 If there is a CA certificate lifetime of the generated
1954 certificate equals lifetime of the CA certificate. If
1955 generated certificate is selfsigned lifetime is three
1957 This option is enabled by default when ssl-bump is used.
1958 See the ssl-bump option above for more information.
1960 dynamic_cert_mem_cache_size=SIZE
1961 Approximate total RAM size spent on cached generated
1962 certificates. If set to zero, caching is disabled. The
1963 default value is 4MB.
1967 cert= Path to SSL certificate (PEM format).
1969 key= Path to SSL private key file (PEM format)
1970 if not specified, the certificate file is
1971 assumed to be a combined certificate and
1974 cipher= Colon separated list of supported ciphers.
1975 NOTE: some ciphers such as EDH ciphers depend on
1976 additional settings. If those settings are
1977 omitted the ciphers may be silently ignored
1978 by the OpenSSL library.
1980 options= Various SSL implementation options. The most important
1983 NO_SSLv3 Disallow the use of SSLv3
1985 NO_TLSv1 Disallow the use of TLSv1.0
1987 NO_TLSv1_1 Disallow the use of TLSv1.1
1989 NO_TLSv1_2 Disallow the use of TLSv1.2
1992 Always create a new key when using
1993 temporary/ephemeral DH key exchanges
1996 Enable ephemeral ECDH key exchange.
1997 The adopted curve should be specified
1998 using the tls-dh option.
2001 Disable use of RFC5077 session tickets.
2002 Some servers may have problems
2003 understanding the TLS extension due
2004 to ambiguous specification in RFC4507.
2006 ALL Enable various bug workarounds
2007 suggested as "harmless" by OpenSSL
2008 Be warned that this reduces SSL/TLS
2009 strength to some attacks.
2011 See the OpenSSL SSL_CTX_set_options documentation for a
2014 clientca= File containing the list of CAs to use when
2015 requesting a client certificate.
2017 tls-cafile= PEM file containing CA certificates to use when verifying
2018 client certificates. If not configured clientca will be
2019 used. May be repeated to load multiple files.
2021 capath= Directory containing additional CA certificates
2022 and CRL lists to use when verifying client certificates.
2023 Requires OpenSSL or LibreSSL.
2025 crlfile= File of additional CRL lists to use when verifying
2026 the client certificate, in addition to CRLs stored in
2027 the capath. Implies VERIFY_CRL flag below.
2030 File containing DH parameters for temporary/ephemeral DH key
2031 exchanges, optionally prefixed by a curve for ephemeral ECDH
2033 See OpenSSL documentation for details on how to create the
2034 DH parameter file. Supported curves for ECDH can be listed
2035 using the "openssl ecparam -list_curves" command.
2036 WARNING: EDH and EECDH ciphers will be silently disabled if
2037 this option is not set.
2039 sslflags= Various flags modifying the use of SSL:
2041 Don't request client certificates
2042 immediately, but wait until acl processing
2043 requires a certificate (not yet implemented).
2045 Don't allow for session reuse. Each connection
2046 will result in a new SSL session.
2048 Verify CRL lists when accepting client
2051 Verify CRL lists for all certificates in the
2052 client certificate chain.
2054 tls-default-ca[=off]
2055 Whether to use the system Trusted CAs. Default is OFF.
2057 tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1.
2059 sslcontext= SSL session ID context identifier.
2063 connection-auth[=on|off]
2064 use connection-auth=off to tell Squid to prevent
2065 forwarding Microsoft connection oriented authentication
2066 (NTLM, Negotiate and Kerberos)
2068 disable-pmtu-discovery=
2069 Control Path-MTU discovery usage:
2070 off lets OS decide on what to do (default).
2071 transparent disable PMTU discovery when transparent
2073 always disable always PMTU discovery.
2075 In many setups of transparently intercepting proxies
2076 Path-MTU discovery can not work on traffic towards the
2077 clients. This is the case when the intercepting device
2078 does not fully track connections and fails to forward
2079 ICMP must fragment messages to the cache server. If you
2080 have such setup and experience that certain clients
2081 sporadically hang or never complete requests set
2082 disable-pmtu-discovery option to 'transparent'.
2084 name= Specifies a internal name for the port. Defaults to
2085 the port specification (port or addr:port)
2087 tcpkeepalive[=idle,interval,timeout]
2088 Enable TCP keepalive probes of idle connections.
2089 In seconds; idle is the initial time before TCP starts
2090 probing the connection, interval how often to probe, and
2091 timeout the time before giving up.
2093 require-proxy-header
2094 Require PROXY protocol version 1 or 2 connections.
2095 The proxy_protocol_access is required to whitelist
2096 downstream proxies which can be trusted.
2098 If you run Squid on a dual-homed machine with an internal
2099 and an external interface we recommend you to specify the
2100 internal address:port in http_port. This way Squid will only be
2101 visible on the internal address.
2105 # Squid normally listens to port 3128
2106 http_port @DEFAULT_HTTP_PORT@
2111 IFDEF: USE_GNUTLS||USE_OPENSSL
2116 Usage: [ip:]port [mode] cert=certificate.pem [options]
2118 The socket address where Squid will listen for client requests made
2119 over TLS or SSL connections. Commonly referred to as HTTPS.
2121 This is most useful for situations where you are running squid in
2122 accelerator mode and you want to do the TLS work at the accelerator level.
2124 You may specify multiple socket addresses on multiple lines,
2125 each with their own certificate and/or options.
2127 The TLS cert= option is mandatory on HTTPS ports.
2129 See http_port for a list of modes and options.
2137 Enables Native FTP proxy by specifying the socket address where Squid
2138 listens for FTP client requests. See http_port directive for various
2139 ways to specify the listening address and mode.
2141 Usage: ftp_port address [mode] [options]
2143 WARNING: This is a new, experimental, complex feature that has seen
2144 limited production exposure. Some Squid modules (e.g., caching) do not
2145 currently work with native FTP proxying, and many features have not
2146 even been tested for compatibility. Test well before deploying!
2148 Native FTP proxying differs substantially from proxying HTTP requests
2149 with ftp:// URIs because Squid works as an FTP server and receives
2150 actual FTP commands (rather than HTTP requests with FTP URLs).
2152 Native FTP commands accepted at ftp_port are internally converted or
2153 wrapped into HTTP-like messages. The same happens to Native FTP
2154 responses received from FTP origin servers. Those HTTP-like messages
2155 are shoveled through regular access control and adaptation layers
2156 between the FTP client and the FTP origin server. This allows Squid to
2157 examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP
2158 mechanisms when shoveling wrapped FTP messages. For example,
2159 http_access and adaptation_access directives are used.
2163 intercept Same as http_port intercept. The FTP origin address is
2164 determined based on the intended destination of the
2165 intercepted connection.
2167 tproxy Support Linux TPROXY for spoofing outgoing
2168 connections using the client IP address.
2169 NP: disables authentication and maybe IPv6 on the port.
2171 By default (i.e., without an explicit mode option), Squid extracts the
2172 FTP origin address from the login@origin parameter of the FTP USER
2173 command. Many popular FTP clients support such native FTP proxying.
2177 name=token Specifies an internal name for the port. Defaults to
2178 the port address. Usable with myportname ACL.
2181 Enables tracking of FTP directories by injecting extra
2182 PWD commands and adjusting Request-URI (in wrapping
2183 HTTP requests) to reflect the current FTP server
2184 directory. Tracking is disabled by default.
2186 protocol=FTP Protocol to reconstruct accelerated and intercepted
2187 requests with. Defaults to FTP. No other accepted
2188 values have been tested with. An unsupported value
2189 results in a FATAL error. Accepted values are FTP,
2190 HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1).
2192 Other http_port modes and options that are not specific to HTTP and
2193 HTTPS may also work.
2196 NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
2199 LOC: Ip::Qos::TheConfig.tosToServer
2201 Allows you to select a TOS/Diffserv value for packets outgoing
2202 on the server side, based on an ACL.
2204 tcp_outgoing_tos ds-field [!]aclname ...
2206 Example where normal_service_net uses the TOS value 0x00
2207 and good_service_net uses 0x20
2209 acl normal_service_net src 10.0.0.0/24
2210 acl good_service_net src 10.0.1.0/24
2211 tcp_outgoing_tos 0x00 normal_service_net
2212 tcp_outgoing_tos 0x20 good_service_net
2214 TOS/DSCP values really only have local significance - so you should
2215 know what you're specifying. For more information, see RFC2474,
2216 RFC2475, and RFC3260.
2218 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
2219 "default" to use whatever default your host has.
2220 Note that only multiples of 4 are usable as the two rightmost bits have
2221 been redefined for use by ECN (RFC 3168 section 23.1).
2222 The squid parser will enforce this by masking away the ECN bits.
2224 Processing proceeds in the order specified, and stops at first fully
2227 Only fast ACLs are supported.
2230 NAME: clientside_tos
2233 LOC: Ip::Qos::TheConfig.tosToClient
2235 Allows you to select a TOS/DSCP value for packets being transmitted
2236 on the client-side, based on an ACL.
2238 clientside_tos ds-field [!]aclname ...
2240 Example where normal_service_net uses the TOS value 0x00
2241 and good_service_net uses 0x20
2243 acl normal_service_net src 10.0.0.0/24
2244 acl good_service_net src 10.0.1.0/24
2245 clientside_tos 0x00 normal_service_net
2246 clientside_tos 0x20 good_service_net
2248 Note: This feature is incompatible with qos_flows. Any TOS values set here
2249 will be overwritten by TOS values in qos_flows.
2251 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
2252 "default" to use whatever default your host has.
2253 Note that only multiples of 4 are usable as the two rightmost bits have
2254 been redefined for use by ECN (RFC 3168 section 23.1).
2255 The squid parser will enforce this by masking away the ECN bits.
2259 NAME: tcp_outgoing_mark
2261 IFDEF: SO_MARK&&USE_LIBCAP
2263 LOC: Ip::Qos::TheConfig.nfmarkToServer
2265 Allows you to apply a Netfilter mark value to outgoing packets
2266 on the server side, based on an ACL.
2268 tcp_outgoing_mark mark-value [!]aclname ...
2270 Example where normal_service_net uses the mark value 0x00
2271 and good_service_net uses 0x20
2273 acl normal_service_net src 10.0.0.0/24
2274 acl good_service_net src 10.0.1.0/24
2275 tcp_outgoing_mark 0x00 normal_service_net
2276 tcp_outgoing_mark 0x20 good_service_net
2278 Only fast ACLs are supported.
2281 NAME: clientside_mark
2283 IFDEF: SO_MARK&&USE_LIBCAP
2285 LOC: Ip::Qos::TheConfig.nfmarkToClient
2287 Allows you to apply a Netfilter mark value to packets being transmitted
2288 on the client-side, based on an ACL.
2290 clientside_mark mark-value [!]aclname ...
2292 Example where normal_service_net uses the mark value 0x00
2293 and good_service_net uses 0x20
2295 acl normal_service_net src 10.0.0.0/24
2296 acl good_service_net src 10.0.1.0/24
2297 clientside_mark 0x00 normal_service_net
2298 clientside_mark 0x20 good_service_net
2300 Note: This feature is incompatible with qos_flows. Any mark values set here
2301 will be overwritten by mark values in qos_flows.
2308 LOC: Ip::Qos::TheConfig
2310 Allows you to select a TOS/DSCP value to mark outgoing
2311 connections to the client, based on where the reply was sourced.
2312 For platforms using netfilter, allows you to set a netfilter mark
2313 value instead of, or in addition to, a TOS value.
2315 By default this functionality is disabled. To enable it with the default
2316 settings simply use "qos_flows mark" or "qos_flows tos". Default
2317 settings will result in the netfilter mark or TOS value being copied
2318 from the upstream connection to the client. Note that it is the connection
2319 CONNMARK value not the packet MARK value that is copied.
2321 It is not currently possible to copy the mark or TOS value from the
2322 client to the upstream connection request.
2324 TOS values really only have local significance - so you should
2325 know what you're specifying. For more information, see RFC2474,
2326 RFC2475, and RFC3260.
2328 The TOS/DSCP byte must be exactly that - a octet value 0 - 255.
2329 Note that only multiples of 4 are usable as the two rightmost bits have
2330 been redefined for use by ECN (RFC 3168 section 23.1).
2331 The squid parser will enforce this by masking away the ECN bits.
2333 Mark values can be any unsigned 32-bit integer value.
2335 This setting is configured by setting the following values:
2337 tos|mark Whether to set TOS or netfilter mark values
2339 local-hit=0xFF Value to mark local cache hits.
2341 sibling-hit=0xFF Value to mark hits from sibling peers.
2343 parent-hit=0xFF Value to mark hits from parent peers.
2345 miss=0xFF[/mask] Value to mark cache misses. Takes precedence
2346 over the preserve-miss feature (see below), unless
2347 mask is specified, in which case only the bits
2348 specified in the mask are written.
2350 The TOS variant of the following features are only possible on Linux
2351 and require your kernel to be patched with the TOS preserving ZPH
2352 patch, available from http://zph.bratcheda.org
2353 No patch is needed to preserve the netfilter mark, which will work
2354 with all variants of netfilter.
2356 disable-preserve-miss
2357 This option disables the preservation of the TOS or netfilter
2358 mark. By default, the existing TOS or netfilter mark value of
2359 the response coming from the remote server will be retained
2360 and masked with miss-mark.
2361 NOTE: in the case of a netfilter mark, the mark must be set on
2362 the connection (using the CONNMARK target) not on the packet
2366 Allows you to mask certain bits in the TOS or mark value
2367 received from the remote server, before copying the value to
2368 the TOS sent towards clients.
2369 Default for tos: 0xFF (TOS from server is not changed).
2370 Default for mark: 0xFFFFFFFF (mark from server is not changed).
2372 All of these features require the --enable-zph-qos compilation flag
2373 (enabled by default). Netfilter marking also requires the
2374 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and
2375 libcap 2.09+ (--with-libcap).
2379 NAME: tcp_outgoing_address
2382 DEFAULT_DOC: Address selection is performed by the operating system.
2383 LOC: Config.accessList.outgoing_address
2385 Allows you to map requests to different outgoing IP addresses
2386 based on the username or source address of the user making
2389 tcp_outgoing_address ipaddr [[!]aclname] ...
2392 Forwarding clients with dedicated IPs for certain subnets.
2394 acl normal_service_net src 10.0.0.0/24
2395 acl good_service_net src 10.0.2.0/24
2397 tcp_outgoing_address 2001:db8::c001 good_service_net
2398 tcp_outgoing_address 10.1.0.2 good_service_net
2400 tcp_outgoing_address 2001:db8::beef normal_service_net
2401 tcp_outgoing_address 10.1.0.1 normal_service_net
2403 tcp_outgoing_address 2001:db8::1
2404 tcp_outgoing_address 10.1.0.3
2406 Processing proceeds in the order specified, and stops at first fully
2409 Squid will add an implicit IP version test to each line.
2410 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.
2411 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.
2414 NOTE: The use of this directive using client dependent ACLs is
2415 incompatible with the use of server side persistent connections. To
2416 ensure correct results it is best to set server_persistent_connections
2417 to off when using this directive in such configurations.
2419 NOTE: The use of this directive to set a local IP on outgoing TCP links
2420 is incompatible with using TPROXY to set client IP out outbound TCP links.
2421 When needing to contact peers use the no-tproxy cache_peer option and the
2422 client_dst_passthru directive re-enable normal forwarding such as this.
2426 NAME: host_verify_strict
2429 LOC: Config.onoff.hostStrictVerify
2431 Regardless of this option setting, when dealing with intercepted
2432 traffic, Squid always verifies that the destination IP address matches
2433 the Host header domain or IP (called 'authority form URL').
2435 This enforcement is performed to satisfy a MUST-level requirement in
2436 RFC 2616 section 14.23: "The Host field value MUST represent the naming
2437 authority of the origin server or gateway given by the original URL".
2440 Squid always responds with an HTTP 409 (Conflict) error
2441 page and logs a security warning if there is no match.
2443 Squid verifies that the destination IP address matches
2444 the Host header for forward-proxy and reverse-proxy traffic
2445 as well. For those traffic types, Squid also enables the
2446 following checks, comparing the corresponding Host header
2447 and Request-URI components:
2449 * The host names (domain or IP) must be identical,
2450 but valueless or missing Host header disables all checks.
2451 For the two host names to match, both must be either IP
2454 * Port numbers must be identical, but if a port is missing
2455 the scheme-default port is assumed.
2458 When set to OFF (the default):
2459 Squid allows suspicious requests to continue but logs a
2460 security warning and blocks caching of the response.
2462 * Forward-proxy traffic is not checked at all.
2464 * Reverse-proxy traffic is not checked at all.
2466 * Intercepted traffic which passes verification is handled
2467 according to client_dst_passthru.
2469 * Intercepted requests which fail verification are sent
2470 to the client original destination instead of DIRECT.
2471 This overrides 'client_dst_passthru off'.
2473 For now suspicious intercepted CONNECT requests are always
2474 responded to with an HTTP 409 (Conflict) error page.
2479 As described in CVE-2009-0801 when the Host: header alone is used
2480 to determine the destination of a request it becomes trivial for
2481 malicious scripts on remote websites to bypass browser same-origin
2482 security policy and sandboxing protections.
2484 The cause of this is that such applets are allowed to perform their
2485 own HTTP stack, in which case the same-origin policy of the browser
2486 sandbox only verifies that the applet tries to contact the same IP
2487 as from where it was loaded at the IP level. The Host: header may
2488 be different from the connected IP and approved origin.
2492 NAME: client_dst_passthru
2495 LOC: Config.onoff.client_dst_passthru
2497 With NAT or TPROXY intercepted traffic Squid may pass the request
2498 directly to the original client destination IP or seek a faster
2499 source using the HTTP Host header.
2501 Using Host to locate alternative servers can provide faster
2502 connectivity with a range of failure recovery options.
2503 But can also lead to connectivity trouble when the client and
2504 server are attempting stateful interactions unaware of the proxy.
2506 This option (on by default) prevents alternative DNS entries being
2507 located to send intercepted traffic DIRECT to an origin server.
2508 The clients original destination IP and port will be used instead.
2510 Regardless of this option setting, when dealing with intercepted
2511 traffic Squid will verify the Host: header and any traffic which
2512 fails Host verification will be treated as if this option were ON.
2514 see host_verify_strict for details on the verification process.
2519 -----------------------------------------------------------------------------
2522 NAME: tls_outgoing_options
2523 IFDEF: USE_GNUTLS||USE_OPENSSL
2524 TYPE: securePeerOptions
2525 DEFAULT: min-version=1.0
2526 LOC: Security::ProxyOutgoingConfig
2528 disable Do not support https:// URLs.
2530 cert=/path/to/client/certificate
2531 A client TLS certificate to use when connecting.
2533 key=/path/to/client/private_key
2534 The private TLS key corresponding to the cert= above.
2535 If key= is not specified cert= is assumed to reference
2536 a PEM file containing both the certificate and the key.
2538 cipher=... The list of valid TLS ciphers to use.
2541 The minimum TLS protocol version to permit.
2542 To control SSLv3 use the options= parameter.
2543 Supported Values: 1.0 (default), 1.1, 1.2
2545 options=... Specify various TLS/SSL implementation options:
2547 NO_SSLv3 Disallow the use of SSLv3
2549 NO_TLSv1 Disallow the use of TLSv1.0
2551 NO_TLSv1_1 Disallow the use of TLSv1.1
2553 NO_TLSv1_2 Disallow the use of TLSv1.2
2556 Always create a new key when using
2557 temporary/ephemeral DH key exchanges
2560 Disable use of RFC5077 session tickets.
2561 Some servers may have problems
2562 understanding the TLS extension due
2563 to ambiguous specification in RFC4507.
2565 ALL Enable various bug workarounds
2566 suggested as "harmless" by OpenSSL
2567 Be warned that this reduces SSL/TLS
2568 strength to some attacks.
2570 See the OpenSSL SSL_CTX_set_options documentation for a
2573 cafile= PEM file containing CA certificates to use when verifying
2574 the peer certificate. May be repeated to load multiple files.
2576 capath= A directory containing additional CA certificates to
2577 use when verifying the peer certificate.
2578 Requires OpenSSL or LibreSSL.
2580 crlfile=... A certificate revocation list file to use when
2581 verifying the peer certificate.
2583 flags=... Specify various flags modifying the TLS implementation:
2586 Accept certificates even if they fail to
2589 Don't verify the peer certificate
2590 matches the server name
2593 Whether to use the system Trusted CAs. Default is ON.
2595 domain= The peer name as advertised in its certificate.
2596 Used for verifying the correctness of the received peer
2597 certificate. If not specified the peer hostname will be
2603 -----------------------------------------------------------------------------
2606 NAME: ssl_unclean_shutdown
2610 LOC: Config.SSL.unclean_shutdown
2612 Some browsers (especially MSIE) bugs out on SSL shutdown
2619 LOC: Config.SSL.ssl_engine
2622 The OpenSSL engine to use. You will need to set this if you
2623 would like to use hardware SSL acceleration for example.
2626 NAME: sslproxy_session_ttl
2629 LOC: Config.SSL.session_ttl
2632 Sets the timeout value for SSL sessions
2635 NAME: sslproxy_session_cache_size
2638 LOC: Config.SSL.sessionCacheSize
2641 Sets the cache size to use for ssl session
2644 NAME: sslproxy_foreign_intermediate_certs
2647 LOC: Config.ssl_client.foreignIntermediateCertsPath
2650 Many origin servers fail to send their full server certificate
2651 chain for verification, assuming the client already has or can
2652 easily locate any missing intermediate certificates.
2654 Squid uses the certificates from the specified file to fill in
2655 these missing chains when trying to validate origin server
2658 The file is expected to contain zero or more PEM-encoded
2659 intermediate certificates. These certificates are not treated
2660 as trusted root certificates, and any self-signed certificate in
2661 this file will be ignored.
2664 NAME: sslproxy_cert_sign_hash
2667 LOC: Config.SSL.certSignHash
2670 Sets the hashing algorithm to use when signing generated certificates.
2671 Valid algorithm names depend on the OpenSSL library used. The following
2672 names are usually available: sha1, sha256, sha512, and md5. Please see
2673 your OpenSSL library manual for the available hashes. By default, Squids
2674 that support this option use sha256 hashes.
2676 Squid does not forcefully purge cached certificates that were generated
2677 with an algorithm other than the currently configured one. They remain
2678 in the cache, subject to the regular cache eviction policy, and become
2679 useful if the algorithm changes again.
2684 TYPE: sslproxy_ssl_bump
2685 LOC: Config.accessList.ssl_bump
2686 DEFAULT_DOC: Become a TCP tunnel without decrypting proxied traffic.
2689 This option is consulted when a CONNECT request is received on
2690 an http_port (or a new connection is intercepted at an
2691 https_port), provided that port was configured with an ssl-bump
2692 flag. The subsequent data on the connection is either treated as
2693 HTTPS and decrypted OR tunneled at TCP level without decryption,
2694 depending on the first matching bumping "action".
2696 ssl_bump <action> [!]acl ...
2698 The following bumping actions are currently supported:
2701 Become a TCP tunnel without decrypting proxied traffic.
2702 This is the default action.
2705 Establish a secure connection with the server and, using a
2706 mimicked server certificate, with the client.
2709 Receive client (step SslBump1) or server (step SslBump2)
2710 certificate while preserving the possibility of splicing the
2711 connection. Peeking at the server certificate (during step 2)
2712 usually precludes bumping of the connection at step 3.
2715 Receive client (step SslBump1) or server (step SslBump2)
2716 certificate while preserving the possibility of bumping the
2717 connection. Staring at the server certificate (during step 2)
2718 usually precludes splicing of the connection at step 3.
2721 Close client and server connections.
2723 Backward compatibility actions available at step SslBump1:
2726 Bump the connection. Establish a secure connection with the
2727 client first, then connect to the server. This old mode does
2728 not allow Squid to mimic server SSL certificate and does not
2729 work with intercepted SSL connections.
2732 Bump the connection. Establish a secure connection with the
2733 server first, then establish a secure connection with the
2734 client, using a mimicked server certificate. Works with both
2735 CONNECT requests and intercepted SSL connections, but does
2736 not allow to make decisions based on SSL handshake info.
2739 Decide whether to bump or splice the connection based on
2740 client-to-squid and server-to-squid SSL hello messages.
2744 Same as the "splice" action.
2746 All ssl_bump rules are evaluated at each of the supported bumping
2747 steps. Rules with actions that are impossible at the current step are
2748 ignored. The first matching ssl_bump action wins and is applied at the
2749 end of the current step. If no rules match, the splice action is used.
2750 See the at_step ACL for a list of the supported SslBump steps.
2752 This clause supports both fast and slow acl types.
2753 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2755 See also: http_port ssl-bump, https_port ssl-bump, and acl at_step.
2758 # Example: Bump all TLS connections except those originating from
2759 # localhost or those going to example.com.
2761 acl broken_sites ssl::server_name .example.com
2762 ssl_bump splice localhost
2763 ssl_bump splice broken_sites
2767 NAME: sslproxy_cert_error
2770 DEFAULT_DOC: Server certificate errors terminate the transaction.
2771 LOC: Config.ssl_client.cert_error
2774 Use this ACL to bypass server certificate validation errors.
2776 For example, the following lines will bypass all validation errors
2777 when talking to servers for example.com. All other
2778 validation errors will result in ERR_SECURE_CONNECT_FAIL error.
2780 acl BrokenButTrustedServers dstdomain example.com
2781 sslproxy_cert_error allow BrokenButTrustedServers
2782 sslproxy_cert_error deny all
2784 This clause only supports fast acl types.
2785 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
2786 Using slow acl types may result in server crashes
2788 Without this option, all server certificate validation errors
2789 terminate the transaction to protect Squid and the client.
2791 SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed
2792 but should not happen unless your OpenSSL library is buggy.
2795 Bypassing validation errors is dangerous because an
2796 error usually implies that the server cannot be trusted
2797 and the connection may be insecure.
2799 See also: sslproxy_flags and DONT_VERIFY_PEER.
2802 NAME: sslproxy_cert_sign
2805 POSTSCRIPTUM: signUntrusted ssl::certUntrusted
2806 POSTSCRIPTUM: signSelf ssl::certSelfSigned
2807 POSTSCRIPTUM: signTrusted all
2808 TYPE: sslproxy_cert_sign
2809 LOC: Config.ssl_client.cert_sign
2812 sslproxy_cert_sign <signing algorithm> acl ...
2814 The following certificate signing algorithms are supported:
2817 Sign using the configured CA certificate which is usually
2818 placed in and trusted by end-user browsers. This is the
2819 default for trusted origin server certificates.
2822 Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error.
2823 This is the default for untrusted origin server certificates
2824 that are not self-signed (see ssl::certUntrusted).
2827 Sign using a self-signed certificate with the right CN to
2828 generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the
2829 browser. This is the default for self-signed origin server
2830 certificates (see ssl::certSelfSigned).
2832 This clause only supports fast acl types.
2834 When sslproxy_cert_sign acl(s) match, Squid uses the corresponding
2835 signing algorithm to generate the certificate and ignores all
2836 subsequent sslproxy_cert_sign options (the first match wins). If no
2837 acl(s) match, the default signing algorithm is determined by errors
2838 detected when obtaining and validating the origin server certificate.
2840 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2841 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2842 CONNECT request that carries a domain name. In all other cases (CONNECT
2843 to an IP address or an intercepted SSL connection), Squid cannot detect
2844 the domain mismatch at certificate generation time when
2845 bump-server-first is used.
2848 NAME: sslproxy_cert_adapt
2851 TYPE: sslproxy_cert_adapt
2852 LOC: Config.ssl_client.cert_adapt
2855 sslproxy_cert_adapt <adaptation algorithm> acl ...
2857 The following certificate adaptation algorithms are supported:
2860 Sets the "Not After" property to the "Not After" property of
2861 the CA certificate used to sign generated certificates.
2864 Sets the "Not Before" property to the "Not Before" property of
2865 the CA certificate used to sign generated certificates.
2867 setCommonName or setCommonName{CN}
2868 Sets Subject.CN property to the host name specified as a
2869 CN parameter or, if no explicit CN parameter was specified,
2870 extracted from the CONNECT request. It is a misconfiguration
2871 to use setCommonName without an explicit parameter for
2872 intercepted or tproxied SSL connections.
2874 This clause only supports fast acl types.
2876 Squid first groups sslproxy_cert_adapt options by adaptation algorithm.
2877 Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the
2878 corresponding adaptation algorithm to generate the certificate and
2879 ignores all subsequent sslproxy_cert_adapt options in that algorithm's
2880 group (i.e., the first match wins within each algorithm group). If no
2881 acl(s) match, the default mimicking action takes place.
2883 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can
2884 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a
2885 CONNECT request that carries a domain name. In all other cases (CONNECT
2886 to an IP address or an intercepted SSL connection), Squid cannot detect
2887 the domain mismatch at certificate generation time when
2888 bump-server-first is used.
2891 NAME: sslpassword_program
2894 LOC: Config.Program.ssl_password
2897 Specify a program used for entering SSL key passphrases
2898 when using encrypted SSL certificate keys. If not specified
2899 keys must either be unencrypted, or Squid started with the -N
2900 option to allow it to query interactively for the passphrase.
2902 The key file name is given as argument to the program allowing
2903 selection of the right password if you have multiple encrypted
2908 OPTIONS RELATING TO EXTERNAL SSL_CRTD
2909 -----------------------------------------------------------------------------
2912 NAME: sslcrtd_program
2915 DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
2916 LOC: Ssl::TheConfig.ssl_crtd
2918 Specify the location and options of the executable for certificate
2920 @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
2921 For more information use:
2922 @DEFAULT_SSL_CRTD@ -h
2925 NAME: sslcrtd_children
2926 TYPE: HelperChildConfig
2928 DEFAULT: 32 startup=5 idle=1
2929 LOC: Ssl::TheConfig.ssl_crtdChildren
2931 The maximum number of processes spawn to service ssl server.
2932 The maximum this may be safely set to is 32.
2934 The startup= and idle= options allow some measure of skew in your
2939 Sets the minimum number of processes to spawn when Squid
2940 starts or reconfigures. When set to zero the first request will
2941 cause spawning of the first child process to handle it.
2943 Starting too few children temporary slows Squid under load while it
2944 tries to spawn enough additional processes to cope with traffic.
2948 Sets a minimum of how many processes Squid is to try and keep available
2949 at all times. When traffic begins to rise above what the existing
2950 processes can handle this many more will be spawned up to the maximum
2951 configured. A minimum setting of 1 is required.
2955 Sets the maximum number of queued requests.
2956 If the queued requests exceed queue size for more than 3 minutes
2957 squid aborts its operation.
2958 The default value is set to 2*numberofchildren.
2960 You must have at least one ssl_crtd process.
2963 NAME: sslcrtvalidator_program
2967 LOC: Ssl::TheConfig.ssl_crt_validator
2969 Specify the location and options of the executable for ssl_crt_validator
2972 Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ...
2975 ttl=n TTL in seconds for cached results. The default is 60 secs
2976 cache=n limit the result cache size. The default value is 2048
2979 NAME: sslcrtvalidator_children
2980 TYPE: HelperChildConfig
2982 DEFAULT: 32 startup=5 idle=1 concurrency=1
2983 LOC: Ssl::TheConfig.ssl_crt_validator_Children
2985 The maximum number of processes spawn to service SSL server.
2986 The maximum this may be safely set to is 32.
2988 The startup= and idle= options allow some measure of skew in your
2993 Sets the minimum number of processes to spawn when Squid
2994 starts or reconfigures. When set to zero the first request will
2995 cause spawning of the first child process to handle it.
2997 Starting too few children temporary slows Squid under load while it
2998 tries to spawn enough additional processes to cope with traffic.
3002 Sets a minimum of how many processes Squid is to try and keep available
3003 at all times. When traffic begins to rise above what the existing
3004 processes can handle this many more will be spawned up to the maximum
3005 configured. A minimum setting of 1 is required.
3009 The number of requests each certificate validator helper can handle in
3010 parallel. A value of 0 indicates the certficate validator does not
3011 support concurrency. Defaults to 1.
3013 When this directive is set to a value >= 1 then the protocol
3014 used to communicate with the helper is modified to include
3015 a request ID in front of the request/response. The request
3016 ID from the request must be echoed back with the response
3021 Sets the maximum number of queued requests.
3022 If the queued requests exceed queue size for more than 3 minutes
3023 squid aborts its operation.
3024 The default value is set to 2*numberofchildren.
3026 You must have at least one ssl_crt_validator process.
3030 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
3031 -----------------------------------------------------------------------------
3039 To specify other caches in a hierarchy, use the format:
3041 cache_peer hostname type http-port icp-port [options]
3046 # hostname type port port options
3047 # -------------------- -------- ----- ----- -----------
3048 cache_peer parent.foo.net parent 3128 3130 default
3049 cache_peer sib1.foo.net sibling 3128 3130 proxy-only
3050 cache_peer sib2.foo.net sibling 3128 3130 proxy-only
3051 cache_peer example.com parent 80 0 default
3052 cache_peer cdn.example.com sibling 3128 0
3054 type: either 'parent', 'sibling', or 'multicast'.
3056 proxy-port: The port number where the peer accept HTTP requests.
3057 For other Squid proxies this is usually 3128
3058 For web servers this is usually 80
3060 icp-port: Used for querying neighbor caches about objects.
3061 Set to 0 if the peer does not support ICP or HTCP.
3062 See ICP and HTCP options below for additional details.
3065 ==== ICP OPTIONS ====
3067 You MUST also set icp_port and icp_access explicitly when using these options.
3068 The defaults will prevent peer traffic using ICP.
3071 no-query Disable ICP queries to this neighbor.
3074 Indicates the named peer is a member of a multicast group.
3075 ICP queries will not be sent directly to the peer, but ICP
3076 replies will be accepted from it.
3078 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
3079 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
3082 To only send ICP queries to this neighbor infrequently.
3083 This is used to keep the neighbor round trip time updated
3084 and is usually used in conjunction with weighted-round-robin.
3087 ==== HTCP OPTIONS ====
3089 You MUST also set htcp_port and htcp_access explicitly when using these options.
3090 The defaults will prevent peer traffic using HTCP.
3093 htcp Send HTCP, instead of ICP, queries to the neighbor.
3094 You probably also want to set the "icp-port" to 4827
3095 instead of 3130. This directive accepts a comma separated
3096 list of options described below.
3098 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
3100 htcp=no-clr Send HTCP to the neighbor but without
3101 sending any CLR requests. This cannot be used with
3104 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
3105 This cannot be used with no-clr.
3108 Send HTCP to the neighbor including CLRs but only when
3109 they do not result from PURGE requests.
3112 Forward any HTCP CLR requests this proxy receives to the peer.
3115 ==== PEER SELECTION METHODS ====
3117 The default peer selection method is ICP, with the first responding peer
3118 being used as source. These options can be used for better load balancing.
3121 default This is a parent cache which can be used as a "last-resort"
3122 if a peer cannot be located by any of the peer-selection methods.
3123 If specified more than once, only the first is used.
3125 round-robin Load-Balance parents which should be used in a round-robin
3126 fashion in the absence of any ICP queries.
3127 weight=N can be used to add bias.
3129 weighted-round-robin
3130 Load-Balance parents which should be used in a round-robin
3131 fashion with the frequency of each parent being based on the
3132 round trip time. Closer parents are used more often.
3133 Usually used for background-ping parents.
3134 weight=N can be used to add bias.
3136 carp Load-Balance parents which should be used as a CARP array.
3137 The requests will be distributed among the parents based on the
3138 CARP load balancing hash function based on their weight.
3140 userhash Load-balance parents based on the client proxy_auth or ident username.
3142 sourcehash Load-balance parents based on the client source IP.
3145 To be used only for cache peers of type "multicast".
3146 ALL members of this multicast group have "sibling"
3147 relationship with it, not "parent". This is to a multicast
3148 group when the requested object would be fetched only from
3149 a "parent" cache, anyway. It's useful, e.g., when
3150 configuring a pool of redundant Squid proxies, being
3151 members of the same multicast group.
3154 ==== PEER SELECTION OPTIONS ====
3156 weight=N use to affect the selection of a peer during any weighted
3157 peer-selection mechanisms.
3158 The weight must be an integer; default is 1,
3159 larger weights are favored more.
3160 This option does not affect parent selection if a peering
3161 protocol is not in use.
3163 basetime=N Specify a base amount to be subtracted from round trip
3165 It is subtracted before division by weight in calculating
3166 which parent to fectch from. If the rtt is less than the
3167 base time the rtt is set to a minimal value.
3169 ttl=N Specify a TTL to use when sending multicast ICP queries
3171 Only useful when sending to a multicast group.
3172 Because we don't accept ICP replies from random
3173 hosts, you must configure other group members as
3174 peers with the 'multicast-responder' option.
3176 no-delay To prevent access to this neighbor from influencing the
3179 digest-url=URL Tell Squid to fetch the cache digest (if digests are
3180 enabled) for this host from the specified URL rather
3181 than the Squid default location.
3184 ==== CARP OPTIONS ====
3186 carp-key=key-specification
3187 use a different key than the full URL to hash against the peer.
3188 the key-specification is a comma-separated list of the keywords
3189 scheme, host, port, path, params
3190 Order is not important.
3192 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
3194 originserver Causes this parent to be contacted as an origin server.
3195 Meant to be used in accelerator setups when the peer
3199 Set the Host header of requests forwarded to this peer.
3200 Useful in accelerator setups where the server (peer)
3201 expects a certain domain name but clients may request
3202 others. ie example.com or www.example.com
3204 no-digest Disable request of cache digests.
3207 Disables requesting ICMP RTT database (NetDB).
3210 ==== AUTHENTICATION OPTIONS ====
3213 If this is a personal/workgroup proxy and your parent
3214 requires proxy authentication.
3216 Note: The string can include URL escapes (i.e. %20 for
3217 spaces). This also means % must be written as %%.
3220 Send login details received from client to this peer.
3221 Both Proxy- and WWW-Authorization headers are passed
3222 without alteration to the peer.
3223 Authentication is not required by Squid for this to work.
3225 Note: This will pass any form of authentication but
3226 only Basic auth will work through a proxy unless the
3227 connection-auth options are also used.
3229 login=PASS Send login details received from client to this peer.
3230 Authentication is not required by this option.
3232 If there are no client-provided authentication headers
3233 to pass on, but username and password are available
3234 from an external ACL user= and password= result tags
3235 they may be sent instead.
3237 Note: To combine this with proxy_auth both proxies must
3238 share the same user database as HTTP only allows for
3239 a single login (one for proxy, one for origin server).
3240 Also be warned this will expose your users proxy
3241 password to the peer. USE WITH CAUTION
3244 Send the username to the upstream cache, but with a
3245 fixed password. This is meant to be used when the peer
3246 is in another administrative domain, but it is still
3247 needed to identify each user.
3248 The star can optionally be followed by some extra
3249 information which is added to the username. This can
3250 be used to identify this proxy to the peer, similar to
3251 the login=username:password option above.
3254 If this is a personal/workgroup proxy and your parent
3255 requires a secure proxy authentication.
3256 The first principal from the default keytab or defined by
3257 the environment variable KRB5_KTNAME will be used.
3259 WARNING: The connection may transmit requests from multiple
3260 clients. Negotiate often assumes end-to-end authentication
3261 and a single-client. Which is not strictly true here.
3263 login=NEGOTIATE:principal_name
3264 If this is a personal/workgroup proxy and your parent
3265 requires a secure proxy authentication.
3266 The principal principal_name from the default keytab or
3267 defined by the environment variable KRB5_KTNAME will be
3270 WARNING: The connection may transmit requests from multiple
3271 clients. Negotiate often assumes end-to-end authentication
3272 and a single-client. Which is not strictly true here.
3274 connection-auth=on|off
3275 Tell Squid that this peer does or not support Microsoft
3276 connection oriented authentication, and any such
3277 challenges received from there should be ignored.
3278 Default is auto to automatically determine the status
3282 Do not use a keytab to authenticate to a peer when
3283 login=NEGOTIATE is specified. Let the GSSAPI
3284 implementation determine which already existing
3285 credentials cache to use instead.
3288 ==== SSL / HTTPS / TLS OPTIONS ====
3290 ssl Encrypt connections to this peer with SSL/TLS.
3292 sslcert=/path/to/ssl/certificate
3293 A client SSL certificate to use when connecting to
3296 sslkey=/path/to/ssl/key
3297 The private SSL key corresponding to sslcert above.
3298 If 'sslkey' is not specified 'sslcert' is assumed to
3299 reference a combined file containing both the
3300 certificate and the key.
3302 sslcipher=... The list of valid SSL ciphers to use when connecting
3306 The minimum TLS protocol version to permit. To control
3307 SSLv3 use the ssloptions= parameter.
3308 Supported Values: 1.0 (default), 1.1, 1.2
3310 ssloptions=... Specify various SSL implementation options:
3312 NO_SSLv3 Disallow the use of SSLv3
3314 NO_TLSv1 Disallow the use of TLSv1.0
3316 NO_TLSv1_1 Disallow the use of TLSv1.1
3318 NO_TLSv1_2 Disallow the use of TLSv1.2
3321 Always create a new key when using
3322 temporary/ephemeral DH key exchanges
3325 Disable use of RFC5077 session tickets.
3326 Some servers may have problems
3327 understanding the TLS extension due
3328 to ambiguous specification in RFC4507.
3330 ALL Enable various bug workarounds
3331 suggested as "harmless" by OpenSSL
3332 Be warned that this reduces SSL/TLS
3333 strength to some attacks.
3335 See the OpenSSL SSL_CTX_set_options documentation for a
3338 tls-cafile= PEM file containing CA certificates to use when verifying
3339 the peer certificate. May be repeated to load multiple files.
3341 sslcapath=... A directory containing additional CA certificates to
3342 use when verifying the peer certificate.
3343 Requires OpenSSL or LibreSSL.
3345 sslcrlfile=... A certificate revocation list file to use when
3346 verifying the peer certificate.
3348 sslflags=... Specify various flags modifying the SSL implementation:
3351 Accept certificates even if they fail to
3355 Don't verify the peer certificate
3356 matches the server name
3358 ssldomain= The peer name as advertised in it's certificate.
3359 Used for verifying the correctness of the received peer
3360 certificate. If not specified the peer hostname will be
3364 Enable the "Front-End-Https: On" header needed when
3365 using Squid as a SSL frontend in front of Microsoft OWA.
3366 See MS KB document Q307347 for details on this header.
3367 If set to auto the header will only be added if the
3368 request is forwarded as a https:// URL.
3370 tls-default-ca[=off]
3371 Whether to use the system Trusted CAs. Default is ON.
3373 tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1.
3375 ==== GENERAL OPTIONS ====
3378 A peer-specific connect timeout.
3379 Also see the peer_connect_timeout directive.
3381 connect-fail-limit=N
3382 How many times connecting to a peer must fail before
3383 it is marked as down. Standby connection failures
3384 count towards this limit. Default is 10.
3386 allow-miss Disable Squid's use of only-if-cached when forwarding
3387 requests to siblings. This is primarily useful when
3388 icp_hit_stale is used by the sibling. Excessive use
3389 of this option may result in forwarding loops. One way
3390 to prevent peering loops when using this option, is to
3391 deny cache peer usage on requests from a peer:
3393 cache_peer_access peerName deny fromPeer
3395 max-conn=N Limit the number of concurrent connections the Squid
3396 may open to this peer, including already opened idle
3397 and standby connections. There is no peer-specific
3398 connection limit by default.
3400 A peer exceeding the limit is not used for new
3401 requests unless a standby connection is available.
3403 max-conn currently works poorly with idle persistent
3404 connections: When a peer reaches its max-conn limit,
3405 and there are idle persistent connections to the peer,
3406 the peer may not be selected because the limiting code
3407 does not know whether Squid can reuse those idle
3410 standby=N Maintain a pool of N "hot standby" connections to an
3411 UP peer, available for requests when no idle
3412 persistent connection is available (or safe) to use.
3413 By default and with zero N, no such pool is maintained.
3414 N must not exceed the max-conn limit (if any).
3416 At start or after reconfiguration, Squid opens new TCP
3417 standby connections until there are N connections
3418 available and then replenishes the standby pool as
3419 opened connections are used up for requests. A used
3420 connection never goes back to the standby pool, but
3421 may go to the regular idle persistent connection pool
3422 shared by all peers and origin servers.
3424 Squid never opens multiple new standby connections
3425 concurrently. This one-at-a-time approach minimizes
3426 flooding-like effect on peers. Furthermore, just a few
3427 standby connections should be sufficient in most cases
3428 to supply most new requests with a ready-to-use
3431 Standby connections obey server_idle_pconn_timeout.
3432 For the feature to work as intended, the peer must be
3433 configured to accept and keep them open longer than
3434 the idle timeout at the connecting Squid, to minimize
3435 race conditions typical to idle used persistent
3436 connections. Default request_timeout and
3437 server_idle_pconn_timeout values ensure such a
3440 name=xxx Unique name for the peer.
3441 Required if you have multiple peers on the same host
3442 but different ports.
3443 This name can be used in cache_peer_access and similar
3444 directives to identify the peer.
3445 Can be used by outgoing access controls through the
3448 no-tproxy Do not use the client-spoof TPROXY support when forwarding
3449 requests to this peer. Use normal address selection instead.
3450 This overrides the spoof_client_ip ACL.
3452 proxy-only objects fetched from the peer will not be stored locally.
3456 NAME: cache_peer_access
3459 DEFAULT_DOC: No peer usage restrictions.
3462 Restricts usage of cache_peer proxies.
3465 cache_peer_access peer-name allow|deny [!]aclname ...
3467 For the required peer-name parameter, use either the value of the
3468 cache_peer name=value parameter or, if name=value is missing, the
3469 cache_peer hostname parameter.
3471 This directive narrows down the selection of peering candidates, but
3472 does not determine the order in which the selected candidates are
3473 contacted. That order is determined by the peer selection algorithms
3474 (see PEER SELECTION sections in the cache_peer documentation).
3476 If a deny rule matches, the corresponding peer will not be contacted
3477 for the current transaction -- Squid will not send ICP queries and
3478 will not forward HTTP requests to that peer. An allow match leaves
3479 the corresponding peer in the selection. The first match for a given
3480 peer wins for that peer.
3482 The relative order of cache_peer_access directives for the same peer
3483 matters. The relative order of any two cache_peer_access directives
3484 for different peers does not matter. To ease interpretation, it is a
3485 good idea to group cache_peer_access directives for the same peer
3488 A single cache_peer_access directive may be evaluated multiple times
3489 for a given transaction because individual peer selection algorithms
3490 may check it independently from each other. These redundant checks
3491 may be optimized away in future Squid versions.
3493 This clause only supports fast acl types.
3494 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
3498 NAME: neighbor_type_domain
3499 TYPE: hostdomaintype
3501 DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer.
3504 Modify the cache_peer neighbor type when passing requests
3505 about specific domains to the peer.
3508 neighbor_type_domain neighbor parent|sibling domain domain ...
3511 cache_peer foo.example.com parent 3128 3130
3512 neighbor_type_domain foo.example.com sibling .au .de
3514 The above configuration treats all requests to foo.example.com as a
3515 parent proxy unless the request is for a .au or .de ccTLD domain name.
3518 NAME: dead_peer_timeout
3522 LOC: Config.Timeout.deadPeer
3524 This controls how long Squid waits to declare a peer cache
3525 as "dead." If there are no ICP replies received in this
3526 amount of time, Squid will declare the peer dead and not
3527 expect to receive any further ICP replies. However, it
3528 continues to send ICP queries, and will mark the peer as
3529 alive upon receipt of the first subsequent ICP reply.
3531 This timeout also affects when Squid expects to receive ICP
3532 replies from peers. If more than 'dead_peer' seconds have
3533 passed since the last ICP reply was received, Squid will not
3534 expect to receive an ICP reply on the next query. Thus, if
3535 your time between requests is greater than this timeout, you
3536 will see a lot of requests sent DIRECT to origin servers
3537 instead of to your parents.
3540 NAME: forward_max_tries
3543 LOC: Config.forward_max_tries
3545 Controls how many different forward paths Squid will try
3546 before giving up. See also forward_timeout.
3548 NOTE: connect_retries (default: none) can make each of these
3549 possible forwarding paths be tried multiple times.
3553 MEMORY CACHE OPTIONS
3554 -----------------------------------------------------------------------------
3561 LOC: Config.memMaxSize
3563 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
3564 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
3565 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
3566 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
3568 'cache_mem' specifies the ideal amount of memory to be used
3570 * In-Transit objects
3572 * Negative-Cached objects
3574 Data for these objects are stored in 4 KB blocks. This
3575 parameter specifies the ideal upper limit on the total size of
3576 4 KB blocks allocated. In-Transit objects take the highest
3579 In-transit objects have priority over the others. When
3580 additional space is needed for incoming data, negative-cached
3581 and hot objects will be released. In other words, the
3582 negative-cached and hot objects will fill up any unused space
3583 not needed for in-transit objects.
3585 If circumstances require, this limit will be exceeded.
3586 Specifically, if your incoming request rate requires more than
3587 'cache_mem' of memory to hold in-transit objects, Squid will
3588 exceed this limit to satisfy the new requests. When the load
3589 decreases, blocks will be freed until the high-water mark is
3590 reached. Thereafter, blocks will be used to store hot
3593 If shared memory caching is enabled, Squid does not use the shared
3594 cache space for in-transit objects, but they still consume as much
3595 local memory as they need. For more details about the shared memory
3596 cache, see memory_cache_shared.
3599 NAME: maximum_object_size_in_memory
3603 LOC: Config.Store.maxInMemObjSize
3605 Objects greater than this size will not be attempted to kept in
3606 the memory cache. This should be set high enough to keep objects
3607 accessed frequently in memory to improve performance whilst low
3608 enough to keep larger objects from hoarding cache_mem.
3611 NAME: memory_cache_shared
3614 LOC: Config.memShared
3616 DEFAULT_DOC: "on" where supported if doing memory caching with multiple SMP workers.
3618 Controls whether the memory cache is shared among SMP workers.
3620 The shared memory cache is meant to occupy cache_mem bytes and replace
3621 the non-shared memory cache, although some entities may still be
3622 cached locally by workers for now (e.g., internal and in-transit
3623 objects may be served from a local memory cache even if shared memory
3624 caching is enabled).
3626 By default, the memory cache is shared if and only if all of the
3627 following conditions are satisfied: Squid runs in SMP mode with
3628 multiple workers, cache_mem is positive, and Squid environment
3629 supports required IPC primitives (e.g., POSIX shared memory segments
3630 and GCC-style atomic operations).
3632 To avoid blocking locks, shared memory uses opportunistic algorithms
3633 that do not guarantee that every cachable entity that could have been
3634 shared among SMP workers will actually be shared.
3636 Currently, entities exceeding 32KB in size cannot be shared.
3639 NAME: memory_cache_mode
3643 DEFAULT_DOC: Keep the most recently fetched objects in memory
3645 Controls which objects to keep in the memory cache (cache_mem)
3647 always Keep most recently fetched objects in memory (default)
3649 disk Only disk cache hits are kept in memory, which means
3650 an object must first be cached on disk and then hit
3651 a second time before cached in memory.
3653 network Only objects fetched from network is kept in memory
3656 NAME: memory_replacement_policy
3658 LOC: Config.memPolicy
3661 The memory replacement policy parameter determines which
3662 objects are purged from memory when memory space is needed.
3664 See cache_replacement_policy for details on algorithms.
3669 -----------------------------------------------------------------------------
3672 NAME: cache_replacement_policy
3674 LOC: Config.replPolicy
3677 The cache replacement policy parameter determines which
3678 objects are evicted (replaced) when disk space is needed.
3680 lru : Squid's original list based LRU policy
3681 heap GDSF : Greedy-Dual Size Frequency
3682 heap LFUDA: Least Frequently Used with Dynamic Aging
3683 heap LRU : LRU policy implemented using a heap
3685 Applies to any cache_dir lines listed below this directive.
3687 The LRU policies keeps recently referenced objects.
3689 The heap GDSF policy optimizes object hit rate by keeping smaller
3690 popular objects in cache so it has a better chance of getting a
3691 hit. It achieves a lower byte hit rate than LFUDA though since
3692 it evicts larger (possibly popular) objects.
3694 The heap LFUDA policy keeps popular objects in cache regardless of
3695 their size and thus optimizes byte hit rate at the expense of
3696 hit rate since one large, popular object will prevent many
3697 smaller, slightly less popular objects from being cached.
3699 Both policies utilize a dynamic aging mechanism that prevents
3700 cache pollution that can otherwise occur with frequency-based
3701 replacement policies.
3703 NOTE: if using the LFUDA replacement policy you should increase
3704 the value of maximum_object_size above its default of 4 MB to
3705 to maximize the potential byte hit rate improvement of LFUDA.
3707 For more information about the GDSF and LFUDA cache replacement
3708 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
3709 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
3712 NAME: minimum_object_size
3716 DEFAULT_DOC: no limit
3717 LOC: Config.Store.minObjectSize
3719 Objects smaller than this size will NOT be saved on disk. The
3720 value is specified in bytes, and the default is 0 KB, which
3721 means all responses can be stored.
3724 NAME: maximum_object_size
3728 LOC: Config.Store.maxObjectSize
3730 Set the default value for max-size parameter on any cache_dir.
3731 The value is specified in bytes, and the default is 4 MB.
3733 If you wish to get a high BYTES hit ratio, you should probably
3734 increase this (one 32 MB object hit counts for 3200 10KB
3737 If you wish to increase hit ratio more than you want to
3738 save bandwidth you should leave this low.
3740 NOTE: if using the LFUDA replacement policy you should increase
3741 this value to maximize the byte hit rate improvement of LFUDA!
3742 See cache_replacement_policy for a discussion of this policy.
3748 DEFAULT_DOC: No disk cache. Store cache ojects only in memory.
3749 LOC: Config.cacheSwap
3752 cache_dir Type Directory-Name Fs-specific-data [options]
3754 You can specify multiple cache_dir lines to spread the
3755 cache among different disk partitions.
3757 Type specifies the kind of storage system to use. Only "ufs"
3758 is built by default. To enable any of the other storage systems
3759 see the --enable-storeio configure option.
3761 'Directory' is a top-level directory where cache swap
3762 files will be stored. If you want to use an entire disk
3763 for caching, this can be the mount-point directory.
3764 The directory must exist and be writable by the Squid
3765 process. Squid will NOT create this directory for you.
3767 In SMP configurations, cache_dir must not precede the workers option
3768 and should use configuration macros or conditionals to give each
3769 worker interested in disk caching a dedicated cache directory.
3772 ==== The ufs store type ====
3774 "ufs" is the old well-known Squid storage format that has always
3778 cache_dir ufs Directory-Name Mbytes L1 L2 [options]
3780 'Mbytes' is the amount of disk space (MB) to use under this
3781 directory. The default is 100 MB. Change this to suit your
3782 configuration. Do NOT put the size of your disk drive here.
3783 Instead, if you want Squid to use the entire disk drive,
3784 subtract 20% and use that value.
3786 'L1' is the number of first-level subdirectories which
3787 will be created under the 'Directory'. The default is 16.
3789 'L2' is the number of second-level subdirectories which
3790 will be created under each first-level directory. The default
3794 ==== The aufs store type ====
3796 "aufs" uses the same storage format as "ufs", utilizing
3797 POSIX-threads to avoid blocking the main Squid process on
3798 disk-I/O. This was formerly known in Squid as async-io.
3801 cache_dir aufs Directory-Name Mbytes L1 L2 [options]
3803 see argument descriptions under ufs above
3806 ==== The diskd store type ====
3808 "diskd" uses the same storage format as "ufs", utilizing a
3809 separate process to avoid blocking the main Squid process on
3813 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
3815 see argument descriptions under ufs above
3817 Q1 specifies the number of unacknowledged I/O requests when Squid
3818 stops opening new files. If this many messages are in the queues,
3819 Squid won't open new files. Default is 64
3821 Q2 specifies the number of unacknowledged messages when Squid
3822 starts blocking. If this many messages are in the queues,
3823 Squid blocks until it receives some replies. Default is 72
3825 When Q1 < Q2 (the default), the cache directory is optimized
3826 for lower response time at the expense of a decrease in hit
3827 ratio. If Q1 > Q2, the cache directory is optimized for
3828 higher hit ratio at the expense of an increase in response
3832 ==== The rock store type ====
3835 cache_dir rock Directory-Name Mbytes [options]
3837 The Rock Store type is a database-style storage. All cached
3838 entries are stored in a "database" file, using fixed-size slots.
3839 A single entry occupies one or more slots.
3841 If possible, Squid using Rock Store creates a dedicated kid
3842 process called "disker" to avoid blocking Squid worker(s) on disk
3843 I/O. One disker kid is created for each rock cache_dir. Diskers
3844 are created only when Squid, running in daemon mode, has support
3845 for the IpcIo disk I/O module.
3847 swap-timeout=msec: Squid will not start writing a miss to or
3848 reading a hit from disk if it estimates that the swap operation
3849 will take more than the specified number of milliseconds. By
3850 default and when set to zero, disables the disk I/O time limit
3851 enforcement. Ignored when using blocking I/O module because
3852 blocking synchronous I/O does not allow Squid to estimate the
3853 expected swap wait time.
3855 max-swap-rate=swaps/sec: Artificially limits disk access using
3856 the specified I/O rate limit. Swap out requests that
3857 would cause the average I/O rate to exceed the limit are
3858 delayed. Individual swap in requests (i.e., hits or reads) are
3859 not delayed, but they do contribute to measured swap rate and
3860 since they are placed in the same FIFO queue as swap out
3861 requests, they may wait longer if max-swap-rate is smaller.
3862 This is necessary on file systems that buffer "too
3863 many" writes and then start blocking Squid and other processes
3864 while committing those writes to disk. Usually used together
3865 with swap-timeout to avoid excessive delays and queue overflows
3866 when disk demand exceeds available disk "bandwidth". By default
3867 and when set to zero, disables the disk I/O rate limit
3868 enforcement. Currently supported by IpcIo module only.
3870 slot-size=bytes: The size of a database "record" used for
3871 storing cached responses. A cached response occupies at least
3872 one slot and all database I/O is done using individual slots so
3873 increasing this parameter leads to more disk space waste while
3874 decreasing it leads to more disk I/O overheads. Should be a
3875 multiple of your operating system I/O page size. Defaults to
3876 16KBytes. A housekeeping header is stored with each slot and
3877 smaller slot-sizes will be rejected. The header is smaller than
3881 ==== COMMON OPTIONS ====
3883 no-store no new objects should be stored to this cache_dir.
3885 min-size=n the minimum object size in bytes this cache_dir
3886 will accept. It's used to restrict a cache_dir
3887 to only store large objects (e.g. AUFS) while
3888 other stores are optimized for smaller objects
3892 max-size=n the maximum object size in bytes this cache_dir
3894 The value in maximum_object_size directive sets
3895 the default unless more specific details are
3896 available (ie a small store capacity).
3898 Note: To make optimal use of the max-size limits you should order
3899 the cache_dir lines with the smallest max-size value first.
3903 # Uncomment and adjust the following to add a disk cache directory.
3904 #cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
3908 NAME: store_dir_select_algorithm
3910 LOC: Config.store_dir_select_algorithm
3913 How Squid selects which cache_dir to use when the response
3914 object will fit into more than one.
3916 Regardless of which algorithm is used the cache_dir min-size
3917 and max-size parameters are obeyed. As such they can affect
3918 the selection algorithm by limiting the set of considered
3925 This algorithm is suited to caches with similar cache_dir
3926 sizes and disk speeds.
3928 The disk with the least I/O pending is selected.
3929 When there are multiple disks with the same I/O load ranking
3930 the cache_dir with most available capacity is selected.
3932 When a mix of cache_dir sizes are configured the faster disks
3933 have a naturally lower I/O loading and larger disks have more
3934 capacity. So space used to store objects and data throughput
3935 may be very unbalanced towards larger disks.
3940 This algorithm is suited to caches with unequal cache_dir
3943 Each cache_dir is selected in a rotation. The next suitable
3946 Available cache_dir capacity is only considered in relation
3947 to whether the object will fit and meets the min-size and
3948 max-size parameters.
3950 Disk I/O loading is only considered to prevent overload on slow
3951 disks. This algorithm does not spread objects by size, so any
3952 I/O loading per-disk may appear very unbalanced and volatile.
3954 If several cache_dirs use similar min-size, max-size, or other
3955 limits to to reject certain responses, then do not group such
3956 cache_dir lines together, to avoid round-robin selection bias
3957 towards the first cache_dir after the group. Instead, interleave
3958 cache_dir lines from different groups. For example:
3960 store_dir_select_algorithm round-robin
3961 cache_dir rock /hdd1 ... min-size=100000
3962 cache_dir rock /ssd1 ... max-size=99999
3963 cache_dir rock /hdd2 ... min-size=100000
3964 cache_dir rock /ssd2 ... max-size=99999
3965 cache_dir rock /hdd3 ... min-size=100000
3966 cache_dir rock /ssd3 ... max-size=99999
3969 NAME: max_open_disk_fds
3971 LOC: Config.max_open_disk_fds
3973 DEFAULT_DOC: no limit
3975 To avoid having disk as the I/O bottleneck Squid can optionally
3976 bypass the on-disk cache if more than this amount of disk file
3977 descriptors are open.
3979 A value of 0 indicates no limit.
3982 NAME: cache_swap_low
3983 COMMENT: (percent, 0-100)
3986 LOC: Config.Swap.lowWaterMark
3988 The low-water mark for AUFS/UFS/diskd cache object eviction by
3989 the cache_replacement_policy algorithm.
3991 Removal begins when the swap (disk) usage of a cache_dir is
3992 above this low-water mark and attempts to maintain utilization
3993 near the low-water mark.
3995 As swap utilization increases towards the high-water mark set
3996 by cache_swap_high object eviction becomes more agressive.
3998 The value difference in percentages between low- and high-water
3999 marks represent an eviction rate of 300 objects per second and
4000 the rate continues to scale in agressiveness by multiples of
4001 this above the high-water mark.
4003 Defaults are 90% and 95%. If you have a large cache, 5% could be
4004 hundreds of MB. If this is the case you may wish to set these
4005 numbers closer together.
4007 See also cache_swap_high and cache_replacement_policy
4010 NAME: cache_swap_high
4011 COMMENT: (percent, 0-100)
4014 LOC: Config.Swap.highWaterMark
4016 The high-water mark for AUFS/UFS/diskd cache object eviction by
4017 the cache_replacement_policy algorithm.
4019 Removal begins when the swap (disk) usage of a cache_dir is
4020 above the low-water mark set by cache_swap_low and attempts to
4021 maintain utilization near the low-water mark.
4023 As swap utilization increases towards this high-water mark object
4024 eviction becomes more agressive.
4026 The value difference in percentages between low- and high-water
4027 marks represent an eviction rate of 300 objects per second and
4028 the rate continues to scale in agressiveness by multiples of
4029 this above the high-water mark.
4031 Defaults are 90% and 95%. If you have a large cache, 5% could be
4032 hundreds of MB. If this is the case you may wish to set these
4033 numbers closer together.
4035 See also cache_swap_low and cache_replacement_policy
4040 -----------------------------------------------------------------------------
4047 DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in.
4051 logformat <name> <format specification>
4053 Defines an access log format.
4055 The <format specification> is a string with embedded % format codes
4057 % format codes all follow the same basic structure where all but
4058 the formatcode is optional. Output strings are automatically escaped
4059 as required according to their context and the output format
4060 modifiers are usually not needed, but can be specified if an explicit
4061 output format is desired.
4063 % ["|[|'|#|/] [-] [[0]width] [{arg}] formatcode [{arg}]
4065 " output in quoted string format
4066 [ output in squid text log format as used by log_mime_hdrs
4067 # output in URL quoted format
4068 / output in shell \-escaped format
4073 width minimum and/or maximum field width:
4074 [width_min][.width_max]
4075 When minimum starts with 0, the field is zero-padded.
4076 String values exceeding maximum width are truncated.
4078 {arg} argument such as header name etc. This field may be
4079 placed before or after the token, but not both at once.
4083 % a literal % character
4084 sn Unique sequence number per log line entry
4085 err_code The ID of an error response served by Squid or
4086 a similar internal error identifier.
4087 err_detail Additional err_code-dependent error information.
4088 note The annotation specified by the argument. Also
4089 logs the adaptation meta headers set by the
4090 adaptation_meta configuration parameter.
4091 If no argument given all annotations logged.
4092 The argument may include a separator to use with
4095 By default, multiple note values are separated with ","
4096 and multiple notes are separated with "\r\n".
4097 When logging named notes with %{name}note, the
4098 explicitly configured separator is used between note
4099 values. When logging all notes with %note, the
4100 explicitly configured separator is used between
4101 individual notes. There is currently no way to
4102 specify both value and notes separators when logging
4103 all notes with %note.
4105 Connection related format codes:
4107 >a Client source IP address
4109 >p Client source port
4110 >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier)
4111 >la Local IP address the client connected to
4112 >lp Local port number the client connected to
4113 >qos Client connection TOS/DSCP value set by Squid
4114 >nfmark Client connection netfilter mark set by Squid
4116 la Local listening IP address the client connection was connected to.
4117 lp Local listening port number the client connection was connected to.
4119 <a Server IP address of the last server or peer connection
4120 <A Server FQDN or peer name
4121 <p Server port number of the last server or peer connection
4122 <la Local IP address of the last server or peer connection
4123 <lp Local port number of the last server or peer connection
4124 <qos Server connection TOS/DSCP value set by Squid
4125 <nfmark Server connection netfilter mark set by Squid
4127 Time related format codes:
4129 ts Seconds since epoch
4130 tu subsecond time (milliseconds)
4131 tl Local time. Optional strftime format argument
4132 default %d/%b/%Y:%H:%M:%S %z
4133 tg GMT time. Optional strftime format argument
4134 default %d/%b/%Y:%H:%M:%S %z
4135 tr Response time (milliseconds)
4136 dt Total time spent making DNS lookups (milliseconds)
4137 tS Approximate master transaction start time in
4138 <full seconds since epoch>.<fractional seconds> format.
4139 Currently, Squid considers the master transaction
4140 started when a complete HTTP request header initiating
4141 the transaction is received from the client. This is
4142 the same value that Squid uses to calculate transaction
4143 response time when logging %tr to access.log. Currently,
4144 Squid uses millisecond resolution for %tS values,
4145 similar to the default access.log "current time" field
4148 Access Control related format codes:
4150 et Tag returned by external acl
4151 ea Log string returned by external acl
4152 un User name (any available)
4153 ul User name from authentication
4154 ue User name from external acl helper
4155 ui User name from ident
4156 un A user name. Expands to the first available name
4157 from the following list of information sources:
4158 - authenticated user name, like %ul
4159 - user name supplied by an external ACL, like %ue
4160 - SSL client name, like %us
4161 - ident user name, like %ui
4162 credentials Client credentials. The exact meaning depends on
4163 the authentication scheme: For Basic authentication,
4164 it is the password; for Digest, the realm sent by the
4165 client; for NTLM and Negotiate, the client challenge
4166 or client credentials prefixed with "YR " or "KK ".
4168 HTTP related format codes:
4172 [http::]rm Request method (GET/POST etc)
4173 [http::]>rm Request method from client
4174 [http::]<rm Request method sent to server or peer
4175 [http::]ru Request URL from client (historic, filtered for logging)
4176 [http::]>ru Request URL from client
4177 [http::]<ru Request URL sent to server or peer
4178 [http::]>rs Request URL scheme from client
4179 [http::]<rs Request URL scheme sent to server or peer
4180 [http::]>rd Request URL domain from client
4181 [http::]<rd Request URL domain sent to server or peer
4182 [http::]>rP Request URL port from client
4183 [http::]<rP Request URL port sent to server or peer
4184 [http::]rp Request URL path excluding hostname
4185 [http::]>rp Request URL path excluding hostname from client
4186 [http::]<rp Request URL path excluding hostname sent to server or peer
4187 [http::]rv Request protocol version
4188 [http::]>rv Request protocol version from client
4189 [http::]<rv Request protocol version sent to server or peer
4191 [http::]>h Original received request header.
4192 Usually differs from the request header sent by
4193 Squid, although most fields are often preserved.
4194 Accepts optional header field name/value filter
4195 argument using name[:[separator]element] format.
4196 [http::]>ha Received request header after adaptation and
4197 redirection (pre-cache REQMOD vectoring point).
4198 Usually differs from the request header sent by
4199 Squid, although most fields are often preserved.
4200 Optional header name argument as for >h
4204 [http::]<Hs HTTP status code received from the next hop
4205 [http::]>Hs HTTP status code sent to the client
4207 [http::]<h Reply header. Optional header name argument
4210 [http::]mt MIME content type
4215 [http::]st Total size of request + reply traffic with client
4216 [http::]>st Total size of request received from client.
4217 Excluding chunked encoding bytes.
4218 [http::]<st Total size of reply sent to client (after adaptation)
4220 [http::]>sh Size of request headers received from client
4221 [http::]<sh Size of reply headers sent to client (after adaptation)
4223 [http::]<sH Reply high offset sent
4224 [http::]<sS Upstream object size
4226 [http::]<bs Number of HTTP-equivalent message body bytes
4227 received from the next hop, excluding chunked
4228 transfer encoding and control messages.
4229 Generated FTP/Gopher listings are treated as
4234 [http::]<pt Peer response time in milliseconds. The timer starts
4235 when the last request byte is sent to the next hop
4236 and stops when the last response byte is received.
4237 [http::]<tt Total time in milliseconds. The timer
4238 starts with the first connect request (or write I/O)
4239 sent to the first selected peer. The timer stops
4240 with the last I/O with the last peer.
4242 Squid handling related format codes:
4244 Ss Squid request status (TCP_MISS etc)
4245 Sh Squid hierarchy status (DEFAULT_PARENT etc)
4247 SSL-related format codes:
4249 ssl::bump_mode SslBump decision for the transaction:
4251 For CONNECT requests that initiated bumping of
4252 a connection and for any request received on
4253 an already bumped connection, Squid logs the
4254 corresponding SslBump mode ("server-first" or
4255 "client-first"). See the ssl_bump option for
4256 more information about these modes.
4258 A "none" token is logged for requests that
4259 triggered "ssl_bump" ACL evaluation matching
4260 either a "none" rule or no rules at all.
4262 In all other cases, a single dash ("-") is
4265 ssl::>sni SSL client SNI sent to Squid. Available only
4266 after the peek, stare, or splice SSL bumping
4270 The Subject field of the received client
4271 SSL certificate or a dash ('-') if Squid has
4272 received an invalid/malformed certificate or
4273 no certificate at all. Consider encoding the
4274 logged value because Subject often has spaces.
4277 The Issuer field of the received client
4278 SSL certificate or a dash ('-') if Squid has
4279 received an invalid/malformed certificate or
4280 no certificate at all. Consider encoding the
4281 logged value because Issuer often has spaces.
4284 The list of certificate validation errors
4285 detected by Squid (including OpenSSL and
4286 certificate validation helper components). The
4287 errors are listed in the discovery order. By
4288 default, the error codes are separated by ':'.
4289 Accepts an optional separator argument.
4291 %ssl::>negotiated_version The negotiated TLS version of the
4294 %ssl::<negotiated_version The negotiated TLS version of the
4295 last server or peer connection.
4297 %ssl::>received_hello_version The TLS version of the Hello
4298 message received from TLS client.
4300 %ssl::<received_hello_version The TLS version of the Hello
4301 message received from TLS server.
4303 %ssl::>received_supported_version The maximum TLS version
4304 supported by the TLS client.
4306 %ssl::<received_supported_version The maximum TLS version
4307 supported by the TLS server.
4309 %ssl::>negotiated_cipher The negotiated cipher of the
4312 %ssl::<negotiated_cipher The negotiated cipher of the
4313 last server or peer connection.
4315 If ICAP is enabled, the following code becomes available (as
4316 well as ICAP log codes documented with the icap_log option):
4318 icap::tt Total ICAP processing time for the HTTP
4319 transaction. The timer ticks when ICAP
4320 ACLs are checked and when ICAP
4321 transaction is in progress.
4323 If adaptation is enabled the following codes become available:
4325 adapt::<last_h The header of the last ICAP response or
4326 meta-information from the last eCAP
4327 transaction related to the HTTP transaction.
4328 Like <h, accepts an optional header name
4331 adapt::sum_trs Summed adaptation transaction response
4332 times recorded as a comma-separated list in
4333 the order of transaction start time. Each time
4334 value is recorded as an integer number,
4335 representing response time of one or more
4336 adaptation (ICAP or eCAP) transaction in
4337 milliseconds. When a failed transaction is
4338 being retried or repeated, its time is not
4339 logged individually but added to the
4340 replacement (next) transaction. See also:
4343 adapt::all_trs All adaptation transaction response times.
4344 Same as adaptation_strs but response times of
4345 individual transactions are never added
4346 together. Instead, all transaction response
4347 times are recorded individually.
4349 You can prefix adapt::*_trs format codes with adaptation
4350 service name in curly braces to record response time(s) specific
4351 to that service. For example: %{my_service}adapt::sum_trs
4353 The default formats available (which do not need re-defining) are:
4355 logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
4356 logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
4357 logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
4358 logformat referrer %ts.%03tu %>a %{Referer}>h %ru
4359 logformat useragent %>a [%tl] "%{User-Agent}>h"
4361 NOTE: When the log_mime_hdrs directive is set to ON.
4362 The squid, common and combined formats have a safely encoded copy
4363 of the mime headers appended to each line within a pair of brackets.
4365 NOTE: The common and combined formats are not quite true to the Apache definition.
4366 The logs from Squid contain an extra status and hierarchy code appended.
4370 NAME: access_log cache_access_log
4372 LOC: Config.Log.accesslogs
4373 DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
4375 Configures whether and how Squid logs HTTP and ICP transactions.
4376 If access logging is enabled, a single line is logged for every
4377 matching HTTP or ICP request. The recommended directive formats are:
4379 access_log <module>:<place> [option ...] [acl acl ...]
4380 access_log none [acl acl ...]
4382 The following directive format is accepted but may be deprecated:
4383 access_log <module>:<place> [<logformat name> [acl acl ...]]
4385 In most cases, the first ACL name must not contain the '=' character
4386 and should not be equal to an existing logformat name. You can always
4387 start with an 'all' ACL to work around those restrictions.
4389 Will log to the specified module:place using the specified format (which
4390 must be defined in a logformat directive) those entries which match
4391 ALL the acl's specified (which must be defined in acl clauses).
4392 If no acl is specified, all requests will be logged to this destination.
4394 ===== Available options for the recommended directive format =====
4396 logformat=name Names log line format (either built-in or
4397 defined by a logformat directive). Defaults
4400 buffer-size=64KB Defines approximate buffering limit for log
4401 records (see buffered_logs). Squid should not
4402 keep more than the specified size and, hence,
4403 should flush records before the buffer becomes
4404 full to avoid overflows under normal
4405 conditions (the exact flushing algorithm is
4406 module-dependent though). The on-error option
4407 controls overflow handling.
4409 on-error=die|drop Defines action on unrecoverable errors. The
4410 'drop' action ignores (i.e., does not log)
4411 affected log records. The default 'die' action
4412 kills the affected worker. The drop action
4413 support has not been tested for modules other
4416 rotate=N Specifies the number of log file rotations to
4417 make when you run 'squid -k rotate'. The default
4418 is to obey the logfile_rotate directive. Setting
4419 rotate=0 will disable the file name rotation,
4420 but the log files are still closed and re-opened.
4421 This will enable you to rename the logfiles
4422 yourself just before sending the rotate signal.
4423 Only supported by the stdio module.
4425 ===== Modules Currently available =====
4427 none Do not log any requests matching these ACL.
4428 Do not specify Place or logformat name.
4430 stdio Write each log line to disk immediately at the completion of
4432 Place: the filename and path to be written.
4434 daemon Very similar to stdio. But instead of writing to disk the log
4435 line is passed to a daemon helper for asychronous handling instead.
4436 Place: varies depending on the daemon.
4438 log_file_daemon Place: the file name and path to be written.
4440 syslog To log each request via syslog facility.
4441 Place: The syslog facility and priority level for these entries.
4442 Place Format: facility.priority
4444 where facility could be any of:
4445 authpriv, daemon, local0 ... local7 or user.
4447 And priority could be any of:
4448 err, warning, notice, info, debug.
4450 udp To send each log line as text data to a UDP receiver.
4451 Place: The destination host name or IP and port.
4452 Place Format: //host:port
4454 tcp To send each log line as text data to a TCP receiver.
4455 Lines may be accumulated before sending (see buffered_logs).
4456 Place: The destination host name or IP and port.
4457 Place Format: //host:port
4460 access_log daemon:@DEFAULT_ACCESS_LOG@ squid
4466 LOC: Config.Log.icaplogs
4469 ICAP log files record ICAP transaction summaries, one line per
4472 The icap_log option format is:
4473 icap_log <filepath> [<logformat name> [acl acl ...]]
4474 icap_log none [acl acl ...]]
4476 Please see access_log option documentation for details. The two
4477 kinds of logs share the overall configuration approach and many
4480 ICAP processing of a single HTTP message or transaction may
4481 require multiple ICAP transactions. In such cases, multiple
4482 ICAP transaction log lines will correspond to a single access
4485 ICAP log uses logformat codes that make sense for an ICAP
4486 transaction. Header-related codes are applied to the HTTP header
4487 embedded in an ICAP server response, with the following caveats:
4488 For REQMOD, there is no HTTP response header unless the ICAP
4489 server performed request satisfaction. For RESPMOD, the HTTP
4490 request header is the header sent to the ICAP server. For
4491 OPTIONS, there are no HTTP headers.
4493 The following format codes are also available for ICAP logs:
4495 icap::<A ICAP server IP address. Similar to <A.
4497 icap::<service_name ICAP service name from the icap_service
4498 option in Squid configuration file.
4500 icap::ru ICAP Request-URI. Similar to ru.
4502 icap::rm ICAP request method (REQMOD, RESPMOD, or
4503 OPTIONS). Similar to existing rm.
4505 icap::>st Bytes sent to the ICAP server (TCP payload
4506 only; i.e., what Squid writes to the socket).
4508 icap::<st Bytes received from the ICAP server (TCP
4509 payload only; i.e., what Squid reads from
4512 icap::<bs Number of message body bytes received from the
4513 ICAP server. ICAP message body, if any, usually
4514 includes encapsulated HTTP message headers and
4515 possibly encapsulated HTTP message body. The
4516 HTTP body part is dechunked before its size is
4519 icap::tr Transaction response time (in
4520 milliseconds). The timer starts when
4521 the ICAP transaction is created and
4522 stops when the transaction is completed.
4525 icap::tio Transaction I/O time (in milliseconds). The
4526 timer starts when the first ICAP request
4527 byte is scheduled for sending. The timers
4528 stops when the last byte of the ICAP response
4531 icap::to Transaction outcome: ICAP_ERR* for all
4532 transaction errors, ICAP_OPT for OPTION
4533 transactions, ICAP_ECHO for 204
4534 responses, ICAP_MOD for message
4535 modification, and ICAP_SAT for request
4536 satisfaction. Similar to Ss.
4538 icap::Hs ICAP response status code. Similar to Hs.
4540 icap::>h ICAP request header(s). Similar to >h.
4542 icap::<h ICAP response header(s). Similar to <h.
4544 The default ICAP log format, which can be used without an explicit
4545 definition, is called icap_squid:
4547 logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
4549 See also: logformat, log_icap, and %adapt::<last_h
4552 NAME: logfile_daemon
4554 DEFAULT: @DEFAULT_LOGFILED@
4555 LOC: Log::TheConfig.logfile_daemon
4557 Specify the path to the logfile-writing daemon. This daemon is
4558 used to write the access and store logs, if configured.
4560 Squid sends a number of commands to the log daemon:
4561 L<data>\n - logfile data
4566 r<n>\n - set rotate count to <n>
4567 b<n>\n - 1 = buffer output, 0 = don't buffer output
4569 No responses is expected.
4572 NAME: stats_collection
4574 LOC: Config.accessList.stats_collection
4576 DEFAULT_DOC: Allow logging for all transactions.
4577 COMMENT: allow|deny acl acl...
4579 This options allows you to control which requests gets accounted
4580 in performance counters.
4582 This clause only supports fast acl types.
4583 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
4586 NAME: cache_store_log
4589 LOC: Config.Log.store
4591 Logs the activities of the storage manager. Shows which
4592 objects are ejected from the cache, and which objects are
4593 saved and for how long.
4594 There are not really utilities to analyze this data, so you can safely
4595 disable it (the default).
4597 Store log uses modular logging outputs. See access_log for the list
4598 of modules supported.
4601 cache_store_log stdio:@DEFAULT_STORE_LOG@
4602 cache_store_log daemon:@DEFAULT_STORE_LOG@
4605 NAME: cache_swap_state cache_swap_log
4607 LOC: Config.Log.swap
4609 DEFAULT_DOC: Store the journal inside its cache_dir
4611 Location for the cache "swap.state" file. This index file holds
4612 the metadata of objects saved on disk. It is used to rebuild
4613 the cache during startup. Normally this file resides in each
4614 'cache_dir' directory, but you may specify an alternate
4615 pathname here. Note you must give a full filename, not just
4616 a directory. Since this is the index for the whole object
4617 list you CANNOT periodically rotate it!
4619 If %s can be used in the file name it will be replaced with a
4620 a representation of the cache_dir name where each / is replaced
4621 with '.'. This is needed to allow adding/removing cache_dir
4622 lines when cache_swap_log is being used.
4624 If have more than one 'cache_dir', and %s is not used in the name
4625 these swap logs will have names such as:
4631 The numbered extension (which is added automatically)
4632 corresponds to the order of the 'cache_dir' lines in this
4633 configuration file. If you change the order of the 'cache_dir'
4634 lines in this file, these index files will NOT correspond to
4635 the correct 'cache_dir' entry (unless you manually rename
4636 them). We recommend you do NOT use this option. It is
4637 better to keep these index files in each 'cache_dir' directory.
4640 NAME: logfile_rotate
4643 LOC: Config.Log.rotateNumber
4645 Specifies the default number of logfile rotations to make when you
4646 type 'squid -k rotate'. The default is 10, which will rotate
4647 with extensions 0 through 9. Setting logfile_rotate to 0 will
4648 disable the file name rotation, but the logfiles are still closed
4649 and re-opened. This will enable you to rename the logfiles
4650 yourself just before sending the rotate signal.
4652 Note, from Squid-3.1 this option is only a default for cache.log,
4653 that log can be rotated separately by using debug_options.
4655 Note, from Squid-3.6 this option is only a default for access.log
4656 recorded by stdio: module. Those logs can be rotated separately by
4657 using the rotate=N option on their access_log directive.
4659 Note, the 'squid -k rotate' command normally sends a USR1
4660 signal to the running squid process. In certain situations
4661 (e.g. on Linux with Async I/O), USR1 is used for other
4662 purposes, so -k rotate uses another signal. It is best to get
4663 in the habit of using 'squid -k rotate' instead of 'kill -USR1
4670 DEFAULT: @DEFAULT_MIME_TABLE@
4671 LOC: Config.mimeTablePathname
4673 Path to Squid's icon configuration file.
4675 You shouldn't need to change this, but the default file contains
4676 examples and formatting information if you do.
4682 LOC: Config.onoff.log_mime_hdrs
4685 The Cache can record both the request and the response MIME
4686 headers for each HTTP transaction. The headers are encoded
4687 safely and will appear as two bracketed fields at the end of
4688 the access log (for either the native or httpd-emulated log
4689 formats). To enable this logging set log_mime_hdrs to 'on'.
4694 DEFAULT: @DEFAULT_PID_FILE@
4695 LOC: Config.pidFilename
4697 A filename to write the process-id to. To disable, enter "none".
4700 NAME: client_netmask
4702 LOC: Config.Addrs.client_netmask
4704 DEFAULT_DOC: Log full client IP address
4706 A netmask for client addresses in logfiles and cachemgr output.
4707 Change this to protect the privacy of your cache clients.
4708 A netmask of 255.255.255.0 will log all IP's in that range with
4709 the last digit set to '0'.
4712 NAME: strip_query_terms
4714 LOC: Config.onoff.strip_query_terms
4717 By default, Squid strips query terms from requested URLs before
4718 logging. This protects your user's privacy and reduces log size.
4720 When investigating HIT/MISS or other caching behaviour you
4721 will need to disable this to see the full URL used by Squid.
4728 LOC: Config.onoff.buffered_logs
4730 Whether to write/send access_log records ASAP or accumulate them and
4731 then write/send them in larger chunks. Buffering may improve
4732 performance because it decreases the number of I/Os. However,
4733 buffering increases the delay before log records become available to
4734 the final recipient (e.g., a disk file or logging daemon) and,
4735 hence, increases the risk of log records loss.
4737 Note that even when buffered_logs are off, Squid may have to buffer
4738 records if it cannot write/send them immediately due to pending I/Os
4739 (e.g., the I/O writing the previous log record) or connectivity loss.
4741 Currently honored by 'daemon' and 'tcp' access_log modules only.
4744 NAME: netdb_filename
4746 DEFAULT: stdio:@DEFAULT_NETDB_FILE@
4747 LOC: Config.netdbFilename
4750 Where Squid stores it's netdb journal.
4751 When enabled this journal preserves netdb state between restarts.
4753 To disable, enter "none".
4757 OPTIONS FOR TROUBLESHOOTING
4758 -----------------------------------------------------------------------------
4763 DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
4764 LOC: Debug::cache_log
4766 Squid administrative logging file.
4768 This is where general information about Squid behavior goes. You can
4769 increase the amount of data logged to this file and how often it is
4770 rotated with "debug_options"
4776 DEFAULT_DOC: Log all critical and important messages.
4777 LOC: Debug::debugOptions
4779 Logging options are set as section,level where each source file
4780 is assigned a unique section. Lower levels result in less
4781 output, Full debugging (level 9) can result in a very large
4782 log file, so be careful.
4784 The magic word "ALL" sets debugging levels for all sections.
4785 The default is to run with "ALL,1" to record important warnings.
4787 The rotate=N option can be used to keep more or less of these logs
4788 than would otherwise be kept by logfile_rotate.
4789 For most uses a single log should be enough to monitor current
4790 events affecting Squid.
4795 LOC: Config.coredump_dir
4796 DEFAULT_IF_NONE: none
4797 DEFAULT_DOC: Use the directory from where Squid was started.
4799 By default Squid leaves core files in the directory from where
4800 it was started. If you set 'coredump_dir' to a directory
4801 that exists, Squid will chdir() to that directory at startup
4802 and coredump files will be left there.
4806 # Leave coredumps in the first cache dir
4807 coredump_dir @DEFAULT_SWAP_DIR@
4813 OPTIONS FOR FTP GATEWAYING
4814 -----------------------------------------------------------------------------
4820 LOC: Config.Ftp.anon_user
4822 If you want the anonymous login password to be more informative
4823 (and enable the use of picky FTP servers), set this to something
4824 reasonable for your domain, like wwwuser@somewhere.net
4826 The reason why this is domainless by default is the
4827 request can be made on the behalf of a user in any domain,
4828 depending on how the cache is used.
4829 Some FTP server also validate the email address is valid
4830 (for example perl.com).
4836 LOC: Config.Ftp.passive
4838 If your firewall does not allow Squid to use passive
4839 connections, turn off this option.
4841 Use of ftp_epsv_all option requires this to be ON.
4847 LOC: Config.Ftp.epsv_all
4849 FTP Protocol extensions permit the use of a special "EPSV ALL" command.
4851 NATs may be able to put the connection on a "fast path" through the
4852 translator, as the EPRT command will never be used and therefore,
4853 translation of the data portion of the segments will never be needed.
4855 When a client only expects to do two-way FTP transfers this may be
4857 If squid finds that it must do a three-way FTP transfer after issuing
4858 an EPSV ALL command, the FTP session will fail.
4860 If you have any doubts about this option do not use it.
4861 Squid will nicely attempt all other connection methods.
4863 Requires ftp_passive to be ON (default) for any effect.
4869 LOC: Config.accessList.ftp_epsv
4871 FTP Protocol extensions permit the use of a special "EPSV" command.
4873 NATs may be able to put the connection on a "fast path" through the
4874 translator using EPSV, as the EPRT command will never be used
4875 and therefore, translation of the data portion of the segments
4876 will never be needed.
4878 EPSV is often required to interoperate with FTP servers on IPv6
4879 networks. On the other hand, it may break some IPv4 servers.
4881 By default, EPSV may try EPSV with any FTP server. To fine tune
4882 that decision, you may restrict EPSV to certain clients or servers
4885 ftp_epsv allow|deny al1 acl2 ...
4887 WARNING: Disabling EPSV may cause problems with external NAT and IPv6.
4889 Only fast ACLs are supported.
4890 Requires ftp_passive to be ON (default) for any effect.
4896 LOC: Config.Ftp.eprt
4898 FTP Protocol extensions permit the use of a special "EPRT" command.
4900 This extension provides a protocol neutral alternative to the
4901 IPv4-only PORT command. When supported it enables active FTP data
4902 channels over IPv6 and efficient NAT handling.
4904 Turning this OFF will prevent EPRT being attempted and will skip
4905 straight to using PORT for IPv4 servers.
4907 Some devices are known to not handle this extension correctly and
4908 may result in crashes. Devices which suport EPRT enough to fail
4909 cleanly will result in Squid attempting PORT anyway. This directive
4910 should only be disabled when EPRT results in device failures.
4912 WARNING: Doing so will convert Squid back to the old behavior with all
4913 the related problems with external NAT devices/layers and IPv4-only FTP.
4916 NAME: ftp_sanitycheck
4919 LOC: Config.Ftp.sanitycheck
4921 For security and data integrity reasons Squid by default performs
4922 sanity checks of the addresses of FTP data connections ensure the
4923 data connection is to the requested server. If you need to allow
4924 FTP connections to servers using another IP address for the data
4925 connection turn this off.
4928 NAME: ftp_telnet_protocol
4931 LOC: Config.Ftp.telnet
4933 The FTP protocol is officially defined to use the telnet protocol
4934 as transport channel for the control connection. However, many
4935 implementations are broken and does not respect this aspect of
4938 If you have trouble accessing files with ASCII code 255 in the
4939 path or similar problems involving this ASCII code you can
4940 try setting this directive to off. If that helps, report to the
4941 operator of the FTP server in question that their FTP server
4942 is broken and does not follow the FTP standard.
4946 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
4947 -----------------------------------------------------------------------------
4952 DEFAULT: @DEFAULT_DISKD@
4953 LOC: Config.Program.diskd
4955 Specify the location of the diskd executable.
4956 Note this is only useful if you have compiled in
4957 diskd as one of the store io modules.
4960 NAME: unlinkd_program
4963 DEFAULT: @DEFAULT_UNLINKD@
4964 LOC: Config.Program.unlinkd
4966 Specify the location of the executable for file deletion process.
4969 NAME: pinger_program
4972 DEFAULT: @DEFAULT_PINGER@
4975 Specify the location of the executable for the pinger process.
4984 Control whether the pinger is active at run-time.
4985 Enables turning ICMP pinger on and off with a simple
4986 squid -k reconfigure.
4991 OPTIONS FOR URL REWRITING
4992 -----------------------------------------------------------------------------
4995 NAME: url_rewrite_program redirect_program
4997 LOC: Config.Program.redirect
5000 Specify the location of the executable URL rewriter to use.
5001 Since they can perform almost any function there isn't one included.
5003 For each requested URL, the rewriter will receive on line with the format
5005 [channel-ID <SP>] URL [<SP> extras]<NL>
5007 See url_rewrite_extras on how to send "extras" with optional values to
5009 After processing the request the helper must reply using the following format:
5011 [channel-ID <SP>] result [<SP> kv-pairs]
5013 The result code can be:
5015 OK status=30N url="..."
5016 Redirect the URL to the one supplied in 'url='.
5017 'status=' is optional and contains the status code to send
5018 the client in Squids HTTP response. It must be one of the
5019 HTTP redirect status codes: 301, 302, 303, 307, 308.
5020 When no status is given Squid will use 302.
5022 OK rewrite-url="..."
5023 Rewrite the URL to the one supplied in 'rewrite-url='.
5024 The new URL is fetched directly by Squid and returned to
5025 the client as the response to its request.
5028 When neither of url= and rewrite-url= are sent Squid does
5032 Do not change the URL.
5035 An internal error occurred in the helper, preventing
5036 a result being identified. The 'message=' key name is
5037 reserved for delivering a log message.
5040 In addition to the above kv-pairs Squid also understands the following
5041 optional kv-pairs received from URL rewriters:
5043 Associates a TAG with the client TCP connection.
5044 The TAG is treated as a regular annotation but persists across
5045 future requests on the client connection rather than just the
5046 current request. A helper may update the TAG during subsequent
5047 requests be returning a new kv-pair.
5049 When using the concurrency= option the protocol is changed by
5050 introducing a query channel tag in front of the request/response.
5051 The query channel tag is a number between 0 and concurrency-1.
5052 This value must be echoed back unchanged to Squid as the first part
5053 of the response relating to its request.
5055 WARNING: URL re-writing ability should be avoided whenever possible.
5056 Use the URL redirect form of response instead.
5058 Re-write creates a difference in the state held by the client
5059 and server. Possibly causing confusion when the server response
5060 contains snippets of its view state. Embeded URLs, response
5061 and content Location headers, etc. are not re-written by this
5064 By default, a URL rewriter is not used.
5067 NAME: url_rewrite_children redirect_children
5068 TYPE: HelperChildConfig
5069 DEFAULT: 20 startup=0 idle=1 concurrency=0
5070 LOC: Config.redirectChildren
5072 The maximum number of redirector processes to spawn. If you limit
5073 it too few Squid will have to wait for them to process a backlog of
5074 URLs, slowing it down. If you allow too many they will use RAM
5075 and other system resources noticably.
5077 The startup= and idle= options allow some measure of skew in your
5082 Sets a minimum of how many processes are to be spawned when Squid
5083 starts or reconfigures. When set to zero the first request will
5084 cause spawning of the first child process to handle it.
5086 Starting too few will cause an initial slowdown in traffic as Squid
5087 attempts to simultaneously spawn enough processes to cope.
5091 Sets a minimum of how many processes Squid is to try and keep available
5092 at all times. When traffic begins to rise above what the existing
5093 processes can handle this many more will be spawned up to the maximum
5094 configured. A minimum setting of 1 is required.
5098 The number of requests each redirector helper can handle in
5099 parallel. Defaults to 0 which indicates the redirector
5100 is a old-style single threaded redirector.
5102 When this directive is set to a value >= 1 then the protocol
5103 used to communicate with the helper is modified to include
5104 an ID in front of the request/response. The ID from the request
5105 must be echoed back with the response to that request.
5109 Sets the maximum number of queued requests.
5110 If the queued requests exceed queue size and redirector_bypass
5111 configuration option is set, then redirector is bypassed. Otherwise, if
5112 overloading persists squid may abort its operation.
5113 The default value is set to 2*numberofchildren.
5116 NAME: url_rewrite_host_header redirect_rewrites_host_header
5119 LOC: Config.onoff.redir_rewrites_host
5121 To preserve same-origin security policies in browsers and
5122 prevent Host: header forgery by redirectors Squid rewrites
5123 any Host: header in redirected requests.
5125 If you are running an accelerator this may not be a wanted
5126 effect of a redirector. This directive enables you disable
5127 Host: alteration in reverse-proxy traffic.
5129 WARNING: Entries are cached on the result of the URL rewriting
5130 process, so be careful if you have domain-virtual hosts.
5132 WARNING: Squid and other software verifies the URL and Host
5133 are matching, so be careful not to relay through other proxies
5134 or inspecting firewalls with this disabled.
5137 NAME: url_rewrite_access redirector_access
5140 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
5141 LOC: Config.accessList.redirector
5143 If defined, this access list specifies which requests are
5144 sent to the redirector processes.
5146 This clause supports both fast and slow acl types.
5147 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5150 NAME: url_rewrite_bypass redirector_bypass
5152 LOC: Config.onoff.redirector_bypass
5155 When this is 'on', a request will not go through the
5156 redirector if all the helpers are busy. If this is 'off'
5157 and the redirector queue grows too large, Squid will exit
5158 with a FATAL error and ask you to increase the number of
5159 redirectors. You should only enable this if the redirectors
5160 are not critical to your caching system. If you use
5161 redirectors for access control, and you enable this option,
5162 users may have access to pages they should not
5163 be allowed to request.
5164 This options sets default queue-size option of the url_rewrite_children
5168 NAME: url_rewrite_extras
5169 TYPE: TokenOrQuotedString
5170 LOC: Config.redirector_extras
5171 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
5173 Specifies a string to be append to request line format for the
5174 rewriter helper. "Quoted" format values may contain spaces and
5175 logformat %macros. In theory, any logformat %macro can be used.
5176 In practice, a %macro expands as a dash (-) if the helper request is
5177 sent before the required macro information is available to Squid.
5180 NAME: url_rewrite_timeout
5181 TYPE: UrlHelperTimeout
5182 LOC: Config.onUrlRewriteTimeout
5184 DEFAULT_DOC: Squid waits for the helper response forever
5186 Squid times active requests to redirector. The timeout value and Squid
5187 reaction to a timed out request are configurable using the following
5190 url_rewrite_timeout timeout time-units on_timeout=<action> [response=<quoted-response>]
5192 supported timeout actions:
5193 fail Squid return a ERR_GATEWAY_FAILURE error page
5195 bypass Do not re-write the URL
5197 retry Send the lookup to the helper again
5199 use_configured_response
5200 Use the <quoted-response> as helper response
5204 OPTIONS FOR STORE ID
5205 -----------------------------------------------------------------------------
5208 NAME: store_id_program storeurl_rewrite_program
5210 LOC: Config.Program.store_id
5213 Specify the location of the executable StoreID helper to use.
5214 Since they can perform almost any function there isn't one included.
5216 For each requested URL, the helper will receive one line with the format
5218 [channel-ID <SP>] URL [<SP> extras]<NL>
5221 After processing the request the helper must reply using the following format:
5223 [channel-ID <SP>] result [<SP> kv-pairs]
5225 The result code can be:
5228 Use the StoreID supplied in 'store-id='.
5231 The default is to use HTTP request URL as the store ID.
5234 An internal error occured in the helper, preventing
5235 a result being identified.
5237 In addition to the above kv-pairs Squid also understands the following
5238 optional kv-pairs received from URL rewriters:
5240 Associates a TAG with the client TCP connection.
5241 Please see url_rewrite_program related documentation for this
5244 Helper programs should be prepared to receive and possibly ignore
5245 additional whitespace-separated tokens on each input line.
5247 When using the concurrency= option the protocol is changed by
5248 introducing a query channel tag in front of the request/response.
5249 The query channel tag is a number between 0 and concurrency-1.
5250 This value must be echoed back unchanged to Squid as the first part
5251 of the response relating to its request.
5253 NOTE: when using StoreID refresh_pattern will apply to the StoreID
5254 returned from the helper and not the URL.
5256 WARNING: Wrong StoreID value returned by a careless helper may result
5257 in the wrong cached response returned to the user.
5259 By default, a StoreID helper is not used.
5262 NAME: store_id_extras
5263 TYPE: TokenOrQuotedString
5264 LOC: Config.storeId_extras
5265 DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp"
5267 Specifies a string to be append to request line format for the
5268 StoreId helper. "Quoted" format values may contain spaces and
5269 logformat %macros. In theory, any logformat %macro can be used.
5270 In practice, a %macro expands as a dash (-) if the helper request is
5271 sent before the required macro information is available to Squid.
5274 NAME: store_id_children storeurl_rewrite_children
5275 TYPE: HelperChildConfig
5276 DEFAULT: 20 startup=0 idle=1 concurrency=0
5277 LOC: Config.storeIdChildren
5279 The maximum number of StoreID helper processes to spawn. If you limit
5280 it too few Squid will have to wait for them to process a backlog of
5281 requests, slowing it down. If you allow too many they will use RAM
5282 and other system resources noticably.
5284 The startup= and idle= options allow some measure of skew in your
5289 Sets a minimum of how many processes are to be spawned when Squid
5290 starts or reconfigures. When set to zero the first request will
5291 cause spawning of the first child process to handle it.
5293 Starting too few will cause an initial slowdown in traffic as Squid
5294 attempts to simultaneously spawn enough processes to cope.
5298 Sets a minimum of how many processes Squid is to try and keep available
5299 at all times. When traffic begins to rise above what the existing
5300 processes can handle this many more will be spawned up to the maximum
5301 configured. A minimum setting of 1 is required.
5305 The number of requests each storeID helper can handle in
5306 parallel. Defaults to 0 which indicates the helper
5307 is a old-style single threaded program.
5309 When this directive is set to a value >= 1 then the protocol
5310 used to communicate with the helper is modified to include
5311 an ID in front of the request/response. The ID from the request
5312 must be echoed back with the response to that request.
5316 Sets the maximum number of queued requests.
5317 If the queued requests exceed queue size and store_id_bypass
5318 configuration option is set, then storeID helper is bypassed. Otherwise,
5319 if overloading persists squid may abort its operation.
5320 The default value is set to 2*numberofchildren.
5323 NAME: store_id_access storeurl_rewrite_access
5326 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
5327 LOC: Config.accessList.store_id
5329 If defined, this access list specifies which requests are
5330 sent to the StoreID processes. By default all requests
5333 This clause supports both fast and slow acl types.
5334 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5337 NAME: store_id_bypass storeurl_rewrite_bypass
5339 LOC: Config.onoff.store_id_bypass
5342 When this is 'on', a request will not go through the
5343 helper if all helpers are busy. If this is 'off'
5344 and the helper queue grows too large, Squid will exit
5345 with a FATAL error and ask you to increase the number of
5346 helpers. You should only enable this if the helperss
5347 are not critical to your caching system. If you use
5348 helpers for critical caching components, and you enable this
5349 option, users may not get objects from cache.
5350 This options sets default queue-size option of the store_id_children
5355 OPTIONS FOR TUNING THE CACHE
5356 -----------------------------------------------------------------------------
5359 NAME: cache no_cache
5362 DEFAULT_DOC: By default, this directive is unused and has no effect.
5363 LOC: Config.accessList.noCache
5365 Requests denied by this directive will not be served from the cache
5366 and their responses will not be stored in the cache. This directive
5367 has no effect on other transactions and on already cached responses.
5369 This clause supports both fast and slow acl types.
5370 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5372 This and the two other similar caching directives listed below are
5373 checked at different transaction processing stages, have different
5374 access to response information, affect different cache operations,
5375 and differ in slow ACLs support:
5377 * cache: Checked before Squid makes a hit/miss determination.
5378 No access to reply information!
5379 Denies both serving a hit and storing a miss.
5380 Supports both fast and slow ACLs.
5381 * send_hit: Checked after a hit was detected.
5382 Has access to reply (hit) information.
5383 Denies serving a hit only.
5384 Supports fast ACLs only.
5385 * store_miss: Checked before storing a cachable miss.
5386 Has access to reply (miss) information.
5387 Denies storing a miss only.
5388 Supports fast ACLs only.
5390 If you are not sure which of the three directives to use, apply the
5391 following decision logic:
5393 * If your ACL(s) are of slow type _and_ need response info, redesign.
5394 Squid does not support that particular combination at this time.
5396 * If your directive ACL(s) are of slow type, use "cache"; and/or
5397 * if your directive ACL(s) need no response info, use "cache".
5399 * If you do not want the response cached, use store_miss; and/or
5400 * if you do not want a hit on a cached response, use send_hit.
5406 DEFAULT_DOC: By default, this directive is unused and has no effect.
5407 LOC: Config.accessList.sendHit
5409 Responses denied by this directive will not be served from the cache
5410 (but may still be cached, see store_miss). This directive has no
5411 effect on the responses it allows and on the cached objects.
5413 Please see the "cache" directive for a summary of differences among
5414 store_miss, send_hit, and cache directives.
5416 Unlike the "cache" directive, send_hit only supports fast acl
5417 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5421 # apply custom Store ID mapping to some URLs
5422 acl MapMe dstdomain .c.example.com
5423 store_id_program ...
5424 store_id_access allow MapMe
5426 # but prevent caching of special responses
5427 # such as 302 redirects that cause StoreID loops
5428 acl Ordinary http_status 200-299
5429 store_miss deny MapMe !Ordinary
5431 # and do not serve any previously stored special responses
5432 # from the cache (in case they were already cached before
5433 # the above store_miss rule was in effect).
5434 send_hit deny MapMe !Ordinary
5440 DEFAULT_DOC: By default, this directive is unused and has no effect.
5441 LOC: Config.accessList.storeMiss
5443 Responses denied by this directive will not be cached (but may still
5444 be served from the cache, see send_hit). This directive has no
5445 effect on the responses it allows and on the already cached responses.
5447 Please see the "cache" directive for a summary of differences among
5448 store_miss, send_hit, and cache directives. See the
5449 send_hit directive for a usage example.
5451 Unlike the "cache" directive, store_miss only supports fast acl
5452 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5458 LOC: Config.maxStale
5461 This option puts an upper limit on how stale content Squid
5462 will serve from the cache if cache validation fails.
5463 Can be overriden by the refresh_pattern max-stale option.
5466 NAME: refresh_pattern
5467 TYPE: refreshpattern
5471 usage: refresh_pattern [-i] regex min percent max [options]
5473 By default, regular expressions are CASE-SENSITIVE. To make
5474 them case-insensitive, use the -i option.
5476 'Min' is the time (in minutes) an object without an explicit
5477 expiry time should be considered fresh. The recommended
5478 value is 0, any higher values may cause dynamic applications
5479 to be erroneously cached unless the application designer
5480 has taken the appropriate actions.
5482 'Percent' is a percentage of the objects age (time since last
5483 modification age) an object without explicit expiry time
5484 will be considered fresh.
5486 'Max' is an upper limit on how long objects without an explicit
5487 expiry time will be considered fresh.
5489 options: override-expire
5499 override-expire enforces min age even if the server
5500 sent an explicit expiry time (e.g., with the
5501 Expires: header or Cache-Control: max-age). Doing this
5502 VIOLATES the HTTP standard. Enabling this feature
5503 could make you liable for problems which it causes.
5505 Note: override-expire does not enforce staleness - it only extends
5506 freshness / min. If the server returns a Expires time which
5507 is longer than your max time, Squid will still consider
5508 the object fresh for that period of time.
5510 override-lastmod enforces min age even on objects
5511 that were modified recently.
5513 reload-into-ims changes a client no-cache or ``reload''
5514 request for a cached entry into a conditional request using
5515 If-Modified-Since and/or If-None-Match headers, provided the
5516 cached entry has a Last-Modified and/or a strong ETag header.
5517 Doing this VIOLATES the HTTP standard. Enabling this feature
5518 could make you liable for problems which it causes.
5520 ignore-reload ignores a client no-cache or ``reload''
5521 header. Doing this VIOLATES the HTTP standard. Enabling
5522 this feature could make you liable for problems which
5525 ignore-no-store ignores any ``Cache-control: no-store''
5526 headers received from a server. Doing this VIOLATES
5527 the HTTP standard. Enabling this feature could make you
5528 liable for problems which it causes.
5530 ignore-private ignores any ``Cache-control: private''
5531 headers received from a server. Doing this VIOLATES
5532 the HTTP standard. Enabling this feature could make you
5533 liable for problems which it causes.
5535 refresh-ims causes squid to contact the origin server
5536 when a client issues an If-Modified-Since request. This
5537 ensures that the client will receive an updated version
5538 if one is available.
5540 store-stale stores responses even if they don't have explicit
5541 freshness or a validator (i.e., Last-Modified or an ETag)
5542 present, or if they're already stale. By default, Squid will
5543 not cache such responses because they usually can't be
5544 reused. Note that such responses will be stale by default.
5546 max-stale=NN provide a maximum staleness factor. Squid won't
5547 serve objects more stale than this even if it failed to
5548 validate the object. Default: use the max_stale global limit.
5550 Basically a cached object is:
5552 FRESH if expire > now, else STALE
5554 FRESH if lm-factor < percent, else STALE
5558 The refresh_pattern lines are checked in the order listed here.
5559 The first entry which matches is used. If none of the entries
5560 match the default will be used.
5562 Note, you must uncomment all the default lines if you want
5563 to change one. The default setting is only active if none is
5569 # Add any of your own refresh_pattern entries above these.
5571 refresh_pattern ^ftp: 1440 20% 10080
5572 refresh_pattern ^gopher: 1440 0% 1440
5573 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
5574 refresh_pattern . 0 20% 4320
5578 NAME: quick_abort_min
5582 LOC: Config.quickAbort.min
5585 NAME: quick_abort_max
5589 LOC: Config.quickAbort.max
5592 NAME: quick_abort_pct
5596 LOC: Config.quickAbort.pct
5598 The cache by default continues downloading aborted requests
5599 which are almost completed (less than 16 KB remaining). This
5600 may be undesirable on slow (e.g. SLIP) links and/or very busy
5601 caches. Impatient users may tie up file descriptors and
5602 bandwidth by repeatedly requesting and immediately aborting
5605 When the user aborts a request, Squid will check the
5606 quick_abort values to the amount of data transferred until
5609 If the transfer has less than 'quick_abort_min' KB remaining,
5610 it will finish the retrieval.
5612 If the transfer has more than 'quick_abort_max' KB remaining,
5613 it will abort the retrieval.
5615 If more than 'quick_abort_pct' of the transfer has completed,
5616 it will finish the retrieval.
5618 If you do not want any retrieval to continue after the client
5619 has aborted, set both 'quick_abort_min' and 'quick_abort_max'
5622 If you want retrievals to always continue if they are being
5623 cached set 'quick_abort_min' to '-1 KB'.
5626 NAME: read_ahead_gap
5627 COMMENT: buffer-size
5629 LOC: Config.readAheadGap
5632 The amount of data the cache will buffer ahead of what has been
5633 sent to the client when retrieving an object from another server.
5637 IFDEF: USE_HTTP_VIOLATIONS
5640 LOC: Config.negativeTtl
5643 Set the Default Time-to-Live (TTL) for failed requests.
5644 Certain types of failures (such as "connection refused" and
5645 "404 Not Found") are able to be negatively-cached for a short time.
5646 Modern web servers should provide Expires: header, however if they
5647 do not this can provide a minimum TTL.
5648 The default is not to cache errors with unknown expiry details.
5650 Note that this is different from negative caching of DNS lookups.
5652 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5653 this feature could make you liable for problems which it
5657 NAME: positive_dns_ttl
5660 LOC: Config.positiveDnsTtl
5663 Upper limit on how long Squid will cache positive DNS responses.
5664 Default is 6 hours (360 minutes). This directive must be set
5665 larger than negative_dns_ttl.
5668 NAME: negative_dns_ttl
5671 LOC: Config.negativeDnsTtl
5674 Time-to-Live (TTL) for negative caching of failed DNS lookups.
5675 This also sets the lower cache limit on positive lookups.
5676 Minimum value is 1 second, and it is not recommendable to go
5677 much below 10 seconds.
5680 NAME: range_offset_limit
5681 COMMENT: size [acl acl...]
5683 LOC: Config.rangeOffsetLimit
5686 usage: (size) [units] [[!]aclname]
5688 Sets an upper limit on how far (number of bytes) into the file
5689 a Range request may be to cause Squid to prefetch the whole file.
5690 If beyond this limit, Squid forwards the Range request as it is and
5691 the result is NOT cached.
5693 This is to stop a far ahead range request (lets say start at 17MB)
5694 from making Squid fetch the whole object up to that point before
5695 sending anything to the client.
5697 Multiple range_offset_limit lines may be specified, and they will
5698 be searched from top to bottom on each request until a match is found.
5699 The first match found will be used. If no line matches a request, the
5700 default limit of 0 bytes will be used.
5702 'size' is the limit specified as a number of units.
5704 'units' specifies whether to use bytes, KB, MB, etc.
5705 If no units are specified bytes are assumed.
5707 A size of 0 causes Squid to never fetch more than the
5708 client requested. (default)
5710 A size of 'none' causes Squid to always fetch the object from the
5711 beginning so it may cache the result. (2.0 style)
5713 'aclname' is the name of a defined ACL.
5715 NP: Using 'none' as the byte value here will override any quick_abort settings
5716 that may otherwise apply to the range request. The range request will
5717 be fully fetched from start to finish regardless of the client
5718 actions. This affects bandwidth usage.
5721 NAME: minimum_expiry_time
5724 LOC: Config.minimum_expiry_time
5727 The minimum caching time according to (Expires - Date)
5728 headers Squid honors if the object can't be revalidated.
5729 The default is 60 seconds.
5731 In reverse proxy environments it might be desirable to honor
5732 shorter object lifetimes. It is most likely better to make
5733 your server return a meaningful Last-Modified header however.
5735 In ESI environments where page fragments often have short
5736 lifetimes, this will often be best set to 0.
5739 NAME: store_avg_object_size
5743 LOC: Config.Store.avgObjectSize
5745 Average object size, used to estimate number of objects your
5746 cache can hold. The default is 13 KB.
5748 This is used to pre-seed the cache index memory allocation to
5749 reduce expensive reallocate operations while handling clients
5750 traffic. Too-large values may result in memory allocation during
5751 peak traffic, too-small values will result in wasted memory.
5753 Check the cache manager 'info' report metrics for the real
5754 object sizes seen by your Squid before tuning this.
5757 NAME: store_objects_per_bucket
5760 LOC: Config.Store.objectsPerBucket
5762 Target number of objects per bucket in the store hash table.
5763 Lowering this value increases the total number of buckets and
5764 also the storage maintenance rate. The default is 20.
5769 -----------------------------------------------------------------------------
5772 NAME: request_header_max_size
5776 LOC: Config.maxRequestHeaderSize
5778 This specifies the maximum size for HTTP headers in a request.
5779 Request headers are usually relatively small (about 512 bytes).
5780 Placing a limit on the request header size will catch certain
5781 bugs (for example with persistent connections) and possibly
5782 buffer-overflow or denial-of-service attacks.
5785 NAME: reply_header_max_size
5789 LOC: Config.maxReplyHeaderSize
5791 This specifies the maximum size for HTTP headers in a reply.
5792 Reply headers are usually relatively small (about 512 bytes).
5793 Placing a limit on the reply header size will catch certain
5794 bugs (for example with persistent connections) and possibly
5795 buffer-overflow or denial-of-service attacks.
5798 NAME: request_body_max_size
5802 DEFAULT_DOC: No limit.
5803 LOC: Config.maxRequestBodySize
5805 This specifies the maximum size for an HTTP request body.
5806 In other words, the maximum size of a PUT/POST request.
5807 A user who attempts to send a request with a body larger
5808 than this limit receives an "Invalid Request" error message.
5809 If you set this parameter to a zero (the default), there will
5810 be no limit imposed.
5812 See also client_request_buffer_max_size for an alternative
5813 limitation on client uploads which can be configured.
5816 NAME: client_request_buffer_max_size
5820 LOC: Config.maxRequestBufferSize
5822 This specifies the maximum buffer size of a client request.
5823 It prevents squid eating too much memory when somebody uploads
5828 IFDEF: USE_HTTP_VIOLATIONS
5831 DEFAULT_DOC: Obey RFC 2616.
5832 LOC: Config.accessList.brokenPosts
5834 A list of ACL elements which, if matched, causes Squid to send
5835 an extra CRLF pair after the body of a PUT/POST request.
5837 Some HTTP servers has broken implementations of PUT/POST,
5838 and rely on an extra CRLF pair sent by some WWW clients.
5840 Quote from RFC2616 section 4.1 on this matter:
5842 Note: certain buggy HTTP/1.0 client implementations generate an
5843 extra CRLF's after a POST request. To restate what is explicitly
5844 forbidden by the BNF, an HTTP/1.1 client must not preface or follow
5845 a request with an extra CRLF.
5847 This clause only supports fast acl types.
5848 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
5851 acl buggy_server url_regex ^http://....
5852 broken_posts allow buggy_server
5855 NAME: adaptation_uses_indirect_client icap_uses_indirect_client
5858 IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION
5860 LOC: Adaptation::Config::use_indirect_client
5862 Controls whether the indirect client IP address (instead of the direct
5863 client IP address) is passed to adaptation services.
5865 See also: follow_x_forwarded_for adaptation_send_client_ip
5869 IFDEF: USE_HTTP_VIOLATIONS
5873 LOC: Config.onoff.via
5875 If set (default), Squid will include a Via header in requests and
5876 replies as required by RFC2616.
5882 LOC: Config.onoff.ie_refresh
5885 Microsoft Internet Explorer up until version 5.5 Service
5886 Pack 1 has an issue with transparent proxies, wherein it
5887 is impossible to force a refresh. Turning this on provides
5888 a partial fix to the problem, by causing all IMS-REFRESH
5889 requests from older IE versions to check the origin server
5890 for fresh content. This reduces hit ratio by some amount
5891 (~10% in my experience), but allows users to actually get
5892 fresh content when they want it. Note because Squid
5893 cannot tell if the user is using 5.5 or 5.5SP1, the behavior
5894 of 5.5 is unchanged from old versions of Squid (i.e. a
5895 forced refresh is impossible). Newer versions of IE will,
5896 hopefully, continue to have the new behavior and will be
5897 handled based on that assumption. This option defaults to
5898 the old Squid behavior, which is better for hit ratios but
5899 worse for clients using IE, if they need to be able to
5900 force fresh content.
5903 NAME: vary_ignore_expire
5906 LOC: Config.onoff.vary_ignore_expire
5909 Many HTTP servers supporting Vary gives such objects
5910 immediate expiry time with no cache-control header
5911 when requested by a HTTP/1.0 client. This option
5912 enables Squid to ignore such expiry times until
5913 HTTP/1.1 is fully implemented.
5915 WARNING: If turned on this may eventually cause some
5916 varying objects not intended for caching to get cached.
5919 NAME: request_entities
5921 LOC: Config.onoff.request_entities
5924 Squid defaults to deny GET and HEAD requests with request entities,
5925 as the meaning of such requests are undefined in the HTTP standard
5926 even if not explicitly forbidden.
5928 Set this directive to on if you have clients which insists
5929 on sending request entities in GET or HEAD requests. But be warned
5930 that there is server software (both proxies and web servers) which
5931 can fail to properly process this kind of request which may make you
5932 vulnerable to cache pollution attacks if enabled.
5935 NAME: request_header_access
5936 IFDEF: USE_HTTP_VIOLATIONS
5937 TYPE: http_header_access
5938 LOC: Config.request_header_access
5940 DEFAULT_DOC: No limits.
5942 Usage: request_header_access header_name allow|deny [!]aclname ...
5944 WARNING: Doing this VIOLATES the HTTP standard. Enabling
5945 this feature could make you liable for problems which it
5948 This option replaces the old 'anonymize_headers' and the
5949 older 'http_anonymizer' option with something that is much
5950 more configurable. A list of ACLs for each header name allows
5951 removal of specific header fields under specific conditions.
5953 This option only applies to outgoing HTTP request headers (i.e.,
5954 headers sent by Squid to the next HTTP hop such as a cache peer
5955 or an origin server). The option has no effect during cache hit
5956 detection. The equivalent adaptation vectoring point in ICAP
5957 terminology is post-cache REQMOD.
5959 The option is applied to individual outgoing request header
5960 fields. For each request header field F, Squid uses the first
5961 qualifying sets of request_header_access rules:
5963 1. Rules with header_name equal to F's name.
5964 2. Rules with header_name 'Other', provided F's name is not
5965 on the hard-coded list of commonly used HTTP header names.
5966 3. Rules with header_name 'All'.
5968 Within that qualifying rule set, rule ACLs are checked as usual.
5969 If ACLs of an "allow" rule match, the header field is allowed to
5970 go through as is. If ACLs of a "deny" rule match, the header is
5971 removed and request_header_replace is then checked to identify
5972 if the removed header has a replacement. If no rules within the
5973 set have matching ACLs, the header field is left as is.
5975 For example, to achieve the same behavior as the old
5976 'http_anonymizer standard' option, you should use:
5978 request_header_access From deny all
5979 request_header_access Referer deny all
5980 request_header_access User-Agent deny all
5982 Or, to reproduce the old 'http_anonymizer paranoid' feature
5985 request_header_access Authorization allow all
5986 request_header_access Proxy-Authorization allow all
5987 request_header_access Cache-Control allow all
5988 request_header_access Content-Length allow all
5989 request_header_access Content-Type allow all
5990 request_header_access Date allow all
5991 request_header_access Host allow all
5992 request_header_access If-Modified-Since allow all
5993 request_header_access Pragma allow all
5994 request_header_access Accept allow all
5995 request_header_access Accept-Charset allow all
5996 request_header_access Accept-Encoding allow all
5997 request_header_access Accept-Language allow all
5998 request_header_access Connection allow all
5999 request_header_access All deny all
6001 HTTP reply headers are controlled with the reply_header_access directive.
6003 By default, all headers are allowed (no anonymizing is performed).
6006 NAME: reply_header_access
6007 IFDEF: USE_HTTP_VIOLATIONS
6008 TYPE: http_header_access
6009 LOC: Config.reply_header_access
6011 DEFAULT_DOC: No limits.
6013 Usage: reply_header_access header_name allow|deny [!]aclname ...
6015 WARNING: Doing this VIOLATES the HTTP standard. Enabling
6016 this feature could make you liable for problems which it
6019 This option only applies to reply headers, i.e., from the
6020 server to the client.
6022 This is the same as request_header_access, but in the other
6023 direction. Please see request_header_access for detailed
6026 For example, to achieve the same behavior as the old
6027 'http_anonymizer standard' option, you should use:
6029 reply_header_access Server deny all
6030 reply_header_access WWW-Authenticate deny all
6031 reply_header_access Link deny all
6033 Or, to reproduce the old 'http_anonymizer paranoid' feature
6036 reply_header_access Allow allow all
6037 reply_header_access WWW-Authenticate allow all
6038 reply_header_access Proxy-Authenticate allow all
6039 reply_header_access Cache-Control allow all
6040 reply_header_access Content-Encoding allow all
6041 reply_header_access Content-Length allow all
6042 reply_header_access Content-Type allow all
6043 reply_header_access Date allow all
6044 reply_header_access Expires allow all
6045 reply_header_access Last-Modified allow all
6046 reply_header_access Location allow all
6047 reply_header_access Pragma allow all
6048 reply_header_access Content-Language allow all
6049 reply_header_access Retry-After allow all
6050 reply_header_access Title allow all
6051 reply_header_access Content-Disposition allow all
6052 reply_header_access Connection allow all
6053 reply_header_access All deny all
6055 HTTP request headers are controlled with the request_header_access directive.
6057 By default, all headers are allowed (no anonymizing is
6061 NAME: request_header_replace header_replace
6062 IFDEF: USE_HTTP_VIOLATIONS
6063 TYPE: http_header_replace
6064 LOC: Config.request_header_access
6067 Usage: request_header_replace header_name message
6068 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
6070 This option allows you to change the contents of headers
6071 denied with request_header_access above, by replacing them
6072 with some fixed string.
6074 This only applies to request headers, not reply headers.
6076 By default, headers are removed if denied.
6079 NAME: reply_header_replace
6080 IFDEF: USE_HTTP_VIOLATIONS
6081 TYPE: http_header_replace
6082 LOC: Config.reply_header_access
6085 Usage: reply_header_replace header_name message
6086 Example: reply_header_replace Server Foo/1.0
6088 This option allows you to change the contents of headers
6089 denied with reply_header_access above, by replacing them
6090 with some fixed string.
6092 This only applies to reply headers, not request headers.
6094 By default, headers are removed if denied.
6097 NAME: request_header_add
6098 TYPE: HeaderWithAclList
6099 LOC: Config.request_header_add
6102 Usage: request_header_add field-name field-value acl1 [acl2] ...
6103 Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
6105 This option adds header fields to outgoing HTTP requests (i.e.,
6106 request headers sent by Squid to the next HTTP hop such as a
6107 cache peer or an origin server). The option has no effect during
6108 cache hit detection. The equivalent adaptation vectoring point
6109 in ICAP terminology is post-cache REQMOD.
6111 Field-name is a token specifying an HTTP header name. If a
6112 standard HTTP header name is used, Squid does not check whether
6113 the new header conflicts with any existing headers or violates
6114 HTTP rules. If the request to be modified already contains a
6115 field with the same name, the old field is preserved but the
6116 header field values are not merged.
6118 Field-value is either a token or a quoted string. If quoted
6119 string format is used, then the surrounding quotes are removed
6120 while escape sequences and %macros are processed.
6122 In theory, all of the logformat codes can be used as %macros.
6123 However, unlike logging (which happens at the very end of
6124 transaction lifetime), the transaction may not yet have enough
6125 information to expand a macro when the new header value is needed.
6126 And some information may already be available to Squid but not yet
6127 committed where the macro expansion code can access it (report
6128 such instances!). The macro will be expanded into a single dash
6129 ('-') in such cases. Not all macros have been tested.
6131 One or more Squid ACLs may be specified to restrict header
6132 injection to matching requests. As always in squid.conf, all
6133 ACLs in an option ACL list must be satisfied for the insertion
6134 to happen. The request_header_add option supports fast ACLs
6143 This option used to log custom information about the master
6144 transaction. For example, an admin may configure Squid to log
6145 which "user group" the transaction belongs to, where "user group"
6146 will be determined based on a set of ACLs and not [just]
6147 authentication information.
6148 Values of key/value pairs can be logged using %{key}note macros:
6150 note key value acl ...
6151 logformat myFormat ... %{key}note ...
6154 NAME: relaxed_header_parser
6155 COMMENT: on|off|warn
6157 LOC: Config.onoff.relaxed_header_parser
6160 In the default "on" setting Squid accepts certain forms
6161 of non-compliant HTTP messages where it is unambiguous
6162 what the sending application intended even if the message
6163 is not correctly formatted. The messages is then normalized
6164 to the correct form when forwarded by Squid.
6166 If set to "warn" then a warning will be emitted in cache.log
6167 each time such HTTP error is encountered.
6169 If set to "off" then such HTTP errors will cause the request
6170 or response to be rejected.
6173 NAME: collapsed_forwarding
6176 LOC: Config.onoff.collapsed_forwarding
6179 This option controls whether Squid is allowed to merge multiple
6180 potentially cachable requests for the same URI before Squid knows
6181 whether the response is going to be cachable.
6183 This feature is disabled by default: Enabling collapsed forwarding
6184 needlessly delays forwarding requests that look cachable (when they are
6185 collapsed) but then need to be forwarded individually anyway because
6186 they end up being for uncachable content. However, in some cases, such
6187 as accelleration of highly cachable content with periodic or groupped
6188 expiration times, the gains from collapsing [large volumes of
6189 simultenous refresh requests] outweigh losses from such delays.
6194 -----------------------------------------------------------------------------
6197 NAME: forward_timeout
6200 LOC: Config.Timeout.forward
6203 This parameter specifies how long Squid should at most attempt in
6204 finding a forwarding path for the request before giving up.
6207 NAME: connect_timeout
6210 LOC: Config.Timeout.connect
6213 This parameter specifies how long to wait for the TCP connect to
6214 the requested server or peer to complete before Squid should
6215 attempt to find another path where to forward the request.
6218 NAME: peer_connect_timeout
6221 LOC: Config.Timeout.peer_connect
6224 This parameter specifies how long to wait for a pending TCP
6225 connection to a peer cache. The default is 30 seconds. You
6226 may also set different timeout values for individual neighbors
6227 with the 'connect-timeout' option on a 'cache_peer' line.
6233 LOC: Config.Timeout.read
6236 Applied on peer server connections.
6238 After each successful read(), the timeout will be extended by this
6239 amount. If no data is read again after this amount of time,
6240 the request is aborted and logged with ERR_READ_TIMEOUT.
6242 The default is 15 minutes.
6248 LOC: Config.Timeout.write
6251 This timeout is tracked for all connections that have data
6252 available for writing and are waiting for the socket to become
6253 ready. After each successful write, the timeout is extended by
6254 the configured amount. If Squid has data to write but the
6255 connection is not ready for the configured duration, the
6256 transaction associated with the connection is terminated. The
6257 default is 15 minutes.
6260 NAME: request_timeout
6262 LOC: Config.Timeout.request
6265 How long to wait for complete HTTP request headers after initial
6266 connection establishment.
6269 NAME: request_start_timeout
6271 LOC: Config.Timeout.request_start_timeout
6274 How long to wait for the first request byte after initial
6275 connection establishment.
6278 NAME: client_idle_pconn_timeout persistent_request_timeout
6280 LOC: Config.Timeout.clientIdlePconn
6283 How long to wait for the next HTTP request on a persistent
6284 client connection after the previous request completes.
6287 NAME: ftp_client_idle_timeout
6289 LOC: Config.Timeout.ftpClientIdle
6292 How long to wait for an FTP request on a connection to Squid ftp_port.
6293 Many FTP clients do not deal with idle connection closures well,
6294 necessitating a longer default timeout than client_idle_pconn_timeout
6295 used for incoming HTTP requests.
6298 NAME: client_lifetime
6301 LOC: Config.Timeout.lifetime
6304 The maximum amount of time a client (browser) is allowed to
6305 remain connected to the cache process. This protects the Cache
6306 from having a lot of sockets (and hence file descriptors) tied up
6307 in a CLOSE_WAIT state from remote clients that go away without
6308 properly shutting down (either because of a network failure or
6309 because of a poor client implementation). The default is one
6312 NOTE: The default value is intended to be much larger than any
6313 client would ever need to be connected to your cache. You
6314 should probably change client_lifetime only as a last resort.
6315 If you seem to have many client connections tying up
6316 filedescriptors, we recommend first tuning the read_timeout,
6317 request_timeout, persistent_request_timeout and quick_abort values.
6320 NAME: pconn_lifetime
6323 LOC: Config.Timeout.pconnLifetime
6326 Desired maximum lifetime of a persistent connection.
6327 When set, Squid will close a now-idle persistent connection that
6328 exceeded configured lifetime instead of moving the connection into
6329 the idle connection pool (or equivalent). No effect on ongoing/active
6330 transactions. Connection lifetime is the time period from the
6331 connection acceptance or opening time until "now".
6333 This limit is useful in environments with long-lived connections
6334 where Squid configuration or environmental factors change during a
6335 single connection lifetime. If unrestricted, some connections may
6336 last for hours and even days, ignoring those changes that should
6337 have affected their behavior or their existence.
6339 Currently, a new lifetime value supplied via Squid reconfiguration
6340 has no effect on already idle connections unless they become busy.
6342 When set to '0' this limit is not used.
6345 NAME: half_closed_clients
6347 LOC: Config.onoff.half_closed_clients
6350 Some clients may shutdown the sending side of their TCP
6351 connections, while leaving their receiving sides open. Sometimes,
6352 Squid can not tell the difference between a half-closed and a
6353 fully-closed TCP connection.
6355 By default, Squid will immediately close client connections when
6356 read(2) returns "no more data to read."
6358 Change this option to 'on' and Squid will keep open connections
6359 until a read(2) or write(2) on the socket returns an error.
6360 This may show some benefits for reverse proxies. But if not
6361 it is recommended to leave OFF.
6364 NAME: server_idle_pconn_timeout pconn_timeout
6366 LOC: Config.Timeout.serverIdlePconn
6369 Timeout for idle persistent connections to servers and other
6376 LOC: Ident::TheConfig.timeout
6379 Maximum time to wait for IDENT lookups to complete.
6381 If this is too high, and you enabled IDENT lookups from untrusted
6382 users, you might be susceptible to denial-of-service by having
6383 many ident requests going at once.
6386 NAME: shutdown_lifetime
6389 LOC: Config.shutdownLifetime
6392 When SIGTERM or SIGHUP is received, the cache is put into
6393 "shutdown pending" mode until all active sockets are closed.
6394 This value is the lifetime to set for all open descriptors
6395 during shutdown mode. Any active clients after this many
6396 seconds will receive a 'timeout' message.
6400 ADMINISTRATIVE PARAMETERS
6401 -----------------------------------------------------------------------------
6407 LOC: Config.adminEmail
6409 Email-address of local cache manager who will receive
6410 mail if the cache dies. The default is "webmaster".
6416 LOC: Config.EmailFrom
6418 From: email-address for mail sent when the cache dies.
6419 The default is to use 'squid@unique_hostname'.
6421 See also: unique_hostname directive.
6427 LOC: Config.EmailProgram
6429 Email program used to send mail if the cache dies.
6430 The default is "mail". The specified program must comply
6431 with the standard Unix mail syntax:
6432 mail-program recipient < mailfile
6434 Optional command line options can be specified.
6437 NAME: cache_effective_user
6439 DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
6440 LOC: Config.effectiveUser
6442 If you start Squid as root, it will change its effective/real
6443 UID/GID to the user specified below. The default is to change
6444 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
6445 see also; cache_effective_group
6448 NAME: cache_effective_group
6451 DEFAULT_DOC: Use system group memberships of the cache_effective_user account
6452 LOC: Config.effectiveGroup
6454 Squid sets the GID to the effective user's default group ID
6455 (taken from the password file) and supplementary group list
6456 from the groups membership.
6458 If you want Squid to run with a specific GID regardless of
6459 the group memberships of the effective user then set this
6460 to the group (or GID) you want Squid to run as. When set
6461 all other group privileges of the effective user are ignored
6462 and only this GID is effective. If Squid is not started as
6463 root the user starting Squid MUST be member of the specified
6466 This option is not recommended by the Squid Team.
6467 Our preference is for administrators to configure a secure
6468 user account for squid with UID/GID matching system policies.
6471 NAME: httpd_suppress_version_string
6475 LOC: Config.onoff.httpd_suppress_version_string
6477 Suppress Squid version string info in HTTP headers and HTML error pages.
6480 NAME: visible_hostname
6482 LOC: Config.visibleHostname
6484 DEFAULT_DOC: Automatically detect the system host name
6486 If you want to present a special hostname in error messages, etc,
6487 define this. Otherwise, the return value of gethostname()
6488 will be used. If you have multiple caches in a cluster and
6489 get errors about IP-forwarding you must set them to have individual
6490 names with this setting.
6493 NAME: unique_hostname
6495 LOC: Config.uniqueHostname
6497 DEFAULT_DOC: Copy the value from visible_hostname
6499 If you want to have multiple machines with the same
6500 'visible_hostname' you must give each machine a different
6501 'unique_hostname' so forwarding loops can be detected.
6504 NAME: hostname_aliases
6506 LOC: Config.hostnameAliases
6509 A list of other DNS names your cache has.
6517 Minimum umask which should be enforced while the proxy
6518 is running, in addition to the umask set at startup.
6520 For a traditional octal representation of umasks, start
6525 OPTIONS FOR THE CACHE REGISTRATION SERVICE
6526 -----------------------------------------------------------------------------
6528 This section contains parameters for the (optional) cache
6529 announcement service. This service is provided to help
6530 cache administrators locate one another in order to join or
6531 create cache hierarchies.
6533 An 'announcement' message is sent (via UDP) to the registration
6534 service by Squid. By default, the announcement message is NOT
6535 SENT unless you enable it with 'announce_period' below.
6537 The announcement message includes your hostname, plus the
6538 following information from this configuration file:
6544 All current information is processed regularly and made
6545 available on the Web at http://www.ircache.net/Cache/Tracker/.
6548 NAME: announce_period
6550 LOC: Config.Announce.period
6552 DEFAULT_DOC: Announcement messages disabled.
6554 This is how frequently to send cache announcements.
6556 To enable announcing your cache, just set an announce period.
6559 announce_period 1 day
6564 DEFAULT: tracker.ircache.net
6565 LOC: Config.Announce.host
6567 Set the hostname where announce registration messages will be sent.
6569 See also announce_port and announce_file
6575 LOC: Config.Announce.file
6577 The contents of this file will be included in the announce
6578 registration messages.
6584 LOC: Config.Announce.port
6586 Set the port where announce registration messages will be sent.
6588 See also announce_host and announce_file
6592 HTTPD-ACCELERATOR OPTIONS
6593 -----------------------------------------------------------------------------
6596 NAME: httpd_accel_surrogate_id
6599 DEFAULT_DOC: visible_hostname is used if no specific ID is set.
6600 LOC: Config.Accel.surrogate_id
6602 Surrogates (http://www.esi.org/architecture_spec_1.0.html)
6603 need an identification token to allow control targeting. Because
6604 a farm of surrogates may all perform the same tasks, they may share
6605 an identification token.
6608 NAME: http_accel_surrogate_remote
6612 LOC: Config.onoff.surrogate_is_remote
6614 Remote surrogates (such as those in a CDN) honour the header
6615 "Surrogate-Control: no-store-remote".
6617 Set this to on to have squid behave as a remote surrogate.
6621 IFDEF: USE_SQUID_ESI
6622 COMMENT: libxml2|expat|custom
6624 LOC: ESIParser::Type
6627 ESI markup is not strictly XML compatible. The custom ESI parser
6628 will give higher performance, but cannot handle non ASCII character
6633 DELAY POOL PARAMETERS
6634 -----------------------------------------------------------------------------
6638 TYPE: delay_pool_count
6640 IFDEF: USE_DELAY_POOLS
6643 This represents the number of delay pools to be used. For example,
6644 if you have one class 2 delay pool and one class 3 delays pool, you
6645 have a total of 2 delay pools.
6647 See also delay_parameters, delay_class, delay_access for pool
6648 configuration details.
6652 TYPE: delay_pool_class
6654 IFDEF: USE_DELAY_POOLS
6657 This defines the class of each delay pool. There must be exactly one
6658 delay_class line for each delay pool. For example, to define two
6659 delay pools, one of class 2 and one of class 3, the settings above
6663 delay_pools 4 # 4 delay pools
6664 delay_class 1 2 # pool 1 is a class 2 pool
6665 delay_class 2 3 # pool 2 is a class 3 pool
6666 delay_class 3 4 # pool 3 is a class 4 pool
6667 delay_class 4 5 # pool 4 is a class 5 pool
6669 The delay pool classes are:
6671 class 1 Everything is limited by a single aggregate
6674 class 2 Everything is limited by a single aggregate
6675 bucket as well as an "individual" bucket chosen
6676 from bits 25 through 32 of the IPv4 address.
6678 class 3 Everything is limited by a single aggregate
6679 bucket as well as a "network" bucket chosen
6680 from bits 17 through 24 of the IP address and a
6681 "individual" bucket chosen from bits 17 through
6682 32 of the IPv4 address.
6684 class 4 Everything in a class 3 delay pool, with an
6685 additional limit on a per user basis. This
6686 only takes effect if the username is established
6687 in advance - by forcing authentication in your
6690 class 5 Requests are grouped according their tag (see
6691 external_acl's tag= reply).
6694 Each pool also requires a delay_parameters directive to configure the pool size
6695 and speed limits used whenever the pool is applied to a request. Along with
6696 a set of delay_access directives to determine when it is used.
6698 NOTE: If an IP address is a.b.c.d
6699 -> bits 25 through 32 are "d"
6700 -> bits 17 through 24 are "c"
6701 -> bits 17 through 32 are "c * 256 + d"
6703 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
6704 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
6706 This clause only supports fast acl types.
6707 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6709 See also delay_parameters and delay_access.
6713 TYPE: delay_pool_access
6715 DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool.
6716 IFDEF: USE_DELAY_POOLS
6719 This is used to determine which delay pool a request falls into.
6721 delay_access is sorted per pool and the matching starts with pool 1,
6722 then pool 2, ..., and finally pool N. The first delay pool where the
6723 request is allowed is selected for the request. If it does not allow
6724 the request to any pool then the request is not delayed (default).
6726 For example, if you want some_big_clients in delay
6727 pool 1 and lotsa_little_clients in delay pool 2:
6729 delay_access 1 allow some_big_clients
6730 delay_access 1 deny all
6731 delay_access 2 allow lotsa_little_clients
6732 delay_access 2 deny all
6733 delay_access 3 allow authenticated_clients
6735 See also delay_parameters and delay_class.
6739 NAME: delay_parameters
6740 TYPE: delay_pool_rates
6742 IFDEF: USE_DELAY_POOLS
6745 This defines the parameters for a delay pool. Each delay pool has
6746 a number of "buckets" associated with it, as explained in the
6747 description of delay_class.
6749 For a class 1 delay pool, the syntax is:
6751 delay_parameters pool aggregate
6753 For a class 2 delay pool:
6755 delay_parameters pool aggregate individual
6757 For a class 3 delay pool:
6759 delay_parameters pool aggregate network individual
6761 For a class 4 delay pool:
6763 delay_parameters pool aggregate network individual user
6765 For a class 5 delay pool:
6767 delay_parameters pool tagrate
6769 The option variables are:
6771 pool a pool number - ie, a number between 1 and the
6772 number specified in delay_pools as used in
6775 aggregate the speed limit parameters for the aggregate bucket
6778 individual the speed limit parameters for the individual
6779 buckets (class 2, 3).
6781 network the speed limit parameters for the network buckets
6784 user the speed limit parameters for the user buckets
6787 tagrate the speed limit parameters for the tag buckets
6790 A pair of delay parameters is written restore/maximum, where restore is
6791 the number of bytes (not bits - modem and network speeds are usually
6792 quoted in bits) per second placed into the bucket, and maximum is the
6793 maximum number of bytes which can be in the bucket at any time.
6795 There must be one delay_parameters line for each delay pool.
6798 For example, if delay pool number 1 is a class 2 delay pool as in the
6799 above example, and is being used to strictly limit each host to 64Kbit/sec
6800 (plus overheads), with no overall limit, the line is:
6802 delay_parameters 1 none 8000/8000
6804 Note that 8 x 8K Byte/sec -> 64K bit/sec.
6806 Note that the word 'none' is used to represent no limit.
6809 And, if delay pool number 2 is a class 3 delay pool as in the above
6810 example, and you want to limit it to a total of 256Kbit/sec (strict limit)
6811 with each 8-bit network permitted 64Kbit/sec (strict limit) and each
6812 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits
6813 to permit a decent web page to be downloaded at a decent speed
6814 (if the network is not being limited due to overuse) but slow down
6815 large downloads more significantly:
6817 delay_parameters 2 32000/32000 8000/8000 600/8000
6819 Note that 8 x 32K Byte/sec -> 256K bit/sec.
6820 8 x 8K Byte/sec -> 64K bit/sec.
6821 8 x 600 Byte/sec -> 4800 bit/sec.
6824 Finally, for a class 4 delay pool as in the example - each user will
6825 be limited to 128Kbits/sec no matter how many workstations they are logged into.:
6827 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
6830 See also delay_class and delay_access.
6834 NAME: delay_initial_bucket_level
6835 COMMENT: (percent, 0-100)
6838 IFDEF: USE_DELAY_POOLS
6839 LOC: Config.Delay.initial
6841 The initial bucket percentage is used to determine how much is put
6842 in each bucket when squid starts, is reconfigured, or first notices
6843 a host accessing it (in class 2 and class 3, individual hosts and
6844 networks only have buckets associated with them once they have been
6849 CLIENT DELAY POOL PARAMETERS
6850 -----------------------------------------------------------------------------
6853 NAME: client_delay_pools
6854 TYPE: client_delay_pool_count
6856 IFDEF: USE_DELAY_POOLS
6857 LOC: Config.ClientDelay
6859 This option specifies the number of client delay pools used. It must
6860 preceed other client_delay_* options.
6863 client_delay_pools 2
6865 See also client_delay_parameters and client_delay_access.
6868 NAME: client_delay_initial_bucket_level
6869 COMMENT: (percent, 0-no_limit)
6872 IFDEF: USE_DELAY_POOLS
6873 LOC: Config.ClientDelay.initial
6875 This option determines the initial bucket size as a percentage of
6876 max_bucket_size from client_delay_parameters. Buckets are created
6877 at the time of the "first" connection from the matching IP. Idle
6878 buckets are periodically deleted up.
6880 You can specify more than 100 percent but note that such "oversized"
6881 buckets are not refilled until their size goes down to max_bucket_size
6882 from client_delay_parameters.
6885 client_delay_initial_bucket_level 50
6888 NAME: client_delay_parameters
6889 TYPE: client_delay_pool_rates
6891 IFDEF: USE_DELAY_POOLS
6892 LOC: Config.ClientDelay
6895 This option configures client-side bandwidth limits using the
6898 client_delay_parameters pool speed_limit max_bucket_size
6900 pool is an integer ID used for client_delay_access matching.
6902 speed_limit is bytes added to the bucket per second.
6904 max_bucket_size is the maximum size of a bucket, enforced after any
6905 speed_limit additions.
6907 Please see the delay_parameters option for more information and
6911 client_delay_parameters 1 1024 2048
6912 client_delay_parameters 2 51200 16384
6914 See also client_delay_access.
6918 NAME: client_delay_access
6919 TYPE: client_delay_pool_access
6921 DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool.
6922 IFDEF: USE_DELAY_POOLS
6923 LOC: Config.ClientDelay
6925 This option determines the client-side delay pool for the
6928 client_delay_access pool_ID allow|deny acl_name
6930 All client_delay_access options are checked in their pool ID
6931 order, starting with pool 1. The first checked pool with allowed
6932 request is selected for the request. If no ACL matches or there
6933 are no client_delay_access options, the request bandwidth is not
6936 The ACL-selected pool is then used to find the
6937 client_delay_parameters for the request. Client-side pools are
6938 not used to aggregate clients. Clients are always aggregated
6939 based on their source IP addresses (one bucket per source IP).
6941 This clause only supports fast acl types.
6942 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
6943 Additionally, only the client TCP connection details are available.
6944 ACLs testing HTTP properties will not work.
6946 Please see delay_access for more examples.
6949 client_delay_access 1 allow low_rate_network
6950 client_delay_access 2 allow vips_network
6953 See also client_delay_parameters and client_delay_pools.
6957 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
6958 -----------------------------------------------------------------------------
6963 LOC: Config.Wccp.router
6965 DEFAULT_DOC: WCCP disabled.
6968 Use this option to define your WCCP ``home'' router for
6971 wccp_router supports a single WCCP(v1) router
6973 wccp2_router supports multiple WCCPv2 routers
6975 only one of the two may be used at the same time and defines
6976 which version of WCCP to use.
6980 TYPE: IpAddress_list
6981 LOC: Config.Wccp2.router
6983 DEFAULT_DOC: WCCPv2 disabled.
6986 Use this option to define your WCCP ``home'' router for
6989 wccp_router supports a single WCCP(v1) router
6991 wccp2_router supports multiple WCCPv2 routers
6993 only one of the two may be used at the same time and defines
6994 which version of WCCP to use.
6999 LOC: Config.Wccp.version
7003 This directive is only relevant if you need to set up WCCP(v1)
7004 to some very old and end-of-life Cisco routers. In all other
7005 setups it must be left unset or at the default setting.
7006 It defines an internal version in the WCCP(v1) protocol,
7007 with version 4 being the officially documented protocol.
7009 According to some users, Cisco IOS 11.2 and earlier only
7010 support WCCP version 3. If you're using that or an earlier
7011 version of IOS, you may need to change this value to 3, otherwise
7012 do not specify this parameter.
7015 NAME: wccp2_rebuild_wait
7017 LOC: Config.Wccp2.rebuildwait
7021 If this is enabled Squid will wait for the cache dir rebuild to finish
7022 before sending the first wccp2 HereIAm packet
7025 NAME: wccp2_forwarding_method
7027 LOC: Config.Wccp2.forwarding_method
7031 WCCP2 allows the setting of forwarding methods between the
7032 router/switch and the cache. Valid values are as follows:
7034 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
7035 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
7037 Currently (as of IOS 12.4) cisco routers only support GRE.
7038 Cisco switches only support the L2 redirect assignment method.
7041 NAME: wccp2_return_method
7043 LOC: Config.Wccp2.return_method
7047 WCCP2 allows the setting of return methods between the
7048 router/switch and the cache for packets that the cache
7049 decides not to handle. Valid values are as follows:
7051 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
7052 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
7054 Currently (as of IOS 12.4) cisco routers only support GRE.
7055 Cisco switches only support the L2 redirect assignment.
7057 If the "ip wccp redirect exclude in" command has been
7058 enabled on the cache interface, then it is still safe for
7059 the proxy server to use a l2 redirect method even if this
7060 option is set to GRE.
7063 NAME: wccp2_assignment_method
7065 LOC: Config.Wccp2.assignment_method
7069 WCCP2 allows the setting of methods to assign the WCCP hash
7070 Valid values are as follows:
7072 hash - Hash assignment
7073 mask - Mask assignment
7075 As a general rule, cisco routers support the hash assignment method
7076 and cisco switches support the mask assignment method.
7081 LOC: Config.Wccp2.info
7082 DEFAULT_IF_NONE: standard 0
7083 DEFAULT_DOC: Use the 'web-cache' standard service.
7086 WCCP2 allows for multiple traffic services. There are two
7087 types: "standard" and "dynamic". The standard type defines
7088 one service id - http (id 0). The dynamic service ids can be from
7089 51 to 255 inclusive. In order to use a dynamic service id
7090 one must define the type of traffic to be redirected; this is done
7091 using the wccp2_service_info option.
7093 The "standard" type does not require a wccp2_service_info option,
7094 just specifying the service id will suffice.
7096 MD5 service authentication can be enabled by adding
7097 "password=<password>" to the end of this service declaration.
7101 wccp2_service standard 0 # for the 'web-cache' standard service
7102 wccp2_service dynamic 80 # a dynamic service type which will be
7103 # fleshed out with subsequent options.
7104 wccp2_service standard 0 password=foo
7107 NAME: wccp2_service_info
7108 TYPE: wccp2_service_info
7109 LOC: Config.Wccp2.info
7113 Dynamic WCCPv2 services require further information to define the
7114 traffic you wish to have diverted.
7118 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
7119 priority=<priority> ports=<port>,<port>..
7121 The relevant WCCPv2 flags:
7122 + src_ip_hash, dst_ip_hash
7123 + source_port_hash, dst_port_hash
7124 + src_ip_alt_hash, dst_ip_alt_hash
7125 + src_port_alt_hash, dst_port_alt_hash
7128 The port list can be one to eight entries.
7132 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
7133 priority=240 ports=80
7135 Note: the service id must have been defined by a previous
7136 'wccp2_service dynamic <id>' entry.
7141 LOC: Config.Wccp2.weight
7145 Each cache server gets assigned a set of the destination
7146 hash proportional to their weight.
7151 LOC: Config.Wccp.address
7153 DEFAULT_DOC: Address selected by the operating system.
7156 Use this option if you require WCCPv2 to use a specific
7159 The default behavior is to not bind to any specific address.
7164 LOC: Config.Wccp2.address
7166 DEFAULT_DOC: Address selected by the operating system.
7169 Use this option if you require WCCP to use a specific
7172 The default behavior is to not bind to any specific address.
7176 PERSISTENT CONNECTION HANDLING
7177 -----------------------------------------------------------------------------
7179 Also see "pconn_timeout" in the TIMEOUTS section
7182 NAME: client_persistent_connections
7184 LOC: Config.onoff.client_pconns
7187 Persistent connection support for clients.
7188 Squid uses persistent connections (when allowed). You can use
7189 this option to disable persistent connections with clients.
7192 NAME: server_persistent_connections
7194 LOC: Config.onoff.server_pconns
7197 Persistent connection support for servers.
7198 Squid uses persistent connections (when allowed). You can use
7199 this option to disable persistent connections with servers.
7202 NAME: persistent_connection_after_error
7204 LOC: Config.onoff.error_pconns
7207 With this directive the use of persistent connections after
7208 HTTP errors can be disabled. Useful if you have clients
7209 who fail to handle errors on persistent connections proper.
7212 NAME: detect_broken_pconn
7214 LOC: Config.onoff.detect_broken_server_pconns
7217 Some servers have been found to incorrectly signal the use
7218 of HTTP/1.0 persistent connections even on replies not
7219 compatible, causing significant delays. This server problem
7220 has mostly been seen on redirects.
7222 By enabling this directive Squid attempts to detect such
7223 broken replies and automatically assume the reply is finished
7224 after 10 seconds timeout.
7228 CACHE DIGEST OPTIONS
7229 -----------------------------------------------------------------------------
7232 NAME: digest_generation
7233 IFDEF: USE_CACHE_DIGESTS
7235 LOC: Config.onoff.digest_generation
7238 This controls whether the server will generate a Cache Digest
7239 of its contents. By default, Cache Digest generation is
7240 enabled if Squid is compiled with --enable-cache-digests defined.
7243 NAME: digest_bits_per_entry
7244 IFDEF: USE_CACHE_DIGESTS
7246 LOC: Config.digest.bits_per_entry
7249 This is the number of bits of the server's Cache Digest which
7250 will be associated with the Digest entry for a given HTTP
7251 Method and URL (public key) combination. The default is 5.
7254 NAME: digest_rebuild_period
7255 IFDEF: USE_CACHE_DIGESTS
7258 LOC: Config.digest.rebuild_period
7261 This is the wait time between Cache Digest rebuilds.
7264 NAME: digest_rewrite_period
7266 IFDEF: USE_CACHE_DIGESTS
7268 LOC: Config.digest.rewrite_period
7271 This is the wait time between Cache Digest writes to
7275 NAME: digest_swapout_chunk_size
7278 IFDEF: USE_CACHE_DIGESTS
7279 LOC: Config.digest.swapout_chunk_size
7282 This is the number of bytes of the Cache Digest to write to
7283 disk at a time. It defaults to 4096 bytes (4KB), the Squid
7287 NAME: digest_rebuild_chunk_percentage
7288 COMMENT: (percent, 0-100)
7289 IFDEF: USE_CACHE_DIGESTS
7291 LOC: Config.digest.rebuild_chunk_percentage
7294 This is the percentage of the Cache Digest to be scanned at a
7295 time. By default it is set to 10% of the Cache Digest.
7300 -----------------------------------------------------------------------------
7305 LOC: Config.Port.snmp
7307 DEFAULT_DOC: SNMP disabled.
7310 The port number where Squid listens for SNMP requests. To enable
7311 SNMP support set this to a suitable port number. Port number
7312 3401 is often used for the Squid SNMP agent. By default it's
7313 set to "0" (disabled)
7321 LOC: Config.accessList.snmp
7323 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
7326 Allowing or denying access to the SNMP port.
7328 All access to the agent is denied by default.
7331 snmp_access allow|deny [!]aclname ...
7333 This clause only supports fast acl types.
7334 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
7337 snmp_access allow snmppublic localhost
7338 snmp_access deny all
7341 NAME: snmp_incoming_address
7343 LOC: Config.Addrs.snmp_incoming
7345 DEFAULT_DOC: Accept SNMP packets from all machine interfaces.
7348 Just like 'udp_incoming_address', but for the SNMP port.
7350 snmp_incoming_address is used for the SNMP socket receiving
7351 messages from SNMP agents.
7353 The default snmp_incoming_address is to listen on all
7354 available network interfaces.
7357 NAME: snmp_outgoing_address
7359 LOC: Config.Addrs.snmp_outgoing
7361 DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system.
7364 Just like 'udp_outgoing_address', but for the SNMP port.
7366 snmp_outgoing_address is used for SNMP packets returned to SNMP
7369 If snmp_outgoing_address is not set it will use the same socket
7370 as snmp_incoming_address. Only change this if you want to have
7371 SNMP replies sent using another address than where this Squid
7372 listens for SNMP queries.
7374 NOTE, snmp_incoming_address and snmp_outgoing_address can not have
7375 the same value since they both use the same port.
7380 -----------------------------------------------------------------------------
7383 NAME: icp_port udp_port
7386 DEFAULT_DOC: ICP disabled.
7387 LOC: Config.Port.icp
7389 The port number where Squid sends and receives ICP queries to
7390 and from neighbor caches. The standard UDP port for ICP is 3130.
7393 icp_port @DEFAULT_ICP_PORT@
7400 DEFAULT_DOC: HTCP disabled.
7401 LOC: Config.Port.htcp
7403 The port number where Squid sends and receives HTCP queries to
7404 and from neighbor caches. To turn it on you want to set it to
7411 NAME: log_icp_queries
7415 LOC: Config.onoff.log_udp
7417 If set, ICP queries are logged to access.log. You may wish
7418 do disable this if your ICP load is VERY high to speed things
7419 up or to simplify log analysis.
7422 NAME: udp_incoming_address
7424 LOC:Config.Addrs.udp_incoming
7426 DEFAULT_DOC: Accept packets from all machine interfaces.
7428 udp_incoming_address is used for UDP packets received from other
7431 The default behavior is to not bind to any specific address.
7433 Only change this if you want to have all UDP queries received on
7434 a specific interface/address.
7436 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
7437 modules. Altering it will affect all of them in the same manner.
7439 see also; udp_outgoing_address
7441 NOTE, udp_incoming_address and udp_outgoing_address can not
7442 have the same value since they both use the same port.
7445 NAME: udp_outgoing_address
7447 LOC: Config.Addrs.udp_outgoing
7449 DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system.
7451 udp_outgoing_address is used for UDP packets sent out to other
7454 The default behavior is to not bind to any specific address.
7456 Instead it will use the same socket as udp_incoming_address.
7457 Only change this if you want to have UDP queries sent using another
7458 address than where this Squid listens for UDP queries from other
7461 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
7462 modules. Altering it will affect all of them in the same manner.
7464 see also; udp_incoming_address
7466 NOTE, udp_incoming_address and udp_outgoing_address can not
7467 have the same value since they both use the same port.
7474 LOC: Config.onoff.icp_hit_stale
7476 If you want to return ICP_HIT for stale cache objects, set this
7477 option to 'on'. If you have sibling relationships with caches
7478 in other administrative domains, this should be 'off'. If you only
7479 have sibling relationships with caches under your control,
7480 it is probably okay to set this to 'on'.
7481 If set to 'on', your siblings should use the option "allow-miss"
7482 on their cache_peer lines for connecting to you.
7485 NAME: minimum_direct_hops
7488 LOC: Config.minDirectHops
7490 If using the ICMP pinging stuff, do direct fetches for sites
7491 which are no more than this many hops away.
7494 NAME: minimum_direct_rtt
7498 LOC: Config.minDirectRtt
7500 If using the ICMP pinging stuff, do direct fetches for sites
7501 which are no more than this many rtt milliseconds away.
7507 LOC: Config.Netdb.low
7509 The low water mark for the ICMP measurement database.
7511 Note: high watermark controlled by netdb_high directive.
7513 These watermarks are counts, not percents. The defaults are
7514 (low) 900 and (high) 1000. When the high water mark is
7515 reached, database entries will be deleted until the low
7522 LOC: Config.Netdb.high
7524 The high water mark for the ICMP measurement database.
7526 Note: low watermark controlled by netdb_low directive.
7528 These watermarks are counts, not percents. The defaults are
7529 (low) 900 and (high) 1000. When the high water mark is
7530 reached, database entries will be deleted until the low
7534 NAME: netdb_ping_period
7536 LOC: Config.Netdb.period
7539 The minimum period for measuring a site. There will be at
7540 least this much delay between successive pings to the same
7541 network. The default is five minutes.
7548 LOC: Config.onoff.query_icmp
7550 If you want to ask your peers to include ICMP data in their ICP
7551 replies, enable this option.
7553 If your peer has configured Squid (during compilation) with
7554 '--enable-icmp' that peer will send ICMP pings to origin server
7555 sites of the URLs it receives. If you enable this option the
7556 ICP replies from that peer will include the ICMP data (if available).
7557 Then, when choosing a parent cache, Squid will choose the parent with
7558 the minimal RTT to the origin server. When this happens, the
7559 hierarchy field of the access.log will be
7560 "CLOSEST_PARENT_MISS". This option is off by default.
7563 NAME: test_reachability
7567 LOC: Config.onoff.test_reachability
7569 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH
7570 instead of ICP_MISS if the target host is NOT in the ICMP
7571 database, or has a zero RTT.
7574 NAME: icp_query_timeout
7577 DEFAULT_DOC: Dynamic detection.
7579 LOC: Config.Timeout.icp_query
7581 Normally Squid will automatically determine an optimal ICP
7582 query timeout value based on the round-trip-time of recent ICP
7583 queries. If you want to override the value determined by
7584 Squid, set this 'icp_query_timeout' to a non-zero value. This
7585 value is specified in MILLISECONDS, so, to use a 2-second
7586 timeout (the old default), you would write:
7588 icp_query_timeout 2000
7591 NAME: maximum_icp_query_timeout
7595 LOC: Config.Timeout.icp_query_max
7597 Normally the ICP query timeout is determined dynamically. But
7598 sometimes it can lead to very large values (say 5 seconds).
7599 Use this option to put an upper limit on the dynamic timeout
7600 value. Do NOT use this option to always use a fixed (instead
7601 of a dynamic) timeout value. To set a fixed timeout see the
7602 'icp_query_timeout' directive.
7605 NAME: minimum_icp_query_timeout
7609 LOC: Config.Timeout.icp_query_min
7611 Normally the ICP query timeout is determined dynamically. But
7612 sometimes it can lead to very small timeouts, even lower than
7613 the normal latency variance on your link due to traffic.
7614 Use this option to put an lower limit on the dynamic timeout
7615 value. Do NOT use this option to always use a fixed (instead
7616 of a dynamic) timeout value. To set a fixed timeout see the
7617 'icp_query_timeout' directive.
7620 NAME: background_ping_rate
7624 LOC: Config.backgroundPingRate
7626 Controls how often the ICP pings are sent to siblings that
7627 have background-ping set.
7631 MULTICAST ICP OPTIONS
7632 -----------------------------------------------------------------------------
7637 LOC: Config.mcast_group_list
7640 This tag specifies a list of multicast groups which your server
7641 should join to receive multicasted ICP queries.
7643 NOTE! Be very careful what you put here! Be sure you
7644 understand the difference between an ICP _query_ and an ICP
7645 _reply_. This option is to be set only if you want to RECEIVE
7646 multicast queries. Do NOT set this option to SEND multicast
7647 ICP (use cache_peer for that). ICP replies are always sent via
7648 unicast, so this option does not affect whether or not you will
7649 receive replies from multicast group members.
7651 You must be very careful to NOT use a multicast address which
7652 is already in use by another group of caches.
7654 If you are unsure about multicast, please read the Multicast
7655 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
7657 Usage: mcast_groups 239.128.16.128 224.0.1.20
7659 By default, Squid doesn't listen on any multicast groups.
7662 NAME: mcast_miss_addr
7663 IFDEF: MULTICAST_MISS_STREAM
7665 LOC: Config.mcast_miss.addr
7667 DEFAULT_DOC: disabled.
7669 If you enable this option, every "cache miss" URL will
7670 be sent out on the specified multicast address.
7672 Do not enable this option unless you are are absolutely
7673 certain you understand what you are doing.
7676 NAME: mcast_miss_ttl
7677 IFDEF: MULTICAST_MISS_STREAM
7679 LOC: Config.mcast_miss.ttl
7682 This is the time-to-live value for packets multicasted
7683 when multicasting off cache miss URLs is enabled. By
7684 default this is set to 'site scope', i.e. 16.
7687 NAME: mcast_miss_port
7688 IFDEF: MULTICAST_MISS_STREAM
7690 LOC: Config.mcast_miss.port
7693 This is the port number to be used in conjunction with
7697 NAME: mcast_miss_encode_key
7698 IFDEF: MULTICAST_MISS_STREAM
7700 LOC: Config.mcast_miss.encode_key
7701 DEFAULT: XXXXXXXXXXXXXXXX
7703 The URLs that are sent in the multicast miss stream are
7704 encrypted. This is the encryption key.
7707 NAME: mcast_icp_query_timeout
7711 LOC: Config.Timeout.mcast_icp_query
7713 For multicast peers, Squid regularly sends out ICP "probes" to
7714 count how many other peers are listening on the given multicast
7715 address. This value specifies how long Squid should wait to
7716 count all the replies. The default is 2000 msec, or 2
7721 INTERNAL ICON OPTIONS
7722 -----------------------------------------------------------------------------
7725 NAME: icon_directory
7727 LOC: Config.icons.directory
7728 DEFAULT: @DEFAULT_ICON_DIR@
7730 Where the icons are stored. These are normally kept in
7734 NAME: global_internal_static
7736 LOC: Config.onoff.global_internal_static
7739 This directive controls is Squid should intercept all requests for
7740 /squid-internal-static/ no matter which host the URL is requesting
7741 (default on setting), or if nothing special should be done for
7742 such URLs (off setting). The purpose of this directive is to make
7743 icons etc work better in complex cache hierarchies where it may
7744 not always be possible for all corners in the cache mesh to reach
7745 the server generating a directory listing.
7748 NAME: short_icon_urls
7750 LOC: Config.icons.use_short_names
7753 If this is enabled Squid will use short URLs for icons.
7754 If disabled it will revert to the old behavior of including
7755 it's own name and port in the URL.
7757 If you run a complex cache hierarchy with a mix of Squid and
7758 other proxies you may need to disable this directive.
7763 -----------------------------------------------------------------------------
7766 NAME: error_directory
7768 LOC: Config.errorDirectory
7770 DEFAULT_DOC: Send error pages in the clients preferred language
7772 If you wish to create your own versions of the default
7773 error files to customize them to suit your company copy
7774 the error/template files to another directory and point
7777 WARNING: This option will disable multi-language support
7778 on error pages if used.
7780 The squid developers are interested in making squid available in
7781 a wide variety of languages. If you are making translations for a
7782 language that Squid does not currently provide please consider
7783 contributing your translation back to the project.
7784 http://wiki.squid-cache.org/Translations
7786 The squid developers working on translations are happy to supply drop-in
7787 translated error files in exchange for any new language contributions.
7790 NAME: error_default_language
7791 IFDEF: USE_ERR_LOCALES
7793 LOC: Config.errorDefaultLanguage
7795 DEFAULT_DOC: Generate English language pages.
7797 Set the default language which squid will send error pages in
7798 if no existing translation matches the clients language
7801 If unset (default) generic English will be used.
7803 The squid developers are interested in making squid available in
7804 a wide variety of languages. If you are interested in making
7805 translations for any language see the squid wiki for details.
7806 http://wiki.squid-cache.org/Translations
7809 NAME: error_log_languages
7810 IFDEF: USE_ERR_LOCALES
7812 LOC: Config.errorLogMissingLanguages
7815 Log to cache.log what languages users are attempting to
7816 auto-negotiate for translations.
7818 Successful negotiations are not logged. Only failures
7819 have meaning to indicate that Squid may need an upgrade
7820 of its error page translations.
7823 NAME: err_page_stylesheet
7825 LOC: Config.errorStylesheet
7826 DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css
7828 CSS Stylesheet to pattern the display of Squid default error pages.
7830 For information on CSS see http://www.w3.org/Style/CSS/
7835 LOC: Config.errHtmlText
7838 HTML text to include in error messages. Make this a "mailto"
7839 URL to your admin address, or maybe just a link to your
7840 organizations Web page.
7842 To include this in your error messages, you must rewrite
7843 the error template files (found in the "errors" directory).
7844 Wherever you want the 'err_html_text' line to appear,
7845 insert a %L tag in the error template file.
7848 NAME: email_err_data
7851 LOC: Config.onoff.emailErrData
7854 If enabled, information about the occurred error will be
7855 included in the mailto links of the ERR pages (if %W is set)
7856 so that the email body contains the data.
7857 Syntax is <A HREF="mailto:%w%W">%w</A>
7862 LOC: Config.denyInfoList
7865 Usage: deny_info err_page_name acl
7866 or deny_info http://... acl
7867 or deny_info TCP_RESET acl
7869 This can be used to return a ERR_ page for requests which
7870 do not pass the 'http_access' rules. Squid remembers the last
7871 acl it evaluated in http_access, and if a 'deny_info' line exists
7872 for that ACL Squid returns a corresponding error page.
7874 The acl is typically the last acl on the http_access deny line which
7875 denied access. The exceptions to this rule are:
7876 - When Squid needs to request authentication credentials. It's then
7877 the first authentication related acl encountered
7878 - When none of the http_access lines matches. It's then the last
7879 acl processed on the last http_access line.
7880 - When the decision to deny access was made by an adaptation service,
7881 the acl name is the corresponding eCAP or ICAP service_name.
7883 NP: If providing your own custom error pages with error_directory
7884 you may also specify them by your custom file name:
7885 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
7887 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
7888 may be specified by prefixing the file name with the code and a colon.
7889 e.g. 404:ERR_CUSTOM_ACCESS_DENIED
7891 Alternatively you can tell Squid to reset the TCP connection
7892 by specifying TCP_RESET.
7894 Or you can specify an error URL or URL pattern. The browsers will
7895 get redirected to the specified URL after formatting tags have
7896 been replaced. Redirect will be done with 302 or 307 according to
7897 HTTP/1.1 specs. A different 3xx code may be specified by prefixing
7898 the URL. e.g. 303:http://example.com/
7901 %a - username (if available. Password NOT included)
7904 %E - Error description
7906 %H - Request domain name
7907 %i - Client IP Address
7909 %o - Message result from external ACL helper
7910 %p - Request Port number
7911 %P - Request Protocol name
7912 %R - Request URL path
7913 %T - Timestamp in RFC 1123 format
7914 %U - Full canonical URL from client
7915 (HTTPS URLs terminate with *)
7916 %u - Full canonical URL from client
7917 %w - Admin email from squid.conf
7919 %% - Literal percent (%) code
7924 OPTIONS INFLUENCING REQUEST FORWARDING
7925 -----------------------------------------------------------------------------
7928 NAME: nonhierarchical_direct
7930 LOC: Config.onoff.nonhierarchical_direct
7933 By default, Squid will send any non-hierarchical requests
7934 (not cacheable request type) direct to origin servers.
7936 When this is set to "off", Squid will prefer to send these
7937 requests to parents.
7939 Note that in most configurations, by turning this off you will only
7940 add latency to these request without any improvement in global hit
7943 This option only sets a preference. If the parent is unavailable a
7944 direct connection to the origin server may still be attempted. To
7945 completely prevent direct connections use never_direct.
7950 LOC: Config.onoff.prefer_direct
7953 Normally Squid tries to use parents for most requests. If you for some
7954 reason like it to first try going direct and only use a parent if
7955 going direct fails set this to on.
7957 By combining nonhierarchical_direct off and prefer_direct on you
7958 can set up Squid to use a parent as a backup path if going direct
7961 Note: If you want Squid to use parents for all requests see
7962 the never_direct directive. prefer_direct only modifies how Squid
7963 acts on cacheable requests.
7966 NAME: cache_miss_revalidate
7970 LOC: Config.onoff.cache_miss_revalidate
7972 RFC 7232 defines a conditional request mechanism to prevent
7973 response objects being unnecessarily transferred over the network.
7974 If that mechanism is used by the client and a cache MISS occurs
7975 it can prevent new cache entries being created.
7977 This option determines whether Squid on cache MISS will pass the
7978 client revalidation request to the server or tries to fetch new
7979 content for caching. It can be useful while the cache is mostly
7980 empty to more quickly have the cache populated by generating
7981 non-conditional GETs.
7983 When set to 'on' (default), Squid will pass all client If-* headers
7984 to the server. This permits server responses without a cacheable
7985 payload to be delivered and on MISS no new cache entry is created.
7987 When set to 'off' and if the request is cacheable, Squid will
7988 remove the clients If-Modified-Since and If-None-Match headers from
7989 the request sent to the server. This requests a 200 status response
7990 from the server to create a new cache entry with.
7995 LOC: Config.accessList.AlwaysDirect
7997 DEFAULT_DOC: Prevent any cache_peer being used for this request.
7999 Usage: always_direct allow|deny [!]aclname ...
8001 Here you can use ACL elements to specify requests which should
8002 ALWAYS be forwarded by Squid to the origin servers without using
8003 any peers. For example, to always directly forward requests for
8004 local servers ignoring any parents or siblings you may have use
8007 acl local-servers dstdomain my.domain.net
8008 always_direct allow local-servers
8010 To always forward FTP requests directly, use
8013 always_direct allow FTP
8015 NOTE: There is a similar, but opposite option named
8016 'never_direct'. You need to be aware that "always_direct deny
8017 foo" is NOT the same thing as "never_direct allow foo". You
8018 may need to use a deny rule to exclude a more-specific case of
8019 some other rule. Example:
8021 acl local-external dstdomain external.foo.net
8022 acl local-servers dstdomain .foo.net
8023 always_direct deny local-external
8024 always_direct allow local-servers
8026 NOTE: If your goal is to make the client forward the request
8027 directly to the origin server bypassing Squid then this needs
8028 to be done in the client configuration. Squid configuration
8029 can only tell Squid how Squid should fetch the object.
8031 NOTE: This directive is not related to caching. The replies
8032 is cached as usual even if you use always_direct. To not cache
8033 the replies see the 'cache' directive.
8035 This clause supports both fast and slow acl types.
8036 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
8041 LOC: Config.accessList.NeverDirect
8043 DEFAULT_DOC: Allow DNS results to be used for this request.
8045 Usage: never_direct allow|deny [!]aclname ...
8047 never_direct is the opposite of always_direct. Please read
8048 the description for always_direct if you have not already.
8050 With 'never_direct' you can use ACL elements to specify
8051 requests which should NEVER be forwarded directly to origin
8052 servers. For example, to force the use of a proxy for all
8053 requests, except those in your local domain use something like:
8055 acl local-servers dstdomain .foo.net
8056 never_direct deny local-servers
8057 never_direct allow all
8059 or if Squid is inside a firewall and there are local intranet
8060 servers inside the firewall use something like:
8062 acl local-intranet dstdomain .foo.net
8063 acl local-external dstdomain external.foo.net
8064 always_direct deny local-external
8065 always_direct allow local-intranet
8066 never_direct allow all
8068 This clause supports both fast and slow acl types.
8069 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
8073 ADVANCED NETWORKING OPTIONS
8074 -----------------------------------------------------------------------------
8077 NAME: incoming_udp_average incoming_icp_average
8080 LOC: Config.comm_incoming.udp.average
8082 Heavy voodoo here. I can't even believe you are reading this.
8083 Are you crazy? Don't even think about adjusting these unless
8084 you understand the algorithms in comm_select.c first!
8087 NAME: incoming_tcp_average incoming_http_average
8090 LOC: Config.comm_incoming.tcp.average
8092 Heavy voodoo here. I can't even believe you are reading this.
8093 Are you crazy? Don't even think about adjusting these unless
8094 you understand the algorithms in comm_select.c first!
8097 NAME: incoming_dns_average
8100 LOC: Config.comm_incoming.dns.average
8102 Heavy voodoo here. I can't even believe you are reading this.
8103 Are you crazy? Don't even think about adjusting these unless
8104 you understand the algorithms in comm_select.c first!
8107 NAME: min_udp_poll_cnt min_icp_poll_cnt
8110 LOC: Config.comm_incoming.udp.min_poll
8112 Heavy voodoo here. I can't even believe you are reading this.
8113 Are you crazy? Don't even think about adjusting these unless
8114 you understand the algorithms in comm_select.c first!
8117 NAME: min_dns_poll_cnt
8120 LOC: Config.comm_incoming.dns.min_poll
8122 Heavy voodoo here. I can't even believe you are reading this.
8123 Are you crazy? Don't even think about adjusting these unless
8124 you understand the algorithms in comm_select.c first!
8127 NAME: min_tcp_poll_cnt min_http_poll_cnt
8130 LOC: Config.comm_incoming.tcp.min_poll
8132 Heavy voodoo here. I can't even believe you are reading this.
8133 Are you crazy? Don't even think about adjusting these unless
8134 you understand the algorithms in comm_select.c first!
8140 LOC: Config.accept_filter
8144 The name of an accept(2) filter to install on Squid's
8145 listen socket(s). This feature is perhaps specific to
8146 FreeBSD and requires support in the kernel.
8148 The 'httpready' filter delays delivering new connections
8149 to Squid until a full HTTP request has been received.
8150 See the accf_http(9) man page for details.
8152 The 'dataready' filter delays delivering new connections
8153 to Squid until there is some data to process.
8154 See the accf_dataready(9) man page for details.
8158 The 'data' filter delays delivering of new connections
8159 to Squid until there is some data to process by TCP_ACCEPT_DEFER.
8160 You may optionally specify a number of seconds to wait by
8161 'data=N' where N is the number of seconds. Defaults to 30
8162 if not specified. See the tcp(7) man page for details.
8165 accept_filter httpready
8170 NAME: client_ip_max_connections
8172 LOC: Config.client_ip_max_connections
8174 DEFAULT_DOC: No limit.
8176 Set an absolute limit on the number of connections a single
8177 client IP can use. Any more than this and Squid will begin to drop
8178 new connections from the client until it closes some links.
8180 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP
8181 connections from the client. For finer control use the ACL access controls.
8183 Requires client_db to be enabled (the default).
8185 WARNING: This may noticably slow down traffic received via external proxies
8186 or NAT devices and cause them to rebound error messages back to their clients.
8189 NAME: tcp_recv_bufsize
8193 DEFAULT_DOC: Use operating system TCP defaults.
8194 LOC: Config.tcpRcvBufsz
8196 Size of receive buffer to set for TCP sockets. Probably just
8197 as easy to change your kernel's default.
8198 Omit from squid.conf to use the default buffer size.
8203 -----------------------------------------------------------------------------
8210 LOC: Adaptation::Icap::TheConfig.onoff
8213 If you want to enable the ICAP module support, set this to on.
8216 NAME: icap_connect_timeout
8219 LOC: Adaptation::Icap::TheConfig.connect_timeout_raw
8222 This parameter specifies how long to wait for the TCP connect to
8223 the requested ICAP server to complete before giving up and either
8224 terminating the HTTP transaction or bypassing the failure.
8226 The default for optional services is peer_connect_timeout.
8227 The default for essential services is connect_timeout.
8228 If this option is explicitly set, its value applies to all services.
8231 NAME: icap_io_timeout
8235 DEFAULT_DOC: Use read_timeout.
8236 LOC: Adaptation::Icap::TheConfig.io_timeout_raw
8239 This parameter specifies how long to wait for an I/O activity on
8240 an established, active ICAP connection before giving up and
8241 either terminating the HTTP transaction or bypassing the
8245 NAME: icap_service_failure_limit
8246 COMMENT: limit [in memory-depth time-units]
8247 TYPE: icap_service_failure_limit
8249 LOC: Adaptation::Icap::TheConfig
8252 The limit specifies the number of failures that Squid tolerates
8253 when establishing a new TCP connection with an ICAP service. If
8254 the number of failures exceeds the limit, the ICAP service is
8255 not used for new ICAP requests until it is time to refresh its
8258 A negative value disables the limit. Without the limit, an ICAP
8259 service will not be considered down due to connectivity failures
8260 between ICAP OPTIONS requests.
8262 Squid forgets ICAP service failures older than the specified
8263 value of memory-depth. The memory fading algorithm
8264 is approximate because Squid does not remember individual
8265 errors but groups them instead, splitting the option
8266 value into ten time slots of equal length.
8268 When memory-depth is 0 and by default this option has no
8269 effect on service failure expiration.
8271 Squid always forgets failures when updating service settings
8272 using an ICAP OPTIONS transaction, regardless of this option
8276 # suspend service usage after 10 failures in 5 seconds:
8277 icap_service_failure_limit 10 in 5 seconds
8280 NAME: icap_service_revival_delay
8283 LOC: Adaptation::Icap::TheConfig.service_revival_delay
8286 The delay specifies the number of seconds to wait after an ICAP
8287 OPTIONS request failure before requesting the options again. The
8288 failed ICAP service is considered "down" until fresh OPTIONS are
8291 The actual delay cannot be smaller than the hardcoded minimum
8292 delay of 30 seconds.
8295 NAME: icap_preview_enable
8299 LOC: Adaptation::Icap::TheConfig.preview_enable
8302 The ICAP Preview feature allows the ICAP server to handle the
8303 HTTP message by looking only at the beginning of the message body
8304 or even without receiving the body at all. In some environments,
8305 previews greatly speedup ICAP processing.
8307 During an ICAP OPTIONS transaction, the server may tell Squid what
8308 HTTP messages should be previewed and how big the preview should be.
8309 Squid will not use Preview if the server did not request one.
8311 To disable ICAP Preview for all ICAP services, regardless of
8312 individual ICAP server OPTIONS responses, set this option to "off".
8314 icap_preview_enable off
8317 NAME: icap_preview_size
8320 LOC: Adaptation::Icap::TheConfig.preview_size
8322 DEFAULT_DOC: No preview sent.
8324 The default size of preview data to be sent to the ICAP server.
8325 This value might be overwritten on a per server basis by OPTIONS requests.
8328 NAME: icap_206_enable
8332 LOC: Adaptation::Icap::TheConfig.allow206_enable
8335 206 (Partial Content) responses is an ICAP extension that allows the
8336 ICAP agents to optionally combine adapted and original HTTP message
8337 content. The decision to combine is postponed until the end of the
8338 ICAP response. Squid supports Partial Content extension by default.
8340 Activation of the Partial Content extension is negotiated with each
8341 ICAP service during OPTIONS exchange. Most ICAP servers should handle
8342 negotation correctly even if they do not support the extension, but
8343 some might fail. To disable Partial Content support for all ICAP
8344 services and to avoid any negotiation, set this option to "off".
8350 NAME: icap_default_options_ttl
8353 LOC: Adaptation::Icap::TheConfig.default_options_ttl
8356 The default TTL value for ICAP OPTIONS responses that don't have
8357 an Options-TTL header.
8360 NAME: icap_persistent_connections
8364 LOC: Adaptation::Icap::TheConfig.reuse_connections
8367 Whether or not Squid should use persistent connections to
8371 NAME: adaptation_send_client_ip icap_send_client_ip
8373 IFDEF: USE_ADAPTATION
8375 LOC: Adaptation::Config::send_client_ip
8378 If enabled, Squid shares HTTP client IP information with adaptation
8379 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests.
8380 For eCAP, Squid sets the libecap::metaClientIp transaction option.
8382 See also: adaptation_uses_indirect_client
8385 NAME: adaptation_send_username icap_send_client_username
8387 IFDEF: USE_ADAPTATION
8389 LOC: Adaptation::Config::send_username
8392 This sends authenticated HTTP client username (if available) to
8393 the adaptation service.
8395 For ICAP, the username value is encoded based on the
8396 icap_client_username_encode option and is sent using the header
8397 specified by the icap_client_username_header option.
8400 NAME: icap_client_username_header
8403 LOC: Adaptation::Icap::TheConfig.client_username_header
8404 DEFAULT: X-Client-Username
8406 ICAP request header name to use for adaptation_send_username.
8409 NAME: icap_client_username_encode
8413 LOC: Adaptation::Icap::TheConfig.client_username_encode
8416 Whether to base64 encode the authenticated client username.
8420 TYPE: icap_service_type
8422 LOC: Adaptation::Icap::TheConfig
8425 Defines a single ICAP service using the following format:
8427 icap_service id vectoring_point uri [option ...]
8430 an opaque identifier or name which is used to direct traffic to
8431 this specific service. Must be unique among all adaptation
8432 services in squid.conf.
8434 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8435 This specifies at which point of transaction processing the
8436 ICAP service should be activated. *_postcache vectoring points
8437 are not yet supported.
8439 uri: icap://servername:port/servicepath
8440 ICAP server and service location.
8441 icaps://servername:port/servicepath
8442 The "icap:" URI scheme is used for traditional ICAP server and
8443 service location (default port is 1344, connections are not
8444 encrypted). The "icaps:" URI scheme is for Secure ICAP
8445 services that use SSL/TLS-encrypted ICAP connections (by
8446 default, on port 11344).
8448 ICAP does not allow a single service to handle both REQMOD and RESPMOD
8449 transactions. Squid does not enforce that requirement. You can specify
8450 services with the same service_url and different vectoring_points. You
8451 can even specify multiple identical services as long as their
8452 service_names differ.
8454 To activate a service, use the adaptation_access directive. To group
8455 services, use adaptation_service_chain and adaptation_service_set.
8457 Service options are separated by white space. ICAP services support
8458 the following name=value options:
8461 If set to 'on' or '1', the ICAP service is treated as
8462 optional. If the service cannot be reached or malfunctions,
8463 Squid will try to ignore any errors and process the message as
8464 if the service was not enabled. No all ICAP errors can be
8465 bypassed. If set to 0, the ICAP service is treated as
8466 essential and all ICAP errors will result in an error page
8467 returned to the HTTP client.
8469 Bypass is off by default: services are treated as essential.
8472 If set to 'on' or '1', the ICAP service is allowed to
8473 dynamically change the current message adaptation plan by
8474 returning a chain of services to be used next. The services
8475 are specified using the X-Next-Services ICAP response header
8476 value, formatted as a comma-separated list of service names.
8477 Each named service should be configured in squid.conf. Other
8478 services are ignored. An empty X-Next-Services value results
8479 in an empty plan which ends the current adaptation.
8481 Dynamic adaptation plan may cross or cover multiple supported
8482 vectoring points in their natural processing order.
8484 Routing is not allowed by default: the ICAP X-Next-Services
8485 response header is ignored.
8488 Only has effect on split-stack systems. The default on those systems
8489 is to use IPv4-only connections. When set to 'on' this option will
8490 make Squid use IPv6-only connections to contact this ICAP service.
8492 on-overload=block|bypass|wait|force
8493 If the service Max-Connections limit has been reached, do
8494 one of the following for each new ICAP transaction:
8495 * block: send an HTTP error response to the client
8496 * bypass: ignore the "over-connected" ICAP service
8497 * wait: wait (in a FIFO queue) for an ICAP connection slot
8498 * force: proceed, ignoring the Max-Connections limit
8500 In SMP mode with N workers, each worker assumes the service
8501 connection limit is Max-Connections/N, even though not all
8502 workers may use a given service.
8504 The default value is "bypass" if service is bypassable,
8505 otherwise it is set to "wait".
8509 Use the given number as the Max-Connections limit, regardless
8510 of the Max-Connections value given by the service, if any.
8512 connection-encryption=on|off
8513 Determines the ICAP service effect on the connections_encrypted
8516 The default is "on" for Secure ICAP services (i.e., those
8517 with the icaps:// service URIs scheme) and "off" for plain ICAP
8520 Does not affect ICAP connections (e.g., does not turn Secure
8523 ==== ICAPS / TLS OPTIONS ====
8525 These options are used for Secure ICAP (icaps://....) services only.
8527 tls-cert=/path/to/ssl/certificate
8528 A client SSL certificate to use when connecting to
8531 tls-key=/path/to/ssl/key
8532 The private TLS/SSL key corresponding to sslcert above.
8533 If 'tls-key' is not specified 'tls-cert' is assumed to
8534 reference a combined PEM format file containing both the
8535 certificate and the key.
8537 tls-cipher=... The list of valid TLS/SSL ciphers to use when connecting
8538 to this icap server.
8541 The minimum TLS protocol version to permit. To control
8542 SSLv3 use the ssloptions= parameter.
8543 Supported Values: 1.0 (default), 1.1, 1.2
8545 tls-options=... Specify various OpenSSL library options:
8547 NO_SSLv3 Disallow the use of SSLv3
8549 NO_TLSv1 Disallow the use of TLSv1.0
8550 NO_TLSv1_1 Disallow the use of TLSv1.1
8551 NO_TLSv1_2 Disallow the use of TLSv1.2
8554 Always create a new key when using
8555 temporary/ephemeral DH key exchanges
8557 ALL Enable various bug workarounds
8558 suggested as "harmless" by OpenSSL
8559 Be warned that this reduces SSL/TLS
8560 strength to some attacks.
8562 See the OpenSSL SSL_CTX_set_options documentation for a
8563 more complete list. Options relevant only to SSLv2 are
8566 tls-cafile= PEM file containing CA certificates to use when verifying
8567 the icap server certificate.
8568 Use to specify intermediate CA certificate(s) if not sent
8569 by the server. Or the full CA chain for the server when
8570 using the tls-default-ca=off flag.
8571 May be repeated to load multiple files.
8573 tls-capath=... A directory containing additional CA certificates to
8574 use when verifying the icap server certificate.
8575 Requires OpenSSL or LibreSSL.
8577 tls-crlfile=... A certificate revocation list file to use when
8578 verifying the icap server certificate.
8580 tls-flags=... Specify various flags modifying the Squid TLS implementation:
8583 Accept certificates even if they fail to
8586 Don't verify the icap server certificate
8587 matches the server name
8589 tls-default-ca[=off]
8590 Whether to use the system Trusted CAs. Default is ON.
8592 tls-domain= The icap server name as advertised in it's certificate.
8593 Used for verifying the correctness of the received icap
8594 server certificate. If not specified the icap server
8595 hostname extracted from ICAP URI will be used.
8597 Older icap_service format without optional named parameters is
8598 deprecated but supported for backward compatibility.
8601 icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0
8602 icap_service svcLogger reqmod_precache icaps://icap2.mydomain.net:11344/reqmod routing=on
8606 TYPE: icap_class_type
8611 This deprecated option was documented to define an ICAP service
8612 chain, even though it actually defined a set of similar, redundant
8613 services, and the chains were not supported.
8615 To define a set of redundant services, please use the
8616 adaptation_service_set directive. For service chains, use
8617 adaptation_service_chain.
8621 TYPE: icap_access_type
8626 This option is deprecated. Please use adaptation_access, which
8627 has the same ICAP functionality, but comes with better
8628 documentation, and eCAP support.
8633 -----------------------------------------------------------------------------
8640 LOC: Adaptation::Ecap::TheConfig.onoff
8643 Controls whether eCAP support is enabled.
8647 TYPE: ecap_service_type
8649 LOC: Adaptation::Ecap::TheConfig
8652 Defines a single eCAP service
8654 ecap_service id vectoring_point uri [option ...]
8657 an opaque identifier or name which is used to direct traffic to
8658 this specific service. Must be unique among all adaptation
8659 services in squid.conf.
8661 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
8662 This specifies at which point of transaction processing the
8663 eCAP service should be activated. *_postcache vectoring points
8664 are not yet supported.
8666 uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional
8667 Squid uses the eCAP service URI to match this configuration
8668 line with one of the dynamically loaded services. Each loaded
8669 eCAP service must have a unique URI. Obtain the right URI from
8670 the service provider.
8672 To activate a service, use the adaptation_access directive. To group
8673 services, use adaptation_service_chain and adaptation_service_set.
8675 Service options are separated by white space. eCAP services support
8676 the following name=value options:
8679 If set to 'on' or '1', the eCAP service is treated as optional.
8680 If the service cannot be reached or malfunctions, Squid will try
8681 to ignore any errors and process the message as if the service
8682 was not enabled. No all eCAP errors can be bypassed.
8683 If set to 'off' or '0', the eCAP service is treated as essential
8684 and all eCAP errors will result in an error page returned to the
8687 Bypass is off by default: services are treated as essential.
8690 If set to 'on' or '1', the eCAP service is allowed to
8691 dynamically change the current message adaptation plan by
8692 returning a chain of services to be used next.
8694 Dynamic adaptation plan may cross or cover multiple supported
8695 vectoring points in their natural processing order.
8697 Routing is not allowed by default.
8699 connection-encryption=on|off
8700 Determines the eCAP service effect on the connections_encrypted
8703 Defaults to "on", which does not taint the master transaction
8706 Does not affect eCAP API calls.
8708 Older ecap_service format without optional named parameters is
8709 deprecated but supported for backward compatibility.
8713 ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off
8714 ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on
8717 NAME: loadable_modules
8719 IFDEF: USE_LOADABLE_MODULES
8720 LOC: Config.loadable_module_names
8723 Instructs Squid to load the specified dynamic module(s) or activate
8724 preloaded module(s).
8726 loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
8730 MESSAGE ADAPTATION OPTIONS
8731 -----------------------------------------------------------------------------
8734 NAME: adaptation_service_set
8735 TYPE: adaptation_service_set_type
8736 IFDEF: USE_ADAPTATION
8741 Configures an ordered set of similar, redundant services. This is
8742 useful when hot standby or backup adaptation servers are available.
8744 adaptation_service_set set_name service_name1 service_name2 ...
8746 The named services are used in the set declaration order. The first
8747 applicable adaptation service from the set is used first. The next
8748 applicable service is tried if and only if the transaction with the
8749 previous service fails and the message waiting to be adapted is still
8752 When adaptation starts, broken services are ignored as if they were
8753 not a part of the set. A broken service is a down optional service.
8755 The services in a set must be attached to the same vectoring point
8756 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8758 If all services in a set are optional then adaptation failures are
8759 bypassable. If all services in the set are essential, then a
8760 transaction failure with one service may still be retried using
8761 another service from the set, but when all services fail, the master
8762 transaction fails as well.
8764 A set may contain a mix of optional and essential services, but that
8765 is likely to lead to surprising results because broken services become
8766 ignored (see above), making previously bypassable failures fatal.
8767 Technically, it is the bypassability of the last failed service that
8770 See also: adaptation_access adaptation_service_chain
8773 adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
8774 adaptation service_set svcLogger loggerLocal loggerRemote
8777 NAME: adaptation_service_chain
8778 TYPE: adaptation_service_chain_type
8779 IFDEF: USE_ADAPTATION
8784 Configures a list of complementary services that will be applied
8785 one-by-one, forming an adaptation chain or pipeline. This is useful
8786 when Squid must perform different adaptations on the same message.
8788 adaptation_service_chain chain_name service_name1 svc_name2 ...
8790 The named services are used in the chain declaration order. The first
8791 applicable adaptation service from the chain is used first. The next
8792 applicable service is applied to the successful adaptation results of
8793 the previous service in the chain.
8795 When adaptation starts, broken services are ignored as if they were
8796 not a part of the chain. A broken service is a down optional service.
8798 Request satisfaction terminates the adaptation chain because Squid
8799 does not currently allow declaration of RESPMOD services at the
8800 "reqmod_precache" vectoring point (see icap_service or ecap_service).
8802 The services in a chain must be attached to the same vectoring point
8803 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
8805 A chain may contain a mix of optional and essential services. If an
8806 essential adaptation fails (or the failure cannot be bypassed for
8807 other reasons), the master transaction fails. Otherwise, the failure
8808 is bypassed as if the failed adaptation service was not in the chain.
8810 See also: adaptation_access adaptation_service_set
8813 adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
8816 NAME: adaptation_access
8817 TYPE: adaptation_access_type
8818 IFDEF: USE_ADAPTATION
8821 DEFAULT_DOC: Allow, unless rules exist in squid.conf.
8823 Sends an HTTP transaction to an ICAP or eCAP adaptation service.
8825 adaptation_access service_name allow|deny [!]aclname...
8826 adaptation_access set_name allow|deny [!]aclname...
8828 At each supported vectoring point, the adaptation_access
8829 statements are processed in the order they appear in this
8830 configuration file. Statements pointing to the following services
8831 are ignored (i.e., skipped without checking their ACL):
8833 - services serving different vectoring points
8834 - "broken-but-bypassable" services
8835 - "up" services configured to ignore such transactions
8836 (e.g., based on the ICAP Transfer-Ignore header).
8838 When a set_name is used, all services in the set are checked
8839 using the same rules, to find the first applicable one. See
8840 adaptation_service_set for details.
8842 If an access list is checked and there is a match, the
8843 processing stops: For an "allow" rule, the corresponding
8844 adaptation service is used for the transaction. For a "deny"
8845 rule, no adaptation service is activated.
8847 It is currently not possible to apply more than one adaptation
8848 service at the same vectoring point to the same HTTP transaction.
8850 See also: icap_service and ecap_service
8853 adaptation_access service_1 allow all
8856 NAME: adaptation_service_iteration_limit
8858 IFDEF: USE_ADAPTATION
8859 LOC: Adaptation::Config::service_iteration_limit
8862 Limits the number of iterations allowed when applying adaptation
8863 services to a message. If your longest adaptation set or chain
8864 may have more than 16 services, increase the limit beyond its
8865 default value of 16. If detecting infinite iteration loops sooner
8866 is critical, make the iteration limit match the actual number
8867 of services in your longest adaptation set or chain.
8869 Infinite adaptation loops are most likely with routing services.
8871 See also: icap_service routing=1
8874 NAME: adaptation_masterx_shared_names
8876 IFDEF: USE_ADAPTATION
8877 LOC: Adaptation::Config::masterx_shared_name
8880 For each master transaction (i.e., the HTTP request and response
8881 sequence, including all related ICAP and eCAP exchanges), Squid
8882 maintains a table of metadata. The table entries are (name, value)
8883 pairs shared among eCAP and ICAP exchanges. The table is destroyed
8884 with the master transaction.
8886 This option specifies the table entry names that Squid must accept
8887 from and forward to the adaptation transactions.
8889 An ICAP REQMOD or RESPMOD transaction may set an entry in the
8890 shared table by returning an ICAP header field with a name
8891 specified in adaptation_masterx_shared_names.
8893 An eCAP REQMOD or RESPMOD transaction may set an entry in the
8894 shared table by implementing the libecap::visitEachOption() API
8895 to provide an option with a name specified in
8896 adaptation_masterx_shared_names.
8898 Squid will store and forward the set entry to subsequent adaptation
8899 transactions within the same master transaction scope.
8901 Only one shared entry name is supported at this time.
8904 # share authentication information among ICAP services
8905 adaptation_masterx_shared_names X-Subscriber-ID
8908 NAME: adaptation_meta
8910 IFDEF: USE_ADAPTATION
8911 LOC: Adaptation::Config::metaHeaders
8914 This option allows Squid administrator to add custom ICAP request
8915 headers or eCAP options to Squid ICAP requests or eCAP transactions.
8916 Use it to pass custom authentication tokens and other
8917 transaction-state related meta information to an ICAP/eCAP service.
8919 The addition of a meta header is ACL-driven:
8920 adaptation_meta name value [!]aclname ...
8922 Processing for a given header name stops after the first ACL list match.
8923 Thus, it is impossible to add two headers with the same name. If no ACL
8924 lists match for a given header name, no such header is added. For
8927 # do not debug transactions except for those that need debugging
8928 adaptation_meta X-Debug 1 needs_debugging
8930 # log all transactions except for those that must remain secret
8931 adaptation_meta X-Log 1 !keep_secret
8933 # mark transactions from users in the "G 1" group
8934 adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1
8936 The "value" parameter may be a regular squid.conf token or a "double
8937 quoted string". Within the quoted string, use backslash (\) to escape
8938 any character, which is currently only useful for escaping backslashes
8939 and double quotes. For example,
8940 "this string has one backslash (\\) and two \"quotes\""
8942 Used adaptation_meta header values may be logged via %note
8943 logformat code. If multiple adaptation_meta headers with the same name
8944 are used during master transaction lifetime, the header values are
8945 logged in the order they were used and duplicate values are ignored
8946 (only the first repeated value will be logged).
8952 LOC: Adaptation::Icap::TheConfig.repeat
8953 DEFAULT_IF_NONE: deny all
8955 This ACL determines which retriable ICAP transactions are
8956 retried. Transactions that received a complete ICAP response
8957 and did not have to consume or produce HTTP bodies to receive
8958 that response are usually retriable.
8960 icap_retry allow|deny [!]aclname ...
8962 Squid automatically retries some ICAP I/O timeouts and errors
8963 due to persistent connection race conditions.
8965 See also: icap_retry_limit
8968 NAME: icap_retry_limit
8971 LOC: Adaptation::Icap::TheConfig.repeat_limit
8973 DEFAULT_DOC: No retries are allowed.
8975 Limits the number of retries allowed.
8977 Communication errors due to persistent connection race
8978 conditions are unavoidable, automatically retried, and do not
8979 count against this limit.
8981 See also: icap_retry
8987 -----------------------------------------------------------------------------
8990 NAME: check_hostnames
8993 LOC: Config.onoff.check_hostnames
8995 For security and stability reasons Squid can check
8996 hostnames for Internet standard RFC compliance. If you want
8997 Squid to perform these checks turn this directive on.
9000 NAME: allow_underscore
9003 LOC: Config.onoff.allow_underscore
9005 Underscore characters is not strictly allowed in Internet hostnames
9006 but nevertheless used by many sites. Set this to off if you want
9007 Squid to be strict about the standard.
9008 This check is performed only when check_hostnames is set to on.
9011 NAME: dns_retransmit_interval
9014 LOC: Config.Timeout.idns_retransmit
9016 Initial retransmit interval for DNS queries. The interval is
9017 doubled each time all configured DNS servers have been tried.
9023 LOC: Config.Timeout.idns_query
9025 DNS Query timeout. If no response is received to a DNS query
9026 within this time all DNS servers for the queried domain
9027 are assumed to be unavailable.
9030 NAME: dns_packet_max
9032 DEFAULT_DOC: EDNS disabled
9034 LOC: Config.dns.packet_max
9036 Maximum number of bytes packet size to advertise via EDNS.
9037 Set to "none" to disable EDNS large packet support.
9039 For legacy reasons DNS UDP replies will default to 512 bytes which
9040 is too small for many responses. EDNS provides a means for Squid to
9041 negotiate receiving larger responses back immediately without having
9042 to failover with repeat requests. Responses larger than this limit
9043 will retain the old behaviour of failover to TCP DNS.
9045 Squid has no real fixed limit internally, but allowing packet sizes
9046 over 1500 bytes requires network jumbogram support and is usually not
9049 WARNING: The RFC also indicates that some older resolvers will reply
9050 with failure of the whole request if the extension is added. Some
9051 resolvers have already been identified which will reply with mangled
9052 EDNS response on occasion. Usually in response to many-KB jumbogram
9053 sizes being advertised by Squid.
9054 Squid will currently treat these both as an unable-to-resolve domain
9055 even if it would be resolvable without EDNS.
9062 DEFAULT_DOC: Search for single-label domain names is disabled.
9063 LOC: Config.onoff.res_defnames
9065 Normally the RES_DEFNAMES resolver option is disabled
9066 (see res_init(3)). This prevents caches in a hierarchy
9067 from interpreting single-component hostnames locally. To allow
9068 Squid to handle single-component names, enable this option.
9071 NAME: dns_multicast_local
9075 DEFAULT_DOC: Search for .local and .arpa names is disabled.
9076 LOC: Config.onoff.dns_mdns
9078 When set to on, Squid sends multicast DNS lookups on the local
9079 network for domains ending in .local and .arpa.
9080 This enables local servers and devices to be contacted in an
9081 ad-hoc or zero-configuration network environment.
9084 NAME: dns_nameservers
9087 DEFAULT_DOC: Use operating system definitions
9088 LOC: Config.dns_nameservers
9090 Use this if you want to specify a list of DNS name servers
9091 (IP addresses) to use instead of those given in your
9092 /etc/resolv.conf file.
9094 On Windows platforms, if no value is specified here or in
9095 the /etc/resolv.conf file, the list of DNS name servers are
9096 taken from the Windows registry, both static and dynamic DHCP
9097 configurations are supported.
9099 Example: dns_nameservers 10.0.0.1 192.172.0.4
9104 DEFAULT: @DEFAULT_HOSTS@
9105 LOC: Config.etcHostsPath
9107 Location of the host-local IP name-address associations
9108 database. Most Operating Systems have such a file on different
9110 - Un*X & Linux: /etc/hosts
9111 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
9112 (%SystemRoot% value install default is c:\winnt)
9113 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
9114 (%SystemRoot% value install default is c:\windows)
9115 - Windows 9x/Me: %windir%\hosts
9116 (%windir% value is usually c:\windows)
9117 - Cygwin: /etc/hosts
9119 The file contains newline-separated definitions, in the
9120 form ip_address_in_dotted_form name [name ...] names are
9121 whitespace-separated. Lines beginning with an hash (#)
9122 character are comments.
9124 The file is checked at startup and upon configuration.
9125 If set to 'none', it won't be checked.
9126 If append_domain is used, that domain will be added to
9127 domain-local (i.e. not containing any dot character) host
9133 LOC: Config.appendDomain
9135 DEFAULT_DOC: Use operating system definitions
9137 Appends local domain name to hostnames without any dots in
9138 them. append_domain must begin with a period.
9140 Be warned there are now Internet names with no dots in
9141 them using only top-domain names, so setting this may
9142 cause some Internet sites to become unavailable.
9145 append_domain .yourdomain.com
9148 NAME: ignore_unknown_nameservers
9150 LOC: Config.onoff.ignore_unknown_nameservers
9153 By default Squid checks that DNS responses are received
9154 from the same IP addresses they are sent to. If they
9155 don't match, Squid ignores the response and writes a warning
9156 message to cache.log. You can allow responses from unknown
9157 nameservers by setting this option to 'off'.
9163 LOC: Config.dns.v4_first
9165 With the IPv6 Internet being as fast or faster than IPv4 Internet
9166 for most networks Squid prefers to contact websites over IPv6.
9168 This option reverses the order of preference to make Squid contact
9169 dual-stack websites over IPv4 first. Squid will still perform both
9170 IPv6 and IPv4 DNS lookups before connecting.
9173 This option will restrict the situations under which IPv6
9174 connectivity is used (and tested). Hiding network problems
9175 which would otherwise be detected and warned about.
9179 COMMENT: (number of entries)
9182 LOC: Config.ipcache.size
9184 Maximum number of DNS IP cache entries.
9191 LOC: Config.ipcache.low
9198 LOC: Config.ipcache.high
9200 The size, low-, and high-water marks for the IP cache.
9203 NAME: fqdncache_size
9204 COMMENT: (number of entries)
9207 LOC: Config.fqdncache.size
9209 Maximum number of FQDN cache entries.
9214 -----------------------------------------------------------------------------
9217 NAME: configuration_includes_quoted_values
9219 TYPE: configuration_includes_quoted_values
9221 LOC: ConfigParser::RecognizeQuotedValues
9223 If set, Squid will recognize each "quoted string" after a configuration
9224 directive as a single parameter. The quotes are stripped before the
9225 parameter value is interpreted or used.
9226 See "Values with spaces, quotes, and other special characters"
9227 section for more details.
9234 LOC: Config.onoff.mem_pools
9236 If set, Squid will keep pools of allocated (but unused) memory
9237 available for future use. If memory is a premium on your
9238 system and you believe your malloc library outperforms Squid
9239 routines, disable this.
9242 NAME: memory_pools_limit
9246 LOC: Config.MemPools.limit
9248 Used only with memory_pools on:
9249 memory_pools_limit 50 MB
9251 If set to a non-zero value, Squid will keep at most the specified
9252 limit of allocated (but unused) memory in memory pools. All free()
9253 requests that exceed this limit will be handled by your malloc
9254 library. Squid does not pre-allocate any memory, just safe-keeps
9255 objects that otherwise would be free()d. Thus, it is safe to set
9256 memory_pools_limit to a reasonably high value even if your
9257 configuration will use less memory.
9259 If set to none, Squid will keep all memory it can. That is, there
9260 will be no limit on the total amount of memory used for safe-keeping.
9262 To disable memory allocation optimization, do not set
9263 memory_pools_limit to 0 or none. Set memory_pools to "off" instead.
9265 An overhead for maintaining memory pools is not taken into account
9266 when the limit is checked. This overhead is close to four bytes per
9267 object kept. However, pools may actually _save_ memory because of
9268 reduced memory thrashing in your malloc library.
9272 COMMENT: on|off|transparent|truncate|delete
9275 LOC: opt_forwarded_for
9277 If set to "on", Squid will append your client's IP address
9278 in the HTTP requests it forwards. By default it looks like:
9280 X-Forwarded-For: 192.1.2.3
9282 If set to "off", it will appear as
9284 X-Forwarded-For: unknown
9286 If set to "transparent", Squid will not alter the
9287 X-Forwarded-For header in any way.
9289 If set to "delete", Squid will delete the entire
9290 X-Forwarded-For header.
9292 If set to "truncate", Squid will remove all existing
9293 X-Forwarded-For entries, and place the client IP as the sole entry.
9296 NAME: cachemgr_passwd
9297 TYPE: cachemgrpasswd
9299 DEFAULT_DOC: No password. Actions which require password are denied.
9300 LOC: Config.passwd_list
9302 Specify passwords for cachemgr operations.
9304 Usage: cachemgr_passwd password action action ...
9306 Some valid actions are (see cache manager menu for a full list):
9346 * Indicates actions which will not be performed without a
9347 valid password, others can be performed if not listed here.
9349 To disable an action, set the password to "disable".
9350 To allow performing an action without a password, set the
9353 Use the keyword "all" to set the same password for all actions.
9356 cachemgr_passwd secret shutdown
9357 cachemgr_passwd lesssssssecret info stats/objects
9358 cachemgr_passwd disable all
9365 LOC: Config.onoff.client_db
9367 If you want to disable collecting per-client statistics,
9368 turn off client_db here.
9371 NAME: refresh_all_ims
9375 LOC: Config.onoff.refresh_all_ims
9377 When you enable this option, squid will always check
9378 the origin server for an update when a client sends an
9379 If-Modified-Since request. Many browsers use IMS
9380 requests when the user requests a reload, and this
9381 ensures those clients receive the latest version.
9383 By default (off), squid may return a Not Modified response
9384 based on the age of the cached version.
9387 NAME: reload_into_ims
9388 IFDEF: USE_HTTP_VIOLATIONS
9392 LOC: Config.onoff.reload_into_ims
9394 When you enable this option, client no-cache or ``reload''
9395 requests will be changed to If-Modified-Since requests.
9396 Doing this VIOLATES the HTTP standard. Enabling this
9397 feature could make you liable for problems which it
9400 see also refresh_pattern for a more selective approach.
9403 NAME: connect_retries
9405 LOC: Config.connect_retries
9407 DEFAULT_DOC: Do not retry failed connections.
9409 This sets the maximum number of connection attempts made for each
9410 TCP connection. The connect_retries attempts must all still
9411 complete within the connection timeout period.
9413 The default is not to re-try if the first connection attempt fails.
9414 The (not recommended) maximum is 10 tries.
9416 A warning message will be generated if it is set to a too-high
9417 value and the configured value will be over-ridden.
9419 Note: These re-tries are in addition to forward_max_tries
9420 which limit how many different addresses may be tried to find
9424 NAME: retry_on_error
9426 LOC: Config.retry.onerror
9429 If set to ON Squid will automatically retry requests when
9430 receiving an error response with status 403 (Forbidden),
9431 500 (Internal Error), 501 or 503 (Service not available).
9432 Status 502 and 504 (Gateway errors) are always retried.
9434 This is mainly useful if you are in a complex cache hierarchy to
9435 work around access control errors.
9437 NOTE: This retry will attempt to find another working destination.
9438 Which is different from the server which just failed.
9441 NAME: as_whois_server
9443 LOC: Config.as_whois_server
9444 DEFAULT: whois.ra.net
9446 WHOIS server to query for AS numbers. NOTE: AS numbers are
9447 queried only when Squid starts up, not for every request.
9452 LOC: Config.onoff.offline
9455 Enable this option and Squid will never try to validate cached
9459 NAME: uri_whitespace
9460 TYPE: uri_whitespace
9461 LOC: Config.uri_whitespace
9464 What to do with requests that have whitespace characters in the
9467 strip: The whitespace characters are stripped out of the URL.
9468 This is the behavior recommended by RFC2396 and RFC3986
9469 for tolerant handling of generic URI.
9470 NOTE: This is one difference between generic URI and HTTP URLs.
9472 deny: The request is denied. The user receives an "Invalid
9474 This is the behaviour recommended by RFC2616 for safe
9475 handling of HTTP request URL.
9477 allow: The request is allowed and the URI is not changed. The
9478 whitespace characters remain in the URI. Note the
9479 whitespace is passed to redirector processes if they
9481 Note this may be considered a violation of RFC2616
9482 request parsing where whitespace is prohibited in the
9485 encode: The request is allowed and the whitespace characters are
9486 encoded according to RFC1738.
9488 chop: The request is allowed and the URI is chopped at the
9492 NOTE the current Squid implementation of encode and chop violates
9493 RFC2616 by not using a 301 redirect after altering the URL.
9498 LOC: Config.chroot_dir
9501 Specifies a directory where Squid should do a chroot() while
9502 initializing. This also causes Squid to fully drop root
9503 privileges after initializing. This means, for example, if you
9504 use a HTTP port less than 1024 and try to reconfigure, you may
9505 get an error saying that Squid can not open the port.
9508 NAME: balance_on_multiple_ip
9510 LOC: Config.onoff.balance_on_multiple_ip
9513 Modern IP resolvers in squid sort lookup results by preferred access.
9514 By default squid will use these IP in order and only rotates to
9515 the next listed when the most preffered fails.
9517 Some load balancing servers based on round robin DNS have been
9518 found not to preserve user session state across requests
9519 to different IP addresses.
9521 Enabling this directive Squid rotates IP's per request.
9524 NAME: pipeline_prefetch
9525 TYPE: pipelinePrefetch
9526 LOC: Config.pipeline_max_prefetch
9528 DEFAULT_DOC: Do not pre-parse pipelined requests.
9530 HTTP clients may send a pipeline of 1+N requests to Squid using a
9531 single connection, without waiting for Squid to respond to the first
9532 of those requests. This option limits the number of concurrent
9533 requests Squid will try to handle in parallel. If set to N, Squid
9534 will try to receive and process up to 1+N requests on the same
9535 connection concurrently.
9537 Defaults to 0 (off) for bandwidth management and access logging
9540 NOTE: pipelining requires persistent connections to clients.
9542 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication.
9545 NAME: high_response_time_warning
9548 LOC: Config.warnings.high_rptm
9550 DEFAULT_DOC: disabled.
9552 If the one-minute median response time exceeds this value,
9553 Squid prints a WARNING with debug level 0 to get the
9554 administrators attention. The value is in milliseconds.
9557 NAME: high_page_fault_warning
9559 LOC: Config.warnings.high_pf
9561 DEFAULT_DOC: disabled.
9563 If the one-minute average page fault rate exceeds this
9564 value, Squid prints a WARNING with debug level 0 to get
9565 the administrators attention. The value is in page faults
9569 NAME: high_memory_warning
9571 LOC: Config.warnings.high_memory
9572 IFDEF: HAVE_MSTATS&&HAVE_GNUMALLOC_H
9574 DEFAULT_DOC: disabled.
9576 If the memory usage (as determined by gnumalloc, if available and used)
9577 exceeds this amount, Squid prints a WARNING with debug level 0 to get
9578 the administrators attention.
9580 # TODO: link high_memory_warning to mempools?
9582 NAME: sleep_after_fork
9583 COMMENT: (microseconds)
9585 LOC: Config.sleep_after_fork
9588 When this is set to a non-zero value, the main Squid process
9589 sleeps the specified number of microseconds after a fork()
9590 system call. This sleep may help the situation where your
9591 system reports fork() failures due to lack of (virtual)
9592 memory. Note, however, if you have a lot of child
9593 processes, these sleep delays will add up and your
9594 Squid will not service requests for some amount of time
9595 until all the child processes have been started.
9596 On Windows value less then 1000 (1 milliseconds) are
9600 NAME: windows_ipaddrchangemonitor
9601 IFDEF: _SQUID_WINDOWS_
9605 LOC: Config.onoff.WIN32_IpAddrChangeMonitor
9607 On Windows Squid by default will monitor IP address changes and will
9608 reconfigure itself after any detected event. This is very useful for
9609 proxies connected to internet with dial-up interfaces.
9610 In some cases (a Proxy server acting as VPN gateway is one) it could be
9611 desiderable to disable this behaviour setting this to 'off'.
9612 Note: after changing this, Squid service must be restarted.
9617 IFDEF: USE_SQUID_EUI
9619 LOC: Eui::TheConfig.euiLookup
9621 Whether to lookup the EUI or MAC address of a connected client.
9624 NAME: max_filedescriptors max_filedesc
9627 DEFAULT_DOC: Use operating system limits set by ulimit.
9628 LOC: Config.max_filedescriptors
9630 Reduce the maximum number of filedescriptors supported below
9631 the usual operating system defaults.
9633 Remove from squid.conf to inherit the current ulimit setting.
9635 Note: Changing this requires a restart of Squid. Also
9636 not all I/O types supports large values (eg on Windows).
9639 NAME: force_request_body_continuation
9641 LOC: Config.accessList.forceRequestBodyContinuation
9643 DEFAULT_DOC: Deny, unless rules exist in squid.conf.
9645 This option controls how Squid handles data upload requests from HTTP
9646 and FTP agents that require a "Please Continue" control message response
9647 to actually send the request body to Squid. It is mostly useful in
9648 adaptation environments.
9650 When Squid receives an HTTP request with an "Expect: 100-continue"
9651 header or an FTP upload command (e.g., STOR), Squid normally sends the
9652 request headers or FTP command information to an adaptation service (or
9653 peer) and waits for a response. Most adaptation services (and some
9654 broken peers) may not respond to Squid at that stage because they may
9655 decide to wait for the HTTP request body or FTP data transfer. However,
9656 that request body or data transfer may never come because Squid has not
9657 responded with the HTTP 100 or FTP 150 (Please Continue) control message
9658 to the request sender yet!
9660 An allow match tells Squid to respond with the HTTP 100 or FTP 150
9661 (Please Continue) control message on its own, before forwarding the
9662 request to an adaptation service or peer. Such a response usually forces
9663 the request sender to proceed with sending the body. A deny match tells
9664 Squid to delay that control response until the origin server confirms
9665 that the request body is needed. Delaying is the default behavior.
9668 NAME: server_pconn_for_nonretriable
9671 DEFAULT_DOC: Open new connections for forwarding requests Squid cannot retry safely.
9672 LOC: Config.accessList.serverPconnForNonretriable
9674 This option provides fine-grained control over persistent connection
9675 reuse when forwarding HTTP requests that Squid cannot retry. It is useful
9676 in environments where opening new connections is very expensive
9677 (e.g., all connections are secured with TLS with complex client and server
9678 certificate validation) and race conditions associated with persistent
9679 connections are very rare and/or only cause minor problems.
9681 HTTP prohibits retrying unsafe and non-idempotent requests (e.g., POST).
9682 Squid limitations also prohibit retrying all requests with bodies (e.g., PUT).
9683 By default, when forwarding such "risky" requests, Squid opens a new
9684 connection to the server or cache_peer, even if there is an idle persistent
9685 connection available. When Squid is configured to risk sending a non-retriable
9686 request on a previously used persistent connection, and the server closes
9687 the connection before seeing that risky request, the user gets an error response
9688 from Squid. In most cases, that error response will be HTTP 502 (Bad Gateway)
9689 with ERR_ZERO_SIZE_OBJECT or ERR_WRITE_ERROR (peer connection reset) error detail.
9691 If an allow rule matches, Squid reuses an available idle persistent connection
9692 (if any) for the request that Squid cannot retry. If a deny rule matches, then
9693 Squid opens a new connection for the request that Squid cannot retry.
9695 This option does not affect requests that Squid can retry. They will reuse idle
9696 persistent connections (if any).
9698 This clause only supports fast acl types.
9699 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
9702 acl SpeedIsWorthTheRisk method POST
9703 server_pconn_for_nonretriable allow SpeedIsWorthTheRisk
projects / thirdparty / squid.git / blob