About

The Component extension provides a generic database storage mechanism for discovery and poller modules.
The Driver behind this extension was to provide the features of ports, in a generic manner to discovery/poller modules.

It provides a status (Nagios convention), the ability to Disable (do not poll), or Ignore (do not Alert).

Reserved Fields

When this data from both the component and component_prefs tables is returned in one single consolidated array, there is the potential for someone to attempt to set an attribute (in the component_prefs) table that is used in the component table.
Because of this all fields of the component table are reserved, they cannot be used as custom attributes, if you update these the module will attempt to write them to the component table, not the component_prefs table.

Using Components

Create an instance of the component class:

$COMPONENT = new LibreNMS\Component();

Retrieving Components

Now you can retrieve an array of the available components:

$ARRAY = $COMPONENT->getComponents($DEVICE_ID, $OPTIONS);

getComponents takes 2 arguments:

DEVICE_ID or null for all devices.

OPTIONS - an array of various options.

getComponents will return an array containing components in the following format:

Editing Components

Edit the Array

Once you have a component array from getComponents the first thing to do is extract the components for only the single device you are editing. This is required because the setComponentPrefs function only saves a single device at a time.

Then simply edit this array to suit your needs.
If you need to add a new Attribute/Value pair you can:

$ARRAY[COMPONENT_ID]['New Attribute'] = "Value";

If you need to delete a previously set Attribute/Value pair you can:

unset($ARRAY[COMPONENT_ID]['New Attribute']);

If you need to edit a previously set Attribute/Value pair you can:

$ARRAY[COMPONENT_ID]['Existing Attribute'] = "New Value";

Write the components

To write component changes back to the database simply:

$COMPONENT->setComponentPrefs($DEVICE_ID, $ARRAY)

When writing the component array there are several caveats to be aware of, these are:

$ARRAY must be in the format of a single device ID - $ARRAY[$COMPONENT_ID][Attribute] = 'Value'; NOT in the multi device format returned by getComponents - $ARRAY[$DEVICE_ID][$COMPONENT_ID][Attribute] = 'Value';

API

Component details are available via the API.
Please see the API-Docs for details.

Alerting

It is intended that discovery/poller modules will detect the status of a component during the polling cycle.
Status is logged using the Nagios convention for status codes, where:
0 = Ok,
1 = Warning,
2 = Critical

If you are creating a poller module which can detect a fault condition simply set STATUS to something other than 0 and ERROR to a message that indicates the problem.

To actually raise an alert, the user will need to create an alert rule. To assist with this several Alerting Macro's have been created:

%macro.component_normal - A component that is not disabled or ignored and in a Normal state.

%macro.component_warning - A component that is not disabled or ignored and NOT in a Warning state.

%macro.component_critical - A component that is not disabled or ignored and NOT in a Critical state.

To raise alerts for components, the following rules could be created:

%macros.component_critical = "1" - To alert on all Critical components

%macros.component_critical = "1" && %component.type = "<Type of Component>" - To alert on all Critical components of a particular type.

If there is a particular component you would like excluded from alerting, simply set the ignore field to 1.

The data that is written to each alert when it is raised is in the following format:

COMPONENT_TYPE - LABEL - ERROR

Example Code

To see an example of how the component module can used, please see the following modules: