Modifier, vérifier et transporter les paramètres¶

La marche à suivre pour modifier pss.json à la main, pour transporter les paramètres vers une autre version de Perfect Streamer et pour les réutiliser sur un autre nœud.

Lisez d’abord Le fichier de configuration pss.json — au moins les sections sur la parcimonie du fichier, sur la lecture du fichier et sur les règles invisibles. Ici est écrit quoi faire ; là-bas, pourquoi — et les raisons ne sont pas évidentes. En bref : le fichier ne contient que les écarts par rapport aux valeurs par défaut, le service ignore une clé inconnue sans s’arrêter, et une seule valeur inacceptable fait rejeter tout le fichier.

Modifier le fichier change le prochain démarrage. Pour modifier un service en fonctionnement, utilisez l’interface web ou l’API HTTP (Pilotage via l’API HTTP).

Ce dont vous aurez besoin¶

Le schéma¶

Deux fichiers sont fournis avec la documentation : le schéma strict pss.schema.json et le permissif pss.compat.schema.json. Ce qui les distingue et ce que chacun vérifie figure dans Deux fichiers de schéma ; on y explique aussi pourquoi une vérification permissive ne suffit pas à elle seule.

Les schémas font partie de la documentation, non du produit. Ils ne sont pas sur le nœud et il n’en existe pas de copie dans le répertoire de configuration : les y chercher n’a pas de sens. Tous deux se trouvent sur le site de la documentation, dans le répertoire de leur version :

https://doc2.pstreamer.tv/schema/

Prenez le schéma de votre version et gardez-le sur la machine où vous modifiez le fichier.

Vérifiez la ligne de version à l’intérieur du schéma avant de vous y fier. Une vérification avec le schéma d’une autre version donne des réponses assurées et fausses.

Le validateur¶

N’importe quel validateur JSON Schema prenant en charge le draft 2020-12 conviendra. Le schéma utilise des constructions conditionnelles : un validateur limité à des versions antérieures acceptera un fichier qu’il aurait dû refuser ; cela mérite d’être vérifié au moment de choisir un autre outil.

Le validateur recommandé est jv, un programme open source autonome sous licence Apache 2.0 ; les builds sont publiés sur la page des versions du projet jsonschema.

Prenez l’archive correspondant à votre plateforme, décompressez-la et placez le programme dans un répertoire déjà présent dans PATH :

$ tar xzf jv-v<version>-linux-amd64.tar.gz
$ sudo install -m 0755 jv /usr/local/bin/jv
$ jv --version

Des builds sont publiés pour Linux, Windows et macOS.

Note

Le build Linux exige un jeu de bibliothèques système assez récent : il fonctionne sur RHEL, AlmaLinux et Rocky 9, Debian 12, Ubuntu 22.04 et plus récents, et sur une distribution plus ancienne il ne démarre pas du tout. Ce n’est pas un obstacle : vérifiez le fichier sur un poste de travail et portez sur le nœud un fichier déjà vérifié. C’est d’ailleurs la bonne façon de faire — le fichier est petit, et le nœud n’a pas besoin d’un validateur.

Un outil pour les contrôles que le schéma n’effectue pas¶

Deux règles ne sont pas du tout exprimables en JSON Schema : l’unicité des identifiants et l’égalité de longueur des tableaux appariés. Les commandes de Les contrôles que le schéma n’effectue pas utilisent jq, présent dans le dépôt de toute distribution :

Sous RHEL, AlmaLinux et Rocky :

$ sudo dnf install jq

Sous Debian et Ubuntu :

$ sudo apt install jq

Modifier un paramètre¶

Exécutez la séquence en entier. Les étapes que l’on saute d’ordinaire sont la 5 et la 7 — ce sont précisément elles qui attrapent les erreurs silencieuses.

