-## 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.
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
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 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]
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.
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
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:
+ each with their own certificate and/or options.
- 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.
+ The TLS cert= option is mandatory on HTTPS ports.
- 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.
-
- 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
-
- SINGLE_ECDH_USE
- Enable ephemeral ECDH key exchange.
- The adopted curve should be specified
- using the tls-dh option.
-
- 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.
-
- tls-dh=[curve:]file
- File containing DH parameters for temporary/ephemeral DH key
- exchanges, optionally prefixed by a curve for ephemeral ECDH
- 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.
-
- 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.
-
- 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
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
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 ====
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
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
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.
+ 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.
more complete list. Options relevant only to SSLv2 are
not supported.
- tls-cafile=... A PEM file containing additional CA certificates to use
- when verifying the icap server certificate. Used
- to specify intermediate CA certificate(s) if not sent
- by the server. Or the full CA chain for the server
- when using the NO_DEFAULT_CA flag.
+ 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.
tls-capath=... A directory containing additional CA certificates to
use when verifying the icap server certificate.
+ Requires OpenSSL or LibreSSL.
tls-crlfile=... A certificate revocation list file to use when
verifying the icap server certificate.
DONT_VERIFY_PEER
Accept certificates even if they fail to
verify.
- NO_DEFAULT_CA
- Don't use the default CA list built into
- OpenSSL.
DONT_VERIFY_DOMAIN
Don't verify the icap server certificate
matches the server name
+ 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
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.