4.1.2 ACL

Access control lists, or ACLs, are special request matching statements that evaluate to true for requests originating from one of the predefined IP addresses. Access control lists are defined using the ACL section statement, which has three forms: anonymous, file reference, and ACL reference.

In anonymous form, the ACL is a section statement: the keyword is followed by a newline and a list of CIDRs, terminated with End on a separate line. Each line in the list defines a single CIDR enclosed in double quotes. A CIDR consists of a network address (IPv4 or IPv6), optionally followed by slash and network mask length, a decimal number in the range [0,32] for IPv4 and [0,64] for IPv6. For example:

ACL
    "127.0.0.1/8"
    "192.0.2.0/25"
End

For convenience, Include statements can also be used between ACL and End.

In file reference form, the ACL syntax is:

ACL -file "name"

or

ACL -filewatch "name"

Here, name is the name of a disk file with the ACL definition. Its syntax is similar to the contents of anonymous ACL definition, except that CIDRs need not be quoted, and Include statements are not allowed. If the file name is relative, it is looked up in the include directory.

If the -file keyword is used, the file is read at startup and its contents is remembered for the lifetime of the program. It is an error if the file does not exist. Any errors in the file are treated as configuration file errors and cause immediate program termination.

If the -filewatch keyword is used, the file is read at startup and is being monitored for changes during the runtime. Once the file changes, it is re-read and the ACL is reconstructed from its new contents. If the file is removed, the ACL is cleared (which means that it will evaluate to false during request matching), and a file creation monitor is installed. Once the file is re-created, the monitor will wake up, the file will be rescanned and the ACL updated accordingly.

Consequently, when -filewatch form is used, it is OK if the file does not exist at startup. Furthermore, any errors in the file contents are reported, but don’t cause program termination.

On GNU/Linux systems, pound uses inotify kernel API ⁴, which allows it to react immediately on the file system changes. On systems where inotify is not available, pound falls back to periodic checking for changes in file modification time. The interval between two succeeding checks is defined by the WatcherTTL statement (see WatcherTTL).

The third syntax form for ACL statements is ACL reference. As its name implies, the ACL in this form refers to another named ACL, defined elsewhere in the configuration files. Syntactically, it is

ACL "name"

where name is the name of the ACL to refer to. This syntax makes it possible to use a single ACL in multiple places of the configuration file.

Named access control lists are defined at the top level of a configuration file. Syntactically, the definition is similar to anonymous or file reference forms of ACLs as discussed above, except that the keyword ACL is followed on the same line by the name to be assigned to that ACL, in double quotes. Thus the following are valid named ACL declarations:

ACL "secure" -file "aclfile"

ACL "secure" -filewatch "aclfile"

ACL "secure"
    "127.0.0.1/8"
    "192.0.2.0/25"
End

All three examples define a named ACL ‘secure’. The former two read its contents from the disk file aclfile. The latter one provides its definition in the form of a section. This ACL can then be used in any Service appearing after its definition by using the following construct:

ACL "secure"

Consider for example the following service declaration:

Service
    ACL "secure"
    Path -beg "/stat"
    Backend
        ...
    End
End

This service will handle requests whose URL starts with ‘/stat’, if they came from one of the IP addresses mentioned in the access control list with the name ‘secure’. Effectively, this means that the access to that URL is limited to these IP addresses.