Public Access
Shell: ping, nslookup, port, traceroute, ifconfig and arp (#90)
Network troubleshooting from the device itself, in the Shell and over both consoles. ping, nslookup, port and traceroute each run on a task of their own and print as they go, to the console that asked; one at a time, and `cancel` stops it. ifconfig and arp answer at once: the interfaces (Wi-Fi and the VPN), which is the default route, the DNS servers, the neighbours. nslookup asks a DNS server itself, so it can say which server answered and in how long, and ask another. A sized ping finds what a tunnel really carries. With a how-to, "When the network doesn't work", and the rest of the docs. tls, ntp and netstat from the issue's list are not in this. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
This commit is contained in:
Claude Opus 5.5
@@ -39,6 +39,8 @@ install <path.ota> Update from SD
|
||||
update check | update list | update status | update install <tag> the project's releases on Gitea
|
||||
sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal
|
||||
Irc | Wifi | Gnss | Gemini | Lora | Storage | Notes | Shell | System | Settings open that App: a capital letter is an App, not a command
|
||||
ping <host> [count] [size] | nslookup <name> [server] | port <host> <port> | traceroute <host> | cancel is it there, does its name resolve, is its port open, which way; one at a time
|
||||
ifconfig | arp the interfaces (Wi-Fi and the VPN), their addresses, the default route and the DNS servers; the neighbours heard
|
||||
vpn status | vpn up [seconds] | vpn down | vpn import [path] | vpn forget | vpn auto on|off the WireGuard tunnel (Settings > VPN); import reads /vpn/wg0.conf; with seconds, it goes down by itself
|
||||
debug status | debug off [seconds] the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back
|
||||
debug on | debug token <16 to 64 characters> | debug token new (USB serial only) switch it on, set its token
|
||||
@@ -110,6 +112,8 @@ In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few r
|
||||
| `coredump erase` | Forgets the core dump |
|
||||
| `loop spin on` / `loop spin off` | Make the main loop spin without resting, to compare load and radio noise |
|
||||
| `crash abort` / `crash wdt` | Crash on purpose, or hang the main loop until the watchdog fires |
|
||||
| `ping <host> [count] [size]` / `nslookup <name> [server]` / `port <host> <port>` / `traceroute <host>` / `cancel` | Network troubleshooting (issue #90): does a host answer and how fast; a name's addresses, from which DNS server and in how long; is a TCP port open, refused or silent; the routers on the way. Each runs on a task of its own and prints as it goes, one at a time; `cancel` stops it |
|
||||
| `ifconfig` / `arp` | The interfaces (Wi-Fi and the VPN) with their addresses, MTU, which is the default route, and the DNS servers; the neighbours heard on the Wi-Fi |
|
||||
| `vpn status` / `vpn up [seconds]` / `vpn down` / `vpn import [path]` / `vpn forget` / `vpn auto on\|off` | The WireGuard tunnel: its state, on (for that many seconds, then off by itself: for trying a configuration from afar), off, read a `.conf` from the card (`/vpn/wg0.conf`), erase it, start with Wi-Fi. No key is ever printed |
|
||||
| `debug status` / `debug off [seconds]` | The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long |
|
||||
| `debug on` / `debug token <value>` / `debug token new` | USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed |
|
||||
|
||||
@@ -8,7 +8,7 @@ docs = true
|
||||
source = "docs/milestones/N1.md"
|
||||
tag = "N1"
|
||||
+++
|
||||
**Status:** in progress. The WireGuard tunnel (issue #8) shipped as **v0.19.0**. SSH (#2) is not started.
|
||||
**Status:** in progress. The WireGuard tunnel (issue #8) shipped as **v0.19.0**. The network troubleshooting commands (issue #90) are built: `ping`, `nslookup`, `port`, `traceroute`, `ifconfig`, `arp`; `tls`, `ntp` and `netstat` are still to do. SSH (#2) is not started.
|
||||
|
||||
**Goal:** reach things from the device that aren't on the Wi-Fi it happens to be on, and keep its traffic private on a network that isn't yours.
|
||||
|
||||
@@ -89,3 +89,43 @@ The test keys were made for the purpose and deleted. Two rounds: first with the
|
||||
**Taking the tunnel down reconnected Wi-Fi.** The first version gave DHCP's DNS servers back by asking for a new lease, which is how the Wi-Fi settings do it, and which drops every connection: the Debug Console session that had typed `vpn down` among them. The servers that were there are now simply remembered and put back.
|
||||
|
||||
**"What AllowedIPs say" was more than the network stack can do.** The design round promised split tunnels by AllowedIPs. lwIP has no routing table: it can send by an interface's subnet, or by default. So it is one subnet or everything, and the import tells which.
|
||||
|
||||
## Network troubleshooting commands (issue #90)
|
||||
|
||||
With a tunnel, fixed addresses and a file server on the device, "is it the network or is it me" needed another machine to answer.
|
||||
|
||||
### Decisions (2026-10-08; built on the issue's list, without a round of questions)
|
||||
|
||||
- **The familiar names:** `ping`, `nslookup`, `traceroute`, `ifconfig`, `arp`. `port <host> <port>` for "is that TCP port open", which has no single familiar name.
|
||||
- **In this version:** those six. **Not yet:** `tls` (why a certificate fails), `ntp` (the clock's offset), `netstat` (what listens). The issue stays open for them.
|
||||
- **Commands only,** in the Shell and over both consoles; no page in an App.
|
||||
- **One line an answer, short:** a Shell line is 38 characters.
|
||||
|
||||
### As built
|
||||
|
||||
- **`lib/net/src/net_probe.h`** (host-tested, 5 tests): what was typed; the ICMP echo request and what answers it, a router's "time exceeded" included; the DNS query and its answer, with the pointers names are shortened by.
|
||||
- **`NetTools`** (`src/services/net_tools`): `ping`, `nslookup`, `port` and `traceroute` each run on a task of their own, made for the command and gone after it, printing to the console that asked (the Shell shows only its own replies). One at a time; `cancel` stops it within a fifth of a second.
|
||||
- **`ping`** and **`traceroute`** share a raw ICMP socket: a traceroute is echo requests allowed one hop, then two, then three, and the routers' complaints are the list.
|
||||
- **`nslookup`** asks one server itself, over UDP, and so can say which server answered and how long it took, which the system's resolver doesn't; and it can ask a server that isn't the configured one.
|
||||
- **`port`** is a connection attempt that is not waited for: open, refused, or five seconds of nothing.
|
||||
- **`ifconfig`** and **`arp`** read lwIP's own lists, with its lock held.
|
||||
- **Cost:** 12 KB of flash. A 6 KB task while a command runs (2.6 KB of it never used), nothing otherwise.
|
||||
|
||||
### Checks on the device (2026-10-08, with the VPN up and everything routed through it)
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| `ifconfig` | `vpn 10.9.0.2/32 mtu 1420, up, default route`; `wifi ... gw ... mtu 1500, up`; the DNS server |
|
||||
| `arp` | The gateway and one other machine |
|
||||
| `ping` of a neighbour, of a name | 4 of 4 in 3 to 4 ms; 3 of 3 in about 50 ms |
|
||||
| `ping 9.9.9.9 2 1392`, then `1393` | Both back; neither back: the tunnel carries 1420 bytes exactly |
|
||||
| `nslookup` | The address, the server and the time; an alias followed; with another server; "there is no nope.invalid" |
|
||||
| `port` | `open, 52 ms`; `refused`; "no answer in 5 s"; "doesn't resolve" |
|
||||
| `traceroute 9.9.9.9` | Nine hops, the tunnel's server first, "arrived" |
|
||||
| A second command while a ping runs | "another one is running: `cancel` stops it" |
|
||||
| `cancel` | "stopped", with the count so far |
|
||||
| In the Shell | Tab completes them; the lines appear there and only there |
|
||||
|
||||
**Not checked:** without the VPN (every check went through the tunnel, or to the local network); a network that drops ICMP; the commands in Safe Mode, where they are not offered.
|
||||
|
||||
**Found on the way:** a refused connection is reported by lwIP as "reset", not "refused"; the first version called it "no route". And the header for the tested half was first given the same name as the service's, which makes a file include itself: the same mistake as an hour before, in the same way.
|
||||
|
||||
@@ -73,6 +73,10 @@ In the Storage App, press <kbd>w</kbd>: the device serves a small web page to an
|
||||
|
||||
<kbd>Fn</kbd> + <kbd>p</kbd>, on any screen. The picture goes to `/screenshots` on the SD card. See [Take a screenshot](/howto/screenshot/).
|
||||
|
||||
## The network doesn't work: how do I find out why?
|
||||
|
||||
From the device itself, in the Shell: `ifconfig`, `ping`, `nslookup`, `port` and `traceroute`. [When the network doesn't work](/howto/network-check/) puts them in order.
|
||||
|
||||
## Do I need an SD card?
|
||||
|
||||
For the radio, GNSS position, Wi-Fi tools, IRC chat and Gemini browsing, no. For anything that is *kept*, yes: notes, IRC logs, Wi-Fi scan logs, GNSS Tracks, LoRa captures, saved Gemini pages and update files. See [Find your files on the SD card](/howto/sd-files/).
|
||||
|
||||
@@ -43,6 +43,21 @@ Type an App's name **with a capital letter** to open it, without going back to t
|
||||
|
||||
The capital is the difference: every command is in small letters, every App starts with a capital. <kbd>Tab</kbd> completes them too.
|
||||
|
||||
## The network
|
||||
|
||||
For the day the network doesn't do what it should. Each of the first four takes a moment and prints as it goes; one runs at a time, and `cancel` stops it.
|
||||
|
||||
| Command | Tells you |
|
||||
|---|---|
|
||||
| `ping 10.9.0.1` | Whether a host answers, and how fast. A count and a size may follow: `ping 10.9.0.1 10 1392` |
|
||||
| `nslookup roro9stack.net` | A name's addresses, which DNS server answered and in how long. Another server may follow: `nslookup roro9stack.net 9.9.9.9` |
|
||||
| `port git.twis.la 443` | Whether a TCP port is **open**, **refused** (the host is there, nothing listens) or silent (down, or filtered) |
|
||||
| `traceroute 9.9.9.9` | The routers on the way, one a line |
|
||||
| `ifconfig` | The interfaces (Wi-Fi, and the [VPN](/guide/vpn/) when it is up), their addresses, **which one is the default route**, and the DNS servers |
|
||||
| `arp` | The neighbours heard on the Wi-Fi: is the gateway there at all |
|
||||
|
||||
A host can be a name or an address. [When the network doesn't work](/howto/network-check/) puts them in order.
|
||||
|
||||
## Deleting
|
||||
|
||||
`rm` works as it does on Unix, with one addition: it asks.
|
||||
|
||||
@@ -60,6 +60,8 @@ vpn auto on|off start with Wi-Fi
|
||||
|
||||
`vpn up` with a number of seconds is for trying a new configuration from a distance: if it cuts you off, it comes back by itself.
|
||||
|
||||
To see it work: `ifconfig` shows the tunnel and whether it is the default route, and `ping`, `nslookup`, `port` and `traceroute` go the way real traffic goes. See [When the network doesn't work](/howto/network-check/).
|
||||
|
||||
## Limits
|
||||
|
||||
One tunnel, to one server. IPv4 only: IPv6 addresses in the file are left out. The server can be an address or a name.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
+++
|
||||
title = "How-tos"
|
||||
description = "Short recipes for things you will want to do: move files with your phone, set up the VPN, take a screenshot, record a track, capture radio packets, and what to try when something does not work."
|
||||
description = "Short recipes for things you will want to do: move files with your phone, set up the VPN, take a screenshot, find out why the network doesn't work, record a track, capture radio packets, and what to try when something does not work."
|
||||
template = "guide-index.html"
|
||||
page_template = "guide-page.html"
|
||||
sort_by = "weight"
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
+++
|
||||
title = "When the network doesn't work"
|
||||
description = "Find out where it stops, from the device itself: the Wi-Fi, the gateway, the names, the port, the route, the tunnel."
|
||||
weight = 12
|
||||
[extra]
|
||||
tag = "Network"
|
||||
+++
|
||||
|
||||
Open the [Shell](/guide/shell/) and go down this list. Each step says what a good answer looks like; the first bad one is where the trouble is.
|
||||
|
||||
1. **`ifconfig`**: is there an address, and where does traffic go?
|
||||
|
||||
```
|
||||
ifconfig: vpn 10.9.0.2/32 mtu 1420, up, default route
|
||||
ifconfig: wifi 172.16.42.25/21 gw 172.16.42.1 mtu 1500, up
|
||||
ifconfig: dns 10.9.0.1
|
||||
```
|
||||
|
||||
No `wifi` line, or `down`: it is the Wi-Fi itself ([Settings](/guide/settings/#wi-fi)). "default route" says which way everything leaves: on `vpn`, everything goes through the tunnel.
|
||||
|
||||
2. **`ping` the gateway** (the `gw` address): is the local network there?
|
||||
|
||||
```
|
||||
ping: 4/4 back, 0% lost, 3/3/4 ms
|
||||
```
|
||||
|
||||
Nothing back: `arp` shows whether the gateway was ever heard.
|
||||
|
||||
3. **`ping 9.9.9.9`**: is the internet there, without names? If the gateway answers and this doesn't, the trouble is beyond your network, or in the tunnel.
|
||||
|
||||
4. **`nslookup roro9stack.net`**: do names resolve?
|
||||
|
||||
```
|
||||
nslookup: 10.9.0.1 answered in 6 ms
|
||||
nslookup: 65.21.233.110
|
||||
```
|
||||
|
||||
"no answer from": that DNS server is unreachable. Try another to compare: `nslookup roro9stack.net 9.9.9.9`. If that one answers, change the servers ([DNS and NTP](/guide/settings/#dns-and-ntp)).
|
||||
|
||||
5. **`port <host> <port>`**: is the service there? `open` is good. `refused` means the machine is up and nothing listens on that port. "no answer" means it is down, or a firewall drops it.
|
||||
|
||||
6. **`traceroute <host>`**: where does it stop? The last router that answers is the last one that works.
|
||||
|
||||
## With the VPN up
|
||||
|
||||
- `ifconfig` shows the `vpn` line, and "default route" on it if everything goes through.
|
||||
- `ping` the server's tunnel address first: that is the tunnel itself.
|
||||
- **Finding the tunnel's real packet size:** `ping 9.9.9.9 2 1392` (1392 bytes, plus 28 of headers, is 1420: WireGuard's usual). If that comes back and 1393 doesn't, the tunnel carries 1420. If 1392 doesn't come back either, try smaller: something on the way allows less, and the server's configuration wants a lower `MTU`.
|
||||
|
||||
## Good to know
|
||||
|
||||
- `cancel` stops a `ping` or a `traceroute`.
|
||||
- Some hosts and routers don't answer pings or traceroutes at all; a silent hop (`*`) in the middle of a route that goes on is normal.
|
||||
- The same commands work over the [Debug Console](/dev/debug/).
|
||||
@@ -18,7 +18,7 @@ You need a WireGuard server, and a **client configuration** made on it for the C
|
||||
|
||||
## Check it
|
||||
|
||||
From another machine on the VPN, ping the Cardputer's tunnel address (the `Address` line of the file). Or on the device, in the [Shell](/guide/shell/): `vpn status`.
|
||||
On the device, in the [Shell](/guide/shell/): `vpn status`, then `ifconfig` (a `vpn` line, up) and `ping` the server's tunnel address. Or from another machine on the VPN, ping the Cardputer's tunnel address (the `Address` line of the file). More in [When the network doesn't work](/howto/network-check/).
|
||||
|
||||
## If it stays dim
|
||||
|
||||
|
||||
Reference in New Issue
Block a user