Skip to content

Commit 82ccfd6

Browse files
vankovapvankovap
authored
vpn + zsc object-storage (#287)
1 parent c29385b commit 82ccfd6

File tree

3 files changed

+209
-60
lines changed

3 files changed

+209
-60
lines changed

‎apps/docs/content/references/networking/vpn.mdx‎

Lines changed: 27 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -20,23 +20,17 @@ You can interact with services within your project and even establish SSH connec
2020

2121
### Start VPN
2222

23-
To start a VPN session:
23+
Connects to the Zerops VPN.
2424

2525
```bash
26-
zcli vpn up
26+
zcli vpn up [project-id] [flags]
2727
```
2828

29-
Select your project when prompted.
30-
31-
```bash
32-
Usage:
33-
zcli vpn up [project-id] [flags]
34-
35-
Flags:
36-
--auto-disconnect Automatically disconnects existing VPN connections
37-
--help Display help for the vpn up command
38-
--project-id string Project ID for command execution (required for multiple projects)
39-
```
29+
**Flags:**
30+
- `--auto-disconnect` - Automatically disconnect from VPN if already connected
31+
- `--help` - Display help for the vpn up command
32+
- `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420)
33+
- `-P, --project-id string` - Required when you have access to multiple projects
4034

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

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

5953
### Stop VPN
6054

61-
To stop the VPN session:
55+
Disconnects from the Zerops VPN.
6256

6357
```bash
64-
zcli vpn down
65-
66-
Usage:
67-
zcli vpn down [flags]
68-
69-
Flags:
70-
--help Display help for the vpn down command
58+
zcli vpn down [flags]
7159
```
7260

61+
**Flags:**
62+
- `--help` - Display help for the vpn down command
63+
7364
## Troubleshooting
7465

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

117-
## How do we provide better security?
108+
#### 4. VPN Connection Conflicts
109+
**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.
110+
111+
**Solution**: Run the VPN with a reduced MTU (Maximum Transmission Unit) size:
112+
```bash
113+
zcli vpn up --mtu 1350
114+
```
115+
116+
This resolves packet size conflicts that can occur when multiple VPN connections are active simultaneously.
117+
118+
## Enhanced Security with WireGuard
118119

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

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

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

130-
Inside Zerops project runs a Wireguard server and zCLI (Zerops Command Line Interface) works as
131-
a Wireguard client which helps you to interact with your zerops project if you're authorized.
126+
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.

‎apps/docs/content/references/zsc.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,95 @@ zsc cdn purge example.com "/images/"
113113
:::
114114
---
115115

116+
### object-storage
117+
118+
Manages object storage operations for backups and restores.
119+
120+
```sh
121+
zsc object-storage [command]
122+
```
123+
124+
#### Available flags
125+
- `-h, --help`: Help for the object-storage command
126+
127+
When using `--storage objectstorage`, the command requires the following environment variables to be defined:
128+
129+
* `objectstorage_apiUrl` - API URL of the object storage service
130+
* `objectstorage_accessKeyId` - Access key ID for authentication
131+
* `objectstorage_secretAccessKey` - Secret access key for authentication
132+
* `objectstorage_bucketName` - Name of the bucket to use
133+
134+
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.
135+
136+
#### Sub-commands
137+
138+
#### Common parameters
139+
All sub-commands share these parameters:
140+
- `--storage`: Name of the object storage service
141+
- `--name`: Name of the backup in storage
142+
- `--silent`, `-s`: Suppresses command output (default: false)
143+
- `--no-fail`: Prevents command failure with exit code 1 (default: false)
144+
145+
**list** - Lists all available backups in the specified storage
146+
```sh
147+
zsc object-storage list --storage <storage-name> --name <backup-name>
148+
```
149+
150+
**backup** - Creates a backup of specified directories to object storage
151+
```sh
152+
zsc object-storage backup <directory1> [<directory2>...] --storage <storage-name> --name <backup-name> [options]
153+
```
154+
Additional options:
155+
- `--truncateCount`: If greater than 0, truncate operation is performed after successful backup, keeping the specified number of most recent backups (default: 0)
156+
157+
**restore** - Restores a backup from object storage
158+
```sh
159+
zsc object-storage restore [<directory>] --storage <storage-name> --name <backup-name> [options]
160+
```
161+
Additional options:
162+
- `--dryRun`: Simulates restore operation without performing actual changes
163+
- `--overwrite`: Allows overwriting existing files during restore
164+
- `--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)
165+
- `--ignore-non-existing`: Prevents command failure if backup doesn't exist
166+
167+
**truncate** - Removes old backups, keeping only the most recent ones
168+
```sh
169+
zsc object-storage truncate --storage <storage-name> --name <backup-name> [options]
170+
```
171+
Additional options:
172+
- `--dryRun`: Simulates truncate operation without performing actual deletions (default: false)
173+
- `--truncateCount`: Number of most recent backups to keep (default: 5)
174+
175+
#### Examples
176+
```sh
177+
# List all backups
178+
zsc object-storage list --storage objectstorage --name daily-backup
179+
180+
# Create a backup with retention
181+
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncateCount 5
182+
183+
# Restore with dry run preview
184+
zsc object-storage restore --storage objectstorage --name database-backup --dryRun
185+
186+
# Clean up old backups
187+
zsc object-storage truncate --storage objectstorage --name logs-backup --truncateCount 3
188+
```
189+
190+
#### Example usage in `zerops.yaml`
191+
```yaml
192+
zerops:
193+
- setup: app
194+
run:
195+
initCommands:
196+
- "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
197+
crontab:
198+
- timing: "*/10 * * * *"
199+
command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncateCount 5 ./data/"
200+
allContainers: false
201+
```
202+
203+
---
204+
116205
### shared-storage
117206
118207
Manages shared storage volumes for persistent data storage.

