Merge 840e186 into 97a81e7

ngsi_event_broker/.gitignore

@@ -13,4 +13,6 @@ test-driver
 Makefile
 Makefile.in
 *.src.tar.gz
+*.changes
+*.deb
 docs

ngsi_event_broker/README.md

@@ -8,59 +8,130 @@ Nagios event broker ([NEB][NEB_ref]) module to forward plugin data to
 
 ## Installation
 
-As the module is an architecture-dependent compiled shared object,
-first we'll get sources either from this repository or downloading a
-[source code distribution][src_dist_ref].
+The module is an architecture-dependent compiled shared object distributed as
+a single library bundled in a Debian (.deb) or RedHat (.rpm) package. Assuming
+FI-WARE package repositories are configured, just use the proper tool (such as
+`apt-get` or `rpm`) to install `fiware-monitoring-ngsi-event-broker` package.
+Currently, packages for these are distributions are released:
 
-The first option requires *autotools* and *libtool* to be installed, in order
-to generate configuration script
+* Ubuntu 12.04 LTS
+
+As an alternative, module can be compiled from sources, either downloaded from
+SCM repository or as [source code tarball][src_dist_ref]. First option requires
+*autotools* and *libtool* to be installed, in order to generate configuration
+script
 
     $ mkdir m4
     $ autoreconf --install
 
-Once configuration script is generated/downloaded, follow these steps:
+Once `configure` script is generated (or downloaded as part of source tarball),
+follow these steps:
 
     $ ./configure
     $ make
     $ make check
     $ sudo make install
 
-Last step will try to copy generated shared object to the Nagios library
-directory, thus requiring sudoer privileges. Installation directory will
-usually be `/usr/lib/nagios` or `/usr/lib64/nagios`.
+Default target directory for this manual installation is Nagios libdir (usually
+`/usr/lib/nagios` or `/usr/lib64/nagios`) and requires sudoer privileges. This
+can be changed by running `./configure --libdir=target_libdir`.
 
 ## Usage
 
-Stop Nagios service and edit configuration file at `/etc/nagios/nagios.cfg`
-to add new broker module. The id of the [region][region_ref] that current
-infrastructure belongs to and the URL of NGSI Adapter must be supplied as
-arguments:
+Nagios should be instructed to load this module on startup. First, stop Nagios
+service and then edit configuration file at `/etc/nagios/nagios.cfg` to add the
+new broker module with its arguments: the id of the [region][region_ref] that
+current infrastructure belongs to, and the endpoint of NGSI Adapter component to
+request:
 
     event_broker_options=-1
     broker_module=/path/ngsi_event_broker_xifi.so -r region -u http://host:port
 
-Finally, start Nagios service. Check log files for module initialization (may
-fail for missing arguments, for example). Also check that requests are sent to
-adapter server in response to plugin executions. Requests will include some
-query string parameters:
-
-* SNMP monitoring:
-
-    `http://host:port/check_snmp?id=region:ifaddr/ifport&type=interface`
-
-* Host service monitoring:
-
-    `http://host:port/check_xxxx?id=region:hostname:servname&type=host_service`
+The module will use such information given as arguments together with data taken
+from the [Nagios service definition][nagios_service_ref] to issue a request to
+NGSI Adapter. In many cases, service definitions need no modifications and the
+broker just works transparently once Nagios is restarted. But there are some
+scenarios requiring slight changes in those service definitions (see below).
+
+Once main configuration file and service definitions have been reviewed, then
+start Nagios service. Check log files for module initialization (may fail for
+missing arguments, for example). Also check that requests are sent to Adapter
+server in response to plugin executions.
+
+#### Service definitions
+
+Assuming this Nagios host definition:
+
+    define host{
+        use                     linux-server
+        host_name               myhostname
+        alias                   linux_server
+        address                 192.168.0.2
+        }
+
+then a typical Nagios service definition would look like this:
+
+    define service{
+        use                     generic-service
+        host_name               myhostname
+        service_description     my service description
+        check_command           check_name!arguments
+        ...
+        }
+
+Depending on the entities being monitored (thus depending on the kind of plugins
+used), some of these data items are taken and some additional may be required.
+Requests to NGSI Adapter issued by this broker will all follow the pattern
+`http://{host}:{port}/{check_name}?id={region}:{uniqueid}&type={type}`, where:
+
+* `http://{host}:{port}` is the endpoint taken from broker arguments
+* `{check_name}` is taken from Nagios command specified at service definition
+* `{region}` is taken from broker arguments
+* `{uniqueid}` is taken from service definition, depending on the command plugin
+* `{type}` is also taken from service definition, also depending on the command
+
+For *SNMP monitoring* a Nagios command named `check_snmp` should be used. Entity
+type `interface` is assumed by default and `{uniqueid}` consist of the address
+and port number given as command arguments (see `check_snmp` manpage). Entity id
+in requests would be `{region}:{ifaddr}/{ifport}`
+
+For *host service monitoring* there are no restrictions on the command names and
+the plugins to be used. The `{uniqueid}` consist of the hostname and description
+of the service, resulting an entity id `{region}:{hostname}:{servicedesc}`.
+However, the exact entity type must be explicitly given with a custom variable
+`_entity_type` at service definition (or using templates, as follows):
+
+    define service{
+        use                     generic-service
+        name                    host-service
+        _entity_type            host_service
+        }
+
+    define service{
+        use                     host-service
+        host_name               myhostname
+        service_description     my service description
+        check_command           check_name!arguments
+        ...
+        }
+
+For *any other plugin executed locally* the entity id will include the local
+address and a `host` entity type will be assumed, resulting a request like
+`http://{host}:{port}/{check_name}?id={region}:{localaddr}&type=host`
+
+For *any other plugin executed remotely via NRPE* the entity id will include
+the remote address instead, a `vm` entity type will be assumed and the
+`{check_name}` will be taken from arguments of `check_nrpe` plugin
+
+Default entity types may be superseded in any case by including in the service
+definition the aforementioned custom variable `_entity_type`.
 
