Beta13 additions: metrics, S3 file transfer, guest query access and tuning options

CONFIG.md

@@ -2,8 +2,7 @@
 
 ### TeamSpeak 6 Server: Frequently Used Parameters & Environment Variables
 
-This document provides a detailed list of frequently used command-line parameters and their corresponding environment variables for configuring the TeamSpeak 6 server. You can configure the server using:
+This document outlines the most commonly used command-line parameters and their equivalent environment variables for configuring the TeamSpeak 6 server. You can configure the server using either of the following methods:
-
 - Command-line flags
 - Environment variables
 - A `tsserver.yaml` configuration file
@@ -13,47 +12,101 @@ This document provides a detailed list of frequently used command-line parameter
 #### General & Core Server Configuration
 
 | Parameter                     | Environment Variable           | Description                                                                                                                                           |
-|----------------------------------|--------------------------------|-----------------------------------------------------------------------------|
+|-------------------------------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `--config-file <file>`        | `TSSERVER_CONFIG_FILE`         | Specifies the configuration file to load (e.g., `tsserver.yaml`).                                                                                     |
 | `--license-path <path>`       | `TSSERVER_LICENSE_PATH`        | Directory path where the server will look for the `licensekey.dat` file.                                                                              |
-| `--accept-license [0\|1]`        | `TSSERVER_LICENSE_ACCEPTED`    | Set to `1` or `accept` to agree to the server license.                     |
+| `--accept-license`            | `TSSERVER_LICENSE_ACCEPTED`    | Use the --accept-license flag or set the environment variable to 1 or accept to confirm that you have read and accepted the server license agreement. |
-| `--default-voice-port <port>`    | `TSSERVER_DEFAULT_PORT`        | Sets the default UDP voice port for the first virtual server (Default: 9987). |
+| `--default-voice-port <port>` | `TSSERVER_DEFAULT_PORT`        | Permanently sets the default UDP voice port for the first virtual server created (Default: 9987).                                                     |
+| `--log-timezone <zone>`       | `TSSERVER_LOG_TIMEZONE`        | Time zone used for log timestamps, `utc` (default) or `local`. On Windows, `local` requires Windows 10 1903 / Windows Server 2022 or later.           |
 
 ---
 
 #### File Transfer
 
 | Parameter                         | Environment Variable           | Description                                            |
-|----------------------------------|--------------------------------|-----------------------------------------------------------------------------|
+|-----------------------------------|--------------------------------|--------------------------------------------------------|
-| `--filetransfer-port <port>`     | `TSSERVER_FILE_TRANSFER_PORT`  | The TCP port used for file transfers (Default: 30033).                      |         |
+| `--filetransfer-port <port>`      | `TSSERVER_FILE_TRANSFER_PORT`  | The TCP port used for file transfers (Default: 30033). |
+
+---
+
+#### S3 File Transfer
+
+When enabled, the server stores channel files in an S3 compatible bucket and hands clients presigned URLs instead of serving the transfer itself.
+
+| Parameter                              | Environment Variable                     | Description                                                             |
+|----------------------------------------|------------------------------------------|-------------------------------------------------------------------------|
+| `--s3ft-enabled`                       | `TSSERVER_S3FT_ENABLED`                  | Enables S3 file transfer (Default: off).                                |
+| `--s3ft-domain <host>`                 | `TSSERVER_S3FT_DOMAIN`                   | Endpoint domain of the S3 service, for example an AWS or MinIO host.    |
+| `--s3ft-bucket <name>`                 | `TSSERVER_S3FT_BUCKET`                   | Bucket the server stores files in.                                      |
+| `--s3ft-region <region>`               | `TSSERVER_S3FT_REGION`                   | Region of the bucket.                                                   |
+| `--s3ft-access-key <key>`              | `TSSERVER_S3FT_ACCESS_KEY`               | Access key used to authenticate against the S3 service.                 |
+| `--s3ft-secret-key <key>`              | `TSSERVER_S3FT_SECRET_KEY`               | Secret key belonging to the access key.                                 |
+| `--s3ft-account-id <id>`               | `TSSERVER_S3FT_ACCOUNT_ID`               | Optional account id, required by some providers.                        |
+| `--s3ft-presigned-url-expiration <sec>`| `TSSERVER_S3FT_PRESIGNED_URL_EXPIRATION` | Lifetime of a presigned URL in seconds (Default: 300).                  |
 
 ---
 
 #### Database
 
 | Parameter                         | Environment Variable              | Description                                                                           |
-|----------------------------------|--------------------------------|-----------------------------------------------------------------------------|
+|----------------------------------|------------------------------------|---------------------------------------------------------------------------------------|
 | `--db-plugin <plugin>`           | `TSSERVER_DATABASE_PLUGIN`         | Specifies the database plugin to use (e.g., `sqlite3`, `mariadb`).                    |
 | `--db-host <host>`               | `TSSERVER_DATABASE_HOST`           | The hostname or IP address of your database server.                                   |
 | `--db-port <port>`               | `TSSERVER_DATABASE_PORT`           | The port used to connect to your database server.                                     |
 | `--db-name <name>`               | `TSSERVER_DATABASE_NAME`           | The name of the database to use.                                                      |
 | `--db-username <user>`           | `TSSERVER_DATABASE_USERNAME`       | The username for database authentication.                                             |
 | `--db-password <pass>`           | `TSSERVER_DATABASE_PASSWORD`       | The password for database authentication.                                             |
-| `--db-connections <num>`         | `TSSERVER_DATABASE_CONNECTIONS`| Number of connections to establish to the database (Default: 10).          |
+| `--db-connections <num>`         | `TSSERVER_DATABASE_CONNECTIONS`    | Number of connections to establish to the database (Default: 10).                     |
+| `--db-sql-create-path <path>`    | `TSSERVER_DATABASE_SQL_CREATE_PATH`| The path for the database creation scripts (e.g., `create_mariadb`, `create_sqlite`). |
 
 ---
 
 #### Server Query
 
 | Parameter                       | Environment Variable             | Description                                                                 |
-|----------------------------------|----------------------------------|-------------------------------------------------------------------------|
+|---------------------------------|----------------------------------|-----------------------------------------------------------------------------|
-| `--query-http-enable [0\|1]`     | `TSSERVER_QUERY_HTTP_ENABLED`    | Enables the HTTP query interface.                                      |
+| `--query-http-enable`           | `TSSERVER_QUERY_HTTP_ENABLED`    | Enables the HTTP query interface.                                           |
 | `--query-http-port <port>`      | `TSSERVER_QUERY_HTTP_PORT`       | The port for the HTTP query interface (Default: 10080).                     |
-| `--query-ssh-enable [0\|1]`      | `TSSERVER_QUERY_SSH_ENABLED`     | Enables the SSH query interface.                                       |
+| `--query-ssh-enable`            | `TSSERVER_QUERY_SSH_ENABLED`     | Enables the SSH query interface.                                            |
 | `--query-ssh-port <port>`       | `TSSERVER_QUERY_SSH_PORT`        | The port for the SSH query interface (Default: 10022).                      |
 | `--query-admin-password <pass>` | `TSSERVER_QUERY_ADMIN_PASSWORD`  | Sets a password for the serveradmin query account, overriding the database. |
 | `--query-ip-allow-list <file>`  | `TSSERVER_QUERY_ALLOW_LIST`      | Path to a file listing IPs exempt from query flood protection.              |
 | `--query-ip-block-list <file>`  | `TSSERVER_QUERY_DENY_LIST`       | Path to a file listing IPs that are blocked from the query interface.       |
+| `--query-admin-api-key <key>`   | `TSSERVER_QUERY_ADMIN_API_KEY`   | Sets the Web Query API key of the serveradmin account.                      |
+| `--query-ssh-allow-guest <0/1>` | `TSSERVER_QUERY_SSH_ALLOW_GUEST` | Allow unauthenticated guest sessions on SSH (user `guest`), (Default: 1).   |
+| `--query-http-allow-guest <0/1>`| `TSSERVER_QUERY_HTTP_ALLOW_GUEST`| Allow unauthenticated guest requests on Web Query, (Default: 1).            |
+
+---
+
+#### Metrics
+
+The server can expose its monitoring data as Prometheus metrics, without a ServerQuery admin
+key. The endpoint is disabled by default, and when enabled it is unauthenticated.
+
+| Parameter                  | Environment Variable        | Description                                                                                               |
+|----------------------------|-----------------------------|-----------------------------------------------------------------------------------------------------------|
+| `--metrics-enable`         | `TSSERVER_METRICS_ENABLED`  | Enables the Prometheus metrics endpoint, scraped at `GET /metrics`.                                       |
+| `--metrics-port <port>`    | `TSSERVER_METRICS_PORT`     | Port for the metrics endpoint (Default: 9187).                                                            |
+| `--metrics-ip <ip>`        | `TSSERVER_METRICS_IP`       | Address(es) to bind the endpoint to (Default: localhost only).                                            |
+| `--metrics-voice`          | `TSSERVER_METRICS_VOICE`    | Adds per-packet voice diagnostics. This instruments the hot path, so benchmark before enabling under load. |
+
+---
+
+#### Performance Tuning
+
+The defaults suit most servers. Change these only when you have measured a reason to.
+
+| Parameter                        | Environment Variable             | Description                                                                            |
+|----------------------------------|----------------------------------|----------------------------------------------------------------------------------------|
+| `--threads-voice-udp <n>`        | `TSSERVER_VOICE_UDP_THREADS`     | Threads for UDP socket send/receive, shared by all packet types (Default: 16).         |
+| `--threads-voice <n>`            | `TSSERVER_VOICE_THREADS`         | Threads per virtual server for voice packets (Default: 4).                             |
+| `--threads-command <n>`          | `TSSERVER_COMMAND_THREADS`       | Threads per virtual server for command packets (Default: 4).                           |
+| `--threads-ack <n>`              | `TSSERVER_ACK_THREADS`           | Threads per virtual server for acknowledge packets (Default: 3).                       |
+| `--threads-ping <n>`             | `TSSERVER_PING_THREADS`          | Threads per virtual server for ping and pong packets (Default: 2).                     |
+| `--threads-init <n>`             | `TSSERVER_INIT_THREADS`          | Threads per virtual server for connection initialization packets (Default: 2).         |
+| `--socket-read-depth <n>`        | `TSSERVER_SOCKET_READ_DEPTH`     | Concurrent receives per UDP socket, only worthwhile at high packet rates (Default: 4). |
+| `--socket-receive-buffer <bytes>`| `TSSERVER_SOCKET_RECEIVE_BUFFER` | UDP receive buffer, clamped by the kernel to `net.core.rmem_max` (Default: 4194304).   |
+| `--socket-send-buffer <bytes>`   | `TSSERVER_SOCKET_SEND_BUFFER`    | UDP send buffer, clamped by the kernel to `net.core.wmem_max` (Default: 4194304).      |
 
 ### Example `tsserver.yaml` Configuration
 
@@ -133,264 +186,548 @@ server:
       private-key: ""
 ```
 
-### Further Options
+### Further Parameters and Environment Variables
 
 #### General Options
 
-- **`-h, --help`**
+* **`-h, --help`**
-    - Prints the help message and exits.
 
-- **`--write-config-file`**
+  * Prints the help message and exits.
-    - Writes the current configuration to the config file.
+  * **Type:** `BOOLEAN FLAG`
 
-- **`--config-file [tsserver.yaml]`**
+* **`--accept-license`**
-    - Configuration file to load.
-    - **Environment Variable:** `TSSERVER_CONFIG_FILE`
 
-- **`-v, --version`**
+  * Confirms you have read and accepted the server license agreement.
-    - Displays program version information and exits.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_LICENSE_ACCEPTED`
 
