Alignak Web services module
The installation of this module will copy some configuration files in the Alignak default configuration directory (eg. /usr/local/etc/alignak). The copied files are located in the default sub-directory used for the modules (eg. arbiter/modules).
To install the module from PyPI: :
sudo pip install alignak-module-wsTo install the module from the source files (for developing purpose): :
git clone https://github.com/Alignak-monitoring-contrib/alignak-module-ws
cd alignak-module-ws
sudo pip install . -eNote: using `sudo python setup.py install` will not correctly manage the package configuration files! The recommended way is really to use `pip`;)
This module for Alignak exposes some Alignak Web Services:
- GET / will return the list of the available endpoints
- GET /alignak_map that will return the map and status of all the Alignak running daemons
- POST /alignak_command that will notify an external command to the Alignak framework
- PATCH /host/<host_name> that allows to send live state for an host and its services, update host custom variables, enable/disable host checks
Once installed, this module has its own configuration file in the /usr/local/etc/alignak/arbiter/modules directory. The default configuration file is mod-ws.cfg. This file is commented to help configure all the parameters.
To configure an Alignak daemon (receiver is the recommended daemon) to use this module:
- edit your daemon configuration file (eg. receiver-master.cfg)
- add your module alias value (web-services) to the modules parameter of the daemon
Note that currently the SSL part of this module has not yet been tested!
As a default, all the WS endpoints require the client to provide some credentials. You can provide those credentials directly in the HTTP Authorization header or you can use the /login and /logout endpoints to create a WS session.
To provide the credentials you can use the token delivered by the Alignak backend when you are logging-in.
Example 1 (direct credentials provided): :
$ curl -X GET -H "Content-Type: application/json" --user "1442583814636-bed32565-2ff7-4023-87fb-34a3ac93d34c:" http://127.0.0.1:8888/alignak_logsExample 2 (login session): :
$ curl -H "Content-Type: application/json" -X POST -d '{"username":"admin","password":"admin"}' http://127.0.0.1:8888/login
{'_status': 'OK', '_result': ["1442583814636-bed32565-2ff7-4023-87fb-34a3ac93d34c"]}
$ curl -X GET -H "Content-Type: application/json" --user "1442583814636-bed32565-2ff7-4023-87fb-34a3ac93d34c:" http://127.0.0.1:8888/alignak_logsNote that using the login / logout session is an easy thing with a python library like requests with its session mechanism ;) Or with any client that handles sessions ...
The Alignak backend configuration part requires to set the Alignak backend endpoint and some login information. The login information are not mandatory because the module will use the credentials provided by the Web Service client when one will request on an endpoint with some credentials.
The Alignak arbiter configuration part is not mandatory. It will only be used by the module to get the Alignak daemons states to populate the /alignak_map endpoint. §Thus, you should only configure this part if you intend to use this endpoint to get some information.
To create a session near the Web Services server, POST on the /login endpoint and provide your username and password to authenticate near the Alignak backend. :
$ curl -H "Content-Type: application/json" -X POST -d '{"username":"admin","password":"admin"}' http://127.0.0.1:8888/login
{'_status': 'OK', '_result': ["1442583814636-bed32565-2ff7-4023-87fb-34a3ac93d34c"]}Logging out will clear the session on the server side. :
$ curl -H "Content-Type: application/json" -X GET http://127.0.0.1:8888/logoutTo get Alignak daemons states, GET on the alignak_map endpoint: :
$ wget http://demo.alignak.net:8888/alignak_map
$ cat alignak_map
{
"reactionner": {
.../...
},
"broker": {
.../...
},
"arbiter": {
"arbiter-master": {
"passive": false,
"polling_interval": 1,
"alive": true,
"realm_name": "",
"manage_sub_realms": false,
"is_sent": false,
"spare": false,
"check_interval": 60,
"address": "127.0.0.1",
"manage_arbiters": false,
"reachable": true,
"max_check_attempts": 3,
"last_check": 0,
"port": 7770
}
},
"scheduler": {
.../...
},
"receiver": {
.../...
},
"poller": {
.../...
}
}The state of the all the Alignak running daemons is returned in a JSON object formatted as the former example. each daemon type contains an object for each daemon instance with the daemon configuration and live state.
To get Alignak history, GET on the alignak_logs endpoint: :
$ wget http://demo.alignak.net:8888/alignak_logs
$ cat alignak_logs
{
"_status": "OK",
"items": [
{
"service_name": "Zombies",
"host_name": "chazay",
"user_name": "Alignak",
"_created": "Sun, 12 Mar 2017 19:14:48 GMT",
"message": "",
"type": "check.result"
},
{
"service_name": "Users",
"host_name": "denice",
"user_name": "Alignak",
"_created": "Sun, 12 Mar 2017 19:14:40 GMT",
"message": "",
"type": "check.result"
},
{
"service_name": "Zombies",
"host_name": "alignak_glpi",
"user_name": "Alignak",
"_created": "Sun, 12 Mar 2017 19:14:37 GMT",
"message": "",
"type": "check.result"
},
{
"service_name": "Processus",
"host_name": "lachassagne",
"user_name": "Alignak",
"_created": "Sun, 12 Mar 2017 19:14:18 GMT",
"message": "",
"type": "check.result"
},
.../...
]
}The result is a JSON object containing a _status property that should be 'OK' and an items array property that contain the 25 most recent history events stored in the backend. Each item in this array has the properties:
- _created: GMT date of the event creation in the backend
- host_name / service_name
- user_name: Alignak for Alignak self-generated events, else web UI user that provoked the event
- message: for an Alignak check result, this will contain the main check result information: state[state_type] (acknowledged/downtimed): output (eg. UP[HARD] (False/False): Check output)
- type is the event type:
# WebUI user comment "webui.comment",
# Check result "check.result",
# Request to force a check (from WebUI) "check.request", "check.requested",
# Add acknowledge (from WebUI) "ack.add", # Set acknowledge "ack.processed", # Delete acknowledge "ack.delete",
# Add downtime (from WebUI) "downtime.add", # Set downtime "downtime.processed", # Delete downtime "downtime.delete"
# timeperiod transition "monitoring.timeperiod_transition", # alert "monitoring.alert", # event handler "monitoring.event_handler", # flapping start / stop "monitoring.flapping_start", "monitoring.flapping_stop", # downtime start / cancel / end "monitoring.downtime_start", "monitoring.downtime_cancelled", "monitoring.downtime_end", # acknowledge "monitoring.acknowledge", # notification "monitoring.notification",
Some parameters can be used to refine the results:
- count: number of elements to get (default=25). According to the Alignak backend pagination, the maximu number of elements taht can be returned is 50.
- page: page number (default=0). With the default count (25 items), page=0 returns the items from 0 to 24, page=1 returns the items from 25 to 49, ...
- search: search criteria in the items fields. The search criteria is using the same search engin as the one implemented in the WebUI.
host_name:pattern, search for pattern in the host_name field (pattern can be a regex) service_name:pattern, search for pattern in the host_name field (pattern can be a regex) user_name:pattern, search for pattern in the host_name field (pattern can be a regex)
type:monitoring-alert, search for all events that have the monitoring.alert type
- several search criterias can be used simultaneously. Simply separate them with a space character:
host_name:pattern type:monitoring-alert`
(To be completed...)
Note that the returned items are always sorted to get the most recent first
To send an host/service live state, PATCH on the host endpoint providing the host name and its state: :
$ curl --request PATCH \
--url http://demo.alignak.net:8888/host \
--header 'authorization: Basic MTQ4NDU1ODM2NjkyMi1iY2Y3Y2NmMS03MjM4LTQ4N2ItYWJkOS0zMGNlZDdlNDI2ZmI6' \
--header 'cache-control: no-cache' \
--header 'content-type: application/json' \
--data '
{
"name": "passive-01",
"variables": {
"test": "test"
},
"active_checks_enabled": false,
"passive_checks_enabled": true,
"livestate": {
"state": "UP",
"output": "WS output - active checks disabled"
},
"services": {
"first": {
"name": "dev_BarcodeReader",
"active_checks_enabled": false,
"passive_checks_enabled": true,
"livestate": {
"state": "OK",
"output": "WS output - I am ok!"
}
}
}
}'
# JSON result
{
"_status": "OK",
"_result": [
"passive-01 is alive :)",
"[1491368659] PROCESS_HOST_CHECK_RESULT;passive-01;0;WS output - active checks disabled",
"[1491368659] PROCESS_SERVICE_CHECK_RESULT;passive-01;dev_BarcodeReader;0;WS output - I am ok!",
"Service 'passive-01/dev_BarcodeReader' unchanged.",
"Host 'passive-01' unchanged."
],
"_feedback": {
"passive_checks_enabled": true,
"active_checks_enabled": false,
"alias": "Passive host 1",
"freshness_state": "d",
"notes": "",
"retry_interval": 0,
"_overall_state_id": 4,
"freshness_threshold": 14400,
"location": {
"type": "Point",
"coordinates": [
46.60611,
1.87528
]
},
"check_interval": 5,
"services": {
"first": {
"active_checks_enabled": false,
"freshness_threshold": 43200,
"_overall_state_id": 1,
"freshness_state": "x",
"notes": "",
"retry_interval": 0,
"alias": "Barcode reader",
"passive_checks_enabled": true,
"check_interval": 0,
"max_check_attempts": 1,
"check_freshness": true
}
},
"max_check_attempts": 1,
"check_freshness": true
}
}The result is a JSON object containing a _status property that should be 'OK' and a _result array property that contains information about the actions that were executed. A _feedback dictionary property provides some informatyion about the host/service.
If an error is detected, the _status property is not 'OK' and a _issues array property will report the detected error(s).
The /host/host_name can be used to target the host. If a name property is present in the JSON data then this property will take precedence over the host_name in the endpoint.
For the host services states, use the same syntax as for an host: :
$ curl -X PATCH -H "Content-Type: application/json" -d '{
"name": "test_host",
"livestate": {
"state": "up",
"output": "Output...",
"long_output": "Long output...",
"perf_data": "'counter'=1"
},
"services": {
"test_service": {
"name": "test_service",
"livestate": {
"state": "ok",
"output": "Output...",
"long_output": "Long output...",
"perf_data": "'counter'=1"
}
},
"test_service2": {
"name": "test_service2",
"livestate": {
"state": "warning",
"output": "Output...",
"long_output": "Long output...",
"perf_data": "'counter'=2"
}
},
"test_service3": {
"name": "test_service3",
"livestate": {
"state": "critical",
"output": "Output...",
"long_output": "Long output...",
"perf_data": "'counter'=3"
}
},
}
}' "http://demo.alignak.net:8888/host"The livestate data for an host or service may contain: - `state`: "ok","warning","critical","unknown","unreachable" for a service. "up","down","unreachable" for an host. - `output`: the host/service check output - `long_output`: the host/service long output (second part of tha output) - `perf_data`: the host/service check performance data - `timestamp`: timestamp for the host/service check
To create/update host custom variables, PATCH on the host endpoint providing the host name and its variables: :
$ curl -X PATCH -H "Content-Type: application/json" -d '{
"name": "test_host",
"variables": {
'test1': 'string',
'test2': 12,
'test3': 15055.0,
'test4': "new!"
}
}' "http://demo.alignak.net:8888/host"The result is a JSON object containing a _status property that should be 'OK' and an _result array property that contains information about the actions that were executed.
If an error is detected, the _status property is not 'OK' and a _issues array property will report the detected error(s).
The /host/host_name can be used to target the host. If a name property is present in the JSON data then this property will take precedence over the host_name in the endpoint.
Note that the returned items are always sorted to get the most recent first
To enable/disable hosts/services checks, PATCH on the host endpoint providing the host (service) name and its checks configuration: :
$ curl -X PATCH -H "Content-Type: application/json" -d '{
"name": "test_host",
"active_checks_enabled": True,
"passive_checks_enabled": True,
"services": {
"test_service": {
"name": "test_ok_0",
"active_checks_enabled": True,
"passive_checks_enabled": True,
},
"test_service2": {
"name": "test_ok_1",
"active_checks_enabled": False,
"passive_checks_enabled": False,
},
"test_service3": {
"name": "test_ok_2",
"active_checks_enabled": True,
"passive_checks_enabled": False,
},
}
}' "http://demo.alignak.net:8888/host"The result is a JSON object containing a _status property that should be 'OK' and an _result array property that contains information about the actions that were executed.
If an error is detected, the _status property is not 'OK' and a _issues array property will report the detected error(s).
The /host/host_name can be used to target the host. If a name property is present in the JSON data then this property will take precedence over the host_name in the endpoint.
If the configuration parameters allow_host_creation and allow_service_creation are set in the module configuration file, hosts and services may be created when patching the /host endpoint.
Each time that the /host endpoint is patched, the module will check if the concerned host/services exist in the Alignak backend. If they do not exist, they will be created.
Some data may be provided for the creation in the template property. If no template data are provided, the host/service will be created with the default values defined in the backend. The host/service properties managed in the backend are described in the backend documentation.
To create hosts/services, PATCH on the host endpoint providing the host (service) data in the template property: :
$ curl -X PATCH -H "Content-Type: application/json" -d '{
"name": "test_host",
"template": {
"alias": "My host...",
"_templates": ["generic-host", "important"]
},
"services": {
"test_service": {
"name": "test_ok_0",
"template": {
"alias": "My service...",
"_templates": ["generic-service", "normal"]
},
}
}
}' "http://demo.alignak.net:8888/host"To send an external command, JSON post on the command endpoint.
For a global Alignak command: :
# Disable all notifications from Alignak
$ curl -X POST -H "Content-Type: application/json" -d '{
"command": "disable_notifications"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "DISABLE_NOTIFICATIONS"}
# Enable all notifications from Alignak
$ curl -X POST -H "Content-Type: application/json" -d '{
"command": "enable_notifications"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "ENABLE_NOTIFICATIONS"}If your command requires to target a specific element: :
# Notify a host check result for `always_down` host
$ curl -X POST -H "Content-Type: application/json" -d '{
"command": "PROCESS_HOST_CHECK_RESULT",
"element": "always_down",
"parameters": "0;Host is UP and running"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "PROCESS_HOST_CHECK_RESULT;always_down;0;Host is UP and running"}
# Notify a service check result for `always_down/Load` host
$ curl -X POST -H "Content-Type: application/json" -d '{
"command": "PROCESS_SERVICE_CHECK_RESULT",
"element": "always_down/Load",
"parameters": "0;Service is OK|'My metric=12%:80:90:0:100"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "PROCESS_SERVICE_CHECK_RESULT;always_down/Load;0;Service is OK"}
# Notify a service check result for `always_down/Load` host (Alignak syntax)
$ curl -X POST -H "Content-Type: application/json" -d '{
"command": "PROCESS_SERVICE_CHECK_RESULT",
"host": "always_down",
"service": "Load",
"parameters": "0;Service is OK|'My metric=12%:80:90:0:100"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "PROCESS_SERVICE_CHECK_RESULT;always_down/Load;0;Service is OK"}Note: the element parameter is the old fashioned Nagios way to target an element and you can target a service with host;service syntax or with host/service syntax. Alignak recommands to use the host, service or user parameters in place of element !
Note: a timestamp (integer or float) can also be provided. If it does not exist, Alignak will use the time it receives the command as a timestamp. Specify a timestamp parameter if you want to set a specific one for the command :
# Notify a host check result for `always_down` host at a specific time stamp
$ curl -X POST -H "Content-Type: application/json" -d '{
"timestamp": "1484992154",
"command": "PROCESS_HOST_CHECK_RESULT",
"element": "always_down",
"parameters": "0;Host is UP and running"
}' "http://demo.alignak.net:8888/command"
{"_status": "ok", "_result": "PROCESS_HOST_CHECK_RESULT;always_down;0;Host is UP and running"}Note: for the available external commands, see the Alignak documentation chapter on the external commands.
Contributions to this project are welcome and encouraged ... issues in the project repository are the common way to raise an information.