Using Zerops VPN

At Zerops, security is our core priority. We ensure everything stays within a private network with zero exposure to the internet. Unlike typical consumer VPNs that focus on changing your public IP address, our WireGuard VPN implementation is specifically designed to give you secure access to your project's services.

Prerequisites

Before getting started, ensure you have:

• WireGuard installed on your system
• zCLI (serves as the WireGuard client)
• A Zerops project with at least one service

Usage

You can interact with services within your project and even establish SSH connection to your services after connecting to project through VPN.

Start VPN

Connects to the Zerops VPN.

zcli vpn up [project-id] [flags]

Flags:

• --auto-disconnect - Automatically disconnect from VPN if already connected
• --help - Display help for the vpn up command
• --mtu int - Set custom MTU value for Wireguard interface (default: 1420)
• -P, --project-id string - Required when you have access to multiple projects

To connect to a specific project without using the interactive mode, use the project ID from your Zerops dashboard:

zcli vpn up Evs8Je4NTvKeIkUqoUXp2w

Info

First-time zcli vpn up usage requires installing the Zerops VPN daemon. Confirm with y when prompted (administrator privileges may be required).

Upon connection, you'll have secure access to your project's private network with the following characteristics:

• All services are accessible via their hostnames
• Only one project connection is possible at a time (new connections automatically close existing ones)
• The VPN daemon maintains connection stability with automatic reconnection
• Environment variables are not available through VPN connections

Stop VPN

Disconnects from the Zerops VPN.

zcli vpn down [flags]

Flags:

• --help - Display help for the vpn down command

Troubleshooting

1. Interface Already Exists

Problem: When running zcli vpn up, you get an error like:

ERR /opt/homebrew/bin/wg-quick up /opt/homebrew/etc/wireguard/zerops.conf: [+] Interface for zerops is utun6 wg-quick: 'zerops' already exists as 'utun6'

Solution: Reset the VPN connection by running:

zcli vpn down
zcli vpn up

2. Hostname Resolution

Problem: Even with VPN successfully connected, hostname resolution fails with errors like:

could not translate host name "hostname" to address: nodename nor servname provided, or not known

• The issue is known to happen rarely on Windows

Solution: Append .zerops to the hostname, even when VPN shows as connected:

# Instead of
psql -h [hostname] -U [user]

# Use
psql -h [hostname].zerops -U [user]

Windows OS tip

In the Advanced TCP/IP Settings dialog, navigate to the DNS tab and confirm that "zerops" appears in the "Append these DNS suffixes (in order)" list. If missing, add it using the Add button.

3. WSL2 VPN Connection

Problem: VPN not running in WSL2

Solution: This might occur because systemd is not running in WSL2 by default. To fix:

1. Run sudo -e /etc/wsl.conf
2. Add system=true to [boot] section
3. Comment out the first line LABEL=cloudimg-rootfs / ext4 defaults 0 1
4. In cmd.exe/PowerShell run wsl --shutdown to restart WSL2

4. VPN Connection Conflicts

Problem: When another VPN connection is active concurrently with Zerops VPN, users may experience degraded network performance or connection timeouts due to packet fragmentation issues.

Solution: Run the VPN with a reduced MTU (Maximum Transmission Unit) size:

zcli vpn up --mtu 1350

This resolves packet size conflicts that can occur when multiple VPN connections are active simultaneously.

Enhanced Security with WireGuard

Zerops uses WireGuard to create secure VPN tunnel connections to your project's private network. This provides enhanced security compared to traditional SSH connections.

WireGuard eliminates the need for passwords or IP address management that SSH typically requires. As a free, lightweight, open-source communication protocol, WireGuard employs advanced cryptography to establish secure connections.

The system creates encrypted tunnels using UDP for traffic transmission and relies on public/private key pairs for user authorization.

Each Zerops project runs a WireGuard server, while the zCLI (Zerops Command Line Interface) functions as a WireGuard client. This architecture enables authorized users to securely interact with their Zerops projects through the command line interface.