1TURN(1)                                                                TURN(1)
2
3
4

GENERAL INFORMATION

6       The  TURN  Server project contains the source code of a TURN server and
7       TURN client messaging library. Also, some extra programs provided,  for
8       testing-only purposes.
9
10       See the INSTALL file for the building instructions.
11
12       After the build, you will have the following binary images:
13
14       1.     turnserver: TURN Server relay.  The compiled binary image of the
15              TURN Server program is located in bin/ sub-directory.
16
17       2.     turnadmin: TURN administration tool.  See  README.turnadmin  and
18              turnadmin man page.
19
20       3.     turnutils_uclient. See README.turnutils and turnutils man page.
21
22       4.     turnutils_peer. See README.turnutils and turnutils man page.
23
24       5.     turnutils_stunclient.  See  README.turnutils  and  turnutils man
25              page.
26
27       6.     turnutils_rfc5769check. See README.turnutils and  turnutils  man
28              page.
29
30       In  the "examples/scripts" sub-directory, you will find the examples of
31       command lines to be used to run the programs. The scripts are meant  to
32       be run from examples/ sub-directory, for example:
33
34       $ cd examples $ ./scripts/secure_relay.sh
35

RUNNING THE TURN SERVER

37       Options  note:  turnserver  has  long  and short option names, for most
38       options.  Some options have only long  form,  some  options  have  only
39       short  form.  Their  syntax  somewhat  different,  if  an  argument  is
40       required:
41
42       The short form must be used as this (for example):
43
44         $ turnserver -L 12.34.56.78
45
46       The long form equivalent must use the "=" character:
47
48         $ turnserver --listening-ip=12.34.56.78
49
50       If this is a flag option (no argument required) then  their  usage  are
51       the same, for example:
52
53        $ turnserver -a
54
55       is equivalent to:
56
57        $ turnserver --lt-cred-mech
58
59       =====================================
60
61   NAME
62        turnserver - a TURN relay server implementation.
63
64   SYNOPSIS
65       $ 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]
66       $ turnserver -h
67
68
69   DESCRIPTION
70       Config file settings:
71
72       -n     Do not use configuration file, use only command line parameters.
73
74       -c     Configuration file name (default - turnserver.conf).  The format
75              of  config  file   can   be   seen   in   the   supplied   exam‐
76              ples/etc/turnserver.conf example file. Long names of the options
77              are used as the configuration items names in the file. If not an
78              absolute path is supplied, then the file is searched in the fol‐
79              lowing directories:
80
81              ·  current directory
82
83              ·  current directory etc/ sub-directory
84
85              ·  upper directory level etc/
86
87              ·  /etc/
88
89              ·  /usr/local/etc/
90
91              ·  installation directory /etc
92
93       User database settings:
94
95       -b, --db, --userdb
96              SQLite user database file  name  (default  -  /var/db/turndb  or
97              /usr/local/var/db/turndb or /var/lib/turn/turndb).
98
99       -e, --psql-userdb
100              User  database  connection string for PostgreSQL.  This database
101              can be used for long-term  credentials  mechanism,  and  it  can
102              store  the secret value for secret-based timed authentication in
103              TURN RESP API.  The connection string format is like that:
104
105              "host=<host>      dbname=<dbname>      user=<db-user>      pass‐
106              word=<db-user-password>  connect_timeout=<seconds>"  (for 8.x or
107              newer Postgres).
108
109              Or:
110
111              "postgresql://username:password@hostname:port/databasename" (for
112              9.x or newer Postgres).
113
114              See the INSTALL file for more explanations and examples.
115
116              Also, see http://www.PostgreSQL.org for full PostgreSQL documen‐
117              tation.
118
119       -M, --mysql-userdb
120              User database connection string  for  MySQL  or  MariaDB.   This
121              database can be used for long-term credentials mechanism, and it
122              can store the secret value for secret-based timed authentication
123              in TURN RESP API.  The connection string format is like that:
124
125              "host=<host>      dbname=<dbname>      user=<db-user>      pass‐
126              word=<db-user-password>   connect_timeout=<seconds>   read_time‐
127              out=<seconds>"
128
129              See the INSTALL file for more explanations and examples.
130
131              Also,  see  http://www.mysql.org  or http://mariadb.org for full
132              MySQL documentation.
133
134              Optional connection string parameters for the secure  communica‐
135              tions    (SSL):    ca,    capath,   cert,   key,   cipher   (see
136              http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html for  the
137              command options description).
138
139       --secret-key-file
140              This is the file path which contain secret key of aes encryption
141              while using MySQL password encryption.  If you want  to  use  in
142              the  MySQL  connection  string the password in encrypted format,
143              then set in this option the file path of the secret key. The key
144              which  is  used  to  encrypt  MySQL  password.  Warning: If this
145              option is set, then MySQL password must be set in "mysql-userdb"
146              option  in encrypted format!  If you want to use cleartext pass‐
147              word then do not set this option!
148
149       -J, --mongo-userdb
150              User database connection string for MongoDB.  This database  can
151              be  used  for  long-term credentials mechanism, and it can store
152              the secret value for secret-based timed authentication  in  TURN
153              RESP API.  The connection string format is like that:
154
155              "mongodb://username:password@host:port/database?options"
156
157              See the INSTALL file for more explanations and examples.
158
159              Also, see http://docs.mongodb.org/manual/ for full MongoDB docu‐
160              mentation.
161
162       -N, --redis-userdb
163              User database connection string for Redis.  This database can be
164              used  for  long-term credentials mechanism, and it can store the
165              secret value for secret-based timed authentication in TURN  RESP
166              API.  The connection string format is like that:
167
168              "ip=<ip-addr>   dbname=<db-number>  password=<db-password>  con‐
169              nect_timeout=<seconds>"
170
171              See the INSTALL file for more explanations and examples.
172
173              Also, see http://redis.io for full Redis documentation.
174
175       Flags:
176
177       -v, --verbose
178              Moderate verbose mode.
179
180       -V, --Verbose
181              Extra verbose mode, very annoying and not recommended.
182
183       -o, --daemon
184              Run server as daemon.
185
186       --prod Production mode: hide the software version.
187
188       -f, --fingerprint
189              Use fingerprints in the TURN messages. If  an  incoming  request
190              contains a fingerprint, then TURN server will always add finger‐
191              prints to the  messages  in  this  session,  regardless  of  the
192              per-server setting.
193
194       -a, --lt-cred-mech
195              Use  long-term  credentials  mechanism  (this  one  you need for
196              WebRTC usage).
197
198       -z, --no-auth
199              Do not use any credentials mechanism,  allow  anonymous  access.
200              Opposite  to  -a  and -A options. This is default option when no
201              authentication-related options are set.  By default, no  creden‐
202              tial mechanism is used - any user is allowed.
203
204       --use-auth-secret
205              TURN  REST API flag.  Flag that sets a special WebRTC authoriza‐
206              tion option that is based upon authentication secret.  The  fea‐
207              ture  purpose  is to support "TURN Server REST API" as described
208              in the TURN REST API section below.  This option uses  timestamp
209              as part of combined username: usercombo -> "timestamp:username",
210              turn user -> usercombo, turn password ->  base64(hmac(input_buf‐
211              fer  =  usercombo, key = shared-secret)).  This allows TURN cre‐
212              dentials to be accounted for a specific user id.  If  you  don't
213              have  a  suitable  id,  the  timestamp  alone can be used.  This
214              option is just turns on secret-based authentication.  The actual
215              value    of   the   secret   is   defined   either   by   option
216              static-auth-secret, or can be found in the turn_secret table  in
217              the database.
218
219       --oauth
220              Support  oAuth  authentication,  as in the third-party STUN/TURN
221              RFC 7635.
222
223       --dh566
224              Use 566 bits predefined DH TLS key. Default size of the  key  is
225              1066.
226
227       --dh2066
228              Use  2066 bits predefined DH TLS key. Default size of the key is
229              1066.
230
231       --no-tlsv1
232              Do not allow TLSv1/DTLSv1 protocol.
233
234       --no-tlsv1_1
235              Do not allow TLSv1.1 protocol.
236
237       --no-tlsv1_2
238              Do not allow TLSv1.2/DTLSv1.2 protocol.
239
240       --no-udp
241              Do not start UDP client listeners.
242
243       --no-tcp
244              Do not start TCP client listeners.
245
246       --no-tls
247              Do not start TLS client listeners.
248
249       --no-dtls
250              Do not start DTLS client listeners.
251
252       --no-udp-relay
253              Do not allow UDP relay endpoints defined in RFC 5766,  use  only
254              TCP relay endpoints as defined in RFC 6062.
255
256       --no-tcp-relay
257              Do  not  allow TCP relay endpoints defined in RFC 6062, use only
258              UDP relay endpoints as defined in RFC 5766.
259
260       --no-stdout-log
261              Flag to prevent stdout log messages.  By default, all  log  mes‐
262              sages  are  going to both stdout and to the configured log file.
263              With this option everything will be going to the log  file  only
264              (unless the log file itself is stdout).
265
266       --syslog
267              With  this  flag,  all  log will be redirected to the system log
268              (syslog).
269
270       --simple-log
271              This flag means that no log file rollover will be used, and  the
272              log  file  name  will be constructed as-is, without PID and date
273              appendage.  This option can be used, for example, together  with
274              the logrotate tool.
275
276       --secure-stun
277              Require authentication of the STUN Binding request.  By default,
278              the clients are allowed anonymous access  to  the  STUN  Binding
279              functionality.
280
281       -S, --stun-only
282              Run  as  STUN  server  only,  all TURN requests will be ignored.
283              Option to suppress TURN functionality, only STUN  requests  will
284              be processed.
285
286       --no-stun
287              Run  as  TURN  server  only,  all STUN requests will be ignored.
288              Option to suppress STUN functionality, only TURN  requests  will
289              be processed.
290
291       --allow-loopback-peers
292              Allow  peers  on  the  loopback  addresses  (127.x.x.x and ::1).
293              Allow it only for testing in a development environment!  In pro‐
294              duction it adds a possible security vulnerability, and so due to
295              security reasons, it is not allowed using it together with empty
296              cli-password.
297
298       --no-multicast-peers
299              Disallow  peers on well-known broadcast addresses (224.0.0.0 and
300              above, and FFXX:*).
301
302       --mobility
303              Mobility with ICE (MICE) specs support.
304
305       --no-cli
306              Turn OFF the CLI support. By default it is always ON.  See  also
307              options --cli-ip and --cli-port.
308
309       --server-relay
310              Server relay. NON-STANDARD AND DANGEROUS OPTION.  Only for those
311              applications when we want to  run  server  applications  on  the
312              relay  endpoints.   This  option  eliminates  the IP permissions
313              check on the packets  incoming  to  the  relay  endpoints.   See
314              http://tools.ietf.org/search/rfc5766#section-17.2.3 .
315
316       --udp-self-balance
317              (recommended  for  older Linuxes only) Automatically balance UDP
318              traffic over auxiliary servers (if configured). The load balanc‐
319              ing  is  using  the  ALTERNATE-SERVER mechanism. The TURN client
320              must support 300 ALTERNATE-SERVER response for this  functional‐
321              ity.
322
323       --check-origin-consistency
324              The flag that sets the origin consistency check: across the ses‐
325              sion, all requests must have  the  same  main  ORIGIN  attribute
326              value (if the ORIGIN was initially used by the session).
327
328       -h     Help.
329
330       Options with values:
331
332       --stale-nonce[=<value>]
333              Use  extra security with nonce value having limited lifetime, in
334              seconds (default 600 secs).
335
336       --max-allocate-lifetime
337              Set the maximum value for the allocation lifetime.   Default  to
338              3600 secs.
339
340       --channel-lifetime
341              Set the lifetime for channel binding, default to 600 secs.  This
342              value MUST not be changed for production purposes.
343
344       --permission-lifetime
345              Set the value for the lifetime of the  permission.   Default  to
346              300 secs.  This MUST not be changed for production purposes.
347
348       -d, --listening-device
349              Listener interface device.  (NOT RECOMMENDED. Optional function‐
350              ality, Linux only).  The turnserver process must have root priv‐
351              ileges to bind the listening endpoint to a device. If turnserver
352              must run as a process without root privileges, then just do  not
353              use this setting.
354
355       -L, --listening-ip
356              Listener  IP address of relay server.  Multiple listeners can be
357              specified, for example: -L ip1 -L ip2 -L ip3 If no IP(s)  speci‐
358              fied, then all IPv4 and IPv6 system IPs will be used for listen‐
359              ing.  The same ip(s) can be used as  both  listening  and  relay
360              ip(s).
361
362       -p, --listening-port
363              TURN  listener  port  for UDP and TCP listeners (Default: 3478).
364              Note: actually, TLS & DTLS sessions can connect to  the  "plain"
365              TCP & UDP port(s), too - if allowed by configuration.
366
367       --tls-listening-port
368              TURN  listener  port for TLS and DTLS listeners (Default: 5349).
369              Note: actually, "plain" TCP & UDP sessions can  connect  to  the
370              TLS  & DTLS port(s), too - if allowed by configuration. The TURN
371              server "automatically" recognizes the type of traffic. Actually,
372              two  listening endpoints (the "plain" one and the "tls" one) are
373              equivalent in terms of functionality; but we keep both endpoints
374              to  satisfy  the RFC 5766 specs.  For secure TCP connections, we
375              currently support SSL version 3 and TLS versions 1.0, 1.1,  1.2.
376              For secure UDP connections, we support DTLS version 1.
377
378       --alt-listening-port
379              Alternative  listening  port  for UDP and TCP listeners; default
380              (or zero) value means "listening port plus one".  This is needed
381              for  STUN  CHANGE_REQUEST - in RFC 5780 sense or in old RFC 3489
382              sense - for NAT behavior discovery). The  TURN  Server  supports
383              CHANGE_REQUEST  only if it is started with more than one listen‐
384              ing  IP  address  of  the  same  family  (IPv4  or  IPv6).   The
385              CHANGE_REQUEST  is  only supported by UDP protocol, other proto‐
386              cols are listening on that endpoint only for "symmetry".
387
388       --alt-tls-listening-port
389              Alternative listening port for TLS and DTLS protocols.   Default
390              (or zero) value means "TLS listening port plus one".
391
392       --aux-server
393              Auxiliary STUN/TURN server listening endpoint.  Aux servers have
394              almost full TURN and STUN functionality.   The  (minor)  limita‐
395              tions are:
396
397              1)  Auxiliary  servers do not have alternative ports and they do
398                  not support STUN RFC 5780 functionality (CHANGE REQUEST).
399
400              2)  Auxiliary  servers  also  are   never   returning   ALTERNA‐
401                  TIVE-SERVER reply.
402
403       Valid  formats  are 1.2.3.4:5555 for IPv4 and [1:2::3:4]:5555 for IPv6.
404       There may be multiple aux-server options, each will be used for listen‐
405       ing to client requests.
406
407       -i, --relay-device
408              Relay  interface  device  for  relay  sockets  (NOT RECOMMENDED.
409              Optional, Linux only).
410
411       -E, --relay-ip
412              Relay address (the local IP address that will be used  to  relay
413              the  packets to the peer). Multiple relay addresses may be used:
414              -E ip1 -E ip2 -E ip3 The same IP(s) can be used as both  listen‐
415              ing  IP(s)  and  relay IP(s).  If no relay IP(s) specified, then
416              the turnserver will apply the default  policy:  it  will  decide
417              itself  which  relay addresses to be used, and it will always be
418              using the client socket IP address as the relay  IP  address  of
419              the  TURN  session (if the requested relay address family is the
420              same as the family of the client socket).
421
422       -X, --external-ip
423              TURN Server public/private address mapping,  if  the  server  is
424              behind  NAT.   In  that  situation,  if a -X is used in form "-X
425              <ip>" then that ip will be reported as relay IP address  of  all
426              allocations.  This scenario works only in a simple case when one
427              single relay address is be used, and no CHANGE_REQUEST function‐
428              ality  is  required. That single relay address must be mapped by
429              NAT to the 'external'  IP.   The  "external-ip"  value,  if  not
430              empty,  is  returned  in  XOR-RELAYED-ADDRESS  field.   For that
431              'external' IP, NAT must forward  ports  directly  (relayed  port
432              12345  must be always mapped to the same 'external' port 12345).
433              In more complex case when more than one IP address is  involved,
434              that  option  must  be  used several times, each entry must have
435              form "-X <public-ip/private-ip>", to map all involved addresses.
436              CHANGE_REQUEST (RFC5780 or RFC3489) NAT discovery STUN function‐
437              ality will work correctly, if the addresses are mapped properly,
438              even  when  the TURN server itself is behind A NAT.  By default,
439              this value is empty, and no address mapping is used.
440
441       -m, --relay-threads
442              Number of the relay threads to handle  the  established  connec‐
443              tions  (in  addition  to  authentication thread and the listener
444              thread).  If explicitly set to 0  then  application  runs  relay
445              process in a single thread, in the same thread with the listener
446              process (the authentication thread  will  still  be  a  separate
447              thread).  If  not  set, then a default optimal algorithm will be
448              employed (OS-dependent). In  the  older  Linux  systems  (before
449              Linux  kernel  3.9),  the  number  of  UDP threads is always one
450              threads per network listening endpoint - unless "-m 0" or "-m 1"
451              is set.
452
453       --min-port
454              Lower  bound  of  the UDP port range for relay endpoints alloca‐
455              tion.  Default value is 49152, according to RFC 5766.
456
457       --max-port
458              Upper bound of the UDP port range for  relay  endpoints  alloca‐
459              tion.  Default value is 65535, according to RFC 5766.
460
461       -u, --user
462              Long-term  security  mechanism  credentials user account, in the
463              column-separated form username:key.  Multiple user accounts  may
464              be  used  in the command line.  The key is either the user pass‐
465              word, or the key is generated by turnadmin command. In the  sec‐
466              ond case, the key must be prepended with 0x symbols.  The key is
467              calculated over the user name, the  user  realm,  and  the  user
468              password.  This setting may not be used with TURN REST API.
469
470       -r, --realm
471              The default realm to be used for the users when no explicit ori‐
472              gin/realm relationship was found in the database, or if the TURN
473              server  is  not  using any database (just the commands-line set‐
474              tings and the userdb file). Must be used with long-term  creden‐
475              tials mechanism or with TURN REST API.
476
477       -C, --rest-api-separator
478              This  is  the timestamp/username separator symbol (character) in
479              TURN REST API. The default value is :.
480
481       -q, --user-quota
482              Per-user allocations quota: how many  concurrent  allocations  a
483              user  can  create. This option can also be set through the data‐
484              base, for a particular realm.
485
486       -Q, --total-quota
487              Total allocations quota: global limit on concurrent allocations.
488              This option can also be set through the database, for a particu‐
489              lar realm.
490
491       -s, --max-bps
492              Max bytes-per-second bandwidth a TURN session is allowed to han‐
493              dle  (input  and output network streams are treated separately).
494              Anything above that limit will  be  dropped  or  temporary  sup‐
495              pressed  (within  the  available buffer limits). This option can
496              also be set through the database, for a particular realm.
497
498       -B, --bps-capacity
499              Maximum server capacity.  Total bytes-per-second  bandwidth  the
500              TURN  server  is  allowed to allocate for the sessions, combined
501              (input and output network streams are treated separately).
502
503       --static-auth-secret
504              Static authentication secret value (a string) for TURN REST  API
505              only.   If  not  set,  then  the turn server will try to use the
506              dynamic  value  in  turn_secret  table  in  user  database   (if
507              present). The database-stored value can be changed on-the-fly by
508              a separate program, so this is why that other mode  is  dynamic.
509              Multiple shared secrets can be used (both in the database and in
510              the "static" fashion).
511
512       --server-name
513              Server name used for the  oAuth  authentication  purposes.   The
514              default value is the realm name.
515
516       --cert Certificate  file, PEM format. Same file search rules applied as
517              for the configuration  file.  If  both  --no-tls  and  --no-dtls
518              options  are  specified,  then  this  parameter  is  not needed.
519              Default value is turn_server_cert.pem.
520
521       --pkey Private key file, PEM format. Same file search rules applied  as
522              for  the  configuration  file.  If  both  --no-tls and --no-dtls
523              options are  specified,  then  this  parameter  is  not  needed.
524              Default value is turn_server_pkey.pem.
525
526       --pkey-pwd
527              If  the  private key file is encrypted, then this password to be
528              used.
529
530       --cipher-list
531              Allowed OpenSSL cipher list for TLS/DTLS  connections.   Default
532              value is "DEFAULT".
533
534       --CA-file
535              CA  file  in  OpenSSL  format.  Forces TURN server to verify the
536              client SSL certificates.  By default, no CA is set and no client
537              certificate check is performed.
538
539       --ec-curve-name
540              Curve  name for EC ciphers, if supported by OpenSSL library (TLS
541              and DTLS). The default value is prime256v1, if pre-OpenSSL 1.0.2
542              is used. With OpenSSL 1.0.2+, an optimal curve will be automati‐
543              cally calculated, if not defined by this option.
544
545       --dh-file
546              Use custom DH TLS key, stored in PEM format in the file.   Flags
547              --dh566 and --dh2066 are ignored when the DH key is taken from a
548              file.
549
550       -l, --log-file
551              Option to set the full path name of the log file.   By  default,
552              the  turnserver tries to open a log file in /var/log/turnserver,
553              /var/log, /var/tmp, /tmp and . (current) directories (which file
554              open operation succeeds first that file will be used). With this
555              option you can set the definite  log  file  name.   The  special
556              names  are  "stdout" and "-" - they will force everything to the
557              stdout. Also, "syslog" name will redirect  everything  into  the
558              system  log  (syslog),  as if the option "--syslog" was set.  In
559              the runtime, the logfile can be reset with the SIGHUP signal  to
560              the turnserver process.
561
562       --alternate-server
563              Option  to  set the "redirection" mode. The value of this option
564              will be the address of the alternate server for UDP &  TCP  ser‐
565              vice  in  form of <ip>[:<port>]. The server will send this value
566              in the attribute ALTERNATE-SERVER, with error 300,  on  ALLOCATE
567              request,  to  the  client.  Client will receive only values with
568              the same address family as the client network  endpoint  address
569              family.   See  RFC  5389 and RFC 5766 for ALTERNATE-SERVER func‐
570              tionality description.  The client must use the  obtained  value
571              for  subsequent  TURN communications.  If more than one --alter‐
572              nate-server options are provided, then the functionality can  be
573              more accurately described as "load-balancing" than a mere "redi‐
574              rection".  If the port number is omitted, then the default  port
575              number  3478  for the UDP/TCP protocols will be used.  Colon (:)
576              characters in IPv6 addresses may conflict with the syntax of the
577              option.  To  alleviate this conflict, literal IPv6 addresses are
578              enclosed in square brackets in such  resource  identifiers,  for
579              example: [2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 .  Multiple
580              alternate  servers  can  be  set.  They  will  be  used  in  the
581              round-robin  manner.  All  servers in the pool are considered of
582              equal weight and the load will be distributed equally. For exam‐
583              ple,  if  we  have  4  alternate  servers, then each server will
584              receive 25% of  ALLOCATE  requests.  An  alternate  TURN  server
585              address can be used more than one time with the alternate-server
586              option, so this can emulate "weighting" of the servers.
587
588       --tls-alternate-server
589              Option to set alternative server for TLS & DTLS services in form
590              of  <ip>:<port>. If the port number is omitted, then the default
591              port number 5349 for the TLS/DTLS protocols will  be  used.  See
592              the previous option for the functionality description.
593
594       -O, --redis-statsdb
595              Redis  status and statistics database connection string, if used
596              (default - empty, no Redis stats DB used). This  database  keeps
597              allocations status information, and it can be also used for pub‐
598              lishing and delivering traffic and  allocation  event  notifica‐
599              tions.   This  database  option  can  be  used  independently of
600              --redis-userdb option, and actually Redis can be used  for  sta‐
601              tus/statistics  and SQLite or MySQL or MongoDB or PostgreSQL can
602              be used for the user database.  The connection  string  has  the
603              same parameters as redis-userdb connection string.
604
605       --max-allocate-timeout
606              Max time, in seconds, allowed for full allocation establishment.
607              Default is 60 seconds.
608
609       --denied-peer-ip=<IPaddr[-IPaddr]>
610
611       --allowed-peer-ip=<IPaddr[-IPaddr]> Options to ban or allow specific ip
612       addresses  or  ranges of ip addresses. If an ip address is specified as
613       both allowed and denied, then  the  ip  address  is  considered  to  be
614       allowed.  This  is useful when you wish to ban a range of ip addresses,
615       except for a few specific ips within that range.  This can be used when
616       you  do not want users of the turn server to be able to access machines
617       reachable by the turn server, but would otherwise be  unreachable  from
618       the  internet  (e.g. when the turn server is sitting behind a NAT). The
619       'white" and "black" peer IP ranges can also be dynamically  changed  in
620       the  database.   The allowed/denied addresses (white/black lists) rules
621       are very simple:
622
623              1)  If there is no rule for an address, then it is allowed;
624
625              2)  If there is an "allowed" rule that fits the address then  it
626                  is allowed - no matter what;
627
628              3)  If  there is no "allowed" rule that fits the address, and if
629                  there is a "denied" rule that fits the address, then  it  is
630                  denied.
631
632       --pidfile
633              File  name  to  store  the  pid  of  the  process.   Default  is
634              /var/run/turnserver.pid  (if  superuser  account  is  used)   or
635              /var/tmp/turnserver.pid .
636
637       --proc-user
638              User  name  to  run  the  process. After the initialization, the
639              turnserver process will make an attempt to  change  the  current
640              user ID to that user.
641
642       --proc-group
643              Group  name  to  run  the process. After the initialization, the
644              turnserver process will make an attempt to  change  the  current
645              group ID to that group.
646
647       -K, --keep-address-family
648              TURN  server  allocates address family according TURN Client <=>
649              Server communication address family.  !! It breaks RFC6156  sec‐
650              tion-4.2 (violates default IPv4) !!
651
652       --cli-ip
653              Local system IP address to be used for CLI management interface.
654              The turnserver process can be accessed for management with  tel‐
655              net, at this IP address and on the CLI port (see the next param‐
656              eter).  Default value is 127.0.0.1. You can use telnet or  putty
657              (in telnet mode) to access the CLI management interface.
658
659       --cli-port
660              CLI management interface listening port. Default is 5766.
661
662       --cli-password
663              CLI  access  password.  Default is empty (no password).  For the
664              security reasons, it is recommended to use the encrypted form of
665              the  password (see the -P command in the turnadmin utility). The
666              dollar signs in the encrypted form must be escaped.
667
668       --cli-max-output-sessions
669              Maximum number of output sessions in ps CLI command.  This value
670              can be changed on-the-fly in CLI. The default value is 256.
671
672       --web-admin
673              Enable Turn Web-admin support. By default it is disabled.
674
675       --web-admin-ip=<IP>
676              Local  system  IP  address  to be used for Web-admin server end‐
677              point. Default value is 127.0.0.1.
678
679       --web-admin-port=<port>
680              Web-admin server port. Default is 8080.
681
682       --web-admin-listen-on-workers
683              Enable for web-admin server  to  listens  on  STUN/TURN  workers
684              STUN/TURN ports.  By default it is disabled for security resons!
685              (This behavior used to be the default behavior, and was  enabled
686              by default.)
687
688       --ne=[1|2|3]
689              Set network engine type for the process (for internal purposes).
690
691       ==================================
692

