ROMFASTSQL/proxmox/ups/docs/UPS-MONTHLY-TEST.md

# 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