Skip to main content
Version: ⭐ 23.10

The BBDO protocol

The BBDO protocol has been created to be the default protocol of Centreon Broker. It is lightweight on the wire and easy to decode. It is especially designed for monitoring resources with Centreon Broker.

Introduction​

BBDO stands for Broker Binary Data Object. BBDO is designed to transfer "data packets" from one node to another. These "data packets" spend most of the time monitoring information provided by the monitoring engine (e.g. Centreon Engine or Nagios). It uses mostly raw binary values, which allows it to consume very little memory.

With Broker 22.04.0, we introduced a new version of BBDO. It is based on Google Protobuf 3. The new protocol remains compatible with the previous one, but introduces new events. For example, PbService and PbServiceStatus events are sent instead of Service and ServiceStatus events. Configured with BBDO 3, Broker still understands Service and ServiceStatus events, but by default it should send the new versions.

Types​

This section is about BBDO 2.

As a binary protocol, BBDO uses data types to serialize data. They are written in a Big Endian format and described in the following table.

TypeRepresentationSize (bytes)
integerbinary4
short integerbinary2
long integerbinary8
timebinary (timestamp)8
booleanbinary (0 is false, everything else is true)1
stringnul-terminated UTF-8 stringvariable
realnul-terminated UTF-8 string (either in fixed (2013) or scientific (2.013e+3) format)variable

Packet format​

The packet format of Centreon Broker introduces only 16 bytes of header to transmit each monitoring event (usually about 100-200 bytes each). Fields are provided in the big endian format.

FieldTypeDescription
checksumunsigned short integerCRC-16-CCITT X.25 of size, id, source and destination. The checksum can be used to recover from an incomplete data packet sent in the stream by dropping bytes one by one.
sizeunsigned short integerSize of the packet, excluding header.
idunsigned integerID of the event.
source_idunsigned integerThe id of the source instance of this event.
destination_idunsigned integerThe id of the destination instance for this event.
dataPayload data.

Here, the only difference between BBDO 3 and the previous versions is the data content. In BBDO 3, this part is a serialized Protobuf object, whereas in previous versions it is data serialized as explained in the Types section.

Packet ID​

As seen in the previous paragraph, every packet holds an ID that expresses by itself how data is encoded. This ID can be split into two 16-bit components. The 16 most significant bits are the event category and the 16 least significant bits the event type.

The event categories serialize event properties one after the other, so order is very important to not lose track when unserializing events.

Event categories​

The current available categories are described in the table below.

CategoryAPI macroValueDescription
NEBBBDO_NEB_TYPE1Classical monitoring events (hosts, services, notifications, event handlers, plugin execution, ...).
BBDOBBDO_BBDO_TYPE2Category internal to the BBDO protocol.
StorageBBDO_STORAGE_TYPE3Category related to RRD graph building.
CorrelationBBDO_CORRELATION_TYPE4Status correlation (deprecated).
DumperBBDO_DUMPER_TYPE5Dumper events (only used for tests).
BamBBDO_BAM_TYPE6Bam events.
ExtcmdBBDO_EXTCMD_TYPE7Centreon Broker external commands (deprecated).
InternalBBDO_INTERNAL_TYPE65535Reserved for internal protocol use.

NEB​

The table below lists event types available in the NEB category. They must be mixed with the BBDO_NEB_TYPE category to get a BBDO event ID.

