-
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 information on how to install and configure Testbed Runtime.
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-runtime.list
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.
In order to display all configuration options (including a bit of documentation) please run:
java -jar tr.iwsn-portal-0.9-SNAPSHOT-server.jar --helpConfig
for the portal server, or
java -jar tr.iwsn-gateway-0.9-SNAPSHOT-server.jar --helpConfig
for the gateway process. This will print out all available configuration parameters including a short description of their meaning.
Below, you'll find a more structured and detailed description on how to configure the invidual modules of Testbed Runtime.
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 web front-end.
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", "SHIRO", or "REMOTE":
# Usage: The authentication backend of the SNAA service
# Example: DUMMY/JAAS/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 delegate authentication and authorization to the standardized Java Authentication and Authorization System (JAAS). 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 =
As an example we'll use the well-known .htpasswd files used in the Apache HTTP servers. To use them, please put the following properties into the portals configuration file:
snaa.type = JAAS
snaa.jaas.config_file = snaa.jaas
snaa.jaas.loginmodule = HtpasswdFile
The property snaa.jaas.loginmodule points to the name of the JAAS module defined within with the snaa.jaas configuration file. ```snaa.jaas```` itself has the following content:
HtpasswdFile {
edu.internet2.middleware.shibboleth.jaas.htpasswd.HtpasswdLoginModule REQUIRED
htpasswdFile = "snaa.htpasswd";
};
The file snaa.htpasswd is standard-conform .htpasswd file that you can administer using e.g., the htpasswd command line utility.
For more information about JAAS and how it works, please refer to the corresponding documentation by Oracle.
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 =
# Usage: Comma-separated list of roles that shall be automatically assigned to users registering themselves
# Example: EXPERIMENTER,SERVICE_PROVIDER
# Default value: EXPERIMENTER
#snaa.shiro.user_registration.auto_roles = EXPERIMENTER
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.
After starting the portal server process you can administrate the user and rights database at http://mytestbed.domain.tld/admin/shiro-snaa.
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 =
The only thing that has to be configured for the RS is the type of persistence layer ("backend") you want to use:
# Usage: Persistence layer to use
# Example: GCAL/JPA/IN_MEMORY
# Default value: IN_MEMORY
#rs.type = IN_MEMORY
# Usage: Persistence layer configuration .properties file
rs.jpa.properties =
The property rs.jpa.properties points to another .properties file containing the Hibernate configuration properties for the RS database (cf. SNAA JPA backend configuration). Below is a sample configuration for the RS:
hibernate.connection.url = jdbc:mysql://localhost:3306/tr_rs
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.
# 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 additional configuration necessary. Please note that this "persistence layer" is in fact non-persistent as its contents will be lost upon restarting the portal process. Can be used if you either don't need to maintain a real reservation database in your testbed or e.g., during development / debugging.
The DeviceDB is the central configuration database of your testbed installation in which all device configurations (such as timeouts, node type, node address, ...) are looked up during runtime. E.g., if a gateway detects a new USB device attached to one of it's USB / serial ports it will try to recognize the device type and identifier and look up a matching configuration in the DeviceDB. If found, the gateway will then connect to the device to have it ready for experimentation.
Once setup the DeviceDB can be administered using the DeviceDB front-end running at http://YOUR_PORTAL_HOST/admin/devicedb. This site is password-protected using HTTP basic authentication (see section about admin UI).
Other than that, the following parameters need to be set to configure the DeviceDB persistence back-end:
# Usage: The type of DeviceDB backend
# Example: IN_MEMORY/JPA/REMOTE/SMARTSANTANDER
# Default value: IN_MEMORY
#devicedb.type = IN_MEMORY
No configuration necessary. Please note that this "persistence layer" is in fact non-persistent as its contents will be lost upon restarting the portal process. Can be used if you either don't need to maintain a real device database in your testbed or e.g., during development / debugging.
# Usage: .properties file to initialize JPA backend for the device database
devicedb.jpa.properties =
Again, the property refers to a Hibernate configuration file in .properties format. Below is an example configuration file:
hibernate.connection.url = jdbc:mysql://localhost:3306/tr_devicedb
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto = update
hibernate.connection.username =
hibernate.connection.password =
# Usage: The URI the DeviceDB REST service runs on
devicedb.remote.uri = http://mytestbed.domain.tld/rest/v1.0/devicedb
# 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 =
The following configuration properties are passed to the WiseGui front-end for initialization:
# Usage: The directory under which to find the WiseGui. If not given WiseGui will be served from a packaged internal version.
#wisegui.source_dir =
# Usage: Name of the testbed to be displayed in WiseGui frontend
# Default value: local testbed
#wisegui.testbed_name = local testbed
Every Testbed Runtime ships with a bundled version of the WiseGui packed into the portals jar file. If you want to use e.g., a newer (development) version or a fork simply clone the WiseGui project and set the wisegui.source_dir property to the directory that contains the cloned/forked WiseGui.
To customize the title of the testbed displayed to WiseGui users, please set wisegui.testbed_name.
In addition to customizing the WiseGui itself you should probably set a number of parameters that will be used to generate the "WiseML" document (an XML-based testbed self-description). The WiseML is used by e.g., the WiseGui to draw a map of the testbed. In the listing below you find the properties used at the Lübeck testbed:
portal.wiseml.setup.description = SmartSantander/WISEBED testbed Luebeck, Germany
portal.wiseml.setup.coordinate_type = geographic
portal.wiseml.setup.origin.latitude = 53.833836
portal.wiseml.setup.origin.longitude = 10.704606
portal.wiseml.setup.origin.x = 0
portal.wiseml.setup.origin.y = 0
portal.wiseml.setup.origin.z = 33.0
portal.wiseml.setup.origin.phi = -145.00
portal.wiseml.setup.origin.theta = 0
portal.wiseml.setup.origin.rho = 0
If the GPS coordinates are not given here, WiseGui will typically center the map according to the distribution of the sensor node locations configured in the DeviceDB.
Testbed Runtime comes with two administrative interfaces (at the time writing this): one for the DeviceDB (http://yourtestbed.yourdomain.tld/admin/devicedb) and one for the Shiro SNAA (http://yourtestbed.yourdomain.tld/admin/shiro-snaa, only if configured). Both sites are secured with HTTP basic authentication to be only accessible by testbed administrators.
To set/change username and password for the administrator please edit the following properties inside the portals configuration file:
admin.username = admin
admin.password = secret
and set them to more sensible values. The password is stored in plain-text format in this configuration file so please make sure file access is restricted accordingly on your server system.
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 = /usr/share/tr.iwsn-gateway/plugins
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).
The listings below show a realistic example configuration for a small testbed (one portal, one gateway). It uses the Shiro-based SNAA with a MySQL backend, as well as RS and DeviceDB with a MySQL backend. Once you've edited the configuration files and started the portal and gateway processes on the respective hosts browse to the DeviceDB admin UI (http://mytestbed.domain.tld/admin/devicedb) to configure the devices available in your testbed. To create, edit and remove users browse to the Shiro SNAA admin UI (http://mytestbed.domain.tld/admin/shiro-snaa).
Contents of tr.iwsn-portal.properties:
hostname = mytestbed.domain.tld
urnprefix = urn:mytestbed:
admin.username = admin
admin.password = secret
eventstore.path = /var/log/tr.iwsn-portal/eventstore
snaa.type = SHIRO
snaa.shiro.jpa.properties_file = portal-snaa-shiro-jpa-mysql.properties
rs.type = JPA
rs.jpa.properties = portal-rs-jpa-mysql.properties
devicedb.type = JPA
devicedb.jpa.properties = portal-devicedb-jpa-mysql.properties
wisegui.testbed_name = My Testbed @ My Organization
Contents of portal-snaa-shiro-jpa-mysql.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 =
# configure connection pooling for production servers
hibernate.connection.provider_class=org.hibernate.connection.C3P0ConnectionProvider
hibernate.c3p0.acquire_increment=1
hibernate.c3p0.idle_test_period=60
hibernate.c3p0.min_size=1
hibernate.c3p0.max_size=10
hibernate.c3p0.max_statements=50
hibernate.c3p0.timeout=10
hibernate.c3p0.acquireRetryAttempts=1
hibernate.c3p0.acquireRetryDelay=250
# configure cache to get fast (only to be used if no other process touches database)
#hibernate.cache.provider_class = org.hibernate.cache.EhCacheProvider
#hibernate.cache.region.factory_class = org.hibernate.cache.ehcache.EhCacheRegionFactory
#hibernate.cache.use_second_level_cache = true
#hibernate.cache.use_query_cache = true
Contents of portal-rs-jpa-mysql.properties:
hibernate.connection.url = jdbc:mysql://localhost:3306/tr_rs
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto = update
hibernate.connection.username =
hibernate.connection.password =
# configure connection pooling for production servers
hibernate.connection.provider_class=org.hibernate.connection.C3P0ConnectionProvider
hibernate.c3p0.acquire_increment=1
hibernate.c3p0.idle_test_period=60
hibernate.c3p0.min_size=1
hibernate.c3p0.max_size=10
hibernate.c3p0.max_statements=50
hibernate.c3p0.timeout=10
hibernate.c3p0.acquireRetryAttempts=1
hibernate.c3p0.acquireRetryDelay=250
# configure cache to get fast (only to be used if no other process touches database)
#hibernate.cache.provider_class = org.hibernate.cache.EhCacheProvider
#hibernate.cache.region.factory_class = org.hibernate.cache.ehcache.EhCacheRegionFactory
#hibernate.cache.use_second_level_cache = true
#hibernate.cache.use_query_cache = true
Contents of portal-devicedb-jpa-mysql.properties:
hibernate.connection.url = jdbc:mysql://localhost:3306/tr_devicedb
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto = update
hibernate.connection.username =
hibernate.connection.password =
# configure connection pooling for production servers
hibernate.connection.provider_class=org.hibernate.service.jdbc.connections.internal.C3P0ConnectionProvider
hibernate.c3p0.acquire_increment=1
hibernate.c3p0.idle_test_period=60
hibernate.c3p0.min_size=1
hibernate.c3p0.max_size=10
hibernate.c3p0.max_statements=50
hibernate.c3p0.timeout=10
hibernate.c3p0.acquireRetryAttempts=1
hibernate.c3p0.acquireRetryDelay=250
# configure cache to get fast (only to be used if no other process touches database)
#hibernate.cache.provider_class = org.hibernate.cache.EhCacheProvider
#hibernate.cache.region.factory_class = org.hibernate.cache.ehcache.EhCacheRegionFactory
#hibernate.cache.use_second_level_cache = true
#hibernate.cache.use_query_cache = true
Contents of tr.iwsn-gateway.properties:
urnprefix = urn:mytestbed:
gateway.portaladdress = localhost:8880
devicedb.type = REMOTE
devicedb.remote.uri = http://localhost:8888/rest/v1.0/devicedb
The configuration file is identical for every gateway you set up, so you can safely copy this file on every gateway host.
Testbed Runtime ships with a device auto-detection feature, currently supporting Telos B, iSense, XBee and Pacemate nodes. For this it uses a slightly modified version of the motelist utility of TinyOS, which detects which nodes are attached to which USB port. A gateway host will:
- periodically run the extended motelist script
- calculate a difference to the last run to determine which devices were attached / detached since the last run.
- then try to download the device configuration from the DeviceDB by looking up either the devices MAC address (iSense) or its "reference". The "reference" (as printed out by motelist) corresponds to the ID of the USB-to-serial converter chip on the devices, giving you a unique, non-modifiable identifier.
- If the gateway could successfully download the configuration from DeviceDB it will try to connect to the device and if he is successful the WiseGui frontend should almost immediately show a 'tick' symbol instead of a 'cross', indicating the device to be ready for experimentation.
If you don't need / want device auto-detection you can simply disable it by adding
gateway.scan_devices = false
to a / each gateways configuration file. It will then not execute the motelist script. In order to connect to devices whatsoever you'd in this case have to use static device configuration (see below).
Some device types (e.g., TriSoS) don't support autodetection and/or have a very static hardware setup in which also serial/COM ports almost never change. In this case you can use the new (0.9.1-SNAPSHOT as of 18.02.2015 and later) static device configuration feature. For this, simply add an additional line to the individual gateways configuration file:
[...]
gateway.static_devices = urn:local:0x1,urn:local:0x2
For every node URN listed in this comma-separated string the gateway will try to find a configuration in the DeviceDB in which you can configure the node type and serial / COM port to which the device is attached. If the gateway can find this configuration it will connect to the device. If unsuccessful it will retry periodically, or if you change the configuration in DeviceDB.