Editar, verificar e transferir as configurações¶

O procedimento para editar o pss.json manualmente, para transferir as configurações para outra versão do Perfect Streamer e para reutilizá-las em outro nó.

Leia primeiro O arquivo de configuração pss.json — pelo menos as seções sobre a esparsidade do arquivo, sobre a leitura do arquivo e sobre as regras invisíveis. Aqui está escrito o que fazer; lá, por quê — e as razões não são óbvias. Em resumo: no arquivo estão apenas as diferenças em relação aos valores padrão, uma chave desconhecida o serviço ignora sem parar, e um único valor inaceitável descarta todo o arquivo.

Editar o arquivo muda a próxima inicialização. Para alterar um serviço em funcionamento, use a interface web ou a API HTTP (Gerenciamento pela API HTTP).

O que será necessário¶

O esquema¶

Com a documentação são fornecidos dois arquivos: o esquema estrito pss.schema.json e o permissivo pss.compat.schema.json. Em que diferem e o que cada um verifica está em Dois arquivos de esquema; ali mesmo se diz por que uma verificação permissiva por si só não basta.

Os esquemas são parte da documentação, e não do produto. No nó eles não existem, e no diretório de configurações não há cópia alguma: procurá-la ali não faz sentido. Ambos estão no site da documentação, no diretório da sua versão:

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

Pegue o esquema da sua versão e mantenha-o na máquina onde você edita o arquivo.

Verifique a linha de versão dentro do esquema antes de confiar nele. Uma verificação pelo esquema de outra versão dá respostas confiantes e erradas.

O validador¶

Serve qualquer validador de JSON Schema com suporte ao draft 2020-12. O esquema usa construções condicionais, por isso um validador limitado a edições anteriores aceitará um arquivo que deveria ter rejeitado; vale a pena verificar isso ao escolher outra ferramenta.

O recomendado é o jv, um programa independente de código aberto sob licença Apache 2.0; as compilações são publicadas na página de versões do projeto jsonschema.

Pegue o arquivo compactado da sua plataforma, descompacte-o e coloque o programa em um diretório que já esteja no PATH:

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

São publicadas compilações para Linux, Windows e macOS.

Nota

A compilação para Linux exige um conjunto de bibliotecas de sistema razoavelmente recente: funciona em RHEL, AlmaLinux e Rocky 9, Debian 12, Ubuntu 22.04 e mais novos, e em uma distribuição mais antiga não inicia de jeito nenhum. Isso não é obstáculo: verifique o arquivo em uma estação de trabalho e leve ao nó um já verificado. Aliás, assim é mais correto — o arquivo é pequeno e no nó não é preciso um validador.

Uma ferramenta para as verificações que o esquema não faz¶

Duas regras não são exprimíveis em JSON Schema de modo algum: a unicidade dos identificadores e o comprimento igual dos arrays pareados. Os comandos de As verificações que o esquema não faz usam o jq, presente no repositório de qualquer distribuição:

No RHEL, AlmaLinux e Rocky:

$ sudo dnf install jq

No Debian e Ubuntu:

$ sudo apt install jq

Alterar um parâmetro¶

Execute a sequência por inteiro. As etapas que costumam ser puladas são a 5 e a 7 — e são justamente elas que apanham os erros silenciosos.

Pare o serviço.
```
$ sudo systemctl stop pss
```
O arquivo de um nó em funcionamento não deve ser editado: o serviço sobrescreve o pss.json conforme o seu próprio cronograma com o que mantém na memória, e a edição desaparecerá sem uma única mensagem.
Salve uma cópia — com um nome que ainda não exista.
```
$ cp pss.json pss.json.$(date +%Y%m%d_%H%M%S)
```
É o único caminho de volta: o serviço não mantém uma cópia de segurança automática da configuração em uso. Não use o mesmo nome de cópia duas vezes: em uma segunda passagem por esta sequência você sobrescreveria o único arquivo são com o que uma tentativa malsucedida deixou para trás.
Edite.

Altere os valores no lugar. Não mova chaves e não mova entradas de arrays — o porquê está em A ordem das chaves dentro de um objeto importa e A ordem das entradas em um array não é preservada. Ao acrescentar uma entrada a um array, dê a ela um id explícito e único: ninguém o atribuirá por você (Os identificadores são atribuídos manualmente). Dê à entrada também as suas chaves de ancoragem — stream-name em um fluxo, type e o endereço em uma entrada e uma saída, name em uma placa e um armazenamento, e assim por diante (Estrutura do documento): sem elas o arquivo será rejeitado por inteiro.
Remova os seus comentários. A leitura admite apenas os de bloco /* ... */, as ferramentas JSON estritas não aceitam nem esses, e o serviço apagará os comentários de qualquer forma na primeira gravação (Os comentários são lidos, mas não preservados).
Verifique o arquivo pelo esquema.
```
$ jv pss.schema.json pss.json
```
Um código de retorno zero significa que a verificação passou. Caso contrário, é impressa uma linha por erro, e cada uma nomeia o lugar exato:
```
jsonschema validation failed with 'pss.schema.json#'
  - at '/stream/3/input/1/passphrase': false schema
```
Lê-se assim: a segunda entrada do quarto fluxo tem uma chave passphrase que não pertence ao transporte escolhido pela sua chave type. As posições são contadas a partir de zero.
Execute as verificações da seção As verificações que o esquema não faz.
Inicie o serviço e leia o log.
```
$ sudo systemctl start pss
$ grep -iE 'ignore|clamped|config' /var/log/pss/main.log
```
O serviço grava o log em um arquivo; o diretório é definido pela chave log-dir do pss.properties, por padrão /var/log/pss. Essas linhas não aparecerão em journalctl -u pss enquanto no pss.properties não estiver ativado log-to-console ou log-to-syslog.

Uma linha sobre uma chave ignorada significa que o esquema não corresponde à compilação instalada — em geral ele é mais antigo ou mais novo. Uma linha sobre um valor levado ao limite significa que um número saiu da faixa e foi corrigido em silêncio, e que o arquivo já foi regravado com o valor corrigido.

Se o serviço não iniciou, veja o diretório bad/ — Recuperação após um arquivo rejeitado.
Verifique o resultado pela interface, e não pelo arquivo. O arquivo não mostra as configurações que ficaram no valor padrão, portanto por ele nada pode ser confirmado. Leia a configuração de volta pela API HTTP: ali são devolvidas todas as chaves.

Transferir as configurações para outra versão¶

No arquivo não há marca de versão, e o serviço não realiza conversão alguma. Uma configuração de outra versão é aplicada como está: as chaves que já não existem são ignoradas; as chaves que ainda não existiam assumem os valores padrão. Nem uma nem outra são informadas. O procedimento abaixo torna ambas visíveis.

Pegue o pss.schema.json da versão de destino — aquela que lerá o arquivo, e não aquela que o gravou.
Primeira passagem, permissiva. Verifica tipos, faixas e chaves obrigatórias, mas tolera as chaves de que a versão de destino abriu mão:
```
$ jv pss.compat.schema.json pss.json
```
Tudo o que é informado aqui é um problema de verdade: um valor fora da faixa, uma chave que mudou de forma, um identificador ausente.
Segunda passagem, estrita. Lista as chaves que a versão de destino já não conhece:
```
$ jv pss.schema.json pss.json
```
Cada reclamação nova em relação à segunda etapa é uma chave que a nova versão ignorará em silêncio. Decida em cada caso se a configuração foi renomeada, substituída por outro mecanismo ou abolida, e em qualquer caso apague a chave do arquivo: deixada ali, ela não custa nada em operação, mas esconde o fato de que a configuração não faz mais nada.

A passagem estrita responde também pela pertença de uma chave a uma variante, que o esquema permissivo não verifica — por isso não se pode limitar a uma única passagem permissiva.
Compare os valores padrão das duas versões.

No arquivo estão apenas as diferenças em relação aos padrões, por isso uma configuração que você nunca tocou está ausente do arquivo — e se o seu padrão mudou, o comportamento mudará junto com a atualização, em silêncio. O arquivo e o esquema são cegos a isso por construção: o esquema da versão de destino não mostrará tal mudança.

Isso só é visível na configuração vigente, porque a API HTTP devolve todas as chaves, inclusive as que ficaram no valor padrão. Leia-a no nó de origem antes da atualização e em um nó da versão de destino: as divergências nas chaves que você nunca definiu são justamente os padrões que mudaram.
Continue a partir da etapa 4 de Alterar um parâmetro.

Aviso

Não transfira o pss.json para trás, para uma versão mais antiga. Uma chave que apareceu depois será ignorada, mas um valor que hoje é admissível e antes não era será levado ao limite ou descartará todo o arquivo.

Transferir as configurações para outro nó¶

A configuração é portátil, mas parte das chaves identifica o nó ou abre acesso a ele, e copiá-las sem alteração é, na melhor das hipóteses, confuso e, na pior, um vazamento.

