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@groupALLNONE 

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.