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](https://openvpn.net/) traffic via [Global Socket](https://www.gsocket.io/) 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 repo root 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.