This section describes how the server will be installed on a platform and how it is configured.
A typical server installation will include the following directories and files underneath the server root directory.
swerve.cfg | The main server configuration file is in the root directory. |
bin/ | This will contain the swerve program. |
conf/ | This will contain various configuration files such as the mime.types file. |
conf/icons/ | The standard Apache icons will be kept here. |
cgi-bin/ | This will contain any CGI-BIN scripts. Access to these scripts will have to be individually configured. |
htdocs/ | This is the root of the documentation tree. |
var/ | Files created by the server at run-time will be written here. This directory must not reside on an NFS-mounted file system to avoid file locking problems. Log files will be written in this directory. The space requirements are expected to be small. |
var/lock | The lock file prevents multiple executions of the server. |
var/pid | The pid file contains the process ID of the server. |
tmp/ | Uploaded files and data will be cached here. Lots of space may be required here. This directory must not reside on an NFS-mounted file system to avoid file locking problems. |
A configuration file contains sections consisting of a section name followed by parameters enclosed in braces and terminated by semicolons. For example
Server { ServerRoot = /home/swerve; Listen = localhost:80; } |
Free use of white space will be allowed as usual. Comments begin with a # character. If the value of a parameter is not enclosed in double quotes then leading white space after the equals sign and trailing white space will be stripped.
Backslash quoting is allowed within quoted strings for the double-quote character and also \n for a new-line and \t for a tab. A backslash at the end of a line will continue a quoted string to the next line.
The names of the parameters and the sections are case-insensitive.
The following server parameters apply to the server as a whole. Where allowed, relative paths are relative to the server root unless specified otherwise.
This is the path to the server installation. It must be an absolute path. The configuration directory is expected to be at <ServerRoot>/conf.
This is the directory where run-time files are kept. It must be an absolute path and not on an NFS-mounted file system. For security this should be accessible only by the user that the server is running as. The default location is <ServerRoot>/var.
This is the directory where temporary files are kept. It must be an absolute path and not on an NFS-mounted file system. For security this should be accessible only by the user that the server is running as. The default location is <ServerRoot>/tmp.
The value is the number of seconds to time-out a connection if a request or response is not completed.
The value is the maximum number of connections that will be allowed at a time.
The value is the maximum total size in bytes that temporary files in TmpDir are allowed to consume. Connections that try to upload more than this limit will be paused until space is available or they time-out.
The value is the maximum size in bytes that an entity in a request is allowed to have. These entities, such as uploaded files or form data, are saved in temporary files in TmpDir (if they are too large to be held in memory). By setting this limit you can stop one client from filling the temporary disk space.
This sets the port to listen on. This differs from Apache. The possible values are localhost:<port> or just :<port>.
This sets the web address of the server. It is used for URLs generated by the server that refer to its own resources, for example icons. It is required.
These set the user and group name to run as, if the server is started as root.
This sets the name of the file in each directory that implements a node, which will be used as the index for the node. The default is index.html
This sets the path to the mime.types file. This file maps from file extensions to mime types the same way as Apache. The default is <ServerRoot>/conf/mime.types.
The default type for an unrecognised file will be fixed at text/plain.
This sets the path to the error log file. It must be an absolute path. The default is <ServerRoot>/var/errors. Unlike Apache, the log format will be fixed.
This sets the logging level. The possible values are: debug, info, warn and error. They are case-insensitive. The levels are ordered e.g. a level of warn includes all error messages as well.
The contents of the resource store is described by a series of node sections. Each legal URL path is described by a node section. The section describes how the path is implemented and what access controls apply.
An implementation of a path can be either:
When a file-system directory implements a path then optionally all subdirectories will implement extensions of the path. That is, if the URL path /a is implemented by the directory /home/swerve/htdocs/a then the subdirectory /home/swerve/htdocs/a/b will implement the path /a/b. See the WithSubDirs option below.
The section will specify the path to a CGI-BIN script.
The server may have some built-in handlers which can be associated with nodes.
A node section looks like this.
Node / { Directory = /home/swerve/htdocs; WithSubDirs = yes; } |
The URL path to the node follows the Node keyword. The root node is described by the path /. URL "percent escapes" are allowed in the path. Remember that URL paths are case-sensitive. The node parameters follow.
This specifies that the node is implemented as a disk directory. If the path is relative then it is relative to <ServerRoot>/htdocs.
The node will read a file named .swerve in its directory to look for new authorisation or option parameters. If it finds authorisation parameters then they must supply a complete valid authorisation which will replace that in the configuration section. If it finds an Options parameter then these will add to or override options in the configuration section.
This specifies that the node is implemented by some built-in handler in the server.
This specifies that the node is implemented by a CGI-BIN script. If the path is relative then it is relative to <ServerRoot>/cgi-bin.
Exaclty one of Directory, BuiltIn or Script must appear in each node section.
This specifies extra options that apply to the node. The keywords are case-insensitive.
The first keyword can be "all" to enable all options, "none" to disable all options or "inherit" to inherit options from the next higher node. Only the WithSubDirs and FollowSymLinks options can be inherited.
If this Options line appears in a .swerve file then the inherited options include changes made by an Options line in the configuration file's node section for the corresponding URL path.
If this parameter is omitted in the configuration file then "none" is assumed. If it is omitted in the .swerve file then no change is made to the node's options.
Subsequent keywords are preceded by a "+" or a "-" to enable or disable the option for this node.
The FollowSymLinks option allows symbolic links in directories to be followed (without affecting the URL path).
The WithSubDirs option allows each subdirectory to automatically implement an extension of the URL path of the node as described above for the Directory option.
This specifies the "Basic" authentication scheme which checks user names and passwords. This parameter is required to enable authentication for access to the node.
This specifies the realm name for basic authentication. A client typically maintains separate user name and password pairs for each realm.
This specifies the path to a file that lists user names and their passwords. If the path is relative then it is relative to the server root.
The format is the same as for Apache i.e. each line is <user>:<password> except that the passwords are not encrypted. Since they aren't encrypted colons are not allowed in passwords.
There is no encryption since the Unix crypt() function is not available in the SML/NJ libraries and it's not important for this web server.
This specifies the path to a file that lists user groups. If the path is relative then it is relative to the server root.
The file format is the same as for Apache. Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces for example:
mygroup: bob joe anne
This specifies a list of user names, separated by spaces, that are allowed to access the node, if they are authenticated.
This specifies a list of group names, separated by spaces, that are allowed to access the node. All users in the group are allowed access if they are authenticated.
The AuthAllowUsers and AuthAllowGroups parameters together produce a list of user names. If this list is empty then all users will be allowed if their password is authenticated. To disallow all users just provide a dummy user name in AuthAllowUsers that has no password since this user can never be authenticated.
The contents of the user or group files will be read each time a request is received. This allows changes to the files to be immediately available but it will be a bit slow.
In the section called The Resource Store I describe how URLs are interpreted by being passed down through the tree of resource nodes. The URL must pass authentication at each node that requires it. This allows the authentication scheme at a higher node to block access to allow lower nodes.