Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

resin.xml: server instance configuration


Configuration of JVM, threading, cluster, and TCP parameters for a server.

Overview

The reference for the <server> tag and its schema are at <server>.

  • Core configuration: the server's id, local TCP address and port which configure it in the cluster.
  • server-default: shared configuration for all servers belongs in a server-default.
  • cluster/cloud the server configuration in the cluster block defines the cluster.
  • JVM: JVM command-line parameters like -Xmx.
  • HTTP and TCP ports: configuring the server's HTTP ports.
  • Thread Pool: thread pool size and idle thread pool size.
  • Load balancing: timeouts and weights for the load balancer.
  • Watchdog: configuration for the server's watchdog.

Core Configuration

A cluster server has an "id", a local network "address" and a local network "port". For a standalone server, the address and port can be omitted, but the server cannot participate in a cluster or be managed from a command line.

The following example shows the minimal server for a two-server cluster. These servers do not listen to a HTTP port, so they are either a backend tier with a load-balancer or they are a non-HTTP use of Resin (like a SOA service.)

Example: minimal server in resin.xml
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="">

  <server id="a" address="192.168.1.10" port="6800"/>
  <server id="b" address="192.168.1.11" port="6800"/>

  ...

</cluster>
</resin>

Clustering: servers in a cluster

Each <server> becomes part of a cluster, the <cluster> that contains the server tag. Because each server has a local-network address and port, the servers can automatically communicate with each other. Essentially, there's no extra configuration needed for Resin clustering.

A Resin cluster uses a triple-redundant hub called the triad to store shared data and to coordinate cluster services like caching and JMS queues. If you have two servers, those servers will form the hub. The triple redundancy is important for reliability: the cluster can survive two triad servers going down. The hub-and-spoke topology is important for elastic cloud configurations: adding and removing servers just removes spokes without affecting the hub.

Typically, a site with many servers will configure at least the first three in the resin.xml, and use Resin's elastic-server capability for the remaining servers. Keeping the first three in the resin.xml ensures that all servers can connect to at least one of the triad even if one is down for maintenance or a restart.

Example: triad configuration in resin.xml
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="">

  <server id="a" address="192.168.1.10" port="6800"/>
  <server id="b" address="192.168.1.11" port="6800"/>
  <server id="c" address="192.168.1.12" port="6800"/>
    
  <dynamic-server-enable/>
  <resin:DynamicCloudService/>

  ...

</cluster>
</resin>

dynamic servers and --cluster

For more details see the clustering overview.

Elastic servers are added to a cluster using the command-line --elastic-server and --cluster option. The new server is assigned a server id from the command line, an IP address from the local network. The new server contacts the triad defined in the resin.xml and requests to be added. The triad updates the cluster topology and informs all servers about the new server.

Example: command-line for dynamic server
unix> bin/resin.sh start --cluster app-tier --elastic-server start

The new server will use configuration from the <server-default> in the cluster it's joining. It will automatically deploy applications which were deployed in the cluster, and will automatically join clustered caches, JMS queues, and load balancing.

When the server shuts down, the triad will hold its topology spot open for 15 minutes to allow for restarts. After the timeout, the triad will remove the server.

server-default

Most sites use a shared <server-default> to configure servers because parameters for a cluster's servers are usually identical. The HTTP ports, timeouts, keepalives, JVM and thread configurations can be shared easily. Servers that do need different configuration (like a staging server) can override the configuration in the <server> tag.

For example, the following defines a common set of JVM and HTTP configuration.

Example: basic http configuration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app">

  <server-default>
    <jvm-arg-line>-Xmx2048m</jvm-arg-line>
    
    <accept-thread-min>32</accept-thread-max>
    <accept-thread-min>64</accept-thread-max>
    
    <port-thread-max>256</port-thread-max>
    
    <http port="80"/>
  </server-default>

  <server id="a" address="192.168.1.10" port="6800"/>
  <server id="b" address="192.168.1.11" port="6800"/>
  ...

HTTP and TCP ports: managing sockets and timeouts

HTTP ports are typically configured in a <server-default> tag because a Resin servers in a cluster will typically all listen to the same HTTP port. If each server listens to a different HTTP port, the <http> tag is in the individual <server> block instead of the <server-default>.

The following example is a typical configuration for a Resin cluster where each server listens to the same HTTP port.

Example: basic http configuration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <http port="80"/>
  </server-default>
  
  <server id="a" address="192.168.1.10" port="6800"/>
  ...

Accept thread and connection pools

Each HTTP port has a thread pool which listens for new requests and processes them. The thread that accepts a HTTP connection will also process the request, and a new thread will be created to take its place listening for new requests. Since this HTTP thread pool is a child of Resin's main thread pool, the Resin threads limits and management automatically apply.

port-thread-max is the maximum thread count for handling a port's requests. If more requests arrive than threads, the requests will be queued until a thread becomes available. You can use port-thread-max to limit the maximum load on a server.

accept-thread-min sets the minimum number of threads which are concurrently accepting a new connection. If the thread count drops below accept-thread-min, Resin will spawn a new thread to accept() the connection. If you look at a thread dump, there will always be at least this many threads in the accept() method. A larger value for accept-thread-min improves load-spike handling.

