Caucho Technology

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 providesheap-dumpcommand. With Resin Open Source,heap-dumpwill 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-rawoption 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 providesthread-dumpcommand. 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'sprofilecommand 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

Commandlog-levelchanges 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-listprints 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 forjavax.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-dumpproduces 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-setsets 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-callcalls 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 adeploycommand

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 adeploy-listcommand

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 adeploy-copycommand

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 anundeploycommand

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 anstart-webappcommand

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 anstop-webappcommand

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 anrestart-webappcommand

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

Thepdf-reportcommand 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

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