-* Other plugins executed locally:
-
-    `http://host:port/check_xxxx?id=region:localaddr&type=host`
+## Changelog
 
-* Other plugins executed remotely via NRPE:
+Version 1.3.1
 
-    `http://host:port/check_xxxx?id=region:nrpeaddr&type=vm`
-
-## Changelog
+* Included Debian package generation
+* Fixed error in argument parser
 
 Version 1.3.0
 
@@ -87,20 +158,24 @@ Version 1.0.0
 
 ## License
 
-(c) 2013 Telefónica I+D, Apache License 2.0
+(c) 2013-2014 Telefónica I+D, Apache License 2.0
 
 [NEB_ref]:
 http://nagios.sourceforge.net/download/contrib/documentation/misc/NEB%202x%20Module%20API.pdf
 "The Nagios Event Broker API"
 
 [NGSI_Adapter_ref]:
-https://github.com/Fiware/fiware-monitoring/tree/master/ngsi_adapter
+https://github.com/telefonicaid/fiware-monitoring/tree/master/ngsi_adapter
 "NGSI Adapter"
 
 [src_dist_ref]:
-https://forge.fi-ware.org/frs/download.php/1101/ngsi_event_broker-1.3.0.src.tar.gz
+https://forge.fi-ware.org/frs/download.php/1101/ngsi_event_broker-1.3.1.src.tar.gz
 "NGSI Event Broker source distribution package"
 
+[nagios_service_ref]:
+http://nagios.sourceforge.net/docs/3_0/objectdefinitions.html#service
+"Nagios Service Definition"
+
 [region_ref]:
 http://docs.openstack.org/glossary/content/glossary.html#region
 "OpenStack Glossary: Region"

ngsi_event_broker/script/build/files/debian/changelog

@@ -0,0 +1,39 @@
+fiware-monitoring-ngsi-event-broker (1.3.1) precise; urgency=low
+
+  * Included Debian package generation
+  * Fixed error in argument parser
+
+ -- Telefónica I+D <opensource@tid.es>  Mon, 14 Jul 2014 10:00:00 +0200
+
+fiware-monitoring-ngsi-event-broker (1.3.0) precise; urgency=low
+
+  * Included "host_service" monitoring
+
+ -- Telefónica I+D <opensource@tid.es>  Tue, 01 Apr 2014 13:25:37 +0200
+
+fiware-monitoring-ngsi-event-broker (1.2.0) precise; urgency=low
+
+  * Unification into a single _xifi broker
+
+ -- Telefónica I+D <opensource@tid.es>  Wed, 12 Mar 2014 15:48:40 +0200
+
+fiware-monitoring-ngsi-event-broker (1.1.0) precise; urgency=low
+
+  * Broker splitted into _snmp and _host
+  * IP address as unique identifier (within region) for hosts and vms
+  * Added region as argument
+  * Added NRPE support
+
+ -- Telefónica I+D <opensource@tid.es>  Wed, 05 Feb 2014 19:41:35 +0200
+
+fiware-monitoring-ngsi-event-broker (1.0.1) precise; urgency=low
+
+  * Added regions support (value retrieved from a metadata key named "region")
+
+ -- Telefónica I+D <opensource@tid.es>  Tue, 14 Jan 2014 12:21:39 +0200
+
+fiware-monitoring-ngsi-event-broker (1.0.0) precise; urgency=low
+
+  * Initial release of the module
+
+ -- Telefónica I+D <opensource@tid.es>  Mon, 25 Nov 2013 12:00:48 +0200

