|
|
@@ -2,9 +2,9 @@
|
|
|
.TH TURN 1 "28 April 2020" "" ""
|
|
|
.SH GENERAL INFORMATION
|
|
|
|
|
|
-The \fBTURN Server\fP project contains the source code of a TURN server and TURN client
|
|
|
-messaging library. Also, some extra programs provided, for testing\-only
|
|
|
-purposes.
|
|
|
+The \fBTURN Server\fP project contains the source code of a TURN server and TURN client
|
|
|
+messaging library. Also, some extra programs provided, for testing\-only
|
|
|
+purposes.
|
|
|
.PP
|
|
|
See the INSTALL file for the building instructions.
|
|
|
.PP
|
|
|
@@ -12,7 +12,7 @@ After the build, you will have the following binary images:
|
|
|
.TP
|
|
|
.B
|
|
|
1.
|
|
|
-\fIturnserver\fP: \fBTURN Server\fP relay.
|
|
|
+\fIturnserver\fP: \fBTURN Server\fP relay.
|
|
|
The compiled binary image of the \fBTURN Server\fP program is located in bin/ sub\-directory.
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -35,7 +35,7 @@ turnutils_stunclient. See README.turnutils and \fIturnutils\fP man page.
|
|
|
6.
|
|
|
turnutils_rfc5769check. See README.turnutils and \fIturnutils\fP man page.
|
|
|
.PP
|
|
|
-In the "examples/scripts" sub\-directory, you will find the examples of command lines to be used
|
|
|
+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:
|
|
|
.PP
|
|
|
$ cd examples
|
|
|
@@ -43,7 +43,7 @@ $ ./scripts/secure_relay.sh
|
|
|
.SH RUNNING THE TURN SERVER
|
|
|
|
|
|
Options note: \fIturnserver\fP has long and short option names, for most options.
|
|
|
-Some options have only long form, some options have only short form. Their syntax
|
|
|
+Some options have only long form, some options have only short form. Their syntax
|
|
|
somewhat different, if an argument is required:
|
|
|
.PP
|
|
|
The short form must be used as this (for example):
|
|
|
@@ -94,10 +94,8 @@ $ \fIturnserver\fP \fB\-h\fP
|
|
|
.fi
|
|
|
.fam T
|
|
|
.fi
|
|
|
-.SS DESCRIPTION
|
|
|
+.SS DESCRIPTION
|
|
|
|
|
|
-.TP
|
|
|
-.B
|
|
|
Config file settings:
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -108,10 +106,10 @@ Do not use configuration file, use only command line parameters.
|
|
|
\fB\-c\fP
|
|
|
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 \fIoptions\fP 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:
|
|
|
+the supplied examples/etc/turnserver.conf example file. Long
|
|
|
+names of the \fIoptions\fP 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:
|
|
|
.RS
|
|
|
.IP \(bu 3
|
|
|
current directory
|
|
|
@@ -126,8 +124,7 @@ upper directory level etc/
|
|
|
.IP \(bu 3
|
|
|
installation directory /etc
|
|
|
.RE
|
|
|
-.TP
|
|
|
-.B
|
|
|
+.PP
|
|
|
User database settings:
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -139,18 +136,18 @@ SQLite user database file name (default \- /var/db/turndb or
|
|
|
\fB\-e\fP, \fB\-\-psql\-userdb\fP
|
|
|
User database connection string for PostgreSQL.
|
|
|
This database can be used for long\-term credentials mechanism,
|
|
|
-and it can store the secret value
|
|
|
+and it can store the secret value
|
|
|
for secret\-based timed authentication in TURN REST API.
|
|
|
The connection string format is like that:
|
|
|
.RS
|
|
|
.PP
|
|
|
-"host=<host> dbname=<dbname> user=<db\-user> password=<db\-user\-password> connect_timeout=<seconds>"
|
|
|
+"host=<host> dbname=<dbname> user=<db\-user> password=<db\-user\-password> connect_timeout=<seconds>"
|
|
|
(for 8.x or newer Postgres).
|
|
|
.PP
|
|
|
Or:
|
|
|
.PP
|
|
|
-"postgresql://username:password@hostname:port/databasename"
|
|
|
-(for 9.x or newer Postgres).
|
|
|
+"postgresql://username:password@hostname:port/databasename"
|
|
|
+(for 9.x or newer Postgres).
|
|
|
.PP
|
|
|
See the INSTALL file for more explanations and examples.
|
|
|
.PP
|
|
|
@@ -159,9 +156,9 @@ Also, see http://www.PostgreSQL.org for full PostgreSQL documentation.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-M\fP, \fB\-\-mysql\-userdb\fP
|
|
|
-User database connection string for MySQL or MariaDB.
|
|
|
+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
|
|
|
+and it can store the secret value for
|
|
|
secret\-based timed authentication in TURN REST API.
|
|
|
The connection string format is like that:
|
|
|
.RS
|
|
|
@@ -170,12 +167,12 @@ The connection string format is like that:
|
|
|
.PP
|
|
|
See the INSTALL file for more explanations and examples.
|
|
|
.PP
|
|
|
-Also, see http://www.mysql.org or http://mariadb.org
|
|
|
+Also, see http://www.mysql.org or http://mariadb.org
|
|
|
for full MySQL documentation.
|
|
|
.PP
|
|
|
-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
|
|
|
+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 \fIoptions\fP description).
|
|
|
.RE
|
|
|
.TP
|
|
|
@@ -184,14 +181,14 @@ command \fIoptions\fP description).
|
|
|
This is the file path which contain secret key of aes encryption while using MySQL password encryption.
|
|
|
If you want to use in the MySQL connection string the password in encrypted format,
|
|
|
then set in this option the file path of the secret key. The key which is used to encrypt MySQL password.
|
|
|
-Warning: If this option is set, then MySQL password must be set in "mysql\-userdb" option in encrypted format!
|
|
|
+Warning: If this option is set, then MySQL password must be set in "mysql\-userdb" option in encrypted format!
|
|
|
If you want to use cleartext password then do not set this option!
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-J\fP, \fB\-\-mongo\-userdb\fP
|
|
|
-User database connection string for MongoDB.
|
|
|
+User database connection string for MongoDB.
|
|
|
This database can be used for long\-term credentials mechanism,
|
|
|
-and it can store the secret value
|
|
|
+and it can store the secret value
|
|
|
for secret\-based timed authentication in TURN REST API.
|
|
|
The connection string format is like that:
|
|
|
.RS
|
|
|
@@ -206,9 +203,9 @@ for full MongoDB documentation.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-N\fP, \fB\-\-redis\-userdb\fP
|
|
|
-User database connection string for Redis.
|
|
|
+User database connection string for Redis.
|
|
|
This database can be used for long\-term credentials mechanism,
|
|
|
-and it can store the secret
|
|
|
+and it can store the secret
|
|
|
value for secret\-based timed authentication in TURN REST API.
|
|
|
The connection string format is like that:
|
|
|
.RS
|
|
|
@@ -219,8 +216,7 @@ See the INSTALL file for more explanations and examples.
|
|
|
.PP
|
|
|
Also, see http://redis.io for full Redis documentation.
|
|
|
.RE
|
|
|
-.TP
|
|
|
-.B
|
|
|
+.PP
|
|
|
Flags:
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -234,15 +230,13 @@ Extra verbose mode, very annoying and not recommended.
|
|
|
.B
|
|
|
\fB\-o\fP, \fB\-\-daemon\fP
|
|
|
Run server as daemon.
|
|
|
-.TP
|
|
|
-.B
|
|
|
-\fB\-\-prod\fP
|
|
|
-Production mode: hide the software version.
|
|
|
+.PP
|
|
|
+\fB\-\-no\-software\-attribute\fP Production mode: hide the software version.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-f\fP, \fB\-\-fingerprint\fP
|
|
|
Use fingerprints in the TURN messages. If an incoming request
|
|
|
-contains a fingerprint, then TURN server will always add
|
|
|
+contains a fingerprint, then TURN server will always add
|
|
|
fingerprints to the messages in this session, regardless of the
|
|
|
per\-server setting.
|
|
|
.TP
|
|
|
@@ -252,8 +246,8 @@ Use long\-term credentials mechanism (this one you need for WebRTC usage).
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-z\fP, \fB\-\-no\-auth\fP
|
|
|
-Do not use any credentials mechanism, allow anonymous access.
|
|
|
-Opposite to \fB\-a\fP and \fB\-A\fP \fIoptions\fP. This is default option when no
|
|
|
+Do not use any credentials mechanism, allow anonymous access.
|
|
|
+Opposite to \fB\-a\fP and \fB\-A\fP \fIoptions\fP. This is default option when no
|
|
|
authentication\-related \fIoptions\fP are set.
|
|
|
By default, no credential mechanism is used \-
|
|
|
any user is allowed.
|
|
|
@@ -261,8 +255,8 @@ any user is allowed.
|
|
|
.B
|
|
|
\fB\-\-use\-auth\-secret\fP
|
|
|
TURN REST API flag.
|
|
|
-Flag that sets a special WebRTC authorization option
|
|
|
-that is based upon authentication secret. The feature purpose
|
|
|
+Flag that sets a special WebRTC authorization option
|
|
|
+that is based upon authentication secret. The feature purpose
|
|
|
is to support "\fBTURN Server\fP REST API" as described in
|
|
|
the TURN REST API section below.
|
|
|
This option uses timestamp as part of combined username:
|
|
|
@@ -281,11 +275,11 @@ Support oAuth authentication, as in the third\-party STUN/TURN RFC 7635.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-dh566\fP
|
|
|
-Use 566 bits predefined DH TLS key. Default size of the key is 1066.
|
|
|
+Use 566 bits predefined DH TLS key. Default size of the key is 2066.
|
|
|
.TP
|
|
|
.B
|
|
|
-\fB\-\-dh2066\fP
|
|
|
-Use 2066 bits predefined DH TLS key. Default size of the key is 1066.
|
|
|
+\fB\-\-dh1066\fP
|
|
|
+Use 1066 bits predefined DH TLS key. Default size of the key is 2066.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-tlsv1\fP
|
|
|
@@ -317,19 +311,19 @@ Do not start DTLS client listeners.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-udp\-relay\fP
|
|
|
-Do not allow UDP relay endpoints defined in RFC 5766,
|
|
|
+Do not allow UDP relay endpoints defined in RFC 5766,
|
|
|
use only TCP relay endpoints as defined in RFC 6062.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-tcp\-relay\fP
|
|
|
-Do not allow TCP relay endpoints defined in RFC 6062,
|
|
|
-use only UDP relay endpoints as defined in RFC 5766.
|
|
|
+Do not allow TCP relay endpoints defined in RFC 6062,
|
|
|
+use only UDP relay endpoints as defined in RFC 5766.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-stdout\-log\fP
|
|
|
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 configured log file. With this option everything will be going to
|
|
|
the log file only (unless the log file itself is stdout).
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -349,25 +343,25 @@ By default, the clients are allowed anonymous access to the STUN Binding functio
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-S\fP, \fB\-\-stun\-only\fP
|
|
|
-Run as STUN server only, all TURN requests will be ignored.
|
|
|
+Run as STUN server only, all TURN requests will be ignored.
|
|
|
Option to suppress TURN functionality, only STUN requests will be processed.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-stun\fP
|
|
|
-Run as TURN server only, all STUN requests will be ignored.
|
|
|
+Run as TURN server only, all STUN requests will be ignored.
|
|
|
Option to suppress STUN functionality, only TURN requests will be processed.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-allow\-loopback\-peers\fP
|
|
|
Allow peers on the loopback addresses (127.x.x.x and ::1).
|
|
|
-Allow it only for testing in a development environment!
|
|
|
-In production it adds a possible security vulnerability,
|
|
|
-and so due to security reasons, it is not allowed
|
|
|
+Allow it only for testing in a development environment!
|
|
|
+In production it adds a possible security vulnerability,
|
|
|
+and so due to security reasons, it is not allowed
|
|
|
using it together with empty cli\-password.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-no\-multicast\-peers\fP
|
|
|
-Disallow peers on well\-known broadcast addresses
|
|
|
+Disallow peers on well\-known broadcast addresses
|
|
|
(224.0.0.0 and above, and FFXX:*).
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -381,10 +375,10 @@ See also \fIoptions\fP \fB\-\-cli\-ip\fP and \fB\-\-cli\-port\fP.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-server\-relay\fP
|
|
|
-Server relay. NON\-STANDARD AND DANGEROUS OPTION.
|
|
|
-Only for those applications when we want to run
|
|
|
+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
|
|
|
+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 .
|
|
|
.TP
|
|
|
@@ -392,13 +386,13 @@ See http://tools.ietf.org/search/rfc5766#section\-17.2.3 .
|
|
|
\fB\-\-udp\-self\-balance\fP
|
|
|
(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
|
|
|
+(if configured). The load balancing is using the
|
|
|
+ALTERNATE\-SERVER mechanism. The TURN client must support
|
|
|
300 ALTERNATE\-SERVER response for this functionality.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-check\-origin\-consistency\fP
|
|
|
-The flag that sets the 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).
|
|
|
@@ -406,8 +400,7 @@ initially used by the session).
|
|
|
.B
|
|
|
\fB\-h\fP
|
|
|
Help.
|
|
|
-.TP
|
|
|
-.B
|
|
|
+.PP
|
|
|
Options with values:
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -434,17 +427,17 @@ This MUST not be changed for production purposes.
|
|
|
.B
|
|
|
\fB\-d\fP, \fB\-\-listening\-device\fP
|
|
|
Listener interface device.
|
|
|
-(NOT RECOMMENDED. Optional functionality, Linux only).
|
|
|
-The \fIturnserver\fP process must have root privileges to bind the
|
|
|
-listening endpoint to a device. If \fIturnserver\fP must run as a
|
|
|
+(NOT RECOMMENDED. Optional functionality, Linux only).
|
|
|
+The \fIturnserver\fP process must have root privileges to bind the
|
|
|
+listening endpoint to a device. If \fIturnserver\fP must run as a
|
|
|
process without root privileges, then just do not use this setting.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-L\fP, \fB\-\-listening\-ip\fP
|
|
|
-Listener IP address of relay server.
|
|
|
+Listener IP address of relay server.
|
|
|
Multiple listeners can be specified, for example:
|
|
|
\fB\-L\fP ip1 \fB\-L\fP ip2 \fB\-L\fP ip3
|
|
|
-If no \fBIP\fP(s) specified, then all IPv4 and
|
|
|
+If no \fBIP\fP(s) specified, then all IPv4 and
|
|
|
IPv6 system IPs will be used for listening.
|
|
|
The same \fBip\fP(s) can be used as both listening and relay \fBip\fP(s).
|
|
|
.TP
|
|
|
@@ -458,11 +451,11 @@ Note: actually, TLS & DTLS sessions can connect to the "plain" TCP & UDP
|
|
|
\fB\-\-tls\-listening\-port\fP
|
|
|
TURN listener port for TLS and DTLS listeners (Default: 5349).
|
|
|
Note: actually, "plain" TCP & UDP sessions can connect to the TLS & DTLS
|
|
|
-\fBport\fP(s), too \- if allowed by configuration. The TURN server
|
|
|
+\fBport\fP(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
|
|
|
+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.
|
|
|
.TP
|
|
|
@@ -483,6 +476,12 @@ Alternative listening port for TLS and DTLS protocols.
|
|
|
Default (or zero) value means "TLS listening port plus one".
|
|
|
.TP
|
|
|
.B
|
|
|
+\fB\-\-tcp\-proxy\-port\fP
|
|
|
+Support connections from TCP loadbalancer on this port. The loadbalancer
|
|
|
+should use the binary proxy protocol.
|
|
|
+(https://www.haproxy.org/download/1.8/doc/proxy\-protocol.txt)
|
|
|
+.TP
|
|
|
+.B
|
|
|
\fB\-\-aux\-server\fP
|
|
|
Auxiliary STUN/TURN server listening endpoint.
|
|
|
Aux servers have almost full TURN and STUN functionality.
|
|
|
@@ -501,20 +500,20 @@ to client requests.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-i\fP, \fB\-\-relay\-device\fP
|
|
|
-Relay interface device for relay sockets
|
|
|
+Relay interface device for relay sockets
|
|
|
(NOT RECOMMENDED. Optional, Linux only).
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-E\fP, \fB\-\-relay\-ip\fP
|
|
|
-Relay address (the local IP address that
|
|
|
-will be used to relay the packets to the
|
|
|
+Relay address (the local IP address that
|
|
|
+will be used to relay the packets to the
|
|
|
peer). Multiple relay addresses may be used:
|
|
|
\fB\-E\fP ip1 \fB\-E\fP ip2 \fB\-E\fP ip3
|
|
|
The same \fBIP\fP(s) can be used as both listening \fBIP\fP(s) and relay \fBIP\fP(s).
|
|
|
-If no relay \fBIP\fP(s) specified, then the \fIturnserver\fP 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
|
|
|
+If no relay \fBIP\fP(s) specified, then the \fIturnserver\fP 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).
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -522,7 +521,7 @@ address family is the same as the family of the client socket).
|
|
|
\fBTURN Server\fP public/private address mapping, if the server is behind NAT.
|
|
|
In that situation, if a \fB\-X\fP is used in form "\fB\-X\fP <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
|
|
|
+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
|
|
|
@@ -530,8 +529,8 @@ 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 "\fB\-X\fP <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
|
|
|
+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.
|
|
|
.TP
|
|
|
@@ -540,54 +539,54 @@ By default, this value is empty, and no address mapping is used.
|
|
|
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
|
|
|
+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
|
|
|
+(before Linux kernel 3.9), the number of UDP threads is always one threads
|
|
|
per network listening endpoint \- unless "\fB\-m\fP 0" or "\fB\-m\fP 1" is set.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-min\-port\fP
|
|
|
-Lower bound of the UDP port range for relay
|
|
|
+Lower bound of the UDP port range for relay
|
|
|
endpoints allocation.
|
|
|
Default value is 49152, according to RFC 5766.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-max\-port\fP
|
|
|
-Upper bound of the UDP port range for relay
|
|
|
+Upper bound of the UDP port range for relay
|
|
|
endpoints allocation.
|
|
|
Default value is 65535, according to RFC 5766.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-u\fP, \fB\-\-user\fP
|
|
|
-Long\-term security mechanism credentials user account,
|
|
|
-in the column\-separated form username:key.
|
|
|
+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 \fIturnadmin\fP command. In the second case,
|
|
|
the key must be prepended with 0x symbols.
|
|
|
-The key is calculated over the user name,
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-r\fP, \fB\-\-realm\fP
|
|
|
-The default realm to be used for the users when no explicit
|
|
|
+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
|
|
|
+and the userdb file). Must be used with long\-term credentials
|
|
|
mechanism or with TURN REST API.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-C\fP, \fB\-\-rest\-api\-separator\fP
|
|
|
-This is the timestamp/username separator symbol
|
|
|
+This is the timestamp/username separator symbol
|
|
|
(character) in TURN REST API. The default value is :.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-q\fP, \fB\-\-user\-quota\fP
|
|
|
-Per\-user allocations quota: how many concurrent
|
|
|
-allocations a user can create. This option can also be set
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -598,9 +597,9 @@ This option can also be set through the database, for a particular realm.
|
|
|
.B
|
|
|
\fB\-s\fP, \fB\-\-max\-bps\fP
|
|
|
Max bytes\-per\-second bandwidth a TURN session is allowed to handle
|
|
|
-(input and output network streams are treated separately). Anything above
|
|
|
+(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
|
|
|
+available buffer limits). This option can also be set through the
|
|
|
database, for a particular realm.
|
|
|
.TP
|
|
|
.B
|
|
|
@@ -613,7 +612,7 @@ separately).
|
|
|
.B
|
|
|
\fB\-\-static\-auth\-secret\fP
|
|
|
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
|
|
|
+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
|
|
|
@@ -641,17 +640,17 @@ The default value is the realm name.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-cert\fP
|
|
|
-Certificate file, PEM format. Same file
|
|
|
-search rules applied as for the configuration
|
|
|
-file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
|
|
|
+Certificate file, PEM format. Same file
|
|
|
+search rules applied as for the configuration
|
|
|
+file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
|
|
|
are specified, then this parameter is not needed.
|
|
|
Default value is turn_server_cert.pem.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-pkey\fP
|
|
|
-Private key file, PEM format. Same file
|
|
|
-search rules applied as for the configuration
|
|
|
-file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
|
|
|
+Private key file, PEM format. Same file
|
|
|
+search rules applied as for the configuration
|
|
|
+file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
|
|
|
are specified, then this parameter is not needed.
|
|
|
Default value is turn_server_pkey.pem.
|
|
|
.TP
|
|
|
@@ -666,14 +665,14 @@ Default value is "DEFAULT".
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-CA\-file\fP
|
|
|
-CA file in OpenSSL format.
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-ec\-curve\-name\fP
|
|
|
-Curve name for EC ciphers, if supported by OpenSSL
|
|
|
-library (TLS and DTLS). The default value is prime256v1,
|
|
|
+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.
|
|
|
@@ -681,79 +680,79 @@ by this option.
|
|
|
.B
|
|
|
\fB\-\-dh\-file\fP
|
|
|
Use custom DH TLS key, stored in PEM format in the file.
|
|
|
-Flags \fB\-\-dh566\fP and \fB\-\-dh2066\fP are ignored when the DH key is taken from a file.
|
|
|
+Flags \fB\-\-dh566\fP and \fB\-\-dh1066\fP are ignored when the DH key is taken from a file.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-l\fP, \fB\-\-log\-file\fP
|
|
|
Option to set the full path name of the log file.
|
|
|
-By default, the \fIturnserver\fP tries to open a log file in
|
|
|
-/var/log/\fIturnserver\fP, /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
|
|
|
+By default, the \fIturnserver\fP tries to open a log file in
|
|
|
+/var/log/\fIturnserver\fP, /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
|
|
|
+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 "\fB\-\-syslog\fP" was set.
|
|
|
-In the runtime, the logfile can be reset with the SIGHUP signal
|
|
|
+the system log (syslog), as if the option "\fB\-\-syslog\fP" was set.
|
|
|
+In the runtime, the logfile can be reset with the SIGHUP signal
|
|
|
to the \fIturnserver\fP process.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-alternate\-server\fP
|
|
|
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
|
|
|
+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.
|
|
|
+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 \fB\-\-alternate\-server\fP \fIoptions\fP 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
|
|
|
+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 .
|
|
|
+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.
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-tls\-alternate\-server\fP
|
|
|
-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
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-O\fP, \fB\-\-redis\-statsdb\fP
|
|
|
-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
|
|
|
+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 \fB\-\-redis\-userdb\fP option,
|
|
|
-and actually Redis can be used for status/statistics and SQLite or MySQL or MongoDB or
|
|
|
+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.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-max\-allocate\-timeout\fP
|
|
|
-Max time, in seconds, allowed for full allocation establishment.
|
|
|
+Max time, in seconds, allowed for full allocation establishment.
|
|
|
Default is 60 seconds.
|
|
|
.PP
|
|
|
\fB\-\-denied\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]>
|
|
|
.PP
|
|
|
-\fB\-\-allowed\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]> 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
|
|
|
+\fB\-\-allowed\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]> 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.
|
|
|
+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:
|
|
|
.RS
|
|
|
.IP 1) 4
|
|
|
@@ -791,9 +790,9 @@ Client <=> Server communication address family.
|
|
|
\fB\-\-cli\-ip\fP
|
|
|
Local system IP address to be used for CLI management interface.
|
|
|
The \fIturnserver\fP process can be accessed for management with telnet,
|
|
|
-at this IP address and on the CLI port (see the next parameter).
|
|
|
+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.
|
|
|
+to access the CLI management interface.
|
|
|
.TP
|
|
|
.B
|
|
|
\fB\-\-cli\-port\fP
|
|
|
@@ -847,24 +846,24 @@ This is a set of notes for the WebRTC users:
|
|
|
.IP 1) 4
|
|
|
WebRTC uses long\-term authentication mechanism, so you have to use \fB\-a\fP
|
|
|
option (or \fB\-\-lt\-cred\-mech\fP). WebRTC relaying will not work with anonymous
|
|
|
-access. With \fB\-a\fP option, do not forget to set the
|
|
|
-default realm (\fB\-r\fP option). You will also have to set up the user accounts,
|
|
|
+access. With \fB\-a\fP option, do not forget to set the
|
|
|
+default realm (\fB\-r\fP option). You will also have to set up the user accounts,
|
|
|
for that you have a number of \fIoptions\fP:
|
|
|
.PP
|
|
|
.nf
|
|
|
.fam C
|
|
|
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).
|
|
|
+ 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.
|
|
|
+ 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.
|
|
|
+ the database table or Redis key/value pairs.
|
|
|
|
|
|
.fam T
|
|
|
.fi
|
|
|
@@ -882,19 +881,19 @@ number range.
|
|
|
.SH 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
|
|
|
+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.
|
|
|
.PP
|
|
|
-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
|
|
|
+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.
|
|
|
.PP
|
|
|
-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
|
|
|
+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.
|
|
|
.PP
|
|
|
The "classic" long\-term credentials mechanism (LTCM) is described here:
|
|
|
@@ -905,22 +904,22 @@ http://tools.ietf.org/html/rfc5389#section\-15.4
|
|
|
.PP
|
|
|
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
|
|
|
+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.
|
|
|
.PP
|
|
|
-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.
|
|
|
+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.
|
|
|
.PP
|
|
|
The temporary user is generated as:
|
|
|
.PP
|
|
|
temporary\-username="timestamp" + ":" + "username"
|
|
|
.PP
|
|
|
-where username is the persistent user name, and the timestamp format is just
|
|
|
+where username is the persistent user name, and the timestamp format is just
|
|
|
seconds since 1970 \- the same value as \fBtime\fP(NULL) function returns.
|
|
|
.PP
|
|
|
The temporary password is obtained as HMAC\-SHA1 function over the temporary
|
|
|
@@ -932,7 +931,7 @@ 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.
|
|
|
.PP
|
|
|
-So, a timestamp is used for the temporary password calculation, and this
|
|
|
+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.
|
|
|
@@ -947,7 +946,7 @@ For developers, we are going to describe it step\-by\-step below:
|
|
|
.RS
|
|
|
.IP \(bu 3
|
|
|
a new TURN client sends a request command to the TURN server. Optionally,
|
|
|
-it adds the ORIGIN field to it.
|
|
|
+it adds the ORIGIN field to it.
|
|
|
.IP \(bu 3
|
|
|
TURN server sees that this is a new client and the message is not
|
|
|
authenticated.
|
|
|
@@ -970,13 +969,13 @@ the client uses username, realm and password to produce a key:
|
|
|
(SASLprep is described here: http://tools.ietf.org/html/rfc4013)
|
|
|
.IP \(bu 3
|
|
|
the client forms a new request, adds username, realm and nonce to the
|
|
|
-request. Then, the client calculates and adds the integrity field to
|
|
|
+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:
|
|
|
+described in the end of section 15.4:
|
|
|
http://tools.ietf.org/html/rfc5389#section\-15.4
|
|
|
.IP \(bu 3
|
|
|
the client, optionally, adds the fingerprint field. This may be also
|
|
|
-a tricky procedure, described in section 15.5 of the same document.
|
|
|
+a tricky procedure, described in section 15.5 of the same document.
|
|
|
WebRTC usually uses fingerprinted TURN messages.
|
|
|
.IP \(bu 3
|
|
|
the TURN server receives the request, reads the username.
|
|
|
@@ -989,33 +988,33 @@ then the TURN server calculates the key.
|
|
|
then the TURN server calculates the integrity field.
|
|
|
.IP \(bu 3
|
|
|
then the TURN server compares the calculated integrity field with the
|
|
|
-received one \- they must be the same. If the integrity fields differ,
|
|
|
+received one \- they must be the same. If the integrity fields differ,
|
|
|
then the request is rejected.
|
|
|
.RE
|
|
|
.PP
|
|
|
-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 "\fB\-\-stale\-nonce\fP" option for extra security: in
|
|
|
+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 "\fB\-\-stale\-nonce\fP" 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.
|
|
|
.PP
|
|
|
-In subsequent communications, the server and the client will always assume
|
|
|
-the same password \- the original password becomes the session parameter and
|
|
|
+In subsequent communications, the server 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
|
|
|
+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).
|
|
|
.PP
|
|
|
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 .
|
|
|
.PP
|
|
|
-A very important thing is that the nonce must be totally random and it must be
|
|
|
-different for different clients and different sessions.
|
|
|
+A very important thing is that the nonce must be totally random and it must be
|
|
|
+different for different clients and different sessions.
|
|
|
.PP
|
|
|
===================================
|
|
|
.SH DATABASES
|
|
|
@@ -1023,7 +1022,7 @@ different for different clients and different sessions.
|
|
|
For the user database, the \fIturnserver\fP has the following \fIoptions\fP:
|
|
|
.IP 1) 4
|
|
|
Users can be set in the command line, with multiple \fB\-u\fP or \fB\-\-user\fP \fIoptions\fP.
|
|
|
-Obviously, only a few users can be set that way, and their credentials are fixed
|
|
|
+Obviously, only a few users can be set that way, and their credentials are fixed
|
|
|
for the \fIturnserver\fP process lifetime.
|
|
|
.IP 2) 4
|
|
|
Users can be stored in SQLite DB. The default SQLite database file is /var/db/turndb
|
|
|
@@ -1031,23 +1030,23 @@ or /usr/local/var/db/turndb or /var/lib/turn/turndb.
|
|
|
.IP 3) 4
|
|
|
Users can be stored in PostgreSQL database, if the \fIturnserver\fP was compiled with PostgreSQL
|
|
|
support. Each time \fIturnserver\fP 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 \fIturnserver\fP. This is the way if you need the
|
|
|
+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 \fIturnserver\fP. 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 \fIturnadmin\fP 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
|
|
|
+For long\-term credentials, you have to set the "keys" for the users; the "keys" are generated
|
|
|
+by the \fIturnadmin\fP 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.
|
|
|
.IP 4) 4
|
|
|
The same is true for MySQL database. The same schema file is applicable.
|
|
|
-The same considerations are applicable.
|
|
|
+The same considerations are applicable.
|
|
|
.IP 5) 4
|
|
|
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.
|
|
|
+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.
|
|
|
.IP 6) 4
|
|
|
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
|
|
|
@@ -1064,21 +1063,21 @@ The simplest choice is not to use it. Do not set \fB\-\-redis\-statsdb\fP option
|
|
|
will be simply ignored.
|
|
|
.IP 2) 4
|
|
|
If you choose to use it, then set the \fB\-\-redis\-statsdb\fP option. This may be the same database
|
|
|
-as in \fB\-\-redis\-userdb\fP option, or it may be a different database. You may want to use different
|
|
|
+as in \fB\-\-redis\-userdb\fP 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
|
|
|
+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.
|
|
|
.PP
|
|
|
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,
|
|
|
+two are totally independent. So, you have overall 6*2=12 ways to handle persistent information,
|
|
|
choose any for your convenience.
|
|
|
.PP
|
|
|
-You do not have to handle the database information "manually" \- the \fIturnadmin\fP program can handle
|
|
|
+You do not have to handle the database information "manually" \- the \fIturnadmin\fP 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 \fIturnadmin\fP and
|
|
|
-it will set the users for you (see the \fIturnadmin\fP manuals). If you are using SQLite, then the
|
|
|
-\fIturnserver\fP or \fIturnadmin\fP will initialize the empty database, for you, when started. The
|
|
|
-TURN server installation process creates an empty initialized SQLite database in the default
|
|
|
+with schema.sql SQL script. With Redis, you do not have to do even that \- just run \fIturnadmin\fP and
|
|
|
+it will set the users for you (see the \fIturnadmin\fP manuals). If you are using SQLite, then the
|
|
|
+\fIturnserver\fP or \fIturnadmin\fP 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).
|
|
|
.PP
|
|
|
=================================
|
|
|
@@ -1097,7 +1096,7 @@ does not include the ALPN information into the ServerHello.
|
|
|
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.
|
|
|
+An example of C++ code can be found in stunclient.c file.
|
|
|
.PP
|
|
|
=================================
|
|
|
.SH DOCS
|
|
|
@@ -1112,13 +1111,13 @@ $ man \fB\-M\fP man \fIturnserver\fP
|
|
|
.PP
|
|
|
to see the man page.
|
|
|
.PP
|
|
|
-In the docs/html subdirectory of the original archive tree, you will find the client library
|
|
|
+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/\fIturnserver\fP/html.
|
|
|
.PP
|
|
|
=================================
|
|
|
.SH LOGS
|
|
|
|
|
|
-When the \fBTURN Server\fP starts, it makes efforts to create a log file turn_<pid>.log
|
|
|
+When the \fBTURN Server\fP starts, it makes efforts to create a log file turn_<pid>.log
|
|
|
in the following directories:
|
|
|
.RS
|
|
|
.IP \(bu 3
|
|
|
@@ -1133,7 +1132,7 @@ in the following directories:
|
|
|
current directory
|
|
|
.RE
|
|
|
.PP
|
|
|
-If all efforts failed (due to the system permission settings) then all
|
|
|
+If all efforts failed (due to the system permission settings) then all
|
|
|
log messages are sent only to the standard output of the process.
|
|
|
.PP
|
|
|
This behavior can be controlled by \fB\-\-log\-file\fP, \fB\-\-syslog\fP and \fB\-\-no\-stdout\-log\fP
|
|
|
@@ -1143,7 +1142,7 @@ This behavior can be controlled by \fB\-\-log\-file\fP, \fB\-\-syslog\fP and \fB
|
|
|
.SH HTTPS MANAGEMENT INTERFACE
|
|
|
|
|
|
The \fIturnserver\fP process provides an HTTPS Web access as statistics and basic
|
|
|
-management interface. The \fIturnserver\fP listens to incoming HTTPS admin
|
|
|
+management interface. The \fIturnserver\fP 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.
|
|
|
.PP
|
|
|
@@ -1165,11 +1164,11 @@ in "help" command output in the telnet CLI.
|
|
|
=================================
|
|
|
.SH CLUSTERS
|
|
|
|
|
|
-\fBTURN Server\fP 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
|
|
|
-\fBTURN Server\fP 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
|
|
|
+\fBTURN Server\fP 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
|
|
|
+\fBTURN Server\fP 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.
|
|
|
.PP
|
|
|
=================================
|
Greg Fodor