ROMFASTSQL/proxmox/cluster/ups/README.md

Documentație UPS - Cluster Proxmox

Despre

Această documentație descrie configurarea completă a sistemului UPS (Uninterruptible Power Supply) pentru cluster-ul Proxmox, incluzând monitorizare automată și shutdown orchestrat.

Structură Directoare

proxmox/ups/
├── README.md                           # Acest fișier
├── config/                             # Fișiere de configurare NUT
│   ├── ups.conf                        # Configurare driver UPS
│   ├── upsd.conf                       # Configurare server NUT
│   ├── upsd.users                      # Utilizatori și permisiuni
│   ├── upsmon.conf                     # Configurare monitor local
│   └── upssched.conf                   # Scheduler evenimente UPS
├── scripts/                            # Scripturi de shutdown și testare
│   ├── ups-shutdown-cluster.sh         # Script principal shutdown orchestrat
│   ├── ups-shutdown-test.sh            # Script test (dry-run)
│   ├── upssched-cmd                    # Handler evenimente upssched
│   ├── ups-monthly-test.sh             # Test lunar automat baterie
│   └── ups-maintenance-shutdown.sh     # Shutdown pentru mentenanță UPS (NOU!)
└── docs/                               # Documentație
    ├── INSTALARE-NUT.md                # Ghid instalare NUT pe Proxmox
    ├── INSTALARE-WINNUT.md             # Ghid instalare WinNUT pe Windows
    ├── UPS-SHUTDOWN-README.md          # Documentație completă sistem
    ├── UPS-MONTHLY-TEST.md             # Documentație test lunar baterie
    └── UPS-BATTERY-REPLACEMENT.md      # Procedură înlocuire baterie (NOU!)

🎯 Utilizare: Pentru instalare nouă: Citește README.md Urmează docs/INSTALARE-NUT.md Copiază fișiere din config/ și scripts/ pe server Pentru backup: Tot ce trebuie este salvat în proxmox/ups/ Versionat în Git Pentru recovery: Restaurează fișiere din config/ în /etc/nut/ Restaurează fișiere din scripts/ în /usr/local/bin/ Restart servicii

Arhitectură Sistem

Hardware

• UPS: INNO TECH USB to Serial (Vendor ID: 0665, Product ID: 5161)
• Conectat la: pvemini (10.0.20.201) via USB
• Tip: Voltronic/Megatec protocol (driver: nutdrv_qx)

Cluster Proxmox

• pvemini (10.0.20.201) - Nod PRIMARY
  • Are UPS-ul conectat fizic
  • Rulează NUT server și driver
  • Ultimul nod care se oprește
• pve1 (10.0.20.200) - Nod SECONDARY
  • Se oprește primul în caz de baterie critică
• pve2 (10.0.20.202) - Nod SECONDARY
  • Se oprește primul în caz de baterie critică

Monitorizare

• VM 201 (Windows 11) - Monitorizare vizuală via WinNUT
  • Afișează status UPS în timp real
  • NU controlează shutdown-ul

Flux Automat Shutdown

Scenario 1: Întrerupere scurtă (< 3 minute)

1. Curent se întrerupe → UPS trece pe baterie (status: OB)
2. 📧 Email: "Trecere pe baterie" - notificare imediată
3. upssched pornește timer de 180 secunde
4. Curent revine înainte de 3 minute
5. 📧 Email: "Curent revenit - OK"
6. Timer anulat → Niciun sistem nu se oprește

Scenario 2: Întrerupere lungă (> 3 minute)

1. Curent se întrerupe → UPS pe baterie
2. 📧 Email: "Trecere pe baterie"
3. Timer 180 secunde expiră
4. 📧 Email: "Pe baterie 3 min - SHUTDOWN"
5. /usr/local/bin/ups-shutdown-cluster.sh pornește:
   • 📧 Email: "Shutdown cluster PORNIT"
   • Step 1: Oprește toate VM-urile și LXC de pe toate nodurile
   • Step 2: Așteaptă 90 secunde pentru oprire graceful
   • Step 3: Shutdown pve1 → 📧 Email: "Shutdown pve1 trimis"
   • Step 4: Shutdown pveelite → 📧 Email: "Shutdown pveelite trimis"
   • Step 5: Așteaptă 60 secunde
   • 📧 Email: "Shutdown pvemini (ULTIMUL NOD)"
   • Step 6: Comandă UPS shutdown (oprire completă)
   • Step 7: Shutdown pvemini (nod primary - ultimul)

