-## Copyright (C) 1996-2018 The Squid Software Foundation and contributors
+## Copyright (C) 1996-2021 The Squid Software Foundation and contributors
##
## Squid software is distributed under GPLv2+ license and includes
## contributions from numerous individuals and organizations.
MB - Megabyte
GB - Gigabyte
+ Values with time units
+
+ Time-related directives marked with either "time-units" or
+ "time-units-small" accept a time unit. The supported time units are:
+
+ nanosecond (time-units-small only)
+ microsecond (time-units-small only)
+ millisecond
+ second
+ minute
+ hour
+ day
+ week
+ fortnight
+ month - 30 days
+ year - 31557790080 milliseconds (just over 365 days)
+ decade
+
Values with spaces, quotes, and other special characters
Squid supports directive parameters with spaces, quotes, and other
files using the syntax:
parameters("/path/filename")
For example:
- acl whitelist dstdomain parameters("/etc/squid/whitelist.txt")
+ acl allowlist dstdomain parameters("/etc/squid/allowlist.txt")
Conditional configuration
This option is not yet supported by Squid-3.
DOC_END
+# Options removed in 5.x
+NAME: dns_v4_first
+TYPE: obsolete
+DOC_START
+ Remove this line. Squid no longer supports preferential treatment of DNS A records.
+DOC_END
+
# Options removed in 4.x
NAME: cache_peer_domain cache_host_domain
TYPE: obsolete
DOC_END
# Options Removed in 3.2
+NAME: balance_on_multiple_ip
+TYPE: obsolete
+DOC_START
+ Remove this line. Squid performs a 'Happy Eyeballs' algorithm, this multiple-IP algorithm is not longer relevant.
+DOC_END
+
NAME: chunked_request_body_max_size
TYPE: obsolete
DOC_START
The expanded key_extras value is added to the Squid credentials
cache and, hence, will affect authentication. It can be used to
- autenticate different users with identical user names (e.g.,
+ authenticate different users with identical user names (e.g.,
when user authentication depends on http_port).
Avoid adding frequently changing information to key_extras. For
"children" numberofchildren [startup=N] [idle=N] [concurrency=N]
[queue-size=N] [on-persistent-overload=action]
+ [reservation-timeout=seconds]
The maximum number of authenticator processes to spawn. If
you start too few Squid will have to wait for them to process
NOTE: NTLM and Negotiate schemes do not support concurrency
in the Squid code module even though some helpers can.
+ The reservation-timeout=seconds option allows NTLM and Negotiate
+ helpers to forget about clients that abandon their in-progress
+ connection authentication without closing the connection. The
+ timeout is measured since the last helper response received by
+ Squid for the client. Fractional seconds are not supported.
+
+ After the timeout, the helper will be used for other clients if
+ there are no unreserved helpers available. In the latter case,
+ the old client attempt to resume authentication will not be
+ forwarded to the helper (and the client should open a new HTTP
+ connection and retry authentication from scratch).
+
+ By default, reservations do not expire and clients that keep
+ their connections open without completing authentication may
+ exhaust all NTLM and Negotiate helpers.
+
"keep_alive" on|off
If you experience problems with PUT/POST requests when using
the NTLM or Negotiate schemes then you can try setting this
For Basic and Digest this parameter is ignored.
"utf8" on|off
- HTTP uses iso-latin-1 as character set, while some
- authentication backends such as LDAP expects UTF-8. If this is
- set to on Squid will translate the HTTP iso-latin-1 charset to
- UTF-8 before sending the username and password to the helper.
+ Useful for sending credentials to authentication backends that
+ expect UTF-8 encoding (e.g., LDAP).
- For NTLM and Negotiate this parameter is ignored.
+ When this option is enabled, Squid uses HTTP Accept-Language
+ request header to guess the received credentials encoding
+ (ISO-Latin-1, CP1251, or UTF-8) and then converts the first
+ two encodings into UTF-8.
+
+ When this option is disabled and by default, Squid sends
+ credentials in their original (i.e. received) encoding.
+
+ This parameter is only honored for Basic and Digest schemes.
+ For Basic, the entire username:password credentials are
+ checked and, if necessary, re-encoded. For Digest -- just the
+ username component. For NTLM and Negotiate schemes, this
+ parameter is ignored.
IF HAVE_AUTH_MODULE_BASIC
=== Basic authentication parameters ===
If you do not specify a DATA macro inside FORMAT,
Squid automatically appends %DATA to your FORMAT.
+ Note that Squid-3.x may expand %DATA to whitespace
+ or nothing in this case.
By default, Squid applies URL-encoding to each ACL
argument inside the argument string. If an explicit
(e.g., with %#DATA, spaces between arguments become
%20).
- If SSL is enabled, the following formating codes become available:
+ If SSL is enabled, the following formatting codes become available:
%USER_CERT SSL User certificate in PEM format
%USER_CERTCHAIN SSL User certificate chain in PEM format
DEFAULT: all src all
DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
DEFAULT: localhost src 127.0.0.1/32 ::1
-DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
+DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1/128 ::/128
DEFAULT: CONNECT method CONNECT
DEFAULT_DOC: ACLs all, manager, localhost, to_localhost, and CONNECT are predefined.
DOC_START
# regex matching on URL path [fast]
acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
- # ranges are alloed
+ # ranges are allowed
acl aclname localport 3128 ... # TCP port the client connected to [fast]
# NP: for interception mode this is usually '80'
# use REQUIRED to accept any valid username.
#
# Will use proxy authentication in forward-proxy scenarios, and plain
- # http authenticaiton in reverse-proxy scenarios
+ # http authentication in reverse-proxy scenarios
#
# NOTE: when a Proxy-Authentication header is sent but it is not
# needed during ACL checking the username is NOT logged
# acl hasWhatMyLoggingDaemonNeeds has request
# acl hasWhatMyLoggingDaemonNeeds has response
+acl aclname at_step step
+ # match against the current request processing step [fast]
+ # Valid steps are:
+ # GeneratingCONNECT: Generating HTTP CONNECT request headers
+IF USE_OPENSSL
+ # The following ssl_bump processing steps are recognized:
+ # SslBump1: After getting TCP-level and HTTP CONNECT info.
+ # SslBump2: After getting SSL Client Hello info.
+ # SslBump3: After getting SSL Server Hello info.
+ENDIF
+
IF USE_OPENSSL
acl aclname ssl_error errorname
# match against SSL certificate validation error [fast]
# The SHA1 digest algorithm is the default and is currently
# the only algorithm supported (-sha1).
- acl aclname at_step step
- # match against the current step during ssl_bump evaluation [fast]
- # Never matches and should not be used outside the ssl_bump context.
- #
- # At each SslBump step, Squid evaluates ssl_bump directives to find
- # the next bumping action (e.g., peek or splice). Valid SslBump step
- # values and the corresponding ssl_bump evaluation moments are:
- # SslBump1: After getting TCP-level and HTTP CONNECT info.
- # SslBump2: After getting SSL Client Hello info.
- # SslBump3: After getting SSL Server Hello info.
-
acl aclname ssl::server_name [option] .foo.com ...
# matches server name obtained from various sources [fast]
#
acl fileupload req_mime_type -i ^multipart/form-data$
acl javascript rep_mime_type -i ^application/x-javascript$
-NOCOMMENT_START
+CONFIG_START
#
# Recommended minimum configuration:
#
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
-NOCOMMENT_END
+CONFIG_END
DOC_END
NAME: proxy_protocol_access
This clause supports both fast and slow acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
-NOCOMMENT_START
+CONFIG_START
#
# Recommended minimum Access Permission configuration:
# And finally deny all other access to this proxy
http_access deny all
-NOCOMMENT_END
+CONFIG_END
DOC_END
NAME: adapted_http_access http_access2
Don't request client certificates
immediately, but wait until acl processing
requires a certificate (not yet implemented).
+ CONDITIONAL_AUTH
+ Request a client certificate during the TLS
+ handshake, but ignore certificate absence in
+ the TLS client Hello. If the client does
+ supply a certificate, it is validated.
NO_SESSION_REUSE
Don't allow for session reuse. Each connection
will result in a new SSL session.
require-proxy-header
Require PROXY protocol version 1 or 2 connections.
- The proxy_protocol_access is required to whitelist
+ The proxy_protocol_access is required to permit
downstream proxies which can be trusted.
+ worker-queues
+ Ask TCP stack to maintain a dedicated listening queue
+ for each worker accepting requests at this port.
+ Requires TCP stack that supports the SO_REUSEPORT socket
+ option.
+
+ SECURITY WARNING: Enabling worker-specific queues
+ allows any process running as Squid's effective user to
+ easily accept requests destined to this port.
+
If you run Squid on a dual-homed machine with an internal
and an external interface we recommend you to specify the
internal address:port in http_port. This way Squid will only be
visible on the internal address.
-NOCOMMENT_START
+CONFIG_START
# Squid normally listens to port 3128
http_port @DEFAULT_HTTP_PORT@
-NOCOMMENT_END
+CONFIG_END
DOC_END
NAME: https_port
min-version=1.N
The minimum TLS protocol version to permit.
To control SSLv3 use the options= parameter.
- Supported Values: 1.0 (default), 1.1, 1.2
+ Supported Values: 1.0 (default), 1.1, 1.2, 1.3
options=... Specify various TLS/SSL implementation options.
Specify the location and options of the executable for ssl_crt_validator
process.
- Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ...
+ Usage: sslcrtvalidator_program [ttl=...] [cache=n] path ...
Options:
- ttl=n TTL in seconds for cached results. The default is 60 secs
- cache=n limit the result cache size. The default value is 2048
+
+ cache=bytes
+ Limits how much memory Squid can use for caching validator
+ responses. The default is 67108864 (i.e. 64 MB).
+ Reconfiguration purges any excess entries. To disable caching,
+ use cache=0. Currently, cache entry sizes are seriously
+ underestimated. Even with that bug, a typical estimate for a
+ single cache entry size would be at least a few kilobytes (the
+ size of the PEM certificates sent to the validator).
+
+ ttl=<seconds|"infinity">
+ Approximately how long Squid may reuse the validator results
+ for. The default is 3600 (i.e. 1 hour). Using ttl=infinity
+ disables TTL checks. Reconfiguration does not affect TTLs of
+ the already cached entries. To disable caching, use zero cache
+ size, not zero TTL -- zero TTL allows reuse for the remainder
+ of the second when the result was cached.
DOC_END
NAME: sslcrtvalidator_children
concurrency=
The number of requests each certificate validator helper can handle in
- parallel. A value of 0 indicates the certficate validator does not
+ parallel. A value of 0 indicates the certificate validator does not
support concurrency. Defaults to 1.
When this directive is set to a value >= 1 then the protocol
TYPE: int
LOC: Config.forward_max_tries
DOC_START
- Controls how many different forward paths Squid will try
- before giving up. See also forward_timeout.
+ Limits the number of attempts to forward the request.
+
+ For the purpose of this limit, Squid counts all high-level request
+ forwarding attempts, including any same-destination retries after
+ certain persistent connection failures and any attempts to use a
+ different peer. However, low-level connection reopening attempts
+ (enabled using connect_retries) are not counted.
- NOTE: connect_retries (default: none) can make each of these
- possible forwarding paths be tried multiple times.
+ See also: forward_timeout and connect_retries.
DOC_END
COMMENT_START
NAME: cache_dir
TYPE: cachedir
DEFAULT: none
-DEFAULT_DOC: No disk cache. Store cache ojects only in memory.
+DEFAULT_DOC: No disk cache. Store cache objects only in memory.
LOC: Config.cacheSwap
DOC_START
Format:
Note: To make optimal use of the max-size limits you should order
the cache_dir lines with the smallest max-size value first.
-NOCOMMENT_START
+CONFIG_START
# Uncomment and adjust the following to add a disk cache directory.
#cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256
-NOCOMMENT_END
+CONFIG_END
DOC_END
NAME: store_dir_select_algorithm
cache_dir rock /ssd3 ... max-size=99999
DOC_END
+NAME: paranoid_hit_validation
+COMMENT: time-units-small
+TYPE: time_nanoseconds
+DEFAULT: 0
+DEFAULT_DOC: validation disabled
+LOC: Config.paranoid_hit_validation
+DOC_START
+ Controls whether Squid should perform paranoid validation of cache entry
+ metadata integrity every time a cache entry is hit. This low-level
+ validation should always succeed. Each failed validation results in a
+ cache miss, a BUG line reported to cache.log, and the invalid entry
+ marked as unusable (and eventually purged from the cache).
+
+ Squid can only validate shared cache memory and rock cache_dir entries.
+
+ * Zero (default) value means that the validation is disabled.
+
+ * Positive values enable validation:
+ - values less than 1 day approximate the maximum time that Squid is allowed
+ to spend validating a single cache hit.
+ - values greater or equal to 1 day are considered as no limitation:
+ in this case all checks will be performed, regardless of how much time
+ they take.
+
+ Hits are usually stored using 16KB slots (for rock, the size is
+ configurable via cache_dir slot-size). Larger hits require scanning more
+ slots and, hence, take more time. When validation is enabled, at least one
+ slot is always validated, regardless of the configured time limit.
+
+ A worker process validating an entry cannot do anything else (i.e. the
+ validation is blocking). The validation overhead is environment dependent,
+ but developers have observed Squid spending 3-10 microseconds to check each
+ slot of a Rock or shared memory hit entry. If Squid cuts validation short
+ because it runs out of configured time, it treats the entry as valid.
+
+ When hit validation is enabled, its statistics is included in Cache
+ Manager mgr:counters, mgr:5min, and mgr:60min reports.
+DOC_END
+
NAME: max_open_disk_fds
TYPE: int
LOC: Config.max_open_disk_fds
near the low-water mark.
As swap utilization increases towards the high-water mark set
- by cache_swap_high object eviction becomes more agressive.
+ by cache_swap_high object eviction becomes more aggressive.
The value difference in percentages between low- and high-water
marks represent an eviction rate of 300 objects per second and
- the rate continues to scale in agressiveness by multiples of
+ the rate continues to scale in aggressiveness by multiples of
this above the high-water mark.
Defaults are 90% and 95%. If you have a large cache, 5% could be
maintain utilization near the low-water mark.
As swap utilization increases towards this high-water mark object
- eviction becomes more agressive.
+ eviction becomes more aggressive.
The value difference in percentages between low- and high-water
marks represent an eviction rate of 300 objects per second and
- the rate continues to scale in agressiveness by multiples of
+ the rate continues to scale in aggressiveness by multiples of
this above the high-water mark.
Defaults are 90% and 95%. If you have a large cache, 5% could be
individual notes. There is currently no way to
specify both value and notes separators when logging
all notes with %note.
+ master_xaction The master transaction identifier is an unsigned
+ integer. These IDs are guaranteed to monotonically
+ increase within a single worker process lifetime, with
+ higher values corresponding to transactions that were
+ accepted or initiated later. Due to current implementation
+ deficiencies, some IDs are skipped (i.e. never logged).
+ Concurrent workers and restarted workers use similar,
+ overlapping sequences of master transaction IDs.
Connection related format codes:
>qos Client connection TOS/DSCP value set by Squid
>nfmark Client connection netfilter packet MARK set by Squid
+ transport::>connection_id Identifies a transport connection
+ accepted by Squid (e.g., a connection carrying the
+ logged HTTP request). Currently, Squid only supports
+ TCP transport connections.
+
+ The logged identifier is an unsigned integer. These
+ IDs are guaranteed to monotonically increase within a
+ single worker process lifetime, with higher values
+ corresponding to connections that were accepted later.
+ Many IDs are skipped (i.e. never logged). Concurrent
+ workers and restarted workers use similar, partially
+ overlapping sequences of IDs.
+
la Local listening IP address the client connection was connected to.
lp Local listening port number the client connection was connected to.
not available. Consider encoding the logged
value because Issuer often has spaces.
+ ssl::<cert
+ The received server x509 certificate in PEM
+ format, including BEGIN and END lines (or a
+ dash ('-') if the certificate is unavailable).
+
+ WARNING: Large certificates will exceed the
+ current 8KB access.log record limit, resulting
+ in truncated records. Such truncation usually
+ happens in the middle of a record field. The
+ limit applies to all access logging modules.
+
+ The logged certificate may have failed
+ validation and may not be trusted by Squid.
+ This field does not include any intermediate
+ certificates that may have been received from
+ the server or fetched during certificate
+ validation process.
+
+ Currently, Squid only collects server
+ certificates during step3 of SslBump
+ processing; connections that were not subject
+ to ssl_bump rules or that did not match a peek
+ or stare rule at step2 will not have the
+ server certificate information.
+
+ This field is using pass-through URL encoding
+ by default.
+
ssl::<cert_errors
The list of certificate validation errors
detected by Squid (including OpenSSL and
service name in curly braces to record response time(s) specific
to that service. For example: %{my_service}adapt::sum_trs
+ Format codes related to the PROXY protocol:
+
+ proxy_protocol::>h PROXY protocol header, including optional TLVs.
+
+ Supports the same field and element reporting/extraction logic
+ as %http::>h. For configuration and reporting purposes, Squid
+ maps each PROXY TLV to an HTTP header field: the TLV type
+ (configured as a decimal integer) is the field name, and the
+ TLV value is the field value. All TLVs of "LOCAL" connections
+ (in PROXY protocol terminology) are currently skipped/ignored.
+
+ Squid also maps the following standard PROXY protocol header
+ blocks to pseudo HTTP headers (their names use PROXY
+ terminology and start with a colon, following HTTP tradition
+ for pseudo headers): :command, :version, :src_addr, :dst_addr,
+ :src_port, and :dst_port.
+
+ Without optional parameters, this logformat code logs
+ pseudo headers and TLVs.
+
+ This format code uses pass-through URL encoding by default.
+
+ Example:
+ # relay custom PROXY TLV #224 to adaptation services
+ adaptation_meta Client-Foo "%proxy_protocol::>h{224}"
+
+ See also: %http::>h
+
The default formats available (which do not need re-defining) are:
logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
that exists, Squid will chdir() to that directory at startup
and coredump files will be left there.
-NOCOMMENT_START
+CONFIG_START
# Leave coredumps in the first cache dir
coredump_dir @DEFAULT_SWAP_DIR@
-NOCOMMENT_END
+CONFIG_END
DOC_END
straight to using PORT for IPv4 servers.
Some devices are known to not handle this extension correctly and
- may result in crashes. Devices which suport EPRT enough to fail
+ may result in crashes. Devices which support EPRT enough to fail
cleanly will result in Squid attempting PORT anyway. This directive
should only be disabled when EPRT results in device failures.
LOC: Config.Program.redirect
DEFAULT: none
DOC_START
- Specify the location of the executable URL rewriter to use.
- Since they can perform almost any function there isn't one included.
+ The name and command line parameters of an admin-provided executable
+ for redirecting clients or adjusting/replacing client request URLs.
- For each requested URL, the rewriter will receive on line with the format
+ This helper is consulted after the received request is cleared by
+ http_access and adapted using eICAP/ICAP services (if any). If the
+ helper does not redirect the client, Squid checks adapted_http_access
+ and may consult the cache or forward the request to the next hop.
- [channel-ID <SP>] URL [<SP> extras]<NL>
- See url_rewrite_extras on how to send "extras" with optional values to
- the helper.
- After processing the request the helper must reply using the following format:
+ For each request, the helper gets one line in the following format:
- [channel-ID <SP>] result [<SP> kv-pairs]
+ [channel-ID <SP>] request-URL [<SP> extras] <NL>
- The result code can be:
+ Use url_rewrite_extras to configure what Squid sends as 'extras'.
+
+
+ The helper must reply to each query using a single line:
+
+ [channel-ID <SP>] result [<SP> kv-pairs] <NL>
+
+ The result section must match exactly one of the following outcomes:
+
+ OK [status=30N] url="..."
- OK status=30N url="..."
- Redirect the URL to the one supplied in 'url='.
- 'status=' is optional and contains the status code to send
- the client in Squids HTTP response. It must be one of the
- HTTP redirect status codes: 301, 302, 303, 307, 308.
- When no status is given Squid will use 302.
+ Redirect the client to a URL supplied in the 'url' parameter.
+ Optional 'status' specifies the status code to send to the
+ client in Squid's HTTP redirect response. It must be one of
+ the standard HTTP redirect status codes: 301, 302, 303, 307,
+ or 308. When no specific status is requested, Squid uses 302.
OK rewrite-url="..."
- Rewrite the URL to the one supplied in 'rewrite-url='.
- The new URL is fetched directly by Squid and returned to
- the client as the response to its request.
+
+ Replace the current request URL with the one supplied in the
+ 'rewrite-url' parameter. Squid fetches the resource specified
+ by the new URL and forwards the received response (or its
+ cached copy) to the client.
+
+ WARNING: Avoid rewriting URLs! When possible, redirect the
+ client using an "OK url=..." helper response instead.
+ Rewriting URLs may create inconsistent requests and/or break
+ synchronization between internal client and origin server
+ states, especially when URLs or other message parts contain
+ snippets of that state. For example, Squid does not adjust
+ Location headers and embedded URLs after the helper rewrites
+ the request URL.
OK
- When neither of url= and rewrite-url= are sent Squid does
- not change the URL.
+ Keep the client request intact.
ERR
- Do not change the URL.
+ Keep the client request intact.
- BH
- An internal error occurred in the helper, preventing
- a result being identified. The 'message=' key name is
- reserved for delivering a log message.
+ BH [message="..."]
+ A helper problem that should be reported to the Squid admin
+ via a level-1 cache.log message. The 'message' parameter is
+ reserved for specifying the log message.
+ In addition to the kv-pairs mentioned above, Squid also understands
+ the following optional kv-pairs in URL rewriter responses:
- In addition to the above kv-pairs Squid also understands the following
- optional kv-pairs received from URL rewriters:
clt_conn_tag=TAG
Associates a TAG with the client TCP connection.
- The TAG is treated as a regular annotation but persists across
- future requests on the client connection rather than just the
- current request. A helper may update the TAG during subsequent
- requests be returning a new kv-pair.
- When using the concurrency= option the protocol is changed by
- introducing a query channel tag in front of the request/response.
- The query channel tag is a number between 0 and concurrency-1.
- This value must be echoed back unchanged to Squid as the first part
- of the response relating to its request.
+ The clt_conn_tag=TAG pair is treated as a regular transaction
+ annotation for the current request and also annotates future
+ requests on the same client connection. A helper may update
+ the TAG during subsequent requests by returning a new kv-pair.
- WARNING: URL re-writing ability should be avoided whenever possible.
- Use the URL redirect form of response instead.
- Re-write creates a difference in the state held by the client
- and server. Possibly causing confusion when the server response
- contains snippets of its view state. Embeded URLs, response
- and content Location headers, etc. are not re-written by this
- interface.
+ Helper messages contain the channel-ID part if and only if the
+ url_rewrite_children directive specifies positive concurrency. As a
+ channel-ID value, Squid sends a number between 0 and concurrency-1.
+ The helper must echo back the received channel-ID in its response.
- By default, a URL rewriter is not used.
+ By default, Squid does not use a URL rewriter.
DOC_END
NAME: url_rewrite_children redirect_children
DOC_START
This option puts an upper limit on how stale content Squid
will serve from the cache if cache validation fails.
- Can be overriden by the refresh_pattern max-stale option.
+ Can be overridden by the refresh_pattern max-stale option.
DOC_END
NAME: refresh_pattern
to change one. The default setting is only active if none is
used.
-NOCOMMENT_START
+CONFIG_START
#
# Add any of your own refresh_pattern entries above these.
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
-NOCOMMENT_END
+CONFIG_END
DOC_END
NAME: quick_abort_min
note key value acl ...
logformat myFormat ... %{key}note ...
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DOC_END
NAME: relaxed_header_parser
need an identification token to allow control targeting. Because
a farm of surrogates may all perform the same tasks, they may share
an identification token.
+
+ When the surrogate is a reverse-proxy, this ID is also
+ used as cdn-id for CDN-Loop detection (RFC 8586).
DOC_END
NAME: http_accel_surrogate_remote
DEFAULT_DOC: Address selected by the operating system.
IFDEF: USE_WCCP
DOC_START
- Use this option if you require WCCPv2 to use a specific
+ Use this option if you require WCCP(v1) to use a specific
interface address.
The default behavior is to not bind to any specific address.
DEFAULT_DOC: Address selected by the operating system.
IFDEF: USE_WCCPv2
DOC_START
- Use this option if you require WCCP to use a specific
+ Use this option if you require WCCPv2 to use a specific
interface address.
The default behavior is to not bind to any specific address.
you may also specify them by your custom file name:
Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
- By defaut Squid will send "403 Forbidden". A different 4xx or 5xx
+ By default Squid will send "403 Forbidden". A different 4xx or 5xx
may be specified by prefixing the file name with the code and a colon.
e.g. 404:ERR_CUSTOM_ACCESS_DENIED
Requires client_db to be enabled (the default).
- WARNING: This may noticably slow down traffic received via external proxies
+ WARNING: This may noticeably slow down traffic received via external proxies
or NAT devices and cause them to rebound error messages back to their clients.
DOC_END
Activation of the Partial Content extension is negotiated with each
ICAP service during OPTIONS exchange. Most ICAP servers should handle
- negotation correctly even if they do not support the extension, but
+ negotiation correctly even if they do not support the extension, but
some might fail. To disable Partial Content support for all ICAP
services and to avoid any negotiation, set this option to "off".
nameservers by setting this option to 'off'.
DOC_END
-NAME: dns_v4_first
-TYPE: onoff
-DEFAULT: off
-LOC: Config.dns.v4_first
-DOC_START
- With the IPv6 Internet being as fast or faster than IPv4 Internet
- for most networks Squid prefers to contact websites over IPv6.
-
- This option reverses the order of preference to make Squid contact
- dual-stack websites over IPv4 first. Squid will still perform both
- IPv6 and IPv4 DNS lookups before connecting.
-
- WARNING:
- This option will restrict the situations under which IPv6
- connectivity is used (and tested). Hiding network problems
- which would otherwise be detected and warned about.
-DOC_END
-
NAME: ipcache_size
COMMENT: (number of entries)
TYPE: int
DEFAULT: 0
DEFAULT_DOC: Do not retry failed connections.
DOC_START
- This sets the maximum number of connection attempts made for each
- TCP connection. The connect_retries attempts must all still
- complete within the connection timeout period.
+ Limits the number of reopening attempts when establishing a single
+ TCP connection. All these attempts must still complete before the
+ applicable connection opening timeout expires.
- The default is not to re-try if the first connection attempt fails.
- The (not recommended) maximum is 10 tries.
+ By default and when connect_retries is set to zero, Squid does not
+ retry failed connection opening attempts.
- A warning message will be generated if it is set to a too-high
- value and the configured value will be over-ridden.
+ The (not recommended) maximum is 10 tries. An attempt to configure a
+ higher value results in the value of 10 being used (with a warning).
- Note: These re-tries are in addition to forward_max_tries
- which limit how many different addresses may be tried to find
- a useful server.
+ Squid may open connections to retry various high-level forwarding
+ failures. For an outside observer, that activity may look like a
+ low-level connection reopening attempt, but those high-level retries
+ are governed by forward_max_tries instead.
+
+ See also: connect_timeout, forward_timeout, icap_connect_timeout,
+ ident_timeout, and forward_max_tries.
DOC_END
NAME: retry_on_error
get an error saying that Squid can not open the port.
DOC_END
-NAME: balance_on_multiple_ip
-TYPE: onoff
-LOC: Config.onoff.balance_on_multiple_ip
-DEFAULT: off
-DOC_START
- Modern IP resolvers in squid sort lookup results by preferred access.
- By default squid will use these IP in order and only rotates to
- the next listed when the most preffered fails.
-
- Some load balancing servers based on round robin DNS have been
- found not to preserve user session state across requests
- to different IP addresses.
-
- Enabling this directive Squid rotates IP's per request.
-DOC_END
-
NAME: pipeline_prefetch
TYPE: pipelinePrefetch
LOC: Config.pipeline_max_prefetch
NAME: max_filedescriptors max_filedesc
TYPE: int
DEFAULT: 0
-DEFAULT_DOC: Use operating system limits set by ulimit.
+DEFAULT_DOC: Use operating system soft limit set by ulimit.
LOC: Config.max_filedescriptors
DOC_START
- Reduce the maximum number of filedescriptors supported below
- the usual operating system defaults.
+ Set the maximum number of filedescriptors, either below the
+ operating system default or up to the hard limit.
- Remove from squid.conf to inherit the current ulimit setting.
+ Remove from squid.conf to inherit the current ulimit soft
+ limit setting.
Note: Changing this requires a restart of Squid. Also
not all I/O types supports large values (eg on Windows).
that the request body is needed. Delaying is the default behavior.
DOC_END
+NAME: http_upgrade_request_protocols
+TYPE: http_upgrade_request_protocols
+LOC: Config.http_upgrade_request_protocols
+DEFAULT: none
+DEFAULT_DOC: Upgrade header dropped, effectively blocking an upgrade attempt.
+DOC_START
+ Controls client-initiated and server-confirmed switching from HTTP to
+ another protocol (or to several protocols) using HTTP Upgrade mechanism
+ defined in RFC 7230 Section 6.7. Squid itself does not understand the
+ protocols being upgraded to and participates in the upgraded
+ communication only as a dumb TCP proxy. Admins should not allow
+ upgrading to protocols that require a more meaningful proxy
+ participation.
+
+ Usage: http_upgrade_request_protocols <protocol> allow|deny [!]acl ...
+
+ The required "protocol" parameter is either an all-caps word OTHER or an
+ explicit protocol name (e.g. "WebSocket") optionally followed by a slash
+ and a version token (e.g. "HTTP/3"). Explicit protocol names and
+ versions are case sensitive.
+
+ When an HTTP client sends an Upgrade request header, Squid iterates over
+ the client-offered protocols and, for each protocol P (with an optional
+ version V), evaluates the first non-empty set of
+ http_upgrade_request_protocols rules (if any) from the following list:
+
+ * All rules with an explicit protocol name equal to P.
+ * All rules that use OTHER instead of a protocol name.
+
+ In other words, rules using OTHER are considered for protocol P if and
+ only if there are no rules mentioning P by name.
+
+ If both of the above sets are empty, then Squid removes protocol P from
+ the Upgrade offer.
+
+ If the client sent a versioned protocol offer P/X, then explicit rules
+ referring to the same-name but different-version protocol P/Y are
+ declared inapplicable. Inapplicable rules are not evaluated (i.e. are
+ ignored). However, inapplicable rules still belong to the first set of
+ rules for P.
+
+ Within the applicable rule subset, individual rules are evaluated in
+ their configuration order. If all ACLs of an applicable "allow" rule
+ match, then the protocol offered by the client is forwarded to the next
+ hop as is. If all ACLs of an applicable "deny" rule match, then the
+ offer is dropped. If no applicable rules have matching ACLs, then the
+ offer is also dropped. The first matching rule also ends rules
+ evaluation for the offered protocol.
+
+ If all client-offered protocols are removed, then Squid forwards the
+ client request without the Upgrade header. Squid never sends an empty
+ Upgrade request header.
+
+ An Upgrade request header with a value violating HTTP syntax is dropped
+ and ignored without an attempt to use extractable individual protocol
+ offers.
+
+ Upon receiving an HTTP 101 (Switching Protocols) control message, Squid
+ checks that the server listed at least one protocol name and sent a
+ Connection:upgrade response header. Squid does not understand individual
+ protocol naming and versioning concepts enough to implement stricter
+ checks, but an admin can restrict HTTP 101 (Switching Protocols)
+ responses further using http_reply_access. Responses denied by
+ http_reply_access rules and responses flagged by the internal Upgrade
+ checks result in HTTP 502 (Bad Gateway) ERR_INVALID_RESP errors and
+ Squid-to-server connection closures.
+
+ If Squid sends an Upgrade request header, and the next hop (e.g., the
+ origin server) responds with an acceptable HTTP 101 (Switching
+ Protocols), then Squid forwards that message to the client and becomes
+ a TCP tunnel.
+
+ The presence of an Upgrade request header alone does not preclude cache
+ lookups. In other words, an Upgrade request might be satisfied from the
+ cache, using regular HTTP caching rules.
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
+ Each of the following groups of configuration lines represents a
+ separate configuration example:
+
+ # never upgrade to protocol Foo; all others are OK
+ http_upgrade_request_protocols Foo deny all
+ http_upgrade_request_protocols OTHER allow all
+
+ # only allow upgrades to protocol Bar (except for its first version)
+ http_upgrade_request_protocols Bar/1 deny all
+ http_upgrade_request_protocols Bar allow all
+ http_upgrade_request_protocols OTHER deny all # this rule is optional
+
+ # only allow upgrades to protocol Baz, and only if Baz is the only offer
+ acl UpgradeHeaderHasMultipleOffers ...
+ http_upgrade_request_protocols Baz deny UpgradeHeaderHasMultipleOffers
+ http_upgrade_request_protocols Baz allow all
+DOC_END
+
NAME: server_pconn_for_nonretriable
TYPE: acl_access
DEFAULT: none
server_pconn_for_nonretriable allow SpeedIsWorthTheRisk
DOC_END
+NAME: happy_eyeballs_connect_timeout
+COMMENT: (msec)
+TYPE: int
+DEFAULT: 250
+LOC: Config.happyEyeballs.connect_timeout
+DOC_START
+ This Happy Eyeballs (RFC 8305) tuning directive specifies the minimum
+ delay between opening a primary to-server connection and opening a
+ spare to-server connection for the same master transaction. This delay
+ is similar to the Connection Attempt Delay in RFC 8305, but it is only
+ applied to the first spare connection attempt. Subsequent spare
+ connection attempts use happy_eyeballs_connect_gap, and primary
+ connection attempts are not artificially delayed at all.
+
+ Terminology: The "primary" and "spare" designations are determined by
+ the order of DNS answers received by Squid: If Squid DNS AAAA query
+ was answered first, then primary connections are connections to IPv6
+ peer addresses (while spare connections use IPv4 addresses).
+ Similarly, if Squid DNS A query was answered first, then primary
+ connections are connections to IPv4 peer addresses (while spare
+ connections use IPv6 addresses).
+
+ Shorter happy_eyeballs_connect_timeout values reduce master
+ transaction response time, potentially improving user-perceived
+ response times (i.e., making user eyeballs happier). Longer delays
+ reduce both concurrent connection level and server bombardment with
+ connection requests, potentially improving overall Squid performance
+ and reducing the chance of being blocked by servers for opening too
+ many unused connections.
+
+ RFC 8305 prohibits happy_eyeballs_connect_timeout values smaller than
+ 10 (milliseconds) to "avoid congestion collapse in the presence of
+ high packet-loss rates".
+
+ The following Happy Eyeballs directives place additional connection
+ opening restrictions: happy_eyeballs_connect_gap and
+ happy_eyeballs_connect_limit.
+DOC_END
+
+NAME: happy_eyeballs_connect_gap
+COMMENT: (msec)
+TYPE: int
+DEFAULT: -1
+DEFAULT_DOC: no artificial delays between spare attempts
+LOC: Config.happyEyeballs.connect_gap
+DOC_START
+ This Happy Eyeballs (RFC 8305) tuning directive specifies the
+ minimum delay between opening spare to-server connections (to any
+ server; i.e. across all concurrent master transactions in a Squid
+ instance). Each SMP worker currently multiplies the configured gap
+ by the total number of workers so that the combined spare connection
+ opening rate of a Squid instance obeys the configured limit. The
+ workers do not coordinate connection openings yet; a micro burst
+ of spare connection openings may violate the configured gap.
+
+ This directive has similar trade-offs as
+ happy_eyeballs_connect_timeout, but its focus is on limiting traffic
+ amplification effects for Squid as a whole, while
+ happy_eyeballs_connect_timeout works on an individual master
+ transaction level.
+
+ The following Happy Eyeballs directives place additional connection
+ opening restrictions: happy_eyeballs_connect_timeout and
+ happy_eyeballs_connect_limit. See the former for related terminology.
+DOC_END
+
+NAME: happy_eyeballs_connect_limit
+TYPE: int
+DEFAULT: -1
+DEFAULT_DOC: no artificial limit on the number of concurrent spare attempts
+LOC: Config.happyEyeballs.connect_limit
+DOC_START
+ This Happy Eyeballs (RFC 8305) tuning directive specifies the
+ maximum number of spare to-server connections (to any server; i.e.
+ across all concurrent master transactions in a Squid instance).
+ Each SMP worker gets an equal share of the total limit. However,
+ the workers do not share the actual connection counts yet, so one
+ (busier) worker cannot "borrow" spare connection slots from another
+ (less loaded) worker.
+
+ Setting this limit to zero disables concurrent use of primary and
+ spare TCP connections: Spare connection attempts are made only after
+ all primary attempts fail. However, Squid would still use the
+ DNS-related optimizations of the Happy Eyeballs approach.
+
+ This directive has similar trade-offs as happy_eyeballs_connect_gap,
+ but its focus is on limiting Squid overheads, while
+ happy_eyeballs_connect_gap focuses on the origin server and peer
+ overheads.
+
+ The following Happy Eyeballs directives place additional connection
+ opening restrictions: happy_eyeballs_connect_timeout and
+ happy_eyeballs_connect_gap. See the former for related terminology.
+DOC_END
+
EOF