-- **`--license-path [.]`**
+* **`--write-config-file`**
-    - Path where the server will look for the server license.
+
-    - **Environment Variable:** `TSSERVER_LICENSE_PATH`
+  * Writes the current configuration to the config file.
+  * **Type:** `BOOLEAN FLAG`
+
+* **`--config-file [tsserver.yaml]`**
+
+  * Configuration file to load.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_CONFIG_FILE`
+
+* **`-v, --version`**
+
+  * Displays program version information and exits.
+  * **Type:** `BOOLEAN FLAG`
+
+* **`--license-path [.]`**
+
+  * Path where the server will look for the server license.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_LICENSE_PATH`
+
+---
 
 #### Server Configuration
 
-- **`--default-voice-port :INT in [1 - 65535] [9987]`**
+* **`--default-voice-port [9987]`**
-    - Sets the default voice port for the first virtual server.
-    - **Environment Variable:** `TSSERVER_DEFAULT_PORT`
 
-- **`--voice-ip [[0.0.0.0,::]]`**
+  * Permanently sets the default voice port for the first virtual server created.
-    - IP address for the server to bind the voice port to.
+  * **Type:** `INTEGER in [1 - 65535]`
-    - **Environment Variable:** `TSSERVER_VOICE_IP`
+  * **Environment Variable:** `TSSERVER_DEFAULT_PORT`
 
-- **`--machine-id`**
+* **`--voice-ip [[0.0.0.0,::]]`**
-    - A string to distinguish this instance from other instances using the same database.
-    - **Environment Variable:** `TSSERVER_MACHINE_ID`
 
-- **`--threads-voice-udp :UINT in [1 - 16] [5]`**
+  * IP address for the server to bind the voice port to.
-    - Number of threads to use for voice processing.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_VOICE_UDP_THREADS`
+  * **Environment Variable:** `TSSERVER_VOICE_IP`
+
+* **`--machine-id`**
+
+  * A string to distinguish this instance from other instances using the same database.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_MACHINE_ID`
+
+* **`--threads-voice-udp [16]`**
+
+  * Threads for UDP socket send/receive, shared by all packet types and virtual servers.
+  * **Type:** `INTEGER in [1 - 32]`
+  * **Environment Variable:** `TSSERVER_VOICE_UDP_THREADS`
+
+---
 
 #### Logging
 
-- **`--log-path [logs]`**
+* **`--log-path [logs]`**
-    - Path to the directory where log files are stored.
-    - **Environment Variable:** `TSSERVER_LOG_PATH`
 
-- **`--log-append [0]`**
+  * Path to the directory where log files are stored.
-    - Write one ever-growing log file per virtual server.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_APPEND_LOGS`
+  * **Environment Variable:** `TSSERVER_LOG_PATH`
+
+* **`--log-append`**
+
+  * Write one ever-growing log file per virtual server.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_APPEND_LOGS`
+
+* **`--log-timezone [utc]`**
+
+  * Time zone used for log timestamps. Valid values are `utc` and `local`.
+  * On Windows, `local` requires Windows 10 1903 / Windows Server 2022 or later.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_LOG_TIMEZONE`
+
+---
 
 #### Virtual Server Management
 
-- **`--no-default-virtual-server [0]`**
+* **`--no-default-virtual-server`**
-    - If specified, no default server is created even if no server exists in the database.
+
-    - **Environment Variable:** `TSSERVER_NO_DEFAULT_SERVER`
+  * If specified, no default server is created even if no server exists in the database.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_NO_DEFAULT_SERVER`
+
+---
 
 #### File Transfer
 
-- **`--filetransfer-port :INT in [1 - 65535] [30033]`**
+* **`--filetransfer-port [30033]`**
-    - Port on which to listen for file transfer connections.
-    - **Environment Variable:** `TSSERVER_FILE_TRANSFER_PORT`
 
-- **`--filetransfer-ip [[0.0.0.0,::]]`**
+  * Port on which to listen and advertise for file transfer connections.
-    - Address on which to listen for file transfer connections.
+  * **Type:** `INTEGER in [1 - 65535]`
-    - **Environment Variable:** `TSSERVER_FILE_TRANSFER_IP`
+  * **Environment Variable:** `TSSERVER_FILE_TRANSFER_PORT`
+  * **Docker Note:** When running inside a Docker container, ensure that the **internal container port matches the external host port**. File transfers rely on clients connecting directly to this port, mismatches between the container's listening port and the published port will cause connectivity issues.
+
+* `--filetransfer-ip [[0.0.0.0,::]]`
+
+  * The address on which to listen for file transfer connections
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_FILE_TRANSFER_IP`
+
+---
+
+#### S3 File Transfer Options
+
+* **`--s3ft-enabled`**
+
+  * Enable S3 file transfer.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_S3FT_ENABLED`
+
+* **`--s3ft-domain`**
+
+  * Endpoint domain of the S3 service, for example an AWS endpoint or a self-hosted MinIO host.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_DOMAIN`
+
+* **`--s3ft-bucket`**
+
+  * Name of the bucket the server stores files in.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_BUCKET`
+
+* **`--s3ft-region`**
+
+  * Region the bucket lives in.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_REGION`
+
+* **`--s3ft-access-key`**
+
+  * Access key used to authenticate against the S3 service.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_ACCESS_KEY`
+
+* **`--s3ft-secret-key`**
+
+  * Secret key belonging to the access key. Prefer the environment variable or the
+    configuration file over the command line, so the value does not show up in the process list.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_SECRET_KEY`
+
+* **`--s3ft-account-id`**
+
+  * Optional account id, required by some S3 providers.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_S3FT_ACCOUNT_ID`
+
+* **`--s3ft-presigned-url-expiration [300]`**
+
+  * How long a presigned URL stays valid, in seconds.
+  * **Type:** `INTEGER`
+  * **Environment Variable:** `TSSERVER_S3FT_PRESIGNED_URL_EXPIRATION`
+
+---
 
 #### Database Configuration
 
