From 9395096ae98ac37026697759812f305fe54e8d8c Mon Sep 17 00:00:00 2001 From: AfonsoVi Date: Mon, 22 Apr 2024 22:51:29 +0100 Subject: [PATCH] Add tcp-alloc example documentation --- examples/README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/examples/README.md b/examples/README.md index 5499a772..2e7af3ff 100644 --- a/examples/README.md +++ b/examples/README.md @@ -65,7 +65,9 @@ This mechanism is described in https://datatracker.ietf.org/doc/html/draft-ubert This example demonstrates the use of a permission handler in the PION TURN server. The example implements a filtering policy that lets clients to connect back to their own host or server-reflexive address but will drop everything else. This will let the client ping-test through but will block essentially all other peer connection attempts. ## turn-client -The `turn-client` directory contains 2 examples that show common Pion TURN usages. All of these examples take the following arguments. +The `turn-client` directory contains 3 examples that show common Pion TURN usages. + +All of these examples except `tcp-alloc` take the following arguments. * -host : TURN server host * -ping : Run ping test @@ -126,3 +128,41 @@ Following diagram shows what turn-client does: > mappedAddr and the external IP:port (*3) are the same) This process is known as > "UDP hole punching" and TURN server exhibits "Address-restricted" behavior. Once it is done, > packets coming from (*3) will be received by relayConn. + + +#### tcp-alloc +The `tcp-alloc` exemplifies how to create client TCP allocations and use them to exchange messages between peers. It simulates two clients and creates a TCP allocation for each. Then, both clients exchange their relayed addresses with each other through a signaling server. Finally, each client uses its TCP allocation and the relayed address of the other client to send and receive a single message. + +The `tcp-alloc` takes the following arguments: + +* -host : TURN server host +* -port : Listening port (defaults to 3478) +* -user : <username>=<password> pair +* -realm : Realm name (defaults to "pion.ly") +* -signaling : Run the signaling server + + +To run the example: + +1) Start one client and the signaling server used to exchange the relayed addresses: + +```sh +go build +./tcp-alloc -host -port -user= -signaling=true +``` + +2) Start the other client without starting the signaling server: + +```sh +./tcp-alloc -host -port -user= -signaling=false +``` + +A Coturn TURN server can be locally deployed and used for testing with the following command (this is a test configuration of the Coturn TURN server and should not be used for production): + +```sh +/bin/turnserver -lt-cred-mech -u -r pion.ly --allow-loopback-peers --cli-password= +``` + +>If using this Coturn TURN server deployment: +>* turn-server-name : 127.0.0.1 +>* port : 3478 \ No newline at end of file