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

SYSTEMD

37       If  the  systemd  development library is available, then it will notify
38       systemd about the server status.
39

RUNNING THE TURN SERVER

41       To run the coturn server as a daemon use:
42
43         $ turnserver -o
44
45       Note that if you make any changes to the config file the server has  to
46       be restarted.
47
48       Options  note: turnserver has long and short option names, for most op‐
49       tions.  Some options have only long form, some options have only  short
50       form. Their syntax somewhat different, if an argument is required:
51
52       The short form must be used as this (for example):
53
54         $ turnserver -L 12.34.56.78
55
56       The long form equivalent must use the "=" character:
57
58         $ turnserver --listening-ip=12.34.56.78
59
60       If  this  is  a flag option (no argument required) then their usage are
61       the same, for example:
62
63        $ turnserver -a
64
65       is equivalent to:
66
67        $ turnserver --lt-cred-mech
68
69

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

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

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

LOAD BALANCE AND PERFORMANCE TUNING

777       This topic is covered in the wiki page:
778
779       https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
780

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

WEBRTC USAGE

783       This is a set of notes for the WebRTC users:
784
785       1)  WebRTC  uses long-term authentication mechanism, so you have to use
786           -a option (or --lt-cred-mech). WebRTC relaying will not  work  with
787           anonymous  access. With -a option, do not forget to set the default
788           realm (-r option). You will also have to set up the user  accounts,
789           for that you have a number of options:
790
791               a) command-line options (-u).
792
793               b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to
794               set keys with turnadmin utility (see docs and wiki for turnadmin).
795               You cannot use open passwords in the database.
796
797               c) Redis key/value pair(s), if Redis is used. You key use either keys or
798               open passwords with Redis; see turndb/testredisdbsetup.sh file.
799
800               d) You also can use the TURN REST API. You will need shared secret(s) set
801               either  through the command line option, or through the config file, or through
802               the database table or Redis key/value pairs.
803
804
805       2)  Usually WebRTC uses fingerprinting (-f).
806
807       3)  -v option may be nice to see the connected clients.
808
809       4)  -X is needed if you are running your TURN server behind a NAT.
810
811       5)  --min-port  and  --max-port  may be needed if you want to limit the
812           relay endpoints ports number range.
813

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

TURN REST API

