Skip to content

Home

Jump to bottom
ingvord edited this page Feb 3, 2021 · 28 revisions

Getting started with rest-server

NOTE: For versions < 2.0 see deprecated features section

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

Next you need to deploy and start Tango REST API implementation instance either via .war distribution or docker container:

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

Docker container

One way is to create a fresh docker image directly from the code of this repo:

$> git clone [email protected]:tango-controls/rest-server.git
$> cd rest-server
$> mvn package
$> docker build -t image_name . 
$> docker run -d image_name

OR

using distributed docker image

$> docker pull tangocs/rest-server:rest-server-2.1
$> docker run -p 8080:8080 -d tangocs/rest-server:rest-server-2.1

Now Tango REST API is available at localhost:8080. You may need to provide authentication credentials to access it. See next section for on how to setup it.

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

device

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

[1] Oracle Kerberos Requirements

.war

Add JAAS realm to META-INF/context.xml or {TOMCAT_HOME}/conf/server.xml:

        <Realm className="org.apache.catalina.realm.JAASRealm"
               appName="TangoRestServer"
               userClassNames="javax.security.auth.kerberos.KerberosPrincipal"
               roleClassNames="org.apache.catalina.users.MemoryRole"
               configFile="jaas.conf"/>

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>
  1. Adjust content of the LDAP realm according to your environment [1, 2]. DO NOT change commonRole attribute as it is required for mtangorest.server
  2. 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)

Setup HTTP/2.0

.war

For development purpose self-signed SSL certificate can be used. Ubuntu/Debian has pre-generated self-signed certificate (package ssl-cert):

$ sudo locate snakeoil
/etc/ssl/certs/ssl-cert-snakeoil.pem
/etc/ssl/private/ssl-cert-snakeoil.key

Add tomcat8 user to ssl-cert group:

sudo gpasswd -a tomcat8 ssl-cert

Edit /etc/tomcat8/server.xml by uncommenting https connector and altering certificate files:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol"
               maxThreads="150" SSLEnabled="true" >
        <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
        <SSLHostConfig>
            <Certificate certificateKeyFile="/etc/ssl/private/ssl-cert-snakeoil.key"
                         certificateFile="/etc/ssl/certs/ssl-cert-snakeoil.pem"
                         type="RSA" />
        </SSLHostConfig>
</Connector>

Restart Tomcat: sudo service tomcat8 restart

NOTE Apache Tomcat prior 9 (running on Java 8) requires libtcnative-1 to be installed

Deprecated features

Setup Tango Controls environment (depreceated since 2.0)

Define TangoRestServer device in the Tango DB:

jive

Device may have the following properties:

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

TOMCAT_SSL_CERTIFICATE_FILE [optional:default=/etc/ssl/certs/ssl-cert-snakeoil.pem] defines SSL certificate file used for HTTP/2.0 entrypoint

TOMCAT_SSL_CERTIFICATE_KEY_FILE [optional:default=/etc/ssl/private/ssl-cert-snakeoil.key] defines SSL certificate key file used for HTTP/2.0 entrypoint

Tango REST device (deprecated since 2.0)

When started mTangoREST server deploys a Tango device:

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>

Deploying .jar (deprecated since 2.0)

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

Setting up LDAP for .jar distribution (deprecated since 2.0)

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

Enabling HTTP/2.0 for .jar distribution (deprecated since 2.0)

To enable HTTP/2.0 in .jar distribution the following requirements must be met:

  1. Optionally provide ssl cert and key files as TangoRestServer device properties: TOMCAT_SSL_CERTIFICATE_FILE and TOMCAT_SSL_CERTIFICATE_KEY_FILE. By default these are /etc/ssl/certs/ssl-cert-snakeoil.pem and /etc/ssl/private/ssl-cert-snakeoil.key respectfully.

  2. Install required libtcnative-1 library (for Tomcat 9.0.13 1.2.14 is required)

  3. Run TangoRestServer under user with read access to certificate private key (member of ssl-cert group)

NOTE: HTTP/2.0 entry point will be available on Tomcat port + 40 e.g. if Tomcat port is set to 10001 (default value) corresponding HTTP/2.0 entry point will be on port 10041.

JavaScript console

There is an embedded JavaScript console:

Groooovy!

To access it user must have mtango-groovy role.

Variable context exports TangoRestServer instance into the console.

Clone this wiki locally