Le fichier de configuration

Une Constellation est décrite en un seul fichier : le fichier de configuration Constellation.

Ce fichier se nomme “Constellation.Server.exe.config” et se trouve dans le répertoire d’installation du serveur (par défaut dans “Program Files\Constellation Plateform\Server« ).

Vous pouvez le modifier de différente manière :

• En éditant ce fichier directement sur le serveur (avec un éditeur de texte type Notepad)
• Via la Console Constellation (sur la page Configuration Editor)
• Via Visual Studio
• Via l’API de Management Constellation

Le fichier contient une balise globale “configuration” dans laquelle vous trouverez 4 sections :

• configSections : réservé au moteur .NET
• constellation : la section de configuration Constellation (anciennement nommée ‘constellationSection’)
• startup : réservé au moteur .NET
• runtime : réservé au moteur .NET

Vous ne devez en aucun cas modifier les sections réservées au moteur .NET sans savoir exactement ce que vous faites.

La section de “constellation” se décompose de la façon suivante :

• listenUris : définit la configuration des URI d’écoute du serveur Constellation
• fileServer : définit la configuration du serveur Web statique utilisé pour l’hébergement de la Console Constellation
• recoveryOptions : définit les options de récupération des packages
• sentinels : définit la configuration des sentinelles (et des packages) de votre Constellation
• settingsGroups : définit la configuration des groupes de “settings”
• credentials : définit la configuration des credentials pour l’accès à votre Constellation

A chaque modification vous devez recharger la configuration soit via le hub de contrôle ou la Console Constellation (bouton “Reload Configuration”) ou soit en redémarrant le service Constellation Server.

Section “listenUris”

Cette section permet de définir les URI sur lesquels le serveur Constellation doit écouter.

Ici le serveur répondra sur le port HTTP 8088 quelque soit le host (nom DNS ou adresse IP) car nous utilisons le wildcard “+” (pour plus d’information, lisez ceci).

Vous pouvez configurer autant de “listenUri” que vous souhaitez. Par exemple :

Ici, le serveur Constellation répondra :

