feat(logs): add CLM

Author: gsanchietti

logs.rst

@@ -12,7 +12,9 @@ Logs are initially written to a temporary in-memory directory to prevent potenti
 
 3. **Custom Syslog Forwarder**: Logs can be sent to a remote syslog server.
 
-The next paragraph will explain how to configure this latter option.
+4. **Cloud Log Manager**: Logs can be forwarded to the Nethesis Cloud Log Manager (CLM) service.
+
+The next paragraphs will explain how to configure these latter options.
 
 Forwarding to a remote server
 =============================
@@ -48,6 +50,71 @@ It is possible also to configure RFC 5424 using the same syntax: ::
 
 It is possible to configure multiple forwarders by repeating the operation using a different configuration name like ``clm2``.
 
+Forwarding to Cloud Log Manager
+================================
+
+.. admonition:: Service entitlement required
+
+   You need to purchase a subscription for the CLM service from Nethesis and obtain the tenant identifier.
+   The service is currenlty reserved to Enterprise customers. For more information, please contact Nethesis sales.
+
+The ``ns-clm`` package forwards syslog messages to the Nethesis Cloud Log Manager (CLM) service.
+It provides the ``ns-clm-forwarder`` daemon, which tails ``/var/log/messages`` and tracks its read position in ``/var/run/ns-clm/last_offset``.
+New syslog lines are parsed, batched, and sent as JSON via HTTP POST to the CLM endpoint.
+The daemon polls for new lines every 10 seconds, detects log rotation automatically, and persists the offset on shutdown so it can resume after a restart.
+
+The package is not included by default on NethSecurity 8.7.2 or earlier, but it is available in the package repository and can be
+manually installed.
+Install it with: ::
+
+  opkg update
+  opkg install ns-clm
+
+The UCI configuration is stored in ``/etc/config/ns-clm``:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 50
+
+   * - Option
+     - Default
+     - Description
+   * - ``enabled``
+     - ``0``
+     - Enable (``1``) or disable (``0``) the forwarder
+   * - ``uuid``
+     - (empty)
+     - Unique identifier for the device, generated with ``uuidgen`` and prefixed with "L" to ensure it starts with a letter
+     - This is required for the CLM service to identify the source of the logs
+     - Example: ``L3d50ca11-4415-4e46-9ee9-b1da0f62c337``
+   * - ``address``
+     - ``https://nar.nethesis.it``
+     - CLM server address
+   * - ``tenant``
+     - (empty)
+     - CLM tenant identifier, available inside the CLM portal, under ``Users and Companies`` -> ``Companies``
+   * - ``debug``
+     - ``0``
+     - Enable debug output to stderr (``1``)
+
+To enable the forwarder and set the tenant identifier, run: ::
+
+ uci set ns-clm.config.uuid="L$(uuidgen)"
+ uci set ns-clm.config.enabled=1
+ uci set ns-clm.config.tenant=<tenant_id>
+ uci commit ns-clm
+ reload_config
+
+You can find the tenant identifier in the CLM portal, under ``Users and Companies`` -> ``Companies``.
+
+To also enable the service at boot: ::
+
+ /etc/init.d/ns-clm enable && /etc/init.d/ns-clm start
+
+To stop and disable the forwarder: ::
+
+ /etc/init.d/ns-clm stop && /etc/init.d/ns-clm disable
+
 Log rotation size
 =================