When the internet doesn't work (zev doctor)

"No internet" can mean a dozen different things: the Wi-Fi dropped, the router lost its connection, DNS stopped answering, a proxy app was closed while the system still points at it, a hotel's sign-in page, a clock three days off. Each needs a different fix, and the wrong one wastes an hour. `zev doctor` checks every layer in order and tells you **which one** is broken and why: ```bash zev doctor # check, and say what's wrong zev doctor --fix # fix it, check again, put back any fix that didn't help zev doctor undo # put back what --fix changed ``` ```diagram type: flow title: Where zev doctor looks, from the bottom up --- Connection | Is Wi-Fi joined or a cable plugged in, and did the network give an address? | | 📶 ~ Router | Does the router answer? | | 📡 ~ Internet | Does anything on the internet answer, by address alone? A VPN's leftover kill switch shows up here | | 🌍 ~ DNS | Do names resolve, honestly and quickly? | accent | 🔤 ~ Sign-in, clock, HTTPS | A hotel's sign-in page, a clock that's off, something opening secure connections | | 🔐 ~ Proxy | Does the system send programs to a proxy that isn't there? | accent | 🔀 ~ IPv6, packets, quality | Broken IPv6, big packets that vanish, a slow or unsteady line | good | 📈 ``` A layer is only checked when the ones below it work. If the router doesn't answer, there's no point asking about DNS, and zev doctor doesn't. The first layer that fails is **the cause**, and everything above it is a consequence. ## What it looks like A laptop on a phone's hotspot. Everything works, and one thing is worth fixing: ```text Checking this computer's internet, layer by layer ✓ Connection wlo1, Wi-Fi HomeWiFi, -35 dBm ✓ Address 192.168.1.34 ✓ Router 192.168.1.1 answers ✓ Internet 1.1.1.1 answers in 180 ms ✓ DNS names resolve in 68 ms (127.0.0.53) ✓ Sign-in no sign-in page in the way ✓ Clock right (within 0 s) ✓ HTTPS www.cloudflare.com opens securely ✓ Proxy none set: programs connect directly ✓ Packets 1500 bytes get through ! Quality 126 ms, varies 18 ms, 0 of 8 lost Wi-Fi power saving is on. zev tune check measures it under load; sudo zev tune on fixes what it finds. Worth fixing (Quality): 126 ms, varies 18 ms, 0 of 8 lost zev doctor --fix would: • turn Wi-Fi power saving off, kept only if the line gets steadier sudo zev tune on --quick --only wifi_power --no-service ``` ```diagram type: cards title: How to read a line --- ✓ | Works | Nothing to do | good ! | Worth fixing | It works, but slower or less steady than it should. A warning alone exits with code 0 | warn ✗ | Broken | The first one is the cause. Exit code 1 | bad · | Not checked | A layer below it is broken, or it couldn't be measured | ``` ## How --fix works ```diagram type: sequence title: zev doctor --fix lanes: zev doctor | This computer alt: zev doctor checks every layer, applies the fix for each problem through the zev command made for it, waits, checks every layer again, keeps the fixes whose layer got better, and puts back the ones that didn't change anything; zev doctor undo puts back the rest later --- zev doctor -> This computer : check every layer note zev doctor : DNS: the system's resolver doesn't answer | bad zev doctor -> This computer : zev dns on zev doctor -> This computer : check every layer again note zev doctor : DNS works now: keep it, and write down how to put it back | good note zev doctor : a fix that changed nothing comes off at once | warn ``` Each fix goes through the zev command built for that job (`zev dns on`, `zev vpn off`, `zev proxy share on`, `zev tune on --only …`), so you get their own care too. `zev tune on`, for example, measures before and after and keeps a change only if it helped. Fixes that change system settings need `sudo`. The ones for your desktop don't, and they must not run as root, because they change your own settings. Run `zev doctor --fix` as yourself and it does what it can, then names the `sudo` command for the rest. ## Examples ### The DNS server stopped answering The computer reaches the internet, but no name resolves. DNS servers on the internet answer fine, so only the one this computer was given is broken: ```text ✓ Router 192.168.77.1 answers ✓ Internet 198.51.100.10 answers in 0 ms ✗ DNS names don't resolve: the system's DNS (198.51.100.11) doesn't answer DNS servers on the internet answer (1 ms): only the one this computer was given is broken. The cause (DNS): names don't resolve: the system's DNS (198.51.100.11) doesn't answer zev doctor --fix would: • send names through resolvers that answer, with a fallback sudo zev dns on ``` ```bash sudo zev doctor --fix ``` ```text → send names through resolvers that answer, with a fallback … done Checking again… ✓ DNS names resolve in 5 ms (127.0.0.153) ✓ Fixed: send names through resolvers that answer, with a fallback zev doctor undo puts these back. ✓ All good now. ``` `sudo zev doctor undo` runs `zev dns off`, and the computer's DNS settings are what they were. The same layer also catches a DNS server that **lies**, answering a public name with a private address: ```text The cause (DNS): the system's DNS gives blocked.example a private address (10.10.34.36) ``` ### A proxy app was closed, and the system still points at it This is the most common "no internet" that isn't one. The browser says the connection failed, the internet is fine, and the system proxy still sends everything to a port where nothing listens: ```text ✓ Internet 198.51.100.10 answers in 0 ms ✓ DNS names resolve in 2 ms (198.51.100.11) ✗ Proxy zev proxy system's setting for new sessions points at 127.0.0.1:10808, and nothing answers there Browsers and apps that use it say there's no internet, while the internet works. The proxy app was closed or crashed. ``` ```bash zev doctor --fix # no sudo: it's your own desktop setting ``` ```text ✓ Fixed: turn off zev proxy system's setting for new sessions: nothing answers at 127.0.0.1:10808 ✓ All good now. ``` It checks GNOME's and KDE's system proxy, zev proxy's setting for new sessions, and the `http_proxy`, `https_proxy` and `all_proxy` variables. If the dead port is zev proxy's own (10808) and you have proxies saved, the fix is `zev proxy share on` instead, which starts it again. A variable set in your terminal can't be changed from outside it, so zev doctor tells you what to type: ```text ✗ Proxy $https_proxy in this terminal points at 127.0.0.1:3999, and nothing answers there In this terminal: unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY (and remove them from ~/.bashrc or ~/.profile). ``` When the proxy app is running but can't reach its server, it's a warning instead, and `zev proxy doctor` is the next step. ### A VPN stopped and left everything blocked ```text ✓ Router 192.168.77.1 answers ✗ Internet nothing on the internet answers: zev vpn's kill switch is still on zev vpn stopped without cleaning up, and its kill switch blocks every connection that doesn't go through it. zev doctor --fix would: • remove zev vpn's kill switch and routes sudo zev vpn off ``` If another VPN app takes all traffic and nothing comes back, zev doctor names its tunnel and tells you to reconnect or quit that app. It never touches another program's VPN. ### A hotel, café or office sign-in page ```text ✗ Sign-in a sign-in page holds the connection (a hotel, café or office network) Web pages are sent to http://198.51.100.10/login until you sign in there. zev doctor --fix would: • open the sign-in page (http://198.51.100.10/login) xdg-open http://198.51.100.10/login ``` ### The clock is off Secure sites check the time, so a clock days off makes every certificate look invalid. zev doctor compares the time with a web server's: ```text ✗ Clock this computer's clock is behind by 3 day(s) Secure sites check the time: with the clock this far off, their certificates look invalid. zev doctor --fix would: • set the clock from the network sudo timedatectl set-ntp true ``` ### It's not your computer ```text ✓ Router 192.168.77.1 answers ✗ Internet the router answers, the internet doesn't Your computer is fine: the router or the provider has no connection right now. The cause (Internet): the router answers, the internet doesn't Restart the router; if that doesn't help, ask the provider. ``` Knowing that saves you from reinstalling drivers for nothing. ### Pages start late, or big pages hang ```text ! IPv6 set up, but it goes nowhere Programs try IPv6 first and wait for it to fail: pages start late. ! Packets big packets vanish above 1400 bytes (eth0 sends 1500) Small pages load and big ones hang: the network drops large packets without saying so. zev doctor --fix would: • prefer IPv4, kept only if it helps sudo zev tune on --quick --only prefer_v4 --no-service • let the system find the packet size that gets through sudo zev tune on --quick --only mtu_probing --no-service ``` ## Every problem it knows | Layer | What it finds | The fix | sudo | |---|---|---|---| | Connection | Wi-Fi off, no cable, no network joined | `nmcli radio wifi on` | no | | Address | no address from the router (DHCP), no route | `nmcli device reconnect <device>` | no | | Router | the router doesn't answer | reconnect; otherwise restart the router | no | | Internet | the router has no internet; zev vpn's kill switch or routes left over; another VPN that's stuck | `zev vpn off` for zev's; advice for the rest | yes | | DNS | no answer, blocked port 53, lying answers, slow answers, zev dns's server stopped, zev vpn's DNS left over | `zev dns on` (or `zev vpn off`) | yes | | Sign-in | a captive portal | open the page | no | | Clock | the clock is more than 5 minutes off | `timedatectl set-ntp true` | yes | | HTTPS | a certificate this computer doesn't trust (interception), secure connections cut by name | advice, `zev proxy doctor` | | | Proxy | the system, zev or a variable points at a proxy that isn't there; a proxy that runs but gets nowhere | turn it off, or `zev proxy share on` | no | | IPv6 | set up but goes nowhere | `zev tune on --only prefer_v4` | yes | | Packets | a path MTU black hole | `zev tune on --only mtu_probing` | yes | | Quality | slow, unsteady or lossy line; weak Wi-Fi; Wi-Fi power saving | `zev tune on --only wifi_power`; `zev tune check` for the rest | yes | ## Commands | Command | What it does | |---|---| | `zev doctor` | Check every layer, name the cause and the fix. Changes nothing | | `zev doctor --fix` | Apply the fixes it can, check again, put back any that didn't help | | `sudo zev doctor --fix` | The same, for the fixes that need sudo | | `zev doctor undo` | Put back what `--fix` changed (`sudo` for the ones made with sudo) | | `zev doctor --json` | The same as data: each layer's state, the cause, each fix and its command | ```bash zev doctor --json | jq -r .cause # "dns", "proxy", … or "" when all is well zev doctor --json | jq '.layers[] | select(.state=="bad")' ``` zev doctor runs on Linux. It needs no setup and nothing running, so it works on a computer that has never used zev's network commands. For the line itself, under load, see [A better internet line](/docs/en/tune). For DNS, the proxy and the VPN: [zev dns](/docs/en/dns), [zev proxy](/docs/en/proxy), [zev vpn](/docs/en/vpn).