1. Request arrives at web server.
2. Plugin (mod_caucho, mod_isapi, etc) checks if it's a Resin request
3. Plugin selects a backend JVM, i.e. a <srun>
   • If it's an old session, send it to the owner JVM. (sticky-sessions)
   • If it's a new request, send it to the next <srun>, using a round-robin policy.
4. Plugin sends the request to the backend JVM with a TCP socket.
5. Plugin receives the response from the backend JVM with the same TCP socket.

The plugin needs to know which requests should go to Resin, i.e. the servlet-mappings. And it needs to know the TCP host/port names of the backend machines, i.e. the <srun> and <srun-backup> tags. /caucho-status shows all that information in one table. All the plugins and the JVMs can read the same resin.conf, making maintenance easier.

The plugin controls the load balancing since it needs to decide which JVM to use. Because the plugin is key in load-balancing, looking at the /caucho-status will tell you exactly how your system is configured. The JVMs are just passive, waiting for the next request. From the JVM-perspective, a request from a plugin is identical to an HTTP request, except it uses a slightly different encoding. In fact, with Resin 1.2, the same JVM can server as an srun and as an httpd listening to port 8080, for example. The dual srun/http configuration can be useful for debugging.

Selecting a free JVM is done using a round-robin policy. Although the round-robin policy is simple, in practice it is as effective as complicated balancing policies. In addition, because it's simple, round-robin is more robust and faster than adaptive policies.

<caucho.com>
<http-server>

  <srun id="a" host='localhost' port='6802' srun-index='1'/>
  <srun-backup id="b" host='localhost' port='6803' srun-index='2'/>

  ...
  
</http-server>
</caucho.com>

You will start the two srun processes separately. Each srun needs to know which port to listen to. The -server argument to srun.sh selects a srun block to start. -server a selects the first one, i.e. port 6802 and -server b selects the second one.

Here's how to start them on unix:

unix> srun.sh -pid srun1.pid -server a start unix> srun.sh -pid srun2.pid -server b start

On Unix, the -pid is used to keep track of the live srun so a later srun.sh stop will work. It just names a file that will contain the process id (pid) of the started process.

And here's how to install them on NT:

c:\resin1.2> bin/srun -server a -install-as ResinA c:\resin1.2> bin/srun -server b -install-as ResinB

On Unix, the -pid is used to keep track of the live srun so a later srun.sh stop will work. It just names a file that will contain the process id (pid) of the started process.

To make sure that your web server understands the configuration, look at http://host/caucho-status. caucho-status will show the current state of all the JVMs.

• The webserver plugin (mod_caucho, or isapi_srun) looks in the resin.conf for <srun> and <srun-backup> elements.
• /caucho-status shows all the servlet runners and backups.
• srun.sh -server a start the srun with id="a".
• The plugin will always send a session to the same backend srun.

Once you start using multiple computers, you can start distributing the load between a single web server and multiple JVMs. This is a cheap alternative to a router-based load balancer. Also, by using Resin's load balancing, you can make sure that sessions stay on the same machine.

<caucho.com> <http-server> <srun id="1" host='host1' port='6802' srun-index='1'/> <srun id="2" host='host2' port='6802' srun-index='2'/> <srun id="3" host='host3' port='6802' srun-index='3'/> ... </http-server> </caucho.com>

Each host and the plugin can share the same resin.conf. Sharing the resin.conf makes maintenance easier, since the files won't get out of sync.

However, you could use a different resin.conf for plugin and for each of the JVMs. The resin.conf for the plugin, e.g. mod_caucho, just needs enough information to list the <srun> hosts and enough servlet-mappings to tell the plugin where to send the requests.

• The webserver plugin (mod_caucho, or isapi_srun) looks in the resin.conf for <srun> and <srun-backup> elements.
• The webserver plugin can share the same resin.conf as the JVMs.
• srun.sh -server a starts the srun with id="a".
• The plugin sends a session to the same backend srun.
• New sessions or non-session requests balance the load with a round-robin policy.

A session needs to stay on the same JVM that started it. Otherwise, each JVM would only see every second or third request and get confused.

To make sure that sessions stay on the same JVM, Resin encodes the cookie with the host number. In the previous example, the hosts would generate cookies like:

srun-index	cookie prefix
1	aaaxxx
2	baaxxx
3	caaxxx

Note: srun-index only exists in Resin 1.2.3. If unspecified, it defaults to the index of the srun in the srun list.

On the web server, mod_caucho will decode the cookie and send it to the appropriate host. So baaX8Zwoo would go to host2.

In the infrequent case that host2 fails, Resin will send the request to host3. The user will lose the session but that's a minor problem compared to showing a connection failure error. To save sessions, you'll need to use distributed sessions.

In this configuration, the site needs to take control of its own sessions. Because the router will distribute the load randomly, any persistent session state needs to be handled by a centralized server like a database.

Even in this configuration, you can use Resin's load balancing to increase reliability. Each web server should choose its own JVM first, but use another machine as a backup.

In this case, you can use the trick that localhost refers to the preferred host. The configuration would look like:

<caucho.com> <http-server> <srun id="a" host='localhost' port='6802' srun-index='1'/> <srun-backup id="b" host='host1' port='6802' srun-index='2'/> <srun-backup id="c" host='host2' port='6802' srun-index='3'/> <srun-backup id="d" host='host3' port='6802' srun-index='4'/> ... </http-server> </caucho.com>

Alternately, if you're using Apache, you could configure the sruns in the httpd.conf.

host1 httpd.conf

CauchoConfigFile /home/www/resin/conf/resin.conf CauchoHost host1 6802 CauchoBackup host2 6802

host2 httpd.conf

CauchoConfigFile /home/www/resin/conf/resin.conf CauchoBackup host1 6802 CauchoHost host2 6802

I've made the order consistent so sessions will always go to the correct machine. baaXXX will always go to host2. Normally, of course, sites using this configuration will handle their own cookies.

Multiple web servers can use the same JVM. For example, a fast plain webserver and an SSL web server may only need a single JVM. (Although a backup would be good.) Since the JVM doesn't care where the request comes from, it can treat each request identically.

This simplifies SSL development. A servlet just needs to check the request.isSecure() method to see if the request is SSL or not. Other than that, all requests are handled identically.

By default, if mod_caucho can't connect to any of the JVMs, it will return a basic "can't connect" page to the user. Sites which want a more professional response can redirect the user to an error page.

In the resin.conf, you'll use:

<caucho.com> <http-server> <error-page exception='connection' location='/error.html'/> </http-server> </caucho.com>

The error page must be an absolute path because it could be called from any url. Of course, it can't refer to a servlet or to a JSP file.