# Configuration

Backend server settings and the relay plugin's config.yml

Source: https://socketsvc.vercel.app/zh-TW/proxy/configuration
A proxied setup has two sides to configure: each backend's own SocketSVC config, and the relay plugin's `config.yml` on the proxy.

## Backend configuration

On every backend server's `plugins/SocketSVC/config.yml` (or `config/socketsvc-server.yml` for a server mod):

```yaml
bind-address: 127.0.0.1   # or a private address the proxy machine can reach
port: 24456                 # internal only; unique per backend if co-located
public-host: voice.example.com   # or public-url: wss://voice.example.com
```

- `bind-address`/`port` no longer need to be reachable by players directly — only the relay needs to reach them. If several backends run on the same machine, give each a unique port.
- `public-host`/`public-url` must point at the **relay's** public address, not the backend's own.

These are the same, already-existing fields described in [Server configuration](/server/configuration); nothing about the backend plugin or mod itself changes for proxy mode. Apply the change with `/ssvc-server reload` on each backend.

## Relay configuration

Drop `socketsvc-proxy-<version>.jar` into your proxy's `plugins/` folder — the same jar works whether that proxy is Velocity or BungeeCord/Waterfall. On first run it writes a default `config.yml` into its data folder. A filled-in example:

```yaml title="config.yml"
listen:
  bind-address: "0.0.0.0"
  port: 24455          # the ONE public port for the whole network

connect-timeout-ms: 5000

servers:
  survival: "127.0.0.1:24456"   # matches the proxy's own server name
  creative: "127.0.0.1:24457"   # -> that backend's internal voice address

server-list-advert: true   # badge this network in the multiplayer server list

metrics:
  enabled: true   # anonymous, aggregate usage only - never player identities or voice data
```

| Key | Default | Meaning |
| --- | --- | --- |
| `listen.bind-address` | `0.0.0.0` | Address the relay listens on |
| `listen.port` | `24455` | The one public WebSocket port for the whole network |
| `connect-timeout-ms` | `5000` | How long to wait when connecting to a backend's internal voice listener; must be positive |
| `servers` | empty | Proxy server name → that backend's internal `host:port` voice address |
| `server-list-advert` | `true` | Marks this network's status ping so a player running the client mod sees a voice-chat badge next to it in the multiplayer server list; see [Server list badge](#server-list-badge) |
| `metrics.enabled` | `true` | Anonymous, aggregate usage metrics (relay count, platform); never player identities or voice data |

<Callout type="warn" title="The default config has no servers">
  The generated `config.yml` only contains commented-out `servers` examples, and the relay refuses to start until at least one server is listed. Add your backends, then run `/ssvc-proxy reload` (or restart the proxy); check the proxy log if it still fails.
</Callout>

### Server names

The `servers` keys must match the server names already used in `velocity.toml` / BungeeCord's own `config.yml` (the same names players switch between with `/server`). Each value is the corresponding backend's internal `bind-address:port` from [Backend configuration](#backend-configuration), written as `"host:port"`.

### Server list badge

With `server-list-advert` on (the default), a player running the SocketSVC client mod sees a microphone badge beside this network's row in their multiplayer server list, in the margin to the left of it, before joining.

**The relay has to be the one to send it.** Players ping the proxy, and each backend's own voice listener is internal and never answers a server-list ping, so a backend's own `server-list-advert` does nothing on a proxied network.

The marker is an empty component appended to the MOTD carrying only a style `insertion`, which has no rendering of its own — a vanilla client sees exactly the MOTD it would have seen. It is advisory: an MOTD plugin that rebuilds the description from a plain string drops it and the badge simply does not appear; nothing else changes. `/ssvc-proxy reload` applies a change, and the mechanism is the same one described under [Server list badge](/server/configuration#server-list-badge) for a standalone server.

### Metrics

`metrics.enabled` uses the same [FastStats](https://faststats.dev) SDK, version and project token as the Paper server plugin's own metrics (`metrics.enabled` in the server's [config.yml](https://github.com/HippoDev03/SocketSVC/blob/main/server/paper/src/main/resources/config.yml)). Set it to `false` to opt out; it takes effect on the next proxy start, not on `/ssvc-proxy reload`.

### Firewall and TLS

Only the relay's `listen.port` needs to be open in your firewall — the per-backend voice ports stay internal. For `wss://`, put an external reverse proxy or tunnel in front of `listen.port` and set the backends' `public-url` to that `wss://` address; the relay itself only speaks plain `ws://`.

## Updates

The relay is the single public voice port for a whole network, so it **never replaces itself**: it reports, and an administrator installs with `/ssvc-proxy update confirm` (permission `socketsvc.proxy.admin.update`, falling back to operators).

```yaml
updates:
  enabled: true
  channel: release
  endpoint: ''         # blank uses the deploy SocketSVC ships with
  notify-admins: true  # tell holders of socketsvc.proxy.admin.update when they connect
```

`/ssvc-proxy update` checks and prints a confirmation panel, `confirm` downloads and verifies it, and `list` shows every build on the channel. The verified jar is staged under the plugin's data folder and swapped in as the proxy shuts down; `updates/apply.log` records what happened.