Apache Rivet 3.2 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	This directive is meaningful with the default request handler. In order to have this triggered by calling ::rivet::abort_page or ::rivet::exit any special request handler should explicitly read this script from the configuration using ::rivet::inspect and evaluate it (see the section called “Apache Child Processes Lifecycle and Request Processing”)
AfterScript	X	X	X	X	Special request handler scripts should read it from the configuration calling ::rivet::inspect and evaluate it
AfterEveryScript	X	X	X	X	See notes for the AfterScript directive
BeforeScript	X	X	X	X	See notes for the AfterScript directive
CacheSize			X	X
ChildExitScript			X	X
ChildInitScript			X	X
ErrorScript	X	X	X	X	Rivet provides a default error handler. In case you are writing your own request handling procedure you need to call this error handler yourself or develop your application specific error handler to be integrated into the RequestHandler script. See also the notes for the AbortScript and AfterScript directives
ExportRivetNS			X	X	It can be set in a virtual host configuration if SeparateVirtualInterps is On, otherwise this directive can be safely used at the global level only
GlobalInitScript			X		effective only when SeparateVirtualInterps is Off (default)
ImportRivetNS			X	X	It can be set in a virtual host configuration if SeparateVirtualInterps is On, otherwise this directive can be safely used at the global level only
HonorHeaderOnlyRequests			X	X
MpmBridge			X		global only
RequestHandler			X	X
SeparateChannels			X		global only (DEPRECATED: will be replaced in future versions of Rivet)
SeparateVirtualInterps			X		global only
ServerInitScript			X		global only
SingleThreadExit			X		global only
UploadDirectory	X	X	X	X
UploadFilesToVar			X	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 mod_rivet places the whole command set on the export list of the ::rivet 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 only available at the global level

ImportRivetNS (yes | no)

Rivet commands are created within the ::rivet namespace. Setting this option mod_rivet is told to place the whole command set on the export list of the ::rivet namespace (implicitly forcing also ExportRivetNS) and then importing the commands 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 could be removed in future versions of Rivet. This option is only available at the global level

MpmBridge ?string?

This global only option tells mod_rivet which MPM bridge has to be loaded. The module attempt to interpolate the argument value

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 configure switch --with-rivet-target-dir=DIR. 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 actually 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.

SingleThreadExit (yes | no)

The Tcl exit command has a simple implementation that eventually calls Tcl_Exit (which in turn calls stdlib's exit) that forces the immediate deletion of all threads in a process. This behavior would be unacceptable with the worker MPM and worker bridge which are fundamentally threaded. Therefore Rivet shadows the Tcl exit command with ::rivet::exit which calls a designated function in the running bridge. The prefork bridge simply prepares the child process to terminate, whereas the worker bridge is behavior controlled by this option.

If SingleThreadExit is set (default) each thread behaves individually and terminates after running the ChildExitScript and deleting its Tcl interpreters
If SingleThreadExit is No the worker bridge notifies all threads to exit and then calls Tcl_Exit

The latter option might be useful in cases where an application is using an improperly developed Tcl extension which might cause a child process to crash when calling Tcl_DeleteInterp.

	Note
	The default is No for the prefork bridge (loaded by default if the server runs the prefork MPM) and true for the worker and lazy bridges

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.2 with CMake		Apache Rivet HTTP Request Processing