ROMFASTSQL/proxmox/ups/docs/UPS-SHUTDOWN-README.md

# 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:** Așteaptă 180 secunde (3 minute) înainte de shutdown
- **LOWBATT:** Shutdown imediat
- **ONLINE:** Anulează toate timer-ele

### 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. Oprește toate VM-urile de pe toate nodurile (paralel)
3. Așteaptă 90 secunde
4. Shutdown pve1 și pve2 (secundare)
5. Așteaptă 30 secunde
6. Shutdown pvemini (primary - ultimul)

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

#### 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**

Apelat automat de upssched când:
- UPS pe baterie 3 minute → lansează shutdown orchestrat
- Baterie scăzută → shutdown imediat
- Pierdere comunicație → doar logging

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. Timer de 180 secunde pornește
3. Curent revine → Timer anulat
4. **Rezultat:** Niciun sistem nu se oprește

### Scenario 2: Întrerupere Lungă (> 3 minute)
1. Curent se întrerupe → UPS trece pe baterie
2. Timer 180 secunde expiră
3. Scriptu de shutdown pornește:
   - VM-uri se opresc pe toate nodurile
   - După 90s: pve1, pve2 se opresc
   - După încă 30s: pvemini se oprește
4. **Rezultat:** Shutdown orchestrat complet

### Scenario 3: Baterie Scăzută Imediată
1. UPS raportează LOWBATT
2. Shutdown **IMEDIAT** (fără timer)
3. Același flux de shutdown orchestrat
4. **Rezultat:** Shutdown rapid pentru protecție

## 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: 2025-10-06