Provided by: coturn_4.5.0.7-1ubuntu2.18.04.3_amd64 bug

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>  | --mongo-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, --db, --userdb
              SQLite    user    database    file    name    (default    -    /var/db/turndb    or
              /usr/local/var/db/turndb or /var/lib/turn/turndb).

       -e, --psql-userdb
              User database connection string for PostgreSQL.  This  database  can  be  used  for
              long-term credentials mechanism, 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  credentials  mechanism,  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> read_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.

              Optional connection string parameters for  the  secure  communications  (SSL):  ca,
              capath,               cert,              key,              cipher              (see
              http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html  for  the  command  options
              description).

       -J, --mongo-userdb
              User  database  connection  string  for  MongoDB.   This  database  can be used for
              long-term credentials mechanism, and it can store the secret value for secret-based
              timed authentication in TURN RESP API.  The connection string format is like that:

              "mongodb://username:password@host:port/database?options"

              See the INSTALL file for more explanations and examples.

              Also, see http://docs.mongodb.org/manual/ for full MongoDB documentation.

       -N, --redis-userdb
              User database connection string for Redis.  This database can be used for long-term
              credentials mechanism, 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.

       --prod Production mode: hide the software version.

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

       -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  ->  "timestamp:username",  turn
              user  ->  usercombo,  turn  password -> base64(hmac(input_buffer = usercombo, key =
              shared-secret)).  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.

       --oauth
              Support oAuth authentication, as in the third-party STUN/TURN RFC 7635.

       --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-tlsv1
              Do not allow TLSv1/DTLSv1 protocol.

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

       --no-tlsv1_2
              Do not allow TLSv1.2/DTLSv1.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.

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

       --simple-log
              This flag means that no log file rollover will be used, and the log file name  will
              be constructed as-is, without PID and date appendage.  This option can be used, for
              example, together with the logrotate tool.

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

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

       --check-origin-consistency
              The flag that sets the origin consistency check: across the session,  all  requests
              must have the same main ORIGIN attribute value (if the ORIGIN was initially used by
              the session).

       -h     Help.

       Options with values:

       --stale-nonce[=<value>]
              Use extra security with nonce value having limited lifetime,  in  seconds  (default
              600 secs).

       --max-allocate-lifetime
              Set the maximum value for the allocation lifetime.  Default to 3600 secs.

       --channel-lifetime
              Set  the lifetime for channel binding, default to 600 secs.  This value MUST not be
              changed for production purposes.

       --permission-lifetime
              Set the value for the lifetime of the permission.  Default to 300 secs.  This  MUST
              not be changed for production purposes.

       -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.  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 the relay threads to handle the established connections (in  addition  to
              authentication  thread  and  the  listener  thread).   If  explicitly 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). If
              not set, then a default optimal algorithm will be employed (OS-dependent).  In  the
              older  Linux 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 be 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 user realm, and the user password.  This setting may not be used
              with TURN REST API.

       -r, --realm
              The  default  realm  to  be  used  for  the  users  when  no  explicit origin/realm
              relationship was found in the database, or if the TURN  server  is  not  using  any
              database  (just  the commands-line settings and the userdb file). Must be used with
              long-term credentials mechanism or with TURN REST API.

       -C, --rest-api-separator
              This is the timestamp/username 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. This
              option can also be set through the database, for a particular realm.

       -Q, --total-quota
              Total allocations quota: global limit on concurrent allocations.  This  option  can
              also be set through the database, for a particular realm.

       -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). This option
              can also be set through the database, for a particular realm.

       -B, --bps-capacity
              Maximum server capacity.  Total  bytes-per-second  bandwidth  the  TURN  server  is
              allowed  to  allocate  for the sessions, combined (input and output network streams
              are treated separately).

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

       --server-name
              Server name used for the oAuth authentication purposes.  The default value  is  the
              realm name.

       --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, if pre-OpenSSL 1.0.2 is used. With OpenSSL 1.0.2+,  an
              optimal curve will be automatically calculated, if not defined by this option.

       --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.  In the runtime, the logfile can be  reset  with  the  SIGHUP  signal  to  the
              turnserver process.

       --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 SQLite or MySQL or
              MongoDB 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).  For the security reasons,  it
              is recommended to use the encrypted form of the password (see the -P command in the
              turnadmin utility). The dollar signs in the encrypted form must be escaped.

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

       https://github.com/coturn/coturn/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. With -a  option,
           do  not  forget to set the default 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) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to
               set keys with turnadmin utility (see docs and wiki for turnadmin).
               You cannot use open passwords in the database.

               c) Redis key/value pair(s), if Redis is used. You key use either keys or
               open passwords with Redis; see turndb/testredisdbsetup.sh file.

               d) 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.
       Optionally,  the  user must supply the ORIGIN value, so that the server can figure out the
       realm to be used for the user. 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="timestamp" + ":" + "username"

       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
       https://github.com/coturn/coturn/.

       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.  Optionally,  it
                 adds the ORIGIN field to it.

              •  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. If the ORIGIN field was  present  in  the
                 client  request,  it  may affect the realm value that the server chooses for the
                 client.

              •  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 stored in SQLite DB. The default SQLite database file is /var/db/turndb
           or /usr/local/var/db/turndb or /var/lib/turn/turndb.

       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). See the file turndb/testsqldbsetup.sql as an example.

       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.  See the file turndb/testredisdbsetup.sh as an example.

       6)  If  a  database  is  used, then users can be divided into multiple independent realms.
           Each realm can be administered separately, and each realm can  have  its  own  set  of
           users and its own performance options (max-bps, user-quota, total-quota).

       7)  If you use MongoDB, the database will be setup for you automatically.

       8)  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). If you are
       using SQLite, then the turnserver or turnadmin will initialize  the  empty  database,  for
       you,  when  started.  The  TURN  server  installation process creates an empty initialized
       SQLite database in the default location  (/var/db/turndb  or  /usr/local/var/db/turndb  or
       /var/lib/turn/turndb, depending on the system).

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

