netriage 0.51.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- netriage-0.51.0/GUIDE.md +227 -0
- netriage-0.51.0/LICENSE +21 -0
- netriage-0.51.0/MANIFEST.in +3 -0
- netriage-0.51.0/PKG-INFO +92 -0
- netriage-0.51.0/README.md +69 -0
- netriage-0.51.0/TROUBLESHOOTING.md +137 -0
- netriage-0.51.0/docs/cli.png +0 -0
- netriage-0.51.0/docs/crowded.png +0 -0
- netriage-0.51.0/docs/demo-sudo.gif +0 -0
- netriage-0.51.0/docs/demo.gif +0 -0
- netriage-0.51.0/docs/weak.png +0 -0
- netriage-0.51.0/netriage/__init__.py +3 -0
- netriage-0.51.0/netriage/__main__.py +8 -0
- netriage-0.51.0/netriage/cli.py +794 -0
- netriage-0.51.0/netriage/compare.py +227 -0
- netriage-0.51.0/netriage/debug.py +85 -0
- netriage-0.51.0/netriage/diagnose.py +825 -0
- netriage-0.51.0/netriage/logo.py +16 -0
- netriage-0.51.0/netriage/logs.py +180 -0
- netriage-0.51.0/netriage/media.py +120 -0
- netriage-0.51.0/netriage/network.py +265 -0
- netriage-0.51.0/netriage/render.py +472 -0
- netriage-0.51.0/netriage/report.py +175 -0
- netriage-0.51.0/netriage/soak.py +218 -0
- netriage-0.51.0/netriage/util.py +459 -0
- netriage-0.51.0/netriage/wifi.py +486 -0
- netriage-0.51.0/netriage/wired.py +138 -0
- netriage-0.51.0/netriage.egg-info/PKG-INFO +92 -0
- netriage-0.51.0/netriage.egg-info/SOURCES.txt +51 -0
- netriage-0.51.0/netriage.egg-info/dependency_links.txt +1 -0
- netriage-0.51.0/netriage.egg-info/entry_points.txt +2 -0
- netriage-0.51.0/netriage.egg-info/top_level.txt +1 -0
- netriage-0.51.0/pyproject.toml +50 -0
- netriage-0.51.0/setup.cfg +4 -0
- netriage-0.51.0/tests/fixtures/ethtool.txt +13 -0
- netriage-0.51.0/tests/fixtures/iw_link.txt +11 -0
- netriage-0.51.0/tests/fixtures/iw_scan.txt +26 -0
- netriage-0.51.0/tests/fixtures/iw_station.txt +11 -0
- netriage-0.51.0/tests/fixtures/lldp_neighbors.txt +11 -0
- netriage-0.51.0/tests/integration/__init__.py +0 -0
- netriage-0.51.0/tests/integration/conftest.py +156 -0
- netriage-0.51.0/tests/integration/test_cli_blackbox.py +106 -0
- netriage-0.51.0/tests/integration/test_matrix.py +146 -0
- netriage-0.51.0/tests/test_cli.py +1481 -0
- netriage-0.51.0/tests/test_compare.py +195 -0
- netriage-0.51.0/tests/test_debug.py +82 -0
- netriage-0.51.0/tests/test_diagnose.py +517 -0
- netriage-0.51.0/tests/test_logs.py +86 -0
- netriage-0.51.0/tests/test_network.py +100 -0
- netriage-0.51.0/tests/test_progress.py +137 -0
- netriage-0.51.0/tests/test_soak.py +107 -0
- netriage-0.51.0/tests/test_wifi.py +242 -0
- netriage-0.51.0/tests/test_wired.py +118 -0
netriage-0.51.0/GUIDE.md
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# netriage — command guide
|
|
2
|
+
|
|
3
|
+
## Commands
|
|
4
|
+
|
|
5
|
+
| Command | Question it answers |
|
|
6
|
+
|---|---|
|
|
7
|
+
| `netriage` | What is wrong with this link, right now? |
|
|
8
|
+
| `netriage scan` | What is around me, and how busy are the channels? |
|
|
9
|
+
| `netriage watch` | Is the fault intermittent? When does it drop? |
|
|
10
|
+
| `netriage read ID` | What did that run look like? |
|
|
11
|
+
| `netriage report [FILE \| ID]` | The same run as Markdown, for a ticket. |
|
|
12
|
+
| `netriage compare [A] [B]` | Did the change actually help? |
|
|
13
|
+
| `netriage history` | The saved runs, numbered. |
|
|
14
|
+
|
|
15
|
+
### `netriage`
|
|
16
|
+
|
|
17
|
+
One pass: link, network, throughput, verdict. About 5–20 seconds.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
netriage # what is wrong right now
|
|
21
|
+
netriage --wired # force the cable
|
|
22
|
+
netriage --offline # never touch the internet, ~2 seconds
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### `netriage scan`
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
netriage scan
|
|
29
|
+
netriage scan --json | jq '.[] | {ssid, channel, signal}'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Merges `iw` and `nmcli`, deduplicated by BSSID: one source alone often reports
|
|
33
|
+
less. As root you also get each access point's own load and client count;
|
|
34
|
+
without it the table says so.
|
|
35
|
+
|
|
36
|
+
### `netriage watch`
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
netriage watch --minutes 20 --interval 2
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
| Option | Default |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `--minutes M` | 10 |
|
|
45
|
+
| `--interval S` | 5 |
|
|
46
|
+
| `--out FILE` | `~/Documents/netriage-log/watch-*.csv` |
|
|
47
|
+
|
|
48
|
+
One CSV row per sample, plus a summary when it stops.
|
|
49
|
+
|
|
50
|
+
### `netriage read ID`
|
|
51
|
+
|
|
52
|
+
Re-prints a saved run in the shape of a live one. No hardware, no root.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
netriage history # the id is the first column
|
|
56
|
+
netriage read 12
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### `netriage report [FILE | ID]`
|
|
60
|
+
|
|
61
|
+
Markdown for one run; the newest by default. Missing values read `unknown` or
|
|
62
|
+
`not tested`, never `0`.
|
|
63
|
+
|
|
64
|
+
### `netriage compare [A] [B] ...`
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
netriage compare # the two most recent
|
|
68
|
+
netriage compare 23 22 # by run id
|
|
69
|
+
netriage compare a.json b.json # by file
|
|
70
|
+
netriage compare 1 2 3 4 # trend table
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Two runs from different media are refused: they share no measurement.
|
|
74
|
+
|
|
75
|
+
## Flags
|
|
76
|
+
|
|
77
|
+
Options work before or after the command.
|
|
78
|
+
|
|
79
|
+
| Flag | Effect |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `--iface NAME` | test a specific interface |
|
|
82
|
+
| `--wired` / `--wifi` | force the medium |
|
|
83
|
+
| `--offline` | no speed test, no public DNS, no portal check |
|
|
84
|
+
| `--json` | machine-readable output — the default run and `scan` only |
|
|
85
|
+
| `--data-dir PATH` | where reports go; absolute, remembered; `default` forgets |
|
|
86
|
+
| `--redact` | mask MACs, addresses, SSIDs, user name, and the debug bundle |
|
|
87
|
+
| `--version` | version and where the package was loaded from |
|
|
88
|
+
|
|
89
|
+
`NO_COLOR` disables colour. Exit codes: `0` fine, `1` a CRITICAL finding, `2`
|
|
90
|
+
could not run, `130` interrupted.
|
|
91
|
+
|
|
92
|
+
## One run, start to finish
|
|
93
|
+
|
|
94
|
+

