rtnetmon/README.md

# rtnetmon

Real-time network monitoring dashboard for Linux and macOS, with one- or
two-interface support.

## Overview

rtnetmon is a terminal-based network monitoring tool that provides real-time
visibility into network health, packet loss, and latency across one or two
network interfaces simultaneously. It runs on Linux and macOS and uses a
terminal dashboard interface.

## Features

- **Interface Monitoring**: Monitor one or 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 or macOS
- Go 1.21 or later
- Root/sudo access (for raw ICMP packets)
- `ping` command available in PATH
- On Linux: `ip` (with `/proc/net/route` as a fallback)
- On macOS: `netstat`

## Platform support and interface detection

rtnetmon monitors either one or two interfaces, chosen automatically for the
platform it runs on. When only one interface is detected, the dashboard shows a
single pane.

**Linux.** The two named interfaces (`--ifaceA`/`--ifaceB`, default
`gu0`/`backhaul0`) are used when both exist — this is the original dual-bridge
setup, unchanged. When neither exists, the single default-route interface is
monitored instead.

**macOS.** The physical internet interface is found from the default route. When
a VPN client is running (Mullvad and similar clients create a `utun` tunnel that
carries a default route or holds a routable address), that tunnel is monitored
as the primary pane alongside the physical interface. With no VPN running, only
the physical interface is monitored. Interface names are detected on macOS; the
`--ifaceA`/`--ifaceB` flags are not used there, but `--labelA`/`--labelB` still
set the pane labels.

### Supported matrix

| OS    | Interfaces monitored                                        |
| ----- | ----------------------------------------------------------- |
| Linux | `gu0` + `backhaul0` when both exist (two panes)             |
| Linux | the single default-route interface otherwise (one pane)     |
| macOS | VPN tunnel + physical default-route interface (two panes)   |
| macOS | the physical default-route interface with no VPN (one pane) |

Anything outside this matrix — on Linux, only one of the named pair present, or
no/multiple default routes when neither is present; on macOS, no default route
or more than one physical default route — exits with a clear error.

## Installation

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

## Usage

```bash
sudo ./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
│   └── main.go
├── internal/
│   ├── cli/           # Command-line interface using Cobra
│   │   └── root.go
│   ├── netdetect/     # Per-platform interface/route detection and selection
│   │   ├── netdetect.go     # Selection logic and route parsers (pure)
│   │   ├── routes_linux.go  # Linux default-route query (build-tagged)
│   │   └── routes_darwin.go # macOS default-route query (build-tagged)
│   └── monitor/       # Core monitoring functionality
│       ├── monitor.go     # Main monitoring types and functions
│       ├── loops.go       # Monitoring loops (reachability, loss, TCP)
│       ├── styles.go      # Terminal color styles
│       ├── ui.go          # User interface rendering
│       ├── dial_linux.go  # TCP source binding (build-tagged)
│       └── dial_darwin.go # TCP IP_BOUND_IF binding (build-tagged)
├── go.mod
├── go.sum
├── Makefile
└── README.md
```

## Development

### Building

```bash
make build          # Build the binary
make test          # Run tests
make lint          # Run linter
make fmt           # Format code
make all           # Format, lint, test, and build
```

### Testing

The project includes unit tests for core functionality. Run tests with:

```bash
make test
```

### 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 for one or two interfaces
mon := monitor.NewMonitor([]monitor.IfaceSpec{
    {Name: "eth0", Label: "Primary"},
    {Name: "wlan0", Label: "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