--------------------- PatchSet 11554 Date: 2007/08/07 12:05:02 Author: adrian Branch: HEAD Tag: (none) Log: More cf.data.pre reorganisation - mostly focusing on reducing the "misc" group. Members: src/cf.data.pre:1.406->1.407 Index: squid/src/cf.data.pre =================================================================== RCS file: /cvsroot/squid/squid/src/cf.data.pre,v retrieving revision 1.406 retrieving revision 1.407 diff -u -r1.406 -r1.407 --- squid/src/cf.data.pre 6 Aug 2007 13:40:46 -0000 1.406 +++ squid/src/cf.data.pre 7 Aug 2007 12:05:02 -0000 1.407 @@ -1,6 +1,6 @@ # -# $Id: cf.data.pre,v 1.406 2007/08/06 13:40:46 hno Exp $ +# $Id: cf.data.pre,v 1.407 2007/08/07 12:05:02 adrian Exp $ # # SQUID Web Proxy Cache http://www.squid-cache.org/ # ---------------------------------------------------------- @@ -229,6 +229,22 @@ DOC_END +NAME: htcp_port +IFDEF: USE_HTCP +TYPE: ushort +DEFAULT: 4827 +LOC: Config.Port.htcp +DOC_START + The port number where Squid sends and receives HTCP queries to + and from neighbor caches. Default is 4827. To disable use + "0". +DOC_END + +COMMENT_START + SSL OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + NAME: ssl_unclean_shutdown IFDEF: USE_SSL TYPE: onoff @@ -339,84 +355,6 @@ option to allow it to query interactively for the passphrase. DOC_END -NAME: icp_port udp_port -TYPE: ushort -DEFAULT: @DEFAULT_ICP_PORT@ -LOC: Config.Port.icp -DOC_START - The port number where Squid sends and receives ICP queries to - and from neighbor caches. Default is 3130. To disable use - "0". May be overridden with -u on the command line. -DOC_END - -NAME: htcp_port -IFDEF: USE_HTCP -TYPE: ushort -DEFAULT: 4827 -LOC: Config.Port.htcp -DOC_START - The port number where Squid sends and receives HTCP queries to - and from neighbor caches. Default is 4827. To disable use - "0". -DOC_END - -NAME: mcast_groups -TYPE: wordlist -LOC: Config.mcast_group_list -DEFAULT: none -DOC_START - This tag specifies a list of multicast groups which your server - should join to receive multicasted ICP queries. - - NOTE! Be very careful what you put here! Be sure you - understand the difference between an ICP _query_ and an ICP - _reply_. This option is to be set only if you want to RECEIVE - multicast queries. Do NOT set this option to SEND multicast - ICP (use cache_peer for that). ICP replies are always sent via - unicast, so this option does not affect whether or not you will - receive replies from multicast group members. - - You must be very careful to NOT use a multicast address which - is already in use by another group of caches. - - If you are unsure about multicast, please read the Multicast - chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/). - - Usage: mcast_groups 239.128.16.128 224.0.1.20 - - By default, Squid doesn't listen on any multicast groups. -DOC_END - -NAME: udp_incoming_address -TYPE: address -LOC:Config.Addrs.udp_incoming -DEFAULT: 0.0.0.0 -DOC_NONE - -NAME: udp_outgoing_address -TYPE: address -LOC: Config.Addrs.udp_outgoing -DEFAULT: 255.255.255.255 -DOC_START - udp_incoming_address is used for the ICP socket receiving packets - from other caches. - udp_outgoing_address is used for ICP packets sent out to other - caches. - - The default behavior is to not bind to any specific address. - - A udp_incoming_address value of 0.0.0.0 indicates Squid - should listen for UDP messages on all available interfaces. - - If udp_outgoing_address is set to 255.255.255.255 (the default) - it will use the same socket as udp_incoming_address. Only - change this if you want to have ICP queries sent using another - address than where this Squid listens for ICP queries from other - caches. - - NOTE, udp_incoming_address and udp_outgoing_address can not - have the same value since they both use port 3130. -DOC_END COMMENT_START OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM @@ -856,35 +794,8 @@ NOCOMMENT_END DOC_END -NAME: cache_vary -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.cache_vary -DOC_START - Set to off to disable caching of Vary:in objects. -DOC_END - -NAME: broken_vary_encoding -TYPE: acl_access -DEFAULT: none -LOC: Config.accessList.vary_encoding -DOC_START - Many servers have broken support for on-the-fly Content-Encoding, - returning the same ETag on both plain and gzip:ed variants. - Vary replies matching this access list will have the cache split - on the Accept-Encoding header of the request and not trusting the - ETag to be unique. - -NOCOMMENT_START -# Apache mod_gzip and mod_deflate known to be broken so don't trust -# Apache to signal ETag correctly on such responses -acl apache rep_header Server ^Apache -broken_vary_encoding allow apache -NOCOMMENT_END -DOC_END - COMMENT_START - OPTIONS WHICH AFFECT THE CACHE SIZE + MEMORY CACHE OPTIONS ----------------------------------------------------------------------------- COMMENT_END @@ -925,61 +836,6 @@ objects. DOC_END -NAME: cache_swap_low -COMMENT: (percent, 0-100) -TYPE: int -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 - - 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 - -NAME: maximum_object_size -COMMENT: (bytes) -TYPE: b_size_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. - - 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: minimum_object_size -COMMENT: (bytes) -TYPE: b_size_t -DEFAULT: 0 KB -LOC: Config.Store.minObjectSize -DOC_START - Objects smaller than this size will NOT be saved on disk. The - value is specified in kilobytes, and the default is 0 KB, which - means there is no minimum. -DOC_END - NAME: maximum_object_size_in_memory COMMENT: (bytes) TYPE: b_size_t @@ -1024,46 +880,6 @@ Maximum number of FQDN cache entries. DOC_END -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. - - 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 - - Applies to any cache_dir lines listed below this. - - The LRU policies keeps recently referenced objects. - - 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. - - 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. - - Both policies utilize a dynamic aging mechanism that prevents - cache pollution that can otherwise occur with frequency-based - replacement policies. - - NOTE: if using the LFUDA replacement policy you should increase - the value of maximum_object_size above its default of 4096 KB to - to maximize the potential byte hit rate improvement of LFUDA. - - 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 - NAME: memory_replacement_policy TYPE: removalpolicy LOC: Config.memPolicy @@ -1076,7 +892,7 @@ DOC_END COMMENT_START - LOGFILE PATHNAMES AND CACHE DIRECTORIES + DISK CACHE OPTIONS ----------------------------------------------------------------------------- COMMENT_END @@ -1226,26 +1042,147 @@ (hard coded at 1 MB). DOC_END -NAME: logformat -TYPE: logformat -LOC: Config.Log.logformats -DEFAULT: none +NAME: store_dir_select_algorithm +TYPE: string +LOC: Config.store_dir_select_algorithm +DEFAULT: least-load DOC_START - Usage: + Set this to 'round-robin' as an alternative. +DOC_END - logformat +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. - Defines an access log format. + A value of 0 indicates no limit. +DOC_END - The is a string with embedded % format codes +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. - % 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. + 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 - % ["|[|'|#] [-] [[0]width] [{argument}] formatcode + Applies to any cache_dir lines listed below this. + + The LRU policies keeps recently referenced objects. + + 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. + + 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. + + Both policies utilize a dynamic aging mechanism that prevents + cache pollution that can otherwise occur with frequency-based + replacement policies. + + NOTE: if using the LFUDA replacement policy you should increase + the value of maximum_object_size above its default of 4096 KB to + to maximize the potential byte hit rate improvement of LFUDA. + + 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 + +NAME: minimum_object_size +COMMENT: (bytes) +TYPE: b_size_t +DEFAULT: 0 KB +LOC: Config.Store.minObjectSize +DOC_START + Objects smaller than this size will NOT be saved on disk. The + value is specified in kilobytes, and the default is 0 KB, which + means there is no minimum. +DOC_END + +NAME: maximum_object_size +COMMENT: (bytes) +TYPE: b_size_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. + + 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: cache_swap_low +COMMENT: (percent, 0-100) +TYPE: int +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 + + 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 + LOGFILE OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + +NAME: logformat +TYPE: logformat +LOC: Config.Log.logformats +DEFAULT: none +DOC_START + Usage: + + logformat + + Defines an access log format. + + 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 @@ -1381,6 +1318,27 @@ better to keep these log files in each 'cache_dir' directory. DOC_END +NAME: logfile_rotate +TYPE: int +DEFAULT: 10 +LOC: Config.Log.rotateNumber +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 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 + '. +DOC_END + + NAME: emulate_httpd_log COMMENT: on|off TYPE: onoff @@ -1497,6 +1455,40 @@ the last digit set to '0'. DOC_END +NAME: forward_log +IFDEF: WIP_FWD_LOG +TYPE: string +DEFAULT: none +LOC: Config.Log.forward +DOC_START + Logs the server-side requests. + + This is currently work in progress. +DOC_END + +NAME: strip_query_terms +TYPE: onoff +LOC: Config.onoff.strip_query_terms +DEFAULT: on +DOC_START + By default, Squid strips query terms from requested URLs before + logging. This protects your user's privacy. +DOC_END + +NAME: buffered_logs +COMMENT: on|off +TYPE: onoff +DEFAULT: off +LOC: Config.onoff.buffered_logs +DOC_START + cache.log log file is written with stdio functions, and as such + it can be buffered or unbuffered. By default it will be unbuffered. + Buffering it can speed up the writing slightly (though you are + unlikely to need to worry unless you run with tons of debugging + enabled in which case performance will suffer badly anyway..). +DOC_END + + COMMENT_START OPTIONS FOR EXTERNAL SUPPORT PROGRAMS ----------------------------------------------------------------------------- @@ -1566,191 +1558,69 @@ is broken and does not follow the FTP standard. DOC_END -NAME: check_hostnames -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.check_hostnames +NAME: diskd_program +TYPE: string +DEFAULT: @DEFAULT_DISKD@ +LOC: Config.Program.diskd DOC_START - For security and stability reasons Squid by default checks - hostnames for Internet standard RFC compliance. If you do not want - Squid to perform these checks then turn this directive off. + Specify the location of the diskd executable. + Note that this is only useful if you have compiled in + diskd as one of the store io modules. DOC_END -NAME: allow_underscore -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.allow_underscore +NAME: unlinkd_program +IFDEF: USE_UNLINKD +TYPE: string +DEFAULT: @DEFAULT_UNLINKD@ +LOC: Config.Program.unlinkd DOC_START - Underscore characters is not strictly allowed in Internet hostnames - but nevertheless used by many sites. Set this to off if you want - Squid to be strict about the standard. + Specify the location of the executable for file deletion process. DOC_END -NAME: cache_dns_program +NAME: pinger_program TYPE: string -IFDEF: USE_DNSSERVERS -DEFAULT: @DEFAULT_DNSSERVER@ -LOC: Config.Program.dnsserver +DEFAULT: @DEFAULT_PINGER@ +LOC: Config.Program.pinger +IFDEF: USE_ICMP DOC_START - Specify the location of the executable for dnslookup process. + Specify the location of the executable for the pinger process. DOC_END -NAME: dns_children -TYPE: int -IFDEF: USE_DNSSERVERS -DEFAULT: 5 -LOC: Config.dnsChildren +NAME: url_rewrite_program redirect_program +TYPE: programline +LOC: Config.Program.url_rewrite.command +DEFAULT: none DOC_START - The number of processes spawn to service DNS name lookups. - For heavily loaded caches on large servers, you should - probably increase this value to at least 10. The maximum - is 32. The default is 5. + Specify the location of the executable for the URL rewriter. + Since they can perform almost any function there isn't one included. - You must have at least one dnsserver process. -DOC_END + For each requested URL rewriter will receive on line with the format -NAME: dns_retransmit_interval -TYPE: time_t -DEFAULT: 5 seconds -LOC: Config.Timeout.idns_retransmit -IFDEF: !USE_DNSSERVERS -DOC_START - Initial retransmit interval for DNS queries. The interval is - doubled each time all configured DNS servers have been tried. + URL client_ip "/" fqdn user method urlgroup + + 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). + + It can also return a "urlgroup" that can subsequently be matched + in cache_peer_access and similar ACL driven rules. An urlgroup is + returned by prefixing the returned url with "!urlgroup!" + By default, a URL rewriter is not used. DOC_END -NAME: dns_timeout -TYPE: time_t -DEFAULT: 2 minutes -LOC: Config.Timeout.idns_query -IFDEF: !USE_DNSSERVERS +NAME: url_rewrite_children redirect_children +TYPE: int +DEFAULT: 5 +LOC: Config.Program.url_rewrite.children DOC_START - DNS Query timeout. If no response is received to a DNS query - within this time all DNS servers for the queried domain - are assumed to be unavailable. -DOC_END - -NAME: dns_defnames -COMMENT: on|off -TYPE: onoff -DEFAULT: off -LOC: Config.onoff.res_defnames -DOC_START - Normally the RES_DEFNAMES resolver option is disabled - (see res_init(3)). This prevents caches in a hierarchy - from interpreting single-component hostnames locally. To allow - Squid to handle single-component names, enable this option. -DOC_END - -NAME: dns_nameservers -TYPE: wordlist -DEFAULT: none -LOC: Config.dns_nameservers -DOC_START - Use this if you want to specify a list of DNS name servers - (IP addresses) to use instead of those given in your - /etc/resolv.conf file. - On Windows platforms, if no value is specified here or in - the /etc/resolv.conf file, the list of DNS name servers are - taken from the Windows registry, both static and dynamic DHCP - configurations are supported. - - Example: dns_nameservers 10.0.0.1 192.172.0.4 -DOC_END - -NAME: hosts_file -TYPE: string -DEFAULT: @DEFAULT_HOSTS@ -LOC: Config.etcHostsPath -DOC_START - Location of the host-local IP name-address associations - database. Most Operating Systems have such a file on different - default locations: - - Un*X & Linux: /etc/hosts - - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts - (%SystemRoot% value install default is c:\winnt) - - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts - (%SystemRoot% value install default is c:\windows) - - Windows 9x/Me: %windir%\hosts - (%windir% value is usually c:\windows) - - Cygwin: /etc/hosts - - The file contains newline-separated definitions, in the - form ip_address_in_dotted_form name [name ...] names are - whitespace-separated. Lines beginning with an hash (#) - character are comments. - - The file is checked at startup and upon configuration. - If set to 'none', it won't be checked. - If append_domain is used, that domain will be added to - domain-local (i.e. not containing any dot character) host - definitions. -DOC_END - -NAME: diskd_program -TYPE: string -DEFAULT: @DEFAULT_DISKD@ -LOC: Config.Program.diskd -DOC_START - Specify the location of the diskd executable. - Note that 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 - -NAME: url_rewrite_program redirect_program -TYPE: programline -LOC: Config.Program.url_rewrite.command -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 urlgroup - - 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). - - It can also return a "urlgroup" that can subsequently be matched - in cache_peer_access and similar ACL driven rules. An urlgroup is - returned by prefixing the returned url with "!urlgroup!" - - By default, a URL rewriter is not used. -DOC_END - -NAME: url_rewrite_children redirect_children -TYPE: int -DEFAULT: 5 -LOC: Config.Program.url_rewrite.children -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. + 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 @@ -2470,6 +2340,108 @@ client requested. (default) DOC_END +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. +DOC_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: 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 50. +DOC_END + + +COMMENT_START + HTTP OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + +NAME: broken_posts +TYPE: acl_access +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. + + Some HTTP servers has broken implementations of PUT/POST, + and rely on an extra CRLF pair sent by some WWW clients. + + Quote from RFC2068 section 4.1 on this matter: + + 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. + +Example: + acl buggy_server url_regex ^http://.... + broken_posts allow buggy_server +DOC_END + +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. +DOC_END + +NAME: cache_vary +TYPE: onoff +DEFAULT: on +LOC: Config.onoff.cache_vary +DOC_START + Set to off to disable caching of Vary:in objects. +DOC_END + +NAME: broken_vary_encoding +TYPE: acl_access +DEFAULT: none +LOC: Config.accessList.vary_encoding +DOC_START + Many servers have broken support for on-the-fly Content-Encoding, + returning the same ETag on both plain and gzip:ed variants. + Vary replies matching this access list will have the cache split + on the Accept-Encoding header of the request and not trusting the + ETag to be unique. + +NOCOMMENT_START +# Apache mod_gzip and mod_deflate known to be broken so don't trust +# Apache to signal ETag correctly on such responses +acl apache rep_header Server ^Apache +broken_vary_encoding allow apache +NOCOMMENT_END +DOC_END + + NAME: collapsed_forwarding COMMENT: (on|off) TYPE: onoff @@ -2497,23 +2469,190 @@ frequently. DOC_END -COMMENT_START - TIMEOUTS - ----------------------------------------------------------------------------- -COMMENT_END - -NAME: forward_timeout -COMMENT: time-units -TYPE: time_t -LOC: Config.Timeout.forward -DEFAULT: 4 minutes +NAME: ie_refresh +COMMENT: on|off +TYPE: onoff +LOC: Config.onoff.ie_refresh +DEFAULT: off DOC_START - This parameter specifies how long Squid should at most attempt in - finding a forwarding path for the request before giving up. + 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 that 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 -NAME: connect_timeout -COMMENT: time-units +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: extension_methods +TYPE: extension_method +LOC: RequestMethods +DEFAULT: none +DOC_START + Squid only knows about standardized HTTP request methods. + You can add up to 20 additional "extension" methods here. +DOC_END + +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. + + 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: header_access +IFDEF: HTTP_VIOLATIONS +TYPE: http_header_access[] +LOC: Config.header_access +DEFAULT: none +DOC_START + Usage: 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. + + 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: + + header_access From deny all + header_access Referer deny all + header_access Server deny all + header_access User-Agent deny all + header_access WWW-Authenticate deny all + header_access Link deny all + + Or, to reproduce the old 'http_anonymizer paranoid' feature + you should use: + + header_access Allow allow all + header_access Authorization allow all + header_access WWW-Authenticate allow all + header_access Proxy-Authorization allow all + header_access Proxy-Authenticate allow all + header_access Cache-Control allow all + header_access Content-Encoding allow all + header_access Content-Length allow all + header_access Content-Type allow all + header_access Date allow all + header_access Expires allow all + header_access Host allow all + header_access If-Modified-Since allow all + header_access Last-Modified allow all + header_access Location allow all + header_access Pragma allow all + header_access Accept allow all + header_access Accept-Charset allow all + header_access Accept-Encoding allow all + header_access Accept-Language allow all + header_access Content-Language allow all + header_access Mime-Version allow all + header_access Retry-After allow all + header_access Title allow all + header_access Connection allow all + header_access Proxy-Connection allow all + header_access All deny all + + By default, all headers are allowed (no anonymizing is + performed). +DOC_END + +NAME: header_replace +IFDEF: HTTP_VIOLATIONS +TYPE: http_header_replace[] +LOC: Config.header_access +DEFAULT: none +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. + + By default, headers are removed if denied. +DOC_END + +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. + + 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. +DOC_END + +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: connect_timeout +COMMENT: time-units TYPE: time_t LOC: Config.Timeout.connect DEFAULT: 1 minute @@ -3917,214 +4056,161 @@ DOC_END COMMENT_START - MISCELLANEOUS + SNMP OPTIONS ----------------------------------------------------------------------------- COMMENT_END -NAME: dns_testnames -TYPE: wordlist -LOC: Config.dns_testname_list -DEFAULT: none -DEFAULT_IF_NONE: netscape.com internic.net nlanr.net microsoft.com -DOC_START - The DNS tests exit as soon as the first site is successfully looked up - - This test can be disabled with the -D command line option. -DOC_END - -NAME: logfile_rotate -TYPE: int -DEFAULT: 10 -LOC: Config.Log.rotateNumber +NAME: snmp_port +TYPE: ushort +LOC: Config.Port.snmp +DEFAULT: 3401 +IFDEF: SQUID_SNMP 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 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 - '. + Squid can now serve statistics and status information via SNMP. + By default it listens to port 3401 on the machine. If you don't + wish to use SNMP, set this to "0". DOC_END -NAME: append_domain -TYPE: string -LOC: Config.appendDomain +NAME: snmp_access +TYPE: acl_access +LOC: Config.accessList.snmp DEFAULT: none +DEFAULT_IF_NONE: deny all +IFDEF: SQUID_SNMP DOC_START - Appends local domain name to hostnames without any dots in - them. append_domain must begin with a period. + Allowing or denying access to the SNMP port. - Be warned there are now Internet names with no dots in - them using only top-domain names, so setting this may - cause some Internet sites to become unavailable. + All access to the agent is denied by default. + usage: -Example: - append_domain .yourdomain.com -DOC_END + snmp_access allow|deny [!]aclname ... -NAME: tcp_recv_bufsize -COMMENT: (bytes) -TYPE: b_size_t -DEFAULT: 0 bytes -LOC: Config.tcpRcvBufsz -DOC_START - Size of receive buffer to set for TCP sockets. Probably just - as easy to change your kernel's default. Set to zero to use - the default buffer size. +Example: + snmp_access allow snmppublic localhost + snmp_access deny all DOC_END -NAME: error_map -TYPE: errormap -LOC: Config.errorMapList -DEFAULT: none +NAME: snmp_incoming_address +TYPE: address +LOC: Config.Addrs.snmp_incoming +DEFAULT: 0.0.0.0 +IFDEF: SQUID_SNMP +DOC_NONE +NAME: snmp_outgoing_address +TYPE: address +LOC: Config.Addrs.snmp_outgoing +DEFAULT: 255.255.255.255 +IFDEF: SQUID_SNMP DOC_START - Map errors to custom messages + Just like 'udp_incoming_address' above, but for the SNMP port. - error_map message_url http_status ... + snmp_incoming_address is used for the SNMP socket receiving + messages from SNMP agents. + snmp_outgoing_address is used for SNMP packets returned to SNMP + agents. - http_status ... is a list of HTTP status codes or Squid error - messages. + The default snmp_incoming_address (0.0.0.0) is to listen on all + available network interfaces. - Use in accelerators to substitute the error messages returned - by servers with other custom errors. - - error_map http://your.server/error/404.shtml 404 + If snmp_outgoing_address is set to 255.255.255.255 (the default) + it will use the same socket as snmp_incoming_address. Only + change this if you want to have SNMP replies sent using another + address than where this Squid listens for SNMP queries. - Requests for error messages is a GET request for the configured - URL with the following special headers + NOTE, snmp_incoming_address and snmp_outgoing_address can not have + the same value since they both use port 3401. +DOC_END - X-Error-Status: The received HTTP status code (i.e. 404) - X-Request-URI: The requested URI where the error occurred +COMMENT_START + MULTICAST ICP OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END - In Addition the following headers are forwarded from the client - request: +NAME: mcast_groups +TYPE: wordlist +LOC: Config.mcast_group_list +DEFAULT: none +DOC_START + This tag specifies a list of multicast groups which your server + should join to receive multicasted ICP queries. - User-Agent, Cookie, X-Forwarded-For, Via, Authorization, - Accept, Referer + NOTE! Be very careful what you put here! Be sure you + understand the difference between an ICP _query_ and an ICP + _reply_. This option is to be set only if you want to RECEIVE + multicast queries. Do NOT set this option to SEND multicast + ICP (use cache_peer for that). ICP replies are always sent via + unicast, so this option does not affect whether or not you will + receive replies from multicast group members. - And the following headers from the server reply: + You must be very careful to NOT use a multicast address which + is already in use by another group of caches. - Server, Via, Location, Content-Location + If you are unsure about multicast, please read the Multicast + chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/). - The reply returned to the client will carry the original HTTP - headers from the real error message, but with the reply body - of the configured error message. + Usage: mcast_groups 239.128.16.128 224.0.1.20 + By default, Squid doesn't listen on any multicast groups. DOC_END -NAME: err_html_text -TYPE: eol -LOC: Config.errHtmlText -DEFAULT: none -DOC_START - HTML text to include in error messages. Make this a "mailto" - URL to your admin address, or maybe just a link to your - organizations Web page. - - To include this in your error messages, you must rewrite - the error template files (found in the "errors" directory). - Wherever you want the 'err_html_text' line to appear, - insert a %L tag in the error template file. -DOC_END -NAME: deny_info -TYPE: denyinfo -LOC: Config.denyInfoList -DEFAULT: none +NAME: mcast_miss_addr +IFDEF: MULTICAST_MISS_STREAM +TYPE: address +LOC: Config.mcast_miss.addr +DEFAULT: 255.255.255.255 DOC_START - Usage: deny_info err_page_name acl - or deny_info http://... acl - Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys - - This can be used to return a ERR_ page for requests which - do not pass the 'http_access' rules. A single ACL will cause - the http_access check to fail. If a 'deny_info' line exists - for that ACL Squid returns a corresponding error page. - - You may use ERR_ pages that come with Squid or create your own pages - and put them into the configured errors/ directory. - - Alternatively you can specify an error URL. The browsers will - get redirected (302) to the specified URL. %s in the redirection - URL will be replaced by the requested URL. + If you enable this option, every "cache miss" URL will + be sent out on the specified multicast address. - Alternatively you can tell Squid to reset the TCP connection - by specifying TCP_RESET. + Do not enable this option unless you are are absolutely + certain you understand what you are doing. DOC_END -NAME: memory_pools -COMMENT: on|off -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.mem_pools +NAME: mcast_miss_ttl +IFDEF: MULTICAST_MISS_STREAM +TYPE: ushort +LOC: Config.mcast_miss.ttl +DEFAULT: 16 DOC_START - If set, Squid will keep pools of allocated (but unused) memory - available for future use. If memory is a premium on your - system and you believe your malloc library outperforms Squid - routines, disable this. + This is the time-to-live value for packets multicasted + when multicasting off cache miss URLs is enabled. By + default this is set to 'site scope', i.e. 16. DOC_END -NAME: memory_pools_limit -COMMENT: (bytes) -TYPE: b_size_t -DEFAULT: 5 MB -LOC: Config.MemPools.limit +NAME: mcast_miss_port +IFDEF: MULTICAST_MISS_STREAM +TYPE: ushort +LOC: Config.mcast_miss.port +DEFAULT: 3135 DOC_START - Used only with memory_pools on: - memory_pools_limit 50 MB - - If set to a non-zero value, Squid will keep at most the specified - limit of allocated (but unused) memory in memory pools. All free() - requests that exceed this limit will be handled by your malloc - library. Squid does not pre-allocate any memory, just safe-keeps - objects that otherwise would be free()d. Thus, it is safe to set - memory_pools_limit to a reasonably high value even if your - configuration will use less memory. - - If set to zero, Squid will keep all memory it can. That is, there - will be no limit on the total amount of memory used for safe-keeping. - - To disable memory allocation optimization, do not set - memory_pools_limit to 0. Set memory_pools to "off" instead. - - An overhead for maintaining memory pools is not taken into account - when the limit is checked. This overhead is close to four bytes per - object kept. However, pools may actually _save_ memory because of - reduced memory thrashing in your malloc library. + This is the port number to be used in conjunction with + 'mcast_miss_addr'. DOC_END -NAME: via -IFDEF: HTTP_VIOLATIONS -COMMENT: on|off -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.via +NAME: mcast_miss_encode_key +IFDEF: MULTICAST_MISS_STREAM +TYPE: string +LOC: Config.mcast_miss.encode_key +DEFAULT: XXXXXXXXXXXXXXXX DOC_START - If set (default), Squid will include a Via header in requests and - replies. + The URLs that are sent in the multicast miss stream are + encrypted. This is the encryption key. DOC_END -NAME: forwarded_for -COMMENT: on|off -TYPE: onoff -DEFAULT: on -LOC: opt_forwarded_for -DOC_START - If set, Squid will include your system's IP address or name - in the HTTP requests it forwards. By default it looks like - this: - - X-Forwarded-For: 192.1.2.3 - - If you disable this, it will appear as +COMMENT_START + ICP OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END - X-Forwarded-For: unknown +NAME: icp_port udp_port +TYPE: ushort +DEFAULT: @DEFAULT_ICP_PORT@ +LOC: Config.Port.icp +DOC_START + The port number where Squid sends and receives ICP queries to + and from neighbor caches. Default is 3130. To disable use + "0". May be overridden with -u on the command line. DOC_END NAME: log_icp_queries @@ -4138,6 +4224,37 @@ up or to simplify log analysis. DOC_END +NAME: udp_incoming_address +TYPE: address +LOC:Config.Addrs.udp_incoming +DEFAULT: 0.0.0.0 +DOC_NONE + +NAME: udp_outgoing_address +TYPE: address +LOC: Config.Addrs.udp_outgoing +DEFAULT: 255.255.255.255 +DOC_START + udp_incoming_address is used for the ICP socket receiving packets + from other caches. + udp_outgoing_address is used for ICP packets sent out to other + caches. + + The default behavior is to not bind to any specific address. + + A udp_incoming_address value of 0.0.0.0 indicates Squid + should listen for UDP messages on all available interfaces. + + If udp_outgoing_address is set to 255.255.255.255 (the default) + it will use the same socket as udp_incoming_address. Only + change this if you want to have ICP queries sent using another + address than where this Squid listens for ICP queries from other + caches. + + NOTE, udp_incoming_address and udp_outgoing_address can not + have the same value since they both use port 3130. +DOC_END + NAME: icp_hit_stale COMMENT: on|off TYPE: onoff @@ -4171,125 +4288,32 @@ which are no more than this many rtt milliseconds away. DOC_END -NAME: cachemgr_passwd -TYPE: cachemgrpasswd -DEFAULT: none -LOC: Config.passwd_list +NAME: netdb_low +TYPE: int +DEFAULT: 900 +LOC: Config.Netdb.low +DOC_NONE + +NAME: netdb_high +TYPE: int +DEFAULT: 1000 +LOC: Config.Netdb.high DOC_START - Specify passwords for cachemgr operations. + The low and high water marks for the ICMP measurement + database. These are counts, not percents. The defaults are + 900 and 1000. When the high water mark is reached, database + entries will be deleted until the low mark is reached. +DOC_END - Usage: cachemgr_passwd password action action ... - - Some valid actions are (see cache manager menu for a full list): - 5min - 60min - asndb - authenticator - cbdata - client_list - comm_incoming - config * - counters - delay - digest_stats - dns - events - filedescriptors - fqdncache - histograms - http_headers - info - io - ipcache - mem - menu - netdb - non_peers - objects - offline_toggle * - pconn - peer_select - redirector - refresh - server_list - shutdown * - store_digest - storedir - utilization - via_headers - vm_objects - - * Indicates actions which will not be performed without a - valid password, others can be performed if not listed here. - - To disable an action, set the password to "disable". - To allow performing an action without a password, set the - password to "none". - - Use the keyword "all" to set the same password for all actions. - -Example: - cachemgr_passwd secret shutdown - cachemgr_passwd lesssssssecret info stats/objects - cachemgr_passwd disable all -DOC_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: 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 50. -DOC_END - -NAME: client_db -COMMENT: on|off -TYPE: onoff -DEFAULT: on -LOC: Config.onoff.client_db -DOC_START - If you want to disable collecting per-client statistics, - turn off client_db here. -DOC_END - -NAME: netdb_low -TYPE: int -DEFAULT: 900 -LOC: Config.Netdb.low -DOC_NONE - -NAME: netdb_high -TYPE: int -DEFAULT: 1000 -LOC: Config.Netdb.high -DOC_START - The low and high water marks for the ICMP measurement - database. These are counts, not percents. The defaults are - 900 and 1000. When the high water mark is reached, database - entries will be deleted until the low mark is reached. -DOC_END - -NAME: netdb_ping_period -TYPE: time_t -LOC: Config.Netdb.period -DEFAULT: 5 minutes -DOC_START - The minimum period for measuring a site. There will be at - least this much delay between successive pings to the same - network. The default is five minutes. -DOC_END +NAME: netdb_ping_period +TYPE: time_t +LOC: Config.Netdb.period +DEFAULT: 5 minutes +DOC_START + The minimum period for measuring a site. There will be at + least this much delay between successive pings to the same + network. The default is five minutes. +DOC_END NAME: query_icmp COMMENT: on|off @@ -4321,341 +4345,266 @@ database, or has a zero RTT. DOC_END -NAME: buffered_logs -COMMENT: on|off -TYPE: onoff -DEFAULT: off -LOC: Config.onoff.buffered_logs +COMMENT_START + INTERNAL ICON OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + +NAME: icon_directory +TYPE: string +LOC: Config.icons.directory +DEFAULT: @DEFAULT_ICON_DIR@ 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..). + Where the icons are stored. These are normally kept in + @DEFAULT_ICON_DIR@ DOC_END -NAME: reload_into_ims -IFDEF: HTTP_VIOLATIONS -COMMENT: on|off +NAME: global_internal_static TYPE: onoff -DEFAULT: off -LOC: Config.onoff.reload_into_ims +LOC: Config.onoff.global_internal_static +DEFAULT: on DOC_START - When you enable this option, client no-cache or ``reload'' - requests will be changed to If-Modified-Since requests. - Doing this VIOLATES the HTTP standard. Enabling this - feature could make you liable for problems which it - causes. - - see also refresh_pattern for a more selective approach. + This directive controls is Squid should intercept all requests for + /squid-internal-static/ no matter which host the URL is requesting + (default on setting), or if nothing special should be done for + such URLs (off setting). The purpose of this directive is to make + icons etc work better in complex cache hierarchies where it may + not always be possible for all corners in the cache mesh to reach + the server generating a directory listing. DOC_END -NAME: always_direct -TYPE: acl_access -LOC: Config.accessList.AlwaysDirect -DEFAULT: none +NAME: short_icon_urls +TYPE: onoff +LOC: Config.icons.use_short_names +DEFAULT: off DOC_START - Usage: always_direct allow|deny [!]aclname ... + If this is enabled Squid will use short URLs for icons. - Here you can use ACL elements to specify requests which should - ALWAYS be forwarded by Squid to the origin servers without using - any peers. For example, to always directly forward requests for - local servers ignoring any parents or siblings you may have use - something like: + If off the URLs for icons will always be absolute URLs + including the proxy name and port. +DOC_END - acl local-servers dstdomain my.domain.net - always_direct allow local-servers +COMMENT_START + ERROR PAGE OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END - To always forward FTP requests directly, use +NAME: error_directory +TYPE: string +LOC: Config.errorDirectory +DEFAULT: @DEFAULT_ERROR_DIR@ +DOC_START + If you wish to create your own versions of the default + (English) error files, either to customize them to suit your + language or company copy the template English files to another + directory and point this tag at them. +DOC_END - acl FTP proto FTP - always_direct allow FTP +NAME: error_map +TYPE: errormap +LOC: Config.errorMapList +DEFAULT: none +DOC_START + Map errors to custom messages - NOTE: There is a similar, but opposite option named - 'never_direct'. You need to be aware that "always_direct deny - foo" is NOT the same thing as "never_direct allow foo". You - may need to use a deny rule to exclude a more-specific case of - some other rule. Example: + error_map message_url http_status ... - acl local-external dstdomain external.foo.net - acl local-servers dstdomain .foo.net - always_direct deny local-external - always_direct allow local-servers + http_status ... is a list of HTTP status codes or Squid error + messages. - NOTE: If your goal is to make the client forward the request - directly to the origin server bypassing Squid then this needs - to be done in the client configuration. Squid configuration - can only tell Squid how Squid should fetch the object. + Use in accelerators to substitute the error messages returned + by servers with other custom errors. - NOTE: This directive is not related to caching. The replies - is cached as usual even if you use always_direct. To not cache - the replies see no_cache. + error_map http://your.server/error/404.shtml 404 - This option replaces some v1.1 options such as local_domain - and local_ip. -DOC_END + Requests for error messages is a GET request for the configured + URL with the following special headers -NAME: never_direct -TYPE: acl_access -LOC: Config.accessList.NeverDirect -DEFAULT: none -DOC_START - Usage: never_direct allow|deny [!]aclname ... + X-Error-Status: The received HTTP status code (i.e. 404) + X-Request-URI: The requested URI where the error occurred - never_direct is the opposite of always_direct. Please read - the description for always_direct if you have not already. + In Addition the following headers are forwarded from the client + request: - With 'never_direct' you can use ACL elements to specify - requests which should NEVER be forwarded directly to origin - servers. For example, to force the use of a proxy for all - requests, except those in your local domain use something like: + User-Agent, Cookie, X-Forwarded-For, Via, Authorization, + Accept, Referer - acl local-servers dstdomain .foo.net - acl all src 0.0.0.0/0.0.0.0 - never_direct deny local-servers - never_direct allow all + And the following headers from the server reply: - or if Squid is inside a firewall and there are local intranet - servers inside the firewall use something like: + Server, Via, Location, Content-Location - acl local-intranet dstdomain .foo.net - acl local-external dstdomain external.foo.net - always_direct deny local-external - always_direct allow local-intranet - never_direct allow all + The reply returned to the client will carry the original HTTP + headers from the real error message, but with the reply body + of the configured error message. - This option replaces some v1.1 options such as inside_firewall - and firewall_ip. DOC_END -NAME: header_access -IFDEF: HTTP_VIOLATIONS -TYPE: http_header_access[] -LOC: Config.header_access +NAME: err_html_text +TYPE: eol +LOC: Config.errHtmlText DEFAULT: none DOC_START - Usage: header_access header_name allow|deny [!]aclname ... + HTML text to include in error messages. Make this a "mailto" + URL to your admin address, or maybe just a link to your + organizations Web page. - 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. - - 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: - - header_access From deny all - header_access Referer deny all - header_access Server deny all - header_access User-Agent deny all - header_access WWW-Authenticate deny all - header_access Link deny all - - Or, to reproduce the old 'http_anonymizer paranoid' feature - you should use: - - header_access Allow allow all - header_access Authorization allow all - header_access WWW-Authenticate allow all - header_access Proxy-Authorization allow all - header_access Proxy-Authenticate allow all - header_access Cache-Control allow all - header_access Content-Encoding allow all - header_access Content-Length allow all - header_access Content-Type allow all - header_access Date allow all - header_access Expires allow all - header_access Host allow all - header_access If-Modified-Since allow all - header_access Last-Modified allow all - header_access Location allow all - header_access Pragma allow all - header_access Accept allow all - header_access Accept-Charset allow all - header_access Accept-Encoding allow all - header_access Accept-Language allow all - header_access Content-Language allow all - header_access Mime-Version allow all - header_access Retry-After allow all - header_access Title allow all - header_access Connection allow all - header_access Proxy-Connection allow all - header_access All deny all - - By default, all headers are allowed (no anonymizing is - performed). + To include this in your error messages, you must rewrite + the error template files (found in the "errors" directory). + Wherever you want the 'err_html_text' line to appear, + insert a %L tag in the error template file. DOC_END -NAME: header_replace -IFDEF: HTTP_VIOLATIONS -TYPE: http_header_replace[] -LOC: Config.header_access +NAME: deny_info +TYPE: denyinfo +LOC: Config.denyInfoList DEFAULT: none DOC_START - Usage: header_replace header_name message - Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit) + Usage: deny_info err_page_name acl + or deny_info http://... acl + Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys - 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. + This can be used to return a ERR_ page for requests which + do not pass the 'http_access' rules. A single ACL will cause + the http_access check to fail. If a 'deny_info' line exists + for that ACL Squid returns a corresponding error page. - By default, headers are removed if denied. -DOC_END + You may use ERR_ pages that come with Squid or create your own pages + and put them into the configured errors/ directory. -NAME: icon_directory -TYPE: string -LOC: Config.icons.directory -DEFAULT: @DEFAULT_ICON_DIR@ -DOC_START - Where the icons are stored. These are normally kept in - @DEFAULT_ICON_DIR@ -DOC_END + Alternatively you can specify an error URL. The browsers will + get redirected (302) to the specified URL. %s in the redirection + URL will be replaced by the requested URL. -NAME: global_internal_static -TYPE: onoff -LOC: Config.onoff.global_internal_static -DEFAULT: on -DOC_START - This directive controls is Squid should intercept all requests for - /squid-internal-static/ no matter which host the URL is requesting - (default on setting), or if nothing special should be done for - such URLs (off setting). The purpose of this directive is to make - icons etc work better in complex cache hierarchies where it may - not always be possible for all corners in the cache mesh to reach - the server generating a directory listing. + Alternatively you can tell Squid to reset the TCP connection + by specifying TCP_RESET. DOC_END -NAME: short_icon_urls -TYPE: onoff -LOC: Config.icons.use_short_names -DEFAULT: off -DOC_START - If this is enabled Squid will use short URLs for icons. - - If off the URLs for icons will always be absolute URLs - including the proxy name and port. -DOC_END +COMMENT_START + OPTIONS INFLUENCING REQUEST FORWARDING + ----------------------------------------------------------------------------- +COMMENT_END -NAME: error_directory -TYPE: string -LOC: Config.errorDirectory -DEFAULT: @DEFAULT_ERROR_DIR@ +NAME: nonhierarchical_direct +TYPE: onoff +LOC: Config.onoff.nonhierarchical_direct +DEFAULT: on DOC_START - If you wish to create your own versions of the default - (English) error files, either to customize them to suit your - language or company copy the template English files to another - directory and point this tag at them. -DOC_END + By default, Squid will send any non-hierarchical requests + (matching hierarchy_stoplist or not cacheable request type) direct + to origin servers. -NAME: maximum_single_addr_tries -TYPE: int -LOC: Config.retry.maxtries -DEFAULT: 1 -DOC_START - This sets the maximum number of connection attempts for a - host that only has one address (for multiple-address hosts, - each address is tried once). + If you set this to off, Squid will prefer to send these + requests to parents. - The default value is one attempt, the (not recommended) - maximum is 255 tries. A warning message will be generated - if it is set to a value greater than ten. + Note that in most configurations, by turning this off you will only + add latency to these request without any improvement in global hit + ratio. - Note: This is in addition to the request re-forwarding which - takes place if Squid fails to get a satisfying response. + If you are inside an firewall see never_direct instead of + this directive. DOC_END -NAME: retry_on_error +NAME: prefer_direct TYPE: onoff -LOC: Config.retry.onerror +LOC: Config.onoff.prefer_direct DEFAULT: off DOC_START - If set to on Squid will automatically retry requests when - receiving an error response. This is mainly useful if you - are in a complex cache hierarchy to work around access - control errors. -DOC_END + Normally Squid tries to use parents for most requests. If you for some + reason like it to first try going direct and only use a parent if + going direct fails set this to on. -NAME: snmp_port -TYPE: ushort -LOC: Config.Port.snmp -DEFAULT: 3401 -IFDEF: SQUID_SNMP -DOC_START - Squid can now serve statistics and status information via SNMP. - By default it listens to port 3401 on the machine. If you don't - wish to use SNMP, set this to "0". + By combining nonhierarchical_direct off and prefer_direct on you + can set up Squid to use a parent as a backup path if going direct + fails. + + Note: If you want Squid to use parents for all requests see + the never_direct directive. prefer_direct only modifies how Squid + acts on cacheable requests. DOC_END -NAME: snmp_access +NAME: always_direct TYPE: acl_access -LOC: Config.accessList.snmp +LOC: Config.accessList.AlwaysDirect DEFAULT: none -DEFAULT_IF_NONE: deny all -IFDEF: SQUID_SNMP DOC_START - Allowing or denying access to the SNMP port. + Usage: always_direct allow|deny [!]aclname ... - All access to the agent is denied by default. - usage: + Here you can use ACL elements to specify requests which should + ALWAYS be forwarded by Squid to the origin servers without using + any peers. For example, to always directly forward requests for + local servers ignoring any parents or siblings you may have use + something like: - snmp_access allow|deny [!]aclname ... + acl local-servers dstdomain my.domain.net + always_direct allow local-servers -Example: - snmp_access allow snmppublic localhost - snmp_access deny all -DOC_END + To always forward FTP requests directly, use -NAME: snmp_incoming_address -TYPE: address -LOC: Config.Addrs.snmp_incoming -DEFAULT: 0.0.0.0 -IFDEF: SQUID_SNMP -DOC_NONE -NAME: snmp_outgoing_address -TYPE: address -LOC: Config.Addrs.snmp_outgoing -DEFAULT: 255.255.255.255 -IFDEF: SQUID_SNMP -DOC_START - Just like 'udp_incoming_address' above, but for the SNMP port. + acl FTP proto FTP + always_direct allow FTP - snmp_incoming_address is used for the SNMP socket receiving - messages from SNMP agents. - snmp_outgoing_address is used for SNMP packets returned to SNMP - agents. + NOTE: There is a similar, but opposite option named + 'never_direct'. You need to be aware that "always_direct deny + foo" is NOT the same thing as "never_direct allow foo". You + may need to use a deny rule to exclude a more-specific case of + some other rule. Example: - The default snmp_incoming_address (0.0.0.0) is to listen on all - available network interfaces. + acl local-external dstdomain external.foo.net + acl local-servers dstdomain .foo.net + always_direct deny local-external + always_direct allow local-servers - If snmp_outgoing_address is set to 255.255.255.255 (the default) - it will use the same socket as snmp_incoming_address. Only - change this if you want to have SNMP replies sent using another - address than where this Squid listens for SNMP queries. + NOTE: If your goal is to make the client forward the request + directly to the origin server bypassing Squid then this needs + to be done in the client configuration. Squid configuration + can only tell Squid how Squid should fetch the object. - NOTE, snmp_incoming_address and snmp_outgoing_address can not have - the same value since they both use port 3401. + NOTE: This directive is not related to caching. The replies + is cached as usual even if you use always_direct. To not cache + the replies see no_cache. + + This option replaces some v1.1 options such as local_domain + and local_ip. DOC_END -NAME: as_whois_server -TYPE: string -LOC: Config.as_whois_server -DEFAULT: whois.ra.net -DEFAULT_IF_NONE: whois.ra.net +NAME: never_direct +TYPE: acl_access +LOC: Config.accessList.NeverDirect +DEFAULT: none DOC_START - WHOIS server to query for AS numbers. NOTE: AS numbers are - queried only when Squid starts up, not for every request. + Usage: never_direct allow|deny [!]aclname ... + + never_direct is the opposite of always_direct. Please read + the description for always_direct if you have not already. + + With 'never_direct' you can use ACL elements to specify + requests which should NEVER be forwarded directly to origin + servers. For example, to force the use of a proxy for all + requests, except those in your local domain use something like: + + acl local-servers dstdomain .foo.net + acl all src 0.0.0.0/0.0.0.0 + never_direct deny local-servers + never_direct allow all + + or if Squid is inside a firewall and there are local intranet + servers inside the firewall use something like: + + acl local-intranet dstdomain .foo.net + acl local-external dstdomain external.foo.net + always_direct deny local-external + always_direct allow local-intranet + never_direct allow all + + This option replaces some v1.1 options such as inside_firewall + and firewall_ip. DOC_END +COMMENT_START + ADVANCED NETWORKING OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + NAME: incoming_icp_average TYPE: int DEFAULT: 6 @@ -4696,164 +4645,436 @@ you understand the algorithms in comm_select.c first! DOC_END -NAME: max_open_disk_fds +NAME: max_filedescriptors TYPE: int -LOC: Config.max_open_disk_fds DEFAULT: 0 +LOC: Config.max_filedescriptors 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. + The maximum number of filedescriptors supported. - A value of 0 indicates no limit. + The default "0" means Squid inherits the current ulimit setting. + + Note: Changing this requires a restart of Squid. Also + not all comm loops supports values larger than --with-maxfd. DOC_END -NAME: offline_mode +NAME: accept_filter +IFDEF: SO_ACCEPTFILTER +TYPE: string +DEFAULT: none +LOC: Config.accept_filter +DOC_START + The name of an accept(2) filter to install on Squid's + listen socket(s). This feature is perhaps specific to + FreeBSD and requires support in the kernel. + + The 'httpready' filter delays delivering new connections + to Squid until a full HTTP request has been recieved. + See the accf_http(9) man page. + +EXAMPLE: +accept_filter httpready +DOC_END + +NAME: tcp_recv_bufsize +COMMENT: (bytes) +TYPE: b_size_t +DEFAULT: 0 bytes +LOC: Config.tcpRcvBufsz +DOC_START + Size of receive buffer to set for TCP sockets. Probably just + as easy to change your kernel's default. Set to zero to use + the default buffer size. +DOC_END + +COMMENT_START + DNS OPTIONS + ----------------------------------------------------------------------------- +COMMENT_END + +NAME: check_hostnames +TYPE: onoff +DEFAULT: on +LOC: Config.onoff.check_hostnames +DOC_START + For security and stability reasons Squid by default checks + hostnames for Internet standard RFC compliance. If you do not want + Squid to perform these checks then turn this directive off. +DOC_END + +NAME: allow_underscore +TYPE: onoff +DEFAULT: on +LOC: Config.onoff.allow_underscore +DOC_START + Underscore characters is not strictly allowed in Internet hostnames + but nevertheless used by many sites. Set this to off if you want + Squid to be strict about the standard. +DOC_END + +NAME: cache_dns_program +TYPE: string +IFDEF: USE_DNSSERVERS +DEFAULT: @DEFAULT_DNSSERVER@ +LOC: Config.Program.dnsserver +DOC_START + Specify the location of the executable for dnslookup process. +DOC_END + +NAME: dns_children +TYPE: int +IFDEF: USE_DNSSERVERS +DEFAULT: 5 +LOC: Config.dnsChildren +DOC_START + The number of processes spawn to service DNS name lookups. + For heavily loaded caches on large servers, you should + probably increase this value to at least 10. The maximum + is 32. The default is 5. + + You must have at least one dnsserver process. +DOC_END + +NAME: dns_retransmit_interval +TYPE: time_t +DEFAULT: 5 seconds +LOC: Config.Timeout.idns_retransmit +IFDEF: !USE_DNSSERVERS +DOC_START + Initial retransmit interval for DNS queries. The interval is + doubled each time all configured DNS servers have been tried. + +DOC_END + +NAME: dns_timeout +TYPE: time_t +DEFAULT: 2 minutes +LOC: Config.Timeout.idns_query +IFDEF: !USE_DNSSERVERS +DOC_START + DNS Query timeout. If no response is received to a DNS query + within this time all DNS servers for the queried domain + are assumed to be unavailable. +DOC_END + +NAME: dns_defnames +COMMENT: on|off TYPE: onoff -LOC: Config.onoff.offline DEFAULT: off +LOC: Config.onoff.res_defnames DOC_START - Enable this option and Squid will never try to validate cached - objects. + Normally the RES_DEFNAMES resolver option is disabled + (see res_init(3)). This prevents caches in a hierarchy + from interpreting single-component hostnames locally. To allow + Squid to handle single-component names, enable this option. DOC_END -NAME: uri_whitespace -TYPE: uri_whitespace -LOC: Config.uri_whitespace -DEFAULT: strip +NAME: dns_nameservers +TYPE: wordlist +DEFAULT: none +LOC: Config.dns_nameservers DOC_START - What to do with requests that have whitespace characters in the - URI. Options: + Use this if you want to specify a list of DNS name servers + (IP addresses) to use instead of those given in your + /etc/resolv.conf file. + On Windows platforms, if no value is specified here or in + the /etc/resolv.conf file, the list of DNS name servers are + taken from the Windows registry, both static and dynamic DHCP + configurations are supported. - strip: The whitespace characters are stripped out of the URL. - This is the behavior recommended by RFC2396. - deny: The request is denied. The user receives an "Invalid - Request" message. - allow: The request is allowed and the URI is not changed. The - whitespace characters remain in the URI. Note the - whitespace is passed to redirector processes if they - are in use. - encode: The request is allowed and the whitespace characters are - encoded according to RFC1738. This could be considered - a violation of the HTTP/1.1 - RFC because proxies are not allowed to rewrite URI's. - chop: The request is allowed and the URI is chopped at the - first whitespace. This might also be considered a - violation. + Example: dns_nameservers 10.0.0.1 192.172.0.4 DOC_END -NAME: broken_posts -TYPE: acl_access +NAME: hosts_file +TYPE: string +DEFAULT: @DEFAULT_HOSTS@ +LOC: Config.etcHostsPath +DOC_START + Location of the host-local IP name-address associations + database. Most Operating Systems have such a file on different + default locations: + - Un*X & Linux: /etc/hosts + - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts + (%SystemRoot% value install default is c:\winnt) + - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts + (%SystemRoot% value install default is c:\windows) + - Windows 9x/Me: %windir%\hosts + (%windir% value is usually c:\windows) + - Cygwin: /etc/hosts + + The file contains newline-separated definitions, in the + form ip_address_in_dotted_form name [name ...] names are + whitespace-separated. Lines beginning with an hash (#) + character are comments. + + The file is checked at startup and upon configuration. + If set to 'none', it won't be checked. + If append_domain is used, that domain will be added to + domain-local (i.e. not containing any dot character) host + definitions. +DOC_END + +NAME: dns_testnames +TYPE: wordlist +LOC: Config.dns_testname_list DEFAULT: none -LOC: Config.accessList.brokenPosts +DEFAULT_IF_NONE: netscape.com internic.net nlanr.net microsoft.com 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. + The DNS tests exit as soon as the first site is successfully looked up - Some HTTP servers has broken implementations of PUT/POST, - and rely on an extra CRLF pair sent by some WWW clients. + This test can be disabled with the -D command line option. +DOC_END - Quote from RFC2068 section 4.1 on this matter: +NAME: append_domain +TYPE: string +LOC: Config.appendDomain +DEFAULT: none +DOC_START + Appends local domain name to hostnames without any dots in + them. append_domain must begin with a period. - 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. + Be warned there are now Internet names with no dots in + them using only top-domain names, so setting this may + cause some Internet sites to become unavailable. Example: - acl buggy_server url_regex ^http://.... - broken_posts allow buggy_server + append_domain .yourdomain.com DOC_END -NAME: mcast_miss_addr -IFDEF: MULTICAST_MISS_STREAM -TYPE: address -LOC: Config.mcast_miss.addr -DEFAULT: 255.255.255.255 +NAME: ignore_unknown_nameservers +TYPE: onoff +LOC: Config.onoff.ignore_unknown_nameservers +DEFAULT: on DOC_START - If you enable this option, every "cache miss" URL will - be sent out on the specified multicast address. + By default Squid checks that DNS responses are received + from the same IP addresses they are sent to. If they + don't match, Squid ignores the response and writes a warning + message to cache.log. You can allow responses from unknown + nameservers by setting this option to 'off'. +DOC_END - Do not enable this option unless you are are absolutely - certain you understand what you are doing. +COMMENT_START + MISCELLANEOUS + ----------------------------------------------------------------------------- +COMMENT_END + +NAME: memory_pools +COMMENT: on|off +TYPE: onoff +DEFAULT: on +LOC: Config.onoff.mem_pools +DOC_START + If set, Squid will keep pools of allocated (but unused) memory + available for future use. If memory is a premium on your + system and you believe your malloc library outperforms Squid + routines, disable this. DOC_END -NAME: mcast_miss_ttl -IFDEF: MULTICAST_MISS_STREAM -TYPE: ushort -LOC: Config.mcast_miss.ttl -DEFAULT: 16 +NAME: memory_pools_limit +COMMENT: (bytes) +TYPE: b_size_t +DEFAULT: 5 MB +LOC: Config.MemPools.limit DOC_START - This is the time-to-live value for packets multicasted - when multicasting off cache miss URLs is enabled. By - default this is set to 'site scope', i.e. 16. + Used only with memory_pools on: + memory_pools_limit 50 MB + + If set to a non-zero value, Squid will keep at most the specified + limit of allocated (but unused) memory in memory pools. All free() + requests that exceed this limit will be handled by your malloc + library. Squid does not pre-allocate any memory, just safe-keeps + objects that otherwise would be free()d. Thus, it is safe to set + memory_pools_limit to a reasonably high value even if your + configuration will use less memory. + + If set to zero, Squid will keep all memory it can. That is, there + will be no limit on the total amount of memory used for safe-keeping. + + To disable memory allocation optimization, do not set + memory_pools_limit to 0. Set memory_pools to "off" instead. + + An overhead for maintaining memory pools is not taken into account + when the limit is checked. This overhead is close to four bytes per + object kept. However, pools may actually _save_ memory because of + reduced memory thrashing in your malloc library. DOC_END -NAME: mcast_miss_port -IFDEF: MULTICAST_MISS_STREAM -TYPE: ushort -LOC: Config.mcast_miss.port -DEFAULT: 3135 +NAME: forwarded_for +COMMENT: on|off +TYPE: onoff +DEFAULT: on +LOC: opt_forwarded_for DOC_START - This is the port number to be used in conjunction with - 'mcast_miss_addr'. + If set, Squid will include your system's IP address or name + in the HTTP requests it forwards. By default it looks like + this: + + X-Forwarded-For: 192.1.2.3 + + If you disable this, it will appear as + + X-Forwarded-For: unknown DOC_END -NAME: mcast_miss_encode_key -IFDEF: MULTICAST_MISS_STREAM -TYPE: string -LOC: Config.mcast_miss.encode_key -DEFAULT: XXXXXXXXXXXXXXXX +NAME: cachemgr_passwd +TYPE: cachemgrpasswd +DEFAULT: none +LOC: Config.passwd_list +DOC_START + Specify passwords for cachemgr operations. + + Usage: cachemgr_passwd password action action ... + + Some valid actions are (see cache manager menu for a full list): + 5min + 60min + asndb + authenticator + cbdata + client_list + comm_incoming + config * + counters + delay + digest_stats + dns + events + filedescriptors + fqdncache + histograms + http_headers + info + io + ipcache + mem + menu + netdb + non_peers + objects + offline_toggle * + pconn + peer_select + redirector + refresh + server_list + shutdown * + store_digest + storedir + utilization + via_headers + vm_objects + + * Indicates actions which will not be performed without a + valid password, others can be performed if not listed here. + + To disable an action, set the password to "disable". + To allow performing an action without a password, set the + password to "none". + + Use the keyword "all" to set the same password for all actions. + +Example: + cachemgr_passwd secret shutdown + cachemgr_passwd lesssssssecret info stats/objects + cachemgr_passwd disable all +DOC_END + +NAME: client_db +COMMENT: on|off +TYPE: onoff +DEFAULT: on +LOC: Config.onoff.client_db +DOC_START + If you want to disable collecting per-client statistics, + turn off client_db here. +DOC_END + +NAME: reload_into_ims +IFDEF: HTTP_VIOLATIONS +COMMENT: on|off +TYPE: onoff +DEFAULT: off +LOC: Config.onoff.reload_into_ims DOC_START - The URLs that are sent in the multicast miss stream are - encrypted. This is the encryption key. + When you enable this option, client no-cache or ``reload'' + requests will be changed to If-Modified-Since requests. + Doing this VIOLATES the HTTP standard. Enabling this + feature could make you liable for problems which it + causes. + + see also refresh_pattern for a more selective approach. DOC_END -NAME: nonhierarchical_direct -TYPE: onoff -LOC: Config.onoff.nonhierarchical_direct -DEFAULT: on +NAME: maximum_single_addr_tries +TYPE: int +LOC: Config.retry.maxtries +DEFAULT: 1 DOC_START - By default, Squid will send any non-hierarchical requests - (matching hierarchy_stoplist or not cacheable request type) direct - to origin servers. - - If you set this to off, Squid will prefer to send these - requests to parents. + This sets the maximum number of connection attempts for a + host that only has one address (for multiple-address hosts, + each address is tried once). - Note that in most configurations, by turning this off you will only - add latency to these request without any improvement in global hit - ratio. + The default value is one attempt, the (not recommended) + maximum is 255 tries. A warning message will be generated + if it is set to a value greater than ten. - If you are inside an firewall see never_direct instead of - this directive. + Note: This is in addition to the request re-forwarding which + takes place if Squid fails to get a satisfying response. DOC_END -NAME: prefer_direct +NAME: retry_on_error TYPE: onoff -LOC: Config.onoff.prefer_direct +LOC: Config.retry.onerror DEFAULT: off DOC_START - Normally Squid tries to use parents for most requests. If you for some - reason like it to first try going direct and only use a parent if - going direct fails set this to on. - - By combining nonhierarchical_direct off and prefer_direct on you - can set up Squid to use a parent as a backup path if going direct - fails. + If set to on Squid will automatically retry requests when + receiving an error response. This is mainly useful if you + are in a complex cache hierarchy to work around access + control errors. +DOC_END - Note: If you want Squid to use parents for all requests see - the never_direct directive. prefer_direct only modifies how Squid - acts on cacheable requests. +NAME: as_whois_server +TYPE: string +LOC: Config.as_whois_server +DEFAULT: whois.ra.net +DEFAULT_IF_NONE: whois.ra.net +DOC_START + WHOIS server to query for AS numbers. NOTE: AS numbers are + queried only when Squid starts up, not for every request. DOC_END -NAME: strip_query_terms +NAME: offline_mode TYPE: onoff -LOC: Config.onoff.strip_query_terms -DEFAULT: on +LOC: Config.onoff.offline +DEFAULT: off DOC_START - By default, Squid strips query terms from requested URLs before - logging. This protects your user's privacy. + Enable this option and Squid will never try to validate cached + objects. +DOC_END + +NAME: uri_whitespace +TYPE: uri_whitespace +LOC: Config.uri_whitespace +DEFAULT: strip +DOC_START + What to do with requests that have whitespace characters in the + URI. Options: + + strip: The whitespace characters are stripped out of the URL. + This is the behavior recommended by RFC2396. + deny: The request is denied. The user receives an "Invalid + Request" message. + allow: The request is allowed and the URI is not changed. The + whitespace characters remain in the URI. Note the + whitespace is passed to redirector processes if they + are in use. + encode: The request is allowed and the whitespace characters are + encoded according to RFC1738. This could be considered + a violation of the HTTP/1.1 + RFC because proxies are not allowed to rewrite URI's. + chop: The request is allowed and the URI is chopped at the + first whitespace. This might also be considered a + violation. DOC_END NAME: coredump_dir @@ -4889,18 +5110,6 @@ be allowed to request. DOC_END -NAME: ignore_unknown_nameservers -TYPE: onoff -LOC: Config.onoff.ignore_unknown_nameservers -DEFAULT: on -DOC_START - By default Squid checks that DNS responses are received - from the same IP addresses they are sent to. If they - don't match, Squid ignores the response and writes a warning - message to cache.log. You can allow responses from unknown - nameservers by setting this option to 'off'. -DOC_END - NAME: chroot TYPE: string LOC: Config.chroot_dir @@ -4939,31 +5148,6 @@ reasons. DOC_END -NAME: extension_methods -TYPE: extension_method -LOC: RequestMethods -DEFAULT: none -DOC_START - Squid only knows about standardized HTTP request methods. - You can add up to 20 additional "extension" methods here. -DOC_END - -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. - - 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: high_response_time_warning TYPE: int COMMENT: (msec) @@ -4996,64 +5180,6 @@ the administrators attention. DOC_END -NAME: store_dir_select_algorithm -TYPE: string -LOC: Config.store_dir_select_algorithm -DEFAULT: least-load -DOC_START - Set this to 'round-robin' as an alternative. -DOC_END - -NAME: forward_log -IFDEF: WIP_FWD_LOG -TYPE: string -DEFAULT: none -LOC: Config.Log.forward -DOC_START - Logs the server-side requests. - - This is currently work in progress. -DOC_END - -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 that 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 - -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: sleep_after_fork COMMENT: (microseconds) TYPE: int @@ -5072,67 +5198,4 @@ rounded to 1000. DOC_END -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. -DOC_END - -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. - - 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. -DOC_END - -NAME: max_filedescriptors -TYPE: int -DEFAULT: 0 -LOC: Config.max_filedescriptors -DOC_START - The maximum number of filedescriptors supported. - - The default "0" means Squid inherits the current ulimit setting. - - Note: Changing this requires a restart of Squid. Also - not all comm loops supports values larger than --with-maxfd. -DOC_END - -NAME: accept_filter -IFDEF: SO_ACCEPTFILTER -TYPE: string -DEFAULT: none -LOC: Config.accept_filter -DOC_START - The name of an accept(2) filter to install on Squid's - listen socket(s). This feature is perhaps specific to - FreeBSD and requires support in the kernel. - - The 'httpready' filter delays delivering new connections - to Squid until a full HTTP request has been recieved. - See the accf_http(9) man page. - -EXAMPLE: -accept_filter httpready -DOC_END EOF