Substitua todos os segredos. A lista deles está em Valores que não devem ser repassados. Não os zere: parte das chaves não aceita valor vazio e descartará todo o arquivo. Coloque uma substituição evidente, de comprimento verossímil, e defina os valores reais pela interface web após a primeira inicialização.
Altere os dados de identificação do nó: o nome do nó precisa ser único dentro do domínio, e a observação, o papel e a região descrevem esta máquina, e não aquela de onde foram copiados.
Revise tudo o que nomeia uma máquina específica: endereços de escuta, nomes de interfaces, caminhos dos armazenamentos, números de placas. Um caminho inexistente e uma placa não instalada o esquema não apanhará.
Revise a seção Meshwork. Os endereços, nomes e segredos dos peers são arrays pareados correspondidos por posição (Os arrays pareados são correspondidos por posição): ao apagar uma entrada, apague a entrada correspondente de cada array. Aqui uma divergência de comprimento descarta o arquivo por inteiro, portanto confira-os de antemão — O comprimento igual dos arrays pareados.
Compare as licenças dos dois nós. As configurações daquilo que a licença de destino não inclui se revelarão chaves desconhecidas: a seção sairá do arquivo com um único aviso no log. Isso é mais perceptível na recepção DVB.
Continue a partir da etapa 4 de Alterar um parâmetro.

As verificações que o esquema não faz¶

Identificadores repetidos¶

Duas entradas de um mesmo array com o mesmo id descartam todo o arquivo. A unicidade de uma chave entre as entradas de um array não é exprimível em JSON Schema, por isso ela é verificada à parte:

$ 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

Um resultado vazio é o que se quer. Todo o resto nomeia o array e os identificadores nele repetidos. Um id ausente o comando conta como zero: é assim que o serviço o lê no array stream, onde duas entradas sem identificador colidem. Em qualquer outro array uma entrada sem id descarta o arquivo por si só, portanto um identificador zero fora de stream já é um achado.

O comprimento igual dos arrays pareados¶

Onde os arrays são correspondidos por posição, o número de entradas neles precisa coincidir. Para a seção Meshwork:

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

Os três números precisam ser iguais. A verificação aqui não é de higiene: o serviço detecta sozinho uma divergência de comprimento e descarta todo o arquivo — nos peers Meshwork, nas variáveis de ambiente, nas listas «antes — depois» da reatribuição de PID (mpegts-pid-old e mpegts-pid-new), nas listas de troca de idioma (mpegts-lang-set-pid e mpegts-lang-set) e no par biss-pnr e biss-key. No quarteto de endereços RIST (rist-addr-*) o arquivo não é descartado, mas a entrada não abre e o motivo vai para o log.

A ordem das chaves¶

O esquema não vê a ordem das chaves, e ela importa em três lugares — A ordem das chaves dentro de um objeto importa. Não há comando para isso: a regra consiste em não mover nada e, em uma entrada nova acrescentada manualmente, colocar type, mpts e mode em primeiro lugar.

Referências entre seções¶

Os números que apontam para outra parte do arquivo — um armazenamento, uma fonte do guia de programação, uma placa de recepção, um fluxo de origem — não são verificados pelo esquema. Se o destino não existir, o serviço informará isso na inicialização.

Recuperação após um arquivo rejeitado¶

Se o pss.json não puder ser lido, o serviço o move para o diretório bad/ com um nome contendo data e hora e sobe com a configuração restaurada anteriormente ou, na ausência dela, com as configurações padrão (pss_default.json, Comportamento na inicialização e em erros de configuração). Elas não contêm fluxo algum, por isso nesse estado o nó funciona vazio. Que as configurações não puderam ser carregadas e que o nó funciona com as de reserva é informado por um alerta na inicialização.

Não reinicie o nó mais uma vez. Um reinício não prejudica a cópia arquivada, mas a configuração em funcionamento agora são as configurações padrão, e não há motivo para deixá-las serem salvas por cima de coisa alguma.
Encontre o arquivo arquivado no diretório bad/. O mais recente é a sua configuração.
Descubra o que há de errado com ele:
```
$ jv pss.schema.json bad/pss_20260809_101500.json
```
O log da inicialização malsucedida também nomeia a chave e o motivo.
Corrija, verifique até obter um resultado limpo, copie de volta por cima do pss.json e inicie.

Se a cópia arquivada sumiu ou também está danificada, a última esperança é a cópia feita na etapa 2 de Alterar um parâmetro. É para isso que essa etapa existe.

Sugestões no editor¶

A maioria dos editores sugerirá os nomes das chaves, mostrará os valores admissíveis e sublinhará um erro durante a digitação, se você lhes indicar o esquema.

Vincule o esquema pelo nome do arquivo, nas configurações do próprio editor: nos editores que funcionam pelo servidor de linguagem JSON é a entrada json.schemas, que associa o nome pss.json ao esquema. O esquema pode ser indicado tanto por um arquivo local quanto pelo endereço da versão publicada. O arquivo local é preferível: funciona sem rede e fixa a versão com firmeza, ao passo que em um endereço é fácil digitar a versão errada.