Skip to content

vpn + zsc object-storage #287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 8, 2025
Merged

vpn + zsc object-storage #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 27 additions & 32 deletions apps/docs/content/references/networking/vpn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,17 @@ You can interact with services within your project and even establish SSH connec

### Start VPN

To start a VPN session:
Connects to the Zerops VPN.

```bash
zcli vpn up
zcli vpn up [project-id] [flags]
```

Select your project when prompted.

```bash
Usage:
zcli vpn up [project-id] [flags]

Flags:
--auto-disconnect Automatically disconnects existing VPN connections
--help Display help for the vpn up command
--project-id string Project ID for command execution (required for multiple projects)
```
**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:

Expand All @@ -58,18 +52,15 @@ Upon connection, you'll have secure access to your project's private network wit

### Stop VPN

To stop the VPN session:
Disconnects from the Zerops VPN.

```bash
zcli vpn down

Usage:
zcli vpn down [flags]

Flags:
--help Display help for the vpn down command
zcli vpn down [flags]
```

**Flags:**
- `--help` - Display help for the vpn down command

## Troubleshooting

#### 1. Interface Already Exists
Expand Down Expand Up @@ -114,18 +105,22 @@ In the Advanced TCP/IP Settings dialog, navigate to the DNS tab and confirm that
3. Comment out the first line `LABEL=cloudimg-rootfs / ext4 defaults 0 1`
4. In `cmd.exe/PowerShell` run `wsl --shutdown` to restart WSL2

## How do we provide better security?
#### 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.

## Enhanced Security with WireGuard

We are using WireGuard under the hood for VPN to establish a secure tunnel
connection to a private network of a Zerops project. This approach provides a safer connection
compared to SSH.
Zerops uses **WireGuard** to create secure VPN tunnel connections to your project's private network. This provides enhanced security compared to traditional **SSH** connections.

Additionally, you won't need to add any passwords or IP addresses for SSH access.
WireGuard is a free, lightweight, open-source software—technically a communication protocol—that
utilizes cryptography.
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.

It helps us create a secure tunnel that uses UDP for transmitting traffic. We use public/private key pairs
for authorization.
The system creates encrypted tunnels using **UDP** for traffic transmission and relies on **public/private key pairs** for user authorization.

Inside Zerops project runs a Wireguard server and zCLI (Zerops Command Line Interface) works as
a Wireguard client which helps you to interact with your zerops project if you're authorized.
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.
89 changes: 89 additions & 0 deletions apps/docs/content/references/zsc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,95 @@ zsc cdn purge example.com "/images/"
:::
---

### object-storage

Manages object storage operations for backups and restores.

```sh
zsc object-storage [command]
```

#### Available flags
- `-h, --help`: Help for the object-storage command

When using `--storage objectstorage`, the command requires the following environment variables to be defined:

* `objectstorage_apiUrl` - API URL of the object storage service
* `objectstorage_accessKeyId` - Access key ID for authentication
* `objectstorage_secretAccessKey` - Secret access key for authentication
* `objectstorage_bucketName` - Name of the bucket to use

These environment variables will be automatically available if the object storage service has `envIsolation: none` configured, or if the entire project has `envIsolation: none` set. Otherwise, you need to explicitly reference these environment variables in your `zerops.yaml` file.

#### Sub-commands

#### Common parameters
All sub-commands share these parameters:
- `--storage`: Name of the object storage service
- `--name`: Name of the backup in storage
- `--silent`, `-s`: Suppresses command output (default: false)
- `--no-fail`: Prevents command failure with exit code 1 (default: false)

**list** - Lists all available backups in the specified storage
```sh
zsc object-storage list --storage <storage-name> --name <backup-name>
```

**backup** - Creates a backup of specified directories to object storage
```sh
zsc object-storage backup <directory1> [<directory2>...] --storage <storage-name> --name <backup-name> [options]
```
Additional options:
- `--truncateCount`: If greater than 0, truncate operation is performed after successful backup, keeping the specified number of most recent backups (default: 0)

**restore** - Restores a backup from object storage
```sh
zsc object-storage restore [<directory>] --storage <storage-name> --name <backup-name> [options]
```
Additional options:
- `--dryRun`: Simulates restore operation without performing actual changes
- `--overwrite`: Allows overwriting existing files during restore
- `--index`: Specifies which backup to restore. Non-negative values count from newest (0 = newest, 1 = second newest), negative values count from oldest (-1 = oldest, -2 = second oldest) (default: 0)
- `--ignore-non-existing`: Prevents command failure if backup doesn't exist

**truncate** - Removes old backups, keeping only the most recent ones
```sh
zsc object-storage truncate --storage <storage-name> --name <backup-name> [options]
```
Additional options:
- `--dryRun`: Simulates truncate operation without performing actual deletions (default: false)
- `--truncateCount`: Number of most recent backups to keep (default: 5)

#### Examples
```sh
# List all backups
zsc object-storage list --storage objectstorage --name daily-backup

# Create a backup with retention
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncateCount 5

# Restore with dry run preview
zsc object-storage restore --storage objectstorage --name database-backup --dryRun

# Clean up old backups
zsc object-storage truncate --storage objectstorage --name logs-backup --truncateCount 3
```

#### Example usage in `zerops.yaml`
```yaml
zerops:
- setup: app
run:
initCommands:
- "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
crontab:
- timing: "*/10 * * * *"
command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncateCount 5 ./data/"
allContainers: false
```

---

### shared-storage

Manages shared storage volumes for persistent data storage.
Expand Down
121 changes: 93 additions & 28 deletions apps/docs/static/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22125,19 +22125,15 @@ Before getting started, ensure you have:
## 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
To start a VPN session:
```bash
zcli vpn up
```
Select your project when prompted.
Connects to the Zerops VPN.
```bash
Usage:
zcli vpn up [project-id] [flags]
Flags:
--auto-disconnect Automatically disconnects existing VPN connections
--help Display help for the vpn up command
--project-id string Project ID for command execution (required for multiple projects)
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
Expand All @@ -22152,14 +22148,12 @@ Upon connection, you'll have secure access to your project's private network wit
- The VPN daemon maintains connection stability with automatic reconnection
- Environment variables are not available through VPN connections
### Stop VPN
To stop the VPN session:
Disconnects from the Zerops VPN.
```bash
zcli vpn down
Usage:
zcli vpn down [flags]
Flags:
--help Display help for the vpn down command
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:
Expand Down Expand Up @@ -22194,17 +22188,18 @@ In the Advanced TCP/IP Settings dialog, navigate to the DNS tab and confirm that
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
## How do we provide better security?
We are using WireGuard under the hood for VPN to establish a secure tunnel
connection to a private network of a Zerops project. This approach provides a safer connection
compared to SSH.
Additionally, you won't need to add any passwords or IP addresses for SSH access.
WireGuard is a free, lightweight, open-source software—technically a communication protocol—that
utilizes cryptography.
It helps us create a secure tunnel that uses UDP for transmitting traffic. We use public/private key pairs
for authorization.
Inside Zerops project runs a Wireguard server and zCLI (Zerops Command Line Interface) works as
a Wireguard client which helps you to interact with your zerops project if you're authorized.
#### 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.
## 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.

----------------------------------------

Expand Down Expand Up @@ -22439,6 +22434,76 @@ zsc cdn purge example.com "/images/"
- Currently, the purge command only works for the [Static Mode](/features/cdn#static-mode) CDN
:::
---
### object-storage
Manages object storage operations for backups and restores.
```sh
zsc object-storage [command]
```
#### Available flags
- `-h, --help`: Help for the object-storage command
When using `--storage objectstorage`, the command requires the following environment variables to be defined:
* `objectstorage_apiUrl` - API URL of the object storage service
* `objectstorage_accessKeyId` - Access key ID for authentication
* `objectstorage_secretAccessKey` - Secret access key for authentication
* `objectstorage_bucketName` - Name of the bucket to use
These environment variables will be automatically available if the object storage service has `envIsolation: none` configured, or if the entire project has `envIsolation: none` set. Otherwise, you need to explicitly reference these environment variables in your `zerops.yaml` file.
#### Sub-commands
#### Common parameters
All sub-commands share these parameters:
- `--storage`: Name of the object storage service
- `--name`: Name of the backup in storage
- `--silent`, `-s`: Suppresses command output (default: false)
- `--no-fail`: Prevents command failure with exit code 1 (default: false)
**list** - Lists all available backups in the specified storage
```sh
zsc object-storage list --storage --name
```
**backup** - Creates a backup of specified directories to object storage
```sh
zsc object-storage backup [...] --storage --name [options]
```
Additional options:
- `--truncateCount`: If greater than 0, truncate operation is performed after successful backup, keeping the specified number of most recent backups (default: 0)
**restore** - Restores a backup from object storage
```sh
zsc object-storage restore [] --storage --name [options]
```
Additional options:
- `--dryRun`: Simulates restore operation without performing actual changes
- `--overwrite`: Allows overwriting existing files during restore
- `--index`: Specifies which backup to restore. Non-negative values count from newest (0 = newest, 1 = second newest), negative values count from oldest (-1 = oldest, -2 = second oldest) (default: 0)
- `--ignore-non-existing`: Prevents command failure if backup doesn't exist
**truncate** - Removes old backups, keeping only the most recent ones
```sh
zsc object-storage truncate --storage --name [options]
```
Additional options:
- `--dryRun`: Simulates truncate operation without performing actual deletions (default: false)
- `--truncateCount`: Number of most recent backups to keep (default: 5)
#### Examples
```sh
# List all backups
zsc object-storage list --storage objectstorage --name daily-backup
# Create a backup with retention
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncateCount 5
# Restore with dry run preview
zsc object-storage restore --storage objectstorage --name database-backup --dryRun
# Clean up old backups
zsc object-storage truncate --storage objectstorage --name logs-backup --truncateCount 3
```
#### Example usage in `zerops.yaml`
```yaml
zerops:
- setup: app
run:
initCommands:
- "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
crontab:
- timing: "*/10 * * * *"
command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncateCount 5 ./data/"
allContainers: false
```
---
### shared-storage
Manages shared storage volumes for persistent data storage.
```sh
Expand Down