Home | Documentation | Download

eturnal Documentation

Copyright © 2020-2023 ProcessOne, SARL

Version: 1.12.0 (Sep 28 2023)

Authors: Holger Weiss.

eturnal is a STUN and TURN server, which supports the authentication mechanism described in the REST API for Access to TURN Services specification. The idea is that WebRTC (or other) clients receive temporary TURN credentials where the user name is comprised of the (Unix) expiry timestamp and the password is derived from a secret shared between the service generating those credentials and eturnal. The service offering the credentials performs a Base64(HMAC-SHA1($secret, $timestamp)) operation to generate the ephemeral password, and eturnal does the same to verify it. As an alternative, static credentials may be configured as well.

The README.md file shipped with eturnal should get you started quickly. For details, see the reference documentation below.

Deployment

Docker images are available on GitHub. Linux/x64 and Linux/arm64 packages for DEB- and RPM-based distributions can be retrieved from eturnal.net. On other Linux/x64 and Linux/arm64 systems, the binary release can be installed as described below. For building eturnal from source, see the INSTALL.md file shipped with eturnal's source code archive.

Installation

The binary release is installed using the following command line:

curl -fsS https://eturnal.net/install | sudo sh

The installer extracts the release archive into /opt/eturnal and creates a system user called eturnal. An example configuration is installed as /etc/eturnal.yml if that file doesn't exist yet. On systemd-managed systems, a service unit is created and eturnal is started.

Upgrade

The above installation command can also be used to upgrade eturnal from an earlier version. In that case, the service must be restarted afterwards. On systemd-managed systems:

sudo systemctl restart eturnal

Removal

For uninstalling eturnal and removing the configuration, run the following commands:

curl -fsS https://eturnal.net/uninstall | sudo sh
sudo rm /etc/eturnal.yml

Global Configuration

The eturnal server is configured by editing the eturnal.yml file (and optionally setting one or more Environment Variables). If /etc/eturnal.yml doesn't exist, eturnal will (by default) search for etc/eturnal.yml within the installation directory. In order to use a different path, the environment variable ETURNAL_ETC_DIR can be specified. As an alternative, the arguments -conf file '"/path/to/eturnal.yml"' (note the double quoting) can be appended to the eturnalctl command line used for starting up eturnal.

The eturnal.yml file uses the YAML format. YAML is indentation-sensitive, so care must be taken to indent the configuration correctly. The options documented below are to be placed within the eturnal section of the configuration file. (This section will usually be the only one in that file, but the eturnal.yml file could also be used to adjust the behavior of the underlying virtual machine by adding other sections.)

The eturnal server recognizes the following global configuration options. Module Configuration options are described below.

blacklist_clients

The blacklist_clients option specifies a list of one or more IPv4 and/or IPv6 addresses and/or CIDR blocks. TURN relaying from any of the listed addresses is refused, unless the address is also matched by a whitelist_clients entry. Note that 0.0.0.0/8, ::/128, 2001::/32, and 2002::/16 are always blocked and cannot be whitelisted.

Example:

blacklist_clients:
  - "192.0.2.2"
  - "203.0.113.0/24"
  - "2001:db8::/32"

blacklist_peers

The blacklist_peers option specifies a list of one or more IPv4 and/or IPv6 addresses and/or CIDR blocks. TURN relaying to any of the listed addresses is refused, unless the address is also matched by a whitelist_peers entry. The list may also contain the special keyword recommended, which expands to the addresses suggested by Enable Security. Note that 0.0.0.0/8, ::/128, 2001::/32, and 2002::/16 are always blocked and cannot be whitelisted.

Example:

blacklist_peers:
  - recommended
  - "192.0.2.2"
  - "203.0.113.0/24"
  - "2001:db8::/32"

credentials

Static (non-ephemeral) credentials may be configured instead of (or in addition to) shared secrets by adding them to the credentials map, where each user name is specified as the key and the corresponding password is specified as the value.

Example:

credentials:
  alice: l0vesBob
  bob: l0vesAlice
  eve: stalksTh3m

listen

