Access Control List (ACL)

An Access Control List (ACL) is a set of rules that controls which visitors to your web site are allowed to use a particular web gadget. You can use an ACL to allow or deny visitors based on their IP address, their host name, their country, and so on.

Most web gadgets will have a configuration option available that lets you specify the name of an ACL file to use. A web gadget will only make use of one ACL file, but they can all share the same one.

An ACL file is a plain text file. It could be named anything you'd like, but we recommend naming it ".htacl" so that people can't view it directly with their web browser (all files that start with ".ht" are protected from viewing by the web server).

Let's start by looking at a sample ACL file:

# Banned IPs and Networks message Sorry, we've had too much spam from your network allow ip=192.168.1.56 deny ip=192.168.1.0/24 deny ip=10.1.2.0/24 # Banned countries message Sorry, we've had too many fraudulent orders from your country deny country=NG

The first thing to note is that blank lines, or lines that begin with a hash mark, are ignored. The hash mark provides a way for you to embed comments in the file.

When an ACL file is used, the web gadget checks each line until it finds the first one that matches the current visitor to your site, or it reaches the end of the file. The default action if no matching rules are found is to allow the visitor to proceed.

The message command sets the error message that will be displayed for any subsequent rules that trigger. The initial value of the error message is simply "Permission denied." and that's what will be displayed unless you set it to something else. You can change the message as many times as you'd like throughtout the ACL file.

The deny and allow commands are used to deny or allow the use of the web gadget by the current visitor. These commands are normally followed by one or more values to check in the form of keyword=value (you can reverse the test by changing the '=' sign to '!='). The keywords you can use are as follows:

ip	This tests the visitor's IP address. The value must be an IP address with an optional netmask.
host	This tests the visitor's host name, which is determined by first performing a reverse lookup on the IP address. If the value begins with a dot, then it checks to see if the hostname ends with the value, otherwise it must match exactly.
country	This tests the visitor's two character countrycode, which is determined by doing a GeoIP lookup on the IP address. Exmples: CA for Canada, JP for Japan, etc.
region	This tests the visitor's region, which is determined by doing a GeoIP lookup on the IP address. Examples: BC for British Columbia, CA for California, etc.
city	This tests the visitor's city name, which is determined by doing a GeoIP lookup on the IP address. Examples: Victoria, Paris, etc.
platform	This tests the visitor's computer platform, which is determined from their browser details. Examples: Win32, Win98, MacOSX, MacPPC, Linux, etc.
browser	This tests the visitor's browser name. Examples: Firefox, Safari, etc.

You can combine multiple tests on the same line by separating them with commas, in which case they must ALL match for the rule to trigger. For example, allowing visitors just because their city is 'Victoria' doesn't make much sense, since there are many Victorias around the world. If the goal is to always allow visitors who are connecting from Victoria, BC, Canada then you would use a rule like this:

allow country=CA,region=BC,city=Victoria

A line with deny or allow on it but nothing else will always match the current visitor and deny or allow them. This can be used to have a default action. If the end of the ACL is reached without a match, the default action is allow.