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`](docs/UPS-SHUTDOWN-README.md)
   - Detalii NUT: [`docs/INSTALARE-NUT.md`](docs/INSTALARE-NUT.md)
   - WinNUT: [`docs/INSTALARE-WINNUT.md`](docs/INSTALARE-WINNUT.md)

2. **Verifică status UPS:**
   ```bash
   ssh root@10.0.20.201
   upsc nutdev1
   ```

3. **Test dry-run:**
   ```bash
   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ă

```bash
# 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:**
```bash
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`](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:**
   ```bash
   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

```bash
# 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`](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

```bash
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:**
   ```powershell
   Test-NetConnection -ComputerName 10.0.20.201 -Port 3493
   ```
3. **Verifică server:**
   ```bash
   ssh root@10.0.20.201 "ss -tulpn | grep 3493"
   ```

### Scriptul de shutdown nu funcționează

```bash
# 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

```bash
# 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:
```bash
# 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`:

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

## Backup și Restore

### Backup configurație

```bash
# 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

```bash
# 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!

```bash
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:

```bash
# 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`](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.