1TURN(1) TURN(1)
2
6 A set of turnutils_* programs provides some utility functionality to be
7 used for testing and for setting up the TURN server.
8 1. turnutils_uclient: emulates multiple UDP,TCP,TLS or DTLS
10 clients. (this program is provided for the testing purposes
11 only !) The compiled binary image of this program is located in
12 bin/ sub-directory.
13 2. turnutils_peer: a simple stateless UDP-only "echo" server, to be
15 used as the final server in relay pattern ("peer"). For every
16 incoming UDP packet, it simply echoes it back. (this program is
17 provided for the testing purposes only !) When the test clients
18 are communicating in the client-to-client manner (when the "tur‐
19 nutils_uclient" program is used with "-y" option) then the tur‐
20 nutils_peer is not needed.
21 The compiled binary image of this program is located in bin/ subdirec‐
23 tory.
24 3. turnutils_stunclient: a simple STUN client example. The com‐
26 piled binary image of this program is located in bin/ subdirec‐
27 tory.
28 4. turnutils_rfc5769check: a utility that checks the correctness of
30 the STUN/TURN protocol implementation. This utility is used only
31 for the compilation check procedure, it is not copied to the in‐
32 stallation destination.
33 In the "examples/scripts" subdirectory, you will find the examples of
35 command lines to be used to run the programs. The scripts are meant to
36 be run from examples/ subdirectory, for example:
37 $ cd examples
39 $ ./scripts/secure_relay.sh
41 5. turnutils_natdiscovery: a utility that provides NAT behavior
43 discovery according RFC5780. This utility discovers the actual
44 NAT Mapping and Filtering behavior, etc. Be aware that on TURN
45 server side two different listening IP addresses should be con‐
46 figured to be able to work properly!
47 6. turnutils_oauth: a utility that provides OAuth access_token gen‐
49 eration(AEAD encryption), validation and decryption. This util‐
50 ity inputs all the keys and lifetimes and any related informa‐
51 tion that needed for creation and validationi of an access_to‐
52 ken. It outputs a JSON with all OAuth PoP parameters that need
53 to pass to the client. Output is generated accoriding RFC7635
54 Appendix B, Figure 8.
55 For more details, and for the access_token structure, read rfc7635, and
57 see script in examples/scripts/oauth.sh.
58
60 NAME
61 turnutils_uclient - this client emulation application is supplied for
62 the test purposes only.
63 SYNOPSIS
65 $ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>
66 DESCRIPTION
69 It was designed to simulate multiple clients. It uses asynch IO API in
70 libevent to handle multiple clients. A client connects to the relay,
71 negotiates the session, and sends multiple (configured number) messages
72 to the server (relay), expecting the same number of replies. The length
73 of the messages is configurable. The message is an arbitrary octet
74 stream. The number of the messages to send is configurable.
75 Flags:
77 -t Use TCP for communications between client and TURN server (de‐
79 fault is UDP).
80 -b Use SCTP for communications between client and TURN server (de‐
82 fault is UDP).
83 -T Use TCP for the relay transport (default - UDP). Implies options
85 -t, -y, -c, and ignores flags and options -s, -e, -r and -g. Can
86 be used together with -b.
87 -P Passive TCP (RFC6062 with active peer). Implies -T.
89 -S Secure SSL connection: SSL/TLS for TCP, DTLS for UDP, TLS/SCTP
91 for SCTP.
92 -U Secure unencrypted connection (suite eNULL): SSL/TLS for TCP,
94 DTLS for UDP.
95 -v Verbose.
97 -s Use "Send" method in TURN; by default, it uses TURN Channels.
99 -y Use client-to-client connections: RTP/RTCP pair of channels to
101 another RTP/RTCP pair of channels. with this option the turnu‐
102 tils_peer application is not used, as the allocated relay end‐
103 points are talking to each other.
104 -h Hang on indefinitely after the last sent packet.
106 -c Do not create rtcp connections.
108 -x Request IPv6 relay address (RFC6156).
110 -X IPv4 relay address explicitly requested.
112 -g Set DONT_FRAGMENT parameter in TURN requests.
114 -D Do mandatory channel padding even for UDP (like pjnath).
116 -N do negative tests (some limited cases only).
118 -R do negative protocol tests.
120 -O DOS attack mode.
122 -M Use TURN ICE Mobility.
124 -I Do not set permissions on TURN relay endpoints (for testing the
126 non-standard server relay functionality).
127 -G Generate extra requests (create permissions, channel bind).
129 -B Random disconnect after a few initial packets.
131 -Z Dual allocation (SSODA). Implies -c option.
133 -J Use oAuth with default test key kid='north'.
135 Options with required values:
137 -l Message length (Default: 100 Bytes).
139 -i Certificate file (for secure connections only, optional).
141 -k Private key file (for secure connections only).
143 -E CA file for server certificate verification, if the server cer‐
145 tificate to be verified.
146 -p TURN Server port (Defaults: 3478 unsecure, 5349 secure).
148 -n Number of messages to send (Default: 5).
150 -d Local interface device (optional, Linux only).
152 -L Local IP address (optional).
154 -m Number of clients (Default: 1, 2 or 4, depending on options).
156 -e Peer address.
158 -r Peer port (Default: 3480).
160 -z Per-session packet interval in milliseconds (Default: 20).
162 -u STUN/TURN user name.
164 -w STUN/TURN user password.
166 -W TURN REST API secret. The "plain text" secret e.g. "north" that
168 is stored in the value column of the turn_secret table in the
169 database if dynamic, or the static-auth-secret value set in the
170 configuration file if using static.
171 -C This is the timestamp/username separator symbol (character) in
173 TURN REST API. The default value is :.
174 -F Cipher suite for TLS/DTLS. Default value is DEFAULT.
176 -o the ORIGIN STUN attribute value.
178 -a Bandwidth for the bandwidth request in ALLOCATE. The default
180 value is zero.
181 See the examples in the "examples/scripts" directory.
183
185 NAME
186 turnutils_peer - a simple UDP-only echo backend server.
187 SYNOPSIS
189 $ turnutils_peer [-v] [options]
190 DESCRIPTION
193 This application is used for the test purposes only, as a peer for the
194 turnutils_uclient application.
195 Options with required values:
197 -p Listening UDP port (Default: 3480).
199 -d Listening interface device (optional)
201 -L Listening address of turnutils_peer server. Multiple listening
203 addresses can be used, IPv4 and IPv6. If no listener ad‐
204 dress(es) defined, then it listens on all IPv4 and IPv6 ad‐
205 dresses.
206 -v Verbose
208
210 NAME
211 turnutils_stunclient - a basic STUN client.
212 SYNOPSIS
214 $ turnutils_stunclient [options] <STUN-Server-IP-address>
215 DESCRIPTION
218 It sends a "new" STUN RFC 5389 request (over UDP) and shows the reply
219 information.
220 Options with required values:
222 -p STUN server port (Default: 3478).
224 -L Local address to use (optional).
226 -f Force RFC 5780 processing.
228 The turnutils_stunclient program checks the results of the first re‐
230 quest, and if it finds that the STUN server supports RFC 5780 (the
231 binding response reveals that) then the turnutils_stunclient makes a
232 couple more requests with different parameters, to demonstrate the NAT
233 discovery capabilities.
234 This utility does not support the "old" "classic" STUN protocol (RFC
236 3489).
237
239 NAME
240 turnutils_rfc5769check - a utility that tests the correctness of STUN
241 protocol implementation.
242 SYNOPSIS
244 $ turnutils_rfc5769check
245 DESCRIPTION
248 turnutils_rfc5769check tests the correctness of STUN protocol implemen‐
249 tation against the test vectors predefined in RFC 5769 and prints the
250 results of the tests on the screen. This utility is used only for the
251 compilation check procedure, it is not copied to the installation des‐
252 tination.
253 Usage:
255 $ turnutils_rfc5769check
257
259 NAME
260 turnutils_natdiscovery - a utility that discovers NAT mapping and fil‐
261 tering behavior according RFC5780.
262 SYNOPSIS
264 $ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>
265 DESCRIPTION
268 turnutils_natdiscovery discovers the NAT Mapping and Filtering behav‐
269 ior, to determine if that NAT is currently using Endpoint-Independent,
270 Address-Dependent, or Address and Port-Dependent Mapping and/or to de‐
271 termine if that NAT is currently using Endpoint-Independent, Ad‐
272 dress-Dependent, or Address and Port-Dependent Filtering.
273 Use either -m, -f, -c, -H flag to discover NAT behavior.
275 Flags:
277 -m NAT mapping behavior discovery
279 -f NAT filtering behavior discovery
281 -t NAT mapping lifetime behavior discovery Requires a timer (-T)
283 -c NAT collision behavior discovery
285 -H NAT hairpinning behavior discovery
287 -P Add 1500 byte Padding to the behavior discovery Applicable with
289 all except NAT mapping Lifetime discovery
290 Options with required values:
292 -p STUN server port (Default: 3478)
294 -L Local address to use (optional)
296 -l Local port to use (use with -L)
298 -A Secondary Local address (optional) Required for collision dis‐
300 covery
301 -T Mapping lifetime timer (sec) Used by mapping lifetime behavior
303 discovery
304 Usage:
306 $ turnutils_natdiscovery -m -f stun.example.com
308
310 NAME
311 turnutils_oauth - a utility that helps OAuth access_token genera‐
312 tion/encryption and validation/decyption
313 SYNOPSIS
315 $ turnutils_oauth [options]
316 DESCRIPTION
319 turnutils_oauth utilitiy provides help in OAuth access_token encryption
320 and/or decryption with AEAD (Atuthenticated Encryption with Associated
321 Data). It helps for an Auth Server in access_token creation, and also
322 for debugging purposes it helps the access_token validation and decryp‐
323 tion. This utility inputs all the keys and lifetimes and any related
324 information that are needed for encryption or decryption of an ac‐
325 cess_token. It outputs a JSON with all OAuth PoP parameters that need
326 to pass to the client. Output is generated accoriding RFC7635 Appendix
327 B, Figure 8. This utility could help to build an Auth Server service,
328 but be awere that this utility does not generate "session key" /
329 "mac_key" and not verifies lifetime of "session key" / "mac_key" or
330 "Auth key". For more details, and for the access_token structure, read
331 rfc7635, and see the example in examples/scripts/oauth.sh.
332 Use either -e and/or -d flag to encrypt or decrypt access_token.
334 Flags:
336 -h, --help
338 usage
339 -v, --verbose
341 verbose mode
342 -e, --encrypt
344 encrypt token
345 -d, --decrypt
347 decrypt validate token
348 Options with required values:
350 -i, --server-name
352 server name (max. 255 char)
353 -j, --auth-key-id
355 Auth key id (max. 32 char)
356 -k, --auth-key
358 base64 encoded Auth key
359 -l --auth-key-timestamp Auth key timestamp (sec since epoch)
361 -m, --auth-key-lifetime
363 Auth key lifetime in sec
364 -n, --auth-key-as-rs-alg
366 Authorization Server(AS) - Resource Server(RS) encryption algo‐
367 rithm
368 -o, --token-nonce
370 base64 encoded nonce base64(12 octet) = 16 char
371 -p, --token-mac-key
373 base64 encoded MAC key base64(32 octet) = 44 char
374 -q, --token-timestamp
376 timestamp in format 64 bit unsigned (Native format - Unix), so
377 48 bit for secs since epoch UTC + 16 bit for 1/64000 fractions
378 of a second. e.g.: the actual unixtimestamp 16 bit left
379 shifted. (Default: actual gmtime)
380 -r, --token-lifetime
382 lifetime in sec (Default: 3600)
383 -t, --token
385 base64 encoded encrypted token for validation and decryption
386 -u, --hmac-alg
388 stun client hmac algorithm
389 Usage:
391 $ turnutils_natdiscovery
393
396 After installation, run the command:
397 $ man turnutils
399 or in the project root directory:
401 $ man -M man turnutils
403 to see the man page.
405
408 /etc/turnserver.conf
409 /var/db/turndb
411 /usr/local/var/db/turndb
413 /var/lib/turn/turndb
415 /usr/local/etc/turnserver.conf
417
420 /usr/local/share/turnserver
421 /usr/local/share/doc/turnserver
423 /usr/local/share/examples/turnserver
425
428 new STUN RFC 5389
429
431 TURN-TCP extension RFC 6062
432 TURN IPv6 extension RFC 6156
434 STUN/TURN test vectors RFC 5769
436 STUN NAT behavior discovery RFC 5780
438
441 turnserver, turnadmin
442
444 WEB RESOURCES
445 project page:
446 https://github.com/coturn/coturn/
448 Wiki page:
450 https://github.com/coturn/coturn/wiki
452 forum:
454 https://groups.google.com/forum/?fromgroups=#!fo‐
456 rum/turn-server-project-rfc5766-turn-server/
457
459 AUTHORS
460 Oleg Moskalenko <mom040267@gmail.com>
461 Gabor Kovesdan http://kovesdan.org/
463 Daniel Pocock http://danielpocock.com/
465 John Selbie (jselbie@gmail.com)
467 Lee Sylvester <lee@designrealm.co.uk>
469 Erik Johnston <erikj@openmarket.com>
471 Roman Lisagor <roman@demonware.net>
473 Vladimir Tsanev <tsachev@gmail.com>
475 Po-sheng Lin <personlin118@gmail.com>
477 Peter Dunkley <peter.dunkley@acision.com>
479 Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
481 Federico Pinna <fpinna@vivocha.com>
483 Bradley T. Hughes <bradleythughes@fastmail.fm>
485 Mihály Mészáros <misi@majd.eu>
487 ACTIVE MAINTAINERS
489 Mihály Mészáros <misi@majd.eu>
490 05 June 2021 TURN(1)