Creating .nsconfig files on Web Advantage

Creating and using .nsconfig files with Web Advantage

The Web Advantage server has been configured so that it will read and apply directives contained in a file called .nsconfig (pronounced "dot en es config") which should be placed in the document root directory of the public server to control access to directories under this root. To control access to CGI scripts, you need a separate access control file for the cgi-bin directory. These directives allow you to restrict access to portions of your content based on source hostname/address or username/password. (Directives in .nsconfig which allow access will not override corresponding deny directives in obj.conf).

The syntax and semantics of directives to be placed in .nsconfig files is explained next. (Before you read on, please check the Netscape reference Understanding Wildcards for complete information on wildcards. In the discussion below, we will use the simple wildcard * only. This pattern matches 0 or more of any characters. More complicated patterns are permitted as described in the reference.)

File Specifications and Directives in the .nsconfig File

Each set of commands is of the form

<Files PATTERN >
directive1 directive2 ... </Files>

and one of these groups is termed a "Files set." There can be multiple "Files sets" in a .nsconfig file. Thus a sample .nsconfig file has the form

<Files *> directive1 </Files>

<Files foo*.html> directive2 </Files>

<Files dir1/*> directive3 </Files>

<Files dir1/dir2/*> directive4 </Files>

The "Files" specification line says to apply the subsequent directive (s) to the filesystem pathnames specified by PATTERN. PATTERN may include wildcards as described in the reference. When a PATTERN is evaulated, it is first prefixed by the absolute (Unix) pathname of the directory containing the .nsconfig file. If the PATTERN contains a directory, the subsequent directives are applied recursively. Thus the specification Files * will apply the subsequent directives recursively to all directories below the document root (or cgi-bin directory). The specification Files foo*.html will apply the subsequent directives to all files in the document root directory whose name matches the pattern foo*.html. (i.e. start with foo and end with .html). If dir1 is a subdirectory of the document root, the specification Files dir1/* in the document root .nsconfig file will apply subsequent directives to all files and directories under dir1.

Restricting Based on Hostname/IP Address

The directives used to restrict access based on source address or host name are of the form

RestrictAccess type=allow | deny dns=HOSTPATTERN ip=IPPATTERN

where the notation "|" means choose one or the other of the terms joined by the "|", HOSTPATTERN is a domain name specification, possibly with wildcards, e.g. *.foo.com, IPPATTERN is an ip address specification possibly with wildcards, e.g. 128.22.* for all hosts in network 128.22.

For example,

RestrictAccess type=deny dns=*.foo.com

denies access to all hosts in domain foo.com.

The order in which Files specifications and directives are given in the .nsconfig file is important. When deciding whether to serve a given URL, the server's algorithm is to apply the last directive (of a given type) in the .nsconfig file for which the corresponding "Files" specification matches the directory containing the file that the given URL points to. For example, if the first of two directives denies access to dir1/* to a set of hosts, and the second directive allows access to dir1/dir2/* for the same set of hosts, URLs that resolve to files in dir1/dir2 will be served to that set of hosts. URLs that resolve to dir1 will not be. If the order of directives were reversed, files in dir1/dir2 would not be served. (Files in dir1/dir2 are covered by the dir1/* pattern since the pattern is applied recursively, and the deny directive comes after in this second case.)

If the only RestrictAccess directives in a particular "Files" set are of type allow, then all hosts not specified by patterns are denied. That is, it's as if the first directive in the "Files" set were to deny all hosts and subsequent directives were to indicate those permitted.

Username/Password Authentication

Username/password authentication is given by directives of the form

RequireAuth realm=STRING userfile=FILENAME userpat=PATTERN

where

STRING is a character string enclosed by double quotes
FILENAME is the absolute pathname of a file containing user:password pairs, one pair to a line. The passwords are standard Unix encrypted passwords
PATTERN is a wildcard string (see reference above) used to select user names from the password file

The directive says to require username/password authentication to the content specified in the associated "Files" specification based on the given password file. If no userpat is given, any user in the userfile will be accepted. If a userpat is given, the userfile is searched for usernames matching PATTERN and only those users are allowed. PATTERN can contain wildcards as described in the reference URL on wildcards mentioned above.

--------------------------------------
<Files test/*> RequireAuth realm="Hello3" userfile="/home/www/public/htpasswd" </Files>This directive activates authentication using name and passwords from /home/www/public/htpasswd for all files in the test directory.
--------------------------------------

--------------------------------------
<Files blah/index.html> RequireAuth realm="Hello2" userfile="/home/bill/htpasswd" </Files>This directive activates authentication using names and passwords from /home/bill/htpasswd for the file blah/index.html.
--------------------------------------

--------------------------------------
<Files blah/index2.html> RequireAuth realm="Hello1" userfile="/home/www/public/htpasswd2" userpat=(|bill) <Files>This directive activates authentication using names and passwords from /home/www/public/htpasswd2 where the name matches the pattern bill for the file blah/index2.html.
--------------------------------------

The foregoing provide some examples of this capability. Several items of note:

The password filename is an absolute filesystem reference. It need not be in the document root directory. This is useful if you want it to be updated by cgi-scripts (e.g. user registration).

To generate encrypted passwords for use in a password file, use the command wa_pass_encrypt. It will prompt you to enter, then re-enter the password, and will then print out an encrypted string that you can paste into the password file.

A separate password file may be used for each "Files" set.

Note in the third example, which is restricting access to a user named bill in the password file, that the "|" sign is required even though there is only one name. (| is the "or" symbol and would be used as joe | bill | helen etc. were there multiple names.)

The "realm" string provides an identifier for the "Files" set and the ReqAuth command. It is included in the request for password sent from server to browser and is used by the browser to identify which password to supply to the server. Netscape Navigator puts the realm string in the dialog box when it prompts the viewer for a password. (A request for authentication goes from the server to the browser each time a protected URL is requested. It is only seen once by the user because the browser remembers the password, using the realm as the key, and sends it automatically on subsequent requests.) Therefore, realm strings should be unique.