Skip to main content

🔋 Raspberry Pi NUT – Monitoring & Management Guide (Updated Architecture)

🎯 Objective

Provide a reliable CLI operational reference for monitoring and managing a Raspberry Pi running Network UPS Tools (NUT), whether configured as:

  • 🟢 Master (Server) — directly connected to UPS

  • 🔵 Client — monitoring a remote NUT server

This entry reflects real‑world diagnostics and includes commands for both modes.

🏗️ Architecture Modes

Mode A — Pi = NUT Master


UPS → Raspberry Pi → Clients

Pi reads UPS via USB and broadcasts events.

Mode B — Pi = NUT Client


UPS → Remote Server → Raspberry Pi

Pi monitors UPS state over network.

In this mode:


upsc ups@localhost ❌ (will fail)
upsc apc@SERVER_IP ✅

🔍 Determine Your Mode

Check config:


cat /etc/nut/nut.conf

Possible values:

Mode Meaning
netserver Pi is master
netclient Pi is client
standalone Local only

🔎 Service Status Checks


systemctl status nut-monitor
systemctl status nut-server

Interpretation:

Result Meaning
nut-server not found Client mode
nut-server active Master mode

📡 Query UPS Status (Correct Command)

If Pi is MASTER


upsc ups@localhost

If Pi is CLIENT

Use server hostname/IP:


upsc apc@192.168.1.60

Replace IP with your server.

🧪 Quick Status Filter


upsc apc@SERVER_IP | egrep "status|charge|runtime|load"

🚦 Status Codes

Code Meaning Action
OL Online Normal
OB On battery Monitor runtime
LB Low battery Shutdown imminent
FSD Forced shutdown Shutdown triggered

📊 Operational Thresholds

Metric Ideal Warning Critical
Load <50% >70% >85%
Runtime >10m <8m <4m
Charge >80% <60% <40%

🔎 Log Diagnostics


journalctl -u nut-monitor -n 50

Live:


journalctl -f -u nut-monitor

Important log meanings:

Message Meaning
Connection refused Server not running
No route to host Network unreachable
Login failed Credential mismatch
Communications established Link restored

🧯 Network Failure Interpretation

If you see:


connect failed: No route to host

This means:

  • remote server offline

  • IP changed

  • network outage

If later followed by:


Communications established

→ system recovered automatically.

🛠️ Client Connectivity Test


ping SERVER_IP

Then:


upsc apc@SERVER_IP

If ping works but upsc fails → NUT server issue.

🔐 Config Files Reference

File Purpose
/etc/nut/nut.conf Operating mode
/etc/nut/upsmon.conf Client monitoring targets
/etc/nut/ups.conf UPS driver (server only)
/etc/nut/upsd.users Auth users

🧠 Design Principle

Always verify where authority lives.

Only the true master:

  • talks to UPS

  • sends shutdown signals

  • controls FSD events

Misidentifying the master risks failed shutdown orchestration.

🚑 Fast Troubleshooting Flow

Check mode:


cat /etc/nut/nut.conf

Check monitor:


systemctl status nut-monitor

Query UPS:


upsc TARGET

Check logs:


journalctl -u nut-monitor -n 50

✅ Best Practices

  • Use DHCP reservation for NUT server

  • Document server IP

  • Test outage quarterly

  • Keep load <50%

  • Confirm shutdown order

📌 Reality Check Rule

If upsc fails, the problem is always one of three things:

  • wrong target

  • server offline

  • network path broken

Status: Field‑verified reference for real NUT deployments (master + client environments)


Updated ✅

Your BookStack entry has been rewritten to reflect the real architecture logic:

  • distinguishes Master vs Client mode

  • corrects upsc usage depending on role

  • adds diagnostic interpretation table

  • includes network-failure analysis

  • adds authority-model principle (who actually controls shutdown)

It’s now aligned with your actual Pi setup where the node may act as a client monitoring another NUT server, not necessarily the master.

✅ Suggested next entry (very useful for your infra docs):
“UPS Authority Map — Device Shutdown Order Diagram”
This would visually document:


UPS → Master → Clients → Final Power Cut

It prevents future confusion months later when troubleshooting.

 


No comments to display

Back to top