Add hairpinning natdiscovery to README and man

README.turnutils

@@ -1,40 +1,40 @@
 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. 
+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/ 
+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 
+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 
+(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. 
+
+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 
+
+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 
+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. Be aweare that at least two different listening IP addresses should 
+5.	turnutils_natdiscovery: a utility that provides NAT behavior discovery
+according RFC5780. This utility discovers the actual NAT Mapping and Filtering
+behavior. Be aweare that at least two different listening IP addresses should
 be configured to be able to work properly!
 
 6.	turnutils_oauth: a utility that provides OAuth access_token 
@@ -49,34 +49,34 @@ script in examples/scripts/oauth.sh.
 
 
 =====================================
-    
+
   NAME
-  
+
 turnutils_uclient - this client emulation application is supplied for the test purposes only.
- 
-  SYNOPSIS  
+
+  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. 
+
+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:   
+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, 
+-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.
@@ -87,11 +87,11 @@ Flags:
 
 -s      Use "Send" method in TURN; by default, it uses TURN Channels.
 
--y      Use client-to-client connections: 
+-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.
@@ -109,12 +109,12 @@ Flags:
 -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.
@@ -123,7 +123,7 @@ Flags:
 
 -J	Use oAuth with default test key kid='north'.
 
-Options with required values:  
+Options with required values:
 
 -l      Message length (Default: 100 Bytes).
 
@@ -159,7 +159,7 @@ Options with required values:
 	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 
+-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.
@@ -171,23 +171,23 @@ Options with required values:
 See the examples in the "examples/scripts" directory.
 
 ======================================
-  
+
   NAME
-    
-turnutils_peer - a simple UDP-only echo backend server.  
-  
+
+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:  
+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.
@@ -198,50 +198,50 @@ If no listener address(es) defined, then it listens on all IPv4 and IPv6 address
 ========================================
 
   NAME
-  
-turnutils_stunclient -  a basic STUN client. 
-  
+
+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:  
+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 
+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.   
-  
+
+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 
+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:  
+
+Usage:
 
 $ turnutils_rfc5769check
 
@@ -249,7 +249,7 @@ $ turnutils_rfc5769check
 
   NAME
 
-turnutils_natdiscovery - a utility that discovers NAT mapping and filtering 
+turnutils_natdiscovery - a utility that discovers NAT mapping and filtering
 behavior according RFC5780.
 
   SYNOPSIS
@@ -258,13 +258,13 @@ $ 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. 
+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 flag to discover NAT behavior.
+Use either -m, -f, -c, -H flag to discover NAT behavior.
 
 Flags:
 
@@ -274,6 +274,8 @@ Flags:
 
 -c  NAT collision behavior discovery
 
+-H  NAT hairpinning behavior discovery
+
 Options with required values:
 
 -p  STUN server port (Default: 3478)
@@ -356,7 +358,7 @@ Usage:
 $ turnutils_natdiscovery
 
 ===================================
- 
+
 DOCS
 
 After installation, run the command:
@@ -402,7 +404,7 @@ new STUN RFC 5389
 TURN RFC 5766
 
 TURN-TCP extension RFC 6062
- 
+
 TURN IPv6 extension RFC 6156
 
 STUN/TURN test vectors RFC 5769
@@ -448,15 +450,15 @@ SEE ALSO
 	Erik Johnston <[email protected]>
 
 	Roman Lisagor <[email protected]>
-	
+
 	Vladimir Tsanev <[email protected]>
-	
+
 	Po-sheng Lin <[email protected]>
-	
+
 	Peter Dunkley <[email protected]>
-	
+
 	Mutsutoshi Yoshimoto <[email protected]>
-	
+
 	Federico Pinna <[email protected]>
 
 	Bradley T. Hughes <[email protected]>

man/man1/turnutils.1

@@ -3,39 +3,39 @@
 .SH GENERAL INFORMATION
 
 A set of turnutils_* programs provides some utility functionality to be used
-for testing and for setting up the TURN server. 
+for testing and for setting up the TURN server.
 .TP
 .B
 1.
-\fIturnutils_uclient\fP: emulates multiple UDP,TCP,TLS or DTLS clients. 
+\fIturnutils_uclient\fP: 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/ 
+The compiled binary image of this program is located in bin/
 sub\-directory.
 .TP
 .B
 2.
-\fIturnutils_peer\fP: a simple stateless UDP\-only "echo" server, 
-to be used as the final server in relay pattern ("peer"). For every incoming 
+\fIturnutils_peer\fP: 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 "\fIturnutils_uclient\fP" program is used with "\fB\-y\fP" option) then the 
+(this program is provided for the testing purposes only !)
+When the test clients are communicating in the client\-to\-client manner
+(when the "\fIturnutils_uclient\fP" program is used with "\fB\-y\fP" option) then the
 \fIturnutils_peer\fP is not needed.
 .PP
 The compiled binary image of this program is located in bin/ subdirectory.
 .TP
 .B
 3.