The listen option specifies a list of one or more sockets the eturnal server listens on. Each listen entry holds one or more of the following key-value pairs:

• ip: address
  The ip address must be a string denoting the IPv4 or IPv6 address (note that IPv6 addresses with leading "::" must be enclosed with quotation marks). Specifying "0.0.0.0" tells eturnal to listen on all IPv4 interfaces. Specifying "::" tells eturnal to listen on all IPv6 interfaces, and possibly also all IPv4 interfaces, depending on the operating system (configuration). The default value is "::".
• port: number
  The port number must be between 0 and 65535, and is usually between 1024 and 49151. The default value is 5349 if the transport is set to tls, otherwise 3478.
• transport: protocol
  The transport protocol must be one of udp, tcp, tls, or, in order to accept unencrypted TCP and TLS connections on the same port, auto. The default value is udp.
• proxy_protocol: flag
  If the proxy_protocol flag is set to true, the client IP address/port is retrieved from the HAproxy protocol header. This is not supported if the transport is udp. The default value is false.
• enable_turn: flag
  The enable_turn flag must be true to enable TURN in addition to STUN, or false to offer just STUN on this socket. The default value is true.

Example:

listen:
  -
    ip: "::"           # This is the default.
    port: 3478         # This is the default for "transport: udp".
    transport: udp     # This is the default.
    enable_turn: true  # This is the default.
  -
    ip: "::"           # This is the default.
    port: 3478         # This is the default for "transport: auto".
    transport: auto    # Default: "udp".
    enable_turn: true  # This is the default.
  -
    ip: "::"           # This is the default.
    port: 5349         # This is the default for "transport: tls".
    transport: tls     # Default: "udp".
    enable_turn: true  # This is the default.

log_dir

This option specifies the directory the eturnal.log file is written into. Alternatively, this option can be set to the special value stdout, which configures eturnal to print log messages to the standard output rather than logging to a file. If this option isn't defined, the value of the envionment variable LOGS_DIRECTORY is used instead. If this environment variable is unset as well, a log directory is created within the installation prefix.

log_level

The value of this option determines the amount of output that is logged. Valid log levels are, ordered from least to most amount of output: critical, error, warning, notice, info, and debug.

log_rotate_count

The value of this option determines the number of rotated log file archives to keep if the log_rotate_size option is set to a positive integer value and the log_dir option isn't set to stdout. Otherwise, this option is ignored.

log_rotate_size

If this option is set to a positive integer value and the log_dir option isn't set to stdout, internal log rotation is enabled. The value of this option specifies the log file size limit in bytes. If this limit is exceeded, the log file is rotated. If this option isn't specified (or set to unlimited), external log rotation tools can be used.

Note: External rotation is detected automatically, so there's no need to notify eturnal (e.g., by sending a HUP signal) after log rotation.

max_bps

This option limits the bandwidth of TCP and TLS connections to the specified number of bytes per second. If the option isn't specified (or set to unlimited), the bandwith is not limited by eturnal.

max_permissions

This option specifies the maximum number of TURN permissions that may be created for a given allocation. If it's set to unlimited, an arbitrary number of permissions can be created for each allocation.

modules

Modules are enabled by adding them to the modules map, where each module name is specified as the key and the value defines the module's configuration. See the Module Configuration section for the available modules and their configuration options.

Example:

modules:
  mod_log_stun: {}
  mod_stats_prometheus: {}
  mod_stats_influx:
    host: localhost
    port: 8089

realm

This option defines the realm. A realm is required for authentication as per the STUN/TURN protocols, but with shared secret authentication, the actual value of the realm is meaningless. Therefore, this option can usually be left unspecified.

relay_ipv4_addr

This option specifies the IPv4 address used for relaying data from/to TURN peers. Note that this must be the server's public IPv4 address; i.e., it cannot be set to, for example, "0.0.0.0". If this option isn't specified, the value of the envionment variable ETURNAL_RELAY_IPV4_ADDR is used instead. If this environment variable is unset as well, eturnal will try to autodetect the system's IPv4 address. If this fails, eturnal won't offer TURN relaying from/to IPv4 peers.

relay_ipv6_addr

