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 administration


The /resin-admin web-app provides an administration overview of a Resin server. Resin-Pro users can obtain information across the entire cluster, profile a running Resin instance, and obtain thread dumps and heap dumps.

All Resin users should familiarize themselves with the thread dump, profile, and heap capabilities.

/resin-admin web-app

The /resin-admin web-app provides an administration overview of a Resin server. Resin-Pro users can obtain information across the entire cluster, profile a running Resin instance, and obtain thread dumps and heap dumps.

Configuring /resin-admin

Since /resin-admin is just a web-app implemented with Quercus/PHP, enabling it is just adding an appropriate <web-app> tag.

To enable the /resin-admin, you'll need to create an admin user and password.

  1. Create an admin user following the prompt at /resin-admin.
  2. Copy the conf/admin-users.xml.generated to conf/admin-users.xml.
  3. Change the resin_admin_external to true if you need access from a non-local IP address.
  4. Browse /resin-admin with an HTML 5 browser.

The steps are for security reasons. Copying the admin-users.xml verifies that you have access to the server. And the default resin_admin_external=false makes sure you're not exposing the /resin-admin to the internet.

Adding /resin-admin users

The admin-users.xml contains the admin users and passwords who are allowed access to /resin-admin. The format is an XML file where each user has a <user> tag. The password is encoded with the standard {SSHA} password scheme used by LDAP. Since the /resin-admin login page includes an automatic {SSHA} generator, you can use that page to generate additional passwords.

Example: sample admin-users.xml
<resin:AdminAuthenticator xmlns="http://caucho.com/ns/resin"
                          xmlns:resin="urn:java:com.caucho.resin">
  <user name="admin" password="{SSHA}h5QdSulQyqIgYo7BIJ3YfnRSY56kD847"/>
  <user name="resin" password="{SSHA}J0y0dlG2uRKT83g3OfzEjFNTIaTHVsA9"/>
</resin:AdminAuthenticator>

Allowing external internal access

Example: exposing /resin-admin to the internet
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">

  ...

  <web-app id="/resin-admin" root-directory="${resin.root}/doc/admin">
     <prologue>
        <!-- allow access from any IP address -->
        <resin:set var="resin_admin_external" value="true"/>
        <resin:set var="resin_admin_insecure" value="true"/>
     </prologue>
  </web-app>

</host>
</cluster>
</resin>

/resin-admin summary tab

The summary tab provides a basic overview of the Resin instance. Resin-Pro users can see the summary page of each server in a cluster.

The overview section shows basic configuration information like the server-id, Resin version, Resin home, memory information, and how long the instance has been up. It's useful as a basic check to verify the configuration and see if the server is having any problems.

Thread pool

The thread pool give the current state of Resin's threads.

TCP ports

The TCP ports gives information about the HTTP, HTTPS, and cluster ports, showing how many threads are active and also how many connections are in various keepalive states.

Server Connectors - Load Balancing

The Server Connectors section is the main section for load balancing. It will give an overview of any failures in connecting to the backend servers, showing the latency and load.

Connection pools - Database pooling

The connection pool section shows the state and history of the database pools.

WebApps

The WebApps shows the current state of the active web-apps for each virtual host. In particular, it will show the time and number of any 500 errors, letting you track down errors in the log files.

/resin-admin config tab

The config tag summarizes Resin's internal configuration. This tab can be useful to double-check that the values in the resin.xml and web.xml match the expected values.

/resin-admin threads tab

The threads tab is a critical debugging tab. It shows the state and stack trace of every thread in the JVM, grouped by functionality. If the server ever freezes or moves slowly, use the thread tab as your first resource for figuring out what's going on in the system.

All Resin users should familiarize themselves with the thread dump for their application. It's very important to understand the normal, baseline status, so if something does go wrong, you'll know what looks different.

In particular, any freeze or slowness of Resin should immediately suggest looking at the thread page.

/resin-admin cpu profile tab

The cpu profile tab lets you gather basic profiling information on a running Resin server. Because the overhead is low, it's even possible to run a profile on a deployment server, which will give much better information about the performance of your system than any artificial benchmarks.

With Resin's integrated profiling, there's no excuse to skip the profiling step for your application.

/resin-admin heap dump tab

The heap dump tab lets you gather a heap memory information at any time, giving you critical information at times when you may not have a dedicated profiler available.

/resin-admin Custom Configuration

For advanced users, you can change the standard AdminAuthenticator to be any of the Resin authenticators with a little extra configuration. The default authenticator uses an XML file called admin-users.xml to define the admin users.

