Skip to main content

Advanced container configuration

This page covers optional configuration for a poller deployed in a container, beyond the default centengine and gorgone services.

Allow the poller to send email notifications​

This section applies if you want your poller to be able to send notifications.

A poller in a container has two different ways to send email notifications, so you can use whichever fits your infrastructure:

Option 1: Native SMTP command​

This is the most common way of sending notifications.

The native SMTP command needs an SMTP relay to send emails. Configure it with environment variables on the centengine service in the docker-compose.

VariableEffect
SMTP_HOSTAddress of the SMTP relay. Required for the native SMTP command: notifications are silently not sent while this is empty.
SMTP_PORTPort of the SMTP relay (default: 25).
SMTP_FROMFrom: address used in outgoing notification emails.
SMTP_TLSSet to on to use TLS when connecting to the relay (default: off).

If you use the native SMTP command, the docker-compose.yaml generated by the install script does not map these variables by default. Add them directly to the centengine service's environment: block, or, to keep them out of the .env file the install script regenerates on every run, put them in a separate file and reference it as an extra env_file:

Add the last 3 lines to your docker-compose file.

services:
  centengine:
    # ...
    env_file:
      - .env
      - .env.smtp

Then store your environment variables in a .env.smtp file located in the same directory as the docker-compose file.

# .env.smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=25
SMTP_FROM=centreon-engine@example.com
SMTP_TLS=off

Restart the centengine service (docker compose up -d) after changing these variables.

mailutils and msmtp are pre-installed in the image. At startup, centengine writes an msmtp configuration from the SMTP_* variables above, so /usr/bin/mail sends through your relay with no further setup.

Option 2: centreon-plugin-notification-email connector​

The connector's SMTP relay settings are plain command-line options, so you can set them directly in the command.

The connector is pre-installed under $CENTREONPLUGINS$ (usually /usr/lib/centreon/plugins/), as centreon_notification_email.pl. Its --smtp-address, --smtp-port and --from-address options take your relay directly, no environment variable needed.

The connector picks between its host and service notification templates based on whether --service-description is set, so the same command_line can be used as both the host and the service notification command. Replace the SMTP, Centreon URL, and token placeholders below with your own, then define it on the Configuration > Commands page:

$CENTREONPLUGINS$centreon_notification_email.pl --plugin=notification::email::plugin --mode=alert --to-address='$CONTACTEMAIL$' --host-address='$HOSTADDRESS$' --host-name='$HOSTNAME$' --host-alias='$HOSTALIAS$' --host-state='$HOSTSTATE$' --host-output='$HOSTOUTPUT$' --host-attempts='$HOSTATTEMPT$' --max-host-attempts='$MAXHOSTATTEMPTS$' --host-duration='$HOSTDURATION$' --date='$SHORTDATETIME$' --type='$NOTIFICATIONTYPE$' --service-description='$SERVICEDESC$' --service-displayname='$SERVICEDISPLAYNAME$' --service-state='$SERVICESTATE$' --service-output='$SERVICEOUTPUT$' --service-longoutput='$LONGSERVICEOUTPUT$' --service-attempts='$SERVICEATTEMPT$' --max-service-attempts='$MAXSERVICEATTEMPTS$' --service-duration='$SERVICEDURATION$' --host-id='$HOSTID$' --service-id='$SERVICEID$' --notif-author='$NOTIFICATIONAUTHOR$' --notif-comment='$NOTIFICATIONCOMMENT$' --centreon-url='https://central.example.com' --smtp-address='smtp.example.com' --smtp-port='25' --from-address='centreon-engine@example.com' --centreon-user='admin' --centreon-token='your-autologin-key' --smtp-nossl
  • --centreon-url, --centreon-user and --centreon-token (a Centreon autologin key, Administration > Accounts > your user > Security) make the email link back to the resource and embed its performance graph. Omit all three if you don't need that - the email is still sent.
  • --insecure skips TLS certificate verification when fetching that graph, useful when --centreon-url uses a self-signed certificate.
  • Add --smtp-user/--smtp-password if your relay requires authentication, and drop --smtp-nossl to use TLS.