816       In WebRTC, the browser obtains the TURN connection information from the
817       web  server. This information is a secure information - because it con‐
818       tains the necessary TURN credentials. As these credentials  are  trans‐
819       mitted over the public networks, we have a potential security breach.
820
821       If  we have to transmit a valuable information over the public network,
822       then this information has to have a limited lifetime. Then the guy  who
823       obtains  this  information  without  permission will be able to perform
824       only limited damage.
825
826       This is how the idea of TURN REST API - time-limited TURN credentials -
827       appeared.  This  security mechanism is based upon the long-term creden‐
828       tials mechanism. The main idea of the REST API is that the  web  server
829       provides  the  credentials  to the client, but those credentials can be
830       used only limited time by an application that  has  to  create  a  TURN
831       server connection.
832
833       The "classic" long-term credentials mechanism (LTCM) is described here:
834
835       http://tools.ietf.org/html/rfc5389#section-10.2
836
837       http://tools.ietf.org/html/rfc5389#section-15.4
838
839       For  authentication,  each  user must know two things: the username and
840       the password. Optionally, the user must supply  the  ORIGIN  value,  so
841       that  the  server can figure out the realm to be used for the user. The
842       nonce and the realm values are supplied by the TURN server. But LTCM is
843       not  saying  anything about the nature and about the persistence of the
844       username and of the password; and this is used by the REST API.
845
846       In the TURN REST API, there is no persistent  passwords  for  users.  A
847       user has just the username. The password is always temporary, and it is
848       generated by the web server on-demand, when the user accesses  the  We‐
849       bRTC  page.  And, actually, a temporary one-time session only, username
850       is provided to the user, too.
851
852       The temporary user is generated as:
853
854       temporary-username="timestamp" + ":" + "username"
855
856       where username is the persistent user name, and the timestamp format is
857       just  seconds  since  1970  - the same value as time(NULL) function re‐
858       turns.
859
860       The temporary password is obtained as HMAC-SHA1 function over the  tem‐
861       porary  username,  with shared secret as the HMAC key, and then the re‐
862       sult is encoded:
863
864       temporary-password  =   base64_encode(hmac-sha1(shared-secret,   tempo‐
865       rary-username))
866
867       Both  the  TURN  server and the web server know the same shared secret.
868       How the shared secret is distributed among  the  involved  entities  is
869       left to the WebRTC deployment details - this is beyond the scope of the
870       TURN REST API.
871
872       So, a timestamp is used for the  temporary  password  calculation,  and
873       this  timestamp  can be retrieved from the temporary username. This in‐
874       formation is valuable, but only temporary, while the timestamp  is  not
875       expired.  Without knowledge of the shared secret, a new temporary pass‐
876       word cannot be generated.
877
878       This is all formally described in Justin's Uberti TURN REST  API  docu‐
879       ment  that  can  be  obtained following the link "TURN REST API" in the
880       TURN Server project's page https://github.com/coturn/coturn/.
881
882       Once the temporary username and password are  obtained  by  the  client
883       (browser)  application,  then the rest is just 'classic" long-term cre‐
884       dentials mechanism.  For  developers,  we  are  going  to  describe  it
885       step-by-step below:
886
887              •  a new TURN client sends a request command to the TURN server.
888                 Optionally, it adds the ORIGIN field to it.
889
890              •  TURN server sees that this is a new client and the message is
891                 not authenticated.
892
893              •  the  TURN  server generates a random nonce string, and return
894                 the error 401 to the client, with nonce and  realm  included.
895                 If the ORIGIN field was present in the client request, it may
896                 affect the realm  value  that  the  server  chooses  for  the
897                 client.
898
899              •  the client sees the 401 error and it extracts two values from
900                 the error response: the nonce and the realm.
901
902              •  the client uses username, realm and  password  to  produce  a
903                 key:
904
905                       key = MD5(username ":" realm ":" SASLprep(password))
906              (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
907
908              •  the  client  forms  a  new  request, adds username, realm and
909                 nonce to the request. Then, the client  calculates  and  adds
910                 the  integrity  field  to  the request. This is the trickiest
911                 part of the process, and it is described in the end  of  sec‐
912                 tion 15.4: http://tools.ietf.org/html/rfc5389#section-15.4
913
914              •  the  client, optionally, adds the fingerprint field. This may
915                 be also a tricky procedure, described in section 15.5 of  the
916                 same  document.   WebRTC usually uses fingerprinted TURN mes‐
917                 sages.
918
919              •  the TURN server receives the request, reads the username.
920
921              •  then the TURN server checks that the nonce and the  realm  in
922                 the request are the valid ones.
923
924              •  then the TURN server calculates the key.
925
926              •  then the TURN server calculates the integrity field.
927
928              •  then  the TURN server compares the calculated integrity field
929                 with the received one - they must be the same. If the  integ‐
930                 rity fields differ, then the request is rejected.
931
932       In  subsequent  communications, the client may go with exactly the same
933       sequence, but for optimization usually the client, having  already  in‐
934       formation  about  realm  and nonce, pre-calculates the integrity string
935       for each request, so that the 401 error response  becomes  unnecessary.
936       The  TURN  server may use "--stale-nonce" option for extra security: in
937       some time, the nonce expires and the client will obtain 438  error  re‐
938       sponse  with the new nonce, and the client will have to start using the
939       new nonce.
940
941       In subsequent communications, the server and the client will always as‐
942       sume  the same password - the original password becomes the session pa‐
943       rameter and is never expiring. So the password is  not  changing  while
944       the  session  is  valid  and  unexpired. So, if the session is properly
945       maintained, it may go forever, even if the user password has  been  al‐
946       ready  changed  (in  the database). The session simply is using the old
947       password. Once the session got disconnected, the client  will  have  to
948       use the new password to re-connect (if the password has been changed).
949
950       An example when a new shared secret is generated every hour by the TURN
951       server box and then supplied to the web server, remotely,  is  provided
952       in the script examples/scripts/restapi/shared_secret_maintainer.pl .
953
954       A  very important thing is that the nonce must be totally random and it
955       must be different for different clients and different sessions.
956

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

DATABASES

959       For the user database, the turnserver has the following options:
960
961       1)  Users can be set in the command line, with multiple  -u  or  --user
962           options.   Obviously,  only  a  few  users can be set that way, and
963           their credentials are fixed for the turnserver process lifetime.
964
965       2)  Users can be stored in SQLite DB. The default SQLite database  file
966           is      /var/db/turndb      or      /usr/local/var/db/turndb     or
967           /var/lib/turn/turndb.
968
969       3)  Users can be stored in PostgreSQL database, if the  turnserver  was
970           compiled  with PostgreSQL support. Each time turnserver checks user
971           credentials, it reads the database (asynchronously, of  course,  so
972           that the current flow of packets is not delayed in any way), so any
973           change in the  database  content  is  immediately  visible  by  the
974           turnserver.  This  is the way if you need the best scalability. The
975           schema for the database can  be  found  in  schema.sql  file.   For
976           long-term  credentials,  you  have to set the "keys" for the users;
977           the "keys" are generated by the turnadmin utility. For the key gen‐
978           eration,  you  need username, password and the realm.  All users in
979           the database must use the same realm value; if down  the  road  you
980           will decide to change the realm name, then you will have to re-gen‐
981           erate all user keys (that can be done in a batch script).  See  the
982           file turndb/testsqldbsetup.sql as an example.
983
984       4)  The same is true for MySQL database. The same schema file is appli‐
985           cable.  The same considerations are applicable.
986
987       5)  The same is true for the Redis database, but the Redis database has
988           a  different  schema - it can be found (in the form of explanation)
989           in schema.userdb.redis.  Also, in Redis you can store  both  "keys"
990           and  open  passwords  (for long term credentials) - the "open pass‐
991           word" option is less secure but more  convenient  for  low-security
992           environments.   See the file turndb/testredisdbsetup.sh as an exam‐
993           ple.
994
995       6)  If a database is used, then users can be divided into multiple  in‐
996           dependent  realms.  Each  realm can be administered separately, and
997           each realm can have its own set of users and  its  own  performance
998           options (max-bps, user-quota, total-quota).
999
1000       7)  If  you  use  MongoDB, the database will be setup for you automati‐
1001           cally.
1002
1003       8)  Of course, the turnserver can be  used  in  non-secure  mode,  when
1004           users  are  allowed  to establish sessions anonymously. But in most
1005           cases (like WebRTC) that will not work.
1006
1007       For the status and statistics database, there are two choices:
1008
1009       1)  The simplest choice is not to use it. Do  not  set  --redis-statsdb
1010           option, and this functionality will be simply ignored.
1011
1012       2)  If  you choose to use it, then set the --redis-statsdb option. This
1013           may be the same database as in --redis-userdb option, or it may  be
1014           a  different  database.  You may want to use different database for
1015           security or convenience reasons. Also, you can use different  data‐
1016           base  management  systems  for the user database and for the ststus
1017           and statistics database. For example, you can use MySQL as the user
1018           database,  and you can use redis for the statistics. Or you can use
1019           Redis for both.
1020
1021       So, we have 6 choices for the user management, and 2  choices  for  the
1022       statistics  management. These two are totally independent. So, you have
1023       overall 6*2=12 ways to handle persistent information,  choose  any  for
1024       your convenience.
1025
1026       You  do  not  have  to handle the database information "manually" - the
1027       turnadmin program can handle everything for  you.  For  PostgreSQL  and
1028       MySQL  you  will  just have to create an empty database with schema.sql
1029       SQL script. With Redis, you do not have to do even that - just run tur‐
1030       nadmin  and  it will set the users for you (see the turnadmin manuals).
1031       If you are using SQLite, then the turnserver or turnadmin will initial‐
1032       ize  the empty database, for you, when started. The TURN server instal‐
1033       lation process creates an empty initialized SQLite database in the  de‐
1034       fault   location   (/var/db/turndb   or   /usr/local/var/db/turndb   or
1035       /var/lib/turn/turndb, depending on the system).
1036

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

