Resin Documentation

Feb 2012: Leading industry analyst names Caucho as "Visionary" vendor for Enterprise Application Servers.
Feb 2012: NetCraft survey says Resin experiencing strong growth in last year and used in number of the Million Busiest Sites.

home company blog wiki docs
app server web server
health cloud java ee pro

resin 4.0

command line resin administration

Starting with version 4.0.17 Resin provides extended set of commands that allow administrators and programmers perform debugging and monitoring tasks on remote Resin server using command line.

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

enabling the commands
available commands
heap-dump: producing JVM memory heap dump
thread-dump: producing a thread dump
profile: profiling application
log-level: setting log level
jmx-list: listing JMX MBeans, attributes and operations
jmx-dump: dump all MBean attributes and values
jmx-set: setting attribute value on MBeans
jmx-call: invoking method on a MBean
deploy: deploying a web application
deploy-list: listing deployed applications
deploy-copy: copy application from context '/hello-world' to context '/foo'
undeploy: undeploying application
start-webapp: starting application
stop-webapp: stopping application
restart-webapp: restarting application
pdf-report: pdf report generation
license-add: copy a license to the license directory

enabling the commands

By default these commands are disabled. Enabling the command requires ManagerService be registered in resin.xml file.

Since the default resin.xml already includes a <resin:AdminAuthenticator> with a <resin:import>, you can just reuse the admin configuration from the /resin-admin page.

Example: enabling Resin ManagerService

  <resin xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
  ...
  <cluster id=''>

    <resin:AdminAuthenticator>
      <user name="admin" password="{SSHA}h5QdSulQyqIgYP7B1J3YfnRSo56kD847"/>
    </resin:AdminAuthenticator>

    <resin:RemoteAdminService/>

    <resin:ManagerService/>

    ...
  </cluster>
    ...
  </resin>

available commands

commands
COMMAND	DESCRIPTION
deploy	deploys an application archive
undeploy	un-deploys an application specified by a context
deploy-list	lists all applications deployed on a server
deploy-copy	copies an application from one context to another
start-webapp	starts web application context
stop-webapp	stops web application context
restart-webapp	restarts web application context
heap-dump	produces heap dump
thread-dump	produces thread dump
profile	turn profiling and displays results after sampling completes
jmx-list	lists MBeans, attributes and operations
jmx-dump	dump all MBean attributes and values
jmx-set	sets value of a jmx attribute
jmx-call	calls MBean's method
log-level	changes log-level
pdf-report	generates pdf report

Since all commands require connecting to Resin server remotely list of required parameters includes authentication and remote connection options such as IP and Port.

common options
ARGUMENT	MEANING	DEFAULT
-conf	configuration file	conf/resin.xml
-address	ip or host name of the server	taken from conf/resin.xml
-port	server http port	taken from conf/resin.xml
-user	user name used for authentication to the server	none, required
-password	password used for authentication to the server	none, required

heap-dump: producing JVM memory heap dump

To produce a heap dump resin provides heap-dump command. With Resin Open Source, heap-dump will produce a standard heap dump file and put it into the Resin log directory on the remote machine.

bin/resin.sh [-conf <file>] heap-dump [options] [-raw]

Example: producing a heap dump on Resin Open Source

unix> bin/resin.sh -conf conf/resin.conf heap-dump -user foo -password test -raw

