coturn 命令[通俗易懂]

coturn 命令[通俗易懂]以下是引用自README.TURNSERVER,官方自带的文档。WEBRTC简单的例子:配置config: 1listening-device=eth0 2listening-port=3478 3relay-device=eth0 4Verbose 5lt-cred-mech 6min-port=49152 7max-por

以下是引用自README.TURNSERVER,官方自带的文档。

WEBRTC简单的例子:

配置config:

  1 listening-device=eth0
  2 listening-port=3478
  3 relay-device=eth0
  4 Verbose
  5 lt-cred-mech
  6 min-port=49152
  7 max-port=65535
  8 fingerprint
  9 use-auth-secret
 10 static-auth-secret=mqd
 11 user=mqd:mqd
 12 user=mqd:0xb0635aa4685ae81d4a3bee86ef95c0d5
 13 stale-nonce
 14 no-dtls
 15 no-cli
 16 cert=/etc/turn_server_cert.pem
 17 pkey=/etc/turn_server_pkey.pem
 18 log-file=/root/coturn/bin/my-turn.log
 19 no-loopback-peers
 20 no-multicast-peers
 21 #turnserver -o -a -f -v -r demo

turnserver -o -a -f -v -u mqd -p mqd -r demo 

使用turnutils_stunclient 可以测试stun服务

使用turnutils_uclient可以测试turn服务 (webrtc有时候不能工作是因为turn服务没通)

GENERAL INFORMATION

The TURN Server project contains the source code of a TURN server and TURN client 

messaging library. Also, some extra programs provided, for testing-only 

purposes. 

See the INSTALL file for the building instructions.

After the build, you will have the following binary images:

1.
turnserver: TURN Server relay. 

The compiled binary image of the TURN Server program is located in bin/ sub-directory.

2.
turnadmin: TURN administration tool. See README.turnadmin and turnadmin man page.

  

3.
turnutils_uclient. See README.turnutils and turnutils man page.

4.
turnutils_peer. See README.turnutils and turnutils man page.

   

5.
turnutils_stunclient. See README.turnutils and turnutils man page.

  

6.
turnutils_rfc5769check. See README.turnutils and turnutils man page.

In the "examples/scripts" sub-directory, you will find the examples of command lines to be used 

to run the programs. The scripts are meant to be run from examples/ sub-directory, for example:

$ cd examples

$ ./scripts/secure_relay.sh

  

RUNNING THE TURN SERVER

Options note: turnserver has long and short option names, for most options.

Some options have only long form, some options have only short form. Their syntax 

somewhat different, if an argument is required:

The short form must be used as this (for example):

  $ turnserver -L 12.34.56.78

  

The long form equivalent must use the "=" character:

  $ turnserver --listening-ip=12.34.56.78

  

If this is a flag option (no argument required) then their usage are the same, for example:

 $ turnserver -a

 

is equivalent to:

 $ turnserver --lt-cred-mech

  

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

  NAME

  

turnserver - a TURN relay server implementation.

  

  SYNOPSIS

  

$ 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]

$ turnserver -h

  

  DESCRIPTION


  

Config file settings:  

-n
Do not use configuration file, use only command line parameters.

-c
Configuration file name (default - turnserver.conf).


The format of config file can be seen in


the supplied examples/etc/turnserver.conf example file. Long 


names of the options are used as the configuration 


items names in the file. If not an absolute path is supplied, 


then the file is searched in the following directories: 


 * current directory


 * current directory etc/ sub-directory


 * upper directory level etc/


 * /etc/ 


 * /usr/local/etc/


 * installation directory /etc

User database settings:  

-b, --db, --userdb
SQLite user database file name (default - /var/db/turndb or


/usr/local/var/db/turndb or /var/lib/turn/turndb).


 

-e, --psql-userdb
User database connection string for PostgreSQL.


This database can be used for long-term credentials mechanism,


and it can store the secret value 


for secret-based timed authentication in TURN RESP API.


The connection string format is like that:


 


"host=<host> dbname=<dbname> user=<db-user> password=<db-user-password> connect_timeout=<seconds>" 


(for 8.x or newer Postgres).





Or:





"postgresql://username:password@hostname:port/databasename" 


(for 9.x or newer Postgres). 


See the INSTALL file for more explanations and examples.





Also, see http://www.PostgreSQL.org for full PostgreSQL documentation.


 

-M, --mysql-userdb
User database connection string for MySQL or MariaDB. 


This database can be used for long-term credentials mechanism,


and it can store the secret value for 


secret-based timed authentication in TURN RESP API.


The connection string format is like that:


 