Arrêtez le service.
```
$ sudo systemctl stop pss
```
Le fichier d’un nœud en fonctionnement ne doit pas être modifié : le service réécrit pss.json selon son propre calendrier à partir de ce qu’il garde en mémoire, et la modification disparaîtra sans le moindre message.
Enregistrez une copie — sous un nom qui n’existe pas encore.
```
$ cp pss.json pss.json.$(date +%Y%m%d_%H%M%S)
```
C’est le seul retour possible : le service ne tient pas de sauvegarde automatique de la configuration en service. N’utilisez pas deux fois le même nom de copie : lors d’un second passage dans cette séquence, vous écraseriez le seul fichier sain par ce qu’a laissé une tentative ratée.
Modifiez.

Modifiez les valeurs sur place. Ne déplacez pas les clés et ne déplacez pas les entrées de tableau — pour le pourquoi, voir L’ordre des clés à l’intérieur d’un objet a du sens et L’ordre des entrées dans un tableau n’est pas conservé. En ajoutant une entrée à un tableau, donnez-lui un id explicite et unique : personne ne l’attribuera à votre place (Les identifiants se posent à la main). Donnez également à l’entrée ses clés d’ancrage — stream-name pour un flux, type et l’adresse pour une entrée et une sortie, name pour une carte et un stockage, et ainsi de suite (Structure du document) : sans elles, le fichier sera rejeté en entier.
Supprimez vos commentaires. La lecture n’admet que les blocs /* ... */, les outils JSON stricts n’acceptent même pas ceux-là, et le service effacera de toute façon les commentaires au premier enregistrement (Les commentaires sont lus mais non conservés).
Vérifiez le fichier avec le schéma.
```
$ jv pss.schema.json pss.json
```
Un code de retour nul signifie que la vérification est passée. Sinon, une ligne est imprimée par erreur, et chacune nomme l’endroit exact :
```
jsonschema validation failed with 'pss.schema.json#'
  - at '/stream/3/input/1/passphrase': false schema
```
Cela se lit ainsi : la deuxième entrée du quatrième flux possède une clé passphrase qui n’appartient pas au transport choisi par sa clé type. Les positions se comptent à partir de zéro.
Effectuez les contrôles de la section Les contrôles que le schéma n’effectue pas.
Démarrez le service et lisez le journal.
```
$ sudo systemctl start pss
$ grep -iE 'ignore|clamped|config' /var/log/pss/main.log
```
Le service écrit le journal dans un fichier ; le répertoire est fixé par la clé log-dir de pss.properties, par défaut /var/log/pss. Ces lignes n’apparaîtront pas dans journalctl -u pss tant que log-to-console ou log-to-syslog n’est pas activé dans pss.properties.

Une ligne à propos d’une clé ignorée signifie que le schéma ne correspond pas au build installé — il est en général plus ancien ou plus récent. Une ligne à propos d’une valeur ramenée à la borne signifie qu’un nombre est sorti de la plage et a été corrigé en silence, et que le fichier a déjà été réenregistré avec la valeur corrigée.

Si le service n’a pas démarré, regardez dans le répertoire bad/ — Récupération après un fichier rejeté.
Vérifiez le résultat par l’interface, non par le fichier. Le fichier ne montre pas les paramètres restés à leur valeur par défaut : on ne peut donc rien confirmer avec lui. Relisez la configuration via l’API HTTP : toutes les clés y sont renvoyées.

Transporter les paramètres vers une autre version¶

Le fichier ne porte aucune marque de version et le service n’effectue aucune conversion. Une configuration issue d’une autre version s’applique telle quelle : les clés qui n’existent plus sont ignorées ; les clés qui n’existaient pas encore prennent leur valeur par défaut. Ni l’un ni l’autre n’est signalé. La marche à suivre ci-dessous rend les deux visibles.

