PSS Lic Perfect Streamer Toolkit v2.0 — licença do nó¶
Parte do Perfect Streamer Toolkit — 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 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. 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.
Utilização¶
pss_lic <comando> [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 |
|---|---|---|
|
Aplicar ao nó uma atualização de licença — um arquivo V2C, H2R ou R2H |
|
|
Exportar o estado da chave (C2V) para enviar ao fornecedor |
— |
|
Exportar a impressão digital do nó |
— |
|
Exportar o bloco recipient do nó — a descrição do nó como destinatário de uma transferência |
— |
|
Listar as chaves do sistema de proteção visíveis a partir deste nó |
— |
|
Transferir temporariamente a licença do produto para outro nó; o resultado é um arquivo H2R |
|
|
Transferir a chave para outro nó; o resultado é um arquivo V2C, e a licença é retirada do nó atual |
|
|
Devolver antecipadamente uma licença transferida temporariamente; o resultado é um arquivo R2H |
|
|
Exibir a versão do utilitário e a versão da API do sistema de proteção |
— |
|
Exibir a ajuda integrada |
— |
Opções¶
Opção |
Descrição |
Aceita por |
|---|---|---|
|
Dados de entrada |
|
|
Dados de saída; por padrão |
todos exceto |
|
Bloco recipient do nó receptor |
|
|
Identificador da chave, decimal |
|
|
Identificador do produto, decimal |
|
|
Duração da transferência temporária em segundos; por padrão |
|
|
Instantâneo reduzido do estado; em uma chave de hardware (HL), um arquivo menor |
|
|
Imprimir apenas os identificadores das chaves, um por linha |
|
|
Não solicitar confirmação |
|
|
Somente erros |
todos |
|
Registro detalhado das chamadas ao sistema de proteção |
todos |
|
Exibir as versões e sair |
todos |
|
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 <file> 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:
# 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:
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:
# 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:
# 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
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.
No nó B, exportar o bloco recipient e passar o arquivo ao nó A:
/opt/pss/tools/pss_lic recipient --out b.rcp
No nó A, transferir a chave. O utilitário pedirá confirmação:
/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]
É considerada confirmação qualquer resposta que comece com
youY:yesconfirma do mesmo modo quey. 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.No nó B, aplicar o arquivo recebido e reiniciar o serviço:
/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.
No nó B, exportar o bloco recipient e passar o arquivo ao nó A:
/opt/pss/tools/pss_lic recipient --out b.rcp
No nó A, transferir a licença por um dia:
/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
No nó B, aplicar o arquivo recebido e reiniciar o serviço:
/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.
No nó B, descobrir o identificador da chave transferida e cancelar a transferência:
/opt/pss/tools/pss_lic keys --ids /opt/pss/tools/pss_lic cancel --key-id <id> --out back.r2h
No nó A, aplicar o arquivo recebido e reiniciar o serviço:
/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 |
|---|---|
|
A operação foi realizada. O mesmo código é retornado quando a atualização já havia sido aplicada antes |
|
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 |
|
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 |
|
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.
# 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 |
|
O nó enxerga várias chaves. Obter a lista com |
42 |
|
A versão do aksusbd é inferior a 9.12; atualizar o pacote do sistema de proteção |
47 |
|
O armazenamento da licença está danificado; é necessário um novo V2C do fornecedor |
48 |
|
No diretório |
54 |
|
Está sendo aplicado um V2C desatualizado; solicitar um novo ao fornecedor |
55 |
|
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 |
|
O bloco recipient está corrompido; exportá-lo novamente no nó receptor |
60 |
|
Verificar |
61 |
|
Verificar |
62 |
|
O arquivo foi emitido para outra máquina e só é aplicável nela |
63 |
|
A duração da transferência excede o que a licença permite |
64 |
|
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 |
|
A chave está inativa |
67 |
|
A transferência temporária não é permitida pelas condições da licença |
68 |
|
O nó enxerga vários serviços do sistema de proteção; |
69 |
|
A transferência não é permitida pelas condições da licença |
70 |
|
A chave já foi transferida deste nó |
71 |
|
Está sendo aplicado um arquivo de transferência antigo; a chave já foi transferida deste nó |
77 |
|
O nó receptor executa um serviço do sistema de proteção desatualizado; atualizá-lo |
78 |
|
O armazenamento da licença pertence a outra máquina; é necessário um novo V2C do fornecedor |
79 |
|
Há na rede um segundo nó com o mesmo nome; renomear o nó ou reemitir a licença |
94 |
|
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
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.
