From d1a2717ec16a214a02bd33b7c3f8c80b4ddfa53c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20=C5=A0ediv=C3=BD?= Date: Sun, 16 Feb 2025 18:53:12 +0100 Subject: [PATCH] add troubleshooting page. --- .../docs/getting-started/troubleshooting.md | 248 +++++++++++++++++- 1 file changed, 247 insertions(+), 1 deletion(-) diff --git a/webpage/docs/getting-started/troubleshooting.md b/webpage/docs/getting-started/troubleshooting.md index 31944ab4..82456803 100644 --- a/webpage/docs/getting-started/troubleshooting.md +++ b/webpage/docs/getting-started/troubleshooting.md @@ -4,4 +4,250 @@ sidebar_position: 7 # Troubleshooting -Common issues, error messages, and their solutions. +Neko UI loads, but you don't see the screen, and it gives you a `connection timeout` or `disconnected` error? + +## Test your client + +Some browsers may block WebRTC access by default. You can check if it is enabled by going to `about:webrtc` or `chrome://webrtc-internals` in your browser. + +Check if your extensions are not blocking WebRTC access. The following extensions are known to block or not work properly with WebRTC: +- Privacy Badger +- Private Internet Access +- PIA VPN (even if disabled) + +Test whether your client [supports](https://www.webrtc-experiment.com/DetectRTC/) and can [connect to WebRTC](https://www.webcasts.com/webrtc/). + +## Networking + +If you are absolutely sure that your client is working correctly, then most likely your networking is not set up correctly. + +### Check if your ports are correctly exposed in Docker + +Check that your ephemeral port range `NEKO_WEBRTC_EPR` is correctly exposed as a `/udp` port range. + +In the following example, the specified range `52000-52100` must also be exposed using Docker. You can't map it to a different range, e.g. `52000-52100:53000-53100/udp`. If you want to use a different range, you must change the range in `NEKO_WEBRTC_EPR` too. + +```yaml title="docker-compose.yml" +services: + neko: + image: "ghcr.io/m1k1o/neko/firefox:latest" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + # highlight-start + - "52000-52100:52000-52100/udp" + # highlight-end + environment: + NEKO_DESKTOP_SCREEN: 1920x1080@30 + NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko + NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin + # highlight-start + NEKO_WEBRTC_EPR: 52000-52100 + # highlight-end + NEKO_WEBRTC_ICELITE: 1 +``` + +### Validate UDP ports reachability + +Ensure that your ports are reachable through your external IP. + +To validate the UDP connection the simplest way, run this on your server: + +```shell +nc -ul 52101 +``` + +And this on your local client: + +```shell +nc -u [server ip] 52101 +``` +Then try to type on one end, you should see characters on the other side. + +If it does not work for you, then most likely your port forwarding is not working correctly. Or your ISP is blocking traffic. + +:::tip +If you get a [`command 'nc' not found`](https://command-not-found.com/nc) error, you can install the `netcat` package using: + +```shell +sudo apt-get install netcat +``` +::: + +### Check if your external IP was determined correctly + +One of the first logs, when the server starts, writes down your external IP that will be sent to your clients to connect to. + +```shell +docker compose logs neko | grep nat_ips +``` + +:::note +`docker-compose` was replaced with `docker compose` (no hyphen) recently. If you are using an older version of docker-compose, you should use `docker-compose` instead of `docker compose`. +::: + +You should see this: + +``` +11:11AM INF webrtc starting ephemeral_port_range=52000-52100 ice_lite=true ice_servers="[{URLs:[stun:stun.l.google.com:19302] Username: Credential: CredentialType:password}]" module=webrtc nat_ips= +``` + +If your IP is not correct, you can specify your own IP resolver using `NEKO_WEBRTC_IP_RETRIEVAL_URL`. It needs to return the IP address that will be used. + +```yaml title="docker-compose.yml" +services: + neko: + image: "ghcr.io/m1k1o/neko/firefox:latest" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_DESKTOP_SCREEN: 1920x1080@30 + NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko + NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin + NEKO_WEBRTC_EPR: 52000-52100 + NEKO_WEBRTC_ICELITE: 1 + # highlight-start + NEKO_WEBRTC_IP_RETRIEVAL_URL: https://ifconfig.co/ip + # highlight-end +``` + +Or you can specify your IP address manually using `NEKO_WEBRTC_NAT1TO1`: + +```yaml title="docker-compose.yml" +services: + neko: + image: "ghcr.io/m1k1o/neko/firefox:latest" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_DESKTOP_SCREEN: 1920x1080@30 + NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko + NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin + NEKO_WEBRTC_EPR: 52000-52100 + NEKO_WEBRTC_ICELITE: 1 + # highlight-start + NEKO_WEBRTC_NAT1TO1: + # highlight-end +``` + +:::note +It's read as `NAT One to One`, so it's a capital letter `O`, not zero `0`, in `NAT1TO1`. +::: + +If you want to use n.eko only locally, you must put your local IP address here, otherwise, the public address will be used. + +### Neko works externally, but not locally + +You are probably missing the NAT Loopback (NAT Hairpinning) setting on your router. + +Example for pfsense with truecharts docker container: +- First, port forward the relevant ports `8080` and `52000-52100/udp` for the container. +- Then turn on `Pure NAT` in pfsense (under system > advanced > firewall and nat). + - Make sure to check the two boxes so it works. +- Make sure `NEKO_WEBRTC_NAT1TO1` is blank and the `NEKO_WEBRTC_IP_RETRIEVAL_URL` address is working correctly (if unset, the default value is chosen). +- Test externally to confirm it works. +- Internally you have to access it using `:port` + +If your router does not support NAT Loopback (NAT Hairpinning), you can use turn servers to overcome this issue. See [more details here](/docs/v3/getting-started/configuration/webrtc#ice-servers) on how to set up a local coturn instance. + +### Neko works locally, but not externally + +Make sure that you are exposing your ports correctly. + +If you put a local IP as `NEKO_WEBRTC_NAT1TO1`, external clients try to connect to that IP. But it is unreachable for them because it is your local IP. You must use your public IP address with port forwarding. + +## Debug mode + +To see verbose information from the n.eko server, you can enable debug mode using `NEKO_DEBUG`. + +```yaml title="docker-compose.yml" +services: + neko: + image: "ghcr.io/m1k1o/neko/firefox:latest" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_DESKTOP_SCREEN: 1920x1080@30 + NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko + NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin + NEKO_WEBRTC_EPR: 52000-52100 + # highlight-start + NEKO_DEBUG: 1 + # highlight-end +``` + +Ensure that you have enabled debug mode in the JavaScript console too, in order to see verbose information from the client. + +## Frequently Encountered Errors + +### Common server errors + +``` +WRN session created with an error error="invalid 1:1 NAT IP mapping" +``` + +Check your `NEKO_WEBRTC_NAT1TO1` or ensure that `NEKO_WEBRTC_IP_RETRIEVAL_URL` returns the correct IP. + +--- + +``` +WRN could not get server reflexive address udp6 stun:stun.l.google.com:19302: write udp6 [::]:52042->[2607:f8b0:4001:c1a::7f]:19302: sendto: cannot assign requested address +``` + +Check if your DNS is set up correctly, and if your IPv6 connectivity is working properly, or is disabled. + +--- + +``` +WRN undeclaredMediaProcessor failed to open SrtcpSession: the DTLS transport has not started yet module=webrtc subsystem= +``` + +Check if your UDP ports are exposed correctly and reachable. + +### Common client errors + +``` +Firefox can’t establish a connection to the server at ws:///ws?password=neko. +``` + +Check if your TCP port is exposed correctly and your reverse proxy is correctly proxying websocket connections. And if your browser has not disabled websocket connections. + +--- + +``` +Getting a black screen with a cursor, but no browser. +``` + +Most likely you forgot to add `-cap-add=SYS_ADMIN` when using chromium-based browsers. + +### Unrelated server errors + +``` +[ERROR:bus.cc(393)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix") +``` + +This error originates from the browser, that it could not connect to dbus. This does not affect us and can be ignored. + +### Broadcast pipeline not working with some ingest servers + +See [related issue](https://github.com/m1k1o/neko/issues/276). + +``` +Could not connect to RTMP stream "'rtmp:///live/ live=1'" for writing +``` + +Some ingest servers require the `live=1` parameter in the URL (e.g. nginx-rtmp-module). Some do not and do not accept apostrophes (e.g. owncast). You can try to change the pipeline to: + +```yaml +NEKO_CAPTURE_BROADCAST_PIPELINE: "flvmux name=mux ! rtmpsink location={url} pulsesrc device={device} ! audio/x-raw,channels=2 ! audioconvert ! voaacenc ! mux. ximagesrc display-name={display} show-pointer=false use-damage=false ! video/x-raw,framerate=28/1 ! videoconvert ! queue ! x264enc bframes=0 key-int-max=0 byte-stream=true tune=zerolatency speed-preset=veryfast ! mux." +```