/fiware-orion

FIWARE Orion Context Broker

Primary LanguageC++GNU Affero General Public License v3.0AGPL-3.0

Orion Context Broker

This is the code repository for the Orion Context Broker, the reference implementation of the Publish/Subscribe Context Broker GE.

This project is part of FIWARE. Check also the FIWARE Catalogue entry for Orion

Any feedback on this documentation is highly welcome, including bugs, typos or things you think should be included but aren't. You can use github issues to provide feedback.

For documentation previous to Orion 0.23.0 please check the manuals at FIWARE public wiki:

GEi overall description

Orion is a C++ implementation of the NGSI9/10 REST API binding developed as a part of the FIWARE platform.

Orion Context Broker allows you to manage all the whole lifecycle of context information including updates, queries, registrations and subscriptions. It is an NGSI9/10 server implementation to manage context information and its availability. Using the Orion Context Broker, you are able to register context elements and manage them through updates and queries. In addition, you can subscribe to context information so when some condition occurs (e.g. an interval of time has passed or the context elements have changed) you receive a notification. These usage scenarios and the Orion Context Broker features are described in this document.

If this is your first contact with the Orion Context Broker, it is highly recommended to have a look to the brief Quick Start guide.

Build and Install

The recommended procedure is to install using RPM packages in CentOS 6.x. If you are interested in building from sources, check this document.

