romfast/ROMFASTSQL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add complete UPS monitoring system with monthly battery testing

Browse Source 
This commit adds a comprehensive UPS monitoring and management system for
the Proxmox cluster with automated shutdown orchestration and monthly
battery health testing.

Features:
- NUT (Network UPS Tools) configuration for INNO TECH USB UPS
- Automated cluster shutdown on power failure (3-minute grace period)
- Monthly automated battery testing with health evaluation
- Email notifications via PVE::Notify system
- WinNUT monitoring client for Windows VM 201

Components added:
- config/: NUT configuration files (ups.conf, upsd.conf, upsmon.conf, etc.)
- scripts/ups-shutdown-cluster.sh: Orchestrated cluster shutdown
- scripts/ups-monthly-test.sh: Monthly battery test with email reports
- scripts/upssched-cmd: Event handler for UPS state changes
- docs/: Complete installation and usage documentation

Key findings:
- UPS battery.charge reporting has 10-40 second delay after test start
- Test must monitor voltage drop (1.5-2V) and charge drop (9-27%)
- Battery health evaluation: EXCELLENT/GOOD/FAIR/POOR based on discharge rate
- Email notifications use Handlebars templates without Unicode emojis for compatibility

Configuration:
- UPS: INNO TECH (Voltronic protocol, vendor 0665:5161)
- Primary node: pvemini (10.0.20.201) with USB connection
- Monthly test: cron 0 0 1 * * /opt/scripts/ups-monthly-test.sh
- Shutdown timer: 180 seconds on battery before cluster shutdown

Documentation includes complete installation guides for NUT server,
WinNUT client, and troubleshooting procedures.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marius
2025-10-06 21:39:46 +03:00
parent 238c02fdf0
commit 87b9709a0d
14 changed files with 3292 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

470
proxmox/ups/docs/UPS-MONTHLY-TEST.md Normal file
View File