accept-thread-max sets the maximum number of threads which are concurrently accepting a new connection. When a request completes, it normally tries to accept a new connection, but when accept-thread-max threads are already listening, the thread will exit instead. A larger gap between accept-thread-min and accept-thread-max reduces thread churning.

connection-max limits the total requests/connections allowed at any time. Typically this will be very large because most sites will never need to throttle the connections.

throttle-concurrent-max limits the concurrent requests from a single IP address. This limit can help with denial-of-service attacks.

The following example show a typical configuration for the HTTP accept pool. The example tags are in the <server-default> instead of the <http> for convenience, since both <http> ports 80 and 81 need the same configuration. If the two <http> ports needed different values, you would put the <accept-thread-min> tag inside the <http> port itself.

Example: configuring the accept thread pool
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <accept-thread-min>32<accept-thread-min><accept-thread-max>64<accept-thread-max>

    <http port="80"/>
    <http port="81"/>
  </server-default>

  ...

HTTP socket timeouts and configuration

socket-timeout configures the read and write timeout for the socket to protect against network hangs and denial-of-service attacks. When Resin reads a HTTP request or POST data, it uses the socket-timeout to limit how long it will wait. Resin also uses socket-timeout on the response writes to disconnect from frozen clients.

The socket-timeout must be at least 65s because of browser requirements.

If you have a long-polling application, you will probably need to increase the default socket-timeout to your long-polling time.

Example: socket-timeout for a HTTP port
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <socket-timeout>120s<socket-timeout>

    <http port="80"/>
    <http port="81"/>
  </server-default>

  ...

Keepalive configuration

HTTP keepalives improve performance by letting browsers reuse the same TCP socket for new requests, for example images and javascript files from a main page. You can balance the added efficiency against the extra sockets and threads in the <server> and <http> keepalive configuration.

To handle many keepalive sockets with fewer threads, Resin Pro has a "keepalive-select" manager which detaches the thread from its connection and reuses the thread. The keepalive-select manager allows for tens of thousands of connections as many as your operating system will allow file descriptors.

keepalive-timeout will close the socket if the browser waits too long before sending a new request. Because requests are bursty, even a small value like 10s can improve performance.

keepalive-max defines the maximum connections waiting for keepalive requests. With the keepalive-select manager or a 64-bit system, this can be a large number. It's generally better to limit the keepalives using keepalive-timeout instead of keepalive-max.

keepalive-select-enable lets you disable the keepalive-select manager. Because modern 64-bit operating systems handle threads efficiently, it can be more efficient to use the connection thread to wait for a new request. However, the keepalive-select-thread-timeout may be a better choice in that situation.

keepalive-select-thread-timeout sets a short thread-based keepalive timeout waiting for the next request before going to the select manager. Because keepalive requests are bursty and thread-based keepalive is faster, Resin waits for a short time. You can increase the performance with a slight increased thread count by increasing keepalive-select-thread-timeout.

Openssl and Jsse

For more information see the SSL page.

HTTP ports can use either OpenSSL (faster) or JSSE to support SSL ports. The SSL configuration tags belong inside the <http> tag.

Example: OpenSSL HTTP configuration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
  
    <http port="443">
      <openssl>
        <certificate-file>keys/mycert.crt</certificate-file>
        <certificate-key-file>keys/mycert.key</certificate-key-file>
        <password>mypassword</password>
        <protocol>-sslv3</protocol>
      </openssl>
    </http>
    
  </server-default>

  ...

Load Balancing: Socket Pooling, Timeouts, and Failover

For efficiency, Resin's load balancer manages a pool of sockets connecting to the app-tier servers. If Resin forwards a new request to an app-tier server and it has an idle socket available, it will reuse that socket, improving performance an minimizing network load. Resin uses a set of timeout values to manage those idle sockets and to handle any failures or freezes of the backend servers. The following diagram illustrates the main timeout values:

web-a:connecty-timeout,app-a:socket-timeout,web-a:recover-time,app-a:keepalive-timeout,web-a:idle-time
  • load-balance-connect-timeout: the load balancer timeout for the connect() system call to complete to the app-tier (5s).
  • load-balance-idle-time: load balancer timeout for an idle socket before closing it automatically (5s).
  • load-balance-recover-time: the load balancer connection failure wait time before trying a new connection (15s).
  • load-balance-socket-timeout: the load balancer timeout for a valid request to complete (665s).
  • keepalive-timeout: the app-tier timeout for a keepalive connection (15s)
  • socket-timeout: the app-tier timeout for a read or write (65s)

JVM parameters: setting the JVM command line

JVM command-line parameters are configured in the <server> tag. When launching Resin, the watchdog process will read the <server> tag and add the JVM argument to the launched command-line.

Because most servers in a cluster are identical, you'll generally put the JVM configuration in a <server-default>. If you have some servers with different requirements, you can configure the JVM in <server>.

Example: -Xmx2048m in server-default
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="">

  <server-default>
    <jvm-arg>-Xmx2048m</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>

setuid: user-name and group-name

Because Unix requires root access to bind to port 80 and 443, Resin can change from root (the watchdog) to a specific user (the Resin server). The user-name and group-name tags in the <server> set the user to run as.

Example: user-name and group-name
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="">

  <server-default>
    <user-name>resin</user-name>
    <group-name>resin</group-name>
  </server-default>

  ...

</cluster>
</resin>

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.