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:

1.	turnserver: TURN Server relay. 
The compiled binary image of the TURN Server program is located in bin/ sub-directory.

2.	turnadmin: TURN administration tool. See README.turnadmin and turnadmin man page.
  
3.	turnutils_uclient. See README.turnutils and turnutils man page.

4.	turnutils_peer. See README.turnutils and turnutils man page.
   
5.	turnutils_stunclient. See README.turnutils and turnutils man page.
  
6.	turnutils_rfc5769check. See README.turnutils and turnutils man page.

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

$ cd examples
$ ./scripts/secure_relay.sh
  
RUNNING THE TURN SERVER

Options note: turnserver has long and short option names, for most options.
Some options have only long form, some options have only short form. Their syntax 
somewhat different, if an argument is required:

The short form must be used as this (for example):

  $ turnserver -L 12.34.56.78
  
The long form equivalent must use the "=" character:

  $ turnserver --listening-ip=12.34.56.78
  
If this is a flag option (no argument required) then their usage are the same, for example:

 $ turnserver -a
 
is equivalent to:

 $ turnserver --lt-cred-mech
  
=====================================

  NAME
  
turnserver - a TURN relay server implementation.
  
  SYNOPSIS
  
$ turnserver [-n | -c <config-file> ] [flags] [ --userdb=<userdb-file> | --psql-userdb=<db-conn-string> | --mysql-userdb=<db-conn-string>  | --redis-userdb=<db-conn-string> ] [-z | --no-auth | -a | --lt-cred-mech ] [options]
$ turnserver -h
  
  DESCRIPTION						
  
Config file settings:  

-n		Do not use configuration file, use only command line parameters.

-c		Configuration file name (default - turnserver.conf).
		The format of config file can be seen in
		the supplied examples/etc/turnserver.conf example file. Long 
		names of the options are used as the configuration 
		items names in the file. If not an absolute path is supplied, 
		then the file is searched in the following directories: 
		  * current directory
		  * current directory etc/ sub-directory
		  * upper directory level etc/
		  * /etc/ 
		  * /usr/local/etc/
		  * installation directory /etc

User database settings:  

-b, --userdb	User database file name (default - turnuserdb.conf),
		for long-term credentials mechanism only.
		This user file database is being dynamically checked while the turnserver 
		is working, and the user accounts can be changed dynamically by
		editing the database.
				  
-e, --psql-userdb	User database connection string for PostgreSQL.
		This database can be used for long-term and short-term credentials mechanisms,
		and it can store the secret value for secret-based timed authentication in TURN RESP API.
		The connection string format is like that:
		 
		"host=<host> dbname=<dbname> user=<db-user> password=<db-user-password> connect_timeout=<seconds>" 
		(for 8.x or newer Postgres).
		
		Or:
		
		"postgresql://username:password@hostname:port/databasename" (for 9.x or newer Postgres). 
		See the INSTALL file for more explanations and examples.
		
		Also, see http://www.PostgreSQL.org for full PostgreSQL documentation.
				  
-M, --mysql-userdb	User database connection string for MySQL. 
		This database can be used for long-term and short-term credentials mechanisms,
		and it can store the secret value for secret-based timed authentication in TURN RESP API.
		The connection string format is like that:
		 
		"host=<host> dbname=<dbname> user=<db-user> password=<db-user-password> connect_timeout=<seconds>"
		See the INSTALL file for more explanations and examples.
		
		Also, see http://www.mysql.org for full MySQL documentation.
		
-N, --redis-userdb	User database connection string for Redis. 
		This database can be used for long-term and short-term credentials mechanisms,
		and it can store the secret value for secret-based timed authentication in TURN RESP API.
		The connection string format is like that:
		 
		"ip=<ip-addr> dbname=<db-number> password=<db-password> connect_timeout=<seconds>"
		See the INSTALL file for more explanations and examples.
		
		Also, see http://redis.io for full Redis documentation.

Flags:   

-v, --verbose		Moderate verbose mode.