LOAD BALANCE AND PERFORMANCE TUNING

694       This topic is covered in the wiki page:
695
696       https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
697
698       ===================================
699

WEBRTC USAGE

701       This is a set of notes for the WebRTC users:
702
703       1)  WebRTC  uses long-term authentication mechanism, so you have to use
704           -a option (or --lt-cred-mech). WebRTC relaying will not  work  with
705           anonymous  access. With -a option, do not forget to set the default
706           realm (-r option). You will also have to set up the user  accounts,
707           for that you have a number of options:
708
709               a) command-line options (-u).
710
711               b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to
712               set keys with turnadmin utility (see docs and wiki for turnadmin).
713               You cannot use open passwords in the database.
714
715               c) Redis key/value pair(s), if Redis is used. You key use either keys or
716               open passwords with Redis; see turndb/testredisdbsetup.sh file.
717
718               d) You also can use the TURN REST API. You will need shared secret(s) set
719               either  through the command line option, or through the config file, or through
720               the database table or Redis key/value pairs.
721
722
723       2)  Usually WebRTC uses fingerprinting (-f).
724
725       3)  -v option may be nice to see the connected clients.
726
727       4)  -X is needed if you are running your TURN server behind a NAT.
728
729       5)  --min-port  and  --max-port  may be needed if you want to limit the
730           relay endpoints ports number range.
731
732       ===================================
733

