# Instalare și Configurare NUT (Network UPS Tools) pe Proxmox

## Despre

Acest ghid descrie instalarea și configurarea NUT (Network UPS Tools) pe un cluster Proxmox pentru monitorizare UPS și shutdown orchestrat automat.

## Arhitectură

- **Nod PRIMARY (pvemini - 10.0.20.201):** Are UPS-ul conectat fizic via USB, rulează NUT server și driver
- **Noduri SECONDARY (pve1, pve2):** Pot monitoriza UPS-ul prin rețea (opțional)
- **VM 201 (Windows 11):** Monitorizare vizuală prin WinNUT client

## Prerequisite

- Proxmox VE instalat
- UPS conectat via USB la nodul primary
- Acces root la noduri

## 1. Instalare NUT pe Nodul PRIMARY

### 1.1. Instalare pachete

```bash
apt update
apt install -y nut nut-client nut-server
```

### 1.2. Detectare UPS

```bash
# Listează dispozitive USB
lsusb

# Exemple output:
# Bus 001 Device 002: ID 0665:5161 Cypress Semiconductor USB to Serial

# Verifică dacă kernel-ul a detectat UPS-ul
dmesg | grep -i ups
dmesg | grep -i hid
```

### 1.3. Testare driver NUT

```bash
# Caută driver potrivit pentru UPS-ul tău
nut-scanner -U

# sau
nut-scanner --usb_scan
```

## 2. Configurare NUT

### 2.1. Configurare Driver UPS (`/etc/nut/ups.conf`)

Creează configurația pentru UPS:

```bash
cat > /etc/nut/ups.conf << 'EOF'
[nutdev1]
    driver = nutdrv_qx
    port = auto
    vendorid = 0665
    productid = 5161
    subdriver = cypress
    desc = "UPS Cypress via USB"
EOF
```

**Note:**
- Înlocuiește `vendorid` și `productid` cu valorile de la `lsusb`
- Driver-ul `nutdrv_qx` funcționează pentru majoritatea UPS-urilor Voltronic/Megatec/Q1
- Alte drivere comune: `usbhid-ups`, `blazer_usb`, `nutdrv_qx`

### 2.2. Configurare Server NUT (`/etc/nut/upsd.conf`)

```bash
cat >> /etc/nut/upsd.conf << 'EOF'

# Ascultă pe localhost pentru monitorul local
LISTEN 127.0.0.1 3493

# Ascultă pe IP-ul nodului pentru clienți din rețea
LISTEN 10.0.20.201 3493
EOF
```

**Note:**
- Înlocuiește `10.0.20.201` cu IP-ul nodului tău PRIMARY
- Portul default NUT este 3493

### 2.3. Configurare Utilizatori (`/etc/nut/upsd.users`)

```bash
cat > /etc/nut/upsd.users << 'EOF'
[admin]
    password = parola99
    actions = SET
    instcmds = ALL
    upsmon master
EOF
```

**IMPORTANT:** Schimbă parola `parola99` cu ceva sigur!

### 2.4. Configurare Monitor Local (`/etc/nut/upsmon.conf`)

Editează `/etc/nut/upsmon.conf` și adaugă:

```bash
# Monitorizare UPS local
MONITOR nutdev1@localhost 1 admin parola99 master

# Folosește upssched pentru notificări
NOTIFYCMD /usr/sbin/upssched

# Activează notificările cu EXEC pentru evenimente
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
NOTIFYFLAG COMMOK SYSLOG+WALL+EXEC
NOTIFYFLAG COMMBAD SYSLOG+WALL+EXEC
```

**Note:**
- `master` = acest nod controlează UPS-ul (va fi ultimul care se închide)
- `1` = powervalue (câte surse de alimentare alimentează acest UPS)

### 2.5. Configurare NUT Mode (`/etc/nut/nut.conf`)

```bash
cat > /etc/nut/nut.conf << 'EOF'
MODE=netserver
EOF
```

Moduri disponibile:
- `none` - NUT dezactivat
- `standalone` - Doar local, fără rețea
- `netserver` - Server + local (recomandat pentru PRIMARY)
- `netclient` - Doar client (pentru noduri SECONDARY)

## 3. Pornire Servicii

### 3.1. Pornire driver UPS

```bash
upsdrvctl start
```

Ar trebui să vezi:
```
Network UPS Tools - UPS driver controller 2.8.0
Network UPS Tools - Megatec/Q1 protocol USB driver 0.32 (2.8.0)
Using subdriver: Cypress 0.10
```

### 3.2. Pornire server NUT

```bash
systemctl enable nut-server
systemctl start nut-server
systemctl status nut-server
```

### 3.3. Pornire monitor NUT

```bash
systemctl enable nut-monitor
systemctl start nut-monitor
systemctl status nut-monitor
```

## 4. Verificare Funcționare

### 4.1. Test status UPS

```bash
# Listează UPS-uri disponibile
upsc -l

# Afișează toate informațiile despre UPS
upsc nutdev1

# Doar status
upsc nutdev1 ups.status

# Baterie
upsc nutdev1 battery.charge
upsc nutdev1 battery.voltage

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

### 4.2. Verificare conexiuni

```bash
# Verifică dacă upsd ascultă pe portul 3493
ss -tulpn | grep 3493