|
|
95
|
+
|
|
96
|
+
As a normal user you get the link, the network, the throughput and the verdict.
|
|
97
|
+
Two lines say what root would add: the radio's own channel load, and each
|
|
98
|
+
access point's load and client count.
|
|
99
|
+
|
|
100
|
+

|
|
101
|
+
|
|
102
|
+
With `sudo` those two lines fill in and nothing else changes.
|
|
103
|
+
|
|
104
|
+
## Three results
|
|
105
|
+
|
|
106
|
+
### A healthy link
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
all clear 4 APs · gateway 2.1 ms
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+

|
|
113
|
+
|
|
114
|
+
Signal above −60 dBm, retries under 10%, channel not crowded. Nothing to do.
|
|
115
|
+
|
|
116
|
+
### A crowded channel
|
|
117
|
+
|
|
118
|
+

|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
[WARNING] Channel is 62% busy
|
|
122
|
+
[WARNING] 4 access points share 2.4 GHz channel 1
|
|
123
|
+
[WARNING] High retransmission rate (22.5%)
|
|
124
|
+
[INFO] Throughput is 10.8 Mb/s on a 144 Mb/s link
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Signal is fine. The air is the problem. The last line matters most: the radio
|
|
128
|
+
negotiated 144 Mb/s but delivered 10.8, so whatever is limiting it is not the
|
|
129
|
+
signal strength.
|
|
130
|
+
|
|
131
|
+
### A weak signal
|
|
132
|
+
|
|
133
|
+