TURN REST API

735       In WebRTC, the browser obtains the TURN connection information from the
736       web  server. This information is a secure information - because it con‐
737       tains the necessary TURN credentials. As these credentials  are  trans‐
738       mitted over the public networks, we have a potential security breach.
739
740       If  we have to transmit a valuable information over the public network,
741       then this information has to have a limited lifetime. Then the guy  who
742       obtains  this  information  without  permission will be able to perform
743       only limited damage.
744
745       This is how the idea of TURN REST API - time-limited TURN credentials -
746       appeared.  This  security mechanism is based upon the long-term creden‐
747       tials mechanism. The main idea of the REST API is that the  web  server
748       provides  the  credentials  to the client, but those credentials can be
749       used only limited time by an application that  has  to  create  a  TURN
750       server connection.
751
752       The "classic" long-term credentials mechanism (LTCM) is described here:
753
754       http://tools.ietf.org/html/rfc5389#section-10.2
755
756       http://tools.ietf.org/html/rfc5389#section-15.4
757
758       For  authentication,  each  user must know two things: the username and
759       the password. Optionally, the user must supply  the  ORIGIN  value,  so
760       that  the  server can figure out the realm to be used for the user. The
761       nonce and the realm values are supplied by the TURN server. But LTCM is
762       not  saying  anything about the nature and about the persistence of the
763       username and of the password; and this is used by the REST API.
764
765       In the TURN REST API, there is no persistent  passwords  for  users.  A
766       user has just the username. The password is always temporary, and it is
767       generated by the web server  on-demand,  when  the  user  accesses  the
768       WebRTC page. And, actually, a temporary one-time session only, username
769       is provided to the user, too.
770
771       The temporary user is generated as:
772
773       temporary-username="timestamp" + ":" + "username"
774
775       where username is the persistent user name, and the timestamp format is
776       just  seconds  sinse  1970  -  the  same  value  as time(NULL) function
777       returns.
778
779       The temporary password is obtained as HMAC-SHA1 function over the  tem‐
780       porary  username,  with  shared  secret  as  the HMAC key, and then the
781       result is encoded:
782
783       temporary-password  =   base64_encode(hmac-sha1(shared-secret,   tempo‐
784       rary-username))
785
786       Both  the  TURN  server and the web server know the same shared secret.
787       How the shared secret is distributed among  the  involved  entities  is
788       left to the WebRTC deployment details - this is beyond the scope of the
789       TURN REST API.
790
791       So, a timestamp is used for the  temporary  password  calculation,  and
792       this  timestamp  can  be  retrieved  from  the temporary username. This
793       information is valuable, but only temporary, while the timestamp is not
794       expired.  Without knowledge of the shared secret, a new temporary pass‐
795       word cannot be generated.
796
797       This is all formally described in Justin's Uberti TURN REST  API  docu‐
798       ment  that  can  be  obtained following the link "TURN REST API" in the
799       TURN Server project's page https://github.com/coturn/coturn/.
800
801       Once the temporary username and password are  obtained  by  the  client
802       (browser)  application,  then the rest is just 'classic" long-term cre‐
803       dentials mechanism.  For  developers,  we  are  going  to  describe  it
804       step-by-step below:
805
806              ·  a new TURN client sends a request command to the TURN server.
807                 Optionally, it adds the ORIGIN field to it.
808
809              ·  TURN server sees that this is a new client and the message is
810                 not authenticated.
811
812              ·  the  TURN  server generates a random nonce string, and return
813                 the error 401 to the client, with nonce and  realm  included.
814                 If the ORIGIN field was present in the client request, it may
815                 affect the realm  value  that  the  server  chooses  for  the
816                 client.
817
818              ·  the client sees the 401 error and it extracts two values from
819                 the error response: the nonce and the realm.
820
821              ·  the client uses username, realm and  password  to  produce  a
822                 key:
823
824                       key = MD5(username ":" realm ":" SASLprep(password))
825              (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
826
827              ·  the  client  forms  a  new  request, adds username, realm and
828                 nonce to the request. Then, the client  calculates  and  adds
829                 the  integrity  field  to  the request. This is the trickiest
830                 part of the process, and it is described in the end  of  sec‐
831                 tion 15.4: http://tools.ietf.org/html/rfc5389#section-15.4
832
833              ·  the  client, optionally, adds the fingerprint field. This may
834                 be also a tricky procedure, described in section 15.5 of  the
835                 same  document.   WebRTC usually uses fingerprinted TURN mes‐
836                 sages.
837
838              ·  the TURN server receives the request, reads the username.
839
840              ·  then the TURN server checks that the nonce and the  realm  in
841                 the request are the valid ones.
842
843              ·  then the TURN server calculates the key.
844
845              ·  then the TURN server calculates the integrity field.
846
847              ·  then  the TURN server compares the calculated integrity field
848                 with the received one  -  they  must  be  the  same.  If  the
849                 integrity fields differ, then the request is rejected.
850
851       In  subsequent  communications, the client may go with exactly the same
852       sequence, but for  optimization  usually  the  client,  having  already
853       information  about realm and nonce, pre-calculates the integrity string
854       for each request, so that the 401 error response  becomes  unnecessary.
855       The  TURN  server may use "--stale-nonce" option for extra security: in
856       some time, the nonce expires and  the  client  will  obtain  438  error
857       response  with  the  new nonce, and the client will have to start using
858       the new nonce.
859
860       In subsequent communications, the sever  and  the  client  will  always
861       assume  the  same  password - the original password becomes the session
862       parameter and is never expiring. So the password is not changing  while
863       the  session  is  valid  and  unexpired. So, if the session is properly
864       maintained, it may go forever, even  if  the  user  password  has  been
865       already  changed (in the database). The session simply is using the old
866       password. Once the session got disconnected, the client  will  have  to
867       use the new password to re-connect (if the password has been changed).
868
869       An example when a new shared secret is generated every hour by the TURN
870       server box and then supplied to the web server, remotely,  is  provided
871       in the script examples/scripts/restapi/shared_secret_maintainer.pl .
872
873       A  very important thing is that the nonce must be totally random and it
874       must be different for different clients and different sessions.
875
876       ===================================
877

DATABASES

879       For the user database, the turnserver has the following options:
880
881       1)  Users can be set in the command line, with multiple  -u  or  --user
882           options.   Obviously,  only  a  few  users can be set that way, and
883           their credentials are fixed for the turnserver process lifetime.
884
885       2)  Users can be stored in SQLite DB. The default SQLite database  file
886           is      /var/db/turndb      or      /usr/local/var/db/turndb     or
887           /var/lib/turn/turndb.
888
889       3)  Users can be stored in PostgreSQL database, if the  turnserver  was
890           compiled  with PostgreSQL support. Each time turnserver checks user
891           credentials, it reads the database (asynchronously, of  course,  so
892           that the current flow of packets is not delayed in any way), so any
893           change in the  database  content  is  immediately  visible  by  the
894           turnserver.  This  is the way if you need the best scalability. The
895           schema for the database can  be  found  in  schema.sql  file.   For
896           long-term  credentials,  you  have to set the "keys" for the users;
897           the "keys" are generated by the turnadmin utility. For the key gen‐
898           eration,  you  need username, password and the realm.  All users in
899           the database must use the same realm value; if down  the  road  you
900           will decide to change the realm name, then you will have to re-gen‐
901           erate all user keys (that can be done in a batch script).  See  the
902           file turndb/testsqldbsetup.sql as an example.
903
904       4)  The same is true for MySQL database. The same schema file is appli‐
905           cable.  The same considerations are applicable.
906
907       5)  The same is true for the Redis database, but the Redis database has
908           aa  different schema - it can be found (in the form of explanation)
909           in schema.userdb.redis.  Also, in Redis you can store  both  "keys"
910           and  open  passwords  (for long term credentials) - the "open pass‐
911           word" option is less secure but more  convenient  for  low-security
912           environments.   See the file turndb/testredisdbsetup.sh as an exam‐
913           ple.
914
915       6)  If a database is used, then users  can  be  divided  into  multiple
916           independent  realms. Each realm can be administered separately, and
917           each realm can have its own set of users and  its  own  performance
918           options (max-bps, user-quota, total-quota).
919
920       7)  If  you  use  MongoDB, the database will be setup for you automati‐
921           cally.
922
923       8)  Of course, the turnserver can be  used  in  non-secure  mode,  when
924           users  are  allowed  to establish sessions anonymously. But in most
925           cases (like WebRTC) that will not work.
926
927       For the status and statistics database, there are two choices:
928
929       1)  The simplest choice is not to use it. Do  not  set  --redis-statsdb
930           option, and this functionality will be simply ignored.
931
932       2)  If  you choose to use it, then set the --redis-statsdb option. This
933           may be the same database as in --redis-userdb option, or it may  be
934           a  different  database.  You may want to use different database for
935           security or convenience reasons. Also, you can use different  data‐
936           base  management  systems  for the user database and for the ststus
937           and statistics database. For example, you can use MySQL as the user
938           database,  and you can use redis for the statistics. Or you can use
939           Redis for both.
940
941       So, we have 6 choices for the user management, and 2  choices  for  the
942       statistics  management. These two are totally independent. So, you have
943       overall 6*2=12 ways to handle persistent information,  choose  any  for
944       your convenience.
945
946       You  do  not  have  to handle the database information "manually" - the
947       turnadmin program can handle everything for  you.  For  PostgreSQL  and
948       MySQL  you  will  just have to create an empty database with schema.sql
949       SQL script. With Redis, you do not have to do even that - just run tur‐
950       nadmin  and  it will set the users for you (see the turnadmin manuals).
951       If you are using SQLite, then the turnserver or turnadmin will initial‐
952       ize  the empty database, for you, when started. The TURN server instal‐
953       lation process creates an empty  initialized  SQLite  database  in  the
954       default   location   (/var/db/turndb   or  /usr/local/var/db/turndb  or
955       /var/lib/turn/turndb, depending on the system).
956
957       =================================
958

