Page History

Contexte

Cette page a pour but objectif de vous décrire la mise en place du pack docker-on-linux-by-APISSH__shinken :

• Le déploiement du pack sur

  votre plateforme,
  • Mise en place du framework de sondes.
  • Mise en place du pack.
• La configuration de vos connexions API,
• La mise en place de pré-requis pour certains checks.

Le déploiement du pack sur votre plateforme

Mise en place du framework de sondes

• la plateforme (sur le Synchronizer et sur le ou les Pollers),

• La configuration des prérequis nécessaires à l’exécution des checks.

L'installation du pack sur l'infrastructure Shinken

Installation de dépendance : VENV__plugins-packs__shinken

En préambule, il faut :

1. Récupérer la dernière version du pack contenant le VENV auprès de l'équipe Shinken,
2. Transférer le pack sur le Synchronizer et le ou les Pollers.

L'installation de l'environnement virtuel s'effectue en deux étapes :

Récupérer l'archive tar.xz de l'environnement virtuel

Chaque pack requiert une version minimale de l'environnement virtuel pour fonctionner. Les versions sont rétrocompatibles. Il est donc recommandé de toujours utiliser la dernière version disponible de l'environnement virtuel.

Décompresser l'archive tar.xz de l'environnement virtuel sur tous les serveurs Shinken avec un poller ou synchronizer et lancer l'installation

Décompresser l'archive sur les serveurs Shinken

Pour l'exécution correcte des commandes du pack docker-by-API__shinken, vous aurez besoin d'installer l'environnement virtuel python Shinken fourni en complément du pack sur un Poller ou Synchronizer.

Pour cela, décompressez l'archive qui vous a été fourni.

tar -xJf VENV__plugins-packs__shinken__VXX.XX.XX__Linux-<distrib>.tar.xz

Il suffit ensuite d'Rentrer dans le répertoire créé à la suite de la décompression, et exécuter le script d'installation du venv.

cd VENV__plugins-packs__shinken__VXX.XX.XX__Linux-<distrib>
./install-venv.sh

Mise en place du pack

En préambule, il faut :

1. récupérer la dernière version du pack auprès de l'équipe Shinken ou de votre partenaire,
2. Transférer le pack sur votre Synchronizer et votre/vos Pollers.

avec l'installeur "install.sh" ( sur Poller / Synchronizer )

Commun à tout Poller / Synchronizer

Que ce soit sur un Synchronizer où ou sur un Pollers Poller :

1. Désarchiver le pack :

   Code Block
   language bashtext theme Emacs
   tar --no-same-owner -xf NOM_DU_PACK.tar.xz

2. Entrée Entrer dans le répertoire extrait de l'archive et lancer le "install.sh"

   Code Block
   language bashtext theme Emacs
   cd NOM_DU_PACK/ ./install.sh

3. L'installeur dépose les éléments suivants :

   • Le fichier de configuration de la source "shinken-additional-packs-import" qui servira à importer la définition du pack dans le Synchronizer.
   • Les fichiers de définitions des éléments du pack, à importer dans le Synchronizer.
   • Les sondes du pack. 

Exemple de mise en place :

========================================================

PRE-INSTALLATION CHECKS
========================================================

No previous installation 

detected. Proceeding with installation...


========================================================
INSTALL PACK [ docker-on-linux-by-SSH__shinken v01.00.00 ]
========================================================

    -----------------------------
    |   COLLECTOR [ shinken-additional-packs-import ]

        => Collector 

cfg 

file already AVAILABLE
              - Path : /etc/shinken

/

sources/shinken-additional-packs-import.cfg

        => 

Collector DATA 

space already AVAILABLE
 

             - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import

        => Definition File already AVAILABLE [ definition_shinken-additional-packs-import.cfg ]
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/definition_shinken-additional-packs-import.cfg

        => Applying permissions
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import
              - Setting owner ( to "shinken" user )
              - Setting rights

    -----------------------------
    |   MONITORING DEFINITION:

        => Installing definitions file in source-data folder ( Collector => shinken-additional-packs-import )
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import
              - Setting owner ( to "shinken" user )
              - Setting rights

        => Installing global data definitions file in SHINKEN directory ( => resource.d )
              - Path : /etc/shinken/resource.d/shinken-additional-packs-import/
              - Setting owner ( to "shinken" user )
              - Setting rights

    -----------------------------
    |   PROBES:

        => 

Installing probes
              - Path : /var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-

