chore: bump to NethSecurity 8.8

administrative_users.rst

@@ -0,0 +1,189 @@
+.. _administrative_users-section:
+
+====================
+Administrative users
+====================
+
+NethSecurity allows local users to be granted administrative access to the web interface. Administrative users should be personal accounts assigned to individual operators, so that actions can be attributed to a specific user in the logs.
+
+This page explains how administrative users work, how MFA applies to administrators, how administrative actions are logged, and how to reconstruct administrator activity for troubleshooting and audit purposes.
+
+Administrative account types
+============================
+
+NethSecurity uses the following administrative account types:
+
+* ``root``: local system account. It should be reserved for emergency or recovery operations whenever possible.
+* Administrative users: local users with the **Administrator user** option enabled. They can access the NethSecurity UI and perform administrative operations.
+* Non-administrative users: local or remote users used for services such as VPN or authentication, without access to the NethSecurity UI.
+
+.. note::
+
+   Administrative access should be granted only to trusted operators.
+
+Creating administrative users
+-----------------------------
+
+Administrative users are created from the local users database.
+
+To create an administrative user:
+
+1. Create a local user.
+2. Set a password for the user.
+3. Enable the **Administrator user** option.
+4. Save the configuration.
+
+For general information about local and remote user databases, see :ref:`users_databases-section`.
+
+.. _2fa-section:
+
+NethSecurity UI 2FA
+===================
+
+Protecting your NethSecurity administrator account is crucial, and Two-Factor Authentication (2FA) adds an extra layer of security beyond just a password.
+2FA requires two verification steps when logging in. Instead of just a password, you'll also need a temporary code generated by a separate app on
+your smartphone or tablet. This significantly reduces the risk of unauthorized access even if your password is compromised.
+
+Enabling 2FA on NethSecurity UI:
+
+- Log in to your NethSecurity web interface
+- Click on the user icon in the top right corner and select ``Account settings``
+- Find the Two-factor authentication option and click :guilabel:`Configure 2FA`
+
+Setting up your authenticator app:
+
+- Download an authenticator app on your smartphone or tablet. Popular options include FreeOTP, Google Authenticator, and Microsoft Authenticator.
+- Open the app and scan the QR code displayed on the NethSecurity web interface. This will add your NethSecurity account to the authenticator app.
+- Enter the 6-digit code displayed by your authenticator app in the One-Time Password (OTP) field on the NethSecurity web interface.
+
+The system will also provide you with a set of backup codes. These codes can be used to log in if you lose your smartphone or authenticator app.
+Store these codes securely, preferably offline.
+
+Disable 2FA via the web interface
+---------------------------------
+
+If the administrator can still log in to the web interface:
+
+1. Click the user icon in the top-right corner and select ``Account settings``.
+2. Scroll to the ``Two-factor authentication`` section.
+3. Click ``Revoke 2FA``.
+4. A confirmation dialog appears warning that the security level will be reduced.
+   Click ``Revoke 2FA`` to confirm.
+5. If prompted, enter your current password to authorize the change.
+
+After the confirmation the status badge changes to disabled and the next login will no
+longer require an OTP.
+
+Disable 2FA from the command line (emergency recovery)
+-------------------------------------------------------
+
+If an administrator has lost both the OTP device and the recovery codes and can no
+longer log in to the web interface, 2FA can be reset directly from the shell as ``root``
+over SSH.
+
+Run the following commands, replacing `<username>` with the administrator account name
+(use ``root`` for the default administrator): ::
+
+  SECRETS_DIR=/etc/ns-api-server
+  USERNAME=root   # change to the affected username
+
+  rm -f  "${SECRETS_DIR}/${USERNAME}/secret"
+  rm -f  "${SECRETS_DIR}/${USERNAME}/codes"
+  printf '0' > "${SECRETS_DIR}/${USERNAME}/status"
+
+After these commands the user can log in with just their password.  2FA can be
+re-enabled at any time from the web interface.
+
+.. note::
+
+  Only the ``root`` account has SSH access by default.  Non-root administrators
+  cannot be recovered from SSH by the affected user themselves; an existing ``root``
+  session is required to run the commands above on their behalf.
+
+
+Root and emergency access
+=========================
+
+The ``root`` account is the main local system account, it should be treated as an emergency or recovery account and should not be used for ordinary administrative activity when personal administrative users are available.
+Use personal administrative accounts for daily operations, so that actions can be attributed to individual users in the logs.
+
+Administrative activity logging
+===============================
+
+NethSecurity logs administrative activity performed through the web interface in ``/var/log/messages``.
+Administrative logs can support troubleshooting, incident analysis, and audit reconstruction.
+
+Where to find administrative logs
+---------------------------------
+
+Logs are written in ``/var/log/messages`` and rotated on a weekly base, they are visible from the UI in their dedicated section.
+To see administrative UI events use the filter ``nethsecurity-api``.
+
+For long-term retention and centralized audit, configure persistent log storage, remote syslog forwarding, Controller log forwarding, or Cloud Log Manager. For details, see :ref:`logs-section`.
+
+Reconstructing administrator actions
+------------------------------------
+
+To reconstruct administrator activity, start from the login event and then review the following UI/API authorization and commit events for the same user, the logs allow to answer questions such as:
+
+* who logged in;
+* when the administrator accessed the firewall;
+* which UI pages or API functions were used;
+* which configuration areas were changed;
+* which values were submitted;
+* whether a change was committed;
+* whether the action was followed by service errors or security events.
+
+Every time an administrator logs in to the NethSecurity UI, the system logs the event, inside the `/var/log/messages` file.
+Example of login event for user `goofy`: ::
+
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:78: [INFO][AUTH] authentication success for user goofy
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:186: [INFO][AUTH] login response success for user o
+
+Example of logout event for user `goofy`: ::
+
+  Jun 21 09:46:13 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:46:13 middleware.go:214: [INFO][AUTH] logout response success for user goofy
+
+
+Also every action performed by an administrator inside the NethSecurity UI is logged inside the `/var/log/messages` file.
+Example of action performed by user `goofy`: ::
+
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:170: [INFO][AUTH] authorization success for user goofy. POST /api/ubus/call {"path":"ns.dashboard","method":"service-status","payload":{"service":"internet"}}
+
+Audit and compliance recommendations
+------------------------------------
+
+For audit-oriented deployments:
+
+* create a personal administrative account for each operator;
+* avoid shared administrative accounts;
+* enable MFA for all administrative users;
+* reserve ``root`` for emergency or recovery operations whenever possible;
+* use strong passwords and protect recovery codes;
+* configure persistent log storage or remote log forwarding;
+* forward logs to a remote syslog server, SIEM, Controller, or Cloud Log Manager;
+* verify that log forwarding is working correctly;
+* ensure that date, time, and timezone are correct, preferably using NTP;
+* define log retention according to the organization security policy;
+* protect remote logs from unauthorized access or deletion;
+* periodically review administrative access and configuration change logs.
+
+NethSecurity logs can support audit reconstruction and incident analysis. 
+Organizational processes such as change approval, periodic review, incident classification, and evidence preservation remain the responsibility of the organization operating the firewall.
+
+Current limitations
+-------------------
+
+Administrative activity logs are technical logs intended to support troubleshooting and audit reconstruction.
+
+Administrators should be aware of the following limitations:
+
+* NethSecurity does not currently provide a full local RBAC model for web administrators;
+* a dedicated local read-only administrator role is not currently available;
+* administrative users should therefore be assigned only to trusted operators;
+* some log entries may require correlation with configuration commit logs or related service logs;
+* an authorization event means that the API request was allowed, but related logs should be checked to confirm the final effect of the operation;
+* not every log entry necessarily contains the same fields;
+* local in-memory logs may be lost after reboot or rotation unless persistent storage or remote forwarding is configured.
+
+For long-term audit requirements, use remote log forwarding or Cloud Log Manager in addition to local logs.

