#
-# $Id: cf.data.pre,v 1.464 2007/09/03 04:35:05 hno Exp $
+# $Id: cf.data.pre,v 1.465 2007/09/04 17:39:57 hno Exp $
#
# SQUID Web Proxy Cache http://www.squid-cache.org/
# ----------------------------------------------------------
DOC_END
COMMENT_START
- SSL OPTIONS
+ OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
COMMENT_END
-NAME: ssl_unclean_shutdown
-IFDEF: USE_SSL
-TYPE: onoff
-DEFAULT: off
-LOC: Config.SSL.unclean_shutdown
-DOC_START
- Some browsers (especially MSIE) bugs out on SSL shutdown
- messages.
-DOC_END
-
-NAME: ssl_engine
-IFDEF: USE_SSL
-TYPE: string
-LOC: Config.SSL.ssl_engine
+NAME: auth_param
+TYPE: authparam
+LOC: Config.authConfiguration
DEFAULT: none
DOC_START
- The OpenSSL engine to use. You will need to set this if you
- would like to use hardware SSL acceleration for example.
-DOC_END
+ This is used to define parameters for the various authentication
+ schemes supported by Squid.
-NAME: sslproxy_client_certificate
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cert
-TYPE: string
-DOC_START
- Client SSL Certificate to use when proxying https:// URLs
-DOC_END
+ format: auth_param scheme parameter [setting]
-NAME: sslproxy_client_key
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.key
-TYPE: string
-DOC_START
- Client SSL Key to use when proxying https:// URLs
-DOC_END
+ The order in which authentication schemes are presented to the client is
+ dependent on the order the scheme first appears in config file. IE
+ has a bug (it's not RFC 2617 compliant) in that it will use the basic
+ scheme if basic is the first entry presented, even if more secure
+ schemes are presented. For now use the order in the recommended
+ settings section below. If other browsers have difficulties (don't
+ recognize the schemes offered even if you are using basic) either
+ put basic first, or disable the other schemes (by commenting out their
+ program entry).
-NAME: sslproxy_version
-IFDEF: USE_SSL
-DEFAULT: 1
-LOC: Config.ssl_client.version
-TYPE: int
-DOC_START
- SSL version level to use when proxying https:// URLs
-DOC_END
+ Once an authentication scheme is fully configured, it can only be
+ shutdown by shutting squid down and restarting. Changes can be made on
+ the fly and activated with a reconfigure. I.E. You can change to a
+ different helper, but not unconfigure the helper completely.
-NAME: sslproxy_options
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.options
-TYPE: string
-DOC_START
- SSL engine options to use when proxying https:// URLs
-DOC_END
+ Please note that while this directive defines how Squid processes
+ authentication it does not automatically activate authentication.
+ To use authentication you must in addition make use of ACLs based
+ on login name in http_access (proxy_auth, proxy_auth_regex or
+ external with %LOGIN used in the format tag). The browser will be
+ challenged for authentication on the first such acl encountered
+ in http_access processing and will also be re-challenged for new
+ login credentials if the request is being denied by a proxy_auth
+ type acl.
-NAME: sslproxy_cipher
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cipher
-TYPE: string
-DOC_START
- SSL cipher list to use when proxying https:// URLs
-DOC_END
+ WARNING: authentication can't be used in a transparently intercepting
+ proxy as the client then thinks it is talking to an origin server and
+ not the proxy. This is a limitation of bending the TCP/IP protocol to
+ transparently intercepting port 80, not a limitation in Squid.
-NAME: sslproxy_cafile
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cafile
-TYPE: string
-DOC_START
- file containing CA certificates to use when verifying server
- certificates while proxying https:// URLs
-DOC_END
+ === Parameters for the basic scheme follow. ===
-NAME: sslproxy_capath
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.capath
-TYPE: string
-DOC_START
- directory containing CA certificates to use when verifying
- server certificates while proxying https:// URLs
-DOC_END
+ "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.
-NAME: sslproxy_flags
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.flags
-TYPE: string
-DOC_START
- Various flags modifying the use of SSL while proxying https:// URLs:
- DONT_VERIFY_PEER Accept certificates even if they fail to
- verify.
- NO_DEFAULT_CA Don't use the default CA list built in
- to OpenSSL.
-DOC_END
+ By default, the basic authentication scheme is not used unless a
+ program is specified.
-NAME: sslpassword_program
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.Program.ssl_password
-TYPE: string
-DOC_START
- Specify a program used for entering SSL key passphrases
- when using encrypted SSL certificate keys. If not specified
- keys must either be unencrypted, or Squid started with the -N
- option to allow it to query interactively for the passphrase.
-DOC_END
+ If you want to use the traditional NCSA proxy authentication, set
+ this line to something like
-COMMENT_START
- OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
- -----------------------------------------------------------------------------
-COMMENT_END
+ auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
-NAME: cache_peer
-TYPE: peer
-DEFAULT: none
-LOC: Config.peers
-DOC_START
- To specify other caches in a hierarchy, use the format:
+ "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
- cache_peer hostname type http-port icp-port [options]
+ "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
- For example,
+ "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
- # proxy icp
- # hostname type port port options
- # -------------------- -------- ----- ----- -----------
- cache_peer parent.foo.net parent 3128 3130 proxy-only default
- cache_peer sib1.foo.net sibling 3128 3130 proxy-only
- cache_peer sib2.foo.net sibling 3128 3130 proxy-only
+ "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.
- type: either 'parent', 'sibling', or 'multicast'.
+ "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
- proxy-port: The port number where the cache listens for proxy
- requests.
+ === Parameters for the digest scheme follow ===
- icp-port: Used for querying neighbor caches about
- objects. To have a non-ICP neighbor
- specify '7' for the ICP port and make sure the
- neighbor machine has the UDP echo port
- enabled in its /etc/inetd.conf file.
- NOTE: Also requires icp_port option enabled to send/receive
- requests via this method.
+ "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.
- options: proxy-only
- weight=n
- basetime=n
- ttl=n
- no-query
- background-ping
- default
- round-robin
- weighted-round-robin
- carp
- multicast-responder
- closest-only
- no-digest
- no-netdb-exchange
- no-delay
- login=user:password | PASS | *:password
- connect-timeout=nn
- digest-url=url
- allow-miss
- max-conn=n
- htcp
- htcp-oldsquid
- originserver
- name=xxx
- forceddomain=name
- ssl
- sslcert=/path/to/ssl/certificate
- sslkey=/path/to/ssl/key
- sslversion=1|2|3|4
- sslcipher=...
- ssloptions=...
- front-end-https[=on|auto]
+ By default, the digest authentication scheme is not used unless a
+ program is specified.
- use 'proxy-only' to specify objects fetched
- from this cache should not be saved locally.
+ If you want to use a digest authenticator, set this line to
+ something like
- use 'weight=n' to affect the selection of a peer
- during any weighted peer-selection mechanisms.
- The weight must be an integer; default is 1,
- larger weights are favored more.
- This option does not affect parent selection if a peering
- protocol is not in use.
-
- use 'basetime=n' to specify a base amount to
- be subtracted from round trip times of parents.
- It is subtracted before division by weight in calculating
- which parent to fectch from. If the rtt is less than the
- base time the rtt is set to a minimal value.
-
- use 'ttl=n' to specify a IP multicast TTL to use
- when sending an ICP queries to this address.
- Only useful when sending to a multicast group.
- Because we don't accept ICP replies from random
- hosts, you must configure other group members as
- peers with the 'multicast-responder' option below.
+ auth_param digest program @DEFAULT_PREFIX@/bin/digest_auth_pw @DEFAULT_PREFIX@/etc/digpass
- use 'no-query' to NOT send ICP queries to this
- neighbor.
+ "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
- use 'background-ping' to only send ICP queries to this
- neighbor infrequently. This is used to keep the neighbor
- round trip time updated and is usually used in
- conjunction with weighted-round-robin.
+ "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
- use 'default' if this is a parent cache which can
- be used as a "last-resort" if a peer cannot be located
- by any of the peer-selection mechanisms.
- If specified more than once, only the first is used.
+ "nonce_garbage_interval" timeinterval
+ Specifies the interval that nonces that have been issued
+ to client_agent's are checked for validity.
- use 'round-robin' to define a set of parents which
- should be used in a round-robin fashion in the
- absence of any ICP queries.
+ "nonce_max_duration" timeinterval
+ Specifies the maximum length of time a given nonce will be
+ valid for.
- use 'weighted-round-robin' to define a set of parents
- which should be used in a round-robin fashion with the
- frequency of each parent being based on the round trip
- time. Closer parents are used more often.
- Usually used for background-ping parents.
+ "nonce_max_count" number
+ Specifies the maximum number of times a given nonce can be
+ used.
- use 'carp' to define a set of parents which should
- be used as a CARP array. The requests will be
- distributed among the parents based on the CARP load
- balancing hash function based on their weigth.
+ "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.
- 'multicast-responder' indicates the named peer
- is a member of a multicast group. ICP queries will
- not be sent directly to the peer, but ICP replies
- will be accepted from it.
+ "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.
- 'closest-only' indicates that, for ICP_OP_MISS
- replies, we'll only forward CLOSEST_PARENT_MISSes
- and never FIRST_PARENT_MISSes.
+ "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.
- use 'no-digest' to NOT request cache digests from
- this neighbor.
+ === NTLM scheme options follow ===
- 'no-netdb-exchange' disables requesting ICMP
- RTT database (NetDB) from the neighbor.
+ "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.
- use 'no-delay' to prevent access to this neighbor
- from influencing the delay pools.
+ auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
- use 'login=user:password' if this is a personal/workgroup
- proxy and your parent requires proxy authentication.
- Note: The string can include URL escapes (i.e. %20 for
- spaces). This also means % must be written as %%.
+ "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.
- use 'login=PASS' if users must authenticate against
- the upstream proxy or in the case of a reverse proxy
- configuration, the origin web server. This will pass
- the users credentials as they are to the peer.
- This only works for the Basic HTTP authentication scheme.
- Note: To combine this with proxy_auth both proxies must
- share the same user database as HTTP only allows for
- a single login (one for proxy, one for origin server).
- Also be warned this will expose your users proxy
- password to the peer. USE WITH CAUTION
+ auth_param ntlm children 5
- use 'login=*:password' to pass the username to the
- upstream cache, but with a fixed password. This is meant
- to be used when the peer is in another administrative
- domain, but it is still needed to identify each user.
- The star can optionally be followed by some extra
- information which is added to the username. This can
- be used to identify this proxy to the peer, similar to
- the login=username:password option above.
+ "keep_alive" on|off
+ If you experience problems with PUT/POST requests when using the
+ Negotiate authentication scheme then you can try setting this to
+ off. This will cause Squid to forcibly close the connection on
+ the initial requests where the browser asks which schemes are
+ supported by the proxy.
- use 'connect-timeout=nn' to specify a peer
- specific connect timeout (also see the
- peer_connect_timeout directive)
+ auth_param ntlm keep_alive on
- use 'digest-url=url' to tell Squid to fetch the cache
- digest (if digests are enabled) for this host from
- the specified URL rather than the Squid default
- location.
+ === Options for configuring the NEGOTIATE auth-scheme follow ===
- use 'allow-miss' to 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)
+ "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.
- use 'max-conn=n' to limit the amount of connections Squid
- may open to this peer.
+ auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
- use 'htcp' to send HTCP, instead of ICP, queries
- to the neighbor. You probably also want to
- set the "icp port" to 4827 instead of 3130.
+ "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
- use 'htcp-oldsquid' to send HTCP to old Squid versions
+ "keep_alive" on|off
+ If you experience problems with PUT/POST requests when using the
+ Negotiate authentication scheme then you can try setting this to
+ off. This will cause Squid to forcibly close the connection on
+ the initial requests where the browser asks which schemes are
+ supported by the proxy.
- 'originserver' causes this parent peer to be contacted as
- a origin server. Meant to be used in accelerator setups.
+ auth_param negotiate keep_alive on
- use 'name=xxx' if you have multiple peers on the same
- host but different ports. This name can be used to
- differentiate the peers in cache_peer_access and similar
- directives.
+NOCOMMENT_START
+#Recommended minimum configuration per scheme:
+#auth_param negotiate program <uncomment and complete this line to activate>
+#auth_param negotiate children 5
+#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 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 basic program <uncomment and complete this line>
+#auth_param basic children 5
+#auth_param basic realm Squid proxy-caching web server
+#auth_param basic credentialsttl 2 hours
+NOCOMMENT_END
+DOC_END
- use 'forceddomain=name' to forcibly set the Host header
- of requests forwarded to this peer. Useful in accelerator
- setups where the server (peer) expects a certain domain
- name and using redirectors to feed this domain name
- is not feasible.
+NAME: authenticate_cache_garbage_interval
+TYPE: time_t
+DEFAULT: 1 hour
+LOC: Config.authenticateGCInterval
+DOC_START
+ The time period between garbage collection across the username cache.
+ This is a tradeoff between memory utilization (long intervals - say
+ 2 days) and CPU (short intervals - say 1 minute). Only change if you
+ have good reason to.
+DOC_END
- use 'ssl' to indicate connections to this peer should
- be SSL/TLS encrypted.
+NAME: authenticate_ttl
+TYPE: time_t
+DEFAULT: 1 hour
+LOC: Config.authenticateTTL
+DOC_START
+ The time a user & their credentials stay in the logged in
+ user cache since their last request. When the garbage
+ interval passes, all user credentials that have passed their
+ TTL are removed from memory.
+DOC_END
- use 'sslcert=/path/to/ssl/certificate' to specify a client
- SSL certificate to use when connecting to this peer.
+NAME: authenticate_ip_ttl
+TYPE: time_t
+LOC: Config.authenticateIpTTL
+DEFAULT: 0 seconds
+DOC_START
+ If you use proxy authentication and the 'max_user_ip' ACL,
+ this directive controls how long Squid remembers the IP
+ addresses associated with each user. Use a small value
+ (e.g., 60 seconds) if your users might change addresses
+ quickly, as is the case with dialups. You might be safe
+ using a larger value (e.g., 2 hours) in a corporate LAN
+ environment with relatively static address assignments.
+DOC_END
- use 'sslkey=/path/to/ssl/key' to specify the private SSL
- key corresponding to sslcert above. If 'sslkey' is not
- specified 'sslcert' is assumed to reference a
- combined file containing both the certificate and the key.
-
- use sslversion=1|2|3|4 to specify 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
-
- use sslcipher=... to specify the list of valid SSL ciphers
- to use when connecting to this peer.
-
- use ssloptions=... to 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.
-
- use sslcafile=... to specify a file containing
- additional CA certificates to use when verifying the
- peer certificate.
-
- use sslcapath=... to specify a directory containing
- additional CA certificates to use when verifying the
- peer certificate.
-
- use sslcrlfile=... to specify a certificate revocation
- list file to use when verifying the peer certificate.
-
- use sslflags=... to specify various flags modifying the
- SSL implementation:
- DONT_VERIFY_PEER
- Accept certificates even if they fail to
- verify.
- NO_DEFAULT_CA
- Don't use the default CA list built in
- to OpenSSL.
- DONT_VERIFY_DOMAIN
- Don't verify the peer certificate
- matches the server name
-
- use ssldomain= to specify the peer name as advertised
- in it's certificate. Used for verifying the correctness
- of the received peer certificate. If not specified the
- peer hostname will be used.
-
- use front-end-https to enable the "Front-End-Https: On"
- header needed when using Squid as a SSL frontend in front
- of Microsoft OWA. See MS KB document Q307347 for details
- on this header. If set to auto the header will
- only be added if the request is forwarded as a https://
- URL.
-DOC_END
-
-NAME: cache_peer_domain cache_host_domain
-TYPE: hostdomain
+NAME: external_acl_type
+TYPE: externalAclHelper
+LOC: Config.externalAclHelperList
DEFAULT: none
-LOC: none
DOC_START
- Use to limit the domains for which a neighbor cache will be
- queried. Usage:
+ This option defines external acl classes using a helper program
+ to look up the status
- cache_peer_domain cache-host domain [domain ...]
- cache_peer_domain cache-host !domain
+ external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
- For example, specifying
+ Options:
- cache_peer_domain parent.foo.net .edu
+ 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
+ external acl lookups of this type. (default 5)
+ 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
- has the effect such that UDP query packets are sent to
- 'bigserver' only when the requested object exists on a
- server in the .edu domain. Prefixing the domainname
- with '!' means the cache will be queried for objects
- NOT in that domain.
+ FORMAT specifications
- NOTE: * Any number of domains may be given for a cache-host,
- either on the same or separate lines.
- * When multiple domains are given for a particular
- cache-host, the first matched domain is applied.
- * Cache hosts with no domain restrictions are queried
- for all requests.
- * There are no defaults.
- * There is also a 'cache_peer_access' tag in the ACL
- section.
-DOC_END
+ %LOGIN Authenticated user login name
+ %EXT_USER Username from external acl
+ %IDENT Ident user name
+ %SRC Client IP
+ %SRCPORT Client source port
+ %URI Requested URI
+ %DST Requested host
+ %PROTO Requested protocol
+ %PORT Requested port
+ %PATH Requested URL path
+ %METHOD Request method
+ %MYADDR Squid interface address
+ %MYPORT Squid http_port number
+ %PATH Requested URL-path (including query-string if any)
+ %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
+ %{Header} HTTP request header
+ %{Hdr:member} HTTP request header list member
+ %{Hdr:;member}
+ HTTP request header list member using ; as
+ list separator. ; can be any non-alphanumeric
+ character.
-NAME: neighbor_type_domain
-TYPE: hostdomaintype
-DEFAULT: none
-LOC: none
-DOC_START
- usage: neighbor_type_domain neighbor parent|sibling domain domain ...
+ 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)
- 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.
+ 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.
-EXAMPLE:
- cache_peer parent cache.foo.org 3128 3130
- neighbor_type_domain cache.foo.org sibling .com .net
- neighbor_type_domain cache.foo.org sibling .au .de
-DOC_END
+ General result syntax:
-NAME: dead_peer_timeout
-COMMENT: (seconds)
-DEFAULT: 10 seconds
-TYPE: time_t
-LOC: Config.Timeout.deadPeer
-DOC_START
- This controls how long Squid waits to declare a peer cache
- as "dead." If there are no ICP replies received in this
- amount of time, Squid will declare the peer dead and not
- expect to receive any further ICP replies. However, it
- continues to send ICP queries, and will mark the peer as
- alive upon receipt of the first subsequent ICP reply.
+ OK/ERR keyword=value ...
- This timeout also affects when Squid expects to receive ICP
- replies from peers. If more than 'dead_peer' seconds have
- passed since the last ICP reply was received, Squid will not
- expect to receive an ICP reply on the next query. Thus, if
- your time between requests is greater than this timeout, you
- will see a lot of requests sent DIRECT to origin servers
- instead of to your parents.
-DOC_END
+ Defined keywords:
-NAME: hierarchy_stoplist
-TYPE: wordlist
-DEFAULT: none
-LOC: Config.hierarchy_stoplist
-DOC_START
- 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.
- Note: never_direct overrides this option.
-NOCOMMENT_START
-#We recommend you to use at least the following line.
-hierarchy_stoplist cgi-bin ?
-NOCOMMENT_END
-DOC_END
+ 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.
+ log= String to be logged in access.log. Available as
+ %ea in logformat specifications
-NAME: cache no_cache
-TYPE: acl_access
-DEFAULT: none
-LOC: Config.accessList.noCache
-DOC_START
- A list of ACL elements which, if matched, 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.
+ If protocol=3.0 (the default) then URL escaping is used to protect
+ each value in both requests and responses.
- You must use the word 'DENY' to indicate the ACL names which should
- NOT be cached.
+ 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.
- Default is to allow all to be cached
-NOCOMMENT_START
-#We recommend you to use the following two lines.
-acl QUERY urlpath_regex cgi-bin \?
-cache deny QUERY
-NOCOMMENT_END
+ 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.
DOC_END
COMMENT_START
- MEMORY CACHE OPTIONS
+ ACCESS CONTROLS
-----------------------------------------------------------------------------
COMMENT_END
-NAME: cache_mem
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 8 MB
-LOC: Config.memMaxSize
+NAME: acl
+TYPE: acl
+LOC: Config.aclList
+DEFAULT: none
DOC_START
- NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
- IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
- USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
- THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
+ Defining an Access List
- 'cache_mem' specifies the ideal amount of memory to be used
- for:
- * In-Transit objects
- * Hot Objects
- * Negative-Cached objects
+ acl aclname acltype string1 ...
+ acl aclname acltype "file" ...
- Data for these objects are stored in 4 KB blocks. This
- parameter specifies the ideal upper limit on the total size of
- 4 KB blocks allocated. In-Transit objects take the highest
- priority.
+ when using "file", the file should contain one item per line
- In-transit objects have priority over the others. When
- additional space is needed for incoming data, negative-cached
- and hot objects will be released. In other words, the
- negative-cached and hot objects will fill up any unused space
- not needed for in-transit objects.
+ acltype is one of the types described below
- If circumstances require, this limit will be exceeded.
- Specifically, if your incoming request rate requires more than
- 'cache_mem' of memory to hold in-transit objects, Squid will
- exceed this limit to satisfy the new requests. When the load
- decreases, blocks will be freed until the high-water mark is
- reached. Thereafter, blocks will be used to store hot
- objects.
-DOC_END
-
-NAME: maximum_object_size_in_memory
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 8 KB
-LOC: Config.Store.maxInMemObjSize
-DOC_START
- Objects greater than this size will not be attempted to kept in
- the memory cache. This should be set high enough to keep objects
- accessed frequently in memory to improve performance whilst low
- enough to keep larger objects from hoarding cache_mem.
-DOC_END
+ By default, regular expressions are CASE-SENSITIVE. To make
+ them case-insensitive, use the -i option.
-NAME: memory_replacement_policy
-TYPE: removalpolicy
-LOC: Config.memPolicy
-DEFAULT: lru
-DOC_START
- The memory replacement policy parameter determines which
- objects are purged from memory when memory space is needed.
+ acl aclname src ip-address/netmask ... (clients IP address)
+ acl aclname src addr1-addr2/netmask ... (range of addresses)
+ acl aclname dst ip-address/netmask ... (URL host's IP address)
+ acl aclname myip ip-address/netmask ... (local socket IP address)
- See cache_replacement_policy for details.
-DOC_END
+ 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.
+ #
+ # 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.
-COMMENT_START
- DISK CACHE OPTIONS
- -----------------------------------------------------------------------------
-COMMENT_END
+ acl aclname srcdomain .foo.com ... # reverse lookup, client IP
+ acl aclname dstdomain .foo.com ... # Destination server from URL
+ acl aclname srcdom_regex [-i] xxx ... # regex matching client name
+ acl aclname dstdom_regex [-i] xxx ... # regex matching server
+ # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
+ # based URL is used and no match is found. The name "none" is used
+ # if the reverse lookup fails.
-NAME: cache_dir
-TYPE: cachedir
-DEFAULT: none
-DEFAULT_IF_NONE: ufs @DEFAULT_SWAP_DIR@ 100 16 256
-LOC: Config.cacheSwap
-DOC_START
- Usage:
+ acl aclname http_status 200 301 500- 400-403 ... # status code in reply
- cache_dir Type Directory-Name Fs-specific-data [options]
+ acl aclname time [day-abbrevs] [h1:m1-h2:m2]
+ day-abbrevs:
+ S - Sunday
+ M - Monday
+ T - Tuesday
+ W - Wednesday
+ H - Thursday
+ F - Friday
+ A - Saturday
+ h1:m1 must be less than h2:m2
+ acl aclname url_regex [-i] ^http:// ... # regex matching on whole URL
+ acl aclname urlpath_regex [-i] \.gif$ ... # regex matching on URL path
+ acl aclname port 80 70 21 ...
+ acl aclname port 0-1024 ... # ranges allowed
+ acl aclname myport 3128 ... # (local socket TCP port)
+ acl aclname proto HTTP FTP ...
+ acl aclname method GET POST ...
+ acl aclname browser [-i] regexp ...
+ # pattern match on User-Agent header (see also req_header below)
+ acl aclname referer_regex [-i] regexp ...
+ # pattern match on Referer header
+ # Referer is highly unreliable, so use with care
+ acl aclname ident username ...
+ acl aclname ident_regex [-i] pattern ...
+ # string match on ident output.
+ # use REQUIRED to accept any non-null ident.
+ acl aclname src_as number ...
+ acl aclname dst_as number ...
+ # Except for access control, AS numbers can be used for
+ # routing of requests to specific caches. Here's an
+ # example for routing all requests for AS#1241 and only
+ # those to mycache.mydomain.net:
+ # acl asexample dst_as 1241
+ # cache_peer_access mycache.mydomain.net allow asexample
+ # cache_peer_access mycache_mydomain.net deny all
- You can specify multiple cache_dir lines to spread the
- cache among different disk partitions.
+ acl aclname proxy_auth [-i] username ...
+ acl aclname proxy_auth_regex [-i] pattern ...
+ # list of valid usernames
+ # use REQUIRED to accept any valid username.
+ #
+ # NOTE: when a Proxy-Authentication header is sent but it is not
+ # needed during ACL checking the username is NOT logged
+ # in access.log.
+ #
+ # NOTE: proxy_auth requires a EXTERNAL authentication program
+ # to check username/password combinations (see
+ # auth_param directive).
+ #
+ # NOTE: proxy_auth can't be used in a transparent proxy as
+ # the browser needs to be configured for using a proxy in order
+ # to respond to proxy authentication.
- Type specifies the kind of storage system to use. Only "ufs"
- is built by default. To enable any of the other storage systems
- see the --enable-storeio configure option.
+ acl aclname snmp_community string ...
+ # A community string to limit access to your SNMP Agent
+ # Example:
+ #
+ # acl snmppublic snmp_community public
- 'Directory' is a top-level directory where cache swap
- files will be stored. If you want to use an entire disk
- for caching, this can be the mount-point directory.
- The directory must exist and be writable by the Squid
- process. Squid will NOT create this directory for you.
+ acl aclname maxconn number
+ # This will be matched when the client's IP address has
+ # more than <number> HTTP connections established.
- The ufs store type:
+ acl aclname max_user_ip [-s] number
+ # This will be matched when the user attempts to log in from more
+ # than <number> different ip addresses. The authenticate_ip_ttl
+ # parameter controls the timeout on the ip entries.
+ # If -s is specified the limit is strict, denying browsing
+ # from any further IP addresses until the ttl has expired. Without
+ # -s Squid will just annoy the user by "randomly" denying requests.
+ # (the counter is reset each time the limit is reached and a
+ # request is denied)
+ # NOTE: in acceleration mode or where there is mesh of child proxies,
+ # clients may appear to come from multiple addresses if they are
+ # going through proxy farms, so a limit of 1 may cause user problems.
- "ufs" is the old well-known Squid storage format that has always
- been there.
+ acl aclname req_mime_type mime-type1 ...
+ # regex match against the mime type of the request generated
+ # by the client. Can be used to detect file upload or some
+ # types HTTP tunneling requests.
+ # NOTE: This does NOT match the reply. You cannot use this
+ # to match the returned file type.
- cache_dir ufs Directory-Name Mbytes L1 L2 [options]
+ acl aclname req_header header-name [-i] any\.regex\.here
+ # regex match against any of the known request headers. May be
+ # thought of as a superset of "browser", "referer" and "mime-type"
+ # ACLs.
- 'Mbytes' is the amount of disk space (MB) to use under this
- directory. The default is 100 MB. Change this to suit your
- configuration. Do NOT put the size of your disk drive here.
- Instead, if you want Squid to use the entire disk drive,
- subtract 20% and use that value.
+ acl aclname rep_mime_type mime-type1 ...
+ # regex match against the mime type of the reply received by
+ # squid. Can be used to detect file download or some
+ # types HTTP tunneling requests.
+ # 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.
- 'Level-1' is the number of first-level subdirectories which
- will be created under the 'Directory'. The default is 16.
+ acl aclname rep_header header-name [-i] any\.regex\.here
+ # regex match against any of the known reply headers. May be
+ # thought of as a superset of "browser", "referer" and "mime-type"
+ # ACLs.
- 'Level-2' is the number of second-level subdirectories which
- will be created under each first-level directory. The default
- is 256.
+ acl acl_name external class_name [arguments...]
+ # external ACL lookup via a helper class defined by the
+ # external_acl_type directive.
- The aufs store type:
+ acl aclname user_cert attribute values...
+ # match against attributes in a user SSL certificate
+ # attribute is one of DN/C/O/CN/L/ST
- "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.
+ 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
- cache_dir aufs Directory-Name Mbytes L1 L2 [options]
+ acl aclname ext_user username ...
+ acl aclname ext_user_regex [-i] pattern ...
+ # string match on username returned by external acl helper
+ # use REQUIRED to accept any non-null user name.
- see argument descriptions under ufs above
+Examples:
+acl macaddress arp 09:00:2b:23:45:67
+acl myexample dst_as 1241
+acl password proxy_auth REQUIRED
+acl fileupload req_mime_type -i ^multipart/form-data$
+acl javascript rep_mime_type -i ^application/x-javascript$
- The diskd store type:
+NOCOMMENT_START
+#Recommended minimum configuration:
+acl all src 0.0.0.0/0.0.0.0
+acl manager proto cache_object
+acl localhost src 127.0.0.1/255.255.255.255
+acl to_localhost dst 127.0.0.0/8
+acl SSL_ports port 443
+acl Safe_ports port 80 # http
+acl Safe_ports port 21 # ftp
+acl Safe_ports port 443 # https
+acl Safe_ports port 70 # gopher
+acl Safe_ports port 210 # wais
+acl Safe_ports port 1025-65535 # unregistered ports
+acl Safe_ports port 280 # http-mgmt
+acl Safe_ports port 488 # gss-http
+acl Safe_ports port 591 # filemaker
+acl Safe_ports port 777 # multiling http
+acl CONNECT method CONNECT
+NOCOMMENT_END
+DOC_END
- "diskd" uses the same storage format as "ufs", utilizing a
- separate process to avoid blocking the main Squid process on
- disk-I/O.
+NAME: http_access
+TYPE: acl_access
+LOC: Config.accessList.http
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access based on defined access lists
- cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
+ Access to the HTTP port:
+ http_access allow|deny [!]aclname ...
- see argument descriptions under ufs above
+ NOTE on default values:
- Q1 specifies the number of unacknowledged I/O requests when Squid
- stops opening new files. If this many messages are in the queues,
- Squid won't open new files. Default is 64
+ If there are no "access" lines present, the default is to deny
+ the request.
- Q2 specifies the number of unacknowledged messages when Squid
- starts blocking. If this many messages are in the queues,
- Squid blocks until it receives some replies. Default is 72
+ If none of the "access" lines cause a match, the default is the
+ opposite of the last line in the list. If the last line was
+ deny, the default is allow. Conversely, if the last line
+ is allow, the default will be deny. For these reasons, it is a
+ good idea to have an "deny all" or "allow all" entry at the end
+ of your access lists to avoid potential confusion.
- When Q1 < Q2 (the default), the cache directory is optimized
- for lower response time at the expense of a decrease in hit
- ratio. If Q1 > Q2, the cache directory is optimized for
- higher hit ratio at the expense of an increase in response
- time.
-
- The coss store type:
-
- 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.
+NOCOMMENT_START
+#Recommended minimum configuration:
+#
+# Only allow cachemgr access from localhost
+http_access allow manager localhost
+http_access deny manager
+# Deny requests to unknown ports
+http_access deny !Safe_ports
+# Deny CONNECT to other than SSL ports
+http_access deny CONNECT !SSL_ports
+#
+# 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
+#http_access deny to_localhost
+#
+# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
- The null store type:
+# Example rule allowing access from your local networks. Adapt
+# to list your (internal) IP networks from where browsing should
+# be allowed
+#acl our_networks src 192.168.1.0/24 192.168.2.0/24
+#http_access allow our_networks
- no options are allowed or required
+# And finally deny all other access to this proxy
+http_access deny all
+NOCOMMENT_END
+DOC_END
- Common options:
+NAME: http_reply_access
+TYPE: acl_access
+LOC: Config.accessList.reply
+DEFAULT: none
+DOC_START
+ Allow replies to client requests. This is complementary to http_access.
- no-store, no new objects should be stored to this cache_dir
+ http_reply_access allow|deny [!] aclname ...
- max-size=n, refers to the max object size this storedir supports.
- It is used to initially choose the storedir to dump 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.
+ NOTE: if there are no access lines present, the default is to allow
+ all replies
- 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.
+ 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
+ with an "allow all" or "deny all" entry.
DOC_END
-NAME: store_dir_select_algorithm
-TYPE: string
-LOC: Config.store_dir_select_algorithm
-DEFAULT: least-load
+NAME: icp_access
+TYPE: acl_access
+LOC: Config.accessList.icp
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
DOC_START
- Set this to 'round-robin' as an alternative.
-DOC_END
+ Allowing or Denying access to the ICP port based on defined
+ access lists
-NAME: max_open_disk_fds
-TYPE: int
-LOC: Config.max_open_disk_fds
-DEFAULT: 0
-DOC_START
- To avoid having disk as the I/O bottleneck Squid can optionally
- bypass the on-disk cache if more than this amount of disk file
- descriptors are open.
+ icp_access allow|deny [!]aclname ...
- A value of 0 indicates no limit.
+ See http_access for details
+
+NOCOMMENT_START
+#Allow ICP queries from everyone
+icp_access allow all
+NOCOMMENT_END
DOC_END
-NAME: cache_replacement_policy
-TYPE: removalpolicy
-LOC: Config.replPolicy
-DEFAULT: lru
+NAME: htcp_access
+IFDEF: USE_HTCP
+TYPE: acl_access
+LOC: Config.accessList.htcp
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
DOC_START
- The cache replacement policy parameter determines which
- objects are evicted (replaced) when disk space is needed.
-
- lru : Squid's original list based LRU policy
- heap GDSF : Greedy-Dual Size Frequency
- heap LFUDA: Least Frequently Used with Dynamic Aging
- heap LRU : LRU policy implemented using a heap
+ Allowing or Denying access to the HTCP port based on defined
+ access lists
- Applies to any cache_dir lines listed below this.
+ htcp_access allow|deny [!]aclname ...
- The LRU policies keeps recently referenced objects.
+ See http_access for details
- The heap GDSF policy optimizes object hit rate by keeping smaller
- popular objects in cache so it has a better chance of getting a
- hit. It achieves a lower byte hit rate than LFUDA though since
- it evicts larger (possibly popular) objects.
+#Allow HTCP queries from everyone
+htcp_access allow all
+DOC_END
- The heap LFUDA policy keeps popular objects in cache regardless of
- their size and thus optimizes byte hit rate at the expense of
- hit rate since one large, popular object will prevent many
- smaller, slightly less popular objects from being cached.
+NAME: htcp_clr_access
+IFDEF: USE_HTCP
+TYPE: acl_access
+LOC: Config.accessList.htcp_clr
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access to purge content using HTCP based
+ on defined access lists
- Both policies utilize a dynamic aging mechanism that prevents
- cache pollution that can otherwise occur with frequency-based
- replacement policies.
+ htcp_clr_access allow|deny [!]aclname ...
- NOTE: if using the LFUDA replacement policy you should increase
- the value of maximum_object_size above its default of 4096 KB to
- to maximize the potential byte hit rate improvement of LFUDA.
+ See http_access for details
- For more information about the GDSF and LFUDA cache replacement
- policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
- and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
+#Allow HTCP CLR requests from trusted peers
+acl htcp_clr_peer src 172.16.1.2
+htcp_clr_access allow htcp_clr_peer
DOC_END
-NAME: minimum_object_size
-COMMENT: (bytes)
-TYPE: b_int64_t
-DEFAULT: 0 KB
-LOC: Config.Store.minObjectSize
+NAME: miss_access
+TYPE: acl_access
+LOC: Config.accessList.miss
+DEFAULT: none
DOC_START
- Objects smaller than this size will NOT be saved on disk. The
- value is specified in kilobytes, and the default is 0 KB, which
- means there is no minimum.
-DOC_END
+ Use to force your neighbors to use you as a sibling instead of
+ a parent. For example:
-NAME: maximum_object_size
-COMMENT: (bytes)
-TYPE: b_int64_t
-DEFAULT: 4096 KB
-LOC: Config.Store.maxObjectSize
-DOC_START
- Objects larger than this size will NOT be saved on disk. The
- value is specified in kilobytes, and the default is 4MB. If
- you wish to get a high BYTES hit ratio, you should probably
- 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.
+ acl localclients src 172.16.0.0/16
+ miss_access allow localclients
+ miss_access deny !localclients
- 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.
-DOC_END
+ This means only your local clients are allowed to fetch
+ MISSES and all other clients can only fetch HITS.
-NAME: cache_swap_low
-COMMENT: (percent, 0-100)
-TYPE: int
-DEFAULT: 90
-LOC: Config.Swap.lowWaterMark
-DOC_NONE
+ By default, allow all clients who passed the http_access rules
+ to fetch MISSES from us.
-NAME: cache_swap_high
-COMMENT: (percent, 0-100)
-TYPE: int
-DEFAULT: 95
-LOC: Config.Swap.highWaterMark
+NOCOMMENT_START
+#Default setting:
+# miss_access allow all
+NOCOMMENT_END
+DOC_END
+
+NAME: ident_lookup_access
+TYPE: acl_access
+IFDEF: USE_IDENT
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+LOC: Config.accessList.identLookup
DOC_START
+ A list of ACL elements which, if matched, cause an ident
+ (RFC 931) lookup to be performed for this request. For
+ example, you might choose to always perform ident lookups
+ for your main multi-user Unix boxes, but not for your Macs
+ and PCs. By default, ident lookups are not performed for
+ any requests.
- 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.
+ To enable ident lookups for specific client addresses, you
+ can follow this example:
- 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.
-DOC_END
+ acl ident_aware_hosts src 198.168.1.0/255.255.255.0
+ ident_lookup_access allow ident_aware_hosts
+ ident_lookup_access deny all
-COMMENT_START
- LOGFILE OPTIONS
- -----------------------------------------------------------------------------
-COMMENT_END
+ Only src type ACL checks are fully supported. A src_domain
+ ACL might work at times, but it will not always provide
+ the correct result.
+DOC_END
-NAME: logformat
-TYPE: logformat
-LOC: Config.Log.logformats
+NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
+TYPE: acl_tos
DEFAULT: none
+LOC: Config.accessList.outgoing_tos
DOC_START
- Usage:
+ Allows you to select a TOS/Diffserv value to mark outgoing
+ connections with, based on the username or source address
+ making the request.
- logformat <name> <format specification>
+ tcp_outgoing_tos ds-field [!]aclname ...
- Defines an access log format.
+ Example where normal_service_net uses the TOS value 0x00
+ and normal_service_net uses 0x20
- The <format specification> is a string with embedded % format codes
-
- % format codes all follow the same basic structure where all but
- the formatcode is optional. Output strings are automatically escaped
- as required according to their context and the output format
- modifiers are usually not needed, but can be specified if an explicit
- output format is desired.
-
- % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
-
- " output in quoted string format
- [ output in squid text log format as used by log_mime_hdrs
- # output in URL quoted format
- ' output as-is
+ acl normal_service_net src 10.0.0.0/255.255.255.0
+ acl good_service_net src 10.0.1.0/255.255.255.0
+ tcp_outgoing_tos 0x00 normal_service_net 0x00
+ tcp_outgoing_tos 0x20 good_service_net
- - left aligned
- width field width. If starting with 0 the
- output is zero padded
- {arg} argument such as header name etc
+ TOS/DSCP values really only have local significance - so you should
+ know what you're specifying. For more information, see RFC2474 and
+ RFC3260.
- Format codes:
+ 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 values 0 - 63 is usable as the two highest bits
+ have been redefined for use by ECN (RFC3168).
- >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)
- ts Seconds since epoch
- tu subsecond time (milliseconds)
- tl Local time. Optional strftime format argument
- default %d/%b/%Y:%H:%M:%S %z
- tg GMT time. Optional strftime format argument
- default %d/%b/%Y:%H:%M:%S %z
- tr Response time (milliseconds)
- >h Request header. Optional header name argument
- on the format header[:[separator]element]
- <h Reply header. Optional header name argument
- as for >h
- un User name
- ul User name from authentication
- ui User name from ident
- us User name from SSL
- ue User name from external acl helper
- Hs HTTP status code
- Ss Squid request status (TCP_MISS etc)
- Sh Squid hierarchy status (DEFAULT_PARENT etc)
- mt MIME content type
- rm Request method (GET/POST etc)
- ru Request URL
- rp Request URL-Path excluding hostname
- rv Request protocol version
- et Tag returned by external acl
- ea Log string returned by external acl
- <st Reply size including HTTP headers
- <sH Reply high offset sent
- <sS Upstream object size
- % a literal % character
+ Processing proceeds in the order specified, and stops at first fully
+ matching line.
-logformat squid %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
-logformat squidmime %ts.%03tu %6tr %>a %Ss/%03Hs %<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
+ 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_persisten_connections
+ to off when using this directive in such configurations.
DOC_END
-NAME: access_log cache_access_log
-TYPE: access_log
-LOC: Config.Log.accesslogs
+NAME: clientside_tos
+TYPE: acl_tos
DEFAULT: none
+LOC: Config.accessList.clientside_tos
DOC_START
- 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 ...]]
+ Allows you to select a TOS/Diffserv value to mark client-side
+ connections with, based on the username or source address
+ making the request.
+DOC_END
- 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).
- If no acl is specified, all requests will be logged to this file.
+NAME: tcp_outgoing_address
+TYPE: acl_address
+DEFAULT: none
+LOC: Config.accessList.outgoing_address
+DOC_START
+ Allows you to map requests to different outgoing IP addresses
+ based on the username or source address of the user making
+ the request.
- To disable logging of a request use the filepath "none", in which case
- a logformat name should not be specified.
+ tcp_outgoing_address ipaddr [[!]aclname] ...
- To log the request via syslog specify a filepath of "syslog":
+ 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.
- access_log syslog[:facility.priority] [format [acl1 [acl2 ....]]]
- where facility could be any of:
- authpriv, daemon, local0 .. local7 or user.
+ acl normal_service_net src 10.0.0.0/255.255.255.0
+ acl good_service_net src 10.0.1.0/255.255.255.0
+ tcp_outgoing_address 10.0.0.1 normal_service_net
+ tcp_outgoing_address 10.0.0.2 good_service_net
+ tcp_outgoing_address 10.0.0.3
- And priority could be any of:
- err, warning, notice, info, debug.
-NOCOMMENT_START
-access_log @DEFAULT_ACCESS_LOG@ squid
-NOCOMMENT_END
-DOC_END
+ Processing proceeds in the order specified, and stops at first fully
+ matching line.
-NAME: cache_log
-TYPE: string
-DEFAULT: @DEFAULT_CACHE_LOG@
-LOC: Config.Log.log
-DOC_START
- Cache logging file. This is where general information about
- your cache's behavior goes. You can increase the amount of data
- logged to this file with the "debug_options" tag below.
+ 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.
DOC_END
-NAME: cache_store_log
-TYPE: string
-DEFAULT: @DEFAULT_STORE_LOG@
-LOC: Config.Log.store
+NAME: reply_header_max_size
+COMMENT: (KB)
+TYPE: b_size_t
+DEFAULT: 20 KB
+LOC: Config.maxReplyHeaderSize
DOC_START
- Logs the activities of the storage manager. Shows which
- objects are ejected from the cache, and which objects are
- saved and for how long. To disable, enter "none". There are
- not really utilities to analyze this data, so you can safely
- disable it.
+ This specifies the maximum size for HTTP headers in a reply.
+ Reply headers are usually relatively small (about 512 bytes).
+ Placing a limit on the reply header size will catch certain
+ bugs (for example with persistent connections) and possibly
+ buffer-overflow or denial-of-service attacks.
DOC_END
-NAME: cache_swap_state cache_swap_log
-TYPE: string
-LOC: Config.Log.swap
+NAME: reply_body_max_size
+COMMENT: size [acl acl...]
+TYPE: acl_b_size_t
DEFAULT: none
+LOC: Config.ReplyBodySize
DOC_START
- Location for the cache "swap.state" file. This index file holds
- the metadata of objects saved on disk. It is used to rebuild
- the cache during startup. Normally this file resides in each
- 'cache_dir' directory, but you may specify an alternate
- pathname here. Note you must give a full filename, not just
- a directory. Since this is the index for the whole object
- list you CANNOT periodically rotate it!
+ This option specifies the maximum size of a reply body. It can be
+ used to prevent users from downloading very large files, such as
+ MP3's and movies. When the reply headers are received, the
+ reply_body_max_size lines are processed, and the first line where
+ all (if any) listed ACLs are true is used as the maximum body size
+ for this reply.
- If %s can be used in the file name it will be replaced with a
- a representation of the cache_dir name where each / is replaced
- with '.'. This is needed to allow adding/removing cache_dir
- lines when cache_swap_log is being used.
+ This size is checked twice. First when we get the reply headers,
+ we check the content-length value. If the content length value exists
+ and is larger than the allowed size, the request is denied and the
+ user receives an error message that says "the request or reply
+ is too large." If there is no content-length, and the reply
+ size exceeds this limit, the client's connection is just closed
+ and they will receive a partial reply.
- If have more than one 'cache_dir', and %s is not used in the name
- these swap logs will have names such as:
+ WARNING: downstream caches probably can not detect a partial reply
+ if there is no content-length header, so they will cache
+ partial responses and give them out as hits. You should NOT
+ use this option if you have downstream caches.
- cache_swap_log.00
- cache_swap_log.01
- cache_swap_log.02
+ WARNING: A maximum size smaller than the size of squid's error messages
+ will cause an infinite loop and crash squid. Ensure that the smallest
+ non-zero value you use is greater that the maximum header size plus
+ the size of your largest error page.
- The numbered extension (which is added automatically)
- corresponds to the order of the 'cache_dir' lines in this
- configuration file. If you change the order of the 'cache_dir'
- lines in this file, these index files will NOT correspond to
- the correct 'cache_dir' entry (unless you manually rename
- them). We recommend you do NOT use this option. It is
- better to keep these index files in each 'cache_dir' directory.
+ If you set this parameter none (the default), there will be
+ no limit imposed.
DOC_END
-NAME: logfile_rotate
-TYPE: int
-DEFAULT: 10
-LOC: Config.Log.rotateNumber
+NAME: log_access
+TYPE: acl_access
+LOC: Config.accessList.log
+DEFAULT: none
+COMMENT: allow|deny acl acl...
DOC_START
- Specifies the number of logfile rotations to make when you
- type 'squid -k rotate'. The default is 10, which will rotate
- with extensions 0 through 9. Setting logfile_rotate to 0 will
- disable the file name rotation, but the logfiles are still closed
- and re-opened. This will enable you to rename the logfiles
- yourself just before sending the rotate signal.
-
- Note, the 'squid -k rotate' command normally sends a USR1
- signal to the running squid process. In certain situations
- (e.g. on Linux with Async I/O), USR1 is used for other
- purposes, so -k rotate uses another signal. It is best to get
- in the habit of using 'squid -k rotate' instead of 'kill -USR1
- <pid>'.
+ 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.
DOC_END
-NAME: emulate_httpd_log
-COMMENT: on|off
+COMMENT_START
+ SSL OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: ssl_unclean_shutdown
+IFDEF: USE_SSL
TYPE: onoff
DEFAULT: off
-LOC: Config.onoff.common_log
+LOC: Config.SSL.unclean_shutdown
DOC_START
- 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.
+ Some browsers (especially MSIE) bugs out on SSL shutdown
+ messages.
DOC_END
-NAME: log_ip_on_direct
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.log_ip_on_direct
-DOC_START
- 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.
-DOC_END
-
-NAME: mime_table
+NAME: ssl_engine
+IFDEF: USE_SSL
TYPE: string
-DEFAULT: @DEFAULT_MIME_TABLE@
-LOC: Config.mimeTablePathname
-DOC_START
- Pathname to Squid's MIME table. You shouldn't need to change
- this, but the default file contains examples and formatting
- information if you do.
-DOC_END
-
-NAME: log_mime_hdrs
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.log_mime_hdrs
-DEFAULT: off
+LOC: Config.SSL.ssl_engine
+DEFAULT: none
DOC_START
- The Cache can record both the request and the response MIME
- headers for each HTTP transaction. The headers are encoded
- safely and will appear as two bracketed fields at the end of
- the access log (for either the native or httpd-emulated log
- formats). To enable this logging set log_mime_hdrs to 'on'.
+ The OpenSSL engine to use. You will need to set this if you
+ would like to use hardware SSL acceleration for example.
DOC_END
-NAME: useragent_log
-TYPE: string
-LOC: Config.Log.useragent
+NAME: sslproxy_client_certificate
+IFDEF: USE_SSL
DEFAULT: none
-IFDEF: USE_USERAGENT_LOG
+LOC: Config.ssl_client.cert
+TYPE: string
DOC_START
- Squid will write the User-Agent field from HTTP requests
- to the filename specified here. By default useragent_log
- is disabled.
+ Client SSL Certificate to use when proxying https:// URLs
DOC_END
-NAME: referer_log referrer_log
-TYPE: string
-LOC: Config.Log.referer
+NAME: sslproxy_client_key
+IFDEF: USE_SSL
DEFAULT: none
-IFDEF: USE_REFERER_LOG
+LOC: Config.ssl_client.key
+TYPE: string
DOC_START
- 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.
+ Client SSL Key to use when proxying https:// URLs
DOC_END
-NAME: pid_filename
-TYPE: string
-DEFAULT: @DEFAULT_PID_FILE@
-LOC: Config.pidFilename
+NAME: sslproxy_version
+IFDEF: USE_SSL
+DEFAULT: 1
+LOC: Config.ssl_client.version
+TYPE: int
DOC_START
- A filename to write the process-id to. To disable, enter "none".
+ SSL version level to use when proxying https:// URLs
DOC_END
-NAME: debug_options
-TYPE: debug
-DEFAULT: ALL,1
-LOC: Config.debugOptions
+NAME: sslproxy_options
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.options
+TYPE: string
DOC_START
- Logging options are set as section,level where each source file
- is assigned a unique section. Lower levels result in less
- output, Full debugging (level 9) can result in a very large
- log file, so be careful. The magic word "ALL" sets debugging
- levels for all sections. We recommend normally running with
- "ALL,1".
+ SSL engine options to use when proxying https:// URLs
DOC_END
-NAME: log_fqdn
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.log_fqdn
+NAME: sslproxy_cipher
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.cipher
+TYPE: string
DOC_START
- 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.
+ SSL cipher list to use when proxying https:// URLs
DOC_END
-NAME: client_netmask
-TYPE: address
-LOC: Config.Addrs.client_netmask
-DEFAULT: 255.255.255.255
+NAME: sslproxy_cafile
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.cafile
+TYPE: string
DOC_START
- 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'.
+ file containing CA certificates to use when verifying server
+ certificates while proxying https:// URLs
DOC_END
-NAME: forward_log
-IFDEF: WIP_FWD_LOG
-TYPE: string
+NAME: sslproxy_capath
+IFDEF: USE_SSL
DEFAULT: none
-LOC: Config.Log.forward
+LOC: Config.ssl_client.capath
+TYPE: string
DOC_START
- Logs the server-side requests.
-
- This is currently work in progress.
+ directory containing CA certificates to use when verifying
+ server certificates while proxying https:// URLs
DOC_END
-NAME: strip_query_terms
-TYPE: onoff
-LOC: Config.onoff.strip_query_terms
-DEFAULT: on
+NAME: sslproxy_flags
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.flags
+TYPE: string
DOC_START
- By default, Squid strips query terms from requested URLs before
- logging. This protects your user's privacy.
+ Various flags modifying the use of SSL while proxying https:// URLs:
+ DONT_VERIFY_PEER Accept certificates even if they fail to
+ verify.
+ NO_DEFAULT_CA Don't use the default CA list built in
+ to OpenSSL.
DOC_END
-NAME: buffered_logs
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.buffered_logs
+NAME: sslpassword_program
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.Program.ssl_password
+TYPE: string
DOC_START
- cache.log log file is written with stdio functions, and as such
- it can be buffered or unbuffered. By default it will be unbuffered.
- Buffering it can speed up the writing slightly (though you are
- unlikely to need to worry unless you run with tons of debugging
- enabled in which case performance will suffer badly anyway..).
+ Specify a program used for entering SSL key passphrases
+ when using encrypted SSL certificate keys. If not specified
+ keys must either be unencrypted, or Squid started with the -N
+ option to allow it to query interactively for the passphrase.
DOC_END
COMMENT_START
- OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
+ OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
-----------------------------------------------------------------------------
COMMENT_END
-NAME: ftp_user
-TYPE: string
-DEFAULT: Squid@
-LOC: Config.Ftp.anon_user
+NAME: cache_peer
+TYPE: peer
+DEFAULT: none
+LOC: Config.peers
DOC_START
- If you want the anonymous login password to be more informative
- (and enable the use of picky ftp servers), set this to something
- 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
- (for example perl.com).
-DOC_END
+ To specify other caches in a hierarchy, use the format:
-NAME: ftp_list_width
-TYPE: size_t
-DEFAULT: 32
-LOC: Config.Ftp.list_width
-DOC_START
- 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.
-DOC_END
+ cache_peer hostname type http-port icp-port [options]
-NAME: ftp_passive
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.passive
-DOC_START
- If your firewall does not allow Squid to use passive
- connections, turn off this option.
-DOC_END
+ For example,
-NAME: ftp_sanitycheck
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.sanitycheck
-DOC_START
- For security and data integrity reasons Squid by default performs
- sanity checks of the addresses of FTP data connections ensure the
- data connection is to the requested server. If you need to allow
- FTP connections to servers using another IP address for the data
- connection turn this off.
-DOC_END
+ # proxy icp
+ # hostname type port port options
+ # -------------------- -------- ----- ----- -----------
+ cache_peer parent.foo.net parent 3128 3130 proxy-only default
+ cache_peer sib1.foo.net sibling 3128 3130 proxy-only
+ cache_peer sib2.foo.net sibling 3128 3130 proxy-only
-NAME: ftp_telnet_protocol
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.telnet
-DOC_START
- The FTP protocol is officially defined to use the telnet protocol
- as transport channel for the control connection. However, many
- implementations are broken and does not respect this aspect of
- the FTP protocol.
+ type: either 'parent', 'sibling', or 'multicast'.
- If you have trouble accessing files with ASCII code 255 in the
- path or similar problems involving this ASCII code you can
- try setting this directive to off. If that helps, report to the
- operator of the FTP server in question that their FTP server
- is broken and does not follow the FTP standard.
-DOC_END
+ proxy-port: The port number where the cache listens for proxy
+ requests.
-NAME: diskd_program
-TYPE: string
-DEFAULT: @DEFAULT_DISKD@
-LOC: Config.Program.diskd
-DOC_START
- Specify the location of the diskd executable.
- Note this is only useful if you have compiled in
- diskd as one of the store io modules.
-DOC_END
+ icp-port: Used for querying neighbor caches about
+ objects. To have a non-ICP neighbor
+ specify '7' for the ICP port and make sure the
+ neighbor machine has the UDP echo port
+ enabled in its /etc/inetd.conf file.
+ NOTE: Also requires icp_port option enabled to send/receive
+ requests via this method.
-NAME: unlinkd_program
-IFDEF: USE_UNLINKD
-TYPE: string
-DEFAULT: @DEFAULT_UNLINKD@
-LOC: Config.Program.unlinkd
-DOC_START
- Specify the location of the executable for file deletion process.
-DOC_END
+ options: proxy-only
+ weight=n
+ basetime=n
+ ttl=n
+ no-query
+ background-ping
+ default
+ round-robin
+ weighted-round-robin
+ carp
+ multicast-responder
+ closest-only
+ no-digest
+ no-netdb-exchange
+ no-delay
+ login=user:password | PASS | *:password
+ connect-timeout=nn
+ digest-url=url
+ allow-miss
+ max-conn=n
+ htcp
+ htcp-oldsquid
+ originserver
+ name=xxx
+ forceddomain=name
+ ssl
+ sslcert=/path/to/ssl/certificate
+ sslkey=/path/to/ssl/key
+ sslversion=1|2|3|4
+ sslcipher=...
+ ssloptions=...
+ front-end-https[=on|auto]
-NAME: pinger_program
-TYPE: string
-DEFAULT: @DEFAULT_PINGER@
-LOC: Config.Program.pinger
-IFDEF: USE_ICMP
-DOC_START
- Specify the location of the executable for the pinger process.
-DOC_END
+ use 'proxy-only' to specify objects fetched
+ from this cache should not be saved locally.
-NAME: url_rewrite_program redirect_program
-TYPE: wordlist
-LOC: Config.Program.redirect
-DEFAULT: none
-DOC_START
- Specify the location of the executable for the URL rewriter.
- Since they can perform almost any function there isn't one included.
+ use 'weight=n' to affect the selection of a peer
+ during any weighted peer-selection mechanisms.
+ The weight must be an integer; default is 1,
+ larger weights are favored more.
+ This option does not affect parent selection if a peering
+ protocol is not in use.
- For each requested URL rewriter will receive on line with the format
+ use 'basetime=n' to specify a base amount to
+ be subtracted from round trip times of parents.
+ It is subtracted before division by weight in calculating
+ which parent to fectch from. If the rtt is less than the
+ base time the rtt is set to a minimal value.
- URL <SP> client_ip "/" fqdn <SP> user <SP> method <NL>
+ use 'ttl=n' to specify a IP multicast TTL to use
+ when sending an ICP queries to this address.
+ Only useful when sending to a multicast group.
+ Because we don't accept ICP replies from random
+ hosts, you must configure other group members as
+ peers with the 'multicast-responder' option below.
- 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).
+ use 'no-query' to NOT send ICP queries to this
+ neighbor.
- 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).
+ use 'background-ping' to only send ICP queries to this
+ neighbor infrequently. This is used to keep the neighbor
+ round trip time updated and is usually used in
+ conjunction with weighted-round-robin.
- By default, a URL rewriter is not used.
-DOC_END
+ use 'default' if this is a parent cache which can
+ be used as a "last-resort" if a peer cannot be located
+ by any of the peer-selection mechanisms.
+ If specified more than once, only the first is used.
-NAME: url_rewrite_children redirect_children
-TYPE: int
-DEFAULT: 5
-LOC: Config.redirectChildren
-DOC_START
- 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.
-DOC_END
+ use 'round-robin' to define a set of parents which
+ should be used in a round-robin fashion in the
+ absence of any ICP queries.
-NAME: url_rewrite_concurrency redirect_concurrency
-TYPE: int
-DEFAULT: 0
-LOC: Config.redirectConcurrency
-DOC_START
- 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.
-DOC_END
+ use 'weighted-round-robin' to define a set of parents
+ which should be used in a round-robin fashion with the
+ frequency of each parent being based on the round trip
+ time. Closer parents are used more often.
+ Usually used for background-ping parents.
-NAME: url_rewrite_host_header redirect_rewrites_host_header
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.redir_rewrites_host
-DOC_START
- 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.
+ use 'carp' to define a set of parents which should
+ be used as a CARP array. The requests will be
+ distributed among the parents based on the CARP load
+ balancing hash function based on their weigth.
- WARNING: Entries are cached on the result of the URL rewriting
- process, so be careful if you have domain-virtual hosts.
-DOC_END
+ 'multicast-responder' indicates the named peer
+ is a member of a multicast group. ICP queries will
+ not be sent directly to the peer, but ICP replies
+ will be accepted from it.
-NAME: url_rewrite_access redirector_access
-TYPE: acl_access
-DEFAULT: none
-LOC: Config.accessList.redirector
-DOC_START
- If defined, this access list specifies which requests are
- sent to the redirector processes. By default all requests
- are sent.
-DOC_END
+ 'closest-only' indicates that, for ICP_OP_MISS
+ replies, we'll only forward CLOSEST_PARENT_MISSes
+ and never FIRST_PARENT_MISSes.
-NAME: auth_param
-TYPE: authparam
-LOC: Config.authConfiguration
-DEFAULT: none
-DOC_START
- This is used to define parameters for the various authentication
- schemes supported by Squid.
+ use 'no-digest' to NOT request cache digests from
+ this neighbor.
- format: auth_param scheme parameter [setting]
+ 'no-netdb-exchange' disables requesting ICMP
+ RTT database (NetDB) from the neighbor.
- The order in which authentication schemes are presented to the client is
- dependent on the order the scheme first appears in config file. IE
- has a bug (it's not RFC 2617 compliant) in that it will use the basic
- scheme if basic is the first entry presented, even if more secure
- schemes are presented. For now use the order in the recommended
- settings section below. If other browsers have difficulties (don't
- recognize the schemes offered even if you are using basic) either
- put basic first, or disable the other schemes (by commenting out their
- program entry).
+ use 'no-delay' to prevent access to this neighbor
+ from influencing the delay pools.
- Once an authentication scheme is fully configured, it can only be
- shutdown by shutting squid down and restarting. Changes can be made on
- the fly and activated with a reconfigure. I.E. You can change to a
- different helper, but not unconfigure the helper completely.
+ use 'login=user:password' if this is a personal/workgroup
+ proxy and your parent requires proxy authentication.
+ Note: The string can include URL escapes (i.e. %20 for
+ spaces). This also means % must be written as %%.
- Please note that while this directive defines how Squid processes
- authentication it does not automatically activate authentication.
- To use authentication you must in addition make use of ACLs based
- on login name in http_access (proxy_auth, proxy_auth_regex or
- external with %LOGIN used in the format tag). The browser will be
- challenged for authentication on the first such acl encountered
- in http_access processing and will also be re-challenged for new
- login credentials if the request is being denied by a proxy_auth
- type acl.
+ use 'login=PASS' if users must authenticate against
+ the upstream proxy or in the case of a reverse proxy
+ configuration, the origin web server. This will pass
+ the users credentials as they are to the peer.
+ This only works for the Basic HTTP authentication scheme.
+ Note: To combine this with proxy_auth both proxies must
+ share the same user database as HTTP only allows for
+ a single login (one for proxy, one for origin server).
+ Also be warned this will expose your users proxy
+ password to the peer. USE WITH CAUTION
- WARNING: authentication can't be used in a transparently intercepting
- proxy as the client then thinks it is talking to an origin server and
- not the proxy. This is a limitation of bending the TCP/IP protocol to
- transparently intercepting port 80, not a limitation in Squid.
+ use 'login=*:password' to pass the username to the
+ upstream cache, but with a fixed password. This is meant
+ to be used when the peer is in another administrative
+ domain, but it is still needed to identify each user.
+ The star can optionally be followed by some extra
+ information which is added to the username. This can
+ be used to identify this proxy to the peer, similar to
+ the login=username:password option above.
- === Parameters for the basic scheme follow. ===
+ use 'connect-timeout=nn' to specify a peer
+ specific connect timeout (also see the
+ peer_connect_timeout directive)
- "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.
+ use 'digest-url=url' to tell Squid to fetch the cache
+ digest (if digests are enabled) for this host from
+ the specified URL rather than the Squid default
+ location.
- By default, the basic authentication scheme is not used unless a
- program is specified.
+ use 'allow-miss' to 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)
- If you want to use the traditional NCSA proxy authentication, set
- this line to something like
+ use 'max-conn=n' to limit the amount of connections Squid
+ may open to this peer.
- auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
+ use 'htcp' to send HTCP, instead of ICP, queries
+ to the neighbor. You probably also want to
+ set the "icp port" to 4827 instead of 3130.
- "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
+ use 'htcp-oldsquid' to send HTCP to old Squid versions
- "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
+ 'originserver' causes this parent peer to be contacted as
+ a origin server. Meant to be used in accelerator setups.
- "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.
+ use 'name=xxx' if you have multiple peers on the same
+ host but different ports. This name can be used to
+ differentiate the peers in cache_peer_access and similar
+ directives.
- "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
+ use 'forceddomain=name' to forcibly set the Host header
+ of requests forwarded to this peer. Useful in accelerator
+ setups where the server (peer) expects a certain domain
+ name and using redirectors to feed this domain name
+ is not feasible.
- === Parameters for the digest scheme follow ===
+ use 'ssl' to indicate connections to this peer should
+ be SSL/TLS encrypted.
- "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.
+ use 'sslcert=/path/to/ssl/certificate' to specify a client
+ SSL certificate to use when connecting to this peer.
- By default, the digest authentication scheme is not used unless a
- program is specified.
+ use 'sslkey=/path/to/ssl/key' to specify the private SSL
+ key corresponding to sslcert above. If 'sslkey' is not
+ specified 'sslcert' is assumed to reference a
+ combined file containing both the certificate and the key.
- If you want to use a digest authenticator, set this line to
- something like
+ use sslversion=1|2|3|4 to specify 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
- auth_param digest program @DEFAULT_PREFIX@/bin/digest_auth_pw @DEFAULT_PREFIX@/etc/digpass
+ use sslcipher=... to specify the list of valid SSL ciphers
+ to use when connecting to this peer.
- "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
+ use ssloptions=... to 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.
- "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
+ use sslcafile=... to specify a file containing
+ additional CA certificates to use when verifying the
+ peer certificate.
- "nonce_garbage_interval" timeinterval
- Specifies the interval that nonces that have been issued
- to client_agent's are checked for validity.
+ use sslcapath=... to specify a directory containing
+ additional CA certificates to use when verifying the
+ peer certificate.
- "nonce_max_duration" timeinterval
- Specifies the maximum length of time a given nonce will be
- valid for.
+ use sslcrlfile=... to specify a certificate revocation
+ list file to use when verifying the peer certificate.
+
+ use sslflags=... to specify various flags modifying the
+ SSL implementation:
+ DONT_VERIFY_PEER
+ Accept certificates even if they fail to
+ verify.
+ NO_DEFAULT_CA
+ Don't use the default CA list built in
+ to OpenSSL.
+ DONT_VERIFY_DOMAIN
+ Don't verify the peer certificate
+ matches the server name
- "nonce_max_count" number
- Specifies the maximum number of times a given nonce can be
- used.
+ use ssldomain= to specify the peer name as advertised
+ in it's certificate. Used for verifying the correctness
+ of the received peer certificate. If not specified the
+ peer hostname will be used.
- "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.
+ use front-end-https to enable the "Front-End-Https: On"
+ header needed when using Squid as a SSL frontend in front
+ of Microsoft OWA. See MS KB document Q307347 for details
+ on this header. If set to auto the header will
+ only be added if the request is forwarded as a https://
+ URL.
+DOC_END
- "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.
+NAME: cache_peer_domain cache_host_domain
+TYPE: hostdomain
+DEFAULT: none
+LOC: none
+DOC_START
+ Use to limit the domains for which a neighbor cache will be
+ queried. Usage:
- "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.
+ cache_peer_domain cache-host domain [domain ...]
+ cache_peer_domain cache-host !domain
- === NTLM scheme options follow ===
+ For example, specifying
- "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.
+ cache_peer_domain parent.foo.net .edu
- auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
+ has the effect such that UDP query packets are sent to
+ 'bigserver' only when the requested object exists on a
+ server in the .edu domain. Prefixing the domainname
+ with '!' means the cache will be queried for objects
+ NOT in that domain.
- "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.
+ NOTE: * Any number of domains may be given for a cache-host,
+ either on the same or separate lines.
+ * When multiple domains are given for a particular
+ cache-host, the first matched domain is applied.
+ * Cache hosts with no domain restrictions are queried
+ for all requests.
+ * There are no defaults.
+ * There is also a 'cache_peer_access' tag in the ACL
+ section.
+DOC_END
- auth_param ntlm children 5
+NAME: cache_peer_access
+TYPE: peer_access
+DEFAULT: none
+LOC: none
+DOC_START
+ Similar to 'cache_peer_domain' but provides more flexibility by
+ using ACL elements.
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
+ cache_peer_access cache-host allow|deny [!]aclname ...
- auth_param ntlm keep_alive on
+ 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://www.squid-cache.org/FAQ/FAQ-10.html).
+DOC_END
- === Options for configuring the NEGOTIATE auth-scheme follow ===
+NAME: neighbor_type_domain
+TYPE: hostdomaintype
+DEFAULT: none
+LOC: none
+DOC_START
+ usage: neighbor_type_domain neighbor parent|sibling domain domain ...
- "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.
+ 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.
- auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
+EXAMPLE:
+ cache_peer parent cache.foo.org 3128 3130
+ neighbor_type_domain cache.foo.org sibling .com .net
+ neighbor_type_domain cache.foo.org sibling .au .de
+DOC_END
- "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
+NAME: dead_peer_timeout
+COMMENT: (seconds)
+DEFAULT: 10 seconds
+TYPE: time_t
+LOC: Config.Timeout.deadPeer
+DOC_START
+ This controls how long Squid waits to declare a peer cache
+ as "dead." If there are no ICP replies received in this
+ amount of time, Squid will declare the peer dead and not
+ expect to receive any further ICP replies. However, it
+ continues to send ICP queries, and will mark the peer as
+ alive upon receipt of the first subsequent ICP reply.
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
-
- auth_param negotiate keep_alive on
+ This timeout also affects when Squid expects to receive ICP
+ replies from peers. If more than 'dead_peer' seconds have
+ passed since the last ICP reply was received, Squid will not
+ expect to receive an ICP reply on the next query. Thus, if
+ your time between requests is greater than this timeout, you
+ will see a lot of requests sent DIRECT to origin servers
+ instead of to your parents.
+DOC_END
+NAME: hierarchy_stoplist
+TYPE: wordlist
+DEFAULT: none
+LOC: Config.hierarchy_stoplist
+DOC_START
+ 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.
+ Note: never_direct overrides this option.
NOCOMMENT_START
-#Recommended minimum configuration per scheme:
-#auth_param negotiate program <uncomment and complete this line to activate>
-#auth_param negotiate children 5
-#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 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 basic program <uncomment and complete this line>
-#auth_param basic children 5
-#auth_param basic realm Squid proxy-caching web server
-#auth_param basic credentialsttl 2 hours
+#We recommend you to use at least the following line.
+hierarchy_stoplist cgi-bin ?
NOCOMMENT_END
DOC_END
-NAME: authenticate_cache_garbage_interval
-TYPE: time_t
-DEFAULT: 1 hour
-LOC: Config.authenticateGCInterval
+NAME: cache no_cache
+TYPE: acl_access
+DEFAULT: none
+LOC: Config.accessList.noCache
DOC_START
- The time period between garbage collection across the username cache.
- This is a tradeoff between memory utilization (long intervals - say
- 2 days) and CPU (short intervals - say 1 minute). Only change if you
- have good reason to.
+ A list of ACL elements which, if matched, 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.
+
+ You must use the word 'DENY' to indicate the ACL names which should
+ NOT be cached.
+
+ Default is to allow all to be cached
+NOCOMMENT_START
+#We recommend you to use the following two lines.
+acl QUERY urlpath_regex cgi-bin \?
+cache deny QUERY
+NOCOMMENT_END
DOC_END
-NAME: authenticate_ttl
-TYPE: time_t
-DEFAULT: 1 hour
-LOC: Config.authenticateTTL
+COMMENT_START
+ MEMORY CACHE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: cache_mem
+COMMENT: (bytes)
+TYPE: b_size_t
+DEFAULT: 8 MB
+LOC: Config.memMaxSize
DOC_START
- The time a user & their credentials stay in the logged in
- user cache since their last request. When the garbage
- interval passes, all user credentials that have passed their
- TTL are removed from memory.
+ NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
+ IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
+ USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
+ THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
+
+ 'cache_mem' specifies the ideal amount of memory to be used
+ for:
+ * In-Transit objects
+ * Hot Objects
+ * Negative-Cached objects
+
+ Data for these objects are stored in 4 KB blocks. This
+ parameter specifies the ideal upper limit on the total size of
+ 4 KB blocks allocated. In-Transit objects take the highest
+ priority.
+
+ In-transit objects have priority over the others. When
+ additional space is needed for incoming data, negative-cached
+ and hot objects will be released. In other words, the
+ negative-cached and hot objects will fill up any unused space
+ not needed for in-transit objects.
+
+ If circumstances require, this limit will be exceeded.
+ Specifically, if your incoming request rate requires more than
+ 'cache_mem' of memory to hold in-transit objects, Squid will
+ exceed this limit to satisfy the new requests. When the load
+ decreases, blocks will be freed until the high-water mark is
+ reached. Thereafter, blocks will be used to store hot
+ objects.
DOC_END
-NAME: authenticate_ip_ttl
-TYPE: time_t
-LOC: Config.authenticateIpTTL
-DEFAULT: 0 seconds
+NAME: maximum_object_size_in_memory
+COMMENT: (bytes)
+TYPE: b_size_t
+DEFAULT: 8 KB
+LOC: Config.Store.maxInMemObjSize
DOC_START
- If you use proxy authentication and the 'max_user_ip' ACL,
- this directive controls how long Squid remembers the IP
- addresses associated with each user. Use a small value
- (e.g., 60 seconds) if your users might change addresses
- quickly, as is the case with dialups. You might be safe
- using a larger value (e.g., 2 hours) in a corporate LAN
- environment with relatively static address assignments.
+ Objects greater than this size will not be attempted to kept in
+ the memory cache. This should be set high enough to keep objects
+ accessed frequently in memory to improve performance whilst low
+ enough to keep larger objects from hoarding cache_mem.
DOC_END
-NAME: external_acl_type
-TYPE: externalAclHelper
-LOC: Config.externalAclHelperList
-DEFAULT: none
+NAME: memory_replacement_policy
+TYPE: removalpolicy
+LOC: Config.memPolicy
+DEFAULT: lru
DOC_START
- This option defines external acl classes using a helper program
- to look up the status
-
- external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
-
- Options:
-
- 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
- external acl lookups of this type. (default 5)
- 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
+ The memory replacement policy parameter determines which
+ objects are purged from memory when memory space is needed.
- FORMAT specifications
+ See cache_replacement_policy for details.
+DOC_END
- %LOGIN Authenticated user login name
- %EXT_USER Username from external acl
- %IDENT Ident user name
- %SRC Client IP
- %SRCPORT Client source port
- %URI Requested URI
- %DST Requested host
- %PROTO Requested protocol
- %PORT Requested port
- %PATH Requested URL path
- %METHOD Request method
- %MYADDR Squid interface address
- %MYPORT Squid http_port number
- %PATH Requested URL-path (including query-string if any)
- %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
- %{Header} HTTP request header
- %{Hdr:member} HTTP request header list member
- %{Hdr:;member}
- HTTP request header list member using ; as
- list separator. ; can be any non-alphanumeric
- character.
+COMMENT_START
+ DISK CACHE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
- 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)
+NAME: cache_replacement_policy
+TYPE: removalpolicy
+LOC: Config.replPolicy
+DEFAULT: lru
+DOC_START
+ The cache replacement policy parameter determines which
+ objects are evicted (replaced) when disk space is needed.
- 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.
+ lru : Squid's original list based LRU policy
+ heap GDSF : Greedy-Dual Size Frequency
+ heap LFUDA: Least Frequently Used with Dynamic Aging
+ heap LRU : LRU policy implemented using a heap
- General result syntax:
+ Applies to any cache_dir lines listed below this.
- OK/ERR keyword=value ...
+ The LRU policies keeps recently referenced objects.
- Defined keywords:
+ The heap GDSF policy optimizes object hit rate by keeping smaller
+ popular objects in cache so it has a better chance of getting a
+ hit. It achieves a lower byte hit rate than LFUDA though since
+ it evicts larger (possibly popular) objects.
- 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.
- log= String to be logged in access.log. Available as
- %ea in logformat specifications
+ The heap LFUDA policy keeps popular objects in cache regardless of
+ their size and thus optimizes byte hit rate at the expense of
+ hit rate since one large, popular object will prevent many
+ smaller, slightly less popular objects from being cached.
- If protocol=3.0 (the default) then URL escaping is used to protect
- each value in both requests and responses.
+ Both policies utilize a dynamic aging mechanism that prevents
+ cache pollution that can otherwise occur with frequency-based
+ replacement policies.
- 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.
+ NOTE: if using the LFUDA replacement policy you should increase
+ the value of maximum_object_size above its default of 4096 KB to
+ to maximize the potential byte hit rate improvement of LFUDA.
- 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.
+ For more information about the GDSF and LFUDA cache replacement
+ policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
+ and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
DOC_END
-COMMENT_START
- OPTIONS FOR TUNING THE CACHE
- -----------------------------------------------------------------------------
-COMMENT_END
-
-NAME: request_header_max_size
-COMMENT: (KB)
-TYPE: b_size_t
-DEFAULT: 20 KB
-LOC: Config.maxRequestHeaderSize
+NAME: cache_dir
+TYPE: cachedir
+DEFAULT: none
+DEFAULT_IF_NONE: ufs @DEFAULT_SWAP_DIR@ 100 16 256
+LOC: Config.cacheSwap
DOC_START
- This specifies the maximum size for HTTP headers in a request.
- Request headers are usually relatively small (about 512 bytes).
- Placing a limit on the request header size will catch certain
- bugs (for example with persistent connections) and possibly
- buffer-overflow or denial-of-service attacks.
-DOC_END
+ Usage:
-NAME: request_body_max_size
-COMMENT: (bytes)
-TYPE: b_int64_t
-DEFAULT: 0 KB
-LOC: Config.maxRequestBodySize
-DOC_START
- This specifies the maximum size for an HTTP request body.
- In other words, the maximum size of a PUT/POST request.
- A user who attempts to send a request with a body larger
- 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.
-DOC_END
+ cache_dir Type Directory-Name Fs-specific-data [options]
-NAME: refresh_pattern
-TYPE: refreshpattern
-LOC: Config.Refresh
-DEFAULT: none
-DOC_START
- usage: refresh_pattern [-i] regex min percent max [options]
+ You can specify multiple cache_dir lines to spread the
+ cache among different disk partitions.
- By default, regular expressions are CASE-SENSITIVE. To make
- them case-insensitive, use the -i option.
+ Type specifies the kind of storage system to use. Only "ufs"
+ is built by default. To enable any of the other storage systems
+ see the --enable-storeio configure option.
- 'Min' is the time (in minutes) an object without an explicit
- expiry time should be considered fresh. The recommended
- value is 0, any higher values may cause dynamic applications
- to be erroneously cached unless the application designer
- has taken the appropriate actions.
+ 'Directory' is a top-level directory where cache swap
+ files will be stored. If you want to use an entire disk
+ for caching, this can be the mount-point directory.
+ The directory must exist and be writable by the Squid
+ process. Squid will NOT create this directory for you.
- 'Percent' is a percentage of the objects age (time since last
- modification age) an object without explicit expiry time
- will be considered fresh.
+ The ufs store type:
- 'Max' is an upper limit on how long objects without an explicit
- expiry time will be considered fresh.
+ "ufs" is the old well-known Squid storage format that has always
+ been there.
- options: override-expire
- override-lastmod
- reload-into-ims
- ignore-reload
- ignore-no-cache
- ignore-no-store
- ignore-private
- ignore-auth
- refresh-ims
+ cache_dir ufs Directory-Name Mbytes L1 L2 [options]
- override-expire enforces min age even if the server
- sent a Expires: header. Doing this VIOLATES the HTTP
- standard. Enabling this feature could make you liable
- for problems which it causes.
+ 'Mbytes' is the amount of disk space (MB) to use under this
+ directory. The default is 100 MB. Change this to suit your
+ configuration. Do NOT put the size of your disk drive here.
+ Instead, if you want Squid to use the entire disk drive,
+ subtract 20% and use that value.
- override-lastmod enforces min age even on objects
- that were modified recently.
+ 'Level-1' is the number of first-level subdirectories which
+ will be created under the 'Directory'. The default is 16.
- 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.
+ 'Level-2' is the number of second-level subdirectories which
+ will be created under each first-level directory. The default
+ is 256.
- 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.
+ The aufs store type:
- 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.
+ "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.
- 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
- liable for problems which it causes.
+ cache_dir aufs Directory-Name Mbytes L1 L2 [options]
- ignore-private ignores any ``Cache-control: private''
- headers received from a server. Doing this VIOLATES
- the HTTP standard. Enabling this feature could make you
- liable for problems which it causes.
+ see argument descriptions under ufs above
- ignore-auth caches responses to requests with authorization,
- as if the originserver had sent ``Cache-control: public''
- in the response header. Doing this VIOLATES the HTTP standard.
- Enabling this feature could make you liable for problems which
- it causes.
+ The diskd store type:
- refresh-ims causes squid to contact the origin server
- when a client issues an If-Modified-Since request. This
- ensures that the client will receive an updated version
- if one is available.
+ "diskd" uses the same storage format as "ufs", utilizing a
+ separate process to avoid blocking the main Squid process on
+ disk-I/O.
- Basically a cached object is:
+ cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
- FRESH if expires < now, else STALE
- STALE if age > max
- FRESH if lm-factor < percent, else STALE
- FRESH if age < min
- else STALE
+ see argument descriptions under ufs above
- The refresh_pattern lines are checked in the order listed here.
- The first entry which matches is used. If none of the entries
- match the default will be used.
+ Q1 specifies the number of unacknowledged I/O requests when Squid
+ stops opening new files. If this many messages are in the queues,
+ Squid won't open new files. Default is 64
- Note, you must uncomment all the default lines if you want
- to change one. The default setting is only active if none is
- used.
+ Q2 specifies the number of unacknowledged messages when Squid
+ starts blocking. If this many messages are in the queues,
+ Squid blocks until it receives some replies. Default is 72
-Suggested default:
-NOCOMMENT_START
-refresh_pattern ^ftp: 1440 20% 10080
-refresh_pattern ^gopher: 1440 0% 1440
-refresh_pattern . 0 20% 4320
-NOCOMMENT_END
-DOC_END
+ When Q1 < Q2 (the default), the cache directory is optimized
+ for lower response time at the expense of a decrease in hit
+ ratio. If Q1 > Q2, the cache directory is optimized for
+ higher hit ratio at the expense of an increase in response
+ time.
-NAME: quick_abort_min
-COMMENT: (KB)
-TYPE: kb_int64_t
-DEFAULT: 16 KB
-LOC: Config.quickAbort.min
-DOC_NONE
+ The coss store type:
-NAME: quick_abort_max
-COMMENT: (KB)
-TYPE: kb_int64_t
-DEFAULT: 16 KB
-LOC: Config.quickAbort.max
-DOC_NONE
+ 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.
-NAME: quick_abort_pct
-COMMENT: (percent)
-TYPE: int
-DEFAULT: 95
-LOC: Config.quickAbort.pct
-DOC_START
- The cache by default continues downloading aborted requests
- which are almost completed (less than 16 KB remaining). This
- may be undesirable on slow (e.g. SLIP) links and/or very busy
- caches. Impatient users may tie up file descriptors and
- bandwidth by repeatedly requesting and immediately aborting
- downloads.
+ 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.
- When the user aborts a request, Squid will check the
- quick_abort values to the amount of data transfered until
- then.
+ The null store type:
- If the transfer has less than 'quick_abort_min' KB remaining,
- it will finish the retrieval.
+ no options are allowed or required
- If the transfer has more than 'quick_abort_max' KB remaining,
- it will abort the retrieval.
+ Common options:
- If more than 'quick_abort_pct' of the transfer has completed,
- it will finish the retrieval.
+ no-store, no new objects should be stored to this cache_dir
- If you do not want any retrieval to continue after the client
- has aborted, set both 'quick_abort_min' and 'quick_abort_max'
- to '0 KB'.
+ max-size=n, refers to the max object size this storedir supports.
+ It is used to initially choose the storedir to dump 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.
- If you want retrievals to always continue if they are being
- cached set 'quick_abort_min' to '-1 KB'.
+ 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.
DOC_END
-NAME: read_ahead_gap
-COMMENT: buffer-size
-TYPE: b_int64_t
-LOC: Config.readAheadGap
-DEFAULT: 16 KB
+NAME: store_dir_select_algorithm
+TYPE: string
+LOC: Config.store_dir_select_algorithm
+DEFAULT: least-load
DOC_START
- The amount of data the cache will buffer ahead of what has been
- sent to the client when retrieving an object from another server.
+ Set this to 'round-robin' as an alternative.
DOC_END
-NAME: negative_ttl
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.negativeTtl
-DEFAULT: 5 minutes
+NAME: max_open_disk_fds
+TYPE: int
+LOC: Config.max_open_disk_fds
+DEFAULT: 0
DOC_START
- Time-to-Live (TTL) for failed requests. Certain types of
- failures (such as "connection refused" and "404 Not Found") are
- negatively-cached for a configurable amount of time. The
- default is 5 minutes. Note that this is different from
- negative caching of DNS lookups.
+ To avoid having disk as the I/O bottleneck Squid can optionally
+ bypass the on-disk cache if more than this amount of disk file
+ descriptors are open.
+
+ A value of 0 indicates no limit.
DOC_END
-NAME: positive_dns_ttl
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.positiveDnsTtl
-DEFAULT: 6 hours
-DOC_START
- Upper limit on how long Squid will cache positive DNS responses.
- Default is 6 hours (360 minutes). This directive must be set
- larger than negative_dns_ttl.
-DOC_END
-
-NAME: negative_dns_ttl
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.negativeDnsTtl
-DEFAULT: 1 minutes
-DOC_START
- Time-to-Live (TTL) for negative caching of failed DNS lookups.
- This also sets the lower cache limit on positive lookups.
- Minimum value is 1 second, and it is not recommendable to go
- much below 10 seconds.
-DOC_END
-
-NAME: range_offset_limit
+NAME: minimum_object_size
COMMENT: (bytes)
TYPE: b_int64_t
-LOC: Config.rangeOffsetLimit
DEFAULT: 0 KB
+LOC: Config.Store.minObjectSize
DOC_START
- 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.
-
- 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 -1 causes Squid to always fetch the object from the
- beginning so it may cache the result. (2.0 style)
-
- A value of 0 causes Squid to never fetch more than the
- client requested. (default)
+ 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.
DOC_END
-NAME: minimum_expiry_time
-COMMENT: (seconds)
-TYPE: time_t
-LOC: Config.minimum_expiry_time
-DEFAULT: 60 seconds
+NAME: maximum_object_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 4096 KB
+LOC: Config.Store.maxObjectSize
DOC_START
- The minimum caching time according to (Expires - Date)
- Headers Squid honors if the object can't be revalidated
- defaults to 60 seconds. In reverse proxy enorinments it
- might be desirable to honor shorter object lifetimes. It
- is most likely better to make your server return a
- meaningful Last-Modified header however. In ESI environments
- where page fragments often have short lifetimes, this will
- often be best set to 0.
-DOC_END
+ 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.
-NAME: store_avg_object_size
-COMMENT: (kbytes)
-TYPE: kb_size_t
-DEFAULT: 13 KB
-LOC: Config.Store.avgObjectSize
-DOC_START
- Average object size, used to estimate number of objects your
- cache can hold. The default is 13 KB.
+ 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.
DOC_END
-NAME: store_objects_per_bucket
+NAME: cache_swap_low
+COMMENT: (percent, 0-100)
TYPE: int
-DEFAULT: 20
-LOC: Config.Store.objectsPerBucket
+DEFAULT: 90
+LOC: Config.Swap.lowWaterMark
+DOC_NONE
+
+NAME: cache_swap_high
+COMMENT: (percent, 0-100)
+TYPE: int
+DEFAULT: 95
+LOC: Config.Swap.highWaterMark
DOC_START
- Target number of objects per bucket in the store hash table.
- Lowering this value increases the total number of buckets and
- also the storage maintenance rate. The default is 20.
+
+ 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.
+
+ 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.
DOC_END
COMMENT_START
- HTTP OPTIONS
+ LOGFILE OPTIONS
-----------------------------------------------------------------------------
COMMENT_END
-NAME: broken_posts
-TYPE: acl_access
+NAME: logformat
+TYPE: logformat
+LOC: Config.Log.logformats
DEFAULT: none
-LOC: Config.accessList.brokenPosts
DOC_START
- A list of ACL elements which, if matched, causes Squid to send
- an extra CRLF pair after the body of a PUT/POST request.
+ Usage:
- Some HTTP servers has broken implementations of PUT/POST,
- and rely on an extra CRLF pair sent by some WWW clients.
+ logformat <name> <format specification>
- Quote from RFC2616 section 4.1 on this matter:
+ Defines an access log format.
- Note: certain buggy HTTP/1.0 client implementations generate an
- extra CRLF's after a POST request. To restate what is explicitly
- forbidden by the BNF, an HTTP/1.1 client must not preface or follow
- a request with an extra CRLF.
+ The <format specification> is a string with embedded % format codes
-Example:
- acl buggy_server url_regex ^http://....
- broken_posts allow buggy_server
-DOC_END
+ % format codes all follow the same basic structure where all but
+ the formatcode is optional. Output strings are automatically escaped
+ as required according to their context and the output format
+ modifiers are usually not needed, but can be specified if an explicit
+ output format is desired.
-NAME: via
-IFDEF: HTTP_VIOLATIONS
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.via
-DOC_START
- If set (default), Squid will include a Via header in requests and
- replies as required by RFC2616.
-DOC_END
+ % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
-NAME: ie_refresh
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.ie_refresh
-DEFAULT: off
-DOC_START
- Microsoft Internet Explorer up until version 5.5 Service
- Pack 1 has an issue with transparent proxies, wherein it
- is impossible to force a refresh. Turning this on provides
- a partial fix to the problem, by causing all IMS-REFRESH
- requests from older IE versions to check the origin server
- for fresh content. This reduces hit ratio by some amount
- (~10% in my experience), but allows users to actually get
- fresh content when they want it. Note because Squid
- cannot tell if the user is using 5.5 or 5.5SP1, the behavior
- of 5.5 is unchanged from old versions of Squid (i.e. a
- forced refresh is impossible). Newer versions of IE will,
- hopefully, continue to have the new behavior and will be
- handled based on that assumption. This option defaults to
- the old Squid behavior, which is better for hit ratios but
- worse for clients using IE, if they need to be able to
- force fresh content.
-DOC_END
+ " output in quoted string format
+ [ output in squid text log format as used by log_mime_hdrs
+ # output in URL quoted format
+ ' output as-is
-NAME: vary_ignore_expire
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.vary_ignore_expire
-DEFAULT: off
-DOC_START
- Many HTTP servers supporting Vary gives such objects
- immediate expiry time with no cache-control header
- when requested by a HTTP/1.0 client. This option
- enables Squid to ignore such expiry times until
- HTTP/1.1 is fully implemented.
- WARNING: This may eventually cause some varying
- objects not intended for caching to get cached.
-DOC_END
+ - left aligned
+ width field width. If starting with 0 the
+ output is zero padded
+ {arg} argument such as header name etc
-NAME: extension_methods
-TYPE: wordlist
-LOC: Config.ext_methods
-DEFAULT: none
-DOC_START
- Squid only knows about standardized HTTP request methods.
- You can add up to 20 additional "extension" methods here.
-DOC_END
+ Format codes:
-NAME: request_entities
-TYPE: onoff
-LOC: Config.onoff.request_entities
-DEFAULT: off
-DOC_START
- Squid defaults to deny GET and HEAD requests with request entities,
- as the meaning of such requests are undefined in the HTTP standard
- even if not explicitly forbidden.
+ >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)
+ ts Seconds since epoch
+ tu subsecond time (milliseconds)
+ tl Local time. Optional strftime format argument
+ default %d/%b/%Y:%H:%M:%S %z
+ tg GMT time. Optional strftime format argument
+ default %d/%b/%Y:%H:%M:%S %z
+ tr Response time (milliseconds)
+ >h Request header. Optional header name argument
+ on the format header[:[separator]element]
+ <h Reply header. Optional header name argument
+ as for >h
+ un User name
+ ul User name from authentication
+ ui User name from ident
+ us User name from SSL
+ ue User name from external acl helper
+ Hs HTTP status code
+ Ss Squid request status (TCP_MISS etc)
+ Sh Squid hierarchy status (DEFAULT_PARENT etc)
+ mt MIME content type
+ rm Request method (GET/POST etc)
+ ru Request URL
+ rp Request URL-Path excluding hostname
+ rv Request protocol version
+ et Tag returned by external acl
+ ea Log string returned by external acl
+ <st Reply size including HTTP headers
+ <sH Reply high offset sent
+ <sS Upstream object size
+ % a literal % character
- Set this directive to on if you have clients which insists
- on sending request entities in GET or HEAD requests. But be warned
- that there is server software (both proxies and web servers) which
- can fail to properly process this kind of request which may make you
- vulnerable to cache pollution attacks if enabled.
+logformat squid %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
+logformat squidmime %ts.%03tu %6tr %>a %Ss/%03Hs %<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
DOC_END
-NAME: request_header_access
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_access[]
-LOC: Config.request_header_access
+NAME: access_log cache_access_log
+TYPE: access_log
+LOC: Config.Log.accesslogs
DEFAULT: none
DOC_START
- Usage: request_header_access header_name allow|deny [!]aclname ...
-
- WARNING: Doing this VIOLATES the HTTP standard. Enabling
- this feature could make you liable for problems which it
- causes.
-
- 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.
+ 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 ...]]
- 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'.
+ 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).
+ If no acl is specified, all requests will be logged to this file.
- For example, to achieve the same behavior as the old
- 'http_anonymizer standard' option, you should use:
+ To disable logging of a request use the filepath "none", in which case
+ a logformat name should not be specified.
- 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
+ To log the request via syslog specify a filepath of "syslog":
- Or, to reproduce the old 'http_anonymizer paranoid' feature
- you should use:
+ access_log syslog[:facility.priority] [format [acl1 [acl2 ....]]]
+ where facility could be any of:
+ authpriv, daemon, local0 .. local7 or user.
- 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 Proxy-Connection allow all
- request_header_access All deny all
+ And priority could be any of:
+ err, warning, notice, info, debug.
+NOCOMMENT_START
+access_log @DEFAULT_ACCESS_LOG@ squid
+NOCOMMENT_END
+DOC_END
- although many of those are HTTP reply headers, and so should be
- controlled with the reply_header_access directive.
+NAME: cache_log
+TYPE: string
+DEFAULT: @DEFAULT_CACHE_LOG@
+LOC: Config.Log.log
+DOC_START
+ Cache logging file. This is where general information about
+ your cache's behavior goes. You can increase the amount of data
+ logged to this file with the "debug_options" tag below.
+DOC_END
- By default, all headers are allowed (no anonymizing is
- performed).
+NAME: cache_store_log
+TYPE: string
+DEFAULT: @DEFAULT_STORE_LOG@
+LOC: Config.Log.store
+DOC_START
+ Logs the activities of the storage manager. Shows which
+ objects are ejected from the cache, and which objects are
+ saved and for how long. To disable, enter "none". There are
+ not really utilities to analyze this data, so you can safely
+ disable it.
DOC_END
-NAME: reply_header_access
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_access[]
-LOC: Config.reply_header_access
+NAME: cache_swap_state cache_swap_log
+TYPE: string
+LOC: Config.Log.swap
DEFAULT: none
DOC_START
- Usage: reply_header_access header_name allow|deny [!]aclname ...
-
- WARNING: Doing this VIOLATES the HTTP standard. Enabling
- this feature could make you liable for problems which it
- causes.
-
- This option only applies to reply headers, i.e., from the
- 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'.
-
- 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
+ Location for the cache "swap.state" file. This index file holds
+ the metadata of objects saved on disk. It is used to rebuild
+ the cache during startup. Normally this file resides in each
+ 'cache_dir' directory, but you may specify an alternate
+ pathname here. Note you must give a full filename, not just
+ a directory. Since this is the index for the whole object
+ list you CANNOT periodically rotate it!
- Or, to reproduce the old 'http_anonymizer paranoid' feature
- you should use:
+ If %s can be used in the file name it will be replaced with a
+ a representation of the cache_dir name where each / is replaced
+ with '.'. This is needed to allow adding/removing cache_dir
+ lines when cache_swap_log is being used.
- reply_header_access Allow allow all
- reply_header_access Authorization allow all
- reply_header_access WWW-Authenticate allow all
- reply_header_access Proxy-Authorization allow all
- reply_header_access Proxy-Authenticate allow all
- reply_header_access Cache-Control allow all
- reply_header_access Content-Encoding allow all
- reply_header_access Content-Length allow all
- reply_header_access Content-Type allow all
- reply_header_access Date allow all
- reply_header_access Expires allow all
- reply_header_access Host allow all
- reply_header_access If-Modified-Since allow all
- reply_header_access Last-Modified allow all
- reply_header_access Location allow all
- reply_header_access Pragma allow all
- reply_header_access Accept allow all
- reply_header_access Accept-Charset allow all
- reply_header_access Accept-Encoding allow all
- reply_header_access Accept-Language allow all
- reply_header_access Content-Language allow all
- reply_header_access Mime-Version allow all
- reply_header_access Retry-After allow all
- reply_header_access Title allow all
- reply_header_access Connection allow all
- reply_header_access Proxy-Connection allow all
- reply_header_access All deny all
+ If have more than one 'cache_dir', and %s is not used in the name
+ these swap logs will have names such as:
- although the HTTP request headers won't be usefully controlled
- by this directive -- see request_header_access for details.
+ cache_swap_log.00
+ cache_swap_log.01
+ cache_swap_log.02
- By default, all headers are allowed (no anonymizing is
- performed).
+ The numbered extension (which is added automatically)
+ corresponds to the order of the 'cache_dir' lines in this
+ configuration file. If you change the order of the 'cache_dir'
+ lines in this file, these index files will NOT correspond to
+ the correct 'cache_dir' entry (unless you manually rename
+ them). We recommend you do NOT use this option. It is
+ better to keep these index files in each 'cache_dir' directory.
DOC_END
-NAME: header_replace
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_replace[]
-LOC: Config.request_header_access
-DEFAULT: none
+NAME: logfile_rotate
+TYPE: int
+DEFAULT: 10
+LOC: Config.Log.rotateNumber
DOC_START
- Usage: header_replace header_name message
- Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
-
- This option allows you to change the contents of headers
- denied with header_access above, by replacing them with
- some fixed string. This replaces the old fake_user_agent
- option.
+ Specifies the number of logfile rotations to make when you
+ type 'squid -k rotate'. The default is 10, which will rotate
+ with extensions 0 through 9. Setting logfile_rotate to 0 will
+ disable the file name rotation, but the logfiles are still closed
+ and re-opened. This will enable you to rename the logfiles
+ yourself just before sending the rotate signal.
- This only applies to request headers, not reply headers.
+ Note, the 'squid -k rotate' command normally sends a USR1
+ signal to the running squid process. In certain situations
+ (e.g. on Linux with Async I/O), USR1 is used for other
+ purposes, so -k rotate uses another signal. It is best to get
+ in the habit of using 'squid -k rotate' instead of 'kill -USR1
+ <pid>'.
+DOC_END
- By default, headers are removed if denied.
+NAME: emulate_httpd_log
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.common_log
+DOC_START
+ 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.
DOC_END
-NAME: relaxed_header_parser
-COMMENT: on|off|warn
-TYPE: tristate
-LOC: Config.onoff.relaxed_header_parser
+NAME: log_ip_on_direct
+COMMENT: on|off
+TYPE: onoff
DEFAULT: on
+LOC: Config.onoff.log_ip_on_direct
DOC_START
- In the default "on" setting Squid accepts certain forms
- of non-compliant HTTP messages where it is unambiguous
- what the sending application intended even if the message
- is not correctly formatted. The messages is then normalized
- to the correct form when forwarded by Squid.
+ 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.
+DOC_END
- If set to "warn" then a warning will be emitted in cache.log
- each time such HTTP error is encountered.
-
- If set to "off" then such HTTP errors will cause the request
- or response to be rejected.
+NAME: mime_table
+TYPE: string
+DEFAULT: @DEFAULT_MIME_TABLE@
+LOC: Config.mimeTablePathname
+DOC_START
+ Pathname to Squid's MIME table. You shouldn't need to change
+ this, but the default file contains examples and formatting
+ information if you do.
DOC_END
-COMMENT_START
- TIMEOUTS
- -----------------------------------------------------------------------------
-COMMENT_END
+NAME: log_mime_hdrs
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.log_mime_hdrs
+DEFAULT: off
+DOC_START
+ The Cache can record both the request and the response MIME
+ headers for each HTTP transaction. The headers are encoded
+ safely and will appear as two bracketed fields at the end of
+ the access log (for either the native or httpd-emulated log
+ formats). To enable this logging set log_mime_hdrs to 'on'.
+DOC_END
-NAME: forward_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.forward
-DEFAULT: 4 minutes
+NAME: useragent_log
+TYPE: string
+LOC: Config.Log.useragent
+DEFAULT: none
+IFDEF: USE_USERAGENT_LOG
DOC_START
- This parameter specifies how long Squid should at most attempt in
- finding a forwarding path for the request before giving up.
+ Squid will write the User-Agent field from HTTP requests
+ to the filename specified here. By default useragent_log
+ is disabled.
DOC_END
-NAME: connect_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.connect
-DEFAULT: 1 minute
+NAME: referer_log referrer_log
+TYPE: string
+LOC: Config.Log.referer
+DEFAULT: none
+IFDEF: USE_REFERER_LOG
DOC_START
- This parameter specifies how long to wait for the TCP connect to
- the requested server or peer to complete before Squid should
- attempt to find another path where to forward the request.
+ 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.
DOC_END
-NAME: peer_connect_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.peer_connect
-DEFAULT: 30 seconds
+NAME: pid_filename
+TYPE: string
+DEFAULT: @DEFAULT_PID_FILE@
+LOC: Config.pidFilename
DOC_START
- This parameter specifies how long to wait for a pending TCP
- connection to a peer cache. The default is 30 seconds. You
- may also set different timeout values for individual neighbors
- with the 'connect-timeout' option on a 'cache_peer' line.
+ A filename to write the process-id to. To disable, enter "none".
DOC_END
-NAME: read_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.read
-DEFAULT: 15 minutes
+NAME: debug_options
+TYPE: debug
+DEFAULT: ALL,1
+LOC: Config.debugOptions
DOC_START
- The read_timeout is applied on server-side 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.
+ Logging options are set as section,level where each source file
+ is assigned a unique section. Lower levels result in less
+ output, Full debugging (level 9) can result in a very large
+ log file, so be careful. The magic word "ALL" sets debugging
+ levels for all sections. We recommend normally running with
+ "ALL,1".
DOC_END
-NAME: request_timeout
-TYPE: time_t
-LOC: Config.Timeout.request
-DEFAULT: 5 minutes
+NAME: log_fqdn
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.log_fqdn
DOC_START
- How long to wait for an HTTP request after initial
- connection establishment.
+ 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.
DOC_END
-NAME: persistent_request_timeout
-TYPE: time_t
-LOC: Config.Timeout.persistent_request
-DEFAULT: 2 minutes
+NAME: client_netmask
+TYPE: address
+LOC: Config.Addrs.client_netmask
+DEFAULT: 255.255.255.255
DOC_START
- How long to wait for the next HTTP request on a persistent
- connection after the previous request completes.
+ 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'.
DOC_END
-NAME: client_lifetime
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.lifetime
-DEFAULT: 1 day
+NAME: forward_log
+IFDEF: WIP_FWD_LOG
+TYPE: string
+DEFAULT: none
+LOC: Config.Log.forward
DOC_START
- The maximum amount of time a client (browser) is allowed to
- remain connected to the cache process. This protects the Cache
- from having a lot of sockets (and hence file descriptors) tied up
- in a CLOSE_WAIT state from remote clients that go away without
- properly shutting down (either because of a network failure or
- because of a poor client implementation). The default is one
- day, 1440 minutes.
+ Logs the server-side requests.
- NOTE: The default value is intended to be much larger than any
- client would ever need to be connected to your cache. You
- should probably change client_lifetime only as a last resort.
- If you seem to have many client connections tying up
- filedescriptors, we recommend first tuning the read_timeout,
- request_timeout, persistent_request_timeout and quick_abort values.
+ This is currently work in progress.
DOC_END
-NAME: half_closed_clients
+NAME: strip_query_terms
TYPE: onoff
-LOC: Config.onoff.half_closed_clients
+LOC: Config.onoff.strip_query_terms
DEFAULT: on
DOC_START
- Some clients may shutdown the sending side of their TCP
- connections, while leaving their receiving sides open. Sometimes,
- Squid can not tell the difference between a half-closed and a
- fully-closed TCP connection. By default, half-closed client
- connections are kept open until a read(2) or write(2) on the
- socket returns an error. Change this option to 'off' and Squid
- will immediately close client connections when read(2) returns
- "no more data to read."
+ By default, Squid strips query terms from requested URLs before
+ logging. This protects your user's privacy.
DOC_END
-NAME: pconn_timeout
-TYPE: time_t
-LOC: Config.Timeout.pconn
-DEFAULT: 1 minute
+NAME: buffered_logs
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.buffered_logs
DOC_START
- Timeout for idle persistent connections to servers and other
- proxies.
+ 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..).
DOC_END
-NAME: ident_timeout
-TYPE: time_t
-IFDEF: USE_IDENT
-LOC: Config.Timeout.ident
-DEFAULT: 10 seconds
+COMMENT_START
+ OPTIONS FOR FTP GATEWAYING
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: ftp_user
+TYPE: string
+DEFAULT: Squid@
+LOC: Config.Ftp.anon_user
DOC_START
- Maximum time to wait for IDENT lookups to complete.
+ If you want the anonymous login password to be more informative
+ (and enable the use of picky ftp servers), set this to something
+ reasonable for your domain, like wwwuser@somewhere.net
- If this is too high, and you enabled IDENT lookups from untrusted
- users, you might be susceptible to denial-of-service by having
- many ident requests going at once.
+ 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
+ (for example perl.com).
DOC_END
-NAME: shutdown_lifetime
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.shutdownLifetime
-DEFAULT: 30 seconds
+NAME: ftp_list_width
+TYPE: size_t
+DEFAULT: 32
+LOC: Config.Ftp.list_width
DOC_START
- When SIGTERM or SIGHUP is received, the cache is put into
- "shutdown pending" mode until all active sockets are closed.
- This value is the lifetime to set for all open descriptors
- during shutdown mode. Any active clients after this many
- seconds will receive a 'timeout' message.
+ 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.
DOC_END
-COMMENT_START
- ACCESS CONTROLS
- -----------------------------------------------------------------------------
-COMMENT_END
-
-NAME: acl
-TYPE: acl
-LOC: Config.aclList
-DEFAULT: none
+NAME: ftp_passive
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.passive
DOC_START
- Defining an Access List
-
- acl aclname acltype string1 ...
- acl aclname acltype "file" ...
+ If your firewall does not allow Squid to use passive
+ connections, turn off this option.
+DOC_END
- when using "file", the file should contain one item per line
+NAME: ftp_sanitycheck
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.sanitycheck
+DOC_START
+ For security and data integrity reasons Squid by default performs
+ sanity checks of the addresses of FTP data connections ensure the
+ data connection is to the requested server. If you need to allow
+ FTP connections to servers using another IP address for the data
+ connection turn this off.
+DOC_END
- acltype is one of the types described below
+NAME: ftp_telnet_protocol
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.telnet
+DOC_START
+ The FTP protocol is officially defined to use the telnet protocol
+ as transport channel for the control connection. However, many
+ implementations are broken and does not respect this aspect of
+ the FTP protocol.
+
+ If you have trouble accessing files with ASCII code 255 in the
+ path or similar problems involving this ASCII code you can
+ try setting this directive to off. If that helps, report to the
+ operator of the FTP server in question that their FTP server
+ is broken and does not follow the FTP standard.
+DOC_END
+
+COMMENT_START
+ OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: diskd_program
+TYPE: string
+DEFAULT: @DEFAULT_DISKD@
+LOC: Config.Program.diskd
+DOC_START
+ Specify the location of the diskd executable.
+ Note this is only useful if you have compiled in
+ diskd as one of the store io modules.
+DOC_END
+
+NAME: unlinkd_program
+IFDEF: USE_UNLINKD
+TYPE: string
+DEFAULT: @DEFAULT_UNLINKD@
+LOC: Config.Program.unlinkd
+DOC_START
+ Specify the location of the executable for file deletion process.
+DOC_END
+
+NAME: pinger_program
+TYPE: string
+DEFAULT: @DEFAULT_PINGER@
+LOC: Config.Program.pinger
+IFDEF: USE_ICMP
+DOC_START
+ Specify the location of the executable for the pinger process.
+DOC_END
+
+COMMENT_START
+ OPTIONS FOR URL REWRITING
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: url_rewrite_program redirect_program
+TYPE: wordlist
+LOC: Config.Program.redirect
+DEFAULT: none
+DOC_START
+ Specify the location of the executable for the URL rewriter.
+ Since they can perform almost any function there isn't one included.
+
+ For each requested URL rewriter will receive on line with the format
+
+ URL <SP> client_ip "/" fqdn <SP> user <SP> method <NL>
+
+ 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).
+
+ 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).
+
+ By default, a URL rewriter is not used.
+DOC_END
+
+NAME: url_rewrite_children redirect_children
+TYPE: int
+DEFAULT: 5
+LOC: Config.redirectChildren
+DOC_START
+ 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.
+DOC_END
+
+NAME: url_rewrite_concurrency redirect_concurrency
+TYPE: int
+DEFAULT: 0
+LOC: Config.redirectConcurrency
+DOC_START
+ 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.
+DOC_END
+
+NAME: url_rewrite_host_header redirect_rewrites_host_header
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.redir_rewrites_host
+DOC_START
+ 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.
+
+ WARNING: Entries are cached on the result of the URL rewriting
+ process, so be careful if you have domain-virtual hosts.
+DOC_END
+
+NAME: url_rewrite_access redirector_access
+TYPE: acl_access
+DEFAULT: none
+LOC: Config.accessList.redirector
+DOC_START
+ If defined, this access list specifies which requests are
+ sent to the redirector processes. By default all requests
+ are sent.
+DOC_END
+
+NAME: url_rewrite_bypass redirector_bypass
+TYPE: onoff
+LOC: Config.onoff.redirector_bypass
+DEFAULT: off
+DOC_START
+ When this is 'on', a request will not go through the
+ redirector if all redirectors are busy. If this is 'off'
+ 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
+ are not critical to your caching system. If you use
+ redirectors for access control, and you enable this option,
+ users may have access to pages they should not
+ be allowed to request.
+DOC_END
+
+COMMENT_START
+ OPTIONS FOR TUNING THE CACHE
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: request_header_max_size
+COMMENT: (KB)
+TYPE: b_size_t
+DEFAULT: 20 KB
+LOC: Config.maxRequestHeaderSize
+DOC_START
+ This specifies the maximum size for HTTP headers in a request.
+ Request headers are usually relatively small (about 512 bytes).
+ Placing a limit on the request header size will catch certain
+ bugs (for example with persistent connections) and possibly
+ buffer-overflow or denial-of-service attacks.
+DOC_END
+
+NAME: request_body_max_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 0 KB
+LOC: Config.maxRequestBodySize
+DOC_START
+ This specifies the maximum size for an HTTP request body.
+ In other words, the maximum size of a PUT/POST request.
+ A user who attempts to send a request with a body larger
+ 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.
+DOC_END
+
+NAME: refresh_pattern
+TYPE: refreshpattern
+LOC: Config.Refresh
+DEFAULT: none
+DOC_START
+ usage: refresh_pattern [-i] regex min percent max [options]
By default, regular expressions are CASE-SENSITIVE. To make
them case-insensitive, use the -i option.
- acl aclname src ip-address/netmask ... (clients IP address)
- acl aclname src addr1-addr2/netmask ... (range of addresses)
- acl aclname dst ip-address/netmask ... (URL host's IP address)
- acl aclname myip ip-address/netmask ... (local socket IP address)
+ 'Min' is the time (in minutes) an object without an explicit
+ expiry time should be considered fresh. The recommended
+ value is 0, any higher values may cause dynamic applications
+ to be erroneously cached unless the application designer
+ has taken the appropriate actions.
- 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.
- #
- # 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.
+ 'Percent' is a percentage of the objects age (time since last
+ modification age) an object without explicit expiry time
+ will be considered fresh.
- acl aclname srcdomain .foo.com ... # reverse lookup, client IP
- acl aclname dstdomain .foo.com ... # Destination server from URL
- acl aclname srcdom_regex [-i] xxx ... # regex matching client name
- acl aclname dstdom_regex [-i] xxx ... # regex matching server
- # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
- # based URL is used and no match is found. The name "none" is used
- # if the reverse lookup fails.
+ 'Max' is an upper limit on how long objects without an explicit
+ expiry time will be considered fresh.
- acl aclname http_status 200 301 500- 400-403 ... # status code in reply
+ options: override-expire
+ override-lastmod
+ reload-into-ims
+ ignore-reload
+ ignore-no-cache
+ ignore-no-store
+ ignore-private
+ ignore-auth
+ refresh-ims
- acl aclname time [day-abbrevs] [h1:m1-h2:m2]
- day-abbrevs:
- S - Sunday
- M - Monday
- T - Tuesday
- W - Wednesday
- H - Thursday
- F - Friday
- A - Saturday
- h1:m1 must be less than h2:m2
- acl aclname url_regex [-i] ^http:// ... # regex matching on whole URL
- acl aclname urlpath_regex [-i] \.gif$ ... # regex matching on URL path
- acl aclname port 80 70 21 ...
- acl aclname port 0-1024 ... # ranges allowed
- acl aclname myport 3128 ... # (local socket TCP port)
- acl aclname proto HTTP FTP ...
- acl aclname method GET POST ...
- acl aclname browser [-i] regexp ...
- # pattern match on User-Agent header (see also req_header below)
- acl aclname referer_regex [-i] regexp ...
- # pattern match on Referer header
- # Referer is highly unreliable, so use with care
- acl aclname ident username ...
- acl aclname ident_regex [-i] pattern ...
- # string match on ident output.
- # use REQUIRED to accept any non-null ident.
- acl aclname src_as number ...
- acl aclname dst_as number ...
- # Except for access control, AS numbers can be used for
- # routing of requests to specific caches. Here's an
- # example for routing all requests for AS#1241 and only
- # those to mycache.mydomain.net:
- # acl asexample dst_as 1241
- # cache_peer_access mycache.mydomain.net allow asexample
- # cache_peer_access mycache_mydomain.net deny all
+ override-expire enforces min age even if the server
+ sent a Expires: header. Doing this VIOLATES the HTTP
+ standard. Enabling this feature could make you liable
+ for problems which it causes.
- acl aclname proxy_auth [-i] username ...
- acl aclname proxy_auth_regex [-i] pattern ...
- # list of valid usernames
- # use REQUIRED to accept any valid username.
- #
- # NOTE: when a Proxy-Authentication header is sent but it is not
- # needed during ACL checking the username is NOT logged
- # in access.log.
- #
- # NOTE: proxy_auth requires a EXTERNAL authentication program
- # to check username/password combinations (see
- # auth_param directive).
- #
- # NOTE: proxy_auth can't be used in a transparent proxy as
- # the browser needs to be configured for using a proxy in order
- # to respond to proxy authentication.
+ override-lastmod enforces min age even on objects
+ that were modified recently.
- acl aclname snmp_community string ...
- # A community string to limit access to your SNMP Agent
- # Example:
- #
- # acl snmppublic snmp_community public
+ 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.
- acl aclname maxconn number
- # This will be matched when the client's IP address has
- # more than <number> HTTP connections established.
+ 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.
- acl aclname max_user_ip [-s] number
- # This will be matched when the user attempts to log in from more
- # than <number> different ip addresses. The authenticate_ip_ttl
- # parameter controls the timeout on the ip entries.
- # If -s is specified the limit is strict, denying browsing
- # from any further IP addresses until the ttl has expired. Without
- # -s Squid will just annoy the user by "randomly" denying requests.
- # (the counter is reset each time the limit is reached and a
- # request is denied)
- # NOTE: in acceleration mode or where there is mesh of child proxies,
- # clients may appear to come from multiple addresses if they are
- # going through proxy farms, so a limit of 1 may cause user problems.
+ 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
+ liable for problems which it causes.
+
+ ignore-private ignores any ``Cache-control: private''
+ headers received from a server. Doing this VIOLATES
+ the HTTP standard. Enabling this feature could make you
+ liable for problems which it causes.
+
+ ignore-auth caches responses to requests with authorization,
+ as if the originserver had sent ``Cache-control: public''
+ in the response header. Doing this VIOLATES the HTTP standard.
+ Enabling this feature could make you liable for problems which
+ it causes.
+
+ refresh-ims causes squid to contact the origin server
+ when a client issues an If-Modified-Since request. This
+ ensures that the client will receive an updated version
+ if one is available.
+
+ Basically a cached object is:
+
+ FRESH if expires < now, else STALE
+ STALE if age > max
+ FRESH if lm-factor < percent, else STALE
+ FRESH if age < min
+ else STALE
+
+ The refresh_pattern lines are checked in the order listed here.
+ The first entry which matches is used. If none of the entries
+ match the default will be used.
+
+ Note, you must uncomment all the default lines if you want
+ to change one. The default setting is only active if none is
+ used.
+
+Suggested default:
+NOCOMMENT_START
+refresh_pattern ^ftp: 1440 20% 10080
+refresh_pattern ^gopher: 1440 0% 1440
+refresh_pattern . 0 20% 4320
+NOCOMMENT_END
+DOC_END
+
+NAME: quick_abort_min
+COMMENT: (KB)
+TYPE: kb_int64_t
+DEFAULT: 16 KB
+LOC: Config.quickAbort.min
+DOC_NONE
+
+NAME: quick_abort_max
+COMMENT: (KB)
+TYPE: kb_int64_t
+DEFAULT: 16 KB
+LOC: Config.quickAbort.max
+DOC_NONE
+
+NAME: quick_abort_pct
+COMMENT: (percent)
+TYPE: int
+DEFAULT: 95
+LOC: Config.quickAbort.pct
+DOC_START
+ The cache by default continues downloading aborted requests
+ which are almost completed (less than 16 KB remaining). This
+ may be undesirable on slow (e.g. SLIP) links and/or very busy
+ caches. Impatient users may tie up file descriptors and
+ bandwidth by repeatedly requesting and immediately aborting
+ downloads.
+
+ When the user aborts a request, Squid will check the
+ quick_abort values to the amount of data transfered until
+ then.
+
+ If the transfer has less than 'quick_abort_min' KB remaining,
+ it will finish the retrieval.
+
+ If the transfer has more than 'quick_abort_max' KB remaining,
+ it will abort the retrieval.
+
+ If more than 'quick_abort_pct' of the transfer has completed,
+ it will finish the retrieval.
+
+ If you do not want any retrieval to continue after the client
+ has aborted, set both 'quick_abort_min' and 'quick_abort_max'
+ to '0 KB'.
+
+ If you want retrievals to always continue if they are being
+ cached set 'quick_abort_min' to '-1 KB'.
+DOC_END
- acl aclname req_mime_type mime-type1 ...
- # regex match against the mime type of the request generated
- # by the client. Can be used to detect file upload or some
- # types HTTP tunneling requests.
- # NOTE: This does NOT match the reply. You cannot use this
- # to match the returned file type.
+NAME: read_ahead_gap
+COMMENT: buffer-size
+TYPE: b_int64_t
+LOC: Config.readAheadGap
+DEFAULT: 16 KB
+DOC_START
+ The amount of data the cache will buffer ahead of what has been
+ sent to the client when retrieving an object from another server.
+DOC_END
- acl aclname req_header header-name [-i] any\.regex\.here
- # regex match against any of the known request headers. May be
- # thought of as a superset of "browser", "referer" and "mime-type"
- # ACLs.
+NAME: negative_ttl
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.negativeTtl
+DEFAULT: 5 minutes
+DOC_START
+ Time-to-Live (TTL) for failed requests. Certain types of
+ failures (such as "connection refused" and "404 Not Found") are
+ negatively-cached for a configurable amount of time. The
+ default is 5 minutes. Note that this is different from
+ negative caching of DNS lookups.
+DOC_END
- acl aclname rep_mime_type mime-type1 ...
- # regex match against the mime type of the reply received by
- # squid. Can be used to detect file download or some
- # types HTTP tunneling requests.
- # 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.
+NAME: positive_dns_ttl
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.positiveDnsTtl
+DEFAULT: 6 hours
+DOC_START
+ Upper limit on how long Squid will cache positive DNS responses.
+ Default is 6 hours (360 minutes). This directive must be set
+ larger than negative_dns_ttl.
+DOC_END
- acl aclname rep_header header-name [-i] any\.regex\.here
- # regex match against any of the known reply headers. May be
- # thought of as a superset of "browser", "referer" and "mime-type"
- # ACLs.
+NAME: negative_dns_ttl
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.negativeDnsTtl
+DEFAULT: 1 minutes
+DOC_START
+ Time-to-Live (TTL) for negative caching of failed DNS lookups.
+ This also sets the lower cache limit on positive lookups.
+ Minimum value is 1 second, and it is not recommendable to go
+ much below 10 seconds.
+DOC_END
- acl acl_name external class_name [arguments...]
- # external ACL lookup via a helper class defined by the
- # external_acl_type directive.
+NAME: range_offset_limit
+COMMENT: (bytes)
+TYPE: b_int64_t
+LOC: Config.rangeOffsetLimit
+DEFAULT: 0 KB
+DOC_START
+ 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.
- acl aclname user_cert attribute values...
- # match against attributes in a user SSL certificate
- # attribute is one of DN/C/O/CN/L/ST
+ 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.
- 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
+ A value of -1 causes Squid to always fetch the object from the
+ beginning so it may cache the result. (2.0 style)
- acl aclname ext_user username ...
- acl aclname ext_user_regex [-i] pattern ...
- # string match on username returned by external acl helper
- # use REQUIRED to accept any non-null user name.
+ A value of 0 causes Squid to never fetch more than the
+ client requested. (default)
+DOC_END
-Examples:
-acl macaddress arp 09:00:2b:23:45:67
-acl myexample dst_as 1241
-acl password proxy_auth REQUIRED
-acl fileupload req_mime_type -i ^multipart/form-data$
-acl javascript rep_mime_type -i ^application/x-javascript$
+NAME: minimum_expiry_time
+COMMENT: (seconds)
+TYPE: time_t
+LOC: Config.minimum_expiry_time
+DEFAULT: 60 seconds
+DOC_START
+ The minimum caching time according to (Expires - Date)
+ Headers Squid honors if the object can't be revalidated
+ defaults to 60 seconds. In reverse proxy enorinments it
+ might be desirable to honor shorter object lifetimes. It
+ is most likely better to make your server return a
+ meaningful Last-Modified header however. In ESI environments
+ where page fragments often have short lifetimes, this will
+ often be best set to 0.
+DOC_END
-NOCOMMENT_START
-#Recommended minimum configuration:
-acl all src 0.0.0.0/0.0.0.0
-acl manager proto cache_object
-acl localhost src 127.0.0.1/255.255.255.255
-acl to_localhost dst 127.0.0.0/8
-acl SSL_ports port 443
-acl Safe_ports port 80 # http
-acl Safe_ports port 21 # ftp
-acl Safe_ports port 443 # https
-acl Safe_ports port 70 # gopher
-acl Safe_ports port 210 # wais
-acl Safe_ports port 1025-65535 # unregistered ports
-acl Safe_ports port 280 # http-mgmt
-acl Safe_ports port 488 # gss-http
-acl Safe_ports port 591 # filemaker
-acl Safe_ports port 777 # multiling http
-acl CONNECT method CONNECT
-NOCOMMENT_END
+NAME: store_avg_object_size
+COMMENT: (kbytes)
+TYPE: kb_size_t
+DEFAULT: 13 KB
+LOC: Config.Store.avgObjectSize
+DOC_START
+ Average object size, used to estimate number of objects your
+ cache can hold. The default is 13 KB.
DOC_END
-NAME: http_access
+NAME: store_objects_per_bucket
+TYPE: int
+DEFAULT: 20
+LOC: Config.Store.objectsPerBucket
+DOC_START
+ Target number of objects per bucket in the store hash table.
+ Lowering this value increases the total number of buckets and
+ also the storage maintenance rate. The default is 20.
+DOC_END
+
+COMMENT_START
+ HTTP OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: broken_posts
TYPE: acl_access
-LOC: Config.accessList.http
DEFAULT: none
-DEFAULT_IF_NONE: deny all
+LOC: Config.accessList.brokenPosts
DOC_START
- Allowing or Denying access based on defined access lists
+ A list of ACL elements which, if matched, causes Squid to send
+ an extra CRLF pair after the body of a PUT/POST request.
- Access to the HTTP port:
- http_access allow|deny [!]aclname ...
+ Some HTTP servers has broken implementations of PUT/POST,
+ and rely on an extra CRLF pair sent by some WWW clients.
- NOTE on default values:
+ Quote from RFC2616 section 4.1 on this matter:
- If there are no "access" lines present, the default is to deny
- the request.
+ Note: certain buggy HTTP/1.0 client implementations generate an
+ extra CRLF's after a POST request. To restate what is explicitly
+ forbidden by the BNF, an HTTP/1.1 client must not preface or follow
+ a request with an extra CRLF.
- If none of the "access" lines cause a match, the default is the
- opposite of the last line in the list. If the last line was
- deny, the default is allow. Conversely, if the last line
- is allow, the default will be deny. For these reasons, it is a
- good idea to have an "deny all" or "allow all" entry at the end
- of your access lists to avoid potential confusion.
+Example:
+ acl buggy_server url_regex ^http://....
+ broken_posts allow buggy_server
+DOC_END
-NOCOMMENT_START
-#Recommended minimum configuration:
-#
-# Only allow cachemgr access from localhost
-http_access allow manager localhost
-http_access deny manager
-# Deny requests to unknown ports
-http_access deny !Safe_ports
-# Deny CONNECT to other than SSL ports
-http_access deny CONNECT !SSL_ports
-#
-# 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
-#http_access deny to_localhost
-#
-# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
+NAME: via
+IFDEF: HTTP_VIOLATIONS
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.via
+DOC_START
+ If set (default), Squid will include a Via header in requests and
+ replies as required by RFC2616.
+DOC_END
-# Example rule allowing access from your local networks. Adapt
-# to list your (internal) IP networks from where browsing should
-# be allowed
-#acl our_networks src 192.168.1.0/24 192.168.2.0/24
-#http_access allow our_networks
+NAME: ie_refresh
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.ie_refresh
+DEFAULT: off
+DOC_START
+ Microsoft Internet Explorer up until version 5.5 Service
+ Pack 1 has an issue with transparent proxies, wherein it
+ is impossible to force a refresh. Turning this on provides
+ a partial fix to the problem, by causing all IMS-REFRESH
+ requests from older IE versions to check the origin server
+ for fresh content. This reduces hit ratio by some amount
+ (~10% in my experience), but allows users to actually get
+ fresh content when they want it. Note because Squid
+ cannot tell if the user is using 5.5 or 5.5SP1, the behavior
+ of 5.5 is unchanged from old versions of Squid (i.e. a
+ forced refresh is impossible). Newer versions of IE will,
+ hopefully, continue to have the new behavior and will be
+ handled based on that assumption. This option defaults to
+ the old Squid behavior, which is better for hit ratios but
+ worse for clients using IE, if they need to be able to
+ force fresh content.
+DOC_END
-# And finally deny all other access to this proxy
-http_access deny all
-NOCOMMENT_END
+NAME: vary_ignore_expire
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.vary_ignore_expire
+DEFAULT: off
+DOC_START
+ Many HTTP servers supporting Vary gives such objects
+ immediate expiry time with no cache-control header
+ when requested by a HTTP/1.0 client. This option
+ enables Squid to ignore such expiry times until
+ HTTP/1.1 is fully implemented.
+ WARNING: This may eventually cause some varying
+ objects not intended for caching to get cached.
DOC_END
-NAME: http_reply_access
-TYPE: acl_access
-LOC: Config.accessList.reply
+NAME: extension_methods
+TYPE: wordlist
+LOC: Config.ext_methods
DEFAULT: none
DOC_START
- Allow replies to client requests. This is complementary to http_access.
-
- http_reply_access allow|deny [!] aclname ...
+ Squid only knows about standardized HTTP request methods.
+ You can add up to 20 additional "extension" methods here.
+DOC_END
- NOTE: if there are no access lines present, the default is to allow
- all replies
+NAME: request_entities
+TYPE: onoff
+LOC: Config.onoff.request_entities
+DEFAULT: off
+DOC_START
+ Squid defaults to deny GET and HEAD requests with request entities,
+ as the meaning of such requests are undefined in the HTTP standard
+ even if not explicitly forbidden.
- 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
- with an "allow all" or "deny all" entry.
+ Set this directive to on if you have clients which insists
+ on sending request entities in GET or HEAD requests. But be warned
+ that there is server software (both proxies and web servers) which
+ can fail to properly process this kind of request which may make you
+ vulnerable to cache pollution attacks if enabled.
DOC_END
-NAME: icp_access
-TYPE: acl_access
-LOC: Config.accessList.icp
+NAME: request_header_access
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_access[]
+LOC: Config.request_header_access
DEFAULT: none
-DEFAULT_IF_NONE: deny all
DOC_START
- Allowing or Denying access to the ICP port based on defined
- access lists
-
- icp_access allow|deny [!]aclname ...
+ Usage: request_header_access header_name allow|deny [!]aclname ...
- See http_access for details
+ WARNING: Doing this VIOLATES the HTTP standard. Enabling
+ this feature could make you liable for problems which it
+ causes.
-NOCOMMENT_START
-#Allow ICP queries from everyone
-icp_access allow all
-NOCOMMENT_END
-DOC_END
+ 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.
-NAME: htcp_access
-IFDEF: USE_HTCP
-TYPE: acl_access
-LOC: Config.accessList.htcp
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-DOC_START
- Allowing or Denying access to the HTCP port based on defined
- access lists
+ This option only applies to request headers, i.e., from the
+ client to the server.
- htcp_access allow|deny [!]aclname ...
+ 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'.
- See http_access for details
+ For example, to achieve the same behavior as the old
+ 'http_anonymizer standard' option, you should use:
-#Allow HTCP queries from everyone
-htcp_access allow all
-DOC_END
+ 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
-NAME: htcp_clr_access
-IFDEF: USE_HTCP
-TYPE: acl_access
-LOC: Config.accessList.htcp_clr
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-DOC_START
- Allowing or Denying access to purge content using HTCP based
- on defined access lists
+ Or, to reproduce the old 'http_anonymizer paranoid' feature
+ you should use:
- htcp_clr_access allow|deny [!]aclname ...
+ 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 Proxy-Connection allow all
+ request_header_access All deny all
- See http_access for details
+ although many of those are HTTP reply headers, and so should be
+ controlled with the reply_header_access directive.
-#Allow HTCP CLR requests from trusted peers
-acl htcp_clr_peer src 172.16.1.2
-htcp_clr_access allow htcp_clr_peer
+ By default, all headers are allowed (no anonymizing is
+ performed).
DOC_END
-NAME: miss_access
-TYPE: acl_access
-LOC: Config.accessList.miss
+NAME: reply_header_access
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_access[]
+LOC: Config.reply_header_access
DEFAULT: none
DOC_START
- Use to force your neighbors to use you as a sibling instead of
- a parent. For example:
+ Usage: reply_header_access header_name allow|deny [!]aclname ...
- acl localclients src 172.16.0.0/16
- miss_access allow localclients
- miss_access deny !localclients
+ WARNING: Doing this VIOLATES the HTTP standard. Enabling
+ this feature could make you liable for problems which it
+ causes.
- This means only your local clients are allowed to fetch
- MISSES and all other clients can only fetch HITS.
+ This option only applies to reply headers, i.e., from the
+ server to the client.
- By default, allow all clients who passed the http_access rules
- to fetch MISSES from us.
+ This is the same as request_header_access, but in the other
+ direction.
-NOCOMMENT_START
-#Default setting:
-# miss_access allow all
-NOCOMMENT_END
-DOC_END
+ 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.
-NAME: cache_peer_access
-TYPE: peer_access
-DEFAULT: none
-LOC: none
-DOC_START
- Similar to 'cache_peer_domain' but provides more flexibility by
- using ACL elements.
+ 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'.
- cache_peer_access cache-host allow|deny [!]aclname ...
+ For example, to achieve the same behavior as the old
+ 'http_anonymizer standard' option, you should use:
- 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://www.squid-cache.org/FAQ/FAQ-10.html).
-DOC_END
+ 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
-NAME: ident_lookup_access
-TYPE: acl_access
-IFDEF: USE_IDENT
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-LOC: Config.accessList.identLookup
-DOC_START
- A list of ACL elements which, if matched, cause an ident
- (RFC 931) lookup to be performed for this request. For
- example, you might choose to always perform ident lookups
- for your main multi-user Unix boxes, but not for your Macs
- and PCs. By default, ident lookups are not performed for
- any requests.
+ Or, to reproduce the old 'http_anonymizer paranoid' feature
+ you should use:
- To enable ident lookups for specific client addresses, you
- can follow this example:
+ reply_header_access Allow allow all
+ reply_header_access Authorization allow all
+ reply_header_access WWW-Authenticate allow all
+ reply_header_access Proxy-Authorization allow all
+ reply_header_access Proxy-Authenticate allow all
+ reply_header_access Cache-Control allow all
+ reply_header_access Content-Encoding allow all
+ reply_header_access Content-Length allow all
+ reply_header_access Content-Type allow all
+ reply_header_access Date allow all
+ reply_header_access Expires allow all
+ reply_header_access Host allow all
+ reply_header_access If-Modified-Since allow all
+ reply_header_access Last-Modified allow all
+ reply_header_access Location allow all
+ reply_header_access Pragma allow all
+ reply_header_access Accept allow all
+ reply_header_access Accept-Charset allow all
+ reply_header_access Accept-Encoding allow all
+ reply_header_access Accept-Language allow all
+ reply_header_access Content-Language allow all
+ reply_header_access Mime-Version allow all
+ reply_header_access Retry-After allow all
+ reply_header_access Title allow all
+ reply_header_access Connection allow all
+ reply_header_access Proxy-Connection allow all
+ reply_header_access All deny all
- acl ident_aware_hosts src 198.168.1.0/255.255.255.0
- ident_lookup_access allow ident_aware_hosts
- ident_lookup_access deny all
+ although the HTTP request headers won't be usefully controlled
+ by this directive -- see request_header_access for details.
- Only src type ACL checks are fully supported. A src_domain
- ACL might work at times, but it will not always provide
- the correct result.
+ By default, all headers are allowed (no anonymizing is
+ performed).
DOC_END
-NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
-TYPE: acl_tos
+NAME: header_replace
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_replace[]
+LOC: Config.request_header_access
DEFAULT: none
-LOC: Config.accessList.outgoing_tos
-DOC_START
- Allows you to select a TOS/Diffserv value to mark outgoing
- connections with, based on the username or source address
- making the request.
+DOC_START
+ Usage: header_replace header_name message
+ Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
- tcp_outgoing_tos ds-field [!]aclname ...
+ This option allows you to change the contents of headers
+ denied with header_access above, by replacing them with
+ some fixed string. This replaces the old fake_user_agent
+ option.
- Example where normal_service_net uses the TOS value 0x00
- and normal_service_net uses 0x20
+ This only applies to request headers, not reply headers.
- acl normal_service_net src 10.0.0.0/255.255.255.0
- acl good_service_net src 10.0.1.0/255.255.255.0
- tcp_outgoing_tos 0x00 normal_service_net 0x00
- tcp_outgoing_tos 0x20 good_service_net
+ By default, headers are removed if denied.
+DOC_END
- TOS/DSCP values really only have local significance - so you should
- know what you're specifying. For more information, see RFC2474 and
- RFC3260.
+NAME: relaxed_header_parser
+COMMENT: on|off|warn
+TYPE: tristate
+LOC: Config.onoff.relaxed_header_parser
+DEFAULT: on
+DOC_START
+ In the default "on" setting Squid accepts certain forms
+ of non-compliant HTTP messages where it is unambiguous
+ what the sending application intended even if the message
+ is not correctly formatted. The messages is then normalized
+ to the correct form when forwarded by Squid.
- 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 values 0 - 63 is usable as the two highest bits
- have been redefined for use by ECN (RFC3168).
+ If set to "warn" then a warning will be emitted in cache.log
+ each time such HTTP error is encountered.
- Processing proceeds in the order specified, and stops at first fully
- matching line.
+ If set to "off" then such HTTP errors will cause the request
+ or response to be rejected.
+DOC_END
- 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_persisten_connections
- to off when using this directive in such configurations.
+COMMENT_START
+ TIMEOUTS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: forward_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.forward
+DEFAULT: 4 minutes
+DOC_START
+ This parameter specifies how long Squid should at most attempt in
+ finding a forwarding path for the request before giving up.
DOC_END
-NAME: clientside_tos
-TYPE: acl_tos
-DEFAULT: none
-LOC: Config.accessList.clientside_tos
+NAME: connect_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.connect
+DEFAULT: 1 minute
DOC_START
- Allows you to select a TOS/Diffserv value to mark client-side
- connections with, based on the username or source address
- making the request.
+ This parameter specifies how long to wait for the TCP connect to
+ the requested server or peer to complete before Squid should
+ attempt to find another path where to forward the request.
DOC_END
-NAME: tcp_outgoing_address
-TYPE: acl_address
-DEFAULT: none
-LOC: Config.accessList.outgoing_address
+NAME: peer_connect_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.peer_connect
+DEFAULT: 30 seconds
DOC_START
- Allows you to map requests to different outgoing IP addresses
- based on the username or source address of the user making
- the request.
+ This parameter specifies how long to wait for a pending TCP
+ connection to a peer cache. The default is 30 seconds. You
+ may also set different timeout values for individual neighbors
+ with the 'connect-timeout' option on a 'cache_peer' line.
+DOC_END
- tcp_outgoing_address ipaddr [[!]aclname] ...
+NAME: read_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.read
+DEFAULT: 15 minutes
+DOC_START
+ The read_timeout is applied on server-side 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.
+DOC_END
- 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.
+NAME: request_timeout
+TYPE: time_t
+LOC: Config.Timeout.request
+DEFAULT: 5 minutes
+DOC_START
+ How long to wait for an HTTP request after initial
+ connection establishment.
+DOC_END
- acl normal_service_net src 10.0.0.0/255.255.255.0
- acl good_service_net src 10.0.1.0/255.255.255.0
- tcp_outgoing_address 10.0.0.1 normal_service_net
- tcp_outgoing_address 10.0.0.2 good_service_net
- tcp_outgoing_address 10.0.0.3
+NAME: persistent_request_timeout
+TYPE: time_t
+LOC: Config.Timeout.persistent_request
+DEFAULT: 2 minutes
+DOC_START
+ How long to wait for the next HTTP request on a persistent
+ connection after the previous request completes.
+DOC_END
- Processing proceeds in the order specified, and stops at first fully
- matching line.
+NAME: client_lifetime
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.lifetime
+DEFAULT: 1 day
+DOC_START
+ The maximum amount of time a client (browser) is allowed to
+ remain connected to the cache process. This protects the Cache
+ from having a lot of sockets (and hence file descriptors) tied up
+ in a CLOSE_WAIT state from remote clients that go away without
+ properly shutting down (either because of a network failure or
+ because of a poor client implementation). The default is one
+ day, 1440 minutes.
- 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.
+ NOTE: The default value is intended to be much larger than any
+ client would ever need to be connected to your cache. You
+ should probably change client_lifetime only as a last resort.
+ If you seem to have many client connections tying up
+ filedescriptors, we recommend first tuning the read_timeout,
+ request_timeout, persistent_request_timeout and quick_abort values.
DOC_END
-NAME: reply_header_max_size
-COMMENT: (KB)
-TYPE: b_size_t
-DEFAULT: 20 KB
-LOC: Config.maxReplyHeaderSize
+NAME: half_closed_clients
+TYPE: onoff
+LOC: Config.onoff.half_closed_clients
+DEFAULT: on
DOC_START
- This specifies the maximum size for HTTP headers in a reply.
- Reply headers are usually relatively small (about 512 bytes).
- Placing a limit on the reply header size will catch certain
- bugs (for example with persistent connections) and possibly
- buffer-overflow or denial-of-service attacks.
+ Some clients may shutdown the sending side of their TCP
+ connections, while leaving their receiving sides open. Sometimes,
+ Squid can not tell the difference between a half-closed and a
+ fully-closed TCP connection. By default, half-closed client
+ connections are kept open until a read(2) or write(2) on the
+ socket returns an error. Change this option to 'off' and Squid
+ will immediately close client connections when read(2) returns
+ "no more data to read."
DOC_END
-NAME: reply_body_max_size
-COMMENT: size [acl acl...]
-TYPE: acl_b_size_t
-DEFAULT: none
-LOC: Config.ReplyBodySize
+NAME: pconn_timeout
+TYPE: time_t
+LOC: Config.Timeout.pconn
+DEFAULT: 1 minute
DOC_START
- This option specifies the maximum size of a reply body. It can be
- used to prevent users from downloading very large files, such as
- MP3's and movies. When the reply headers are received, the
- reply_body_max_size lines are processed, and the first line where
- all (if any) listed ACLs are true is used as the maximum body size
- for this reply.
-
- This size is checked twice. First when we get the reply headers,
- we check the content-length value. If the content length value exists
- and is larger than the allowed size, the request is denied and the
- user receives an error message that says "the request or reply
- is too large." If there is no content-length, and the reply
- size exceeds this limit, the client's connection is just closed
- and they will receive a partial reply.
-
- WARNING: downstream caches probably can not detect a partial reply
- if there is no content-length header, so they will cache
- partial responses and give them out as hits. You should NOT
- use this option if you have downstream caches.
+ Timeout for idle persistent connections to servers and other
+ proxies.
+DOC_END
- WARNING: A maximum size smaller than the size of squid's error messages
- will cause an infinite loop and crash squid. Ensure that the smallest
- non-zero value you use is greater that the maximum header size plus
- the size of your largest error page.
+NAME: ident_timeout
+TYPE: time_t
+IFDEF: USE_IDENT
+LOC: Config.Timeout.ident
+DEFAULT: 10 seconds
+DOC_START
+ Maximum time to wait for IDENT lookups to complete.
- If you set this parameter none (the default), there will be
- no limit imposed.
+ If this is too high, and you enabled IDENT lookups from untrusted
+ users, you might be susceptible to denial-of-service by having
+ many ident requests going at once.
DOC_END
-NAME: log_access
-TYPE: acl_access
-LOC: Config.accessList.log
-DEFAULT: none
-COMMENT: allow|deny acl acl...
+NAME: shutdown_lifetime
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.shutdownLifetime
+DEFAULT: 30 seconds
DOC_START
- 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.
+ When SIGTERM or SIGHUP is received, the cache is put into
+ "shutdown pending" mode until all active sockets are closed.
+ This value is the lifetime to set for all open descriptors
+ during shutdown mode. Any active clients after this many
+ seconds will receive a 'timeout' message.
DOC_END
COMMENT_START
NOCOMMENT_END
DOC_END
-NAME: redirector_bypass
-TYPE: onoff
-LOC: Config.onoff.redirector_bypass
-DEFAULT: off
-DOC_START
- When this is 'on', a request will not go through the
- redirector if all redirectors are busy. If this is 'off'
- 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
- are not critical to your caching system. If you use
- redirectors for access control, and you enable this option,
- users may have access to pages they should not
- be allowed to request.
-DOC_END
-
NAME: chroot
TYPE: string
LOC: Config.chroot_dir
projects / thirdparty / squid.git / commitdiff
