Configuration

3.1  Named Virtual Hosts

Many Web sites can be served from one Web server process through the use of virtual hosting. When a client (Web browser) sends a request to the server, the domain name is embedded in the request. The Web server can then service the request in different ways based on that requested domain name.

Zero or more virtual hosts may be defined, in addition to the default host. If a request is sent to the server for a host which is not in the virtual host table, then the default host is used. For example, if the client requests http://www.plt-scheme.org/, the server can send back information in the directory /var/www/plt/www.plt-scheme.org/; if the client requests, from the save server, http://www.drscheme.org/, the server can send back information from the directory /home/mburns/www.drscheme.org/.

To configure virtual hosting using the configuration tool, see the section titled ``Managing Virtual Hosts''. To configure virtual hosting by editing the file directly, see virtual-host-table.

3.2  The Configuration Tool

The configuration tool is a normal servlet, run by the Web server, that can manage the configuration files. This is provided as an alternative to editing the file directly.

For security reasons, the configuration servlet is only accessible from the local machine. Thus, one gets to the servlet via http://localhost/servlets/configure.ss.

Once there, select the filename for the configuration file (the default should work). As part of the basic configuration, you can change the port to listen on, the maximum number of waiting connections, and the initial timeout. Individual hosts can be added and edited below the basic configuration.

3.2.1  Managing Virtual Hosts

Adding a virtual host is as simple as selecting ``Add Host.'' The page will reload with the information for the new host; simply change the name to be the domain name for the new host, and change the directory to be the correct directory for the virtual host. The Web server must be restarted for these settings to take effect.

In addition to the virtual hosts's domain and Web root, the details of all hosts (including the default host) can be changed by selecting ``Edit Minor Details.'' From there, the log file, static files directory, password file, timeout values, and message files can all be modified. For details, see the section titled ``Configuration File Syntax''.

3.3  Configuration File Syntax

Instead of using the configuration tool, as described in the section titled ``The Configuration Tool'', the configuration file can be edited ``by hand''. The provided, default configuration file is collects/web-server/configuration-table. The file has the following syntax.

((port natural-number)
 (max-waiting natural-number)
 (initial-connection-timeout number)
 (default-host-table host-table)
 (virtual-host-table (string host-table) ...))

port : natural-number
Usually 80, indicating which port to listen on by default.
max-waiting : natural-number
Usually 40, indicating the maximum number of clients that can wait for a TCP/IP connection to the Web server. This limit usually does not cause problems because the Web server quickly accepts connections as requested and there is no limit on the number of simultaneous connections. On some platforms, choosing a large number may consume too many resources.
initial-connection-timeout : natural-number
Usually 30. After a client connects to the Web server, the server only waits for an HTTP request for this many seconds before closing the connection. Browsers tend to send requests immediately, so a small number is best . This number should be kept small to prevent denial-of-service attacks.
default-host-table : host-table
Described in the section titled ``Host Table Syntax''.
virtual-host-table : (listof (cons string host-table))
A list of (string host-table), where the host-table is defined in the section titled ``Host Table Syntax'' and the string represents the named virtual host's domain name.

For example, let the virtual host table be

(virtual-host-table
  ("www.plt-scheme.org"
   (host-table
     (default-indices "index.shtml" "index.html")
     (log-format parenthesized-default)
     (messages
       (servlet-message "servlet-error.html")
       (authentication-message "forbidden.html")
       (servlets-refreshed "servlet-refresh.html")
       (passwords-refreshed "passwords-refresh.html")
       (file-not-found-message "not-found.html")
       (protocol-message "protocol-error.html")
       (collect-garbage "collect-garbage.html"))
     (timeouts
       (default-servlet-timeout 120)
       (password-connection-timeout 300)
       (servlet-connection-timeout 86400)
       (file-per-byte-connection-timeout 1/20)
       (file-base-connection-timeout 30))
     (paths
       (configuration-root "errors")
       (host-root "/var/www/www.plt-scheme.org")
       (log-file-path "/var/log/www.plt-scheme.org")
       (file-root "htdocs")
       (servlet-root ".")
       (password-authentication "passwd")))))

Requesting the URL http://localhost/ will use the default-host-table, but requesting the URL http://www.plt-scheme.org/, assuming DNS is set up correctly, will return the first of

  1. /var/www/www.plt-scheme.org/index.shtml

  2. /var/www/www.plt-scheme.org/index.html