This option specifies the IPv6 address used for relaying data from/to TURN peers. Note that this must be the server's public IPv6 address; i.e., it cannot be set to, for example, "::". If this option isn't specified, the value of the envionment variable ETURNAL_RELAY_IPV6_ADDR is used instead. If this environment variable is unset as well, eturnal will try to autodetect the system's IPv6 address. If this fails, eturnal won't offer TURN relaying from/to IPv6 peers.

relay_max_port

This option defines the upper bound of the UDP port range to be used for TURN relaying. The value should usually be (well) above 49152. If this option isn't specified, the value of the envionment variable ETURNAL_RELAY_MAX_PORT is used instead.

Note that each TURN relay allocation requires a dedicated port, and that several TURN relays might be allocated for a single, e.g., audio/video call. Therefore, make sure to keep the port range large enough.

relay_min_port

This option defines the lower bound of the UDP port range to be used for TURN relaying. The value should usually be above 49151 and (well) below the relay_max_port number. If this option isn't specified, the value of the envionment variable ETURNAL_RELAY_MIN_PORT is used instead.

run_dir

This option specifies the directory eturnal will use for storing runtime data. If this option isn't defined, the value of the envionment variable RUNTIME_DIRECTORY is used instead. If this environment variable is unset as well, a run directory is created within the installation prefix.

secret

This option defines the shared authentication secret used to derive the passwords for ephemeral TURN user names as described in the REST API for Access to TURN Services specification. If this option isn't defined, the value of the environment variable ETURNAL_SECRET is used instead. If this environment variable is unset as well, a pseudorandom secret (which is not cryptographically secure) is used. If a list of secrets is specified, credentials derived from any of those will be accepted. This allows for rotating the secret without invalidating existing credentials.

software_name

This option specifies the server software name announced to clients during the STUN/TURN communication.

strict_expiry

If the strict_expiry option is set to false, the expiry timestamp of ephemeral credentials is only checked during TURN session creation. Once credentials are accepted, clients may continue to use them for refreshing the existing session beyond the credential expiry time (as long as the configured shared secret remains unchanged). If the strict_expiry option is set to true, expired credentials won't be accepted for refreshing TURN sessions. The default value is false.

tls_ciphers

This option can be used to specify a cipher list to be handed over to OpenSSL for TLS connections. See the openssl-ciphers manual for a list of permitted cipher strings and their meanings. The ciphers are either specified as a list or joined into a string using a : character as separator.

tls_crt_file

This option specifies the path to the PEM file containing the certificate (chain) offered while negotiating TLS connections. The PEM file must be readable by the user running the eturnal server. The file may also contain the private key, in which case the tls_key_file option can be left unspecified.

If the tls_crt_file option isn't specified but TLS is enabled for one or more listen entries, eturnal will attempt to create a self-signed certificate during startup. If TLS is to be used for security reasons (rather than just for circumventing restrictive packet filters), clients may well refuse to accept such a certificate. Therefore, it's strongly recommended to specify this option if TLS is enabled.

tls_dh_file

The tls_dh_file option specifies the path to a PEM file holding DH parameters to be used instead of the default DH parameters. The file could be created using a command such as openssl dhparam -out dh-parameters.pem 4096.

tls_key_file

This option specifies the path to the PEM file containing the private key used while negotiating TLS connections. The PEM file must be readable by the user running the eturnal server.

If a tls_crt_file but no tls_key_file is specified, it is assumed that the tls_crt_file contains both the certificate chain and the private key.

tls_options

This setting can be used to specify options to be handed over to OpenSSL for TLS connections. See the SSL_CTX_set_options manual for details on the available options. They are specified in lower case and without SSL_OP_ prefix, either as a list or combined into a string using a | character as separator.

Example:

tls_options:
  - no_tlsv1
  - no_tlsv1_1
  - cipher_server_preference

whitelist_clients

The whitelist_clients option specifies a list of one or more IPv4 and/or IPv6 addresses and/or CIDR blocks. TURN relaying from any of the listed addresses is permitted even if the address would otherwise be rejected due to being matched by a blacklist_clients entry.

