Enhance HA maintenance troubleshooting documentation

docs/administrator-manual/high-availability/ha_maintenance_troubleshooting.md

@@ -64,14 +64,92 @@ After connecting to the primary node, use the following command to access the se
 
 This command will establish an SSH connection to the secondary node using the SSH key generated during the HA setup.
 
-### Upgrade
+### Upgrading the secondary node
 
-The secondary node does not receive system updates automatically because it does not have direct Internet access. To update the secondary node, you need to connect to the primary node and run the update command on the primary node itself:
+The secondary node does not receive system updates automatically because it does not have direct Internet access. To update the secondary node, you need to connect to the primary node and **run the update command on the primary node** itself:
 
     ns-ha-config upgrade-remote
 
 This command will download the latest image, upload it to the secondary node, and install it. As a normal upgrade, the secondary node will reboot after the installation.
 
+### Upgrading an HA pair
+
+When a new NethSecurity version is released, both nodes of the cluster have to be moved to it, and the order matters: upgrade the secondary node first, since
+`upgrade-remote` runs from the primary node and the node being upgraded is not carrying traffic.
+
+1. On the primary node, run `ns-ha-config status`: the roles must be correct and the `Last Sync Status` must be `Successful`. Do not upgrade a cluster that is not already healthy.
+2. From the primary node, run `ns-ha-config upgrade-remote`. The secondary node reboots; only redundancy is lost.
+3. Wait for the synchronization status to return to `Up to Date`.
+4. Upgrade the primary node and let it reboot, the secondary node takes over during the reboot and hands the role back when the primary node returns.
+5. Check `ns-ha-config status` on both nodes, confirm that the services are running on the primary node, then wait 10 minutes before testing a failover.
+
+### Adding a secondary node to a degraded HA cluster
+
+If you detached the secondary node for maintenance, or replaced its hardware, and the primary node has kept serving traffic on its own in a degraded cluster,
+this is the procedure to follow. The firewall you are about to put in has never belonged to this cluster and carries no HA configuration of its own.
+
+Adding it does not require a reset: the configuration of the primary node is still valid, and only the association with the new device has to be created.
+
+Prepare the new firewall exactly as you would when building a cluster from scratch, following [Setup and management](ha_setup_and_management): same interface names, same devices and the same static addresses as the node it replaces, on the HA interface and on every additional LAN of the cluster.
+
+Then repeat, from the primary node, every step of the initial cluster setup except `init-primary-node`. Start by checking the new node: the command verifies its addressing, the SSH access and the DHCP options before anything is written.
+
+    ns-ha-config check-backup-node <backup_node_ip> <lan_interface>
+    ns-ha-config init-backup-node <lan_interface>
+
+Then run again, with the same values used when the cluster was first set up, one command for every additional LAN and every additional virtual IP:
+
+    ns-ha-config add-lan-interface <primary_node_ip> <backup_node_ip> <virtual_ip>
+    ns-ha-config add-vip <lan_interface> <virtual_ip>
+
+:::warning
+
+The additional LANs and virtual IPs must be added again even though nothing changed on the primary node. Those commands are the only thing that creates the corresponding
+sections on the secondary node.
+
+Skipping them leaves a cluster that looks healthy, with a correct `ns-ha-config status`, but whose additional LANs have no virtual IP after a failover.
+
+:::
+
+Finally, check the result and test a failover, confirming that **every** virtual IP is present on the secondary node, not only the one of the HA interface.
+
+### Reset the configuration
+
+:::note
+
+Reset the cluster when you want to dismantle it and go back to standalone firewalls, or when you are rebuilding it with a different layout: fewer interfaces, different virtual IPs. 
+The sections of the previous cluster survive on the primary node and no other command removes them.
+
+Resetting is not needed to replace or re-add a secondary node, see
+[Adding a secondary node to a degraded HA cluster](#adding-a-secondary-node-to-a-degraded-ha-cluster).
+
+:::
+
+The reset command restores the cluster configuration to its default state, it must be run locally on the primary node, and while the secondary node is still connected, so that the secondary node is reset too.
+Typically, after the reset, the primary node can continue operating normally, while the secondary node, no longer used in the cluster should be disconnected and reset to default to avoid any conflicts.
+
+The reset command will:
+
+- Stop and disable `keepalived` and `conntrackd`.
+- Remove HA configuration files.
+- Clean up `dropbear` configuration including SSH keys.
+
+At the end, a reboot is required to apply the changes. Just execute: :
+
+    ns-ha-config reset
+    reboot
+
+
+Interface addresses are not touched: both nodes keep their own IP addresses, and only the virtual IPs disappear because they are managed by `keepalived`. 
+The primary node can be set up again straight away.
+
+:::warning
+
+The virtual IP does not exist until the cluster is set up again: clients using it as gateway or DNS server lose connectivity in the meantime.
+
+:::
+
+
 ## Troubleshooting {#troubleshooting_ha-section}
 
 Troubleshooting the HA setup can be challenging, especially if the secondary node is not reachable or the primary node is not responding as expected.
@@ -173,17 +251,3 @@ Enable `keepalived` debug logging (on primary): :
 
 Then, search for `Keepalived_vrrp` in the `/var/log/messages` file.
 
-### Reset the configuration
-
-The reset command restores the cluster configuration to its default state. Typically, after the reset, the primary node can continue operating normally, while the secondary node, no longer used in the cluster should be reset to default to avoid any conflicts. After the reset, only the HA interface remains active, so a reboot is required to complete the process. The reset must be performed locally on the primary node.
-
-To reset command will:
-
-- Stop and disable `keepalived` and `conntrackd`.
-- Remove HA configuration files.
-- Clean up `dropbear` configuration including SSH keys.
-
-At the end, a reboot is required to apply the changes. Just execute: :
-
-    ns-ha-config reset
-    reboot

docs/administrator-manual/high-availability/ha_setup_and_management.md

@@ -227,6 +227,12 @@ A Virtual IP (VIP) is an additional IP address assigned to a network interface t
 
 This is useful for services that require multiple IP addresses on the same interface, such as virtual servers or load balancing.
 
+:::note
+
+Virtual IPs can only be added to the LAN interfaces of the cluster. Additional public addresses on a WAN are configured as aliases on the primary node and are replicated automatically, see [WAN interfaces](#wan-interfaces).
+
+:::
+
 Use the `ns-ha-config` command to register the virtual IP in the HA cluster configuration.
 
 Virtual IPs must be explicitly set on the primary node. :

i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/high-availability/ha_maintenance_troubleshooting.md

@@ -64,14 +64,89 @@ Dopo aver stabilito la connessione al nodo primario, utilizza il seguente comand
 
 Questo comando stabilirà una connessione SSH al nodo secondario utilizzando la chiave SSH generata durante la configurazione HA.
 
-### Aggiornamento
+### Aggiornamento del nodo secondario
 
 Il nodo secondario non riceve gli aggiornamenti di sistema automaticamente perché non ha accesso diretto a Internet. Per aggiornare il nodo secondario, è necessario connettersi al nodo primario e da lì lanciare il comando di aggiornamento:
 
     ns-ha-config upgrade-remote
 
 Questo comando scaricherà l'immagine più recente, la caricherà sul nodo secondario e l'installerà. Come un normale aggiornamento, il nodo secondario si riavvierà dopo l'installazione.
 
+### Aggiornamento di una coppia HA
+
+Quando esce una nuova versione di NethSecurity è necessario portare entrambi i nodi del cluster alla stessa versione, e l'ordine conta: è conveniente aggiornare per primo il nodo secondario, dato che `upgrade-remote` si lancia dal nodo primario e il nodo che viene aggiornato non sta gestendo traffico.
+
+1. Sul nodo primario eseguire `ns-ha-config status`: i ruoli devono essere corretti e `Last Sync Status` deve riportare `Successful`. Non aggiornare un
+   cluster che non sia già in buona salute.
+2. Dal nodo primario eseguire `ns-ha-config upgrade-remote`. Il nodo secondario si riavvia; si perde soltanto la ridondanza.
+3. Attendere una nuova sincronizzazione tra i 2 nodi.
+4. Aggiornare il nodo primario e lasciarlo riavviare: durante il riavvio il nodo secondario assume il ruolo di master e lo restituisce quando il nodo primario torna disponibile.
+5. Verificare `ns-ha-config status` su entrambi i nodi, controllare che i servizi siano attivi sul nodo primario, quindi attendere 10 minuti prima di provare un failover.
+
+### Aggiungere un nodo secondario a un cluster HA degradato
+
+Se il nodo secondario è stato scollegato per manutenzione, o se ne è stato sostituito l'hardware, e nel frattempo il nodo primario ha continuato a servire il traffico da solo in un cluster degradato,
+questa è la procedura da seguire. Il firewall da inserire non ha mai fatto parte di questo cluster e non ha alcuna configurazione HA propria.
+
+Aggiungerlo non richiede un reset: la configurazione del nodo primario è ancora valida, e va creata soltanto l'associazione con il nuovo dispositivo.
+
+Preparare il nuovo firewall esattamente come per costruire un cluster da zero, seguendo [Setup and management](ha_setup_and_management): stessi nomi di interfaccia, stessi device e gli stessi indirizzi statici del nodo che sostituisce, sull'interfaccia HA e su ogni LAN aggiuntiva del cluster.
+
+Ripetere poi, dal nodo primario, tutti i passi della configurazione iniziale del cluster tranne `init-primary-node`. Cominciare dal controllo del nuovo nodo: il comando ne verifica l'indirizzamento, l'accesso SSH e le opzioni DHCP prima che venga scritto alcunché.
+
+    ns-ha-config check-backup-node <backup_node_ip> <lan_interface>
+    ns-ha-config init-backup-node <lan_interface>
+
+Eseguire poi di nuovo, con gli stessi valori usati alla prima configurazione del cluster, un comando per ogni LAN aggiuntiva e per ogni IP virtuale aggiuntivo:
+
+    ns-ha-config add-lan-interface <primary_node_ip> <backup_node_ip> <virtual_ip>
+    ns-ha-config add-vip <lan_interface> <virtual_ip>
+
+:::warning
+
+Le LAN aggiuntive e gli IP virtuali vanno aggiunti di nuovo anche se sul nodo primario non è cambiato nulla. Quei comandi sono l'unica cosa che crea le sezioni corrispondenti
+sul nodo secondario.
+
+Saltare questi comandi lascia un cluster apparentemente sano, con un `ns-ha-config status` corretto, ma le cui LAN aggiuntive restano senza IP virtuale dopo un failover.
+
+:::
+
+Infine verificare il risultato e provare un failover, controllando che **ogni** IP virtuale sia presente sul nodo secondario, non solo quello dell'interfaccia HA.
+
+### Reset della configurazione
+
+:::note
+
+Eseguire il reset del cluster quando si vuole smantellarlo e tornare a firewall indipendenti, oppure quando lo si sta ricostruendo con una struttura diversa: meno interfacce, altri IP virtuali.
+Le sezioni del cluster precedente sopravvivono sul nodo primario e nessun altro comando le rimuove.
+
+Il reset non serve per sostituire o reinserire un nodo secondario, vedere
+[Aggiungere un nodo secondario a un cluster HA degradato](#aggiungere-un-nodo-secondario-a-un-cluster-ha-degradato).
+
+:::
+
+Il comando di reset riporta la configurazione del cluster allo stato predefinito. Va eseguito localmente sul nodo primario e con il nodo secondario ancora collegato, in modo che il reset coinvolga anche quest'ultimo.Di norma, dopo il reset il nodo primario può continuare a funzionare normalmente, mentre il nodo secondario, non più utilizzato nel cluster, va scollegato e riportato alla configurazione di fabbrica per evitare conflitti.
+
+Il comando di reset:
+
+- Arresta e disabilita `keepalived` e `conntrackd`.
+- Rimuove i file di configurazione dell'HA.
+- Ripulisce la configurazione di `dropbear`, comprese le chiavi SSH.
+
+Alla fine, è necessario un riavvio per applicare le modifiche. Basta eseguire:
+
+    ns-ha-config reset
+    reboot
+
+Gli indirizzi delle interfacce non vengono modificati: entrambi i nodi mantengono i propri indirizzi IP e spariscono solo gli IP virtuali, perché sono
+gestiti da `keepalived`. Il nodo primario può essere riconfigurato immediatamente.
+
+:::warning
+
+L'IP virtuale non esiste finché il cluster non viene riconfigurato: nel frattempo i client che lo usano come gateway o server DNS perdono la connettività.
+
+:::
+
 ## Risoluzione dei problemi {#troubleshooting_ha-section}
 
 La risoluzione dei problemi della configurazione HA può essere impegnativa, soprattutto se il nodo secondario non è raggiungibile o il nodo primario non risponde come previsto.
@@ -173,17 +248,3 @@ Abilita la registrazione di debug di `keepalived` (sul primario):
 
 Quindi, cerca `Keepalived_vrrp` nel file `/var/log/messages`.
 
-### Ripristina la configurazione
-
-Il comando reset ripristina la configurazione del cluster al suo stato predefinito. Tipicamente, dopo il reset, il nodo primario può continuare a operare normalmente, mentre il nodo secondario, non più utilizzato nel cluster dovrebbe essere ripristinato al valore predefinito per evitare conflitti. Dopo il reset, rimane attiva solo l'interfaccia HA, quindi è necessario un riavvio per completare il processo. Il reset deve essere eseguito localmente sul nodo primario.
-
-Il comando reset:
-
-- Arresta e disabilita `keepalived` e `conntrackd`.
-- Rimuove i file di configurazione HA.
-- Pulisce la configurazione di `dropbear` incluse le chiavi SSH.
-
-Alla fine, è necessario un riavvio per applicare le modifiche. Basta eseguire:
-
-    ns-ha-config reset
-    reboot

i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/high-availability/ha_setup_and_management.md

@@ -227,6 +227,13 @@ Un IP virtuale (VIP) è un indirizzo IP aggiuntivo assegnato a un'interfaccia di
 
 Questo è utile per i servizi che richiedono più indirizzi IP sulla stessa interfaccia, come server virtuali o bilanciamento del carico.
 
+:::note
+
+Gli IP virtuali possono essere aggiunti solo alle interfacce LAN del cluster. Gli indirizzi pubblici aggiuntivi su una WAN si configurano come alias sul nodo primario e vengono replicati automaticamente, vedere
+[Interfacce WAN](#interfacce-wan).
+
+:::
+
 Utilizza il comando `ns-ha-config` per registrare l'IP virtuale nella configurazione del cluster HA.
 
 Gli IP virtuali devono essere impostati esplicitamente nel nodo primario. :