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"