"host=<host> dbname=<dbname> user=<db-user> password=<db-user-password> connect_timeout=<seconds> read_timeout=<seconds>"


See the INSTALL file for more explanations and examples.





Also, see http://www.mysql.org or http://mariadb.org 


for full MySQL documentation.





Optional connection string parameters for the secure communications (SSL): 


ca, capath, cert, key, cipher 


(see http://dev.mysql.com/doc/refman/5.1/en/ssl-options.html for the 


command options description).




-J, --mongo-userdb
User database connection string for MongoDB. 


This database can be used for long-term credentials mechanism,


and it can store the secret value 


for secret-based timed authentication in TURN RESP API.


The connection string format is like that:


 


"mongodb://username:password@host:port/database?options"


See the INSTALL file for more explanations and examples.





Also, see http://docs.mongodb.org/manual/


for full MongoDB documentation.




-N, --redis-userdb
User database connection string for Redis. 


This database can be used for long-term
credentials mechanism,


and it can store the secret 


value for secret-based timed authentication in TURN RESP API.


The connection string format is like that:


 


"ip=<ip-addr> dbname=<db-number> password=<db-password> connect_timeout=<seconds>"


See the INSTALL file for more explanations and examples.





Also, see http://redis.io for full Redis documentation.

Flags:   

-v, --verbose
Moderate verbose mode.

-V, --Verbose
Extra verbose mode, very annoying and not recommended.

-o, --daemon
Run server as daemon.

-f, --fingerprint
Use fingerprints in the TURN messages. If an incoming request


contains a fingerprint, then TURN server will always add 


fingerprints to the messages in this session, regardless of the


per-server setting.

-a, --lt-cred-mech
Use long-term credentials mechanism (this one you need for WebRTC usage).

-z, --no-auth
Do not use any credentials mechanism, allow anonymous access. 


Opposite to -a and -A options. This is default option when no 


authentication-related options are set.


By default, no credential mechanism is used -


any user is allowed.

--use-auth-secret
TURN REST API flag.


Flag that sets a special WebRTC authorization option 


that is based upon authentication secret. The feature purpose 


is to support "TURN Server REST API" as described in


the TURN REST API section below.


This option uses timestamp as part of combined username:


usercombo -> "timestamp:username",


turn user -> usercombo,


turn password -> base64(hmac(input_buffer = usercombo, key = shared-secret)).


This allows TURN credentials to be accounted for a specific user id.


If you don't have a suitable id, the timestamp alone can be used.


This option is just turns on secret-based authentication.


The actual value of the secret is defined either by option static-auth-secret,


or can be found in the turn_secret table in the database.




--oauth
Support oAuth authentication, as in the third-party STUN/TURN RFC 7635.




--dh566
Use 566 bits predefined DH TLS key. Default size of the key is 1066.

--dh2066
Use 2066 bits predefined DH TLS key. Default size of the key is 1066.

--no-tlsv1
Do not allow TLSv1/DTLSv1 protocol.

--no-tlsv1_1
Do not allow TLSv1.1 protocol.

--no-tlsv1_2
Do not allow TLSv1.2/DTLSv1.2 protocol.

--no-udp
Do not start UDP client listeners.

--no-tcp
Do not start TCP client listeners.

--no-tls
Do not start TLS client listeners.

--no-dtls
Do not start DTLS client listeners.

--no-udp-relay
Do not allow UDP relay endpoints defined in RFC 5766, 


use only TCP relay endpoints as defined in RFC 6062.

--no-tcp-relay
Do not allow TCP relay endpoints defined in RFC 6062, 


use only UDP relay endpoints as defined in RFC 5766. 

--no-stdout-log
Flag to prevent stdout log messages.


By default, all log messages are going to both stdout and to


the configured log file. With this option everything will be going to 


the log file only (unless the log file itself is stdout).




--syslog
With this flag, all log will be redirected to the system log (syslog).

--simple-log
This flag means that no log file rollover will be used, and the log file


name will be constructed as-is, without PID and date appendage.


This option can be used, for example, together with the logrotate tool.




--secure-stun
Require authentication of the STUN Binding request.


By default, the clients are allowed anonymous access to the STUN Binding functionality.

-S, --stun-only
Run as STUN server only, all TURN requests will be ignored. 


Option to suppress TURN functionality, only STUN requests will be processed.

--no-stun
Run as TURN server only, all STUN requests will be ignored. 


Option to suppress STUN functionality, only TURN requests will be processed.

--no-loopback-peers
Disallow peers on the loopback addresses (127.x.x.x and ::1).

--no-multicast-peers
Disallow peers on well-known broadcast addresses 


(224.0.0.0 and above, and FFXX:*).

