Home

Getting started with mTangoREST.server

Step-by-step guideline on how to install Tango REST API server and TangoWebapp (client) on Windows can be found here: Tango Controls tutorial

setup Tango Controls environment

Define TangoRestServer device in the Tango DB:

Device may have the following properties:

TANGO_DB [optional: default=tango://localhost:10000/sys/database/2] defines which tango_host(database) will be exported through this server. NOTE deprecated since rc4

TANGO_ACCESS [optional: default=tango://localhost:10000/sys/access_control/1] defines which TangoAccessControl device will be used for authentication. Maybe set to none this disables TangoAccessControl integration

TOMCAT_PORT [optional:default=10001] a port on which embedded tomcat will run

TOMCAT_AUTH_METHOD [optional:default=plain] defines which type of authentication mechanism will be used [plain|kerberos]. For more info on authentication see below.

Next you need to deploy and start mtangorest.server instance either via .war or .jar distribution:

.war

Unzip and place it into your servlet container's webapps folder ({CATALINA_HOME}/webapps). Restart the container. If everything is fine you should notice something like the following output in the log:

TangoRestServer has been initialized.
[2015-03-05 03:54:31,112] Artifact tango:war: Artifact is deployed successfully
[2015-03-05 03:54:31,113] Artifact tango:war: Deploy took 2 338 milliseconds

To be 100% sure that mtango.server is properly deployed open your browser and type in the address bar http://localhost:8080/tango/rest. An authorization popup will appear, to pass the authorization you should define user(s) with role(s) mtango-rest, mtango-admin *) in the servlet container (see {CATALINA_HOME}/conf/tomcat-users.xml). You should see a list of supported Tango REST API versions list:

#!json
{
  "rc3":"http://localhost:8080/tango/rest/rc3"
}

*) This one is used to access mTango admin panel. If you do not plan to use it (it is not required for this tutorial) just skip this role.

.jar

Download the latest mtango.server .jar.

To run the server simply execute the following: java -jar mtango.server.jar $INSTANCE,

where $INSTANCE is a desired Tango device instance name, e.g. test

Or create the following bash script and place it near to the jar (possibly where Starter device can find it):

#!bash
#!/bin/bash

echo "Using TANGO_HOST=$TANGO_HOST"

INSTANCE_NAME=$1
echo "Using INSTANCE_NAME=$INSTANCE_NAME"

#-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
JAVA_OPTS="-Xmx4G -Xshare:off -XX:+UseG1GC -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5009"
echo "Using JAVA_OPTS=$JAVA_OPTS"

/usr/bin/java -jar $JAVA_OPTS -DTANGO_HOST=$TANGO_HOST /usr/lib/tango/server/mtango.server-rc2-0.2.jar $INSTANCE_NAME org.tango.TangoRestServer $INSTANCE_NAME &

Now it is the time to test it. Use tango-cs/tango as username/password when prompted. The result must be like this one:

Authentication

mtangorest.server uses krb-authorization module to perform authorization.

This module supports two types of authorization mechanisms:

plain

Uses simple mtangorest.server device properties:

TOMCAT_USERS -- comma separated usernames

TOMCAT_PASSWORDS -- comma separated passwords

If above properties ain't set default username/password pair is: tango-cs/tango

kerberos

Changes in the source code are required to setup it: create a new file kerberos.properties in {src}/main/resources with the following content:

java.security.krb5.realm=<your_realm>
java.security.krb5.kdc=<your_kdc>

NOTE realm must be in UPPER_CASE otherwise this error will occur: stream modified (41)

Rebuild and restart the server.

Tango REST device

When started mTangoREST server deploys a Tango device:

this device exports the following attributes:

aliveProxies -- currently used proxies

cacheEnabled -- indicates whether HTTP cache-control headers are added to responses

attributeValueExpirationDelay -- defines the value for the Expires header for attribute values

staticValueExpirationDelay -- defines the value for the Expires header for static values (aka device info)

proxyKeepAliveDelay -- defines how long the server will keep TangoProxy instance

and the following commands:

setProxiesSource([devices,values]) -- sets proxy source value for each passed device (DeviceProxy.set_source)

NOTE: when .war file is deployed Tango device instance name is defined in web.xml:

#!xml

<context-param>
    <param-name>tango.rest.server.instance</param-name>
    <param-value>development</param-value>
</context-param>

Groovy console

There is embedded Groovy console:

To access it user must have mtango-groovy role.