Skip to content

enh(doc): enhancement to BSM api-v2 #1200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
psamecentreon wants to merge 8 commits into from
Closed

enh(doc): enhancement to BSM api-v2 #1200

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
77b8480
enh(doc): enhancement to BSM api-v2
psamecentreon Dec 16, 2021
5c063ff
Update sc-bsm.md
psamecentreon Dec 16, 2021
d286e7c
First review of documentation
psamecentreon Dec 29, 2021
fcc25b6
Update r2nd review of docs
psamecentreon Dec 30, 2021
d71a399
Update sc-bsm.md
psamecentreon Dec 30, 2021
1721367
Update sc-bsm.md
psamecentreon Dec 30, 2021
de370b7
Update sc-bsm.md
psamecentreon Jan 27, 2022
47c7029
Review translate FR version
psamecentreon Feb 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 207 additions & 76 deletions en/integrations/event-management/sc-bsm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,124 +3,255 @@ id: sc-hp-bsm
title: BSM
---

## BSM + Centreon Integration Benefits
## Before starting

BSM Stream Connector sends events related data from **Centreon** to **Micro Focus BSM** (Business Service Management).
- You can send events from a central server, a remote server or a poller.
- By default, this stream connector sends **host_status** and **service_status** events. The event format is shown **[there](#event-format)**.
- Aformentioned events are fired each time a host or a service is checked. Various parameters let you filter out events.

## How it Works
## Installation

* Every time a service or a host's state is checked, the event passes through Centreon Broker, which uses the functions defined in the Stream Connector to send state changes to BSM.
### Dependencies

## Requirements
<!--DOCUSAURUS_CODE_TABS-->
<!--CentOS 7/Redhat 7-->

* Integration with BSM requires the ability to access a **webservice on you BSM platform**. Please contact your BSM expert for this part.
* A Centreon account is required with either **admin privileges** or **Export configuration** and **Broker configuration** menu access in the WUI.
* A **`root` access in command-line interface on Centreon central server** is required as well.
Install **Epel** repository.

## Support
```shell
yum -y install epel-release
```

Install dependencies.

```shell
yum install luarocks make gcc lua-curl lua-devel
```

<!-- CentOS 8 -->

Install dnf plugins package.

```shell
dnf -y install dnf-plugins-core
```

Install **Powertools** repository.

```shell
dnf config-manager --set-enabled powertools
```

Install **Epel** repository.

```shell
dnf -y install epel-release
```

If you need help with this integration, depending on how you are using Centreon, you can:
Install dependencies.

* **Commercial Edition customers**: please contact the [Centreon Support team](mailto:support@centreon.com).
* **Open Source Edition users** or **Centreon IT-100 users** (free versions): please reach our [Community Slack](https://centreon.github.io) where our users and staff will try to help you.
```shell
dnf install make gcc libcurl-devel lua-devel luarocks
```

## Integration Walkthrough
<!-- RedHat 8 -->

### Installation
Install dnf plugins package.

Login as `root` on the Centreon central server using your favorite SSH client.
```shell
dnf -y install dnf-plugins-core
```

In case your Centreon central server must use a proxy server to reach the Internet, you will have to export the `https_proxy` environment variable and configure `yum` to be able to install everything.
Install **Epel** repository.

```bash
export https_proxy=http://my.proxy.server:3128
echo "proxy=http://my.proxy.server:3128" >> /etc/yum.conf
```shell
dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
```

Now that your Centreon central server is able to reach the Internet, you can run:
Enable **Codeready** repository.

```bash
yum install -y lua-curl epel-release
yum install -y luarocks
```shell
subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
```

Install dependencies.

```shell
dnf install make gcc libcurl-devel lua-devel luarocks
```

<!--END_DOCUSAURUS_CODE_TABS-->

### Lua modules

<!--DOCUSAURUS_CODE_TABS-->
<!--CentOS/Redhat 7-->

Install **luaxml**.

```shell
luarocks install luaxml
```

This package is necessary for the script to run. Now let's download the script:
Install Centreon lua modules.

```shell
luarocks install centreon-stream-connectors-lib
```

<!-- CentOS/Redhat 8-->

```bash
wget -O /usr/share/centreon-broker/lua/bsm_connector.lua https://raw.githubusercontent.com/centreon/centreon-stream-connector-scripts/master/centreon-certified/bsm/bsm_connector-apiv1.lua
chmod 644 /usr/share/centreon-broker/lua/bsm_connector.lua
Install **lua-curl**.

```shell
luarocks install Lua-cURL
```

The BSM StreamConnnector is now installed on your Centreon central server!
Install **luaxml**.

### Broker configuration
```shell
luarocks install luaxml
```
Comment on lines +112 to +114

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this dependency is made using C, does it works on el7 and el8 ? (should be, because i've tested on el8 and it worked and obviously the stream connector has been made using el7 when first created). It's just a comment to about testing things and the issues we can have we dependencies

@psamecentreon psamecentreon Dec 30, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This install is OK.
I'll have to continue my test with the stream connector code


Install Centreon lua modules.

1. Login to the Centreon WUI using an administrator account.
2. Navigate to the **Configuration** > **Pollers** menu and select **Broker configuration**.
3. Click on the **central-broker-master** broker configuration object and navigate to the **Output** tab.
4. Add a new **Generic - Stream connector** output.
5. Name it as you want (eg. **BSM**) and set the right path for the LUA script: `/usr/share/centreon-broker/lua/bsm_connector.lua`.
6. The parameter `http_server_url` has to be set according to your BSM platforms characteristics:
```shell
luarocks install centreon-stream-connectors-lib
```

| Name | Type | Value |
|-------------------|--------|-------------------------------------------------------------------|
| `http_server_url` | String | `https://<my.bsm.server>:30005/bsmc/rest/events/<my-webservice>/` |
<!--END_DOCUSAURUS_CODE_TABS-->

7. Save your configuration, then navigate to the **Configuration** > **Pollers** menu and select **Pollers**.
8. Select the **Central** poller and click on **Export configuration**.
9. Keep **Generate Configuration Files** and **Run monitoring engine debug (-v)** checked and select **Move Export Files** and then click on the **Export** button.
10. Restart the `cbd` service:
### Download BSM stream connector

```bash
systemctl restart cbd
```shell
wget -O /usr/share/centreon-broker/lua/bsm_connector-apiv2.lua https://raw.githubusercontent.com/centreon/centreon-stream-connector-scripts/master/centreon-certified/bsm/bsm_connector-apiv2.lua
Comment thread
psamecentreon marked this conversation as resolved.
Outdated
chmod 644 /usr/share/centreon-broker/lua/bsm_connector-apiv2.lua
```

Now your central server has loaded the BSM Stream Connector and has started to send data!
## Configuration

To configure your stream connector, you must **head over** the **Configuration --> Poller --> Broker configuration** menu. **Select** the **central-broker-master** configuration (or the appropriate broker configuration if it is a poller or a remote server that will send events) and **click** the **Output tab** when the broker form is displayed.

**Add** a new **generic - stream connector** output and **set** the following fields as follow:

| Field | Value |
| --------------- | ------------------------------------------------------ |
| Name | BSM |
| Path | /usr/share/centreon-broker/lua/bsm_connector-apiv2.lua |
Comment thread
psamecentreon marked this conversation as resolved.
Outdated

### Add BSM optional parameters

Some stream connectors have a set of optional parameters dedicated to the Software that they are associated with. To add them you must **click** on the **+Add a new entry** button located **below** the **filter category** input.

| Type | Name | Value (explanation) | defaultvalue |
|--------|---------------------|------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------------------- |
| String | `http_server_url` | URL de votre plateforme BSM | `https://<my.bsm.server>:30005/bsmc/rest/events/<my-webservice>/` |
| String | `http_proxy_string` | Paramétrage du proxy permettant de sortir vers Internet en HTTP/HTTPS | `http://your.proxy.server:3128` |
| String | `source_ci` | Nom permettant d'identifier l'émetteur | `Centreon` |
| Number | `log_level` | Niveau de verbosité des logs 0: errors seulement, 1: +warnings, 2: +verbose, 3: +debug | 2 |
| String | `log_path` | Chemin complet du fichier de log | `/var/log/centreon-broker/my-custom-logfile.log` |
| Number | `max_buffer_size` | Nombre maximum d'événements à stocker en mémoire tampon en attendant de les transmettre en un seul envoi | 1 |
| Number | `max_buffer_age` | Temps d'attente maximum avant d'envoyer les événements en mémoire tampon si `max_buffer_size` n'est pas encore atteint | 5 |

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you need to split this part into two chapters. One about mandatory parameters. and one about optional parameters. Those two chapters must only talk about BSM dedicated parameters. Others such as max_buffer_xxx logs and so on must be explained in another chapter

please, use only english


> To make sure that everything goes fine, you should have a look at `central-broker-master.log` and `stream-connector-bsm.log`, both located in `/var/log/centreon-broker`.
### Proxy configuration

#### Advanced configuration
When using a proxy to connect to the BSM endpoint, you can use additional parameters to configure it:

**Parameters table**
| Type | Name | Value explanation |
| -------- | ------------------ | ----------------------------------------------------- |
| string | proxy_address | Proxy address |
| number | proxy_port | Proxy port (mandatory when proxy_address is set) |
| string | proxy_username | Proxy username the file in which logs are written |
| password | proxy_password | Proxy password (mandatory when proxy_username is set) |

| Name | Type | Value example | Explanation |
|---------------------|--------|-------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `http_server_url` | String | `https://<my.bsm.server>:30005/bsmc/rest/events/<my-webservice>/` | URL of your BSM platform |
| `http_proxy_string` | String | `http://your.proxy.server:3128` | Proxy string needed to reach the Internet in HTTP/HTTPS |
| `source_ci` | String | `Centreon` (default value) | Name used to identify the transmitter |
| `log_level` | Number | 2 (default value) | Verbosity level for logs 0: errors only 1: +warnings, 2: +verbose, 3: +debug |
| `log_path` | String | `/var/log/centreon-broker/my-custom-logfile.log` | Log file full path and name |
| `max_buffer_size` | Number | 1 (default value) | Number of events to enqueue in buffer before sending |
| `max_buffer_age` | Number | 5 (default value) | Maximum number of seconds before sending an event when `max_buffer_size` hasn't been reached |
### Standard parameters

**Remarks**
All stream connectors can use a set of optional parameters that are made available through Centreon stream connectors lua modules.

* The default value of 2 for `log_level` is fine for initial troubleshooting, but can generate a huge amount of logs if you monitor a lot of hosts. In order to get less log messages, you should tune this parameter.
* The default value of 1 for `max_buffer_size` works fine and ensures the best response times. You might want to tune it (*ie.* increase it) if you have an important amount of data to send to BSM.
All those parameters are documented **[here](https://github.com/centreon/centreon-stream-connector-scripts/blob/master/modules/docs/sc_param.md#default-parameters)**.

---------------
Some of them are overridden by this stream connector.

## How to Uninstall
| Type | Name | Default value for the stream connector |
| ------ | ------------------- | -------------------------------------- |
| string | accepted_categories | neb |
| string | accepted_elements | host_status,service_status |

1. Login to the Centreon WUI using an administrator account.
2. Navigate to the **Configuration** > **Pollers** menu and select **Broker configuration**.
3. Click on the **central-broker-master** broker configuration object and navigate to the **Output** tab.
4. Delete the **Generic - Stream connector** output by clicking on the red circled cross at the end of the line.
5. Save your configuration, then navigate to the **Configuration** > **Pollers** menu and select **Pollers**.
6. Select the **Central** poller and click on **Export configuration**.
7. Keep **Generate Configuration Files** and **Run monitoring engine debug (-v)** checked and select **Move Export Files** and then click on the **Export** button.
8. Restart the `cbd` service:
## Event bulking

```bash
systemctl restart cbd
This stream connector is not compatible with event bulking. Meaning that the option `max_buffer_size` can't be higher than 1

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

according to the code, it is


## Event format

This stream connector will send event with the following format.

### status event

```xml
{
"<event_data>"
"<hostname>" hostname "</hostname>"
"<svc_desc>" service_description "</svc_desc>"
"<state>" self.sc_event.event.state "</state>"
"<last_update>" self.sc_event.event.last_update "</last_update>"
"<output>" string.match(e.output, "^(.*)\n") "</output>"
xml_service_severity
"<url>" xml_url "</url>"
"<source_host_id>" ifnil_or_empty(self.sc_event.event.host_id, '0') "</source_host_id>"
"<source_svc_id>" ifnil_or_empty(self.sc_event.event.service_id, '0') "</source_svc_id>"
"<scheduled_downtime_depth>" ifnil_or_empty(self.sc_event.event.scheduled_downtime_depth, '0') "</scheduled_downtime_depth>"
"</event_data>"
}
Comment on lines +190 to +217

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a copy paste from the code, this is not the xml that is sent 😈

this stream connector handles services and hosts, you need to provide the example for both kind of events

```

The Stream Connector is not loaded anymore!
### Custom event format

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you'll need to test this one


This stream connector allows you to change the format of the event to suit your needs. Only the **event** part of the json is customisable. It also allows you to handle events type 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.

| Type | Name | Value |
| ------ | ----------- | ------------------------------------------------------- |
| string | format_file | /etc/centreon-broker/lua-conf/bsm-events-format.json |

9. Optionally, you can even delete the script file:
> The event format configuration file must be readable by the centreon-broker user

```bash
rm -f /usr/share/centreon-broker/lua/bsm_connector.lua
To learn more about custom event format and templating file, head over the following **[documentation](https://github.com/centreon/centreon-stream-connector-scripts/blob/master/modules/docs/templating.md#templating-documentation)**.

## Curl commands

Here is the list of all the curl commands that are used by the stream connector.

### Send events

You can trigger a signal with the following command:

```shell
curl -X POST -H 'content-type: application/xml' 'https://centreon.bsm.server:30005/bsmc/rest/events/myCentreon/' -d '{"<event_data>" "<hostname>" 'srv-vp-central01' "</hostname>" \
"<svc_desc>" 'Swap' "</svc_desc>" \
"<state>" 'Critical' "</state>" \
"<last_update>" '12/16/2021 1:14 PM' "</last_update>" \
"<output>" 'Critical: Swap Total: 1.60 GB Used: 1.51 GB (94.44%) Free: 1.25 MB (5.56%)\n' "</output>" \
'0' \
"<url>" 'no action url for this host' "</url>" \
"<source_host_id>" '3450' "</source_host_id>" \
"<source_svc_id>" '1245' "</source_svc_id>" \
"<scheduled_downtime_depth>" '0' "</scheduled_downtime_depth>" \
"</event_data>"}'
```

You can then close this signal with the following command:

```shell
curl -X POST -H 'content-type: application/xml' 'https://centreon.bsm.server:30005/bsmc/rest/events/myCentreon/' -d '{"<event_data>" "<hostname>" 'srv-vp-central01' "</hostname>" \
"<svc_desc>" 'Swap' "</svc_desc>" \
"<state>" 'OK' "</state>" \
"<last_update>" '12/16/2021 1:45 PM' "</last_update>" \
"<output>" 'OK: Swap Total: 1.60 GB Used: 91.25 MB (5.56%) Free: 1.51 GB (94.44%)\n' "</output>" \
'0' \
"<url>" 'no action url for this host' "</url>" \
"<source_host_id>" '3450' "</source_host_id>" \
"<source_svc_id>" '1245' "</source_svc_id>" \
"<scheduled_downtime_depth>" '0' "</scheduled_downtime_depth>" \
"</event_data>"}'
```
Comment on lines +225 to +261

@tanguyvda tanguyvda Dec 17, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is too much things from another documentation to feel like it is the curl that is send. This is the hardest part when refactoring a stream connector. You have to guess the curl command from the code.