In this post I’d like to provide a complete listing of all commands available in Resin. First, let’s enable resin:ManagerService. Open your resin.xml file and add <resin:ManagerService/> into <cluster-default> section. If you running Resin-Pro look for <resin:AdminServices/> tag and uncomment it. Remember that <cluster-default> applies settings to all configured clusters, e.g. app-tier and web-tier. Once that’s done, lets create an administrative user. If you have already used /resin-admin then please use username and password that you use with /resin-admin and skip to the next section. Otherwise, create a file named admin-users.xml next to your resin.xml in the RESIN_HOME/conf directory and copy the code below into the new file.

<resin:AdminAuthenticator xmlns="http://caucho.com/ns/resin"
                          xmlns:resin="urn:java:com.caucho.resin"
                          password-digest="none">
  <user name="admin" password="secret"/>
</resin:AdminAuthenticator>

The clear text for password can be avoided by using the digest. To create one, open /resin-admin and make a new account with that (if you’d like to make your configuration more secure). Great, now lets look at the commands. In the table below I’ve listed them all. You can scroll down to the description of a command that you’d like to read about, but  I suggest that you first read the left side of the table. We tried to use intuitive names.

Starting and Stopping Resin Application Server

All right, now let me introduce each in its separate section, starting with the set used to start servers up. We have four of those: start, console, gui and start-with-foreground. Any of the four can be used to start a server, but the most appropriate for a task should always be used. Let’s quickly reduce that list to three: start-with-foreground should only be used with MacOSX’s service startup system. Resin is always started using a bootstrap JVM. If the boot-strap JVM exists, MacOSX’s launchd kills any of the child processes that it started, so the boot-strap JVM needs to be kept running in the foreground, thus the special way of starting with launchd is required. If you are on Mac there is a resin.plist file in the contrib/MacOSX directory. It can be used by using ‘launchctl start com.caucho.resin’ command, but don’t forget to load it first:  ’launchctl load resin.plist’. Use an editor to set resin-home and root-directory values inside resin.plist. The remaining behaviour of the start-with-foreground is no different from that of start command.

Resin bootstrap JVM reads resin.xml. The information in resin.xml such as that contained in <jvm-args> and <watchdog-jvm-args> is then used to start the watchdog and an instance of a Resin server. After starting Watch-Dog and Resin the bootstrap JVM exists. (unless start-with-foreground was used)

Command start should be used when starting Resin in the background. That’s the right command to use with custom scripts as well.

Commands gui and console are similar, the both run Resin in a console with gui command providing a simple UI with start and stop controls.

The list of arguments can be obtained using bin/resin.sh help start

usage: bin/resin.sh [-options] start

where options include:

-conf <file>                : select a configuration file
-data-directory <dir>       : select a resin-data directory
-join-cluster <cluster>     : join a cluster as a dynamic server
-log-directory <dir>        : select a logging directory
-resin-home <dir>           : select a resin home directory
-root-directory <dir>       : select a root directory
-server <id>                : select a <server> to run
-watchdog-port <port>       : override the watchdog-port
-verbose                    : print verbose starting information
-preview                    : run as a preview server
-debug-port <port>          : configure a debug port
-jmx-port <port>            : configure an unauthenticated jmx port

Commands stop, shutdown and kill are all used to shut the server down.

This commands work similarly with differences important enough to be outlined in a separate post made by Paul. The list of arguments for stop and kill commands are below.

bin/resin.sh help stop
usage: bin/resin.sh [-options] stop

where options include:
   -conf  <file>       : select a configuration file
   -data-directory     : select a resin-data directory
   -log-directory      : select a logging directory
   -resin-home         : select a resin home directory
   -root-directory     : select a root directory
   -server             : select a  to run
   -watchdog-port      : override the watchdog-port
   -verbose            : print verbose starting information

Kill isn’t graceful i.e. it’s an emergency command, that destroys java process running Resin. Killing does not give Resin a chance to run its finalization routines, part of which is closing all Web-Apps properly. Such, application life-cycle listeners will not be called when Resin is shutdown using the kill command.

Deploying Applications and Managing Deployed Application

Deploy set of commands provides ways to deploy applications, copy them from one context to another (/foo -> /bar), start, stop, list and undeploy applications. There needs to be a word shared about the foundation that the application deployment and repository is built upon. The very base of the application repository is an implementation of Git (The Fast Version Control System). Basing the system on Git was visionary, as it brings inherent to a Version Control System capabilities forth for use with Resin’s deployment. Choosing a repository format that had proven itself capable is a great choice, because it allows Git functionality be added continually. Currently, the functionality implemented in the Resin Application Repository allows fast, atomic deployment. Fast - because internally only the files that changed get transferred and stored. Atomic, because updates that use Git algorithm are transactional - either all succeeds, or nothing. In the cloud these features are even more important, since deploying to a cloud propagates an application to all servers comprising the cloud. Internally, the repository will be stored in RESIN_ROOT/resin-data/${server-id}/.git. Let’s look at these commands.

