El archivo de configuración pss.json

La página describe el formato del archivo pss.json: cómo está construido el documento, qué acepta el servicio al leerlo y qué se pierde al escribirlo. Está dirigida a quienes editan el archivo directamente o trasladan los ajustes a otro nodo.

Una edición del archivo surte efecto desde el siguiente arranque. Para cambiar la configuración de un servicio en funcionamiento, utilice la interfaz web o la API HTTP (Gestión mediante la API HTTP): solo ellas aplican un cambio de inmediato e informan del resultado.

Los procedimientos paso a paso de edición, comprobación y traslado: Editar, comprobar y trasladar los ajustes.

Qué es este archivo

pss.json es el archivo de configuración en uso, en el directorio /opt/pss/config. El orden de carga, el repliegue a pss_back.json y pss_default.json y el archivo histórico de los archivos dañados en el directorio bad/ se describen en Comportamiento en el arranque y ante errores de configuración.

Una consecuencia de ese orden hay que tenerla presente antes de abrir el archivo en un editor: un solo valor inaceptable cuesta todos los flujos. El archivo no se repara por partes: se rechaza entero, y el repliegue lleva a pss_default.json, donde no hay flujo alguno. La copia de seguridad pss_back.json existe únicamente allí donde los ajustes se han restaurado al menos una vez a través de la interfaz web (Mantenimiento); el servicio no mantiene una copia periódica. Precisamente por eso el archivo se comprueba antes de que el servicio lo lea.

El archivo no es una descripción completa de la configuración: guarda solo las diferencias respecto a los valores con los que se compiló el producto. Lo que de ello se deriva está en la sección siguiente; es lo más importante que hay que entender antes de editar.

En el mismo directorio se encuentra pss.properties: los parámetros globales del proceso (rutas a los datos y a los registros y similares). Es un archivo «clave=valor» con su propia sintaxis, no tiene relación con JSON y nada de lo dicho aquí le concierne.

En el archivo solo están las diferencias respecto a los valores por defecto

Al escribir el archivo, el servicio omite todo valor simple que coincida con el valor por defecto. Solo se guardan las diferencias.

De ello se derivan tres cosas, y las tres ocurren en la práctica:

• Por el archivo no se puede saber cómo está configurado el servicio. Una clave ausente significa el valor por defecto, y ese valor no está escrito en ninguna parte del archivo. Para leer la configuración vigente al completo, pídasela al servicio en funcionamiento a través de la API HTTP: allí se devuelven todas las claves, incluidas las que se han quedado en su valor por defecto.

• Escribir una clave con su valor por defecto es inútil. Ese valor se acepta y en el siguiente guardado del archivo desaparece.

• Un cambio del valor por defecto entre versiones cambia el comportamiento en silencio. Si el nodo nunca ha redefinido esa clave, no está en el archivo, y tras una actualización empezará a funcionar con el nuevo valor por defecto desde el primer arranque, sin que el archivo diga nada al respecto. Este es el principal riesgo al trasladar los ajustes entre versiones, y por el propio archivo no se detecta. Solo hay una manera de ver ese cambio: leer la configuración vigente de ambas versiones a través de la API HTTP, donde también se devuelven los valores por defecto.

La omisión afecta solo a los valores sueltos. Las propias secciones y listas se escriben siempre, aunque dentro no quede nada: "user-default": {} es una sección cuyas claves están todas en sus valores por defecto, y "accept-stream": [] es una lista vacía escrita por la misma regla. Los corchetes vacíos no dicen ni que el ajuste esté definido ni que se haya omitido: atienda al significado de la clave concreta.

Estructura del documento

El documento es un único objeto JSON. Sus miembros de primer nivel son las secciones de ajustes:

