Skip to main content

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 the for monitoring area of Centreon Broker.

Introduction​

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

Types​

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 packets format of Centreon Broker introduce 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.

Packet ID​

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

The event categories serialize events properties one after the other, so order is very important to not loose 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.
DumperBBDO_DUMPER_TYPE5Dumper events.
BamBBDO_BAM_TYPE6Bam events.
ExtcmdBBDO_EXTCMD_TYPE7Centreon Broker external commands.
InternalBBDO_INTERNAL_TYPE65535Reserved for internal protocol use.

NEB​

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

TypeValue
Acknowledgement1
Comment2
Custom variable3
Custom variable status4
Downtime5
Event handler6
Flapping status7
Host check8
Host dependency9
Host group10
Host group member11
Host12
Host parent13
Host status14
Instance15
Instance status16
Log entry17
Module18
Service check19
Service dependency20
Service group21
Service group member22
Service23
Service status24
Instance Configuration25

Storage​

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

TypeValue
metric1
rebuild2
remove_graph3
status4
index mapping5
metric mapping6

BBDO​

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

TypeValue
version_response1
ack2

BAM​

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

TypeValue
ba_status1
kpi_status2
meta_service_status3
ba_event4
kpi_event5
ba_duration_event6
dimension_ba_event7
dimension_kpi_event8
dimension_ba_bv_relation_event9
dimension_bv_event10
dimension_truncate_table_signal11
rebuild12
dimension_timeperiod13
dimension_ba_timeperiod_relation14
dimension_timeperiod_exception15
dimension_timeperiod_exclusion16
inherited_downtime17

Dumper​

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

TypeValue
Dump1
Timestamp cache2
Remove3
Reload4
Db dump5
Db dump committed6
Entries Ba7
Entries Ba type8
Entries boolean9
Entries host10
Entries kpi11
Entries organization12
Entries service13
Directory dump14
Directory dump committed15

Extcmd​

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

TypeValue
Command request1
Command result2

Event serialization​

Most events listed in each event category have a mapping used to serialize their content. Indeed 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 following rules described in the types paragraph.

Example​

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

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 which 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 starts the extensions negotiation.

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

Example​

Let's have C the client and S the server. The following steps are performed sequentially.

  • C initiates a TCP connection with S and connection gets 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 determines 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, ...
  • 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 their ways. This is used by Centreon Broker to insure every packet is accounted for, and to start retention procedure in case the other side is unresponsive.

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

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