Skip to main content
Version: 22.10

Canopsis Events

The Canopsis Events stream connector allows you to send data from Centreon to Canopsis using their HTTP REST API.

Before starting

  • In most cases, you will want to send data from the central server. It is also possible to send it from a remote server or a poller (e.g. if you want to avoid the central server being a SPOF, or if you are an MSP and you install the stream connector on a poller or a remote server within your customer's infrastructure).
  • By default, the Canopsis Events stream connector sends events from host_status, service_status,
    acknowledgement and downtime. Broker events. The event format is shown here.
  • These events are sent each time a host or a service is checked. Various parameters let you filter out events.

Compatibility

This stream connector is designed to be compatible with Canopsis' API v.4, this include the following versions of Canopsis : 22.10, 23.04, 23.10 and 24.04.

Installation

Perform the installation on the server that will send data to Canopsis (central server, remote server, poller).

  1. Login as root on the Centreon central server using your favorite SSH client.

  2. Run the following command:

dnf install centreon-stream-connector-canopsis

Configuring Canopsis

You will need to configure your Canopsis instance to receive data from Centreon. Refer to the Canopsis user guide , in particular check if creation, reading and deletion rights are activated. See the following documentations:

  • rights administration
  • planification administration (in case of downtimes). For the user associated to the Authentication key you must modify the rights matrix on the Canopsis Administration > Rights page, API tab. You need to check at least the box listed in this table:
SectionSubsectionBoxes to check
GlobalEventCheck the only available box
PBehaviorPBehaviorsCheck the create, read, update and delete boxes
PBehaviorPBehaviors ExceptionsCheck the create and read boxes
PBehaviorPBehaviors ReasonCheck the create and read boxes
PBehaviorPBehaviors TypesCheck the read box

Make sure Canopsis is able to receive data sent by Centreon: flows must not be blocked by Canopsis's configuration or by a security equipment.

Configuring the stream connector in Centreon

  1. On your central server, go to Configuration > Pollers > Broker configuration.
  2. Click on central-broker-master (or the appropriate broker configuration if it is a poller or a remote server that will send events).
  3. On the Output tab, select Generic - Stream connector from the list and then click Add. A new output appears in the list.
  4. Fill in the fields as follows:
FieldValue
NameCanopsis events
Path/usr/share/centreon-broker/lua/canopsis2x-events-apiv2.lua
Filter categoryNeb
  1. To enable Centreon to connect to your Canopsis equipment, fill in the following mandatory parameters. The fields for the first entry are already present. Click on the +Add a new entry link located below the Filter category table to add another one.
TypeNameDescriptionExample of value
stringcanopsis_authkeyCanopsis API authentication keyan_authkey
stringcanopsis_hostCanopsis host addressa host
  1. Fill in any optional parameters you want (using the +Add a new entry link):
TypeNameDescriptionDefault value
stringlogfileFile in which logs are written/var/log/centreon-broker/canopsis-events-apiv2.log
numberlog_levelLogging level from 1 (errors) to 3 (debug)1
  1. Use the stream connector's optional parameters to filter or adapt the data you want Centreon to send to Canopsis.

  2. Deploy the configuration.

  3. Restart centengine on all pollers:

    systemctl restart centengine

    Canopsis should now receive data from Centreon.

Filtering or adapting the data you want to send to Canopsis

All stream connectors have a set of optional parameters , that allow you to filter the data you will send to your Canopsis equipment, to reformat the data, to define a proxy...

Each optional parameter has a default value, that is indicated in the corresponding documentation.

  • To override the default value of a parameter, click on the +Add a new entry link located below the Filter category table to add a custom parameter. For example, if you want to only send to Canopsis the events linked to a hostgroup called "Europe", enter:

    type = string
    name = accepted_hostgroup
    value = Europe
  • For the Canopsis Events stream connector, the following values always override the default values, you do not need to define them in the interface except if you want to change their values (for example to remove the downtimes in the accepted_elements variable).

TypeNameValue explanationDefault value for the stream connectorPossible values
stringaccepted_categoriesEach event is linked to a broker category (neb or bam) that we can use to filter eventsnebneb or bam
stringaccepted_elementsCentreon element handle by this connector (for more you need to add custom event format input see below), the list of elements needs to be separated by commas without spaceshost_status,service_status,acknowledgement,downtimehost_status or service_status or acknowledgement or downtime
stringcanopsis_downtime_comment_routeCanopsis route to send downtime comments/api/v4/pbehavior-comments/api/v4/pbehavior-comments
stringcanopsis_downtime_reason_nameCanopsis reason name for downtimesCentreon_downtime-
stringcanopsis_downtime_reason_routeCanopsis route to request "reason" field/api/v4/pbehavior-reasons/api/v4/pbehavior-reasons
stringcanopsis_downtime_routeCanopsis route to send downtime events/api/v4/pbehaviors/api/v4/pbehaviors
numbercanopsis_downtime_send_pbhActivate (1) the sending of downtimes if all rules to do it are checked (reason and type exists)10 ou 1
stringcanopsis_downtime_type_nameCanopsis downtime type category nameDefault maintenance-
stringcanopsis_downtime_type_routeCanopsis route to request the "type" field (except downtimes)/api/v4/pbehavior-types/api/v4/pbehavior-types
stringcanopsis_event_routeCanopsis route to send events/api/v4/event/api/v4/event
numbercanopsis_portCanopsis port443-
numbercanopsis_sort_list_hostgroupsActivate (1) the sort of hosts groups lists00 ou 1
numbercanopsis_sort_list_servicegroupsActivate (1) the sort of services groups lists00 ou 1
stringconnectorConnector type shows in Canopsis interface in Alarms > Connector Typecentreon-stream-
stringconnector_nameConnector namecentreon-stream-central-
stringconnector_name_typeConnector typepoller-
stringsending_methodSending method (only API is available at this moment)apiapi
stringsending_protocolSending protocol use (can be https or http)httpshttp ou https
numberuse_severity_as_stateActivate (1) convert the severity as state00 ou 1

Event bulking

This stream connector is not compatible with event bulking at this moment. Meaning that it is not able to send more than one event in each call to the Canopsis REST API.

Event format

This stream connector will send events with the following format.

Output example for service_status events

[
{
"action_url": "",
"component": "Host-name",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "check",
"host_id": "15",
"hostgroups": [
"Group 1",
"Group 2"
],
"long_output": "Plugin's long output",
"notes_url": "",
"output": "Plugin's output",
"resource": "Service-name",
"service_id": "47",
"servicegroups": [],
"source_type": "resource",
"state": 1,
"timestamp": 1708693347
}
]

Output example for host_status events

[
{
"action_url": "",
"component": "Host-1",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "check",
"host_id": "15",
"hostgroups": [
"Group 1",
"Group 2"
],
"long_output": "OK: Host is OK",
"notes_url": "",
"output": "OK: Host is OK",
"source_type": "component",
"state": 0,
"timestamp": 1708953238
}
]

Output example for acknowledgement events

[
{
"author": "admin",
"component": "Host-1",
"connector": "centreon-stream",
"connector_name": "Central",
"event_type": "ack",
"long_output": "Acknowledged by admin",
"output": "Acknowledged by admin",
"resource": "passif",
"source_type": "resource",
"state": 1,
"timestamp": 1709052753
}
]

Output example for downtime events

[
{
"_id": "centreon-downtime-8-1715607730",
"author": "admin",
"enabled": true,
"entity_pattern": [
[
{
"field": "name",
"cond": {
"type": "eq",
"value": "Test-Service-Demo-Canopsis/Test-Demo-Canopsis"
}
}
]
],
"name": "centreon-downtime-8-1715607730",
"reason": "XXXX",
"rrule": "",
"tstart": 1715607718,
"tstop": 1715607958,
"type": "XXXX"
}
]
  • Note: In version 22.10 of Canopsis there is also a "color" field.

Custom event format

This stream connector allows you to change the format of the event to suit your needs. It allows you to handle event types that are not handled by default such as ba_status events.

In order to use this feature you need to configure a json event format file and add a new stream connector parameter.

TypeNameValue
stringformat_file/etc/centreon-broker/canopsis-events-format.json

The event format configuration file must be readable by the centreon-broker user.

To learn more about custom event formats and templating files, read this documentation.

Curl commands: testing the stream connector

Configuration of the stream connector

If you want to test that the configuration commands are sent to Canopsis correctly, use the following curl commands.

Request pbehavior-reasons route

This command checks that the pbehavior-reasons route is accessible and returns the values for the Reason field for the downtimes. This allows you to check that the name of the Reason field for Centreon downtimes exists (the default value is Centreon_downtime).

  1. Log in to the server that you configured to send events to Canopsis (your central server, a remote server or a poller).
  2. Run the following command (replace with your own values):
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_pbehavior_reasons>'

Replace the <xxxx> inside the above command with the correct values for authentication to the Canopsis host. The default values defined in the connector are 443 for canopsis_port and /api/v4/pbehavior-reasons for canopsis_pbehavior_reasons.

  1. Check if the command returns a data structure of this form:
   "data":[
{
"_id":"XXXX",
"description":"DESCRIPTION",
"name":"NAME"
}
]

Request pbehavior-types route

This command checks that the pbehavior-types route is accessible and returns the possible IDs for the Types of downtimes. This allows you to check that the name of the Type field for Centreon downtimes exists (the default value is Default maintenance).

  1. Log in to the server that you configured to send events to Canopsis (your central server, a remote server or a poller).
  2. Run the following command:
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_pbehavior_types>'

Replace the <xxxx> inside the above command with the correct values for authentication to the Canopsis host. The default values defined in the connector are 443 for canopsis_port and /api/v4/pbehavior-types for canopsis_pbehavior_types.

  1. Check if the command returns a data structure of this form:
"data":[
{
"_id":"ec35c069-1651-4ee1-8944-3e5574e7b516",
"name":"Default active",
"description":"Default active",
"type":"active",
"priority":2,
"icon_name":"",
"color":"#2FAB63"
},
{
"_id":"470c469c-77bc-402c-910f-30a8b2584343",
"name":"Default inactive",
"description":"Default inactive",
"type":"inactive",
"priority":1,
"icon_name":"brightness_3",
"color":"#979797"
},
{
"_id":"5ea9d2d8-0f16-4e19-bcca-64b1e96e00fa",
"name":"Default maintenance",
"description":"Default maintenance",
"type":"maintenance",
"priority":3,
"icon_name":"build",
"color":"#BF360C"
},
{
"_id":"1fb65097-ddaa-4e99-9239-8263095c156c",
"name":"Default pause",
"description":"Default pause",
"type":"pause",
"priority":4,
"icon_name":"pause",
"color":"#5A6D80"
}
]

With the default values of the Canopsis connector, downtimes have the "Default maintenance" type.

Request app-info route

This command checks that the app-info route is accessible and returns information about the Canopsis host.

  1. Log in to the server that you configured to send events to Canopsis (your central server, a remote server or a poller).
  2. Run the following command:
curl -X GET -H 'accept: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port>/api/v4/app-info'

Replace all the <xxxx> inside the above command with the correct values for authentication to the Canopsis host. The default value defined in the connector for canopsis_port is 443.

  1. This command only allows access to the Canopsis version so no need to inspect all the returned content of it.

Sending events

If you want to test that events are sent to Canopsis correctly:

  1. Log in to the server that you configured to send events to Canopsis (your central server, a remote server or a poller).
  2. Run the following command:
curl -X POST -H 'content-length: 400' -H 'content-type: application/json' -H 'x-canopsis-authkey: <canopsis-auth-token>' '<https_canopsis_host_url>:<canopsis_port><canopsis_event_route>' -d '[{"hostgroups":[],"component":"Test-Canopsis","host_id":"8","event_type":"check","resource":"passif","output":"Test_passif_output","servicegroups":[],"connector":"centreon-stream","source_type":"resource","action_url":"","long_output":"Test-curl-command Passif long output","notes_url":"","connector_name":"Central","timestamp":1710843117,"service_id":"10","state":1}]'

Replace all the <xxxx> inside the above command with the correct values for authentication to the Canopsis host. The default values defined in the connector are 443 for canopsis_port and /api/v4/event for canopsis_event_route.

  1. Check that the event has been received by Canopsis. The status should appear in the Alarms > In progress page of Canopsis.

image