#
-# $Id: cf.data.pre,v 1.437 2007/05/22 17:12:38 rousskov Exp $
-#
+# $Id: cf.data.pre,v 1.492 2007/12/29 18:20:22 hno Exp $
#
# SQUID Web Proxy Cache http://www.squid-cache.org/
# ----------------------------------------------------------
COMMENT_END
COMMENT_START
- NETWORK OPTIONS
+ OPTIONS FOR AUTHENTICATION
-----------------------------------------------------------------------------
COMMENT_END
-NAME: http_port ascii_port
-TYPE: http_port_list
+NAME: auth_param
+TYPE: authparam
+LOC: Config.authConfiguration
DEFAULT: none
-LOC: Config.Sockaddr.http
DOC_START
- Usage: port [options]
- hostname:port [options]
- 1.2.3.4:port [options]
-
- The socket addresses where Squid will listen for HTTP client
- requests. You may specify multiple socket addresses.
- There are three forms: port alone, hostname with port, and
- IP address with port. If you specify a hostname or IP
- address, Squid binds the socket to that specific
- address. This replaces the old 'tcp_incoming_address'
- option. Most likely, you do not need to bind to a specific
- address, so you can use the port number alone.
+ This is used to define parameters for the various authentication
+ schemes supported by Squid.
- If you are running Squid in accelerator mode, you
- probably want to listen on port 80 also, or instead.
+ format: auth_param scheme parameter [setting]
- The -a command line option will override the *first* port
- number listed here. That option will NOT override an IP
- address, however.
+ 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.
- You may specify multiple socket addresses on multiple lines.
+ === Parameters for the basic scheme follow. ===
- Options:
+ "program" cmdline
+ Specify the command for the external authenticator. Such a program
+ reads a line containing "username password" and replies "OK" or
+ "ERR" in an endless loop. "ERR" responses may optionally be followed
+ by a error description available as %m in the returned error page.
+ If you use an authenticator, make sure you have 1 acl of type proxy_auth.
- transparent Support for transparent proxies
+ By default, the basic authentication scheme is not used unless a
+ program is specified.
- accel Accelerator mode. Also set implicit by the other
- accelerator directives
+ If you want to use the traditional NCSA proxy authentication, set
+ this line to something like
- vhost Accelerator mode using Host header for virtual
- domain support
+ auth_param basic program @DEFAULT_PREFIX@/libexec/ncsa_auth @DEFAULT_PREFIX@/etc/passwd
- vport Accelerator with IP based virtual host support
+ "children" numberofchildren
+ The number of authenticator processes to spawn. If you start too few
+ Squid will have to wait for them to process a backlog of credential
+ verifications, slowing it down. When password verifications are
+ done via a (slow) network you are likely to need lots of
+ authenticator processes.
+ auth_param basic children 5
- vport=NN As above, but uses specified port number rather
- than the http_port number
+ "concurrency" concurrency
+ The number of concurrent requests the helper can process.
+ The default of 0 is used for helpers who only supports
+ one request at a time. Setting this changes the protocol used to
+ include a channel number first on the request/response line, allowing
+ multiple requests to be sent to the same helper in parallell without
+ wating for the response.
+ Must not be set unless it's known the helper supports this.
+ auth_param basic concurrency 0
- defaultsite= Main web site name for accelerators
+ "realm" realmstring
+ Specifies the realm name which is to be reported to the
+ client for the basic proxy authentication scheme (part of
+ the text the user will see when prompted their username and
+ password). There is no default.
+ auth_param basic realm Squid proxy-caching web server
- protocol= Protocol to reconstruct accelerated requests with.
- Defaults to http
+ "credentialsttl" timetolive
+ Specifies how long squid assumes an externally validated
+ username:password pair is valid for - in other words how
+ often the helper program is called for that user. Set this
+ low to force revalidation with short lived passwords. Note
+ setting this high does not impact your susceptibility
+ to replay attacks unless you are using an one-time password
+ system (such as SecureID). If you are using such a system,
+ you will be vulnerable to replay attacks unless you also
+ use the max_user_ip ACL in an http_access rule.
- tproxy Support Linux TPROXY for spoofing
- outgoing connections using the client
- IP address.
+ "casesensitive" on|off
+ Specifies if usernames are case sensitive. Most user databases are
+ case insensitive allowing the same username to be spelled using both
+ lower and upper case letters, but some are case sensitive. This
+ makes a big difference for user_max_ip ACL processing and similar.
+ auth_param basic casesensitive off
- disable-pmtu-discovery=
- Control Path-MTU discovery usage:
- off lets OS decide on what to do (default).
- transparent disable PMTU discovery when transparent
- support is enabled.
- always disable always PMTU discovery.
+ === Parameters for the digest scheme follow ===
- 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'.
+ "program" cmdline
+ Specify the command for the external authenticator. Such
+ a program reads a line containing "username":"realm" and
+ replies with the appropriate H(A1) value hex encoded or
+ ERR if the user (or his H(A1) hash) does not exists.
+ See rfc 2616 for the definition of H(A1).
+ "ERR" responses may optionally be followed by a error description
+ available as %m in the returned error page.
- If you run Squid on a dual-homed machine with an internal
- and an external interface we recommend you to specify the
- internal address:port in http_port. This way Squid will only be
- visible on the internal address.
-NOCOMMENT_START
-# Squid normally listens to port 3128
-http_port @DEFAULT_HTTP_PORT@
-NOCOMMENT_END
-DOC_END
+ By default, the digest authentication scheme is not used unless a
+ program is specified.
-NAME: https_port
-IFDEF: USE_SSL
-TYPE: https_port_list
-DEFAULT: none
-LOC: Config.Sockaddr.https
-DOC_START
- Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...]
+ If you want to use a digest authenticator, set this line to
+ something like
- The socket address where Squid will listen for HTTPS client
- requests.
+ auth_param digest program @DEFAULT_PREFIX@/bin/digest_auth_pw @DEFAULT_PREFIX@/etc/digpass
- This is really only useful for situations where you are running
- squid in accelerator mode and you want to do the SSL work at the
- accelerator level.
+ "children" numberofchildren
+ The number of authenticator processes to spawn (no default).
+ If you start too few Squid will have to wait for them to
+ process a backlog of H(A1) calculations, slowing it down.
+ When the H(A1) calculations are done via a (slow) network
+ you are likely to need lots of authenticator processes.
+ auth_param digest children 5
- You may specify multiple socket addresses on multiple lines,
- each with their own SSL certificate and/or options.
+ "realm" realmstring
+ Specifies the realm name which is to be reported to the
+ client for the digest proxy authentication scheme (part of
+ the text the user will see when prompted their username and
+ password). There is no default.
+ auth_param digest realm Squid proxy-caching web server
- Options:
+ "nonce_garbage_interval" timeinterval
+ Specifies the interval that nonces that have been issued
+ to client_agent's are checked for validity.
- defaultsite= The name of the https site presented on
- this port
+ "nonce_max_duration" timeinterval
+ Specifies the maximum length of time a given nonce will be
+ valid for.
- protocol= Protocol to reconstruct accelerated requests
- with. Defaults to https
+ "nonce_max_count" number
+ Specifies the maximum number of times a given nonce can be
+ used.
- cert= Path to SSL certificate (PEM format)
+ "nonce_strictness" on|off
+ Determines if squid requires strict increment-by-1 behavior
+ for nonce counts, or just incrementing (off - for use when
+ useragents generate nonce counts that occasionally miss 1
+ (ie, 1,2,4,6)). Default off.
- 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
+ "check_nonce_count" on|off
+ This directive if set to off can disable the nonce count check
+ completely to work around buggy digest qop implementations in
+ certain mainstream browser versions. Default on to check the
+ nonce count to protect from authentication replay attacks.
- version= The version of SSL/TLS supported
- 1 automatic (default)
- 2 SSLv2 only
- 3 SSLv3 only
- 4 TLSv1 only
+ "post_workaround" on|off
+ This is a workaround to certain buggy browsers who sends
+ an incorrect request digest in POST requests when reusing
+ the same nonce as acquired earlier on a GET request.
- cipher= Colon separated list of supported ciphers
+ === NTLM scheme options follow ===
- options= Various SSL engine options. The most important
- being:
- NO_SSLv2 Disallow the use of SSLv2
- NO_SSLv3 Disallow the use of SSLv3
- NO_TLSv1 Disallow the use of TLSv1
- 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
+ "program" cmdline
+ Specify the command for the external NTLM authenticator.
+ Such a program reads exchanged NTLMSSP packets with
+ the browser via Squid until authentication is completed.
+ If you use an NTLM authenticator, make sure you have 1 acl
+ of type proxy_auth. By default, the NTLM authenticator_program
+ is not used.
- clientca= File containing the list of CAs to use when
- requesting a client certificate
+ auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
- cafile= File containing additional CA certificates to
- use when verifying client certificates. If unset
- clientca will be used
+ "children" numberofchildren
+ The number of authenticator processes to spawn (no default).
+ If you start too few Squid will have to wait for them to
+ process a backlog of credential verifications, slowing it
+ down. When credential verifications are done via a (slow)
+ network you are likely to need lots of authenticator
+ processes.
- capath= Directory containing additional CA certificates
- and CRL lists to use when verifying client certificates
+ auth_param ntlm children 5
- 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.
+ "keep_alive" on|off
+ If you experience problems with PUT/POST requests when using the
+ Negotiate authentication scheme then you can try setting this to
+ off. This will cause Squid to forcibly close the connection on
+ the initial requests where the browser asks which schemes are
+ supported by the proxy.
- dhparams= File containing DH parameters for temporary/ephemeral
- DH key exchanges
+ auth_param ntlm keep_alive on
- 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)
- NO_DEFAULT_CA
- Don't use the default CA lists built in
- 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
- VERIFY_CRL_ALL
- Verify CRL lists for all certificates in the
- client certificate chain
+ === Options for configuring the NEGOTIATE auth-scheme follow ===
- sslcontext= SSL session ID context identifier.
+ "program" cmdline
+ Specify the command for the external Negotiate authenticator.
+ This protocol is used in Microsoft Active-Directory enabled setups with
+ the Microsoft Internet Explorer or Mozilla Firefox browsers.
+ Its main purpose is to exchange credentials with the Squid proxy
+ using the Kerberos mechanisms.
+ If you use a Negotiate authenticator, make sure you have at least one acl
+ of type proxy_auth active. By default, the negotiate authenticator_program
+ is not used.
+ The only supported program for this role is the ntlm_auth
+ program distributed as part of Samba, version 4 or later.
- accel Accelerator mode. Also set implicit by the other
- accelerator directives
+ auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
- vhost Accelerator mode using Host header for virtual
- domain support
+ "children" numberofchildren
+ The number of authenticator processes to spawn (no default).
+ If you start too few Squid will have to wait for them to
+ process a backlog of credential verifications, slowing it
+ down. When crendential verifications are done via a (slow)
+ network you are likely to need lots of authenticator
+ processes.
+ auth_param negotiate children 5
- vport Accelerator with IP based virtual host support
+ "keep_alive" on|off
+ If you experience problems with PUT/POST requests when using the
+ Negotiate authentication scheme then you can try setting this to
+ off. This will cause Squid to forcibly close the connection on
+ the initial requests where the browser asks which schemes are
+ supported by the proxy.
- vport=NN As above, but uses specified port number rather
- than the https_port number
+ auth_param negotiate keep_alive on
+NOCOMMENT_START
+#Recommended minimum configuration per scheme:
+#auth_param negotiate program <uncomment and complete this line to activate>
+#auth_param negotiate children 5
+#auth_param negotiate keep_alive on
+#auth_param ntlm program <uncomment and complete this line to activate>
+#auth_param ntlm children 5
+#auth_param ntlm keep_alive on
+#auth_param digest program <uncomment and complete this line>
+#auth_param digest children 5
+#auth_param digest realm Squid proxy-caching web server
+#auth_param digest nonce_garbage_interval 5 minutes
+#auth_param digest nonce_max_duration 30 minutes
+#auth_param digest nonce_max_count 50
+#auth_param basic program <uncomment and complete this line>
+#auth_param basic children 5
+#auth_param basic realm Squid proxy-caching web server
+#auth_param basic credentialsttl 2 hours
+NOCOMMENT_END
DOC_END
-NAME: ssl_unclean_shutdown
-IFDEF: USE_SSL
-TYPE: onoff
-DEFAULT: off
-LOC: Config.SSL.unclean_shutdown
-DOC_START
- Some browsers (especially MSIE) bugs out on SSL shutdown
- messages.
-DOC_END
-
-NAME: ssl_engine
-IFDEF: USE_SSL
-TYPE: string
-LOC: Config.SSL.ssl_engine
-DEFAULT: none
+NAME: authenticate_cache_garbage_interval
+TYPE: time_t
+DEFAULT: 1 hour
+LOC: Config.authenticateGCInterval
DOC_START
- The openssl engine to use. You will need to set this if you
- would like to use hardware SSL acceleration for example.
+ 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: sslproxy_client_certificate
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cert
-TYPE: string
+NAME: authenticate_ttl
+TYPE: time_t
+DEFAULT: 1 hour
+LOC: Config.authenticateTTL
DOC_START
- Client SSL Certificate to use when proxying https:// URLs
+ The time a user & their credentials stay in the logged in
+ user cache since their last request. When the garbage
+ interval passes, all user credentials that have passed their
+ TTL are removed from memory.
DOC_END
-NAME: sslproxy_client_key
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.key
-TYPE: string
+NAME: authenticate_ip_ttl
+TYPE: time_t
+LOC: Config.authenticateIpTTL
+DEFAULT: 0 seconds
DOC_START
- Client SSL Key to use when proxying https:// URLs
+ If you use proxy authentication and the 'max_user_ip' ACL,
+ this directive controls how long Squid remembers the IP
+ addresses associated with each user. Use a small value
+ (e.g., 60 seconds) if your users might change addresses
+ quickly, as is the case with dialups. You might be safe
+ using a larger value (e.g., 2 hours) in a corporate LAN
+ environment with relatively static address assignments.
DOC_END
-NAME: sslproxy_version
-IFDEF: USE_SSL
-DEFAULT: 1
-LOC: Config.ssl_client.version
-TYPE: int
-DOC_START
- SSL version level to use when proxying https:// URLs
-DOC_END
+COMMENT_START
+ ACCESS CONTROLS
+ -----------------------------------------------------------------------------
+COMMENT_END
-NAME: sslproxy_options
-IFDEF: USE_SSL
+NAME: external_acl_type
+TYPE: externalAclHelper
+LOC: Config.externalAclHelperList
DEFAULT: none
-LOC: Config.ssl_client.options
-TYPE: string
DOC_START
- SSL engine options to use when proxying https:// URLs
-DOC_END
+ This option defines external acl classes using a helper program
+ to look up the status
-NAME: sslproxy_cipher
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cipher
-TYPE: string
-DOC_START
- SSL cipher list to use when proxying https:// URLs
-DOC_END
+ external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
-NAME: sslproxy_cafile
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.cafile
-TYPE: string
-DOC_START
- file containing CA certificates to use when verifying server
- certificates while proxying https:// URLs
-DOC_END
+ Options:
-NAME: sslproxy_capath
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.capath
-TYPE: string
-DOC_START
- directory containing CA certificates to use when verifying
- server certificates while proxying https:// URLs
-DOC_END
+ ttl=n TTL in seconds for cached results (defaults to 3600
+ for 1 hour)
+ negative_ttl=n
+ TTL for cached negative lookups (default same
+ as ttl)
+ children=n Number of acl helper processes spawn to service
+ external acl lookups of this type. (default 5)
+ concurrency=n concurrency level per process. Only used with helpers
+ capable of processing more than one query at a time.
+ cache=n result cache size, 0 is unbounded (default)
+ grace=n Percentage remaining of TTL where a refresh of a
+ cached entry should be initiated without needing to
+ wait for a new reply. (default 0 for no grace period)
+ protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
+ ipv4 / ipv6 IP-mode used to communicate to this helper.
+ For compatability with older configurations and helpers
+ 'ipv4' is the default unless --with-localhost-ipv6 is used.
+ --with-localhost-ipv6 changes the default to 'ipv6'.
+ SPECIAL NOTE: these options override --with-localhost-ipv6
-NAME: sslproxy_flags
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.ssl_client.flags
-TYPE: string
-DOC_START
- Various flags modifying the use of SSL while proxying https:// URLs:
- DONT_VERIFY_PEER Accept certificates even if they fail to
- verify.
- NO_DEFAULT_CA Don't use the default CA list built in
- to OpenSSL.
-DOC_END
+ FORMAT specifications
-NAME: sslpassword_program
-IFDEF: USE_SSL
-DEFAULT: none
-LOC: Config.Program.ssl_password
-TYPE: string
-DOC_START
- Specify a program used for entering SSL key passphrases
- when using encrypted SSL certificate keys. If not specified
- keys must either be unencrypted, or Squid started with the -N
- option to allow it to query interactively for the passphrase.
-DOC_END
+ %LOGIN Authenticated user login name
+ %EXT_USER Username from external acl
+ %IDENT Ident user name
+ %SRC Client IP
+ %SRCPORT Client source port
+ %URI Requested URI
+ %DST Requested host
+ %PROTO Requested protocol
+ %PORT Requested port
+ %PATH Requested URL path
+ %METHOD Request method
+ %MYADDR Squid interface address
+ %MYPORT Squid http_port number
+ %PATH Requested URL-path (including query-string if any)
+ %USER_CERT SSL User certificate in PEM format
+ %USER_CERTCHAIN SSL User certificate chain in PEM format
+ %USER_CERT_xx SSL User certificate subject attribute xx
+ %USER_CA_xx SSL User certificate issuer attribute xx
+ %{Header} HTTP request header
+ %{Hdr:member} HTTP request header list member
+ %{Hdr:;member}
+ HTTP request header list member using ; as
+ list separator. ; can be any non-alphanumeric
+ character.
-NAME: icp_port udp_port
-TYPE: ushort
-DEFAULT: 0
-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).
-NOCOMMENT_START
-icp_port @DEFAULT_ICP_PORT@
-NOCOMMENT_END
-DOC_END
+ In addition to the above, any string specified in the referencing
+ acl will also be included in the helper request line, after the
+ specified formats (see the "acl external" directive)
-NAME: htcp_port
-IFDEF: USE_HTCP
-TYPE: ushort
-DEFAULT: 4827
-LOC: Config.Port.htcp
-DOC_START
- The port number where Squid sends and receives HTCP queries to
- and from neighbor caches. Default is 4827. To disable use
- "0".
-DOC_END
+ 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.
+ General result syntax:
-NAME: mcast_groups
-TYPE: wordlist
-LOC: Config.mcast_group_list
-DEFAULT: none
-DOC_START
- This tag specifies a list of multicast groups which your server
- should join to receive multicasted ICP queries.
+ OK/ERR keyword=value ...
- NOTE! Be very careful what you put here! Be sure you
- understand the difference between an ICP _query_ and an ICP
- _reply_. This option is to be set only if you want to RECEIVE
- multicast queries. Do NOT set this option to SEND multicast
- ICP (use cache_peer for that). ICP replies are always sent via
- unicast, so this option does not affect whether or not you will
- receive replies from multicast group members.
+ Defined keywords:
- You must be very careful to NOT use a multicast address which
- is already in use by another group of caches.
+ user= The users name (login)
+ password= The users password (for login= cache_peer option)
+ message= Message describing the reason. Available as %o
+ in error pages
+ tag= Apply a tag to a request (for both ERR and OK results)
+ Only sets a tag, does not alter existing tags.
+ log= String to be logged in access.log. Available as
+ %ea in logformat specifications
- If you are unsure about multicast, please read the Multicast
- chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
+ If protocol=3.0 (the default) then URL escaping is used to protect
+ each value in both requests and responses.
- Usage: mcast_groups 239.128.16.128 224.0.1.20
+ 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.
- By default, Squid doesn't listen on any multicast groups.
+ 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
-
-NAME: udp_incoming_address
-TYPE: address
-LOC:Config.Addrs.udp_incoming
-DEFAULT: 0.0.0.0
-DOC_NONE
-
-NAME: udp_outgoing_address
-TYPE: address
-LOC: Config.Addrs.udp_outgoing
-DEFAULT: 255.255.255.255
+NAME: acl
+TYPE: acl
+LOC: Config.aclList
+DEFAULT: all src all
DOC_START
- udp_incoming_address is used for the ICP socket receiving packets
- from other caches.
- udp_outgoing_address is used for ICP packets sent out to other
- caches.
-
- The default behavior is to not bind to any specific address.
-
- A udp_incoming_address value of 0.0.0.0 indicates Squid
- should listen for UDP messages on all available interfaces.
-
- If udp_outgoing_address is set to 255.255.255.255 (the default)
- it will use the same socket as udp_incoming_address. Only
- change this if you want to have ICP queries sent using another
- address than where this Squid listens for ICP queries from other
- caches.
+ Defining an Access List
- NOTE, udp_incoming_address and udp_outgoing_address can not
- have the same value since they both use port 3130.
-DOC_END
+ acl aclname acltype string1 ...
+ acl aclname acltype "file" ...
-COMMENT_START
- OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
- -----------------------------------------------------------------------------
-COMMENT_END
+ when using "file", the file should contain one item per line
-NAME: cache_peer
-TYPE: peer
-DEFAULT: none
-LOC: Config.peers
-DOC_START
- To specify other caches in a hierarchy, use the format:
+ acltype is one of the types described below
- cache_peer hostname type http_port icp_port [options]
+ By default, regular expressions are CASE-SENSITIVE. To make
+ them case-insensitive, use the -i option.
- For example,
+ acl aclname src ip-address/netmask ... (clients IP address)
+ acl aclname src addr1-addr2/netmask ... (range of addresses)
+ acl aclname dst ip-address/netmask ... (URL host's IP address)
+ acl aclname myip ip-address/netmask ... (local socket IP address)
- # proxy icp
- # hostname type port port options
- # -------------------- -------- ----- ----- -----------
- cache_peer parent.foo.net parent 3128 3130 [proxy-only]
- cache_peer sib1.foo.net sibling 3128 3130 [proxy-only]
- cache_peer sib2.foo.net sibling 3128 3130 [proxy-only]
+ acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
+ # The arp ACL requires the special configure option --enable-arp-acl.
+ # Furthermore, the ARP ACL code is not portable to all operating systems.
+ # It works on Linux, Solaris, Windows, FreeBSD, and some other *BSD variants.
+ #
+ # NOTE: Squid can only determine the MAC address for clients that are on
+ # the same subnet. If the client is on a different subnet, then Squid cannot
+ # find out its MAC address.
+
+ acl aclname srcdomain .foo.com ... # reverse lookup, client IP
+ acl aclname dstdomain .foo.com ... # Destination server from URL
+ acl aclname srcdom_regex [-i] xxx ... # regex matching client name
+ acl aclname dstdom_regex [-i] xxx ... # regex matching server
+ # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
+ # based URL is used and no match is found. The name "none" is used
+ # if the reverse lookup fails.
+
+ acl aclname http_status 200 301 500- 400-403 ... # status code in reply
+
+ acl aclname time [day-abbrevs] [h1:m1-h2:m2]
+ day-abbrevs:
+ S - Sunday
+ M - Monday
+ T - Tuesday
+ W - Wednesday
+ H - Thursday
+ F - Friday
+ A - Saturday
+ h1:m1 must be less than h2:m2
+ acl aclname url_regex [-i] ^http:// ... # regex matching on whole URL
+ acl aclname urlpath_regex [-i] \.gif$ ... # regex matching on URL path
+ acl aclname port 80 70 21 ...
+ acl aclname port 0-1024 ... # ranges allowed
+ acl aclname myport 3128 ... # (local socket TCP port)
+ acl aclname proto HTTP FTP ...
+ acl aclname method GET POST ...
+ acl aclname browser [-i] regexp ...
+ # pattern match on User-Agent header (see also req_header below)
+ acl aclname referer_regex [-i] regexp ...
+ # pattern match on Referer header
+ # Referer is highly unreliable, so use with care
+ acl aclname ident username ...
+ acl aclname ident_regex [-i] pattern ...
+ # string match on ident output.
+ # use REQUIRED to accept any non-null ident.
+ acl aclname src_as number ...
+ acl aclname dst_as number ...
+ # Except for access control, AS numbers can be used for
+ # routing of requests to specific caches. Here's an
+ # example for routing all requests for AS#1241 and only
+ # those to mycache.mydomain.net:
+ # acl asexample dst_as 1241
+ # cache_peer_access mycache.mydomain.net allow asexample
+ # cache_peer_access mycache_mydomain.net deny all
+
+ acl aclname proxy_auth [-i] username ...
+ acl aclname proxy_auth_regex [-i] pattern ...
+ # list of valid usernames
+ # use REQUIRED to accept any valid username.
+ #
+ # NOTE: when a Proxy-Authentication header is sent but it is not
+ # needed during ACL checking the username is NOT logged
+ # in access.log.
+ #
+ # NOTE: proxy_auth requires a EXTERNAL authentication program
+ # to check username/password combinations (see
+ # auth_param directive).
+ #
+ # NOTE: proxy_auth can't be used in a transparent proxy as
+ # the browser needs to be configured for using a proxy in order
+ # to respond to proxy authentication.
+
+ acl aclname snmp_community string ...
+ # A community string to limit access to your SNMP Agent
+ # Example:
+ #
+ # acl snmppublic snmp_community public
+
+ acl aclname maxconn number
+ # This will be matched when the client's IP address has
+ # more than <number> HTTP connections established.
+
+ acl aclname max_user_ip [-s] number
+ # This will be matched when the user attempts to log in from more
+ # than <number> different ip addresses. The authenticate_ip_ttl
+ # parameter controls the timeout on the ip entries.
+ # If -s is specified the limit is strict, denying browsing
+ # from any further IP addresses until the ttl has expired. Without
+ # -s Squid will just annoy the user by "randomly" denying requests.
+ # (the counter is reset each time the limit is reached and a
+ # request is denied)
+ # NOTE: in acceleration mode or where there is mesh of child proxies,
+ # clients may appear to come from multiple addresses if they are
+ # going through proxy farms, so a limit of 1 may cause user problems.
+
+ acl aclname req_mime_type mime-type1 ...
+ # regex match against the mime type of the request generated
+ # by the client. Can be used to detect file upload or some
+ # types HTTP tunneling requests.
+ # NOTE: This does NOT match the reply. You cannot use this
+ # to match the returned file type.
+
+ acl aclname req_header header-name [-i] any\.regex\.here
+ # regex match against any of the known request headers. May be
+ # thought of as a superset of "browser", "referer" and "mime-type"
+ # ACLs.
+
+ acl aclname rep_mime_type mime-type1 ...
+ # regex match against the mime type of the reply received by
+ # squid. Can be used to detect file download or some
+ # types HTTP tunneling requests.
+ # NOTE: This has no effect in http_access rules. It only has
+ # effect in rules that affect the reply data stream such as
+ # http_reply_access.
+
+ acl aclname rep_header header-name [-i] any\.regex\.here
+ # regex match against any of the known reply headers. May be
+ # thought of as a superset of "browser", "referer" and "mime-type"
+ # ACLs.
+
+ acl acl_name external class_name [arguments...]
+ # external ACL lookup via a helper class defined by the
+ # external_acl_type directive.
+
+ acl aclname user_cert attribute values...
+ # match against attributes in a user SSL certificate
+ # attribute is one of DN/C/O/CN/L/ST
+
+ acl aclname ca_cert attribute values...
+ # match against attributes a users issuing CA SSL certificate
+ # attribute is one of DN/C/O/CN/L/ST
+
+ acl aclname ext_user username ...
+ acl aclname ext_user_regex [-i] pattern ...
+ # string match on username returned by external acl helper
+ # use REQUIRED to accept any non-null user name.
+
+Examples:
+acl macaddress arp 09:00:2b:23:45:67
+acl myexample dst_as 1241
+acl password proxy_auth REQUIRED
+acl fileupload req_mime_type -i ^multipart/form-data$
+acl javascript rep_mime_type -i ^application/x-javascript$
+
+NOCOMMENT_START
+#Recommended minimum configuration:
+acl manager proto cache_object
+acl localhost src 127.0.0.1/32
+acl to_localhost dst 127.0.0.0/8
+#
+# Example rule allowing access from your local networks.
+# Adapt to list your (internal) IP networks from where browsing
+# should be allowed
+acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
+acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
+acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
+#
+acl SSL_ports port 443
+acl Safe_ports port 80 # http
+acl Safe_ports port 21 # ftp
+acl Safe_ports port 443 # https
+acl Safe_ports port 70 # gopher
+acl Safe_ports port 210 # wais
+acl Safe_ports port 1025-65535 # unregistered ports
+acl Safe_ports port 280 # http-mgmt
+acl Safe_ports port 488 # gss-http
+acl Safe_ports port 591 # filemaker
+acl Safe_ports port 777 # multiling http
+acl CONNECT method CONNECT
+NOCOMMENT_END
+DOC_END
+
+NAME: http_access
+TYPE: acl_access
+LOC: Config.accessList.http
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access based on defined access lists
+
+ Access to the HTTP port:
+ http_access allow|deny [!]aclname ...
+
+ NOTE on default values:
+
+ If there are no "access" lines present, the default is to deny
+ the request.
+
+ If none of the "access" lines cause a match, the default is the
+ opposite of the last line in the list. If the last line was
+ deny, the default is allow. Conversely, if the last line
+ is allow, the default will be deny. For these reasons, it is a
+ good idea to have an "deny all" or "allow all" entry at the end
+ of your access lists to avoid potential confusion.
+
+NOCOMMENT_START
+#Recommended minimum configuration:
+#
+# Only allow cachemgr access from localhost
+http_access allow manager localhost
+http_access deny manager
+# Deny requests to unknown ports
+http_access deny !Safe_ports
+# Deny CONNECT to other than SSL ports
+http_access deny CONNECT !SSL_ports
+#
+# We strongly recommend the following be uncommented to protect innocent
+# web applications running on the proxy server who think the only
+# one who can access services on "localhost" is a local user
+#http_access deny to_localhost
+#
+# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
+
+# Example rule allowing access from your local networks.
+# Adapt localnet in the ACL section to list your (internal) IP networks
+# from where browsing should be allowed
+http_access allow localnet
+
+# And finally deny all other access to this proxy
+http_access deny all
+NOCOMMENT_END
+DOC_END
+
+NAME: http_reply_access
+TYPE: acl_access
+LOC: Config.accessList.reply
+DEFAULT: none
+DOC_START
+ Allow replies to client requests. This is complementary to http_access.
+
+ http_reply_access allow|deny [!] aclname ...
+
+ NOTE: if there are no access lines present, the default is to allow
+ 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
+ with an "allow all" or "deny all" entry.
+DOC_END
+
+NAME: icp_access
+TYPE: acl_access
+LOC: Config.accessList.icp
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access to the ICP port based on defined
+ access lists
+
+ icp_access allow|deny [!]aclname ...
+
+ See http_access for details
+
+NOCOMMENT_START
+#Allow ICP queries from local networks only
+icp_access allow localnet
+icp_access deny all
+NOCOMMENT_END
+DOC_END
+
+NAME: htcp_access
+IFDEF: USE_HTCP
+TYPE: acl_access
+LOC: Config.accessList.htcp
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access to the HTCP port based on defined
+ access lists
+
+ htcp_access allow|deny [!]aclname ...
+
+ See http_access for details
+
+ NOTE: The default if no htcp_access lines are present is to
+ deny all traffic. This default may cause problems with peers
+ using the htcp or htcp-oldsquid options.
+
+NOCOMMENT_START
+#Allow HTCP queries from local networks only
+htcp_access allow localnet
+htcp_access deny all
+NOCOMMENT_END
+DOC_END
+
+NAME: htcp_clr_access
+IFDEF: USE_HTCP
+TYPE: acl_access
+LOC: Config.accessList.htcp_clr
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+DOC_START
+ Allowing or Denying access to purge content using HTCP based
+ on defined access lists
+
+ htcp_clr_access allow|deny [!]aclname ...
+
+ See http_access for details
+
+#Allow HTCP CLR requests from trusted peers
+acl htcp_clr_peer src 172.16.1.2
+htcp_clr_access allow htcp_clr_peer
+DOC_END
+
+NAME: miss_access
+TYPE: acl_access
+LOC: Config.accessList.miss
+DEFAULT: none
+DOC_START
+ Use to force your neighbors to use you as a sibling instead of
+ a parent. For example:
+
+ acl localclients src 172.16.0.0/16
+ miss_access allow localclients
+ miss_access deny !localclients
+
+ This means only your local clients are allowed to fetch
+ MISSES and all other clients can only fetch HITS.
+
+ By default, allow all clients who passed the http_access rules
+ to fetch MISSES from us.
+
+NOCOMMENT_START
+#Default setting:
+# miss_access allow all
+NOCOMMENT_END
+DOC_END
+
+NAME: ident_lookup_access
+TYPE: acl_access
+IFDEF: USE_IDENT
+DEFAULT: none
+DEFAULT_IF_NONE: deny all
+LOC: Config.accessList.identLookup
+DOC_START
+ A list of ACL elements which, if matched, cause an ident
+ (RFC 931) lookup to be performed for this request. For
+ example, you might choose to always perform ident lookups
+ for your main multi-user Unix boxes, but not for your Macs
+ and PCs. By default, ident lookups are not performed for
+ any requests.
+
+ To enable ident lookups for specific client addresses, you
+ can follow this example:
- type: either 'parent', 'sibling', or 'multicast'.
+ acl ident_aware_hosts src 198.168.1.0/255.255.255.0
+ ident_lookup_access allow ident_aware_hosts
+ ident_lookup_access deny all
- proxy_port: The port number where the cache listens for proxy
- requests.
+ Only src type ACL checks are fully supported. A src_domain
+ ACL might work at times, but it will not always provide
+ the correct result.
+DOC_END
- icp_port: Used for querying neighbor caches about
- objects. To have a non-ICP neighbor
- specify '7' for the ICP port and make sure the
- neighbor machine has the UDP echo port
- enabled in its /etc/inetd.conf file.
+NAME: reply_body_max_size
+COMMENT: size [acl acl...]
+TYPE: acl_b_size_t
+DEFAULT: none
+LOC: Config.ReplyBodySize
+DOC_START
+ This option specifies the maximum size of a reply body. It can be
+ used to prevent users from downloading very large files, such as
+ MP3's and movies. When the reply headers are received, the
+ reply_body_max_size lines are processed, and the first line where
+ all (if any) listed ACLs are true is used as the maximum body size
+ for this reply.
- options: proxy-only
- weight=n
- basetime=n
- ttl=n
- no-query
- background-ping
- default
- round-robin
- weighted-round-robin
- carp
- multicast-responder
- closest-only
- no-digest
- no-netdb-exchange
- no-delay
- login=user:password | PASS | *:password
- connect-timeout=nn
- digest-url=url
- allow-miss
- max-conn
- htcp
- htcp-oldsquid
- originserver
- name=xxx
- forceddomain=name
- ssl
- sslcert=/path/to/ssl/certificate
- sslkey=/path/to/ssl/key
- sslversion=1|2|3|4
- sslcipher=...
- ssloptions=...
- front-end-https[=on|auto]
+ This size is checked twice. First when we get the reply headers,
+ we check the content-length value. If the content length value exists
+ and is larger than the allowed size, the request is denied and the
+ user receives an error message that says "the request or reply
+ is too large." If there is no content-length, and the reply
+ size exceeds this limit, the client's connection is just closed
+ and they will receive a partial reply.
- use 'proxy-only' to specify objects fetched
- from this cache should not be saved locally.
+ WARNING: downstream caches probably can not detect a partial reply
+ if there is no content-length header, so they will cache
+ partial responses and give them out as hits. You should NOT
+ use this option if you have downstream caches.
- use 'weight=n' to specify a weighted parent.
- The weight must be an integer. The default weight
- is 1, larger weights are favored more.
+ WARNING: A maximum size smaller than the size of squid's error messages
+ will cause an infinite loop and crash squid. Ensure that the smallest
+ non-zero value you use is greater that the maximum header size plus
+ the size of your largest error page.
- use 'basetime=n' to specify a base amount to
- be subtracted from round trip times of parents.
- It is subtracted before division by weight in calculating
- which parent to fectch from. If the rtt is less than the
- base time the rtt is set to a minimal value.
+ If you set this parameter none (the default), there will be
+ no limit imposed.
+DOC_END
- use 'ttl=n' to specify a IP multicast TTL to use
- when sending an ICP queries to this address.
- Only useful when sending to a multicast group.
- Because we don't accept ICP replies from random
- hosts, you must configure other group members as
- peers with the 'multicast-responder' option below.
+COMMENT_START
+ NETWORK OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
- use 'no-query' to NOT send ICP queries to this
- neighbor.
+NAME: http_port ascii_port
+TYPE: http_port_list
+DEFAULT: none
+LOC: Config.Sockaddr.http
+DOC_START
+ Usage: port [options]
+ hostname:port [options]
+ 1.2.3.4:port [options]
- use 'background-ping' to only send ICP queries to this
- neighbor infrequently. This is used to keep the neighbor
- round trip time updated and is usually used in
- conjunction with weighted-round-robin.
+ The socket addresses where Squid will listen for HTTP client
+ requests. You may specify multiple socket addresses.
+ There are three forms: port alone, hostname with port, and
+ IP address with port. If you specify a hostname or IP
+ address, Squid binds the socket to that specific
+ address. This replaces the old 'tcp_incoming_address'
+ option. Most likely, you do not need to bind to a specific
+ address, so you can use the port number alone.
- use 'default' if this is a parent cache which can
- be used as a "last-resort." You should probably
- only use 'default' in situations where you cannot
- use ICP with your parent cache(s).
+ If you are running Squid in accelerator mode, you
+ probably want to listen on port 80 also, or instead.
- use 'round-robin' to define a set of parents which
- should be used in a round-robin fashion in the
- absence of any ICP queries.
+ The -a command line option may be used to specify additional
+ port(s) where Squid listens for proxy request. Such ports will
+ be plain proxy ports with no options.
- use 'weighted-round-robin' to define a set of parents
- which should be used in a round-robin fashion with the
- frequency of each parent being based on the round trip
- time. Closer parents are used more often.
- Usually used for background-ping parents.
+ You may specify multiple socket addresses on multiple lines.
- use 'carp' to define a set of parents which should
- be used as a CARP array. The requests will be
- distributed among the parents based on the CARP load
- balancing hash function based on their weigth.
+ Options:
- 'multicast-responder' indicates the named peer
- is a member of a multicast group. ICP queries will
- not be sent directly to the peer, but ICP replies
- will be accepted from it.
+ transparent Support for transparent interception of
+ outgoing requests without browser settings.
- 'closest-only' indicates that, for ICP_OP_MISS
- replies, we'll only forward CLOSEST_PARENT_MISSes
- and never FIRST_PARENT_MISSes.
+ tproxy Support Linux TPROXY for spoofing outgoing
+ connections using the client IP address.
- use 'no-digest' to NOT request cache digests from
- this neighbor.
+ accel Accelerator mode. Also needs at least one of
+ vhost / vport / defaultsite.
- 'no-netdb-exchange' disables requesting ICMP
- RTT database (NetDB) from the neighbor.
+ defaultsite=domainname
+ What to use for the Host: header if it is not present
+ in a request. Determines what site (not origin server)
+ accelerators should consider the default.
+ Implies accel.
- use 'no-delay' to prevent access to this neighbor
- from influencing the delay pools.
+ vhost Accelerator mode using Host header for virtual
+ domain support. Implies accel.
- use 'login=user:password' if this is a personal/workgroup
- proxy and your parent requires proxy authentication.
- Note: The string can include URL escapes (i.e. %20 for
- spaces). This also means % must be written as %%.
+ vport Accelerator with IP based virtual host support.
+ Implies accel.
- use 'login=PASS' if users must authenticate against
- the upstream proxy or in the case of a reverse proxy
- configuration, the origin web server. This will pass
- the users credentials as they are to the peer.
- This only works for the Basic HTTP authentication scheme.
- Note: To combine this with proxy_auth both proxies must
- share the same user database as HTTP only allows for
- one proxy login.
- Also be warned this will expose your users proxy
- password to the peer. USE WITH CAUTION
+ vport=NN As above, but uses specified port number rather
+ than the http_port number. Implies accel.
- use 'login=*:password' to pass the username to the
- upstream cache, but with a fixed password. This is meant
- to be used when the peer is in another administrative
- domain, but it is still needed to identify each user.
- The star can optionally be followed by some extra
- information which is added to the username. This can
- be used to identify this proxy to the peer, similar to
- the login=username:password option above.
+ protocol= Protocol to reconstruct accelerated requests with.
+ Defaults to http.
- use 'connect-timeout=nn' to specify a peer
- specific connect timeout (also see the
- peer_connect_timeout directive)
+ disable-pmtu-discovery=
+ Control Path-MTU discovery usage:
+ off lets OS decide on what to do (default).
+ transparent disable PMTU discovery when transparent
+ support is enabled.
+ always disable always PMTU discovery.
- use 'digest-url=url' to tell Squid to fetch the cache
- digest (if digests are enabled) for this host from
- the specified URL rather than the Squid default
- location.
+ 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'.
- use 'allow-miss' to disable Squid's use of only-if-cached
- when forwarding requests to siblings. This is primarily
- useful when icp_hit_stale is used by the sibling. To
- extensive use of this option may result in forwarding
- loops, and you should avoid having two-way peerings
- with this option. (for example to deny peer usage on
- requests from peer by denying cache_peer_access if the
- source is a peer)
+ If you run Squid on a dual-homed machine with an internal
+ and an external interface we recommend you to specify the
+ internal address:port in http_port. This way Squid will only be
+ visible on the internal address.
- use 'max-conn' to limit the amount of connections Squid
- may open to this peer.
+NOCOMMENT_START
+# Squid normally listens to port 3128
+http_port @DEFAULT_HTTP_PORT@
+NOCOMMENT_END
+DOC_END
- use 'htcp' to send HTCP, instead of ICP, queries
- to the neighbor. You probably also want to
- set the "icp port" to 4827 instead of 3130.
+NAME: https_port
+IFDEF: USE_SSL
+TYPE: https_port_list
+DEFAULT: none
+LOC: Config.Sockaddr.https
+DOC_START
+ Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...]
- use 'htcp-oldsquid' to send HTCP to old Squid versions
+ The socket address where Squid will listen for HTTPS client
+ requests.
- 'originserver' causes this parent peer to be contacted as
- a origin server. Meant to be used in accelerator setups.
+ This is really only useful for situations where you are running
+ squid in accelerator mode and you want to do the SSL work at the
+ accelerator level.
- use 'name=xxx' if you have multiple peers on the same
- host but different ports. This name can be used to
- differentiate the peers in cache_peer_access and similar
- directives.
+ You may specify multiple socket addresses on multiple lines,
+ each with their own SSL certificate and/or options.
- use 'forceddomain=name' to forcibly set the Host header
- of requests forwarded to this peer. Useful in accelerator
- setups where the server (peer) expects a certain domain
- name and using redirectors to feed this domainname
- is not feasible.
+ Options:
- use 'ssl' to indicate connections to this peer should
- bs SSL/TLS encrypted.
+ accel Accelerator mode. Also needs at least one of
+ defaultsite or vhost.
- use 'sslcert=/path/to/ssl/certificate' to specify a client
- SSL certificate to use when connecting to this peer.
+ defaultsite= The name of the https site presented on
+ this port. Implies accel.
- use 'sslkey=/path/to/ssl/key' to specify the private SSL
- key corresponding to sslcert above. If 'sslkey' is not
- specified 'sslcert' is assumed to reference a
- combined file containing both the certificate and the key.
+ vhost Accelerator mode using Host header for virtual
+ domain support. Requires a wildcard certificate
+ or other certificate valid for more than one domain.
+ Implies accel.
- use sslversion=1|2|3|4 to specify the SSL version to use
- when connecting to this peer
- 1 = automatic (default)
- 2 = SSL v2 only
- 3 = SSL v3 only
- 4 = TLS v1 only
+ protocol= Protocol to reconstruct accelerated requests with.
+ Defaults to https.
- use sslcipher=... to specify the list of valid SSL chipers
- to use when connecting to this peer
+ cert= Path to SSL certificate (PEM format).
- use ssloptions=... to specify various SSL engine options:
- NO_SSLv2 Disallow the use of SSLv2
- NO_SSLv3 Disallow the use of SSLv3
- NO_TLSv1 Disallow the use of TLSv1
- See src/ssl_support.c or the OpenSSL documentation for
- a more complete list.
+ 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.
+
+ version= The version of SSL/TLS supported
+ 1 automatic (default)
+ 2 SSLv2 only
+ 3 SSLv3 only
+ 4 TLSv1 only
- use cafile=... to specify a file containing additional
- CA certificates to use when verifying the peer certificate
+ cipher= Colon separated list of supported ciphers.
- use capath=... to specify a directory containing additional
- CA certificates to use when verifying the peer certificate
+ options= Various SSL engine options. The most important
+ being:
+ NO_SSLv2 Disallow the use of SSLv2
+ NO_SSLv3 Disallow the use of SSLv3
+ NO_TLSv1 Disallow the use of TLSv1
+ 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.
- use sslflags=... to specify various flags modifying the
- SSL implementation:
- DONT_VERIFY_PEER
- Accept certificates even if they fail to
- verify.
- NO_DEFAULT_CA
- Don't use the default CA list built in
- to OpenSSL.
- DONT_VERIFY_DOMAIN
- Don't verify the peer certificate
- matches the server name
+ clientca= File containing the list of CAs to use when
+ requesting a client certificate.
- use sslname= 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.
+ cafile= File containing additional CA certificates to
+ use when verifying client certificates. If unset
+ clientca will be used.
- use front-end-https to enable the "Front-End-Https: On"
- header needed when using Squid as a SSL frontend infront
- of Microsoft OWA. See MS KB document Q307347 for details
- on this header. If set to auto the header will
- only be added if the request is forwarded as a https://
- URL.
+ capath= Directory containing additional CA certificates
+ and CRL lists to use when verifying client certificates.
- NOTE: non-ICP neighbors must be specified as 'parent'.
-DOC_END
+ 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.
-NAME: cache_peer_domain cache_host_domain
-TYPE: hostdomain
-DEFAULT: none
-LOC: none
-DOC_START
- Use to limit the domains for which a neighbor cache will be
- queried. Usage:
+ dhparams= File containing DH parameters for temporary/ephemeral
+ DH key exchanges.
- cache_peer_domain cache-host domain [domain ...]
- cache_peer_domain cache-host !domain
+ 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).
+ NO_DEFAULT_CA
+ Don't use the default CA lists built in
+ 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.
+ VERIFY_CRL_ALL
+ Verify CRL lists for all certificates in the
+ client certificate chain.
- For example, specifying
+ sslcontext= SSL session ID context identifier.
- cache_peer_domain parent.foo.net .edu
+ vport Accelerator with IP based virtual host support.
- has the effect such that UDP query packets are sent to
- 'bigserver' only when the requested object exists on a
- server in the .edu domain. Prefixing the domainname
- with '!' means the cache will be queried for objects
- NOT in that domain.
+ vport=NN As above, but uses specified port number rather
+ than the https_port number. Implies accel.
- NOTE: * Any number of domains may be given for a cache-host,
- either on the same or separate lines.
- * When multiple domains are given for a particular
- cache-host, the first matched domain is applied.
- * Cache hosts with no domain restrictions are queried
- for all requests.
- * There are no defaults.
- * There is also a 'cache_peer_access' tag in the ACL
- section.
DOC_END
-
-NAME: neighbor_type_domain
-TYPE: hostdomaintype
+NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
+TYPE: acl_tos
DEFAULT: none
-LOC: none
+LOC: Config.accessList.outgoing_tos
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 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 parent cache.foo.org 3128 3130
- neighbor_type_domain cache.foo.org sibling .com .net
- neighbor_type_domain cache.foo.org sibling .au .de
-DOC_END
+ Allows you to select a TOS/Diffserv value to mark outgoing
+ connections with, based on the username or source address
+ making the request.
-NAME: icp_query_timeout
-COMMENT: (msec)
-DEFAULT: 0
-TYPE: int
-LOC: Config.Timeout.icp_query
-DOC_START
- Normally Squid will automatically determine an optimal ICP
- query timeout value based on the round-trip-time of recent ICP
- queries. If you want to override the value determined by
- Squid, set this 'icp_query_timeout' to a non-zero value. This
- value is specified in MILLISECONDS, so, to use a 2-second
- timeout (the old default), you would write:
+ tcp_outgoing_tos ds-field [!]aclname ...
- icp_query_timeout 2000
-DOC_END
+ Example where normal_service_net uses the TOS value 0x00
+ and normal_service_net uses 0x20
-NAME: maximum_icp_query_timeout
-COMMENT: (msec)
-DEFAULT: 2000
-TYPE: int
-LOC: Config.Timeout.icp_query_max
-DOC_START
- Normally the ICP query timeout is determined dynamically. But
- sometimes it can lead to very large values (say 5 seconds).
- Use this option to put an upper limit on the dynamic timeout
- value. Do NOT use this option to always use a fixed (instead
- of a dynamic) timeout value. To set a fixed timeout see the
- 'icp_query_timeout' directive.
-DOC_END
+ acl normal_service_net src 10.0.0.0/255.255.255.0
+ acl good_service_net src 10.0.1.0/255.255.255.0
+ tcp_outgoing_tos 0x00 normal_service_net
+ tcp_outgoing_tos 0x20 good_service_net
-NAME: minimum_icp_query_timeout
-COMMENT: (msec)
-DEFAULT: 5
-TYPE: int
-LOC: Config.Timeout.icp_query_min
-DOC_START
- Normally the ICP query timeout is determined dynamically. But
- sometimes it can lead to very small timeouts, even lower than
- the normal latency variance on your link due to traffic.
- Use this option to put an lower limit on the dynamic timeout
- value. Do NOT use this option to always use a fixed (instead
- of a dynamic) timeout value. To set a fixed timeout see the
- 'icp_query_timeout' directive.
-DOC_END
+ TOS/DSCP values really only have local significance - so you should
+ know what you're specifying. For more information, see RFC2474 and
+ RFC3260.
-NAME: mcast_icp_query_timeout
-COMMENT: (msec)
-DEFAULT: 2000
-TYPE: int
-LOC: Config.Timeout.mcast_icp_query
-DOC_START
- 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
- seconds.
-DOC_END
+ 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).
-NAME: dead_peer_timeout
-COMMENT: (seconds)
-DEFAULT: 10 seconds
-TYPE: time_t
-LOC: Config.Timeout.deadPeer
-DOC_START
- This controls how long Squid waits to declare a peer cache
- as "dead." If there are no ICP replies received in this
- amount of time, Squid will declare the peer dead and not
- expect to receive any further ICP replies. However, it
- continues to send ICP queries, and will mark the peer as
- alive upon receipt of the first subsequent ICP reply.
+ Processing proceeds in the order specified, and stops at first fully
+ matching line.
- This timeout also affects when Squid expects to receive ICP
- replies from peers. If more than 'dead_peer' seconds have
- passed since the last ICP reply was received, Squid will not
- expect to receive an ICP reply on the next query. Thus, if
- your time between requests is greater than this timeout, you
- will see a lot of requests sent DIRECT to origin servers
- instead of to your parents.
+ 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: hierarchy_stoplist
-TYPE: wordlist
+NAME: clientside_tos
+TYPE: acl_tos
DEFAULT: none
-LOC: Config.hierarchy_stoplist
+LOC: Config.accessList.clientside_tos
DOC_START
- A list of words which, if found in a URL, cause the object to
- be handled directly by this cache. In other words, use this
- to not query neighbor caches for certain objects. You may
- list this option multiple times.
-NOCOMMENT_START
-#We recommend you to use at least the following line.
-hierarchy_stoplist cgi-bin ?
-NOCOMMENT_END
+ Allows you to select a TOS/Diffserv value to mark client-side
+ connections with, based on the username or source address
+ making the request.
DOC_END
-
-NAME: cache no_cache
-TYPE: acl_access
+NAME: tcp_outgoing_address
+TYPE: acl_address
DEFAULT: none
-LOC: Config.accessList.noCache
+LOC: Config.accessList.outgoing_address
DOC_START
- A list of ACL elements which, if matched, cause the request to
- not be satisfied from the cache and the reply to not be cached.
- In other words, use this to force certain objects to never be cached.
+ Allows you to map requests to different outgoing IP addresses
+ based on the username or source address of the user making
+ the request.
- You must use the word 'DENY' to indicate the ACL names which should
- NOT be cached.
+ tcp_outgoing_address ipaddr [[!]aclname] ...
- Default is to allow all to be cached
-NOCOMMENT_START
-#We recommend you to use the following two lines.
-acl QUERY urlpath_regex cgi-bin \?
-cache deny QUERY
-NOCOMMENT_END
-DOC_END
+ Example where requests from 10.0.0.0/24 will be forwarded
+ with source address 10.1.0.1, 10.0.2.0/24 forwarded with
+ source address 10.1.0.2 and the rest will be forwarded with
+ source address 10.1.0.3.
-NAME: background_ping_rate
-COMMENT: time-units
-TYPE: time_t
-DEFAULT: 10 seconds
-LOC: Config.backgroundPingRate
-DOC_START
- Controls how often the ICP pings are sent to siblings that
- have background-ping set.
-DOC_END
+ acl normal_service_net src 10.0.0.0/255.255.255.0
+ acl good_service_net src 10.0.1.0/255.255.255.0
+ tcp_outgoing_address 10.0.0.1 normal_service_net
+ tcp_outgoing_address 10.0.0.2 good_service_net
+ tcp_outgoing_address 10.0.0.3
+ Processing proceeds in the order specified, and stops at first fully
+ matching line.
-COMMENT_START
- OPTIONS WHICH AFFECT THE CACHE SIZE
- -----------------------------------------------------------------------------
-COMMENT_END
+ Note: The use of this directive using client dependent ACLs is
+ incompatible with the use of server side persistent connections. To
+ ensure correct results it is best to set server_persistent_connections
+ to off when using this directive in such configurations.
-NAME: cache_mem
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 8 MB
-LOC: Config.memMaxSize
-DOC_START
- NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
- IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
- USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
- THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
- 'cache_mem' specifies the ideal amount of memory to be used
- for:
- * In-Transit objects
- * Hot Objects
- * Negative-Cached objects
+ IPv6 Magic:
+
+ Squid is built with a capability of bridging the IPv4 and IPv6 internets.
+ tcp_outgoing_address as exampled above breaks this bridging by forcing
+ all outbound traffic through a certain IPv4 which may be on the wrong
+ side of the IPv4/IPv6 boundary.
- Data for these objects are stored in 4 KB blocks. This
- parameter specifies the ideal upper limit on the total size of
- 4 KB blocks allocated. In-Transit objects take the highest
- priority.
+ To operate with tcp_outgoing_address and keep the bridging benefits
+ an additional ACL needs to be used which ensures the IPv6-bound traffic
+ is never forced or permitted out the IPv4 interface.
- In-transit objects have priority over the others. When
- additional space is needed for incoming data, negative-cached
- and hot objects will be released. In other words, the
- negative-cached and hot objects will fill up any unused space
- not needed for in-transit objects.
+ acl to_ipv6 dst ipv6
+ tcp_outgoing_address 2002::c001 good_service_net to_ipv6
+ tcp_outgoing_address 10.0.0.2 good_service_net !to_ipv6
- If circumstances require, this limit will be exceeded.
- Specifically, if your incoming request rate requires more than
- 'cache_mem' of memory to hold in-transit objects, Squid will
- exceed this limit to satisfy the new requests. When the load
- decreases, blocks will be freed until the high-water mark is
- reached. Thereafter, blocks will be used to store hot
- objects.
-DOC_END
+ tcp_outgoing_address 2002::beef normal_service_net to_ipv6
+ tcp_outgoing_address 10.0.0.1 normal_service_net !to_ipv6
+ tcp_outgoing_address 2002::1 to_ipv6
+ tcp_outgoing_address 10.0.0.3 !to_ipv6
+DOC_END
-NAME: cache_swap_low
-COMMENT: (percent, 0-100)
-TYPE: int
-DEFAULT: 90
-LOC: Config.Swap.lowWaterMark
-DOC_NONE
+COMMENT_START
+ SSL OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
-NAME: cache_swap_high
-COMMENT: (percent, 0-100)
-TYPE: int
-DEFAULT: 95
-LOC: Config.Swap.highWaterMark
+NAME: ssl_unclean_shutdown
+IFDEF: USE_SSL
+TYPE: onoff
+DEFAULT: off
+LOC: Config.SSL.unclean_shutdown
DOC_START
+ Some browsers (especially MSIE) bugs out on SSL shutdown
+ messages.
+DOC_END
- The low- and high-water marks for cache object replacement.
- Replacement begins when the swap (disk) usage is above the
- low-water mark and attempts to maintain utilization near the
- low-water mark. As swap utilization gets close to high-water
- mark object eviction becomes more aggressive. If utilization is
- close to the low-water mark less replacement is done each time.
+NAME: ssl_engine
+IFDEF: USE_SSL
+TYPE: string
+LOC: Config.SSL.ssl_engine
+DEFAULT: none
+DOC_START
+ The OpenSSL engine to use. You will need to set this if you
+ would like to use hardware SSL acceleration for example.
+DOC_END
- 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.
+NAME: sslproxy_client_certificate
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.cert
+TYPE: string
+DOC_START
+ Client SSL Certificate to use when proxying https:// URLs
DOC_END
-NAME: maximum_object_size
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 4096 KB
-LOC: Config.Store.maxObjectSize
+NAME: sslproxy_client_key
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.key
+TYPE: string
DOC_START
- Objects larger than this size will NOT be saved on disk. The
- value is specified in kilobytes, and the default is 4MB. If
- you wish to get a high BYTES hit ratio, you should probably
- increase this (one 32 MB object hit counts for 3200 10KB
- hits). If you wish to increase speed more than your want to
- save bandwidth you should leave this low.
+ Client SSL Key to use when proxying https:// URLs
+DOC_END
- NOTE: if using the LFUDA replacement policy you should increase
- this value to maximize the byte hit rate improvement of LFUDA!
- See replacement_policy below for a discussion of this policy.
+NAME: sslproxy_version
+IFDEF: USE_SSL
+DEFAULT: 1
+LOC: Config.ssl_client.version
+TYPE: int
+DOC_START
+ SSL version level to use when proxying https:// URLs
DOC_END
-NAME: minimum_object_size
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 0 KB
-LOC: Config.Store.minObjectSize
+NAME: sslproxy_options
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.options
+TYPE: string
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.
+ SSL engine options to use when proxying https:// URLs
DOC_END
-NAME: maximum_object_size_in_memory
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 8 KB
-LOC: Config.Store.maxInMemObjSize
+NAME: sslproxy_cipher
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.cipher
+TYPE: string
DOC_START
- Objects greater than this size will not be attempted to kept in
- the memory cache. This should be set high enough to keep objects
- accessed frequently in memory to improve performance whilst low
- enough to keep larger objects from hoarding cache_mem .
+ SSL cipher list to use when proxying https:// URLs
DOC_END
-NAME: ipcache_size
-COMMENT: (number of entries)
-TYPE: int
-DEFAULT: 1024
-LOC: Config.ipcache.size
-DOC_NONE
+NAME: sslproxy_cafile
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.cafile
+TYPE: string
+DOC_START
+ file containing CA certificates to use when verifying server
+ certificates while proxying https:// URLs
+DOC_END
-NAME: ipcache_low
-COMMENT: (percent)
-TYPE: int
-DEFAULT: 90
-LOC: Config.ipcache.low
-DOC_NONE
+NAME: sslproxy_capath
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.capath
+TYPE: string
+DOC_START
+ directory containing CA certificates to use when verifying
+ server certificates while proxying https:// URLs
+DOC_END
-NAME: ipcache_high
-COMMENT: (percent)
-TYPE: int
-DEFAULT: 95
-LOC: Config.ipcache.high
+NAME: sslproxy_flags
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.ssl_client.flags
+TYPE: string
DOC_START
- The size, low-, and high-water marks for the IP cache.
+ Various flags modifying the use of SSL while proxying https:// URLs:
+ DONT_VERIFY_PEER Accept certificates even if they fail to
+ verify.
+ NO_DEFAULT_CA Don't use the default CA list built in
+ to OpenSSL.
DOC_END
-NAME: fqdncache_size
-COMMENT: (number of entries)
-TYPE: int
-DEFAULT: 1024
-LOC: Config.fqdncache.size
+NAME: sslpassword_program
+IFDEF: USE_SSL
+DEFAULT: none
+LOC: Config.Program.ssl_password
+TYPE: string
DOC_START
- Maximum number of FQDN cache entries.
+ Specify a program used for entering SSL key passphrases
+ when using encrypted SSL certificate keys. If not specified
+ keys must either be unencrypted, or Squid started with the -N
+ option to allow it to query interactively for the passphrase.
DOC_END
-NAME: cache_replacement_policy
-TYPE: removalpolicy
-LOC: Config.replPolicy
-DEFAULT: lru
+COMMENT_START
+ OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: cache_peer
+TYPE: peer
+DEFAULT: none
+LOC: Config.peers
DOC_START
- The cache replacement policy parameter determines which
- objects are evicted (replaced) when disk space is needed.
+ To specify other caches in a hierarchy, use the format:
- lru : Squid's original list based LRU policy
- heap GDSF : Greedy-Dual Size Frequency
- heap LFUDA: Least Frequently Used with Dynamic Aging
- heap LRU : LRU policy implemented using a heap
+ cache_peer hostname type http-port icp-port [options]
- Applies to any cache_dir lines listed below this.
+ For example,
+
+ # proxy icp
+ # hostname type port port options
+ # -------------------- -------- ----- ----- -----------
+ cache_peer parent.foo.net parent 3128 3130 proxy-only default
+ cache_peer sib1.foo.net sibling 3128 3130 proxy-only
+ cache_peer sib2.foo.net sibling 3128 3130 proxy-only
+
+ type: either 'parent', 'sibling', or 'multicast'.
+
+ proxy-port: The port number where the cache listens for proxy
+ requests.
+
+ icp-port: Used for querying neighbor caches about
+ objects. To have a non-ICP neighbor
+ specify '7' for the ICP port and make sure the
+ neighbor machine has the UDP echo port
+ enabled in its /etc/inetd.conf file.
+ NOTE: Also requires icp_port option enabled to send/receive
+ requests via this method.
+
+ options: proxy-only
+ weight=n
+ basetime=n
+ ttl=n
+ no-query
+ background-ping
+ default
+ round-robin
+ weighted-round-robin
+ carp
+ multicast-responder
+ closest-only
+ no-digest
+ no-netdb-exchange
+ no-delay
+ login=user:password | PASS | *:password
+ connect-timeout=nn
+ digest-url=url
+ allow-miss
+ max-conn=n
+ htcp
+ htcp-oldsquid
+ originserver
+ name=xxx
+ forceddomain=name
+ ssl
+ sslcert=/path/to/ssl/certificate
+ sslkey=/path/to/ssl/key
+ sslversion=1|2|3|4
+ sslcipher=...
+ ssloptions=...
+ front-end-https[=on|auto]
+
+ use 'proxy-only' to specify objects fetched
+ from this cache should not be saved locally.
+
+ use 'weight=n' to affect the selection of a peer
+ during any weighted peer-selection mechanisms.
+ The weight must be an integer; default is 1,
+ larger weights are favored more.
+ This option does not affect parent selection if a peering
+ protocol is not in use.
+
+ use 'basetime=n' to specify a base amount to
+ be subtracted from round trip times of parents.
+ It is subtracted before division by weight in calculating
+ which parent to fectch from. If the rtt is less than the
+ base time the rtt is set to a minimal value.
- The LRU policies keeps recently referenced objects.
+ use 'ttl=n' to specify a IP multicast TTL to use
+ when sending an ICP queries to this address.
+ Only useful when sending to a multicast group.
+ Because we don't accept ICP replies from random
+ hosts, you must configure other group members as
+ peers with the 'multicast-responder' option below.
- The heap GDSF policy optimizes object hit rate by keeping smaller
- popular objects in cache so it has a better chance of getting a
- hit. It achieves a lower byte hit rate than LFUDA though since
- it evicts larger (possibly popular) objects.
+ use 'no-query' to NOT send ICP queries to this
+ neighbor.
- The heap LFUDA policy keeps popular objects in cache regardless of
- their size and thus optimizes byte hit rate at the expense of
- hit rate since one large, popular object will prevent many
- smaller, slightly less popular objects from being cached.
+ use 'background-ping' to only send ICP queries to this
+ neighbor infrequently. This is used to keep the neighbor
+ round trip time updated and is usually used in
+ conjunction with weighted-round-robin.
- Both policies utilize a dynamic aging mechanism that prevents
- cache pollution that can otherwise occur with frequency-based
- replacement policies.
+ use 'default' if this is a parent cache which can
+ be used as a "last-resort" if a peer cannot be located
+ by any of the peer-selection mechanisms.
+ If specified more than once, only the first is used.
- NOTE: if using the LFUDA replacement policy you should increase
- the value of maximum_object_size above its default of 4096 KB to
- to maximize the potential byte hit rate improvement of LFUDA.
+ use 'round-robin' to define a set of parents which
+ should be used in a round-robin fashion in the
+ absence of any ICP queries.
- For more information about the GDSF and LFUDA cache replacement
- policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
- and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
-DOC_END
+ use 'weighted-round-robin' to define a set of parents
+ which should be used in a round-robin fashion with the
+ frequency of each parent being based on the round trip
+ time. Closer parents are used more often.
+ Usually used for background-ping parents.
-NAME: memory_replacement_policy
-TYPE: removalpolicy
-LOC: Config.memPolicy
-DEFAULT: lru
-DOC_START
- The memory replacement policy parameter determines which
- objects are purged from memory when memory space is needed.
+ use 'carp' to define a set of parents which should
+ be used as a CARP array. The requests will be
+ distributed among the parents based on the CARP load
+ balancing hash function based on their weight.
- See cache_replacement_policy for details.
-DOC_END
+ 'multicast-responder' indicates the named peer
+ is a member of a multicast group. ICP queries will
+ not be sent directly to the peer, but ICP replies
+ will be accepted from it.
+ 'closest-only' indicates that, for ICP_OP_MISS
+ replies, we'll only forward CLOSEST_PARENT_MISSes
+ and never FIRST_PARENT_MISSes.
-COMMENT_START
- LOGFILE PATHNAMES AND CACHE DIRECTORIES
- -----------------------------------------------------------------------------
-COMMENT_END
+ use 'no-digest' to NOT request cache digests from
+ this neighbor.
-NAME: cache_dir
-TYPE: cachedir
-DEFAULT: none
-DEFAULT_IF_NONE: ufs @DEFAULT_SWAP_DIR@ 100 16 256
-LOC: Config.cacheSwap
-DOC_START
- Usage:
+ 'no-netdb-exchange' disables requesting ICMP
+ RTT database (NetDB) from the neighbor.
- cache_dir Type Directory-Name Fs-specific-data [options]
+ use 'no-delay' to prevent access to this neighbor
+ from influencing the delay pools.
- You can specify multiple cache_dir lines to spread the
- cache among different disk partitions.
+ use 'login=user:password' if this is a personal/workgroup
+ proxy and your parent requires proxy authentication.
+ Note: The string can include URL escapes (i.e. %20 for
+ spaces). This also means % must be written as %%.
- Type specifies the kind of storage system to use. Only "ufs"
- is built by default. To enable any of the other storage systems
- see the --enable-storeio configure option.
+ use 'login=PASS' if users must authenticate against
+ the upstream proxy or in the case of a reverse proxy
+ configuration, the origin web server. This will pass
+ the users credentials as they are to the peer.
+ This only works for the Basic HTTP authentication scheme.
+ Note: To combine this with proxy_auth both proxies must
+ share the same user database as HTTP only allows for
+ a single login (one for proxy, one for origin server).
+ Also be warned this will expose your users proxy
+ password to the peer. USE WITH CAUTION
- 'Directory' is a top-level directory where cache swap
- files will be stored. If you want to use an entire disk
- for caching, this can be the mount-point directory.
- The directory must exist and be writable by the Squid
- process. Squid will NOT create this directory for you.
+ use 'login=*:password' to pass the username to the
+ upstream cache, but with a fixed password. This is meant
+ to be used when the peer is in another administrative
+ domain, but it is still needed to identify each user.
+ The star can optionally be followed by some extra
+ information which is added to the username. This can
+ be used to identify this proxy to the peer, similar to
+ the login=username:password option above.
- The ufs store type:
+ use 'connect-timeout=nn' to specify a peer
+ specific connect timeout (also see the
+ peer_connect_timeout directive)
- "ufs" is the old well-known Squid storage format that has always
- been there.
+ use 'digest-url=url' to tell Squid to fetch the cache
+ digest (if digests are enabled) for this host from
+ the specified URL rather than the Squid default
+ location.
- cache_dir ufs Directory-Name Mbytes L1 L2 [options]
+ use 'allow-miss' to disable Squid's use of only-if-cached
+ when forwarding requests to siblings. This is primarily
+ useful when icp_hit_stale is used by the sibling. To
+ extensive use of this option may result in forwarding
+ loops, and you should avoid having two-way peerings
+ with this option. (for example to deny peer usage on
+ requests from peer by denying cache_peer_access if the
+ source is a peer)
- 'Mbytes' is the amount of disk space (MB) to use under this
- directory. The default is 100 MB. Change this to suit your
- configuration. Do NOT put the size of your disk drive here.
- Instead, if you want Squid to use the entire disk drive,
- subtract 20% and use that value.
+ use 'max-conn=n' to limit the amount of connections Squid
+ may open to this peer.
- 'Level-1' is the number of first-level subdirectories which
- will be created under the 'Directory'. The default is 16.
+ use 'htcp' to send HTCP, instead of ICP, queries
+ to the neighbor. You probably also want to
+ set the "icp port" to 4827 instead of 3130.
+ You MUST also set htcp_access expicitly. The default of
+ deny all will prevent peer traffic.
- 'Level-2' is the number of second-level subdirectories which
- will be created under each first-level directory. The default
- is 256.
+ use 'htcp-oldsquid' to send HTCP to old Squid versions
+ You MUST also set htcp_access expicitly. The default of
+ deny all will prevent peer traffic.
- The aufs store type:
+ 'originserver' causes this parent peer to be contacted as
+ a origin server. Meant to be used in accelerator setups.
- "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.
+ use 'name=xxx' if you have multiple peers on the same
+ host but different ports. This name can be used to
+ differentiate the peers in cache_peer_access and similar
+ directives.
- cache_dir aufs Directory-Name Mbytes L1 L2 [options]
+ use 'forceddomain=name' to forcibly set the Host header
+ of requests forwarded to this peer. Useful in accelerator
+ setups where the server (peer) expects a certain domain
+ name and using redirectors to feed this domain name
+ is not feasible.
- see argument descriptions under ufs above
+ use 'ssl' to indicate connections to this peer should
+ be SSL/TLS encrypted.
- The diskd store type:
+ use 'sslcert=/path/to/ssl/certificate' to specify a client
+ SSL certificate to use when connecting to this peer.
- "diskd" uses the same storage format as "ufs", utilizing a
- separate process to avoid blocking the main Squid process on
- disk-I/O.
+ use 'sslkey=/path/to/ssl/key' to specify the private SSL
+ key corresponding to sslcert above. If 'sslkey' is not
+ specified 'sslcert' is assumed to reference a
+ combined file containing both the certificate and the key.
- cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
+ use sslversion=1|2|3|4 to specify the SSL version to use
+ when connecting to this peer
+ 1 = automatic (default)
+ 2 = SSL v2 only
+ 3 = SSL v3 only
+ 4 = TLS v1 only
- see argument descriptions under ufs above
+ use sslcipher=... to specify the list of valid SSL ciphers
+ to use when connecting to this peer.
- Q1 specifies the number of unacknowledged I/O requests when Squid
- stops opening new files. If this many messages are in the queues,
- Squid won't open new files. Default is 64
+ use ssloptions=... to specify various SSL engine options:
+ NO_SSLv2 Disallow the use of SSLv2
+ NO_SSLv3 Disallow the use of SSLv3
+ NO_TLSv1 Disallow the use of TLSv1
+ See src/ssl_support.c or the OpenSSL documentation for
+ a more complete list.
- Q2 specifies the number of unacknowledged messages when Squid
- starts blocking. If this many messages are in the queues,
- Squid blocks until it receives some replies. Default is 72
+ use sslcafile=... to specify a file containing
+ additional CA certificates to use when verifying the
+ peer certificate.
- When Q1 < Q2 (the default), the cache directory is optimized
- for lower response time at the expense of a decrease in hit
- ratio. If Q1 > Q2, the cache directory is optimized for
- higher hit ratio at the expense of an increase in response
- time.
+ use sslcapath=... to specify a directory containing
+ additional CA certificates to use when verifying the
+ peer certificate.
- The coss store type:
+ use sslcrlfile=... to specify a certificate revocation
+ list file to use when verifying the peer certificate.
+
+ use sslflags=... to specify various flags modifying the
+ SSL implementation:
+ DONT_VERIFY_PEER
+ Accept certificates even if they fail to
+ verify.
+ NO_DEFAULT_CA
+ Don't use the default CA list built in
+ to OpenSSL.
+ DONT_VERIFY_DOMAIN
+ Don't verify the peer certificate
+ matches the server name
- block-size=n defines the "block size" for COSS cache_dir's.
- Squid uses file numbers as block numbers. Since file numbers
- are limited to 24 bits, the block size determines the maximum
- size of the COSS partition. The default is 512 bytes, which
- leads to a maximum cache_dir size of 512<<24, or 8 GB. Note
- you should not change the coss block size after Squid
- has written some objects to the cache_dir.
+ 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.
- The coss file store has changed from 2.5. Now it uses a file
- called 'stripe' in the directory names in the config - and
- this will be created by squid -z.
+ use front-end-https to enable the "Front-End-Https: On"
+ header needed when using Squid as a SSL frontend in front
+ of Microsoft OWA. See MS KB document Q307347 for details
+ on this header. If set to auto the header will
+ only be added if the request is forwarded as a https://
+ URL.
+DOC_END
- Common options:
+NAME: cache_peer_domain cache_host_domain
+TYPE: hostdomain
+DEFAULT: none
+LOC: none
+DOC_START
+ Use to limit the domains for which a neighbor cache will be
+ queried. Usage:
- no-store, no new objects should be stored to this cache_dir
+ cache_peer_domain cache-host domain [domain ...]
+ cache_peer_domain cache-host !domain
- max-size=n, refers to the max object size this storedir supports.
- It is used to initially choose the storedir to dump the object.
- Note: To make optimal use of the max-size limits you should order
- the cache_dir lines with the smallest max-size value first and the
- ones with no max-size specification last.
+ For example, specifying
- 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.
+ cache_peer_domain parent.foo.net .edu
- The null store type:
+ has the effect such that UDP query packets are sent to
+ 'bigserver' only when the requested object exists on a
+ server in the .edu domain. Prefixing the domainname
+ with '!' means the cache will be queried for objects
+ NOT in that domain.
- no options are allowed or required
+ NOTE: * Any number of domains may be given for a cache-host,
+ either on the same or separate lines.
+ * When multiple domains are given for a particular
+ cache-host, the first matched domain is applied.
+ * Cache hosts with no domain restrictions are queried
+ for all requests.
+ * There are no defaults.
+ * There is also a 'cache_peer_access' tag in the ACL
+ section.
DOC_END
-
-NAME: logformat
-TYPE: logformat
-LOC: Config.Log.logformats
+NAME: cache_peer_access
+TYPE: peer_access
DEFAULT: none
+LOC: none
DOC_START
- Usage:
-
- logformat <name> <format specification>
-
- Defines an access log format.
-
- The <format specification> is a string with embedded % format codes
+ Similar to 'cache_peer_domain' but provides more flexibility by
+ using ACL elements.
- % format codes all follow the same basic structure where all but
- the formatcode is optional. Output strings are automatically escaped
- as required according to their context and the output format
- modifiers are usually not needed, but can be specified if an explicit
- output format is desired.
+ cache_peer_access cache-host allow|deny [!]aclname ...
- % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
+ The syntax is identical to 'http_access' and the other lists of
+ ACL elements. See the comments for 'http_access' below, or
+ the Squid FAQ (http://www.squid-cache.org/FAQ/FAQ-10.html).
+DOC_END
- " output in quoted string format
- [ output in squid text log format as used by log_mime_hdrs
- # output in URL quoted format
- ' output as-is
+NAME: neighbor_type_domain
+TYPE: hostdomaintype
+DEFAULT: none
+LOC: none
+DOC_START
+ usage: neighbor_type_domain neighbor parent|sibling domain domain ...
- - left aligned
- width field width. If starting with 0 the
- output is zero padded
- {arg} argument such as header name etc
+ Modifying the neighbor type for specific domains is now
+ possible. You can treat some domains differently than the the
+ default neighbor type specified on the 'cache_peer' line.
+ Normally it should only be necessary to list domains which
+ should be treated differently because the default neighbor type
+ applies for hostnames which do not match domains listed here.
- Format codes:
+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
+DOC_END
- >a Client source IP address
- >A Client FQDN
- >p Client source port
- <A Server IP address or peer name
- la Local IP address (http_port)
- lp Local port number (http_port)
- ts Seconds since epoch
- tu subsecond time (milliseconds)
- tl Local time. Optional strftime format argument
- default %d/%b/%Y:%H:%M:S %z
- tg GMT time. Optional strftime format argument
- default %d/%b/%Y:%H:%M:S %z
- tr Response time (milliseconds)
- >h Request header. Optional header name argument
- on the format header[:[separator]element]
- <h Reply header. Optional header name argument
- as for >h
- un User name
- ul User login
- ui User ident
- ue User from external acl
- Hs HTTP status code
- Ss Squid request status (TCP_MISS etc)
- Sh Squid hierarchy status (DEFAULT_PARENT etc)
- mt MIME content type
- rm Request method (GET/POST etc)
- ru Request URL
- rp Request URL-Path excluding hostname
- rv Request protocol version
- et Tag returned by external acl
- ea Log string returned by external acl
- <st Reply size including HTTP headers
- <sH Reply high offset sent
- <sS Upstream object size
- % a literal % character
+NAME: dead_peer_timeout
+COMMENT: (seconds)
+DEFAULT: 10 seconds
+TYPE: time_t
+LOC: Config.Timeout.deadPeer
+DOC_START
+ This controls how long Squid waits to declare a peer cache
+ as "dead." If there are no ICP replies received in this
+ amount of time, Squid will declare the peer dead and not
+ expect to receive any further ICP replies. However, it
+ continues to send ICP queries, and will mark the peer as
+ alive upon receipt of the first subsequent ICP reply.
-logformat squid %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
-logformat squidmime %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h]
-logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st %Ss:%Sh
-logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
+ This timeout also affects when Squid expects to receive ICP
+ replies from peers. If more than 'dead_peer' seconds have
+ passed since the last ICP reply was received, Squid will not
+ expect to receive an ICP reply on the next query. Thus, if
+ your time between requests is greater than this timeout, you
+ will see a lot of requests sent DIRECT to origin servers
+ instead of to your parents.
DOC_END
-NAME: access_log cache_access_log
-TYPE: access_log
-LOC: Config.Log.accesslogs
+NAME: hierarchy_stoplist
+TYPE: wordlist
DEFAULT: none
-DEFAULT_IF_NONE: @DEFAULT_ACCESS_LOG@
+LOC: Config.hierarchy_stoplist
DOC_START
- These files log client request activities. Has a line every HTTP or
- ICP request. The format is:
- access_log <filepath> [<logformat name> [acl acl ...]]
- access_log none [acl acl ...]]
+ A list of words which, if found in a URL, cause the object to
+ be handled directly by this cache. In other words, use this
+ to not query neighbor caches for certain objects. You may
+ list this option multiple times.
+ Note: never_direct overrides this option.
+NOCOMMENT_START
+#We recommend you to use at least the following line.
+hierarchy_stoplist cgi-bin ?
+NOCOMMENT_END
+DOC_END
- Will log to the specified file using the specified format (which
- must be defined in a logformat directive) those entries which match
- ALL the acl's specified (which must be defined in acl clauses).
- If no acl is specified, all requests will be logged to this file.
+COMMENT_START
+ MEMORY CACHE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
- To disable logging of a request use the filepath "none", in which case
- a logformat name should not be specified.
+NAME: cache_mem
+COMMENT: (bytes)
+TYPE: b_size_t
+DEFAULT: 8 MB
+LOC: Config.memMaxSize
+DOC_START
+ NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE.
+ IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL
+ USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER
+ THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS.
- To log the request via syslog specify a filepath of "syslog":
+ 'cache_mem' specifies the ideal amount of memory to be used
+ for:
+ * In-Transit objects
+ * Hot Objects
+ * Negative-Cached objects
- access_log syslog[:facility|priority] [format [acl1 [acl2 ....]]]
- where facility could be any of:
- LOG_AUTHPRIV, LOG_DAEMON, LOG_LOCAL0 .. LOG_LOCAL7 or LOG_USER.
+ Data for these objects are stored in 4 KB blocks. This
+ parameter specifies the ideal upper limit on the total size of
+ 4 KB blocks allocated. In-Transit objects take the highest
+ priority.
- And priority could be any of:
- LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.
-DOC_END
+ In-transit objects have priority over the others. When
+ additional space is needed for incoming data, negative-cached
+ and hot objects will be released. In other words, the
+ negative-cached and hot objects will fill up any unused space
+ not needed for in-transit objects.
+ If circumstances require, this limit will be exceeded.
+ Specifically, if your incoming request rate requires more than
+ 'cache_mem' of memory to hold in-transit objects, Squid will
+ exceed this limit to satisfy the new requests. When the load
+ decreases, blocks will be freed until the high-water mark is
+ reached. Thereafter, blocks will be used to store hot
+ objects.
+DOC_END
-NAME: cache_log
-TYPE: string
-DEFAULT: @DEFAULT_CACHE_LOG@
-LOC: Config.Log.log
+NAME: maximum_object_size_in_memory
+COMMENT: (bytes)
+TYPE: b_size_t
+DEFAULT: 8 KB
+LOC: Config.Store.maxInMemObjSize
DOC_START
- Cache logging file. This is where general information about
- your cache's behavior goes. You can increase the amount of data
- logged to this file with the "debug_options" tag below.
+ Objects greater than this size will not be attempted to kept in
+ the memory cache. This should be set high enough to keep objects
+ accessed frequently in memory to improve performance whilst low
+ enough to keep larger objects from hoarding cache_mem.
DOC_END
-
-NAME: cache_store_log
-TYPE: string
-DEFAULT: @DEFAULT_STORE_LOG@
-LOC: Config.Log.store
+NAME: memory_replacement_policy
+TYPE: removalpolicy
+LOC: Config.memPolicy
+DEFAULT: lru
DOC_START
- Logs the activities of the storage manager. Shows which
- objects are ejected from the cache, and which objects are
- saved and for how long. To disable, enter "none". There are
- not really utilities to analyze this data, so you can safely
- disable it.
+ The memory replacement policy parameter determines which
+ objects are purged from memory when memory space is needed.
+
+ See cache_replacement_policy for details.
DOC_END
+COMMENT_START
+ DISK CACHE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
-NAME: cache_swap_state cache_swap_log
-TYPE: string
-LOC: Config.Log.swap
-DEFAULT: none
+NAME: cache_replacement_policy
+TYPE: removalpolicy
+LOC: Config.replPolicy
+DEFAULT: lru
DOC_START
- Location for the cache "swap.state" file. This index file holds
- the metadata of objects saved on disk. It is used to rebuild
- the cache during startup. Normally this file resides in each
- 'cache_dir' directory, but you may specify an alternate
- pathname here. Note you must give a full filename, not just
- a directory. Since this is the index for the whole object
- list you CANNOT periodically rotate it!
+ The cache replacement policy parameter determines which
+ objects are evicted (replaced) when disk space is needed.
- If %s can be used in the file name it will be replaced with a
- a representation of the cache_dir name where each / is replaced
- with '.'. This is needed to allow adding/removing cache_dir
- lines when cache_swap_log is being used.
+ lru : Squid's original list based LRU policy
+ heap GDSF : Greedy-Dual Size Frequency
+ heap LFUDA: Least Frequently Used with Dynamic Aging
+ heap LRU : LRU policy implemented using a heap
- If have more than one 'cache_dir', and %s is not used in the name
- these swap logs will have names such as:
+ Applies to any cache_dir lines listed below this.
- cache_swap_log.00
- cache_swap_log.01
- cache_swap_log.02
+ The LRU policies keeps recently referenced objects.
- 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
- 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.
-DOC_END
+ The heap GDSF policy optimizes object hit rate by keeping smaller
+ popular objects in cache so it has a better chance of getting a
+ hit. It achieves a lower byte hit rate than LFUDA though since
+ it evicts larger (possibly popular) objects.
+
+ The heap LFUDA policy keeps popular objects in cache regardless of
+ their size and thus optimizes byte hit rate at the expense of
+ hit rate since one large, popular object will prevent many
+ smaller, slightly less popular objects from being cached.
+
+ Both policies utilize a dynamic aging mechanism that prevents
+ cache pollution that can otherwise occur with frequency-based
+ replacement policies.
+ NOTE: if using the LFUDA replacement policy you should increase
+ the value of maximum_object_size above its default of 4096 KB to
+ to maximize the potential byte hit rate improvement of LFUDA.
-NAME: emulate_httpd_log
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.common_log
-DOC_START
- The Cache can emulate the log file format which many 'httpd'
- programs use. To disable/enable this emulation, set
- emulate_httpd_log to 'off' or 'on'. The default
- is to use the native log format since it includes useful
- information Squid-specific log analyzers use.
+ For more information about the GDSF and LFUDA cache replacement
+ policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html
+ and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html.
DOC_END
-NAME: log_ip_on_direct
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.log_ip_on_direct
+NAME: cache_dir
+TYPE: cachedir
+DEFAULT: none
+LOC: Config.cacheSwap
DOC_START
- Log the destination IP address in the hierarchy log tag when going
- direct. Earlier Squid versions logged the hostname here. If you
- prefer the old way set this to off.
-DOC_END
+ Usage:
-NAME: mime_table
-TYPE: string
-DEFAULT: @DEFAULT_MIME_TABLE@
-LOC: Config.mimeTablePathname
-DOC_START
- Pathname to Squid's MIME table. You shouldn't need to change
- this, but the default file contains examples and formatting
- information if you do.
-DOC_END
+ cache_dir Type Directory-Name Fs-specific-data [options]
+ You can specify multiple cache_dir lines to spread the
+ cache among different disk partitions.
-NAME: log_mime_hdrs
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.log_mime_hdrs
-DEFAULT: off
-DOC_START
- The Cache can record both the request and the response MIME
- headers for each HTTP transaction. The headers are encoded
- safely and will appear as two bracketed fields at the end of
- the access log (for either the native or httpd-emulated log
- formats). To enable this logging set log_mime_hdrs to 'on'.
-DOC_END
+ Type specifies the kind of storage system to use. Only "ufs"
+ is built by default. To enable any of the other storage systems
+ see the --enable-storeio configure option.
+ 'Directory' is a top-level directory where cache swap
+ files will be stored. If you want to use an entire disk
+ for caching, this can be the mount-point directory.
+ The directory must exist and be writable by the Squid
+ process. Squid will NOT create this directory for you.
-NAME: useragent_log
-TYPE: string
-LOC: Config.Log.useragent
-DEFAULT: none
-IFDEF: USE_USERAGENT_LOG
-DOC_START
- Squid will write the User-Agent field from HTTP requests
- to the filename specified here. By default useragent_log
- is disabled.
-DOC_END
+ The ufs store type:
+ "ufs" is the old well-known Squid storage format that has always
+ been there.
-NAME: referer_log
-TYPE: string
-LOC: Config.Log.referer
-DEFAULT: none
-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.
-DOC_END
+ 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
+ configuration. Do NOT put the size of your disk drive here.
+ Instead, if you want Squid to use the entire disk drive,
+ subtract 20% and use that value.
-NAME: pid_filename
-TYPE: string
-DEFAULT: @DEFAULT_PID_FILE@
-LOC: Config.pidFilename
-DOC_START
- A filename to write the process-id to. To disable, enter "none".
-DOC_END
+ 'Level-1' is the number of first-level subdirectories which
+ will be created under the 'Directory'. The default is 16.
+ 'Level-2' is the number of second-level subdirectories which
+ will be created under each first-level directory. The default
+ is 256.
-NAME: debug_options
-TYPE: debug
-DEFAULT: ALL,1
-LOC: Config.debugOptions
-DOC_START
- Logging options are set as section,level where each source file
- is assigned a unique section. Lower levels result in less
- output, Full debugging (level 9) can result in a very large
- log file, so be careful. The magic word "ALL" sets debugging
- levels for all sections. We recommend normally running with
- "ALL,1".
-DOC_END
+ 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.
-NAME: log_fqdn
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.log_fqdn
-DOC_START
- Turn this on if you wish to log fully qualified domain names
- in the access.log. To do this Squid does a DNS lookup of all
- IP's connecting to it. This can (in some situations) increase
- latency, which makes your cache seem slower for interactive
- browsing.
-DOC_END
+ cache_dir aufs Directory-Name Mbytes L1 L2 [options]
+ see argument descriptions under ufs above
-NAME: client_netmask
-TYPE: address
-LOC: Config.Addrs.client_netmask
-DEFAULT: 255.255.255.255
-DOC_START
- A netmask for client addresses in logfiles and cachemgr output.
- Change this to protect the privacy of your cache clients.
- A netmask of 255.255.255.0 will log all IP's in that range with
- the last digit set to '0'.
-DOC_END
+ 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.
-COMMENT_START
- OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
- -----------------------------------------------------------------------------
-COMMENT_END
+ cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]
-NAME: ftp_user
-TYPE: string
-DEFAULT: Squid@
-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
- reasonable for your domain, like wwwuser@somewhere.net
+ see argument descriptions under ufs above
- The reason why this is domainless by default is the
- request can be made on the behalf of a user in any domain,
- depending on how the cache is used.
- Some ftp server also validate the email address is valid
- (for example perl.com).
-DOC_END
+ Q1 specifies the number of unacknowledged I/O requests when Squid
+ stops opening new files. If this many messages are in the queues,
+ Squid won't open new files. Default is 64
-NAME: ftp_list_width
-TYPE: size_t
-DEFAULT: 32
-LOC: Config.Ftp.list_width
-DOC_START
- Sets the width of ftp listings. This should be set to fit in
- the width of a standard browser. Setting this too small
- can cut off long filenames when browsing ftp sites.
-DOC_END
+ Q2 specifies the number of unacknowledged messages when Squid
+ starts blocking. If this many messages are in the queues,
+ Squid blocks until it receives some replies. Default is 72
-NAME: ftp_passive
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.passive
-DOC_START
- If your firewall does not allow Squid to use passive
- connections, turn off this option.
-DOC_END
+ When Q1 < Q2 (the default), the cache directory is optimized
+ for lower response time at the expense of a decrease in hit
+ ratio. If Q1 > Q2, the cache directory is optimized for
+ higher hit ratio at the expense of an increase in response
+ time.
-NAME: ftp_sanitycheck
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.sanitycheck
-DOC_START
- For security and data integrity reasons Squid by default performs
- sanity checks of the addresses of FTP data connections ensure the
- data connection is to the requested server. If you need to allow
- FTP connections to servers using another IP address for the data
- connection turn this off.
-DOC_END
+ The coss store type:
-NAME: check_hostnames
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.check_hostnames
-DOC_START
- For security and stability reasons Squid can check
- hostnames for Internet standard RFC compliance. If you want
- Squid to perform these checks turn this directive on.
-DOC_END
+ block-size=n defines the "block size" for COSS cache_dir's.
+ Squid uses file numbers as block numbers. Since file numbers
+ are limited to 24 bits, the block size determines the maximum
+ size of the COSS partition. The default is 512 bytes, which
+ leads to a maximum cache_dir size of 512<<24, or 8 GB. Note
+ you should not change the coss block size after Squid
+ has written some objects to the cache_dir.
-NAME: allow_underscore
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.allow_underscore
-DOC_START
- Underscore characers 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.
-DOC_END
+ The coss file store has changed from 2.5. Now it uses a file
+ called 'stripe' in the directory names in the config - and
+ this will be created by squid -z.
-NAME: ftp_telnet_protocol
-TYPE: onoff
-DEFAULT: on
-LOC: Config.Ftp.telnet
-DOC_START
-The FTP protocol is officially defined to use the telnet protocol
-as transport channel for the control connection. However, many
-implementations are broken and does not respect this aspect of
-the FTP protocol.
+ Common options:
+
+ no-store, no new objects should be stored to this cache_dir
+
+ max-size=n, refers to the max object size this storedir supports.
+ It is used to initially choose the storedir to dump the object.
+ Note: To make optimal use of the max-size limits you should order
+ the cache_dir lines with the smallest max-size value first and the
+ ones with no max-size specification last.
-If you have trouble accessing files with ASCII code 255 in the
-path or similar problems involving this ASCII code you can
-try setting this directive to off. If that helps, report to the
-operator of the FTP server in question that their FTP server
-is broken and does not follow the FTP standard.
+ 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
+DEFAULT_IF_NONE: ufs @DEFAULT_SWAP_DIR@ 100 16 256
+NOCOMMENT_END
DOC_END
-NAME: cache_dns_program
+NAME: store_dir_select_algorithm
TYPE: string
-IFDEF: USE_DNSSERVERS
-DEFAULT: @DEFAULT_DNSSERVER@
-LOC: Config.Program.dnsserver
+LOC: Config.store_dir_select_algorithm
+DEFAULT: least-load
DOC_START
- Specify the location of the executable for dnslookup process.
+ Set this to 'round-robin' as an alternative.
DOC_END
-NAME: dns_children
+NAME: max_open_disk_fds
TYPE: int
-IFDEF: USE_DNSSERVERS
-DEFAULT: 5
-LOC: Config.dnsChildren
+LOC: Config.max_open_disk_fds
+DEFAULT: 0
DOC_START
- The number of processes spawn to service DNS name lookups.
- For heavily loaded caches on large servers, you should
- probably increase this value to at least 10. The maximum
- is 32. The default is 5.
+ To avoid having disk as the I/O bottleneck Squid can optionally
+ bypass the on-disk cache if more than this amount of disk file
+ descriptors are open.
- You must have at least one dnsserver process.
+ A value of 0 indicates no limit.
DOC_END
-NAME: dns_retransmit_interval
-TYPE: time_t
-DEFAULT: 5 seconds
-LOC: Config.Timeout.idns_retransmit
-IFDEF: !USE_DNSSERVERS
+NAME: minimum_object_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 0 KB
+LOC: Config.Store.minObjectSize
DOC_START
- Initial retransmit interval for DNS queries. The interval is
- doubled each time all configured DNS servers have been tried.
-
+ Objects smaller than this size will NOT be saved on disk. The
+ value is specified in kilobytes, and the default is 0 KB, which
+ means there is no minimum.
DOC_END
-NAME: dns_timeout
-TYPE: time_t
-DEFAULT: 5 minutes
-LOC: Config.Timeout.idns_query
-IFDEF: !USE_DNSSERVERS
+NAME: maximum_object_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 4096 KB
+LOC: Config.Store.maxObjectSize
DOC_START
- DNS Query timeout. If no response is received to a DNS query
- within this time all DNS servers for the queried domain
- are assumed to be unavailable.
+ Objects larger than this size will NOT be saved on disk. The
+ value is specified in kilobytes, and the default is 4MB. If
+ you wish to get a high BYTES hit ratio, you should probably
+ increase this (one 32 MB object hit counts for 3200 10KB
+ hits). If you wish to increase speed more than your want to
+ save bandwidth you should leave this low.
+
+ NOTE: if using the LFUDA replacement policy you should increase
+ this value to maximize the byte hit rate improvement of LFUDA!
+ See replacement_policy below for a discussion of this policy.
DOC_END
-NAME: dns_defnames
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.res_defnames
+NAME: cache_swap_low
+COMMENT: (percent, 0-100)
+TYPE: int
+DEFAULT: 90
+LOC: Config.Swap.lowWaterMark
+DOC_NONE
+
+NAME: cache_swap_high
+COMMENT: (percent, 0-100)
+TYPE: int
+DEFAULT: 95
+LOC: Config.Swap.highWaterMark
DOC_START
- Normally the RES_DEFNAMES resolver option is disabled
- (see res_init(3)). This prevents caches in a hierarchy
- from interpreting single-component hostnames locally. To allow
- Squid to handle single-component names, enable this option.
+
+ The low- and high-water marks for cache object replacement.
+ Replacement begins when the swap (disk) usage is above the
+ low-water mark and attempts to maintain utilization near the
+ low-water mark. As swap utilization gets close to high-water
+ mark object eviction becomes more aggressive. If utilization is
+ close to the low-water mark less replacement is done each time.
+
+ Defaults are 90% and 95%. If you have a large cache, 5% could be
+ hundreds of MB. If this is the case you may wish to set these
+ numbers closer together.
DOC_END
-NAME: dns_nameservers
-TYPE: wordlist
+COMMENT_START
+ LOGFILE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: logformat
+TYPE: logformat
+LOC: Config.Log.logformats
DEFAULT: none
-LOC: Config.dns_nameservers
DOC_START
- Use this if you want to specify a list of DNS name servers
- (IP addresses) to use instead of those given in your
- /etc/resolv.conf file.
- On Windows platforms, if no value is specified here or in
- the /etc/resolv.conf file, the list of DNS name servers are
- taken from the Windows registry, both static and dynamic DHCP
- configurations are supported.
+ Usage:
- Example: dns_nameservers 10.0.0.1 192.172.0.4
+ logformat <name> <format specification>
+
+ Defines an access log format.
+
+ The <format specification> is a string with embedded % format codes
+
+ % format codes all follow the same basic structure where all but
+ the formatcode is optional. Output strings are automatically escaped
+ as required according to their context and the output format
+ modifiers are usually not needed, but can be specified if an explicit
+ output format is desired.
+
+ % ["|[|'|#] [-] [[0]width] [{argument}] formatcode
+
+ " output in quoted string format
+ [ output in squid text log format as used by log_mime_hdrs
+ # output in URL quoted format
+ ' output as-is
+
+ - left aligned
+ width field width. If starting with 0 the
+ output is zero padded
+ {arg} argument such as header name etc
+
+ Format codes:
+
+ >a Client source IP address
+ >A Client FQDN
+ >p Client source port
+ <A Server IP address or peer name
+ la Local IP address (http_port)
+ lp Local port number (http_port)
+ ts Seconds since epoch
+ tu subsecond time (milliseconds)
+ tl Local time. Optional strftime format argument
+ default %d/%b/%Y:%H:%M:%S %z
+ tg GMT time. Optional strftime format argument
+ default %d/%b/%Y:%H:%M:%S %z
+ tr Response time (milliseconds)
+ >h Request header. Optional header name argument
+ on the format header[:[separator]element]
+ <h Reply header. Optional header name argument
+ as for >h
+ un User name
+ ul User name from authentication
+ ui User name from ident
+ us User name from SSL
+ ue User name from external acl helper
+ Hs HTTP status code
+ Ss Squid request status (TCP_MISS etc)
+ Sh Squid hierarchy status (DEFAULT_PARENT etc)
+ mt MIME content type
+ rm Request method (GET/POST etc)
+ ru Request URL
+ rp Request URL-Path excluding hostname
+ rv Request protocol version
+ et Tag returned by external acl
+ ea Log string returned by external acl
+ <st Reply size including HTTP headers
+ <sH Reply high offset sent
+ <sS Upstream object size
+ % a literal % character
+
+logformat squid %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
+logformat squidmime %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h]
+logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st %Ss:%Sh
+logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
DOC_END
-NAME: hosts_file
-TYPE: string
-DEFAULT: @DEFAULT_HOSTS@
-LOC: Config.etcHostsPath
+NAME: access_log cache_access_log
+TYPE: access_log
+LOC: Config.Log.accesslogs
+DEFAULT: none
DOC_START
- Location of the host-local IP name-address associations
- database. Most Operating Systems have such a file on different
- default locations:
- - Un*X & Linux: /etc/hosts
- - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
- (%SystemRoot% value install default is c:\winnt)
- - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
- (%SystemRoot% value install default is c:\windows)
- - Windows 9x/Me: %windir%\hosts
- (%windir% value is usually c:\windows)
- - Cygwin: /etc/hosts
+ These files log client request activities. Has a line every HTTP or
+ ICP request. The format is:
+ access_log <filepath> [<logformat name> [acl acl ...]]
+ access_log none [acl acl ...]]
- The file contains newline-separated definitions, in the
- form ip_address_in_dotted_form name [name ...] names are
- whitespace-separated. Lines beginning with an hash (#)
- character are comments.
+ Will log to the specified file using the specified format (which
+ must be defined in a logformat directive) those entries which match
+ ALL the acl's specified (which must be defined in acl clauses).
+ If no acl is specified, all requests will be logged to this file.
- The file is checked at startup and upon configuration.
- If set to 'none', it won't be checked.
- If append_domain is used, that domain will be added to
- domain-local (i.e. not containing any dot character) host
- definitions.
+ To disable logging of a request use the filepath "none", in which case
+ a logformat name should not be specified.
+
+ To log the request via syslog specify a filepath of "syslog":
+
+ access_log syslog[:facility.priority] [format [acl1 [acl2 ....]]]
+ where facility could be any of:
+ authpriv, daemon, local0 .. local7 or user.
+
+ And priority could be any of:
+ err, warning, notice, info, debug.
+NOCOMMENT_START
+access_log @DEFAULT_ACCESS_LOG@ squid
+NOCOMMENT_END
DOC_END
-NAME: diskd_program
+NAME: log_access
+TYPE: acl_access
+LOC: Config.accessList.log
+DEFAULT: none
+COMMENT: allow|deny acl acl...
+DOC_START
+ This options allows you to control which requests gets logged
+ to access.log (see access_log directive). Requests denied for
+ logging will also not be accounted for in performance counters.
+DOC_END
+
+NAME: cache_log
TYPE: string
-DEFAULT: @DEFAULT_DISKD@
-LOC: Config.Program.diskd
+DEFAULT: @DEFAULT_CACHE_LOG@
+LOC: Config.Log.log
DOC_START
- Specify the location of the diskd executable.
- Note this is only useful if you have compiled in
- diskd as one of the store io modules.
+ Cache logging file. This is where general information about
+ your cache's behavior goes. You can increase the amount of data
+ logged to this file with the "debug_options" tag below.
DOC_END
-NAME: unlinkd_program
-IFDEF: USE_UNLINKD
+NAME: cache_store_log
TYPE: string
-DEFAULT: @DEFAULT_UNLINKD@
-LOC: Config.Program.unlinkd
+DEFAULT: @DEFAULT_STORE_LOG@
+LOC: Config.Log.store
DOC_START
- Specify the location of the executable for file deletion process.
+ Logs the activities of the storage manager. Shows which
+ objects are ejected from the cache, and which objects are
+ saved and for how long. To disable, enter "none". There are
+ not really utilities to analyze this data, so you can safely
+ disable it.
DOC_END
-NAME: pinger_program
+NAME: cache_swap_state cache_swap_log
TYPE: string
-DEFAULT: @DEFAULT_PINGER@
-LOC: Config.Program.pinger
-IFDEF: USE_ICMP
+LOC: Config.Log.swap
+DEFAULT: none
DOC_START
- Specify the location of the executable for the pinger process.
-DOC_END
+ Location for the cache "swap.state" file. This index file holds
+ the metadata of objects saved on disk. It is used to rebuild
+ the cache during startup. Normally this file resides in each
+ 'cache_dir' directory, but you may specify an alternate
+ pathname here. Note you must give a full filename, not just
+ a directory. Since this is the index for the whole object
+ list you CANNOT periodically rotate it!
+ If %s can be used in the file name it will be replaced with a
+ a representation of the cache_dir name where each / is replaced
+ with '.'. This is needed to allow adding/removing cache_dir
+ lines when cache_swap_log is being used.
-NAME: url_rewrite_program redirect_program
-TYPE: wordlist
-LOC: Config.Program.redirect
-DEFAULT: none
-DOC_START
- Specify the location of the executable for the URL redirector.
- 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.
-DOC_END
+ If have more than one 'cache_dir', and %s is not used in the name
+ these swap logs will have names such as:
+ cache_swap_log.00
+ cache_swap_log.01
+ cache_swap_log.02
-NAME: url_rewrite_children redirect_children
+ The numbered extension (which is added automatically)
+ corresponds to the order of the 'cache_dir' lines in this
+ configuration file. If you change the order of the 'cache_dir'
+ lines in this file, these index files will NOT correspond to
+ the correct 'cache_dir' entry (unless you manually rename
+ them). We recommend you do NOT use this option. It is
+ better to keep these index files in each 'cache_dir' directory.
+DOC_END
+
+NAME: logfile_rotate
TYPE: int
-DEFAULT: 5
-LOC: Config.redirectChildren
+DEFAULT: 10
+LOC: Config.Log.rotateNumber
DOC_START
- The number of redirector processes to spawn. If you start
- too few Squid will have to wait for them to process a backlog of
- URLs, slowing it down. If you start too many they will use RAM
- and other system resources.
+ Specifies the number of logfile rotations to make when you
+ type 'squid -k rotate'. The default is 10, which will rotate
+ with extensions 0 through 9. Setting logfile_rotate to 0 will
+ disable the file name rotation, but the logfiles are still closed
+ and re-opened. This will enable you to rename the logfiles
+ yourself just before sending the rotate signal.
+
+ Note, the 'squid -k rotate' command normally sends a USR1
+ signal to the running squid process. In certain situations
+ (e.g. on Linux with Async I/O), USR1 is used for other
+ purposes, so -k rotate uses another signal. It is best to get
+ in the habit of using 'squid -k rotate' instead of 'kill -USR1
+ <pid>'.
DOC_END
-NAME: url_rewrite_concurrency redirect_concurrency
-TYPE: int
-DEFAULT: 0
-LOC: Config.redirectConcurrency
+NAME: emulate_httpd_log
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.common_log
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.
+ The Cache can emulate the log file format which many 'httpd'
+ programs use. To disable/enable this emulation, set
+ emulate_httpd_log to 'off' or 'on'. The default
+ is to use the native log format since it includes useful
+ information Squid-specific log analyzers use.
DOC_END
-NAME: url_rewrite_host_header redirect_rewrites_host_header
+NAME: log_ip_on_direct
+COMMENT: on|off
TYPE: onoff
DEFAULT: on
-LOC: Config.onoff.redir_rewrites_host
+LOC: Config.onoff.log_ip_on_direct
DOC_START
- By default Squid rewrites any Host: header in redirected
- requests. If you are running an accelerator this may
- not be a wanted effect of a redirector.
+ Log the destination IP address in the hierarchy log tag when going
+ direct. Earlier Squid versions logged the hostname here. If you
+ prefer the old way set this to off.
+DOC_END
- WARNING: Entries are cached on the result of the URL rewriting
- process, so be careful if you have domain-virtual hosts.
+NAME: mime_table
+TYPE: string
+DEFAULT: @DEFAULT_MIME_TABLE@
+LOC: Config.mimeTablePathname
+DOC_START
+ Pathname to Squid's MIME table. You shouldn't need to change
+ this, but the default file contains examples and formatting
+ information if you do.
DOC_END
-NAME: redirector_access
-TYPE: acl_access
-DEFAULT: none
-LOC: Config.accessList.redirector
+NAME: log_mime_hdrs
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.log_mime_hdrs
+DEFAULT: off
DOC_START
- If defined, this access list specifies which requests are
- sent to the redirector processes. By default all requests
- are sent.
+ The Cache can record both the request and the response MIME
+ headers for each HTTP transaction. The headers are encoded
+ safely and will appear as two bracketed fields at the end of
+ the access log (for either the native or httpd-emulated log
+ formats). To enable this logging set log_mime_hdrs to 'on'.
DOC_END
-NAME: auth_param
-TYPE: authparam
-LOC: Config.authConfiguration
+NAME: useragent_log
+TYPE: string
+LOC: Config.Log.useragent
DEFAULT: none
+IFDEF: USE_USERAGENT_LOG
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.
-
- 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).
-
- 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.
-
- === 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
- "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
-
- Then, 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.
- 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.
- auth_param basic concurrency 0
-
- "realm" realmstring
- Specifies the realm name which is to be reported to the
- client for the basic proxy authentication scheme (part of
- the text the user will see when prompted their username and
- password). There is no default.
- auth_param basic realm Squid proxy-caching web server
-
- "credentialsttl" timetolive
- Specifies how long squid assumes an externally validated
- username:password pair is valid for - in other words how
- often the helper program is called for that user. Set this
- low to force revalidation with short lived passwords. Note
- setting this high does not impact your susceptibility
- to replay attacks unless you are using an one-time password
- system (such as SecureID). If you are using such a system,
- you will be vulnerable to replay attacks unless you also
- use the max_user_ip ACL in an http_access rule.
-
- "casesensitive" on|off
- Specifies if usernames are case sensitive. Most user databases are
- case insensitive allowing the same username to be spelled using both
- lower and upper case letters, but some are case sensitive. This
- makes a big difference for user_max_ip ACL processing and similar.
- auth_param basic casesensitive off
-
- === Parameters for the digest scheme follow ===
-
- "program" cmdline
- Specify the command for the external authenticator. Such
- a program reads a line containing "username":"realm" and
- replies with the appropriate H(A1) value hex encoded or
- ERR if the user (or his H(A1) hash) does not exists.
- See rfc 2616 for the definition of H(A1).
- "ERR" responses may optionally be followed by a error description
- available as %m in the returned error page.
-
- By default, the digest authentication 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
-
- auth_param digest program @DEFAULT_PREFIX@/bin/digest_auth_pw @DEFAULT_PREFIX@/etc/digpass
-
-
- "children" numberofchildren
- The number of authenticator processes to spawn (no default).
- If you start too few Squid will have to wait for them to
- process a backlog of H(A1) calculations, slowing it down.
- When the H(A1) calculations are done via a (slow) network
- you are likely to need lots of authenticator processes.
- auth_param digest children 5
-
- "realm" realmstring
- Specifies the realm name which is to be reported to the
- client for the digest proxy authentication scheme (part of
- the text the user will see when prompted their username and
- password). There is no default.
- auth_param digest realm Squid proxy-caching web server
-
- "nonce_garbage_interval" timeinterval
- Specifies the interval that nonces that have been issued
- to client_agent's are checked for validity.
-
- "nonce_max_duration" timeinterval
- Specifies the maximum length of time a given nonce will be
- valid for.
+ Squid will write the User-Agent field from HTTP requests
+ to the filename specified here. By default useragent_log
+ is disabled.
+DOC_END
- "nonce_max_count" number
- Specifies the maximum number of times a given nonce can be
- used.
+NAME: referer_log referrer_log
+TYPE: string
+LOC: Config.Log.referer
+DEFAULT: none
+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
- "nonce_strictness" on|off
- Determines if squid requires strict increment-by-1 behavior
- for nonce counts, or just incrementing (off - for use when
- useragents generate nonce counts that occasionally miss 1
- (ie, 1,2,4,6)). Default off.
+NAME: pid_filename
+TYPE: string
+DEFAULT: @DEFAULT_PID_FILE@
+LOC: Config.pidFilename
+DOC_START
+ A filename to write the process-id to. To disable, enter "none".
+DOC_END
- "check_nonce_count" on|off
- This directive if set to off can disable the nonce count check
- completely to work around buggy digest qop implementations in
- certain mainstream browser versions. Default on to check the
- nonce count to protect from authentication replay attacks.
+NAME: debug_options
+TYPE: eol
+DEFAULT: ALL,1
+LOC: Config.debugOptions
+DOC_START
+ Logging options are set as section,level where each source file
+ is assigned a unique section. Lower levels result in less
+ output, Full debugging (level 9) can result in a very large
+ log file, so be careful. The magic word "ALL" sets debugging
+ levels for all sections. We recommend normally running with
+ "ALL,1".
+DOC_END
- "post_workaround" on|off
- This is a workaround to certain buggy browsers who sends
- an incorrect request digest in POST requests when reusing
- the same nonce as acquired earlier on a GET request.
+NAME: log_fqdn
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.log_fqdn
+DOC_START
+ Turn this on if you wish to log fully qualified domain names
+ in the access.log. To do this Squid does a DNS lookup of all
+ IP's connecting to it. This can (in some situations) increase
+ latency, which makes your cache seem slower for interactive
+ browsing.
+DOC_END
- === NTLM scheme options follow ===
+NAME: client_netmask
+TYPE: address
+LOC: Config.Addrs.client_netmask
+DEFAULT: 255.255.255.255
+DOC_START
+ A netmask for client addresses in logfiles and cachemgr output.
+ Change this to protect the privacy of your cache clients.
+ A netmask of 255.255.255.0 will log all IP's in that range with
+ the last digit set to '0'.
+DOC_END
- "program" cmdline
- Specify the command for the external NTLM authenticator.
- Such a program reads exchanged NTLMSSP packets with
- the browser via Squid until authentication is completed.
- If you use an NTLM authenticator, make sure you have 1 acl
- of type proxy_auth. By default, the NTLM authenticator_program
- is not used.
+NAME: forward_log
+IFDEF: WIP_FWD_LOG
+TYPE: string
+DEFAULT: none
+LOC: Config.Log.forward
+DOC_START
+ Logs the server-side requests.
- auth_param ntlm program @DEFAULT_PREFIX@/bin/ntlm_auth
+ This is currently work in progress.
+DOC_END
- "children" numberofchildren
- The number of authenticator processes to spawn (no default).
- If you start too few Squid will have to wait for them to
- process a backlog of credential verifications, slowing it
- down. When credential verifications are done via a (slow)
- network you are likely to need lots of authenticator
- processes.
+NAME: strip_query_terms
+TYPE: onoff
+LOC: Config.onoff.strip_query_terms
+DEFAULT: on
+DOC_START
+ By default, Squid strips query terms from requested URLs before
+ logging. This protects your user's privacy.
+DOC_END
- auth_param ntlm children 5
+NAME: buffered_logs
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.buffered_logs
+DOC_START
+ cache.log log file is written with stdio functions, and as such
+ it can be buffered or unbuffered. By default it will be unbuffered.
+ Buffering it can speed up the writing slightly (though you are
+ unlikely to need to worry unless you run with tons of debugging
+ enabled in which case performance will suffer badly anyway..).
+DOC_END
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
+NAME: netdb_filename
+TYPE: string
+DEFAULT: @DEFAULT_NETDB_FILE@
+LOC: Config.netdbFilename
+IFDEF: USE_ICMP
+DOC_START
+ A filename where Squid stores it's netdb state between restarts.
+ To disable, enter "none".
+DOC_END
- auth_param ntlm keep_alive on
+COMMENT_START
+ OPTIONS FOR FTP GATEWAYING
+ -----------------------------------------------------------------------------
+COMMENT_END
- === Options for configuring the NEGOTIATE auth-scheme follow ===
+NAME: ftp_user
+TYPE: string
+DEFAULT: Squid@
+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
+ reasonable for your domain, like wwwuser@somewhere.net
- "program" cmdline
- Specify the command for the external Negotiate authenticator.
- This protocol is used in Microsoft Active-Directory enabled setups with
- the Microsoft Internet Explorer or Mozilla Firefox browsers.
- Its main purpose is to exchange credentials with the Squid proxy
- using the Kerberos mechanisms.
- If you use a Negotiate authenticator, make sure you have at least one acl
- of type proxy_auth active. By default, the negotiate authenticator_program
- is not used.
- The only supported program for this role is the ntlm_auth
- program distributed as part of Samba, version 4 or later.
+ The reason why this is domainless by default is the
+ request can be made on the behalf of a user in any domain,
+ depending on how the cache is used.
+ Some ftp server also validate the email address is valid
+ (for example perl.com).
+DOC_END
- auth_param negotiate program @DEFAULT_PREFIX@/bin/ntlm_auth --helper-protocol=gss-spnego
+NAME: ftp_list_width
+TYPE: size_t
+DEFAULT: 32
+LOC: Config.Ftp.list_width
+DOC_START
+ Sets the width of ftp listings. This should be set to fit in
+ the width of a standard browser. Setting this too small
+ can cut off long filenames when browsing ftp sites.
+DOC_END
- "children" numberofchildren
- The number of authenticator processes to spawn (no default).
- If you start too few Squid will have to wait for them to
- process a backlog of credential verifications, slowing it
- down. When crendential verifications are done via a (slow)
- network you are likely to need lots of authenticator
- processes.
- auth_param negotiate children 5
-
- "keep_alive" on|off
- If you experience problems with PUT/POST requests when using the
- Negotiate authentication scheme then you can try setting this to
- off. This will cause Squid to forcibly close the connection on
- the initial requests where the browser asks which schemes are
- supported by the proxy.
+NAME: ftp_passive
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.passive
+DOC_START
+ If your firewall does not allow Squid to use passive
+ connections, turn off this option.
+DOC_END
- auth_param negotiate keep_alive on
+NAME: ftp_sanitycheck
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.sanitycheck
+DOC_START
+ For security and data integrity reasons Squid by default performs
+ sanity checks of the addresses of FTP data connections ensure the
+ data connection is to the requested server. If you need to allow
+ FTP connections to servers using another IP address for the data
+ connection turn this off.
+DOC_END
-NOCOMMENT_START
-#Recommended minimum configuration per scheme:
-#auth_param negotiate program <uncomment and complete this line to activate>
-#auth_param negotiate children 5
-#auth_param negotiate keep_alive on
-#auth_param ntlm program <uncomment and complete this line to activate>
-#auth_param ntlm children 5
-#auth_param ntlm keep_alive on
-#auth_param digest program <uncomment and complete this line>
-#auth_param digest children 5
-#auth_param digest realm Squid proxy-caching web server
-#auth_param digest nonce_garbage_interval 5 minutes
-#auth_param digest nonce_max_duration 30 minutes
-#auth_param digest nonce_max_count 50
-#auth_param basic program <uncomment and complete this line>
-#auth_param basic children 5
-#auth_param basic realm Squid proxy-caching web server
-#auth_param basic credentialsttl 2 hours
-NOCOMMENT_END
+NAME: ftp_telnet_protocol
+TYPE: onoff
+DEFAULT: on
+LOC: Config.Ftp.telnet
+DOC_START
+ The FTP protocol is officially defined to use the telnet protocol
+ as transport channel for the control connection. However, many
+ implementations are broken and does not respect this aspect of
+ the FTP protocol.
+
+ If you have trouble accessing files with ASCII code 255 in the
+ path or similar problems involving this ASCII code you can
+ try setting this directive to off. If that helps, report to the
+ operator of the FTP server in question that their FTP server
+ is broken and does not follow the FTP standard.
DOC_END
-NAME: authenticate_cache_garbage_interval
-TYPE: time_t
-DEFAULT: 1 hour
-LOC: Config.authenticateGCInterval
+COMMENT_START
+ OPTIONS FOR EXTERNAL SUPPORT PROGRAMS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: diskd_program
+TYPE: string
+DEFAULT: @DEFAULT_DISKD@
+LOC: Config.Program.diskd
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.
+ Specify the location of the diskd executable.
+ Note this is only useful if you have compiled in
+ diskd as one of the store io modules.
DOC_END
-NAME: authenticate_ttl
-TYPE: time_t
-DEFAULT: 1 hour
-LOC: Config.authenticateTTL
+NAME: unlinkd_program
+IFDEF: USE_UNLINKD
+TYPE: string
+DEFAULT: @DEFAULT_UNLINKD@
+LOC: Config.Program.unlinkd
DOC_START
- The time a user & their credentials stay in the logged in
- user cache since their last request. When the garbage
- interval passes, all user credentials that have passed their
- TTL are removed from memory.
+ Specify the location of the executable for file deletion process.
DOC_END
-NAME: authenticate_ip_ttl
-TYPE: time_t
-LOC: Config.authenticateIpTTL
-DEFAULT: 0 seconds
+NAME: pinger_program
+TYPE: string
+DEFAULT: @DEFAULT_PINGER@
+LOC: Config.pinger.program
+IFDEF: USE_ICMP
DOC_START
- If you use proxy authentication and the 'max_user_ip' ACL,
- this directive controls how long Squid remembers the IP
- addresses associated with each user. Use a small value
- (e.g., 60 seconds) if your users might change addresses
- quickly, as is the case with dialups. You might be safe
- using a larger value (e.g., 2 hours) in a corporate LAN
- environment with relatively static address assignments.
+ Specify the location of the executable for the pinger process.
DOC_END
-NAME: external_acl_type
-TYPE: externalAclHelper
-LOC: Config.externalAclHelperList
-DEFAULT: none
+NAME: pinger_enable
+TYPE: onoff
+DEFAULT: on
+LOC: Config.pinger.enable
+IFDEF: USE_ICMP
DOC_START
- This option defines external acl classes using a helper program
- to look up the status
+ Control whether the pinger is active at run-time.
+ Enables turning ICMP pinger on and off with a simple squid -k reconfigure.
+DOC_END
- external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
- Options:
+COMMENT_START
+ OPTIONS FOR URL REWRITING
+ -----------------------------------------------------------------------------
+COMMENT_END
- ttl=n TTL in seconds for cached results (defaults to 3600
- for 1 hour)
- negative_ttl=n
- TTL for cached negative lookups (default same
- as ttl)
- children=n Number of acl helper processes spawn to service
- external acl lookups of this type.
- concurrency=n concurrency level per process. Use 0 for old style
- helpers who can only process a single request at a
- time.
- cache=n result cache size, 0 is unbounded (default)
- grace=n Percentage remaining of TTL where a refresh of a
- cached entry should be initiated without needing to
- wait for a new reply. (default 0 for no grace period)
- protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers
+NAME: url_rewrite_program redirect_program
+TYPE: wordlist
+LOC: Config.Program.redirect
+DEFAULT: none
+DOC_START
+ Specify the location of the executable for the URL rewriter.
+ Since they can perform almost any function there isn't one included.
- FORMAT specifications
+ For each requested URL rewriter will receive on line with the format
- %LOGIN Authenticated user login name
- %EXT_USER Username from external acl
- %IDENT Ident user name
- %SRC Client IP
- %SRCPORT Client source port
- %URI Requested URI
- %DST Requested host
- %PROTO Requested protocol
- %PORT Requested port
- %PATH Requested URL path
- %METHOD Request method
- %MYADDR Squid interface address
- %MYPORT Squid http_port number
- %USER_CERT SSL User certificate in PEM format
- %USER_CERTCHAIN SSL User certificate chain in PEM format
- %USER_CERT_xx SSL User certificate subject attribute xx
- %USER_CA_xx SSL User certificate issuer attribute xx
- %{Header} HTTP request header
- %{Hdr:member} HTTP request header list member
- %{Hdr:;member}
- HTTP request header list member using ; as
- list separator. ; can be any non-alphanumeric
- character.
+ URL <SP> client_ip "/" fqdn <SP> user <SP> method [<SP> kvpairs]<NL>
- 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 the future, the rewriter interface will be extended with
+ key=value pairs ("kvpairs" shown above). Rewriter programs
+ should be prepared to receive and possibly ignore additional
+ whitespace-separated tokens on each input line.
- 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.
+ 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).
- General result syntax:
+ 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).
- OK/ERR keyword=value ...
+ By default, a URL rewriter is not used.
+DOC_END
- Defined keywords:
+NAME: url_rewrite_children redirect_children
+TYPE: int
+DEFAULT: 5
+LOC: Config.redirectChildren
+DOC_START
+ The number of redirector processes to spawn. If you start
+ too few Squid will have to wait for them to process a backlog of
+ URLs, slowing it down. If you start too many they will use RAM
+ and other system resources.
+DOC_END
- user= The users name (login)
- password= The users password (for login= cache_peer option)
- message= Message describing the reason. Available as %o
- in error pages
- tag= Apply a tag to a request (for both ERR and OK results)
- Only sets a tag, does not alter existing tags.
- log= String to be logged in access.log. Available as
- %ea in logformat specifications
+NAME: url_rewrite_concurrency redirect_concurrency
+TYPE: int
+DEFAULT: 0
+LOC: Config.redirectConcurrency
+DOC_START
+ The number of requests each redirector helper can handle in
+ parallel. Defaults to 0 which indicates the redirector
+ is a old-style single threaded redirector.
+DOC_END
+
+NAME: url_rewrite_host_header redirect_rewrites_host_header
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.redir_rewrites_host
+DOC_START
+ By default Squid rewrites any Host: header in redirected
+ requests. If you are running an accelerator this may
+ not be a wanted effect of a redirector.
+
+ WARNING: Entries are cached on the result of the URL rewriting
+ process, so be careful if you have domain-virtual hosts.
+DOC_END
- Keyword values need to be URL escaped if they may contain
- contain whitespace or quotes.
+NAME: url_rewrite_access redirector_access
+TYPE: acl_access
+DEFAULT: none
+LOC: Config.accessList.redirector
+DOC_START
+ If defined, this access list specifies which requests are
+ sent to the redirector processes. By default all requests
+ are sent.
+DOC_END
- In Squid-2.5 compatibility mode quoting using " and \ is used
- instead of URL escaping.
+NAME: url_rewrite_bypass redirector_bypass
+TYPE: onoff
+LOC: Config.onoff.redirector_bypass
+DEFAULT: off
+DOC_START
+ When this is 'on', a request will not go through the
+ redirector if all redirectors are busy. If this is 'off'
+ and the redirector queue grows too large, Squid will exit
+ with a FATAL error and ask you to increase the number of
+ redirectors. You should only enable this if the redirectors
+ are not critical to your caching system. If you use
+ redirectors for access control, and you enable this option,
+ users may have access to pages they should not
+ be allowed to request.
DOC_END
COMMENT_START
-----------------------------------------------------------------------------
COMMENT_END
-NAME: request_header_max_size
-COMMENT: (KB)
-TYPE: b_size_t
-DEFAULT: 20 KB
-LOC: Config.maxRequestHeaderSize
+NAME: cache no_cache
+TYPE: acl_access
+DEFAULT: none
+LOC: Config.accessList.noCache
DOC_START
- This specifies the maximum size for HTTP headers in a request.
- Request headers are usually relatively small (about 512 bytes).
- Placing a limit on the request header size will catch certain
- bugs (for example with persistent connections) and possibly
- buffer-overflow or denial-of-service attacks.
-DOC_END
+ A list of ACL elements which, if matched, cause the request to
+ not be satisfied from the cache and the reply to not be cached.
+ In other words, use this to force certain objects to never be cached.
-NAME: request_body_max_size
-COMMENT: (KB)
-TYPE: b_size_t
-DEFAULT: 0 KB
-LOC: Config.maxRequestBodySize
-DOC_START
- This specifies the maximum size for an HTTP request body.
- In other words, the maximum size of a PUT/POST request.
- A user who attempts to send a request with a body larger
- than this limit receives an "Invalid Request" error message.
- If you set this parameter to a zero (the default), there will
- be no limit imposed.
+ You must use the word 'DENY' to indicate the ACL names which should
+ NOT be cached.
+
+ Default is to allow all to be cached
+NOCOMMENT_START
+#We recommend you to use the following two lines.
+acl QUERY urlpath_regex cgi-bin \?
+cache deny QUERY
+NOCOMMENT_END
DOC_END
NAME: refresh_pattern
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
NAME: quick_abort_min
COMMENT: (KB)
-TYPE: kb_size_t
+TYPE: kb_int64_t
DEFAULT: 16 KB
LOC: Config.quickAbort.min
DOC_NONE
NAME: quick_abort_max
COMMENT: (KB)
-TYPE: kb_size_t
+TYPE: kb_int64_t
DEFAULT: 16 KB
LOC: Config.quickAbort.max
DOC_NONE
NAME: read_ahead_gap
COMMENT: buffer-size
-TYPE: kb_size_t
+TYPE: b_int64_t
LOC: Config.readAheadGap
DEFAULT: 16 KB
DOC_START
negative caching of DNS lookups.
DOC_END
-
NAME: positive_dns_ttl
COMMENT: time-units
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
COMMENT: (bytes)
-TYPE: b_size_t
+TYPE: b_int64_t
LOC: Config.rangeOffsetLimit
DEFAULT: 0 KB
DOC_START
This is to stop a far ahead range request (lets say start at 17MB)
from making Squid fetch the whole object up to that point before
sending anything to the client.
-
- A value of -1 causes Squid to always fetch the object from the
- beginning so it may cache the result. (2.0 style)
-
- A value of 0 causes Squid to never fetch more than the
- client requested. (default)
-DOC_END
-
-
-COMMENT_START
- TIMEOUTS
- -----------------------------------------------------------------------------
-COMMENT_END
-
-NAME: forward_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.forward
-DEFAULT: 4 minutes
-DOC_START
- This parameter specifies how long Squid should at most attempt in
- finding a forwarding path for the request before giving up.
-DOC_END
-
-NAME: connect_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.connect
-DEFAULT: 1 minute
-DOC_START
- This parameter specifies how long to wait for the TCP connect to
- the requested server or peer to complete before Squid should
- attempt to find another path where to forward the request.
-DOC_END
-
-NAME: peer_connect_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.peer_connect
-DEFAULT: 30 seconds
-DOC_START
- This parameter specifies how long to wait for a pending TCP
- connection to a peer cache. The default is 30 seconds. You
- may also set different timeout values for individual neighbors
- with the 'connect-timeout' option on a 'cache_peer' line.
-DOC_END
-
-NAME: read_timeout
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.read
-DEFAULT: 15 minutes
-DOC_START
- The read_timeout is applied on server-side connections. After
- each successful read(), the timeout will be extended by this
- amount. If no data is read again after this amount of time,
- the request is aborted and logged with ERR_READ_TIMEOUT. The
- default is 15 minutes.
-DOC_END
-
-
-NAME: request_timeout
-TYPE: time_t
-LOC: Config.Timeout.request
-DEFAULT: 5 minutes
-DOC_START
- How long to wait for an HTTP request after initial
- connection establishment.
-DOC_END
-
-
-NAME: persistent_request_timeout
-TYPE: time_t
-LOC: Config.Timeout.persistent_request
-DEFAULT: 1 minute
-DOC_START
- How long to wait for the next HTTP request on a persistent
- connection after the previous request completes.
-DOC_END
-
-
-NAME: client_lifetime
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.Timeout.lifetime
-DEFAULT: 1 day
-DOC_START
- The maximum amount of time a client (browser) is allowed to
- remain connected to the cache process. This protects the Cache
- from having a lot of sockets (and hence file descriptors) tied up
- in a CLOSE_WAIT state from remote clients that go away without
- properly shutting down (either because of a network failure or
- because of a poor client implementation). The default is one
- day, 1440 minutes.
-
- NOTE: The default value is intended to be much larger than any
- client would ever need to be connected to your cache. You
- should probably change client_lifetime only as a last resort.
- If you seem to have many client connections tying up
- filedescriptors, we recommend first tuning the read_timeout,
- request_timeout, persistent_request_timeout and quick_abort values.
-DOC_END
-
-NAME: half_closed_clients
-TYPE: onoff
-LOC: Config.onoff.half_closed_clients
-DEFAULT: on
-DOC_START
- Some clients may shutdown the sending side of their TCP
- connections, while leaving their receiving sides open. Sometimes,
- Squid can not tell the difference between a half-closed and a
- fully-closed TCP connection. By default, half-closed client
- connections are kept open until a read(2) or write(2) on the
- socket returns an error. Change this option to 'off' and Squid
- will immediately close client connections when read(2) returns
- "no more data to read."
+
+ A value of -1 causes Squid to always fetch the object from the
+ beginning so it may cache the result. (2.0 style)
+
+ A value of 0 causes Squid to never fetch more than the
+ client requested. (default)
DOC_END
-NAME: pconn_timeout
+NAME: minimum_expiry_time
+COMMENT: (seconds)
TYPE: time_t
-LOC: Config.Timeout.pconn
-DEFAULT: 120 seconds
+LOC: Config.minimum_expiry_time
+DEFAULT: 60 seconds
DOC_START
- Timeout for idle persistent connections to servers and other
- proxies.
+ The minimum caching time according to (Expires - Date)
+ Headers Squid honors if the object can't be revalidated
+ defaults to 60 seconds. In reverse proxy enorinments it
+ might be desirable to honor shorter object lifetimes. It
+ is most likely better to make your server return a
+ meaningful Last-Modified header however. In ESI environments
+ where page fragments often have short lifetimes, this will
+ often be best set to 0.
DOC_END
-NAME: ident_timeout
-TYPE: time_t
-IFDEF: USE_IDENT
-LOC: Config.Timeout.ident
-DEFAULT: 10 seconds
+NAME: store_avg_object_size
+COMMENT: (kbytes)
+TYPE: kb_int64_t
+DEFAULT: 13 KB
+LOC: Config.Store.avgObjectSize
DOC_START
- Maximum time to wait for IDENT lookups to complete.
-
- If this is too high, and you enabled IDENT lookups from untrusted
- users, you might be susceptible to denial-of-service by having
- many ident requests going at once.
+ Average object size, used to estimate number of objects your
+ cache can hold. The default is 13 KB.
DOC_END
-
-NAME: shutdown_lifetime
-COMMENT: time-units
-TYPE: time_t
-LOC: Config.shutdownLifetime
-DEFAULT: 30 seconds
+NAME: store_objects_per_bucket
+TYPE: int
+DEFAULT: 20
+LOC: Config.Store.objectsPerBucket
DOC_START
- When SIGTERM or SIGHUP is received, the cache is put into
- "shutdown pending" mode until all active sockets are closed.
- This value is the lifetime to set for all open descriptors
- during shutdown mode. Any active clients after this many
- seconds will receive a 'timeout' message.
+ Target number of objects per bucket in the store hash table.
+ Lowering this value increases the total number of buckets and
+ also the storage maintenance rate. The default is 20.
DOC_END
COMMENT_START
- ACCESS CONTROLS
+ HTTP OPTIONS
-----------------------------------------------------------------------------
COMMENT_END
-NAME: acl
-TYPE: acl
-LOC: Config.aclList
-DEFAULT: none
+NAME: request_header_max_size
+COMMENT: (KB)
+TYPE: b_size_t
+DEFAULT: 20 KB
+LOC: Config.maxRequestHeaderSize
DOC_START
- Defining an Access List
-
- acl aclname acltype string1 ...
- acl aclname acltype "file" ...
-
- when using "file", the file should contain one item per line
-
- acltype is one of the types described below
-
- By default, regular expressions are CASE-SENSITIVE. To make
- them case-insensitive, use the -i option.
-
- acl aclname src ip-address/netmask ... (clients IP address)
- acl aclname src addr1-addr2/netmask ... (range of addresses)
- acl aclname dst ip-address/netmask ... (URL host's IP address)
- acl aclname myip ip-address/netmask ... (local socket IP address)
-
- acl aclname arp mac-address ... (xx:xx:xx:xx:xx:xx notation)
- # The arp ACL requires the special configure option --enable-arp-acl.
- # Furthermore, the ARP ACL code is not portable to all operating systems.
- # It works on Linux, Solaris, Windows, FreeBSD, and some other *BSD variants.
- #
- # NOTE: Squid can only determine the MAC address for clients that are on
- # the same subnet. If the client is on a different subnet, then Squid cannot
- # find out its MAC address.
-
- acl aclname srcdomain .foo.com ... # reverse lookup, client IP
- acl aclname dstdomain .foo.com ... # Destination server from URL
- acl aclname srcdom_regex [-i] xxx ... # regex matching client name
- acl aclname dstdom_regex [-i] xxx ... # regex matching server
- # For dstdomain and dstdom_regex a reverse lookup is tried if a IP
- # based URL is used and no match is found. The name "none" is used
- # if the reverse lookup fails.
-
- acl aclname http_status 200 301 500- 400-403 ... # status code in reply
-
- acl aclname time [day-abbrevs] [h1:m1-h2:m2]
- day-abbrevs:
- S - Sunday
- M - Monday
- T - Tuesday
- W - Wednesday
- H - Thursday
- F - Friday
- A - Saturday
- h1:m1 must be less than h2:m2
- acl aclname url_regex [-i] ^http:// ... # regex matching on whole URL
- acl aclname urlpath_regex [-i] \.gif$ ... # regex matching on URL path
- acl aclname port 80 70 21 ...
- acl aclname port 0-1024 ... # ranges allowed
- acl aclname myport 3128 ... # (local socket TCP port)
- acl aclname proto HTTP FTP ...
- acl aclname method GET POST ...
- acl aclname browser [-i] regexp ...
- # pattern match on User-Agent header (see also req_header below)
- acl aclname referer_regex [-i] regexp ...
- # pattern match on Referer header
- # Referer is highly unreliable, so use with care
- acl aclname ident username ...
- acl aclname ident_regex [-i] pattern ...
- # string match on ident output.
- # use REQUIRED to accept any non-null ident.
- acl aclname src_as number ...
- acl aclname dst_as number ...
- # Except for access control, AS numbers can be used for
- # routing of requests to specific caches. Here's an
- # example for routing all requests for AS#1241 and only
- # those to mycache.mydomain.net:
- # acl asexample dst_as 1241
- # cache_peer_access mycache.mydomain.net allow asexample
- # cache_peer_access mycache_mydomain.net deny all
-
- acl aclname proxy_auth [-i] username ...
- acl aclname proxy_auth_regex [-i] pattern ...
- # list of valid usernames
- # use REQUIRED to accept any valid username.
- #
- # NOTE: when a Proxy-Authentication header is sent but it is not
- # needed during ACL checking the username is NOT logged
- # in access.log.
- #
- # NOTE: proxy_auth requires a EXTERNAL authentication program
- # to check username/password combinations (see
- # auth_param directive).
- #
- # NOTE: proxy_auth can't be used in a transparent proxy as
- # the browser needs to be configured for using a proxy in order
- # to respond to proxy authentication.
+ This specifies the maximum size for HTTP headers in a request.
+ Request headers are usually relatively small (about 512 bytes).
+ Placing a limit on the request header size will catch certain
+ bugs (for example with persistent connections) and possibly
+ buffer-overflow or denial-of-service attacks.
+DOC_END
- acl aclname snmp_community string ...
- # A community string to limit access to your SNMP Agent
- # Example:
- #
- # acl snmppublic snmp_community public
+NAME: reply_header_max_size
+COMMENT: (KB)
+TYPE: b_size_t
+DEFAULT: 20 KB
+LOC: Config.maxReplyHeaderSize
+DOC_START
+ This specifies the maximum size for HTTP headers in a reply.
+ Reply headers are usually relatively small (about 512 bytes).
+ Placing a limit on the reply header size will catch certain
+ bugs (for example with persistent connections) and possibly
+ buffer-overflow or denial-of-service attacks.
+DOC_END
- acl aclname maxconn number
- # This will be matched when the client's IP address has
- # more than <number> HTTP connections established.
+NAME: request_body_max_size
+COMMENT: (bytes)
+TYPE: b_int64_t
+DEFAULT: 0 KB
+LOC: Config.maxRequestBodySize
+DOC_START
+ This specifies the maximum size for an HTTP request body.
+ In other words, the maximum size of a PUT/POST request.
+ A user who attempts to send a request with a body larger
+ than this limit receives an "Invalid Request" error message.
+ If you set this parameter to a zero (the default), there will
+ be no limit imposed.
+DOC_END
- acl aclname max_user_ip [-s] number
- # This will be matched when the user attempts to log in from more
- # than <number> different ip addresses. The authenticate_ip_ttl
- # parameter controls the timeout on the ip entries.
- # If -s is specified the limit is strict, denying browsing
- # from any further IP addresses until the ttl has expired. Without
- # -s Squid will just annoy the user by "randomly" denying requests.
- # (the counter is reset each time the limit is reached and a
- # request is denied)
- # NOTE: in acceleration mode or where there is mesh of child proxies,
- # clients may appear to come from multiple addresses if they are
- # going through proxy farms, so a limit of 1 may cause user problems.
+NAME: broken_posts
+TYPE: acl_access
+DEFAULT: none
+LOC: Config.accessList.brokenPosts
+DOC_START
+ A list of ACL elements which, if matched, causes Squid to send
+ an extra CRLF pair after the body of a PUT/POST request.
- acl aclname rep_mime_type mime-type1 ...
- # regex match against the mime type of the reply received by
- # squid. Can be used to detect file download or some
- # types HTTP tunneling requests.
- # NOTE: This has no effect in http_access rules. It only has
- # effect in rules that affect the reply data stream such as
- # http_reply_access.
+ Some HTTP servers has broken implementations of PUT/POST,
+ and rely on an extra CRLF pair sent by some WWW clients.
- acl aclname rep_header header-name [-i] any\.regex\.here
- # regex match against any of the known reply headers. May be
- # thought of as a superset of "browser", "referer" and "mime-type"
- # ACLs.
+ Quote from RFC2616 section 4.1 on this matter:
- acl aclname req_mime_type mime-type1 ...
- # regex match agains the mime type of the request generated
- # by the client. Can be used to detect file upload or some
- # types HTTP tunneling requests.
- # NOTE: This does NOT match the reply. You cannot use this
- # to match the returned file type.
+ Note: certain buggy HTTP/1.0 client implementations generate an
+ extra CRLF's after a POST request. To restate what is explicitly
+ forbidden by the BNF, an HTTP/1.1 client must not preface or follow
+ a request with an extra CRLF.
- acl aclname req_header header-name [-i] any\.regex\.here
- # regex match against any of the known request headers. May be
- # thought of as a superset of "browser", "referer" and "mime-type"
- # ACLs.
+Example:
+ acl buggy_server url_regex ^http://....
+ broken_posts allow buggy_server
+DOC_END
- acl acl_name external class_name [arguments...]
- # external ACL lookup via a helper class defined by the
- # external_acl_type directive.
+NAME: via
+IFDEF: HTTP_VIOLATIONS
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.via
+DOC_START
+ If set (default), Squid will include a Via header in requests and
+ replies as required by RFC2616.
+DOC_END
- acl aclname user_cert attribute values...
- # match against attributes in a user SSL certificate
- # attribute is one of DN/C/O/CN/L/ST
+NAME: ie_refresh
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.ie_refresh
+DEFAULT: off
+DOC_START
+ Microsoft Internet Explorer up until version 5.5 Service
+ Pack 1 has an issue with transparent proxies, wherein it
+ is impossible to force a refresh. Turning this on provides
+ a partial fix to the problem, by causing all IMS-REFRESH
+ requests from older IE versions to check the origin server
+ for fresh content. This reduces hit ratio by some amount
+ (~10% in my experience), but allows users to actually get
+ fresh content when they want it. Note because Squid
+ cannot tell if the user is using 5.5 or 5.5SP1, the behavior
+ of 5.5 is unchanged from old versions of Squid (i.e. a
+ forced refresh is impossible). Newer versions of IE will,
+ hopefully, continue to have the new behavior and will be
+ handled based on that assumption. This option defaults to
+ the old Squid behavior, which is better for hit ratios but
+ worse for clients using IE, if they need to be able to
+ force fresh content.
+DOC_END
- acl aclname ca_cert attribute values...
- # match against attributes a users issuing CA SSL certificate
- # attribute is one of DN/C/O/CN/L/ST
+NAME: vary_ignore_expire
+COMMENT: on|off
+TYPE: onoff
+LOC: Config.onoff.vary_ignore_expire
+DEFAULT: off
+DOC_START
+ Many HTTP servers supporting Vary gives such objects
+ immediate expiry time with no cache-control header
+ when requested by a HTTP/1.0 client. This option
+ enables Squid to ignore such expiry times until
+ HTTP/1.1 is fully implemented.
+ WARNING: This may eventually cause some varying
+ objects not intended for caching to get cached.
+DOC_END
- acl aclname ext_user username ...
- acl aclname ext_user_regex [-i] pattern ...
- # string match on username returned by external acl processing
- # use REQUIRED to accept any non-null user name.
+NAME: extension_methods
+TYPE: wordlist
+LOC: Config.ext_methods
+DEFAULT: none
+DOC_START
+ Squid only knows about standardized HTTP request methods.
+ You can add up to 20 additional "extension" methods here.
+DOC_END
-Examples:
-acl macaddress arp 09:00:2b:23:45:67
-acl myexample dst_as 1241
-acl password proxy_auth REQUIRED
-acl fileupload req_mime_type -i ^multipart/form-data$
-acl javascript rep_mime_type -i ^application/x-javascript$
+NAME: request_entities
+TYPE: onoff
+LOC: Config.onoff.request_entities
+DEFAULT: off
+DOC_START
+ Squid defaults to deny GET and HEAD requests with request entities,
+ as the meaning of such requests are undefined in the HTTP standard
+ even if not explicitly forbidden.
-NOCOMMENT_START
-#Recommended minimum configuration:
-acl all src 0.0.0.0/0.0.0.0
-acl manager proto cache_object
-acl localhost src 127.0.0.1/255.255.255.255
-acl to_localhost dst 127.0.0.0/8
-acl SSL_ports port 443
-acl Safe_ports port 80 # http
-acl Safe_ports port 21 # ftp
-acl Safe_ports port 443 # https
-acl Safe_ports port 70 # gopher
-acl Safe_ports port 210 # wais
-acl Safe_ports port 1025-65535 # unregistered ports
-acl Safe_ports port 280 # http-mgmt
-acl Safe_ports port 488 # gss-http
-acl Safe_ports port 591 # filemaker
-acl Safe_ports port 777 # multiling http
-acl CONNECT method CONNECT
-NOCOMMENT_END
+ Set this directive to on if you have clients which insists
+ on sending request entities in GET or HEAD requests. But be warned
+ that there is server software (both proxies and web servers) which
+ can fail to properly process this kind of request which may make you
+ vulnerable to cache pollution attacks if enabled.
DOC_END
-NAME: http_access
-TYPE: acl_access
-LOC: Config.accessList.http
+NAME: request_header_access
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_access[]
+LOC: Config.request_header_access
DEFAULT: none
-DEFAULT_IF_NONE: deny all
DOC_START
- Allowing or Denying access based on defined access lists
+ Usage: request_header_access header_name allow|deny [!]aclname ...
- Access to the HTTP port:
- http_access allow|deny [!]aclname ...
+ WARNING: Doing this VIOLATES the HTTP standard. Enabling
+ this feature could make you liable for problems which it
+ causes.
- NOTE on default values:
+ This option replaces the old 'anonymize_headers' and the
+ older 'http_anonymizer' option with something that is much
+ more configurable. This new method creates a list of ACLs
+ for each header, allowing you very fine-tuned header
+ mangling.
- If there are no "access" lines present, the default is to deny
- the request.
+ This option only applies to request headers, i.e., from the
+ client to the server.
- If none of the "access" lines cause a match, the default is the
- opposite of the last line in the list. If the last line was
- deny, the default is allow. Conversely, if the last line
- is allow, the default will be deny. For these reasons, it is a
- good idea to have an "deny all" or "allow all" entry at the end
- of your access lists to avoid potential confusion.
+ You can only specify known headers for the header name.
+ Other headers are reclassified as 'Other'. You can also
+ refer to all the headers with 'All'.
-NOCOMMENT_START
-#Recommended minimum configuration:
-#
-# Only allow cachemgr access from localhost
-http_access allow manager localhost
-http_access deny manager
-# Deny requests to unknown ports
-http_access deny !Safe_ports
-# Deny CONNECT to other than SSL ports
-http_access deny CONNECT !SSL_ports
-#
-# We strongly recommend the following be uncommented to protect innocent
-# web applications running on the proxy server who think the only
-# one who can access services on "localhost" is a local user
-#http_access deny to_localhost
-#
-# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
+ For example, to achieve the same behavior as the old
+ 'http_anonymizer standard' option, you should use:
-# Example rule allowing access from your local networks. Adapt
-# to list your (internal) IP networks from where browsing should
-# be allowed
-#acl our_networks src 192.168.1.0/24 192.168.2.0/24
-#http_access allow our_networks
+ 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
-# And finally deny all other access to this proxy
-http_access deny all
-NOCOMMENT_END
+ 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 Proxy-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.
+
+ By default, all headers are allowed (no anonymizing is
+ performed).
DOC_END
-NAME: http_reply_access
-TYPE: acl_access
-LOC: Config.accessList.reply
+NAME: reply_header_access
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_access[]
+LOC: Config.reply_header_access
DEFAULT: none
-DEFAULT_IF_NONE: allow all
DOC_START
- Allow replies to client requests. This is complementary to http_access.
+ Usage: reply_header_access header_name allow|deny [!]aclname ...
- http_reply_access allow|deny [!] aclname ...
+ WARNING: Doing this VIOLATES the HTTP standard. Enabling
+ this feature could make you liable for problems which it
+ causes.
- NOTE: if there are no access lines present, the default is to allow
- all replies
+ This option only applies to reply headers, i.e., from the
+ server to the client.
- If none of the access lines cause a match the opposite of the
- last line will apply. Thus it is good practice to end the rules
- with an "allow all" or "deny all" entry.
+ This is the same as request_header_access, but in the other
+ direction.
-NOCOMMENT_START
-#Recommended minimum configuration:
-#
-# Insert your own rules here.
-#
-#
-# and finally allow by default
-http_reply_access allow all
-NOCOMMENT_END
-DOC_END
+ This option replaces the old 'anonymize_headers' and the
+ older 'http_anonymizer' option with something that is much
+ more configurable. This new method creates a list of ACLs
+ for each header, allowing you very fine-tuned header
+ mangling.
+ You can only specify known headers for the header name.
+ Other headers are reclassified as 'Other'. You can also
+ refer to all the headers with 'All'.
-NAME: icp_access
-TYPE: acl_access
-LOC: Config.accessList.icp
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-DOC_START
- Allowing or Denying access to the ICP port based on defined
- access lists
+ For example, to achieve the same behavior as the old
+ 'http_anonymizer standard' option, you should use:
- icp_access allow|deny [!]aclname ...
+ 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
+
+ Or, to reproduce the old 'http_anonymizer paranoid' feature
+ 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
+ reply_header_access Content-Length allow all
+ reply_header_access Content-Type allow all
+ reply_header_access Date allow all
+ reply_header_access Expires allow all
+ reply_header_access Host allow all
+ reply_header_access If-Modified-Since allow all
+ reply_header_access Last-Modified allow all
+ reply_header_access Location allow all
+ reply_header_access Pragma allow all
+ reply_header_access Accept allow all
+ reply_header_access Accept-Charset allow all
+ reply_header_access Accept-Encoding allow all
+ reply_header_access Accept-Language allow all
+ reply_header_access Content-Language allow all
+ reply_header_access Mime-Version allow all
+ reply_header_access Retry-After allow all
+ reply_header_access Title allow all
+ reply_header_access Connection allow all
+ reply_header_access Proxy-Connection allow all
+ reply_header_access All deny all
- See http_access for details
+ although the HTTP request headers won't be usefully controlled
+ by this directive -- see request_header_access for details.
-NOCOMMENT_START
-#Allow ICP queries from everyone
-icp_access allow all
-NOCOMMENT_END
+ By default, all headers are allowed (no anonymizing is
+ performed).
DOC_END
-
-NAME: htcp_access
-IFDEF: USE_HTCP
-TYPE: acl_access
-LOC: Config.accessList.htcp
+NAME: header_replace
+IFDEF: HTTP_VIOLATIONS
+TYPE: http_header_replace[]
+LOC: Config.request_header_access
DEFAULT: none
-DEFAULT_IF_NONE: deny all
DOC_START
- Allowing or Denying access to the HTCP port based on defined
- access lists
+ Usage: header_replace header_name message
+ Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
- htcp_access allow|deny [!]aclname ...
+ This option allows you to change the contents of headers
+ denied with header_access above, by replacing them with
+ some fixed string. This replaces the old fake_user_agent
+ option.
- See http_access for details
+ This only applies to request headers, not reply headers.
-#Allow HTCP queries from everyone
-htcp_access allow all
+ By default, headers are removed if denied.
DOC_END
-NAME: htcp_clr_access
-IFDEF: USE_HTCP
-TYPE: acl_access
-LOC: Config.accessList.htcp_clr
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
+NAME: relaxed_header_parser
+COMMENT: on|off|warn
+TYPE: tristate
+LOC: Config.onoff.relaxed_header_parser
+DEFAULT: on
DOC_START
- Allowing or Denying access to purge content using HTCP based
- on defined access lists
-
- htcp_clr_access allow|deny [!]aclname ...
+ In the default "on" setting Squid accepts certain forms
+ of non-compliant HTTP messages where it is unambiguous
+ what the sending application intended even if the message
+ is not correctly formatted. The messages is then normalized
+ to the correct form when forwarded by Squid.
- See http_access for details
+ If set to "warn" then a warning will be emitted in cache.log
+ each time such HTTP error is encountered.
-#Allow HTCP CLR requests from trusted peers
-acl htcp_clr_peer src 172.16.1.2
-htcp_clr_access allow htcp_clr_peer
+ If set to "off" then such HTTP errors will cause the request
+ or response to be rejected.
DOC_END
+COMMENT_START
+ TIMEOUTS
+ -----------------------------------------------------------------------------
+COMMENT_END
-NAME: miss_access
-TYPE: acl_access
-LOC: Config.accessList.miss
-DEFAULT: none
+NAME: forward_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.forward
+DEFAULT: 4 minutes
DOC_START
- Use to force your neighbors to use you as a sibling instead of
- a parent. For example:
-
- acl localclients src 172.16.0.0/16
- miss_access allow localclients
- miss_access deny !localclients
-
- This means only your local clients are allowed to fetch
- MISSES and all other clients can only fetch HITS.
-
- By default, allow all clients who passed the http_access rules
- to fetch MISSES from us.
-
-NOCOMMENT_START
-#Default setting:
-# miss_access allow all
-NOCOMMENT_END
+ This parameter specifies how long Squid should at most attempt in
+ finding a forwarding path for the request before giving up.
DOC_END
-
-NAME: cache_peer_access
-TYPE: peer_access
-DEFAULT: none
-LOC: none
+NAME: connect_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.connect
+DEFAULT: 1 minute
DOC_START
- Similar to 'cache_peer_domain' but provides more flexibility by
- using ACL elements.
-
- 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
- the Squid FAQ (http://www.squid-cache.org/FAQ/FAQ-10.html).
+ This parameter specifies how long to wait for the TCP connect to
+ the requested server or peer to complete before Squid should
+ attempt to find another path where to forward the request.
DOC_END
-NAME: ident_lookup_access
-TYPE: acl_access
-IFDEF: USE_IDENT
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-LOC: Config.accessList.identLookup
+NAME: peer_connect_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.peer_connect
+DEFAULT: 30 seconds
DOC_START
- A list of ACL elements which, if matched, cause an ident
- (RFC 931) lookup to be performed for this request. For
- example, you might choose to always perform ident lookups
- for your main multi-user Unix boxes, but not for your Macs
- and PCs. By default, ident lookups are not performed for
- any requests.
-
- To enable ident lookups for specific client addresses, you
- can follow this example:
-
- acl ident_aware_hosts src 198.168.1.0/255.255.255.0
- ident_lookup_access allow ident_aware_hosts
- ident_lookup_access deny all
-
- Only src type ACL checks are fully supported. A src_domain
- ACL might work at times, but it will not always provide
- the correct result.
+ This parameter specifies how long to wait for a pending TCP
+ connection to a peer cache. The default is 30 seconds. You
+ may also set different timeout values for individual neighbors
+ with the 'connect-timeout' option on a 'cache_peer' line.
DOC_END
-NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
-TYPE: acl_tos
-DEFAULT: none
-LOC: Config.accessList.outgoing_tos
+NAME: read_timeout
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.read
+DEFAULT: 15 minutes
DOC_START
- Allows you to select a TOS/Diffserv value to mark outgoing
- connections with, based on the username or source address
- making the request.
-
- tcp_outgoing_tos ds-field [!]aclname ...
-
- Example where normal_service_net uses the TOS value 0x00
- and normal_service_net uses 0x20
-
- acl normal_service_net src 10.0.0.0/255.255.255.0
- acl good_service_net src 10.0.1.0/255.255.255.0
- tcp_outgoing_tos 0x00 normal_service_net 0x00
- tcp_outgoing_tos 0x20 good_service_net
-
- TOS/DSCP values really only have local significance - so you should
- know what you're specifying. For more, see RFC 2474
-
- The TOS/DSCP byte must be exactly that - a byte, value 0 - 255, or
- "default" to use whatever default your host has.
-
- Processing proceeds in the order specified, and stops at first fully
- matching line.
+ The read_timeout is applied on server-side connections. After
+ each successful read(), the timeout will be extended by this
+ amount. If no data is read again after this amount of time,
+ the request is aborted and logged with ERR_READ_TIMEOUT. The
+ default is 15 minutes.
DOC_END
-NAME: tcp_outgoing_address
-TYPE: acl_address
-DEFAULT: none
-LOC: Config.accessList.outgoing_address
+NAME: request_timeout
+TYPE: time_t
+LOC: Config.Timeout.request
+DEFAULT: 5 minutes
DOC_START
- Allows you to map requests to different outgoing IP addresses
- based on the username or sourceaddress of the user making
- the request.
-
- tcp_outgoing_address ipaddr [[!]aclname] ...
+ How long to wait for an HTTP request after initial
+ connection establishment.
+DOC_END
- Example where requests from 10.0.0.0/24 will be forwarded
- with source address 10.1.0.1, 10.0.2.0/24 forwarded with
- source address 10.1.0.2 and the rest will be forwarded with
- source address 10.1.0.3.
+NAME: persistent_request_timeout
+TYPE: time_t
+LOC: Config.Timeout.persistent_request
+DEFAULT: 2 minutes
+DOC_START
+ How long to wait for the next HTTP request on a persistent
+ connection after the previous request completes.
+DOC_END
- acl normal_service_net src 10.0.0.0/255.255.255.0
- acl good_service_net src 10.0.1.0/255.255.255.0
- tcp_outgoing_address 10.0.0.1 normal_service_net
- tcp_outgoing_address 10.0.0.2 good_service_net
- tcp_outgoing_address 10.0.0.3
+NAME: client_lifetime
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.Timeout.lifetime
+DEFAULT: 1 day
+DOC_START
+ The maximum amount of time a client (browser) is allowed to
+ remain connected to the cache process. This protects the Cache
+ from having a lot of sockets (and hence file descriptors) tied up
+ in a CLOSE_WAIT state from remote clients that go away without
+ properly shutting down (either because of a network failure or
+ because of a poor client implementation). The default is one
+ day, 1440 minutes.
- Processing proceeds in the order specified, and stops at first fully
- matching line.
+ NOTE: The default value is intended to be much larger than any
+ client would ever need to be connected to your cache. You
+ should probably change client_lifetime only as a last resort.
+ If you seem to have many client connections tying up
+ filedescriptors, we recommend first tuning the read_timeout,
+ request_timeout, persistent_request_timeout and quick_abort values.
DOC_END
-NAME: reply_header_max_size
-COMMENT: (KB)
-TYPE: b_size_t
-DEFAULT: 20 KB
-LOC: Config.maxReplyHeaderSize
+NAME: half_closed_clients
+TYPE: onoff
+LOC: Config.onoff.half_closed_clients
+DEFAULT: on
DOC_START
- This specifies the maximum size for HTTP headers in a reply.
- Reply headers are usually relatively small (about 512 bytes).
- Placing a limit on the reply header size will catch certain
- bugs (for example with persistent connections) and possibly
- buffer-overflow or denial-of-service attacks.
+ Some clients may shutdown the sending side of their TCP
+ connections, while leaving their receiving sides open. Sometimes,
+ Squid can not tell the difference between a half-closed and a
+ fully-closed TCP connection. By default, half-closed client
+ connections are kept open until a read(2) or write(2) on the
+ socket returns an error. Change this option to 'off' and Squid
+ will immediately close client connections when read(2) returns
+ "no more data to read."
DOC_END
-NAME: reply_body_max_size
-COMMENT: size [acl acl...]
-TYPE: acl_b_size_t
-DEFAULT: none
-LOC: Config.ReplyBodySize
+NAME: pconn_timeout
+TYPE: time_t
+LOC: Config.Timeout.pconn
+DEFAULT: 1 minute
DOC_START
- This option specifies the maximum size of a reply body. It can be
- used to prevent users from downloading very large files, such as
- MP3's and movies. When the reply headers are received, the
- reply_body_max_size lines are processed, and the first line where
- all (if any) listed ACLs are true is used as the maximum body size
- for this reply.
-
- This size is checked twice. First when we get the reply headers,
- we check the content-length value. If the content length value exists
- and is larger than the allowed size, the request is denied and the
- user receives an error message that says "the request or reply
- is too large." If there is no content-length, and the reply
- size exceeds this limit, the client's connection is just closed
- and they will receive a partial reply.
-
- WARNING: downstream caches probably can not detect a partial reply
- if there is no content-length header, so they will cache
- partial responses and give them out as hits. You should NOT
- use this option if you have downstream caches.
+ Timeout for idle persistent connections to servers and other
+ proxies.
+DOC_END
- WARNING: A maximum size smaller than the size of squid's error messages
- will cause an infinite loop and crash squid. Ensure that the smallest
- non-zero value you use is greater that the maximum header size plus
- the size of your largest error page.
+NAME: ident_timeout
+TYPE: time_t
+IFDEF: USE_IDENT
+LOC: Config.Timeout.ident
+DEFAULT: 10 seconds
+DOC_START
+ Maximum time to wait for IDENT lookups to complete.
- If you set this parameter none (the default), there will be
- no limit imposed.
+ If this is too high, and you enabled IDENT lookups from untrusted
+ users, you might be susceptible to denial-of-service by having
+ many ident requests going at once.
DOC_END
-NAME: log_access
-TYPE: acl_access
-LOC: Config.accessList.log
-DEFAULT: none
-COMMENT: allow|deny acl acl...
+NAME: shutdown_lifetime
+COMMENT: time-units
+TYPE: time_t
+LOC: Config.shutdownLifetime
+DEFAULT: 30 seconds
DOC_START
- This options allows you to control which requests gets logged
- to access.log (see access_log directive). Requests denied for
- logging will also not be accounted for in performance counters.
+ When SIGTERM or SIGHUP is received, the cache is put into
+ "shutdown pending" mode until all active sockets are closed.
+ This value is the lifetime to set for all open descriptors
+ during shutdown mode. Any active clients after this many
+ seconds will receive a 'timeout' message.
DOC_END
COMMENT_START
mail if the cache dies. The default is "webmaster."
DOC_END
-
NAME: mail_from
TYPE: string
DEFAULT: none
src/globals.h before building squid.
DOC_END
-
NAME: mail_program
TYPE: eol
DEFAULT: mail
LOC: Config.EmailProgram
DOC_START
Email program used to send mail if the cache dies.
- The default is "mail". The specified program must complain
+ The default is "mail". The specified program must comply
with the standard Unix mail syntax:
- mail_program recipient < mailfile
+ mail-program recipient < mailfile
+
Optional command line options can be specified.
DOC_END
-
NAME: cache_effective_user
TYPE: string
-DEFAULT: nobody
+DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@
LOC: Config.effectiveUser
DOC_START
If you start Squid as root, it will change its effective/real
UID/GID to the user specified below. The default is to change
- to UID to nobody. If you define cache_effective_user, but not
- cache_effective_group, Squid sets the GID to the effective
- user's default group ID (taken from the password file) and
- supplementary group list from the from groups membership of
- cache_effective_user.
+ to UID of @DEFAULT_CACHE_EFFECTIVE_USER@.
+ see also; cache_effective_group
DOC_END
-
NAME: cache_effective_group
TYPE: string
DEFAULT: none
LOC: Config.effectiveGroup
DOC_START
+ Squid sets the GID to the effective user's default group ID
+ (taken from the password file) and supplementary group list
+ from the groups membership.
+
If you want Squid to run with a specific GID regardless of
the group memberships of the effective user then set this
to the group (or GID) you want Squid to run as. When set
- all other group privileges of the effective user is ignored
+ all other group privileges of the effective user are ignored
and only this GID is effective. If Squid is not started as
- root the user starting Squid must be member of the specified
+ root the user starting Squid MUST be member of the specified
group.
-DOC_END
+ This option is not recommended by the Squid Team.
+ Our preference is for administrators to configure a secure
+ user account for squid with UID/GID matching system policies.
+DOC_END
NAME: httpd_suppress_version_string
COMMENT: on|off
Suppress Squid version string info in HTTP headers and HTML error pages.
DOC_END
-
NAME: visible_hostname
TYPE: string
LOC: Config.visibleHostname
names with this setting.
DOC_END
-
NAME: unique_hostname
TYPE: string
LOC: Config.uniqueHostname
'unique_hostname' so forwarding loops can be detected.
DOC_END
-
NAME: hostname_aliases
TYPE: wordlist
LOC: Config.hostnameAliases
NOCOMMENT_END
DOC_END
-
NAME: announce_host
TYPE: string
DEFAULT: tracker.ircache.net
message.
DOC_END
+COMMENT_START
+ HTTPD-ACCELERATOR OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
NAME: httpd_accel_surrogate_id
-IFDEF: ESI
+IFDEF: USE_SQUID_ESI
TYPE: string
LOC: Config.Accel.surrogate_id
DEFAULT: unset-id
DOC_END
NAME: http_accel_surrogate_remote
-IFDEF: ESI
+IFDEF: USE_SQUID_ESI
COMMENT: on|off
TYPE: onoff
DEFAULT: off
DOC_END
NAME: esi_parser
-IFDEF: ESI
+IFDEF: USE_SQUID_ESI
COMMENT: libxml2|expat|custom
TYPE: string
LOC: ESIParser::Type
encodings.
DOC_END
-
COMMENT_START
- DELAY POOL PARAMETERS (all require DELAY_POOLS compilation option)
+ DELAY POOL PARAMETERS
-----------------------------------------------------------------------------
COMMENT_END
individual the "delay parameters" for the individual
buckets (class 2, 3).
- network the "delay parameters" for the network buckets
- (class 3).
+ network the "delay parameters" for the network buckets
+ (class 3).
+
+ user the delay parameters for the user buckets
+ (class 4).
+
+ tag the delay parameters for the tag buckets
+ (class 5).
+
+ A pair of delay parameters is written restore/maximum, where restore is
+ the number of bytes (not bits - modem and network speeds are usually
+ quoted in bits) per second placed into the bucket, and maximum is the
+ maximum number of bytes which can be in the bucket at any time.
+
+ For example, if delay pool number 1 is a class 2 delay pool as in the
+ above example, and is being used to strictly limit each host to 64kbps
+ (plus overheads), with no overall limit, the line is:
+
+delay_parameters 1 -1/-1 8000/8000
+
+ Note that the figure -1 is used to represent "unlimited".
+
+ And, if delay pool number 2 is a class 3 delay pool as in the above
+ example, and you want to limit it to a total of 256kbps (strict limit)
+ with each 8-bit network permitted 64kbps (strict limit) and each
+ individual host permitted 4800bps with a bucket maximum size of 64kb
+ to permit a decent web page to be downloaded at a decent speed
+ (if the network is not being limited due to overuse) but slow down
+ large downloads more significantly:
+
+delay_parameters 2 32000/32000 8000/8000 600/8000
+
+ There must be one delay_parameters line for each delay pool.
+
+ Finally, for a class 4 delay pool as in the example - each user will
+ be limited to 128Kb no matter how many workstations they are logged into.:
+
+delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
+DOC_END
+
+NAME: delay_initial_bucket_level
+COMMENT: (percent, 0-100)
+TYPE: ushort
+DEFAULT: 50
+IFDEF: DELAY_POOLS
+LOC: Config.Delay.initial
+DOC_START
+ The initial bucket percentage is used to determine how much is put
+ in each bucket when squid starts, is reconfigured, or first notices
+ a host accessing it (in class 2 and class 3, individual hosts and
+ networks only have buckets associated with them once they have been
+ "seen" by squid).
+DOC_END
+
+COMMENT_START
+ WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: wccp_router
+TYPE: address
+LOC: Config.Wccp.router
+DEFAULT: 0.0.0.0
+IFDEF: USE_WCCP
+DOC_NONE
+NAME: wccp2_router
+TYPE: IPAddress_list
+LOC: Config.Wccp2.router
+DEFAULT: none
+IFDEF: USE_WCCPv2
+DOC_START
+ Use this option to define your WCCP ``home'' router for
+ Squid.
+
+ wccp_router supports a single WCCP(v1) router
+
+ wccp2_router supports multiple WCCPv2 routers
+
+ only one of the two may be used at the same time and defines
+ which version of WCCP to use.
+DOC_END
+
+NAME: wccp_version
+TYPE: int
+LOC: Config.Wccp.version
+DEFAULT: 4
+IFDEF: USE_WCCP
+DOC_START
+ This directive is only relevant if you need to set up WCCP(v1)
+ to some very old and end-of-life Cisco routers. In all other
+ setups it must be left unset or at the default setting.
+ It defines an internal version in the WCCP(v1) protocol,
+ with version 4 being the officially documented protocol.
+
+ According to some users, Cisco IOS 11.2 and earlier only
+ support WCCP version 3. If you're using that or an earlier
+ version of IOS, you may need to change this value to 3, otherwise
+ do not specify this parameter.
+DOC_END
+
+NAME: wccp2_rebuild_wait
+TYPE: onoff
+LOC: Config.Wccp2.rebuildwait
+DEFAULT: on
+IFDEF: USE_WCCPv2
+DOC_START
+ If this is enabled Squid will wait for the cache dir rebuild to finish
+ before sending the first wccp2 HereIAm packet
+DOC_END
+
+NAME: wccp2_forwarding_method
+TYPE: int
+LOC: Config.Wccp2.forwarding_method
+DEFAULT: 1
+IFDEF: USE_WCCPv2
+DOC_START
+ WCCP2 allows the setting of forwarding methods between the
+ router/switch and the cache. Valid values are as follows:
+
+ 1 - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
+ 2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
+
+ Currently (as of IOS 12.4) cisco routers only support GRE.
+ Cisco switches only support the L2 redirect assignment method.
+DOC_END
+
+NAME: wccp2_return_method
+TYPE: int
+LOC: Config.Wccp2.return_method
+DEFAULT: 1
+IFDEF: USE_WCCPv2
+DOC_START
+ WCCP2 allows the setting of return methods between the
+ router/switch and the cache for packets that the cache
+ decides not to handle. Valid values are as follows:
+
+ 1 - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
+ 2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
+
+ Currently (as of IOS 12.4) cisco routers only support GRE.
+ Cisco switches only support the L2 redirect assignment.
+
+ If the "ip wccp redirect exclude in" command has been
+ enabled on the cache interface, then it is still safe for
+ the proxy server to use a l2 redirect method even if this
+ option is set to GRE.
+DOC_END
+
+NAME: wccp2_assignment_method
+TYPE: int
+LOC: Config.Wccp2.assignment_method
+DEFAULT: 1
+IFDEF: USE_WCCPv2
+DOC_START
+ WCCP2 allows the setting of methods to assign the WCCP hash
+ Valid values are as follows:
+
+ 1 - Hash assignment
+ 2 - Mask assignment
+
+ As a general rule, cisco routers support the hash assignment method
+ and cisco switches support the mask assignment method.
+DOC_END
+
+NAME: wccp2_service
+TYPE: wccp2_service
+LOC: Config.Wccp2.info
+DEFAULT: none
+DEFAULT_IF_NONE: standard 0
+IFDEF: USE_WCCPv2
+DOC_START
+ WCCP2 allows for multiple traffic services. There are two
+ types: "standard" and "dynamic". The standard type defines
+ one service id - http (id 0). The dynamic service ids can be from
+ 51 to 255 inclusive. In order to use a dynamic service id
+ one must define the type of traffic to be redirected; this is done
+ using the wccp2_service_info option.
+
+ The "standard" type does not require a wccp2_service_info option,
+ just specifying the service id will suffice.
- user the delay parameters for the user buckets
- (class 4).
+ MD5 service authentication can be enabled by adding
+ "password=<password>" to the end of this service declaration.
- tag the delay parameters for the tag buckets
- (class 5).
+ Examples:
- A pair of delay parameters is written restore/maximum, where restore is
- the number of bytes (not bits - modem and network speeds are usually
- quoted in bits) per second placed into the bucket, and maximum is the
- maximum number of bytes which can be in the bucket at any time.
+ wccp2_service standard 0 # for the 'web-cache' standard service
+ wccp2_service dynamic 80 # a dynamic service type which will be
+ # fleshed out with subsequent options.
+ wccp2_service standard 0 password=foo
- For example, if delay pool number 1 is a class 2 delay pool as in the
- above example, and is being used to strictly limit each host to 64kbps
- (plus overheads), with no overall limit, the line is:
+DOC_END
-delay_parameters 1 -1/-1 8000/8000
+NAME: wccp2_service_info
+TYPE: wccp2_service_info
+LOC: Config.Wccp2.info
+DEFAULT: none
+IFDEF: USE_WCCPv2
+DOC_START
+ Dynamic WCCPv2 services require further information to define the
+ traffic you wish to have diverted.
- Note that the figure -1 is used to represent "unlimited".
+ The format is:
- And, if delay pool number 2 is a class 3 delay pool as in the above
- example, and you want to limit it to a total of 256kbps (strict limit)
- with each 8-bit network permitted 64kbps (strict limit) and each
- individual host permitted 4800bps with a bucket maximum size of 64kb
- to permit a decent web page to be downloaded at a decent speed
- (if the network is not being limited due to overuse) but slow down
- large downloads more significantly:
+ wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
+ priority=<priority> ports=<port>,<port>..
-delay_parameters 2 32000/32000 8000/8000 600/8000
+ The relevant WCCPv2 flags:
+ + src_ip_hash, dst_ip_hash
+ + source_port_hash, dest_port_hash
+ + src_ip_alt_hash, dst_ip_alt_hash
+ + src_port_alt_hash, dst_port_alt_hash
+ + ports_source
- There must be one delay_parameters line for each delay pool.
+ The port list can be one to eight entries.
- Finally, for a class 4 delay pool as in the example - each user will
- be limited to 128Kb no matter how many workstations they are logged into.:
+ Example:
-delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000
+ wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
+ priority=240 ports=80
+
+ Note: the service id must have been defined by a previous
+ 'wccp2_service dynamic <id>' entry.
DOC_END
-NAME: delay_initial_bucket_level
-COMMENT: (percent, 0-100)
-TYPE: ushort
-DEFAULT: 50
-IFDEF: DELAY_POOLS
-LOC: Config.Delay.initial
+NAME: wccp2_weight
+TYPE: int
+LOC: Config.Wccp2.weight
+DEFAULT: 10000
+IFDEF: USE_WCCPv2
DOC_START
- The initial bucket percentage is used to determine how much is put
- in each bucket when squid starts, is reconfigured, or first notices
- a host accessing it (in class 2 and class 3, individual hosts and
- networks only have buckets associated with them once they have been
- "seen" by squid).
+ Each cache server gets assigned a set of the destination
+ hash proportional to their weight.
DOC_END
+NAME: wccp_address
+TYPE: address
+LOC: Config.Wccp.address
+DEFAULT: 0.0.0.0
+IFDEF: USE_WCCP
+DOC_NONE
+NAME: wccp2_address
+TYPE: address
+LOC: Config.Wccp2.address
+DEFAULT: 0.0.0.0
+IFDEF: USE_WCCPv2
+DOC_START
+ Use this option if you require WCCP to use a specific
+ interface address.
+
+ The default behavior is to not bind to any specific address.
+DOC_END
COMMENT_START
- MISCELLANEOUS
+ PERSISTENT CONNECTION HANDLING
-----------------------------------------------------------------------------
+
+ Also see "pconn_timeout" in the TIMEOUTS section
COMMENT_END
-NAME: dns_testnames
-TYPE: wordlist
-LOC: Config.dns_testname_list
-DEFAULT: none
-DEFAULT_IF_NONE: netscape.com internic.net nlanr.net microsoft.com
-DOC_START
- The DNS tests exit as soon as the first site is successfully looked up
+NAME: client_persistent_connections
+TYPE: onoff
+LOC: Config.onoff.client_pconns
+DEFAULT: on
+DOC_NONE
- This test can be disabled with the -D command line option.
+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.
DOC_END
+NAME: persistent_connection_after_error
+TYPE: onoff
+LOC: Config.onoff.error_pconns
+DEFAULT: off
+DOC_START
+ With this directive the use of persistent connections after
+ HTTP errors can be disabled. Useful if you have clients
+ who fail to handle errors on persistent connections proper.
+DOC_END
-NAME: logfile_rotate
-TYPE: int
-DEFAULT: 10
-LOC: Config.Log.rotateNumber
+NAME: detect_broken_pconn
+TYPE: onoff
+LOC: Config.onoff.detect_broken_server_pconns
+DEFAULT: off
DOC_START
- Specifies the number of logfile rotations to make when you
- type 'squid -k rotate'. The default is 10, which will rotate
- with extensions 0 through 9. Setting logfile_rotate to 0 will
- disable the file name rotation, but the logfiles are still closed
- and re-opened. This will enable you to rename the logfiles
- yourself just before sending the rotate signal.
+ Some servers have been found to incorrectly signal the use
+ of HTTP/1.0 persistent connections even on replies not
+ compatible, causing significant delays. This server problem
+ has mostly been seen on redirects.
- Note, the 'squid -k rotate' command normally sends a USR1
- signal to the running squid process. In certain situations
- (e.g. on Linux with Async I/O), USR1 is used for other
- purposes, so -k rotate uses another signal. It is best to get
- in the habit of using 'squid -k rotate' instead of 'kill -USR1
- <pid>'.
+ By enabling this directive Squid attempts to detect such
+ broken replies and automatically assume the reply is finished
+ after 10 seconds timeout.
DOC_END
+COMMENT_START
+ CACHE DIGEST OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
-NAME: append_domain
-TYPE: string
-LOC: Config.appendDomain
-DEFAULT: none
+NAME: digest_generation
+IFDEF: USE_CACHE_DIGESTS
+TYPE: onoff
+LOC: Config.onoff.digest_generation
+DEFAULT: on
DOC_START
- Appends local domain name to hostnames without any dots in
- them. append_domain must begin with a period.
+ This controls whether the server will generate a Cache Digest
+ of its contents. By default, Cache Digest generation is
+ enabled if Squid is compiled with --enable-cache-digests defined.
+DOC_END
- Be warned there are now Internet names with no dots in
- them using only top-domain names, so setting this may
- cause some Internet sites to become unavailable.
+NAME: digest_bits_per_entry
+IFDEF: USE_CACHE_DIGESTS
+TYPE: int
+LOC: Config.digest.bits_per_entry
+DEFAULT: 5
+DOC_START
+ This is the number of bits of the server's Cache Digest which
+ will be associated with the Digest entry for a given HTTP
+ Method and URL (public key) combination. The default is 5.
+DOC_END
-Example:
- append_domain .yourdomain.com
+NAME: digest_rebuild_period
+IFDEF: USE_CACHE_DIGESTS
+COMMENT: (seconds)
+TYPE: time_t
+LOC: Config.digest.rebuild_period
+DEFAULT: 1 hour
+DOC_START
+ This is the wait time between Cache Digest rebuilds.
DOC_END
+NAME: digest_rewrite_period
+COMMENT: (seconds)
+IFDEF: USE_CACHE_DIGESTS
+TYPE: time_t
+LOC: Config.digest.rewrite_period
+DEFAULT: 1 hour
+DOC_START
+ This is the wait time between Cache Digest writes to
+ disk.
+DOC_END
-NAME: tcp_recv_bufsize
+NAME: digest_swapout_chunk_size
COMMENT: (bytes)
TYPE: b_size_t
-DEFAULT: 0 bytes
-LOC: Config.tcpRcvBufsz
+IFDEF: USE_CACHE_DIGESTS
+LOC: Config.digest.swapout_chunk_size
+DEFAULT: 4096 bytes
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.
+ This is the number of bytes of the Cache Digest to write to
+ disk at a time. It defaults to 4096 bytes (4KB), the Squid
+ default swap page.
DOC_END
-NAME: err_html_text
-TYPE: eol
-LOC: Config.errHtmlText
-DEFAULT: none
+NAME: digest_rebuild_chunk_percentage
+COMMENT: (percent, 0-100)
+IFDEF: USE_CACHE_DIGESTS
+TYPE: int
+LOC: Config.digest.rebuild_chunk_percentage
+DEFAULT: 10
DOC_START
- HTML text to include in error messages. Make this a "mailto"
- URL to your admin address, or maybe just a link to your
- organizations Web page.
-
- To include this in your error messages, you must rewrite
- the error template files (found in the "errors" directory).
- Wherever you want the 'err_html_text' line to appear,
- insert a %L tag in the error template file.
+ This is the percentage of the Cache Digest to be scanned at a
+ time. By default it is set to 10% of the Cache Digest.
DOC_END
-NAME: email_err_data
-COMMENT: on|off
-TYPE: onoff
-LOC: Config.onoff.emailErrData
-DEFAULT: on
+COMMENT_START
+ SNMP OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: snmp_port
+TYPE: ushort
+LOC: Config.Port.snmp
+DEFAULT: 0
+IFDEF: SQUID_SNMP
DOC_START
- If enabled, information about the occurred error will be
- included in the mailto links of the ERR pages (if %W is set)
- so that the email body contains the data.
- Syntax is <A HREF="mailto:%w%W">%w</A>
+ The port number where Squid listens for SNMP requests. To enable
+ SNMP support set this to a suitable port number. Port number
+ 3401 is often used for the Squid SNMP agent. By default it's
+ set to "0" (disabled)
+NOCOMMENT_START
+#snmp_port 3401
+NOCOMMENT_END
DOC_END
-
-NAME: deny_info
-TYPE: denyinfo
-LOC: Config.denyInfoList
+NAME: snmp_access
+TYPE: acl_access
+LOC: Config.accessList.snmp
DEFAULT: none
+DEFAULT_IF_NONE: deny all
+IFDEF: SQUID_SNMP
DOC_START
- Usage: deny_info err_page_name acl
- or deny_info http://... acl
- Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
-
- This can be used to return a ERR_ page for requests which
- do not pass the 'http_access' rules. A single ACL will cause
- the http_access check to fail. If a 'deny_info' line exists
- for that ACL Squid returns a corresponding error page.
-
- You may use ERR_ pages that come with Squid or create your own pages
- and put them into the configured errors/ directory.
+ Allowing or denying access to the SNMP port.
- Alternatively you can specify an error URL. The browsers will
- get redirected (302) to the specified URL. %s in the redirection
- URL will be replaced by the requested URL.
+ All access to the agent is denied by default.
+ usage:
- Alternatively you can tell Squid to reset the TCP connection
- by specifying TCP_RESET.
-DOC_END
+ snmp_access allow|deny [!]aclname ...
-NAME: memory_pools
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.mem_pools
-DOC_START
- If set, Squid will keep pools of allocated (but unused) memory
- available for future use. If memory is a premium on your
- system and you believe your malloc library outperforms Squid
- routines, disable this.
+Example:
+ snmp_access allow snmppublic localhost
+ snmp_access deny all
DOC_END
-NAME: memory_pools_limit
-COMMENT: (bytes)
-TYPE: b_size_t
-DEFAULT: 5 MB
-LOC: Config.MemPools.limit
+NAME: snmp_incoming_address
+TYPE: address
+LOC: Config.Addrs.snmp_incoming
+DEFAULT: 0.0.0.0
+IFDEF: SQUID_SNMP
+DOC_NONE
+NAME: snmp_outgoing_address
+TYPE: address
+LOC: Config.Addrs.snmp_outgoing
+DEFAULT: 255.255.255.255
+IFDEF: SQUID_SNMP
DOC_START
- Used only with memory_pools on:
- memory_pools_limit 50 MB
+ Just like 'udp_incoming_address' above, but for the SNMP port.
- If set to a non-zero value, Squid will keep at most the specified
- limit of allocated (but unused) memory in memory pools. All free()
- requests that exceed this limit will be handled by your malloc
- library. Squid does not pre-allocate any memory, just safe-keeps
- objects that otherwise would be free()d. Thus, it is safe to set
- memory_pools_limit to a reasonably high value even if your
- configuration will use less memory.
+ snmp_incoming_address is used for the SNMP socket receiving
+ messages from SNMP agents.
+ snmp_outgoing_address is used for SNMP packets returned to SNMP
+ agents.
- If set to zero, Squid will keep all memory it can. That is, there
- will be no limit on the total amount of memory used for safe-keeping.
+ The default snmp_incoming_address (0.0.0.0) is to listen on all
+ available network interfaces.
- To disable memory allocation optimization, do not set
- memory_pools_limit to 0. Set memory_pools to "off" instead.
+ If snmp_outgoing_address is set to 255.255.255.255 (the default)
+ it will use the same socket as snmp_incoming_address. Only
+ change this if you want to have SNMP replies sent using another
+ address than where this Squid listens for SNMP queries.
- An overhead for maintaining memory pools is not taken into account
- when the limit is checked. This overhead is close to four bytes per
- object kept. However, pools may actually _save_ memory because of
- reduced memory thrashing in your malloc library.
+ NOTE, snmp_incoming_address and snmp_outgoing_address can not have
+ the same value since they both use port 3401.
DOC_END
-NAME: via
-IFDEF: HTTP_VIOLATIONS
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.via
+COMMENT_START
+ ICP OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: icp_port udp_port
+TYPE: ushort
+DEFAULT: 0
+LOC: Config.Port.icp
DOC_START
- If set (default), Squid will include a Via header in requests and
- replies as required by RFC2616.
+ 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).
+NOCOMMENT_START
+icp_port @DEFAULT_ICP_PORT@
+NOCOMMENT_END
DOC_END
-NAME: forwarded_for
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: opt_forwarded_for
+NAME: htcp_port
+IFDEF: USE_HTCP
+TYPE: ushort
+DEFAULT: 0
+LOC: Config.Port.htcp
DOC_START
- If set, Squid will include your system's IP address or name
- in the HTTP requests it forwards. By default it looks like
- this:
-
- X-Forwarded-For: 192.1.2.3
-
- If you disable this, it will appear as
-
- X-Forwarded-For: unknown
+ 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).
+NOCOMMENT_START
+#htcp_port 4827
+NOCOMMENT_END
DOC_END
NAME: log_icp_queries
up or to simplify log analysis.
DOC_END
+NAME: udp_incoming_address
+TYPE: address
+LOC:Config.Addrs.udp_incoming
+DEFAULT: 0.0.0.0
+DOC_START
+ udp_incoming_address is used for UDP packets received from other
+ caches.
+
+ The default behavior is to not bind to any specific address.
+
+ Only change this if you want to have all UDP queries received on
+ a specific interface/address.
+
+ NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS
+ modules. Altering it will affect all of them in the same manner.
+
+ see also; udp_outgoing_address
+
+ NOTE, udp_incoming_address and udp_outgoing_address can not
+ have the same value since they both use the same port.
+DOC_END
+
+NAME: udp_outgoing_address
+TYPE: address
+LOC: Config.Addrs.udp_outgoing
+DEFAULT: 255.255.255.255
+DOC_START
+ udp_outgoing_address is used for UDP packets sent out to other
+ caches.
+
+ The default behavior is to not bind to any specific address.
+
+ Instead it will use the same socket as udp_incoming_address.
+ Only change this if you want to have UDP queries sent using another
+ address than where this Squid listens for UDP queries from other
+ caches.
+
+ NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS
+ modules. Altering it will affect all of them in the same manner.
+
+ see also; udp_incoming_address
+
+ NOTE, udp_incoming_address and udp_outgoing_address can not
+ have the same value since they both use the same port.
+DOC_END
+
NAME: icp_hit_stale
COMMENT: on|off
TYPE: onoff
on their cache_peer lines for connecting to you.
DOC_END
-
NAME: minimum_direct_hops
TYPE: int
DEFAULT: 4
LOC: Config.minDirectHops
DOC_START
- If using the ICMP pinging stuff, do direct fetches for sites
- which are no more than this many hops away.
-DOC_END
-
-NAME: minimum_direct_rtt
-TYPE: int
-DEFAULT: 400
-LOC: Config.minDirectRtt
-DOC_START
- If using the ICMP pinging stuff, do direct fetches for sites
- which are no more than this many rtt milliseconds away.
-DOC_END
-
-NAME: cachemgr_passwd
-TYPE: cachemgrpasswd
-DEFAULT: none
-LOC: Config.passwd_list
-DOC_START
- Specify passwords for cachemgr operations.
-
- Usage: cachemgr_passwd password action action ...
-
- Some valid actions are (see cache manager menu for a full list):
- 5min
- 60min
- asndb
- authenticator
- cbdata
- client_list
- comm_incoming
- config *
- counters
- delay
- digest_stats
- dns
- events
- filedescriptors
- fqdncache
- histograms
- http_headers
- info
- io
- ipcache
- mem
- menu
- netdb
- non_peers
- objects
- offline_toggle *
- pconn
- peer_select
- redirector
- refresh
- server_list
- shutdown *
- store_digest
- storedir
- utilization
- via_headers
- vm_objects
-
- * Indicates actions which will not be performed without a
- valid password, others can be performed if not listed here.
-
- To disable an action, set the password to "disable".
- To allow performing an action without a password, set the
- password to "none".
-
- Use the keyword "all" to set the same password for all actions.
-
-Example:
- cachemgr_passwd secret shutdown
- cachemgr_passwd lesssssssecret info stats/objects
- cachemgr_passwd disable all
-DOC_END
-
-NAME: store_avg_object_size
-COMMENT: (kbytes)
-TYPE: kb_size_t
-DEFAULT: 13 KB
-LOC: Config.Store.avgObjectSize
-DOC_START
- Average object size, used to estimate number of objects your
- cache can hold. See doc/Release-Notes-1.1.txt. The default is
- 13 KB.
-DOC_END
-
-NAME: store_objects_per_bucket
-TYPE: int
-DEFAULT: 20
-LOC: Config.Store.objectsPerBucket
-DOC_START
- Target number of objects per bucket in the store hash table.
- Lowering this value increases the total number of buckets and
- also the storage maintenance rate. The default is 20.
+ If using the ICMP pinging stuff, do direct fetches for sites
+ which are no more than this many hops away.
DOC_END
-NAME: client_db
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.client_db
+NAME: minimum_direct_rtt
+TYPE: int
+DEFAULT: 400
+LOC: Config.minDirectRtt
DOC_START
- If you want to disable collecting per-client statistics,
- turn off client_db here.
+ If using the ICMP pinging stuff, do direct fetches for sites
+ which are no more than this many rtt milliseconds away.
DOC_END
-
NAME: netdb_low
TYPE: int
DEFAULT: 900
entries will be deleted until the low mark is reached.
DOC_END
-
NAME: netdb_ping_period
TYPE: time_t
LOC: Config.Netdb.period
network. The default is five minutes.
DOC_END
-
NAME: query_icmp
COMMENT: on|off
TYPE: onoff
database, or has a zero RTT.
DOC_END
-NAME: buffered_logs
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.buffered_logs
-DOC_START
- cache.log log file is written with stdio functions, and as such
- it can be buffered or unbuffered. By default it will be unbuffered.
- Buffering it can speed up the writing slightly (though you are
- unlikely to need to worry unless you run with tons of debugging
- enabled in which case performance will suffer badly anyway..).
-DOC_END
-
-NAME: refresh_all_ims
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.refresh_all_ims
-DOC_START
- When you enable this option, squid will always check
- the origin server for an update when a client sends an
- If-Modified-Since request. Many browsers use IMS
- requests when the user requests a reload, and this
- ensures those clients receive the latest version.
-
- By default (off), squid may return a Not Modified response
- based on the age of the cached version.
-DOC_END
-
-NAME: reload_into_ims
-IFDEF: HTTP_VIOLATIONS
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: off
-LOC: Config.onoff.reload_into_ims
+NAME: icp_query_timeout
+COMMENT: (msec)
+DEFAULT: 0
+TYPE: int
+LOC: Config.Timeout.icp_query
DOC_START
- When you enable this option, client no-cache or ``reload''
- requests will be changed to If-Modified-Since requests.
- Doing this VIOLATES the HTTP standard. Enabling this
- feature could make you liable for problems which it
- causes.
+ Normally Squid will automatically determine an optimal ICP
+ query timeout value based on the round-trip-time of recent ICP
+ queries. If you want to override the value determined by
+ Squid, set this 'icp_query_timeout' to a non-zero value. This
+ value is specified in MILLISECONDS, so, to use a 2-second
+ timeout (the old default), you would write:
- see also refresh_pattern for a more selective approach.
+ icp_query_timeout 2000
DOC_END
-NAME: always_direct
-TYPE: acl_access
-LOC: Config.accessList.AlwaysDirect
-DEFAULT: none
+NAME: maximum_icp_query_timeout
+COMMENT: (msec)
+DEFAULT: 2000
+TYPE: int
+LOC: Config.Timeout.icp_query_max
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
- something like:
-
- acl local-servers dstdomain my.domain.net
- always_direct allow local-servers
-
- To always forward FTP requests directly, use
-
- acl FTP proto FTP
- always_direct allow FTP
-
- NOTE: There is a similar, but opposite option named
- 'never_direct'. You need to be aware that "always_direct deny
- foo" is NOT the same thing as "never_direct allow foo". You
- may need to use a deny rule to exclude a more-specific case of
- some other rule. Example:
-
- acl local-external dstdomain external.foo.net
- acl local-servers dstdomain .foo.net
- always_direct deny local-external
- always_direct allow local-servers
-
- This option replaces some v1.1 options such as local_domain
- and local_ip.
+ Normally the ICP query timeout is determined dynamically. But
+ sometimes it can lead to very large values (say 5 seconds).
+ Use this option to put an upper limit on the dynamic timeout
+ value. Do NOT use this option to always use a fixed (instead
+ of a dynamic) timeout value. To set a fixed timeout see the
+ 'icp_query_timeout' directive.
DOC_END
-NAME: never_direct
-TYPE: acl_access
-LOC: Config.accessList.NeverDirect
-DEFAULT: none
+NAME: minimum_icp_query_timeout
+COMMENT: (msec)
+DEFAULT: 5
+TYPE: int
+LOC: Config.Timeout.icp_query_min
DOC_START
- Usage: never_direct allow|deny [!]aclname ...
-
- never_direct is the opposite of always_direct. Please read
- the description for always_direct if you have not already.
-
- With 'never_direct' you can use ACL elements to specify
- requests which should NEVER be forwarded directly to origin
- servers. For example, to force the use of a proxy for all
- requests, except those in your local domain use something like:
-
- acl local-servers dstdomain .foo.net
- acl all src 0.0.0.0/0.0.0.0
- never_direct deny local-servers
- never_direct allow all
-
- or if Squid is inside a firewall and there are local intranet
- servers inside the firewall use something like:
-
- acl local-intranet dstdomain .foo.net
- acl local-external dstdomain external.foo.net
- always_direct deny local-external
- always_direct allow local-intranet
- never_direct allow all
-
- This option replaces some v1.1 options such as inside_firewall
- and firewall_ip.
+ Normally the ICP query timeout is determined dynamically. But
+ sometimes it can lead to very small timeouts, even lower than
+ the normal latency variance on your link due to traffic.
+ Use this option to put an lower limit on the dynamic timeout
+ value. Do NOT use this option to always use a fixed (instead
+ of a dynamic) timeout value. To set a fixed timeout see the
+ 'icp_query_timeout' directive.
DOC_END
-NAME: request_header_access
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_access[]
-LOC: Config.request_header_access
-DEFAULT: none
+NAME: background_ping_rate
+COMMENT: time-units
+TYPE: time_t
+DEFAULT: 10 seconds
+LOC: Config.backgroundPingRate
DOC_START
- Usage: request_header_access header_name allow|deny [!]aclname ...
-
- WARNING: Doing this VIOLATES the HTTP standard. Enabling
- this feature could make you liable for problems which it
- causes.
-
- This option replaces the old 'anonymize_headers' and the
- older 'http_anonymizer' option with something that is much
- more configurable. This new method creates a list of ACLs
- for each header, allowing you very fine-tuned header
- mangling.
-
- This option only applies to request headers, i.e., from the
- client to the server.
-
- You can only specify known headers for the header name.
- Other headers are reclassified as 'Other'. You can also
- refer to all the headers with 'All'.
-
- For example, to achieve the same behavior as the old
- 'http_anonymizer standard' option, you should use:
-
- 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 Proxy-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.
-
- By default, all headers are allowed (no anonymizing is
- performed).
+ Controls how often the ICP pings are sent to siblings that
+ have background-ping set.
DOC_END
-NAME: reply_header_access
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_access[]
-LOC: Config.reply_header_access
-DEFAULT: none
-DOC_START
- Usage: reply_header_access header_name allow|deny [!]aclname ...
-
- WARNING: Doing this VIOLATES the HTTP standard. Enabling
- this feature could make you liable for problems which it
- causes.
-
- This option only applies to reply headers, i.e., from the
- server to the client.
-
- This is the same as request_header_access, but in the other
- direction.
+COMMENT_START
+ MULTICAST ICP OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
- This option replaces the old 'anonymize_headers' and the
- older 'http_anonymizer' option with something that is much
- more configurable. This new method creates a list of ACLs
- for each header, allowing you very fine-tuned header
- mangling.
+NAME: mcast_groups
+TYPE: wordlist
+LOC: Config.mcast_group_list
+DEFAULT: none
+DOC_START
+ This tag specifies a list of multicast groups which your server
+ should join to receive multicasted ICP queries.
- You can only specify known headers for the header name.
- Other headers are reclassified as 'Other'. You can also
- refer to all the headers with 'All'.
+ NOTE! Be very careful what you put here! Be sure you
+ understand the difference between an ICP _query_ and an ICP
+ _reply_. This option is to be set only if you want to RECEIVE
+ multicast queries. Do NOT set this option to SEND multicast
+ ICP (use cache_peer for that). ICP replies are always sent via
+ unicast, so this option does not affect whether or not you will
+ receive replies from multicast group members.
- For example, to achieve the same behavior as the old
- 'http_anonymizer standard' option, you should use:
+ You must be very careful to NOT use a multicast address which
+ is already in use by another group of caches.
- 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
+ If you are unsure about multicast, please read the Multicast
+ chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/).
- Or, to reproduce the old 'http_anonymizer paranoid' feature
- you should use:
+ Usage: mcast_groups 239.128.16.128 224.0.1.20
- reply_header_access Allow allow all
- reply_header_access Authorization allow all
- reply_header_access WWW-Authenticate allow all
- reply_header_access Proxy-Authorization allow all
- reply_header_access Proxy-Authenticate allow all
- reply_header_access Cache-Control allow all
- reply_header_access Content-Encoding allow all
- reply_header_access Content-Length allow all
- reply_header_access Content-Type allow all
- reply_header_access Date allow all
- reply_header_access Expires allow all
- reply_header_access Host allow all
- reply_header_access If-Modified-Since allow all
- reply_header_access Last-Modified allow all
- reply_header_access Location allow all
- reply_header_access Pragma allow all
- reply_header_access Accept allow all
- reply_header_access Accept-Charset allow all
- reply_header_access Accept-Encoding allow all
- reply_header_access Accept-Language allow all
- reply_header_access Content-Language allow all
- reply_header_access Mime-Version allow all
- reply_header_access Retry-After allow all
- reply_header_access Title allow all
- reply_header_access Connection allow all
- reply_header_access Proxy-Connection allow all
- reply_header_access All deny all
+ By default, Squid doesn't listen on any multicast groups.
+DOC_END
- although the HTTP request headers won't be usefully controlled
- by this directive -- see request_header_access for details.
+NAME: mcast_miss_addr
+IFDEF: MULTICAST_MISS_STREAM
+TYPE: address
+LOC: Config.mcast_miss.addr
+DEFAULT: 255.255.255.255
+DOC_START
+ If you enable this option, every "cache miss" URL will
+ be sent out on the specified multicast address.
- By default, all headers are allowed (no anonymizing is
- performed).
+ Do not enable this option unless you are are absolutely
+ certain you understand what you are doing.
DOC_END
-NAME: header_replace
-IFDEF: HTTP_VIOLATIONS
-TYPE: http_header_replace[]
-LOC: Config.request_header_access
-DEFAULT: none
+NAME: mcast_miss_ttl
+IFDEF: MULTICAST_MISS_STREAM
+TYPE: ushort
+LOC: Config.mcast_miss.ttl
+DEFAULT: 16
DOC_START
- Usage: header_replace header_name message
- Example: header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)
+ This is the time-to-live value for packets multicasted
+ when multicasting off cache miss URLs is enabled. By
+ default this is set to 'site scope', i.e. 16.
+DOC_END
- This option allows you to change the contents of headers
- denied with header_access above, by replacing them with
- some fixed string. This replaces the old fake_user_agent
- option.
+NAME: mcast_miss_port
+IFDEF: MULTICAST_MISS_STREAM
+TYPE: ushort
+LOC: Config.mcast_miss.port
+DEFAULT: 3135
+DOC_START
+ This is the port number to be used in conjunction with
+ 'mcast_miss_addr'.
+DOC_END
- This only applies to request headers, not reply headers.
+NAME: mcast_miss_encode_key
+IFDEF: MULTICAST_MISS_STREAM
+TYPE: string
+LOC: Config.mcast_miss.encode_key
+DEFAULT: XXXXXXXXXXXXXXXX
+DOC_START
+ The URLs that are sent in the multicast miss stream are
+ encrypted. This is the encryption key.
+DOC_END
- By default, headers are removed if denied.
+NAME: mcast_icp_query_timeout
+COMMENT: (msec)
+DEFAULT: 2000
+TYPE: int
+LOC: Config.Timeout.mcast_icp_query
+DOC_START
+ 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
+ seconds.
DOC_END
+COMMENT_START
+ INTERNAL ICON OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
NAME: icon_directory
TYPE: string
LOC: Config.icons.directory
If disabled it will revert to the old behavior of including
it's own name and port in the URL.
- If you run a complex cache hierarchy with a mix of Squid and
- other proxies you may need to disable this directive.
-DOC_END
-
-NAME: error_directory
-TYPE: string
-LOC: Config.errorDirectory
-DEFAULT: @DEFAULT_ERROR_DIR@
-DOC_START
- If you wish to create your own versions of the default
- (English) error files, either to customize them to suit your
- language or company copy the template English files to another
- directory and point this tag at them.
-DOC_END
-
-NAME: maximum_single_addr_tries
-TYPE: int
-LOC: Config.retry.maxtries
-DEFAULT: 1
-DOC_START
- This sets the maximum number of connection attempts for a
- host that only has one address (for multiple-address hosts,
- each address is tried once).
-
- The default value is one attempt, the (not recommended)
- maximum is 255 tries. A warning message will be generated
- if it is set to a value greater than ten.
-
- Note: This is in addition to the request re-forwarding which
- takes place if Squid fails to get a satisfying response.
-DOC_END
-
-NAME: retry_on_error
-TYPE: onoff
-LOC: Config.retry.onerror
-DEFAULT: off
-DOC_START
- If set to on Squid will automatically retry requests when
- receiving an error response. This is mainly useful if you
- are in a complex cache hierarchy to work around access
- control errors.
-DOC_END
-
-NAME: snmp_port
-TYPE: ushort
-LOC: Config.Port.snmp
-DEFAULT: 3401
-IFDEF: SQUID_SNMP
-DOC_START
- Squid can now serve statistics and status information via SNMP.
- By default it listens to port 3401 on the machine. If you don't
- wish to use SNMP, set this to "0".
-
- 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
-TYPE: acl_access
-LOC: Config.accessList.snmp
-DEFAULT: none
-DEFAULT_IF_NONE: deny all
-IFDEF: SQUID_SNMP
-DOC_START
- Allowing or denying access to the SNMP port.
-
- All access to the agent is denied by default.
- usage:
-
- snmp_access allow|deny [!]aclname ...
-
-Example:
- snmp_access allow snmppublic localhost
- snmp_access deny all
-DOC_END
-
-NAME: snmp_incoming_address
-TYPE: address
-LOC: Config.Addrs.snmp_incoming
-DEFAULT: 0.0.0.0
-IFDEF: SQUID_SNMP
-DOC_NONE
-NAME: snmp_outgoing_address
-TYPE: address
-LOC: Config.Addrs.snmp_outgoing
-DEFAULT: 255.255.255.255
-IFDEF: SQUID_SNMP
-DOC_START
- Just like 'udp_incoming_address' above, but for the SNMP port.
-
- snmp_incoming_address is used for the SNMP socket receiving
- messages from SNMP agents.
- snmp_outgoing_address is used for SNMP packets returned to SNMP
- agents.
-
- The default snmp_incoming_address (0.0.0.0) is to listen on all
- available network interfaces.
-
- If snmp_outgoing_address is set to 255.255.255.255 (the default)
- it will use the same socket as snmp_incoming_address. Only
- change this if you want to have SNMP replies sent using another
- address than where this Squid listens for SNMP queries.
-
- NOTE, snmp_incoming_address and snmp_outgoing_address can not have
- the same value since they both use port 3401.
-DOC_END
-
-NAME: as_whois_server
-TYPE: string
-LOC: Config.as_whois_server
-DEFAULT: whois.ra.net
-DEFAULT_IF_NONE: whois.ra.net
-DOC_START
- WHOIS server to query for AS numbers. NOTE: AS numbers are
- queried only when Squid starts up, not for every request.
-DOC_END
-
-NAME: wccp_router
-TYPE: address
-LOC: Config.Wccp.router
-DEFAULT: 0.0.0.0
-IFDEF: USE_WCCP
-DOC_NONE
-NAME: wccp2_router
-TYPE: sockaddr_in_list
-LOC: Config.Wccp2.router
-DEFAULT: none
-IFDEF: USE_WCCPv2
-DOC_START
- Use this option to define your WCCP ``home'' router for
- Squid.
-
- wccp_router supports a single WCCP(v1) router
+ If you run a complex cache hierarchy with a mix of Squid and
+ other proxies you may need to disable this directive.
+DOC_END
- wccp2_router supports multiple WCCPv2 routers
+COMMENT_START
+ ERROR PAGE OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
- only one of the two may be used at the same time and defines
- which version of WCCP to use.
+NAME: error_directory
+TYPE: string
+LOC: Config.errorDirectory
+DEFAULT: @DEFAULT_ERROR_DIR@
+DOC_START
+ If you wish to create your own versions of the default
+ (English) error files, either to customize them to suit your
+ language or company copy the template English files to another
+ directory and point this tag at them.
+
+ The squid developers are interested in making squid available in
+ a wide variety of languages. If you are making translations for a
+ langauge that Squid does not currently provide please consider
+ contributing your translation back to the project.
DOC_END
-NAME: wccp_version
-TYPE: int
-LOC: Config.Wccp.version
-DEFAULT: 4
-IFDEF: USE_WCCP
+NAME: err_html_text
+TYPE: eol
+LOC: Config.errHtmlText
+DEFAULT: none
DOC_START
- This directive is only relevant if you need to set up WCCP(v1)
- to some very old and end-of-life Cisco routers. In all other
- setups it must be left unset or at the default setting.
- It defines an internal version in the WCCP(v1) protocol,
- with version 4 being the officially documented protocol.
+ HTML text to include in error messages. Make this a "mailto"
+ URL to your admin address, or maybe just a link to your
+ organizations Web page.
- According to some users, Cisco IOS 11.2 and earlier only
- support WCCP version 3. If you're using that or an earlier
- version of IOS, you may need to change this value to 3, otherwise
- do not specify this parameter.
+ To include this in your error messages, you must rewrite
+ the error template files (found in the "errors" directory).
+ Wherever you want the 'err_html_text' line to appear,
+ insert a %L tag in the error template file.
DOC_END
-NAME: wccp2_rebuild_wait
+NAME: email_err_data
+COMMENT: on|off
TYPE: onoff
-LOC: Config.Wccp2.rebuildwait
+LOC: Config.onoff.emailErrData
DEFAULT: on
-IFDEF: USE_WCCPv2
DOC_START
- If this is enabled Squid will wait for the cache dir rebuild to finish
- before sending the first wccp2 HereIAm packet
+ If enabled, information about the occurred error will be
+ included in the mailto links of the ERR pages (if %W is set)
+ so that the email body contains the data.
+ Syntax is <A HREF="mailto:%w%W">%w</A>
DOC_END
-NAME: wccp2_forwarding_method
-TYPE: int
-LOC: Config.Wccp2.forwarding_method
-DEFAULT: 1
-IFDEF: USE_WCCPv2
+NAME: deny_info
+TYPE: denyinfo
+LOC: Config.denyInfoList
+DEFAULT: none
DOC_START
- WCCP2 allows the setting of forwarding methods between the
- router/switch and the cache. Valid values are as follows:
+ Usage: deny_info err_page_name acl
+ or deny_info http://... acl
+ Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys
- 1 - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
- 2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
+ This can be used to return a ERR_ page for requests which
+ do not pass the 'http_access' rules. Squid remembers the last
+ acl it evaluated in http_access, and if a 'deny_info' line exists
+ for that ACL Squid returns a corresponding error page.
- Currently (as of IOS 12.4) cisco routers only support GRE.
- Cisco switches only support the L2 redirect assignment method.
+ The acl is typically the last acl on the http_access deny line which
+ denied access. The exceptions to this rule are:
+ - When Squid needs to request authentication credentials. It's then
+ the first authentication related acl encountered
+ - When none of the http_access lines matches. It's then the last
+ acl processed on the last http_access line.
+
+ You may use ERR_ pages that come with Squid or create your own pages
+ and put them into the configured errors/ directory.
+
+ Alternatively you can specify an error URL. The browsers will
+ get redirected (302) to the specified URL. %s in the redirection
+ URL will be replaced by the requested URL.
+
+ Alternatively you can tell Squid to reset the TCP connection
+ by specifying TCP_RESET.
DOC_END
-NAME: wccp2_return_method
-TYPE: int
-LOC: Config.Wccp2.return_method
-DEFAULT: 1
-IFDEF: USE_WCCPv2
+COMMENT_START
+ OPTIONS INFLUENCING REQUEST FORWARDING
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: nonhierarchical_direct
+TYPE: onoff
+LOC: Config.onoff.nonhierarchical_direct
+DEFAULT: on
DOC_START
- WCCP2 allows the setting of return methods between the
- router/switch and the cache for packets that the cache
- decides not to handle. Valid values are as follows:
+ By default, Squid will send any non-hierarchical requests
+ (matching hierarchy_stoplist or not cacheable request type) direct
+ to origin servers.
- 1 - GRE encapsulation (forward the packet in a GRE/WCCP tunnel)
- 2 - L2 redirect (forward the packet using Layer 2/MAC rewriting)
+ If you set this to off, Squid will prefer to send these
+ requests to parents.
- Currently (as of IOS 12.4) cisco routers only support GRE.
- Cisco switches only support the L2 redirect assignment.
+ 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 the "ip wccp redirect exclude in" command has been
- enabled on the cache interface, then it is still safe for
- the proxy server to use a l2 redirect method even if this
- option is set to GRE.
+ If you are inside an firewall see never_direct instead of
+ this directive.
DOC_END
-NAME: wccp2_assignment_method
-TYPE: int
-LOC: Config.Wccp2.assignment_method
-DEFAULT: 1
-IFDEF: USE_WCCPv2
+NAME: prefer_direct
+TYPE: onoff
+LOC: Config.onoff.prefer_direct
+DEFAULT: off
DOC_START
- WCCP2 allows the setting of methods to assign the WCCP hash
- Valid values are as follows:
+ Normally Squid tries to use parents for most requests. If you for some
+ reason like it to first try going direct and only use a parent if
+ going direct fails set this to on.
- 1 - Hash assignment
- 2 - Mask assignment
+ 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.
- As a general rule, cisco routers support the hash assignment method
- and cisco switches support the mask assignment method.
+ 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: wccp2_service
-TYPE: wccp2_service
-LOC: Config.Wccp2.info
+NAME: always_direct
+TYPE: acl_access
+LOC: Config.accessList.AlwaysDirect
DEFAULT: none
-DEFAULT_IF_NONE: standard 0
-IFDEF: USE_WCCPv2
DOC_START
- WCCP2 allows for multiple traffic services. There are two
- types: "standard" and "dynamic". The standard type defines
- one service id - http (id 0). The dynamic service ids can be from
- 51 to 255 inclusive. In order to use a dynamic service id
- one must define the type of traffic to be redirected; this is done
- using the wccp2_service_info option.
+ Usage: always_direct allow|deny [!]aclname ...
- The "standard" type does not require a wccp2_service_info option,
- just specifying the service id will suffice.
+ Here you can use ACL elements to specify requests which should
+ ALWAYS be forwarded by Squid to the origin servers without using
+ any peers. For example, to always directly forward requests for
+ local servers ignoring any parents or siblings you may have use
+ something like:
- MD5 service authentication can be enabled by adding
- "password=<password>" to the end of this service declaration.
+ acl local-servers dstdomain my.domain.net
+ always_direct allow local-servers
- Examples:
+ To always forward FTP requests directly, use
- wccp2_service standard 0 # for the 'web-cache' standard service
- wccp2_service dynamic 80 # a dynamic service type which will be
- # fleshed out with subsequent options.
- wccp2_service standard 0 password=foo
+ acl FTP proto FTP
+ always_direct allow FTP
-DOC_END
+ NOTE: There is a similar, but opposite option named
+ 'never_direct'. You need to be aware that "always_direct deny
+ foo" is NOT the same thing as "never_direct allow foo". You
+ may need to use a deny rule to exclude a more-specific case of
+ some other rule. Example:
-NAME: wccp2_service_info
-TYPE: wccp2_service_info
-LOC: Config.Wccp2.info
-DEFAULT: none
-IFDEF: USE_WCCPv2
-DOC_START
- Dynamic WCCPv2 services require further information to define the
- traffic you wish to have diverted.
+ acl local-external dstdomain external.foo.net
+ acl local-servers dstdomain .foo.net
+ always_direct deny local-external
+ always_direct allow local-servers
- The format is:
+ 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.
- wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>..
- priority=<priority> ports=<port>,<port>..
+ 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.
- The relevant WCCPv2 flags:
- + src_ip_hash, dst_ip_hash
- + source_port_hash, dest_port_hash
- + src_ip_alt_hash, dst_ip_alt_hash
- + src_port_alt_hash, dst_port_alt_hash
- + ports_source
+ This option replaces some v1.1 options such as local_domain
+ and local_ip.
+DOC_END
- The port list can be one to eight entries.
+NAME: never_direct
+TYPE: acl_access
+LOC: Config.accessList.NeverDirect
+DEFAULT: none
+DOC_START
+ Usage: never_direct allow|deny [!]aclname ...
- Example:
+ never_direct is the opposite of always_direct. Please read
+ the description for always_direct if you have not already.
- wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source
- priority=240 ports=80
+ With 'never_direct' you can use ACL elements to specify
+ requests which should NEVER be forwarded directly to origin
+ servers. For example, to force the use of a proxy for all
+ requests, except those in your local domain use something like:
- Note: the service id must have been defined by a previous
- 'wccp2_service dynamic <id>' entry.
-DOC_END
+ acl local-servers dstdomain .foo.net
+ acl all src 0.0.0.0/0.0.0.0
+ never_direct deny local-servers
+ never_direct allow all
-NAME: wccp2_weight
-TYPE: int
-LOC: Config.Wccp2.weight
-DEFAULT: 10000
-IFDEF: USE_WCCPv2
-DOC_START
- Each cache server gets assigned a set of the destination
- hash proportional to their weight.
-DOC_END
+ or if Squid is inside a firewall and there are local intranet
+ servers inside the firewall use something like:
-NAME: wccp_address
-TYPE: address
-LOC: Config.Wccp.address
-DEFAULT: 0.0.0.0
-IFDEF: USE_WCCP
-DOC_NONE
-NAME: wccp2_address
-TYPE: address
-LOC: Config.Wccp2.address
-DEFAULT: 0.0.0.0
-IFDEF: USE_WCCPv2
-DOC_START
- Use this option if you require WCCP to use a specific
- interface address.
+ acl local-intranet dstdomain .foo.net
+ acl local-external dstdomain external.foo.net
+ always_direct deny local-external
+ always_direct allow local-intranet
+ never_direct allow all
- The default behavior is to not bind to any specific address.
+ This option replaces some v1.1 options such as inside_firewall
+ and firewall_ip.
DOC_END
+COMMENT_START
+ ADVANCED NETWORKING OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
NAME: incoming_icp_average
TYPE: int
you understand the algorithms in comm_select.c first!
DOC_END
-NAME: max_open_disk_fds
-TYPE: int
-LOC: Config.max_open_disk_fds
-DEFAULT: 0
+NAME: accept_filter
+TYPE: string
+DEFAULT: none
+LOC: Config.accept_filter
DOC_START
- To avoid having disk as the I/O bottleneck Squid can optionally
- bypass the on-disk cache if more than this amount of disk file
- descriptors are open.
+ FreeBSD:
- A value of 0 indicates no limit.
+ The name of an accept(2) filter to install on Squid's
+ listen socket(s). This feature is perhaps specific to
+ FreeBSD and requires support in the kernel.
+
+ The 'httpready' filter delays delivering new connections
+ to Squid until a full HTTP request has been received.
+ See the accf_http(9) man page for details.
+
+ The 'dataready' filter delays delivering new connections
+ to Squid until there is some data to process.
+ See the accf_dataready(9) man page for details.
+
+ Linux:
+
+ The 'data' filter delays delivering of new connections
+ to Squid until there is some data to process by TCP_ACCEPT_DEFER.
+ You may optionally specify a number of seconds to wait by
+ 'data=N' where N is the number of seconds. Defaults to 30
+ if not specified. See the tcp(7) man page for details.
+EXAMPLE:
+# FreeBSD
+accept_filter httpready
+# Linux
+accept_filter data
DOC_END
-NAME: offline_mode
+NAME: tcp_recv_bufsize
+COMMENT: (bytes)
+TYPE: b_size_t
+DEFAULT: 0 bytes
+LOC: Config.tcpRcvBufsz
+DOC_START
+ Size of receive buffer to set for TCP sockets. Probably just
+ as easy to change your kernel's default. Set to zero to use
+ the default buffer size.
+DOC_END
+
+COMMENT_START
+ ICAP OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: icap_enable
TYPE: onoff
-LOC: Config.onoff.offline
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.onoff
DEFAULT: off
DOC_START
- Enable this option and Squid will never try to validate cached
- objects.
+ If you want to enable the ICAP module support, set this to on.
DOC_END
-NAME: uri_whitespace
-TYPE: uri_whitespace
-LOC: Config.uri_whitespace
-DEFAULT: strip
+NAME: icap_connect_timeout
+TYPE: time_t
+DEFAULT: none
+LOC: TheICAPConfig.connect_timeout_raw
+IFDEF: ICAP_CLIENT
DOC_START
- What to do with requests that have whitespace characters in the
- URI. Options:
+ This parameter specifies how long to wait for the TCP connect to
+ the requested ICAP server to complete before giving up and either
+ terminating the HTTP transaction or bypassing the failure.
- strip: The whitespace characters are stripped out of the URL.
- This is the behavior recommended by RFC2396.
- deny: The request is denied. The user receives an "Invalid
- Request" message.
- allow: The request is allowed and the URI is not changed. The
- whitespace characters remain in the URI. Note the
- whitespace is passed to redirector processes if they
- are in use.
- encode: The request is allowed and the whitespace characters are
- encoded according to RFC1738. This could be considered
- a violation of the HTTP/1.1
- RFC because proxies are not allowed to rewrite URI's.
- chop: The request is allowed and the URI is chopped at the
- first whitespace. This might also be considered a
- violation.
+ The default for optional services is peer_connect_timeout.
+ The default for essential services is connect_timeout.
+ If this option is explicitly set, its value applies to all services.
DOC_END
-NAME: broken_posts
-TYPE: acl_access
+NAME: icap_io_timeout
+COMMENT: time-units
+TYPE: time_t
DEFAULT: none
-LOC: Config.accessList.brokenPosts
+LOC: TheICAPConfig.io_timeout_raw
+IFDEF: ICAP_CLIENT
DOC_START
- A list of ACL elements which, if matched, causes Squid to send
- an extra CRLF pair after the body of a PUT/POST request.
+ This parameter specifies how long to wait for an I/O activity on
+ an established, active ICAP connection before giving up and
+ either terminating the HTTP transaction or bypassing the
+ failure.
- 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:
+ The default is read_timeout.
+DOC_END
- Note: certain buggy HTTP/1.0 client implementations generate an
- extra CRLF's after a POST request. To restate what is explicitly
- forbidden by the BNF, an HTTP/1.1 client must not preface or follow
- a request with an extra CRLF.
+NAME: icap_service_failure_limit
+TYPE: int
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig.service_failure_limit
+DEFAULT: 10
+DOC_START
+ The limit specifies the number of failures that Squid tolerates
+ when establishing a new TCP connection with an ICAP service. If
+ the number of failures exceeds the limit, the ICAP service is
+ not used for new ICAP requests until it is time to refresh its
+ OPTIONS. The per-service failure counter is reset to zero each
+ time Squid fetches new service OPTIONS.
-Example:
- acl buggy_server url_regex ^http://....
- broken_posts allow buggy_server
+ A negative value disables the limit. Without the limit, an ICAP
+ service will not be considered down due to connectivity failures
+ between ICAP OPTIONS requests.
DOC_END
-NAME: mcast_miss_addr
-IFDEF: MULTICAST_MISS_STREAM
-TYPE: address
-LOC: Config.mcast_miss.addr
-DEFAULT: 255.255.255.255
+NAME: icap_service_revival_delay
+TYPE: int
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig.service_revival_delay
+DEFAULT: 180
DOC_START
- If you enable this option, every "cache miss" URL will
- be sent out on the specified multicast address.
+ The delay specifies the number of seconds to wait after an ICAP
+ OPTIONS request failure before requesting the options again. The
+ failed ICAP service is considered "down" until fresh OPTIONS are
+ fetched.
- Do not enable this option unless you are are absolutely
- certain you understand what you are doing.
+ The actual delay cannot be smaller than the hardcoded minimum
+ delay of 30 seconds.
DOC_END
-NAME: mcast_miss_ttl
-IFDEF: MULTICAST_MISS_STREAM
-TYPE: ushort
-LOC: Config.mcast_miss.ttl
-DEFAULT: 16
+NAME: icap_preview_enable
+TYPE: onoff
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.preview_enable
+DEFAULT: on
DOC_START
- This is the time-to-live value for packets multicasted
- when multicasting off cache miss URLs is enabled. By
- default this is set to 'site scope', i.e. 16.
+ The ICAP Preview feature allows the ICAP server to handle the
+ HTTP message by looking only at the beginning of the message body
+ or even without receiving the body at all. In some environments,
+ previews greatly speedup ICAP processing.
+
+ During an ICAP OPTIONS transaction, the server may tell Squid what
+ HTTP messages should be previewed and how big the preview should be.
+ Squid will not use Preview if the server did not request one.
+
+ To disable ICAP Preview for all ICAP services, regardless of
+ individual ICAP server OPTIONS responses, set this option to "off".
+Example:
+icap_preview_enable off
DOC_END
-NAME: mcast_miss_port
-IFDEF: MULTICAST_MISS_STREAM
-TYPE: ushort
-LOC: Config.mcast_miss.port
-DEFAULT: 3135
+NAME: icap_preview_size
+TYPE: int
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig.preview_size
+DEFAULT: -1
DOC_START
- This is the port number to be used in conjunction with
- 'mcast_miss_addr'.
+ 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.
DOC_END
-NAME: mcast_miss_encode_key
-IFDEF: MULTICAST_MISS_STREAM
-TYPE: string
-LOC: Config.mcast_miss.encode_key
-DEFAULT: XXXXXXXXXXXXXXXX
+NAME: icap_default_options_ttl
+TYPE: int
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig.default_options_ttl
+DEFAULT: 60
DOC_START
- The URLs that are sent in the multicast miss stream are
- encrypted. This is the encryption key.
+ The default TTL value for ICAP OPTIONS responses that don't have
+ an Options-TTL header.
DOC_END
-NAME: nonhierarchical_direct
+NAME: icap_persistent_connections
TYPE: onoff
-LOC: Config.onoff.nonhierarchical_direct
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.reuse_connections
DEFAULT: on
DOC_START
- By default, Squid will send any non-hierarchical requests
- (matching hierarchy_stoplist or not cachable request type) direct
- to origin servers.
+ Whether or not Squid should use persistent connections to
+ an ICAP server.
+DOC_END
- If you set this to off, Squid will prefer to send these
- requests to parents.
+NAME: icap_send_client_ip
+TYPE: onoff
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.send_client_ip
+DEFAULT: off
+DOC_START
+ This adds the header "X-Client-IP" to ICAP requests.
+DOC_END
- Note that in most configurations, by turning this off you will only
- add latency to these request without any improvement in global hit
- ratio.
+NAME: icap_send_client_username
+TYPE: onoff
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.send_client_username
+DEFAULT: off
+DOC_START
+ This sends authenticated HTTP client username (if available) to
+ the ICAP service. The username value is encoded based on the
+ icap_client_username_encode option and is sent using the header
+ specified by the icap_client_username_header option.
+DOC_END
- If you are inside an firewall see never_direct instead of
- this directive.
+NAME: icap_client_username_header
+TYPE: string
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig.client_username_header
+DEFAULT: X-Client-Username
+DOC_START
+ ICAP request header name to use for send_client_username.
DOC_END
-NAME: prefer_direct
+NAME: icap_client_username_encode
TYPE: onoff
-LOC: Config.onoff.prefer_direct
+IFDEF: ICAP_CLIENT
+COMMENT: on|off
+LOC: TheICAPConfig.client_username_encode
DEFAULT: off
DOC_START
- Normally Squid tries to use parents for most requests. If you for some
- reason like it to first try going direct and only use a parent if
- going direct fails set this to on.
+ Whether to base64 encode the authenticated client username.
+DOC_END
- 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.
+NAME: icap_service
+TYPE: icap_service_type
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig
+DEFAULT: none
+DOC_START
+ Defines a single ICAP service
+
+ icap_service servicename vectoring_point bypass service_url
+
+ vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
+ This specifies at which point of transaction processing the
+ ICAP service should be activated. *_postcache vectoring points
+ are not yet supported.
+ bypass = 1|0
+ If set to 1, the ICAP service is treated as optional. If the
+ service cannot be reached or malfunctions, Squid will try to
+ ignore any errors and process the message as if the service
+ was not enabled. No all ICAP errors can be bypassed.
+ If set to 0, the ICAP service is treated as essential and all
+ ICAP errors will result in an error page returned to the
+ HTTP client.
+ service_url = icap://servername:port/service
+
+Example:
+icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod
+icap_service service_2 respmod_precache 0 icap://icap2.mydomain.net:1344/respmod
DOC_END
-NAME: strip_query_terms
-TYPE: onoff
-LOC: Config.onoff.strip_query_terms
-DEFAULT: on
+NAME: icap_class
+TYPE: icap_class_type
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig
+DEFAULT: none
DOC_START
- By default, Squid strips query terms from requested URLs before
- logging. This protects your user's privacy.
+ Defines an ICAP service chain. Eventually, multiple services per
+ vectoring point will be supported. For now, please specify a single
+ service per class:
+
+ icap_class classname servicename
+
+Example:
+icap_class class_1 service_1
+icap class class_2 service_1
+icap class class_3 service_3
DOC_END
-NAME: coredump_dir
-TYPE: string
-LOC: Config.coredump_dir
+NAME: icap_access
+TYPE: icap_access_type
+IFDEF: ICAP_CLIENT
+LOC: TheICAPConfig
DEFAULT: none
-DEFAULT_IF_NONE: none
DOC_START
- By default Squid leaves core files in the directory from where
- it was started. If you set 'coredump_dir' to a directory
- that exists, Squid will chdir() to that directory at startup
- and coredump files will be left there.
+ Redirects a request through an ICAP service class, depending
+ on given acls
-NOCOMMENT_START
-# Leave coredumps in the first cache dir
-coredump_dir @DEFAULT_SWAP_DIR@
-NOCOMMENT_END
+ icap_access classname allow|deny [!]aclname...
+
+ The icap_access statements are processed in the order they appear in
+ this configuration file. If an access list matches, the processing stops.
+ For an "allow" rule, the specified class is used for the request. A "deny"
+ rule simply stops processing without using the class. You can also use the
+ special classname "None".
+
+ For backward compatibility, it is also possible to use services
+ directly here.
+Example:
+icap_access class_1 allow all
DOC_END
-NAME: redirector_bypass
+COMMENT_START
+ DNS OPTIONS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: check_hostnames
TYPE: onoff
-LOC: Config.onoff.redirector_bypass
DEFAULT: off
+LOC: Config.onoff.check_hostnames
DOC_START
- When this is 'on', a request will not go through the
- redirector if all redirectors are busy. If this is 'off'
- and the redirector queue grows too large, Squid will exit
- with a FATAL error and ask you to increase the number of
- redirectors. You should only enable this if the redirectors
- are not critical to your caching system. If you use
- redirectors for access control, and you enable this option,
- users may have access to pages they should not
- be allowed to request.
+ For security and stability reasons Squid can check
+ hostnames for Internet standard RFC compliance. If you want
+ Squid to perform these checks turn this directive on.
DOC_END
-NAME: ignore_unknown_nameservers
+NAME: allow_underscore
TYPE: onoff
-LOC: Config.onoff.ignore_unknown_nameservers
DEFAULT: on
+LOC: Config.onoff.allow_underscore
DOC_START
- By default Squid checks that DNS responses are received
- from the same IP addresses they are sent to. If they
- don't match, Squid ignores the response and writes a warning
- message to cache.log. You can allow responses from unknown
- nameservers by setting this option to 'off'.
+ 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.
DOC_END
-NAME: digest_generation
-IFDEF: USE_CACHE_DIGESTS
-TYPE: onoff
-LOC: Config.onoff.digest_generation
-DEFAULT: on
+NAME: cache_dns_program
+TYPE: string
+IFDEF: USE_DNSSERVERS
+DEFAULT: @DEFAULT_DNSSERVER@
+LOC: Config.Program.dnsserver
DOC_START
- This controls whether the server will generate a Cache Digest
- of its contents. By default, Cache Digest generation is
- enabled if Squid is compiled with USE_CACHE_DIGESTS defined.
+ Specify the location of the executable for dnslookup process.
DOC_END
-NAME: digest_bits_per_entry
-IFDEF: USE_CACHE_DIGESTS
+NAME: dns_children
TYPE: int
-LOC: Config.digest.bits_per_entry
+IFDEF: USE_DNSSERVERS
DEFAULT: 5
+LOC: Config.dnsChildren
DOC_START
- This is the number of bits of the server's Cache Digest which
- will be associated with the Digest entry for a given HTTP
- Method and URL (public key) combination. The default is 5.
+ The number of processes spawn to service DNS name lookups.
+ For heavily loaded caches on large servers, you should
+ probably increase this value to at least 10. The maximum
+ is 32. The default is 5.
+
+ You must have at least one dnsserver process.
DOC_END
-NAME: digest_rebuild_period
-IFDEF: USE_CACHE_DIGESTS
-COMMENT: (seconds)
+NAME: dns_retransmit_interval
TYPE: time_t
-LOC: Config.digest.rebuild_period
-DEFAULT: 1 hour
+DEFAULT: 5 seconds
+LOC: Config.Timeout.idns_retransmit
+IFDEF: !USE_DNSSERVERS
DOC_START
- This is the number of seconds between Cache Digest rebuilds.
+ Initial retransmit interval for DNS queries. The interval is
+ doubled each time all configured DNS servers have been tried.
+
DOC_END
-NAME: digest_rewrite_period
-COMMENT: (seconds)
-IFDEF: USE_CACHE_DIGESTS
+NAME: dns_timeout
TYPE: time_t
-LOC: Config.digest.rewrite_period
-DEFAULT: 1 hour
+DEFAULT: 2 minutes
+LOC: Config.Timeout.idns_query
+IFDEF: !USE_DNSSERVERS
DOC_START
- This is the number of seconds between Cache Digest writes to
- disk.
+ DNS Query timeout. If no response is received to a DNS query
+ within this time all DNS servers for the queried domain
+ are assumed to be unavailable.
DOC_END
-NAME: digest_swapout_chunk_size
-COMMENT: (bytes)
-TYPE: b_size_t
-IFDEF: USE_CACHE_DIGESTS
-LOC: Config.digest.swapout_chunk_size
-DEFAULT: 4096 bytes
+NAME: dns_defnames
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: off
+LOC: Config.onoff.res_defnames
DOC_START
- This is the number of bytes of the Cache Digest to write to
- disk at a time. It defaults to 4096 bytes (4KB), the Squid
- default swap page.
+ Normally the RES_DEFNAMES resolver option is disabled
+ (see res_init(3)). This prevents caches in a hierarchy
+ from interpreting single-component hostnames locally. To allow
+ Squid to handle single-component names, enable this option.
DOC_END
-NAME: digest_rebuild_chunk_percentage
-COMMENT: (percent, 0-100)
-IFDEF: USE_CACHE_DIGESTS
-TYPE: int
-LOC: Config.digest.rebuild_chunk_percentage
-DEFAULT: 10
+NAME: dns_nameservers
+TYPE: wordlist
+DEFAULT: none
+LOC: Config.dns_nameservers
DOC_START
- This is the percentage of the Cache Digest to be scanned at a
- time. By default it is set to 10% of the Cache Digest.
+ Use this if you want to specify a list of DNS name servers
+ (IP addresses) to use instead of those given in your
+ /etc/resolv.conf file.
+ On Windows platforms, if no value is specified here or in
+ the /etc/resolv.conf file, the list of DNS name servers are
+ taken from the Windows registry, both static and dynamic DHCP
+ configurations are supported.
+
+ Example: dns_nameservers 10.0.0.1 192.172.0.4
DOC_END
-NAME: chroot
+NAME: hosts_file
TYPE: string
-LOC: Config.chroot_dir
-DEFAULT: none
+DEFAULT: @DEFAULT_HOSTS@
+LOC: Config.etcHostsPath
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.
-DOC_END
+ Location of the host-local IP name-address associations
+ database. Most Operating Systems have such a file on different
+ default locations:
+ - Un*X & Linux: /etc/hosts
+ - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts
+ (%SystemRoot% value install default is c:\winnt)
+ - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts
+ (%SystemRoot% value install default is c:\windows)
+ - Windows 9x/Me: %windir%\hosts
+ (%windir% value is usually c:\windows)
+ - Cygwin: /etc/hosts
-NAME: client_persistent_connections
-TYPE: onoff
-LOC: Config.onoff.client_pconns
-DEFAULT: on
-DOC_NONE
+ The file contains newline-separated definitions, in the
+ form ip_address_in_dotted_form name [name ...] names are
+ whitespace-separated. Lines beginning with an hash (#)
+ character are comments.
-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.
+ The file is checked at startup and upon configuration.
+ If set to 'none', it won't be checked.
+ If append_domain is used, that domain will be added to
+ domain-local (i.e. not containing any dot character) host
+ definitions.
DOC_END
-NAME: persistent_connection_after_error
-TYPE: onoff
-LOC: Config.onoff.error_pconns
-DEFAULT: off
+NAME: dns_testnames
+TYPE: wordlist
+LOC: Config.dns_testname_list
+DEFAULT: none
+DEFAULT_IF_NONE: netscape.com internic.net nlanr.net microsoft.com
DOC_START
- With this directive the use of persistent connections after
- HTTP errors can be disabled. Useful if you have clients
- who fail to handle errors on persistent connections proper.
+ The DNS tests exit as soon as the first site is successfully looked up
+
+ This test can be disabled with the -D command line option.
DOC_END
-NAME: detect_broken_pconn
-TYPE: onoff
-LOC: Config.onoff.detect_broken_server_pconns
-DEFAULT: off
+NAME: append_domain
+TYPE: string
+LOC: Config.appendDomain
+DEFAULT: none
DOC_START
- Some servers have been found to incorrectly signal the use
- of HTTP/1.0 persistent connections even on replies not
- compatible, causing significant delays. This server problem
- has mostly been seen on redirects.
+ Appends local domain name to hostnames without any dots in
+ them. append_domain must begin with a period.
- By enabling this directive Squid attempts to detect such
- broken replies and automatically assume the reply is finished
- after 10 seconds timeout.
+ Be warned there are now Internet names with no dots in
+ them using only top-domain names, so setting this may
+ cause some Internet sites to become unavailable.
+
+Example:
+ append_domain .yourdomain.com
DOC_END
-NAME: balance_on_multiple_ip
+NAME: ignore_unknown_nameservers
TYPE: onoff
-LOC: Config.onoff.balance_on_multiple_ip
+LOC: Config.onoff.ignore_unknown_nameservers
DEFAULT: on
DOC_START
- Some load balancing servers based on round robin DNS have been
- found not to preserve user session state across requests
- to different IP addresses.
-
- By default Squid rotates IP's per request. By disabling
- this directive only connection failure triggers rotation.
+ By default Squid checks that DNS responses are received
+ from the same IP addresses they are sent to. If they
+ don't match, Squid ignores the response and writes a warning
+ message to cache.log. You can allow responses from unknown
+ nameservers by setting this option to 'off'.
DOC_END
-NAME: pipeline_prefetch
+NAME: dns_v4_fallback
TYPE: onoff
-LOC: Config.onoff.pipeline_prefetch
-DEFAULT: off
+DEFAULT: on
+LOC: Config.onoff.dns_require_A
DOC_START
- To boost the performance of pipelined requests to closer
- match that of a non-proxied environment Squid can try to fetch
- up to two requests in parallel from a pipeline.
+ Standard practice with DNS is to lookup either A or AAAA records
+ and use the results if it succeeds. Only looking up the other if
+ the first attempt fails or otherwise produces no results.
- Defaults to off for bandwidth management and access logging
- reasons.
-DOC_END
+ That policy however will cause squid to produce error pages for some
+ servers that advertise AAAA but are unreachable over IPv6.
-NAME: extension_methods
-TYPE: wordlist
-LOC: Config.ext_methods
-DEFAULT: none
-DOC_START
- Squid only knows about standardized HTTP request methods.
- You can add up to 20 additional "extension" methods here.
+ If this is ON squid will always lookup both AAAA and A, using both.
+ If this is OFF squid will lookup AAAA and only try A if none found.
+
+ WARNING: There are some possibly unwanted side-effects with this on:
+ *) Doubles the load placed by squid on the DNS network.
+ *) May negatively impact connection delay times.
DOC_END
-NAME: request_entities
-TYPE: onoff
-LOC: Config.onoff.request_entities
-DEFAULT: off
+NAME: ipcache_size
+COMMENT: (number of entries)
+TYPE: int
+DEFAULT: 1024
+LOC: Config.ipcache.size
+DOC_NONE
+
+NAME: ipcache_low
+COMMENT: (percent)
+TYPE: int
+DEFAULT: 90
+LOC: Config.ipcache.low
+DOC_NONE
+
+NAME: ipcache_high
+COMMENT: (percent)
+TYPE: int
+DEFAULT: 95
+LOC: Config.ipcache.high
DOC_START
- Squid defaults to deny GET and HEAD requests with request entities,
- as the meaning of such requests are undefined in the HTTP standard
- even if not explicitly forbidden.
-
- Set this directive to on if you have clients which insists
- on sending request entities in GET or HEAD requests.
+ The size, low-, and high-water marks for the IP cache.
DOC_END
-NAME: high_response_time_warning
+NAME: fqdncache_size
+COMMENT: (number of entries)
TYPE: int
-COMMENT: (msec)
-LOC: Config.warnings.high_rptm
-DEFAULT: 0
+DEFAULT: 1024
+LOC: Config.fqdncache.size
DOC_START
- If the one-minute median response time exceeds this value,
- Squid prints a WARNING with debug level 0 to get the
- administrators attention. The value is in milliseconds.
+ Maximum number of FQDN cache entries.
DOC_END
-NAME: high_page_fault_warning
-TYPE: int
-LOC: Config.warnings.high_pf
-DEFAULT: 0
+COMMENT_START
+ MISCELLANEOUS
+ -----------------------------------------------------------------------------
+COMMENT_END
+
+NAME: memory_pools
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.mem_pools
DOC_START
- If the one-minute average page fault rate exceeds this
- value, Squid prints a WARNING with debug level 0 to get
- the administrators attention. The value is in page faults
- per second.
+ If set, Squid will keep pools of allocated (but unused) memory
+ available for future use. If memory is a premium on your
+ system and you believe your malloc library outperforms Squid
+ routines, disable this.
DOC_END
-NAME: high_memory_warning
+NAME: memory_pools_limit
+COMMENT: (bytes)
TYPE: b_size_t
-LOC: Config.warnings.high_memory
-DEFAULT: 0
+DEFAULT: 5 MB
+LOC: Config.MemPools.limit
DOC_START
- If the memory usage (as determined by mallinfo) exceeds
- value, Squid prints a WARNING with debug level 0 to get
- the administrators attention.
+ Used only with memory_pools on:
+ memory_pools_limit 50 MB
+
+ If set to a non-zero value, Squid will keep at most the specified
+ limit of allocated (but unused) memory in memory pools. All free()
+ requests that exceed this limit will be handled by your malloc
+ library. Squid does not pre-allocate any memory, just safe-keeps
+ objects that otherwise would be free()d. Thus, it is safe to set
+ memory_pools_limit to a reasonably high value even if your
+ configuration will use less memory.
+
+ If set to zero, Squid will keep all memory it can. That is, there
+ will be no limit on the total amount of memory used for safe-keeping.
+
+ To disable memory allocation optimization, do not set
+ memory_pools_limit to 0. Set memory_pools to "off" instead.
+
+ An overhead for maintaining memory pools is not taken into account
+ when the limit is checked. This overhead is close to four bytes per
+ object kept. However, pools may actually _save_ memory because of
+ reduced memory thrashing in your malloc library.
DOC_END
-NAME: store_dir_select_algorithm
-TYPE: string
-LOC: Config.store_dir_select_algorithm
-DEFAULT: least-load
+NAME: forwarded_for
+COMMENT: on|off
+TYPE: onoff
+DEFAULT: on
+LOC: opt_forwarded_for
DOC_START
- Set this to 'round-robin' as an alternative.
+ If set, Squid will include your system's IP address or name
+ in the HTTP requests it forwards. By default it looks like
+ this:
+
+ X-Forwarded-For: 192.1.2.3
+
+ If you disable this, it will appear as
+
+ X-Forwarded-For: unknown
DOC_END
-NAME: forward_log
-IFDEF: WIP_FWD_LOG
-TYPE: string
+NAME: cachemgr_passwd
+TYPE: cachemgrpasswd
DEFAULT: none
-LOC: Config.Log.forward
+LOC: Config.passwd_list
DOC_START
- Logs the server-side requests.
+ Specify passwords for cachemgr operations.
- This is currently work in progress.
+ Usage: cachemgr_passwd password action action ...
+
+ Some valid actions are (see cache manager menu for a full list):
+ 5min
+ 60min
+ asndb
+ authenticator
+ cbdata
+ client_list
+ comm_incoming
+ config *
+ counters
+ delay
+ digest_stats
+ dns
+ events
+ filedescriptors
+ fqdncache
+ histograms
+ http_headers
+ info
+ io
+ ipcache
+ mem
+ menu
+ netdb
+ non_peers
+ objects
+ offline_toggle *
+ pconn
+ peer_select
+ redirector
+ refresh
+ server_list
+ shutdown *
+ store_digest
+ storedir
+ utilization
+ via_headers
+ vm_objects
+
+ * Indicates actions which will not be performed without a
+ valid password, others can be performed if not listed here.
+
+ To disable an action, set the password to "disable".
+ To allow performing an action without a password, set the
+ password to "none".
+
+ Use the keyword "all" to set the same password for all actions.
+
+Example:
+ cachemgr_passwd secret shutdown
+ cachemgr_passwd lesssssssecret info stats/objects
+ cachemgr_passwd disable all
DOC_END
-NAME: ie_refresh
+NAME: client_db
COMMENT: on|off
TYPE: onoff
-LOC: Config.onoff.ie_refresh
-DEFAULT: off
+DEFAULT: on
+LOC: Config.onoff.client_db
DOC_START
- Microsoft Internet Explorer up until version 5.5 Service
- Pack 1 has an issue with transparent proxies, wherein it
- is impossible to force a refresh. Turning this on provides
- a partial fix to the problem, by causing all IMS-REFRESH
- requests from older IE versions to check the origin server
- for fresh content. This reduces hit ratio by some amount
- (~10% in my experience), but allows users to actually get
- fresh content when they want it. Note because Squid
- cannot tell if the user is using 5.5 or 5.5SP1, the behavior
- of 5.5 is unchanged from old versions of Squid (i.e. a
- forced refresh is impossible). Newer versions of IE will,
- hopefully, continue to have the new behavior and will be
- handled based on that assumption. This option defaults to
- the old Squid behavior, which is better for hit ratios but
- worse for clients using IE, if they need to be able to
- force fresh content.
+ If you want to disable collecting per-client statistics,
+ turn off client_db here.
DOC_END
-NAME: vary_ignore_expire
+NAME: refresh_all_ims
COMMENT: on|off
TYPE: onoff
-LOC: Config.onoff.vary_ignore_expire
DEFAULT: off
+LOC: Config.onoff.refresh_all_ims
DOC_START
- Many HTTP servers supporting Vary gives such objects
- immediate expiry time with no cache-control header
- when requested by a HTTP/1.0 client. This option
- enables Squid to ignore such expiry times until
- HTTP/1.1 is fully implemented.
- WARNING: This may eventually cause some varying
- objects not intended for caching to get cached.
-DOC_END
-
-NAME: sleep_after_fork
-COMMENT: (microseconds)
-TYPE: int
-LOC: Config.sleep_after_fork
-DEFAULT: 0
-DOC_START
- When this is set to a non-zero value, the main Squid process
- sleeps the specified number of microseconds after a fork()
- system call. This sleep may help the situation where your
- system reports fork() failures due to lack of (virtual)
- memory. Note, however, if you have a lot of child
- 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
- rounded to 1000.
-DOC_END
-
-NAME: minimum_expiry_time
-COMMENT: (seconds)
-TYPE: time_t
-LOC: Config.minimum_expiry_time
-DEFAULT: 60 seconds
-DOC_START
- The minimum caching time according to (Expires - Date)
- Headers Squid honors if the object can't be revalidated
- defaults to 60 seconds. In reverse proxy enorinments it
- might be desirable to honor shorter object lifetimes. It
- is most likely better to make your server return a
- meaningful Last-Modified header however. In ESI environments
- where page fragments often have short lifetimes, this will
- often be best set to 0.
-DOC_END
-
-NAME: relaxed_header_parser
-COMMENT: on|off|warn
-TYPE: tristate
-LOC: Config.onoff.relaxed_header_parser
-DEFAULT: on
-DOC_START
- In the default "on" setting Squid accepts certain forms
- of non-compliant HTTP messages where it is unambiguous
- what the sending application intended even if the message
- is not correctly formatted. The messages is then normalized
- to the correct form when forwarded by Squid.
-
- If set to "warn" then a warning will be emitted in cache.log
- each time such HTTP error is encountered.
+ When you enable this option, squid will always check
+ the origin server for an update when a client sends an
+ If-Modified-Since request. Many browsers use IMS
+ requests when the user requests a reload, and this
+ ensures those clients receive the latest version.
- If set to "off" then such HTTP errors will cause the request
- or response to be rejected.
+ By default (off), squid may return a Not Modified response
+ based on the age of the cached version.
DOC_END
-COMMENT_START
- ICAP OPTIONS
- -----------------------------------------------------------------------------
-COMMENT_END
-
-NAME: icap_enable
-TYPE: onoff
-IFDEF: ICAP_CLIENT
+NAME: reload_into_ims
+IFDEF: HTTP_VIOLATIONS
COMMENT: on|off
-LOC: TheICAPConfig.onoff
+TYPE: onoff
DEFAULT: off
+LOC: Config.onoff.reload_into_ims
DOC_START
- If you want to enable the ICAP module support, set this to on.
+ When you enable this option, client no-cache or ``reload''
+ requests will be changed to If-Modified-Since requests.
+ Doing this VIOLATES the HTTP standard. Enabling this
+ feature could make you liable for problems which it
+ causes.
+
+ see also refresh_pattern for a more selective approach.
DOC_END
-NAME: icap_service_failure_limit
+NAME: maximum_single_addr_tries
TYPE: int
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig.service_failure_limit
-DEFAULT: 10
+LOC: Config.retry.maxtries
+DEFAULT: 1
DOC_START
- The limit specifies the number of failures that Squid tolerates
- when establishing a new TCP connection with an ICAP service. If
- the number of failures exceeds the limit, the ICAP service is
- not used for new ICAP requests until it is time to refresh its
- OPTIONS. The per-service failure counter is reset to zero each
- time Squid fetches new service OPTIONS.
+ This sets the maximum number of connection attempts for a
+ host that only has one address (for multiple-address hosts,
+ each address is tried once).
- A negative value disables the limit. Without the limit, an ICAP
- service will not be considered down due to connectivity failures
- between ICAP OPTIONS requests.
+ The default value is one attempt, the (not recommended)
+ maximum is 255 tries. A warning message will be generated
+ if it is set to a value greater than ten.
+
+ Note: This is in addition to the request re-forwarding which
+ takes place if Squid fails to get a satisfying response.
DOC_END
-NAME: icap_service_revival_delay
-TYPE: int
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig.service_revival_delay
-DEFAULT: 180
+NAME: retry_on_error
+TYPE: onoff
+LOC: Config.retry.onerror
+DEFAULT: off
DOC_START
- The delay specifies the number of seconds to wait after an ICAP
- OPTIONS request failure before requesting the options again. The
- failed ICAP service is considered "down" until fresh OPTIONS are
- fetched.
+ If set to on Squid will automatically retry requests when
+ receiving an error response. This is mainly useful if you
+ are in a complex cache hierarchy to work around access
+ control errors.
+DOC_END
- The actual delay cannot be smaller than the hardcoded minimum
- delay of 30 seconds.
+NAME: as_whois_server
+TYPE: string
+LOC: Config.as_whois_server
+DEFAULT: whois.ra.net
+DEFAULT_IF_NONE: whois.ra.net
+DOC_START
+ WHOIS server to query for AS numbers. NOTE: AS numbers are
+ queried only when Squid starts up, not for every request.
DOC_END
-NAME: icap_preview_enable
+NAME: offline_mode
TYPE: onoff
-IFDEF: ICAP_CLIENT
-COMMENT: on|off
-LOC: TheICAPConfig.preview_enable
+LOC: Config.onoff.offline
DEFAULT: off
DOC_START
- Set this to 'on' if you want to enable the ICAP preview
- feature in Squid.
+ Enable this option and Squid will never try to validate cached
+ objects.
DOC_END
-NAME: icap_preview_size
-TYPE: int
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig.preview_size
-DEFAULT: -1
+NAME: uri_whitespace
+TYPE: uri_whitespace
+LOC: Config.uri_whitespace
+DEFAULT: strip
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.
+ What to do with requests that have whitespace characters in the
+ URI. Options:
+
+ strip: The whitespace characters are stripped out of the URL.
+ This is the behavior recommended by RFC2396.
+ deny: The request is denied. The user receives an "Invalid
+ Request" message.
+ allow: The request is allowed and the URI is not changed. The
+ whitespace characters remain in the URI. Note the
+ whitespace is passed to redirector processes if they
+ are in use.
+ encode: The request is allowed and the whitespace characters are
+ encoded according to RFC1738. This could be considered
+ a violation of the HTTP/1.1
+ RFC because proxies are not allowed to rewrite URI's.
+ chop: The request is allowed and the URI is chopped at the
+ first whitespace. This might also be considered a
+ violation.
DOC_END
-NAME: icap_default_options_ttl
-TYPE: int
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig.default_options_ttl
-DEFAULT: 60
+NAME: coredump_dir
+TYPE: string
+LOC: Config.coredump_dir
+DEFAULT: none
+DEFAULT_IF_NONE: none
DOC_START
- The default TTL value for ICAP OPTIONS responses that don't have
- an Options-TTL header.
+ By default Squid leaves core files in the directory from where
+ it was started. If you set 'coredump_dir' to a directory
+ that exists, Squid will chdir() to that directory at startup
+ and coredump files will be left there.
+
+NOCOMMENT_START
+# Leave coredumps in the first cache dir
+coredump_dir @DEFAULT_SWAP_DIR@
+NOCOMMENT_END
DOC_END
-NAME: icap_persistent_connections
-TYPE: onoff
-IFDEF: ICAP_CLIENT
-COMMENT: on|off
-LOC: TheICAPConfig.reuse_connections
-DEFAULT: on
+NAME: chroot
+TYPE: string
+LOC: Config.chroot_dir
+DEFAULT: none
DOC_START
- Whether or not Squid should use persistent connections to
- an ICAP server.
+ 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 may get an
+ error saying that Squid can not open the port.
DOC_END
-NAME: icap_send_client_ip
+NAME: balance_on_multiple_ip
TYPE: onoff
-IFDEF: ICAP_CLIENT
-COMMENT: on|off
-LOC: TheICAPConfig.send_client_ip
+LOC: Config.onoff.balance_on_multiple_ip
DEFAULT: off
DOC_START
- This adds the header "X-Client-IP" to ICAP requests.
+ Modern IP resolvers in squid sort lookup results by preferred access.
+ By default squid will use these IP in order and only rotates to
+ the next listed when the most preffered fails.
+
+ Some load balancing servers based on round robin DNS have been
+ found not to preserve user session state across requests
+ to different IP addresses.
+
+ Enabling this directive Squid rotates IP's per request.
DOC_END
-NAME: icap_send_client_username
+NAME: pipeline_prefetch
TYPE: onoff
-IFDEF: ICAP_CLIENT
-COMMENT: on|off
-LOC: TheICAPConfig.send_client_username
+LOC: Config.onoff.pipeline_prefetch
DEFAULT: off
DOC_START
- This sends authenticated HTTP client username (if available) to
- the ICAP service. The username value is encoded based on the
- icap_client_username_encode option and is sent using the header
- specified by the icap_client_username_header option.
-DOC_END
+ To boost the performance of pipelined requests to closer
+ match that of a non-proxied environment Squid can try to fetch
+ up to two requests in parallel from a pipeline.
-NAME: icap_client_username_header
-TYPE: string
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig.client_username_header
-DEFAULT: X-Client-Username
-DOC_START
- ICAP request header name to use for send_client_username.
+ Defaults to off for bandwidth management and access logging
+ reasons.
DOC_END
-NAME: icap_client_username_encode
-TYPE: onoff
-IFDEF: ICAP_CLIENT
-COMMENT: on|off
-LOC: TheICAPConfig.client_username_encode
-DEFAULT: off
+NAME: high_response_time_warning
+TYPE: int
+COMMENT: (msec)
+LOC: Config.warnings.high_rptm
+DEFAULT: 0
DOC_START
- Whether to base64 encode the authenticated client username.
+ If the one-minute median response time exceeds this value,
+ Squid prints a WARNING with debug level 0 to get the
+ administrators attention. The value is in milliseconds.
DOC_END
-NAME: icap_service
-TYPE: icap_service_type
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig
-DEFAULT: none
+NAME: high_page_fault_warning
+TYPE: int
+LOC: Config.warnings.high_pf
+DEFAULT: 0
DOC_START
- Defines a single ICAP service
-
- icap_service servicename vectoring_point bypass service_url
-
- vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
- This specifies at which point of request processing the ICAP
- service should be plugged in.
- bypass = 1|0
- If set to 1 and the ICAP server cannot be reached, the request will go
- through without being processed by an ICAP server
- service_url = icap://servername:port/service
-
- Note: reqmod_precache and respmod_postcache is not yet implemented
-
-Example:
-icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod
-icap_service service_2 respmod_precache 0 icap://icap2.mydomain.net:1344/respmod
+ If the one-minute average page fault rate exceeds this
+ value, Squid prints a WARNING with debug level 0 to get
+ the administrators attention. The value is in page faults
+ per second.
DOC_END
-NAME: icap_class
-TYPE: icap_class_type
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig
-DEFAULT: none
+NAME: high_memory_warning
+TYPE: b_size_t
+LOC: Config.warnings.high_memory
+DEFAULT: 0 KB
DOC_START
- Defines an ICAP service chain. If there are multiple services per
- vectoring point, they are processed in the specified order.
-
- icap_class classname servicename...
-
-Example:
-icap_class class_1 service_1 service_2
-icap class class_2 service_1 service_3
+ If the memory usage (as determined by mallinfo) exceeds
+ this amount, Squid prints a WARNING with debug level 0 to get
+ the administrators attention.
DOC_END
-NAME: icap_access
-TYPE: icap_access_type
-IFDEF: ICAP_CLIENT
-LOC: TheICAPConfig
-DEFAULT: none
+NAME: sleep_after_fork
+COMMENT: (microseconds)
+TYPE: int
+LOC: Config.sleep_after_fork
+DEFAULT: 0
DOC_START
- Redirects a request through an ICAP service class, depending
- on given acls
-
- icap_access classname allow|deny [!]aclname...
-
- The icap_access statements are processed in the order they appear in
- this configuration file. If an access list matches, the processing stops.
- For an "allow" rule, the specified class is used for the request. A "deny"
- rule simply stops processing without using the class. You can also use the
- special classname "None".
-
- For backward compatibility, it is also possible to use services
- directly here.
-Example:
-icap_access class_1 allow all
+ When this is set to a non-zero value, the main Squid process
+ sleeps the specified number of microseconds after a fork()
+ system call. This sleep may help the situation where your
+ system reports fork() failures due to lack of (virtual)
+ memory. Note, however, if you have a lot of child
+ 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 milliseconds) are
+ rounded to 1000.
DOC_END
EOF
projects / thirdparty / squid.git / blobdiff