docs: added documentation on how to enable receiving logs from remote

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.

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
 ----------
 

dpi_filter.rst

@@ -60,35 +60,20 @@ You can include a description explaining the reason for the exclusion.
 
 Each exception can be enabled or disabled as desired.
 
-Netify interface exclusion
---------------------------
+Netify traffic bypass
+---------------------
 
-By default, Netifyd monitors all interfaces. To exclude specific interfaces, you can define an exclusion list. Below are commands to add, modify, or remove excluded interfaces.
-The exclusion list is configured using the ``ns_exclude`` option that takes a list of patterns. Each entry is a shel glob pattern.
+By default, Netifyd processes all traffic passing from, to and out of the firewall. In some cases it may be desiderable to completely ignore traffic analysis on some specific hosts or subnets. The exclusions is configured using the `bypassv4` and `bypassv6` options that take a list of IP addresses or CIDR subnets. Bypasses can have a description to explain the reason for the bypass, separated by a `|` pipe character after the IP.
 
-- Add interfaces to exclusion list. The system will exclude the `eth1` interface and all OpenVPN and WireGuard interfaces: ::
+To add a new bypass entry, use the following command: ::
 
-      uci add_list netifyd.@netifyd[0].ns_exclude='eth1'
-      uci add_list netifyd.@netifyd[0].ns_exclude='tun*'
-      uci add_list netifyd.@netifyd[0].ns_exclude='wg*'
+      uci add_list netifyd.config.bypassv4='10.45.23.0/24|Remote network'
+      uci add_list netifyd.config.bypassv4='192.168.5.164|Critical host'
       uci commit netifyd
-      echo '{"changes": {"network": {}}}' | /usr/libexec/rpcd/ns.commit call commit
+      reload_config
 
-In this case the system will exclude interface ``eth1``, all WireGuard ``wgX`` interfaces and all OpenVPN routed interfaces.
-
-- Modify exclusion list: ::
+To edit and manage uci entries, refer to the :ref:`UCI list management <uci-lists>` section.
 
-      uci delete netifyd.@netifyd[0].ns_exclude='eth1'
-      uci add_list netifyd.@netifyd[0].ns_exclude='eth2'
-      uci commit netifyd
-      echo '{"changes": {"network": {}}}' | /usr/libexec/rpcd/ns.commit call commit
-
-- Clear exclusion list: ::
-
-      uci delete netifyd.@netifyd[0].ns_exclude
-      uci commit netifyd
-      echo '{"changes": {"network": {}}}' | /usr/libexec/rpcd/ns.commit call commit
-
-- Return the exclusion list: ::
+You can visualize the applied bypass entries and netifyd capture configuration using the following command: ::
 
-      uci show netifyd.@netifyd[0].ns_exclude
+      nft list table inet netifyd

index.rst

@@ -65,6 +65,7 @@ NethSecurity administrator manual
    :caption: Users and objects
 
    users_databases
+   administrative_users
    objects
 
 .. toctree::
@@ -97,6 +98,12 @@ NethSecurity administrator manual
    ipsec_tunnels
    wireguard
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Logs
+
+   logs
+
 .. toctree::
    :maxdepth: 2
    :caption: High Availability
@@ -115,7 +122,6 @@ NethSecurity administrator manual
    smtp
    snmp
    custom_openvpn_tunnel
-   logs
    speedtest
    ups
    wol