.. _`manuel_util`: ****************** Manuel utilisateur ****************** Installation ============ Pré-requis logiciels -------------------- Afin de pouvoir faire fonctionner VigiConf, l'installation préalable des logiciels suivants est requise : * python (>= 2.5), sur la machine où VigiConf est installé * postgresql-server (>= 8.2), éventuellement sur une machine distante Reportez-vous aux manuels de ces différents logiciels pour savoir comment procéder à leur installation sur votre machine. VigiConf requiert également la présence de plusieurs dépendances Python. Ces dépendances seront automatiquement installées en même temps que le paquet de VigiConf. Installation du paquet RPM -------------------------- L'installation de VigiConf se fait en installant simplement le paquet RPM "``vigilo-vigiconf``". La procédure exacte d'installation dépend du gestionnaire de paquets utilisé. Les instructions suivantes décrivent la procédure pour les gestionnaires de paquets RPM les plus fréquemment rencontrés. Installation à l'aide de urpmi: .. sourcecode:: bash urpmi vigilo-vigiconf # sur la machine d'administration urpmi vigilo-vigiconf-local # sur les autres machines de la plate-forme de supervision Installation à l'aide de yum: .. sourcecode:: bash yum install vigilo-vigiconf # sur la machine d'administration yum install vigilo-vigiconf-local # sur les autres machines de la plate-forme de supervision Configuration ============= La configuration de VigiConf comprend deux parties. D'une part, la configuration de l'outil en lui-même. D'autre part, la configuration du parc informatique supervisé par Vigilo (et dont la configuration est gérée par VigiConf). Ce chapitre ne porte que sur la configuration de VigiConf. Pour la documentation sur la configuration du parc informatique supervisé, reportez-vous au chapitre :ref:`confparc`. Par défaut, la configuration de VigiConf se trouve dans :file:`/etc/vigilo/vigiconf/settings.ini`. Vous devrez **impérativement** modifier ce fichier de configuration avant d'utiliser VigiConf. Si vous le souhaitez, vous pouvez également placer les options de configuration communes à tous les modules de Vigilo installés sur la machine dans le fichier :file:`/etc/vigilo/settings.ini`. Ce fichier générique sera chargé en premier au lancement de VigiConf. Ces fichiers sont composés de différentes sections permettant de paramétrer des aspects divers de VigiConf, chacune de ces sections peut contenir un ensemble de valeurs sous la forme ``cle=valeur``. Les lignes commençant par ";" ou "#" sont des commentaires et sont par conséquent ignorées. Le format de ces fichiers peut donc être résumé dans l'extrait suivant: .. sourcecode:: ini # Ceci est un commentaire ; Ceci est également un commentaire [section1] option1=valeur1 ; ... optionN=valeurN ; ... [sectionN] option1=valeur1 ; ... optionN=valeurN Configuration de la base de données ----------------------------------- Connexion ^^^^^^^^^ VigiConf enregistre une partie des informations de la configuration du parc supervisé en base de données. La configuration de la connexion à cette base de données se fait en modifiant la valeur de la clé ``sqlalchemy_url`` sous la section ``[database]``. Cette clé consiste en une :term:`URL` définissant tous les paramètres nécessaires pour pouvoir se connecter à la base de données. Le format de cette URL est le suivant:: sgbd://utilisateur:mot_de_passe@serveur:port/base_de_donnees Le champ ``:port`` est optionnel et peut être omis si vous utilisez le port par défaut d'installation du SGBD choisi. Par exemple, voici la valeur correspondant à une installation mono-poste par défaut de Vigilo:: postgresql://vigilo:vigilo@localhost/vigilo .. warning:: À l'heure actuelle, seul PostgreSQL a fait l'objet de tests intensifs. D'autres SGBD peuvent également fonctionner, mais aucun support ne sera fourni pour ceux-ci. Configuration du dépôt pour le suivi des évolutions --------------------------------------------------- Les modifications apportées à la configuration du parc sont enregistrées dans un dépôt :term:`SVN`, permettant ainsi d'assurer un suivi des modifications et un éventuel retour arrière. La configuration de ce dépôt se fait en utilisant les clés suivantes de la section ``vigiconf``: confdir Dossier contenant un « checkout » (version de travail) du dépôt SVN et dont les modifications seront enregistrées dans le dépôt à chaque utilisation de la commande "``vigiconf deploy``". Cette option doit pointer vers le dossier où la configuration du parc supervisé est sauvegardée. svnusername Nom d'utilisateur pour accéder au dépôt SVN. svnpassword Mot de passe pour accéder au dépôt SVN. svnrepository URL indiquant l'emplacement du dépôt SVN. Il peut s'agir d'une URL pointant vers un dépôt local (``file://``) ou distant (``ssh+svn://``, ``http://``, etc.). Référez-vous à la documentation de Subversion pour les différents protocoles supportés. Autres options de configuration ------------------------------- Les paragraphes qui suivent décrivent les autres options de configuration disponibles dans VigiConf et situées sous la section ``[vigiconf]`` du fichier ``settings.ini``. En règle générale, les valeurs correspondant à une nouvelle installation de VigiConf sont suffisantes et il n'est pas nécessaire de les modifier. Répertoire de travail pour la génération ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ L'option "``libdir``" permet de spécifier l'emplacement du répertoire de travail servant à générer les fichiers de configuration des applications. La valeur définie dans la configuration initiale est :file:`/var/lib/vigilo/vigiconf`. Emplacement final de la configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ La directive "``targetconfdir``" permet d'indiquer le dossier vers lequel les fichiers de configuration finaux seront télé-déployés sur les serveurs de supervision. La valeur définie dans la configuration initiale est :file:`/etc/vigilo/vigiconf`. Les applications dont dépend Vigilo (ex : Nagios) doivent être configurées pour aller chercher leur fichier de configuration dans le sous-dossier "``prod``" de ce dossier. Répertoire des plugins de VigiConf ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ L'option "``pluginsdir``" permet de faciliter l'extension de VigiConf à l'aide de plugins (modules complémentaires). Il s'agit de l'emplacement d'un répertoire qui contiendra des modules Python (eggs) qui seront chargés automatiquement au lancement de VigiConf. Ces modules ont la possibilité d'enregistrer des points d'entrée Python afin d'ajouter de nouvelles fonctionnalités. La valeur de cette option dans la configuration initiale fournie avec VigiConf est :file:`/etc/vigilo/vigiconf/plugins`. Emplacement du verrou ^^^^^^^^^^^^^^^^^^^^^ Afin d'éviter un conflit lorsque plusieurs administrateurs du même parc effectuent un nouveau déploiement de la configuration simultanément, VigiConf acquiert un verrou au démarrage. Ce verrou est automatiquement libéré lors de l'arrêt de VigiConf. La directive "``lockfile``" permet de spécifier l'emplacement du fichier qui correspondra au verrou. Dans la configuration fournie par défaut avec VigiConf, le verrou est enregistré dans :file:`/var/lock/subsys/vigilo-vigiconf/vigiconf.token`. Mode de simulation des opérations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ L'option "``simulate``" est un booléen qui permet d'activer un mode spécial de VigiConf dans lequel les opérations sont simulées et ne sont pas validées. Cette option est destinée uniquement au débogage de l'application lors de la phase de développement et doit être positionnée à "``False``" en production. .. _confparc: Configuration du parc à superviser ================================== La configuration du parc à superviser se fait au travers de fichiers XML. Ces fichiers sont stockés dans le répertoire pointé par l'option "``confdir``" de la section "``vigiconf``" dans le fichier de configuration de VigiConf. Des fichiers d'exemple sont installés en même temps que VigiConf. Ce chapitre présente la structure de la configuration et le contenu des différents fichiers. Fichiers de configuration XML ----------------------------- Afin d'éviter les erreurs de saisie dans les fichiers de configuration de VigiConf, ceux-ci font systématiquement l'objet d'une validation à l'aide de schémas XML. Ces schémas sont stockés dans: :file:`/usr/lib{arch}/python{version}/site-packages/vigilo/vigiconf/validation/xsd/` Par exemple, pour une installation standard de Python 2.5 sur une machine équipée d'une architecture x86: :file:`/usr/lib/python2.5/site-packages/vigilo/vigiconf/validation/xsd/` Dans la suite de ce document, on considère qu'un fichier :samp:`{type}.xml` de la configuration de VigiConf est valide s'il respecte le schéma défini dans le fichier :samp:`{type}.xsd` situé dans ce répertoire correspondant au type d'objet manipulé. Pour le reste des explications de ce chapitre, tous les emplacements de fichiers ou dossiers indiqués sont relatifs au dossier de configuration du parc (par défaut, :file:`/etc/vigilo/vigiconf/conf.d/`) Configuration des hôtes ----------------------- Le dossier "``hosts``" contient les fichiers de définition des hôtes supervisés du parc. Tous les fichiers XML de ce dossier sont analysés et doivent contenir la définition d'un ou plusieurs hôtes. La balise à la racine de ce document se nomme "``hosts``" et peut contenir un ou plusieurs blocs "``host``", correspondant chacun à la définition d'un hôte. Le fragment de code suivant rappelle la structure générale du fichier: .. sourcecode:: xml ... ... ... Définition d'un hôte ^^^^^^^^^^^^^^^^^^^^ Un hôte est défini à l'aide d'une balise *host* ayant la forme suivante: .. sourcecode:: xml ... Un bloc de données *host* possède les attributs suivants : name [requis] Nom de l'hôte. Il peut s'agir d'un nom entièrement qualifié (FQDN) ou simplement d'un nom court permettant d'identifier l'équipement au sein du parc. address [optionnel] Adresse permettant de communiquer avec l'hôte. Il peut s'agir d'une adresse IP (v4 ou v6) ou d'un nom de domaine entièrement qualifié (FQDN). Si cet attribut est omis, la valeur de l'attribut *name* est utilisée. ventilation [optionnel] Nom du groupe de supervision dans lequel cet hôte doit être placé (ventilé). En général, il n'est pas nécessaire de spécifier cet attribut. VigiConf tente de le déduire automatiquement à partir des noms des groupes auxquels l'hôte est rattaché. Cet attribut permet essentiellement de résoudre les conflits entre les groupes. Il peut également être utilisé pour affecter l'hôte à un groupe de supervision qui n'a aucune relation avec les groupes métier. La balise *host* peut contenir les balises suivantes : - ``class`` (0 ou plus) - ``template`` (0 ou plus) - ``attribute`` (0 ou plus) - ``nagios`` (0 ou 1) - ``test`` (0 ou plus) - ``tag`` (0 ou plus) - ``group`` (1 ou plus) Balise "``class``" ^^^^^^^^^^^^^^^^^^ Syntaxe: .. sourcecode:: xml nom de la classe Indique la ou les classes d'équipements auxquelles l'hôte appartient. En fonction de ces classes, des tests spécifiques peuvent être disponibles afin d'obtenir des informations plus précises sur l'état de l'équipement. Balise "``template``" ^^^^^^^^^^^^^^^^^^^^^ Syntaxe: .. sourcecode:: xml Précise le nom du modèle d'hôtes duquel cet hôte hérite une partie de ses propriétés. L'utilisation de l'héritage est pratique lorsque votre parc est composé d'éléments (serveurs, routeurs, etc.) homogènes. Vous pouvez alors définir un modèle (template) pour chaque type d'équipement avec tous les tests associés et créer ensuite simplement une définition d'hôte pour chaque équipement. Cette balise peut être utilisée à plusieurs reprises. Les paramètres du dernier modèle chargé écrasent ceux des modèles précédents. Les valeurs définies au niveau d'un hôte écrase toujours les valeurs définies au niveau d'un modèle hérité (en particulier, les paramètres des tests). .. note:: Pour être utilisable via cette balise, le modèle doit avoir été défini à l'aide de la balise *hosttemplate* (voir :ref:`hosttemplate`). .. warning:: En cas de conflits liés aux dépendances des modèles, il se peut que les modèles soient réordonnés (un message d'avertissement est alors émis par VigiConf lors du déploiement). Dans ce cas, l'ordre d'application des paramètres peut être légèrement différent de l'ordre d'affectation des modèles dans le fichier de configuration. Balise "``attribute``" ^^^^^^^^^^^^^^^^^^^^^^ Syntaxes: .. sourcecode:: xml valeur de l'attribut valeur 1 valeur 2 Cette balise permet de fixer certains des attributs de l'hôte, comme par exemple le nombre de processeurs présents sur la machine. En général, ces informations sont extraites automatiquement des équipements par une interrogation SNMP (voir à ce sujet le chapitre « :ref:`discover` »). Les noms d'attributs utilisables dépendent des tests de supervision installés avec VigiConf. Par défaut, les attributs suivants sont disponibles : - "``collectorTimeout``" : délai d'attente utilisé lors de la récupération des données SNMP de l'hôte ; - "``cpulist``" : la liste des identifiants des processeurs sur l'équipement ; - "``fans``" : la liste des identifiants des ventilateurs sur l'équipement ; - "``snmpCommunity``" : la communauté pour l'accès SNMP à l'équipement ; - "``snmpPort``" : le port SNMP à utiliser (par défaut, le port 161 est utilisé) ; - "``snmpVersion``" : la version SNMP à utiliser (par défaut, la version 2 est utilisée) ; - "``tempsensors``" : la liste des noms des sondes de température présentes sur l'équipement. .. only:: enterprise La version enterprise de Vigilo contient les attributs supplémentaires suivants : - "``oxe_login``": le nom d'utilisateur permettant de se connecter à l'hôte en utilisant le protocole Telnet; - "``oxe_password``": le mot de passe allant de paire avec le nom d'utilisateur permettant de se connecter à l'hôte en utilisant le protocole Telnet ; - "``QOS_mainClassName``": la liste des classes de services utilisées pour la qualité de service. Pour chaque classe, il est possible de définir le libellé affiché dans les graphes, en utilisant la syntaxe "nom_de_la_classe|libellé". - "``QOS_subClassName``": la liste des sous-classes de services utilisées pour la qualité de service. Pour chaque sous-classe, il est possible de définir le libellé affiché dans les graphes, en utilisant la syntaxe "nom_de_la_sous_classe|libellé". - "``timeout``": délai d'attente utilisé lors des connexions Telnet à l'hôte. .. _`configuration des tests d'un hôte`: Balise "``test``" ^^^^^^^^^^^^^^^^^ Syntaxe: .. sourcecode:: xml valeur argument 1 valeur argument 2 ... valeur argument n valeur directive 1 ... valeur directive n La balise ``test`` permet d'ajouter un test de supervision à l'hôte. Elle possède un attribut ``name`` obligatoire qui désigne le test de supervision à appliquer (par exemple : "``CPU``" pour superviser l'état du processeur d'un équipement). Un test accepte généralement zéro, un ou plusieurs arguments, qui doivent être passés dans l'ordre lors de la déclaration du test, à l'aide de la balise ``arg``. Chaque argument dispose d'un nom (attribut ``name``) et d'une valeur (ou liste de valeurs). Pour spécifier une liste de valeurs pour un argument, la sous-balise ``item`` doit être utilisée, comme dans l'extrait suivant : .. sourcecode:: xml whitelist 127.0.0.1 localhost 192.168.0.0/24 Chaque argument possède un type (spécifié dans la documentation du test). Les types reconnus sont : - les chaînes de caractères ; - les nombres entiers ; - les nombres relatifs (flottants) ; - les booléens (utiliser la valeur ``1``, ``true``, ``on`` ou ``yes`` pour la valeur ``True`` ou bien ``0``, ``false``, ``off`` ou ``no`` pour la valeur ``False``). Vous pouvez également, de façon optionnelle, définir des paramètres spécifiques pour la supervision à l'aide de la balise ``nagios``, qui contiendra une ou plusieurs directives adressées au moteur de supervision Nagios. Voir la section ci-dessous pour plus d'informations. .. note:: Si le même argument est défini deux fois, seule la dernière valeur sera utilisée. .. _nagiostag: Balise "``nagios``" ^^^^^^^^^^^^^^^^^^^ Un bloc de données ``nagios`` contient des blocs ``directive`` dont l'attribut ``name`` appartient à la liste des directives "``host``" de Nagios. La documentation sur ces directives est disponible dans `la documentation Nagios `_. Syntaxe: .. sourcecode:: xml 5 10 1 Toutes les directives proposées par Nagios sont utilisables ici. Néanmoins, un mauvais réglage des directives peut dégrader sérieusement les performances de la supervision, voire entrainer un dysfonctionnement. L'utilisation des directives est donc à laisser à des utilisateurs avertis. Un bloc ``nagios`` peut se trouver au sein d'un bloc ``host``/``hosttemplate`` ou d'un bloc ``test``. Si la même directive est défini deux fois, la dernière valeur est celle qui sera utilisée. Balise "``tag``" ^^^^^^^^^^^^^^^^ Syntaxe: .. sourcecode:: xml valeur La balise ``tag`` permet d'affecter une étiquette à un hôte ou un service. L'attribut ``name`` permet de préciser le nom de l'étiquette à ajouter. Il doit correspondre au nom d'une image (**privée de son extension**) à afficher dans VigiMap. Cette image doit se trouver dans :samp:`/etc/vigilo/vigimap/public/images/tags`. L'attribut ``service`` permet, quant à lui, d'indiquer le nom du service auquel cette étiquette sera affectée. Utilisez la valeur "``host``" si l'étiquette doit porter sur l'hôte en lui-même et non pas sur l'un de ses services. Enfin, la valeur de l'étiquette est facultative et fait office de méta-donnée. Exemple, pour associer à un hôte l'étiquette de MCO (l'image ``mco.png`` est fournie dans toute installation standard de Vigilo): .. sourcecode:: xml Balise "``group``" ^^^^^^^^^^^^^^^^^^ Syntaxe: .. sourcecode:: xml /Chemin complet/vers le/Groupe Nom de groupe La balise ``group`` permet d'indiquer les groupes métiers auxquels cet équipement appartient. Les groupes sont organisés de manière hiérarchique (sous la forme d'un arbre). La première forme (chemin absolu) permet de se déplacer dans cette hiérarchie en donnant le chemin complet jusqu'au groupe, de la racine de l'arbre vers les feuilles. Chaque élément du chemin est précédé du symbole "``/``". Si le nom de l'élément contient un "``/``" ou un "``\``", vous devez le faire précéder du caractère d'échappement "``\``". Ainsi, l'élément "``Serveurs Linux/Unix``" sera écrit dans les chemins comme "``Serveurs Linux\/Unix``". La seconde forme (chemin relatif) permet d'ajouter l'équipement à tous les groupes dont le nom vaut celui indiqué, quelque soit leur position dans l'arbre. Il n'est pas possible de préciser plusieurs éléments (par exemple "``A/B``") lorsque cette forme est utilisée. Les règles d'échappement de la première forme s'appliquent également ici. .. note:: Les groupes sont utilisés pour décider de la ventilation des équipements sur les différents groupes de supervision. Une fois tous les groupes exprimés sous la forme d'un chemin absolu, VigiConf suppose que le premier élément du chemin correspond au groupe à utiliser pour la ventilation. En cas de conflit, ou pour placer l'équipement dans un autre groupe de ventilation que celui déterminé automatiquement, vous devez utiliser l'attribut *ventilation* de la balise *host* afin de spécifier manuellement le groupe de ventilation à utiliser. Remarques ^^^^^^^^^ De même que pour les tests, l'hôte peut disposer de directives de configuration spécifiques destinées à Nagios. Celles-ci seront groupées sous une balise ``nagios`` (voir également la documentation concernant la balise ``test`` ci-dessus). Chaque hôte hérite implicitement d'un modèle appelé "``default``". Toutes les directives définies dans le modèle "``default``" sont donc appliquées à la configuration des différents hôtes, et ce même si ces hôtes n'indiquent pas explicitement qu'ils utilisent ce modèle, via la balise ``