------------------------------------------------------------ revno: 12537 revision-id: squid3@treenet.co.nz-20130427022320-nhbfobdui4e9qdm5 parent: squid3@treenet.co.nz-20130427021746-5on30o8fzm0rh942 committer: Amos Jeffries branch nick: 3.3 timestamp: Fri 2013-04-26 20:23:20 -0600 message: Docs: Polish configuration file documentation * Mostly adding DEFAULT_DOC directive to hide strange default values. This wll help us move to different internal values for no-limit etc at some point in the future. * Migrates some access controls to "DEFAULT: none" instead of "deny all". This reduces run-time CPU cycles running useless ACL tests. NP: some access controls have been left unchanged due to complexity in the code testing them (ie icap_access). * added documentation for several directives which were missing text * corrected buffered_logs documentation (text by Alex Rousskov) * updated cf_gen tool to produce more descriptive error messages * corrected icp_access default to match documented 'deny all' permission ------------------------------------------------------------ # Bazaar merge directive format 2 (Bazaar 0.90) # revision_id: squid3@treenet.co.nz-20130427022320-nhbfobdui4e9qdm5 # target_branch: http://bzr.squid-cache.org/bzr/squid3/3.3 # testament_sha1: 45b3592f1000668e33ac7a22b734365c524a6e4c # timestamp: 2013-04-27 02:26:10 +0000 # source_branch: http://bzr.squid-cache.org/bzr/squid3/3.3 # base_revision_id: squid3@treenet.co.nz-20130427021746-\ # 5on30o8fzm0rh942 # # Begin patch === modified file 'helpers/external_acl/session/ext_session_acl.8' --- helpers/external_acl/session/ext_session_acl.8 2011-10-23 01:07:46 +0000 +++ helpers/external_acl/session/ext_session_acl.8 2013-04-27 02:23:20 +0000 @@ -68,7 +68,7 @@ acl with the argument .B LOGIN , or terminated by the argument -.B LOGOUT . +.B LOGOUT \. Without this flag the helper automatically starts the session after the first request. .SH CONFIGURATION @@ -79,7 +79,7 @@ .B must be specified in the configuration. .PP -Configuration example using the default automatic mode +Passive session configuration example using the default automatic mode .if !'po4a'hide' .RS .if !'po4a'hide' .B external_acl_type session ttl=300 negative_ttl=0 children=1 concurrency=200 %LOGIN /usr/local/squid/libexec/ext_session_acl .if !'po4a'hide' .br === modified file 'src/cf.data.pre' --- src/cf.data.pre 2013-04-02 04:04:31 +0000 +++ src/cf.data.pre 2013-04-27 02:23:20 +0000 @@ -327,7 +327,7 @@ If you want to use the traditional NCSA proxy authentication, set this line to something like - auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd + auth_param basic program @DEFAULT_PREFIX@/libexec/basic_ncsa_auth @DEFAULT_PREFIX@/etc/passwd "utf8" on|off HTTP uses iso-latin-1 as character set, while some authentication @@ -477,7 +477,7 @@ of type proxy_auth. By default, the NTLM authenticator_program is not used. - auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth + auth_param ntlm program /usr/bin/ntlm_auth "children" numberofchildren [startup=N] [idle=N] The maximum number of authenticator processes to spawn (default 5). @@ -518,7 +518,7 @@ The only supported program for this role is the ntlm_auth program distributed as part of Samba, version 4 or later. - auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego + auth_param negotiate program /usr/bin/ntlm_auth --helper-protocol=gss-spnego "children" numberofchildren [startup=N] [idle=N] The maximum number of authenticator processes to spawn (default 5). @@ -1028,6 +1028,7 @@ IFDEF: FOLLOW_X_FORWARDED_FOR LOC: Config.accessList.followXFF DEFAULT_IF_NONE: deny all +DEFAULT_DOC: X-Forwarded-For header will be ignored. DOC_START Allowing or Denying the X-Forwarded-For header to be followed to find the original source of a request. @@ -1137,6 +1138,7 @@ TYPE: acl_access LOC: Config.accessList.http DEFAULT_IF_NONE: deny all +DEFAULT_DOC: Deny, unless rules exist in squid.conf. DOC_START Allowing or Denying access based on defined access lists @@ -1197,6 +1199,7 @@ TYPE: acl_access LOC: Config.accessList.adapted_http DEFAULT: none +DEFAULT_DOC: Allow, unless rules exist in squid.conf. DOC_START Allowing or Denying access based on defined access lists @@ -1211,13 +1214,14 @@ TYPE: acl_access LOC: Config.accessList.reply DEFAULT: none +DEFAULT_DOC: Allow, unless rules exist in squid.conf. DOC_START Allow replies to client requests. This is complementary to http_access. http_reply_access allow|deny [!] aclname ... NOTE: if there are no access lines present, the default is to allow - all replies + all replies. If none of the access lines cause a match the opposite of the last line will apply. Thus it is good practice to end the rules @@ -1230,14 +1234,17 @@ NAME: icp_access TYPE: acl_access LOC: Config.accessList.icp -DEFAULT_IF_NONE: deny all +DEFAULT: none +DEFAULT_DOC: Deny, unless rules exist in squid.conf. DOC_START Allowing or Denying access to the ICP port based on defined access lists icp_access allow|deny [!]aclname ... - See http_access for details + NOTE: The default if no icp_access lines are present is to + deny all traffic. This default may cause problems with peers + using ICP. This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. @@ -1251,14 +1258,16 @@ IFDEF: USE_HTCP TYPE: acl_access LOC: Config.accessList.htcp -DEFAULT_IF_NONE: deny all +DEFAULT: none +DEFAULT_DOC: Deny, unless rules exist in squid.conf. DOC_START Allowing or Denying access to the HTCP port based on defined access lists htcp_access allow|deny [!]aclname ... - See http_access for details + See also htcp_clr_access for details on access control for + cache purge (CLR) HTCP messages. NOTE: The default if no htcp_access lines are present is to deny all traffic. This default may cause problems with peers @@ -1276,27 +1285,29 @@ IFDEF: USE_HTCP TYPE: acl_access LOC: Config.accessList.htcp_clr -DEFAULT_IF_NONE: deny all +DEFAULT: none +DEFAULT_DOC: Deny, unless rules exist in squid.conf. DOC_START Allowing or Denying access to purge content using HTCP based - on defined access lists + on defined access lists. + See htcp_access for details on general HTCP access control. htcp_clr_access allow|deny [!]aclname ... - See http_access for details - This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. # Allow HTCP CLR requests from trusted peers -acl htcp_clr_peer src 172.16.1.2 +acl htcp_clr_peer src 192.0.2.2 2001:DB8::2 htcp_clr_access allow htcp_clr_peer +htcp_clr_access deny all DOC_END NAME: miss_access TYPE: acl_access LOC: Config.accessList.miss DEFAULT: none +DEFAULT_DOC: Allow, unless rules exist in squid.conf. DOC_START Determins whether network access is permitted when satisfying a request. @@ -1304,15 +1315,14 @@ to force your neighbors to use you as a sibling instead of a parent. - acl localclients src 172.16.0.0/16 - miss_access allow localclients + acl localclients src 192.0.2.0/24 2001:DB8::a:0/64 miss_access deny !localclients + miss_access allow all This means only your local clients are allowed to fetch relayed/MISS replies from the network and all other clients can only fetch cached objects (HITs). - The default for this setting allows all clients who passed the http_access rules to relay via this proxy. @@ -1323,7 +1333,8 @@ NAME: ident_lookup_access TYPE: acl_access IFDEF: USE_IDENT -DEFAULT_IF_NONE: deny all +DEFAULT: none +DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched. LOC: Ident::TheConfig.identLookup DOC_START A list of ACL elements which, if matched, cause an ident @@ -1352,6 +1363,7 @@ COMMENT: size [acl acl...] TYPE: acl_b_size_t DEFAULT: none +DEFAULT_DOC: No limit is applied. LOC: Config.ReplyBodySize DOC_START This option specifies the maximum size of a reply body. It can be @@ -1922,6 +1934,7 @@ NAME: tcp_outgoing_address TYPE: acl_address DEFAULT: none +DEFAULT_DOC: Address selection is performed by the operating system. LOC: Config.accessList.outgoing_address DOC_START Allows you to map requests to different outgoing IP addresses @@ -2102,6 +2115,7 @@ NAME: sslproxy_version IFDEF: USE_SSL DEFAULT: 1 +DEFAULT_DOC: automatic SSL/TLS version negotiation LOC: Config.ssl_client.version TYPE: int DOC_START @@ -2182,6 +2196,7 @@ IFDEF: USE_SSL TYPE: sslproxy_ssl_bump LOC: Config.accessList.ssl_bump +DEFAULT_DOC: Does not bump unless rules are present in squid.conf DEFAULT: none DOC_START This option is consulted when a CONNECT request is received on @@ -2228,7 +2243,7 @@ # Example: Bump all requests except those originating from - # localhost and those going to example.com. + # localhost or those going to example.com. acl broken_sites dstdomain .example.com ssl_bump none localhost @@ -2252,6 +2267,7 @@ NAME: sslproxy_cert_error IFDEF: USE_SSL DEFAULT: none +DEFAULT_DOC: Server certificate errors terminate the transaction. LOC: Config.ssl_client.cert_error TYPE: acl_access DOC_START @@ -2270,13 +2286,14 @@ Using slow acl types may result in server crashes Without this option, all server certificate validation errors - terminate the transaction. Bypassing validation errors is dangerous - because an error usually implies that the server cannot be trusted and - the connection may be insecure. + terminate the transaction to protect Squid and the client. + + SECURITY WARNING: + Bypassing validation errors is dangerous because an + error usually implies that the server cannot be trusted + and the connection may be insecure. See also: sslproxy_flags and DONT_VERIFY_PEER. - - Default setting: sslproxy_cert_error deny all DOC_END NAME: sslproxy_cert_sign @@ -2292,14 +2309,17 @@ sslproxy_cert_sign acl ... The following certificate signing algorithms are supported: + signTrusted Sign using the configured CA certificate which is usually placed in and trusted by end-user browsers. This is the default for trusted origin server certificates. + signUntrusted Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error. This is the default for untrusted origin server certificates that are not self-signed (see ssl::certUntrusted). + signSelf Sign using a self-signed certificate with the right CN to generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the @@ -2322,7 +2342,7 @@ bump-server-first is used. DOC_END -NAME: sslproxy_cert_adapt +NAME: sslproxy_cert_adapt IFDEF: USE_SSL DEFAULT: none TYPE: sslproxy_cert_adapt @@ -2332,12 +2352,15 @@ sslproxy_cert_adapt acl ... The following certificate adaptation algorithms are supported: + setValidAfter Sets the "Not After" property to the "Not After" property of the CA certificate used to sign generated certificates. + setValidBefore Sets the "Not Before" property to the "Not Before" property of the CA certificate used to sign generated certificates. + setCommonName or setCommonName{CN} Sets Subject.CN property to the host name specified as a CN parameter or, if no explicit CN parameter was specified, @@ -2799,10 +2822,11 @@ LOC: none DOC_START Use to limit the domains for which a neighbor cache will be - queried. Usage: + queried. - cache_peer_domain cache-host domain [domain ...] - cache_peer_domain cache-host !domain + Usage: + cache_peer_domain cache-host domain [domain ...] + cache_peer_domain cache-host !domain For example, specifying @@ -2833,7 +2857,8 @@ Similar to 'cache_peer_domain' but provides more flexibility by using ACL elements. - cache_peer_access cache-host allow|deny [!]aclname ... + Usage: + cache_peer_access cache-host allow|deny [!]aclname ... The syntax is identical to 'http_access' and the other lists of ACL elements. See the comments for 'http_access' below, or @@ -2843,21 +2868,21 @@ NAME: neighbor_type_domain TYPE: hostdomaintype DEFAULT: none +DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer. LOC: none DOC_START - usage: neighbor_type_domain neighbor parent|sibling domain domain ... - - Modifying the neighbor type for specific domains is now - possible. You can treat some domains differently than 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. - -EXAMPLE: - cache_peer cache.foo.org parent 3128 3130 - neighbor_type_domain cache.foo.org sibling .com .net - neighbor_type_domain cache.foo.org sibling .au .de + Modify the cache_peer neighbor type when passing requests + about specific domains to the peer. + + Usage: + neighbor_type_domain neighbor parent|sibling domain domain ... + + For example: + cache_peer foo.example.com parent 3128 3130 + neighbor_type_domain foo.example.com sibling .au .de + + The above configuration treats all requests to foo.example.com as a + parent proxy unless the request is for a .au or .de ccTLD domain name. DOC_END NAME: dead_peer_timeout @@ -3001,6 +3026,7 @@ TYPE: memcachemode LOC: Config DEFAULT: always +DEFAULT_DOC: Keep the most recently fetched objects in memory DOC_START Controls which objects to keep in the memory cache (cache_mem) @@ -3021,7 +3047,7 @@ The memory replacement policy parameter determines which objects are purged from memory when memory space is needed. - See cache_replacement_policy for details. + See cache_replacement_policy for details on algorithms. DOC_END COMMENT_START @@ -3042,7 +3068,7 @@ heap LFUDA: Least Frequently Used with Dynamic Aging heap LRU : LRU policy implemented using a heap - Applies to any cache_dir lines listed below this. + Applies to any cache_dir lines listed below this directive. The LRU policies keeps recently referenced objects. @@ -3072,11 +3098,11 @@ NAME: cache_dir TYPE: cachedir DEFAULT: none +DEFAULT_DOC: No disk cache. Store cache ojects only in memory. LOC: Config.cacheSwap DOC_START - Usage: - - cache_dir Type Directory-Name Fs-specific-data [options] + Format: + cache_dir Type Directory-Name Fs-specific-data [options] You can specify multiple cache_dir lines to spread the cache among different disk partitions. @@ -3095,12 +3121,14 @@ and should use configuration macros or conditionals to give each worker interested in disk caching a dedicated cache directory. - The ufs store type: + + ==== The ufs store type ==== "ufs" is the old well-known Squid storage format that has always been there. - cache_dir ufs Directory-Name Mbytes L1 L2 [options] + Usage: + cache_dir ufs Directory-Name Mbytes L1 L2 [options] 'Mbytes' is the amount of disk space (MB) to use under this directory. The default is 100 MB. Change this to suit your @@ -3115,23 +3143,27 @@ will be created under each first-level directory. The default is 256. - The aufs store type: + + ==== The aufs store type ==== "aufs" uses the same storage format as "ufs", utilizing POSIX-threads to avoid blocking the main Squid process on disk-I/O. This was formerly known in Squid as async-io. - cache_dir aufs Directory-Name Mbytes L1 L2 [options] + Usage: + cache_dir aufs Directory-Name Mbytes L1 L2 [options] see argument descriptions under ufs above - The diskd store type: + + ==== The diskd store type ==== "diskd" uses the same storage format as "ufs", utilizing a separate process to avoid blocking the main Squid process on disk-I/O. - cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n] + Usage: + cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n] see argument descriptions under ufs above @@ -3149,8 +3181,10 @@ higher hit ratio at the expense of an increase in response time. - The rock store type: - + + ==== The rock store type ==== + + Usage: cache_dir rock Directory-Name Mbytes [options] The Rock Store type is a database-style storage. All cached @@ -3189,7 +3223,7 @@ enforcement. Currently supported by IpcIo module only. - The coss store type: + ==== The coss store type ==== NP: COSS filesystem in Squid-3 has been deemed too unstable for production use and has thus been removed from this release. @@ -3207,24 +3241,31 @@ called 'stripe' in the directory names in the config - and this will be created by squid -z. - Common options: - - no-store, no new objects should be stored to this cache_dir - - min-size=n, refers to the min object size in bytes this cache_dir - will accept. It's used to restrict a cache_dir to only store - large objects (e.g. aufs) while other storedirs are optimized - for smaller objects (e.g. COSS). Defaults to 0. - - max-size=n, refers to the max object size in bytes this cache_dir - supports. It is used to select the cache_dir to store the object. + + ==== COMMON OPTIONS ==== + + no-store no new objects should be stored to this cache_dir. + + min-size=n the minimum object size in bytes this cache_dir + will accept. It's used to restrict a cache_dir + to only store large objects (e.g. AUFS) while + other stores are optimized for smaller objects + (e.g. COSS). + Defaults to 0. + + max-size=n the maximum object size in bytes this cache_dir + supports. + The value in maximum_object_size directive, sets + a default unless more specific details are available + about the cache_dir (ie a small store capacity). + Note: To make optimal use of the max-size limits you should order - the cache_dir lines with the smallest max-size value first and the - ones with no max-size specification last. + the cache_dir lines with the smallest max-size value first. Note for coss, max-size must be less than COSS_MEMBUF_SZ, which can be changed with the --with-coss-membuf-size=N configure option. + NOCOMMENT_START # Uncomment and adjust the following to add a disk cache directory. @@ -3237,13 +3278,54 @@ LOC: Config.store_dir_select_algorithm DEFAULT: least-load DOC_START - Set this to 'round-robin' as an alternative. + How Squid selects which cache_dir to use when the response + object will fit into more than one. + + Regardless of which algorithm is used the cache_dir min-size + and max-size parameters are obeyed. As such they can affect + the selection algorithm by limiting the set of considered + cache_dir. + + Algorithms: + + least-load + + This algorithm is suited to caches with similar cache_dir + sizes and disk speeds. + + The disk with the least I/O pending is selected. + When there are multiple disks with the same I/O load ranking + the cache_dir with most available capacity is selected. + + When a mix of cache_dir sizes are configured the faster disks + have a naturally lower I/O loading and larger disks have more + capacity. So space used to store objects and data throughput + may be very unbalanced towards larger disks. + + + round-robin + + This algorithm is suited to caches with unequal cache_dir + disk sizes. + + Each cache_dir is selected in a rotation. The next suitable + cache_dir is used. + + Available cache_dir capacity is only considered in relation + to whether the object will fit and meets the min-size and + max-size parameters. + + Disk I/O loading is only considered to prevent overload on slow + disks. This algorithm does not spread objects by size, so any + I/O loading per-disk may appear very unbalanced and volatile. + DOC_END NAME: max_open_disk_fds TYPE: int LOC: Config.max_open_disk_fds DEFAULT: 0 +DEFAULT_DOC: no limit 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 @@ -3256,11 +3338,12 @@ COMMENT: (bytes) TYPE: b_int64_t DEFAULT: 0 KB +DEFAULT_DOC: no limit 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. + value is specified in bytes, and the default is 0 KB, which + means all responses can be stored. DOC_END NAME: maximum_object_size @@ -3290,7 +3373,20 @@ TYPE: int DEFAULT: 90 LOC: Config.Swap.lowWaterMark -DOC_NONE +DOC_START + The low-water mark 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. + + See also cache_swap_high +DOC_END NAME: cache_swap_high COMMENT: (percent, 0-100) @@ -3298,8 +3394,7 @@ DEFAULT: 95 LOC: Config.Swap.highWaterMark DOC_START - - The low- and high-water marks for cache object replacement. + The high-water mark 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 @@ -3309,6 +3404,8 @@ Defaults are 90% and 95%. If you have a large cache, 5% could be hundreds of MB. If this is the case you may wish to set these numbers closer together. + + See also cache_swap_low DOC_END COMMENT_START @@ -3320,6 +3417,7 @@ TYPE: logformat LOC: Log::TheConfig DEFAULT: none +DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in. DOC_START Usage: @@ -3700,6 +3798,7 @@ TYPE: acl_access LOC: Config.accessList.log DEFAULT: none +DEFAULT_DOC: Allow logging for all transactions. COMMENT: allow|deny acl acl... DOC_START This options allows you to control which requests gets logged @@ -3715,6 +3814,7 @@ IFDEF: ICAP_CLIENT LOC: Config.accessList.icap DEFAULT: none +DEFAULT_DOC: Allow logging for all ICAP transactions. DOC_START This options allows you to control which requests get logged to icap.log. See the icap_log directive for ICAP log details. @@ -3743,6 +3843,7 @@ TYPE: string LOC: Config.Log.swap DEFAULT: none +DEFAULT_DOC: Store the journal inside its cache_dir 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 @@ -3792,8 +3893,8 @@ in the habit of using 'squid -k rotate' instead of 'kill -USR1 '. - Note, from Squid-3.1 this option has no effect on the cache.log, - that log can be rotated separately by using debug_options + Note, from Squid-3.1 this option is only a default for cache.log, + that log can be rotated separately by using debug_options. DOC_END NAME: emulate_httpd_log @@ -3813,9 +3914,10 @@ 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. + Path to Squid's icon configuration file. + + You shouldn't need to change this, but the default file contains + examples and formatting information if you do. DOC_END NAME: log_mime_hdrs @@ -3861,6 +3963,7 @@ TYPE: address LOC: Config.Addrs.client_netmask DEFAULT: no_addr +DEFAULT_DOC: Log full client IP address DOC_START A netmask for client addresses in logfiles and cachemgr output. Change this to protect the privacy of your cache clients. @@ -3880,7 +3983,10 @@ DEFAULT: on DOC_START By default, Squid strips query terms from requested URLs before - logging. This protects your user's privacy. + logging. This protects your user's privacy and reduces log size. + + When investigating HIT/MISS or other caching behaviour you + will need to disable this to see the full URL used by Squid. DOC_END NAME: buffered_logs @@ -3889,11 +3995,18 @@ 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..). + Whether to write/send access_log records ASAP or accumulate them and + then write/send them in larger chunks. Buffering may improve + performance because it decreases the number of I/Os. However, + buffering increases the delay before log records become available to + the final recipient (e.g., a disk file or logging daemon) and, + hence, increases the risk of log records loss. + + Note that even when buffered_logs are off, Squid may have to buffer + records if it cannot write/send them immediately due to pending I/Os + (e.g., the I/O writing the previous log record) or connectivity loss. + + Currently honored by 'daemon' access_log module only. DOC_END NAME: netdb_filename @@ -3902,7 +4015,9 @@ LOC: Config.netdbFilename IFDEF: USE_ICMP DOC_START - A filename where Squid stores it's netdb state between restarts. + Where Squid stores it's netdb journal. + When enabled this journal preserves netdb state between restarts. + To disable, enter "none". DOC_END @@ -3916,14 +4031,17 @@ DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@ LOC: Debug::cache_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 and how often its rotated with "debug_options" + Squid administrative logging file. + + This is where general information about Squid behavior goes. You can + increase the amount of data logged to this file and how often it is + rotated with "debug_options" DOC_END NAME: debug_options TYPE: eol DEFAULT: ALL,1 +DEFAULT_DOC: Log all critical and important messages. LOC: Debug::debugOptions DOC_START Logging options are set as section,level where each source file @@ -3932,7 +4050,7 @@ log file, so be careful. The magic word "ALL" sets debugging levels for all sections. - We recommend normally running with "ALL,1". + The default is to run with "ALL,1" to record important warnings. The rotate=N option can be used to keep more or less of these logs than would otherwise be kept by logfile_rotate. @@ -3944,6 +4062,7 @@ TYPE: string LOC: Config.coredump_dir DEFAULT_IF_NONE: none +DEFAULT_DOC: Use the directory from where Squid was started. DOC_START By default Squid leaves core files in the directory from where it was started. If you set 'coredump_dir' to a directory @@ -3969,13 +4088,13 @@ LOC: Config.Ftp.anon_user 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 + (and enable the use of picky FTP servers), set this to something reasonable for your domain, like wwwuser@somewhere.net The reason why this is domainless by default is the request can be made on the behalf of a user in any domain, depending on how the cache is used. - Some ftp server also validate the email address is valid + Some FTP server also validate the email address is valid (for example perl.com). DOC_END @@ -4226,11 +4345,11 @@ NAME: url_rewrite_access redirector_access TYPE: acl_access DEFAULT: none +DEFAULT_DOC: Allow, unless rules exist in squid.conf. 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. + sent to the redirector processes. This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. @@ -4242,7 +4361,7 @@ 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' + redirector if all the helpers are busy. If this is 'off' and the redirector queue grows too large, Squid will exit with a FATAL error and ask you to increase the number of redirectors. You should only enable this if the redirectors @@ -4260,6 +4379,7 @@ NAME: cache no_cache TYPE: acl_access DEFAULT: none +DEFAULT_DOC: Allow caching, unless rules exist in squid.conf. LOC: Config.accessList.noCache DOC_START A list of ACL elements which, if matched and denied, cause the request to @@ -4269,8 +4389,6 @@ You must use the words 'allow' or 'deny' to indicate whether items matching the ACL should be allowed or denied into the cache. - Default is to allow all to be cached. - This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. DOC_END @@ -4399,7 +4517,9 @@ NOCOMMENT_START +# # Add any of your own refresh_pattern entries above these. +# refresh_pattern ^ftp: 1440 20% 10080 refresh_pattern ^gopher: 1440 0% 1440 refresh_pattern -i (/cgi-bin/|\?) 0 0% 0 @@ -4557,13 +4677,15 @@ 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 environments it - might be desirable to honor shorter object lifetimes. It - is most likely better to make your server return a - meaningful Last-Modified header however. In ESI environments - where page fragments often have short lifetimes, this will - often be best set to 0. + headers Squid honors if the object can't be revalidated. + The default is 60 seconds. + + In reverse proxy environments it might be desirable to honor + shorter object lifetimes. It is most likely better to make + your server return a meaningful Last-Modified header however. + + In ESI environments where page fragments often have short + lifetimes, this will often be best set to 0. DOC_END NAME: store_avg_object_size @@ -4574,6 +4696,14 @@ DOC_START Average object size, used to estimate number of objects your cache can hold. The default is 13 KB. + + This is used to pre-seed the cache index memory allocation to + reduce expensive reallocate operations while handling clients + traffic. Too-large values may result in memory allocation during + peak traffic, too-small values will result in wasted memory. + + Check the cache manager 'info' report metrics for the real + object sizes seen by your Squid before tuning this. DOC_END NAME: store_objects_per_bucket @@ -4621,6 +4751,7 @@ COMMENT: (bytes) TYPE: b_int64_t DEFAULT: 0 KB +DEFAULT_DOC: No limit. LOC: Config.maxRequestBodySize DOC_START This specifies the maximum size for an HTTP request body. @@ -4629,6 +4760,9 @@ than this limit receives an "Invalid Request" error message. If you set this parameter to a zero (the default), there will be no limit imposed. + + See also client_request_buffer_max_size for an alternative + limitation on client uploads which can be configured. DOC_END NAME: client_request_buffer_max_size @@ -4673,6 +4807,7 @@ IFDEF: USE_HTTP_VIOLATIONS TYPE: acl_access DEFAULT: none +DEFAULT_DOC: Obey RFC 2616. LOC: Config.accessList.brokenPosts DOC_START A list of ACL elements which, if matched, causes Squid to send @@ -4781,6 +4916,7 @@ TYPE: http_header_access LOC: Config.request_header_access DEFAULT: none +DEFAULT_DOC: No limits. DOC_START Usage: request_header_access header_name allow|deny [!]aclname ... @@ -4820,46 +4956,30 @@ request_header_access From deny all request_header_access Referer deny all - request_header_access Server deny all request_header_access User-Agent deny all - request_header_access WWW-Authenticate deny all - request_header_access Link deny all Or, to reproduce the old 'http_anonymizer paranoid' feature you should use: - request_header_access Allow allow all request_header_access Authorization allow all - request_header_access WWW-Authenticate allow all request_header_access Proxy-Authorization allow all - request_header_access Proxy-Authenticate allow all request_header_access Cache-Control allow all - request_header_access Content-Encoding allow all request_header_access Content-Length allow all request_header_access Content-Type allow all request_header_access Date allow all - request_header_access Expires allow all request_header_access Host allow all request_header_access If-Modified-Since allow all - request_header_access Last-Modified allow all - request_header_access Location allow all request_header_access Pragma allow all request_header_access Accept allow all request_header_access Accept-Charset allow all request_header_access Accept-Encoding allow all request_header_access Accept-Language allow all - request_header_access Content-Language allow all - request_header_access Mime-Version allow all - request_header_access Retry-After allow all - request_header_access Title allow all request_header_access Connection allow all request_header_access All deny all - although many of those are HTTP reply headers, and so should be - controlled with the reply_header_access directive. + HTTP reply headers are controlled with the reply_header_access directive. - By default, all headers are allowed (no anonymizing is - performed). + By default, all headers are allowed (no anonymizing is performed). DOC_END NAME: reply_header_access @@ -4867,6 +4987,7 @@ TYPE: http_header_access LOC: Config.reply_header_access DEFAULT: none +DEFAULT_DOC: No limits. DOC_START Usage: reply_header_access header_name allow|deny [!]aclname ... @@ -4884,10 +5005,7 @@ 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 @@ -4895,9 +5013,7 @@ you should use: reply_header_access Allow allow all - reply_header_access Authorization allow all reply_header_access WWW-Authenticate allow all - reply_header_access Proxy-Authorization allow all reply_header_access Proxy-Authenticate allow all reply_header_access Cache-Control allow all reply_header_access Content-Encoding allow all @@ -4905,24 +5021,17 @@ reply_header_access Content-Type allow all reply_header_access Date allow all reply_header_access Expires allow all - reply_header_access Host allow all - reply_header_access If-Modified-Since allow all reply_header_access Last-Modified allow all reply_header_access Location allow all reply_header_access Pragma allow all - reply_header_access Accept allow all - reply_header_access Accept-Charset allow all - reply_header_access Accept-Encoding allow all - reply_header_access Accept-Language allow all reply_header_access Content-Language allow all - reply_header_access Mime-Version allow all reply_header_access Retry-After allow all reply_header_access Title allow all + reply_header_access Content-Disposition allow all reply_header_access Connection allow all reply_header_access All deny all - although the HTTP request headers won't be usefully controlled - by this directive -- see request_header_access for details. + HTTP request headers are controlled with the request_header_access directive. By default, all headers are allowed (no anonymizing is performed). @@ -4939,8 +5048,7 @@ This option allows you to change the contents of headers denied with request_header_access above, by replacing them - with some fixed string. This replaces the old fake_user_agent - option. + with some fixed string. This only applies to request headers, not reply headers. @@ -5196,7 +5304,7 @@ LOC: Config.adminEmail DOC_START Email-address of local cache manager who will receive - mail if the cache dies. The default is "webmaster." + mail if the cache dies. The default is "webmaster". DOC_END NAME: mail_from @@ -5205,9 +5313,9 @@ LOC: Config.EmailFrom DOC_START From: email-address for mail sent when the cache dies. - The default is to use 'appname@unique_hostname'. - Default appname value is "squid", can be changed into - src/globals.h before building squid. + The default is to use 'squid@unique_hostname'. + + See also: unique_hostname directive. DOC_END NAME: mail_program @@ -5237,6 +5345,7 @@ NAME: cache_effective_group TYPE: string DEFAULT: none +DEFAULT_DOC: Use system group memberships of the cache_effective_user account LOC: Config.effectiveGroup DOC_START Squid sets the GID to the effective user's default group ID @@ -5269,6 +5378,7 @@ TYPE: string LOC: Config.visibleHostname DEFAULT: none +DEFAULT_DOC: Automatically detect the system host name DOC_START If you want to present a special hostname in error messages, etc, define this. Otherwise, the return value of gethostname() @@ -5281,6 +5391,7 @@ TYPE: string LOC: Config.uniqueHostname DEFAULT: none +DEFAULT_DOC: Copy the value from visible_hostname DOC_START If you want to have multiple machines with the same 'visible_hostname' you must give each machine a different @@ -5335,10 +5446,9 @@ TYPE: time_t LOC: Config.Announce.period DEFAULT: 0 +DEFAULT_DOC: Announcement messages disabled. DOC_START - This is how frequently to send cache announcements. The - default is `0' which disables sending the announcement - messages. + This is how frequently to send cache announcements. To enable announcing your cache, just set an announce period. @@ -5350,26 +5460,29 @@ TYPE: string DEFAULT: tracker.ircache.net LOC: Config.Announce.host -DOC_NONE +DOC_START + Set the hostname where announce registration messages will be sent. + + See also announce_port and announce_file +DOC_END NAME: announce_file TYPE: string DEFAULT: none LOC: Config.Announce.file -DOC_NONE +DOC_START + The contents of this file will be included in the announce + registration messages. +DOC_END NAME: announce_port TYPE: u_short DEFAULT: 3131 LOC: Config.Announce.port DOC_START - announce_host and announce_port set the hostname and port - number where the registration message will be sent. + Set the port where announce registration messages will be sent. - Hostname will default to 'tracker.ircache.net' and port will - default default to 3131. If the 'filename' argument is given, - the contents of that file will be included in the announce - message. + See also announce_host and announce_file DOC_END COMMENT_START @@ -5380,14 +5493,13 @@ NAME: httpd_accel_surrogate_id TYPE: string DEFAULT: none +DEFAULT_DOC: visible_hostname is used if no specific ID is set. LOC: Config.Accel.surrogate_id DOC_START Surrogates (http://www.esi.org/architecture_spec_1.0.html) need an identification token to allow control targeting. Because a farm of surrogates may all perform the same tasks, they may share an identification token. - - The default ID is the visible_hostname DOC_END NAME: http_accel_surrogate_remote @@ -5396,7 +5508,9 @@ DEFAULT: off LOC: Config.onoff.surrogate_is_remote DOC_START - Remote surrogates (such as those in a CDN) honour Surrogate-Control: no-store-remote. + Remote surrogates (such as those in a CDN) honour the header + "Surrogate-Control: no-store-remote". + Set this to on to have squid behave as a remote surrogate. DOC_END @@ -5426,6 +5540,9 @@ This represents the number of delay pools to be used. For example, if you have one class 2 delay pool and one class 3 delays pool, you have a total of 2 delay pools. + + See also delay_parameters, delay_class, delay_access for pool + configuration details. DOC_END NAME: delay_class @@ -5482,11 +5599,17 @@ NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic. + + This clause only supports fast acl types. + See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. + + See also delay_parameters and delay_access. DOC_END NAME: delay_access TYPE: delay_pool_access DEFAULT: none +DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool. IFDEF: USE_DELAY_POOLS LOC: Config.Delay DOC_START @@ -5500,12 +5623,14 @@ For example, if you want some_big_clients in delay pool 1 and lotsa_little_clients in delay pool 2: -Example: - delay_access 1 allow some_big_clients - delay_access 1 deny all - delay_access 2 allow lotsa_little_clients - delay_access 2 deny all - delay_access 3 allow authenticated_clients + delay_access 1 allow some_big_clients + delay_access 1 deny all + delay_access 2 allow lotsa_little_clients + delay_access 2 deny all + delay_access 3 allow authenticated_clients + + See also delay_parameters and delay_class. + DOC_END NAME: delay_parameters @@ -5597,6 +5722,10 @@ be limited to 128Kbits/sec no matter how many workstations they are logged into.: delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000 + + + See also delay_class and delay_access. + DOC_END NAME: delay_initial_bucket_level @@ -5627,8 +5756,10 @@ This option specifies the number of client delay pools used. It must preceed other client_delay_* options. -Example: - client_delay_pools 2 + Example: + client_delay_pools 2 + + See also client_delay_parameters and client_delay_access. DOC_END NAME: client_delay_initial_bucket_level @@ -5647,8 +5778,8 @@ buckets are not refilled until their size goes down to max_bucket_size from client_delay_parameters. -Example: - client_delay_initial_bucket_level 50 + Example: + client_delay_initial_bucket_level 50 DOC_END NAME: client_delay_parameters @@ -5673,18 +5804,21 @@ Please see the delay_parameters option for more information and examples. -Example: - client_delay_parameters 1 1024 2048 - client_delay_parameters 2 51200 16384 + Example: + client_delay_parameters 1 1024 2048 + client_delay_parameters 2 51200 16384 + + See also client_delay_access. + DOC_END NAME: client_delay_access TYPE: client_delay_pool_access DEFAULT: none +DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool. IFDEF: USE_DELAY_POOLS LOC: Config.ClientDelay DOC_START - This option determines the client-side delay pool for the request: @@ -5701,11 +5835,19 @@ not used to aggregate clients. Clients are always aggregated based on their source IP addresses (one bucket per source IP). + This clause only supports fast acl types. + See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. + Additionally, only the client TCP connection details are available. + ACLs testing HTTP properties will not work. + Please see delay_access for more examples. -Example: - client_delay_access 1 allow low_rate_network - client_delay_access 2 allow vips_network + Example: + client_delay_access 1 allow low_rate_network + client_delay_access 2 allow vips_network + + + See also client_delay_parameters and client_delay_pools. DOC_END COMMENT_START @@ -5717,6 +5859,7 @@ TYPE: address LOC: Config.Wccp.router DEFAULT: any_addr +DEFAULT_DOC: WCCP disabled. IFDEF: USE_WCCP DOC_START Use this option to define your WCCP ``home'' router for @@ -5734,6 +5877,7 @@ TYPE: IpAddress_list LOC: Config.Wccp2.router DEFAULT: none +DEFAULT_DOC: WCCPv2 disabled. IFDEF: USE_WCCPv2 DOC_START Use this option to define your WCCP ``home'' router for @@ -5833,6 +5977,7 @@ TYPE: wccp2_service LOC: Config.Wccp2.info DEFAULT_IF_NONE: standard 0 +DEFAULT_DOC: Use the 'web-cache' standard service. IFDEF: USE_WCCPv2 DOC_START WCCP2 allows for multiple traffic services. There are two @@ -5902,13 +6047,20 @@ TYPE: address LOC: Config.Wccp.address DEFAULT: 0.0.0.0 +DEFAULT_DOC: Address selected by the operating system. IFDEF: USE_WCCP -DOC_NONE +DOC_START + Use this option if you require WCCPv2 to use a specific + interface address. + + The default behavior is to not bind to any specific address. +DOC_END NAME: wccp2_address TYPE: address LOC: Config.Wccp2.address DEFAULT: 0.0.0.0 +DEFAULT_DOC: Address selected by the operating system. IFDEF: USE_WCCPv2 DOC_START Use this option if you require WCCP to use a specific @@ -5928,17 +6080,20 @@ TYPE: onoff LOC: Config.onoff.client_pconns DEFAULT: on -DOC_NONE +DOC_START + Persistent connection support for clients. + Squid uses persistent connections (when allowed). You can use + this option to disable persistent connections with clients. +DOC_END NAME: server_persistent_connections TYPE: onoff LOC: Config.onoff.server_pconns DEFAULT: on DOC_START - Persistent connection support for clients and servers. By - default, Squid uses persistent connections (when allowed) - with its clients and servers. You can use these options to - disable persistent connections with clients and/or servers. + Persistent connection support for servers. + Squid uses persistent connections (when allowed). You can use + this option to disable persistent connections with servers. DOC_END NAME: persistent_connection_after_error @@ -6046,6 +6201,7 @@ TYPE: u_short LOC: Config.Port.snmp DEFAULT: 0 +DEFAULT_DOC: SNMP disabled. IFDEF: SQUID_SNMP DOC_START The port number where Squid listens for SNMP requests. To enable @@ -6060,7 +6216,8 @@ NAME: snmp_access TYPE: acl_access LOC: Config.accessList.snmp -DEFAULT_IF_NONE: deny all +DEFAULT: none +DEFAULT_DOC: Deny, unless rules exist in squid.conf. IFDEF: SQUID_SNMP DOC_START Allowing or denying access to the SNMP port. @@ -6072,6 +6229,7 @@ This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. + Example: snmp_access allow snmppublic localhost snmp_access deny all @@ -6081,32 +6239,37 @@ TYPE: address LOC: Config.Addrs.snmp_incoming DEFAULT: any_addr -IFDEF: SQUID_SNMP -DOC_NONE - -NAME: snmp_outgoing_address -TYPE: address -LOC: Config.Addrs.snmp_outgoing -DEFAULT: no_addr +DEFAULT_DOC: Accept SNMP packets from all machine interfaces. IFDEF: SQUID_SNMP DOC_START Just like 'udp_incoming_address', but for the SNMP port. snmp_incoming_address is used for the SNMP socket receiving messages from SNMP agents. + + The default snmp_incoming_address is to listen on all + available network interfaces. +DOC_END + +NAME: snmp_outgoing_address +TYPE: address +LOC: Config.Addrs.snmp_outgoing +DEFAULT: no_addr +DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system. +IFDEF: SQUID_SNMP +DOC_START + Just like 'udp_outgoing_address', but for the SNMP port. + snmp_outgoing_address is used for SNMP packets returned to SNMP agents. - The default snmp_incoming_address is to listen on all - available network interfaces. - If snmp_outgoing_address is not set it will use the same socket as snmp_incoming_address. Only change this if you want to have SNMP replies sent using another address than where this Squid listens for SNMP queries. NOTE, snmp_incoming_address and snmp_outgoing_address can not have - the same value since they both use port 3401. + the same value since they both use the same port. DOC_END COMMENT_START @@ -6117,11 +6280,11 @@ NAME: icp_port udp_port TYPE: u_short DEFAULT: 0 +DEFAULT_DOC: ICP disabled. LOC: Config.Port.icp DOC_START The port number where Squid sends and receives ICP queries to and from neighbor caches. The standard UDP port for ICP is 3130. - Default is disabled (0). Example: icp_port @DEFAULT_ICP_PORT@ @@ -6131,11 +6294,12 @@ IFDEF: USE_HTCP TYPE: u_short DEFAULT: 0 +DEFAULT_DOC: HTCP disabled. LOC: Config.Port.htcp DOC_START The port number where Squid sends and receives HTCP queries to and from neighbor caches. To turn it on you want to set it to - 4827. By default it is set to "0" (disabled). + 4827. Example: htcp_port 4827 @@ -6156,6 +6320,7 @@ TYPE: address LOC:Config.Addrs.udp_incoming DEFAULT: any_addr +DEFAULT_DOC: Accept packets from all machine interfaces. DOC_START udp_incoming_address is used for UDP packets received from other caches. @@ -6178,6 +6343,7 @@ TYPE: address LOC: Config.Addrs.udp_outgoing DEFAULT: no_addr +DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system. DOC_START udp_outgoing_address is used for UDP packets sent out to other caches. @@ -6223,6 +6389,7 @@ DOC_END NAME: minimum_direct_rtt +COMMENT: (msec) TYPE: int DEFAULT: 400 LOC: Config.minDirectRtt @@ -6235,17 +6402,30 @@ TYPE: int DEFAULT: 900 LOC: Config.Netdb.low -DOC_NONE +DOC_START + The low water mark for the ICMP measurement database. + + Note: high watermark controlled by netdb_high directive. + + These watermarks are counts, not percents. The defaults are + (low) 900 and (high) 1000. When the high water mark is + reached, database entries will be deleted until the low + mark is reached. +DOC_END 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. + The high water mark for the ICMP measurement database. + + Note: low watermark controlled by netdb_low directive. + + These watermarks are counts, not percents. The defaults are + (low) 900 and (high) 1000. When the high water mark is + reached, database entries will be deleted until the low + mark is reached. DOC_END NAME: netdb_ping_period @@ -6291,6 +6471,7 @@ NAME: icp_query_timeout COMMENT: (msec) DEFAULT: 0 +DEFAULT_DOC: Dynamic detection. TYPE: int LOC: Config.Timeout.icp_query DOC_START @@ -6380,6 +6561,7 @@ TYPE: address LOC: Config.mcast_miss.addr DEFAULT: no_addr +DEFAULT_DOC: disabled. DOC_START If you enable this option, every "cache miss" URL will be sent out on the specified multicast address. @@ -6482,6 +6664,7 @@ TYPE: string LOC: Config.errorDirectory DEFAULT: none +DEFAULT_DOC: Send error pages in the clients preferred language DOC_START If you wish to create your own versions of the default error files to customize them to suit your company copy @@ -6506,6 +6689,7 @@ TYPE: string LOC: Config.errorDefaultLanguage DEFAULT: none +DEFAULT_DOC: Generate English language pages. DOC_START Set the default language which squid will send error pages in if no existing translation matches the clients language @@ -6647,15 +6831,16 @@ (matching hierarchy_stoplist or not cacheable request type) direct to origin servers. - If you set this to off, Squid will prefer to send these + When this is set to "off", Squid will prefer to send these requests to parents. Note that in most configurations, by turning this off you will only add latency to these request without any improvement in global hit ratio. - If you are inside an firewall see never_direct instead of - this directive. + This option only sets a preference. If the parent is unavailable a + direct connection to the origin server may still be attempted. To + completely prevent direct connections use never_direct. DOC_END NAME: prefer_direct @@ -6680,6 +6865,7 @@ TYPE: acl_access LOC: Config.accessList.AlwaysDirect DEFAULT: none +DEFAULT_DOC: Prevent any cache_peer being used for this request. DOC_START Usage: always_direct allow|deny [!]aclname ... @@ -6725,6 +6911,7 @@ TYPE: acl_access LOC: Config.accessList.NeverDirect DEFAULT: none +DEFAULT_DOC: Allow DNS results to be used for this request. DOC_START Usage: never_direct allow|deny [!]aclname ... @@ -6855,6 +7042,7 @@ TYPE: int LOC: Config.client_ip_max_connections DEFAULT: -1 +DEFAULT_DOC: No limit. DOC_START Set an absolute limit on the number of connections a single client IP can use. Any more than this and Squid will begin to drop @@ -6873,11 +7061,12 @@ COMMENT: (bytes) TYPE: b_size_t DEFAULT: 0 bytes +DEFAULT_DOC: Use operating system TCP defaults. 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. + as easy to change your kernel's default. + Omit from squid.conf to use the default buffer size. DOC_END COMMENT_START @@ -6914,6 +7103,7 @@ COMMENT: time-units TYPE: time_t DEFAULT: none +DEFAULT_DOC: Use read_timeout. LOC: Adaptation::Icap::TheConfig.io_timeout_raw IFDEF: ICAP_CLIENT DOC_START @@ -6921,8 +7111,6 @@ an established, active ICAP connection before giving up and either terminating the HTTP transaction or bypassing the failure. - - The default is read_timeout. DOC_END NAME: icap_service_failure_limit @@ -7002,10 +7190,10 @@ IFDEF: ICAP_CLIENT LOC: Adaptation::Icap::TheConfig.preview_size DEFAULT: -1 +DEFAULT_DOC: No preview sent. DOC_START The default size of preview data to be sent to the ICAP server. - -1 means no preview. This value might be overwritten on a per server - basis by OPTIONS requests. + This value might be overwritten on a per server basis by OPTIONS requests. DOC_END NAME: icap_206_enable @@ -7397,6 +7585,7 @@ IFDEF: USE_ADAPTATION LOC: none DEFAULT: none +DEFAULT_DOC: Allow, unless rules exist in squid.conf. DOC_START Sends an HTTP transaction to an ICAP or eCAP adaptation service. @@ -7542,9 +7731,9 @@ IFDEF: ICAP_CLIENT LOC: Adaptation::Icap::TheConfig.repeat_limit DEFAULT: 0 +DEFAULT_DOC: No retries are allowed. DOC_START - Limits the number of retries allowed. When set to zero (default), - no retries are allowed. + Limits the number of retries allowed. Communication errors due to persistent connection race conditions are unavoidable, automatically retried, and do not @@ -7644,6 +7833,7 @@ NAME: dns_packet_max TYPE: b_ssize_t +DEFAULT_DOC: EDNS disabled DEFAULT: none LOC: Config.dns.packet_max IFDEF: !USE_DNSHELPER @@ -7674,6 +7864,7 @@ COMMENT: on|off TYPE: onoff DEFAULT: off +DEFAULT_DOC: Search for single-label domain names is disabled. LOC: Config.onoff.res_defnames DOC_START Normally the RES_DEFNAMES resolver option is disabled @@ -7685,11 +7876,13 @@ NAME: dns_nameservers TYPE: wordlist DEFAULT: none +DEFAULT_DOC: Use operating system definitions 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 @@ -7731,6 +7924,7 @@ TYPE: string LOC: Config.appendDomain DEFAULT: none +DEFAULT_DOC: Use operating system definitions DOC_START Appends local domain name to hostnames without any dots in them. append_domain must begin with a period. @@ -7780,7 +7974,9 @@ TYPE: int DEFAULT: 1024 LOC: Config.ipcache.size -DOC_NONE +DOC_START + Maximum number of DNS IP cache entries. +DOC_END NAME: ipcache_low COMMENT: (percent) @@ -7881,6 +8077,7 @@ NAME: cachemgr_passwd TYPE: cachemgrpasswd DEFAULT: none +DEFAULT_DOC: No password. Actions which require password are denied. LOC: Config.passwd_list DOC_START Specify passwords for cachemgr operations. @@ -7988,6 +8185,7 @@ TYPE: int LOC: Config.connect_retries DEFAULT: 0 +DEFAULT_DOC: Do not retry failed connections. DOC_START This sets the maximum number of connection attempts made for each TCP connection. The connect_retries attempts must all still @@ -8048,20 +8246,32 @@ URI. Options: strip: The whitespace characters are stripped out of the URL. - This is the behavior recommended by RFC2396. + This is the behavior recommended by RFC2396 and RFC3986 + for tolerant handling of generic URI. + NOTE: This is one difference between generic URI and HTTP URLs. + deny: The request is denied. The user receives an "Invalid Request" message. + This is the behaviour recommended by RFC2616 for safe + handling of HTTP request URL. + allow: The request is allowed and the URI is not changed. The whitespace characters remain in the URI. Note the whitespace is passed to redirector processes if they are in use. + Note this may be considered a violation of RFC2616 + request parsing where whitespace is prohibited in the + URL field. + encode: The request is allowed and the whitespace characters are - encoded according to RFC1738. This could be considered - a violation of the HTTP/1.1 - RFC because proxies are not allowed to rewrite URI's. + encoded according to RFC1738. + chop: The request is allowed and the URI is chopped at the - first whitespace. This might also be considered a - violation. + first whitespace. + + + NOTE the current Squid implementation of encode and chop violates + RFC2616 by not using a 301 redirect after altering the URL. DOC_END NAME: chroot @@ -8112,6 +8322,7 @@ COMMENT: (msec) LOC: Config.warnings.high_rptm DEFAULT: 0 +DEFAULT_DOC: disabled. DOC_START If the one-minute median response time exceeds this value, Squid prints a WARNING with debug level 0 to get the @@ -8122,6 +8333,7 @@ TYPE: int LOC: Config.warnings.high_pf DEFAULT: 0 +DEFAULT_DOC: disabled. DOC_START If the one-minute average page fault rate exceeds this value, Squid prints a WARNING with debug level 0 to get @@ -8133,6 +8345,7 @@ TYPE: b_size_t LOC: Config.warnings.high_memory DEFAULT: 0 KB +DEFAULT_DOC: disabled. DOC_START If the memory usage (as determined by mallinfo) exceeds this amount, Squid prints a WARNING with debug level 0 to get @@ -8184,20 +8397,23 @@ NAME: max_filedescriptors max_filedesc TYPE: int DEFAULT: 0 +DEFAULT_DOC: Use operating system limits set by ulimit. LOC: Config.max_filedescriptors DOC_START - The maximum number of filedescriptors supported. + Reduce the maximum number of filedescriptors supported below + the usual operating system defaults. - The default "0" means Squid inherits the current ulimit setting. + Remove from squid.conf to inherit the current ulimit setting. Note: Changing this requires a restart of Squid. Also - not all comm loops supports large values. + not all I/O types supports large values (eg on Windows). DOC_END NAME: workers TYPE: int LOC: Config.workers DEFAULT: 1 +DEFAULT_DOC: SMP support disabled. DOC_START Number of main Squid processes or "workers" to fork and maintain. 0: "no daemon" mode, like running "squid -N ..." @@ -8212,6 +8428,7 @@ TYPE: CpuAffinityMap LOC: Config.cpuAffinityMap DEFAULT: none +DEFAULT_DOC: Let operating system decide. DOC_START Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,... === modified file 'src/cf_gen.cc' --- src/cf_gen.cc 2012-10-28 05:27:14 +0000 +++ src/cf_gen.cc 2013-04-27 02:23:20 +0000 @@ -189,6 +189,13 @@ exit(1); } +static void +errorMsg(const char *filename, int line, const char *detail) +{ + std::cerr << "Error in '" << filename << "' on line " << line << + "--> " << detail << std::endl; +} + int main(int argc, char *argv[]) { @@ -218,7 +225,7 @@ *-------------------------------------------------------------------*/ fp.open(type_depend, std::ifstream::in); if (fp.fail()) { - std::cerr << "error while opening type dependencies file '" << + std::cerr << "Error while opening type dependencies file '" << type_depend << "': " << strerror(errno) << std::endl; exit(1); } @@ -245,7 +252,7 @@ /* Open input file */ fp.open(input_filename, std::ifstream::in); if (fp.fail()) { - std::cerr << "error while opening input file '" << + std::cerr << "Error while opening input file '" << input_filename << "': " << strerror(errno) << std::endl; exit(1); } @@ -262,14 +269,14 @@ if (strncmp(buff, "IF ", 3) == 0) { if ((ptr = strtok(buff + 3, WS)) == NULL) { - std::cerr << "Missing IF parameter on line" << linenum << std::endl; + errorMsg(input_filename, linenum, "Missing IF parameter"); exit(1); } IFDEFS.push(ptr); continue; } else if (strcmp(buff, "ENDIF") == 0) { if (IFDEFS.size() == 0) { - std::cerr << "ENDIF without IF before on line " << linenum << std::endl; + errorMsg(input_filename, linenum, "ENDIF without IF first"); exit(1); } IFDEFS.pop(); @@ -285,7 +292,7 @@ char *name, *aliasname; if ((name = strtok(buff + 5, WS)) == NULL) { - std::cerr << "Error in input file\n"; + errorMsg(input_filename, linenum, buff); exit(1); } @@ -302,8 +309,7 @@ entries.back().loc = "none"; state = sDOC; } else { - std::cerr << "Error on line " << linenum << std::endl << - "--> " << buff << std::endl; + errorMsg(input_filename, linenum, buff); exit(1); } @@ -352,14 +358,14 @@ curr.defaults.docs.push_back(ptr); } else if (!strncmp(buff, "LOC:", 4)) { if ((ptr = strtok(buff + 4, WS)) == NULL) { - std::cerr << "Error on line " << linenum << std::endl; + errorMsg(input_filename, linenum, buff); exit(1); } curr.loc = ptr; } else if (!strncmp(buff, "TYPE:", 5)) { if ((ptr = strtok(buff + 5, WS)) == NULL) { - std::cerr << "Error on line " << linenum << std::endl; + errorMsg(input_filename, linenum, buff); exit(1); } @@ -373,7 +379,7 @@ curr.type = ptr; } else if (!strncmp(buff, "IFDEF:", 6)) { if ((ptr = strtok(buff + 6, WS)) == NULL) { - std::cerr << "Error on line " << linenum << std::endl; + errorMsg(input_filename, linenum, buff); exit(1); } @@ -383,7 +389,7 @@ } else if (!strcmp(buff, "DOC_NONE")) { state = sSTART; } else { - std::cerr << "Error on line " << linenum << std::endl; + errorMsg(input_filename, linenum, buff); exit(1); } } @@ -417,7 +423,7 @@ } if (state != sEXIT) { - std::cerr << "Error: unexpected EOF\n"; + errorMsg(input_filename, linenum, "Error: unexpected EOF"); exit(1); } @@ -435,7 +441,7 @@ std::ofstream fout(output_filename,std::ostream::out); if (!fout.good()) { - std::cerr << "error while opening output .c file '" << + std::cerr << "Error while opening output .c file '" << output_filename << "': " << strerror(errno) << std::endl; exit(1); } @@ -466,7 +472,7 @@ /* Open output x.conf file */ fout.open(conf_filename,std::ostream::out); if (!fout.good()) { - std::cerr << "error while opening output conf file '" << + std::cerr << "Error while opening output conf file '" << output_filename << "': " << strerror(errno) << std::endl; exit(1); } @@ -477,7 +483,7 @@ fout.open(conf_filename_short,std::ostream::out); if (!fout.good()) { - std::cerr << "error while opening output short conf file '" << + std::cerr << "Error while opening output short conf file '" << output_filename << "': " << strerror(errno) << std::endl; exit(1); } === modified file 'src/client_side.cc' --- src/client_side.cc 2013-03-29 05:59:17 +0000 +++ src/client_side.cc 2013-04-27 02:23:20 +0000 @@ -2520,12 +2520,14 @@ debugs(33, 2, "SQUID_X509_V_ERR_DOMAIN_MISMATCH: Certificate " << "does not match domainname " << request->GetHost()); - ACLFilledChecklist check(Config.ssl_client.cert_error, request, dash_str); - check.sslErrors = new Ssl::Errors(SQUID_X509_V_ERR_DOMAIN_MISMATCH); - const bool allowDomainMismatch = - check.fastCheck() == ACCESS_ALLOWED; - delete check.sslErrors; - check.sslErrors = NULL; + bool allowDomainMismatch = false; + if (Config.ssl_client.cert_error) { + ACLFilledChecklist check(Config.ssl_client.cert_error, request, dash_str); + check.sslErrors = new Ssl::Errors(SQUID_X509_V_ERR_DOMAIN_MISMATCH); + allowDomainMismatch = (check.fastCheck() == ACCESS_ALLOWED); + delete check.sslErrors; + check.sslErrors = NULL; + } if (!allowDomainMismatch) { quitAfterError(request); === modified file 'src/icp_v2.cc' --- src/icp_v2.cc 2013-01-02 10:12:45 +0000 +++ src/icp_v2.cc 2013-04-27 02:23:20 +0000 @@ -429,9 +429,9 @@ bool icpAccessAllowed(Ip::Address &from, HttpRequest * icp_request) { - /* absent an explicit allow, we deny all */ + /* absent any explicit rules, we deny all */ if (!Config.accessList.icp) - return true; + return false; ACLFilledChecklist checklist(Config.accessList.icp, icp_request, NULL); checklist.src_addr = from; === modified file 'src/store_dir.cc' --- src/store_dir.cc 2013-03-04 20:10:29 +0000 +++ src/store_dir.cc 2013-04-27 02:23:20 +0000 @@ -240,7 +240,7 @@ * in the *tightest fit* swapdir to conserve space, along with the * actual swapdir usage. But for now, this hack will do while * testing, so you should order your swapdirs in the config file - * from smallest maxobjsize to unlimited (-1) maxobjsize. + * from smallest max-size= to largest max-size=. * * We also have to choose nleast == nconf since we need to consider * ALL swapdirs, regardless of state. Again, this is a hack while