Historique

CentCTL est un exécutable indépendant créé en 2020 par Mélissa Bertin au sein de la société YPSI. Tout comme CLAPI, il utilise l'API pour réaliser la majeure partie des tâches sur Centreon en ligne de commande. CLAPI nécessite d'être exécuté localement sur le serveur Centreon Central. Vous aurez donc besoin d'une connexion SSH pour pouvoir l'administrer depuis votre poste de travail. De plus, les commandes nécessitent systématiquement une authentification avec mot de passe en clair, et a parfois une syntaxe de commande peu intuitive.

CentCTL utilise l'API REST v1 pour opérer les différentes tâches d'administration. En ayant seulement accès à l'API, on peut administrer notre solution de supervision sans connexion SSH. Aucunement besoin d'interface web, seul un utilisateur avec les droits d'accès à l'API est nécessaire. Le module est développé en langage Go, ce qui le rend multiplateforme et plaira donc à la fois à nos amis pingouins comme aux croqueurs de pommes et aux afficionados des solutions Microsoft.

Centreon & CentCTL: l'importance de la convention de nommage.

Il est très important d'adopter une convention de nommage précise et de s'y tenir!!! Il est très facile de filtrer les éléments dont vous avez besoin grâce à des regex dans CentCTL. Mais pour cela, il faut adopter une convention assez précise.

Ci-dessous je détaille une proposition de convention de nommage.

Les commandes

  • ChC = Check Command
  • NoC = Notification Command
  • DiC = Discovery Command
  • MiC = Miscellaneous Command
  • CoC = Connectors Command

Puis ajoutez le nom de la commande. Prenez soit l'objet utilisé par le plugin Centreon, Nagios ou autre pour les commandes de check (par exemple check_ping), soit un descriptif très succinct comme nous pouvons l'avoir de base dans les commandes de notification déjà intégrées à Centreon (host-notify-by-email).

Le résultat donnera quelque chose comme:

  • ChC_CHECK_PING
  • NoC_HOST_EMAIL

Si votre commande est spécifiquement adapté à un seul type d'OS, alors il faudra le préciser avant le nom:

  • ChC_OS_ORACLE8_DISK_SPACE_VAR
  • ChC_OS_WINSRV16_DISK_SPACE_D

Ect... Libre à vous d'imaginer le plus parlant.

Les templates

Les templates de configuration

