]> git.ipfire.org Git - thirdparty/squid.git/commitdiff
Syncronized squid.conf comments with Squid-2
authorhno <>
Fri, 17 Aug 2007 09:30:39 +0000 (09:30 +0000)
committerhno <>
Fri, 17 Aug 2007 09:30:39 +0000 (09:30 +0000)
src/cf.data.pre

index 7389571603849af9c68b5698ad99040b6437d9cd..f6f1b36c3fd6555d1ca19e3b596562068ad5d45a 100644 (file)
@@ -1,6 +1,6 @@
 
 #
-# $Id: cf.data.pre,v 1.449 2007/08/16 16:12:29 hno Exp $
+# $Id: cf.data.pre,v 1.450 2007/08/17 03:30:39 hno Exp $
 #
 # SQUID Web Proxy Cache                http://www.squid-cache.org/
 # ----------------------------------------------------------
@@ -81,18 +81,20 @@ DOC_START
 
        Options:
 
-          transparent  Support for transparent proxies
+          transparent  Support for transparent interception of
+                       outgoing requests without browser settings.
 
-          accel        Accelerator mode. Also set implicit by the other
-                       accelerator directives
+          accel        Accelerator mode. Also needs at least one of
+                       vhost / vport / defaultsite.
 
           vhost        Accelerator mode using Host header for virtual
-                       domain support
+                       domain support. Implies accel.
 
-          vport        Accelerator with IP based virtual host support
+          vport        Accelerator with IP based virtual host support.
+                       Implies accel.
 
           vport=NN     As above, but uses specified port number rather
-                       than the http_port number
+                       than the http_port number. Implies accel.
 
           defaultsite=domainname
                        What to use for the Host: header if it is not present
@@ -101,11 +103,10 @@ DOC_START
                        Implies accel.
 
           protocol=    Protocol to reconstruct accelerated requests with.
-                       Defaults to http
+                       Defaults to http.
 
-          tproxy       Support Linux TPROXY for spoofing
-                       outgoing connections using the client
-                       IP address.
+          tproxy       Support Linux TPROXY for spoofing outgoing
+                       connections using the client IP address.
 
           disable-pmtu-discovery=
                        Control Path-MTU discovery usage:
@@ -114,13 +115,14 @@ DOC_START
                                        support is enabled.
                            always      disable always PMTU discovery.
 
-       In many setups of transparently intercepting proxies Path-MTU
-       discovery can not work on traffic towards the clients. This is
-       the case when the intercepting device does not fully track
-       connections and fails to forward ICMP must fragment messages
-       to the cache server. If you have such setup and experience that
-       certain clients sporadically hang or never complete requests set
-       disable-pmtu-discovery option to 'transparent'.
+                       In many setups of transparently intercepting proxies
+                       Path-MTU discovery can not work on traffic towards the
+                       clients. This is the case when the intercepting device
+                       does not fully track connections and fails to forward
+                       ICMP must fragment messages to the cache server. If you
+                       have such setup and experience that certain clients
+                       sporadically hang or never complete requests set
+                       disable-pmtu-discovery option to 'transparent'.
 
        If you run Squid on a dual-homed machine with an internal
        and an external interface we recommend you to specify the
@@ -160,17 +162,19 @@ DOC_START
                        this port. Implies accel.
 
           vhost        Accelerator mode using Host header for virtual
-                       domain support. Implies accel.
-       
+                       domain support. Requires a wildcard certificate
+                       or other certificate valid for more than one domain.
+                       Implies accel.
+
           protocol=    Protocol to reconstruct accelerated requests with.
                        Defaults to https.
 
-          cert=        Path to SSL certificate (PEM format)
+          cert=        Path to SSL certificate (PEM format).
 
           key=         Path to SSL private key file (PEM format)
                        if not specified, the certificate file is
                        assumed to be a combined certificate and
-                       key file
+                       key file.
 
           version=     The version of SSL/TLS supported
                            1   automatic (default)
@@ -178,7 +182,7 @@ DOC_START
                            3   SSLv3 only
                            4   TLSv1 only
 
-          cipher=      Colon separated list of supported ciphers
+          cipher=      Colon separated list of supported ciphers.
 
           options=     Various SSL engine options. The most important
                        being:
