Squid configuration directive external_acl_type
- Changes to external_acl_type in Squid-4:
New parameter queue-size= to set the maximum number of queued requests.
New parameter on-persistent-overload= to set the action taken when the helper queue is overloaded.
Format field updated to accept any logformat %macro code.
The optional acl-value fields in this helper input now expand to a dash ('-') if the %DATA macro is not specified explicitly.
- Changes to external_acl_type in Squid-3.5:
New format code %ssl::>sni to send SSL client SNI.
New format code %ssl::<cert_subject to send SSL server certificate DN.
New format code %ssl::<cert_issuer to send SSL server certificate issuer DN.
New format code %un to send any available user name (requires 3.5.7 or later).
New response kv-pair clt_conn_tag= to associates a given tag with the client TCP connection.
- Changes to external_acl_type in Squid-3.4:
Deprecated protocol=3.0 option. No longer necessary.
New result code BH to signal helper internal errors
- Changes to external_acl_type in Squid-3.3:
%ACL format tag ported from 2.6. Sends the name of ACL being tested to the external helper.
%DATA format tag ported from 2.6. Inserts the ACL arguments into a particular location of the helper input instead of at the end of the line.
For older versions than 3.3 see the linked pages above
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 formating 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"
- About Squid
- Why Squid?
- Squid Developers
- How to Donate
- How to Help Out
- Getting Squid
- Squid Source Packages
- Squid Deployment Case-Studies
- Squid Software Foundation
- FAQ and Wiki
- Guide Books:
- Security Advisories
- Bugzilla Database
- Mailing lists
- Contacting us
- Commercial services
- Project Sponsors
- Squid-based products
- Developer Resources
- Related Writings
- Related Software:
- Squid Artwork