Einstellungen bearbeiten, prüfen und übertragen¶

Das Vorgehen beim Bearbeiten von pss.json von Hand, beim Übertragen der Einstellungen auf eine andere Version von Perfect Streamer und bei der Wiederverwendung der Einstellungen auf einem anderen Knoten.

Lesen Sie zuerst Die Einstellungsdatei pss.json — mindestens die Abschnitte über die Dünnbesetztheit der Datei, über das Lesen der Datei und über die unsichtbaren Regeln. Hier steht, was zu tun ist; dort, warum — und die Gründe sind nicht offensichtlich. Kurz: in der Datei stehen nur die Abweichungen von den Standardwerten, einen unbekannten Schlüssel ignoriert der Dienst, ohne anzuhalten, und ein einziger unannehmbarer Wert verwirft die gesamte Datei.

Das Bearbeiten der Datei ändert den nächsten Start. Um einen laufenden Dienst zu ändern, verwenden Sie die Weboberfläche oder die HTTP API (Steuerung über die HTTP API).

Was Sie brauchen¶

Das Schema¶

Mit der Dokumentation werden zwei Dateien geliefert: das strenge Schema pss.schema.json und das nachsichtige pss.compat.schema.json. Worin sie sich unterscheiden und was jedes von ihnen prüft, steht in Zwei Schemadateien; dort steht auch, warum eine nachsichtige Prüfung für sich allein nicht genügt.

Die Schemata sind Teil der Dokumentation, nicht des Produkts. Auf dem Knoten gibt es sie nicht, und im Einstellungsverzeichnis existiert keine Kopie: dort danach zu suchen ist sinnlos. Beide liegen auf der Dokumentationsseite, im Verzeichnis ihrer Version:

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

Nehmen Sie das Schema für Ihre Version und halten Sie es auf der Maschine bereit, auf der Sie die Datei bearbeiten.

Prüfen Sie die Versionszeile im Schema, bevor Sie sich darauf verlassen. Eine Prüfung mit dem Schema einer anderen Ausgabe liefert zuversichtliche und falsche Antworten.

Der Validator¶

Es genügt jeder JSON-Schema-Validator mit Unterstützung für Draft 2020-12. Das Schema verwendet bedingte Konstrukte, deshalb nimmt ein auf frühere Fassungen beschränkter Validator eine Datei an, die er hätte ablehnen müssen; das sollte man bei der Wahl eines anderen Werkzeugs prüfen.

Empfohlen wird jv, ein eigenständiges Open-Source-Programm unter der Apache 2.0-Lizenz; Builds werden auf der Releases-Seite des Projekts jsonschema veröffentlicht.

Nehmen Sie das Archiv für Ihre Plattform, entpacken Sie es und legen Sie das Programm in ein Verzeichnis, das bereits in PATH enthalten ist:

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

Builds werden für Linux, Windows und macOS veröffentlicht.

Bemerkung

Der Linux-Build verlangt einen einigermaßen aktuellen Satz von Systembibliotheken: er läuft auf RHEL, AlmaLinux und Rocky 9, Debian 12, Ubuntu 22.04 und neuer, auf einer älteren Distribution startet er überhaupt nicht. Das ist kein Hindernis: prüfen Sie die Datei auf einer Arbeitsstation und übertragen Sie sie bereits geprüft auf den Knoten. So ist es ohnehin richtiger — die Datei ist klein, und auf dem Knoten wird kein Validator gebraucht.

Ein Werkzeug für die Prüfungen, die das Schema nicht vornimmt¶

Zwei Regeln lassen sich in JSON Schema überhaupt nicht ausdrücken: die Eindeutigkeit der Bezeichner und die gleiche Länge gepaarter Arrays. Die Befehle aus Die Prüfungen, die das Schema nicht vornimmt verwenden jq, das im Repository jeder Distribution vorhanden ist:

Unter RHEL, AlmaLinux und Rocky:

$ sudo dnf install jq

Unter Debian und Ubuntu:

$ sudo apt install jq

Einen Parameter ändern¶

Führen Sie die Abfolge vollständig aus. Übersprungen werden meist die Schritte 5 und 7 — und genau sie fangen die stillen Fehler ab.

Den Dienst stoppen.
```
$ sudo systemctl stop pss
```
Die Datei eines laufenden Knotens darf nicht bearbeitet werden: der Dienst überschreibt pss.json nach eigenem Zeitplan mit dem, was er im Speicher hält, und die Änderung verschwindet ohne jede Meldung.
Eine Kopie speichern — unter einem Namen, den es noch nicht gibt.
```
$ cp pss.json pss.json.$(date +%Y%m%d_%H%M%S)
```
Das ist der einzige Weg zurück: eine automatische Sicherung der funktionierenden Konfiguration führt der Dienst nicht. Verwenden Sie denselben Kopienamen nicht zweimal: bei einem zweiten Durchgang durch diese Abfolge würden Sie die einzige heile Datei mit dem überschreiben, was ein missglückter Versuch hinterlassen hat.
Bearbeiten.

