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

CONFIG.md

@@ -17,6 +17,7 @@ This document outlines the most commonly used command-line parameters and their
 | `--license-path <path>`       | `TSSERVER_LICENSE_PATH`        | Directory path where the server will look for the `licensekey.dat` file.                                                                              |
 | `--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`        | 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.           |
 
 ---
 
@@ -28,6 +29,23 @@ This document outlines the most commonly used command-line parameters and their
 
 ---
 
+#### 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                                                                           |
@@ -54,6 +72,41 @@ This document outlines the most commonly used command-line parameters and their
 | `--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
 
@@ -192,10 +245,10 @@ server:
   * **Type:** `STRING`
   * **Environment Variable:** `TSSERVER_MACHINE_ID`
 
-* **`--threads-voice-udp [5]`**
+* **`--threads-voice-udp [16]`**
 
-  * Number of threads to use for voice processing.
-  * **Type:** `INTEGER in [1 - 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`
 
 ---
@@ -214,6 +267,13 @@ 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
@@ -243,6 +303,59 @@ server:
 
 ---
 
+#### 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`**
@@ -348,13 +461,13 @@ server:
 * **`--query-pool-size [2]`**
 
   * How many threads to use for query command processing.
-  * **Type:** `INTEGER in [2 - 32]`
+  * **Type:** `INTEGER in [1 - 32]`
   * **Environment Variable:** `TSSERVER_QUERY_POOL_SIZE`
 
-* **`--query-log-timing [3600]`**
+* **`--query-log-timing [0]`**
 
-  * Interval in seconds after which to log query statistics.
-  * **Type:** `INTEGER in [10 - 31556952]`
+  * Interval in seconds after which to log query statistics, `0` disables them.
+  * **Type:** `INTEGER in [0 - 31556952]`
   * **Environment Variable:** `TSSERVER_QUERY_LOG_TIMING`
 
 * **`--query-ip-allow-list [query_ip_allowlist.txt]`**
@@ -375,6 +488,13 @@ server:
   * **Type:** `STRING`
   * **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.
@@ -433,6 +553,14 @@ server:
   * **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
@@ -455,6 +583,14 @@ server:
   * **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
@@ -534,3 +670,64 @@ server:
   * 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,7 +19,7 @@ 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**.
 
-**Preview License:** In response to your feedback, the server now comes with a **temporary** 32-slot preview license to offer greater flexibility during the evaluation period. Please note that this license is **only valid for two months**.
+**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**.
 
@@ -40,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).
 
@@ -66,26 +66,52 @@ 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
+tsserver.exe --accept-license
 ```
 
-<h2><img width="32" src="/icons/docker.svg">&nbsp;Running the Server with Docker (Recommended):</h2>
-Docker is the easiest way to run the TeamSpeak 6 server in an isolated and manageable environment.
+<h2><img width="32" src="/icons/docker.svg" alt="Docker">&nbsp;Run the Server with Docker (Recommended)</h2>
+<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.
 
 ```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):
-This is the best practice for a server you intend to keep running. Create a docker-compose.yaml file:
+### 2. Using docker-compose.yaml (for more persistent setups):
+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:
@@ -100,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:
-    name: tsserver-data
+  teamspeak-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:
-    name: tsserver-data
+  teamspeak-data:
+    name: teamspeak-data