--mobility
Mobility with ICE (MICE) specs support.

--no-cli
Turn OFF the CLI support. By default it is always ON.


See also options --cli-ip and --cli-port.




--server-relay
Server relay. NON-STANDARD AND DANGEROUS OPTION. 


Only for those applications when we want to run 


server applications on the relay endpoints.


This option eliminates the IP permissions check 


on the packets incoming to the relay endpoints.


See http://tools.ietf.org/search/rfc5766#section-17.2.3 .




--udp-self-balance
(recommended for older Linuxes only)


Automatically balance UDP traffic over auxiliary servers


(if configured). The load balancing is using the 


ALTERNATE-SERVER mechanism. The TURN client must support 


300 ALTERNATE-SERVER response for this functionality.




--check-origin-consistency
The flag that sets the origin consistency 


check: across the session, all requests must have the same


main ORIGIN attribute value (if the ORIGIN was


initially used by the session).

-h
Help.

    

Options with values:  

--stale-nonce[=<value>]
Use extra security with nonce value having


limited lifetime, in seconds (default 600 secs).

--max-allocate-lifetime
Set the maximum value for the allocation lifetime.


Default to 3600 secs.

--channel-lifetime
Set the lifetime for channel binding, default to 600 secs.


This value MUST not be changed for production purposes.

--permission-lifetime
Set the value for the lifetime of the permission.


Default to 300 secs.


This MUST not be changed for production purposes.

-d, --listening-device
Listener interface device.


(NOT RECOMMENDED. Optional functionality, Linux only). 


The turnserver process must have root privileges to bind the 


listening endpoint to a device. If turnserver must run as a 


process without root privileges, then just do not use this setting.

-L, --listening-ip
Listener IP address of relay server. 


Multiple listeners can be specified, for example:


-L ip1 -L ip2 -L ip3


If no IP(s) specified, then all IPv4 and 


IPv6 system IPs will be used for listening.


The same ip(s) can be used as both listening and relay ip(s).

-p, --listening-port
TURN listener port for UDP and TCP listeners (Default: 3478).


Note: actually, TLS & DTLS sessions can connect to the "plain" TCP & UDP


port(s), too - if allowed by configuration.

--tls-listening-port
TURN listener port for TLS and DTLS listeners (Default: 5349).


Note: actually, "plain" TCP & UDP sessions can connect to the TLS & DTLS


port(s), too - if allowed by configuration. The TURN server 


"automatically" recognizes the type of traffic. Actually, two listening


endpoints (the "plain" one and the "tls" one) are equivalent in terms of


functionality; but we keep both endpoints to satisfy the RFC 5766 specs.


For secure TCP connections, we currently support SSL version 3 and 


TLS versions 1.0, 1.1, 1.2.


For secure UDP connections, we support DTLS version 1.

--alt-listening-port
Alternative listening port for UDP and TCP listeners;


default (or zero) value means "listening port plus one".


This is needed for STUN CHANGE_REQUEST - in RFC 5780 sense

               
or in old RFC 3489 sense - for NAT behavior discovery). The TURN Server


supports CHANGE_REQUEST only if it is started with more than one


listening IP address of the same family (IPv4 or IPv6). The CHANGE_REQUEST


is only supported by UDP protocol, other protocols are listening


on that endpoint only for "symmetry".

--alt-tls-listening-port
Alternative listening port for TLS and DTLS protocols.


Default (or zero) value means "TLS listening port plus one".




--aux-server
Auxiliary STUN/TURN server listening endpoint.


Aux servers have almost full TURN and STUN functionality.


The (minor) limitations are:


1) Auxiliary servers do not have alternative ports and


they do not support STUN RFC 5780 functionality (CHANGE REQUEST).


2) Auxiliary servers also are never returning ALTERNATIVE-SERVER reply.





Valid formats are 1.2.3.4:5555 for IPv4 and [1:2::3:4]:5555 for IPv6.


There may be multiple aux-server options, each will be used for listening


to client requests.

-i, --relay-device
Relay interface device for relay sockets 


(NOT RECOMMENDED. Optional, Linux only).

-E, --relay-ip
Relay address (the local IP address that 


will be used to relay the packets to the 


peer). Multiple relay addresses may be used:


-E ip1 -E ip2 -E ip3


The same IP(s) can be used as both listening IP(s) and relay IP(s).


If no relay IP(s) specified, then the turnserver will apply the 


default policy: it will decide itself which relay addresses to be 


used, and it will always be using the client socket IP address as 


the relay IP address of the TURN session (if the requested relay 


address family is the same as the family of the client socket).

-X, --external-ip
TURN Server public/private address mapping, if the server is behind NAT.


