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