-- **`--clear-database [0]`**
+* **`--clear-database`**
-    - **WARNING:** If present, the database is reset to default, and all servers, clients, etc., are lost!
 
-- **`--no-permission-update [0]`**
+  * ⚠️ WARNING: Resets the database completely (deletes all servers, clients, etc.).
-    - Do not apply permission changes with a server update.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_SKIP_PERMISSION_UPDATE`
 
-- **`--db-plugin [sqlite3]`**
+* **`--no-permission-update`**
-    - Specifies which database plugin to use.
-    - **Environment Variable:** `TSSERVER_DATABASE_PLUGIN`
 
-- **`--db-sql-path [sql]`**
+  * Do not apply permission changes during server updates.
-    - Path to the SQL folder containing the SQL queries executed by the server.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_DATABASE_SQL_PATH`
+  * **Environment Variable:** `TSSERVER_SKIP_PERMISSION_UPDATE`
 
-- **`--db-sql-create-path [create_sqlite]`**
+* **`--db-plugin [sqlite3]`**
-    - Path relative to the `--sql-path` where to load the database creation scripts from.
-    - **Environment Variable:** `TSSERVER_DATABASE_SQL_CREATE_PATH`
 
-- **`--db-client-keep-days [30]`**
+  * Specifies the database plugin to use.
-    - Number of days to keep clients in the database.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_DATABASE_CLIENT_KEEP_DAYS`
+  * **Environment Variable:** `TSSERVER_DATABASE_PLUGIN`
 
-#### Advanced Database Configuration
+* **`--db-sql-path [sql]`**
 
-- **`--db-skip-integrity-check [0]`**
+  * Path to folder containing SQL queries used by the server.
-    - SQLite only: Skip the database integrity check when opening the database.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_DATABASE_SKIP_INTEGRITY_CHECK`
+  * **Environment Variable:** `TSSERVER_DATABASE_SQL_PATH`
 
-- **`--db-host [127.0.0.1]`**
+* **`--db-sql-create-path [create_sqlite]`**
-    - Hostname/IP address to use when connecting to the database server.
-    - **Environment Variable:** `TSSERVER_DATABASE_HOST`
 
-- **`--db-port :INT in [1 - 65535] [5432]`**
+  * Subdirectory in SQL path to use for DB creation scripts.
-    - Port to use when connecting to the database server.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_DATABASE_PORT`
+  * **Environment Variable:** `TSSERVER_DATABASE_SQL_CREATE_PATH`
 
-- **`--db-socket`**
+* **`--db-client-keep-days [30]`**
-    - Socket to use for the database connection.
-    - **Environment Variable:** `TSSERVER_DATABASE_SOCKET`
 
-- **`--db-timeout :INT in [1 - 432000] [10]`**
+  * Number of days to keep clients in the database.
-    - Timeout in seconds for the database connection.
+  * **Type:** `INTEGER`
-    - **Environment Variable:** `TSSERVER_DATABASE_TIMEOUT`
+  * **Environment Variable:** `TSSERVER_DATABASE_CLIENT_KEEP_DAYS`
 
-- **`--db-name [teamspeak]`**
+* **`--db-skip-integrity-check`**
-    - The database name to use.
-    - **Environment Variable:** `TSSERVER_DATABASE_NAME`
 
-- **`--db-username`**
+  * SQLite only: skip DB integrity check at startup.
-    - The username to use for database authentication.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_DATABASE_USERNAME`
+  * **Environment Variable:** `TSSERVER_DATABASE_SKIP_INTEGRITY_CHECK`
 
-- **`--db-password`**
+* **`--db-log-queries`**
-    - The password to use for database authentication.
-    - **Environment Variable:** `TSSERVER_DATABASE_PASSWORD`
 
-- **`--db-connections :INT in [2 - 100] [10]`**
+  * Enable logging of SQL queries.
-    - Number of connections to establish to the database.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_DATABASE_CONNECTIONS`
+  * **Environment Variable:** `TSSERVER_DATABASE_LOG_QUERIES`
 
-- **`--db-log-queries [0]`**
+#### Database Connection Options
-    - Whether to log database queries.
+* **`--db-host [127.0.0.1]`**
-    - **Environment Variable:** `TSSERVER_DATABASE_LOG_QUERIES`
+
+  * Database hostname or IP.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_DATABASE_HOST`
+
+* **`--db-port [5432]`**
+
+  * Database port.
+  * **Type:** `INTEGER in [1 - 65535]`
+  * **Environment Variable:** `TSSERVER_DATABASE_PORT`
+
+* **`--db-socket`**
+
+  * Socket file to use for database connection.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_DATABASE_SOCKET`
+
+* **`--db-timeout [10]`**
+
+  * Timeout in seconds when connecting to DB.
+  * **Type:** `INTEGER in [1 - 432000]`
+  * **Environment Variable:** `TSSERVER_DATABASE_TIMEOUT`
+
+* **`--db-name [teamspeak]`**
+
+  * Name of the database to use.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_DATABASE_NAME`
+
+* **`--db-username`**
+
+  * The username to use for database authentication.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_DATABASE_USERNAME`
+
+* **`--db-password`**
+
+  * The password to use for database authentication.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_DATABASE_PASSWORD`
+
+* **`--db-connections [10]`**
+
+  * Number of connections to establish to the database.
+  * **Type:** `INTEGER in [2 - 100]`
+  * **Environment Variable:** `TSSERVER_DATABASE_CONNECTIONS`
+
+---
 
 #### Query Options
 