-V, --Verbose		Extra verbose mode, very annoying and not recommended.

-o, --daemon		Run server as daemon.

-f, --fingerprint	Use fingerprints in the TURN messages. If an incoming request
			contains a fingerprint, then TURN server will always add 
			fingerprints to the messages in this session, regardless of the
			per-server setting.

-a, --lt-cred-mech	Use long-term credentials mechanism (this one you need for WebRTC usage). 
			This option can be used with either flat file user database or 
			PostgreSQL DB or MySQL DB or Redis for user keys storage.
-A, --st-cred-mech	Use the short-term credentials mechanism. This option requires
	                a PostgreSQL or MySQL or Redis DB for short term passwords storage.

-z, --no-auth		Do not use any credentials mechanism, allow anonymous access. 
			Opposite to -a and -A options. This is default option when no 
			authentication-related options are set.
			By default, no credential mechanism is used -
			any user is allowed.

--use-auth-secret	Flag that sets a special WebRTC authorization option 
			that is based upon authentication secret. The feature purpose 
			is to support "TURN Server REST API" as described in
			the TURN REST API section below.
			This option uses timestamp as part of combined username:
			usercombo -> "user_id:timestamp",
			turn user -> usercombo,
			turn password -> base64(hmac(secret key, usercombo)).
			This allows TURN credentials to be accounted for a specific user id.
			If you don't have a suitable id, the timestamp alone can be used.
			This option is just turns on secret-based authentication.
			The actual value of the secret is defined either by option static-auth-secret,
			or can be found in the turn_secret table in the database.
			This option can be used with long-term credentials mechanisms only -
			it does not make much sense with the short-term mechanism.

--no-udp		Do not start UDP client listeners.

--no-tcp		Do not start TCP client listeners.

--no-tls		Do not start TLS client listeners.

--no-dtls		Do not start DTLS client listeners.

--no-udp-relay		Do not allow UDP relay endpoints defined in RFC 5766, 
use only TCP relay endpoints as defined in RFC 6062.

--no-tcp-relay		Do not allow TCP relay endpoints defined in RFC 6062, 
use only UDP relay endpoints as defined in RFC 5766. 

--stale-nonce		Use extra security with nonce value having limited lifetime (600 secs). 

--no-stdout-log		Flag to prevent stdout log messages.
			By default, all log messages are going to both stdout and to
			the configured log file. With this option everything will be going to 
			the log file only (unless the log file itself is stdout).
			
--syslog		With this flag, all log will be redirected to the system log (syslog).

-S, --stun-only		Run as STUN server only, all TURN requests will be ignored.

--no-loopback-peers	Disallow peers on the loopback addresses (127.x.x.x and ::1).

--no-multicast-peers	Disallow peers on well-known broadcast addresses (224.0.0.0 and above, and FFXX:*). 

-h			Help.
    
Options with required values:  

-d, --listening-device		Listener interface device (optional functionality, Linux only). 
				The turnserver process must have root privileges to bind the 
				listening endpoint to a device. If turnserver must run as a 
				process without root privileges, then just do not use this setting.

-L, --listening-ip		Listener IP address of relay server. 
				Multiple listeners can be specified:
				-L ip1 -L ip2 -L ip3
				If no IP(s) specified, then all IPv4 and 
				IPv6 system IPs will be used for listening.
				The same ip(s) can be used as both listening and relay ip(s).

-p, --listening-port		TURN listener port for UDP and TCP listeners (Default: 3478).
				Note: actually, TLS & DTLS sessions can connect to the "plain" TCP & UDP
				port(s), too - if allowed by configuration. 				

--tls-listening-port		TURN listener port for TLS and DTLS listeners (Default: 5349).
				Note: actually, "plain" TCP & UDP sessions can connect to the TLS & DTLS
				port(s), too - if allowed by configuration. The TURN server 
				"automatically" recognizes the type of traffic. Actually, two listening
				endpoints (the "plain" one and the "tls" one) are equivalent in terms of
				functionality; but we keep both endpoints to satisfy the RFC 5766 specs.
				For secure TCP connections, we currently support SSL version 3 and 
				TLS versions 1.0, 1.1, 1.2. SSL2 "encapsulation mode" is also supported.
				For secure UDP connections, we support DTLS version 1.

