# NetMonitor — User Guide

A complete guide for operating NetMonitor: logging in, reading the dashboard, monitoring remote servers over SNMP, managing users, running it as a service, and troubleshooting.

> **Version:** 1.0 · **Default login:** `sysadmin` / `pas4admin` · **Default URL:** `http://localhost:8080`

---

## Table of contents

1. [What is NetMonitor?](#1-what-is-netmonitor)
2. [Getting started](#2-getting-started)
3. [Logging in & out](#3-logging-in--out)
4. [The dashboard](#4-the-dashboard)
5. [Time ranges & data retention](#5-time-ranges--data-retention)
6. [Reading the KPI cards](#6-reading-the-kpi-cards)
7. [Reading the charts](#7-reading-the-charts)
8. [Adding a remote server (SNMP)](#8-adding-a-remote-server-snmp)
9. [Testing a remote connection](#9-testing-a-remote-connection)
10. [Editing, pausing & deleting hosts](#10-editing-pausing--deleting-hosts)
11. [User management](#11-user-management)
12. [Roles: what you can and can't do](#12-roles-what-you-can-and-cant-do)
13. [Changing your password](#13-changing-your-password)
14. [Running as a service](#14-running-as-a-service)
15. [Configuration reference](#15-configuration-reference)
16. [Troubleshooting](#16-troubleshooting)
17. [FAQ](#17-faq)
18. [Security checklist](#18-security-checklist)

---

## 1. What is NetMonitor?

NetMonitor continuously samples metrics from:

- **The machine it runs on** (local host) — every 60 seconds.
- **Any number of remote servers** that answer SNMP v2c requests — every 10–3600 seconds (your choice per host).

Collected metrics:

| Metric | Local | Remote (SNMP) |
|---|---|---|
| CPU utilisation % | ✅ | ✅ (HOST-RESOURCES MIB) |
| Load average 1/5/15 min | ✅ | ✅ when the device exposes `hrLoad` (HOST-RESOURCES) |
| Memory total / used / % | ✅ | ✅ (HOST-RESOURCES) |
| Swap | ✅ | ✅ when reported via `hrStorage` type 4 |
| Disk total / used / % | ✅ | ✅ (all fixed disks, `hrStorage` type 2) |
| Network in/out (Mbps) + errors | ✅ | ✅ (per-interface) |
| Uptime, hostname, OS | ✅ | ✅ |

All values are stored in a local SQLite database and shown as live KPI cards and history charts in the web UI.

---

## 2. Getting started

### One-time setup (operator who installs it)

```bash
cd /path/to/Net-Monitor

# 1) dependencies (once)
pip3 install --user --break-system-packages flask psutil

# 2a) quick foreground test
./run.sh                 # Ctrl-C to stop

# 2b) ... or install as a service (recommended for daily use)
./service.sh install
```

### First login

1. Open **http://localhost:8080** (or `http://<server-ip>:8080` from another machine on the LAN).
2. Sign in with **sysadmin** / **pas4admin**.
3. **Change the default password immediately** (🔑 button, top-right → see [§13](#13-changing-your-password)).
4. Wait up to 60 seconds for the first local sample, then watch the dashboard populate.

---

## 3. Logging in & out

- **Sign in:** enter username + password on the login page. Wrong credentials show *"Invalid username or password"* (NetMonitor never hints which part was wrong).
- **Sign out:** click **Sign out** in the top bar. This clears the session on this browser only — other sessions stay alive until they expire or the server restarts.
- Sessions are cookie-based (`HttpOnly`, `SameSite=Lax`). Disabling cookies in the browser breaks the app.

---

## 4. The dashboard

The main screen has five areas:

```
┌────────────────────────────────────────────────────────────────┐
│ 📡 NetMonitor                              [avatar name role] 🔑 Sign out │
├──────────────┬─────────────────────────────────────────────────┤
│ Monitored    │ [down banner — only when the host is unreachable]│
│ hosts        │ Host title · OS        last updated  1h 6h 24h 7d 30d │
│ • Local (up) │ ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐│
│ • core-1(up) │ │ CPU  ││ Mem  ││ Net↑ ││ Net↓ ││ Load ││ Disk ││
│              │ └──────┘└──────┘└──────┘└──────┘└──────┘└──────┘│
│ ＋Add host   │  [CPU chart]      [Memory chart]                │
│ ⚙ Manage…    │  [Network throughput — full width]              │
│ ⟳ Refresh    │  [Load chart]      [Disk chart]                 │
│              │                                                  │
│              │ ⚙ Administration            (admin only)         │
│              │  [Remote hosts] [Users]  + tables & modals       │
└──────────────┴─────────────────────────────────────────────────┘
```

- **Top bar** — your identity, role badge (`admin`/`user`), 🔑 change password, Sign out.
- **Sidebar (left)** — every monitored host with a green/red up/down dot; click to switch. Admins also get **＋ Add remote host**, **⚙ Manage…**, and **⟳ Refresh** (force an immediate reload).
- **Down banner** — a red strip appears at the top of the page if the selected remote host hasn't answered recently.
- **Toolbar** — selected host name + OS, "last updated" time, and the **time-range buttons** (see §5).
- **KPI cards** — current values (see §6).
- **Charts** — history for the selected range (see §7).
- **Administration section** — visible to **admins only**: *Remote hosts* and *Users* tabs (see §8–§11).

The dashboard **auto-refreshes every 30 seconds**; you don't need to reload the page.

---

## 5. Time ranges & data retention

The toolbar has five range buttons: **1h · 6h · 24h · 7d · 30d**.

- Clicking one re-renders all charts for that window.
- Data is sampled **every 60 seconds**, so:
  - 1h → up to 60 points
  - 24h → up to 1440 points
  - 30d → up to 43 200 raw points
- For long windows the server **downsamples to ~800 points** for smooth charts (you still see the full trend, just less micro-detail).
- Raw samples older than `retention_days` (default **30 days**) are purged automatically. To keep longer history, raise `retention_days` in `config.json` and restart (see §15).

> If a range shows *"No samples yet for this range — data is collected every 60 seconds. Come back in a minute."*, the host was just added (or the app just started) — wait one poll cycle.

---

## 6. Reading the KPI cards

| Card | Main value | Sub-line |
|---|---|---|
| 🧠 **CPU** | current utilisation % | load averages |
| 💾 **Memory** | % used | used GB of total GB |
| 📥 **Net in** | current inbound rate (Mbps/Ms auto) | rx errors |
| 📤 **Net out** | current outbound rate | tx errors |
| ⚖ **Load (1m)** | 1-minute load average | core count (local) |
| 💽 **Disk** | % of storage used | used / total GB |
| ⏱ **Uptime** | days h m since last boot | hostname |
| 🗄 **Swap** | used MB/GB of total | % used |

**Colour coding:** values turn **green** (healthy), **amber** (elevated — e.g. CPU > 70 %, disk > 80 %), or **red** (critical — e.g. CPU > 90 %, disk > 90 %).

Rates ("Net in/out") are computed between consecutive samples, so they show the speed *over the last poll interval*, not an instantaneous spike.

---

## 7. Reading the charts

Five charts, all in the selected time range:

| Chart | What it shows |
|---|---|
| **CPU usage** | % utilisation over time |
| **Memory** | % used (line) and used GB (line) |
| **Network throughput** | Mb/s in and out across *all* interfaces, plus the top 6 busiest individual interfaces when available |
| **Load average** | three lines: 1 min, 5 min, 15 min |
| **Disk usage** | % of total storage used over time |

**Hover** any chart to see a tooltip with the timestamp and values at that point. Gaps in a line mean the host wasn't reachable for those samples.

---

## 8. Adding a remote server (SNMP)

> Requires **admin** role.

1. Click **＋ Add remote host** in the sidebar (or the **⚙ Administration → Remote hosts → ＋ Add host** button).
2. Fill in the dialog:

| Field | Example | Rules |
|---|---|---|
| **Name** | `core-router-1` | required, must be unique |
| **IP address** | `192.168.1.10` | required (IP or hostname) |
| **SNMP community (v2c)** | `public` | defaults to `public` if left blank |
| **SNMP port** | `161` | 1–65535, default 161 (UDP) |
| **Poll interval (s)** | `60` | 10–3600, default 60 |

3. Click **🔍 Test connection** first (recommended — see §9).
4. Click **Save**. The host appears in the sidebar and in the admin table; the first sample arrives within one poll interval.

### What "community string" means

The SNMP **community** is a shared secret the device checks on each request — think of it as a *read-only password*. Most small devices ship with `public`, which is why it works out of the box on many. If your device was configured with a custom community, ask the network team for it.

> ⚠️ SNMP v2c has **no authentication or encryption** — anyone on the network can replay your community string. Use a dedicated, read-only community for monitoring, and only monitor hosts you trust.

### Which devices work?

Anything that answers SNMP v2c and implements the standard MIBs: Linux/UNIX hosts (with `snmpd`), most routers and switches (Cisco IOS, Juniper, pfSense/OPNsense, Mikrotik, etc.), and many appliances. NetMonitor reads `sys*`, `HOST-RESOURCES` (`hr*`) and `IF-MIB` (`ifTable`) OIDs. Devices without HOST-RESOURCES will still show interfaces, uptime, hostname and OS.

---

## 9. Testing a remote connection

In the host dialog, **🔍 Test connection** performs a live SNMP probe against the *currently typed* values (so you can test before saving). It reports:

- ✅ **OK** — latency (ms), hostname, OS description, CPU %, total memory, total disk, and the interface names it found.
- ❌ **Failure** — a reason, e.g. `timeout`, `no response`, or an SNMP error such as `notReadable` (wrong community).

Common test failures:

| Symptom | Likely cause | Fix |
|---|---|---|
| `timeout` / no response | host down, wrong IP, or UDP 161 firewalled | `ping` the host; check firewall rules on the remote |
| `notReadable` / `noSuchName` | wrong community string | confirm the community with the device admin |
| Interfaces OK but no CPU/memory/load/swap | device lacks HOST-RESOURCES MIB | nothing to fix — those values show "–" for this host; interface & uptime data still work |
| Works from CLI but not here | port != 161, or source-address binding | set the correct SNMP port in the form |

---

## 10. Editing, pausing & deleting hosts

In **⚙ Administration → Remote hosts**, each row has actions:

- **Edit** — opens the same dialog pre-filled; you can also change the community, port, interval, or re-test.
- **Enable/Disable** — toggles collection without losing the host's history. A disabled host is skipped by the collector; re-enabling resumes within one cycle.
- **Delete** — removes the host. *Historical samples are kept in the database* (they simply won't be reachable from the UI), but the host disappears from the sidebar and tables.

After any host change the collector restarts automatically — no service restart needed.

---

## 11. User management

> Requires **admin** role.

**⚙ Administration → Users** shows a table: *Username · Role · Status · Created · Actions*.

- **＋ Add user** — create an account:
  - **Username:** 3–32 characters, letters/digits/underscore (e.g. `jdoe`, `ops_2`)
  - **Password:** minimum 6 characters
  - **Role:** `user` (view only) or `admin` (full control)
- **Edit** — change username, role, set a new password, or disable the account.
- **Enable/Disable** — a disabled account can no longer sign in; existing sessions are rejected on their next API call.
- **Delete** — removes the account (you cannot delete your own account; NetMonitor blocks it).

Guardrails built in:
- If an admin **demotes themselves or disables their own account**, the UI logs them out immediately.
- You cannot delete the last working admin accidentally — at minimum, be deliberate: NetMonitor does not lock you out by blocking self-deletion.

---

## 12. Roles: what you can and can't do

| Capability | 👑 admin | 👁 user |
|---|:---:|:---:|
| Log in / log out | ✅ | ✅ |
| View dashboard, KPIs, charts, all hosts | ✅ | ✅ |
| Switch time ranges | ✅ | ✅ |
| Refresh / change own password | ✅ | ✅ |
| Add / edit / disable / delete remote hosts | ✅ | ❌ |
| Test remote connections | ✅ | ❌ |
| Create / edit / disable / delete users | ✅ | ❌ |

`user` accounts are ideal for dashboards shown to other teams: they get everything visual, none of the controls. Any admin-only API call from a `user` session returns HTTP 403.

---

## 13. Changing your password

Any role can change their own password:

1. Click the **🔑** button in the top bar.
2. Enter the **current** password and a **new** password (≥ 6 characters).
3. Click **Update** — a toast confirms success.

To reset someone else's password, an admin can edit the user and set a new password (§11).

---

## 14. Running as a service

NetMonitor ships with a systemd unit (`net-monitor.service`) and a helper script.

```bash
./service.sh install     # copy unit → enable on boot → start   (asks for sudo once)
./service.sh status      # service state, PID, health check, last 5 log lines
./service.sh restart     # pick up config.json changes
./service.sh start|stop
./service.sh uninstall   # remove unit; data in ./data/ is preserved
```

Useful commands:

```bash
sudo systemctl status net-monitor          # state + recent logs
sudo journalctl -u net-monitor -f          # live logs
sudo journalctl -u net-monitor -S today    # today's logs
```

Unit characteristics:

- `Restart=on-failure` with a 5 s backoff — it comes back after crashes.
- Starts after `network-online.target`.
- Hardened: `NoNewPrivileges=true`, `PrivateTmp=true`.
- Runs as the user who installed it (edit `net-monitor.service` `User=` to change).

> **Note:** the app intentionally runs as a single instance. If you start `./run.sh` while the service is running, they will conflict on port 8080 — stop one.

---

## 15. Configuration reference

`config.json`:

| Key | Default | Meaning |
|---|---|---|
| `host` | `0.0.0.0` | network interface to bind |
| `port` | `8080` | HTTP port |
| `local_poll_interval` | `60` | seconds between local samples (remote hosts use their own per-host interval) |
| `retention_days` | `30` | auto-delete samples older than this |

Restart (or `./service.sh restart`) after editing.

Files created at runtime in `data/`:

| File | Notes |
|---|---|
| `netmonitor.db` | all monitoring data + user accounts — **back this up** |
| `secret.key` | session signing secret (0600). Delete to force everyone to re-login. |

---

## 16. Troubleshooting

**The web page won't load**
- Is the service running? `./service.sh status`
- Correct port? `curl -s http://localhost:8080/api/health`
- Another process on 8080? `ss -ltnp | grep 8080`
- From another machine: LAN firewall / SELinux may block 8080.

**Local host shows no data**
- First sample takes up to 60 s after start.
- Check `psutil` import works: `python3 -c "import psutil"` as the service user.

**Remote host keeps showing red / down**
- Run **Test connection** from the UI for the exact error.
- Verify UDP 161 outbound from the server: `sudo apt install snmp  && snmpget -v2c -c public <ip> sysDescr.0` (if you have net-snmp available).
- Check the remote device's firewall and SNMP source-address restrictions.

**Charts have gaps**
- Normal for hosts that were unreachable during that window, or that were added mid-range.

**I locked myself out**
- Stop the service (`./service.sh stop`), delete the bad user via the DB, or reset: the `sysadmin` account is always present; if you forgot its password, stop the service and run a one-off `python3 -c` to reset the hash, or delete `data/netmonitor.db` (⚠️ wipes all history) and restart to re-seed `sysadmin`/`pas4admin`.

**Service won't start after moving folders**
- The unit file has absolute paths (`User=`, `WorkingDirectory=`, `ExecStart=`). Update `net-monitor.service` and re-run `./service.sh install`.

---

## 17. FAQ

**Q: Is this MRTG?**
A: It follows the same idea — poll, store, chart — but with a modern web UI, multi-host support, user roles, and no RRDtool dependency. Storage is plain SQLite.

**Q: Why is SNMP v2c instead of v3?**
A: v2c + community strings is the overwhelmingly common read-only setup and needs zero extra dependencies. The SNMP layer is isolated in `snmp_client.py`, so adding v3 later is a contained change.

**Q: How is remote disk measured?**
A: NetMonitor sums all fixed disks (`hrStorage` type 2) reported by HOST-RESOURCES, so multi-disk hosts show the aggregate. Per-partition breakdowns are a natural extension.

**Q: Where is the data?**
A: `./data/netmonitor.db` (SQLite). Copy it anywhere with SQLite tooling, or just back up the file.

**Q: Does it need the internet?**
A: No. Everything is local; the only external traffic is SNMP *to* the hosts you add.

**Q: Can I have several NetMonitor instances?**
A: Yes — separate folders, separate ports, separate `data/` directories.

**Q: What's the API for?**
A: Automation and integrations (Grafana, scripts, alerting). See the API table in [README.md](../README.md).

---

## 18. Security checklist

- [ ] Changed the default `sysadmin` password.
- [ ] Created role-appropriate accounts; gave viewers the `user` role.
- [ ] SNMP communities are unique, read-only, and only used for monitoring.
- [ ] `data/` directory is not world-readable (`chmod 700 data`).
- [ ] If the server is reachable beyond your LAN: put the app behind an HTTPS reverse proxy and restrict by IP/VPN.
- [ ] Back up `data/netmonitor.db` regularly.
- [ ] Review the user list periodically; disable (not just delete) accounts you're unsure about.

---

*NetMonitor — simple, self-contained, and yours.*