eturnal¶

eturnal is a modern, straightforward STUN and TURN server written in Erlang. Clients can connect using UDP, TCP, or TLS over IPv4 or IPv6. For authentication, eturnal supports the mechanism described in the REST API for Access to TURN Services specification.

Note

For this guide you should be familiar with the basic concepts of

License¶

eturnal is released under the Apache License, Version 2.0.

Prerequisites¶

Set up your URL:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

Check the latest release and download a precompiled tarball from https://eturnal.net and adapt the download url to the most recent version in the commands below:

[isabell@stardust ~]$ wget https://eturnal.net/download/linux/eturnal-1.10.1-linux-x64.tar.gz
[isabell@stardust ~]$ tar xzf eturnal-1.10.1-linux-x64.tar.gz
[isabell@stardust ~]$

Configuration¶

Open Firewall Ports¶

eturnal needs 2 listen ports, plus a port range for relaying UDP connections. So lets open 5 ports.

To make the application accessible from the outside, open a port in the firewall:

[isabell@stardust ~]$ uberspace port add
Port 40132 will be open for TCP and UDP traffic in a few minutes.
[isabell@stardust ~]$

eturnal Config¶

Generate a DH-file and a random super long secret (64 characters).

[isabell@stardust ~]$ openssl dhparam -out $HOME/eturnal/etc/dh-parameters.pem 4096
Generating DH parameters, 4096 bit long safe prime, generator 2
This is going to take a long time
........+.................................+.....................+..................
....................+.....................................+........+...............
[...]
[isabell@stardust ~]$ openssl rand -hex 32
<super-long-secret>

Backup the standard config:

[isabell@stardust ~]$ mv ~/eturnal/etc/eturnal.yml ~/eturnal/etc/eturnal.yml.bkp
[isabell@stardust ~]$

Then, create a new file at ~/eturnal/etc/eturnal.yml and replace values in brackets <value> with your values:

eturnal:

  secret: "<super-long-secret>"

  listen:
    -
      ip: "::"
      port: <port-1>
      transport: udp
    -
      ip: "::"
      port: <port-1>
      transport: tcp
    -
      ip: "::"
      port: <port-2>
      transport: tls

  tls_crt_file: /home/isabell/etc/certificates/isabell.uber.space.crt
  tls_key_file: /home/isabell/etc/certificates/isabell.uber.space.key
  tls_dh_file: /home/isabell/eturnal/etc/dh-parameters.pem

  relay_min_port: <port-3>
  relay_max_port: <port-5>

  blacklist:
    - "127.0.0.0/8"
    - "::1"

  log_level: error
  log_rotate_size: 10485760
  log_rotate_count: 10
  log_dir: stdout

Find other configuration options in the reference documentation. You can now first start eturnal as daemon and check it’s startup by invoking:

[isabell@stardust ~]$ ~/eturnal/bin/eturnalctl daemon
No cookie is set or found. This limits the scripts functionality, installing, upgrading, rpc and getting a list of versions will not work.
^C (press CTRL+C)
[isabell@stardust ~]$ ~/eturnal/bin/eturnalctl info
eturnal 1.10.1 on Erlang/OTP 25 (ERTS 13.0.3)
Uptime: 0 days, 0 hours, 0 minutes, 27 seconds
Active TURN sessions: 0
Processes: 77
Total length of run queues: 1
Total CPU usage (reductions): 1313446
Allocated memory (MiB): 33
[isabell@stardust ~]$

If it’s shows an error message, check your configuration.

Afterwards you can set up the service by creating a file ~/etc/services.d/eturnal.ini with the following content:

[program:eturnal]
command=%(ENV_HOME)s/eturnal/bin/eturnalctl foreground
autostart=yes
autorestart=yes
startsecs=30

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check the logs.

Finishing installation¶

There are a multiple applications that can use eturnal as STUN/TURN server.

Nextcloud Talk¶

If you are using Nextcloud, the Talk app can use eturnal in in the Talk` Tab of Settings:

Add isabell.uber.space:<port-1> as STUN Server.

Add isabell.uber.space:<port-1> with <super-long-secret> as TURN and TURNS Server for UDP and TCP

Test your server (the little heart beat symbol next to the fields)

The test should result in a checkmark symbol. If not check your Nextcloud and eturnal logs.

Synapse¶

The Synapse homeserver can employ your eturnal server for webRTC calls by editing your homeserver.yaml config:

## TURN ##

# The public URIs of the TURN server to give to clients
turn_uris:
  - "turns:isabell.uber.space:<port-1>?transport=udp"
  - "turns:isabell.uber.space:<port-1>?transport=tcp"
  - "turn:isabell.uber.space:<port-1>?transport=udp"
  - "turn:isabell.uber.space:<port-1>?transport=tcp"

# The shared secret used to compute passwords for the TURN server
turn_shared_secret: "<super-long-secret>"

Tested on Uberspace v7.13 with Erlang v24 and eturnal v1.10.1.

Written by: this.ven <https://this.ven.uber.space>