squid-cache.org

	This option defines external acl classes using a helper program
	to look up the status

	  external_acl_type name [options] FORMAT /path/to/helper [helper arguments]

	Options:

	  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)

	  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 is for no grace period)

	  cache=n	The maximum number of entries in the result cache. The
			default limit is 262144 entries.  Each cache entry usually
			consumes at least 256 bytes. Squid currently does not remove
			expired cache entries until the limit is reached, so a proxy
			will sooner or later reach the limit. The expanded FORMAT
			value is used as the cache key, so if the details in FORMAT
			are highly variable, a larger cache may be needed to produce
			reduction in helper load.

	  children-max=n
			Maximum number of acl helper processes spawned to service
			external acl lookups of this type. (default 5)

	  children-startup=n
			Minimum number of acl helper processes to spawn during
			startup and reconfigure to service external acl lookups
			of this type. (default 0)

	  children-idle=n
			Number of acl helper processes to keep ahead of traffic
			loads. Squid will spawn this many at once whenever load
			rises above the capabilities of existing processes.
			Up to the value of children-max. (default 1)

	  concurrency=n	concurrency level per process. Only used with helpers
			capable of processing more than one query at a time.

	  queue-size=N  The queue-size option sets the maximum number of
			queued requests. A request is queued when no existing
			helper can accept it due to concurrency limit and no
			new helper can be started due to children-max limit.
			If the queued requests exceed queue size, the acl is
			ignored. The default value is set to 2*children-max.

	  protocol=2.5	Compatibility mode for Squid-2.5 external acl helpers.

	  ipv4 / ipv6	IP protocol used to communicate with this helper.
			The default is to auto-detect IPv6 and use it when available.


	FORMAT is a series of %macro codes. See logformat directive for a full list
	of the accepted codes. Although note that at the time of any external ACL
	being tested data may not be available and thus some %macro expand to '-'.

	In addition to the logformat codes; when processing external ACLs these
	additional macros are made available:

	  %ACL		The name of the ACL being tested.

	  %DATA		The ACL arguments specified in the referencing config
			'acl ... external' line, separated by spaces (an
			"argument string"). see acl external.

			If there are no ACL arguments %DATA expands to '-'.

			If you do not specify a DATA macro inside FORMAT,
			Squid automatically appends %DATA to your FORMAT.
			Note that Squid-3.x may expand %DATA to whitespace
			or nothing in this case.

			By default, Squid applies URL-encoding to each ACL
			argument inside the argument string. If an explicit
			encoding modifier is used (e.g., %#DATA), then Squid
			encodes the whole argument string as a single token
			(e.g., with %#DATA, spaces between arguments become
			%20).

	If SSL is enabled, the following formatting codes become available:

	  %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_CERT_xx	SSL User certificate issuer attribute xx


	NOTE: all other format codes accepted by older Squid versions
		are deprecated.


	General request syntax:

	  [channel-ID] FORMAT-values


	FORMAT-values consists of transaction details expanded with
	whitespace separation per the config file FORMAT specification
	using the FORMAT macros listed above.

	Request values sent to the helper are URL escaped to protect
	each value in requests against whitespaces.

	If using protocol=2.5 then the request sent to the helper is not
	URL escaped to protect against whitespace.

	NOTE: protocol=3.0 is deprecated as no longer necessary.

	When using the concurrency= option the protocol is changed by
	introducing a query channel tag in front of the request/response.
	The query channel tag is a number between 0 and concurrency-1.
	This value must be echoed back unchanged to Squid as the first part
	of the response relating to its request.


	The helper receives lines expanded per the above format specification
	and for each input line returns 1 line starting with OK/ERR/BH result
	code and optionally followed by additional keywords with more details.


	General result syntax:

	  [channel-ID] result keyword=value ...

	Result consists of one of the codes:

	  OK
		the ACL test produced a match.

	  ERR
		the ACL test does not produce a match.

	  BH
		An internal error occurred in the helper, preventing
		a result being identified.

	The meaning of 'a match' is determined by your squid.conf
	access control configuration. See the Squid wiki for details.

	Defined keywords:

	  user=		The users name (login)

	  password=	The users password (for login= cache_peer option)

	  message=	Message describing the reason for this response.
			Available as %o in error pages.
			Useful on (ERR and BH results).

	  tag=		Apply a tag to a request. Only sets a tag once,
			does not alter existing tags.

	  log=		String to be logged in access.log. Available as
			%ea in logformat specifications.

	  clt_conn_tag= Associates a TAG with the client TCP connection.
			Please see url_rewrite_program related documentation
			for this kv-pair.

	Any keywords may be sent on any response whether OK, ERR or BH.

	All response keyword values need to be a single token with URL
	escaping, or enclosed in double quotes (") and escaped using \ on
	any double quotes or \ characters within the value. The wrapping
	double quotes are removed before the value is interpreted by Squid.
	\r and \n are also replace by CR and LF.

	Some example key values:

		user=John%20Smith
		user="John Smith"
		user="J. \"Bob\" Smith"