Server Configuration

TclHttpd configures itself with two main steps: setting configuration parameters and loading packages. The configuration step uses a configuration file and command line arguments to set basic configuration parameters. The default configuration file is named tclhttpd.rc in the same directory as the start-up script (i.e., bin/tclhttpd.rc). Specify an alternate configuration file with the -config command line argument. You can override the configuration file with additional command line arguments, which are described in Table 18-11. The configuration values from the file and the command line are copied into the Config Tcl array.

Package loading is split into two parts. The main bin/httpd.tcl script loads some core packages. The rest are loaded in the bin/httpdthread.tcl script. The reason for the split is to try to isolate the core of the server from application-specific functions. In addition, in the threaded version of the server, every thread loads and runs the bin/httpdthread.tcl script. You can specify an alternate package loading script with the -main command line argument.

For example, to start the server for the document tree under /usr/local/htdocs and your own email address as Webmaster, you can execute this command to start the server:

tclsh httpd.tcl -docRoot /usr/local/htdocs -webmaster welch

If you are using the Tclkit version described in Chapter 22:

tclkit tclhttpd.kit -docRoot /usr/local/htdocs -webmaster welch

Alternatively, you can put these settings into a configuration file, and start the server with that configuration file:

tclsh httpd.tcl -config mytclhttpd.rc

Command Line Arguments

There are several parameters you may need to set for a standard Web server. These are shown below in Table 18-11. The command line values are mapped into the Config array by the httpd.tcl startup script.

Table 18-11. Basic TclHttpd parameters

Parameter	Command Option	Config Variable
Port number. The default is 8015.	-port number	Config(port)
Server name. The default is [info hostname].	-name name	Config(name)
IP address. The default is 0, for "any address".	-ipaddr address	Config(ipaddr)
Directory of the root of the URL tree. The default is the htdocs directory.	-docRoot directory	Config(docRoot)
User ID of the TclHttpd process. The default is 50. (UNIX only.)	-uid uid	Config(uid)
Group ID of the TclHttpd process. The default is 100. (UNIX only.)	-gid gid	Config(gid)
Webmaster email. The default is webmaster.	-webmaster email	Config(webmaster)
Configuration file. The default is tclhttpd.rc.	-config filename	Config(file)
Directory containing custom code. The server loads all files found in this directory.	-library directory	Config(library)

Server Name and Port

The name and port parameters define how your server is known to Web browsers. The URLs that access your server begin with:

http://name:port/

If the port number is 80, you can leave out the port specification. The call that starts the server using these parameters is found in httpd.tcl as:

Httpd_Server $Config(name) $Config(port) $Config(ipaddr)

Specifying the IP address is necessary only if you have several network interfaces (or several IP addresses assigned to one network interface) and want the server to listen to requests on a particular network address. Otherwise, by default, the server accepts requests from any network interface.

User and Group ID

The user and group IDs are used on UNIX systems with the setuid and setgid system calls. This lets you start the server as root, which is necessary to listen on port 80, and then switch to a less privileged user account. If you use Tcl+HTML templates that cache the results in HTML files, then you need to pick an account that can write those files. Otherwise, you may want to pick a very unprivileged account.

The setuid function is available through the TclX (Extended Tcl) id command, or through a setuid extension distributed with TclHttpd under the src directory. If either of these facilities is not available, then the attempt to change user ID gracefully fails. See the README file in the src directory for instructions on compiling and installing the extensions found there.

Webmaster Email

The Webmaster email address is used for automatic error reporting in the case of server errors. This is defined in the configuration file with the following command:

Doc_Webmaster $Config(webmaster)

If you call Doc_Webmaster with no arguments, it returns the email address you previously defined. This is useful when generating pages that contain mailto: URLs with the Webmaster address.

Document Root

The document root is the directory that contains the static files, templates, CGI scripts, and so on that make up your Web site. By default, the httpd.tcl script uses the htdocs directory next to the directory containing httpd.tcl. It is worth noting the trick used to locate this directory:

file join [file dirname [info script]] ../htdocs

The info script command returns the full name of the http.tcl script, file dirname computes its directory, and file join finds the adjacent directory. The path ../htdocs works with file join on any platform. The default location of the configuration file is found in a similar way:

file join [file dirname [info script]] tclhttpd.rc

The configuration file initializes the document root with this call:

Doc_Root $Config(docRoot)

If you need to find out what the document root is, you can call Doc_Root with no arguments and it returns the directory of the document root. If you want to add additional document trees into your Web site, you can do that with a call like this in your configuration file:

Doc_AddRoot directory urlprefix

Other Document Settings

The Doc_IndexFile command sets a pattern used to find the index file in a directory. The command used in the default configuration file is:

Doc_IndexFile index.{htm,html,tml,subst}

If you invent other file types with different file suffixes, you can alter this pattern to include them. This pattern will be used by the Tcl glob command.

The Doc_PublicHtml command is used to define "home directories" on your HTML site. If the URL begins with ~username, then the Web server will look under the home directory of the user for a particular directory. The command in the default configuration file is:

Doc_PublicHtml public_html

For example, if my home directory is /home/welch, then the URL ~welch maps to the directory /home/welch/public_html. If there is no Doc_PublicHtml command, then this mapping does not occur.

You can register two special pages that are used when the server encounters an error and when a user specifies an unknown URL. The default configuration file has these commands:

Doc_ErrorPage error.html
Doc_NotFoundPage notfound.html

These files are treated like templates in that they are passed through subst in order to include the error information or the URL of the missing page. These are pretty crude templates compared to the templates described earlier. You can count only on the Doc and Httpd arrays being defined. Look at the Doc_SubstSystemFile in doc.tcl for the truth about how these files are processed.

Document Templates

The template mechanism has two main configuration options. The first specifies an additional library directory that contains your application-specific scripts. This lets you keep your application-specific files separate from the TclHttpd implementation. The command in the default configuration file specifies the libtml directory of the document tree:

Doc_TemplateLibrary [file join $Config(docRoot) libtml]

You can also specify an alternate Tcl interpreter in which to process the templates. The default is to use the main interpreter, which is named {} according to the conventions described in Chapter 19.

Doc_TemplateInterp {}

Log Files

The server keeps standard format log files. The Log_SetFile command defines the base name of the log file. The default configuration file uses this command:

Log_SetFile /tmp/log$Config(port)_

By default, the server rotates the log file each night at midnight. Each day's log file is suffixed with the current date (e.g., /tmp/logport_990218.) The error log, however, is not rotated, and all errors are accumulated in /tmp/logport_error.

The log records are normally flushed every few minutes to eliminate an extra I/O operation on each HTTP transaction. You can set this period with Log_FlushMinutes. If minutes is 0, the log is flushed on every HTTP transaction. The default configuration file contains:

Log_FlushMinutes 1

CGI Directories

You can register a directory that contains CGI programs with the Cgi_Directory command. This command has the interesting effect of forcing all files in the directory to be executed as CGI scripts, so you cannot put normal HTML files there. The default configuration file contains:

Cgi_Directory /cgi-bin

This means that the cgi-bin directory under the document root is a CGI directory. If you supply another argument to Cgi_Directory, then this is a file system directory that gets mapped into the URL defined by the first argument. You can also put CGI scripts into other directories and use the .cgi suffix to indicate that they should be executed as CGI scripts.

The cgi.tcl file has some additional parameters that you can tune only by setting some elements of the Cgi Tcl array. See the comments in the beginning of that file for details.