1TURN(1) TURN(1)
2
3
4
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
37 If the systemd development library is available, then it will notify
38 systemd about the server status.
39
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
784 This topic is covered in the wiki page:
785
786 https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
787
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
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
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
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
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
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
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
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
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
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
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
1145 /usr/local/share/turnserver
1146
1147 /usr/local/share/doc/turnserver
1148
1149 /usr/local/share/examples/turnserver
1150
1153 obsolete STUN RFC 3489
1154
1155 new STUN RFC 5389
1156
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
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)