ALPN

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

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

LIBRARIES

1048       In  the  lib/  sub-directory  the build process will create TURN client
1049       messaging library.  In the include/ sub-directory,  the  necessary  in‐
1050       clude  files  will  be placed.  The C++ wrapper for the messaging func‐
1051       tionality is located in TurnMsgLib.h header.  An example  of  C++  code
1052       can be found in stunclient.c file.
1053

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

DOCS

1056       After installation, run the command:
1057
1058       $ man turnserver
1059
1060       or in the project root directory:
1061
1062       $ man -M man turnserver
1063
1064       to see the man page.
1065
1066       In  the  docs/html  subdirectory of the original archive tree, you will
1067       find the client library reference. After the installation, it  will  be
1068       placed in PREFIX/share/doc/turnserver/html.
1069

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

LOGS

1072       When  the  TURN  Server  starts,  it makes efforts to create a log file
1073       turn_<pid>.log in the following directories:
1074
1075              •  /var/log
1076
1077              •  /log/
1078
1079              •  /var/tmp
1080
1081              •  /tmp
1082
1083              •  current directory
1084
1085       If all efforts failed (due to the system permission settings) then  all
1086       log messages are sent only to the standard output of the process.
1087
1088       This  behavior  can be controlled by --log-file, --syslog and --no-std‐
1089       out-log options.
1090

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