-- **`--query-pool-size :UINT in [2 - 32] [2]`**
+* **`--query-pool-size [2]`**
-    - Number of threads to use for query command processing.
-    - **Environment Variable:** `TSSERVER_QUERY_POOL_SIZE`
 
-- **`--query-log-timing :INT in [10 - 31556952] [3600]`**
+  * How many threads to use for query command processing.
-    - Interval in seconds after which to log query statistics.
+  * **Type:** `INTEGER in [1 - 32]`
-    - **Environment Variable:** `TSSERVER_QUERY_LOG_TIMING`
+  * **Environment Variable:** `TSSERVER_QUERY_POOL_SIZE`
 
-- **`--query-ip-allow-list [query_ip_allowlist.txt]`**
+* **`--query-log-timing [0]`**
-    - File path to a file which lists the addresses that are exempt from query flood protection.
-    - **Environment Variable:** `TSSERVER_QUERY_ALLOW_LIST`
 
-- **`--query-ip-block-list [query_ip_denylist.txt]`**
+  * Interval in seconds after which to log query statistics, `0` disables them.
-    - File path to a file which lists the addresses that are blocked from the query interface.
+  * **Type:** `INTEGER in [0 - 31556952]`
-    - **Environment Variable:** `TSSERVER_QUERY_DENY_LIST`
+  * **Environment Variable:** `TSSERVER_QUERY_LOG_TIMING`
 
-- **`--query-admin-password`**
+* **`--query-ip-allow-list [query_ip_allowlist.txt]`**
-    - Override the query password for the built-in serveradmin account.
-    - **Environment Variable:** `TSSERVER_QUERY_ADMIN_PASSWORD`
 
-- **`--query-log-commands [0]`**
+  * File path listing IPs exempt from query flood protection.
-    - If specified, every command received on the query interface will be logged.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_QUERY_LOG_COMMANDS`
+  * **Environment Variable:** `TSSERVER_QUERY_ALLOW_LIST`
 
-- **`--query-skip-brute-force-check [0]`**
+* **`--query-ip-block-list [query_ip_denylist.txt]`**
-    - Skips brute force checking when clients connect to the query interface.
-    - **Environment Variable:** `TSSERVER_QUERY_SKIP_BRUTE_FORCE_CHECK`
 
-- **`--query-buffer-mb :INT in [20 - 100] [20]`**
+  * File path listing IPs blocked from the query interface.
-    - Memory allocation for query connection buffering.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_QUERY_BUFFER_MB`
+  * **Environment Variable:** `TSSERVER_QUERY_DENY_LIST`
 
-- **`--query-documentation-path [serverquerydocs]`**
+* **`--query-admin-password`**
-    - Path to the query documentation files.
-    - **Environment Variable:** `TSSERVER_QUERY_DOCUMENTATION_PATH`
 
-- **`--query-timeout [300]`**
+  * Override the query password for the built-in serveradmin account.
-    - Specifies the timeout for query connections.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_QUERY_TIMEOUT`
+  * **Environment Variable:** `TSSERVER_QUERY_ADMIN_PASSWORD`
+
+* **`--query-admin-api-key`**
+
+  * Sets the Web Query API key of the built-in serveradmin account. The first run creates the
+    key, later starts replace the existing manage-scope key.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_ADMIN_API_KEY`
+
+* **`--query-log-commands`**
+
+  * Log every command received on the query interface.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_QUERY_LOG_COMMANDS`
+
+* **`--query-skip-brute-force-check`**
+
+  * Skip brute force checking on query interface connections.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_QUERY_SKIP_BRUTE_FORCE_CHECK`
+
+* **`--query-buffer-mb [20]`**
+
+  * How much memory (in MB) to allocate for query connection buffering.
+  * **Type:** `INTEGER in [20 - 100]`
+  * **Environment Variable:** `TSSERVER_QUERY_BUFFER_MB`
+
+* **`--query-documentation-path [serverquerydocs]`**
+
+  * Path to the query documentation files.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_DOCUMENTATION_PATH`
+
+* **`--query-timeout [300]`**
+
+  * Timeout in seconds before query connections expire.
+  * **Type:** `INTEGER`
+  * **Environment Variable:** `TSSERVER_QUERY_TIMEOUT`
+
+---
 
 #### Query SSH Options
 
-- **`--query-ssh-enable [0]`**
+* **`--query-ssh-enable`**
-    - Enable the SSH query interface.
-    - **Environment Variable:** `TSSERVER_QUERY_SSH_ENABLED`
 
-- **`--query-ssh-port :INT in [1 - 65535] [10022]`**
+  * Enable the SSH query interface.
-    - Port on which to listen for SSH query connections.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_QUERY_SSH_PORT`
+  * **Environment Variable:** `TSSERVER_QUERY_SSH_ENABLED`
 
-- **`--query-ssh-ip [[0.0.0.0,::]]`**
+* **`--query-ssh-port [10022]`**
-    - Address on which to listen for SSH query connections.
-    - **Environment Variable:** `TSSERVER_QUERY_SSH_IP`
 