--alt-listening-port		Alternative listening port for UDP and TCP listeners;
				default (or zero) value means "listening port plus one". 
				This is needed for STUN CHANGE_REQUEST  - in RFC 5780 sense
                or in old RFC 3489 sense - for NAT behavior discovery). The TURN Server 
				supports CHANGE_REQUEST only if it is started with more than one 
				listening IP address of the same family (IPv4 or IPv6). The CHANGE_REQUEST
				is only supported by UDP protocol, other protocols are listening
				on that endpoint only for "symmetry".
							 
--alt-tls-listening-port	Alternative listening port for TLS and DTLS protocols.
				Default (or zero) value means "TLS listening port plus one".
				
--aux-server	Auxiliary STUN/TURN server listening endpoint.
				Aux servers have almost full TURN and STUN functionality.
				The (minor) limitations are:
					1) Auxiliary servers do not have alternative ports and
					they do not support STUN RFC 5780 functionality (CHANGE REQUEST).
					2) Auxiliary servers also are never returning ALTERNATIVE-SERVER reply.
					
				Valid formats are 1.2.3.4:5555 for IPv4 and [1:2::3:4]:5555 for IPv6.
				There may be multiple aux-server options, each will be used for listening
				to client requests.
				
--udp-self-balance	Automatically balance UDP traffic over auxiliary servers (if configured).
					The load balancing is happening by the ALTERNATE-SERVER mechanism.
					The TURN client must support 300 ALTERNATE-SERVER response for this 
					functionality.

-i, --relay-device		Relay interface device for relay sockets 
				(optional, Linux only).

-E, --relay-ip			Relay address (the local IP address that 
				will be used to relay the packets to the 
				peer). Multiple relay addresses may be used:
				-E ip1 -E ip2 -E ip3
				If no relay IP(s) specified, then all 
				non-loopback system IPs will be used.
				The same ip(s) can be used as both listening and relay ip(s).

-X, --external-ip		TURN Server public/private address mapping, if the server is behind NAT.
				In that situation, if a -X is used in form "-X <ip>" then that ip will be reported
				as relay IP address of all allocations. This scenario works only in a simple case
				when one single relay address is be used, and no CHANGE_REQUEST functionality is 
				required. That single relay address must be mapped by NAT to the 'external' IP.
				The "external-ip" value, if not empty, is returned in XOR-RELAYED-ADDRESS field.
				For that 'external' IP, NAT must forward ports directly (relayed port 12345
				must be always mapped to the same 'external' port 12345).
				In more complex case when more than one IP address is involved,
				that option must be used several times, each entry must
				have form "-X <public-ip/private-ip>", to map all involved addresses.
				CHANGE_REQUEST (RFC5780 or RFC3489) NAT discovery STUN functionality will work 
				correctly, if the addresses are mapped properly, even when the TURN server itself 
				is behind A NAT.
				By default, this value is empty, and no address mapping is used.
				
-m, --relay-threads		Number of non-UDP relay threads to handle the established connections
				(in addition to authentication thread and the listener thread).
				If set to 0 then application runs TCP/TLS/DTLS relay process in a single thread,
				in the same thread with the listener process (the authentication thread will 
				still be a separate thread).
				The number of UDP threads is always one per network listening endpoint - including
				the auxiliary endpoints.

--min-port			Lower bound of the UDP port range for relay 
				endpoints allocation.
				Default value is 49152, according to RFC 5766.

--max-port			Upper bound of the UDP port range for relay 
				endpoints allocation.
				Default value is 65535, according to RFC 5766.

-u, --user			Long-term credentials user account, in the column-separated 
				form username:key. 
				Multiple user accounts may used in the command line.
				The key is either the user password, or
				the key is generated
				by turnadmin command. In the second case,
				the key must be prepended with 0x symbols.
				The key is calculated over the user name, 
				the realm, and the user password.

