Skip to main content

Setting up the agent's environment

Step 1: Configure Centreon​

This step is performed via the central server's interface. (It is also possible to perform these steps using the Centreon Web API.)

Install the Monitoring Connector you need (OnPrem version)​

On your central server, install the monitoring connector which will provide the templates and commands you need to configure the hosts and services monitored in Centreon. In the case of a Cloud platform, these connectors are already installed.

  1. On your central server, go to Configuration > Connectors > Monitoring Connectors.
  2. Install the Linux Centreon Monitoring Agent monitoring connector.
  1. If you want to monitor a CMA-supported application, install the corresponding connector on your central server.

Update the Centreon Monitoring Agent connector (onPrem version)​

  1. Go to Configuration > Commands > Connectors.

  2. Update the Centreon Monitoring Agent connector in the following way: in the Used by command field, type Centreon-Monitoring-Agent and then click Select all.

Create an authentication token​

This step only applies to OnPrem platforms. For Centreon Cloud, a default token is provided on the Administration > Authentication token page.

  1. Go to Administration > Authentication tokens.

  2. Create a token with the Centreon Monitoring Agent type.

    • You can select an expiration time. By default, tokens do not expire.
    • Keep the token generated for the agent configuration. If necessary, you can copy it to the clipboard at any time from the list of tokens.
    • You can use just one token for all your pollers and agents, or manage several for more precise control.

CMA authentication token behavior: deactivation/expiration/revocation​

  • The monitoring engine checks the presence and validity of the token, and disconnects if the token is missing (because it has been disabled or revoked) or has expired. The message Token expired appears in the poller and agent logs.

  • When you disable or revoke a token, deploy the configuration for this action to take effect.

  • Expiration takes effect immediately, without requiring any user action.

Create the host and services​

On the central server, create the host and apply the OS-Linux-Centreon-Monitoring-Agent-custom host template to it. The template includes the Enable passive checks option, which is set to On.

Depending on the desired connection direction, the host's “Address” field will have no impact (connection initiated by the agent) or will be retrieved when the host is selected in the agent configuration (connection initiated by the poller).

Create the services associated with the host template.

Configure poller/agent communication​

  1. Go to the Configuration > Pollers > Agent configurations page, then click Add.
  2. In the window that opens, select the Centreon Monitoring Agent agent type. Additional fields will appear.
  3. Select the connection direction (default: the agent connects to the poller).
  4. Select encryption mode
  1. In the Settings section, select the poller(s) that will receive data from the agent.
  2. In the OTLP Receiver section, enter the paths to the certificate files. See dedicated page to determine which files are required, depending on your configuration and the connection direction you want.

    If you are configuring multiple pollers at the same time, make sure that all certificate files have the same name.

  3. Click Save.
  4. Deploy the configuration by restarting the collection engine.

This configuration is deployed on the poller in the /etc/centreon-engine/otl_server.json file. Please note that this file should not be edited manually as it is overwritten each time the configuration is deployed.

Step 2: Prepare the poller​

Cloud: This step is not necessary if you want to use CMA with the Central poller.

This step is performed on the poller.

Configure the firewall​

Run the following commands:

firewall-cmd --zone=public --add-port=4317/tcp --permanent
firewall-cmd --reload

Configure encryption settings​

See the dedicated section to determine which files are required, depending on your configuration and the connection direction you need.

Add CMA commands to your custom whitelists​

If you are using whitelists on the poller (Cloud pollers have whitelists set by default), these must allow CMA commands. On the poller, in your custom whitelist file (e.g., /etc/centreon-engine-whitelist/my-whitelist.yml), include the following lines in the cma-whitelist block:

whitelist:
  regex:
    - \/usr\/lib(64)?\/nagios\/plugins\/.*
    - \/usr\/lib(64)?\/nagios\/plugins\/.check_.*
    