Sección	Tipo	Qué describe
server	objeto	El nombre y el rol del nodo, el registro, el mantenimiento.
cluster	objeto	Meshwork: las direcciones, los nombres y los secretos de los nodos vecinos.
user-default	objeto	Reservada, todavía no contiene claves.
user	matriz	Las cuentas de los receptores de flujos y de los socios.
web-server	objeto	La interfaz web y sus cuentas.
http-server	objeto	La difusión de los flujos por HTTP.
epg-server	objeto	La difusión de la guía de programas.
cs	objeto	Servidores externos de gestión de abonados.
mosaic	objeto	Activación del mosaico.
epg	objeto	La recopilación de la guía de programas y sus fuentes.
alerter	objeto	Los umbrales de las alertas y las direcciones de entrega.
acme	objeto	La obtención automática de certificados.
dvb-adapter	matriz	Tarjetas de recepción DVB.
dvr-storage-list	objeto	Almacenes del archivo DVR.
stream	matriz	Flujos.
stream-adaptive	matriz	Grupos de tasa de bits adaptativa.

Las matrices de primer nivel siempre contienen objetos. Dentro de las secciones y de las entradas también aparecen listas simples de valores —números y cadenas—; sobre ellas véase Las matrices emparejadas se corresponden por posición. Los objetos de las matrices contienen a su vez matrices anidadas de objetos, por lo que la profundidad máxima del documento es de tres niveles:

stream[]  ->  input[]   ->  las claves de una entrada
          ->  output[]  ->  las claves de una salida

Las claves de las secciones simples son opcionales sin excepción, y la ausencia de una sección entera no es un error.

Las entradas de matriz son la excepción. Además de id, cada entrada debe llevar sus claves de anclaje: un flujo, stream-name; una entrada y una salida, type y la dirección o la ruta del transporte elegido; una tarjeta de recepción, name; un almacén, name y dir-path; una cuenta de la interfaz web y de la guía de programas, login y password; una fuente de la guía, name y source. Omitir cualquiera de ellas descarta el archivo entero. El esquema comprueba estas claves, así que una comprobación antes del arranque atrapará una entrada así.

La referencia de cada clave —su tipo, su rango y su valor por defecto— está en el documento de referencia de la API HTTP (Documentos de referencia). Aquí no se repite a propósito: dos copias de una misma referencia divergen en una sola entrega.

Qué hace el servicio al leer el archivo

La lectura es deliberadamente desigual: en unos casos el servicio perdona el error, en otros rechaza el archivo entero; su primera tarea es levantar el nodo. Ahí está exactamente la diferencia entre una errata que verá y una errata que no verá.

Se acepta, pero no como pretendía quien editó

Qué hay en el archivo	Qué hace el servicio
Clave desconocida	Se ignora. En el registro se escribe una advertencia con el nombre de la clave y de la sección a la que va dirigida (para una entrada de matriz se nombra la matriz, no la entrada). El ajuste que quería cambiar sencillamente no cambia, y una errata en el nombre de una clave no se ve hasta que se lee el registro. La clave desaparece del archivo en el siguiente guardado de la configuración, pero por sí sola no provoca un guardado y puede quedarse mucho tiempo en el archivo.
Falta una clave	Rige el valor por defecto. No es un error.
Falta una sección	Todas sus claves toman sus valores por defecto. No es un error.
La misma clave dos veces en una sección	Gana en silencio la última. Ni error ni advertencia.
Un número, o true y false, entre comillas	Se acepta: el valor se lee como texto y se analiza. El esquema, en cambio, rechazará ese valor, por lo que los números y los indicadores se escriben sin comillas.
Un número fuera de rango	Se lleva al límite más cercano, con una advertencia en el registro que indica la clave, el valor leído y el límite aplicado. Tras la carga, el servicio vuelve a guardar el archivo con el valor corregido, por lo que en el siguiente arranque la advertencia no se repite. El mismo valor enviado por la API HTTP no se corrige, sino que se rechaza con un error.
Una matriz donde se espera un valor único	Se ignora por completo, sin una sola línea en el registro. El ajuste se queda en su valor por defecto y no aparece diagnóstico alguno.

Los errores de forma en torno a las listas y una clave repetida son los casos que pasan en completo silencio: el registro no dirá nada de ellos. Son el principal argumento a favor de comprobar el archivo con el esquema antes del arranque.

Nota

También resulta desconocida una clave que esta compilación no admite. En un nodo cuya compilación no sabe recibir DVB, la sección dvb-adapter de un archivo trasladado pasa a ser desconocida por entero: una advertencia en el registro y, en el siguiente guardado, desaparece del archivo.

