COMMENT_START
WELCOME TO @SQUID@
----------------------------
-
+
This is the documentation for the Squid configuration file.
This documentation can also be found online at:
http://www.squid-cache.org/Doc/config/
-
+
You may wish to look at the Squid home page and wiki for the
FAQ and other documentation:
http://www.squid-cache.org/
http://wiki.squid-cache.org/SquidFaq
http://wiki.squid-cache.org/ConfigExamples
-
+
This documentation shows what the defaults for various directives
happen to be. If you don't need to change the default, you should
leave the line out of your squid.conf in most cases.
-
+
In some cases "none" refers to no default setting at all,
while in other cases it refers to the value of the option
- the comments for that keyword indicate if this is the case.
"optimistic" kernel simply kills Squid kid with a SIGBUS signal.
Some of the memory limits enforced by the kernel are currently
poorly understood: We do not know how to detect and check them. This
- option ensures that the mapped memory will be available.
+ option ensures that the mapped memory will be available.
This option may have a positive performance side-effect: Locking
memory at start avoids runtime paging I/O. Paging slows Squid down.
DOC_START
Defining an Access List
- Every access list definition must begin with an aclname and acltype,
+ Every access list definition must begin with an aclname and acltype,
followed by either type-specific arguments or a quoted filename that
they are read from.
-i,+i By default, regular expressions are CASE-SENSITIVE. To make them
case-insensitive, use the -i option. To return case-sensitive
use the +i option between patterns, or make a new ACL line
- without -i.
+ without -i.
-n Disable lookups and address type conversions. If lookup or
conversion is required because the parameter type (IP or
-m[=delimiters]
Perform a list membership test, interpreting values as
comma-separated token lists and matching against individual
- tokens instead of whole values.
+ tokens instead of whole values.
The optional "delimiters" parameter specifies one or more
alternative non-alphanumeric delimiter characters.
non-alphanumeric delimiter characters.
acl aclname myportname 3128 ... # *_port name [fast]
acl aclname proto HTTP FTP ... # request protocol [fast]
-
+
acl aclname method GET POST ... # HTTP request method [fast]
- acl aclname http_status 200 301 500- 400-403 ...
+ acl aclname http_status 200 301 500- 400-403 ...
# status code in reply [fast]
acl aclname browser [-i] regexp ...
acl aclname server_cert_fingerprint [-sha1] fingerprint
# match against server SSL certificate fingerprint [fast]
#
- # The fingerprint is the digest of the DER encoded version
+ # The fingerprint is the digest of the DER encoded version
# of the whole certificate. The user should use the form: XX:XX:...
# Optional argument specifies the digest algorithm to use.
# The SHA1 digest algorithm is the default and is currently
# matches server name obtained from various sources [fast]
#
# The ACL computes server name(s) using such information sources as
- # CONNECT request URI, TLS client SNI, and TLS server certificate
+ # CONNECT request URI, TLS client SNI, and TLS server certificate
# subject (CN and SubjectAltName). The computed server name(s) usually
# change with each SslBump step, as more info becomes available:
# * SNI is used as the server name instead of the request URI,
#
# Unlike dstdomain, this ACL does not perform DNS lookups.
#
- # An ACL option below may be used to restrict what information
+ # An ACL option below may be used to restrict what information
# sources are used to extract the server names from:
#
# --client-requested
# This group ACL is fast if all evaluated ACLs in the group are fast
# and slow otherwise.
- acl aclname all-of acl1 acl2 ...
+ acl aclname all-of acl1 acl2 ...
# match all of the acls [fast or slow]
# The first mismatching ACL stops further ACL evaluation.
#
refer to as the indirect client address. This address may
be treated as the client address for access control, ICAP, delay
pools and logging, depending on the acl_uses_indirect_client,
- icap_uses_indirect_client, delay_pool_uses_indirect_client,
+ icap_uses_indirect_client, delay_pool_uses_indirect_client,
log_uses_indirect_client and tproxy_uses_indirect_client options.
This clause only supports fast acl types.
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. Only fast ACLs are supported.
Supported actions are:
-
+
tunnel: Establish a TCP connection with the intended server and
blindly shovel TCP packets between the client and server.
generate-host-certificates[=<on|off>]
Dynamically create SSL server certificates for the
- destination hosts of bumped CONNECT requests.When
+ destination hosts of bumped CONNECT requests.When
enabled, the cert and key options are used to sign
generated certificates. Otherwise generated
certificate will be selfsigned.
- If there is a CA certificate lifetime of the generated
+ If there is a CA certificate lifetime of the generated
certificate equals lifetime of the CA certificate. If
- generated certificate is selfsigned lifetime is three
+ generated certificate is selfsigned lifetime is three
years.
This option is enabled by default when ssl-bump is used.
See the ssl-bump 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
Other Options:
connection-auth[=on|off]
- use connection-auth=off to tell Squid to prevent
+ use connection-auth=off to tell Squid to prevent
forwarding Microsoft connection oriented authentication
(NTLM, Negotiate and Kerberos)
Regardless of this option setting, when dealing with intercepted
traffic, Squid always verifies that the destination IP address matches
the Host header domain or IP (called 'authority form URL').
-
+
This enforcement is performed to satisfy a MUST-level requirement in
RFC 2616 section 14.23: "The Host field value MUST represent the naming
authority of the origin server or gateway given by the original URL".
-
+
When set to ON:
Squid always responds with an HTTP 409 (Conflict) error
page and logs a security warning if there is no match.
-
+
Squid verifies that the destination IP address matches
the Host header for forward-proxy and reverse-proxy traffic
as well. For those traffic types, Squid also enables the
following checks, comparing the corresponding Host header
and Request-URI components:
-
+
* The host names (domain or IP) must be identical,
but valueless or missing Host header disables all checks.
For the two host names to match, both must be either IP
or FQDN.
-
+
* Port numbers must be identical, but if a port is missing
the scheme-default port is assumed.
-
-
+
+
When set to OFF (the default):
Squid allows suspicious requests to continue but logs a
security warning and blocks caching of the response.
-
+
* Forward-proxy traffic is not checked at all.
-
+
* Reverse-proxy traffic is not checked at all.
-
+
* Intercepted traffic which passes verification is handled
according to client_dst_passthru.
-
+
* Intercepted requests which fail verification are sent
to the client original destination instead of DIRECT.
This overrides 'client_dst_passthru off'.
-
+
For now suspicious intercepted CONNECT requests are always
responded to with an HTTP 409 (Conflict) error page.
-
-
+
+
SECURITY NOTE:
-
+
As described in CVE-2009-0801 when the Host: header alone is used
to determine the destination of a request it becomes trivial for
malicious scripts on remote websites to bypass browser same-origin
security policy and sandboxing protections.
-
+
The cause of this is that such applets are allowed to perform their
own HTTP stack, in which case the same-origin policy of the browser
sandbox only verifies that the applet tries to contact the same IP
as from where it was loaded at the IP level. The Host: header may
be different from the connected IP and approved origin.
-
+
DOC_END
NAME: client_dst_passthru
With NAT or TPROXY intercepted traffic Squid may pass the request
directly to the original client destination IP or seek a faster
source using the HTTP Host header.
-
+
Using Host to locate alternative servers can provide faster
connectivity with a range of failure recovery options.
But can also lead to connectivity trouble when the client and
server are attempting stateful interactions unaware of the proxy.
-
+
This option (on by default) prevents alternative DNS entries being
located to send intercepted traffic DIRECT to an origin server.
The clients original destination IP and port will be used instead.
-
+
Regardless of this option setting, when dealing with intercepted
traffic Squid will verify the Host: header and any traffic which
fails Host verification will be treated as if this option were ON.
-
+
see host_verify_strict for details on the verification process.
DOC_END
LOC: Security::ProxyOutgoingConfig
DOC_START
disable Do not support https:// URLs.
-
+
cert=/path/to/client/certificate
A client X.509 certificate to use when connecting.
-
+
key=/path/to/client/private_key
The private key corresponding to the cert= above.
If key= is not specified cert= is assumed to
reference a PEM file containing both the certificate
and private key.
-
+
cipher=... The list of valid TLS ciphers to use.
min-version=1.N
for a more complete list.
http://www.gnutls.org/manual/gnutls.html#Priority-Strings
-
+
cafile= PEM file containing CA certificates to use when verifying
the peer certificate. May be repeated to load multiple files.
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.
-
+
flags=... Specify various flags modifying the TLS implementation:
-
+
DONT_VERIFY_PEER
Accept certificates even if they fail to
verify.
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
not allow to make decisions based on SSL handshake info.
peek-and-splice
- Decide whether to bump or splice the connection based on
+ Decide whether to bump or splice the connection based on
client-to-squid and server-to-squid SSL hello messages.
XXX: Remove.
TYPE: sslproxy_cert_adapt
LOC: Config.ssl_client.cert_adapt
DOC_START
-
+
sslproxy_cert_adapt <adaptation algorithm> acl ...
The following certificate adaptation algorithms are supported:
the CA certificate used to sign generated certificates.
setCommonName or setCommonName{CN}
- Sets Subject.CN property to the host name specified as a
+ Sets Subject.CN property to the host name specified as a
CN parameter or, if no explicit CN parameter was specified,
extracted from the CONNECT request. It is a misconfiguration
to use setCommonName without an explicit parameter for
intercepted or tproxied SSL connections.
-
+
This clause only supports fast acl types.
Squid first groups sslproxy_cert_adapt options by adaptation algorithm.
DOC_END
COMMENT_START
- OPTIONS RELATING TO EXTERNAL SSL_CRTD
+ OPTIONS RELATING TO EXTERNAL SSL_CRTD
-----------------------------------------------------------------------------
COMMENT_END
NAME: sslcrtd_program
-TYPE: eol
+TYPE: eol
IFDEF: USE_SSL_CRTD
DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB
LOC: Ssl::TheConfig.ssl_crtd
The startup= and idle= options allow some measure of skew in your
tuning.
-
+
startup=N
-
+
Sets the minimum number of processes to spawn when Squid
starts or reconfigures. When set to zero the first request will
cause spawning of the first child process to handle it.
-
+
Starting too few children temporary slows Squid under load while it
tries to spawn enough additional processes to cope with traffic.
-
+
idle=N
-
+
Sets a minimum of how many processes Squid is to try and keep available
at all times. When traffic begins to rise above what the existing
processes can handle this many more will be spawned up to the maximum
numberofchildren limit. If the queued requests exceed queue size for
more than 3 minutes squid aborts its operation. The default value is
set to 2*numberofchildren.
-
+
You must have at least one ssl_crtd process.
DOC_END
does not support spawning more than 32 helpers.
Usage: numberofchildren [option]...
-
+
The startup= and idle= options allow some measure of skew in your
tuning.
-
+
startup=N
-
+
Sets the minimum number of processes to spawn when Squid
starts or reconfigures. When set to zero the first request will
cause spawning of the first child process to handle it.
-
+
Starting too few children temporary slows Squid under load while it
tries to spawn enough additional processes to cope with traffic.
-
+
idle=N
-
+
Sets a minimum of how many processes Squid is to try and keep available
at all times. When traffic begins to rise above what the existing
processes can handle this many more will be spawned up to the maximum
configured. A minimum setting of 1 is required.
concurrency=
-
+
The number of requests each certificate validator helper can handle in
parallel. A value of 0 indicates the certificate validator does not
support concurrency. Defaults to 1.
-
+
When this directive is set to a value >= 1 then the protocol
used to communicate with the helper is modified to include
a request ID in front of the request/response. The request
child can be started due to numberofchildren limit. If the queued
requests exceed queue size for more than 3 minutes squid aborts its
operation. The default value is set to 2*numberofchildren.
-
+
You must have at least one ssl_crt_validator process.
DOC_END
LOC: Config.peers
DOC_START
To specify other caches in a hierarchy, use the format:
-
+
cache_peer hostname type http-port icp-port [options]
-
+
For example,
-
+
# proxy icp
# hostname type port port options
# -------------------- -------- ----- ----- -----------
cache_peer sib1.foo.net sibling 3128 3130 proxy-only
cache_peer sib2.foo.net sibling 3128 3130 proxy-only
cache_peer example.com parent 80 0 default
- cache_peer cdn.example.com sibling 3128 0
-
+ cache_peer cdn.example.com sibling 3128 0
+
type: either 'parent', 'sibling', or 'multicast'.
-
+
proxy-port: The port number where the peer accept HTTP requests.
For other Squid proxies this is usually 3128
For web servers this is usually 80
-
+
icp-port: Used for querying neighbor caches about objects.
Set to 0 if the peer does not support ICP or HTCP.
See ICP and HTCP options below for additional details.
-
-
+
+
==== ICP OPTIONS ====
-
+
You MUST also set icp_port and icp_access explicitly when using these options.
The defaults will prevent peer traffic using ICP.
-
-
+
+
no-query Disable ICP queries to this neighbor.
-
+
multicast-responder
Indicates the named peer is a member of a multicast group.
ICP queries will not be sent directly to the peer, but ICP
replies will be accepted from it.
-
+
closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
-
+
background-ping
To only send ICP queries to this neighbor infrequently.
This is used to keep the neighbor round trip time updated
and is usually used in conjunction with weighted-round-robin.
-
-
+
+
==== HTCP OPTIONS ====
-
+
You MUST also set htcp_port and htcp_access explicitly when using these options.
The defaults will prevent peer traffic using HTCP.
-
-
+
+
htcp Send HTCP, instead of ICP, queries to the neighbor.
You probably also want to set the "icp-port" to 4827
instead of 3130. This directive accepts a comma separated
list of options described below.
-
+
htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier).
-
+
htcp=no-clr Send HTCP to the neighbor but without
sending any CLR requests. This cannot be used with
only-clr.
-
+
htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests.
This cannot be used with no-clr.
-
+
htcp=no-purge-clr
Send HTCP to the neighbor including CLRs but only when
they do not result from PURGE requests.
-
+
htcp=forward-clr
Forward any HTCP CLR requests this proxy receives to the peer.
-
-
+
+
==== PEER SELECTION METHODS ====
-
+
The default peer selection method is ICP, with the first responding peer
being used as source. These options can be used for better load balancing.
-
-
+
+
default This is a parent cache which can be used as a "last-resort"
if a peer cannot be located by any of the peer-selection methods.
If specified more than once, only the first is used.
-
+
round-robin Load-Balance parents which should be used in a round-robin
fashion in the absence of any ICP queries.
weight=N can be used to add bias.
-
+
weighted-round-robin
Load-Balance parents which should be used in a round-robin
fashion with the frequency of each parent being based on the
round trip time. Closer parents are used more often.
Usually used for background-ping parents.
weight=N can be used to add bias.
-
+
carp Load-Balance parents which should be used as a CARP array.
The requests will be distributed among the parents based on the
CARP load balancing hash function based on their weight.
-
+
userhash Load-balance parents based on the client proxy_auth or ident username.
-
+
sourcehash Load-balance parents based on the client source IP.
multicast-siblings
a "parent" cache, anyway. It's useful, e.g., when
configuring a pool of redundant Squid proxies, being
members of the same multicast group.
-
-
+
+
==== PEER SELECTION OPTIONS ====
-
+
weight=N use to affect the selection of a peer during any weighted
peer-selection mechanisms.
The weight must be an integer; default is 1,
larger weights are favored more.
This option does not affect parent selection if a peering
protocol is not in use.
-
+
basetime=N Specify a base amount to be subtracted from round trip
times of parents.
It is subtracted before division by weight in calculating
which parent to fectch from. If the rtt is less than the
base time the rtt is set to a minimal value.
-
+
ttl=N Specify a TTL to use when sending multicast ICP queries
to this address.
Only useful when sending to a multicast group.
Because we don't accept ICP replies from random
hosts, you must configure other group members as
peers with the 'multicast-responder' option.
-
+
no-delay To prevent access to this neighbor from influencing the
delay pools.
-
+
digest-url=URL Tell Squid to fetch the cache digest (if digests are
enabled) for this host from the specified URL rather
than the Squid default location.
-
-
+
+
==== CARP OPTIONS ====
-
+
carp-key=key-specification
use a different key than the full URL to hash against the peer.
- the key-specification is a comma-separated list of the keywords
+ the key-specification is a comma-separated list of the keywords
scheme, host, port, path, params
Order is not important.
-
+
==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
-
+
originserver Causes this parent to be contacted as an origin server.
Meant to be used in accelerator setups when the peer
is a web server.
-
+
forceddomain=name
Set the Host header of requests forwarded to this peer.
Useful in accelerator setups where the server (peer)
expects a certain domain name but clients may request
others. ie example.com or www.example.com
-
+
no-digest Disable request of cache digests.
-
+
no-netdb-exchange
Disables requesting ICMP RTT database (NetDB).
-
-
+
+
==== AUTHENTICATION OPTIONS ====
-
+
login=user:password
If this is a personal/workgroup proxy and your parent
requires proxy authentication.
-
+
Note: The string can include URL escapes (i.e. %20 for
spaces). This also means % must be written as %%.
-
+
login=PASSTHRU
Send login details received from client to this peer.
Both Proxy- and WWW-Authorization headers are passed
without alteration to the peer.
Authentication is not required by Squid for this to work.
-
+
Note: This will pass any form of authentication but
only Basic auth will work through a proxy unless the
connection-auth options are also used.
login=PASS Send login details received from client to this peer.
Authentication is not required by this option.
-
+
If there are no client-provided authentication headers
to pass on, but username and password are available
from an external ACL user= and password= result tags
they may be sent instead.
-
+
Note: To combine this with proxy_auth both proxies must
share the same user database as HTTP only allows for
a single login (one for proxy, one for origin server).
Also be warned this will expose your users proxy
password to the peer. USE WITH CAUTION
-
+
login=*:password
Send the username to the upstream cache, but with a
fixed password. This is meant to be used when the peer
information which is added to the username. This can
be used to identify this proxy to the peer, similar to
the login=username:password option above.
-
+
login=NEGOTIATE
If this is a personal/workgroup proxy and your parent
requires a secure proxy authentication.
The first principal from the default keytab or defined by
- the environment variable KRB5_KTNAME will be used.
-
+ the environment variable KRB5_KTNAME will be used.
+
WARNING: The connection may transmit requests from multiple
clients. Negotiate often assumes end-to-end authentication
and a single-client. Which is not strictly true here.
-
+
login=NEGOTIATE:principal_name
If this is a personal/workgroup proxy and your parent
- requires a secure proxy authentication.
+ requires a secure proxy authentication.
The principal principal_name from the default keytab or
defined by the environment variable KRB5_KTNAME will be
used.
-
+
WARNING: The connection may transmit requests from multiple
clients. Negotiate often assumes end-to-end authentication
and a single-client. Which is not strictly true here.
-
+
connection-auth=on|off
Tell Squid that this peer does or not support Microsoft
connection oriented authentication, and any such
challenges received from there should be ignored.
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 ====
-
+
tls Encrypt connections to this peer with TLS.
-
+
sslcert=/path/to/ssl/certificate
A client X.509 certificate to use when connecting to
this peer.
-
+
sslkey=/path/to/ssl/key
The private key corresponding to sslcert above.
If sslkey= is not specified sslcert= is assumed to
reference a PEM file containing both the certificate
and private key.
-
+
sslcipher=... The list of valid SSL ciphers to use when connecting
to this peer.
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.
-
+
sslflags=... Specify various flags modifying the SSL implementation:
-
+
DONT_VERIFY_PEER
Accept certificates even if they fail to
verify.
DONT_VERIFY_DOMAIN
Don't verify the peer certificate
matches the server name
-
+
ssldomain= The peer name as advertised in it's certificate.
Used for verifying the correctness of the received peer
certificate. If not specified the peer hostname will be
used.
-
+
front-end-https[=off|on|auto]
Enable the "Front-End-Https: On" header needed when
using Squid as a SSL frontend in front of Microsoft OWA.
See MS KB document Q307347 for details on this header.
If set to auto the header will only be added if the
request is forwarded as a https:// URL.
-
+
tls-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
A peer-specific connect timeout.
Also see the peer_connect_timeout directive.
-
+
connect-fail-limit=N
How many times connecting to a peer must fail before
it is marked as down. Standby connection failures
count towards this limit. Default is 10.
-
+
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. Excessive use
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
and standby connections. There is no peer-specific
connection limit by default.
-
+
A peer exceeding the limit is not used for new
requests unless a standby connection is available.
-
+
max-conn currently works poorly with idle persistent
connections: When a peer reaches its max-conn limit,
and there are idle persistent connections to the peer,
the peer may not be selected because the limiting code
does not know whether Squid can reuse those idle
connections.
-
+
standby=N Maintain a pool of N "hot standby" connections to an
UP peer, available for requests when no idle
persistent connection is available (or safe) to use.
By default and with zero N, no such pool is maintained.
N must not exceed the max-conn limit (if any).
-
+
At start or after reconfiguration, Squid opens new TCP
standby connections until there are N connections
available and then replenishes the standby pool as
connection never goes back to the standby pool, but
may go to the regular idle persistent connection pool
shared by all peers and origin servers.
-
+
Squid never opens multiple new standby connections
concurrently. This one-at-a-time approach minimizes
flooding-like effect on peers. Furthermore, just a few
standby connections should be sufficient in most cases
to supply most new requests with a ready-to-use
connection.
-
+
Standby connections obey server_idle_pconn_timeout.
For the feature to work as intended, the peer must be
configured to accept and keep them open longer than
connections. Default request_timeout and
server_idle_pconn_timeout values ensure such a
configuration.
-
+
name=xxx Unique name for the peer.
Required if you have multiple peers on the same host
but different ports.
directives to identify the peer.
Can be used by outgoing access controls through the
peername ACL type.
-
+
no-tproxy Do not use the client-spoof TPROXY support when forwarding
requests to this peer. Use normal address selection instead.
This overrides the spoof_client_ip ACL.
-
+
proxy-only objects fetched from the peer will not be stored locally.
-
+
DOC_END
NAME: cache_peer_access
certain persistent connection failures and any attempts to use a
different peer. However, low-level connection reopening attempts
(enabled using connect_retries) are not counted.
-
+
See also: forward_timeout and connect_retries.
DOC_END
DOC_START
Set the default value for max-size parameter on any cache_dir.
The value is specified in bytes, and the default is 4 MB.
-
+
If you wish to get a high BYTES hit ratio, you should probably
increase this (one 32 MB object hit counts for 3200 10KB
hits).
-
+
If you wish to increase hit ratio more than you want to
save bandwidth you should leave this low.
-
+
NOTE: if using the LFUDA replacement policy you should increase
this value to maximize the byte hit rate improvement of LFUDA!
See cache_replacement_policy for a discussion of this policy.
default %d/%b/%Y:%H:%M:%S %z
tr Response time (milliseconds)
dt Total time spent making DNS lookups (milliseconds)
- tS Approximate master transaction start time in
+ tS Approximate master transaction start time in
<full seconds since epoch>.<fractional seconds> format.
Currently, Squid considers the master transaction
started when a complete HTTP request header initiating
[http::]<sH Reply high offset sent
[http::]<sS Upstream object size
- [http::]<bs Number of HTTP-equivalent message body bytes
+ [http::]<bs Number of HTTP-equivalent message body bytes
received from the next hop, excluding chunked
transfer encoding and control messages.
Generated FTP/Gopher listings are treated as
[http::]<pt Peer response time in milliseconds. The timer starts
when the last request byte is sent to the next hop
and stops when the last response byte is received.
- [http::]<tt Total time in milliseconds. The timer
+ [http::]<tt Total time in milliseconds. The timer
starts with the first connect request (or write I/O)
sent to the first selected peer. The timer stops
with the last I/O with the last peer.
an already bumped connection, Squid logs the
corresponding SslBump mode ("splice", "bump",
"peek", "stare", "terminate", "server-first"
- or "client-first"). See the ssl_bump option
+ or "client-first"). See the ssl_bump option
for more information about these modes.
A "none" token is logged for requests that
DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
DOC_START
Configures whether and how Squid logs HTTP and ICP transactions.
- If access logging is enabled, a single line is logged for every
+ If access logging is enabled, a single line is logged for every
matching HTTP or ICP request. The recommended directive formats are:
access_log <module>:<place> [option ...] [acl acl ...]
In most cases, the first ACL name must not contain the '=' character
and should not be equal to an existing logformat name. You can always
start with an 'all' ACL to work around those restrictions.
-
+
Will log to the specified module:place using the specified format (which
must be defined in a logformat directive) those entries which match
ALL the acl's specified (which must be defined in acl clauses).
If no acl is specified, all requests will be logged to this destination.
-
+
===== Available options for the recommended directive format =====
logformat=name Names log line format (either built-in or
on-error=die|drop Defines action on unrecoverable errors. The
'drop' action ignores (i.e., does not log)
affected log records. The default 'die' action
- kills the affected worker. The drop action
+ kills the affected worker. The drop action
support has not been tested for modules other
than tcp.
Only supported by the stdio module.
===== Modules Currently available =====
-
+
none Do not log any requests matching these ACL.
Do not specify Place or logformat name.
-
+
stdio Write each log line to disk immediately at the completion of
each request.
Place: the filename and path to be written.
-
+
daemon Very similar to stdio. But instead of writing to disk the log
line is passed to a daemon helper for asychronous handling instead.
Place: varies depending on the daemon.
-
+
log_file_daemon Place: the file name and path to be written.
-
+
syslog To log each request via syslog facility.
Place: The syslog facility and priority level for these entries.
Place Format: facility.priority
And priority could be any of:
err, warning, notice, info, debug.
-
+
udp To send each log line as text data to a UDP receiver.
Place: The destination host name or IP and port.
Place Format: //host:port
The icap_log option format is:
icap_log <filepath> [<logformat name> [acl acl ...]]
icap_log none [acl acl ...]]
-
+
Please see access_log option documentation for details. The two
kinds of logs share the overall configuration approach and many
features.
icap::ru ICAP Request-URI. Similar to ru.
- icap::rm ICAP request method (REQMOD, RESPMOD, or
+ icap::rm ICAP request method (REQMOD, RESPMOD, or
OPTIONS). Similar to existing rm.
icap::>st The total size of the ICAP request sent to the ICAP
saved and for how long.
There are not really utilities to analyze this data, so you can safely
disable it (the default).
-
+
Store log uses modular logging outputs. See access_log for the list
of modules supported.
-
+
Example:
cache_store_log stdio:@DEFAULT_STORE_LOG@
cache_store_log daemon:@DEFAULT_STORE_LOG@
NATs may be able to put the connection on a "fast path" through the
translator using EPSV, as the EPRT command will never be used
- and therefore, translation of the data portion of the segments
+ and therefore, translation of the data portion of the segments
will never be needed.
EPSV is often required to interoperate with FTP servers on IPv6
The startup= and idle= options allow some measure of skew in your
tuning.
-
+
startup=
-
+
Sets a minimum of how many processes are to be spawned when Squid
starts or reconfigures. When set to zero the first request will
cause spawning of the first child process to handle it.
-
+
Starting too few will cause an initial slowdown in traffic as Squid
attempts to simultaneously spawn enough processes to cope.
-
+
idle=
-
+
Sets a minimum of how many processes Squid is to try and keep available
at all times. When traffic begins to rise above what the existing
processes can handle this many more will be spawned up to the maximum
To preserve same-origin security policies in browsers and
prevent Host: header forgery by redirectors Squid rewrites
any Host: header in redirected requests.
-
+
If you are running an accelerator this may not be a wanted
effect of a redirector. This directive enables you disable
Host: alteration in reverse-proxy traffic.
-
+
WARNING: Entries are cached on the result of the URL rewriting
process, so be careful if you have domain-virtual hosts.
-
+
WARNING: Squid and other software verifies the URL and Host
are matching, so be careful not to relay through other proxies
or inspecting firewalls with this disabled.
queues. Using too many helpers wastes your system resources.
Usage: numberofchildren [option]...
-
+
The startup= and idle= options allow some measure of skew in your
tuning.
-
+
startup=
-
+
Sets a minimum of how many processes are to be spawned when Squid
starts or reconfigures. When set to zero the first request will
cause spawning of the first child process to handle it.
-
+
Starting too few will cause an initial slowdown in traffic as Squid
attempts to simultaneously spawn enough processes to cope.
-
+
idle=
-
+
Sets a minimum of how many processes Squid is to try and keep available
at all times. When traffic begins to rise above what the existing
processes can handle this many more will be spawned up to the maximum
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
+ 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
to 0.
ensures that the client will receive an updated version
if one is available.
- store-stale stores responses even if they don't have explicit
- freshness or a validator (i.e., Last-Modified or an ETag)
- present, or if they're already stale. By default, Squid will
+ store-stale stores responses even if they don't have explicit
+ freshness or a validator (i.e., Last-Modified or an ETag)
+ present, or if they're already stale. By default, Squid will
not cache such responses because they usually can't be
reused. Note that such responses will be stale by default.
DEFAULT: none
DOC_START
usage: (size) [units] [[!]aclname]
-
- Sets an upper limit on how far (number of bytes) into the file
- a Range request may be to cause Squid to prefetch the whole file.
- If beyond this limit, Squid forwards the Range request as it is and
+
+ Sets an upper limit on how far (number of bytes) into the file
+ a Range request may be to cause Squid to prefetch the whole file.
+ If beyond this limit, Squid forwards the Range request as it is and
the result is NOT cached.
-
+
This is to stop a far ahead range request (lets say start at 17MB)
from making Squid fetch the whole object up to that point before
sending anything to the client.
-
- Multiple range_offset_limit lines may be specified, and they will
- be searched from top to bottom on each request until a match is found.
- The first match found will be used. If no line matches a request, the
+
+ Multiple range_offset_limit lines may be specified, and they will
+ be searched from top to bottom on each request until a match is found.
+ The first match found will be used. If no line matches a request, the
default limit of 0 bytes will be used.
-
+
'size' is the limit specified as a number of units.
-
+
'units' specifies whether to use bytes, KB, MB, etc.
If no units are specified bytes are assumed.
-
+
A size of 0 causes Squid to never fetch more than the
client requested. (default)
-
+
A size of 'none' causes Squid to always fetch the object from the
beginning so it may cache the result. (2.0 style)
-
+
'aclname' is the name of a defined ACL.
-
- NP: Using 'none' as the byte value here will override any quick_abort settings
+
+ NP: Using 'none' as the byte value here will override any quick_abort settings
that may otherwise apply to the range request. The range request will
be fully fetched from start to finish regardless of the client
actions. This affects bandwidth usage.
the idle connection pool (or equivalent). No effect on ongoing/active
transactions. Connection lifetime is the time period from the
connection acceptance or opening time until "now".
-
+
This limit is useful in environments with long-lived connections
where Squid configuration or environmental factors change during a
single connection lifetime. If unrestricted, some connections may
last for hours and even days, ignoring those changes that should
have affected their behavior or their existence.
-
+
Currently, a new lifetime value supplied via Squid reconfiguration
has no effect on already idle connections unless they become busy.
-
+
When set to '0' this limit is not used.
DOC_END
DOC_END
COMMENT_START
- OPTIONS INFLUENCING REQUEST FORWARDING
+ OPTIONS INFLUENCING REQUEST FORWARDING
-----------------------------------------------------------------------------
COMMENT_END
See the accf_dataready(9) man page for details.
Linux:
-
+
The 'data' filter delays delivering of new connections
to Squid until there is some data to process by TCP_ACCEPT_DEFER.
You may optionally specify a number of seconds to wait by
between ICAP OPTIONS requests.
Squid forgets ICAP service failures older than the specified
- value of memory-depth. The memory fading algorithm
- is approximate because Squid does not remember individual
+ value of memory-depth. The memory fading algorithm
+ is approximate because Squid does not remember individual
errors but groups them instead, splitting the option
value into ten time slots of equal length.
- When memory-depth is 0 and by default this option has no
+ When memory-depth is 0 and by default this option has no
effect on service failure expiration.
Squid always forgets failures when updating service settings
DOC_START
The ICAP Preview feature allows the ICAP server to handle the
HTTP message by looking only at the beginning of the message body
- or even without receiving the body at all. In some environments,
+ or even without receiving the body at all. In some environments,
previews greatly speedup ICAP processing.
During an ICAP OPTIONS transaction, the server may tell Squid what
* block: send an HTTP error response to the client
* bypass: ignore the "over-connected" ICAP service
* wait: wait (in a FIFO queue) for an ICAP connection slot
- * force: proceed, ignoring the Max-Connections limit
+ * force: proceed, ignoring the Max-Connections limit
In SMP mode with N workers, each worker assumes the service
connection limit is Max-Connections/N, even though not all
The default value is "bypass" if service is bypassable,
otherwise it is set to "wait".
-
+
max-conn=number
Use the given number as the Max-Connections limit, regardless
DOC_START
This deprecated option was documented to define an ICAP service
chain, even though it actually defined a set of similar, redundant
- services, and the chains were not supported.
+ services, and the chains were not supported.
To define a set of redundant services, please use the
adaptation_service_set directive. For service chains, use
connection-encryption=on|off
Determines the eCAP service effect on the connections_encrypted
- ACL.
+ ACL.
Defaults to "on", which does not taint the master transaction
w.r.t. that ACL.
This option specifies the table entry names that Squid must accept
from and forward to the adaptation transactions.
- An ICAP REQMOD or RESPMOD transaction may set an entry in the
- shared table by returning an ICAP header field with a name
+ An ICAP REQMOD or RESPMOD transaction may set an entry in the
+ shared table by returning an ICAP header field with a name
specified in adaptation_masterx_shared_names.
An eCAP REQMOD or RESPMOD transaction may set an entry in the
headers or eCAP options to Squid ICAP requests or eCAP transactions.
Use it to pass custom authentication tokens and other
transaction-state related meta information to an ICAP/eCAP service.
-
+
The addition of a meta header is ACL-driven:
adaptation_meta name value [!]aclname ...
-
+
Processing for a given header name stops after the first ACL list match.
Thus, it is impossible to add two headers with the same name. If no ACL
- lists match for a given header name, no such header is added. For
+ lists match for a given header name, no such header is added. For
example:
-
+
# do not debug transactions except for those that need debugging
adaptation_meta X-Debug 1 needs_debugging
-
+
# log all transactions except for those that must remain secret
adaptation_meta X-Log 1 !keep_secret
-
+
# mark transactions from users in the "G 1" group
adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1
-
+
The "value" parameter may be a regular squid.conf token or a "double
quoted string". Within the quoted string, use backslash (\) to escape
any character, which is currently only useful for escaping backslashes
DOC_START
Maximum number of bytes packet size to advertise via EDNS.
Set to "none" to disable EDNS large packet support.
-
+
For legacy reasons DNS UDP replies will default to 512 bytes which
is too small for many responses. EDNS provides a means for Squid to
negotiate receiving larger responses back immediately without having
to failover with repeat requests. Responses larger than this limit
will retain the old behaviour of failover to TCP DNS.
-
+
Squid has no real fixed limit internally, but allowing packet sizes
over 1500 bytes requires network jumbogram support and is usually not
necessary.
-
+
WARNING: The RFC also indicates that some older resolvers will reply
with failure of the whole request if the extension is added. Some
resolvers have already been identified which will reply with mangled
receiving an error response with status 403 (Forbidden),
500 (Internal Error), 501 or 503 (Service not available).
Status 502 and 504 (Gateway errors) are always retried.
-
+
This is mainly useful if you are in a complex cache hierarchy to
work around access control errors.
-
+
NOTE: This retry will attempt to find another working destination.
Which is different from the server which just failed.
DOC_END
DEFAULT: on
LOC: Config.onoff.WIN32_IpAddrChangeMonitor
DOC_START
- On Windows Squid by default will monitor IP address changes and will
+ On Windows Squid by default will monitor IP address changes and will
reconfigure itself after any detected event. This is very useful for
proxies connected to internet with dial-up interfaces.
In some cases (a Proxy server acting as VPN gateway is one) it could be
and FTP agents that require a "Please Continue" control message response
to actually send the request body to Squid. It is mostly useful in
adaptation environments.
-
+
When Squid receives an HTTP request with an "Expect: 100-continue"
header or an FTP upload command (e.g., STOR), Squid normally sends the
request headers or FTP command information to an adaptation service (or
that request body or data transfer may never come because Squid has not
responded with the HTTP 100 or FTP 150 (Please Continue) control message
to the request sender yet!
-
+
An allow match tells Squid to respond with the HTTP 100 or FTP 150
(Please Continue) control message on its own, before forwarding the
request to an adaptation service or peer. Such a response usually forces
projects / thirdparty / squid.git / commitdiff