@@ -188,49 +192,49 @@ DOC_START
                            SINGLE_DH_USE Always create a new key when using
                                      temporary/ephemeral DH key exchanges
                        See src/ssl_support.c or OpenSSL SSL_CTX_set_options
-                       documentation for a complete list of options
+                       documentation for a complete list of options.
 
           clientca=    File containing the list of CAs to use when
-                       requesting a client certificate
+                       requesting a client certificate.
 
           cafile=      File containing additional CA certificates to
                        use when verifying client certificates. If unset
                        clientca will be used.
 
           capath=      Directory containing additional CA certificates
-                       and CRL lists to use when verifying client certificates
+                       and CRL lists to use when verifying client certificates.
 
           crlfile=     File of additional CRL lists to use when verifying
                        the client certificate, in addition to CRLs stored in
                        the capath. Implies VERIFY_CRL flag below.
 
           dhparams=    File containing DH parameters for temporary/ephemeral
-                       DH key exchanges
+                       DH key exchanges.
 
           sslflags=    Various flags modifying the use of SSL:
                            DELAYED_AUTH
                                Don't request client certificates
                                immediately, but wait until acl processing
-                               requires a certificate (not yet implemented)
+                               requires a certificate (not yet implemented).
                            NO_DEFAULT_CA
                                Don't use the default CA lists built in
-                               to OpenSSL
+                               to OpenSSL.
                            NO_SESSION_REUSE
                                Don't allow for session reuse. Each connection
                                will result in a new SSL session.
                            VERIFY_CRL
                                Verify CRL lists when accepting client
-                               certificates
+                               certificates.
                            VERIFY_CRL_ALL
                                Verify CRL lists for all certificates in the
-                               client certificate chain
+                               client certificate chain.
 
           sslcontext=  SSL session ID context identifier.
 
-          vport        Accelerator with IP based virtual host support
+          vport        Accelerator with IP based virtual host support.
 
           vport=NN     As above, but uses specified port number rather
-                       than the https_port number. Implies accel
+                       than the https_port number. Implies accel.
 
 DOC_END
 
@@ -481,7 +485,7 @@ DOC_START
                     connect-timeout=nn
                     digest-url=url
                     allow-miss
-                    max-conn
+                    max-conn=n
                     htcp
                     htcp-oldsquid
                     originserver
@@ -607,7 +611,7 @@ DOC_START
                     requests from peer by denying cache_peer_access if the
                     source is a peer)
 
-                    use 'max-conn' to limit the amount of connections Squid
+                    use 'max-conn=n' to limit the amount of connections Squid
                     may open to this peer.
 
                     use 'htcp' to send HTCP, instead of ICP, queries
@@ -648,8 +652,8 @@ DOC_START
                        3 = SSL v3 only
                        4 = TLS v1 only
 
-                    use sslcipher=... to specify the list of valid SSL chipers
-                    to use when connecting to this peer
+                    use sslcipher=... to specify the list of valid SSL ciphers
+                    to use when connecting to this peer.
 
                     use ssloptions=... to specify various SSL engine options:
                        NO_SSLv2  Disallow the use of SSLv2
@@ -658,12 +662,15 @@ DOC_START
                     See src/ssl_support.c or the OpenSSL documentation for
                     a more complete list.
 
-                    use cafile=... to specify a file containing additional
+                    use sslcafile=... to specify a file containing additional
                     CA certificates to use when verifying the peer certificate
 
-                    use capath=... to specify a directory containing additional
+                    use sslcapath=... to specify a directory containing additional
                     CA certificates to use when verifying the peer certificate
 
+                    use sslcrlfile=... to specify a certificate revocation
+                    list file to use when verifying the peer certificate.
+                    
                     use sslflags=... to specify various flags modifying the
                     SSL implementation:
                        DONT_VERIFY_PEER
@@ -676,7 +683,7 @@ DOC_START
                                Don't verify the peer certificate
                                matches the server name
 
-                    use sslname= to specify the peer name as advertised
+                    use ssldomain= to specify the peer name as advertised
                     in it's certificate. Used for verifying the correctness
                     of the received peer certificate. If not specified the
                     peer hostname will be used.
@@ -687,8 +694,6 @@ DOC_START
                     on this header. If set to auto the header will
                     only be added if the request is forwarded as a https://
                     URL.
-
-       NOTE: non-ICP neighbors must be specified as 'parent'.
 DOC_END
 
 NAME: cache_peer_domain cache_host_domain
