docs: correct low MTU troubleshooting language (#17468)

spikecurtis · EdwardAngert · web-flow · commit 0ef7d0b3e5b6 · 2025-04-23T10:00:33.000+04:00
Fixes docs troubleshooting language around low MTU. In fact, we see
conenctions hanging rather than just showing low performance, since
packets are dropped rather than fragmented.

---------

Co-authored-by: Edward Angert &lt;EdwardAngert@users.noreply.github.com&gt;
Co-authored-by: EdwardAngert &lt;17991901+EdwardAngert@users.noreply.github.com&gt;
diff --git a/docs/admin/networking/troubleshooting.md b/docs/admin/networking/troubleshooting.md
@@ -95,14 +95,27 @@ the NAT configuration, or deploy an internal STUN server.
 
 If a network interface on the side of either the client or agent has an MTU
 smaller than 1378, any direct connections form may have degraded quality or
-performance, as IP packets are fragmented. `coder ping` will indicate if this is
-the case by inspecting network interfaces on both the client and the workspace
-agent.
+might hang entirely.
 
-If another interface cannot be used, and the MTU cannot be changed, you may need
-to disable direct connections, and relay all traffic via DERP instead, which
+Use `coder ping` to check for MTU issues, as it inspects
+network interfaces on both the client and the workspace agent:
+
+```console
+$ coder ping my-workspace
+...
+Possible client-side issues with direct connection:
+
+ - Network interface utun0 has MTU 1280 (less than 1378), which may degrade the quality of direct connections or render them unusable.
+```
+
+If another interface cannot be used, and the MTU cannot be changed, you should
+disable direct connections and relay all traffic via DERP instead, which
 will not be affected by the low MTU.
 
+To disable direct connections, set the
+[`--block-direct-connections`](../../reference/cli/server.md#--block-direct-connections)
+flag or `CODER_BLOCK_DIRECT` environment variable on the Coder server.
+
 ## Throughput
 
 The `coder speedtest <workspace>` command measures the throughput between the
