I. DOWNLOAD

You have to download the archive file turnserver-*.tar.gz and unpack it:

$ tar xfz turnserver-*.tgz

it will create the directory 'turnserver-*' with all sources, build files, 
examples and documentation.

II. BUILD

If you are sure that you system is ready for the build (see the section 
"Extra libraries and Utilities" below) then you can build the system.
First, you have to run the configure script:

	$ cd turnserver-*
	$ ./configure
	
It will create a Makefile customized for your system. 

By default, the generated Makefile will be set to install everything
in /usr/local directory. You can change that and some other settings by 
setting PREFIX variable (and other common build variables) in the 
configure command line. Compilation and linking options
can be customized, too. For example:

	$ PREFIX=/opt CC=clang CFLAGS=-D_CAURIB LDFLAGS=-lshanka ./configure   

(see below a separate section for more details).

The script configure is a proprietary script. It will create a Makefile 
that you can use to build the project:

	$ make

The make command without options will do the following:
 - compile the code.
 - create bin/ sub-directory and put the TURN server, TURN admin and "utility" programs there.
 - create lib/ sub-directory and put the client library there.
 - create include/turn/ sub-directory and put include files there.

The programs can be either called directly, or a shell scripts can be used. 
The script examples are located in examples/scripts directory. These scripts are just 
examples: you can run them successfully for the tests, but
you will have to change the script parameters for your real environment.

The command:

	$ sudo make install 

will install everything into the system file structure (see below).

The command:

	$ sudo make deinstall
	
will remove all installed TURN Server files from your system.

The command:

	$ make clean 
	
will clean all results of the build and configuration actions.

Do not run "make clean" before "make deinstall". The "clean" command will
remove the Makefile and you will not be able to "deinstall" then. If that 
has happened, then run ./configure and make again, then deinstall and then clean.

NOTE: On most modern systems, the build will produce dynamically linked 
executables. If you want statically linked executables, you have to modify, 
accordingly, the Makefile.in template file.

III. INSTALL

This step is optional. You can run the turnserver from the original build 
directory, successfully, without installing the TURN server into the system. 
You have to install the turnserver only if you want to integrate the turnserver 
in your system.

Run the command:

$ make install

It will install turnserver in /usr/local/ directory (or to whatever directory
was set in the PREFIX variable). You will have to copy 
/usr/local/etc/turnserver.conf.default to /usr/local/etc/turnserver.conf file 
and adjust your runtime configuration.

This command will also:

 - copy the content of examples subdirectory into 
 PREFIX/share/examples/turnserver/ directory;
 - copy the content of include/turn subdirectory into
 PREFIX/include/turn/ directory;
 - copy the database schema file turndb/schema.sql into PREFIX/share/turnserver/ 
 directory;
 - copy all docs into PREFIX/share/doc/turnserver/ directory.

After the installation, you may want to adjust the system-wide shared library search 
path by using "ldconfig" (Linux & FreeBSD) or "crle" (Solaris). Your system must be 
able to find the libevent2, openssl and (optionally) PostgreSQL and/or MySQL and/or Redis 
shared libraries, either with the help of the system-wide library search configuration or 
by using LD_LIBRARY_PATH.

IV. PLATFORMS

The TURN Server is using generic *NIX system APIs and is supposed to be usable 
on wide range of *NIX systems. 

The following platforms have been used in the development:

	- Linux Ubuntu 11.x and 12.x, i386 and x86_64
	- FreeBSD 6.x, i386
	- FreeBSD 8.x, i386
	- PC-BSD 9.x, x86_64
	- Solaris 11, x86_64
	- Linux CentOS / Red Hat Enterprise Edition 6.3, x86_64 (amd64)
	- Linux CentOS / Red Hat Enterprise Edition 6.4, x86_32 (i386)
	- Linux Debian 'Squeeze', i386
	- Linux Mint 14.1 'Nadia', i386
	- Linux Debian 'Wheezy', x86_64 
	- Cygwin 1.7.17 (only partial support, see STATUS file)

It must work on many other *NIXes, as well. The configure script and/or 
Makefile may need adjustments for other *NIXes not mentioned above.

The code of the client messaging library can be compiled and used on 
Windows, too, but it is not supported for now.

