Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit cd7ce8e

Browse files
ethanndicksonethanndickson
authored
docs: add networking troubleshooting page (#14548)
1 parent 84922e2 commit cd7ce8e

File tree

5 files changed

+154
-45
lines changed

5 files changed

+154
-45
lines changed

‎cli/cliui/agent.go

+23-9
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ func PeerDiagnostics(w io.Writer, d tailnet.PeerDiagnostics) {
309309
_, _ = fmt.Fprint(w, "✘ not connected to DERP\n")
310310
}
311311
if d.SentNode {
312-
_, _ = fmt.Fprint(w, "✔ sent local data to Coder networking coodinator\n")
312+
_, _ = fmt.Fprint(w, "✔ sent local data to Coder networking coordinator\n")
313313
} else {
314314
_, _ = fmt.Fprint(w, "✘ have not sent local data to Coder networking coordinator\n")
315315
}
@@ -394,12 +394,18 @@ func (d ConnDiags) splitDiagnostics() (general, client, agent []string) {
394394
for _, msg := range d.AgentNetcheck.Interfaces.Warnings {
395395
agent = append(agent, msg.Message)
396396
}
397+
if len(d.AgentNetcheck.Interfaces.Warnings) > 0 {
398+
agent[len(agent)-1] += "\nhttps://coder.com/docs/networking/troubleshooting#low-mtu"
399+
}
397400
}
398401

399402
if d.LocalInterfaces != nil {
400403
for _, msg := range d.LocalInterfaces.Warnings {
401404
client = append(client, msg.Message)
402405
}
406+
if len(d.LocalInterfaces.Warnings) > 0 {
407+
client[len(client)-1] += "\nhttps://coder.com/docs/networking/troubleshooting#low-mtu"
408+
}
403409
}
404410

405411
if d.PingP2P && !d.Verbose {
@@ -414,37 +420,45 @@ func (d ConnDiags) splitDiagnostics() (general, client, agent []string) {
414420
}
415421

416422
if d.ConnInfo.DisableDirectConnections {
417-
general = append(general, "❗ Your Coder administrator has blocked direct connections")
423+
general = append(general, "❗ Your Coder administrator has blocked direct connections\n"+
424+
" https://coder.com/docs/networking/troubleshooting#disabled-deployment-wide")
418425
if !d.Verbose {
419426
return general, client, agent
420427
}
421428
}
422429

423430
if !d.ConnInfo.DERPMap.HasSTUN() {
424-
general = append(general, "The DERP map is not configured to use STUN")
431+
general = append(general, "❗ The DERP map is not configured to use STUN\n"+
432+
" https://coder.com/docs/networking/troubleshooting#no-stun-servers")
425433
} else if d.LocalNetInfo != nil && !d.LocalNetInfo.UDP {
426-
client = append(client, "Client could not connect to STUN over UDP")
434+
client = append(client, "Client could not connect to STUN over UDP\n"+
435+
" https://coder.com/docs/networking/troubleshooting#udp-blocked")
427436
}
428437

429438
if d.LocalNetInfo != nil && d.LocalNetInfo.MappingVariesByDestIP.EqualBool(true) {
430-
client = append(client, "Client is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers")
439+
client = append(client, "Client is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers\n"+
440+
" https://coder.com/docs/networking/troubleshooting#Endpoint-Dependent-Nat-Hard-NAT")
431441
}
432442

433443
if d.AgentNetcheck != nil && d.AgentNetcheck.NetInfo != nil {
434444
if d.AgentNetcheck.NetInfo.MappingVariesByDestIP.EqualBool(true) {
435-
agent = append(agent, "Agent is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers")
445+
agent = append(agent, "Agent is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers\n"+
446+
" https://coder.com/docs/networking/troubleshooting#Endpoint-Dependent-Nat-Hard-NAT")
436447
}
437448
if !d.AgentNetcheck.NetInfo.UDP {
438-
agent = append(agent, "Agent could not connect to STUN over UDP")
449+
agent = append(agent, "Agent could not connect to STUN over UDP\n"+
450+
" https://coder.com/docs/networking/troubleshooting#udp-blocked")
439451
}
440452
}
441453

442454
if d.ClientIPIsAWS {
443-
client = append(client, "Client IP address is within an AWS range (AWS uses hard NAT)")
455+
client = append(client, "Client IP address is within an AWS range (AWS uses hard NAT)\n"+
456+
" https://coder.com/docs/networking/troubleshooting#Endpoint-Dependent-Nat-Hard-NAT")
444457
}
445458

446459
if d.AgentIPIsAWS {
447-
agent = append(agent, "Agent IP address is within an AWS range (AWS uses hard NAT)")
460+
agent = append(agent, "Agent IP address is within an AWS range (AWS uses hard NAT)\n"+
461+
" https://coder.com/docs/networking/troubleshooting#Endpoint-Dependent-Nat-Hard-NAT")
448462
}
449463
return general, client, agent
450464
}

‎cli/cliui/agent_test.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -533,7 +533,7 @@ func TestPeerDiagnostics(t *testing.T) {
533533
LastWireguardHandshake: time.Time{},
534534
},
535535
want: []*regexp.Regexp{
536-
regexp.MustCompile(`^✔ sent local data to Coder networking coodinator$`),
536+
regexp.MustCompile(`^✔ sent local data to Coder networking coordinator$`),
537537
},
538538
},
539539
{

‎docs/manifest.json

+5
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,11 @@
351351
"title": "STUN and NAT",
352352
"description": "Learn how Coder establishes direct connections",
353353
"path": "./networking/stun.md"
354+
},
355+
{
356+
"title": "Troubleshooting",
357+
"description": "Troubleshoot networking issues in Coder",
358+
"path": "./networking/troubleshooting.md"
354359
}
355360
]
356361
},

‎docs/networking/index.md

+1-35
Original file line numberDiff line numberDiff line change
@@ -169,41 +169,7 @@ with security policies. In these cases, pass the `--browser-only` flag to
169169
With browser-only connections, developers can only connect to their workspaces
170170
via the web terminal and [web IDEs](../ides/web-ides.md).
171171

172-
## Troubleshooting
173-
174-
The `coder ping -v <workspace>` will ping a workspace and return debug logs for
175-
the connection. We recommend running this command and inspecting the output when
176-
debugging SSH connections to a workspace. For example:
177-
178-
```console
179-
$ coder ping -v my-workspace
180-
181-
2023-06-21 17:50:22.412 [debu] wgengine: ping(fd7a:115c:a1e0:49d6:b259:b7ac:b1b2:48f4): sending disco ping to [cFYPo] ...
182-
pong from my-workspace proxied via DERP(Denver) in 90ms
183-
2023-06-21 17:50:22.503 [debu] wgengine: magicsock: closing connection to derp-13 (conn-close), age 5s
184-
2023-06-21 17:50:22.503 [debu] wgengine: magicsock: 0 active derp conns
185-
2023-06-21 17:50:22.504 [debu] wgengine: wg: [v2] Routine: receive incoming v6 - stopped
186-
2023-06-21 17:50:22.504 [debu] wgengine: wg: [v2] Device closed
187-
```
188-
189-
The `coder speedtest <workspace>` command measures user <-> workspace
190-
throughput. E.g.:
191-
192-
```
193-
$ coder speedtest dev
194-
29ms via coder
195-
Starting a 5s download test...
196-
INTERVAL TRANSFER BANDWIDTH
197-
0.00-1.00 sec 630.7840 MBits 630.7404 Mbits/sec
198-
1.00-2.00 sec 913.9200 MBits 913.8106 Mbits/sec
199-
2.00-3.00 sec 943.1040 MBits 943.0399 Mbits/sec
200-
3.00-4.00 sec 933.3760 MBits 933.2143 Mbits/sec
201-
4.00-5.00 sec 848.8960 MBits 848.7019 Mbits/sec
202-
5.00-5.02 sec 13.5680 MBits 828.8189 Mbits/sec
203-
----------------------------------------------------
204-
0.00-5.02 sec 4283.6480 MBits 853.8217 Mbits/sec
205-
```
206-
207172
## Up next
208173

209174
- Learn about [Port Forwarding](./port-forwarding.md)
175+
- Troubleshoot [Networking Issues](./troubleshooting.md)