whitelist_clients:
  - "203.0.113.113"
  - "203.0.113.0/26"
  - "2001:db8::/64"

whitelist_peers

The whitelist_peers option specifies a list of one or more IPv4 and/or IPv6 addresses and/or CIDR blocks. TURN relaying to any of the listed addresses is permitted even if the address would otherwise be rejected due to being matched by a blacklist_peers entry.

whitelist_peers:
  - "203.0.113.113"
  - "203.0.113.0/26"
  - "2001:db8::/64"

Module Configuration

The eturnal server ships the following modules, which can be configured as described in this section.

mod_log_stun

This module enables logging of STUN queries. Without this module, STUN requests only show up in the debug output.

level

The value of this option determines the level used for logging STUN requests. Valid log levels are critical, error, warning, notice, info, and debug.

mod_stats_influx

This module logs STUN/TURN events/statistics into InfluxDB. It requires an InfluxDB database (created with an arbitrary name) to be accessible via UDP, and has the following configuration options:

host

This option specifies the host name or IP address InfluxDB's UDP service is listening on.

port

This option specifies the port number InfluxDB's UDP service is listening on.

mod_stats_prometheus

This module exposes various STUN/TURN and (by default) virtual machine metrics to Prometheus via HTTP under the /metrics endpoint.

ip

This option specifies the IPv4 or IPv6 address the module is listening on (note that IPv6 addresses with leading "::" must be enclosed with quotation marks). The default value is any, which configures the module to listen on all available interfaces.

port

This option specifies the port number the module is listening on. The default value is 8081.

tls

If this option is set to true, the module accepts only TLS-encrypted HTTPS connections. The default value is false, which configures the module to use unencrypted HTTP connections instead.

tls_crt_file

This option specifies the path to the PEM file containing the certificate (chain) offered while negotiating HTTPS connections. The PEM file must be readable by the user running the eturnal server. The file may also contain the private key, in which case the tls_key_file option can be left unspecified.

If this option isn't specified but tls is enabled, the module will fall back to using the global tls_crt_file setting. If that doesn't point to a PEM file either, eturnal will attempt to create a self-signed certificate during startup. However, it's strongly recommended to specify this option if TLS is enabled.

tls_key_file

This option specifies the path to the PEM file containing the private key used while negotiating HTTPS connections. The PEM file must be readable by the user running the eturnal server. If this option isn't specified but tls is enabled, the module will fall back to using the global tls_key_file setting.

If a tls_crt_file but no tls_key_file is specified, it is assumed that the tls_crt_file contains both the certificate chain and the private key.

vm_metrics

If this option is set to false, omit metrics describing the state of the underlying virtual machine. The default value is true, which tells the module to include those metrics.

Environment Variables

The eturnal server recognizes the following environment variables.

ERL_DIST_PORT

The environment variable ERL_DIST_PORT specifies the TCP port number used by the eturnalctl command for communicating with eturnal. By default, a random port is chosen. If this variable is specified, the Erlang Port Mapper Daemon (EPMD) service is not spawned during eturnal startup, and the ERL_EPMD_ADDRESS and ERL_EPMD_PORT variables are ignored. ERL_DIST_PORT must be set to the same port number during eturnal startup and when calling eturnalctl. Therefore, it's usually most convenient to specify the dist_port variable at the top of the eturnalctl script itself. This feature requires at least Erlang/OTP 23.1 and Rebar3 3.18.0.

ERL_EPMD_ADDRESS

On eturnal startup, an Erlang Port Mapper Daemon (EPMD) service is spawned (if it's not running already, and ERL_DIST_PORT isn't specified). By default, eturnal lets EPMD listen on localhost. Setting the ERL_EPMD_ADDRESS environment variable tells EPMD to listen on the specified comma-seperated list of IP addresses instead. Note that the IPv4 and IPv6 loopback addresses are implicitly added to this list if not specified. Setting ERL_EPMD_ADDRESS to an empty value lets EPMD listen on all interfaces.

ERL_EPMD_PORT

Setting this environment variable tells EPMD to listen on the specified port. By default, EPMD listens on port 4369. ERL_EPMD_PORT must be set to the same port number during eturnal startup and when calling eturnalctl.

