@netin-ds/netin-ds-drv-mqtt

Variables de entorno

Configuración general del DriverAPI

• CONFIG_DRIVER_ARTIFACT_ID default(netin-ds-drv-mqtt): nombre del driver desde el punto de vista de NetinDS.

  No se recomienda su modificación si no se sabe lo que se esta haciendo.

• CONFIG_DRIVER_UPDATE_INTERVAL default(60000): intervalo de comprobación de cambios en la configuración de origines (addresses de NetinDS).

• CONFIG_DRIVER_AUTO_UPDATE default(false): permitir que DriverAPI actualice de forma automática la configuración de origines (addresses de NetinDS) cuando son detectados cambios.

  No se recomienda su modificación si no se sabe lo que se esta haciendo.

• CONFIG_DRIVER_LAZY_START default(false): indicar al driver que realice un proceso de enroll sobre el sistema al arrancar.

  No se recomienda su modificación si no se sabe lo que se esta haciendo.

• CONFIG_DRIVER_HEALTH_PORT default(3000): puerto sobre el que se ofrece el REST API de observability de NetinDS. Dicha REST API se ofrecerá en los endpoints:

  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/health: estado de los subcomponentes internos del driver, incluyendo el estado de las conexiones de los dispositivos MQTT.
  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/failures: listado de fallos de los subcomponentes internos del driver (Dispositivos MQTT). El tamaño de este listado puede configurarse mediante la variable de entorno: CONFIG_CONFLICT_BUFFER_LENGTH, cuyo valor por defecto es 100.

    No se recomienda modificación de la variable CONFIG_CONFLICT_BUFFER_LENGTH si no se sabe lo que se esta haciendo.

  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/registers: registro de los últimos trabajos de publicación hacia NetinDS que acabarón con algún tipo de error. El tamaño de este listado puede configurarse mediante la variable de entorno: CONFIG_CONFLICT_BUFFER_LENGTH, cuyo valor por defecto es 100.

    No se recomienda modificación de la variable CONFIG_CONFLICT_BUFFER_LENGTH si no se sabe lo que se esta haciendo.

  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/quarantine: registro de los datapointSet o datapoints en estado de cuarentena, es decir, datapoints cuya configuración es incorrecta.
  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/metrics: métricas del driver en formato prometheus⁠.
  • http://127.0.0.1:{CONFIG_DRIVER_HEALTH_PORT}/v1/alarms: registro de las alarmas emitidas desde este driver a NetinDS y su estado.

• CONFIG_DRIVER_AGENT_HOST_ADDRESS default(localhost): dirección IP del sistema donde se encuentra el NetinDS Agent Engine.

Configuración del registro de eventos (logger) @netin-js\logger⁠

Registro por consola

• CONFIG_LOGGER_CONSOLE_ENABLE default(false): habilitación del logger de consola.
• CONFIG_LOGGER_CONSOLE_LEVEL default('info'): nivel de registro.

Registro por fichero

• CONFIG_LOGGER_FILE_ENABLE default(true): habilitación del logger de fichero.
• CONFIG_LOGGER_FILE_LEVEL default('info'): nivel de registro.
• CONFIG_LOGGER_FILE_FILE_NAME default('logs/netin-ds-drv-mqtt.log'): nombre del fichero de registro.
• CONFIG_LOGGER_FILE_MAX_FILES default(10): cantidad maxima de ficheros (rotacional).
• CONFIG_LOGGER_FILE_MAX_SIZE default(10 * 1000000): tamaño máximo en bytes del archivo.
• CONFIG_LOGGER_FILE_ZIPPED default(true): indica que todos los ficheros logs se comprimen, excepto el que se está escribiendo actualmente
• CONFIG_LOGGER_FILE_JSON default(false): indica si el formato es json o string, por defecto es string.

Registro mediante el fluentd

