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


 

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 Server | Application Server (Java EE Certified) and Web Server
 

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

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
COMMANDDESCRIPTION
deploydeploys an application archive
undeployun-deploys an application specified by a context
deploy-listlists all applications deployed on a server
deploy-copycopies an application from one context to another
start-webappstarts web application context
stop-webappstops web application context
restart-webapprestarts web application context
heap-dumpproduces heap dump
thread-dumpproduces thread dump
profileturn profiling and displays results after sampling completes
jmx-listlists MBeans, attributes and operations
jmx-dumpdump all MBean attributes and values
jmx-setsets value of a jmx attribute
jmx-callcalls MBean's method
log-levelchanges log-level
pdf-reportgenerates 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
ARGUMENTMEANINGDEFAULT
-confconfiguration fileconf/resin.xml
-addressip or host name of the servertaken from conf/resin.xml
-portserver http porttaken from conf/resin.xml
-useruser name used for authentication to the servernone, required
-passwordpassword used for authentication to the servernone, 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/OPTIONMEANINGDEFAULT
-rawproduces a standard .hprof file
note
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/OPTIONMEANINGDEFAULT
-active-timespecifies profiling time span in ms (defaults to 5000 - 5 sec.)5s
-sampling-ratespecifies 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/OPTIONMEANINGDEFAULT
-active-timespecifies temporary level active time. e.g. 5spermanent
-<level>specifies new log levelnone, required
valuename 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/OPTIONMEANING
-attributesoutputs a list of attributes for each MBean
-valuesoutputs a list of attributes and values for each MBean
-operationsoutputs a list of operations each MBean
-operationsoutputs a list of operations each MBean
-platformonly queries MBeans in java.lang domain(unless pattern is specified)
-allqueries 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/OPTIONMEANINGDEFAULT
-fileif 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/OPTIONMEANING
-patternspecifies pattern to match target MBean
-attributesets name of the attribute
valueString 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/OPTIONMEANING
-patternspecifies pattern to match target MBean
-operationsets name of the operation to invoke
valuespace 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
ARGUMENTMEANINGDEFAULT
-hostvirtual host to make application available ondefault
-namename of the context to deploy to, defaults to war-file name[/foo].war
-stagespecifies stage for staging an applicationproduction
-versionversion 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
ARGUMENTMEANINGDEFAULT
-sourcecontext to copy application fromnone
-source hosthost to copy application fromdefault
-source-stagesource stageproduction
-source-versionversion of the source application formatted as <major.minor.micro.qualifier>none
-targetcontext to copy application tonone
-target-hosthost to copy an application todefault
-target-stagetarget stageproduction
-target-versionversion 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
ARGUMENTMEANINGDEFAULT
-hostvirtual host to make application available ondefault
-stagespecifies stage for staging an applicationproduction
-versionversion 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
ARGUMENTMEANINGDEFAULT
-hostvirtual host to make application available ondefault
-stagespecifies stage for staging an applicationproduction
-versionversion 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
ARGUMENTMEANINGDEFAULT
-hostvirtual host to make application available ondefault
-stagespecifies stage for staging an applicationproduction
-versionversion 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
ARGUMENTMEANINGDEFAULT
-hostvirtual host to make application available ondefault
-stagespecifies stage for staging an applicationproduction
-versionversion 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
ARGUMENTMEANINGDEFAULT
-logdirPDF output directoryResin log directory
-pathPath to a PDF generating .php file${resin.home}/doc/admin/pdf-gen.php
-periodReport look back period of time7D
-snapshotTake a snapshot of the server before reportingfalse
-watchdogReport on server period to the last restartfalse

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
ARGUMENTMEANINGDEFAULT
-licensePath to license file to addnone, required
-toFile name license will be written toname of license file
-overwriteOverwrite existing license file if existsfalse, true if set
-restartRestart Resin after license is addedfalse, true if set

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