From 751b39d7e2c0e75b86cc09c63349320ecd807ba8 Mon Sep 17 00:00:00 2001 From: Tommaso Bailetti Date: Thu, 28 May 2026 15:41:04 +0200 Subject: [PATCH 1/8] docs: added avahi documentation (#255) --- avahi.rst | 38 ++++++++++++++++++++++++++++++++++++++ index.rst | 1 + 2 files changed, 39 insertions(+) create mode 100644 avahi.rst diff --git a/avahi.rst b/avahi.rst new file mode 100644 index 00000000..ca37f436 --- /dev/null +++ b/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. diff --git a/index.rst b/index.rst index b4f38f57..69440ea8 100644 --- a/index.rst +++ b/index.rst @@ -110,6 +110,7 @@ NethSecurity administrator manual :maxdepth: 2 :caption: Advanced (CLI) + avahi ddns dns_over_http smtp From 32a2c2c8aab73d7867bf1a453694156db27d2ebb Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Thu, 28 May 2026 16:05:20 +0200 Subject: [PATCH 2/8] docs: document firewall don't track action --- firewall_rules.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/firewall_rules.rst b/firewall_rules.rst index 0a46b3b8..516d7f80 100644 --- a/firewall_rules.rst +++ b/firewall_rules.rst @@ -44,6 +44,8 @@ Fill in the following fields for the new rule: * ``Accept``: accept the network traffic. * ``Reject``: block the traffic and notify the sender host. * ``Drop``: block the traffic, packets are dropped and no notification is sent to the sender host. + * ``Don't track``: bypass connection tracking for matching traffic. This action is available only in + ``Forward rules`` and ``Input rules``, requires a source zone, and is not available in ``Output rules``. * ``Rule position``: decide whether to add the rule to the bottom or top of the rule list. * ``Logging``: indicate whether traffic matching this rule should be logged. The log entry will include the rule name as a prefix. By default, logging is limited to 1 entry per second. See the :ref:`logging-limits` section for instructions on changing this limit. From bffee8d6ab3f1380bc1bd49f31c27cce1b5f1682 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Fri, 29 May 2026 09:15:02 +0200 Subject: [PATCH 3/8] docs: note community access for updates and ldap #275 --- updates.rst | 4 ++-- users_databases.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/updates.rst b/updates.rst index fbfff3b8..0d7f4ac3 100644 --- a/updates.rst +++ b/updates.rst @@ -75,9 +75,9 @@ After the upgrade, ensure that the system has internet access, then restore the Automatic package updates ========================= -.. admonition:: Subscription required +.. note:: No subscription required - This feature is available only if the firewall has a valid subscription. + Starting from NethSecurity 8.8, this feature is available even without a subscription. Automatic updates for packages can be enabled from the ``Update`` section under the ``System`` menu, by enabling the ``Automatic updates`` option. Updates are checked daily and, if available, they are automatically downloaded and installed. diff --git a/users_databases.rst b/users_databases.rst index bf01d2e8..aee38fff 100644 --- a/users_databases.rst +++ b/users_databases.rst @@ -36,9 +36,9 @@ The user must have a password set. Remote databases ================ -.. admonition:: Subscription required +.. note:: No subscription required - This feature is available only if the firewall has a valid subscription. + Starting from NethSecurity 8.8, this feature is available even without a subscription. The administrator can extend the capabilities of the firewall by adding new remote databases. Remote databases allow the firewall to authenticate users against an external LDAP server, such as Active Directory or OpenLDAP. From aac3deee5fb511ed5e3c0ca2ffd1ac0625e39574 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Fri, 29 May 2026 09:15:31 +0200 Subject: [PATCH 4/8] docs: add adblock troubleshooting guidance (#276) --- threat_shield_dns.rst | 46 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/threat_shield_dns.rst b/threat_shield_dns.rst index 1f8cd7be..a27ecc58 100644 --- a/threat_shield_dns.rst +++ b/threat_shield_dns.rst @@ -150,6 +150,52 @@ The output might look like this: This output shows if the domain is currently blocked by any active blocklists. In this specific example, the domain `baddomain.com` is part of the category **adult**, as indicated by ``adb_list.adult.gz``. This helps you identify which category or list caused the domain to be blocked. +.. _adblock_troubleshooting-section: + +Troubleshooting +=============== + +After enabling Adblock or changing its configuration, wait up to 30 seconds for the changes to be applied. +During boot, Adblock also waits around 30 seconds for the network to come up before loading the feeds. + +Use the following command to check whether Adblock is running:: + + /etc/init.d/adblock status + +If the output shows zero blocked domains and no active feeds, Adblock has not loaded anything yet. In that case the status may look like this:: + + ::: adblock runtime information + + adblock_status : enabled + + frontend_ver : 4.5.5-r2 + + backend_ver : 4.5.5-r3 + + blocked_domains : 0 + + active_feeds : - + + dns_backend : dnsmasq (2.91-r3), /tmp/dnsmasq.d, 3.39 MB + + run_ifaces : trigger: -, report: br-lan + + run_information : base: /tmp, dns: /tmp/dnsmasq.d, backup: /tmp/adblock-backup, report: /tmp/adblock-report, error: /tmp/adb_error.log + + run_flags : shift: ✘, custom feed: ✔, ext. DNS (std/prot/remote/bridge): ✘/✘/✘/✘, force: ✔, flush: ✘, tld: ✔, search: ✘, report: ✔, mail: ✘, jail: ✘, debug: ✔ + + last_run : mode: reload, date / time: 28/05/2026 13:44:31, duration: 0m 5s, memory: 3450.30 MB available + + system_info : cores: 2, fetch: wget, Nethesis NethBox Z1+, x86/64, NethSecurity 8.8.0-nethsecurity-8.8.20260528105131.094c098 (r32933-4ccb782af7) + +A correctly loaded system should look like this:: + + ::: adblock runtime information + + adblock_status : enabled + + frontend_ver : 4.5.5-r2 + + backend_ver : 4.5.5-r3 + + blocked_domains : 237 974 + + active_feeds : doh_vpn_tor_proxy gambling, + + dns_backend : dnsmasq (2.91-r3), /tmp/dnsmasq.ns_dnsmasq.d, 19.74 MB + + run_ifaces : trigger: -, report: - + + run_information : base: /tmp, dns: /tmp/dnsmasq.ns_dnsmasq.d, backup: /tmp/adblock-backup, report: /tmp/adblock-report, error: /dev/null + + run_flags : shift: ✘, custom feed: ✔, ext. DNS (std/prot/remote/bridge): ✘/✘/✘/✘, force: ✔, flush: ✘, tld: ✔, search: ✘, report: ✘, mail: ✘, jail: ✘, debug: ✘ + + last_run : mode: reload, date / time: 28/05/2026 14:30:37, duration: 0m 2s, memory: 708.93 MB available + + system_info : cores: 2, fetch: curl, QEMU Standard PC (Q35 + ICH9, 2009), x86/64, NethSecurity 8.8.0-nethsecurity-8.8.20260527151745.8ae1ddcc9 (r32933-4ccb782af7) + +If there were network problems and Adblock could not download any feed, just restart it:: + + /etc/init.d/adblock restart + .. _advanced_configuration-section: Advanced configuration From 88c13b63d9cfaeb29451d7a61bd4d936c3456a3d Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Thu, 28 May 2026 15:36:16 +0200 Subject: [PATCH 5/8] docs: note persistent DHCP leases on storage --- dns_dhcp.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/dns_dhcp.rst b/dns_dhcp.rst index f14ff7ea..52691e9f 100644 --- a/dns_dhcp.rst +++ b/dns_dhcp.rst @@ -96,6 +96,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 --------------------- From 847d38deaebfa18e953696032a8e6327921569de Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Fri, 29 May 2026 09:16:51 +0200 Subject: [PATCH 6/8] docs(doh): update https-dns-proxy guide #266 --- dns_over_http.rst | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index efe7d0e7..a84cdf57 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -10,8 +10,9 @@ DNS over HTTPS (DoH) is a protocol for encrypting DNS queries over HTTPS, enhanc This feature allows you to configure upstream DNS servers that support the DoH protocol. The ``https-dns-proxy`` package provides a local DNS-to-HTTPS proxy that forwards DNS queries to a remote DoH provider. -This document provides instructions for installing and configuring the DoH upstream servers that provide -filtering and are based in the EU, but you can use any DoH provider that suits your needs. +This document provides instructions for configuring DoH upstream servers that +provide filtering and are based in the EU, but you can use any DoH provider +that suits your needs. This configuration only applies to the upstream servers of the firewall: clients will continue to send DNS requests to the firewall in plaintext on port 53. A list of DoH providers that support European locations and filtering are available on the @@ -28,7 +29,10 @@ Some popular alternatives include: Installation ============ -The ``https-dns-proxy`` package is not included in default NethSecurity images, so you will need to install it manually: :: +Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no +separate installation step is required. + +On NethSecurity 8.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: opkg update opkg install https-dns-proxy @@ -36,12 +40,17 @@ The ``https-dns-proxy`` package is not included in default NethSecurity images, Configuration ============= -By default, the package includes two providers (Cloudflare and Google). -To use a custom DoH provider, you'll need to: +By default, the package includes two providers (Cloudflare and Google), listens +on ``127.0.0.1:5053`` and ``127.0.0.1:5054``, and keeps +``dnsmasq_config_update`` set to ``-`` so it does not modify the firewall DNS +configuration automatically. + +To start using the proxy, you need to: 1. Remove the default providers (optional) 2. Add your preferred DoH provider configuration -3. Commit and apply the configuration +3. Choose the ``dnsmasq_config_update`` value to use +4. Commit the configuration and enable the service Configuration steps ------------------- @@ -65,9 +74,16 @@ In this example, we will configure the DNS4EU (joindns4.eu) DoH provider. The ``bootstrap_dns`` parameter is optional, if not provided, the system will use Google and Cloudflare DNS for bootstrap. -3. Apply the configuration, https-dns-proxy will automatically use the local DoH proxy as upstream DNS: :: +3. Enable integration with ``dnsmasq`` and start the service: :: + + uci set https-dns-proxy.config.dnsmasq_config_update='*' + uci commit https-dns-proxy + /etc/init.d/https-dns-proxy enable + /etc/init.d/https-dns-proxy start - reload_config + The value ``*`` updates all ``dnsmasq`` instances. If you need a more + specific integration, set ``dnsmasq_config_update`` to the instance name or + index you want to manage. Verification ^^^^^^^^^^^^ @@ -100,18 +116,13 @@ Run the following commands via SSH or terminal: :: Image update ------------ -The ``https-dns-proxy`` package overrides the default DNS configuration, -so if you update your NethSecurity image, the system will not be able to connect to Internet -and restore the package. +The package is included in the image, so it does not need to be reinstalled +after an upgrade. -To overcome this issue, you can temporarily stop the DoH proxy before updating the image: :: +However, NethSecurity treats ``dnsmasq_config_update='-'`` as the disabled +state. If that value is still set during an image upgrade, the first-boot +defaults script can disable ``https-dns-proxy`` again. - service https-dns-proxy stop - -This will restore the default DNS configuration and allow the system to connect to the Internet -after image update. Once the update is complete, you can restart the DoH proxy: :: - - service https-dns-proxy restart Blocking other DoH providers ---------------------------- From 572c9b0632446fd55bfc17bede00fc00cf20e093 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Fri, 29 May 2026 09:17:33 +0200 Subject: [PATCH 7/8] docs: clarify extra package restore retries (#269) --- updates.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/updates.rst b/updates.rst index 0d7f4ac3..22e1da97 100644 --- a/updates.rst +++ b/updates.rst @@ -49,6 +49,15 @@ Restore extra packages ---------------------- Starting from version 8.7.2, extra packages are automatically reinstalled after system upgrade. Please note that the reinstall procedure requires access to Internet. +If one or more packages cannot be installed because the network is not yet ready or a transient error occurs, +the restore service stays enabled and retries automatically on the next boot until all packages are restored. +Restored packages are reported inside the log. +For example, a mixed restore may log:: + + Restored package: etherwake + Failed to restore package: qemu-ga + Some packages failed to restore, will retry later + In case of error, proceed with the manual restore documented below. See the next section for earlier versions. From a5696f552a2aacc979307f2d5b53fb1eba23b1f2 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Fri, 29 May 2026 09:18:58 +0200 Subject: [PATCH 8/8] docs: document opkg and apk command equivalents (#272) --------- Co-authored-by: Matteo Di Lorenzi <52289654+m-dilorenzi@users.noreply.github.com> --- checkmk.rst | 9 ++++++++- install.rst | 28 ++++++++++++++++++++-------- logs.rst | 12 +++++++++--- network.rst | 21 +++++++++++++++------ remote_access.rst | 10 ++++++++-- updates.rst | 37 +++++++++++++++++++++++++++++++++++++ ups.rst | 32 ++++++++++++++++++++++++++------ wol.rst | 10 ++++++++-- 8 files changed, 131 insertions(+), 28 deletions(-) diff --git a/checkmk.rst b/checkmk.rst index 1b1f9df9..09e4659e 100644 --- a/checkmk.rst +++ b/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 diff --git a/install.rst b/install.rst index 2642251c..d2e79e6d 100644 --- a/install.rst +++ b/install.rst @@ -134,11 +134,17 @@ QEMU guest agent QEMU guest agent is not part of the NethSecurity image but can be installed from the command line. The agent can work when the virtual machine is running on KVM, Proxmox, or other QEMU-based hypervisors. -First, make sure the virtual machine is running, then connect to the machine using SSH or the Proxmox console and -execute the following commands: :: +First, make sure the virtual machine is running, then connect to the machine using SSH or the Proxmox console. - opkg update - opkg install qemu-ga +If you are running NethSecurity 8.8, use:: + + apk update + apk add qemu-ga + +If you are running NethSecurity 8.7.2 or older, use:: + + opkg update + opkg install qemu-ga After the installation, start the service: :: @@ -180,11 +186,17 @@ VMware open-vm-tools VMware open-vm-tools are not part of the NethSecurity image but can be installed from the command line. The tools can work only when the virtual machine is running on VMWare hypervisors. -First make sure the virtual machine is running, then connect to the machine using SSH or the VMWare console and -execute the following commands: :: +First, make sure the virtual machine is running, then connect to the machine using SSH or the VMWare console. + +If you are running NethSecurity 8.8, use:: + + apk update + apk add open-vm-tools + +If you are running NethSecurity 8.7.2 or older, use:: - opkg update - opkg install open-vm-tools + opkg update + opkg install open-vm-tools After the installation, start the service: :: diff --git a/logs.rst b/logs.rst index cd54dede..0ffe8d64 100644 --- a/logs.rst +++ b/logs.rst @@ -65,10 +65,16 @@ The daemon polls for new lines every 10 seconds, detects log rotation automatica 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 +If you are running NethSecurity 8.8, use:: + + apk update + apk add ns-clm + +If you are running NethSecurity 8.7.2 or older, use:: + + opkg update + opkg install ns-clm The UCI configuration is stored in ``/etc/config/ns-clm``: diff --git a/network.rst b/network.rst index c647e67b..747fcb37 100644 --- a/network.rst +++ b/network.rst @@ -162,12 +162,17 @@ These packages can be installed from the command line console, just find the cor Bus 001 Device 002: ID 0627:0001 QEMU QEMU USB Tablet Bus 001 Device 001: ID 1d6b:0002 Linux 5.15.162 xhci-hcd xHCI Host Controller -* Search for the the kernel module: +* Search for the kernel module: - :: + If you are running NethSecurity 8.8, use:: + + apk update + apk search kmod-usb-net-* + + If you are running NethSecurity 8.7.2 or older, use:: - opkg update - opkg find kmod-usb-net-\* + opkg update + opkg find kmod-usb-net-* * Output example: @@ -188,9 +193,13 @@ These packages can be installed from the command line console, just find the cor * Install the right driver: - :: + If you are running NethSecurity 8.8, use:: + + apk add kmod-usb-net-rtl8150 + + If you are running NethSecurity 8.7.2 or older, use:: - opkg install kmod-usb-net-rtl8150 + opkg install kmod-usb-net-rtl8150 * Verify a new ethX interface appears using ``ifconfig -a`` * Configure the ethernet from the UI diff --git a/remote_access.rst b/remote_access.rst index a94dee3b..5f905d43 100644 --- a/remote_access.rst +++ b/remote_access.rst @@ -337,9 +337,15 @@ Two packages are provided for installation, covering the vast majority of adapte * To install Prolific PL2303 driver: - :: + If you are running NethSecurity 8.8, use:: + + apk update + apk add kmod-usb-serial-pl2303 + + If you are running NethSecurity 8.7.2 or older, use:: - opkg install kmod-usb-serial-pl2303 + opkg update + opkg install kmod-usb-serial-pl2303 * The logs will show an output similar to this: diff --git a/updates.rst b/updates.rst index 22e1da97..bb8dee4d 100644 --- a/updates.rst +++ b/updates.rst @@ -90,3 +90,40 @@ Automatic package updates Automatic updates for packages can be enabled from the ``Update`` section under the ``System`` menu, by enabling the ``Automatic updates`` option. Updates are checked daily and, if available, they are automatically downloaded and installed. + +Package manager commands +======================== + +NethSecurity 8.8 uses ``apk``. NethSecurity 8.7.2 and earlier use ``opkg``. +Use the following quick reference when translating older command examples: + +.. list-table:: + :header-rows: 1 + :widths: 28 28 44 + + * - OPKG command + - APK equivalent + - Description + * - ``opkg install `` + - ``apk add `` + - Install a package + * - ``opkg remove `` + - ``apk del `` + - Remove a package + * - ``opkg upgrade`` + - ``apk upgrade`` + - Upgrade all packages + * - ``opkg files `` + - ``apk info -L `` + - List package contents + * - ``opkg list-installed`` + - ``apk info`` + - List installed packages + * - ``opkg update`` + - ``apk update`` + - Update package lists + * - ``opkg search `` + - ``apk search `` + - Search for packages + +The ``opkg find`` command used in a few older examples maps to ``apk search`` on NethSecurity 8.8. diff --git a/ups.rst b/ups.rst index 382b6592..3a3aea60 100644 --- a/ups.rst +++ b/ups.rst @@ -38,7 +38,14 @@ Then, follow these steps: Step 1: install the required packages -------------------------------------- -Install the required packages:: +Install the required packages. + +If you are running NethSecurity 8.8, use:: + + apk update + apk add nut-server nut-upsc nut-upsmon nut-upscmd + +If you are running NethSecurity 8.7.2 or older, use:: opkg update opkg install nut-server nut-upsc nut-upsmon nut-upscmd @@ -61,9 +68,15 @@ Step 2: setup the appropriate driver 2. Select the driver from the `NUT driver page `_. 3. All driver packages start with ``nut-driver-`` prefix. Some UPS models may require a specific driver, but most of them work with the ``usbhid-ups`` driver. - Install the selected driver package, in this case the ``usbhid-ups`` driver: :: + Install the selected driver package, in this case the ``usbhid-ups`` driver. + + If you are running NethSecurity 8.8, use:: + + apk add nut-driver-usbhid-ups - opkg install nut-driver-usbhid-ups + If you are running NethSecurity 8.7.2 or older, use:: + + opkg install nut-driver-usbhid-ups 4. Set up the driver inside the ``upsd`` (nut-server) server. The nut-server will connect to the UPS using the driver and the port specified. It will monitor the UPS at regular intervals and provide the information to the clients like ``upsmon``. Execute: :: @@ -184,10 +197,17 @@ Connect to remote NUT server This is the case where a secondary firewall is connected to the same UPS and the NUT server is running on the primary firewall. The secondary firewall will connect to the primary firewall and monitor the UPS status. -1. First, install the NUT services on the client machine:: +1. First, install the NUT services on the client machine. - opkg update - opkg install nut-upsc nut-upsmon + If you are running NethSecurity 8.8, use:: + + apk update + apk add nut-upsc nut-upsmon + + If you are running NethSecurity 8.7.2 or older, use:: + + opkg update + opkg install nut-upsc nut-upsmon These packages are not preserved during a system upgrade. For more info see :ref:`restore_extra_packages-section`. diff --git a/wol.rst b/wol.rst index 3e939710..2c1ac8e9 100644 --- a/wol.rst +++ b/wol.rst @@ -13,7 +13,14 @@ On NethSecurity, EtherWake is available in the official repositories but it is n Installation ------------ -Install the package with:: +Install the package with the commands that match your NethSecurity version. + +If you are running NethSecurity 8.8, use:: + + apk update + apk add etherwake + +If you are running NethSecurity 8.7.2 or older, use:: opkg update opkg install etherwake @@ -37,4 +44,3 @@ The basic command is:: Example:: etherwake -i eth0 00:11:22:33:44:55 -