<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>&lt;IfModule rivet_module&gt;
    AddType application/x-httpd-rivet .rvt
    AddType application/x-rivet-tcl   .tcl

    RivetServerConf CacheSize              100
    RivetServerConf SeparateVirtualInterps On
&lt;/IfModule&gt;

&lt;Directory /var/www/myrivetapp&gt;
    RivetDirConf BeforeScript &quot;source /var/www/myrivetapp/before_script.tcl&quot;
&lt;/Directory&gt;</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>&lt;VirtualHost ...&gt;....&lt;/VirtualHost&gt;</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>&lt;VirtualHost ...&gt;....&lt;/VirtualHost&gt;</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>