tun2socks

README

go-tun2socks

A tun2socks implementation written in Go.

Tested and worked on macOS, Linux, Windows and iOS (as a library).

Overview

                                      lwip.Setup()
                                           +
                                           |
                                           |
                                           |
                                           |                TCP/UDP             lwip.RegisterTCPConnectionHandler()
                                           |
                          lwip.Input()     |           tun2socks.Connection     lwip.RegisterUDPConnectionHandler()
                                           v
Application +------> TUN +-----------> lwIP stack +------------------------------> tun2socks.ConnectionHandler +-------> SOCKS5 server +--> Destination


                         <-----------+
                    lwip.RegisterOutputFn()

Features

• Support both TCP and UDP (only IPv4 for now)
• Supported proxy protocols: SOCKS5, Shadowsocks
• UDP direct relaying (no proxy)
• ICMP local echoing

Build

go-tun2socks is using cgo, thus a C compiler is required.

go get github.com/eycorsican/go-tun2socks
cd $GOPATH/src/github.com/eycorsican/go-tun2socks
go get -d ./...
make clean && make build
./build/tun2socks -h

An alternative way to build (or cross compile) tun2socks is to use xgo, to use xgo, you also need docker:

# install docker: https://docs.docker.com/install

# install xgo
go get github.com/karalabe/xgo

go get github.com/eycorsican/go-tun2socks
cd $GOPATH/src/github.com/eycorsican/go-tun2socks
go get -d ./...
make clean && make xbuild
ls ./build

Run

./build/tun2socks -tunName tun1 -tunAddr 240.0.0.2 -tunGw 240.0.0.1 -proxyType socks -proxyServer 1.2.3.4:1086

Note that the TUN device may have a different name, and it should be a different name on Windows unless you have renamed it, so make sure use ifconfig, ipconfig or ip addr to check it out.

Create TUN device and Configure Routing Table

Suppose your original gateway is 192.168.0.1. The proxy server address is 1.2.3.4.

The following commands will need root permissions.

macOS

The program will automatically create a TUN device for you on macOS. To show the created TUN device, use ifconfig.

Delete original gateway:

route delete default

Add our TUN interface as the default gateway:

route add default 240.0.0.2

Add a route for your proxy server to bypass the TUN interface:

route add 1.2.3.4/32 192.168.0.1

Linux

The program will not create the TUN device for you on Linux. You need to create the TUN device by yourself:

ip tuntap add mode tun dev tun1
ip addr add 240.0.0.2 dev tun1
ip link set dev tun1 up

Delete original gateway:

ip route del default

Add our TUN interface as the default gateway:

ip route add default via 240.0.0.2

Add a route for your proxy server to bypass the TUN interface:

ip route add 1.2.3.4/32 via 192.168.0.1

Windows

To create a TUN device on Windows, you need Tap-windows, refer here for more information.

Add our TUN interface as the default gateway:

route add 0.0.0.0 mask 0.0.0.0 240.0.0.2 metric 6

Add a route for your proxy server to bypass the TUN interface:

route add 1.2.3.4 192.168.0.1 metric 5

What happened to lwIP?

Take a look at this repo: https://github.com/eycorsican/lwip

TODO

• Built-in routing rules and routing table management
• Support IPv6
• Support ICMP packets forwarding

Acknowledgements

• https://github.com/zhuhaow/tun2socks
• https://github.com/yinghuocho/gotun2socks
• https://github.com/shadowsocks/go-shadowsocks2
• https://github.com/nadoo/glider

Documentation

Index

• type Connection
• type ConnectionHandler

Types

type Connection

type Connection interface {
	// RemoteAddr returns the destination network address.
	RemoteAddr() net.Addr

	// LocalAddr returns the local client network address.
	LocalAddr() net.Addr

	// Receive receives data from TUN.
	Receive(data []byte) error

	// Write writes data to TUN.
	Write(data []byte) error

	// Sent will be called when sent data has been acknowledged by clients.
	Sent(len uint16)

	// Close closes the connection.
	Close() error

	// Abort aborts the connection to client by sending a RST segment.
	Abort()

	// Err will be called when a fatal error has occurred on the connection.
	Err(err error)

	// Reset resets the connection.
	Reset()

	// LocalDidClose will be called when local client has close the connection.
	LocalDidClose()
}

Connection abstracts a TCP/UDP connection comming from TUN. This connection should be handled by a registered TCP/UDP proxy handler.

type ConnectionHandler

type ConnectionHandler interface {
	// Connect connects the proxy server.
	Connect(conn Connection, target net.Addr) error

	// DidReceive will be called when data arrives from TUN.
	DidReceive(conn Connection, data []byte) error

	// DidSend will be called when sent data has been acknowledged by local clients.
	DidSend(conn Connection, len uint16)

	// DidClose will be called when the connection has been closed.
	DidClose(conn Connection)

	// DidAbort will be called when the connection has been aborted.
	DidAbort(conn Connection)

	// DidReset will be called when the connection has been reseted.
	DidReset(conn Connection)

	// LocalDidClose will be called when local client has close the connection.
	LocalDidClose(conn Connection)
}

ConnectionHandler handles connections comming from TUN.