--- title: PSS Lic Perfect Streamer Toolkit v2.0 — licença do nó url: https://doc2.pstreamer.tv/pt/manual/toolkit/pss_lic.html lang: pt-BR product: Perfect Streamer version: 2.0.1.264 --- # PSS Lic Perfect Streamer Toolkit v2.0 — licença do nó Parte do **Perfect Streamer Toolkit** — [https://pstreamer.tv](https://pstreamer.tv) Utilitário de console para gerenciar a licença de um nó: aplica a atualização de licença enviada pelo fornecedor, exporta o estado da chave para a solicitação de ativação e transfere a licença de um nó para outro. Trabalha com a mesma chave do sistema de proteção que o próprio streamer — de software (SL) ou de hardware (HL). O acesso à chave é feito pelo serviço **aksusbd** do sistema de proteção, por isso o utilitário só funciona onde esse serviço está em execução. A ferramenta faz parte do pacote **pstreamer** e, após a instalação, encontra-se em `/opt/pss/tools/pss_lic` — não é preciso instalar nada separadamente. ## Quando o utilitário é necessário A tela [Licença](../webui/administration.md#webui-license) sabe exportar o C2V e aplicar a chave V2C recebida, mas nada além disso. Pelo console estão disponíveis todas as operações com a chave, e só daqui se faz o restante: - ativação e atualização da licença em um nó sem acesso à interface web; - automação: implantação de um parque de nós, renovação planejada de licenças, verificações a partir de um sistema de monitoramento; - transferência de uma licença entre nós — permanente ou temporária. O utilitário não precisa de permissões de root: a gravação no armazenamento seguro é feita pelo serviço do sistema de proteção, e não pelo próprio utilitário. Root só é necessário para gravar o arquivo de saída em um diretório do sistema e para reiniciar o serviço **pss** após a troca da licença. A ativação inicial da licença de teste não é feita por este utilitário, e sim pelo script `/opt/pss/tools/activate.sh` — veja [Ativação temporária e inicialização](../first_start/index.md#first-start-activation). O script chama o **pss_lic** por conta própria e em seguida reinicia o serviço **pss** e habilita sua inicialização automática. O procedimento para obter uma licença permanente está descrito em [Ativação permanente](../first_start/index.md#first-start-permanent-activation). ## Utilização ``` pss_lic [opções] ``` Executado sem argumentos, com `-h` ou com `--help`, imprime a ajuda integrada e termina com o código `0`. As opções vêm depois do comando; antes do comando só são admitidos `-h`, `--help`, `-V` e `--version`. Argumentos posicionais não são aceitos — tudo é indicado por opções. ### Comandos | Comando | Finalidade | Opções obrigatórias | | --- | --- | --- | | `apply` | Aplicar ao nó uma atualização de licença — um arquivo V2C, H2R ou R2H | `--in` | | `c2v` | Exportar o estado da chave (C2V) para enviar ao fornecedor | — | | `fingerprint` | Exportar a impressão digital do nó | — | | `recipient` | Exportar o bloco recipient do nó — a descrição do nó como destinatário de uma transferência | — | | `keys` | Listar as chaves do sistema de proteção visíveis a partir deste nó | — | | `detach` | Transferir temporariamente a licença do produto para outro nó; o resultado é um arquivo H2R | `--product-id` | | `rehost` | Transferir a chave para outro nó; o resultado é um arquivo V2C, e a licença é retirada do nó atual | `--key-id` | | `cancel` | Devolver antecipadamente uma licença transferida temporariamente; o resultado é um arquivo R2H | `--key-id` | | `version` | Exibir a versão do utilitário e a versão da API do sistema de proteção | — | | `help` | Exibir a ajuda integrada | — | ### Opções | Opção | Descrição | Aceita por | | --- | --- | --- | | `-i, --in ` | Dados de entrada | `apply` | | `-o, --out ` | Dados de saída; por padrão `-`, ou seja, stdout | todos exceto `version` e `help` | | `-r, --recipient ` | Bloco recipient do nó receptor | `detach`, `rehost` | | `-k, --key-id ` | Identificador da chave, decimal | `c2v`, `keys`, `detach`, `rehost`, `cancel` | | `-p, --product-id ` | Identificador do produto, decimal | `detach` | | `--duration ` | Duração da transferência temporária em segundos; por padrão `120`, no máximo `31536000` | `detach` | | `--fast` | Instantâneo reduzido do estado; em uma chave de hardware (HL), um arquivo menor | `c2v` | | `--ids` | Imprimir apenas os identificadores das chaves, um por linha | `keys` | | `-y, --yes` | Não solicitar confirmação | `rehost`, `cancel` | | `-q, --quiet` | Somente erros | todos | | `-v, --verbose` | Registro detalhado das chamadas ao sistema de proteção | todos | | `-V, --version` | Exibir as versões e sair | todos | | `-h, --help` | Exibir a ajuda | todos | Uma opção que não consta na linha do seu comando é um erro de sintaxe, e não um sinalizador ignorado em silêncio: o utilitário informa, por exemplo, `--key-id is not valid for 'fingerprint'`, e muitas vezes acrescenta uma linha com a causa. Os valores de `--key-id`, `--product-id` e `--duration` são apenas números decimais a partir de `1`; zero não é admitido. ### Entrada e saída Qualquer argumento de arquivo — `--in`, `--out`, `--recipient` — aceita `-`: leitura do stdin, escrita no stdout. Por padrão a saída vai para o stdout. No **stdout** chegam apenas os próprios dados — o bloco de licença. As mensagens de sucesso, os avisos e os erros vão para o **stderr** e começam com o prefixo `pss_lic:`. Graças a isso, qualquer comando pode ser redirecionado para um arquivo ou para um pipe sem analisar a saída. Se nenhum arquivo de saída for indicado e o stdout for um terminal, os comandos `detach`, `rehost` e `cancel` avisam que o resultado da transferência acabará na tela e será perdido: ``` pss_lic: writing the V2C to the terminal; use --out to keep it ``` O arquivo de entrada é verificado antes de recorrer ao sistema de proteção: são rejeitados um arquivo vazio, um arquivo que contenha um byte nulo e um arquivo maior que 8 MiB. A marca de ordem de bytes UTF-8 no início do arquivo — alguns clientes de e-mail e editores a acrescentam — é removida automaticamente. ## Aplicação de uma atualização de licença O arquivo enviado pelo fornecedor é aplicado com um único comando: ```bash # 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 - ``` Em caso de sucesso, o stderr exibe: ``` pss_lic: update applied ``` **O utilitário não reinicia o serviço.** Um streamer em funcionamento mantém a licença anterior na memória, por isso, após trocar a licença, reinicie o serviço manualmente: ```bash sudo systemctl restart pss ``` Aplicar novamente o mesmo arquivo não é considerado erro: o utilitário informa `this V2C is already installed, nothing to do` e termina com o código `0`. É nessa propriedade que se apoia a repetibilidade do script `activate.sh`. Não confunda esta mensagem com a recusa `the update is older than the one already installed (stale or rolled-back V2C)` (estado 54) — esta significa que está sendo aplicado um arquivo desatualizado e termina com o código `1`. Nesse caso, solicite ao fornecedor um V2C novo. Com o comando `apply` são aplicados os três tipos de atualização: o V2C do fornecedor, o H2R de uma transferência temporária e o R2H de sua devolução. ## Exportação dos dados para o fornecedor A solicitação de ativação ou de ampliação da licença é construída a partir de um arquivo C2V — um instantâneo do estado atual da chave: ```bash # export the key state for the vendor /opt/pss/tools/pss_lic c2v --out host.c2v ``` Se o nó enxergar várias chaves, o sistema de proteção não adivinhará qual é a desejada e responde com a recusa `too many keys match the scope` (estado 37). O comando `keys` lista os identificadores das chaves: ```bash # 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 --out host.c2v ``` Sem `--ids`, o comando `keys` imprime a lista de chaves e de suas licenças na forma em que o sistema de proteção a devolve — um documento XML, e não uma tabela. Para escolher um valor de `--key-id` basta a forma `--ids`. A opção `--fast` solicita à chave um instantâneo reduzido do estado. Em uma chave de hardware (HL) esse arquivo fica cerca de uma ordem de magnitude menor que o completo; em uma de software (SL) o tamanho é o mesmo — difere apenas pelos dados que contém. **O conteúdo de um C2V não pode ser lido no nó**, por isso o identificador da chave é obtido com o comando `keys` e não do próprio arquivo. **Um C2V — uma solicitação.** Não envie ao fornecedor o mesmo C2V duas vezes: o segundo V2C emitido a partir dele pode ser aplicado apenas parcialmente. Para uma nova solicitação, exporte o C2V novamente. Os comandos `fingerprint` e `recipient` exportam a impressão digital do nó e o bloco recipient. A impressão digital descreve a máquina e é o que o fornecedor precisa quando ainda não há licença no nó: é a ela que uma nova chave de software é vinculada. O bloco recipient descreve o nó como destinatário de uma transferência e não é necessário ao fornecedor, e sim ao segundo nó — veja Transferência da licença para outro nó. Ambos se referem ao nó como um todo, e não a uma chave isolada, por isso a opção `--key-id` não é válida para eles. ## Transferência da licença para outro nó A transferência de uma licença entre nós só é possível com uma chave de software (SL): uma chave de hardware viaja junto com o próprio dispositivo e não é afetada pelos comandos do utilitário. A licença de teste não é transferível. A possibilidade de transferência é definida pelas condições da licença; se não estiver prevista, o sistema de proteção responde com a recusa `rehost is not allowed for this licence`. Esclareça isso previamente com o fornecedor. > **Aviso** > > O `rehost` retira a licença do nó atual. O arquivo obtido só pode ser aplicado no nó cujo bloco recipient foi passado em `--recipient`. Se o arquivo for perdido ou o nó receptor estiver inacessível, a licença se perde junto: não há retorno local. Indique sempre `--recipient` e salve o resultado em um arquivo, e não na tela. A transferência ocorre em três etapas e envolve os dois nós. A seguir, A é o nó do qual a licença sai e B é o nó para o qual ela é transferida. 1. No nó **B**, exportar o bloco recipient e passar o arquivo ao nó A: ```bash /opt/pss/tools/pss_lic recipient --out b.rcp ``` 2. No nó **A**, transferir a chave. O utilitário pedirá confirmação: ```bash /opt/pss/tools/pss_lic rehost --key-id --recipient b.rcp --out a2b.v2c ``` ``` pss_lic: about to move the licence off this host. This cannot be undone. Continue? [y/N] ``` É considerada confirmação qualquer resposta que comece com `y` ou `Y`: `yes` confirma do mesmo modo que `y`. Qualquer outra resposta, inclusive uma linha vazia, cancela a operação. A pergunta é feita diretamente no terminal, por isso redirecionar a saída não a esconde. Se não houver terminal — por exemplo, se o comando for iniciado por um agendador — o utilitário se recusa a executar a transferência e sugere indicar `--yes`. 3. No nó **B**, aplicar o arquivo recebido e reiniciar o serviço: ```bash /opt/pss/tools/pss_lic apply --in a2b.v2c sudo systemctl restart pss ``` Do momento em que a etapa 2 é executada até a etapa 3 ser concluída, a licença não está em nenhum dos dois nós. Planeje a transferência de modo que esse intervalo seja curto. O arquivo obtido é inútil em qualquer lugar que não o nó B: em outra máquina ele dá uma recusa com o estado 62. Tentar aplicar no nó A um arquivo antigo da mesma chave dá o estado 70 ou 71 — a chave já foi transferida. ## Transferência temporária da licença O `detach` transfere a licença do produto para outro nó por um prazo determinado, e o `cancel` a devolve antecipadamente. Assim como a transferência permanente, a temporária só funciona com uma chave de software e apenas se as condições da licença a permitirem; caso contrário, o sistema de proteção responde com uma recusa de estado 67. Com uma licença de teste, essa recusa é o resultado esperado, não um defeito. O identificador de produto do Perfect Streamer é `2`. O prazo é indicado em segundos com a opção `--duration`; **o valor padrão é de 120 segundos**, portanto, em operação, sempre o indique explicitamente. O limite superior do próprio utilitário é de `31536000` segundos (um ano), mas o limite real é definido pela licença: com um prazo longo demais, o sistema de proteção responde com a recusa `invalid duration specified`. O prazo solicitado é apenas isso — uma solicitação: o valor final é determinado pela chave e pode ser menor. 1. No nó **B**, exportar o bloco recipient e passar o arquivo ao nó A: ```bash /opt/pss/tools/pss_lic recipient --out b.rcp ``` 2. No nó **A**, transferir a licença por um dia: ```bash /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 ``` 3. No nó **B**, aplicar o arquivo recebido e reiniciar o serviço: ```bash /opt/pss/tools/pss_lic apply --in b.h2r sudo systemctl restart pss ``` Ao expirar o prazo, a licença volta ao nó A por conta própria. A devolução antecipada vai no sentido inverso: o arquivo R2H é criado no nó receptor e aplicado no nó de origem. Se o prazo já tiver expirado até lá, não há o que devolver — o utilitário informa `the R2H: nothing to write` e termina com o código `1`. 1. No nó **B**, descobrir o identificador da chave transferida e cancelar a transferência: ```bash /opt/pss/tools/pss_lic keys --ids /opt/pss/tools/pss_lic cancel --key-id --out back.r2h ``` 2. No nó **A**, aplicar o arquivo recebido e reiniciar o serviço: ```bash /opt/pss/tools/pss_lic apply --in back.r2h sudo systemctl restart pss ``` A opção `--recipient` não é válida para `cancel`: a licença volta de onde veio. Assim como `rehost`, o comando `cancel` pede confirmação. A própria `detach` não pede — a transferência é limitada pelo prazo e é reversível. Guarde os arquivos intermediários com o mesmo cuidado que em uma transferência permanente: enquanto o H2R não for aplicado no nó B, e o R2H no nó A, a licença não está disponível em nenhum dos dois e só retorna ao expirar a duração da transferência. ## Códigos de saída | Código | Significado | | --- | --- | | `0` | A operação foi realizada. O mesmo código é retornado quando a atualização já havia sido aplicada antes | | `1` | O sistema de proteção recusou a operação — a mensagem indica o número do estado. O mesmo código é retornado quando a operação terminou sem dados, por exemplo `the R2H: nothing to write` | | `2` | Erro de sintaxe: comando desconhecido, opção não válida para o comando, opção obrigatória ausente, valor não válido. O mesmo código é retornado quando o operador respondeu «não» à solicitação de confirmação | | `3` | Erro de entrada/saída: o arquivo não pode ser aberto, lido ou gravado | Dois casos vale a pena prever nos scripts. A recusa do operador em confirmar é o código `2`, e não `0`: uma verificação do tipo «código diferente de zero significa falha» tomará o cancelamento por um defeito. Um arquivo de entrada ilegível é o código `3`, e não `1`: não se chegou ao sistema de proteção. ```bash # 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 } ``` ## Mensagens e diagnóstico As mensagens saem no stderr com o prefixo `pss_lic:`. Uma recusa do sistema de proteção é sempre impressa da mesma forma — o que falhou, uma descrição textual da causa e o número do estado — e, para as causas mais comuns, acrescenta-se uma linha de dica: ``` 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 ``` A opção `-q` remove as mensagens de sucesso — inclusive o aviso sobre a saída no terminal — mas não os erros nem as dicas. A opção `-v` acrescenta um registro das chamadas ao sistema de proteção: as requisições, o número de bytes lidos e gravados, o nome da função chamada. Ao entrar em contato com o suporte, anexe justamente a saída obtida com `-v`. O grupo de recusas mais frequente é a chave não estar visível ou o serviço do sistema de proteção não responder (estados 7, 14, 33, 50 e 80). Verifique se o serviço está em execução (`systemctl status aksusbd`), se a chave USB está conectada e se as bibliotecas do fornecedor estão no diretório `/var/hasplm` — elas são instaladas pelo pacote **pstreamer**. As demais recusas estão na tabela abaixo; na primeira coluna, o número do estado da linha de recusa; na segunda, o seu texto. | Estado | Texto da recusa | Causa e solução | | --- | --- | --- | | 37 | `too many keys match the scope` | O nó enxerga várias chaves. Obter a lista com `keys --ids` e indicar `--key-id` | | 42 | `License Manager version is too old` | A versão do **aksusbd** é inferior a 9.12; atualizar o pacote do sistema de proteção | | 47 | `secure storage contains garbage` | O armazenamento da licença está danificado; é necessário um novo V2C do fornecedor | | 48 | `vendor library cannot be found` | No diretório `/var/hasplm` não há as bibliotecas do fornecedor; elas são instaladas pelo pacote **pstreamer** | | 54 | `the update is older than the one already installed (stale or rolled-back V2C)` | Está sendo aplicado um V2C desatualizado; solicitar um novo ao fornecedor | | 55 | `another update must be installed first` | O arquivo de atualização está à frente do estado da chave — foi omitida uma atualização intermediária; exportar um C2V novo e aplicar o V2C emitido para ele | | 58 | `invalid XML recipient parameter` | O bloco recipient está corrompido; exportá-lo novamente no nó receptor | | 60 | `the scope does not select a unique Product` | Verificar `--product-id` e, em um nó com várias chaves, acrescentar `--key-id` | | 61 | `invalid Product information` | Verificar `--product-id`; no Perfect Streamer ele é `2` | | 62 | `unknown recipient; this blob may only be applied on the recipient it was made for` | O arquivo foi emitido para outra máquina e só é aplicável nela | | 63 | `invalid duration specified` | A duração da transferência excede o que a licença permite | | 64 | `cloned secure storage detected` | O armazenamento da licença foi reconhecido como uma cópia — consequência da clonagem de um disco ou de uma máquina virtual; solicitar ao fornecedor a reemissão da licença para esta máquina | | 66 | `the specified key is inactive` | A chave está inativa | | 67 | `no detachable Feature exists` | A transferência temporária não é permitida pelas condições da licença | | 68 | `the scope does not select a unique host` | O nó enxerga vários serviços do sistema de proteção; `fingerprint` e `recipient` referem-se ao serviço, não à chave | | 69 | `rehost is not allowed for this licence` | A transferência não é permitida pelas condições da licença | | 70 | `the licence was rehosted to another machine` | A chave já foi transferida deste nó | | 71 | `an old rehost licence is being applied` | Está sendo aplicado um arquivo de transferência antigo; a chave já foi transferida deste nó | | 77 | `the recipient of the requested operation is older than expected` | O nó receptor executa um serviço do sistema de proteção desatualizado; atualizá-lo | | 78 | `secure storage ID mismatch` | O armazenamento da licença pertence a outra máquina; é necessário um novo V2C do fornecedor | | 79 | `duplicate host name while the key uses host name fingerprinting` | Há na rede um segundo nó com o mesmo nome; renomear o nó ou reemitir a licença | | 94 | `the key and the update are out of sync (update counters diverged)` | Os contadores de atualizações da chave e do arquivo divergiram; exportar um C2V novo e aplicar o V2C emitido para ele | Para cada estado conhecido o utilitário imprime uma descrição textual; um estado não reconhecido é impresso como `unrecognised status` com o seu número. Um caso à parte é o comando `keys`: se o sistema de proteção não aceitou o formato detalhado da listagem, o utilitário imprime a linha de recusa e depois repete a requisição no formato curto. A listagem é produzida mesmo assim e o código de saída permanece zero, por isso essa linha de recusa antes de um resultado normal não deve ser lida como falha. O comando `version` funciona mesmo com o sistema de proteção defeituoso — é justamente isso que o torna útil como primeiro passo do diagnóstico. Ele imprime o banner do utilitário e a versão da API do sistema de proteção; se o serviço do sistema de proteção estiver indisponível, no lugar da versão é impresso `unavailable` com um número de estado, e o código de saída permanece zero. ## Migração da versão 1.2 Na versão 2.0 a sintaxe posicional foi substituída por comandos e opções longas; as formas anteriores não são suportadas. Ao serem digitadas, o utilitário imprime a substituição e termina com o código `2`. | Em 1.2 | Em 2.0 | | --- | --- | | `pss_lic u ` | `pss_lic apply --in ` | | `pss_lic i [chave] [arquivo]` | `pss_lic c2v [--key-id ] [--out ]` | | `pss_lic d [arquivo]` | `pss_lic detach --product-id [--out ]` | | `pss_lic r [arquivo]` | `pss_lic rehost --key-id [--out ]` | | `pss_lic f [arquivo]` | `pss_lic fingerprint [--out ]` | O comportamento da saída também mudou: na 2.0 apenas os dados vão para o stdout e as mensagens para o stderr. Os scripts que analisavam a saída mista da versão 1.2 precisam ser corrigidos.