From: hno <> Date: Tue, 4 Sep 2007 23:39:56 +0000 (+0000) Subject: More squid.conf reordering to get the dependencies between options sorted proper X-Git-Tag: SQUID_3_0_RC1~67 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=41bd17a47f74cefe841f7025291b655eeead07f4;p=thirdparty%2Fsquid.git More squid.conf reordering to get the dependencies between options sorted proper this patch also adds an automatic dependency verification to cf_gen, reducing the risk of this kind of confusing ordering of the directives. driven by the new cf.data.depend file listing the directive types and their dependencies. --- diff --git a/src/Makefile.am b/src/Makefile.am index 05eb786d93..46b50792f6 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -1,7 +1,7 @@ # # Makefile for the Squid Object Cache server # -# $Id: Makefile.am,v 1.187 2007/08/26 21:04:32 hno Exp $ +# $Id: Makefile.am,v 1.188 2007/09/04 17:39:56 hno Exp $ # # Uncomment and customize the following to suit your needs: # @@ -1023,7 +1023,7 @@ squid.conf.default: cf_parser.h $(SHELL) -c "test -f squid.conf.default || ./cf_gen cf.data" cf_parser.h: cf.data cf_gen$(EXEEXT) - ./cf_gen cf.data + ./cf_gen cf.data $(srcdir)/cf.data.depend cf_gen_defines.h: $(srcdir)/cf_gen_defines $(srcdir)/cf.data.pre $(AWK) -f $(srcdir)/cf_gen_defines <$(srcdir)/cf.data.pre >cf_gen_defines.h diff --git a/src/cf.data.depend b/src/cf.data.depend new file mode 100644 index 0000000000..dfce077457 --- /dev/null +++ b/src/cf.data.depend @@ -0,0 +1,50 @@ +# type dependencies +access_log acl logformat +acl external_acl_type auth_param +acl_access acl +acl_address acl +acl_b_size_t acl +acl_tos acl +address +authparam +b_int64_t +b_size_t +cachedir cache_replacement_policy +cachemgrpasswd +debug +delay_pool_access acl delay_class +delay_pool_class delay_pools +delay_pool_count +delay_pool_rates delay_class +denyinfo acl +eol +externalAclHelper auth_param +hostdomain cache_peer +hostdomaintype cache_peer +http_header_access +http_header_replace +http_port_list +https_port_list +icap_access_type icap_class acl +icap_class_type icap_service +icap_service_type +int +kb_int64_t +kb_size_t +logformat +onoff +peer +peer_access cache_peer acl +refreshpattern +removalpolicy +size_t +sockaddr_in_list +string +string +time_t +tristate +uri_whitespace +ushort +wccp2_service +wccp2_service_info +wordlist diff --git a/src/cf.data.pre b/src/cf.data.pre index ec62d09252..a7eb3f2c57 100644 --- a/src/cf.data.pre +++ b/src/cf.data.pre @@ -1,6 +1,6 @@ # -# $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/ # ---------------------------------------------------------- @@ -239,2902 +239,2933 @@ DOC_START 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 +#auth_param negotiate children 5 +#auth_param negotiate keep_alive on +#auth_param ntlm program +#auth_param ntlm children 5 +#auth_param ntlm keep_alive on +#auth_param digest program +#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 +#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 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 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 + 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 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 - h Request header. Optional header name argument - on the format header[:[separator]element] - 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 - a %Ss/%03Hs %a %Ss/%03Hs %h] [%a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %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 [ [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 - '. + 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 client_ip "/" fqdn user method + 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 -#auth_param negotiate children 5 -#auth_param negotiate keep_alive on -#auth_param ntlm program -#auth_param ntlm children 5 -#auth_param ntlm keep_alive on -#auth_param digest program -#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 -#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 - 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 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 + h Request header. Optional header name argument + on the format header[:[separator]element] + 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 + a %Ss/%03Hs %a %Ss/%03Hs %h] [%a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %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 [ [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 + '. +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 client_ip "/" fqdn user method + + 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 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 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 @@ -5232,22 +5263,6 @@ coredump_dir @DEFAULT_SWAP_DIR@ 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 diff --git a/src/cf_gen.cc b/src/cf_gen.cc index c4cc7aa857..17a5407132 100644 --- a/src/cf_gen.cc +++ b/src/cf_gen.cc @@ -1,6 +1,6 @@ /* - * $Id: cf_gen.cc,v 1.60 2007/08/27 13:37:02 hno Exp $ + * $Id: cf_gen.cc,v 1.61 2007/09/04 17:39:57 hno Exp $ * * DEBUG: none Generate squid.conf.default and cf_parser.h * AUTHOR: Max Okumoto @@ -55,6 +55,7 @@ #define MAX_LINE 1024 /* longest configuration line */ #define _PATH_PARSER "cf_parser.h" #define _PATH_SQUID_CONF "squid.conf.default" +#define _PATH_CF_DEPEND "cf.data.depend" enum State { sSTART, @@ -101,8 +102,22 @@ typedef struct Entry Entry; +typedef struct TypeDep +{ + char *name; + + TypeDep *next; +} TypeDep; + +typedef struct Type +{ + char *name; + TypeDep *depend; -static const char WS[] = " \t"; + struct Type *next; +} Type; + +static const char WS[] = " \t\n"; static int gen_default(Entry *, FILE *); static void gen_parse(Entry *, FILE *); static void gen_parse_entry(Entry *entry, FILE *fp); @@ -124,6 +139,31 @@ lineAdd(Line ** L, const char *str) (*L)->data = xstrdup(str); } +static void +checkDepend(const char *directive, const char *name, const Type *types, const Entry *entries) +{ + const Type *type; + for (type = types; type; type = type->next) { + const TypeDep *dep; + if (strcmp(type->name, name) != 0) + continue; + for (dep = type->depend; dep; dep = dep->next) { + const Entry *entry; + for (entry = entries; entry; entry = entry->next) { + if (strcmp(entry->name, dep->name) == 0) + break; + } + if (!entry) { + fprintf(stderr, "ERROR: '%s' (%s) depends on '%s'\n", directive, name, dep->name); + exit(1); + } + } + return; + } + fprintf(stderr, "ERROR: Dependencies for cf.data type '%s' used in '%s' not defined\n", name, directive); + exit(1); +} + int main(int argc, char *argv[]) { @@ -131,9 +171,11 @@ main(int argc, char *argv[]) char *input_filename = argv[1]; const char *output_filename = _PATH_PARSER; const char *conf_filename = _PATH_SQUID_CONF; + const char *type_depend = argv[2]; int linenum = 0; Entry *entries = NULL; Entry *curr = NULL; + Type *types = NULL; enum State state; int rc = 0; char *ptr = NULL; @@ -144,6 +186,34 @@ main(int argc, char *argv[]) const char *rmode = "r"; #endif + char buff[MAX_LINE]; + + + /*-------------------------------------------------------------------* + * Parse type dependencies + *-------------------------------------------------------------------*/ + if ((fp = fopen(type_depend, rmode)) == NULL) { + perror(input_filename); + exit(1); + } + + while ((NULL != fgets(buff, MAX_LINE, fp))) { + const char *type = strtok(buff, WS); + const char *dep; + if (!type || type[0] == '#') + continue; + Type *t = (Type *)xcalloc(1, sizeof(*t)); + t->name = xstrdup(type); + while ((dep = strtok(NULL, WS)) != NULL) { + TypeDep *d = (TypeDep *)xcalloc(1, sizeof(*dep)); + d->name = xstrdup(dep); + d->next = t->depend; + t->depend = d; + } + t->next = types; + types = t; + } + fclose(fp); /*-------------------------------------------------------------------* * Parse input file @@ -164,7 +234,6 @@ main(int argc, char *argv[]) state = sSTART; while (feof(fp) == 0 && state != sEXIT) { - char buff[MAX_LINE]; char *t; if (NULL == fgets(buff, MAX_LINE, fp)) @@ -261,6 +330,7 @@ main(int argc, char *argv[]) *(ptr + strlen(ptr) - 2) = '\0'; } + checkDepend(curr->name, ptr, types, entries); curr->type = xstrdup(ptr); } else if (!strncmp(buff, "IFDEF:", 6)) { if ((ptr = strtok(buff + 6, WS)) == NULL) {