Ubuntu Manpage: A set of turnutils_* programs provides some utility functionality to be used for testing and for setting

Provided by: coturn_4.5.1.1-1.1ubuntu0.20.04.2_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

       ====================================

GENERAL INFORMATION

DOCS

FILES

DIRECTORIES

STANDARDS

SEE ALSO