Shell: network troubleshooting commands (ping, nslookup and the rest) #90

New Issue

2026-10-07T23:57:11Z

twisla commented

2026-10-07 23:57:11 +00:00

Idea

The Shell (and both consoles) get the commands one reaches for when the network doesn't do what it should: ping, a name lookup, and a few more.

Why

With a VPN (#8), fixed addresses (#7) and a file server (#88) on the device, "is it the network or is it me" comes up, and today the device can only say wifi status and vpn status. Checking that a host answers, that a name resolves, or which way a packet leaves needs another machine.

Wanted

Command	Does
`ping <host> [count]`	ICMP echo: answers, times, loss. Through the tunnel or not, as routed
`nslookup <name>` (or `dig`)	Resolves a name with the DNS servers in use, and says which server answered and how long it took. Optionally `nslookup <name> <server>`

Others worth having

Command	Does	Why
`ifconfig` (or `ip`)	Every interface: Wi-Fi and the tunnel, with address, mask, gateway, MTU, which one is the default route, and the DNS servers	"Which way does it leave" is the first question with a VPN up
`port <host> <port>`	Opens a TCP connection and says whether it was accepted, refused or timed out, and in how long	Tells a dead host from a closed port from a firewall
`traceroute <host>`	The hops to a host	Where it stops
`tls <host> [port]`	A TLS handshake: who the certificate is for, who signed it, when it expires, and whether this device would trust it	IRC, Gemini and updates all fail with "TLS error" today, with no way to see why
`ntp [server]`	Asks a time server and shows the offset from the device's clock	The clock gates the VPN and TLS
`arp`	The neighbours the device has seen on the Wi-Fi	Is the gateway even there
`netstat`	What the device listens on and its open connections	What is exposed right now (the Update Service, the Debug Console, sharing)
`ping -s <size>`	A ping of a given size, not fragmented	Finding the MTU a path really allows, which matters for a tunnel

What's known

lwIP has raw sockets for ICMP (ESP-IDF ships a ping component), dns_gethostbyname, and the interface list; the firmware already takes lwIP's lock where it must (the VPN service).
Each command has to answer later, from another task, to the console that asked: the Shell shows only the replies to its own commands (Console::origin(), as ls and tasks do).
Long ones (ping, traceroute) must be stoppable (cancel, or any key in the Shell) and must not block the main loop: its watchdog allows five seconds.
Tab completes them for free once they are in the help text.
Memory: a TLS handshake is the expensive one (about 52 KB); the others are small.

Questions

Which names: nslookup or dig, ifconfig or ip, port or nc? Familiar names, or one consistent style?
Which of the "others" are in the first version?
Do they also get a place in an App (a "Network" page in System), or the Shell only?
Output for a 38-column screen: one line an answer.

## Idea The Shell (and both consoles) get the commands one reaches for when the network doesn't do what it should: `ping`, a name lookup, and a few more. ## Why With a VPN (#8), fixed addresses (#7) and a file server (#88) on the device, "is it the network or is it me" comes up, and today the device can only say `wifi status` and `vpn status`. Checking that a host answers, that a name resolves, or which way a packet leaves needs another machine. ## Wanted | Command | Does | |---|---| | `ping <host> [count]` | ICMP echo: answers, times, loss. Through the tunnel or not, as routed | | `nslookup <name>` (or `dig`) | Resolves a name with the DNS servers in use, and says which server answered and how long it took. Optionally `nslookup <name> <server>` | ## Others worth having | Command | Does | Why | |---|---|---| | `ifconfig` (or `ip`) | Every interface: Wi-Fi and the tunnel, with address, mask, gateway, MTU, which one is the default route, and the DNS servers | "Which way does it leave" is the first question with a VPN up | | `port <host> <port>` | Opens a TCP connection and says whether it was accepted, refused or timed out, and in how long | Tells a dead host from a closed port from a firewall | | `traceroute <host>` | The hops to a host | Where it stops | | `tls <host> [port]` | A TLS handshake: who the certificate is for, who signed it, when it expires, and whether this device would trust it | IRC, Gemini and updates all fail with "TLS error" today, with no way to see why | | `ntp [server]` | Asks a time server and shows the offset from the device's clock | The clock gates the VPN and TLS | | `arp` | The neighbours the device has seen on the Wi-Fi | Is the gateway even there | | `netstat` | What the device listens on and its open connections | What is exposed right now (the Update Service, the Debug Console, sharing) | | `ping -s <size>` | A ping of a given size, not fragmented | Finding the MTU a path really allows, which matters for a tunnel | ## What's known - lwIP has raw sockets for ICMP (ESP-IDF ships a `ping` component), `dns_gethostbyname`, and the interface list; the firmware already takes lwIP's lock where it must (the VPN service). - Each command has to answer **later, from another task**, to the console that asked: the Shell shows only the replies to its own commands (`Console::origin()`, as `ls` and `tasks` do). - Long ones (`ping`, `traceroute`) must be stoppable (`cancel`, or any key in the Shell) and must not block the main loop: its watchdog allows five seconds. - Tab completes them for free once they are in the `help` text. - Memory: a TLS handshake is the expensive one (about 52 KB); the others are small. ## Questions 1. Which names: `nslookup` or `dig`, `ifconfig` or `ip`, `port` or `nc`? Familiar names, or one consistent style? 2. Which of the "others" are in the first version? 3. Do they also get a place in an App (a "Network" page in System), or the Shell only? 4. Output for a 38-column screen: one line an answer. ## Related #67 (the Shell), #8 (the VPN), #7 (DNS and NTP settings), #2 (SSH), `docs/milestones/N1.md`, `docs/milestones/S1.md`.

twisla added this to the N1 Network tools milestone 2026-10-07 23:57:11 +00:00

twisla added the

area/vpn labels 2026-10-07 23:57:11 +00:00

twisla referenced this issue from a commit

2026-10-08 00:29:07 +00:00