-## Copyright (C) 1996-2015 The Squid Software Foundation and contributors
+## Copyright (C) 1996-2016 The Squid Software Foundation and contributors
##
## Squid software is distributed under GPLv2+ license and includes
## contributions from numerous individuals and organizations.
NAME: sslproxy_version
TYPE: obsolete
DOC_START
- Remove this line. Use tls_outgoing_options version= instead.
+ Remove this line. Use tls_outgoing_options options= instead.
DOC_END
# Options removed in 3.5
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
The default is to auto-detect IPv6 and use it when available.
- FORMAT specifications
-
- %LOGIN Authenticated user login name
- %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.
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)
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)
- # The arp ACL requires the special configure option --enable-arp-acl.
- # Furthermore, the ARP ACL code is not portable to all operating systems.
- # It works on Linux, Solaris, Windows, FreeBSD, and some
- # other *BSD variants.
# [fast]
+ # 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
+ # clients that are on the same subnet. If the client is on a
+ # different subnet, then Squid cannot find out its address.
#
- # NOTE: Squid can only determine the MAC address for clients that are on
- # the same subnet. If the client is on a different subnet,
- # then Squid cannot find out its MAC address.
+ # NOTE 2: IPv6 protocol does not contain ARP. MAC/EUI is either
+ # encoded directly in the IPv6 address or not available.
acl aclname srcdomain .foo.com ...
# reverse lookup, from client IP [slow]
acl aclname user_cert attribute values...
# match against attributes in a user SSL certificate
- # attribute is one of DN/C/O/CN/L/ST [fast]
+ # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]
acl aclname ca_cert attribute values...
# match against attributes a users issuing CA SSL certificate
- # attribute is one of DN/C/O/CN/L/ST [fast]
+ # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]
acl aclname ext_user username ...
acl aclname ext_user_regex [-i] pattern ...
# 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 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]
SECURITY WARNING: Usage of this option is dangerous
and should not be used trivially. Correct configuration
- of follow_x_forewarded_for with a limited set of trusted
+ of follow_x_forwarded_for with a limited set of trusted
sources is required to prevent abuse of your proxy.
DOC_END
DEFAULT: none
DEFAULT_DOC: Allow, unless rules exist in squid.conf.
DOC_START
- Determins whether network access is permitted when satisfying a request.
+ Determines whether network access is permitted when satisfying a request.
For example;
to force your neighbors to use you as a sibling instead of
CONNECT tunnel on http_port: same as https_port
CONNECT tunnel on https_port: same as https_port
- Currently, this directive has effect on intercepted connections and
+ Currently, this directive has effect on intercepted connections and
bumped tunnels only. Other cases are not supported because Squid
cannot know the intended destination of other traffic.
Modes:
- intercept Support for IP-Layer interception of
- outgoing requests without browser settings.
- NP: disables authentication and IPv6 on the port.
+ intercept Support for IP-Layer NAT interception delivering
+ traffic to this Squid port.
+ NP: disables authentication on the port.
- tproxy Support Linux TPROXY for spoofing outgoing
- connections using the client IP address.
- NP: disables authentication and maybe IPv6 on the port.
+ tproxy Support Linux TPROXY (or BSD divert-to) with spoofing
+ of outgoing connections using the client IP address.
+ NP: disables authentication on the port.
accel Accelerator / reverse proxy mode
assumed to be a combined certificate and
key file.
- version= The version of SSL/TLS supported
- 1 automatic (default)
- 3 SSLv3 only
- 4 TLSv1.0 only
- 5 TLSv1.1 only
- 6 TLSv1.2 only
-
cipher= Colon separated list of supported ciphers.
NOTE: some ciphers such as EDH ciphers depend on
additional settings. If those settings are
Always create a new key when using
temporary/ephemeral DH key exchanges
+ SINGLE_ECDH_USE
+ Enable ephemeral ECDH key exchange.
+ The adopted curve should be specified
+ using the tls-dh option.
+
NO_TICKET
Disable use of RFC5077 session tickets.
Some servers may have problems
clientca= File containing the list of CAs to use when
requesting a client certificate.
- cafile= File containing additional CA certificates to
- use when verifying client certificates. If unset
- clientca will be used.
+ tls-cafile= PEM file containing CA certificates to use when verifying
+ client certificates. If not configured clientca will be
+ used. May be repeated to load multiple files.
capath= Directory containing additional CA certificates
and CRL lists to use when verifying client certificates.
+ Requires OpenSSL or LibreSSL.
crlfile= File of additional CRL lists to use when verifying
the client certificate, in addition to CRLs stored in
the capath. Implies VERIFY_CRL flag below.
- dhparams= File containing DH parameters for temporary/ephemeral
- DH key exchanges. See OpenSSL documentation for details
- on how to create this file.
- WARNING: EDH ciphers will be silently disabled if this
- option is not set.
+ tls-dh=[curve:]file
+ File containing DH parameters for temporary/ephemeral DH key
+ exchanges, optionally prefixed by a curve for ephemeral ECDH
+ key exchanges.
+ See OpenSSL documentation for details on how to create the
+ DH parameter file. Supported curves for ECDH can be listed
+ using the "openssl ecparam -list_curves" command.
+ WARNING: EDH and EECDH ciphers will be silently disabled if
+ this option is not set.
sslflags= Various flags modifying the use of SSL:
DELAYED_AUTH
Don't request client certificates
immediately, but wait until acl processing
requires a certificate (not yet implemented).
- NO_DEFAULT_CA
- Don't use the default CA lists built in
- to OpenSSL.
NO_SESSION_REUSE
Don't allow for session reuse. Each connection
will result in a new SSL session.
Verify CRL lists for all certificates in the
client certificate chain.
+ 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.
Other Options:
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 cert=certificate.pem [key=key.pem] [mode] [options...]
+ Usage: [ip:]port [mode] 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 SSL 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 SSL certificate and/or options.
-
- Modes:
-
- accel Accelerator / reverse proxy mode
-
- intercept Support for IP-Layer interception of
- outgoing requests without browser settings.
- NP: disables authentication and IPv6 on the port.
-
- tproxy Support Linux TPROXY for spoofing outgoing
- connections using the client IP address.
- NP: disables authentication and maybe IPv6 on the port.
-
- ssl-bump For each intercepted connection allowed by ssl_bump
- ACLs, establish a secure connection with the client and with
- the server, decrypt HTTPS messages as they pass through
- Squid, and treat them as unencrypted HTTP messages,
- becoming the man-in-the-middle.
-
- An "ssl_bump server-first" match is required to
- fully enable bumping of intercepted SSL connections.
-
- Requires tproxy or intercept.
-
- Omitting the mode flag causes default forward proxy mode to be used.
-
-
- See http_port for a list of generic options
-
-
- SSL Options:
-
- cert= Path to SSL certificate (PEM format).
-
- 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.
-
- version= The version of SSL/TLS supported
- 1 automatic (default)
- 3 SSLv3 only
- 4 TLSv1 only
-
- cipher= Colon separated list of supported ciphers.
-
- options= Various SSL engine options. The most important
- being:
-
- 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
-
- SSL_OP_NO_TICKET
- Disable use of RFC5077 session tickets.
- Some servers may have problems
- understanding the TLS extension due
- to ambiguous specification in RFC4507.
-
- ALL Enable various bug workarounds
- suggested as "harmless" by OpenSSL
- Be warned that this reduces SSL/TLS
- strength to some attacks.
-
- See the OpenSSL SSL_CTX_set_options documentation for a
- more complete list.
-
- clientca= File containing the list of CAs to use when
- requesting a client certificate.
-
- cafile= File containing additional CA certificates to
- use when verifying client certificates. If unset
- clientca will be used.
-
- capath= Directory containing additional CA certificates
- and CRL lists to use when verifying client certificates.
-
- crlfile= File of additional CRL lists to use when verifying
- the client certificate, in addition to CRLs stored in
- the capath. Implies VERIFY_CRL flag below.
-
- dhparams= File containing DH parameters for temporary/ephemeral
- DH key exchanges.
-
- sslflags= Various flags modifying the use of SSL:
- DELAYED_AUTH
- Don't request client certificates
- immediately, but wait until acl processing
- requires a certificate (not yet implemented).
- NO_DEFAULT_CA
- Don't use the default CA lists built in
- to OpenSSL.
- NO_SESSION_REUSE
- Don't allow for session reuse. Each connection
- will result in a new SSL session.
- VERIFY_CRL
- Verify CRL lists when accepting client
- certificates.
- VERIFY_CRL_ALL
- Verify CRL lists for all certificates in the
- client certificate chain.
+ each with their own certificate and/or options.
- sslcontext= SSL session ID context identifier.
-
- generate-host-certificates[=<on|off>]
- Dynamically create SSL server certificates for the
- destination hosts of bumped SSL requests.When
- enabled, the cert and key options are used to sign
- generated certificates. Otherwise generated
- certificate will be selfsigned.
- If there is CA certificate life time of generated
- certificate equals lifetime of CA certificate. If
- generated certificate is selfsigned lifetime is three
- years.
- This option is enabled by default when SslBump is used.
- See the sslBump option above for more information.
+ The TLS cert= option is mandatory on HTTPS ports.
- dynamic_cert_mem_cache_size=SIZE
- Approximate total RAM size spent on cached generated
- certificates. If set to zero, caching is disabled. The
- default value is 4MB.
-
- See http_port for a list of available options.
+ See http_port for a list of modes and options.
DOC_END
NAME: ftp_port
NAME: tls_outgoing_options
IFDEF: USE_GNUTLS||USE_OPENSSL
TYPE: securePeerOptions
-DEFAULT: disable
+DEFAULT: min-version=1.0
LOC: Security::ProxyOutgoingConfig
DOC_START
disable Do not support https:// URLs.
If key= is not specified cert= is assumed to reference
a PEM file containing both the certificate and the key.
- version=1|3|4|5|6
- The TLS/SSL version to use when connecting
- 1 = automatic (default)
- 3 = SSL v3 only
- 4 = TLS v1.0 only
- 5 = TLS v1.1 only
- 6 = TLS v1.2 only
-
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:
NO_SSLv3 Disallow the use of SSLv3
See the OpenSSL SSL_CTX_set_options documentation for a
more complete list.
- cafile=... A file containing additional CA certificates to use
- when verifying the peer certificate.
-
- capath=... A directory containing additional CA certificates to
+ cafile= PEM file containing CA certificates to use when verifying
+ the peer certificate. May be repeated to load multiple files.
+
+ capath= A directory containing additional CA certificates to
use when verifying the peer certificate.
+ Requires OpenSSL or LibreSSL.
crlfile=... A certificate revocation list file to use when
verifying the peer certificate.
DONT_VERIFY_PEER
Accept certificates even if they fail to
verify.
- NO_DEFAULT_CA
- Don't use the default CA list built in
- to OpenSSL.
DONT_VERIFY_DOMAIN
Don't verify the peer certificate
matches the server name
+ 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
certificate. If not specified the peer hostname will be
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
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 ====
reference a combined file containing both the
certificate and the key.
- sslversion=1|3|4|5|6
- The SSL version to use when connecting to this peer
- 1 = automatic (default)
- 3 = SSL v3 only
- 4 = TLS v1.0 only
- 5 = TLS v1.1 only
- 6 = TLS v1.2 only
-
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.
+ Supported Values: 1.0 (default), 1.1, 1.2
+
ssloptions=... Specify various SSL implementation options:
NO_SSLv3 Disallow the use of SSLv3
See the OpenSSL SSL_CTX_set_options documentation for a
more complete list.
- sslcafile=... A file containing additional CA certificates to use
- when verifying the peer certificate.
+ tls-cafile= PEM file containing CA certificates to use when verifying
+ the peer certificate. May be repeated to load multiple files.
sslcapath=... A directory containing additional CA certificates to
use when verifying the peer certificate.
+ Requires OpenSSL or LibreSSL.
sslcrlfile=... A certificate revocation list file to use when
verifying the peer certificate.
Accept certificates even if they fail to
verify.
- NO_DEFAULT_CA
- Don't use the default CA list built in
- to OpenSSL.
-
DONT_VERIFY_DOMAIN
Don't verify the peer certificate
matches the server name
If set to auto the header will only be added if the
request is forwarded as a https:// URL.
+ 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
DEFAULT: 90
LOC: Config.Swap.lowWaterMark
DOC_START
- The low-water mark for cache object replacement.
- Replacement begins when the swap (disk) usage is above the
- low-water mark and attempts to maintain utilization near the
- low-water mark. As swap utilization gets close to high-water
- mark object eviction becomes more aggressive. If utilization is
- close to the low-water mark less replacement is done each time.
+ The low-water mark for AUFS/UFS/diskd cache object eviction by
+ the cache_replacement_policy algorithm.
+
+ Removal begins when the swap (disk) usage of a cache_dir is
+ above this low-water mark and attempts to maintain utilization
+ near the low-water mark.
+
+ As swap utilization increases towards the high-water mark set
+ by cache_swap_high object eviction becomes more agressive.
+
+ 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
+ this above the high-water mark.
Defaults are 90% and 95%. If you have a large cache, 5% could be
hundreds of MB. If this is the case you may wish to set these
numbers closer together.
- See also cache_swap_high
+ See also cache_swap_high and cache_replacement_policy
DOC_END
NAME: cache_swap_high
DEFAULT: 95
LOC: Config.Swap.highWaterMark
DOC_START
- The high-water mark for cache object replacement.
- Replacement begins when the swap (disk) usage is above the
- low-water mark and attempts to maintain utilization near the
- low-water mark. As swap utilization gets close to high-water
- mark object eviction becomes more aggressive. If utilization is
- close to the low-water mark less replacement is done each time.
+ The high-water mark for AUFS/UFS/diskd cache object eviction by
+ the cache_replacement_policy algorithm.
+
+ Removal begins when the swap (disk) usage of a cache_dir is
+ above the low-water mark set by cache_swap_low and attempts to
+ maintain utilization near the low-water mark.
+
+ As swap utilization increases towards this high-water mark object
+ eviction becomes more agressive.
+
+ 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
+ this above the high-water mark.
Defaults are 90% and 95%. If you have a large cache, 5% could be
hundreds of MB. If this is the case you may wish to set these
numbers closer together.
- See also cache_swap_low
+ See also cache_swap_low and cache_replacement_policy
DOC_END
COMMENT_START
modifiers are usually not needed, but can be specified if an explicit
output format is desired.
- % ["|[|'|#] [-] [[0]width] [{arg}] formatcode [{arg}]
+ % ["|[|'|#|/] [-] [[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
ul User name from authentication
ue User name from external acl helper
ui User name from ident
- us User name from SSL
+ un A user name. Expands to the first available name
+ from the following list of information sources:
+ - authenticated user name, like %ul
+ - user name supplied by an external ACL, like %ue
+ - SSL client name, like %us
+ - ident user name, like %ui
credentials Client credentials. The exact meaning depends on
the authentication scheme: For Basic authentication,
it is the password; for Digest, the realm sent by the
Squid, although most fields are often preserved.
Optional header name argument as for >h
-
RESPONSE
[http::]<Hs HTTP status code received from the next hop
Generated FTP/Gopher listings are treated as
received bodies.
-
TIMING
[http::]<pt Peer response time in milliseconds. The timer starts
after the peek, stare, or splice SSL bumping
actions.
+ ssl::>cert_subject
+ The Subject field of the received client
+ SSL certificate or a dash ('-') if Squid has
+ received an invalid/malformed certificate or
+ no certificate at all. Consider encoding the
+ logged value because Subject often has spaces.
+
+ ssl::>cert_issuer
+ The Issuer field of the received client
+ SSL certificate or a dash ('-') if Squid has
+ received an invalid/malformed certificate or
+ no certificate at all. Consider encoding the
+ logged value because Issuer often has spaces.
+
+ ssl::<cert_errors
+ The list of certificate validation errors
+ detected by Squid (including OpenSSL and
+ certificate validation helper components). The
+ errors are listed in the discovery order. By
+ 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):
ACLs are checked and when ICAP
transaction is in progress.
- If adaptation is enabled the following three codes become available:
+ If adaptation is enabled the following codes become available:
adapt::<last_h The header of the last ICAP response or
meta-information from the last eCAP
service name in curly braces to record response time(s) specific
to that service. For example: %{my_service}adapt::sum_trs
- If SSL is enabled, the following formating codes become available:
-
- %ssl::>cert_subject The Subject field of the received client
- SSL certificate or a dash ('-') if Squid has
- received an invalid/malformed certificate or
- no certificate at all. Consider encoding the
- logged value because Subject often has spaces.
-
- %ssl::>cert_issuer The Issuer field of the received client
- SSL certificate or a dash ('-') if Squid has
- received an invalid/malformed certificate or
- no certificate at all. Consider encoding the
- logged value because Issuer often has spaces.
-
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
reload-into-ims
ignore-reload
ignore-no-store
- ignore-must-revalidate
ignore-private
- ignore-auth
max-stale=NN
refresh-ims
store-stale
the HTTP standard. Enabling this feature could make you
liable for problems which it causes.
- ignore-must-revalidate ignores any ``Cache-Control: must-revalidate``
- headers received from a server. Doing this VIOLATES
- the HTTP standard. Enabling this feature could make you
- liable for problems which it causes.
-
ignore-private ignores any ``Cache-control: private''
headers received from a server. Doing this VIOLATES
the HTTP standard. Enabling this feature could make you
liable for problems which it causes.
- ignore-auth caches responses to requests with authorization,
- as if the originserver had sent ``Cache-control: public''
- in the response header. Doing this VIOLATES the HTTP standard.
- Enabling this feature could make you liable for problems which
- it causes.
-
refresh-ims causes squid to contact the origin server
when a client issues an If-Modified-Since request. This
ensures that the client will receive an updated version
Basically a cached object is:
- FRESH if expires < now, else STALE
+ FRESH if expire > now, else STALE
STALE if age > max
FRESH if lm-factor < percent, else STALE
FRESH if age < min
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
Use the given number as the Max-Connections limit, regardless
of the Max-Connections value given by the service, if any.
- ==== SSL / ICAPS / TLS OPTIONS ====
+ 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.
- sslcert=/path/to/ssl/certificate
+ tls-cert=/path/to/ssl/certificate
A client SSL certificate to use when connecting to
this icap server.
- 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
+ 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.
- sslversion=1|3|4|5|6
- The SSL version to use when connecting to this icap
- server
- 1 = automatic (default)
- 3 = SSL v3 only
- 4 = TLS v1.0 only
- 5 = TLS v1.1 only
- 6 = TLS v1.2 only
-
- sslcipher=... The list of valid SSL ciphers to use when connecting
+ tls-cipher=... The list of valid TLS/SSL ciphers to use when connecting
to this icap server.
- ssloptions=... Specify various SSL implementation options:
+ tls-min-version=1.N
+ The minimum TLS protocol version to permit. To control
+ SSLv3 use the ssloptions= 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
+
ALL Enable various bug workarounds
- suggested as "harmless" by OpenSSL
- Be warned that this reduces SSL/TLS
- strength to some attacks.
+ suggested as "harmless" by OpenSSL
+ Be warned that this reduces SSL/TLS
+ strength to some attacks.
See the OpenSSL SSL_CTX_set_options documentation for a
- more complete list.
+ more complete list. Options relevant only to SSLv2 are
+ not supported.
- sslcafile=... A file containing additional CA certificates to use
- when verifying the icap server certificate.
+ tls-cafile= PEM file containing CA certificates to use when verifying
+ 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-default-ca=off flag.
+ May be repeated to load multiple files.
- sslcapath=... A directory containing additional CA certificates to
+ tls-capath=... A directory containing additional CA certificates to
use when verifying the icap server certificate.
+ Requires OpenSSL or LibreSSL.
- sslcrlfile=... A certificate revocation list file to use when
+ tls-crlfile=... A certificate revocation list file to use when
verifying the icap server certificate.
- sslflags=... Specify various flags modifying the SSL implementation:
+ tls-flags=... Specify various flags modifying the Squid TLS implementation:
DONT_VERIFY_PEER
Accept certificates even if they fail to
verify.
- NO_DEFAULT_CA
- Don't use the default CA list built in
- to OpenSSL.
DONT_VERIFY_DOMAIN
Don't verify the icap server certificate
matches the server name
- ssldomain= The icap server name as advertised in it's certificate.
+ 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
server certificate. If not specified the icap server
hostname extracted from ICAP URI will be used.
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.
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