From a885fb6bc8c929d038312d3d13fbdd44b5cf6136 Mon Sep 17 00:00:00 2001 From: Michael Taylor Date: Tue, 21 Jul 2026 10:38:53 -0700 Subject: [PATCH] docs(run-a-relay): document relay operator config knobs (14 locales) Add a "Configuration and tuning" section to the run-a-relay page documenting every dig-relay tunable: network listeners, capacity/connection limits, the per-IP/per-connection abuse-protection limits, health-sweep/liveness knobs, and optional relay-side TLS. Each entry gives the CLI flag, the DIG_RELAY_* env var, the default, and what it does. Applied byte-identically to all 14 locales (English mirrors per repo convention). Values verified against dig-relay v0.12.0. Co-Authored-By: Claude --- docs/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ .../current/run-a-node/run-a-relay.md | 71 +++++++++++++++++++ package.json | 2 +- 15 files changed, 995 insertions(+), 1 deletion(-) diff --git a/docs/run-a-node/run-a-relay.md b/docs/run-a-node/run-a-relay.md index a1123b4..d1f35a0 100644 --- a/docs/run-a-node/run-a-relay.md +++ b/docs/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/de/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/de/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 0ff85f3..d1d70b2 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/es/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/es/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 26a3947..53d262d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/fr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 412fc80..21dac3f 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/hi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 71b4e3c..db58c05 100644 --- a/i18n/hi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/hi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/id/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/id/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 87935ee..0b297de 100644 --- a/i18n/id/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/id/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/ja/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 9cd4f7c..e127248 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/ko/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index bccd266..185e69d 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index ce187d3..ab6b48c 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/ru/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 5512291..dae3518 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/tr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 0ff0269..0fafef8 100644 --- a/i18n/tr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/tr/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/vi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 41dc904..bc0ca24 100644 --- a/i18n/vi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/vi/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index 561058d..43da852 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md b/i18n/zh-TW/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md index d3ed08a..1444dec 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/run-a-node/run-a-relay.md @@ -84,6 +84,77 @@ dig-relay status # is it serving? (probes the health endpoint) A relay is only useful if other nodes can reach it, so run it somewhere with a public address (a small cloud instance is plenty — a relay is lightweight) and allow inbound traffic on its relay port. Put it behind TLS (`wss://`) for production. ::: +## Configuration and tuning + +A relay runs well with **zero configuration** — the defaults are production-safe, and the [universal installer](./universal-installer.md) sets everything up for you. The settings below let you tune capacity, abuse protection, and connection hygiene for your own environment. + +Every setting can be given as a flag on `dig-relay serve` **or** as an environment variable (the installed service reads the environment). When both are set, the command-line flag wins. Restart the relay after changing a setting. + +```bash +# Example: a higher-capacity relay that also terminates its own TLS +dig-relay serve \ + --listen [::]:9450 \ + --max-connections 16384 \ + --tls-cert /etc/dig-relay/relay.crt \ + --tls-key /etc/dig-relay/relay.key +``` + +### Network listeners + +Where the relay binds each of its listeners. An IPv6 address (the default `[::]`) accepts both IPv6 and IPv4 connections. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--listen` | `DIG_RELAY_LISTEN` | `[::]:9450` | The relay connection listener — the port your nodes connect to. | +| `--health-listen` | `DIG_RELAY_HEALTH_LISTEN` | `[::]:9451` | The HTTP health-check endpoint (used by `dig-relay status` and monitoring). | +| `--dashboard-listen` | `DIG_RELAY_DASHBOARD_LISTEN` | `[::]:80` | The HTTP peer-stats dashboard. | +| `--stun-listen` | `DIG_RELAY_STUN_LISTEN` | `[::]:3478` | The STUN (UDP) listener that helps nodes discover their public address for hole punching. | + +### Capacity and connection limits + +Overall size and per-connection bounds. Raise these for a busy relay with room to spare. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections` | `DIG_RELAY_MAX_CONNECTIONS` | `4096` | Maximum concurrent connections the relay accepts. | +| `--idle-timeout-secs` | *(flag only)* | `120` | Seconds of silence before an idle connection is closed. This is the long backstop behind the faster health sweep below. | +| `--register-timeout-secs` | `DIG_RELAY_REGISTER_TIMEOUT_SECS` | `10` | Seconds a freshly-accepted connection has to register before it is dropped. | +| `--max-message-bytes` | `DIG_RELAY_MAX_MESSAGE_BYTES` | `262144` | Largest single inbound message accepted (256 KiB). | +| `--outbound-queue-capacity` | `DIG_RELAY_OUTBOUND_QUEUE_CAPACITY` | `1024` | Per-connection outbound queue depth. A reader slower than this has messages dropped rather than stalling the relay. | + +### Abuse-protection limits + +These bound what a single source can consume, so one busy or misbehaving host can't monopolise or overwhelm a shared relay. **Set any of them to `0` to disable that specific limit.** + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--max-connections-per-ip` | `DIG_RELAY_MAX_CONNECTIONS_PER_IP` | `64` | Maximum concurrent connections from one source IP. Must not exceed `--max-connections`. | +| `--registrations-per-ip-per-sec` | `DIG_RELAY_REGISTRATIONS_PER_IP_PER_SEC` | `10` | Registration attempts per second allowed from one source IP. | +| `--max-registrations-per-ip` | `DIG_RELAY_MAX_REGISTRATIONS_PER_IP` | `128` | Maximum concurrent registrations from one source IP. | +| `--messages-per-conn-per-sec` | `DIG_RELAY_MESSAGES_PER_CONN_PER_SEC` | `256` | Inbound messages per second per connection before it is disconnected. | +| `--bytes-per-conn-per-sec` | `DIG_RELAY_BYTES_PER_CONN_PER_SEC` | `1048576` | Inbound bytes per second per connection before it is disconnected (1 MiB/s). | +| `--max-relayed-bytes-per-conn` | `DIG_RELAY_MAX_RELAYED_BYTES_PER_CONN` | `1073741824` | Total inbound bytes one connection may relay over its lifetime before it is disconnected (1 GiB). | +| `--stun-per-ip-rps` | `DIG_RELAY_STUN_PER_IP_RPS` | `5` | STUN responses per second to one source IP. | +| `--stun-global-rps` | `DIG_RELAY_STUN_GLOBAL_RPS` | `1000` | STUN responses per second across all sources. | + +### Connection health and pruning + +The relay actively removes dead or silent connections so they stop being handed out to other nodes, instead of waiting for the much longer idle timeout to reap them. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--health-check-interval-secs` | `DIG_RELAY_HEALTH_CHECK_INTERVAL_SECS` | `30` | How often the relay sweeps for and removes dead or silent connections. Must be less than or equal to the liveness deadline. | +| `--liveness-deadline-secs` | `DIG_RELAY_LIVENESS_DEADLINE_SECS` | `90` | Seconds without any inbound message before the sweep prunes a connection. Must be shorter than the idle timeout. | + +### Terminate TLS at the relay (optional) + +By default the relay speaks plain `ws://` and expects TLS to be terminated in front of it — for example at a load balancer, which is how the public `relay.dig.net` is run. Set **both** of the settings below to have the relay terminate TLS itself and require every connecting client to present a certificate. + +| Flag | Environment variable | Default | What it does | +|---|---|---|---| +| `--tls-cert` | `DIG_RELAY_TLS_CERT_PATH` | *(none)* | Path to the relay's TLS certificate (PEM). Set together with `--tls-key`. | +| `--tls-key` | `DIG_RELAY_TLS_KEY_PATH` | *(none)* | Path to the relay's TLS private key (PEM). Set together with `--tls-cert`. | + ## Related - [Configure a node](./configure.md) — all node settings, including the relay diff --git a/package.json b/package.json index c9ddecb..0f68e7a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs-dig-net", - "version": "0.5.1", + "version": "0.5.2", "private": true, "scripts": { "docusaurus": "docusaurus",