Item(s) enclosed in square brackets [ ] indicate an optional item. (Do not type the square brackets in your records.)
Items separated by vertical bars | indicate that you should choose an item from the list.
Dots ... indicate that the preceding element can be repeated.
Control is configured by two option records
(HTTPD_CHECK_CODEREC and HTTPD_USER_ACCESS_DEFAULT)
in system file
$tcp:tcpip.config and by two option bits
(WEBPAGENA and WEBPAGDIS)
in each userid record
in the system Code Table. The CODUPD utility is used to
turn the option bits on or off for a userid.
Records in file $tcp:tcpip.config :
HTTPD_CHECK_CODEREC YES|NO
HTTPD_USER_ACCESS_DEFAULT YES|NO
The default is NO for the first record and YES for the second.
Case is not significant in the YES and NO keywords, but the
option names themselves should be in upper case.
If HTTPD_CHECK_CODEREC is NO, or if this record is not present
in the file, then the Code Table option bits are not consulted,
and global access is determined by the setting of the
HTTPD_USER_ACCESS_DEFAULT record: if YES (or no record is present)
all userids are allowed; if NO, no userids are allowed.
If HTTPD_CHECK_CODEREC is YES, then the Code Table option bits
are consulted to decide whether files owned by a given userid
are allowed to be served to the web.
If the option bit WEBPAGDIS (Web Page Disable) is on in the
Code Table record for the userid, the userid is not allowed to
serve files. If the option bit WEBPAGENA (Web Page Enable) is on,
the userid is allowed. If both bits are on, the userid is
not allowed. If neither bit is on (which is the normal default when
a userid is created), the HTTPD_USER_ACCESS_DEFAULT setting
controls whether the userid is allowed: yes if YES (or no record is
present), no if NO.
The system is initially configured to allow access
to all web pages for all users. If your web pages are not accessible
please check with your system administrator.
The administrator can set the userid option bits on or off by
using the keywords WEBPAGENA, NOWEBPAGENA, WEBPAGDIS, and
NOWEBPAGDIS on a CHANGE command in the CODUPD utility.
The NO... forms of the keywords turn a bit off.
For example, to prevent user FRED from serving web pages, enter
the following command in CODUPD:
change fred webpagdis
At some later time, to allow FRED to serve web pages, enter
the following command in CODUPD:
change fred webpagena nowebpagdis
Caution: As explained above, the Code Table option bits have
no effect unless HTTPD_CHECK_CODEREC is YES in $tcp:tcpip.config.
Setting HTTPD_CHECK_CODEREC to YES increases the system overhead
somewhat, because HTTPD has to read the userid's Code Table record
for each web request.
Example 1:
To have a system that disables most user accounts
for web accessibility and have just some accounts enabled, the
system administrator would set the following in the $tcp:tcpip.config
file:
HTTPD_CHECK_CODEREC YES
Then he would use the CODUPD utility
to set the enable option bit on and the disable bit off
in the userids to be allowed.
Example 2:
To allow everyone except for some accounts, the configuration
is as follows:
HTTPD_CHECK_CODEREC YES
Then the system administrator would use CODUPD to
set the disable bit on in the userids to be prevented from serving
web pages.
Controlling access to WEB documents can be done on
a directory basis through Access Configuration Files (ACFs) and
on an individual file basis by Access Control List Files (ACLFs).
Access files contain security controls (directives) and are stored
in the directories that you are protecting.
ACFs can allow or deny access by Internet address
or userid and password. For example, whole directories can be
locked out to all Internet addresses, allowing only internal use.
Confidential documents or other resources can be password-protected
so that only authorized users have access.
User names can be organized into groups, with each group given a
group name, and access control can be defined in terms of group names.
ACFs only restrict
access on a per directory (not per file) basis.
ACLFs (Access Control List Files) can be used to
provide additional access control on a per file basis within a
directory. This is discussed in the topic "Controlling Access
on a Per File Basis".
Note: The access control discussed here does not include
the additional access restrictions that may be imposed
on a Web document by
file httpctl\httpd.auth in the library of the owner of
the document file. That authorization file limits HTTP GET and
PUT requests, but not execution of CGI programs. The format of
the file is the same as that for FTPD, which is described in
file ftpd.auth.sample.
In ACF files (#htaccess.ctl)
any record starting with ; or # or * (in column 1) is a
comment and is ignored. Blank records are ignored.
In ACLF files (#aclf.ctl)
any record starting with ; or # (in column 1) is a
comment and is ignored. Blank records are ignored.
In user group definition files, any record starting with ;
(in column 1) is a
comment and is ignored. Blank records are ignored.
Text (command names, keywords, options, etc.) in ACF, ACLF
and group definition files
is not case-sensitive. Upper or lower case, or a mixture, can
be used. The only exception is the operand of the Authname
statement in ACF files
(the "realm" string), which is case-sensitive.
In many cases, it is necessary to restrict access
to a directory to only certain IP (Internet) addresses. This
is done via the Access Configuration file (ACF). A directory
is protected by having a file called #htaccess.ctl within
it. You can have an ACF for each directory. However, access controls
apply to all directories that fall below it in the tree.
For example, if http has a subdirectory called docs,
and docs has a subdirectory called sales,
then a #htaccess.ctl file in http applies to the
lower directories docs and sales also.
But if docs (or sales) has its own #htaccess.ctl
file, it overrides the one in the parent directory http for
access to files in docs (or sales).
The MUSIC web server first looks for an access file in the same
directory as the file (a web document or a CGI program file)
being referenced. If there is one, it uses
it. If not, it tries the parent directory, and so on until a
#htaccess.ctl file is found or the root directory is reached.
An access file in the root directory acts as the default for all
lower directories in that userid.
The following describes the LIMIT directive and options
that are required for the #htaccess.ctl file.
Usage:
Example:
GET access is the
most commonly used and includes all document requests from the
directory, such as .htm, .html, .txt, .gif, and .jpg files.
An HTTP HEAD request is treated as a GET for purposes of
access control.
If you wish to control access to a CGI (Common Gateway Interface)
program, specify POST
in the Limit statement, even if the actual HTTP method used is
GET (or HEAD).
POST access means sending HTML form data or other types of data
to the server for processing by a CGI (script) program.
In the Limit statement, the keyword POST also applies to access
for any CGI program, even if the GET (or HEAD) method
is used (for example,
when the CGI is invoked by a query string at the end of the
URL, rather than by an HTML form).
The file being accessed is considered to be a CGI program if
the file name matches one of the patterns defined for CGI files
in $tcp:tcpip.config (normally *:HTTPEXEC\* and
*:CGI-BIN\*).
PUT access allows the publish feature of Netscape
Gold, Netscape Composer,
Microsoft's Publisher software, and other HTTP client
programs that support PUT (such as the httpput command),
to upload created or edited
web pages and other files to the server, using the HTTP PUT request.
Currently, a PUT request always requires a login using a
userid and password from the MUSIC Code Table and does not process any
#HTACCESS.CTL file. Therefore the PUT keyword has no effect if
used in <Limit>. If you wish to limit PUT requests by target
file name, you can create an authorization file named
user:httpctl\httpd.auth where user is the target
user library. See file ftpd.auth.sample for the file format.
To enable PUT requests at all, you
must specify the parameter PUTOK=T in file $tcp:httpd.
The default is PUTOK=F, meaning no PUTs are allowed.
Limit supports four types of statements inside the pair of Limit
tags: Deny, Allow, Order, and Require. The following describes
these statements except Require.
Require is described in the next section
as it is only needed if you want to control access by Userid and
Password. The Order statement is important in determining how
the Deny and Allow statements are used.
There should be only one Limit section per ACF file. Reading of the
ACF file stops when a </limit> record is found.
The statements within the Limit section can be indented if you wish.
Notes:
When restricting access to web forms
you can use one of three strategies. You can restrict:
If only the POST for the CGI is restricted, all users will be able
to see the forms document but only those authorized will be able to
send data for processing.
If both the GET for the forms document
and the POST for the CGI are restricted, the
challenge is seen by the user once. The AuthName should be the same
for both limit sections in the respective directories.
It is not recommended that you restrict only the html forms document.
You should protect either the post for the CGI or both POST and GET.
It is possible for anyone to construct a URL that references
your CGI and attempt to process data through it without authorization.
This is prevented by protecting the post for the CGI.
For example, the
html document http\#htaccess.ctl could look as follows.
Usage:
The Deny directive refuses the type of access specified
in the Limit directive to the specified numeric IP address(es)
or IP address pattern(s).
Each item on the Deny statement
can be a full IP address (in the form n.n.n.n) or a
partial IP address (called a pattern)
or the keyword all.
You can specify more than one item, separated by blanks,
on a statement, but it is
more common to put each item on its own Deny statement.
The effect is the same.
Access to the document or CGI program in question is denied
(assuming Order and Allow statements do not override this denial)
if the client's (that is, the browser's) IP address matches any of
the items on the Deny statements. All client IP addresses match
the all keyword.
A partial IP address (a pattern) can be in any of several forms:
n.n.n.* or n.n.n. or n.n.n
matches the client's
IP address if the first 3 parts are the same, regardless of the
4th part of the client IP address.
For example, Deny 135.47.5. matches all client addresses
135.47.5.0 thru 135.47.5.255, but does not match 135.47.6.30 or
135.47.51.6.
Similarly, n.n.* or n.n. or n.n match if the
first 2 parts are the same, regardless of the 3rd and 4th parts.
n.* or n. or n compare only the first part.
Other forms for matching the end of the client's IP address
can also be used, such as .n.n.n etc., but they are not
as useful.
In addition, each part "n" in a pattern (1 to 3 decimal digits)
can contain "wild" characters *
(which matches any sequence of 0
or more digits) and ?
(which matches any single digit).
For example, Deny 112.45.200.1?
matches all client addresses
112.45.200.10 thru 112.45.200.19. This is sometimes useful for
reducing the number of Deny statements needed.
Note: Unlike the Apache web server, MUSIC does not support
host names (domain names) on the Deny and Allow statements.
Only numeric IP addresses can be used.
Examples:
Global Access Control
Global Access Control is a system administrator function.
It controls which MUSIC userids are allowed to provide web content
to be served by HTTPD. This also includes use of CGI (Common Gateway
Interface) program files.
All userids can be allowed, or none can
be allowed, or some can be allowed and others not.
HTTPD_USER_ACCESS_DEFAULT NO
HTTPD_USER_ACCESS_DEFAULT YES
Comments and Case-Sensitivity in Access Files
Controlling Access by Internet Address
Limit
Default if no Limit section:
Open to all IP addresses, no passwords required
statements ...
</Limit>
The Limit directive limits access to files in the
directory tree. The Limit parameter (GET, PUT, or POST)
specifies what type of access is restricted.
One or more types can be specified, separated by blanks.
Order deny,allow
Deny from all
allow from 198.168.
</Limit>
If you restrict the GET on the HTML document,
the unauthorized web users never see the actual form since the
challenge for a user/password will occur before it is displayed.
AuthType Basic
Authname "My form stuff"
<Limit GET>
order deny,allow
allow from all
require SysUser ccfp
</Limit>
For example,
the CGI file httpexec\#htaccess.ctl could look as follows.
AuthType Basic
Authname "My form stuff"
<Limit POST>
order deny,allow
allow from all
require SysUser ccfp
</Limit>
The AuthType and AuthName statements are described later in this
document.
Note that AuthName must be identical to allow the authenticated
user/password to be valid for both the form document and the CGI that
is to process it. The string specified in AuthName is case-sensitive.
Default if no Deny statements: No hosts are denied
Deny from 198.0
Deny from 198.168.189.
Deny from .168.180
Deny from all
Allow
Usage:
The allow directive allows the type of access specified in the Limit directive to the specified client numeric IP address(es). Each item is a full or partial IP address or the keyword all. The syntax of the Allow statement is the same as that of the Deny statement. The same IP address patterns can be used.
Examples:
Usage:
The Order directive specifies in what order the Deny and Allow statements are processed. When "order deny,allow" is specified, all Deny statements are processed first. With "order allow,deny", the Allow statements are processed before the Deny statements. By default, the order is allow, then deny.
This is important when the user's (browser's) IP address occurs in both Allow and Deny directives because of wild cards or the all keyword. The rule is that the last-processed Allow or Deny statement that matches the user's IP address is the one that applies.
If the user's IP address does not match any of the Allow or Deny statements, then access is allowed.
The Order statement should precede the Allow and Deny statements.
Caution: The physical order in which Deny and Allow directives appear in a Limit section has no bearing on the order of processing. This is determined strictly by the Order directive. In other words the same IP address may resolve correctly as both allowed and denied based on the directives specified. However, the order specified will be used to make the final decision on access. If the Order was allow,deny then access is denied, since the Deny is processed after the Allow, and the rule is that the last one processed is the one that applies.
Recommendation: MUSIC's default Order setting, and the handling of the case where the user's IP address does not match any Allow or Deny statements, may be different from other web servers (such as Apache). Therefore, it is strongly recommended that each Limit section contain (1) an Order statement, and (2) a "deny from all" or an "allow from all" statement somewhere. If these two rules are followed, MUSIC's processing should be the same as other servers.
If there is any doubt as to the effect of the Order, Deny, and Allow statements in an access file, use the httest command to verify the correct behaviour for various client IP addresses. The httest command, described in a later section, allows you to simulate access from a specified client IP address, to see whether access is allowed or denied to a given MUSIC file.
Examples:
In the example below, only host addresses beginning
with 198.168. are allowed. All others are denied.
Controlling Access by Userid and Password
Besides controlling access by IP address, directories
can be password-protected by requiring a valid userid and password
combination. The userid (user name) can be either a MUSIC/SP
system userid (1 to 16 characters long, from the MUSIC/SP Code Table)
or a 1- to 64-character userid from a user password file which is
maintained by the user who owns the web documents. Both types of
user names are case-insensitive (upper and lower case are considered
equivalent). The browser prompts the user to enter a user name and
password when required. The browser remembers the user name and
password, and automatically resends it for later requests for the
same documents (the same AuthName string) in the same browser session.
If a directory is protected, users need authorization
to access any file in that directory.
The following directives apply to user authorization:
In order for password protection to be enforced,
an ACF must contain all of the above directives,
except possibly AuthUserFile, which is needed only when usernames
from a user password file are used, and AuthGroupFile,
which is only necessary when allowing access to a group of usernames.
Also, the Require statement
must be included within the <limit>
section.
The ACF file should contain only 1 of each of the above statements. If more than one is present, only the last one is used. In particular, the Limit section should contain only 1 Require statement.
Note:
Controlling access
by IP address needs an ACF with a <limit> section. Controlling
access by userid needs an ACF with the authorization directives
above and a <limit> section.
Example:
The AuthType directive specifies the type of HTTP authorization in effect for the directory; in particular, how the authorization information is sent from the browser to the server, and how the server interprets it. Currently, only the Basic type is implemented. NOTE: Using the Basic type of authorization, the userid and password entered by the user is sent from the browser to the server in plain text form (Base-64 encoding), therefore there is a security risk that the data may be intercepted and the password revealed to a third party (unless other steps are taken to ensure that all communication between the two machines is encrypted or otherwise protected).
Usage:
The AuthName directive specifies a string that identifies the resource or facility for which access is required. It is also called a "realm" string.
The AuthName string is case-sensitive, can be up to 62 characters long, and should be enclosed within double quote characters ("). Do not use a " character inside the string. If you omit the opening or closing quote, the server will automatically supply it.
The string is displayed on the user's browser when the user is asked for a userid and password, and gives some indication as to why authorization is necessary. It normally should contain enough information for the user to know what user name to enter. Of course, if you want to keep unauthorized users totally in the dark, you can specify AuthName Secret or something equally unclear to potential users. The specified string may contain spaces, as in the example below. It is case-sensitive.
The authname string is the "realm" string that the browser will use. The browser will automatically resend the same userid/password (without prompting) when the domain name is the same and the realm is the same. The realm string is sent from the server to the browser as a 401 challenge, and is displayed in the browser's userid/password dialog box.
Usage:
Example:
In order to enforce password security, the Web server
needs a list of acceptable userids and passwords. These are contained
in a password file, or authorized user file, specified by the
AuthUserFile directive. It is also possible to require a valid
system login userid (from the MUSIC/SP Code Table), in which case
a user password file may not be needed.
The various possibilities are discussed
under the Require statement later.
Usage:
Example:
User authorization files are created with the htpasswd utility. To create a new password file, use the htpasswd command with the -c option, then add more user names by commands without -c.
Usage:
The optional -c switch is used only when creating a new password file.
Example:
Notes:
In addition to requiring a single userid and password,
you can require membership in a group of authorized users.
Groups are used when you specify a group type on the Require
statement, such as require group * or
require sysgroup * .
To implement group security, you create a user authorization
file containing names and passwords, using the htpasswd
command as described above. (If the user names are system Code Table
userids, a user authorization file is not needed.)
This can be a new file or
an existing one. In addition, you must create a group authorization
file, which is a text file that lists the user names that are
members of each group. You can use the Editor to create and modify
the group file. The full file name of the
group authorization file is specified by the AuthGroupFile statement.
Usage:
Example:
User name patterns, containing wild characters * (matches any set of 0 or more characters) and/or ? (matches any single character), can be specified in the group file, as well as specific user names. For example, if a group is specified as containing user name pattern abc*, then any user name starting with abc is considered to be in the group.
The example below illustrates that you can have multiple
groups in one group file and each group statement can occur on
separate lines. In this example we have 3 groups called guests,
members, and staff.
Group guests has 5 users. Group members has 3 users.
Group staff contains the user chief and all user names starting
with the characters abc.
A user can be a member of more than one group.
You can have as many lines as is required
for any individual group.
The previous directives have merely set up the locations of files to be used in password protection. The directive which actually activates this protection is the Require statement, which occurs in a Limit section and may require that all access to files in the restricted directory be authorized by a valid user name and password entered by the user at the browser.
Usage:
Require type name
where type is one of 8 keywords that specify the type of Require statement: User Group SysUser SysGroup System SysUserLogin SysGroupLogin SystemLogin
and name is a single user or group name, depending on which type is used. For System and SystemLogin types, name is not used. For some types of Require, the name can be the special name *, as described below. Specifying the special name *any or *anyone is equivalent to *.
The Require statement pulls together all the other authorization
directives to enforce user authorization. If an user name is
specified, Require looks for that user's information in the AuthUserFile
specified for the directory. If membership in a group is required,
Require checks to see that the user has a valid userid and password
as specified in AuthUserFile and that the user is in the specified
group as listed in AuthGroupFile.
Examples:
In the example below, any user attempting to access
a file in the directory is asked to provide authorization for
mystuff. If the user enters userid Fred and the
correct password in AuthUserFile, access is granted.
SysUserLogin, SysGroupLogin, and SystemLogin are used when limiting the POST (CGI processing) access. This has meaning only for CGI. When a CGI script is encountered, the CGI will be executed using the authenticated userid's login account, user privileges and disk space (not the userid that owns the CGI program file). If GET access is also limited by the same section, the userid is used only for authorization and not logging in. For GET, the meanings revert to those of SysUser, SysGroup and System respectively.
System and SystemLogin do not use the "name"
portion of the Require statement.
Important: CGIs that require SysUserLogin, SysGroupLogin or SystemLogin will execute under the user account that was entered in the dialog box at the browser's challenge for a user/password. These CGIs have access to the entered userid's files and resources. For all other cases the CGI will execute on the account of the owner of the CGI program file, and there is no access to resources other than those owned by the owner of the CGI (unless the owner is a privileged user).
Therefore, for reasons of security, SysUserLogin, SysGroupLogin, and SystemLogin are restricted to CGI programs listed in the file $TCP:LOGON.PROGS (this file is maintained by the site system administrator) or in the file xxx:LOGON.PROGS (where xxx is the library to which the logon is done, i.e. the MUSIC/SP userid entered by the user at the browser, but without the subcode if any). This is to prevent rogue CGIs from doing harm to user accounts that happen to execute them. If the CGI is provided by the system administrator, it is probably listed in file $tcp:logon.progs. If it is provided by an ordinary user yyy, any user xxx who wants to allow yyy's CGI to execute via login to account xxx would create file xxx:logon.progs and list the CGI file in it. (xxx and yyy may be the same or different userids.)
When require system or require sysuser * is used, or when no access control file is used at all, many users may be able to execute the CGI, and the CGI runs under the userid of its owner. Therefore the CGI program should be careful not to allow harmful operations such as deletion of arbitrary files on the owner's library. A typical dangerous operation to be avoided is to allow the user at the browser to enter any file name in a web form, then have the CGI program process that file without further checking.
Controlling Access on a Per File Basis
If an ACF (Access Configuration File) is present and limits one or more access types (GET or POST), HTTPD will also look for an ACLF (Access Control List File) in the target directory. The ACLF file, if present, can specify fine-grained access control, on a per-file basis, for web documents and CGI programs in the directory. The ACLF file can only be activated by the Require statement in the Limit section in the applicable ACF file (in this directory or a directory higher in the tree). Also, in order for the ACLF to apply, the method of access (e.g. GET or POST) to the file must be one of the methods specified in the Limit section of the ACF file.
The ACLF file is named #aclf.ctl and must be in
the same directory as the files it protects. Its access protection
does not extend to directories below it in the tree.
Typically, an ACLF file is used when you want some files to be accessed by some user names or groups, and other files to be accessed by other user names or groups. For each file or set of files, you can specify the user names or groups that have access. Whether user names or groups are used is determined by the type parameter on the applicable Require statement.
The format of a record in the ACLF file is:
filename: method,method,...: name,name,...
There can be several records in an ACLF file. Case is not significant in the ACLF. Methods and names are separated by 1 or more blanks or commas. Blanks before and after the colon (":") are optional. Records starting with ; or # are ignored, as are blank records. Records can be up to 512 bytes long; longer records are truncated without warning. Invalid records are ignored.
HTTPD reads records from the ACLF file, looking for a match on the file name. When a file name match is found, and access is allowed to the file, reading stops. Otherwise HTTPD continues to read records. If EOF (end of file) is reached, access is not allowed to the file. Therefore, multiple ACLF records can apply to a particular file. In order for HTTPD to allow access to the file, at least one of the records must allow access.
When access is by group and an ACLF file is used, normally it is most useful to specify the special group name * in the Require statement.
For example,
the following is a valid ACLF:
Testing Access Control
The program HTTEST can be used to test your access Control Files
and the
associated Access Control List files without using the WEB.
HTTEST will display a brief report of the #HTACCESS.CTL file.
It also reports whether the IP address specified has access or not.
HTTEST will detect password requirements and will ask you to enter a
userid/password combination (as required) for testing.
If you need HTTEST to verify a userid against the MUSIC Code Table,
it must be run on an id with sufficient privileges.
Usage: httest web_file [IPaddress]
Where web_file is a fully qualified MUSIC file name whose access is to be tested. It need not even exist. IPaddress is the numeric address of a site you wish to test for access. HTTEST tests whether a browser at that IP address would have access to the specified web_file. If IPaddress is not specified, you are asked to enter one (if you don't care about IP address testing, just enter any address, such as 0.0.0.0). The IP address should be a complete numeric address, not a partial address.
Examples:
httest jdoe:httpexec\cgi1.rex 218.45.0.5
httest jdoe:http\plandoc.htm