In that situation, if a -X is used in form "-X <ip>" then that ip will be reported


as relay IP address of all allocations. This scenario works only in a simple case


when one single relay address is be used, and no CHANGE_REQUEST functionality is 


required. That single relay address must be mapped by NAT to the 'external' IP.


The "external-ip" value, if not empty, is returned in XOR-RELAYED-ADDRESS field.


For that 'external' IP, NAT must forward ports directly (relayed port 12345


must be always mapped to the same 'external' port 12345).


In more complex case when more than one IP address is involved,


that option must be used several times, each entry must


have form "-X <public-ip/private-ip>", to map all involved addresses.


CHANGE_REQUEST (RFC5780 or RFC3489) NAT discovery STUN functionality will work 


correctly, if the addresses are mapped properly, even when the TURN server itself 


is behind A NAT.


By default, this value is empty, and no address mapping is used.




-m, --relay-threads
Number of the relay threads to handle the established connections


(in addition to authentication thread and the listener thread).


If explicitly set to 0 then application runs relay process in a single thread,


in the same thread with the listener process (the authentication thread will 


still be a separate thread). If not set, then a default optimal algorithm 


will be employed (OS-dependent). In the older Linux systems


(before Linux kernel 3.9), the number of UDP threads is always one threads 


per network listening endpoint - unless "-m 0" or "-m 1" is set.

--min-port
Lower bound of the UDP port range for relay 


endpoints allocation.


Default value is 49152, according to RFC 5766.

--max-port
Upper bound of the UDP port range for relay 


endpoints allocation.


Default value is 65535, according to RFC 5766.

-u, --user
Long-term security mechanism credentials user account, 


in the column-separated form username:key. 


Multiple user accounts may be used in the command line.


The key is either the user password, or


the key is generated


by turnadmin command. In the second case,


the key must be prepended with 0x symbols.


The key is calculated over the user name, 


the user realm, and the user password.


This setting may not be used with TURN REST API.

-r, --realm
The default realm to be used for the users when no explicit 


origin/realm relationship was found in the database, or if the TURN


server is not using any database (just the commands-line settings


and the userdb file). Must be used with long-term credentials 


mechanism or with TURN REST API.

-C, --rest-api-separator
This is the timestamp/username separator symbol 


(character) in TURN REST API. The default value is :.

-q, --user-quota
Per-user allocations quota: how many concurrent 


allocations a user can create. This option can also be set 


through the database, for a particular realm.

-Q, --total-quota
Total allocations quota: global limit on concurrent allocations.


This option can also be set through the database, for a particular realm.

-s, --max-bps
Max bytes-per-second bandwidth a TURN session is allowed to handle


(input and output network streams are treated separately). Anything above 


that limit will be dropped or temporary suppressed (within the


available buffer limits). This option can also be set through the 


database, for a particular realm.




-B, --bps-capacity
Maximum server capacity.


Total bytes-per-second bandwidth the TURN server is allowed to allocate


for the sessions, combined (input and output network streams are treated


separately).

--static-auth-secret
Static authentication secret value (a string) for TURN REST API only.


If not set, then the turn server will try to use the dynamic value 


in turn_secret table in user database (if present). The database-stored


value can be changed on-the-fly by a separate program, so this is why


that other mode is dynamic. Multiple shared secrets can be used


(both in the database and in the "static" fashion).




--server-name
Server name used for


the oAuth authentication purposes.


The default value is the realm name.

--cert
Certificate file, PEM format. Same file 


search rules applied as for the configuration 


file. If both --no-tls and --no-dtls options 


are specified, then this parameter is not needed.


Default value is turn_server_cert.pem.

--pkey
   
Private key file, PEM format. Same file 


search rules applied as for the configuration 


file. If both --no-tls and --no-dtls options 


are specified, then this parameter is not needed.


Default value is turn_server_pkey.pem.




--pkey-pwd
If the private key file is encrypted, then this password to be used.

--cipher-list
Allowed OpenSSL cipher list for TLS/DTLS connections.


Default value is "DEFAULT".




--CA-file
CA file in OpenSSL format. 


Forces TURN server to verify the client SSL certificates.


By default, no CA is set and no client certificate check is performed.

--ec-curve-name
Curve name for EC ciphers, if supported by OpenSSL 


library (TLS and DTLS). The default value is prime256v1, 


if pre-OpenSSL 1.0.2 is used. With OpenSSL 1.0.2+,


an optimal curve will be automatically calculated, if not defined


by this option.

--dh-file
Use custom DH TLS key, stored in PEM format in the file.


Flags --dh566 and --dh2066 are ignored when the DH key is taken from a file.