@@ -794,7 +799,7 @@ DEFAULT: 2000
 TYPE: int
 LOC: Config.Timeout.mcast_icp_query
 DOC_START
-       For Multicast peers, Squid regularly sends out ICP "probes" to
+       For multicast peers, Squid regularly sends out ICP "probes" to
        count how many other peers are listening on the given multicast
        address.  This value specifies how long Squid should wait to
        count all the replies.  The default is 2000 msec, or 2
@@ -832,6 +837,7 @@ DOC_START
        be handled directly by this cache.  In other words, use this
        to not query neighbor caches for certain objects.  You may
        list this option multiple times.
+       Note: never_direct overrides this option.
 NOCOMMENT_START
 #We recommend you to use at least the following line.
 hierarchy_stoplist cgi-bin ?
@@ -1156,6 +1162,10 @@ DOC_START
        called 'stripe' in the directory names in the config - and
        this will be created by squid -z.
 
+       The null store type:
+
+       no options are allowed or required
+
        Common options:
 
        no-store, no new objects should be stored to this cache_dir
@@ -1169,10 +1179,6 @@ DOC_START
        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.
-
-       The null store type:
-
-       no options are allowed or required
 DOC_END
 
 NAME: logformat
@@ -1217,18 +1223,19 @@ DOC_START
                ts      Seconds since epoch
                tu      subsecond time (milliseconds)
                tl      Local time. Optional strftime format argument
-                       default %d/%b/%Y:%H:%M:S %z
+                       default %d/%b/%Y:%H:%M:%S %z
                tg      GMT time. Optional strftime format argument
-                       default %d/%b/%Y:%H:%M:S %z
+                       default %d/%b/%Y:%H:%M:%S %z
                tr      Response time (milliseconds)
                >h      Request header. Optional header name argument
                        on the format header[:[separator]element]
                <h      Reply header. Optional header name argument
                        as for >h
                un      User name
-               ul      User login
-               ui      User ident
-               ue      User from external acl
+               ul      User name from authentication
+               ui      User name from ident
+               us      User name from SSL
+               ue      User name from external acl helper
                Hs      HTTP status code
                Ss      Squid request status (TCP_MISS etc)
                Sh      Squid hierarchy status (DEFAULT_PARENT etc)
@@ -1254,7 +1261,6 @@ NAME: access_log cache_access_log
 TYPE: access_log
 LOC: Config.Log.accesslogs
 DEFAULT: none
-DEFAULT_IF_NONE: @DEFAULT_ACCESS_LOG@
 DOC_START
        These files log client request activities. Has a line every HTTP or
        ICP request. The format is:
@@ -1277,6 +1283,9 @@ DOC_START
 
        And priority could be any of:
        LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
+NOCOMMENT_START
+access_log @DEFAULT_ACCESS_LOG@ squid
+NOCOMMENT_END
 DOC_END
 
 NAME: cache_log
@@ -1329,10 +1338,10 @@ DOC_START
        The numbered extension (which is added automatically)
        corresponds to the order of the 'cache_dir' lines in this
        configuration file.  If you change the order of the 'cache_dir'
-       lines in this file, these log files will NOT correspond to
+       lines in this file, these index files will NOT correspond to
        the correct 'cache_dir' entry (unless you manually rename
        them).  We recommend you do NOT use this option.  It is
-       better to keep these log files in each 'cache_dir' directory.
+       better to keep these index files in each 'cache_dir' directory.
 DOC_END
 
 NAME: emulate_httpd_log
@@ -1393,7 +1402,7 @@ DOC_START
        is disabled.
 DOC_END
 
-NAME: referer_log
+NAME: referer_log referrer_log
 TYPE: string
 LOC: Config.Log.referer
 DEFAULT: none
@@ -1401,6 +1410,9 @@ IFDEF: USE_REFERER_LOG
 DOC_START
        Squid will write the Referer field from HTTP requests to the
        filename specified here.  By default referer_log is disabled.
+       Note that "referer" is actually a misspelling of "referrer"
+       however the misspelt version has been accepted into the HTTP RFCs
+       and we accept both.
 DOC_END
 
 NAME: pid_filename
@@ -1532,7 +1544,7 @@ TYPE: onoff
 DEFAULT: on
 LOC: Config.onoff.allow_underscore
 DOC_START
