<title>Resin Configuration</title>

<p/>General (non-HTTP) configuration.  resin.conf is actually a general
configuration file, like NT's registry.  So some Resin modules like
logging and DBPool also have their configuration in resin.conf,
but outside the <var/http-server/> block.

<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/>The following are equivalent:
<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/srun-port/> refers to
a configuration like:

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

<p/>That example could be rewritten as:

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

<objsummary/>

<section title='caucho.com'>

<defun name=include title='resin:include' index='resin:include'>
<sum>Includes another configuration file.</sum>

<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 name=java title='java' index='java'>
<sum>Configuration for the Java compiler.</sum>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>compiler<td>Path to the java compiler or "internal"<td>internal
<tr><td>work-dir<td>Directory for JSP, XSL, and JS compiled *.java<td>/tmp/caucho
<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>classpath<td>extra classpath (Resin 1.2.3)<td>none
<tr><td>max-compile-time<td>Limits the time for a Java compilation (Resin 1.2.3)<td>30 sec
</deftable>

<p/><var/work-dir/> is used by any part of Resin that needs to generate
temporary files.  For example, the JSP engine puts the generated *.java
and *.class files in work-dir.  The XSL and JavaScript compilers also
put their generated *.java and *.class files in work-dir.

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

<defun name=jsp title='jsp' version='Resin 1.1'>
<sum>JSP configuration</sum>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>auto-compile<td>compile the JSP if it's changed<td>true
<tr><td>precompile<td>use precompiled JSP classes if available<td>true
<tr><td>session<td>enable/disable sessions by default.<td>true
<tr><td>static-encoding<td>allow JSP to precompile character encoding<td>true
<tr><td>jsp-max<td>limit the number of active JSP pages<td>1024
<tr><td>recompile-on-error<td>If the JSP page throws a java.lang.Error, recompile it. (since Resin 1.2.3)<td>false
</deftable>

</defun>

<defun name=log title='log' index='log'>
<sum>Starts logging for debugging.</sum>

<deftable>
<tr><th>Attribute<th>Meaning<th>default
<tr><td>id<td>Name of debugging section<th>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>

For example, to log everything to standard error use:

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

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

<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'>
<sum>VFS mailto: configuration.</sum>  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.

<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'>
<sum>httpd and srun configuration.</sum>

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

</defun>

<defun name=group-name title='group-name'>
<sum>Sets Unix group.</sum>  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.

<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'>
<sum>Sets a Java system property.</sum>  The effect is the same as if you
had called System.setProperty before starting Resin.

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

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

<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'>
<sum>Enables the a Java security manager.</sum>  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/>By default, all web-apps have read/write/delete access
to the entire web-app.

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

<defun name=user-name title='user-name'>
<sum>Sets Unix user.</sum>  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.

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

<p/>You must use the <var/bin/resin/> launcher to use user-name:

<example>
unix> bin/resin -conf conf/test.conf
</example>

</defun>

</section>