TypeValueUses Protobuf
Acknowledgement1No
Comment2No
Custom variable3No
Custom variable status4No
Downtime5No
Event handler6No
Host check8No
Host dependency9No
Host group10No
Host group member11No
Host12No
Host parent13No
Host status14No
Instance15No
Instance status16No
Log entry17No
Module18No
Service check19No
Service dependency20No
Service group21No
Service group member22No
Service23No
Service status24No
Instance Configuration25No
Responsive Instance26No
Pb Service27Yes
Pb Adaptive Service28Yes
Pb Service Status29Yes
Pb Host30Yes
Pb Adaptive Host31Yes
Pb Host Status32Yes
Pb Severity33Yes
Pb Tag34Yes
Pb Comment35Yes
Pb Downtime36Yes
Pb Custom variable37Yes
Pb Custom variable status38Yes
Pb Host check39Yes
Pb Service check40Yes
Pb Log entry41Yes
Pb Instance Status42Yes
Pb Instance44Yes
Pb Acknowledgement45Yes
Pb Responsive Instance46Yes

Storage​

The table below lists event types available in the Storage category. They must be mixed with the BBDO_STORAGE_TYPE category to get a BBDO event ID.

TypeValueUses Protobuf
Metric1No
Rebuild2No
Remove_graph3No
Status4No
Index mapping5No
Metric mapping6No
Pb Rebuild Message7Yes
Pb Remove Graph Message8Yes
Pb Metric9Yes
Pb Status10Yes
Pb Index mapping11Yes
Pb Metric mapping12Yes

BBDO​

The table below lists event types available in the BBDO category. They must be mixed with the BBDO_BBDO_TYPE category to get a BBDO event ID.

TypeValueUses Protobuf
version response1No
ack2No
stop3No
Pb ack8Yes
Pb stop9Yes

BAM​

The table below lists event types available in the BAM category. They must be mixed with the BBDO_BAM_TYPE category to get a BBDO event ID.

TypeValueUses Protobuf
BA status1No
KPI status2No
Meta Service Status3No
BA event4No
KPI event5No
BA Duration Event6No
Dimension BA Event7No
Dimension KPI Event8No
Dimension BA BV Relation Event9No
Dimension BV Event10No
Dimension Truncate Table Signal11No
Rebuild12No
Dimension Timeperiod13No
Dimension BA Timeperiod Relation14No
Inherited Downtime17No
Pb Inherited Downtime18Yes
Pb BA status19Yes
Pb BA event20Yes
Pb KPI event21Yes
Pb Dimension BV Event22Yes
Pb Dimension BA BV Relation Event23Yes
Pb Dimension Timeperiod24Yes
Pb Dimension BA Event25Yes
Pb Dimension KPI Event26Yes
Pb KPI status27Yes
Pb BA Duration Event28Yes
Pb Dimension BA Timeperiod Relation29Yes
Pb Dimension Truncate Table Signal30Yes

Event serialization​

Most events listed in each event category have a mapping used to serialize their content. In fact, their content is directly serialized in the packet payload data, one field after the other in the order described in the mapping tables. They are encoded according to the rules described in the types paragraph.

Example​

Let's take an example and see how a host check event is sent in a packet. Its mapping is as follows:

PropertyTypeValue in example
active_checks_enabledbooleanTrue.
check_typeshort integer0 (active host check).
host_idunsigned integer42
next_checktime1365080225
command_linestring./my_plugin -H 127.0.0.1

And gives the following packet with values in hexadecimal.

+-----------------+-----------------+-----------------------------------+
| CRC16 | SIZE | ID |
+========+========+========+========+========+========+========+========+
| 0A | 23 | 00 | 28 | 00 | 01 | 00 | 09 |
+--------+--------+--------+--------+--------+--------+--------+--------+

+--------+-----------------+-----------------------------------+--------
| active_| | |
| checks_| check_type | host_id | =>
| enabled| | |
+========+========+========+========+==========================+========+
| 01 | 00 | 00 | 00 | 00 | 00 | 2A | 00 |
+--------+--------+--------+--------+--------+--------+--------+--------+

--------------------------+--------------------------------------------
=> next_check | =>
+========+========+========+========+========+========+========+========+
| 00 | 00 | 00 | 51 | 5D | 78 | A1 | 2E |
+--------+--------+--------+--------+--------+--------+--------+--------+

