ACL File Syntax

An ACL file is a text file containing one ACL or more. All ACL files must follow a specific format and syntax. All ACL files must begin with the version number they use. There can be only one version line and it can appear after any comment lines. For example:

You can include comments in the file by beginning the comment line with the pound (#) sign.

Each ACL in the file begins with a statement that defines its type. ACLs can follow one of three types:

• Path ACLs specify an absolute path to the resource they affect.
• URI (Uniform Resource Indicator) ACLs specify a directory or file.
• Named ACLs specify a name that is referenced in resources in the OBJ.CONF file. The server comes with a default named resource that allows read access to anyone and write access to users in the local database or LDAP directory. Even though you can create a named ACL from the Server Preference forms, you must manually reference the named ACLs with resources in the OBJ.CONF file.

The type line begins with the letters acl and then includes the type information in double quotation marks followed by a semicolon. Each type information for all ACLs must be a unique name, even among different ACL files. The following lines are examples of several different types of ACLs:

After you define the type of ACL, you can have one or more statements that define the method used with the ACL (authentication statements) and the people and computers who are allowed or denied access (authorization statements). The following sections describe the syntax for these statements.

Authentication Statements

ACLs can optionally specify the authentication method the server must use when processing the ACL. There are two general methods:

• Basic requires users to enter a username and password before accessing a resource.
• SSL requires the user to have a client certificate. For this method to work, the Web server must have encryption turned on.

By default, the server uses the basic method for any ACL that doesn't specify a method. You can change the default setting by editing the following line in the MAGNUS.CONF file:

Each authenticate line must specify what list (users, groups, or both) the server should use when authenticating users. The following authentication statement, which would appear after the ACL type line, specifies basic authentication with users matched to individual users in the database or directory:

The following example uses SSL as the authentication method for users and groups:

Any allow or deny statements must match the lists you specify in the authenticate line. If the line says authenticate (user), the allow or deny line must also specify users. The following example allows any user whose username begins with the letters sales:

If the last line was changed to group = sales, then the ACL would fail because there are no groups in the user lists.

Authorization Statements

Each ACL entry can include one or more authorization statements, which specify who is allowed or denied access to a server resource. Use the following syntax when writing authorization statements:

Start each line with either allow or deny. It's usually a good idea to deny access to everyone in the first rule or command you enter and then specifically allow access for users, groups, or computers in subsequent rules. This is because of the hierarchy of rules.

For example, if you allow anyone access to a directory called MY_STUFF, then you have a subdirectory MY_STUFF/PERSONAL that allows access to a few users. The access control on the subdirectory won't work because anyone allowed access to the MY_STUFF directory will also be allowed access to the MY_STUFF/PERSONAL directory. To prevent this, create a rule for the subdirectory that first denies access to anyone and then allows it for the few users who need access.

However, in some cases, if you set the default ACL to deny access to everyone, then your other ACL rules don't need a Deny All rule.

The following line denies access to everyone:

Hierarchy of Authorization Statements

ACLs have a hierarchy that depends on the resource. For example, if the server receives a request for the document (URI) /MY_STUFF/WEB/PRESENTATION.HTML, the server first looks for an ACL that matches the file type or any other wildcard pattern that matches the request, then it looks for one on the directory, and finally it looks for an ACL on the URI. If there is more than one ACL that matches, the server uses the last statement that matches.

However, if you use an absolute statement, then the server stops looking for other matches and uses the ACL containing the absolute statement. If you have two absolute statements for the same resource, the server uses the first one in the file and stops looking for other resources that match.

For example, using the ACL hierarchy with the request for the document
/MY_STUFF/WEB/PRESENTATION.HTML, you could have an absolute ACL that restricts access to the file type *.HTML then the server would use that ACL instead of looking for one that matches the URI or the path.

Attribute Qualifier Expressions

Attribute qualifier expressions define who is allowed or denied access based on their username, group name, hostname, or IP address. The following lines are examples of allowing access to different people or computers:

user = "anyone"

user = "smith*"

group = "sales"

dns = "*.organization.com"

dns = "*.organization.com" or "*.accounting_mail.com"

ip = "198.*"

You can also restrict access to your server by time of day (based on the local time on the server) by using the timeofday attribute qualifier. For example, you can use the timeofday attribute qualifier to restrict access to certain users during specific hours.

Use a 24-hour clock to specify times (for example, use 0400 to specify 4 a.m. or 2230 for 10:30 p.m.).

The following example restricts access to a group of users called Guests between 8:00 a.m. and 4:59 p.m.

You can also restrict access by day of the week. Use the following three-letter abbreviations to specify days of the week: Sun, Mon, Tue, Wed Thu, Fri, and Sat.

The following statement allows access for users in the Premium group any day and any time. Users in the Discount group get access all day on weekends and on weekdays anytime except 8:00 a.m. to 4:59 p.m.

Operators for Expressions

You can use various operators in attribute qualifier expressions. You can use parentheses to delineate the order of precedence of the operators. With user, group, dns, and ip qualifiers, you can use the following operators:

and

or

not

= (equals)

!= (not equal to)

With timeofday and dayofweek qualifiers, you can use the following additional operators:

> (greater than)

< (less than)

>= (greater than or equal to)

<= (less than or equal to)

Default ACL File

After installing the server, it uses the default settings in the file SERVER_ROOT/HTTPACL/GENERATED.HTTPS-SERVERID.ACL.

There is also a file called GENWORK.HTTPS-SERVERID.ACL that is a working copy that the server uses until you save and apply your changes when working with the user interface. When editing the ACL file, you might want to work in the GENWORK file and then use Server Preferences to save and apply the changes.

The following text is from the default file:

The default ACL file is referenced in MAGNUS.CONF as follows:

You can reference multiple ACL files in MAGNUS.CONF and then use their ACLs for resources in OBJ.CONF. However, the server uses only the first ACL file with the Web Publisher and with evaluation of access control for objects that don't have specific ACLs listed in OBJ.CONF. If you're using the Server Preference form to do some access control, the first ACL file in MAGNUS.CONF should point to the file GENERATED.HTTPS-SERVERID.ACL. See Referencing ACL Files in OBJ.CONF for more information.

General Syntax Rules

Input strings can contain the following characters:

• Letters A through Z
• Numbers 0 through 9
• Period (.) and underscore (_)

If you use any other characters, use double quotation marks (" ") around the characters.

A single statement can be placed on its own line and be terminated with a semicolon. Multiple statements are placed within braces. A list of items must be separated by commas and enclosed in double quotation marks.