ALPN

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

LIBRARIES

970       In  the  lib/  sub-directory  the build process will create TURN client
971       messaging  library.   In  the  include/  sub-directory,  the  necessary
972       include  files will be placed.  The C++ wrapper for the messaging func‐
973       tionality is located in TurnMsgLib.h header.  An example  of  C++  code
974       can be found in stunclient.c file.
975
976       =================================
977

DOCS

979       After installation, run the command:
980
981       $ man turnserver
982
983       or in the project root directory:
984
985       $ man -M man turnserver
986
987       to see the man page.
988
989       In  the  docs/html  subdirectory of the original archive tree, you will
990       find the client library reference. After the installation, it  will  be
991       placed in PREFIX/share/doc/turnserver/html.
992
993       =================================
994

LOGS

996       When  the  TURN  Server  starts,  it makes efforts to create a log file
997       turn_<pid>.log in the following directories:
998
999              ·  /var/log
1000
1001              ·  /log/
1002
1003              ·  /var/tmp
1004
1005              ·  /tmp
1006
1007              ·  current directory
1008
1009       If all efforts failed (due to the system permission settings) then  all
1010       log messages are sent only to the standard output of the process.
1011
1012       This  behavior  can be controlled by --log-file, --syslog and --no-std‐
1013       out-log options.
1014
1015       =================================
1016