• Aux requêtes sur le port HTTP 8088
• Aux requêtes sur le port HTTP 8888 où le host est “constellation.mydomain.net” (en clair une requête http://<ip>:8888  ne fonctionnera pas)
• Aux requêtes sur le port HTTP 8080 quelque soit le host mais dont le path doit forcement démarrer par “/constellation/”
• Aux requêtes sur le port HTTPS 8089 en utilisant un cryptage SSL (plus d’information)

Pour prendre en compte les modifications de cette section vous devez redémarrer le service Constellation.

Section “fileServer”

Cette section permet d’activer et configurer le “fileServer” de Constellation pour héberger des fichiers statiques (pages HTML, fichiers CSS, JS, images, etc..).

Cela sert principalement pour “auto-héberger”  la Console Constellation par le serveur Constellation lui-même.

En effet, la Console Constellation n’est ni plus ni moins qu’une application Web client-side, c’est à dire une série de pages HTML avec scripts JS et fichiers CSS/Image. Libre à vous de l’héberger sur vos serveurs Web mais afin de limiter les prérequis, le serveur Constellation peut lui-même héberger la console grâce au “fileServer” intégré.

La section “fileServer” ne contient que quatre attributs :

• “enable” : indique si le serveur de fichier statique sur le serveur Constellation doit être activé (true ou false).
• “path” : le répertoire d’écoute (préfixé par la listenUri).
• “localhostOnly” : indique si le fileServer répond seulement aux requêtes “locales” ou à toutes les requêtes (true ou false).
• “physicalPath” : le répertoire physique

Dans l’exemple ci-dessus, le serveur de fichier est activé mais ne répondra qu’aux requêtes locales. Le serveur délivra les fichiers dans “D:\App\Constellation\Console” sur l’URL “<listen_URI_du_serveur_Constellation>/WebConsole” par exemple http://localhost:8088/WebConsole ou http://127.0.0.1:8088/WebConsole en partant du principe qu’il existe une listenUri “http://+:8088”.

Comme pour la section précédente (listenUris), il faut obligatoirement redémarrer le service Constellation Server pour prendre en compte ces modifications.

Section “recoveryOptions”

Les options de récupération (recoveryOptions) permettent de définir le comportement de la sentinelle en cas d’arrêt brutale de l’exécution d’un package (crash du package).

Chaque package peut avoir ses propres options de récupération mais cette section permet de définir les options “globales”, c’est à dire appliqué par défaut pour chaque package de la Constellation.

Les options de récupérations se résume en quatre propriétés :

• “restartAfterFailure” (true par défaut) : définit si la sentinelle doit redémarrer un package en cas de crash de ce dernier
• “numberOfRetry” (3 par défaut) : définit le nombre maximal de tentative de redémarrage d’un package
• “restCounterAfterMinutes” (15 par défaut) : définit la période (en minute) au delà de laquelle le compteur d’erreur est réinitialisé
• “restartPackageAfterSeconds” (30 par défaut) : définit le délai d’attente avant de redémarrer un package suite à un crash

Dans la configuration par défaut, si un package “crash” il est automatiquement redémarré 30 secondes après son crash dans la limite de 3 tentatives sachant qu’au bout de 15 minutes, le compteur de tentative est réinitialisé à 0.

Section “sentinels”

Dans cette section vous allez déclarer vos sentinelles (virtuelles ou non) dans lesquelles vous déclarerez les packages (virtuels ou non) qui eux même déclarons leurs settings et leurs groupes.

En clair, c’est cette section qui décrit votre “Constellation”.

Prenez l’exemple de la Constellation suivante :

Voici ce qu’elle décrit :

• Nous avons deux sentinelles “SENTINEL-NAME-DEMO” et “ANOTHER-SENTINEL »
• Les deux sentinelles utilisent le même credential “Standard” (déclaré dans la section credentials).
• Sur la première sentinelle est déployée deux packages :
  • “HWMonitor” : le package utilise le même credential que sa sentinelle (car non défini explicitement donc hérite du credential de sa sentinelle)
  • “DemoPackage” : ce package utilise le credential nommé “ControlHubAccess” et déclare les settings suivants :
    • IntSetting et StringSetting associés à des valeurs (numérique et string)
    • SettingXml et SettingJson associés à des contenus (XML et JSON)
    • Importe le groupes de settings nommé “GroupSettingsDemo” défini dans la section “settingsGroups”

Les sentinelles

Pour entrer dans le détail, vous allez déclarer dans la section “sentinels”, les sentinelles de votre Constellation que ce soit des sentinelles réelles ou virtuelles.

Pour cela, vous utiliser la balise “<sentinel>” qui comporte les attributs suivants :

• “name” : le nom de la sentinelle (obligatoire et unique)
• “credential” : le nom du credential (déclaré dans la section credentials) à utiliser pour l’authentification (obligatoire)

La section “<sentinel>” contient une collection de “<package>” rangée dans la balise “<packages>”. Chaque package peut-être réel ou virtuel.

Les packages

L’élément “<package>” contient les attributs suivants :

• “name”: le nom de l’instance du package (obligatoire et unique)
• “filename” (facultatif) : le nom du fichier du package à utiliser dans le repository (plus d’info)
• “enable” (facultatif, par defaut true) : indique si le package est activé ou désactivé
• “credential” (facultatif, utilise par défaut du credential de sa sentinelle) : spécifie le credential que le package va utiliser pour s’authentifier sur le serveur Constellation
• “autostart” (facultatif, par defaut true) : indique si le package doit automatiquement démarrer sur sa sentinelle ou juste être déployé (et donc démarré manuellement)

Un package peut contenir ensuite trois sous sections :

• “recoveryOptions” : définit les options de récupération du package (par défaut, la sentinelle utilise les options globales)
• “settings” : définit les paramètres/variables de configuration d’un package
• “groups” : définit les groupes dans lesquels le package sera abonné

Les options de récupérations

La balise est la même que la section globale.

Par exemple si on ne souhaite pas que le package redémarre en cas de crash, on peut écrire :

Les paramètres de configuration

Chaque package peut définir des paramètres de configuration au niveau du serveur Constellation. Cela vous permet de changer ces paramètres directement depuis la Constellation qui se chargera de redescendre ces paramètres sur vos packages.

Il y a deux types de settings :

• Les “Setting Value” : il s’agit d’un couple clé/value
• Les “Setting Content”  : il s’agit d’un setting dont la valeur peut être un XML ou JSON

Dans l’exemple plus haut, le package “DemoPackage” contient à la fois des settings de type “value” et de type “content”.

Vous pouvez également regrouper des settings dans les groupes afin de les partager entre plusieurs package grâce aux settingsGroups. Toujours dans l’exemple précédent, le package “DemoPackage” inclut le groupe “GroupSettingsDemo”, un groupe de settings décrit dans la section ”settingsGroups”.

Pour plus d’information sur les settings, consultez l’article sur l’exploitation des settings avec l’API .NET.

Les groupes

Comme vous le savez, un message peut être envoyé à un groupe dans lequel des packages réels ou virtuels peuvent s’abonner.

Il y a deux manières d’abonner un package à un groupe :

• Soit par le package lui même en invoquant la méthode “SubscribeToMessage” via les différentes API Constellation misent à disposition
• Soit dans la configuration du package au niveau du serveur Constellation

Cela vous permet d’avoir la main sur l’appartenance des packages aux groupes que vous pouvez administrer sans devoir modifier vos packages (virtuels ou non).

La section “groups” sur un package permet de définir ces liens. Par exemple :

Ici le package “MonPackage” est abonné aux groupes “MonGroupeA” et “MonGroupeB”. En cas de modification des affectations aux groupes, il faudra redémarrer le package soit via vos applications en utilisant les API du hub de contrôle soit depuis la Console Constellation.

Section “settingsGroups”

Vous pouvez grouper des settings (Content ou Value) dans des groupes au niveau du serveur et importer ces groupes dans les settings de vos packages ou dans d’autres groupes.

Par exemple, créons un groupe pour “HWMonitorSettings” qui contient le setting “Interval” :

Ainsi pour chaque instance du package “HWMonitor”, vous pouvez importer le groupe “HWMonitorSettings” afin de centraliser la configuration de ce package :

Vous pouvez importer des groupes dans des groupes sans limite.

C’est toujours la valeur du setting la plus proche du package qui gagne (surcharge).

Bien entendu, vous pouvez créer autant de groupe que vous voulez et chaque groupe peut contenir des SettingValue ou des SettingContent :

Pour bien comprendre, imaginez le package suivant :

Ici cette instance du package “DemoPackage” définie au niveau du serveur (= sans prendre en compte les settings déclarés dans le fichier local et le manifeste) 7 settings :

• numberTest = 42 (définit dans les settings du package)
• Demo1 = “It’s me” (définit dans les settings du package, cette valeur écrase celle des groupes importés)
• Demo2 = 2015 (définit par le groupe “test2”. Cette valeur écrase la valeur du groupe “test”, car le groupe “test2” est importé APRES le groupe “test”)
• MyStringSetting, MyBoolSetting, MyXmlDocument et MyJsonObject définies par le groupe “common” (groupe importé dans le groupe “test2” lui même importé sur le package “DemoPackage”).

Section “credentials”

Comme évoqué dans l’article lié à la sécurité, tous les appels (http) au serveur Constellation doivent être authentifiés en utilisant une clé d’accès que l’on nomme “AccessKey”.

Ces clé d’accès sont liés à des credentials.

Dans la section “credentials” nous allons donc définir les différents credentials ainsi que les différentes autorisations et droits sur ces credentials.

Chaque credential comporte obligatoirement deux propriétés :

• Le nom (unique) du credential
• L’AccessKey

Ainsi que les propriétés suivantes :

• “enable” (true par défaut) : indique si le credential est activé ou désactivé
• “enableControlHub” (false par défaut) : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
• “enableManagementAPI” (false par défaut) : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
• “enableDeveloperAccess” (false par défaut) : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Par exemple :

Vous pouvez ensuite définir des autorisations particulières sur un credential pour l’envoi de message, l’abonnement aux groupes de message ou encore l’interrogation de StateObject.

Pour cela il existe trois sous-sections :

• “stateObjects” : autorisations spécifiques pour l’interrogation (Request ou Subscribe) des StateObjects
• “messages” : autorisations spécifiques pour l’envoi de messages
• “groups” : autorisations spécifiques pour l’abonnement aux groupes

Les autorisations sur l’interrogation des StateObjects

Par défaut un credential actif (enable=true) peut interroger (Request ou Subscribe) tous les StateObjects de votre Constellation sans restriction.

Pour modifier ce comportement vous pouvez utiliser les autorisation sur les StateObjects.

Par exemple :

Ici le credential “Standard” ne pourra pas interroger les StateObjects de la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

• Les StateObjects produits par le(s) instance(s) du package “Paradox”
• Les StateObjects produits par les packages (quel qu’il soit) de la sentinelle “PC-SEB”
• Les StateObjects nommés “/intelcpu/load/0” et produits par le package “HWMonitor” peu importe la sentinelle
• Le StateObject nommé “/ram/load” produit par le package “HWMonitor” sur la sentinelle “SERVER”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

• “id” (obligatoire) : identifiant unique de l’autorisation
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
• “sentinelName” (facultatif – * par défaut) : sentinelle producteur du StateObject
• “packageName” (facultatif – * par défaut) : package producteur du StateObject
• “name” (facultatif – * par défaut) :  nom du StateObject

Les autorisations sur l’envoi de messages

Par défaut un credential actif (enable=true) peut envoyer un message à n’importe quel scope dans votre Constellation sans restriction.

Par exemple :

Ici le credential “Standard” ne pourra pas envoyer de message dans la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

• Messages envoyés au groupe “A”
• Messages envoyés au package “DemoPackage”
• Message “SetTargetTemperature” envoyé au package “Nest”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

• “id” (obligatoire) : identifiant unique de l’autorisation
• “scope” (obligatoire) : type de scope pour le message (All, Group, Package ou Sentinel)
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
• “args” (facultatif) : les arguments du scope
• “messageKey” (facultatif) :  la clé du message

Les autorisation sur l’abonnement aux groupes

Par défaut un credential actif (enable=true) peut s’abonner à n’importe quel groupe sans restriction.

Par exemple :

Ici le credential “Standard” ne pourra pas s’abonner à des groupes (defaultAuthorization = Deny) à l’exception du groupe “A”. Les attributs sont les suivants :

• “groupName” (obligatoire) : le nom du groupe
• “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)

Editer la page sur GitHub