<document>
<header>
  <title>server: Server tag configuration</title>
  <version>Resin 3.1</version>

  <description>

  <p>The &lt;server> tag configures a JVM instance in a cluster.  It
configures HTTP and cluster sockets, keepalives and timeouts, thread pooling,
load balancing, and JVM arguments.</p>

  </description>
</header>
<body>

<localtoc/>

<s1 title="See Also">

<ul>
<li>See the <a href="index-tags.xtp">index</a> for a list of all the tags.</li>
<li>See &lt;<a href="cluster-tags.xtp">cluster</a>&gt; tag configuration</li>
</ul>

</s1>

<defun title="&lt;accept-listen-backlog>" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>

<p>&lt;accept-listen-backlog> configures operating system TCP listen
queue size for the port.</p>

<p>When a browser connects to a server, the server's operating
system handles the TCP initialization before handing the socket to
the server's application.  The operating system will hold the opened
connections in a small queue, until the application is ready to
receive them.  When the queue fills up, the operating system will
start refusing new connections.</p>

<default>100</default>

</defun>

<defun title="&lt;accept-thread-max>" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>

<p>&lt;accept-thread-max> configures the maximum number of 
threads listening for new connections on this port.  &lt;accept-thread-max>
works with &lt;accept-thread-min> to handle spiky loads without
creating and destroying too many threads.</p>

<p>Socket connections are associated with a thread which handles
the request.  In Resin, a number of threads wait to accept a new
connection and then handle the request.  &lt;accept-thread-max>
specifies the maximum number of threads which are waiting for
a new connection.</p>

<p>Larger values handle spiky loads better but require more threads
to wait for the connections.  Smaller values use less threads, but may
be slower handling spikes.</p>

<default>10</default>

</defun>

<defun title="&lt;accept-thread-min>" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>

<p>&lt;accept-thread-min> configures the minimum number of 
threads listening for new connections on this port   &lt;accept-thread-min>
works with &lt;accept-thread-max> to handle spiky loads without
creating and destroying too many threads.</p>

<p>Socket connections are associated with a thread which handles
the request.  In Resin, a number of threads wait to accept a new
connection and then handle the request.  &lt;accept-thread-min>
specifies the minimum number of threads which are waiting for
a new connection.  If many connections appear rapidly with a small
value of &lt;accept-thread-min>, the application
may pause until a new thread is available for the new connection.</p>

<p>Larger values handle spiky loads better but require more threads
to wait for the connections.  Smaller values use less threads, but may
be slower handling spikes.</p>

</defun>

<defun title="&lt;address>" version="Resin 3.1">
<parents>server</parents>

<p>The server &lt;address> defines the IP interface for Resin
cluster communication and load balancing.  It will be an
internal IP address like 192.168.* for a clustered configuration
or 127.* for a single-server configuration.  No wild cards are allowed
because the other cluster servers and load balancer use the address
to connect to the server.</p>

<default>127.0.0.1</default>

<example title="server address">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.1.1" port="6800"/>
    &lt;server id="web-b" address="192.168.1.2" port="6800"/>

    ...
  &lt;/cluster>

  &lt;cluster id="app-tier"&gt;
    &lt;server id="app-a" address="192.168.2.11" port="6800"/>
    &lt;server id="app-b" address="192.168.2.12" port="6800"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;cluster-port>" version="Resin 3.0">
<parents>server</parents>

<p>&lt;cluster-port> configures the cluster and load balancing socket,
for load balancing, distributed sessions, and distributed management.</p>

<p>When configuring Resin in a load-balanced cluster, each Resin instance
will have its own &lt;srun&gt; configuration, which Resin uses for distributed
session management and for the load balancing itself.</p>

<p>When configuring multiple JVMs, each &lt;srun&gt; has a
unique &lt;id&gt; which allows the -server command-line to select
which ports the server should listen to.</p>

<deftable-childtags>
<tr><td>address</td>
    <td>hostname of the interface to listen to</td>
    <td>*</td></tr>
<tr><td>jsse-ssl</td>
    <td>configures the port to use JSSE for SSL</td>
    <td>none</td></tr>
<tr><td>openssl</td>
    <td>configures the port to use OpenSSL</td>
    <td>none</td></tr>
<tr><td>port</td>
    <td>port to listen to</td>
    <td>required</td></tr>
<tr><td>read-timeout</td>
    <td>timeout waiting to read from idle client</td>
    <td>65s</td></tr>