-\fIturnutils_stunclient\fP: a simple STUN client example. 
+\fIturnutils_stunclient\fP: a simple STUN client example.
 The compiled binary image of this program is located in bin/ subdirectory.
 .TP
 .B
 4.
-\fIturnutils_rfc5769check\fP: a utility that checks the correctness of the 
+\fIturnutils_rfc5769check\fP: 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.
 .PP
-In the "examples/scripts" subdirectory, you will find the examples of command lines to be used 
+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:
 .PP
 $ cd examples
@@ -44,9 +44,9 @@ $ ./scripts/secure_relay.sh
 .TP
 .B
 5.
-\fIturnutils_natdiscovery\fP: a utility that provides NAT behavior discovery 
-according RFC5780. This utility discovers the actual NAT Mapping and Filtering 
-behavior. Be aweare that at least two different listening IP addresses should 
+\fIturnutils_natdiscovery\fP: a utility that provides NAT behavior discovery
+according RFC5780. This utility discovers the actual NAT Mapping and Filtering
+behavior. Be aweare that at least two different listening IP addresses should
 be configured to be able to work properly!
 .TP
 .B
@@ -69,19 +69,25 @@ script in examples/scripts/oauth.sh.
 \fB
 \fBturnutils_uclient \fP\- this client emulation application is supplied for the test purposes only.
 \fB
-.SS  SYNOPSIS  
+.SS  SYNOPSIS
+.nf
+.fam C
 
-$ \fIturnutils_uclient\fP [\fB\-tTSvsyhcxg\fP] [options] <TURN\-Server\-IP\-address>
+$ \fIturnutils_uclient\fP [\fB\-tTSvsyhcxg\fP] [\fIoptions\fP] <TURN\-Server\-IP\-address>
+
+.fam T
+.fi
+.fam T
+.fi
 .SS  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. 
+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.
-.TP
-.B
+.PP
 Flags:
 .TP
 .B
@@ -94,8 +100,8 @@ Use SCTP for communications between client and TURN server (default is UDP).
 .TP
 .B
 \fB\-T\fP
-Use TCP for the relay transport (default \- UDP). Implies options \fB\-t\fP, \fB\-y\fP, \fB\-c\fP, 
-and ignores flags and options \fB\-s\fP, \fB\-e\fP, \fB\-r\fP and \fB\-g\fP. Can be used together
+Use TCP for the relay transport (default \- UDP). Implies \fIoptions\fP \fB\-t\fP, \fB\-y\fP, \fB\-c\fP,
+and ignores flags and \fIoptions\fP \fB\-s\fP, \fB\-e\fP, \fB\-r\fP and \fB\-g\fP. Can be used together
 with \fB\-b\fP.
 .TP
 .B
