Using CLI to backup files into Blimp + ZS3 Server
Blimp is an AI-ready, distributed on-prem storage solution powered by Züs, the world’s fastest blockchain, offering 400 ms optimistic and 2-second full finality. It is the first S3-compatible storage platform that is both ACID-compliant and runs on a zero-knowledge network.
Designed for enterprise-scale storage and AI-driven applications, Blimp ensures high security, redundancy, and data sovereignty.
ZS3 Server is an S3-compatible object storage gateway that connects traditional cloud tools like AWS CLI and MinIO CLI with the decentralized Züs network using the GoSDK. It enables users to manage files via familiar S3 APIs while benefitting from decentralized storage.
This guide includes:
CLI-based wallet recovery and allocation creation
Deploying ZS3Server through Blimp UI and verifying endpoint
File uploads/downloads using zboxcli, AWS CLI, and MinIO CLI
Using encrypted folders and verifying storage
Backup configuration using Restic and Veeam
Referenced Pages:
CLI Setup: https://docs.zus.network/zus-docs/clis
ZS3 Server Concept & Usage: https://docs.zus.network/zus-docs/system-overview/storage/zs3-server
Prerequisites
Before proceeding, ensure that you have:
System Requirements:
Linux (Ubuntu 20.04+) or macOS (Big Sur 11.0.1+)
Admin access to a terminal environment with
bash
,make
, and package installation permissions
Tools:
Veeam Backup & Replication — enterprise backup and disaster recovery solution with S3 support
Account Setup:
Mnemonic phrase (24-word seed phrase) securely backed up
Wallet recovered using zwalletcli with a local JSON wallet file (e.g.,
zus_wallet.json
)Wallet funded with ZCN tokens through the Blimp UI or supported wallet integrations (e.g., MetaMask)
Setting Up Blimp Allocation via CLI
This section guides users through creating a Züs wallet, installing CLI tools, and performing basic file operations on their Blimp allocation.
Step 1: Sign Up on Blimp
Google, Apple, or Okta SSO
Email and one-time password (OTP)
Enter your mobile number and verify it with a second OTP
You will now receive your wallet mnemonics — a 24-word seed phrase
Write down this mnemonic phrase. It will not be shown again and is essential for wallet recovery.
Step 2: Select Blobber Brand
When creating your allocation, select the brand based on your performance and decentralization preference:
Züs‑Only: Operated directly by Züs (high performance)
All‑Blobbers: All available providers (max decentralization)
Unbranded: Only third-party blobbers
All Brands: Mixed strategy
Step 3: Install CLI Tools
Use Git to clone and install zboxcli
and zwalletcli
.
Install zboxcli
Install zwalletcli
Step 4: Add CLI Configuration
Create the required config file at ~/.zcn/config.yaml
:
This file allows the CLI tools to communicate with the Züs blockchain.
Step 5: Recover Wallet from Mnemonics
Use the 24-word mnemonic to regenerate your wallet keys and store them in a JSON file:
Verify wallet creation:
You should see:
Step 6: Create a New Allocation (Optional)
If you haven’t created a default 2 GB allocation on the Blimp UI, you can create one via CLI as follows:
This will reserve 2 GB of storage with 2 data and 2 parity shards.
Step 7: Uploading Files to Blimp Allocation
Ensure you are in the zboxcli
directory before using these commands.
Upload Single File
Download a File
Update a File
Upload Multiple Files via JSON
Create a JSON file (e.g., multi-upload.json
) with this format:
Upload with:
Each upload will be confirmed via terminal output indicating upload status and content type.
To verify uploads, you can use:
You may also check file presence and metadata in the Blimp web UI by navigating to your allocation dashboard.
Deploying ZS3 Server
This section covers how to set up and fully understand the ZS3 Server infrastructure, the bridge that makes your Blimp allocation accessible using traditional S3-compatible tools like AWS CLI and MinIO CLI.
ZS3 (Zus S3) is a decentralized, S3-compatible object storage solution that operates on the Züs blockchain network. It ensures:
Full data sovereignty and ownership
Redundancy and geographic distribution across blobbers
Blockchain-verified audit trails through Write Markers
Optimized security with optional data encryption and compression
ZS3 Server acts as a gateway, translating standard S3 requests into operations that are compatible with Züs decentralized storage via GoSDK.
Important: Each Blimp allocation should have its own ZS3Server deployment to guarantee isolation, performance, and security.
Core Components of ZS3 Server
Component
Description
MinIO Gateway
Receives and interprets standard S3 REST API calls.
ZS3 Cache
Buffers incoming operations (uploads, deletions) to optimize blockchain transactions.
GoSDK Adapter
Bridges the operations to the Züs network, committing updates using blockchain write markers.
Blobbers
Actual decentralized storage nodes storing encrypted data shards.
LogSearch API
Collects operational and audit logs from ZS3 for monitoring and recovery.
Step-by-Step ZS3 Server Deployment via Blimp UI
Step 1: Sign Up and Fund Wallet (Pre-requisite)
Ensure your wallet is active, funded with ZCN, and associated with a valid mnemonic.
Step 2: Create a New S3-Compatible Allocation
Click Create New Allocation
Fill in allocation details:
Size (e.g., 10 GB, 100 GB)
Preferred blobbers (automatic or manual selection)
Confirm and complete payment via ZCN or linked MetaMask wallet.
Step 3: Generate ZS3 Deployment Script
After allocation creation:
Click Deploy S3 Server
Provide your public IP address if prompted (important if behind firewall/NAT)
Click Generate Script
The output script will:
Set environment variables (access key, secret key, wallet ID)
Download and configure the MinIO gateway linked to your allocation
Configure the ZS3 server to use your allocation ID
Step 4: Execute the Deployment Script
On your target server (Linux preferred):
Upon success, you’ll receive an endpoint such as:
This is your live S3-compatible endpoint.
Step 5: Secure and Monitor Deployment
Confirm ports (443/80) are open
Save your access key and secret key securely
(Optional) Enable SSL certificates if required for production
Check deployment status using provided logs or via the Blimp UI "Conduct Operations" tab
Understanding the ZS3 Data Flow
Client issues standard S3 API call (upload/download)
MinIO Gateway parses the request
ZS3 Cache batches changes
GoSDK validates, signs, and submits changes to the Züs network
Blobbers store shards redundantly and securely
Blockchain records every change through Write Markers ensuring immutability
Encryption and Compression Settings (Highly Recommended)
Modify your ZS3 configuration file located at ~/.zcn/zs3server.json
:
Encrypt: Ensures that files are encrypted client-side before hitting any storage blobber.
Compress: Reduces data size to optimize storage cost and network usage.
Admin Functions and Disaster Recovery
Logsearch API: Running on port 8080 by default. Query operational logs using WebSockets or simple HTTP GET.
Disaster Recovery: Configure secondary ZS3 Server. Use MinIO's
mc mirror
command to sync primary to secondary instances:
This protects your data if the primary server fails or needs replacement.
Using AWS CLI with ZS3
The AWS Command Line Interface (AWS CLI) can be easily configured to interact with your ZS3 Server endpoint, allowing you to perform traditional S3 operations such as creating buckets, uploading files, downloading objects, listing contents, and more.
This section walks through configuring AWS CLI and demonstrates essential operations using ZS3.
AWS CLI is a widely adopted tool for cloud storage interactions. Using it with ZS3 ensures developers and sysadmins can leverage familiar workflows while benefiting from decentralized storage.
No custom clients or SDKs needed; just point the CLI to your ZS3 endpoint.
Prerequisites
Access Key and Secret Key from your deployed ZS3 server (available under "Using CLI" in Blimp S3 allocation)
ZS3 Server endpoint (e.g.,
https://blimp7fyct.zus.network
)
Ensure you have access to the CLI credentials before proceeding.
Configuring AWS CLI for ZS3
Run:
You will be prompted:
AWS Access Key ID [None]:
<your-access-key>
AWS Secret Access Key [None]:
<your-secret-key>
Default region name [None]:
us-east-1
Default output format [None]:
<press ENTER>
Note:
The "region" field is mandatory but irrelevant for ZS3 operations. Use any valid region like
us-east-1
.Default output format can be left blank or set to
json
.
Important: Using the --endpoint-url
Parameter
--endpoint-url
ParameterWhen operating with ZS3, you must always specify your custom endpoint.
Example Base Format:
If omitted, AWS CLI will default to Amazon S3 and fail the request.
Performing File Operations with AWS CLI
Create a New Bucket
Expected Output:
Upload a File
Expected Output:
Download a File
List Buckets
List Objects in a Bucket
Delete a File
Authorizing New Users (Advanced)
In addition to the admin credentials, you may want to create additional users for your ZS3 server. This can be accomplished via the Admin API.
Add a New User Command:
Replace placeholders accordingly.
Successful response:
Once the new user is added, you can reconfigure your AWS CLI profile using their credentials to access the S3-compatible bucket.
Error
Cause
Solution
InvalidAccessKeyId
Wrong Access Key used
Verify the Access Key ID matches what's generated in Blimp.
SignatureDoesNotMatch
Incorrect Secret Key
Re-check the Secret Key and reconfigure.
NoSuchBucket
Bucket doesn't exist
Confirm spelling or list existing buckets first.
AccessDenied
Incorrect permissions or wrong keys
Check if user is authorized.
Using MinIO CLI (mc) with ZS3
The MinIO Client (mc
) is a powerful tool that offers an advanced S3-compatible command-line experience. It supports operations such as uploading files, downloading objects, creating buckets, listing buckets, copying, mirroring, and managing S3-compatible storage endpoints.
In this section, you will learn how to install and configure mc
to work seamlessly with your ZS3 server and perform everyday file operations.
Prerequisites
MinIO CLI (
mc
) installed on your machine (Official Download Guide).Access Key, Secret Key, and Endpoint URL from your ZS3 deployment.
Installing MinIO CLI
For Linux:
For macOS using Homebrew:
Configuring mc with ZS3 Server
Set an alias to your ZS3 endpoint:
Where:
zcn
= the shortcut name you assign to your ZS3 serverReplace
<access-key>
,<secret-key>
, and endpoint URL appropriately.
Successful setup will output:
You can list all configured aliases:
Performing File Operations with mc
Create a New Bucket
Output:
Upload a File
Upload a Directory Recursively
Useful for uploading a full directory structure in one shot.
List Buckets
List Objects inside a Bucket
Download a File
Remove a File
Remove a Bucket
The --force
flag is needed to remove a non-empty bucket.
Advanced Operations
Sync/Mirror Data
Sync local directory to ZS3:
Sync ZS3 bucket to another local directory:
View Object Metadata
This shows object size, last modified time, ETag, and content type.
Verifying Uploads on Blimp UI
Go to the Blimp Dashboard.
Select your allocation.
Use the "Conduct Operations" menu.
List buckets and verify object presence.
Objects uploaded via
mc
should appear immediately.
Handling Common Errors with mc
Error
Cause
Solution
Access Denied
Wrong credentials or missing permissions
Verify Access/Secret keys and user permissions.
NoSuchBucket
Bucket not created yet
Ensure the bucket exists before uploading.
Signature Mismatch
Incorrect API version used
Always set --api S3v2
during alias creation.
Always encrypt sensitive uploads using ZS3 encryption settings. Use mc mirror
for efficient large-scale backup and disaster recovery setups.
Monitor network bandwidth during large mirror
operations to optimize scheduling. Script repetitive tasks with bash scripts using mc
for automation.
Backup Tool Integrations with Restic and Veeam
This section explains how to integrate your ZS3 server-backed storage with powerful backup tools like Restic (open-source backup utility) and Veeam (enterprise-grade backup platform). This ensures secure, decentralized, and redundant data protection strategies.
Using Restic with ZS3
Restic is an efficient, secure, and easy-to-use backup tool that supports S3-compatible storage backends.
Prerequisites
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from your ZS3 deployment
ZS3 endpoint URL (e.g.,
https://blimp7fyct.zus.network
)
Installing Restic
For Ubuntu:
For macOS using Homebrew:
Configuring Environment Variables
Set the necessary environment variables for Restic to authenticate with ZS3:
You can add these exports to your ~/.bashrc
or ~/.zshrc
file to load them automatically.
Initializing the Restic Repository
Expected Output:
Performing Backups
Backup a local directory:
Output example:
Listing Backup Snapshots
Example Output:
Restoring from Backup
Restore the latest snapshot:
Scheduling Restic Backups
You can automate regular backups with a cron job:
Example entry (daily at midnight):
Using Veeam with ZS3
Veeam is a widely trusted enterprise backup solution, compatible with S3 object storage like ZS3.
Prerequisites
Veeam Backup & Replication installed (v11 or later recommended)
Access to your ZS3 credentials and endpoint
Adding ZS3 as an Object Storage Repository
Step 1: Launch Veeam
Open Veeam Backup & Replication console.
Navigate to Backup Infrastructure > Backup Repositories > Add Repository.
Select Object Storage > S3 Compatible.
Step 2: Enter ZS3 Endpoint and Region
Service Point:
https://blimp7fyct.zus.network
Region:
us-east-1
(or any other placeholder; ZS3 does not enforce regions)
Step 3: Add Access Key and Secret Key
Click "Add" next to Credentials.
Input the Access Key and Secret Key from your Blimp deployment.
Step 4: Select the Bucket
Choose your allocated bucket.
Optionally create a new folder inside the bucket (e.g.,
/VeeamBackups
).
Step 5: Enable Immutability (Optional)
Check the "Make recent backups immutable" box to prevent accidental deletion or ransomware attacks.
Step 6: Finalize Setup
Name your object storage repository (e.g.,
Blimp ZS3 Backup
)Finish the setup wizard.
Your ZS3 repository will now appear under Veeam's Object Storage Repositories list.
Creating Backup Jobs Targeting ZS3
Set up standard backup jobs.
Use your ZS3 object repository as the target.
Configure retention, backup frequency, and application-aware options as needed.
Troubleshooting & Logs
Even with the best setup, users may occasionally encounter issues. This section highlights common troubleshooting scenarios, log access methods, and diagnostic tips to ensure smooth operation of your Blimp allocation and ZS3 server.
Common Issues and Resolutions
Problem
Cause
Solution
InvalidAccessKeyId
Incorrect Access Key or missing configuration
Reconfigure your CLI settings; verify the key in Blimp UI.
SignatureDoesNotMatch
Incorrect Secret Key, wrong API version, or time drift
Ensure you set --api S3v2
for MinIO. Check system clock (NTP sync).
NoSuchBucket
Referencing a non-existent bucket
List existing buckets with mc ls zcn/
or aws s3 ls
and verify names.
AccessDenied
Invalid user permissions or expired credentials
Use correct keys. Refresh credentials if expired.
Slow Uploads/Timeouts
Large files, network instability, small cache size
Enable compression, use multipart uploads, optimize cache settings.
Unable to Deploy ZS3 Server
Wrong IP address or firewall blocking ports
Ensure port 443 and 80 are open. Provide correct public IP when generating deployment script.
API Connection Refused
Deployment not completed properly or wrong endpoint
Recheck script execution and confirm endpoint URL matches deployment output.
CLI-Specific Issues
AWS CLI
Always append
--endpoint-url https://your-zs3-endpoint
to each command.Ensure
us-east-1
(or dummy region) is provided during configuration.Credentials should match those visible in Blimp's "Using CLI" section.
MinIO CLI (mc)
Confirm
--api S3v2
is specified when setting aliases.Use exact bucket/object names respecting case sensitivity.
Use
mc alias list
to verify endpoint configuration.
Restic
Ensure environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, RESTIC_REPOSITORY) are exported.
Initialize repository once before running backups.
Use
restic forget
to prune old snapshots if needed.
Accessing ZS3 Server Logs
The ZS3 Server automatically deploys a Logsearch API service to help monitor storage operations and troubleshoot problems.
Where to Find Logs
Default on port 8080 of the ZS3 server.
If the server IP is
192.168.1.50
, access:
Types of Logs Available
MinIO Audit Logs: Track every API request made to the ZS3 gateway.
Allocation Write Markers: Confirm successful blockchain commits.
Upload/Download Errors: View recent errors related to storage transactions.
Sample API Query to Fetch Logs
Response will return JSON format logs for easy parsing or export.
Logsearch API Parameters (Optional Advanced Use)
You can query logs with additional filters:
?type=error
→ Fetch only error logs?bucket=mybucket
→ Filter by bucket name?operation=PUT
→ Filter by upload events
Example filtered query:
Diagnosing Slow Performance
If you experience slow uploads or downloads:
Check network latency and bandwidth to ZS3 server.
Enable compression in
.zcn/zs3server.json
to reduce upload size.Increase local cache size settings in the server config.
Use multipart uploads (
mc mirror
andaws s3 sync
auto-handle this).Split large file uploads into smaller batches.
Last updated