Resin Installation

From Resin 3.0

Revision as of 07:29, 17 December 2009 by Reza (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

 <header>
   <product>resin</product>
   <version>Resin 4.0</version>
   <title>Resin Installation</title>

   <description>

Resin Step-by-Step Installation Guide If you've decided that you're ready to deploy Resin for production, this page will guide you through the steps to install this powerful application server system-wide. You'll see where we recommend installing the various components of Resin as well as some basic production tuning tips.

   </description>
 </header>

 <body>

   <localtoc/>

This page is for you if you:

Are evaluating Resin
Want to do local application development with Resin
Have evaluated Resin and are ready to install system-wide

This page leads you step-by-step through the installation of Resin. After going through these steps, you'll have a full Java and PHP Application Server able to serve even the most demanding web sites.

You'll learn:

How to install Resin system-wide
The recommended installation locations for Resin
How to run the Resin administration application

Install JDK 1.5 or later. You'll need to set the JAVA_HOME variable in your shell or link /usr/java to the Java home directory.
Download the latest version of Resin 4 from the <a href="http://www.caucho.com/download">Resin download page</a>. Grab the Professional version if:
- You have purchased a Resin Professional license.
- You have obtained an evaluation Resin Professional license.
- You are considering purchasing Resin Professional (without a license, Resin Professional simply downgrades to the open source functionality). This will make it easier to upgrade in the future.
Unzip or untar the Resin download. If you downloaded Resin Professional, it will unzip into resin-pro-4.x.x/, otherwise it will download into resin-4.x.x/.

</s2>

If you're installing Resin on Windows, you can skip to the next section. If you're installing Resin on Ubuntu or Debian and want to use the .deb packaged version of Resin, skip to the end of this section.

Next we'll change into the Resin directory we just unpacked to configure and build the server. The Java portions of Resin are already compiled, but this step will build additional C-based components of Resin that provide additional functionality such as:

A faster IO library, including massive keepalive support *
Support for OpenSSL *
The ability to run as a non-priviledged user for security
Connector modules for Apache

(* only available in Resin Professional)

The following command installs Resin and its files into the recommended locations on the file system:

<example> ./configure --prefix=/usr/local/resin \

           --with-resin-root=/var/www \
           --with-resin-log=/var/log/resin \
           --with-resin-conf=/etc/resin

</example>

This will configure Resin to install in /usr/local/resin, with support for OpenSSL if it was detected, but without support for Apache. If you want to use Apache or another 3rd party HTTP server in front of Resin (unrecommended), please take a look at our <a href="install-3rd-party.xtp">third-party HTTP server setup documentation</a>. If you need to configure other options with Resin, now is the time to do it. Please consult the <a href="configure.xtp">reference to all the configuration options</a>.

Once you've run the configuration successfully, the configure script will display a summary like the following:

<example> Resin Configuration summary:

 RESIN_HOME: /usr/local/resin
     root: /var/www
     conf: /etc/resin/conf
     log : /var/log/resin
     init: /etc/init.d/resin

 + epoll() for keepalives
 + OpenSSL 0.9.8g 19 Oct 2007
     OpenSSL include: /usr/include
     OpenSSL lib: /usr/lib
     OpenSSL libraries:  -lssl -lcrypto

 JAVA_HOME: /usr/lib/jvm/java-6-sun
   + 32-bit JNI in -I/usr/lib/jvm/java-6-sun/include \
                   -I/usr/lib/jvm/java-6-sun/include/linux
     JNI CFLAGS: -g -O2 -DPOLL -DEPOLL -D_POSIX_PTHREAD_SEMANTICS \
                 -DHAS_SOCK_TIMEOUT -DHAS_JVMTI

</example> </s3>

Now that you've configured the Resin build process, all you need to do is build and install! To build, just run

If this step went well, you'll now need to install the Resin files as the root user:

<example> sudo make install </example>

Where ever you install Resin to, we'll refer to that directory as resin.home.

If you have a license file for Resin, save it in /usr/local/resin/licenses

</s3>

We provide a Debian packaged version of Resin that Debian and Ubuntu users can take advantage of. It performs all of the installation steps above for you and creates all the recommended server and content directories. Simply download from the <a href="http://caucho.com/download">Resin download page</a> and install using dpkg.

Alternatively, you can add Caucho's Debian repository to your system's repositories to use automated update tools like Synaptic and apt-get. To do this, add the following line to your /etc/apt/sources.list

<example> deb http://caucho.com/download/debian/ unstable universe deb http://caucho.com/download/debian/ unstable multiverse </example>

After adding this line, update your local repository cache by running:

<example> apt-get update </example>

Finally, install Resin Professional using the following:

<example> apt-get install resin-pro </example>

If you have a license file for Resin, save it in /usr/local/resin/licenses

Or install Resin Open Source with this command:

<example> apt-get install resin </example> </s3> </s2>

The native libraries that are included with Resin are precompiled for Windows in both 32-bit and 64-bit mode. These libraries provide:

A faster IO library, including massive keepalive support *
Support for OpenSSL *
Connector modules for Apache/IIS

(* only available in Resin Professional)

Download the latest version of Resin 4 from the <a href="http://www.caucho.com/download">Resin download page</a>. Grab the Professional version if:
- You have purchased a Resin Professional license.
- You have obtained an evaluation Resin Professional license.
- You are considering purchasing Resin Professional (without a license, Resin Professional simply downgrades to the open source functionality). This will make it easier to upgrade in the future.
Unzip or untar the Resin download. If you downloaded Resin Professional, it will unzip into resin-pro-4.x.x\, otherwise it will download into resin-4.x.x\.
Move the directory from the previous step to C:\Resin
Run C:\Resin\setup.exe
If you have a license file for Resin, save it in C:\Resin\licenses

</s2> </s1>

Once your have the Resin server installed, you can start installing your content.

Resin and JavaEE organize content into "web applications" or webapps. As an administrator, your developers have probably provided you with a webapp in the form of a .war file or a webapp directory. In the Resin root directory is a special subdirectory named webapps which is a webapp deploy directory. Deploying applications in Resin is as easy as copying a .war file or web application directory to one of these webapp deploy directories. Resin detects the applications and deploys them automatically.

In the directory structure above, notice the special webapp directories named "ROOT". These will map to the "/" (root) application. Other webapps will map to their name. For example, "wordpress" will map to "http://www.example.com/wordpress".

</s2>

Resin is configured to use the content directory structure show above by default. In the examples, the Resin root directory is /var/www. This directory is also the recommended content root for Unix. For Windows, the recommended content root is C:\www. To specify the root directory to Resin, you pass it on the command line when starting the server. For example:

<example> java -jar ${resin.home}/lib/resin.jar --root-directory /var/www start </example>

If you use the Unix startup scripts mentioned in the next section, they automatically specify the root and log directories.

</s2> </s1>

When you installed using the .deb package or when you ran "make install" earlier, the installer created a file named /etc/init.d/resin which contains a standard Unix init.d startup file. This file will start Resin when invoked as:

<example> /etc/init.d/resin start </example>

Use the tools that came with your system to execute the script on startup.

</s2> <s2 title="Installing Resin as a Windows Service">

Resin can install itself as a Windows Service by executing the resin.exe with the -install command line option. If you pass other options to resin.exe along with the -install option, such as specifying a server or content directory, these will be used when the service is started. To install Resin as a Windows Service using the default options, simply run:

<example> C:\Resin\resin.exe -install </example>

You can also install Resin using a specific service name or install multiple Resin services using the -install-as option:

<example> C:\Resin\resin.exe -install-as ResinA </example> <s3 title="Running resin.exe on Windows Vista and Windows Server 2008">

Note: the command prompt i.e. cmd.exe on Windows Vista and Windows Server 2008 will need to be run with administrative priviliges by choosing "Run As Administrator" from the context menu(given by Windows on right click). The cmd.exe locations for Windows Vista and Windows Server 2008 are %WINDIR%/system32 and %WINDIR%/sytemwow64 respectively.

</s3> </s2> </s1>

One of the most useful tools provided with Resin is the built-in, web-based administration console. This tool provides detailed information about the operation of the server, a feature that is very useful to administrators, but one which must be kept secure from unauthorized users.

If you are deploying Resin to a production machine, it's likely that you won't be running your browser on the same system as the server. In this case, you'll need to configure Resin to allow you to access the server remotely.

Edit /etc/resin/resin.xml
Change the line: <example> <resin:set var="resin_admin_external" value="false"/> </example>
to
```
   <example>
```
<resin:set var="resin_admin_external" value="true"/>
```
   </example>
```
Save /etc/resin/resin.xml and restart the server.
Replace "localhost" with the name of your host in the URLs below.

Now that you're able to access the administration application, you have to set up a password and install it. In order to prove that you have access to the machine on which Resin is running, the only way to change the password is to create a file with the authentication information on that machine.

Browse to http://localhost:8080/resin-admin/
Enter a username and password in the lower half of the page, then click "Create Configuration File". The recommended username is "admin". <figure src="admin-password-create.png"/>
After going to the next page, a new "admin-users.xml.generated" file has been created for you in the same directory as your resin.xml file is located. (If you followed the directions above, this should be in /etc/resin for Unix and C:\Resin\conf for Windows.) Just rename this file to admin-users.xml and Resin will use it to <figure src="admin-password-save.png"/>
Browse back to http://localhost:8080/resin-admin/. The change you made should force Resin to restart and return a 503 error. Just hit refresh in a few moments to bring up the page again.
You should now be able to login using the username and password that you gave above.

</s1>

If something went wrong above, the first place to check for problems is the log.

If you are using Unix, look in /var/log/resin/jvm_default.log
If you are using Windows, look in C:\Resin\log\jvm_default.log

Hopefully, the log message will be clear enough for you to figure out the problem. If not, you have a number of resources available to you to help you figure out what's going wrong:

The <a href="http://maillist.caucho.com/">Resin mailing list</a>.
The <a href="http://forum.caucho.com/">Resin Forums</a>.
<a href="mailto:presales@caucho.com">Presales technical support</a> for those considering purchasing Resin Professional.
<a href="http://store.caucho.com/">Paid technical support</a> directly from the Resin developers.

</s1>

</body> </document>

 <header>
   <product>resin</product>
   <title>Resin with Apache and IIS</title>
   <description>

Resin provides a fast servlet runner for Apache 2.2, and IIS allowing these HTTP servers to dispatch requests to Resin.

   </description>
 </header>

<body>

Before integrating Resin with Apache, it is valuable to configure Resin as a <a href="install.xtp">standalone server</a>, especially with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

Many users find that the performance, flexibility, and features of Resin make it a desirable replacement for Apache and IIS. These 3rd party HTTP servers add overhead to Resin's operation, therefore you should have a specific reason to run one of them with Resin.

</s1>

When used with Apache, Resin serves JSPs and Servlets and Apache serves static content like html and images. Apache is a frontend server, it handles the request from the browser. Resin's mod_caucho plugin integrates with Apache, it dispatches requests for JSPs and Servlets to one or more backend Resin servers.

mod_caucho queries the backend server to distinguish the URLs going to Resin from the URLs handled by Apache. The backend server uses the <servlet-mapping> directives to decide which URLs to send. Also, any *.war file automatically gets all its URLs. Other URLs stay with Apache.

There's a more complete discussion of the URL dispatching in the <a href="../doc/plugin-dispatch.xtp">How the Plugins Dispatch to Resin</a> page.

</s2>

Resin needs Apache 2.x or greater and DSO support. You probably have DSO support, but if you're not sure, you can check for mod_so.c when running httpd -l:

<example title="checking apache httpd for mod_so.c"> unix> /usr/local/apache/bin/httpd -l Compiled-in modules:

 ...
 mod_so.c
 ...

</example>

If you don't have DSO support, you can recompile Apache or install another package from your operating system vendor. Check their documentation for more details.

Compiling mod_caucho on Unix is usually as easy as changing the way that you configure Resin during installation:

Locate the apxs program that is included with Apache.
Follow the <a href="install.xtp">Resin installation instructions</a>. In addition to any other configure script options, add the --with-apxs option. Assuming that your apxs program is in /usr/sbin/apxs, you might run configure in the following way: <example> unix> ./configure --with-apxs=/usr/sbin/apxs --prefix=/usr/local/resin </example>
Run make and make install as specified in the installation instructions. In addition to building the normal Resin native libraries, these steps will also build mod_caucho, install it, and add some directives to the end of your httpd.conf file configuring mod_caucho.

</s3>

</s2>

The setup.exe program installs the mod_caucho.dll plugin for any Apache it finds, and modifies the Apache httpd.conf file.

The httpd.conf file is also easily modified manually:

<example title="httpd.conf"> LoadModule caucho_module \

   <resin.home>/win32/apache-2.0/mod_caucho.dll

ResinConfigServer localhost 6800 <Location /caucho-status>

 SetHandler caucho-status

</Location> </example>

Replace win32 with win64 above if you're using a 64-bit version of Apache.

</s2>

The communication between mod_caucho and the backend Resin server takes place using a server port.

The resin.xml for the backend server contains a server to enable the port. The default resin.xml has an server listener on port 6800.

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin"

      xmlns:resin="urn:java:com.caucho.resin">
 ...
 <cluster id="app-tier">
   ...
   <server id="" address="127.0.0.1" port="6800"/>
   ...

</example>

The resin.xml and the layout of your webapps should match the layout that Apache expects. The mapping of urls to filesystem locations should be consistent between Apache and the backend Resin server.

The default resin.xml looks in <resin.root>/webapps/ROOT for JSP files and <resin.root>/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use Apache's document area, you configure an explicit web-app with the appropriate document-directory:

<example title="resin.xml"> <resin xmlns="http://caucho.com/ns/resin"

      xmlns:resin="urn:java:com.caucho.resin">
 ...
 <cluster id="">
   ...
   <host id="">
     <web-app id='/' document-directory="/usr/local/apache/htdocs"/>
   </host>
   ...
 </cluster>

</resin> </example>

</s2>

The ResinConfigServer is used to tell mod_caucho how to contact the backend Resin server. The backend Resin server tell's mod_caucho which urls should be dispatched.

<deftable> <tr><th>Apache Command</th><th>Meaning </th></tr><tr><td>ResinConfigServer host port</td><td>Specifies the Resin JVM at host:port as a configuration server. </td></tr></deftable>

The caucho-status handler is optional and probably should be avoided in a production site. It lets you ask the Caucho Apache module about it's configuration, and the status of the backend server(s), valuable for debugging.

After any change to httpd.conf, restart Apache. Now browse http://localhost/caucho-status.

You can also dispatch to Resin directly from the httpd.conf. Instead of relying on the ResinConfigServer directive to determine which url's to dispatch to the backend server, Apache handler's are used to specify the url's to dispatch.

<example> CauchoHost 127.0.0.1 6800

 SetHandler caucho-request

</Location> </example>

 <th width="30%">Apache Command</th>
 <th>Meaning</th>

</tr> <tr>

 <td>CauchoHost host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with an server port at host:port as a backend server.</td>

</tr> <tr>

 <td>CauchoBackup host port</td>
 <td>Alternative to ResinConfigServer, adds the Resin JVM with
 a server port at host:port as a backup backend server.

</td> </tr> </deftable>

 <th width="30%">Apache Handler</th>
 <th>Meaning</th>

</tr> <tr>

 <td>caucho-status</td>
 <td>Handler to display /caucho-status</td>

</tr> <tr>

 <td>caucho-request</td>
 <td>Dispatch a request to Resin</td>

</tr> </deftable>

Requests dispatched directly from the Apache httpd.conf will not appear in /caucho-status.

</s3>

</s2>

The <a href="../admin/load-balancing.xtp">Load Balancing</a> section provides an introduction to the concepts of load balancing.

mod_caucho recognizes cluster configurations for load balancing. Requests are distributed to all machines in the cluster, all requests in a session will go to the same host, and if one host goes down, Resin will send the request to the next available machine. Optional backup machines only receive requests if all of the primaries are down.

mod_caucho only needs to know about one of the backend servers. It will query that backend server, and learn about all of the other members of the cluster. mod_caucho keeps a local cache of the configuration information, so if the backend server becomes unavailable then the cached configuration will be used until the backend server becomes available again.

The httpd.conf file can also specify more than one backend server, when mod_caucho checks for configuration updates, it will check each in turn, and only if none of them are available will it use the local cached copy.

<example> ResinConfigServer 192.168.0.11 6800 ResinConfigServer 192.168.0.12 6801 </example>

Manual dispatching in httpd.conf can also specify the backend hosts and the backend backup hosts, as an alternative to using ResinConfigServer.

<example> CauchoHost 192.168.0.11 6800 CauchoBackup 192.168.0.11 6801 CauchoHost 192.168.0.12 6800 CauchoBackup 192.168.0.12 6801

 SetHandler caucho-request

</Location> </example>

</s3>

 ResinConfigServer 192.168.0.11 6800

</Location>

 ResinConfigServer 192.168.0.12 6800

</Location> </example>

</s3>

</s2>

Check your configuration with Resin standalone. In other words, add a <http port='8080'/> and check port 8080.
Check http://localhost/caucho-status. That will tell if mod_caucho has properly connected to the backend Resin server. Each server should be green and the mappings should match your resin.xml.
If caucho-status fails entirely, the problem is in the mod_caucho installation and the Apache httpd.conf.
If caucho-status shows the wrong mappings, there's something wrong with the resin.xml or the pointer to the backend server in httpd.conf.
If caucho-status shows a red servlet runner, then Resin hasn't properly started.
If you get a "cannot connect to servlet engine", caucho-status will show red, then Resin hasn't started properly.
If Resin doesn't start properly, you should look at the logs in <resin.log>/log. You should start java -jar <resin.home>/lib/resin.jar -verbose or resin.exe -verbose to get more information.
If Resin never logs a "hmux listening to *:6800" line, it's not listening for connections from mod_caucho. You'll need to add a <server> line.
If you get Resin's "file not found", the Apache configuration is functional but the resin.xml probably points to the wrong directories.

</s2> </s1>

     <figure src="iis_srun.gif"/>

Configure the following two environment variables in the Control Panel:

<example> JAVA_HOME=C:\jdk1.5.0 RESIN_HOME=C:\Resin </example>

Of course, adjust these to the correct directories for Java and Resin if they differ from your own.

</s2>

To configure Resin with IIS, you must follow the following steps:

Configure IIS/PWS
Configure resin.xml
Start resin.exe

You should run RESIN_HOME/setup.exe to setup your configuration. If setup.exe is not used, or it fails, the steps in <a href="#Manual-Configuration">Manual Configuration</a> are necessary.

</s3>

isapi_srun.dll installs itself as the default priority. Some users may need to set the priority to a higher level, e.g. to override IIS's DAV support.

<example title="resin.ini"> ResinConfigServer localhost 6802 CauchoStatus yes IISPriority high </example>

</s3>

resin.xml should mirror the configuration of IIS. In other words, you need to configure the document root and any directory aliases.

For many users, the only need to change needed in Resin is to change the <a config-tag="document-directory"/> attribute from 'webapps/ROOT' to something like 'C:/inetpub/wwwroot'. The mapping of url paths from the browser to real files on the disk must be the same for Resin as they are for IIS. For more complicated configurations that use mappings in IIS, you'll need to add <a href="webapp-tags.xtp">path-mapping</a> attributes to match.

 <!-- configures the default host, matching any host name -->
 <host id="">

 <!-- configures the root web-app -->
 <web-app id='/'>
   <root-directory>C:/inetpub/wwwroot</root-directory>
   <!-- adds xsl to the search path -->
   <class-loader>
     <simple-loader path="$host-root/xsl"/>
   </class-loader>
 </web-app>

</host>

</cluster> </cluster> </example>

</s3>

</s2>

Resin's IIS plugin supports load balancing in much the same way as mod_caucho does for Apache. Consult the <a href="#balance">mod_caucho load balancing section</a> for more details.

</s2>

Experts may want to configure Resin/IIS by hand instead of using the setup program. The steps involved are:

Make sure resin.exe works
Copy isapi_srun.dll to the IIS scripts directory, d:\inetpub\scripts.
You may need to run net stop w3svc to get permission to overwrite the file.
If you have a virtual site (virtual hosts), you must configure IIS to have
the virtual directory /scripts point to d:\inetpub\scripts for each virtual site.
(optional) Create a resin.ini in d:\inetpub\scripts pointing to the ResinConfigServer
(optional) Add a "CauchoStatus yes" line to the resin.ini for debugging
Configure IIS to load isapi_srun.dll as an ISAPI filter.
Restart IIS (control panel/services) or net stop w3svc followed
by net start w3svc.
Browse /servlet/Hello and /foo.jsp.
You should see a "cannot connect" error.
Start resin.exe
Browse /servlet/Hello and /foo.jsp. You should now see the servlet.

Copying isapi_srun.dll to inetpub/scripts directory is relatively straightforward. If you're upgrading to a new version of Resin, you may need to stop IIS (control panel/services) to get permission to overwrite isapi_srun.dll.

The resin.ini is an optional file in inetpub/scripts to override the automatic registry $RESIN_HOME/conf/resin.xml configuration file. If you only have one Resin server, you should not create a resin.ini and let isapi_srun.dll use the registry value set by the setup.exe program.

resin.ini is only needed if you have multiple Resin configuration files for different IIS virtual hosts.

The resin.ini should contain the following line:

<example> ResinConfigServer localhost 6802 </example>

You can change the host from localhost to a backend server. You can also add multiple ResinConfigServer items to cluster the configuration.

For debugging, you can add a "CauchoStatus yes" line to the resin.ini:

<example> ResinConfigServer localhost 6802 CauchoStatus yes </example>

For security purposes, the default value of CauchoStatus is "no" when you have a resin.ini.

Adding an ISAPI filter is accomplished in the IIS manager.

When Resin and IIS are on different machines, you'll change the ResinConfigServer from "localhost" to the IP address of the Resin server.

<example> ResinConfigServer 192.168.0.10 6802 CauchoStatus yes </example>

</s3>

</s2>

If IIS is managing multiple virtual sites (better known as virtual hosts), then you need to configure IIS to use the isapi_srun.dll filter for each virtual site. Configure IIS to have the virtual directory /scripts for each virtual site point to d:\inetpub\scripts, so that each virtual site uses the isapiu_srun.dll.

</s2>

Check your configuration with the standalone web server. In other words, add a <http port='8080'/> block and browse http://localhost:8080.
Check http://localhost/caucho-status. That will tell if
the ISAPI filter/extension is properly installed.
Each server should be green and the mappings should
match your resin.xml.
If caucho-status fails entirely, the problem is in the isapi_srun
installation. Try http://localhost/scripts/isapi_srun.dll/caucho-status directly (bypassing the filter). If this fails, IIS can't find isapi_srun.dll.
- Check that isapi_srun.dll is in c:\inetpub\scripts.
- Make sure that both IIS and the underlying NTFS file system have permissions set appropriately for isapi_srun.dll.
- Make sure that your IIS host has a mapping from /scripts
  to c:\inetpub\scripts and that the /scripts has execute permissions.
- IIS 6 users may need to take <a href="#iis6">additional steps</a>.
If you've created a new
IIS web site, you need to create a virtual directory /scripts pointing to the d:\inetpub\scripts directory.
If caucho-status shows the wrong mappings, there's something wrong
with the resin.xml.
If caucho-status shows a red servlet runner, then resin.exe hasn't
properly started.
If you get a "cannot connect to servlet engine", caucho-status
will show red, and resin.exe hasn't started properly.
If resin.exe doesn't start properly, you should look at the logs
in resin3.2/log. You should start resin.exe -verbose to get more information.
If you get Resin's file not found, the IIS configuration
is good but the resin.xml probably points to the wrong directories.

IIS 6/Windows 2003 users may need to perform additional steps.

Make sure that the System account has suffiicient privleges to read the C:\InetPub and C:\InetPub\Scripts directory and the isapi_srun.dll.
Check the `Web Service Extensions' listed in the `Internet Service Manager'
to make sure that Resin is listed as a Web Service Extension and has a status of "enabled". You may need to click "add a new web service extension...", under Extension name add .jsp or whatever your file extension is, click Add and browse to the isapi_srun.dll, check the "Set extension status to allowed box", click OK.
Check that the user specified as the
"application pool identity" for Resin has read/write permission to the Resin installation directory. In the Internet Service Manager, open the Properties dialog for "Application Pools". Find the User on the "Identity" tab, it may be the user named "Network Service" in the drop-down list associated with the radio button labeled "predefined". Then check physical file permissions on the Resin installation directory and all its subdirectories and subfiles, to ensure that that user has read/write permission status is "Enabled".

</s3> </s2> </s1>

The previous sections show how to configure Apache and IIS to work with Resin. This section shows how the plugins for these servers interpret the Resin's configuration and how to change that configuration for your deployment.

The web server plugins (mod_caucho and isapi_srun) have two main tasks:

Select urls to dispatch to the Java process
Pass the request and retrieve the response from the Java process.

mod_caucho discovers its configuration by contacting the ResinConfigServer specified in the httpd.conf or resin.ini. The ResinConfigServer can be any Resin server. When a user requests a URL, mod_caucho uses the configuration it has determined from the ResinConfigServer to determine whether Resin or Apache should handle the request. That decision is based on the configuration in the ResinConfigServer's resin.xml.

</s2>

The <a href="webapp-tags.xtp#servlet-mapping">servlet-mapping</a> tag selects the URLs to send to Resin. <a href="host-tags.xtp#host"><host></a> and <a href="webapp-tags.xtp"><web-app></a> group the servlet-mapping tags.

servlet-mapping's <a href="webapp-tags.xtp#url-pattern">url-pattern</a> selects the URLs to pass to Resin. servlet-mapping and url-pattern are part of the Servlet 2.3 standard, so there are many references explaining how it works.

url-pattern can take one of four forms:

"/" matches all URLs. Use this to pass all requests to Resin.
"/prefix/url/*" matches any URL starting with /prefix/url,
including prefix/url itself. It does not match /prefix/urlfoo because any slash must immediately follow url
"/exact/path" matches only the exact path. In other words, it
will not match /exact/path/bogus.
"*.ext" matches any URL with the extension ext. Resin
allows path-infos, so /foo/bar.ext/path/info will also match.

</s3>

<note>mod_caucho does not understand regular expressions. If you put regular expressions in your resin.xml, mod_caucho will not send the request to Resin. Apache will handle the request itself.</note>

If you want to use regular expressions in servlet-mapping, web-app, or hosts, you must use Apache-specific configuration to send the request to Resin. You can see this by looking at /caucho-status. /caucho-status will not display any regular expressions.

</s3>

There are two special servlet-names which only affect the plugins: plugin_match and plugin_ignore.

plugin_match will direct a request to Resin. The servlet engine itself will ignore the plugin_match directive. You can use plugin_match to direct an entire subtree to Resin, e.g. to workaround the regexp limitation, but allow Resin's other servlet-mapping directives to control which servlets are used.

plugin_ignore keeps the request at on the web server. So you could create a directory /static where all documents, including JSPs are served by the web server.

<example>  <servlet-mapping url-pattern='/resin/*'

                servlet-name='plugin_match'/>

<servlet-mapping url-pattern='/static/*'

                servlet-name='plugin_ignore'/>

</example>

</s3>

<a href="webapp-tags.xtp">web-apps</a> collect servlets and JSP files into separate applications. All the servlet-mappings in a web-app apply only to the URL suffix.

In the following example, every URL starting with /prefix/url maps to the web-app. The servlet-mapping only applies to URLs matching the prefix.

 <servlet-mapping url-pattern='*.foo' .../>

</web-app> .. </example>

In the exaple, mod_caucho will match any URL matching /prefix/url/*.foo. /prefix/url/bar.foo will match, but /test/bar.foo will not match.

<note>Resin standalone allows a regexp attribute instead of an id. Because mod_caucho does not understand regexps, it will ignore any web-app with a regexp attribute.</note>

<note>web.xml files and war files are treated exactly the same as web-apps in the resin.xml.</note>

</s3>

<a href="cluster-tags.xtp#host">host</a> blocks configure <a href="virtual-host.xtp">virtual hosts</a>. There's a bit of extra work for virtual hosts that we'll ignore here. (Basically, you need to add Apache ServerName directives so Resin knows the name of the virtual host.)

For dispatching, a host block gathers a set of web-apps. Each host will match a different set of URLs, depending on the web-app configuration. The default host matches any host not matched by a specific rule.

As usual, /caucho-status will show the URLs matched for each host.

<note>mod_caucho does not understand the host regexp attribute. It will ignore all hosts using regexp. To get around this, you can either configure Apache directly (see below), or configure the default host with the same set of servlet-mappings. Since mod_caucho will use the default host if no others match, it will send the right requests to Resin.</note>

</s3>

</s2>

</s1>

</body> </document>

Resin Installation

From Resin 3.0

Views

Personal tools

Navigation

Search

Toolbox