mirrors/coturn
1
0
Fork 0
mirror of https://github.com/coturn/coturn.git synced 2025-10-23 20:11:17 +02:00
Code Issues Projects Releases Wiki Activity

update Changelog and update man

Browse Source
This commit is contained in:
Mészáros Mihály 2020-04-28 10:15:43 +02:00
parent 9152469dc5
commit 5b65099678
4 changed files with 242 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
ChangeLog
View File

@ -56,7 +56,8 @@ Version 4.5.1.2 'dan Eider':
- merge PR #514 Unify spelling of Coturn (by paulmenzel) - merge PR #514 Unify spelling of Coturn (by paulmenzel)
- merge PR#506 Rename "prod" config option to "no-software-attribute" (by dbrgn) - 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 #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> 02/03/2019 Oleg Moskalenko <mom040267@gmail.com> Mihály Mészáros <misi@majd.eu>
Version 4.5.1.1 'dan Eider': Version 4.5.1.1 'dan Eider':

47
man/man1/turnadmin.1
View File

@ -2,16 +2,16 @@
.TH TURN 1 "28 April 2020" "" "" .TH TURN 1 "28 April 2020" "" ""
.SH GENERAL INFORMATION .SH GENERAL INFORMATION
\fIturnadmin\fP is a TURN administration tool. This tool can be used to manage \fIturnadmin\fP is a TURN administration tool. This tool can be used to manage
the user accounts (add/remove users, generate the user accounts (add/remove users, generate
TURN keys for the users). For security reasons, we do not recommend TURN keys for the users). For security reasons, we do not recommend
storing passwords openly. The better option is to use pre\-processed "keys" 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. 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 Turnadmin is a link to \fIturnserver\fP binary, but \fIturnadmin\fP performs different
functions. functions.
.PP .PP
Options note: \fIturnadmin\fP has long and short option names, for most options. 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: somewhat different, if an argument is required:
.PP .PP
The short form must be used as this (for example): The short form must be used as this (for example):
@ -46,7 +46,7 @@ is equivalent to:
.fam T .fam T
.fi .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. because data for multiple realms can be stored in the same database.
.PP .PP
===================================== =====================================
@ -54,15 +54,20 @@ because data for multiple realms can be stored in the same database.
\fB \fB
\fBturnadmin \fP\- a TURN relay administration tool. \fBturnadmin \fP\- a TURN relay administration tool.
\fB \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] $ \fIturnadmin\fP [ \fB\-h\fP | \fB\-\-help\fP]
.fam T
.fi
.fam T
.fi
.SS DESCRIPTION .SS DESCRIPTION
.TP
.B
Commands: Commands:
.TP .TP
.B .B
@ -135,15 +140,14 @@ List origin\-to\-realm relations.
Set realm params: max\-bps, total\-quota, user\-quota. Set realm params: max\-bps, total\-quota, user\-quota.
.TP .TP
.B .B
\fB\-G\fP, \fB\-\-list\-realm\-options\fP \fB\-G\fP, \fB\-\-list\-realm\fP\-\fIoptions\fP
List realm params. List realm params.
.TP .TP
.B .B
\fB\-E\fP, \fB\-\-generate\-encrypted\-password\-aes\fP \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 an encrypted form of password with AES\-128
.TP .PP
.B
Options with required values: Options with required values:
.TP .TP
.B .B
@ -210,13 +214,12 @@ Set value of realm's total\-quota parameter.
.TP .TP
.B .B
\fB\-\-user\-quota\fP \fB\-\-user\-quota\fP
Set value of realm's user\-quota parameter. Set value of realm's user\-quota parameter.
.TP .TP
.B .B
\fB\-h\fP, \fB\-\-help\fP \fB\-h\fP, \fB\-\-help\fP
Help. Help.
.TP .PP
.B
Command examples: Command examples:
.PP .PP
Generate an encrypted form of a password: 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 .PP
.RS .RS
.TP
.B
Help: Help:
.PP .PP
$ \fIturnadmin\fP \fB\-h\fP $ \fIturnadmin\fP \fB\-h\fP
@ -291,7 +292,7 @@ $ \fIturnadmin\fP \fB\-h\fP
======================================= =======================================
.SS DOCS .SS DOCS
After installation, run the command: After installation, run the \fIcommand\fP:
.PP .PP
$ man \fIturnadmin\fP $ man \fIturnadmin\fP
.PP .PP

407
man/man1/turnserver.1
View File