-r, --realm			Realm to be used for all users, with long-term credentials only

-q, --user-quota		Per-user allocations quota: how many concurrent 
				allocations a user can create.

-Q, --total-quota		Total allocations quota: global limit on concurrent allocations.

--static-auth-secret		Static authentication secret value (a string).
				If not set, then the turn server will try to use the dynamic value 
				in turn_secret table in user database (if present). The database-stored
				value can be changed on-the-fly by a separate program, so this is why 
				that other mode is dynamic.
				Multiple shared secrets can be used (both in the database and in the "static" fashion).

-s, --max-bps			Max bytes-per-second bandwidth a TURN session is allowed to handle
				(input and output network streams combined). Anything above that limit
				will be dropped.

--cert				Certificate file, PEM format. Same file 
				search rules applied as for the configuration 
				file. If both --no-tls and --no-dtls options 
				are specified, then this parameter is not needed.
				Default value is turn_server_cert.pem.

--pkey		     		Private key file, PEM format. Same file 
				search rules applied as for the configuration 
				file. If both --no-tls and --no-dtls options 
				are specified, then this parameter is not needed.
				Default value is turn_server_pkey.pem.
				
-l, --log-file			Option to set the full path name of the log file.
				By default, the turnserver tries to open a log file in 
				/var/log/turnserver, /var/log, /var/tmp, /tmp and . (current) 
				directories (which file open operation succeeds 
				first that file will be used). With this option you can set the 
				definite log file name.
				The special names are "stdout" and "-" - they will force everything 
				to the stdout. Also, "syslog" name will redirect everything into
				the system log (syslog), as if the option "--syslog" was set.
				
--alternate-server		Option to set the "redirection" mode. The value of this option
				will be the address of the alternate server for UDP & TCP service in form of 
				<ip>[:<port>]. The server will send this value in the attribute
				ALTERNATE-SERVER, with error 300, on ALLOCATE request, to the client.
				Client will receive only values with the same address family
				as the client network endpoint address family. 
				See RFC 5389 and RFC 5766 for ALTERNATE-SERVER functionality description. 
				The client must use the obtained value for subsequent TURN communications.
				If more than one --alternate-server options are provided, then the functionality
				can be more accurately described as "load-balancing" than a mere "redirection". 
				If the port number is omitted, then the default port 
				number 3478 for the UDP/TCP protocols will be used.
				Colon (:) characters in IPv6 addresses may conflict with the syntax of 
				the option. To alleviate this conflict, literal IPv6 addresses are enclosed 
				in square brackets in such resource identifiers, for example: 
				[2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 . 
				Multiple alternate servers can be set. They will be used in the
				round-robin manner. All servers in the pool are considered of equal weight and 
				the load will be distributed equally. For example, if we have 4 alternate servers, 
				then each server will receive 25% of ALLOCATE requests. An alternate TURN server 
				address can be used more than one time with the alternate-server option, so this 
				can emulate "weighting" of the servers. 

--tls-alternate-server		Option to set alternative server for TLS & DTLS services in form of 
				<ip>:<port>. If the port number is omitted, then the default port 
				number 5349 for the TLS/DTLS protocols will be used. See the previous option for the 
				functionality description.

-C, --rest-api-separator	This is the username/timestamp separator symbol (character) in TURN REST API.
				The default value is :.

-O, --redis-statsdb	Redis status and statistics database connection string, if used (default - empty, 
				no Redis stats DB used). This database keeps allocations status information, and it can 
				be also used for publishing and delivering traffic and allocation event notifications.
				This database option can be used independently of --redis-userdb option,
				and actually Redis can be used for status/statistics and MySQL or PostgreSQL can
				be used for the user database.
				The connection string has the same parameters as redis-userdb connection string.

--max-allocate-timeout	Max time, in seconds, allowed for full allocation establishment. 
				Default is 60 seconds.
				
--denied-peer-ip=<IPaddr[-IPaddr]>

--allowed-peer-ip=<IPaddr[-IPaddr]> Options to ban or allow specific ip addresses or ranges of ip addresses. 
				If an ip address is specified as both allowed and denied, then the ip address is 
				considered to be allowed. This is useful when you wish to ban a range of ip 
				addresses, except for a few specific ips within that range.
				This can be used when you do not want users of the turn server to be able to access
				machines reachable by the turn server, but would otherwise be unreachable from the 
				internet (e.g. when the turn server is sitting behind a NAT). The 'white" and "black" peer 
				IP ranges can also be dynamically changed in the database.

--cipher-list	Allowed OpenSSL cipher list for TLS/DTLS connections.
				Default value is "ALL:eNULL:aNULL:NULL".
				
--pidfile 		File name to store the pid of the process.
				Default is /var/run/turnserver.pid (if superuser account is used) or
				/var/tmp/turnserver.pid .
				
--secure-stun	Require authentication of the STUN Binding request.
				By default, the clients are allowed anonymous access to the STUN Binding functionality.
		
==================================

LOAD BALANCE

To set a load balancing scheme, you have three options:

	a) Set a complex networking load-balancing equipment that redirects 
	the requests to a member of the TURN servers group. It must take care 
	about redirecting the requests to the same server from the same client - 
	because some TURN sessions from the same client must share the information.
	
	b) Set a less complex scheme with round-robin DNS. The client must send all 
	its requests to the same DNS-discovered TURN server.
	
	c) Use build-in balancing capability with ALTERNATE-SERVER option 
	(--alternate-server options). In this case, the client must also send all 
	requests to the same alternate-server address.
	 
