across all Squid processes.
COMMENT_END
+# options still not yet ported from 2.7 to 3.x
+NAME: broken_vary_encoding
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: cache_vary
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: collapsed_forwarding
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3. see http://bugs.squid-cache.org/show_bug.cgi?id=3495
+DOC_END
+
+NAME: error_map
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: external_refresh_check
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: ignore_ims_on_miss
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: location_rewrite_program location_rewrite_access location_rewrite_children location_rewrite_concurrency
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+NAME: refresh_stale_hit
+TYPE: obsolete
+DOC_START
+ This option is not yet supported by Squid-3.
+DOC_END
+
+# no Options Removed in 3.3
+
# Options Removed in 3.2
NAME: ignore_expect_100
TYPE: obsolete
NAME: dns_v4_fallback
TYPE: obsolete
DOC_START
- Remove this line.
+ Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant.
DOC_END
NAME: ftp_list_width
Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead.
DOC_END
+NAME: maximum_single_addr_tries
+TYPE: obsolete
+DOC_START
+ Replaced by connect_retries. The behaviour has changed, please read the documentation before altering.
+DOC_END
+
+NAME: update_headers
+TYPE: obsolete
+DOC_START
+ Remove this line. The feature is supported by default in storage types where update is implemented.
+DOC_END
+
NAME: url_rewrite_concurrency
TYPE: obsolete
DOC_START
Remove this line. All valid methods for HTTP are accepted by default.
DOC_END
+# 2.7 Options Removed/Replaced in 3.2
+NAME: zero_buffers
+TYPE: obsolete
+DOC_NONE
+
# 2.7 Options Removed/Replaced in 3.1
NAME: incoming_rate
TYPE: obsolete
Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead.
DOC_END
+NAME: wais_relay_host
+TYPE: obsolete
+DOC_START
+ Replace this line with 'cache_peer' configuration.
+DOC_END
+
+NAME: wais_relay_port
+TYPE: obsolete
+DOC_START
+ Replace this line with 'cache_peer' configuration.
+DOC_END
+
COMMENT_START
OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
"program" cmdline
Specify the command for the external authenticator. Such a program
- reads a line containing "username password" and replies "OK" or
- "ERR" in an endless loop. "ERR" responses may optionally be followed
- by a error description available as %m in the returned error page.
+ reads a line containing "username password" and replies with one of
+ three results:
+
+ OK
+ the user exists.
+
+ ERR
+ the user does not exist.
+
+ BH
+ An internal error occurred in the helper, preventing
+ a result being identified.
+
+ "ERR" and "BH" results may optionally be followed by message="..."
+ containing a description available as %m in the returned error page.
+
If you use an authenticator, make sure you have 1 acl of type
proxy_auth.
If you want to use the traditional NCSA proxy authentication, set
this line to something like
- auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
+ auth_param basic program @DEFAULT_PREFIX@/libexec/basic_ncsa_auth @DEFAULT_PREFIX@/etc/passwd
"utf8" on|off
- HTTP uses iso-latin-1 as characterset, while some authentication
+ HTTP uses iso-latin-1 as character set, while some authentication
backends such as LDAP expects UTF-8. If this is set to on Squid will
translate the HTTP iso-latin-1 charset to UTF-8 before sending the
username & password to the helper.
supports one request at a time. Setting this to a number greater than
0 changes the protocol used to include a channel number first on the
request/response line, allowing multiple requests to be sent to the
- same helper in parallell without wating for the response.
+ same helper in parallel without waiting for the response.
Must not be set unless it's known the helper supports this.
auth_param basic children 20 startup=0 idle=1
"program" cmdline
Specify the command for the external authenticator. Such
a program reads a line containing "username":"realm" and
- replies with the appropriate H(A1) value hex encoded or
- ERR if the user (or his H(A1) hash) does not exists.
- See rfc 2616 for the definition of H(A1).
- "ERR" responses may optionally be followed by a error description
- available as %m in the returned error page.
+ replies with one of three results:
+
+ OK ha1="..."
+ the user exists. The ha1= key is mandatory and
+ contains the appropriate H(A1) value, hex encoded.
+ See rfc 2616 for the definition of H(A1).
+
+ ERR
+ the user does not exist.
+
+ BH
+ An internal error occurred in the helper, preventing
+ a result being identified.
+
+ "ERR" and "BH" results may optionally be followed by message="..."
+ containing a description available as %m in the returned error page.
By default, the digest authentication scheme is not used unless a
program is specified.
auth_param digest program @DEFAULT_PREFIX@/bin/digest_pw_auth @DEFAULT_PREFIX@/etc/digpass
"utf8" on|off
- HTTP uses iso-latin-1 as characterset, while some authentication
+ HTTP uses iso-latin-1 as character set, while some authentication
backends such as LDAP expects UTF-8. If this is set to on Squid will
translate the HTTP iso-latin-1 charset to UTF-8 before sending the
username & password to the helper.
supports one request at a time. Setting this to a number greater than
0 changes the protocol used to include a channel number first on the
request/response line, allowing multiple requests to be sent to the
- same helper in parallell without wating for the response.
+ same helper in parallel without waiting for the response.
Must not be set unless it's known the helper supports this.
auth_param digest children 20 startup=0 idle=1
"nonce_strictness" on|off
Determines if squid requires strict increment-by-1 behavior
for nonce counts, or just incrementing (off - for use when
- useragents generate nonce counts that occasionally miss 1
+ user agents generate nonce counts that occasionally miss 1
(ie, 1,2,4,6)). Default off.
"check_nonce_count" on|off
Such a program reads exchanged NTLMSSP packets with
the browser via Squid until authentication is completed.
If you use an NTLM authenticator, make sure you have 1 acl
- of type proxy_auth. By default, the NTLM authenticator_program
+ of type proxy_auth. By default, the NTLM authenticator program
is not used.
- auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
+ auth_param ntlm program /usr/bin/ntlm_auth
"children" numberofchildren [startup=N] [idle=N]
The maximum number of authenticator processes to spawn (default 5).
using the Kerberos mechanisms.
If you use a Negotiate authenticator, make sure you have at least
one acl of type proxy_auth active. By default, the negotiate
- authenticator_program is not used.
+ authenticator program is not used.
The only supported program for this role is the ntlm_auth
program distributed as part of Samba, version 4 or later.
- auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
+ auth_param negotiate program /usr/bin/ntlm_auth --helper-protocol=gss-spnego
"children" numberofchildren [startup=N] [idle=N]
The maximum number of authenticator processes to spawn (default 5).
If you start too few Squid will have to wait for them to
process a backlog of credential verifications, slowing it
- down. When crendential verifications are done via a (slow)
+ down. When credential verifications are done via a (slow)
network you are likely to need lots of authenticator
processes.
LOC: Config.authenticateGCInterval
DOC_START
The time period between garbage collection across the username cache.
- This is a tradeoff between memory utilization (long intervals - say
+ This is a trade-off between memory utilization (long intervals - say
2 days) and CPU (short intervals - say 1 minute). Only change if you
have good reason to.
DOC_END
NAME: authenticate_ip_ttl
TYPE: time_t
LOC: Config.authenticateIpTTL
-DEFAULT: 0 seconds
+DEFAULT: 1 second
DOC_START
If you use proxy authentication and the 'max_user_ip' ACL,
this directive controls how long Squid remembers the IP
addresses associated with each user. Use a small value
(e.g., 60 seconds) if your users might change addresses
- quickly, as is the case with dialups. You might be safe
+ quickly, as is the case with dialup. You might be safe
using a larger value (e.g., 2 hours) in a corporate LAN
environment with relatively static address assignments.
DOC_END
list separator. ; can be any non-alphanumeric
character.
+ %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.
- In addition to the above, any string specified in the referencing
- acl will also be included in the helper request line, after the
- specified formats (see the "acl external" directive)
- The helper receives lines per the above format specification,
- and returns lines starting with OK or ERR indicating the validity
- of the request and optionally followed by additional keywords with
- more details.
+ General request syntax:
+
+ [channel-ID] FORMAT-values [acl-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.
+
+ If using protocol=2.5 then the request sent to the helper is not
+ URL escaped to protect against whitespace.
+
+ NOTE: protocol=3.0 is deprecated as no longer necessary.
+
+ When using the concurrency= option the protocol is changed by
+ introducing a query channel tag in front of the request/response.
+ The query channel tag is a number between 0 and concurrency-1.
+ This value must be echoed back unchanged to Squid as the first part
+ of the response relating to its request.
+
+
+ The helper receives lines expanded per the above format specification
+ and for each input line returns 1 line starting with OK/ERR/BH result
+ code and optionally followed by additional keywords with more details.
+
General result syntax:
- OK/ERR keyword=value ...
+ [channel-ID] result keyword=value ...
+
+ Result consists of one of the codes:
+
+ OK
+ the ACL test produced a match.
+
+ ERR
+ the ACL test does not produce a match.
+
+ BH
+ An internal error occurred in the helper, preventing
+ a result being identified.
+
+ The meaning of 'a match' is determined by your squid.conf
+ access control configuration. See the Squid wiki for details.
Defined keywords:
user= The users name (login)
+
password= The users password (for login= cache_peer option)
- message= Message describing the reason. Available as %o
- in error pages
- tag= Apply a tag to a request (for both ERR and OK results)
- Only sets a tag, does not alter existing tags.
+
+ message= Message describing the reason for this response.
+ Available as %o in error pages.
+ Useful on (ERR and BH results).
+
+ tag= Apply a tag to a request. Only sets a tag once,
+ does not alter existing tags.
+
log= String to be logged in access.log. Available as
- %ea in logformat specifications
+ %ea in logformat specifications.
- If protocol=3.0 (the default) then URL escaping is used to protect
- each value in both requests and responses.
+ Any keywords may be sent on any response whether OK, ERR or BH.
- If using protocol=2.5 then all values need to be enclosed in quotes
- if they may contain whitespace, or the whitespace escaped using \.
- And quotes or \ characters within the keyword value must be \ escaped.
+ All response keyword values need to be a single token with URL
+ escaping, or enclosed in double quotes (") and escaped using \ on
+ any double quotes or \ characters within the value. The wrapping
+ double quotes are removed before the value is interpreted by Squid.
+ \r and \n are also replace by CR and LF.
- When using the concurrency= option the protocol is changed by
- introducing a query channel tag infront of the request/response.
- The query channel tag is a number between 0 and concurrency-1.
+ Some example key values:
+
+ user=John%20Smith
+ user="John Smith"
+ user="J. \"Bob\" Smith"
DOC_END
NAME: acl
TYPE: acl
LOC: Config.aclList
-IFDEF USE_SSL
+IF USE_SSL
DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED
DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID
DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH
When using "file", the file should contain one item per line.
- 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.
+ Some acl types supports options which changes their default behaviour.
+ The available options are:
+
+ -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.
+
+ -n Disable lookups and address type conversions. If lookup or
+ conversion is required because the parameter type (IP or
+ domain name) does not match the message address type (domain
+ name or IP), then the ACL would immediately declare a mismatch
+ without any warnings or lookups.
+
+ -- 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)
Some acl types require suspending the current request in order
to access some external data source.
acl aclname src ip-address/mask ... # clients IP address [fast]
acl aclname src addr1-addr2/mask ... # range of addresses [fast]
- acl aclname dst ip-address/mask ... # URL host's IP address [slow]
+ acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow]
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)
acl aclname srcdomain .foo.com ...
# reverse lookup, from client IP [slow]
- acl aclname dstdomain .foo.com ...
+ acl aclname dstdomain [-n] .foo.com ...
# Destination server from URL [fast]
acl aclname srcdom_regex [-i] \.foo\.com ...
# regex matching client name [slow]
- acl aclname dstdom_regex [-i] \.foo\.com ...
+ acl aclname dstdom_regex [-n] [-i] \.foo\.com ...
# regex matching server [fast]
#
# For dstdomain and dstdom_regex a reverse lookup is tried if a IP
acl aclname url_regex [-i] ^http:// ...
# regex matching on whole URL [fast]
+ acl aclname urllogin [-i] [^a-zA-Z0-9] ...
+ # regex matching on URL login field
acl aclname urlpath_regex [-i] \.gif$ ...
# regex matching on URL path [fast]
# effect in rules that affect the reply data stream such as
# http_reply_access.
-IFDEF USE_SSL
+IF USE_SSL
acl aclname ssl_error errorname
# match against SSL certificate validation error [fast]
#
#
# NOTE: The ssl_error ACL is only supported with sslproxy_cert_error,
# sslproxy_cert_sign, and sslproxy_cert_adapt options.
+
+ acl aclname server_cert_fingerprint [-sha1] fingerprint
+ # match against server SSL certificate fingerprint [fast]
+ #
+ # 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
+ # the only algorithm supported (-sha1).
ENDIF
Examples:
IFDEF: FOLLOW_X_FORWARDED_FOR
LOC: Config.accessList.followXFF
DEFAULT_IF_NONE: deny all
+DEFAULT_DOC: X-Forwarded-For header will be ignored.
DOC_START
Allowing or Denying the X-Forwarded-For header to be followed to
find the original source of a request.
sources is required to prevent abuse of your proxy.
DOC_END
+NAME: spoof_client_ip
+TYPE: acl_access
+LOC: Config.accessList.spoof_client_ip
+DEFAULT: none
+DEFAULT_DOC: Allow spoofing on all TPROXY traffic.
+DOC_START
+ Control client IP address spoofing of TPROXY traffic based on
+ defined access lists.
+
+ spoof_client_ip allow|deny [!]aclname ...
+
+ If there are no "spoof_client_ip" lines present, the default
+ is to "allow" spoofing of any suitable request.
+
+ Note that the cache_peer "no-tproxy" option overrides this ACL.
+
+ This clause supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+DOC_END
+
NAME: http_access
TYPE: acl_access
LOC: Config.accessList.http
DEFAULT_IF_NONE: deny all
+DEFAULT_DOC: Deny, unless rules exist in squid.conf.
DOC_START
Allowing or Denying access based on defined access lists
#
# Recommended minimum Access Permission configuration:
#
-# Only allow cachemgr access from localhost
-http_access allow localhost manager
-http_access deny manager
-
# Deny requests to certain unsafe ports
http_access deny !Safe_ports
# Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports
+# Only allow cachemgr access from localhost
+http_access allow localhost manager
+http_access deny manager
+
# We strongly recommend the following be uncommented to protect innocent
# web applications running on the proxy server who think the only
# one who can access services on "localhost" is a local user
TYPE: acl_access
LOC: Config.accessList.adapted_http
DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
DOC_START
Allowing or Denying access based on defined access lists
TYPE: acl_access
LOC: Config.accessList.reply
DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
DOC_START
Allow replies to client requests. This is complementary to http_access.
http_reply_access allow|deny [!] aclname ...
NOTE: if there are no access lines present, the default is to allow
- all replies
+ all replies.
If none of the access lines cause a match the opposite of the
last line will apply. Thus it is good practice to end the rules
NAME: icp_access
TYPE: acl_access
LOC: Config.accessList.icp
-DEFAULT_IF_NONE: deny all
+DEFAULT: none
+DEFAULT_DOC: Deny, unless rules exist in squid.conf.
DOC_START
Allowing or Denying access to the ICP port based on defined
access lists
icp_access allow|deny [!]aclname ...
- See http_access for details
+ NOTE: The default if no icp_access lines are present is to
+ deny all traffic. This default may cause problems with peers
+ using ICP.
This clause only supports fast acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
IFDEF: USE_HTCP
TYPE: acl_access
LOC: Config.accessList.htcp
-DEFAULT_IF_NONE: deny all
+DEFAULT: none
+DEFAULT_DOC: Deny, unless rules exist in squid.conf.
DOC_START
Allowing or Denying access to the HTCP port based on defined
access lists
htcp_access allow|deny [!]aclname ...
- See http_access for details
+ See also htcp_clr_access for details on access control for
+ cache purge (CLR) HTCP messages.
NOTE: The default if no htcp_access lines are present is to
deny all traffic. This default may cause problems with peers
IFDEF: USE_HTCP
TYPE: acl_access
LOC: Config.accessList.htcp_clr
-DEFAULT_IF_NONE: deny all
+DEFAULT: none
+DEFAULT_DOC: Deny, unless rules exist in squid.conf.
DOC_START
Allowing or Denying access to purge content using HTCP based
- on defined access lists
+ on defined access lists.
+ See htcp_access for details on general HTCP access control.
htcp_clr_access allow|deny [!]aclname ...
- See http_access for details
-
This clause only supports fast acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
# Allow HTCP CLR requests from trusted peers
-acl htcp_clr_peer src 172.16.1.2
+acl htcp_clr_peer src 192.0.2.2 2001:DB8::2
htcp_clr_access allow htcp_clr_peer
+htcp_clr_access deny all
DOC_END
NAME: miss_access
TYPE: acl_access
LOC: Config.accessList.miss
DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
DOC_START
Determins whether network access is permitted when satisfying a request.
to force your neighbors to use you as a sibling instead of
a parent.
- acl localclients src 172.16.0.0/16
- miss_access allow localclients
+ acl localclients src 192.0.2.0/24 2001:DB8::a:0/64
miss_access deny !localclients
+ miss_access allow all
This means only your local clients are allowed to fetch relayed/MISS
replies from the network and all other clients can only fetch cached
objects (HITs).
-
The default for this setting allows all clients who passed the
http_access rules to relay via this proxy.
NAME: ident_lookup_access
TYPE: acl_access
IFDEF: USE_IDENT
-DEFAULT_IF_NONE: deny all
+DEFAULT: none
+DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched.
LOC: Ident::TheConfig.identLookup
DOC_START
A list of ACL elements which, if matched, cause an ident
COMMENT: size [acl acl...]
TYPE: acl_b_size_t
DEFAULT: none
+DEFAULT_DOC: No limit is applied.
LOC: Config.ReplyBodySize
DOC_START
This option specifies the maximum size of a reply body. It can be
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. An average XXX-bit certificate
- consumes about XXX bytes of RAM.
+ default value is 4MB.
TLS / SSL 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.
+
tproxy Support Linux TPROXY for spoofing outgoing
connections using the client IP address.
NP: disables authentication and maybe IPv6 on the port.
An "ssl_bump server-first" match is required to
fully enable bumping of intercepted SSL connections.
- Requires tproxy.
+ Requires tproxy or intercept.
Omitting the mode flag causes default forward proxy mode to be used.
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. An average XXX-bit certificate
- consumes about XXX bytes of RAM.
+ default value is 4MB.
See http_port for a list of available options.
DOC_END
NAME: tcp_outgoing_address
TYPE: acl_address
DEFAULT: none
+DEFAULT_DOC: Address selection is performed by the operating system.
LOC: Config.accessList.outgoing_address
DOC_START
Allows you to map requests to different outgoing IP addresses
* Reverse-proxy traffic is not checked at all.
* Intercepted traffic which passes verification is handled
- normally.
+ according to client_dst_passthru.
- For now it also forces suspicious requests to go DIRECT to the
- original destination, overriding client_dst_passthru for
- intercepted requests which fail Host: verification.
+ * 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.
-DOC_END
-
-NAME: client_dst_passthru
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.client_dst_passthru
-DOC_START
- With NAT or TPROXY intercepted traffic Squid may pass the request
- directly to the original client destination IP or seek a faster
- source.
- This option (on by default) prevents cache_peer and alternative DNS
- entries being used on intercepted traffic. Both of which lead to
- the security vulnerability outlined below.
-
- SECURITY WARNING:
- This directive should only be disabled if cache_peer are required.
+ 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
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
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.client_dst_passthru
+DOC_START
+ 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
COMMENT_START
NAME: sslproxy_version
IFDEF: USE_SSL
DEFAULT: 1
+DEFAULT_DOC: automatic SSL/TLS version negotiation
LOC: Config.ssl_client.version
TYPE: int
DOC_START
IFDEF: USE_SSL
TYPE: sslproxy_ssl_bump
LOC: Config.accessList.ssl_bump
+DEFAULT_DOC: Does not bump unless rules are present in squid.conf
DEFAULT: none
DOC_START
This option is consulted when a CONNECT request is received on
# Example: Bump all requests except those originating from
- # localhost and those going to example.com.
+ # localhost or those going to example.com.
acl broken_sites dstdomain .example.com
ssl_bump none localhost
NAME: sslproxy_cert_error
IFDEF: USE_SSL
DEFAULT: none
+DEFAULT_DOC: Server certificate errors terminate the transaction.
LOC: Config.ssl_client.cert_error
TYPE: acl_access
DOC_START
Using slow acl types may result in server crashes
Without this option, all server certificate validation errors
- terminate the transaction. Bypassing validation errors is dangerous
- because an error usually implies that the server cannot be trusted and
- the connection may be insecure.
+ terminate the transaction to protect Squid and the client.
- See also: sslproxy_flags and DONT_VERIFY_PEER.
+ SECURITY WARNING:
+ Bypassing validation errors is dangerous because an
+ error usually implies that the server cannot be trusted
+ and the connection may be insecure.
- Default setting: sslproxy_cert_error deny all
+ See also: sslproxy_flags and DONT_VERIFY_PEER.
DOC_END
NAME: sslproxy_cert_sign
sslproxy_cert_sign <signing algorithm> acl ...
The following certificate signing algorithms are supported:
+
signTrusted
Sign using the configured CA certificate which is usually
placed in and trusted by end-user browsers. This is the
default for trusted origin server certificates.
+
signUntrusted
Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error.
This is the default for untrusted origin server certificates
that are not self-signed (see ssl::certUntrusted).
+
signSelf
Sign using a self-signed certificate with the right CN to
generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the
bump-server-first is used.
DOC_END
-NAME: sslproxy_cert_adapt
+NAME: sslproxy_cert_adapt
IFDEF: USE_SSL
DEFAULT: none
TYPE: sslproxy_cert_adapt
sslproxy_cert_adapt <adaptation algorithm> acl ...
The following certificate adaptation algorithms are supported:
+
setValidAfter
Sets the "Not After" property to the "Not After" property of
the CA certificate used to sign generated certificates.
+
setValidBefore
Sets the "Not Before" property to the "Not Before" property of
the CA certificate used to sign generated certificates.
+
setCommonName or setCommonName{CN}
Sets Subject.CN property to the host name specified as a
CN parameter or, if no explicit CN parameter was specified,
You must have at least one ssl_crtd process.
DOC_END
+NAME: sslcrtvalidator_program
+TYPE: eol
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Ssl::TheConfig.ssl_crt_validator
+DOC_START
+ Specify the location and options of the executable for ssl_crt_validator
+ process.
+
+ Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ...
+
+ Options:
+ ttl=n TTL in seconds for cached results. The default is 60 secs
+ cache=n limit the result cache size. The default value is 2048
+DOC_END
+
+NAME: sslcrtvalidator_children
+TYPE: HelperChildConfig
+IFDEF: USE_SSL
+DEFAULT: 32 startup=5 idle=1 concurrency=1
+LOC: Ssl::TheConfig.ssl_crt_validator_Children
+DOC_START
+ The maximum number of processes spawn to service SSL server.
+ The maximum this may be safely set to is 32.
+
+ 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. Defaults to 0 which indicates the certficate validator
+ is a old-style single threaded redirector.
+
+ 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
+ ID from the request must be echoed back with the response
+ to that request.
+
+ You must have at least one ssl_crt_validator process.
+DOC_END
+
COMMENT_START
OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
-----------------------------------------------------------------------------
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.
LOC: none
DOC_START
Use to limit the domains for which a neighbor cache will be
- queried. Usage:
+ queried.
- cache_peer_domain cache-host domain [domain ...]
- cache_peer_domain cache-host !domain
+ Usage:
+ cache_peer_domain cache-host domain [domain ...]
+ cache_peer_domain cache-host !domain
For example, specifying
Similar to 'cache_peer_domain' but provides more flexibility by
using ACL elements.
- cache_peer_access cache-host allow|deny [!]aclname ...
+ Usage:
+ cache_peer_access cache-host allow|deny [!]aclname ...
The syntax is identical to 'http_access' and the other lists of
ACL elements. See the comments for 'http_access' below, or
NAME: neighbor_type_domain
TYPE: hostdomaintype
DEFAULT: none
+DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer.
LOC: none
DOC_START
- usage: neighbor_type_domain neighbor parent|sibling domain domain ...
+ Modify the cache_peer neighbor type when passing requests
+ about specific domains to the peer.
- Modifying the neighbor type for specific domains is now
- possible. You can treat some domains differently than the
- default neighbor type specified on the 'cache_peer' line.
- Normally it should only be necessary to list domains which
- should be treated differently because the default neighbor type
- applies for hostnames which do not match domains listed here.
+ Usage:
+ neighbor_type_domain neighbor parent|sibling domain domain ...
-EXAMPLE:
- cache_peer cache.foo.org parent 3128 3130
- neighbor_type_domain cache.foo.org sibling .com .net
- neighbor_type_domain cache.foo.org sibling .au .de
+ For example:
+ cache_peer foo.example.com parent 3128 3130
+ neighbor_type_domain foo.example.com sibling .au .de
+
+ The above configuration treats all requests to foo.example.com as a
+ parent proxy unless the request is for a .au or .de ccTLD domain name.
DOC_END
NAME: dead_peer_timeout
TYPE: memcachemode
LOC: Config
DEFAULT: always
+DEFAULT_DOC: Keep the most recently fetched objects in memory
DOC_START
Controls which objects to keep in the memory cache (cache_mem)
The memory replacement policy parameter determines which
objects are purged from memory when memory space is needed.
- See cache_replacement_policy for details.
+ See cache_replacement_policy for details on algorithms.
DOC_END
COMMENT_START
heap LFUDA: Least Frequently Used with Dynamic Aging
heap LRU : LRU policy implemented using a heap
- Applies to any cache_dir lines listed below this.
+ Applies to any cache_dir lines listed below this directive.
The LRU policies keeps recently referenced objects.
replacement policies.
NOTE: if using the LFUDA replacement policy you should increase
- the value of maximum_object_size above its default of 4096 KB to
+ the value of maximum_object_size above its default of 4 MB to
to maximize the potential byte hit rate improvement of LFUDA.
For more information about the GDSF and LFUDA cache replacement
NAME: cache_dir
TYPE: cachedir
DEFAULT: none
+DEFAULT_DOC: No disk cache. Store cache ojects only in memory.
LOC: Config.cacheSwap
DOC_START
- Usage:
-
- cache_dir Type Directory-Name Fs-specific-data [options]
+ Format:
+ cache_dir Type Directory-Name Fs-specific-data [options]
You can specify multiple cache_dir lines to spread the
cache among different disk partitions.
and should use configuration macros or conditionals to give each
worker interested in disk caching a dedicated cache directory.
- The ufs store type:
+
+ ==== The ufs store type ====
"ufs" is the old well-known Squid storage format that has always
been there.
- cache_dir ufs Directory-Name Mbytes L1 L2 [options]
+ Usage:
+ cache_dir ufs Directory-Name Mbytes L1 L2 [options]
'Mbytes' is the amount of disk space (MB) to use under this
directory. The default is 100 MB. Change this to suit your
will be created under each first-level directory. The default
is 256.
- The aufs store type:
+
+ ==== The aufs store type ====
"aufs" uses the same storage format as "ufs", utilizing
POSIX-threads to avoid blocking the main Squid process on
disk-I/O. This was formerly known in Squid as async-io.
- cache_dir aufs Directory-Name Mbytes L1 L2 [options]
+ Usage:
+ cache_dir aufs Directory-Name Mbytes L1 L2 [options]
see argument descriptions under ufs above
- The diskd store type:
+
+ ==== The diskd store type ====
"diskd" uses the same storage format as "ufs", utilizing a
separate process to avoid blocking the main Squid process on
disk-I/O.
- cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
+ Usage:
+ cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
see argument descriptions under ufs above
higher hit ratio at the expense of an increase in response
time.
- The rock store type:
+ ==== The rock store type ====
+
+ Usage:
cache_dir rock Directory-Name Mbytes <max-size=bytes> [options]
The Rock Store type is a database-style storage. All cached
slot size is specified in bytes using the max-size option. See
below for more info on the max-size option.
+ If possible, Squid using Rock Store creates a dedicated kid
+ process called "disker" to avoid blocking Squid worker(s) on disk
+ I/O. One disker kid is created for each rock cache_dir. Diskers
+ are created only when Squid, running in daemon mode, has support
+ for the IpcIo disk I/O module.
+
swap-timeout=msec: Squid will not start writing a miss to or
reading a hit from disk if it estimates that the swap operation
will take more than the specified number of milliseconds. By
enforcement. Currently supported by IpcIo module only.
- The coss store type:
+ ==== The coss store type ====
NP: COSS filesystem in Squid-3 has been deemed too unstable for
production use and has thus been removed from this release.
called 'stripe' in the directory names in the config - and
this will be created by squid -z.
- Common options:
- no-store, no new objects should be stored to this cache_dir
+ ==== COMMON OPTIONS ====
+
+ no-store no new objects should be stored to this cache_dir.
+
+ min-size=n the minimum object size in bytes this cache_dir
+ will accept. It's used to restrict a cache_dir
+ to only store large objects (e.g. AUFS) while
+ other stores are optimized for smaller objects
+ (e.g. COSS).
+ Defaults to 0.
- min-size=n, refers to the min object size in bytes this cache_dir
- will accept. It's used to restrict a cache_dir to only store
- large objects (e.g. aufs) while other storedirs are optimized
- for smaller objects (e.g. COSS). Defaults to 0.
+ max-size=n the maximum object size in bytes this cache_dir
+ supports.
+ The value in maximum_object_size directive, sets
+ a default unless more specific details are available
+ about the cache_dir (ie a small store capacity).
- max-size=n, refers to the max object size in bytes this cache_dir
- supports. It is used to select the cache_dir to store the object.
Note: To make optimal use of the max-size limits you should order
- the cache_dir lines with the smallest max-size value first and the
- ones with no max-size specification last.
+ the cache_dir lines with the smallest max-size value first.
Note for coss, max-size must be less than COSS_MEMBUF_SZ,
which can be changed with the --with-coss-membuf-size=N configure
option.
+
NOCOMMENT_START
# Uncomment and adjust the following to add a disk cache directory.
LOC: Config.store_dir_select_algorithm
DEFAULT: least-load
DOC_START
- Set this to 'round-robin' as an alternative.
+ How Squid selects which cache_dir to use when the response
+ object will fit into more than one.
+
+ Regardless of which algorithm is used the cache_dir min-size
+ and max-size parameters are obeyed. As such they can affect
+ the selection algorithm by limiting the set of considered
+ cache_dir.
+
+ Algorithms:
+
+ least-load
+
+ This algorithm is suited to caches with similar cache_dir
+ sizes and disk speeds.
+
+ The disk with the least I/O pending is selected.
+ When there are multiple disks with the same I/O load ranking
+ the cache_dir with most available capacity is selected.
+
+ When a mix of cache_dir sizes are configured the faster disks
+ have a naturally lower I/O loading and larger disks have more
+ capacity. So space used to store objects and data throughput
+ may be very unbalanced towards larger disks.
+
+
+ round-robin
+
+ This algorithm is suited to caches with unequal cache_dir
+ disk sizes.
+
+ Each cache_dir is selected in a rotation. The next suitable
+ cache_dir is used.
+
+ Available cache_dir capacity is only considered in relation
+ to whether the object will fit and meets the min-size and
+ max-size parameters.
+
+ Disk I/O loading is only considered to prevent overload on slow
+ disks. This algorithm does not spread objects by size, so any
+ I/O loading per-disk may appear very unbalanced and volatile.
+
DOC_END
NAME: max_open_disk_fds
TYPE: int
LOC: Config.max_open_disk_fds
DEFAULT: 0
+DEFAULT_DOC: no limit
DOC_START
To avoid having disk as the I/O bottleneck Squid can optionally
bypass the on-disk cache if more than this amount of disk file
COMMENT: (bytes)
TYPE: b_int64_t
DEFAULT: 0 KB
+DEFAULT_DOC: no limit
LOC: Config.Store.minObjectSize
DOC_START
Objects smaller than this size will NOT be saved on disk. The
- value is specified in kilobytes, and the default is 0 KB, which
- means there is no minimum.
+ value is specified in bytes, and the default is 0 KB, which
+ means all responses can be stored.
DOC_END
NAME: maximum_object_size
COMMENT: (bytes)
TYPE: b_int64_t
-DEFAULT: 4096 KB
+DEFAULT: 4 MB
LOC: Config.Store.maxObjectSize
DOC_START
- Objects larger than this size will NOT be saved on disk. The
- value is specified in kilobytes, and the default is 4MB. If
- you wish to get a high BYTES hit ratio, you should probably
+ The default limit on size of objects stored to disk.
+ This size is used for cache_dir where max-size is not set.
+ 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 speed more than your want to
+ 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
TYPE: int
DEFAULT: 90
LOC: Config.Swap.lowWaterMark
-DOC_NONE
+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.
+
+ 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
+DOC_END
NAME: cache_swap_high
COMMENT: (percent, 0-100)
DEFAULT: 95
LOC: Config.Swap.highWaterMark
DOC_START
-
- The low- and high-water marks for cache object replacement.
+ 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
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
DOC_END
COMMENT_START
TYPE: logformat
LOC: Log::TheConfig
DEFAULT: none
+DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in.
DOC_START
Usage:
err_code The ID of an error response served by Squid or
a similar internal error identifier.
err_detail Additional err_code-dependent error information.
+ note The meta header specified by the argument. Also
+ logs the adaptation meta headers set by the
+ adaptation_meta configuration parameter.
+ If no argument given all meta headers logged.
Connection related format codes:
HTTP related format codes:
- [http::]>h Original request header. Optional header name argument
- on the format header[:[separator]element]
- [http::]>ha The HTTP request headers after adaptation and redirection.
+ [http::]>h Original received request header.
+ Usually differs from the request header sent by
+ Squid, although most fields are often preserved.
+ Accepts optional header field name/value filter
+ argument using name[:[separator]element] format.
+ [http::]>ha Received request header after adaptation and
+ redirection (pre-cache REQMOD vectoring point).
+ Usually differs from the request header sent by
+ Squid, although most fields are often preserved.
Optional header name argument as for >h
[http::]<h Reply header. Optional header name argument
as for >h
Ss Squid request status (TCP_MISS etc)
Sh Squid hierarchy status (DEFAULT_PARENT etc)
+ SSL-related format codes:
+
+ ssl::bump_mode SslBump decision for the transaction:
+
+ For CONNECT requests that initiated bumping of
+ a connection and for any request received on
+ an already bumped connection, Squid logs the
+ corresponding SslBump mode ("server-first" or
+ "client-first"). See the ssl_bump option for
+ more information about these modes.
+
+ A "none" token is logged for requests that
+ triggered "ssl_bump" ACL evaluation matching
+ either a "none" rule or no rules at all.
+
+ In all other cases, a single dash ("-") is
+ logged.
+
If ICAP is enabled, the following code becomes available (as
well as ICAP log codes documented with the icap_log option):
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
LOC: Config.Log.accesslogs
DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid
DOC_START
- These files log client request activities. Has a line every HTTP or
- ICP request. The format is:
+ Configures whether and how Squid logs HTTP and ICP transactions.
+ 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 ...]
+ access_log none [acl acl ...]
+
+ The following directive format is accepted but may be deprecated:
access_log <module>:<place> [<logformat name> [acl acl ...]]
- access_log none [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
+ defined by a logformat directive). Defaults
+ to 'squid'.
+
+ buffer-size=64KB Defines approximate buffering limit for log
+ records (see buffered_logs). Squid should not
+ keep more than the specified size and, hence,
+ should flush records before the buffer becomes
+ full to avoid overflows under normal
+ conditions (the exact flushing algorithm is
+ module-dependent though). The on-error option
+ controls overflow handling.
+
+ 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
+ support has not been tested for modules other
+ than tcp.
+
===== Modules Currently available =====
none Do not log any requests matching these ACL.
Place Format: //host:port
tcp To send each log line as text data to a TCP receiver.
+ Lines may be accumulated before sending (see buffered_logs).
Place: The destination host name or IP and port.
Place Format: //host:port
TYPE: acl_access
LOC: Config.accessList.log
DEFAULT: none
+DEFAULT_DOC: Allow logging for all transactions.
COMMENT: allow|deny acl acl...
DOC_START
This options allows you to control which requests gets logged
IFDEF: ICAP_CLIENT
LOC: Config.accessList.icap
DEFAULT: none
+DEFAULT_DOC: Allow logging for all ICAP transactions.
DOC_START
This options allows you to control which requests get logged
to icap.log. See the icap_log directive for ICAP log details.
DOC_START
Logs the activities of the storage manager. Shows which
objects are ejected from the cache, and which objects are
- saved and for how long. To disable, enter "none" or remove the line.
+ saved and for how long.
There are not really utilities to analyze this data, so you can safely
- disable it.
-
+ disable it (the default).
+
+ Store log uses modular logging outputs. See access_log for the list
+ of modules supported.
+
Example:
- cache_store_log @DEFAULT_STORE_LOG@
+ cache_store_log stdio:@DEFAULT_STORE_LOG@
+ cache_store_log daemon:@DEFAULT_STORE_LOG@
DOC_END
NAME: cache_swap_state cache_swap_log
TYPE: string
LOC: Config.Log.swap
DEFAULT: none
+DEFAULT_DOC: Store the journal inside its cache_dir
DOC_START
Location for the cache "swap.state" file. This index file holds
the metadata of objects saved on disk. It is used to rebuild
in the habit of using 'squid -k rotate' instead of 'kill -USR1
<pid>'.
- Note, from Squid-3.1 this option has no effect on the cache.log,
- that log can be rotated separately by using debug_options
+ Note, from Squid-3.1 this option is only a default for cache.log,
+ that log can be rotated separately by using debug_options.
DOC_END
NAME: emulate_httpd_log
DEFAULT: @DEFAULT_MIME_TABLE@
LOC: Config.mimeTablePathname
DOC_START
- Pathname to Squid's MIME table. You shouldn't need to change
- this, but the default file contains examples and formatting
- information if you do.
+ Path to Squid's icon configuration file.
+
+ You shouldn't need to change this, but the default file contains
+ examples and formatting information if you do.
DOC_END
NAME: log_mime_hdrs
TYPE: address
LOC: Config.Addrs.client_netmask
DEFAULT: no_addr
+DEFAULT_DOC: Log full client IP address
DOC_START
A netmask for client addresses in logfiles and cachemgr output.
Change this to protect the privacy of your cache clients.
DEFAULT: on
DOC_START
By default, Squid strips query terms from requested URLs before
- logging. This protects your user's privacy.
+ logging. This protects your user's privacy and reduces log size.
+
+ When investigating HIT/MISS or other caching behaviour you
+ will need to disable this to see the full URL used by Squid.
DOC_END
NAME: buffered_logs
DEFAULT: off
LOC: Config.onoff.buffered_logs
DOC_START
- cache.log log file is written with stdio functions, and as such
- it can be buffered or unbuffered. By default it will be unbuffered.
- Buffering it can speed up the writing slightly (though you are
- unlikely to need to worry unless you run with tons of debugging
- enabled in which case performance will suffer badly anyway..).
+ Whether to write/send access_log records ASAP or accumulate them and
+ then write/send them in larger chunks. Buffering may improve
+ performance because it decreases the number of I/Os. However,
+ buffering increases the delay before log records become available to
+ the final recipient (e.g., a disk file or logging daemon) and,
+ hence, increases the risk of log records loss.
+
+ Note that even when buffered_logs are off, Squid may have to buffer
+ records if it cannot write/send them immediately due to pending I/Os
+ (e.g., the I/O writing the previous log record) or connectivity loss.
+
+ Currently honored by 'daemon' and 'tcp' access_log modules only.
DOC_END
NAME: netdb_filename
LOC: Config.netdbFilename
IFDEF: USE_ICMP
DOC_START
- A filename where Squid stores it's netdb state between restarts.
+ Where Squid stores it's netdb journal.
+ When enabled this journal preserves netdb state between restarts.
+
To disable, enter "none".
DOC_END
DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@
LOC: Debug::cache_log
DOC_START
- Cache logging file. This is where general information about
- your cache's behavior goes. You can increase the amount of data
- logged to this file and how often its rotated with "debug_options"
+ Squid administrative logging file.
+
+ This is where general information about Squid behavior goes. You can
+ increase the amount of data logged to this file and how often it is
+ rotated with "debug_options"
DOC_END
NAME: debug_options
TYPE: eol
DEFAULT: ALL,1
+DEFAULT_DOC: Log all critical and important messages.
LOC: Debug::debugOptions
DOC_START
Logging options are set as section,level where each source file
log file, so be careful.
The magic word "ALL" sets debugging levels for all sections.
- We recommend normally running with "ALL,1".
+ The default is to run with "ALL,1" to record important warnings.
The rotate=N option can be used to keep more or less of these logs
than would otherwise be kept by logfile_rotate.
TYPE: string
LOC: Config.coredump_dir
DEFAULT_IF_NONE: none
+DEFAULT_DOC: Use the directory from where Squid was started.
DOC_START
By default Squid leaves core files in the directory from where
it was started. If you set 'coredump_dir' to a directory
LOC: Config.Ftp.anon_user
DOC_START
If you want the anonymous login password to be more informative
- (and enable the use of picky ftp servers), set this to something
+ (and enable the use of picky FTP servers), set this to something
reasonable for your domain, like wwwuser@somewhere.net
The reason why this is domainless by default is the
request can be made on the behalf of a user in any domain,
depending on how the cache is used.
- Some ftp server also validate the email address is valid
+ Some FTP server also validate the email address is valid
(for example perl.com).
DOC_END
For each requested URL, the rewriter will receive on line with the format
- URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
+ [channel-ID <SP>] URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kv-pairs]<NL>
+
+
+ After processing the request the helper must reply using the following format:
+
+ [channel-ID <SP>] result [<SP> kv-pairs]
+
+ The result code can be:
+
+ OK status=30N url="..."
+ Redirect the URL to the one supplied in 'url='.
+ 'status=' is optional and contains the status code to send
+ the client in Squids HTTP response. It must be one of the
+ HTTP redirect status codes: 301, 302, 303, 307, 308.
+ When no status is given Squid will use 302.
+
+ OK rewrite-url="..."
+ Rewrite the URL to the one supplied in 'rewrite-url='.
+ The new URL is fetched directly by Squid and returned to
+ the client as the response to its request.
+
+ ERR
+ Do not change the URL.
+
+ BH
+ An internal error occurred in the helper, preventing
+ a result being identified.
+
- In the future, the rewriter interface will be extended with
- key=value pairs ("kvpairs" shown above). Rewriter programs
+ In the future, the interface protocol will be extended with
+ key=value pairs ("kv-pairs" shown above). Helper programs
should be prepared to receive and possibly ignore additional
whitespace-separated tokens on each input line.
- And the rewriter may return a rewritten URL. The other components of
- the request line does not need to be returned (ignored if they are).
+ When using the concurrency= option the protocol is changed by
+ introducing a query channel tag in front of the request/response.
+ The query channel tag is a number between 0 and concurrency-1.
+ This value must be echoed back unchanged to Squid as the first part
+ of the response relating to its request.
- The rewriter can also indicate that a client-side redirect should
- be performed to the new URL. This is done by prefixing the returned
- URL with "301:" (moved permanently) or 302: (moved temporarily), etc.
+ WARNING: URL re-writing ability should be avoided whenever possible.
+ Use the URL redirect form of response instead.
+
+ Re-write creates a difference in the state held by the client
+ and server. Possibly causing confusion when the server response
+ contains snippets of its view state. Embeded URLs, response
+ and content Location headers, etc. are not re-written by this
+ interface.
By default, a URL rewriter is not used.
DOC_END
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
- ID from the request must be echoed back with the response
- to that request.
+ an ID in front of the request/response. The ID from the request
+ must be echoed back with the response to that request.
DOC_END
NAME: url_rewrite_host_header redirect_rewrites_host_header
NAME: url_rewrite_access redirector_access
TYPE: acl_access
DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
LOC: Config.accessList.redirector
DOC_START
If defined, this access list specifies which requests are
- sent to the redirector processes. By default all requests
- are sent.
+ sent to the redirector processes.
This clause supports both fast and slow acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DEFAULT: off
DOC_START
When this is 'on', a request will not go through the
- redirector if all redirectors are busy. If this is 'off'
+ redirector if all the helpers are busy. If this is 'off'
and the redirector queue grows too large, Squid will exit
with a FATAL error and ask you to increase the number of
redirectors. You should only enable this if the redirectors
be allowed to request.
DOC_END
+COMMENT_START
+ OPTIONS FOR STORE ID
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: store_id_program storeurl_rewrite_program
+TYPE: wordlist
+LOC: Config.Program.store_id
+DEFAULT: none
+DOC_START
+ Specify the location of the executable StoreID helper to use.
+ Since they can perform almost any function there isn't one included.
+
+ For each requested URL, the helper will receive one line with the format
+
+ [channel-ID <SP>] URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kv-pairs]<NL>
+
+
+ After processing the request the helper must reply using the following format:
+
+ [channel-ID <SP>] result [<SP> kv-pairs]
+
+ The result code can be:
+
+ OK store-id="..."
+ Use the StoreID supplied in 'store-id='.
+
+ ERR
+ The default is to use HTTP request URL as the store ID.
+
+ BH
+ An internal error occured in the helper, preventing
+ a result being identified.
+
+
+ Helper programs should be prepared to receive and possibly ignore additional
+ kv-pairs with keys they do not support.
+
+ When using the concurrency= option the protocol is changed by
+ introducing a query channel tag in front of the request/response.
+ The query channel tag is a number between 0 and concurrency-1.
+ This value must be echoed back unchanged to Squid as the first part
+ of the response relating to its request.
+
+ NOTE: when using StoreID refresh_pattern will apply to the StoreID
+ returned from the helper and not the URL.
+
+ WARNING: Wrong StoreID value returned by a careless helper may result
+ in the wrong cached response returned to the user.
+
+ By default, a StoreID helper is not used.
+DOC_END
+
+NAME: store_id_children storeurl_rewrite_children
+TYPE: HelperChildConfig
+DEFAULT: 20 startup=0 idle=1 concurrency=0
+LOC: Config.storeIdChildren
+DOC_START
+ The maximum number of StoreID helper processes to spawn. If you limit
+ it too few Squid will have to wait for them to process a backlog of
+ requests, slowing it down. If you allow too many they will use RAM
+ and other system resources noticably.
+
+ 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
+ configured. A minimum setting of 1 is required.
+
+ concurrency=
+
+ The number of requests each storeID helper can handle in
+ parallel. Defaults to 0 which indicates the helper
+ is a old-style single threaded program.
+
+ When this directive is set to a value >= 1 then the protocol
+ used to communicate with the helper is modified to include
+ an ID in front of the request/response. The ID from the request
+ must be echoed back with the response to that request.
+DOC_END
+
+NAME: store_id_access storeurl_rewrite_access
+TYPE: acl_access
+DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
+LOC: Config.accessList.store_id
+DOC_START
+ If defined, this access list specifies which requests are
+ sent to the StoreID processes. By default all requests
+ are sent.
+
+ This clause supports both fast and slow acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+DOC_END
+
+NAME: store_id_bypass storeurl_rewrite_bypass
+TYPE: onoff
+LOC: Config.onoff.store_id_bypass
+DEFAULT: on
+DOC_START
+ When this is 'on', a request will not go through the
+ helper if all helpers are busy. If this is 'off'
+ and the helper queue grows too large, Squid will exit
+ with a FATAL error and ask you to increase the number of
+ helpers. You should only enable this if the helperss
+ are not critical to your caching system. If you use
+ helpers for critical caching components, and you enable this
+ option, users may not get objects from cache.
+DOC_END
+
COMMENT_START
OPTIONS FOR TUNING THE CACHE
-----------------------------------------------------------------------------
NAME: cache no_cache
TYPE: acl_access
DEFAULT: none
+DEFAULT_DOC: Allow caching, unless rules exist in squid.conf.
LOC: Config.accessList.noCache
DOC_START
A list of ACL elements which, if matched and denied, cause the request to
You must use the words 'allow' or 'deny' to indicate whether items
matching the ACL should be allowed or denied into the cache.
- Default is to allow all to be cached.
-
This clause supports both fast and slow acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
DOC_END
override-lastmod
reload-into-ims
ignore-reload
- ignore-no-cache
ignore-no-store
ignore-must-revalidate
ignore-private
this feature could make you liable for problems which
it causes.
- ignore-no-cache ignores any ``Pragma: no-cache'' and
- ``Cache-control: no-cache'' headers received from a server.
- The HTTP RFC never allows the use of this (Pragma) header
- from a server, only a client, though plenty of servers
- send it anyway.
-
ignore-no-store ignores any ``Cache-control: no-store''
headers received from a server. Doing this VIOLATES
the HTTP standard. Enabling this feature could make you
NOCOMMENT_START
+#
# Add any of your own refresh_pattern entries above these.
+#
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
DEFAULT: 60 seconds
DOC_START
The minimum caching time according to (Expires - Date)
- Headers Squid honors if the object can't be revalidated
- defaults to 60 seconds. In reverse proxy environments it
- might be desirable to honor shorter object lifetimes. It
- is most likely better to make your server return a
- meaningful Last-Modified header however. In ESI environments
- where page fragments often have short lifetimes, this will
- often be best set to 0.
+ headers Squid honors if the object can't be revalidated.
+ The default is 60 seconds.
+
+ In reverse proxy environments it might be desirable to honor
+ shorter object lifetimes. It is most likely better to make
+ your server return a meaningful Last-Modified header however.
+
+ In ESI environments where page fragments often have short
+ lifetimes, this will often be best set to 0.
DOC_END
NAME: store_avg_object_size
DOC_START
Average object size, used to estimate number of objects your
cache can hold. The default is 13 KB.
+
+ This is used to pre-seed the cache index memory allocation to
+ reduce expensive reallocate operations while handling clients
+ traffic. Too-large values may result in memory allocation during
+ peak traffic, too-small values will result in wasted memory.
+
+ Check the cache manager 'info' report metrics for the real
+ object sizes seen by your Squid before tuning this.
DOC_END
NAME: store_objects_per_bucket
COMMENT: (bytes)
TYPE: b_int64_t
DEFAULT: 0 KB
+DEFAULT_DOC: No limit.
LOC: Config.maxRequestBodySize
DOC_START
This specifies the maximum size for an HTTP request body.
than this limit receives an "Invalid Request" error message.
If you set this parameter to a zero (the default), there will
be no limit imposed.
+
+ See also client_request_buffer_max_size for an alternative
+ limitation on client uploads which can be configured.
DOC_END
NAME: client_request_buffer_max_size
IFDEF: USE_HTTP_VIOLATIONS
TYPE: acl_access
DEFAULT: none
+DEFAULT_DOC: Obey RFC 2616.
LOC: Config.accessList.brokenPosts
DOC_START
A list of ACL elements which, if matched, causes Squid to send
NAME: request_header_access
IFDEF: USE_HTTP_VIOLATIONS
-TYPE: http_header_access[]
+TYPE: http_header_access
LOC: Config.request_header_access
DEFAULT: none
+DEFAULT_DOC: No limits.
DOC_START
Usage: request_header_access header_name allow|deny [!]aclname ...
This option replaces the old 'anonymize_headers' and the
older 'http_anonymizer' option with something that is much
- more configurable. This new method creates a list of ACLs
- for each header, allowing you very fine-tuned header
- mangling.
-
- This option only applies to request headers, i.e., from the
- client to the server.
-
- You can only specify known headers for the header name.
- Other headers are reclassified as 'Other'. You can also
- refer to all the headers with 'All'.
+ more configurable. A list of ACLs for each header name allows
+ removal of specific header fields under specific conditions.
+
+ This option only applies to outgoing HTTP request headers (i.e.,
+ headers sent by Squid to the next HTTP hop such as a cache peer
+ or an origin server). The option has no effect during cache hit
+ detection. The equivalent adaptation vectoring point in ICAP
+ terminology is post-cache REQMOD.
+
+ The option is applied to individual outgoing request header
+ fields. For each request header field F, Squid uses the first
+ qualifying sets of request_header_access rules:
+
+ 1. Rules with header_name equal to F's name.
+ 2. Rules with header_name 'Other', provided F's name is not
+ on the hard-coded list of commonly used HTTP header names.
+ 3. Rules with header_name 'All'.
+
+ Within that qualifying rule set, rule ACLs are checked as usual.
+ If ACLs of an "allow" rule match, the header field is allowed to
+ go through as is. If ACLs of a "deny" rule match, the header is
+ removed and request_header_replace is then checked to identify
+ if the removed header has a replacement. If no rules within the
+ set have matching ACLs, the header field is left as is.
For example, to achieve the same behavior as the old
'http_anonymizer standard' option, you should use:
request_header_access From deny all
request_header_access Referer deny all
- request_header_access Server deny all
request_header_access User-Agent deny all
- request_header_access WWW-Authenticate deny all
- request_header_access Link deny all
Or, to reproduce the old 'http_anonymizer paranoid' feature
you should use:
- request_header_access Allow allow all
request_header_access Authorization allow all
- request_header_access WWW-Authenticate allow all
request_header_access Proxy-Authorization allow all
- request_header_access Proxy-Authenticate allow all
request_header_access Cache-Control allow all
- request_header_access Content-Encoding allow all
request_header_access Content-Length allow all
request_header_access Content-Type allow all
request_header_access Date allow all
- request_header_access Expires allow all
request_header_access Host allow all
request_header_access If-Modified-Since allow all
- request_header_access Last-Modified allow all
- request_header_access Location allow all
request_header_access Pragma allow all
request_header_access Accept allow all
request_header_access Accept-Charset allow all
request_header_access Accept-Encoding allow all
request_header_access Accept-Language allow all
- request_header_access Content-Language allow all
- request_header_access Mime-Version allow all
- request_header_access Retry-After allow all
- request_header_access Title allow all
request_header_access Connection allow all
request_header_access All deny all
- although many of those are HTTP reply headers, and so should be
- controlled with the reply_header_access directive.
+ HTTP reply headers are controlled with the reply_header_access directive.
- By default, all headers are allowed (no anonymizing is
- performed).
+ By default, all headers are allowed (no anonymizing is performed).
DOC_END
NAME: reply_header_access
IFDEF: USE_HTTP_VIOLATIONS
-TYPE: http_header_access[]
+TYPE: http_header_access
LOC: Config.reply_header_access
DEFAULT: none
+DEFAULT_DOC: No limits.
DOC_START
Usage: reply_header_access header_name allow|deny [!]aclname ...
server to the client.
This is the same as request_header_access, but in the other
- direction.
-
- This option replaces the old 'anonymize_headers' and the
- older 'http_anonymizer' option with something that is much
- more configurable. This new method creates a list of ACLs
- for each header, allowing you very fine-tuned header
- mangling.
-
- You can only specify known headers for the header name.
- Other headers are reclassified as 'Other'. You can also
- refer to all the headers with 'All'.
+ direction. Please see request_header_access for detailed
+ documentation.
For example, to achieve the same behavior as the old
'http_anonymizer standard' option, you should use:
- reply_header_access From deny all
- reply_header_access Referer deny all
reply_header_access Server deny all
- reply_header_access User-Agent deny all
reply_header_access WWW-Authenticate deny all
reply_header_access Link deny all
you should use:
reply_header_access Allow allow all
- reply_header_access Authorization allow all
reply_header_access WWW-Authenticate allow all
- reply_header_access Proxy-Authorization allow all
reply_header_access Proxy-Authenticate allow all
reply_header_access Cache-Control allow all
reply_header_access Content-Encoding allow all
reply_header_access Content-Type allow all
reply_header_access Date allow all
reply_header_access Expires allow all
- reply_header_access Host allow all
- reply_header_access If-Modified-Since allow all
reply_header_access Last-Modified allow all
reply_header_access Location allow all
reply_header_access Pragma allow all
- reply_header_access Accept allow all
- reply_header_access Accept-Charset allow all
- reply_header_access Accept-Encoding allow all
- reply_header_access Accept-Language allow all
reply_header_access Content-Language allow all
- reply_header_access Mime-Version allow all
reply_header_access Retry-After allow all
reply_header_access Title allow all
+ reply_header_access Content-Disposition allow all
reply_header_access Connection allow all
reply_header_access All deny all
- although the HTTP request headers won't be usefully controlled
- by this directive -- see request_header_access for details.
+ HTTP request headers are controlled with the request_header_access directive.
By default, all headers are allowed (no anonymizing is
performed).
NAME: request_header_replace header_replace
IFDEF: USE_HTTP_VIOLATIONS
-TYPE: http_header_replace[]
+TYPE: http_header_replace
LOC: Config.request_header_access
DEFAULT: none
DOC_START
This option allows you to change the contents of headers
denied with request_header_access above, by replacing them
- with some fixed string. This replaces the old fake_user_agent
- option.
+ with some fixed string.
This only applies to request headers, not reply headers.
NAME: reply_header_replace
IFDEF: USE_HTTP_VIOLATIONS
-TYPE: http_header_replace[]
+TYPE: http_header_replace
LOC: Config.reply_header_access
DEFAULT: none
DOC_START
By default, headers are removed if denied.
DOC_END
+NAME: request_header_add
+TYPE: HeaderWithAclList
+LOC: Config.request_header_add
+DEFAULT: none
+DOC_START
+ Usage: request_header_add field-name field-value acl1 [acl2] ...
+ Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all
+
+ This option adds header fields to outgoing HTTP requests (i.e.,
+ request headers sent by Squid to the next HTTP hop such as a
+ cache peer or an origin server). The option has no effect during
+ cache hit detection. The equivalent adaptation vectoring point
+ in ICAP terminology is post-cache REQMOD.
+
+ Field-name is a token specifying an HTTP header name. If a
+ standard HTTP header name is used, Squid does not check whether
+ the new header conflicts with any existing headers or violates
+ HTTP rules. If the request to be modified already contains a
+ field with the same name, the old field is preserved but the
+ header field values are not merged.
+
+ Field-value is either a token or a quoted string. If quoted
+ string format is used, then the surrounding quotes are removed
+ while escape sequences and %macros are processed.
+
+ In theory, all of the logformat codes can be used as %macros.
+ However, unlike logging (which happens at the very end of
+ transaction lifetime), the transaction may not yet have enough
+ information to expand a macro when the new header value is needed.
+ And some information may already be available to Squid but not yet
+ committed where the macro expansion code can access it (report
+ such instances!). The macro will be expanded into a single dash
+ ('-') in such cases. Not all macros have been tested.
+
+ One or more Squid ACLs may be specified to restrict header
+ injection to matching requests. As always in squid.conf, all
+ ACLs in an option ACL list must be satisfied for the insertion
+ to happen. The request_header_add option supports fast ACLs
+ only.
+DOC_END
+
+NAME: note
+TYPE: note
+LOC: Config.notes
+DEFAULT: none
+DOC_START
+ This option used to log custom information about the master
+ transaction. For example, an admin may configure Squid to log
+ which "user group" the transaction belongs to, where "user group"
+ will be determined based on a set of ACLs and not [just]
+ authentication information.
+ Values of key/value pairs can be logged using %{key}note macros:
+
+ note key value acl ...
+ logformat myFormat ... %{key}note ...
+DOC_END
+
NAME: relaxed_header_parser
COMMENT: on|off|warn
TYPE: tristate
LOC: Config.adminEmail
DOC_START
Email-address of local cache manager who will receive
- mail if the cache dies. The default is "webmaster."
+ mail if the cache dies. The default is "webmaster".
DOC_END
NAME: mail_from
LOC: Config.EmailFrom
DOC_START
From: email-address for mail sent when the cache dies.
- The default is to use 'appname@unique_hostname'.
- Default appname value is "squid", can be changed into
- src/globals.h before building squid.
+ The default is to use 'squid@unique_hostname'.
+
+ See also: unique_hostname directive.
DOC_END
NAME: mail_program
NAME: cache_effective_group
TYPE: string
DEFAULT: none
+DEFAULT_DOC: Use system group memberships of the cache_effective_user account
LOC: Config.effectiveGroup
DOC_START
Squid sets the GID to the effective user's default group ID
TYPE: string
LOC: Config.visibleHostname
DEFAULT: none
+DEFAULT_DOC: Automatically detect the system host name
DOC_START
If you want to present a special hostname in error messages, etc,
define this. Otherwise, the return value of gethostname()
TYPE: string
LOC: Config.uniqueHostname
DEFAULT: none
+DEFAULT_DOC: Copy the value from visible_hostname
DOC_START
If you want to have multiple machines with the same
'visible_hostname' you must give each machine a different
TYPE: time_t
LOC: Config.Announce.period
DEFAULT: 0
+DEFAULT_DOC: Announcement messages disabled.
DOC_START
- This is how frequently to send cache announcements. The
- default is `0' which disables sending the announcement
- messages.
+ This is how frequently to send cache announcements.
To enable announcing your cache, just set an announce period.
TYPE: string
DEFAULT: tracker.ircache.net
LOC: Config.Announce.host
-DOC_NONE
+DOC_START
+ Set the hostname where announce registration messages will be sent.
+
+ See also announce_port and announce_file
+DOC_END
NAME: announce_file
TYPE: string
DEFAULT: none
LOC: Config.Announce.file
-DOC_NONE
+DOC_START
+ The contents of this file will be included in the announce
+ registration messages.
+DOC_END
NAME: announce_port
TYPE: u_short
DEFAULT: 3131
LOC: Config.Announce.port
DOC_START
- announce_host and announce_port set the hostname and port
- number where the registration message will be sent.
+ Set the port where announce registration messages will be sent.
- Hostname will default to 'tracker.ircache.net' and port will
- default default to 3131. If the 'filename' argument is given,
- the contents of that file will be included in the announce
- message.
+ See also announce_host and announce_file
DOC_END
COMMENT_START
NAME: httpd_accel_surrogate_id
TYPE: string
DEFAULT: none
+DEFAULT_DOC: visible_hostname is used if no specific ID is set.
LOC: Config.Accel.surrogate_id
DOC_START
Surrogates (http://www.esi.org/architecture_spec_1.0.html)
need an identification token to allow control targeting. Because
a farm of surrogates may all perform the same tasks, they may share
an identification token.
-
- The default ID is the visible_hostname
DOC_END
NAME: http_accel_surrogate_remote
DEFAULT: off
LOC: Config.onoff.surrogate_is_remote
DOC_START
- Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote.
+ Remote surrogates (such as those in a CDN) honour the header
+ "Surrogate-Control: no-store-remote".
+
Set this to on to have squid behave as a remote surrogate.
DOC_END
This represents the number of delay pools to be used. For example,
if you have one class 2 delay pool and one class 3 delays pool, you
have a total of 2 delay pools.
+
+ See also delay_parameters, delay_class, delay_access for pool
+ configuration details.
DOC_END
NAME: delay_class
NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to
IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic.
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
+ See also delay_parameters and delay_access.
DOC_END
NAME: delay_access
TYPE: delay_pool_access
DEFAULT: none
+DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool.
IFDEF: USE_DELAY_POOLS
LOC: Config.Delay
DOC_START
For example, if you want some_big_clients in delay
pool 1 and lotsa_little_clients in delay pool 2:
-Example:
- delay_access 1 allow some_big_clients
- delay_access 1 deny all
- delay_access 2 allow lotsa_little_clients
- delay_access 2 deny all
- delay_access 3 allow authenticated_clients
+ delay_access 1 allow some_big_clients
+ delay_access 1 deny all
+ delay_access 2 allow lotsa_little_clients
+ delay_access 2 deny all
+ delay_access 3 allow authenticated_clients
+
+ See also delay_parameters and delay_class.
+
DOC_END
NAME: delay_parameters
be limited to 128Kbits/sec no matter how many workstations they are logged into.:
delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
+
+
+ See also delay_class and delay_access.
+
DOC_END
NAME: delay_initial_bucket_level
This option specifies the number of client delay pools used. It must
preceed other client_delay_* options.
-Example:
- client_delay_pools 2
+ Example:
+ client_delay_pools 2
+
+ See also client_delay_parameters and client_delay_access.
DOC_END
NAME: client_delay_initial_bucket_level
buckets are not refilled until their size goes down to max_bucket_size
from client_delay_parameters.
-Example:
- client_delay_initial_bucket_level 50
+ Example:
+ client_delay_initial_bucket_level 50
DOC_END
NAME: client_delay_parameters
Please see the delay_parameters option for more information and
examples.
-Example:
- client_delay_parameters 1 1024 2048
- client_delay_parameters 2 51200 16384
+ Example:
+ client_delay_parameters 1 1024 2048
+ client_delay_parameters 2 51200 16384
+
+ See also client_delay_access.
+
DOC_END
NAME: client_delay_access
TYPE: client_delay_pool_access
DEFAULT: none
+DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool.
IFDEF: USE_DELAY_POOLS
LOC: Config.ClientDelay
DOC_START
-
This option determines the client-side delay pool for the
request:
not used to aggregate clients. Clients are always aggregated
based on their source IP addresses (one bucket per source IP).
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+ Additionally, only the client TCP connection details are available.
+ ACLs testing HTTP properties will not work.
+
Please see delay_access for more examples.
-Example:
- client_delay_access 1 allow low_rate_network
- client_delay_access 2 allow vips_network
+ Example:
+ client_delay_access 1 allow low_rate_network
+ client_delay_access 2 allow vips_network
+
+
+ See also client_delay_parameters and client_delay_pools.
DOC_END
COMMENT_START
TYPE: address
LOC: Config.Wccp.router
DEFAULT: any_addr
+DEFAULT_DOC: WCCP disabled.
IFDEF: USE_WCCP
DOC_START
Use this option to define your WCCP ``home'' router for
TYPE: IpAddress_list
LOC: Config.Wccp2.router
DEFAULT: none
+DEFAULT_DOC: WCCPv2 disabled.
IFDEF: USE_WCCPv2
DOC_START
Use this option to define your WCCP ``home'' router for
TYPE: wccp2_service
LOC: Config.Wccp2.info
DEFAULT_IF_NONE: standard 0
+DEFAULT_DOC: Use the 'web-cache' standard service.
IFDEF: USE_WCCPv2
DOC_START
WCCP2 allows for multiple traffic services. There are two
TYPE: address
LOC: Config.Wccp.address
DEFAULT: 0.0.0.0
+DEFAULT_DOC: Address selected by the operating system.
IFDEF: USE_WCCP
-DOC_NONE
+DOC_START
+ Use this option if you require WCCPv2 to use a specific
+ interface address.
+
+ The default behavior is to not bind to any specific address.
+DOC_END
NAME: wccp2_address
TYPE: address
LOC: Config.Wccp2.address
DEFAULT: 0.0.0.0
+DEFAULT_DOC: Address selected by the operating system.
IFDEF: USE_WCCPv2
DOC_START
Use this option if you require WCCP to use a specific
TYPE: onoff
LOC: Config.onoff.client_pconns
DEFAULT: on
-DOC_NONE
+DOC_START
+ Persistent connection support for clients.
+ Squid uses persistent connections (when allowed). You can use
+ this option to disable persistent connections with clients.
+DOC_END
NAME: server_persistent_connections
TYPE: onoff
LOC: Config.onoff.server_pconns
DEFAULT: on
DOC_START
- Persistent connection support for clients and servers. By
- default, Squid uses persistent connections (when allowed)
- with its clients and servers. You can use these options to
- disable persistent connections with clients and/or servers.
+ Persistent connection support for servers.
+ Squid uses persistent connections (when allowed). You can use
+ this option to disable persistent connections with servers.
DOC_END
NAME: persistent_connection_after_error
TYPE: u_short
LOC: Config.Port.snmp
DEFAULT: 0
+DEFAULT_DOC: SNMP disabled.
IFDEF: SQUID_SNMP
DOC_START
The port number where Squid listens for SNMP requests. To enable
NAME: snmp_access
TYPE: acl_access
LOC: Config.accessList.snmp
-DEFAULT_IF_NONE: deny all
+DEFAULT: none
+DEFAULT_DOC: Deny, unless rules exist in squid.conf.
IFDEF: SQUID_SNMP
DOC_START
Allowing or denying access to the SNMP port.
This clause only supports fast acl types.
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
Example:
snmp_access allow snmppublic localhost
snmp_access deny all
TYPE: address
LOC: Config.Addrs.snmp_incoming
DEFAULT: any_addr
+DEFAULT_DOC: Accept SNMP packets from all machine interfaces.
IFDEF: SQUID_SNMP
-DOC_NONE
+DOC_START
+ Just like 'udp_incoming_address', but for the SNMP port.
+
+ snmp_incoming_address is used for the SNMP socket receiving
+ messages from SNMP agents.
+
+ The default snmp_incoming_address is to listen on all
+ available network interfaces.
+DOC_END
NAME: snmp_outgoing_address
TYPE: address
LOC: Config.Addrs.snmp_outgoing
DEFAULT: no_addr
+DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system.
IFDEF: SQUID_SNMP
DOC_START
- Just like 'udp_incoming_address', but for the SNMP port.
+ Just like 'udp_outgoing_address', but for the SNMP port.
- snmp_incoming_address is used for the SNMP socket receiving
- messages from SNMP agents.
snmp_outgoing_address is used for SNMP packets returned to SNMP
agents.
- The default snmp_incoming_address is to listen on all
- available network interfaces.
-
If snmp_outgoing_address is not set it will use the same socket
as snmp_incoming_address. Only change this if you want to have
SNMP replies sent using another address than where this Squid
listens for SNMP queries.
NOTE, snmp_incoming_address and snmp_outgoing_address can not have
- the same value since they both use port 3401.
+ the same value since they both use the same port.
DOC_END
COMMENT_START
NAME: icp_port udp_port
TYPE: u_short
DEFAULT: 0
+DEFAULT_DOC: ICP disabled.
LOC: Config.Port.icp
DOC_START
The port number where Squid sends and receives ICP queries to
and from neighbor caches. The standard UDP port for ICP is 3130.
- Default is disabled (0).
Example:
icp_port @DEFAULT_ICP_PORT@
IFDEF: USE_HTCP
TYPE: u_short
DEFAULT: 0
+DEFAULT_DOC: HTCP disabled.
LOC: Config.Port.htcp
DOC_START
The port number where Squid sends and receives HTCP queries to
and from neighbor caches. To turn it on you want to set it to
- 4827. By default it is set to "0" (disabled).
+ 4827.
Example:
htcp_port 4827
TYPE: address
LOC:Config.Addrs.udp_incoming
DEFAULT: any_addr
+DEFAULT_DOC: Accept packets from all machine interfaces.
DOC_START
udp_incoming_address is used for UDP packets received from other
caches.
TYPE: address
LOC: Config.Addrs.udp_outgoing
DEFAULT: no_addr
+DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system.
DOC_START
udp_outgoing_address is used for UDP packets sent out to other
caches.
DOC_END
NAME: minimum_direct_rtt
+COMMENT: (msec)
TYPE: int
DEFAULT: 400
LOC: Config.minDirectRtt
TYPE: int
DEFAULT: 900
LOC: Config.Netdb.low
-DOC_NONE
+DOC_START
+ The low water mark for the ICMP measurement database.
+
+ Note: high watermark controlled by netdb_high directive.
+
+ These watermarks are counts, not percents. The defaults are
+ (low) 900 and (high) 1000. When the high water mark is
+ reached, database entries will be deleted until the low
+ mark is reached.
+DOC_END
NAME: netdb_high
TYPE: int
DEFAULT: 1000
LOC: Config.Netdb.high
DOC_START
- The low and high water marks for the ICMP measurement
- database. These are counts, not percents. The defaults are
- 900 and 1000. When the high water mark is reached, database
- entries will be deleted until the low mark is reached.
+ The high water mark for the ICMP measurement database.
+
+ Note: low watermark controlled by netdb_low directive.
+
+ These watermarks are counts, not percents. The defaults are
+ (low) 900 and (high) 1000. When the high water mark is
+ reached, database entries will be deleted until the low
+ mark is reached.
DOC_END
NAME: netdb_ping_period
NAME: icp_query_timeout
COMMENT: (msec)
DEFAULT: 0
+DEFAULT_DOC: Dynamic detection.
TYPE: int
LOC: Config.Timeout.icp_query
DOC_START
TYPE: address
LOC: Config.mcast_miss.addr
DEFAULT: no_addr
+DEFAULT_DOC: disabled.
DOC_START
If you enable this option, every "cache miss" URL will
be sent out on the specified multicast address.
TYPE: string
LOC: Config.errorDirectory
DEFAULT: none
+DEFAULT_DOC: Send error pages in the clients preferred language
DOC_START
If you wish to create your own versions of the default
error files to customize them to suit your company copy
TYPE: string
LOC: Config.errorDefaultLanguage
DEFAULT: none
+DEFAULT_DOC: Generate English language pages.
DOC_START
Set the default language which squid will send error pages in
if no existing translation matches the clients language
(matching hierarchy_stoplist or not cacheable request type) direct
to origin servers.
- If you set this to off, Squid will prefer to send these
+ When this is set to "off", Squid will prefer to send these
requests to parents.
Note that in most configurations, by turning this off you will only
add latency to these request without any improvement in global hit
ratio.
- If you are inside an firewall see never_direct instead of
- this directive.
+ This option only sets a preference. If the parent is unavailable a
+ direct connection to the origin server may still be attempted. To
+ completely prevent direct connections use never_direct.
DOC_END
NAME: prefer_direct
TYPE: acl_access
LOC: Config.accessList.AlwaysDirect
DEFAULT: none
+DEFAULT_DOC: Prevent any cache_peer being used for this request.
DOC_START
Usage: always_direct allow|deny [!]aclname ...
TYPE: acl_access
LOC: Config.accessList.NeverDirect
DEFAULT: none
+DEFAULT_DOC: Allow DNS results to be used for this request.
DOC_START
Usage: never_direct allow|deny [!]aclname ...
TYPE: int
LOC: Config.client_ip_max_connections
DEFAULT: -1
+DEFAULT_DOC: No limit.
DOC_START
Set an absolute limit on the number of connections a single
client IP can use. Any more than this and Squid will begin to drop
COMMENT: (bytes)
TYPE: b_size_t
DEFAULT: 0 bytes
+DEFAULT_DOC: Use operating system TCP defaults.
LOC: Config.tcpRcvBufsz
DOC_START
Size of receive buffer to set for TCP sockets. Probably just
- as easy to change your kernel's default. Set to zero to use
- the default buffer size.
+ as easy to change your kernel's default.
+ Omit from squid.conf to use the default buffer size.
DOC_END
COMMENT_START
COMMENT: time-units
TYPE: time_t
DEFAULT: none
+DEFAULT_DOC: Use read_timeout.
LOC: Adaptation::Icap::TheConfig.io_timeout_raw
IFDEF: ICAP_CLIENT
DOC_START
an established, active ICAP connection before giving up and
either terminating the HTTP transaction or bypassing the
failure.
-
- The default is read_timeout.
DOC_END
NAME: icap_service_failure_limit
IFDEF: ICAP_CLIENT
LOC: Adaptation::Icap::TheConfig.preview_size
DEFAULT: -1
+DEFAULT_DOC: No preview sent.
DOC_START
The default size of preview data to be sent to the ICAP server.
- -1 means no preview. This value might be overwritten on a per server
- basis by OPTIONS requests.
+ This value might be overwritten on a per server basis by OPTIONS requests.
DOC_END
NAME: icap_206_enable
IFDEF: USE_ADAPTATION
LOC: none
DEFAULT: none
+DEFAULT_DOC: Allow, unless rules exist in squid.conf.
DOC_START
Sends an HTTP transaction to an ICAP or eCAP adaptation service.
DOC_END
NAME: adaptation_meta
-TYPE: adaptation_meta_type
+TYPE: note
IFDEF: USE_ADAPTATION
LOC: Adaptation::Config::metaHeaders
DEFAULT: none
any character, which is currently only useful for escaping backslashes
and double quotes. For example,
"this string has one backslash (\\) and two \"quotes\""
+
+ Used adaptation_meta header values may be logged via %note
+ logformat code. If multiple adaptation_meta headers with the same name
+ are used during master transaction lifetime, the header values are
+ logged in the order they were used and duplicate values are ignored
+ (only the first repeated value will be logged).
DOC_END
NAME: icap_retry
IFDEF: ICAP_CLIENT
LOC: Adaptation::Icap::TheConfig.repeat_limit
DEFAULT: 0
+DEFAULT_DOC: No retries are allowed.
DOC_START
- Limits the number of retries allowed. When set to zero (default),
- no retries are allowed.
+ Limits the number of retries allowed.
Communication errors due to persistent connection race
conditions are unavoidable, automatically retried, and do not
NAME: dns_packet_max
TYPE: b_ssize_t
+DEFAULT_DOC: EDNS disabled
DEFAULT: none
LOC: Config.dns.packet_max
IFDEF: !USE_DNSHELPER
COMMENT: on|off
TYPE: onoff
DEFAULT: off
+DEFAULT_DOC: Search for single-label domain names is disabled.
LOC: Config.onoff.res_defnames
DOC_START
Normally the RES_DEFNAMES resolver option is disabled
NAME: dns_nameservers
TYPE: wordlist
DEFAULT: none
+DEFAULT_DOC: Use operating system definitions
LOC: Config.dns_nameservers
DOC_START
Use this if you want to specify a list of DNS name servers
(IP addresses) to use instead of those given in your
/etc/resolv.conf file.
+
On Windows platforms, if no value is specified here or in
the /etc/resolv.conf file, the list of DNS name servers are
taken from the Windows registry, both static and dynamic DHCP
TYPE: string
LOC: Config.appendDomain
DEFAULT: none
+DEFAULT_DOC: Use operating system definitions
DOC_START
Appends local domain name to hostnames without any dots in
them. append_domain must begin with a period.
TYPE: int
DEFAULT: 1024
LOC: Config.ipcache.size
-DOC_NONE
+DOC_START
+ Maximum number of DNS IP cache entries.
+DOC_END
NAME: ipcache_low
COMMENT: (percent)
NAME: cachemgr_passwd
TYPE: cachemgrpasswd
DEFAULT: none
+DEFAULT_DOC: No password. Actions which require password are denied.
LOC: Config.passwd_list
DOC_START
Specify passwords for cachemgr operations.
TYPE: int
LOC: Config.connect_retries
DEFAULT: 0
+DEFAULT_DOC: Do not retry failed connections.
DOC_START
This sets the maximum number of connection attempts made for each
TCP connection. The connect_retries attempts must all still
URI. Options:
strip: The whitespace characters are stripped out of the URL.
- This is the behavior recommended by RFC2396.
+ This is the behavior recommended by RFC2396 and RFC3986
+ for tolerant handling of generic URI.
+ NOTE: This is one difference between generic URI and HTTP URLs.
+
deny: The request is denied. The user receives an "Invalid
Request" message.
+ This is the behaviour recommended by RFC2616 for safe
+ handling of HTTP request URL.
+
allow: The request is allowed and the URI is not changed. The
whitespace characters remain in the URI. Note the
whitespace is passed to redirector processes if they
are in use.
+ Note this may be considered a violation of RFC2616
+ request parsing where whitespace is prohibited in the
+ URL field.
+
encode: The request is allowed and the whitespace characters are
- encoded according to RFC1738. This could be considered
- a violation of the HTTP/1.1
- RFC because proxies are not allowed to rewrite URI's.
+ encoded according to RFC1738.
+
chop: The request is allowed and the URI is chopped at the
- first whitespace. This might also be considered a
- violation.
+ first whitespace.
+
+
+ NOTE the current Squid implementation of encode and chop violates
+ RFC2616 by not using a 301 redirect after altering the URL.
DOC_END
NAME: chroot
COMMENT: (msec)
LOC: Config.warnings.high_rptm
DEFAULT: 0
+DEFAULT_DOC: disabled.
DOC_START
If the one-minute median response time exceeds this value,
Squid prints a WARNING with debug level 0 to get the
TYPE: int
LOC: Config.warnings.high_pf
DEFAULT: 0
+DEFAULT_DOC: disabled.
DOC_START
If the one-minute average page fault rate exceeds this
value, Squid prints a WARNING with debug level 0 to get
TYPE: b_size_t
LOC: Config.warnings.high_memory
DEFAULT: 0 KB
+DEFAULT_DOC: disabled.
DOC_START
If the memory usage (as determined by mallinfo) exceeds
this amount, Squid prints a WARNING with debug level 0 to get
DOC_END
NAME: windows_ipaddrchangemonitor
-IFDEF: _SQUID_MSWIN_
+IFDEF: _SQUID_WINDOWS_
COMMENT: on|off
TYPE: onoff
DEFAULT: on
NAME: max_filedescriptors max_filedesc
TYPE: int
DEFAULT: 0
+DEFAULT_DOC: Use operating system limits set by ulimit.
LOC: Config.max_filedescriptors
DOC_START
- The maximum number of filedescriptors supported.
+ Reduce the maximum number of filedescriptors supported below
+ the usual operating system defaults.
- The default "0" means Squid inherits the current ulimit setting.
+ Remove from squid.conf to inherit the current ulimit setting.
Note: Changing this requires a restart of Squid. Also
- not all comm loops supports large values.
+ 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 ..."
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,...
projects / thirdparty / squid.git / blobdiff