Prenez pss.schema.json pour la version cible — celle qui lira le fichier, et non celle qui l’a écrit.
Première passe, permissive. Elle vérifie les types, les plages et les clés obligatoires, mais tolère les clés auxquelles la version cible a renoncé :
```
$ jv pss.compat.schema.json pss.json
```
Tout ce qui est signalé ici est un vrai problème : une valeur hors plage, une clé qui a changé de forme, un identifiant manquant.
Deuxième passe, stricte. Elle énumère les clés que la version cible ne connaît plus :
```
$ jv pss.schema.json pss.json
```
Chaque grief nouveau par rapport à la deuxième étape est une clé que la nouvelle version ignorera en silence. Décidez pour chacune si le paramètre a été renommé, remplacé par un autre mécanisme ou supprimé, et dans tous les cas retirez la clé du fichier : laissée en place, elle ne coûte rien à l’exécution, mais elle masque le fait que le paramètre n’agit plus.

La passe stricte répond aussi de l’appartenance d’une clé à une variante, que le schéma permissif ne vérifie pas — c’est pourquoi on ne peut pas se limiter à une seule passe permissive.
Comparez les valeurs par défaut des deux versions.

Le fichier ne contient que les écarts par rapport aux valeurs par défaut : un paramètre que vous n’avez jamais touché est donc absent du fichier — et si sa valeur par défaut a changé, le comportement changera avec la mise à jour, en silence. Le fichier et le schéma y sont aveugles par construction : le schéma de la version cible ne montrera pas un tel changement.

On ne le voit que dans la configuration effective, car l’API HTTP renvoie toutes les clés, y compris celles restées à leur valeur par défaut. Lisez-la sur le nœud source avant la mise à jour et sur un nœud de la version cible : les écarts sur les clés que vous n’avez jamais définies sont précisément les valeurs par défaut qui ont changé.
Poursuivez à l’étape 4 de Modifier un paramètre.

Avertissement

Ne transportez pas pss.json en arrière, vers une version plus ancienne. Une clé apparue plus tard sera ignorée, mais une valeur admissible aujourd’hui et qui ne l’était pas auparavant sera ramenée à la borne ou fera rejeter tout le fichier.

Transporter les paramètres vers un autre nœud¶

Une configuration est portable, mais certaines clés identifient le nœud ou en ouvrent l’accès, et les copier sans changement est au mieux déroutant, au pire une fuite.

Remplacez tous les secrets. Leur liste est dans Des valeurs à ne pas transmettre. Ne les videz pas : certaines clés n’acceptent pas la valeur vide et feront rejeter tout le fichier. Mettez un remplacement manifeste de longueur plausible, et saisissez les vraies valeurs via l’interface web après le premier démarrage.
Changez les données d’identification du nœud : le nom du nœud doit être unique au sein du domaine, et la note, le rôle et la région décrivent cette machine-ci, non celle dont ils ont été copiés.
Passez en revue tout ce qui désigne une machine précise : adresses d’écoute, noms d’interfaces, chemins des stockages, numéros de cartes. Un chemin inexistant et une carte non installée, le schéma ne les attrapera pas.
Passez en revue la section Meshwork. Les adresses, noms et secrets des pairs sont des tableaux appariés mis en correspondance par position (Les tableaux appariés se correspondent par position) : en supprimant une entrée, supprimez l’entrée correspondante dans chaque tableau. Ici, un écart de longueur fait rejeter le fichier en entier : vérifiez-les au préalable — La longueur égale des tableaux appariés.
Comparez les licences des deux nœuds. Les paramètres de ce que la licence cible n’inclut pas se révéleront être des clés inconnues : la section quittera le fichier avec un seul avertissement dans le journal. C’est le plus visible sur la réception DVB.
Poursuivez à l’étape 4 de Modifier un paramètre.

Les contrôles que le schéma n’effectue pas¶

Identifiants en double¶

Deux entrées d’un même tableau avec le même id font rejeter tout le fichier. L’unicité d’une clé parmi les entrées d’un tableau n’est pas exprimable en JSON Schema : elle se vérifie donc séparément :

