View Source

Contexte

Cette page a pour objectif de décrire la mise en place du pack proxmox-ve-by-API__shinken :

Le déploiement du pack sur 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 : VENVplugins-packsshinken

En préambule, il faut :

Récupérer la dernière version du pack contenant le VENV auprès de l'équipe Shinken,
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.

Pack	Environnement virtuel minimum
proxmox-ve-by-API	V01.00.03

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

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

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

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

Mise en place du pack avec l'installeur "install.sh" ( sur Poller / Synchronizer )

Commun à tout Poller / Synchronizer

Que ce soit sur un Synchronizer ou sur un Poller :

Désarchiver le pack :

tar --no-same-owner -xf NOM_DU_PACK.tar.xz

Entrer dans le répertoire extrait de l'archive et lancer le "install.sh"
cd NOM_DU_PACK/ ./install.sh
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...

========================================================
CHECKING PACK LIBRARIES:
========================================================
  - PYTHON VENV
  ~~~~~~~~~~~~~~~~~~
            => Location [/var/lib/shinken-user/libexec/shinken-additional-packs/.shinken__venv_plugin]

        => REQUIRED : 01.00.03
            - Currently installed Venv version : 01.00.03

            => NOTHING TO DO.


========================================================
INSTALL PACK [ proxmox-ve-by-API__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/proxmox-ve-by-API__shinken
              - Setting owner ( to "shinken" user )
              - Setting rights

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

Si une version du pack est déjà installée, elle doit être désinstallée avant d’installer la nouvelle version. L’installeur vérifiera automatiquement si l’ancienne version a été correctement supprimée et vous avertira si ce n’est pas le cas.

========================================================
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/proxmox-ve-by-API__shinken
              - /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/proxmox-ve-by-API__shinken
              - /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken
              - /etc/shinken/resource.d/shinken-additional-packs-import/global-data/proxmox-ve-by-API__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

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.
cat /etc/shinken/synchronizers/synchronizer-master.cfg
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 :
service-shinken-synchronizer restart
Pour les versions de Shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante :
service shinken-synchronizer restart
Activer le collecteur "shinken-additional-packs-import" si ce n'est pas déjà fait.
Lancer l'import du collecteur "shinken-additional-packs-import" :
- En suivant, vous devrez peut-être accepter ou des nouveautés ou des différences qui seraient liées à 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.
service-shinken-synchronizer restart
Pour les versions de Shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante :
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/proxmox-ve-by-API__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/proxmox-ve-by-API__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken
rm -rf /etc/shinken/resource.d/shinken-additional-packs-import/global-data/proxmox-ve-by-API__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/proxmox-ve-by-API__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 :

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

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
service-shinken-synchronizer restart
Pour les versions de shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante :
service shinken-synchronizer restart
Activer le collecteur "shinken-additional-packs-import" :
Lancer l'import du collecteur "shinken-additional-packs-import",
- 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.
service-shinken-synchronizer restart
Pour les versions de Shinken strictement inférieures à V02.08.02-RC018.05, il faudra utiliser la commande suivante :
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__proxmox-ve-by-API_shinken__V01.00.00__Linux

Attention à ne pas supprimer le fichier tar.gz. Connaître la version exacte du pack livré est utile en cas de problème avec celui-ci.

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/proxmox-ve-by-API__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/proxmox-ve-by-API__shinken
rm -rf /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken
rm -rf /etc/shinken/resource.d/shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken

Comment configurer la connexion API ?

Pour l'exécution correcte des commandes du pack proxmox-ve-by-API, l'accès à l'API native de Proxmox est requis.

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) est réalisée par les Pollers, en tant qu'utilisateur "shinken".
- Les pollers Shinken seront la source des appels HTTP/HTTPS
D'autre part, du côté du cluster Proxmox supervisé,
- Pour accéder à l'API, un nom d'utilisateur et un token API sont requis.
- Dans les modèles du pack proxmox-ve-by-API, des données sont prévues à cet effet.

Nous conseillons fortement l'utilisation d'un utilisateur spécifique ( pour le service de supervision ) à droit restreint pour effectuer les vérifications, afin d'éviter les brèches de sécurité.

Côté client ( Proxmox supervisé )

Pour créer tous les éléments nécessaires à la supervision Proxmox, il faut, directement depuis l'interface de configuration Proxmox :

Créer un nouvel utilisateur
Créer une nouvelle clé API ( liée à l'utilisateur créé )
Ajouter le rôle "PVEAuditor" au nouvel utilisateur pour permettre la supervision.

Dans cet exemple, le nom d'utilisateur utilisé sera "shinken" et le nom de la clé sera "SUP-SHINKEN".

Les noms d'utilisateur et de clé API utilisés ici seront ensuite utilisés dans l'interface Shinken pour les données suivantes :

PROXMOX-VE-BY-API__TOKEN
PROXMOX-VE-BY-API__USER

Création de l'utilisateur

Sur l'interface de configuration, se rendre dans "Datacenter" puis dans "Users" :

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-6_17-7-45.png

Dans le menu "Users", créer un nouvel utilisateur avec le bouton "Add" ( indiquer uniquement un nom d'utilisateur et valider ) :

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-6_17-9-43.png

À ce stade, l'utilisateur de supervision "shinken" a bien été créé.

Création de la clé API

Sur l'interface de configuration, se rendre dans "Datacenter" puis dans "API Tokens" :

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-6_17-14-22.png

Dans le menu "API Tokens", créer une nouvelle clé avec le bouton "Add" ( indiquer uniquement un nom à la clé et valider ) :

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-6_17-16-54.png

La clé API ne s'affiche qu'une seule fois, à la création de celle-ci. Il faut la stocker en lieu sûr avant de continuer.

À ce stade, la clé API "SUP-SHINKEN" a bien été créée.

Gestion des droits d'accès aux ressources

Sur l'interface de configuration, se rendre dans "Datacenter" puis dans "Permissions" :

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-7_9-36-16.png

Dans le menu "Permission", créer une première règle avec le bouton "Add" en sélectionnant "User Permission" et indiquer :

Path : /
User : shinken@pam
Role : PVEAuditor

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-7_9-41-31.png

Dans le menu "Permission", créer une seconde règle avec le bouton "Add" en sélectionnant "API Token Permission" et indiquer :

Path : /
User : shinken@pam!PVE-SHK
Role : PVEAuditor

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-7_9-44-42.png

A ce stade, la configuration des permission est terminée.

La configuration sur l'interface de configuration Proxmox est terminé. Le noeud est prêt à être supervisé.

Côté interface de configuration

Modèle d'hôtes proxmox-ve-by-APIbaseshinken

Nom

Modifiable sur

Unité

Défaut

Valeur par défaut à l'installation du pack

Description

PROXMOX-VE-BY-API__NODE-NAME

l'Hôte

( Onglet Données )

--

$HOSTNAME$

$HOSTNAME$

Le nom du nœud Proxmox supervisé. Il faut utiliser le nom du nœud correspondant à l'adresse IP de l'hôte :

exemple-shinken-proxmox-cluster01 : 172.17.0.14
exemple-shinken-proxmox-cluster01 : 172.17.0.15

Shinken Entreprise V02.08.02 > Mise en place du Pack proxmox-ve-by-API__shinken > image-2026-7-7_10-11-1.png

Si l'adresse IP de l'hôte Shinken est 172.17.0.14, alors PROXMOX-VE-BY-API__NODE-NAME doit être exemple-shinken-proxmox-cluster01.

PROXMOX-VE-BY-API__PORT

l'Hôte

( Onglet Données )

--

8006

8006

Le port utilisé pour accéder à l'API. Par défaut, il s'agit du même port que celui de l'interface de configuration et de gestion Proxmox.

PROXMOX-VE-BY-API__SSL__USE-SSL

l'Hôte

( Onglet Données )

--

True

True

Le mode de gestion SSL :

True : vérification activée avec les autorités de certification connues du système
False : vérification des certificats désactivée
/chemin/vers/cert : vérification du certificat pour une autorité de certification spécifique

PROXMOX-VE-BY-API__TOKEN

l'Hôte

( Onglet Données )

--

shinken:secret

shinken:secret

Combinaison du nom de la clé API et de la clé API.

TOKEN-API-NAME:API-KEY
- Exemple : SUP-SHINKEN:d2abf83e-da98-4583-bf4b-f3e7e292dadd

PROXMOX-VE-BY-API__USER

l'Hôte

( Onglet Données )

--

shinken@pve

shinken@pve

Nom de l'utilisateur Proxmox à utiliser pour la connexion.

Désinstaller le pack avec "uninstall.sh"

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

cd PACK__proxmox-ve-by-API__shinken__V01.00.00__Linux ./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 [ proxmox-ve-by-API__shinken V01.00.00 ]
==========================================================

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

        => Deleting pack monitoring definition folder
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/proxmox-ve-by-API__shinken

        => Deleting pack monitoring definition file
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/packs/proxmox-ve-by-API__shinken.pack

        => Deleting pack monitoring globaldata folder
              - Path : /etc/shinken-user/source-data/source-data-shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken

        => Deleting shinken pack globaldata folder
              - Path : /etc/shinken/resource.d/shinken-additional-packs-import/global-data/proxmox-ve-by-API__shinken/


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

        => Deleting probes
              - Path : /var/lib/shinken-user/libexec/shinken-additional-packs/proxmox-ve-by-API__shinken


==========================================================
PACK [ proxmox-ve-by-API__shinken V01.00.00 ] SUCCESSFULLY UNINSTALLED
==========================================================

À noter : vous devrez retirer les éléments importés dans le Synchronizer ( modèles d'hôtes, checks, ... ) via les actions de masse.

Contexte

L'installation du pack sur l'infrastructure Shinken

Installation de dépendance : VENV__plugins-packs__shinken

Mise en place du pack avec l'installeur "install.sh" ( sur Poller / Synchronizer )

Commun à tout Poller / Synchronizer

Sur le Synchronizer

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é

Extraire le pack

Les sondes ( mises en place )

Sur le Synchronizer

Comment configurer la connexion API ?

Côté client ( Proxmox supervisé )

Création de l'utilisateur

Création de la clé API

Gestion des droits d'accès aux ressources

Côté interface de configuration

Modèle d'hôtes proxmox-ve-by-API__base__shinken

Désinstaller le pack avec "uninstall.sh"

Installation de dépendance : VENVplugins-packsshinken

Modèle d'hôtes proxmox-ve-by-APIbaseshinken