• CONFIG_LOGGER_FLUENTD_ENABLE default(false): habilitación del logger mediante fluentd.
• CONFIG_LOGGER_FLUENTD_LEVEL default('info'): nivel de registro.
• CONFIG_LOGGER_FLUENTD_HOST default('localhost'): host donde se encuentra el servicio fluentd.
• CONFIG_LOGGER_FLUENTD_PORT default(28930): host donde se encuentra el servicio fluentd.
• CONFIG_LOGGER_FLUENTD_TIMEOUT default(5000): configura el tiempo de inactividad del socket.
• CONFIG_LOGGER_FLUENTD_ACK_RESPONSE default(true): cambia el protocolo a at-least-one. El logger esperara por el ack del servicio.
• CONFIG_LOGGER_FLUENTD_RECONNECT_INTERVAL default(5000): configura el intervalo de reconexión en milisegundos.
• CONFIG_LOGGER_FLUENTD_EVENT_MODE default('Message'): configura el modo en el que son tratados los eventos. Son soportados Message, PackedForward y CompressedPackedForward. Ver Event Modes⁠.
• CONFIG_LOGGER_FLUENTD_TLS default(false): habilita el uso de TLS en este socket.
• CONFIG_LOGGER_FLUENTD_FLUSH_INTERVAL default(2000): no tiene efecto en Message Mode. El logger almacena los eventos y los envía en cada intervalo de flush.
• CONFIG_LOGGER_FLUENTD_MESSAGE_SEND_QUEUE_SIZE default(100 * 1024 * 1024): no tiene efecto en Message Mode. Tamaño de la cola de mensajes en bytes.

Niveles de registro

Los niveles de registro, al ser niveles apilados, cada nivel complementa al nivel anterior mostrando mayor detalle del mismo evento o flujo. Usar el nivel adecuado para cada tipo de registro es de gran importancia, especialmente en sistemas en producción donde un alto nivel de registros pueden reducir en gran medida el rendimiento de los sistemas:

• error: Cualquier error que es fatal para la operación, aunque no tiene porque serlo para el servicio o la aplicación. Este tipo de errores requieren de la intervención de los administradores del sistema ó usuarios para corregir el problema.
• warn: Eventos que pueden provocar comportamientos no deseados en el sistema, el sistema trata de recuperarse por si mismo del evento, pero se podrían producir comportamiento extraños en la aplicación.
• info: Información util para los usuarios administradores del sistema (inicio/parada de servicio, version de la aplicación, conexiones con recursos externos ...)
• verbose: Información util para conocer todos los pasos realizados por una aplicación, orientada a usuarios administradores que tratan de conocer la toma de decisiones el fundamento de la toma de decisiones o la razón base de los eventos de una aplicación o sistema.
• debug: - Información que es util para el diagnostico de los sistemas ó servicios, no solo para desarrolladores (configuraciones, modos de funcionamiento ...).
• silly: - Información especifica de utilizada para trazar el comportamiento del código en una funcionalidad especifica.

Configuración del Broker MQTT

Configuración del servicio

• CONFIG_BROKER_HOST default(0.0.0.0): dirección IP sobre la que se enlaza el broker MQTT.
• CONFIG_BROKER_PORT default(1883): puerto sobre el que se ofrece el servicio.
• CONFIG_BROKER_MODE default(tcp): modo de funcionamiento del broker MQTT. Las opciones validas son tcp o tls, esta ultima obliga a la configuración de certificados para el broker MQTT.
• CONFIG_BROKER_FILE_CERT_PATH default(certs/cert-broker.pem): ruta al fichero de certificado para el servidor. Solo se usa en modo tls.
• CONFIG_BROKER_FILE_KEY_PATH default(certs/key-broker.pem): ruta al fichero de clave privada. Solo se usa en modo tls.
• CONFIG_BROKER_FILE_CA_PATH default(certs/ca-broker.pem): ruta al fichero de certificado de CA. Solo se usa en modo tls.

Configuración de rendimiento y limites

• CONFIG_BROKER_CONCURRENCY default(100): número de mensajes concurrentes gestionados por el broker. Este valor es independiente del tamaño del buffer de para la publicación de datapoints sobre NetinDS, es decir, es un buffer previo al del propio DriverAPI de NetinDS.
• CONFIG_BROKER_QUEUE_LIMIT default(42): número máximo de mensajes en cola antes de que el dispositivo MQTT establezca la sesión.

  Esta opción se establece para futuros usos del broker MQTT, en su versión 1.X.X el sistema es de un solo sentido, es decir, no debería de haber subscriptores conectados al broker, solo productores. Aunque es del todo posible la configuración del sistema para permitir suscripciones.