avahi.rst

@@ -0,0 +1,38 @@
+.. _avahi-section:
+
+=======================
+Avahi (mDNS reflector)
+=======================
+
+Multicast DNS (mDNS) allows devices to discover services on a local network without a centralized DNS server, using multicast traffic within the ``.local`` domain.
+A typical use case is IoT network segmentation: when IoT devices live in a dedicated network, control devices like smartphones and PCs rely on mDNS for discovery.
+However, mDNS traffic does not cross network boundaries, so an mDNS reflector such as Avahi is required to bridge the gap and allow service discovery across network segments.
+
+On NethSecurity, the ``avahi-nodbus-daemon`` package is available in the official repositories but is not installed by default.
+
+.. note::
+   Starting from version 8.7.2, extra packages are automatically reinstalled after system upgrade.
+   For earlier versions and for additional information, refer to this documentation: :ref:`restore_extra_packages-section`.
+
+Installation
+============
+
+Install the package with::
+
+    apk update
+    apk add avahi-nodbus-daemon
+
+Configuration
+=============
+
+By default, the mDNS reflector functionality is disabled. To enable it:
+
+1. Edit the Avahi daemon configuration file: ::
+
+     sed -i 's/^enable\-reflector\=no$/enable\-reflector\=yes/g' /etc/avahi/avahi-daemon.conf
+
+2. Restart the Avahi daemon to apply the changes: ::
+
+     /etc/init.d/avahi-daemon restart
+
+After enabling the reflector, mDNS traffic will be reflected across network interfaces, allowing service discovery to work between different network segments.