Deploy is a command used to deploy applications. Help system prints out a brief message that will be explained below in more detail.

bin/resin.sh help deploy
usage: bin/resin.sh [-conf  <file>] [-server <id>] deploy -user -password <password> [options] 

description:
   deploys application specified in a  to resin server

options:
  -conf        : resin configuration file
  -server      : id of a server
   -address    : ip or host name of the server
   -port       : server http port
   -user       : user name used for authentication to the server
   -password   : password used for authentication to the server
   -host       : virtual host to make application available on
   -name       : name of the context to deploy to, defaults to war-file name
   -stage      : stage to deploy application to, defaults to production
   -version    : version of application formatted as
   -m          : commit message

Command deploy is where you start deploying applications to Resin. Although the apps can be just copied into webapps directory, in clustered deployment the easier way is to deploy using CLI or Web-based Resin Administration Console - /resin-admin. Let’s briefly discuss each option of the command.

-conf should point to a configuration file. The location can be either an absolute path or path relative to RESIN_ROOT.

-server <id> should be pointing to a an id of a triad server. In a single server deployment the parameter can be omitted.

-address and -port point to an http port of a running Resin server. It can be omitted if an http port can be inferred from a configuration file. When a configuration file isn’t specified these two options are required.

-user and -password are security options, they should match those defined in conf/admin-users.xml.

-name is the name of a new web-application context. When not specified, name is inferred from the name of a .war file, but cutting the .war extension.

-stage is used to actuate the deployed application only on staging servers. Configuration supplied with Resin by default runs sets Resin Server in production mode. That is also the default mode of Resin without configuration.

-version is used to specify version of the app deployed. With <web-app-deploy@versioning set to true, higher version will override lower version in the context.

-m is simply a commit message.

Next - is a deploy-copy command.

Deploy copy command will resemble to you a copy command of a version control system. It can be used to promote a version or rollback to an older version.

bin/resin.sh help deploy-copy
usage: bin/resin.sh [-conf <<file>] [-server <id>] deploy-copy -user <user> -password <password> [options]

description:
   copies a deployed application according to the given options

  options:
 -conf <file>          : resin configuration file
 -server <id>                     : id of a server
 -address <address>               : ip or host name of the server
 -port <port>                     : server http port
 -user <user>                     : user name used for authentication to the server
 -password <password>             : password used for authentication to the server
 -source <source>                 : source context
 -source-host <source-host>       : source host
 -source-stage <source-stage>     : source stage
 -source-version <source-version> : source version
 -target <target>                 : target context
 -target-host <target-host>       : target host
 -target-stage <target-stage>     : target stage
 -target-version <target-version> : target version
 -m <message>                     : commit message

The command has a source and a taget. The command can be used to copy between hosts, versions and contexts. For example, an application can be copied from context /foo to context /bar

bin/resin.sh -server a deploy-copy -user admin -password secret -source foo -target bar

Attributes that fit source|target-* pattern have the same meaning as with the deploy command, so I won’t go into greater detail on these in the blog.

Command deploy-list

The deploy-list simply lists the applications deployed. It accepts an optional regex pattern to match the applicaitons. It’s always a good idea to use the command with no pattern to see the complete list of applications deployed on Resin. Note, that this command does not list applications deployed by copying exploded directories into webapps. War files copied to webapps or deployed using the CLI or Resin Admin tool are listed with the command. A List of applications returned by the command may look like below.

bin/resin.sh -server a deploy-list -user admin -password secret
production/webapp/default/bar
production/webapp/default/foo
production/webapp/default/foo-1.0.0
production/webapp/default/foo-2.0.0

Commands deploy-start, deploy-stop, deploy-restart

The three commands accept the same list of options.

bin/resin.sh help deploy-start
usage: bin/resin.sh [-conf <file>] [-server <id>] deploy-start -user <user> -password <password> [options] <name>

description:
   starts application context specified in a <name>
options:
   -conf <file>          : resin configuration file
   -server <id>          : id of a server
   -address <address>    : ip or host name of the server
   -port <port>          : server http port
   -user <user>          : user name used for authentication to the server
   -password <password>  : password used for authentication to the server
   -host <host>          : virtual host to make application available on
   -stage <stage>        : name of the stage, for servers running in staging mode
   -version <version>    : version of application formatted as <major.minor.micro.qualifier>

