ROMFASTSQL/proxmox/cluster/ups/docs/INSTALARE-NUT.md

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

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

1.2. Detectare UPS

# 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

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

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)

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)

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ă:

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

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

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

systemctl enable nut-server
systemctl start nut-server
systemctl status nut-server

3.3. Pornire monitor NUT

systemctl enable nut-monitor
systemctl start nut-monitor
systemctl status nut-monitor

4. Verificare Funcționare

4.1. Test status UPS

# 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

# 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

# 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

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

Copiaza scriptul upssched-cmd din directorul scripts/ in /usr/local/bin/:

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

5.3. Configurare sudo pentru user nut

Scripturile ruleaza ca user nut si au nevoie de sudo pentru a accesa PVE::Notify:

# Instaleaza sudo daca nu exista
apt-get install -y sudo

# Configureaza permisiuni sudo pentru user nut
cat > /etc/sudoers.d/nut << 'EOF'
nut ALL=(root) NOPASSWD: /usr/bin/perl
EOF
chmod 440 /etc/sudoers.d/nut

5.4. Configurare permisiuni fisiere log

Fisierele de log trebuie sa fie writable de user-ul nut:

touch /var/log/ups-events.log /var/log/ups-shutdown.log
chown nut:nut /var/log/ups-events.log /var/log/ups-shutdown.log
chmod 664 /var/log/ups-events.log /var/log/ups-shutdown.log

5.5. Creare director runtime

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

6. Instalare Scripturi Shutdown Orchestrat

6.1. Copiere scripturi

# 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ă:

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ă:

# 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

/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!

# 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

# 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

# Verifică configurația
upsd -c reload

# Debug mode
upsd -D

# Logs
journalctl -u nut-server -f

8.3. Monitor nu se conectează

# 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

# Reload driver
upsdrvctl stop
upsdrvctl start

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

9. Logs și Monitorizare

Logs importante:

/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:

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

# Verifică status UPS
upsc nutdev1 ups.status battery.charge

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

Lunar:

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

# Test fizic (deconectare scurtă < 1 min)

Anual:

# 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