Overview

Core Configuration

Clustering: servers in a cluster

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.

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

HTTP and TCP ports: managing sockets and timeouts

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.

<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.

<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.

<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>
      </openssl>
    </http>
    
  </server-default>

  ...

Load Balancing: Socket Pooling, Timeouts, and Failover

JVM parameters: setting the JVM command line

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.

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