1TURN(1)                                                                TURN(1)
2
3
4

GENERAL INFORMATION

6       A set of turnutils_* programs provides some utility functionality to be
7       used for testing and for setting up the TURN server.
8
9       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
14       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
22       The  compiled binary image of this program is located in bin/ subdirec‐
23       tory.
24
25       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
29       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
34       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
38       $ cd examples
39
40       $ ./scripts/secure_relay.sh
41
42       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
48       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
56       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
64   SYNOPSIS
65       $ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>
66
67
68   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
76       Flags:
77
78       -t     Use TCP for communications between client and TURN  server  (de‐
79              fault is UDP).
80
81       -b     Use  SCTP for communications between client and TURN server (de‐
82              fault is UDP).
83
84       -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
88       -P     Passive TCP (RFC6062 with active peer). Implies -T.
89
90       -S     Secure SSL connection: SSL/TLS for TCP, DTLS for  UDP,  TLS/SCTP
91              for SCTP.
92
93       -U     Secure  unencrypted  connection  (suite eNULL): SSL/TLS for TCP,
94              DTLS for UDP.
95
96       -v     Verbose.
97
98       -s     Use "Send" method in TURN; by default, it uses TURN Channels.
99
100       -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
105       -h     Hang on indefinitely after the last sent packet.
106
107       -c     Do not create rtcp connections.
108
109       -x     Request IPv6 relay address (RFC6156).
110
111       -X     IPv4 relay address explicitly requested.
112
113       -g     Set DONT_FRAGMENT parameter in TURN requests.
114
115       -D     Do mandatory channel padding even for UDP (like pjnath).
116
117       -N     do negative tests (some limited cases only).
118
119       -R     do negative protocol tests.
120
121       -O     DOS attack mode.
122
123       -M     Use TURN ICE Mobility.
124
125       -I     Do  not set permissions on TURN relay endpoints (for testing the
126              non-standard server relay functionality).
127
128       -G     Generate extra requests (create permissions, channel bind).
129
130       -B     Random disconnect after a few initial packets.
131
132       -Z     Dual allocation (SSODA). Implies -c option.
133
134       -J     Use oAuth with default test key kid='north'.
135
136       Options with required values:
137
138       -l     Message length (Default: 100 Bytes).
139
140       -i     Certificate file (for secure connections only, optional).
141
142       -k     Private key file (for secure connections only).
143
144       -E     CA file for server certificate verification, if the server  cer‐
145              tificate to be verified.
146
147       -p     TURN Server port (Defaults: 3478 unsecure, 5349 secure).
148
149       -n     Number of messages to send (Default: 5).
150
151       -d     Local interface device (optional, Linux only).
152
153       -L     Local IP address (optional).
154
155       -m     Number of clients (Default: 1, 2 or 4, depending on options).
156
157       -e     Peer address.
158
159       -r     Peer port (Default: 3480).
160
161       -z     Per-session packet interval in milliseconds (Default: 20).
162
163       -u     STUN/TURN user name.
164
165       -w     STUN/TURN user password.
166
167       -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
172       -C     This is the timestamp/username separator symbol  (character)  in
173              TURN REST API. The default value is :.
174
175       -F     Cipher suite for TLS/DTLS. Default value is DEFAULT.
176
177       -o     the ORIGIN STUN attribute value.
178
179       -a     Bandwidth  for  the  bandwidth  request in ALLOCATE. The default
180              value is zero.
181
182       See the examples in the "examples/scripts" directory.
183

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

185   NAME
186        turnutils_peer - a simple UDP-only echo backend server.
187
188   SYNOPSIS
189       $ turnutils_peer [-v] [options]
190
191
192   DESCRIPTION
193       This application is used for the test purposes only, as a peer for  the
194       turnutils_uclient application.
195
196       Options with required values:
197
198       -p     Listening UDP port (Default: 3480).
199
200       -d     Listening interface device (optional)
201
202       -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
207       -v     Verbose
208

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

210   NAME
211        turnutils_stunclient - a basic STUN client.
212
213   SYNOPSIS
214       $ turnutils_stunclient [options] <STUN-Server-IP-address>
215
216
217   DESCRIPTION
218       It sends a "new" STUN RFC 5389 request (over UDP) and shows  the  reply
219       information.
220
221       Options with required values:
222
223       -p     STUN server port (Default: 3478).
224
225       -L     Local address to use (optional).
226
227       -f     Force RFC 5780 processing.
228
229       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
235       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
243   SYNOPSIS
244       $ turnutils_rfc5769check
245
246
247   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
254       Usage:
255
256       $ turnutils_rfc5769check
257

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

