ROMFASTSQL/proxmox/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. upssched pornește timer de 180 secunde
3. Curent revine înainte de 3 minute
4. Timer anulat → Niciun sistem nu se oprește

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

1. Curent se întrerupe → UPS pe baterie
2. Timer 180 secunde expiră
3. /usr/local/bin/ups-shutdown-cluster.sh pornește:
   • Step 1: Oprește toate VM-urile de pe toate nodurile (paralel)
   • Step 2: Așteaptă 90 secunde pentru oprire graceful
   • Step 3: Shutdown pve1 și pve2 (noduri secundare)
   • Step 4: Așteaptă 30 secunde
   • Step 5: Shutdown pvemini (nod primary - ultimul)

Scenario 3: Baterie scăzută imediată

1. UPS raportează LOWBATT (baterie critică)
2. Shutdown IMEDIAT (fără timer)
3. 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 așteptare (default: 3 minute)

Editează /etc/nut/upssched.conf pe pvemini:

# Schimbă din 180 (3 min) la 300 (5 min)
AT ONBATT * START-TIMER onbatt 300

Apoi:

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

Funcționalități Complete

✅ Shutdown Orchestrat Automat

• Detectare întrerupere curent (3 minute grace period)
• Oprire ordonată: VM-uri → noduri secundare → nod primary
• Notificări în timp real prin upssched

✅ 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.1
• Ultima modificare: 2025-10-06
• Autor: Configurat automat via Claude Code
• Changelog:
  • 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.