• CONFIG_BROKER_MAX_CLIENTS_LENGTH default(23): tamaño máximo de clientId de los clientes MQTT.
• CONFIG_BROKER_HEARTBEAT_INTERVAL default(60000): duración del intervalo de publicación de la señal de heartbeat sobre el canal $SYS/${CONFIG_BROKER_ID}/heartbeat.
• CONFIG_BROKER_ID default(netin-ds-drv-mqtt): identificador del broker MQTT, utilizado en los topics de diagnostico del broker.
• CONFIG_BROKER_CONNECT_TIMEOUT default(30000): tiempo máximo de espera para que el cliente MQTT mande un paquete CONNECT⁠ después de establecer la conexión TCP.
• CONFIG_BROKER_MQ_MIDDLEWARE default(default): modo de intercambio de mensajes. En el caso del uso den modo cluster del sistema esta variable debe configurarse como redis y la opciones de Redis (ver resto de variables de entorno) debe ser correctamente configurada. Las opciones validas son default ó redis.

  La opción de funcionamiento en modo cluster no ha sido declarada estable en la version 1.X.X.

• CONFIG_BROKER_PERSISTENCE_MIDDLEWARE default(default): middleware que almacena los mensajes QoS > 0, retained y LWT (Last Will Testament). Si es necesario la gestión de esos mensajes mediante un sistema de persistencia se recomienda el uso, junto con el modo cluster, de Redis, para lo cual esta variable debe configurarse como redis y la opciones de Redis (ver resto de variables de entorno) debe ser correctamente configurada.

  Esta opción se establece para futuros usos del broker MQTT, en su versión 1.X.X el sistema es de un solo sentido, es decir, no debería de haber subscriptores conectados al broker, solo productores. Aunque es del todo posible la configuración del sistema para permitir suscripciones. Sin suscriptores, la gestión de este tipo de mensajes carece de sentido

Configuración de seguridad

• CONFIG_BROKER_USERNAME default(undefined): usuario única utilizada para la validación de clientes MQTT. Opcional.
• CONFIG_BROKER_PASSWORD default(undefined): password única utilizada para la validación de clientes MQTT. Opcional.
• CONFIG_BROKER_WHITE_LISTED_ORIGINS default(true): con esta opción se indica que solo se permitirá la conexión al broker de aquellos dispositivos configurados en NetinDS.
• CONFIG_BROKER_WHITE_LISTED_PUBLICATIONS_TOPICS default(false): con esta opción de indica que solo se permitan publicar mensajes en topic que cumplan con la RegExp indicada en la variable CONFIG_BROKER_PUBLICATIONS_REGEXP.
• CONFIG_BROKER_PUBLICATIONS_REGEXP default([\\s\\S]*): RegExp utilizada para la validación de topic en procesos de publicación. Solo se utiliza si CONFIG_BROKER_WHITE_LISTED_PUBLICATIONS_TOPICS es true.
• CONFIG_BROKER_ALLOW_SUBSCRIPTIONS default(false): con esta opción se indica si es posible o no realizar suscripciones a topics de broker.
• CONFIG_BROKER_WHITE_LISTED_SUBSCRIPTIONS_TOPICS default(false): con esta opción de indica que solo se permitan publicar mensajes en topic que cumplan con la RegExp indicada en la variable CONFIG_BROKER_SUBSCRIPTIONS_REGEXP.
• CONFIG_BROKER_SUBSCRIPTIONS_REGEXP default([\\s\\S]*): RegExp utilizada para la validación de topic de procesos de suscripción. Solo se utiliza si CONFIG_BROKER_WHITE_LISTED_SUBSCRIPTIONS_TOPICS es true.

Configuración del reenvío de mensajes

