Rivet Apache Directives

Rivet directives are used within the Apache httpd server configuration to set up the environment where Rivet script will be run. Their precedence is as follows: RivetDirConf, RivetUserConf, RivetServerConf, meaning that DirConf will override UserConf, which will in turn override ServerConf.

The directive ServerInitScript plays a special role since the script runs within the master interpreter, an interpreter created before the Apache parent process spawns the children that actually will serve the requests coming from the network. During this stage Apache is still running as a single process, so this is the right place for doing initializations or loading packages. Since this script will be running in a single process environment (from the Apache point of view) ServerInitScript is also the right place for doing anything needs to avoid resource concurrency among processes (e.g. the creation and initialization of an IPC system)

RivetServerConf specifies a global option that is valid for the whole server. If you have a virtual host, in some cases, the option specified in the virtualhost takes precedence over the 'global' version.

CacheSize ?size?

Sets the size of the internal page cache, where size is the number of byte-compiled pages to be cached for future use. Default is MaxRequestsPerChild / 5, or 50, if MaxRequestsPerChild is 0.

This option is completely global, even when using separate, per-virtual host interpreters.

ServerInitScript ?script?

Tcl script which is to run when the master interpreter is created. Namespaces, variables and packages loaded during this stage will be copied later on in the startup process, when child processes are created.

This option is only available at the global level.

GlobalInitScript ?script?

Tcl script run as part of a child process initialization. If the option SeparateVirtualInterp is not used this is the right place where file handles, database connections or sockets can be opened. The argument script is an actual Tcl script, so to run a file, you would do:

RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"

This option is ignored in virtual hosts.

ChildInitScript ?script?

Script to be evaluated when each Apache child process is initialized. This is the recommended place to load modules, create global variables, open connections to other facilities (such as databases) and so on.

In virtual hosts, this script is run in addition to any global childinitscript. When SeparateVirtualInterp any ChildInitScript placed within a <VirtualHost ...>....</VirtualHost> will be that Virtual Host specific ininitalization

ChildExitScript ?script?

Script to be evaluated when each Apache child process exits. This is the logical place to clean up resources created in ChildInitScript, if necessary.

In virtual hosts, this script is run in addition to any global childexitscript. When SeparateVirtualInterp any ChildExitScript placed within a <VirtualHost ...>....</VirtualHost> will be that Virtual Host specific exit handler

BeforeScript ?script?

Script to be evaluated before each server parsed (.rvt) page. This can be used to create a standard header, for instance. It could also be used to load code that you need for every page, if you don't want to put it in a GlobalInitScript ChildInitScript when you are first developing a web site.

	Note
	This code is evaluated at the global level, not inside the request namespace where pages are evaluated.

In virtual hosts, this option takes precedence over the global setting.

AfterScript ?script?

Script to be called after each server parsed (.rvt) page.

In virtual hosts, this option takes precedence over the global setting.

ErrorScript ?script?

When Rivet encounters an error in a script, it constructs an HTML page with some information about the error, and the script that was being evaluated. If an ErrorScript is specified, it is possible to create custom error pages. This may be useful if you want to make sure that users never view your source code.

In virtual hosts, this option takes precedence over the global setting.

AfterEveryScript ?script?

AfterEveryScript is a script that is to be run anyway before requests processing ends. This script is therefore run both when the content generation script completes successfully and when its execution is interrupted by abort_page. The code in this script can understand whether it's running after the page was interrupted by calling abort_page with the argument ?-aborting?. The command will return 1 if an abort_page call took place earlier in the request processing.

AbortScript ?script?

The execution of a can be interrupted by invoking abort_page. If an AbortScript is defined for the page being generated, control is passed to it. AbortScript is the right place where specific actions can be taken to catch resources left dangling by the sudden interruption.

UploadDirectory ?directory?

Directory to place uploaded files.

In virtual hosts, this option takes precedence over the global setting.

UploadMaxSize ?size?

Maximum size for uploaded files.

In virtual hosts, this option takes precedence over the global setting.

UploadFilesToVar (yes | no)

This option controls whether it is possible to upload files to a Tcl variable. If you have a size limit, and don't have to deal with large files, this might be more convenient than sending the data to a file on disk.

SeparateVirtualInterps (yes | no)

If on, Rivet will create a separate Tcl interpreter for each Apache virtual host. This is useful in an ISP type situation where it is desirable to separate clients into separate interpreters, so that they don't accidentally interfere with one another.

	Note
	This option is, by nature, only available at the global level. By enabling SeparateVirtualInterps you must rely only on ChildInitScript to initialize the interpreters. Don't expect the initialization done in ServerInitScript and GlobalInitScript to be handed down to the slave interpreters that are private to each configured virtual host.

SeparateChannels (yes | no)

Internally mod_rivet creates a new Tcl channel (Rivet channel) which is configured as stdout and registered to each existing interpreter. There is no need of multiple channels in a single thread as each thread can serve only one request at a time. But if you are deploying mod_rivet in a complex environment running unrelated applications developed by different teams, it could be the case to have SeparateVirtualInterps set. If you want to enhance the environment separation you may also set SeparateChannels to force mod_rivet to create a channel per each Tcl interpreter thus enabling single application code to change the Rivet channel parameters without affecting other applications (even though changing the Tcl channel parameters is a rare necessity). Setting this options increases the system overheads as each Rivet channel needs to allocate its own control structures and internal buffers.

	Note
	This option is implemented in order to have fine grain control over mod_rivet. In nearly all practical cases you won't need to change Rivet Channel (stdout) settings for different applications by calling fconfigure stdout ..... This option is, by nature, only available at the global level and has effect only if also SeparateVirtualInterps is set

HonorHeaderOnlyRequests (yes | no)

If a HEAD requests is issued by the client Rivet detects this case and sends back to the client a standard header response. If the real header has to be examined (e.g. for debugging) you can turn this options on.

This option is, by nature, only available at the global level

RivetDirConf (BeforeScript | AfterScript | ErrorScript | UploadDirectory)

These options are the same as for RivetServerConf, except that they are only valid for the directory where they are specified, and its subdirectories. It may be specified in Directory sections.

RivetUserConf (BeforeScript | AfterScript | ErrorScript | UploadDirectory)

These options are the same as for RivetServerConf, except that they are only valid for the directory where they are specified, and its subdirectories.


Apache Child Processes Lifecycle and Request Processing		Rivet Tcl Commands and Variables