You can create an alternative authenticator by configuring it and setting its CDI name to be "resinAuth". For example, the following will configure an XmlAuthenticator.

resin.xml custom /resin-admin configuration
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:ee="urn:java:ee">
       xmlns:resin="urn:java:com.caucho.resin">

  <resin:XmlAuthenticator ee:Named="resinAuth">
    <user name="admin" password="{SSHA}h5QdSulQyqIgYo7BIJ3YfnRSY56kD847"/>
  </resin:XmlAuthenticator>

  ...
  
<cluster id="">
<host id="">

  <web-app id="/resin-admin" root-directory="${resin.root}/doc/admin">
     ...
  </web-app>

Admin topics

Interpreting the proxy cache hit ratio

The proxy cache is Resin's internal proxy cache (in Resin Pro). The hit ratio marks what percentage of requests are served out of the cache, i.e. quickly, and which percentage are taking the full time.

The proxy cache hit ratio is useful for seeing if you can improve your application's performance with better caching. For example, if you had a news site like www.cnn.com, you should have a high hit rate to make sure you're not overtaxing the database.

If you have a low value, you might want to look at your heavily used pages to see if you can cache more.

Resin's JMX Interfaces

See com.caucho.management.server.

JMX Instrumenting Beans

Resin's IoC container can register the application's services with JMX automatically. The registered beans will then be available in a JMX application like jconsole or through PHP or Java.

  1. For a class MyFoo, create an interface MyFooXMBean with the management interface.
  2. Class MyFoo needs to implement the MyFooMBean interface.
  3. When Resin handles the <bean> tag, it will register MyFoo with the JMX server.

Instrumenting a bean

Resin will automatically register any servlet which implements an MBean interface. By default, the JMX name will be:

resin:name=name,type=type,Host=name,WebApp=name
ObjectName attributes
ATTRIBUTEVALUE
typeThe FooMBean name minus the MBean, e.g. "Foo"
namethe bean's name value
Hostthe virtual host name
WebAppthe web-app's context path

The domain is web-app, the type property is calculated from the MBean class name and the name property is the value of <name>.

JMX clients will use the name to manage the bean. For example, a client might use the pattern web-app:type=Foo,* to retrieve the bean.

MyServiceMBean.java
package test;

public interface MyServiceMBean {
  public int getCount();
}
MyServlet.java
package test;

import java.io.*;
import javax.servlet.*;

public class MyService implements MyServiceMBean
{
  private int _count;

  public int getCount()
  {
    return _count;
  }

  public void doStuff()
  {
    _count++;
  }
}

PHP: Displaying and Managing Resources

The easiest way to display and manage JMX is with PHP. The /resin-admin web-app provides several examples of getting JMX data.

PHP: Getting the Count attribute
<php?

$mbean_server = new MBeanServer();

$service = $mbean_server->query("resin:*,type=MyService");

echo "Service.count: " . $service[0]->Count . "\n";

?>

JMX Console

JDK 5.0 includes a JMX implementation that is used to provide local and remote administration of a Resin server. The JVM will expose JMX if it's started with appropriate -D system properties. For example, -Dcom.sun.management.jmxremote will expose JMX to the local machine.

To configure the JVM arguments for Resin, you'll add a <jvm-arg> to the resin.xml. When Resin's Watchdog process starts Resin, it will pass along the configured arguments, enabling JMX administration.

Start Resin and allow local JMX administration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Choose Resin's JVM from the "Local" list.
Start Resin and allow remote JMX administration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>

Without some configuration effort, the previous command will not work. Password configuration and SSL configuration is required by the JDK implementation of remote JMX. Detailed instructions are included in the JDK documentation.

The following is useful for testing, but should be done with caution as the port is not protected by password or by SSL, and if not protected by a firewall is accessible by anyone who can guess the port number.

Start Resin and remote JMX - disable password checking and SSL
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.ssl=false</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.authenticate=false</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Enter the host name and port number (9999) on the "Remote" tab
Setting a password for remote JMX access
$ cd $JAVA_HOME/jre/lib/management
$ cp jmxremote.password.template jmxremote.password
$ chmod u=rw jmxremote.password
$ vi jmxremote.password

Set a password for "monitorRole" and "controlRole":

monitorRole 12monitor
controlRole 55control
Start Resin and remote JMX - disable SSL
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.ssl=false</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Enter the host name and port number (9999) on the "Remote" tabEnter the username and password on the "Remote" tab

SNMP