259   NAME
260        turnutils_natdiscovery - a utility that discovers NAT mapping and fil‐
261       tering behavior according RFC5780.
262
263   SYNOPSIS
264       $ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>
265
266
267   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
274       Use either -m, -f, -c, -H flag to discover NAT behavior.
275
276       Flags:
277
278       -m     NAT mapping behavior discovery
279
280       -f     NAT filtering behavior discovery
281
282       -t     NAT mapping lifetime behavior discovery Requires a timer (-T)
283
284       -c     NAT collision behavior discovery
285
286       -H     NAT hairpinning behavior discovery
287
288       -P     Add 1500 byte Padding to the behavior discovery Applicable  with
289              all except NAT mapping Lifetime discovery
290
291       Options with required values:
292
293       -p     STUN server port (Default: 3478)
294
295       -L     Local address to use (optional)
296
297       -l     Local port to use (use with -L)
298
299       -A     Secondary  Local  address (optional) Required for collision dis‐
300              covery
301
302       -T     Mapping lifetime timer (sec) Used by mapping  lifetime  behavior
303              discovery
304
305       Usage:
306
307       $ 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
314   SYNOPSIS
315       $ turnutils_oauth [options]
316
317
318   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
333       Use either -e and/or -d flag to encrypt or decrypt access_token.
334
335       Flags:
336
337       -h, --help
338              usage
339
340       -v, --verbose
341              verbose mode
342
343       -e, --encrypt
344              encrypt token
345
346       -d, --decrypt
347              decrypt validate token
348
349       Options with required values:
350
351       -i, --server-name
352              server name (max. 255 char)
353
354       -j, --auth-key-id
355              Auth key id (max. 32 char)
356
357       -k, --auth-key
358              base64 encoded Auth key
359
360       -l     --auth-key-timestamp       Auth key timestamp (sec since epoch)
361
362       -m, --auth-key-lifetime
363              Auth key lifetime in sec
364
365       -n, --auth-key-as-rs-alg
366              Authorization Server(AS) - Resource Server(RS) encryption  algo‐
367              rithm
368
369       -o, --token-nonce
370              base64 encoded nonce base64(12 octet) = 16 char
371
372       -p, --token-mac-key
373              base64 encoded MAC key base64(32 octet) = 44 char
374
375       -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
381       -r, --token-lifetime
382              lifetime in sec (Default: 3600)
383
384       -t, --token
385              base64 encoded encrypted token for validation and decryption
386
387       -u, --hmac-alg
388              stun client hmac algorithm
389
390       Usage:
391
392       $ turnutils_natdiscovery
393

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

DOCS

396       After installation, run the command:
397
398       $ man turnutils
399
400       or in the project root directory:
401
402       $ man -M man turnutils
403
404       to see the man page.
405

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

FILES

408       /etc/turnserver.conf
409
410       /var/db/turndb
411
412       /usr/local/var/db/turndb
413
414       /var/lib/turn/turndb
415
416       /usr/local/etc/turnserver.conf
417

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

DIRECTORIES

420       /usr/local/share/turnserver
421
422       /usr/local/share/doc/turnserver
423
424       /usr/local/share/examples/turnserver
425

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

STANDARDS

428       new STUN RFC 5389
429

TURN RFC 5766

431       TURN-TCP extension RFC 6062
432
433       TURN IPv6 extension RFC 6156
434
435       STUN/TURN test vectors RFC 5769
436
437       STUN NAT behavior discovery RFC 5780
438

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

SEE ALSO

441       turnserver, turnadmin
442

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

444   WEB RESOURCES
445       project page:
446
447       https://github.com/coturn/coturn/
448
449       Wiki page:
450
451       https://github.com/coturn/coturn/wiki
452
453       forum:
454
455       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
462       Gabor Kovesdan http://kovesdan.org/
463
464       Daniel Pocock http://danielpocock.com/
465
466       John Selbie (jselbie@gmail.com)
467
468       Lee Sylvester <lee@designrealm.co.uk>
469
470       Erik Johnston <erikj@openmarket.com>
471
472       Roman Lisagor <roman@demonware.net>
473
474       Vladimir Tsanev <tsachev@gmail.com>
475
476       Po-sheng Lin <personlin118@gmail.com>
477
478       Peter Dunkley <peter.dunkley@acision.com>
479
480       Mutsutoshi Yoshimoto <mutsutoshi.yoshimoto@mixi.co.jp>
481
482       Federico Pinna <fpinna@vivocha.com>
483
484       Bradley T. Hughes <bradleythughes@fastmail.fm>
485
486       Mihály Mészáros <misi@majd.eu>
487
488   ACTIVE MAINTAINERS
489       Mihály Mészáros <misi@majd.eu>
490
491
492
493                                 05 June 2021                          TURN(1)
Impressum