# Documentație Sistem UPS Shutdown Orchestrat

## Configurare Completă

### Hardware
- **UPS:** INNO TECH USB to Serial (ID: 0665:5161)
- **Conectat la:** pvemini (10.0.20.201) - via USB
- **Cluster Proxmox:**
  - pvemini (10.0.20.201) - PRIMARY (are UPS-ul conectat)
  - pve1 (10.0.20.200) - SECONDARY
  - pve2 (10.0.20.202) - SECONDARY

### Software
- **NUT (Network UPS Tools)** versiunea 2.8.0
- **WinNUT** pe VM 201 (Windows 11) pentru monitorizare vizuală

### Fișiere de Configurare

#### 1. /etc/nut/ups.conf
Configurează driver-ul pentru UPS:
```
[nutdev1]
    driver = nutdrv_qx
    port = auto
    vendorid = 0665
    productid = 5161
    subdriver = cypress
    desc = "UPS Cypress via USB"
```

#### 2. /etc/nut/upsd.conf
Server NUT - ascultă pe localhost și rețea:
```
LISTEN 127.0.0.1 3493
LISTEN 10.0.20.201 3493
```

#### 3. /etc/nut/upsd.users
Utilizatori autorizați:
```
[admin]
    password = parola99
    actions = SET
    instcmds = ALL
    upsmon master
```

#### 4. /etc/nut/upsmon.conf
Monitor local:
```
MONITOR nutdev1@localhost 1 admin parola99 master
NOTIFYCMD /usr/sbin/upssched
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
```

#### 5. /etc/nut/upssched.conf
Scheduler pentru evenimente:
- **ONBATT:** Notificare email imediată + așteaptă 180 secunde (3 minute) înainte de shutdown
- **LOWBATT:** Shutdown imediat + notificare email
- **ONLINE:** Anulează timer-ele + notificare email "curent revenit"

### Scripturi Create

#### 1. /usr/local/bin/ups-shutdown-cluster.sh
**Script principal de shutdown orchestrat**

Ordinea de operații:
1. Verifică status UPS (trebuie OB sau LB)
2. **📧 Email: "Shutdown cluster PORNIT"**
3. Oprește toate VM-urile și LXC de pe toate nodurile (paralel)
4. Așteaptă 90 secunde pentru oprire graceful
5. Shutdown pve1 → **📧 Email: "Shutdown pve1 trimis"**
6. Shutdown pveelite → **📧 Email: "Shutdown pveelite trimis"**
7. Așteaptă 60 secunde
8. **📧 Email: "Shutdown pvemini (ULTIMUL NOD)"**
9. Comandă UPS shutdown (oprire completă UPS)
10. Shutdown pvemini (primary - ultimul)

Logare: `/var/log/ups-shutdown.log` + `journalctl -t ups-shutdown`

#### 2. /usr/local/bin/ups-shutdown-test.sh
**Script de test (DRY RUN) - NU oprește nimic**

Folosește-l pentru a testa:
```bash
/usr/local/bin/ups-shutdown-test.sh
tail -f /var/log/ups-shutdown-test.log
```

#### 3. /usr/local/bin/upssched-cmd
**Handler pentru evenimente UPS** - trimite notificări email via PVE::Notify

| Eveniment | Acțiune | Email |
|-----------|---------|-------|
| `onbatt_start` | UPS trece pe baterie | "Trecere pe baterie - Timer 3 min" |
| `onbatt` | Timer 3 min expirat | "Pe baterie 3 min - SHUTDOWN" + lansare shutdown |
| `online` | Curent revenit | "Curent revenit - OK" |
| `lowbatt` | Baterie critică | "BATERIE CRITICĂ" + shutdown imediat |
| `commbad` | Comunicație pierdută | "Comunicație pierdută cu UPS" |

Logare: `/var/log/ups-events.log`

## Testare și Verificare

### Verificare Status UPS
```bash
# Status general
upsc nutdev1

# Doar status
upsc nutdev1 ups.status

# Baterie
upsc nutdev1 battery.charge

# Tensiuni
upsc nutdev1 input.voltage output.voltage
```

### Verificare Servicii
```bash
systemctl status nut-server
systemctl status nut-monitor
journalctl -u nut-server -f
journalctl -u nut-monitor -f
```

