Differences

This shows you the differences between two versions of the page.

--- sensorweaver:admin-guide [2014-12-22 15:12] – luigi.fortunati
+++ sensorweaver:admin-guide [2017-12-04 14:40] (current) – davide
@@ Line 4: / Line 4: @@
 The guide assume that:
-  * You have a java 7 JRE installed on your system
+  * You have a java 8 JRE installed on your system
-  * Have basic administration knowledge of the [[http://karaf.apache.org/index.html|Karaf]] OSGi container
+  * You have basic knowledge on the administration of the [[http://karaf.apache.org/index.html|Karaf]] OSGi container
 ==== MQTT Broker ====
 The communication platforms relies on MQTT at the lowest communication layer.
 On linux/windows machines you can easily install the Mosquitto MQTT broker by downloading it on the [[http://mosquitto.org/|official website]].
 Ubuntu repositories alredy host a Mosquitto package, install it using apt with
 <code>
@@ Line 15: / Line 16: @@
 </code>
-Without any configuration you should already have an instance of mosquitto on your machine, already configured with open access on port 1883.
+Without any further configuration you should already have an instance of mosquitto running on your machine, with open access on port 1883.
 ==== Karaf ====
-Download the sensorweaver karaf bundle from this link and decompress it.
-The sensor weaver karaf bundle comes with custom configuration that enables it to download and start automatically sensorweaver bundles
-  * Karaf container
+We strongly recommend Apache Karaf as the OSGi container of choice. You have two choices:
-    * Download
+  * <del>Download a preconfigure Apache Karaf bundle</del>
-    * How to install
+  * Download Apache Karaf and use [[http://ala.isti.cnr.it:8081/nexus/index.html#nexus-search;gav~~sensorweaver-features~~xml~features|sensorweaver karaf features]]
-  * How to configure services
+=== SensorWeaver Karaf Bundle ===
+<del>The preconfigured SensorWeaver karaf bundle can be downloaded from this {{:sensorweaver:sensorweaver-karaf-bundle.tar.gz|link}}.
+That is based on Karaf 3.0.2 and already includes a default configuration that will launch the execution environment (Middleware included) with minimal effort required.
+You can install your bundles in the container and test it using Karaf [[http://karaf.apache.org/manual/latest/developers-guide/debugging.html|debug and logging tools]].</del>
+=== SensorWeaver features ===
+Alternatively you can download an Apache Karaf Distribution from the [[http://karaf.apache.org/index/community/download.html|Karaf download page]] and add the feature file manually.
+Please refer to Karaf [[http://karaf.apache.org/manual/latest/users-guide/provisioning.html|documentation]] to setup the feature repositores.
+To use sensorweaver features you first have to setup the maven repo in file 'org.ops4j.pax.url.mvn.cfg' under karaf etc folder.
+The last lines of the file should look like this:
+<file properties org.ops4j.pax.url.mvn.cfg>
+....
+http://repository.springsource.com/maven/bundles/external@id=spring-ebr-repository@snapshots@noreleases, \
+http://ala.isti.cnr.it:8081/nexus/content/repositories/wnlab-releases@id=wnlab-releases, \
+http://ala.isti.cnr.it:8081/nexus/content/repositories/wnlab-snapshots@id=wnlab-snapshots@snapshots
+</file>
+Including the snapshot repository is not mandatory.
+To install the whole set of middleware bundles, start karaf and execute the following karaf console commands:
+<code console>
+karaf@root()> feature:repo-add mvn:it.cnr.isti.sensorweaver/sensorweaver-features/2.1.4/xml/features
+Adding feature url mvn:it.cnr.isti.sensorweaver/sensorweaver-features/2.1.4/xml/features
+karaf@root()> feature:install middleware
+karaf@root()> list
+START LEVEL 100 , List Threshold: 50
+ID | State  | Lvl | Version | Name
+-------------------------------------------------------------------
+| Active |  80 | 2.3.1   | Gson
+| Active |  80 | 18.0.0  | Guava: Google Core Libraries for Java
+| Active |  80 | 2.0.6   | Messaging Service API
+| Active |  90 | 2.0.7   | MQTT Messaging Service
+| Active |  80 | 2.1.2   | Middleware API
+| Active |  90 | 2.1.2   | Middleware Service implementation
+| Active |  80 | 2.5     | Commons Lang
+| Active |  80 | 1.0.2   | Paho MQTT Client
+</code>
+The feature will install with default bundle configuration. At this point you can stop karaf and manually configure the bundles by modifying property files under the karaf 'etc' folder.
+==== Bundles configuration ====
+Middleware needs two components to be configured in order to run:
+  * Messaging configuration
+  * Middleware configuration
+Keep in mind that, since the Middleware components are stateful services, the configuration cannot be updated at runtime without disrupting clients, hence a bundle restart is required each time the configuration is changed.
+Middleware components will just ignore dynamic changes to their configuration at runtime.
+Messaging configuration includes the target MQTT broker and security options.
+Default messaging system configuration assumes that you have a MQTT broker listening on localhost on port 1883, without security enabled.
+You can modify messaging system configuration by creating a configuration file in the ''etc'' folder of Apache Karaf.
+Here is the default configuration:
+<file properties it.cnr.isti.sensorweaver.messaging.mqtt.cfg>
+host=localhost
+port=1883
+truststorePassword=
+keystorePassword=
+truststorePath=
+keystorePath=
+username=
+password=
+mode=anonymous
+</file>
+Messaging layer can follow one of these broker authentication mechanisms (mode field):
+  * //anonymous//: broker must be set to allow anonmyous clients
+  * //password//: by setting the mode to password the messaging layer will connect to the broker using the //username// and //password// provided in the available fields. Refer to the broker documentation to set the authentication credentials.
+  * //certificate//: certificate based authentication. Refer to [[https://mosquitto.org/man/mosquitto-tls-7.html|this]] guide for the creation of the keys and certificates (comprising the CA certificate).
+Middleware configuration includes a scope name assigned to the middleware instance. A scope identify an area of visibility of data on the Middleware.
+Each middleware instance is assigned a nodeId at startup. The nodeId can be set via configuration. If an ID is not provided, the hostname is used.
+Here is the default configuration:
+<file properties it.cnr.isti.sensorweaver.middleware.cfg>
+scope=default
+nodeId=
+</file>
+The scope defines a domain under which messages are published on the broker and is the first level of each topic used for message publication.
+The nodeId, if not provided, defaults to the client hostname. It can be set manually by configuration.