V. COMPILERS

The TURN Server is written in C programming language, for portability 
and for the performance reasons. 

The tested C compilers are:

	- gcc 3.4.4 thru 4.7.2
	- clang 3.0 or better
	- Solaris Studio 12.3 C compiler, version 5.12

It may be compiled with others compilers, too.

The code is compatible with C++ compiler, and a C++ compiler
(like g++) can be used for the compilation, too:

	$ CC=g++ ./configure
	$ make

VI. WHICH EXTRA LIBRARIES AND UTILITIES YOU NEED 

In addition to common *NIX OS services and libraries, to compile this code, 
OpenSSL (version 1.0.0a or better recommended) and libevent2 (version 2.0.5 
or better) are required, the PostgreSQL C client development setup is optional, 
the MySQL C client development setup is optional, and the Hiredis development
files for Redis database access are optional.
For fully functional build, the extra set of libraries must be installed
in full version (the development headers and the libraries to link with). 
For runtime, only runtime setup is required. If the build is modified for static 
linking, then even runtime installation is not needed.

OpenSSL, libevent2, PostgreSQL, MySQL and Hiredis library (for redis access)
can be downloaded from their web sites:
 - http://www.openssl.org;
 - http://www.libevent.org;
 - http://www.postgresql.org;
 - http://www.mysql.org;
 - http://redis.io .
 
The installations are pretty straightforward - the usual 
"./configure" and "make install" commands. Install them into their default 
locations - the configure script and the Makefile are assuming that they are 
installed in their default locations. If not, then you will have to modify those.

FreeBSD, PC-BSD, Linux Ubuntu 11.10+, Debian Wheezy have even simpler way of the
third party tools installation:      

	*) PC-BSD or FreeBSD (the ports database is assumed to be installed):

		$ cd /usr/ports/security/openssl/
		$ sudo make install clean
		$ cd /usr/ports/devel/libevent2/
		$ sudo make install clean
		$ cd /usr/ports/databases/postgresql84-client/ (or any other version)
		$ sudo make install clean
		$ cd /usr/ports/databases/mysql51-client/ (or any other version)
		$ sudo make install clean
		$ cd /usr/ports/databases/hiredis/
		$ sudo make install clean

	**) Linux Ubuntu 11.10+, Debian Wheezy, Mint 14+:
		
		$ sudo apt-get install libssl-dev
		$ sudo apt-get install libevent-dev
		$ sudo apt-get install libpq-dev
		$ sudo apt-get install mysql-client
		$ sudo apt-get install libmysqlclient-dev
		$ sudo apt-get install libhiredis-dev
		
		or you can use Synaptic or other software center.
		
	***) Other OS in Debian family (Squeeze and earlier Ubuntus) setups are similar, 
	although some packages have different names. 
		 
	****) On CentOS / RedHat 6.x you have to install libevent2 "manually", and optionally you have to
	download and install Hiredis, but everything else can be found in the software repository. 

NOTE: If your tools are installed in non-standard locations, you will have to adjust CFLAGS 
and LDFLAGS environment variables for TURN server ./configure script. For example, to 
configure the TURN server with Solaris 11 PostgreSQL 32-bits setup, you may use a command 
like this:

  $ CFLAGS="${CFLAGS} -I/usr/postgres/9.2-pgdg/include/" LDFLAGS="${LDFLAGS} -L/usr/postgres/9.2-pgdg/lib/" ./configure

You may also have to adjust the turn server start script, add PostgreSQL and/or MySQL and/or Redis 
runtime library path to LD_LIBRARY_PATH. Or you may find that it would be more convenient to adjust the 
system-wide shared library search path by using "ldconfig" (Linux & FreeBSD) or "crle" (Solaris).

See also the next section.

NOTE: See "PostgreSQL setup" and "MySQL setup" and "Redis setup" sections below for more database setup information.

NOTE: If you do not install PostgreSQL or MySQL or Redis then you will
be limited to flat files for user database. It will work great for 
smaller user databases (like 100 users) but for larger systems you 
will need PostgreSQL or MySQL or Redis.

