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


 

Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

rest resin administration


Starting with version 4.0.26 Resin provides REST interface. Simple and secure, it can be used for integration with services such as RightScale® and others.

Overview

REST interface is provided for convenience of integration with administration and monitoring tools that are capable of using REST as integration protocol. Resin's set of REST actions covers functionality available via CLI and adds an extra action that allows retrieving Resin statistics data.

By default Resin REST is disabled. Default configuration also requires secure protocol.

REST actions, available via the interface, are required to be invoked with either GET or POST methods. Depending on the effect on the server the proper HTTP method is required: actions change state of the Resin's internal objects require POST method. Other actions must use GET.

enabling the interface

By default the interface is disabled. Un-commenting line rest_admin_enable : true in resin properties enables the REST service.

By default, the connection is required to be made over a secure protocol(HTTPS). Relaxing the secure constraint can be done with setting rest_admin_secure totrue.

Example: enabling Resin Secure REST interface
        # Enable Resin REST Admin
        rest_admin_enable : true

        # Require SSL for REST Admin
        rest_admin_secure : true
      

Resin REST Servlet is registered in cluster-default.xml file (see excerpt below for a reference).

Reference: registered REST Servlet
        <resin:if test="${rest_admin_enable}">
          <web-app id="/resin-rest"
                      root-directory="${resin.root}/doc/resin-rest">

            <resin:BasicLogin realm-name="resin"/>

            <resin:Allow url-pattern="/*">
              <resin:IfUserInRole role="resin-admin"/>
            </resin:Allow>

            <servlet-mapping url-pattern="/*"
                                servlet-class="com.caucho.admin.servlet.AdminRestServlet">
              <init>
                <require-secure>${rest_admin_secure}</require-secure>
              </init>
            </servlet-mapping>
          </web-app>
        </resin:if>
      

The registration can be augmented further with resin:IfNetwork constraint to limit access to specific IPs only. Adding the constraint must be considered when enabling access over HTTP.

invoking REST action

Invoking REST action requires constructing an HTTP request with proper url and body. REST action is encoded in the URL. Base of the URL is the address of the Resin server itself combined with the context name of the Resin REST web-app. The defaut URL is http://localhost:8080/resin-rest. Concatenating the URL with action name creates a complete Resin REST service URL. e.g. http://localhost:8080/resin-rest/jmx-list

Example: invoking Resin REST jmx-list action
        ~$curl --user admin:secret http://localhost:8080/resin-rest/jmx-list
      

interpreting Resin REST Service results

Resin REST replies with JSON Objects encoded as a String. Since integration requires interchangeable data format JSON, with the multitudes of available parsers in various languages, is a proper choice. The output below has been post-formatted and shortened for easy reading.

Example: invoking Resin REST jmx-list action
~$curl --user admin:secret \
       'http://localhost:8080/resin-rest/jmx-list?pattern=resin:type=Resin&print-values=true'

        [
          {
            "attributes":[
              ...
              {
                "name":"ConfigFile",
                "value":"/Volumes/projects/caucho/trunk/resin/conf/resin.xml"
              },
              {
                "name":"LogDirectory",
                "value":"/Volumes/projects/caucho/trunk/resin/log"
              },
              {
                "name":"ResinHome",
                "value":"/Volumes/projects/caucho/trunk/resin/"
              },
              {
                "name":"RootDirectory",
                "value":"/Volumes/projects/caucho/trunk/resin/"
              }
            ],
           "name":"resin:type=Resin"
          }
          ...
        ]

      

available REST actions

REST actions
ACTIONHTTP METHODDESCRIPTION
config-catGETprints configuration file deployed with config-deploy action or command
config-deployPOSTdeploys configuration
config-lslists files deployed via config-deploy command or action
config-undeployPOSTUn-deploys configuration deployed with config-deploy action
deploy-copyPOSTcopies an application from one context to another
deploy-listGETlists all applications deployed on a server
jmx-callPOSTcalls MBean's method
jmx-dumpGETdump all MBean attributes and values
jmx-listGETlists MBeans, attributes and operations
jmx-setPOSTsets value of a jmx attribute
license-addPOSTadds a license file
list-restartsGETlists Resin server restarts
log-levelPOSTconfigures log level for one or more loggers
pdf-reportGETproduces and returns pdf-report
statsGETprints stats collected by Resin
thread-dumpGETproduces a thread dump
user-addPOSTadds an user with Resin administrator privileges
user-listGETlists users with Resin administrator privileges
user-removePOSTremoves user added with user-add command or action
web-app-deployPOSTdeploys an application to Resin
web-app-restartPOSTrestarts deployed application
web-app-startPOSTstarts deployed application
web-app-stopPOSTstops deployed application
web-app-undeployPOSTundeploys an application deployed with web-app-deploy command

