Home

eturnal Documentation

Copyright © 2020 ProcessOne, SARL

Version: 1.4.3 (Dec 16 2020)

Authors: Holger Weiss.

eturnal is a STUN/TURN server that implements 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 credentails 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

Linux/x64 packages for DEB- and RPM-based distributions can be retrieved from eturnal.net. On other Linux/x64 systems, the binary release can be installed as described in this section. For building eturnal from source, see the README.md file shipped with eturnal's source code archive.

The binary release archive holds a stand-alone directory that includes everything required to run eturnal. It's recommended to create a dedicated system user for running eturnal (if not already done), and to extract the release archive into this user's home directory by running the following commands with superuser privileges:

# useradd -r -d /opt/eturnal eturnal
# curl https://eturnal.net/download/eturnal-1.4.3-linux-x64.tar.gz | tar -C /opt -xzf -

The example configuration file shipped with eturnal can either be edited in place or copied into the system's /etc directory, first:

# cp -i /opt/eturnal/etc/eturnal.yml /etc/

The release archive also includes a systemd unit file, which can be enabled by running the following commands with superuser privileges:

# cp /opt/eturnal/etc/systemd/system/eturnal.service /etc/systemd/system/
# systemctl daemon-reload
# systemctl --now enable eturnal

By default, the binary release assumes the user running eturnal is called eturnal, and his home directory is /opt/eturnal. If a different user and/or installation prefix is to be used, the systemd unit file and the eturnalctl script must be adjusted accordingly.

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

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. The following example shows the default blacklist:

blacklist:
  - "127.0.0.0/8"
  - "::1"
  - "2001::/32"
  - "2002::/16"

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). This is the only mandatory key-value pair for each listen entry. 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).
• port: number
  The (optional) 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 (optional) transport protocol must be one of udp, tcp, or tls. The default value is udp.
• enable_turn: flag
  The (optional) 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: "::"
    port: 3478         # This is the default for "transport: udp".
    transport: udp     # This is the default.
    enable_turn: true  # This is the default.
  -
    ip: "::"
    port: 3478         # This is the default for "transport: tcp".
    transport: tcp     # Default: "udp".
    enable_turn: true  # This is the default.
  -
    ip: "::"
    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 tells 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_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, eturnal will use the host name's IPv4 address. If relay_ipv4_addr is unspecified and the host name doesn't resolve to a public IPv4 address, eturnal will refuse to start, unless TURN is disabled for all listen entries.

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, eturnal will use the host name's IPv6 address. If relay_ipv6_addr is unspecified and the host name doesn't resolve to a public IPv6 address, 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.

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.

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. Specifying this option (or the environment variable ETURNAL_SECRET) is mandatory unless TURN relaying is disabled for all listen entries.

software_name

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

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_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.

Module Configuration

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

mod_example

This module just serves as an example for module developers and might be removed from a future release. It logs the duration and some metadata of TURN sessions, and has the following configuration option:

time_unit

This option defines the time unit used for logging the duration of TURN sessions.

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.

Environment Variables

The eturnal server recognizes the following environment variables.

ERL_EPMD_ADDRESS

On eturnal startup, an Erlang Port Mapper Daemon (epmd) service is spawned (if not running already). This service listens on all available interfaces by default. 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. It's usually recommended to set ERL_EPMD_ADDRESS to 127.0.0.1 (e.g., by calling systemctl edit eturnal and adding an Environment="ERL_EPMD_ADDRESS=127.0.0.1" line to the [Service] section).

ERL_EPMD_PORT

Setting this environment variable tells epmd to listen on the specified port. By default, epmd listens on port 4369.

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_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. Specifying either this environment variable or the secret option is mandatory unless TURN relaying is disabled for all listen entries.

LOGS_DIRECTORY

If the log_dir option isn't specified, this environment variable specifies 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 specifies 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 info
  Print some details regarding the running eturnal instance.
• eturnalctl reload
  Reload the configuration file.
• eturnalctl sessions
  Print the list of currently active TURN sessions.
• 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