ALPN

       The server supports ALPNs "stun.turn" and "stun.nat-discovery", when compiled with OpenSSL
       1.0.2 or newer. If the server receives a TLS/DTLS ClientHello message that contains one or
       both  of those ALPNs, then the server chooses the first stun.* label and sends it back (in
       the ServerHello) in the ALPN extension field. If no stun.* label is found, then the server
       does not include the ALPN information into the ServerHello.

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

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.

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

HTTPS MANAGEMENT INTERFACE

       The turnserver process provides an HTTPS Web access as  statistics  and  basic  management
       interface. The turnserver listens to incoming HTTPS admin connections on the same ports as
       the main TURN/STUN listener. The Web admin pages are basic and self-explanatory.

       To make the HTTPS interface active, the database table admin_user must be  populated  with
       the  admin  user  account(s).  An  admin  user  can  be  a superuser (if not assigned to a
       particular realm) or a restricted user (if assigned to  a  realm).  The  restricted  admin
       users can perform only limited actions, within their corresponding realms.

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

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

       /var/db/turndb

       /usr/local/var/db/turndb

       /var/lib/turn/turndb

       /usr/local/etc/turnserver.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:

       https://github.com/coturn/coturn/

       Wiki page:

       https://github.com/coturn/coturn/wiki

       forum:

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

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

   AUTHORS
       Oleg Moskalenko <mom040267@gmail.com>

       Gabor Kovesdan http://kovesdan.org/

       Daniel Pocock http://danielpocock.com/

       John Selbie (jselbie@gmail.com)

       Lee Sylvester <lee@designrealm.co.uk>

       Erik Johnston <erikj@openmarket.com>

       Roman Lisagor <roman@demonware.net>

       Vladimir Tsanev <tsachev@gmail.com>

       Po-sheng Lin <personlin118@gmail.com>

       Peter Dunkley <peter.dunkley@acision.com>

       Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>

       Federico Pinna <fpinna@vivocha.com>

       Bradley T. Hughes <bradleythughes@fastmail.fm>

       Mihaly Meszaros <bakfitty@gmail.com>

                                        29 September 2017                                 TURN(1)