doc/xml/directives.xml (562 lines of code) (raw):
<section id="directives">
<title>Apache Rivet &version; Configuration</title>
<section>
<para>
Rivet directives are used within the Apache httpd server
configuration to set up the environment where Rivet script
will be run.
</para>
<title>Apache Rivet Configuration lines</title>
<para>
Rivet has 3 general <quote>scope</quote> directives
<itemizedlist>
<listitem>RivetDirConf: for configuration directives meant to
apply to a directory tree</listitem>
<listitem>RivetUserConf: for directives specific to
a user private space</listitem>
<listitem>RivetServerConf: for any directive meant to apply
globally (either to the whole Rivet installation or a single
<ulink url="&apachedoc-vhost;">virtual host</ulink>)
</listitem>
</itemizedlist>
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.
</para>
<para>
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
</para>
<programlisting><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></programlisting>
</section>
<section>
<title>Configuration Directives</title>
<table align="center" title="Configuration Directives application scopes" class="directives">
<thead>
<td>Configuration Directives</td><td>DirConf</td><td>UserConf</td><td>ServerConf</td><td>Virtual Host</td><td>Notes</td>
</thead>
<tbody>
<tr><td>AbortScript</td><td>X</td><td>X</td><td>X</td><td>X</td>
<td>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 <xref linkend="request">request processing</xref>)</td>
</tr>
<tr><td>AfterScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td>Special request handler scripts
should read it from the configuration calling ::rivet::inspect and evaluate it</td></tr>
<tr><td>AfterEveryScript</td><td>X</td><td>X</td><td>X</td><td>X</td><td>See notes for the AfterScript directive</td></tr>
<tr><td>BeforeScript</td><td>X</td><td>X</td><td>X</td><td>X</td>
<td>See notes for the AfterScript directive</td></tr>
<tr><td>CacheSize</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>ChildExitScript</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>ChildInitScript</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>ErrorScript</td><td>X</td><td>X</td><td>X</td><td>X</td>
<td>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</td></tr>
<tr><td>ExportRivetNS</td><td></td><td></td><td>X</td><td>X</td><td>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</td></tr>
<tr><td>GlobalInitScript</td><td></td><td></td><td>X</td><td></td>
<td>effective only when SeparateVirtualInterps is Off (default)</td></tr>
<tr><td>ImportRivetNS</td><td></td><td></td><td>X</td><td>X</td><td>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</td></tr>
<tr><td>HonorHeadRequests</td><td></td><td></td><td>X</td><td>X</td><td>Replaces HonorHeaderOnlyReqs, which is still supported but DEPRECATED</td></tr>
<tr><td>MpmBridge</td><td></td><td></td><td>X</td><td></td><td>global only</td></tr>
<tr><td>RequestHandler</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>SeparateChannels</td><td></td><td></td><td>X</td><td></td><td>global only (DEPRECATED: will be
replaced in future versions of Rivet)</td></tr>
<tr><td>SeparateVirtualInterps</td><td></td><td></td><td>X</td><td></td><td>global only</td></tr>
<tr><td>ServerInitScript</td><td></td><td></td><td>X</td><td></td><td>global only</td></tr>
<tr><td>SingleThreadExit</td><td></td><td></td><td>X</td><td></td><td>global only</td></tr>
<tr><td>UploadDirectory</td><td>X</td><td>X</td><td>X</td><td>X</td><td></td></tr>
<tr><td>UploadFilesToVar</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>UploadMaxSize</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
</tbody>
</table>
<variablelist>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">AbortScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
If an <option>AbortScript</option> is defined control is passed to it as
soon as the command <xref linkend="abort_page" /> is called.
<option>AbortScript</option>
is the right place where specific actions can be taken
to catch resources left dangling by the sudden interruption.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">AfterScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
Script to be called after each parsed .rvt template or .tcl script
is executed
</para>
<para>
In virtual hosts, this option overrides any AfterScript
definitions at the global level.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">AfterEveryScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
<option>AfterEveryScript</option> 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 <xref linkend="abort_page" />. The code in this script
can understand whether it's running after the page was
interrupted by calling <xref linkend="abort_page" />
with the argument <arg>-aborting</arg>. The command
will return 1 if an abort_page call took place
earlier in the request processing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">BeforeScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
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 <option>GlobalInitScript</option>
<option>ChildInitScript</option> 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.
</note>
</para>
<para>
In virtual hosts, this option takes precedence over
the global setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">CacheSize</arg>
<arg><replaceable>size</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
Sets the size of the internal page cache, where
<option><replaceable>size</replaceable></option> is
the number of byte-compiled pages to be cached for
future use. Default is
<command>MaxRequestsPerChild</command> / 5, or 50,
if <command>MaxRequestsPerChild</command> is 0.
</para>
<para>
This option is completely global, even when using
separate per-virtual host interpreters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ChildExitScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
Script to be evaluated when each Apache child
process exits. This is the logical place to clean
up resources created in <option>ChildInitScript</option>,
if necessary.
</para>
<para>
In virtual hosts, this script is run in addition to
any global childexitscript.
When <command>SeparateVirtualInterp</command>
any <command>ChildExitScript</command> placed within a
<option><VirtualHost ...>....</VirtualHost></option>
will be that Virtual Host specific exit handler
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ChildInitScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
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.
</para>
<para>
In virtual hosts, this script is run in addition to
any global childinitscript.
When <command>SeparateVirtualInterp</command>
any <command>ChildInitScript</command> placed within a
<option><VirtualHost ...>....</VirtualHost></option>
will be that Virtual Host specific ininitalization
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ErrorScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
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 <option>ErrorScript</option> 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.
</para>
<para>
In virtual hosts, this option takes precedence over
the global setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ExportRivetNS</arg>
<group choice="req">
<arg>yes</arg>
<arg>no</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
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.
</para>
<para>This option is, by nature, only available at the global level</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">HonorHeadRequests</arg>
<group choice="req">
<arg>yes</arg>
<arg>no</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
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.
</para>
<para>This option is only available at the global level</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ImportRivetNS</arg>
<group choice="req">
<arg>yes</arg>
<arg>no</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
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
</para>
<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
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">MpmBridge</arg>
<arg><replaceable>string</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
This global only option tells mod_rivet which MPM bridge has
to be loaded. The module attempt to interpolate the argument value
<programlisting>bridge = apr_pstrcat(pool,RIVET_DIR,"/mpm/rivet_",rsc->mpm_bridge,"_mpm.so",NULL);</programlisting>
Where RIVET_DIR is the location of the rivet libraries whose definition
is controlled by the configure switch <command>--with-rivet-target-dir=DIR</command>.
For example
<programlisting>RivetServerConf MpmBridge lazy</programlisting> will cause the
rivet_lazy_mpm.so library module to be loaded.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">RequestHandler</arg>
<arg>request_handler_filename</arg>
</cmdsynopsis>
</term>
<listitem>
<para>
Filename of the request handler script. Overrides the default request handler. Can
be virtual host specific
</para>
<note>
Note that changing this scripts requires the programmer to understand mod_rivet
request processing model. See the <link linkend="processing">request processing</link>
manual page
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">SeparateChannels</arg>
<group choice="req">
<arg>yes</arg>
<arg>no</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
Internally mod_rivet creates a new Tcl channel (Rivet channel) which is configured
as <command>stdout</command> 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 <command>SeparateVirtualInterps</command>
set. If you want to enhance the environment separation you may also
set <command>SeparateChannels</command> 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.
</para>
<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 <command>fconfigure stdout ....</command>.
This option is, by nature, only available at the global level and has effect only if
also <command>SeparateVirtualInterps</command> is set
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">SeparateVirtualInterps</arg>
<group choice="req">
<arg>yes</arg>
<arg>no</arg>
</group>
</cmdsynopsis>
</term>
<listitem>
<para>
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.
</para>
<note>
This option is, by nature, only available at the
global level. By enabling <command>SeparateVirtualInterps</command>
you must rely only on <command>ChildInitScript</command> to
initialize the interpreters. Don't expect the
initialization done in <command>ServerInitScript</command> and
<command>GlobalInitScript</command> to be handed down to the
slave interpreters that are private to each configured
virtual host.
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">ServerInitScript</arg>
<arg><replaceable>script</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>
The directive <command>ServerInitScript</command> 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.
</para>
<para>
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 &version2-generic; 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">SingleThreadExit</arg>
<group choice="req"><arg>yes</arg><arg>no</arg></group>
</cmdsynopsis>
</term>
<listitem>
<para>
The Tcl <command>exit</command> 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 <command>exit</command> command with
<command>::rivet::exit</command> 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.
<orderedlist>
<listitem>If SingleThreadExit is set (default) each thread behaves
individually and terminates after running the ChildExitScript and deleting
its Tcl interpreters</listitem>
<listitem>If SingleThreadExit is <command>No</command> the worker bridge notifies all threads
to exit and then calls Tcl_Exit</listitem>
</orderedlist>
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.
</para>
<note>
The default is <command>No</command> for the prefork bridge (loaded by default if the server
runs the prefork MPM) and <command>true</command> for the worker and lazy bridges
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">UploadDirectory</arg>
<arg><replaceable>directory</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>Directory to place uploaded files.</para>
<para>
In virtual hosts, this option takes precedence over
the global setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">UploadFilesToVar</arg>
<group choice="req"><arg>yes</arg><arg>no</arg></group>
</cmdsynopsis>
</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice="plain">UploadMaxSize</arg>
<arg><replaceable>size</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
<para>Maximum size for uploaded files.</para>
<para>
In virtual hosts, this option takes precedence over
the global setting.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>