-----------------------------------------------------------------------
=> command_line =>
+========+========+========+========+========+========+========+========+
| 2F | 6D | 79 | 5F | 70 | 6C | 75 | 67 |
+--------+--------+--------+--------+--------+--------+--------+--------+

-----------------------------------------------------------------------
=> command_line =>
+========+========+========+========+========+========+========+========+
| 69 | 6E | 20 | 2D | 48 | 20 | 31 | 32 |
+--------+--------+--------+--------+--------+--------+--------+--------+

-----------------------------------------------------------------------+
=> command_line |
+========+========+========+========+========+========+========+========+
| 37 | 2E | 30 | 2E | 30 | 2E | 31 | 00 |
+--------+--------+--------+--------+--------+--------+--------+--------+

Connection establishment​

BBDO is a protocol that can negotiate features. When establishing a connection, a version_response packet is sent by the client. It provides its supported BBDO protocol version and extensions. The server replies to this message with another version_response packet containing its own supported protocol version and extensions. If protocol versions match, then the extension negotiation begins.

Currently, two extensions are supported: TLS and COMPRESSION. Right after the version_response packet, each peer searches in the other peer's extension list for the extensions it supports. When one is found, it is enabled (i.e., it immediately starts).

Example​

Let us call the client C and the server S. The following steps are performed sequentially.

  • C initiates a TCP connection with S and the connection is established
  • C sends a version_response packet with the following attributes
    • protocol major: 1
    • protocol minor: 0
    • protocol patch: 0
    • extensions: "TLS COMPRESSION"
  • S sends its own version_response packet in reply to C's
    • protocol major: 1
    • protocol minor: 0
    • protocol patch: 0
    • extensions: "TLS COMPRESSION"
  • C and S determine which extensions they have in common (here TLS and COMPRESSION)
  • if order is important, extensions are applied in the order provided by the server
  • TLS connection is initiated, handshake performed, etc.
  • compression connection is opened
  • now data transmitted between C and S is both encrypted and compressed!

Acknowledgement​

So called 'clever' clients/servers can acknowledge packets sent to them. This is used by Centreon Broker to ensure every packet is accounted for, and to start a retention procedure in case the other side is unresponsive.

To do so, the other side must periodically send a BBDO 'ack' packet back on the same TCP channel. This packet has the number of packets acknowledged by the client.

'Clever'/'Dumb' modes are configured on each TCP output, on a per Broker basis.

Switching versions of BBDO​

BBDO must have the same version for all servers in your architecture (central server, remote servers, pollers).

If you use BBDO v2 with this version of Centreon, you will not be able to use the Resources Status page.

If you want to switch versions of BBDO (either switch from v3 to v2 or from v2 to v3), follow this procedure:

  1. On the central server, go to Configuration > Pollers > Broker configuration.

  2. Select the server you want, and on the General tab, in Advanced options, select the version of BBDO you want from the BBDO version list. Then click Save.

  3. Do the same with all the elements listed on the **Configuration > Pollers > Broker configuration page

  4. Restart gorgoned on each server:

    systemctl restart gorgoned
  5. Deploy the configuration for all servers.

  6. Stop the following services:

    • On the central server and on remote servers:

      systemctl stop cbd centengine
    • On the pollers:

      systemctl stop centengine
  7. Start the following services:

    • On the central server and on remote servers:

      systemctl start cbd centengine
    • On the pollers:

      systemctl start centengine

You can check in the logs which version of BBDO is active for a server:

  • central broker:

    tail /var/log/centreon-broker/central-{broker,rrd,module}-master.log

  • remote broker:

    tail /var/log/centreon-broker/<remote_name>-{broker,rrd,module}-master.log
  • poller module:

    tail /var/log/centreon-broker/<poller_name>-module.log

The following line states which version is used for each server:

[2022-05-17T14:53:44.828+00:00] [bbdo] [info] BBDO: peer is using protocol version 2.0.0, we're using version 2.0.0