The main Tcl script consists of
The document root is the name of the directory on your server machine
that corresponds to the root of server's URL hierarchy. This is defined
With no arguments,
If you have additional directories you need to paste into the hierarchy
you can use
If you want users to export their own pages under ~user URLs, then
The server generates log files in a standard format that is understood by various log-processing utilities. (If you have special needs you can implement a new log module.) The log files are automatically rotated every day, except that there is only one error log that is always appended. You specify the base name of the log file and a different suffix is appended for the daily logs and the error file:
The logs are flushed periodically instead of on each log entry, except the error log which is flushed immediately. You can set the period with:
Server Name and Port
You set the server's host name and port with the
If you need to specify the server's own IP address, in case you have multiple servers running on different interfaces, just append the IP address to this command:
If you are going to run several servers you'll need to clone the startup script and run a different Tcl process for each server.
The server partitions the URL space into "domains" that are uniquely identified by a prefix of the URL. The longest matching prefix is used. For example, "/" is the prefix of all URLs, but you can also have a "/device" domain and a "/status" domain that are handled by different Tcl procedures. Basic file system service is provided by the Doc domain (i.e., doc.tcl), which makes a call like this:
but the CGI domain makes a call like
This registers a Tcl procedure that is called each time a request matches the prefix. The longest matching prefix is used to resolve conflicts between prefixes like "/" and "/cgi-bin". The domain handler is invoked like this:
Sample domain handlers include
Application Direct URLs
The Direct module implements a mapping from URLs to Tcl procedure calls.
The name of the URL determines the procedure, and the arguments come
from query data. Use
This declares that URLs beginning with
This defines an implementation for the
If the procedure has arguments defined, then the
If you have an HTML form with
The Doc domain supports handlers for MIME types. The
Example handlers include
Safe-Tcl in an external process
This is currently broken, and safesrv.tcl and safecgio.tcl need to be updated to the new server core. Instead of putting the Safe-Tcl processing in another file, it is done in a the main process using the "Subst" approach described below.
For example, a simple
<h1>Hello World</h1> The current time is [clock format [clock seconds]]
<h1>Hello World</h1> The current time is Sat Apr 18 11:01:49 PDT 1998
Caching results in .html filesIf your fetch the .tml file directly, the server always does template processing. The return meta-data does not include a modify time, so proxies and browsers will not cache the page. However, if you fetch a .html file and there is a corresponding .tml file, then the server can check to see if the template is newer than the .html file. If it is, then the template is processed, the results are cached in the .html file, and the .html file is returned to the client. In this case a modify time is returned so proxies and browsers can cache the file.
Why cache the results of template processing? We use templates to provide the general look and feel of our site. Most pages are static and just use the templates for standard headers, images, and so on. Caching these pages makes sense because the template will generate the same thing every time.
There are two configuration command that affect template results caching.
Permissions and the setuid extensionIf your web server process is caching template results in .html files it must have permission to write those files. You can run the server as yourself and control permissions that way. However, if you want to run under port 80 you need to start the server as root. For security reasons most web servers do a setuid call to change into a normal user after opening their main socket.
The src directory of the distribution has a setuid.c file that implements a "setuid" Tcl command. This will only work if the server starts as root. The setuid command takes two arguments, a user ID and a group ID. For now they must be numeric, not symbolic IDs.
What I do is have a tclhttpd user account and a "web" group. I have the server setuid to these after it calls Httpd_Server. Then I make the htdocs hierarchy have group ownership of "web" and group write permission. The directories can be owned by the webmaster - they do not have to be owned by tclhttpd and probably should not be. This is what this directory looks like:
drwxrwxr-x 4 welch web 512 Apr 18 12:38 ./ drwxrwxr-x 13 welch web 1024 Apr 18 11:30 ../ -rw-r--r-- 1 welch web 201 Apr 18 11:31 .tml -rw-r--r-- 1 tclhttpd web 8184 Apr 18 12:38 index.html -rw-r--r-- 1 welch web 5566 Apr 17 22:00 index.tml drwxr-xr-x 2 welch web 512 Apr 15 23:15 patch2.0.1/ drwxr-xr-x 2 welch web 512 Jan 2 09:37 patch2.1/ -rw-r--r-- 1 welch web 14493 Apr 18 12:38 reference.html -rw-r--r-- 1 welch web 1689 Apr 18 11:45 register.html -rw-r--r-- 1 tclhttpd web 14805 Apr 18 11:48 server.html -rw-r--r-- 1 welch web 12186 Apr 18 11:48 server.tml -rw-r--r-- 1 welch web 7209 Apr 18 11:37 usenixAbstract.htmlYou can see where the server has cached a couple .html files and that the current directory is group writable. Note also that I can't edit the cached files because they are owned by the server.
Tcl code for TemplatesThe server supports a library of Tcl scripts that are to be used with your .tml documents. This is typically in the /libtml directory of your htdocs area. In addition, the server looks for ".tml" files (that's a file beginning with .) in each directory up to the root of the URL tree. The idea is that you put global settings in the /.tml file, and you put per-directory definitions in local .tml files. These files are sourced, so they should contain Tcl commands. The upper-most .tml file is sourced first, and the .tml file in the current directory is sourced last, just before the template file itself.
You can find example .tml files in the sample htdocs directory.
The server checks date stamps on the .tml files and will regenerate a .html page if either its corresponding .tml file or any of the per-directory .tml files are newer. So, touching the root .tml file will cause all your generated .html files to be preprocessed the next time they are fetched.
Configuration CommandsAs well as Doc_CheckTemplates described above, your main init script can use these commands to affect template processing:
Old .subst filesThe template mechanism above superceeds the originial .subst templates. Those are still supported, but they lack the caching support, the script library, and the per-directory .tml files.
The MIME type handler for
Then it calls