===================================

WEBRTC USAGE

This is a set of notes for the WebRTC users:

1) WebRTC uses long-term authentication mechanism, so you have to use -a option (or --lt-cred-mech).
WebRTC relaying will not work with anonymous access or with short-term authentication.
With -a option, do not forget to set the realm (-r option). You will also have to set up
the user accounts, for that you have a number of options:

	a) command-line options (-u).
	
	b) userdb config file.
	
	c) a database table (PostgreSQL or MySQL). You will have to set keys with 
	turnadmin utility (see docs and wiki for turnadmin). You cannot use open passwords 
	in the database.

	d) Redis key/value pair(s), if Redis is used. You key use either keys or 
	open passwords with Redis; see turndb/testredisdbsetup.sh file.  
	
	e) You also can use the TURN REST API. You will need shared secret(s) set
	either	through the command line option, or through the config file, or through
	the database table or Redis key/value pairs.  

2) Usually WebRTC uses fingerprinting (-f).

3) -v option may be nice to see the connected clients.

4) -X is needed if you are running your TURN server behind a NAT.

5) --min-port and --max-port may be needed if you want to limit the relay endpoints ports 
number range.

===================================

TURN REST API

In WebRTC, the browser obtains the TURN connection information from the web
server. This information is a secure information - because it contains the 
necessary TURN credentials. As these credentials are transmitted over the 
public networks, we have a potential security breach.

If we have to transmit a valuable information over the public network, 
then this information has to have a limited lifetime. Then the guy who 
obtains this information without permission will be able to perform 
only limited damage.

This is how the idea of TURN REST API - time-limited TURN credentials - 
appeared. This security mechanism is based upon the long-term credentials 
mechanism. The main idea of the REST API is that the web server provides 
the credentials to the client, but those credentials can be used only 
limited time by an application that has to create a TURN server connection.

The "classic" long-term credentials mechanism (LTCM) is described here:

http://tools.ietf.org/html/rfc5389#section-10.2
http://tools.ietf.org/html/rfc5389#section-15.4

For authentication, each user must know two things: the username and the 
password. The nonce and the realm values are supplied by the TURN server. 
But LTCM is not saying anything about the nature and about the persistence 
of the username and of the password; and this is used by the REST API.

In the TURN REST API, there is no persistent passwords for users. A user has 
just the username. The password is always temporary, and it is generated by 
the web server on-demand, when the user accesses the WebRTC page. And, 
actually, a temporary one-time session only, username is provided to the user, 
too. 

