Création de plugins OCS inventory

Intro


Vous avez un besoin spécifique et souhaitez remonter des informations sur votre serveur OCS inventory. Malheureusement, il n'y a pas de plugins existants pour cela ?
Nous allons voir comment faire

  • Création d'un plugin OCS inventory
  • Mise en place de ce plugin
  • Déploiement du plugin sur les postes
  • Fonctionnement de l'agent
  • Vérification des informations
  • Debug

Attention il y a des différences entre le plugin d'exemple et ce que j'ai fait. Adapté au besoin, le plus important, c'est d'indiquer le nom de votre plugin partout en MAJ quand c'est nécessaire, puis de faire un script qui renvoie les informations à OCS

Création d'un plugin OCS inventory


Pour commencer, récupérer le plugin d'exemple :

https://github.com/PluginsOCSInventory-NG/example

Maintenant définissez vos critères.
Les informations retournées par le plugin seront stocker en base, il faut donc savoir combien de colonnes seront nécessaires

  • Definisez le nombre de colonnes souhaitez
    • Cela dépend de ce que votre script remontra. Exemple: si votre plugin affiche la liste des utilisateurs vous n'aurez besoin que d'une colonne, mais si vous souhaitez afficher s'il est admin il en faudra deux
  • Choisir un nom et le garder à vie ou pas

J'ai pris l'exemple de mon plugin sur GIT :
https://github.com/Yoyox78/OCS-Inventory-Plugin-DCUState

Chaque occurence contenant Example ou exemple sera à remplacer par Dcustate ou dcustate dans mon cas.
Dans votre cas, il faudra mettre le nom que vous avez choisi pour votre plugin, je ne détaille que les parties à modifier des fichiers

APACHE

Ce dossier sert lors de l’enregistrement sur le serveur de communication

MAP.pm

C’est le fichier de liaison entre le serveur de communication et la base de données

Dans mon cas j’ai 4 colonnes

# Lorsque vous modifiez cette ligne pensez à mettre la première lettre en majuscule (Dcustate dans mon cas), sinon ça ne fonctionnera pas
package Apache::Ocsinventory::Plugins::Dcustate::Map;