Scenario 3: Baterie scăzută imediată

1. UPS raportează LOWBATT (baterie critică)
2. 📧 Email: "BATERIE CRITICĂ - SHUTDOWN IMEDIAT"
3. Shutdown IMEDIAT (fără timer)
4. Același flux de shutdown orchestrat ca mai sus

Quick Start

Pentru Administrator Nou

1. Citește documentația:

   • Start: docs/UPS-SHUTDOWN-README.md
   • Detalii NUT: docs/INSTALARE-NUT.md
   • WinNUT: docs/INSTALARE-WINNUT.md

2. Verifică status UPS:

   ssh root@10.0.20.201
   upsc nutdev1
   

3. Test dry-run:

   ssh root@10.0.20.201
   /usr/local/bin/ups-shutdown-test.sh
   cat /var/log/ups-shutdown-test.log
   

4. Monitorizează în WinNUT:

   • Pornește WinNUT pe VM 201
   • Verifică că se conectează la 10.0.20.201:3493

Verificare Săptămânală

# Conectează-te la pvemini
ssh root@10.0.20.201

# Status UPS
upsc nutdev1 ups.status battery.charge input.voltage

# Status servicii
systemctl status nut-server nut-monitor

# Logs evenimente recente
tail -20 /var/log/ups-events.log

# Test dry-run
/usr/local/bin/ups-shutdown-test.sh

Verificare Lunară

🔋 Test Automat Baterie (1 ale lunii la 00:00):

Scriptul /opt/scripts/ups-monthly-test.sh rulează automat lunar și:

• Testează capacitatea reală a bateriei
• Monitorizează scăderea charge și voltage
• Evaluează sănătatea bateriei (EXCELLENT/GOOD/FAIR/POOR)
• Trimite raport HTML prin email via PVE::Notify

Verificare rezultat test:

ssh root@10.0.20.201
# Vezi ultimul test
tail -50 /var/log/ups-monthly-test.log

# Rulare manuală (pentru testare)
/opt/scripts/ups-monthly-test.sh

Documentație completă: docs/UPS-MONTHLY-TEST.md

---

Test fizic manual (opțional):

• Deconectează UPS de la priză timp de 30 secunde
• Verifică că WinNUT detectează schimbarea (On Battery)
• Verifică logs: tail -f /var/log/ups-events.log
• Reconectează înainte de 3 minute pentru a evita shutdown

Verificare SSH între noduri:

ssh root@10.0.20.201
ssh root@10.0.20.200 "hostname"
ssh root@10.0.20.202 "hostname"

Instalare de la Zero

1. Instalare NUT pe pvemini

# Instalare pachete
apt update
apt install -y nut nut-client nut-server