NOTE: To run PostgreSQL or MySQL or Redis server on the same system, you will also have to install 
a corresponding PostgreSQL or MySQL or Redis server package. C development packages only provide 
development libraries, and client libraries only provide client access utilities and 
runtime libraries. The server packages includes everything - client, C development and 
server runtime.   

NOTE: OpenSSL to be installed before libevent2. When libevent2 is building, it 
is checking whether OpenSSL has been already installed, and which version of 
OpenSSL. If the OpenSSL is missed, or too old, then libevent_openssl library is 
not being created during the build, and you will not be able to compile the 
TURN Server with TLS support.

NOTE: An older libevent version, version 1.x.x, is often included in some *NIX 
distributions. That version has its deficiencies and is inferior to the newer 
libevent2, especially in the performance department. This is why we are 
not providing backward compatibility with the older libevent version. 
If you have a system with older libevent, then you have to install the new 
libevent2 from their web site. It was tested with older *NIXes (like FreeBSD 6.x) 
and it works just fine.

NOTE: OpenSSL version 1.0.0a or newer is recommended. Older versions do not 
support DTLS, reliably, in some cases. For example, the Debian 'Squeeze' Linux with 
supplied 0.9.8 version of OpenSSL, does not work correctly with DTLS over IPv6. 
If your system already has an older version OpenSSL installed (usually in directory
/usr) then you may want to install your newer OpenSSL "over" the old one (because it will 
most probably will not allow removal of the old one). When installing the newer OpenSSL,
run the OpenSSL's configure command like this:

    $ ./config --prefix=/usr

that will set the installation prefix to /usr (without "--prefix=/usr" by default it 
would be installed to /usr/local). This is necessary if you want to overwrite your 
existing older OpenSSL installation.

VII. BUILDING WITH NON-DEFAULT PREFIX DIRECTORY

Say, you have an older system with old openssl and old libevent 
library and you do not want to change that, but you still want 
to build the turnserver.

Do the following steps:

1) Download new openssl from openssl.org.
2) Configure and build new openssl and install it into /opt:
  
    $ ./config --prefix=/opt
    $ make
    $ make install

3) Download the latest libevent2 from libevent.org, configure and install it into /opt:

    $ ./configure --prefix=/opt
    $ make
    $ make install

4) Change directory to rfc5766-turn-server and build it:

    $ PREFIX=/opt ./configure
    $ make

After that, you can either use it locally, or install it into /opt. 
But remember that to run it, you have to adjust your LD_LIBRARY_PATH, like that:

    $ LD_LIBRARY_PATH=/opt/lib ./bin/turnserver

An alternative would be adjusting the system-wide shared library search path by using "ldconfig" 
(Linux & FreeBSD) or "crle" (Solaris).

VIII. TEST SCRIPT SETS

First of all, we can use test vectors from RFC 5769 to double-check that our STUN/TURN 
message encoding algorithms work properly. Run the utility:

 $ cd examples
 $ ./scripts/rfc5769.sh
 
It will perform several protocol checks and print the results on the output. If anything
has compiled wrongly (TURN Server, or OpenSSL libraries) then you will see some errors.

Now, you can perform the TURN functionality test (bare minimum TURN example).

If everything compiled properly, then the following programs must run 
together successfully, simulating TURN network routing in local loopback
networking environment:

Open two shell screens or consoles:

In shell number 1, run TURN server application:
 $ cd examples
 $ ./scripts/basic/relay.sh

In shell number 2, run test client application:

 $ cd examples
 $ ./scripts/basic/udp_c2c_client.sh

If the client application produces output and in approximately 22 seconds prints 
the jitter, loss and round-trip-delay statistics, then everything is fine.

There is another more complex test:

In shell number 1, run TURN server application:
 $ cd examples
 $ ./scripts/basic/relay.sh
 
In shell number 2, run "peer" application:
 $ cd examples
 $ ./scripts/peer.sh

In shell number 3, run test client application:

 $ cd examples
 $ ./scripts/basic/udp_client.sh (or ./scripts/basic/tcp_client.sh)