### Test Manual Shutdown (DRY RUN)
```bash
/usr/local/bin/ups-shutdown-test.sh
```

### Test Simulare UPS pe Baterie
**⚠️ ATENȚIE: Acest test va iniția shutdown real dacă îl lași 3 minute!**
```bash
# Deconectează fizic UPS-ul de la priză pentru 30 secunde
# Monitorizează logs:
tail -f /var/log/ups-events.log

# Reconectează înainte de 3 minute pentru a anula shutdown-ul
```

## Monitorizare din WinNUT (VM 201)

### Conexiune
- **Server:** 10.0.20.201
- **Port:** 3493
- **UPS Name:** nutdev1
- **Username:** admin
- **Password:** parola99
- **Polling Interval:** 15 secunde

### Ce Vezi în WinNUT
- Input/Output Voltage
- Frequency
- Battery Charge (%)
- Battery Voltage
- UPS Load (%)
- UPS Status (Online/On Battery/Low Battery)

## Scenarii de Funcționare

### Scenario 1: Întrerupere Scurtă (< 3 minute)
1. Curent se întrerupe → UPS trece pe baterie
2. **📧 Email: "Trecere pe baterie"**
3. Timer de 180 secunde pornește
4. Curent revine → Timer anulat
5. **📧 Email: "Curent revenit - OK"**
6. **Rezultat:** Niciun sistem nu se oprește

### Scenario 2: Întrerupere Lungă (> 3 minute)
1. Curent se întrerupe → UPS trece pe baterie
2. **📧 Email: "Trecere pe baterie"**
3. Timer 180 secunde expiră
4. **📧 Email: "Pe baterie 3 min - SHUTDOWN"**
5. Script de shutdown pornește:
   - **📧 Email: "Shutdown cluster PORNIT"**
   - VM-uri/LXC se opresc pe toate nodurile
   - După 90s: pve1 se oprește → **📧 Email**
   - pveelite se oprește → **📧 Email**
   - După 60s: **📧 Email: "Shutdown pvemini (ULTIMUL NOD)"**
   - UPS primește comandă shutdown
   - pvemini se oprește
6. **Rezultat:** Shutdown orchestrat complet + UPS oprit

### Scenario 3: Baterie Scăzută Imediată
1. UPS raportează LOWBATT
2. **📧 Email: "BATERIE CRITICĂ - SHUTDOWN IMEDIAT"**
3. Shutdown **IMEDIAT** (fără timer)
4. Același flux de shutdown orchestrat
5. **Rezultat:** Shutdown rapid pentru protecție + UPS oprit

## Loguri și Troubleshooting

### Fișiere de Log
```bash
/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)
journalctl -u nut-server        # Server NUT
journalctl -u nut-monitor       # Monitor NUT
```

### Comenzi Utile
```bash
# Liste conexiuni active la NUT
ss -tnp | grep :3493

# Test conectivitate de pe alt nod
ssh root@10.0.20.200 'upsc nutdev1@10.0.20.201'

# Restart servicii
systemctl restart nut-server nut-monitor
```

## Întreținere

### Verificare Săptămânală
```bash
# Status UPS
upsc nutdev1 ups.status battery.charge

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

# Verificare logs
tail -20 /var/log/ups-events.log
```

### Verificare Lunară
- Test fizic: deconectează UPS 30 secunde
- Verifică că WinNUT detectează schimbarea
- Verifică că logs arată evenimentul
- Reconectează înainte de 3 minute

## ⚠️ IMPORTANT

1. **Nu modifica** timpul de 3 minute fără consultare - trebuie să fie suficient pentru:
   - VM-uri să se oprească graceful
   - Noduri secundare să se închidă
   - pvemini să rămână ultimul funcțional

2. **Testează periodic** scriptul dry-run pentru a verifica că SSH funcționează între noduri

3. **Monitorizează** statusul bateriei UPS - înlocuiește bateria când charge devine sub 80%

4. **WinNUT** este doar pentru monitorizare - shutdown-ul este automat de pe Proxmox

## Contact și Suport
- Documentație NUT: https://networkupstools.org/
- Script creat: 2025-10-06
- Ultima modificare: 2026-01-13 (adăugat notificări email + UPS shutdown)