blob: 08849cee5f1fbb513ec400561124fad75578489e [file] [log] [blame]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Rivet Apache Directives</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="request.html" title="Apache Child Processes Lifecycle and Request Processing"><link rel="next" href="commands.html" title="Rivet Tcl Commands and Variables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Rivet Apache Directives</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="request.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="commands.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="directives"></a>Rivet Apache Directives</h2></div></div></div><div class="section"><div class="titlepage"></div><p style="width:90%">
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:
<span style="font-family:monospace"><span class="command"><strong>RivetDirConf</strong></span></span>,
<span style="font-family:monospace"><span class="command"><strong>RivetUserConf</strong></span></span>,
<span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, meaning that DirConf will
override UserConf, which will in turn override ServerConf.
</p></div><div class="section"><div class="titlepage"></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetServerConf</span> (<span style="font-family:monospace; font-weight: bold;">CacheSize</span> | <span style="font-family:monospace; font-weight: bold;">ServerInitScript</span> | <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> | <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">AbortScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterEveryScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> | <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> | <span style="font-family:monospace; font-weight: bold;">UploadFilesToVar</span> | <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> | <span style="font-family:monospace; font-weight: bold;">SeparateChannels</span> | <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
<span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span> 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.
</div><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">CacheSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
Sets the size of the internal page cache, where
<em class="replaceable"><code>size</code></em> is
the number of byte-compiled pages to be cached for
future use. Default is
<span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> / 5, or 50,
if <span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> is 0.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
This option is completely global, even when using
separate, per-virtual host interpreters.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ServerInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
This option is only available at the global level.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
The directive <span style="font-family:monospace"><span class="command"><strong>ServerInitScript</strong></span></span> 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) <span style="font-family:monospace"><span class="command"><strong>ServerInitScript</strong></span></span>
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)
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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 <em class="replaceable"><code>script</code></em>
is an actual Tcl script, so to run a file, you would
do: <pre class="programlisting">RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"</pre>
</div><div style="margin-bottom:1.5ex ; padding .5ex">
This option is ignored in virtual hosts.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this script is run in addition to
any global childinitscript.
When <span style="font-family:monospace"><span class="command"><strong>SeparateVirtualInterp</strong></span></span>
any <span style="font-family:monospace"><span class="command"><strong>ChildInitScript</strong></span></span> placed within a
&lt;VirtualHost ...&gt;....&lt;/VirtualHost&gt;
will be that Virtual Host specific ininitalization
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
Script to be evaluated when each Apache child
process exits. This is the logical place to clean
up resources created in ChildInitScript,
if necessary.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this script is run in addition to
any global childexitscript.
When <span style="font-family:monospace"><span class="command"><strong>SeparateVirtualInterp</strong></span></span>
any <span style="font-family:monospace"><span class="command"><strong>ChildExitScript</strong></span></span> placed within a
&lt;VirtualHost ...&gt;....&lt;/VirtualHost&gt;
will be that Virtual Host specific exit handler
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This code is evaluated at the global level, not
inside the request namespace where pages are
evaluated.
</td></tr></table></div>
</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this option takes precedence over
the global setting.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">AfterScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
Script to be called after each server parsed (.rvt) page.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this option takes precedence over
the global setting.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this option takes precedence over
the global setting.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">AfterEveryScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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 <a class="xref" href="abort_page.html" title="abort_page">abort_page</a>. The code in this script
can understand whether it's running after the page was
interrupted by calling <a class="xref" href="abort_page.html" title="abort_page">abort_page</a>
with the argument ?<span style="font-family:monospace; font-weight: bold;">-aborting</span>?. The command
will return 1 if an abort_page call took place
earlier in the request processing.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">AbortScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
The execution of a can be interrupted by
invoking <a class="xref" href="abort_page.html" title="abort_page">abort_page</a>. 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.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>directory</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Directory to place uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this option takes precedence over
the global setting.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Maximum size for uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex">
In virtual hosts, this option takes precedence over
the global setting.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadFilesToVar</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
This option is, by nature, only available at the
global level. By enabling <span style="font-family:monospace"><span class="command"><strong>SeparateVirtualInterps</strong></span></span>
you must rely only on <span style="font-family:monospace"><span class="command"><strong>ChildInitScript</strong></span></span> to
initialize the interpreters. Don't expect the
initialization done in <span style="font-family:monospace"><span class="command"><strong>ServerInitScript</strong></span></span> and
<span style="font-family:monospace"><span class="command"><strong>GlobalInitScript</strong></span></span> to be handed down to the
slave interpreters that are private to each configured
virtual host.
</td></tr></table></div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">SeparateChannels</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
Internally mod_rivet creates a new Tcl channel (Rivet channel) which is configured
as <span style="font-family:monospace"><span class="command"><strong>stdout</strong></span></span> 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 <span style="font-family:monospace"><span class="command"><strong>SeparateVirtualInterps</strong></span></span>
set. If you want to enhance the environment separation you may also
set <span style="font-family:monospace"><span class="command"><strong>SeparateChannels</strong></span></span> 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.
</div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">
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 <span style="font-family:monospace"><span class="command"><strong>fconfigure stdout ....</strong></span></span>.
This option is, by nature, only available at the global level and has effect only if
also <span style="font-family:monospace"><span class="command"><strong>SeparateVirtualInterps</strong></span></span> is set
</td></tr></table></div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
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.
</div><div style="margin-bottom:1.5ex ; padding .5ex">This option is, by nature, only available at the global level</div></div></dd></dl></div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetDirConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
These options are the same as for
<span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are
only valid for the directory where they are specified, and
its subdirectories. It may be specified in <span style="font-family:monospace"><span class="command"><strong>Directory</strong></span></span>
sections.
</div></div></dd><dt><span class="term">
<div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetUserConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div>
</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">
These options are the same as for
<span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are
only valid for the directory where they are specified, and
its subdirectories.
</div></div></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="commands.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Apache Child Processes Lifecycle and Request Processing </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Rivet Tcl Commands and Variables</td></tr></table></div></body></html>