Diagnostics — tools#

Two commands the router runs on your behalf: a traceroute, and a name lookup through the router's own resolver. Both matter because they answer the question from where the router sits, which is frequently not what your laptop sees.

Traceroute from the router#

Type a name or an address and press Run (or Enter). The agent posts it to the router's own traceroute endpoint and returns the text verbatim, which the page prints in a monospace block.

The field hint sets the expectation: "a name or address; up to a minute for a path that stops answering". That is real — thirty hops of timeouts takes a while, which is why this call uses the agent's long-running HTTP client rather than the ordinary read client — agent/vyos.go, the slow tier.

The host is validated before it goes anywhere. It must match ^[A-Za-z0-9.:_-]{1,253}$ — a name or an address, and nothing a shell would read — hostArg in agent/gaps.go. Anything else is refused with a 400 naming the field.

It needs the operator role. The route is POST /api/diagnostics/traceroute behind writeable. Nothing is configured by a traceroute, but it is a command executed on the router, and this product puts commands on the operator side of the line. A viewer sees the button disabled with the reason: "Operator role runs commands on the router".

Failures are shown as text, not swallowed: an unreachable router gives "traceroute: …" with the transport error, and a router that refused the command returns its own words.

The equivalent at the console:

traceroute 192.0.2.1

DNS lookup through the router's resolver#

Type a name and press Look up. The agent runs show host lookup <name> and returns three things: the addresses it could parse out, the raw output, and the name you asked for.

The addresses appear as green badges; a name that resolved to nothing shows one amber badge reading no address. The raw output is printed below, because the sentence the resolver produced is often more informative than the addresses — a SERVFAIL or a NXDOMAIN says something a missing badge does not.

Parsing is deliberately narrow: the agent recognises the two lines VyOS prints —

example.com has address 192.0.2.1
example.com has IPv6 address 2001:db8::1

— and takes the last field of each. Anything else stays in the raw output rather than being guessed at — handleHostLookup in agent/gaps.go.

This needs only the viewer role. It is GET /api/diagnostics/lookup?host=…, a read. The same hostArg validation applies.

The point of running it here rather than on your laptop is in the field's own hint: "what the router's own clients would get". If the router forwards to a filtering resolver — an AdGuard Home or Pi-hole container, say — this is the answer that filter gives, and it is frequently not the answer your workstation gets.

The equivalent at the console:

show host lookup example.com

What this tab will not do#

• No ping. There is no ICMP echo tool in the product.
• No source selection. You cannot choose which interface or source address the traceroute leaves from; it is the router's default path.
• No protocol or port options. No UDP/TCP/ICMP switch, no port, no max-hop setting.
• No record-type choice on the lookup. It is show host lookup, which is A and AAAA. For anything else — MX, TXT, a specific server — use dig at the console.
• Nothing is kept. Results live in the page until you navigate away.

See also#

• Diagnostics — the other five tabs.
• Diagnostics — neighbours — when the question is "is that host even on the wire".
• Apps — the filtering resolvers whose answers this lookup would show.

Checked against ui/src/pages/Diagnostics.tsx, agent/gaps.go, agent/main.go, agent/vyos.go.