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

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

LOAD BALANCE AND PERFORMANCE TUNING

784       This topic is covered in the wiki page:
785
786       https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
787

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

WEBRTC USAGE

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

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

TURN REST API

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

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

DATABASES

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

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

ALPN

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

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

LIBRARIES

1055       In the lib/ sub-directory the build process  will  create  TURN  client
1056       messaging  library.   In  the include/ sub-directory, the necessary in‐
1057       clude files will be placed.  The C++ wrapper for  the  messaging  func‐
1058       tionality  is  located  in TurnMsgLib.h header.  An example of C++ code
1059       can be found in stunclient.c file.
1060

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

DOCS

1063       After installation, run the command:
1064
1065       $ man turnserver
1066
1067       or in the project root directory:
1068
1069       $ man -M man turnserver
1070
1071       to see the man page.
1072
1073       In the docs/html subdirectory of the original archive  tree,  you  will
1074       find  the  client library reference. After the installation, it will be
1075       placed in PREFIX/share/doc/turnserver/html.
1076

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

LOGS

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

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

HTTPS MANAGEMENT INTERFACE

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

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

TELNET CLI

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

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

CLUSTERS

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

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

FILES

1133       /etc/turnserver.conf
1134
1135       /var/db/turndb
1136
1137       /usr/local/var/db/turndb
1138
1139       /var/lib/turn/turndb
1140
1141       /usr/local/etc/turnserver.conf
1142

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

DIRECTORIES

1145       /usr/local/share/turnserver
1146
1147       /usr/local/share/doc/turnserver
1148
1149       /usr/local/share/examples/turnserver
1150

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

STANDARDS

1153       obsolete STUN RFC 3489
1154
1155       new STUN RFC 5389
1156

TURN RFC 5766

1158       TURN-TCP extension RFC 6062
1159
1160       TURN IPv6 extension RFC 6156
1161
1162       STUN/TURN test vectors RFC 5769
1163
1164       STUN NAT behavior discovery RFC 5780
1165

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

SEE ALSO

1168       turnadmin, turnutils
1169

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

1171   WEB RESOURCES
1172       project page:
1173
1174       https://github.com/coturn/coturn/
1175
1176       Wiki page:
1177
1178       https://github.com/coturn/coturn/wiki
1179
1180       forum:
1181
1182       https://groups.google.com/forum/?fromgroups=#!fo‐
1183       rum/turn-server-project-rfc5766-turn-server
1184

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

1186   AUTHORS
1187       See the AUTHORS.md file in the coturn source distribution.
1188
1189
1190
1191                                 05 June 2021                          TURN(1)
Impressum