There is a similar set of examples/scripts/longtermsecure/* scripts for TURN environment 
with long-term authentication mechanism. This set of scripts is more complex, 
and checking the scripts options is useful for understanding how the TURN Server works:

In shell number 1, run secure TURN server application:
 $ cd examples
 $ ./scripts/longtermsecure/secure_relay.sh
 
In shell number 2, run "peer" application:
 $ cd examples
 $ ./scripts/peer.sh

In shell number 3, run secure test client application:

 $ cd examples
 $ ./scripts/longtermsecure/secure_udp_client.sh
  
 (or ./scripts/longtermsecure/secure_tcp_client.sh)
 (or ./scripts/longtermsecure/secure_tls_client.sh)
 (or ./scripts/longtermsecure/secure_dtls_client.sh)
 (or ./scripts/longtermsecure/secure_udp_c2c.sh for "peerless" client-to-client communications)

The provided scripts are set for the local loopback communications, as an example and 
as a test environment. Real networking IPs must be used in real work environments. 

Try wireshark to check the communications between client, turnserver and the peer. 

Check the README.* files and the comments in the scripts relay.sh and secure_relay.sh 
as a guidance how to run the TURN server.

IX. OS X compilation notes

OS X usually has an older version of openssl supplied, with some Apple additions. 
The compilation will produce lots of warnings which can be ignored, but the best 
option is to install a good fresh openssl development library, free of Apple tweaks,
from http://www.openssl.org. 

X. CLIENT API LIBRARY.

The compilation process will create lib/ sub-directory with libturnclient.a library. 
The header files for this library are located in include/turn/client/ sub-directory.
The C++ wrapper for the messaging functionality is located in TurnMsgLib.h header.
An example of C++ code can be found in stunclient.c file. This file is compiled as a 
C++ program if C++ compiler is used, and as a C program if C compiler is used.

XI. DOCS

After installation, the man page turnserver(1) must be available. The man page is 
located in man/man1 subdirectory. If you want to see the man page without 
installation, run the command:

	$	man -M man turnserver

HTML-formatted client library functions reference is located in docs/html subdirectory
of the original archive tree. After the installation, it will be placed in 
PREFIX/share/doc/turnserver/html.

XII. PostgreSQL setup

The site http://www.postgresql.org site has excellent extensive documentation. 
For a quick-start guide, you can take a look into this page: 
http://www.freebsddiary.org/postgresql.php. That page is written for FreeBSD users, 
but it has lots of generic information applicable to other *NIXes, too.

For the psql-userdb TURN server parameter, you can either set a PostgreSQL connection string,
or a PostgreSQL URI, see the link:

For 8.4 PostgreSQL version:
http://www.postgresql.org/docs/8.4/static/libpq-connect.html

For newer 9.x versions: 
http://www.postgresql.org/docs/9.2/static/libpq-connect.html#LIBPQ-CONNSTRING.

In the PostgreSQL connection string or URI, you can set the host, the access port, 
the database name, the user, and the user password (if the access is secured). 
Numerous other parameters can be set, see the links above. 
The TURN server will blindly use that connection string without any 
modifications. You are responsible for the right connection string format.

Below are the steps to setup the PostgreSQL database server from scratch:

1) Install PostgreSQL server.

2) Find and edit Postgres' pg_hba.conf file to set the access options (see docs).
On different systems, it may be located in different places.
Set the local access as "trust" for now (you can change it later), 
for TCP/IP access set the value as "md5".
To set TCP/IP access from any host, use "0.0.0.0/0" for IPv4, and "::/0" for IPv6.

3) Edit postgresql.conf file to allow TCP/IP access - uncomment and edit 
the "listen_addresses" option (see docs). On different systems, this file may be 
located in different places.

4) Restart your system.

5) Check /etc/passwd file to find out which user account is used for the PostgreSQL
admin access on your system (it may be "pgsql", or "postgres", or "postgresql"). 
Let's assume that this is "postgres" account.

6) Create a database for the TURN purposes, with name, say, "turn":

   $ createdb -U postgres turn

7) Create a user for the TURN with name, say, "turn":
   $ psql -U postgres turn
     turn=# create user turn with password 'turn';
     turn=# 
     Ctrl-D

8) Create the TURN users database table:

   $ psql -U turn turn
     Password for user turn: <type "turn">
     turn=> CREATE TABLE turnusers_lt (name varchar(512) PRIMARY KEY,hmackey char(32));
     turn=>
     Ctrl-D

9) You are ready to use the TURN database. The database name is "turn",
the user name is "turn", the user password is "turn". Of course, you can choose 
your own names.

The database schema for the TURN server is very minimalistic and is located in project's 
turndb/schema.sql file, or in the system's PREFIX/share/turnserver/schema.sql file after
the turnserver installation:

# Table for long-term credentials mechanism authorization:
#
CREATE TABLE turnusers_lt (
    name varchar(512) PRIMARY KEY,
    hmackey char(32)
);

# Table for short-term credentials mechanism authorisation:
#
CREATE TABLE turnusers_st (
    name varchar(512) PRIMARY KEY,
    password varchar(512)
);

# Table holding shared secrets for secret-based authorization
# (REST API). It can only be used together with the long-term 
# mechanism:
#
CREATE TABLE turn_secret (
    value varchar(512)
);

The field hmackey contains HEX string representation of the 128 bits key.
We do not store the user password, for security reasons.
Storing only the HMAC key has its own implications - if you change the realm,
you will have to update the HMAC keys of all users, because the realm is used for
the HMAC key generation.

You can use turnadmin program to manage the database - you can either use turnadmin to 
add/modify/delete users, or you can use turnadmin to produce the hmac keys and 
modify the database with your favorite tools.

Examples of database schema creation:

psql -h <host> -U <db-user> -d <database-name>  < turndb/schema.sql
(old style for 8.4)

psql postgresql://username:password@/databasename < turndb/schema.sql
(newer style for 9.x, UNIX domain local sockets)

Or:

psql postgresql://sql-userusername:password@hostname:port/databasename < turndb/schema.sql
(newer style for 9.x, TCP/IP access)

Here, the string "postgresql://turn:turn@/turn" is the connection URI. 
Of course, the administrators can play with the connection string as they want.

When starting the turnserver, the psql-userdb parameter will be, for example:

turnserver ... --psql-userdb="host=localhost dbname=turn user=turn password=turn connect_timeout=30"

Or, for 9.x PostgreSQL versions: 
turnserver ... --psql-userdb=postgresql://username:password@/databasename ...


XII. MySQL setup

The MySQL setup is similar to PostgreSQL (same idea), and is well documented on their 
site http://www.mysql.org. The TURN Server database schema is the same as for PostgreSQL
and you can find it in turndb/schema.sql file.

If the TURN server was compiled with MySQL support, then we can use the TURN server 
database parameter --mysql-userdb. The value of this parameter is a connection string 
for the MySQL database. As "native" MySQL does not have such a feature as 
"connection string", the TURN server parses the connection string and converts it into 
MySQL database access parameter. The format of the MySQL connection string is:

"host=<host> dbname=<database-name> user=<database-user> password=<database-user-password> port=<port> connect_timeout=<seconds>"

(all parameters are optional)

So, an example of the MySQL database parameter in the TURN server command line would be:

--mysql-userdb="host=localhost dbname=turn user=turn password=turn connect_timeout=30"

Or in the turnserver.conf file:

mysql-userdb="host=localhost dbname=turn user=turn password=turn connect_timeout=30"

XIII. Redis setup

The Redis setup is well documented on their site http://redis.io. 
The TURN Server Redis database schema description can be found 
in turndb/schema.*.redis files.

If the TURN server was compiled with Hiredis support (Hiredis is the C client library 
for Redis), then we can use the TURN server database parameter --redis-userdb. 
The value of this parameter is a connection string 
for the Redis database. As "native" Redis does not have such a feature as 
"connection string", the TURN server parses the connection string and converts it into 
Redis database access parameter. The format of the Redis connection string is:

"ip=<ip-addr> dbname=<database-number> password=<database-password> port=<port> connect_timeout=<seconds>"

(all parameters are optional)

So, an example of the Redis database parameter in the TURN server command line would be:

--redis-userdb="ip=127.0.0.1 dbname=0 password=turn connect_timeout=30"

Or in the turnserver.conf file:

redis-userdb="ip=127.0.0.1 dbname=0 password=turn connect_timeout=30"

Redis can be also used for the TURN allocation status check and for status and traffic notifications.
See the explanation in the turndb/schema.stats.redis file.

 


  
