<s1 title="Port and Protocol Configuration">

<objsummary/>

<s2 title='Port Configuration'>

<defun title='accept-buffer-size' version="Resin 1.2">
<p>Number of sockets in the accept buffer.</p>

<p><b>Default:</b> 256</p>
</defun>

<defun title='http' version="Resin 1.2">
<p>Defines a HTTP or SSL port for the standalone server.</p>

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>id<td>http identifier name
<tr><td>host<td>The listening host
<tr><td>port<td>The listening port
<tr><td>virtual-host<td>Virtual host to select a <a href="#host">host</a> block.
<tr><td>ssl<td>enable ssl
<tr><td>ssl2<td>enable SSLv2<td>true
<tr><td>ssl3<td>enable SSLv3<td>true
<tr><td>tls1<td>enable TLSv1<td>true
<tr><td>key-store-type<td>JSSE Type of the key store (default jks)
<tr><td>key-store-file<td>JSSE File containing the certificates
<tr><td>key-store-password<td>JSSE Password to read the certificates
<!--
<tr><td>ca-certificate-path<td>OpenSSL CA certificate path (Resin 2.1.4)
<tr><td>ca-certificate-file<td>OpenSSL CA certificate path (Resin 2.1.4)
<tr><td>ca-revocation-path<td>OpenSSL CA revocation path (Resin 2.1.4)
<tr><td>ca-revocation-file<td>OpenSSL CA revocation path (Resin 2.1.4)
-->
<tr><td>certificate-chain-file<td>OpenSSL certificate chain (Resin 2.1.4)
<tr><td>certificate-file<td>OpenSSL certificate (Resin 2.0.5)
<tr><td>certificate-key-file<td>OpenSSL key certificate (Resin 2.0.5)
<tr><td>certificate-key-password<td>OpenSSL key password (Resin 2.1.1)
<tr><td>crypto-device<td>OpenSSL engine (Resin 2.0.5)

<tr><td>thread-max<td>Maximum number of live threads.<td>200
<tr><td>thread-min<td>Minimum number of live threads.<td>5
<tr><td>thread-keepalive<td>Number of keepalive threads<td>100
<tr><td>request-timeout<td>Max time for a request, after this the request
will be interrupted.<td>65 sec
<tr><td>listen<td>Value of the socket listen parameter<td>5
<tr><td>accept-buffer-size<td>Number of sockets in the accept buffer.<td>256
<tr><td>shutdown-wait-time<td>How long to wait for connections to
finish before exiting.<td>10 sec.
</deftable>

<example title='Basic HTTP configuration'>
&lt;caucho.com&gt;
  &lt;http-server&gt;
    &lt;http port='8080'&gt;
    ...
  &lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

<example title='JSSE configuration'>
&lt;caucho.com&gt;
  &lt;http-server&gt;
    &lt;http port='8443'&gt;
      &lt;ssl>true&lt;/ssl>
      &lt;key-store-type>pkcs12&lt;/key-store-type>
      &lt;key-store-file>keys/server.p12&lt;/key-store-file>
      &lt;key-store-password>changeit&lt;/key-store-password>
    &lt;/http>
    ...
  &lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

</defun>

<defun title="dead-time">
<p>For load balancing, how long the server should treat a dead server
as dead before retrying it.</p>

<p><b>Default:</b> Defaults to 5 sec.</p>
</defun>

<defun title="host" version="Resin 1.2">
<p>Specifies an interface for the http or srun to listen to.
In cases where the server should not listen at all interfaces on a
multihomed host, the &lt;host> tag will restrict Resin to listen to
one interface.
</p>
<p><b>Default:</b> listen to all interfaces.</p>
</defun>

<defun title="live-time">
<p>For load balancing, how long the server should keep an
idle srun connection open before closing it.  &lt;live-time> must be less
than &lt;request-timeout>.</p>

<p><b>Default:</b> Defaults to 10 sec.</p>
</defun>

