Provided by: coturn_4.6.1-1build1_amd64 bug

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)