UDPoTCP

What does it do?

UDPoTCP (User Datagram Protocol over Transmission Control Protocol) is pair of two programs: an UDP-to-TCP-Server and a TCP-to-UDP-Client. The server takes UDP packages that arrive at a certain port and address (socket) and sends them to a client that is connected to it via TCP. The client simply takes the packages received via TCP and pours them out on (another) UDP socket.

So what is that good for?

Well let me explain why I initially wrote that piece of software. I like VLC a lot and I do own a TV-card. At home, in my LAN, I can watch TV on every computer, because I can use VLC to stream the data from the TV-card. The most comfortable way to do it is using VLC UDP streaming, as you can see on this screenshot:

When I use this setup my VLC would transmit UDP packets into my LAN (using the socket 192.168.0.255:1234) and I can set up many clients to listen to their :1234 ports. UDP packets would stay in my LAN, since my firewall is not set up to let any of there packets out and my provider would also block them, which is very understandable. (Many UDP packets would completely pollute the internet.)

So far so good. But what if I am not at home? As said my provider will not allow UDP packets to travel across the internet. What if I wanted to receive my UDP stream at the bluedynamics office, for example? One solution would be to set up a VPN (Virtual Private Network). The most prominent candidate for a VPN solution seemed to be openVPN. But soon I understood that the configuration is a bit more tricky than I had expected. What about a lightweight solution? Why not write python software? I did.

UDPoTCP (User Datagram Protocol over Transmission Control Protocol)

How is it used?

Let me continue with my video/audio stream example. As mentioned I have VLC transmitting UDP packets into my source LAN (192.168.0.255:1234). I will now explain how to use UDPoTCP to receive those packets on another system that is not in the same subnet and how to pour those packets into the second (target) LAN.

First I start the server on my firewall box since the open ports of that machine are visible on the internet, I also run a web server there.

python udp2tcp_server.py -i 0.0.0.0:1234 -o 0.0.0.0:4321 -v 1

This command starts the (source) server and it would catch any packets on port 1234 and listen to incoming connections on port 4321. On the target system I will start the client:

python tcp2udp_client.py -i gogo.bluedynamics.com:4321 -o 255.255.255.255:1234 -v 1

As soon as the connection is established the client will send all received data out into the LAN (255.255.255.255:1234), enabling me and my coworkers to receive them. I can start VLC in the target LAN and open an UDP stream on port 1234, that is the default setting for the menu entry File/Open Network... I have another screenshot for you:

Now the packets are in both the source and the target LAN.

What else?

You can also establish a secure stream. Just make use of ssh, it provides a commonly used secure tunnel:

ssh -L 4321:127.0.0.1:4321 gogo@gogo.bluedynamics.com

With this options ssh creates a secure tunnel to my streaming server. Now I can start the streaming udp2tcp_server.py software on the source system and let it use an internal socket. I already logged in at the source system with the above ssh command and now I just start the UDPoTCP server there:

python udp2tcp_server.py -i 0.0.0.0:1234 -o 127.0.0.1:4321 -v 0

Now the server just listens on its internal 4321 port for incoming connections, shielded from the internet. Now you can use tcp2udp_client.py on the target system and it will receive the packets from the (secure) ssh tunnel:

python tcp2udp_client.py -i 127.0.0.1:4321 -o 127.0.0.1:1234 -v 0

This will send the UDP packets to your local machine only. They will not be visible in the target LAN, only on your box.

Can you use it, too?

Yes you can! Feel free to download UDPoTCP here. Simply unpack the archive on your box, it contains the server and client software. Contact me if the example above could not help you to make it run.

Future features

I probably will add an option for udp2tcp_server.py that allows you to specify the adresses of clients that are allowed to connect. Since only one client can connect at a time this will be necessary as soon as there are concurrent connections. I will do that if it will become necessary, and might want to use a .allow file to keep administration simple.

Have fun and give me feedback!
Gogo.