rtnetmon/README.md

# rtnetmon

rtnetmon is a WTFPL-licensed Go terminal (CLI/TUI) network monitor by
[@sneak](https://sneak.berlin) that shows real-time network health, packet
loss, and latency across two Linux network interfaces at once.

## Overview

rtnetmon is a terminal-based network monitoring tool that provides real-time
visibility into network health, packet loss, and latency across two network
interfaces simultaneously. It's designed for Linux systems and uses ncurses
for a clean, real-time dashboard interface.

## Features

- **Dual Interface Monitoring**: Monitor two network interfaces simultaneously
- **Real-time Updates**: Live dashboard with sub-second updates
- **Comprehensive Metrics**:
  - ICMP reachability tests
  - Packet loss percentage
  - TCP connection latency
  - Interface health status
- **Visual Indicators**: Color-coded status, spinners, and meters for quick status assessment
  - Packet loss meter uses reverse coloring (empty/green = good, full/red = bad)
- **Detailed Logging**: Optional logging to file for debugging and analysis

## Requirements

- Linux operating system
- Go 1.21 or later
- Root/sudo access (for raw ICMP packets)
- `ping` command available in PATH

## Installation

```bash
git clone https://git.eeqj.de/sneak/rtnetmon.git
cd rtnetmon
make build   # produces ./bin/rtnetmon
```

## Usage

```bash
sudo ./bin/rtnetmon --ifaceA eth0 --labelA "Primary WAN" --ifaceB wlan0 --labelB "Backup WiFi"
```

### Command Line Options

- `--ifaceA`: Primary network interface (default: "gu0")
- `--labelA`: Label for primary interface (default: "gu LAN - VPN outbound")
- `--ifaceB`: Secondary network interface (default: "backhaul0")
- `--labelB`: Label for secondary interface (default: "Cox cable direct")
- `--hosts`: Comma-separated list of hosts to monitor
- `--logfile`: Path to log file (default: "/tmp/rtnetmon.log")

### Keyboard Controls

- `q` or `Ctrl+C`: Quit the application

## Project Structure

```
rtnetmon/
├── cmd/rtnetmon/       # main entry point (thin: calls internal/cli)
│   └── main.go
├── internal/
│   ├── cli/            # command-line interface using Cobra
│   │   └── root.go
│   └── monitor/        # core monitoring functionality
│       ├── monitor.go  # monitor types, probes, logging
│       ├── loops.go    # monitoring loops (reachability, loss, TCP)
│       ├── styles.go   # terminal color styles
│       └── ui.go       # user interface rendering
├── script/             # Scripts to Rule Them All entrypoints
├── .gitea/workflows/   # CI (runs script/cibuild)
├── Dockerfile          # lint + test gate phases and the build
├── Makefile            # thin shims over script/
├── .golangci.yml       # vendored linter config
├── go.mod / go.sum
└── README.md
```

## Development

```bash
make build       # build ./bin/rtnetmon
make check       # run tests, lint, and fmt-check (the default target)
make test        # run the test suite (test phase of the Dockerfile)
make lint        # run golangci-lint (lint phase of the Dockerfile)
make fmt         # format Go code (writes)
make fmt-check   # verify formatting (read-only)
make docker      # build the Docker image
make hooks       # install the git pre-commit hook
make dev         # go run ./cmd/rtnetmon
make clean       # remove build artifacts
```

Linting and testing run in Docker so results do not depend on host tooling;
`make lint`, `make test`, `make docker`, and `make cibuild` therefore require
a Docker daemon. `make check` must be green before committing, and the
pre-commit hook (`make hooks`) runs it.

## Entrypoints

This repository adheres to the
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
standard: normalized scripts in `script/` are the entrypoints for the
development workflow, and the Makefile targets are thin shims that call them.

- `script/bootstrap` — install dependencies idempotently (git, make, go).
- `script/setup` — bootstrap plus install the git pre-commit hook.
- `script/projectname` — output the project name.
- `script/test` — run the test suite as the Dockerfile `test` phase.
- `script/lint` — run golangci-lint as the Dockerfile `lint` phase.
- `script/fmt` — format Go code (host).
- `script/fmt-check` — verify formatting (host, read-only).
- `script/check` — run test, lint, and fmt-check.
- `script/docker` — build the Docker image.
- `script/cibuild` — bootstrap, check, and build the image; run by CI.
- `script/precommit` — run by the pre-commit hook (go mod tidy check + check).
- `script/install-precommit` — install the pre-commit hook.

### Using the Monitor API

The monitor package provides an object-oriented API for programmatic use:

```go
import "git.eeqj.de/sneak/rtnetmon/internal/monitor"

// Create a new monitor
mon := monitor.NewMonitor("eth0", "Primary", "wlan0", "Backup", "/tmp/monitor.log")

// Configure timing parameters (optional - defaults are sensible)
mon.ICMPTimeout = 1 * time.Second
mon.PacketLossPings = 10
mon.PacketLossPeriod = 10 * time.Second

// Add hosts to monitor
mon.AddReachabilityHost("8.8.8.8")
mon.AddReachabilityHost("google.com")

mon.AddPacketLossHost("github.com")
mon.AddPacketLossHost("8.8.8.8")

mon.AddTCPHost("google.com:443")
mon.AddTCPHost("github.com:443")

// Run the monitor
ctx := context.Background()
if err := mon.Run(ctx); err != nil {
    log.Fatal(err)
}
```

## License

WTFPL - Do What The Fuck You Want To Public License

## Author

sneak@sneak.berlin