‎docs/networking/troubleshooting.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Troubleshooting
2+
3+
`coder ping <workspace>` will ping the workspace agent and print diagnostics on
4+
the state of the connection. These diagnostics are created by inspecting both
5+
the client and agent network configurations, and provide insights into why a
6+
direct connection may be impeded, or why the quality of one might be degraded.
7+
8+
The `-v/--verbose` flag can be appended to the command to print client debug
9+
logs.
10+
11+
```console
12+
$ coder ping dev
13+
pong from workspace proxied via DERP(Council Bluffs, Iowa) in 42ms
14+
pong from workspace proxied via DERP(Council Bluffs, Iowa) in 41ms
15+
pong from workspace proxied via DERP(Council Bluffs, Iowa) in 39ms
16+
✔ preferred DERP region: 999 (Council Bluffs, Iowa)
17+
✔ sent local data to Coder networking coordinator
18+
✔ received remote agent data from Coder networking coordinator
19+
preferred DERP region: 999 (Council Bluffs, Iowa)
20+
endpoints: x.x.x.x:46433, x.x.x.x:46433, x.x.x.x:46433
21+
✔ Wireguard handshake 11s ago
22+
23+
❗ You are connected via a DERP relay, not directly (p2p)
24+
Possible client-side issues with direct connection:
25+
- Network interface utun0 has MTU 1280, (less than 1378), which may degrade the quality of direct connections
26+
27+
Possible agent-side issues with direct connection:
28+
- Agent is potentially behind a hard NAT, as multiple endpoints were retrieved from different STUN servers
29+
- Agent IP address is within an AWS range (AWS uses hard NAT)
30+
```
31+
32+
## Common Problems with Direct Connections
33+
34+
### Disabled Deployment-wide
35+
36+
Direct connections can be disabled at the deployment level by setting the
37+
`CODER_BLOCK_DIRECT` environment variable or the `--block-direct-connections`
38+
flag on the server. When set, this will be reflected in the output of
39+
`coder ping`.
40+
41+
### UDP Blocked
42+
43+
Some corporate firewalls block UDP traffic. Direct connections require UDP
44+
traffic to be allowed between the client and agent, as well as between the
45+
client/agent and STUN servers in most cases. `coder ping` will indicate if
46+
either the Coder agent or client had issues sending or receiving UDP packets to
47+
STUN servers.
48+
49+
If this is the case, you may need to add exceptions to the firewall to allow UDP
50+
for Coder workspaces, clients, and STUN servers.
51+
52+
### Endpoint-Dependent NAT (Hard NAT)
53+
54+
Hard NATs prevent public endpoints gathered from STUN servers from being used by
55+
the peer to establish a direct connection. Typically, if only one side of the
56+
connection is behind a hard NAT, direct connections can still be established
57+
easily. However, if both sides are behind hard NATs, direct connections may take
58+
longer to establish or may not be possible at all.
59+
60+
`coder ping` will indicate if it's possible the client or agent is behind a hard
61+
NAT.
62+
63+
Learn more about [STUN and NAT](./stun.md).
64+
65+
### No STUN Servers
66+
67+
If there are no STUN servers available within a deployment's DERP MAP, direct
68+
connections may not be possible. Notable exceptions are if the client and agent
69+
are on the same network, or if either is able to use UPnP instead of STUN to
70+
resolve the public IP of the other. `coder ping` will indicate if no STUN
71+
servers were found.
72+
73+
### Endpoint Firewalls
74+
75+
Direct connections may also be impeded if one side is behind a hard NAT and the
76+
other is running a firewall that blocks ingress traffic from unknown 5-tuples
77+
(Protocol, Source IP, Source Port, Destination IP, Destination Port).
78+
79+
If this is suspected, you may need to add an exception for Coder to the
80+
firewall, or reconfigure the hard NAT.
81+
82+
### VPNs
83+
84+
If a VPN is the default route for all IP traffic, it may interfere with the
85+
ability for clients and agents to form direct connections. This happens if the
86+
NAT does not permit traffic to be
87+
['hairpinned'](./stun.md#3-direct-connections-with-vpn-and-nat-hairpinning) from
88+
the public IP address of the NAT (determined via STUN) to the internal IP
89+
address of the agent.
90+
91+
If this is the case, you may need to add exceptions to the VPN for Coder, modify
92+
the NAT configuration, or deploy an internal STUN server.
93+
94+
### Low MTU
95+
96+
If a network interface on the side of either the client or agent has an MTU
97+
smaller than 1378, any direct connections form may have degraded quality or
98+
performance, as IP packets are fragmented. `coder ping` will indicate if this is
99+
the case by inspecting network interfaces on both the client and the workspace
100+
agent.
101+
102+
If another interface cannot be used, and the MTU cannot be changed, you may need
103+
to disable direct connections, and relay all traffic via DERP instead, which
104+
will not be affected by the low MTU.
105+
106+
## Throughput
107+
108+
The `coder speedtest <workspace>` command measures the throughput between the
109+
client and the workspace agent.
110+
111+
```console
112+
$ coder speedtest workspace
113+
29ms via coder
114+
Starting a 5s download test...
115+
INTERVAL TRANSFER BANDWIDTH
116+
0.00-1.00 sec 630.7840 MBits 630.7404 Mbits/sec
117+
1.00-2.00 sec 913.9200 MBits 913.8106 Mbits/sec
118+
2.00-3.00 sec 943.1040 MBits 943.0399 Mbits/sec
119+
3.00-4.00 sec 933.3760 MBits 933.2143 Mbits/sec
120+
4.00-5.00 sec 848.8960 MBits 848.7019 Mbits/sec
121+
5.00-5.02 sec 13.5680 MBits 828.8189 Mbits/sec
122+
----------------------------------------------------
123+
0.00-5.02 sec 4283.6480 MBits 853.8217 Mbits/sec
124+
```

0 commit comments

Comments
 (0)