From 6b727cc5bac75e98a7a3c6a634e4412d14bddd89 Mon Sep 17 00:00:00 2001 From: Tommaso Bailetti Date: Tue, 6 Oct 2026 17:35:11 +0200 Subject: [PATCH 1/3] feat: added documentation on how to change the network --- .../administrator-manual/system/controller.md | 27 ++++++++++++++++++- .../administrator-manual/system/controller.md | 27 ++++++++++++++++++- 2 files changed, 52 insertions(+), 2 deletions(-) diff --git a/docs/administrator-manual/system/controller.md b/docs/administrator-manual/system/controller.md index 9d425234..de3df111 100644 --- a/docs/administrator-manual/system/controller.md +++ b/docs/administrator-manual/system/controller.md @@ -28,7 +28,7 @@ After the installation, the controller must be configured. The configuration can - `Controller hostname`: The fully qualified domain name for the controller, like: `mycontroller.nethsecurity.org`. Ensure the hostname is resolvable and reachable from the units. - `Let's Encrypt certificate`: Enable or disable Let's Encrypt certificate for the controller web interface. It\'s recommended to enable it. -- `VPN network` and `VPN netmask`: The OpenVPN network and netmask. When choosing the network, make sure it does not overlap with the existing networks inside all the units that will be connected to the controller. Use only class C networks like `192.168.7.0` with netmask `255.255.255.0`. +- `VPN network` and `VPN netmask`: The OpenVPN network and netmask. When choosing the network, make sure it does not overlap with the existing networks inside all the units that will be connected to the controller. The netmask can be anywhere from `255.255.240.0` (/20) to `255.255.255.0` (/24), and the network must be the first address of the network, like `172.19.64.0` with netmask `255.255.240.0`. New installations get a random /20 network. These values can't be changed from the web interface after the first configuration, see [Change the VPN network](#controller_vpn_network-section). - `Administrator user`: The controller administrator user name. The administrator user is the only user that can create and manage other users inside the controller. The same user name is used to access the Grafana interface. - `Administrator password`: Choose a strong password for the administrator user. Note that the default password is displayed only once, please store it in a safe place. The same password is used to access the Grafana interface. For security reasons, you should change the password after the first login both for the controller and the Grafana interface. @@ -53,6 +53,31 @@ The actual `UDP port` number can be found in the Controller module status page u ::: +### Change the VPN network {#controller_vpn_network-section} + +Controllers installed before the /20 support use a /24 VPN network, which limits the number of units. The network can be widened from the NethServer 8 command line. + +Run the following command on the NethServer 8 node as `root`, replacing `nethsecurity-controller1` with the actual controller module instance name. This example widens `172.19.64.0/24` to `172.19.64.0/20`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.19.64.0", "ovpn_netmask": "255.255.240.0"}' + +The command stops the controller, applies the new network and starts the controller again. Units reconnect on their own and keep their VPN IP address. + +Before running it, make sure that: + +- the network address is the same as the current one: only the netmask can change +- the new netmask is wider than the current one, down to `255.255.240.0` (/20) +- the network address is the first address of the new network: `172.19.64.0` is valid for a /20, `172.19.65.0` is not +- the new network does not overlap with the networks inside the connected units + +The command rejects any other change, like moving to a different network or shrinking it. + +:::warning + +Adding `"force": true` to the data skips these checks and also allows netmasks wider than /20. Units with a VPN IP address outside the new network lose the connection to the controller: they must be removed and added again. Changing the network address does this to all units. + +::: + ## Users The controller has two types of users: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md index 524523f3..c917fe2c 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md @@ -28,7 +28,7 @@ Dopo l'installazione, il controller deve essere configurato. La configurazione p - `Hostname del controller`: Il nome di dominio completamente qualificato per il controller, ad esempio: `mycontroller.nethsecurity.org`. Assicurati che il nome host sia risolvibile e raggiungibile dalle unità. - `Certificato Let's Encrypt`: Abilita o disabilita il certificato Let's Encrypt per l'interfaccia web del controller. È consigliato abilitarlo. -- `Rete VPN` e `Maschera VPN`: La rete OpenVPN e la maschera di rete. Quando scegli la rete, assicurati che non si sovrapponga con le reti esistenti all'interno di tutte le unità che verranno connesse al controller. Usa solo reti di classe C come `192.168.7.0` con maschera `255.255.255.0`. +- `Rete VPN` e `Maschera VPN`: La rete OpenVPN e la maschera di rete. Quando scegli la rete, assicurati che non si sovrapponga con le reti esistenti all'interno di tutte le unità che verranno connesse al controller. La maschera può andare da `255.255.240.0` (/20) a `255.255.255.0` (/24) e la rete deve essere il primo indirizzo della rete, ad esempio `172.19.64.0` con maschera `255.255.240.0`. Le nuove installazioni ricevono una rete /20 casuale. Questi valori non possono essere modificati dall'interfaccia web dopo la prima configurazione, vedi [Cambiare la rete VPN](#controller_vpn_network-section). - `Utente amministratore`: Il nome utente dell'amministratore del controller. L'utente amministratore è l'unico utente che può creare e gestire altri utenti all'interno del controller. Lo stesso nome utente viene utilizzato per accedere all'interfaccia Grafana. - `Password amministratore`: Scegli una password complessa per l'utente amministratore. Nota che la password predefinita viene visualizzata una sola volta, conservala in un luogo sicuro. La stessa password viene utilizzata per accedere all'interfaccia Grafana. Per motivi di sicurezza, dovresti cambiare la password dopo il primo accesso sia per il controller che per l'interfaccia Grafana. @@ -53,6 +53,31 @@ Il numero di `porta UDP` effettivo può essere trovato nella pagina dello stato ::: +### Cambiare la rete VPN {#controller_vpn_network-section} + +I controller installati prima del supporto alle reti /20 usano una rete VPN /24, che limita il numero di unità. La rete può essere allargata dalla riga di comando di NethServer 8. + +Esegui il seguente comando sul nodo NethServer 8 come `root`, sostituendo `nethsecurity-controller1` con il nome effettivo dell'istanza del modulo controller. Questo esempio allarga `172.19.64.0/24` a `172.19.64.0/20`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.19.64.0", "ovpn_netmask": "255.255.240.0"}' + +Il comando ferma il controller, applica la nuova rete e riavvia il controller. Le unità si riconnettono da sole e mantengono il loro indirizzo IP VPN. + +Prima di eseguirlo, assicurati che: + +- l'indirizzo di rete sia lo stesso di quello attuale: può cambiare solo la maschera +- la nuova maschera sia più ampia di quella attuale, fino a `255.255.240.0` (/20) +- l'indirizzo di rete sia il primo indirizzo della nuova rete: `172.19.64.0` è valido per una /20, `172.19.65.0` no +- la nuova rete non si sovrapponga con le reti all'interno delle unità connesse + +Il comando rifiuta qualsiasi altra modifica, come spostarsi su una rete diversa o restringerla. + +:::warning + +Aggiungendo `"force": true` ai dati si saltano questi controlli e si consentono anche maschere più ampie di /20. Le unità con un indirizzo IP VPN fuori dalla nuova rete perdono la connessione al controller: devono essere rimosse e aggiunte di nuovo. Cambiare l'indirizzo di rete ha questo effetto su tutte le unità. + +::: + ## Utenti Il controller ha due tipi di utenti: From d99088e15046bb23b98bd76233be54de7779895c Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Thu, 8 Oct 2026 08:32:17 +0200 Subject: [PATCH 2/3] docs: add unaligned VPN network examples A /24 VPN network address is often not a valid /20 address, so the documented example does not apply to most existing controllers. Add the two ways out: widen to the largest netmask keeping the same network address, or move to the containing /20 block with force, which disconnects no unit. Assisted-by: Claude Code:claude-opus-5 --- docs/administrator-manual/system/controller.md | 16 ++++++++++++++++ .../administrator-manual/system/controller.md | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/docs/administrator-manual/system/controller.md b/docs/administrator-manual/system/controller.md index de3df111..f7a8692c 100644 --- a/docs/administrator-manual/system/controller.md +++ b/docs/administrator-manual/system/controller.md @@ -78,6 +78,22 @@ Adding `"force": true` to the data skips these checks and also allows netmasks w ::: +#### When the current network address is not aligned + +A /24 network address is not always a valid /20 address. For example `172.23.142.0/24` cannot become `172.23.142.0/20`, because the /20 block that contains it starts at `172.23.128.0`. + +There are two ways out. + +Widen to the largest netmask that keeps the same network address. `172.23.142.0` is a valid /23 address, so the network can grow to `172.23.142.0/23`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.142.0", "ovpn_netmask": "255.255.254.0"}' + +Or move to the /20 block that already contains the current network, using `force`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.128.0", "ovpn_netmask": "255.255.240.0", "force": true}' + +Here `force` is needed only because the network address changes. No unit is disconnected: every address of `172.23.142.0/24`, like `172.23.142.2`, is also inside `172.23.128.0/20`. Before running it, make sure the whole new /20 does not overlap with the networks inside the connected units. + ## Users The controller has two types of users: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md index c917fe2c..82dac8c6 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md @@ -78,6 +78,22 @@ Aggiungendo `"force": true` ai dati si saltano questi controlli e si consentono ::: +#### Quando l'indirizzo di rete attuale non è allineato + +Un indirizzo di rete /24 non è sempre un indirizzo /20 valido. Ad esempio `172.23.142.0/24` non può diventare `172.23.142.0/20`, perché il blocco /20 che lo contiene inizia a `172.23.128.0`. + +Ci sono due soluzioni. + +Allargare fino alla maschera più ampia che mantiene lo stesso indirizzo di rete. `172.23.142.0` è un indirizzo /23 valido, quindi la rete può diventare `172.23.142.0/23`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.142.0", "ovpn_netmask": "255.255.254.0"}' + +Oppure spostarsi sul blocco /20 che già contiene la rete attuale, usando `force`: + + api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.128.0", "ovpn_netmask": "255.255.240.0", "force": true}' + +In questo caso `force` serve solo perché cambia l'indirizzo di rete. Nessuna unità viene disconnessa: ogni indirizzo di `172.23.142.0/24`, come `172.23.142.2`, si trova anche dentro `172.23.128.0/20`. Prima di eseguirlo, assicurati che l'intera nuova /20 non si sovrapponga con le reti all'interno delle unità connesse. + ## Utenti Il controller ha due tipi di utenti: From 2884494b980f492239ecc41248f122194d2bac80 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Thu, 8 Oct 2026 08:35:10 +0200 Subject: [PATCH 3/3] docs: state how many units each VPN network holds Readers choosing between the two widening options need the capacity of each result to decide. A network holds its size minus the network address, the broadcast address and one address for the controller. Assisted-by: Claude Code:claude-opus-5 --- docs/administrator-manual/system/controller.md | 6 ++++-- .../current/administrator-manual/system/controller.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/administrator-manual/system/controller.md b/docs/administrator-manual/system/controller.md index f7a8692c..c3e4fc57 100644 --- a/docs/administrator-manual/system/controller.md +++ b/docs/administrator-manual/system/controller.md @@ -84,16 +84,18 @@ A /24 network address is not always a valid /20 address. For example `172.23.142 There are two ways out. -Widen to the largest netmask that keeps the same network address. `172.23.142.0` is a valid /23 address, so the network can grow to `172.23.142.0/23`: +Widen to the largest netmask that keeps the same network address. `172.23.142.0` is a valid /23 address, so the network can grow to `172.23.142.0/23`, which holds 509 units instead of 253: api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.142.0", "ovpn_netmask": "255.255.254.0"}' -Or move to the /20 block that already contains the current network, using `force`: +Or move to the /20 block that already contains the current network, using `force`. A /20 holds 4093 units: api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.128.0", "ovpn_netmask": "255.255.240.0", "force": true}' Here `force` is needed only because the network address changes. No unit is disconnected: every address of `172.23.142.0/24`, like `172.23.142.2`, is also inside `172.23.128.0/20`. Before running it, make sure the whole new /20 does not overlap with the networks inside the connected units. +The number of units a network holds is the size of the network minus its network address, its broadcast address and one address for the controller itself. + ## Users The controller has two types of users: diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md index 82dac8c6..d0c7ef57 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/system/controller.md @@ -84,16 +84,18 @@ Un indirizzo di rete /24 non è sempre un indirizzo /20 valido. Ad esempio `172. Ci sono due soluzioni. -Allargare fino alla maschera più ampia che mantiene lo stesso indirizzo di rete. `172.23.142.0` è un indirizzo /23 valido, quindi la rete può diventare `172.23.142.0/23`: +Allargare fino alla maschera più ampia che mantiene lo stesso indirizzo di rete. `172.23.142.0` è un indirizzo /23 valido, quindi la rete può diventare `172.23.142.0/23`, che ospita 509 unità invece di 253: api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.142.0", "ovpn_netmask": "255.255.254.0"}' -Oppure spostarsi sul blocco /20 che già contiene la rete attuale, usando `force`: +Oppure spostarsi sul blocco /20 che già contiene la rete attuale, usando `force`. Una /20 ospita 4093 unità: api-cli run module/nethsecurity-controller1/set-vpn-network --data '{"ovpn_network": "172.23.128.0", "ovpn_netmask": "255.255.240.0", "force": true}' In questo caso `force` serve solo perché cambia l'indirizzo di rete. Nessuna unità viene disconnessa: ogni indirizzo di `172.23.142.0/24`, come `172.23.142.2`, si trova anche dentro `172.23.128.0/20`. Prima di eseguirlo, assicurati che l'intera nuova /20 non si sovrapponga con le reti all'interno delle unità connesse. +Il numero di unità che una rete ospita è la dimensione della rete meno il suo indirizzo di rete, il suo indirizzo di broadcast e un indirizzo per il controller stesso. + ## Utenti Il controller ha due tipi di utenti: