112 lines
5.8 KiB
Markdown
112 lines
5.8 KiB
Markdown
# 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 `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.
|