-l, --log-file
Option to set the full path name of the log file.


By default, the turnserver tries to open a log file in 


/var/log/turnserver, /var/log, /var/tmp, /tmp and . (current) 


directories (which file open operation succeeds 


first that file will be used). With this option you can set the 


definite log file name.


The special names are "stdout" and "-" - they will force everything 


to the stdout. Also, "syslog" name will redirect everything into


the system log (syslog), as if the option "--syslog" was set. 


In the runtime, the logfile can be reset with the SIGHUP signal 


to the turnserver process.




--alternate-server
Option to set the "redirection" mode. The value of this option


will be the address of the alternate server for UDP & TCP service in form of 


<ip>[:<port>]. The server will send this value in the attribute


ALTERNATE-SERVER, with error 300, on ALLOCATE request, to the client.


Client will receive only values with the same address family


as the client network endpoint address family. 


See RFC 5389 and RFC 5766 for ALTERNATE-SERVER functionality description. 


The client must use the obtained value for subsequent TURN communications.


If more than one --alternate-server options are provided, then the functionality


can be more accurately described as "load-balancing" than a mere "redirection". 


If the port number is omitted, then the default port 


number 3478 for the UDP/TCP protocols will be used.


Colon (:) characters in IPv6 addresses may conflict with the syntax of 


the option. To alleviate this conflict, literal IPv6 addresses are enclosed 


in square brackets in such resource identifiers, for example: 


[2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 . 


Multiple alternate servers can be set. They will be used in the


round-robin manner. All servers in the pool are considered of equal weight and 


the load will be distributed equally. For example, if we have 4 alternate servers, 


then each server will receive 25% of ALLOCATE requests. An alternate TURN server 


address can be used more than one time with the alternate-server option, so this 


can emulate "weighting" of the servers. 

--tls-alternate-server
Option to set alternative server for TLS & DTLS services in form of 


<ip>:<port>. If the port number is omitted, then the default port 


number 5349 for the TLS/DTLS protocols will be used. See the 


previous option for the functionality description.

-O, --redis-statsdb
Redis status and statistics database connection string, if used (default - empty, 


no Redis stats DB used). This database keeps allocations status information, and it can 


be also used for publishing and delivering traffic and allocation event notifications.


This database option can be used independently of --redis-userdb option,


and actually Redis can be used for status/statistics and SQLite or MySQL or MongoDB or 


PostgreSQL can be used for the user database.


The connection string has the same parameters as redis-userdb connection string.

--max-allocate-timeout
Max time, in seconds, allowed for full allocation establishment. 


Default is 60 seconds.

--denied-peer-ip=<IPaddr[-IPaddr]>

--allowed-peer-ip=<IPaddr[-IPaddr]> Options to ban or allow specific ip addresses or ranges 


of ip addresses. If an ip address is specified as both allowed and denied, then 


the ip address is considered to be allowed. This is useful when you wish to ban


a range of ip addresses, except for a few specific ips within that range.


This can be used when you do not want users of the turn server to be able to access


machines reachable by the turn server, but would otherwise be unreachable from the 


internet (e.g. when the turn server is sitting behind a NAT). The 'white" and "black" peer 


IP ranges can also be dynamically changed in the database. 


The allowed/denied addresses (white/black lists) rules are very simple:


1) If there is no rule for an address, then it is allowed; 


2) If there is an "allowed" rule that fits the address then it is allowed - no matter what;


3) If there is no "allowed" rule that fits the address, and if there is a "denied" rule that


fits the address, then it is denied.

--pidfile
File name to store the pid of the process.


Default is /var/run/turnserver.pid (if superuser account is used) or


/var/tmp/turnserver.pid .




--proc-user
User name to run the process. After the initialization, the turnserver process


will make an attempt to change the current user ID to that user.




--proc-group
Group name to run the process. After the initialization, the turnserver process


will make an attempt to change the current group ID to that group.




--cli-ip
Local system IP address to be used for CLI management interface.


The turnserver process can be accessed for management with telnet,


at this IP address and on the CLI port (see the next parameter). 


Default value is 127.0.0.1. You can use telnet or putty (in telnet mode)


to access the CLI management interface. 




--cli-port
CLI management interface listening port. Default is 5766.

--cli-password
CLI access password. Default is empty (no password).


For the security reasons, it is recommended to use the encrypted


form of the password (see the -P command in the turnadmin


utility). The dollar signs in the encrypted form must be escaped.

--cli-max-output-sessions
Maximum number of output sessions in ps CLI command.


This value can be changed on-the-fly in CLI. The default value is 256.

--ne=[1|2|3]
Set network engine type for the process (for internal purposes).

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