Se rechaza junto con todo el archivo

Cada uno de estos casos interrumpe la carga. El archivo se traslada al directorio bad/ y el servicio pasa al siguiente archivo por orden (Comportamiento en el arranque y ante errores de configuración).

Qué hay en el archivo	Explicación
Un error de sintaxis JSON	Cualquiera.
Un valor null	En cualquier sitio y para cualquier clave. null no se acepta nunca: para devolver un ajuste a su valor por defecto, se elimina la clave.
Una forma de valor incorrecta	Un objeto donde se espera un valor único; un valor único donde se espera un objeto o una lista de objetos.
Un número u otra palabra en lugar de un indicador	Las claves lógicas solo admiten true y false, entre comillas o sin ellas. No se admiten ni 1 y 0, ni "yes" y "no".
Una cadena más larga de lo permitido	Los límites de longitud, a diferencia de los rangos numéricos, nunca se truncan.
Un número fraccionario donde hace falta un entero	El valor no se analiza como entero y la carga se interrumpe. Lo mismo para una cadena que no se lee como número.
Una entrada de matriz sin clave de anclaje	Además de id, una entrada debe llevar sus propias claves obligatorias (Estructura del documento).
Una entrada de matriz sin id	El identificador es obligatorio. La excepción es la matriz stream: allí un id ausente se lee como 0, y ese es un valor admisible, por lo que solo se rechazará la segunda entrada sin identificador, como repetición.
Un id repetido	Dos entradas de una misma matriz con el mismo identificador.
La repetición de un valor declarado único	Varias matrices exigen que una clave sea única entre sus entradas: nombres de cuentas, nombres y rutas de los almacenes, nombres de flujos, direcciones de las fuentes y otras.
Un valor vacío donde hace falta texto	Dentro de las entradas de matriz esta exigencia es estricta; en las secciones simples no se observa en todas partes, y no conviene fiarse de esa indulgencia.
Un valor que no ha pasado la comprobación de la sección	Algunas secciones comprueban sus valores en conjunto, y esa comprobación también interrumpe la carga: caracteres no admitidos o exceso de longitud en el nombre del nodo y en el nombre del dominio, un nivel de registro desconocido, un dominio adicional mal escrito, un número discordante de entradas en las matrices emparejadas de Meshwork, una longitud discordante de las listas de nombres y de valores de las variables de entorno.

El registro es parte del procedimiento

Los errores de la primera tabla no impiden el arranque; los de la segunda lo interrumpen. El único lugar donde se ven los primeros es el registro tras el primer arranque. Cualquier línea sobre una clave ignorada o un valor llevado al límite significa que el archivo dice algo distinto de lo que usted escribió en él.

Reglas que no se ven en el archivo

Son propiedades de la lectura, no de la sintaxis. El archivo puede ser JSON impecable, pasar todas las comprobaciones de la sección anterior y aun así significar algo distinto de lo que aparenta.

El orden de las claves dentro de un objeto importa

Las claves se aplican en el orden en que están escritas. En varios sitios una clave determina qué claves existen siquiera más abajo en la misma entrada, y por eso debe ir antes que ellas. Una clave escrita por encima de su clave determinante todavía no está reconocida en el momento de la lectura y se descarta como desconocida: con una advertencia en el registro y sin error de carga.

Así funcionan:

• type en una entrada de entrada o de salida: elige el transporte y todo lo que le corresponde;

• mpts y stream-name en una entrada de flujo. mpts elige el tipo de flujo y debe preceder, entre otras cosas, a las matrices input y output, mientras que stream-name abre los parámetros de OTT, del archivo y del multiplex si la clave mpts no está en la entrada. El valor por defecto de la clave enable-mosaic, tomado de mpts, queda fijado en el momento en que se lee mpts (y, en su ausencia, stream-name): un enable-mosaic definido explícitamente por encima de ese punto se sobrescribe con ese valor, por debajo se conserva;

• type y mode en una entrada de tarjeta DVB: juntos determinan el conjunto de parámetros de configuración, y ambos deben ir antes de la clave name.