SSH__shinken
 

-

Setting owner ( to "shinken" user )
              - Setting rights

En suivant, spécifiquement sur le Synchronizer

define synchronizer {
    [...]
    sources                   Source 1, Source 2, Source 3, shinken-additional-packs-import
    [...]
}

et en suivant, redémarrez le Synchronizer pour que le collecteur soit pris en compte :

========================================================
PRE-INSTALLATION CHECKS
========================================================

ERROR: Previous installation detected!

The following files/folders from a previous installation were found:
              - /var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-SSH__shinken
              - /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/docker-on-linux-by-SSH__shinken
              - /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken
              - /etc/shinken/resource.d/shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken

Please run './uninstall.sh' before installing the pack.

Installation ABORTED.

WARNING: Uninstallation will remove all installed config files ( .cfg ).
This step is required for installing this new pack version.
All manual changes to the present config files will be lost. This doesn't affect shinken Staging or Production environment.

Sur le Synchronizer

1. SEULEMENT si le collecteur "shinken-additional-packs-import" n'est pas déja PRÉSENT dans votre Synchronizer ( par exemple : première fois que vous utilisez un installeur de pack Shinken ) :
   
   Vérifier dans la configuration de votre Synchronizer ( /etc/shinken/synchronizers/synchronizer-master.cfg ) que le collecteur "shinken-additional-packs-import" soit présent dans le champ sources.

   Code Block
   language text theme Emacs
   cat /etc/shinken/synchronizers/synchronizer-master.cfg

   Code Block
   language js theme Confluence
   define synchronizer { [...] sources Source 1, Source 2, Source 3, shinken-additional-packs-import [...] }

   Si le collecteur "shinken-additional-packs-import" n'est pas présent, l'ajouter dans la liste puis redémarrez le Synchronizer pour que le collecteur soit pris en compte :

   Section
   Code Block language text theme Emacs service-shinken-synchronizer restart Note icon false Pour les versions de shinken strictement inferieur à V02.08.02-RC018.05, il faudra utiliser la commande suivante : Code Block language text theme Emacs service shinken-synchronizer restart

2. Activer le collecteur "shinken-additional-packs-import" si ce n'est pas déja fait.
   
   

   Panel
   Image Added

