12.5 External ACLs
As of Version 2.5, Squid includes a new feature known as external ACLs. These are ACL elements that are implemented in external helper processes. You instruct Squid to write certain information to the helper, which then responds with either OK or ERR. Refer to Section 6.1.3 for a description of the external_acl_type syntax. Here, I'll only discuss the particular external ACL helper programs that come with the Squid source code.
12.5.1 ip_user
./configure enable-external-acl-helpers=ip_user
This helper reads usernames and client IP addresses as input. It checks the two values against a configuration file to decide whether or not the combination is valid. To use this ACL helper, you would add lines like this to squid.conf:
external_acl_type ip_user_helper %SRC %LOGIN
/usr/local/squid/libexec/ip_user -f /usr/local/squid/etc/ip_user.conf
acl AclName external ip_user_helper
%SRC is replaced with the client's IP address and %LOGIN is replaced with the username for each request. The ip_user.conf configuration file has the following format:
ip_addr[/mask] user|@group|ALL|NONE
For example:
127.0.0.1 ALL 192.168.1.0/24 bob 10.8.1.0/24 @lusers 172.16.0.0/16 NONE
This configuration file causes ip_user to return OK for any request coming from 127.0.0.1, for Bob's requests coming from the 192.168.1.0/24 network, for any name in the luser group when the request comes from the 10.8.1.0/24 network, and returns ERR for any request from the 172.16.0.0/16 network. It also returns ERR for any address and username pair that doesn't appear in the list.
12.5.2 ldap_group
./configure enable-external-acl-helpers=ldap_group
This helper determines whether or not a user belongs to a particular LDAP group. You specify the LDAP group names on the acl line. It might look like this in your configuration file:
external_acl_type ldap_group_helper %LOGIN /usr/local/squid/libexec/squid_ldap_group
-b "ou=people,dc=example,dc=com" ldap.example.com
acl AclName external ldap_group_helper GroupRDN ...
Note that you must have the OpenLDAP (http://www.openldap.org) libraries installed on your system to compile the squid_ldap_group helper program.
12.5.3 unix_group
./configure enable-external-acl-helpers=unix_group
This helper looks for usernames in the Unix group database (e.g., /etc/group file). You specify the groups to check on the helper command line as follows:
external_acl_type unix_group_helper %LOGIN
/usr/local/squid/libexec/check_group -g group1 -g group2 ...
acl AclName external unix_group_helper
Alternatively, you can specify groups on the acl line. This allows you to use the same helper for different groups:
external_acl_type unix_group_helper %LOGIN /usr/local/squid/libexec/check_group acl AclName1 external unix_group_helper group1 ... acl AclName2 external unix_group_helper group2 ...
12.5.4 wbinfo_group
./configure enable-external-acl-helpers=wbinfo_group
This helper is a short Perl script that utilizes the wbinfo program from the Samba package. wbinfo is a client for the winbindd daemon. The script expects a single Unix group name following the username on each request. Thus, you must put a group name on the acl line:
external_acl_type wbinfo_group_helper %LOGIN /usr/local/squid/libexec/wbinfo_group.pl acl AclName external wbinfo_group_helper group
12.5.5 winbind_group
./configure enable-external-acl-helpers=winbind_group
This helper, written in C, also queries a winbindd server about group membership of Windows NT usernames. It is based on the winbind helpers for Basic and NTLM authentication. You can specify multiple group names on the acl command line:
external_acl_type winbind_group_helper %LOGIN /usr/local/squid/libexec/wb_check_group acl AclName external winbind_group_helper group1 group2 ...
12.5.6 Write Your Own
The external ACL interface offers a lot of flexibility. Chances are you can use it to implement almost any access control check not supported by the built-in methods. Writing an external ACL is a two-step process. First, you must decide what request information the helper program needs to make a decision. Place the appropriate keywords on an external_acl_type line, along with the pathname to the helper program. For example, if you want to write an external ACL helper that uses the client's IP address, the user's name, and the value of the Host header, you would write something like:
external_acl_type MyAclHelper %SRC %LOGIN %{Host}
/usr/local/squid/libexec/myaclhelper
The second step is to write the myaclhelper program. It must read the request tokens on stdin, make its decision, then write either OK or ERR to stdout. Continuing with the previous example, this Perl script illustrates how to do it:
#!/usr/bin/perl -wl
require 'shellwords.pl';
$|=1;
while (<>) {
($ip,$name,$host) = &shellwords;
if (&valid($ip,$name,$host)) {
print "OK";
} else {
print "ERR";
}
}
sub valid {
my $ip = shift;
my $name = shift;
my $host = shift;
...
}
Refer to Section 6.1.3 for the list of tokens (%SRC, %LOGIN, etc.) that you can pass from Squid to the helper. Note that when a token contains whitespace, Squid wraps it in double quotes. As the example shows, you can use Perl's shellwords library to parse quoted tokens easily.
Of course, to utilize the external ACL, you must reference it in an acl line. The ACL element is a match whenever the external helper returns OK.
The external ACL helper interface allows you to pass additional information from the helper to Squid (on the OK/ERR line). These take the form of keyword=value pairs. For example:
OK user=hank
Currently, the only keywords that Squid knows about are error and user. If the user value is set, Squid uses it in the access.log. The error value isn't currently used by Squid.