Ändern Sie die Werte an Ort und Stelle. Verschieben Sie keine Schlüssel und keine Array-Einträge — warum, siehe Die Reihenfolge der Schlüssel innerhalb eines Objekts ist bedeutsam und Die Reihenfolge der Einträge in einem Array bleibt nicht erhalten. Wenn Sie einem Array einen Eintrag hinzufügen, geben Sie ihm ein ausdrückliches und eindeutiges id: niemand vergibt es für Sie (Bezeichner werden von Hand vergeben). Geben Sie dem Eintrag auch seine Ankerschlüssel — stream-name bei einem Stream, type und die Adresse bei einem Ein- und einem Ausgang, name bei einer Karte und einem Speicher und so weiter (Aufbau des Dokuments): ohne sie wird die Datei als Ganzes abgewiesen.
Entfernen Sie Ihre Kommentare. Das Lesen lässt nur Blockkommentare /* ... */ zu, strenge JSON-Werkzeuge nehmen auch diese nicht an, und der Dienst löscht die Kommentare ohnehin beim ersten Speichern (Kommentare werden gelesen, aber nicht bewahrt).
Die Datei gegen das Schema prüfen.
```
$ jv pss.schema.json pss.json
```
Ein Rückgabecode von null bedeutet, dass die Prüfung bestanden ist. Andernfalls wird je Fehler eine Zeile ausgegeben, und jede nennt die genaue Stelle:
```
jsonschema validation failed with 'pss.schema.json#'
  - at '/stream/3/input/1/passphrase': false schema
```
Das liest sich so: der zweite Eingang des vierten Streams hat einen Schlüssel passphrase, der nicht zu dem Transport gehört, den sein Schlüssel type gewählt hat. Die Positionen werden ab null gezählt.
Führen Sie die Prüfungen aus Die Prüfungen, die das Schema nicht vornimmt durch.
Den Dienst starten und das Protokoll lesen.
```
$ sudo systemctl start pss
$ grep -iE 'ignore|clamped|config' /var/log/pss/main.log
```
Der Dienst schreibt das Protokoll in eine Datei; das Verzeichnis legt der Schlüssel log-dir der Datei pss.properties fest, standardmäßig /var/log/pss. In journalctl -u pss erscheinen diese Zeilen nicht, solange in pss.properties nicht log-to-console oder log-to-syslog eingeschaltet ist.

Eine Zeile über einen ignorierten Schlüssel bedeutet, dass das Schema nicht zur installierten Ausgabe passt — meist ist es älter oder neuer. Eine Zeile über einen auf die Grenze gesetzten Wert bedeutet, dass eine Zahl aus dem Bereich gefallen ist und stillschweigend korrigiert wurde, und die Datei wurde mit dem korrigierten Wert bereits neu gespeichert.

Ist der Dienst nicht gestartet, sehen Sie im Verzeichnis bad/ nach — Wiederherstellung nach einer abgewiesenen Datei.
Prüfen Sie das Ergebnis über die Oberfläche, nicht anhand der Datei. Die Datei zeigt die auf ihrem Standardwert verbliebenen Einstellungen nicht, damit lässt sich also nichts bestätigen. Lesen Sie die Konfiguration über die HTTP API zurück: dort werden alle Schlüssel zurückgegeben.

Einstellungen auf eine andere Version übertragen¶

In der Datei gibt es keinen Versionsvermerk, und der Dienst nimmt keinerlei Umwandlung vor. Eine Konfiguration aus einer anderen Ausgabe wird so angewendet, wie sie ist: Schlüssel, die es nicht mehr gibt, werden ignoriert; Schlüssel, die es noch nicht gab, erhalten ihre Standardwerte. Über keines von beidem wird berichtet. Das Vorgehen unten macht beides sichtbar.