The temporary user is generated as:

temporary-username="username" + ":" + "timestamp"

where username is the persistent user name, and the timestamp format is just 
seconds sinse 1970 - the same value as time(NULL) function returns.

The temporary password is obtained as HMAC-SHA1 function over the temporary
username, with shared secret as the HMAC key, and then the result is encoded:

temporary-password = base64_encode(hmac-sha1(shared-secret, temporary-username))

Both the TURN server and the web server know the same shared secret. How the
shared secret is distributed among the involved entities is left to the WebRTC
deployment details - this is beyond the scope of the TURN REST API.

So, a timestamp is used for the temporary password calculation, and this 
timestamp can be retrieved from the temporary username. This information
is valuable, but only temporary, while the timestamp is not expired. Without
knowledge of the shared secret, a new temporary password cannot be generated.

This is all formally described in Justin's Uberti TURN REST API document
that can be obtained following the link "TURN REST API" in the TURN Server
project's page http://code.google.com/p/rfc5766-turn-server/.

Once the temporary username and password are obtained by the client (browser)
application, then the rest is just 'classic" long-term credentials mechanism.
For developers, we are going to describe it step-by-step below:

  - a new TURN client sends a request command to the TURN server.
  - TURN server sees that this is a new client and the message is not 
  	authenticated.
  - the TURN server generates a random nonce string, and return the 
  	error 401 to the client, with nonce and realm included.
  - the client sees the 401 error and it extracts two values from 
  	the error response: the nonce and the realm.
  - the client uses username, realm and password to produce a key:

         key = MD5(username ":" realm ":" SASLprep(password))
 (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
 
  - the client forms a new request, adds username, realm and nonce to the 
  	request. Then, the client calculates and adds the integrity field to 
  	the request. This is the trickiest part of the process, and it is
  	 described in the end of section 15.4: 
  	http://tools.ietf.org/html/rfc5389#section-15.4
  - the client, optionally, adds the fingerprint field. This may be also 
  	a tricky procedure, described in section 15.5 of the same document. 
  	WebRTC usually uses fingerprinted TURN messages.
  - the TURN server receives the request, reads the username.
  - then the TURN server checks that the nonce and the realm in the request 
  	are the valid ones.
  - then the TURN server calculates the key.
  - then the TURN server calculates the integrity field.
  - then the TURN server compares the calculated integrity field with the 
  	received one - they must be the same. If the integrity fields differ, 
  	then the request is rejected.

In subsequent communications, the client may go with exactly the same 
sequence, but for optimization usually the client, having already 
information about realm and nonce, pre-calculates the integrity string 
for each request, so that the 401 error response becomes unnecessary. 
The TURN server may use "--stale-nonce" option for extra security: in 
some time, the nonce expires and the client will obtain 438 error response
with the new nonce, and the client will have to start using the new nonce.

In subsequent communications, the sever and the client will always assume 
the same password - the original password becomes the session parameter and 
is never expiring. So the password is not changing while the session is valid
and unexpired. So, if the session is properly maintained, it may go forever, 
even if the user password has been already changed (in the database). The 
session simply is using the old password. Once the session got disconnected, 
the client will have to use the new password to re-connect (if the password 
has been changed).

An example when a new shared secret is generated every hour by the TURN server
box and then supplied to the web server, remotely, is provided in the script
examples/scripts/restapi/shared_secret_maintainer.pl .

A very important thing is that the nonce must be totally random and it must be 
different for different clients and different sessions. 
	 
===================================

DATABASES

For the user database, the turnserver has the following options:

1) Users can be set in the command line, with multiple -u or --user options. 
Obviously, only a few users can be set that way, and their credentials are fixed 
for the turnserver process lifetime.

2) Users can be set in turnusers.conf flat file DB. The turnserver process periodically 
re-reads this file, so the user accounts may be changed while the turnserver is running.
But still a relatively small (up to a hundred ?) number of users can be handled that way.