<defun title='port' version="Resin 1.2">
<p>Specifies the port the http or srun should listen to.
Most HTTP web servers listen to port 80.
</p>
</defun>

<defun title='request-timeout'>
<p>Time in seconds for a connection to timeout.  An idle client
uses a TCP connection until it quits.  <var/request-timeout/> limits
the time taken up by idle clients.</p>

<p><b>Default:</b> Defaults to 65 sec.</p>
</defun>

<defun title="server" version="Resin 2.0">
<p>Configures a custom protocol server. Some specialized
application may have a custom protocol, like IMAP, which need to
be integrated with the Resin server.  These ports can be configured
with the &lt;server> configuration.</p>

<p>The &lt;request-factory> class implements
<code/com.caucho.server.RequestFactory/> and creates request objects
of type <code/com.caucho.server.Request/>.  Each <code/Request/> will
handle the protocol on the given socket.</p>

<example>
&lt;caucho.com>
  &lt;http-server>
    &lt;server id='a' port='9999'>
      &lt;request-factory>com.trecorp.server.MyServer&lt;/request-factory>
      &lt;init-param foo='bar'/>
    &lt;/server>
    ...
  &lt;/http-server>
&lt;/caucho.com>
</example>
</defun>

<defun title='srun' version='Resin 1.1'>
<p>Defines multiple client machines for load balancing.  This
directive used by the web server (Apache or IIS) and by the Java portion
of Resin.</p>

<p>Each <var/srun/> directive adds a new client to receive load
balanced requests.  With Resin 1.2, the resin.conf must have at least
one &lt;srun> or &lt;http> element.</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>id<td>srun identifier name.<td>none
<tr><td>host<td>The host name of the client srun.<td>all interfaces
<tr><td>port<td>The port name of the client srun.<td>none
<tr><td>connect-timeout<td>How long to wait for a connection from the
web server to the Resin srun before giving up.<td>30 sec
<tr><td>live-time<td>How long the web-server/srun connection should stay live.<td>10 sec
<tr><td>dead-time<td>How long before checking that a srun has come back up.<td>5 sec
<tr><td>timeout<td>How long the load balancing server should wait for a response.<td>30 sec

<tr><td>thread-max<td>Maximum number of live threads.<td>200
<tr><td>thread-min<td>Minimum number of live threads.<td>5
<tr><td>thread-keepalive<td>Number of keepalive threads<td>100
<tr><td>request-timeout<td>Max time for a request, after this the request
will be interrupted.<td>65 sec
<tr><td>listen<td>Value of the socket listen parameter<td>5
<tr><td>accept-buffer-size<td>Number of sockets in the accept buffer.<td>256
<tr><td>shutdown-wait-time<td>How long to wait for connections to
finish before exiting.<td>10 sec.
</deftable>

<example title='Load balance over three machines'>
&lt;caucho.com&gt;
  &lt;http-server&gt;
    &lt;srun id='a' host='host1.caucho.com' port='6802'&gt;
    &lt;srun id='b' host='host2.caucho.com' port='6802'&gt;
    &lt;srun id='c' host='host2.caucho.com' port='6803'&gt;
  &lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

<p>To start srun 'a' use a command line like</p>
<example>
unix> <var/srun.sh -server a/>
Resin 2.1.0
srun listening to host1.caucho.com:6802
</example>

<p>On Unix, when starting a daemon, you'll need to specify a unique pid file.
</p>

<example>
unix> <var/srun.sh -server a -pid a.pid start/>
</example>
</defun>

