Discovering services automatically

Launch a manual scan

After the discovery rules are programmed, it is possible to run them from the Centreon web interface.

Go to the Configuration > Services > Scan menu.

Start to write the name of the host and the web interface automatically completes the name:

Select the discovery command to run from the list that has just appeared:

If the list is empty, it means that your host doesn't use a host template linked to a discovery rule.

Click the Scan button and wait during the discovery:

The result is displayed. Select items to add to the monitoring and click the Save button:

The items were added and it is no longer possible to select them:

It is possible that some items in the list of results cannot be selected. This indicates that they are already part of the configuration.

The services were added and can be displayed in the menu Configuration > Services > Services by host:

Discovery rules

General options

A discovery rule lets you create services dynamically and link them to a host, based on the elements discovered by the probes. The created unit services will be attached to a service template so that Centreon's functionality can be used (inheritance, overloading and more).

To create a rule, go to Configuration > Services > Rules and click the Add button:

Fill the first fields:

Here is the description of the firsts fields located inside the General tab:

Rule name: the rule's name
Command Macro: discovery command used to list available XML attributes
Command Discover: discovery command which will be executed to enumerate the elements
Service template: the service template used to dynamically create new services based on the discovery

Go to the second Inclusions / Exclusions & Macros tab. You should see available XML attributes:

Come back to the first General tab, define the Service display name and select values for the other fields:

Define the name of the service that will be created.

The service name can contain a macro corresponding to an XML stream's attribute. For example: when looking for network interfaces, the interface name will be given by the name attribute. Traffic-$name$ will be replaced by Traffic-eth0 if the interface's name is eth0. The XML attribute's name must be described between two $ characters. You can use many XML attributes to build the service name.

Here is the description of the other fields located inside the General tab:

Hosts templates: the templates used to retrieve the list of hosts for which a discovery rule should be run
Linked Instances: execute only the rule for host attached to selected instances.

Keep empty to execute rule for any instance.

Contacts: contacts that will be notified about creation or deactivation during a discovery
Contact groups: contact groups that will be notified about creation or deactivation during a discovery
Disable elements not found: lets the module deactivate services associated to elements that cannot be found anymore
Update existing services: update created service property if enable (custom macro, etc.).
Activate: activate or deactivate the rule (will be ignored by the discovery process if deactivated)

Click the Save button to save the discovery rule.

Inclusions / Exclusions & Macros

The Inclusions / Exclusions & Macros tab works as follows:

The Inclusions / Exclusions part allows elements to be included or excluded during the discovery. This inclusion/exclusion is relative to an XML attribute.

The inclusion/exclusion rules are defined using the following algorithm:

If only inclusion rules are present, the attribute's value corresponding to at least one inclusion will be considered
If only exclusion rules are present, every element will be considered, except the ones corresponding to an exclusion
If both types are present, the process checks if the element corresponds to an inclusion and then checks if it is not listed into the exclusion list

The second part, Macros, is used to define matches between an XML attribute and a service's template macro. For all created services, the macros' values will be replaced by the attributes' values.

In the image above, all macros will be created for the service because the checkbox Empty is selected. To avoid creating them, do not check the Empty checkbox. The $_SERVICEINTERFACEID macro created on the service will contain the value of $interfaceid from the value of the XML element.

Advanced options

On the last Advanced tab, you can apply a regexp on the Service display name. Click the Add a new entry button and define the pattern and expression result:

The regexp can be applied on the String field for:

@SERVICENAME@: The service name will be created
All XML attributes defined by $attribute_name$

The second part, Customize code, lets you use Perl code.

Custom display scan gives you the capability to change the display of a manual scan. By default, a manual scan displays the service name. Here is an example to add the size of the disk:

my ($value, $unit) = change_bytes(value => $total$);
$description = "<span style='color: red; font-weight: bold'>@SERVICENAME@</span> [size = <b>$value $unit</b>]";

Custom variables gives you the capability to create some custom macros. Here is an example to have a dynamic threshold according to disk size:

my $total_gb = $total$ / 1000 / 1000 / 1000;
if ($total_gb < 100) {
    $warning$ = 80;
    $critical$ = 90;
} elsif ($total_gb < 500) {
    $warning$ = 90;
    $critical$ = 95;
} else {
    $warning$ = 95;
    $critical$ = 98;
}

Now, you could use $warning$ and $critical$ macro in Macros part.

Discovery commands

A discovery commands is a command line to execute a discovery plugin.

For each discovery plugin, you need to define two commands:

The first one to get the list of available XML attributes
The second one to discover items on a host