# Copiere fișiere de configurare
cd /path/to/ROMFASTSQL/proxmox/ups
scp config/* root@10.0.20.201:/etc/nut/

# Copiere scripturi shutdown
scp scripts/ups-shutdown-cluster.sh scripts/ups-shutdown-test.sh scripts/upssched-cmd root@10.0.20.201:/usr/local/bin/
ssh root@10.0.20.201 "chmod +x /usr/local/bin/ups-*.sh /usr/local/bin/upssched-cmd"

# Copiere script test lunar
scp scripts/ups-monthly-test.sh root@10.0.20.201:/opt/scripts/
ssh root@10.0.20.201 "chmod +x /opt/scripts/ups-monthly-test.sh"

# Configurare cron pentru test lunar
ssh root@10.0.20.201 "(crontab -l 2>/dev/null | grep -v ups-monthly-test; echo '# UPS Monthly Battery Test'; echo '0 0 1 * * /opt/scripts/ups-monthly-test.sh') | crontab -"

# Configurare permisiuni
ssh root@10.0.20.201 "chown nut:nut /etc/nut/ups*.conf /etc/nut/upsd.*"
ssh root@10.0.20.201 "chmod 640 /etc/nut/upsd.users"

# Pornire servicii
ssh root@10.0.20.201 "systemctl enable nut-server nut-monitor"
ssh root@10.0.20.201 "systemctl start nut-server nut-monitor"

# Verificare
ssh root@10.0.20.201 "upsc nutdev1"

2. Instalare WinNUT pe VM 201

Vezi ghid detaliat: docs/INSTALARE-WINNUT.md

Server: 10.0.20.201
Port: 3493
UPS: nutdev1
User: admin
Pass: parola99
Polling: 15

Troubleshooting Rapid

UPS nu răspunde

ssh root@10.0.20.201

# Verifică UPS conectat
lsusb | grep 0665

# Restart driver
upsdrvctl stop && upsdrvctl start

# Verifică status
upsc nutdev1

WinNUT nu se conectează

1. Verifică Polling Interval ≠ 0 (pune 15)
2. Test port:

   Test-NetConnection -ComputerName 10.0.20.201 -Port 3493
   

3. Verifică server:

   ssh root@10.0.20.201 "ss -tulpn | grep 3493"
   

Scriptul de shutdown nu funcționează

# Test SSH între noduri
ssh root@10.0.20.201 "ssh root@10.0.20.200 hostname"

# Dacă eșuează, reconfigurează SSH keys
ssh root@10.0.20.201
ssh-keygen -f /root/.ssh/known_hosts -R 10.0.20.200
ssh-keyscan -H 10.0.20.200 >> /root/.ssh/known_hosts

Logs Important

Fișier	Scop
/var/log/ups-shutdown.log	Shutdown orchestrat real
/var/log/ups-shutdown-test.log	Test dry-run
/var/log/ups-events.log	Evenimente UPS (upssched)
/var/log/ups-monthly-test.log	Test lunar baterie (NOU!)
journalctl -u nut-server	Server NUT
journalctl -u nut-monitor	Monitor NUT

Comenzi Utile

# Status UPS complet
upsc nutdev1

# Doar câmpuri importante
upsc nutdev1 ups.status battery.charge input.voltage output.voltage

# Comenzi disponibile
upscmd -l nutdev1

# Conexiuni active NUT
ss -tnp | grep 3493

# Monitoring live
watch -n 2 'upsc nutdev1 ups.status battery.charge input.voltage'

# Test shutdown (DRY RUN - nu oprește nimic)
/usr/local/bin/ups-shutdown-test.sh

# Test lunar baterie (cu raport email)
/opt/scripts/ups-monthly-test.sh

# Verifică ultimul test lunar
tail -50 /var/log/ups-monthly-test.log

Configurare Personalizată

Modificare timp de asteptare (default: 3 minute)

Fisier: /etc/nut/upssched.conf pe pvemini

Linia relevanta:

AT ONBATT * START-TIMER onbatt 180

Valoarea 180 = secunde (3 minute). Exemple:

• 180 = 3 minute
• 300 = 5 minute
• 600 = 10 minute

Pentru a modifica:

# Editare manuala
nano /etc/nut/upssched.conf

# Sau comanda directa (exemplu: 5 minute)
sed -i 's/START-TIMER onbatt [0-9]*/START-TIMER onbatt 300/' /etc/nut/upssched.conf

# Restart serviciu pentru a aplica
systemctl restart nut-monitor

Adăugare noduri noi în cluster

Editează /usr/local/bin/ups-shutdown-cluster.sh:

# Adaugă IP-ul noului nod
NODES=("10.0.20.200" "10.0.20.202" "10.0.20.XXX")

Backup și Restore

Backup configurație

# De pe stația locală
cd /path/to/ROMFASTSQL/proxmox/ups

