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


Resin Documentation

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

resin.xml: configuration overview

Overview of the Resin configuration: for most common properties and resin.xml for full customization.


All Resin configuration is ultimately managed by the resin.xml. To keep configuration manageable, the resin.xml imports properties files like, and xml files like cluster-default.xml and health.xml. Many sites will never need to change the resin.xml and can just modify the

Concepts and naming conventions

  • cluster - a collection of identically-configured servers.
  • environment - isolated class-loader contexts with shared resources: server, host and web-app are the main environments.
  • host - a HTTP virtual host.
  • proxy cache - HTTP proxy cache.
  • resource - drivers or services available to the application though JNDI or CDI like databases, JMS queues, custom CDI-configured service. Resin-specific resources include security, authenticators, health-checks and the rewrite/dispatch system.
  • rewrite/dispatch - the configuration for dispatching HTTP URLs to servlets and response codes like Apache's mod_rewrite.
  • server - a Resin JVM instance. There may be multiple servers on a machine.
  • watchdog - a JVM instance which watches over the Resin server and restarts the server if necessary.
  • web-app - a HTTP web-application which runs servlets.

The defines properties used by the resin.xml for the Resin server and cluster. Many sites will only need to modify the for their configuration.

Example: key
# web-tier Triad servers: web-0 web-1 web-2
# web_servers      :
# web.http          : 80

# app-tier Triad servers: app-0 app-1 app-2
app_servers      :

app.http          : 8080

setuid_user   : resin
setuid_group  : resin

home_cluster : app
elastic_cloud_enable : true

jvm_args  : -Xmx2048m -XX:MaxPermSize=256m

web_admin_enable  : true

admin_user     : my-admin
admin_password : {SSHA}G3UOLv0dkJHTZxAwmhrIC2CRBZ4VJgTB

The properties in are converted into JSP EL variable used by the resin.xml, like port="${http}".

Properties can be qualified by the server's name or by its cluster. The app.http in the above example is the ${http} variable specific to the "app" cluster. You can also use app-0.http to define a custom http port for a specific server.


The resin.xml file is the root of Resin's configuration. Other files like the and cluster-default.xml are imported files to organize the configuration. Conceptually, they're all delegated from the resin.xml.

The resin.xml configures clusters, servers, virtual hosts, web-app deployment, resources, health checks, and class-loaders. Almost all of Resin's behavior is configured by the resin.xml.

The standard resin.xml distributed with Resin and its property file configures a standard, flexible clustering system including an application server tier, a http web tier, and virtual hosts. Many sites will not need to modify the standard resin.xml.

The resin.xml is flexible enough to configure non-http servers. If you have a non-http Java service, it can take advantage of Resin's watchdog, lifecycle and health system by being configured as a standard CDI service in a non-http Resin system.

Example: resin.xml outline
<resin xmlns=""

    <!-- shared configuration across all clusters -->
    <resin:import path="classpath:META-INF/caucho/app-default.xml"/>
    <resin:import path="${__DIR__}/health.xml" optional="true"/>
  <cluster id="my-cluster">

      <!-- thread limits, JVM config, keepalives, ports, HTTP -->

      <http port="8080"/>

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

    <host id="" root-directory="hosts/">

      <resin:MovedPermanently regexp="/old-file" target="/new-path"/>
      <web-app-deploy path="webapps"

      <web-app id="/custom">

Next Steps

  • configuration shows how to customize basic configuration.
  • resin.xml configuration shows more advanced and specialized configuration.
  • command-line describes using the resinctl command line interface.
  • deployment deploying applications to a running server.
  • clustering describes clustering, cloud, and dynamic servers.
  • resin-admin describes the /resin-admin browser-based interface.
  • health describes the Resin health and monitoring system.
  • REST admin describes the REST interface for remote third-party admin integration.
  • Resin HTTP Web Server describes fast, scalable HTTP web server.
  • HTTP URL Rewrite describes Resin's URL rewriting (like mod_rewrite).
  • Security describes authentication, authorization and SSL.

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

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including, CNET, DZone and many more are powered by Resin.

home company blog wiki docs 
app server