HTTPS MANAGEMENT INTERFACE

1018       The turnserver process provides an HTTPS Web access as  statistics  and
1019       basic  management  interface.  The turnserver listens to incoming HTTPS
1020       admin connections on the same ports as the main TURN/STUN listener. The
1021       Web admin pages are basic and self-explanatory.
1022
1023       To  make the HTTPS interface active, the database table admin_user must
1024       be populated with the admin user account(s). An admin  user  can  be  a
1025       superuser  (if not assigned to a particular realm) or a restricted user
1026       (if assigned to a realm). The restricted admin users can  perform  only
1027       limited actions, within their corresponding realms.
1028
1029       =================================
1030

TELNET CLI

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

CLUSTERS

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

FILES

1054       /etc/turnserver.conf
1055
1056       /var/db/turndb
1057
1058       /usr/local/var/db/turndb
1059
1060       /var/lib/turn/turndb
1061
1062       /usr/local/etc/turnserver.conf
1063
1064       =================================
1065

DIRECTORIES

1067       /usr/local/share/turnserver
1068
1069       /usr/local/share/doc/turnserver
1070
1071       /usr/local/share/examples/turnserver
1072
1073       =================================
1074

STANDARDS

1076       obsolete STUN RFC 3489
1077
1078       new STUN RFC 5389
1079
1080       TURN RFC 5766
1081
1082       TURN-TCP extension RFC 6062
1083
1084       TURN IPv6 extension RFC 6156
1085
1086       STUN/TURN test vectors RFC 5769
1087
1088       STUN NAT behavior discovery RFC 5780
1089
1090       =================================
1091

