skyformat99 / turnserver

Implementation of RFC5766 and RFC5389

TurnServer

A fork from http://turnserver.sourceforge.net

TurnServer is an open-source implementation of Traversal Using Relays around NAT (TURN) protocol. It aims to be compliant with RFC5766 (TURN) and RFC5389 (STUN).

The TURN protocol allows a client to obtain IP addresses and ports from such a relay. It is most useful for elements behind symmetric NATs or firewalls that wish to be on the receiving end of a connection to a single peer.

TURN clients can connect to TurnServer with the following protocols: UDP, TCP and TLS over TCP. Experimental DTLS support is also provided. Relaying data can be done with UDP or TCP protocol.

TurnServer supports also RFC5389 (STUN Binding request), RFC6062 (relay data with TCP protocol) and RFC6156 (relay IPv6-IPv6, IPv4-IPv6 and IPv6-IPv4).

TurnServer is known to work on the following systems:

• GNU/Linux 2.6;
• FreeBSD 7.x, 8.x.

Build / install

TurnServer requires following libraries:

• libconfuse development files (version >= 2.6);
• libssl development files;
• librt (normally included in Linux and BSD distribution).

TurnServer is written in pure C according to the C99 and POSIX + XSI standards. Thus it should be compiled on all POSIX systems which have realtime signals support.

Note for BSD users, install the required libconfuse ports in /usr/ prefix, otherwise you have to set the PKG_CONFIG_PATH variable or make symlinks before running ./configure script:

ln -sf /usr/local/lib/libconfuse.so /usr/lib/ && \
ln -sf /usr/local/include/confuse.h /usr/include/

To build TurnServer, run following commands:

$ autoreconf -i
$ ./configure
$ make
$ make install

./configure can take options:

--enable-debug-build                 : allow to compile with debug informations
                                       default=no
--enable-fdsetsize=number            : allow to preconfigure FD_SETSIZE macro
                                       (must be a number >=32) default=no
--enable-xor-peer-address-max=number : allow to preconfigure
                                       XOR_PEER_ADDRESS_MAX macro (must be a
                                       number > 0) default=5

Copy the template configuration file (extra/turnserver.conf.template) and template accounts database file (extra/turnusers.txt) to a directory of your choice (i.e. /etc/ or /usr/local/etc/). Do not forget, the accounts database file pathname has to be populated in configuration file (attribute account_file). See next sections to know how to setup configuration and accounts files.

To generate the API documentation:

$ make doxygen-run

The HTML generated documentation is located in doc/html/ directory of TurnServer sources.

Launch the server:

$ turnserver -c /path/to/config/file

Configuration file

In extra/ directory you will find a configuration template file (turnserver.conf.template). Change settings according to your environment.

Here are important parameters,

• listen_address : public IPv4 address;
• listen_addressv6 : public IPv6 address;
• realm : realm (i.e. domain.org) of the server;
• account_file : specify the location of the accounts database file;
• tcp_port and udp_port : bind the service on the specified port;
• tls : enable TLS support;
• tls_port : bind the secure service on the specified port.
• ca_file : Certification Authority (must set if tls = true)
• cert_file : server certificate (must set if tls = true)
• private_key_file : server private key (must set if tls = true)
• turn_tcp : enable TURN-TCP extension
• tcp_buffer_userspace : enable userspace buffering for TURN-TCP extension, if false OS buffering will be used
• tcp_buffer_size : maximum amount of bytes that can be buffered for TURN-TCP (RFC6062) extension

Other parameters such as allocations number quota or experimental features are documented in manpages:

$ man turnserver.conf

Accounts database file

TurnServer uses (for the moment) a basic text file which contains accounts information.

The format of each line is:

login:password:realm:state

The state can be "authorized", "refused" or "restricted". The "restricted" state means the account has bandwidth restrictions.

Note: realm have to match realm parameter defined in TurnServer configuration file. The ":" character is also forbidden in login, password or realm fields.

Security

If TurnServer is launched as root or set-uid root, it is possible to drop privileges.

One possibility is to create a special user (which have less privileges). To create such a user named turnserver:

adduser --system --group turnserver

Then you have to tell configuration file to choose this user:

unpriv_user = turnserver

If TurnServer is set-uid root and unpriv_user is not set, TurnServer will drop privileges to the user who launched the binary.

Note: if turnserver is launched as root and unpriv_user not set, the program will not loose its root privileges.

How-to test simply turnserver

TurnServer is shipped with two test tools: test_turn_client and test_echo_server. The first one is a minimal TURN client and test_echo_server is a simple UDP echo server.

To test TurnServer simply:

• configure turnserver.conf;
• configure turnusers.txt ;
• launch "turnserver -c /path/to/turnserver.conf";
• launch "test_echo_server 8086";
• launch "test_turn_client -t udp -s turnserver_address -p turnserver_address -w 8086 -u user -g password -d domain.org".

The turnserver_address parameter should be the address configured in turnserver.conf's listen_address or listen_addressv6. if you want to use localhost here, you should configure listen_address to 127.0.0.1 and listen_addressv6 to ::1. The user, password and domain.org parameters are the ones from turnusers.txt.

It is not necessary to run the server and the test tools on different computers but it is recommended just to be sure everything work as in real use-case.