PSS Lic Perfect Streamer Toolkit v2.0 — Lizenz des Knotens¶
Teil des Perfect Streamer Toolkit — https://pstreamer.tv
Ein Kommandozeilen-Dienstprogramm zur Verwaltung der Lizenz eines Knotens: es wendet das vom Anbieter gesendete Lizenz-Update an, exportiert den Zustand des Schlüssels für eine Aktivierungsanfrage und überträgt die Lizenz von einem Knoten auf einen anderen.
Es arbeitet mit demselben Schlüssel des Schutzsystems wie der Streamer selbst — einem Software- (SL) oder einem Hardware-Schlüssel (HL). Der Zugriff auf den Schlüssel erfolgt über den Dienst aksusbd des Schutzsystems, deshalb funktioniert das Dienstprogramm nur dort, wo dieser Dienst läuft.
Das Werkzeug ist Bestandteil des Pakets pstreamer und befindet sich nach der Installation unter /opt/pss/tools/pss_lic — es muss nichts separat installiert werden.
Wann das Dienstprogramm nötig ist¶
Der Bildschirm Lizenz kann das C2V exportieren und den zugesandten V2C-Schlüssel anwenden, mehr aber nicht. Über die Konsole sind alle Operationen am Schlüssel verfügbar, und nur von hier aus wird alles Übrige erledigt:
Aktivierung und Aktualisierung der Lizenz auf einem Knoten ohne Zugang zur Weboberfläche;
Automatisierung: Ausrollen eines Knotenparks, planmäßige Lizenzerneuerung, Prüfungen aus einem Überwachungssystem;
Übertragung einer Lizenz zwischen Knoten — dauerhaft oder vorübergehend.
Das Dienstprogramm braucht keine Root-Rechte: das Schreiben in den geschützten Speicher übernimmt der Dienst des Schutzsystems, nicht das Dienstprogramm. Root wird nur benötigt, um die Ausgabedatei in ein Systemverzeichnis zu schreiben und um den Dienst pss nach dem Lizenzwechsel neu zu starten.
Die Erstaktivierung der Testlizenz führt nicht dieses Dienstprogramm aus, sondern das Skript /opt/pss/tools/activate.sh — siehe Temporäre Aktivierung und Start. Das Skript ruft pss_lic selbst auf, startet anschließend den Dienst pss neu und aktiviert dessen Autostart. Wie eine dauerhafte Lizenz zu beziehen ist, beschreibt Dauerhafte Aktivierung.
Verwendung¶
pss_lic <Befehl> [Optionen]
Ohne Argumente, mit -h oder mit --help gestartet, gibt es die eingebaute Hilfe aus und endet mit Code 0. Optionen stehen nach dem Befehl; vor dem Befehl sind nur -h, --help, -V und --version zulässig. Positionsargumente werden nicht angenommen — alles wird über Optionen angegeben.
Befehle¶
Befehl |
Zweck |
Erforderliche Optionen |
|---|---|---|
|
Ein Lizenz-Update auf den Knoten anwenden — eine V2C-, H2R- oder R2H-Datei |
|
|
Den Zustand des Schlüssels (C2V) für den Versand an den Anbieter exportieren |
— |
|
Den Fingerabdruck des Knotens exportieren |
— |
|
Den Recipient-Block des Knotens exportieren — die Beschreibung des Knotens als Empfänger einer Übertragung |
— |
|
Die von diesem Knoten aus sichtbaren Schlüssel des Schutzsystems auflisten |
— |
|
Eine Produktlizenz vorübergehend auf einen anderen Knoten übertragen; das Ergebnis ist eine H2R-Datei |
|
|
Den Schlüssel auf einen anderen Knoten übertragen; das Ergebnis ist eine V2C-Datei, und die Lizenz wird vom aktuellen Knoten entfernt |
|
|
Eine vorübergehend übertragene Lizenz vorzeitig zurückgeben; das Ergebnis ist eine R2H-Datei |
|
|
Version des Dienstprogramms und API-Version des Schutzsystems anzeigen |
— |
|
Die eingebaute Hilfe anzeigen |
— |
Optionen¶
Option |
Beschreibung |
Akzeptiert von |
|---|---|---|
|
Eingabedaten |
|
|
Ausgabedaten; standardmäßig |
alle außer |
|
Recipient-Block des empfangenden Knotens |
|
|
Schlüssel-ID, dezimal |
|
|
Produkt-ID, dezimal |
|
|
Dauer der vorübergehenden Übertragung in Sekunden; standardmäßig |
|
|
Verkürzter Zustandsabzug; bei einem Hardware-Schlüssel (HL) eine kleinere Datei |
|
|
Nur die Schlüssel-IDs ausgeben, eine pro Zeile |
|
|
Keine Bestätigung anfordern |
|
|
Nur Fehler |
alle |
|
Ausführliches Protokoll der Zugriffe auf das Schutzsystem |
alle |
|
Versionen anzeigen und beenden |
alle |
|
Hilfe anzeigen |
alle |
Eine Option, die in der Zeile ihres Befehls nicht aufgeführt ist, ist ein Syntaxfehler und kein stillschweigend ignoriertes Flag: das Dienstprogramm meldet beispielsweise --key-id is not valid for 'fingerprint' und fügt häufig eine Zeile mit der Ursache hinzu. Die Werte von --key-id, --product-id und --duration sind ausschließlich Dezimalzahlen ab 1; null ist unzulässig.
Ein- und Ausgabe¶
Jedes Dateiargument — --in, --out, --recipient — akzeptiert -: Lesen von stdin, Schreiben nach stdout. Standardmäßig geht die Ausgabe nach stdout.
Auf stdout gelangen nur die Daten selbst — der Lizenzblock. Erfolgsmeldungen, Warnungen und Fehler gehen auf stderr und beginnen mit dem Präfix pss_lic:. Dadurch lässt sich jeder Befehl in eine Datei oder eine Pipeline umleiten, ohne die Ausgabe auswerten zu müssen.
Ist keine Ausgabedatei angegeben und stdout ein Terminal, warnen die Befehle detach, rehost und cancel, dass das Ergebnis der Übertragung auf dem Bildschirm landet und verloren geht:
pss_lic: writing the V2C to the terminal; use --out <file> to keep it
Die Eingabedatei wird geprüft, bevor das Schutzsystem angesprochen wird: eine leere Datei, eine Datei, die ein Nullbyte enthält, und eine Datei über 8 MiB werden abgewiesen. Eine UTF-8-Bytereihenfolge-Markierung am Dateianfang — manche Mail-Clients und Editoren fügen sie hinzu — wird automatisch entfernt.
Anwenden eines Lizenz-Updates¶
Die vom Anbieter gesendete Datei wird mit einem einzigen Befehl angewendet:
# apply a licence update sent by the vendor
/opt/pss/tools/pss_lic apply --in license.v2c
# the same file through a pipe
cat license.v2c | /opt/pss/tools/pss_lic apply --in -
Bei Erfolg erscheint auf stderr:
pss_lic: update applied
Das Dienstprogramm startet den Dienst nicht neu. Ein laufender Streamer hält die bisherige Lizenz im Speicher, deshalb ist der Dienst nach einem Lizenzwechsel von Hand neu zu starten:
sudo systemctl restart pss
Das erneute Anwenden derselben Datei gilt nicht als Fehler: das Dienstprogramm meldet this V2C is already installed, nothing to do und beendet sich mit Code 0. Auf dieser Eigenschaft beruht die Wiederholbarkeit des Skripts activate.sh.
Verwechseln Sie diese Meldung nicht mit der Ablehnung the update is older than the one already installed (stale or rolled-back V2C) (Status 54) — diese bedeutet, dass eine veraltete Datei angewendet wird, und endet mit Code 1. Fordern Sie in diesem Fall beim Anbieter ein aktuelles V2C an.
Mit dem Befehl apply werden alle drei Arten von Updates angewendet: das V2C vom Anbieter, das H2R bei einer vorübergehenden Übertragung und das R2H bei deren Rückgabe.
Export der Daten für den Anbieter¶
Eine Aktivierungsanfrage oder eine Anfrage zur Erweiterung der Lizenz wird aus einer C2V-Datei erstellt — einer Momentaufnahme des aktuellen Zustands des Schlüssels:
# export the key state for the vendor
/opt/pss/tools/pss_lic c2v --out host.c2v
Sieht der Knoten mehrere Schlüssel, rät das Schutzsystem nicht, welcher gemeint ist, und antwortet mit der Ablehnung too many keys match the scope (Status 37). Die Schlüssel-IDs listet der Befehl keys auf:
# list the key ids visible on this host, then scope the export to one of them
/opt/pss/tools/pss_lic keys --ids
/opt/pss/tools/pss_lic c2v --key-id <id> --out host.c2v
Ohne --ids gibt der Befehl keys die Liste der Schlüssel und ihrer Lizenzen in der Form aus, in der das Schutzsystem sie liefert — als XML-Dokument, nicht als Tabelle. Für die Wahl eines Wertes für --key-id genügt die Form --ids.
Die Option --fast fordert beim Schlüssel einen verkürzten Zustandsabzug an. Bei einem Hardware-Schlüssel (HL) fällt diese Datei etwa um eine Größenordnung kleiner aus als die vollständige; bei einem Software-Schlüssel (SL) ist die Größe dieselbe — es unterscheidet sich nur der Umfang der Daten.
Der Inhalt eines C2V lässt sich auf dem Knoten nicht lesen, deshalb wird die Schlüssel-ID mit dem Befehl keys ermittelt und nicht aus der Datei selbst.
Ein C2V — eine Anfrage. Senden Sie dem Anbieter nicht zweimal dasselbe C2V: das zweite daraufhin ausgestellte V2C lässt sich möglicherweise nur teilweise anwenden. Für eine erneute Anfrage das C2V neu exportieren.
Die Befehle fingerprint und recipient exportieren den Fingerabdruck des Knotens und den Recipient-Block. Der Fingerabdruck beschreibt die Maschine und wird vom Anbieter benötigt, solange auf dem Knoten noch keine Lizenz vorhanden ist: an ihn wird ein neuer Software-Schlüssel gebunden. Der Recipient-Block beschreibt den Knoten als Empfänger einer Übertragung und wird nicht vom Anbieter, sondern vom zweiten Knoten gebraucht — siehe Übertragung der Lizenz auf einen anderen Knoten. Beide beziehen sich auf den Knoten als Ganzes und nicht auf einen einzelnen Schlüssel, deshalb ist die Option --key-id für sie unzulässig.
Übertragung der Lizenz auf einen anderen Knoten¶
Eine Lizenz lässt sich nur bei einem Software-Schlüssel (SL) zwischen Knoten übertragen: ein Hardware-Schlüssel wandert mit dem Gerät selbst und wird von den Befehlen des Dienstprogramms nicht berührt. Eine Testlizenz ist nicht übertragbar. Ob eine Übertragung möglich ist, legen die Lizenzbedingungen fest; ist sie nicht vorgesehen, antwortet das Schutzsystem mit der Ablehnung rehost is not allowed for this licence. Klären Sie das vorab mit dem Anbieter.
Warnung
rehost nimmt die Lizenz vom aktuellen Knoten. Die erzeugte Datei lässt sich nur auf dem Knoten anwenden, dessen Recipient-Block in --recipient übergeben wurde. Geht die Datei verloren oder ist der empfangende Knoten nicht erreichbar, ist die Lizenz mit ihr verloren: einen lokalen Rückweg gibt es nicht. Geben Sie stets --recipient an und speichern Sie das Ergebnis in einer Datei, nicht auf dem Bildschirm.
Die Übertragung erfolgt in drei Schritten und betrifft beide Knoten. Im Folgenden ist A der Knoten, den die Lizenz verlässt, und B der Knoten, auf den sie übergeht.
Auf Knoten B den Recipient-Block exportieren und die Datei an Knoten A übergeben:
/opt/pss/tools/pss_lic recipient --out b.rcp
Auf Knoten A den Schlüssel übertragen. Das Dienstprogramm fragt nach einer Bestätigung:
/opt/pss/tools/pss_lic rehost --key-id <id> --recipient b.rcp --out a2b.v2c
pss_lic: about to move the licence off this host. This cannot be undone. Continue? [y/N]
Als Bestätigung gilt eine Antwort, die mit
yoderYbeginnt:yesbestätigt genauso wiey. Jede andere Antwort, auch eine leere Zeile, bricht die Operation ab. Die Frage wird direkt auf dem Terminal gestellt, eine Umleitung der Ausgabe verbirgt sie also nicht. Fehlt ein Terminal — etwa weil der Befehl aus einem Scheduler gestartet wurde —, verweigert das Dienstprogramm die Übertragung und schlägt--yesvor.Auf Knoten B die erhaltene Datei anwenden und den Dienst neu starten:
/opt/pss/tools/pss_lic apply --in a2b.v2c sudo systemctl restart pss
Von dem Moment an, in dem Schritt 2 ausgeführt ist, bis Schritt 3 durchgelaufen ist, liegt die Lizenz auf keinem der beiden Knoten. Planen Sie die Übertragung so, dass dieser Zeitraum kurz bleibt.
Die erzeugte Datei ist überall außer auf Knoten B nutzlos: auf einer anderen Maschine ergibt sie eine Ablehnung mit Status 62. Der Versuch, auf Knoten A eine alte Datei desselben Schlüssels anzuwenden, ergibt Status 70 oder 71 — der Schlüssel wurde bereits übertragen.
Vorübergehende Übertragung der Lizenz¶
detach überträgt eine Produktlizenz für eine festgelegte Frist auf einen anderen Knoten, cancel gibt sie vorzeitig zurück. Wie die dauerhafte Übertragung funktioniert auch die vorübergehende nur mit einem Software-Schlüssel und nur, wenn die Lizenzbedingungen es zulassen; andernfalls antwortet das Schutzsystem mit einer Ablehnung mit Status 67. Bei einer Testlizenz ist eine solche Ablehnung das erwartete Ergebnis und kein Defekt.
Die Produkt-ID von Perfect Streamer ist 2. Die Frist wird in Sekunden mit der Option --duration angegeben; der Standardwert beträgt 120 Sekunden, geben Sie ihn im Betrieb daher stets ausdrücklich an. Die Obergrenze des Dienstprogramms selbst liegt bei 31536000 Sekunden (einem Jahr), die tatsächliche Grenze setzt jedoch die Lizenz: bei einer zu langen Frist antwortet das Schutzsystem mit der Ablehnung invalid duration specified. Die angeforderte Frist ist genau das — eine Anfrage: den endgültigen Wert bestimmt der Schlüssel, und er kann kürzer ausfallen.
Auf Knoten B den Recipient-Block exportieren und die Datei an Knoten A übergeben:
/opt/pss/tools/pss_lic recipient --out b.rcp
Auf Knoten A die Lizenz für einen Tag übertragen:
/opt/pss/tools/pss_lic detach --product-id 2 --duration 86400 --recipient b.rcp --out b.h2r
pss_lic: product 2 detached, 86400 s requested
Auf Knoten B die erhaltene Datei anwenden und den Dienst neu starten:
/opt/pss/tools/pss_lic apply --in b.h2r sudo systemctl restart pss
Nach Ablauf der Frist kehrt die Lizenz von selbst auf Knoten A zurück. Die vorzeitige Rückgabe verläuft in umgekehrter Richtung: die R2H-Datei entsteht auf dem empfangenden Knoten und wird auf dem ursprünglichen angewendet. Ist die Frist bis dahin bereits abgelaufen, gibt es nichts zurückzugeben — das Dienstprogramm meldet the R2H: nothing to write und endet mit Code 1.
Auf Knoten B die ID des übertragenen Schlüssels ermitteln und die Übertragung abbrechen:
/opt/pss/tools/pss_lic keys --ids /opt/pss/tools/pss_lic cancel --key-id <id> --out back.r2h
Auf Knoten A die erhaltene Datei anwenden und den Dienst neu starten:
/opt/pss/tools/pss_lic apply --in back.r2h sudo systemctl restart pss
Die Option --recipient ist für cancel unzulässig: die Lizenz kehrt dorthin zurück, woher sie kam. Wie rehost fragt auch der Befehl cancel nach einer Bestätigung. detach selbst fragt nicht — die Übertragung ist zeitlich begrenzt und umkehrbar.
Bewahren Sie die Zwischendateien ebenso sorgfältig auf wie bei einer dauerhaften Übertragung: solange das H2R nicht auf Knoten B und das R2H nicht auf Knoten A angewendet ist, steht die Lizenz auf keinem von beiden zur Verfügung und kehrt erst nach Ablauf der Übertragungsdauer zurück.
Exit-Codes¶
Code |
Bedeutung |
|---|---|
|
Die Operation wurde ausgeführt. Derselbe Code wird zurückgegeben, wenn das Update bereits zuvor angewendet wurde |
|
Das Schutzsystem hat die Operation abgelehnt — die Meldung nennt die Statusnummer. Derselbe Code wird zurückgegeben, wenn die Operation ohne Daten endete, zum Beispiel |
|
Syntaxfehler: ein unbekannter Befehl, eine für den Befehl unzulässige Option, eine fehlende Pflichtoption, ein unzulässiger Wert. Derselbe Code wird zurückgegeben, wenn der Bediener die Bestätigungsabfrage mit „nein“ beantwortet hat |
|
Ein-/Ausgabefehler: die Datei lässt sich nicht öffnen, lesen oder schreiben |
Zwei Fälle sollten Skripte berücksichtigen. Verweigert der Bediener die Bestätigung, ist das Code 2 und nicht 0: eine Prüfung „Code ungleich null bedeutet Störung“ hält den Abbruch für einen Fehler. Eine nicht lesbare Eingabedatei ist Code 3 und nicht 1: bis zum Schutzsystem kam es gar nicht.
# distinguish a refusal by the key from a bad command line or a missing file
/opt/pss/tools/pss_lic apply --in license.v2c || {
case $? in
1) echo "the key refused the update" >&2 ;;
2) echo "wrong command line, or the operator declined" >&2 ;;
3) echo "the file could not be read" >&2 ;;
esac
}
Meldungen und Diagnose¶
Meldungen erscheinen auf stderr mit dem Präfix pss_lic:. Eine Ablehnung des Schutzsystems wird immer in derselben Form ausgegeben — was misslungen ist, eine Beschreibung der Ursache im Klartext und die Statusnummer — und bei häufigen Ursachen kommt eine Hinweiszeile hinzu:
pss_lic: reading the key state (C2V) failed: too many keys match the scope (status 37)
pss_lic: hint: this host holds several keys; run 'pss_lic keys --ids' and pass --key-id
Die Option -q entfernt die Erfolgsmeldungen — auch die Warnung vor der Ausgabe auf das Terminal —, nicht aber die Fehler und nicht die Hinweise. Die Option -v ergänzt ein Protokoll der Zugriffe auf das Schutzsystem: die Anfragen, die Zahl der gelesenen und geschriebenen Bytes, den Namen der aufgerufenen Funktion. Legen Sie beim Support genau die Ausgabe mit -v bei.
Die häufigste Gruppe von Ablehnungen ist ein nicht sichtbarer Schlüssel oder ein nicht antwortender Dienst des Schutzsystems (Status 7, 14, 33, 50 und 80). Prüfen Sie, ob der Dienst läuft (systemctl status aksusbd), ob der USB-Schlüssel angeschlossen ist und ob die Bibliotheken des Anbieters im Verzeichnis /var/hasplm vorhanden sind — sie installiert das Paket pstreamer. Die übrigen Ablehnungen stehen in der Tabelle unten; in der ersten Spalte die Statusnummer aus der Ablehnungszeile, in der zweiten deren Text.
Status |
Text der Ablehnung |
Ursache und Abhilfe |
|---|---|---|
37 |
|
Der Knoten sieht mehrere Schlüssel. Die Liste mit |
42 |
|
Die Version von aksusbd ist niedriger als 9.12; das Paket des Schutzsystems aktualisieren |
47 |
|
Der Lizenzspeicher ist beschädigt; ein neues V2C vom Anbieter ist erforderlich |
48 |
|
Im Verzeichnis |
54 |
|
Es wird ein veraltetes V2C angewendet; ein aktuelles beim Anbieter anfordern |
55 |
|
Die Update-Datei ist dem Zustand des Schlüssels voraus — ein Zwischenupdate wurde übersprungen; ein aktuelles C2V exportieren und das dafür ausgestellte V2C anwenden |
58 |
|
Der Recipient-Block ist beschädigt; ihn auf dem empfangenden Knoten erneut exportieren |
60 |
|
|
61 |
|
|
62 |
|
Die Datei wurde für eine andere Maschine ausgestellt und ist nur dort anwendbar |
63 |
|
Die Übertragungsdauer ist länger als die Lizenz zulässt |
64 |
|
Der Lizenzspeicher wurde als Kopie erkannt — eine Folge des Klonens einer Festplatte oder einer virtuellen Maschine; beim Anbieter eine Neuausstellung der Lizenz für diese Maschine anfordern |
66 |
|
Der Schlüssel ist inaktiv |
67 |
|
Die vorübergehende Übertragung ist durch die Lizenzbedingungen nicht erlaubt |
68 |
|
Der Knoten sieht mehrere Dienste des Schutzsystems; |
69 |
|
Die Übertragung ist durch die Lizenzbedingungen nicht erlaubt |
70 |
|
Der Schlüssel wurde bereits von diesem Knoten übertragen |
71 |
|
Es wird eine alte Übertragungsdatei angewendet; der Schlüssel wurde bereits von diesem Knoten übertragen |
77 |
|
Auf dem empfangenden Knoten läuft ein veralteter Dienst des Schutzsystems; ihn aktualisieren |
78 |
|
Der Lizenzspeicher gehört zu einer anderen Maschine; ein neues V2C vom Anbieter ist erforderlich |
79 |
|
Im Netz gibt es einen zweiten Knoten mit demselben Namen; den Knoten umbenennen oder die Lizenz neu ausstellen lassen |
94 |
|
Die Update-Zähler von Schlüssel und Datei sind auseinandergelaufen; ein aktuelles C2V exportieren und das dafür ausgestellte V2C anwenden |
Für jeden bekannten Status gibt das Dienstprogramm eine Beschreibung im Klartext aus; ein nicht erkannter Status wird als unrecognised status mit seiner Nummer ausgegeben.
Ein Sonderfall ist der Befehl keys: hat das Schutzsystem das ausführliche Format der Liste nicht angenommen, gibt das Dienstprogramm die Ablehnungszeile aus und wiederholt die Anfrage dann im Kurzformat. Die Liste wird dabei ausgegeben und der Exit-Code bleibt null, eine solche Ablehnungszeile vor einem normalen Ergebnis ist daher nicht als Störung zu lesen.
Der Befehl version funktioniert auch bei defektem Schutzsystem — genau das macht ihn als ersten Diagnoseschritt nützlich. Er gibt das Banner des Dienstprogramms und die API-Version des Schutzsystems aus; ist der Dienst des Schutzsystems nicht erreichbar, erscheint statt der Version unavailable mit einer Statusnummer, und der Exit-Code bleibt null.
Umstieg von Version 1.2¶
In Version 2.0 wurde die positionale Syntax durch Befehle und lange Optionen ersetzt; die früheren Formen werden nicht unterstützt. Bei ihrer Eingabe gibt das Dienstprogramm den Ersatz aus und beendet sich mit Code 2.
Bis 1.2 |
Ab 2.0 |
|---|---|
|
|
|
|
|
|
|
|
|
|
Auch das Verhalten der Ausgabe hat sich geändert: in 2.0 gelangen nur die Daten nach stdout, die Meldungen nach stderr. Skripte, die die gemischte Ausgabe der Version 1.2 ausgewertet haben, müssen angepasst werden.