<tr><td>write-timeout</td>
     <td>timeout waiting to write to idle client</td>
     <td>65s</td></tr>
<tr><td>accept-listen-backlog</td>
    <td>The socket factory's listen backlog for receiving sockets</td>
    <td>100</td></tr>
<tr><td>tcp-no-delay</td>
    <td>sets the NO_DELAY socket parameter</td>
    <td>true</td></tr>
</deftable-childtags>

<p>The class that corresponds to &lt;srun&gt; is <a href="javadoc|com.caucho.server.cluster.ClusterPort|"/></p>

</defun>

<defun title="&lt;group-name>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;group-name> configures the operating system group Resin should
run as.  Since the HTTP port 80 is protected in Unix, the web server
needs to start as root to bind to port 80.  For security, Resin should
switch to a non-root user after binding to port 80.</p>

<example title="resin.xml with user-name">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;http port="80"/>

      &lt;user-name>resin&lt;/user-name>
      &lt;group-name>www&lt;/group-name>
    &lt;/server-default>

    &lt;server id="web-a"/>
    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;http>" version="Resin 3.0">
<parents>server</parents>

<p>&lt;http> configures a HTTP or HTTPS port listening for HTTP requests.</p>

<p>When configuring multiple JVMs, each &lt;http&gt; will have a
unique &lt;server-id&gt; which allows the -server command-line to select
which ports the server should listen to.</p>

<deftable-childtags>
<tr><td>address</td>
    <td>IP address of the interface to listen to</td>
    <td>*</td></tr>
<tr><td>port</td>
    <td>port to listen to</td>
    <td>required</td></tr>
<tr><td>tcp-no-delay</td>
    <td>sets the NO_DELAY socket parameter</td>
    <td>true</td></tr>
<tr><td>read-timeout</td>
    <td>timeout waiting to read from idle client</td>
    <td>65s</td></tr>
<tr><td>write-timeout</td>
    <td>timeout waiting to write to idle client</td>
    <td>65s</td></tr>
<tr><td>socket-listen-backlog</td>
    <td>The socket factory's listen backlog for receiving sockets</td>
    <td>100</td></tr>
<tr><td>virtual-host</td>
    <td>forces all requests to this &lt;http&gt; to use the named virtual host</td>
    <td>none</td></tr>
<tr><td>openssl</td>
    <td>configures the port to use OpenSSL</td>
    <td>none</td></tr>
<tr><td>jsse-ssl</td>
    <td>configures the port to use JSSE for SSL</td>
    <td>none</td></tr>
</deftable-childtags>

<p>The <var>virtual-host</var> attribute overrides the browser's
Host directive, specifying the explicit host and port for
<code>request.getServerName()</code> and <code>getServerPort()</code>.
It is not used in most virtual host configurations.
Only IP-based virtual hosts which wish to ignore the browser's Host
will use @virtual-host.</p>

</defun>

<defun title="&lt;jvm-arg>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;jvm-arg> configures JVM arguments to be passed to Resin on
the command line, typically -X memory parameters and -D defines.</p>

<example title="standard jvm-args">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server-default>
      &lt;jvm-arg>-Xmx512m&lt;/jvm-arg>
      &lt;jvm-arg>-Xss1m&lt;/jvm-arg>
      &lt;jvm-arg>-verbosegc&lt;/jvm-arg>
    &lt;/server-default>

    &lt;server id="app-a" address="192.168.2.10"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;jvm-classpath>" version="Resin 3.1.6">
<parents>server</parents>

<p>&lt;jvm-classpath> adds a classpath entry when starting the JVM.</p>

<example title="adding a classpath">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server-default>
      &lt;jvm-classpath>/tmp/test-classpath;/jvm-classpath>
    &lt;/server-default>

    &lt;server id="app-a" address="192.168.2.10"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;keepalive-max>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;keepalive-max> configures the maximum number of sockets
which can be used directly for <g>keepalive</g> connections.
In Resin Professional, the <g>select manager</g> allows for
a much larger number of keepalive sockets, since it can detach
threads from connections.  Without the select manager, each
connection is associated with a thread.</p>

<p>A value of -1 disables keepalives.</p>

<p>Keepalives are an important TCP technique used with HTTP and
Resin's load-balancing to avoid the heavy network cost of creating
a new socket.  Since an initial HTTP request is usually immediately
followed by extra requests to load files like images and stylesheets,
it's generally more efficient to keep the socket open for a short time
instead of creating a new one.  The socket keepalive is even more
important for Resin's load balancing, to avoid creating extra sockets
between the web-tier and the app-tier and to make distributed sessions
more efficient.</p>