|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
[CRITICAL] Very weak signal (-82 dBm)
|
|
137
|
+
[CRITICAL] Low signal-to-noise ratio (12 dB)
|
|
138
|
+
[INFO] Channel 104 is a DFS channel
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
−82 dBm at 5 GHz. The channel is only 9% busy and retries are low, so this is
|
|
142
|
+
distance, not interference.
|
|
143
|
+
|
|
144
|
+
## Reading the numbers
|
|
145
|
+
|
|
146
|
+
### Wireless link
|
|
147
|
+
|
|
148
|
+
| Field | Good | Watch | Bad | What it is |
|
|
149
|
+
|---|---|---|---|---|
|
|
150
|
+
| Signal | ≥ −60 dBm | ≤ −70 → WARNING | ≤ −78 → CRITICAL | distance and walls |
|
|
151
|
+
| SNR | ≥ 25 dB | 15–25 | < 15 → CRITICAL | signal above the noise floor |
|
|
152
|
+
| Channel busy | < 30% | ≥ 50% → WARNING | ≥ 70% → CRITICAL | airtime already used |
|
|
153
|
+
| TX retries | < 10% | ≥ 20% → WARNING | ≥ 35% → CRITICAL | the real health meter |
|
|
154
|
+
| Negotiated | — | — | — | what the radios agreed on, not what you get |
|
|
155
|
+
|
|
156
|
+
### Network
|
|
157
|
+
|
|
158
|
+
| Field | Good | Watch | Bad |
|
|
159
|
+
|---|---|---|---|
|
|
160
|
+
| Gateway RTT | < 10 ms | ≥ 100 ms → WARNING | ≥ 300 ms → CRITICAL |
|
|
161
|
+
| Gateway loss | 0% | — | ≥ 20% → CRITICAL |
|
|
162
|
+
| Internet loss | 0% | ≥ 5% → WARNING | — |
|
|
163
|
+
| Jitter | < 5 ms | ≥ 20 ms and ≥ 50% of the mean | — |
|
|
164
|
+
| DNS (local) | ok, < 50 ms | > 200 ms → WARNING | no reply → CRITICAL |
|
|
165
|
+
| Subnet | /24 | ≤ /16 → WARNING | — |
|
|
166
|
+
|
|
167
|
+
`DNS local` is the resolver DHCP handed out; `DNS public` is 1.1.1.1, there for
|
|
168
|
+
comparison. REFUSED, SERVFAIL and NXDOMAIN are reported as themselves, not as
|
|
169
|
+
"the server is down".
|
|
170
|
+
|
|
171
|
+
### Wired link
|
|
172
|
+
|
|
173
|
+
| Field | Good | Bad | What it is |
|
|
174
|
+
|---|---|---|---|
|
|
175
|
+
| Speed / duplex | 1000 Mb/s full | — | half duplex deserves a look |
|
|
176
|
+
| Frame errors | < 10 per million | ≥ 10 → WARNING, ≥ 100 → CRITICAL | a rate, not a count |
|
|
177
|
+
| Checksum errors | any | — | not frame errors: the adapter's own tally |
|
|
178
|
+
| LLDP | switch + port | unknown | which port you are plugged into |
|
|
179
|
+
|
|
180
|
+
### `unknown`
|
|
181
|
+
|
|
182
|
+
A value that could not be read says `unknown`, never `0`. A missing tool is not
|
|
183
|
+
a healthy link.
|
|
184
|
+
|
|
185
|
+
## Recipes
|
|
186
|
+
|
|
187
|
+
**Site survey**
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
for room in 101 102 201; do echo "== $room"; netriage scan | head -20; done
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**Before and after a change**
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
netriage --json > before.json
|
|
197
|
+
# change the channel
|
|
198
|
+
netriage --json > after.json
|
|
199
|
+
netriage compare before.json after.json
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**A fault that comes and goes**
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
netriage watch --minutes 30 --interval 2
|
|
206
|
+
# look for DISCONNECTED rows and the Drops count
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
**Evidence for a ticket**
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
netriage
|
|
213
|
+
netriage report > evidence.md
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Where files go
|
|
217
|
+
|
|
218
|
+
| What | Where |
|
|
219
|
+
|---|---|
|
|
220
|
+
| Saved runs | `~/Documents/netriage-log/netriage-YYYYMMDD-NNNN.json` |
|
|
221
|
+
| Debug bundle | same directory, `-debug.txt` |
|
|
222
|
+
| Watch CSVs | same directory, `watch-*.csv` |
|
|
223
|
+
|
|
224
|
+
On a machine without `~/Documents` the directory is
|
|
225
|
+
`~/.local/share/netriage/logs`. `netriage --data-dir /some/path` moves it and
|
|
226
|
+
remembers; `NETRIAGE_DATA_DIR` moves it for one run. The directory is `0700`
|
|
227
|
+
and the files `0600`: they name networks and addresses.
|
netriage-0.51.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 netriage contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
netriage-0.51.0/PKG-INFO
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: netriage
|
|
3
|
+
Version: 0.51.0
|
|
4
|
+
Summary: Field network triage: tells you what is wrong with a wired or wireless link, not just what is measurable.
|
|
5
|
+
Author: netriage contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/chchenbo/netriage
|
|
8
|
+
Project-URL: Issues, https://github.com/chchenbo/netriage/issues
|
|
9
|
+
Keywords: network,wifi,diagnostics,triage,linux,lldp
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: System Administrators
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Topic :: System :: Networking
|
|
18
|
+
Classifier: Topic :: System :: Systems Administration
|
|
19
|
+
Requires-Python: >=3.8
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# netriage
|
|
25
|
+
|
|
26
|
+
**A field network check that prints a verdict, not a wall of numbers.**
|
|
27
|
+
|
|
28
|
+
Someone says *"the Wi-Fi is broken in room 2.14"*. You have a laptop, no
|
|
29
|
+
context, and ten minutes. `netriage` takes one pass of measurements and says
|
|
30
|
+
which of the usual things is wrong: coverage, congestion, retries, DHCP, DNS,
|
|
31
|
+
or a link that is fine and a ceiling somewhere else.
|
|
32
|
+
|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
Linux only, standard library only, Python 3.8+. It reads `iw`, `ethtool`,
|
|
36
|
+
`nmcli`, `ping`, `dig` and `lldpcli` — there is nothing to measure on another
|
|
37
|
+
platform.
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
sudo apt install -y iw ethtool lldpd dnsutils curl iputils-ping network-manager
|
|
43
|
+
sudo systemctl enable --now lldpd
|
|
44
|
+
|
|
45
|
+
git clone https://github.com/chchenbo/netriage netriage-src
|
|
46
|
+
cd netriage-src
|
|
47
|
+
sudo bash install.sh
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
That puts the command in `/usr/local/bin`, so from any directory:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
netriage
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`sudo netriage` adds what only root can read — the access point's own load
|
|
57
|
+
figures and client counts — and the report says so on the line it applies to:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
Channel busy n/a - run with sudo to read it from the AP
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Use
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
netriage # what is wrong with this link, right now?
|
|
67
|
+
netriage scan # what is around me, and how busy are the channels?
|
|
68
|
+
netriage watch --minutes 20 # is the fault intermittent? when does it drop?
|
|
69
|
+
netriage read 12 # what did run 12 look like?
|
|
70
|
+
netriage report 12 # the same run as Markdown, for a ticket
|
|
71
|
+
netriage compare # did the change actually help?
|
|
72
|
+
netriage history # the saved runs
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**→ [GUIDE.md](GUIDE.md)** — every command, every flag, and what each number
|
|
76
|
+
means.
|
|
77
|
+
**→ [TROUBLESHOOTING.md](TROUBLESHOOTING.md)** — what to do when the command
|
|
78
|
+
is not found, or a report looks wrong.
|
|
79
|
+
|
|
80
|
+
## What it will not do
|
|
81
|
+
|
|
82
|
+
It measures and it states what it measured. It does not tell you what to
|
|
83
|
+
change: it does not know the building, the budget or the policy, and a generic
|
|
84
|
+
recommendation is worse than none.
|
|
85
|
+
|
|
86
|
+
A value it could not read shows as `unknown`, never as zero. An interface that
|
|
87
|
+
cannot route is not measured at all, because the probes would silently travel
|
|
88
|
+
over a different one.
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# netriage
|
|
2
|
+
|
|
3
|
+
**A field network check that prints a verdict, not a wall of numbers.**
|
|
4
|
+
|
|
5
|
+
Someone says *"the Wi-Fi is broken in room 2.14"*. You have a laptop, no
|
|
6
|
+
context, and ten minutes. `netriage` takes one pass of measurements and says
|
|
7
|
+
which of the usual things is wrong: coverage, congestion, retries, DHCP, DNS,
|
|
8
|
+
or a link that is fine and a ceiling somewhere else.
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+
|
|
12
|
+
Linux only, standard library only, Python 3.8+. It reads `iw`, `ethtool`,
|
|
13
|
+
`nmcli`, `ping`, `dig` and `lldpcli` — there is nothing to measure on another
|
|
14
|
+
platform.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
sudo apt install -y iw ethtool lldpd dnsutils curl iputils-ping network-manager
|
|
20
|
+
sudo systemctl enable --now lldpd
|
|
21
|
+
|
|
22
|
+
git clone https://github.com/chchenbo/netriage netriage-src
|
|
23
|
+
cd netriage-src
|
|
24
|
+
sudo bash install.sh
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
That puts the command in `/usr/local/bin`, so from any directory:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
netriage
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`sudo netriage` adds what only root can read — the access point's own load
|
|
34
|
+
figures and client counts — and the report says so on the line it applies to:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
Channel busy n/a - run with sudo to read it from the AP
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Use
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
netriage # what is wrong with this link, right now?
|
|
44
|
+
netriage scan # what is around me, and how busy are the channels?
|
|
45
|
+
netriage watch --minutes 20 # is the fault intermittent? when does it drop?
|
|
46
|
+
netriage read 12 # what did run 12 look like?
|
|
47
|
+
netriage report 12 # the same run as Markdown, for a ticket
|
|
48
|
+
netriage compare # did the change actually help?
|
|
49
|
+
netriage history # the saved runs
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**→ [GUIDE.md](GUIDE.md)** — every command, every flag, and what each number
|
|
53
|
+
means.
|
|
54
|
+
**→ [TROUBLESHOOTING.md](TROUBLESHOOTING.md)** — what to do when the command
|
|
55
|
+
is not found, or a report looks wrong.
|
|
56
|
+
|
|
57
|
+
## What it will not do
|
|
58
|
+
|
|
59
|
+
It measures and it states what it measured. It does not tell you what to
|
|
60
|
+
change: it does not know the building, the budget or the policy, and a generic
|
|
61
|
+
recommendation is worse than none.
|
|
62
|
+
|
|
63
|
+
A value it could not read shows as `unknown`, never as zero. An interface that
|
|
64
|
+
cannot route is not measured at all, because the probes would silently travel
|
|
65
|
+
over a different one.
|
|
66
|
+
|
|
67
|
+
## License
|
|
68
|
+
|
|
69
|
+
MIT
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Every entry here happened on a real machine. One cause, one fix.
|
|
4
|
+
|
|
5
|
+
The installer checks all of this itself. If it printed `this shell not yet` but
|
|
6
|
+
`a new terminal ok`, you only need a new terminal.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## `netriage: command not found`
|
|
11
|
+
|
|
12
|
+
Installed, but your shell does not look there.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
command -v netriage # nothing? then it is not on PATH
|
|
16
|
+
echo $PATH | tr ':' '\n' | grep local
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
rehash # forget cached command paths
|
|
21
|
+
export PATH="/usr/local/bin:$PATH" # system install
|
|
22
|
+
export PATH="$HOME/.local/bin:$PATH" # per-user install
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Put that line in `~/.zshrc` or `~/.bashrc` to make it stick.
|
|
26
|
+
`sudo bash install.sh` avoids the question: `/usr/local/bin` is on every PATH,
|
|
27
|
+
including sudo's.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Typing `netriage` does nothing, and the folder changes
|
|
32
|
+
|
|
33
|
+
You are in a directory that contains a **folder** called `netriage`, and your
|
|
34
|
+
shell has `AUTO_CD`. zsh sees a name that is not a command, sees a directory
|
|
35
|
+
with that name, and enters it. Nothing is printed.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pwd # did it change to .../netriage?
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**Fix:** the checkout must not be called `netriage`. `push.sh` copies it to
|
|
42
|
+
`~/netriage-src` for this reason:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
mv ~/netriage ~/netriage-src 2>/dev/null || true
|
|
46
|
+
rehash
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## `netriage --version` shows a package path I did not install
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
package /home/you/netriage/netriage <- a checkout, not the install
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`python3 -m netriage` puts the current directory first on `sys.path`. The
|
|
58
|
+
installed command does not: it is a script with a shebang and an explicit
|
|
59
|
+
`sys.path` entry, so it always loads the installed copy.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## `netriage history` is empty although runs happened
|
|
64
|
+
|
|
65
|
+
Before 0.32.0 a `sudo netriage` run wrote a report owned by root, mode 0600.
|
|
66
|
+
The human could not read it, and `history` skipped it.
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
sudo netriage # repairs ownership, then records
|
|
70
|
+
netriage history
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Or by hand:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
sudo chown -R "$USER" ~/Documents/netriage-log
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Since 0.33.0 `history` says so instead of staying silent, and lists the reports
|
|
80
|
+
it could not read.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## `sudo netriage` says command not found
|
|
85
|
+
|
|
86
|
+
You installed for your user only. sudo resets `HOME` and `PATH`, so it cannot
|
|
87
|
+
see `~/.local/bin`.
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
cd ~/netriage-src && sudo bash install.sh
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## `scan` shows only one access point
|
|
96
|
+
|
|
97
|
+
Many drivers answer `iw dev wlan0 scan` with just the BSS you are associated
|
|
98
|
+
with. netriage asks again with `scan flush` and merges NetworkManager's list,
|
|
99
|
+
but a card can still refuse.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
sudo iw dev wlan0 scan flush | grep -c '^BSS'
|
|
103
|
+
nmcli -t -f BSSID,SSID device wifi list
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
If both show one, the neighbourhood really is that empty.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## `unknown (ethtool not installed)` and friends
|
|
111
|
+
|
|
112
|
+
netriage never invents a value. A missing tool shows as `unknown`, never as
|
|
113
|
+
`none` or `0`.
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
sudo apt install -y iw ethtool lldpd dnsutils curl iputils-ping network-manager
|
|
117
|
+
sudo systemctl enable --now lldpd
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## `--json` is refused on `history`, `report`, `compare`, `watch`
|
|
123
|
+
|
|
124
|
+
By design. Only the default run and `scan` produce JSON; the others write text,
|
|
125
|
+
Markdown or CSV. A script that pipes them into `jq` should fail loudly.
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Anything else
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
sudo netriage --debug --redact
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
writes `netriage-YYYYMMDD-NNNN-debug.txt` next to the report: every tool's
|
|
136
|
+
availability, the raw output, and the parsed result with addresses masked.
|
|
137
|
+
Attach that to the issue.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|