<s1 title="Miscellaneous Resin Configuration">

<p>This section contains general, i.e. non-HTTP, configuration.
resin.conf is a general configuration file, like NT's registry.
Some Resin modules like logging have their configuration in
resin.conf, but outside the <var/http-server/> block.</p>

<p>Configuration is based on element XML.  The canonical form uses
elements only, like the Servlet 2.2 deployment descriptors.
To make the configuration more readable, you can use an attribute
as syntactic sugar for an element.</p>

<p>The following are equivalent:</p>
<deftable>
<tr><td>&lt;foo>&lt;bar>13&lt;/bar>&lt;/foo><td>canonical representation, but verbose
<tr><td>&lt;foo bar=13/><td>typical configuration
<tr><td>&lt;foo>&lt;bar id=13/>&lt;/foo><td>Useful for a key-based list.
</deftable>

<p>In general, the order is not important, but the nesting depth is.
In this reference guide, <var/caucho.com/http-server/http/port/> refers to
a configuration like:</p>

<example>
&lt;caucho.com>
  &lt;http-server>
    &lt;http>
      &lt;port>80&lt;/port>
    &lt;/http>
  &lt;/http-server>
&lt;/caucho.com>
</example>

<p>That example could be rewritten as:</p>

<example>
&lt;caucho.com>
  &lt;http-server>
    &lt;http port='80'/>
  &lt;/http-server>
&lt;/caucho.com>
</example>

<objsummary/>

<s2 title='caucho.com'>

<defun title='resin:include'>
<p>Includes another configuration file.</p>

<example>
&lt;caucho.com>
&lt;http-server>
  &lt;host id='host1'>
    &lt;resin:include href='host.conf'/>
  &lt;/host>
  &lt;host id='host2'>
    &lt;resin:include href='host.conf'/>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</example>
</defun>

<defun title='resin:include-directory'>
<p>Includes files in a directory.  All the files in the
directory named by the <var/href/> and which have the given extension
will be inserted into the XML document.</p>

<example>
&lt;caucho.com>
&lt;http-server>
  &lt;host id='host1'>
    &lt;resin:include-directory sub='host.conf' extension='.xml'/>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</example>
</defun>

<defun title='java'>
<p>Configuration for the Java compiler.  In general, we recommend
using IBM's <var/jikes/> compiler because it's significantly faster than
the "internal" compiler.
</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>classpath<td>extra classpath (Resin 1.2.3)<td>none
<tr><td>compiler<td>Path to the java compiler or "internal"<td>internal
<tr><td>compiler-args<td>Extra args to pass to the compiler<td>none
<tr><td>encoding<td>Character encoding (Resin 1.2.4)<td>none
<tr><td>max-compile-time<td>Limits the time for a Java compilation (Resin 1.2.3)<td>30 sec
</deftable>

<example>
&lt;caucho.com>
  &lt;java compiler='/usr/local/bin/jikes'
         compiler-args='-g'/>
  ...
&lt;/caucho.com>
</example>

<p>The "internal" compiler is the default only because it's always available
for any JDK.  The external jikes compiler is generally a preferred
configuration.</p>
</defun>

<defun title='log'>
<p>Debug log configuration.  Most of Resin's code has debug logging
built in.  The &lt;log> configuration enables that logging, allowing
users to see what's going on.  The debug logging can be useful when
trying to understand what HTTP requests and headers the browser is sending
or Resin is returning.</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>default
<tr><td>id<td>Name of debugging section<td>none
<tr><td>href<td>Destination file<td>none
<tr><td>timestamp<td>timestamp format<td>none
<tr><td>rollover-count<td>how many rotated (<var/href.n/>) logs to keep.<td>2
<tr><td>rollover-period<td>How often to rotate the log.<td>none
</deftable>

<p>For example, to log everything to standard error use:</p>

<example>
&lt;caucho.com&gt;
  &lt;log id='/' href='stderr:' timestamp="[%H:%M:%S.%s]"/>
&lt;/caucho.com&gt;
</example>

<deftable>
<tr><th>log <var/id/> value<th>Meaning
<tr><td>/<td>Debug everything
<tr><td>/caucho.com/jsp<td>Debug jsp
<tr><td>/caucho.com/java<td>See all Java compilation
<tr><td>/caucho.com/xsl<td>XSL debugging
<tr><td>/caucho.com/tcp-server
    <td>See thread creation and deletion
<tr><td>/caucho.com/sql
    <td>See database pooling
<tr><td>/caucho.com/http
    <td>HTTP related information
