luxferre/gs-warp
1
0
Fork 0
Code Actions Activity

init upload

Browse Source
This commit is contained in:
Luxferre
2026-07-25 11:14:52 +03:00
commit f7e67801a5
7 changed files with 360 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+108
View File
@@ -0,0 +1,108 @@
# 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. Enter and save the GSocket secret: `make server-secret`
2. Build (if necessary) and start the server: `make server`
3. Export the `client.ovpn` file to the current directory: `make ovpn`
4. Stop the server (without removing the data): `make stop-server`
5. Stop the server and remove all data: `make clean`
### 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`, enter your GSocket server secret and then 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. Run these commands directly: `gs-netcat -D -s your_gsocket_secret -p 1194 && sudo openvpn --daemon gs-warp --config client.ovpn`
3. 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. In a separate terminal window, run `gs-netcat -D -s your_gsocket_secret -p 1194`.
3. Start the OpenVPN connection in the client.
4. 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.