From e46a9afad644fd81b02f3ed10d4c786fa05b223f Mon Sep 17 00:00:00 2001 From: Petra Vankova Date: Fri, 8 Aug 2025 15:19:05 +0200 Subject: [PATCH] vpn + zsc object-storage --- .../content/references/networking/vpn.mdx | 59 ++++----- apps/docs/content/references/zsc.mdx | 89 +++++++++++++ apps/docs/static/llms-full.txt | 121 ++++++++++++++---- 3 files changed, 209 insertions(+), 60 deletions(-) diff --git a/apps/docs/content/references/networking/vpn.mdx b/apps/docs/content/references/networking/vpn.mdx index b2ea8e46..c95b0e14 100644 --- a/apps/docs/content/references/networking/vpn.mdx +++ b/apps/docs/content/references/networking/vpn.mdx @@ -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: @@ -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 @@ -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. \ No newline at end of file diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index b0f97914..677ca34d 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -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 --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. diff --git a/apps/docs/static/llms-full.txt b/apps/docs/static/llms-full.txt index d4b05da1..eed2a0fa 100644 --- a/apps/docs/static/llms-full.txt +++ b/apps/docs/static/llms-full.txt @@ -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 @@ -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: @@ -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. ---------------------------------------- @@ -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