Measurements

A measurement is one test with one structured result. It records what happened, not what it means: a failed measurement is evidence, and interpreting evidence is the job of later commands. Everything here runs on your machine, and nw sends nothing anywhere except the packets of the tests themselves.

Every measurement has an ID, a type, a status, start and end times, a duration, a target, and either a result or an error. The report schema lists every field.

Statuses

StatusMeaning
successThe measurement completed and the check passed
failureThe measurement ran and the check did not pass; error.code says how
skippedA step it depends on failed, so it did not run; note says why
inconclusiveIt ran but proves nothing, for example a local check that could not read the system; note says why

DNS

nw test dns <host> asks for the A and AAAA records of a name, both at once.

  • The system resolver is always measured first, as the baseline. It uses the operating system’s own resolver, so it behaves like your applications: it honors the hosts file and search domains. The name servers your system is configured with are listed in resolver.servers. The operating system does not report DNS response codes, so for the system baseline an NXDOMAIN and an empty answer are both reported as dns.no_answer.
  • Each --resolver is queried directly, over UDP (retrying over TCP when the answer is truncated) or over TCP for tcp://. These report the exact response code (NOERROR, NXDOMAIN, SERVFAIL, REFUSED), CNAME chains and timings.
  • A name with an A record but no AAAA record is a success. A missing AAAA is normal and is never counted as an IPv6 failure. The per-type result keeps the evidence.
  • Differences between resolvers are observations. Split-horizon DNS, CDNs, caches and geography all produce legitimate differences.
Error codeMeaning
dns.nxdomainThe resolver said the name does not exist
dns.no_answerThe name exists but there were no A or AAAA records (also what the system baseline reports for “not found”)
dns.servfailThe resolver reported a failure while answering
dns.refusedThe resolver refused to answer
dns.timeoutNo response before the deadline
dns.transportThe resolver could not be reached at all
dns.errorAnother response code

TCP

nw test tcp <host:port> resolves the host (a name needs DNS; an IP address does not) and connects to each address on the port, IPv4 and IPv6 separately. The connection is closed right after it opens and nothing is sent.

Error codeMeaning
tcp.refusedThe destination answered that nothing listens on the port
tcp.timeoutNo answer before the deadline (packets dropped or filtered)
tcp.unreachableNo route to the network or host
tcp.resetThe connection was reset
tcp.errorAnother operating system error

TLS

nw test tls <host[:port]> completes a handshake with each address and verifies the certificate chain and the name. Verification is always on, and there is no option to turn it off. The report keeps the certificate details even when verification fails, because they are the evidence: subject, issuer, validity period, names (SANs), and whether the chain verified.

Certificate errors are kept apart from handshake errors, because the causes and next steps differ.

Error codeMeaning
tls.cert_expiredThe certificate is expired or not yet valid
tls.cert_untrustedThe chain does not lead to a trusted authority
tls.hostname_mismatchThe certificate is not valid for the name you asked for
tls.handshake_failureThe handshake failed for another reason, for example an alert from the server, a server that does not speak TLS, or a closed connection
tls.resetThe connection was reset during the handshake
tls.timeoutThe handshake did not finish before the deadline
tls.errorAnother failure

A failed handshake can have many causes: server configuration, client configuration, a proxy, or interference on the path. The report states what was seen and does not guess which.

HTTP

nw test http <url> makes one request, GET unless you pass --method HEAD, and follows up to --max-redirects redirects. The request goes directly: proxy environment variables are ignored, so you measure the path itself.

  • Each request in the chain is a hop with its own timings: DNS, connect, TLS, first byte and total, in milliseconds. A stage that did not happen, such as TLS on plain HTTP, is left out.
  • Up to 1 MiB of the body is read and thrown away, so the total includes the transfer. Bodies, cookies and authorization headers are never stored. Only a short list of diagnostic response headers is kept (server, content type and length, cache control, via, alt-svc, strict transport security, retry-after, date).
  • A response with any status code is a completed measurement. A 503 is a success with status_code: 503; whether that is a problem is judged by nw diagnose; see Findings.
  • Errors from the stages below are reported with their own codes, so an HTTP request that fails in TLS says tls.cert_expired, not a generic HTTP error.
Error codeMeaning
http.timeoutNo complete response before the deadline, after the connection was established
http.redirect_loopA URL was requested twice, or there were more redirects than allowed
http.protocol_errorThe server’s reply was not valid HTTP, or a redirect went somewhere unsupported
http.resetThe connection was reset after it was established
http.errorAnother failure

Plus every dns.*, tcp.* and tls.* code above, when the failure happened in that stage.

Encrypted DNS, probes and DNSSEC

A resolver can also be reached over TLS (tls://host, port 853) or HTTPS (https://host/dns-query, port 443). The query and the reply then cannot be read or altered on the path, and the server’s certificate is verified against the host in the address. A certificate or connection failure shows as dns.transport with the reason in the message. A host name in such an address is resolved by the operating system to connect; that lookup is not measured.

Some measurements are probes: extra, comparative measurements that exist as evidence for the interference rules. They carry params.probe, are listed in the report, and are ignored by the layer summary and by the ordinary rules, so a failed probe never makes a healthy target look broken. The probes are:

params.probeTypeWhat it does
multiple_responsesdnsSends one plain UDP query and keeps listening for 500 ms, recording every reply with its delay
dnssecdnsAsks with DNSSEC requested and records the signature state, the resolver’s validation flag and the CNAME chain. On SERVFAIL it asks again with validation disabled, to tell a validation failure from an ordinary failure
answer_reachabilitytcpConnects to the addresses that two resolvers returned, when the resolvers disagree
sni_target, sni_controltlsRepeats the handshake with the target name, and makes handshakes with a neutral control name, at the same address
legacy_tlstlsOffers only TLS 1.0 and 1.1 (verification stays on)
plain_httphttpMakes the same request over http that was made over https
http3httpMakes a HEAD request over HTTP/3 (QUIC, UDP) to one address

Local checks

nw doctor also inspects this machine’s own network setup. These measurements have type local, scope local, and a params.check of interfaces, route, resolvers or proxy. Their results record counts and kinds, never addresses or interface names, so a report can be shared safely. They read the operating system and send nothing; see Platform support for what each platform can read.

  • interfaces: is any interface up, not loopback, with an address that is not link-local? Counts of interfaces and the address families in use.
  • route: does the operating system have a default route for IPv4 and for IPv6? It asks which route it would use and sends no packet.
  • resolvers: how many DNS servers are configured, by kind (private, global, loopback), and where the configuration was read from.
  • proxy: whether a proxy is set. It is always a success: a proxy is context, not a fault. Credentials are never kept.

A local check that could not read the system is inconclusive, with the reason in note, rather than a failure.

Error codeMeaning
local.no_interfaceNo interface is up with an address that can reach beyond this machine
local.no_routeThe operating system has no route to the internet for IPv4 or IPv6
local.no_resolverThe operating system has no DNS server configured

Deadlines

--timeout (default 10 seconds) is the deadline of each measurement. Press Ctrl-C to stop a run: nw closes its connections, prints nothing partial, and exits with status 130.