LOAD BALANCE AND PERFORMANCE TUNING

This topic is covered in the wiki page:

https://github.com/coturn/coturn/wiki/turn_performance_and_load_balance


 

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

WEBRTC USAGE

This is a set of notes for the WebRTC users:

1) WebRTC uses long-term authentication mechanism, so you have to use -a 

option (or --lt-cred-mech). WebRTC relaying will not work with anonymous

access. With -a option, do not forget to set the 

default realm (-r option). You will also have to set up the user accounts, 

for that you have a number of options:


a) command-line options (-u).





b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to 


set keys with turnadmin utility (see docs and wiki for turnadmin). 


You cannot use open passwords in the database.


c) Redis key/value pair(s), if Redis is used. You key use either keys or 


open passwords with Redis; see turndb/testredisdbsetup.sh file.  





d) You also can use the TURN REST API. You will need shared secret(s) set


either
through the command line option, or through the config file, or through


the database table or Redis key/value pairs.  

2) Usually WebRTC uses fingerprinting (-f).

3) -v option may be nice to see the connected clients.

4) -X is needed if you are running your TURN server behind a NAT.

5) --min-port and --max-port may be needed if you want to limit the relay endpoints ports 

number range.

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

TURN REST API

In WebRTC, the browser obtains the TURN connection information from the web

server. This information is a secure information - because it contains the 

necessary TURN credentials. As these credentials are transmitted over the 

public networks, we have a potential security breach.

If we have to transmit a valuable information over the public network, 

then this information has to have a limited lifetime. Then the guy who 

obtains this information without permission will be able to perform 

only limited damage.

This is how the idea of TURN REST API - time-limited TURN credentials - 

appeared. This security mechanism is based upon the long-term credentials 

mechanism. The main idea of the REST API is that the web server provides 

the credentials to the client, but those credentials can be used only 

limited time by an application that has to create a TURN server connection.

The "classic" long-term credentials mechanism (LTCM) is described here:

http://tools.ietf.org/html/rfc5389#section-10.2

http://tools.ietf.org/html/rfc5389#section-15.4

For authentication, each user must know two things: the username and the

password. Optionally, the user must supply the ORIGIN value, so that the

server can figure out the realm to be used for the user. The nonce and 

the realm values are supplied by the TURN server. But LTCM is not saying 

anything about the nature and about the persistence of the username and 

of the password; and this is used by the REST API.

In the TURN REST API, there is no persistent passwords for users. A user has 

just the username. The password is always temporary, and it is generated by 

the web server on-demand, when the user accesses the WebRTC page. And, 

actually, a temporary one-time session only, username is provided to the user, 

too. 

The temporary user is generated as:

temporary-username="timestamp" + ":" + "username"

where username is the persistent user name, and the timestamp format is just 

seconds sinse 1970 - the same value as time(NULL) function returns.

The temporary password is obtained as HMAC-SHA1 function over the temporary

username, with shared secret as the HMAC key, and then the result is encoded:

temporary-password = base64_encode(hmac-sha1(shared-secret, temporary-username))

Both the TURN server and the web server know the same shared secret. How the

shared secret is distributed among the involved entities is left to the WebRTC

deployment details - this is beyond the scope of the TURN REST API.

So, a timestamp is used for the temporary password calculation, and this 

timestamp can be retrieved from the temporary username. This information

is valuable, but only temporary, while the timestamp is not expired. Without

knowledge of the shared secret, a new temporary password cannot be generated.

This is all formally described in Justin's Uberti TURN REST API document

that can be obtained following the link "TURN REST API" in the TURN Server

project's page https://github.com/coturn/coturn/.

Once the temporary username and password are obtained by the client (browser)

application, then the rest is just 'classic" long-term credentials mechanism.

For developers, we are going to describe it step-by-step below:

  - a new TURN client sends a request command to the TURN server. Optionally, 

  it adds the ORIGIN field to it. 

  - TURN server sees that this is a new client and the message is not 

 
authenticated.

  - the TURN server generates a random nonce string, and return the 

 
error 401 to the client, with nonce and realm included. If the ORIGIN

 
field was present in the client request, it may affect the realm value

 
that the server chooses for the client.

  - the client sees the 401 error and it extracts two values from 

 