HTTPS MANAGEMENT INTERFACE

1093       The turnserver process provides an HTTPS Web access as  statistics  and
1094       basic  management  interface.  The turnserver listens to incoming HTTPS
1095       admin connections on the same ports as the main TURN/STUN listener. The
1096       Web admin pages are basic and self-explanatory.
1097
1098       To  make the HTTPS interface active, the database table admin_user must
1099       be populated with the admin user account(s). An admin user can be a su‐
1100       peruser  (if  not  assigned to a particular realm) or a restricted user
1101       (if assigned to a realm). The restricted admin users can  perform  only
1102       limited actions, within their corresponding realms.
1103

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

TELNET CLI

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

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

CLUSTERS

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

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

FILES

1126       /etc/turnserver.conf
1127
1128       /var/db/turndb
1129
1130       /usr/local/var/db/turndb
1131
1132       /var/lib/turn/turndb
1133
1134       /usr/local/etc/turnserver.conf
1135

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

DIRECTORIES

1138       /usr/local/share/turnserver
1139
1140       /usr/local/share/doc/turnserver
1141
1142       /usr/local/share/examples/turnserver
1143

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

STANDARDS

1146       obsolete STUN RFC 3489
1147
1148       new STUN RFC 5389
1149

TURN RFC 5766

1151       TURN-TCP extension RFC 6062
1152
1153       TURN IPv6 extension RFC 6156
1154
1155       STUN/TURN test vectors RFC 5769
1156
1157       STUN NAT behavior discovery RFC 5780
1158

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

SEE ALSO

1161       turnadmin, turnutils
1162

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

1164   WEB RESOURCES
1165       project page:
1166
1167       https://github.com/coturn/coturn/
1168
1169       Wiki page:
1170
1171       https://github.com/coturn/coturn/wiki
1172
1173       forum:
1174
1175       https://groups.google.com/forum/?fromgroups=#!fo‐
1176       rum/turn-server-project-rfc5766-turn-server
1177

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

1179   AUTHORS
1180       Oleg Moskalenko <mom040267@gmail.com>
1181
1182       Gabor Kovesdan http://kovesdan.org/
1183
1184       Daniel Pocock http://danielpocock.com/
1185
1186       John Selbie (jselbie@gmail.com)
1187
1188       Lee Sylvester <lee@designrealm.co.uk>
1189
1190       Erik Johnston <erikj@openmarket.com>
1191
1192       Roman Lisagor <roman@demonware.net>
1193
1194       Vladimir Tsanev <tsachev@gmail.com>
1195
1196       Po-sheng Lin <personlin118@gmail.com>
1197
1198       Peter Dunkley <peter.dunkley@acision.com>
1199
1200       Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
1201
1202       Federico Pinna <fpinna@vivocha.com>
1203
1204       Bradley T. Hughes <bradleythughes@fastmail.fm>
1205
1206       Mihály Mészáros <misi@majd.eu>
1207
1208   ACTIVE MAINTAINERS
1209       Mihály Mészáros <misi@majd.eu>
1210
1211
1212
1213                                 05 June 2021                          TURN(1)
Impressum