SEE ALSO

1093       turnadmin, turnutils
1094
1095       ======================================
1096
1097   WEB RESOURCES
1098       project page:
1099
1100       https://github.com/coturn/coturn/
1101
1102       Wiki page:
1103
1104       https://github.com/coturn/coturn/wiki
1105
1106       forum:
1107
1108       https://groups.google.com/forum/?from
1109       groups=#!forum/turn-server-project-rfc5766-turn-server
1110
1111       ======================================
1112
1113   AUTHORS
1114       Oleg Moskalenko <mom040267@gmail.com>
1115
1116       Gabor Kovesdan http://kovesdan.org/
1117
1118       Daniel Pocock http://danielpocock.com/
1119
1120       John Selbie (jselbie@gmail.com)
1121
1122       Lee Sylvester <lee@designrealm.co.uk>
1123
1124       Erik Johnston <erikj@openmarket.com>
1125
1126       Roman Lisagor <roman@demonware.net>
1127
1128       Vladimir Tsanev <tsachev@gmail.com>
1129
1130       Po-sheng Lin <personlin118@gmail.com>
1131
1132       Peter Dunkley <peter.dunkley@acision.com>
1133
1134       Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
1135
1136       Federico Pinna <fpinna@vivocha.com>
1137
1138       Bradley T. Hughes <bradleythughes@fastmail.fm>
1139
1140       Mihaly Meszaros <misi@majd.eu>
1141
1142
1143
1144                                29 January 2019                        TURN(1)
Impressum