<tr><td>/caucho.com/http/session
    <td>HTTP sessions
<tr><td>/caucho.com/distribution
    <td>Distributed and persistent sessions
<tr><td>/caucho.com/http/cache
    <td>Resin's proxy cache
</deftable>

<p>The timestamp can include the following patterns:</p>

<deftable>
<tr><th>Pattern<th>Meaning
<tr><td>%a<td>short weekday (mon, tue, ...)
<tr><td>%A<td>long weekday (Monday, Tuesday, ...)
<tr><td>%b<td>short month (Jan, Feb, ...)
<tr><td>%B<td>long month (January, February, ...)
<tr><td>%c<td>locale specific date
<tr><td>%d<td>day of month
<tr><td>%H<td>24-hour
<tr><td>%I<td>12-hour
<tr><td>%j<td>day of year
<tr><td>%m<td>month
<tr><td>%M<td>minute
<tr><td>%p<td>am/pm
<tr><td>%S<td>seconds
<tr><td>%s<td>milliseconds
<tr><td>%W<td>week of year
<tr><td>%w<td>day of week
<tr><td>%y<td>2-digit year
<tr><td>%Y<td>4-digit year
</deftable>

</defun>

<defun title='smtp.vfs'>
<p>VFS mailto: configuration.  The smtp.vfs configuration only
applies to the mailto: scheme in Resin's VFS. See the <a href="../java_tut/mail_form.xtp">form mailing</a> tutorial.</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>host<td>SMTP host<td>localhost
<tr><td>port<td>SMTP port<td>25
<tr><td>sender<td>sending mail address<td>The current user and local host
</deftable>

</defun>

<defun title='http-server'>
<p>httpd and srun configuration.</p>

<p>Configures both <a href='http-config.xtp'>http and srun</a>.  The
configuration is identical.</p>

</defun>

<defun name=group-name title='group-name'>
<p>Sets the Unix group.  To listen to port 80, Unix systems require Resin
to start as root.  group-name lets the server change to a safer user after
listening to port 80.</p>

<example>
&lt;caucho.com&gt;
  &lt;user-name>httpd&lt;/user-name>
  &lt;group-name>daemon&lt;/group-name>
&lt;/caucho.com&gt;
</example>
</defun>

<defun title='system-property'>
<p>Sets a Java system property.  The effect is the same as if you
had called System.setProperty before starting Resin.</p>

<example>
&lt;caucho.com&gt;
  &lt;system-property foo=bar/>
&lt;/caucho.com&gt;
</example>
</defun>

<defun title='security-provider'>
<p>Adds a Java security provider without modifying the java.security.</p>

<example>
&lt;caucho.com&gt;
  &lt;security-provider id='com.sun.net.ssl.internal.ssl.Provider'/>
&lt;/caucho.com&gt;
</example>
</defun>

<defun title='security-manager'>
<p>Enables the a Java security manager.  Normal configurations will
not use a security manager, because the security manager slows performance.
ISPs may want to add a security-manager to prevent some actions by
the clients.</p>

<p>By default, all web-apps have read/write/delete access
to the entire web-app.</p>

<example>
&lt;caucho.com&gt;
  &lt;security-manager/>
  ...
&lt;/caucho.com&gt;
</example>
</defun>

<defun title='user-name'>
<p>Sets Unix user.  To listen to port 80, Unix systems require Resin
to start as root.  user-name lets the server change to a safer user after
listening to port 80.</p>

<example>
&lt;caucho.com&gt;
  &lt;user-name>httpd&lt;/user-name>
  &lt;group-name>daemon&lt;/group-name>
&lt;/caucho.com&gt;
</example>

</defun>

</s2>

<s2 title='Formal Description'>

<def>
caucho.com ::= <a href="#java">java</a>,
               <a href="#log">log</a>*,
               <a href="#smtp.vfs">smtp.vfs</a>,
               <a href="#user-name">user-name</a>,
               <a href="#group-name">group-name</a>,
               <a href="#system-property">system-property</a>*,
               <a href="#security-provider">security-provider</a>,
               <a href="#security-manager">security-manager</a>,
               <a href="http-config.xtp">http-server</a>

java ::= <a href="#java">compiler</a>,
         <a href="#java">compiler-args</a>,
         <a href="#java">encoding</a>,
         <a href="#java">classpath</a>
         <a href="#java">max-compile-time</a>

log ::= <a href="#log">href</a>,
        <a href="#log">timestamp</a>,
        <a href="#log">rollover-count</a>,
        <a href="#log">rollover-period</a>

</def>

</s2>
</s1>
