turnutils_uclient(1)

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
32              installation 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
52              access_token.  It  outputs  a JSON with all OAuth PoP parameters
53              that need to pass to the client. Output is generated  accoriding
54              RFC7635 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
59       =====================================
60
61   NAME
62        turnutils_uclient - this client emulation application is supplied  for
63       the test purposes only.
64
65   SYNOPSIS
66       $ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>
67
68
69   DESCRIPTION
70       It  was designed to simulate multiple clients. It uses asynch IO API in
71       libevent to handle multiple clients. A client connects  to  the  relay,
72       negotiates the session, and sends multiple (configured number) messages
73       to the server (relay), expecting the same number of replies. The length
74       of  the  messages  is  configurable.  The message is an arbitrary octet
75       stream.  The number of the messages to send is configurable.
76
77       Flags:
78
79       -t     Use TCP  for  communications  between  client  and  TURN  server
80              (default is UDP).
81
82       -b     Use  SCTP  for  communications  between  client  and TURN server
83              (default is UDP).
84
85       -T     Use TCP for the relay transport (default - UDP). Implies options
86              -t, -y, -c, and ignores flags and options -s, -e, -r and -g. Can
87              be used together with -b.
88
89       -P     Passive TCP (RFC6062 with active peer). Implies -T.
90
91       -S     Secure SSL connection: SSL/TLS for TCP, DTLS for  UDP,  TLS/SCTP
92              for SCTP.
93
94       -U     Secure  unencrypted  connection  (suite eNULL): SSL/TLS for TCP,
95              DTLS for UDP.
96
97       -v     Verbose.
98
99       -s     Use "Send" method in TURN; by default, it uses TURN Channels.
100
101       -y     Use client-to-client connections: RTP/RTCP pair of  channels  to
102              another  RTP/RTCP pair of channels.  with this option the turnu‐
103              tils_peer application is not used, as the allocated  relay  end‐
104              points are talking to each other.
105
106       -h     Hang on indefinitely after the last sent packet.
107
108       -c     Do not create rtcp connections.
109
110       -x     Request IPv6 relay address (RFC6156).
111
112       -X     IPv4 relay address explicitly requested.
113
114       -g     Set DONT_FRAGMENT parameter in TURN requests.
115
116       -D     Do mandatory channel padding even for UDP (like pjnath).
117
118       -N     do negative tests (some limited cases only).
119
120       -R     do negative protocol tests.
121
122       -O     DOS attack mode.
123
124       -M     Use TURN ICE Mobility.
125
126       -I     Do  not set permissions on TURN relay endpoints (for testing the
127              non-standard server relay functionality).
128
129       -G     Generate extra requests (create permissions, channel bind).
130
131       -B     Random disconnect after a few initial packets.
132
133       -Z     Dual allocation (SSODA). Implies -c option.
134
135       -J     Use oAuth with default test key kid='north'.
136
137       Options with required values:
138
139       -l     Message length (Default: 100 Bytes).
140
141       -i     Certificate file (for secure connections only, optional).
142
143       -k     Private key file (for secure connections only).
144
145       -E     CA file for server certificate verification, if the server  cer‐
146              tificate to be verified.
147
148       -p     TURN Server port (Defaults: 3478 unsecure, 5349 secure).
149
150       -n     Number of messages to send (Default: 5).
151
152       -d     Local interface device (optional, Linux only).
153
154       -L     Local IP address (optional).
155
156       -m     Number of clients (Default: 1, 2 or 4, depending on options).
157
158       -e     Peer address.
159
160       -r     Peer port (Default: 3480).
161
162       -z     Per-session packet interval in milliseconds (Default: 20).
163
164       -u     STUN/TURN user name.
165
166       -w     STUN/TURN user password.
167
168       -W     TURN  REST API secret. The "plain text" secret e.g. "north" that
169              is stored in the value column of the turn_secret  table  in  the
170              database  if dynamic, or the static-auth-secret value set in the
171              configuration file if using static.
172
173       -C     This is the timestamp/username separator symbol  (character)  in
174              TURN REST API. The default value is :.
175
176       -F     Cipher suite for TLS/DTLS. Default value is DEFAULT.
177
178       -o     the ORIGIN STUN attribute value.
179
180       -a     Bandwidth  for  the  bandwidth  request in ALLOCATE. The default
181              value is zero.
182
183       See the examples in the "examples/scripts" directory.
184
185       ======================================
186
187   NAME
188        turnutils_peer - a simple UDP-only echo backend server.
189
190   SYNOPSIS
191       $ turnutils_peer [-v] [options]
192
193
194   DESCRIPTION
195       This application is used for the test purposes only, as a peer for  the
196       turnutils_uclient application.
197
198       Options with required values:
199
200       -p     Listening UDP port (Default: 3480).
201
202       -d     Listening interface device (optional)
203
204       -L     Listening  address  of turnutils_peer server. Multiple listening
205              addresses  can  be  used,  IPv4  and  IPv6.   If   no   listener
206              address(es)  defined,  then  it  listens  on  all  IPv4 and IPv6
207              addresses.
208
209       -v     Verbose
210
211       ========================================
212
213   NAME
214        turnutils_stunclient - a basic STUN client.
215
216   SYNOPSIS
217       $ turnutils_stunclient [options] <STUN-Server-IP-address>
218
219
220   DESCRIPTION
221       It sends a "new" STUN RFC 5389 request (over UDP) and shows  the  reply
222       information.
223
224       Options with required values:
225
226       -p     STUN server port (Default: 3478).
227
228       -L     Local address to use (optional).
229
230       -f     Force RFC 5780 processing.
231
232       The  turnutils_stunclient  program  checks  the  results  of  the first
233       request, and if it finds that the STUN server supports  RFC  5780  (the
234       binding  response  reveals  that) then the turnutils_stunclient makes a
235       couple more requests with different parameters, to demonstrate the  NAT
236       discovery capabilities.
237
238       This  utility  does  not support the "old" "classic" STUN protocol (RFC
239       3489).
240
241       =====================================
242
243   NAME
244        turnutils_rfc5769check - a utility that tests the correctness of  STUN
245       protocol implementation.
246
247   SYNOPSIS
248       $ turnutils_rfc5769check
249
250
251   DESCRIPTION
252       turnutils_rfc5769check tests the correctness of STUN protocol implemen‐
253       tation against the test vectors predefined in RFC 5769 and  prints  the
254       results  of  the tests on the screen. This utility is used only for the
255       compilation check procedure, it is not copied to the installation  des‐
256       tination.
257
258       Usage:
259
260       $ turnutils_rfc5769check
261
262       =====================================
263
264   NAME
265        turnutils_natdiscovery - a utility that discovers NAT mapping and fil‐
266       tering behavior according RFC5780.
267
268   SYNOPSIS
269       $ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>
270
271
272   DESCRIPTION
273       turnutils_natdiscovery discovers the NAT Mapping and  Filtering  behav‐
274       ior,  to determine if that NAT is currently using Endpoint-Independent,
275       Address-Dependent, or Address  and  Port-Dependent  Mapping  and/or  to
276       determine   if   that  NAT  is  currently  using  Endpoint-Independent,
277       Address-Dependent, or Address and Port-Dependent Filtering.
278
279       Use either -m, -f, -c, -H flag to discover NAT behavior.
280
281       Flags:
282
283       -m     NAT mapping behavior discovery
284
285       -f     NAT filtering behavior discovery
286
287       -t     NAT mapping lifetime behavior discovery Requires a timer (-T)
288
289       -c     NAT collision behavior discovery
290
291       -H     NAT hairpinning behavior discovery
292
293       -P     Add 1500 byte Padding to the behavior discovery Applicable  with
294              all except NAT mapping Lifetime discovery
295
296       Options with required values:
297
298       -p     STUN server port (Default: 3478)
299
300       -L     Local address to use (optional)
301
302       -l     Local port to use (use with -L)
303
304       -A     Secondary  Local  address (optional) Required for collision dis‐
305              covery
306
307       -T     Mapping lifetime timer (sec) Used by mapping  lifetime  behavior
308              discovery
309
310       Usage:
311
312       $ turnutils_natdiscovery -m -f stun.example.com
313
314       =====================================
315
316   NAME
317         turnutils_oauth  -  a  utility  that helps OAuth access_token genera‐
318       tion/encryption and validation/decyption
319
320   SYNOPSIS
321       $ turnutils_oauth [options]
322
323
324   DESCRIPTION
325       turnutils_oauth utilitiy provides help in OAuth access_token encryption
326       and/or  decryption with AEAD (Atuthenticated Encryption with Associated
327       Data). It helps for an Auth Server in access_token creation,  and  also
328       for debugging purposes it helps the access_token validation and decryp‐
329       tion. This utility inputs all the keys and lifetimes  and  any  related
330       information  that  are  needed  for  encryption  or  decryption  of  an
331       access_token. It outputs a JSON with all OAuth PoP parameters that need
332       to  pass to the client. Output is generated accoriding RFC7635 Appendix
333       B, Figure 8. This utility could help to build an Auth  Server  service,
334       but  be  awere  that  this  utility  does  not generate "session key" /
335       "mac_key" and not verifies lifetime of "session  key"  /  "mac_key"  or
336       "Auth key".  For more details, and for the access_token structure, read
337       rfc7635, and see the example in examples/scripts/oauth.sh.
338
339       Use either -e and/or -d flag to encrypt or decrypt access_token.
340
341       Flags:
342
343       -h, --help
344              usage
345
346       -v, --verbose
347              verbose mode
348
349       -e, --encrypt
350              encrypt token
351
352       -d, --decrypt
353              decrypt validate token
354
355       Options with required values:
356
357       -i, --server-name
358              server name (max. 255 char)
359
360       -j, --auth-key-id
361              Auth key id (max. 32 char)
362
363       -k, --auth-key
364              base64 encoded Auth key
365
366       -l     --auth-key-timestamp       Auth key timestamp (sec since epoch)
367
368       -m, --auth-key-lifetime
369              Auth key lifetime in sec
370
371       -n, --auth-key-as-rs-alg
372              Authorization Server(AS) - Resource Server(RS) encryption  algo‐
373              rithm
374
375       -o, --token-nonce
376              base64 encoded nonce base64(12 octet) = 16 char
377
378       -p, --token-mac-key
379              base64 encoded MAC key base64(32 octet) = 44 char
380
381       -q, --token-timestamp
382              timestamp  in  format 64 bit unsigned (Native format - Unix), so
383              48 bit for secs since epoch UTC + 16 bit for  1/64000  fractions
384              of  a  second.   e.g.:  the  actual  unixtimestamp  16  bit left
385              shifted. (Default: actual gmtime)
386
387       -r, --token-lifetime
388              lifetime in sec (Default: 3600)
389
390       -t, --token
391              base64 encoded encrypted token for validation and decryption
392
393       -u, --hmac-alg
394              stun client hmac algorithm
395
396       Usage:
397
398       $ turnutils_natdiscovery
399
400       ===================================
401

DOCS

403       After installation, run the command:
404
405       $ man turnutils
406
407       or in the project root directory:
408
409       $ man -M man turnutils
410
411       to see the man page.
412
413       =====================================
414

FILES

416       /etc/turnserver.conf
417
418       /var/db/turndb
419
420       /usr/local/var/db/turndb
421
422       /var/lib/turn/turndb
423
424       /usr/local/etc/turnserver.conf
425
426       =================================
427

DIRECTORIES

429       /usr/local/share/turnserver
430
431       /usr/local/share/doc/turnserver
432
433       /usr/local/share/examples/turnserver
434
435       ===================================
436

STANDARDS

438       new STUN RFC 5389
439
440       TURN RFC 5766
441
442       TURN-TCP extension RFC 6062
443
444       TURN IPv6 extension RFC 6156
445
446       STUN/TURN test vectors RFC 5769
447
448       STUN NAT behavior discovery RFC 5780
449
450       ====================================
451

GENERAL INFORMATION

DOCS

FILES

DIRECTORIES

STANDARDS

SEE ALSO