Squid configuration directive cache_peer

Available in: 3.HEAD   3.4   3.3   3.2   2.7   3.1   3.0   2.6  

History:

Changes in 3.HEAD cache_peer

New standby=N option to retain a set of N open and unused connections to the peer at virtually all times to reduce TCP handshake delays.

These connections differ from HTTP persistent connections in that they have not been used for HTTP messaging (and may never be). They may be turned into persistent connections after their first use subject to the same keep-alive critera any HTTP connection is checked for.

Changes in 3.4 cache_peer

idle= not yet ported from 2.7

monitorinterval= not yet ported from 2.6

monitorsize= not yet ported from 2.6

monitortimeout= not yet ported from 2.6

monitorurl= not yet ported from 2.6

Changes in 3.3 cache_peer

idle= not yet ported from 2.7

monitorinterval= not yet ported from 2.6

monitorsize= not yet ported from 2.6

monitortimeout= not yet ported from 2.6

monitorurl= not yet ported from 2.6

For older versions see the linked page above

Configuration Details:

Option Name:cache_peer
Replaces:
Requires:
Default Value:none
Suggested Config:

	To specify other caches in a hierarchy, use the format:
	
		cache_peer hostname type http-port icp-port [options]
	
	For example,
	
	#                                        proxy  icp
	#          hostname             type     port   port  options
	#          -------------------- -------- ----- -----  -----------
	cache_peer parent.foo.net       parent    3128  3130  default
	cache_peer sib1.foo.net         sibling   3128  3130  proxy-only
	cache_peer sib2.foo.net         sibling   3128  3130  proxy-only
	cache_peer example.com          parent    80       0  default
	cache_peer cdn.example.com      sibling   3128     0  
	
	      type:	either 'parent', 'sibling', or 'multicast'.
	
	proxy-port:	The port number where the peer accept HTTP requests.
			For other Squid proxies this is usually 3128
			For web servers this is usually 80
	
	  icp-port:	Used for querying neighbor caches about objects.
			Set to 0 if the peer does not support ICP or HTCP.
			See ICP and HTCP options below for additional details.
	
	
	==== ICP OPTIONS ====
	
	You MUST also set icp_port and icp_access explicitly when using these options.
	The defaults will prevent peer traffic using ICP.
	
	
	no-query	Disable ICP queries to this neighbor.
	
	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.
	
	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.
	
	
	==== HTCP OPTIONS ====
	
	You MUST also set htcp_port and htcp_access explicitly when using these options.
	The defaults will prevent peer traffic using HTCP.
	
	
	htcp		Send HTCP, instead of ICP, queries to the neighbor.
			You probably also want to set the "icp-port" to 4827
			instead of 3130. This directive accepts a comma separated
			list of options described below.
	
	htcp=oldsquid	Send HTCP to old Squid versions (2.5 or earlier).
	
	htcp=no-clr	Send HTCP to the neighbor but without
			sending any CLR requests.  This cannot be used with
			only-clr.
	
	htcp=only-clr	Send HTCP to the neighbor but ONLY CLR requests.
			This cannot be used with no-clr.
	
	htcp=no-purge-clr
			Send HTCP to the neighbor including CLRs but only when
			they do not result from PURGE requests.
	
	htcp=forward-clr
			Forward any HTCP CLR requests this proxy receives to the peer.
	
	
	==== PEER SELECTION METHODS ====
	
	The default peer selection method is ICP, with the first responding peer
	being used as source. These options can be used for better load balancing.
	
	
	default		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 methods.
			If specified more than once, only the first is used.
	
	round-robin	Load-Balance parents which should be used in a round-robin
			fashion in the absence of any ICP queries.
			weight=N can be used to add bias.
	
	weighted-round-robin
			Load-Balance 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.
			weight=N can be used to add bias.
	
	carp		Load-Balance 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.
	
	userhash	Load-balance parents based on the client proxy_auth or ident username.
	
	sourcehash	Load-balance parents based on the client source IP.

	multicast-siblings
			To be used only for cache peers of type "multicast".
			ALL members of this multicast group have "sibling"
			relationship with it, not "parent".  This is to a multicast
			group when the requested object would be fetched only from
			a "parent" cache, anyway.  It's useful, e.g., when
			configuring a pool of redundant Squid proxies, being
			members of the same multicast group.
	
	
	==== PEER SELECTION OPTIONS ====
	
	weight=N	use 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.
	
	basetime=N	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.
	
	ttl=N		Specify a TTL to use when sending multicast 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.
	
	no-delay	To prevent access to this neighbor from influencing the
			delay pools.
	
	digest-url=URL	Tell Squid to fetch the cache digest (if digests are
			enabled) for this host from the specified URL rather
			than the Squid default location.
	
	
	==== CARP OPTIONS ====
	
	carp-key=key-specification
			use a different key than the full URL to hash against the peer.
			the key-specification is a comma-separated list of the keywords			
			scheme, host, port, path, params
			Order is not important.
	
	==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
	
	originserver	Causes this parent to be contacted as an origin server.
			Meant to be used in accelerator setups when the peer
			is a web server.
	
	forceddomain=name
			Set the Host header of requests forwarded to this peer.
			Useful in accelerator setups where the server (peer)
			expects a certain domain name but clients may request
			others. ie example.com or www.example.com
	
	no-digest	Disable request of cache digests.
	
	no-netdb-exchange
			Disables requesting ICMP RTT database (NetDB).
	
	
	==== AUTHENTICATION OPTIONS ====
	
	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 %%.
	
	login=PASSTHRU
			Send login details received from client to this peer.
			Both Proxy- and WWW-Authorization headers are passed
			without alteration to the peer.
			Authentication is not required by Squid for this to work.
			
			Note: This will pass any form of authentication but
			only Basic auth will work through a proxy unless the
			connection-auth options are also used.

	login=PASS	Send login details received from client to this peer.
			Authentication is not required by this option.
			
			If there are no client-provided authentication headers
			to pass on, but username and password are available
			from an external ACL user= and password= result tags
			they may be sent instead.
			
			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
	
	login=*:password
			Send 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.
	
	login=NEGOTIATE
			If this is a personal/workgroup proxy and your parent
			requires a secure proxy authentication.
			The first principal from the default keytab or defined by
			the environment variable KRB5_KTNAME will be used. 
	
			WARNING: The connection may transmit requests from multiple
			clients. Negotiate often assumes end-to-end authentication
			and a single-client. Which is not strictly true here.
	
	login=NEGOTIATE:principal_name
			If this is a personal/workgroup proxy and your parent
			requires a secure proxy authentication. 
			The principal principal_name from the default keytab or
			defined by the environment variable KRB5_KTNAME will be
			used.
	
			WARNING: The connection may transmit requests from multiple
			clients. Negotiate often assumes end-to-end authentication
			and a single-client. Which is not strictly true here.
	
	connection-auth=on|off
			Tell Squid that this peer does or not support Microsoft
			connection oriented authentication, and any such
			challenges received from there should be ignored.
			Default is auto to automatically determine the status
			of the peer.
	
	
	==== SSL / HTTPS / TLS OPTIONS ====
	
	ssl		Encrypt connections to this peer with SSL/TLS.
	
	sslcert=/path/to/ssl/certificate
			A client SSL certificate to use when connecting to
			this peer.
	
	sslkey=/path/to/ssl/key
			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.
	
	sslversion=1|2|3|4|5|6
			The SSL version to use when connecting to this peer
				1 = automatic (default)
				2 = SSL v2 only
				3 = SSL v3 only
				4 = TLS v1.0 only
				5 = TLS v1.1 only
				6 = TLS v1.2 only
	
	sslcipher=...	The list of valid SSL ciphers to use when connecting
			to this peer.
	
	ssloptions=... 	Specify various SSL implementation options:

			    NO_SSLv2    Disallow the use of SSLv2
			    NO_SSLv3    Disallow the use of SSLv3
			    NO_TLSv1    Disallow the use of TLSv1.0
			    NO_TLSv1_1  Disallow the use of TLSv1.1
			    NO_TLSv1_2  Disallow the use of TLSv1.2
			    SINGLE_DH_USE
				      Always create a new key when using
				      temporary/ephemeral DH key exchanges
			    ALL       Enable various bug workarounds
				      suggested as "harmless" by OpenSSL
				      Be warned that this reduces SSL/TLS
				      strength to some attacks.

			See the OpenSSL SSL_CTX_set_options documentation for a
			more complete list.
	
	sslcafile=... 	A file containing additional CA certificates to use
			when verifying the peer certificate.
	
	sslcapath=...	A directory containing additional CA certificates to
			use when verifying the peer certificate.
	
	sslcrlfile=... 	A certificate revocation list file to use when
			verifying the peer certificate.
	
	sslflags=...	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
	
	ssldomain= 	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.
	
	front-end-https
			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.
	
	
	==== GENERAL OPTIONS ====
	
	connect-timeout=N
			A peer-specific connect timeout.
			Also see the peer_connect_timeout directive.
	
	connect-fail-limit=N
			How many times connecting to a peer must fail before
			it is marked as down. Standby connection failures
			count towards this limit. Default is 10.
	
	allow-miss	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.
	
	max-conn=N 	Limit the number of concurrent connections the Squid
			may open to this peer, including already opened idle
			and standby connections. There is no peer-specific
			connection limit by default.
	
			A peer exceeding the limit is not used for new
			requests unless a standby connection is available.
	
			max-conn currently works poorly with idle persistent
			connections: When a peer reaches its max-conn limit,
			and there are idle persistent connections to the peer,
			the peer may not be selected because the limiting code
			does not know whether Squid can reuse those idle
			connections.
	
	standby=N	Maintain a pool of N "hot standby" connections to an
			UP peer, available for requests when no idle
			persistent connection is available (or safe) to use.
			By default and with zero N, no such pool is maintained.
			N must not exceed the max-conn limit (if any).
	
			At start or after reconfiguration, Squid opens new TCP
			standby connections until there are N connections
			available and then replenishes the standby pool as
			opened connections are used up for requests. A used
			connection never goes back to the standby pool, but
			may go to the regular idle persistent connection pool
			shared by all peers and origin servers.
	
			Squid never opens multiple new standby connections
			concurrently.  This one-at-a-time approach minimizes
			flooding-like effect on peers. Furthermore, just a few
			standby connections should be sufficient in most cases
			to supply most new requests with a ready-to-use
			connection.
	
			Standby connections obey server_idle_pconn_timeout.
			For the feature to work as intended, the peer must be
			configured to accept and keep them open longer than
			the idle timeout at the connecting Squid, to minimize
			race conditions typical to idle used persistent
			connections. Default request_timeout and
			server_idle_pconn_timeout values ensure such a
			configuration.
	
	name=xxx	Unique name for the peer.
			Required if you have multiple peers on the same host
			but different ports.
			This name can be used in cache_peer_access and similar
			directives to dentify the peer.
			Can be used by outgoing access controls through the
			peername ACL type.
	
	no-tproxy	Do not use the client-spoof TPROXY support when forwarding
			requests to this peer. Use normal address selection instead.
			This overrides the spoof_client_ip ACL.
	
	proxy-only	objects fetched from the peer will not be stored locally.
	

 

Back

Search

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors