From 52984e2942d1c3fae28201e41c4fb9cf951fc146 Mon Sep 17 00:00:00 2001 From: Paul Mucur Date: Thu, 7 Nov 2024 10:23:29 +0000 Subject: [PATCH 1/4] Document rpi-connect 2.1.0's new doctor CLI Rather than having users run connectivity checks themselves, document the new rpi-connect doctor CLI command and what it tests. While the doctor will output various things users can try, keep the details of our servers and ports in case someone wants to check their network ahead of time. --- .../services/connect/troubleshooting.adoc | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/documentation/asciidoc/services/connect/troubleshooting.adoc b/documentation/asciidoc/services/connect/troubleshooting.adoc index 5d2411000..8bd3bd1f5 100644 --- a/documentation/asciidoc/services/connect/troubleshooting.adoc +++ b/documentation/asciidoc/services/connect/troubleshooting.adoc @@ -61,11 +61,25 @@ For screen sharing, Connect can only share an existing graphical desktop session ==== Networking and firewall issues -Connect avoids changing your network or firewall in order to establish a connection. However, if you have a restrictive network and experience trouble connecting, check the following: +Connect avoids changing your network or firewall in order to establish a connection. However, if you have a restrictive network and experience trouble connecting, `rpi-connect` and `rpi-connect-lite` include a `rpi-connect doctor` command to run a series of tests to check that Connect can establish connections properly. -. Can you access the Connect API, which Connect uses for authentication and connection negotiation between your Raspberry Pi and your browser? To check, load https://api.connect.raspberrypi.com/up?[https://api.connect.raspberrypi.com/up?] on your Raspberry Pi. -. Can you access the Connect STUN server, which Connect uses to obtain a peer-to-peer connection through local or public networks? To check, ping `stun.raspberrypi.com` on UDP port 3478. -. Can you access our TURN servers, which Connect uses to relay sessions when a peer-to-peer connection fails? To check, ping `turn1.raspberrypi.com`, `turn2.raspberrypi.com` and `turn3.raspberrypi.com` on TCP ports 3478 or 443, or UDP ports 3478, 443 and 49152 -> 65535. +Specifically: + +. Can we make an HTTPS request to the Raspberry Pi Connect API at `api.connect.raspberrypi.com` on port 443 and have it respond successfully? +. Can we make an authenticated request to the Raspberry Pi Connect API? +. Can we communicate with the Raspberry Pi Connect STUN or TURN servers at `stun.raspberrypi.com`, `turn1.raspberrypi.com`, `turn2.raspberrypi.com`, or `turn3.raspberrypi.com` on UDP port 3478 and receive a server reflexive candidate? +. Can we communicate with the Raspberry Pi Connect TURN servers on TCP ports 3478 or 443, and UDP ports 3478, 443, and 49152 -> 65535 and receive a relay candidate? + +To run these tests on your device, run the following command: + +[source,console] +---- +$ rpi-connect doctor +✓ Communication with Raspberry Pi Connect API +✓ Authentication with Raspberry Pi Connect API +✓ Peer-to-peer connection candidate via STUN +✓ Peer-to-peer connection candidate via TURN +---- === View Connect status From 13136793f83a17234092d12d7bc0886ff94b2e46 Mon Sep 17 00:00:00 2001 From: nate contino Date: Thu, 7 Nov 2024 16:19:29 +0000 Subject: [PATCH 2/4] Update documentation/asciidoc/services/connect/troubleshooting.adoc --- .../services/connect/troubleshooting.adoc | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/documentation/asciidoc/services/connect/troubleshooting.adoc b/documentation/asciidoc/services/connect/troubleshooting.adoc index 8bd3bd1f5..794e4594c 100644 --- a/documentation/asciidoc/services/connect/troubleshooting.adoc +++ b/documentation/asciidoc/services/connect/troubleshooting.adoc @@ -75,12 +75,35 @@ To run these tests on your device, run the following command: [source,console] ---- $ rpi-connect doctor +---- + +If Connect can communicate properly on your network, you should see output similar to the following: + +---- ✓ Communication with Raspberry Pi Connect API ✓ Authentication with Raspberry Pi Connect API ✓ Peer-to-peer connection candidate via STUN ✓ Peer-to-peer connection candidate via TURN ---- +If Connect can't communicate properly on your network, you'll see an "x" instead of a check next to the failing test case. Ask your network administrator to enable the following connections on your network: + +* unauthenticated HTTPS requests to the Raspberry Pi Connect API on port 443 of `api.connect.raspberrypi.com` +* authenticated requests to the Raspberry Pi Connect API on port 443 of `api.connect.raspberrypi.com` +* requests to Raspberry Pi Connect STUN or TURN servers on UDP port 3478 of all of the following: +** `stun.raspberrypi.com` +** `turn1.raspberrypi.com` +** `turn2.raspberrypi.com` +** `turn3.raspberrypi.com` +* requests to Raspberry Pi Connect TURN servers on TCP ports 3478 or 443 of all of the following: +** `turn1.raspberrypi.com` +** `turn2.raspberrypi.com` +** `turn3.raspberrypi.com` +* requests to Raspberry Pi Connect TURN servers on UDP ports 3478, 443, or 49152 -> 65535 of all of the following: +** `turn1.raspberrypi.com` +** `turn2.raspberrypi.com` +** `turn3.raspberrypi.com` + === View Connect status To view the current status of the Connect service, run the following command: From a532bdc58bd4e4978dfebb890c49d2c184a46a6d Mon Sep 17 00:00:00 2001 From: nate contino Date: Thu, 7 Nov 2024 16:19:36 +0000 Subject: [PATCH 3/4] Update documentation/asciidoc/services/connect/troubleshooting.adoc --- documentation/asciidoc/services/connect/troubleshooting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/services/connect/troubleshooting.adoc b/documentation/asciidoc/services/connect/troubleshooting.adoc index 794e4594c..d70518231 100644 --- a/documentation/asciidoc/services/connect/troubleshooting.adoc +++ b/documentation/asciidoc/services/connect/troubleshooting.adoc @@ -61,7 +61,7 @@ For screen sharing, Connect can only share an existing graphical desktop session ==== Networking and firewall issues -Connect avoids changing your network or firewall in order to establish a connection. However, if you have a restrictive network and experience trouble connecting, `rpi-connect` and `rpi-connect-lite` include a `rpi-connect doctor` command to run a series of tests to check that Connect can establish connections properly. +Connect usually communicates between devices without requiring changes to your network or firewall. However, especially restrictive networks can sometimes block Connect communication. To help debug problems with such networks, `rpi-connect` and `rpi-connect-lite` include the `rpi-connect doctor` command. `rpi-connect doctor` runs a series of tests to check that Connect communication functions properly on your network. Specifically: From 1d361c952073e87be7f32f71b723815e46069454 Mon Sep 17 00:00:00 2001 From: nate contino Date: Thu, 7 Nov 2024 16:19:42 +0000 Subject: [PATCH 4/4] Update documentation/asciidoc/services/connect/troubleshooting.adoc --- .../asciidoc/services/connect/troubleshooting.adoc | 6 ------ 1 file changed, 6 deletions(-) diff --git a/documentation/asciidoc/services/connect/troubleshooting.adoc b/documentation/asciidoc/services/connect/troubleshooting.adoc index d70518231..d05876ab3 100644 --- a/documentation/asciidoc/services/connect/troubleshooting.adoc +++ b/documentation/asciidoc/services/connect/troubleshooting.adoc @@ -63,12 +63,6 @@ For screen sharing, Connect can only share an existing graphical desktop session Connect usually communicates between devices without requiring changes to your network or firewall. However, especially restrictive networks can sometimes block Connect communication. To help debug problems with such networks, `rpi-connect` and `rpi-connect-lite` include the `rpi-connect doctor` command. `rpi-connect doctor` runs a series of tests to check that Connect communication functions properly on your network. -Specifically: - -. Can we make an HTTPS request to the Raspberry Pi Connect API at `api.connect.raspberrypi.com` on port 443 and have it respond successfully? -. Can we make an authenticated request to the Raspberry Pi Connect API? -. Can we communicate with the Raspberry Pi Connect STUN or TURN servers at `stun.raspberrypi.com`, `turn1.raspberrypi.com`, `turn2.raspberrypi.com`, or `turn3.raspberrypi.com` on UDP port 3478 and receive a server reflexive candidate? -. Can we communicate with the Raspberry Pi Connect TURN servers on TCP ports 3478 or 443, and UDP ports 3478, 443, and 49152 -> 65535 and receive a relay candidate? To run these tests on your device, run the following command: