# 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](https://www.wireguard.com/install) installed on your system
- [zCLI](/references/cli) (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.

```bash
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:

```bash
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.

```bash
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:
```bash
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:
```bash
# Instead of
psql -h [hostname] -U [user]

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

:::tip 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:
```bash
zcli vpn up --mtu 1350
```

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

#### 5. wg-quick Issues on Ubuntu 25.*
**Problem**: VPN fails to start due to wg-quick errors on Ubuntu 25.* systems.

**Solution**: Install and configure AppArmor utilities:
```bash
sudo apt install apparmor-utils
sudo aa-complain wg-quick
```

## 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.