3) Users can be stored in PostgreSQL database, if the turnserver was compiled with PostgreSQL
support. Each time turnserver checks user credentials, it reads the database (asynchronously,
of course, so that the current flow of packets is not delayed in any way), so any change in the 
database content is immediately visible by the turnserver. This is the way if you need the 
best scalability. The schema for the database can be found in schema.sql file.
For long-term credentials, you have to set the "keys" for the users; the "keys" are generated 
by the turnadmin utility. For the key generation, you need username, password and the realm. 
All users in the database must use the same realm value; if down the road you will decide 
to change the realm name, then you will have to re-generate all user keys (that can be done 
in a batch script). If you are using short-term credentials, then you use open passwords 
in the database; you will have to make sure that nobody can access the database outside of 
the TURN server box. 

4) The same is true for MySQL database. The same schema file is applicable. 
The same considerations are applicable. 

5) The same is true for the Redis database, but the Redis database has aa different schema -
it can be found (in the form of explanation) in schema.userdb.redis. 
Also, in Redis you can store both "keys" and open passwords (for long term credentials) - 
the "open password" option is less secure but more convenient for low-security environments. 
For short-term credentials, you will use open passwords only. See the file 
turndb/testredisdbsetup.sh as an example. 

6) Of course, the turnserver can be used in non-secure mode, when users are allowed to establish
sessions anonymously. But in most cases (like WebRTC) that will not work.

For the status and statistics database, there are two choices:

1) The simplest choice is not to use it. Do not set --redis-statsdb option, and this functionality 
will be simply ignored.

2) If you choose to use it, then set the --redis-statsdb option. This may be the same database
as in --redis-userdb option, or it may be a different database. You may want to use different 
database for security or convenience reasons. Also, you can use different database management
systems for the user database and for the ststus and statistics database. For example, you can use 
MySQL as the user database, and you can use redis for the statistics. Or you can use Redis for both.

So, we have 6 choices for the user management, and 2 choices for the statistics management. These
two are totally independent. So, you have overall 6*2=12 ways to handle persistent information, 
choose any for your convenience.

You do not have to handle the database information "manually" - the turnadmin program can handle 
everything for you. For PostgreSQL and MySQL you will just have to create an empty database
with schema.sql SQL script. With Redis, you do not have to do even that - just run turnadmin and 
it will set the users for you (see the turnadmin manuals).
    
=================================

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

After installation, run the command:

$ man turnserver

or in the project root directory:

$ man -M man turnserver

to see the 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 turn_<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, --syslog and --no-stdout-log options.

=================================

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.

=================================

FILES

/etc/turnserver.conf

/etc/turnuserdb.conf

/usr/local/etc/turnserver.conf

/usr/local/etc/turnuserdb.conf

=================================

DIRECTORIES

/usr/local/share/turnserver

/usr/local/share/doc/turnserver

/usr/local/share/examples/turnserver

=================================

STANDARDS

obsolete STUN RFC 3489

new STUN RFC 5389

TURN RFC 5766

TURN-TCP extension RFC 6062
 
TURN IPv6 extension RFC 6156

STUN/TURN test vectors RFC 5769

STUN NAT behavior discovery RFC 5780

=================================

SEE ALSO

	turnadmin, turnutils

======================================

  WEB RESOURCES

	project page:

	http://code.google.com/p/rfc5766-turn-server/

	Wiki page:

	http://code.google.com/p/rfc5766-turn-server/wiki/Readme

	forum:

	https://groups.google.com/forum/?fromgroups=#!forum/turn-server-project-rfc5766-turn-server/

======================================

  AUTHORS

	Oleg Moskalenko <[email protected]>

	Gabor Kovesdan http://kovesdan.org/

	Daniel Pocock http://danielpocock.com/

	John Selbie ([email protected])

	Lee Sylvester <[email protected]>

	Erik Johnston <[email protected]>

	Roman Lisagor <[email protected]>
	
	Vladimir Tsanev <[email protected]>
	
	Po-sheng Lin <[email protected]>