Une bonne pratique est de créer, pour les services et pour les hôtes, des templates de configuration (pour configurer d'autres templates).

Exemple: template de configuration de notifications.

Lors de la création d'un modèle d'hôte ou de service, liez directement le Template de configuration de notifications, et vous n'aurez pas à configurer les notifications pour ce template. Ce qui, grâce aux relations avec les modèles d'hôte ou de service fonctionnels, évitera les manipulations trop lourdes et trop contraignantes dans leurs nombres pour venir modifier un paramètre concernant les notifications. Vous changez votre paramètre directement dans le template de configuration de notification et cela s'applique absolument à tout les templates liés, se répercutant donc sur les hôtes et services.

Lors de la création de ce template, ne configurez que les paramètres notifications (ce qui correspond à l'onglet du même nom dans l'interface web).

Par exemple, ces templates se nommeront ainsi:

  • Nom => STC_NOTIF = Service Template Configuration

  • Nom => HTC_NOTIF = Host Template Configuration

Vous pouvez mettre la même chose dans l'alias.

Libre à vous de créer les template de configuration de votre choix, par exemple plusieurs templates de configuration pour vos différentes communautés snmp, etc... Adaptez selon vos besoins.

Les templates de service

Ces templates de baseront sur le nom de la commande qu'ils représentent:

  • Nom => ST_ChC_OS_DEB10_DISK_SPACE_VAR (ST pour Service Template)
    • Alias => SFT_ChC_OS_DEB10_DISK_SPACE_VAR (SFT pour Service From Template)

Ici, définir un alias correctement peut vous permettre de différencier sur la page des services par hôtes, les services hérités d'un modèle de service, et ceux créés manuellement sans passer par un template.

Les templates d'hôte

Décrivez succinctement l'OS et la fonction de l'hôte en question:

  • Nom => HT_OS_WINSRV19_WEB_SRV (HT pour Host Template)
    • Alias => HFT_OS_WINSRV19_WEB_SRV (HFT pour Host From Template)

Les hôtes

Le nom de l'hôte supervisé sera basé sur le nom de la société et/ou sa localisation (si vous supervisez plusieurs entreprises ou sites), son os, sa fonction, éventuellement le service auquel il est affecté et un numéro (utile si vous supervisez de très nombreux postes de travail ou une ferme de serveurs)

  • Nom: Aukfood_Linux_Server_Web_001
    • ou encore: CrdAgr_RSY-PlaceVendee_Win10_Direction_001

Pour l'alias, inscrivez simplement son FQDN.

Les services

Si vous créez un service automatiquement lors de la création d'un hôte en relation avec un template d'hote et des templates de service alors celui ci portera le nom de l'alias donné au template de service:

  • SFT_ChC_CHECK_PING

Si vous créez un service manuellement sans passer par un template:

  • S_ChC_CHECK_PING

Pourquoi tout ça?

Et bien, lorsque vous allez utiliser des commandes CentCTL par la suite pour créer des listes à utiliser dans un script pour automatiser un déploiement par exemple, vous n'aurez qu'à filtrer avec un peu de regex des ensembles d'éléments, rediriger le flux de sortie dans un fichier, un peu de substitution massive par de la regex (encore) dans vim et le tour est joué. J'y reviendrai plus tard.

Préparer le poste de travail

Le reste de cet article décrit des procédures qui ont été réalisées sous Rocky Linux 8.4.

Téléchargement de CentCTL

Créer un dossier dans lequel récupérer CentCTL puis télécharger la dernière version:

mkdir $HOME/centctl
cd $HOME/centctl
wget https://github.com/YPSI-SAS/centctl/releases/download/v2.5/centctl_linux_amd64 -O centctl

Rendre ce fichier exécutable:

chmod +x centctl

Préparation de la commande

Configurer la variable d'environnement CENTCTL_CONF avec le chemin et le nom du fichier de configuration nommé centctl.yaml. Modifier le .bashrc de l'utilisateur qui utilisera CentCTL avec la ligne suivante en bas du fichier:

export CENTCTL_CONF=/home/USER/centctl/centctl.yaml

USER étant votre nom d'utilisateur, bien entendu !

Configurer l'auto-complétion :

Si le paquet n'est pas installé:

dnf install bash-completion

Puis exécuter les commandes:

source ~/.bashrc
type _init_completion

Si la commande réussi, on peut passer à la suite, sinon:

  1. Dans le .bashrc, écrivez cette ligne de commande en bas du fichier:

    source /usr/share/bash-completion/bash_completion
  2. Rechargez votre shell avec source .bashrc puis vérifiez que la complétion et correctement installée avec la commande type _init_completion.

Pour terminer, ajouter le script de complétion dans le répertoire /etc/bash_completion.d:

sudo su
/home/USER/centctl/centctl completion bash > /etc/bash_completion.d/centctl

Configuration de CentCTL

Il faut maintenant construire de fichier de configuration centctl.yaml.

vim centctl.yaml

Pour déclarer un serveur, utilisez la configuration ci-dessous en remplaçant les mots en MAJUSCULE.

  • NAMESERVER c'est le nom du serveur à utiliser avec le flag --server. ATTENTION: le nom du serveur doit être unique.
  • URL: c'est l'adresse utilisée pour l'accès à l'interface web de Centreon au format: https://monserveurcentreon.fr (ou avec l'IP). ATTENTION: si l'url n'est pas sécurisée, mettre http.
  • insecure est utilisé quand l'URL du server est en https. Le flag est le même ( --insecure) pour forcer la connexion.
  • LOGIN est le login avec les droits d'accès RestAPI utilisé pour la connexion au serveur. CONSEIL: utiliser admin qui est automatiquement autorisé pour l'API Rest.
  • PASSWORD est le mot de passe de l'utilisateur
  • VERSION est la version du Rest API (v1 ou v2)
  • default défini le server par défaut auquel se connecter

Exemple de fichier de configuration:

servers:
    -   server: "centreon-centos"
        url: "https://centreon21.aukfood.fr"
        insecure: true
        login: "admin"
        password: "Pa55word"
        version: "v1"
        default: true
    -   server: "centreon-rocky"
        url: "http://192.168.1.222/centreon"
        login: "admin"
        password: "azerty666"
        version: "v1"

Pour rappel CentCTL utilise la V1 de Rest API.

Tester la configuration

Pour exécuter les commandes ./centctl, se placer dans le répertoire centctl

Un test tout simple qui permet de voir si la configuration est bonne:

./centctl --server=centreon-centos list host

Voici le résultat, au format json par défaut:

{
 "server": {
  "name": "centreon-centos",
  "hosts": [
   {
    "id": "23",
    "name": "Aukfood_Rocky_Client_001",
    "alias": "RockyLinux.aukfood.fr",
    "address": "192.168.1.148",
    "activate": "1"
   }
  ]
 }
}

D'autres formats sont disponibles avec le flag --output en fin de commande:

./centctl --server=centreon-centos list host --output yaml
./centctl --server=centreon-centos list host --output csv
./centctl --server=centreon-centos list host --output text

D'autres options sont disponibles, comme filtrer avec des regex... Rendez-vous sur la page d'aide /.centctl --help

Exporter les configurations

La migration de la configuration de la plateforme Centreon est possible avec CentCTL, même par exemple depuis la 20.10 vers une version supérieure comme la 21.10.

Personnellement je préfère éviter d'exporter toute la configuration d'un coup surtout si celle-ci est importante, j'ai été confronté à certains problèmes lors de test. Je préfère être méticuleux et catégoriser.

La configuration du moteur Centreon

J'utilise le flag -r ^.* pour tout selectionner mais le flag --all marche très bien aussi.

./centctl --server=centreon-centos export engineCFG -r ^.* -f engine.csv

Les ressources du poller

./centctl --server=centreon-centos export resourceCFG -r ^.* -f ressources.csv

Les contacts/utilisateurs

./centctl --server=centreon-centos export contact -r ^.* -f contacts.csv

Les paramètres de notification ne seront pas exportés, attention lors de l'importation à les configurer de nouveau à la main. En effet, l'API REST v1 ne prend pas en charge ces paramètres et la v2 ne supporte pas les contacts.

Les commandes

Exportez les commandes:

./centctl --server=centreon-centos export command -r ^ChC  -f check_commands.csv
./centctl --server=centreon-centos export command -r ^NoC  -f notification_commands.csv
(etc...)

Les Templates

Les templates de notification

Exportez les templates de notifications des services et des hôtes à part du reste des templates:

./centctl --server=centreon-centos export template service -r ^STC -f conf_serv_temp.csv
./centctl --server=centreon-centos export template host -r ^HTC -f conf_host_temp.csv

Les templates d'hôte

./centctl --server=centreon-centos export template host -r ^HT -f host_temp.csv

Les templates de service

./centctl --server=centreon-centos export template service -r ^ST -f serv_temp.csv

Les hôtes

./centctl --server=centreon-centos export host -r ^.* -f hosts.csv

Les services

 ./centctl --server=centreon-centos export service -r ^*$ -f services.csv

Importer vos configurations

Cet ordre d'importation me parait le plus logique en fonction des dépendances/héritages qu'il peut y avoir.

  1. La configuration du moteur
  2. Les ressources du poller
  3. Les templates de configuration
  4. Les commandes
  5. Les utilisateurs
  6. Les templates d'hôtes
  7. Les templates de services
  8. Les hôtes
  9. Les services

Si différents éléments n'ont pas tous les paramètres renseignés car ceux-ci sont hérités de templates, alors de nombreux messages de warning apparaitront, mais ne gêneront pas le processus.

./centctl --server=centreon-rocky import -f engine.csv 
./centctl --server=centreon-rocky import -f ressources.csv 
./centctl --server=centreon-rocky import -f contacts.csv
./centctl --server=centreon-rocky import -f check_commands.csv

(ect... pour les commandes)

./centctl --server=centreon-rocky import -f conf_host_temp.csv
./centctl --server=centreon-rocky import -f conf_serv_temp.csv
./centctl --server=centreon-rocky import -f host_temp.csv
./centctl --server=centreon-rocky import -f serv_temp.csv
./centctl --server=centreon-rocky import -f hosts.csv
./centctl --server=centreon-rocky import -f services.csv

Déployer la configuration

./centctl --server=centreon-rocky import -f engine.csv 

Il peut être préférable de vérifier la configuration dans l'interface web plutot que d'appliquer directement lors d'une grosse importation.

CentCTL: de la commande à l'hôte.

Les manipulations qui vont suivre peuvent paraitre longues et fastidieuses comparé à la simplicité d'utilisation de l'interface web Centreon. En effet, pour un besoin ponctuel, il est préférable de passer par l'interface.

Mais ces commandes sont nécessaires dans le cadre de la réalisation d'un script pour automatiser et accélérer la configuration de nombreux éléments.

Créer une commande

./centctl --server=centreon-rocky add command -l "\$USER1$/check_ping -H \$HOSTADDRESS$ -w \$_SERVICEWARNING$ \$_SERVICECRITICAL$ -p \$_SERVICENBPACKETS$ -4" -n ChC_CHECK_PING -t check

Il est impératif de banaliser le premier $ des macros avec un antislash sinon le shell va interpréter comme une variable vide et ça ne va pas correctement s'implanter dans Centreon.

Créer un template de service:

Exemple avec la commande check_ping:

./centctl --server=centreon-rocky add template service -a SFT_ChC_CHECK_PING -n ST_ChC_CHECK_PING -t CST_NOTIF

Configurer les paramètres généraux:

./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p macro --value="WARNING|3,40%|0|seuil d'alerte 1"
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p macro --value="CRITICAL|5,60%|0|seuil d'alerte 2"
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p macro --value="NBPACKETS|5|0|nombre de paquets"
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p check_period -v 24x7
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p normal_check_interval -v 5
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p retry_check_interval -v 5
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p active_checks_enabled -v 1
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p passive_checks_enabled -v 0
./centctl --server=centreon-rocky modify template service -n ST_ChC_CHECK_PING -p is_volatile -v 0

Configurer les paramètres de notification:

Nous allons utiliser un autre template, dédié à la configuration des notifications

./centctl --server=centreon-rocky modify template service -n STC_NOTIF -p notifications_enabled -v 1
./centctl --server=centreon-rocky modify template service -n STC_NOTIF -p contact -v "admin"
/centctl --server=centreon-rocky modify template service -n STC_NOTIF -p contactgroup -v "Supervisors"
/centctl --server=centreon-rocky modify template service -n STC_NOTIF -p notification_interval -v 10
./centctl --server=centreon-rocky modify template service -n STC_NOTIF -p notification_period -v 24x7
./centctl --server=centreon-rocky modify template service -n STC_NOTIF -p notification_options -v "w,u,c,r,f,s"
./centctl --server=centreon-rocky modify template service -n STC_NOTIF -p recovery_notification_delay -v 0

Pour les temps définis à zero il n'est pas utile de taper la commande

Créer un template d'hôte

./centctl --server=centreon-rocky add template host -a HFT_DEBIAN_WEB_SERVER -n HT_DEBIAN_WEB_SERVER -t HTC_NOTIF
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p snmp_community -v public
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p snmp_version -v 2c
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p timezone -v Europe/Paris
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p check_command -v ChC_HOSTALIVE
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p max_check_attempts -v 5
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p check_interval -v 1
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p retry_check_interval -v 1
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p active_checks_enabled -v 1
./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p passive_checks_enabled -v 0

Ici la commande ChC_HOSTALIVE liée au template ne comporte pas de macros perso ni d'arguments. Dans le cas où vous auriez des macros à configurer, les valeurs de celles-ci se déclarent de la même manière que pour les macros des templates de service.

Les commandes pour les paramètres de notifications sont les mêmes que pour les templates de service.

Pour lier des templates de service:

./centctl --server=centreon-rocky modify template host -n HT_DEBIAN_WEB_SERVER -p linkedservice -v ST_ChC_CHECK_PING

Répéter la commande autant de fois qu'il y a de templates de service à lier.

Créer un hôte

./centctl --server=centreon-rocky add host -i 192.168.1.148 -a websrv01.aukfood.fr -n Aukfood_Debian_Web_Server_001 -p Central -t HT_DEBIAN_WEB_SERVER 

Par défaut, l'ajout de l'hôte par CentCTL créé automatiquement les services liés aux templates.

Pour définir d'autres paramètres (soit non définis dans un template d'hôte ou volonté de le changer, soit pour configurer l'hôte manuellement sans relation avec un template), se référer aux commandes listées plus haut.

./centctl --server=centreon-rocky modify host -n Aukfood_Debian_Web_Server_001 -p .....

Créer un service

./centctl --server=centreon-rocky add service -n Aukfood_Debian_Web_Server_001 -t ST_ChC_CHECK_PING -d SFT_ChC_CHECK_PING

-n nom de l'hôte, -t template de service, -d description (nom du service/alias du template de service)

Pour aller plus loin

De nombreux autres paramètres n'ont pas été abordés! Pour en découvrir d'autres, c'est par ici !!!

Exemple pratique: automatiser le déploiement d'un nouveau service sur tout un parc

Afin d'éviter de devoir faire une myriade de clics pour déployer un nouveau service sur des centaines de machines, nous pouvons à l'aide d'un petit script très basique déployer en un temps record la nouvelle sonde.

Contexte

Nous avons correctement créé nos hôtes, hérités d'un Template d'hôte, qui est en relation avec un ou plusieurs Template de service qui contiennent une commande.

Extraire une liste d'hôtes

./centctl --server=centreon-rocky list host -r ^.* --output csv > hosts.csv
vim hosts.csv

La liste se présente sous ce format:

ID,Name,Alias,Address,Activate
5,Aukfood_Debian_Web_Server_001,websrv01.aukfood.fr,192.168.1.148,1
6,Aukfood_Debian_Web_Server_002,websrv02.aukfood.fr,192.168.1.149,1
7,Aukfood_Win19srv_Dns_Server_001,dnssrv01.aukfood.fr,192.168.1.253,1

Quelques petites manips avec vim:

  • Ôter la premiere ligne en plaçant le curseur en début de ligne et appuyez 2 fois rapidement sur d

  • Entrez ces commandes:

    :g/^\d*,/s///
    :g/,.*$/s///

    > Selon les préférences, la commande sed ira très bien aussi!

Après manipulation nous obtennons une liste ne contenant que les noms d'hôtes.

Aukfood_Debian_Web_Server_001
Aukfood_Debian_Web_Server_002
Aukfood_Win19srv_Dns_Server_001

Créer le script

vim autodeploy.sh
#!/bin/bash

#Déclare la liste d'hôte
listhost="$(<hosts.csv)"

#Boucle sur tout les hôtes
for host in $listhost; do
./centctl --server=centreon-rocky add service -n $host -t ST_ChC_CHECK_PING -d SFT_ChC_CHECK_PING
done

#Exporte la configuration sur le poller selectionné et le recharge
./centctl --server=centreon-rocky apply -n Central

echo "Wouah, c'était long! Tu as bien travaillé, vas te reposer maintenant ;)"

Maintenant, vous pouvez grâce à toutes les commandes CentCTL vues précédemment vous amuser à scripter dans tout les sens...

Sources

L'atelier de Kermith qui est une vraie pépite pleine de bonne choses! Github de CentCTL dans lequel j'ai trouvé nombreuses réponses. Mes cours sur la supervision lors de ma formation TSSR à l'ENI de St-Herblain ( coucou Fred 🙂 )

Merci

Merci de m'avoir lu, et soyez indulgent pour mon 1er article dans le monde de l'IT !!! (et du monde libre, une pierre deux coups, tant qu'à faire)

Charles, stagiaire TSSR.