Access control lists, or ACLs, are special conditional
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 all three forms, the ACL
statement accepts optional argument -forwarded, which indicates
that the remote IP should be determined from the
X-Forwarded-From IP address (see %a), instead of using the
actual originator IP.
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 (see File inclusion)
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 then being monitored for changes during the runtime. See File-based Conditions, for details.
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.