Home › Documentation › Tools › gnulte-doctor
gnulte-doctor(8) — the pre-flight check
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
| Check | Notes |
|---|---|
| Privileges | whether the tools that need root can get it |
tc / iptables | binaries present (the kernel interface for shaping) |
ip_forward | IPv4 forwarding state, as the engine expects to find it |
| netem / netfilter modules | whether the kernel modules are loaded or loadable |
| Default route and interface | that there is a usable default route and a sane egress interface |
| Duplicate IPs | two hosts answering for the same address (ARP conflicts) |
| Safety record | the state of the authorised-use acceptance record |
Options
| Flag | Description |
|---|---|
--json | output the report as JSON, for scripts and bug reports |
-q | quiet: print only warnings and failures |
--version | print 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