ngsi_event_broker/script/build/files/debian/compat

@@ -0,0 +1 @@
+8

ngsi_event_broker/script/build/files/debian/control

@@ -0,0 +1,13 @@
+Source: fiware-monitoring-ngsi-event-broker
+Section: main
+Priority: extra
+Maintainer: Telefónica I+D <opensource@tid.es>
+Build-Depends: debhelper (>= 8.0.0), autotools-dev
+Standards-Version: 3.9.2
+Homepage: https://github.com/telefonicaid/fiware-monitoring/tree/master/ngsi_event_broker
+Vcs-Git: git@github.com:telefonicaid/fiware-monitoring.git
+
+Package: fiware-monitoring-ngsi-event-broker
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}
+Description: Nagios event broker (NEB) module to forward plugin data to NGSI Adapter.

ngsi_event_broker/script/build/files/debian/copyright

@@ -0,0 +1,27 @@
+Format: http://dep.debian.net/deps/dep5
+Upstream-Name: fiware-monitoring-ngsi-event-broker
+Source: https://github.com/telefonicaid/fiware-monitoring/tree/master/ngsi_event_broker
+
+Files: *
+Copyright: 2013-2014 Telefónica I+D <opensource@tid.es>
+License: Apache-2.0
+
+Files: debian/*
+Copyright: 2013-2014 Telefónica I+D <opensource@tid.es>
+License: Apache-2.0
+
+License: Apache-2.0
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ .
+ On Debian systems, the complete text of the Apache version 2.0 license
+ can be found in "/usr/share/common-licenses/Apache-2.0".

ngsi_event_broker/script/build/files/debian/postinst

@@ -0,0 +1,49 @@
+#!/bin/sh
+# postinst script for fiware-monitoring-ngsi-event-broker
+
+set -e
+
+PACKAGE=fiware-monitoring-ngsi-event-broker
+FIWARE_USR=fiware
+FIWARE_GRP=fiware
+FIWARE_DIR=/opt/fiware
+BROKER_USR=$FIWARE_USR
+BROKER_GRP=$FIWARE_GRP
+BROKER_DIR=$FIWARE_DIR/ngsi_event_broker
+
+if [ "$1" = configure ]; then
+	VERSION=$2
+	# check FIWARE user
+	if ! getent passwd $FIWARE_USR >/dev/null; then
+		addgroup --quiet $FIWARE_GRP 2>/dev/null || true
+		adduser  --quiet --ingroup $FIWARE_GRP \
+		         --home /nonexistent --no-create-home \
+		         --disabled-password --shell /bin/false \
+		         --gecos "FI-WARE" $FIWARE_USR
+	fi
+	# check BROKER user
+	if ! getent passwd $BROKER_USR >/dev/null; then
+		addgroup --quiet $BROKER_GRP 2>/dev/null || true
+		adduser  --quiet --ingroup $BROKER_GRP \
+		         --home /nonexistent --no-create-home \
+		         --disabled-password --shell /bin/false \
+		         --gecos "FI-WARE NSGI Event Broker" $BROKER_USR
+	fi
+	# change directory ownership
+	chown -R $FIWARE_USR:$FIWARE_GRP $FIWARE_DIR
+	chown -R $BROKER_USR:$BROKER_GRP $BROKER_DIR
+	# change file permissions
+	chmod -R g+w $BROKER_DIR
+	find $BROKER_DIR -name "*.so" -exec chmod a+x {} \;
+	# postinstall message
+	fmt --width=${COLUMNS:-$(tput cols)} <<-EOF
+
+		NGSI Event Broker installed at $BROKER_DIR.
+
+		This library is intended to be used as a Nagios module, so
+		further configuration steps are required. Please read Usage
+		section at /usr/share/doc/$PACKAGE/README.md for more
+		details.
+
+	EOF
+fi

ngsi_event_broker/script/build/files/debian/rules

@@ -0,0 +1,20 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+# This file was automatically generated by dh_make tool:
+#	$ export DEBFULLNAME="Telefónica I+D"
+#	$ export DEBEMAIL="opensource@tid.es"
+#	$ dh_make -c apache -n -s -p fiware-monitoring-ngsi-event-broker_<x.y.z>
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+# Override this variable with an actual value
+NAGIOS_SRCDIR=
+
+%:
+	dh $@
+
+override_dh_auto_configure:
+	dh_auto_configure -- \
+	--with-nagios-srcdir=$(NAGIOS_SRCDIR) \
+	--libdir=/opt/fiware/ngsi_event_broker/lib

ngsi_event_broker/script/build/files/debian/source/format

@@ -0,0 +1 @@
+3.0 (native)