Home › Documentation › Tools › gnulte-doctor

gnulte-doctor(8) — the pre-flight check

Applies to gnulte-doctor v16.13 · last updated 2026-10-15

A zero-dependency check of whether this machine is ready to run the toolkit. Run it before the first real test and whenever something behaves strangely — most GNULTE problems are a WARN or FAIL it can already name.

Requirements

  • No privileges needed; running it as root adds the privilege-related checks.
  • Added in v16.9; no external tools of any kind.

Synopsis

gnulte-doctor [flags]

What it checks

CheckNotes
Privilegeswhether the tools that need root can get it
tc / iptablesbinaries present (the kernel interface for shaping)
ip_forwardIPv4 forwarding state, as the engine expects to find it
netem / netfilter moduleswhether the kernel modules are loaded or loadable
Default route and interfacethat there is a usable default route and a sane egress interface
Duplicate IPstwo hosts answering for the same address (ARP conflicts)
Safety recordthe state of the authorised-use acceptance record

Options

FlagDescription
--jsonoutput the report as JSON, for scripts and bug reports
-qquiet: print only warnings and failures
--versionprint version and exit

Examples

gnulte-doctor          # human-readable PASS/WARN/FAIL table
gnulte-doctor --json   # machine-readable, for bug reports and gating
gnulte-doctor -q       # warnings and failures only

Exit status

Exits non-zero when any check fails, so a script can gate on it:

gnulte-doctor -q || exit 1
gnulte-doctor --json | jq '.checks[] | select(.status=="FAIL")'

Reading the result

  • PASS — the machine is fine for that check.
  • WARN — usable, but something will behave differently (a missing optional module, an unusual route, a duplicate IP).
  • FAIL — a tool will not work until this is fixed; the table includes a fix-it hint.

Installation

Part of the GNULTE suite. Build and install everything at once;

git clone https://github.com/notmicrosoft2000-cmd/gnulte-go.git
cd gnulte-go
./build.sh          # builds all eight binaries, runs go vet + go test ./...
sudo ./install.sh   # installs to /usr/local/bin + safety docs

installs gnulte-doctor to /usr/local/bin/gnulte-doctor. See installation for requirements.

Common errors

Non-zero exit status
At least one check FAILed; the table names it with a fix-it hint. In scripts, gate with gnulte-doctor -q || ....
Everything PASSes but shaping still fails
Re-run as root so the privilege checks are meaningful, then see troubleshooting.

Related tools

  • Troubleshooting — the manual version of the same diagnosis
  • every other tool in the suite — doctor is the first step of all of them