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 To run the coturn server as a daemon use:
42 $ turnserver -o
44 Note that if you make any changes to the config file the server has to
46 be restarted.
47 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 The short form must be used as this (for example):
53 $ turnserver -L 12.34.56.78
55 The long form equivalent must use the "=" character:
57 $ turnserver --listening-ip=12.34.56.78
59 If this is a flag option (no argument required) then their usage are
61 the same, for example:
62 $ turnserver -a
64 is equivalent to:
66 $ turnserver --lt-cred-mech
68
71 NAME
72 turnserver - a TURN relay server implementation.
73 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 DESCRIPTION
80 Config file settings:
81 -n Do not use configuration file, use only command line parameters.
83 -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 • current directory
92 • current directory etc/ sub-directory
94 • upper directory level etc/
96 • /etc/
98 • /usr/local/etc/
100 • installation directory /etc
102 User database settings:
104 -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 -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 "host=<host> dbname=<dbname> user=<db-user> pass‐
116 word=<db-user-password> connect_timeout=<seconds>" (for 8.x or
117 newer Postgres).
118 Or:
120 "postgresql://username:password@hostname:port/databasename" (for
122 9.x or newer Postgres).
123 See the INSTALL file for more explanations and examples.
125 Also, see http://www.PostgreSQL.org for full PostgreSQL documen‐
127 tation.
128 -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 "host=<host> dbname=<dbname> user=<db-user> pass‐
136 word=<db-user-password> connect_timeout=<seconds> read_time‐
137 out=<seconds>"
138 See the INSTALL file for more explanations and examples.
140 Also, see http://www.mysql.org or http://mariadb.org for full
142 MySQL documentation.
143 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 --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 -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 "mongodb://username:password@host:port/database?options"
166 See the INSTALL file for more explanations and examples.
168 Also, see http://docs.mongodb.org/manual/ for full MongoDB docu‐
170 mentation.
171 -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 "ip=<ip-addr> dbname=<db-number> password=<db-password> con‐
179 nect_timeout=<seconds>"
180 See the INSTALL file for more explanations and examples.
182 Also, see http://redis.io for full Redis documentation.
184 Flags:
186 -v, --verbose
188 Moderate verbose mode.
189 -V, --Verbose
191 Extra verbose mode, very annoying and not recommended.
192 -o, --daemon
194 Run server as daemon.
195 --no-software-attribute Production mode: hide the software version.
197 -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 -a, --lt-cred-mech
205 Use long-term credentials mechanism (this one you need for We‐
206 bRTC usage).
207 -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 --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 --oauth
229 Support oAuth authentication, as in the third-party STUN/TURN
230 RFC 7635.
231 --dh566
233 Use 566 bits predefined DH TLS key. Default size of the key is
234 2066.
235 --dh1066
237 Use 1066 bits predefined DH TLS key. Default size of the key is
238 2066.
239 --no-tlsv1
241 Do not allow TLSv1/DTLSv1 protocol.
242 --no-tlsv1_1
244 Do not allow TLSv1.1 protocol.
245 --no-tlsv1_2
247 Do not allow TLSv1.2/DTLSv1.2 protocol.
248 --no-udp
250 Do not start UDP client listeners.
251 --no-tcp
253 Do not start TCP client listeners.
254 --no-tls
256 Do not start TLS client listeners.
257 --no-dtls
259 Do not start DTLS client listeners.
260 --no-udp-relay
262 Do not allow UDP relay endpoints defined in RFC 5766, use only
263 TCP relay endpoints as defined in RFC 6062.
264 --no-tcp-relay
266 Do not allow TCP relay endpoints defined in RFC 6062, use only
267 UDP relay endpoints as defined in RFC 5766.
268 --no-stdout-log
270 Flag to prevent stdout log messages. By default, all log mes‐
271 sages are going to both stdout and to the configured log file.
272 With this option everything will be going to the log file only
273 (unless the log file itself is stdout).
274 --syslog
276 With this flag, all log will be redirected to the system log
277 (syslog).
278 --simple-log
280 This flag means that no log file rollover will be used, and the
281 log file name will be constructed as-is, without PID and date
282 appendage. This option can be used, for example, together with
283 the logrotate tool.
284 --new-log-timestamp
286 Enable full ISO-8601 timestamp in all logs.
287 --new-log-timestamp-format
289 <format> Set timestamp format (in strftime(1) format)
290 --log-binding
292 Log STUN binding request. It is now disabled by default to avoid
293 DoS attacks.
294 --secure-stun
296 Require authentication of the STUN Binding request. By default,
297 the clients are allowed anonymous access to the STUN Binding
298 functionality.
299 -S, --stun-only
301 Run as STUN server only, all TURN requests will be ignored. Op‐
302 tion to suppress TURN functionality, only STUN requests will be
303 processed.
304 --no-stun
306 Run as TURN server only, all STUN requests will be ignored. Op‐
307 tion to suppress STUN functionality, only TURN requests will be
308 processed.
309 --allow-loopback-peers
311 Allow peers on the loopback addresses (127.x.x.x and ::1). Al‐
312 low it only for testing in a development environment! In pro‐
313 duction it adds a possible security vulnerability, and so due to
314 security reasons, it is not allowed using it together with empty
315 cli-password.
316 --no-multicast-peers
318 Disallow peers on well-known broadcast addresses (224.0.0.0 and
319 above, and FFXX:*).
320 --mobility
322 Mobility with ICE (MICE) specs support.
323 --no-cli
325 Turn OFF the CLI support. By default it is always ON. See also
326 options --cli-ip and --cli-port.
327 --server-relay
329 Server relay. NON-STANDARD AND DANGEROUS OPTION. Only for those
330 applications when we want to run server applications on the re‐
331 lay endpoints. This option eliminates the IP permissions check
332 on the packets incoming to the relay endpoints. See
333 http://tools.ietf.org/search/rfc5766#section-17.2.3 .
334 --udp-self-balance
336 (recommended for older Linuxes only) Automatically balance UDP
337 traffic over auxiliary servers (if configured). The load balanc‐
338 ing is using the ALTERNATE-SERVER mechanism. The TURN client
339 must support 300 ALTERNATE-SERVER response for this functional‐
340 ity.
341 --check-origin-consistency
343 The flag that sets the origin consistency check: across the ses‐
344 sion, all requests must have the same main ORIGIN attribute
345 value (if the ORIGIN was initially used by the session).
346 --prometheus
348 Enable prometheus metrics. By default it is disabled. Would lis‐
349 ten on port 9641 under the path /metrics also the path / on this
350 port can be used as a health check
351 --prometheus-port
353 Prometheus listener port (Default: 9641).
354 --prometheus-username-labels
356 Enable labeling prometheus traffic metrics with client user‐
357 names. Labeling with client usernames is disabled by default,
358 because this may cause memory leaks when using authentication
359 with ephemeral usernames (e.g. TURN REST API).
360 -h Help.
362 Options with values:
364 --stale-nonce[=<value>]
366 Use extra security with nonce value having limited lifetime, in
367 seconds (default 600 secs). Set it to 0 for unlimited nonce
368 lifetime.
369 --max-allocate-lifetime
371 Set the maximum value for the allocation lifetime. Default to
372 3600 secs.
373 --channel-lifetime
375 Set the lifetime for channel binding, default to 600 secs. This
376 value MUST not be changed for production purposes.
377 --permission-lifetime
379 Set the value for the lifetime of the permission. Default to
380 300 secs. This MUST not be changed for production purposes.
381 -d, --listening-device
383 Listener interface device. (NOT RECOMMENDED. Optional function‐
384 ality, Linux only). The turnserver process must have root priv‐
385 ileges to bind the listening endpoint to a device. If turnserver
386 must run as a process without root privileges, then just do not
387 use this setting.
388 -L, --listening-ip
390 Listener IP address of relay server. Multiple listeners can be
391 specified, for example: -L ip1 -L ip2 -L ip3 If no IP(s) speci‐
392 fied, then all IPv4 and IPv6 system IPs will be used for listen‐
393 ing. The same ip(s) can be used as both listening and relay
394 ip(s).
395 -p, --listening-port
397 TURN listener port for UDP and TCP listeners (Default: 3478).
398 Note: actually, TLS & DTLS sessions can connect to the "plain"
399 TCP & UDP port(s), too - if allowed by configuration.
400 --tls-listening-port
402 TURN listener port for TLS and DTLS listeners (Default: 5349).
403 Note: actually, "plain" TCP & UDP sessions can connect to the
404 TLS & DTLS port(s), too - if allowed by configuration. The TURN
405 server "automatically" recognizes the type of traffic. Actually,
406 two listening endpoints (the "plain" one and the "tls" one) are
407 equivalent in terms of functionality; but we keep both endpoints
408 to satisfy the RFC 5766 specs. For secure TCP connections, we
409 currently support SSL version 3 and TLS versions 1.0, 1.1, 1.2.
410 For secure UDP connections, we support DTLS version 1.
411 --alt-listening-port
413 Alternative listening port for UDP and TCP listeners; default
414 (or zero) value means "listening port plus one". This is needed
415 for STUN CHANGE_REQUEST - in RFC 5780 sense or in old RFC 3489
416 sense - for NAT behavior discovery). The TURN Server supports
417 CHANGE_REQUEST only if it is started with more than one listen‐
418 ing IP address of the same family (IPv4 or IPv6). The CHANGE_RE‐
419 QUEST is only supported by UDP protocol, other protocols are
420 listening on that endpoint only for "symmetry".
421 --alt-tls-listening-port
423 Alternative listening port for TLS and DTLS protocols. Default
424 (or zero) value means "TLS listening port plus one".
425 --tcp-proxy-port
427 Support connections from TCP loadbalancer on this port. The
428 loadbalancer should use the binary proxy protocol.
429 (https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
430 --aux-server
432 Auxiliary STUN/TURN server listening endpoint. Aux servers have
433 almost full TURN and STUN functionality. The (minor) limita‐
434 tions are:
435 1) Auxiliary servers do not have alternative ports and they do
437 not support STUN RFC 5780 functionality (CHANGE REQUEST).
438 2) Auxiliary servers also are never returning ALTERNA‐
440 TIVE-SERVER reply.
441 Valid formats are 1.2.3.4:5555 for IPv4 and [1:2::3:4]:5555 for IPv6.
443 There may be multiple aux-server options, each will be used for listen‐
444 ing to client requests.
445 -i, --relay-device
447 Relay interface device for relay sockets (NOT RECOMMENDED. Op‐
448 tional, Linux only).
449 -E, --relay-ip
451 Relay address (the local IP address that will be used to relay
452 the packets to the peer). Multiple relay addresses may be used:
453 -E ip1 -E ip2 -E ip3 The same IP(s) can be used as both listen‐
454 ing IP(s) and relay IP(s). If no relay IP(s) specified, then
455 the turnserver will apply the default policy: it will decide it‐
456 self which relay addresses to be used, and it will always be us‐
457 ing the client socket IP address as the relay IP address of the
458 TURN session (if the requested relay address family is the same
459 as the family of the client socket).
460 -X, --external-ip
462 TURN Server public/private address mapping, if the server is be‐
463 hind NAT. In that situation, if a -X is used in form "-X <ip>"
464 then that ip will be reported as relay IP address of all alloca‐
465 tions. This scenario works only in a simple case when one single
466 relay address is be used, and no CHANGE_REQUEST functionality is
467 required. That single relay address must be mapped by NAT to the
468 'external' IP. The "external-ip" value, if not empty, is re‐
469 turned in XOR-RELAYED-ADDRESS field. For that 'external' IP,
470 NAT must forward ports directly (relayed port 12345 must be al‐
471 ways mapped to the same 'external' port 12345). In more complex
472 case when more than one IP address is involved, that option must
473 be used several times, each entry must have form "-X <pub‐
474 lic-ip/private-ip>", to map all involved addresses. CHANGE_RE‐
475 QUEST (RFC5780 or RFC3489) NAT discovery STUN functionality will
476 work correctly, if the addresses are mapped properly, even when
477 the TURN server itself is behind A NAT. By default, this value
478 is empty, and no address mapping is used.
479 -m, --relay-threads
481 Number of the relay threads to handle the established connec‐
482 tions (in addition to authentication thread and the listener
483 thread). If explicitly set to 0 then application runs relay
484 process in a single thread, in the same thread with the listener
485 process (the authentication thread will still be a separate
486 thread). If not set, then a default optimal algorithm will be
487 employed (OS-dependent). In the older Linux systems (before
488 Linux kernel 3.9), the number of UDP threads is always one
489 threads per network listening endpoint - unless "-m 0" or "-m 1"
490 is set.
491 --min-port
493 Lower bound of the UDP port range for relay endpoints alloca‐
494 tion. Default value is 49152, according to RFC 5766.
495 --max-port
497 Upper bound of the UDP port range for relay endpoints alloca‐
498 tion. Default value is 65535, according to RFC 5766.
499 -u, --user
501 Long-term security mechanism credentials user account, in the
502 column-separated form username:key. Multiple user accounts may
503 be used in the command line. The key is either the user pass‐
504 word, or the key is generated by turnadmin command. In the sec‐
505 ond case, the key must be prepended with 0x symbols. The key is
506 calculated over the user name, the user realm, and the user
507 password. This setting may not be used with TURN REST API.
508 -r, --realm
510 The default realm to be used for the users when no explicit ori‐
511 gin/realm relationship was found in the database, or if the TURN
512 server is not using any database (just the commands-line set‐
513 tings and the userdb file). Must be used with long-term creden‐
514 tials mechanism or with TURN REST API.
515 -C, --rest-api-separator
517 This is the timestamp/username separator symbol (character) in
518 TURN REST API. The default value is :.
519 -q, --user-quota
521 Per-user allocations quota: how many concurrent allocations a
522 user can create. This option can also be set through the data‐
523 base, for a particular realm.
524 -Q, --total-quota
526 Total allocations quota: global limit on concurrent allocations.
527 This option can also be set through the database, for a particu‐
528 lar realm.
529 -s, --max-bps
531 Max bytes-per-second bandwidth a TURN session is allowed to han‐
532 dle (input and output network streams are treated separately).
533 Anything above that limit will be dropped or temporary sup‐
534 pressed (within the available buffer limits). This option can
535 also be set through the database, for a particular realm.
536 -B, --bps-capacity
538 Maximum server capacity. Total bytes-per-second bandwidth the
539 TURN server is allowed to allocate for the sessions, combined
540 (input and output network streams are treated separately).
541 --static-auth-secret
543 Static authentication secret value (a string) for TURN REST API
544 only. If not set, then the turn server will try to use the dy‐
545 namic value in turn_secret table in user database (if present).
546 The database-stored value can be changed on-the-fly by a sepa‐
547 rate program, so this is why that other mode is dynamic. Multi‐
548 ple shared secrets can be used (both in the database and in the
549 "static" fashion).
550 --no-auth-pings
552 Disable periodic health checks to 'dynamic' auth secret
553 tables.
554 --no-dynamic-ip-list
556 Do not use dynamic allowed/denied peer ip list.
557 --no-dynamic-realms
559 Do not use dynamic realm assignment and options.
560 --server-name
562 Server name used for the oAuth authentication purposes. The de‐
563 fault value is the realm name.
564 --cert Certificate file, PEM format. Same file search rules applied as
566 for the configuration file. If both --no-tls and --no-dtls op‐
567 tions are specified, then this parameter is not needed. Default
568 value is turn_server_cert.pem.
569 --pkey Private key file, PEM format. Same file search rules applied as
571 for the configuration file. If both --no-tls and --no-dtls op‐
572 tions are specified, then this parameter is not needed. Default
573 value is turn_server_pkey.pem.
574 --pkey-pwd
576 If the private key file is encrypted, then this password to be
577 used.
578 --cipher-list
580 Allowed OpenSSL cipher list for TLS/DTLS connections. Default
581 value is "DEFAULT".
582 --CA-file
584 CA file in OpenSSL format. Forces TURN server to verify the
585 client SSL certificates. By default, no CA is set and no client
586 certificate check is performed.
587 --ec-curve-name
589 Curve name for EC ciphers, if supported by OpenSSL library (TLS
590 and DTLS). The default value is prime256v1, if pre-OpenSSL 1.0.2
591 is used. With OpenSSL 1.0.2+, an optimal curve will be automati‐
592 cally calculated, if not defined by this option.
593 --dh-file
595 Use custom DH TLS key, stored in PEM format in the file. Flags
596 --dh566 and --dh1066 are ignored when the DH key is taken from a
597 file.
598 -l, --log-file
600 Option to set the full path name of the log file. By default,
601 the turnserver tries to open a log file in /var/log/turnserver,
602 /var/log, /var/tmp, /tmp and . (current) directories (which file
603 open operation succeeds first that file will be used). With this
604 option you can set the definite log file name. The special
605 names are "stdout" and "-" - they will force everything to the
606 stdout. Also, "syslog" name will redirect everything into the
607 system log (syslog), as if the option "--syslog" was set. In
608 the runtime, the logfile can be reset with the SIGHUP signal to
609 the turnserver process.
610 --alternate-server
612 Option to set the "redirection" mode. The value of this option
613 will be the address of the alternate server for UDP & TCP ser‐
614 vice in form of <ip>[:<port>]. The server will send this value
615 in the attribute ALTERNATE-SERVER, with error 300, on ALLOCATE
616 request, to the client. Client will receive only values with
617 the same address family as the client network endpoint address
618 family. See RFC 5389 and RFC 5766 for ALTERNATE-SERVER func‐
619 tionality description. The client must use the obtained value
620 for subsequent TURN communications. If more than one --alter‐
621 nate-server options are provided, then the functionality can be
622 more accurately described as "load-balancing" than a mere "redi‐
623 rection". If the port number is omitted, then the default port
624 number 3478 for the UDP/TCP protocols will be used. Colon (:)
625 characters in IPv6 addresses may conflict with the syntax of the
626 option. To alleviate this conflict, literal IPv6 addresses are
627 enclosed in square brackets in such resource identifiers, for
628 example: [2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 . Multiple
629 alternate servers can be set. They will be used in the
630 round-robin manner. All servers in the pool are considered of
631 equal weight and the load will be distributed equally. For exam‐
632 ple, if we have 4 alternate servers, then each server will re‐
633 ceive 25% of ALLOCATE requests. An alternate TURN server address
634 can be used more than one time with the alternate-server option,
635 so this can emulate "weighting" of the servers.
636 --tls-alternate-server
638 Option to set alternative server for TLS & DTLS services in form
639 of <ip>:<port>. If the port number is omitted, then the default
640 port number 5349 for the TLS/DTLS protocols will be used. See
641 the previous option for the functionality description.
642 -O, --redis-statsdb
644 Redis status and statistics database connection string, if used
645 (default - empty, no Redis stats DB used). This database keeps
646 allocations status information, and it can be also used for pub‐
647 lishing and delivering traffic and allocation event notifica‐
648 tions. This database option can be used independently of --re‐
649 dis-userdb option, and actually Redis can be used for sta‐
650 tus/statistics and SQLite or MySQL or MongoDB or PostgreSQL can
651 be used for the user database. The connection string has the
652 same parameters as redis-userdb connection string.
653 --max-allocate-timeout
655 Max time, in seconds, allowed for full allocation establishment.
656 Default is 60 seconds.
657 --denied-peer-ip=<IPaddr[-IPaddr]>
659 --allowed-peer-ip=<IPaddr[-IPaddr]> Options to ban or allow specific ip
661 addresses or ranges of ip addresses. If an ip address is specified as
662 both allowed and denied, then the ip address is considered to be al‐
663 lowed. This is useful when you wish to ban a range of ip addresses, ex‐
664 cept for a few specific ips within that range. This can be used when
665 you do not want users of the turn server to be able to access machines
666 reachable by the turn server, but would otherwise be unreachable from
667 the internet (e.g. when the turn server is sitting behind a NAT). The
668 'white" and "black" peer IP ranges can also be dynamically changed in
669 the database. The allowed/denied addresses (white/black lists) rules
670 are very simple:
671 1) If there is no rule for an address, then it is allowed;
673 2) If there is an "allowed" rule that fits the address then it
675 is allowed - no matter what;
676 3) If there is no "allowed" rule that fits the address, and if
678 there is a "denied" rule that fits the address, then it is
679 denied.
680 --pidfile
682 File name to store the pid of the process. Default is
683 /var/run/turnserver.pid (if superuser account is used) or
684 /var/tmp/turnserver.pid .
685 --acme-redirect
687 <URL> Redirect ACME/RFC8555 (like Let's Encrypt challenge) re‐
688 quests, i.e. HTTP GET requests matching
689 '^/.well-known/acme-challenge/(.*)' to <URL>$1 with $1 == (.*).
690 No validation of <URL> will be done, so make sure you do not
691 forget the trailing slash. If <URL> is an empty string (the de‐
692 fault value), no special handling of such requests will be done.
693 --proc-user
695 User name to run the process. After the initialization, the
696 turnserver process will make an attempt to change the current
697 user ID to that user.
698 --proc-group
700 Group name to run the process. After the initialization, the
701 turnserver process will make an attempt to change the current
702 group ID to that group.
703 -K, --keep-address-family
705 Deprecated and will be removed in favor of --allocation-de‐
706 fault-address-family!! TURN server allocates address family ac‐
707 cording TURN Client <=> Server communication address family. !!
708 It breaks RFC6156 section-4.2 (violates default IPv4) !!
709 -A --allocation-default-address-family=<ipv4|ipv6|keep>
711 Default is IPv4 TURN server allocates address family according
712 TURN client requested address family. If address family not re‐
713 quested explicitly by the client, then it falls back to this de‐
714 fault. The standard RFC explicitly define that this default
715 must be IPv4, so use other option values with care!
716 --cli-ip
718 Local system IP address to be used for CLI management interface.
719 The turnserver process can be accessed for management with tel‐
720 net, at this IP address and on the CLI port (see the next param‐
721 eter). Default value is 127.0.0.1. You can use telnet or putty
722 (in telnet mode) to access the CLI management interface.
723 --cli-port
725 CLI management interface listening port. Default is 5766.
726 --cli-password
728 CLI access password. Default is empty (no password). For the
729 security reasons, it is recommended to use the encrypted form of
730 the password (see the -P command in the turnadmin utility). The
731 dollar signs in the encrypted form must be escaped.
732 --cli-max-output-sessions
734 Maximum number of output sessions in ps CLI command. This value
735 can be changed on-the-fly in CLI. The default value is 256.
736 --web-admin
738 Enable Turn Web-admin support. By default it is disabled.
739 --web-admin-ip=<IP>
741 Local system IP address to be used for Web-admin server end‐
742 point. Default value is 127.0.0.1.
743 --web-admin-port=<port>
745 Web-admin server port. Default is 8080.
746 --web-admin-listen-on-workers
748 Enable for web-admin server to listens on STUN/TURN workers
749 STUN/TURN ports. By default it is disabled for security rea‐
750 sons! (This behavior used to be the default behavior, and was
751 enabled by default.)
752 --ne=[1|2|3]
754 Set network engine type for the process (for internal purposes).
755 --no-rfc5780
757 Disable RFC5780 (NAT behavior discovery). Originally, if there
758 are more than one listener address from the same address family,
759 then by default the NAT behavior discovery feature enabled.
760 This option disables this original behavior, because the NAT be‐
761 havior discovery adds attributes to response, and this increase
762 the possibility of an amplification attack. Strongly encouraged
763 to use this option to decrease gain factor in STUN binding re‐
764 sponses.
765 --no-stun-backward-compatibility
767 Disable handling old STUN Binding requests and disable
768 MAPPED-ADDRESS attribute in binding response (use only the
769 XOR-MAPPED-ADDRESS).
770 --response-origin-only-with-rfc5780
772 Only send RESPONSE-ORIGIN attribute in binding response if
773 RFC5780 is enabled.
774
777 This topic is covered in the wiki page:
778 https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance
780
783 This is a set of notes for the WebRTC users:
784 1) WebRTC uses long-term authentication mechanism, so you have to use
786 -a option (or --lt-cred-mech). WebRTC relaying will not work with
787 anonymous access. With -a option, do not forget to set the default
788 realm (-r option). You will also have to set up the user accounts,
789 for that you have a number of options:
790 a) command-line options (-u).
792 b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to
794 set keys with turnadmin utility (see docs and wiki for turnadmin).
795 You cannot use open passwords in the database.
796 c) Redis key/value pair(s), if Redis is used. You key use either keys or
798 open passwords with Redis; see turndb/testredisdbsetup.sh file.
799 d) You also can use the TURN REST API. You will need shared secret(s) set
801 either through the command line option, or through the config file, or through
802 the database table or Redis key/value pairs.
803 2) Usually WebRTC uses fingerprinting (-f).
806 3) -v option may be nice to see the connected clients.
808 4) -X is needed if you are running your TURN server behind a NAT.
810 5) --min-port and --max-port may be needed if you want to limit the
812 relay endpoints ports number range.
813
816 In WebRTC, the browser obtains the TURN connection information from the
817 web server. This information is a secure information - because it con‐
818 tains the necessary TURN credentials. As these credentials are trans‐
819 mitted over the public networks, we have a potential security breach.
820 If we have to transmit a valuable information over the public network,
822 then this information has to have a limited lifetime. Then the guy who
823 obtains this information without permission will be able to perform
824 only limited damage.
825 This is how the idea of TURN REST API - time-limited TURN credentials -
827 appeared. This security mechanism is based upon the long-term creden‐
828 tials mechanism. The main idea of the REST API is that the web server
829 provides the credentials to the client, but those credentials can be
830 used only limited time by an application that has to create a TURN
831 server connection.
832 The "classic" long-term credentials mechanism (LTCM) is described here:
834 http://tools.ietf.org/html/rfc5389#section-10.2
836 http://tools.ietf.org/html/rfc5389#section-15.4
838 For authentication, each user must know two things: the username and
840 the password. Optionally, the user must supply the ORIGIN value, so
841 that the server can figure out the realm to be used for the user. The
842 nonce and the realm values are supplied by the TURN server. But LTCM is
843 not saying anything about the nature and about the persistence of the
844 username and of the password; and this is used by the REST API.
845 In the TURN REST API, there is no persistent passwords for users. A
847 user has just the username. The password is always temporary, and it is
848 generated by the web server on-demand, when the user accesses the We‐
849 bRTC page. And, actually, a temporary one-time session only, username
850 is provided to the user, too.
851 The temporary user is generated as:
853 temporary-username="timestamp" + ":" + "username"
855 where username is the persistent user name, and the timestamp format is
857 just seconds since 1970 - the same value as time(NULL) function re‐
858 turns.
859 The temporary password is obtained as HMAC-SHA1 function over the tem‐
861 porary username, with shared secret as the HMAC key, and then the re‐
862 sult is encoded:
863 temporary-password = base64_encode(hmac-sha1(shared-secret, tempo‐
865 rary-username))
866 Both the TURN server and the web server know the same shared secret.
868 How the shared secret is distributed among the involved entities is
869 left to the WebRTC deployment details - this is beyond the scope of the
870 TURN REST API.
871 So, a timestamp is used for the temporary password calculation, and
873 this timestamp can be retrieved from the temporary username. This in‐
874 formation is valuable, but only temporary, while the timestamp is not
875 expired. Without knowledge of the shared secret, a new temporary pass‐
876 word cannot be generated.
877 This is all formally described in Justin's Uberti TURN REST API docu‐
879 ment that can be obtained following the link "TURN REST API" in the
880 TURN Server project's page https://github.com/coturn/coturn/.
881 Once the temporary username and password are obtained by the client
883 (browser) application, then the rest is just 'classic" long-term cre‐
884 dentials mechanism. For developers, we are going to describe it
885 step-by-step below:
886 • a new TURN client sends a request command to the TURN server.
888 Optionally, it adds the ORIGIN field to it.
889 • TURN server sees that this is a new client and the message is
891 not authenticated.
892 • the TURN server generates a random nonce string, and return
894 the error 401 to the client, with nonce and realm included.
895 If the ORIGIN field was present in the client request, it may
896 affect the realm value that the server chooses for the
897 client.
898 • the client sees the 401 error and it extracts two values from
900 the error response: the nonce and the realm.
901 • the client uses username, realm and password to produce a
903 key:
904 key = MD5(username ":" realm ":" SASLprep(password))
906 (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
907 • the client forms a new request, adds username, realm and
909 nonce to the request. Then, the client calculates and adds
910 the integrity field to the request. This is the trickiest
911 part of the process, and it is described in the end of sec‐
912 tion 15.4: http://tools.ietf.org/html/rfc5389#section-15.4
913 • the client, optionally, adds the fingerprint field. This may
915 be also a tricky procedure, described in section 15.5 of the
916 same document. WebRTC usually uses fingerprinted TURN mes‐
917 sages.
918 • the TURN server receives the request, reads the username.
920 • then the TURN server checks that the nonce and the realm in
922 the request are the valid ones.
923 • then the TURN server calculates the key.
925 • then the TURN server calculates the integrity field.
927 • then the TURN server compares the calculated integrity field
929 with the received one - they must be the same. If the integ‐
930 rity fields differ, then the request is rejected.
931 In subsequent communications, the client may go with exactly the same
933 sequence, but for optimization usually the client, having already in‐
934 formation about realm and nonce, pre-calculates the integrity string
935 for each request, so that the 401 error response becomes unnecessary.
936 The TURN server may use "--stale-nonce" option for extra security: in
937 some time, the nonce expires and the client will obtain 438 error re‐
938 sponse with the new nonce, and the client will have to start using the
939 new nonce.
940 In subsequent communications, the server and the client will always as‐
942 sume the same password - the original password becomes the session pa‐
943 rameter and is never expiring. So the password is not changing while
944 the session is valid and unexpired. So, if the session is properly
945 maintained, it may go forever, even if the user password has been al‐
946 ready changed (in the database). The session simply is using the old
947 password. Once the session got disconnected, the client will have to
948 use the new password to re-connect (if the password has been changed).
949 An example when a new shared secret is generated every hour by the TURN
951 server box and then supplied to the web server, remotely, is provided
952 in the script examples/scripts/restapi/shared_secret_maintainer.pl .
953 A very important thing is that the nonce must be totally random and it
955 must be different for different clients and different sessions.
956
959 For the user database, the turnserver has the following options:
960 1) Users can be set in the command line, with multiple -u or --user
962 options. Obviously, only a few users can be set that way, and
963 their credentials are fixed for the turnserver process lifetime.
964 2) Users can be stored in SQLite DB. The default SQLite database file
966 is /var/db/turndb or /usr/local/var/db/turndb or
967 /var/lib/turn/turndb.
968 3) Users can be stored in PostgreSQL database, if the turnserver was
970 compiled with PostgreSQL support. Each time turnserver checks user
971 credentials, it reads the database (asynchronously, of course, so
972 that the current flow of packets is not delayed in any way), so any
973 change in the database content is immediately visible by the
974 turnserver. This is the way if you need the best scalability. The
975 schema for the database can be found in schema.sql file. For
976 long-term credentials, you have to set the "keys" for the users;
977 the "keys" are generated by the turnadmin utility. For the key gen‐
978 eration, you need username, password and the realm. All users in
979 the database must use the same realm value; if down the road you
980 will decide to change the realm name, then you will have to re-gen‐
981 erate all user keys (that can be done in a batch script). See the
982 file turndb/testsqldbsetup.sql as an example.
983 4) The same is true for MySQL database. The same schema file is appli‐
985 cable. The same considerations are applicable.
986 5) The same is true for the Redis database, but the Redis database has
988 a different schema - it can be found (in the form of explanation)
989 in schema.userdb.redis. Also, in Redis you can store both "keys"
990 and open passwords (for long term credentials) - the "open pass‐
991 word" option is less secure but more convenient for low-security
992 environments. See the file turndb/testredisdbsetup.sh as an exam‐
993 ple.
994 6) If a database is used, then users can be divided into multiple in‐
996 dependent realms. Each realm can be administered separately, and
997 each realm can have its own set of users and its own performance
998 options (max-bps, user-quota, total-quota).
999 7) If you use MongoDB, the database will be setup for you automati‐
1001 cally.
1002 8) Of course, the turnserver can be used in non-secure mode, when
1004 users are allowed to establish sessions anonymously. But in most
1005 cases (like WebRTC) that will not work.
1006 For the status and statistics database, there are two choices:
1008 1) The simplest choice is not to use it. Do not set --redis-statsdb
1010 option, and this functionality will be simply ignored.
1011 2) If you choose to use it, then set the --redis-statsdb option. This
1013 may be the same database as in --redis-userdb option, or it may be
1014 a different database. You may want to use different database for
1015 security or convenience reasons. Also, you can use different data‐
1016 base management systems for the user database and for the ststus
1017 and statistics database. For example, you can use MySQL as the user
1018 database, and you can use redis for the statistics. Or you can use
1019 Redis for both.
1020 So, we have 6 choices for the user management, and 2 choices for the
1022 statistics management. These two are totally independent. So, you have
1023 overall 6*2=12 ways to handle persistent information, choose any for
1024 your convenience.
1025 You do not have to handle the database information "manually" - the
1027 turnadmin program can handle everything for you. For PostgreSQL and
1028 MySQL you will just have to create an empty database with schema.sql
1029 SQL script. With Redis, you do not have to do even that - just run tur‐
1030 nadmin and it will set the users for you (see the turnadmin manuals).
1031 If you are using SQLite, then the turnserver or turnadmin will initial‐
1032 ize the empty database, for you, when started. The TURN server instal‐
1033 lation process creates an empty initialized SQLite database in the de‐
1034 fault location (/var/db/turndb or /usr/local/var/db/turndb or
1035 /var/lib/turn/turndb, depending on the system).
1036
1039 The server supports ALPNs "stun.turn" and "stun.nat-discovery", when
1040 compiled with OpenSSL 1.0.2 or newer. If the server receives a TLS/DTLS
1041 ClientHello message that contains one or both of those ALPNs, then the
1042 server chooses the first stun.* label and sends it back (in the Server‐
1043 Hello) in the ALPN extension field. If no stun.* label is found, then
1044 the server does not include the ALPN information into the ServerHello.
1045
1048 In the lib/ sub-directory the build process will create TURN client
1049 messaging library. In the include/ sub-directory, the necessary in‐
1050 clude files will be placed. The C++ wrapper for the messaging func‐
1051 tionality is located in TurnMsgLib.h header. An example of C++ code
1052 can be found in stunclient.c file.
1053
1056 After installation, run the command:
1057 $ man turnserver
1059 or in the project root directory:
1061 $ man -M man turnserver
1063 to see the man page.
1065 In the docs/html subdirectory of the original archive tree, you will
1067 find the client library reference. After the installation, it will be
1068 placed in PREFIX/share/doc/turnserver/html.
1069
1072 When the TURN Server starts, it makes efforts to create a log file
1073 turn_<pid>.log in the following directories:
1074 • /var/log
1076 • /log/
1078 • /var/tmp
1080 • /tmp
1082 • current directory
1084 If all efforts failed (due to the system permission settings) then all
1086 log messages are sent only to the standard output of the process.
1087 This behavior can be controlled by --log-file, --syslog and --no-std‐
1089 out-log options.
1090
1093 The turnserver process provides an HTTPS Web access as statistics and
1094 basic management interface. The turnserver listens to incoming HTTPS
1095 admin connections on the same ports as the main TURN/STUN listener. The
1096 Web admin pages are basic and self-explanatory.
1097 To make the HTTPS interface active, the database table admin_user must
1099 be populated with the admin user account(s). An admin user can be a su‐
1100 peruser (if not assigned to a particular realm) or a restricted user
1101 (if assigned to a realm). The restricted admin users can perform only
1102 limited actions, within their corresponding realms.
1103
1106 The turnserver process provides a telnet CLI access as statistics and
1107 basic management interface. By default, the turnserver starts a telnet
1108 CLI listener on IP 127.0.0.1 and port 5766. That can be changed by the
1109 command-cline options of the turnserver process (see --cli-ip and
1110 --cli-port options). The full list of telnet CLI commands is provided
1111 in "help" command output in the telnet CLI.
1112
1115 TURN Server can be a part of the cluster installation. But, to support
1116 the "even port" functionality (RTP/RTCP streams pairs) the client re‐
1117 quests from a particular IP must be delivered to the same TURN Server
1118 instance, so it requires some networking setup massaging for the clus‐
1119 ter. The reason is that the RTP and RTCP relaying endpoints must be al‐
1120 located on the same relay IP. It would be possible to design a scheme
1121 with the application-level requests forwarding (and we may do that
1122 later) but it would affect the performance.
1123
1126 /etc/turnserver.conf
1127 /var/db/turndb
1129 /usr/local/var/db/turndb
1131 /var/lib/turn/turndb
1133 /usr/local/etc/turnserver.conf
1135
1138 /usr/local/share/turnserver
1139 /usr/local/share/doc/turnserver
1141 /usr/local/share/examples/turnserver
1143
1146 obsolete STUN RFC 3489
1147 new STUN RFC 5389
1149
1151 TURN-TCP extension RFC 6062
1152 TURN IPv6 extension RFC 6156
1154 STUN/TURN test vectors RFC 5769
1156 STUN NAT behavior discovery RFC 5780
1158
1161 turnadmin, turnutils
1162
1164 WEB RESOURCES
1165 project page:
1166 https://github.com/coturn/coturn/
1168 Wiki page:
1170 https://github.com/coturn/coturn/wiki
1172 forum:
1174 https://groups.google.com/forum/?fromgroups=#!fo‐
1176 rum/turn-server-project-rfc5766-turn-server
1177
1179 AUTHORS
1180 Oleg Moskalenko <mom040267@gmail.com>
1181 Gabor Kovesdan http://kovesdan.org/
1183 Daniel Pocock http://danielpocock.com/
1185 John Selbie (jselbie@gmail.com)
1187 Lee Sylvester <lee@designrealm.co.uk>
1189 Erik Johnston <erikj@openmarket.com>
1191 Roman Lisagor <roman@demonware.net>
1193 Vladimir Tsanev <tsachev@gmail.com>
1195 Po-sheng Lin <personlin118@gmail.com>
1197 Peter Dunkley <peter.dunkley@acision.com>
1199 Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
1201 Federico Pinna <fpinna@vivocha.com>
1203 Bradley T. Hughes <bradleythughes@fastmail.fm>
1205 Mihály Mészáros <misi@majd.eu>
1207 ACTIVE MAINTAINERS
1209 Mihály Mészáros <misi@majd.eu>
1210 05 June 2021 TURN(1)