Ubuntu Manpage: The TURN Server project contains the source code of a TURN server and TURN client

Provided by: rfc5766-turn-server_3.2.3.1-1_amd64

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.

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 or MariaDB. 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 or http://mariadb.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
TURN REST API flag. 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.

--dh566
Use 566 bits predefined DH TLS key. Default size of the key is 1066.

--dh2066
Use 2066 bits predefined DH TLS key. Default size of the key is 1066.

--no-sslv2
Do not allow SSLv2 protocol.

--no-sslv3
Do not allow SSLv3 protocol.

--no-tlsv1
Do not allow TLSv1 protocol.

--no-tlsv1_1
Do not allow TLSv1.1 protocol.

--no-tlsv1_2
Do not allow TLSv1.2 protocol.

--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).

--secure-stun
Require authentication of the STUN Binding request. By default, the clients are
allowed anonymous access to the STUN Binding functionality.

-S, --stun-only
Run as STUN server only, all TURN requests will be ignored. Option to suppress
TURN functionality, only STUN requests will be processed.

--no-stun
Run as TURN server only, all STUN requests will be ignored. Option to suppress
STUN functionality, only TURN requests will be processed.

--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:*).

--sha256
Require SHA256 digest function to be used for the message integrity. By default,
the server uses SHA1 hashes. With this option, the server requires the stronger
SHA256 hashes. The client application must support SHA256 hash function if this
option is used. If the server obtains a message from the client with a weaker
(SHA1) hash function then the server returns error code 426.

--mobility
Mobility with ICE (MICE) specs support.

--no-cli
Turn OFF the CLI support. By default it is always ON. See also options --cli-ip
and --cli-port.

--server-relay
Server relay. NON-STANDARD AND DANGEROUS OPTION. Only for those applications when
we want to run server applications on the relay endpoints. This option eliminates
the IP permissions check on the packets incoming to the relay endpoints. See
http://tools.ietf.org/search/rfc5766#section-17.2.3 .

--udp-self-balance
(recommended for older Linuxes only) Automatically balance UDP traffic over
auxiliary servers (if configured). The load balancing is using the ALTERNATE-SERVER
mechanism. The TURN client must support 300 ALTERNATE-SERVER response for this
functionality.

-h Help.

Options with required values:

-d, --listening-device
Listener interface device. (NOT RECOMMENDED. 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, for
example: -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.

-i, --relay-device
Relay interface device for relay sockets (NOT RECOMMENDED. 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 The same IP(s)
can be used as both listening IP(s) and relay IP(s). If no relay IP(s) specified,
then the turnserver will apply the default policy: it will decide itself which
relay addresses to be used, and it will always be using the client socket IP
address as the relay IP address of the TURN session (if the requested relay address
family is the same as the family of the client socket).

-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 relay threads to handle the established connections (in addition to
authentication thread and the listener thread). If set to 0 then application runs
relay process in a single thread, in the same thread with the listener process (the
authentication thread will still be a separate thread). In older systems (before
Linux kernel 3.9), the number of UDP threads is always one threads per network
listening endpoint - unless "-m 0" or "-m 1" is set.

--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 security mechanism 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. This setting may not be used with
TURN REST API or with short-term credentials mechanism.

-r, --realm
Realm to be used for all users. Must be used with long-term credentials mechanism
or with TURN REST API.

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

-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) for TURN REST API only. 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 are treated separately). Anything above that limit will be
dropped or temporary suppressed (within the available buffer limits).

--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.

--pkey-pwd
If the private key file is encrypted, then this password to be used.

--cipher-list
Allowed OpenSSL cipher list for TLS/DTLS connections. Default value is "DEFAULT".

--CA-file
CA file in OpenSSL format. Forces TURN server to verify the client SSL
certificates. By default, no CA is set and no client certificate check is
performed.

--ec-curve-name
Curve name for EC ciphers, if supported by OpenSSL library (TLS and DTLS). The
default value is prime256v1.

--dh-file
Use custom DH TLS key, stored in PEM format in the file. Flags --dh566 and
--dh2066 are ignored when the DH key is taken from a file.

-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.

-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. The allowed/denied addresses (white/black lists) rules are very
simple:

1) If there is no rule for an address, then it is allowed;

2) If there is an "allowed" rule that fits the address then it is allowed - no
matter what;

3) If there is no "allowed" rule that fits the address, and if there is a "denied"
rule that fits the address, then it is denied.

--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 .

--proc-user
User name to run the process. After the initialization, the turnserver process will
make an attempt to change the current user ID to that user.

--proc-group
Group name to run the process. After the initialization, the turnserver process
will make an attempt to change the current group ID to that group.

--cli-ip
Local system IP address to be used for CLI management interface. The turnserver
process can be accessed for management with telnet, at this IP address and on the
CLI port (see the next parameter). Default value is 127.0.0.1. You can use telnet
or putty (in telnet mode) to access the CLI management interface.

--cli-port
CLI management interface listening port. Default is 5766.

--cli-password
CLI access password. Default is empty (no password).

--cli-max-output-sessions
Maximum number of output sessions in ps CLI command. This value can be changed
on-the-fly in CLI. The default value is 256.

--ne=[1|2|3]
Set network engine type for the process (for internal purposes).

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

LOAD BALANCE AND PERFORMANCE TUNING

       This topic is covered in the wiki page:

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

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

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.

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

TELNET CLI

       The turnserver process provides a telnet CLI access as  statistics  and  basic  management
       interface.  By  default,  the  turnserver starts a telnet CLI listener on IP 127.0.0.1 and
       port 5766. That can be changed by the command-cline options of the turnserver process (see
       --cli-ip  and  --cli-port  options).  The  full list of telnet CLI commands is provided in
       "help" command output in the telnet CLI.

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

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

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