-       Underscore characers is not strictly allowed in Internet hostnames
+       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.
        This check is performed only when check_hostnames is set to on.
@@ -1574,7 +1586,7 @@ DOC_END
 
 NAME: dns_timeout
 TYPE: time_t
-DEFAULT: 5 minutes
+DEFAULT: 2 minutes
 LOC: Config.Timeout.idns_query
 IFDEF: !USE_DNSSERVERS
 DOC_START
@@ -1673,10 +1685,21 @@ TYPE: wordlist
 LOC: Config.Program.redirect
 DEFAULT: none
 DOC_START
-       Specify the location of the executable for the URL redirector.
+       Specify the location of the executable for the URL rewriter.
        Since they can perform almost any function there isn't one included.
-       See the FAQ (section 15) for information on how to write one.
-       By default, a redirector is not used.
+
+       For each requested URL rewriter will receive on line with the format
+
+       URL <SP> client_ip "/" fqdn <SP> user <SP> method <NL>
+
+       And the rewriter may return a rewritten URL. The other components of
+       the request line does not need to be returned (ignored if they are).
+
+       The rewriter can also indicate that a client-side redirect should
+       be performed to the new URL. This is done by prefixing the returned
+       URL with "301:" (moved permanently) or 302: (moved temporarily).
+
+       By default, a URL rewriter is not used.
 DOC_END
 
 NAME: url_rewrite_children redirect_children
@@ -1696,8 +1719,8 @@ DEFAULT: 0
 LOC: Config.redirectConcurrency
 DOC_START
        The number of requests each redirector helper can handle in
-       parallell. Defaults to 0 which indicates the redirector
-       is a old-style singlethreaded redirector.
+       parallel. Defaults to 0 which indicates the redirector
+       is a old-style single threaded redirector.
 DOC_END
 
 NAME: url_rewrite_host_header redirect_rewrites_host_header
@@ -1728,61 +1751,74 @@ TYPE: authparam
 LOC: Config.authConfiguration
 DEFAULT: none
 DOC_START
-       This is used to pass parameters to the various authentication
-       schemes.
-       format: auth_param scheme parameter [setting]
-
-       auth_param basic program @DEFAULT_PREFIX@/bin/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
-       would tell the basic authentication scheme it's program parameter.
+       This is used to define parameters for the various authentication
+       schemes supported by Squid.
 
