README

This WIKI is outdated and will be removed soon!! Please check the source for more recent documentation: https://github.com/coturn/coturn

GENERAL INFORMATION

The TURN Server project contains the source code of a TURN server and TURN client messaging library. Also, some extra programs provided, for testing-only purposes.

See the INSTALL file for the building instructions.

After the build, you will have the following binary images:

turnserver: TURN Server relay. The compiled binary image of this program is located in bin/ sub-directory.
turnadmin: TURN administration tool. This tool can be used for:
1. generation of TURN keys for the user accounts. For security reasons, we do not recommend storing passwords openly. The better option is to use pre-processed "keys" which are then used for authentication. These keys are generated by turnadmin.
2. listing available users in the database.
3. adding and deleting users in the database.
4. updating user passwords.
5. setting shared secret for TURN REST API.
turnutils_uclient: emulates multiple UDP,TCP,TLS or DTLS clients. The compiled binary image of this program is located in bin/ sub-directory.
turnutils_peer: a simple stateless UDP-only "echo" server, to be used as the final server in relay pattern ("peer"). For every incoming UDP packet, it simply echoes it back. (this program is provided for the testing purposes only !) When the test clients are communicating in the client-to-client manner, this component is not needed. The compiled binary image of this program is located in bin/ subdirectory.
turnutils_stunclient: a simple STUN client example that implements RFC 5389 and RFC 5780. The compiled binary image of this program is located in bin/ subdirectory.
turnutils_rfc5769check: a utility that checks the correctness of the STUN/TURN protocol implementation. This program will perform several checks and print the result on the screen. It will exit with 0 status if everything is OK, and with (-1) if there was an error in the protocol implementation.

In the "examples/scripts" subdirectory, you will find the examples of command lines to be used to run the programs. The scripts are meant to be run from examples/ subdirectory, for example:

	$ cd examples
	$ ./scripts/longtermsecure/secure_relay.sh

RUN

turnserver application: a TURN relay server implementation

Usage:

       $ turnserver [flags] [-n | -c <config-file>] [ --db=<sqlite-db-file> |--userdb=<sqlite-db-file> | --psql-userdb=<db-conn-string> | --mysql-userdb=<db-conn-string> ] [options]
       $ turnserver -h

TURNSERVER WIKI PAGE

turnadmin application: a TURN relay administration tool

Usage:

       $ turnadmin [command] [options]
       $ turnadmin [ -h	| --help]

TURNADMIN WIKI PAGE

turnutils_uclient application (for test purposes only)

It was designed to simulate multiple clients. It uses asynch IO API in libevent to handle multiple clients. A client connects to the relay, negotiates the session, and sends multiple (configured number) messages to the server (relay), expecting the same number of replies. The length of the messages is configurable. The message is an arbitrary octet stream, but it can be configured as a string. The number of the messages to send is configurable.

Usage:

       $ turnutils_uclient [-tSvsyhcxg] [options]	<TURN-Server-IP-address>

UCLIENT WIKI PAGE

turnutils_peer application (for test purposes ony)

turnutils_peer is a simple UDP-only echo backend server. This application is used for the test purposes only, as a 'peer' for the turnutils_uclient application.

Usage:

       $ turnutils_peer [-v] [options]

PEER WIKI PAGE

turnutils_stunclient is a basic STUN client

It sends a STUN request and shows the reply information.

Usage:

       $ turnutils_stunclient [options] <STUN-Server-IP-address>

STUNCLIENT WIKI PAGE

turnutils_rfc5769check tests the correctness of STUN protocol

It tests the protocol implementation against the test vectors predefined in RFC 5769 and prints the results of the tests on the screen.

Usage:

$ turnutils_rfc5769check

PROTOCOL CHECK UTILITY WIKI PAGE

LIBRARIES

In the lib/ sub-directory the build process will create TURN client messaging library. In the include/ sub-directory, the necessary include files will be placed. 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.

DOCS

In the original archive tree, the command:

$ man -M man turnserver

will give you the man page.

After the proper installation, the command:

$ man turnserver

will give you the same man page.

In the docs/html subdirectory of the original archive tree, you will find the client library reference. After the installation, it will be placed in PREFIX/share/doc/turnserver/html.

LOGS

When the TURN Server starts, it makes efforts to create a log file turnserver_<pid>.log in the following directories:

/var/log
/log/
/var/tmp
/tmp
current directory

If all efforts failed (due to the system permission settings) then all log messages are sent only to the standard output of the process.

This behavior can be controlled by --log-file and --no-stdout-log options (see turnserver help).

CLUSTERS

TURN Server can be a part of the cluster installation. But, to support the "even port" functionality (RTP/RTCP streams pairs) the client requests from a particular IP must be delivered to the same TURN Server instance, so it requires some networking setup massaging for the cluster. The reason is that the RTP and RTCP relaying endpoints must be allocated on the same relay IP. It would be possible to design a scheme with the application-level requests forwarding (and we may do that later) but it would affect the performance.