config-deploy

Command config-deploy deploys a configuration archive from an input stream to Resin cluster. Config-deploy action works with Resin's import tag, which imports from a cloud:/resin-inf/+.xml with default configuration (resin.xml)


          &resin:import fileset="cloud:/resin-inf/+.xml" recover="true"/>
      

Action expects the configuration to be streamed in the POST request body.

        curl -H "Content-Type: " --user admin:secret \
             --data-binary @/tmp/my-conf.jar \
             'http://localhost:8080/resin-rest/config-deploy'
      
note
Note
A value other than "application/x-www-form-urlencoded" must be specified as a value for Content-Type header.
config-deploy options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to deploy to
stagestage of the server's deploymentproduction
versionversion e.g.(1.0.0)
messagecommit message

config-cat

Similar to a unix 'cat' command config-cat prints content of a configuration file deployed to Resin using config-deploy action.

config-cat options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryDefaults to current server
namefull name of the configuration file inside the deployed configuration archive required
stagestage of the server's deployementDefaults to 'production'

config-ls

Action config-ls lists files deployed with config-deploy action.

config-ls options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryDefaults to the current server
namename of the file or directory
stagestage of the server's deploymentproduction
versionversion e.g.(1.0.0)

config-undeploy

Action config-undeploy un-deploys configuration deployed with config-deploy action.

config-undeploy options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to query
stagestage of the server's deploymentproduction
versionversion e.g.(1.0.0)
messagecommit message

jmx-list

Action jmx-list lists MBeans with (optionally) attributes and values.

jmx-list options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryDefaults to the current server
patternpattern used to query the MBeanServer e.g. java.lang:*resin:*
print-attributesprints attributesfalse
print-valuesprints values (overrides print-attributes)false
print-operationsprints operationsfalse
print-all-beansmatches all MBeansfalse
print-platform-beansmatches only java.lang:* MBeansfalse

jmx-call

Action jmx-call invokes an action on an MBean.

jmx-call options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryDefaults to the current server
patternJMX ObjectName pattern used to uniquely identify an MBeanrequired
operationname of operation (method) to invokerequired
operation-indexwhen multiple methods are named with the same name, help to choose the method to invoke 0
valuesspace separated list of argumentsrequired

jmx-dump

Action jmx-dump produces a complete dump of JMX tree with attributes and values.

jmx-dump options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server

jmx-set

Action jmx-set sets a value on an JMX JBean's attribute.

note
Note
Attribute name must be Capitalized (e.g. Foo not foo)
jmx-set options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
patternJMX ObjectName pattern that uniquely identifies an MBeanrequired
attributename of the attributerequired
valuenew value for the attributenull

license-add

Action license-add writes a license file into a remote Resin's license directory.

note
Note
The license file should be passed in the request body.
license-add options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryDefaults to the current server
overwriteoverwrites the file specified in 'to' if the file existsfalse
toname of the file to write torequired
restartoptionally restarts server after license is deployedfalse
        curl -H "Content-Type: " --user admin:secret \
              --data-binary @/tmp/my-conf.jar \
              'http://localhost:8080/resin-rest/config-deploy'
      
note
Note
A value other than "application/x-www-form-urlencoded" must be specified as a value for Content-Type header.

list-restarts

Action list-restarts prints restarts since a start of specified period.

list-restarts options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
periodlookback (from now) period. e.g. '7D'7 days (specifed as 7D)
list server restarts
        curl --user admin:secret
        'http://localhost:8080/resin-rest/list-restarts'
      

log-level

Action log-level configures logging level for specified list of loggers.

log-level options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
loggersspace separated list of loggersroot logger ('') and 'com.caucho' logger
levelnew logging level(all, finest, finer, fine, config, info, warning, severe, off ) required
active-timespecifies period of time the new value will be activeuntil next restart

pdf-report

Action pdf-report creates a PDF report and optionally returns the PDF file with the Response.

pdf-report options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to queryrequired
reportbase name for the reportSnapshot
periodreporting period1 Day (1D)
log-directorydirectory to write the report to on the server sideResin's log directory
profile-timeturns execution profiler on for a specified time e.g. 20s (20 seconds)
sample-periodspecifies sampling rate e.g. 150ms100ms
snapshotincludes JMX, thread dump and memory analysis in the reportfalse
watchdogspecifies period as the starting of the serverfalse
load-pdfStreams PDF Report file with the responsefalse
creating and loading pdf report
        curl --user admin:secret
        'http://localhost:8080/resin-rest/pdf-report?snapshot=true&load-pdf=true' > my-report.pdf
      

