From 27179a3159846ddccfee55b2c43d8f9d48713351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Wala?= Date: Tue, 22 Aug 2023 10:18:56 +0200 Subject: [PATCH] Refactor configuration documentation --- README.md | 81 ++++++++---------------------------------------------- sample.env | 53 +++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 70 deletions(-) create mode 100644 sample.env diff --git a/README.md b/README.md index 16c7c7a..a972ee1 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ TURN server in pure Elixir. Aims to implement: -- [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766) -- [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156#autoid-7) +- RFC 5389: [Session Traversal Utilities for NAT (STUN)](https://datatracker.ietf.org/doc/html/rfc5389) +- RFC 5766: [Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN)](https://datatracker.ietf.org/doc/html/rfc5766) +- RFC 6156: [Traversal Using Relays around NAT (TURN) Extension for IPv6](https://datatracker.ietf.org/doc/html/rfc6156#autoid-7) This project is in early stage of development and some of the features described in the RFCs might be missing. Expect breaking changes. @@ -43,7 +44,7 @@ pc = new RTCPeerConnection({ }); ``` -## Installation +## Installation and running 1. From source @@ -57,77 +58,17 @@ mix run --no-halt 2. In Docker ```console -docker run ghcr.io/elixir-webrtc/rel:latest +docker run --network=host ghcr.io/elixir-webrtc/rel:latest ``` ## Features and configuration -Currently, Rel is configured via environment variables. +Rel exposes Prometheus metrics endpoint (by default `http://127.0.0.1:9568/metrics`). -### TURN server +Rel supports authentication described in [A REST API For Access To TURN Services](https://datatracker.ietf.org/doc/html/draft-uberti-rtcweb-turn-rest-00#section-2.2). +By default available under `http://127.0.0.1:4000/`. Example request would be `POST http://127.0.0.1:4000/&service=turn&username=johnsmith`. +Key query parameter currently is not supported. -Rel by default listens on `0.0.0.0:3478/UDP` for TURN traffic. This can be configured via `LISTEN_IP` and `LISTEN_PORT`. - -```console -LISTEN_IP=0.0.0.0 -LISTEN_PORT=3478 -``` - -`EXTERNAL_LISTEN_IP` is the IP address at which Rel is visible to clients. By default, Rel will try to guess the address -based on active network interfaces, but this must be set explicitly when e.g. using Docker without `--network host`. - -```console -EXTERNAL_LISTEN_IP=167.235.241.140 -``` - -By default, Rel will use the same addresses (`RELAY_IP == LISTEN_IP and EXTERNAL_RELAY_IP == EXTERNAL_LISTEN_IP`) to open allocations, but this -can be set to something else: - -```console -RELAY_IP=0.0.0.0 -EXTERNAL_RELAY_IP=167.235.241.140 -``` - -Rel will try to open relay addresses in `49_152 - 65_535` port range, but this can be changed. `RELAY_PORT_END` must be greater than `RELAY_PORT_START`. - -```console -RELAY_PORT_START=35000 -RELAY_PORT_END=45000 -``` - -Remember to use the `REALM` variable specific to your deployment. It's used in `REALM` STUN attributes. See -[this section of RFC 2617](https://datatracker.ietf.org/doc/html/rfc2617#section-3.2.1) to learn about appropriate values for `REALM` attribute. - -```console -REALM=my-amazing-turn.com -``` - -You can configure the number of running `listener` processes. By default, it is equal to number of running Erlang VM schedulers: - -```console -LISTENER_COUNT=8 -``` - -### Auth - -Auth Provider is an HTTP endpoint that provides credentials required by *A REST API For Access To TURN Services*. -By default it is available at `http://127.0.0.1:4000/`, but the address, encryption and CORS can be configured: - -```console -AUTH_IP=127.0.0.1 -AUTH_PORT=4000 -AUTH_USE_TLS=false -AUTH_KEYFILE=./rel.key -AUTH_CERTFILE./rel.cert -AUTH_ALLOW_CORS=false -``` - -### Metrics - -By default, Rel provides Prometheus metrics at `http://127.0.0.1:9578/metrics`. The address can be configured: - -```console -METRICS_IP=127.0.0.1 -METRICS_PORT=9568 -``` +credentials endpoint described in [Public deployment](#public-deployment) section (by default `http://127.0.0.1:4000/`). +Rel is configured via environment variables. All of the possible options are described in [sample env file](./sample.env). diff --git a/sample.env b/sample.env new file mode 100644 index 0000000..8a0b338 --- /dev/null +++ b/sample.env @@ -0,0 +1,53 @@ +# Rel config env variables + +# Values presented in this example file are used by default +# except where explicitly specified otherwise + +## TURN + +# Server address and port on which Rel listens for TURN/STUN requests +LISTEN_IP=0.0.0.0 +LISTEN_PORT=3478 + +# Server address as seen from the client +# By default it is equal to LISTEN_PORT or (if LISTEN_PORT == 0.0.0.0) Rel +# will try to guess the address based on host's network interfaces +# It must be explicitly set when e.g. running in Docker without `--network=host` +# EXTERNAL_LISTEN_IP=167.235.241.140 + +# Address and port range where relay address will be allocated +RELAY_IP=0.0.0.0 +RELAY_PORT_START=49152 +RELAY_PORT_END=65535 + +# Relay address as seen from peers +# Behave the same way as EXTERNAL_LISTEN_IP +# EXTERNAL_RELAY_IP=167.235.241.140 + +# Values used in REALM STUN attribute, see https://datatracker.ietf.org/doc/html/rfc5389#section-15.7 +REALM=example.com + +# Number of running listener processes. By default equal to number of running Erlang VM schedulers +# LISTENER_COUNT=8 + +## AUTH PROVIDER + +# Auth provider is available under http(s)://$AUTH_IP:$AUTH_PORT/ +AUTH_IP=127.0.0.1 +AUTH_PORT=4000 + +# whether to use HTTP or HTTPS +# If true, AUTH_KEYFILE and AUTH_CERFILE must be explicitly set +AUTH_USE_TLS=false +# AUTH_KEYFILE=./rel.key +# AUTH_CERTFILE=./rel.cert + +# Whether to allos Cross-Origin Resource Sharing +# May be useful when requesting credentials via JavaScript in the browser +AUTH_ALLOW_CORS=false + +## METRICS + +# Prometheus metrics are served on http://$METRICS_IP:$METRICS_PORT/metrics +METRICS_IP=127.0.0.1 +METRICS_PORT=9568