# Backup configurație
ssh root@10.0.20.201 "tar czf /tmp/nut-backup.tar.gz /etc/nut/*.conf /usr/local/bin/ups*.sh /usr/local/bin/upssched-cmd"
scp root@10.0.20.201:/tmp/nut-backup.tar.gz ./nut-backup-$(date +%Y%m%d).tar.gz

Restore configurație

# Extrage backup
tar xzf nut-backup-YYYYMMDD.tar.gz

# Copiază pe server
scp -r etc/nut/* root@10.0.20.201:/etc/nut/
scp usr/local/bin/* root@10.0.20.201:/usr/local/bin/

# Restart servicii
ssh root@10.0.20.201 "systemctl restart nut-server nut-monitor"

Securitate

Parole

IMPORTANT: Schimbă parolele default!

ssh root@10.0.20.201
nano /etc/nut/upsd.users

# Schimbă "parola99" cu ceva sigur
# Apoi restart:
systemctl restart nut-server

Firewall

NUT portul 3493 trebuie accesibil din rețea locală. Dacă ai firewall:

# Permite port 3493 din subnet local
iptables -A INPUT -p tcp --dport 3493 -s 10.0.20.0/24 -j ACCEPT

Suport și Documentație

• NUT Official: https://networkupstools.org/
• NUT Documentation: https://networkupstools.org/docs/user-manual.chunked/
• Hardware Compatibility: https://networkupstools.org/stable-hcl.html
• WinNUT GitHub: https://github.com/gawindx/WinNUT-V2

Notificări Email

Sistemul trimite notificări email via PVE::Notify pentru toate evenimentele importante:

Eveniment	Când	Severity
ONBATT	UPS trece pe baterie	warning
ONLINE	Curentul revine	info
LOWBATT	Baterie critică	error
SHUTDOWN_START	Începe shutdown cluster	error
SHUTDOWN_NODE	Shutdown nod secundar (pentru fiecare)	error
SHUTDOWN_PRIMARY	Shutdown nod primary (ultimul)	error
COMMBAD	Comunicație pierdută cu UPS	warning

Configurare: Email-urile folosesc notificările Proxmox existente. Verifică că ai configurat un target email în Datacenter → Notifications.

Template-uri: /etc/pve/notification-templates/default/ups-power-event-*

Funcționalități Complete

✅ Shutdown Orchestrat Automat

• Detectare întrerupere curent (3 minute grace period)
• Oprire ordonată: VM-uri/LXC → noduri secundare → nod primary
• Oprire automată UPS după shutdown (protecție power surge)
• Notificări email la fiecare pas

✅ Test Lunar Automat Baterie (NOU!)

• Rulare automată pe 1 ale lunii la 00:00
• Test real capacitate baterie (comutare pe baterie ~10 secunde)
• Evaluare sănătate: EXCELLENT/GOOD/FAIR/POOR
• Rapoarte HTML + email prin PVE::Notify
• Recomandări automate pentru înlocuire baterie
• Log detaliat istoric teste

✅ Monitorizare Continuă

• WinNUT pe VM 201 (Windows 11) pentru vizualizare real-time
• NUT server pe pvemini expune date la toate nodurile
• Logging complet evenimente și teste

✅ Mentenanță Baterie (NOU!)

• Script automat shutdown orchestrat pentru înlocuire baterie
• Procedură pas-cu-pas completă cu checklist-uri
• Recovery procedures pentru probleme comune
• Documentație: docs/UPS-BATTERY-REPLACEMENT.md

Autori și Istoric

• Creat: 2025-10-06
• Versiune: 1.2
• Ultima modificare: 2026-01-13
• Autor: Configurat automat via Claude Code
• Changelog:
  • v1.2 (2026-01-13): Adăugat notificări email pentru toate evenimentele UPS + oprire automată UPS
  • v1.1 (2025-10-06): Adăugat test lunar automat baterie cu notificări PVE::Notify
  • v1.0 (2025-10-06): Release inițial cu shutdown orchestrat și monitorizare NUT

Licență

Documentația și scripturile sunt furnizate "as-is" fără garanție. NUT și WinNUT sunt software open-source cu licențele lor respective.