# Indiquez le nom de votre script
$DATA_MAP{dcustate} = {

# Indiquez quel champ servira pour l’ordre de rangement, dans mon cas c’est le champ date
sortBy => 'DATE',

# Dans cette partie, vous devez indiquer vos champs, attention le dernier champ n'a pas de (,) à la fin
   fields => {
      DATE => {},
      TYPE => {},
      NAME => {},
      URGENCY => {}
    }

dcustate.conf

Il indique au serveur de charger le fichier Map.pm du plugin

Lorsque vous modifiez cette ligne pensez à mettre la première lettre en majuscules (Dcustate dans mon cas), sinon ça ne fonctionnera pas
PerlModule Apache::Ocsinventory::Plugins::Dcustate::Map;

cd_dcustate

La convention de nommage exige que le nom du fichier commence par "cd_" ("cd" signifie "computer details").

# Donner le nom du plugin ou un petit détail sur sont utilitée.
print_item_header("dcustate");

# Donner le nom du plugin
$form_name = "dcustate";

# Comme précédemment, mettre les noms des champs choisis ainsi que des descriptions qui apparaîtront en tant qu'entête des colonnes
$list_fields = array(
                    'Date de vérification' => 'DATE',
                    'Type de périphérique' => 'TYPE',
                    'Nom du package' => 'NAME',
                    'Niveau de criticitée' => 'URGENCY'
                    );

language

  • fr_FR
    • fr_FR.txt
  • en_GB
    • en_GB.txt

Dans les deux fichiers, indiquer un numéro choisi et le nom du plugin

Attention à vérifier les numéros utilisés par les autres plugins OCS pour ne pas avoir de doublons :
https://plugins.ocsinventory-ng.org/

Pour cela vérifier dans le fichier hook.xml la ligne suivante de chaque plugin utilisé
<translation>50300</translation>

.travis.yml

Aucune modification à faire dans ce fichier si vous l'avez

hook.xml

Dans cette partie vous indiquez les langues que vous avez créées, (création des dossiers et fichiers dans language)

<value>en_GB</value>
<value>fr_FR</value>

Indiquez le nom donné plus haut pour le fichier et dossier cd_ (mettre le nom du plugin)
<identifier>cd_wustate</identifier>

Indiquez le nombre présent dans les fichiers language
<translation>50300</translation>

Cette partie permet d'indiquer dans quel onglet de l'ordinateur il faut ajouter ce plugin
Mettez tout dans other (pour garder tous les plugins au même endroit)
D’autres possibilités sont envisageables : https://github.com/PluginsOCSInventory-NG/example/blob/master/hook.xml

<category>other</category>

Indiquez le nom du plugin
<available>dcustate</available>

infos.json

Stock des informations générales sur le plugin, comme le nom, l'auteur, la version, etc. Elles seront affichées sur https://plugins.ocsinventory-ng.org/.
Indiquez votre nom, le nom du plugin, à quoi il sert dans toutes les langues choisies

install.php

Remplissez les lignes suivantes, elles permettront de créer, supprimer et mettre à jour la table en BDD suivant si vous installez, supprimés, ou mettez à jour
Remplacer le nom de mon plugin par le vôtre
function extension_install_dcustate()

Cette partie permet la suppression et création de table

$commonObject -> sqlQuery("DROP TABLE IF EXISTS `dcustate`;");
 "CREATE TABLE `dcustate` (

Indiquez les champs mis dans map.pm et cd_dcustate

`DATE` VARCHAR(255) DEFAULT NULL,
`TYPE` VARCHAR(255) DEFAULT NULL,
`NAME` VARCHAR(255) DEFAULT NULL,
`URGENCY` VARCHAR(255) DEFAULT NULL,

Supprime la base, si elle existe

function extension_delete_dcustate()
$commonObject -> sqlQuery("DROP TABLE IF EXISTS `dcustate`");

Permet la mise à jours de la BDD

function extension_upgrade_dcustate()

preview.png

Faire un joli dessin qui représente votre plugin

agent / Windows

Créez votre script qui ne retournera que les informations souhaitées en XML
Voici un exemple de retour, respectez bien ce que vous avez défini précédemment dans les fichiers
dans notre cas, on retrouve bien

  • DATE
  • TYPE
  • NAME
  • URGENCY
        $xml += "<DCUSTATE>`n"
        $xml += "<DATE>$(Get-Date -Format "dd/MM/yyyy_HH:mm")</DATE>`n"
        $xml += "<TYPE>" + $i.type + "</TYPE>`n"
        $xml += "<NAME>" + $i.name + "</NAME>`n"
        $xml += "<URGENCY>" + $i.urgency + "</URGENCY>`n"
        $xml += "</DCUSTATE>`n"

Finition

Zipper votre dossier complet en .zip

Mise en place du plugin


Sur le serveur, voici les deux dossiers qui contiennent le plugin

  • /usr/share/ocsinventory-reports/ocsreports/extensions/dcustate
  • /etc/ocsinventory-server/perl/Apache/Ocsinventory/Plugins/Dcustate

Transférer le dossier extrait de l’archive sur le serveur OCS via scp ou winscp dans le home de l’utilisateur root
Exemple avec dcustate, à adapter suivant le besoin
Faites ces actions en root

cd /usr/share/ocsinventory-reports/ocsreports/extensions
unzip ~/dcustate.zip
chgrp -R www-data dcustate
  • Allez sur OCS dans la partie extension / extension manager
  • Choisissez le plugin dans la liste puis cliquez sur install
  • Le plugin va apparaître dans la liste
  • Activez-le
  • Déconnectez-vous puis reconnectez-vous à OCS (site web) le plugin devrait être ajouté dans plugin

Retourner sur le serveur en ssh

cd /usr/share/ocsinventory-reports/ocsreports/tools
python3 install_plugin.py

Where is the plugins location [/usr/share/ocsinventory-reports/ocsreports/extensions/](appuyez sur entrée)

[0] => uptime
[3] => winupdate
[4] => dcustate

**(sélectionner le numéro puis entrée) 4 dans notre cas**

The server is installed on the same server ? [y]/n
**(Appuyer sur entrée)**

Where is the server location [/etc/ocsinventory-server]
**(Appuyer sur entrée)**

dcustate been successfully installed ! Don't forget to restart your Apache server

Redémarrer le server apache

systemctl restart apache2

Verifier que le plugin est bien ajouté dans OCS

Allez sur un poste au hasard puis dans other (autre en FR) et cherchez le plugin dcustate, il ne devrait pas contenir de données, car vous n'avez pas encore déployé le plugin sur les postes ou serveurs

Deploiement du plugin sur les postes


Attention avant de deployer le plugin sur tous les postes faite un essai sur un ou deux poste pour vérifier que votre plugin fonctionne

  • Connectez-vous sur l’interface OCS
  • Allez dans Deployment / Build
  • Choisissez Windows / Others / Store file / folder
  • Package Name: dcustate (dans mon cas)
  • Description : voir les MAJ à installer pour DCU
  • Path : C:\Program Files\OCS Inventory Agent\Plugins
  • Cliquez sur choisir un fichier
  • Choisissez le fichier présent dans l’archive / agent
  • En général, c'est un fichier ps1
  • Si vous avez plusieurs fichiers il faudra les zipper (.zip) et choisir l’archive créée
  • Maintenant, allez dans Deployment / activate
  • Cliquez sur le V (vert) à droite de votre package créé précédemment
  • Cliquez sur OK
  • Allez dans All computer
  • Afficher 1000 entrées
  • Cochez la case à côté des titres pour sélectionner tous les ordinateurs
  • Allez tout en bas de la page et cliquez sur Deploy
  • Mass assignment : For selection
  • Use the advanced options of … : NO
  • Cliquez sur Validate
  • Sélectionnez votre package (dcustate dans mon cas)
  • Cliquez sur Add selected package
  • Une barre verte apparaît pour indiquer sur combien de PC votre déploiement a été validé
  • Retourner dans Deployment / Activate
  • Vous verrez le nombre de notifications et d’installations effectuées
  • Si vous souhaitez avoir un graphique, cliquez sur l’icône en forme de graphique bleu à gauche

Fonctionnement de l'agent


L’agent exécute les scripts 1 à 1 qui sont présents dans C:\Program Files\OCS Inventory Agent\Plugins.
Quand il lance les scripts, il met tous les retours affichés dans le terminal, même les retours de commande lors de l'exécution d’exe (faire attention à cela)

Ce fichier est supprimé après l’envoi à OCS, si ce fichier n’est pas valide alors ocs ne le supprime pas, vous pourrez donc le consulter pour voir les erreurs
C:\ProgramData\OCS Inventory NG\Agent\NOMDUSCRIPT.ps1.xml

A savoir :
Si vous lancez des exécutables extérieurs, comme Dell Command Update (DCU) (j’ai eu le problème avec lui)
Dans le script, lancez l’application avec la commande suivante, cela évite qu’OCS ne récupérait les sorties du cmd lors de l'exécution
$null = Invoke-Expression " & '$chemin\dcu-cli.exe' /scan -report=${tempfolder}"

Il faut savoir que tout tourne autour de la BDD de ocs, que ce soit l’envoi de données de votre script ou ce que vous remonte l’interface OCS

Vérification des informations


Une fois les premiers agents déployés
Allez sur l'un des postes ou l'agent a été déployé, other (ou autre en FR) et dans le pluging DCUSTATE vous devriez avoir les informations remontées

Attention les informations ne remontent pas après l'installation du plugin, elle seront remontées au redémarrage du service

Debug


Sur le serveur OCS

Vous pouvez voir les connexions des agents en cours, pour cela entrer la commande suivante :

tail -f /var/log/ocsinventory-server/activity.log | grep 'NOMDELORDINATEUR'

Vous aurez des lignes dont la fin sera du type inventory;u:dcustate, les plugins afficher sont ceux dont le serveur à reçu des informations
Donc si votre plugin n'apparaît pas suivez l'instruction sur le client ci-dessous

Sur le client

Comme indiqué précédemment, vous pouvez consulter les fichiers XML qui n'ont pas été transmis à OCS
C:\ProgramData\OCS Inventory NG\Agent\NOMDUSCRIPT.ps1.xml