Provided by: coturn_4.6.1-1build1_amd64 
GENERAL INFORMATION
A set of turnutils_* programs provides some utility functionality to be used for testing
and for setting up the TURN server.
1. turnutils_uclient: emulates multiple UDP,TCP,TLS or DTLS clients. (this program is
provided for the testing purposes only !) The compiled binary image of this
program is located in bin/ sub-directory.
2. turnutils_peer: a simple stateless UDP-only "echo" server, to be used as the final
server in relay pattern ("peer"). For every incoming UDP packet, it simply echoes
it back. (this program is provided for the testing purposes only !) When the test
clients are communicating in the client-to-client manner (when the
"turnutils_uclient" program is used with "-y" option) then the turnutils_peer is
not needed.
The compiled binary image of this program is located in bin/ subdirectory.
3. turnutils_stunclient: a simple STUN client example. The compiled binary image of
this program is located in bin/ subdirectory.
4. turnutils_rfc5769check: a utility that checks the correctness of the STUN/TURN
protocol implementation. This utility is used only for the compilation check
procedure, it is not copied to the installation destination.
In the "examples/scripts" subdirectory, you will find the examples of command lines to be
used to run the programs. The scripts are meant to be run from examples/ subdirectory, for
example:
$ cd examples
$ ./scripts/secure_relay.sh
5. turnutils_natdiscovery: a utility that provides NAT behavior discovery according
RFC5780. This utility discovers the actual NAT Mapping and Filtering behavior, etc.
Be aware that on TURN server side two different listening IP addresses should be
configured to be able to work properly!
6. turnutils_oauth: a utility that provides OAuth access_token generation(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.
For more details, and for the access_token structure, read rfc7635, and see script in
examples/scripts/oauth.sh.
=====================================
NAME
turnutils_uclient - this client emulation application is supplied for the test purposes
only.
SYNOPSIS
$ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>
DESCRIPTION
It was designed to simulate multiple clients. It uses asynch IO API in libevent to handle
multiple clients. A client connects to the relay, negotiates the session, and sends
multiple (configured number) messages to the server (relay), expecting the same number of
replies. The length of the messages is configurable. The message is an arbitrary octet
stream. The number of the messages to send is configurable.
Flags:
-t Use TCP for communications between client and TURN server (default is UDP).
-b Use SCTP for communications between client and TURN server (default is UDP).
-T Use TCP for the relay transport (default - UDP). Implies options -t, -y, -c, and
ignores flags and options -s, -e, -r and -g. Can be used together with -b.
-P Passive TCP (RFC6062 with active peer). Implies -T.
-S Secure SSL connection: SSL/TLS for TCP, DTLS for UDP, TLS/SCTP for SCTP.
-U Secure unencrypted connection (suite eNULL): SSL/TLS for TCP, DTLS for UDP.
-v Verbose.
-s Use "Send" method in TURN; by default, it uses TURN Channels.
-y Use client-to-client connections: RTP/RTCP pair of channels to another RTP/RTCP
pair of channels. with this option the turnutils_peer application is not used, as
the allocated relay endpoints are talking to each other.
-h Hang on indefinitely after the last sent packet.
-c Do not create rtcp connections.
-x Request IPv6 relay address (RFC6156).
-X IPv4 relay address explicitly requested.
-g Set DONT_FRAGMENT parameter in TURN requests.
-D Do mandatory channel padding even for UDP (like pjnath).
-N do negative tests (some limited cases only).
-R do negative protocol tests.
-O DOS attack mode.
-M Use TURN ICE Mobility.
-I Do not set permissions on TURN relay endpoints (for testing the non-standard server
relay functionality).
-G Generate extra requests (create permissions, channel bind).
-B Random disconnect after a few initial packets.
-Z Dual allocation (SSODA). Implies -c option.
-J Use oAuth with default test key kid='north'.
Options with required values:
-l Message length (Default: 100 Bytes).
-i Certificate file (for secure connections only, optional).
-k Private key file (for secure connections only).
-E CA file for server certificate verification, if the server certificate to be
verified.
-p TURN Server port (Defaults: 3478 unsecure, 5349 secure).
-n Number of messages to send (Default: 5).
-d Local interface device (optional, Linux only).
-L Local IP address (optional).
-m Number of clients (Default: 1, 2 or 4, depending on options).
-e Peer address.
-r Peer port (Default: 3480).
-z Per-session packet interval in milliseconds (Default: 20).
-u STUN/TURN user name.
-w STUN/TURN user password.
-W TURN REST API secret. The "plain text" secret e.g. "north" that is stored in the
value column of the turn_secret table in the database if dynamic, or the
static-auth-secret value set in the configuration file if using static.
-C This is the timestamp/username separator symbol (character) in TURN REST API. The
default value is :.
-F Cipher suite for TLS/DTLS. Default value is DEFAULT.
-o the ORIGIN STUN attribute value.
-a Bandwidth for the bandwidth request in ALLOCATE. The default value is zero.
See the examples in the "examples/scripts" directory.
======================================
NAME
turnutils_peer - a simple UDP-only echo backend server.
SYNOPSIS
$ turnutils_peer [-v] [options]
DESCRIPTION
This application is used for the test purposes only, as a peer for the turnutils_uclient
application.
Options with required values:
-p Listening UDP port (Default: 3480).
-d Listening interface device (optional)
-L Listening address of turnutils_peer server. Multiple listening addresses can be
used, IPv4 and IPv6. If no listener address(es) defined, then it listens on all
IPv4 and IPv6 addresses.
-v Verbose
========================================
NAME
turnutils_stunclient - a basic STUN client.
SYNOPSIS
$ turnutils_stunclient [options] <STUN-Server-IP-address>
DESCRIPTION
It sends a "new" STUN RFC 5389 request (over UDP) and shows the reply information.
Options with required values:
-p STUN server port (Default: 3478).
-L Local address to use (optional).
-f Force RFC 5780 processing.
The turnutils_stunclient program checks the results of the first request, and if it finds
that the STUN server supports RFC 5780 (the binding response reveals that) then the
turnutils_stunclient makes a couple more requests with different parameters, to
demonstrate the NAT discovery capabilities.
This utility does not support the "old" "classic" STUN protocol (RFC 3489).
=====================================
NAME
turnutils_rfc5769check - a utility that tests the correctness of STUN protocol
implementation.
SYNOPSIS
$ turnutils_rfc5769check
DESCRIPTION
turnutils_rfc5769check tests the correctness of STUN protocol implementation against the
test vectors predefined in RFC 5769 and prints the results of the tests on the screen.
This utility is used only for the compilation check procedure, it is not copied to the
installation destination.
Usage:
$ turnutils_rfc5769check
=====================================
NAME
turnutils_natdiscovery - a utility that discovers NAT mapping and filtering behavior
according RFC5780.
SYNOPSIS
$ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>
DESCRIPTION
turnutils_natdiscovery discovers the NAT Mapping and Filtering behavior, to determine if
that NAT is currently using Endpoint-Independent, Address-Dependent, or Address and
Port-Dependent Mapping and/or to determine if that NAT is currently using
Endpoint-Independent, Address-Dependent, or Address and Port-Dependent Filtering.
Use either -m, -f, -c, -H flag to discover NAT behavior.
Flags:
-m NAT mapping behavior discovery
-f NAT filtering behavior discovery
-t NAT mapping lifetime behavior discovery Requires a timer (-T)
-c NAT collision behavior discovery
-H NAT hairpinning behavior discovery
-P Add 1500 byte Padding to the behavior discovery Applicable with all except NAT
mapping Lifetime discovery
Options with required values:
-p STUN server port (Default: 3478)
-L Local address to use (optional)
-l Local port to use (use with -L)
-A Secondary Local address (optional) Required for collision discovery
-T Mapping lifetime timer (sec) Used by mapping lifetime behavior discovery
Usage:
$ turnutils_natdiscovery -m -f stun.example.com
=====================================
NAME
turnutils_oauth - a utility that helps OAuth access_token generation/encryption and
validation/decyption
SYNOPSIS
$ turnutils_oauth [options]
DESCRIPTION
turnutils_oauth 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.
Use either -e and/or -d flag to encrypt or decrypt access_token.
Flags:
-h, --help
usage
-v, --verbose
verbose mode
-e, --encrypt
encrypt token
-d, --decrypt
decrypt validate token
Options with required values:
-i, --server-name
server name (max. 255 char)
-j, --auth-key-id
Auth key id (max. 32 char)
-k, --auth-key
base64 encoded Auth key
-l --auth-key-timestamp Auth key timestamp (sec since epoch)
-m, --auth-key-lifetime
Auth key lifetime in sec
-n, --auth-key-as-rs-alg
Authorization Server(AS) - Resource Server(RS) encryption algorithm
-o, --token-nonce
base64 encoded nonce base64(12 octet) = 16 char
-p, --token-mac-key
base64 encoded MAC key base64(32 octet) = 44 char
-q, --token-timestamp
timestamp in format 64 bit unsigned (Native format - Unix), so 48 bit for secs
since epoch UTC + 16 bit for 1/64000 fractions of a second. e.g.: the actual
unixtimestamp 16 bit left shifted. (Default: actual gmtime)
-r, --token-lifetime
lifetime in sec (Default: 3600)
-t, --token
base64 encoded encrypted token for validation and decryption
-u, --hmac-alg
stun client hmac algorithm
Usage:
$ turnutils_natdiscovery
===================================
DOCS
After installation, run the command:
$ man turnutils
or in the project root directory:
$ man -M man turnutils
to see the man page.
=====================================
FILES
/etc/turnserver.conf
/var/db/turndb
/usr/local/var/db/turndb
/var/lib/turn/turndb
/usr/local/etc/turnserver.conf
=================================
DIRECTORIES
/usr/local/share/turnserver
/usr/local/share/doc/turnserver
/usr/local/share/examples/turnserver
===================================
STANDARDS
new STUN RFC 5389
TURN RFC 5766
TURN-TCP extension RFC 6062
TURN IPv6 extension RFC 6156
STUN/TURN test vectors RFC 5769
STUN NAT behavior discovery RFC 5780
====================================
SEE ALSO
turnserver, turnadmin
======================================
WEB RESOURCES
project page:
https://github.com/coturn/coturn/
Wiki page:
https://github.com/coturn/coturn/wiki
forum:
https://groups.google.com/forum/?fromgroups=#!forum/turn-server-project-rfc5766-turn-server/
======================================
AUTHORS
Oleg Moskalenko <mom040267@gmail.com>
Gabor Kovesdan http://kovesdan.org/
Daniel Pocock http://danielpocock.com/
John Selbie (jselbie@gmail.com)
Lee Sylvester <lee@designrealm.co.uk>
Erik Johnston <erikj@openmarket.com>
Roman Lisagor <roman@demonware.net>
Vladimir Tsanev <tsachev@gmail.com>
Po-sheng Lin <personlin118@gmail.com>
Peter Dunkley <peter.dunkley@acision.com>
Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
Federico Pinna <fpinna@vivocha.com>
Bradley T. Hughes <bradleythughes@fastmail.fm>
Mihály Mészáros <misi@majd.eu>
ACTIVE MAINTAINERS
Mihály Mészáros <misi@majd.eu>
05 June 2021 TURN(1)