mirror of
https://github.com/coturn/coturn.git
synced 2025-10-23 12:00:59 +02:00
update Changelog and update man
This commit is contained in:
Mészáros Mihály
parent
9152469dc5
commit
5b65099678
@ -56,7 +56,8 @@ Version 4.5.1.2 'dan Eider':
|
||||
- merge PR #514 Unify spelling of Coturn (by paulmenzel)
|
||||
- merge PR#506 Rename "prod" config option to "no-software-attribute" (by dbrgn)
|
||||
- merge PR #519 fix config extension in README.docker (by ooookai)
|
||||
- merge PR #516 change sql data dir in docker-compose-all.yml (by raghumuppa)
|
||||
- merge PR #516 change sql data dir in docker-compose-all.yml (by raghumuppa)
|
||||
- mergr PR #513 remove trailing spaces from READMEs (by paulmenzel)
|
||||
|
||||
02/03/2019 Oleg Moskalenko <mom040267@gmail.com> Mihály Mészáros <misi@majd.eu>
|
||||
Version 4.5.1.1 'dan Eider':
|
||||
|
||||
@ -2,16 +2,16 @@
|
||||
.TH TURN 1 "28 April 2020" "" ""
|
||||
.SH GENERAL INFORMATION
|
||||
|
||||
\fIturnadmin\fP is a TURN administration tool. This tool can be used to manage
|
||||
the user accounts (add/remove users, generate
|
||||
TURN keys for the users). For security reasons, we do not recommend
|
||||
storing passwords openly. The better option is to use pre\-processed "keys"
|
||||
which are then used for authentication. These keys are generated by \fIturnadmin\fP.
|
||||
Turnadmin is a link to \fIturnserver\fP binary, but \fIturnadmin\fP performs different
|
||||
\fIturnadmin\fP is a TURN administration tool. This tool can be used to manage
|
||||
the user accounts (add/remove users, generate
|
||||
TURN keys for the users). For security reasons, we do not recommend
|
||||
storing passwords openly. The better option is to use pre\-processed "keys"
|
||||
which are then used for authentication. These keys are generated by \fIturnadmin\fP.
|
||||
Turnadmin is a link to \fIturnserver\fP binary, but \fIturnadmin\fP performs different
|
||||
functions.
|
||||
.PP
|
||||
Options note: \fIturnadmin\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):
|
||||
@ -46,7 +46,7 @@ is equivalent to:
|
||||
|
||||
.fam T
|
||||
.fi
|
||||
You have always the use the \fB\-r\fP <realm> option with commands for long term credentials \-
|
||||
You have always the use the \fB\-r\fP <realm> option with commands for long term credentials \-
|
||||
because data for multiple realms can be stored in the same database.
|
||||
.PP
|
||||
=====================================
|
||||
@ -54,15 +54,20 @@ because data for multiple realms can be stored in the same database.
|
||||
\fB
|
||||
\fBturnadmin \fP\- a TURN relay administration tool.
|
||||
\fB
|
||||
.SS SYNOPSIS
|
||||
.SS SYNOPSIS
|
||||
.nf
|
||||
.fam C
|
||||
|
||||
$ \fIturnadmin\fP [\fIcommand\fP] [\fIoptions\fP]
|
||||
|
||||
$ \fIturnadmin\fP [command] [options]
|
||||
.PP
|
||||
$ \fIturnadmin\fP [ \fB\-h\fP | \fB\-\-help\fP]
|
||||
|
||||
.fam T
|
||||
.fi
|
||||
.fam T
|
||||
.fi
|
||||
.SS DESCRIPTION
|
||||
|
||||
.TP
|
||||
.B
|
||||
Commands:
|
||||
.TP
|
||||
.B
|
||||
@ -135,15 +140,14 @@ List origin\-to\-realm relations.
|
||||
Set realm params: max\-bps, total\-quota, user\-quota.
|
||||
.TP
|
||||
.B
|
||||
\fB\-G\fP, \fB\-\-list\-realm\-options\fP
|
||||
\fB\-G\fP, \fB\-\-list\-realm\fP\-\fIoptions\fP
|
||||
List realm params.
|
||||
.TP
|
||||
.B
|
||||
\fB\-E\fP, \fB\-\-generate\-encrypted\-password\-aes\fP
|
||||
Generate and print to the standard output
|
||||
Generate and print to the standard output
|
||||
an encrypted form of password with AES\-128
|
||||
.TP
|
||||
.B
|
||||
.PP
|
||||
Options with required values:
|
||||
.TP
|
||||
.B
|
||||
@ -210,13 +214,12 @@ Set value of realm's total\-quota parameter.
|
||||
.TP
|
||||
.B
|
||||
\fB\-\-user\-quota\fP
|
||||
Set value of realm's user\-quota parameter.
|
||||
Set value of realm's user\-quota parameter.
|
||||
.TP
|
||||
.B
|
||||
\fB\-h\fP, \fB\-\-help\fP
|
||||
Help.
|
||||
.TP
|
||||
.B
|
||||
.PP
|
||||
Command examples:
|
||||
.PP
|
||||
Generate an encrypted form of a password:
|
||||
@ -282,8 +285,6 @@ $ \fIturnadmin\fP \fB\-\-file\-key\-path\fP <key\-file> \fB\-v\fP <encrypted>
|
||||
.PP
|
||||
|
||||
.RS
|
||||
.TP
|
||||
.B
|
||||
Help:
|
||||
.PP
|
||||
$ \fIturnadmin\fP \fB\-h\fP
|
||||
@ -291,7 +292,7 @@ $ \fIturnadmin\fP \fB\-h\fP
|
||||
=======================================
|
||||
.SS DOCS
|
||||
|
||||
After installation, run the command:
|
||||
After installation, run the \fIcommand\fP:
|
||||
.PP
|
||||
$ man \fIturnadmin\fP
|
||||
.PP
|
||||
|
||||
@ -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
|
||||
@ -240,7 +236,7 @@ Run server as daemon.
|
||||
.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
|
||||
@ -250,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.
|
||||
@ -259,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:
|
||||
@ -315,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
|
||||
@ -347,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
|
||||
@ -379,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
|
||||
@ -390,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).
|
||||
@ -404,8 +400,7 @@ initially used by the session).
|
||||
.B
|
||||
\fB\-h\fP
|
||||
Help.
|
||||
.TP
|
||||
.B
|
||||
.PP
|
||||
Options with values:
|
||||
.TP
|
||||
.B
|
||||
@ -432,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
|
||||
@ -456,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
|
||||
@ -505,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
|
||||
@ -526,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
|
||||
@ -534,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
|
||||
@ -544,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
|
||||
@ -602,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
|
||||
@ -617,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
|
||||
@ -631,17 +626,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
|
||||
@ -656,14 +651,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.
|
||||
@ -676,74 +671,74 @@ Flags \fB\-\-dh566\fP and \fB\-\-dh1066\fP are ignored when the DH key is taken
|
||||
.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
|
||||
@ -781,9 +776,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
|
||||
@ -837,24 +832,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
|
||||
@ -872,19 +867,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:
|
||||
@ -895,22 +890,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
|
||||
@ -922,7 +917,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.
|
||||
@ -937,7 +932,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.
|
||||
@ -960,13 +955,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.
|
||||
@ -979,33 +974,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
|
||||
@ -1013,7 +1008,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
|
||||
@ -1021,23 +1016,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
|
||||
@ -1054,21 +1049,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
|
||||
=================================
|
||||
@ -1087,7 +1082,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
|
||||
@ -1102,13 +1097,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
|
||||
@ -1123,7 +1118,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
|
||||
@ -1133,7 +1128,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
|
||||
@ -1155,11 +1150,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
|
||||
=================================
|
||||
|
||||
@ -51,12 +51,12 @@ addresses should be configured to be able to work properly!
|
||||
.TP
|
||||
.B
|
||||
6.
|
||||
\fIturnutils_oauth\fP: a utility that provides OAuth access_token
|
||||
\fBgeneration\fP(AEAD encryption), validation and decryption. This utility inputs
|
||||
all the keys and lifetimes and any related information that needed for
|
||||
creation and validationi of an access_token. It outputs a JSON with all OAuth
|
||||
PoP parameters that need to pass to the client. Output is generated accoriding
|
||||
RFC7635 Appendix B, Figure 8.
|
||||
\fIturnutils_oauth\fP: a utility that provides OAuth access_token
|
||||
\fBgeneration\fP(AEAD encryption), validation and decryption. This utility inputs
|
||||
all the keys and lifetimes and any related information that needed for
|
||||
creation and validationi of an access_token. It outputs a JSON with all OAuth
|
||||
PoP parameters that need to pass to the client. Output is generated accoriding
|
||||
RFC7635 Appendix B, Figure 8.
|
||||
.PP
|
||||
For more details, and for the access_token structure, read rfc7635, and see
|
||||
script in examples/scripts/oauth.sh.
|
||||
@ -480,15 +480,15 @@ $ \fIturnutils_oauth\fP [\fIoptions\fP]
|
||||
.fi
|
||||
.SS DESCRIPTION
|
||||
|
||||
\fIturnutils_oauth\fP utilitiy provides help in OAuth access_token encryption and/or
|
||||
decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps
|
||||
for an Auth Server in access_token creation, and also for debugging purposes it
|
||||
helps the access_token validation and decryption. This utility inputs all the
|
||||
keys and lifetimes and any related information that are needed for encryption
|
||||
or decryption of an access_token. It outputs a JSON with all OAuth PoP
|
||||
parameters that need to pass to the client. Output is generated accoriding
|
||||
RFC7635 Appendix B, Figure 8. This utility could help to build an Auth Server
|
||||
service, but be awere that this utility does not generate "session key" /
|
||||
\fIturnutils_oauth\fP utilitiy provides help in OAuth access_token encryption and/or
|
||||
decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps
|
||||
for an Auth Server in access_token creation, and also for debugging purposes it
|
||||
helps the access_token validation and decryption. This utility inputs all the
|
||||
keys and lifetimes and any related information that are needed for encryption
|
||||
or decryption of an access_token. It outputs a JSON with all OAuth PoP
|
||||
parameters that need to pass to the client. Output is generated accoriding
|
||||
RFC7635 Appendix B, Figure 8. This utility could help to build an Auth Server
|
||||
service, but be awere that this utility does not generate "session key" /
|
||||
"mac_key" and not verifies lifetime of "session key" / "mac_key" or "Auth key".
|
||||
For more details, and for the access_token structure, read rfc7635, and see
|
||||
the example in examples/scripts/oauth.sh.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user