checkmk.rst

@@ -20,7 +20,14 @@ If you only need the upstream agent, install ``checkmk-agent`` alone.
 Install the packages
 --------------------
 
-Install the agent and the optional NethSecurity checks from the command line::
+Install the agent and the optional NethSecurity checks from the command line.
+
+If you are running NethSecurity 8.8, use::
+
+    apk update
+    apk add ns-checkmk-utils
+
+If you are running NethSecurity 8.7.2 or older, use::
 
     opkg update
     opkg install ns-checkmk-utils

controller.rst

@@ -221,7 +221,7 @@ Metrics
 
 Each unit exports two types of metrics:
 
-- system operating metrics (CPU, memory, disk, network): these metrics are collected using `Netdata <https://www.netdata.cloud/>`_
+- system operating metrics (CPU, memory, disk, network): these metrics are collected using `Telegraf <https://www.influxdata.com/time-series-platform/telegraf/>`_
   and stored in `Prometheus <https://prometheus.io/>`_. As soon as a unit is connected, the controller starts scraping the metrics.
   These metrics are available to everyone regardless of the subscription status.
 - firewall metrics (traffic, security, VPN): these metrics are sent from the unit to controller at fixed intervals.
@@ -241,6 +241,13 @@ Users can access the dashboard by clicking on the :guilabel:`Open metrics` link
 By default, only the admin user can access the metrics dashboard. If you want to allow other users to access the metrics dashboard,
 you can create a new role and assign it to the user directly from the Grafana web interface.
 
+.. note::
+
+   Starting from NethSecurity 8.8, Netdata is not installed by default on units.
+   If you have configured custom dashboards that rely on Netdata metrics, you can reinstall it manually on the unit.
+
+   See :ref:`legacy Netdata section <legacy_netdata-section>` for more information on how to resinstall it.
+
 .. _grafana-section:
 
 Grafana
@@ -263,7 +270,7 @@ See the `official documentation <https://grafana.com/docs/grafana/latest/>`_ for
 Prometheus metrics
 ^^^^^^^^^^^^^^^^^^
 
-Prometheus metrics are collected using Netdata and stored in a Prometheus database.
+Prometheus metrics are collected using Telegraf by default. When Netdata is installed manually, Prometheus also scrapes metrics from it.
 
 Metrics exported for each unit includes the following labels:
 