Since 3.1.5, Resin has built-in support for SNMP (Simple Network Management Protocol). This allows Resin to be managed just like any network device (e.g. routers) from an SNMP manager application.

Enabling SNMP support in Resin

To enable Resin's SNMP service, you'll need to add an SNMP protocol tag to your resin.xml under the <server> tag:

resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">
    <server-default>
    
      <protocol class="com.caucho.server.snmp.SnmpProtocol" port="161"/>
      
    <server-default/>
    
    ...
    
  <cluster/>
<resin/>

This opens up a port that listens for SNMP requests and responds to them with an SNMP response. Currently, Resin can only respond to TCP SNMP get-pdu requests.

By default, the SNMP community string is "public". It can be changed with:

<protocol class="com.caucho.server.snmp.SnmpProtocol" port="161">
  <init community="insert_password_here"/>
<protocol/>

MIB Variables

Internally, Resin stores a mapping from SNMP MIB variables to MBean attributes. Requests for a specific MIB variable are simply retrievals for the corresponding MBean attribute. The available MIB mappings are hard-coded in Resin and they are:

SNMP to MBean mappings
SNMP OBJECT IDSNMP TYPEMBEANMBEAN ATTRIBUTE
1.3.6.1.2.1.1.1Octet Stringresin:type=ResinVersion
1.3.6.1.2.1.1.3Time Ticksjava.lang:type=RuntimeUpTime
1.3.6.1.2.1.1.5Octet Stringresin:type=Host,name=defaultURL
1.3.6.1.4.1.30350.1.1Gaugeresin:type=ServerKeepaliveCountTotal
1.3.6.1.4.1.30350.1.2Gaugeresin:type=ServerRequestCountTotal
1.3.6.1.4.1.30350.1.3Gaugeresin:type=ServerRuntimeMemory
1.3.6.1.4.1.30350.1.4Gaugeresin:type=ServerRuntimeMemoryFree
1.3.6.1.4.1.30350.1.5Gaugeresin:type=ServerThreadActiveCount
1.3.6.1.4.1.30350.1.6Gaugeresin:type=ServerThreadKeepaliveCount
1.3.6.1.4.1.30350.2.1Gaugeresin:type=ThreadPoolThreadActiveCount
1.3.6.1.4.1.30350.2.2Gaugeresin:type=ThreadPoolThreadCount
1.3.6.1.4.1.30350.2.3Gaugeresin:type=ThreadPoolThreadIdleCount
1.3.6.1.4.1.30350.2.4Gaugeresin:type=ThreadPoolThreadIdleMax
1.3.6.1.4.1.30350.2.5Gaugeresin:type=ThreadPoolThreadIdleMin
1.3.6.1.4.1.30350.2.6Gaugeresin:type=ThreadPoolThreadMax
1.3.6.1.4.1.30350.3.1Gaugeresin:type=ProxyCacheHitCountTotal
1.3.6.1.4.1.30350.3.2Gaugeresin:type=ProxyCacheMissCountTotal

Defining your own SNMP to MBean mappings

To define your own MIB variables, you'll need to extend the com.caucho.server.snmp.SnmpProtocol class and then use that class name in the <protocol> tag:

resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">
    <server-default>
    
      <protocol class="example.MySnmpProtocol" port="161"/>
      
    <server-default/>
    
    ...
    
  <cluster/>
<resin/>
example.MySnmpProtocol
package example;

import com.caucho.server.snmp.*;
import com.caucho.server.snmp.types.*;

public class MySnmpProtocol extends SnmpProtocol
{
  public MySnmpProtocol()
  {
    super();
  
    addOid(new Oid("1.2.3.4.5",
                   "my_mbean_object_name",
                   "my_mbean_attribute",
                   SnmpValue.OCTET_STRING));
  }
}

"1.2.3.4.5" is the SNMP ID you choose to give to your mapping. It should be in dot notation. SnmpValue.OCTET_STRING is the type Resin should return for that attribute. An abbreviated list of the available types are:

SNMP TYPESDESCRIPTION
SnmpValue.OCTET_STRING8-bit String
SnmpValue.INTEGERsigned 32-bit integer
SnmpValue.COUNTERunsigned 32-bit integer that only increases, wraps around when overflows
SnmpValue.GAUGEunsigned 32-bit integer that may increase and decrease
SnmpValue.TIME_TICKSunsigned 32-bit integer representing time measured in hundredths of a second
SnmpValue.IP_ADDRESSIP address

For a more complete list, see com.caucho.server.snmp JavaDoc.


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