Introducing Resin Command Line Part 2
Since I published Part 1 of the Resin Command Line Overview we’ve added a few more commands. The added commands allows to enable or disable a server, add a license, deploy new configuration files and generate admin password. Today I hope to cover commands I did not cover in part on and the new commands. List of new commands:
| Command | Description | Resin / Resin Pro |
|---|---|---|
| start-all | starts all servers listening to the machine’s IP interfaces | Resin |
| license-add | adds a Resin-Professional license to an installation | Resin Pro |
| enable | enable a Resin server to receive load-balance requests | Resin Pro |
| disable | disables a server for load-balancing | Resin Pro |
| disable-soft | allows existing sessions to finish and disables the server | Resin Pro |
| generate-password | generates an administrator user and password | Resin |
Command start-all
The command simply starts all Resin servers that bind to machine’s interfaces. Before explaining in detail what this command does I have to delve into explaining new feature of Resin Pro 4.0.24. Starting version 4.0.24 Resin introduces a new configuration tag that allows to configure multiple servers at once. The tag works with resin.properties that allows specifying the list of addresses that the new servers will bind to. Using resin.properties allows to localize the changes to a single short file and makes editing configuration a bit easier compared to XML based files. The new server-multi tag will look as below:
<cluster id="app_tier"> <!-- define the servers in the cluster --> <server-multi id-prefix="app-" address-list="${app_tier}" port="6800"/>
Property app_tier is imported from resin.properties:
app_tier : 192.168.1.16;192.168.1.17
Command start-all will examine the IPs and if they are assigned to any of the local interfaces will start appropriate server. The server names are assigned dynamically by adding an index to id-prefix of the server-multi tag. The index is derived from position of a particular IP in address-list. Such, for the two IPs defined in the example above app-0 and app-1 will be started.
bin/resin.sh help start-all starts all servers listening to the machine's IP interfaces 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
Once the servers are started you can shut them down with a resin shutdown command (bin/resin.sh shutdown). Don’t forget about status command to check on status of the servers.
Commands enable, disable and disable-soft
When a need arises to take a server out of rotation with the load-balancer or bring the server back into rotation commands disable(-soft) or enable come into play. Resin’s Load-Balancer (configured in resin.xml with web-tier attributes) integrates with the app-tier’s dynamic capabilities. Web-tier and app-tier’s knowing of each other allow for Resin’s Cloud Elasticity (growing or shrinking). Taking a server out is can be done with either disable or disable-soft commands. Disable-soft allows server to finish sessions that it’s serving. Once the disable-soft command is issued web-tier will no longer distribute any new client’s requests to a that server. The commands take the exact same list of arguments at the moment, available with bin/resin.sh help enable|disable|disable-soft
bin/resin.sh help enable bin/resin.sh help enable usage: bin/resin.sh [-conf <file>] -server <triad-server> enable -address <address> -port <port> -user <user> \ -password <password> <server> description: enables specified in <server> argument server options: -server <triad-server> : one of the servers in the triad -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
Command jmx-dump, jmx-list, jmx-set and jmx-call
The set of Jmx commands helps query and execute actions on objects that are published via JMX. The easiest of the set is jmx-dump command. It only accepts the standart arguments and prints all registered MBeans with attributes and values. After executing the command you will see output similar to below:
resin $bin/resin.sh jmx-dump {"create_time": "Fri Dec 02 10:24:48 PST 2011" , "jmx": { "JMImplementation:type=MBeanServerDelegate" : { "ImplementationName": "Resin-JMX", "ImplementationVendor": "Caucho Technology", "ImplementationVersion": "Resin-4.0.s111202", "MBeanServerId": "Resin-JMX", "SpecificationName": "Java Management Extensions", "SpecificationVendor": "Sun Microsystems", "SpecificationVersion": "1.4" }, ...
If you’d like to query for a specific MBean or a set of MBeans you might want to use command jmx-list. This command accepts a pattern that queries only the MBeans that match the pattern. On the other hand, jmx-list command with *:* argument can be quite helpful when you don’t really know what you are looking for. Piping the output to grep makes combing through a vast amount of data a breeze. The jmx-list command can also print MBeans attributes and values, and, operatons. e.g.
bin/resin.sh jmx-list *:* JMImplementation:type=MBeanServerDelegate com.sun.management:type=HotSpotDiagnostic java.lang:type=ClassLoading java.lang:type=Compilation java.lang:type=GarbageCollector,name=ConcurrentMarkSweep java.lang:type=GarbageCollector,name=ParNew java.lang:type=Memory java.lang:type=MemoryManager,name=CodeCacheManager java.lang:type=MemoryPool,name=CMS Old Gen java.lang:type=MemoryPool,name=CMS Perm Gen java.lang:type=MemoryPool,name=Code Cache java.lang:type=MemoryPool,name=Par Eden Space java.lang:type=MemoryPool,name=Par Survivor Space java.lang:type=OperatingSystem java.lang:type=Runtime java.lang:type=Threading java.util.logging:type=Logging resin:type=AccessLog,Host=default resin:type=BlockManager resin:type=CacheStore resin:type=Cluster,name=app_tier resin:type=Cluster,name=cache_tier resin:type=Cluster,name=web_tier resin:type=ClusterServer,name=app-0 resin:type=ClusterServer,name=app-1 resin:type=ClusterServer,name=web-0
Command’s distinct options include the following:
bin/resin.sh help jmx-list usage: resinctl [--options] jmx-list [<pattern>] lists the JMX MBeans in a Resin server (Resin Pro) ... [common-remote-command-options] --all : when <pattern> not specified sets the wildcard pattern (*:*) --attributes : prints MBean's attributes --operations : prints operations --platform : when <pattern> not specified sets the pattern to (java.lang:*) --values : prints attribute values
Command jmx-set allows to change a value of a MBean attribute at run time. So the command options will include pattern, attribute and value. If the pattern matches multiple beans it will not perform updating of an attribute.
bin/resin.sh help jmx-set usage: resinctl [--options] jmx-set value sets a JMX value for a server MBean (Resin Pro) where options include: ... [common-remote-command-options] --attribute : name of the attribute --pattern : pattern to match MBean, adheres to the rules defined for javax.managment.ObjectName e.g. qa:type=Foo
The command will perform necessary conversions converting attribute from String to type of the attribute. Command jmx-call invokes MBean’s operation. Similarly to jmx-set, the command accepts a pattern that must uniquely identify MBean, operation name and a list of values that will be passed to the operation as parameters.
bin/resin.sh help jmx-call usage: resinctl [--options] jmx-call value... calls a JMX operation on a server MBean (Resin Pro) where options include: ... [common-remote-command-options] --operation <operation> : operation to invoke --pattern <pattern> : pattern to match MBean
Example of using jmx-call command to obtain a heap-dump
bin/resin.sh jmx-call -pattern com.sun.management:type=HotSpotDiagnostic -operation dumpHeap /tmp/heap.hprof true method `dumpHeap(java.lang.String, boolean)' called on `com.sun.management:type=HotSpotDiagnostic' returned `null'.
After the method completes you can view the heap dump with jvisualvm
jvisualvm --openfile /tmp/heap.hprof
Command pdf-report
This command can be very instrumental in collecting various information from JVM and Resin into one document. I’ve uploaded a sample file for you to download and examine. The report is truly more then one can cover in one blog post, but here is a short list of info that it provides.
The command writes the pdf report into Resin’s log directory.
bin/resin.sh help pdf-report usage: resinctl [--options] pdf-report creates a PDF report of a Resin server (Resin Pro) where options include: --address <ip> : IP address or host name of (triad) server --conf <file> : alternate resin.xml file --logdir <dir> : PDF output directory (default to resin log) --password <password> : admin password for authentication --path <file> : path to a PDF-generating .php file --period <time> : specifies look-back period of time (default 7D) --port <port> : IP port of (triad) server --profile-sample <time> : specifies profiling sampling frequency (100ms) --profile-time <time> : turns code profiling on for a time before generating report --report <value> : specifies the report-type key (default Snapshot) --resin-home <dir> : alternate resin home --server <id> : id of a server in the config file --snapshot : saves heap-dump, thread-dump, jmx-dump before generating report --user <user> : admin user name for authentication
You can take a look at the report produced with the following command:
bin/resin.sh -server app-0 pdf-report -snapshot -report blog-sample -profile-time 30s -period 30m
You can open the report for viewing by clicking on a link: Resin PDF Report.
Command generate-password
This command allows to quickly generate password for inserting into a resin.properties file or admin-users.xml file.
bin/resin.sh generate-password -user admin -password secret admin_user : admin admin_password : {SSHA}EsmhniwTx1zi5oSAn5etMsq7sFROhSmV
Command license-add
This command deploys a license to resin server and restarts the server if -restart option is specified.
bin/resin.sh help license-add usage: bin/resin.sh [-conf <file>] license-add -license <license file> [-to <filename>] [-overwrite] [-restart] description: copies a license file to the appropriate license directory options: ... [common-remote-command-options] -license <license file> : path to license file to add (required) -to <filename> : file name license will be written to (defaults to name of license file) -overwrite : overwrite existing license file if exists -restart : restart Resin after license is added
Command log-level
Command log-level is used to change the logging level at runtime. The logging level can be set to return to previous value automatically, after specified period of time.
bin/resin.sh help log-level usage: resinctl [--options] log-level loggers... sets the java.util.logging level for debugging (Resin Pro) where options include: --active-time <time> : specifies temporary level active time (default permanent). e.g. 5s --address <ip> : IP address or host name of (triad) server --all : all logs (rare to use) --conf <file> : alternate resin.xml file --config : configuration debugging logs --fine : finer debugging logs (admin/user-level) --finer : finer debugging logs (developer-level) --finest : finest debugging log --info : default logging level --off : disable logging --password <password> : admin password for authentication --port <port> : IP port of (triad) server --resin-home <dir> : alternate resin home --server <id> : id of a server in the config file --severe : severe, typically fatal warnings --user <user> : admin user name for authentication --warning : non-fatal warnings e.g. bin/resin.sh log-level -finer com.caucho.server.session Logger 'com.caucho.server.session' level is set to 'FINER'
Be cautious setting a log level to finer logging permanently, as it may cause the logs to fill up the disk space very quickly! Especially on servers under load. Set -active-time option to make sure you don’t forget to reset logging level.
Commands user-add, user-list and user-remove
The commands help with Resin administration. The users managed by these commands are Resin administrators. This is not a facility that you can use to add users to your particular application.
bin/resin.sh help user-add usage: bin/resin.sh [-conf <file>] user-add -user <user> -password <password> -u <new user name> [-p <new user password>] description: adds an administrative user options: -address <address> : ip or host name of the server -port <port> : server http port -user <user> : specifies name to use for authorising the request. -password <password> : specifies password to use for authorising the request. -u <new user name> : specifies name for a new user. -p <new user password> : specifies password for a new user.
E.g. adding a foo user identified by ’secret’ password
$bin/resin.sh user-add -u foo -p secret user `foo' added
E.g. listing users
resin-pro-4.0.24 $bin/resin.sh user-list foo
E.g. removing a user:
resin-pro-4.0.24 $bin/resin.sh user-remove foo user `foo' deleted resin-pro-4.0.24 $
Resin 4.0.25 will introduce new commands and we hope that the upcoming release finishes changes to CLI and at that point the CLI can be called ’stable’.
Stay tuned!