-## Copyright (C) 1996-2016 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.
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,
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
# 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
+ # could not compute the server name using any information source
+ # already available at the ACL evaluation time.
acl aclname ssl::server_name_regex [-i] \.foo\.com ...
# regex matches server name obtained from various sources [fast]
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
-----------------------------------------------------------------------------
==== 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
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.
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
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
projects / thirdparty / squid.git / blobdiff