‎apps/docs/static/llms-full.txt‎

Lines changed: 93 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -22125,19 +22125,15 @@ Before getting started, ensure you have:
2212522125
## Usage
2212622126
You can interact with services within your project and even establish SSH connection to your services after connecting to project through VPN.
2212722127
### Start VPN
22128-
To start a VPN session:
22129-
```bash
22130-
zcli vpn up
22131-
```
22132-
Select your project when prompted.
22128+
Connects to the Zerops VPN.
2213322129
```bash
22134-
Usage:
22135-
zcli vpn up [project-id] [flags]
22136-
Flags:
22137-
--auto-disconnect Automatically disconnects existing VPN connections
22138-
--help Display help for the vpn up command
22139-
--project-id string Project ID for command execution (required for multiple projects)
22130+
zcli vpn up [project-id] [flags]
2214022131
```
22132+
**Flags:**
22133+
- `--auto-disconnect` - Automatically disconnect from VPN if already connected
22134+
- `--help` - Display help for the vpn up command
22135+
- `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420)
22136+
- `-P, --project-id string` - Required when you have access to multiple projects
2214122137
To connect to a specific project without using the interactive mode, use the project ID from your Zerops dashboard:
2214222138
```bash
2214322139
zcli vpn up Evs8Je4NTvKeIkUqoUXp2w
@@ -22152,14 +22148,12 @@ Upon connection, you'll have secure access to your project's private network wit
2215222148
- The VPN daemon maintains connection stability with automatic reconnection
2215322149
- Environment variables are not available through VPN connections
2215422150
### Stop VPN
22155-
To stop the VPN session:
22151+
Disconnects from the Zerops VPN.
2215622152
```bash
22157-
zcli vpn down
22158-
Usage:
22159-
zcli vpn down [flags]
22160-
Flags:
22161-
--help Display help for the vpn down command
22153+
zcli vpn down [flags]
2216222154
```
22155+
**Flags:**
22156+
- `--help` - Display help for the vpn down command
2216322157
## Troubleshooting
2216422158
#### 1. Interface Already Exists
2216522159
**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
2219422188
2. Add `system=true` to `[boot]` section
2219522189
3. Comment out the first line `LABEL=cloudimg-rootfs / ext4 defaults 0 1`
2219622190
4. In `cmd.exe/PowerShell` run `wsl --shutdown` to restart WSL2
22197-
## How do we provide better security?
22198-
We are using WireGuard under the hood for VPN to establish a secure tunnel
22199-
connection to a private network of a Zerops project. This approach provides a safer connection
22200-
compared to SSH.
22201-
Additionally, you won't need to add any passwords or IP addresses for SSH access.
22202-
WireGuard is a free, lightweight, open-source software—technically a communication protocol—that
22203-
utilizes cryptography.
22204-
It helps us create a secure tunnel that uses UDP for transmitting traffic. We use public/private key pairs
22205-
for authorization.
22206-
Inside Zerops project runs a Wireguard server and zCLI (Zerops Command Line Interface) works as
22207-
a Wireguard client which helps you to interact with your zerops project if you're authorized.
22191+
#### 4. VPN Connection Conflicts
22192+
**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.
22193+
**Solution**: Run the VPN with a reduced MTU (Maximum Transmission Unit) size:
22194+
```bash
22195+
zcli vpn up --mtu 1350
22196+
```
22197+
This resolves packet size conflicts that can occur when multiple VPN connections are active simultaneously.
22198+
## Enhanced Security with WireGuard
22199+
Zerops uses **WireGuard** to create secure VPN tunnel connections to your project's private network. This provides enhanced security compared to traditional **SSH** connections.
22200+
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.
22201+
The system creates encrypted tunnels using **UDP** for traffic transmission and relies on **public/private key pairs** for user authorization.
22202+
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.
2220822203

