gs-warp/README.md

GS-Warp: A turnkey GSocket-tunneled VPN

About

GS-Warp is a simple and straightforward implementation of the idea of tunneling OpenVPN traffic via Global Socket Relay Network (GSRN). This setup is especially suitable for installing the server side on a small VPS (Virtual Private Server) and allows you to:

• prevent potential eavesdroppers on your VPS traffic from knowing your real peer IP,
• avoid provider-side blocking of your VPS,
• staying protected in case of an (unlikely) event of compromising GSRN or GSocket encryption itself,
• have the outgoing traffic server even behind NAT, as no external IP is required for GS-Warp to work.

Dependencies

Server-side dependencies:

• full (real) root access to the server,
• Docker (recommended),
• OpenVPN (installed within the container),
• GSocket (installed within the container),
• Make (optional but recommended).

Client-side dependencies:

• any OpenVPN client,
• GSocket,
• Make (optional but recommended in case of using the "simple" client).

Usage

On the server

Assumes having Docker and Make. From the repo root:

1. Build (if necessary) and start the server: make -B server
2. Export the client.ovpn file to the current directory: make ovpn
3. Stop the server (without removing the data): make stop-server
4. Stop the server and remove all data: make clean

Note: the client.ovpn file is the sole access key to the entire tunnel. Treat is as confidential data.

On the client ("simple" approach, Make-based)

1. Get the client.ovpn file from the server and put it into the client directory.
2. Run make start and then enter your sudo password (if necessary).
3. To stop the client, run make stop.

On the client (manual approach, POSIX)

1. Get the client.ovpn file from the server.
2. Get the GS secret as the MD5 hash of the client.ovpn file: export GS_SECRET=$(md5sum client.ovpn | cut -d ' ' -f 1)
3. Run these commands directly: gs-netcat -D -s $GS_SECRET -p 1194 && sudo openvpn --daemon gs-warp --config client.ovpn
4. To stop, first stop the OpenVPN process and then gs-netcat.

On the client (manual approach, non-POSIX)

This is suitable for non-POSIX environments. You'll need any OpenVPN client and gs-netcat binary for your platform.

1. Get the client.ovpn file from the server and put it into your OpenVPN client's profile. Do not start the client yet.
2. Get the GS secret as the MD5 hash of the client.ovpn file using whatever means available.
3. In a separate terminal window, run gs-netcat -D -s $GS_SECRET -p 1194.
4. Start the OpenVPN connection in the client.
5. To stop, first stop the OpenVPN connection and then terminate the gs-netcat process.

More client options coming soon!

FAQ

What is the advantage of GS-Warp over a plain VPN on a VPS?

Potential eavesdroppers, including your own ISP, know that you're connecting to your VPS and can block/throttle this connection at will. Tunneling over GSRN hides the very fact of this connection, as well as provides an additional end-to-end encryption layer.

Additionally, a plain VPS requires an external IP for you to be able to connect directly. With GSRN, both peers can be behind NAT and this won't affect their connectivity in any way.

What is the advantage of GS-Warp over plain GSRN tunneling with gs-netcat?

If you only need to have TCP connections tunneled, GS-Warp is an overkill indeed, and you can get away with setting up a SOCKS proxy like this (which even works within containers without special privileges):

# on the server side:
gs-netcat -DlS -s [your_secret]

# on the client side:
gs-netcat -D -p [your_socks_port] -s [your_secret] 

However, if you also need UDP or other IP traffic forwarded through your tunnel, you need to encapsulate it with a full VPN piped through the TCP channel established via gs-netcat. GS-Warp was created to facilitate just that.

Can we use the GS-Warp server setup within existing containers?

Only if you have full root control over the host environment. Namely, you'll need to add NET_ADMIN and NET_RAW capabilities, /dev/net/tun device forwarding and net.ipv4.ip_forward=1 sysctl setting.

Why does GS-Warp use OpenVPN and not e.g. WireGuard or other modern alternatives?

Since all the end-to-end encryption and traffic masking heavy lifting is done by GSocket anyway, the choice of VPN package for IP traffic encapsulation became merely a matter of convenience. OpenVPN was selected because it has uniform configuration format across all platforms it's officially implemented on (desktop, embedded and mobile), which gives us the broadest compatibility range.

I have e.g. an iPad where I can run OpenVPN but cannot run gs-netcat, what do I do?

Just decouple the client setup. Run gs-netcat on another device on your LAN (or even WAN) and then edit the IP in the remote 127.0.0.1 1194 line of your client.ovpn config file to reflect the address of that device.

As a bonus, the traffic between your iPad and the node you run gs-netcat on will still be protected with OpenVPN encryption.

What about Android?

On Android (at least on ARM64), you can freely run gs-netcat within Termux and then use the official OpenVPN Connect application to connect through it using the very same client.ovpn file. Just follow the guide above to run the correct gs-netcat command. Besides this, a dedicated Android helper application is being planned to make running a GSocket-based tunnel much easier for the average user.

N.B.: when running via Termux, don't forget to acquire the wakelock in the notification drawer for the OS to not suddenly suspend the gs-netcat process when idle.

Credits

Created by Luxferre in 2026, released into the public domain with no warranties.

Thanks to Global Socket and OpenVPN projects for making this possible.