cma-whitelist:
  default:
    regex:
      - \/usr\/lib(?:64)?\/nagios\/plugins\/.*
      - \/usr\/lib(?:64)?\/centreon\/plugins\/.*
      - \/usr\/lib(?:64)?\/centreon\/plugins\/check_centreon_bam.*
      - \"C:\/Program Files\/Centreon\/Plugins\/centreon_plugins.exe\"\s+.+
      - ^\{\s*"check":".*\}$
      - \/usr\/bin\/echo\s+Host\s+alive
      - cmd\.exe\s+\/C\s+echo\s+.*

If necessary, you can specify whitelists by host. The syntax will be:

whitelist:
  regex:
    - \/usr\/lib(64)?\/nagios\/plugins\/.*
    - \/usr\/lib(64)?\/nagios\/plugins\/.check_.*
    
cma-whitelist:
  default:
    regex:
      - \/usr\/lib(?:64)?\/nagios\/plugins\/.*
      - \/usr\/lib(?:64)?\/centreon\/plugins\/.*
      - \/usr\/lib(?:64)?\/centreon\/plugins\/check_centreon_bam.*
      - \"C:\/Program Files\/Centreon\/Plugins\/centreon_plugins.exe\"\s+.+
      - ^\{\s*"check":".*\}$
      - \/usr\/bin\/echo\s+Host\s+alive
      - cmd\.exe\s+\/C\s+echo\s+.*
  hosts:
    - hostname:Host_1
    regex:
      - ...
      
    - hostname:Host_2
    regex:
      - ...

Make sure the correct access rigts are defined on all whitelist files:

chown root:centreon-engine /etc/centreon-engine-whitelist/my-whitelist.yml
chmod 0640 /etc/centreon-engine-whitelist/my-whitelist.yml
chown root:centreon-engine /etc/centreon-engine-whitelist
chmod 750 /etc/centreon-engine-whitelist

The behavior is as follows:

  • If the whitelist block is filled in and the cma-whitelist block is absent, the monitoring engine will apply its whitelist (it will only allow the specified commands) and CMA will not apply a whitelist (all commands will be allowed).
  • If both the whitelist and cma-whitelist blocks are filled in, the monitoring engine will apply the whitelist block and CMA will apply the cma-whitelist block (they will only allow the specified commands).
  • If the whitelist block is absent and the cma-whitelist block is filled in, the monitoring engine will not apply a whitelist (all commands will be allowed) and CMA will apply the cma-whitelist block (it will only allow specified commands).
  • If no block is filled in, no whitelist will be applied: all commands will be allowed.

Step 3: Prepare the host​

This step is performed on the monitored host.

Download and install the agent​

Install the Centreon repository and the agent​

Install the Centreon repository and agent using the following commands:

dnf install -y dnf-plugins-core
dnf config-manager --add-repo https://packages.centreon.com/rpm-standard/24.10/el8/centreon-25.10.repo
dnf install  centreon-monitoring-agent

Configure centreon-monitoring-agent​

Replace the contents of the /etc/centreon-monitoring-agent/centagent.json file with the following parameters :

Cloud: when using the Central poller, the value of endpoint will be engine-centreon-${CLOUD_ORG}.euwest1.centreon.cloud:443. ${CLOUD_ORG} is present in the URL of your Cloud platform: https://${CLOUD_ORG}.euwest1.centreon.cloud/

{
  "log_level":"info",
  "endpoint":"<POLLER IP/DNS>:4317",
  "host":"host_1",
  "log_type":"file",
  "log_file":"/var/log/centreon-monitoring-agent/centagent.log" ,
  "encryption":<full/insecure>,
  "ca":"/tmp/ca_1234.crt",
  "ca_common_name":"",
  "token":"<TOKEN>"
}

Important: in the Host field, enter the name of the host to be monitored as you entered it in the Centreon interface. If absent, the agent will use the machine's hostname. This name will be the matching key used to send data back to the Centreon host.

Configure encryption parameters​

See dedicated section to identify which files are required, depending on your configuration and direction.

When migrating from a previous version of CMA, the configured data is retained. Therefore, any encryption that is enabled will be considered “encryption:insecure.” You can change this value as needed and restart the agent.

Configure the logs​

You can configure two kinds of log output:

  • file: the CMA logs into a file, the path is configured in the log_file option.
  • stdout: standard output is used.

If you choose to log into a file, log rotation can be customized using the log_max_file_size and log_max_files options.

Allowed log levels are:

  • off: no logs
  • critical: critical errors
  • error: all errors
  • info: additional information
  • debug: more information about connections
  • trace: the most verbose trace level showing messages sent and received to the poller

Restart the agent​

systemctl restart centagent

You can check that the agent is running using the following command:

systemctl status centagent

Deploy the Centreon agent plugins on the host (Linux)​

If you are using Centreon connectors and non-native controls on Linux:

  1. Enable our plugins repository and install the plugins:

This repository will provide you our packaged plugins as well as the dependencies that are not available in the standard distribution repositories.


dnf -y install dnf-plugins-core epel-release
dnf config-manager --set-enabled powertools

cat >/etc/yum.repos.d/centreon-plugins.repo <<'EOF'
[centreon-plugins-stable]
name=Centreon plugins repository.
baseurl=https://packages.centreon.com/rpm-plugins/el8/stable/$basearch/
enabled=1
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1

[centreon-plugins-stable-noarch]
name=Centreon plugins repository.
baseurl=https://packages.centreon.com/rpm-plugins/el8/stable/noarch/
enabled=1
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1

[centreon-plugins-testing]
name=Centreon plugins repository. (UNSUPPORTED)
baseurl=https://packages.centreon.com/rpm-plugins/el8/testing/$basearch/
enabled=0
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1

[centreon-plugins-testing-noarch]
name=Centreon plugins repository. (UNSUPPORTED)
baseurl=https://packages.centreon.com/rpm-plugins/el8/testing/noarch/
enabled=0
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1

[centreon-plugins-unstable]
name=Centreon plugins repository. (UNSUPPORTED)
baseurl=https://packages.centreon.com/rpm-plugins/el8/unstable/$basearch/
enabled=0
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1

[centreon-plugins-unstable-noarch]
name=Centreon plugins repository. (UNSUPPORTED)
baseurl=https://packages.centreon.com/rpm-plugins/el8/unstable/noarch/
enabled=0
gpgcheck=1
gpgkey=https://yum-gpg.centreon.com/RPM-GPG-KEY-CES
module_hotfixes=1
EOF
  1. Install the plugin:
dnf install -y centreon-plugin-Operatingsystems-Linux-Local.noarch

Updating an existing configuration​

Modify the /etc/centreon-monitoring-agent/centagent.json file and restart the agent.

Configuring multiple agent instances on the same host​

General principle​

You can configure multiple CMA services on a host, for example to communicate with different Centreon pollers/platforms (test/production) monitoring the same host.

An instance consists of:

  • a service
  • its configuration

The name of the instance must be unique on the same host.

Each instance has its own configuration and executes it independently of other instances.

Configuration​

The configuration for each instance is stored in a dedicated JSON file on the host. The file name must be unique.

/etc/centreon-monitoring-agent/centagent1.json

Deploying a named instance​

Running multiple instances configured with the same <endpoint; host> pair will cause duplicate metrics in the database for that host. It is mandatory to change the endpoint and/or host values when deploying a new instance.

  1. Make a copy of the configuration file created during the initial deployment of CMA.
cp  /etc/centreon-monitoring-agent/centagent.json /etc/centreon-monitoring-agent/centagent1.json
  1. Give the file the appropriate permissions:
chmod 0644 /etc/centreon-monitoring-agent/centagent1.json
chown centreon-monitoring-agent:centreon-monitoring-agent /etc/centreon-monitoring-agent/centagent1.json

  1. Make sure you modify the value of 'endpoint' and, if necessary, the rest of the configuration for the new instance in the created file (for example, to change the log level or the certificate path).

  2. Make a copy of the service created during the first CMA deployment.

cp /lib/systemd/system/centagent.service /lib/systemd/system/centagent1.service
  1. In this new file, modify the path in ExecStart to point to the new json file.
...
[Service]
ExecStart=/usr/bin/centagent /etc/centreon-monitoring-agent/centagent1.json
ExecReload=/bin/kill -HUP $MAINPID
...
  1. Give the service the appropriate rights:
chmod 0644 /lib/systemd/system/centagent1.service
chown centreon-monitoring-agent:centreon-monitoring-agent /lib/systemd/system/centagent1.service
  1. Register the new service:
systemctl daemon-reload
systemctl unmask centagent1
systemctl preset centagent1
systemctl enable centagent1
systemctl restart centagent1

Editing a named instance​

  1. Make the desired changes in the JSON file for the instance.
  2. Restart the corresponding service.
systemctl restart centagent1

Uninstalling a named instance​

See Uninstalling the agent.

Updating an existing configuration​

  1. Edit the following file: /etc/centreon-monitoring-agent/centagent.json.
  2. Restart the agent.
systemctl restart centagent

Uninstalling the agent​

  • To uninstall an instance, run the following commands, adapting the name of the service and configuration file:
systemctl stop centagent1
rm /lib/systemd/system/centagent1.service
rm /etc/centreon-monitoring-agent/centagent1.json
systemctl daemon-reload
  • To completely uninstall CMA (all instances and user groups), run the following commands (for each instance, if multiple instances are deployed):
systemctl stop centagent centagent
rm /lib/systemd/system/centagent.service /lib/systemd/system/centagent.service
rm /etc/centreon-monitoring-agent/centagent.json /etc/centreon-monitoring-agent/centagent.json

Then run the following commands:

systemctl daemon-reload
deluser centreon-monitoring-agent
delgroup centreon-monitoring-agent

Step 4: Test if the agent works​

See dedicated section.