2220922204
----------------------------------------
2221022205

@@ -22439,6 +22434,76 @@ zsc cdn purge example.com "/images/"
2243922434
- Currently, the purge command only works for the [Static Mode](/features/cdn#static-mode) CDN
2244022435
:::
2244122436
---
22437+
### object-storage
22438+
Manages object storage operations for backups and restores.
22439+
```sh
22440+
zsc object-storage [command]
22441+
```
22442+
#### Available flags
22443+
- `-h, --help`: Help for the object-storage command
22444+
When using `--storage objectstorage`, the command requires the following environment variables to be defined:
22445+
* `objectstorage_apiUrl` - API URL of the object storage service
22446+
* `objectstorage_accessKeyId` - Access key ID for authentication
22447+
* `objectstorage_secretAccessKey` - Secret access key for authentication
22448+
* `objectstorage_bucketName` - Name of the bucket to use
22449+
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.
22450+
#### Sub-commands
22451+
#### Common parameters
22452+
All sub-commands share these parameters:
22453+
- `--storage`: Name of the object storage service
22454+
- `--name`: Name of the backup in storage
22455+
- `--silent`, `-s`: Suppresses command output (default: false)
22456+
- `--no-fail`: Prevents command failure with exit code 1 (default: false)
22457+
**list** - Lists all available backups in the specified storage
22458+
```sh
22459+
zsc object-storage list --storage --name
22460+
```
22461+
**backup** - Creates a backup of specified directories to object storage
22462+
```sh
22463+
zsc object-storage backup [...] --storage --name [options]
22464+
```
22465+
Additional options:
22466+
- `--truncateCount`: If greater than 0, truncate operation is performed after successful backup, keeping the specified number of most recent backups (default: 0)
22467+
**restore** - Restores a backup from object storage
22468+
```sh
22469+
zsc object-storage restore [] --storage --name [options]
22470+
```
22471+
Additional options:
22472+
- `--dryRun`: Simulates restore operation without performing actual changes
22473+
- `--overwrite`: Allows overwriting existing files during restore
22474+
- `--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)
22475+
- `--ignore-non-existing`: Prevents command failure if backup doesn't exist
22476+
**truncate** - Removes old backups, keeping only the most recent ones
22477+
```sh
22478+
zsc object-storage truncate --storage --name [options]
22479+
```
22480+
Additional options:
22481+
- `--dryRun`: Simulates truncate operation without performing actual deletions (default: false)
22482+
- `--truncateCount`: Number of most recent backups to keep (default: 5)
22483+
#### Examples
22484+
```sh
22485+
# List all backups
22486+
zsc object-storage list --storage objectstorage --name daily-backup
22487+
# Create a backup with retention
22488+
zsc object-storage backup /var/www --storage objectstorage --name web-backup --truncateCount 5
22489+
# Restore with dry run preview
22490+
zsc object-storage restore --storage objectstorage --name database-backup --dryRun
22491+
# Clean up old backups
22492+
zsc object-storage truncate --storage objectstorage --name logs-backup --truncateCount 3
22493+
```
22494+
#### Example usage in `zerops.yaml`
22495+
```yaml
22496+
zerops:
22497+
- setup: app
22498+
run:
22499+
initCommands:
22500+
- "zsc object-storage restore --storage objectstorage --name $ZEROPS_StackName --ignore-non-existing ./data/"
22501+
crontab:
22502+
- timing: "*/10 * * * *"
22503+
command: "zsc object-storage backup --storage objectstorage --name $ZEROPS_StackName --truncateCount 5 ./data/"
22504+
allContainers: false
22505+
```
22506+
---
2244222507
### shared-storage
2244322508
Manages shared storage volumes for persistent data storage.
2244422509
```sh

0 commit comments

Comments
 (0)