Apache Rivet 3.1 Configuration

Apache Rivet Configuration lines

Rivet directives are used within the Apache httpd server configuration to set up the environment where Rivet script will be run.

Rivet has 3 general “scope” directives

RivetDirConf: for configuration directives meant to apply to a directory tree
RivetUserConf: for directives specific to a user private space
RivetServerConf: for any directive meant to apply globally (either to the whole Rivet installation or a single virtual host)

These directives are applied so that RivetDirConf will override RivetUserConf, which in turn overrides any RivetServerConf directives. Not every configuration directory is meaningful to a scope directive, as shown in the table below. The scope of application of a configuration line is matched also with the context where it appears. Virtual hosts definitions are contexts where rivet configuration lines can appear in many adding further customization to a given virtual host server.

Example of configuration of a web server having independent interpreters for each virtual host, a larger default cache and a specific script to be executed before any templates/scripts located in /var/www/myrivetapp

<IfModule rivet_module>
    AddType application/x-httpd-rivet .rvt
    AddType application/x-rivet-tcl   .tcl

    RivetServerConf CacheSize              100
    RivetServerConf SeparateVirtualInterps On
</IfModule>

<Directory /var/www/myrivetapp>
    RivetDirConf BeforeScript "source /var/www/myrivetapp/before_script.tcl"
</Directory>

Configuration Directives

Configuration Directives	DirConf	UserConf	ServerConf	Virtual Host	Notes
AbortScript	X	X	X	X
AfterScript	X	X	X	X
AfterEveryScript	X	X	X	X
BeforeScript	X	X	X	X
CacheSize			X
ChildExitScript			X
ChildInitScript			X
ErrorScript	X	X	X	X
ExportRivetNS			X
GlobalInitScript			X		effective only when SeparateVirtualInterps is Off (default)
ImportRivetNS			X
HonorHeaderOnlyRequests			X
MpmBridge			X		global setting
RequestHandler			X	X
SeparateChannels			X		global setting
SeparateVirtualInterps			X		global setting
ServerInitScript			X
UploadDirectory		X	X	X
UploadFilesToVar			X
UploadMaxSize			X	X

AbortScript ?script?

If an AbortScript is defined control is passed to it as soon as the command abort_page is called. AbortScript is the right place where specific actions can be taken to catch resources left dangling by the sudden interruption.

AfterScript ?script?

Script to be called after each parsed .rvt template or .tcl script is executed

In virtual hosts, this option overrides any AfterScript definitions at the global level.

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.

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.

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.

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

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

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.

ExportRivetNS (yes | no)

Rivet commands are created within the ::rivet namespace. Setting this option you tell mod_rivet to place the whole command set on the export list of namespace, enabling your scripts to import them in a different namespace.

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

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

ImportRivetNS (yes | no)

Rivet commands are created within the ::rivet namespace. Setting this option you tell mod_rivet to place the whole command set on the export list of namespace (implicitly forcing also ExportRivetNS) and then importing the commands on the namespace export list into the global namespace

	Note
	This option is provided only for compatibility with existing code that assumes mod_rivet commands to reside in the global namespace. It's utterly discouraged to use it and it could be removed in future versions of Rivet This option is, by nature, only available at the global level

MpmBridge ?string?

This global only option tells mod_rivet which MPM bridge has to be loaded. The string argument is interpreted first as a name of an MPM bridge and it's interpolated in the string

bridge = apr_pstrcat(pool,RIVET_DIR,"/mpm/rivet_",rsc->mpm_bridge,"_mpm.so",NULL);

Where RIVET_DIR is the location of the rivet libraries whose definition is controlled by the configuration argument <term>--with-rivet-target-dir=DIR</term>. For example

RivetServerConf MpmBridge lazy

will cause the rivet_lazy_mpm.so library module to be loaded. If such library does not exists mod_rivet tries to check if such definition is the fully qualified path to such MPM bridge. If this fails the module causes the web server to stop with an error.

RequestHandler ?request_handler_filename?

Filename of the request handler script. Overrides the default request handler. Can be virtual host specific

	Note
	Note that changing this scripts requires the programmer to understand mod_rivet request processing model. See the request processing manual page

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-grained 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

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.

ServerInitScript ?script?

The directive ServerInitScript plays a special role since the script runs within the master interpreter, an interpreter created when the Apache web server is setting up for answering requests and before worker processes/threads are started. During this stage Apache is still running as a single process, so this is the right place for doing initialization of systems such as any IPC systems.

On systems with the capability of forking child processes the Apache web server can run the prefork MPM. By default rivet selects the prefork brigde which makes mod_rivet work the way mod_rivet 2.x work. In a web server with this set up child processes inherit a copy of the address space from the parent processes and therefore Tcl interpreters too are replicated into the child address space. If SeparateVirtualInteprs is Off child processes run with a copy of the Tcl master interpreter and ServerInitScipt thus provides a way to initialize only once any subsequent Tcl interpreters created by fork calls as each of them are clones of the master interpreter.

UploadDirectory ?directory?

Directory to place 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.

UploadMaxSize ?size?

Maximum size for uploaded files.

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


Building Rivet 3.1 with CMake		Apache Rivet HTTP Request Processing