stats

Action stats returns statistics that can be used for building graphs. The JSON formatting is compatible with jquery-flot graph solution()

stats options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
serverserver to queryrequired
meterscomma separated list of meters e.g.(JVM|Memory|Heap Memory Used, )
periodtime span from now e.g. 2D (2 days)7D
querying Memory statistics

curl --user admin:secret \
     'http://localhost:8080/resin-rest/stats?meters=JVM|Memory|Heap%20Memory%20Used'
            [
              {
              "label":"00|JVM|Memory|Heap Memory Used",
              "data": [
                [1330983197106,0.0],
                [1330983257158,8.5000192E7],
                [1330983299997,8.5000192E7],
                [1330983359987,8.5000192E7],
                [1330983419984,8.5000192E7],
                [1330983479994,8.5000192E7],
                [1330983539986,8.5000192E7],
                [1330983599990,8.5000192E7],
                [1330983659998,8.5000192E7],
                [1330983719999,8.5000192E7],
                [1330983779994,8.5000192E7],
                [1330983839995,8.5000192E7],
                [1330983900012,8.5000192E7],
                [1330983959983,8.5000192E7],
                [1330984019988,8.5000192E7],
                [1330984079986,8.5000192E7],
                [1330984139984,8.5000192E7],
                [1330984199999,8.5000192E7],
                [1330984259992,8.5000192E7],
                [1330984319991,8.5000192E7],
                [1330984379991,8.5000192E7],
                [1330984439987,8.5000192E7],
                [1330984499994,8.5000192E7],
                [1330984559984,8.5000192E7],
                [1330984619996,8.5000192E7],
                [1330984679996,8.5000192E7],
                [1330984739988,8.5000192E7],
                [1330984799980,8.5000192E7],
                [1330984859999,8.5000192E7],
                [1330984919990,8.5000192E7],
                [1330984979992,1.07880448E8]
              ]
              }
            ]
          
note
Note
A complete list of Meters can be looked up in Resin-Admin's graphs section.

thread-dump

Action thread-dump produces and returns thread dump.

thread-dump options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server

user-add

Action user-add adds administrative user.

user-add options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to query
userspecifies user namerequired
passwordspecifies passwordrequired

user-list

Action user-list lists administrative user.

user-list options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to query

user-remove

Action user-remove removes administrative user added with user-add action.

user-remove options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to query
userspecifies user namerequired

web-app-deploy

Action web-app-deploy deploys a web application.

web-app-deploy options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to deploy to
contextweb application contextrequired
hosthost to deploy to'default'
stagestate to deploy toproduction
versionversion e.g. 1.0.0
messagecommit message
deploying an application via REST
        curl -H "Content-Type: " \
             --data-binary @/tmp/my-app.war \
             --user admin:secret \
             'http://localhost:8080/resin-rest/web-app-deploy?context=foo'
      

deploy-copy

Action deploy-copy is used to copy an application from one context to another. Application copied from source context to a target context. The target context is started upon completion of the operation.

deploy-copy options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad serverdefaults to the current server
source-contextcontext to copy an application from e.g. /foorequired
source-hosthost to copy an application from
source-stagestage of the source deploymentproduction
source-versionversion of the source deploymentHEAD
target-contextcontext to copy an application to e.g. /barrequired
target-hosthost to copy an application to
target-stagestage of the target deployment
target-versionversion of the target deployment
messagecommit message

deploy-list

Action deploy-list lists deployed applications.

deploy-list options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server

web-app-restart

Action web-app-restart restarts an application.

web-app-restart options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
tagtag to restart e.g. (production/webapp/default/foo)required
contextcontext to restartrequired
stagedeployment stage of the contextproduction
hostdeployment host'default'
versiondeployment version

web-app-start

Action web-app-start starts web application.

web-app-start options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
tagtag to start e.g.(production/webapp/default/foo)required
contextcontext to startrequired
stagedeployment stage of the contextrequired

web-app-stop

Action web-app-stop stops web application.

web-app-stop options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servercluster server to querydefaults to the current server
tagtag to start e.g.(production/webapp/default/foo)required
contextcontext to stoprequired
stagedeployment stage of the contextrequired

web-app-undeploy

Action web-app-undeploy un-deploys deployed web application.

web-app-undeploy options
PARAMETERDESCRIPTIONDEFAULT/REQUIRED
servertriad server to query
contextcontext to undeployrequired
hostcontext deployment host'default'
stagecontext deployment stageproduction
versionversion
messagecommit message

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