Gnosis VPN Client

Gnosis VPN is a VPN solution build on top the HOPR mixnet. This repo contains the system service and a control application. It is part of a larger project consisting of:

• Gnosis VPN App handling user interface
• Gnosis VPN Server handling VPN server side

Reporting Issues

We use Gnosis VPN repository as the central hub for all user feedback.

How to report an issue

1. Visit Gnosis VPN Discussions board.
2. Search existing Discussions and Issues to see if your topic is already covered.
3. If not, start a new Discussion in the Issues & Bug Reports category.
4. Provide as much detail as possible using the provided template.

The team will review all discussions and promote confirmed bugs or planned features to actionable issues. This repository is reserved for tracking actionable work on this component.

General concept

The client offers three binaries, gnosis_vpn-root, gnosis_vpn-worker and gnosis_vpn-ctl. The client system service (gnosis_vpn-root) runs with root privileges and takes care of routing setup. It spawn the worker process (gnosis_vpn-worker) which is responsible for the application logic. The control application (gnosis_vpn-ctl) is used to manage the client and its connections.

Development setup

1. Create an extra user on your system (e.g. gnosisvpn) with normal privileges. This user will be used to run the worker process.

2. Build binaries via: cargo build or nix build .#gnosis_vpn-dev.

3. Copy worker binary into user's home directory and make it owned by the user:

> sudo cp target/debug/gnosis_vpn-worker /home/gnosisvpn/
# or from nix build:
# sudo cp result/bin/gnosis_vpn-worker /home/gnosisvpn/
> sudo chown gnosisvpn:gnosisvpn /home/gnosisvpn/gnosis_vpn-worker

4. Run the root binary with sudo and provide the path to the worker binary:

> sudo RUST_LOG="debug" GNOSISVPN_HOME=/home/gnosisvpn ./target/debug/gnosis_vpn-root -c <config.toml> \
    --hopr-blokli-url <hopr blokli url> --worker-binary /home/gnosisvpn/gnosis_vpn-worker
# or from nix build:
> sudo RUST_LOG="debug" GNOSISVPN_HOME=/home/gnosisvpn ./result/bin/gnosis_vpn-root -c <config.toml> \
    --hopr-blokli-url <hopr blokli url> --worker-binary /home/gnosisvpn/gnosis_vpn-worker

Worker user configuration

There are three environment variables that control the worker process setup:

• GNOSISVPN_HOME: The home directory for the service. This is where state and caching data will be stored. Defaults to /var/lib/gnosisvpn on Linux and /Libary/Application Support/gnosisvpn on macOS.

• GNOSISVPN_WORKER_USER: The user with limited privileges that will run the worker process. This user needs to have read and execute permissions for the worker binary and write permissions for the GNOSISVPN_HOME directory. Defaults to gnosisvpn.

• GNOSISVPN_WORKER_BINARY: The path to the worker binary. The worker process will be spawned with this binary.

Installation

Use the latest installer.

Check signatures

To validate the signature of the downloaded binary from GitHub, follow these steps:

1. Import the public key (checkout the repository first):

   gpg --import gpg-publickey.asc

2. Verify the binary signature (examples for x86_64 and ARM64):

   # For x86_64 (AMD64)
   gpg --verify gnosis_vpn-root-x86_64-linux.asc gnosis_vpn-root-x86_64-linux
   
   # For ARM64
   gpg --verify gnosis_vpn-root-aarch64-linux.asc gnosis_vpn-root-aarch64-linux

3. Compare the checksum with the actual checksum:

   # For x86_64 (AMD64)
   diff -u <(cat gnosis_vpn-root-x86_64-linux.sha256) <(shasum -a 256 gnosis_vpn-root-x86_64-linux)
   
   # For ARM64
   diff -u <(cat gnosis_vpn-root-aarch64-linux.sha256) <(shasum -a 256 gnosis_vpn-root-aarch64-linux)

Idle shutdown

When --client-autostart <duration> (or GNOSISVPN_CLIENT_AUTOSTART) is set, the service starts the worker automatically on launch and shuts it down after the worker has been idle for the given duration.

The idle countdown behaves as follows:

• Idle: countdown runs; worker shuts down when it reaches zero.
• Connected: countdown is suspended for the lifetime of the VPN tunnel.
• Disconnected: countdown resumes from the full duration.
• Any other command to the worker (e.g. status) resets the countdown.

Example — shut down the worker after 10 minutes of idle time:

gnosis_vpn-root --client-autostart 10m ...

General usage

Check available params and env vars via:

gnosis_vpn-root --help gnosis_vpn-ctl --help

Deployment

Show potential deployment targets:

nix flake show

Build for a target, e.g. x86_64-linux or aarch64-linux:

# For x86_64 (AMD64)
nix build -L .#binary-gnosis_vpn-x86_64-linux

# For ARM64
nix build -L .#binary-gnosis_vpn-aarch64-linux

The resulting binaries are in result/bin/:

$ ls -l result*/bin/
result/bin/:
total 4752
-r-xr-xr-x 1 root root  4863367 Jan  1  1970 gnosis_vpn-root
-r-xr-xr-x 1 root root 14863367 Jan  1  1970 gnosis_vpn-worker
-r-xr-xr-x 1 root root  1740058 Jan  1  1970 gnosis_vpn-ctl