the error response: the nonce and the realm.

  - the client uses username, realm and password to produce a key:

         key = MD5(username ":" realm ":" SASLprep(password))

 (SASLprep is described here: http://tools.ietf.org/html/rfc4013)

 

  - the client forms a new request, adds username, realm and nonce to the 

 
request. Then, the client calculates and adds the integrity field to 

 
the request. This is the trickiest part of the process, and it is

 
described in the end of section 15.4: 

 
http://tools.ietf.org/html/rfc5389#section-15.4

  - the client, optionally, adds the fingerprint field. This may be also 

 
a tricky procedure, described in section 15.5 of the same document. 

 
WebRTC usually uses fingerprinted TURN messages.

  - the TURN server receives the request, reads the username.

  - then the TURN server checks that the nonce and the realm in the request 

 
are the valid ones.

  - then the TURN server calculates the key.

  - then the TURN server calculates the integrity field.

  - then the TURN server compares the calculated integrity field with the 

 
received one - they must be the same. If the integrity fields differ, 

 
then the request is rejected.

In subsequent communications, the client may go with exactly the same 

sequence, but for optimization usually the client, having already 

information about realm and nonce, pre-calculates the integrity string 

for each request, so that the 401 error response becomes unnecessary. 

The TURN server may use "--stale-nonce" option for extra security: in 

some time, the nonce expires and the client will obtain 438 error response

with the new nonce, and the client will have to start using the new nonce.

In subsequent communications, the sever and the client will always assume 

the same password - the original password becomes the session parameter and 

is never expiring. So the password is not changing while the session is valid

and unexpired. So, if the session is properly maintained, it may go forever, 

even if the user password has been already changed (in the database). The 

session simply is using the old password. Once the session got disconnected, 

the client will have to use the new password to re-connect (if the password 

has been changed).

An example when a new shared secret is generated every hour by the TURN server

box and then supplied to the web server, remotely, is provided in the script

examples/scripts/restapi/shared_secret_maintainer.pl .

A very important thing is that the nonce must be totally random and it must be 

different for different clients and different sessions. 


 

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

DATABASES

For the user database, the turnserver has the following options:

1) Users can be set in the command line, with multiple -u or --user options. 

Obviously, only a few users can be set that way, and their credentials are fixed 

for the turnserver process lifetime.

2) Users can be stored in SQLite DB. The default SQLite database file is /var/db/turndb

or /usr/local/var/db/turndb or /var/lib/turn/turndb.

3) Users can be stored in PostgreSQL database, if the turnserver was compiled with PostgreSQL

support. Each time turnserver checks user credentials, it reads the database (asynchronously,

of course, so that the current flow of packets is not delayed in any way), so any change in the 

database content is immediately visible by the turnserver. This is the way if you need the 

best scalability. The schema for the database can be found in schema.sql file.

For long-term credentials, you have to set the "keys" for the users; the "keys" are generated 

by the turnadmin utility. For the key generation, you need username, password and the realm. 

All users in the database must use the same realm value; if down the road you will decide 

to change the realm name, then you will have to re-generate all user keys (that can be done 

in a batch script). See the file turndb/testsqldbsetup.sql as an example.

4) The same is true for MySQL database. The same schema file is applicable. 

The same considerations are applicable. 

5) The same is true for the Redis database, but the Redis database has aa different schema -

it can be found (in the form of explanation) in schema.userdb.redis. 

Also, in Redis you can store both "keys" and open passwords (for long term credentials) - 

the "open password" option is less secure but more convenient for low-security environments. 

See the file turndb/testredisdbsetup.sh as an example. 

6) If a database is used, then users can be divided into multiple independent realms. Each realm

can be administered separately, and each realm can have its own set of users and its own

performance options (max-bps, user-quota, total-quota).

7) If you use MongoDB, the database will be setup for you automatically.

8) Of course, the turnserver can be used in non-secure mode, when users are allowed to establish

sessions anonymously. But in most cases (like WebRTC) that will not work.

For the status and statistics database, there are two choices:

1) The simplest choice is not to use it. Do not set --redis-statsdb option, and this functionality 

will be simply ignored.

2) If you choose to use it, then set the --redis-statsdb option. This may be the same database

as in --redis-userdb option, or it may be a different database. You may want to use different 

database for security or convenience reasons. Also, you can use different database management

systems for the user database and for the ststus and statistics database. For example, you can use 

MySQL as the user database, and you can use redis for the statistics. Or you can use Redis for both.

So, we have 6 choices for the user management, and 2 choices for the statistics management. These

two are totally independent. So, you have overall 6*2=12 ways to handle persistent information, 

choose any for your convenience.

You do not have to handle the database information "manually" - the turnadmin program can handle 

everything for you. For PostgreSQL and MySQL you will just have to create an empty database

with schema.sql SQL script. With Redis, you do not have to do even that - just run turnadmin and 

it will set the users for you (see the turnadmin manuals). If you are using SQLite, then the 

turnserver or turnadmin will initialize the empty database, for you, when started. The 