Nehmen Sie pss.schema.json für die Zielversion — diejenige, die die Datei lesen wird, nicht diejenige, die sie geschrieben hat.
Erster Durchgang, nachsichtig. Er prüft Typen, Bereiche und Pflichtschlüssel, duldet aber die Schlüssel, auf die die Zielversion verzichtet hat:
```
$ jv pss.compat.schema.json pss.json
```
Alles, was hier gemeldet wird, ist ein echtes Problem: ein Wert außerhalb des Bereichs, ein Schlüssel, der die Form gewechselt hat, ein fehlender Bezeichner.
Zweiter Durchgang, streng. Er zählt die Schlüssel auf, die die Zielversion nicht mehr kennt:
```
$ jv pss.schema.json pss.json
```
Jede gegenüber dem zweiten Schritt neue Beanstandung ist ein Schlüssel, den die neue Version stillschweigend ignorieren wird. Entscheiden Sie bei jedem, ob die Einstellung umbenannt, durch einen anderen Mechanismus ersetzt oder abgeschafft wurde, und löschen Sie den Schlüssel in jedem Fall aus der Datei: stehen gelassen kostet er im Betrieb nichts, verbirgt aber die Tatsache, dass die Einstellung nichts mehr bewirkt.

Der strenge Durchgang steht auch für die Zugehörigkeit eines Schlüssels zu einer Variante ein, die das nachsichtige Schema nicht prüft — deshalb darf man sich nicht auf einen nachsichtigen Durchgang allein beschränken.
Vergleichen Sie die Standardwerte der beiden Versionen.

In der Datei stehen nur die Abweichungen von den Standardwerten, eine Einstellung, die Sie nie angefasst haben, fehlt daher in der Datei — und hat sich ihr Standardwert geändert, ändert sich das Verhalten mit dem Update, stillschweigend. Datei und Schema sind dafür konstruktionsbedingt blind: das Schema der Zielversion zeigt eine solche Änderung nicht.

Sichtbar wird sie nur in der geltenden Konfiguration, denn die HTTP API gibt alle Schlüssel zurück, auch die auf ihrem Standardwert verbliebenen. Lesen Sie sie vor dem Update auf dem Ausgangsknoten und auf einem Knoten der Zielversion: die Abweichungen bei den Schlüsseln, die Sie nie gesetzt haben, sind genau die geänderten Standardwerte.
Weiter ab Schritt 4 des Abschnitts Einen Parameter ändern.

Warnung

Übertragen Sie pss.json nicht rückwärts auf eine ältere Version. Ein später hinzugekommener Schlüssel wird ignoriert, ein Wert jedoch, der jetzt zulässig ist und früher nicht war, wird auf die Grenze gesetzt oder verwirft die ganze Datei.

Einstellungen auf einen anderen Knoten übertragen¶

Eine Konfiguration ist übertragbar, doch ein Teil der Schlüssel identifiziert den Knoten oder öffnet den Zugang zu ihm, und sie unverändert zu kopieren ist im besten Fall verwirrend und im schlimmsten ein Leck.

Ersetzen Sie alle Secrets. Ihre Liste steht in Werte, die nicht weitergegeben werden dürfen. Leeren Sie sie nicht: manche Schlüssel nehmen einen leeren Wert nicht an und verwerfen die ganze Datei. Setzen Sie einen offensichtlichen Ersatz von glaubwürdiger Länge ein und tragen Sie die echten Werte nach dem ersten Start über die Weboberfläche nach.
Ändern Sie die Kenndaten des Knotens: der Knotenname muss innerhalb der Domain eindeutig sein, und Notiz, Rolle und Region beschreiben diese Maschine, nicht die, von der sie kopiert wurden.
Sehen Sie alles durch, was eine bestimmte Maschine benennt: Abhöradressen, Schnittstellennamen, Speicherpfade, Kartennummern. Einen nicht vorhandenen Pfad und eine nicht installierte Karte fängt das Schema nicht ab.
Sehen Sie den Abschnitt Meshwork durch. Adressen, Namen und Secrets der Peers sind gepaarte Arrays, die nach Position zugeordnet werden (Gepaarte Arrays werden nach Position einander zugeordnet): löschen Sie beim Entfernen eines Eintrags den entsprechenden Eintrag aus jedem Array. Hier verwirft eine Längenabweichung die Datei vollständig, prüfen Sie sie deshalb vorab — Die gleiche Länge gepaarter Arrays.
Vergleichen Sie die Lizenzen der beiden Knoten. Die Einstellungen dessen, was die Ziellizenz nicht umfasst, erweisen sich als unbekannte Schlüssel: der Abschnitt verlässt die Datei mit einer einzigen Warnung im Protokoll. Am auffälligsten ist das beim DVB-Empfang.
Weiter ab Schritt 4 des Abschnitts Einen Parameter ändern.

Die Prüfungen, die das Schema nicht vornimmt¶

Doppelte Bezeichner¶

Zwei Einträge eines Arrays mit demselben id verwerfen die ganze Datei. Die Eindeutigkeit eines Schlüssels unter den Einträgen eines Arrays lässt sich in JSON Schema nicht ausdrücken, sie wird deshalb gesondert geprüft:

$ 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

Ein leeres Ergebnis ist das Gewünschte. Alles andere nennt das Array und die darin wiederholten Bezeichner. Ein fehlendes id zählt der Befehl als null: so liest es der Dienst im Array stream, wo zwei Einträge ohne Bezeichner kollidieren. In jedem anderen Array verwirft ein Eintrag ohne id die Datei schon von selbst, ein Bezeichner null außerhalb von stream ist daher bereits ein Fund.

Die gleiche Länge gepaarter Arrays¶

Wo Arrays nach Position zugeordnet werden, muss die Anzahl der Einträge in ihnen übereinstimmen. Für den Abschnitt Meshwork:

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

Die drei Zahlen müssen gleich sein. Die Prüfung ist hier keine Frage der Hygiene: eine Längenabweichung erkennt der Dienst selbst und verwirft die ganze Datei — bei den Meshwork-Peers, bei den Umgebungsvariablen, bei den Listen „war — wurde“ der PID-Neuvergabe (mpegts-pid-old und mpegts-pid-new), bei den Listen des Sprachwechsels (mpegts-lang-set-pid und mpegts-lang-set) und beim Paar biss-pnr und biss-key. Bei den vier RIST-Adressen (rist-addr-*) wird die Datei nicht verworfen, der Eingang öffnet sich aber nicht, und der Grund geht ins Protokoll.

Die Reihenfolge der Schlüssel¶

Das Schema sieht die Reihenfolge der Schlüssel nicht, und sie ist an drei Stellen bedeutsam — Die Reihenfolge der Schlüssel innerhalb eines Objekts ist bedeutsam. Einen Befehl dafür gibt es nicht: die Regel lautet, nichts umzustellen und in einem von Hand hinzugefügten neuen Eintrag type, mpts und mode an den Anfang zu setzen.

Verweise zwischen Abschnitten¶

Die Nummern, die auf einen anderen Teil der Datei verweisen — einen Speicher, eine Programmführerquelle, eine Empfangskarte, einen Ausgangsstream — werden vom Schema nicht geprüft. Existiert das Ziel nicht, meldet es der Dienst beim Start.

Wiederherstellung nach einer abgewiesenen Datei¶

Konnte pss.json nicht gelesen werden, verschiebt der Dienst sie in das Verzeichnis bad/ unter einem Namen mit Datum und Uhrzeit und startet mit der zuvor wiederhergestellten Konfiguration, in deren Abwesenheit mit den Standardeinstellungen (pss_default.json, Verhalten beim Start und bei Konfigurationsfehlern). Diese enthalten überhaupt keine Streams, in diesem Zustand läuft der Knoten daher leer. Dass die Einstellungen nicht geladen werden konnten und der Knoten auf den Ersatzeinstellungen läuft, meldet ein Alert beim Start.

Starten Sie den Knoten nicht noch einmal neu. Der archivierten Kopie schadet ein Neustart nicht, doch die aktuell arbeitende Konfiguration sind die Standardeinstellungen, und es gibt keinen Grund, sie über irgendetwas speichern zu lassen.
Suchen Sie die archivierte Datei im Verzeichnis bad/. Die neueste ist Ihre Konfiguration.
Finden Sie heraus, was mit ihr nicht stimmt:
```
$ jv pss.schema.json bad/pss_20260809_101500.json
```
Auch das Protokoll des misslungenen Starts nennt Schlüssel und Ursache.
Beheben Sie es, prüfen Sie bis zu einem sauberen Ergebnis, kopieren Sie es über pss.json zurück und starten Sie.

Ist die archivierte Kopie verschwunden oder ebenfalls beschädigt, bleibt als letzte Hoffnung die in Schritt 2 des Abschnitts Einen Parameter ändern angelegte Kopie. Dafür gibt es diesen Schritt.

Hinweise im Editor¶

Die meisten Editoren schlagen Schlüsselnamen vor, zeigen die zulässigen Werte an und unterstreichen einen Fehler schon beim Tippen, wenn man ihnen das Schema nennt.

Binden Sie das Schema über den Dateinamen, in den Einstellungen des Editors selbst: in Editoren, die über den JSON-Sprachserver arbeiten, ist das der Eintrag json.schemas, der den Namen pss.json dem Schema zuordnet. Das Schema lässt sich sowohl als lokale Datei als auch über die Adresse der veröffentlichten Version angeben. Die lokale Datei ist vorzuziehen: sie funktioniert ohne Netz und legt die Version fest, während sich in einer Adresse leicht die falsche Version tippen lässt.