3pp-mirror/neko
1
0
Fork 0
mirror of https://github.com/m1k1o/neko.git synced 2025-07-24 20:17:58 +02:00
Code Issues Projects Releases Packages Wiki Activity

update docs.

Browse source
This commit is contained in:
Miroslav Šedivý 2025-03-22 18:53:45 +01:00
parent 6f3760e5b9
commit e3cdad3f81
41 changed files with 213 additions and 198 deletions
Download patch file Download diff file Expand all files Collapse all files

228
webpage/docs/reference/v2-migration/README.md Normal file
View file

@ -0,0 +1,228 @@
---
sidebar_position: 3
---
# V2 Migration Guide
Currently, Neko is in compatibility mode, meaning that as soon as a single V2 configuration option is set, the legacy mode is enabled. This approach allows for a smooth transition from V2 to V3, where it does not expose the V2 API for new users but still allows existing users who use the old configuration to continue using it as before.
The legacy mode can be explicitly enabled or disabled by setting the `NEKO_LEGACY` environment variable to `true` or `false`.
:::tip
You can migrate to a new configuration even if you are using a V2 client. Just make sure to set the `NEKO_LEGACY` environment variable to `true`.
:::
:::info Built-in Client
When using Neko in a container with a built-in client, the client will always be compatible with the server regardless of what configuration is used.
:::
## Configuration
V3 is compatible with V2 configuration options when legacy support is enabled. You should be able to run V3 with the V2 configuration without any issues.
The configuration in Neko V3 has been structured differently compared to V2. The V3 configuration is more modular and allows for more flexibility. The V3 configuration is split into multiple sections, each section is responsible for a specific part of the application. This allows for better organization and easier management of the configuration.
In order to migrate from V2 to V3, you need to update the configuration to the new format. The following table shows the mapping between the V2 and V3 configuration options.
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_LOGS=true` | `NEKO_LOG_DIR=/var/log/neko`, V3 allows specifying the log directory |
| `NEKO_CERT` | `NEKO_SERVER_CERT` |
| `NEKO_KEY` | `NEKO_SERVER_KEY` |
| `NEKO_BIND` | `NEKO_SERVER_BIND` |
| `NEKO_PROXY` | `NEKO_SERVER_PROXY` |
| `NEKO_STATIC` | `NEKO_SERVER_STATIC` |
| `NEKO_PATH_PREFIX` | `NEKO_SERVER_PATH_PREFIX` |
| `NEKO_CORS` | `NEKO_SERVER_CORS` |
| `NEKO_LOCKS` | `NEKO_SESSION_LOCKED_CONTROLS` and `NEKO_SESSION_LOCKED_LOGINS`, <br /> V3 allows separate locks for controls and logins |
| `NEKO_IMPLICIT_CONTROL` | `NEKO_SESSION_IMPLICIT_HOSTING` |
| `NEKO_CONTROL_PROTECTION` | `NEKO_SESSION_CONTROL_PROTECTION` |
| `NEKO_HEARTBEAT_INTERVAL` | `NEKO_SESSION_HEARTBEAT_INTERVAL` |
See the V3 [configuration options](/docs/v3/getting-started/configuration).
### WebRTC Video
See the V3 configuration options for the [WebRTC Video](/docs/v3/reference/configuration/capture#webrtc-video).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_DISPLAY` | `NEKO_CAPTURE_VIDEO_DISPLAY` and `NEKO_DESKTOP_DISPLAY`, <br /> consider using `DISPLAY` env variable if both should be the same |
| `NEKO_VIDEO_CODEC` | `NEKO_CAPTURE_VIDEO_CODEC` |
| `NEKO_AV1=true` *deprecated* | `NEKO_CAPTURE_VIDEO_CODEC=av1` |
| `NEKO_H264=true` *deprecated* | `NEKO_CAPTURE_VIDEO_CODEC=h264` |
| `NEKO_VP8=true` *deprecated* | `NEKO_CAPTURE_VIDEO_CODEC=vp8` |
| `NEKO_VP9=true` *deprecated* | `NEKO_CAPTURE_VIDEO_CODEC=vp9` |
| `NEKO_VIDEO` | `NEKO_CAPTURE_VIDEO_PIPELINE`, V3 allows multiple video pipelines |
| `NEKO_VIDEO_BITRATE` | **removed**, use custom pipeline instead |
| `NEKO_HWENC` | **removed**, use custom pipeline instead |
| `NEKO_MAX_FPS` | **removed**, use custom pipeline instead |
:::warning Limitation
V2 did not have client-side cursor support, the cursor was always part of the video stream. In V3, the cursor is sent separately from the video stream. Therefore, when using legacy configuration, there will be two video streams created, one with the cursor (for V2 clients) and one without the cursor (for V3 clients). Please consider using new configuration options if this is not the desired behavior.
:::
### WebRTC Audio
See the V3 configuration options for the [WebRTC Audio](/docs/v3/reference/configuration/capture#webrtc-audio).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_DEVICE` | `NEKO_CAPTURE_AUDIO_DEVICE` |
| `NEKO_AUDIO_CODEC` | `NEKO_CAPTURE_AUDIO_CODEC` |
| `NEKO_G722=true` *deprecated* | `NEKO_CAPTURE_AUDIO_CODEC=g722` |
| `NEKO_OPUS=true` *deprecated* | `NEKO_CAPTURE_AUDIO_CODEC=opus` |
| `NEKO_PCMA=true` *deprecated* | `NEKO_CAPTURE_AUDIO_CODEC=pcma` |
| `NEKO_PCMU=true` *deprecated* | `NEKO_CAPTURE_AUDIO_CODEC=pcmu` |
| `NEKO_AUDIO` | `NEKO_CAPTURE_AUDIO_PIPELINE` |
| `NEKO_AUDIO_BITRATE` | **removed**, use custom pipeline instead |
### Broadcast
See the V3 configuration options for the [Broadcast](/docs/v3/reference/configuration/capture#broadcast).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_BROADCAST_PIPELINE` | `NEKO_CAPTURE_BROADCAST_PIPELINE` |
| `NEKO_BROADCAST_URL` | `NEKO_CAPTURE_BROADCAST_URL` |
| `NEKO_BROADCAST_AUTOSTART` | `NEKO_CAPTURE_BROADCAST_AUTOSTART` |
### Desktop
See the V3 configuration options for the [Desktop](/docs/v3/reference/configuration/desktop).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_SCREEN` | `NEKO_DESKTOP_SCREEN` |
### Authentication
See the V3 configuration options for the [Authentication](/docs/v3/reference/configuration/authentication).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_PASSWORD` | `NEKO_MEMBER_MULTIUSER_USER_PASSWORD` with `NEKO_MEMBER_PROVIDER=multiuser` |
| `NEKO_PASSWORD_ADMIN` | `NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD` with `NEKO_MEMBER_PROVIDER=multiuser` |
In order for the legacy authentication to work, you need to set [Multi-user](http://localhost:3000/docs/v3/reference/configuration/authentication#multi-user-provider).
:::warning Limitation
V2 clients might not be compatible with any other authentication provider than the `multiuser`.
:::
### WebRTC
See the V3 configuration options for the [WebRTC](/docs/v3/reference/configuration/webrtc).
| **V2 Configuration** | **V3 Configuration** |
|---------------------------------------|-----------------------------------------------------------|
| `NEKO_NAT1TO1` | `NEKO_WEBRTC_NAT1TO1` |
| `NEKO_TCPMUX` | `NEKO_WEBRTC_TCPMUX` |
| `NEKO_UDPMUX` | `NEKO_WEBRTC_UDPMUX` |
| `NEKO_ICELITE` | `NEKO_WEBRTC_ICELITE` |
| `NEKO_ICESERVERS` or `NEKO_ICESERVER` | `NEKO_WEBRTC_ICESERVERS_FRONTEND` and `NEKO_WEBRTC_ICESERVERS_BACKEND`, <br /> V3 allows separate ICE servers for frontend and backend |
| `NEKO_IPFETCH` | `NEKO_WEBRTC_IP_RETRIEVAL_URL` |
| `NEKO_EPR` | `NEKO_WEBRTC_EPR` |
### Full V2 Configuration Reference
Here is a full list of all the configuration options available in Neko V2 that are still available in Neko V3 with legacy support enabled.
import Configuration from '@site/src/components/Configuration';
import configOptions from './help.json';
<Configuration configOptions={configOptions} />
See the full [V3 configuration reference](/docs/v3/reference/configuration/#full-configuration-reference) for more details.
## API
V3 is compatible with the V2 API when legacy support is enabled. There was specifically created a compatibility layer (legacy API) that allows V2 clients to connect to V3. The legacy API is enabled by default, but it can be disabled if needed. In later versions, the legacy API will be removed.
### Authentication
In V2 there was only one authentication provider available, as in V3 called the `multiuser` provider. The API knew based on the provided password (as `?pwd=` query string) if the user is an admin or not.
Since V3 handles authentication differently (see [API documentation](/docs/v3/api#authentication)), there has been added `?usr=` query string to the API to specify the username. The password is still provided as `?pwd=` query string. The `?usr=` query string is still optional, if not provided, the API will generate a random username.
:::warning Limitation
For every request in the legacy API, a new user session is created based on the `?usr=&pwd=` query string. The session is destroyed after the API request is completed. So for HTTP API requests, the sessions are short-lived but for WebSocket API requests, the session is kept alive until the WebSocket connection is closed.
:::
Only the `multiuser` provider (or the `noauth` provider) is supported without specifying the `?usr=` query string.
### WebSocket Messages
Since WebSocket messages are not user-facing API, there exists no migration guide for them. When the legacy API is enabled, the user connects to the `/ws` endpoint and is handled by the compatibility layer V2 API. The V3 API is available at the `/api/ws` endpoint.
### WebRTC API
Since the WebRTC API is not user-facing API, there exists no migration guide for it. It has been changed to Big Endian format (previously Little Endian) to allow easier manipulation on the client side.
V2 created a new data channel on the client side, V3 creates a new data channel on the server side. That means, the server just listens for a new data channel from the client and accepts it with the legacy API handler. It overwrites the existing V3 data channel with the legacy one.
### HTTP API
The V2 version had a very limited HTTP API, the V3 API is much more powerful and flexible. See the [API documentation](/docs/v3/api) for more details.
#### GET `/health`
Migrated to the [Health](/docs/v3/api/healthcheck) endpoint for server health checks.
Returns `200 OK` if the server is running.
#### GET `/stats`
Migrated to the [Stats](/docs/v3/api/stats) endpoint for server statistics and the [List Sessions](/docs/v3/api/sessions-get) endpoint for the session list.
Returns a JSON object with the following structure:
```json
{
// How many connections are currently active
"connections": 0,
// Who is currently having a session (empty if no one)
"host": "<session_id>",
// List of currently connected users
"members": [
{
"session_id": "<session_id>",
"displayname": "Name",
"admin": true,
"muted": false,
}
],
// List of banned IPs and who banned them as a session_id
"banned": {
"<ip>": "<session_id>"
},
// List of locked resources and who locked them as a session_id
"locked": {
"<resource>": "<session_id>"
},
// Server uptime
"server_started_at": "2021-01-01T00:00:00Z",
// When was the last admin or user left the session
"last_admin_left_at": "2021-01-01T00:00:00Z",
"last_user_left_at": "2021-01-01T00:00:00Z",
// Whether the control protection or implicit control is enabled
"control_protection": false,
"implicit_control": false,
}
```
#### GET `/screenshot.jpg`
Migrated to the [Screenshot](/docs/v3/api/screen-shot-image) endpoint for taking screenshots.
Returns a screenshot of the desktop as a JPEG image.
#### GET `/file`
The whole functionality of file transfer has been moved to a [File Transfer Plugin](/docs/v3/reference/configuration/plugins#file-transfer-plugin).
## Limitations
In v2, locks and muted users were managed using a simple map that tracked who set the lock and what was locked. In v3, locks are now implemented as setting options and no longer store the `session_id` of the user who applied the lock. As a result, if a client refreshes the page or reconnects, the lock information is lost, and the user who set the lock is displayed as `Somebody`.
Additionally, when using the legacy API with a v2 client, API calls occur in a different order than expected. The client first retrieves the session list before registering the user, meaning the current `session_id` is not known when the session list is fetched. That means, the current user appears as `Somebody` in the session list.

333
webpage/docs/reference/v2-migration/help.json Normal file
View file

@ -0,0 +1,333 @@
[
{
"key": [
"legacy"
],
"type": "boolean",
"defaultValue": "true",
"description": "enable legacy mode"
},
{
"key": [
"logs"
],
"type": "boolean",
"defaultValue": "false",
"description": "save logs to file"
},
{
"key": [
"display"
],
"type": "string",
"description": "XDisplay to capture"
},
{
"key": [
"video_codec"
],
"type": "string",
"description": "video codec to be used"
},
{
"key": [
"av1"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use video_codec"
},
{
"key": [
"h264"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use video_codec"
},
{
"key": [
"vp8"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use video_codec"
},
{
"key": [
"vp9"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use video_codec"
},
{
"key": [
"video"
],
"type": "string",
"description": "video codec parameters to use for streaming"
},
{
"key": [
"video_bitrate"
],
"type": "int",
"description": "video bitrate in kbit/s"
},
{
"key": [
"hwenc"
],
"type": "string",
"description": "use hardware accelerated encoding"
},
{
"key": [
"max_fps"
],
"type": "int",
"description": "maximum fps delivered via WebRTC, 0 is for no maximum"
},
{
"key": [
"device"
],
"type": "string",
"description": "audio device to capture"
},
{
"key": [
"audio_codec"
],
"type": "string",
"description": "audio codec to be used"
},
{
"key": [
"g722"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use audio_codec"
},
{
"key": [
"opus"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use audio_codec"
},
{
"key": [
"pcma"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use audio_codec"
},
{
"key": [
"pcmu"
],
"type": "boolean",
"defaultValue": "false",
"description": "DEPRECATED: use audio_codec"
},
{
"key": [
"audio"
],
"type": "string",
"description": "audio codec parameters to use for streaming"
},
{
"key": [
"audio_bitrate"
],
"type": "int",
"description": "audio bitrate in kbit/s"
},
{
"key": [
"broadcast_pipeline"
],
"type": "string",
"description": "custom gst pipeline used for broadcasting, strings {url} {device} {display} will be replaced"
},
{
"key": [
"broadcast_url"
],
"type": "string",
"description": "a default default URL for broadcast streams, can be disabled/changed later by admins in the GUI"
},
{
"key": [
"broadcast_autostart"
],
"type": "boolean",
"defaultValue": "false",
"description": "automatically start broadcasting when neko starts and broadcast_url is set"
},
{
"key": [
"screen"
],
"type": "string",
"description": "default screen resolution and framerate"
},
{
"key": [
"password"
],
"type": "string",
"description": "password for connecting to stream"
},
{
"key": [
"password_admin"
],
"type": "string",
"description": "admin password for connecting to stream"
},
{
"key": [
"cert"
],
"type": "string",
"description": "path to the SSL cert used to secure the neko server"
},
{
"key": [
"key"
],
"type": "string",
"description": "path to the SSL key used to secure the neko server"
},
{
"key": [
"bind"
],
"type": "string",
"description": "address/port/socket to serve neko"
},
{
"key": [
"proxy"
],
"type": "boolean",
"defaultValue": "false",
"description": "enable reverse proxy mode"
},
{
"key": [
"static"
],
"type": "string",
"description": "path to neko client files to serve"
},
{
"key": [
"path_prefix"
],
"type": "string",
"description": "path prefix for HTTP requests"
},
{
"key": [
"cors"
],
"type": "strings",
"description": "list of allowed origins for CORS"
},
{
"key": [
"locks"
],
"type": "strings",
"description": "resources, that will be locked when starting (control, login)"
},
{
"key": [
"implicit_control"
],
"type": "boolean",
"defaultValue": "false",
"description": "if enabled members can gain control implicitly"
},
{
"key": [
"control_protection"
],
"type": "boolean",
"defaultValue": "false",
"description": "control protection means, users can gain control only if at least one admin is in the room"
},
{
"key": [
"heartbeat_interval"
],
"type": "int",
"defaultValue": "120",
"description": "heartbeat interval in seconds"
},
{
"key": [
"nat1to1"
],
"type": "strings",
"description": "sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP "
},
{
"key": [
"tcpmux"
],
"type": "int",
"description": "single TCP mux port for all peers"
},
{
"key": [
"udpmux"
],
"type": "int",
"description": "single UDP mux port for all peers"
},
{
"key": [
"icelite"
],
"type": "boolean",
"defaultValue": "false",
"description": "configures whether or not the ice agent should be a lite agent"
},
{
"key": [
"iceserver"
],
"type": "strings",
"description": "describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection "
},
{
"key": [
"iceservers"
],
"type": "string",
"description": "describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection "
},
{
"key": [
"ipfetch"
],
"type": "string",
"description": "automatically fetch IP address from given URL when nat1to1 is not present"
},
{
"key": [
"epr"
],
"type": "string",
"description": "limits the pool of ephemeral ports that ICE UDP connections can allocate from"
}
]

52
webpage/docs/reference/v2-migration/help.txt Normal file
View file

@ -0,0 +1,52 @@
--legacy enable legacy mode (default true)
--logs save logs to file
--display string XDisplay to capture
--video_codec string video codec to be used
--av1 DEPRECATED: use video_codec
--h264 DEPRECATED: use video_codec
--vp8 DEPRECATED: use video_codec
--vp9 DEPRECATED: use video_codec
--video string video codec parameters to use for streaming
--video_bitrate int video bitrate in kbit/s
--hwenc string use hardware accelerated encoding
--max_fps int maximum fps delivered via WebRTC, 0 is for no maximum
--device string audio device to capture
--audio_codec string audio codec to be used
--g722 DEPRECATED: use audio_codec
--opus DEPRECATED: use audio_codec
--pcma DEPRECATED: use audio_codec
--pcmu DEPRECATED: use audio_codec
--audio string audio codec parameters to use for streaming
--audio_bitrate int audio bitrate in kbit/s
--broadcast_pipeline string custom gst pipeline used for broadcasting, strings {url} {device} {display} will be replaced
--broadcast_url string a default default URL for broadcast streams, can be disabled/changed later by admins in the GUI
--broadcast_autostart automatically start broadcasting when neko starts and broadcast_url is set
--screen string default screen resolution and framerate
--password string password for connecting to stream
--password_admin string admin password for connecting to stream
--cert string path to the SSL cert used to secure the neko server
--key string path to the SSL key used to secure the neko server
--bind string address/port/socket to serve neko
--proxy enable reverse proxy mode
--static string path to neko client files to serve
--path_prefix string path prefix for HTTP requests
--cors strings list of allowed origins for CORS
--locks strings resources, that will be locked when starting (control, login)
--implicit_control if enabled members can gain control implicitly
--control_protection control protection means, users can gain control only if at least one admin is in the room
--heartbeat_interval int heartbeat interval in seconds (default 120)
--nat1to1 strings sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP
--tcpmux int single TCP mux port for all peers
--udpmux int single UDP mux port for all peers
--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
--iceservers string describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection
--ipfetch string automatically fetch IP address from given URL when nat1to1 is not present
--epr string limits the pool of ephemeral ports that ICE UDP connections can allocate from