<p>Higher values of &lt;keepalive-max> improve network efficiency
but increase the number of threads waiting for new client data.</p>

<default>100</default>

<example title="keepalive-thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>

      &lt;thread-max>512&lt;/thread-max>

      &lt;keepalive-max>100&lt;/keepalive-max>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;keepalive-select-enable>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;keepalive-select-enable> enables the select manager for
keepalives.  The select manager is a Resin Professional feature allowing
more keepalives by detaching threads from sockets.</p>

<p>Normally, this should be left enabled.</p>

<default>true</default>
</defun>

<defun title="&lt;keepalive-select-thread-timeout>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;keepalive-select-thread-timeout> is a short timeout allowing
the select manager to wait for a keepalive before detaching the
thread.  This value would not normally be changed.d wou</p>

<default>1s</default>
</defun>

<defun title="&lt;keepalive-timeout>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;keepalive-timeout> configures how long a keepalive
connection should wait for a new request before closing.  </p>

<p>Keepalives are used both for HTTP connections and for load-balancing and
clustering connections.  HTTP connections generally have a single HTML page,
followed by a number of image requests.  By using keepalives, all the requests
can use a single socket.  The &lt;keepalive-timeout> should be long
enough to catch all the HTTP burst requests, but can close after the
burst is complete.  A value of 5s or 10s is generally sufficient.</p>

<p>The load-balancing and clustering keepalives have a different
timeout behavior.  Since load-balancing sockets are reused for multiple
clients, they can have longer timeouts.</p>

<default>10s</default>

<example title="keepalive-thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>

      &lt;thread-max>512&lt;/thread-max>

      &lt;keepalive-max>100&lt;/keepalive-max>
      &lt;keepalive-timeout>10s&lt;/keepalive-timeout>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;load-balance-connect-timeout>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;load-balance-connect-timeout> configures the maximum time
a client connection to a cluster-port should
take.  The <a href="resin-clustering.xtp">load balance</a> and
<a href="config-sessions.xtp">persistent sessions</a> use load-balance-connect-timeout
to connect to backend or peer servers in the cluster.</p>

<p>Lower values detect failed servers more quickly, but a too-low value
can timeout too quickly for a live server with some network congestion.</p>

<default>5s</default>

<example title="load-balance-connect-timeout">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-connect-timeout>2s&lt;/load-balance-connect-timeout>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;load-balance-recover-time>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;load-balance-recover-time> is the maximum time
the <a href="resin-clustering.xtp">load balancer</a>
will consider the server dead after a failure before retrying
the connection.</p>

<p>Resin uses the load-balance-recover-time to avoid wasting time trying to
connect to an unavailable app-tier server.</p>

<p>Lower values let the load balancer use a restarted <g>app-tier</g> server
faster, but lower values also increase the overhead of trying to
contact unavailable servers.</p>

<default>15s</default>

<example title="load-balance-recover-time">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-recover-time>10s&lt;/load-balance-recover-time>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;load-balance-idle-time>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;load-balance-idle-time> is the maximum time
the <a href="resin-clustering.xtp">load balancer</a>
and <a href="config-sessions.xtp">distributed sessions</a> will leave an
idle socket before closing it.</p>

<p>The default value is normally sufficient, since it tracks the
keepalive of the cluster port.</p>

<p>load-balance-idle-time must be less than the <var>keepalive</var> value of
the target <a href="port-tags.xtp#cluster-port">cluster-port</a>.</p>

<p>The load balancer and distributed sessions reuse sockets to the
cluster peer and <g>app-tier</g> servers to improve TCP performance.
The load-balance-idle-time limits the amount of time those sockets can
remain idle.</p>

<p>Higher values may improve the socket pooling, but may also increase
the chance of connecting to a closed server.</p>

<default>keepalive-timeout - 1s</default>

</defun>

<defun title="&lt;load-balance-warmup-time>" version="Resin 3.1">
<parents>server</parents>

<p>The time the <a href="resin-clustering.xtp">load balancer</a>
uses to throttle connections to an <g>app-tier</g> server that's just
starting up.</p>

<p>Java web-applications often start slowly while they initialize caches.
So a newly-started application will often be slower and consume more
resources than a long-running application.  The warmup-time increases
Resin's reliability by limiting the number of requests to a new
app-tier server until the server has warmed up.</p>

