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