@@ -0,0 +1,470 @@
# Test Lunar Automat Baterie UPS
## Despre
Script automat pentru testarea lunară a bateriei UPS care rulează pe data de 1 a fiecărei luni la ora 00:00. Testul verifică capacitatea reală a bateriei prin comutare pe baterie și monitorizare descărcare/recuperare.
## Funcționalitate
### Ce face scriptul:
1. **Verificare status UPS** înainte de test
- Battery charge, voltage
- Input/output voltage
- Load %
- Verifică că UPS este Online
2. **Rulare test baterie automat**
- Comandă: `upscmd nutdev1 test.battery.start.quick`
- UPS comută pe baterie pentru ~10 secunde
- Descarcă efectiv bateria pentru testare reală
3. **Monitorizare în timp real** (30 secunde)
- Status UPS
- Battery charge %
- Battery voltage
- Detectare anomalii
4. **Analiză rezultate**
- Calculează scăderea încărcării (%)
- Calculează scăderea tensiunii (V)
- Evaluează sănătatea bateriei
5. **Monitorizare recuperare** (5 minute)
- Urmărește reîncărcarea bateriei
- Calculează rata de recuperare
- Oprește când bateria > 95%
6. **Generare rapoarte**
- Raport HTML detaliat cu grafice
- Raport text pentru email
- Log detaliat în `/var/log/ups-monthly-test.log`
7. **Notificare email**
- Trimite raport prin sistemul de notificări Proxmox
- Include sănătatea bateriei în subject
- Rapoarte salvate în `/tmp/ups-test-YYYYMM/`
## Evaluare Sănătate Baterie
Scriptul evaluează sănătatea bateriei bazat pe scăderea încărcării în timpul testului:
| Scădere Încărcare | Sănătate | Status | Acțiune Necesară |
|-------------------|----------|--------|------------------|
| < 10% | **EXCELLENT** | ✅ Verde | Nicio acțiune necesară |
| 10-30% | **GOOD** | ✅ Verde | Continuă monitorizarea |
| 30-50% | **FAIR** | ⚠️ Galben | Planifică înlocuire în 3-6 luni |
| > 50% | **POOR** | 🔴 Roșu | **URGENT: Înlocuiește bateria!** |
### Exemple de rezultate reale:
**Test 1 (2025-10-06 20:45):**
- Scădere încărcare: 0% (charge reporting delay)
- Scădere tensiune: 1.64V (27.88V → 26.24V)
- Evaluare: **EXCELLENT**
- Recuperare: 30 secunde la 100%
**Notă:** UPS-ul raportează uneori încărcarea cu întârziere. Scăderea tensiunii este un indicator mai precis al capacității bateriei.
## Instalare
### 1. Copiere script pe server
```bash
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"
```
### 2. Configurare cron
Script-ul se adaugă automat în cron la instalare, dar poți verifica:
```bash
ssh root@10.0.20.201 "crontab -l | grep ups-monthly-test"
```
Ar trebui să vezi:
```
# UPS Monthly Battery Test - Rulează pe 1 ale lunii la 00:00
0 0 1 * * /opt/scripts/ups-monthly-test.sh
```
### 3. Test manual (recomandat înainte de prima rulare lunară)
```bash
ssh root@10.0.20.201 "/opt/scripts/ups-monthly-test.sh"
```
**ATENȚIE:** Testul va comuta UPS-ul pe baterie pentru ~10 secunde!
## Configurare
### Parametri editabili în script:
```bash
UPS_NAME="nutdev1" # Numele UPS-ului din NUT
UPS_USER="admin" # Username pentru comenzi NUT
UPS_PASS="parola99" # Parola pentru comenzi NUT
MAIL_TO="root@pam" # Destinatar email rapoarte
```
### Personalizare cron:
Pentru a schimba data/ora de rulare, editează cron:
```bash
ssh root@10.0.20.201
crontab -e
```
Exemple:
```bash
# Rulează pe 1 ale lunii la 02:00 (noapte)
0 2 1 * * /opt/scripts/ups-monthly-test.sh
# Rulează în fiecare Duminică la 00:00 (săptămânal)
0 0 * * 0 /opt/scripts/ups-monthly-test.sh
# Rulează pe 15 ale lunii la 00:00 (mijloc de lună)
0 0 15 * * /opt/scripts/ups-monthly-test.sh
```
## Rapoarte Generate
### 1. Raport HTML
**Locație:** `/tmp/ups-test-YYYYMM/ups-test-report.html`
Conține:
- Header cu data, UPS, nod
- Status sănătate baterie (color-coded)
- Metrici în grid layout:
- Încărcare înainte/după
- Tensiune înainte/după
- Scădere încărcare
- Recuperare în 5 min
- Tabel detalii tehnice
- Recomandări bazate pe sănătate
- Footer cu timestamp și paths
### 2. Raport Text
**Locație:** `/tmp/ups-test-YYYYMM/ups-test-report.txt`
Versiune text simplă pentru email.
### 3. Log Detaliat
**Locație:** `/var/log/ups-monthly-test.log`
Log complet cu toate măsurătorile:
- Timestamp pentru fiecare pas
- Status UPS în timp real
- Toate valorile măsurate
- Erori sau warnings
**Păstrare:** Log-ul este append-only, conține istoric complet al tuturor testelor.
## Logs și Monitorizare
### Vizualizare log în timp real:
```bash
ssh root@10.0.20.201 "tail -f /var/log/ups-monthly-test.log"
```
### Verificare ultimul test:
```bash
ssh root@10.0.20.201 "tail -50 /var/log/ups-monthly-test.log"
```
### Căutare teste anterioare:
```bash
# Caută toate testele din 2025
ssh root@10.0.20.201 "grep 'UPS MONTHLY BATTERY TEST - START' /var/log/ups-monthly-test.log | grep 2025"
# Vezi rezultatul ultimului test
ssh root@10.0.20.201 "grep 'Sănătate baterie:' /var/log/ups-monthly-test.log | tail -1"
```
### Verificare cron execution:
```bash
# Verifică că cron a rulat scriptul
ssh root@10.0.20.201 "grep ups-monthly-test /var/log/syslog"
```
## Email Notifications
### Configurare sistem de mail
Scriptul încearcă să trimită email prin:
1. **mail command** (recomandat)
2. **logger** (fallback - doar în syslog)
#### Instalare mail command (dacă nu există):
```bash
ssh root@10.0.20.201 "apt update && apt install -y mailutils"
```
#### Configurare SMTP pentru Proxmox:
Editează `/etc/postfix/main.cf`:
```bash
relayhost = smtp.gmail.com:587
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = encrypt
```
Creează `/etc/postfix/sasl_passwd`:
```
smtp.gmail.com:587 your-email@gmail.com:your-app-password
```
Apoi:
```bash
postmap /etc/postfix/sasl_passwd
chmod 600 /etc/postfix/sasl_passwd*
systemctl restart postfix
```
#### Test email:
```bash
echo "Test email from UPS monitoring" | mail -s "Test" root@pam
```
### Verificare email trimis:
```bash
# Verifică mail queue
ssh root@10.0.20.201 "mailq"
# Verifică mail logs
ssh root@10.0.20.201 "grep 'UPS' /var/log/mail.log"
```
## Troubleshooting
### Testul nu pornește
**Verificare:**
```bash
# UPS online?
upsc nutdev1 ups.status
# Comenzi disponibile?
upscmd -l nutdev1 | grep battery
# Autentificare corectă?
upscmd -u admin -p parola99 nutdev1 test.battery.start.quick
```
### Bateria nu se descarcă în test
**Cauze posibile:**
- UPS-ul nu suportă test real (unele modele low-end)
- Test prea scurt pentru a fi detectat
- Baterie foarte sănătoasă (scădere < 1%)
**Verificare:**
```bash
# Monitorizează tensiune în loc de charge
watch -n 1 'upsc nutdev1 battery.voltage'
# Apoi rulează test manual și observă scăderea
upscmd -u admin -p parola99 nutdev1 test.battery.start.quick
```
### Email nu ajunge
**Verificări:**
```bash
# Mail command instalat?
which mail
# Postfix rulează?
systemctl status postfix
# Verifică logs
tail -50 /var/log/mail.log
# Test manual
echo "Test" | mail -s "Test Subject" root@pam
```
### Script blochează sau timeout
**Cauze:**
- Testul baterie durează prea mult
- UPS nu răspunde
- Probleme rețea
**Soluție:**
Editează scriptul și reduce timeout-urile:
```bash
# Reduce monitorizare de la 15 la 5 iterații
for i in {1..5}; do
```
## Întreținere
### Lunar (După Rulare Automată)
```bash
# Verifică că testul a rulat
ssh root@10.0.20.201 "tail -100 /var/log/ups-monthly-test.log | grep 'COMPLETE'"
# Vezi rezultatul
ssh root@10.0.20.201 "grep 'Sănătate baterie' /var/log/ups-monthly-test.log | tail -1"
# Verifică raportul HTML
ssh root@10.0.20.201 "ls -lh /tmp/ups-test-*/ups-test-report.html"
```
### Anual
```bash
# Cleanup rapoarte vechi (> 12 luni)
ssh root@10.0.20.201 "find /tmp/ups-test-* -type d -mtime +365 -exec rm -rf {} +"
# Rotare log dacă devine prea mare (> 100MB)
ssh root@10.0.20.201 "
if [ \$(stat -f%z /var/log/ups-monthly-test.log) -gt 104857600 ]; then
mv /var/log/ups-monthly-test.log /var/log/ups-monthly-test.log.old
gzip /var/log/ups-monthly-test.log.old
fi
"
```
### La Înlocuire Baterie
După înlocuirea bateriei UPS:
```bash
# Rulează test manual pentru baseline
ssh root@10.0.20.201 "/opt/scripts/ups-monthly-test.sh"
# Verifică că rezultatul este EXCELLENT
ssh root@10.0.20.201 "tail -20 /var/log/ups-monthly-test.log"
# Notează data înlocuirii în log
ssh root@10.0.20.201 "echo '[$(date)] Baterie UPS înlocuită - baseline test executat' >> /var/log/ups-monthly-test.log"
```
## Interpretare Rezultate
### Exemplu rezultat bun:
```
Sănătate baterie: EXCELLENT
Scădere încărcare: 5%
Scădere tensiune: 1.64V
Recuperare: 5% în 30 secunde
```
**Interpretare:** Baterie în stare excelentă, poate susține sarcina, se reîncarcă rapid.
### Exemplu rezultat acceptabil:
```
Sănătate baterie: FAIR
Scădere încărcare: 35%
Scădere tensiune: 4.2V
Recuperare: 15% în 120 secunde
```
**Interpretare:** Baterie uzată, planifică înlocuire în 3-6 luni.
### Exemplu rezultat critic:
```
Sănătate baterie: POOR
Scădere încărcare: 65%
Scădere tensiune: 8.5V
Recuperare: 25% în 300 secunde
```
**Interpretare:** **URGENT!** Baterie critică, înlocuiește imediat! Risc mare de shutdown neplanificat.
## Recomandări Baterie
### Când să înlocuiești bateria:
| Indicator | Bun | Acceptabil | Critic |
|-----------|-----|------------|--------|
| **Vârstă baterie** | < 2 ani | 2-4 ani | > 4 ani |
| **Scădere încărcare** | < 10% | 10-50% | > 50% |
| **Scădere tensiune** | < 2V | 2-5V | > 5V |
| **Timp recuperare** | < 1 min | 1-5 min | > 5 min |
| **Teste failed** | 0 | 1-2 | > 3 |
### Factori care afectează durata de viață:
- **Temperatură:** Ideal 20-25°C (fiecare +10°C reduce durata cu 50%)
- **Cicluri descărcare:** < 20 cicluri/an = bun
- **Profunzime descărcare:** Descărcări până la 50% = OK, sub 20% = deteriorare
- **Calitate baterie:** Baterii branded (APC, Eaton) vs. generice
## Automatizare Avansată
### Alertare automată când bateria devine POOR:
Adaugă în script (după evaluarea sănătății):
```bash
if [ "$BATTERY_HEALTH" == "POOR" ]; then
# Trimite alert urgent
echo "URGENT: Bateria UPS necesită înlocuire!" | \
mail -s "🔴 ALERT UPS: Baterie CRITICĂ!" admin@company.com
# Notificare SMS (dacă ai configurat)
curl -X POST "https://api.service.com/sms" \
-d "to=+40xxxxxxxxx&message=ALERT: Baterie UPS critica!"
fi
```
### Integrare cu Prometheus/Grafana:
Exportă metrici pentru monitorizare long-term:
```bash
# La final de script, exportă metrici
cat >> /var/lib/node_exporter/textfile_collector/ups_battery.prom << EOF
# HELP ups_battery_health Battery health score (0-100)
# TYPE ups_battery_health gauge
ups_battery_health{ups="nutdev1"} $(( 100 - CHARGE_DROP ))
# HELP ups_battery_charge_drop Battery charge drop during test
# TYPE ups_battery_charge_drop gauge
ups_battery_charge_drop{ups="nutdev1"} $CHARGE_DROP
# HELP ups_battery_test_timestamp Last battery test timestamp
# TYPE ups_battery_test_timestamp gauge
ups_battery_test_timestamp{ups="nutdev1"} $(date +%s)
EOF
```
## Referințe
- **NUT Commands:** https://networkupstools.org/docs/user-manual.chunked/ar01s07.html
- **Battery Testing Best Practices:** https://www.apc.com/us/en/faqs/FAQ000267818/
- **Proxmox Notifications:** https://pve.proxmox.com/wiki/Notifications
## Istoric Versiuni
- **v1.0** (2025-10-06)
- Release inițial
- Test automat baterie cu `test.battery.start.quick`
- Rapoarte HTML și text
- Email notifications
- Cron lunar (1 ale lunii)
- Evaluare sănătate baterie (4 nivele)
- Monitorizare recuperare 5 minute
---
**Autor:** Claude Code
**Ultima actualizare:** 2025-10-06