<p>Larger values give the application a longer time to warm up.</p>

<default>60s</default>

<example title="load-balance-warmup-time">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-warmup-time>60s&lt;/load-balance-warmup-time>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;load-balance-weight>" version="Resin 3.1">
<parents>server</parents>

<p>load-balance-weight assigns a load-balance weight to a backend server.
Servers with higher values get more requests.  Servers with lower
values get fewer requests.</p>

<p>In some cases, some <g>app-tier</g> servers may be more powerful than
others.  load-balance-weight lets the load-balancer assign more connections
to the more powerful machines.</p>

<p>Test and profiling servers can also use load-balance-weight to receive a
small number of connections for profiling purposes.</p>

<p>Larger values tell the load-balancer to assign more requests to
the app-tier server.</p>

<default>100</default>

<example title="load-balance-weight">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.10" port="6800"/&gt;

        &lt;server id="test" address="192.168.0.100" port="6800"&gt;
            &lt;load-balance-weight>1&lt;/load-balance-weight>
        &lt;/server>

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;memory-free-min>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;memory-free-min> improves server reliability by detecting
low-memory situations caused by memory leaks and forcing a
clean server restart.  Since Resin's <g>watchdog</g> service
reliably restarts the server, a website can improve stability by forcing
a restart before memory becomes a major problem.  The memory-free-min
restart will also log a warning, notifying the developers that
a potential memory leak needs to be resolved.</p>

<p>When free heap memory gets very low, the garbage collector can
run continually trying to free up extra memory.  This continual
garbage collection can send the CPU time to 100%, cause the site to
become completely unresponsive, and yet take a long time before finally
failing to an out of memory error (forcing an unclean restart).  To avoid this
situation, Resin will detect the low-memory condition and gracefully
restart the server when free memory becomes too low.</p>

<p>The ultimate solution to any memory leak issues is to get a
memory profiler, find the leaking memory and fix it.  &lt;memory-free-min>
is just a temporary bandage to keep the site running reliably until
the memory leak can be found and fixed.</p>

<default>1m</default>

<example title="memory-free-min resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;memory-free-min>1m&lt;/memory-free-min>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;port>" version="Resin 3.1">
<parents>server</parents>

<p>The server &lt;port> defines the TCP port for Resin
cluster communication and load balancing.  Most server instances
will use a common port like 6800, while machines with multiple
servers may use multiple ports like 6800 and 6801.</p>

<default>6800</default>

<example title="multipl servers on a machine ">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier"&gt;
    &lt;server id="app-a" address="192.168.1.11" port="6800"/>
    &lt;server id="app-b" address="192.168.1.11" port="6801"/>

    &lt;server id="app-b" address="192.168.2.12" port="6800"/>
    &lt;server id="app-c" address="192.168.2.12" port="6801"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;port-default>" version="Resin 3.2.1">
<parents>server</parents>

<p>Defines default port parameters for all &lt;http>, &lt;protocol>, and
&lt;cluster-port>.</p>

</defun>

<defun title="&lt;protocol>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;protocol> configures custom socket protocols using Resin's thread
and connection management.</p>

<p>The custom protocol will extend from com.caucho.server.port.Protocol.</p>

<example>
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
&lt;cluster id="web-tier"&gt;

  &lt;server id="a"&gt;
    &lt;protocol address="localhost" port="8888"&gt;
      &lt;type>example.Magic8BallProtocol&lt;/type>
    &lt;/port&gt;
  &lt;/server&gt;

&lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;server>" version="Resin 3.1">
<parents>cluster</parents>

<p>&lt;server> configures a JVM instance in the cluster.
Each &lt;server&gt; is uniquely identified by
its <var>id</var> attribute.  The <var>id</var> will match
the -server-id command line argument.</p>

<p>The server listens to an internal network address,
e.g. 192.168.0.10:6800 for clustering, load balancing,
and administration.</p>

<p>The current server is managed with a
<a href="javadoc|com.caucho.management.server.ServerMXBean">ServerMXBean</a>.
The <g>ObjectName</g> is <var>resin:type=Server</var>.</p>

<p>Peer servers are managed with 
<a href="javadoc|com.caucho.management.server.ServerConnectorMXBean">ServerConnectorMXBean</a>. The ObjectName is <var>resin:type=ServerConnector,name=server-id</var>.</p>

<deftable-childtags>
<tr><td>id</td>
    <td>unique server identifier</td>
    <td>required</td></tr>