Heap dump is written to `/var/log/resin/heap.hprof'.
To view the file on the target machine use
jvisualvm --openfile /var/log/resin/heap.hprof

Resin Pro, when heap-dump is given no -raw option is capable of producing a readable summary report.

Example: heap-dump

unix: bin/resin.sh -conf conf/resin.conf heap-dump -user foo -password test

Heap Dump generated Fri May 08 02:51:31 PDT 1998
   count   |  self size | child size | class name
        68 |       6528 |    3142736 | com.caucho.util.LruCache
     28768 |     920576 |    2674000 | java.lang.String
     29403 |    2066488 |    2066488 | char[]
        68 |    1927360 |    1927360 | com.caucho.util.LruCache$CacheItem[]
      7346 |     715416 |    1796320 | java.lang.Object[]
      5710 |     594200 |    1768624 | java.util.HashMap$Entry[]
      2827 |     135696 |    1606264 | java.util.HashMap
     20787 |     665184 |    1489024 | java.util.HashMap$Entry
      9682 |     852016 |    1235984 | java.lang.reflect.Method
     61507 |     984112 |     984400 | java.lang.Object
       337 |      16176 |     889192 | java.util.concurrent.ConcurrentHashMap
      2881 |     161336 |     883584 | java.util.LinkedHashMap
      1596 |     178752 |     702296 | com.caucho.quercus.program.ProStaticFunction

heap-dump options
ARGUMENT/OPTION	MEANING	DEFAULT
-raw	produces a standard .hprof file

Note

since raw heap dump can be on the order of gigabytes the resulting file is always left on the machine where Resin server is running.

thread-dump: producing a thread dump

To produce a thread dump resin provides thread-dump command. The thread dump is produced on a remote sever and printed out locally.

bin/resin.sh [-conf <file>] thread-dump [options] [-raw]

Example: producing a thread dump

unix> bin/resin.sh -conf conf/resin.conf thread-dump -user foo -password test -raw

  Thread Dump:

  "MailboxWorker[manager@resin.caucho]-8" id=31 RUNNABLE
    at sun.management.ThreadImpl.getThreadInfo0 (ThreadImpl.java) (native)
    at sun.management.ThreadImpl.getThreadInfo (ThreadImpl.java:147)
    at com.caucho.util.ThreadDump.threadDumpImpl (ThreadDump.java:88)
    at com.caucho.util.ThreadDump.getThreadDump (ThreadDump.java:62)
    at com.caucho.server.admin.ManagerActor.doThreadDump (ManagerActor.java:148)
    at sun.reflect.NativeMethodAccessorImpl.invoke0 (NativeMethodAccessorImpl.java) (native)
    at sun.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke (Method.java:597)
    at com.caucho.bam.actor.BamSkeleton$QueryMethodInvoker.invoke (BamSkeleton.java:501)
    at com.caucho.bam.actor.BamSkeleton.query (BamSkeleton.java:215)
    at com.caucho.bam.actor.SkeletonActorFilter.query (SkeletonActorFilter.java:187)
    at com.caucho.bam.query.QueryActorFilter.query (QueryActorFilter.java:95)
    at com.caucho.bam.packet.Query.dispatch (Query.java:86)
    at com.caucho.bam.mailbox.MultiworkerMailbox.dispatch (MultiworkerMailbox.java:268)
    at com.caucho.bam.mailbox.MailboxWorker.runTask (MailboxWorker.java:73)
    at com.caucho.env.thread.AbstractTaskWorker.run (AbstractTaskWorker.java:160)
    at com.caucho.env.thread.ResinThread.runTasks (ResinThread.java:164)
    at com.caucho.env.thread.ResinThread.run (ResinThread.java:130)

  "Signal Dispatcher" id=5 RUNNABLE

  "http://*:8087-1" id=26 RUNNABLE (in native)
    at com.caucho.vfs.JniSocketImpl.readNative (JniSocketImpl.java) (native)
    at com.caucho.vfs.JniSocketImpl.read (JniSocketImpl.java:337)
    at com.caucho.vfs.JniStream.readTimeout (JniStream.java:90)
    at com.caucho.vfs.ReadStream.fillWithTimeout (ReadStream.java:1135)
    at com.caucho.network.listen.TcpSocketLinkListener.keepaliveThreadRead (TcpSocketLinkListener.java:1345)
    at com.caucho.network.listen.TcpSocketLink.processKeepalive (TcpSocketLink.java:767)
    at com.caucho.network.listen.DuplexReadTask.doTask (DuplexReadTask.java:91)
    at com.caucho.network.listen.TcpSocketLink.handleRequests (TcpSocketLink.java:646)
    at com.caucho.network.listen.AcceptTask.doTask (AcceptTask.java:104)
    at com.caucho.network.listen.ConnectionReadTask.runThread (ConnectionReadTask.java:98)
    at com.caucho.network.listen.ConnectionReadTask.run (ConnectionReadTask.java:81)
    at com.caucho.network.listen.AcceptTask.run (AcceptTask.java:67)
    at com.caucho.env.thread.ResinThread.runTasks (ResinThread.java:164)
    at com.caucho.env.thread.ResinThread.run (ResinThread.java:130)

...

profile: profiling application

Profiling application can help find bottlenecks. Resin's profile command turn on sampling for requested period of time and prints out profiling resutls.

bin/resin.sh [-conf <file>] profile [options]

Example: profiling an application

unix> bin/resin.sh -conf conf/resin.conf profile -user foo -password test

Profile started at 1998-05-08 02:51:31.001. Active for a total of 5000ms.
Sampling rate 10ms. Depth 16.
   % time  |time self(s)|   % sum    | Method Call
   800.000 |     40.080 |     28.407 | com.caucho.env.thread.AbstractTaskWorker.run()
   300.000 |     15.030 |     39.060 | com.caucho.env.thread.ResinThread.waitForTask()
   200.000 |     10.020 |     46.162 | com.caucho.vfs.JniSocketImpl.nativeAccept()
   116.168 |      5.820 |     50.287 | _jsp._test__jsp$1.run()
   100.000 |      5.010 |     53.838 | com.caucho.env.thread.AbstractTaskWorker.run()
   100.000 |      5.010 |     57.389 | java.lang.ref.ReferenceQueue.remove()
   100.000 |      5.010 |     60.940 | com.caucho.server.admin.ManagerActor.profile()
   100.000 |      5.010 |     64.491 | java.lang.ref.Reference$ReferenceHandler.run()
   100.000 |      5.010 |     68.042 | java.lang.UNIXProcess.waitForProcessExit()
   100.000 |      5.010 |     71.593 | java.io.FileInputStream.readBytes()
   100.000 |      5.010 |     75.144 | com.caucho.util.Alarm$AlarmThread.run()
   100.000 |      5.010 |     78.694 | com.caucho.env.shutdown.ShutdownSystem$ShutdownThread.run()
   100.000 |      5.010 |     82.245 | com.caucho.network.listen.JniSelectManager.selectNative()
   100.000 |      5.010 |     85.796 | unknown
   100.000 |      5.010 |     89.347 | com.caucho.vfs.JniSocketImpl.readNative()
   100.000 |      5.010 |     92.898 | com.caucho.test.Test$Timeout.run()
   100.000 |      5.010 |     96.449 | com.caucho.profile.ProProfile.nativeProfile()
   100.000 |      5.010 |    100.000 | java.lang.Thread.sleep()
com.caucho.env.thread.AbstractTaskWorker.run()
  sun.misc.Unsafe.park()
  java.util.concurrent.locks.LockSupport.parkUntil()
  com.caucho.env.thread.AbstractTaskWorker.run()
  com.caucho.env.thread.ResinThread.runTasks()
  com.caucho.env.thread.ResinThread.run()

profile options
ARGUMENT/OPTION	MEANING	DEFAULT
-active-time	specifies profiling time span in ms (defaults to 5000 - 5 sec.)	5s
-sampling-rate	specifies sampling rate (defaults to 10ms)	10ms

log-level: setting log level

Command log-level changes a log level, optionally temporarily.

bin/resin.sh [-conf <file>] log-level [options] \
            -all|-finest|-finer|-fine|-config|-info|-warning|-severe|-off \
            [-active-time <time-period>] [loggers...]

Example: setting log level

unix> bin/resin.sh -conf conf/resin.conf log-level -user foo -password test -active-time 5s -finer

Log level is set to `FINER', active time 5 seconds: {root}, com.caucho