As you can see the list of options repeats that of a deploy command.

Command undeploy

Applications deployed using deploy command or with Resin Administration Console can be undeployed using undeploy command. The command prints the following help message:

bin/resin.sh help undeploy
usage: bin/resin.sh [-conf <file>] [-server <id>] undeploy -user <user> -password <password> [options] <name>

description:
   undeploys application specified in a <name>

options:
   -conf <file>          : resin configuration file
   -server <id>          : id of a server
   -address <address>    : ip or host name of the server
   -port <port>          : server http port
   -host <host>          : virtual host to make application available on
   -stage <stage>        : stage to deploy application to, defaults to production
   -version <version>    : version of application formatted as <major.minor.micro.qualifier>
   -m <message>          : commit message

Producing a Heap Dump, Thread-Dump and Profiling Data

Things just got more exiting with Resin’s new heap-dump, thread-dump and profile commands. This commands are simple and require no JMX configuration. Let’s look at each command.

Command heap-dump

bin/resin.sh help heap-dump
usage: bin/resin.sh [-conf <file>] [-server <id>] heap-dump [-address <address>] [-port <port>] -user <user> \
 -password <password> [-raw]

description:
   prints heap summary taken on remote server

   -conf <file>          : resin configuration file
   -server <id>          : id of a server
options:
   -address <address>    : ip or host name of the server
   -port <port>          : server http port
   -user <user>          : user name used for authentication to the server
   -password <password>  : password used for authentication to the server
   -raw                  : creates an hprof file

Heap dump with Resin OSS is a shortcut to producing a regular .hprof that you can produce using java tools: e.g. JMX Console. The command however, requires no JMX configuration thus is more convenient. On Resin Pro, the command will produce a sorted list table of Objects in Memory. This is what the result of executing this command on a instance of Resin Pro might look like.

Heap Dump generated Thu Oct 20 09:54:29 PDT 2011
   count   |  self size | child size | class name
     96855 |   10205808 |   10205808 | char[]
     37898 |    1212736 |    5621168 | com.caucho.loader.JarMap$JarList
       134 |      12864 |    5087200 | com.caucho.util.LruCache
     45908 |    1469056 |    3856696 | java.lang.String
     14809 |    1521752 |    3785216 | java.util.HashMap$Entry[]
     17917 |    1545392 |    3328352 | java.lang.Object[]
      6719 |     322512 |    3245640 | java.util.HashMap
       134 |    3117536 |    3117536 | com.caucho.util.LruCache$CacheItem[]
     12802 |     307248 |    2675216 | com.caucho.util.CharBuffer
      9344 |    2669144 |    2669144 | byte[]
     49213 |    1574816 |    2464120 | java.util.HashMap$Entry
      8088 |     452928 |    1968336 | java.util.LinkedHashMap
     16126 |    1419088 |    1944088 | java.lang.reflect.Method
    106351 |    1701616 |    1701904 | java.lang.Object
      4728 |     491712 |    1603144 | com.caucho.quercus.module.StaticFunction
     15238 |     365712 |    1296120 | java.util.ArrayList
       481 |      23088 |    1133184 | java.util.concurrent.ConcurrentHashMap
      5609 |     134616 |    1131624 | sun.reflect.annotation.AnnotationInvocationHandler
       113 |       6328 |     951816 | com.caucho.db.block.Block
      7696 |     307840 |     878520 | java.util.concurrent.ConcurrentHashMap$Segment
     17984 |     719360 |     830480 | java.util.LinkedHashMap$Entry
       481 |      38480 |     798888 | java.util.concurrent.ConcurrentHashMap$Segment[]
      5260 |     294560 |     634632 | com.caucho.quercus.env.ConstStringValue
      7109 |     227488 |     612400 | com.caucho.xml.QName
        18 |        432 |     609056 | com.caucho.util.IntMap
        18 |     608544 |     608544 | com.caucho.util.IntMap$Item[]
     17409 |     557088 |     557088 | com.caucho.quercus.env.LongCacheValue

...

