Détails techniques sur le fonctionnement de l’agent macOS

Prérequis et installation de l’agent

Prérequis

Les prérequis nécessaires à l’installation de l’agent varient en fonction de la version de l’OS à superviser et par extension de la version de python système installée.

Pour les versions de macOS inférieures à 12.3, l’installation de l’agent Python2 (version installée par défaut sur le système) est à prioriser, ce qui n’engendre aucun prérequis supplémentaire à prendre en compte.

Cela diffère pour l’agent Python3, qui nécessite la vérification des trois éléments suivants en amont de son installation :

  • La machine doit disposer d’une installation de Xcode Command Line Tools, version allégée de Xcode package, qui permet en partie d’étendre les fonctionnalités liées à l’exécution de module Python. L’absence de ce prérequis, entrainera la génération du message d’erreur xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun, qui peut se résoudre en exécutant xcode-select --install.
  • Une machine ayant un processeur Mac M1 ou M2, doit disposer du programme Rosetta 2, afin d’être compatible avec notre agent macOS. Cette installation passe par l’exécution de la commande softwareupdate --install-rosetta puis l’acceptation d’un accord de Licence. A des fins d’automatisation, la commande softwareupdate --install-rosetta --agree-to-license permet d’outrepasser l’acceptation de cet accord.
  • Concernant la gestion des dépendances liées aux modules Python3, celle-ci est automatique depuis la version 4.12 de l’agent. L’apparition d’une erreur ModuleNotFoundError: No module named 'requests' signifie que celle-ci n’a pas pu aboutir correctement, et nécessite dans ce cas de suivre cette procédure.

Installation

L’agent macOS se présente sous la forme d’un package macOS classique (.pkg).

L’installation de l’agent macOS sur les actifs se fait via l’exécution d’une commande d’installation à récupérer depuis l’interface Cyberwatch, via le formulaire de création d’un agent macOS. Cette commande d’installation embarque les paramètres sélectionnés dans Cyberwatch pour son installation comme par exemple : les groupes, l’URL de l’instance Cyberwatch…

L’installation de l’agent sur un système macOS passe par les étapes suivantes :

  • configuration du dépôt de l’actif cible afin qu’il ait connaissance du paquet ;
  • installation du paquet via le gestionnaire de l’actif, récupéré depuis le dépôt hébergé sur le serveur Cyberwatch ;
  • enregistrement de l’agent sur le serveur Cyberwatch à l’aide de la méthode register de l’agent ;
  • suppression du package d’installation.

De façon unitaire, l’installation de l’agent macOS peut se faire via copier/coller de la commande d’installation proposée par Cyberwatch directement sur l’actif à superviser. Pour toute industrialisation du déploiement, il est possible d’automatiser l’installation de l’agent sur les actifs macOS à l’aide d’une solution permettant l’exécution de commande sur un ensemble d’actifs (e.g. Ansible).

Désinstallation de l’agent

La désinstallation complète d’un agent macOS s’effectue via l’exécution des commandes suivantes :

sudo launchctl unload -w /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist
sudo rm -rf /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist
sudo rm -rf /Library/Cyberwatch
sudo rm -rf /var/log/cyberwatch-agent
sudo rm -rf /usr/local/bin/cyberwatch-agent
sudo rm -rf /etc/cyberwatch-agent
sudo pkgutil --forget fr.cyberwatch.agent.pkg

Fonctionnement de l’agent

Sur les systèmes macOS, l’agent fonctionne à l’aide d’un service qui exécute toutes les cinq minutes le package cyberwatch-agent. Ces deux fichiers sont respectivement présents dans les répertoires /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist, symboliquement référencé dans /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist et /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py, symboliquement référencé dans /usr/local/bin/cyberwatch-agent.

Voici les fichiers relatifs au fonctionnement de l’agent Cyberwatch créés sur le système lors de l’installation :

  • /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist daemons lancé toutes les 5 minutes ;
  • /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py fichier python d’exécution de l’agent Cyberwatch ;
  • /etc/cyberwatch-agent/agent.conf fichier de configuration de l’agent ;
  • le répertoire /var/log/cyberwatch-agent/ contenant les fichiers agent.log.*.

L’exécution de l’agent entraîne simplement une communication avec l’API de l’instance Cyberwatch qui répondra avec les éventuelles tâches à réaliser sur l’actif en question.

Mises à jour de l’agent

Les changements de l’agent sont répertoriés dans l’historique des versions de l’agent Cyberwatch.

Lorsque Cyberwatch publie une nouvelle version de l’agent macOS, celle-ci est mise à disposition sur le repository de l’instance on premise et est donc à disposition des actifs sur lesquels le dépôt a été configuré lors de l’installation. Il suffit donc d’exécuter à nouveau les commandes d’installation disponibles depuis le formulaire de création d’un agent macOS.

Gérer manuellement l’installation de la dépendance requests

Malgré la gestion automatique des dépendances lors du processus d’installation, il est possible que pip3 ne parvienne pas à télécharger le module requests depuis PyPI· Cela peut être causé par un blocage de flux, un échec de la vérification du certificat de PyPI… Et se traduit par l’apparition du code d’erreur ModuleNotFoundError: No module named 'requests' lors de l’installation.

Dans ce cas, il suffit d’effectuer manuellement l’installation de ce module en utilisateur root (afin que le module soit chargé pour l’utilisateur exécutant l’agent), puis de relancer la commande d’enregistrement :

sudo su -
pip3 install requests
sudo cyberwatch-agent register --access-key-id '' --secret-access-key '' --api-url '' --allow_selfsigned true --groups ','

Retour en haut