log-level options
ARGUMENT/OPTION	MEANING	DEFAULT
-active-time	specifies temporary level active time. e.g. 5s	permanent
-<level>	specifies new log level	none, required
value	name of the logger(s). Defaults to root and `com.caucho' loggers.

jmx-list: listing JMX MBeans, attributes and operations

Commandjmx-list prints out JMX MBeans, attributes and operations registered in a JVM that is running Resin. As its last argument the command accepts <pattern>. The <pattern> follows convention defined for javax.management.ObjectName, defaulting to resin:*, which matches any MBean in resin domain.

bin/resin.sh [-conf <file>] jmx-list [options] [<pattern>]

Example: listing MBeans

unix> bin/resin.sh -conf conf/resin.conf jmx-list -user foo -password test com.acme:*

com.acme:type=Foo
com.acme:type=Bar

jmx-list options
ARGUMENT/OPTION	MEANING
-attributes	outputs a list of attributes for each MBean
-values	outputs a list of attributes and values for each MBean
-operations	outputs a list of operations each MBean
-operations	outputs a list of operations each MBean
-platform	only queries MBeans in java.lang domain(unless pattern is specified)
-all	queries MBeans in any domain(unless pattern is specified)

Example: listing MBeans with values

bin/resin.sh -conf conf/resin.conf jmx-list -user foo -password test -values com.acme:*

com.acme:type=Foo
  attributes:
    javax.management.MBeanAttributeInfo[description=,
            name=Boolean, type=boolean, read-only, descriptor={}]==false

jmx-dump: dump all MBean attributes and values

Commandjmx-dump produces a complete listing of a MBeans with current attribute values. The output is usually lengthy and can be directed to a file rather than stdout using the -file parameter.

bin/resin.sh [-conf <file>] jmx-dump [options] [-file <file>]

jmx-list options
ARGUMENT/OPTION	MEANING	DEFAULT
-file	if specified, writes output to file

Example: dumping JMX

bin/resin.sh -conf conf/resin.conf jmx-dump -user foo -password test
JMX Dump:
java.lang:type=MemoryPool,name=CMS Old Gen {
  Name=CMS Old Gen
  Type=HEAP
...

jmx-set: setting attribute value on MBeans

Commandjmx-set sets a value on an attribute belonging to a particular JMX MBean.

bin/resin.sh [-conf <file>] jmx-set [options] -pattern <pattern> -attribute <attribute> value

Example: setting attribute value

unix> bin/resin.sh -conf conf/resin.conf jmx-set -user foo -password test \
                   -pattern com.acme:type=Foo -attribute Foo foo-value

value for attribute `Foo' on bean `com.acme:type=Foo' is changed from `null' to `foo-value'