Una excepción a la regla general: si las matrices input y output están por encima de mpts, las entradas y las salidas se construyen como para un flujo de un solo programa, y un tipo admisible solo para un flujo de varios programas provoca el rechazo de todo el archivo y no una advertencia.

Un archivo escrito por el propio servicio siempre satisface estas reglas: el servicio emite las claves en un orden fijo y seguro. Solo es vulnerable un archivo cuyo orden se ha cambiado a mano. JSON Schema no tiene noción de orden, así que el esquema no lo comprueba. La regla práctica es sencilla: no mueva nada; conserve el orden en el que el servicio escribió el archivo.

Los identificadores se ponen a mano

Cada entrada de cada matriz tiene una clave id. Los identificadores se asignan automáticamente solo al crear una entrada a través de la API HTTP; al leer el archivo no los asigna nadie.

Por eso una entrada añadida a mano debe llevar un id explícito:

• es obligatorio en cualquier matriz: sin él se rechaza todo el archivo;

• debe ser único dentro de su matriz;

• el menor valor admisible es 1 en todas partes, salvo en la matriz stream, donde también se admite 0.

Para la matriz stream de ahí se deriva una trampa: un id ausente se lee allí como 0, es decir, como un identificador de verdad. La primera entrada sin id pasará; la segunda chocará con ella y descartará todo el archivo. Por la misma razón, un flujo con id 0 se escribe en el archivo sin línea id alguna: no es un error de escritura, sino consecuencia de que aquí el cero es precisamente el valor por defecto.

La unicidad de los identificadores no es expresable con JSON Schema, así que esta es una de las pocas reglas que el esquema no comprobará por usted. Hay un comando listo para buscar repeticiones en Las comprobaciones que el esquema no hace.

El orden de las entradas en una matriz no se conserva

El servicio ordena las listas grandes en cada lectura, cada una por su propia clave: los flujos por el nombre mostrado, las entradas y salidas de un flujo por la clave de orden, las cuentas por el usuario, los almacenes y las tarjetas de recepción por el nombre. En el orden en que escriba tales entradas, el archivo guardado será distinto. No atribuya significado a su orden: allí donde la secuencia importa hay una clave propia para ella.

La regla no es universal, y conviene fijarse en dos excepciones:

• algunas listas conservan el orden del archivo, en particular los grupos de tasa de bits adaptativa y los servidores de gestión de abonados;

• las listas simples de valores no se reordenan nunca. Es esencial: precisamente en su orden se sostienen las matrices emparejadas (Las matrices emparejadas se corresponden por posición).

Las matrices emparejadas se corresponden por posición

Varios ajustes se expresan mediante matrices paralelas que se corresponden por número: la entrada N de una matriz se refiere a la entrada N de las demás. Así funcionan las direcciones, los nombres y los secretos de los nodos Meshwork vecinos, los nombres y valores de las variables de entorno, y las listas «antes — después» al reasignar identificadores. Eliminar una entrada de una matriz sin eliminar la correspondiente de las demás desplaza todo lo que sigue.

El esquema comprobará que cada matriz contiene elementos del tipo correcto, pero no que las longitudes de las matrices coincidan. Eso lo comprueba el propio servicio y descarta todo el archivo cuando las longitudes difieren en los pares Meshwork, en las variables de entorno, en las listas «antes — después» de la reasignación de PID (mpegts-pid-old y mpegts-pid-new), en las listas de cambio de idioma (mpegts-lang-set-pid y mpegts-lang-set) y en las claves de desencriptado (biss-pnr y biss-key). En el cuarteto de direcciones RIST (rist-addr-*) una diferencia de longitud no interrumpe la carga, pero la entrada no se abre y el motivo se escribe en el registro. Hay un comando de cotejo listo en La igualdad de longitud de las matrices emparejadas.

Los comentarios se leen pero no se conservan

La lectura admite comentarios de bloque de la forma /* ... */: resultan cómodos mientras se trabaja en el archivo. Solo esa forma: el comentario de línea // no se admite y hace que el archivo sea sintácticamente incorrecto, es decir, lo descarta entero. Por la misma razón, no escriba la secuencia /* dentro de un valor de texto: se tomará por el inicio de un comentario.

