Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit8c811a5

Browse files
committed
docs: add networking troubleshooting page
1 parent5366f25 commit8c811a5

File tree

5 files changed

+154
-45
lines changed

5 files changed

+154
-45
lines changed

‎cli/cliui/agent.go

Lines changed: 23 additions & 9 deletions
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
ifd.SentNode {
312-
_,_=fmt.Fprint(w,"✔ sent local data to Coder networkingcoodinator\n")
312+
_,_=fmt.Fprint(w,"✔ sent local data to Coder networkingcoordinator\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:=ranged.AgentNetcheck.Interfaces.Warnings {
395395
agent=append(agent,msg.Message)
396396
}
397+
iflen(d.AgentNetcheck.Interfaces.Warnings)>0 {
398+
agent[len(agent)-1]+="\nhttps://coder.com/docs/networking/troubleshooting#low-mtu"
399+
}
397400
}
398401

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

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

416422
ifd.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
returngeneral,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
}elseifd.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
ifd.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
ifd.AgentNetcheck!=nil&&d.AgentNetcheck.NetInfo!=nil {
434444
ifd.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
ifd.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
ifd.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
returngeneral,client,agent
450464
}

‎cli/cliui/agent_test.go

Lines changed: 1 addition & 1 deletion
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 networkingcoodinator$`),
536+
regexp.MustCompile(`^✔ sent local data to Coder networkingcoordinator$`),
537537
},
538538
},
539539
{

‎docs/manifest.json

Lines changed: 5 additions & 0 deletions
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

Lines changed: 1 addition & 35 deletions
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

Lines changed: 124 additions & 0 deletions
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)
[8]ページ先頭
©2009-2025 Movatter.jp