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
Replace this line with 'cache_peer' configuration.
DOC_END
+COMMENT_START
+ OPTIONS FOR SMP
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: workers
+TYPE: int
+LOC: Config.workers
+DEFAULT: 1
+DEFAULT_DOC: SMP support disabled.
+DOC_START
+ Number of main Squid processes or "workers" to fork and maintain.
+ 0: "no daemon" mode, like running "squid -N ..."
+ 1: "no SMP" mode, start one main Squid process daemon (default)
+ N: start N main Squid process daemons (i.e., SMP mode)
+
+ In SMP mode, each worker does nearly all what a single Squid daemon
+ does (e.g., listen on http_port and forward HTTP requests).
+DOC_END
+
+NAME: cpu_affinity_map
+TYPE: CpuAffinityMap
+LOC: Config.cpuAffinityMap
+DEFAULT: none
+DEFAULT_DOC: Let operating system decide.
+DOC_START
+ Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
+
+ Sets 1:1 mapping between Squid processes and CPU cores. For example,
+
+ cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
+
+ affects processes 1 through 4 only and places them on the first
+ four even cores, starting with core #1.
+
+ CPU cores are numbered starting from 1. Requires support for
+ sched_getaffinity(2) and sched_setaffinity(2) system calls.
+
+ Multiple cpu_affinity_map options are merged.
+
+ See also: workers
+DOC_END
+
COMMENT_START
OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
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
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 ...
# SslBump1: After getting TCP-level and HTTP CONNECT info.
# SslBump2: After getting SSL Client Hello info.
# SslBump3: After getting SSL Server Hello info.
+
+ acl aclname ssl::server_name .foo.com ...
+ # 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.
+
+ acl aclname ssl::server_name_regex [-i] \.foo\.com ...
+ # regex matches server name obtained from various sources [fast]
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
DEFAULT_DOC: Respond with an error message to unidentifiable traffic
DOC_START
Determines Squid behavior when encountering strange requests at the
- beginning of an accepted TCP connection. This is especially useful in
- interception environments where Squid is likely to see connections for
- unsupported protocols that Squid should either terminate or tunnel at
- TCP level.
+ beginning of an accepted TCP connection or the beginning of a bumped
+ CONNECT tunnel. Controlling Squid reaction to unexpected traffic is
+ especially useful in interception environments where Squid is likely
+ to see connections for unsupported protocols that Squid should either
+ terminate or tunnel at TCP level.
on_unsupported_protocol <action> [!]acl ...
- The first matching action wins.
+ The first matching action wins. Only fast ACLs are supported.
Supported actions are:
for the Squid port that received the request (e.g., HTTP
for connections intercepted at the http_port). This is the
default.
-
- Currently, this directive is ignored for non-intercepted connections
- because Squid cannot know what their intended destination is.
+
+ Squid expects the following traffic patterns:
+
+ http_port: a plain HTTP request
+ https_port: SSL/TLS handshake followed by an [encrypted] HTTP request
+ ftp_port: a plain FTP command (no on_unsupported_protocol support yet!)
+ 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
+ bumped tunnels only. Other cases are not supported because Squid
+ cannot know the intended destination of other traffic.
For example:
# define what Squid errors indicate receiving non-HTTP 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
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
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
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
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.
+ 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
RFC2475, and RFC3260.
The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
- "default" to use whatever default your host has. Note that in
- practice often only multiples of 4 is usable as the two rightmost bits
- have been redefined for use by ECN (RFC 3168 section 23.1).
+ "default" to use whatever default your host has.
+ Note that only multiples of 4 are usable as the two rightmost bits have
+ been redefined for use by ECN (RFC 3168 section 23.1).
+ The squid parser will enforce this by masking away the ECN bits.
Processing proceeds in the order specified, and stops at first fully
matching line.
DEFAULT: none
LOC: Ip::Qos::TheConfig.tosToClient
DOC_START
- Allows you to select a TOS/Diffserv value for packets being transmitted
+ Allows you to select a TOS/DSCP value for packets being transmitted
on the client-side, based on an ACL.
clientside_tos ds-field [!]aclname ...
Note: This feature is incompatible with qos_flows. Any TOS values set here
will be overwritten by TOS values in qos_flows.
+
+ The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or
+ "default" to use whatever default your host has.
+ Note that only multiples of 4 are usable as the two rightmost bits have
+ been redefined for use by ECN (RFC 3168 section 23.1).
+ The squid parser will enforce this by masking away the ECN bits.
+
DOC_END
NAME: tcp_outgoing_mark
know what you're specifying. For more information, see RFC2474,
RFC2475, and RFC3260.
- The TOS/DSCP byte must be exactly that - a octet value 0 - 255. Note that
- in practice often only multiples of 4 is usable as the two rightmost bits
- have been redefined for use by ECN (RFC 3168 section 23.1).
+ The TOS/DSCP byte must be exactly that - a octet value 0 - 255.
+ Note that only multiples of 4 are usable as the two rightmost bits have
+ been redefined for use by ECN (RFC 3168 section 23.1).
+ The squid parser will enforce this by masking away the ECN bits.
Mark values can be any unsigned 32-bit integer value.
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
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
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
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
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.
+
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
DOC_END
NAME: pinger_program
-TYPE: string
-DEFAULT: @DEFAULT_PINGER@
-LOC: Config.pinger.program
IFDEF: USE_ICMP
+TYPE: icmp
+DEFAULT: @DEFAULT_PINGER@
+LOC: IcmpCfg
DOC_START
Specify the location of the executable for the pinger process.
DOC_END
NAME: pinger_enable
TYPE: onoff
DEFAULT: on
-LOC: Config.pinger.enable
+LOC: IcmpCfg.enable
IFDEF: USE_ICMP
DOC_START
Control whether the pinger is active at run-time.
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
uri: icap://servername:port/servicepath
ICAP server and service location.
+ icaps://servername:port/servicepath
+ The "icap:" URI scheme is used for traditional ICAP server and
+ service location (default port is 1344, connections are not
+ encrypted). The "icaps:" URI scheme is for Secure ICAP
+ services that use SSL/TLS-encrypted ICAP connections (by
+ default, on port 11344).
ICAP does not allow a single service to handle both REQMOD and RESPMOD
transactions. Squid does not enforce that requirement. You can specify
Use the given number as the Max-Connections limit, regardless
of the Max-Connections value given by the service, if any.
+ ==== ICAPS / TLS OPTIONS ====
+
+ These options are used for Secure ICAP (icaps://....) services only.
+
+ tls-cert=/path/to/ssl/certificate
+ A client SSL certificate to use when connecting to
+ this icap server.
+
+ 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.
+
+ tls-cipher=... The list of valid TLS/SSL ciphers to use when connecting
+ to this icap server.
+
+ tls-min-version=1.N
+ The minimum TLS protocol version to permit. To control
+ SSLv3 use the ssloptions= parameter.
+ 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.
+
+ See the OpenSSL SSL_CTX_set_options documentation for a
+ 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-capath=... A directory containing additional CA certificates to
+ use when verifying the icap server certificate.
+
+ tls-crlfile=... A certificate revocation list file to use when
+ verifying the icap server certificate.
+
+ 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 into
+ OpenSSL.
+ DONT_VERIFY_DOMAIN
+ Don't verify the icap server certificate
+ matches the server name
+
+ 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.
+
Older icap_service format without optional named parameters is
deprecated but supported for backward compatibility.
Example:
icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0
-icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on
+icap_service svcLogger reqmod_precache icaps://icap2.mydomain.net:11344/reqmod routing=on
DOC_END
NAME: icap_class
not all I/O types supports large values (eg on Windows).
DOC_END
-NAME: workers
-TYPE: int
-LOC: Config.workers
-DEFAULT: 1
-DEFAULT_DOC: SMP support disabled.
-DOC_START
- Number of main Squid processes or "workers" to fork and maintain.
- 0: "no daemon" mode, like running "squid -N ..."
- 1: "no SMP" mode, start one main Squid process daemon (default)
- N: start N main Squid process daemons (i.e., SMP mode)
-
- In SMP mode, each worker does nearly all what a single Squid daemon
- does (e.g., listen on http_port and forward HTTP requests).
-DOC_END
-
-NAME: cpu_affinity_map
-TYPE: CpuAffinityMap
-LOC: Config.cpuAffinityMap
-DEFAULT: none
-DEFAULT_DOC: Let operating system decide.
-DOC_START
- Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,...
-
- Sets 1:1 mapping between Squid processes and CPU cores. For example,
-
- cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7
-
- affects processes 1 through 4 only and places them on the first
- four even cores, starting with core #1.
-
- CPU cores are numbered starting from 1. Requires support for
- sched_getaffinity(2) and sched_setaffinity(2) system calls.
-
- Multiple cpu_affinity_map options are merged.
-
- See also: workers
-DOC_END
-
NAME: force_request_body_continuation
TYPE: acl_access
LOC: Config.accessList.forceRequestBodyContinuation