PVE-UPS — Manuale utente
+Un'appliance snella per lo spegnimento da UPS per Proxmox VE: monitora uno o + più UPS — via SNMP o tramite un server NUT — e, in caso di blackout, spegne + in modo ordinato gli host Proxmox assegnati, senza file di configurazione scritti + a mano da nessuna parte. Questo manuale è rivolto ad amministratori con mentalità + tecnica che sono nuovi al prodotto.
+1 Cos'è PVE-UPS?
+PVE-UPS sostituisce le classiche appliance di spegnimento UPS legate al produttore (come APC + PowerChute Network Shutdown) per ambienti Proxmox. Il software gira come un singolo + LXC unprivileged (~256 MB RAM) e non richiede altro che uno script di installazione.
+Funzionalità principali
+-
+
- Monitoraggio di uno o più UPS — con scheda di rete SNMP + (standard RFC 1628 o un MIB del produttore: APC PowerNet, CyberPower, + SNMP v1/v2c/v3, implementazione in puro Python) o tramite un server NUT, + che è il modo in cui si leggono gli UPS USB e seriali. +
- Spegnimento ordinato degli host tramite token API Proxmox — nessun accesso
+ root via SSH. I target possono essere nodi Proxmox VE (privilegio
+
Sys.PowerMgmt) o un Proxmox Backup Server + (Sys.PowerManagement), selezionabile per host.
+ - Mappatura host↔UPS con logica per host (AND/OR) per alimentatori + ridondanti o carico separato, con diagramma dell'alimentazione nella web UI. +
- Configurazione completa tramite procedura guidata web con pulsanti di test. +
- Web UI in inglese, tedesco e italiano — scelta automaticamente dalla lingua + del browser. +
- Fail-safe: perdere il contatto con l'UPS genera un allarme di default, + non spegne mai nulla. +
- Modalità dry-run per una messa in servizio senza rischi. +
- Stato REST/JSON in sola lettura per il monitoraggio (
/api/status, +/api/health).
+
2 Requisiti
+-
+
- Un host Proxmox VE su cui far girare l'LXC. Tipicamente uno degli host da + proteggere. Come target funzionano sia host standalone sia nodi di un cluster — ogni + host viene spento singolarmente tramite la propria API, e PVE-UPS non tocca né + l'HA manager né il quorum. +
- Uno o più UPS, raggiungibili in uno di due modi:
+
-
+
- con una scheda di rete SNMP che espone lo standard + RFC 1628 UPS MIB (indipendente dal produttore) o un MIB del produttore + supportato — APC PowerNet o CyberPower, che coprono anche le schede senza RFC 1628 (vedi + sezione 5), oppure +
- collegato via cavo USB o seriale a una macchina che esegue un
+ server NUT (
upsd) — vedi sezione 5.
+
+ - Connettività di rete tra l'appliance e la sorgente UPS (basta l'accesso in + lettura: UDP 161 per SNMP, TCP 3493 per NUT) e verso l'API dei target + protetti (HTTPS, porta 8006 per Proxmox VE, 8007 per Proxmox Backup Server). +
Oltre ai nodi Proxmox VE, si può spegnere anche un Proxmox Backup Server — + ogni voce host porta un tipo. I due differiscono solo in come vengono + indirizzati; tutto il resto (mappatura UPS, logica AND/OR, ordine, soglie) funziona + allo stesso modo per entrambi. Vedi sezione 4.
+/api/status e /api/health sono volutamente leggibili
+ senza login affinché il monitoraggio possa interrogarli — un motivo in più per cui
+ l'appliance non dovrebbe essere raggiungibile pubblicamente.
+ 3 Installazione e configurazione
+Installa direttamente dalla shell del nodo Proxmox (web UI → nodo →
+ >_ Shell, come root). Lo script scarica l'ultimo pacchetto di release
+ da GitHub, lo scompatta e crea l'LXC:
bash -c "$(curl -fsSL https://github.com/ffind-dev/pve-ups/releases/latest/download/install.sh)"
+# ad es. con un IP statico:
+curl -fsSL https://github.com/ffind-dev/pve-ups/releases/latest/download/install.sh | bash -s -- \
+ --ctid 950 --ip 10.0.0.50/24 --gateway 10.0.0.1 --hostname pve-usvTutte le opzioni sono facoltative; --help le elenca con i default
+ (come one-liner: … | bash -s -- --help).
| Opzione | Default | Significato |
|---|---|---|
--ctid <id> | 950 |
+ ID del nuovo container |
--hostname <name> | pve-usv |
+ Hostname del container |
--storage <name> | automatico | +Storage per il disco del container (content rootdir). Senza:
+ local-lvm, poi local-zfs, poi il primo altro
+ storage non-Ceph |
--template-storage <name> | local |
+ Storage su cui viene scaricato il template Debian 12 (content
+ vztmpl). Il default ripiega su un altro storage adatto; uno
+ esplicito viene rifiutato se non può contenere template |
--bridge <bridge> | vmbr0 |
+ Bridge di rete |
--ip <dhcp|indirizzo/cidr> | dhcp |
+ dhcp o un indirizzo statico come 10.0.0.50/24 |
--gateway <ip> | – | +Gateway di default, usato solo con --ip statico |
--memory <MB> | 256 |
+ RAM del container |
--disk <GB> | 4 |
+ Dimensione del disco del container |
--allow-ceph-storage | off | +Accetta uno --storage basato su Ceph — vedi
+ il guest proprio dell'appliance |
PVE-UPS è elencato anche su community-scripts.org (cerca “PVE-UPS”), una + raccolta mantenuta dalla community di script di supporto per Proxmox. Il one-liner + sopra resta il percorso di riferimento.
+Poi apri la web UI su http://<container-ip>:8080 e segui
+ la procedura guidata:
-
+
- Imposta la password dell'UI. +
- Aggiungi gli UPS (sorgente, indirizzo, credenziali — vedi sezione 5) e + verifica ciascuno con “Test UPS”. +
- Aggiungi gli host: scegli il tipo per ogni voce (Proxmox VE o Proxmox + Backup Server), inserisci il suo token API (vedi sezione 4) e usa “Test”. Definisci quali + UPS alimentano ogni host e con quale logica (AND/OR). +
- Imposta le soglie o mantieni i default. +
- Opzionalmente configura il webhook di notifica (HTTP POST verso un + sistema di ticket/chat/monitoraggio): scegli formato e livello, poi verificalo con + “Invia notifica di test” — vedi Notifiche webhook. +
4 Creare il token API
+Ogni voce host si autentica con un token API — revocabile, e sostituto + dell'accesso root via SSH. Quale token creare dipende dal tipo selezionato + per quella voce, perché Proxmox VE e Proxmox Backup Server usano schemi di token + e nomi di privilegio diversi:
+| Proxmox VE | Proxmox Backup Server | |
|---|---|---|
| Porta API | 8006 | 8007 |
| Privilegio | Sys.PowerMgmt |
+ Sys.PowerManagement |
| Concesso su | /nodes |
+ /system/status |
| Campo “Nodo” | il vero nome del nodo | +un'etichetta libera (PBS lo ignora) |
Proxmox VE
+Crea un utente dedicato con il solo privilegio di power-management e un token + API. Esegui una sola volta, nella shell di un qualsiasi nodo Proxmox:
+pveum user add ups@pve
+pveum role add UpsShutdown -privs "Sys.PowerMgmt"
+pveum acl modify /nodes -user ups@pve -role UpsShutdown
+pveum user token add ups@pve shutdown --privsep 0L'ultimo comando stampa il token ID (ups@pve!shutdown) e
+ il segreto. Inserisci entrambi nella procedura guidata e verifica con “Test”.
/etc/pve) e valgono quindi su
+ ogni nodo — inserisci lo stesso token ID e segreto per ogni nodo. Solo gli
+ host standalone che non condividono un cluster hanno bisogno ognuno di un proprio
+ utente e token.
+ Dai a ogni voce host il proprio URL API
+ (https://<ip-di-questo-nodo>:8006). L'API Proxmox farebbe da proxy
+ per una richiesta a un altro nodo, ma un nodo già spento non può fare da proxy
+ per quelli che devono ancora spegnersi.
/nodes/localhost/status), quindi la macchina che risponde è quella che
+ viene spenta. Proxmox gestisce questa forma localmente invece di cercare il nodo nel
+ cluster, che è esattamente ciò che vuoi mentre i nodi cadono e il quorum è
+ traballante. La conseguenza: un “Nodo” scritto male non può più deviare uno spegnimento —
+ ma due voci che condividono un URL sì, quindi PVE-UPS avvisa di questo sia mentre
+ modifichi sia nell'auto-test.
+ - — niente punti, quindi un
+ FQDN come pve01.example.com viene rifiutato — e maiuscole/minuscole
+ sono distinte, quindi PVE01 non è pve01. Dove le voci
+ condividono un URL API il nome torna nel percorso dello spegnimento, e una
+ discrepanza è riportata come errore anziché come avviso.
+ Proxmox Backup Server
+Esegui questo nella shell del Backup Server. Nota che l'ACL viene concessa + due volte — una all'utente, una al token:
+proxmox-backup-manager user create ups@pbs
+proxmox-backup-manager user generate-token ups@pbs shutdown
+proxmox-backup-manager acl update /system/status Admin --auth-id 'ups@pbs'
+proxmox-backup-manager acl update /system/status Admin --auth-id 'ups@pbs!shutdown'generate-token stampa il token ID
+ (ups@pbs!shutdown) e il segreto — il segreto viene mostrato una
+ sola volta e non può essere recuperato dopo. Inserisci l'URL API come
+ https://<pbs-ip>:8007, poi verifica con “Test”.
Tre dettagli differiscono da Proxmox VE e spiegano i comandi sopra:
+-
+
- Servono entrambe le voci. Su PBS i permessi di un token sono calcolati + dalle sue ACL e poi intersecati con quelli del suo utente, quindi un token + non può mai superare il suo utente. Concederne solo una delle due lascia il token + senza il privilegio. +
- Il ruolo è
Admin. PBS non ha un ruolo granulare di + power-management —Sys.PowerManagementè posseduto solo da +Admin. Concederlo su/system/statusinvece che su +/mantiene l'ambito il più stretto possibile per PBS.
+ - Il campo “Nodo” è solo un'etichetta. PBS ignora il nodo nel percorso API,
+ quindi lo spegnimento indirizza sempre
/nodes/localhost/status. Chiama la + voce come è leggibile sulla dashboard; nulla deve corrispondere all'hostname.
+
Admin, e PVE-UPS deve raggiungere l'API
+ PBS dall'ambiente che protegge. Questa combinazione allarga il percorso da un
+ host di virtualizzazione compromesso verso i backup — che sono esattamente ciò che
+ dovrebbe sopravvivere a una tale compromissione. Per ambienti di produzione
+ sconsigliamo quindi di collegare PBS alla stessa istanza PVE-UPS che gestisce
+ gli host PVE. Alternative: dai al Backup Server un suo percorso di spegnimento UPS
+ (una propria istanza PVE-UPS, raggiungibile solo da un segmento di management separato), o
+ lascialo superare i blackout brevi sull'autonomia del suo UPS.
+ 5 Sorgenti UPS
+Ogni voce UPS nella procedura guidata ha un selettore “Lettura via”. Le due + sorgenti si possono mescolare liberamente in una stessa istanza, e tutto ciò che viene + dopo — soglie, mappatura host, regole fail-safe — è identico per entrambe.
+ +SNMP (UPS con scheda di rete)
+Nell'interfaccia web della scheda di rete dell'UPS (di solito in Network → SNMPv1 + o SNMPv3), abilita l'accesso e concedi all'IP dell'appliance l'accesso in + lettura. Nulla viene mai scritto. Porta di default 161/UDP.
+ +Quale MIB viene letto
+Ogni UPS SNMP ha un'impostazione MIB. Decide quale insieme di oggetti viene + interrogato — i valori stessi, le soglie e tutto ciò che sta a valle sono gli stessi + in ogni caso.
+-
+
- Automatico (default, e la risposta giusta per quasi ogni dispositivo): viene + letto lo standard RFC 1628, e l'UPS passa a un MIB del produttore appena + risponde su quello. Il rilevamento non costa query extra, e un aggiornamento firmware + che aggiunge RFC 1628 in seguito viene recepito da solo. +
- RFC 1628 (standard): il MIB UPS indipendente dal produttore, nient'altro. +
- APC PowerNet: il MIB delle schede di gestione di rete APC/Schneider. +
- CyberPower: il CPS-MIB delle schede di rete CyberPower (famiglia RMCARD). + Viene letto un valore per richiesta — vedi sotto. +
Un MIB del produttore conta soprattutto per APC. Schneider supporta RFC 1628 solo sulle
+ Network Management Card 2 (AP9630/AP9631/AP9635) dal firmware
+ sumx/sy v5.1.7 in poi; le vecchie schede NMC1
+ (AP9617/AP9618/AP9619) parlano solo PowerNet e non sono leggibili attraverso lo
+ standard. Sulle schede che supportano entrambi, PowerNet resta comunque la sorgente
+ migliore: riporta l'autonomia residua in centesimi di secondo anziché in minuti interi, e
+ riporta un self-test come stato a sé — RFC 1628 non sa distinguere un
+ self-test da un blackout vero.
Le schede CyberPower per lo più implementano anch'esse RFC 1628, ma non tutte, + e alcuni firmware non rispondono a una richiesta di più valori insieme — non con + un errore, la richiesta va semplicemente in timeout — mentre ogni valore risponde se + interrogato da solo. Per questo il MIB CyberPower viene sempre letto un valore per + richiesta: qualche centinaio di millisecondi per polling su una rete locale, e una + scheda che smette di rispondere costa comunque un solo timeout, come prima.
+Imposta il MIB esplicitamente solo per forzarne uno, ad esempio per fissare un + dispositivo sullo standard mentre confronti le letture — o quando “Test UPS” riporta + che il polling regolare non ha avuto risposta anche se i valori rispondono uno alla + volta. Allora scegli CyberPower: Automatico parte sempre con una + richiesta di più valori, a cui una scheda del genere non risponde mai.
+ +Server NUT (UPS USB e seriali)
+Un UPS senza scheda di rete si raggiunge tramite
+ Network UPS
+ Tools: la macchina a cui l'UPS è collegato esegue upsd, e
+ PVE-UPS legge da esso su TCP 3493. Molto spesso un server del genere esiste già —
+ i NAS Synology e QNAP hanno una casella “server UPS”, così come TrueNAS e
+ OPNsense; altrimenti va bene un Raspberry Pi o un host Proxmox con il pacchetto
+ nut-server.
Servono tre campi: l'host che esegue upsd, il nome UPS come
+ configurato nel suo ups.conf (upsc -l <host> elenca i
+ nomi disponibili), e opzionalmente nome utente e password — un upsd standard
+ permette di leggere le variabili senza né l'uno né l'altra.
NAS come server NUT (QNAP, Synology)
+Entrambi i produttori forniscono una configurazione propria e fissa — i valori non + si possono scegliere liberamente:
+| NAS | Nome UPS | Utente | Password |
|---|---|---|---|
| QNAP | qnapups | admin | 123456 |
| Synology | ups | ups | nessuna |
Su entrambi il server UPS di rete va abilitato e l'indirizzo IP dell'appliance + deve essere nella lista dei dispositivi consentiti — altrimenti il NAS + semplicemente non risponde, che è di gran lunga la causa più comune di un test + fallito. L'impostazione sta nella configurazione UPS (QNAP: pannello di controllo, + dispositivo esterno; Synology: pannello di controllo, hardware e alimentazione); la + dicitura esatta varia tra le versioni di QTS e DSM.
+upsmon. NUT
+ fa da driver del dispositivo; le soglie, la policy degli host e la decisione di
+ spegnimento restano in questa appliance. Non c'è nulla da configurare sugli host
+ protetti.
+ Leggere il risultato del test
+Sotto la riga di risultato, “Test UPS” offre Dettagli per oggetto — ogni + oggetto interrogato singolarmente, con il suo valore o il motivo per cui manca. Si apre + da solo ogni volta che qualcosa non va, e separa i casi che altrimenti + sembrano identici:
+-
+
- Nulla risponde (ogni riga un errore): indirizzo, porta o credenziali
+ sbagliati, o un firewall blocca UDP 161 (SNMP) / TCP 3493 (NUT). Per NUT
+ controlla anche che la direttiva
LISTENdi upsd copra questo host — di + default ascolta solo su localhost.
+ - Alcuni oggetti rispondono, altri dicono
noSuchObject/ +noSuchInstance(SNMP) o “not provided by this driver” + (NUT): il dispositivo semplicemente non pubblica quei valori. Quando riguarda un + trigger, il test lo dice a parole sopra la tabella — ad esempio un driver + senzabattery.runtimerende la soglia “Autonomia sotto (min)” + permanentemente inefficace. Usa invece il timer “A batteria per più di (s)”: gira + sull'orologio dell'appliance e funziona sempre.
+ noSuchNamesotto SNMPv1: l'oggetto manca e + v1 interrompe una query multi-oggetto appena un oggetto è assente — il polling + regolare fallisce allora completamente anche se gli altri valori sono leggibili. + Passa l'UPS a v2c se lo supporta.
+ - Il polling regolare non ha risposta, ma ogni oggetto risponde uno alla + volta (SNMP): la scheda non gestisce una richiesta di più valori insieme — alcuni + firmware CyberPower la lasciano semplicemente scadere. Il riepilogo lo dice; imposta il + MIB su CyberPower, che viene letto un valore per richiesta. +
- Ogni oggetto RFC 1628 mancante, ogni oggetto del produttore che + risponde: normale su una scheda APC senza supporto RFC 1628. In modalità + Automatico entrambi i MIB sono elencati, quello effettivamente in uso viene + per primo, e la riga sopra la tabella lo nomina. Nulla + da cambiare — gli oggetti contati e gli avvisi sui trigger si riferiscono sempre al + MIB in uso, non a quello perdente. +
- “stale data” (NUT): upsd risponde, ma il suo driver ha perso il contatto + con l'UPS. I valori che ancora fornisce sono vecchi, quindi PVE-UPS tratta l'UPS + come irraggiungibile — un allarme, mai uno spegnimento. Riavvia il driver NUT su + quella macchina. +
- L'oggetto della sorgente di alimentazione manca o riporta “unknown”: il
+ dispositivo risponde e altri valori arrivano, ma l'unico oggetto che dice se gira su
+ rete o a batteria (
upsOutputSource, su APC +upsBasicOutputStatus) no. Da ciò non si può concludere nulla, + quindi PVE-UPS tratta l'UPS come irraggiungibile — un allarme, mai uno spegnimento, e un + conto alla rovescia a batteria in corso continua. Controlla l'impostazione MIB; se il + dispositivo davvero non lo implementa, non può essere usato come sorgente di + spegnimento.
+ ups.statusnon nomina néOLnéOB+ (NUT): lo stesso caso dal lato NUT. La variabile c'è, ma porta solo + qualcosa comeCHRG,ALARMoRB— o è + vuota — e nulla di tutto ciò dice da dove arriva l'alimentazione. Trattato esattamente + come sopra: irraggiungibile, un allarme, mai uno spegnimento, e un conto alla rovescia in + corso continua. Di solito un quirk del driver; controlla il driver sul server NUT.
+
6 Come funziona e logica
+L'engine interroga tutti gli UPS in parallelo e valuta ogni UPS + indipendentemente. Ogni polling porta la propria scadenza, derivata dalle + impostazioni di timeout e tentativi di quel dispositivo, quindi un server che accetta + una connessione e poi tace non può bloccare il conto alla rovescia degli altri. Per UPS + c'è una semplice sequenza di stati:
++ ONLINE su rete → + ON_BATTERY blackout, UPS a batteria → + attivato appena una soglia scatta +
+Quale host si spegne?
+Lo decide la mappatura di ogni host verso i suoi UPS e la sua logica:
+-
+
- AND (
ups_policy = all, default): l'host si spegne solo + quando tutti gli UPS assegnati hanno attivato il trigger — esattamente il + comportamento per server con alimentatori ridondanti (un UPS per + alimentazione). Finché un UPS continua a erogare corrente, l'host resta acceso.
+ - OR (
ups_policy = any): l'host si spegne appena + uno degli UPS assegnati attiva il trigger — per carico separato, non + ridondante.
+
Più host dovuti vengono spenti a stadi, seguendo il campo “Ordine” —
+ crescente, quindi 0 parte per primo: tutto ciò che condivide un numero riceve il
+ comando contemporaneamente, e lo stadio successivo parte solo quando quello è
+ finito. L'host su cui gira l'appliance stessa (this_host) forma sempre
+ l'ultimo stadio indipendentemente dal numero, così può ancora spegnere gli
+ altri. Suggerimento: collega l'host dell'appliance a tutti gli UPS così diventa
+ dovuto per ultimo in modo affidabile. La procedura guidata mostra la sequenza risultante
+ in tempo reale sotto la lista host.
Ogni comando porta anche una scadenza rigida (“Timeout spegnimento host”). + Insieme significano che una macchina che smette di rispondere non può bloccare i suoi + compagni di stadio, gli stadi successivi, o il conto alla rovescia della batteria. Usa + il campo ordine quando un target deve davvero spegnersi prima di un altro — altrimenti + lasciarli uguali è sia più rapido sia più sicuro.
+Se un UPS richiesto si riprende (la rete torna), uno spegnimento non ancora + eseguito viene annullato e lo stato si reimposta.
+Uno spegnimento che è stato inviato resta bloccato — una macchina in fase di + spegnimento non va comandata due volte. Quel blocco viene rilasciato solo quando + ogni UPS è stato raggiungibile e su rete per il tempo impostato in “Riarmo dopo + ritorno rete (min)” (default 5, vuoto = mai). Solo allora l'appliance è pronta per il + blackout successivo: mentre è bloccata, un secondo blackout troverebbe ogni host già + marcato come attivato, e anche l'auto-test pianificato e “Ripristina cluster” stanno + fermi. Il tempo di attesa esiste perché la rete che torna non è la rete che resta — una + rete che cade due volte in un minuto non deve riarmare in mezzo. Un UPS + irraggiungibile non conta mai come “rete tornata”. Il ripristino di un cluster + preparato resta comunque manuale; il riarmo rende solo di nuovo disponibile quel + pulsante, e l'evento lo dice quando un cluster porta ancora la preparazione. Il + pulsante “Reimposta stato” fa la stessa cosa immediatamente, in qualsiasi momento.
+ +Cluster Proxmox VE Beta
+disarm-ha, arrivato con
+ la 9.2. Su una release più vecchia HA non viene disarmato, e dove HA gestisce i guest
+ non vengono nemmeno arrestati a livello cluster; i flag di manutenzione Ceph vengono
+ comunque impostati. PVE-UPS lo rileva dall'API stessa, mai da un numero di versione,
+ quindi funziona anche con un backport.
+ Questa sezione copre un cluster Proxmox VE semplice. Se il cluster esegue + anche Ceph sui propri nodi, leggi poi + Cluster iperconvergenti (Ceph) — quella parte è un + intervento considerevolmente più grande, con privilegi propri.
+Spunta “Membro del cluster” nel riquadro Cluster Proxmox VE della scheda host — + su ogni nodo del cluster. I membri sono raggruppati automaticamente dal nome + del cluster letto dall'API, quindi non serve un secondo token né una sezione di + configurazione extra, e la preparazione gira esattamente una volta per cluster, prima + che il primo nodo si spenga. Ciò che la spunta decide è chi conta come + membro: un nodo senza viene preparato attorno anziché dentro, non viene mai + trascinato da “spegni l'intero cluster come un'unità”, e i suoi interruttori non hanno + voce su ciò che fa il cluster. + Da ciò che invece non esime il nodo è la preparazione stessa, che per natura è + a livello cluster: HA viene disarmato per l'intero cluster e, con l'arresto guest + o Ceph, ogni guest al suo interno viene arrestato — inclusi quelli che girano lì. + Lascia il riquadro non spuntato su un nodo di un cluster e quella macchina resta + accesa senza HA e senza i suoi guest. L'auto-test pianificato nomina un nodo del + genere, così la discrepanza viene scoperta prima di un blackout anziché durante.
+Gli interruttori di questo riquadro agiscono tutti sull'intero cluster — flag + di manutenzione Ceph, stato di arm dell'HA manager, l'arresto guest, e se il cluster si + spegne come un'unità — anche se si modificano per scheda host. Quindi imposta + ciascuno allo stesso modo su ogni nodo di uno stesso cluster. Dove non concordano, + PVE-UPS vale “almeno un nodo l'ha chiesto” (saltare un passo richiesto può costare + lo storage; eseguirne uno che nessuno ha chiesto costa un flag di manutenzione) e scrive + un avviso nominando entrambe le parti, così la discrepanza emerge al prossimo + auto-test anziché durante un blackout.
+Ciò che fa su un cluster semplice è l'unica cosa che uno spegnimento per nodo non + può fare:
+-
+
- Disarmo HA — senza, l'HA manager ripristina servizi su nodi che
+ si stanno spegnendo a loro volta. PVE-UPS disarma con
+
resource-mode=ignore; i guest poi escono dal tracciamento HA e +pve-guestsli spegne nel loro ordine configurato. Questo + non è configurabile, e volutamente: sottofreezei guest + restano gestiti da HA,pve-guestsli salta e l'LRM disarmato non li + ferma più — verrebbero uccisi dallo spegnimento fisico.
+
Il passo è verificato, non presunto: il disarmo viene interrogato finché lo
+ stato HA riporta davvero disarmed. Gira sotto un timeout rigido, perché
+ avviene mentre la batteria si scarica.
Quel timeout (“Timeout disarmo HA / flag Ceph”, in Trigger) è il tempo
+ che il disarmo effettivamente riceve, non solo un freno d'emergenza esterno: il
+ budget viene passato di passo in passo, quindi alzarlo compra davvero più pazienza.
+ Il default è 60 s. Il disarmo è la parte lenta, perché lo stack HA lavora a
+ giri di dieci secondi e ogni nodo deve rilasciare il suo watchdog prima che lo stato
+ passi da disarming a disarmed. Sotto circa mezzo minuto di
+ solito non può essere confermato. Ogni secondo qui è uno che lo spegnimento non ha,
+ quindi alzalo consapevolmente — i nodi di quel cluster lo aspettano. Se il budget
+ finisce, l'evento nomina lo stato a cui si è fermato (“still disarming” significa dagli
+ più tempo; uno stack mai mosso è un problema diverso) e ciò che era già stato fatto.
+ Un cluster già disarmato — un secondo blackout prima di averlo ripristinato —
+ viene lasciato stare anziché disarmato di nuovo. In modalità dry-run viene solo
+ registrato; nulla viene cambiato.
La preparazione dice quando parte, non solo come è finita: un evento nomina + cosa sta per fare, quanti nodi del cluster hanno attivato il trigger, e quanto a lungo + i nodi possono aspettarla. Tra quella riga e il risultato, lo spegnimento dei nodi + di quel cluster sta aspettando di proposito.
+Se la preparazione fallisce, lo spegnimento continua di default. È + l'impostazione più sicura: un disarmo fallito lascia l'HA manager armato, e un HA + manager armato ferma i guest da solo — più rumoroso, ma le macchine si spengono + comunque. L'opposto (“Annulla lo spegnimento se la preparazione del cluster fallisce”, + in Trigger) significa che una preparazione fallita lascia l'intero cluster + acceso finché la batteria è vuota.
+ +Arrestare prima tutti i guest, senza Ceph (opzionale)
+Lasciati a sé, i guest di un cluster semplice vengono fermati dai loro nodi man
+ mano che ciascuno si spegne — in ordine startup inverso, gruppo per gruppo,
+ con il ritardo di ogni gruppo. Con molti gruppi ordinati può durare più della batteria.
+ “Arresta prima tutti i guest a livello cluster” (disattivato di default) lo
+ sostituisce con il passo che usa la procedura Ceph: prima che il primo nodo si spenga,
+ a ogni VM e container del cluster tranne questa appliance viene chiesto di spegnersi —
+ tutti insieme, in parallelo — e il risultato viene verificato rileggendo la lista dei
+ guest.
-
+
- L'ordine di avvio viene ignorato, di proposito: il punto è finire prima + della batteria. Una dipendenza tra un'applicazione e il suo database non viene + rispettata. +
- Ha il suo budget proprio, “Timeout spegnimento guest”, e i guest ancora in + esecuzione dopo “Arresto forzato guest dopo” vengono fermati forzatamente — vedi + lo spegnimento dei guest sotto; quei dettagli valgono + invariati. +
- Dove HA gestisce i guest, HA deve essere disarmato prima (Proxmox VE 9.2+ + e l'interruttore HA), o l'HA manager li riavvierebbe alla stessa velocità con cui si + fermano. Se non può esserlo, il passo viene saltato con un avviso e i nodi fermano i + propri guest come prima. +
- Il guest proprio di questa appliance deve essere selezionato — vedi + il guest proprio dell'appliance. Finché non lo è, + nessun guest viene arrestato. +
- Richiede
VM.AuditeVM.PowerMgmt(tabella sotto).
+
Con l'opzione Ceph l'arresto guest è sempre parte della procedura — la scheda + host lo mostra allora spuntato e bloccato, e togliere la spunta a Ceph ripristina + quello che il riquadro diceva prima.
+ +Il cluster si spegne come un'unità
+La preparazione è a livello cluster per natura — disarma HA per l'intero cluster, + e con l'arresto guest (o l'opzione Ceph) ferma ogni guest al suo interno. Lo + spegnimento stesso, però, è per host: un nodo è dovuto quando i suoi UPS lo + dicono. Le due cose non devono per forza concordare, e quando non lo fanno il risultato + è un cluster lasciato a metà.
+È a questo che serve “Spegni l'intero cluster come un'unità” (attivo di
+ default): appena un nodo del cluster è dovuto, ogni suo nodo viene spento — inclusi
+ quelli il cui UPS non ha attivato il trigger. Vanno nel solito ordine, con
+ l'host dell'appliance per ultimo, e il registro eventi nomina perché ciascuno è stato
+ trascinato.
Disattivalo solo per un cluster semplice dove preferisci che HA sposti i guest + di un singolo nodo guasto sugli altri; lì uno spegnimento parziale è un buon risultato. + Con l'arresto guest dovrebbe restare attivo, o i nodi che restano accesi hanno perso i + loro guest per nulla; con Ceph deve — vedi + la sezione successiva per come appare davvero un cluster + iperconvergente spento a metà.
+Ogni nodo ha bisogno della propria voce host, con il proprio URL API. Lo + spegnimento raggiunge il nodo dietro l'URL API di ogni voce (vedi + sezione 4.1), quindi un nodo senza voce è un nodo che nessuno + spegne, qualsiasi cosa dicano i nomi — ed è anche un nodo che la regola “come + un'unità” non può trascinare. L'auto-test confronta quindi i nomi dei nodi del + cluster con le tue voci host e avvisa di ogni nodo che nessuno spegnerebbe, nominando + entrambe le liste. Dove la differenza è solo maiuscole/minuscole o un suffisso di + dominio, nomina il nodo probabilmente inteso; una voce semplicemente disattivata viene + riportata come disabilitata anziché come mal nominata.
+ +Privilegi per un cluster semplice
+Concedi solo ciò che hai attivato: ogni spunta porta il proprio privilegio, e una + spunta lasciata spenta non ti costa nulla. La tabella si legge cumulativamente, dalla + configurazione base della sezione 4 in giù. La parte Ceph ha + una tabella propria.
+| Cosa è spuntato | Serve in più | Percorso ACL |
|---|---|---|
| nulla (spegnimento semplice) | Sys.PowerMgmt | /nodes |
| Membro del cluster | Sys.Audit | / |
| + Disarma l'HA manager | Sys.Console | / |
| + Arresta prima tutti i guest a livello cluster | VM.Audit, VM.PowerMgmt | / (conta anche su /vms) |
Scegli la riga che corrisponde alle tue spunte ed eseguila una volta per
+ datacenter, nella shell di un qualsiasi nodo. Sys.PowerMgmt non compare
+ qui di proposito — è già su /nodes dalla configurazione base, e non c'è
+ motivo di allargarlo all'intero datacenter:
# Membro del cluster, senza sotto-opzioni — controlli di stato in sola lettura:
+pveum role add UpsCluster -privs "Sys.Audit"
+
+# ... più disarmo HA (concede accesso shell, vedi l'avviso sotto):
+pveum role add UpsCluster -privs "Sys.Audit Sys.Console"
+
+# ... più l'arresto guest a livello cluster:
+pveum role add UpsCluster -privs "Sys.Audit Sys.Console VM.Audit VM.PowerMgmt"Poi collega il ruolo — entrambe le righe, vedi la nota sulla + separazione dei privilegi sotto:
+pveum acl modify / -user ups@pve -role UpsCluster
+pveum acl modify / -token 'ups@pve!shutdown' -role UpsClusterL'auto-test segue la stessa regola: chiede un privilegio solo dove la
+ funzionalità è attiva e questo cluster può effettivamente farla. A una release
+ senza disarm-ha non viene mai chiesto Sys.Console — quindi un
+ avviso su un privilegio mancante significa sempre qualcosa di cui hai davvero
+ bisogno.
Anche il pulsante “Test” sulla scheda host verifica questi privilegi,
+ appena l'opzione cluster è spuntata: nomina ognuno di quelli mancanti, riporta il
+ cluster trovato (nome, numero di nodi, stato Ceph e arm di HA), e lo dice se il nodo
+ risulta non essere affatto membro di un cluster. Un privilegio cluster mancante è
+ riportato come avviso, non come errore — la connessione stessa funziona comunque.
+ Ogni nome viene con ciò che compra (“Sys.Console (disarmo HA)”), così la
+ decisione se concederlo non richiede questa pagina aperta. Sotto, un pannello
+ dettagli elenca ogni query con il suo esito (si apre da solo quando qualcosa non
+ va), così si vede cosa ogni endpoint ha effettivamente risposto anziché solo la riga
+ di riepilogo. Una query che serve solo a un'opzione non spuntata — la lista guest
+ senza l'arresto guest, ad esempio — appare come “not readable (not needed)” e
+ lascia il pannello chiuso.
Sys.Console concede di fatto accesso shell ai nodi.
+ Per questo il disarmo HA è un interruttore a sé: se non vuoi concederlo,
+ lascia l'interruttore spento e usa la riga Sys.Audit sopra.
+ Nota anche che i token API hanno la separazione dei privilegi attiva di
+ default e hanno bisogno di una voce ACL propria — i diritti dell'utente non
+ bastano, ed è per questo che i due comandi acl modify sopra sono
+ entrambi necessari.
+ disarm-ha.
+ Imposta invece l'opzione datacenter shutdown_policy=freeze; il default
+ conditional ripristina i servizi HA su nodi che si stanno spegnendo,
+ e migrate è pure peggio, perché l'LRM allora ritarda lo
+ spegnimento finché tutto non è migrato via. L'auto-test avvisa di entrambi.
+ Dopo, il cluster resta preparato. Non c'è riarmo automatico: + riportare su HA mentre i nodi stanno ancora facendo boot è una decisione da valutare. + L'auto-test continua ad avvisare che HA è disarmato (e che i flag sono impostati, + dove lo erano), e la dashboard mostra un pulsante “Ripristina cluster” — riarma + HA e rimuove i flag, ciascuno verificato, e compare solo finché c'è effettivamente + qualcosa da annullare. Dato che l'appliance si spegne per ultima e torna con gli + altri, ispeziona i cluster una volta all'avvio, così i residui sono subito + sulla dashboard anziché al prossimo auto-test pianificato. Il pulsante è nascosto — e + l'API rifiuta la richiesta — mentre uno spegnimento è in corso: armare HA lì + annullerebbe la preparazione nell'unico momento in cui sta facendo il suo lavoro.
+Su un cluster semplice, i singoli guest non vengono mai toccati da
+ PVE-UPS: a uno spegnimento vengono comunque fermati nel loro ordine configurato —
+ dall'LRM mentre HA è armato, e da pve-guests una volta disarmato — e il
+ problema che il disarmo HA risolve è puramente il ripristino su altri nodi
+ dopo. Solo l'arresto guest cambia questo — spuntato da solo, o come parte
+ dell'opzione Ceph.
Cluster iperconvergenti (Ceph) Beta
+Vale tutto ciò che dice la sezione precedente; questo le + aggiunge due passi. L'ordine è quello in cui girano, ed è portante — gli + interruttori sulla scheda host sono elencati nello stesso ordine esattamente per + questo motivo:
+-
+
- Disarmo HA — deve venire per primo, o l'HA manager riavvia ogni guest + che il passo 2 ferma. +
- Tutti i guest vengono arrestati, a livello cluster — ogni VM e container + tranne questa appliance stessa. +
- Flag di manutenzione Ceph — vengono impostati
noout, +nobackfill,norecoverenorebalancecosì Ceph + non inizia il healing mentre gli OSD spariscono uno a uno. Equivalente a +ceph osd set nooute simili.
+
I passi 2 e 3 sono un'unica opzione, ed è disattivata di default: molti + cluster girano su replicazione ZFS o NFS/iSCSI condiviso, e questa è l'unica parte che + scrive in un layer di storage. Su un cluster senza Ceph viene saltata anziché tentata + e riportata come fallimento, e i suoi privilegi non sono richiesti. Il passo 2 esiste + anche da solo, per cluster senza Ceph (vedi sopra), + ma con Ceph non si può disattivare: lì non è un'opzione ma il primo passo della + procedura ufficiale, e una spunta la cui assenza blocca il cluster durante un blackout + sarebbe una trappola. La scheda host lo mostra spuntato e bloccato mentre Ceph è + attivo.
+I flag sono verificati, non presunti: l'aggiornamento bulk è asincrono + (restituisce solo un worker id), quindi vengono riletti — con ripiego + sull'impostarli singolarmente.
+Perché i guest devono fermarsi prima
+Questa è la parte in cui uno spegnimento per nodo sbaglia. Lasciato a sé, ogni
+ nodo ferma i propri guest mentre si spegne — che suona ordinato e poi si blocca. Con
+ il solito size=3/min_size=2, il pool sta bene dopo la partenza del primo
+ nodo, ma una volta spariti gli OSD del secondo scende sotto min_size. I
+ guest ancora in esecuzione sul nodo sopravvissuto ora si bloccano sulla IO: il loro
+ spegnimento non finisce mai, quindi quel nodo non si spegne mai, e la batteria si
+ esaurisce con il cluster spento a metà.
Proxmox documenta lo stesso ordine (“Shutdown Proxmox VE + Ceph HCI cluster”): + ferma prima tutti i client Ceph, poi imposta i flag OSD, poi spegni i nodi. + PVE-UPS lo segue. A ogni guest in esecuzione viene chiesto di spegnersi insieme — fino a + otto richieste in volo, perché chiederlo a quaranta guest uno dopo l'altro spenderebbe + un connect timeout su ciascuno — e il risultato è verificato rileggendo la + lista guest del cluster, mai dedotto dalla risposta dell'API.
+Due timeout in Trigger governano questo, e sono separati di + proposito:
+-
+
- “Timeout spegnimento guest” (default 300 s) — il budget per + fermare i guest. Scala con quanti ne hai e quanto ci mettono; + il budget HA/Ceph accanto è misurato in giri HA di dieci secondi e varia + a malapena. Un unico numero non potrebbe servire entrambi, e fonderli farebbe + mangiare ai guest il tempo del disarmo. +
- “Arresto forzato guest dopo” (default 120 s) — quando un guest + che ignora la richiesta viene fermato forzatamente. Il valore viene passato anche a + Proxmox come timeout proprio della chiamata di spegnimento, quindi l'arresto avviene + comunque se questa appliance perde la rete subito dopo aver chiesto. Lascialo vuoto + per non forzare mai: un guest bloccato fa allora fallire la preparazione e viene + nominato nel registro eventi. +
Guarda il totale. Tra lo scatto del trigger e l'ultimo nodo a cui viene detto di + spegnersi, il caso peggiore è il budget HA/Ceph più il budget guest più il timeout + di spegnimento per nodo — con i default, 420 s. La pagina impostazioni mostra + quel numero, e l'auto-test avvisa quando il trigger “autonomia stimata sotto” scatta + più tardi di quanto la sequenza richieda. Avvisa soltanto; non corregge mai un + trigger al posto tuo.
+Ordine dei nodi: Proxmox consiglia di spegnere prima i nodi senza + monitor Ceph. PVE-UPS legge il monmap e ti dice quando i tuoi valori “ordine” lo + contraddicono, nel test host e nell'auto-test — ma non li riordina mai da solo. + Il tuo ordine è configurazione esplicita, e sovrascriverlo silenziosamente al momento + del blackout renderebbe bugiarda la sequenza mostrata sulla dashboard.
+Non gestito: i guest vengono fermati in parallelo, non nel loro
+ ordine startup, quindi una dipendenza tra un'applicazione e il suo
+ database non viene rispettata. L'obiettivo qui è fermare la IO rapidamente, e la
+ batteria è il motivo.
Il guest proprio di questa appliance
+“Arresta tutti i guest” non deve includere l'appliance che arresta. In + Trigger → Questa appliance, scegli dalla lista la VM o il container in + cui gira PVE-UPS. È una lista e non un campo di testo di proposito: un id sbagliato + significa che questa appliance spegne sé stessa nel mezzo di un blackout. Se + gira davvero altrove — Docker su un NAS, bare metal, un altro cluster — scegli “non è + un guest di questo cluster”.
+La scelta fa due cose. Marca l'unico guest che non viene mai arrestato, e + imposta “Questo host” sulla scheda host del nodo su cui quel guest gira, così + quel nodo si spegne per ultimo. Quella spunta appare allora come presa dalla selezione + anziché mantenuta due volte; senza una scelta resta un interruttore manuale, come su + un host standalone. Se l'appliance viene poi migrata su un altro nodo, l'auto-test lo + dice.
+Finché nulla è selezionato e “non è un guest di questo cluster” non è impostato, + i guest non vengono arrestati affatto. Il registro eventi lo dice ad alta voce e + lo spegnimento continua senza quel passo — che è esattamente ciò che facevano le + release precedenti. Rifiutare è l'unica risposta sicura qui: l'alternativa è + indovinare, e un'ipotesi sbagliata spegne la macchina che sta eseguendo lo + spegnimento.
+min_size, il suo stesso
+ disco smette di rispondere e non può più spegnere nulla — a metà del
+ blackout. Usa local-lvm, local-zfs o uno storage directory.
+ install.sh lo impone: gli storage su Ceph vengono saltati quando ne
+ viene scelto uno automaticamente e rifiutati quando nominati con
+ --storage, a meno che non passi --allow-ceph-storage. A
+ runtime il test host, l'auto-test e la dashboard lo dicono tutti se l'appliance è
+ comunque su Ceph.
+ Privilegi per la parte Ceph
+In aggiunta ai privilegi del cluster semplice:
+| Cosa è spuntato | Serve in più | Percorso ACL |
|---|---|---|
| Prepara il cluster Ceph | Sys.Modify, VM.Audit, VM.PowerMgmt | / (quelli VM contano anche su /vms) |
| opzionale, per una diagnosi migliore | Datastore.Audit | / o /storage |
# Parte Ceph senza disarmo HA:
+pveum role add UpsCluster -privs "Sys.Audit Sys.Modify VM.Audit VM.PowerMgmt"
+
+# Tutto, incluso il controllo storage opzionale:
+pveum role add UpsCluster -privs "Sys.Audit Sys.Console Sys.Modify VM.Audit VM.PowerMgmt Datastore.Audit"Collega il ruolo con gli stessi due comandi acl modify di sopra. A un
+ cluster senza Ceph non viene mai chiesto Sys.Modify, e
+ VM.Audit o VM.PowerMgmt solo con l'arresto guest
+ spuntato. Datastore.Audit è
+ l'eccezione che conferma la regola: compra solo il controllo se questa appliance
+ sta su Ceph, quindi la sua assenza viene menzionata discretamente e mai riportata come
+ privilegio mancante.
VM.Audit conta più di quanto sembri.
+ /cluster/resources filtra per privilegio invece di rifiutare: un token
+ senza VM.Audit riceve una risposta perfettamente riuscita con una lista
+ guest vuota. PVE-UPS quindi non legge mai “vuota” come “nessun guest da
+ fermare” a meno che il token non dimostri di avere il privilegio — altrimenti
+ riporterebbe una preparazione riuscita mentre quaranta guest continuano a scrivere
+ su Ceph.
+ “Ripristina cluster” non riavvia i guest — tornano
+ tramite la loro impostazione onboot quando i nodi si accendono.
7 Fail-safe e casi limite
+Principio guida: una connessione SNMP persa non è un blackout confermato — + l'UPS può essere solo momentaneamente non reattivo, o uno switch in mezzo è giù. Di + default una perdita di comunicazione genera quindi solo un allarme, nessuno + spegnimento. Due impostazioni opzionali lo raffinano:
+-
+
- Continua lo spegnimento alla perdita (default attivo): se il contatto + con l'UPS si perde dopo che il funzionamento a batteria era già confermato, + un conto alla rovescia a batteria avviato continua sull'orologio locale e scatta alla + scadenza. Solo questo trigger basato sul tempo sopravvive allo stato “cieco” + (autonomia e carica sono allora illeggibili). Se un trigger (es. batteria scarica o + la soglia di carica) era già scattato prima che la connessione cadesse, resta + bloccato e non viene degradato al conto alla rovescia. Sia il conto alla rovescia + sia lo stato attivato sopravvivono anche a un riavvio del servizio: sono + persistiti su disco e ripristinati all'avvio (fino a 24 h di età). +
- Spegnimento dopo X minuti di pura perdita (default spento): tratta una
+ pura perdita di comunicazione (senza funzionamento a batteria confermato in
+ precedenza) come blackout dopo X minuti. Un opt-in deliberato per ambienti dove una
+ perdita di contatto prolungata conta come critica. Scatta solo sul silenzio:
+ un dispositivo che risponde ma la cui risposta non è utilizzabile — nessuna
+ sorgente di alimentazione utilizzabile, nessuno degli oggetti del MIB selezionato,
+ un
ups.statusche non nomina néOLnéOB, o + un server NUT che rispondeERR DATA-STALE, +DRIVER-NOT-CONNECTED,ACCESS-DENIEDo +UNKNOWN-UPS— viene trattato come irraggiungibile per ogni altro + scopo, ma mai come perdita di comunicazione. La + connessione c'è chiaramente, quindi questo trigger ne resta fuori; l'allarme dice + quale dei due casi è. Lo stesso vale per una voce non interrogabile affatto + (una scheda UPS salvata senza indirizzo, ad es. da un import di backup): non ha mai + inviato un pacchetto, quindi non ha prodotto prove sull'alimentazione, e + resta ciò che è altrove — un allarme e un rifiuto di spegnere gli host + che alimenta, non un ordine di farlo.
+
Panoramica dei casi
+| Situazione | Comportamento |
|---|---|
| Su rete, tutto ok | nulla (mostra “Su rete elettrica”) |
| A batteria, un trigger scatta | spegnimento (host a stadi per ordine, host proprio ultimo) |
| Contatto perso mentre è su rete | solo allarme, nessuno spegnimento |
| Contatto perso durante un conto alla rovescia a batteria | il countdown continua, spegnimento alla scadenza |
| Contatto perso dopo un trigger già scattato | il trigger resta bloccato (nessun downgrade) |
| Pura perdita di contatto con l'opt-in attivo | spegnimento alla scadenza della soglia |
| Server NUT risponde con dati obsoleti | conta come irraggiungibile (allarme), mai come “su rete” |
| L'UPS risponde ma non riporta una sorgente utilizzabile | conta come irraggiungibile (allarme), mai come “su rete” |
| Dry-run attivo | il trigger viene rilevato + registrato, nulla viene spento |
| La rete torna | lo stato si reimposta; uno spegnimento già inviato + viene rilasciato dopo “Riarmo dopo ritorno rete” |
8 Trigger e soglie
+Una condizione soddisfatta basta. Tutti i valori si possono cambiare nella + procedura guidata (campo vuoto = condizione disattivata); le soglie sono impostate + globalmente e si possono sovrascrivere per UPS.
+Come viene misurato “a batteria per più di”. PVE-UPS misura il + blackout sul proprio orologio, dal polling in cui ha visto per la prima volta l'UPS + passare a batteria. Deliberatamente non usa il contatore di tempo trascorso che + l'UPS riporta: lo standard definisce quel valore solo mentre il dispositivo è a + batteria, e una scheda che conserva il dato del blackout precedente invece di + azzerarlo farebbe apparire il primissimo polling di un nuovo blackout come se la + soglia fosse già passata. Quel contatore non viene letto affatto. Il timer in corso + sopravvive a un riavvio del servizio, quindi un aggiornamento o un reboot non lo + perdono; solo dove quel timer memorizzato è inutilizzabile (mancante, o più vecchio + di un giorno) un'appliance che si avvia in un blackout già in corso ricomincia a + contare da zero — e le condizioni su autonomia, carica e “batteria scarica” + leggono valori freschi e non ne sono influenzate. La pagina di + stato indica se un tempo trascorso è stato misurato affatto.
+Un timer ripristinato aspetta che l'UPS confermi il blackout. Questa + appliance spegne il proprio host per ultimo, quindi ogni blackout finisce con + il suo riavvio — e torna a un timer memorizzato che dice “a batteria da tre + ore”. Quello è esattamente il momento in cui uno switch sta ancora convergendo e una + scheda SNMP sta ancora avviandosi, e un timer preso per buono lì + spegnerebbe di nuovo le macchine appena risalite. Quindi nulla di ciò che viene letto + dal file memorizzato spegne qualcosa finché un polling del servizio riavviato non ha + risposto. Quella risposta decide in ogni caso: su rete, tutto ciò che è stato + ripristinato viene scartato; ancora a batteria, il trigger viene calcolato dal tempo + ripristinato intero su quello stesso polling. Un riavvio nel mezzo di un + blackout non costa quindi nulla, perché lì l'UPS è raggiungibile per definizione. + L'unico caso che perde il countdown è un UPS che non risponde mai più dopo il + riavvio — e lì l'appliance non ha affatto prove che il blackout sia ancora in + corso, che è esattamente quando non agisce. Mentre un timer è in attesa la + dashboard lo dice invece di contare alla rovescia verso uno spegnimento che non + avverrà. Un timer in attesa non conta nemmeno come blackout per i controlli che si + fermano durante uno: l'auto-test, i controlli all'avvio e + “Ripristina cluster” restano disponibili, il che conta perché un UPS ancora + silenzioso dopo il reboot dell'appliance è esattamente quando il cluster lasciato + dall'ultimo blackout va ripristinato.
+Se una richiesta di spegnimento fallisce — un'API occupata, una + connessione caduta, o un nodo che ha semplicemente impiegato troppo a rispondere + — a quell'host viene chiesto di nuovo ai polling successivi, fino a tre + tentativi in totale, e ognuno finisce nel registro eventi. Una richiesta ripetuta a + una macchina che si sta già spegnendo non fa danni; non richiederlo la lascerebbe + accesa finché la batteria è vuota. Se la rete torna mentre un host è ancora in + ritentativo, l'episodio si chiude come ogni altro: l'appliance torna a + ONLINE e scrive un evento critico che dice che quella + macchina non è mai scesa ed è ancora in esecuzione.
+Valori fuori da un intervallo sensato vengono corretti, non obbediti. Un + intervallo di polling pari a zero o un timeout negativo ripiegano sul default e + scrivono un evento che nomina l'impostazione. È voluto: rifiutare di caricare la + configurazione significherebbe che l'appliance non si avvia più, e non protegge + nulla.
+| Condizione | Default |
|---|---|
| A batteria per più di | 600 s |
| Autonomia sotto | 10 min |
| Carica sotto | 30 % |
L'UPS segnala battery low/depleted | attivo |
Intervallo di polling: 30 s su rete, 8 s a batteria.
+Le soglie batteria scarica, autonomia e carica scattano immediatamente — + indipendentemente dal conto alla rovescia temporale. Il countdown mostrato sulla + dashboard si riferisce esclusivamente alla condizione "a batteria per più di" e + sparisce appena l'UPS ha attivato il trigger. Se un host si spegne subito a quel + punto lo decide la sua logica AND/OR (vedi Come funziona e + logica): con AND aspetta che tutti i suoi UPS alimentanti abbiano + attivato.
+9 Monitoraggio / REST
+Due endpoint in sola lettura sono disponibili senza autenticazione e senza + segreti:
+-
+
GET /api/status— lo stato completo: appliance, tutti gli UPS, + gli host, lo stato dello spegnimento, i target di notifica con l'esito della loro + ultima consegna (webhooks, volutamente senza l'URL), più gli eventi + delle ultime 48 h con un riepilogo per gravità.
+ GET /api/health—200quando l'engine è in esecuzione + (con versione e raggiungibilità degli UPS), altrimenti503. Ideale per + controlli di uptime. Riporta anche i target di spegnimento:hosts_total, +hosts_ok(l'ultimo auto-test ha confermato token e privilegio), +hosts_selftest_okehosts_selftest_at, i + target di notifica (webhooks_total,webhooks_ok— + un target conta come ok finché un invio non è dimostrabilmente fallito, quindi uno mai + provato non risulta guasto) edry_run. Questi sono + informativi — un token rotto non porta l'endpoint a +503, perché l'appliance stessa sta ancora facendo il suo lavoro. Allerta su +hosts_selftest_ok,webhooks_okedry_run+ separatamente se vuoi esserne avvisato: un'appliance lasciata in dry-run passa ogni + controllo qui, rispondeok, e non spegne nulla.
+
curl http://<container-ip>:8080/api/status | jq
+# solo gli eventi critici delle ultime 48 h:
+curl -s http://<container-ip>:8080/api/status \
+ | jq '.events[] | select(.severity=="critical")'Tutti gli endpoint modificanti (salvataggio procedura guidata, test + di spegnimento) sono protetti da password.
+Storico
+La scheda Storico, tra Dashboard e Impostazioni, mostra ogni UPS nel + tempo: autonomia residua, carico e carica, con lo stato di alimentazione come + sfondo colorato — a batteria, spegnimento attivato, non raggiungibile, bypass. Gli + eventi del registro appaiono come marcatori: avvisi ed eventi critici sempre, quelli + informativi (l'auto-test, ad esempio) quando spuntati. Passando sul grafico si + vedono i valori di quel momento e gli eventi al marcatore.
+-
+
- Periodi da 1 ora a 90 giorni, e “Tutto” — o un qualsiasi inizio e fine + digitati in Da e A; quei due campi mostrano sempre il periodo sullo + schermo. Trascina sul grafico per ingrandire un tratto, doppio clic per tornare al + preset; un periodo fisso non si aggiorna sotto di te. +
- Un UPS: autonomia in minuti sopra, carico e carica in percentuale sotto — + due pannelli su un asse temporale anziché un grafico con due scale. La linea + tratteggiata è il trigger “Autonomia sotto” che quell'UPS usa davvero, così vedi + quanto un blackout ci è andato vicino. +
- Tutti (con più di un UPS): una misura per ogni UPS in un unico + grafico, e una striscia di stato per UPS sotto. +
- La tabella blackout elenca ogni tratto a batteria nel periodo — inizio, + durata, autonomia e carica minime, carico massimo, se uno spegnimento è stato + attivato. Cliccando una riga il grafico zooma su quel blackout. +
- CSV scarica i valori grezzi del periodo sullo schermo. +
Cosa viene registrato: un valore per UPS al minuto su rete, uno per polling a
+ batteria, e uno a ogni cambio di stato — circa 1.440 righe per UPS al giorno, pochi
+ MB per UPS su 90 giorni. Vive in history.db accanto al registro eventi
+ (in Docker, nello stesso volume), non fa parte del backup della configurazione, e
+ “Svuota registro” lo lascia stare. È scritto in background: un disco lento o pieno
+ costa lo storico, mai lo spegnimento.
In Impostazioni → Sistema la registrazione si può disattivare, la + retention impostare in giorni (1–365, default 90) e lo storico svuotare. Spento ferma + la registrazione e nasconde la scheda; ciò che è stato registrato resta finché non + scade. + Una nuova installazione registra dall'inizio; dopo un aggiornamento da una versione + precedente resta spento finché non lo attivi, così un aggiornamento non inizia mai + a scrivere su un disco che nessuno ha dimensionato per questo.
+ +Notifiche webhook
+Opzionalmente, ogni evento rilevante viene inviato via HTTP POST a un URL a + scelta (impostazioni, sezione 4). Puoi configurare tutti i webhook che vuoi — + una scheda per target, ciascuna con formato, filtro di gravità e pulsante di test + propri. Gli invii girano in parallelo e vengono riportati singolarmente, quindi un + target irraggiungibile non costa agli altri la loro notifica.
+Un target che smette di funzionare lo dice. Un token scaduto o un + connettore cancellato fallivano in silenzio, il che significava scoprirlo durante il + blackout che non ti è mai arrivato. Il primo fallimento dopo un invio riuscito viene + scritto nel registro eventi, la scheda webhook mostra l'ultimo errore finché un invio + non riesce di nuovo, e la scheda appliance della dashboard guadagna una riga + “Notifiche” finché un qualsiasi target fallisce — la pagina + impostazioni non è dove qualcuno guarda mentre un blackout è in corso. Le notifiche + restano best-effort comunque: non vengono mai ritentate, e un target che fallisce non + ritarda né influenza mai uno spegnimento.
+Formato — la forma del payload, in base al tuo sistema di + destinazione:
+| Formato | Invia |
|---|---|
| JSON (stato completo) | {subject, body, severity, status} —
+ status è lo snapshot completo di /api/status. Per sistemi
+ di ticket, monitoraggio e automazione. |
| Microsoft Teams | una adaptive card (intestazione colorata per + gravità, testo del messaggio, fatti su UPS, host e modalità) nella busta + messaggio che Teams si aspetta. |
| Testo semplice | un breve stato leggibile come
+ text/plain — per qualsiasi cosa che mostri semplicemente una riga di
+ testo. |
| Slack | un allegato con barra colorata per gravità e i fatti come
+ campi. Usa l'URL dell'integrazione “Incoming Webhooks” di un'app Slack
+ (https://hooks.slack.com/services/…). |
| Discord | un embed con titolo, descrizione e campi. Usa l'URL + da canale → Modifica → Integrazioni → Webhook. |
| ntfy | un push in testo semplice i cui header Title,
+ Priority e Tags vengono impostati dall'evento. Usa
+ l'URL del topic (https://ntfy.sh/il-tuo-topic). |
| Personalizzato (template) | un body che scrivi tu, più il content + type — per un target a cui nessun preset si adatta. Vedi sotto. |
Per Microsoft Teams, usa l'URL di un workflow “Posta in un canale quando + viene ricevuta una richiesta webhook” (Teams → canale → Workflows); l'URL di un + classico incoming webhook funziona ugualmente.
+Template personalizzati. Con il formato Personalizzato fornisci body e + content type. Questi placeholder vengono sostituiti; tutto il resto è inviato + verbatim:
+| Placeholder | Contiene |
|---|---|
{{subject}} / {{body}} | l'oggetto + dell'evento e il testo di dettaglio |
{{severity}} / {{severity_upper}} |
+ info, warning o critical |
{{facts}} / {{facts_json}} | il breve + riepilogo UPS/host, come righe di testo o come oggetto JSON |
{{status_json}} | lo snapshot completo di
+ /api/status come JSON |
{{timestamp}} / {{version}} | l'ora + dell'evento (UTC) e la versione dell'appliance |
È una semplice sostituzione, non un linguaggio di espressioni: niente cicli e
+ niente condizionali. Quando il content type contiene json, i valori
+ vengono escapati in JSON automaticamente, quindi una virgoletta in un testo di evento
+ non può produrre un payload malformato.
Header di autenticazione (opzionale, per webhook) — nome e valore di un
+ header aggiuntivo, ad esempio Authorization: Bearer … per un topic
+ ntfy protetto o un header API-key. Il valore è trattato come segreto: non viene mai
+ restituito dall'API e resta invariato quando salvi senza reinserirlo.
Header extra (opzionale, per webhook) — un header per riga, scritto come
+ Nome: Valore, per target che hanno bisogno di più dell'unico header sopra.
+ Nextcloud Talk è il caso tipico: oltre alla sua autorizzazione Basic si aspetta
+ OCS-APIRequest: true e Accept: application/json. Questi
+ header sovrascrivono ciò che il formato scelto imposta, ma mai l'header di
+ autenticazione sopra. Le righe che non sono un header valido vengono ignorate.
Invia dal livello — quali eventi vengono inviati. Tutto ciò che è sotto il + livello selezionato viene comunque scritto nel registro eventi, semplicemente non + attiva un messaggio:
+| Livello | Include ad esempio |
|---|---|
| Tutti gli eventi (incluso info) | in più “rete ripristinata”, + “connessione di rete ripristinata” |
| Avvisi e critici (default) | blackout, UPS irraggiungibile, + auto-test fallito, spegnimento inviato/annullato |
| Solo critici | spegnimento attivato, spegnimento FALLITO |
Il pulsante “Invia notifica di test” invia un messaggio di esempio con i + valori attualmente inseriti — non serve salvare prima, e il filtro di livello non si + applica. Riporta il risultato HTTP del target, quindi un URL sbagliato emerge + subito.
+Le notifiche sono best-effort: un target irraggiungibile viene + registrato e non influenza mai la logica di spegnimento.
+10 Aggiornamenti e gestione
+Gli aggiornamenti si caricano direttamente nella web UI; un servizio companion + minimale e privilegiato li applica (l'app stessa resta senza privilegi). Dopo + l'upload, l'aggiornamento viene tipicamente applicato in pochi secondi. La web UI + permette anche di esportare/importare la configurazione, impostare server NTP e + fuso orario, e vedere/svuotare il registro eventi.
+L'interfaccia web si aggiorna da sola in modo affidabile dopo un update: la + pagina non viene mai messa in cache, e ogni script e stylesheet che carica porta + un'impronta che cambia con il file — un browser non può quindi continuare a servire + la versione precedente. Se una scheda era aperta durante il riavvio del servizio, + in alto compare un avviso con un pulsante “Ricarica”; finché non lo usi, + quella scheda esegue ancora la vecchia interfaccia.
+Nota: il fuso orario (sezione Sistema, es.
+ Europe/Rome) andrebbe impostato, altrimenti il container gira in UTC.
+ L'orario di avvio dell'auto-test è interpretato in quest'ora locale; dopo aver
+ impostato il fuso orario il servizio si riavvia brevemente.
Auto-test delle connessioni di destinazione
+L'appliance verifica da sola se per host il token API e il suo privilegio di
+ power-management funzionano ancora — Sys.PowerMgmt su Proxmox VE,
+ Sys.PowerManagement su un Backup Server — così una credenziale
+ scaduta o revocata emerge molto prima che un blackout ne abbia bisogno. Due
+ impostazioni nella sezione Sistema lo controllano: un orario di
+ avvio (ora piena) e un intervallo da 15 minuti fino a 24 ore. Insieme
+ definiscono orari fissi del giorno: avvio 09:00 con intervallo di 6 ore significa
+ 09:00, 15:00, 21:00 e 03:00. Il default è giornaliero.
Un auto-test fallito viene sempre registrato e notificato. Uno riuscito viene + scritto nel registro eventi al massimo una volta al giorno (e ogni volta che si + riprende da un fallimento), così un intervallo breve non seppellisce il registro. + Mentre un UPS è a batteria l'auto-test viene saltato del tutto — durante un blackout + il countdown ha priorità. Un riavvio non ripete un auto-test già eseguito nello slot + corrente.
+Se anche quell'unica riga al giorno è troppo — un solo amministratore che sa
+ quando un token è cambiato — togli la spunta a “Registra gli auto-test riusciti
+ nel registro eventi”. Sparisce solo la riga verde di routine; il controllo
+ continua a girare all'intervallo configurato, i fallimenti sono registrati e
+ notificati come prima, il journal di sistema registra comunque ogni esecuzione, e il
+ verdetto per host sulla dashboard non ne risente. Il controllo cluster condivide la
+ pianificazione dell'auto-test e la sua riga di log, quindi anche il
+ Cluster <nome>: ok per cluster tace con essa; ogni
+ avviso cluster viene riportato come prima. Due righe verdi sopravvivono
+ comunque all'interruttore: un'esecuzione richiesta da te, e quella che riporta una
+ ripresa da un fallimento.
/api/health dal tuo sistema di monitoraggio (vedi
+ Monitoraggio), che copre anche il caso dell'appliance che
+ non gira affatto.
+ Salvare le impostazioni non attiva un auto-test — è voluto, così + modificare la configurazione non martella mai l'API Proxmox. Dopo aver cambiato un + token o spuntato l'opzione cluster, usa “Esegui auto-test ora” sulla + dashboard per vedere subito il risultato invece di aspettare lo slot successivo. + Scrive sempre il suo risultato nel registro eventi, ignorando il limite di una + volta al giorno, e viene rifiutato mentre un UPS è a batteria.
+Per gli host marcati come membri di cluster l'auto-test + controlla anche il cluster una volta: privilegi del token, quorum, flag di + manutenzione Ceph, stato di arm di HA e shutdown policy del datacenter. Un cluster + sano viene registrato come “Cluster <nome>: ok”, così “controllato e + a posto” è distinguibile da “mai controllato”. Nota il rovescio: senza la spunta + cluster niente di tutto questo gira, e il log mostra allora solo la semplice + riga per host.
+Il risultato viene conservato anche per host: la tabella host della + dashboard mostra il problema nella sua colonna errori anche quando nulla è stato + spento, e /api/health conta quanti target hanno superato + l'ultimo controllo.
+Aggiornamento dalla versione 2.x alla 3.x
+Scarica il pacchetto della release corrente
+ (pve-usv-<versione>.tar.gz) dalla
+ pagina releases di GitHub e caricalo nella web UI sotto
+ “Aggiornamento” — la configurazione è interamente preservata. Due cambi di
+ comportamento: le notifiche e-mail non ci sono più (una voce SMTP configurata in
+ precedenza viene rimossa automaticamente al prossimo salvataggio;
+ il webhook resta), e i testi di eventi/webhook sono in inglese dalla 3.0.0.
Deployment Docker
+Come alternativa all'installazione LXC, a ogni release viene pubblicata
+ un'immagine precompilata su
+ ghcr.io/ffind-dev/pve-ups.
+ L'immagine è multi-arch — linux/amd64, linux/arm64 e
+ linux/arm/v7 — quindi gira anche su un Raspberry Pi 3/4/5 con OS a
+ 64 o 32 bit; Docker sceglie la variante giusta. Un dispositivo così piccolo
+ consuma poco dalla batteria e resta acceso mentre gli host che protegge si
+ spengono. Un
+ docker-compose.example.yml pronto è nel
+ repository; l'essenziale:
services:
+ pve-ups:
+ image: ghcr.io/ffind-dev/pve-ups:latest
+ container_name: pve-ups
+ restart: unless-stopped
+ ports: ["8080:8080"]
+ environment:
+ - TZ=Europe/Rome
+ volumes:
+ - pve-ups-config:/etc/pve-usv # config.yaml (segreti, 0600)
+ - pve-ups-data:/var/lib/pve-usv # events.db, history.db + stato engine
+volumes:
+ pve-ups-config:
+ pve-ups-data:Poi apri http://<docker-host>:8080 e segui la stessa
+ procedura guidata dell'LXC. Configurazione e registro eventi persistono tramite i
+ due volumi montati, quindi docker compose down non perde nulla.
Dato che nell'immagine non c'è un processo companion privilegiato (niente
+ systemd), due cose funzionano diversamente: gli aggiornamenti si applicano
+ scaricando un nuovo tag dell'immagine e ricreando il container
+ (docker compose pull && docker compose up -d) invece
+ dell'uploader in-app, e NTP/fuso orario sono responsabilità dell'host Docker o
+ dell'orchestratore anziché essere impostati dalla procedura guidata — entrambe le
+ aree sono nascoste nella web UI. Tutto il resto (polling UPS, spegnimento Proxmox,
+ soglie, webhook, auto-test) è identico.
TZ sul container. L'orario di avvio
+ dell'auto-test è interpretato nell'ora locale del container, e senza
+ TZ il container gira in UTC — il fuso orario non si può impostare
+ dalla web UI in modalità Docker.
+ 172.17.0.0/16 –
+ 172.31.0.0/16, sposta l'address pool di default di Docker
+ prima di avviare il container — Docker reclama quel range per i suoi
+ bridge, e il container non raggiungerebbe più un UPS o un host Proxmox al suo
+ interno. In /etc/docker/daemon.json, ad es.
+ {"bip":"10.210.0.1/24","default-address-pools":[{"base":"10.211.0.0/16","size":24}]},
+ poi systemctl restart docker.
+ 11 Risoluzione dei problemi
+Un Backup Server riporta “Authentication failed (token invalid?)”
+Quasi sempre è il tipo sbagliato sulla voce host. Proxmox VE e Proxmox
+ Backup Server usano schemi di token diversi, e PBS non riconosce affatto quello PVE —
+ quindi la richiesta viene rifiutata prima ancora che il token venga guardato, per
+ quanto valido sia. Imposta il tipo su Proxmox Backup Server e riprova. Se il
+ test poi riesce ma avverte che Sys.PowerManagement non si è potuto
+ confermare, l'ACL manca sull'utente, sul token, o su entrambi — vedi
+ la sezione 4. Controlla anche che l'URL API usi la porta
+ 8007.
L'aggiornamento resta in coda
+Se un aggiornamento caricato resta su “⏳ In coda”, il drainer della coda non è + attivo su quest'istanza. Succede una volta su macchine aggiornate da una versione + molto vecchia. Esegui una volta dentro il container (abilita il servizio in + permanenza):
+pct exec <CTID> -- systemctl start pve-usv-agent.service
+# o direttamente dentro il container:
+systemctl start pve-usv-agent.serviceCluster: serve un token separato per nodo?
+No. Utenti, token API e ACL sono salvati a livello datacenter
+ (/etc/pve), quindi un token creato una volta su un qualsiasi nodo vale
+ su tutti — eseguire i comandi della sezione 4 una seconda
+ volta riporterebbe solo che l'utente esiste già. Aggiungi ogni nodo con lo
+ stesso token ID e segreto, ma con il suo URL API.
UPS irraggiungibile / allarme
+Controlla indirizzo, credenziali e il firewall tra l'appliance e la sorgente + UPS. “Testa UPS” nella procedura guidata mostra la causa esatta — apri + Dettagli per oggetto per vedere quale oggetto è fallito e perché (vedi + Sorgenti UPS). Una sola perdita di comunicazione non spegne + mai nulla (fail-safe).
+Una soglia non scatta mai
+Non ogni dispositivo riporta ogni valore. Esegui “Testa UPS”: se il dispositivo + non pubblica l'autonomia residua o la carica, il test lo dice sopra la tabella + oggetti, e la soglia corrispondente resta perennemente inefficace. Usa invece “A + batteria per più di (s)” — quel timer gira sull'orologio proprio + dell'appliance.
+Su un UPS SNMP, controlla anche l'impostazione MIB. Molte schede + pubblicano nel loro MIB del produttore ciò che tralasciano dall'RFC 1628; + Automatico lo trova da solo, quindi vale la pena guardarci solo se il MIB è + stato fissato a mano (vedi Sorgenti UPS).
+Un UPS APC non funziona / non risponde nulla di utile
+Lascia l'impostazione MIB su Automatico — il MIB APC PowerNet viene
+ allora usato da solo. Serve perché Schneider supporta RFC 1628 solo sulle Network
+ Management Card 2 (AP9630/AP9631/AP9635) dal firmware
+ sumx/sy v5.1.7 in poi, mentre le schede NMC1 più
+ vecchie (AP9617/AP9618/AP9619) non lo implementano affatto. “Testa UPS” mostra
+ quale MIB è stato usato e quali oggetti ciascuno ha risposto.
Un UPS CyberPower riporta “nessuna risposta” anche se la scheda è + raggiungibile
+Esegui “Testa UPS”. Se il suo riepilogo dice che il polling regolare non ha + avuto risposta mentre i valori rispondono uno alla volta, la scheda non gestisce una + richiesta di più valori insieme: imposta il MIB su CyberPower, che + viene letto un valore per richiesta. Se la scheda non risponde affatto, controlla + community/credenziali e che SNMP sia abilitato per l'IP dell'appliance sulla + scheda.
+NUT: “does not know a UPS with that name” o non risponde nulla
+Il nome dell'UPS deve corrispondere al nome di sezione nel
+ ups.conf di upsd; upsc -l <host> elenca i nomi
+ validi. Se non risponde affatto nulla, molto probabilmente upsd è in ascolto solo su
+ localhost — la sua direttiva LISTEN deve coprire l'interfaccia a cui
+ l'appliance si connette, e la TCP 3493 deve essere aperta.
SNMPv3 con crittografia fallisce
+Se un utente authPriv riporta “Ciphering services not available” o il test
+ punta a crittografia mancante, all'appliance manca il pacchetto Python
+ cryptography, che fornisce i cifrari DES/AES. Le versioni fino alla
+ 3.0.0 non lo installavano. Aggiornare l'appliance risolve — il pacchetto
+ arriva automaticamente. Due cose da sapere: riguarda ogni protocollo di privacy,
+ quindi passare da DES ad AES non aiuta, e authNoPriv (autenticazione
+ MD5/SHA, privacy “nessuna”) continua a funzionare nel frattempo, perché
+ l'autenticazione non ha bisogno di quei cifrari.
Nomi interni: pve-usv
+ Il nome del prodotto è PVE-UPS, ma servizio e percorsi si chiamano
+ tecnicamente ancora pve-usv — ad es.
+ systemctl status pve-usv, /etc/pve-usv/config.yaml e
+ /var/lib/pve-usv/. È intenzionale e mantiene gli aggiornamenti delle
+ installazioni esistenti compatibili.
12 Changelog (in breve)
+Punti salienti semplificati, visibili all'utente. Il changelog + tecnico completo vive nel + repository GitHub.
+ +-
+
- Scheda storico: autonomia residua, carico e carica di ogni UPS nel + tempo, con blackout, trigger e marcatori del registro eventi, zoom, un periodo + libero, una tabella blackout ed export CSV. Dopo un aggiornamento resta spenta + finché non la attivi in Impostazioni → Sistema — vedi + Storico. +
- “Ferma prima tutti i guest a livello cluster” senza Ceph: a ogni + guest viene chiesto di spegnersi insieme prima che il primo nodo scenda, invece + che nodo per nodo in ordine di startup — per cluster dove questo richiede più di + quanto duri la batteria. Vedi l'arresto + guest. +
- Schede di rete CyberPower lette tramite il loro MIB, anche schede + senza RFC 1628. “Automatico” su SNMP v2c non fallisce più su schede che + rispondono a un oggetto mancante con un errore. +
- L'immagine Docker gira su Raspberry Pi (64 e 32 bit). +
-
+
- Un webhook che hai spento non deve più avere un URL. Un target di + notifica preparato a metà viene conservato come bozza; solo uno attivo + insiste ancora su dove postare. +
- I webhook possono portare header extra. Target che ne richiedono più
+ di uno — come Nextcloud Talk, che si aspetta
OCS-APIRequeste +Acceptoltre alla sua autorizzazione — ora funzionano senza un proxy + davanti.
+ - I password manager possono di nuovo compilare il form di login. La + pagina di accesso è un form vero con campo username, che è ciò su cui l'autofill + inline fa leva; i campi token e password nelle impostazioni sono marcati perché + un manager li lasci stare. +
- Gli auto-test riusciti si possono tenere fuori dal registro eventi + senza testare le credenziali meno spesso. Fallimenti, riprese ed “Esegui + auto-test ora” riportano sempre. +
-
+
- Un UPS che riporta un “tempo a batteria” vecchio non spegne più tutto in + una volta. L'appliance ora misura il blackout sul proprio orologio invece di + credere al contatore riportato dal dispositivo — un contatore che lo standard + definisce solo mentre l'UPS è a batteria e che molte schede conservano + dall'ultimo blackout. Il timer in corso sopravvive a un riavvio del + servizio. +
- Un UPS che risponde senza dire da dove viene la sua alimentazione è un + allarme, non un tutto-ok. Per SNMP e NUT allo stesso modo, una lettura così + non azzera più un countdown in corso nel mezzo di un blackout — e non conta mai + nemmeno come silenzio, quindi “Spegnimento su pura perdita di comunicazione” non + si applica a un dispositivo che sta rispondendo. +
- Uno spegnimento che fallisce viene ritentato — tre tentativi invece di + uno, così un'API Proxmox occupata o una connessione caduta non lasciano più una + macchina accesa mentre la dashboard la riporta come gestita. +
- Un cluster si porta dietro solo i nodi che lo hanno chiesto, e i tre + interruttori cluster vengono letti una volta per cluster anziché dal nodo che è + capitato a scattare per primo. Vedi la sezione 6. +
- Inoltre: le consegne webhook fallite vengono riportate invece di fallire + in silenzio, un dry-run attivo lo dice sulla dashboard, le voci che non possono + fare il loro lavoro (un host senza token, un UPS senza indirizzo) vengono + segnalate, e nessuna credenziale può raggiungere l'endpoint di stato + pubblico. +
-
+
- I cluster Proxmox VE vengono preparati prima dello spegnimento + Beta. Marca un nodo come membro di cluster e + PVE-UPS disarma l'HA manager una volta per cluster — e, con l'opzione Ceph, ferma + ogni guest e poi imposta i flag di manutenzione — prima che il primo nodo scenda. + Un pulsante “Ripristina cluster” sulla dashboard lo annulla dopo. Richiede + Proxmox VE 9.2 o più recente ed è opt-in ovunque; vedi la + sezione 6. +
- Un cluster viene spento come unità (attivo di default): un nodo che + diventa dovuto si porta dietro l'intero cluster, nell'ordine configurato, invece + di lasciare mezzo cluster in piedi con HA disarmato. Si può disattivare. +
- Più webhook invece di uno, ciascuno con formato, filtro e pulsante di + test propri — più nuovi formati per Slack, Discord e ntfy + e un template personalizzato. Vedi la sezione 9. +
- L'auto-test è più utile: gira automaticamente dopo che l'appliance si + riarma, “Esegui auto-test ora” lo avvia sul momento, e rinominare un host non + scarta più il suo token API. Vedi la sezione 4. +
-
+
- Anche un Proxmox Backup Server può ora essere spento. Ogni voce host + ha un tipo — Proxmox VE o Proxmox Backup Server — che decide lo schema di + token e il privilegio verificato. Inserire un PBS falliva come token non valido + qualunque cosa si facesse; vedi la sezione 4 per la + configurazione, incluso perché sconsigliamo di collegare PBS alla stessa + istanza in produzione. +
- Per un Backup Server il campo “Nodo” è solo un'etichetta. PBS ignora + il nome del nodo nel path API, quindi lì niente deve corrispondere + all'hostname. +
- Gli host vengono ora spenti a stadi invece che strettamente uno dopo + l'altro: le voci che condividono un “Ordine” vengono comandate insieme, l'host + proprio dell'appliance va sempre per ultimo, e ogni comando ha una deadline + rigida. Una macchina che smette di rispondere non può più ritardare le altre né + il countdown della batteria — vedi la sezione 6. La + procedura guidata mostra la sequenza risultante dal vivo sotto la lista host, + così si vede quali host vanno insieme e quali seguono. +
- Il risultato dell'auto-test viene conservato per host: un token rotto + ora appare nella tabella host della dashboard e in + /api/health, non solo nel registro eventi. +
-
+
- Il webhook ora parla la lingua del suo target: oltre al precedente + JSON di stato può postare una card Microsoft Teams o un breve stato in + testo semplice. Vedi Notifiche webhook. +
- Un nuovo filtro di livello decide quali eventi vengono inviati + affatto. Il default è Avvisi e critici — i messaggi di puro tutto-ok non + arrivano più; imposta il filtro su Tutti gli eventi per il comportamento + precedente. +
- “Invia notifica di test” invia un messaggio di esempio con i valori + attualmente inseriti — senza salvare prima — e riporta il risultato HTTP del + target. +
- Uno spegnimento eseguito o ritirato (
shutdown sent/ +shutdown aborted) conta come avviso invece che info, e viene + mostrato in ambra nel registro eventi.
+
-
+
- Gli UPS APC sono supportati correttamente: un UPS SNMP può ora essere + letto tramite un MIB del produttore invece di RFC 1628, il primo dei quali + è APC PowerNet. Questo copre schede APC che RFC 1628 non riesce a + raggiungere affatto — le NMC1 più vecchie (AP9617/AP9618/AP9619) — oltre alle + schede NMC2 con firmware sotto sumx/sy v5.1.7. Vedi + Sorgenti UPS. +
- La nuova impostazione MIB ha default Automatico e non richiede + attenzione: le voci UPS esistenti la ricevono con l'aggiornamento, e un UPS passa + al suo MIB del produttore da solo appena risponde lì. +
- Le schede che supportano entrambi ottengono letture più accurate: + PowerNet riporta l'autonomia residua in centesimi di secondo invece che in minuti + interi, e marca un auto-test come tale — RFC 1628 non sa distinguerlo da + un blackout vero. +
- Il test UPS si spiega da solo: in modalità Automatico elenca entrambi + i MIB, dice su quale si è assestato e perché, e la dashboard nomina il MIB in + uso. +
-
+
- Gli UPS senza scheda di rete possono ora essere monitorati: una voce + UPS viene letta via SNMP come prima, oppure tramite un server NUT — che è + come si raggiungono gli UPS USB e seriali. I due tipi si possono mescolare in + un'istanza. Vedi Sorgenti UPS. +
- PVE-UPS resta un client NUT strettamente in sola lettura — niente
+
upsmon, niente script di spegnimento, niente file di config. La + decisione resta nell'appliance.
+ - Il test UPS nomina le soglie morte: se un dispositivo non riporta né + autonomia residua né carica, il test lo dice invece di lasciare una soglia che + silenziosamente non scatta mai. +
- Un server NUT che serve dati obsoleti (il suo driver è crashato) conta come + irraggiungibile — un allarme, mai uno spegnimento, e mai scambiato per “su + rete”. +
-
+
- SNMPv3 con crittografia ora funziona. Un utente authPriv falliva con + “Ciphering services not available” fino alla 3.0.0 inclusa — una dipendenza + mancante, che l'aggiornamento installa strada facendo. Vedi + Risoluzione dei problemi. +
- Deployment Docker come alternativa all'LXC: un'immagine precompilata + viene pubblicata a ogni release. Vedi Deployment + Docker. +
- Test SNMP con dettagli per oggetto: ogni oggetto RFC 1628 con il suo + valore o il motivo per cui manca, così credenziali sbagliate, una porta bloccata + e un UPS incompleto si distinguono a colpo d'occhio. +
- Auto-test con intervallo: l'orario del giorno diventa un orario di + avvio, con ripetizione da 15 minuti fino a 24 ore. Le installazioni esistenti + mantengono la loro cadenza giornaliera. +
-
+
- Prima release pubblica su GitHub con il nome PVE-UPS
+ (nomi di servizio/percorsi restano
pve-usvinternamente).
+ - Web UI bilingue: inglese (default) e tedesco, scelta automaticamente + dalla lingua del browser; manuale utente in entrambe le lingue. +
- Registro eventi, messaggi webhook e messaggi API uniformemente in + inglese. +
- Notifiche e-mail rimosse — il webhook copre le notifiche; le voci SMTP + esistenti vengono scartate automaticamente con l'aggiornamento. +
- Installazione e aggiornamenti direttamente via GitHub releases + (installazione one-liner, aggiornamento con upload del pacchetto nella web UI; + indolore dalla 2.x). +