@@ -120,7 +126,7 @@ Use "Send" method in TURN; by default, it uses TURN Channels.
 .TP
 .B
 \fB\-y\fP
-Use client\-to\-client connections: 
+Use client\-to\-client connections:
 RTP/RTCP pair of channels to another RTP/RTCP pair of channels.
 with this option the \fIturnutils_peer\fP application is not used,
 as the allocated relay endpoints are talking to each other.
@@ -185,8 +191,7 @@ Dual allocation (SSODA). Implies \fB\-c\fP option.
 .B
 \fB\-J\fP
 Use oAuth with default test key kid='north'.
-.TP
-.B
+.PP
 Options with required values:
 .TP
 .B
@@ -224,7 +229,7 @@ Local IP address (optional).
 .TP
 .B
 \fB\-m\fP
-Number of clients (Default: 1, 2 or 4, depending on options).
+Number of clients (Default: 1, 2 or 4, depending on \fIoptions\fP).
 .TP
 .B
 \fB\-e\fP
@@ -255,7 +260,7 @@ value set in the configuration file if using static.
 .TP
 .B
 \fB\-C\fP
-This is the timestamp/username separator symbol (character) in 
+This is the timestamp/username separator symbol (character) in
 TURN REST API. The default value is :.
 .TP
 .B
@@ -290,8 +295,7 @@ $ \fIturnutils_peer\fP [\fB\-v\fP] [\fIoptions\fP]
 .SS  DESCRIPTION
 
 This application is used for the test purposes only, as a peer for the \fIturnutils_uclient\fP application.
-.TP
-.B
+.PP
 Options with required values:
 .TP
 .B
@@ -329,8 +333,7 @@ $ \fIturnutils_stunclient\fP [\fIoptions\fP] <STUN\-Server\-IP\-address>
 .SS  DESCRIPTION
 
 It sends a "new" STUN RFC 5389 request (over UDP) and shows the reply information.
-.TP
-.B
+.PP
 Options with required values:
 .TP
 .B
@@ -345,9 +348,9 @@ Local address to use (optional).
 \fB\-f\fP
 Force RFC 5780 processing.
 .PP
-The \fIturnutils_stunclient\fP 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 \fIturnutils_stunclient\fP makes a couple more 
+The \fIturnutils_stunclient\fP 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 \fIturnutils_stunclient\fP makes a couple more
 requests with different parameters, to demonstrate the NAT discovery capabilities.
 .PP
 This utility does not support the "old" "classic" STUN protocol (RFC 3489).
@@ -369,12 +372,11 @@ $ \fIturnutils_rfc5769check\fP
 .fi
 .SS  DESCRIPTION
 
-\fIturnutils_rfc5769check\fP tests the correctness of STUN protocol implementation 
-against the test vectors predefined in RFC 5769 and prints the results of the 
+\fIturnutils_rfc5769check\fP 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.
-.TP
-.B
+.PP
 Usage:
 .PP
 $ \fIturnutils_rfc5769check\fP
@@ -397,13 +399,13 @@ $ \fIturnutils_natdiscovery\fP [\fIoptions\fP] <STUN\-Server\-FQDN\-or\-IP\-addr
 .fi
 .SS  DESCRIPTION
 
-\fIturnutils_natdiscovery\fP 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. 
+\fIturnutils_natdiscovery\fP 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.
 .PP
-Use either \fB\-m\fP, \fB\-f\fP, \fB\-c\fP flag to discover NAT behavior.
+Use either \fB\-m\fP, \fB\-f\fP, \fB\-c\fP, \fB\-H\fP flag to discover NAT behavior.
 .PP
 Flags:
 .TP
@@ -418,6 +420,10 @@ NAT filtering behavior discovery
 .B
 \fB\-c\fP
 NAT collision behavior discovery
+.TP
+.B
+\fB\-H\fP
+NAT hairpinning behavior discovery
 .PP
 Options with required values:
 .TP