Squid_ The Definitive Guide - Duane Wessels [46]
The external_acl_type directive defines a new external ACL type. Here's the general syntax:
external_acl_type type-name [options] format
helper-command
type-name is a user-defined string. You'll also use it in an acl line to reference this particular helper.
Squid currently supports the following options:
ttl= n
The amount of time, in seconds, to cache the result for values that are a match. The default is 3600 seconds, or 1 hour.
negative_ttl= n
The amount of time, in seconds, to cache the result for values that aren't a match. The default is 3600 seconds, or 1 hour.
concurrency= n
The number of helper processes to spawn. The default is 5.
cache= n
The maximum number of results to cache. The default is 0, which doesn't limit the cache size.
format is one or more keywords that begin with the % character. Squid currently supports the following format tokens:
%LOGIN
The username, taken from proxy authentication credentials.
%IDENT
The username, taken from an RFC 1413 ident query.
%SRC
The IP address of the client.
%DST
The IP address of the origin server.
%PROTO
The transfer protocol (e.g., HTTP, FTP, etc.).
%PORT
The origin server TCP port number.
%METHOD
The HTTP request method.
%{Header}
The value of an HTTP request header; for example, %{User-Agent} causes Squid to send strings like this to the authenticator:
"Mozilla/4.0 (compatible; MSIE 6.0; Win32)"
%{Hdr:member}
Selects certain members of list-based HTTP headers, such as Cache-Control; for example, given this HTTP header:
X-Some-Header: foo=xyzzy, bar=plugh, foo=zoinks
and the token %{X-Some-Header:foo}, Squid sends this string to the external ACL process:
foo=xyzzy, foo=zoinks
%{Hdr:; member}
The same as %{Hdr:member }, except that the ; character is the list separator. You can use any nonalphanumeric character as the separator.
helper-command is the command that Squid spawns for the helper. You may include command arguments here as well. For example, the entire command may be something like:
/usr/local/squid/libexec/my-acl-prog.pl -X -5 /usr/local/squid/etc/datafile
Putting all these together results in a long line. Squid's configuration file doesn't support the backslash line-continuation technique shown here, so remember that all these must go on a single line:
external_acl_type MyAclType cache=100 %LOGIN %{User-Agent} \
/usr/local/squid/libexec/my-acl-prog.pl -X -5 \
/usr/local/squid/share/usernames \
/usr/local/squid/share/useragents
Now that you know how to define an external ACL, the next step is to write an acl line that references it. This is relatively straightforward. The syntax is as follows:
acl acl-name external type-name [args ...]
Here is a simple example:
acl MyAcl external MyAclType
Squid accepts any number of optional arguments following the type-name. These are sent to the helper program for each request, after the expanded tokens. See my description of the unix_group helper in Section 12.5.3 for an example of this feature.
Dealing with Long ACL Lists
ACL lists can sometimes be very long. Such lists are awkward to maintain inside the squid.conf file. Also, you may need to generate Squid ACL lists automatically from other sources. In these cases, you'll be happy to know that you can include ACL lists from external files. The syntax is as follows:
acl name "filename"
The double quotes here instruct Squid to open filename and assign its contents to the ACL. For example, instead of this:
acl Foo BadClients 1.2.3.4 1.2.3.5 1.2.3.6 1.2.3.7 1.2.3.9 ...
you can do this:
acl Foo BadClients "/usr/local/squid/etc/BadClients"
and put the IP addresses into the BadClients file:
1.2.3.4
1.2.3.5
1.2.3.6
1.2.3.7
1.2.3.9
...
Your file may include comments that begin with a # character. Note that each entry in the file must be on a separate line. Whereas a space character delimits values on an acl line,