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/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/controller.rst b/controller.rst index 3d44adb4..c2604f63 100644 --- a/controller.rst +++ b/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 `_ +- system operating metrics (CPU, memory, disk, network): these metrics are collected using `Telegraf `_ and stored in `Prometheus `_. 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 ` for more information on how to resinstall it. + .. _grafana-section: Grafana @@ -263,7 +270,7 @@ See the `official documentation `_ 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: diff --git a/dns_dhcp.rst b/dns_dhcp.rst index f14ff7ea..af52205c 100644 --- a/dns_dhcp.rst +++ b/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 --------------------- 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 ---------------------------- 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. diff --git a/index.rst b/index.rst index bc85f71b..f66a7417 100644 --- a/index.rst +++ b/index.rst @@ -117,6 +117,7 @@ NethSecurity administrator manual :maxdepth: 2 :caption: Advanced (CLI) + avahi ddns dns_over_http smtp @@ -126,6 +127,7 @@ NethSecurity administrator manual ups wol checkmk + victoria_logs uci .. toctree:: diff --git a/install.rst b/install.rst index 2642251c..cf8a3045 100644 --- a/install.rst +++ b/install.rst @@ -86,6 +86,10 @@ You can use the downloaded image as a virtual machine disk: .. note:: If you wish to save the logs locally, it is recommended to attach an additional virtual hard drive to the virtual machine and select it as the destination for logs in the ``Storage`` page under the ``System`` section. + If you are deploying a remote virtual machine on a cloud provider, you can also complete the network configuration over virtual monitor with the ``setup`` command + as a quick start. This is often the fastest way to configure the keyboard layout and network interfaces before opening the web user interface. + + Install on Proxmox ------------------ @@ -134,11 +138,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. + +If you are running NethSecurity 8.8, use:: + + apk update + apk add qemu-ga - opkg update - opkg install 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 +190,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 20d601db..254da06c 100644 --- a/logs.rst +++ b/logs.rst @@ -100,10 +100,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/migration.rst b/migration.rst index b20ebf34..2c666c04 100644 --- a/migration.rst +++ b/migration.rst @@ -291,7 +291,7 @@ The following features are not migrated to NethSecurity: - Web proxy (Squid) and filter (ufdbGuard), replaced by :doc:`Content Filtering ` and :ref:`dpi_filter-section` - IPS (Suricata) and IPS alerts (EveBox), replaced by :ref:`intrusion_prevention_system-section` - UPS monitoring (NUT), available only from command line with :doc:`UPS (NUT) ` -- System statistics (Collectd), replaced by Netdata in :ref:`real_time_monitoring-section` +- System statistics (Collectd), replaced by Telegraf and VictoriaMetrics page in :ref:`historical_monitoring-section` - Reports (Dante), replaced by controller metrics in :ref:`controller_metrics-section` - Bandwidth monitor (ntopng), built-in bandwidth monitoring is available in :ref:`real_time_monitoring-section` and through :ref:`controller_metrics-section` - Fail2ban, it is replaced by Threat shield :ref:`brute force attempt block feature ` @@ -301,7 +301,7 @@ The following features are not migrated to NethSecurity: Custom Zones ============ -Custom zones are rarely used in NethServer 7 and tipically for very specific tasks. +Custom zones are rarely used in NethServer 7 and typically for very specific tasks. They are required to define a network segment with firewall rules different from those of the primary interface or, more commonly, to correctly manage traffic coming from a network other than the one to which the interface is connected. These zones allow for defining specific behavior for that network segment and ensure correct routing in complex environments (e.g., a port forwarding rule with a remote host destination via MPLS or a VPN tunnel). diff --git a/monitoring.rst b/monitoring.rst index 3a7dc27e..cb442370 100644 --- a/monitoring.rst +++ b/monitoring.rst @@ -7,12 +7,15 @@ Monitoring NethSecurity provides comprehensive monitoring capabilities to help administrators track the performance and health of the firewall. Monitoring is essential for ensuring the firewall's optimal operation and identifying potential issues that may impact its functionality. -NethSecurity offers two types of monitoring: +NethSecurity offers 3 monitoring views: -- **Real-time monitoring**: it leverages Netdata, Netify agent and logs to provide immediate insights into the firewall's performance. - It reads data from logs and local databases, storing metrics in RAM. Note that these metrics are reset upon every reboot, ensuring that only the most current data are displayed. -- **Historical monitoring**: for a more comprehensive view over time, historical monitoring stores data on a remote controller. - This allows metrics to be preserved across reboots and enables centralized monitoring. Please note that this feature requires a valid subscription both on the firewall and the controller. +- **Real-time monitoring**: it leverages Telegraf, Netifyd and logs to provide immediate insights into the firewall's performance and status, + with detailed charts and alerts. It also uses Netify agent and logs to provide immediate insights into the firewall's traffic, VPN connections and security events. +- **Historical monitoring**: Telegraf writes its data inside VictoriaMetrics, which saves the metrics inside a local persistent storage, when available. + Local historical monitoring is available starting from NethSecurity 8.8 and does not require a subscription. +- **Remote monitoring**: when the firewall is connected to a controller, metrics are also stored remotely using Prometheus. + This allows metrics to be preserved for a longer time and enables centralized monitoring. + Please note that the controller will store metrics only if both the firewall and the controller itself have a valid subscription. .. _real_time_monitoring-section: @@ -103,7 +106,7 @@ The Top Talkers section displays traffic data updated every 30 seconds, providin WAN uplinks ------------- +----------- The WAN uplinks section provides an overview of WAN connections, including status, bandwidth allocation, and traffic data. @@ -121,7 +124,7 @@ This page shows the following information: The results are cached for 5 minutes. - ``WAN interface traffic``: - this histogram shows the traffic data for each WAN connection over the past 60 minutes, sourced from Netdata. + this histogram shows the traffic data for each WAN connection over the past 60 minutes. It helps track real-time performance and diagnose issues such as uneven load balancing or WAN link saturation. - ``Latency to
``: @@ -226,25 +229,49 @@ Available charts are: this char shows the IP addresses that have been blocked most frequently. It is useful for identifying persistent threats or attack sources that should be investigated or blacklisted. +.. _historical_monitoring-section: -Netdata -------- +Historical monitoring +===================== -NethSecurity uses `Netdata `_ as Real-time monitoring tool. -Netdata is an open-source, real-time, performance monitoring and troubleshooting tool for systems and applications. -It provides comprehensive insights into the performance and health of systems and applications through visualizations and detailed metrics. -Netdata is designed to be lightweight, fast, and easy to use. +Starting from NethSecurity 8.8, the Monitoring page includes a new ``Metrics`` view powered by VictoriaMetrics, Telegraf and vmalert. +Telegraf reads the metrics and writes them to VictoriaMetrics, while vmalert evaluates the alert rules. +VictoriaMetrics stores the data in RAM by default, but it automatically switches to persistent storage when available. +If the local storage is removed, the system switches back to RAM storage. -Netdata is enabled by default on NethSecurity and it is accessible from the LAN network. To access it, go to the ``Monitoring`` page -and click :guilabel:`Open report` button from the ``Real-time report`` tab. +As a result, NethSecurity 8.8 metrics remain persistent even without a controller. -Netdata metrics are saved in RAM and will be reset at very machine reboot. -If the firewall is connected to the :ref:`remote controller `, metrics will be stored to the controller itself and preserved across reboots. +Data retention periods are as follows: + +- **RAM storage**: 7 days +- **Persistent storage**: 1 year + + +The ``Metrics`` page has two tabs: ``Charts`` and ``Alerts``. + +Charts +------ + +The ``Charts`` tab shows the following charts: + +* ``CPU usage`` +* ``System load`` +* ``Disk I/O`` +* ``Disk usage (%)`` +* ``Total processes`` +* ``RAM usage`` +* ``Network interface traffic``: one chart for each interface configured on the unit +* ``Network packets`` +* ``Connections (conntrack)`` +* ``Latency``: one chart for each configured ping host +* ``Packet delivery``: one chart for each configured ping host, configured inside the :ref:`ping_latency-section` section + +The chart time range can be changed between 5 minutes, 30 minutes, 1 hour, 12 hours, 24 hours and 7 days. .. _ping_latency-section: Ping latency monitoring ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^ Configure the monitoring tool to evaluate round-trip time and packet loss by transmitting ping messages to network hosts. This tool is employed to monitor the quality of network connectivity. You have the option to include one or more hosts for monitoring, @@ -255,19 +282,64 @@ finally click on the :guilabel:`Save` button to confirm the changes. Changes are applied immediately. To remove a host from the list, click on the delete icon. -You can see a graph of the ping latency by accessing Netdata from the report page. +You can see the latency and packet delivery charts in the ``Metrics`` page after configuring the hosts. -.. _historical_monitoring-section: +.. _alert-section: -Historical monitoring -===================== +Alerts +------ + +The alert system prioritizes only those alerts that have the potential to disrupt or compromise the firewall's functionality. +By focusing on critical indicators, administrators can efficiently address issues that pose a genuine threat to the security and operation of the firewall. + +The ``Alerts`` tab reads current pending and firing alerts from vmalert. +Those alerts are shown locally in the ``Metrics`` page and in the notification drawer opened from the bell icon in the top-right corner. + +Available alerts: + +* ``BackupEncryptionDisabled``: backup encryption is disabled because ``/etc/backup.pass`` is missing or empty. +* ``HighCpuUsage``: CPU usage is above 70%. +* ``CriticalCpuUsage``: CPU usage is above 85%. +* ``HighMemoryUsage``: memory usage is above 80%. +* ``CriticalMemoryUsage``: memory usage is above 90%. +* ``DiskSpaceWarning``: a mounted filesystem is above 80% usage. +* ``DiskSpaceCritical``: a mounted filesystem is above 90% usage. +* ``HighSystemLoad``: system load per CPU is above 2. +* ``WanDown``: a monitored WAN interface is offline. +* ``ServiceDown``: a configured ``procd`` service is not running. +* ``StorageStatus``: the configured data storage is not mounted or is otherwise in error. + +Remote alert notifications +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the server has a valid :ref:`subscription-section`, alert notifications are seamlessly sent to remote servers for centralized monitoring and management. +Both ``my.nethesis.it`` and ``my.nethserver.com`` serve as central hubs for receiving alerts, allowing administrators to stay informed about the firewall's +status and promptly respond to any critical situations. + +Currently, only the following alerts are forwarded to the remote monitoring servers: + +- Disk Space: the disk space alert triggers when available disk space on the system reaches a critical level. + This proactive notification helps prevent potential disruptions by addressing disk space issues before they impact firewall operations. + +- MultiWAN Status (Up/Down): this alert notifies administrators when there are changes in the MultiWAN status, indicating whether connections are up or down. + Timely awareness of MultiWAN status changes is crucial for maintaining continuous and reliable internet connectivity. + +Other alerts, such as CPU and memory usage, are not forwarded to the remote monitoring servers at this time. + + +.. _remote_monitoring-section: + +Remote monitoring +================= .. admonition:: Subscription required This feature is available only if the firewall and the controller have a valid subscription. -If the unit was connected to the controller before the subscription was activated, historical monitoring will not be enabled automatically. -The ``Controller`` page will show a message indicating that historical monitoring is disabled. +Historical monitoring is available locally on the unit and remotely on the controller when the firewall is connected to it. +All data is automatically sent to the controller and stored in Prometheus, allowing for long-term retention and centralized monitoring. + +The ``Controller`` page will show a message indicating that remote monitoring is disabled. To enable it, follow these steps: @@ -277,25 +349,46 @@ To enable it, follow these steps: See the :ref:`controller metrics ` for more information. -.. _alert-section: +.. note:: -Alerts -====== + If the unit was connected to the controller before the subscription was activated, remote monitoring will not be enabled automatically. + To enable it, you need to disconnect the unit from the controller and reconnect it again after the subscription is active. -The alert system leverages the power of the Netdata engine for efficient monitoring and alerting. -The alert system prioritizes only those alerts that have the potential to disrupt or compromise the firewall's functionality. -By focusing on critical indicators, administrators can efficiently address issues that pose a genuine threat to the security and operation of the firewall. +.. _legacy_netdata-section: -If the server has a valid :ref:`subscription-section`, alert notifications are seamlessly sent to remote servers for centralized monitoring and management. -Both ``my.nethesis.it`` and ``my.nethserver.com`` serve as central hubs for receiving alerts, allowing administrators to stay informed about the firewall's -status and promptly respond to any critical situations. +Legacy Netdata +-------------- -Implemented alerts: +.. warning:: -- Disk Space: the disk space alert triggers when available disk space on the system reaches a critical level. - This proactive notification helps prevent potential disruptions by addressing disk space issues before they impact firewall operations. + Starting from 8.8, Netdata has been deprecated and removed from the default installation. + If you still have custom Grafana dashboards that rely on Netdata metrics, + it is recommended to switch to the new Telegraf format. + +NethSecurity 8.7.2 and older uses `Netdata `_ as Real-time monitoring tool. +Netdata is an open-source, real-time, performance monitoring and troubleshooting tool for systems and applications. +It provides comprehensive insights into the performance and health of systems and applications through visualizations and detailed metrics. +Netdata is designed to be lightweight, fast, and easy to use. + +Netdata is enabled by default on NethSecurity 8.7.2 and older and it is accessible from the LAN network. To access it, go to the ``Monitoring`` page +and click :guilabel:`Open report` button from the ``Real-time report`` tab. + +Netdata metrics are saved in RAM and will be reset at every machine reboot. +If the firewall is connected to the :ref:`remote controller `, metrics will be stored to the controller itself and preserved across reboots. + +Install Netdata on NethSecurity 8.8 +----------------------------------- + +If you have configured custom Grafana dashboards that rely on Netdata metrics on the Controller, they will break after upgrading to NethSecurity 8.8 +since Netdata has been removed. + +To restore your dashboards, you can reinstall Netdata manually on NethSecurity 8.8 using the following command:: + + apk update + apk add netdata + +However, it is strongly recommended to migrate your custom dashboards to the new Telegraf format instead. +This ensures better long-term compatibility and support, as Netdata is no longer maintained as part of NethSecurity. -- MultiWAN Status (Up/Down): this alert notifies administrators when there are changes in the MultiWAN status, indicating whether connections are up or down. - Timely awareness of MultiWAN status changes is crucial for maintaining continuous and reliable internet connectivity. 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/release_notes.rst b/release_notes.rst index 224d51e5..e2f39fbf 100644 --- a/release_notes.rst +++ b/release_notes.rst @@ -8,6 +8,41 @@ NethSecurity releases changelogs. - Discussions around `possible bugs `_ +Major changes on 2026-06-25 +=========================== + +Image version: `8.8.0-beta1` (based on OpenWrt 25.12.4) + +.. rubric:: New Features + +- Rebased NethSecurity on OpenWrt 25.12.4 and switched package management from `opkg` to `apk`. +- Monitoring now stores metrics in VictoriaMetrics and automatically uses persistent storage when available. +- Alerts are now accessibile inside the web interface. +- Preserved Bash history across reboots and enabled persistent `/var` when storage is available. +- Added Avahi (mDNS) package to the NethSecurity reposistory. +- Added the firewall `DON'T TRACK` action. +- Several features previously limited to subscription-based versions are now available in the Community edition. +- Added Geoblocking feature to Threat Shield IP, allowing users to block traffic from specific countries or regions. +- Added support for multiple DHCP ranges directly in the UI, allowing for more flexible IP address allocation. + +.. rubric:: Improvements + +- Updated Snort with vectorscan to improve performance. +- Updated OpenVPN to 2.7.4. +- Updated strongSwan to 6.0.3. +- Improved package repository handling and signing for the new base image. +- Netdata is no longer installed by default; legacy controller dashboards can still restore it manually. +- DHCP leases are now persisted if local storage is available, preventing loss of leases on reboot. +- Changes to Threat Shield DNS local list are now applied using the commit button, like all other Threat Shield options. + +.. rubric:: Bug Fixes + +- DNS/DHCP failures now surface clearer troubleshooting information: if dnamsq fails to start, the Web Interface + will display an alert. +- Adblock no longer restarts with empty lists after repeated blocklist or allowlist edits. +- Traffic logging options are shown consistently in the firewall UI. +- IPSec tunnel can now use restart dpd_action. + Major changes on 2026-03-25 =========================== diff --git a/remote_access.rst b/remote_access.rst index 58da5340..9a2c474d 100644 --- a/remote_access.rst +++ b/remote_access.rst @@ -191,25 +191,45 @@ From a Linux machine, use the following command: :: ssh root@192.168.1.1 -VGA console and keyboard layout -=============================== +.. _setup-command-section: -If the machine has a VGA/DVI/HDMI video port, connect a monitor to it. Then, you will be able to log in to the console using the default credentials above. +Using the setup command +======================= -Please note that the system is configured with the US keyboard layout. +If the machine has a VGA/DVI/HDMI video port, connect a monitor to it. You can then use the ``setup`` command from the console to perform the first configuration steps. -To temporarily change the current keyboard layout to Italian, log in to the system and then execute the following command: :: +Use ``setup`` when the web user interface is not yet reachable, or when you are working from VGA, serial console, or SSH on a new firewall. - loadkmap < /usr/share/keymaps/it.map.bin +Run the tool as ``root``:: -The keyboard layout configuration can be saved by writing the keymap code inside ``/etc/keymap``. Example for ``it`` (Italian) keymap: :: + setup - echo 'it' > /etc/keymap - grep -q /etc/keymap /etc/sysupgrade.conf || echo /etc/keymap >> /etc/sysupgrade.conf +The interactive menu lets you: -To obtain the list of available keymaps, execute the following command: :: +* configure the keyboard layout +* configure the LAN and WAN interfaces - ls -1 /usr/share/keymaps/ | cut -d'.' -f1 +Keyboard layout +--------------- + +The system starts with the US keyboard layout. In the ``setup`` menu, choose `keymap` item to switch between the available layouts. +The tool currently supports ``us`` and ``it`` keymaps. + +The selected keymap is applied immediately and saved automatically, so it remains active after reboot. +It's also preserved inside the backup to be restored in case of system recovery or upgrade. + +Network settings +---------------- + +The ``setup`` tool allows you to configure the following network settings: + +- LAN interface: DHCP or static IP address with netmask in CIDR notation +- WAN interface: DHCP or static IP address with netmask in CIDR notation and gateway + +After making changes, the network configuration must be applied with the `Apply network changes` button in the network section. + +If you are using a non-US keyboard layout, you can change it in the setup tool before entering the network configuration. +This is important because the network configuration requires typing IP addresses and other information that may be affected by the keyboard layout. Serial console ============== @@ -240,9 +260,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/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 diff --git a/threat_shield_ip.rst b/threat_shield_ip.rst index 4fc19a30..886e1601 100644 --- a/threat_shield_ip.rst +++ b/threat_shield_ip.rst @@ -135,6 +135,43 @@ Valid syntax for the address is the same as for the :ref:`local_allowlist-sectio When adding addresses to the local blocklist, ensure you enter them correctly to avoid accidentally blocking legitimate traffic. It's also a good practice to include a descriptive comment for each entry to help with future management and auditing of your blocklist. +.. _geoblocking-section: + +Geoblocking +----------- + +The ``Geoblocking`` tab allows you to block network traffic based on the geographic origin of the IP addresses, +relying on country-based IP feeds. This is useful to keep out traffic coming from countries you never expect to +interact with. + +The feature is disabled by default. To enable it, open the ``Geoblocking`` tab and turn on the ``Geo IP Blocking`` switch. +Threat Shield IP must be enabled for geoblocking to work. + +Countries are organized into regions (Africa, Americas, Asia, Europe, Oceania and Others), each shown as a card +reporting the number of currently blocked countries. Selecting a region displays the list of its countries, where you can: + +- block or allow individual countries using their checkbox; +- use the :guilabel:`Block all` and :guilabel:`Allow all` buttons to act on the whole region at once; +- filter the list by country name or by status (blocked / not blocked). + +Click :guilabel:`Save` to apply the configuration. + +.. warning:: Avoid blocking the regions where your own users are located, otherwise legitimate traffic may be dropped. + +Blocking direction +^^^^^^^^^^^^^^^^^^ + +By default, geoblocking only blocks **incoming** connections, i.e. traffic initiated from the selected countries +towards your firewall and networks. Outgoing connections (traffic initiated by your local clients towards hosts in the +selected countries) are still allowed. + +If you also want to block **outgoing** connections to the selected countries, add the ``country`` feed to the +``ban_blockforwardlan`` property, which applies the feed to the LAN-forward chain. From the command line: :: + + uci add_list banip.global.ban_blockforwardlan='country' + uci commit banip + /etc/init.d/banip restart + .. _brute_force-section: Block brute force attacks diff --git a/updates.rst b/updates.rst index fbfff3b8..bb8dee4d 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. @@ -75,9 +84,46 @@ 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. + +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/users_databases.rst b/users_databases.rst index 6f3ecab6..97d7bb20 100644 --- a/users_databases.rst +++ b/users_databases.rst @@ -36,9 +36,9 @@ Please refer to to section :ref:`administrative_users-section`. 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. diff --git a/victoria_logs.rst b/victoria_logs.rst new file mode 100644 index 00000000..c874cbb5 --- /dev/null +++ b/victoria_logs.rst @@ -0,0 +1,26 @@ +============= +Victoria Logs +============= + +NethSecurity 8.8 also ships the optional ``victoria-logs`` package for centralized log storage and aggregation. + +Its Web UI keeps log navigation in one place, so you can browse, query, and visualize the rsyslog stream without jumping between files or services. + +Install it with:: + + apk update + apk add victoria-logs + +The package starts automatically and exposes the Victoria Logs Web UI on port 9428 (``/select/vmui``), accessible only from localhost. +It depends on rsyslog, which forwards syslog messages to Victoria Logs on localhost port 5514. + +Storage and retention are configured automatically: + +* when persistent storage is available, logs are stored under ``/mnt/data/victoria-logs-data`` and retention is set to 1 year +* otherwise logs use ``/var/lib/victoria-logs-data``, retention is limited to 7 days, and disk usage is capped at 50 MB to protect tmpfs + +To access the UI without exposing the service, use SSH port forwarding:: + + ssh -L 9428:127.0.0.1:9428 root@ + +Then open ``http://127.0.0.1:9428/select/vmui`` in your browser. 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 -