eturnal Documentation

Copyright © 2020–2022 ProcessOne, SARL.

Version: 1.10.1 (Aug 2 2022)
Authors: Holger Weiß

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.

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

Installation

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 in this section. For building eturnal from source, see the INSTALL.md file shipped with eturnal's source code archive.

The binary release is installed using the following commands (on AArch64 systems, x64 must be replaced with arm64):

curl -O https://eturnal.net/eturnal-1.10.1-linux-x64.run
chmod +x eturnal-1.10.1-linux-x64.run
sudo ./eturnal-1.10.1-linux-x64.run

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.

If the above commands were used to upgrade eturnal from an earlier version, the service must be restarted afterwards. On systemd-managed systems:

sudo systemctl restart eturnal

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

sudo systemctl --now disable eturnal
sudo rm -rf /opt/eturnal
sudo rm /etc/systemd/system/eturnal.service
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_PREFIX 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

Type: list of IP addresses/CIDRs | default | recommended
Default: Loopback addresses

The blacklist option specifies a list of one or more IPv4 and/or IPv6 addresses and/or CIDR blocks. TURN relaying from or to any of the listed addresses is refused, unless the address is also matched by a whitelist entry. The blacklist may also contain the special keyword default, which expands to the addresses blocked by default, or the special keyword recommended, which expands to the addresses suggested by Enable Security. (As the latter is a superset of the former, there's no point in listing both.) Note that the recommended addresses include private networks. Therefore, if eturnal is supposed to serve clients within a local, private network, that network must be exempted from the recommended addresses by adding it to the whitelist.

Example:

blacklist:
  - "::1"
  - "127.0.0.0/8"
  - "192.0.2.0/24"
  - "98.51.100.0/24"
  - "203.0.113.0/24"
  - "2001:db8::/32"

listen

Type: list of key-value pairs
Default: [::]:3478 (TCP and UDP, TURN enabled)

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:

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

Type: path name | stdout
Default: log

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

Type: log level
Default: info

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

Type: non-negative integer
Default: 10

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

Type: positive integer | unlimited
Default: unlimited

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

Type: positive integer | unlimited
Default: 10

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

Type: positive integer | unlimited
Default: 10

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

Type: map of module configurations
Default: {}

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

Type: string
Default: eturnal.net

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

Type: IPv4 address
Default: Autodetected IPv4 address (or none)

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

Type: IPv6 address
Default: Autodetected IPv6 address (or none)

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

Type: port number
Default: 65535

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

Type: port number
Default: 49152

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

Type: path name
Default: run

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

Type: string | list of strings
Default: pseudorandom bits

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

Type: string
Default: eturnal

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

strict_expiry

Type: boolean
Default: false

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

Type: string | list of strings
Default: HIGH:!aNULL:@STRENGTH

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

Type: path name
Default: none

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

Type: path name
Default: none

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

Type: path name
Default: none

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

Type: string | list of strings
Default: cipher_server_preference

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

Type: list of IP addresses/CIDRs
Default: []

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

whitelist:
  - "203.0.113.113"
  - "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
Type: log level
Default: info

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
Type: string | IP address
Default: localhost

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

port
Type: port number
Default: 8089

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
Type: IP address | any
Default: any

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
Type: port number
Default: 8081

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

tls
Type: boolean
Default: false

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
Type: path name
Default: none

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
Type: path name
Default: none

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
Type: boolean
Default: true

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_PREFIX

This environment variable specifies the path to the etc directory containing the eturnal.yml configuration file. If, for example, ETURNAL_ETC_PREFIX is set to /usr/local/opt/eturnal, the file /usr/local/opt/eturnal/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:

See eturnalctl help for the full list of available commands, and eturnalctl help <command> for details regarding the specified <command>.