Storing --centreon-token in a command definition puts it in plain text in Centreon Engine's configuration. Use a token scoped to a dedicated, low-privilege account rather than an administrator's.

These options can also use the $SMTPADDRESS$, $SMTPPORT$ and $SMTPFROMADDRESS$ poller resource macros. In a container, these macros are overwritten at each container start with the values of the SMTP_HOST, SMTP_PORT and SMTP_FROM variables (see Option 1): set these variables rather than defining the macros in the Centreon interface.

Allow the poller to use custom plugins for monitoring​

This section only applies if you want to use your own custom plugins for monitoring. No action is needed to use the official Centreon monitoring connectors.

The centengine container can install custom check scripts and extra APT dependencies without rebuilding the image.

In the generated docker-compose.yaml, add the following volumes to the centengine service :

    volumes:
      # Custom plugin scripts (must be executable)
      - ./custom-plugins:/usr/lib/nagios/plugins/custom:ro
      # Extra APT packages, installed at startup
      - ./custom-deps.json:/etc/centreon-engine/custom-deps.json:ro

  • Create a custom-plugins directory and store your custom plugin scripts there. The container will copy them to /usr/lib/nagios/plugins/custom.

  • If your plugin needs system dependencies, you must declare them in a custom-deps.json file. For example:

    {
      "apt": ["snmp", "jq"]
    }

    This file is read when the container starts, and watched for changes afterward: editing it on the host triggers an automatic install of the listed packages, with no need to restart the container. Package installation runs in the background, so centengine is not blocked while it happens.

Baking dependencies into a custom image​

If you have a large number of dependencies, you can build a custom image on top of the official one instead of adding the dependencies one by one to the custom-deps.json file. Your custom image will be deployed using the docker-compose.

FROM ghcr.io/centreon/centreon-engine:26.10

RUN sudo apt-get update && sudo apt-get install -y --no-install-recommends \
      snmp \
      jq \
    && sudo apt-get clean

Build it, then reference it as ENGINE_TAG (or override the image: value directly) in your docker-compose.yaml. The main advantage of this approach is startup time: when a poller needs many dependencies, installing them once at build time is faster than installing them every time the container starts via custom-deps.json.

Allow the poller to monitor VMware resources​

Follow this procedure before you deploy a poller in a container using the --with-vmware option.

Monitoring VMware infrastructure requires the proprietary VMware Perl SDK: the daemon cannot start at all without it, even with plain-text credentials. Because the SDK cannot be redistributed for licensing reasons, the centreon-vmware container image is not published on a registry. The generated docker-compose.yaml references it as connector-vmware:${VMWARE_TAG:-local} with pull_policy: never, so you must build it locally, on the container host, before using --with-vmware.

Download the SDK archives from the Broadcom developer portal (see the prerequisites of the VMware ESX monitoring connector for instructions), then clone centreon-plugins, place the archives in its sdks-vmware directory, and build the image:

git clone https://github.com/centreon/centreon-plugins.git
cd centreon-plugins
# Place the downloaded SDK archives in sdks-vmware/ before building
docker build \
  --file .github/docker/connector/Dockerfile.connector-vmware \
  --tag connector-vmware:local \
  .

This downloads the latest package from Centreon's stable APT repository and includes the SDK by default. Add --build-arg VERSION=<version> to pin a specific release, or --build-arg PACKAGE_SOURCE=mount to build from a .deb package placed in a packages-centreon directory instead. Building with --build-arg WITH_SDK=false only validates that the image builds: the resulting daemon cannot start, since the SDK is required in all cases.

Allow the poller to receive data from Centreon Monitoring Agents (CMA)​

Add --with-cma to the poller install command so that centengine can accept connections from the Centreon Monitoring Agent over OpenTelemetry gRPC. Using --with-cma adds the following to the centengine service in the docker-compose:

    volumes:
      - ./certs/poller.crt:/etc/pki/poller.crt:ro
      - ./certs/poller.key:/etc/pki/poller.key:ro
    ports:
      - "4317:4317"

Then generate the corresponding TLS certificates and configure the agent side following Configuring certificates and Setting up the agent's environment.