-- **`--query-ssh-rsa-key [ssh_host_rsa_key]`**
+  * Port on which to listen for SSH query connections.
-    - The SSH RSA host key to use.
+  * **Type:** `INTEGER in [1 - 65535]`
-    - **Environment Variable:** `TSSERVER_QUERY_SSH_RSA_KEY`
+  * **Environment Variable:** `TSSERVER_QUERY_SSH_PORT`
+
+* **`--query-ssh-ip [[0.0.0.0,::]]`**
+
+  * Address to listen on for SSH query connections.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_SSH_IP`
+
+* **`--query-ssh-rsa-key [ssh_host_rsa_key]`**
+
+  * Path to the SSH RSA host key file.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_SSH_RSA_KEY`
+
+* **`--query-ssh-allow-guest [1]`**
+
+  * Allow unauthenticated guest sessions on the SSH query interface, by connecting as user
+    `guest` without a password. What a guest may do is governed by the Guest Server Query
+    group permissions. Set to `0` to require authentication.
+  * **Type:** `BOOLEAN`
+  * **Environment Variable:** `TSSERVER_QUERY_SSH_ALLOW_GUEST`
+
+---
 
 #### Query HTTP Options
 
-- **`--query-http-enable [0]`**
+* **`--query-http-enable`**
-    - Enable the HTTP query interface.
-    - **Environment Variable:** `TSSERVER_QUERY_HTTP_ENABLED`
 
-- **`--query-http-port :INT in [1 - 65535] [10080]`**
+  * Enable the HTTP query interface.
-    - Port on which to listen for Web Query connections.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_QUERY_HTTP_PORT`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTP_ENABLED`
 
-- **`--query-http-ip [[0.0.0.0,::]]`**
+* **`--query-http-port [10080]`**
-    - Address on which to listen for Web Query connections.
+
-    - **Environment Variable:** `TSSERVER_QUERY_HTTP_IP`
+  * Port on which to listen for Web Query connections.
+  * **Type:** `INTEGER in [1 - 65535]`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTP_PORT`
+
+* **`--query-http-ip [[0.0.0.0,::]]`**
+
+  * Address to listen on for Web Query connections.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTP_IP`
+
+* **`--query-http-allow-guest [1]`**
+
+  * Allow requests without an API key on the http and https query interfaces. They run in the
+    `guest` scope, governed by the Guest Server Query group permissions. Set to `0` to require
+    an API key.
+  * **Type:** `BOOLEAN`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTP_ALLOW_GUEST`
+
+---
 
 #### Query HTTPS Options
 
-- **`--query-https-enable [0]`**
+* **`--query-https-enable`**
-    - Enable the HTTPS query interface.
-    - **Environment Variable:** `TSSERVER_QUERY_HTTPS_ENABLED`
 
-- **`--query-https-port :INT in [1 - 65535] [10443]`**
+  * Enable the HTTPS query interface.
-    - Port on which to listen for secure Web Query connections.
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_QUERY_HTTPS_PORT`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTPS_ENABLED`
 
-- **`--query-https-ip [[0.0.0.0,::]]`**
+* **`--query-https-port [10443]`**
-    - Address on which to listen for secure Web Query connections.
-    - **Environment Variable:** `TSSERVER_QUERY_HTTPS_IP`
 
-- **`--query-https-certificate`**
+  * Port on which to listen for secure Web Query connections.
-    - File containing the certificate for secure Web Query connections.
+  * **Type:** `INTEGER in [1 - 65535]`
-    - **Environment Variable:** `TSSERVER_QUERY_HTTPS_CERT`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTPS_PORT`
 
-- **`--query-https-private-key`**
+* **`--query-https-ip [[0.0.0.0,::]]`**
-    - File containing the private key for the certificate.
+
-    - **Environment Variable:** `TSSERVER_QUERY_HTTPS_PRIVATE_KEY`
+  * Address to listen on for secure Web Query connections.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTPS_IP`
+
+* **`--query-https-certificate`**
+
+  * Path to certificate file for HTTPS Web Query.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTPS_CERT`
+
+* **`--query-https-private-key`**
+
+  * Path to private key file used with the certificate.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_QUERY_HTTPS_PRIVATE_KEY`
+
+---
 
 #### Additional Options
 
-- **`--http-proxy`**
+* **`--http-proxy`**
-    - Proxy server for connecting to external services.
-    - **Environment Variable:** `TSSERVER_HTTP_PROXY`
 
-- **`--accept-license [0]`**
+  * Proxy server used for external connections.
-    - Confirms you have read and accepted the server license agreement.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_LICENSE_ACCEPTED`
+  * **Environment Variable:** `TSSERVER_HTTP_PROXY`
 
-- **`--crashdump-path [crashdumps]`**
+* **`--crashdump-path [crashdumps]`**
-    - Path to store crash dumps.
-    - **Environment Variable:** `TSSERVER_CRASHDUMP_PATH`
 