ddns.rst

@@ -85,6 +85,41 @@ Additional notes:
 - Consider enabling logging for the DDNS service to monitor updates and troubleshoot any issues.
 - Some providers may offer advanced features like wildcards and subdomain updates. Explore these options based on your specific needs.
 
+Example: DigitalOcean (DO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following example uses the fictional ``firewall.example.net`` setup on NethSecurity.
+The DigitalOcean API token is intentionally redacted; replace it with your own token. ::
+
+  uci set ddns.do=service
+  uci set ddns.do.service_name='digitalocean.com-v2'
+  uci set ddns.do.lookup_host='firewall.example.net'
+  uci set ddns.do.domain='example.net'
+  uci set ddns.do.username='firewall'
+  uci set ddns.do.password='REDACTED_DIGITALOCEAN_API_TOKEN'
+  uci set ddns.do.param_opt='21694203'
+  uci set ddns.do.enabled='1'
+  uci set ddns.do.interface='wan'
+  uci set ddns.do.ip_source='network'
+  uci set ddns.do.ip_network='wan'
+  uci commit ddns
+  /etc/init.d/ddns restart
+
+The relevant DigitalOcean fields are:
+
+- ``domain``: the domain managed in DigitalOcean
+- ``username``: the hostname label to update
+- ``password``: the personal access token
+- ``param_opt``: the DNS record ID for that hostname
+
+To list the records and find the ID, run::
+
+  curl -X GET -H 'Content-Type: application/json' \
+        -H "Authorization: Bearer TOKEN" \
+        "https://api.digitalocean.com/v2/domains/DOMAIN/records"
+
+Replace ``TOKEN`` and ``DOMAIN`` with your own values.
+
 Example: afraid.org (FreeDNS)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -135,6 +170,20 @@ The domain is named "nstest1.freeddns.it" and the username and password are "nst
   uci commit ddns
   /etc/init.d/ddns restart
 
+Split DNS
+---------
+
+Some deployments publish the same hostname inside the LAN and on the public internet.
+If ``lookup_host`` resolves to a private address on the firewall itself, DDNS can compare the public WAN IP against the internal answer and keep retrying even when the provider update succeeded.
+
+The recommended fix is to make DDNS query an external resolver for the lookup instead of the local split-DNS answer. For example::
+
+  uci set ddns.do.dns_server='1.1.1.1'
+  uci commit ddns
+  /etc/init.d/ddns restart
+
+This keeps split DNS for LAN clients while the DDNS client validates the public record.
+
 Using Luci
 ----------
 

dns_dhcp.rst

@@ -50,6 +50,12 @@ Available fields:
   * ``Range IP end`` : last IP address of DHCP range
   * ``Lease time`` :  lease time (default 1 hour)
 
+  Each DHCP server can serve more than one address range: under ``IP ranges`` you can specify multiple distinct IP ranges
+  for the same interface, each one defined by its own ``Range IP start`` and ``Range IP end``. Click :guilabel:`Add IP range`
+  to define an additional range, or use the trash icon next to a range to remove it. At least one range must be specified,
+  while the others are optional. Each range must belong to the interface network class, and the ``Range IP end`` must be
+  higher than the ``Range IP start``. Ranges are allowed to overlap.
+
 **DHCP Advanced settings**
 
 ``Force DHCP server start`` 
@@ -96,6 +102,11 @@ Dynamic leases
 Dynamic leases represents IP addresses that are currently in use and have been allocated to devices on the network.
 This tab shows all currently active leases.
 
+.. note::
+   When :ref:`storage-section` is configured, dnsmasq stores the lease file in
+   ``/mnt/data/dnsmasq/dhcp.leases``, so dynamic leases survive reboots.
+   Otherwise it keeps using ``/tmp/dhcp.leases``.
+
 Default Configuration
 ---------------------