jmx-set options
ARGUMENT/OPTION	MEANING
-pattern	specifies pattern to match target MBean
-attribute	sets name of the attribute
value	String representation of the value (primitive types and String are supported)

jmx-call: invoking method on a MBean

Commandjmx-call calls a method on a specified with < pattern> MBean.

bin/resin.sh [-conf <file>] jmx-call [options] -pattern <pattern> -operation <operation> value...

Example: invoking method on MBean

unix> bin/resin.sh -conf conf/resin.conf jmx-call \
                   -user foo -password test \
                   -pattern com.acme:type=Foo -pattern com.acme:type=Foo \
                   -operation echo hello

method `echo(java.lang.String)' called on `com.acme:type=Foo' returned `hello'.

jmx-call options
ARGUMENT/OPTION	MEANING
-pattern	specifies pattern to match target MBean
-operation	sets name of the operation to invoke
value	space separated list of parameters that will be passed to the method (primitive types and String are supported)

deploy: deploying a web application

Deploying an application is done with a deploy command

bin/resin.sh [-conf <file>] deploy [options] <war-file>

Example: deploying an application from a hello-world.war archive

unix> bin/resin.sh deploy -user admin -password secret /projects/hello-world/hello-world.war

Deployed production/webapp/default/hello-world as hello-world.war to http://127.0.0.1:8080/hmtp

deploy options
ARGUMENT	MEANING	DEFAULT
-host	virtual host to make application available on	default
-name	name of the context to deploy to, defaults to war-file name	[/foo].war
-stage	specifies stage for staging an application	production
-version	version of application formatted as <major.minor.micro.qualifier>	none

deploy-list: listing deployed applications

Listing deployed applications is done with a deploy-list command

bin/resin.sh [-conf <file>] deploy-list [options]

Example: deploy-list

unix> bin/resin.sh deploy-list -user admin -password secret

production/webapp/default/hello-world

deploy-copy: copy application from context '/hello-world' to context '/foo'