3. Lancer l'import du collecteur "shinken-additional-packs-import" :
   
   

   Panel
   Image Added

   
   

   • En suivant, vous devrez peut-être accepter ou des nouveautés ou des différences qui seraient liés à ce pack ( en fonction de l'évolution du pack ).
     
     

4. IMPORTANT : si c'est première fois que vous installez le pack, il est nécessaire de faire un dernier redémarrage du Synchronizer.

   Section
   Code Block language text theme Emacs service-shinken-synchronizer restart Note icon false Pour les versions de shinken strictement inferieur à V02.08.02-RC018.05, il faudra utiliser la commande suivante : Code Block language text theme Emacs service shinken-synchronizer restart

Mise en place du pack manuellement ( si l'utilisation du script install.sh n’est pas souhaitée ) :

Commun à tout Poller / Synchronizer

Si le pack est déjà installé

Il est recommandé de supprimer les anciens dossiers contenant le pack afin de garantir l'utilisation de la dernière version des fichiers livrés.

Pour effectuer cette suppression ( si la procédure d'installation manuelle a été suivie telle quelle ), la commande suivante peut être utilisée :

rm -rf /var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken/resource.d/shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken

Extraire le pack

Transférer le fichier du pack sur la machine et décompresser le fichier contenant le pack à l'aide de la ligne de commande ci-dessous (remplacer "PACK__shinken__NOM-DU-PACK__VERSION__OS.tar.gz" par le nom exact du pack livré) :

• Pour Linux ( le paramètre --no-same-owner permet de ne pas conserver les attributs d'utilisateurs/roles présent lors de la création du pack ) :

tar -xjfv --no-same-owner PACK__shinken__NOM-DU-PACK__VERSION__linux.tar.xz -C ./

• Pour Windows ( Rôle de Poller ) :

tar -xvzf PACK__shinken__NOM-DU-PACK__VERSION__windows.tar.gz -C ./

Entrer dans le répertoire créé :

cd NOM_DU_PACK/

Les sondes ( mises en place )

On place les sondes :

probe_path="/var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-SSH__shinken"
mkdir --parents $probe_path
cp -r ./probes/* $probe_path
chown -R shinken:shinken $probe_path
chmod -R 750 $probe_path

Sur le Synchronizer

Ensuite, il est nécessaire de placer les définitions des éléments de supervision du pack au bon endroit.

• Les fichiers de configuration :

  • • Il est recommandé de créer un collecteur de type cfg-file-import, qui permet d'importer des définitions d'éléments Shinken à partir des fichiers .cfg fournis dans le pack.

    • La procédure de mise en place de ce type de collecteur est disponible dans la documentation à la page  : ( Collecteur de type ( cfg-file-import ) - Import depuis des fichiers au format .cfg )

    • Dans la suite de cette documentation, ce collecteur sera nommé "shinken-additional-packs-import"

  • Une fois le collecteur mis en place, le pack peut être déployé à l’emplacement attendu :

    • En premier, les fichiers de définition des éléments ( modèles d'hôtes, checks, commandes, ... )  du pack :

      Code Block
      language text theme Emacs
      shinken_collector_data_path="/etc/shinken-user/source-data/source-data-shinken-additional-packs-import" cp -r ./monitoring-definitions/packs/* $shinken_collector_data_path chown -R shinken:shinken $shinken_collector_data_path chmod -R 744 $shinken_collector_data_path

    • Ensuite, les données globales

      Code Block
      language text theme Emacs
      shinken_pack_globaldata_path="/etc/shinken/resource.d/shinken-additional-packs-import" mkdir --parents $shinken_pack_globaldata_path cp -r "./monitoring-definitions/global-data" "$shinken_pack_globaldata_path" chown -R shinken:shinken "$shinken_pack_globaldata_path" chmod -R 744 "$shinken_pack_globaldata_path"

• Redémarrer le Synchronizer

  Section
  Code Block language text theme Emacs service-shinken-synchronizer restart Note icon false Pour les versions de shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante : Code Block language text theme Emacs service shinken-synchronizer restart

• Activer le collecteur  "shinken-additional-packs-import" :

  Panel
  Image Added

• Lancer l'import du collecteur "shinken-additional-packs-import",

  Panel
  Image Added

  
  

  • En suivant, vous devrez peut-être accepter les nouveautés / différences qui seraient liés à ce pack ( en fonction de l'évolution du pack ).
    
    

• IMPORTANT : si c'est la première fois que vous installez le pack, il est nécessaire de faire un dernier redémarrage du Synchronizer.

  Section
  Code Block language text theme Emacs service-shinken-synchronizer restart Note icon false Pour les versions de shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante : Code Block language text theme Emacs service shinken-synchronizer restart

Le dossier extrait lors de la décompression du pack peut également être supprimé à l’aide de la commande suivante :

rm -rf ./PACK__docker-on-linux-by-SSH__shinken__V01.00.00__Linux

Si une version précédente du pack a déjà été installée, il est recommandé de supprimer les anciens dossiers pour éviter de conserver des fichiers obsolètes, notamment en cas de modification de la structure du pack.

Utiliser les commandes suivantes pour effectuer cette suppression :

rm -rf /var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken
rm -rf /etc/shinken/resource.d/shinken-additional-packs-import/global-data/docker-on-linux-by-SSH__shinken

Comment configurer la connexion SSH ?

Pour l'exécution correcte des commandes du pack docker-on-linux-by-SSH, vous aurez besoin d'une connexion SSH.

Quelques informations au préalable sont nécessaires pour la bonne compréhension de cette partie.

• D'une part, du côté de l'architecture Shinken, l'exécution des checks ( plus exactement les sondes ) sont réalisées par les Pollers, en tant qu'utilisateur "shinken".
  • Donc l'utilisateur "shinken " devra avoir accès aux clefs SSH que vous utiliserez pour la connexion SSH sur les serveurs distants monitorés.
• D'autre part, du côté des machines Linux supervisées,
  • un nom d'utilisateur, et une clé SSH ou mot de passe sont requis.
  • Dans les modèles du pack docker-on-linux-by-SSH , des données sont prévues à cet effet.

Nous conseillons l'utilisation d'un utilisateur spécifique ( pour le service de supervision ) ainsi que l'utilisation d'une connexion via clé SSH, afin d'éviter l'utilisation du super utilisateur root qui n'est pas requis par les checks.

Côté client ( Docker supervisé )

Si votre utilisateur de supervision n'est pas déjà créé sur votre linux à superviser, depuis un terminal de la machine supervisée " linux-1 " ( en root ), il faut créer un nouvel utilisateur local avec mot de passe.

Pour pouvoir accéder aux informations sur les conteneurs Docker, l'utilisateur local au linux utilisé pour la connexion doit faire partie du groupe docker.

• dans cet exemple, nous utilisons "user-service-shinken" mais vous pouvez créer un autre utilisateur.

Côté serveur Poller

Copie de la clé SSH de votre utilisateur de supervision "shinken" depuis le serveur Poller "shinken-poller" ( pour cet exemple ), vers le serveur supervisé "linux-1" ( dans cet exemple, IP : 192.168.1.19 ) 

Copie clé SSH via commande ssh-copy-id

Soit via la méthode "automatique" via la commande ssh-copy-id en se connectant au préalable via l'utilisateur shinken sur le ou les serveurs pollers :

[root@shinken-poller ~]# su - shinken
[shinken@shinken-poller ~]#  ssh-copy-id -i ~/.ssh/id_rsa.pub user-service-shinken@linux-1
The authenticity of host '192.168.1.19 (192.168.1.19)' can't be established.
RSA key fingerprint is 00:ff:ee:dd:cc:bb:aa:d6:d3:79:1d:f6:93:47:80:27.
Are you sure you want to continue connecting (yes/no)? yes
user-service-shinken@linux-1's password: XXXXXXXXXXX
Now try logging into the machine, with "ssh 'user-service-shinken@linux-1'", and check in:
  .ssh/authorized_keys
to make sure we haven't added extra keys that you weren't expecting.

Copie clé SSH via commande ssh

Soit via une commande SSH depuis le serveur Poller, il s'agit d'ajouter la clé publique au fichier "authorized_keys" du serveur supervisé ( ici linux-1 ) :

cat /var/lib/shinken/.ssh/id_rsa.pub | ssh root@linux-1 "cat >> /home/user-service-shinken/.ssh/authorized_keys"

Ici la connexion se fait via l'utilisateur root du serveur linux-1 ( mais vous pouvez utiliser votre propre utilisateur ), le but étant de rajouter, en une commande SSH, la clé de l'utilisateur shinken du Poller /var/lib/shinken/.ssh/id_rsa.pub à la fin du fichier /home/user-service-shinken/.ssh/authorized_keys du serveur supervisé.

Copie clé SSH manuellement

Soit via méthode "manuelle" via rajout de la clé dans le fichier authorized_keys

• Récupérez la clé publique de l'utilisateur qui va établir la connexion SSH, et la copier

service shinken-synchronizer restart

Lancer l'import du collecteur "shinken-additional-packs-import":

• Code Block
  language text theme Emacs

• [root@shinken-poller ~]# su - shinken

Ou manuellement ( si ne vous voulez pas utiliser l'install.sh )

Commun à tout Poller / Synchronizer

Si vous avez déjà installé le pack

• [-bash-4.1]$ cat .ssh/id_rsa.pub -> copiez la clé

• Connectez-vous sur le serveur linux supervisé avec votre utilisateur de supervision et collez cette clé dans le fichier "authorized_keys" de l'utilisateur de supervision

Nous vous conseillons de supprimer les anciens dossiers dans lesquels le pack était présent, pour être sûr d'avoir la dernière version de tous les fichiers livrés.

• :

  Code Block
  language text theme Emacs

• [root@linux-

Extraire le pack

• 1 ~]# su - user-service-shinken [-bash-4.1]$ vi .ssh/authorized_keys -> collez la clé

Test de connexion

Test de connexion au serveur "linux-1" en tant qu'utilisateur "user-service-shinken" via l'utilisateur du Poller ( shinken

Transférer sur votre machine et décompressez le fichier contenant le pack à l'aide de la ligne de commande ci-dessous ( en remplaçant "PACK__shinken__NON-DU-PACK__VERSION__OS.tar.gz" par le nom du pack qui vous est livré.

) :

tar -xjfv --no-same-owner PACK__NOM-DU-PACK__shinken__VERSION__linux.tar.xz -C ./

[root@shinken-poller ~]# su - shinken
[shinken@shinken-poller ~]# ssh user-service-shinken@linux-1 -i .ssh/id_rsa

La connexion doit s'établir avec succès.

Problème de connexion : regarder dans les logs

Si la connexion échoue, les logs du service "sshd" peuvent donner des indications précieuses sur la cause de l'échec. La méthode de consultation de ces informations dépend de la distribution utilisée et de son ancienneté.

Ci-dessous, la liste non exhaustive des méthodes connues pour consulter les logs, sur les distributions officiellement supportées par Shinken :

Pour Redhat / Almalinux / Rockylinux / Centos :

• la commande journactl permet d'afficher les logs du service

  Pour Windows ( Rôle de Poller )

  :

  Code Block
  language text theme Emacs

• journalctl -

• xf

Entrez dans le répertoire créér :

cd NOM_DU_PACK/

Les sondes ( mises en place )

• -u sshd

• Le fichier de log "secure" contient les informations concernant les dernières connexions

• :

  Code Block
  language

• text theme Emacs

  cat /var/

Sur le Synchronizer

• log/secure

Pour Debian :

• la commande journactl permet d'afficher les logs du service (le nom de service utilisé n'est pas le même que pour les autres distributions) :

  Code Block
  language text theme Emacs
  journalctl -xf -u ssh

Ces logs permettent, entre autres, de savoir :

• Si le problème de connexion provient du client ou du serveur.
• Si les algorithmes de chiffrement utilisés sont cohérents entre les serveurs et permettent l'établissement de la connexion. 
• Si les droits attribués aux répertoires contenant les clés d'authentification sont les bons.

Exemple :

Dans l'exemple ci-dessous, les droits n'ont pas été correctement appliqués au répertoire de Shinken contenant les clés SSH. La connexion n'a pas pu s'établir 

[root@alpachouette-shinken01 shinken]# journalctl -xf -u sshd
-- Logs begin at Wed 2025-09-03 14:44:35 CEST. --
Sep 04 15:32:21 shinken-server sshd[1372868]: Authentication refused: bad ownership or modes for directory /var/lib/shinken/.ssh
Sep 04 15:32:21 shinken-server sshd[1372868]: Connection closed by authenticating user shinken 172.17.0.37 port 48152 [preauth]
Sep 04 15:32:25 shinken-server sshd[1372968]: Authentication refused: bad ownership or modes for directory /var/lib/shinken/.ssh
Sep 04 15:32:25 shinken-server sshd[1372968]: Connection closed by authenticating user shinken 172.17.0.37 port 48160 [preauth]
Sep 04 15:32:25 shinken-server sshd[1372971]: Authentication refused: bad ownership or modes for directory /var/lib/shinken/.ssh

Côté interface de configuration

Modèle d'hôtes docker-on-linux-by-SSH__base__shinken

Comment configurer la connexion API ?

Pour l'exécution correcte des commandes du pack docker-by-API__shinken, vous aurez besoin d'activer l'API Engine sur l'instance docker supervisée.

Côté client ( Docker supervisé )

Pour savoir comment configurer l'API sur le docker à superviser, voir la page NEW-PAGE Configuration du Docker supervisé pour le pack docker-by-SSH__shinken.

Côté serveur Poller

Aucune configuration spécifique nécessaire sur le Poller

Côté interface de configuration

Modèle d'hôtes docker-by-API

Désinstaller le pack avec "uninstall.sh"

Entrée dans le répertoire extrait de l'archive et lancer le "uninstall.sh"

cd docker-on-linux-by-APISSH__shinken ./uninstall.sh

Ce mécanisme va seulement enlever les fichiers mis en place lors de l'installation ( Fichier du collecteur d'import, définition des éléments de supervision, et les sondes proposées ), mais ne touchent pas aux éléments que vous avez absorbés dans le Synchronizer.

==========================================================
UNINSTALL PACK [ docker-on-linux-by-APISSH__shinken V01.00.00 ]
==========================================================

    -----------------------------
    |   MONITORING DEFINITION:

        => Deleting pack monitoring definition folder
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/docker-on-linux-by-APISSH__shinken

        => Deleting pack monitoring definition file
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/docker-on-linux-by-APISSH__shinken.pack

        => Deleting pack monitoring globaldata folder
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/docker-on-linux-by-APISSH__shinken

        => Deleting shinken pack globaldata folder
              - Path : /etc/shinken/resource.d/shinken-additional-packs-import/global-data/docker-on-linux-by-APISSH__shinken/


    -----------------------------
    |   PROBES:

        => Deleting probes
              - Path : /var/lib/shinken-user/libexec/shinken-additional-packs/docker-on-linux-by-APISSH__shinken


==========================================================
PACK [ docker-on-linux-by-APISSH__shinken V01.00.00 ] SUCCESSFULLY UNINSTALLED
==========================================================