ETURNAL_ETC_DIR

This environment variable specifies the directory containing the eturnal.yml configuration file. If, for example, ETURNAL_ETC_DIR is set to /usr/local/etc, the file /usr/local/etc/eturnal.yml will be used.

ETURNAL_RELAY_IPV4_ADDR

If the relay_ipv4_addr option isn't specified, this environment variable defines the IPv4 address used for relaying data from/to TURN peers.

ETURNAL_RELAY_IPV6_ADDR

If the relay_ipv6_addr option isn't specified, this environment variable defines the IPv6 address used for relaying data from/to TURN peers.

ETURNAL_RELAY_MAX_PORT

If the relay_max_port option isn't specified, this environment variable defines the upper bound of the UDP port range to be used for TURN relaying. The value should usually be (well) above 49152.

ETURNAL_RELAY_MIN_PORT

If the relay_min_port option isn't specified, this environment variable defines the lower bound of the UDP port range to be used for TURN relaying. The value should usually be above 49151 and (well) below the ETURNAL_RELAY_MAX_PORT number.

ETURNAL_SECRET

If the secret option isn't specified, this environment variable defines the shared authentication secret used to derive the passwords for ephemeral TURN user names as described in the REST API for Access to TURN Services specification.

LOGS_DIRECTORY

If the log_dir option isn't specified, this environment variable defines the directory the eturnal.log file is written into. Note that systemd 235 and higher set this environment variable if systemd's [Service] option LogsDirectory is specified.

RUNTIME_DIRECTORY

If the run_dir option isn't specified, this environment variable defines the directory eturnal will use for storing runtime data. Note that systemd 235 and higher set this environment variable if systemd's [Service] option RuntimeDirectory is specified.

Operation

The eturnal server is controlled using the eturnalctl command. This command can be called by the superuser and by the user running the eturnal server. It can also be called by other users after copying the ~eturnal/.erlang.cookie file (where eturnal is the user running eturnal) into their $HOME directory and fixing the ownership/permissions of the copy.

See the following list for a subset of the available eturnalctl commands:

• eturnalctl daemon
  Start eturnal in the background.
• eturnalctl foreground
  Start eturnal in the foreground.
• eturnalctl console
  Start eturnal in the foreground with an interactive Erlang shell.
• eturnalctl remote_console
  Connect to the running eturnal instance with an interactive Erlang shell.
• eturnalctl eval code
  Let the running eturnal VM evaluate the specified Erlang code.
• eturnalctl reload
  Reload the configuration file.
• eturnalctl info
  Print some details regarding the running eturnal instance.
• eturnalctl sessions
  Print the list of currently active TURN sessions.
• eturnalctl sessions username
  Print the list of currently active TURN sessions belonging to the given username. If TURN credentials of the form $timestamp:$suffix are used, just the $suffix may be specified as username, in which case all sessions with that $suffix are listed.
• eturnalctl disconnect username
  Close any TURN session(s) belonging to the given username. If TURN credentials of the form $timestamp:$suffix are used, just the $suffix may be specified as username, in which case all sessions with that $suffix are disconnected.
• eturnalctl credentials
  Print credentials valid for 24 hours, derived from the (first) configured secret.
• eturnalctl credentials expiry[s|m|h|d] [suffix]
  Print credentials valid for the given expiry period, derived from the (first) configured secret. An m, h, or d unit can be appended in order to specify the expiry period in minutes, hours, or days, respectively. The default unit is seconds. Alternatively, the expiry time can be specified as an RFC 3339 timestamp. If a suffix is specified, it is appended to the generated user name, separated from the expiration timestamp with a colon.
• eturnalctl password username
  Print the password for the given username, derived from the (first) configured secret.
• eturnalctl loglevel
  Print the log_level of the running eturnal instance.
• eturnalctl loglevel level
  Set the log_level of the running eturnal instance to level.
• eturnalctl version
  Print the release version of the running eturnal instance.
• eturnalctl stop
  Stop the running eturnal instance.

Home | Documentation | Download