TURN server installation process creates an empty initialized SQLite database in the default 

location (/var/db/turndb or /usr/local/var/db/turndb or /var/lib/turn/turndb, depending on the system).

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

ALPN

The server supports ALPNs "stun.turn" and "stun.nat-discovery", when

compiled with OpenSSL 1.0.2 or newer. If the server receives a TLS/DTLS

ClientHello message that contains one or both of those ALPNs, then the

server chooses the first stun.* label and sends it back (in the ServerHello)

in the ALPN extension field. If no stun.* label is found, then the server

does not include the ALPN information into the ServerHello.

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

LIBRARIES

In the lib/ sub-directory the build process will create TURN client messaging library.

In the include/ sub-directory, the necessary include files will be placed.

The C++ wrapper for the messaging functionality is located in TurnMsgLib.h header.

An example of C++ code can be found in stunclient.c file. 

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

DOCS

After installation, run the command:

$ man turnserver

or in the project root directory:

$ man -M man turnserver

to see the man page.

In the docs/html subdirectory of the original archive tree, you will find the client library 

reference. After the installation, it will be placed in PREFIX/share/doc/turnserver/html.

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

LOGS

When the TURN Server starts, it makes efforts to create a log file turn_<pid>.log 

in the following directories:


* /var/log


* /log/


* /var/tmp


* /tmp


* current directory

If all efforts failed (due to the system permission settings) then all 

log messages are sent only to the standard output of the process.

This behavior can be controlled by --log-file, --syslog and --no-stdout-log

options.

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

HTTPS MANAGEMENT INTERFACE

The turnserver process provides an HTTPS Web access as statistics and basic

management interface. The turnserver listens to incoming HTTPS admin 

connections on the same ports as the main TURN/STUN listener. The Web admin

pages are basic and self-explanatory.

To make the HTTPS interface active, the database table admin_user must be

populated with the admin user account(s). An admin user can be a superuser

(if not assigned to a particular realm) or a restricted user (if assigned to

a realm). The restricted admin users can perform only limited actions, within

their corresponding realms.

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

TELNET CLI

The turnserver process provides a telnet CLI access as statistics and basic management

interface. By default, the turnserver starts a telnet CLI listener on IP 127.0.0.1 and

port 5766. That can be changed by the command-cline options of the turnserver process

(see --cli-ip and --cli-port options). The full list of telnet CLI commands is provided

in "help" command output in the telnet CLI.

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

CLUSTERS

TURN Server can be a part of the cluster installation. But, to support the "even port" functionality 

(RTP/RTCP streams pairs) the client requests from a particular IP must be delivered to the same 

TURN Server instance, so it requires some networking setup massaging for the cluster. The reason is that 

the RTP and RTCP relaying endpoints must be allocated on the same relay IP. It would be possible 

to design a scheme with the application-level requests forwarding (and we may do that later) but 

it would affect the performance.

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

FILES

/etc/turnserver.conf

/var/db/turndb

/usr/local/var/db/turndb

/var/lib/turn/turndb

/usr/local/etc/turnserver.conf

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

DIRECTORIES

/usr/local/share/turnserver

/usr/local/share/doc/turnserver

/usr/local/share/examples/turnserver

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

STANDARDS

obsolete STUN RFC 3489

new STUN RFC 5389

TURN RFC 5766

TURN-TCP extension RFC 6062

 

TURN IPv6 extension RFC 6156

STUN/TURN test vectors RFC 5769

STUN NAT behavior discovery RFC 5780

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

SEE ALSO


turnadmin, turnutils

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

  WEB RESOURCES

project page:

https://github.com/coturn/coturn/

Wiki page:

https://github.com/coturn/coturn/wiki

forum:

https://groups.google.com/forum/?fromgroups=#!forum/turn-server-project-rfc5766-turn-server

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

  AUTHORS


Oleg Moskalenko <mom040267@gmail.com>


Gabor Kovesdan http://kovesdan.org/


Daniel Pocock http://danielpocock.com/


John Selbie (jselbie@gmail.com)


Lee Sylvester <lee@designrealm.co.uk>


Erik Johnston <erikj@openmarket.com>


Roman Lisagor <roman@demonware.net>





Vladimir Tsanev <tsachev@gmail.com>





Po-sheng Lin <personlin118@gmail.com>





Peter Dunkley <peter.dunkley@acision.com>





Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>


Federico Pinna <fpinna@vivocha.com>


Bradley T. Hughes <bradleythughes@fastmail.fm>

        Mihaly Meszaros <bakfitty@gmail.com>

架构君码字不易,如需转载,请注明出处:https://javajgs.com/archives/222479
0
 

发表评论