-## Copyright (C) 1996-2016 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
CAP_IPC_LOCK capability, or equivalent.
DOC_END
+NAME: hopeless_kid_revival_delay
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.hopelessKidRevivalDelay
+DEFAULT: 1 hour
+DOC_START
+ Normally, when a kid process dies, Squid immediately restarts the
+ kid. A kid experiencing frequent deaths is marked as "hopeless" for
+ the duration specified by this directive. Hopeless kids are not
+ automatically restarted.
+
+ Currently, zero values are not supported because they result in
+ misconfigured SMP Squid instances running forever, endlessly
+ restarting each dying kid. To effectively disable hopeless kids
+ revival, set the delay to a huge value (e.g., 1 year).
+
+ Reconfiguration also clears all hopeless kids designations, allowing
+ for manual revival of hopeless kids.
+DOC_END
+
COMMENT_START
OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
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
Concurrency must not be set unless it's known the helper
supports the input format with channel-ID fields.
- The queue-size=N option sets the maximum number of queued
- requests to N. The default maximum is 2*numberofchildren. Squid
- is allowed to temporarily exceed the configured maximum, marking
- the affected helper as "overloaded". If the helper overload
- lasts more than 3 minutes, the action prescribed by the
- on-persistent-overload option applies.
+ The queue-size option sets the maximum number of queued
+ requests. A request is queued when no existing child can
+ accept it due to concurrency limit and no new child can be
+ started due to numberofchildren limit. The default maximum is
+ 2*numberofchildren. Squid is allowed to temporarily exceed the
+ configured maximum, marking the affected helper as
+ "overloaded". If the helper overload lasts more than 3
+ minutes, the action prescribed by the on-persistent-overload
+ option applies.
The on-persistent-overload=action option specifies Squid
reaction to a new helper request arriving when the helper
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.
-IF HAVE_AUTH_MODULE_BASIC
- === Basic authentication parameters ===
+ 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
+ to off. This will cause Squid to forcibly close the connection
+ on the initial request where the browser asks which schemes
+ are supported by the proxy.
+
+ 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).
+
+ 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 ===
"credentialsttl" timetolive
Specifies how long squid assumes an externally validated
IF HAVE_AUTH_MODULE_DIGEST
=== Digest authentication parameters ===
- "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.
-
"nonce_garbage_interval" timeinterval
Specifies the interval that nonces that have been issued
to client_agent's are checked for validity.
incorrect request digest in POST requests when reusing the
same nonce as acquired earlier on a GET request.
-ENDIF
-IF HAVE_AUTH_MODULE_NEGOTIATE
- === Negotiate authentication parameters ===
-
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using
- the this authentication scheme then you can try setting this
- to off. This will cause Squid to forcibly close the connection
- on the initial request where the browser asks which schemes
- are supported by the proxy.
-
-ENDIF
-IF HAVE_AUTH_MODULE_NTLM
- === NTLM authentication parameters ===
-
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using
- the this authentication scheme then you can try setting this
- to off. This will cause Squid to forcibly close the connection
- on the initial request where the browser asks which schemes
- are supported by the proxy.
ENDIF
=== Example Configuration ===
#auth_param negotiate program <uncomment and complete this line to activate>
#auth_param negotiate children 20 startup=0 idle=1
-#auth_param negotiate keep_alive on
#
#auth_param digest program <uncomment and complete this line to activate>
#auth_param digest children 20 startup=0 idle=1
#
#auth_param ntlm program <uncomment and complete this line to activate>
#auth_param ntlm children 20 startup=0 idle=1
-#auth_param ntlm keep_alive on
#
#auth_param basic program <uncomment and complete this line>
#auth_param basic children 5 startup=5 idle=1
-#auth_param basic realm Squid proxy-caching web server
#auth_param basic credentialsttl 2 hours
DOC_END
NAME: authenticate_cache_garbage_interval
+IFDEF: USE_AUTH
TYPE: time_t
DEFAULT: 1 hour
-LOC: Config.authenticateGCInterval
+LOC: Auth::TheConfig.garbageCollectInterval
DOC_START
The time period between garbage collection across the username cache.
This is a trade-off between memory utilization (long intervals - say
DOC_END
NAME: authenticate_ttl
+IFDEF: USE_AUTH
TYPE: time_t
DEFAULT: 1 hour
-LOC: Config.authenticateTTL
+LOC: Auth::TheConfig.credentialsTtl
DOC_START
The time a user & their credentials stay in the logged in
user cache since their last request. When the garbage
DOC_END
NAME: authenticate_ip_ttl
+IFDEF: USE_AUTH
TYPE: time_t
-LOC: Config.authenticateIpTTL
+LOC: Auth::TheConfig.ipTtl
DEFAULT: 1 second
DOC_START
If you use proxy authentication and the 'max_user_ip' ACL,
concurrency=n concurrency level per process. Only used with helpers
capable of processing more than one query at a time.
- queue-size=N The queue-size= option sets the maximum number of queued
- requests. If the queued requests exceed queue size
- the acl is ignored.
- The default value is set to 2*children-max.
+ queue-size=N The queue-size option sets the maximum number of
+ queued requests. A request is queued when no existing
+ helper can accept it due to concurrency limit and no
+ new helper can be started due to children-max limit.
+ If the queued requests exceed queue size, the acl is
+ ignored. The default value is set to 2*children-max.
protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers.
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_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
+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
Defining an Access List
acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow]
acl aclname localip ip-address/mask ... # IP address the client connected to [fast]
- acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
+if USE_SQUID_EUI
+ acl aclname arp mac-address ...
+ acl aclname eui64 eui64-address ...
# [fast]
+ # MAC (EUI-48) and EUI-64 addresses use xx:xx:xx:xx:xx:xx notation.
+ #
# The 'arp' ACL code is not portable to all operating systems.
# It works on Linux, Solaris, Windows, FreeBSD, and some other
# BSD variants.
#
- # NOTE: Squid can only determine the MAC/EUI address for IPv4
+ # The eui_lookup directive is required to be 'on' (the default)
+ # and Squid built with --enable-eui for MAC/EUI addresses to be
+ # available for this ACL.
+ #
+ # Squid can only determine the MAC/EUI address for IPv4
# clients that are on the same subnet. If the client is on a
# different subnet, then Squid cannot find out its address.
#
- # NOTE 2: IPv6 protocol does not contain ARP. MAC/EUI is either
+ # IPv6 protocol does not contain ARP. MAC/EUI is either
# encoded directly in the IPv6 address or not available.
+endif
+ acl aclname clientside_mark mark[/mask] ...
+ # matches CONNMARK of an accepted connection [fast]
+ # DEPRECATED. Use the 'client_connection_mark' instead.
+
+ acl aclname client_connection_mark mark[/mask] ...
+ # matches CONNMARK of an accepted connection [fast]
+ #
+ # mark and mask are unsigned integers (hex, octal, or decimal).
+ # If multiple marks are given, then the ACL matches if at least
+ # one mark matches.
+ #
+ # Uses netfilter-conntrack library.
+ # Requires building Squid with --enable-linux-netfilter.
+ #
+ # The client, various intermediaries, and Squid itself may set
+ # CONNMARK at various times. The last CONNMARK set wins. This ACL
+ # checks the mark present on an accepted connection or set by
+ # Squid afterwards, depending on the ACL check timing. This ACL
+ # effectively ignores any mark set by other agents after Squid has
+ # accepted the connection.
acl aclname srcdomain .foo.com ...
# reverse lookup, from client IP [slow]
# cache_peer_access mycache_mydomain.net deny all
acl aclname peername myPeer ...
+ acl aclname peername_regex [-i] regex-pattern ...
# [fast]
# match against a named cache_peer entry
# set unique name= on cache_peer lines for reliable use.
# 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'
# pattern match on Referer header [fast]
# Referer is highly unreliable, so use with care
- acl aclname ident username ...
+ acl aclname ident [-i] username ...
acl aclname ident_regex [-i] pattern ...
# string match on ident output [slow]
# use REQUIRED to accept any non-null ident.
# 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
# match against attributes a users issuing CA SSL certificate
# attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]
- acl aclname ext_user username ...
+ acl aclname ext_user [-i] username ...
acl aclname ext_user_regex [-i] pattern ...
# string match on username returned by external acl helper [slow]
# use REQUIRED to accept any non-null user name.
# Annotation sources include note and adaptation_meta directives
# as well as helper and eCAP responses.
+ acl aclname annotate_transaction [-m[=delimiters]] key=value ...
+ acl aclname annotate_transaction [-m[=delimiters]] key+=value ...
+ # Always matches. [fast]
+ # Used for its side effect: This ACL immediately adds a
+ # key=value annotation to the current master transaction.
+ # The added annotation can then be tested using note ACL and
+ # logged (or sent to helpers) using %note format code.
+ #
+ # Annotations can be specified using replacement and addition
+ # formats. The key=value form replaces old same-key annotation
+ # value(s). The key+=value form appends a new value to the old
+ # same-key annotation. Both forms create a new key=value
+ # annotation if no same-key annotation exists already. If
+ # -m flag is used, then the value is interpreted as a list
+ # and the annotation will contain key=token pair(s) instead of the
+ # whole key=value pair.
+ #
+ # This ACL is especially useful for recording complex multi-step
+ # ACL-driven decisions. For example, the following configuration
+ # avoids logging transactions accepted after aclX matched:
+ #
+ # # First, mark transactions accepted after aclX matched
+ # acl markSpecial annotate_transaction special=true
+ # http_access allow acl001
+ # ...
+ # http_access deny acl100
+ # http_access allow aclX markSpecial
+ #
+ # # Second, do not log marked transactions:
+ # acl markedSpecial note special true
+ # access_log ... deny markedSpecial
+ #
+ # # Note that the following would not have worked because aclX
+ # # alone does not determine whether the transaction was allowed:
+ # access_log ... deny aclX # Wrong!
+ #
+ # Warning: This ACL annotates the transaction even when negated
+ # and even if subsequent ACLs fail to match. For example, the
+ # following three rules will have exactly the same effect as far
+ # as annotations set by the "mark" ACL are concerned:
+ #
+ # some_directive acl1 ... mark # rule matches if mark is reached
+ # some_directive acl1 ... !mark # rule never matches
+ # some_directive acl1 ... mark !all # rule never matches
+
+ acl aclname annotate_client [-m[=delimiters]] key=value ...
+ acl aclname annotate_client [-m[=delimiters]] key+=value ...
+ #
+ # Always matches. [fast]
+ # Used for its side effect: This ACL immediately adds a
+ # key=value annotation to the current client-to-Squid
+ # connection. Connection annotations are propagated to the current
+ # and all future master transactions on the annotated connection.
+ # See the annotate_transaction ACL for details.
+ #
+ # For example, the following configuration avoids rewriting URLs
+ # of transactions bumped by SslBump:
+ #
+ # # First, mark bumped connections:
+ # acl markBumped annotate_client bumped=true
+ # ssl_bump peek acl1
+ # ssl_bump stare acl2
+ # ssl_bump bump acl3 markBumped
+ # ssl_bump splice all
+ #
+ # # Second, do not send marked transactions to the redirector:
+ # acl markedBumped note bumped true
+ # url_rewrite_access deny markedBumped
+ #
+ # # Note that the following would not have worked because acl3 alone
+ # # does not determine whether the connection is going to be bumped:
+ # url_rewrite_access deny acl3 # Wrong!
+
acl aclname adaptation_service service ...
# Matches the name of any icap_service, ecap_service,
# adaptation_service_set, or adaptation_service_chain that Squid
# adaptation_meta because it starts matching immediately after
# the service has been selected for adaptation.
+ acl aclname transaction_initiator initiator ...
+ # Matches transaction's initiator [fast]
+ #
+ # Supported initiators are:
+ # esi: matches transactions fetching ESI resources
+ # certificate-fetching: matches transactions fetching
+ # a missing intermediate TLS certificate
+ # cache-digest: matches transactions fetching Cache Digests
+ # from a cache_peer
+ # htcp: matches HTCP requests from peers
+ # icp: matches ICP requests to peers
+ # icmp: matches ICMP RTT database (NetDB) requests to peers
+ # asn: matches asns db requests
+ # internal: matches any of the above
+ # client: matches transactions containing an HTTP or FTP
+ # client request received at a Squid *_port
+ # all: matches any transaction, including internal transactions
+ # without a configurable initiator and hopefully rare
+ # transactions without a known-to-Squid initiator
+ #
+ # Multiple initiators are ORed.
+
+ acl aclname has component
+ # matches a transaction "component" [fast]
+ #
+ # Supported transaction components are:
+ # request: transaction has a request header (at least)
+ # response: transaction has a response header (at least)
+ # ALE: transaction has an internally-generated Access Log Entry
+ # structure; bugs notwithstanding, all transaction have it
+ #
+ # For example, the following configuration helps when dealing with HTTP
+ # clients that close connections without sending a request header:
+ #
+ # acl hasRequest has request
+ # acl logMe note important_transaction
+ # # avoid "logMe ACL is used in context without an HTTP request" warnings
+ # access_log ... logformat=detailed hasRequest logMe
+ # # log request-less transactions, instead of ignoring them
+ # access_log ... logformat=brief !hasRequest
+ #
+ # Multiple components are not supported for one "acl" rule, but
+ # can be specified (and are ORed) using multiple same-name rules:
+ #
+ # # OK, this strange logging daemon needs request or response,
+ # # but can work without either a request or a response:
+ # 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 .foo.com ...
+ acl aclname ssl::server_name [option] .foo.com ...
# matches server name obtained from various sources [fast]
#
- # The server name is obtained during Ssl-Bump steps from such sources
- # as CONNECT request URI, client SNI, and SSL server certificate CN.
- # During each Ssl-Bump step, Squid may improve its understanding of a
- # "true server name". Unlike dstdomain, this ACL does not perform
- # DNS lookups.
- # The "none" name can be used to match transactions where Squid
+ # The ACL computes server name(s) using such information sources as
+ # CONNECT request URI, TLS client SNI, and TLS server certificate
+ # subject (CN and SubjectAltName). The computed server name(s) usually
+ # change with each SslBump step, as more info becomes available:
+ # * SNI is used as the server name instead of the request URI,
+ # * subject name(s) from the server certificate (CN and
+ # SubjectAltName) are used as the server names instead of SNI.
+ #
+ # When the ACL computes multiple server names, matching any single
+ # computed name is sufficient for the ACL to match.
+ #
+ # The "none" name can be used to match transactions where the ACL
# could not compute the server name using any information source
- # already available at the ACL evaluation time.
+ # that was both available and allowed to be used by the ACL options at
+ # the ACL evaluation time.
+ #
+ # Unlike dstdomain, this ACL does not perform DNS lookups.
+ #
+ # An ACL option below may be used to restrict what information
+ # sources are used to extract the server names from:
+ #
+ # --client-requested
+ # The server name is SNI regardless of what the server says.
+ # --server-provided
+ # The server name(s) are the certificate subject name(s), regardless
+ # of what the client has requested. If the server certificate is
+ # unavailable, then the name is "none".
+ # --consensus
+ # The server name is either SNI (if SNI matches at least one of the
+ # certificate subject names) or "none" (otherwise). When the server
+ # certificate is unavailable, the consensus server name is SNI.
+ #
+ # Combining multiple options in one ACL is a fatal configuration
+ # error.
+ #
+ # For all options: If no SNI is available, then the CONNECT request
+ # target (a.k.a. URI) is used instead of SNI (for an intercepted
+ # connection, this target is the destination IP address).
acl aclname ssl::server_name_regex [-i] \.foo\.com ...
# regex 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 localnet src 0.0.0.1-0.255.255.255 # RFC 1122 "this" network (LAN)
acl localnet src 10.0.0.0/8 # RFC 1918 local private network (LAN)
acl localnet src 100.64.0.0/10 # RFC 6598 shared address space (CGN)
-acl localhet src 169.254.0.0/16 # RFC 3927 link-local (directly plugged) machines
+acl localnet src 169.254.0.0/16 # RFC 3927 link-local (directly plugged) machines
acl localnet src 172.16.0.0/12 # RFC 1918 local private network (LAN)
acl localnet src 192.168.0.0/16 # RFC 1918 local private network (LAN)
acl localnet src fc00::/7 # RFC 4193 local private network range
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
-acl CONNECT method CONNECT
-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
TLS / SSL Options:
- cert= Path to SSL certificate (PEM format).
+ tls-cert= Path to file containing an X.509 certificate (PEM format)
+ to be used in the TLS handshake ServerHello.
+
+ If this certificate is constrained by KeyUsage TLS
+ feature it must allow HTTP server usage, along with
+ any additional restrictions imposed by your choice
+ of options= settings.
- key= Path to SSL private key file (PEM format)
- if not specified, the certificate file is
- assumed to be a combined certificate and
- key file.
+ When OpenSSL is used this file may also contain a
+ chain of intermediate CA certificates to send in the
+ TLS handshake.
+
+ When GnuTLS is used this option (and any paired
+ tls-key= option) may be repeated to load multiple
+ certificates for different domains.
+
+ Also, when generate-host-certificates=on is configured
+ the first tls-cert= option must be a CA certificate
+ capable of signing the automatically generated
+ certificates.
+
+ tls-key= Path to a file containing private key file (PEM format)
+ for the previous tls-cert= option.
+
+ If tls-key= is not specified tls-cert= is assumed to
+ reference a PEM file containing both the certificate
+ and private key.
cipher= Colon separated list of supported ciphers.
NOTE: some ciphers such as EDH ciphers depend on
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
DEFAULT: none
LOC: HttpPortList
DOC_START
- Usage: [ip:]port [mode] cert=certificate.pem [options]
+ Usage: [ip:]port [mode] tls-cert=certificate.pem [options]
The socket address where Squid will listen for client requests made
over TLS or SSL connections. Commonly referred to as HTTPS.
This is most useful for situations where you are running squid in
- accelerator mode and you want to do the TLS work at the accelerator level.
+ accelerator mode and you want to do the TLS work at the accelerator
+ level.
You may specify multiple socket addresses on multiple lines,
each with their own certificate and/or options.
- The TLS cert= option is mandatory on HTTPS ports.
+ The tls-cert= option is mandatory on HTTPS ports.
See http_port for a list of modes and options.
DOC_END
been redefined for use by ECN (RFC 3168 section 23.1).
The squid parser will enforce this by masking away the ECN bits.
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DOC_END
NAME: tcp_outgoing_mark
Only fast ACLs are supported.
DOC_END
-NAME: clientside_mark
+NAME: mark_client_packet clientside_mark
TYPE: acl_nfmark
IFDEF: SO_MARK&&USE_LIBCAP
DEFAULT: none
LOC: Ip::Qos::TheConfig.nfmarkToClient
DOC_START
- Allows you to apply a Netfilter mark value to packets being transmitted
+ Allows you to apply a Netfilter MARK value to packets being transmitted
on the client-side, based on an ACL.
- clientside_mark mark-value [!]aclname ...
+ mark_client_packet mark-value [!]aclname ...
- Example where normal_service_net uses the mark value 0x00
+ Example where normal_service_net uses the MARK value 0x00
and good_service_net uses 0x20
acl normal_service_net src 10.0.0.0/24
acl good_service_net src 10.0.1.0/24
- clientside_mark 0x00 normal_service_net
- clientside_mark 0x20 good_service_net
+ mark_client_packet 0x00 normal_service_net
+ mark_client_packet 0x20 good_service_net
Note: This feature is incompatible with qos_flows. Any mark values set here
will be overwritten by mark values in qos_flows.
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+DOC_END
+
+NAME: mark_client_connection
+TYPE: acl_nfmark
+IFDEF: SO_MARK&&USE_LIBCAP
+DEFAULT: none
+LOC: Ip::Qos::TheConfig.nfConnmarkToClient
+DOC_START
+ Allows you to apply a Netfilter CONNMARK value to a connection
+ on the client-side, based on an ACL.
+
+ mark_client_connection mark-value[/mask] [!]aclname ...
+
+ The mark-value and mask are unsigned integers (hex, octal, or decimal).
+ The mask may be used to preserve marking previously set by other agents
+ (e.g., iptables).
+
+ A matching rule replaces the CONNMARK value. If a mask is also
+ specified, then the masked bits of the original value are zeroed, and
+ the configured mark-value is ORed with that adjusted value.
+ For example, applying a mark-value 0xAB/0xF to 0x5F CONNMARK, results
+ in a 0xFB marking (rather than a 0xAB or 0x5B).
+
+ This directive semantics is similar to iptables --set-mark rather than
+ --set-xmark functionality.
+
+ The directive does not interfere with qos_flows (which uses packet MARKs,
+ not CONNMARKs).
+
+ Example where squid marks intercepted FTP connections:
+
+ acl proto_ftp proto FTP
+ mark_client_connection 0x200/0xff00 proto_ftp
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DOC_END
NAME: qos_flows
When needing to contact peers use the no-tproxy cache_peer option and the
client_dst_passthru directive re-enable normal forwarding such as this.
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DOC_END
NAME: host_verify_strict
disable Do not support https:// URLs.
cert=/path/to/client/certificate
- A client TLS certificate to use when connecting.
+ A client X.509 certificate to use when connecting.
key=/path/to/client/private_key
- The private TLS key corresponding to the cert= above.
- If key= is not specified cert= is assumed to reference
- a PEM file containing both the certificate and the key.
+ The private key corresponding to the cert= above.
+
+ If key= is not specified cert= is assumed to
+ reference a PEM file containing both the certificate
+ and private key.
cipher=... The list of valid TLS ciphers to use.
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
-
- options=... Specify various TLS/SSL implementation options:
+ Supported Values: 1.0 (default), 1.1, 1.2, 1.3
- NO_SSLv3 Disallow the use of SSLv3
-
- NO_TLSv1 Disallow the use of TLSv1.0
+ options=... Specify various TLS/SSL implementation options.
- NO_TLSv1_1 Disallow the use of TLSv1.1
+ OpenSSL options most important are:
- NO_TLSv1_2 Disallow the use of TLSv1.2
+ NO_SSLv3 Disallow the use of SSLv3
SINGLE_DH_USE
Always create a new key when using
Be warned that this reduces SSL/TLS
strength to some attacks.
- See the OpenSSL SSL_CTX_set_options documentation for a
- more complete list.
+ See the OpenSSL SSL_CTX_set_options documentation
+ for a more complete list.
+
+ GnuTLS options most important are:
+
+ %NO_TICKETS
+ Disable use of RFC5077 session tickets.
+ Some servers may have problems
+ understanding the TLS extension due
+ to ambiguous specification in RFC4507.
+
+ See the GnuTLS Priority Strings documentation
+ for a more complete list.
+ http://www.gnutls.org/manual/gnutls.html#Priority-Strings
+
cafile= PEM file containing CA certificates to use when verifying
the peer certificate. May be repeated to load multiple files.
This is the default action.
bump
- Establish a secure connection with the server and, using a
- mimicked server certificate, with the client.
+ When used on step SslBump1, establishes a secure connection
+ with the client first, then connect to the server.
+ When used on step SslBump2 or SslBump3, establishes a secure
+ connection with the server and, using a mimicked server
+ certificate, with the client.
peek
Receive client (step SslBump1) or server (step SslBump2)
DOC_START
Specify the location and options of the executable for certificate
generator.
- @DEFAULT_SSL_CRTD@ program requires -s and -M parameters
+
+ @DEFAULT_SSL_CRTD@ program can use a disk cache to improve response
+ times on repeated requests. To enable caching, specify -s and -M
+ parameters. If those parameters are not given, the program generates
+ a new certificate on every request.
+
For more information use:
@DEFAULT_SSL_CRTD@ -h
DOC_END
DEFAULT: 32 startup=5 idle=1
LOC: Ssl::TheConfig.ssl_crtdChildren
DOC_START
- The maximum number of processes spawn to service ssl server.
- The maximum this may be safely set to is 32.
-
+ Specifies the maximum number of certificate generation processes that
+ Squid may spawn (numberofchildren) and several related options. Using
+ too few of these helper processes (a.k.a. "helpers") creates request
+ queues. Using too many helpers wastes your system resources. Squid
+ does not support spawning more than 32 helpers.
+
+ Usage: numberofchildren [option]...
+
The startup= and idle= options allow some measure of skew in your
tuning.
queue-size=N
- Sets the maximum number of queued requests.
- If the queued requests exceed queue size for more than 3 minutes
- squid aborts its operation.
- The default value is set to 2*numberofchildren.
+ Sets the maximum number of queued requests. A request is queued when
+ no existing child is idle and no new child can be started due to
+ numberofchildren limit. If the queued requests exceed queue size for
+ more than 3 minutes squid aborts its operation. The default value is
+ set to 2*numberofchildren.
You must have at least one ssl_crtd process.
DOC_END
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
DEFAULT: 32 startup=5 idle=1 concurrency=1
LOC: Ssl::TheConfig.ssl_crt_validator_Children
DOC_START
- The maximum number of processes spawn to service SSL server.
- The maximum this may be safely set to is 32.
+ Specifies the maximum number of certificate validation processes that
+ Squid may spawn (numberofchildren) and several related options. Using
+ too few of these helper processes (a.k.a. "helpers") creates request
+ queues. Using too many helpers wastes your system resources. Squid
+ does not support spawning more than 32 helpers.
+
+ Usage: numberofchildren [option]...
The startup= and idle= options allow some measure of skew in your
tuning.
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
queue-size=N
- Sets the maximum number of queued requests.
- If the queued requests exceed queue size for more than 3 minutes
- squid aborts its operation.
- The default value is set to 2*numberofchildren.
+ Sets the maximum number of queued requests. A request is queued when
+ no existing child can accept it due to concurrency limit and no new
+ child can be started due to numberofchildren limit. If the queued
+ requests exceed queue size for more than 3 minutes squid aborts its
+ operation. The default value is set to 2*numberofchildren.
You must have at least one ssl_crt_validator process.
DOC_END
tls Encrypt connections to this peer with TLS.
sslcert=/path/to/ssl/certificate
- A client SSL certificate to use when connecting to
+ A client X.509 certificate to use when connecting to
this peer.
sslkey=/path/to/ssl/key
- The private SSL key corresponding to sslcert above.
- If 'sslkey' is not specified 'sslcert' is assumed to
- reference a combined file containing both the
- certificate and the key.
+ The private key corresponding to sslcert above.
+
+ If sslkey= is not specified sslcert= is assumed to
+ reference a PEM file containing both the certificate
+ and private key.
sslcipher=... The list of valid SSL ciphers to use when connecting
to this peer.
tls-min-version=1.N
The minimum TLS protocol version to permit. To control
- SSLv3 use the ssloptions= parameter.
+ SSLv3 use the tls-options= parameter.
Supported Values: 1.0 (default), 1.1, 1.2
- ssloptions=... Specify various SSL implementation options:
-
- NO_SSLv3 Disallow the use of SSLv3
-
- NO_TLSv1 Disallow the use of TLSv1.0
+ tls-options=... Specify various TLS implementation options.
- NO_TLSv1_1 Disallow the use of TLSv1.1
+ OpenSSL options most important are:
- NO_TLSv1_2 Disallow the use of TLSv1.2
+ NO_SSLv3 Disallow the use of SSLv3
SINGLE_DH_USE
Always create a new key when using
See the OpenSSL SSL_CTX_set_options documentation for a
more complete list.
-
+
+ GnuTLS options most important are:
+
+ %NO_TICKETS
+ Disable use of RFC5077 session tickets.
+ Some servers may have problems
+ understanding the TLS extension due
+ to ambiguous specification in RFC4507.
+
+ See the GnuTLS Priority Strings documentation
+ for a more complete list.
+ http://www.gnutls.org/manual/gnutls.html#Priority-Strings
+
tls-cafile= PEM file containing CA certificates to use when verifying
the peer certificate. May be repeated to load multiple files.
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
The <format specification> is a string with embedded % format codes
- % format codes all follow the same basic structure where all but
- the formatcode is optional. Output strings are automatically escaped
- as required according to their context and the output format
- modifiers are usually not needed, but can be specified if an explicit
- output format is desired.
+ % format codes all follow the same basic structure where all
+ components but the formatcode are optional and usually unnecessary,
+ especially when dealing with common codes.
+
+ % [encoding] [-] [[0]width] [{arg}] formatcode [{arg}]
+
+ encoding escapes or otherwise protects "special" characters:
+
+ " Quoted string encoding where quote(") and
+ backslash(\) characters are \-escaped while
+ CR, LF, and TAB characters are encoded as \r,
+ \n, and \t two-character sequences.
- % ["|[|'|#|/] [-] [[0]width] [{arg}] formatcode [{arg}]
+ [ Custom Squid encoding where percent(%), square
+ brackets([]), backslash(\) and characters with
+ codes outside of [32,126] range are %-encoded.
+ SP is not encoded. Used by log_mime_hdrs.
- " output in quoted string format
- [ output in squid text log format as used by log_mime_hdrs
- # output in URL quoted format
- / output in shell \-escaped format
- ' output as-is
+ # URL encoding (a.k.a. percent-encoding) where
+ all URL unsafe and control characters (per RFC
+ 1738) are %-encoded.
+
+ / Shell-like encoding where quote(") and
+ backslash(\) characters are \-escaped while CR
+ and LF characters are encoded as \r and \n
+ two-character sequences. Values containing SP
+ character(s) are surrounded by quotes(").
+
+ ' Raw/as-is encoding with no escaping/quoting.
+
+ Default encoding: When no explicit encoding is
+ specified, each %code determines its own encoding.
+ Most %codes use raw/as-is encoding, but some codes use
+ a so called "pass-through URL encoding" where all URL
+ unsafe and control characters (per RFC 1738) are
+ %-encoded, but the percent character(%) is left as is.
- left aligned
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:
>la Local IP address the client connected to
>lp Local port number the client connected to
>qos Client connection TOS/DSCP value set by Squid
- >nfmark Client connection netfilter mark 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.
<la Local IP address of the last server or peer connection
<lp Local port number of the last server or peer connection
<qos Server connection TOS/DSCP value set by Squid
- <nfmark Server connection netfilter mark set by Squid
+ <nfmark Server connection netfilter packet MARK set by Squid
+
+ >handshake Raw client handshake
+ Initial client bytes received by Squid on a newly
+ accepted TCP connection or inside a just established
+ CONNECT tunnel. Squid stops accumulating handshake
+ bytes as soon as the handshake parser succeeds or
+ fails (determining whether the client is using the
+ expected protocol).
+
+ For HTTP clients, the handshake is the request line.
+ For TLS clients, the handshake consists of all TLS
+ records up to and including the TLS record that
+ contains the last byte of the first ClientHello
+ message. For clients using an unsupported protocol,
+ this field contains the bytes received by Squid at the
+ time of the handshake parsing failure.
+
+ See the on_unsupported_protocol directive for more
+ information on Squid handshake traffic expectations.
+
+ Current support is limited to these contexts:
+ - http_port connections, but only when the
+ on_unsupported_protocol directive is in use.
+ - https_port connections (and CONNECT tunnels) that
+ are subject to the ssl_bump peek or stare action.
+
+ To protect binary handshake data, this field is always
+ base64-encoded (RFC 4648 Section 4). If logformat
+ field encoding is configured, that encoding is applied
+ on top of base64. Otherwise, the computed base64 value
+ is recorded as is.
Time related format codes:
[http::]rm Request method (GET/POST etc)
[http::]>rm Request method from client
[http::]<rm Request method sent to server or peer
- [http::]ru Request URL from client (historic, filtered for logging)
- [http::]>ru Request URL from client
+
+ [http::]ru Request URL received (or computed) and sanitized
+
+ Logs request URI received from the client, a
+ request adaptation service, or a request
+ redirector (whichever was applied last).
+
+ Computed URLs are URIs of internally generated
+ requests and various "error:..." URIs.
+
+ Honors strip_query_terms and uri_whitespace.
+
+ This field is not encoded by default. Encoding
+ this field using variants of %-encoding will
+ clash with uri_whitespace modifications that
+ also use %-encoding.
+
+ [http::]>ru Request URL received from the client (or computed)
+
+ Computed URLs are URIs of internally generated
+ requests and various "error:..." URIs.
+
+ Unlike %ru, this request URI is not affected
+ by request adaptation, URL rewriting services,
+ and strip_query_terms.
+
+ Honors uri_whitespace.
+
+ This field is using pass-through URL encoding
+ by default. Encoding this field using other
+ variants of %-encoding will clash with
+ uri_whitespace modifications that also use
+ %-encoding.
+
[http::]<ru Request URL sent to server or peer
[http::]>rs Request URL scheme from client
[http::]<rs Request URL scheme sent to server or peer
For CONNECT requests that initiated bumping of
a connection and for any request received on
an already bumped connection, Squid logs the
- corresponding SslBump mode ("server-first" or
- "client-first"). See the ssl_bump option for
- more information about these modes.
+ corresponding SslBump mode ("splice", "bump",
+ "peek", "stare", "terminate", "server-first"
+ or "client-first"). See the ssl_bump option
+ for more information about these modes.
A "none" token is logged for requests that
triggered "ssl_bump" ACL evaluation matching
- either a "none" rule or no rules at all.
+ a "none" rule.
In all other cases, a single dash ("-") is
logged.
- ssl::>sni SSL client SNI sent to Squid. Available only
- after the peek, stare, or splice SSL bumping
- actions.
+ ssl::>sni SSL client SNI sent to Squid.
ssl::>cert_subject
The Subject field of the received client
no certificate at all. Consider encoding the
logged value because Issuer often has spaces.
+ ssl::<cert_subject
+ The Subject field of the received server
+ TLS certificate or a dash ('-') if this is
+ not available. Consider encoding the logged
+ value because Subject often has spaces.
+
+ ssl::<cert_issuer
+ The Issuer field of the received server
+ TLS certificate or a dash ('-') if this is
+ 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
Note, from Squid-3.1 this option is only a default for cache.log,
that log can be rotated separately by using debug_options.
- Note, from Squid-3.6 this option is only a default for access.log
+ Note, from Squid-4 this option is only a default for access.log
recorded by stdio: module. Those logs can be rotated separately by
using the rotate=N option on their access_log directive.
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>
+
+ Use url_rewrite_extras to configure what Squid sends as 'extras'.
- The result code can be:
- 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.
+ 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="..."
+
+ 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
DEFAULT: 20 startup=0 idle=1 concurrency=0
LOC: Config.redirectChildren
DOC_START
- The maximum number of redirector processes to spawn. If you limit
- it too few Squid will have to wait for them to process a backlog of
- URLs, slowing it down. If you allow too many they will use RAM
- and other system resources noticably.
-
+ Specifies the maximum number of redirector processes that Squid may
+ spawn (numberofchildren) and several related options. Using too few of
+ these helper processes (a.k.a. "helpers") creates request queues.
+ Using too many helpers wastes your system resources.
+
+ Usage: numberofchildren [option]...
+
The startup= and idle= options allow some measure of skew in your
tuning.
queue-size=N
- Sets the maximum number of queued requests to N. The default maximum
- is 2*numberofchildren. If the queued requests exceed queue size and
- redirector_bypass configuration option is set, then redirector is bypassed.
- Otherwise, Squid is allowed to temporarily exceed the configured maximum,
- marking the affected helper as "overloaded". If the helper overload lasts
- more than 3 minutes, the action prescribed by the on-persistent-overload
- option applies.
+ Sets the maximum number of queued requests. A request is queued when
+ no existing child can accept it due to concurrency limit and no new
+ child can be started due to numberofchildren limit. The default
+ maximum is zero if url_rewrite_bypass is enabled and
+ 2*numberofchildren otherwise. If the queued requests exceed queue size
+ and redirector_bypass configuration option is set, then redirector is
+ bypassed. Otherwise, Squid is allowed to temporarily exceed the
+ configured maximum, marking the affected helper as "overloaded". If
+ the helper overload lasts more than 3 minutes, the action prescribed
+ by the on-persistent-overload option applies.
on-persistent-overload=action
redirectors for access control, and you enable this option,
users may have access to pages they should not
be allowed to request.
- This options sets default queue-size option of the url_rewrite_children
- to 0.
+
+ Enabling this option sets the default url_rewrite_children queue-size
+ option value to 0.
DOC_END
NAME: url_rewrite_extras
The default is to use HTTP request URL as the store ID.
BH
- An internal error occured in the helper, preventing
+ An internal error occurred in the helper, preventing
a result being identified.
In addition to the above kv-pairs Squid also understands the following
DEFAULT: 20 startup=0 idle=1 concurrency=0
LOC: Config.storeIdChildren
DOC_START
- The maximum number of StoreID helper processes to spawn. If you limit
- it too few Squid will have to wait for them to process a backlog of
- requests, slowing it down. If you allow too many they will use RAM
- and other system resources noticably.
+ Specifies the maximum number of StoreID helper processes that Squid
+ may spawn (numberofchildren) and several related options. Using
+ too few of these helper processes (a.k.a. "helpers") creates request
+ queues. Using too many helpers wastes your system resources.
+
+ Usage: numberofchildren [option]...
The startup= and idle= options allow some measure of skew in your
tuning.
queue-size=N
- Sets the maximum number of queued requests to N. The default maximum
- is 2*numberofchildren. If the queued requests exceed queue size and
- redirector_bypass configuration option is set, then redirector is bypassed.
- Otherwise, Squid is allowed to temporarily exceed the configured maximum,
- marking the affected helper as "overloaded". If the helper overload lasts
- more than 3 minutes, the action prescribed by the on-persistent-overload
- option applies.
+ Sets the maximum number of queued requests to N. A request is queued
+ when no existing child can accept it due to concurrency limit and no
+ new child can be started due to numberofchildren limit. The default
+ maximum is 2*numberofchildren. If the queued requests exceed queue
+ size and redirector_bypass configuration option is set, then
+ redirector is bypassed. Otherwise, Squid is allowed to temporarily
+ exceed the configured maximum, marking the affected helper as
+ "overloaded". If the helper overload lasts more than 3 minutes, the
+ action prescribed by the on-persistent-overload option applies.
on-persistent-overload=action
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
will be considered fresh.
'Max' is an upper limit on how long objects without an explicit
- expiry time will be considered fresh.
+ expiry time will be considered fresh. The value is also used
+ to form Cache-Control: max-age header for a request sent from
+ Squid to origin/parent.
options: override-expire
override-lastmod
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
disk or memory caches and for Vary-controlled cached objects.
DOC_END
-NAME: collapsed_forwarding_shared_entries_limit
+NAME: collapsed_forwarding_access
+TYPE: acl_access
+DEFAULT: none
+DEFAULT_DOC: Requests may be collapsed if collapsed_forwarding is on.
+LOC: Config.accessList.collapsedForwardingAccess
+DOC_START
+ Use this directive to restrict collapsed forwarding to a subset of
+ eligible requests. The directive is checked for regular HTTP
+ requests, internal revalidation requests, and HTCP/ICP requests.
+
+ collapsed_forwarding_access allow|deny [!]aclname ...
+
+ This directive cannot force collapsing. It has no effect on
+ collapsing unless collapsed_forwarding is 'on', and all other
+ collapsing preconditions are satisfied.
+
+ * A denied request will not collapse, and future transactions will
+ not collapse on it (even if they are allowed to collapse).
+
+ * An allowed request may collapse, or future transactions may
+ collapse on it (provided they are allowed to collapse).
+
+ This directive is evaluated before receiving HTTP response headers
+ and without access to Squid-to-peer connection (if any).
+
+ Only fast ACLs are supported.
+
+ See also: collapsed_forwarding.
+DOC_END
+
+NAME: shared_transient_entries_limit collapsed_forwarding_shared_entries_limit
COMMENT: (number of entries)
TYPE: int64_t
-LOC: Config.collapsed_forwarding_shared_entries_limit
+LOC: Config.shared_transient_entries_limit
DEFAULT: 16384
DOC_START
- This limits the size of a table used for sharing information
- about collapsible entries among SMP workers. Limiting sharing
- too much results in cache content duplication and missed
- collapsing opportunities. Using excessively large values
- wastes shared memory.
+ This directive limits the size of a table used for sharing current
+ transaction information among SMP workers. A table entry stores meta
+ information about a single cache entry being delivered to Squid
+ client(s) by one or more SMP workers. A single table entry consumes
+ less than 128 shared memory bytes.
- The limit should be significantly larger then the number of
- concurrent collapsible entries one wants to share. For a cache
- that handles less than 5000 concurrent requests, the default
+ The limit should be significantly larger than the number of
+ concurrent non-collapsed cachable responses leaving Squid. For a
+ cache that handles less than 5000 concurrent requests, the default
setting of 16384 should be plenty.
- If the limit is set to zero, it disables sharing of collapsed
- forwarding between SMP workers.
+ Using excessively large values wastes shared memory. Limiting the
+ table size too much results in hash collisions, leading to lower hit
+ ratio and missed SMP request collapsing opportunities: Transactions
+ left without a table entry cannot cache their responses and are
+ invisible to other concurrent requests for the same resource.
+
+ A zero limit is allowed but unsupported. A positive small limit
+ lowers hit ratio, but zero limit disables a lot of essential
+ synchronization among SMP workers, leading to HTTP violations (e.g.,
+ stale hit responses). It also disables shared collapsed forwarding:
+ A worker becomes unable to collapse its requests on transactions in
+ other workers, resulting in more trips to the origin server and more
+ cache thrashing.
DOC_END
COMMENT_START
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
NAME: esi_parser
IFDEF: USE_SQUID_ESI
-COMMENT: libxml2|expat|custom
+COMMENT: libxml2|expat
TYPE: string
LOC: ESIParser::Type
-DEFAULT: custom
+DEFAULT: auto
+DEFAULT_DOC: Selects libxml2 if available at ./configure time or libexpat otherwise.
DOC_START
- ESI markup is not strictly XML compatible. The custom ESI parser
- will give higher performance, but cannot handle non ASCII character
- encodings.
+ Selects the XML parsing library to use when interpreting responses with
+ Edge Side Includes.
+
+ To disable ESI handling completely, ./configure Squid with --disable-esi.
DOC_END
COMMENT_START
See also client_delay_parameters and client_delay_pools.
DOC_END
+NAME: response_delay_pool
+TYPE: response_delay_pool_parameters
+DEFAULT: none
+IFDEF: USE_DELAY_POOLS
+LOC: Config.MessageDelay
+DOC_START
+ This option configures client response bandwidth limits using the
+ following format:
+
+ response_delay_pool name [option=value] ...
+
+ name the response delay pool name
+
+ available options:
+
+ individual-restore The speed limit of an individual
+ bucket(bytes/s). To be used in conjunction
+ with 'individual-maximum'.
+
+ individual-maximum The maximum number of bytes which can
+ be placed into the individual bucket. To be used
+ in conjunction with 'individual-restore'.
+
+ aggregate-restore The speed limit for the aggregate
+ bucket(bytes/s). To be used in conjunction with
+ 'aggregate-maximum'.
+
+ aggregate-maximum The maximum number of bytes which can
+ be placed into the aggregate bucket. To be used
+ in conjunction with 'aggregate-restore'.
+
+ initial-bucket-level The initial bucket size as a percentage
+ of individual-maximum.
+
+ Individual and(or) aggregate bucket options may not be specified,
+ meaning no individual and(or) aggregate speed limitation.
+ See also response_delay_pool_access and delay_parameters for
+ terminology details.
+DOC_END
+
+NAME: response_delay_pool_access
+TYPE: response_delay_pool_access
+DEFAULT: none
+DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool.
+IFDEF: USE_DELAY_POOLS
+LOC: Config.MessageDelay
+DOC_START
+ Determines whether a specific named response delay pool is used
+ for the transaction. The syntax for this directive is:
+
+ response_delay_pool_access pool_name allow|deny acl_name
+
+ All response_delay_pool_access options are checked in the order
+ they appear in this configuration file. The first rule with a
+ matching ACL wins. If (and only if) an "allow" rule won, Squid
+ assigns the response to the corresponding named delay pool.
+DOC_END
+
COMMENT_START
WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
-----------------------------------------------------------------------------
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
URL FORMAT TAGS:
%a - username (if available. Password NOT included)
+ %A - Local listening IP address the client connection was connected to
%B - FTP path URL
%e - Error number
%E - Error description
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".
These options are used for Secure ICAP (icaps://....) services only.
tls-cert=/path/to/ssl/certificate
- A client SSL certificate to use when connecting to
- this icap server.
+ A client X.509 certificate to use when connecting to
+ this ICAP server.
tls-key=/path/to/ssl/key
- The private TLS/SSL key corresponding to sslcert above.
- If 'tls-key' is not specified 'tls-cert' is assumed to
- reference a combined PEM format file containing both the
- certificate and the key.
+ The private key corresponding to the previous
+ tls-cert= option.
+
+ If tls-key= is not specified tls-cert= is assumed to
+ reference a PEM file containing both the certificate
+ and private key.
tls-cipher=... The list of valid TLS/SSL ciphers to use when connecting
to this icap server.
tls-min-version=1.N
The minimum TLS protocol version to permit. To control
- SSLv3 use the ssloptions= parameter.
+ SSLv3 use the tls-options= parameter.
Supported Values: 1.0 (default), 1.1, 1.2
tls-options=... Specify various OpenSSL library options:
NO_SSLv3 Disallow the use of SSLv3
- NO_TLSv1 Disallow the use of TLSv1.0
- NO_TLSv1_1 Disallow the use of TLSv1.1
- NO_TLSv1_2 Disallow the use of TLSv1.2
-
SINGLE_DH_USE
Always create a new key when using
temporary/ephemeral DH key exchanges
DOC_END
NAME: dns_nameservers
-TYPE: wordlist
+TYPE: SBufList
DEFAULT: none
DEFAULT_DOC: Use operating system definitions
-LOC: Config.dns_nameservers
+LOC: Config.dns.nameservers
DOC_START
Use this if you want to specify a list of DNS name servers
(IP addresses) to use instead of those given in your
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.
+
+ By default and when connect_retries is set to zero, Squid does not
+ retry failed connection opening attempts.
- The default is not to re-try if the first connection attempt fails.
- The (not recommended) maximum is 10 tries.
+ 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).
- A warning message will be generated if it is set to a too-high
- value and the configured value will be over-ridden.
+ 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.
- 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.
+ 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
projects / thirdparty / squid.git / blobdiff