-## Copyright (C) 1996-2015 The Squid Software Foundation and contributors
+## Copyright (C) 1996-2017 The Squid Software Foundation and contributors
##
## Squid software is distributed under GPLv2+ license and includes
## contributions from numerous individuals and organizations.
${service_name} expands into the current Squid service instance
name identifier which is provided by -n on the command line.
+ Logformat Macros
+
+ Logformat macros can be used in many places outside of the logformat
+ directive. In theory, all of the logformat codes can be used as %macros,
+ where they are supported. In practice, a %macro expands as a dash (-) when
+ the transaction does not yet have enough information and a value is needed.
+
+ There is no definitive list of what tokens are available at the various
+ stages of the transaction.
+
+ And some information may already be available to Squid but not yet
+ committed where the macro expansion code can access it (report
+ such instances!). The macro will be expanded into a single dash
+ ('-') in such cases. Not all macros have been tested.
+
COMMENT_END
# options still not yet ported from 2.7 to 3.x
This option is not yet supported by Squid-3.
DOC_END
-# Options removed in 3.6
+# Options removed in 4.x
NAME: cache_peer_domain cache_host_domain
TYPE: obsolete
DOC_START
Replace with dstdomain ACLs and cache_peer_access.
DOC_END
+NAME: ie_refresh
+TYPE: obsolete
+DOC_START
+ Remove this line. The behaviour enabled by this is no longer needed.
+DOC_END
+
NAME: sslproxy_cafile
TYPE: obsolete
DOC_START
See also: workers
DOC_END
+NAME: shared_memory_locking
+TYPE: YesNoNone
+COMMENT: on|off
+LOC: Config.shmLocking
+DEFAULT: off
+DOC_START
+ Whether to ensure that all required shared memory is available by
+ "locking" that shared memory into RAM when Squid starts. The
+ alternative is faster startup time followed by slightly slower
+ performance and, if not enough RAM is actually available during
+ runtime, mysterious crashes.
+
+ SMP Squid uses many shared memory segments. These segments are
+ brought into Squid memory space using an mmap(2) system call. During
+ Squid startup, the mmap() call often succeeds regardless of whether
+ the system has enough RAM. In general, Squid cannot tell whether the
+ kernel applies this "optimistic" memory allocation policy (but
+ popular modern kernels usually use it).
+
+ Later, if Squid attempts to actually access the mapped memory
+ regions beyond what the kernel is willing to allocate, the
+ "optimistic" kernel simply kills Squid kid with a SIGBUS signal.
+ Some of the memory limits enforced by the kernel are currently
+ poorly understood: We do not know how to detect and check them. This
+ option ensures that the mapped memory will be available.
+
+ This option may have a positive performance side-effect: Locking
+ memory at start avoids runtime paging I/O. Paging slows Squid down.
+
+ Locking memory may require a large enough RLIMIT_MEMLOCK OS limit,
+ CAP_IPC_LOCK capability, or equivalent.
+DOC_END
+
COMMENT_START
OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
NAME: auth_param
TYPE: authparam
IFDEF: USE_AUTH
-LOC: Auth::TheConfig
+LOC: Auth::TheConfig.schemes
DEFAULT: none
DOC_START
This is used to define parameters for the various authentication
For Digest there is no default, this parameter is mandatory.
For NTLM and Negotiate this parameter is ignored.
- "children" numberofchildren [startup=N] [idle=N] [concurrency=N] [queue-size=N]
+ "children" numberofchildren [startup=N] [idle=N] [concurrency=N]
+ [queue-size=N] [on-persistent-overload=action]
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= option sets the maximum number of queued
- requests. If the queued requests exceed queue size for more
- than 3 minutes then squid aborts its operation.
- The default value is set to 2*numberofchildren/
+ 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 on-persistent-overload=action option specifies Squid
+ reaction to a new helper request arriving when the helper
+ has been overloaded for more that 3 minutes already. The number
+ of queued requests determines whether the helper is overloaded
+ (see the queue-size option).
+
+ Two actions are supported:
+
+ die Squid worker quits. This is the default behavior.
+
+ ERR Squid treats the helper request as if it was
+ immediately submitted, and the helper immediately
+ replied with an ERR response. This action has no effect
+ on the already queued and in-progress helper requests.
NOTE: NTLM and Negotiate schemes do not support concurrency
in the Squid code module even though some helpers can.
+ "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.
-IF HAVE_AUTH_MODULE_BASIC
- === Basic authentication parameters ===
+ For Basic and Digest this parameter is ignored.
"utf8" on|off
HTTP uses iso-latin-1 as character set, while some
set to on Squid will translate the HTTP iso-latin-1 charset to
UTF-8 before sending the username and password to the helper.
+ For NTLM and Negotiate this parameter is ignored.
+
+IF HAVE_AUTH_MODULE_BASIC
+ === Basic authentication parameters ===
+
"credentialsttl" timetolive
Specifies how long squid assumes an externally validated
username:password pair is valid for - in other words how
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,
This option defines external acl classes using a helper program
to look up the status
- external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
+ external_acl_type name [options] FORMAT /path/to/helper [helper arguments]
Options:
ttl=n TTL in seconds for cached results (defaults to 3600
- for 1 hour)
+ for 1 hour)
negative_ttl=n
- TTL for cached negative lookups (default same
- as ttl)
+ TTL for cached negative lookups (default same
+ as ttl)
grace=n Percentage remaining of TTL where a refresh of a
cached entry should be initiated without needing to
wait for a new reply. (default is for no grace period)
- cache=n Limit the result cache size, default is 262144.
- The expanded FORMAT value is used as the cache key, so
- if the details in FORMAT are highly variable a larger
- cache may be needed to produce reduction in helper load.
+ cache=n The maximum number of entries in the result cache. The
+ default limit is 262144 entries. Each cache entry usually
+ consumes at least 256 bytes. Squid currently does not remove
+ expired cache entries until the limit is reached, so a proxy
+ will sooner or later reach the limit. The expanded FORMAT
+ value is used as the cache key, so if the details in FORMAT
+ are highly variable, a larger cache may be needed to produce
+ reduction in helper load.
children-max=n
Maximum number of acl helper processes spawned to service
- external acl lookups of this type. (default 20)
+ external acl lookups of this type. (default 5)
children-startup=n
Minimum number of acl helper processes to spawn during
The default is to auto-detect IPv6 and use it when available.
- FORMAT specifications
-
- %LOGIN Authenticated user login name
- %un A user name. Expands to the first available name
- from the following list of information sources:
- - authenticated user name, like %ul or %LOGIN
- - user name sent by an external ACL, like %EXT_USER
- - SSL client name, like %us in logformat
- - ident user name, like %ui in logformat
- %EXT_USER Username from previous external acl
- %EXT_LOG Log details from previous external acl
- %EXT_TAG Tag from previous external acl
- %IDENT Ident user name
- %SRC Client IP
- %SRCPORT Client source port
- %URI Requested URI
- %DST Requested host
- %PROTO Requested URL scheme
- %PORT Requested port
- %PATH Requested URL path
- %METHOD Request method
- %MYADDR Squid interface address
- %MYPORT Squid http_port number
- %PATH Requested URL-path (including query-string if any)
- %USER_CERT SSL User certificate in PEM format
- %USER_CERTCHAIN SSL User certificate chain in PEM format
- %USER_CERT_xx SSL User certificate subject attribute xx
- %USER_CA_CERT_xx SSL User certificate issuer attribute xx
- %ssl::>sni SSL client SNI sent to Squid
- %ssl::<cert_subject SSL server certificate DN
- %ssl::<cert_issuer SSL server certificate issuer DN
-
- %>{Header} HTTP request header "Header"
- %>{Hdr:member}
- HTTP request header "Hdr" list member "member"
- %>{Hdr:;member}
- HTTP request header list member using ; as
- list separator. ; can be any non-alphanumeric
- character.
-
- %<{Header} HTTP reply header "Header"
- %<{Hdr:member}
- HTTP reply header "Hdr" list member "member"
- %<{Hdr:;member}
- HTTP reply header list member using ; as
- list separator. ; can be any non-alphanumeric
- character.
+ FORMAT is a series of %macro codes. See logformat directive for a full list
+ of the accepted codes. Although note that at the time of any external ACL
+ being tested data may not be available and thus some %macro expand to '-'.
+
+ In addition to the logformat codes; when processing external ACLs these
+ additional macros are made available:
%ACL The name of the ACL being tested.
- %DATA The ACL arguments. If not used then any arguments
- is automatically added at the end of the line
- sent to the helper.
- NOTE: this will encode the arguments as one token,
- whereas the default will pass each separately.
- %% The percent sign. Useful for helpers which need
- an unchanging input format.
+ %DATA The ACL arguments specified in the referencing config
+ 'acl ... external' line, separated by spaces (an
+ "argument string"). see acl external.
+
+ If there are no ACL arguments %DATA expands to '-'.
+
+ If you do not specify a DATA macro inside FORMAT,
+ Squid automatically appends %DATA to your FORMAT.
+
+ By default, Squid applies URL-encoding to each ACL
+ argument inside the argument string. If an explicit
+ encoding modifier is used (e.g., %#DATA), then Squid
+ encodes the whole argument string as a single token
+ (e.g., with %#DATA, spaces between arguments become
+ %20).
+
+ If SSL is enabled, the following formating codes become available:
+
+ %USER_CERT SSL User certificate in PEM format
+ %USER_CERTCHAIN SSL User certificate chain in PEM format
+ %USER_CERT_xx SSL User certificate subject attribute xx
+ %USER_CA_CERT_xx SSL User certificate issuer attribute xx
+
+
+ NOTE: all other format codes accepted by older Squid versions
+ are deprecated.
General request syntax:
- [channel-ID] FORMAT-values [acl-values ...]
+ [channel-ID] FORMAT-values
FORMAT-values consists of transaction details expanded with
whitespace separation per the config file FORMAT specification
using the FORMAT macros listed above.
- acl-values consists of any string specified in the referencing
- config 'acl ... external' line. see the "acl external" directive.
-
Request values sent to the helper are URL escaped to protect
each value in requests against whitespaces.
does not alter existing tags.
log= String to be logged in access.log. Available as
- %ea in logformat specifications.
+ %ea in logformat specifications.
- clt_conn_tag= Associates a TAG with the client TCP connection.
+ clt_conn_tag= Associates a TAG with the client TCP connection.
Please see url_rewrite_program related documentation
for this kv-pair.
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: CONNECT method CONNECT
+DEFAULT_DOC: ACLs all, manager, localhost, to_localhost, and CONNECT are predefined.
DOC_START
Defining an Access List
When using "file", the file should contain one item per line.
- Some acl types supports options which changes their default behaviour.
- The available options are:
+
+ ACL Options
+
+ Some acl types supports options which changes their default behaviour:
-i,+i By default, regular expressions are CASE-SENSITIVE. To make them
case-insensitive, use the -i option. To return case-sensitive
name or IP), then the ACL would immediately declare a mismatch
without any warnings or lookups.
+ -m[=delimiters]
+ Perform a list membership test, interpreting values as
+ comma-separated token lists and matching against individual
+ tokens instead of whole values.
+ The optional "delimiters" parameter specifies one or more
+ alternative non-alphanumeric delimiter characters.
+ non-alphanumeric delimiter characters.
+
-- Used to stop processing all options, in the case the first acl
value has '-' character as first character (for example the '-'
is a valid domain name)
# effect in rules that affect the reply data stream such as
# http_reply_access.
- acl aclname note name [value ...]
+ acl aclname note [-m[=delimiters]] name [value ...]
# match transaction annotation [fast]
# Without values, matches any annotation with a given name.
# With value(s), matches any annotation with a given name that
# also has one of the given values.
- # Names and values are compared using a string equality test.
+ # If the -m flag is used, then the value of the named
+ # annotation is interpreted as a list of tokens, and the ACL
+ # matches individual name=token pairs rather than whole
+ # name=value pairs. See "ACL Options" above for more info.
# 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
+
IF USE_OPENSSL
acl aclname ssl_error errorname
# match against SSL certificate validation error [fast]
# 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 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
+ # 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 aclname connections_encrypted
+ # matches transactions with all HTTP messages received over TLS
+ # transport connections. [fast]
+ #
+ # The master transaction deals with HTTP messages received from
+ # various sources. All sources used by the master transaction in the
+ # past are considered by the ACL. The following rules define whether
+ # a given message source taints the entire master transaction,
+ # resulting in ACL mismatches:
+ #
+ # * The HTTP client transport connection is not TLS.
+ # * An adaptation service connection-encryption flag is off.
+ # * The peer or origin server transport connection is not TLS.
+ #
+ # Caching currently does not affect these rules. This cache ignorance
+ # implies that only the current HTTP client transport and REQMOD
+ # services status determine whether this ACL matches a from-cache
+ # transaction. The source of the cached response does not have any
+ # effect on future transaction that use the cached response without
+ # revalidation. This may change.
+ #
+ # DNS, ICP, and HTCP exchanges during the master transaction do not
+ # affect these rules.
ENDIF
acl aclname any-of acl1 acl2 ...
# match any one of the acls [fast or slow]
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
DOC_END
See also: squid_error ACL
DOC_END
+NAME: auth_schemes
+TYPE: AuthSchemes
+IFDEF: USE_AUTH
+LOC: Auth::TheConfig.schemeAccess
+DEFAULT: none
+DEFAULT_DOC: use all auth_param schemes in their configuration order
+DOC_START
+ Use this directive to customize authentication schemes presence and
+ order in Squid's Unauthorized and Authentication Required responses.
+
+ auth_schemes scheme1,scheme2,... [!]aclname ...
+
+ where schemeN is the name of one of the authentication schemes
+ configured using auth_param directives. At least one scheme name is
+ required. Multiple scheme names are separated by commas. Either
+ avoid whitespace or quote the entire schemes list.
+
+ A special "ALL" scheme name expands to all auth_param-configured
+ schemes in their configuration order. This directive cannot be used
+ to configure Squid to offer no authentication schemes at all.
+
+ The first matching auth_schemes rule determines the schemes order
+ for the current Authentication Required transaction. Note that the
+ future response is not yet available during auth_schemes evaluation.
+
+ If this directive is not used or none of its rules match, then Squid
+ responds with all configured authentication schemes in the order of
+ auth_param directives in the configuration file.
+
+ This directive does not determine when authentication is used or
+ how each authentication scheme authenticates clients.
+
+ The following example sends basic and negotiate authentication
+ schemes, in that order, when requesting authentication of HTTP
+ requests matching the isIE ACL (not shown) while sending all
+ auth_param schemes in their configuration order to other clients:
+
+ auth_schemes basic,negotiate isIE
+ auth_schemes ALL all # explicit default
+
+ This directive supports fast ACLs only.
+
+ See also: auth_param.
+DOC_END
+
COMMENT_START
NETWORK OPTIONS
-----------------------------------------------------------------------------
Verify CRL lists for all certificates in the
client certificate chain.
- tls-no-default-ca
- Do not use the system default Trusted CA.
+ tls-default-ca[=off]
+ Whether to use the system Trusted CAs. Default is OFF.
+
+ tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1.
sslcontext= SSL session ID context identifier.
DOC_END
NAME: https_port
-IFDEF: USE_OPENSSL
+IFDEF: USE_GNUTLS||USE_OPENSSL
TYPE: PortCfg
DEFAULT: none
-LOC: HttpsPortList
+LOC: HttpPortList
DOC_START
Usage: [ip:]port [mode] cert=certificate.pem [options]
To control SSLv3 use the options= parameter.
Supported Values: 1.0 (default), 1.1, 1.2
- options=... Specify various TLS/SSL implementation options:
+ options=... Specify various TLS/SSL implementation options.
- NO_SSLv3 Disallow the use of SSLv3
+ OpenSSL options most important are:
- 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
+ NO_SSLv3 Disallow the use of SSLv3
SINGLE_DH_USE
Always create a new key when using
temporary/ephemeral DH key exchanges
- SSL_OP_NO_TICKET
+ NO_TICKET
Disable use of RFC5077 session tickets.
Some servers may have problems
understanding the TLS extension due
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.
Don't verify the peer certificate
matches the server name
- no-default-ca Do not use the system default Trusted CA.
+ default-ca[=off]
+ Whether to use the system Trusted CAs. Default is ON.
domain= The peer name as advertised in its certificate.
Used for verifying the correctness of the received peer
Sets the cache size to use for ssl session
DOC_END
+NAME: sslproxy_foreign_intermediate_certs
+IFDEF: USE_OPENSSL
+DEFAULT: none
+LOC: Config.ssl_client.foreignIntermediateCertsPath
+TYPE: string
+DOC_START
+ Many origin servers fail to send their full server certificate
+ chain for verification, assuming the client already has or can
+ easily locate any missing intermediate certificates.
+
+ Squid uses the certificates from the specified file to fill in
+ these missing chains when trying to validate origin server
+ certificate chains.
+
+ The file is expected to contain zero or more PEM-encoded
+ intermediate certificates. These certificates are not treated
+ as trusted root certificates, and any self-signed certificate in
+ this file will be ignored.
+DOC_END
+
NAME: sslproxy_cert_sign_hash
IFDEF: USE_OPENSSL
DEFAULT: none
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)
See also: http_port ssl-bump, https_port ssl-bump, and acl at_step.
- # Example: Bump all requests except those originating from
+ # Example: Bump all TLS connections except those originating from
# localhost or those going to example.com.
- acl broken_sites dstdomain .example.com
+ acl broken_sites ssl::server_name .example.com
ssl_bump splice localhost
ssl_bump splice broken_sites
ssl_bump bump all
DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
LOC: Ssl::TheConfig.ssl_crtd
DOC_START
- Specify the location and options of the executable for ssl_crtd process.
+ Specify the location and options of the executable for certificate
+ generator.
@DEFAULT_SSL_CRTD@ program requires -s and -M parameters
For more information use:
@DEFAULT_SSL_CRTD@ -h
Default is auto to automatically determine the status
of the peer.
+ auth-no-keytab
+ Do not use a keytab to authenticate to a peer when
+ login=NEGOTIATE is specified. Let the GSSAPI
+ implementation determine which already existing
+ credentials cache to use instead.
+
==== SSL / HTTPS / TLS OPTIONS ====
- ssl Encrypt connections to this peer with SSL/TLS.
+ tls Encrypt connections to this peer with TLS.
sslcert=/path/to/ssl/certificate
A client SSL certificate to use when connecting to
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:
+ tls-options=... Specify various TLS implementation 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
+ 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
temporary/ephemeral DH key exchanges
- SSL_OP_NO_TICKET
+ NO_TICKET
Disable use of RFC5077 session tickets.
Some servers may have problems
understanding the TLS extension due
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.
certificate. If not specified the peer hostname will be
used.
- front-end-https
+ front-end-https[=off|on|auto]
Enable the "Front-End-Https: On" header needed when
using Squid as a SSL frontend in front of Microsoft OWA.
See MS KB document Q307347 for details on this header.
If set to auto the header will only be added if the
request is forwarded as a https:// URL.
-
- tls-no-default-ca
- Do not use the system default Trusted CA.
+ tls-default-ca[=off]
+ Whether to use the system Trusted CAs. Default is ON.
+
+ tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1.
+
==== GENERAL OPTIONS ====
connect-timeout=N
allow-miss Disable Squid's use of only-if-cached when forwarding
requests to siblings. This is primarily useful when
- icp_hit_stale is used by the sibling. To extensive use
- of this option may result in forwarding loops, and you
- should avoid having two-way peerings with this option.
- For example to deny peer usage on requests from peer
- by denying cache_peer_access if the source is a peer.
+ icp_hit_stale is used by the sibling. Excessive use
+ of this option may result in forwarding loops. One way
+ to prevent peering loops when using this option, is to
+ deny cache peer usage on requests from a peer:
+ acl fromPeer ...
+ cache_peer_access peerName deny fromPeer
max-conn=N Limit the number of concurrent connections the Squid
may open to this peer, including already opened idle
Required if you have multiple peers on the same host
but different ports.
This name can be used in cache_peer_access and similar
- directives to dentify the peer.
+ directives to identify the peer.
Can be used by outgoing access controls through the
peername ACL type.
NAME: cache_peer_access
TYPE: peer_access
DEFAULT: none
+DEFAULT_DOC: No peer usage restrictions.
LOC: none
DOC_START
- Use to limit the requests for which a neighbor proxy will be
- queried. Peers with no restrictions are queried for all requests.
+ Restricts usage of cache_peer proxies.
Usage:
- cache_peer_access cache-host allow|deny [!]aclname ...
+ cache_peer_access peer-name allow|deny [!]aclname ...
+
+ For the required peer-name parameter, use either the value of the
+ cache_peer name=value parameter or, if name=value is missing, the
+ cache_peer hostname parameter.
+
+ This directive narrows down the selection of peering candidates, but
+ does not determine the order in which the selected candidates are
+ contacted. That order is determined by the peer selection algorithms
+ (see PEER SELECTION sections in the cache_peer documentation).
+
+ If a deny rule matches, the corresponding peer will not be contacted
+ for the current transaction -- Squid will not send ICP queries and
+ will not forward HTTP requests to that peer. An allow match leaves
+ the corresponding peer in the selection. The first match for a given
+ peer wins for that peer.
+
+ The relative order of cache_peer_access directives for the same peer
+ matters. The relative order of any two cache_peer_access directives
+ for different peers does not matter. To ease interpretation, it is a
+ good idea to group cache_peer_access directives for the same peer
+ together.
+
+ A single cache_peer_access directive may be evaluated multiple times
+ for a given transaction because individual peer selection algorithms
+ may check it independently from each other. These redundant checks
+ may be optimized away in future Squid versions.
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
- The syntax is identical to 'http_access' and the other lists of
- ACL elements. See the comments for 'http_access', or the
- Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
DOC_END
NAME: neighbor_type_domain
To avoid blocking locks, shared memory uses opportunistic algorithms
that do not guarantee that every cachable entity that could have been
shared among SMP workers will actually be shared.
-
- Currently, entities exceeding 32KB in size cannot be shared.
DOC_END
NAME: memory_cache_mode
modifiers are usually not needed, but can be specified if an explicit
output format is desired.
- % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
+ % ["|[|'|#|/] [-] [[0]width] [{arg}] formatcode [{arg}]
" 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
- left aligned
When minimum starts with 0, the field is zero-padded.
String values exceeding maximum width are truncated.
- {arg} argument such as header name etc
+ {arg} argument such as header name etc. This field may be
+ placed before or after the token, but not both at once.
Format codes:
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
default, the error codes are separated by ':'.
Accepts an optional separator argument.
+ %ssl::>negotiated_version The negotiated TLS version of the
+ client connection.
+
+ %ssl::<negotiated_version The negotiated TLS version of the
+ last server or peer connection.
+
+ %ssl::>received_hello_version The TLS version of the Hello
+ message received from TLS client.
+
+ %ssl::<received_hello_version The TLS version of the Hello
+ message received from TLS server.
+
+ %ssl::>received_supported_version The maximum TLS version
+ supported by the TLS client.
+
+ %ssl::<received_supported_version The maximum TLS version
+ supported by the TLS server.
+
+ %ssl::>negotiated_cipher The negotiated cipher of the
+ client connection.
+
+ %ssl::<negotiated_cipher The negotiated cipher of the
+ last server or peer connection.
+
If ICAP is enabled, the following code becomes available (as
well as ICAP log codes documented with the icap_log option):
ICAP transaction log lines will correspond to a single access
log line.
- ICAP log uses logformat codes that make sense for an ICAP
- transaction. Header-related codes are applied to the HTTP header
- embedded in an ICAP server response, with the following caveats:
- For REQMOD, there is no HTTP response header unless the ICAP
- server performed request satisfaction. For RESPMOD, the HTTP
- request header is the header sent to the ICAP server. For
- OPTIONS, there are no HTTP headers.
+ ICAP log supports many access.log logformat %codes. In ICAP context,
+ HTTP message-related %codes are applied to the HTTP message embedded
+ in an ICAP message. Logformat "%http::>..." codes are used for HTTP
+ messages embedded in ICAP requests while "%http::<..." codes are used
+ for HTTP messages embedded in ICAP responses. For example:
+
+ http::>h To-be-adapted HTTP message headers sent by Squid to
+ the ICAP service. For REQMOD transactions, these are
+ HTTP request headers. For RESPMOD, these are HTTP
+ response headers, but Squid currently cannot log them
+ (i.e., %http::>h will expand to "-" for RESPMOD).
+
+ http::<h Adapted HTTP message headers sent by the ICAP
+ service to Squid (i.e., HTTP request headers in regular
+ REQMOD; HTTP response headers in RESPMOD and during
+ request satisfaction in REQMOD).
+
+ ICAP OPTIONS transactions do not embed HTTP messages.
+
+ Several logformat codes below deal with ICAP message bodies. An ICAP
+ message body, if any, typically includes a complete HTTP message
+ (required HTTP headers plus optional HTTP message body). When
+ computing HTTP message body size for these logformat codes, Squid
+ either includes or excludes chunked encoding overheads; see
+ code-specific documentation for details.
+
+ For Secure ICAP services, all size-related information is currently
+ computed before/after TLS encryption/decryption, as if TLS was not
+ in use at all.
The following format codes are also available for ICAP logs:
icap::rm ICAP request method (REQMOD, RESPMOD, or
OPTIONS). Similar to existing rm.
- icap::>st Bytes sent to the ICAP server (TCP payload
- only; i.e., what Squid writes to the socket).
+ icap::>st The total size of the ICAP request sent to the ICAP
+ server (ICAP headers + ICAP body), including chunking
+ metadata (if any).
- icap::<st Bytes received from the ICAP server (TCP
- payload only; i.e., what Squid reads from
- the socket).
+ icap::<st The total size of the ICAP response received from the
+ ICAP server (ICAP headers + ICAP body), including
+ chunking metadata (if any).
- icap::<bs Number of message body bytes received from the
- ICAP server. ICAP message body, if any, usually
- includes encapsulated HTTP message headers and
- possibly encapsulated HTTP message body. The
- HTTP body part is dechunked before its size is
- computed.
+ icap::<bs The size of the ICAP response body received from the
+ ICAP server, excluding chunking metadata (if any).
icap::tr Transaction response time (in
milliseconds). The timer starts when
The default ICAP log format, which can be used without an explicit
definition, is called icap_squid:
-logformat icap_squid %ts.%03tu %6icap::tr %>
a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
+logformat icap_squid %ts.%03tu %6icap::tr %>
A %icap::to/%03icap::Hs %icap::<st %icap::rm %icap::ru %un -/%icap::<A -
- See also: logformat, log_icap, and %adapt::<last_h
+ See also: logformat and %adapt::<last_h
DOC_END
NAME: logfile_daemon
queue-size=N
- Sets the maximum number of queued requests.
- If the queued requests exceed queue size and redirector_bypass
- configuration option is set, then redirector is bypassed. Otherwise, if
- overloading persists squid may abort its operation.
- The default value is set to 2*numberofchildren.
+ 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.
+
+ on-persistent-overload=action
+
+ Specifies Squid reaction to a new helper request arriving when the helper
+ has been overloaded for more that 3 minutes already. The number of queued
+ requests determines whether the helper is overloaded (see the queue-size
+ option).
+
+ Two actions are supported:
+
+ die Squid worker quits. This is the default behavior.
+
+ ERR Squid treats the helper request as if it was
+ immediately submitted, and the helper immediately
+ replied with an ERR response. This action has no effect
+ on the already queued and in-progress helper requests.
DOC_END
NAME: url_rewrite_host_header redirect_rewrites_host_header
DEFAULT: off
DOC_START
When this is 'on', a request will not go through the
- redirector if all the helpers are busy. If this is 'off'
- and the redirector queue grows too large, Squid will exit
- with a FATAL error and ask you to increase the number of
- redirectors. You should only enable this if the redirectors
- are not critical to your caching system. If you use
+ redirector if all the helpers are busy. If this is 'off' and the
+ redirector queue grows too large, the action is prescribed by the
+ on-persistent-overload option. You should only enable this if the
+ redirectors are not critical to your caching system. If you use
redirectors for access control, and you enable this option,
users may have access to pages they should not
be allowed to request.
queue-size=N
- Sets the maximum number of queued requests.
- If the queued requests exceed queue size and store_id_bypass
- configuration option is set, then storeID helper is bypassed. Otherwise,
- if overloading persists squid may abort its operation.
- The default value is set to 2*numberofchildren.
+ 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.
+
+ on-persistent-overload=action
+
+ Specifies Squid reaction to a new helper request arriving when the helper
+ has been overloaded for more that 3 minutes already. The number of queued
+ requests determines whether the helper is overloaded (see the queue-size
+ option).
+
+ Two actions are supported:
+
+ die Squid worker quits. This is the default behavior.
+
+ ERR Squid treats the helper request as if it was
+ immediately submitted, and the helper immediately
+ replied with an ERR response. This action has no effect
+ on the already queued and in-progress helper requests.
DOC_END
NAME: store_id_access storeurl_rewrite_access
DEFAULT: on
DOC_START
When this is 'on', a request will not go through the
- helper if all helpers are busy. If this is 'off'
- and the helper queue grows too large, Squid will exit
- with a FATAL error and ask you to increase the number of
- helpers. You should only enable this if the helperss
- are not critical to your caching system. If you use
+ helper if all helpers are busy. If this is 'off' and the helper
+ queue grows too large, the action is prescribed by the
+ on-persistent-overload option. You should only enable this if the
+ helpers are not critical to your caching system. If you use
helpers for critical caching components, and you enable this
option, users may not get objects from cache.
This options sets default queue-size option of the store_id_children
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
replies as required by RFC2616.
DOC_END
-NAME: ie_refresh
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.ie_refresh
-DEFAULT: off
-DOC_START
- Microsoft Internet Explorer up until version 5.5 Service
- Pack 1 has an issue with transparent proxies, wherein it
- is impossible to force a refresh. Turning this on provides
- a partial fix to the problem, by causing all IMS-REFRESH
- requests from older IE versions to check the origin server
- for fresh content. This reduces hit ratio by some amount
- (~10% in my experience), but allows users to actually get
- fresh content when they want it. Note because Squid
- cannot tell if the user is using 5.5 or 5.5SP1, the behavior
- of 5.5 is unchanged from old versions of Squid (i.e. a
- forced refresh is impossible). Newer versions of IE will,
- hopefully, continue to have the new behavior and will be
- handled based on that assumption. This option defaults to
- the old Squid behavior, which is better for hit ratios but
- worse for clients using IE, if they need to be able to
- force fresh content.
-DOC_END
-
NAME: vary_ignore_expire
COMMENT: on|off
TYPE: onoff
LOC: Config.request_header_add
DEFAULT: none
DOC_START
- Usage: request_header_add field-name field-value acl1 [acl2] ...
+ Usage: request_header_add field-name field-value [ acl ... ]
Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
This option adds header fields to outgoing HTTP requests (i.e.,
string format is used, then the surrounding quotes are removed
while escape sequences and %macros are processed.
- In theory, all of the logformat codes can be used as %macros.
- However, unlike logging (which happens at the very end of
- transaction lifetime), the transaction may not yet have enough
- information to expand a macro when the new header value is needed.
- And some information may already be available to Squid but not yet
- committed where the macro expansion code can access it (report
- such instances!). The macro will be expanded into a single dash
- ('-') in such cases. Not all macros have been tested.
-
One or more Squid ACLs may be specified to restrict header
injection to matching requests. As always in squid.conf, all
- ACLs in an option ACL list must be satisfied for the insertion
- to happen. The request_header_add option supports fast ACLs
- only.
+ ACLs in the ACL list must be satisfied for the insertion to
+ happen. The request_header_add supports fast ACLs only.
+
+ See also: reply_header_add.
+DOC_END
+
+NAME: reply_header_add
+TYPE: HeaderWithAclList
+LOC: Config.reply_header_add
+DEFAULT: none
+DOC_START
+ Usage: reply_header_add field-name field-value [ acl ... ]
+ Example: reply_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
+
+ This option adds header fields to outgoing HTTP responses (i.e., response
+ headers delivered by Squid to the client). This option has no effect on
+ cache hit detection. The equivalent adaptation vectoring point in
+ ICAP terminology is post-cache RESPMOD. This option does not apply to
+ successful CONNECT replies.
+
+ Field-name is a token specifying an HTTP header name. If a
+ standard HTTP header name is used, Squid does not check whether
+ the new header conflicts with any existing headers or violates
+ HTTP rules. If the response to be modified already contains a
+ field with the same name, the old field is preserved but the
+ header field values are not merged.
+
+ Field-value is either a token or a quoted string. If quoted
+ string format is used, then the surrounding quotes are removed
+ while escape sequences and %macros are processed.
+
+ One or more Squid ACLs may be specified to restrict header
+ injection to matching responses. As always in squid.conf, all
+ ACLs in the ACL list must be satisfied for the insertion to
+ happen. The reply_header_add option supports fast ACLs only.
+
+ See also: request_header_add.
DOC_END
NAME: note
potentially cachable requests for the same URI before Squid knows
whether the response is going to be cachable.
- This feature is disabled by default: Enabling collapsed forwarding
- needlessly delays forwarding requests that look cachable (when they are
- collapsed) but then need to be forwarded individually anyway because
- they end up being for uncachable content. However, in some cases, such
- as accelleration of highly cachable content with periodic or groupped
- expiration times, the gains from collapsing [large volumes of
- simultenous refresh requests] outweigh losses from such delays.
+ When enabled, instead of forwarding each concurrent request for
+ the same URL, Squid just sends the first of them. The other, so
+ called "collapsed" requests, wait for the response to the first
+ request and, if it happens to be cachable, use that response.
+ Here, "concurrent requests" means "received after the first
+ request headers were parsed and before the corresponding response
+ headers were parsed".
+
+ This feature is disabled by default: enabling collapsed
+ forwarding needlessly delays forwarding requests that look
+ cachable (when they are collapsed) but then need to be forwarded
+ individually anyway because they end up being for uncachable
+ content. However, in some cases, such as acceleration of highly
+ cachable content with periodic or grouped expiration times, the
+ gains from collapsing [large volumes of simultaneous refresh
+ requests] outweigh losses from such delays.
+
+ Squid collapses two kinds of requests: regular client requests
+ received on one of the listening ports and internal "cache
+ revalidation" requests which are triggered by those regular
+ requests hitting a stale cached object. Revalidation collapsing
+ is currently disabled for Squid instances containing SMP-aware
+ disk or memory caches and for Vary-controlled cached objects.
+DOC_END
+
+NAME: collapsed_forwarding_shared_entries_limit
+COMMENT: (number of entries)
+TYPE: int64_t
+LOC: Config.collapsed_forwarding_shared_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.
+
+ 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
+ setting of 16384 should be plenty.
+
+ If the limit is set to zero, it disables sharing of collapsed
+ forwarding between SMP workers.
DOC_END
COMMENT_START
delay_parameters 1 none 8000/8000
- Note that 8 x 8000 KByte/sec -> 64Kbit/sec.
+ Note that 8 x 8K Byte/sec -> 64K bit/sec.
Note that the word 'none' is used to represent no limit.
delay_parameters 2 32000/32000 8000/8000 600/8000
- Note that 8 x 32000 KByte/sec -> 256Kbit/sec.
- 8 x 8000 KByte/sec -> 64Kbit/sec.
- 8 x 600 Byte/sec -> 4800bit/sec.
+ Note that 8 x 32K Byte/sec -> 256K bit/sec.
+ 8 x 8K Byte/sec -> 64K bit/sec.
+ 8 x 600 Byte/sec -> 4800 bit/sec.
Finally, for a class 4 delay pool as in the example - each user will
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
-----------------------------------------------------------------------------
%H - Request domain name
%i - Client IP Address
%M - Request Method
+ %O - Unescaped message result from external ACL helper
%o - Message result from external ACL helper
%p - Request Port number
%P - Request Protocol name
Use the given number as the Max-Connections limit, regardless
of the Max-Connections value given by the service, if any.
+ connection-encryption=on|off
+ Determines the ICAP service effect on the connections_encrypted
+ ACL.
+
+ The default is "on" for Secure ICAP services (i.e., those
+ with the icaps:// service URIs scheme) and "off" for plain ICAP
+ services.
+
+ Does not affect ICAP connections (e.g., does not turn Secure
+ ICAP on or off).
+
==== ICAPS / TLS OPTIONS ====
These options are used for Secure ICAP (icaps://....) services only.
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
the icap server certificate.
Use to specify intermediate CA certificate(s) if not sent
by the server. Or the full CA chain for the server when
- using the tls-no-default-ca flag.
+ using the tls-default-ca=off flag.
May be repeated to load multiple files.
tls-capath=... A directory containing additional CA certificates to
Don't verify the icap server certificate
matches the server name
- tls-no-default-ca
- Do no use the system default Trusted CA.
+ tls-default-ca[=off]
+ Whether to use the system Trusted CAs. Default is ON.
tls-domain= The icap server name as advertised in it's certificate.
Used for verifying the correctness of the received icap
Routing is not allowed by default.
+ connection-encryption=on|off
+ Determines the eCAP service effect on the connections_encrypted
+ ACL.
+
+ Defaults to "on", which does not taint the master transaction
+ w.r.t. that ACL.
+
+ Does not affect eCAP API calls.
+
Older ecap_service format without optional named parameters is
deprecated but supported for backward compatibility.
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
that the request body is needed. Delaying is the default behavior.
DOC_END
+NAME: server_pconn_for_nonretriable
+TYPE: acl_access
+DEFAULT: none
+DEFAULT_DOC: Open new connections for forwarding requests Squid cannot retry safely.
+LOC: Config.accessList.serverPconnForNonretriable
+DOC_START
+ This option provides fine-grained control over persistent connection
+ reuse when forwarding HTTP requests that Squid cannot retry. It is useful
+ in environments where opening new connections is very expensive
+ (e.g., all connections are secured with TLS with complex client and server
+ certificate validation) and race conditions associated with persistent
+ connections are very rare and/or only cause minor problems.
+
+ HTTP prohibits retrying unsafe and non-idempotent requests (e.g., POST).
+ Squid limitations also prohibit retrying all requests with bodies (e.g., PUT).
+ By default, when forwarding such "risky" requests, Squid opens a new
+ connection to the server or cache_peer, even if there is an idle persistent
+ connection available. When Squid is configured to risk sending a non-retriable
+ request on a previously used persistent connection, and the server closes
+ the connection before seeing that risky request, the user gets an error response
+ from Squid. In most cases, that error response will be HTTP 502 (Bad Gateway)
+ with ERR_ZERO_SIZE_OBJECT or ERR_WRITE_ERROR (peer connection reset) error detail.
+
+ If an allow rule matches, Squid reuses an available idle persistent connection
+ (if any) for the request that Squid cannot retry. If a deny rule matches, then
+ Squid opens a new connection for the request that Squid cannot retry.
+
+ This option does not affect requests that Squid can retry. They will reuse idle
+ persistent connections (if any).
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
+ Example:
+ acl SpeedIsWorthTheRisk method POST
+ server_pconn_for_nonretriable allow SpeedIsWorthTheRisk
+DOC_END
+
EOF
projects / thirdparty / squid.git / blobdiff