<tr><td>address</td>
    <td>IP address of the cluster port</td>
    <td>127.0.0.1</td></tr>
<tr><td>port</td>
    <td>The cluster port</td>
    <td>6800</td></tr>
</deftable-childtags>

<example title="server">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server id="a" address="192.168.0.10" port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;server id="b" address="192.168.0.11" server-port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;server id="c" address="192.168.0.12" server-port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<p>Main configuration for the server, configuring ports,
threads and virtual hosts.</p>

<ul>
<li>Common resources for all virtual hosts and web-apps.</li>
<li>Thread pooling</li>
<li>HTTP and SRUN/Cluster ports</li>
<li>Caching</li>
<li>virtual host configuration and common web-app-default</li>
</ul>

<p>The &lt;server&gt; will generally contain a &lt;class-loader&gt; configuration
which loads the resin/lib jars dynamically, allowing for system-wide jars
to be dropped into resin/lib.  &lt;server&gt; configures
the main dynamic environment.  Database pools common to all virtual hosts,
for example, should be configured in the &lt;server&gt; block.</p>

<p>The &lt;server&gt; configures the &lt;thread-pool&gt; and a set
of &lt;http&gt; and &lt;srun&gt; ports which share the thread pool.
Requests received on those ports will use worker threads from the
thread pool.</p>

<deftable-childtags>
<tr><td>alternate-session-url-prefix</td>
    <td>a prefix to add the session to the beginning of the URL as a path
        prefix instead of the standard ;jsessionid= suffix. For clients like
        mobile devices with limited memory, this will allow careful web
        designers to minimize the page size.</td>
    <td>null</td></tr>
<tr><td>keepalive-max</td>
    <td>the maximum number of keepalive connections</td>
    <td>512</td></tr>
<tr><td>keepalive-thread-timeout</td>
    <td>the maximum time a connection is maintained in the keepalive state</td>
    <td>120s</td></tr>
</deftable-childtags>

<example title="alternate-session-url-prefix">
&lt;server&gt;
  ...
  &lt;alternate-session-url-prefix&gt;/~J=&lt;/alternate-session-url-prefix&gt;
  ...
</example>

<s2 name="server-el" title="EL variables and functions">
<deftable title="EL variables defined by &lt;server&gt;">
<tr><th>variable</th>
    <th>corresponding API</th></tr>
<tr><td>serverId</td>
    <td><i>server</i>.getServerId()</td></tr>
<tr><td>root-dir</td>
    <td><i>server</i>.getRootDirectory()</td></tr>
<tr><td>server-root</td><td><i>server</i>.getRootDirectory()</td></tr>
</deftable>

<deftable title="EL functions defined by &lt;server&gt;">
<tr><th>function</th>
    <th>corresponding API</th></tr>
<tr><td>jndi</td>
    <td><a href="javadoc|com.caucho.naming.Jndi|lookup(String)">Jndi.lookup(String)</a></td></tr>
</deftable>

</s2>

</defun>

<defun title="&lt;server-default>" version="Resin 3.1">
<parents>cluster</parents>

<p>&lt;server-default> defines default values for
all &lt;server&gt; instances.  Since most &lt;server> configuration
is identical for all server instances, the shared configuration belongs
in a &lt;server-default>.  For example, &lt;http> ports, timeouts,
JVM arguments, and keepalives are typically identical for all
server instances and therefore belong in a server-default.</p>

<example title="server">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server-default&gt;
           &lt;thread-max>512&lt;/thread-max>

           &lt;jvm-arg>-Xmx512m -Xss1m&lt;/jvm-arg>

           &lt;http port="8080"/&gt;
        &lt;/server-default&gt;

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;
        &lt;server id="c" address="192.168.0.12" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;shutdown-wait-max>" version="Resin 3.0">
<parents>server</parents>

<p>&lt;shutdown-wait-max> configures the maximum time the server
will wait for the graceful shutdown before forcing an exit.</p>

<default>60s</default>

</defun>

<defun title="&lt;socket-timeout>" version="Resin 3.1">
<parents>http, cluster-port, protocol, server</parents>

<p>&lt;socket-timeout> is the maximum time
a socket <a href="resin-clustering.xtp">load balancer</a>
and <a href="config-sessions.xtp">distributed sessions</a> will wait for
a read or write to a cluster socket.</p>

<p>Crashed servers may never respond to a read request or accept a write.
The socket-timeout lets Resin recover from these kinds of crashes.</p>