Command to list available XML attributes

Go to the Configuration > Commands > Discovery menu and click the Add button to create the first command.

Fill in the fields:

Command Name: Name of your command
Command type: check Discovery option
Command Line: Define the command to get the list of XML attributes

All commands using a Centreon Plugin project need to set the hostname option, so add --hostname=127.0.0.1 in your command line

This is an example of the command line executed in a shell:

/usr/lib/centreon/plugins/centreon_linux_snmp.pl --mode=list-interfaces --hostname=127.0.0.1 --disco-format

And the result:

<?xml version="1.0" encoding="utf-8"?>
<data>
    <element>name</element>
    <element>total</element>
    <element>status</element>
    <element>interfaceid</element>
</data>

Save the command.

Command to get the list of items on a host

Go to the Configuration > Commands > Discovery menu and click the Add button to create the first command.

Fill in the fields:

Command Name: Name of your command
Command type: check Discovery option
Command Line: Define the command to get the list of items.

This is an example of the command line executed in a shell:

/usr/lib/centreon/plugins/centreon_linux_snmp.pl --mode=list-interfaces --hostname=192.168.220.129 --snmp-version=2 --snmp-community=public --disco-show

And the result:

<?xml version="1.0" encoding="utf-8"?>
<data>
    <label status="1" name="lo" total="10" interfaceid="1"/>
    <label status="1" name="eth0" total="1000" interfaceid="2"/>
</data>

Save the command.

Discovery plugins

A discovery plugin (also called plugin) is a script that lists a set of similar elements such as file systems or network interfaces on a given resource.

This plugin must be executable from the command line (shell) by the centreon user (or the user running the monitoring engine). It can be run locally or remotely using protocols such as SSH or NRPE.

The result must be a valid XML stream where each element must be described as an attribute of an XML node. This execution must be available using an option. The Centreon Plugins use '--mode=xxx --disco-show'.

For example:

/usr/lib/centreon/plugins/centreon_linux_snmp.pl --mode=list-interfaces --hostname=192.168.220.129 --snmp-version=2 --snmp-community=public --disco-show

<?xml version="1.0" encoding="utf-8"?>
<data>
    <label status="1" name="lo" total="10" interfaceid="1"/>
    <label status="1" name="eth0" total="1000" interfaceid="2"/>
</data>

In the previous example, the name attribute corresponds to the network interface. The status describes the IFOPERSTATUS, total describes the IFSPEED of the interface and interfaceid describes the IFINDEX.

The discovery plugin should also list (XML output) the available XML attributes using an option. The Centreon Plugins use '--mode=xxx --disco-format'.

For example:

/usr/lib/centreon/plugins/centreon_linux_snmp.pl --mode=list-interfaces --hostname=127.0.0.1 --disco-format

<?xml version="1.0" encoding="utf-8"?>
<data>
    <element>name</element>
    <element>total</element>
    <element>status</element>
    <element>interfaceid</element>
</data>

Here, four attributes are available: name, total, status and interfaceid.

Manually test a rule

You can run a discovery manually using the following options:

Directive	Type	Description
filter_rules	array	Run the selected rules
filter_hosts	array	Run all discovery rules linked to all templates of host used by selected host
filter_pollers	array	Run all discovery rules linked to all poller linked with rule
dry_run	boolean	Run discovery without configuration change (as a test)

Examples

Run all rules:

curl --request POST "http://localhost:8085/api/centreon/autodiscovery/services" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{}'

Test all rules:

curl --request POST "http://localhost:8085/api/centreon/autodiscovery/services" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "dry_run": 1
}'

Test a specific rule:

curl --request POST "http://localhost:8085/api/centreon/autodiscovery/services" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "filter_rules": ["OS-Linux-SNMP-Network-Interfaces-Discovery"],
    "dry_run": 1
}'

Test all rules linked to host templates used by a defined host:

curl --request POST "http://localhost:8085/api/centreon/autodiscovery/services" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "filter_hosts": ["centreon-server"],
    "dry_run": 1
}'

Test a specific rule on a defined host:

curl --request POST "http://localhost:8085/api/centreon/autodiscovery/services" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "filter_rules": ["OS-Linux-SNMP-Network-Interfaces-Discovery"],
    "filter_hosts": ["centreon-server"],
    "dry_run": 1
}'

Launch a manual scan​

Discovery rules​

General options​

Inclusions / Exclusions & Macros​

Advanced options​

Discovery commands​

Command to list available XML attributes​

Command to get the list of items on a host​

Discovery plugins​

Manually test a rule​

Examples​