# Ar trebui să vezi:
# tcp LISTEN 0 16 127.0.0.1:3493 0.0.0.0:*
# tcp LISTEN 0 16 10.0.20.201:3493 0.0.0.0:*
```

### 4.3. Test de pe alt sistem

```bash
# De pe un alt nod sau sistem:
upsc nutdev1@10.0.20.201
```

## 5. Configurare Scheduler Evenimente (upssched)

### 5.1. Creare `/etc/nut/upssched.conf`

```bash
cat > /etc/nut/upssched.conf << 'EOF'
CMDSCRIPT /usr/local/bin/upssched-cmd
PIPEFN /run/nut/upssched.pipe
LOCKFN /run/nut/upssched.lock

# UPS pe baterie - așteaptă 180 secunde (3 minute)
AT ONBATT * START-TIMER onbatt 180

# Baterie scăzută - acțiune imediată
AT LOWBATT * EXECUTE lowbatt

# Curent revenit - anulează timer
AT ONLINE * CANCEL-TIMER onbatt

# Comunicație pierdută - așteaptă 30 secunde
AT COMMBAD * START-TIMER commbad 30

# Comunicație restabilită
AT COMMOK * CANCEL-TIMER commbad
EOF
```

### 5.2. Creare handler script

Copiază scriptul `upssched-cmd` din directorul `scripts/` în `/usr/local/bin/`:

```bash
cp scripts/upssched-cmd /usr/local/bin/
chmod +x /usr/local/bin/upssched-cmd
```

### 5.3. Creare director runtime

```bash
mkdir -p /run/nut
chown nut:nut /run/nut
chmod 770 /run/nut
```

## 6. Instalare Scripturi Shutdown Orchestrat

### 6.1. Copiere scripturi

```bash
# Script principal de shutdown
cp scripts/ups-shutdown-cluster.sh /usr/local/bin/
chmod +x /usr/local/bin/ups-shutdown-cluster.sh

# Script de test (dry-run)
cp scripts/ups-shutdown-test.sh /usr/local/bin/
chmod +x /usr/local/bin/ups-shutdown-test.sh
```

### 6.2. Editare noduri în script

Editează `/usr/local/bin/ups-shutdown-cluster.sh` și verifică:

```bash
NODES=("10.0.20.200" "10.0.20.202")  # IP-urile nodurilor SECONDARY
```

### 6.3. Configurare SSH între noduri

Pentru ca scriptul să funcționeze, trebuie ca nodul PRIMARY să poată face SSH pe nodurile SECONDARY fără parolă:

```bash
# Generează SSH key dacă nu există
ssh-keygen -t ed25519 -N "" -f /root/.ssh/id_ed25519

# Copiază cheia pe nodurile SECONDARY
ssh-copy-id root@10.0.20.200
ssh-copy-id root@10.0.20.202

# Test conexiune
ssh root@10.0.20.200 "hostname"
ssh root@10.0.20.202 "hostname"
```

## 7. Testare

### 7.1. Test dry-run

```bash
/usr/local/bin/ups-shutdown-test.sh
cat /var/log/ups-shutdown-test.log
```

### 7.2. Test simulare UPS pe baterie (ATENȚIE!)

**⚠️ PERICOL:** Acest test va iniția shutdown real dacă îl lași să ruleze 3 minute!

```bash
# Monitorizează logs
tail -f /var/log/ups-events.log &

# Deconectează fizic UPS-ul de la priză
# Așteaptă 10-30 secunde
# Verifică că logs-urile arată "ONBATT"
# RECONECTEAZĂ UPS-ul înainte de 3 minute!

# Verifică că timer-ul a fost anulat
journalctl -u nut-monitor -f
```

## 8. Troubleshooting

### 8.1. Driver-ul nu pornește

```bash
# Verifică permisiuni USB
ls -la /dev/bus/usb/*/*

# Driver manual cu debug
/lib/nut/nutdrv_qx -a nutdev1 -DDDDD

# Verifică logs
journalctl -u nut-driver@nutdev1 -f
```

### 8.2. Server nu pornește

```bash
# Verifică configurația
upsd -c reload

# Debug mode
upsd -D

# Logs
journalctl -u nut-server -f
```

### 8.3. Monitor nu se conectează

```bash
# Verifică parola în upsd.users
cat /etc/nut/upsd.users

# Verifică MONITOR line în upsmon.conf
grep "^MONITOR" /etc/nut/upsmon.conf

# Test manual
upsmon -D
```

### 8.4. UPS nu răspunde

```bash
# Reload driver
upsdrvctl stop
upsdrvctl start

# Verifică comunicația USB
lsusb -v -d 0665:5161
```

## 9. Logs și Monitorizare

### Logs importante:

```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
journalctl -u nut-driver@nutdev1 # Driver UPS
```

### Comenzi utile:

```bash
# Status complet UPS
upsc nutdev1

# Comenzi disponibile
upscmd -l nutdev1

# Variabile disponibile
upsc nutdev1 | grep -E "battery|input|output|ups.status"

# Monitorizare în timp real
watch -n 2 'upsc nutdev1 ups.status battery.charge input.voltage'
```

## 10. Întreținere

### Zilnic/Săptămânal:
```bash
# Verifică status UPS
upsc nutdev1 ups.status battery.charge

# Verifică servicii
systemctl status nut-server nut-monitor
```

### Lunar:
```bash
# Test dry-run
/usr/local/bin/ups-shutdown-test.sh

# Test fizic (deconectare scurtă < 1 min)
```

### Anual:
```bash
# Test complet de baterie pe UPS
# Backup înainte de test!
```

## Referințe

- Documentație oficială NUT: https://networkupstools.org/
- Lista drivere compatibile: https://networkupstools.org/stable-hcl.html
- NUT Users Manual: https://networkupstools.org/docs/user-manual.chunked/index.html
- Troubleshooting Guide: https://networkupstools.org/docs/user-manual.chunked/ar01s07.html