bin/resin.sh -server a -conf conf/resin.cloud.xml heap-dump -user admin -password secret -raw
Heap dump is written to `/home/alex/appservers/resin-pro-4.0.23/log/heap.hprof'.
To view the file on the target machine use
jvisualvm --openfile /home/alex/appservers/resin-pro-4.0.23/log/heap.hprof

Command thread-dump

The command is used to produce a thread-dump on a remote machine and either display it in a console or write to file.

bin/resin.sh help thread-dump
usage: bin/resin.sh [-conf <file>] [-server <id>] thread-dump [-address <address>] [-port <port>] \
-user <user> -password <password> [-file <file>]

description:
   prints a thread dump taken on remote server

   -conf <file>          : resin configuration file
   -server <id>          : id of a server
options:
   -address <address>    : ip or host name of the server
   -port <port>          : server http port
   -user <user>          : user name used for authentication to the server
   -password <password>  : password used for authentication to the server
   -file <file>          : file name where thread dump will be stored

The thread dump can be obtained by a kill -3, but not on Windows. This command is available on all platforms and displays the result in the invoking the command console. The output of the command is a thread dump formatted in a standart way.

Command profile

Available with Resin Pro, the command will turn Resin’s profiling feature on and collect samples at a requested rate over a requested period of time.

bin/resin.sh help profile
usage: bin/resin.sh [-conf <file>] [-server <id>] profile [-address <address>] [-port <port>] \
-user <user> -password <password> [-active-time <time>] [-sampling-rate <rate>] [-depth <depth>]

description:
   activates resin internal profiler (Pro version only)

options:
   -conf <file>          : resin configuration file
   -server <id>          : id of a server
   -address <address>    : ip or host name of the server
   -port <port>          : server http port
   -user <user>          : user name used for authentication to the server
   -password <password>  : password used for authentication to the server
   -active-time          : specifies profiling time span in ms (defaults to 5000 - 5 sec.)
   -sampling-rate        : specifies sampling rate (defaults to 10ms)
   -depth                : specifies stack trace depth (use smaller number (8) for smaller impact, larger
                           for more information). Defauts to 16.

The result of profiling might look something like this:

Profile started at 2011-10-20 11:15:03.865. Active for a total of 5000ms. Sampling rate 10ms. Depth 16.
   % time  |time self(s)|   % sum    | Method Call
  3286.364 |      7.230 |     24.140 | com.caucho.env.thread.ResinThread.waitForTask()
  3000.000 |      6.600 |     46.177 | com.caucho.vfs.JniSocketImpl.nativeAccept()
  1295.455 |      2.850 |     55.693 | com.caucho.vfs.JniSocketImpl.writeNative()
  1118.182 |      2.460 |     63.907 | com.caucho.env.thread.AbstractTaskWorker.run()
   731.818 |      1.610 |     69.282 | com.caucho.vfs.JniSocketImpl.writeNative()
   450.000 |      0.990 |     72.588 | com.caucho.vfs.JniSocketImpl.readNative()
   390.909 |      0.860 |     75.459 | com.caucho.vfs.JniSocketImpl.readNative()
   300.000 |      0.660 |     77.663 | com.caucho.quercus.QuercusContext$EnvTimeoutThread.run()
   300.000 |      0.660 |     79.866 | java.lang.Thread.sleep()
   213.636 |      0.470 |     81.436 | _jsp._loop__jsp._jspService()

The percentages may seem strange, but just remember that there are many threads that are doing the same thing adding up to more then a 100%. The important part is the proportion. As the profiling sampler takes its samples it looks at the stack trace of a frame and increments a count on that trace. Consider com.caucho.vfs.JniSocketImpl.nativeAccept() nativeAccept. Although it does’t do anything it appears at the top because in the idle state many threads are just waiting for a client connection to be made. In the real life application under load the distribution will be different. For this test I created a simple jsp page with a loop in it. As you can see it appears quite close to the top. The tables is followed by a list of expanded stack traces. Each entry in the table will have an expanded stack trace below. The stack traces will be ordered using the same ordering as a table. I am adding a ref# for stack traces as I write this blog entry. The ref# will help find the related entries faster.

Command litst-restarts

The command returns timestamps of server Restarts. The list of options can be obtained with bin/resin.sh help list-restarts. Example:

bin/resin.sh -server a -conf conf/resin.cloud.xml list-restarts -user admin -password secret
Server restarted `5' times since `Thu Oct 13 12:45:38 PDT 2011'
  Wed Oct 19 14:47:50 PDT 2011
  Wed Oct 19 14:56:19 PDT 2011
  Thu Oct 20 09:32:20 PDT 2011
  Thu Oct 20 09:35:25 PDT 2011
  Thu Oct 20 11:11:04 PDT 2011

This is all for Part 1 of the complete CLI blog coverage. In the next few days I will write a second part that covers the  log-level, jmx-* and user management commands.

Tags: CLI, Command Line, deploy, Heap Dump, performance profiler, resin, resin 4.0, Thread Dump

This entry was posted on Thursday, October 20th, 2011 at 2:23 pm and is filed under Engineering. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.