Resin Documentation

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.

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.

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.

        # 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).

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

        ~$curl --user admin:secret http://localhost:8080/resin-rest/jmx-list
      

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.

~$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"
          }
          ...
        ]

      

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

A value other than "application/x-www-form-urlencoded" must be specified as a value for Content-Type header.

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

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

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

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

Action jmx-call invokes an action on an MBean.

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

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

Note

Attribute name must be Capitalized (e.g. Foo not foo)

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

Note

The license file should be passed in the request body.

        curl -H "Content-Type: " --user admin:secret \
              --data-binary @/tmp/my-conf.jar \
              'http://localhost:8080/resin-rest/config-deploy'
      

Note

A value other than "application/x-www-form-urlencoded" must be specified as a value for Content-Type header.

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

        curl --user admin:secret
        'http://localhost:8080/resin-rest/list-restarts'
      

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

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

        curl --user admin:secret
        'http://localhost:8080/resin-rest/pdf-report?snapshot=true&load-pdf=true' > my-report.pdf
      

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

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

A complete list of Meters can be looked up in Resin-Admin's graphs section.

Action thread-dump produces and returns thread dump.

Action user-add adds administrative user.

Action user-list lists administrative user.

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

Action web-app-deploy deploys a web application.

        curl -H "Content-Type: " \
             --data-binary @/tmp/my-app.war \
             --user admin:secret \
             'http://localhost:8080/resin-rest/web-app-deploy?context=foo'
      

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.

Action deploy-list lists deployed applications.

Action web-app-restart restarts an application.

Action web-app-start starts web application.

Action web-app-stop stops web application.

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