<p>Lower values can detect crashes more quickly, but too-low values may
report bogus failures when the server machine is just a little slow.</p>

<default>60s</default>

<example title="socket-timeout">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;socket-timeout>60s&lt;/socket-timeout>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;thread-idle-max>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;thread-idle-max> configures the maximum number of idle
threads in the thread pool.  &lt;thread-idle-max> works
with &lt;thread-idle-min> to maintain a steady number of idle
threads, avoiding the creation or destruction threads when possible.</p>

<p>&lt;thread-idle-max> should be set high enough beyond
&lt;thread-idle-min> so a spiky load will avoid
creating a thread and then  immediately destroying it.</p>

<default>10</default>

<example title="thread-idle-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;thread-idle-min>10&lt;/thread-idle-min>
      &lt;thread-idle-max>20&lt;/thread-idle-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;thread-idle-min>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;thread-idle-min> configures the minimum number of idle
threads in the thread pool.  &lt;thread-idle-min> helps spiky loads,
avoiding delays for thread requests by keeping threads ready for future
requests.  When the number of idle threads drops
below &lt;thread-idle-min>, Resin creates a new thread.</p>

<p>&lt;thread-idle-min> should be set high enough to deal with load
spikes.  Since idle threads are relatively inexpensive in modern operating
systems, having a number of idle threads is not a major resource hog,
especially since these threads are idle, waiting for a new job.</p>

<p>&lt;thread-idle-min> works together with &lt;thread-idle-max> to
avoid thread allocation thrashing, i.e. avoiding creating a new thread
because of &lt;thread-idle-min> and then quickly destroying it
because of &lt;thread-idle-max>.</p>

<default>5</default>

<example title="thread-idle-min in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;thread-idle-min>10&lt;/thread-idle-min>
      &lt;thread-idle-max>20&lt;/thread-idle-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;thread-max>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;thread-max> configures the maximum number of threads
managed by Resin's thread pool.  Resin's thread pool is used
for connection threads, timers, and Resin worker threads for JMS, JCA
and EJB.  Since Resin's thread pool only manages Resin threads,
the actual number of threads in the JVM will be higher.</p>

<p>Modern operating systems can handle a fairly large number of threads,
so values of 512 or 1024 are often reasonable values for thread-max.  The
main limitation for thread-max is virtual memory.  Since each thread
takes up stack space (configured with -Xss), a 32-bit system
might have a thread limit based on virtual memory.</p>

<p>For example, on Linux the user space is only 2G.  If the heap memory
is 1024m (-Xmx1024m) and the stack size is 1m (-Xss1m), the maximum
number of threads is somewhat less than 1024.</p>

<p>In general, JVMs do not handle running out of threads very well, either
freezing or throwing out of memory errors.  Although it may be necessary
to limit the number of threads to avoid running out of memory,
&lt;thread-max> should generally be set to a high value.</p>

<example title="thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

<default>4096</default>

</defun>

<defun title="&lt;user-name>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;user-name> configures the operating system user Resin should
run as.  Since the HTTP port 80 is protected in Unix, the web server
needs to start as root to bind to port 80.  For security, Resin should
switch to a non-root user after binding to port 80.</p>

<example title="resin.xml with user-name">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;http port="80"/>

      &lt;user-name>resin&lt;/user-name>
    &lt;/server-default>

    &lt;server id="web-a"/>
    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;watchdog-arg>" version="Resin 3.1">
<parents>server</parents>

<p>The &lt;watchdog-arg> configures arguments for the
watchdog process.  The watchdog improves reliability by
monitoring the Resin instance, restarting it if necessary.</p>

<p>The &lt;watchdog-arg> typically is used to enable <g>jconsole</g>
for the watchdog JVM.</p>

<example title="resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;server-default>

      &lt;watchdog-arg>-Dcom.sun.management.jmxremote&lt;/watchdog-arg>

    &lt;/server-default>

    ...
       
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;watchdog-port>" version="Resin 3.1">
<parents>server</parents>

<p>&lt;watchdog-port> configures the administration port for the
watchdog JVM.  The watchdog launches the server JVM and monitors its
health, restarting the JVM when necessary to improve site reliability.
The command line arguments use the watchdog-port for
the "start" and "stop" commands to tell the watchdog to start and
stop the server JVM.  The administration also uses the watchdog port
for watchdog administration.</p>

<p>The watchdog port will use the same &lt;address> as the server, so it
will always be an internal network address, never an external internet
address.</p>

<default>6700</default>

</defun>

</body>
</document>
