update docs #95.
This commit is contained in:
59
docs/getting-started/README.md
Normal file
59
docs/getting-started/README.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Getting started & FAQ
|
||||
|
||||
Use the following docker images:
|
||||
- `m1k1o/neko:latest` - for Firefox.
|
||||
- `m1k1o/neko:chromium` - for Chromium (needs `--cap-add=SYS_ADMIN`).
|
||||
- `m1k1o/neko:google-chrome` - for Google Chrome (needs `--cap-add=SYS_ADMIN`).
|
||||
- `m1k1o/neko:ungoogled-chromium` - for [Ungoogled Chromium](https://github.com/Eloston/ungoogled-chromium) (needs `--cap-add=SYS_ADMIN`) (by @whalehub).
|
||||
- `m1k1o/neko:brave` - for [Brave Browser](https://brave.com) (needs `--cap-add=SYS_ADMIN`).
|
||||
- `m1k1o/neko:tor-browser` - for Tor Browser.
|
||||
- `m1k1o/neko:vncviewer` - for simple VNC viewer (specify `NEKO_VNC_URL` to your VNC target).
|
||||
- `m1k1o/neko:vlc` - for VLC Video player (needs volume mounted to `/media` with local video files, or setting `VLC_MEDIA=/media` path).
|
||||
- `m1k1o/neko:xfce` - for a shared desktop / installing shared software.
|
||||
- `m1k1o/neko:base` - for custom base.
|
||||
|
||||
For ARM-based devices (like Raspberry Pi, with GPU hardware acceleration):
|
||||
- `m1k1o/neko:arm-firefox` - for Firefox.
|
||||
- `m1k1o/neko:arm-chromium` - for Chromium.
|
||||
- `m1k1o/neko:arm-base` - for custom arm based.
|
||||
|
||||
Images (except `arm-`) are built using GitHub actions on every push and on weekly basis to keep all browsers up-to-date,
|
||||
|
||||
### Networking:
|
||||
- If you want to use n.eko in **external** network, you can omit `NEKO_NAT1TO1`. It will automatically get your Public IP.
|
||||
- If you want to use n.eko in **internal** network, set `NEKO_NAT1TO1` to your local IP address (e.g. `NEKO_NAT1TO1: 192.168.1.20`)-
|
||||
- Currently, it is not supported to supply multiple NAT addresses (see https://github.com/m1k1o/neko/issues/47).
|
||||
|
||||
### Why so many ports?
|
||||
- WebRTC needs UDP ports in order to transfer Audio/Video towards user and Mouse/Keyboard events to the server in real time.
|
||||
- If you don't set `NEKO_ICELITE=true`, every user will need 2 UDP ports.
|
||||
- If you set `NEKO_ICELITE=true`, every user will need only 1 UDP port. It is **recommended** to use *ice-lite*.
|
||||
- Do not forget, they are **UDP** ports, that configuration must be correct in your firewall/router/docker.
|
||||
- You can freely limit number of UDP ports. But you can't map them to different ports.
|
||||
- This **WON'T** work: `32000-32100:52000-52100/udp`
|
||||
- You can change API port (8080).
|
||||
- This **WILL** work: `3000:8080`
|
||||
|
||||
### Want to customize and install own add-ons, set custom bookmarks?
|
||||
- You would need to modify the existing policy file and mount it to your container.
|
||||
- For Firefox, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/firefox/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/usr/share/firefox-esr/distribution/policies.json'`
|
||||
- For Chromium, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/chromium/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/etc/chromium/policies/managed/policies.json'`
|
||||
|
||||
### Want to use VPN for your n.eko browsing?
|
||||
- Check this out: https://github.com/m1k1o/neko-vpn
|
||||
|
||||
### Want to have multiple rooms on demand?
|
||||
- Check this out: https://github.com/m1k1o/neko-rooms
|
||||
|
||||
### Want to use different Apps than Browser?
|
||||
- Check this out: https://github.com/m1k1o/neko-apps
|
||||
|
||||
### Accounts:
|
||||
- There are no accounts, display name (a.k.a. username) can be freely chosen. Only password needs to match. Depending on which password matches, the visitor gets its privilege:
|
||||
- Anyone, who enters with `NEKO_PASSWORD` will be **user**.
|
||||
- Anyone, who enters with `NEKO_PASSWORD_ADMIN` will be **admin**.
|
||||
|
||||
### Screen size
|
||||
- Only admins can change screen size.
|
||||
- You can set a default screen size, but this size **MUST** be one from the list, that your server supports.
|
||||
- You will get this list in frontend, where you can choose from.
|
118
docs/getting-started/configuration.md
Normal file
118
docs/getting-started/configuration.md
Normal file
@ -0,0 +1,118 @@
|
||||
# Configuration
|
||||
|
||||
## Environment variables
|
||||
|
||||
```
|
||||
NEKO_SCREEN:
|
||||
- Resolution after startup. Only Admins can change this later.
|
||||
- e.g. '1920x1080@30'
|
||||
NEKO_PASSWORD:
|
||||
- Password for the user login
|
||||
- e.g. 'user_password'
|
||||
NEKO_PASSWORD_ADMIN
|
||||
- Password for the admin login
|
||||
- e.g. 'admin_password'
|
||||
NEKO_EPR:
|
||||
- For WebRTC needed range of ports
|
||||
- e.g. 52000-52100
|
||||
NEKO_VP8:
|
||||
- If vp8 should be used as video encoder for the stream (default encoder)
|
||||
- e.g. 'true'
|
||||
NEKO_VP9:
|
||||
- If vp9 should be used as video encoder for the stream (Parameter not optimized yet)
|
||||
- e.g. 'false'
|
||||
NEKO_H264:
|
||||
- If h264 should be used as video encoder for the stream (second best option)
|
||||
- e.g. 'false'
|
||||
NEKO_VIDEO_BITRATE:
|
||||
- Bitrate of the video stream in kb/s
|
||||
- e.g. 3500
|
||||
NEKO_VIDEO:
|
||||
- Makes it possible to create custom gstreamer pipelines. With this you could find the best quality for your CPU
|
||||
- Installed are gstreamer1.0-plugins-base / gstreamer1.0-plugins-good / gstreamer1.0-plugins-bad / gstreamer1.0-plugins-ugly
|
||||
- e.g. ' ximagesrc display-name=%s show-pointer=true use-damage=false ! video/x-raw,framerate=30/1 ! videoconvert ! queue ! video/x-raw,format=NV12 ! x264enc threads=4 bitrate=3500 key-int-max=60 vbv-buf-capacity=4000 byte-stream=true tune=zerolatency speed-preset=veryfast ! video/x-h264,stream-format=byte-stream '
|
||||
NEKO_MAX_FPS:
|
||||
- The resulting stream frames per seconds should be capped (0 for uncapped)
|
||||
- e.g. 0
|
||||
NEKO_OPUS:
|
||||
- If opus should be used as audio encoder for the stream (default encoder)
|
||||
- e.g. 'true'
|
||||
NEKO_G722:
|
||||
- If g722 should be used as audio encoder for the stream
|
||||
- e.g. 'false'
|
||||
NEKO_PCMU:
|
||||
- If pcmu should be used as audio encoder for the stream
|
||||
- e.g. 'false'
|
||||
NEKO_PCMA:
|
||||
- If pcma should be used as audio encoder for the stream
|
||||
- e.g. 'false'
|
||||
NEKO_AUDIO_BITRATE:
|
||||
- Bitrate of the audio stream in kb/s
|
||||
- e.g. 196
|
||||
NEKO_CERT:
|
||||
- Path to the SSL-Certificate
|
||||
- e.g. '/certs/cert.pem'
|
||||
NEKO_KEY:
|
||||
- Path to the SSL-Certificate private key
|
||||
- e.g. '/certs/key.pem'
|
||||
NEKO_ICELITE:
|
||||
- Use the ice lite protocol
|
||||
- e.g. false
|
||||
NEKO_ICESERVER:
|
||||
- Describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer (simple usage for server without authentication)
|
||||
- e.g. 'stun:stun.l.google.com:19302'
|
||||
NEKO_ICESERVERS:
|
||||
- Describes multiple STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer
|
||||
- e.g. '[{"urls": ["turn:turn.example.com:19302", "stun:stun.example.com:19302"], "username": "name", "credential": "password"}, {"urls": ["stun:stun.example2.com:19302"]}]'
|
||||
- [More information](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer)
|
||||
```
|
||||
|
||||
## Agruments
|
||||
|
||||
You can execute `neko serve --help` to see available arguments.
|
||||
|
||||
```
|
||||
Usage:
|
||||
neko serve [flags]
|
||||
|
||||
Flags:
|
||||
--audio string audio codec parameters to use for streaming
|
||||
--audio_bitrate int audio bitrate in kbit/s (default 128)
|
||||
--bind string address/port/socket to serve neko (default "127.0.0.1:8080")
|
||||
--broadcast_pipeline string custom gst pipeline used for broadcasting, strings {url} {device} {display} will be replaced
|
||||
--cert string path to the SSL cert used to secure the neko server
|
||||
--device string audio device to capture (default "auto_null.monitor")
|
||||
--display string XDisplay to capture (default ":99.0")
|
||||
--epr string limits the pool of ephemeral ports that ICE UDP connections can allocate from (default "59000-59100")
|
||||
--g722 use G722 audio codec
|
||||
--h264 use H264 video codec
|
||||
-h, --help help for serve
|
||||
--icelite configures whether or not the ice agent should be a lite agent
|
||||
--iceserver strings describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer (default [stun:stun.l.google.com:19302])
|
||||
--iceservers string describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer
|
||||
--ipfetch string automatically fetch IP address from given URL when nat1to1 is not present (default "http://checkip.amazonaws.com")
|
||||
--key string path to the SSL key used to secure the neko server
|
||||
--max_fps int maximum fps delivered via WebRTC, 0 is for no maximum (default 25)
|
||||
--nat1to1 strings sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP address is used
|
||||
--opus use Opus audio codec
|
||||
--password string password for connecting to stream (default "neko")
|
||||
--password_admin string admin password for connecting to stream (default "admin")
|
||||
--pcma use PCMA audio codec
|
||||
--pcmu use PCMU audio codec
|
||||
--proxy enable reverse proxy mode
|
||||
--screen string default screen resolution and framerate (default "1280x720@30")
|
||||
--static string path to neko client files to serve (default "./www")
|
||||
--video string video codec parameters to use for streaming
|
||||
--video_bitrate int video bitrate in kbit/s (default 3072)
|
||||
--vp8 use VP8 video codec
|
||||
--vp9 use VP9 video codec
|
||||
|
||||
Global Flags:
|
||||
--config string configuration file path
|
||||
-d, --debug enable debug mode
|
||||
-l, --logs save logs to file
|
||||
```
|
||||
|
||||
## Config file
|
||||
|
||||
You can mount YAML config file to docker container on this path `/etc/neko/neko.yaml` and store your configuration there.
|
108
docs/getting-started/examples.md
Normal file
108
docs/getting-started/examples.md
Normal file
@ -0,0 +1,108 @@
|
||||
# Examples
|
||||
|
||||
## Firefox
|
||||
|
||||
```yaml
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:latest"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
environment:
|
||||
NEKO_SCREEN: '1920x1080@30'
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_NAT1TO1: <your-IP>
|
||||
```
|
||||
|
||||
## Chromium
|
||||
|
||||
```yaml
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:chromium"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
environment:
|
||||
NEKO_SCREEN: '1920x1080@30'
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_NAT1TO1: <your-IP>
|
||||
```
|
||||
|
||||
## VLC
|
||||
|
||||
```yaml
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:vlc"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
volumes:
|
||||
- "<your-video-folder>:/video"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
environment:
|
||||
NEKO_SCREEN: '1920x1080@30'
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_NAT1TO1: <your-IP>
|
||||
```
|
||||
|
||||
## Raspberry Pi
|
||||
|
||||
Note! Since HW accelerated pipeline is using H264, you are only able to connect from browsers supporting H264 for WebRTC. At the time of implementing, [Firefox does not support this](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/WebRTC_codecs#supported-foot-1). When omitting `NEKO_VIDEO` and `NEKO_H264` parameters, you get default CPU encoding with VP8.
|
||||
|
||||
```yaml
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:arm-chromium"
|
||||
restart: "unless-stopped"
|
||||
# increase on rpi's with more then 1gb ram.
|
||||
shm_size: "520mb"
|
||||
ports:
|
||||
- "8088:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
# note: this is important since we need a GPU for hardware acceleration alternatively
|
||||
# mount the devices into the docker.
|
||||
privileged: true
|
||||
environment:
|
||||
NEKO_SCREEN: '1280x720@30'
|
||||
NEKO_PASSWORD: 'neko'
|
||||
NEKO_PASSWORD_ADMIN: 'admin'
|
||||
NEKO_EPR: 52000-52100
|
||||
# note: when setting NEKO_VIDEO, then variables NEKO_MAX_FPS and NEKO_VIDEO_BITRATE
|
||||
# are not being used, you can adjust them in this variable.
|
||||
NEKO_VIDEO: |
|
||||
ximagesrc display-name=%s use-damage=0 show-pointer=true use-damage=false
|
||||
! video/x-raw,framerate=30/1
|
||||
! videoconvert
|
||||
! queue
|
||||
! video/x-raw,framerate=30/1,format=NV12
|
||||
! v4l2h264enc extra-controls="controls,h264_profile=0,video_bitrate=1250000;"
|
||||
! h264parse config-interval=3
|
||||
! video/x-h264,profile=baseline,stream-format=byte-stream
|
||||
NEKO_H264: 1
|
||||
```
|
||||
|
||||
## Not using docker?
|
||||
|
||||
You can execute `neko --help` to see available arguments. In [Dockerfile](https://github.com/m1k1o/neko/blob/master/.m1k1o/base/Dockerfile) you can find required dependencies and install them manually.
|
46
docs/getting-started/quick-start.md
Normal file
46
docs/getting-started/quick-start.md
Normal file
@ -0,0 +1,46 @@
|
||||
# Quick Start
|
||||
|
||||
1. Deploy a server or VPS.
|
||||
|
||||
**Recommended Specs:**
|
||||
|
||||
| Resolution | Cores | Ram | Recommendation |
|
||||
|-------------|-------|-------|------------------|
|
||||
| 1024×576@30 | 2 | 2gb | Not Recommended |
|
||||
| 1280x720@30 | 4 | 3gb | Good Performance |
|
||||
| 1280x720@30 | 6 | 4gb | Recommended |
|
||||
| 1280x720@30 | 8 | 4gb+ | Best Performance |
|
||||
|
||||
*Why are the specs so high?* : If you think about it, you have to run a full desktop, a browser (a resource hog on its own) *and* encode/transmit the desktop, there's a lot going on and so it demands some power.
|
||||
|
||||
*Note:* Admin can change the resolution in the GUI.
|
||||
|
||||
2. [Login via SSH](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/).
|
||||
|
||||
3. Install [Docker](https://docs.docker.com/get-docker/):
|
||||
```shell
|
||||
curl -sSL https://get.docker.com/ | CHANNEL=stable bash
|
||||
```
|
||||
|
||||
4. Install [Docker Compose](https://docs.docker.com/compose/install/):
|
||||
```shell
|
||||
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
```
|
||||
|
||||
5. Download docker compose file and start it:
|
||||
```shell
|
||||
wget https://raw.githubusercontent.com/m1k1o/neko/master/docker-compose.yaml
|
||||
sudo docker-compose up -d
|
||||
```
|
||||
|
||||
6. Visit the IP address server in your browser and login, the default password is `neko`.
|
||||
|
||||
> 💡 **Protip**: Run `nano docker-compose.yaml` to edit the settings, then press `ctrl+x` to exit and save the file.
|
||||
|
||||
## Well known cloud providers
|
||||
* [Hetzner Cloud](https://www.hetzner.com/cloud)
|
||||
* [Digital Ocean](https://www.digitalocean.com/)
|
||||
* [Contabo](https://contabo.com/)
|
||||
* [Linode](https://www.linode.com/)
|
||||
* [Vultr](https://www.vultr.com/)
|
116
docs/getting-started/reverse-proxy.md
Normal file
116
docs/getting-started/reverse-proxy.md
Normal file
@ -0,0 +1,116 @@
|
||||
# Behind reverse proxy?
|
||||
|
||||
## Traefik2
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.services.neko-frontend.loadbalancer.server.port=8080"
|
||||
- "traefik.http.routers.neko.rule=${TRAEFIK_RULE}"
|
||||
- "traefik.http.routers.neko.entrypoints=${TRAEFIK_ENTRYPOINTS}"
|
||||
- "traefik.http.routers.neko.tls.certresolver=${TRAEFIK_CERTRESOLVER}"
|
||||
```
|
||||
|
||||
(by @m1k1o, [example](https://github.com/m1k1o/neko-vpn/blob/a1b934515dcf597992a515d61d307c2450a11002/docker-compose.yml#L38-L43))
|
||||
|
||||
## Nginx
|
||||
|
||||
```conf
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8080;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_read_timeout 86400;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $remote_addr;
|
||||
proxy_set_header X-Forwarded-Host $host;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
proxy_set_header X-Forwarded-Protocol $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
(by @GigaFyde, [source](https://github.com/nurdism/neko/issues/111#issuecomment-742656957))
|
||||
|
||||
## Apache
|
||||
|
||||
After successfully installing and running neko, you might want to get rid of the port in the url, use DNS instead of IP address and also having SSL.
|
||||
This will remove the port from the URL and also enables HTTPS.
|
||||
To do this, you have to get running apache server. Now you can go into the `/etc/apache2/sites-available` folder and create new config file for example `neko.conf`
|
||||
After creating new config file, you can use this example config and paste it in. Some thing might vary on your machine so read through and modify if needed.
|
||||
Bear in mind that your neko server doesn't have to run on the same computer as apache. They just have to be on the same network and then you replace localhost with correct internal IP.
|
||||
|
||||
```xml
|
||||
<VirtualHost *:80>
|
||||
# The ServerName directive sets the request scheme, hostname and port that
|
||||
# the server uses to identify itself. This is used when creating
|
||||
# redirection URLs. In the context of virtual hosts, the ServerName
|
||||
# specifies what hostname must appear in the request's Host: header to
|
||||
# match this virtual host. For the default virtual host (this file) this
|
||||
# value is not decisive as it is used as a last resort host regardless.
|
||||
# However, you must set it for any further virtual host explicitly.
|
||||
|
||||
# Paths of those modules might vary across different distros.
|
||||
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
|
||||
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
|
||||
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so
|
||||
|
||||
ServerName example.com
|
||||
ServerAlias www.example.com
|
||||
|
||||
ProxyRequests Off
|
||||
ProxyPass / http://localhost:8080/
|
||||
ProxyPassReverse / http://localhost:8080/
|
||||
|
||||
RewriteEngine on
|
||||
RewriteCond %{HTTP:Upgrade} websocket [NC]
|
||||
RewriteCond %{HTTP:Connection} upgrade [NC]
|
||||
RewriteRule /ws(.*) "ws://localhost:8080/ws$1" [P,L]
|
||||
|
||||
# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
|
||||
# error, crit, alert, emerg.
|
||||
# It is also possible to configure the loglevel for particular
|
||||
# modules, e.g.
|
||||
#LogLevel info ssl:warn
|
||||
|
||||
ErrorLog ${APACHE_LOG_DIR}/error.log
|
||||
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
||||
|
||||
# For most configuration files from conf-available/, which are
|
||||
# enabled or disabled at a global level, it is possible to
|
||||
# include a line for only one particular virtual host. For example the
|
||||
# following line enables the CGI configuration for this host only
|
||||
# after it has been globally disabled with "a2disconf".
|
||||
#Include conf-available/serve-cgi-bin.conf
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
(by @DarkReaper231, [source](https://github.com/nurdism/neko/blob/cad98a62a5bd7f1daf2c11980631bb14ba81a1f6/docs/apache-proxypass-config.md#example-apache-config))
|
||||
|
||||
After creating your new config file, just use `sudo a2ensite neko.conf` and then `sudo systemctl reload apache2`
|
||||
|
||||
### Enabling SSL
|
||||
|
||||
If you want to use SSL for your apache configuration, you can install certbot and use it with `sudo certbot`
|
||||
Then you can just select both `example.com` and `www.example.com` and apply. This will copy your `neko.conf` file and creates one for SSL.
|
||||
|
||||
## Caddy
|
||||
|
||||
```conf
|
||||
https://example.com {
|
||||
reverse_proxy localhost:8080 {
|
||||
header_up Host {host}
|
||||
header_up X-Real-IP {remote_host}
|
||||
header_up X-Forwarded-For {remote_host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
(by @ccallahan, [source](https://github.com/nurdism/neko/pull/125/commits/eb4ceda75423b0d960c8aea0240acf6d7a10fef4))
|
189
docs/getting-started/troubleshooting.md
Normal file
189
docs/getting-started/troubleshooting.md
Normal file
@ -0,0 +1,189 @@
|
||||
# Troubleshooting
|
||||
|
||||
Neko UI loads but you don't see the screen and it gives you `connection timeout` or `disconnected` error?
|
||||
|
||||
## Test your client
|
||||
|
||||
Test whether your cleint can connect to WebRTC here: https://test.webrtc.org/
|
||||
|
||||
## Networking
|
||||
|
||||
Most problems are networking related.
|
||||
|
||||
### Check if your ports are correctly exposed using docker
|
||||
|
||||
Check that your ephemeral port range `NEKO_EPR` is correctly exposed as `/udp` port range.
|
||||
|
||||
In following example, specified range `52000-52100` must be also exposed using docker.
|
||||
|
||||
```diff
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:latest"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
+ - "52000-52100:52000-52100/udp"
|
||||
environment:
|
||||
NEKO_SCREEN: 1920x1080@30
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
+ NEKO_EPR: 52000-52100
|
||||
NEKO_ICELITE: 1
|
||||
```
|
||||
|
||||
### Validate UDP ports reachability
|
||||
|
||||
Ensure, that your ports are reachable through your external IP.
|
||||
|
||||
To validate UDP connection the simpliest 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.
|
||||
|
||||
### 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 conenct to.
|
||||
|
||||
```shell
|
||||
docker-compose logs neko | grep nat_ips
|
||||
```
|
||||
|
||||
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:<nil> CredentialType:password}]" module=webrtc nat_ips=<your-IP>
|
||||
```
|
||||
|
||||
If your IP is not correct, you can specify own IP resover using `NEKO_IPFETCH`. It needs to return IP address that will be used.
|
||||
|
||||
```diff
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:latest"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
environment:
|
||||
NEKO_SCREEN: 1920x1080@30
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_ICELITE: 1
|
||||
+ NEKO_IPFETCH: https://ifconfig.co/ip
|
||||
```
|
||||
|
||||
Or you can specify your IP address manually using `NEKO_NAT1TO1`:
|
||||
|
||||
```diff
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:latest"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
environment:
|
||||
NEKO_SCREEN: 1920x1080@30
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_ICELITE: 1
|
||||
+ NEKO_NAT1TO1: <your-IP>
|
||||
```
|
||||
|
||||
If you want to use n.eko only locally, you must put here your local IP address, otherwise public address will be used.
|
||||
|
||||
## Debug mode
|
||||
|
||||
To see verbose information from n.eko server, you can enable debug mode using `NEKO_DEBUG`.
|
||||
|
||||
```diff
|
||||
version: "3.4"
|
||||
services:
|
||||
neko:
|
||||
image: "m1k1o/neko:latest"
|
||||
restart: "unless-stopped"
|
||||
shm_size: "2gb"
|
||||
ports:
|
||||
- "8080:8080"
|
||||
- "52000-52100:52000-52100/udp"
|
||||
environment:
|
||||
NEKO_SCREEN: 1920x1080@30
|
||||
NEKO_PASSWORD: neko
|
||||
NEKO_PASSWORD_ADMIN: admin
|
||||
NEKO_EPR: 52000-52100
|
||||
NEKO_ICELITE: 1
|
||||
+ NEKO_DEBUG: 1
|
||||
```
|
||||
|
||||
Ensure, that you have enabled debug mode in javascript console too, in order to see verbose information from client.
|
||||
|
||||
## Frequently Encountered Errors
|
||||
|
||||
### Common server errors
|
||||
|
||||
```
|
||||
WRN session created with and error error="invalid 1:1 NAT IP mapping"
|
||||
```
|
||||
|
||||
Check your `NEKO_NAT1TO1` or ensure, that `NEKO_IPFETCH` returns 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://<your-IP>/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 black screen with a cursor, but no browser.
|
||||
```
|
||||
|
||||
Most likely you forgot to add `-cap-add=SYS_ADMIN` when using chromium-based brwosers.
|
||||
|
||||
### 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 browser, that it could not connect to dbus. This does not affect us and can be ignored.
|
BIN
docs/getting-started/udp-ports-nc.png
Normal file
BIN
docs/getting-started/udp-ports-nc.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 5.4 KiB |
Reference in New Issue
Block a user