| TclHttpd configures itself with three main steps. The first step is to process the command line arguments described in Table 18-12. The arguments are copied into the Config Tcl array. Anything not specified on the command line gets a default value. The next configuration step is to source the configuration file. The default configuration file is named tclhttpd.rc in the same directory as the start-up script (i.e., bin/tclhttpd.rc). This file can override command line arguments by setting the Config array itself. This file also has application-specific package require commands and other Tcl commands to initialize the application. Most of the Tcl commands used during initialization are described in the rest of this section. The final step is to actually start up the server. This is done back in the main httpd.tcl script. For example, to start the server for the document tree under /usr/local/htdocs and your own e-mail address as Webmaster, you can execute this command to start the server: tclsh httpd.tcl -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 In this case, the mytclhttpd.rc file could contain these commands to hard-wire the document root and Webmaster e-mail. In this case, the command line arguments cannot override these settings: set Config(docRoot) /usr/local/htdocs set Config(webmaster) welch Command Line Arguments There are several parameters you may need to set for a standard Web server. These are shown below in Table 18-12. The command line values are mapped into the Config array by the httpd.tcl start-up script. Table 18-12. 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 e-mail. The default is webmaster. | -webmaster email | Config(webmaster) | | Configuration file. The default is tclhttpd.rc. | -config filename | Config(file) | | Additional directory to add to the auto_path. | -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, 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 do not have either of these facilities 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 e-mail 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 e-mail 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 username 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. | 
