-
Notifications
You must be signed in to change notification settings - Fork 11
Testbed Runtime 0.9
The Testbed Runtime version 0.9 is a complete rewrite of the basic architecture. While some code from TR 0.8 and older is reused (e.g., drivers, APIs) most of the architecture was redesigned and implemented from scratch to be more clean and comprehensible, extensible, and fast. This document aims to provide a comprehensive overview over the general architecture, as well as on how to install and configure Testbed Runtime.
TODO: describe components SNAA, RS, iWSN, REST API, DeviceDB and WiseGui and how they are embedded in the portal and the gateway process, respectively.
The probably quickest way to install Testbed Runtime is to install it as a Debian package, using apt-get/aptitude. In order to do this you first need to add the Debian repository to apts sources:
wget -O - http://dev.itm.uni-luebeck.de/debian-repo/testbed-runtime-repo.gpg.key | apt-key add -
cd /etc/apt/sources.list.d
wget http://dev.itm.uni-luebeck.de/debian-repo/testbed-
Then, you can install TRs portal and/or gateway service simply by running
apt-get install tr.iwsn-portal
or
apt-get install tr.iwsn-gateway
As TR is writen (almost) purely in Java it is easy and feasible to run TR on every platform that supports Java. Unfortunately, we don't provide ready-to-install-and-run packages for other system than Debian. In order to run TR manually (without any kind of service wrapper) you can simply run it by passing the executable JAR to the Java VM, together with a configuration file (see below for more info on configuring):
java -jar tr.iwsn-portal-0.9-server.jar --logLevel INFO --config portal.properties
and
java -jar tr.iwsn-gateway-0.9-server.jar --logLevel INFO --config gateway.config
The configuration of a testbed installation typically involves one or more (depending on the scenario) configuration files for the portal server and one configuration file that is equal to all gateway hosts.
Testbed Runtime consists of several modules, each providing a certain public or internal functionality and/or API. The most important modules are:
- the
Reservation Systemservice (RS), - the
Sensor Network Authentication and Authorization (SNAA)service, - the DeviceDB, and
- the WiseGui service.
Most components take some basic parameters like the URI/Web server context path a service will be available on. Besides these
- RS and DeviceDB (an internal component storing configurations for IoT devices) can both be configured to use different types of persistence layers for it's reservation data,
- SNAA can be configured to use different authentication mechanisms, and
- WiseGui service takes several configuration parameters on how to present the GUI.
Below, you'll find several subsections, each describing in detail the configuration options of the corresponding component.
In order to configure which authentication backend to use you have to configure the following property to be eiter "DUMMY", "JAAS", "SHIBBOLETH", "SHIRO", or "REMOTE":
# Usage: The authentication backend of the SNAA service
# Example: DUMMY/JAAS/SHIBBOLETH/SHIRO/REMOTE
snaa.type =
The dummy backend simply authenticates and authorizes every user request. Basically, it is a "return true" implementation. Typically this SNAA configuration is used on personal desktop-size testbeds, during development or if no access controls have to be made.
If JAAS is chosen as backend the SNAA implementation will use the standardized Java Authentication and Authorization System (JAAS) to perform its tasks. The following two parameters suffice here:
# Usage: The JAAS backends configuration file (only if JAAS is used)
snaa.jaas.config_file =
# Usage: The login module for the JAAS backend (only if JAAS is used)
# Example: edu.internet2.middleware.shibboleth.jaas.htpasswd.HtpasswdLoginModule
snaa.jaas.loginmodule =
TODO: example configuration for .htpasswd files
For more information about JAAS and how it works, please refer to the corresponding documentation by Oracle.
While Shibboteth in general is a well-known single sign-on system, this backend for SNAA is project-specific for WISEBED. In WISEBED a Shibboleth installation is used and the following parameters will have to be set accordingly.
# Usage: The URL for the attribute based authorization backend data source used together with Shibboleth authentication (only if SHIBBOLETH and ATTRIBUTE_BASED are used)
# Example: jdbc:mysql://localhost:3306/snaportal
snaa.shibboleth.authorization.attribute_based.datasource.url =
# Usage: The key for the attribute based authorization backend data source used together with Shibboleth authentication (only if SHIBBOLETH and ATTRIBUTE_BASED are used)
# Example: homeOrganization
# Default value: homeOrganization
#snaa.shibboleth.authorization.attribute_based.key = homeOrganization
# Usage: The password for the attribute based authorization backend data source used together with Shibboleth authentication (only if SHIBBOLETH and ATTRIBUTE_BASED are used)
snaa.shibboleth.authorization.attribute_based.password =
# Usage: The username for the attribute based authorization backend data source used together with Shibboleth authentication (only if SHIBBOLETH and ATTRIBUTE_BASED are used)
snaa.shibboleth.authorization.attribute_based.username =
# Usage: The value for the attribute based authorization backend data source used together with Shibboleth authentication (only if SHIBBOLETH and ATTRIBUTE_BASED are used)
# Example: wisebed1.itm.uni-luebeck.de
snaa.shibboleth.authorization.attribute_based.value =
# Usage: The type of authorization backend to be used together with Shibboleth authentication (only if SHIBBOLETH is used)
# Example: ALWAYS_ALLOW/ALWAYS_DENY/ATTRIBUTE_BASED
# Default value: ALWAYS_ALLOW
#snaa.shibboleth.authorization.type = ALWAYS_ALLOW
# Usage: A proxy server to be used for the Shibboleth authentication service (only if SHIBBOLETH is used)
snaa.shibboleth.proxy =
# Usage: The URL of the Shibboleth authentication service (only if SHIBBOLETH is used)
# Example: https://wisebed2.itm.uni-luebeck.de/portal/TARWIS/Welcome/welcomeIndex.php
snaa.shibboleth.url =
The Shiro backend uses the Apache Shiro framework to perform authentication and authorization against a relational database schema using the JPA O/R mapper. Please configure the following properties to use ShiroSNAA:
# Usage: The number of iterations to be run for the hash algorithm to be used with Shiro authentication and authorization backend (only if SHIRO is used)
# Example: 1000
# Default value: 1000
#snaa.shiro.hash_algorithm.iterations = 1000
# Usage: The name of the hash algorithm to be used with Shiro authentication and authorization backend (only if SHIRO is used)
# Example: SHA-512
# Default value: SHA-512
#snaa.shiro.hash_algorithm.name = SHA-512
# Usage: The JPA (Hibernate) .properties file for the Shiro authentication and authorization backend (only if SHIRO is used)
snaa.shiro.jpa.properties_file =
The property snaa.shiro.jpa.properties_file has to point to a configuration file that contains all necessary information for the JPA framework to connect to the database. It must e.g., follow this example configuration properties:
hibernate.connection.url = jdbc:mysql://localhost:3306/tr_snaa
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto = update
hibernate.connection.username =
hibernate.connection.password =
The properties within this file will be passed to the Hibernate persistence provider upon startup. For more documentation about the allowed configuration parameters please read the Hibernate documentation.
It is possible to start the SNAA system as a separate process, not embedding it into the portal process. In this case the portal will use the SNAAs services by doing SOAP Web service calls to the remote endpoint. In order to realize this behavior please set the following property:
# Usage: The URI of the remote SNAA server (only if REMOTE is used)
# Example: http://localhost:8890/soap/v3/snaa
snaa.remote.uri =
# Usage: Persistence layer to use
# Example: GCAL/JPA/IN_MEMORY/REMOTE
# Default value: IN_MEMORY
#rs.type = IN_MEMORY
# Usage: Context path on which to run the RS service
# Example: /soap/v3/rs
# Default value: /soap/v3/rs
#rs.context.path = /soap/v3/rs
# Usage: Persistence layer configuration .properties file
rs.jpa.properties =
# Usage: The username of the Google account to be used (only if GCAL is used)
rs.gcal.username =
# Usage: The password of the Google account to be used (only if GCAL is used)
rs.gcal.password =
No configuration necessary.
# Usage: The URI of the remote RS service (only if REMOTE is used)
rs.remote.uri =
# Usage: The type of DeviceDB backend
# Example: IN_MEMORY/JPA/REMOTE/SMARTSANTANDER
# Default value: IN_MEMORY
#devicedb.type = IN_MEMORY
# Usage: The context path on which to run the device database REST API
# Example: /rest/v1.0/devicedb
# Default value: /rest/v1.0/devicedb
#devicedb.rest_api.context_path = /rest/v1.0/devicedb
# Usage: The context path on which to run the device database web frontend
# Example: /devicedb
# Default value: /devicedb
#devicedb.webapp.context_path = /devicedb
No configuration necessary.
# Usage: .properties file to initialize JPA backend for the device database
devicedb.jpa.properties =
# Usage: The URI the DeviceDB REST service runs on
devicedb.remote.uri =
# Usage: If used in the SmartSantander context: the URI of the EventBroker to connect to
# Example: tcp://lira.tlmat.unican.es:9020
devicedb.smartsantander.eventbroker.uri =
# Usage: If used in the SmartSantander context: the ID of the TR portal server in the Resource Directory (RD)
devicedb.smartsantander.rd.portal_id =
TODO: describe configuration options (the rest)
The gateway process is the process that actually connects phyisically with the sensor nodes through their serial port or some other means (such as a wireless connection). In order to do so, it tries to detect sensor nodes as soon as they are attached to the gateway host (or come into communication range). Then, the gateway fetches the configuration of the detected sensor node from the DeviceDB running on the portal server and connects to it. Then, it will "tell" the portal that this specific detected node was attached to this portal host by sending him an according message on a TCP connection using an internal protocol. The portal will remember this information and will, from now on, send all user requests to the connected sensor node over the TCP connection initiated by the gateway process.
So, in order to have the gateway process be fully functional the configuration of the gateway only consists of just a small set of configuration options. Below you find a typical configuration of the gateway process that is sufficient (replace $PORTAL_HOST with the actual hostname of the portal server):
urnprefix = urn:local:
gateway.portaladdress = $PORTAL_HOST:9990
devicedb.type = REMOTE
devicedb.remote.uri = http://$PORTAL_HOST:9999/rest/v1.0/devicedb
The parameter gateway.portaladdress is the host and port on which the portal process listens for connections initiated by the gateways. The DeviceDB is of type REMOTE, pointing to the REST API endpoint URL which runs on the portal server.
Additionally to the properties above, if you want to enable the plugin mechanism, add the following property to have TR check for plugins in the configured directory.
gateway.plugin_directory =
If run in the context of the SmartSantander project, TR requires some more properties:
devicedb.smartsantander.eventbroker.uri = tcp://$EVENTBROKER_HOST:9020
devicedb.smartsantander.rd.portal_id = my_portal_id
gateway.smartsantander.gateway_id = this_gateway_id
If given, TR will subscribe to events on the eventbroker running on $EVENTBROKER_HOST:9020 and listen for all events indicating that a device was added or removed from this gateway (identified by portal and gateway ID).