-       The order authentication prompts are presented to the client_agent
-       is dependent on the order the scheme first appears in config file.
-       IE has a bug (it's not rfc 2617 compliant) in that it will use the basic
-       scheme if basic is the first entry presented, even if more secure schemes
-       are presented. For now use the order in the file below. If other browsers
-       have difficulties (don't recognize the schemes offered even if you are using
-       basic) either put basic first, or disable the other schemes (by commenting
-       out their program entry).
+       format: auth_param scheme parameter [setting]
 
-       Once an authentication scheme is fully configured, it can only be shutdown
-       by shutting squid down and restarting. Changes can be made on the fly and
-       activated with a reconfigure. I.E. You can change to a different helper,
-       but not unconfigure the helper completely.
+       The order in which authentication schemes are presented to the client is
+       dependent on the order the scheme first appears in config file. IE
+       has a bug (it's not RFC 2617 compliant) in that it will use the basic
+       scheme if basic is the first entry presented, even if more secure
+       schemes are presented. For now use the order in the recommended
+       settings section below. If other browsers have difficulties (don't
+       recognize the schemes offered even if you are using basic) either
+       put basic first, or disable the other schemes (by commenting out their
+       program entry).
+
+       Once an authentication scheme is fully configured, it can only be
+       shutdown by shutting squid down and restarting. Changes can be made on
+       the fly and activated with a reconfigure. I.E. You can change to a
+       different helper, but not unconfigure the helper completely.
+
+       Please note that while this directive defines how Squid processes
+       authentication it does not automatically activate authentication.
+       To use authentication you must in addition make use of ACLs based
+       on login name in http_access (proxy_auth, proxy_auth_regex or
+       external with %LOGIN used in the format tag). The browser will be
+       challenged for authentication on the first such acl encountered
+       in http_access processing and will also be re-challenged for new
+       login credentials if the request is being denied by a proxy_auth
+       type acl.
+
+       WARNING: authentication can't be used in a transparently intercepting
+       proxy as the client then thinks it is talking to an origin server and
+       not the proxy. This is a limitation of bending the TCP/IP protocol to
+       transparently intercepting port 80, not a limitation in Squid.
 
        === Parameters for the basic scheme follow. ===
 
        "program" cmdline
-       Specify the command for the external authenticator.  Such a
-       program reads a line containing "username password" and replies
+       Specify the command for the external authenticator.  Such a program
+       reads a line containing "username password" and replies "OK" or
        "ERR" in an endless loop. "ERR" responses may optionally be followed
        by a error description available as %m in the returned error page.
        If you use an authenticator, make sure you have 1 acl of type proxy_auth.
-       By default, the basic authentication scheme is not used unless a program
-       is specified.
 
-       If you want to use the traditional proxy authentication,
-       jump over to the ../helpers/basic_auth/NCSA directory and
-       type:
-               % make
-               % make install
+       By default, the basic authentication scheme is not used unless a
+       program is specified.
 
-       Then, set this line to something like
+       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
 
        "children" numberofchildren
-       The number of authenticator processes to spawn (no default).
-       If you start too few Squid will have to wait for them to
-       process a backlog of usercode/password verifications, slowing
-       it down. When password verifications are done via a (slow)
-       network you are likely to need lots of authenticator
-       processes.
+       The number of authenticator processes to spawn. If you start too few
+       Squid will have to wait for them to process a backlog of credential
+       verifications, slowing it down. When password verifications are
+       done via a (slow) network you are likely to need lots of
+       authenticator processes.
        auth_param basic children 5
 
        "concurrency" concurrency
        The number of concurrent requests the helper can process.
        The default of 0 is used for helpers who only supports
-       one request at a time.
+       one request at a time. Setting this changes the protocol used to
+       include a channel number first on the request/response line, allowing
+       multiple requests to be sent to the same helper in parallell without
+       wating for the response.
+       Must not be set unless it's known the helper supports this.
        auth_param basic concurrency 0
 
        "realm" realmstring
@@ -1821,16 +1857,11 @@ DOC_START
        "ERR" responses may optionally be followed by a error description
        available as %m in the returned error page.
 
-       By default, the digest authentication is not used unless a
+       By default, the digest authentication scheme is not used unless a
        program is specified.
 
-       If you want to use a digest authenticator, jump over to the
-       helpers/digest_auth/ directory and choose the authenticator
-       to use. In it's directory type
-               % make
-               % make install
-
-       Then, set this line to something like
+       If you want to use a digest authenticator, set this line to
+       something like
 
        auth_param digest program @DEFAULT_PREFIX@/bin/digest_auth_pw @DEFAULT_PREFIX@/etc/digpass
 
@@ -1969,10 +2000,10 @@ TYPE: time_t
 DEFAULT: 1 hour
 LOC: Config.authenticateGCInterval
 DOC_START
-       The time period between garbage collection across the
-       username cache.  This is a tradeoff between memory utilization
-       (long intervals - say 2 days) and CPU (short intervals -
-       say 1 minute). Only change if you have good reason to.
+       The time period between garbage collection across the username cache.
+       This is a tradeoff between memory utilization (long intervals - say
+       2 days) and CPU (short intervals - say 1 minute). Only change if you
+       have good reason to.
 DOC_END
 
 NAME: authenticate_ttl
@@ -2018,10 +2049,9 @@ DOC_START
                        TTL for cached negative lookups (default same
                        as ttl)
          children=n    Number of acl helper processes spawn to service
-                       external acl lookups of this type.
-         concurrency=n concurrency level per process. Use 0 for old style
-                       helpers who can only process a single request at a
-                       time.
+                       external acl lookups of this type. (default 5)
+         concurrency=n concurrency level per process. Only used with helpers
+                       capable of processing more than one query at a time.
          cache=n       result cache size, 0 is unbounded (default)
          grace=n       Percentage remaining of TTL where a refresh of a
                        cached entry should be initiated without needing to
@@ -2043,6 +2073,7 @@ DOC_START
          %METHOD       Request method
          %MYADDR       Squid interface address
          %MYPORT       Squid http_port number
+         %PATH         Requested URL-path (including query-string if any)
          %USER_CERT    SSL User certificate in PEM format
          %USER_CERTCHAIN SSL User certificate chain in PEM format
          %USER_CERT_xx SSL User certificate subject attribute xx
@@ -2054,15 +2085,14 @@ DOC_START
                        list separator. ; can be any non-alphanumeric
                        character.
 
-       In addition, any string specified in the referencing acl will
-       also be included in the helper request line, after the specified
-       formats (see the "acl external" directive)
+       In addition to the above, any string specified in the referencing
+       acl will also be included in the helper request line, after the
+       specified formats (see the "acl external" directive)
 
        The helper receives lines per the above format specification,
        and returns lines starting with OK or ERR indicating the validity
        of the request and optionally followed by additional keywords with
-       more details. To protect from odd characters the data is URL
-       escaped.
+       more details.
 
        General result syntax:
 
@@ -2079,11 +2109,16 @@ DOC_START
          log=          String to be logged in access.log. Available as
                        %ea in logformat specifications
 
-       Keyword values need to be URL escaped if they may contain
-       contain whitespace or quotes.
+       If protocol=3.0 (the default) then URL escaping is used to protect
+       each value in both requests and responses.
+
+       If using protocol=2.5 then all values need to be enclosed in quotes
+       if they may contain whitespace, or the whitespace escaped using \.
+       And quotes or \ characters within the keyword value must be \ escaped.
 
-       In Squid-2.5 compatibility mode quoting using " and \ is used
-       instead of URL escaping.
+       When using the concurrency= option the protocol is changed by
+       introducing a query channel tag infront of the request/response.
+       The query channel tag is a number between 0 and concurrency-1.
 DOC_END
 
 COMMENT_START
@@ -2186,9 +2221,9 @@ DOC_START
                liable for problems which it causes.
 
                ignore-auth caches responses to requests with authorization,
-               irrespective of ``Cache-control'' headers received from
-               a server. Doing this VIOLATES the HTTP standard. Enabling
-               this feature could make you liable for problems which
+               as if the originserver had sent ``Cache-control: public''
+               in the response header. Doing this VIOLATES the HTTP standard.
+               Enabling this feature could make you liable for problems which
                it causes.
 
                refresh-ims causes squid to contact the origin server
@@ -2297,18 +2332,21 @@ TYPE: time_t
 LOC: Config.positiveDnsTtl
 DEFAULT: 6 hours
 DOC_START
-       Time-to-Live (TTL) for positive caching of successful DNS lookups.
-       Default is 6 hours (360 minutes).  If you want to minimize the
-       use of Squid's ipcache, set this to 1, not 0.
+       Upper limit on how long Squid will cache positive DNS responses.
+       Default is 6 hours (360 minutes). This directive must be set
+       larger than negative_dns_ttl.
 DOC_END
 
 NAME: negative_dns_ttl
 COMMENT: time-units
 TYPE: time_t
 LOC: Config.negativeDnsTtl
-DEFAULT: 5 minutes
+DEFAULT: 1 minutes
 DOC_START
        Time-to-Live (TTL) for negative caching of failed DNS lookups.
+       This also sets the lower cache limit on positive lookups.
+       Minimum value is 1 second, and it is not recommendable to go
+       much below 10 seconds.
 DOC_END
 
 NAME: range_offset_limit
@@ -2605,12 +2643,12 @@ DOC_START
          # http_reply_access.
 
        acl aclname rep_header header-name [-i] any\.regex\.here
-         # regex match against any of the known reply headers.  May be
+         # regex match against any of the known reply headers. May be
          # thought of as a superset of "browser", "referer" and "mime-type"
          # ACLs.
 
        acl aclname req_mime_type mime-type1 ...
-         # regex match agains the mime type of the request generated
+         # regex match against the mime type of the request generated
          # by the client. Can be used to detect file upload or some
          # types HTTP tunneling requests.
          # NOTE: This does NOT match the reply. You cannot use this
@@ -2635,7 +2673,7 @@ DOC_START
 
        acl aclname ext_user username ...
        acl aclname ext_user_regex [-i] pattern ...
-         # string match on username returned by external acl processing
+         # string match on username returned by external acl helper
          # use REQUIRED to accept any non-null user name.
 
 Examples:
@@ -2877,13 +2915,21 @@ DOC_START
        tcp_outgoing_tos 0x20 good_service_net
 
        TOS/DSCP values really only have local significance - so you should
-       know what you're specifying. For more, see RFC 2474
+       know what you're specifying. For more information, see RFC2474 and
+       RFC3260.
 
-       The TOS/DSCP byte must be exactly that - a byte, value  0 - 255, or
-       "default" to use whatever default your host has.
+       The TOS/DSCP byte must be exactly that - a octet value  0 - 255, or
+       "default" to use whatever default your host has. Note that in
+       practice often only values 0 - 63 is usable as the two highest bits
+       have been redefined for use by ECN (RFC3168).
 
        Processing proceeds in the order specified, and stops at first fully
        matching line.
+
+       Note: The use of this directive using client dependent ACLs is
+       incompatible with the use of server side persistent connections. To
+       ensure correct results it is best to set server_persisten_connections
+       to off when using this directive in such configurations.
 DOC_END
 
 NAME: clientside_tos
@@ -2902,7 +2948,7 @@ DEFAULT: none
 LOC: Config.accessList.outgoing_address
 DOC_START
        Allows you to map requests to different outgoing IP addresses
-       based on the username or sourceaddress of the user making
+       based on the username or source address of the user making
        the request.
 
        tcp_outgoing_address ipaddr [[!]aclname] ...
@@ -2920,6 +2966,11 @@ DOC_START
 
        Processing proceeds in the order specified, and stops at first fully
        matching line.
+
+       Note: The use of this directive using client dependent ACLs is
+       incompatible with the use of server side persistent connections. To
+       ensure correct results it is best to set server_persistent_connections
+       to off when using this directive in such configurations.
 DOC_END
 
 NAME: reply_header_max_size
@@ -4020,8 +4071,7 @@ DEFAULT: 13 KB
 LOC: Config.Store.avgObjectSize
 DOC_START
        Average object size, used to estimate number of objects your
-       cache can hold.  See doc/Release-Notes-1.1.txt.  The default is
-       13 KB.
+       cache can hold.  The default is 13 KB.
 DOC_END
 
 NAME: store_objects_per_bucket
@@ -4154,8 +4204,9 @@ DOC_START
        Usage: always_direct allow|deny [!]aclname ...
 
        Here you can use ACL elements to specify requests which should
-       ALWAYS be forwarded directly to origin servers.  For example,
-       to always directly forward requests for local servers use
+       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:
 
                acl local-servers dstdomain my.domain.net
@@ -4177,6 +4228,15 @@ DOC_START
                always_direct deny local-external
                always_direct allow local-servers
 
+       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: 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
@@ -4455,10 +4515,6 @@ 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".
-
-       Note: If you want Squid to use parents for all requests see
-       the never_direct directive. prefer_direct only modifies how Squid
-       acts on cachable requests.
 DOC_END
 
 NAME: snmp_access
@@ -4618,7 +4674,7 @@ DOC_START
        Some HTTP servers has broken implementations of PUT/POST,
        and rely on an extra CRLF pair sent by some WWW clients.
 
-       Quote from RFC 2068 section 4.1 on this matter:
+       Quote from RFC2616 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
@@ -4680,7 +4736,7 @@ LOC: Config.onoff.nonhierarchical_direct
 DEFAULT: on
 DOC_START
        By default, Squid will send any non-hierarchical requests
-       (matching hierarchy_stoplist or not cachable request type) direct
+       (matching hierarchy_stoplist or not cacheable request type) direct
        to origin servers.
 
        If you set this to off, Squid will prefer to send these
@@ -4706,6 +4762,10 @@ DOC_START
        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: strip_query_terms
@@ -4770,8 +4830,8 @@ DOC_START
        Use this to have Squid do a chroot() while initializing.  This
        also causes Squid to fully drop root privileges after
        initializing.  This means, for example, if you use a HTTP
-       port less than 1024 and try to reconfigure, you will get an
-       error.
+       port less than 1024 and try to reconfigure, you will may get an
+       error saying that Squid can not open the port.
 DOC_END
 
 NAME: balance_on_multiple_ip
@@ -4819,7 +4879,10 @@ DOC_START
        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.
+       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
@@ -4926,7 +4989,7 @@ DOC_START
        processes, these sleep delays will add up and your
        Squid will not service requests for some amount of time
        until all the child processes have been started.
-       On Windows value less then 1000 (1 millisencond) are
+       On Windows value less then 1000 (1 milliseconds) are
        rounded to 1000.
 DOC_END