HolePunch-UDPTunnel

An UDP tunnel system using NAT hole-punching to provide point-to-point tunnels between two clients across networks, through the use of an intermediatry information server for punching, then creating a VPN tunnel interface and forwarding all traffic through the hole-punched UDP ports.

Project Structure

The project consists of two linked golang projects, HolePunchUDPTunnel is the main project and it calls the executable produced by UDPTunnel:

HolePunchUDPTunnel
- Server mode: runs the hole-punch info exchange server.
- Client mode: presents text user interface to select a client to connect to, performs hole-punch and launches the UDPTunnel.
UDPTunnel
- Runs a tunnel client/server with the given IP/ports, creates a vpn between clients when launched automatically by HolePunchUDPTunnel.

Directory Tree

Below is the directory tree of the project:

.
├── bin
│   └── HolePunch-UDPTunnel
├── holepunchudptunnel
│   ├── go.mod
│   ├── go.sum
│   ├── go.work
│   ├── main.go
│   ├── natholepunch
│   │   ├── clientdata.go
│   │   ├── client.go
│   │   ├── go.mod
│   │   └── server.go
│   ├── tui
│   │   ├── go.mod
│   │   ├── logging.go
│   │   └── ui.go
│   └── tunnelman
│       ├── go.mod
│       ├── tunneldata.go
│       ├── tunnelexec.go
│       ├── tunnelman.go
│       └── udptunnel
├── LICENSE
├── Makefile
├── README.md
└── udptunnel
    ├── filter.go
    ├── go.mod
    ├── go.sum
    ├── LICENSE.md
    ├── logger.go
    ├── main.go
    └── tunnel.go

7 directories, 27 files

Module Function Description

HolePunchUDPTunnel
- Main program source directory, relies on compiled executable of support program UDPTunnel
- main.go
  - Starts hole-punch server or hole-punch client plus text user interface (TUI) in client mode
- natholepunch
  - Sub-module for hole-punch server and client code
  - server.go
    - Code for running the hole-punch information exchange server
  - client.go
    - Code for running the hole-punch client and performing UDP hole-punching
  - clientdata.go
    - Defines structs that hold client data for both client and server
- tui
  - Sub-module for TUI code
  - ui.go
    - Code for displaying, rendering and updating the TUI with the information from the other sub-modules
  - logging.go
    - Code for redirecting StdOut output from other modules into a text view inside the TUI
- tunnelman
  - Sub-module for UDPTunnel manager code
  - tunnelman.go
    - Code for managing UDPTunnel configuration and creating UDPTunnel configuration based on hole-punch operation
  - tunnelexec.go
    - Code for executing the UDPTunnel program
    - The binary executable compiled from the UDPTunnel directory is embedded into our HolePunchUDPTunnel executable from this file.
  - tunneldata.go
    - Defines structs that hold UDPTunnel configuration data
UDPTunnel
- Support program source directory, embbeded into and called by HolePunchUDPTunnel
- main.go
  - Reads configuration file and launches a tunnel server/client
- tunnel.go
  - Creates a new tunnel interface (such as tun0) and listens to trafic
  - Forwards raw packets to tunnel interface (local client -> UDPTunnel -> remote client)
  - Accepts raw packets from tunnel interface (local client <- UDPTunnel <- remote client)
- filter.go
  - Security filter to only allow specified ports through the UDP tunnel
- logger.go
  - Prints log and UDP tunnel traffic statistics

Count Lines of Code

Below is the result of counting the lines of code (generated by gocloc):

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Go                              13            378            643           1789
Markdown                         3             36              0            176
Makefile                         1             11              8             34
-------------------------------------------------------------------------------
TOTAL                           17            425            651           1999
-------------------------------------------------------------------------------

Compilation

Begin by going to the project directory.
Compile the code by running make all (if compiling outside of China, change prepare-cn to prepare in Makefile line 12).
Go to the bin directory by running cd bin.
The compiled project executable binary is found as HolePunch-UDPTunnel here.

Usage

Make sure to launch the executable from the same folder as the executable (i.e. cd bin && ./HolePunch-UDPTunnel) To use this project, at least three devices are required:

Hole-punch info exchange server
- Must be run on a server with a public IP
- Run ./HolePunch-UDPTunnel --server
Hole-punch client (2 or more)
- Run on clients behind NATs
- Shows text user interface (TUI) to user
- Run ./HolePunch-UDPTunnel -a <Hole-Punch Server Public UP>
  - replace <Hole-Punch Server Public UP> to the actual public IP of the server running the hole-punch info exchange.
  - Default username is taken to be the OS username
  - Other options available through ./HolePunch-UDPTunnel --help:

Usage of bin/HolePunch-UDPTunnel:
  -a string
        Info exchange server IP address to connect to (default "127.0.0.1")
  -l string
        Specify Local side ID (default "luigipizzolito")
  -p string
        Info exchange server port to listen on or connect to (default "10001")
  -r string
        (optional) Specify remote side ID to tunnel to
  -server
        Run in info exchange server mode (run this on a publicly accesible IP)
  -t duration
        Specify reconnection timeout (default 2s)

Server TUI

After running a hole-punch server, the client info, logs and connection history can be seen:

Client TUI

After running a hole-punch client, the TUI can be seen:
Click, press enter, or press a number key to select a client to connect to.
The hole-punch operation will begin, and pings will be sent in between clients:
After sucessful hole-punch, sudo password is prompted, enter sudo password to launch the UDP tunnel:
After launching UDP tunnel, one client is assigned IP 10.0.0.1 and the other client is assigned IP 10.0.0.2
You may now access the other client with any application or protocol (including TCP) directly by using their IP.
For example, SSHing into the other client:

Luigi-Pizzolito/HolePunch-UDPTunnel