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.
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.
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
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"
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). 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:
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
,
or tls
. The default value is udp
.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: "::" 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.
path name | stdout
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 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
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
.
non-negative integer
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.
positive integer | unlimited
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.
positive integer | unlimited
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.
positive integer | unlimited
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.
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_influx: host: localhost port: 8089
string
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.
IPv4 address
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.
IPv6 address
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.
port number
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
.
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 number
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.
path name
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.
string
undefined
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.
string
eturnal
This option specifies the server software name announced to clients during the STUN/TURN communication.
path name
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.
path name
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.
The eturnal server ships the following modules, which can be configured as described in this section.
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:
second | millisecond
second
This option defines the time unit used for logging the duration of TURN sessions.
This module enables logging of STUN queries. Without this module, STUN requests
only show up in the debug
output.
log level
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
.
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 address
localhost
This option specifies the host name or IP address InfluxDB's UDP service is listening on.
port number
8089
This option specifies the port number InfluxDB's UDP service is listening on.
The eturnal server recognizes the following environment variables.
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).
Setting this environment variable tells epmd to listen on the specified port. By default, epmd listens on port 4369.
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 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.
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.
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.
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
eturnalctl foreground
eturnalctl console
eturnalctl remote_console
eturnalctl eval
codeeturnalctl info
eturnalctl reload
eturnalctl sessions
eturnalctl loglevel
eturnalctl loglevel
leveleturnalctl version
eturnalctl stop
eturnalctl help
for the full list of available commands, and eturnalctl
help <command>
for details regarding the specified <command>
.