$ jq '[paths(type=="array") as $p
       | {at: ($p|join(".")),
          duplicated: (getpath($p)
                       | map(select(type=="object") | (.id // 0))
                       | group_by(.) | map(select(length>1)) | map(.[0]))}
       | select(.duplicated|length>0)]' pss.json

Un résultat vide est ce qu’il faut. Tout le reste nomme le tableau et les identifiants qui s’y répètent. Un id absent, la commande le compte pour zéro : c’est ainsi que le service le lit dans le tableau stream, où deux entrées sans identifiant entrent en collision. Dans tout autre tableau, une entrée sans id fait rejeter le fichier à elle seule : un identifiant nul hors de stream est donc déjà une trouvaille.

La longueur égale des tableaux appariés¶

Là où les tableaux se correspondent par position, le nombre d’entrées doit y être identique. Pour la section Meshwork :

$ jq '.cluster | {addresses: (.["cluster-node-address"]|length),
                  names:     (.["cluster-node-name"]|length),
                  secrets:   (.["cluster-node-secret"]|length)}' pss.json

Les trois nombres doivent être égaux. Le contrôle n’est pas ici une question d’hygiène : le service détecte lui-même un écart de longueur et rejette tout le fichier — chez les pairs Meshwork, chez les variables d’environnement, dans les listes « avant — après » de la réattribution des PID (mpegts-pid-old et mpegts-pid-new), dans les listes de changement de langue (mpegts-lang-set-pid et mpegts-lang-set) et dans la paire biss-pnr et biss-key. Pour le quatuor d’adresses RIST (rist-addr-*), le fichier n’est pas rejeté, mais l’entrée ne s’ouvre pas et la raison part au journal.

L’ordre des clés¶

Le schéma ne voit pas l’ordre des clés, et il compte à trois endroits — L’ordre des clés à l’intérieur d’un objet a du sens. Il n’y a pas de commande pour cela : la règle consiste à ne rien déplacer et, dans une nouvelle entrée ajoutée à la main, à placer type, mpts et mode en premier.

Références entre sections¶

Les numéros qui pointent vers une autre partie du fichier — un stockage, une source du guide des programmes, une carte de réception, un flux d’origine — ne sont pas vérifiés par le schéma. Si la cible n’existe pas, le service le signalera au démarrage.

Récupération après un fichier rejeté¶

Si pss.json n’a pas pu être lu, le service le déplace dans le répertoire bad/ sous un nom comportant la date et l’heure et démarre sur la configuration précédemment restaurée ou, à défaut, sur les paramètres par défaut (pss_default.json, Comportement au démarrage et en cas d’erreurs de configuration). Ceux-ci ne contiennent aucun flux : dans cet état, le nœud tourne à vide. Une alerte au démarrage signale que les paramètres n’ont pas pu être chargés et que le nœud fonctionne sur ceux de secours.

Ne redémarrez pas le nœud une nouvelle fois. Un redémarrage ne nuit pas à la copie archivée, mais la configuration en service est actuellement celle par défaut, et il n’y a aucune raison de la laisser s’enregistrer par-dessus quoi que ce soit.
Trouvez le fichier archivé dans le répertoire bad/. Le plus récent est votre configuration.
Déterminez ce qui ne va pas :
```
$ jv pss.schema.json bad/pss_20260809_101500.json
```
Le journal du démarrage manqué nomme lui aussi la clé et la raison.
Corrigez, vérifiez jusqu’à un résultat propre, recopiez par-dessus pss.json et démarrez.

Si la copie archivée a disparu ou est elle aussi endommagée, le dernier espoir est la copie faite à l’étape 2 de Modifier un paramètre. C’est à cela que sert cette étape.

Suggestions dans l’éditeur¶

La plupart des éditeurs suggéreront les noms de clés, montreront les valeurs admissibles et souligneront une erreur au fil de la frappe, si on leur indique le schéma.

Associez le schéma par nom de fichier, dans les paramètres de l’éditeur lui-même : dans les éditeurs qui passent par le serveur de langage JSON, il s’agit de l’entrée json.schemas, qui fait correspondre le nom pss.json au schéma. Le schéma peut être indiqué aussi bien par un fichier local que par l’adresse de la version publiée. Le fichier local est préférable : il fonctionne sans réseau et fige la version, alors que dans une adresse il est facile de saisir la mauvaise.