Los comentarios no sobreviven a un guardado: el servicio construye el documento de nuevo cada vez a partir de lo que mantiene en memoria, así que el primer guardado los borra todos. Considérelos anotaciones mientras dura la edición, y escriba lo que deba conservarse en la clave note, que tienen la mayoría de las secciones y entradas.

Las herramientas JSON estrictas —incluido el validador de Editar, comprobar y trasladar los ajustes— no analizarán un archivo con comentarios. Antes de la comprobación se eliminan los comentarios.

Conjuntos condicionales de claves

Dos claves actúan como conmutadores que determinan qué claves son admisibles junto a ellas:

• En las entradas de entrada y de salida type elige el transporte. Cada transporte tiene su propio conjunto de claves; una clave de otro transporte no se reconoce.

• En las entradas de tarjeta DVB type elige el sistema de radiodifusión y mode, el modo de trabajo. Juntos determinan el conjunto de claves de configuración, hasta el punto de si existen siquiera claves del conversor.

El esquema reproduce estas condiciones y rechazará una clave que no pertenezca a la variante elegida. El único caso que no puede expresar es una clave cuya forma depende de un conmutador del objeto que la engloba: en un flujo de varios programas la clave de desencriptado (biss-key) se escribe como lista, y en un flujo de un solo programa, como valor único. El esquema acepta ambas formas dondequiera que aparezca esa clave; la correcta la elige solo el servicio.

Valores que no se deben enviar

El archivo guarda las contraseñas y las claves en claro. Antes de entregar la configuración a nadie —a un colega, a una solicitud de soporte, a un sistema de tickets, a un repositorio público— sustituya los valores de:

• las contraseñas de las cuentas en las secciones de la interfaz web, de la guía de programas y de los receptores de flujos, la contraseña del servidor de gestión de abonados, y el usuario y la contraseña de la fuente de la guía;

• el secreto propio del nodo y los secretos de los nodos Meshwork vecinos;

• las frases de contraseña de los transportes y las contraseñas de cliente de las entradas PS1 y SRT, la contraseña de la entrada RTSP, el usuario y la contraseña de la entrada HLS/HTTP;

• las claves y los identificadores de clave de la protección de contenidos y los secretos compartidos;

• las claves de desencriptado;

• el token del bot del servicio de mensajería y la contraseña de la cuenta de correo;

• la clave de vinculación de la autoridad de certificación.

Dos claves no llevan nombre de secreto pero los contienen con regularidad: la dirección de publicación de una salida hacia una plataforma externa y la dirección de origen de una entrada, si las credenciales están escritas directamente en el enlace.

La lista crece con cada nuevo transporte, así que no la dé por exhaustiva: antes de enviar el archivo, busque en él password, secret, key, token y passphrase, y revise cada enlace.

El archivo no es la única vía hacia esos valores: a través de la API HTTP son legibles para cualquier cuenta del nodo, incluido un rol de solo lectura (Acceso).

Advertencia

Sustituir un secreto por una cadena vacía no siempre es seguro: parte de estas claves no admiten un valor vacío y el archivo se rechazará entero. Ponga una sustitución evidente de longitud verosímil.

Comprobación con el JSON Schema

Junto con la documentación se publica una descripción legible por máquina del archivo de configuración en formato JSON Schema. Atrapa toda una clase de errores que el propio servicio se traga en silencio: ante todo una errata en el nombre de una clave y una matriz escrita en lugar de un valor único.

Dos archivos de esquema

Archivo	Función
pss.schema.json	Estricto. Cada clave debe estar entre las declaradas por el producto. Se usa para un archivo destinado a la versión indicada en la cabecera del esquema.
pss.compat.schema.json	Permisivo. Los tipos, los rangos, las enumeraciones y las claves obligatorias se siguen comprobando, pero las claves que el producto no conoce se omiten. Es la primera pasada al trasladar ajustes desde otra versión, donde las claves desconocidas son esperables y no sospechosas.

Ambos esquemas llevan la versión del producto para la que se han generado. Una configuración solo se comprueba con sentido con el esquema de la versión que la va a leer. Comprobar con el esquema de otra entrega da una respuesta segura y equivocada.

Advertencia

