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
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
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.
auth_param basic program @DEFAULT_PREFIX@/libexec/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
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.
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
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
%% 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
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]
#
# 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:
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
-----------------------------------------------------------------------------
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:
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
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>
- In the future, the rewriter interface will be extended with
- key=value pairs ("kvpairs" shown above). Rewriter programs
+
+ 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 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
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
+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
-----------------------------------------------------------------------------
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
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
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
DOC_END
NAME: windows_ipaddrchangemonitor
-IFDEF: _SQUID_MSWIN_
+IFDEF: _SQUID_WINDOWS_
COMMENT: on|off
TYPE: onoff
DEFAULT: on