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|ldap]. 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:

$ curl -u "tango-cs:tango" http://localhost:10001/tango/rest
{"rc4":"http://localhost:10001/tango/rest/rc4"}

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

By default krb-authorization module looks for krb5.conf file (/etc/krb5.conf for Linux) [1]

Kerberos realm and kdc may be overridden via jvm properties: -Djava.security.krb5.realm=<your_realm> -Djava.security.krb5.kdc=<your_kdc>

For instance in IntelliJ IDEA (Run -> Edit Configurations...):

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

[1] Oracle Kerberos Requirements

ldap

.war

To setup ldap integration using .war distribution:

1. Deploy tango.war to {TOMCAT_BASE}/webapps
2. Once Tomcat extracts all files i.e. creates tango folder add context.xml file to tango/META-INF:

<?xml version='1.0' encoding='utf-8'?>
<Context reloadable="true">
    <!-- Default set of monitored resources -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>

    <!-- LDAP realm. Here we use Online LDAP Test Server: 
            http://www.forumsys.com/tutorials/integration-how-to/ldap/online-ldap-test-server/ -->
    <Realm  className="org.apache.catalina.realm.JNDIRealm"
            connectionURL="ldap://ldap.forumsys.com:389"
            userSubtree="true"
            userPattern="uid={0},dc=example,dc=com"
            allRolesMode="authOnly"
            commonRole="mtango-rest"
    />


</Context>

3. Adjust content of the LDAP realm according to your environment [1, 2]. DO NOT change commonRole attribute as it is required for mtangorest.server
4. Restart Tomcat. You should be able to access tango/rest/rc4 using, for instance, tesla/password pair.

[1] Apache Tomcat JNDIReam configuraion

[2] Configuring LDAP authentication (Apache Tomcat)

.jar

When deployed using .jar distribution LDAP properties must be specified in a dedicated file e.g. ldap.properties:

connectionURL=ldap://ldap.forumsys.com:389
userSubtree=true
userPattern=uid={0},dc=example,dc=com
allRolesMode=authOnly

In the example above Online LDAP Test server is used.

Alter the properties according to your environment!

mtangorest.server lookups ldap.properties file in the cwd by default, otherwise specify -DLDAP_PROPERTIES=... in TangoRestServer startup script e.g. -DLDAP_PROPERTIES=/etc/ldap.properties

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>

JavaScript console

There is an embedded JavaScript console:

To access it user must have mtango-groovy role.

Variable context exports TangoRestServer instance into the console.