Skip to content
Branch: master
Go to file
Code

README.md

eturnal STUN/TURN Server

Build Status

eturnal is a modern, straightforward STUN/TURN server with full IPv6 support. For TURN authentication, the mechanism described in the REST API for Access to TURN Services specification is implemented.

On Linux/x64 systems, you can install the binary release. On other platforms, you must build eturnal from source.

Installing the Linux/x64 Binaries

Quick Test

The following two commands give you a STUN/TURN server listening on port 3478 (UDP/TCP) and port 5349 (TLS) using the specified shared secret for TURN authentication (no root privileges required):

$ curl https://eturnal.net/download/eturnal-0.6.0-linux-x64.tar.gz | tar -C /tmp -xzf -
$ ETURNAL_SECRET='crypt1c' /tmp/eturnal/bin/eturnal foreground

To stop the server, press <Ctrl>+C. To remove it, run rm -rf /tmp/eturnal.

Persistent Installation

You'll need root privileges for the following commands. Therefore, call su - or sudo -i, first.

  1. Create user. This step is of course only required if you're installing eturnal for the first time:

    # useradd -r -m -d /opt/eturnal eturnal
    

    Otherwise, create a backup of the old installation, first:

    # mv /opt/eturnal /opt/eturnal-$(date '+%F')
    
  2. Download and extract binary release:

    # curl https://eturnal.net/download/eturnal-0.6.0-linux-x64.tar.gz | tar -C /opt -xzf -
    
  3. Configure the shared secret, your server's IP address(es), and optionally other settings:

    # vi /opt/eturnal/etc/eturnal.yml
    
  4. Start the systemd service:

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

Note: If you'd like to use a different user and/or installation prefix, you must edit the /etc/systemd/system/eturnal.service file accordingly.

Building From Source

Requirements

Note that you need the development headers of the libraries as well. Linux distributions often put those into separate *-dev or *-devel packages. For example, on DEB-based distributions you'd typically install libyaml-dev and libssl-dev, on RPM-based distributions you'll probably need libyaml-devel and openssl-devel.

Compilation

Note: If you build directly from the Git repository rather than using the official source tarball, you must download rebar3 and make it executable (chmod +x rebar3), first.

$ curl https://eturnal.net/download/eturnal-0.6.0.tar.gz | tar -C /tmp -xzf -
$ cd /tmp/eturnal-0.6.0
$ ./rebar3 as prod tar

This generates the archive file _build/prod/rel/eturnal/eturnal-0.6.0.tar.gz. The default installation prefix is set to /opt/eturnal, and it's assumed the server will be executed by a user named eturnal. To change these defaults, edit the build.config file and re-run ./rebar3 as prod tar.

Quick Test

The following command gives you a STUN/TURN server listening on port 3478 (UDP/TCP) and port 5349 (TLS) using the specified shared secret for TURN authentication:

$ ETURNAL_SECRET='crypt1c' ./rebar3 shell

To stop the server, press <Ctrl>+C.

Persistent Installation

The generated archive file holds the contents of the installation prefix. Therefore, you'd follow the binary installation instructions above, but adapt step 2 to extract the archive into the /opt/eturnal directory:

# cd /opt/eturnal
# tar -xzf /tmp/eturnal-0.6.0/_build/prod/rel/eturnal/eturnal-0.6.0.tar.gz

Configuring eturnal

The eturnal server is configured by editing the /opt/eturnal/etc/eturnal.yml file. This file uses the (indentation-sensitive!) YAML format. A commented example configuration with sane default settings is shipped with the eturnal server. However, for TURN relaying to work, you'll have to specify the shared authentication secret, and probably also the relay_ipv4_addr option, which should be set to the server's external IPv4 address.

Note: The /opt/eturnal/etc/eturnal.yml file can be copied to /etc/eturnal.yml, in which case the original copy in /opt will be ignored. That way, the configuration won't be overwritten during upgrades.

Running eturnal

On Linux systems, the eturnal server is usually controlled by systemd:

# systemctl start eturnal
# systemctl restart eturnal
# systemctl reload eturnal
# systemctl stop eturnal

For non-systemd platforms, an example init script is shipped in the etc/init.d directory.

For controlling eturnal, the eturnalctl command can be used; see:

# eturnalctl help

Logging

If eturnal was started by systemd, log files are written into the /var/log/eturnal directory by default. To use an external log rotation utility, remove the log_rotate_* options from your eturnal.yml configuration file and run systemctl reload eturnal. eturnal will detect external rotation automatically, so there's no need to send a HUP signal after log rotation.

Feedback/Support

Please use our issue tracker for bug reports and feature requests. Feel free to (ab)use it for usage questions as well.

You can’t perform that action at this time.