Skip to main content

subtun: A Peer-to-Peer VPN

subtun is a powerful component that creates a secure, peer-to-peer VPN over the subp2p network. It allows you to create a private, virtual network between two or more peers, enabling them to communicate as if they were on the same local network.

How it Works: The TUN Device​

subtun works by creating a TUN device on the host operating system. A TUN device is a virtual network interface that, instead of receiving packets from a physical medium, receives them from a user-space program. In this case, that program is subtun.

When your operating system sends an IP packet to the TUN device, subtun reads the packet, encapsulates it, and sends it over a secure subp2p stream to a remote peer. On the other side, the remote subtun instance receives the packet, decapsulates it, and writes it to its own TUN device. This process is bidirectional, creating a seamless and transparent tunnel between the two peers.

Client-Gateway Architecture​

subtun operates in a client-gateway architecture:

  • Gateway: A subtun instance running in gateway mode acts as a central point for the virtual network. It accepts connections from multiple clients and can route traffic between them.
  • Client: A subtun instance running in client mode connects to a gateway and becomes part of the virtual network.

This architecture allows you to create a variety of network topologies, from simple point-to-point tunnels to more complex hub-and-spoke networks.

Tunneling TCP and UDP​

Because subtun operates at the IP packet level, it is protocol-agnostic. This means it can tunnel any protocol that runs on top of IP, including:

  • TCP: For reliable, connection-oriented communication.
  • UDP: For low-latency, connectionless communication.

This makes subtun incredibly versatile. You can use it to securely access remote services, play games over a private network, or even route traffic between different physical networks.

By leveraging the power of subp2p and TUN devices, subtun provides a simple yet powerful way to create secure, private networks that can span the globe.

subtun in SUBFROST​

The subfrost-cli can be used to create a peer-to-peer VPN using subtun. This is useful for creating a private network between two or more peers, enabling them to communicate as if they were on the same local network.

Running a subtun Gateway​

Here is an example of how to run a subtun gateway:

subfrost-cli tun --gateway --register my-vpn.rail --circuit p2p.subfrost.io

This command will start a subtun gateway and register the name my-vpn.rail on the subp2p network. Clients can then connect to this gateway to join the VPN.

Running a subtun Client​

Here is an example of how to run a subtun client:

subfrost-cli tun --connect my-vpn.rail --circuit p2p.subfrost.io

This command will connect to the subtun gateway at my-vpn.rail and create a TUN device on the local machine. You can then route traffic through this TUN device to communicate with other peers on the VPN.