1TURN(1) TURN(1)
2
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 See the INSTALL file for the building instructions.
11 After the build, you will have the following binary images:
13 1. turnserver: TURN Server relay. The compiled binary image of the
15 TURN Server program is located in bin/ sub-directory.
16 2. turnadmin: TURN administration tool. See README.turnadmin and
18 turnadmin man page.
19 3. turnutils_uclient. See README.turnutils and turnutils man page.
21 4. turnutils_peer. See README.turnutils and turnutils man page.
23 5. turnutils_stunclient. See README.turnutils and turnutils man
25 page.
26 6. turnutils_rfc5769check. See README.turnutils and turnutils man
28 page.
29 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 $ 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 Options note: turnserver has long and short option names, for most
42 options. Some options have only long form, some options have only
43 short form. Their syntax somewhat different, if an argument is
44 required:
45 The short form must be used as this (for example):
47 $ turnserver -L 12.34.56.78
49 The long form equivalent must use the "=" character:
51 $ turnserver --listening-ip=12.34.56.78
53 If this is a flag option (no argument required) then their usage are
55 the same, for example:
56 $ turnserver -a
58 is equivalent to:
60 $ turnserver --lt-cred-mech
62
65 NAME
66 turnserver - a TURN relay server implementation.
67 SYNOPSIS
69 $ 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]
70 $ turnserver -h
71 DESCRIPTION
74 Config file settings:
75 -n Do not use configuration file, use only command line parameters.
77 -c Configuration file name (default - turnserver.conf). The format
79 of config file can be seen in the supplied exam‐
80 ples/etc/turnserver.conf example file. Long names of the options
81 are used as the configuration items names in the file. If not an
82 absolute path is supplied, then the file is searched in the fol‐
83 lowing directories:
84 · current directory
86 · current directory etc/ sub-directory
88 · upper directory level etc/
90 · /etc/
92 · /usr/local/etc/
94 · installation directory /etc
96 User database settings:
98 -b, --db, --userdb
100 SQLite user database file name (default - /var/db/turndb or
101 /usr/local/var/db/turndb or /var/lib/turn/turndb).
102 -e, --psql-userdb
104 User database connection string for PostgreSQL. This database
105 can be used for long-term credentials mechanism, and it can
106 store the secret value for secret-based timed authentication in
107 TURN REST API. The connection string format is like that:
108 "host=<host> dbname=<dbname> user=<db-user> pass‐
110 word=<db-user-password> connect_timeout=<seconds>" (for 8.x or
111 newer Postgres).
112 Or:
114 "postgresql://username:password@hostname:port/databasename" (for
116 9.x or newer Postgres).
117 See the INSTALL file for more explanations and examples.
119 Also, see http://www.PostgreSQL.org for full PostgreSQL documen‐
121 tation.
122 -M, --mysql-userdb
124 User database connection string for MySQL or MariaDB. This
125 database can be used for long-term credentials mechanism, and it
126 can store the secret value for secret-based timed authentication
127 in TURN REST API. The connection string format is like that:
128 "host=<host> dbname=<dbname> user=<db-user> pass‐
130 word=<db-user-password> connect_timeout=<seconds> read_time‐
131 out=<seconds>"
132 See the INSTALL file for more explanations and examples.
134 Also, see http://www.mysql.org or http://mariadb.org for full
136 MySQL documentation.
137 Optional connection string parameters for the secure communica‐
139 tions (SSL): ca, capath, cert, key, cipher (see
140 http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html for the
141 command options description).
142 --secret-key-file
144 This is the file path which contain secret key of aes encryption
145 while using MySQL password encryption. If you want to use in
146 the MySQL connection string the password in encrypted format,
147 then set in this option the file path of the secret key. The key
148 which is used to encrypt MySQL password. Warning: If this
149 option is set, then MySQL password must be set in "mysql-userdb"
150 option in encrypted format! If you want to use cleartext pass‐
151 word then do not set this option!
152 -J, --mongo-userdb
154 User database connection string for MongoDB. This database can
155 be used for long-term credentials mechanism, and it can store
156 the secret value for secret-based timed authentication in TURN
157 REST API. The connection string format is like that:
158 "mongodb://username:password@host:port/database?options"
160 See the INSTALL file for more explanations and examples.
162 Also, see http://docs.mongodb.org/manual/ for full MongoDB docu‐
164 mentation.
165 -N, --redis-userdb
167 User database connection string for Redis. This database can be
168 used for long-term credentials mechanism, and it can store the
169 secret value for secret-based timed authentication in TURN REST
170 API. The connection string format is like that:
171 "ip=<ip-addr> dbname=<db-number> password=<db-password> con‐
173 nect_timeout=<seconds>"
174 See the INSTALL file for more explanations and examples.
176 Also, see http://redis.io for full Redis documentation.
178 Flags:
180 -v, --verbose
182 Moderate verbose mode.
183 -V, --Verbose
185 Extra verbose mode, very annoying and not recommended.
186 -o, --daemon
188 Run server as daemon.
189 --no-software-attribute Production mode: hide the software version.
191 -f, --fingerprint
193 Use fingerprints in the TURN messages. If an incoming request
194 contains a fingerprint, then TURN server will always add finger‐
195 prints to the messages in this session, regardless of the
196 per-server setting.
197 -a, --lt-cred-mech
199 Use long-term credentials mechanism (this one you need for
200 WebRTC usage).
201 -z, --no-auth
203 Do not use any credentials mechanism, allow anonymous access.
204 Opposite to -a and -A options. This is default option when no
205 authentication-related options are set. By default, no creden‐
206 tial mechanism is used - any user is allowed.
207 --use-auth-secret
209 TURN REST API flag. Flag that sets a special WebRTC authoriza‐
210 tion option that is based upon authentication secret. The fea‐
211 ture purpose is to support "TURN Server REST API" as described
212 in the TURN REST API section below. This option uses timestamp
213 as part of combined username: usercombo -> "timestamp:username",
214 turn user -> usercombo, turn password -> base64(hmac(input_buf‐
215 fer = usercombo, key = shared-secret)). This allows TURN cre‐
216 dentials to be accounted for a specific user id. If you don't
217 have a suitable id, the timestamp alone can be used. This
218 option is just turns on secret-based authentication. The actual
219 value of the secret is defined either by option
220 static-auth-secret, or can be found in the turn_secret table in
221 the database.
222 --oauth
224 Support oAuth authentication, as in the third-party STUN/TURN
225 RFC 7635.
226 --dh566
228 Use 566 bits predefined DH TLS key. Default size of the key is
229 2066.
230 --dh1066
232 Use 1066 bits predefined DH TLS key. Default size of the key is
233 2066.
234 --no-tlsv1
236 Do not allow TLSv1/DTLSv1 protocol.
237 --no-tlsv1_1
239 Do not allow TLSv1.1 protocol.
240 --no-tlsv1_2
242 Do not allow TLSv1.2/DTLSv1.2 protocol.
243 --no-udp
245 Do not start UDP client listeners.
246 --no-tcp
248 Do not start TCP client listeners.
249 --no-tls
251 Do not start TLS client listeners.
252 --no-dtls
254 Do not start DTLS client listeners.
255 --no-udp-relay
257 Do not allow UDP relay endpoints defined in RFC 5766, use only
258 TCP relay endpoints as defined in RFC 6062.
259 --no-tcp-relay
261 Do not allow TCP relay endpoints defined in RFC 6062, use only
262 UDP relay endpoints as defined in RFC 5766.
263 --no-stdout-log
265 Flag to prevent stdout log messages. By default, all log mes‐
266 sages are going to both stdout and to the configured log file.
267 With this option everything will be going to the log file only
268 (unless the log file itself is stdout).
269 --syslog
271 With this flag, all log will be redirected to the system log
272 (syslog).
273 --simple-log
275 This flag means that no log file rollover will be used, and the
276 log file name will be constructed as-is, without PID and date
277 appendage. This option can be used, for example, together with
278 the logrotate tool.
279 --new-log-timestamp
281 Enable full ISO-8601 timestamp in all logs.
282 --new-log-timestamp-format
284 <format> Set timestamp format (in strftime(1) format)
285 --log-binding
287 Log STUN binding request. It is now disabled by default to avoid
288 DoS attacks.
289 --secure-stun
291 Require authentication of the STUN Binding request. By default,
292 the clients are allowed anonymous access to the STUN Binding
293 functionality.
294 -S, --stun-only
296 Run as STUN server only, all TURN requests will be ignored.
297 Option to suppress TURN functionality, only STUN requests will
298 be processed.
299 --no-stun
301 Run as TURN server only, all STUN requests will be ignored.
302 Option to suppress STUN functionality, only TURN requests will
303 be processed.
304 --allow-loopback-peers
306 Allow peers on the loopback addresses (127.x.x.x and ::1).
307 Allow it only for testing in a development environment! In pro‐
308 duction it adds a possible security vulnerability, and so due to
309 security reasons, it is not allowed using it together with empty
310 cli-password.
311 --no-multicast-peers
313 Disallow peers on well-known broadcast addresses (224.0.0.0 and
314 above, and FFXX:*).
315 --mobility
317 Mobility with ICE (MICE) specs support.
318 --no-cli
320 Turn OFF the CLI support. By default it is always ON. See also
321 options --cli-ip and --cli-port.
322 --server-relay
324 Server relay. NON-STANDARD AND DANGEROUS OPTION. Only for those
325 applications when we want to run server applications on the
326 relay endpoints. This option eliminates the IP permissions
327 check on the packets incoming to the relay endpoints. See
328 http://tools.ietf.org/search/rfc5766#section-17.2.3 .
329 --udp-self-balance
331 (recommended for older Linuxes only) Automatically balance UDP
332 traffic over auxiliary servers (if configured). The load balanc‐
333 ing is using the ALTERNATE-SERVER mechanism. The TURN client
334 must support 300 ALTERNATE-SERVER response for this functional‐
335 ity.
336 --check-origin-consistency
338 The flag that sets the origin consistency check: across the ses‐
339 sion, all requests must have the same main ORIGIN attribute
340 value (if the ORIGIN was initially used by the session).
341 --prometheus
343 Enable prometheus metrics. By default it is disabled.
344 Would listen on port 9641 unther the path /metrics also
345 the path / on this port can be used as a health check
346 -h Help.
348 Options with values:
350 --stale-nonce[=<value>]
352 Use extra security with nonce value having limited lifetime, in
353 seconds (default 600 secs). Set it to 0 for unlimited nonce
354 lifetime.
355 --max-allocate-lifetime
357 Set the maximum value for the allocation lifetime. Default to
358 3600 secs.
359 --channel-lifetime
361 Set the lifetime for channel binding, default to 600 secs. This
362 value MUST not be changed for production purposes.
363 --permission-lifetime
365 Set the value for the lifetime of the permission. Default to
366 300 secs. This MUST not be changed for production purposes.
367 -d, --listening-device
369 Listener interface device. (NOT RECOMMENDED. Optional function‐
370 ality, Linux only). The turnserver process must have root priv‐
371 ileges to bind the listening endpoint to a device. If turnserver
372 must run as a process without root privileges, then just do not
373 use this setting.
374 -L, --listening-ip
376 Listener IP address of relay server. Multiple listeners can be
377 specified, for example: -L ip1 -L ip2 -L ip3 If no IP(s) speci‐
378 fied, then all IPv4 and IPv6 system IPs will be used for listen‐
379 ing. The same ip(s) can be used as both listening and relay
380 ip(s).
381 -p, --listening-port
383 TURN listener port for UDP and TCP listeners (Default: 3478).
384 Note: actually, TLS & DTLS sessions can connect to the "plain"
385 TCP & UDP port(s), too - if allowed by configuration.
386 --tls-listening-port
388 TURN listener port for TLS and DTLS listeners (Default: 5349).
389 Note: actually, "plain" TCP & UDP sessions can connect to the
390 TLS & DTLS port(s), too - if allowed by configuration. The TURN
391 server "automatically" recognizes the type of traffic. Actually,
392 two listening endpoints (the "plain" one and the "tls" one) are
393 equivalent in terms of functionality; but we keep both endpoints
394 to satisfy the RFC 5766 specs. For secure TCP connections, we
395 currently support SSL version 3 and TLS versions 1.0, 1.1, 1.2.
396 For secure UDP connections, we support DTLS version 1.
397 --alt-listening-port
399 Alternative listening port for UDP and TCP listeners; default
400 (or zero) value means "listening port plus one". This is needed
401 for STUN CHANGE_REQUEST - in RFC 5780 sense or in old RFC 3489
402 sense - for NAT behavior discovery). The TURN Server supports
403 CHANGE_REQUEST only if it is started with more than one listen‐
404 ing IP address of the same family (IPv4 or IPv6). The
405 CHANGE_REQUEST is only supported by UDP protocol, other proto‐
406 cols are listening on that endpoint only for "symmetry".
407 --alt-tls-listening-port
409 Alternative listening port for TLS and DTLS protocols. Default
410 (or zero) value means "TLS listening port plus one".
411 --tcp-proxy-port
413 Support connections from TCP loadbalancer on this port. The
414 loadbalancer should use the binary proxy protocol.
415 (https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
416 --aux-server
418 Auxiliary STUN/TURN server listening endpoint. Aux servers have
419 almost full TURN and STUN functionality. The (minor) limita‐
420 tions are:
421 1) Auxiliary servers do not have alternative ports and they do
423 not support STUN RFC 5780 functionality (CHANGE REQUEST).
424 2) Auxiliary servers also are never returning ALTERNA‐
426 TIVE-SERVER reply.
427 Valid formats are 1.2.3.4:5555 for IPv4 and [1:2::3:4]:5555 for IPv6.
429 There may be multiple aux-server options, each will be used for listen‐
430 ing to client requests.
431 -i, --relay-device
433 Relay interface device for relay sockets (NOT RECOMMENDED.
434 Optional, Linux only).
435 -E, --relay-ip
437 Relay address (the local IP address that will be used to relay
438 the packets to the peer). Multiple relay addresses may be used:
439 -E ip1 -E ip2 -E ip3 The same IP(s) can be used as both listen‐
440 ing IP(s) and relay IP(s). If no relay IP(s) specified, then
441 the turnserver will apply the default policy: it will decide
442 itself which relay addresses to be used, and it will always be
443 using the client socket IP address as the relay IP address of
444 the TURN session (if the requested relay address family is the
445 same as the family of the client socket).
446 -X, --external-ip
448 TURN Server public/private address mapping, if the server is
449 behind NAT. In that situation, if a -X is used in form "-X
450 <ip>" then that ip will be reported as relay IP address of all
451 allocations. This scenario works only in a simple case when one
452 single relay address is be used, and no CHANGE_REQUEST function‐
453 ality is required. That single relay address must be mapped by
454 NAT to the 'external' IP. The "external-ip" value, if not
455 empty, is returned in XOR-RELAYED-ADDRESS field. For that
456 'external' IP, NAT must forward ports directly (relayed port
457 12345 must be always mapped to the same 'external' port 12345).
458 In more complex case when more than one IP address is involved,
459 that option must be used several times, each entry must have
460 form "-X <public-ip/private-ip>", to map all involved addresses.
461 CHANGE_REQUEST (RFC5780 or RFC3489) NAT discovery STUN function‐
462 ality will work correctly, if the addresses are mapped properly,
463 even when the TURN server itself is behind A NAT. By default,
464 this value is empty, and no address mapping is used.
465 -m, --relay-threads
467 Number of the relay threads to handle the established connec‐
468 tions (in addition to authentication thread and the listener
469 thread). If explicitly set to 0 then application runs relay
470 process in a single thread, in the same thread with the listener
471 process (the authentication thread will still be a separate
472 thread). If not set, then a default optimal algorithm will be
473 employed (OS-dependent). In the older Linux systems (before
474 Linux kernel 3.9), the number of UDP threads is always one
475 threads per network listening endpoint - unless "-m 0" or "-m 1"
476 is set.
477 --min-port
479 Lower bound of the UDP port range for relay endpoints alloca‐
480 tion. Default value is 49152, according to RFC 5766.
481 --max-port
483 Upper bound of the UDP port range for relay endpoints alloca‐
484 tion. Default value is 65535, according to RFC 5766.
485 -u, --user
487 Long-term security mechanism credentials user account, in the
488 column-separated form username:key. Multiple user accounts may
489 be used in the command line. The key is either the user pass‐
490 word, or the key is generated by turnadmin command. In the sec‐
491 ond case, the key must be prepended with 0x symbols. The key is
492 calculated over the user name, the user realm, and the user
493 password. This setting may not be used with TURN REST API.
494 -r, --realm
496 The default realm to be used for the users when no explicit ori‐
497 gin/realm relationship was found in the database, or if the TURN
498 server is not using any database (just the commands-line set‐
499 tings and the userdb file). Must be used with long-term creden‐
500 tials mechanism or with TURN REST API.
501 -C, --rest-api-separator
503 This is the timestamp/username separator symbol (character) in
504 TURN REST API. The default value is :.
505 -q, --user-quota
507 Per-user allocations quota: how many concurrent allocations a
508 user can create. This option can also be set through the data‐
509 base, for a particular realm.
510 -Q, --total-quota
512 Total allocations quota: global limit on concurrent allocations.
513 This option can also be set through the database, for a particu‐
514 lar realm.
515 -s, --max-bps
517 Max bytes-per-second bandwidth a TURN session is allowed to han‐
518 dle (input and output network streams are treated separately).
519 Anything above that limit will be dropped or temporary sup‐
520 pressed (within the available buffer limits). This option can
521 also be set through the database, for a particular realm.
522 -B, --bps-capacity
524 Maximum server capacity. Total bytes-per-second bandwidth the
525 TURN server is allowed to allocate for the sessions, combined
526 (input and output network streams are treated separately).
527 --static-auth-secret
529 Static authentication secret value (a string) for TURN REST API
530 only. If not set, then the turn server will try to use the
531 dynamic value in turn_secret table in user database (if
532 present). The database-stored value can be changed on-the-fly by
533 a separate program, so this is why that other mode is dynamic.
534 Multiple shared secrets can be used (both in the database and in
535 the "static" fashion).
536 --no-auth-pings
538 Disable periodic health checks to 'dynamic' auth secret
539 tables.
540 --no-dynamic-ip-list
542 Do not use dynamic allowed/denied peer ip list.
543 --no-dynamic-realms
545 Do not use dynamic realm assignment and options.
546 --server-name
548 Server name used for the oAuth authentication purposes. The
549 default value is the realm name.
550 --cert Certificate file, PEM format. Same file search rules applied as
552 for the configuration file. If both --no-tls and --no-dtls
553 options are specified, then this parameter is not needed.
554 Default value is turn_server_cert.pem.
555 --pkey Private key file, PEM format. Same file search rules applied as
557 for the configuration file. If both --no-tls and --no-dtls
558 options are specified, then this parameter is not needed.
559 Default value is turn_server_pkey.pem.
560 --pkey-pwd
562 If the private key file is encrypted, then this password to be
563 used.
564 --cipher-list
566 Allowed OpenSSL cipher list for TLS/DTLS connections. Default
567 value is "DEFAULT".
568 --CA-file
570 CA file in OpenSSL format. Forces TURN server to verify the
571 client SSL certificates. By default, no CA is set and no client
572 certificate check is performed.
573 --ec-curve-name
575 Curve name for EC ciphers, if supported by OpenSSL library (TLS
576 and DTLS). The default value is prime256v1, if pre-OpenSSL 1.0.2
577 is used. With OpenSSL 1.0.2+, an optimal curve will be automati‐
578 cally calculated, if not defined by this option.
579 --dh-file
581 Use custom DH TLS key, stored in PEM format in the file. Flags
582 --dh566 and --dh1066 are ignored when the DH key is taken from a
583 file.
584 -l, --log-file
586 Option to set the full path name of the log file. By default,
587 the turnserver tries to open a log file in /var/log/turnserver,
588 /var/log, /var/tmp, /tmp and . (current) directories (which file
589 open operation succeeds first that file will be used). With this
590 option you can set the definite log file name. The special
591 names are "stdout" and "-" - they will force everything to the
592 stdout. Also, "syslog" name will redirect everything into the
593 system log (syslog), as if the option "--syslog" was set. In
594 the runtime, the logfile can be reset with the SIGHUP signal to
595 the turnserver process.
596 --alternate-server
598 Option to set the "redirection" mode. The value of this option
599 will be the address of the alternate server for UDP & TCP ser‐
600 vice in form of <ip>[:<port>]. The server will send this value
601 in the attribute ALTERNATE-SERVER, with error 300, on ALLOCATE
602 request, to the client. Client will receive only values with
603 the same address family as the client network endpoint address
604 family. See RFC 5389 and RFC 5766 for ALTERNATE-SERVER func‐
605 tionality description. The client must use the obtained value
606 for subsequent TURN communications. If more than one --alter‐
607 nate-server options are provided, then the functionality can be
608 more accurately described as "load-balancing" than a mere "redi‐
609 rection". If the port number is omitted, then the default port
610 number 3478 for the UDP/TCP protocols will be used. Colon (:)
611 characters in IPv6 addresses may conflict with the syntax of the
612 option. To alleviate this conflict, literal IPv6 addresses are
613 enclosed in square brackets in such resource identifiers, for
614 example: [2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 . Multiple
615 alternate servers can be set. They will be used in the
616 round-robin manner. All servers in the pool are considered of
617 equal weight and the load will be distributed equally. For exam‐
618 ple, if we have 4 alternate servers, then each server will
619 receive 25% of ALLOCATE requests. An alternate TURN server
620 address can be used more than one time with the alternate-server
621 option, so this can emulate "weighting" of the servers.
622 --tls-alternate-server
624 Option to set alternative server for TLS & DTLS services in form
625 of <ip>:<port>. If the port number is omitted, then the default
626 port number 5349 for the TLS/DTLS protocols will be used. See
627 the previous option for the functionality description.
628 -O, --redis-statsdb
630 Redis status and statistics database connection string, if used
631 (default - empty, no Redis stats DB used). This database keeps
632 allocations status information, and it can be also used for pub‐
633 lishing and delivering traffic and allocation event notifica‐
634 tions. This database option can be used independently of
635 --redis-userdb option, and actually Redis can be used for sta‐
636 tus/statistics and SQLite or MySQL or MongoDB or PostgreSQL can
637 be used for the user database. The connection string has the
638 same parameters as redis-userdb connection string.
639 --max-allocate-timeout
641 Max time, in seconds, allowed for full allocation establishment.
642 Default is 60 seconds.
643 --denied-peer-ip=<IPaddr[-IPaddr]>
645 --allowed-peer-ip=<IPaddr[-IPaddr]> Options to ban or allow specific ip
647 addresses or ranges of ip addresses. If an ip address is specified as
648 both allowed and denied, then the ip address is considered to be
649 allowed. This is useful when you wish to ban a range of ip addresses,
650 except for a few specific ips within that range. This can be used when
651 you do not want users of the turn server to be able to access machines
652 reachable by the turn server, but would otherwise be unreachable from
653 the internet (e.g. when the turn server is sitting behind a NAT). The
654 'white" and "black" peer IP ranges can also be dynamically changed in
655 the database. The allowed/denied addresses (white/black lists) rules
656 are very simple:
657 1) If there is no rule for an address, then it is allowed;
659 2) If there is an "allowed" rule that fits the address then it
661 is allowed - no matter what;
662 3) If there is no "allowed" rule that fits the address, and if
664 there is a "denied" rule that fits the address, then it is
665 denied.
666 --pidfile
668 File name to store the pid of the process. Default is
669 /var/run/turnserver.pid (if superuser account is used) or
670 /var/tmp/turnserver.pid .
671 --acme-redirect
673 <URL> Redirect ACME/RFC8555 (like Let's Encrypt challenge)
674 requests, i.e. HTTP GET requests matching
675 '^/.well-known/acme-challenge/(.*)' to <URL>$1 with $1 == (.*).
676 No validation of <URL> will be done, so make sure you do not
677 forget the trailing slash. If <URL> is an empty string (the
678 default value), no special handling of such requests will be
679 done.
680 --proc-user
682 User name to run the process. After the initialization, the
683 turnserver process will make an attempt to change the current
684 user ID to that user.
685 --proc-group
687 Group name to run the process. After the initialization, the
688 turnserver process will make an attempt to change the current
689 group ID to that group.
690 -K, --keep-address-family
692 TURN server allocates address family according TURN Client <=>
693 Server communication address family. !! It breaks RFC6156 sec‐
694 tion-4.2 (violates default IPv4) !!
695 --cli-ip
697 Local system IP address to be used for CLI management interface.
698 The turnserver process can be accessed for management with tel‐
699 net, at this IP address and on the CLI port (see the next param‐
700 eter). Default value is 127.0.0.1. You can use telnet or putty
701 (in telnet mode) to access the CLI management interface.
702 --cli-port
704 CLI management interface listening port. Default is 5766.
705 --cli-password
707 CLI access password. Default is empty (no password). For the
708 security reasons, it is recommended to use the encrypted form of
709 the password (see the -P command in the turnadmin utility). The
710 dollar signs in the encrypted form must be escaped.
711 --cli-max-output-sessions
713 Maximum number of output sessions in ps CLI command. This value
714 can be changed on-the-fly in CLI. The default value is 256.
715 --web-admin
717 Enable Turn Web-admin support. By default it is disabled.
718 --web-admin-ip=<IP>
720 Local system IP address to be used for Web-admin server end‐
721 point. Default value is 127.0.0.1.
722 --web-admin-port=<port>
724 Web-admin server port. Default is 8080.
725 --web-admin-listen-on-workers
727 Enable for web-admin server to listens on STUN/TURN workers
728 STUN/TURN ports. By default it is disabled for security resons!
729 (This behavior used to be the default behavior, and was enabled
730 by default.)
731 --ne=[1|2|3]
733 Set network engine type for the process (for internal purposes).
734
737 This topic is covered in the wiki page:
738 https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
740
743 This is a set of notes for the WebRTC users:
744 1) WebRTC uses long-term authentication mechanism, so you have to use
746 -a option (or --lt-cred-mech). WebRTC relaying will not work with
747 anonymous access. With -a option, do not forget to set the default
748 realm (-r option). You will also have to set up the user accounts,
749 for that you have a number of options:
750 a) command-line options (-u).
752 b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to
754 set keys with turnadmin utility (see docs and wiki for turnadmin).
755 You cannot use open passwords in the database.
756 c) Redis key/value pair(s), if Redis is used. You key use either keys or
758 open passwords with Redis; see turndb/testredisdbsetup.sh file.
759 d) You also can use the TURN REST API. You will need shared secret(s) set
761 either through the command line option, or through the config file, or through
762 the database table or Redis key/value pairs.
763 2) Usually WebRTC uses fingerprinting (-f).
766 3) -v option may be nice to see the connected clients.
768 4) -X is needed if you are running your TURN server behind a NAT.
770 5) --min-port and --max-port may be needed if you want to limit the
772 relay endpoints ports number range.
773
776 In WebRTC, the browser obtains the TURN connection information from the
777 web server. This information is a secure information - because it con‐
778 tains the necessary TURN credentials. As these credentials are trans‐
779 mitted over the public networks, we have a potential security breach.
780 If we have to transmit a valuable information over the public network,
782 then this information has to have a limited lifetime. Then the guy who
783 obtains this information without permission will be able to perform
784 only limited damage.
785 This is how the idea of TURN REST API - time-limited TURN credentials -
787 appeared. This security mechanism is based upon the long-term creden‐
788 tials mechanism. The main idea of the REST API is that the web server
789 provides the credentials to the client, but those credentials can be
790 used only limited time by an application that has to create a TURN
791 server connection.
792 The "classic" long-term credentials mechanism (LTCM) is described here:
794 http://tools.ietf.org/html/rfc5389#section-10.2
796 http://tools.ietf.org/html/rfc5389#section-15.4
798 For authentication, each user must know two things: the username and
800 the password. Optionally, the user must supply the ORIGIN value, so
801 that the server can figure out the realm to be used for the user. The
802 nonce and the realm values are supplied by the TURN server. But LTCM is
803 not saying anything about the nature and about the persistence of the
804 username and of the password; and this is used by the REST API.
805 In the TURN REST API, there is no persistent passwords for users. A
807 user has just the username. The password is always temporary, and it is
808 generated by the web server on-demand, when the user accesses the
809 WebRTC page. And, actually, a temporary one-time session only, username
810 is provided to the user, too.
811 The temporary user is generated as:
813 temporary-username="timestamp" + ":" + "username"
815 where username is the persistent user name, and the timestamp format is
817 just seconds since 1970 - the same value as time(NULL) function
818 returns.
819 The temporary password is obtained as HMAC-SHA1 function over the tem‐
821 porary username, with shared secret as the HMAC key, and then the
822 result is encoded:
823 temporary-password = base64_encode(hmac-sha1(shared-secret, tempo‐
825 rary-username))
826 Both the TURN server and the web server know the same shared secret.
828 How the shared secret is distributed among the involved entities is
829 left to the WebRTC deployment details - this is beyond the scope of the
830 TURN REST API.
831 So, a timestamp is used for the temporary password calculation, and
833 this timestamp can be retrieved from the temporary username. This
834 information is valuable, but only temporary, while the timestamp is not
835 expired. Without knowledge of the shared secret, a new temporary pass‐
836 word cannot be generated.
837 This is all formally described in Justin's Uberti TURN REST API docu‐
839 ment that can be obtained following the link "TURN REST API" in the
840 TURN Server project's page https://github.com/coturn/coturn/.
841 Once the temporary username and password are obtained by the client
843 (browser) application, then the rest is just 'classic" long-term cre‐
844 dentials mechanism. For developers, we are going to describe it
845 step-by-step below:
846 · a new TURN client sends a request command to the TURN server.
848 Optionally, it adds the ORIGIN field to it.
849 · TURN server sees that this is a new client and the message is
851 not authenticated.
852 · the TURN server generates a random nonce string, and return
854 the error 401 to the client, with nonce and realm included.
855 If the ORIGIN field was present in the client request, it may
856 affect the realm value that the server chooses for the
857 client.
858 · the client sees the 401 error and it extracts two values from
860 the error response: the nonce and the realm.
861 · the client uses username, realm and password to produce a
863 key:
864 key = MD5(username ":" realm ":" SASLprep(password))
866 (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
867 · the client forms a new request, adds username, realm and
869 nonce to the request. Then, the client calculates and adds
870 the integrity field to the request. This is the trickiest
871 part of the process, and it is described in the end of sec‐
872 tion 15.4: http://tools.ietf.org/html/rfc5389#section-15.4
873 · the client, optionally, adds the fingerprint field. This may
875 be also a tricky procedure, described in section 15.5 of the
876 same document. WebRTC usually uses fingerprinted TURN mes‐
877 sages.
878 · the TURN server receives the request, reads the username.
880 · then the TURN server checks that the nonce and the realm in
882 the request are the valid ones.
883 · then the TURN server calculates the key.
885 · then the TURN server calculates the integrity field.
887 · then the TURN server compares the calculated integrity field
889 with the received one - they must be the same. If the
890 integrity fields differ, then the request is rejected.
891 In subsequent communications, the client may go with exactly the same
893 sequence, but for optimization usually the client, having already
894 information about realm and nonce, pre-calculates the integrity string
895 for each request, so that the 401 error response becomes unnecessary.
896 The TURN server may use "--stale-nonce" option for extra security: in
897 some time, the nonce expires and the client will obtain 438 error
898 response with the new nonce, and the client will have to start using
899 the new nonce.
900 In subsequent communications, the server and the client will always
902 assume the same password - the original password becomes the session
903 parameter and is never expiring. So the password is not changing while
904 the session is valid and unexpired. So, if the session is properly
905 maintained, it may go forever, even if the user password has been
906 already changed (in the database). The session simply is using the old
907 password. Once the session got disconnected, the client will have to
908 use the new password to re-connect (if the password has been changed).
909 An example when a new shared secret is generated every hour by the TURN
911 server box and then supplied to the web server, remotely, is provided
912 in the script examples/scripts/restapi/shared_secret_maintainer.pl .
913 A very important thing is that the nonce must be totally random and it
915 must be different for different clients and different sessions.
916
919 For the user database, the turnserver has the following options:
920 1) Users can be set in the command line, with multiple -u or --user
922 options. Obviously, only a few users can be set that way, and
923 their credentials are fixed for the turnserver process lifetime.
924 2) Users can be stored in SQLite DB. The default SQLite database file
926 is /var/db/turndb or /usr/local/var/db/turndb or
927 /var/lib/turn/turndb.
928 3) Users can be stored in PostgreSQL database, if the turnserver was
930 compiled with PostgreSQL support. Each time turnserver checks user
931 credentials, it reads the database (asynchronously, of course, so
932 that the current flow of packets is not delayed in any way), so any
933 change in the database content is immediately visible by the
934 turnserver. This is the way if you need the best scalability. The
935 schema for the database can be found in schema.sql file. For
936 long-term credentials, you have to set the "keys" for the users;
937 the "keys" are generated by the turnadmin utility. For the key gen‐
938 eration, you need username, password and the realm. All users in
939 the database must use the same realm value; if down the road you
940 will decide to change the realm name, then you will have to re-gen‐
941 erate all user keys (that can be done in a batch script). See the
942 file turndb/testsqldbsetup.sql as an example.
943 4) The same is true for MySQL database. The same schema file is appli‐
945 cable. The same considerations are applicable.
946 5) The same is true for the Redis database, but the Redis database has
948 aa different schema - it can be found (in the form of explanation)
949 in schema.userdb.redis. Also, in Redis you can store both "keys"
950 and open passwords (for long term credentials) - the "open pass‐
951 word" option is less secure but more convenient for low-security
952 environments. See the file turndb/testredisdbsetup.sh as an exam‐
953 ple.
954 6) If a database is used, then users can be divided into multiple
956 independent realms. Each realm can be administered separately, and
957 each realm can have its own set of users and its own performance
958 options (max-bps, user-quota, total-quota).
959 7) If you use MongoDB, the database will be setup for you automati‐
961 cally.
962 8) Of course, the turnserver can be used in non-secure mode, when
964 users are allowed to establish sessions anonymously. But in most
965 cases (like WebRTC) that will not work.
966 For the status and statistics database, there are two choices:
968 1) The simplest choice is not to use it. Do not set --redis-statsdb
970 option, and this functionality will be simply ignored.
971 2) If you choose to use it, then set the --redis-statsdb option. This
973 may be the same database as in --redis-userdb option, or it may be
974 a different database. You may want to use different database for
975 security or convenience reasons. Also, you can use different data‐
976 base management systems for the user database and for the ststus
977 and statistics database. For example, you can use MySQL as the user
978 database, and you can use redis for the statistics. Or you can use
979 Redis for both.
980 So, we have 6 choices for the user management, and 2 choices for the
982 statistics management. These two are totally independent. So, you have
983 overall 6*2=12 ways to handle persistent information, choose any for
984 your convenience.
985 You do not have to handle the database information "manually" - the
987 turnadmin program can handle everything for you. For PostgreSQL and
988 MySQL you will just have to create an empty database with schema.sql
989 SQL script. With Redis, you do not have to do even that - just run tur‐
990 nadmin and it will set the users for you (see the turnadmin manuals).
991 If you are using SQLite, then the turnserver or turnadmin will initial‐
992 ize the empty database, for you, when started. The TURN server instal‐
993 lation process creates an empty initialized SQLite database in the
994 default location (/var/db/turndb or /usr/local/var/db/turndb or
995 /var/lib/turn/turndb, depending on the system).
996
999 The server supports ALPNs "stun.turn" and "stun.nat-discovery", when
1000 compiled with OpenSSL 1.0.2 or newer. If the server receives a TLS/DTLS
1001 ClientHello message that contains one or both of those ALPNs, then the
1002 server chooses the first stun.* label and sends it back (in the Server‐
1003 Hello) in the ALPN extension field. If no stun.* label is found, then
1004 the server does not include the ALPN information into the ServerHello.
1005
1008 In the lib/ sub-directory the build process will create TURN client
1009 messaging library. In the include/ sub-directory, the necessary
1010 include files will be placed. The C++ wrapper for the messaging func‐
1011 tionality is located in TurnMsgLib.h header. An example of C++ code
1012 can be found in stunclient.c file.
1013
1016 After installation, run the command:
1017 $ man turnserver
1019 or in the project root directory:
1021 $ man -M man turnserver
1023 to see the man page.
1025 In the docs/html subdirectory of the original archive tree, you will
1027 find the client library reference. After the installation, it will be
1028 placed in PREFIX/share/doc/turnserver/html.
1029
1032 When the TURN Server starts, it makes efforts to create a log file
1033 turn_<pid>.log in the following directories:
1034 · /var/log
1036 · /log/
1038 · /var/tmp
1040 · /tmp
1042 · current directory
1044 If all efforts failed (due to the system permission settings) then all
1046 log messages are sent only to the standard output of the process.
1047 This behavior can be controlled by --log-file, --syslog and --no-std‐
1049 out-log options.
1050
1053 The turnserver process provides an HTTPS Web access as statistics and
1054 basic management interface. The turnserver listens to incoming HTTPS
1055 admin connections on the same ports as the main TURN/STUN listener. The
1056 Web admin pages are basic and self-explanatory.
1057 To make the HTTPS interface active, the database table admin_user must
1059 be populated with the admin user account(s). An admin user can be a
1060 superuser (if not assigned to a particular realm) or a restricted user
1061 (if assigned to a realm). The restricted admin users can perform only
1062 limited actions, within their corresponding realms.
1063
1066 The turnserver process provides a telnet CLI access as statistics and
1067 basic management interface. By default, the turnserver starts a telnet
1068 CLI listener on IP 127.0.0.1 and port 5766. That can be changed by the
1069 command-cline options of the turnserver process (see --cli-ip and
1070 --cli-port options). The full list of telnet CLI commands is provided
1071 in "help" command output in the telnet CLI.
1072
1075 TURN Server can be a part of the cluster installation. But, to support
1076 the "even port" functionality (RTP/RTCP streams pairs) the client
1077 requests from a particular IP must be delivered to the same TURN Server
1078 instance, so it requires some networking setup massaging for the clus‐
1079 ter. The reason is that the RTP and RTCP relaying endpoints must be
1080 allocated on the same relay IP. It would be possible to design a scheme
1081 with the application-level requests forwarding (and we may do that
1082 later) but it would affect the performance.
1083
1086 /etc/turnserver.conf
1087 /var/db/turndb
1089 /usr/local/var/db/turndb
1091 /var/lib/turn/turndb
1093 /usr/local/etc/turnserver.conf
1095
1098 /usr/local/share/turnserver
1099 /usr/local/share/doc/turnserver
1101 /usr/local/share/examples/turnserver
1103
1106 obsolete STUN RFC 3489
1107 new STUN RFC 5389
1109
1111 TURN-TCP extension RFC 6062
1112 TURN IPv6 extension RFC 6156
1114 STUN/TURN test vectors RFC 5769
1116 STUN NAT behavior discovery RFC 5780
1118
1121 turnadmin, turnutils
1122
1124 WEB RESOURCES
1125 project page:
1126 https://github.com/coturn/coturn/
1128 Wiki page:
1130 https://github.com/coturn/coturn/wiki
1132 forum:
1134 https://groups.google.com/forum/?from‐
1136 groups=#!forum/turn-server-project-rfc5766-turn-server
1137
1139 AUTHORS
1140 Oleg Moskalenko <mom040267@gmail.com>
1141 Gabor Kovesdan http://kovesdan.org/
1143 Daniel Pocock http://danielpocock.com/
1145 John Selbie (jselbie@gmail.com)
1147 Lee Sylvester <lee@designrealm.co.uk>
1149 Erik Johnston <erikj@openmarket.com>
1151 Roman Lisagor <roman@demonware.net>
1153 Vladimir Tsanev <tsachev@gmail.com>
1155 Po-sheng Lin <personlin118@gmail.com>
1157 Peter Dunkley <peter.dunkley@acision.com>
1159 Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
1161 Federico Pinna <fpinna@vivocha.com>
1163 Bradley T. Hughes <bradleythughes@fastmail.fm>
1165 Mihály Mészáros <misi@majd.eu>
1167 ACTIVE MAINTAINERS
1169 Mihály Mészáros <misi@majd.eu>
1170 10 January 2021 TURN(1)