Copying an application is done with a deploy-copy command

bin/resin.sh [-conf <file>] deploy-copy [options]

Example: deploy-copy

unix> bin/resin.sh deploy-copy -user admin -password secret -source hello-world -target foo

copied production/webapp/default/hello-world to production/webapp/default/foo

deploy-copy options
ARGUMENT	MEANING	DEFAULT
-source	context to copy application from	none
-source host	host to copy application from	default
-source-stage	source stage	production
-source-version	version of the source application formatted as <major.minor.micro.qualifier>	none
-target	context to copy application to	none
-target-host	host to copy an application to	default
-target-stage	target stage	production
-target-version	version application to use for a target, formatted as <major.minor.micro.qualifier>	none

undeploy: undeploying application

Undeploying an application is done with an undeploy command

bin/resin.sh [-conf <file>] undeploy [options] <name>

Example: undeploy

unix> bin/resin.sh undeploy -user admin -password secret undeploy foo

Undeployed foo from http://127.0.0.1:8080/hmtp

undeploy options
ARGUMENT	MEANING	DEFAULT
-host	virtual host to make application available on	default
-stage	specifies stage for staging an application	production
-version	version of application formatted as <major.minor.micro.qualifier>	none

start-webapp: starting application

Starting an application is done with an start-webapp command

bin/resin.sh [-conf <file>] start-webapp [options] <name>

Example: start web application deployed at context '/foo'

unix> bin/resin.sh start-webapp -user admin -password secret foo

'production/webapp/default/foo' is started

start-webapp options
ARGUMENT	MEANING	DEFAULT
-host	virtual host to make application available on	default
-stage	specifies stage for staging an application	production
-version	version of application formatted as <major.minor.micro.qualifier>	none

stop-webapp: stopping application

Stopping an application is done with an stop-webapp command

bin/resin.sh [-conf <file>] stop-webapp [options] <name>

Example: stop web application deployed at context '/foo'

unix> bin/resin.sh stop-webapp -user admin -password secret foo

'production/webapp/default/foo' is stopped

stop-webapp options
ARGUMENT	MEANING	DEFAULT
-host	virtual host to make application available on	default
-stage	specifies stage for staging an application	production
-version	version of application formatted as <major.minor.micro.qualifier>	none

restart-webapp: restarting application

Restarting an application is done with an restart-webapp command

bin/resin.sh [-conf <file>] restart-webapp [options] <name>

Example: stop web application deployed at context '/foo'

unix> bin/resin.sh restart-webapp -user admin -password secret foo

'production/webapp/default/foo' is restarted

restart-webapp options
ARGUMENT	MEANING	DEFAULT
-host	virtual host to make application available on	default
-stage	specifies stage for staging an application	production
-version	version of application formatted as <major.minor.micro.qualifier>	none

pdf-report: pdf report generation

The pdf-report command triggers generation of a PDF report from a .php template.

bin/resin.sh [-conf <file>] pdf-report [options]

Example: generate the default watchdog PDF report

unix> bin/resin.sh pdf-report -user admin -password secret -watchdog

generated /usr/local/resin/log/default-Watchdog-20110801T0251.pdf

pdf-report options
ARGUMENT	MEANING	DEFAULT
-logdir	PDF output directory	Resin log directory
-path	Path to a PDF generating .php file	${resin.home}/doc/admin/pdf-gen.php
-period	Report look back period of time	7D
-snapshot	Take a snapshot of the server before reporting	false
-watchdog	Report on server period to the last restart	false

license-add: copy a license to the license directory

The license-add is a convenient way to remotely add a license to the correct license directory

bin/resin.sh [-conf <file>] license-add -license <license file> [options]

Example: copy test.license to the license directory as test.license, overwrite if exists

unix> bin/resin.sh license-add -user admin -password secret -license test.license -overwrite

add-license wrote test.license successfully

license-add options
ARGUMENT	MEANING	DEFAULT
-license	Path to license file to add	none, required
-to	File name license will be written to	name of license file
-overwrite	Overwrite existing license file if exists	false, true if set
-restart	Restart Resin after license is added	false, true if set