@ -2,9 +2,9 @@
.TH TURN 1 "28 April 2020" "" "" .TH TURN 1 "28 April 2020" "" ""
.SH GENERAL INFORMATION .SH GENERAL INFORMATION
The \fBTURN Server\fP project contains the source code of a TURN server and TURN client 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 messaging library. Also, some extra programs provided, for testing\-only
purposes. purposes.
.PP .PP
See the INSTALL file for the building instructions. See the INSTALL file for the building instructions.
.PP .PP
@ -12,7 +12,7 @@ After the build, you will have the following binary images:
.TP .TP
.B .B
1. 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. The compiled binary image of the \fBTURN Server\fP program is located in bin/ sub\-directory.
.TP .TP
.B .B
@ -35,7 +35,7 @@ turnutils_stunclient. See README.turnutils and \fIturnutils\fP man page.
6. 6.
turnutils_rfc5769check. See README.turnutils and \fIturnutils\fP man page. turnutils_rfc5769check. See README.turnutils and \fIturnutils\fP man page.
.PP .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: to run the programs. The scripts are meant to be run from examples/ sub\-directory, for example:
.PP .PP
$ cd examples $ cd examples
@ -43,7 +43,7 @@ $ ./scripts/secure_relay.sh
.SH RUNNING THE TURN SERVER .SH RUNNING THE TURN SERVER
Options note: \fIturnserver\fP has long and short option names, for most options. 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: somewhat different, if an argument is required:
.PP .PP
The short form must be used as this (for example): The short form must be used as this (for example):
@ -94,10 +94,8 @@ $ \fIturnserver\fP \fB\-h\fP
.fi .fi
.fam T .fam T
.fi .fi
.SS DESCRIPTION .SS DESCRIPTION
.TP
.B
Config file settings: Config file settings:
.TP .TP
.B .B
@ -108,10 +106,10 @@ Do not use configuration file, use only command line parameters.
\fB\-c\fP \fB\-c\fP
Configuration file name (default \- turnserver.conf). Configuration file name (default \- turnserver.conf).
The format of config file can be seen in The format of config file can be seen in
the supplied examples/etc/turnserver.conf example file. Long the supplied examples/etc/turnserver.conf example file. Long
names of the \fIoptions\fP are used as the configuration names of the \fIoptions\fP are used as the configuration
items names in the file. If not an absolute path is supplied, items names in the file. If not an absolute path is supplied,
then the file is searched in the following directories: then the file is searched in the following directories:
.RS .RS
.IP \(bu 3 .IP \(bu 3
current directory current directory
@ -126,8 +124,7 @@ upper directory level etc/
.IP \(bu 3 .IP \(bu 3
installation directory /etc installation directory /etc
.RE .RE
.TP .PP
.B
User database settings: User database settings:
.TP .TP
.B .B
@ -139,18 +136,18 @@ SQLite user database file name (default \- /var/db/turndb or
\fB\-e\fP, \fB\-\-psql\-userdb\fP \fB\-e\fP, \fB\-\-psql\-userdb\fP
User database connection string for PostgreSQL. User database connection string for PostgreSQL.
This database can be used for long\-term credentials mechanism, 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. for secret\-based timed authentication in TURN REST API.
The connection string format is like that: The connection string format is like that:
.RS .RS
.PP .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). (for 8.x or newer Postgres).
.PP .PP
Or: Or:
.PP .PP
"postgresql://username:password@hostname:port/databasename" "postgresql://username:password@hostname:port/databasename"
(for 9.x or newer Postgres). (for 9.x or newer Postgres).
.PP .PP
See the INSTALL file for more explanations and examples. See the INSTALL file for more explanations and examples.
.PP .PP
@ -159,9 +156,9 @@ Also, see http://www.PostgreSQL.org for full PostgreSQL documentation.
.TP .TP
.B .B
\fB\-M\fP, \fB\-\-mysql\-userdb\fP \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, 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. secret\-based timed authentication in TURN REST API.
The connection string format is like that: The connection string format is like that:
.RS .RS
@ -170,12 +167,12 @@ The connection string format is like that:
.PP .PP
See the INSTALL file for more explanations and examples. See the INSTALL file for more explanations and examples.
.PP .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. for full MySQL documentation.
.PP .PP
Optional connection string parameters for the secure communications (SSL): Optional connection string parameters for the secure communications (SSL):
ca, capath, cert, key, cipher ca, capath, cert, key, cipher
(see http://dev.mysql.com/doc/refman/5.1/en/ssl\-options.html for the (see http://dev.mysql.com/doc/refman/5.1/en/ssl\-options.html for the
command \fIoptions\fP description). command \fIoptions\fP description).
.RE .RE
.TP .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. 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, 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. 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! If you want to use cleartext password then do not set this option!
.TP .TP
.B .B
\fB\-J\fP, \fB\-\-mongo\-userdb\fP \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, 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. for secret\-based timed authentication in TURN REST API.
The connection string format is like that: The connection string format is like that:
.RS .RS
@ -206,9 +203,9 @@ for full MongoDB documentation.
.TP .TP
.B .B
\fB\-N\fP, \fB\-\-redis\-userdb\fP \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, 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. value for secret\-based timed authentication in TURN REST API.
The connection string format is like that: The connection string format is like that:
.RS .RS
@ -219,8 +216,7 @@ See the INSTALL file for more explanations and examples.
.PP .PP
Also, see http://redis.io for full Redis documentation. Also, see http://redis.io for full Redis documentation.
.RE .RE
.TP .PP
.B
Flags: Flags:
.TP .TP
.B .B
@ -240,7 +236,7 @@ Run server as daemon.
.B .B
\fB\-f\fP, \fB\-\-fingerprint\fP \fB\-f\fP, \fB\-\-fingerprint\fP
Use fingerprints in the TURN messages. If an incoming request 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 fingerprints to the messages in this session, regardless of the
per\-server setting. per\-server setting.
.TP .TP
@ -250,8 +246,8 @@ Use long\-term credentials mechanism (this one you need for WebRTC usage).
.TP .TP
.B .B
\fB\-z\fP, \fB\-\-no\-auth\fP \fB\-z\fP, \fB\-\-no\-auth\fP
Do not use any credentials mechanism, allow anonymous access. 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 Opposite to \fB\-a\fP and \fB\-A\fP \fIoptions\fP. This is default option when no
authentication\-related \fIoptions\fP are set. authentication\-related \fIoptions\fP are set.
By default, no credential mechanism is used \- By default, no credential mechanism is used \-
any user is allowed. any user is allowed.
@ -259,8 +255,8 @@ any user is allowed.
.B .B
\fB\-\-use\-auth\-secret\fP \fB\-\-use\-auth\-secret\fP
TURN REST API flag. TURN REST API flag.
Flag that sets a special WebRTC authorization option Flag that sets a special WebRTC authorization option
that is based upon authentication secret. The feature purpose that is based upon authentication secret. The feature purpose
is to support "\fBTURN Server\fP REST API" as described in is to support "\fBTURN Server\fP REST API" as described in
the TURN REST API section below. the TURN REST API section below.
This option uses timestamp as part of combined username: This option uses timestamp as part of combined username:
@ -315,19 +311,19 @@ Do not start DTLS client listeners.
.TP .TP
.B .B
\fB\-\-no\-udp\-relay\fP \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. use only TCP relay endpoints as defined in RFC 6062.
.TP .TP
.B .B
\fB\-\-no\-tcp\-relay\fP \fB\-\-no\-tcp\-relay\fP
Do not allow TCP relay endpoints defined in RFC 6062, Do not allow TCP relay endpoints defined in RFC 6062,
use only UDP relay endpoints as defined in RFC 5766. use only UDP relay endpoints as defined in RFC 5766.
.TP .TP
.B .B
\fB\-\-no\-stdout\-log\fP \fB\-\-no\-stdout\-log\fP
Flag to prevent stdout log messages. Flag to prevent stdout log messages.
By default, all log messages are going to both stdout and to 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). the log file only (unless the log file itself is stdout).
.TP .TP
.B .B
@ -347,25 +343,25 @@ By default, the clients are allowed anonymous access to the STUN Binding functio
.TP .TP
.B .B
\fB\-S\fP, \fB\-\-stun\-only\fP \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. Option to suppress TURN functionality, only STUN requests will be processed.
.TP .TP
.B .B
\fB\-\-no\-stun\fP \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. Option to suppress STUN functionality, only TURN requests will be processed.
.TP .TP
.B .B
\fB\-\-allow\-loopback\-peers\fP \fB\-\-allow\-loopback\-peers\fP
Allow peers on the loopback addresses (127.x.x.x and ::1). Allow peers on the loopback addresses (127.x.x.x and ::1).
Allow it only for testing in a development environment! Allow it only for testing in a development environment!
In production it adds a possible security vulnerability, In production it adds a possible security vulnerability,
and so due to security reasons, it is not allowed and so due to security reasons, it is not allowed
using it together with empty cli\-password. using it together with empty cli\-password.
.TP .TP
.B .B
\fB\-\-no\-multicast\-peers\fP \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:*). (224.0.0.0 and above, and FFXX:*).
.TP .TP
.B .B
@ -379,10 +375,10 @@ See also \fIoptions\fP \fB\-\-cli\-ip\fP and \fB\-\-cli\-port\fP.
.TP .TP
.B .B
\fB\-\-server\-relay\fP \fB\-\-server\-relay\fP
Server relay. NON\-STANDARD AND DANGEROUS OPTION. Server relay. NON\-STANDARD AND DANGEROUS OPTION.
Only for those applications when we want to run Only for those applications when we want to run
server applications on the relay endpoints. 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. on the packets incoming to the relay endpoints.
See http://tools.ietf.org/search/rfc5766#section\-17.2.3 . See http://tools.ietf.org/search/rfc5766#section\-17.2.3 .
.TP .TP
@ -390,13 +386,13 @@ See http://tools.ietf.org/search/rfc5766#section\-17.2.3 .
\fB\-\-udp\-self\-balance\fP \fB\-\-udp\-self\-balance\fP
(recommended for older Linuxes only) (recommended for older Linuxes only)
Automatically balance UDP traffic over auxiliary servers Automatically balance UDP traffic over auxiliary servers
(if configured). The load balancing is using the (if configured). The load balancing is using the
ALTERNATE\-SERVER mechanism. The TURN client must support ALTERNATE\-SERVER mechanism. The TURN client must support
300 ALTERNATE\-SERVER response for this functionality. 300 ALTERNATE\-SERVER response for this functionality.
.TP .TP
.B .B
\fB\-\-check\-origin\-consistency\fP \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 check: across the session, all requests must have the same
main ORIGIN attribute value (if the ORIGIN was main ORIGIN attribute value (if the ORIGIN was
initially used by the session). initially used by the session).
@ -404,8 +400,7 @@ initially used by the session).
.B .B
\fB\-h\fP \fB\-h\fP
Help. Help.
.TP .PP
.B
Options with values: Options with values:
.TP .TP
.B .B
@ -432,17 +427,17 @@ This MUST not be changed for production purposes.
.B .B
\fB\-d\fP, \fB\-\-listening\-device\fP \fB\-d\fP, \fB\-\-listening\-device\fP
Listener interface device. Listener interface device.
(NOT RECOMMENDED. Optional functionality, Linux only). (NOT RECOMMENDED. Optional functionality, Linux only).
The \fIturnserver\fP process must have root privileges to bind the The \fIturnserver\fP process must have root privileges to bind the
listening endpoint to a device. If \fIturnserver\fP must run as a listening endpoint to a device. If \fIturnserver\fP must run as a
process without root privileges, then just do not use this setting. process without root privileges, then just do not use this setting.
.TP .TP
.B .B
\fB\-L\fP, \fB\-\-listening\-ip\fP \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: Multiple listeners can be specified, for example:
\fB\-L\fP ip1 \fB\-L\fP ip2 \fB\-L\fP ip3 \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. IPv6 system IPs will be used for listening.
The same \fBip\fP(s) can be used as both listening and relay \fBip\fP(s). The same \fBip\fP(s) can be used as both listening and relay \fBip\fP(s).
.TP .TP
@ -456,11 +451,11 @@ Note: actually, TLS & DTLS sessions can connect to the "plain" TCP & UDP
\fB\-\-tls\-listening\-port\fP \fB\-\-tls\-listening\-port\fP
TURN listener port for TLS and DTLS listeners (Default: 5349). TURN listener port for TLS and DTLS listeners (Default: 5349).
Note: actually, "plain" TCP & UDP sessions can connect to the TLS & DTLS 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 "automatically" recognizes the type of traffic. Actually, two listening
endpoints (the "plain" one and the "tls" one) are equivalent in terms of 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. 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. TLS versions 1.0, 1.1, 1.2.
For secure UDP connections, we support DTLS version 1. For secure UDP connections, we support DTLS version 1.
.TP .TP
@ -505,20 +500,20 @@ to client requests.
.TP .TP
.B .B
\fB\-i\fP, \fB\-\-relay\-device\fP \fB\-i\fP, \fB\-\-relay\-device\fP
Relay interface device for relay sockets Relay interface device for relay sockets
(NOT RECOMMENDED. Optional, Linux only). (NOT RECOMMENDED. Optional, Linux only).
.TP .TP
.B .B
\fB\-E\fP, \fB\-\-relay\-ip\fP \fB\-E\fP, \fB\-\-relay\-ip\fP
Relay address (the local IP address that Relay address (the local IP address that
will be used to relay the packets to the will be used to relay the packets to the
peer). Multiple relay addresses may be used: peer). Multiple relay addresses may be used:
\fB\-E\fP ip1 \fB\-E\fP ip2 \fB\-E\fP ip3 \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). 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 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 default policy: it will decide itself which relay addresses to be
used, and it will always be using the client socket IP address as 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 the relay IP address of the TURN session (if the requested relay
address family is the same as the family of the client socket). address family is the same as the family of the client socket).
.TP .TP
.B .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. \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 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 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. 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. 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 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, In more complex case when more than one IP address is involved,
that option must be used several times, each entry must that option must be used several times, each entry must
have form "\fB\-X\fP <public\-ip/private\-ip>", to map all involved addresses. 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 CHANGE_REQUEST (RFC5780 or RFC3489) NAT discovery STUN functionality will work
correctly, if the addresses are mapped properly, even when the TURN server itself correctly, if the addresses are mapped properly, even when the TURN server itself
is behind A NAT. is behind A NAT.
By default, this value is empty, and no address mapping is used. By default, this value is empty, and no address mapping is used.
.TP .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 Number of the relay threads to handle the established connections
(in addition to authentication thread and the listener thread). (in addition to authentication thread and the listener thread).
If explicitly set to 0 then application runs relay process in a single 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 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 still be a separate thread). If not set, then a default optimal algorithm
will be employed (OS\-dependent). In the older Linux systems 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. per network listening endpoint \- unless "\fB\-m\fP 0" or "\fB\-m\fP 1" is set.
.TP .TP
.B .B
\fB\-\-min\-port\fP \fB\-\-min\-port\fP
Lower bound of the UDP port range for relay Lower bound of the UDP port range for relay
endpoints allocation. endpoints allocation.
Default value is 49152, according to RFC 5766. Default value is 49152, according to RFC 5766.
.TP .TP
.B .B
\fB\-\-max\-port\fP \fB\-\-max\-port\fP
Upper bound of the UDP port range for relay Upper bound of the UDP port range for relay
endpoints allocation. endpoints allocation.
Default value is 65535, according to RFC 5766. Default value is 65535, according to RFC 5766.
.TP .TP
.B .B
\fB\-u\fP, \fB\-\-user\fP \fB\-u\fP, \fB\-\-user\fP
Long\-term security mechanism credentials user account, Long\-term security mechanism credentials user account,
in the column\-separated form username:key. in the column\-separated form username:key.
Multiple user accounts may be used in the command line. Multiple user accounts may be used in the command line.
The key is either the user password, or The key is either the user password, or
the key is generated the key is generated
by \fIturnadmin\fP command. In the second case, by \fIturnadmin\fP command. In the second case,
the key must be prepended with 0x symbols. 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. the user realm, and the user password.
This setting may not be used with TURN REST API. This setting may not be used with TURN REST API.
.TP .TP
.B .B
\fB\-r\fP, \fB\-\-realm\fP \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 origin/realm relationship was found in the database, or if the TURN
server is not using any database (just the commands\-line settings 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. mechanism or with TURN REST API.
.TP .TP
.B .B
\fB\-C\fP, \fB\-\-rest\-api\-separator\fP \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 :. (character) in TURN REST API. The default value is :.
.TP .TP
.B .B
\fB\-q\fP, \fB\-\-user\-quota\fP \fB\-q\fP, \fB\-\-user\-quota\fP
Per\-user allocations quota: how many concurrent Per\-user allocations quota: how many concurrent
allocations a user can create. This option can also be set allocations a user can create. This option can also be set
through the database, for a particular realm. through the database, for a particular realm.
.TP .TP
.B .B
@ -602,9 +597,9 @@ This option can also be set through the database, for a particular realm.
.B .B
\fB\-s\fP, \fB\-\-max\-bps\fP \fB\-s\fP, \fB\-\-max\-bps\fP
Max bytes\-per\-second bandwidth a TURN session is allowed to handle 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 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. database, for a particular realm.
.TP .TP
.B .B
@ -617,7 +612,7 @@ separately).
.B .B
\fB\-\-static\-auth\-secret\fP \fB\-\-static\-auth\-secret\fP
Static authentication secret value (a string) for TURN REST API only. 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 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 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 that other mode is dynamic. Multiple shared secrets can be used
@ -631,17 +626,17 @@ The default value is the realm name.
.TP .TP
.B .B
\fB\-\-cert\fP \fB\-\-cert\fP
Certificate file, PEM format. Same file Certificate file, PEM format. Same file
search rules applied as for the configuration search rules applied as for the configuration
file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
are specified, then this parameter is not needed. are specified, then this parameter is not needed.
Default value is turn_server_cert.pem. Default value is turn_server_cert.pem.
.TP .TP
.B .B
\fB\-\-pkey\fP \fB\-\-pkey\fP
Private key file, PEM format. Same file Private key file, PEM format. Same file
search rules applied as for the configuration search rules applied as for the configuration
file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP file. If both \fB\-\-no\-tls\fP and \fB\-\-no\-dtls\fP \fIoptions\fP
are specified, then this parameter is not needed. are specified, then this parameter is not needed.
Default value is turn_server_pkey.pem. Default value is turn_server_pkey.pem.
.TP .TP
@ -656,14 +651,14 @@ Default value is "DEFAULT".
.TP .TP
.B .B
\fB\-\-CA\-file\fP \fB\-\-CA\-file\fP
CA file in OpenSSL format. CA file in OpenSSL format.
Forces TURN server to verify the client SSL certificates. Forces TURN server to verify the client SSL certificates.
By default, no CA is set and no client certificate check is performed. By default, no CA is set and no client certificate check is performed.
.TP .TP
.B .B
\fB\-\-ec\-curve\-name\fP \fB\-\-ec\-curve\-name\fP
Curve name for EC ciphers, if supported by OpenSSL Curve name for EC ciphers, if supported by OpenSSL
library (TLS and DTLS). The default value is prime256v1, library (TLS and DTLS). The default value is prime256v1,
if pre\-OpenSSL 1.0.2 is used. With OpenSSL 1.0.2+, if pre\-OpenSSL 1.0.2 is used. With OpenSSL 1.0.2+,
an optimal curve will be automatically calculated, if not defined an optimal curve will be automatically calculated, if not defined
by this option. by this option.
@ -676,74 +671,74 @@ Flags \fB\-\-dh566\fP and \fB\-\-dh1066\fP are ignored when the DH key is taken
.B .B
\fB\-l\fP, \fB\-\-log\-file\fP \fB\-l\fP, \fB\-\-log\-file\fP
Option to set the full path name of the log file. Option to set the full path name of the log file.
By default, the \fIturnserver\fP tries to open a log file in By default, the \fIturnserver\fP tries to open a log file in
/var/log/\fIturnserver\fP, /var/log, /var/tmp, /tmp and . (current) /var/log/\fIturnserver\fP, /var/log, /var/tmp, /tmp and . (current)
directories (which file open operation succeeds directories (which file open operation succeeds
first that file will be used). With this option you can set the first that file will be used). With this option you can set the
definite log file name. 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 to the stdout. Also, "syslog" name will redirect everything into
the system log (syslog), as if the option "\fB\-\-syslog\fP" was set. 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 In the runtime, the logfile can be reset with the SIGHUP signal
to the \fIturnserver\fP process. to the \fIturnserver\fP process.
.TP .TP
.B .B
\fB\-\-alternate\-server\fP \fB\-\-alternate\-server\fP
Option to set the "redirection" mode. The value of this option 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 <ip>[:<port>]. The server will send this value in the attribute
ALTERNATE\-SERVER, with error 300, on ALLOCATE request, to the client. ALTERNATE\-SERVER, with error 300, on ALLOCATE request, to the client.
Client will receive only values with the same address family Client will receive only values with the same address family
as the client network endpoint address family. as the client network endpoint address family.
See RFC 5389 and RFC 5766 for ALTERNATE\-SERVER functionality description. See RFC 5389 and RFC 5766 for ALTERNATE\-SERVER functionality description.
The client must use the obtained value for subsequent TURN communications. 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 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". can be more accurately described as "load\-balancing" than a mere "redirection".
If the port number is omitted, then the default port If the port number is omitted, then the default port
number 3478 for the UDP/TCP protocols will be used. number 3478 for the UDP/TCP protocols will be used.
Colon (:) characters in IPv6 addresses may conflict with the syntax of Colon (:) characters in IPv6 addresses may conflict with the syntax of
the option. To alleviate this conflict, literal IPv6 addresses are enclosed the option. To alleviate this conflict, literal IPv6 addresses are enclosed
in square brackets in such resource identifiers, for example: in square brackets in such resource identifiers, for example:
[2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 . [2001:db8:85a3:8d3:1319:8a2e:370:7348]:3478 .
Multiple alternate servers can be set. They will be used in the 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 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, 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 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 address can be used more than one time with the alternate\-server option, so this
can emulate "weighting" of the servers. can emulate "weighting" of the servers.
.TP .TP
.B .B
\fB\-\-tls\-alternate\-server\fP \fB\-\-tls\-alternate\-server\fP
Option to set alternative server for TLS & DTLS services in form of Option to set alternative server for TLS & DTLS services in form of
<ip>:<port>. If the port number is omitted, then the default port <ip>:<port>. If the port number is omitted, then the default port
number 5349 for the TLS/DTLS protocols will be used. See the number 5349 for the TLS/DTLS protocols will be used. See the
previous option for the functionality description. previous option for the functionality description.
.TP .TP
.B .B
\fB\-O\fP, \fB\-\-redis\-statsdb\fP \fB\-O\fP, \fB\-\-redis\-statsdb\fP
Redis status and statistics database connection string, if used (default \- empty, 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 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. 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, 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. PostgreSQL can be used for the user database.
The connection string has the same parameters as redis\-userdb connection string. The connection string has the same parameters as redis\-userdb connection string.
.TP .TP
.B .B
\fB\-\-max\-allocate\-timeout\fP \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. Default is 60 seconds.
.PP .PP
\fB\-\-denied\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]> \fB\-\-denied\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]>
.PP .PP
\fB\-\-allowed\-peer\-ip\fP=<IPaddr[\fB\-IPaddr\fP]> Options to ban or allow specific ip addresses or ranges \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 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 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. 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 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 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 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. IP ranges can also be dynamically changed in the database.
The allowed/denied addresses (white/black lists) rules are very simple: The allowed/denied addresses (white/black lists) rules are very simple:
.RS .RS
.IP 1) 4 .IP 1) 4
@ -781,9 +776,9 @@ Client <=> Server communication address family.
\fB\-\-cli\-ip\fP \fB\-\-cli\-ip\fP
Local system IP address to be used for CLI management interface. Local system IP address to be used for CLI management interface.
The \fIturnserver\fP process can be accessed for management with telnet, 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) 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 .TP
.B .B
\fB\-\-cli\-port\fP \fB\-\-cli\-port\fP
@ -837,24 +832,24 @@ This is a set of notes for the WebRTC users:
.IP 1) 4 .IP 1) 4
WebRTC uses long\-term authentication mechanism, so you have to use \fB\-a\fP 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 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 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, 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: for that you have a number of \fIoptions\fP:
.PP .PP
.nf .nf
.fam C .fam C
a) command\-line options (\-u). a) command\-line options (\-u).
b) a database table (SQLite or PostgreSQL or MySQL or MongoDB). You will have to 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). set keys with turnadmin utility (see docs and wiki for turnadmin).
You cannot use open passwords in the database. You cannot use open passwords in the database.
c) Redis key/value pair(s), if Redis is used. You key use either keys or 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. 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 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 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 .fam T
.fi .fi
@ -872,19 +867,19 @@ number range.
.SH TURN REST API .SH TURN REST API
In WebRTC, the browser obtains the TURN connection information from the web In WebRTC, the browser obtains the TURN connection information from the web
server. This information is a secure information \- because it contains the server. This information is a secure information \- because it contains the
necessary TURN credentials. As these credentials are transmitted over the necessary TURN credentials. As these credentials are transmitted over the
public networks, we have a potential security breach. public networks, we have a potential security breach.
.PP .PP
If we have to transmit a valuable information over the public network, 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 then this information has to have a limited lifetime. Then the guy who
obtains this information without permission will be able to perform obtains this information without permission will be able to perform
only limited damage. only limited damage.
.PP .PP
This is how the idea of TURN REST API \- time\-limited TURN credentials \- This is how the idea of TURN REST API \- time\-limited TURN credentials \-
appeared. This security mechanism is based upon the long\-term 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 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 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. limited time by an application that has to create a TURN server connection.
.PP .PP
The "classic" long\-term credentials mechanism (LTCM) is described here: The "classic" long\-term credentials mechanism (LTCM) is described here:
@ -895,22 +890,22 @@ http://tools.ietf.org/html/rfc5389#section\-15.4
.PP .PP
For authentication, each user must know two things: the username and the For authentication, each user must know two things: the username and the
password. Optionally, the user must supply the ORIGIN value, so that 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 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 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 anything about the nature and about the persistence of the username and
of the password; and this is used by the REST API. of the password; and this is used by the REST API.
.PP .PP
In the TURN REST API, there is no persistent passwords for users. A user has 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 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, 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, actually, a temporary one\-time session only, username is provided to the user,
too. too.
.PP .PP
The temporary user is generated as: The temporary user is generated as:
.PP .PP
temporary\-username="timestamp" + ":" + "username" temporary\-username="timestamp" + ":" + "username"
.PP .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. seconds since 1970 \- the same value as \fBtime\fP(NULL) function returns.
.PP .PP
The temporary password is obtained as HMAC\-SHA1 function over the temporary 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 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. deployment details \- this is beyond the scope of the TURN REST API.
.PP .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 timestamp can be retrieved from the temporary username. This information
is valuable, but only temporary, while the timestamp is not expired. Without is valuable, but only temporary, while the timestamp is not expired. Without
knowledge of the shared secret, a new temporary password cannot be generated. 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 .RS
.IP \(bu 3 .IP \(bu 3
a new TURN client sends a request command to the TURN server. Optionally, 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 .IP \(bu 3
TURN server sees that this is a new client and the message is not TURN server sees that this is a new client and the message is not
authenticated. 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) (SASLprep is described here: http://tools.ietf.org/html/rfc4013)
.IP \(bu 3 .IP \(bu 3
the client forms a new request, adds username, realm and nonce to the 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 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 http://tools.ietf.org/html/rfc5389#section\-15.4
.IP \(bu 3 .IP \(bu 3
the client, optionally, adds the fingerprint field. This may be also 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. WebRTC usually uses fingerprinted TURN messages.
.IP \(bu 3 .IP \(bu 3
the TURN server receives the request, reads the username. 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. then the TURN server calculates the integrity field.
.IP \(bu 3 .IP \(bu 3
then the TURN server compares the calculated integrity field with the 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. then the request is rejected.
.RE .RE
.PP .PP
In subsequent communications, the client may go with exactly the same In subsequent communications, the client may go with exactly the same
sequence, but for optimization usually the client, having already sequence, but for optimization usually the client, having already
information about realm and nonce, pre\-calculates the integrity string information about realm and nonce, pre\-calculates the integrity string
for each request, so that the 401 error response becomes unnecessary. 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 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 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. with the new nonce, and the client will have to start using the new nonce.
.PP .PP
In subsequent communications, the server and the client will always assume In subsequent communications, the server and the client will always assume
the same password \- the original password becomes the session parameter and 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 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, 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 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, 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 the client will have to use the new password to re\-connect (if the password
has been changed). has been changed).
.PP .PP
An example when a new shared secret is generated every hour by the TURN server 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 box and then supplied to the web server, remotely, is provided in the script
examples/scripts/restapi/shared_secret_maintainer.pl . examples/scripts/restapi/shared_secret_maintainer.pl .
.PP .PP
A very important thing is that the nonce must be totally random and it must be A very important thing is that the nonce must be totally random and it must be
different for different clients and different sessions. different for different clients and different sessions.
.PP .PP
=================================== ===================================
.SH DATABASES .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: For the user database, the \fIturnserver\fP has the following \fIoptions\fP:
.IP 1) 4 .IP 1) 4
Users can be set in the command line, with multiple \fB\-u\fP or \fB\-\-user\fP \fIoptions\fP. 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. for the \fIturnserver\fP process lifetime.
.IP 2) 4 .IP 2) 4
Users can be stored in SQLite DB. The default SQLite database file is /var/db/turndb 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 .IP 3) 4
Users can be stored in PostgreSQL database, if the \fIturnserver\fP was compiled with PostgreSQL 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, 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 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 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. 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 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. 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 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 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. in a batch script). See the file turndb/testsqldbsetup.sql as an example.
.IP 4) 4 .IP 4) 4
The same is true for MySQL database. The same schema file is applicable. 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 .IP 5) 4
The same is true for the Redis database, but the Redis database has aa different schema \- 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. 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) \- 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. the "open password" option is less secure but more convenient for low\-security environments.
See the file turndb/testredisdbsetup.sh as an example. See the file turndb/testredisdbsetup.sh as an example.
.IP 6) 4 .IP 6) 4
If a database is used, then users can be divided into multiple independent realms. Each realm 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 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. will be simply ignored.
.IP 2) 4 .IP 2) 4
If you choose to use it, then set the \fB\-\-redis\-statsdb\fP option. This may be the same database 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 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. MySQL as the user database, and you can use redis for the statistics. Or you can use Redis for both.
.PP .PP
So, we have 6 choices for the user management, and 2 choices for the statistics management. These 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. choose any for your convenience.
.PP .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 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 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 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 \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 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). location (/var/db/turndb or /usr/local/var/db/turndb or /var/lib/turn/turndb, depending on the system).
.PP .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 lib/ sub\-directory the build process will create TURN client messaging library.
In the include/ sub\-directory, the necessary include files will be placed. 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. 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 .PP
================================= =================================
.SH DOCS .SH DOCS
@ -1102,13 +1097,13 @@ $ man \fB\-M\fP man \fIturnserver\fP
.PP .PP
to see the man page. to see the man page.
.PP .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. reference. After the installation, it will be placed in PREFIX/share/doc/\fIturnserver\fP/html.
.PP .PP
================================= =================================
.SH LOGS .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: in the following directories:
.RS .RS
.IP \(bu 3 .IP \(bu 3
@ -1123,7 +1118,7 @@ in the following directories:
current directory current directory
.RE .RE
.PP .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. log messages are sent only to the standard output of the process.
.PP .PP
This behavior can be controlled by \fB\-\-log\-file\fP, \fB\-\-syslog\fP and \fB\-\-no\-stdout\-log\fP 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 .SH HTTPS MANAGEMENT INTERFACE
The \fIturnserver\fP process provides an HTTPS Web access as statistics and basic 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 connections on the same ports as the main TURN/STUN listener. The Web admin
pages are basic and self\-explanatory. pages are basic and self\-explanatory.
.PP .PP
@ -1155,11 +1150,11 @@ in "help" command output in the telnet CLI.
================================= =================================
.SH CLUSTERS .SH CLUSTERS
\fBTURN Server\fP can be a part of the cluster installation. But, to support the "even port" functionality \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 (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 \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 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 to design a scheme with the application\-level requests forwarding (and we may do that later) but
it would affect the performance. it would affect the performance.
.PP .PP
================================= =================================

30
man/man1/turnutils.1
View File

@ -51,12 +51,12 @@ addresses should be configured to be able to work properly!
.TP .TP
.B .B
6. 6.
\fIturnutils_oauth\fP: a utility that provides OAuth access_token \fIturnutils_oauth\fP: a utility that provides OAuth access_token
\fBgeneration\fP(AEAD encryption), validation and decryption. This utility inputs \fBgeneration\fP(AEAD encryption), validation and decryption. This utility inputs
all the keys and lifetimes and any related information that needed for 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 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 PoP parameters that need to pass to the client. Output is generated accoriding
RFC7635 Appendix B, Figure 8. RFC7635 Appendix B, Figure 8.
.PP .PP
For more details, and for the access_token structure, read rfc7635, and see For more details, and for the access_token structure, read rfc7635, and see
script in examples/scripts/oauth.sh. script in examples/scripts/oauth.sh.
@ -480,15 +480,15 @@ $ \fIturnutils_oauth\fP [\fIoptions\fP]
.fi .fi
.SS DESCRIPTION .SS DESCRIPTION
\fIturnutils_oauth\fP utilitiy provides help in OAuth access_token encryption and/or \fIturnutils_oauth\fP utilitiy provides help in OAuth access_token encryption and/or
decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps decryption with AEAD (Atuthenticated Encryption with Associated Data). It helps
for an Auth Server in access_token creation, and also for debugging purposes it 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 helps the access_token validation and decryption. This utility inputs all the
keys and lifetimes and any related information that are needed for encryption 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 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 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 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" / 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". "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 For more details, and for the access_token structure, read rfc7635, and see
the example in examples/scripts/oauth.sh. the example in examples/scripts/oauth.sh.