<defun title='srun-backup' version='Resin 1.1'>
<p>Defines backup client machines for load balancing.  This
directive is only picked up by the load balancer.  The
Java portion of Resin treats a &lt;srun-backup> like any other srun.
Normally, &lt;srun-backup> is only used when each web server has
a primary &lt;srun> in preference to other &lt;srun> JVMs.
See the <a href="balance.xtp">load-balancing</a> section
for more information.
</p>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>id<td>srun identifier name<td>none
<tr><td>host<td>The host name of the client srun<td>all interfaces
<tr><td>port<td>The port name of the client srun<td>none
<tr><td>connect-timeout<td>How long to wait for a connection from the
web server to the Resin srun before giving up.<td>30 sec
<tr><td>live-time<td>How long a keepalive connection will remain alive before
closing.<td>5 sec.
<tr><td>dead-time<td>How long to treat a non-responding srun before trying again.<td>5 sec.
<tr><td>shutdown-wait-time<td>How long to wait for connections to
finish before exiting.<td>10 sec.
</deftable>
</defun>

<defun title="ssl" version="Resin 1.2">
<p>Flags a http or srun to use SSL.</p>

<p>Resin supports SSL with either JSSE or OpenSSL on Unix systems.
We generally recommend using ssl="openssl" since it's faster and more stable.
</p>

<p>Resin's OpenSSL uses the same certificates as Apache, so you can
either reuse your Apache certificate or get a new certificate using the
instructions for getting an Apache certificate.
</p>

<p>If you have OpenSSL-engine and Resin 2.0.5, you can enable
SSL engines using the crypto-device tag.  If the JNI libraries are available,
Resin will use OpenSSL's C-based implementation.
</p>

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>ssl<td>enable ssl ="jsse" or ="openssl"
<tr><td>key-store-type<td>JSSE Type of the key store (default jks)
<tr><td>key-store-file<td>JSSE File containing the certificates
<tr><td>key-store-password<td>JSSE Password to read the certificates
<tr><td>certificate-chain-file<td>OpenSSL certificate chain (Resin 2.1.4)
<tr><td>certificate-file<td>OpenSSL certificate (Resin 2.0.5)
<tr><td>certificate-key-file<td>OpenSSL key certificate (Resin 2.0.5)
<tr><td>crypto-device<td>OpenSSL engine (Resin 2.0.5)
</deftable>

<example>
&lt;http-server>
  ...
  &lt;http port='443'>
    &lt;ssl>openssl&lt;/ssl>
    &lt;certificate-file>/opt/resin/keys/cert.pem&lt;/certificate-file>
    &lt;crypto-device>cswift&lt;/crypto-device>
  &lt;/http>
  ...
&lt;/http-server>
</example>
</defun>

<defun title="sslv2" version="Resin 2.1.1">
<p>Enables or disables SSL v2 for a SSL port.
If sslv2 is false, clients trying
to use SSL v2 will fail.</p>

<p><b>Default:</b> true.</p>
</defun>

<defun title="sslv3" version="Resin 2.1.1">
<p>Enables or disables SSL v3 for a SSL port.
If sslv3 is false, clients trying to use SSL v3 will fail.</p>

<p><b>Default:</b> true.</p>
</defun>

<defun title='tcp-no-delay' version='Resin 2.1.6'>
<p>Sets the tcpNoDelay for received sockets.</p>

<p><b>Default:</b> true.</p>
</defun>

<defun title="tlsv1" version="Resin 2.1.1">
<p>Enables or disables TLS v1 for a SSL port.
If tlsv1 is false, clients trying to use TLS v1 will fail.</p>

<p><b>Default:</b> true.</p>
</defun>

<defun title="verify-client" version="Resin 2.1.2">
<p>Configures how SSL should treat client certificates.</p>

<deftable title="verify-client values">
<tr><th>Value<th>Meaning
<tr><td>none<td>Do not use client certificates
<tr><td>require<td>Require a client certificate
<tr><td>optional<td>Use the client certificate if provided, but require any provided certificate to be signed by a known CA.
<tr><td>optional_no_ca<td>Use the client certificate if provided and accept certificates not signed by known CAs.
</deftable>

<p><b>Default:</b> none.</p>
</defun>

</s2>

</s1>