For port-based virtual hosting, run separate instances of the Web server.

3.3.1  Host Table Syntax

The host table is a part of the configuration file with the following syntax

(host-table
 (default-indices string ...)
 (log-format parenthesized-default)
 (messages
  (servlet-message string)
  (authentication-message string)
  (servlets-refreshed string)
  (passwords-refreshed string)
  (file-not-found-message string)
  (protocol-message string)
  (collect-garbage string))
 (timeouts
  (default-servlet-timeout number)
  (password-connection-timeout number)
  (servlet-connection-timeout number)
  (file-per-byte-connection-timeout number)
  (file-base-connection-timeout number))
 (paths
  (configuration-root string)
  (host-root string)
  (log-file-path string)
  (file-root string)
  (servlet-root string)
  (password-authentication string)))

default-indices : (listof string)
This is a list of index files for all directories. When a directory is specified as the URL, such as http://www.plt-scheme.org/, the Web server searches for a file to display, choosing from this list in the specified order. A good default is
(default-indices "index.html" "index.htm")

For example, if default-indices is set to

(default-indices "index.ss" "index.html" "index.htm" "last-resort")

and the user requests http://www.plt-scheme.org/, the Web server will attempt to serve the following URLS, in order, until a file is found:

  1. http://www.plt-scheme.org/index.ss

  2. http://www.plt-scheme.org/index.html

  3. http://www.plt-scheme.org/index.htm

  4. http://www.plt-scheme.org/last-resort

log-format : symbol
The format to use for the log file. Currently only the symbol parenthesized-default is supported.

3.3.1.1  Messages

servlet-message : string
A filename, usually "servlet-error.html", of the page to display when there is an error with the servlet. This file is located relative to the configuration-root directory.
authentication-message : string
A filename, usually "forbidden.html", of the page to display when there user fails authentication. This file is located relative to the configuration-root directory.
servlets-refreshed : string
A filename, usually "servlet-refresh.html", of the page to display when the servlets are refreshed. This file is located relative to the configuration-root directory.
passwords-refreshed : string
A filename, usually "passwords-refresh.html", of the page to display when the password file is refreshed. This file is relative to the configuration-root directory.
file-not-found-message : string
A filename, usually "not-found.html", of the page to display when the requested file was not found (HTTP error number 404). This file is located relative to the configuration-root directory.
protocol-message : string
A filename, usually "protocol-error.html", of the page to display when the Web browser violates the HTTP standard. This should never appear when interacting with the server through a correct Web browser. The server may close the connection instead of sending this error, depending on the severity of the problem.
collect-garbage : string
A filename, usually "collect-garbage.html", of the page to display when the garbage collected is run. This file is relative to the configuration-root directory.

3.3.1.2  Timeouts

default-servlet-timeout : number
This value, usually 120, determines how long, in seconds, a servlet can wait in between requests before shutting down, unless the servlet calls adjust-timeout! to alter this value. Large values consume more memory, while smaller values annoy end users who must restart servlets.
password-connection-timeout : number
Usually 300, this is the number of seconds a user has to enter a username and password.
servlet-connection-timeout : number
Usually 86400 (one day), this is the number of seconds a servlet has to respond to a single request. Some servlets may perform substantial computation on a loaded server before generating a page. On the other hand, most users will not wait very long for a response.
file-per-byte-connection-timeout : number
Usually 1/20. Let bytes by the bytes in a file. The total number of seconds the server has to send a file is file-base-connection-timeout + file-per-byte-connection-timeout * bytes
file-base-connection-timeout : number
Usually 30. Let bytes by the bytes in a file. The total number of seconds the server has to send a file is file-base-connection-timeout + file-per-byte-connection-timeout * bytes

3.3.1.3  Paths

configuration-root : string
The directory under which the files in the section titled ``Messages'' may be found. Usually "conf".
host-root : string
The root directory for Web files. Under this directory is usually the servlet-root, configuration-root, log-file-path, file-root, and password-authentication. Usually "default-web-root".
log-file-path : string
The name of the log file. Usually "log".
file-root : string
The directory from which static (HTML) files are served. Usually "htdocs".
servlet-root : string
The directory from which dynamic (servlet) files are run and served. Causes odd behavior when set to anything besides ".". The servlets directory is always servlets/, under the host-root.
password-authentication : string
The file from which passwords are read. For information on its format, see the section titled ``Passwords''. Usually "passwords".