• CONFIG_BROKER_PROXY_ENABLED default(false): habilita el reenvío de los mensajes publicados por los clientes mensajes a otro broker.
• CONFIG_BROKER_PROXY_URL default(''): URL para conexión con el broker MQTT, los protocolos utilizados puedes ser: mqtt, mqtts, tcp, tls, ws, wss. Para las opciones seguras recuerde configurar CONFIG_BROKER_PROXY_MODE como tls, asi como incluir los certificados correspondientes y su configuración mediante las variables de ruta CONFIG_BROKER_PROXY_***_PATH indicadas mas abajo.
• CONFIG_BROKER_PROXY_TOPIC default(''): topic donde deben reenviarse los mensajes.
• CONFIG_BROKER_PROXY_USERNAME default(undefined): usuario usada por el proxy MQTT.
• CONFIG_BROKER_PROXY_PASSWORD default(undefined): password usada por el proxy MQTT.
• CONFIG_BROKER_PROXY_CLIENT_ID default(netin-ds-drv-mqtt): clientId utilizado por el proxy MQTT.
• CONFIG_BROKER_PROXY_MODE default(tcp): modo de funcionamiento del proxy MQTT. Las opciones validas son tcp o tls, esta ultima obliga a la configuración de certificados para el proxy MQTT.
• CONFIG_BROKER_PROXY_FILE_CERT_PATH default(certs/cert-proxy-client.pem): ruta al fichero de certificado para el proxy. Solo se usa en modo tls.
• CONFIG_BROKER_PROXY_FILE_KEY_PATH default(certs/key-proxy-client.pem): ruta al fichero de clave privada. Solo se usa en modo tls.
• CONFIG_BROKER_PROXY_FILE_CA_PATH default(certs/ca-proxy-client.pem): ruta al fichero de certificado de CA. Solo se usa en modo tls.

Configuración para la resolución de problemas (troubleshooting)

• CONFIG_BROKER_DEBUG_MODE default(false): configura el broker en modo debug, permitiendo registrar todas las interacciones con los clientes MQTT conectados.

Configuración del middleware Redis para persistencia y cluster

• CONFIG_MIDDLEWARE_REDIS_ADDR default('redis://127.0.0.1:28910/1'): URL de conexión a la instancia de Redis. Puede también configurarse mediante las variables: CONFIG_MIDDLEWARE_REDIS_HOST, CONFIG_MIDDLEWARE_REDIS_PORT y CONFIG_MIDDLEWARE_REDIS_DB.
• CONFIG_MIDDLEWARE_REDIS_HOST default('127.0.0.1'): dirección IP donde se encuentra la instancia de Redis.
• CONFIG_MIDDLEWARE_REDIS_PORT default(28910): puerto donde se encuentra la instancia de Redis.
• CONFIG_MIDDLEWARE_REDIS_DB default(1): número de DB a utilizar.
• CONFIG_MIDDLEWARE_REDIS_USERNAME: default(undefined): usuario de Redis.
• CONFIG_MIDDLEWARE_REDIS_PASSWORD: default(undefined): password de Redis.
• CONFIG_MIDDLEWARE_REDIS_RETRY_DELAY_FACTOR default(2000): factor de reintento de conexión en milisegundos, es decir, cadencia añadida a cada reintento.
• CONFIG_MIDDLEWARE_REDIS_RETRY_DELAY_MAX default(60000): máximo tiempo entre reintento de conexiones.
• CONFIG_MIDDLEWARE_REDIS_KEEPALIVE default(10000): keep alive de la conexión con Redis.
• CONFIG_MIDDLEWARE_REDIS_CONNECTION_TIMEOUT default(10000): timeout para el establecimiento de la conexión con la instancia de Redis.
• CONFIG_MIDDLEWARE_REDIS_LAZY_START default(true): Iniciar la comunicación en el arranque.

  No se recomienda modificación de la variable si no se sabe lo que se esta haciendo.

Licencia

Copyright 2021 Network Intelligence S.L. All rights reserved.

Note: All information contained herein is, and remains the property of Network Intelligence S.L. and its suppliers, if any. The intellectual and technical concepts contained herein are property of Network Intelligence S.L. and its suppliers and may be covered by European and Foreign patents, patents in process, and are protected by trade secret or copyright. Dissemination of this information or the reproduction of this material is strictly forbidden unless prior written permission is obtained from Network Intelligence