El esquema permisivo omite algo más que las claves desconocidas. La pertenencia de una clave a la variante elegida (Conjuntos condicionales de claves) se apoya en el esquema en el mismo mecanismo, así que en una comprobación permisiva también pasa una clave auténtica escrita en el tipo de entrada equivocado, en el modo de tarjeta equivocado o en el tipo de flujo equivocado; y con ella tampoco se comprueba su propio rango. El esquema permisivo es solo la primera pasada; la última palabra siempre la tiene el estricto.

Nota

Los esquemas forman parte del conjunto de documentación, no del producto: en el directorio de ajustes de un nodo en funcionamiento no hay copia alguna, ni hace falta. Se publican en el sitio de la documentación: https://doc2.pstreamer.tv/schema/, un directorio por versión. Tome el esquema de su versión y guárdelo en la máquina donde edita el archivo.

La dirección escrita dentro del propio esquema, en la clave $id, es su identificador y no una indicación de descargar nada: la comprobación de un archivo funciona también sin acceso a la red.

Qué comprueba el esquema

• los nombres de las claves: una errata pasa a ser un error en lugar de una omisión silenciosa;

• los tipos de los valores, incluida una matriz escrita en lugar de un valor único;

• los rangos numéricos y los límites de longitud del texto;

• los conjuntos cerrados de valores admisibles;

• la presencia de las claves obligatorias, ante todo id y type;

• la pertenencia a una variante: se señalará una clave de otro transporte o de otro sistema de radiodifusión.

Qué no comprueba el esquema

• el orden de las claves dentro de un objeto (El orden de las claves dentro de un objeto importa);

• la unicidad de los identificadores y de las claves declaradas únicas (Los identificadores se ponen a mano);

• la igualdad de longitud de las matrices paralelas (Las matrices emparejadas se corresponden por posición);

• la forma de una clave que depende de un conmutador del objeto que la engloba (Conjuntos condicionales de claves);

• las referencias entre secciones: si existe realmente el almacén, la fuente o la tarjeta a los que se remite por número;

• todo lo que depende de la máquina: si la ruta admite escritura, si el puerto está libre.

Todo lo enumerado lo comprueba el propio servicio al leer el archivo, y la mayor parte interrumpe la carga. El esquema reduce la brecha, pero no la cierra: una comprobación superada significa que el archivo es correcto y verosímil, no que el servicio lo vaya a aceptar.

Nota

La API HTTP contiene una familia de peticiones /schema que devuelven listas de valores admisibles y del equipamiento detectado: los tipos de entrada y de salida que admite esta compilación, los idiomas, las tarjetas encontradas, los dispositivos de transcodificación. No tienen relación con el archivo pss.schema.json, y lo uno no sustituye a lo otro. La coincidencia en los nombres es solo una coincidencia.

Compatibilidad entre versiones

Advertencia

No se garantiza la compatibilidad hacia atrás. Con una actualización pueden cambiar por igual el archivo de configuración, el esquema y la API HTTP: la composición y los nombres de las claves, los rangos de valores, la forma de las peticiones y las respuestas. Una actualización no traslada los ajustes ni avisa de las divergencias. Vuelva a comprobar el archivo después de cada actualización, y los scripts que trabajan con la API HTTP, también después de cada actualización.

Entre entregas se añaden, se renombran y se eliminan claves sueltas, y los rangos admisibles se estrechan. Una clave eliminada pasa a ser desconocida y se ignora, de modo que el ajuste sencillamente deja de actuar; una clave nueva actúa por defecto mientras no se escriba; un valor que ha quedado fuera de un rango estrechado se lleva al límite. El servicio no informa de ninguno de los tres.

En el archivo no hay marca de versión. Nada en su interior indica la entrega que lo escribió, y el servicio no realiza conversión alguna al leer un archivo de una compilación más antigua o más nueva. Junto con la escasez del archivo, eso significa que un archivo trasladado se aplica tal cual.

El esquema es, por tanto, la única vía práctica para saber qué claves de un archivo existente ya no entiende esta entrega. Vuelva a comprobar el archivo después de cada actualización; el procedimiento es Trasladar los ajustes a otra versión.