-- **`--daemon [0]`**
+  * Path where crash dumps should be written.
-    - Run the server in the background.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_DAEMON`
+  * **Environment Variable:** `TSSERVER_CRASHDUMP_PATH`
 
-- **`--pid-file`**
+* **`--daemon`**
-    - File to store the process ID of the server.
-    - **Environment Variable:** `TSSERVER_PID_FILE`
 
-- **`--hints-enabled [0]`**
+  * Run the server in the background (daemon mode).
-    - Enable permission hints (may affect performance on larger servers).
+  * **Type:** `BOOLEAN FLAG`
-    - **Environment Variable:** `TSSERVER_HINTS_ENABLED`
+  * **Environment Variable:** `TSSERVER_DAEMON`
 
-- **`--maxmind-db-path`**
+* **`--pid-file`**
-    - Path to the MaxMind IP database.
-    - **Environment Variable:** `TSSERVER_MAXMIND_DB_PATH`
 
-- **`--administrative-domain`**
+  * File to write the process ID to.
-    - Administrative domain.
+  * **Type:** `STRING`
-    - **Environment Variable:** `TSSERVER_ADMINISTRATIVE_DOMAIN`
+  * **Environment Variable:** `TSSERVER_PID_FILE`
+
+* **`--hints-enabled`**
+
+  * Enable permission hints (can impact performance on large servers).
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_HINTS_ENABLED`
+
+* **`--maxmind-db-path`**
+
+  * Path to the MaxMind GeoIP database.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_MAXMIND_DB_PATH`
+
+* **`--administrative-domain`**
+
+  * Administrative domain for internal or regulatory identification.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_ADMINISTRATIVE_DOMAIN`
+
+---
+
+#### Metrics Options
+
+* **`--metrics-enable`**
+
+  * Enable the Prometheus metrics endpoint, scraped at `GET /metrics`.
+  * The endpoint is unauthenticated. Keep it on the default loopback bind address, or
+    restrict access with a firewall or reverse proxy.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_METRICS_ENABLED`
+
+* **`--metrics-port [9187]`**
+
+  * Port for the Prometheus metrics endpoint.
+  * **Type:** `INTEGER in [1 - 65535]`
+  * **Environment Variable:** `TSSERVER_METRICS_PORT`
+
+* **`--metrics-ip [[127.0.0.1,::1]]`**
+
+  * Address(es) to bind the metrics endpoint to.
+  * **Type:** `STRING`
+  * **Environment Variable:** `TSSERVER_METRICS_IP`
+
+* **`--metrics-voice`**
+
+  * Add per-packet voice diagnostics, such as forwarding latency, queueing, drops and
+    admission. This instruments the voice hot path, so benchmark before enabling it on a
+    busy server.
+  * **Type:** `BOOLEAN FLAG`
+  * **Environment Variable:** `TSSERVER_METRICS_VOICE`
+
+---
+
+#### Performance Tuning Options
+
+The defaults suit most servers. Change these only when measurements call for it.
+
+* **`--threads-voice [4]`**, **`--threads-command [4]`**, **`--threads-ack [3]`**,
+  **`--threads-ping [2]`**, **`--threads-init [2]`**
+
+  * Threads per virtual server for voice, command, acknowledge, ping/pong and connection
+    initialization packets.
+  * **Type:** `INTEGER in [1 - 32]`
+  * **Environment Variables:** `TSSERVER_VOICE_THREADS`, `TSSERVER_COMMAND_THREADS`,
+    `TSSERVER_ACK_THREADS`, `TSSERVER_PING_THREADS`, `TSSERVER_INIT_THREADS`
+
+* **`--socket-read-depth [4]`**
+
+  * Concurrent receives per UDP socket. Only worthwhile at high packet rates.
+  * **Type:** `INTEGER in [1 - 32]`
+  * **Environment Variable:** `TSSERVER_SOCKET_READ_DEPTH`
+
+* **`--socket-receive-buffer [4194304]`** and **`--socket-send-buffer [4194304]`**
+
+  * UDP socket buffers in bytes. The kernel clamps them to `net.core.rmem_max` and
+    `net.core.wmem_max`; when that happens the server logs a warning at startup naming the
+    value it actually received.
+  * **Type:** `INTEGER in [65536 - 67108864]`
+  * **Environment Variables:** `TSSERVER_SOCKET_RECEIVE_BUFFER`, `TSSERVER_SOCKET_SEND_BUFFER`

README.md

@@ -19,6 +19,8 @@ Tried & tested for nearly 25 years, we have a solution that fits everyone's need
 
 **Limitations:** Please note that **TeamSpeak 3 Server licenses are not compatible** with TeamSpeak 6 Servers, and currently, there is **no migration path available between the two versions**.
 
+**Beta License:** The server includes a 32-slot Beta License that will be **renewed every two months** throughout the beta/evaluation period, until licensing and pricing are finalized.
+
 Additionally, it is **not yet possible to obtain or upgrade to a larger license for TeamSpeak 6**.
 
 We truly appreciate your patience and understanding as we continue to work on solutions to better support your needs in the future.
@@ -38,7 +40,7 @@ Don't want to self-host, or simply require an easier way to get started with Tea
 
 3. **YAML Configuration File:** For a persistent configuration, it is highly recommended to use a tsserver.yaml file. You can generate a default config file using the --write-config-file flag.
 
-Key settings you can control include network ports (voice, file transfer), database connections (supports SQLite and MariaDB), IP bindings, and logging options.
+Key settings you can control include network ports (voice, file transfer), database connections (supports SQLite and MariaDB), IP bindings, and logging options. A Prometheus metrics endpoint and ServerQuery guest access are available as well; both are covered in [CONFIG.md](CONFIG.md).
 
 For a complete list of available options, run the server with the `--help` flag or refer to the [CONFIG.md](CONFIG.md).
 
@@ -55,7 +57,7 @@ chmod +x tsserver
 Run the server from your terminal, making sure to accept the license:
 
 ```sh
-./tsserver --accept-license=accept
+./tsserver --accept-license
 ```
 
 <h2><img width="22" src="/icons/windows.svg">&nbsp;On Windows:</h2>
@@ -64,31 +66,57 @@ Open Command Prompt or PowerShell and navigate to the directory where you extrac
 
 Run the server executable, making sure to accept the license:
 ```powershell
-tsserver.exe --accept-license=accept
+tsserver.exe --accept-license
 ```
 
-<h2><img width="32" src="/icons/docker.svg">&nbsp;Running the Server with Docker (Recommended):</h2>
+<h2><img width="32" src="/icons/docker.svg" alt="Docker">&nbsp;Run the Server with Docker (Recommended)</h2>
-Docker is the easiest way to run the TeamSpeak 6 server in an isolated and manageable environment.
+<p>
+  The easiest way to run the TeamSpeak 6 Server is with 
+  <a href="https://docs.docker.com/engine/install/">Docker</a>.  
+  It provides an isolated, portable, and easily manageable environment, 
+  making setup and maintenance straightforward.
+</p>
 
 ### 1. Simple docker run command:
 
-For a quick start, you can use the docker run command. Make sure your licensekey.dat is in your current directory.
+For a quick start, you can use the docker run command.
 
 ```sh