Requirements

  • System resources: see these recommendations
  • Operating system: CentOS/RedHat. The reference operating system is CentOS 6.3
    but it should work also in any later CentOS/RedHat 6.x version.
  • Database: MongoDB is required to run either in the same host where Orion Context Broker is to be installed or in a different host accessible through the network. The recommended MongoDB version is 2.6.9 (although it should work with later MongoDB 2.6.x and 3.0.x versions). It is not recommended using MongoDB 2.4.x., as some geolocated queries may not work.
    • Note that the officially supported MongoDB version is 2.6. In the case of using MongoDB 3.0 with its new authentication mechanism (SCRAM_SHA1) you may need to compile from sources using special switches for the MongoDB driver. See this issue for details.
  • RPM dependencies (some of these packages could not be in the official CentOS/RedHat repository but in EPEL, in which case you have to configure EPEL repositories, see http://fedoraproject.org/wiki/EPEL):
    • The contextBroker package (mandatory) depends on the following packages: boost-filesystem, boost-thread, libmicrohttpd, logrotate, libcurl and boost-regex.
    • The contextBroker-test package (optional) depends on the following packages: python, python-flask, python-jinja2, curl, libxml2, libxslt, nc, mongo-10gen and contextBroker. The mongo-10gen dependency needs to configure MongoDB repository, check this piece of documentation about that.

Installation

Using yum (recommended)

Configure the FIWARE yum repository (as described in this post). Then you can install doing (as root):

yum install contextBroker

Sometimes the above commands fails due to yum cache. In that case, run yum clean all and try again.

Using RPM file

Download the package from the FIWARE Files area. Look for the "DATA-OrionContextBroker" entry.

Next, install the package using the rpm command (as root):

rpm -i contextBroker-X.Y.Z-1.x86_64.rpm

Optional packages

Apart from the mandatory RPM described above, you can install the contextBroker-test package, which contain utility tools:

yum install contextBroker-test

or

rpm -i contextBroker-test-X.Y.Z-1.x86_64.rpm

Upgrading from a previous version

Upgrade procedure depends on whether the upgrade path (i.e. from the installed Orion version to the target one to upgrade) crosses a version number that requires:

  • Upgrading MongoDB version
  • Migrating the data stored in DB (due to a change in the DB data model).

Upgrading MongoDB version

You only need to pay attention to this if your upgrade path crosses 0.11.0 or 0.22.0. Otherwise, you can skip this section.

Migrating the data stored in DB

You only need to pay attention to this if your upgrade path crosses 0.14.1, 0.19.0 or 0.21.0. Otherwise, you can skip this section. You can also skip this section if your DB are not valuable (e.g. debug/testing environments) and you can flush your DB before upgrading.

If your upgrade cover several segments (e.g. you are using 0.13.0 and want to upgrade to 0.19.0, so both "upgrading to 0.14.1 and beyond from a pre-0.14.1 version" and "upgrading to 0.19.0 and beyond from a pre-0.19.0 version" applies to the case) you need to execute the segments in sequence (the common part are done only one time, i.e. stop CB, remove package, install package, start CB). In the case of doubt, please ask using StackOverflow (remember to include the "fiware-orion" tag in your questions).

Standard upgrade

If you are using yum, then you can upgrade doing (as root):

yum install contextBroker

Sometimes the above commands fails due to yum cache. In that case, run yum clean all and try again.

If you are upgrading using the RPM file, then first download the new package from the FIWARE Files area. Look for the "DATA-OrionContextBroker" entry.

Then upgrade the package using the rpm command (as root):

rpm -U contextBroker-X.Y.Z-1.x86_64.rpm

Running

Once installed, there are two ways of running Orion Context Broker: manually from the command line or as a system service (the later only available if Orion was installed as RPM package). It is not recommended to mix both ways (e.g. start the context broker from the command line, then use /etc/init.d/contextBroker status to check its status). This section assumes you are running Orion as system service. From command line alternative, check this document.

You will typically need superuser privileges to use Orion Context Broker as a system service, so the following commands need to be run as root or using the sudo command.

In order to start the broker service, run:

/etc/init.d/contextBroker start

Then, to stop the context broker, run:

/etc/init.d/contextBroker stop

To restart, run:

/etc/init.d/contextBroker restart

You can use chkconfig command to make contextBroker automatically start/stop when your system boots/shutdowns (see chkconfig documentation for details).

Configuration file

The configuration used by the contextBroker service is stored in the /etc/sysconfig/contextBroker file, which typical content is:

# BROKER_USER - What user to run orion-broker as
BROKER_USER=orion

# BROKER_PORT - the port/socket where orion-broker will listen for connections
BROKER_PORT=1026

# BROKER_LOG_DIR - Where to log to
BROKER_LOG_DIR=/var/log/contextBroker

# BROKER_PID_FILE - Where to store the pid for orion-broker
BROKER_PID_FILE=/var/log/contextBroker/contextBroker.pid

## Database configuration for orion-broker
BROKER_DATABASE_HOST=localhost
BROKER_DATABASE_NAME=orion

## Replica set configuration. Note that if you set this parameter, the BROKER_DATBASE_HOST
## is interpreted as the list of host (or host:port) separated by commas to use as
## replica set seed list (single element lists are also allowed). If BROKER_DATABASE_RPL_SET
## parameter is unset, Orion CB assumes that the BROKER_DATABASE_HOST is an stand-alone
## mongod instance
#BROKER_DATABASE_RPLSET=orion_rs

# Database authentication (not needed if MongoDB doesn't use --auth)
#BROKER_DATABASE_USER=orion
#BROKER_DATABASE_PASSWORD=orion

# Use the following variable if you need extra command line options
#BROKER_EXTRA_OPS="-t 0-255"

All the fields except BROKER_USER and BROKER_EXTRA_OPS map to one of the options described in command line options, as follows:

  • BROKER_PORT maps to -port
  • BROKER_LOG_DIR maps to -logDir
  • BROKER_PID_FILE maps to -pidpath
  • BROKER_DATABASE_HOST maps to -dbhost
  • BROKER_DATABASE_NAME maps to -db
  • BROKER_DATABASE_RPLSET maps to -rplSet
  • BROKER_DATABASE_USER maps to -dbuser
  • BROKER_DATABASE_PASSWORD maps to -dbpwd

Regarding BROKER_EXTRA_OPS, it is used to specify other options not covered by the fields above, as a string that is appended to the broker command line at starting time. Note that this string is "blindly" appended, i.e. the service script doesn't do any check so be careful using this, ensuring that you are providing valid options here and you are not duplicating any option in other BROKER_* field (e.g. not set BROKER_EXTRA_OPS="-port 1026" as BROKER_PORT is used for that).

Regarding BROKER_USER, it is the user that will own the contextBroker process upon launching it. By default, the RPM installation creates a user named 'orion'. Note that if you want to run the broker in a privileged port (i.e. 1024 or below) you will need to use 'root' as BROKER_USER.

Checking status

In order to check the status of the broker, use the following command with superuser privileges (using the root user or the sudo command):

/etc/init.d/contextBroker status

If broker is running you will get:

Checking contextBroker...                         Running

If broker is not running you will get:

Checking contextBroker...                         Service not running

API Overview

In order to create an entity (Room1) with two attributes (temperature and pressure):

(curl <orion_host>:1026/v1/contextEntities/Room1 -s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -X POST -d @- | python -mjson.tool) <<EOF
{
  "attributes" : [
{
  "name" : "temperature",
  "type" : "float",
  "value" : "23"
},
{
  "name" : "pressure",
  "type" : "integer",
  "value" : "720"
}
  ]
}
EOF

In order to query the entity:

curl <orion_host>:1026/v1/contextEntities/Room1 -s -S --header 'Accept: application/json' | python -mjson.tool

In order to update one of the entity atributes (temperature):

(curl <orion_host>:1026/v1/contextEntities/Room2/attributes/temperature -s -S --header 'Content-Type: application/json' --header 'Accept: application/json' -X PUT -d @- | python -mjson.tool) <<EOF
{
   "value" : "26.3"
}
EOF

Please have a look at the Quick Start guide if you want to test these operations in an actual public instance of Orion Context Broker. In addition, have a look to the API Walkthrough and API Reference sections below in order to know more details about the API (subscriptions, registrations, etc.).

API Walkthrough

API Reference Documentation

Testing

Ent-to-end tests

The functional_test makefile target is used for running end-to-end tests:

make functional_test INSTALL_DIR=~

Please have a look to the section on building the source code in order to get more information about how to prepare the environment to run the functional_test target.

Unit tets

The unit_test makefile target is used for running the unit tests:

make functional_test INSTALL_DIR=~

Please have a look to the section on building the source code in order to get more information about how to prepare the environment to run the unit_test target.

Advanced topics:

License

Orion Context Broker is licensed under Affero General Public License (GPL) version 3.