PSS Lic Perfect Streamer Toolkit v2.0 — licence du nœud¶
Composant de Perfect Streamer Toolkit — https://pstreamer.tv
Utilitaire en ligne de commande pour la gestion de la licence d’un nœud : il applique la mise à jour de licence envoyée par le fournisseur, exporte l’état de la clé pour une demande d’activation et transfère la licence d’un nœud à un autre.
Il travaille avec la même clé du système de protection que le streamer lui-même — logicielle (SL) ou matérielle (HL). L’accès à la clé passe par le service aksusbd du système de protection ; l’utilitaire ne fonctionne donc que là où ce service tourne.
L’outil fait partie du paquet pstreamer et se trouve après l’installation dans /opt/pss/tools/pss_lic — rien n’est à installer séparément.
Quand l’utilitaire est nécessaire¶
L’écran Licence sait exporter le C2V et appliquer la clé V2C reçue, mais rien de plus. Depuis la console, toutes les opérations sur la clé sont disponibles, et le reste ne se fait que d’ici :
activation et mise à jour de la licence sur un nœud sans accès à l’interface web ;
automatisation : déploiement d’un parc de nœuds, renouvellement planifié des licences, contrôles depuis un système de supervision ;
transfert d’une licence entre nœuds — permanent ou temporaire.
L’utilitaire n’a pas besoin des droits root : l’écriture dans le stockage sécurisé est réalisée par le service du système de protection, et non par l’utilitaire. Root n’est nécessaire que pour écrire le fichier de sortie dans un répertoire système et pour redémarrer le service pss après un changement de licence.
L’activation initiale de la licence d’essai n’est pas réalisée par cet utilitaire mais par le script /opt/pss/tools/activate.sh — voir Activation temporaire et démarrage. Le script appelle lui-même pss_lic, puis redémarre le service pss et active son démarrage automatique. La marche à suivre pour obtenir une licence permanente est décrite dans Activation permanente.
Utilisation¶
pss_lic <commande> [options]
Lancé sans argument, avec -h ou avec --help, il imprime l’aide intégrée et se termine avec le code 0. Les options se placent après la commande ; avant la commande, seuls -h, --help, -V et --version sont admis. Les arguments positionnels ne sont pas acceptés — tout se donne par options.
Commandes¶
Commande |
Rôle |
Options obligatoires |
|---|---|---|
|
Appliquer au nœud une mise à jour de licence — un fichier V2C, H2R ou R2H |
|
|
Exporter l’état de la clé (C2V) à envoyer au fournisseur |
— |
|
Exporter l’empreinte du nœud |
— |
|
Exporter le bloc recipient du nœud — la description du nœud en tant que destinataire d’un transfert |
— |
|
Lister les clés du système de protection visibles depuis ce nœud |
— |
|
Transférer temporairement la licence du produit vers un autre nœud ; le résultat est un fichier H2R |
|
|
Transférer la clé vers un autre nœud ; le résultat est un fichier V2C, et la licence est retirée du nœud courant |
|
|
Restituer par anticipation une licence transférée temporairement ; le résultat est un fichier R2H |
|
|
Afficher la version de l’utilitaire et la version de l’API du système de protection |
— |
|
Afficher l’aide intégrée |
— |
Options¶
Option |
Description |
Acceptée par |
|---|---|---|
|
Données d’entrée |
|
|
Données de sortie ; par défaut |
toutes sauf |
|
Bloc recipient du nœud destinataire |
|
|
Identifiant de la clé, décimal |
|
|
Identifiant du produit, décimal |
|
|
Durée du transfert temporaire en secondes ; par défaut |
|
|
Instantané d’état réduit ; sur une clé matérielle (HL), un fichier plus petit |
|
|
Afficher uniquement les identifiants des clés, un par ligne |
|
|
Ne pas demander de confirmation |
|
|
Erreurs uniquement |
toutes |
|
Journal détaillé des appels au système de protection |
toutes |
|
Afficher les versions et quitter |
toutes |
|
Afficher l’aide |
toutes |
Une option qui ne figure pas sur la ligne de sa commande est une erreur de syntaxe, et non un drapeau silencieusement ignoré : l’utilitaire signale par exemple --key-id is not valid for 'fingerprint', et ajoute souvent une ligne indiquant la cause. Les valeurs de --key-id, --product-id et --duration sont uniquement des nombres décimaux à partir de 1 ; zéro est interdit.
Entrée et sortie¶
Tout argument de fichier — --in, --out, --recipient — accepte - : lecture depuis stdin, écriture sur stdout. Par défaut, la sortie va sur stdout.
Seules les données elles-mêmes — le bloc de licence — vont sur stdout. Les messages de succès, les avertissements et les erreurs vont sur stderr et commencent par le préfixe pss_lic:. Grâce à cela, toute commande peut être redirigée vers un fichier ou un tube sans avoir à analyser la sortie.
Si aucun fichier de sortie n’est indiqué et que stdout est un terminal, les commandes detach, rehost et cancel avertissent que le résultat du transfert se retrouvera à l’écran et sera perdu :
pss_lic: writing the V2C to the terminal; use --out <file> to keep it
Le fichier d’entrée est vérifié avant tout appel au système de protection : un fichier vide, un fichier contenant un octet nul et un fichier de plus de 8 Mio sont rejetés. Une marque d’ordre des octets UTF-8 en début de fichier — certains clients de messagerie et éditeurs en ajoutent une — est supprimée automatiquement.
Application d’une mise à jour de licence¶
Le fichier envoyé par le fournisseur est appliqué en une seule commande :
# 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 -
En cas de succès, stderr affiche :
pss_lic: update applied
L’utilitaire ne redémarre pas le service. Un streamer en fonctionnement conserve l’ancienne licence en mémoire ; après un changement de licence, redémarrez donc le service à la main :
sudo systemctl restart pss
Réappliquer le même fichier n’est pas une erreur : l’utilitaire signale this V2C is already installed, nothing to do et se termine avec le code 0. C’est sur cette propriété que repose la répétabilité du script activate.sh.
Ne confondez pas ce message avec le refus the update is older than the one already installed (stale or rolled-back V2C) (statut 54) — celui-ci signifie qu’un fichier périmé est appliqué, et il se termine avec le code 1. Demandez alors un V2C récent au fournisseur.
La commande apply applique les trois types de mise à jour : le V2C du fournisseur, le H2R d’un transfert temporaire et le R2H de sa restitution.
Export des données pour le fournisseur¶
Une demande d’activation ou d’extension de la licence se construit à partir d’un fichier C2V — un instantané de l’état courant de la clé :
# export the key state for the vendor
/opt/pss/tools/pss_lic c2v --out host.c2v
Si le nœud voit plusieurs clés, le système de protection ne devinera pas laquelle est visée et répond par le refus too many keys match the scope (statut 37). La commande keys énumère les identifiants des clés :
# 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
Sans --ids, la commande keys imprime la liste des clés et de leurs licences telle que le système de protection la renvoie — un document XML, et non un tableau. Pour choisir une valeur de --key-id, la forme --ids suffit.
L’option --fast demande à la clé un instantané d’état réduit. Sur une clé matérielle (HL), ce fichier est environ un ordre de grandeur plus petit que le fichier complet ; sur une clé logicielle (SL), la taille est la même — seules les données qu’il contient diffèrent.
Le contenu d’un C2V ne peut pas être lu sur le nœud, l’identifiant de la clé s’obtient donc avec la commande keys et non à partir du fichier lui-même.
Un C2V — une demande. N’envoyez pas deux fois le même C2V au fournisseur : le second V2C émis à partir de celui-ci risque de ne s’appliquer que partiellement. Pour une nouvelle demande, réexportez le C2V.
Les commandes fingerprint et recipient exportent l’empreinte du nœud et le bloc recipient. L’empreinte décrit la machine et est ce dont le fournisseur a besoin lorsqu’il n’y a pas encore de licence sur le nœud : c’est à elle qu’une nouvelle clé logicielle est liée. Le bloc recipient décrit le nœud en tant que destinataire d’un transfert et n’est pas nécessaire au fournisseur mais au second nœud — voir Transfert de la licence vers un autre nœud. Tous deux se rapportent au nœud dans son ensemble et non à une clé particulière ; l’option --key-id leur est donc interdite.
Transfert de la licence vers un autre nœud¶
Le transfert d’une licence entre nœuds n’est possible que pour une clé logicielle (SL) : une clé matérielle voyage avec l’appareil lui-même et n’est pas concernée par les commandes de l’utilitaire. Une licence d’essai n’est pas transférable. La possibilité du transfert est fixée par les conditions de la licence ; si elle n’est pas prévue, le système de protection répond par le refus rehost is not allowed for this licence. Renseignez-vous à l’avance auprès du fournisseur.
Avertissement
rehost retire la licence du nœud courant. Le fichier obtenu ne peut être appliqué que sur le nœud dont le bloc recipient a été passé à --recipient. Si le fichier est perdu ou si le nœud destinataire est injoignable, la licence est perdue avec lui : il n’existe pas de retour en arrière local. Indiquez toujours --recipient et enregistrez le résultat dans un fichier, pas à l’écran.
Le transfert se déroule en trois étapes et concerne les deux nœuds. Ci-dessous, A est le nœud que la licence quitte et B celui vers lequel elle est transférée.
Sur le nœud B, exporter le bloc recipient et transmettre le fichier au nœud A :
/opt/pss/tools/pss_lic recipient --out b.rcp
Sur le nœud A, transférer la clé. L’utilitaire demandera une confirmation :
/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]
Vaut confirmation toute réponse commençant par
youY:yesconfirme aussi bien quey. Toute autre réponse, y compris une ligne vide, annule l’opération. La question est posée directement sur le terminal, une redirection de la sortie ne la masque donc pas. En l’absence de terminal — par exemple si la commande est lancée depuis un planificateur — l’utilitaire refuse d’effectuer le transfert et propose d’indiquer--yes.Sur le nœud B, appliquer le fichier reçu et redémarrer le service :
/opt/pss/tools/pss_lic apply --in a2b.v2c sudo systemctl restart pss
Entre le moment où l’étape 2 est exécutée et celui où l’étape 3 aboutit, la licence n’est présente sur aucun des deux nœuds. Planifiez le transfert de sorte que cet intervalle reste court.
Le fichier obtenu est inutile partout ailleurs que sur le nœud B : sur une autre machine, il donne un refus avec le statut 62. Appliquer sur le nœud A un ancien fichier de la même clé donne le statut 70 ou 71 — la clé a déjà été transférée.
Transfert temporaire de la licence¶
detach transfère la licence du produit vers un autre nœud pour une durée donnée, cancel la restitue par anticipation. Comme le transfert permanent, le transfert temporaire ne fonctionne qu’avec une clé logicielle et seulement si les conditions de la licence l’autorisent ; sinon le système de protection répond par un refus portant le statut 67. Avec une licence d’essai, un tel refus est le résultat attendu, non une défaillance.
L’identifiant du produit Perfect Streamer est 2. La durée se donne en secondes avec l’option --duration ; la valeur par défaut est de 120 secondes, indiquez-la donc toujours explicitement en exploitation. La borne supérieure de l’utilitaire lui-même est de 31536000 secondes (un an), mais la limite réelle est fixée par la licence : pour une durée trop longue, le système de protection répond par le refus invalid duration specified. La durée demandée n’est qu’une demande : la valeur définitive est déterminée par la clé et peut s’avérer plus courte.
Sur le nœud B, exporter le bloc recipient et transmettre le fichier au nœud A :
/opt/pss/tools/pss_lic recipient --out b.rcp
Sur le nœud A, transférer la licence pour une journée :
/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
Sur le nœud B, appliquer le fichier reçu et redémarrer le service :
/opt/pss/tools/pss_lic apply --in b.h2r sudo systemctl restart pss
À l’expiration du délai, la licence revient d’elle-même sur le nœud A. La restitution anticipée va dans l’autre sens : le fichier R2H est créé sur le nœud destinataire et appliqué sur le nœud d’origine. Si le délai a déjà expiré à ce moment-là, il n’y a rien à restituer — l’utilitaire signale the R2H: nothing to write et se termine avec le code 1.
Sur le nœud B, relever l’identifiant de la clé transférée et annuler le transfert :
/opt/pss/tools/pss_lic keys --ids /opt/pss/tools/pss_lic cancel --key-id <id> --out back.r2h
Sur le nœud A, appliquer le fichier reçu et redémarrer le service :
/opt/pss/tools/pss_lic apply --in back.r2h sudo systemctl restart pss
L’option --recipient n’est pas valide pour cancel : la licence revient là d’où elle vient. Comme rehost, la commande cancel demande une confirmation. detach elle-même n’en demande pas — le transfert est borné par sa durée et réversible.
Conservez les fichiers intermédiaires avec le même soin que lors d’un transfert permanent : tant que le H2R n’est pas appliqué sur le nœud B, et le R2H sur le nœud A, la licence n’est disponible ni sur l’un ni sur l’autre et ne revient qu’à l’expiration de la durée du transfert.
Codes de sortie¶
Code |
Signification |
|---|---|
|
L’opération a réussi. Le même code est renvoyé lorsque la mise à jour avait déjà été appliquée |
|
Le système de protection a refusé l’opération — le message indique le numéro de statut. Le même code est renvoyé lorsque l’opération s’est terminée sans données, par exemple |
|
Erreur de syntaxe : commande inconnue, option non valide pour la commande, option obligatoire manquante, valeur non valide. Le même code est renvoyé lorsque l’opérateur a répondu « non » à la demande de confirmation |
|
Erreur d’entrée-sortie : le fichier ne peut pas être ouvert, lu ou écrit |
Deux cas méritent d’être pris en compte dans les scripts. Le refus de l’opérateur de confirmer donne le code 2, et non 0 : un contrôle « code non nul = panne » prendra l’annulation pour une défaillance. Un fichier d’entrée illisible donne le code 3, et non 1 : on n’est pas allé jusqu’au système de protection.
# 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
}
Messages et diagnostic¶
Les messages sortent sur stderr avec le préfixe pss_lic:. Un refus du système de protection est toujours imprimé sous la même forme — ce qui a échoué, une description en clair de la cause et le numéro de statut — et, pour les causes courantes, une ligne d’indication s’y ajoute :
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
L’option -q supprime les messages de succès — y compris l’avertissement sur l’écriture vers le terminal — mais ni les erreurs ni les indications. L’option -v ajoute un journal des appels au système de protection : les requêtes, le nombre d’octets lus et écrits, le nom de la fonction appelée. Lors d’un contact avec le support, joignez précisément la sortie obtenue avec -v.
Le groupe de refus le plus fréquent est celui où la clé n’est pas visible ou le service du système de protection ne répond pas (statuts 7, 14, 33, 50 et 80). Vérifiez que le service tourne (systemctl status aksusbd), que la clé USB est branchée et que les bibliothèques du fournisseur sont bien dans le répertoire /var/hasplm — elles sont installées par le paquet pstreamer. Les autres refus figurent dans le tableau ci-dessous ; la première colonne donne le numéro de statut de la ligne de refus, la seconde son texte.
Statut |
Texte du refus |
Cause et solution |
|---|---|---|
37 |
|
Le nœud voit plusieurs clés. Obtenir la liste avec |
42 |
|
La version de aksusbd est antérieure à 9.12 ; mettre à jour le paquet du système de protection |
47 |
|
Le stockage de la licence est endommagé ; un nouveau V2C du fournisseur est nécessaire |
48 |
|
Le répertoire |
54 |
|
Un V2C périmé est appliqué ; en demander un nouveau au fournisseur |
55 |
|
Le fichier de mise à jour est en avance sur l’état de la clé — une mise à jour intermédiaire a été omise ; exporter un C2V récent et appliquer le V2C émis pour celui-ci |
58 |
|
Le bloc recipient est corrompu ; le réexporter sur le nœud destinataire |
60 |
|
Vérifier |
61 |
|
Vérifier |
62 |
|
Le fichier a été émis pour une autre machine et n’est applicable que sur elle |
63 |
|
La durée du transfert dépasse ce que la licence autorise |
64 |
|
Le stockage de la licence est reconnu comme une copie — conséquence du clonage d’un disque ou d’une machine virtuelle ; demander au fournisseur de rééditer la licence pour cette machine |
66 |
|
La clé est inactive |
67 |
|
Le transfert temporaire n’est pas autorisé par les conditions de la licence |
68 |
|
Le nœud voit plusieurs services du système de protection ; |
69 |
|
Le transfert n’est pas autorisé par les conditions de la licence |
70 |
|
La clé a déjà été transférée depuis ce nœud |
71 |
|
Un ancien fichier de transfert est appliqué ; la clé a déjà été transférée depuis ce nœud |
77 |
|
Le nœud destinataire exécute un service du système de protection périmé ; le mettre à jour |
78 |
|
Le stockage de la licence appartient à une autre machine ; un nouveau V2C du fournisseur est nécessaire |
79 |
|
Il existe un second nœud portant le même nom sur le réseau ; renommer le nœud ou faire réémettre la licence |
94 |
|
Les compteurs de mises à jour de la clé et du fichier ont divergé ; exporter un C2V récent et appliquer le V2C émis pour celui-ci |
Pour chaque statut connu, l’utilitaire imprime une description en clair ; un statut non reconnu est imprimé sous la forme unrecognised status avec son numéro.
La commande keys est un cas à part : si le système de protection n’a pas accepté le format détaillé de la liste, l’utilitaire imprime la ligne de refus puis répète la demande au format court. La liste est tout de même produite et le code de sortie reste nul ; une telle ligne de refus précédant un résultat normal ne doit donc pas être lue comme une panne.
La commande version fonctionne même lorsque le système de protection est en panne — c’est précisément ce qui la rend utile comme première étape du diagnostic. Elle imprime la bannière de l’utilitaire et la version de l’API du système de protection ; si le service du système de protection est indisponible, unavailable est imprimé à la place de la version avec un numéro de statut, et le code de sortie reste nul.
Passage depuis la version 1.2¶
Dans la version 2.0, la syntaxe positionnelle a été remplacée par des commandes et des options longues ; les anciennes formes ne sont pas prises en charge. À leur saisie, l’utilitaire imprime le remplacement et se termine avec le code 2.
En 1.2 |
En 2.0 |
|---|---|
|
|
|
|
|
|
|
|
|
|
Le comportement de la sortie a lui aussi changé : en 2.0, seules les données vont sur stdout et les messages sur stderr. Les scripts qui analysaient la sortie mixte de la version 1.2 doivent être corrigés.
