TURN(1)

🌈 TURN(1) 🌈

okay bestie, welcome to the turnutils cinematic universe 💖 this is the home page for a whole squad of turnutils_* programs — a set of utility functionality you use for testing and for setting up the TURN server. no cap. let's meet the cast 👑

---

✨ GENERAL INFORMATION ✨

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 validation of an access_token. It outputs a JSON with all OAuth PoP parameters that need to pass to the client. Output is generated according 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 keys kid='north', 'union' or 'oldempire'.
• -Y — Load-generator mode: packet floods data through a single TURN allocation as fast as possible, alloc creates allocations as fast as possible, and invalid sends small invalid packets to the TURN listener as fast as possible. Load-generator modes imply -c and do not support -y.
• --no-even-port — Never attach an EVEN-PORT attribute to ALLOCATE requests. The default clnet_allocate path picks 0 or -1 randomly even under -c, which the turnserver --multiplex-peer mode strictly rejects with error 400. Use --no-even-port for clean alloc-flood runs and any other testing against --multiplex-peer.
• --listener-threads <N> — Number of receive (listener) threads on the loadgen (also available as -K N). Default auto: 0 for -m < 4, bumped to 1 when -m >= 4. 0 keeps the legacy single-event-base behaviour. Each listener owns its own libevent base; sessions are sharded round-robin. Max 4.
• --sender-threads <N> — Number of send (timer-driven) threads on the loadgen. Default auto: 0 for -m < 4, bumped to 2 when -m >= 4. 0 keeps the legacy single-threaded send (main thread's timer_handler iterates all sessions). Each sender owns its own libevent base and a session shard; per-tick sends coalesce into one UDP-GSO sendmsg (or one sendmmsg when GSO is unavailable). Max 4.

---

💫 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). In load-generator mode, -n is the number of operations per client. If omitted there, the client runs until interrupted.
• -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). In packet and invalid load-generator modes the default is 0 ms.
• -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.

---

🦋 Notes for load-generator mode 🦋

• packet mode still performs the normal TURN allocation/setup and then starts sending immediately with no pacing.
• alloc mode does not require -e; it repeatedly establishes new allocations and closes them again.
• alloc mode does not require -e; it repeatedly establishes new allocations, uses a unique client local port for each one, attaches each one to a unique synthetic peer ip:port, and closes them again.
• invalid mode does not require -e; by default it uses 16-byte payloads unless -l is specified.

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

📜 SYNOPSIS

$ turnutils_stunclient [options] <STUN-Server-IP-address>

💖 DESCRIPTION

Okay so bestie, this one is literally just a basic STUN client. It sends a "new" STUN RFC 5389 request (over UDP, btw) and then shows you the reply information it got back. no cap, that's the whole job. 👑

Options with required values — yes, every single one of these needs a value, no freeloaders allowed:

• -p — STUN server port. (Default: 3478.)
• -L — Local address to use (optional).
• -f — Force RFC 5780 processing.
• -c — Continuously send STUN binding requests and report round-trip latency until interrupted. it's giving "runs forever until you Ctrl-C it" 💅
• -i — Interval between continuous requests in milliseconds. (Default: 1000.)
• -t — Response timeout in milliseconds. (Default: 3000.)

Then here's the plot twist: turnutils_stunclient checks the results of that first request, and if it finds out that the STUN server supports RFC 5780 — and the binding response is the thing that reveals that, iykyk — then it makes a couple more requests with different parameters, to demonstrate the NAT discovery capabilities. main character behavior, fr fr ✨

Continuous mode reports every single response or timeout, and when you interrupt it with Ctrl-C it prints packet loss plus the minimum/average/maximum round-trip latency. 😭 so thorough of it.

Heads up bestie: this utility does not support the "old" "classic" STUN protocol (RFC 3489). Not even a little bit. It is not on the guest list. 🚫

---

🧪 NAME 🧪 — turnutils_rfc5769check

📜 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. and it's only used for the compilation check procedure — it is not copied to the installation destination. so it's the backstage bestie that never goes on stage. 🎭

Usage:

$ turnutils_rfc5769check

---

🦋 NAME 🦋 — turnutils_natdiscovery

📜 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. it's a full-on vibe check for your NAT, bestie. 🔍

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

📜 SYNOPSIS

$ turnutils_oauth [options]

💖 DESCRIPTION

turnutils_oauth is the utility that helps with OAuth access_token generation/encryption and validation/decryption, and it's genuinely so useful. It provides help in OAuth access_token encryption and/or decryption with AEAD (Authenticated Encryption with Associated Data). It helps an Auth Server in access_token creation, and for debugging purposes it also 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 according to RFC7635 Appendix B, Figure 8.

This utility could help you build an Auth Server service — but be aware, bestie, of what it does not do: this utility does not generate "session key" / "mac_key", and it does not verify the lifetime of "session key" / "mac_key" or "Auth key". so don't come for it about that. 💀

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

okay so yes, that usage line really does say turnutils_natdiscovery on the turnutils_oauth page. iconic. not me fixing it. we keep the lore exactly as written. 🙈

---

📚 DOCS 📚

After installation, run the command:

$ man turnutils

or, if you're hanging out in the project root directory:

$ man -M man turnutils

and boom, you've got 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 👑

See the AUTHORS.md file in the coturn source distribution. that's where the whole squad is credited. 💜

---

and that's a wrap on TURN(1), bestie! 🎀 this beauty is dated 17 May 2026 and it's part of the coturn source, version-tagged TURN(1) — so go forth, read your man pages, and slay. 💅✨