diff options
| -rw-r--r-- | hosts/jenkins-test-vm/etc/squid/squid.conf | 4661 | ||||
| -rw-r--r-- | hosts/jenkins/etc/squid/squid.conf | 4661 |
2 files changed, 6840 insertions, 2482 deletions
diff --git a/hosts/jenkins-test-vm/etc/squid/squid.conf b/hosts/jenkins-test-vm/etc/squid/squid.conf index 34be0ec5..ad1cdc47 100644 --- a/hosts/jenkins-test-vm/etc/squid/squid.conf +++ b/hosts/jenkins-test-vm/etc/squid/squid.conf @@ -1,4 +1,4 @@ -# WELCOME TO SQUID 3.1.20 +# WELCOME TO SQUID 3.5.23 # ---------------------------- # # This is the documentation for the Squid configuration file. @@ -32,6 +32,188 @@ # This arbitrary restriction is to prevent recursive include references # from causing Squid entering an infinite loop whilst trying to load # configuration files. +# +# Values with byte units +# +# Squid accepts size units on some size related directives. All +# such directives are documented with a default value displaying +# a unit. +# +# Units accepted by Squid are: +# bytes - byte +# KB - Kilobyte (1024 bytes) +# MB - Megabyte +# GB - Gigabyte +# +# Values with spaces, quotes, and other special characters +# +# Squid supports directive parameters with spaces, quotes, and other +# special characters. Surround such parameters with "double quotes". Use +# the configuration_includes_quoted_values directive to enable or +# disable that support. +# +# Squid supports reading configuration option parameters from external +# files using the syntax: +# parameters("/path/filename") +# For example: +# acl whitelist dstdomain parameters("/etc/squid/whitelist.txt") +# +# Conditional configuration +# +# If-statements can be used to make configuration directives +# depend on conditions: +# +# if <CONDITION> +# ... regular configuration directives ... +# [else +# ... regular configuration directives ...] +# endif +# +# The else part is optional. The keywords "if", "else", and "endif" +# must be typed on their own lines, as if they were regular +# configuration directives. +# +# NOTE: An else-if condition is not supported. +# +# These individual conditions types are supported: +# +# true +# Always evaluates to true. +# false +# Always evaluates to false. +# <integer> = <integer> +# Equality comparison of two integer numbers. +# +# +# SMP-Related Macros +# +# The following SMP-related preprocessor macros can be used. +# +# ${process_name} expands to the current Squid process "name" +# (e.g., squid1, squid2, or cache1). +# +# ${process_number} expands to the current Squid process +# identifier, which is an integer number (e.g., 1, 2, 3) unique +# across all Squid processes of the current service instance. +# +# ${service_name} expands into the current Squid service instance +# name identifier which is provided by -n on the command line. +# + +# TAG: broken_vary_encoding +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: cache_vary +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: error_map +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: external_refresh_check +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: location_rewrite_program +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: refresh_stale_hit +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: hierarchy_stoplist +# Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use. +#Default: +# none + +# TAG: log_access +# Remove this line. Use acls with access_log directives to control access logging +#Default: +# none + +# TAG: log_icap +# Remove this line. Use acls with icap_log directives to control icap logging +#Default: +# none + +# TAG: ignore_ims_on_miss +# Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'. +#Default: +# none + +# TAG: chunked_request_body_max_size +# Remove this line. Squid is now HTTP/1.1 compliant. +#Default: +# none + +# TAG: dns_v4_fallback +# Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant. +#Default: +# none + +# TAG: emulate_httpd_log +# Replace this with an access_log directive using the format 'common' or 'combined'. +#Default: +# none + +# TAG: forward_log +# Use a regular access.log with ACL limiting it to MISS events. +#Default: +# none + +# TAG: ftp_list_width +# Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead. +#Default: +# none + +# TAG: ignore_expect_100 +# Remove this line. The HTTP/1.1 feature is now fully supported by default. +#Default: +# none + +# TAG: log_fqdn +# Remove this option from your config. To log FQDN use %>A in the log format. +#Default: +# none + +# TAG: log_ip_on_direct +# Remove this option from your config. To log server or peer names use %<A in the log format. +#Default: +# none + +# TAG: maximum_single_addr_tries +# Replaced by connect_retries. The behaviour has changed, please read the documentation before altering. +#Default: +# none + +# TAG: referer_log +# Replace this with an access_log directive using the format 'referrer'. +#Default: +# none + +# TAG: update_headers +# Remove this line. The feature is supported by default in storage types where update is implemented. +#Default: +# none + +# TAG: url_rewrite_concurrency +# Remove this line. Set the 'concurrency=' option of url_rewrite_children instead. +#Default: +# none + +# TAG: useragent_log +# Replace this with an access_log directive using the format 'useragent'. +#Default: +# none # TAG: dns_testnames # Remove this line. DNS is no longer tested on startup. @@ -43,6 +225,10 @@ #Default: # none +# TAG: zero_buffers +#Default: +# none + # TAG: incoming_rate #Default: # none @@ -73,6 +259,49 @@ #Default: # none +# TAG: wais_relay_host +# Replace this line with 'cache_peer' configuration. +#Default: +# none + +# TAG: wais_relay_port +# Replace this line with 'cache_peer' configuration. +#Default: +# none + +# OPTIONS FOR SMP +# ----------------------------------------------------------------------------- + +# TAG: workers +# Number of main Squid processes or "workers" to fork and maintain. +# 0: "no daemon" mode, like running "squid -N ..." +# 1: "no SMP" mode, start one main Squid process daemon (default) +# N: start N main Squid process daemons (i.e., SMP mode) +# +# In SMP mode, each worker does nearly all what a single Squid daemon +# does (e.g., listen on http_port and forward HTTP requests). +#Default: +# SMP support disabled. + +# TAG: cpu_affinity_map +# Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,... +# +# Sets 1:1 mapping between Squid processes and CPU cores. For example, +# +# cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7 +# +# affects processes 1 through 4 only and places them on the first +# four even cores, starting with core #1. +# +# CPU cores are numbered starting from 1. Requires support for +# sched_getaffinity(2) and sched_setaffinity(2) system calls. +# +# Multiple cpu_affinity_map options are merged. +# +# See also: workers +#Default: +# Let operating system decide. + # OPTIONS FOR AUTHENTICATION # ----------------------------------------------------------------------------- @@ -80,7 +309,7 @@ # This is used to define parameters for the various authentication # schemes supported by Squid. # -# format: auth_param scheme parameter [setting] +# format: auth_param scheme parameter [setting] # # The order in which authentication schemes are presented to the client is # dependent on the order the scheme first appears in config file. IE @@ -114,228 +343,104 @@ # Ports flagged 'transparent', 'intercept', or 'tproxy' have # authentication disabled. # -# === Parameters for the basic scheme follow. === +# === Parameters common to all schemes. === # # "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. -# If you use an authenticator, make sure you have 1 acl of type -# proxy_auth. -# -# By default, the basic authentication scheme is not used unless a -# program is specified. -# -# If you want to use the traditional NCSA proxy authentication, set -# this line to something like -# -# auth_param basic program /usr/lib/squid/ncsa_auth /usr/etc/passwd -# -# "utf8" on|off -# HTTP uses iso-latin-1 as characterset, 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. -# -# "children" numberofchildren -# The number of authenticator processes to spawn. If you start too few -# Squid will have to wait for them to process a backlog of credential -# verifications, slowing it down. When password verifications are -# done via a (slow) network you are likely to need lots of -# authenticator processes. -# auth_param basic children 5 -# -# "concurrency" concurrency -# The number of concurrent requests the helper can process. -# The default of 0 is used for helpers who only supports -# one request at a time. Setting this 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. -# Must not be set unless it's known the helper supports this. -# auth_param basic concurrency 0 -# -# "realm" realmstring -# Specifies the realm name which is to be reported to the -# client for the basic proxy authentication scheme (part of -# the text the user will see when prompted their username and -# password). There is no default. -# auth_param basic realm Squid proxy-caching web server -# -# "credentialsttl" timetolive -# Specifies how long squid assumes an externally validated -# username:password pair is valid for - in other words how -# often the helper program is called for that user. Set this -# low to force revalidation with short lived passwords. Note -# setting this high does not impact your susceptibility -# to replay attacks unless you are using an one-time password -# system (such as SecureID). If you are using such a system, -# you will be vulnerable to replay attacks unless you also -# use the max_user_ip ACL in an http_access rule. -# -# "casesensitive" on|off -# Specifies if usernames are case sensitive. Most user databases are -# case insensitive allowing the same username to be spelled using both -# lower and upper case letters, but some are case sensitive. This -# makes a big difference for user_max_ip ACL processing and similar. -# auth_param basic casesensitive off -# -# === Parameters for the digest scheme follow === +# Specifies the command for the external authenticator. # -# "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. -# -# By default, the digest authentication scheme is not used unless a -# program is specified. -# -# If you want to use a digest authenticator, set this line to -# something like -# -# auth_param digest program /usr/lib/squid/digest_pw_auth /usr/etc/digpass -# -# "utf8" on|off -# HTTP uses iso-latin-1 as characterset, 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. -# -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# If you start too few Squid will have to wait for them to -# process a backlog of H(A1) calculations, slowing it down. -# When the H(A1) calculations are done via a (slow) network -# you are likely to need lots of authenticator processes. -# auth_param digest children 5 -# -# "realm" realmstring -# Specifies the realm name which is to be reported to the -# client for the digest proxy authentication scheme (part of -# the text the user will see when prompted their username and -# password). There is no default. -# auth_param digest realm Squid proxy-caching web server -# -# "nonce_garbage_interval" timeinterval -# Specifies the interval that nonces that have been issued -# to client_agent's are checked for validity. -# -# "nonce_max_duration" timeinterval -# Specifies the maximum length of time a given nonce will be -# valid for. -# -# "nonce_max_count" number -# Specifies the maximum number of times a given nonce can be -# used. +# By default, each authentication scheme is not used unless a +# program is specified. # -# "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 -# (ie, 1,2,4,6)). Default off. +# See http://wiki.squid-cache.org/Features/AddonHelpers for +# more details on helper operations and creating your own. # -# "check_nonce_count" on|off -# This directive if set to off can disable the nonce count check -# completely to work around buggy digest qop implementations in -# certain mainstream browser versions. Default on to check the -# nonce count to protect from authentication replay attacks. +# "key_extras" format +# Specifies a string to be append to request line format for +# the authentication helper. "Quoted" format values may contain +# spaces and logformat %macros. In theory, any logformat %macro +# can be used. In practice, a %macro expands as a dash (-) if +# the helper request is sent before the required macro +# information is available to Squid. # -# "post_workaround" on|off -# This is a workaround to certain buggy browsers who sends -# an incorrect request digest in POST requests when reusing -# the same nonce as acquired earlier on a GET request. +# By default, Squid uses request formats provided in +# scheme-specific examples below (search for %credentials). # -# === NTLM scheme options follow === +# The expanded key_extras value is added to the Squid credentials +# cache and, hence, will affect authentication. It can be used to +# autenticate different users with identical user names (e.g., +# when user authentication depends on http_port). # -# "program" cmdline -# Specify the command for the external NTLM authenticator. -# 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 -# is not used. +# Avoid adding frequently changing information to key_extras. For +# example, if you add user source IP, and it changes frequently +# in your environment, then max_user_ip ACL is going to treat +# every user+IP combination as a unique "user", breaking the ACL +# and wasting a lot of memory on those user records. It will also +# force users to authenticate from scratch whenever their IP +# changes. # -# auth_param ntlm program /usr/lib/squid/ntlm_auth +# "realm" string +# Specifies the protection scope (aka realm name) which is to be +# reported to the client for the authentication scheme. It is +# commonly part of the text the user will see when prompted for +# their username and password. # -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# If you start too few Squid will have to wait for them to -# process a backlog of credential verifications, slowing it -# down. When credential verifications are done via a (slow) -# network you are likely to need lots of authenticator -# processes. +# For Basic the default is "Squid proxy-caching web server". +# For Digest there is no default, this parameter is mandatory. +# For NTLM and Negotiate this parameter is ignored. # -# auth_param ntlm children 5 +# "children" numberofchildren [startup=N] [idle=N] [concurrency=N] # -# "keep_alive" on|off -# Whether to keep the connection open after the initial response where -# Squid tells the browser which schemes are supported by the proxy. -# Some browsers are known to present many login popups or to corrupt -# POST/PUT requests transfer if the connection is not closed. -# The default is currently OFF to avoid this, but may change. -# -# auth_param ntlm keep_alive on +# The maximum number of authenticator processes to spawn. If +# you start too few Squid will have to wait for them to process +# a backlog of credential verifications, slowing it down. When +# password verifications are done via a (slow) network you are +# likely to need lots of authenticator processes. # -# === Options for configuring the NEGOTIATE auth-scheme follow === +# The startup= and idle= options permit some skew in the exact +# amount run. A minimum of startup=N will begin during startup +# and reconfigure. Squid will start more in groups of up to +# idle=N in an attempt to meet traffic needs and to keep idle=N +# free above those traffic needs up to the maximum. # -# "program" cmdline -# Specify the command for the external Negotiate authenticator. -# This protocol is used in Microsoft Active-Directory enabled setups with -# the Microsoft Internet Explorer or Mozilla Firefox browsers. -# Its main purpose is to exchange credentials with the Squid proxy -# 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. -# 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 /usr/lib/squid/ntlm_auth --helper-protocol=gss-spnego -# -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# 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) -# network you are likely to need lots of authenticator -# processes. -# auth_param negotiate children 5 -# -# "keep_alive" on|off -# Whether to keep the connection open after the initial response where -# Squid tells the browser which schemes are supported by the proxy. -# Some browsers are known to present many login popups or to corrupt -# POST/PUT requests transfer if the connection is not closed. -# The default is currently OFF to avoid this, but may change. -# -# auth_param negotiate keep_alive on +# The concurrency= option sets the number of concurrent requests +# the helper can process. The default of 0 is used for helpers +# who only supports one request at a time. Setting this to a +# number greater than 0 changes the protocol used to include a +# channel ID field first on the request/response line, allowing +# multiple requests to be sent to the same helper in parallel +# without waiting for the response. # +# Concurrency must not be set unless it's known the helper +# supports the input format with channel-ID fields. +# +# NOTE: NTLM and Negotiate schemes do not support concurrency +# in the Squid code module even though some helpers can. # -# Examples: # -##Recommended minimum configuration per scheme: +# +# === Example Configuration === +# +# This configuration displays the recommended authentication scheme +# order from most to least secure with recommended minimum configuration +# settings for each scheme: +# ##auth_param negotiate program <uncomment and complete this line to activate> -##auth_param negotiate children 5 +##auth_param negotiate children 20 startup=0 idle=1 ##auth_param negotiate keep_alive on ## -##auth_param ntlm program <uncomment and complete this line to activate> -##auth_param ntlm children 5 -##auth_param ntlm keep_alive on -## -##auth_param digest program <uncomment and complete this line> -##auth_param digest children 5 +##auth_param digest program <uncomment and complete this line to activate> +##auth_param digest children 20 startup=0 idle=1 ##auth_param digest realm Squid proxy-caching web server ##auth_param digest nonce_garbage_interval 5 minutes ##auth_param digest nonce_max_duration 30 minutes ##auth_param digest nonce_max_count 50 ## +##auth_param ntlm program <uncomment and complete this line to activate> +##auth_param ntlm children 20 startup=0 idle=1 +##auth_param ntlm keep_alive on +## ##auth_param basic program <uncomment and complete this line> -##auth_param basic children 5 +##auth_param basic children 5 startup=5 idle=1 ##auth_param basic realm Squid proxy-caching web server ##auth_param basic credentialsttl 2 hours #Default: @@ -343,7 +448,7 @@ # TAG: authenticate_cache_garbage_interval # 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. #Default: @@ -362,11 +467,11 @@ # 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. #Default: -# authenticate_ip_ttl 0 seconds +# authenticate_ip_ttl 1 second # ACCESS CONTROLS # ----------------------------------------------------------------------------- @@ -381,31 +486,66 @@ # # ttl=n TTL in seconds for cached results (defaults to 3600 # for 1 hour) +# # negative_ttl=n # TTL for cached negative lookups (default same # as ttl) -# children=n Number of acl helper processes spawn to service +# +# grace=n Percentage remaining of TTL where a refresh of a +# cached entry should be initiated without needing to +# wait for a new reply. (default is for no grace period) +# +# cache=n The maximum number of entries in the result cache. The +# default limit is 262144 entries. Each cache entry usually +# consumes at least 256 bytes. Squid currently does not remove +# expired cache entries until the limit is reached, so a proxy +# will sooner or later reach the limit. The expanded FORMAT +# value is used as the cache key, so if the details in FORMAT +# are highly variable, a larger cache may be needed to produce +# reduction in helper load. +# +# children-max=n +# Maximum number of acl helper processes spawned to service # external acl lookups of this type. (default 5) +# +# children-startup=n +# Minimum number of acl helper processes to spawn during +# startup and reconfigure to service external acl lookups +# of this type. (default 0) +# +# children-idle=n +# Number of acl helper processes to keep ahead of traffic +# loads. Squid will spawn this many at once whenever load +# rises above the capabilities of existing processes. +# Up to the value of children-max. (default 1) +# # concurrency=n concurrency level per process. Only used with helpers # capable of processing more than one query at a time. -# cache=n result cache size, 0 is unbounded (default) -# grace=n Percentage remaining of TTL where a refresh of a -# cached entry should be initiated without needing to -# wait for a new reply. (default 0 for no grace period) -# protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers +# +# protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers. +# # ipv4 / ipv6 IP protocol used to communicate with this helper. # The default is to auto-detect IPv6 and use it when available. # +# # FORMAT specifications # # %LOGIN Authenticated user login name -# %EXT_USER Username from external acl +# %un A user name. Expands to the first available name +# from the following list of information sources: +# - authenticated user name, like %ul or %LOGIN +# - user name sent by an external ACL, like %EXT_USER +# - SSL client name, like %us in logformat +# - ident user name, like %ui in logformat +# %EXT_USER Username from previous external acl +# %EXT_LOG Log details from previous external acl +# %EXT_TAG Tag from previous external acl # %IDENT Ident user name # %SRC Client IP # %SRCPORT Client source port # %URI Requested URI # %DST Requested host -# %PROTO Requested protocol +# %PROTO Requested URL scheme # %PORT Requested port # %PATH Requested URL path # %METHOD Request method @@ -415,7 +555,10 @@ # %USER_CERT SSL User certificate in PEM format # %USER_CERTCHAIN SSL User certificate chain in PEM format # %USER_CERT_xx SSL User certificate subject attribute xx -# %USER_CA_xx SSL User certificate issuer attribute xx +# %USER_CA_CERT_xx SSL User certificate issuer attribute xx +# %ssl::>sni SSL client SNI sent to Squid +# %ssl::<cert_subject SSL server certificate DN +# %ssl::<cert_issuer SSL server certificate issuer DN # # %>{Header} HTTP request header "Header" # %>{Hdr:member} @@ -433,43 +576,101 @@ # 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. +# clt_conn_tag= Associates a TAG with the client TCP connection. +# Please see url_rewrite_program related documentation +# for this kv-pair. # -# 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. +# Any keywords may be sent on any response whether OK, ERR or BH. # -# 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. +# 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. +# +# Some example key values: +# +# user=John%20Smith +# user="John Smith" +# user="J. \"Bob\" Smith" #Default: # none @@ -485,9 +686,23 @@ # # 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. @@ -498,29 +713,31 @@ # # ***** ACL TYPES AVAILABLE ***** # -# acl aclname src ip-address/netmask ... # clients IP address [fast] -# acl aclname src addr1-addr2/netmask ... # range of addresses [fast] -# acl aclname dst ip-address/netmask ... # URL host's IP address [slow] -# acl aclname myip ip-address/netmask ... # local socket IP address [fast] +# acl aclname src ip-address/mask ... # clients IP address [fast] +# acl aclname src addr1-addr2/mask ... # range of addresses [fast] +# 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) -# # The arp ACL requires the special configure option --enable-arp-acl. -# # Furthermore, the ARP ACL code is not portable to all operating systems. -# # It works on Linux, Solaris, Windows, FreeBSD, and some -# # other *BSD variants. # # [fast] +# # The 'arp' ACL code is not portable to all operating systems. +# # It works on Linux, Solaris, Windows, FreeBSD, and some other +# # BSD variants. # # -# # NOTE: Squid can only determine the MAC address for clients that are on -# # the same subnet. If the client is on a different subnet, -# # then Squid cannot find out its MAC address. +# # NOTE: Squid can only determine the MAC/EUI address for IPv4 +# # clients that are on the same subnet. If the client is on a +# # different subnet, then Squid cannot find out its address. +# # +# # NOTE 2: IPv6 protocol does not contain ARP. MAC/EUI is either +# # encoded directly in the IPv6 address or not available. # # acl aclname srcdomain .foo.com ... # # reverse lookup, from client IP [slow] -# acl aclname 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 @@ -557,13 +774,17 @@ # # 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] # # acl aclname port 80 70 21 0-1024... # destination TCP port [fast] # # ranges are alloed -# acl aclname myport 3128 ... # local socket TCP port [fast] -# acl aclname myportname 3128 ... # http(s)_port name [fast] +# acl aclname localport 3128 ... # TCP port the client connected to [fast] +# # NP: for interception mode this is usually '80' +# +# acl aclname myportname 3128 ... # *_port name [fast] # # acl aclname proto HTTP FTP ... # request protocol [fast] # @@ -632,6 +853,11 @@ # # clients may appear to come from multiple addresses if they are # # going through proxy farms, so a limit of 1 may cause user problems. # +# acl aclname random probability +# # Pseudo-randomly match requests. Based on the probability given. +# # Probability may be written as a decimal (0.333), fraction (1/3) +# # or ratio of matches:non-matches (3:5). +# # acl aclname req_mime_type [-i] mime-type ... # # regex match against the mime type of the request generated # # by the client. Can be used to detect file upload or some @@ -663,11 +889,11 @@ # # acl aclname user_cert attribute values... # # match against attributes in a user SSL certificate -# # attribute is one of DN/C/O/CN/L/ST [fast] +# # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] # # acl aclname ca_cert attribute values... # # match against attributes a users issuing CA SSL certificate -# # attribute is one of DN/C/O/CN/L/ST [fast] +# # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] # # acl aclname ext_user username ... # acl aclname ext_user_regex [-i] pattern ... @@ -675,7 +901,59 @@ # # use REQUIRED to accept any non-null user name. # # acl aclname tag tagvalue ... -# # string match on tag returned by external acl helper [slow] +# # string match on tag returned by external acl helper [fast] +# # DEPRECATED. Only the first tag will match with this ACL. +# # Use the 'note' ACL instead for handling multiple tag values. +# +# acl aclname hier_code codename ... +# # string match against squid hierarchy code(s); [fast] +# # e.g., DIRECT, PARENT_HIT, NONE, etc. +# # +# # NOTE: This has no effect in http_access rules. It only has +# # effect in rules that affect the reply data stream such as +# # http_reply_access. +# +# acl aclname note name [value ...] +# # match transaction annotation [fast] +# # Without values, matches any annotation with a given name. +# # With value(s), matches any annotation with a given name that +# # also has one of the given values. +# # Names and values are compared using a string equality test. +# # Annotation sources include note and adaptation_meta directives +# # as well as helper and eCAP responses. +# +# acl aclname adaptation_service service ... +# # Matches the name of any icap_service, ecap_service, +# # adaptation_service_set, or adaptation_service_chain that Squid +# # has used (or attempted to use) for the master transaction. +# # This ACL must be defined after the corresponding adaptation +# # service is named in squid.conf. This ACL is usable with +# # adaptation_meta because it starts matching immediately after +# # the service has been selected for adaptation. +# +# acl aclname any-of acl1 acl2 ... +# # match any one of the acls [fast or slow] +# # The first matching ACL stops further ACL evaluation. +# # +# # ACLs from multiple any-of lines with the same name are ORed. +# # For example, A = (a1 or a2) or (a3 or a4) can be written as +# # acl A any-of a1 a2 +# # acl A any-of a3 a4 +# # +# # This group ACL is fast if all evaluated ACLs in the group are fast +# # and slow otherwise. +# +# acl aclname all-of acl1 acl2 ... +# # match all of the acls [fast or slow] +# # The first mismatching ACL stops further ACL evaluation. +# # +# # ACLs from multiple all-of lines with the same name are ORed. +# # For example, B = (b1 and b2) or (b3 and b4) can be written as +# # acl B all-of b1 b2 +# # acl B all-of b3 b4 +# # +# # This group ACL is fast if all evaluated ACLs in the group are fast +# # and slow otherwise. # # Examples: # acl macaddress arp 09:00:2b:23:45:67 @@ -685,14 +963,11 @@ # acl javascript rep_mime_type -i ^application/x-javascript$ # #Default: -# acl all src all +# ACLs all, manager, localhost, and to_localhost are predefined. # # # Recommended minimum configuration: -# (now built-in) -#acl manager proto cache_object -#acl localhost src 127.0.0.1/32 ::1 -#acl to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1 +# # Example rule allowing access from your local networks. # Adapt to list your (internal) IP networks from where browsing @@ -716,39 +991,83 @@ acl Safe_ports port 591 # filemaker acl Safe_ports port 777 # multiling http acl CONNECT method CONNECT +# TAG: proxy_protocol_access +# Determine which client proxies can be trusted to provide correct +# information regarding real client IP address using PROXY protocol. +# +# Requests may pass through a chain of several other proxies +# before reaching us. The original source details may by sent in: +# * HTTP message Forwarded header, or +# * HTTP message X-Forwarded-For header, or +# * PROXY protocol connection header. +# +# This directive is solely for validating new PROXY protocol +# connections received from a port flagged with require-proxy-header. +# It is checked only once after TCP connection setup. +# +# A deny match results in TCP connection closure. +# +# An allow match is required for Squid to permit the corresponding +# TCP connection, before Squid even looks for HTTP request headers. +# If there is an allow match, Squid starts using PROXY header information +# to determine the source address of the connection for all future ACL +# checks, logging, etc. +# +# SECURITY CONSIDERATIONS: +# +# Any host from which we accept client IP details can place +# incorrect information in the relevant header, and Squid +# will use the incorrect information as if it were the +# source address of the request. This may enable remote +# hosts to bypass any access control restrictions that are +# based on the client's source addresses. +# +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +#Default: +# all TCP connections to ports with require-proxy-header will be denied + # TAG: follow_x_forwarded_for -# Allowing or Denying the X-Forwarded-For header to be followed to -# find the original source of a request. +# Determine which client proxies can be trusted to provide correct +# information regarding real client IP address. # # Requests may pass through a chain of several other proxies -# before reaching us. The X-Forwarded-For header will contain a -# comma-separated list of the IP addresses in the chain, with the -# rightmost address being the most recent. +# before reaching us. The original source details may by sent in: +# * HTTP message Forwarded header, or +# * HTTP message X-Forwarded-For header, or +# * PROXY protocol connection header. +# +# PROXY protocol connections are controlled by the proxy_protocol_access +# directive which is checked before this. # # If a request reaches us from a source that is allowed by this -# configuration item, then we consult the X-Forwarded-For header -# to see where that host received the request from. If the -# X-Forwarded-For header contains multiple addresses, we continue -# backtracking until we reach an address for which we are not allowed -# to follow the X-Forwarded-For header, or until we reach the first -# address in the list. For the purpose of ACL used in the -# follow_x_forwarded_for directive the src ACL type always matches -# the address we are testing and srcdomain matches its rDNS. +# directive, then we trust the information it provides regarding +# the IP of the client it received from (if any). +# +# For the purpose of ACLs used in this directive the src ACL type always +# matches the address we are testing and srcdomain matches its rDNS. +# +# On each HTTP request Squid checks for X-Forwarded-For header fields. +# If found the header values are iterated in reverse order and an allow +# match is required for Squid to continue on to the next value. +# The verification ends when a value receives a deny match, cannot be +# tested, or there are no more values to test. +# NOTE: Squid does not yet follow the Forwarded HTTP header. # # The end result of this process is an IP address that we will # refer to as the indirect client address. This address may # be treated as the client address for access control, ICAP, delay # pools and logging, depending on the acl_uses_indirect_client, -# icap_uses_indirect_client, delay_pool_uses_indirect_client and -# log_uses_indirect_client options. +# icap_uses_indirect_client, delay_pool_uses_indirect_client, +# log_uses_indirect_client and tproxy_uses_indirect_client options. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # # SECURITY CONSIDERATIONS: # -# Any host for which we follow the X-Forwarded-For header -# can place incorrect information in the header, and Squid +# Any host from which we accept client IP details can place +# incorrect information in the relevant header, and Squid # will use the incorrect information as if it were the # source address of the request. This may enable remote # hosts to bypass any access control restrictions that are @@ -761,7 +1080,7 @@ acl CONNECT method CONNECT # follow_x_forwarded_for allow localhost # follow_x_forwarded_for allow my_other_proxy #Default: -# follow_x_forwarded_for deny all +# X-Forwarded-For header will be ignored. # TAG: acl_uses_indirect_client on|off # Controls whether the indirect client address @@ -787,10 +1106,41 @@ acl CONNECT method CONNECT #Default: # log_uses_indirect_client on +# TAG: tproxy_uses_indirect_client on|off +# Controls whether the indirect client address +# (see follow_x_forwarded_for) is used instead of the +# direct client address when spoofing the outgoing client. +# +# This has no effect on requests arriving in non-tproxy +# mode ports. +# +# SECURITY WARNING: Usage of this option is dangerous +# and should not be used trivially. Correct configuration +# of follow_x_forwarded_for with a limited set of trusted +# sources is required to prevent abuse of your proxy. +#Default: +# tproxy_uses_indirect_client off + +# TAG: spoof_client_ip +# 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. +#Default: +# Allow spoofing on all TPROXY traffic. + # TAG: http_access # Allowing or Denying access based on defined access lists # -# Access to the HTTP port: +# To allow or deny a message received on an HTTP, HTTPS, or FTP port: # http_access allow|deny [!]aclname ... # # NOTE on default values: @@ -809,22 +1159,22 @@ acl CONNECT method CONNECT # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # #Default: -# http_access deny all +# Deny, unless rules exist in squid.conf. # # # Recommended minimum Access Permission configuration: # -# Only allow cachemgr access from localhost -http_access allow manager localhost -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 @@ -852,7 +1202,7 @@ http_access deny all # # If not set then only http_access is used. #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: http_reply_access # Allow replies to client requests. This is complementary to http_access. @@ -860,7 +1210,7 @@ http_access deny all # 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 @@ -869,7 +1219,7 @@ http_access deny all # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: icp_access # Allowing or Denying access to the ICP port based on defined @@ -877,7 +1227,9 @@ http_access deny all # # 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. @@ -886,7 +1238,7 @@ http_access deny all ##icp_access allow localnet ##icp_access deny all #Default: -# icp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: htcp_access # Allowing or Denying access to the HTCP port based on defined @@ -894,11 +1246,12 @@ http_access deny all # # 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 -# using the htcp or htcp-oldsquid options. +# using the htcp option. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. @@ -907,48 +1260,47 @@ http_access deny all ##htcp_access allow localnet ##htcp_access deny all #Default: -# htcp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: htcp_clr_access # 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 #Default: -# htcp_clr_access deny all +# Deny, unless rules exist in squid.conf. # TAG: miss_access -# Determins whether network access is permitted when satisfying a request. +# Determines whether network access is permitted when satisfying a request. # # For example; # to force your neighbors to use you as a sibling instead of # 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. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# miss_access allow all +# Allow, unless rules exist in squid.conf. # TAG: ident_lookup_access # A list of ACL elements which, if matched, cause an ident @@ -972,7 +1324,7 @@ http_access deny all # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# ident_lookup_access deny all +# Unless rules exist in squid.conf, IDENT is not fetched. # TAG: reply_body_max_size size [acl acl...] # This option specifies the maximum size of a reply body. It can be @@ -1009,23 +1361,22 @@ http_access deny all # reply_body_max_size 10 MB # #Default: -# none +# No limit is applied. # NETWORK OPTIONS # ----------------------------------------------------------------------------- # TAG: http_port -# Usage: port [options] -# hostname:port [options] -# 1.2.3.4:port [options] +# Usage: port [mode] [options] +# hostname:port [mode] [options] +# 1.2.3.4:port [mode] [options] # # The socket addresses where Squid will listen for HTTP client # requests. You may specify multiple socket addresses. # There are three forms: port alone, hostname with port, and # IP address with port. If you specify a hostname or IP # address, Squid binds the socket to that specific -# address. This replaces the old 'tcp_incoming_address' -# option. Most likely, you do not need to bind to a specific +# address. Most likely, you do not need to bind to a specific # address, so you can use the port number alone. # # If you are running Squid in accelerator mode, you @@ -1037,48 +1388,184 @@ http_access deny all # # You may specify multiple socket addresses on multiple lines. # -# Options: +# Modes: # -# intercept Support for IP-Layer interception of -# outgoing requests without browser settings. -# NP: disables authentication and IPv6 on the port. +# intercept Support for IP-Layer NAT interception delivering +# traffic to this Squid port. +# NP: disables authentication on the port. # -# tproxy Support Linux TPROXY for spoofing outgoing -# connections using the client IP address. -# NP: disables authentication and maybe IPv6 on the port. +# tproxy Support Linux TPROXY (or BSD divert-to) with spoofing +# of outgoing connections using the client IP address. +# NP: disables authentication on the port. # -# accel Accelerator mode. Also needs at least one of -# vhost / vport / defaultsite. +# accel Accelerator / reverse proxy mode +# +# ssl-bump For each CONNECT request allowed by ssl_bump ACLs, +# establish secure connection with the client and with +# the server, decrypt HTTPS messages as they pass through +# Squid, and treat them as unencrypted HTTP messages, +# becoming the man-in-the-middle. +# +# The ssl_bump option is required to fully enable +# bumping of CONNECT requests. +# +# Omitting the mode flag causes default forward proxy mode to be used. # -# allow-direct Allow direct forwarding in accelerator mode. Normally -# accelerated requests are denied direct forwarding as if -# never_direct was used. +# +# Accelerator Mode Options: # # defaultsite=domainname # What to use for the Host: header if it is not present # in a request. Determines what site (not origin server) # accelerators should consider the default. -# Implies accel. # -# vhost Accelerator mode using Host header for virtual domain support. -# Also uses the port as specified in Host: header unless -# overridden by the vport option. Implies accel. +# no-vhost Disable using HTTP/1.1 Host header for virtual domain support. +# +# protocol= Protocol to reconstruct accelerated and intercepted +# requests with. Defaults to HTTP/1.1 for http_port and +# HTTPS/1.1 for https_port. +# When an unsupported value is configured Squid will +# produce a FATAL error. +# Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1 # # vport Virtual host port support. Using the http_port number -# instead of the port passed on Host: headers. Implies accel. +# instead of the port passed on Host: headers. # # vport=NN Virtual host port support. Using the specified port # number instead of the port passed on Host: headers. -# Implies accel. # -# protocol= Protocol to reconstruct accelerated requests with. -# Defaults to http. +# act-as-origin +# Act as if this Squid is the origin server. +# This currently means generate new Date: and Expires: +# headers on HIT instead of adding Age:. # # ignore-cc Ignore request Cache-Control headers. # -# Warning: This option violates HTTP specifications if +# WARNING: This option violates HTTP specifications if # used in non-accelerator setups. # +# allow-direct Allow direct forwarding in accelerator mode. Normally +# accelerated requests are denied direct forwarding as if +# never_direct was used. +# +# WARNING: this option opens accelerator mode to security +# vulnerabilities usually only affecting in interception +# mode. Make sure to protect forwarding with suitable +# http_access rules when using this. +# +# +# SSL Bump Mode Options: +# In addition to these options ssl-bump requires TLS/SSL options. +# +# generate-host-certificates[=<on|off>] +# Dynamically create SSL server certificates for the +# destination hosts of bumped CONNECT requests.When +# enabled, the cert and key options are used to sign +# generated certificates. Otherwise generated +# certificate will be selfsigned. +# If there is a CA certificate lifetime of the generated +# certificate equals lifetime of the CA certificate. If +# generated certificate is selfsigned lifetime is three +# years. +# This option is disabled by default. See the ssl-bump +# option above for more information. +# +# dynamic_cert_mem_cache_size=SIZE +# Approximate total RAM size spent on cached generated +# certificates. If set to zero, caching is disabled. +# +# TLS / SSL Options: +# +# cert= Path to SSL certificate (PEM format). +# +# key= Path to SSL private key file (PEM format) +# if not specified, the certificate file is +# assumed to be a combined certificate and +# key file. +# +# version= The version of SSL/TLS supported +# 1 automatic (default) +# 2 SSLv2 only +# 3 SSLv3 only +# 4 TLSv1.0 only +# 5 TLSv1.1 only +# 6 TLSv1.2 only +# +# cipher= Colon separated list of supported ciphers. +# NOTE: some ciphers such as EDH ciphers depend on +# additional settings. If those settings are +# omitted the ciphers may be silently ignored +# by the OpenSSL library. +# +# options= Various SSL implementation options. The most important +# being: +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# SINGLE_DH_USE Always create a new key when using +# temporary/ephemeral DH key exchanges +# NO_TICKET Disables TLS tickets extension +# +# SINGLE_ECDH_USE +# Enable ephemeral ECDH key exchange. +# The adopted curve should be specified +# using the tls-dh option. +# +# ALL Enable various bug workarounds +# suggested as "harmless" by OpenSSL +# Be warned that this reduces SSL/TLS +# strength to some attacks. +# See OpenSSL SSL_CTX_set_options documentation for a +# complete list of options. +# +# clientca= File containing the list of CAs to use when +# requesting a client certificate. +# +# cafile= File containing additional CA certificates to +# use when verifying client certificates. If unset +# clientca will be used. +# +# capath= Directory containing additional CA certificates +# and CRL lists to use when verifying client certificates. +# +# crlfile= File of additional CRL lists to use when verifying +# the client certificate, in addition to CRLs stored in +# the capath. Implies VERIFY_CRL flag below. +# +# tls-dh=[curve:]file +# File containing DH parameters for temporary/ephemeral DH key +# exchanges, optionally prefixed by a curve for ephemeral ECDH +# key exchanges. +# See OpenSSL documentation for details on how to create the +# DH parameter file. Supported curves for ECDH can be listed +# using the "openssl ecparam -list_curves" command. +# WARNING: EDH and EECDH ciphers will be silently disabled if +# this option is not set. +# +# sslflags= Various flags modifying the use of SSL: +# DELAYED_AUTH +# Don't request client certificates +# immediately, but wait until acl processing +# requires a certificate (not yet implemented). +# NO_DEFAULT_CA +# Don't use the default CA lists built in +# to OpenSSL. +# NO_SESSION_REUSE +# Don't allow for session reuse. Each connection +# will result in a new SSL session. +# VERIFY_CRL +# Verify CRL lists when accepting client +# certificates. +# VERIFY_CRL_ALL +# Verify CRL lists for all certificates in the +# client certificate chain. +# +# sslcontext= SSL session ID context identifier. +# +# Other Options: +# # connection-auth[=on|off] # use connection-auth=off to tell Squid to prevent # forwarding Microsoft connection oriented authentication @@ -1100,22 +1587,6 @@ http_access deny all # sporadically hang or never complete requests set # disable-pmtu-discovery option to 'transparent'. # -# ssl-bump Intercept each CONNECT request matching ssl_bump ACL, -# establish secure connection with the client and with -# the server, decrypt HTTP messages as they pass through -# Squid, and treat them as unencrypted HTTP messages, -# becoming the man-in-the-middle. -# -# When this option is enabled, additional options become -# available to specify SSL-related properties of the -# client-side connection: cert, key, version, cipher, -# options, clientca, cafile, capath, crlfile, dhparams, -# sslflags, and sslcontext. See the https_port directive -# for more information on these options. -# -# The ssl_bump option is required to fully enable -# the SslBump feature. -# # name= Specifies a internal name for the port. Defaults to # the port specification (port or addr:port) # @@ -1125,6 +1596,11 @@ http_access deny all # probing the connection, interval how often to probe, and # timeout the time before giving up. # +# require-proxy-header +# Require PROXY protocol version 1 or 2 connections. +# The proxy_protocol_access is required to whitelist +# downstream proxies which can be trusted. +# # If you run Squid on a dual-homed machine with an internal # and an external interface we recommend you to specify the # internal address:port in http_port. This way Squid will only be @@ -1137,35 +1613,49 @@ http_port 3128 # TAG: https_port # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...] +# Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...] # -# The socket address where Squid will listen for HTTPS client -# requests. +# The socket address where Squid will listen for client requests made +# over TLS or SSL connections. Commonly referred to as HTTPS. # -# This is really only useful for situations where you are running -# squid in accelerator mode and you want to do the SSL work at the -# accelerator level. +# This is most useful for situations where you are running squid in +# accelerator mode and you want to do the SSL work at the accelerator level. # # You may specify multiple socket addresses on multiple lines, # each with their own SSL certificate and/or options. # -# Options: +# Modes: +# +# 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. +# +# ssl-bump For each intercepted connection allowed by ssl_bump +# ACLs, establish a secure connection with the client and with +# the server, decrypt HTTPS messages as they pass through +# Squid, and treat them as unencrypted HTTP messages, +# becoming the man-in-the-middle. # -# accel Accelerator mode. Also needs at least one of -# defaultsite or vhost. +# An "ssl_bump server-first" match is required to +# fully enable bumping of intercepted SSL connections. # -# defaultsite= The name of the https site presented on -# this port. Implies accel. +# Requires tproxy or intercept. # -# vhost Accelerator mode using Host header for virtual -# domain support. Requires a wildcard certificate -# or other certificate valid for more than one domain. -# Implies accel. +# Omitting the mode flag causes default forward proxy mode to be used. # -# protocol= Protocol to reconstruct accelerated requests with. -# Defaults to https. +# +# See http_port for a list of generic options +# +# +# SSL Options: # # cert= Path to SSL certificate (PEM format). # @@ -1181,20 +1671,23 @@ http_port 3128 # 4 TLSv1 only # # cipher= Colon separated list of supported ciphers. -# NOTE: some ciphers such as EDH ciphers depend on -# additional settings. If those settings are -# omitted the ciphers may be silently ignored -# by the OpenSSL library. # # options= Various SSL engine options. The most important # being: # NO_SSLv2 Disallow the use of SSLv2 # NO_SSLv3 Disallow the use of SSLv3 # NO_TLSv1 Disallow the use of TLSv1 +# # SINGLE_DH_USE Always create a new key when using # temporary/ephemeral DH key exchanges -# See OpenSSL SSL_CTX_set_options documentation for a -# complete list of options. +# +# SINGLE_ECDH_USE +# Enable ephemeral ECDH key exchange. +# The adopted curve should be specified +# using the tls-dh option. +# +# See src/ssl_support.c or OpenSSL SSL_CTX_set_options +# documentation for a complete list of options. # # clientca= File containing the list of CAs to use when # requesting a client certificate. @@ -1210,11 +1703,10 @@ http_port 3128 # the client certificate, in addition to CRLs stored in # the capath. Implies VERIFY_CRL flag below. # -# dhparams= File containing DH parameters for temporary/ephemeral -# DH key exchanges. See OpenSSL documentation for details -# on how to create this file. -# WARNING: EDH ciphers will be silently disabled if this -# option is not set. +# tls-dh=[curve:]file +# File containing DH parameters for temporary/ephemeral DH key +# exchanges, optionally prefixed by a curve for ephemeral ECDH +# key exchanges. # # sslflags= Various flags modifying the use of SSL: # DELAYED_AUTH @@ -1238,38 +1730,89 @@ http_port 3128 # # generate-host-certificates[=<on|off>] # Dynamically create SSL server certificates for the -# destination hosts of bumped CONNECT requests.When +# destination hosts of bumped SSL requests.When # enabled, the cert and key options are used to sign # generated certificates. Otherwise generated # certificate will be selfsigned. -# If there is CA certificate life time of generated +# If there is CA certificate life time of generated # certificate equals lifetime of CA certificate. If -# generated certificate is selfsigned lifetime is three +# generated certificate is selfsigned lifetime is three # years. -# This option is enabled by default when SslBump is used. -# See the sslBump option above for more information. -# +# This option is disabled by default. See the ssl-bump +# option above for more information. +# # dynamic_cert_mem_cache_size=SIZE # Approximate total RAM size spent on cached generated -# certificates. If set to zero, caching is disabled. The -# default value is 4MB. An average XXX-bit certificate -# consumes about XXX bytes of RAM. +# certificates. If set to zero, caching is disabled. # -# vport Accelerator with IP based virtual host support. +# See http_port for a list of available options. +#Default: +# none + +# TAG: ftp_port +# Enables Native FTP proxy by specifying the socket address where Squid +# listens for FTP client requests. See http_port directive for various +# ways to specify the listening address and mode. # -# vport=NN As above, but uses specified port number rather -# than the https_port number. Implies accel. +# Usage: ftp_port address [mode] [options] # -# name= Specifies a internal name for the port. Defaults to -# the port specification (port or addr:port) +# WARNING: This is a new, experimental, complex feature that has seen +# limited production exposure. Some Squid modules (e.g., caching) do not +# currently work with native FTP proxying, and many features have not +# even been tested for compatibility. Test well before deploying! +# +# Native FTP proxying differs substantially from proxying HTTP requests +# with ftp:// URIs because Squid works as an FTP server and receives +# actual FTP commands (rather than HTTP requests with FTP URLs). +# +# Native FTP commands accepted at ftp_port are internally converted or +# wrapped into HTTP-like messages. The same happens to Native FTP +# responses received from FTP origin servers. Those HTTP-like messages +# are shoveled through regular access control and adaptation layers +# between the FTP client and the FTP origin server. This allows Squid to +# examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP +# mechanisms when shoveling wrapped FTP messages. For example, +# http_access and adaptation_access directives are used. # +# Modes: +# +# intercept Same as http_port intercept. The FTP origin address is +# determined based on the intended destination of the +# intercepted connection. +# +# tproxy Support Linux TPROXY for spoofing outgoing +# connections using the client IP address. +# NP: disables authentication and maybe IPv6 on the port. +# +# By default (i.e., without an explicit mode option), Squid extracts the +# FTP origin address from the login@origin parameter of the FTP USER +# command. Many popular FTP clients support such native FTP proxying. +# +# Options: +# +# name=token Specifies an internal name for the port. Defaults to +# the port address. Usable with myportname ACL. +# +# ftp-track-dirs +# Enables tracking of FTP directories by injecting extra +# PWD commands and adjusting Request-URI (in wrapping +# HTTP requests) to reflect the current FTP server +# directory. Tracking is disabled by default. +# +# protocol=FTP Protocol to reconstruct accelerated and intercepted +# requests with. Defaults to FTP. No other accepted +# values have been tested with. An unsupported value +# results in a FATAL error. Accepted values are FTP, +# HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1). +# +# Other http_port modes and options that are not specific to HTTP and +# HTTPS may also work. #Default: # none # TAG: tcp_outgoing_tos -# Allows you to select a TOS/Diffserv value to mark outgoing -# connections with, based on the username or source address -# making the request. +# Allows you to select a TOS/Diffserv value for packets outgoing +# on the server side, based on an ACL. # # tcp_outgoing_tos ds-field [!]aclname ... # @@ -1286,41 +1829,116 @@ http_port 3128 # RFC2475, and RFC3260. # # The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or -# "default" to use whatever default your host has. Note that in -# practice often only multiples of 4 is usable as the two rightmost bits -# have been redefined for use by ECN (RFC 3168 section 23.1). +# "default" to use whatever default your host has. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. # # Processing proceeds in the order specified, and stops at first fully # matching line. # -# Note: The use of this directive using client dependent ACLs is -# incompatible with the use of server side persistent connections. To -# ensure correct results it is best to set server_persistent_connections -# to off when using this directive in such configurations. +# Only fast ACLs are supported. #Default: # none # TAG: clientside_tos -# Allows you to select a TOS/Diffserv value to mark client-side -# connections with, based on the username or source address -# making the request. +# Allows you to select a TOS/DSCP value for packets being transmitted +# on the client-side, based on an ACL. +# +# clientside_tos ds-field [!]aclname ... +# +# Example where normal_service_net uses the TOS value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# clientside_tos 0x00 normal_service_net +# clientside_tos 0x20 good_service_net +# +# Note: This feature is incompatible with qos_flows. Any TOS values set here +# will be overwritten by TOS values in qos_flows. +# +# The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or +# "default" to use whatever default your host has. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. +# +#Default: +# none + +# TAG: tcp_outgoing_mark +# Note: This option is only available if Squid is rebuilt with the +# Packet MARK (Linux) +# +# Allows you to apply a Netfilter mark value to outgoing packets +# on the server side, based on an ACL. +# +# tcp_outgoing_mark mark-value [!]aclname ... +# +# Example where normal_service_net uses the mark value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# tcp_outgoing_mark 0x00 normal_service_net +# tcp_outgoing_mark 0x20 good_service_net +# +# Only fast ACLs are supported. +#Default: +# none + +# TAG: clientside_mark +# Note: This option is only available if Squid is rebuilt with the +# Packet MARK (Linux) +# +# Allows you to apply a Netfilter mark value to packets being transmitted +# on the client-side, based on an ACL. +# +# clientside_mark mark-value [!]aclname ... +# +# Example where normal_service_net uses the mark value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# clientside_mark 0x00 normal_service_net +# clientside_mark 0x20 good_service_net +# +# Note: This feature is incompatible with qos_flows. Any mark values set here +# will be overwritten by mark values in qos_flows. #Default: # none # TAG: qos_flows # Allows you to select a TOS/DSCP value to mark outgoing -# connections with, based on where the reply was sourced. +# connections to the client, based on where the reply was sourced. +# For platforms using netfilter, allows you to set a netfilter mark +# value instead of, or in addition to, a TOS value. +# +# By default this functionality is disabled. To enable it with the default +# settings simply use "qos_flows mark" or "qos_flows tos". Default +# settings will result in the netfilter mark or TOS value being copied +# from the upstream connection to the client. Note that it is the connection +# CONNMARK value not the packet MARK value that is copied. +# +# It is not currently possible to copy the mark or TOS value from the +# client to the upstream connection request. # # TOS values really only have local significance - so you should # know what you're specifying. For more information, see RFC2474, # RFC2475, and RFC3260. # -# The TOS/DSCP byte must be exactly that - octet value 0x00-0xFF. -# Note that in practice often only values up to 0x3F are usable -# as the two highest bits have been redefined for use by ECN -# (RFC3168). +# The TOS/DSCP byte must be exactly that - a octet value 0 - 255. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. +# +# Mark values can be any unsigned 32-bit integer value. +# +# This setting is configured by setting the following values: # -# This setting is configured by setting the source TOS values: +# tos|mark Whether to set TOS or netfilter mark values # # local-hit=0xFF Value to mark local cache hits. # @@ -1328,23 +1946,37 @@ http_port 3128 # # parent-hit=0xFF Value to mark hits from parent peers. # +# miss=0xFF[/mask] Value to mark cache misses. Takes precedence +# over the preserve-miss feature (see below), unless +# mask is specified, in which case only the bits +# specified in the mask are written. # -# NOTE: 'miss' preserve feature is only possible on Linux at this time. -# -# For the following to work correctly, you will need to patch your -# linux kernel with the TOS preserving ZPH patch. -# The kernel patch can be downloaded from http://zph.bratcheda.org +# The TOS variant of the following features are only possible on Linux +# and require your kernel to be patched with the TOS preserving ZPH +# patch, available from http://zph.bratcheda.org +# No patch is needed to preserve the netfilter mark, which will work +# with all variants of netfilter. # # disable-preserve-miss -# By default, the existing TOS value of the response coming -# from the remote server will be retained and masked with -# miss-mark. This option disables that feature. +# This option disables the preservation of the TOS or netfilter +# mark. By default, the existing TOS or netfilter mark value of +# the response coming from the remote server will be retained +# and masked with miss-mark. +# NOTE: in the case of a netfilter mark, the mark must be set on +# the connection (using the CONNMARK target) not on the packet +# (MARK target). # # miss-mask=0xFF -# Allows you to mask certain bits in the TOS received from the -# remote server, before copying the value to the TOS sent -# towards clients. -# Default: 0xFF (TOS from server is not changed). +# Allows you to mask certain bits in the TOS or mark value +# received from the remote server, before copying the value to +# the TOS sent towards clients. +# Default for tos: 0xFF (TOS from server is not changed). +# Default for mark: 0xFFFFFFFF (mark from server is not changed). +# +# All of these features require the --enable-zph-qos compilation flag +# (enabled by default). Netfilter marking also requires the +# libnetfilter_conntrack libraries (--with-netfilter-conntrack) and +# libcap 2.09+ (--with-libcap). # #Default: # none @@ -1356,72 +1988,133 @@ http_port 3128 # # tcp_outgoing_address ipaddr [[!]aclname] ... # -# Example where requests from 10.0.0.0/24 will be forwarded -# with source address 10.1.0.1, 10.0.2.0/24 forwarded with -# source address 10.1.0.2 and the rest will be forwarded with -# source address 10.1.0.3. -# -# acl normal_service_net src 10.0.0.0/24 -# acl good_service_net src 10.0.2.0/24 -# tcp_outgoing_address 10.1.0.1 normal_service_net -# tcp_outgoing_address 10.1.0.2 good_service_net -# tcp_outgoing_address 10.1.0.3 -# -# Processing proceeds in the order specified, and stops at first fully -# matching line. -# -# Note: The use of this directive using client dependent ACLs is -# incompatible with the use of server side persistent connections. To -# ensure correct results it is best to set server_persistent_connections -# to off when using this directive in such configurations. -# +# For example; +# Forwarding clients with dedicated IPs for certain subnets. # -# IPv6 Magic: +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.2.0/24 # -# Squid is built with a capability of bridging the IPv4 and IPv6 -# internets. -# tcp_outgoing_address as exampled above breaks this bridging by forcing -# all outbound traffic through a certain IPv4 which may be on the wrong -# side of the IPv4/IPv6 boundary. +# tcp_outgoing_address 2001:db8::c001 good_service_net +# tcp_outgoing_address 10.1.0.2 good_service_net # -# To operate with tcp_outgoing_address and keep the bridging benefits -# an additional ACL needs to be used which ensures the IPv6-bound traffic -# is never forced or permitted out the IPv4 interface. +# tcp_outgoing_address 2001:db8::beef normal_service_net +# tcp_outgoing_address 10.1.0.1 normal_service_net # -# # IPv6 destination test along with a dummy access control to perform the required DNS -# # This MUST be place before any ALLOW rules. -# acl to_ipv6 dst ipv6 -# http_access deny ipv6 !all +# tcp_outgoing_address 2001:db8::1 +# tcp_outgoing_address 10.1.0.3 # -# tcp_outgoing_address 2001:db8::c001 good_service_net to_ipv6 -# tcp_outgoing_address 10.1.0.2 good_service_net !to_ipv6 +# Processing proceeds in the order specified, and stops at first fully +# matching line. # -# tcp_outgoing_address 2001:db8::beef normal_service_net to_ipv6 -# tcp_outgoing_address 10.1.0.1 normal_service_net !to_ipv6 +# Squid will add an implicit IP version test to each line. +# Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses. +# Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses. # -# tcp_outgoing_address 2001:db8::1 to_ipv6 -# tcp_outgoing_address 10.1.0.3 !to_ipv6 # -# WARNING: -# 'dst ipv6' bases its selection assuming DIRECT access. -# If peers are used the peername ACL are needed to select outgoing -# address which can link to the peer. +# NOTE: The use of this directive using client dependent ACLs is +# incompatible with the use of server side persistent connections. To +# ensure correct results it is best to set server_persistent_connections +# to off when using this directive in such configurations. # -# 'dst ipv6' is a slow ACL. It will only work here if 'dst' is used -# previously in the http_access rules to locate the destination IP. -# Some more magic may be needed for that: -# http_access allow to_ipv6 !all -# (meaning, allow if to IPv6 but not from anywhere ;) +# NOTE: The use of this directive to set a local IP on outgoing TCP links +# is incompatible with using TPROXY to set client IP out outbound TCP links. +# When needing to contact peers use the no-tproxy cache_peer option and the +# client_dst_passthru directive re-enable normal forwarding such as this. # #Default: -# none +# Address selection is performed by the operating system. + +# TAG: host_verify_strict +# Regardless of this option setting, when dealing with intercepted +# traffic, Squid always verifies that the destination IP address matches +# the Host header domain or IP (called 'authority form URL'). +# +# This enforcement is performed to satisfy a MUST-level requirement in +# RFC 2616 section 14.23: "The Host field value MUST represent the naming +# authority of the origin server or gateway given by the original URL". +# +# When set to ON: +# Squid always responds with an HTTP 409 (Conflict) error +# page and logs a security warning if there is no match. +# +# Squid verifies that the destination IP address matches +# the Host header for forward-proxy and reverse-proxy traffic +# as well. For those traffic types, Squid also enables the +# following checks, comparing the corresponding Host header +# and Request-URI components: +# +# * The host names (domain or IP) must be identical, +# but valueless or missing Host header disables all checks. +# For the two host names to match, both must be either IP +# or FQDN. +# +# * Port numbers must be identical, but if a port is missing +# the scheme-default port is assumed. +# +# +# When set to OFF (the default): +# Squid allows suspicious requests to continue but logs a +# security warning and blocks caching of the response. +# +# * Forward-proxy traffic is not checked at all. +# +# * Reverse-proxy traffic is not checked at all. +# +# * Intercepted traffic which passes verification is handled +# according to client_dst_passthru. +# +# * Intercepted requests which fail verification are sent +# to the client original destination instead of DIRECT. +# This overrides 'client_dst_passthru off'. +# +# For now suspicious intercepted CONNECT requests are always +# responded to with an HTTP 409 (Conflict) error page. +# +# +# SECURITY NOTE: +# +# As described in CVE-2009-0801 when the Host: header alone is used +# to determine the destination of a request it becomes trivial for +# malicious scripts on remote websites to bypass browser same-origin +# security policy and sandboxing protections. +# +# The cause of this is that such applets are allowed to perform their +# own HTTP stack, in which case the same-origin policy of the browser +# sandbox only verifies that the applet tries to contact the same IP +# as from where it was loaded at the IP level. The Host: header may +# be different from the connected IP and approved origin. +# +#Default: +# host_verify_strict off + +# TAG: client_dst_passthru +# With NAT or TPROXY intercepted traffic Squid may pass the request +# directly to the original client destination IP or seek a faster +# source using the HTTP Host header. +# +# Using Host to locate alternative servers can provide faster +# connectivity with a range of failure recovery options. +# But can also lead to connectivity trouble when the client and +# server are attempting stateful interactions unaware of the proxy. +# +# This option (on by default) prevents alternative DNS entries being +# located to send intercepted traffic DIRECT to an origin server. +# The clients original destination IP and port will be used instead. +# +# Regardless of this option setting, when dealing with intercepted +# traffic Squid will verify the Host: header and any traffic which +# fails Host verification will be treated as if this option were ON. +# +# see host_verify_strict for details on the verification process. +#Default: +# client_dst_passthru on # SSL OPTIONS # ----------------------------------------------------------------------------- # TAG: ssl_unclean_shutdown # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Some browsers (especially MSIE) bugs out on SSL shutdown # messages. @@ -1430,7 +2123,7 @@ http_port 3128 # TAG: ssl_engine # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # The OpenSSL engine to use. You will need to set this if you # would like to use hardware SSL acceleration for example. @@ -1439,7 +2132,7 @@ http_port 3128 # TAG: sslproxy_client_certificate # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Client SSL Certificate to use when proxying https:// URLs #Default: @@ -1447,7 +2140,7 @@ http_port 3128 # TAG: sslproxy_client_key # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Client SSL Key to use when proxying https:// URLs #Default: @@ -1455,36 +2148,60 @@ http_port 3128 # TAG: sslproxy_version # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # SSL version level to use when proxying https:// URLs +# +# The versions of SSL/TLS supported: +# +# 1 automatic (default) +# 2 SSLv2 only +# 3 SSLv3 only +# 4 TLSv1.0 only +# 5 TLSv1.1 only +# 6 TLSv1.2 only #Default: -# sslproxy_version 1 +# automatic SSL/TLS version negotiation # TAG: sslproxy_options # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# SSL engine options to use when proxying https:// URLs +# Colon (:) or comma (,) separated list of SSL implementation options +# to use when proxying https:// URLs # # The most important being: # -# NO_SSLv2 Disallow the use of SSLv2 -# NO_SSLv3 Disallow the use of SSLv3 -# NO_TLSv1 Disallow the use of TLSv1 -# SINGLE_DH_USE -# Always create a new key when using -# temporary/ephemeral DH key exchanges +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# +# SINGLE_DH_USE +# Always create a new key when using temporary/ephemeral +# DH key exchanges +# +# NO_TICKET +# Disable use of RFC5077 session tickets. Some servers +# may have problems understanding the TLS extension due +# to ambiguous specification in RFC4507. +# +# ALL Enable various bug workarounds suggested as "harmless" +# by OpenSSL. Be warned that this may reduce SSL/TLS +# strength to some attacks. # -# These options vary depending on your SSL engine. # See the OpenSSL SSL_CTX_set_options documentation for a # complete list of possible options. +# +# WARNING: This directive takes a single token. If a space is used +# the value(s) after that space are SILENTLY IGNORED. #Default: # none # TAG: sslproxy_cipher # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # SSL cipher list to use when proxying https:// URLs # @@ -1494,7 +2211,7 @@ http_port 3128 # TAG: sslproxy_cafile # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # file containing CA certificates to use when verifying server # certificates while proxying https:// URLs @@ -1503,45 +2220,151 @@ http_port 3128 # TAG: sslproxy_capath # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # directory containing CA certificates to use when verifying # server certificates while proxying https:// URLs #Default: # none -# TAG: ssl_bump +# TAG: sslproxy_session_ttl +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Sets the timeout value for SSL sessions +#Default: +# sslproxy_session_ttl 300 + +# TAG: sslproxy_session_cache_size +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Sets the cache size to use for ssl session +#Default: +# sslproxy_session_cache_size 2 MB + +# TAG: sslproxy_foreign_intermediate_certs +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Many origin servers fail to send their full server certificate +# chain for verification, assuming the client already has or can +# easily locate any missing intermediate certificates. +# +# Squid uses the certificates from the specified file to fill in +# these missing chains when trying to validate origin server +# certificate chains. +# +# The file is expected to contain zero or more PEM-encoded +# intermediate certificates. These certificates are not treated +# as trusted root certificates, and any self-signed certificate in +# this file will be ignored. +#Default: +# none + +# TAG: sslproxy_cert_sign_hash # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# This ACL controls which CONNECT requests to an http_port -# marked with an sslBump flag are actually "bumped". Please -# see the sslBump flag of an http_port option for more details -# about decoding proxied SSL connections. +# Sets the hashing algorithm to use when signing generated certificates. +# Valid algorithm names depend on the OpenSSL library used. The following +# names are usually available: sha1, sha256, sha512, and md5. Please see +# your OpenSSL library manual for the available hashes. By default, Squids +# that support this option use sha256 hashes. # -# By default, no requests are bumped. +# Squid does not forcefully purge cached certificates that were generated +# with an algorithm other than the currently configured one. They remain +# in the cache, subject to the regular cache eviction policy, and become +# useful if the algorithm changes again. +#Default: +# none + +# TAG: ssl_bump +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# This option is consulted when a CONNECT request is received on +# an http_port (or a new connection is intercepted at an +# https_port), provided that port was configured with an ssl-bump +# flag. The subsequent data on the connection is either treated as +# HTTPS and decrypted OR tunneled at TCP level without decryption, +# depending on the first matching bumping "action". +# +# ssl_bump <action> [!]acl ... +# +# The following bumping actions are currently supported: +# +# splice +# Become a TCP tunnel without decrypting proxied traffic. +# This is the default action. +# +# bump +# Establish a secure connection with the server and, using a +# mimicked server certificate, with the client. +# +# peek +# Receive client (step SslBump1) or server (step SslBump2) +# certificate while preserving the possibility of splicing the +# connection. Peeking at the server certificate (during step 2) +# usually precludes bumping of the connection at step 3. +# +# stare +# Receive client (step SslBump1) or server (step SslBump2) +# certificate while preserving the possibility of bumping the +# connection. Staring at the server certificate (during step 2) +# usually precludes splicing of the connection at step 3. +# +# terminate +# Close client and server connections. +# +# Backward compatibility actions available at step SslBump1: +# +# client-first +# Bump the connection. Establish a secure connection with the +# client first, then connect to the server. This old mode does +# not allow Squid to mimic server SSL certificate and does not +# work with intercepted SSL connections. +# +# server-first +# Bump the connection. Establish a secure connection with the +# server first, then establish a secure connection with the +# client, using a mimicked server certificate. Works with both +# CONNECT requests and intercepted SSL connections, but does +# not allow to make decisions based on SSL handshake info. +# +# peek-and-splice +# Decide whether to bump or splice the connection based on +# client-to-squid and server-to-squid SSL hello messages. +# XXX: Remove. +# +# none +# Same as the "splice" action. +# +# All ssl_bump rules are evaluated at each of the supported bumping +# steps. Rules with actions that are impossible at the current step are +# ignored. The first matching ssl_bump action wins and is applied at the +# end of the current step. If no rules match, the splice action is used. +# See the at_step ACL for a list of the supported SslBump steps. # -# See also: http_port ssl-bump -# # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # +# See also: http_port ssl-bump, https_port ssl-bump, and acl at_step. +# # -# # Example: Bump all requests except those originating from localhost and -# # those going to webax.com or example.com sites. +# # Example: Bump all TLS connections except those originating from +# # localhost or those going to example.com. # -# acl localhost src 127.0.0.1/32 -# acl broken_sites dstdomain .webax.com -# acl broken_sites dstdomain .example.com -# ssl_bump deny localhost -# ssl_bump deny broken_sites -# ssl_bump allow all +# acl broken_sites ssl::server_name .example.com +# ssl_bump splice localhost +# ssl_bump splice broken_sites +# ssl_bump bump all #Default: -# none +# Become a TCP tunnel without decrypting proxied traffic. # TAG: sslproxy_flags # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Various flags modifying the use of SSL while proxying https:// URLs: # DONT_VERIFY_PEER Accept certificates that fail verification. @@ -1553,16 +2376,16 @@ http_port 3128 # TAG: sslproxy_cert_error # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Use this ACL to bypass server certificate validation errors. # # For example, the following lines will bypass all validation errors -# when talking to servers located at 172.16.0.0/16. All other +# when talking to servers for example.com. All other # validation errors will result in ERR_SECURE_CONNECT_FAIL error. # -# acl BrokenServersAtTrustedIP dst 172.16.0.0/16 -# sslproxy_cert_error allow BrokenServersAtTrustedIP +# acl BrokenButTrustedServers dstdomain example.com +# sslproxy_cert_error allow BrokenButTrustedServers # sslproxy_cert_error deny all # # This clause only supports fast acl types. @@ -1570,19 +2393,107 @@ http_port 3128 # 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. +# +# SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed +# but should not happen unless your OpenSSL library is buggy. +# +# SECURITY WARNING: +# Bypassing validation errors is dangerous because an +# error usually implies that the server cannot be trusted +# and the connection may be insecure. # # See also: sslproxy_flags and DONT_VERIFY_PEER. +#Default: +# Server certificate errors terminate the transaction. + +# TAG: sslproxy_cert_sign +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# +# 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. # -# Default setting: sslproxy_cert_error deny all +# 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 +# browser. This is the default for self-signed origin server +# certificates (see ssl::certSelfSigned). +# +# This clause only supports fast acl types. +# +# When sslproxy_cert_sign acl(s) match, Squid uses the corresponding +# signing algorithm to generate the certificate and ignores all +# subsequent sslproxy_cert_sign options (the first match wins). If no +# acl(s) match, the default signing algorithm is determined by errors +# detected when obtaining and validating the origin server certificate. +# +# WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can +# be used with sslproxy_cert_adapt, but if and only if Squid is bumping a +# CONNECT request that carries a domain name. In all other cases (CONNECT +# to an IP address or an intercepted SSL connection), Squid cannot detect +# the domain mismatch at certificate generation time when +# bump-server-first is used. +#Default: +# none + +# TAG: sslproxy_cert_adapt +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# +# 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, +# extracted from the CONNECT request. It is a misconfiguration +# to use setCommonName without an explicit parameter for +# intercepted or tproxied SSL connections. +# +# This clause only supports fast acl types. +# +# Squid first groups sslproxy_cert_adapt options by adaptation algorithm. +# Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the +# corresponding adaptation algorithm to generate the certificate and +# ignores all subsequent sslproxy_cert_adapt options in that algorithm's +# group (i.e., the first match wins within each algorithm group). If no +# acl(s) match, the default mimicking action takes place. +# +# WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can +# be used with sslproxy_cert_adapt, but if and only if Squid is bumping a +# CONNECT request that carries a domain name. In all other cases (CONNECT +# to an IP address or an intercepted SSL connection), Squid cannot detect +# the domain mismatch at certificate generation time when +# bump-server-first is used. #Default: # none # TAG: sslpassword_program # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Specify a program used for entering SSL key passphrases # when using encrypted SSL certificate keys. If not specified @@ -1595,12 +2506,12 @@ http_port 3128 #Default: # none -#OPTIONS RELATING TO EXTERNAL SSL_CRTD -#----------------------------------------------------------------------------- +# OPTIONS RELATING TO EXTERNAL SSL_CRTD +# ----------------------------------------------------------------------------- # TAG: sslcrtd_program # Note: This option is only available if Squid is rebuilt with the -# -DUSE_SSL_CRTD define +# --enable-ssl-crtd # # Specify the location and options of the executable for ssl_crtd process. # /usr/lib/squid/ssl_crtd program requires -s and -M parameters @@ -1611,14 +2522,90 @@ http_port 3128 # TAG: sslcrtd_children # Note: This option is only available if Squid is rebuilt with the -# -DUSE_SSL_CRTD define +# --enable-ssl-crtd # # 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. +# # You must have at least one ssl_crtd process. #Default: -# sslcrtd_children 5 +# sslcrtd_children 32 startup=5 idle=1 + +# TAG: sslcrtvalidator_program +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# 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 +#Default: +# none + +# TAG: sslcrtvalidator_children +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# 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. A value of 0 indicates the certficate validator does not +# support concurrency. Defaults to 1. +# +# When this directive is set to a value >= 1 then the protocol +# used to communicate with the helper is modified to include +# a request ID in front of the request/response. The request +# ID from the request must be echoed back with the response +# to that request. +# +# You must have at least one ssl_crt_validator process. +#Default: +# sslcrtvalidator_children 32 startup=5 idle=1 concurrency=1 # OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM # ----------------------------------------------------------------------------- @@ -1680,22 +2667,23 @@ http_port 3128 # # htcp Send HTCP, instead of ICP, queries to the neighbor. # You probably also want to set the "icp-port" to 4827 -# instead of 3130. +# instead of 3130. This directive accepts a comma separated +# list of options described below. # -# htcp-oldsquid Send HTCP to old Squid versions. +# htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier). # -# htcp-no-clr Send HTCP to the neighbor but without +# htcp=no-clr Send HTCP to the neighbor but without # sending any CLR requests. This cannot be used with -# htcp-only-clr. +# only-clr. # -# htcp-only-clr Send HTCP to the neighbor but ONLY CLR requests. -# This cannot be used with htcp-no-clr. +# htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests. +# This cannot be used with no-clr. # -# htcp-no-purge-clr +# htcp=no-purge-clr # Send HTCP to the neighbor including CLRs but only when # they do not result from PURGE requests. # -# htcp-forward-clr +# htcp=forward-clr # Forward any HTCP CLR requests this proxy receives to the peer. # # @@ -1768,6 +2756,14 @@ http_port 3128 # than the Squid default location. # # +# ==== CARP OPTIONS ==== +# +# carp-key=key-specification +# use a different key than the full URL to hash against the peer. +# the key-specification is a comma-separated list of the keywords +# scheme, host, port, path, params +# Order is not important. +# # ==== ACCELERATOR / REVERSE-PROXY OPTIONS ==== # # originserver Causes this parent to be contacted as an origin server. @@ -1795,20 +2791,23 @@ http_port 3128 # Note: The string can include URL escapes (i.e. %20 for # spaces). This also means % must be written as %%. # -# login=PROXYPASS +# login=PASSTHRU # Send login details received from client to this peer. -# Authentication is not required, nor changed. +# Both Proxy- and WWW-Authorization headers are passed +# without alteration to the peer. +# Authentication is not required by Squid for this to work. # # Note: This will pass any form of authentication but # only Basic auth will work through a proxy unless the # connection-auth options are also used. -# +# # login=PASS Send login details received from client to this peer. # Authentication is not required by this option. +# # If there are no client-provided authentication headers # to pass on, but username and password are available -# from either proxy login or an external ACL user= and -# password= result tags they may be sent instead. +# from an external ACL user= and password= result tags +# they may be sent instead. # # Note: To combine this with proxy_auth both proxies must # share the same user database as HTTP only allows for @@ -1826,6 +2825,27 @@ http_port 3128 # be used to identify this proxy to the peer, similar to # the login=username:password option above. # +# login=NEGOTIATE +# If this is a personal/workgroup proxy and your parent +# requires a secure proxy authentication. +# The first principal from the default keytab or defined by +# the environment variable KRB5_KTNAME will be used. +# +# WARNING: The connection may transmit requests from multiple +# clients. Negotiate often assumes end-to-end authentication +# and a single-client. Which is not strictly true here. +# +# login=NEGOTIATE:principal_name +# If this is a personal/workgroup proxy and your parent +# requires a secure proxy authentication. +# The principal principal_name from the default keytab or +# defined by the environment variable KRB5_KTNAME will be +# used. +# +# WARNING: The connection may transmit requests from multiple +# clients. Negotiate often assumes end-to-end authentication +# and a single-client. Which is not strictly true here. +# # connection-auth=on|off # Tell Squid that this peer does or not support Microsoft # connection oriented authentication, and any such @@ -1848,22 +2868,42 @@ http_port 3128 # reference a combined file containing both the # certificate and the key. # -# sslversion=1|2|3|4 +# sslversion=1|2|3|4|5|6 # The SSL version to use when connecting to this peer # 1 = automatic (default) # 2 = SSL v2 only # 3 = SSL v3 only -# 4 = TLS v1 only +# 4 = TLS v1.0 only +# 5 = TLS v1.1 only +# 6 = TLS v1.2 only # # sslcipher=... The list of valid SSL ciphers to use when connecting # to this peer. # -# ssloptions=... Specify various SSL engine options: -# NO_SSLv2 Disallow the use of SSLv2 -# NO_SSLv3 Disallow the use of SSLv3 -# NO_TLSv1 Disallow the use of TLSv1 -# See src/ssl_support.c or the OpenSSL documentation for -# a more complete list. +# ssloptions=... Specify various SSL implementation options: +# +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# +# SINGLE_DH_USE +# Always create a new key when using +# temporary/ephemeral DH key exchanges +# +# NO_TICKET +# Disable use of RFC5077 session tickets. Some servers +# may have problems understanding the TLS extension due +# to ambiguous specification in RFC4507. +# +# ALL Enable various bug workarounds +# suggested as "harmless" by OpenSSL +# Be warned that this reduces SSL/TLS +# strength to some attacks. +# +# See the OpenSSL SSL_CTX_set_options documentation for a +# more complete list. # # sslcafile=... A file containing additional CA certificates to use # when verifying the peer certificate. @@ -1907,29 +2947,74 @@ http_port 3128 # # connect-fail-limit=N # How many times connecting to a peer must fail before -# it is marked as down. Default is 10. +# it is marked as down. Standby connection failures +# count towards this limit. Default is 10. # # allow-miss Disable Squid's use of only-if-cached when forwarding # requests to siblings. This is primarily useful when -# icp_hit_stale is used by the sibling. To extensive use -# of this option may result in forwarding loops, and you -# should avoid having two-way peerings with this option. -# For example to deny peer usage on requests from peer -# by denying cache_peer_access if the source is a peer. +# icp_hit_stale is used by the sibling. Excessive use +# of this option may result in forwarding loops. One way +# to prevent peering loops when using this option, is to +# deny cache peer usage on requests from a peer: +# acl fromPeer ... +# cache_peer_access peerName deny fromPeer +# +# max-conn=N Limit the number of concurrent connections the Squid +# may open to this peer, including already opened idle +# and standby connections. There is no peer-specific +# connection limit by default. +# +# A peer exceeding the limit is not used for new +# requests unless a standby connection is available. # -# max-conn=N Limit the amount of connections Squid may open to this -# peer. see also +# max-conn currently works poorly with idle persistent +# connections: When a peer reaches its max-conn limit, +# and there are idle persistent connections to the peer, +# the peer may not be selected because the limiting code +# does not know whether Squid can reuse those idle +# connections. +# +# standby=N Maintain a pool of N "hot standby" connections to an +# UP peer, available for requests when no idle +# persistent connection is available (or safe) to use. +# By default and with zero N, no such pool is maintained. +# N must not exceed the max-conn limit (if any). +# +# At start or after reconfiguration, Squid opens new TCP +# standby connections until there are N connections +# available and then replenishes the standby pool as +# opened connections are used up for requests. A used +# connection never goes back to the standby pool, but +# may go to the regular idle persistent connection pool +# shared by all peers and origin servers. +# +# Squid never opens multiple new standby connections +# concurrently. This one-at-a-time approach minimizes +# flooding-like effect on peers. Furthermore, just a few +# standby connections should be sufficient in most cases +# to supply most new requests with a ready-to-use +# connection. +# +# Standby connections obey server_idle_pconn_timeout. +# For the feature to work as intended, the peer must be +# configured to accept and keep them open longer than +# the idle timeout at the connecting Squid, to minimize +# race conditions typical to idle used persistent +# connections. Default request_timeout and +# server_idle_pconn_timeout values ensure such a +# configuration. # # name=xxx Unique name for the peer. # Required if you have multiple peers on the same host # but different ports. # This name can be used in cache_peer_access and similar -# directives to dentify the peer. +# directives to identify the peer. # Can be used by outgoing access controls through the # peername ACL type. # # 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. # @@ -1938,10 +3023,11 @@ http_port 3128 # TAG: cache_peer_domain # 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 # @@ -1966,33 +3052,57 @@ http_port 3128 # none # TAG: cache_peer_access -# Similar to 'cache_peer_domain' but provides more flexibility by -# using ACL elements. +# Restricts usage of cache_peer proxies. # -# cache_peer_access cache-host allow|deny [!]aclname ... +# Usage: +# cache_peer_access peer-name allow|deny [!]aclname ... +# +# For the required peer-name parameter, use either the value of the +# cache_peer name=value parameter or, if name=value is missing, the +# cache_peer hostname parameter. +# +# This directive narrows down the selection of peering candidates, but +# does not determine the order in which the selected candidates are +# contacted. That order is determined by the peer selection algorithms +# (see PEER SELECTION sections in the cache_peer documentation). +# +# If a deny rule matches, the corresponding peer will not be contacted +# for the current transaction -- Squid will not send ICP queries and +# will not forward HTTP requests to that peer. An allow match leaves +# the corresponding peer in the selection. The first match for a given +# peer wins for that peer. +# +# The relative order of cache_peer_access directives for the same peer +# matters. The relative order of any two cache_peer_access directives +# for different peers does not matter. To ease interpretation, it is a +# good idea to group cache_peer_access directives for the same peer +# together. +# +# A single cache_peer_access directive may be evaluated multiple times +# for a given transaction because individual peer selection algorithms +# may check it independently from each other. These redundant checks +# may be optimized away in future Squid versions. # -# The syntax is identical to 'http_access' and the other lists of -# ACL elements. See the comments for 'http_access' below, or -# the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl). +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# No peer usage restrictions. # TAG: neighbor_type_domain -# 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 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. #Default: -# none +# The peer type from cache_peer directive is used for all requests to that peer. # TAG: dead_peer_timeout (seconds) # This controls how long Squid waits to declare a peer cache @@ -2015,21 +3125,11 @@ http_port 3128 # TAG: forward_max_tries # Controls how many different forward paths Squid will try # before giving up. See also forward_timeout. +# +# NOTE: connect_retries (default: none) can make each of these +# possible forwarding paths be tried multiple times. #Default: -# forward_max_tries 10 - -# TAG: hierarchy_stoplist -# A list of words which, if found in a URL, cause the object to -# be handled directly by this cache. In other words, use this -# to not query neighbor caches for certain objects. You may -# list this option multiple times. -# -# Example: -# hierarchy_stoplist cgi-bin ? -# -# Note: never_direct overrides this option. -#Default: -# none +# forward_max_tries 25 # MEMORY CACHE OPTIONS # ----------------------------------------------------------------------------- @@ -2064,6 +3164,11 @@ http_port 3128 # decreases, blocks will be freed until the high-water mark is # reached. Thereafter, blocks will be used to store hot # objects. +# +# If shared memory caching is enabled, Squid does not use the shared +# cache space for in-transit objects, but they still consume as much +# local memory as they need. For more details about the shared memory +# cache, see memory_cache_shared. #Default: # cache_mem 256 MB @@ -2075,11 +3180,45 @@ http_port 3128 #Default: # maximum_object_size_in_memory 512 KB +# TAG: memory_cache_shared on|off +# Controls whether the memory cache is shared among SMP workers. +# +# The shared memory cache is meant to occupy cache_mem bytes and replace +# the non-shared memory cache, although some entities may still be +# cached locally by workers for now (e.g., internal and in-transit +# objects may be served from a local memory cache even if shared memory +# caching is enabled). +# +# By default, the memory cache is shared if and only if all of the +# following conditions are satisfied: Squid runs in SMP mode with +# multiple workers, cache_mem is positive, and Squid environment +# supports required IPC primitives (e.g., POSIX shared memory segments +# and GCC-style atomic operations). +# +# To avoid blocking locks, shared memory uses opportunistic algorithms +# that do not guarantee that every cachable entity that could have been +# shared among SMP workers will actually be shared. +#Default: +# "on" where supported if doing memory caching with multiple SMP workers. + +# TAG: memory_cache_mode +# Controls which objects to keep in the memory cache (cache_mem) +# +# always Keep most recently fetched objects in memory (default) +# +# disk Only disk cache hits are kept in memory, which means +# an object must first be cached on disk and then hit +# a second time before cached in memory. +# +# network Only objects fetched from network is kept in memory +#Default: +# Keep the most recently fetched objects in memory + # TAG: memory_replacement_policy # 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. #Default: # memory_replacement_policy lru @@ -2095,7 +3234,7 @@ http_port 3128 # 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. # @@ -2114,7 +3253,7 @@ http_port 3128 # 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 @@ -2123,10 +3262,34 @@ http_port 3128 #Default: # cache_replacement_policy lru +# TAG: minimum_object_size (bytes) +# Objects smaller than this size will NOT be saved on disk. The +# value is specified in bytes, and the default is 0 KB, which +# means all responses can be stored. +#Default: +# no limit + +# TAG: maximum_object_size (bytes) +# Set the default value for max-size parameter on any cache_dir. +# The value is specified in bytes, and the default is 4 MB. +# +# If you wish to get a high BYTES hit ratio, you should probably +# increase this (one 32 MB object hit counts for 3200 10KB +# hits). +# +# If you wish to increase hit ratio more than you want to +# save bandwidth you should leave this low. +# +# NOTE: if using the LFUDA replacement policy you should increase +# this value to maximize the byte hit rate improvement of LFUDA! +# See cache_replacement_policy for a discussion of this policy. +#Default: +# maximum_object_size 4 MB +maximum_object_size 153600 KB + # TAG: cache_dir -# 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. @@ -2141,12 +3304,18 @@ http_port 3128 # The directory must exist and be writable by the Squid # process. Squid will NOT create this directory for you. # -# The ufs store type: +# In SMP configurations, cache_dir must not precede the workers option +# and should use configuration macros or conditionals to give each +# worker interested in disk caching a dedicated cache directory. +# +# +# ==== 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 @@ -2161,23 +3330,27 @@ http_port 3128 # 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 # @@ -2195,37 +3368,78 @@ http_port 3128 # higher hit ratio at the expense of an increase in response # time. # -# 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. -# We hope that it can be made usable again soon. -# -# block-size=n defines the "block size" for COSS cache_dir's. -# Squid uses file numbers as block numbers. Since file numbers -# are limited to 24 bits, the block size determines the maximum -# size of the COSS partition. The default is 512 bytes, which -# leads to a maximum cache_dir size of 512<<24, or 8 GB. Note -# you should not change the coss block size after Squid -# has written some objects to the cache_dir. # -# The coss file store has changed from 2.5. Now it uses a file -# called 'stripe' in the directory names in the config - and -# this will be created by squid -z. +# ==== The rock store type ==== # -# Common options: -# -# no-store, no new objects should be stored to this cache_dir +# Usage: +# cache_dir rock Directory-Name Mbytes [options] +# +# The Rock Store type is a database-style storage. All cached +# entries are stored in a "database" file, using fixed-size slots. +# A single entry occupies one or more slots. +# +# 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 +# default and when set to zero, disables the disk I/O time limit +# enforcement. Ignored when using blocking I/O module because +# blocking synchronous I/O does not allow Squid to estimate the +# expected swap wait time. +# +# max-swap-rate=swaps/sec: Artificially limits disk access using +# the specified I/O rate limit. Swap out requests that +# would cause the average I/O rate to exceed the limit are +# delayed. Individual swap in requests (i.e., hits or reads) are +# not delayed, but they do contribute to measured swap rate and +# since they are placed in the same FIFO queue as swap out +# requests, they may wait longer if max-swap-rate is smaller. +# This is necessary on file systems that buffer "too +# many" writes and then start blocking Squid and other processes +# while committing those writes to disk. Usually used together +# with swap-timeout to avoid excessive delays and queue overflows +# when disk demand exceeds available disk "bandwidth". By default +# and when set to zero, disables the disk I/O rate limit +# enforcement. Currently supported by IpcIo module only. +# +# slot-size=bytes: The size of a database "record" used for +# storing cached responses. A cached response occupies at least +# one slot and all database I/O is done using individual slots so +# increasing this parameter leads to more disk space waste while +# decreasing it leads to more disk I/O overheads. Should be a +# multiple of your operating system I/O page size. Defaults to +# 16KBytes. A housekeeping header is stored with each slot and +# smaller slot-sizes will be rejected. The header is smaller than +# 100 bytes. +# +# +# ==== 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. Rock). +# Defaults to 0. +# +# max-size=n the maximum object size in bytes this cache_dir +# supports. +# The value in maximum_object_size directive sets +# the default unless more specific details are +# available (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. +#Default: +# No disk cache. Store cache ojects only in memory. # # Uncomment and adjust the following to add a disk cache directory. @@ -2233,7 +3447,60 @@ http_port 3128 cache_dir ufs /var/spool/squid 4096 16 1024 # TAG: store_dir_select_algorithm -# 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. +# +# If several cache_dirs use similar min-size, max-size, or other +# limits to to reject certain responses, then do not group such +# cache_dir lines together, to avoid round-robin selection bias +# towards the first cache_dir after the group. Instead, interleave +# cache_dir lines from different groups. For example: +# +# store_dir_select_algorithm round-robin +# cache_dir rock /hdd1 ... min-size=100000 +# cache_dir rock /ssd1 ... max-size=99999 +# cache_dir rock /hdd2 ... min-size=100000 +# cache_dir rock /ssd2 ... max-size=99999 +# cache_dir rock /hdd3 ... min-size=100000 +# cache_dir rock /ssd3 ... max-size=99999 #Default: # store_dir_select_algorithm least-load @@ -2244,46 +3511,53 @@ cache_dir ufs /var/spool/squid 4096 16 1024 # # A value of 0 indicates no limit. #Default: -# max_open_disk_fds 0 - -# TAG: minimum_object_size (bytes) -# 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. -#Default: -# minimum_object_size 0 KB - -# TAG: maximum_object_size (bytes) -# 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 -# increase this (one 32 MB object hit counts for 3200 10KB -# hits). If you wish to increase speed more than your want to -# save bandwidth you should leave this low. -# -# NOTE: if using the LFUDA replacement policy you should increase -# this value to maximize the byte hit rate improvement of LFUDA! -# See replacement_policy below for a discussion of this policy. -#Default: -# maximum_object_size 4096 KB -maximum_object_size 153600 KB +# no limit # TAG: cache_swap_low (percent, 0-100) +# The low-water mark for AUFS/UFS/diskd cache object eviction by +# the cache_replacement_policy algorithm. +# +# Removal begins when the swap (disk) usage of a cache_dir is +# above this low-water mark and attempts to maintain utilization +# near the low-water mark. +# +# As swap utilization increases towards the high-water mark set +# by cache_swap_high object eviction becomes more agressive. +# +# The value difference in percentages between low- and high-water +# marks represent an eviction rate of 300 objects per second and +# the rate continues to scale in agressiveness by multiples of +# this above the high-water mark. +# +# Defaults are 90% and 95%. If you have a large cache, 5% could be +# hundreds of MB. If this is the case you may wish to set these +# numbers closer together. +# +# See also cache_swap_high and cache_replacement_policy #Default: # cache_swap_low 90 # TAG: cache_swap_high (percent, 0-100) +# The high-water mark for AUFS/UFS/diskd cache object eviction by +# the cache_replacement_policy algorithm. +# +# Removal begins when the swap (disk) usage of a cache_dir is +# above the low-water mark set by cache_swap_low and attempts to +# maintain utilization near the low-water mark. # -# The low- and high-water marks 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. +# As swap utilization increases towards this high-water mark object +# eviction becomes more agressive. +# +# The value difference in percentages between low- and high-water +# marks represent an eviction rate of 300 objects per second and +# the rate continues to scale in agressiveness by multiples of +# this above the high-water mark. # # Defaults are 90% and 95%. If you have a large cache, 5% could be # hundreds of MB. If this is the case you may wish to set these # numbers closer together. +# +# See also cache_swap_low and cache_replacement_policy #Default: # cache_swap_high 95 @@ -2313,21 +3587,62 @@ maximum_object_size 153600 KB # ' output as-is # # - left aligned -# width field width. If starting with 0 the -# output is zero padded +# +# width minimum and/or maximum field width: +# [width_min][.width_max] +# When minimum starts with 0, the field is zero-padded. +# String values exceeding maximum width are truncated. +# # {arg} argument such as header name etc # # Format codes: # # % a literal % character +# sn Unique sequence number per log line entry +# 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 annotation specified by the argument. Also +# logs the adaptation meta headers set by the +# adaptation_meta configuration parameter. +# If no argument given all annotations logged. +# The argument may include a separator to use with +# annotation values: +# name[:separator] +# By default, multiple note values are separated with "," +# and multiple notes are separated with "\r\n". +# When logging named notes with %{name}note, the +# explicitly configured separator is used between note +# values. When logging all notes with %note, the +# explicitly configured separator is used between +# individual notes. There is currently no way to +# specify both value and notes separators when logging +# all notes with %note. +# +# Connection related format codes: +# # >a Client source IP address # >A Client FQDN # >p Client source port -# <A Server IP address or peer name -# la Local IP address (http_port) -# lp Local port number (http_port) +# >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier) +# >la Local IP address the client connected to +# >lp Local port number the client connected to +# >qos Client connection TOS/DSCP value set by Squid +# >nfmark Client connection netfilter mark set by Squid +# +# la Local listening IP address the client connection was connected to. +# lp Local listening port number the client connection was connected to. +# +# <a Server IP address of the last server or peer connection +# <A Server FQDN or peer name +# <p Server port number of the last server or peer connection # <la Local IP address of the last server or peer connection # <lp Local port number of the last server or peer connection +# <qos Server connection TOS/DSCP value set by Squid +# <nfmark Server connection netfilter mark set by Squid +# +# Time related format codes: +# # ts Seconds since epoch # tu subsecond time (milliseconds) # tl Local time. Optional strftime format argument @@ -2336,49 +3651,141 @@ maximum_object_size 153600 KB # default %d/%b/%Y:%H:%M:%S %z # tr Response time (milliseconds) # dt Total time spent making DNS lookups (milliseconds) +# tS Approximate master transaction start time in +# <full seconds since epoch>.<fractional seconds> format. +# Currently, Squid considers the master transaction +# started when a complete HTTP request header initiating +# the transaction is received from the client. This is +# the same value that Squid uses to calculate transaction +# response time when logging %tr to access.log. Currently, +# Squid uses millisecond resolution for %tS values, +# similar to the default access.log "current time" field +# (%ts.%03tu). +# +# Access Control related format codes: +# +# et Tag returned by external acl +# ea Log string returned by external acl +# un User name (any available) +# ul User name from authentication +# ue User name from external acl helper +# ui User name from ident +# un A user name. Expands to the first available name +# from the following list of information sources: +# - authenticated user name, like %ul +# - user name supplied by an external ACL, like %ue +# - SSL client name, like %us +# - ident user name, like %ui +# credentials Client credentials. The exact meaning depends on +# the authentication scheme: For Basic authentication, +# it is the password; for Digest, the realm sent by the +# client; for NTLM and Negotiate, the client challenge +# or client credentials prefixed with "YR " or "KK ". +# +# HTTP related format codes: +# +# REQUEST # -# HTTP cache 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::]rm Request method (GET/POST etc) +# [http::]>rm Request method from client +# [http::]<rm Request method sent to server or peer +# [http::]ru Request URL from client (historic, filtered for logging) +# [http::]>ru Request URL from client +# [http::]<ru Request URL sent to server or peer +# [http::]>rs Request URL scheme from client +# [http::]<rs Request URL scheme sent to server or peer +# [http::]>rd Request URL domain from client +# [http::]<rd Request URL domain sent to server or peer +# [http::]>rP Request URL port from client +# [http::]<rP Request URL port sent to server or peer +# [http::]rp Request URL path excluding hostname +# [http::]>rp Request URL path excluding hostname from client +# [http::]<rp Request URL path excluding hostname sent to server or peer +# [http::]rv Request protocol version +# [http::]>rv Request protocol version from client +# [http::]<rv Request protocol version sent to server or peer +# +# [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 +# +# +# RESPONSE +# +# [http::]<Hs HTTP status code received from the next hop +# [http::]>Hs HTTP status code sent to the client +# # [http::]<h Reply header. Optional header name argument # as for >h -# [http::]un User name -# [http::]ul User name from authentication -# [http::]ui User name from ident -# [http::]us User name from SSL -# [http::]ue User name from external acl helper -# [http::]>Hs HTTP status code sent to the client -# [http::]<Hs HTTP status code received from the next hop -# [http::]Ss Squid request status (TCP_MISS etc) -# [http::]Sh Squid hierarchy status (DEFAULT_PARENT etc) +# # [http::]mt MIME content type -# [http::]rm Request method (GET/POST etc) -# [http::]ru Request URL -# [http::]rp Request URL-Path excluding hostname -# [http::]rv Request protocol version -# [http::]et Tag returned by external acl -# [http::]ea Log string returned by external acl -# [http::]<st Sent reply size including HTTP headers -# [http::]>st Received request size including HTTP headers. In the -# case of chunked requests the chunked encoding metadata -# are not included -# [http::]>sh Received HTTP request headers size -# [http::]<sh Sent HTTP reply headers size -# [http::]st Request+Reply size including HTTP headers +# +# +# SIZE COUNTERS +# +# [http::]st Total size of request + reply traffic with client +# [http::]>st Total size of request received from client. +# Excluding chunked encoding bytes. +# [http::]<st Total size of reply sent to client (after adaptation) +# +# [http::]>sh Size of request headers received from client +# [http::]<sh Size of reply headers sent to client (after adaptation) +# # [http::]<sH Reply high offset sent # [http::]<sS Upstream object size +# +# [http::]<bs Number of HTTP-equivalent message body bytes +# received from the next hop, excluding chunked +# transfer encoding and control messages. +# Generated FTP/Gopher listings are treated as +# received bodies. +# +# +# TIMING +# # [http::]<pt Peer response time in milliseconds. The timer starts # when the last request byte is sent to the next hop # and stops when the last response byte is received. -# [http::]<tt Total server-side time in milliseconds. The timer +# [http::]<tt Total time in milliseconds. The timer # starts with the first connect request (or write I/O) # sent to the first selected peer. The timer stops # with the last I/O with the last peer. # -# If ICAP is enabled, the following two codes become available (as +# Squid handling related format codes: +# +# 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. +# +# ssl::>sni SSL client SNI sent to Squid. Available only +# after the peek, stare, or splice SSL bumping +# actions. +# +# If ICAP is enabled, the following code becomes available (as # well as ICAP log codes documented with the icap_log option): # # icap::tt Total ICAP processing time for the HTTP @@ -2386,14 +3793,13 @@ maximum_object_size 153600 KB # ACLs are checked and when ICAP # transaction is in progress. # -# icap::<last_h The header of the last ICAP response -# related to the HTTP transaction. Like -# <h, accepts an optional header name -# argument. Will not change semantics -# when multiple ICAP transactions per HTTP -# transaction are supported. +# If adaptation is enabled the following three codes become available: # -# If adaptation is enabled the following two codes become available: +# adapt::<last_h The header of the last ICAP response or +# meta-information from the last eCAP +# transaction related to the HTTP transaction. +# Like <h, accepts an optional header name +# argument. # # adapt::sum_trs Summed adaptation transaction response # times recorded as a comma-separated list in @@ -2417,43 +3823,118 @@ maximum_object_size 153600 KB # 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 -#logformat squidmime %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h] -#logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh -#logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh +#logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt +#logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh +#logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh +#logformat referrer %ts.%03tu %>a %{Referer}>h %ru +#logformat useragent %>a [%tl] "%{User-Agent}>h" +# +# NOTE: When the log_mime_hdrs directive is set to ON. +# The squid, common and combined formats have a safely encoded copy +# of the mime headers appended to each line within a pair of brackets. +# +# NOTE: The common and combined formats are not quite true to the Apache definition. +# The logs from Squid contain an extra status and hierarchy code appended. +# #Default: -# none +# The format definitions squid, common, combined, referrer, useragent are built in. # TAG: access_log -# These files log client request activities. Has a line every HTTP or -# ICP request. The format is: -# access_log <filepath> [<logformat name> [acl acl ...]] -# access_log none [acl acl ...]] +# 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: # -# Will log to the specified file 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). +# access_log <module>:<place> [option ...] [acl acl ...] +# access_log none [acl acl ...] # -# If no acl is specified, all requests will be logged to this file. +# The following directive format is accepted but may be deprecated: +# access_log <module>:<place> [<logformat name> [acl acl ...]] # -# To disable logging of a request use the filepath "none", in which case -# a logformat name should not be specified. +# 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. +# Do not specify Place or logformat name. +# +# stdio Write each log line to disk immediately at the completion of +# each request. +# Place: the filename and path to be written. +# +# daemon Very similar to stdio. But instead of writing to disk the log +# line is passed to a daemon helper for asychronous handling instead. +# Place: varies depending on the daemon. +# +# log_file_daemon Place: the file name and path to be written. +# +# syslog To log each request via syslog facility. +# Place: The syslog facility and priority level for these entries. +# Place Format: facility.priority # -# To log the request via syslog specify a filepath of "syslog": +# where facility could be any of: +# authpriv, daemon, local0 ... local7 or user. # -# access_log syslog[:facility.priority] [format [acl1 [acl2 ....]]] -# where facility could be any of: -# authpriv, daemon, local0 .. local7 or user. +# And priority could be any of: +# err, warning, notice, info, debug. +# +# udp To send each log line as text data to a UDP receiver. +# Place: The destination host name or IP and port. +# Place Format: //host:port # -# And priority could be any of: -# err, warning, notice, info, debug. +# 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 # # Default: -# access_log /var/log/squid/access.log squid +# access_log daemon:/var/log/squid/access.log squid #Default: -# access_log /var/log/squid/access.log squid +# access_log daemon:/var/log/squid/access.log squid # TAG: icap_log # ICAP log files record ICAP transaction summaries, one line per @@ -2472,13 +3953,35 @@ maximum_object_size 153600 KB # ICAP transaction log lines will correspond to a single access # log line. # -# ICAP log uses logformat codes that make sense for an ICAP -# transaction. Header-related codes are applied to the HTTP header -# embedded in an ICAP server response, with the following caveats: -# For REQMOD, there is no HTTP response header unless the ICAP -# server performed request satisfaction. For RESPMOD, the HTTP -# request header is the header sent to the ICAP server. For -# OPTIONS, there are no HTTP headers. +# ICAP log supports many access.log logformat %codes. In ICAP context, +# HTTP message-related %codes are applied to the HTTP message embedded +# in an ICAP message. Logformat "%http::>..." codes are used for HTTP +# messages embedded in ICAP requests while "%http::<..." codes are used +# for HTTP messages embedded in ICAP responses. For example: +# +# http::>h To-be-adapted HTTP message headers sent by Squid to +# the ICAP service. For REQMOD transactions, these are +# HTTP request headers. For RESPMOD, these are HTTP +# response headers, but Squid currently cannot log them +# (i.e., %http::>h will expand to "-" for RESPMOD). +# +# http::<h Adapted HTTP message headers sent by the ICAP +# service to Squid (i.e., HTTP request headers in regular +# REQMOD; HTTP response headers in RESPMOD and during +# request satisfaction in REQMOD). +# +# ICAP OPTIONS transactions do not embed HTTP messages. +# +# Several logformat codes below deal with ICAP message bodies. An ICAP +# message body, if any, typically includes a complete HTTP message +# (required HTTP headers plus optional HTTP message body). When +# computing HTTP message body size for these logformat codes, Squid +# either includes or excludes chunked encoding overheads; see +# code-specific documentation for details. +# +# For Secure ICAP services, all size-related information is currently +# computed before/after TLS encryption/decryption, as if TLS was not +# in use at all. # # The following format codes are also available for ICAP logs: # @@ -2492,12 +3995,16 @@ maximum_object_size 153600 KB # icap::rm ICAP request method (REQMOD, RESPMOD, or # OPTIONS). Similar to existing rm. # -# icap::>st Bytes sent to the ICAP server (TCP payload -# only; i.e., what Squid writes to the socket). +# icap::>st The total size of the ICAP request sent to the ICAP +# server (ICAP headers + ICAP body), including chunking +# metadata (if any). +# +# icap::<st The total size of the ICAP response received from the +# ICAP server (ICAP headers + ICAP body), including +# chunking metadata (if any). # -# icap::<st Bytes received from the ICAP server (TCP -# payload only; i.e., what Squid reads from -# the socket). +# icap::<bs The size of the ICAP response body received from the +# ICAP server, excluding chunking metadata (if any). # # icap::tr Transaction response time (in # milliseconds). The timer starts when @@ -2527,37 +4034,51 @@ maximum_object_size 153600 KB # The default ICAP log format, which can be used without an explicit # definition, is called icap_squid: # -#logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A - +#logformat icap_squid %ts.%03tu %6icap::tr %>A %icap::to/%03icap::Hs %icap::<st %icap::rm %icap::ru %un -/%icap::<A - # -# See also: logformat, log_icap, and %icap::<last_h +# See also: logformat and %adapt::<last_h #Default: # none -# TAG: log_access allow|deny acl acl... -# This options allows you to control which requests gets logged -# to access.log (see access_log directive). Requests denied for -# logging will also not be accounted for in performance counters. +# TAG: logfile_daemon +# Specify the path to the logfile-writing daemon. This daemon is +# used to write the access and store logs, if configured. # -# This clause only supports fast acl types. -# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# Squid sends a number of commands to the log daemon: +# L<data>\n - logfile data +# R\n - rotate file +# T\n - truncate file +# O\n - reopen file +# F\n - flush file +# r<n>\n - set rotate count to <n> +# b<n>\n - 1 = buffer output, 0 = don't buffer output +# +# No responses is expected. #Default: -# none +# logfile_daemon /usr/lib/squid/log_file_daemon -# TAG: log_icap -# This options allows you to control which requests get logged -# to icap.log. See the icap_log directive for ICAP log details. +# TAG: stats_collection allow|deny acl acl... +# This options allows you to control which requests gets accounted +# in performance counters. +# +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow logging for all transactions. # TAG: cache_store_log # 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 /var/log/squid/store.log +# cache_store_log stdio:/var/log/squid/store.log +# cache_store_log daemon:/var/log/squid/store.log #Default: # none @@ -2590,7 +4111,7 @@ maximum_object_size 153600 KB # them). We recommend you do NOT use this option. It is # better to keep these index files in each 'cache_dir' directory. #Default: -# none +# Store the journal inside its cache_dir # TAG: logfile_rotate # Specifies the number of logfile rotations to make when you @@ -2607,34 +4128,19 @@ maximum_object_size 153600 KB # 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. # -# Note2, for Debian/Linux the default of logfile_rotate is -# zero, since it includes external logfile-rotation methods. +# Note2, for Debian/Linux the default of logfile_rotate is +# zero, since it includes external logfile-rotation methods. #Default: # logfile_rotate 0 -# TAG: emulate_httpd_log on|off -# The Cache can emulate the log file format which many 'httpd' -# programs use. To disable/enable this emulation, set -# emulate_httpd_log to 'off' or 'on'. The default -# is to use the native log format since it includes useful -# information Squid-specific log analyzers use. -#Default: -# emulate_httpd_log off - -# TAG: log_ip_on_direct on|off -# Log the destination IP address in the hierarchy log tag when going -# direct. Earlier Squid versions logged the hostname here. If you -# prefer the old way set this to off. -#Default: -# log_ip_on_direct on - # TAG: mime_table -# 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. #Default: # mime_table /usr/share/squid/mime.conf @@ -2647,91 +4153,61 @@ maximum_object_size 153600 KB #Default: # log_mime_hdrs off -# TAG: useragent_log -# Note: This option is only available if Squid is rebuilt with the -# --enable-useragent-log option -# -# Squid will write the User-Agent field from HTTP requests -# to the filename specified here. By default useragent_log -# is disabled. -#Default: -# none - -# TAG: referer_log -# Note: This option is only available if Squid is rebuilt with the -# --enable-referer-log option -# -# Squid will write the Referer field from HTTP requests to the -# filename specified here. By default referer_log is disabled. -# Note that "referer" is actually a misspelling of "referrer" -# however the misspelt version has been accepted into the HTTP RFCs -# and we accept both. -#Default: -# none - # TAG: pid_filename # A filename to write the process-id to. To disable, enter "none". #Default: # pid_filename /var/run/squid.pid -# TAG: log_fqdn on|off -# Turn this on if you wish to log fully qualified domain names -# in the access.log. To do this Squid does a DNS lookup of all -# IP's connecting to it. This can (in some situations) increase -# latency, which makes your cache seem slower for interactive -# browsing. -#Default: -# log_fqdn off - # TAG: client_netmask # A netmask for client addresses in logfiles and cachemgr output. # Change this to protect the privacy of your cache clients. # A netmask of 255.255.255.0 will log all IP's in that range with # the last digit set to '0'. #Default: -# client_netmask no_addr - -# TAG: forward_log -# Note: This option is only available if Squid is rebuilt with the -# -DWIP_FWD_LOG define -# -# Logs the server-side requests. -# -# This is currently work in progress. -#Default: -# none +# Log full client IP address # TAG: strip_query_terms # 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. #Default: # strip_query_terms on # TAG: buffered_logs on|off -# 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. #Default: # buffered_logs off # TAG: netdb_filename -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option +# Where Squid stores it's netdb journal. +# When enabled this journal preserves netdb state between restarts. # -# A filename where Squid stores it's netdb state between restarts. # To disable, enter "none". #Default: -# netdb_filename /var/log/squid/netdb.state +# netdb_filename stdio:/var/log/squid/netdb.state # OPTIONS FOR TROUBLESHOOTING # ----------------------------------------------------------------------------- # TAG: cache_log -# 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" #Default: # cache_log /var/log/squid/cache.log @@ -2742,14 +4218,14 @@ maximum_object_size 153600 KB # 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. # For most uses a single log should be enough to monitor current # events affecting Squid. #Default: -# debug_options ALL,1 +# Log all critical and important messages. # TAG: coredump_dir # By default Squid leaves core files in the directory from where @@ -2758,7 +4234,7 @@ maximum_object_size 153600 KB # and coredump files will be left there. # #Default: -# coredump_dir none +# Use the directory from where Squid was started. # # Leave coredumps in the first cache dir @@ -2769,24 +4245,17 @@ coredump_dir /var/spool/squid # TAG: ftp_user # 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). #Default: # ftp_user Squid@ -# TAG: ftp_list_width -# Sets the width of ftp listings. This should be set to fit in -# the width of a standard browser. Setting this too small -# can cut off long filenames when browsing ftp sites. -#Default: -# ftp_list_width 32 - # TAG: ftp_passive # If your firewall does not allow Squid to use passive # connections, turn off this option. @@ -2822,13 +4291,21 @@ coredump_dir /var/spool/squid # and therefore, translation of the data portion of the segments # will never be needed. # -# Turning this OFF will prevent EPSV being attempted. -# WARNING: Doing so will convert Squid back to the old behavior with all -# the related problems with external NAT devices/layers. +# EPSV is often required to interoperate with FTP servers on IPv6 +# networks. On the other hand, it may break some IPv4 servers. +# +# By default, EPSV may try EPSV with any FTP server. To fine tune +# that decision, you may restrict EPSV to certain clients or servers +# using ACLs: # +# ftp_epsv allow|deny al1 acl2 ... +# +# WARNING: Disabling EPSV may cause problems with external NAT and IPv6. +# +# Only fast ACLs are supported. # Requires ftp_passive to be ON (default) for any effect. #Default: -# ftp_epsv on +# none # TAG: ftp_eprt # FTP Protocol extensions permit the use of a special "EPRT" command. @@ -2889,22 +4366,16 @@ coredump_dir /var/spool/squid # unlinkd_program /usr/lib/squid/unlinkd # TAG: pinger_program -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option -# # Specify the location of the executable for the pinger process. #Default: # pinger_program /usr/lib/squid/pinger # TAG: pinger_enable -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option -# # Control whether the pinger is active at run-time. # Enables turning ICMP pinger on and off with a simple # squid -k reconfigure. #Default: -# pinger_enable off +# pinger_enable on # OPTIONS FOR URL REWRITING # ----------------------------------------------------------------------------- @@ -2915,68 +4386,137 @@ coredump_dir /var/spool/squid # # 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> extras]<NL> +# +# See url_rewrite_extras on how to send "extras" with optional values to +# the helper. +# After processing the request the helper must reply using the following format: +# +# [channel-ID <SP>] result [<SP> kv-pairs] +# +# The result code can be: # -# In the future, the rewriter interface will be extended with -# key=value pairs ("kvpairs" shown above). Rewriter programs -# should be prepared to receive and possibly ignore additional -# whitespace-separated tokens on each input line. +# 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. +# +# OK +# When neither of url= and rewrite-url= are sent Squid does +# not change the URL. +# +# ERR +# Do not change the URL. +# +# BH +# An internal error occurred in the helper, preventing +# a result being identified. The 'message=' key name is +# reserved for delivering a log message. +# +# +# In addition to the above kv-pairs Squid also understands the following +# optional kv-pairs received from URL rewriters: +# clt_conn_tag=TAG +# Associates a TAG with the client TCP connection. +# The TAG is treated as a regular annotation but persists across +# future requests on the client connection rather than just the +# current request. A helper may update the TAG during subsequent +# requests be returning a new kv-pair. +# +# 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. # -# 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). +# WARNING: URL re-writing ability should be avoided whenever possible. +# Use the URL redirect form of response instead. # -# 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. +# 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. #Default: # none # TAG: url_rewrite_children -# The number of redirector processes to spawn. If you start -# too few Squid will have to wait for them to process a backlog of -# URLs, slowing it down. If you start too many they will use RAM -# and other system resources. -#Default: -# url_rewrite_children 5 - -# TAG: url_rewrite_concurrency +# The maximum number of redirector processes to spawn. If you limit +# it too few Squid will have to wait for them to process a backlog of +# URLs, 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 redirector helper can handle in # parallel. Defaults to 0 which indicates the redirector # 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. +# an ID in front of the request/response. The ID from the request +# must be echoed back with the response to that request. #Default: -# url_rewrite_concurrency 0 +# url_rewrite_children 20 startup=0 idle=1 concurrency=0 # TAG: url_rewrite_host_header -# By default Squid rewrites any Host: header in redirected -# requests. If you are running an accelerator this may -# not be a wanted effect of a redirector. -# +# To preserve same-origin security policies in browsers and +# prevent Host: header forgery by redirectors Squid rewrites +# any Host: header in redirected requests. +# +# If you are running an accelerator this may not be a wanted +# effect of a redirector. This directive enables you disable +# Host: alteration in reverse-proxy traffic. +# # WARNING: Entries are cached on the result of the URL rewriting # process, so be careful if you have domain-virtual hosts. +# +# WARNING: Squid and other software verifies the URL and Host +# are matching, so be careful not to relay through other proxies +# or inspecting firewalls with this disabled. #Default: # url_rewrite_host_header on # TAG: url_rewrite_access # 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: -# none +# Allow, unless rules exist in squid.conf. # TAG: url_rewrite_bypass # 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 @@ -2987,23 +4527,231 @@ coredump_dir /var/spool/squid #Default: # url_rewrite_bypass off -# OPTIONS FOR TUNING THE CACHE +# TAG: url_rewrite_extras +# Specifies a string to be append to request line format for the +# rewriter helper. "Quoted" format values may contain spaces and +# logformat %macros. In theory, any logformat %macro can be used. +# In practice, a %macro expands as a dash (-) if the helper request is +# sent before the required macro information is available to Squid. +#Default: +# url_rewrite_extras "%>a/%>A %un %>rm myip=%la myport=%lp" + +# OPTIONS FOR STORE ID # ----------------------------------------------------------------------------- -# TAG: cache -# A list of ACL elements which, if matched and denied, cause the request to -# not be satisfied from the cache and the reply to not be cached. -# In other words, use this to force certain objects to never be cached. +# TAG: store_id_program +# 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> extras]<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. +# +# In addition to the above kv-pairs Squid also understands the following +# optional kv-pairs received from URL rewriters: +# clt_conn_tag=TAG +# Associates a TAG with the client TCP connection. +# Please see url_rewrite_program related documentation for this +# kv-pair +# +# Helper programs should be prepared to receive and possibly ignore +# additional whitespace-separated tokens on each input line. # -# You must use the words 'allow' or 'deny' to indicate whether items -# matching the ACL should be allowed or denied into the cache. +# 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. +#Default: +# none + +# TAG: store_id_extras +# Specifies a string to be append to request line format for the +# StoreId helper. "Quoted" format values may contain spaces and +# logformat %macros. In theory, any logformat %macro can be used. +# In practice, a %macro expands as a dash (-) if the helper request is +# sent before the required macro information is available to Squid. +#Default: +# store_id_extras "%>a/%>A %un %>rm myip=%la myport=%lp" + +# TAG: store_id_children +# 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. # -# Default is to allow all to be cached. +# 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. +#Default: +# store_id_children 20 startup=0 idle=1 concurrency=0 + +# TAG: store_id_access +# 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. #Default: -# none +# Allow, unless rules exist in squid.conf. + +# TAG: store_id_bypass +# 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. +#Default: +# store_id_bypass on + +# OPTIONS FOR TUNING THE CACHE +# ----------------------------------------------------------------------------- + +# TAG: cache +# Requests denied by this directive will not be served from the cache +# and their responses will not be stored in the cache. This directive +# has no effect on other transactions and on already cached responses. +# +# This clause supports both fast and slow acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# +# This and the two other similar caching directives listed below are +# checked at different transaction processing stages, have different +# access to response information, affect different cache operations, +# and differ in slow ACLs support: +# +# * cache: Checked before Squid makes a hit/miss determination. +# No access to reply information! +# Denies both serving a hit and storing a miss. +# Supports both fast and slow ACLs. +# * send_hit: Checked after a hit was detected. +# Has access to reply (hit) information. +# Denies serving a hit only. +# Supports fast ACLs only. +# * store_miss: Checked before storing a cachable miss. +# Has access to reply (miss) information. +# Denies storing a miss only. +# Supports fast ACLs only. +# +# If you are not sure which of the three directives to use, apply the +# following decision logic: +# +# * If your ACL(s) are of slow type _and_ need response info, redesign. +# Squid does not support that particular combination at this time. +# Otherwise: +# * If your directive ACL(s) are of slow type, use "cache"; and/or +# * if your directive ACL(s) need no response info, use "cache". +# Otherwise: +# * If you do not want the response cached, use store_miss; and/or +# * if you do not want a hit on a cached response, use send_hit. +#Default: +# By default, this directive is unused and has no effect. + +# TAG: send_hit +# Responses denied by this directive will not be served from the cache +# (but may still be cached, see store_miss). This directive has no +# effect on the responses it allows and on the cached objects. +# +# Please see the "cache" directive for a summary of differences among +# store_miss, send_hit, and cache directives. +# +# Unlike the "cache" directive, send_hit only supports fast acl +# types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# +# For example: +# +# # apply custom Store ID mapping to some URLs +# acl MapMe dstdomain .c.example.com +# store_id_program ... +# store_id_access allow MapMe +# +# # but prevent caching of special responses +# # such as 302 redirects that cause StoreID loops +# acl Ordinary http_status 200-299 +# store_miss deny MapMe !Ordinary +# +# # and do not serve any previously stored special responses +# # from the cache (in case they were already cached before +# # the above store_miss rule was in effect). +# send_hit deny MapMe !Ordinary +#Default: +# By default, this directive is unused and has no effect. + +# TAG: store_miss +# Responses denied by this directive will not be cached (but may still +# be served from the cache, see send_hit). This directive has no +# effect on the responses it allows and on the already cached responses. +# +# Please see the "cache" directive for a summary of differences among +# store_miss, send_hit, and cache directives. See the +# send_hit directive for a usage example. +# +# Unlike the "cache" directive, store_miss only supports fast acl +# types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +#Default: +# By default, this directive is unused and has no effect. + +# TAG: max_stale time-units +# This option puts an upper limit on how stale content Squid +# will serve from the cache if cache validation fails. +# Can be overriden by the refresh_pattern max-stale option. +#Default: +# max_stale 1 week # TAG: refresh_pattern # usage: refresh_pattern [-i] regex min percent max [options] @@ -3028,12 +4776,13 @@ coredump_dir /var/spool/squid # override-lastmod # reload-into-ims # ignore-reload -# ignore-no-cache # ignore-no-store # ignore-must-revalidate # ignore-private # ignore-auth +# max-stale=NN # refresh-ims +# store-stale # # override-expire enforces min age even if the server # sent an explicit expiry time (e.g., with the @@ -3049,22 +4798,18 @@ coredump_dir /var/spool/squid # override-lastmod enforces min age even on objects # that were modified recently. # -# reload-into-ims changes client no-cache or ``reload'' -# to If-Modified-Since requests. Doing this VIOLATES the -# HTTP standard. Enabling this feature could make you -# liable for problems which it causes. +# reload-into-ims changes a client no-cache or ``reload'' +# request for a cached entry into a conditional request using +# If-Modified-Since and/or If-None-Match headers, provided the +# cached entry has a Last-Modified and/or a strong ETag header. +# Doing this VIOLATES the HTTP standard. Enabling this feature +# could make you liable for problems which it causes. # # ignore-reload ignores a client no-cache or ``reload'' # header. Doing this VIOLATES the HTTP standard. Enabling # 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 @@ -3091,9 +4836,19 @@ coredump_dir /var/spool/squid # ensures that the client will receive an updated version # if one is available. # +# store-stale stores responses even if they don't have explicit +# freshness or a validator (i.e., Last-Modified or an ETag) +# present, or if they're already stale. By default, Squid will +# not cache such responses because they usually can't be +# reused. Note that such responses will be stale by default. +# +# max-stale=NN provide a maximum staleness factor. Squid won't +# serve objects more stale than this even if it failed to +# validate the object. Default: use the max_stale global limit. +# # Basically a cached object is: # -# FRESH if expires < now, else STALE +# FRESH if expire > now, else STALE # STALE if age > max # FRESH if lm-factor < percent, else STALE # FRESH if age < min @@ -3109,7 +4864,9 @@ coredump_dir /var/spool/squid # # +# # 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 @@ -3137,7 +4894,7 @@ refresh_pattern . 0 20% 4320 # downloads. # # When the user aborts a request, Squid will check the -# quick_abort values to the amount of data transfered until +# quick_abort values to the amount of data transferred until # then. # # If the transfer has less than 'quick_abort_min' KB remaining, @@ -3195,44 +4952,68 @@ refresh_pattern . 0 20% 4320 #Default: # negative_dns_ttl 1 minutes -# TAG: range_offset_limit (bytes) -# Sets a upper limit on how far into the the file a Range request -# may be to cause Squid to prefetch the whole file. If beyond this -# limit Squid forwards the Range request as it is and the result -# is NOT cached. -# +# TAG: range_offset_limit size [acl acl...] +# usage: (size) [units] [[!]aclname] +# +# Sets an upper limit on how far (number of bytes) into the file +# a Range request may be to cause Squid to prefetch the whole file. +# If beyond this limit, Squid forwards the Range request as it is and +# the result is NOT cached. +# # This is to stop a far ahead range request (lets say start at 17MB) # from making Squid fetch the whole object up to that point before # sending anything to the client. -# -# A value of 0 causes Squid to never fetch more than the +# +# Multiple range_offset_limit lines may be specified, and they will +# be searched from top to bottom on each request until a match is found. +# The first match found will be used. If no line matches a request, the +# default limit of 0 bytes will be used. +# +# 'size' is the limit specified as a number of units. +# +# 'units' specifies whether to use bytes, KB, MB, etc. +# If no units are specified bytes are assumed. +# +# A size of 0 causes Squid to never fetch more than the # client requested. (default) -# -# A value of -1 causes Squid to always fetch the object from the +# +# A size of 'none' causes Squid to always fetch the object from the # beginning so it may cache the result. (2.0 style) -# -# NP: Using -1 here will override any quick_abort settings that may -# otherwise apply to the range request. The range request will +# +# 'aclname' is the name of a defined ACL. +# +# NP: Using 'none' as the byte value here will override any quick_abort settings +# that may otherwise apply to the range request. The range request will # be fully fetched from start to finish regardless of the client # actions. This affects bandwidth usage. #Default: -# range_offset_limit 0 KB +# none # TAG: minimum_expiry_time (seconds) # 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. #Default: # minimum_expiry_time 60 seconds -# TAG: store_avg_object_size (kbytes) +# TAG: store_avg_object_size (bytes) # 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. #Default: # store_avg_object_size 13 KB @@ -3271,8 +5052,11 @@ refresh_pattern . 0 20% 4320 # 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. #Default: -# request_body_max_size 0 KB +# No limit. # TAG: client_request_buffer_max_size (bytes) # This specifies the maximum buffer size of a client request. @@ -3281,29 +5065,6 @@ refresh_pattern . 0 20% 4320 #Default: # client_request_buffer_max_size 512 KB -# TAG: chunked_request_body_max_size (bytes) -# A broken or confused HTTP/1.1 client may send a chunked HTTP -# request to Squid. Squid does not have full support for that -# feature yet. To cope with such requests, Squid buffers the -# entire request and then dechunks request body to create a -# plain HTTP/1.0 request with a known content length. The plain -# request is then used by the rest of Squid code as usual. -# -# The option value specifies the maximum size of the buffer used -# to hold the request before the conversion. If the chunked -# request size exceeds the specified limit, the conversion -# fails, and the client receives an "unsupported request" error, -# as if dechunking was disabled. -# -# Dechunking is enabled by default. To disable conversion of -# chunked requests, set the maximum to zero. -# -# Request dechunking feature and this option in particular are a -# temporary hack. When chunking requests and responses are fully -# supported, there will be no need to buffer a chunked request. -#Default: -# chunked_request_body_max_size 64 KB - # TAG: broken_posts # A list of ACL elements which, if matched, causes Squid to send # an extra CRLF pair after the body of a PUT/POST request. @@ -3325,15 +5086,15 @@ refresh_pattern . 0 20% 4320 # acl buggy_server url_regex ^http://.... # broken_posts allow buggy_server #Default: -# none +# Obey RFC 2616. -# TAG: icap_uses_indirect_client on|off +# TAG: adaptation_uses_indirect_client on|off # Controls whether the indirect client IP address (instead of the direct # client IP address) is passed to adaptation services. # # See also: follow_x_forwarded_for adaptation_send_client_ip #Default: -# icap_uses_indirect_client on +# adaptation_uses_indirect_client on # TAG: via on|off # If set (default), Squid will include a Via header in requests and @@ -3395,64 +5156,62 @@ refresh_pattern . 0 20% 4320 # # 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). #Default: -# none +# No limits. # TAG: reply_header_access # Usage: reply_header_access header_name allow|deny [!]aclname ... @@ -3465,25 +5224,13 @@ refresh_pattern . 0 20% 4320 # 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 # @@ -3491,9 +5238,7 @@ refresh_pattern . 0 20% 4320 # 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 @@ -3501,29 +5246,22 @@ refresh_pattern . 0 20% 4320 # 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). #Default: -# none +# No limits. # TAG: request_header_replace # Usage: request_header_replace header_name message @@ -3531,8 +5269,7 @@ refresh_pattern . 0 20% 4320 # # 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. # @@ -3554,6 +5291,57 @@ refresh_pattern . 0 20% 4320 #Default: # none +# TAG: request_header_add +# 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. +#Default: +# none + +# TAG: note +# 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 ... +#Default: +# none + # TAG: relaxed_header_parser on|off|warn # In the default "on" setting Squid accepts certain forms # of non-compliant HTTP messages where it is unambiguous @@ -3569,15 +5357,32 @@ refresh_pattern . 0 20% 4320 #Default: # relaxed_header_parser on -# TAG: ignore_expect_100 on|off -# This option makes Squid ignore any Expect: 100-continue header present -# in the request. RFC 2616 requires that Squid being unable to satisfy -# the response expectation MUST return a 417 error. -# -# Note: Enabling this is a HTTP protocol violation, but some clients may -# not handle it well.. -#Default: -# ignore_expect_100 off +# TAG: collapsed_forwarding (on|off) +# When enabled, instead of forwarding each concurrent request for +# the same URL, Squid just sends the first of them. The other, so +# called "collapsed" requests, wait for the response to the first +# request and, if it happens to be cachable, use that response. +# Here, "concurrent requests" means "received after the first +# request headers were parsed and before the corresponding response +# headers were parsed". +# +# This feature is disabled by default: enabling collapsed +# forwarding needlessly delays forwarding requests that look +# cachable (when they are collapsed) but then need to be forwarded +# individually anyway because they end up being for uncachable +# content. However, in some cases, such as acceleration of highly +# cachable content with periodic or grouped expiration times, the +# gains from collapsing [large volumes of simultaneous refresh +# requests] outweigh losses from such delays. +# +# Squid collapses two kinds of requests: regular client requests +# received on one of the listening ports and internal "cache +# revalidation" requests which are triggered by those regular +# requests hitting a stale cached object. Revalidation collapsing +# is currently disabled for Squid instances containing SMP-aware +# disk or memory caches and for Vary-controlled cached objects. +#Default: +# collapsed_forwarding off # TIMEOUTS # ----------------------------------------------------------------------------- @@ -3604,25 +5409,46 @@ refresh_pattern . 0 20% 4320 # peer_connect_timeout 30 seconds # TAG: read_timeout time-units -# The read_timeout is applied on server-side connections. After -# each successful read(), the timeout will be extended by this +# Applied on peer server connections. +# +# After each successful read(), the timeout will be extended by this # amount. If no data is read again after this amount of time, -# the request is aborted and logged with ERR_READ_TIMEOUT. The -# default is 15 minutes. +# the request is aborted and logged with ERR_READ_TIMEOUT. +# +# The default is 15 minutes. #Default: # read_timeout 15 minutes +# TAG: write_timeout time-units +# This timeout is tracked for all connections that have data +# available for writing and are waiting for the socket to become +# ready. After each successful write, the timeout is extended by +# the configured amount. If Squid has data to write but the +# connection is not ready for the configured duration, the +# transaction associated with the connection is terminated. The +# default is 15 minutes. +#Default: +# write_timeout 15 minutes + # TAG: request_timeout # How long to wait for complete HTTP request headers after initial # connection establishment. #Default: # request_timeout 5 minutes -# TAG: persistent_request_timeout +# TAG: client_idle_pconn_timeout # How long to wait for the next HTTP request on a persistent -# connection after the previous request completes. +# client connection after the previous request completes. +#Default: +# client_idle_pconn_timeout 2 minutes + +# TAG: ftp_client_idle_timeout +# How long to wait for an FTP request on a connection to Squid ftp_port. +# Many FTP clients do not deal with idle connection closures well, +# necessitating a longer default timeout than client_idle_pconn_timeout +# used for incoming HTTP requests. #Default: -# persistent_request_timeout 2 minutes +# ftp_client_idle_timeout 30 minutes # TAG: client_lifetime time-units # The maximum amount of time a client (browser) is allowed to @@ -3658,11 +5484,11 @@ refresh_pattern . 0 20% 4320 #Default: # half_closed_clients off -# TAG: pconn_timeout +# TAG: server_idle_pconn_timeout # Timeout for idle persistent connections to servers and other # proxies. #Default: -# pconn_timeout 1 minute +# server_idle_pconn_timeout 1 minute # TAG: ident_timeout # Maximum time to wait for IDENT lookups to complete. @@ -3687,15 +5513,15 @@ refresh_pattern . 0 20% 4320 # TAG: cache_mgr # 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". #Default: # cache_mgr webmaster # TAG: mail_from # 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. #Default: # none @@ -3734,7 +5560,7 @@ refresh_pattern . 0 20% 4320 # Our preference is for administrators to configure a secure # user account for squid with UID/GID matching system policies. #Default: -# none +# Use system group memberships of the cache_effective_user account # TAG: httpd_suppress_version_string on|off # Suppress Squid version string info in HTTP headers and HTML error pages. @@ -3748,14 +5574,14 @@ refresh_pattern . 0 20% 4320 # get errors about IP-forwarding you must set them to have individual # names with this setting. #Default: -# visible_hostname localhost +# Automatically detect the system host name # TAG: unique_hostname # If you want to have multiple machines with the same # 'visible_hostname' you must give each machine a different # 'unique_hostname' so forwarding loops can be detected. #Default: -# none +# Copy the value from visible_hostname # TAG: hostname_aliases # A list of other DNS names your cache has. @@ -3794,33 +5620,32 @@ refresh_pattern . 0 20% 4320 # available on the Web at http://www.ircache.net/Cache/Tracker/. # TAG: announce_period -# 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. # # Example: # announce_period 1 day #Default: -# announce_period 0 +# Announcement messages disabled. # TAG: announce_host +# Set the hostname where announce registration messages will be sent. +# +# See also announce_port and announce_file #Default: # announce_host tracker.ircache.net # TAG: announce_file +# The contents of this file will be included in the announce +# registration messages. #Default: # none # TAG: announce_port -# 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 #Default: # announce_port 3131 @@ -3833,10 +5658,12 @@ refresh_pattern . 0 20% 4320 # a farm of surrogates may all perform the same tasks, they may share # an identification token. #Default: -# httpd_accel_surrogate_id unset-id +# visible_hostname is used if no specific ID is set. # TAG: http_accel_surrogate_remote on|off -# 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. #Default: # http_accel_surrogate_remote off @@ -3855,6 +5682,9 @@ refresh_pattern . 0 20% 4320 # 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. #Default: # delay_pools 0 @@ -3907,6 +5737,11 @@ refresh_pattern . 0 20% 4320 # # 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. #Default: # none @@ -3921,14 +5756,16 @@ refresh_pattern . 0 20% 4320 # 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. +# #Default: -# none +# Deny using the pool, unless allow rules exist in squid.conf for the pool. # TAG: delay_parameters # This defines the parameters for a delay pool. Each delay pool has @@ -3936,23 +5773,23 @@ refresh_pattern . 0 20% 4320 # description of delay_class. # # For a class 1 delay pool, the syntax is: -# delay_pools pool 1 +# delay_class pool 1 # delay_parameters pool aggregate # # For a class 2 delay pool: -# delay_pools pool 2 +# delay_class pool 2 # delay_parameters pool aggregate individual # # For a class 3 delay pool: -# delay_pools pool 3 +# delay_class pool 3 # delay_parameters pool aggregate network individual # # For a class 4 delay pool: -# delay_pools pool 4 +# delay_class pool 4 # delay_parameters pool aggregate network individual user # # For a class 5 delay pool: -# delay_pools pool 5 +# delay_class pool 5 # delay_parameters pool tagrate # # The option variables are: @@ -3988,11 +5825,11 @@ refresh_pattern . 0 20% 4320 # above example, and is being used to strictly limit each host to 64Kbit/sec # (plus overheads), with no overall limit, the line is: # -# delay_parameters 1 -1/-1 8000/8000 +# delay_parameters 1 none 8000/8000 # -# Note that 8 x 8000 KByte/sec -> 64Kbit/sec. +# Note that 8 x 8K Byte/sec -> 64K bit/sec. # -# Note that the figure -1 is used to represent "unlimited". +# Note that the word 'none' is used to represent no limit. # # # And, if delay pool number 2 is a class 3 delay pool as in the above @@ -4005,15 +5842,19 @@ refresh_pattern . 0 20% 4320 # # delay_parameters 2 32000/32000 8000/8000 600/8000 # -# Note that 8 x 32000 KByte/sec -> 256Kbit/sec. -# 8 x 8000 KByte/sec -> 64Kbit/sec. -# 8 x 600 Byte/sec -> 4800bit/sec. +# Note that 8 x 32K Byte/sec -> 256K bit/sec. +# 8 x 8K Byte/sec -> 64K bit/sec. +# 8 x 600 Byte/sec -> 4800 bit/sec. # # # Finally, for a class 4 delay pool as in the example - each user will # 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. +# #Default: # none @@ -4026,6 +5867,94 @@ refresh_pattern . 0 20% 4320 #Default: # delay_initial_bucket_level 50 +# CLIENT DELAY POOL PARAMETERS +# ----------------------------------------------------------------------------- + +# TAG: client_delay_pools +# This option specifies the number of client delay pools used. It must +# preceed other client_delay_* options. +# +# Example: +# client_delay_pools 2 +# +# See also client_delay_parameters and client_delay_access. +#Default: +# client_delay_pools 0 + +# TAG: client_delay_initial_bucket_level (percent, 0-no_limit) +# This option determines the initial bucket size as a percentage of +# max_bucket_size from client_delay_parameters. Buckets are created +# at the time of the "first" connection from the matching IP. Idle +# buckets are periodically deleted up. +# +# You can specify more than 100 percent but note that such "oversized" +# buckets are not refilled until their size goes down to max_bucket_size +# from client_delay_parameters. +# +# Example: +# client_delay_initial_bucket_level 50 +#Default: +# client_delay_initial_bucket_level 50 + +# TAG: client_delay_parameters +# +# This option configures client-side bandwidth limits using the +# following format: +# +# client_delay_parameters pool speed_limit max_bucket_size +# +# pool is an integer ID used for client_delay_access matching. +# +# speed_limit is bytes added to the bucket per second. +# +# max_bucket_size is the maximum size of a bucket, enforced after any +# speed_limit additions. +# +# Please see the delay_parameters option for more information and +# examples. +# +# Example: +# client_delay_parameters 1 1024 2048 +# client_delay_parameters 2 51200 16384 +# +# See also client_delay_access. +# +#Default: +# none + +# TAG: client_delay_access +# This option determines the client-side delay pool for the +# request: +# +# client_delay_access pool_ID allow|deny acl_name +# +# All client_delay_access options are checked in their pool ID +# order, starting with pool 1. The first checked pool with allowed +# request is selected for the request. If no ACL matches or there +# are no client_delay_access options, the request bandwidth is not +# limited. +# +# The ACL-selected pool is then used to find the +# client_delay_parameters for the request. Client-side pools are +# 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 +# +# +# See also client_delay_parameters and client_delay_pools. +#Default: +# Deny use of the pool, unless allow rules exist in squid.conf for the pool. + # WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS # ----------------------------------------------------------------------------- @@ -4040,7 +5969,7 @@ refresh_pattern . 0 20% 4320 # only one of the two may be used at the same time and defines # which version of WCCP to use. #Default: -# wccp_router any_addr +# WCCP disabled. # TAG: wccp2_router # Use this option to define your WCCP ``home'' router for @@ -4053,7 +5982,7 @@ refresh_pattern . 0 20% 4320 # only one of the two may be used at the same time and defines # which version of WCCP to use. #Default: -# none +# WCCPv2 disabled. # TAG: wccp_version # This directive is only relevant if you need to set up WCCP(v1) @@ -4110,7 +6039,7 @@ refresh_pattern . 0 20% 4320 # Valid values are as follows: # # hash - Hash assignment -# mask - Mask assignment +# mask - Mask assignment # # As a general rule, cisco routers support the hash assignment method # and cisco switches support the mask assignment method. @@ -4138,7 +6067,7 @@ refresh_pattern . 0 20% 4320 # # fleshed out with subsequent options. # wccp2_service standard 0 password=foo #Default: -# wccp2_service standard 0 +# Use the 'web-cache' standard service. # TAG: wccp2_service_info # Dynamic WCCPv2 services require further information to define the @@ -4175,8 +6104,12 @@ refresh_pattern . 0 20% 4320 # wccp2_weight 10000 # TAG: wccp_address +# Use this option if you require WCCPv2 to use a specific +# interface address. +# +# The default behavior is to not bind to any specific address. #Default: -# wccp_address 0.0.0.0 +# Address selected by the operating system. # TAG: wccp2_address # Use this option if you require WCCP to use a specific @@ -4184,7 +6117,7 @@ refresh_pattern . 0 20% 4320 # # The default behavior is to not bind to any specific address. #Default: -# wccp2_address 0.0.0.0 +# Address selected by the operating system. # PERSISTENT CONNECTION HANDLING # ----------------------------------------------------------------------------- @@ -4192,14 +6125,16 @@ refresh_pattern . 0 20% 4320 # Also see "pconn_timeout" in the TIMEOUTS section # TAG: client_persistent_connections +# Persistent connection support for clients. +# Squid uses persistent connections (when allowed). You can use +# this option to disable persistent connections with clients. #Default: # client_persistent_connections on # TAG: server_persistent_connections -# 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. #Default: # server_persistent_connections on @@ -4275,7 +6210,7 @@ refresh_pattern . 0 20% 4320 # Example: # snmp_port 3401 #Default: -# snmp_port 0 +# SNMP disabled. # TAG: snmp_access # Allowing or denying access to the SNMP port. @@ -4287,26 +6222,29 @@ refresh_pattern . 0 20% 4320 # # 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 #Default: -# snmp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: snmp_incoming_address -#Default: -# snmp_incoming_address any_addr - -# TAG: snmp_outgoing_address # Just like 'udp_incoming_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. +#Default: +# Accept SNMP packets from all machine interfaces. + +# TAG: snmp_outgoing_address +# Just like 'udp_outgoing_address', but for the SNMP port. +# +# snmp_outgoing_address is used for SNMP packets returned to SNMP +# agents. # # 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 @@ -4314,9 +6252,9 @@ refresh_pattern . 0 20% 4320 # 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. #Default: -# snmp_outgoing_address no_addr +# Use snmp_incoming_address or an address selected by the operating system. # ICP OPTIONS # ----------------------------------------------------------------------------- @@ -4324,22 +6262,21 @@ refresh_pattern . 0 20% 4320 # TAG: icp_port # 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 3130 #Default: -# icp_port 0 +# ICP disabled. # TAG: htcp_port # 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 #Default: -# htcp_port 0 +# HTCP disabled. # TAG: log_icp_queries on|off # If set, ICP queries are logged to access.log. You may wish @@ -4365,7 +6302,7 @@ refresh_pattern . 0 20% 4320 # NOTE, udp_incoming_address and udp_outgoing_address can not # have the same value since they both use the same port. #Default: -# udp_incoming_address any_addr +# Accept packets from all machine interfaces. # TAG: udp_outgoing_address # udp_outgoing_address is used for UDP packets sent out to other @@ -4386,7 +6323,7 @@ refresh_pattern . 0 20% 4320 # NOTE, udp_incoming_address and udp_outgoing_address can not # have the same value since they both use the same port. #Default: -# udp_outgoing_address no_addr +# Use udp_incoming_address or an address selected by the operating system. # TAG: icp_hit_stale on|off # If you want to return ICP_HIT for stale cache objects, set this @@ -4405,21 +6342,33 @@ refresh_pattern . 0 20% 4320 #Default: # minimum_direct_hops 4 -# TAG: minimum_direct_rtt +# TAG: minimum_direct_rtt (msec) # If using the ICMP pinging stuff, do direct fetches for sites # which are no more than this many rtt milliseconds away. #Default: # minimum_direct_rtt 400 # TAG: netdb_low +# 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. #Default: # netdb_low 900 # TAG: netdb_high -# 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. #Default: # netdb_high 1000 @@ -4462,7 +6411,7 @@ refresh_pattern . 0 20% 4320 # # icp_query_timeout 2000 #Default: -# icp_query_timeout 0 +# Dynamic detection. # TAG: maximum_icp_query_timeout (msec) # Normally the ICP query timeout is determined dynamically. But @@ -4528,7 +6477,7 @@ refresh_pattern . 0 20% 4320 # Do not enable this option unless you are are absolutely # certain you understand what you are doing. #Default: -# mcast_miss_addr no_addr +# disabled. # TAG: mcast_miss_ttl # Note: This option is only available if Squid is rebuilt with the @@ -4618,7 +6567,7 @@ refresh_pattern . 0 20% 4320 # The squid developers working on translations are happy to supply drop-in # translated error files in exchange for any new language contributions. #Default: -# none +# Send error pages in the clients preferred language # TAG: error_default_language # Set the default language which squid will send error pages in @@ -4632,7 +6581,7 @@ refresh_pattern . 0 20% 4320 # translations for any language see the squid wiki for details. # http://wiki.squid-cache.org/Translations #Default: -# none +# Generate English language pages. # TAG: error_log_languages # Log to cache.log what languages users are attempting to @@ -4687,17 +6636,47 @@ refresh_pattern . 0 20% 4320 # the first authentication related acl encountered # - When none of the http_access lines matches. It's then the last # acl processed on the last http_access line. +# - When the decision to deny access was made by an adaptation service, +# the acl name is the corresponding eCAP or ICAP service_name. # # NP: If providing your own custom error pages with error_directory # you may also specify them by your custom file name: # Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys # -# Alternatively you can specify an error URL. The browsers will -# get redirected (302 or 307) to the specified URL. %s in the redirection -# URL will be replaced by the requested URL. +# By defaut Squid will send "403 Forbidden". A different 4xx or 5xx +# may be specified by prefixing the file name with the code and a colon. +# e.g. 404:ERR_CUSTOM_ACCESS_DENIED # # Alternatively you can tell Squid to reset the TCP connection # by specifying TCP_RESET. +# +# Or you can specify an error URL or URL pattern. The browsers will +# get redirected to the specified URL after formatting tags have +# been replaced. Redirect will be done with 302 or 307 according to +# HTTP/1.1 specs. A different 3xx code may be specified by prefixing +# the URL. e.g. 303:http://example.com/ +# +# URL FORMAT TAGS: +# %a - username (if available. Password NOT included) +# %B - FTP path URL +# %e - Error number +# %E - Error description +# %h - Squid hostname +# %H - Request domain name +# %i - Client IP Address +# %M - Request Method +# %o - Message result from external ACL helper +# %p - Request Port number +# %P - Request Protocol name +# %R - Request URL path +# %T - Timestamp in RFC 1123 format +# %U - Full canonical URL from client +# (HTTPS URLs terminate with *) +# %u - Full canonical URL from client +# %w - Admin email from squid.conf +# %x - Error name +# %% - Literal percent (%) code +# #Default: # none @@ -4706,18 +6685,18 @@ refresh_pattern . 0 20% 4320 # TAG: nonhierarchical_direct # By default, Squid will send any non-hierarchical requests -# (matching hierarchy_stoplist or not cacheable request type) direct -# to origin servers. +# (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. #Default: # nonhierarchical_direct on @@ -4736,6 +6715,29 @@ refresh_pattern . 0 20% 4320 #Default: # prefer_direct off +# TAG: cache_miss_revalidate on|off +# RFC 7232 defines a conditional request mechanism to prevent +# response objects being unnecessarily transferred over the network. +# If that mechanism is used by the client and a cache MISS occurs +# it can prevent new cache entries being created. +# +# This option determines whether Squid on cache MISS will pass the +# client revalidation request to the server or tries to fetch new +# content for caching. It can be useful while the cache is mostly +# empty to more quickly have the cache populated by generating +# non-conditional GETs. +# +# When set to 'on' (default), Squid will pass all client If-* headers +# to the server. This permits server responses without a cacheable +# payload to be delivered and on MISS no new cache entry is created. +# +# When set to 'off' and if the request is cacheable, Squid will +# remove the clients If-Modified-Since and If-None-Match headers from +# the request sent to the server. This requests a 200 status response +# from the server to create a new cache entry with. +#Default: +# cache_miss_revalidate on + # TAG: always_direct # Usage: always_direct allow|deny [!]aclname ... # @@ -4776,7 +6778,7 @@ refresh_pattern . 0 20% 4320 # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Prevent any cache_peer being used for this request. # TAG: never_direct # Usage: never_direct allow|deny [!]aclname ... @@ -4805,37 +6807,52 @@ refresh_pattern . 0 20% 4320 # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow DNS results to be used for this request. # ADVANCED NETWORKING OPTIONS # ----------------------------------------------------------------------------- -# TAG: incoming_icp_average +# TAG: incoming_udp_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# incoming_icp_average 6 +# incoming_udp_average 6 -# TAG: incoming_http_average +# TAG: incoming_tcp_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# incoming_http_average 4 +# incoming_tcp_average 4 # TAG: incoming_dns_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: # incoming_dns_average 4 -# TAG: min_icp_poll_cnt +# TAG: min_udp_poll_cnt +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# min_icp_poll_cnt 8 +# min_udp_poll_cnt 8 # TAG: min_dns_poll_cnt +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: # min_dns_poll_cnt 8 -# TAG: min_http_poll_cnt +# TAG: min_tcp_poll_cnt # Heavy voodoo here. I can't even believe you are reading this. # Are you crazy? Don't even think about adjusting these unless # you understand the algorithms in comm_select.c first! #Default: -# min_http_poll_cnt 8 +# min_tcp_poll_cnt 8 # TAG: accept_filter # FreeBSD: @@ -4880,14 +6897,14 @@ refresh_pattern . 0 20% 4320 # WARNING: This may noticably slow down traffic received via external proxies # or NAT devices and cause them to rebound error messages back to their clients. #Default: -# client_ip_max_connections -1 +# No limit. # TAG: tcp_recv_bufsize (bytes) # 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. #Default: -# tcp_recv_bufsize 0 bytes +# Use operating system TCP defaults. # ICAP OPTIONS # ----------------------------------------------------------------------------- @@ -4913,22 +6930,36 @@ refresh_pattern . 0 20% 4320 # an established, active ICAP connection before giving up and # either terminating the HTTP transaction or bypassing the # failure. -# -# The default is read_timeout. #Default: -# none +# Use read_timeout. -# TAG: icap_service_failure_limit +# TAG: icap_service_failure_limit limit [in memory-depth time-units] # The limit specifies the number of failures that Squid tolerates # when establishing a new TCP connection with an ICAP service. If # the number of failures exceeds the limit, the ICAP service is # not used for new ICAP requests until it is time to refresh its -# OPTIONS. The per-service failure counter is reset to zero each -# time Squid fetches new service OPTIONS. +# OPTIONS. # # A negative value disables the limit. Without the limit, an ICAP # service will not be considered down due to connectivity failures # between ICAP OPTIONS requests. +# +# Squid forgets ICAP service failures older than the specified +# value of memory-depth. The memory fading algorithm +# is approximate because Squid does not remember individual +# errors but groups them instead, splitting the option +# value into ten time slots of equal length. +# +# When memory-depth is 0 and by default this option has no +# effect on service failure expiration. +# +# Squid always forgets failures when updating service settings +# using an ICAP OPTIONS transaction, regardless of this option +# setting. +# +# For example, +# # suspend service usage after 10 failures in 5 seconds: +# icap_service_failure_limit 10 in 5 seconds #Default: # icap_service_failure_limit 10 @@ -4962,10 +6993,26 @@ refresh_pattern . 0 20% 4320 # TAG: icap_preview_size # 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. #Default: -# icap_preview_size -1 +# No preview sent. + +# TAG: icap_206_enable on|off +# 206 (Partial Content) responses is an ICAP extension that allows the +# ICAP agents to optionally combine adapted and original HTTP message +# content. The decision to combine is postponed until the end of the +# ICAP response. Squid supports Partial Content extension by default. +# +# Activation of the Partial Content extension is negotiated with each +# ICAP service during OPTIONS exchange. Most ICAP servers should handle +# negotation correctly even if they do not support the extension, but +# some might fail. To disable Partial Content support for all ICAP +# services and to avoid any negotiation, set this option to "off". +# +# Example: +# icap_206_enable off +#Default: +# icap_206_enable on # TAG: icap_default_options_ttl # The default TTL value for ICAP OPTIONS responses that don't have @@ -4979,25 +7026,27 @@ refresh_pattern . 0 20% 4320 #Default: # icap_persistent_connections on -# TAG: icap_send_client_ip on|off +# TAG: adaptation_send_client_ip on|off # If enabled, Squid shares HTTP client IP information with adaptation # services. For ICAP, Squid adds the X-Client-IP header to ICAP requests. # For eCAP, Squid sets the libecap::metaClientIp transaction option. # # See also: adaptation_uses_indirect_client #Default: -# icap_send_client_ip off +# adaptation_send_client_ip off -# TAG: icap_send_client_username on|off +# TAG: adaptation_send_username on|off # This sends authenticated HTTP client username (if available) to -# the ICAP service. The username value is encoded based on the +# the adaptation service. +# +# For ICAP, the username value is encoded based on the # icap_client_username_encode option and is sent using the header # specified by the icap_client_username_header option. #Default: -# icap_send_client_username off +# adaptation_send_username off # TAG: icap_client_username_header -# ICAP request header name to use for send_client_username. +# ICAP request header name to use for adaptation_send_username. #Default: # icap_client_username_header X-Client-Username @@ -5009,17 +7058,19 @@ refresh_pattern . 0 20% 4320 # TAG: icap_service # Defines a single ICAP service using the following format: # -# icap_service service_name vectoring_point [options] service_url +# icap_service id vectoring_point uri [option ...] # -# service_name: ID -# an opaque identifier which must be unique in squid.conf +# id: ID +# an opaque identifier or name which is used to direct traffic to +# this specific service. Must be unique among all adaptation +# services in squid.conf. # # vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache # This specifies at which point of transaction processing the # ICAP service should be activated. *_postcache vectoring points # are not yet supported. # -# service_url: icap://servername:port/servicepath +# uri: icap://servername:port/servicepath # ICAP server and service location. # # ICAP does not allow a single service to handle both REQMOD and RESPMOD @@ -5028,6 +7079,8 @@ refresh_pattern . 0 20% 4320 # can even specify multiple identical services as long as their # service_names differ. # +# To activate a service, use the adaptation_access directive. To group +# services, use adaptation_service_chain and adaptation_service_set. # # Service options are separated by white space. ICAP services support # the following name=value options: @@ -5049,11 +7102,12 @@ refresh_pattern . 0 20% 4320 # returning a chain of services to be used next. The services # are specified using the X-Next-Services ICAP response header # value, formatted as a comma-separated list of service names. -# Each named service should be configured in squid.conf and -# should have the same method and vectoring point as the current -# ICAP transaction. Services violating these rules are ignored. -# An empty X-Next-Services value results in an empty plan which -# ends the current adaptation. +# Each named service should be configured in squid.conf. Other +# services are ignored. An empty X-Next-Services value results +# in an empty plan which ends the current adaptation. +# +# Dynamic adaptation plan may cross or cover multiple supported +# vectoring points in their natural processing order. # # Routing is not allowed by default: the ICAP X-Next-Services # response header is ignored. @@ -5063,12 +7117,32 @@ refresh_pattern . 0 20% 4320 # is to use IPv4-only connections. When set to 'on' this option will # make Squid use IPv6-only connections to contact this ICAP service. # +# on-overload=block|bypass|wait|force +# If the service Max-Connections limit has been reached, do +# one of the following for each new ICAP transaction: +# * block: send an HTTP error response to the client +# * bypass: ignore the "over-connected" ICAP service +# * wait: wait (in a FIFO queue) for an ICAP connection slot +# * force: proceed, ignoring the Max-Connections limit +# +# In SMP mode with N workers, each worker assumes the service +# connection limit is Max-Connections/N, even though not all +# workers may use a given service. +# +# The default value is "bypass" if service is bypassable, +# otherwise it is set to "wait". +# +# +# max-conn=number +# Use the given number as the Max-Connections limit, regardless +# of the Max-Connections value given by the service, if any. +# # Older icap_service format without optional named parameters is # deprecated but supported for backward compatibility. # #Example: -#icap_service svcBlocker reqmod_precache bypass=0 icap://icap1.mydomain.net:1344/reqmod -#icap_service svcLogger reqmod_precache routing=on icap://icap2.mydomain.net:1344/respmod +#icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0 +#icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on #Default: # none @@ -5094,38 +7168,65 @@ refresh_pattern . 0 20% 4320 # ----------------------------------------------------------------------------- # TAG: ecap_enable on|off -# Note: This option is only available if Squid is rebuilt with the -# --enable-ecap option -# # Controls whether eCAP support is enabled. #Default: # ecap_enable off # TAG: ecap_service -# Note: This option is only available if Squid is rebuilt with the -# --enable-ecap option -# # Defines a single eCAP service # -# ecap_service servicename vectoring_point bypass service_url +# ecap_service id vectoring_point uri [option ...] # -# vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache +# id: ID +# an opaque identifier or name which is used to direct traffic to +# this specific service. Must be unique among all adaptation +# services in squid.conf. +# +# vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache # This specifies at which point of transaction processing the # eCAP service should be activated. *_postcache vectoring points # are not yet supported. -# bypass = 1|0 -# If set to 1, the eCAP service is treated as optional. If the -# service cannot be reached or malfunctions, Squid will try to -# ignore any errors and process the message as if the service +# +# uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional +# Squid uses the eCAP service URI to match this configuration +# line with one of the dynamically loaded services. Each loaded +# eCAP service must have a unique URI. Obtain the right URI from +# the service provider. +# +# To activate a service, use the adaptation_access directive. To group +# services, use adaptation_service_chain and adaptation_service_set. +# +# Service options are separated by white space. eCAP services support +# the following name=value options: +# +# bypass=on|off|1|0 +# If set to 'on' or '1', the eCAP service is treated as optional. +# If the service cannot be reached or malfunctions, Squid will try +# to ignore any errors and process the message as if the service # was not enabled. No all eCAP errors can be bypassed. -# If set to 0, the eCAP service is treated as essential and all -# eCAP errors will result in an error page returned to the +# If set to 'off' or '0', the eCAP service is treated as essential +# and all eCAP errors will result in an error page returned to the # HTTP client. -# service_url = ecap://vendor/service_name?custom&cgi=style¶meters=optional +# +# Bypass is off by default: services are treated as essential. +# +# routing=on|off|1|0 +# If set to 'on' or '1', the eCAP service is allowed to +# dynamically change the current message adaptation plan by +# returning a chain of services to be used next. +# +# Dynamic adaptation plan may cross or cover multiple supported +# vectoring points in their natural processing order. +# +# Routing is not allowed by default. +# +# Older ecap_service format without optional named parameters is +# deprecated but supported for backward compatibility. +# # #Example: -#ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block -#ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg +#ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off +#ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on #Default: # none @@ -5247,7 +7348,7 @@ refresh_pattern . 0 20% 4320 #Example: #adaptation_access service_1 allow all #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: adaptation_service_iteration_limit # Limits the number of iterations allowed when applying adaptation @@ -5275,8 +7376,14 @@ refresh_pattern . 0 20% 4320 # # An ICAP REQMOD or RESPMOD transaction may set an entry in the # shared table by returning an ICAP header field with a name -# specified in adaptation_masterx_shared_names. Squid will store -# and forward that ICAP header field to subsequent ICAP +# specified in adaptation_masterx_shared_names. +# +# An eCAP REQMOD or RESPMOD transaction may set an entry in the +# shared table by implementing the libecap::visitEachOption() API +# to provide an option with a name specified in +# adaptation_masterx_shared_names. +# +# Squid will store and forward the set entry to subsequent adaptation # transactions within the same master transaction scope. # # Only one shared entry name is supported at this time. @@ -5287,6 +7394,43 @@ refresh_pattern . 0 20% 4320 #Default: # none +# TAG: adaptation_meta +# This option allows Squid administrator to add custom ICAP request +# headers or eCAP options to Squid ICAP requests or eCAP transactions. +# Use it to pass custom authentication tokens and other +# transaction-state related meta information to an ICAP/eCAP service. +# +# The addition of a meta header is ACL-driven: +# adaptation_meta name value [!]aclname ... +# +# Processing for a given header name stops after the first ACL list match. +# Thus, it is impossible to add two headers with the same name. If no ACL +# lists match for a given header name, no such header is added. For +# example: +# +# # do not debug transactions except for those that need debugging +# adaptation_meta X-Debug 1 needs_debugging +# +# # log all transactions except for those that must remain secret +# adaptation_meta X-Log 1 !keep_secret +# +# # mark transactions from users in the "G 1" group +# adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1 +# +# The "value" parameter may be a regular squid.conf token or a "double +# quoted string". Within the quoted string, use backslash (\) to escape +# any character, which is currently only useful for escaping backslashes +# 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). +#Default: +# none + # TAG: icap_retry # This ACL determines which retriable ICAP transactions are # retried. Transactions that received a complete ICAP response @@ -5303,8 +7447,7 @@ refresh_pattern . 0 20% 4320 # icap_retry deny all # TAG: icap_retry_limit -# 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 @@ -5312,7 +7455,7 @@ refresh_pattern . 0 20% 4320 # # See also: icap_retry #Default: -# icap_retry_limit 0 +# No retries are allowed. # DNS OPTIONS # ----------------------------------------------------------------------------- @@ -5332,31 +7475,9 @@ refresh_pattern . 0 20% 4320 #Default: # allow_underscore on -# TAG: cache_dns_program -# Note: This option is only available if Squid is rebuilt with the -# --disable-internal-dns option -# -# Specify the location of the executable for dnslookup process. -#Default: -# cache_dns_program /usr/lib/squid/dnsserver - -# TAG: dns_children -# Note: This option is only available if Squid is rebuilt with the -# --disable-internal-dns option -# -# The number of processes spawn to service DNS name lookups. -# For heavily loaded caches on large servers, you should -# probably increase this value to at least 10. The maximum -# is 32. The default is 5. -# -# You must have at least one dnsserver process. -#Default: -# dns_children 5 - # TAG: dns_retransmit_interval # Initial retransmit interval for DNS queries. The interval is # doubled each time all configured DNS servers have been tried. -# #Default: # dns_retransmit_interval 5 seconds @@ -5365,7 +7486,31 @@ refresh_pattern . 0 20% 4320 # within this time all DNS servers for the queried domain # are assumed to be unavailable. #Default: -# dns_timeout 2 minutes +# dns_timeout 30 seconds + +# TAG: dns_packet_max +# Maximum number of bytes packet size to advertise via EDNS. +# Set to "none" to disable EDNS large packet support. +# +# For legacy reasons DNS UDP replies will default to 512 bytes which +# is too small for many responses. EDNS provides a means for Squid to +# negotiate receiving larger responses back immediately without having +# to failover with repeat requests. Responses larger than this limit +# will retain the old behaviour of failover to TCP DNS. +# +# Squid has no real fixed limit internally, but allowing packet sizes +# over 1500 bytes requires network jumbogram support and is usually not +# necessary. +# +# WARNING: The RFC also indicates that some older resolvers will reply +# with failure of the whole request if the extension is added. Some +# resolvers have already been identified which will reply with mangled +# EDNS response on occasion. Usually in response to many-KB jumbogram +# sizes being advertised by Squid. +# Squid will currently treat these both as an unable-to-resolve domain +# even if it would be resolvable without EDNS. +#Default: +# EDNS disabled # TAG: dns_defnames on|off # Normally the RES_DEFNAMES resolver option is disabled @@ -5373,12 +7518,21 @@ refresh_pattern . 0 20% 4320 # from interpreting single-component hostnames locally. To allow # Squid to handle single-component names, enable this option. #Default: -# dns_defnames off +# Search for single-label domain names is disabled. + +# TAG: dns_multicast_local on|off +# When set to on, Squid sends multicast DNS lookups on the local +# network for domains ending in .local and .arpa. +# This enables local servers and devices to be contacted in an +# ad-hoc or zero-configuration network environment. +#Default: +# Search for .local and .arpa names is disabled. # TAG: dns_nameservers # 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 @@ -5386,7 +7540,7 @@ refresh_pattern . 0 20% 4320 # # Example: dns_nameservers 10.0.0.1 192.172.0.4 #Default: -# none +# Use operating system definitions # TAG: hosts_file # Location of the host-local IP name-address associations @@ -5425,7 +7579,7 @@ refresh_pattern . 0 20% 4320 #Example: # append_domain .yourdomain.com #Default: -# none +# Use operating system definitions # TAG: ignore_unknown_nameservers # By default Squid checks that DNS responses are received @@ -5436,23 +7590,6 @@ refresh_pattern . 0 20% 4320 #Default: # ignore_unknown_nameservers on -# TAG: dns_v4_fallback -# Standard practice with DNS is to lookup either A or AAAA records -# and use the results if it succeeds. Only looking up the other if -# the first attempt fails or otherwise produces no results. -# -# That policy however will cause squid to produce error pages for some -# servers that advertise AAAA but are unreachable over IPv6. -# -# If this is ON squid will always lookup both AAAA and A, using both. -# If this is OFF squid will lookup AAAA and only try A if none found. -# -# WARNING: There are some possibly unwanted side-effects with this on: -# *) Doubles the load placed by squid on the DNS network. -# *) May negatively impact connection delay times. -#Default: -# dns_v4_fallback on - # TAG: dns_v4_first # With the IPv6 Internet being as fast or faster than IPv4 Internet # for most networks Squid prefers to contact websites over IPv6. @@ -5464,11 +7601,12 @@ refresh_pattern . 0 20% 4320 # WARNING: # This option will restrict the situations under which IPv6 # connectivity is used (and tested), potentially hiding network -# problem swhich would otherwise be detected and warned about. +# problems which would otherwise be detected and warned about. #Default: # dns_v4_first off # TAG: ipcache_size (number of entries) +# Maximum number of DNS IP cache entries. #Default: # ipcache_size 1024 @@ -5489,6 +7627,15 @@ refresh_pattern . 0 20% 4320 # MISCELLANEOUS # ----------------------------------------------------------------------------- +# TAG: configuration_includes_quoted_values on|off +# If set, Squid will recognize each "quoted string" after a configuration +# directive as a single parameter. The quotes are stripped before the +# parameter value is interpreted or used. +# See "Values with spaces, quotes, and other special characters" +# section for more details. +#Default: +# configuration_includes_quoted_values off + # TAG: memory_pools on|off # If set, Squid will keep pools of allocated (but unused) memory # available for future use. If memory is a premium on your @@ -5539,7 +7686,7 @@ refresh_pattern . 0 20% 4320 # X-Forwarded-For header. # # If set to "truncate", Squid will remove all existing -# X-Forwarded-For entries, and place itself as the sole entry. +# X-Forwarded-For entries, and place the client IP as the sole entry. #Default: # forwarded_for on @@ -5602,7 +7749,7 @@ refresh_pattern . 0 20% 4320 # cachemgr_passwd lesssssssecret info stats/objects # cachemgr_passwd disable all #Default: -# none +# No password. Actions which require password are denied. # TAG: client_db on|off # If you want to disable collecting per-client statistics, @@ -5633,19 +7780,22 @@ refresh_pattern . 0 20% 4320 #Default: # reload_into_ims off -# TAG: maximum_single_addr_tries -# This sets the maximum number of connection attempts for a -# host that only has one address (for multiple-address hosts, -# each address is tried once). +# TAG: connect_retries +# This sets the maximum number of connection attempts made for each +# TCP connection. The connect_retries attempts must all still +# complete within the connection timeout period. # -# The default value is one attempt, the (not recommended) -# maximum is 255 tries. A warning message will be generated -# if it is set to a value greater than ten. +# The default is not to re-try if the first connection attempt fails. +# The (not recommended) maximum is 10 tries. # -# Note: This is in addition to the request re-forwarding which -# takes place if Squid fails to get a satisfying response. +# A warning message will be generated if it is set to a too-high +# value and the configured value will be over-ridden. +# +# Note: These re-tries are in addition to forward_max_tries +# which limit how many different addresses may be tried to find +# a useful server. #Default: -# maximum_single_addr_tries 1 +# Do not retry failed connections. # TAG: retry_on_error # If set to ON Squid will automatically retry requests when @@ -5678,20 +7828,32 @@ refresh_pattern . 0 20% 4320 # 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. #Default: # uri_whitespace strip @@ -5718,23 +7880,28 @@ refresh_pattern . 0 20% 4320 # balance_on_multiple_ip off # TAG: pipeline_prefetch -# To boost the performance of pipelined requests to closer -# match that of a non-proxied environment Squid can try to fetch -# up to two requests in parallel from a pipeline. -# -# Defaults to off for bandwidth management and access logging +# HTTP clients may send a pipeline of 1+N requests to Squid using a +# single connection, without waiting for Squid to respond to the first +# of those requests. This option limits the number of concurrent +# requests Squid will try to handle in parallel. If set to N, Squid +# will try to receive and process up to 1+N requests on the same +# connection concurrently. +# +# Defaults to 0 (off) for bandwidth management and access logging # reasons. # +# NOTE: pipelining requires persistent connections to clients. +# # WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication. #Default: -# pipeline_prefetch off +# Do not pre-parse pipelined requests. # TAG: high_response_time_warning (msec) # If the one-minute median response time exceeds this value, # Squid prints a WARNING with debug level 0 to get the # administrators attention. The value is in milliseconds. #Default: -# high_response_time_warning 0 +# disabled. # TAG: high_page_fault_warning # If the one-minute average page fault rate exceeds this @@ -5742,14 +7909,17 @@ refresh_pattern . 0 20% 4320 # the administrators attention. The value is in page faults # per second. #Default: -# high_page_fault_warning 0 +# disabled. # TAG: high_memory_warning -# If the memory usage (as determined by mallinfo) exceeds -# this amount, Squid prints a WARNING with debug level 0 to get +# Note: This option is only available if Squid is rebuilt with the +# GNU Malloc with mstats() +# +# If the memory usage (as determined by gnumalloc, if available and used) +# exceeds this amount, Squid prints a WARNING with debug level 0 to get # the administrators attention. #Default: -# high_memory_warning 0 KB +# disabled. # TAG: sleep_after_fork (microseconds) # When this is set to a non-zero value, the main Squid process @@ -5766,6 +7936,9 @@ refresh_pattern . 0 20% 4320 # sleep_after_fork 0 # TAG: windows_ipaddrchangemonitor on|off +# Note: This option is only available if Squid is rebuilt with the +# MS Windows +# # On Windows Squid by default will monitor IP address changes and will # reconfigure itself after any detected event. This is very useful for # proxies connected to internet with dial-up interfaces. @@ -5775,13 +7948,19 @@ refresh_pattern . 0 20% 4320 #Default: # windows_ipaddrchangemonitor on +# TAG: eui_lookup +# Whether to lookup the EUI or MAC address of a connected client. +#Default: +# eui_lookup on + # TAG: max_filedescriptors -# 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). #Default: -# max_filedescriptors 0 +# Use operating system limits set by ulimit. diff --git a/hosts/jenkins/etc/squid/squid.conf b/hosts/jenkins/etc/squid/squid.conf index 34be0ec5..ad1cdc47 100644 --- a/hosts/jenkins/etc/squid/squid.conf +++ b/hosts/jenkins/etc/squid/squid.conf @@ -1,4 +1,4 @@ -# WELCOME TO SQUID 3.1.20 +# WELCOME TO SQUID 3.5.23 # ---------------------------- # # This is the documentation for the Squid configuration file. @@ -32,6 +32,188 @@ # This arbitrary restriction is to prevent recursive include references # from causing Squid entering an infinite loop whilst trying to load # configuration files. +# +# Values with byte units +# +# Squid accepts size units on some size related directives. All +# such directives are documented with a default value displaying +# a unit. +# +# Units accepted by Squid are: +# bytes - byte +# KB - Kilobyte (1024 bytes) +# MB - Megabyte +# GB - Gigabyte +# +# Values with spaces, quotes, and other special characters +# +# Squid supports directive parameters with spaces, quotes, and other +# special characters. Surround such parameters with "double quotes". Use +# the configuration_includes_quoted_values directive to enable or +# disable that support. +# +# Squid supports reading configuration option parameters from external +# files using the syntax: +# parameters("/path/filename") +# For example: +# acl whitelist dstdomain parameters("/etc/squid/whitelist.txt") +# +# Conditional configuration +# +# If-statements can be used to make configuration directives +# depend on conditions: +# +# if <CONDITION> +# ... regular configuration directives ... +# [else +# ... regular configuration directives ...] +# endif +# +# The else part is optional. The keywords "if", "else", and "endif" +# must be typed on their own lines, as if they were regular +# configuration directives. +# +# NOTE: An else-if condition is not supported. +# +# These individual conditions types are supported: +# +# true +# Always evaluates to true. +# false +# Always evaluates to false. +# <integer> = <integer> +# Equality comparison of two integer numbers. +# +# +# SMP-Related Macros +# +# The following SMP-related preprocessor macros can be used. +# +# ${process_name} expands to the current Squid process "name" +# (e.g., squid1, squid2, or cache1). +# +# ${process_number} expands to the current Squid process +# identifier, which is an integer number (e.g., 1, 2, 3) unique +# across all Squid processes of the current service instance. +# +# ${service_name} expands into the current Squid service instance +# name identifier which is provided by -n on the command line. +# + +# TAG: broken_vary_encoding +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: cache_vary +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: error_map +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: external_refresh_check +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: location_rewrite_program +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: refresh_stale_hit +# This option is not yet supported by Squid-3. +#Default: +# none + +# TAG: hierarchy_stoplist +# Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use. +#Default: +# none + +# TAG: log_access +# Remove this line. Use acls with access_log directives to control access logging +#Default: +# none + +# TAG: log_icap +# Remove this line. Use acls with icap_log directives to control icap logging +#Default: +# none + +# TAG: ignore_ims_on_miss +# Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'. +#Default: +# none + +# TAG: chunked_request_body_max_size +# Remove this line. Squid is now HTTP/1.1 compliant. +#Default: +# none + +# TAG: dns_v4_fallback +# Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant. +#Default: +# none + +# TAG: emulate_httpd_log +# Replace this with an access_log directive using the format 'common' or 'combined'. +#Default: +# none + +# TAG: forward_log +# Use a regular access.log with ACL limiting it to MISS events. +#Default: +# none + +# TAG: ftp_list_width +# Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead. +#Default: +# none + +# TAG: ignore_expect_100 +# Remove this line. The HTTP/1.1 feature is now fully supported by default. +#Default: +# none + +# TAG: log_fqdn +# Remove this option from your config. To log FQDN use %>A in the log format. +#Default: +# none + +# TAG: log_ip_on_direct +# Remove this option from your config. To log server or peer names use %<A in the log format. +#Default: +# none + +# TAG: maximum_single_addr_tries +# Replaced by connect_retries. The behaviour has changed, please read the documentation before altering. +#Default: +# none + +# TAG: referer_log +# Replace this with an access_log directive using the format 'referrer'. +#Default: +# none + +# TAG: update_headers +# Remove this line. The feature is supported by default in storage types where update is implemented. +#Default: +# none + +# TAG: url_rewrite_concurrency +# Remove this line. Set the 'concurrency=' option of url_rewrite_children instead. +#Default: +# none + +# TAG: useragent_log +# Replace this with an access_log directive using the format 'useragent'. +#Default: +# none # TAG: dns_testnames # Remove this line. DNS is no longer tested on startup. @@ -43,6 +225,10 @@ #Default: # none +# TAG: zero_buffers +#Default: +# none + # TAG: incoming_rate #Default: # none @@ -73,6 +259,49 @@ #Default: # none +# TAG: wais_relay_host +# Replace this line with 'cache_peer' configuration. +#Default: +# none + +# TAG: wais_relay_port +# Replace this line with 'cache_peer' configuration. +#Default: +# none + +# OPTIONS FOR SMP +# ----------------------------------------------------------------------------- + +# TAG: workers +# Number of main Squid processes or "workers" to fork and maintain. +# 0: "no daemon" mode, like running "squid -N ..." +# 1: "no SMP" mode, start one main Squid process daemon (default) +# N: start N main Squid process daemons (i.e., SMP mode) +# +# In SMP mode, each worker does nearly all what a single Squid daemon +# does (e.g., listen on http_port and forward HTTP requests). +#Default: +# SMP support disabled. + +# TAG: cpu_affinity_map +# Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,... +# +# Sets 1:1 mapping between Squid processes and CPU cores. For example, +# +# cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7 +# +# affects processes 1 through 4 only and places them on the first +# four even cores, starting with core #1. +# +# CPU cores are numbered starting from 1. Requires support for +# sched_getaffinity(2) and sched_setaffinity(2) system calls. +# +# Multiple cpu_affinity_map options are merged. +# +# See also: workers +#Default: +# Let operating system decide. + # OPTIONS FOR AUTHENTICATION # ----------------------------------------------------------------------------- @@ -80,7 +309,7 @@ # This is used to define parameters for the various authentication # schemes supported by Squid. # -# format: auth_param scheme parameter [setting] +# format: auth_param scheme parameter [setting] # # The order in which authentication schemes are presented to the client is # dependent on the order the scheme first appears in config file. IE @@ -114,228 +343,104 @@ # Ports flagged 'transparent', 'intercept', or 'tproxy' have # authentication disabled. # -# === Parameters for the basic scheme follow. === +# === Parameters common to all schemes. === # # "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. -# If you use an authenticator, make sure you have 1 acl of type -# proxy_auth. -# -# By default, the basic authentication scheme is not used unless a -# program is specified. -# -# If you want to use the traditional NCSA proxy authentication, set -# this line to something like -# -# auth_param basic program /usr/lib/squid/ncsa_auth /usr/etc/passwd -# -# "utf8" on|off -# HTTP uses iso-latin-1 as characterset, 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. -# -# "children" numberofchildren -# The number of authenticator processes to spawn. If you start too few -# Squid will have to wait for them to process a backlog of credential -# verifications, slowing it down. When password verifications are -# done via a (slow) network you are likely to need lots of -# authenticator processes. -# auth_param basic children 5 -# -# "concurrency" concurrency -# The number of concurrent requests the helper can process. -# The default of 0 is used for helpers who only supports -# one request at a time. Setting this 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. -# Must not be set unless it's known the helper supports this. -# auth_param basic concurrency 0 -# -# "realm" realmstring -# Specifies the realm name which is to be reported to the -# client for the basic proxy authentication scheme (part of -# the text the user will see when prompted their username and -# password). There is no default. -# auth_param basic realm Squid proxy-caching web server -# -# "credentialsttl" timetolive -# Specifies how long squid assumes an externally validated -# username:password pair is valid for - in other words how -# often the helper program is called for that user. Set this -# low to force revalidation with short lived passwords. Note -# setting this high does not impact your susceptibility -# to replay attacks unless you are using an one-time password -# system (such as SecureID). If you are using such a system, -# you will be vulnerable to replay attacks unless you also -# use the max_user_ip ACL in an http_access rule. -# -# "casesensitive" on|off -# Specifies if usernames are case sensitive. Most user databases are -# case insensitive allowing the same username to be spelled using both -# lower and upper case letters, but some are case sensitive. This -# makes a big difference for user_max_ip ACL processing and similar. -# auth_param basic casesensitive off -# -# === Parameters for the digest scheme follow === +# Specifies the command for the external authenticator. # -# "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. -# -# By default, the digest authentication scheme is not used unless a -# program is specified. -# -# If you want to use a digest authenticator, set this line to -# something like -# -# auth_param digest program /usr/lib/squid/digest_pw_auth /usr/etc/digpass -# -# "utf8" on|off -# HTTP uses iso-latin-1 as characterset, 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. -# -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# If you start too few Squid will have to wait for them to -# process a backlog of H(A1) calculations, slowing it down. -# When the H(A1) calculations are done via a (slow) network -# you are likely to need lots of authenticator processes. -# auth_param digest children 5 -# -# "realm" realmstring -# Specifies the realm name which is to be reported to the -# client for the digest proxy authentication scheme (part of -# the text the user will see when prompted their username and -# password). There is no default. -# auth_param digest realm Squid proxy-caching web server -# -# "nonce_garbage_interval" timeinterval -# Specifies the interval that nonces that have been issued -# to client_agent's are checked for validity. -# -# "nonce_max_duration" timeinterval -# Specifies the maximum length of time a given nonce will be -# valid for. -# -# "nonce_max_count" number -# Specifies the maximum number of times a given nonce can be -# used. +# By default, each authentication scheme is not used unless a +# program is specified. # -# "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 -# (ie, 1,2,4,6)). Default off. +# See http://wiki.squid-cache.org/Features/AddonHelpers for +# more details on helper operations and creating your own. # -# "check_nonce_count" on|off -# This directive if set to off can disable the nonce count check -# completely to work around buggy digest qop implementations in -# certain mainstream browser versions. Default on to check the -# nonce count to protect from authentication replay attacks. +# "key_extras" format +# Specifies a string to be append to request line format for +# the authentication helper. "Quoted" format values may contain +# spaces and logformat %macros. In theory, any logformat %macro +# can be used. In practice, a %macro expands as a dash (-) if +# the helper request is sent before the required macro +# information is available to Squid. # -# "post_workaround" on|off -# This is a workaround to certain buggy browsers who sends -# an incorrect request digest in POST requests when reusing -# the same nonce as acquired earlier on a GET request. +# By default, Squid uses request formats provided in +# scheme-specific examples below (search for %credentials). # -# === NTLM scheme options follow === +# The expanded key_extras value is added to the Squid credentials +# cache and, hence, will affect authentication. It can be used to +# autenticate different users with identical user names (e.g., +# when user authentication depends on http_port). # -# "program" cmdline -# Specify the command for the external NTLM authenticator. -# 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 -# is not used. +# Avoid adding frequently changing information to key_extras. For +# example, if you add user source IP, and it changes frequently +# in your environment, then max_user_ip ACL is going to treat +# every user+IP combination as a unique "user", breaking the ACL +# and wasting a lot of memory on those user records. It will also +# force users to authenticate from scratch whenever their IP +# changes. # -# auth_param ntlm program /usr/lib/squid/ntlm_auth +# "realm" string +# Specifies the protection scope (aka realm name) which is to be +# reported to the client for the authentication scheme. It is +# commonly part of the text the user will see when prompted for +# their username and password. # -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# If you start too few Squid will have to wait for them to -# process a backlog of credential verifications, slowing it -# down. When credential verifications are done via a (slow) -# network you are likely to need lots of authenticator -# processes. +# For Basic the default is "Squid proxy-caching web server". +# For Digest there is no default, this parameter is mandatory. +# For NTLM and Negotiate this parameter is ignored. # -# auth_param ntlm children 5 +# "children" numberofchildren [startup=N] [idle=N] [concurrency=N] # -# "keep_alive" on|off -# Whether to keep the connection open after the initial response where -# Squid tells the browser which schemes are supported by the proxy. -# Some browsers are known to present many login popups or to corrupt -# POST/PUT requests transfer if the connection is not closed. -# The default is currently OFF to avoid this, but may change. -# -# auth_param ntlm keep_alive on +# The maximum number of authenticator processes to spawn. If +# you start too few Squid will have to wait for them to process +# a backlog of credential verifications, slowing it down. When +# password verifications are done via a (slow) network you are +# likely to need lots of authenticator processes. # -# === Options for configuring the NEGOTIATE auth-scheme follow === +# The startup= and idle= options permit some skew in the exact +# amount run. A minimum of startup=N will begin during startup +# and reconfigure. Squid will start more in groups of up to +# idle=N in an attempt to meet traffic needs and to keep idle=N +# free above those traffic needs up to the maximum. # -# "program" cmdline -# Specify the command for the external Negotiate authenticator. -# This protocol is used in Microsoft Active-Directory enabled setups with -# the Microsoft Internet Explorer or Mozilla Firefox browsers. -# Its main purpose is to exchange credentials with the Squid proxy -# 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. -# 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 /usr/lib/squid/ntlm_auth --helper-protocol=gss-spnego -# -# "children" numberofchildren -# The number of authenticator processes to spawn (no default). -# 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) -# network you are likely to need lots of authenticator -# processes. -# auth_param negotiate children 5 -# -# "keep_alive" on|off -# Whether to keep the connection open after the initial response where -# Squid tells the browser which schemes are supported by the proxy. -# Some browsers are known to present many login popups or to corrupt -# POST/PUT requests transfer if the connection is not closed. -# The default is currently OFF to avoid this, but may change. -# -# auth_param negotiate keep_alive on +# The concurrency= option sets the number of concurrent requests +# the helper can process. The default of 0 is used for helpers +# who only supports one request at a time. Setting this to a +# number greater than 0 changes the protocol used to include a +# channel ID field first on the request/response line, allowing +# multiple requests to be sent to the same helper in parallel +# without waiting for the response. # +# Concurrency must not be set unless it's known the helper +# supports the input format with channel-ID fields. +# +# NOTE: NTLM and Negotiate schemes do not support concurrency +# in the Squid code module even though some helpers can. # -# Examples: # -##Recommended minimum configuration per scheme: +# +# === Example Configuration === +# +# This configuration displays the recommended authentication scheme +# order from most to least secure with recommended minimum configuration +# settings for each scheme: +# ##auth_param negotiate program <uncomment and complete this line to activate> -##auth_param negotiate children 5 +##auth_param negotiate children 20 startup=0 idle=1 ##auth_param negotiate keep_alive on ## -##auth_param ntlm program <uncomment and complete this line to activate> -##auth_param ntlm children 5 -##auth_param ntlm keep_alive on -## -##auth_param digest program <uncomment and complete this line> -##auth_param digest children 5 +##auth_param digest program <uncomment and complete this line to activate> +##auth_param digest children 20 startup=0 idle=1 ##auth_param digest realm Squid proxy-caching web server ##auth_param digest nonce_garbage_interval 5 minutes ##auth_param digest nonce_max_duration 30 minutes ##auth_param digest nonce_max_count 50 ## +##auth_param ntlm program <uncomment and complete this line to activate> +##auth_param ntlm children 20 startup=0 idle=1 +##auth_param ntlm keep_alive on +## ##auth_param basic program <uncomment and complete this line> -##auth_param basic children 5 +##auth_param basic children 5 startup=5 idle=1 ##auth_param basic realm Squid proxy-caching web server ##auth_param basic credentialsttl 2 hours #Default: @@ -343,7 +448,7 @@ # TAG: authenticate_cache_garbage_interval # 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. #Default: @@ -362,11 +467,11 @@ # 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. #Default: -# authenticate_ip_ttl 0 seconds +# authenticate_ip_ttl 1 second # ACCESS CONTROLS # ----------------------------------------------------------------------------- @@ -381,31 +486,66 @@ # # ttl=n TTL in seconds for cached results (defaults to 3600 # for 1 hour) +# # negative_ttl=n # TTL for cached negative lookups (default same # as ttl) -# children=n Number of acl helper processes spawn to service +# +# grace=n Percentage remaining of TTL where a refresh of a +# cached entry should be initiated without needing to +# wait for a new reply. (default is for no grace period) +# +# cache=n The maximum number of entries in the result cache. The +# default limit is 262144 entries. Each cache entry usually +# consumes at least 256 bytes. Squid currently does not remove +# expired cache entries until the limit is reached, so a proxy +# will sooner or later reach the limit. The expanded FORMAT +# value is used as the cache key, so if the details in FORMAT +# are highly variable, a larger cache may be needed to produce +# reduction in helper load. +# +# children-max=n +# Maximum number of acl helper processes spawned to service # external acl lookups of this type. (default 5) +# +# children-startup=n +# Minimum number of acl helper processes to spawn during +# startup and reconfigure to service external acl lookups +# of this type. (default 0) +# +# children-idle=n +# Number of acl helper processes to keep ahead of traffic +# loads. Squid will spawn this many at once whenever load +# rises above the capabilities of existing processes. +# Up to the value of children-max. (default 1) +# # concurrency=n concurrency level per process. Only used with helpers # capable of processing more than one query at a time. -# cache=n result cache size, 0 is unbounded (default) -# grace=n Percentage remaining of TTL where a refresh of a -# cached entry should be initiated without needing to -# wait for a new reply. (default 0 for no grace period) -# protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers +# +# protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers. +# # ipv4 / ipv6 IP protocol used to communicate with this helper. # The default is to auto-detect IPv6 and use it when available. # +# # FORMAT specifications # # %LOGIN Authenticated user login name -# %EXT_USER Username from external acl +# %un A user name. Expands to the first available name +# from the following list of information sources: +# - authenticated user name, like %ul or %LOGIN +# - user name sent by an external ACL, like %EXT_USER +# - SSL client name, like %us in logformat +# - ident user name, like %ui in logformat +# %EXT_USER Username from previous external acl +# %EXT_LOG Log details from previous external acl +# %EXT_TAG Tag from previous external acl # %IDENT Ident user name # %SRC Client IP # %SRCPORT Client source port # %URI Requested URI # %DST Requested host -# %PROTO Requested protocol +# %PROTO Requested URL scheme # %PORT Requested port # %PATH Requested URL path # %METHOD Request method @@ -415,7 +555,10 @@ # %USER_CERT SSL User certificate in PEM format # %USER_CERTCHAIN SSL User certificate chain in PEM format # %USER_CERT_xx SSL User certificate subject attribute xx -# %USER_CA_xx SSL User certificate issuer attribute xx +# %USER_CA_CERT_xx SSL User certificate issuer attribute xx +# %ssl::>sni SSL client SNI sent to Squid +# %ssl::<cert_subject SSL server certificate DN +# %ssl::<cert_issuer SSL server certificate issuer DN # # %>{Header} HTTP request header "Header" # %>{Hdr:member} @@ -433,43 +576,101 @@ # 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. +# clt_conn_tag= Associates a TAG with the client TCP connection. +# Please see url_rewrite_program related documentation +# for this kv-pair. # -# 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. +# Any keywords may be sent on any response whether OK, ERR or BH. # -# 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. +# 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. +# +# Some example key values: +# +# user=John%20Smith +# user="John Smith" +# user="J. \"Bob\" Smith" #Default: # none @@ -485,9 +686,23 @@ # # 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. @@ -498,29 +713,31 @@ # # ***** ACL TYPES AVAILABLE ***** # -# acl aclname src ip-address/netmask ... # clients IP address [fast] -# acl aclname src addr1-addr2/netmask ... # range of addresses [fast] -# acl aclname dst ip-address/netmask ... # URL host's IP address [slow] -# acl aclname myip ip-address/netmask ... # local socket IP address [fast] +# acl aclname src ip-address/mask ... # clients IP address [fast] +# acl aclname src addr1-addr2/mask ... # range of addresses [fast] +# 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) -# # The arp ACL requires the special configure option --enable-arp-acl. -# # Furthermore, the ARP ACL code is not portable to all operating systems. -# # It works on Linux, Solaris, Windows, FreeBSD, and some -# # other *BSD variants. # # [fast] +# # The 'arp' ACL code is not portable to all operating systems. +# # It works on Linux, Solaris, Windows, FreeBSD, and some other +# # BSD variants. # # -# # NOTE: Squid can only determine the MAC address for clients that are on -# # the same subnet. If the client is on a different subnet, -# # then Squid cannot find out its MAC address. +# # NOTE: Squid can only determine the MAC/EUI address for IPv4 +# # clients that are on the same subnet. If the client is on a +# # different subnet, then Squid cannot find out its address. +# # +# # NOTE 2: IPv6 protocol does not contain ARP. MAC/EUI is either +# # encoded directly in the IPv6 address or not available. # # acl aclname srcdomain .foo.com ... # # reverse lookup, from client IP [slow] -# acl aclname 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 @@ -557,13 +774,17 @@ # # 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] # # acl aclname port 80 70 21 0-1024... # destination TCP port [fast] # # ranges are alloed -# acl aclname myport 3128 ... # local socket TCP port [fast] -# acl aclname myportname 3128 ... # http(s)_port name [fast] +# acl aclname localport 3128 ... # TCP port the client connected to [fast] +# # NP: for interception mode this is usually '80' +# +# acl aclname myportname 3128 ... # *_port name [fast] # # acl aclname proto HTTP FTP ... # request protocol [fast] # @@ -632,6 +853,11 @@ # # clients may appear to come from multiple addresses if they are # # going through proxy farms, so a limit of 1 may cause user problems. # +# acl aclname random probability +# # Pseudo-randomly match requests. Based on the probability given. +# # Probability may be written as a decimal (0.333), fraction (1/3) +# # or ratio of matches:non-matches (3:5). +# # acl aclname req_mime_type [-i] mime-type ... # # regex match against the mime type of the request generated # # by the client. Can be used to detect file upload or some @@ -663,11 +889,11 @@ # # acl aclname user_cert attribute values... # # match against attributes in a user SSL certificate -# # attribute is one of DN/C/O/CN/L/ST [fast] +# # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] # # acl aclname ca_cert attribute values... # # match against attributes a users issuing CA SSL certificate -# # attribute is one of DN/C/O/CN/L/ST [fast] +# # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] # # acl aclname ext_user username ... # acl aclname ext_user_regex [-i] pattern ... @@ -675,7 +901,59 @@ # # use REQUIRED to accept any non-null user name. # # acl aclname tag tagvalue ... -# # string match on tag returned by external acl helper [slow] +# # string match on tag returned by external acl helper [fast] +# # DEPRECATED. Only the first tag will match with this ACL. +# # Use the 'note' ACL instead for handling multiple tag values. +# +# acl aclname hier_code codename ... +# # string match against squid hierarchy code(s); [fast] +# # e.g., DIRECT, PARENT_HIT, NONE, etc. +# # +# # NOTE: This has no effect in http_access rules. It only has +# # effect in rules that affect the reply data stream such as +# # http_reply_access. +# +# acl aclname note name [value ...] +# # match transaction annotation [fast] +# # Without values, matches any annotation with a given name. +# # With value(s), matches any annotation with a given name that +# # also has one of the given values. +# # Names and values are compared using a string equality test. +# # Annotation sources include note and adaptation_meta directives +# # as well as helper and eCAP responses. +# +# acl aclname adaptation_service service ... +# # Matches the name of any icap_service, ecap_service, +# # adaptation_service_set, or adaptation_service_chain that Squid +# # has used (or attempted to use) for the master transaction. +# # This ACL must be defined after the corresponding adaptation +# # service is named in squid.conf. This ACL is usable with +# # adaptation_meta because it starts matching immediately after +# # the service has been selected for adaptation. +# +# acl aclname any-of acl1 acl2 ... +# # match any one of the acls [fast or slow] +# # The first matching ACL stops further ACL evaluation. +# # +# # ACLs from multiple any-of lines with the same name are ORed. +# # For example, A = (a1 or a2) or (a3 or a4) can be written as +# # acl A any-of a1 a2 +# # acl A any-of a3 a4 +# # +# # This group ACL is fast if all evaluated ACLs in the group are fast +# # and slow otherwise. +# +# acl aclname all-of acl1 acl2 ... +# # match all of the acls [fast or slow] +# # The first mismatching ACL stops further ACL evaluation. +# # +# # ACLs from multiple all-of lines with the same name are ORed. +# # For example, B = (b1 and b2) or (b3 and b4) can be written as +# # acl B all-of b1 b2 +# # acl B all-of b3 b4 +# # +# # This group ACL is fast if all evaluated ACLs in the group are fast +# # and slow otherwise. # # Examples: # acl macaddress arp 09:00:2b:23:45:67 @@ -685,14 +963,11 @@ # acl javascript rep_mime_type -i ^application/x-javascript$ # #Default: -# acl all src all +# ACLs all, manager, localhost, and to_localhost are predefined. # # # Recommended minimum configuration: -# (now built-in) -#acl manager proto cache_object -#acl localhost src 127.0.0.1/32 ::1 -#acl to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1 +# # Example rule allowing access from your local networks. # Adapt to list your (internal) IP networks from where browsing @@ -716,39 +991,83 @@ acl Safe_ports port 591 # filemaker acl Safe_ports port 777 # multiling http acl CONNECT method CONNECT +# TAG: proxy_protocol_access +# Determine which client proxies can be trusted to provide correct +# information regarding real client IP address using PROXY protocol. +# +# Requests may pass through a chain of several other proxies +# before reaching us. The original source details may by sent in: +# * HTTP message Forwarded header, or +# * HTTP message X-Forwarded-For header, or +# * PROXY protocol connection header. +# +# This directive is solely for validating new PROXY protocol +# connections received from a port flagged with require-proxy-header. +# It is checked only once after TCP connection setup. +# +# A deny match results in TCP connection closure. +# +# An allow match is required for Squid to permit the corresponding +# TCP connection, before Squid even looks for HTTP request headers. +# If there is an allow match, Squid starts using PROXY header information +# to determine the source address of the connection for all future ACL +# checks, logging, etc. +# +# SECURITY CONSIDERATIONS: +# +# Any host from which we accept client IP details can place +# incorrect information in the relevant header, and Squid +# will use the incorrect information as if it were the +# source address of the request. This may enable remote +# hosts to bypass any access control restrictions that are +# based on the client's source addresses. +# +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +#Default: +# all TCP connections to ports with require-proxy-header will be denied + # TAG: follow_x_forwarded_for -# Allowing or Denying the X-Forwarded-For header to be followed to -# find the original source of a request. +# Determine which client proxies can be trusted to provide correct +# information regarding real client IP address. # # Requests may pass through a chain of several other proxies -# before reaching us. The X-Forwarded-For header will contain a -# comma-separated list of the IP addresses in the chain, with the -# rightmost address being the most recent. +# before reaching us. The original source details may by sent in: +# * HTTP message Forwarded header, or +# * HTTP message X-Forwarded-For header, or +# * PROXY protocol connection header. +# +# PROXY protocol connections are controlled by the proxy_protocol_access +# directive which is checked before this. # # If a request reaches us from a source that is allowed by this -# configuration item, then we consult the X-Forwarded-For header -# to see where that host received the request from. If the -# X-Forwarded-For header contains multiple addresses, we continue -# backtracking until we reach an address for which we are not allowed -# to follow the X-Forwarded-For header, or until we reach the first -# address in the list. For the purpose of ACL used in the -# follow_x_forwarded_for directive the src ACL type always matches -# the address we are testing and srcdomain matches its rDNS. +# directive, then we trust the information it provides regarding +# the IP of the client it received from (if any). +# +# For the purpose of ACLs used in this directive the src ACL type always +# matches the address we are testing and srcdomain matches its rDNS. +# +# On each HTTP request Squid checks for X-Forwarded-For header fields. +# If found the header values are iterated in reverse order and an allow +# match is required for Squid to continue on to the next value. +# The verification ends when a value receives a deny match, cannot be +# tested, or there are no more values to test. +# NOTE: Squid does not yet follow the Forwarded HTTP header. # # The end result of this process is an IP address that we will # refer to as the indirect client address. This address may # be treated as the client address for access control, ICAP, delay # pools and logging, depending on the acl_uses_indirect_client, -# icap_uses_indirect_client, delay_pool_uses_indirect_client and -# log_uses_indirect_client options. +# icap_uses_indirect_client, delay_pool_uses_indirect_client, +# log_uses_indirect_client and tproxy_uses_indirect_client options. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # # SECURITY CONSIDERATIONS: # -# Any host for which we follow the X-Forwarded-For header -# can place incorrect information in the header, and Squid +# Any host from which we accept client IP details can place +# incorrect information in the relevant header, and Squid # will use the incorrect information as if it were the # source address of the request. This may enable remote # hosts to bypass any access control restrictions that are @@ -761,7 +1080,7 @@ acl CONNECT method CONNECT # follow_x_forwarded_for allow localhost # follow_x_forwarded_for allow my_other_proxy #Default: -# follow_x_forwarded_for deny all +# X-Forwarded-For header will be ignored. # TAG: acl_uses_indirect_client on|off # Controls whether the indirect client address @@ -787,10 +1106,41 @@ acl CONNECT method CONNECT #Default: # log_uses_indirect_client on +# TAG: tproxy_uses_indirect_client on|off +# Controls whether the indirect client address +# (see follow_x_forwarded_for) is used instead of the +# direct client address when spoofing the outgoing client. +# +# This has no effect on requests arriving in non-tproxy +# mode ports. +# +# SECURITY WARNING: Usage of this option is dangerous +# and should not be used trivially. Correct configuration +# of follow_x_forwarded_for with a limited set of trusted +# sources is required to prevent abuse of your proxy. +#Default: +# tproxy_uses_indirect_client off + +# TAG: spoof_client_ip +# 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. +#Default: +# Allow spoofing on all TPROXY traffic. + # TAG: http_access # Allowing or Denying access based on defined access lists # -# Access to the HTTP port: +# To allow or deny a message received on an HTTP, HTTPS, or FTP port: # http_access allow|deny [!]aclname ... # # NOTE on default values: @@ -809,22 +1159,22 @@ acl CONNECT method CONNECT # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # #Default: -# http_access deny all +# Deny, unless rules exist in squid.conf. # # # Recommended minimum Access Permission configuration: # -# Only allow cachemgr access from localhost -http_access allow manager localhost -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 @@ -852,7 +1202,7 @@ http_access deny all # # If not set then only http_access is used. #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: http_reply_access # Allow replies to client requests. This is complementary to http_access. @@ -860,7 +1210,7 @@ http_access deny all # 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 @@ -869,7 +1219,7 @@ http_access deny all # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: icp_access # Allowing or Denying access to the ICP port based on defined @@ -877,7 +1227,9 @@ http_access deny all # # 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. @@ -886,7 +1238,7 @@ http_access deny all ##icp_access allow localnet ##icp_access deny all #Default: -# icp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: htcp_access # Allowing or Denying access to the HTCP port based on defined @@ -894,11 +1246,12 @@ http_access deny all # # 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 -# using the htcp or htcp-oldsquid options. +# using the htcp option. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. @@ -907,48 +1260,47 @@ http_access deny all ##htcp_access allow localnet ##htcp_access deny all #Default: -# htcp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: htcp_clr_access # 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 #Default: -# htcp_clr_access deny all +# Deny, unless rules exist in squid.conf. # TAG: miss_access -# Determins whether network access is permitted when satisfying a request. +# Determines whether network access is permitted when satisfying a request. # # For example; # to force your neighbors to use you as a sibling instead of # 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. # # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# miss_access allow all +# Allow, unless rules exist in squid.conf. # TAG: ident_lookup_access # A list of ACL elements which, if matched, cause an ident @@ -972,7 +1324,7 @@ http_access deny all # This clause only supports fast acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# ident_lookup_access deny all +# Unless rules exist in squid.conf, IDENT is not fetched. # TAG: reply_body_max_size size [acl acl...] # This option specifies the maximum size of a reply body. It can be @@ -1009,23 +1361,22 @@ http_access deny all # reply_body_max_size 10 MB # #Default: -# none +# No limit is applied. # NETWORK OPTIONS # ----------------------------------------------------------------------------- # TAG: http_port -# Usage: port [options] -# hostname:port [options] -# 1.2.3.4:port [options] +# Usage: port [mode] [options] +# hostname:port [mode] [options] +# 1.2.3.4:port [mode] [options] # # The socket addresses where Squid will listen for HTTP client # requests. You may specify multiple socket addresses. # There are three forms: port alone, hostname with port, and # IP address with port. If you specify a hostname or IP # address, Squid binds the socket to that specific -# address. This replaces the old 'tcp_incoming_address' -# option. Most likely, you do not need to bind to a specific +# address. Most likely, you do not need to bind to a specific # address, so you can use the port number alone. # # If you are running Squid in accelerator mode, you @@ -1037,48 +1388,184 @@ http_access deny all # # You may specify multiple socket addresses on multiple lines. # -# Options: +# Modes: # -# intercept Support for IP-Layer interception of -# outgoing requests without browser settings. -# NP: disables authentication and IPv6 on the port. +# intercept Support for IP-Layer NAT interception delivering +# traffic to this Squid port. +# NP: disables authentication on the port. # -# tproxy Support Linux TPROXY for spoofing outgoing -# connections using the client IP address. -# NP: disables authentication and maybe IPv6 on the port. +# tproxy Support Linux TPROXY (or BSD divert-to) with spoofing +# of outgoing connections using the client IP address. +# NP: disables authentication on the port. # -# accel Accelerator mode. Also needs at least one of -# vhost / vport / defaultsite. +# accel Accelerator / reverse proxy mode +# +# ssl-bump For each CONNECT request allowed by ssl_bump ACLs, +# establish secure connection with the client and with +# the server, decrypt HTTPS messages as they pass through +# Squid, and treat them as unencrypted HTTP messages, +# becoming the man-in-the-middle. +# +# The ssl_bump option is required to fully enable +# bumping of CONNECT requests. +# +# Omitting the mode flag causes default forward proxy mode to be used. # -# allow-direct Allow direct forwarding in accelerator mode. Normally -# accelerated requests are denied direct forwarding as if -# never_direct was used. +# +# Accelerator Mode Options: # # defaultsite=domainname # What to use for the Host: header if it is not present # in a request. Determines what site (not origin server) # accelerators should consider the default. -# Implies accel. # -# vhost Accelerator mode using Host header for virtual domain support. -# Also uses the port as specified in Host: header unless -# overridden by the vport option. Implies accel. +# no-vhost Disable using HTTP/1.1 Host header for virtual domain support. +# +# protocol= Protocol to reconstruct accelerated and intercepted +# requests with. Defaults to HTTP/1.1 for http_port and +# HTTPS/1.1 for https_port. +# When an unsupported value is configured Squid will +# produce a FATAL error. +# Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1 # # vport Virtual host port support. Using the http_port number -# instead of the port passed on Host: headers. Implies accel. +# instead of the port passed on Host: headers. # # vport=NN Virtual host port support. Using the specified port # number instead of the port passed on Host: headers. -# Implies accel. # -# protocol= Protocol to reconstruct accelerated requests with. -# Defaults to http. +# act-as-origin +# Act as if this Squid is the origin server. +# This currently means generate new Date: and Expires: +# headers on HIT instead of adding Age:. # # ignore-cc Ignore request Cache-Control headers. # -# Warning: This option violates HTTP specifications if +# WARNING: This option violates HTTP specifications if # used in non-accelerator setups. # +# allow-direct Allow direct forwarding in accelerator mode. Normally +# accelerated requests are denied direct forwarding as if +# never_direct was used. +# +# WARNING: this option opens accelerator mode to security +# vulnerabilities usually only affecting in interception +# mode. Make sure to protect forwarding with suitable +# http_access rules when using this. +# +# +# SSL Bump Mode Options: +# In addition to these options ssl-bump requires TLS/SSL options. +# +# generate-host-certificates[=<on|off>] +# Dynamically create SSL server certificates for the +# destination hosts of bumped CONNECT requests.When +# enabled, the cert and key options are used to sign +# generated certificates. Otherwise generated +# certificate will be selfsigned. +# If there is a CA certificate lifetime of the generated +# certificate equals lifetime of the CA certificate. If +# generated certificate is selfsigned lifetime is three +# years. +# This option is disabled by default. See the ssl-bump +# option above for more information. +# +# dynamic_cert_mem_cache_size=SIZE +# Approximate total RAM size spent on cached generated +# certificates. If set to zero, caching is disabled. +# +# TLS / SSL Options: +# +# cert= Path to SSL certificate (PEM format). +# +# key= Path to SSL private key file (PEM format) +# if not specified, the certificate file is +# assumed to be a combined certificate and +# key file. +# +# version= The version of SSL/TLS supported +# 1 automatic (default) +# 2 SSLv2 only +# 3 SSLv3 only +# 4 TLSv1.0 only +# 5 TLSv1.1 only +# 6 TLSv1.2 only +# +# cipher= Colon separated list of supported ciphers. +# NOTE: some ciphers such as EDH ciphers depend on +# additional settings. If those settings are +# omitted the ciphers may be silently ignored +# by the OpenSSL library. +# +# options= Various SSL implementation options. The most important +# being: +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# SINGLE_DH_USE Always create a new key when using +# temporary/ephemeral DH key exchanges +# NO_TICKET Disables TLS tickets extension +# +# SINGLE_ECDH_USE +# Enable ephemeral ECDH key exchange. +# The adopted curve should be specified +# using the tls-dh option. +# +# ALL Enable various bug workarounds +# suggested as "harmless" by OpenSSL +# Be warned that this reduces SSL/TLS +# strength to some attacks. +# See OpenSSL SSL_CTX_set_options documentation for a +# complete list of options. +# +# clientca= File containing the list of CAs to use when +# requesting a client certificate. +# +# cafile= File containing additional CA certificates to +# use when verifying client certificates. If unset +# clientca will be used. +# +# capath= Directory containing additional CA certificates +# and CRL lists to use when verifying client certificates. +# +# crlfile= File of additional CRL lists to use when verifying +# the client certificate, in addition to CRLs stored in +# the capath. Implies VERIFY_CRL flag below. +# +# tls-dh=[curve:]file +# File containing DH parameters for temporary/ephemeral DH key +# exchanges, optionally prefixed by a curve for ephemeral ECDH +# key exchanges. +# See OpenSSL documentation for details on how to create the +# DH parameter file. Supported curves for ECDH can be listed +# using the "openssl ecparam -list_curves" command. +# WARNING: EDH and EECDH ciphers will be silently disabled if +# this option is not set. +# +# sslflags= Various flags modifying the use of SSL: +# DELAYED_AUTH +# Don't request client certificates +# immediately, but wait until acl processing +# requires a certificate (not yet implemented). +# NO_DEFAULT_CA +# Don't use the default CA lists built in +# to OpenSSL. +# NO_SESSION_REUSE +# Don't allow for session reuse. Each connection +# will result in a new SSL session. +# VERIFY_CRL +# Verify CRL lists when accepting client +# certificates. +# VERIFY_CRL_ALL +# Verify CRL lists for all certificates in the +# client certificate chain. +# +# sslcontext= SSL session ID context identifier. +# +# Other Options: +# # connection-auth[=on|off] # use connection-auth=off to tell Squid to prevent # forwarding Microsoft connection oriented authentication @@ -1100,22 +1587,6 @@ http_access deny all # sporadically hang or never complete requests set # disable-pmtu-discovery option to 'transparent'. # -# ssl-bump Intercept each CONNECT request matching ssl_bump ACL, -# establish secure connection with the client and with -# the server, decrypt HTTP messages as they pass through -# Squid, and treat them as unencrypted HTTP messages, -# becoming the man-in-the-middle. -# -# When this option is enabled, additional options become -# available to specify SSL-related properties of the -# client-side connection: cert, key, version, cipher, -# options, clientca, cafile, capath, crlfile, dhparams, -# sslflags, and sslcontext. See the https_port directive -# for more information on these options. -# -# The ssl_bump option is required to fully enable -# the SslBump feature. -# # name= Specifies a internal name for the port. Defaults to # the port specification (port or addr:port) # @@ -1125,6 +1596,11 @@ http_access deny all # probing the connection, interval how often to probe, and # timeout the time before giving up. # +# require-proxy-header +# Require PROXY protocol version 1 or 2 connections. +# The proxy_protocol_access is required to whitelist +# downstream proxies which can be trusted. +# # If you run Squid on a dual-homed machine with an internal # and an external interface we recommend you to specify the # internal address:port in http_port. This way Squid will only be @@ -1137,35 +1613,49 @@ http_port 3128 # TAG: https_port # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...] +# Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...] # -# The socket address where Squid will listen for HTTPS client -# requests. +# The socket address where Squid will listen for client requests made +# over TLS or SSL connections. Commonly referred to as HTTPS. # -# This is really only useful for situations where you are running -# squid in accelerator mode and you want to do the SSL work at the -# accelerator level. +# This is most useful for situations where you are running squid in +# accelerator mode and you want to do the SSL work at the accelerator level. # # You may specify multiple socket addresses on multiple lines, # each with their own SSL certificate and/or options. # -# Options: +# Modes: +# +# 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. +# +# ssl-bump For each intercepted connection allowed by ssl_bump +# ACLs, establish a secure connection with the client and with +# the server, decrypt HTTPS messages as they pass through +# Squid, and treat them as unencrypted HTTP messages, +# becoming the man-in-the-middle. # -# accel Accelerator mode. Also needs at least one of -# defaultsite or vhost. +# An "ssl_bump server-first" match is required to +# fully enable bumping of intercepted SSL connections. # -# defaultsite= The name of the https site presented on -# this port. Implies accel. +# Requires tproxy or intercept. # -# vhost Accelerator mode using Host header for virtual -# domain support. Requires a wildcard certificate -# or other certificate valid for more than one domain. -# Implies accel. +# Omitting the mode flag causes default forward proxy mode to be used. # -# protocol= Protocol to reconstruct accelerated requests with. -# Defaults to https. +# +# See http_port for a list of generic options +# +# +# SSL Options: # # cert= Path to SSL certificate (PEM format). # @@ -1181,20 +1671,23 @@ http_port 3128 # 4 TLSv1 only # # cipher= Colon separated list of supported ciphers. -# NOTE: some ciphers such as EDH ciphers depend on -# additional settings. If those settings are -# omitted the ciphers may be silently ignored -# by the OpenSSL library. # # options= Various SSL engine options. The most important # being: # NO_SSLv2 Disallow the use of SSLv2 # NO_SSLv3 Disallow the use of SSLv3 # NO_TLSv1 Disallow the use of TLSv1 +# # SINGLE_DH_USE Always create a new key when using # temporary/ephemeral DH key exchanges -# See OpenSSL SSL_CTX_set_options documentation for a -# complete list of options. +# +# SINGLE_ECDH_USE +# Enable ephemeral ECDH key exchange. +# The adopted curve should be specified +# using the tls-dh option. +# +# See src/ssl_support.c or OpenSSL SSL_CTX_set_options +# documentation for a complete list of options. # # clientca= File containing the list of CAs to use when # requesting a client certificate. @@ -1210,11 +1703,10 @@ http_port 3128 # the client certificate, in addition to CRLs stored in # the capath. Implies VERIFY_CRL flag below. # -# dhparams= File containing DH parameters for temporary/ephemeral -# DH key exchanges. See OpenSSL documentation for details -# on how to create this file. -# WARNING: EDH ciphers will be silently disabled if this -# option is not set. +# tls-dh=[curve:]file +# File containing DH parameters for temporary/ephemeral DH key +# exchanges, optionally prefixed by a curve for ephemeral ECDH +# key exchanges. # # sslflags= Various flags modifying the use of SSL: # DELAYED_AUTH @@ -1238,38 +1730,89 @@ http_port 3128 # # generate-host-certificates[=<on|off>] # Dynamically create SSL server certificates for the -# destination hosts of bumped CONNECT requests.When +# destination hosts of bumped SSL requests.When # enabled, the cert and key options are used to sign # generated certificates. Otherwise generated # certificate will be selfsigned. -# If there is CA certificate life time of generated +# If there is CA certificate life time of generated # certificate equals lifetime of CA certificate. If -# generated certificate is selfsigned lifetime is three +# generated certificate is selfsigned lifetime is three # years. -# This option is enabled by default when SslBump is used. -# See the sslBump option above for more information. -# +# This option is disabled by default. See the ssl-bump +# option above for more information. +# # dynamic_cert_mem_cache_size=SIZE # Approximate total RAM size spent on cached generated -# certificates. If set to zero, caching is disabled. The -# default value is 4MB. An average XXX-bit certificate -# consumes about XXX bytes of RAM. +# certificates. If set to zero, caching is disabled. # -# vport Accelerator with IP based virtual host support. +# See http_port for a list of available options. +#Default: +# none + +# TAG: ftp_port +# Enables Native FTP proxy by specifying the socket address where Squid +# listens for FTP client requests. See http_port directive for various +# ways to specify the listening address and mode. # -# vport=NN As above, but uses specified port number rather -# than the https_port number. Implies accel. +# Usage: ftp_port address [mode] [options] # -# name= Specifies a internal name for the port. Defaults to -# the port specification (port or addr:port) +# WARNING: This is a new, experimental, complex feature that has seen +# limited production exposure. Some Squid modules (e.g., caching) do not +# currently work with native FTP proxying, and many features have not +# even been tested for compatibility. Test well before deploying! +# +# Native FTP proxying differs substantially from proxying HTTP requests +# with ftp:// URIs because Squid works as an FTP server and receives +# actual FTP commands (rather than HTTP requests with FTP URLs). +# +# Native FTP commands accepted at ftp_port are internally converted or +# wrapped into HTTP-like messages. The same happens to Native FTP +# responses received from FTP origin servers. Those HTTP-like messages +# are shoveled through regular access control and adaptation layers +# between the FTP client and the FTP origin server. This allows Squid to +# examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP +# mechanisms when shoveling wrapped FTP messages. For example, +# http_access and adaptation_access directives are used. # +# Modes: +# +# intercept Same as http_port intercept. The FTP origin address is +# determined based on the intended destination of the +# intercepted connection. +# +# tproxy Support Linux TPROXY for spoofing outgoing +# connections using the client IP address. +# NP: disables authentication and maybe IPv6 on the port. +# +# By default (i.e., without an explicit mode option), Squid extracts the +# FTP origin address from the login@origin parameter of the FTP USER +# command. Many popular FTP clients support such native FTP proxying. +# +# Options: +# +# name=token Specifies an internal name for the port. Defaults to +# the port address. Usable with myportname ACL. +# +# ftp-track-dirs +# Enables tracking of FTP directories by injecting extra +# PWD commands and adjusting Request-URI (in wrapping +# HTTP requests) to reflect the current FTP server +# directory. Tracking is disabled by default. +# +# protocol=FTP Protocol to reconstruct accelerated and intercepted +# requests with. Defaults to FTP. No other accepted +# values have been tested with. An unsupported value +# results in a FATAL error. Accepted values are FTP, +# HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1). +# +# Other http_port modes and options that are not specific to HTTP and +# HTTPS may also work. #Default: # none # TAG: tcp_outgoing_tos -# Allows you to select a TOS/Diffserv value to mark outgoing -# connections with, based on the username or source address -# making the request. +# Allows you to select a TOS/Diffserv value for packets outgoing +# on the server side, based on an ACL. # # tcp_outgoing_tos ds-field [!]aclname ... # @@ -1286,41 +1829,116 @@ http_port 3128 # RFC2475, and RFC3260. # # The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or -# "default" to use whatever default your host has. Note that in -# practice often only multiples of 4 is usable as the two rightmost bits -# have been redefined for use by ECN (RFC 3168 section 23.1). +# "default" to use whatever default your host has. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. # # Processing proceeds in the order specified, and stops at first fully # matching line. # -# Note: The use of this directive using client dependent ACLs is -# incompatible with the use of server side persistent connections. To -# ensure correct results it is best to set server_persistent_connections -# to off when using this directive in such configurations. +# Only fast ACLs are supported. #Default: # none # TAG: clientside_tos -# Allows you to select a TOS/Diffserv value to mark client-side -# connections with, based on the username or source address -# making the request. +# Allows you to select a TOS/DSCP value for packets being transmitted +# on the client-side, based on an ACL. +# +# clientside_tos ds-field [!]aclname ... +# +# Example where normal_service_net uses the TOS value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# clientside_tos 0x00 normal_service_net +# clientside_tos 0x20 good_service_net +# +# Note: This feature is incompatible with qos_flows. Any TOS values set here +# will be overwritten by TOS values in qos_flows. +# +# The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or +# "default" to use whatever default your host has. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. +# +#Default: +# none + +# TAG: tcp_outgoing_mark +# Note: This option is only available if Squid is rebuilt with the +# Packet MARK (Linux) +# +# Allows you to apply a Netfilter mark value to outgoing packets +# on the server side, based on an ACL. +# +# tcp_outgoing_mark mark-value [!]aclname ... +# +# Example where normal_service_net uses the mark value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# tcp_outgoing_mark 0x00 normal_service_net +# tcp_outgoing_mark 0x20 good_service_net +# +# Only fast ACLs are supported. +#Default: +# none + +# TAG: clientside_mark +# Note: This option is only available if Squid is rebuilt with the +# Packet MARK (Linux) +# +# Allows you to apply a Netfilter mark value to packets being transmitted +# on the client-side, based on an ACL. +# +# clientside_mark mark-value [!]aclname ... +# +# Example where normal_service_net uses the mark value 0x00 +# and good_service_net uses 0x20 +# +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.1.0/24 +# clientside_mark 0x00 normal_service_net +# clientside_mark 0x20 good_service_net +# +# Note: This feature is incompatible with qos_flows. Any mark values set here +# will be overwritten by mark values in qos_flows. #Default: # none # TAG: qos_flows # Allows you to select a TOS/DSCP value to mark outgoing -# connections with, based on where the reply was sourced. +# connections to the client, based on where the reply was sourced. +# For platforms using netfilter, allows you to set a netfilter mark +# value instead of, or in addition to, a TOS value. +# +# By default this functionality is disabled. To enable it with the default +# settings simply use "qos_flows mark" or "qos_flows tos". Default +# settings will result in the netfilter mark or TOS value being copied +# from the upstream connection to the client. Note that it is the connection +# CONNMARK value not the packet MARK value that is copied. +# +# It is not currently possible to copy the mark or TOS value from the +# client to the upstream connection request. # # TOS values really only have local significance - so you should # know what you're specifying. For more information, see RFC2474, # RFC2475, and RFC3260. # -# The TOS/DSCP byte must be exactly that - octet value 0x00-0xFF. -# Note that in practice often only values up to 0x3F are usable -# as the two highest bits have been redefined for use by ECN -# (RFC3168). +# The TOS/DSCP byte must be exactly that - a octet value 0 - 255. +# Note that only multiples of 4 are usable as the two rightmost bits have +# been redefined for use by ECN (RFC 3168 section 23.1). +# The squid parser will enforce this by masking away the ECN bits. +# +# Mark values can be any unsigned 32-bit integer value. +# +# This setting is configured by setting the following values: # -# This setting is configured by setting the source TOS values: +# tos|mark Whether to set TOS or netfilter mark values # # local-hit=0xFF Value to mark local cache hits. # @@ -1328,23 +1946,37 @@ http_port 3128 # # parent-hit=0xFF Value to mark hits from parent peers. # +# miss=0xFF[/mask] Value to mark cache misses. Takes precedence +# over the preserve-miss feature (see below), unless +# mask is specified, in which case only the bits +# specified in the mask are written. # -# NOTE: 'miss' preserve feature is only possible on Linux at this time. -# -# For the following to work correctly, you will need to patch your -# linux kernel with the TOS preserving ZPH patch. -# The kernel patch can be downloaded from http://zph.bratcheda.org +# The TOS variant of the following features are only possible on Linux +# and require your kernel to be patched with the TOS preserving ZPH +# patch, available from http://zph.bratcheda.org +# No patch is needed to preserve the netfilter mark, which will work +# with all variants of netfilter. # # disable-preserve-miss -# By default, the existing TOS value of the response coming -# from the remote server will be retained and masked with -# miss-mark. This option disables that feature. +# This option disables the preservation of the TOS or netfilter +# mark. By default, the existing TOS or netfilter mark value of +# the response coming from the remote server will be retained +# and masked with miss-mark. +# NOTE: in the case of a netfilter mark, the mark must be set on +# the connection (using the CONNMARK target) not on the packet +# (MARK target). # # miss-mask=0xFF -# Allows you to mask certain bits in the TOS received from the -# remote server, before copying the value to the TOS sent -# towards clients. -# Default: 0xFF (TOS from server is not changed). +# Allows you to mask certain bits in the TOS or mark value +# received from the remote server, before copying the value to +# the TOS sent towards clients. +# Default for tos: 0xFF (TOS from server is not changed). +# Default for mark: 0xFFFFFFFF (mark from server is not changed). +# +# All of these features require the --enable-zph-qos compilation flag +# (enabled by default). Netfilter marking also requires the +# libnetfilter_conntrack libraries (--with-netfilter-conntrack) and +# libcap 2.09+ (--with-libcap). # #Default: # none @@ -1356,72 +1988,133 @@ http_port 3128 # # tcp_outgoing_address ipaddr [[!]aclname] ... # -# Example where requests from 10.0.0.0/24 will be forwarded -# with source address 10.1.0.1, 10.0.2.0/24 forwarded with -# source address 10.1.0.2 and the rest will be forwarded with -# source address 10.1.0.3. -# -# acl normal_service_net src 10.0.0.0/24 -# acl good_service_net src 10.0.2.0/24 -# tcp_outgoing_address 10.1.0.1 normal_service_net -# tcp_outgoing_address 10.1.0.2 good_service_net -# tcp_outgoing_address 10.1.0.3 -# -# Processing proceeds in the order specified, and stops at first fully -# matching line. -# -# Note: The use of this directive using client dependent ACLs is -# incompatible with the use of server side persistent connections. To -# ensure correct results it is best to set server_persistent_connections -# to off when using this directive in such configurations. -# +# For example; +# Forwarding clients with dedicated IPs for certain subnets. # -# IPv6 Magic: +# acl normal_service_net src 10.0.0.0/24 +# acl good_service_net src 10.0.2.0/24 # -# Squid is built with a capability of bridging the IPv4 and IPv6 -# internets. -# tcp_outgoing_address as exampled above breaks this bridging by forcing -# all outbound traffic through a certain IPv4 which may be on the wrong -# side of the IPv4/IPv6 boundary. +# tcp_outgoing_address 2001:db8::c001 good_service_net +# tcp_outgoing_address 10.1.0.2 good_service_net # -# To operate with tcp_outgoing_address and keep the bridging benefits -# an additional ACL needs to be used which ensures the IPv6-bound traffic -# is never forced or permitted out the IPv4 interface. +# tcp_outgoing_address 2001:db8::beef normal_service_net +# tcp_outgoing_address 10.1.0.1 normal_service_net # -# # IPv6 destination test along with a dummy access control to perform the required DNS -# # This MUST be place before any ALLOW rules. -# acl to_ipv6 dst ipv6 -# http_access deny ipv6 !all +# tcp_outgoing_address 2001:db8::1 +# tcp_outgoing_address 10.1.0.3 # -# tcp_outgoing_address 2001:db8::c001 good_service_net to_ipv6 -# tcp_outgoing_address 10.1.0.2 good_service_net !to_ipv6 +# Processing proceeds in the order specified, and stops at first fully +# matching line. # -# tcp_outgoing_address 2001:db8::beef normal_service_net to_ipv6 -# tcp_outgoing_address 10.1.0.1 normal_service_net !to_ipv6 +# Squid will add an implicit IP version test to each line. +# Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses. +# Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses. # -# tcp_outgoing_address 2001:db8::1 to_ipv6 -# tcp_outgoing_address 10.1.0.3 !to_ipv6 # -# WARNING: -# 'dst ipv6' bases its selection assuming DIRECT access. -# If peers are used the peername ACL are needed to select outgoing -# address which can link to the peer. +# NOTE: The use of this directive using client dependent ACLs is +# incompatible with the use of server side persistent connections. To +# ensure correct results it is best to set server_persistent_connections +# to off when using this directive in such configurations. # -# 'dst ipv6' is a slow ACL. It will only work here if 'dst' is used -# previously in the http_access rules to locate the destination IP. -# Some more magic may be needed for that: -# http_access allow to_ipv6 !all -# (meaning, allow if to IPv6 but not from anywhere ;) +# NOTE: The use of this directive to set a local IP on outgoing TCP links +# is incompatible with using TPROXY to set client IP out outbound TCP links. +# When needing to contact peers use the no-tproxy cache_peer option and the +# client_dst_passthru directive re-enable normal forwarding such as this. # #Default: -# none +# Address selection is performed by the operating system. + +# TAG: host_verify_strict +# Regardless of this option setting, when dealing with intercepted +# traffic, Squid always verifies that the destination IP address matches +# the Host header domain or IP (called 'authority form URL'). +# +# This enforcement is performed to satisfy a MUST-level requirement in +# RFC 2616 section 14.23: "The Host field value MUST represent the naming +# authority of the origin server or gateway given by the original URL". +# +# When set to ON: +# Squid always responds with an HTTP 409 (Conflict) error +# page and logs a security warning if there is no match. +# +# Squid verifies that the destination IP address matches +# the Host header for forward-proxy and reverse-proxy traffic +# as well. For those traffic types, Squid also enables the +# following checks, comparing the corresponding Host header +# and Request-URI components: +# +# * The host names (domain or IP) must be identical, +# but valueless or missing Host header disables all checks. +# For the two host names to match, both must be either IP +# or FQDN. +# +# * Port numbers must be identical, but if a port is missing +# the scheme-default port is assumed. +# +# +# When set to OFF (the default): +# Squid allows suspicious requests to continue but logs a +# security warning and blocks caching of the response. +# +# * Forward-proxy traffic is not checked at all. +# +# * Reverse-proxy traffic is not checked at all. +# +# * Intercepted traffic which passes verification is handled +# according to client_dst_passthru. +# +# * Intercepted requests which fail verification are sent +# to the client original destination instead of DIRECT. +# This overrides 'client_dst_passthru off'. +# +# For now suspicious intercepted CONNECT requests are always +# responded to with an HTTP 409 (Conflict) error page. +# +# +# SECURITY NOTE: +# +# As described in CVE-2009-0801 when the Host: header alone is used +# to determine the destination of a request it becomes trivial for +# malicious scripts on remote websites to bypass browser same-origin +# security policy and sandboxing protections. +# +# The cause of this is that such applets are allowed to perform their +# own HTTP stack, in which case the same-origin policy of the browser +# sandbox only verifies that the applet tries to contact the same IP +# as from where it was loaded at the IP level. The Host: header may +# be different from the connected IP and approved origin. +# +#Default: +# host_verify_strict off + +# TAG: client_dst_passthru +# With NAT or TPROXY intercepted traffic Squid may pass the request +# directly to the original client destination IP or seek a faster +# source using the HTTP Host header. +# +# Using Host to locate alternative servers can provide faster +# connectivity with a range of failure recovery options. +# But can also lead to connectivity trouble when the client and +# server are attempting stateful interactions unaware of the proxy. +# +# This option (on by default) prevents alternative DNS entries being +# located to send intercepted traffic DIRECT to an origin server. +# The clients original destination IP and port will be used instead. +# +# Regardless of this option setting, when dealing with intercepted +# traffic Squid will verify the Host: header and any traffic which +# fails Host verification will be treated as if this option were ON. +# +# see host_verify_strict for details on the verification process. +#Default: +# client_dst_passthru on # SSL OPTIONS # ----------------------------------------------------------------------------- # TAG: ssl_unclean_shutdown # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Some browsers (especially MSIE) bugs out on SSL shutdown # messages. @@ -1430,7 +2123,7 @@ http_port 3128 # TAG: ssl_engine # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # The OpenSSL engine to use. You will need to set this if you # would like to use hardware SSL acceleration for example. @@ -1439,7 +2132,7 @@ http_port 3128 # TAG: sslproxy_client_certificate # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Client SSL Certificate to use when proxying https:// URLs #Default: @@ -1447,7 +2140,7 @@ http_port 3128 # TAG: sslproxy_client_key # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Client SSL Key to use when proxying https:// URLs #Default: @@ -1455,36 +2148,60 @@ http_port 3128 # TAG: sslproxy_version # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # SSL version level to use when proxying https:// URLs +# +# The versions of SSL/TLS supported: +# +# 1 automatic (default) +# 2 SSLv2 only +# 3 SSLv3 only +# 4 TLSv1.0 only +# 5 TLSv1.1 only +# 6 TLSv1.2 only #Default: -# sslproxy_version 1 +# automatic SSL/TLS version negotiation # TAG: sslproxy_options # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# SSL engine options to use when proxying https:// URLs +# Colon (:) or comma (,) separated list of SSL implementation options +# to use when proxying https:// URLs # # The most important being: # -# NO_SSLv2 Disallow the use of SSLv2 -# NO_SSLv3 Disallow the use of SSLv3 -# NO_TLSv1 Disallow the use of TLSv1 -# SINGLE_DH_USE -# Always create a new key when using -# temporary/ephemeral DH key exchanges +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# +# SINGLE_DH_USE +# Always create a new key when using temporary/ephemeral +# DH key exchanges +# +# NO_TICKET +# Disable use of RFC5077 session tickets. Some servers +# may have problems understanding the TLS extension due +# to ambiguous specification in RFC4507. +# +# ALL Enable various bug workarounds suggested as "harmless" +# by OpenSSL. Be warned that this may reduce SSL/TLS +# strength to some attacks. # -# These options vary depending on your SSL engine. # See the OpenSSL SSL_CTX_set_options documentation for a # complete list of possible options. +# +# WARNING: This directive takes a single token. If a space is used +# the value(s) after that space are SILENTLY IGNORED. #Default: # none # TAG: sslproxy_cipher # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # SSL cipher list to use when proxying https:// URLs # @@ -1494,7 +2211,7 @@ http_port 3128 # TAG: sslproxy_cafile # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # file containing CA certificates to use when verifying server # certificates while proxying https:// URLs @@ -1503,45 +2220,151 @@ http_port 3128 # TAG: sslproxy_capath # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # directory containing CA certificates to use when verifying # server certificates while proxying https:// URLs #Default: # none -# TAG: ssl_bump +# TAG: sslproxy_session_ttl +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Sets the timeout value for SSL sessions +#Default: +# sslproxy_session_ttl 300 + +# TAG: sslproxy_session_cache_size +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Sets the cache size to use for ssl session +#Default: +# sslproxy_session_cache_size 2 MB + +# TAG: sslproxy_foreign_intermediate_certs +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# Many origin servers fail to send their full server certificate +# chain for verification, assuming the client already has or can +# easily locate any missing intermediate certificates. +# +# Squid uses the certificates from the specified file to fill in +# these missing chains when trying to validate origin server +# certificate chains. +# +# The file is expected to contain zero or more PEM-encoded +# intermediate certificates. These certificates are not treated +# as trusted root certificates, and any self-signed certificate in +# this file will be ignored. +#Default: +# none + +# TAG: sslproxy_cert_sign_hash # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # -# This ACL controls which CONNECT requests to an http_port -# marked with an sslBump flag are actually "bumped". Please -# see the sslBump flag of an http_port option for more details -# about decoding proxied SSL connections. +# Sets the hashing algorithm to use when signing generated certificates. +# Valid algorithm names depend on the OpenSSL library used. The following +# names are usually available: sha1, sha256, sha512, and md5. Please see +# your OpenSSL library manual for the available hashes. By default, Squids +# that support this option use sha256 hashes. # -# By default, no requests are bumped. +# Squid does not forcefully purge cached certificates that were generated +# with an algorithm other than the currently configured one. They remain +# in the cache, subject to the regular cache eviction policy, and become +# useful if the algorithm changes again. +#Default: +# none + +# TAG: ssl_bump +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# This option is consulted when a CONNECT request is received on +# an http_port (or a new connection is intercepted at an +# https_port), provided that port was configured with an ssl-bump +# flag. The subsequent data on the connection is either treated as +# HTTPS and decrypted OR tunneled at TCP level without decryption, +# depending on the first matching bumping "action". +# +# ssl_bump <action> [!]acl ... +# +# The following bumping actions are currently supported: +# +# splice +# Become a TCP tunnel without decrypting proxied traffic. +# This is the default action. +# +# bump +# Establish a secure connection with the server and, using a +# mimicked server certificate, with the client. +# +# peek +# Receive client (step SslBump1) or server (step SslBump2) +# certificate while preserving the possibility of splicing the +# connection. Peeking at the server certificate (during step 2) +# usually precludes bumping of the connection at step 3. +# +# stare +# Receive client (step SslBump1) or server (step SslBump2) +# certificate while preserving the possibility of bumping the +# connection. Staring at the server certificate (during step 2) +# usually precludes splicing of the connection at step 3. +# +# terminate +# Close client and server connections. +# +# Backward compatibility actions available at step SslBump1: +# +# client-first +# Bump the connection. Establish a secure connection with the +# client first, then connect to the server. This old mode does +# not allow Squid to mimic server SSL certificate and does not +# work with intercepted SSL connections. +# +# server-first +# Bump the connection. Establish a secure connection with the +# server first, then establish a secure connection with the +# client, using a mimicked server certificate. Works with both +# CONNECT requests and intercepted SSL connections, but does +# not allow to make decisions based on SSL handshake info. +# +# peek-and-splice +# Decide whether to bump or splice the connection based on +# client-to-squid and server-to-squid SSL hello messages. +# XXX: Remove. +# +# none +# Same as the "splice" action. +# +# All ssl_bump rules are evaluated at each of the supported bumping +# steps. Rules with actions that are impossible at the current step are +# ignored. The first matching ssl_bump action wins and is applied at the +# end of the current step. If no rules match, the splice action is used. +# See the at_step ACL for a list of the supported SslBump steps. # -# See also: http_port ssl-bump -# # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # +# See also: http_port ssl-bump, https_port ssl-bump, and acl at_step. +# # -# # Example: Bump all requests except those originating from localhost and -# # those going to webax.com or example.com sites. +# # Example: Bump all TLS connections except those originating from +# # localhost or those going to example.com. # -# acl localhost src 127.0.0.1/32 -# acl broken_sites dstdomain .webax.com -# acl broken_sites dstdomain .example.com -# ssl_bump deny localhost -# ssl_bump deny broken_sites -# ssl_bump allow all +# acl broken_sites ssl::server_name .example.com +# ssl_bump splice localhost +# ssl_bump splice broken_sites +# ssl_bump bump all #Default: -# none +# Become a TCP tunnel without decrypting proxied traffic. # TAG: sslproxy_flags # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Various flags modifying the use of SSL while proxying https:// URLs: # DONT_VERIFY_PEER Accept certificates that fail verification. @@ -1553,16 +2376,16 @@ http_port 3128 # TAG: sslproxy_cert_error # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Use this ACL to bypass server certificate validation errors. # # For example, the following lines will bypass all validation errors -# when talking to servers located at 172.16.0.0/16. All other +# when talking to servers for example.com. All other # validation errors will result in ERR_SECURE_CONNECT_FAIL error. # -# acl BrokenServersAtTrustedIP dst 172.16.0.0/16 -# sslproxy_cert_error allow BrokenServersAtTrustedIP +# acl BrokenButTrustedServers dstdomain example.com +# sslproxy_cert_error allow BrokenButTrustedServers # sslproxy_cert_error deny all # # This clause only supports fast acl types. @@ -1570,19 +2393,107 @@ http_port 3128 # 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. +# +# SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed +# but should not happen unless your OpenSSL library is buggy. +# +# SECURITY WARNING: +# Bypassing validation errors is dangerous because an +# error usually implies that the server cannot be trusted +# and the connection may be insecure. # # See also: sslproxy_flags and DONT_VERIFY_PEER. +#Default: +# Server certificate errors terminate the transaction. + +# TAG: sslproxy_cert_sign +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# +# 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. # -# Default setting: sslproxy_cert_error deny all +# 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 +# browser. This is the default for self-signed origin server +# certificates (see ssl::certSelfSigned). +# +# This clause only supports fast acl types. +# +# When sslproxy_cert_sign acl(s) match, Squid uses the corresponding +# signing algorithm to generate the certificate and ignores all +# subsequent sslproxy_cert_sign options (the first match wins). If no +# acl(s) match, the default signing algorithm is determined by errors +# detected when obtaining and validating the origin server certificate. +# +# WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can +# be used with sslproxy_cert_adapt, but if and only if Squid is bumping a +# CONNECT request that carries a domain name. In all other cases (CONNECT +# to an IP address or an intercepted SSL connection), Squid cannot detect +# the domain mismatch at certificate generation time when +# bump-server-first is used. +#Default: +# none + +# TAG: sslproxy_cert_adapt +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# +# 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, +# extracted from the CONNECT request. It is a misconfiguration +# to use setCommonName without an explicit parameter for +# intercepted or tproxied SSL connections. +# +# This clause only supports fast acl types. +# +# Squid first groups sslproxy_cert_adapt options by adaptation algorithm. +# Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the +# corresponding adaptation algorithm to generate the certificate and +# ignores all subsequent sslproxy_cert_adapt options in that algorithm's +# group (i.e., the first match wins within each algorithm group). If no +# acl(s) match, the default mimicking action takes place. +# +# WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can +# be used with sslproxy_cert_adapt, but if and only if Squid is bumping a +# CONNECT request that carries a domain name. In all other cases (CONNECT +# to an IP address or an intercepted SSL connection), Squid cannot detect +# the domain mismatch at certificate generation time when +# bump-server-first is used. #Default: # none # TAG: sslpassword_program # Note: This option is only available if Squid is rebuilt with the -# --enable-ssl option +# --with-openssl # # Specify a program used for entering SSL key passphrases # when using encrypted SSL certificate keys. If not specified @@ -1595,12 +2506,12 @@ http_port 3128 #Default: # none -#OPTIONS RELATING TO EXTERNAL SSL_CRTD -#----------------------------------------------------------------------------- +# OPTIONS RELATING TO EXTERNAL SSL_CRTD +# ----------------------------------------------------------------------------- # TAG: sslcrtd_program # Note: This option is only available if Squid is rebuilt with the -# -DUSE_SSL_CRTD define +# --enable-ssl-crtd # # Specify the location and options of the executable for ssl_crtd process. # /usr/lib/squid/ssl_crtd program requires -s and -M parameters @@ -1611,14 +2522,90 @@ http_port 3128 # TAG: sslcrtd_children # Note: This option is only available if Squid is rebuilt with the -# -DUSE_SSL_CRTD define +# --enable-ssl-crtd # # 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. +# # You must have at least one ssl_crtd process. #Default: -# sslcrtd_children 5 +# sslcrtd_children 32 startup=5 idle=1 + +# TAG: sslcrtvalidator_program +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# 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 +#Default: +# none + +# TAG: sslcrtvalidator_children +# Note: This option is only available if Squid is rebuilt with the +# --with-openssl +# +# 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. A value of 0 indicates the certficate validator does not +# support concurrency. Defaults to 1. +# +# When this directive is set to a value >= 1 then the protocol +# used to communicate with the helper is modified to include +# a request ID in front of the request/response. The request +# ID from the request must be echoed back with the response +# to that request. +# +# You must have at least one ssl_crt_validator process. +#Default: +# sslcrtvalidator_children 32 startup=5 idle=1 concurrency=1 # OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM # ----------------------------------------------------------------------------- @@ -1680,22 +2667,23 @@ http_port 3128 # # htcp Send HTCP, instead of ICP, queries to the neighbor. # You probably also want to set the "icp-port" to 4827 -# instead of 3130. +# instead of 3130. This directive accepts a comma separated +# list of options described below. # -# htcp-oldsquid Send HTCP to old Squid versions. +# htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier). # -# htcp-no-clr Send HTCP to the neighbor but without +# htcp=no-clr Send HTCP to the neighbor but without # sending any CLR requests. This cannot be used with -# htcp-only-clr. +# only-clr. # -# htcp-only-clr Send HTCP to the neighbor but ONLY CLR requests. -# This cannot be used with htcp-no-clr. +# htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests. +# This cannot be used with no-clr. # -# htcp-no-purge-clr +# htcp=no-purge-clr # Send HTCP to the neighbor including CLRs but only when # they do not result from PURGE requests. # -# htcp-forward-clr +# htcp=forward-clr # Forward any HTCP CLR requests this proxy receives to the peer. # # @@ -1768,6 +2756,14 @@ http_port 3128 # than the Squid default location. # # +# ==== CARP OPTIONS ==== +# +# carp-key=key-specification +# use a different key than the full URL to hash against the peer. +# the key-specification is a comma-separated list of the keywords +# scheme, host, port, path, params +# Order is not important. +# # ==== ACCELERATOR / REVERSE-PROXY OPTIONS ==== # # originserver Causes this parent to be contacted as an origin server. @@ -1795,20 +2791,23 @@ http_port 3128 # Note: The string can include URL escapes (i.e. %20 for # spaces). This also means % must be written as %%. # -# login=PROXYPASS +# login=PASSTHRU # Send login details received from client to this peer. -# Authentication is not required, nor changed. +# Both Proxy- and WWW-Authorization headers are passed +# without alteration to the peer. +# Authentication is not required by Squid for this to work. # # Note: This will pass any form of authentication but # only Basic auth will work through a proxy unless the # connection-auth options are also used. -# +# # login=PASS Send login details received from client to this peer. # Authentication is not required by this option. +# # If there are no client-provided authentication headers # to pass on, but username and password are available -# from either proxy login or an external ACL user= and -# password= result tags they may be sent instead. +# from an external ACL user= and password= result tags +# they may be sent instead. # # Note: To combine this with proxy_auth both proxies must # share the same user database as HTTP only allows for @@ -1826,6 +2825,27 @@ http_port 3128 # be used to identify this proxy to the peer, similar to # the login=username:password option above. # +# login=NEGOTIATE +# If this is a personal/workgroup proxy and your parent +# requires a secure proxy authentication. +# The first principal from the default keytab or defined by +# the environment variable KRB5_KTNAME will be used. +# +# WARNING: The connection may transmit requests from multiple +# clients. Negotiate often assumes end-to-end authentication +# and a single-client. Which is not strictly true here. +# +# login=NEGOTIATE:principal_name +# If this is a personal/workgroup proxy and your parent +# requires a secure proxy authentication. +# The principal principal_name from the default keytab or +# defined by the environment variable KRB5_KTNAME will be +# used. +# +# WARNING: The connection may transmit requests from multiple +# clients. Negotiate often assumes end-to-end authentication +# and a single-client. Which is not strictly true here. +# # connection-auth=on|off # Tell Squid that this peer does or not support Microsoft # connection oriented authentication, and any such @@ -1848,22 +2868,42 @@ http_port 3128 # reference a combined file containing both the # certificate and the key. # -# sslversion=1|2|3|4 +# sslversion=1|2|3|4|5|6 # The SSL version to use when connecting to this peer # 1 = automatic (default) # 2 = SSL v2 only # 3 = SSL v3 only -# 4 = TLS v1 only +# 4 = TLS v1.0 only +# 5 = TLS v1.1 only +# 6 = TLS v1.2 only # # sslcipher=... The list of valid SSL ciphers to use when connecting # to this peer. # -# ssloptions=... Specify various SSL engine options: -# NO_SSLv2 Disallow the use of SSLv2 -# NO_SSLv3 Disallow the use of SSLv3 -# NO_TLSv1 Disallow the use of TLSv1 -# See src/ssl_support.c or the OpenSSL documentation for -# a more complete list. +# ssloptions=... Specify various SSL implementation options: +# +# NO_SSLv2 Disallow the use of SSLv2 +# NO_SSLv3 Disallow the use of SSLv3 +# NO_TLSv1 Disallow the use of TLSv1.0 +# NO_TLSv1_1 Disallow the use of TLSv1.1 +# NO_TLSv1_2 Disallow the use of TLSv1.2 +# +# SINGLE_DH_USE +# Always create a new key when using +# temporary/ephemeral DH key exchanges +# +# NO_TICKET +# Disable use of RFC5077 session tickets. Some servers +# may have problems understanding the TLS extension due +# to ambiguous specification in RFC4507. +# +# ALL Enable various bug workarounds +# suggested as "harmless" by OpenSSL +# Be warned that this reduces SSL/TLS +# strength to some attacks. +# +# See the OpenSSL SSL_CTX_set_options documentation for a +# more complete list. # # sslcafile=... A file containing additional CA certificates to use # when verifying the peer certificate. @@ -1907,29 +2947,74 @@ http_port 3128 # # connect-fail-limit=N # How many times connecting to a peer must fail before -# it is marked as down. Default is 10. +# it is marked as down. Standby connection failures +# count towards this limit. Default is 10. # # allow-miss Disable Squid's use of only-if-cached when forwarding # requests to siblings. This is primarily useful when -# icp_hit_stale is used by the sibling. To extensive use -# of this option may result in forwarding loops, and you -# should avoid having two-way peerings with this option. -# For example to deny peer usage on requests from peer -# by denying cache_peer_access if the source is a peer. +# icp_hit_stale is used by the sibling. Excessive use +# of this option may result in forwarding loops. One way +# to prevent peering loops when using this option, is to +# deny cache peer usage on requests from a peer: +# acl fromPeer ... +# cache_peer_access peerName deny fromPeer +# +# max-conn=N Limit the number of concurrent connections the Squid +# may open to this peer, including already opened idle +# and standby connections. There is no peer-specific +# connection limit by default. +# +# A peer exceeding the limit is not used for new +# requests unless a standby connection is available. # -# max-conn=N Limit the amount of connections Squid may open to this -# peer. see also +# max-conn currently works poorly with idle persistent +# connections: When a peer reaches its max-conn limit, +# and there are idle persistent connections to the peer, +# the peer may not be selected because the limiting code +# does not know whether Squid can reuse those idle +# connections. +# +# standby=N Maintain a pool of N "hot standby" connections to an +# UP peer, available for requests when no idle +# persistent connection is available (or safe) to use. +# By default and with zero N, no such pool is maintained. +# N must not exceed the max-conn limit (if any). +# +# At start or after reconfiguration, Squid opens new TCP +# standby connections until there are N connections +# available and then replenishes the standby pool as +# opened connections are used up for requests. A used +# connection never goes back to the standby pool, but +# may go to the regular idle persistent connection pool +# shared by all peers and origin servers. +# +# Squid never opens multiple new standby connections +# concurrently. This one-at-a-time approach minimizes +# flooding-like effect on peers. Furthermore, just a few +# standby connections should be sufficient in most cases +# to supply most new requests with a ready-to-use +# connection. +# +# Standby connections obey server_idle_pconn_timeout. +# For the feature to work as intended, the peer must be +# configured to accept and keep them open longer than +# the idle timeout at the connecting Squid, to minimize +# race conditions typical to idle used persistent +# connections. Default request_timeout and +# server_idle_pconn_timeout values ensure such a +# configuration. # # name=xxx Unique name for the peer. # Required if you have multiple peers on the same host # but different ports. # This name can be used in cache_peer_access and similar -# directives to dentify the peer. +# directives to identify the peer. # Can be used by outgoing access controls through the # peername ACL type. # # 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. # @@ -1938,10 +3023,11 @@ http_port 3128 # TAG: cache_peer_domain # 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 # @@ -1966,33 +3052,57 @@ http_port 3128 # none # TAG: cache_peer_access -# Similar to 'cache_peer_domain' but provides more flexibility by -# using ACL elements. +# Restricts usage of cache_peer proxies. # -# cache_peer_access cache-host allow|deny [!]aclname ... +# Usage: +# cache_peer_access peer-name allow|deny [!]aclname ... +# +# For the required peer-name parameter, use either the value of the +# cache_peer name=value parameter or, if name=value is missing, the +# cache_peer hostname parameter. +# +# This directive narrows down the selection of peering candidates, but +# does not determine the order in which the selected candidates are +# contacted. That order is determined by the peer selection algorithms +# (see PEER SELECTION sections in the cache_peer documentation). +# +# If a deny rule matches, the corresponding peer will not be contacted +# for the current transaction -- Squid will not send ICP queries and +# will not forward HTTP requests to that peer. An allow match leaves +# the corresponding peer in the selection. The first match for a given +# peer wins for that peer. +# +# The relative order of cache_peer_access directives for the same peer +# matters. The relative order of any two cache_peer_access directives +# for different peers does not matter. To ease interpretation, it is a +# good idea to group cache_peer_access directives for the same peer +# together. +# +# A single cache_peer_access directive may be evaluated multiple times +# for a given transaction because individual peer selection algorithms +# may check it independently from each other. These redundant checks +# may be optimized away in future Squid versions. # -# The syntax is identical to 'http_access' and the other lists of -# ACL elements. See the comments for 'http_access' below, or -# the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl). +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# No peer usage restrictions. # TAG: neighbor_type_domain -# 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 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. #Default: -# none +# The peer type from cache_peer directive is used for all requests to that peer. # TAG: dead_peer_timeout (seconds) # This controls how long Squid waits to declare a peer cache @@ -2015,21 +3125,11 @@ http_port 3128 # TAG: forward_max_tries # Controls how many different forward paths Squid will try # before giving up. See also forward_timeout. +# +# NOTE: connect_retries (default: none) can make each of these +# possible forwarding paths be tried multiple times. #Default: -# forward_max_tries 10 - -# TAG: hierarchy_stoplist -# A list of words which, if found in a URL, cause the object to -# be handled directly by this cache. In other words, use this -# to not query neighbor caches for certain objects. You may -# list this option multiple times. -# -# Example: -# hierarchy_stoplist cgi-bin ? -# -# Note: never_direct overrides this option. -#Default: -# none +# forward_max_tries 25 # MEMORY CACHE OPTIONS # ----------------------------------------------------------------------------- @@ -2064,6 +3164,11 @@ http_port 3128 # decreases, blocks will be freed until the high-water mark is # reached. Thereafter, blocks will be used to store hot # objects. +# +# If shared memory caching is enabled, Squid does not use the shared +# cache space for in-transit objects, but they still consume as much +# local memory as they need. For more details about the shared memory +# cache, see memory_cache_shared. #Default: # cache_mem 256 MB @@ -2075,11 +3180,45 @@ http_port 3128 #Default: # maximum_object_size_in_memory 512 KB +# TAG: memory_cache_shared on|off +# Controls whether the memory cache is shared among SMP workers. +# +# The shared memory cache is meant to occupy cache_mem bytes and replace +# the non-shared memory cache, although some entities may still be +# cached locally by workers for now (e.g., internal and in-transit +# objects may be served from a local memory cache even if shared memory +# caching is enabled). +# +# By default, the memory cache is shared if and only if all of the +# following conditions are satisfied: Squid runs in SMP mode with +# multiple workers, cache_mem is positive, and Squid environment +# supports required IPC primitives (e.g., POSIX shared memory segments +# and GCC-style atomic operations). +# +# To avoid blocking locks, shared memory uses opportunistic algorithms +# that do not guarantee that every cachable entity that could have been +# shared among SMP workers will actually be shared. +#Default: +# "on" where supported if doing memory caching with multiple SMP workers. + +# TAG: memory_cache_mode +# Controls which objects to keep in the memory cache (cache_mem) +# +# always Keep most recently fetched objects in memory (default) +# +# disk Only disk cache hits are kept in memory, which means +# an object must first be cached on disk and then hit +# a second time before cached in memory. +# +# network Only objects fetched from network is kept in memory +#Default: +# Keep the most recently fetched objects in memory + # TAG: memory_replacement_policy # 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. #Default: # memory_replacement_policy lru @@ -2095,7 +3234,7 @@ http_port 3128 # 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. # @@ -2114,7 +3253,7 @@ http_port 3128 # 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 @@ -2123,10 +3262,34 @@ http_port 3128 #Default: # cache_replacement_policy lru +# TAG: minimum_object_size (bytes) +# Objects smaller than this size will NOT be saved on disk. The +# value is specified in bytes, and the default is 0 KB, which +# means all responses can be stored. +#Default: +# no limit + +# TAG: maximum_object_size (bytes) +# Set the default value for max-size parameter on any cache_dir. +# The value is specified in bytes, and the default is 4 MB. +# +# If you wish to get a high BYTES hit ratio, you should probably +# increase this (one 32 MB object hit counts for 3200 10KB +# hits). +# +# If you wish to increase hit ratio more than you want to +# save bandwidth you should leave this low. +# +# NOTE: if using the LFUDA replacement policy you should increase +# this value to maximize the byte hit rate improvement of LFUDA! +# See cache_replacement_policy for a discussion of this policy. +#Default: +# maximum_object_size 4 MB +maximum_object_size 153600 KB + # TAG: cache_dir -# 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. @@ -2141,12 +3304,18 @@ http_port 3128 # The directory must exist and be writable by the Squid # process. Squid will NOT create this directory for you. # -# The ufs store type: +# In SMP configurations, cache_dir must not precede the workers option +# and should use configuration macros or conditionals to give each +# worker interested in disk caching a dedicated cache directory. +# +# +# ==== 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 @@ -2161,23 +3330,27 @@ http_port 3128 # 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 # @@ -2195,37 +3368,78 @@ http_port 3128 # higher hit ratio at the expense of an increase in response # time. # -# 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. -# We hope that it can be made usable again soon. -# -# block-size=n defines the "block size" for COSS cache_dir's. -# Squid uses file numbers as block numbers. Since file numbers -# are limited to 24 bits, the block size determines the maximum -# size of the COSS partition. The default is 512 bytes, which -# leads to a maximum cache_dir size of 512<<24, or 8 GB. Note -# you should not change the coss block size after Squid -# has written some objects to the cache_dir. # -# The coss file store has changed from 2.5. Now it uses a file -# called 'stripe' in the directory names in the config - and -# this will be created by squid -z. +# ==== The rock store type ==== # -# Common options: -# -# no-store, no new objects should be stored to this cache_dir +# Usage: +# cache_dir rock Directory-Name Mbytes [options] +# +# The Rock Store type is a database-style storage. All cached +# entries are stored in a "database" file, using fixed-size slots. +# A single entry occupies one or more slots. +# +# 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 +# default and when set to zero, disables the disk I/O time limit +# enforcement. Ignored when using blocking I/O module because +# blocking synchronous I/O does not allow Squid to estimate the +# expected swap wait time. +# +# max-swap-rate=swaps/sec: Artificially limits disk access using +# the specified I/O rate limit. Swap out requests that +# would cause the average I/O rate to exceed the limit are +# delayed. Individual swap in requests (i.e., hits or reads) are +# not delayed, but they do contribute to measured swap rate and +# since they are placed in the same FIFO queue as swap out +# requests, they may wait longer if max-swap-rate is smaller. +# This is necessary on file systems that buffer "too +# many" writes and then start blocking Squid and other processes +# while committing those writes to disk. Usually used together +# with swap-timeout to avoid excessive delays and queue overflows +# when disk demand exceeds available disk "bandwidth". By default +# and when set to zero, disables the disk I/O rate limit +# enforcement. Currently supported by IpcIo module only. +# +# slot-size=bytes: The size of a database "record" used for +# storing cached responses. A cached response occupies at least +# one slot and all database I/O is done using individual slots so +# increasing this parameter leads to more disk space waste while +# decreasing it leads to more disk I/O overheads. Should be a +# multiple of your operating system I/O page size. Defaults to +# 16KBytes. A housekeeping header is stored with each slot and +# smaller slot-sizes will be rejected. The header is smaller than +# 100 bytes. +# +# +# ==== 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. Rock). +# Defaults to 0. +# +# max-size=n the maximum object size in bytes this cache_dir +# supports. +# The value in maximum_object_size directive sets +# the default unless more specific details are +# available (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. +#Default: +# No disk cache. Store cache ojects only in memory. # # Uncomment and adjust the following to add a disk cache directory. @@ -2233,7 +3447,60 @@ http_port 3128 cache_dir ufs /var/spool/squid 4096 16 1024 # TAG: store_dir_select_algorithm -# 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. +# +# If several cache_dirs use similar min-size, max-size, or other +# limits to to reject certain responses, then do not group such +# cache_dir lines together, to avoid round-robin selection bias +# towards the first cache_dir after the group. Instead, interleave +# cache_dir lines from different groups. For example: +# +# store_dir_select_algorithm round-robin +# cache_dir rock /hdd1 ... min-size=100000 +# cache_dir rock /ssd1 ... max-size=99999 +# cache_dir rock /hdd2 ... min-size=100000 +# cache_dir rock /ssd2 ... max-size=99999 +# cache_dir rock /hdd3 ... min-size=100000 +# cache_dir rock /ssd3 ... max-size=99999 #Default: # store_dir_select_algorithm least-load @@ -2244,46 +3511,53 @@ cache_dir ufs /var/spool/squid 4096 16 1024 # # A value of 0 indicates no limit. #Default: -# max_open_disk_fds 0 - -# TAG: minimum_object_size (bytes) -# 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. -#Default: -# minimum_object_size 0 KB - -# TAG: maximum_object_size (bytes) -# 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 -# increase this (one 32 MB object hit counts for 3200 10KB -# hits). If you wish to increase speed more than your want to -# save bandwidth you should leave this low. -# -# NOTE: if using the LFUDA replacement policy you should increase -# this value to maximize the byte hit rate improvement of LFUDA! -# See replacement_policy below for a discussion of this policy. -#Default: -# maximum_object_size 4096 KB -maximum_object_size 153600 KB +# no limit # TAG: cache_swap_low (percent, 0-100) +# The low-water mark for AUFS/UFS/diskd cache object eviction by +# the cache_replacement_policy algorithm. +# +# Removal begins when the swap (disk) usage of a cache_dir is +# above this low-water mark and attempts to maintain utilization +# near the low-water mark. +# +# As swap utilization increases towards the high-water mark set +# by cache_swap_high object eviction becomes more agressive. +# +# The value difference in percentages between low- and high-water +# marks represent an eviction rate of 300 objects per second and +# the rate continues to scale in agressiveness by multiples of +# this above the high-water mark. +# +# Defaults are 90% and 95%. If you have a large cache, 5% could be +# hundreds of MB. If this is the case you may wish to set these +# numbers closer together. +# +# See also cache_swap_high and cache_replacement_policy #Default: # cache_swap_low 90 # TAG: cache_swap_high (percent, 0-100) +# The high-water mark for AUFS/UFS/diskd cache object eviction by +# the cache_replacement_policy algorithm. +# +# Removal begins when the swap (disk) usage of a cache_dir is +# above the low-water mark set by cache_swap_low and attempts to +# maintain utilization near the low-water mark. # -# The low- and high-water marks 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. +# As swap utilization increases towards this high-water mark object +# eviction becomes more agressive. +# +# The value difference in percentages between low- and high-water +# marks represent an eviction rate of 300 objects per second and +# the rate continues to scale in agressiveness by multiples of +# this above the high-water mark. # # Defaults are 90% and 95%. If you have a large cache, 5% could be # hundreds of MB. If this is the case you may wish to set these # numbers closer together. +# +# See also cache_swap_low and cache_replacement_policy #Default: # cache_swap_high 95 @@ -2313,21 +3587,62 @@ maximum_object_size 153600 KB # ' output as-is # # - left aligned -# width field width. If starting with 0 the -# output is zero padded +# +# width minimum and/or maximum field width: +# [width_min][.width_max] +# When minimum starts with 0, the field is zero-padded. +# String values exceeding maximum width are truncated. +# # {arg} argument such as header name etc # # Format codes: # # % a literal % character +# sn Unique sequence number per log line entry +# 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 annotation specified by the argument. Also +# logs the adaptation meta headers set by the +# adaptation_meta configuration parameter. +# If no argument given all annotations logged. +# The argument may include a separator to use with +# annotation values: +# name[:separator] +# By default, multiple note values are separated with "," +# and multiple notes are separated with "\r\n". +# When logging named notes with %{name}note, the +# explicitly configured separator is used between note +# values. When logging all notes with %note, the +# explicitly configured separator is used between +# individual notes. There is currently no way to +# specify both value and notes separators when logging +# all notes with %note. +# +# Connection related format codes: +# # >a Client source IP address # >A Client FQDN # >p Client source port -# <A Server IP address or peer name -# la Local IP address (http_port) -# lp Local port number (http_port) +# >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier) +# >la Local IP address the client connected to +# >lp Local port number the client connected to +# >qos Client connection TOS/DSCP value set by Squid +# >nfmark Client connection netfilter mark set by Squid +# +# la Local listening IP address the client connection was connected to. +# lp Local listening port number the client connection was connected to. +# +# <a Server IP address of the last server or peer connection +# <A Server FQDN or peer name +# <p Server port number of the last server or peer connection # <la Local IP address of the last server or peer connection # <lp Local port number of the last server or peer connection +# <qos Server connection TOS/DSCP value set by Squid +# <nfmark Server connection netfilter mark set by Squid +# +# Time related format codes: +# # ts Seconds since epoch # tu subsecond time (milliseconds) # tl Local time. Optional strftime format argument @@ -2336,49 +3651,141 @@ maximum_object_size 153600 KB # default %d/%b/%Y:%H:%M:%S %z # tr Response time (milliseconds) # dt Total time spent making DNS lookups (milliseconds) +# tS Approximate master transaction start time in +# <full seconds since epoch>.<fractional seconds> format. +# Currently, Squid considers the master transaction +# started when a complete HTTP request header initiating +# the transaction is received from the client. This is +# the same value that Squid uses to calculate transaction +# response time when logging %tr to access.log. Currently, +# Squid uses millisecond resolution for %tS values, +# similar to the default access.log "current time" field +# (%ts.%03tu). +# +# Access Control related format codes: +# +# et Tag returned by external acl +# ea Log string returned by external acl +# un User name (any available) +# ul User name from authentication +# ue User name from external acl helper +# ui User name from ident +# un A user name. Expands to the first available name +# from the following list of information sources: +# - authenticated user name, like %ul +# - user name supplied by an external ACL, like %ue +# - SSL client name, like %us +# - ident user name, like %ui +# credentials Client credentials. The exact meaning depends on +# the authentication scheme: For Basic authentication, +# it is the password; for Digest, the realm sent by the +# client; for NTLM and Negotiate, the client challenge +# or client credentials prefixed with "YR " or "KK ". +# +# HTTP related format codes: +# +# REQUEST # -# HTTP cache 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::]rm Request method (GET/POST etc) +# [http::]>rm Request method from client +# [http::]<rm Request method sent to server or peer +# [http::]ru Request URL from client (historic, filtered for logging) +# [http::]>ru Request URL from client +# [http::]<ru Request URL sent to server or peer +# [http::]>rs Request URL scheme from client +# [http::]<rs Request URL scheme sent to server or peer +# [http::]>rd Request URL domain from client +# [http::]<rd Request URL domain sent to server or peer +# [http::]>rP Request URL port from client +# [http::]<rP Request URL port sent to server or peer +# [http::]rp Request URL path excluding hostname +# [http::]>rp Request URL path excluding hostname from client +# [http::]<rp Request URL path excluding hostname sent to server or peer +# [http::]rv Request protocol version +# [http::]>rv Request protocol version from client +# [http::]<rv Request protocol version sent to server or peer +# +# [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 +# +# +# RESPONSE +# +# [http::]<Hs HTTP status code received from the next hop +# [http::]>Hs HTTP status code sent to the client +# # [http::]<h Reply header. Optional header name argument # as for >h -# [http::]un User name -# [http::]ul User name from authentication -# [http::]ui User name from ident -# [http::]us User name from SSL -# [http::]ue User name from external acl helper -# [http::]>Hs HTTP status code sent to the client -# [http::]<Hs HTTP status code received from the next hop -# [http::]Ss Squid request status (TCP_MISS etc) -# [http::]Sh Squid hierarchy status (DEFAULT_PARENT etc) +# # [http::]mt MIME content type -# [http::]rm Request method (GET/POST etc) -# [http::]ru Request URL -# [http::]rp Request URL-Path excluding hostname -# [http::]rv Request protocol version -# [http::]et Tag returned by external acl -# [http::]ea Log string returned by external acl -# [http::]<st Sent reply size including HTTP headers -# [http::]>st Received request size including HTTP headers. In the -# case of chunked requests the chunked encoding metadata -# are not included -# [http::]>sh Received HTTP request headers size -# [http::]<sh Sent HTTP reply headers size -# [http::]st Request+Reply size including HTTP headers +# +# +# SIZE COUNTERS +# +# [http::]st Total size of request + reply traffic with client +# [http::]>st Total size of request received from client. +# Excluding chunked encoding bytes. +# [http::]<st Total size of reply sent to client (after adaptation) +# +# [http::]>sh Size of request headers received from client +# [http::]<sh Size of reply headers sent to client (after adaptation) +# # [http::]<sH Reply high offset sent # [http::]<sS Upstream object size +# +# [http::]<bs Number of HTTP-equivalent message body bytes +# received from the next hop, excluding chunked +# transfer encoding and control messages. +# Generated FTP/Gopher listings are treated as +# received bodies. +# +# +# TIMING +# # [http::]<pt Peer response time in milliseconds. The timer starts # when the last request byte is sent to the next hop # and stops when the last response byte is received. -# [http::]<tt Total server-side time in milliseconds. The timer +# [http::]<tt Total time in milliseconds. The timer # starts with the first connect request (or write I/O) # sent to the first selected peer. The timer stops # with the last I/O with the last peer. # -# If ICAP is enabled, the following two codes become available (as +# Squid handling related format codes: +# +# 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. +# +# ssl::>sni SSL client SNI sent to Squid. Available only +# after the peek, stare, or splice SSL bumping +# actions. +# +# If ICAP is enabled, the following code becomes available (as # well as ICAP log codes documented with the icap_log option): # # icap::tt Total ICAP processing time for the HTTP @@ -2386,14 +3793,13 @@ maximum_object_size 153600 KB # ACLs are checked and when ICAP # transaction is in progress. # -# icap::<last_h The header of the last ICAP response -# related to the HTTP transaction. Like -# <h, accepts an optional header name -# argument. Will not change semantics -# when multiple ICAP transactions per HTTP -# transaction are supported. +# If adaptation is enabled the following three codes become available: # -# If adaptation is enabled the following two codes become available: +# adapt::<last_h The header of the last ICAP response or +# meta-information from the last eCAP +# transaction related to the HTTP transaction. +# Like <h, accepts an optional header name +# argument. # # adapt::sum_trs Summed adaptation transaction response # times recorded as a comma-separated list in @@ -2417,43 +3823,118 @@ maximum_object_size 153600 KB # 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 -#logformat squidmime %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h] -#logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh -#logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh +#logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt +#logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh +#logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh +#logformat referrer %ts.%03tu %>a %{Referer}>h %ru +#logformat useragent %>a [%tl] "%{User-Agent}>h" +# +# NOTE: When the log_mime_hdrs directive is set to ON. +# The squid, common and combined formats have a safely encoded copy +# of the mime headers appended to each line within a pair of brackets. +# +# NOTE: The common and combined formats are not quite true to the Apache definition. +# The logs from Squid contain an extra status and hierarchy code appended. +# #Default: -# none +# The format definitions squid, common, combined, referrer, useragent are built in. # TAG: access_log -# These files log client request activities. Has a line every HTTP or -# ICP request. The format is: -# access_log <filepath> [<logformat name> [acl acl ...]] -# access_log none [acl acl ...]] +# 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: # -# Will log to the specified file 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). +# access_log <module>:<place> [option ...] [acl acl ...] +# access_log none [acl acl ...] # -# If no acl is specified, all requests will be logged to this file. +# The following directive format is accepted but may be deprecated: +# access_log <module>:<place> [<logformat name> [acl acl ...]] # -# To disable logging of a request use the filepath "none", in which case -# a logformat name should not be specified. +# 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. +# Do not specify Place or logformat name. +# +# stdio Write each log line to disk immediately at the completion of +# each request. +# Place: the filename and path to be written. +# +# daemon Very similar to stdio. But instead of writing to disk the log +# line is passed to a daemon helper for asychronous handling instead. +# Place: varies depending on the daemon. +# +# log_file_daemon Place: the file name and path to be written. +# +# syslog To log each request via syslog facility. +# Place: The syslog facility and priority level for these entries. +# Place Format: facility.priority # -# To log the request via syslog specify a filepath of "syslog": +# where facility could be any of: +# authpriv, daemon, local0 ... local7 or user. # -# access_log syslog[:facility.priority] [format [acl1 [acl2 ....]]] -# where facility could be any of: -# authpriv, daemon, local0 .. local7 or user. +# And priority could be any of: +# err, warning, notice, info, debug. +# +# udp To send each log line as text data to a UDP receiver. +# Place: The destination host name or IP and port. +# Place Format: //host:port # -# And priority could be any of: -# err, warning, notice, info, debug. +# 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 # # Default: -# access_log /var/log/squid/access.log squid +# access_log daemon:/var/log/squid/access.log squid #Default: -# access_log /var/log/squid/access.log squid +# access_log daemon:/var/log/squid/access.log squid # TAG: icap_log # ICAP log files record ICAP transaction summaries, one line per @@ -2472,13 +3953,35 @@ maximum_object_size 153600 KB # ICAP transaction log lines will correspond to a single access # log line. # -# ICAP log uses logformat codes that make sense for an ICAP -# transaction. Header-related codes are applied to the HTTP header -# embedded in an ICAP server response, with the following caveats: -# For REQMOD, there is no HTTP response header unless the ICAP -# server performed request satisfaction. For RESPMOD, the HTTP -# request header is the header sent to the ICAP server. For -# OPTIONS, there are no HTTP headers. +# ICAP log supports many access.log logformat %codes. In ICAP context, +# HTTP message-related %codes are applied to the HTTP message embedded +# in an ICAP message. Logformat "%http::>..." codes are used for HTTP +# messages embedded in ICAP requests while "%http::<..." codes are used +# for HTTP messages embedded in ICAP responses. For example: +# +# http::>h To-be-adapted HTTP message headers sent by Squid to +# the ICAP service. For REQMOD transactions, these are +# HTTP request headers. For RESPMOD, these are HTTP +# response headers, but Squid currently cannot log them +# (i.e., %http::>h will expand to "-" for RESPMOD). +# +# http::<h Adapted HTTP message headers sent by the ICAP +# service to Squid (i.e., HTTP request headers in regular +# REQMOD; HTTP response headers in RESPMOD and during +# request satisfaction in REQMOD). +# +# ICAP OPTIONS transactions do not embed HTTP messages. +# +# Several logformat codes below deal with ICAP message bodies. An ICAP +# message body, if any, typically includes a complete HTTP message +# (required HTTP headers plus optional HTTP message body). When +# computing HTTP message body size for these logformat codes, Squid +# either includes or excludes chunked encoding overheads; see +# code-specific documentation for details. +# +# For Secure ICAP services, all size-related information is currently +# computed before/after TLS encryption/decryption, as if TLS was not +# in use at all. # # The following format codes are also available for ICAP logs: # @@ -2492,12 +3995,16 @@ maximum_object_size 153600 KB # icap::rm ICAP request method (REQMOD, RESPMOD, or # OPTIONS). Similar to existing rm. # -# icap::>st Bytes sent to the ICAP server (TCP payload -# only; i.e., what Squid writes to the socket). +# icap::>st The total size of the ICAP request sent to the ICAP +# server (ICAP headers + ICAP body), including chunking +# metadata (if any). +# +# icap::<st The total size of the ICAP response received from the +# ICAP server (ICAP headers + ICAP body), including +# chunking metadata (if any). # -# icap::<st Bytes received from the ICAP server (TCP -# payload only; i.e., what Squid reads from -# the socket). +# icap::<bs The size of the ICAP response body received from the +# ICAP server, excluding chunking metadata (if any). # # icap::tr Transaction response time (in # milliseconds). The timer starts when @@ -2527,37 +4034,51 @@ maximum_object_size 153600 KB # The default ICAP log format, which can be used without an explicit # definition, is called icap_squid: # -#logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A - +#logformat icap_squid %ts.%03tu %6icap::tr %>A %icap::to/%03icap::Hs %icap::<st %icap::rm %icap::ru %un -/%icap::<A - # -# See also: logformat, log_icap, and %icap::<last_h +# See also: logformat and %adapt::<last_h #Default: # none -# TAG: log_access allow|deny acl acl... -# This options allows you to control which requests gets logged -# to access.log (see access_log directive). Requests denied for -# logging will also not be accounted for in performance counters. +# TAG: logfile_daemon +# Specify the path to the logfile-writing daemon. This daemon is +# used to write the access and store logs, if configured. # -# This clause only supports fast acl types. -# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# Squid sends a number of commands to the log daemon: +# L<data>\n - logfile data +# R\n - rotate file +# T\n - truncate file +# O\n - reopen file +# F\n - flush file +# r<n>\n - set rotate count to <n> +# b<n>\n - 1 = buffer output, 0 = don't buffer output +# +# No responses is expected. #Default: -# none +# logfile_daemon /usr/lib/squid/log_file_daemon -# TAG: log_icap -# This options allows you to control which requests get logged -# to icap.log. See the icap_log directive for ICAP log details. +# TAG: stats_collection allow|deny acl acl... +# This options allows you to control which requests gets accounted +# in performance counters. +# +# This clause only supports fast acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow logging for all transactions. # TAG: cache_store_log # 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 /var/log/squid/store.log +# cache_store_log stdio:/var/log/squid/store.log +# cache_store_log daemon:/var/log/squid/store.log #Default: # none @@ -2590,7 +4111,7 @@ maximum_object_size 153600 KB # them). We recommend you do NOT use this option. It is # better to keep these index files in each 'cache_dir' directory. #Default: -# none +# Store the journal inside its cache_dir # TAG: logfile_rotate # Specifies the number of logfile rotations to make when you @@ -2607,34 +4128,19 @@ maximum_object_size 153600 KB # 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. # -# Note2, for Debian/Linux the default of logfile_rotate is -# zero, since it includes external logfile-rotation methods. +# Note2, for Debian/Linux the default of logfile_rotate is +# zero, since it includes external logfile-rotation methods. #Default: # logfile_rotate 0 -# TAG: emulate_httpd_log on|off -# The Cache can emulate the log file format which many 'httpd' -# programs use. To disable/enable this emulation, set -# emulate_httpd_log to 'off' or 'on'. The default -# is to use the native log format since it includes useful -# information Squid-specific log analyzers use. -#Default: -# emulate_httpd_log off - -# TAG: log_ip_on_direct on|off -# Log the destination IP address in the hierarchy log tag when going -# direct. Earlier Squid versions logged the hostname here. If you -# prefer the old way set this to off. -#Default: -# log_ip_on_direct on - # TAG: mime_table -# 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. #Default: # mime_table /usr/share/squid/mime.conf @@ -2647,91 +4153,61 @@ maximum_object_size 153600 KB #Default: # log_mime_hdrs off -# TAG: useragent_log -# Note: This option is only available if Squid is rebuilt with the -# --enable-useragent-log option -# -# Squid will write the User-Agent field from HTTP requests -# to the filename specified here. By default useragent_log -# is disabled. -#Default: -# none - -# TAG: referer_log -# Note: This option is only available if Squid is rebuilt with the -# --enable-referer-log option -# -# Squid will write the Referer field from HTTP requests to the -# filename specified here. By default referer_log is disabled. -# Note that "referer" is actually a misspelling of "referrer" -# however the misspelt version has been accepted into the HTTP RFCs -# and we accept both. -#Default: -# none - # TAG: pid_filename # A filename to write the process-id to. To disable, enter "none". #Default: # pid_filename /var/run/squid.pid -# TAG: log_fqdn on|off -# Turn this on if you wish to log fully qualified domain names -# in the access.log. To do this Squid does a DNS lookup of all -# IP's connecting to it. This can (in some situations) increase -# latency, which makes your cache seem slower for interactive -# browsing. -#Default: -# log_fqdn off - # TAG: client_netmask # A netmask for client addresses in logfiles and cachemgr output. # Change this to protect the privacy of your cache clients. # A netmask of 255.255.255.0 will log all IP's in that range with # the last digit set to '0'. #Default: -# client_netmask no_addr - -# TAG: forward_log -# Note: This option is only available if Squid is rebuilt with the -# -DWIP_FWD_LOG define -# -# Logs the server-side requests. -# -# This is currently work in progress. -#Default: -# none +# Log full client IP address # TAG: strip_query_terms # 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. #Default: # strip_query_terms on # TAG: buffered_logs on|off -# 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. #Default: # buffered_logs off # TAG: netdb_filename -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option +# Where Squid stores it's netdb journal. +# When enabled this journal preserves netdb state between restarts. # -# A filename where Squid stores it's netdb state between restarts. # To disable, enter "none". #Default: -# netdb_filename /var/log/squid/netdb.state +# netdb_filename stdio:/var/log/squid/netdb.state # OPTIONS FOR TROUBLESHOOTING # ----------------------------------------------------------------------------- # TAG: cache_log -# 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" #Default: # cache_log /var/log/squid/cache.log @@ -2742,14 +4218,14 @@ maximum_object_size 153600 KB # 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. # For most uses a single log should be enough to monitor current # events affecting Squid. #Default: -# debug_options ALL,1 +# Log all critical and important messages. # TAG: coredump_dir # By default Squid leaves core files in the directory from where @@ -2758,7 +4234,7 @@ maximum_object_size 153600 KB # and coredump files will be left there. # #Default: -# coredump_dir none +# Use the directory from where Squid was started. # # Leave coredumps in the first cache dir @@ -2769,24 +4245,17 @@ coredump_dir /var/spool/squid # TAG: ftp_user # 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). #Default: # ftp_user Squid@ -# TAG: ftp_list_width -# Sets the width of ftp listings. This should be set to fit in -# the width of a standard browser. Setting this too small -# can cut off long filenames when browsing ftp sites. -#Default: -# ftp_list_width 32 - # TAG: ftp_passive # If your firewall does not allow Squid to use passive # connections, turn off this option. @@ -2822,13 +4291,21 @@ coredump_dir /var/spool/squid # and therefore, translation of the data portion of the segments # will never be needed. # -# Turning this OFF will prevent EPSV being attempted. -# WARNING: Doing so will convert Squid back to the old behavior with all -# the related problems with external NAT devices/layers. +# EPSV is often required to interoperate with FTP servers on IPv6 +# networks. On the other hand, it may break some IPv4 servers. +# +# By default, EPSV may try EPSV with any FTP server. To fine tune +# that decision, you may restrict EPSV to certain clients or servers +# using ACLs: # +# ftp_epsv allow|deny al1 acl2 ... +# +# WARNING: Disabling EPSV may cause problems with external NAT and IPv6. +# +# Only fast ACLs are supported. # Requires ftp_passive to be ON (default) for any effect. #Default: -# ftp_epsv on +# none # TAG: ftp_eprt # FTP Protocol extensions permit the use of a special "EPRT" command. @@ -2889,22 +4366,16 @@ coredump_dir /var/spool/squid # unlinkd_program /usr/lib/squid/unlinkd # TAG: pinger_program -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option -# # Specify the location of the executable for the pinger process. #Default: # pinger_program /usr/lib/squid/pinger # TAG: pinger_enable -# Note: This option is only available if Squid is rebuilt with the -# --enable-icmp option -# # Control whether the pinger is active at run-time. # Enables turning ICMP pinger on and off with a simple # squid -k reconfigure. #Default: -# pinger_enable off +# pinger_enable on # OPTIONS FOR URL REWRITING # ----------------------------------------------------------------------------- @@ -2915,68 +4386,137 @@ coredump_dir /var/spool/squid # # 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> extras]<NL> +# +# See url_rewrite_extras on how to send "extras" with optional values to +# the helper. +# After processing the request the helper must reply using the following format: +# +# [channel-ID <SP>] result [<SP> kv-pairs] +# +# The result code can be: # -# In the future, the rewriter interface will be extended with -# key=value pairs ("kvpairs" shown above). Rewriter programs -# should be prepared to receive and possibly ignore additional -# whitespace-separated tokens on each input line. +# 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. +# +# OK +# When neither of url= and rewrite-url= are sent Squid does +# not change the URL. +# +# ERR +# Do not change the URL. +# +# BH +# An internal error occurred in the helper, preventing +# a result being identified. The 'message=' key name is +# reserved for delivering a log message. +# +# +# In addition to the above kv-pairs Squid also understands the following +# optional kv-pairs received from URL rewriters: +# clt_conn_tag=TAG +# Associates a TAG with the client TCP connection. +# The TAG is treated as a regular annotation but persists across +# future requests on the client connection rather than just the +# current request. A helper may update the TAG during subsequent +# requests be returning a new kv-pair. +# +# 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. # -# 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). +# WARNING: URL re-writing ability should be avoided whenever possible. +# Use the URL redirect form of response instead. # -# 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. +# 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. #Default: # none # TAG: url_rewrite_children -# The number of redirector processes to spawn. If you start -# too few Squid will have to wait for them to process a backlog of -# URLs, slowing it down. If you start too many they will use RAM -# and other system resources. -#Default: -# url_rewrite_children 5 - -# TAG: url_rewrite_concurrency +# The maximum number of redirector processes to spawn. If you limit +# it too few Squid will have to wait for them to process a backlog of +# URLs, 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 redirector helper can handle in # parallel. Defaults to 0 which indicates the redirector # 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. +# an ID in front of the request/response. The ID from the request +# must be echoed back with the response to that request. #Default: -# url_rewrite_concurrency 0 +# url_rewrite_children 20 startup=0 idle=1 concurrency=0 # TAG: url_rewrite_host_header -# By default Squid rewrites any Host: header in redirected -# requests. If you are running an accelerator this may -# not be a wanted effect of a redirector. -# +# To preserve same-origin security policies in browsers and +# prevent Host: header forgery by redirectors Squid rewrites +# any Host: header in redirected requests. +# +# If you are running an accelerator this may not be a wanted +# effect of a redirector. This directive enables you disable +# Host: alteration in reverse-proxy traffic. +# # WARNING: Entries are cached on the result of the URL rewriting # process, so be careful if you have domain-virtual hosts. +# +# WARNING: Squid and other software verifies the URL and Host +# are matching, so be careful not to relay through other proxies +# or inspecting firewalls with this disabled. #Default: # url_rewrite_host_header on # TAG: url_rewrite_access # 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: -# none +# Allow, unless rules exist in squid.conf. # TAG: url_rewrite_bypass # 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 @@ -2987,23 +4527,231 @@ coredump_dir /var/spool/squid #Default: # url_rewrite_bypass off -# OPTIONS FOR TUNING THE CACHE +# TAG: url_rewrite_extras +# Specifies a string to be append to request line format for the +# rewriter helper. "Quoted" format values may contain spaces and +# logformat %macros. In theory, any logformat %macro can be used. +# In practice, a %macro expands as a dash (-) if the helper request is +# sent before the required macro information is available to Squid. +#Default: +# url_rewrite_extras "%>a/%>A %un %>rm myip=%la myport=%lp" + +# OPTIONS FOR STORE ID # ----------------------------------------------------------------------------- -# TAG: cache -# A list of ACL elements which, if matched and denied, cause the request to -# not be satisfied from the cache and the reply to not be cached. -# In other words, use this to force certain objects to never be cached. +# TAG: store_id_program +# 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> extras]<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. +# +# In addition to the above kv-pairs Squid also understands the following +# optional kv-pairs received from URL rewriters: +# clt_conn_tag=TAG +# Associates a TAG with the client TCP connection. +# Please see url_rewrite_program related documentation for this +# kv-pair +# +# Helper programs should be prepared to receive and possibly ignore +# additional whitespace-separated tokens on each input line. # -# You must use the words 'allow' or 'deny' to indicate whether items -# matching the ACL should be allowed or denied into the cache. +# 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. +#Default: +# none + +# TAG: store_id_extras +# Specifies a string to be append to request line format for the +# StoreId helper. "Quoted" format values may contain spaces and +# logformat %macros. In theory, any logformat %macro can be used. +# In practice, a %macro expands as a dash (-) if the helper request is +# sent before the required macro information is available to Squid. +#Default: +# store_id_extras "%>a/%>A %un %>rm myip=%la myport=%lp" + +# TAG: store_id_children +# 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. # -# Default is to allow all to be cached. +# 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. +#Default: +# store_id_children 20 startup=0 idle=1 concurrency=0 + +# TAG: store_id_access +# 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. #Default: -# none +# Allow, unless rules exist in squid.conf. + +# TAG: store_id_bypass +# 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. +#Default: +# store_id_bypass on + +# OPTIONS FOR TUNING THE CACHE +# ----------------------------------------------------------------------------- + +# TAG: cache +# Requests denied by this directive will not be served from the cache +# and their responses will not be stored in the cache. This directive +# has no effect on other transactions and on already cached responses. +# +# This clause supports both fast and slow acl types. +# See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# +# This and the two other similar caching directives listed below are +# checked at different transaction processing stages, have different +# access to response information, affect different cache operations, +# and differ in slow ACLs support: +# +# * cache: Checked before Squid makes a hit/miss determination. +# No access to reply information! +# Denies both serving a hit and storing a miss. +# Supports both fast and slow ACLs. +# * send_hit: Checked after a hit was detected. +# Has access to reply (hit) information. +# Denies serving a hit only. +# Supports fast ACLs only. +# * store_miss: Checked before storing a cachable miss. +# Has access to reply (miss) information. +# Denies storing a miss only. +# Supports fast ACLs only. +# +# If you are not sure which of the three directives to use, apply the +# following decision logic: +# +# * If your ACL(s) are of slow type _and_ need response info, redesign. +# Squid does not support that particular combination at this time. +# Otherwise: +# * If your directive ACL(s) are of slow type, use "cache"; and/or +# * if your directive ACL(s) need no response info, use "cache". +# Otherwise: +# * If you do not want the response cached, use store_miss; and/or +# * if you do not want a hit on a cached response, use send_hit. +#Default: +# By default, this directive is unused and has no effect. + +# TAG: send_hit +# Responses denied by this directive will not be served from the cache +# (but may still be cached, see store_miss). This directive has no +# effect on the responses it allows and on the cached objects. +# +# Please see the "cache" directive for a summary of differences among +# store_miss, send_hit, and cache directives. +# +# Unlike the "cache" directive, send_hit only supports fast acl +# types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +# +# For example: +# +# # apply custom Store ID mapping to some URLs +# acl MapMe dstdomain .c.example.com +# store_id_program ... +# store_id_access allow MapMe +# +# # but prevent caching of special responses +# # such as 302 redirects that cause StoreID loops +# acl Ordinary http_status 200-299 +# store_miss deny MapMe !Ordinary +# +# # and do not serve any previously stored special responses +# # from the cache (in case they were already cached before +# # the above store_miss rule was in effect). +# send_hit deny MapMe !Ordinary +#Default: +# By default, this directive is unused and has no effect. + +# TAG: store_miss +# Responses denied by this directive will not be cached (but may still +# be served from the cache, see send_hit). This directive has no +# effect on the responses it allows and on the already cached responses. +# +# Please see the "cache" directive for a summary of differences among +# store_miss, send_hit, and cache directives. See the +# send_hit directive for a usage example. +# +# Unlike the "cache" directive, store_miss only supports fast acl +# types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. +#Default: +# By default, this directive is unused and has no effect. + +# TAG: max_stale time-units +# This option puts an upper limit on how stale content Squid +# will serve from the cache if cache validation fails. +# Can be overriden by the refresh_pattern max-stale option. +#Default: +# max_stale 1 week # TAG: refresh_pattern # usage: refresh_pattern [-i] regex min percent max [options] @@ -3028,12 +4776,13 @@ coredump_dir /var/spool/squid # override-lastmod # reload-into-ims # ignore-reload -# ignore-no-cache # ignore-no-store # ignore-must-revalidate # ignore-private # ignore-auth +# max-stale=NN # refresh-ims +# store-stale # # override-expire enforces min age even if the server # sent an explicit expiry time (e.g., with the @@ -3049,22 +4798,18 @@ coredump_dir /var/spool/squid # override-lastmod enforces min age even on objects # that were modified recently. # -# reload-into-ims changes client no-cache or ``reload'' -# to If-Modified-Since requests. Doing this VIOLATES the -# HTTP standard. Enabling this feature could make you -# liable for problems which it causes. +# reload-into-ims changes a client no-cache or ``reload'' +# request for a cached entry into a conditional request using +# If-Modified-Since and/or If-None-Match headers, provided the +# cached entry has a Last-Modified and/or a strong ETag header. +# Doing this VIOLATES the HTTP standard. Enabling this feature +# could make you liable for problems which it causes. # # ignore-reload ignores a client no-cache or ``reload'' # header. Doing this VIOLATES the HTTP standard. Enabling # 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 @@ -3091,9 +4836,19 @@ coredump_dir /var/spool/squid # ensures that the client will receive an updated version # if one is available. # +# store-stale stores responses even if they don't have explicit +# freshness or a validator (i.e., Last-Modified or an ETag) +# present, or if they're already stale. By default, Squid will +# not cache such responses because they usually can't be +# reused. Note that such responses will be stale by default. +# +# max-stale=NN provide a maximum staleness factor. Squid won't +# serve objects more stale than this even if it failed to +# validate the object. Default: use the max_stale global limit. +# # Basically a cached object is: # -# FRESH if expires < now, else STALE +# FRESH if expire > now, else STALE # STALE if age > max # FRESH if lm-factor < percent, else STALE # FRESH if age < min @@ -3109,7 +4864,9 @@ coredump_dir /var/spool/squid # # +# # 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 @@ -3137,7 +4894,7 @@ refresh_pattern . 0 20% 4320 # downloads. # # When the user aborts a request, Squid will check the -# quick_abort values to the amount of data transfered until +# quick_abort values to the amount of data transferred until # then. # # If the transfer has less than 'quick_abort_min' KB remaining, @@ -3195,44 +4952,68 @@ refresh_pattern . 0 20% 4320 #Default: # negative_dns_ttl 1 minutes -# TAG: range_offset_limit (bytes) -# Sets a upper limit on how far into the the file a Range request -# may be to cause Squid to prefetch the whole file. If beyond this -# limit Squid forwards the Range request as it is and the result -# is NOT cached. -# +# TAG: range_offset_limit size [acl acl...] +# usage: (size) [units] [[!]aclname] +# +# Sets an upper limit on how far (number of bytes) into the file +# a Range request may be to cause Squid to prefetch the whole file. +# If beyond this limit, Squid forwards the Range request as it is and +# the result is NOT cached. +# # This is to stop a far ahead range request (lets say start at 17MB) # from making Squid fetch the whole object up to that point before # sending anything to the client. -# -# A value of 0 causes Squid to never fetch more than the +# +# Multiple range_offset_limit lines may be specified, and they will +# be searched from top to bottom on each request until a match is found. +# The first match found will be used. If no line matches a request, the +# default limit of 0 bytes will be used. +# +# 'size' is the limit specified as a number of units. +# +# 'units' specifies whether to use bytes, KB, MB, etc. +# If no units are specified bytes are assumed. +# +# A size of 0 causes Squid to never fetch more than the # client requested. (default) -# -# A value of -1 causes Squid to always fetch the object from the +# +# A size of 'none' causes Squid to always fetch the object from the # beginning so it may cache the result. (2.0 style) -# -# NP: Using -1 here will override any quick_abort settings that may -# otherwise apply to the range request. The range request will +# +# 'aclname' is the name of a defined ACL. +# +# NP: Using 'none' as the byte value here will override any quick_abort settings +# that may otherwise apply to the range request. The range request will # be fully fetched from start to finish regardless of the client # actions. This affects bandwidth usage. #Default: -# range_offset_limit 0 KB +# none # TAG: minimum_expiry_time (seconds) # 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. #Default: # minimum_expiry_time 60 seconds -# TAG: store_avg_object_size (kbytes) +# TAG: store_avg_object_size (bytes) # 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. #Default: # store_avg_object_size 13 KB @@ -3271,8 +5052,11 @@ refresh_pattern . 0 20% 4320 # 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. #Default: -# request_body_max_size 0 KB +# No limit. # TAG: client_request_buffer_max_size (bytes) # This specifies the maximum buffer size of a client request. @@ -3281,29 +5065,6 @@ refresh_pattern . 0 20% 4320 #Default: # client_request_buffer_max_size 512 KB -# TAG: chunked_request_body_max_size (bytes) -# A broken or confused HTTP/1.1 client may send a chunked HTTP -# request to Squid. Squid does not have full support for that -# feature yet. To cope with such requests, Squid buffers the -# entire request and then dechunks request body to create a -# plain HTTP/1.0 request with a known content length. The plain -# request is then used by the rest of Squid code as usual. -# -# The option value specifies the maximum size of the buffer used -# to hold the request before the conversion. If the chunked -# request size exceeds the specified limit, the conversion -# fails, and the client receives an "unsupported request" error, -# as if dechunking was disabled. -# -# Dechunking is enabled by default. To disable conversion of -# chunked requests, set the maximum to zero. -# -# Request dechunking feature and this option in particular are a -# temporary hack. When chunking requests and responses are fully -# supported, there will be no need to buffer a chunked request. -#Default: -# chunked_request_body_max_size 64 KB - # TAG: broken_posts # A list of ACL elements which, if matched, causes Squid to send # an extra CRLF pair after the body of a PUT/POST request. @@ -3325,15 +5086,15 @@ refresh_pattern . 0 20% 4320 # acl buggy_server url_regex ^http://.... # broken_posts allow buggy_server #Default: -# none +# Obey RFC 2616. -# TAG: icap_uses_indirect_client on|off +# TAG: adaptation_uses_indirect_client on|off # Controls whether the indirect client IP address (instead of the direct # client IP address) is passed to adaptation services. # # See also: follow_x_forwarded_for adaptation_send_client_ip #Default: -# icap_uses_indirect_client on +# adaptation_uses_indirect_client on # TAG: via on|off # If set (default), Squid will include a Via header in requests and @@ -3395,64 +5156,62 @@ refresh_pattern . 0 20% 4320 # # 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). #Default: -# none +# No limits. # TAG: reply_header_access # Usage: reply_header_access header_name allow|deny [!]aclname ... @@ -3465,25 +5224,13 @@ refresh_pattern . 0 20% 4320 # 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 # @@ -3491,9 +5238,7 @@ refresh_pattern . 0 20% 4320 # 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 @@ -3501,29 +5246,22 @@ refresh_pattern . 0 20% 4320 # 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). #Default: -# none +# No limits. # TAG: request_header_replace # Usage: request_header_replace header_name message @@ -3531,8 +5269,7 @@ refresh_pattern . 0 20% 4320 # # 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. # @@ -3554,6 +5291,57 @@ refresh_pattern . 0 20% 4320 #Default: # none +# TAG: request_header_add +# 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. +#Default: +# none + +# TAG: note +# 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 ... +#Default: +# none + # TAG: relaxed_header_parser on|off|warn # In the default "on" setting Squid accepts certain forms # of non-compliant HTTP messages where it is unambiguous @@ -3569,15 +5357,32 @@ refresh_pattern . 0 20% 4320 #Default: # relaxed_header_parser on -# TAG: ignore_expect_100 on|off -# This option makes Squid ignore any Expect: 100-continue header present -# in the request. RFC 2616 requires that Squid being unable to satisfy -# the response expectation MUST return a 417 error. -# -# Note: Enabling this is a HTTP protocol violation, but some clients may -# not handle it well.. -#Default: -# ignore_expect_100 off +# TAG: collapsed_forwarding (on|off) +# When enabled, instead of forwarding each concurrent request for +# the same URL, Squid just sends the first of them. The other, so +# called "collapsed" requests, wait for the response to the first +# request and, if it happens to be cachable, use that response. +# Here, "concurrent requests" means "received after the first +# request headers were parsed and before the corresponding response +# headers were parsed". +# +# This feature is disabled by default: enabling collapsed +# forwarding needlessly delays forwarding requests that look +# cachable (when they are collapsed) but then need to be forwarded +# individually anyway because they end up being for uncachable +# content. However, in some cases, such as acceleration of highly +# cachable content with periodic or grouped expiration times, the +# gains from collapsing [large volumes of simultaneous refresh +# requests] outweigh losses from such delays. +# +# Squid collapses two kinds of requests: regular client requests +# received on one of the listening ports and internal "cache +# revalidation" requests which are triggered by those regular +# requests hitting a stale cached object. Revalidation collapsing +# is currently disabled for Squid instances containing SMP-aware +# disk or memory caches and for Vary-controlled cached objects. +#Default: +# collapsed_forwarding off # TIMEOUTS # ----------------------------------------------------------------------------- @@ -3604,25 +5409,46 @@ refresh_pattern . 0 20% 4320 # peer_connect_timeout 30 seconds # TAG: read_timeout time-units -# The read_timeout is applied on server-side connections. After -# each successful read(), the timeout will be extended by this +# Applied on peer server connections. +# +# After each successful read(), the timeout will be extended by this # amount. If no data is read again after this amount of time, -# the request is aborted and logged with ERR_READ_TIMEOUT. The -# default is 15 minutes. +# the request is aborted and logged with ERR_READ_TIMEOUT. +# +# The default is 15 minutes. #Default: # read_timeout 15 minutes +# TAG: write_timeout time-units +# This timeout is tracked for all connections that have data +# available for writing and are waiting for the socket to become +# ready. After each successful write, the timeout is extended by +# the configured amount. If Squid has data to write but the +# connection is not ready for the configured duration, the +# transaction associated with the connection is terminated. The +# default is 15 minutes. +#Default: +# write_timeout 15 minutes + # TAG: request_timeout # How long to wait for complete HTTP request headers after initial # connection establishment. #Default: # request_timeout 5 minutes -# TAG: persistent_request_timeout +# TAG: client_idle_pconn_timeout # How long to wait for the next HTTP request on a persistent -# connection after the previous request completes. +# client connection after the previous request completes. +#Default: +# client_idle_pconn_timeout 2 minutes + +# TAG: ftp_client_idle_timeout +# How long to wait for an FTP request on a connection to Squid ftp_port. +# Many FTP clients do not deal with idle connection closures well, +# necessitating a longer default timeout than client_idle_pconn_timeout +# used for incoming HTTP requests. #Default: -# persistent_request_timeout 2 minutes +# ftp_client_idle_timeout 30 minutes # TAG: client_lifetime time-units # The maximum amount of time a client (browser) is allowed to @@ -3658,11 +5484,11 @@ refresh_pattern . 0 20% 4320 #Default: # half_closed_clients off -# TAG: pconn_timeout +# TAG: server_idle_pconn_timeout # Timeout for idle persistent connections to servers and other # proxies. #Default: -# pconn_timeout 1 minute +# server_idle_pconn_timeout 1 minute # TAG: ident_timeout # Maximum time to wait for IDENT lookups to complete. @@ -3687,15 +5513,15 @@ refresh_pattern . 0 20% 4320 # TAG: cache_mgr # 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". #Default: # cache_mgr webmaster # TAG: mail_from # 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. #Default: # none @@ -3734,7 +5560,7 @@ refresh_pattern . 0 20% 4320 # Our preference is for administrators to configure a secure # user account for squid with UID/GID matching system policies. #Default: -# none +# Use system group memberships of the cache_effective_user account # TAG: httpd_suppress_version_string on|off # Suppress Squid version string info in HTTP headers and HTML error pages. @@ -3748,14 +5574,14 @@ refresh_pattern . 0 20% 4320 # get errors about IP-forwarding you must set them to have individual # names with this setting. #Default: -# visible_hostname localhost +# Automatically detect the system host name # TAG: unique_hostname # If you want to have multiple machines with the same # 'visible_hostname' you must give each machine a different # 'unique_hostname' so forwarding loops can be detected. #Default: -# none +# Copy the value from visible_hostname # TAG: hostname_aliases # A list of other DNS names your cache has. @@ -3794,33 +5620,32 @@ refresh_pattern . 0 20% 4320 # available on the Web at http://www.ircache.net/Cache/Tracker/. # TAG: announce_period -# 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. # # Example: # announce_period 1 day #Default: -# announce_period 0 +# Announcement messages disabled. # TAG: announce_host +# Set the hostname where announce registration messages will be sent. +# +# See also announce_port and announce_file #Default: # announce_host tracker.ircache.net # TAG: announce_file +# The contents of this file will be included in the announce +# registration messages. #Default: # none # TAG: announce_port -# 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 #Default: # announce_port 3131 @@ -3833,10 +5658,12 @@ refresh_pattern . 0 20% 4320 # a farm of surrogates may all perform the same tasks, they may share # an identification token. #Default: -# httpd_accel_surrogate_id unset-id +# visible_hostname is used if no specific ID is set. # TAG: http_accel_surrogate_remote on|off -# 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. #Default: # http_accel_surrogate_remote off @@ -3855,6 +5682,9 @@ refresh_pattern . 0 20% 4320 # 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. #Default: # delay_pools 0 @@ -3907,6 +5737,11 @@ refresh_pattern . 0 20% 4320 # # 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. #Default: # none @@ -3921,14 +5756,16 @@ refresh_pattern . 0 20% 4320 # 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. +# #Default: -# none +# Deny using the pool, unless allow rules exist in squid.conf for the pool. # TAG: delay_parameters # This defines the parameters for a delay pool. Each delay pool has @@ -3936,23 +5773,23 @@ refresh_pattern . 0 20% 4320 # description of delay_class. # # For a class 1 delay pool, the syntax is: -# delay_pools pool 1 +# delay_class pool 1 # delay_parameters pool aggregate # # For a class 2 delay pool: -# delay_pools pool 2 +# delay_class pool 2 # delay_parameters pool aggregate individual # # For a class 3 delay pool: -# delay_pools pool 3 +# delay_class pool 3 # delay_parameters pool aggregate network individual # # For a class 4 delay pool: -# delay_pools pool 4 +# delay_class pool 4 # delay_parameters pool aggregate network individual user # # For a class 5 delay pool: -# delay_pools pool 5 +# delay_class pool 5 # delay_parameters pool tagrate # # The option variables are: @@ -3988,11 +5825,11 @@ refresh_pattern . 0 20% 4320 # above example, and is being used to strictly limit each host to 64Kbit/sec # (plus overheads), with no overall limit, the line is: # -# delay_parameters 1 -1/-1 8000/8000 +# delay_parameters 1 none 8000/8000 # -# Note that 8 x 8000 KByte/sec -> 64Kbit/sec. +# Note that 8 x 8K Byte/sec -> 64K bit/sec. # -# Note that the figure -1 is used to represent "unlimited". +# Note that the word 'none' is used to represent no limit. # # # And, if delay pool number 2 is a class 3 delay pool as in the above @@ -4005,15 +5842,19 @@ refresh_pattern . 0 20% 4320 # # delay_parameters 2 32000/32000 8000/8000 600/8000 # -# Note that 8 x 32000 KByte/sec -> 256Kbit/sec. -# 8 x 8000 KByte/sec -> 64Kbit/sec. -# 8 x 600 Byte/sec -> 4800bit/sec. +# Note that 8 x 32K Byte/sec -> 256K bit/sec. +# 8 x 8K Byte/sec -> 64K bit/sec. +# 8 x 600 Byte/sec -> 4800 bit/sec. # # # Finally, for a class 4 delay pool as in the example - each user will # 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. +# #Default: # none @@ -4026,6 +5867,94 @@ refresh_pattern . 0 20% 4320 #Default: # delay_initial_bucket_level 50 +# CLIENT DELAY POOL PARAMETERS +# ----------------------------------------------------------------------------- + +# TAG: client_delay_pools +# This option specifies the number of client delay pools used. It must +# preceed other client_delay_* options. +# +# Example: +# client_delay_pools 2 +# +# See also client_delay_parameters and client_delay_access. +#Default: +# client_delay_pools 0 + +# TAG: client_delay_initial_bucket_level (percent, 0-no_limit) +# This option determines the initial bucket size as a percentage of +# max_bucket_size from client_delay_parameters. Buckets are created +# at the time of the "first" connection from the matching IP. Idle +# buckets are periodically deleted up. +# +# You can specify more than 100 percent but note that such "oversized" +# buckets are not refilled until their size goes down to max_bucket_size +# from client_delay_parameters. +# +# Example: +# client_delay_initial_bucket_level 50 +#Default: +# client_delay_initial_bucket_level 50 + +# TAG: client_delay_parameters +# +# This option configures client-side bandwidth limits using the +# following format: +# +# client_delay_parameters pool speed_limit max_bucket_size +# +# pool is an integer ID used for client_delay_access matching. +# +# speed_limit is bytes added to the bucket per second. +# +# max_bucket_size is the maximum size of a bucket, enforced after any +# speed_limit additions. +# +# Please see the delay_parameters option for more information and +# examples. +# +# Example: +# client_delay_parameters 1 1024 2048 +# client_delay_parameters 2 51200 16384 +# +# See also client_delay_access. +# +#Default: +# none + +# TAG: client_delay_access +# This option determines the client-side delay pool for the +# request: +# +# client_delay_access pool_ID allow|deny acl_name +# +# All client_delay_access options are checked in their pool ID +# order, starting with pool 1. The first checked pool with allowed +# request is selected for the request. If no ACL matches or there +# are no client_delay_access options, the request bandwidth is not +# limited. +# +# The ACL-selected pool is then used to find the +# client_delay_parameters for the request. Client-side pools are +# 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 +# +# +# See also client_delay_parameters and client_delay_pools. +#Default: +# Deny use of the pool, unless allow rules exist in squid.conf for the pool. + # WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS # ----------------------------------------------------------------------------- @@ -4040,7 +5969,7 @@ refresh_pattern . 0 20% 4320 # only one of the two may be used at the same time and defines # which version of WCCP to use. #Default: -# wccp_router any_addr +# WCCP disabled. # TAG: wccp2_router # Use this option to define your WCCP ``home'' router for @@ -4053,7 +5982,7 @@ refresh_pattern . 0 20% 4320 # only one of the two may be used at the same time and defines # which version of WCCP to use. #Default: -# none +# WCCPv2 disabled. # TAG: wccp_version # This directive is only relevant if you need to set up WCCP(v1) @@ -4110,7 +6039,7 @@ refresh_pattern . 0 20% 4320 # Valid values are as follows: # # hash - Hash assignment -# mask - Mask assignment +# mask - Mask assignment # # As a general rule, cisco routers support the hash assignment method # and cisco switches support the mask assignment method. @@ -4138,7 +6067,7 @@ refresh_pattern . 0 20% 4320 # # fleshed out with subsequent options. # wccp2_service standard 0 password=foo #Default: -# wccp2_service standard 0 +# Use the 'web-cache' standard service. # TAG: wccp2_service_info # Dynamic WCCPv2 services require further information to define the @@ -4175,8 +6104,12 @@ refresh_pattern . 0 20% 4320 # wccp2_weight 10000 # TAG: wccp_address +# Use this option if you require WCCPv2 to use a specific +# interface address. +# +# The default behavior is to not bind to any specific address. #Default: -# wccp_address 0.0.0.0 +# Address selected by the operating system. # TAG: wccp2_address # Use this option if you require WCCP to use a specific @@ -4184,7 +6117,7 @@ refresh_pattern . 0 20% 4320 # # The default behavior is to not bind to any specific address. #Default: -# wccp2_address 0.0.0.0 +# Address selected by the operating system. # PERSISTENT CONNECTION HANDLING # ----------------------------------------------------------------------------- @@ -4192,14 +6125,16 @@ refresh_pattern . 0 20% 4320 # Also see "pconn_timeout" in the TIMEOUTS section # TAG: client_persistent_connections +# Persistent connection support for clients. +# Squid uses persistent connections (when allowed). You can use +# this option to disable persistent connections with clients. #Default: # client_persistent_connections on # TAG: server_persistent_connections -# 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. #Default: # server_persistent_connections on @@ -4275,7 +6210,7 @@ refresh_pattern . 0 20% 4320 # Example: # snmp_port 3401 #Default: -# snmp_port 0 +# SNMP disabled. # TAG: snmp_access # Allowing or denying access to the SNMP port. @@ -4287,26 +6222,29 @@ refresh_pattern . 0 20% 4320 # # 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 #Default: -# snmp_access deny all +# Deny, unless rules exist in squid.conf. # TAG: snmp_incoming_address -#Default: -# snmp_incoming_address any_addr - -# TAG: snmp_outgoing_address # Just like 'udp_incoming_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. +#Default: +# Accept SNMP packets from all machine interfaces. + +# TAG: snmp_outgoing_address +# Just like 'udp_outgoing_address', but for the SNMP port. +# +# snmp_outgoing_address is used for SNMP packets returned to SNMP +# agents. # # 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 @@ -4314,9 +6252,9 @@ refresh_pattern . 0 20% 4320 # 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. #Default: -# snmp_outgoing_address no_addr +# Use snmp_incoming_address or an address selected by the operating system. # ICP OPTIONS # ----------------------------------------------------------------------------- @@ -4324,22 +6262,21 @@ refresh_pattern . 0 20% 4320 # TAG: icp_port # 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 3130 #Default: -# icp_port 0 +# ICP disabled. # TAG: htcp_port # 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 #Default: -# htcp_port 0 +# HTCP disabled. # TAG: log_icp_queries on|off # If set, ICP queries are logged to access.log. You may wish @@ -4365,7 +6302,7 @@ refresh_pattern . 0 20% 4320 # NOTE, udp_incoming_address and udp_outgoing_address can not # have the same value since they both use the same port. #Default: -# udp_incoming_address any_addr +# Accept packets from all machine interfaces. # TAG: udp_outgoing_address # udp_outgoing_address is used for UDP packets sent out to other @@ -4386,7 +6323,7 @@ refresh_pattern . 0 20% 4320 # NOTE, udp_incoming_address and udp_outgoing_address can not # have the same value since they both use the same port. #Default: -# udp_outgoing_address no_addr +# Use udp_incoming_address or an address selected by the operating system. # TAG: icp_hit_stale on|off # If you want to return ICP_HIT for stale cache objects, set this @@ -4405,21 +6342,33 @@ refresh_pattern . 0 20% 4320 #Default: # minimum_direct_hops 4 -# TAG: minimum_direct_rtt +# TAG: minimum_direct_rtt (msec) # If using the ICMP pinging stuff, do direct fetches for sites # which are no more than this many rtt milliseconds away. #Default: # minimum_direct_rtt 400 # TAG: netdb_low +# 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. #Default: # netdb_low 900 # TAG: netdb_high -# 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. #Default: # netdb_high 1000 @@ -4462,7 +6411,7 @@ refresh_pattern . 0 20% 4320 # # icp_query_timeout 2000 #Default: -# icp_query_timeout 0 +# Dynamic detection. # TAG: maximum_icp_query_timeout (msec) # Normally the ICP query timeout is determined dynamically. But @@ -4528,7 +6477,7 @@ refresh_pattern . 0 20% 4320 # Do not enable this option unless you are are absolutely # certain you understand what you are doing. #Default: -# mcast_miss_addr no_addr +# disabled. # TAG: mcast_miss_ttl # Note: This option is only available if Squid is rebuilt with the @@ -4618,7 +6567,7 @@ refresh_pattern . 0 20% 4320 # The squid developers working on translations are happy to supply drop-in # translated error files in exchange for any new language contributions. #Default: -# none +# Send error pages in the clients preferred language # TAG: error_default_language # Set the default language which squid will send error pages in @@ -4632,7 +6581,7 @@ refresh_pattern . 0 20% 4320 # translations for any language see the squid wiki for details. # http://wiki.squid-cache.org/Translations #Default: -# none +# Generate English language pages. # TAG: error_log_languages # Log to cache.log what languages users are attempting to @@ -4687,17 +6636,47 @@ refresh_pattern . 0 20% 4320 # the first authentication related acl encountered # - When none of the http_access lines matches. It's then the last # acl processed on the last http_access line. +# - When the decision to deny access was made by an adaptation service, +# the acl name is the corresponding eCAP or ICAP service_name. # # NP: If providing your own custom error pages with error_directory # you may also specify them by your custom file name: # Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys # -# Alternatively you can specify an error URL. The browsers will -# get redirected (302 or 307) to the specified URL. %s in the redirection -# URL will be replaced by the requested URL. +# By defaut Squid will send "403 Forbidden". A different 4xx or 5xx +# may be specified by prefixing the file name with the code and a colon. +# e.g. 404:ERR_CUSTOM_ACCESS_DENIED # # Alternatively you can tell Squid to reset the TCP connection # by specifying TCP_RESET. +# +# Or you can specify an error URL or URL pattern. The browsers will +# get redirected to the specified URL after formatting tags have +# been replaced. Redirect will be done with 302 or 307 according to +# HTTP/1.1 specs. A different 3xx code may be specified by prefixing +# the URL. e.g. 303:http://example.com/ +# +# URL FORMAT TAGS: +# %a - username (if available. Password NOT included) +# %B - FTP path URL +# %e - Error number +# %E - Error description +# %h - Squid hostname +# %H - Request domain name +# %i - Client IP Address +# %M - Request Method +# %o - Message result from external ACL helper +# %p - Request Port number +# %P - Request Protocol name +# %R - Request URL path +# %T - Timestamp in RFC 1123 format +# %U - Full canonical URL from client +# (HTTPS URLs terminate with *) +# %u - Full canonical URL from client +# %w - Admin email from squid.conf +# %x - Error name +# %% - Literal percent (%) code +# #Default: # none @@ -4706,18 +6685,18 @@ refresh_pattern . 0 20% 4320 # TAG: nonhierarchical_direct # By default, Squid will send any non-hierarchical requests -# (matching hierarchy_stoplist or not cacheable request type) direct -# to origin servers. +# (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. #Default: # nonhierarchical_direct on @@ -4736,6 +6715,29 @@ refresh_pattern . 0 20% 4320 #Default: # prefer_direct off +# TAG: cache_miss_revalidate on|off +# RFC 7232 defines a conditional request mechanism to prevent +# response objects being unnecessarily transferred over the network. +# If that mechanism is used by the client and a cache MISS occurs +# it can prevent new cache entries being created. +# +# This option determines whether Squid on cache MISS will pass the +# client revalidation request to the server or tries to fetch new +# content for caching. It can be useful while the cache is mostly +# empty to more quickly have the cache populated by generating +# non-conditional GETs. +# +# When set to 'on' (default), Squid will pass all client If-* headers +# to the server. This permits server responses without a cacheable +# payload to be delivered and on MISS no new cache entry is created. +# +# When set to 'off' and if the request is cacheable, Squid will +# remove the clients If-Modified-Since and If-None-Match headers from +# the request sent to the server. This requests a 200 status response +# from the server to create a new cache entry with. +#Default: +# cache_miss_revalidate on + # TAG: always_direct # Usage: always_direct allow|deny [!]aclname ... # @@ -4776,7 +6778,7 @@ refresh_pattern . 0 20% 4320 # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Prevent any cache_peer being used for this request. # TAG: never_direct # Usage: never_direct allow|deny [!]aclname ... @@ -4805,37 +6807,52 @@ refresh_pattern . 0 20% 4320 # This clause supports both fast and slow acl types. # See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. #Default: -# none +# Allow DNS results to be used for this request. # ADVANCED NETWORKING OPTIONS # ----------------------------------------------------------------------------- -# TAG: incoming_icp_average +# TAG: incoming_udp_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# incoming_icp_average 6 +# incoming_udp_average 6 -# TAG: incoming_http_average +# TAG: incoming_tcp_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# incoming_http_average 4 +# incoming_tcp_average 4 # TAG: incoming_dns_average +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: # incoming_dns_average 4 -# TAG: min_icp_poll_cnt +# TAG: min_udp_poll_cnt +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: -# min_icp_poll_cnt 8 +# min_udp_poll_cnt 8 # TAG: min_dns_poll_cnt +# Heavy voodoo here. I can't even believe you are reading this. +# Are you crazy? Don't even think about adjusting these unless +# you understand the algorithms in comm_select.c first! #Default: # min_dns_poll_cnt 8 -# TAG: min_http_poll_cnt +# TAG: min_tcp_poll_cnt # Heavy voodoo here. I can't even believe you are reading this. # Are you crazy? Don't even think about adjusting these unless # you understand the algorithms in comm_select.c first! #Default: -# min_http_poll_cnt 8 +# min_tcp_poll_cnt 8 # TAG: accept_filter # FreeBSD: @@ -4880,14 +6897,14 @@ refresh_pattern . 0 20% 4320 # WARNING: This may noticably slow down traffic received via external proxies # or NAT devices and cause them to rebound error messages back to their clients. #Default: -# client_ip_max_connections -1 +# No limit. # TAG: tcp_recv_bufsize (bytes) # 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. #Default: -# tcp_recv_bufsize 0 bytes +# Use operating system TCP defaults. # ICAP OPTIONS # ----------------------------------------------------------------------------- @@ -4913,22 +6930,36 @@ refresh_pattern . 0 20% 4320 # an established, active ICAP connection before giving up and # either terminating the HTTP transaction or bypassing the # failure. -# -# The default is read_timeout. #Default: -# none +# Use read_timeout. -# TAG: icap_service_failure_limit +# TAG: icap_service_failure_limit limit [in memory-depth time-units] # The limit specifies the number of failures that Squid tolerates # when establishing a new TCP connection with an ICAP service. If # the number of failures exceeds the limit, the ICAP service is # not used for new ICAP requests until it is time to refresh its -# OPTIONS. The per-service failure counter is reset to zero each -# time Squid fetches new service OPTIONS. +# OPTIONS. # # A negative value disables the limit. Without the limit, an ICAP # service will not be considered down due to connectivity failures # between ICAP OPTIONS requests. +# +# Squid forgets ICAP service failures older than the specified +# value of memory-depth. The memory fading algorithm +# is approximate because Squid does not remember individual +# errors but groups them instead, splitting the option +# value into ten time slots of equal length. +# +# When memory-depth is 0 and by default this option has no +# effect on service failure expiration. +# +# Squid always forgets failures when updating service settings +# using an ICAP OPTIONS transaction, regardless of this option +# setting. +# +# For example, +# # suspend service usage after 10 failures in 5 seconds: +# icap_service_failure_limit 10 in 5 seconds #Default: # icap_service_failure_limit 10 @@ -4962,10 +6993,26 @@ refresh_pattern . 0 20% 4320 # TAG: icap_preview_size # 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. #Default: -# icap_preview_size -1 +# No preview sent. + +# TAG: icap_206_enable on|off +# 206 (Partial Content) responses is an ICAP extension that allows the +# ICAP agents to optionally combine adapted and original HTTP message +# content. The decision to combine is postponed until the end of the +# ICAP response. Squid supports Partial Content extension by default. +# +# Activation of the Partial Content extension is negotiated with each +# ICAP service during OPTIONS exchange. Most ICAP servers should handle +# negotation correctly even if they do not support the extension, but +# some might fail. To disable Partial Content support for all ICAP +# services and to avoid any negotiation, set this option to "off". +# +# Example: +# icap_206_enable off +#Default: +# icap_206_enable on # TAG: icap_default_options_ttl # The default TTL value for ICAP OPTIONS responses that don't have @@ -4979,25 +7026,27 @@ refresh_pattern . 0 20% 4320 #Default: # icap_persistent_connections on -# TAG: icap_send_client_ip on|off +# TAG: adaptation_send_client_ip on|off # If enabled, Squid shares HTTP client IP information with adaptation # services. For ICAP, Squid adds the X-Client-IP header to ICAP requests. # For eCAP, Squid sets the libecap::metaClientIp transaction option. # # See also: adaptation_uses_indirect_client #Default: -# icap_send_client_ip off +# adaptation_send_client_ip off -# TAG: icap_send_client_username on|off +# TAG: adaptation_send_username on|off # This sends authenticated HTTP client username (if available) to -# the ICAP service. The username value is encoded based on the +# the adaptation service. +# +# For ICAP, the username value is encoded based on the # icap_client_username_encode option and is sent using the header # specified by the icap_client_username_header option. #Default: -# icap_send_client_username off +# adaptation_send_username off # TAG: icap_client_username_header -# ICAP request header name to use for send_client_username. +# ICAP request header name to use for adaptation_send_username. #Default: # icap_client_username_header X-Client-Username @@ -5009,17 +7058,19 @@ refresh_pattern . 0 20% 4320 # TAG: icap_service # Defines a single ICAP service using the following format: # -# icap_service service_name vectoring_point [options] service_url +# icap_service id vectoring_point uri [option ...] # -# service_name: ID -# an opaque identifier which must be unique in squid.conf +# id: ID +# an opaque identifier or name which is used to direct traffic to +# this specific service. Must be unique among all adaptation +# services in squid.conf. # # vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache # This specifies at which point of transaction processing the # ICAP service should be activated. *_postcache vectoring points # are not yet supported. # -# service_url: icap://servername:port/servicepath +# uri: icap://servername:port/servicepath # ICAP server and service location. # # ICAP does not allow a single service to handle both REQMOD and RESPMOD @@ -5028,6 +7079,8 @@ refresh_pattern . 0 20% 4320 # can even specify multiple identical services as long as their # service_names differ. # +# To activate a service, use the adaptation_access directive. To group +# services, use adaptation_service_chain and adaptation_service_set. # # Service options are separated by white space. ICAP services support # the following name=value options: @@ -5049,11 +7102,12 @@ refresh_pattern . 0 20% 4320 # returning a chain of services to be used next. The services # are specified using the X-Next-Services ICAP response header # value, formatted as a comma-separated list of service names. -# Each named service should be configured in squid.conf and -# should have the same method and vectoring point as the current -# ICAP transaction. Services violating these rules are ignored. -# An empty X-Next-Services value results in an empty plan which -# ends the current adaptation. +# Each named service should be configured in squid.conf. Other +# services are ignored. An empty X-Next-Services value results +# in an empty plan which ends the current adaptation. +# +# Dynamic adaptation plan may cross or cover multiple supported +# vectoring points in their natural processing order. # # Routing is not allowed by default: the ICAP X-Next-Services # response header is ignored. @@ -5063,12 +7117,32 @@ refresh_pattern . 0 20% 4320 # is to use IPv4-only connections. When set to 'on' this option will # make Squid use IPv6-only connections to contact this ICAP service. # +# on-overload=block|bypass|wait|force +# If the service Max-Connections limit has been reached, do +# one of the following for each new ICAP transaction: +# * block: send an HTTP error response to the client +# * bypass: ignore the "over-connected" ICAP service +# * wait: wait (in a FIFO queue) for an ICAP connection slot +# * force: proceed, ignoring the Max-Connections limit +# +# In SMP mode with N workers, each worker assumes the service +# connection limit is Max-Connections/N, even though not all +# workers may use a given service. +# +# The default value is "bypass" if service is bypassable, +# otherwise it is set to "wait". +# +# +# max-conn=number +# Use the given number as the Max-Connections limit, regardless +# of the Max-Connections value given by the service, if any. +# # Older icap_service format without optional named parameters is # deprecated but supported for backward compatibility. # #Example: -#icap_service svcBlocker reqmod_precache bypass=0 icap://icap1.mydomain.net:1344/reqmod -#icap_service svcLogger reqmod_precache routing=on icap://icap2.mydomain.net:1344/respmod +#icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0 +#icap_service svcLogger reqmod_precache icap://icap2.mydomain.net:1344/respmod routing=on #Default: # none @@ -5094,38 +7168,65 @@ refresh_pattern . 0 20% 4320 # ----------------------------------------------------------------------------- # TAG: ecap_enable on|off -# Note: This option is only available if Squid is rebuilt with the -# --enable-ecap option -# # Controls whether eCAP support is enabled. #Default: # ecap_enable off # TAG: ecap_service -# Note: This option is only available if Squid is rebuilt with the -# --enable-ecap option -# # Defines a single eCAP service # -# ecap_service servicename vectoring_point bypass service_url +# ecap_service id vectoring_point uri [option ...] # -# vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache +# id: ID +# an opaque identifier or name which is used to direct traffic to +# this specific service. Must be unique among all adaptation +# services in squid.conf. +# +# vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache # This specifies at which point of transaction processing the # eCAP service should be activated. *_postcache vectoring points # are not yet supported. -# bypass = 1|0 -# If set to 1, the eCAP service is treated as optional. If the -# service cannot be reached or malfunctions, Squid will try to -# ignore any errors and process the message as if the service +# +# uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional +# Squid uses the eCAP service URI to match this configuration +# line with one of the dynamically loaded services. Each loaded +# eCAP service must have a unique URI. Obtain the right URI from +# the service provider. +# +# To activate a service, use the adaptation_access directive. To group +# services, use adaptation_service_chain and adaptation_service_set. +# +# Service options are separated by white space. eCAP services support +# the following name=value options: +# +# bypass=on|off|1|0 +# If set to 'on' or '1', the eCAP service is treated as optional. +# If the service cannot be reached or malfunctions, Squid will try +# to ignore any errors and process the message as if the service # was not enabled. No all eCAP errors can be bypassed. -# If set to 0, the eCAP service is treated as essential and all -# eCAP errors will result in an error page returned to the +# If set to 'off' or '0', the eCAP service is treated as essential +# and all eCAP errors will result in an error page returned to the # HTTP client. -# service_url = ecap://vendor/service_name?custom&cgi=style¶meters=optional +# +# Bypass is off by default: services are treated as essential. +# +# routing=on|off|1|0 +# If set to 'on' or '1', the eCAP service is allowed to +# dynamically change the current message adaptation plan by +# returning a chain of services to be used next. +# +# Dynamic adaptation plan may cross or cover multiple supported +# vectoring points in their natural processing order. +# +# Routing is not allowed by default. +# +# Older ecap_service format without optional named parameters is +# deprecated but supported for backward compatibility. +# # #Example: -#ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block -#ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg +#ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off +#ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on #Default: # none @@ -5247,7 +7348,7 @@ refresh_pattern . 0 20% 4320 #Example: #adaptation_access service_1 allow all #Default: -# none +# Allow, unless rules exist in squid.conf. # TAG: adaptation_service_iteration_limit # Limits the number of iterations allowed when applying adaptation @@ -5275,8 +7376,14 @@ refresh_pattern . 0 20% 4320 # # An ICAP REQMOD or RESPMOD transaction may set an entry in the # shared table by returning an ICAP header field with a name -# specified in adaptation_masterx_shared_names. Squid will store -# and forward that ICAP header field to subsequent ICAP +# specified in adaptation_masterx_shared_names. +# +# An eCAP REQMOD or RESPMOD transaction may set an entry in the +# shared table by implementing the libecap::visitEachOption() API +# to provide an option with a name specified in +# adaptation_masterx_shared_names. +# +# Squid will store and forward the set entry to subsequent adaptation # transactions within the same master transaction scope. # # Only one shared entry name is supported at this time. @@ -5287,6 +7394,43 @@ refresh_pattern . 0 20% 4320 #Default: # none +# TAG: adaptation_meta +# This option allows Squid administrator to add custom ICAP request +# headers or eCAP options to Squid ICAP requests or eCAP transactions. +# Use it to pass custom authentication tokens and other +# transaction-state related meta information to an ICAP/eCAP service. +# +# The addition of a meta header is ACL-driven: +# adaptation_meta name value [!]aclname ... +# +# Processing for a given header name stops after the first ACL list match. +# Thus, it is impossible to add two headers with the same name. If no ACL +# lists match for a given header name, no such header is added. For +# example: +# +# # do not debug transactions except for those that need debugging +# adaptation_meta X-Debug 1 needs_debugging +# +# # log all transactions except for those that must remain secret +# adaptation_meta X-Log 1 !keep_secret +# +# # mark transactions from users in the "G 1" group +# adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1 +# +# The "value" parameter may be a regular squid.conf token or a "double +# quoted string". Within the quoted string, use backslash (\) to escape +# any character, which is currently only useful for escaping backslashes +# 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). +#Default: +# none + # TAG: icap_retry # This ACL determines which retriable ICAP transactions are # retried. Transactions that received a complete ICAP response @@ -5303,8 +7447,7 @@ refresh_pattern . 0 20% 4320 # icap_retry deny all # TAG: icap_retry_limit -# 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 @@ -5312,7 +7455,7 @@ refresh_pattern . 0 20% 4320 # # See also: icap_retry #Default: -# icap_retry_limit 0 +# No retries are allowed. # DNS OPTIONS # ----------------------------------------------------------------------------- @@ -5332,31 +7475,9 @@ refresh_pattern . 0 20% 4320 #Default: # allow_underscore on -# TAG: cache_dns_program -# Note: This option is only available if Squid is rebuilt with the -# --disable-internal-dns option -# -# Specify the location of the executable for dnslookup process. -#Default: -# cache_dns_program /usr/lib/squid/dnsserver - -# TAG: dns_children -# Note: This option is only available if Squid is rebuilt with the -# --disable-internal-dns option -# -# The number of processes spawn to service DNS name lookups. -# For heavily loaded caches on large servers, you should -# probably increase this value to at least 10. The maximum -# is 32. The default is 5. -# -# You must have at least one dnsserver process. -#Default: -# dns_children 5 - # TAG: dns_retransmit_interval # Initial retransmit interval for DNS queries. The interval is # doubled each time all configured DNS servers have been tried. -# #Default: # dns_retransmit_interval 5 seconds @@ -5365,7 +7486,31 @@ refresh_pattern . 0 20% 4320 # within this time all DNS servers for the queried domain # are assumed to be unavailable. #Default: -# dns_timeout 2 minutes +# dns_timeout 30 seconds + +# TAG: dns_packet_max +# Maximum number of bytes packet size to advertise via EDNS. +# Set to "none" to disable EDNS large packet support. +# +# For legacy reasons DNS UDP replies will default to 512 bytes which +# is too small for many responses. EDNS provides a means for Squid to +# negotiate receiving larger responses back immediately without having +# to failover with repeat requests. Responses larger than this limit +# will retain the old behaviour of failover to TCP DNS. +# +# Squid has no real fixed limit internally, but allowing packet sizes +# over 1500 bytes requires network jumbogram support and is usually not +# necessary. +# +# WARNING: The RFC also indicates that some older resolvers will reply +# with failure of the whole request if the extension is added. Some +# resolvers have already been identified which will reply with mangled +# EDNS response on occasion. Usually in response to many-KB jumbogram +# sizes being advertised by Squid. +# Squid will currently treat these both as an unable-to-resolve domain +# even if it would be resolvable without EDNS. +#Default: +# EDNS disabled # TAG: dns_defnames on|off # Normally the RES_DEFNAMES resolver option is disabled @@ -5373,12 +7518,21 @@ refresh_pattern . 0 20% 4320 # from interpreting single-component hostnames locally. To allow # Squid to handle single-component names, enable this option. #Default: -# dns_defnames off +# Search for single-label domain names is disabled. + +# TAG: dns_multicast_local on|off +# When set to on, Squid sends multicast DNS lookups on the local +# network for domains ending in .local and .arpa. +# This enables local servers and devices to be contacted in an +# ad-hoc or zero-configuration network environment. +#Default: +# Search for .local and .arpa names is disabled. # TAG: dns_nameservers # 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 @@ -5386,7 +7540,7 @@ refresh_pattern . 0 20% 4320 # # Example: dns_nameservers 10.0.0.1 192.172.0.4 #Default: -# none +# Use operating system definitions # TAG: hosts_file # Location of the host-local IP name-address associations @@ -5425,7 +7579,7 @@ refresh_pattern . 0 20% 4320 #Example: # append_domain .yourdomain.com #Default: -# none +# Use operating system definitions # TAG: ignore_unknown_nameservers # By default Squid checks that DNS responses are received @@ -5436,23 +7590,6 @@ refresh_pattern . 0 20% 4320 #Default: # ignore_unknown_nameservers on -# TAG: dns_v4_fallback -# Standard practice with DNS is to lookup either A or AAAA records -# and use the results if it succeeds. Only looking up the other if -# the first attempt fails or otherwise produces no results. -# -# That policy however will cause squid to produce error pages for some -# servers that advertise AAAA but are unreachable over IPv6. -# -# If this is ON squid will always lookup both AAAA and A, using both. -# If this is OFF squid will lookup AAAA and only try A if none found. -# -# WARNING: There are some possibly unwanted side-effects with this on: -# *) Doubles the load placed by squid on the DNS network. -# *) May negatively impact connection delay times. -#Default: -# dns_v4_fallback on - # TAG: dns_v4_first # With the IPv6 Internet being as fast or faster than IPv4 Internet # for most networks Squid prefers to contact websites over IPv6. @@ -5464,11 +7601,12 @@ refresh_pattern . 0 20% 4320 # WARNING: # This option will restrict the situations under which IPv6 # connectivity is used (and tested), potentially hiding network -# problem swhich would otherwise be detected and warned about. +# problems which would otherwise be detected and warned about. #Default: # dns_v4_first off # TAG: ipcache_size (number of entries) +# Maximum number of DNS IP cache entries. #Default: # ipcache_size 1024 @@ -5489,6 +7627,15 @@ refresh_pattern . 0 20% 4320 # MISCELLANEOUS # ----------------------------------------------------------------------------- +# TAG: configuration_includes_quoted_values on|off +# If set, Squid will recognize each "quoted string" after a configuration +# directive as a single parameter. The quotes are stripped before the +# parameter value is interpreted or used. +# See "Values with spaces, quotes, and other special characters" +# section for more details. +#Default: +# configuration_includes_quoted_values off + # TAG: memory_pools on|off # If set, Squid will keep pools of allocated (but unused) memory # available for future use. If memory is a premium on your @@ -5539,7 +7686,7 @@ refresh_pattern . 0 20% 4320 # X-Forwarded-For header. # # If set to "truncate", Squid will remove all existing -# X-Forwarded-For entries, and place itself as the sole entry. +# X-Forwarded-For entries, and place the client IP as the sole entry. #Default: # forwarded_for on @@ -5602,7 +7749,7 @@ refresh_pattern . 0 20% 4320 # cachemgr_passwd lesssssssecret info stats/objects # cachemgr_passwd disable all #Default: -# none +# No password. Actions which require password are denied. # TAG: client_db on|off # If you want to disable collecting per-client statistics, @@ -5633,19 +7780,22 @@ refresh_pattern . 0 20% 4320 #Default: # reload_into_ims off -# TAG: maximum_single_addr_tries -# This sets the maximum number of connection attempts for a -# host that only has one address (for multiple-address hosts, -# each address is tried once). +# TAG: connect_retries +# This sets the maximum number of connection attempts made for each +# TCP connection. The connect_retries attempts must all still +# complete within the connection timeout period. # -# The default value is one attempt, the (not recommended) -# maximum is 255 tries. A warning message will be generated -# if it is set to a value greater than ten. +# The default is not to re-try if the first connection attempt fails. +# The (not recommended) maximum is 10 tries. # -# Note: This is in addition to the request re-forwarding which -# takes place if Squid fails to get a satisfying response. +# A warning message will be generated if it is set to a too-high +# value and the configured value will be over-ridden. +# +# Note: These re-tries are in addition to forward_max_tries +# which limit how many different addresses may be tried to find +# a useful server. #Default: -# maximum_single_addr_tries 1 +# Do not retry failed connections. # TAG: retry_on_error # If set to ON Squid will automatically retry requests when @@ -5678,20 +7828,32 @@ refresh_pattern . 0 20% 4320 # 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. #Default: # uri_whitespace strip @@ -5718,23 +7880,28 @@ refresh_pattern . 0 20% 4320 # balance_on_multiple_ip off # TAG: pipeline_prefetch -# To boost the performance of pipelined requests to closer -# match that of a non-proxied environment Squid can try to fetch -# up to two requests in parallel from a pipeline. -# -# Defaults to off for bandwidth management and access logging +# HTTP clients may send a pipeline of 1+N requests to Squid using a +# single connection, without waiting for Squid to respond to the first +# of those requests. This option limits the number of concurrent +# requests Squid will try to handle in parallel. If set to N, Squid +# will try to receive and process up to 1+N requests on the same +# connection concurrently. +# +# Defaults to 0 (off) for bandwidth management and access logging # reasons. # +# NOTE: pipelining requires persistent connections to clients. +# # WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication. #Default: -# pipeline_prefetch off +# Do not pre-parse pipelined requests. # TAG: high_response_time_warning (msec) # If the one-minute median response time exceeds this value, # Squid prints a WARNING with debug level 0 to get the # administrators attention. The value is in milliseconds. #Default: -# high_response_time_warning 0 +# disabled. # TAG: high_page_fault_warning # If the one-minute average page fault rate exceeds this @@ -5742,14 +7909,17 @@ refresh_pattern . 0 20% 4320 # the administrators attention. The value is in page faults # per second. #Default: -# high_page_fault_warning 0 +# disabled. # TAG: high_memory_warning -# If the memory usage (as determined by mallinfo) exceeds -# this amount, Squid prints a WARNING with debug level 0 to get +# Note: This option is only available if Squid is rebuilt with the +# GNU Malloc with mstats() +# +# If the memory usage (as determined by gnumalloc, if available and used) +# exceeds this amount, Squid prints a WARNING with debug level 0 to get # the administrators attention. #Default: -# high_memory_warning 0 KB +# disabled. # TAG: sleep_after_fork (microseconds) # When this is set to a non-zero value, the main Squid process @@ -5766,6 +7936,9 @@ refresh_pattern . 0 20% 4320 # sleep_after_fork 0 # TAG: windows_ipaddrchangemonitor on|off +# Note: This option is only available if Squid is rebuilt with the +# MS Windows +# # On Windows Squid by default will monitor IP address changes and will # reconfigure itself after any detected event. This is very useful for # proxies connected to internet with dial-up interfaces. @@ -5775,13 +7948,19 @@ refresh_pattern . 0 20% 4320 #Default: # windows_ipaddrchangemonitor on +# TAG: eui_lookup +# Whether to lookup the EUI or MAC address of a connected client. +#Default: +# eui_lookup on + # TAG: max_filedescriptors -# 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). #Default: -# max_filedescriptors 0 +# Use operating system limits set by ulimit. |