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:
- Orion Context Broker - Installation and Administration Guide
- Orion Context Broker - User and Programmers Guide
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.
The recommended procedure is to install using RPM packages in CentOS 6.x. If you are interested in building from sources, check this document.
- 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.
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.
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
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
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).
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.
- Orion versions previous to 0.11.0 recommend MongoDB 2.2
- Orion version from 0.11.0 to 0.20.0 recommend MongoDB 2.4. Check the 2.4 upgrade procedure in the oficial MongoDB documentation.
- Orion version from 0.21.0 on recommend MongoDB 2.6 o 3.0. check the 2.6 upgrade procedure or the 3.0 upgrade procedure in the oficial MongoDB documentation.
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.
- Upgrading to 0.14.1 and beyond from a pre-0.14.1 version
- Upgrading to 0.19.0 and beyond from a pre-0.19.0 version
- Upgrading to 0.21.0 and beyond from a pre-0.21.0 version
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).
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
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).
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.
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
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.).
- FIWARE NGSI v1 (Markdown)
- FIWARE NGSI v2 (Apiary) - ongoing, not yet suitable for production
- FIWARE NGSI v1 (XSD and PDF)
- FIWARE NGSI v2 (Apiary) - ongoing, not yet suitable for production
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.
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.
- Installation and administration
- API
- Pagination
- Geolocation
- Structured values for attributes
- Context Providers registration and request forwarding
- Attribute metadata
- Filtering results
- Multy tenancy
- Entity service paths
- Adding and removing attributes and entities with APPEND and DELETE in updateContext
- Updating registrations and subscriptions
- Context broker federation
- Forbidden characters
- Duration (for registration and subscriptions)
- Using empty types
- Mixing standard and convenience operations
- HTTP and NGSI response codes
- Security considerations
- Known limitations
- Container-based deployment
- Sample code contributions
- Deprecated features
Orion Context Broker is licensed under Affero General Public License (GPL) version 3.