| Home | Documentation | Download |  |
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.
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
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.
list of IP addresses/CIDRs | default | recommendedThe 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"
list of key-value pairs[::]: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:
ip: addressip 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: numberport 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: protocoltransport 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: flagproxy_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: flagenable_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.
path name | stdoutlogThis 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 levelinfoThe 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.
non-negative integer10The 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.
positive integer | unlimitedunlimitedIf 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.
positive integer | unlimited10This 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.
positive integer | unlimited10This 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.
map of module configurations{}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
stringeturnal.netThis 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.
IPv4 addressnone)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.
IPv6 addressnone)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.
port number65535This 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.
port number49152This 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.
path namerunThis 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.
string | list of stringsThis 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.
stringeturnalThis option specifies the server software name announced to clients during the STUN/TURN communication.
booleanfalseIf 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.
string | list of stringsHIGH:!aNULL:@STRENGTHThis 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.
path namenoneThis 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.
path namenoneThe 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.
path namenoneThis 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.
string | list of stringscipher_server_preferenceThis 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
list of IP addresses/CIDRs[]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"
The eturnal server ships the following modules, which can be configured as described in this section.
This module enables logging of STUN queries. Without this module, STUN requests
only show up in the debug output.
log levelinfoThe value of this option determines the level used for logging STUN requests.
Valid log levels are critical, error, warning, notice, info, and
debug.
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:
string | IP addresslocalhostThis option specifies the host name or IP address InfluxDB's UDP service is listening on.
port number8089This option specifies the port number InfluxDB's UDP service is listening on.
This module exposes various STUN/TURN and (by default) virtual machine metrics
to Prometheus via HTTP under the /metrics endpoint.
IP address | anyanyThis 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 number8081This option specifies the port number the module is listening on. The default
value is 8081.
booleanfalseIf 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.
path namenoneThis 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.
path namenoneThis 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.
booleantrueIf 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.
The eturnal server recognizes the following environment variables.
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.
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.
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.
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.
If the relay_ipv4_addr option isn't specified, this environment variable defines the IPv4 address used for relaying data from/to TURN peers.
If the relay_ipv6_addr option isn't specified, this environment variable defines the IPv6 address used for relaying data from/to TURN peers.
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.
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.
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.
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.
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.
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 daemoneturnalctl foregroundeturnalctl consoleeturnalctl remote_consoleeturnalctl eval codeeturnalctl reloadeturnalctl infoeturnalctl sessionseturnalctl sessions username$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$timestamp:$suffix are used, just the
$suffix may be specified as username, in which case all
sessions with that $suffix are disconnected.eturnalctl credentialseturnalctl credentials expiry[s|m|h|d]
[suffix]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 usernameeturnalctl logleveleturnalctl loglevel leveleturnalctl versioneturnalctl stopeturnalctl help for the full list of available commands, and eturnalctl
help <command> for details regarding the specified <command>.