-docker run -it --rm \
+# Running the TeamSpeak 6 Server container in detached mode using a docker volume
+docker run -d \
+  --name teamspeak-server \
   -p 9987:9987/udp \
   -p 30033:30033 \
   -e TSSERVER_LICENSE_ACCEPTED=accept \
+  -v teamspeak-data:/var/tsserver/ \
   teamspeaksystems/teamspeak6-server:latest
+
+# Check server logs (e.g. ServerAdmin privilege key)
+docker logs -f teamspeak-server
+
+# Manage the container
+docker stop teamspeak-server    # Stop the server
+docker start teamspeak-server   # Start it again
+docker restart teamspeak-server # Restart in one step
+
+# Clean up
+docker rm -f teamspeak-server   # Remove the container (data is kept in the volume)
+docker volume rm teamspeak-data # Remove the data volume (permanently deletes all server data!)
+
 ```
 
-### 2. Using docker-compose.yaml (for persistent setups):
+### 2. Using docker-compose.yaml (for more persistent setups):
-This is the best practice for a server you intend to keep running. Create a docker-compose.yaml file:
+For a server you intend to keep running long-term, it’s recommended to use Docker Compose instead of docker run.
+
+Create a docker-compose.yaml file in your project directory.
+
+You can use the following minimal example, or explore the ready-made configurations in the `compose/`
+folder (e.g. example-compose-mariadb.yaml):
 
 ```yaml
 services:
   teamspeak:
-    image: teamspeaksystems/teamspeak6-server:v6.0.0-beta2
+    image: teamspeaksystems/teamspeak6-server:latest
     container_name: teamspeak-server
     restart: unless-stopped
     ports:
@@ -98,11 +126,30 @@ services:
     environment:
       - TSSERVER_LICENSE_ACCEPTED=accept
     volumes:
-      - teamspeak-data:/var/tsserver/
+      - teamspeak-data:/var/tsserver
 
 volumes:
   teamspeak-data:
+    name: teamspeak-data
 ```
+Common Docker Compose Commands: 
+```sh
+# Running the server in detached mode using the example compose file
+docker compose -f example-compose-sqlite.yaml up -d
+
+# Check server logs (e.g. ServerAdmin privilege key)
+docker compose -f example-compose-sqlite.yaml logs -f
+
+# Manage the compose
+docker compose -f example-compose-sqlite.yaml stop     # Stop the server
+docker compose -f example-compose-sqlite.yaml start    # Start it again
+docker compose -f example-compose-sqlite.yaml restart  # Restart in one step
+
+# Clean up
+docker compose -f example-compose-sqlite.yaml down     # Remove the container (data is kept in the volume)
+docker volume rm teamspeak-data                        # Remove the data volume (permanently deletes all server data!)
+```
+
 
 ## 🔗 Useful Links
 [Official Website](https://teamspeak.com/en/)<br>

compose/example-compose-mariadb.yaml

@@ -8,6 +8,7 @@ services:
       - "30033:30033/tcp" # File transfer port
       # - "10080:10080/tcp" # WebQuery port
       # - "10022:10022/tcp" # SSHQuery port
+      # - "9187:9187/tcp"   # Prometheus metrics endpoint
     environment:
       - TSSERVER_LICENSE_ACCEPTED=accept
       - TSSERVER_DEFAULT_PORT=9987
@@ -16,6 +17,8 @@ services:
       - TSSERVER_FILE_TRANSFER_IP=0.0.0.0
       # - TSSERVER_QUERY_HTTP_ENABLED=true
       # - TSSERVER_QUERY_SSH_ENABLED=true
+      # - TSSERVER_METRICS_ENABLED=true
+      # - TSSERVER_METRICS_IP=0.0.0.0
 
       # Database settings
       - TSSERVER_DATABASE_PLUGIN=mariadb
@@ -26,7 +29,7 @@ services:
       - TSSERVER_DATABASE_USERNAME=teamspeak
       - TSSERVER_DATABASE_PASSWORD=YourPasswordHere
     volumes:
-      - tsserver-data:/var/tsserver
+      - teamspeak-data:/var/tsserver
     depends_on:
       mariadb:
         condition: service_healthy
@@ -50,7 +53,7 @@ services:
       retries: 3
 
 volumes:
-  tsserver-data:
+  teamspeak-data:
-    name: tsserver-data
+    name: teamspeak-data
   mariadb-data:
     name: mariadb-data

compose/example-compose-sqlite.yaml

@@ -8,6 +8,7 @@ services:
       - "30033:30033/tcp"  # File transfer port
       # - "10022:10022/tcp" # (Optional) ServerQuery SSH port
       # - "10080:10080/tcp"  # (Optional) WebQuery port
+      # - "9187:9187/tcp"    # (Optional) Prometheus metrics endpoint
     environment:
       - TSSERVER_LICENSE_ACCEPTED=accept
       - TSSERVER_DEFAULT_PORT=9987
@@ -19,9 +20,11 @@ services:
       # - TSSERVER_MACHINE_ID=my_unique_machine_id
       # - TSSERVER_LOG_PATH=/var/tsserver/logs
       # - TSSERVER_QUERY_ADMIN_PASSWORD=secretpassword
+      # - TSSERVER_METRICS_ENABLED=true
+      # - TSSERVER_METRICS_IP=0.0.0.0
     volumes:
-      - tsserver-data:/var/tsserver
+      - teamspeak-data:/var/tsserver
 
 volumes:
-  tsserver-data:
+  teamspeak-data:
-    name: tsserver-data
+    name: teamspeak-data