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:
zwalletcli — for wallet creation, funding, and recovery
zboxcli — for managing allocations and performing file operations
aws-cli — for interacting with ZS3 using S3 API
mc (MinIO client) — CLI for file management on S3-compatible endpoints
Restic — secure, deduplicating backup CLI tool
Veeam Backup & Replication — enterprise backup and disaster recovery solution with S3 support
Account Setup:
Blimp account created via blimp.software
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
Navigate to blimp.software. Click Sign Up for Free and choose an authentication method:
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
git clone https://github.com/0chain/zboxcli.git
cd zboxcli
make install
Install zwalletcli
git clone https://github.com/0chain/zwalletcli.git
cd zwalletcli
make install
Step 4: Add CLI Configuration
Create the required config file at ~/.zcn/config.yaml
:
block_worker: https://mainnet.zus.network/dns
signature_scheme: bls0chain
min_submit: 50
min_confirmation: 50
confirmation_chain_length: 3
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:
./zwallet recoverwallet --wallet zus_wallet.json --mnemonic "your twenty four word mnemonic"
Verify wallet creation:
cat ~/.zcn/zus_wallet.json
You should see:
{"client_id":"<id>","client_key":"<key>","keys":[{"public_key":"<pub>","private_key":"<priv>"}],"mnemonics":"word list","version":"1.0"}
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:
./zbox newallocation --size 2147483648 --lock 1.0 --data 2 --parity 2 --wallet zus_wallet.json
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
./zbox upload --localpath /My/path/file.png --remotepath / --allocation <allocation_id> --wallet zus_wallet.json
Download a File
./zbox download --remotepath /file.png --localpath /Downloads --allocation <allocation_id> --wallet zus_wallet.json
Update a File
./zbox update --localpath /My/path/newdata.txt --remotepath /data.txt --allocation <allocation_id> --wallet zus_wallet.json
Upload Multiple Files via JSON
Create a JSON file (e.g., multi-upload.json
) with this format:
[
{
"remotePath": "/",
"filePath": "/My/local/cat.png",
"fileName": "cat.png",
"encrypt": false
},
{
"remotePath": "/",
"filePath": "/My/local/pikachu.webp",
"fileName": "pikachu.webp",
"encrypt": false
}
]
Upload with:
./zbox upload --multiuploadjson /My/local/multi-upload.json --remotepath / --allocation <allocation_id> --wallet zus_wallet.json
Each upload will be confirmed via terminal output indicating upload status and content type.
To verify uploads, you can use:
./zbox listrefs --allocation <allocation_id> --wallet zus_wallet.json
You may also check file presence and metadata in the Blimp web UI by navigating to your allocation dashboard.
CLIsDeploying 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
Log in to the Blimp UI. Navigate to the S3 tab
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):
curl -fsSL https://raw.githubusercontent.com/0chain/zcnwebappscripts/main/blimp.sh | sed 's/parameters/replacements/' | bash
Upon success, you’ll receive an endpoint such as:
zs3server url ---> blimp7fyct.zus.network
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": true,
"compress": true
}
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:
./mc mirror secondary/<bucket_name>/ primary/<bucket_name>/ --summary
This protects your data if the primary server fails or needs replacement.
Launching ZS3 ServerUsing 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
AWS CLI installed (Install Guide)
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:
aws configure
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:
aws --endpoint-url https://<your-zs3-endpoint> s3 <operation>
If omitted, AWS CLI will default to Amazon S3 and fail the request.
Performing File Operations with AWS CLI
Create a New Bucket
aws --endpoint-url https://blimp7fyct.zus.network s3 mb s3://mybucketname
Expected Output:
make_bucket: mybucketname
Upload a File
aws --endpoint-url https://blimp7fyct.zus.network s3 cp ./localfile.txt s3://mybucketname
Expected Output:
upload: ./localfile.txt to s3://mybucketname/localfile.txt
Download a File
aws --endpoint-url https://blimp7fyct.zus.network s3 cp s3://mybucketname/localfile.txt ./downloadedfile.txt
List Buckets
aws --endpoint-url https://blimp7fyct.zus.network s3 ls
List Objects in a Bucket
aws --endpoint-url https://blimp7fyct.zus.network s3 ls s3://mybucketname
Delete a File
aws --endpoint-url https://blimp7fyct.zus.network s3 rm s3://mybucketname/localfile.txt
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:
curl -X POST "https://blimp7fyct.zus.network/minioclient/admin?action=addUser&userAccessKey=newuser&userSecretKey=NewStrongPass123&accessKey=adminuser&secretAccessKey=AdminSecret"
Replace placeholders accordingly.
Successful response:
{"Success":true,"AccessKey":"newuser"}
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:
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/mc
For macOS using Homebrew:
brew install minio/stable/mc
Configuring mc with ZS3 Server
Set an alias to your ZS3 endpoint:
mc alias set zcn https://blimp7fyct.zus.network <access-key> <secret-key> --api S3v2
Where:
zcn
= the shortcut name you assign to your ZS3 serverReplace
<access-key>
,<secret-key>
, and endpoint URL appropriately.
Successful setup will output:
Added `zcn` successfully.
You can list all configured aliases:
mc alias list
Performing File Operations with mc
Create a New Bucket
mc mb zcn/mybucket
Output:
Bucket created successfully `zcn/mybucket`
Upload a File
mc cp /path/to/myfile.txt zcn/mybucket
Upload a Directory Recursively
mc mirror /path/to/myfolder zcn/mybucket
Useful for uploading a full directory structure in one shot.
List Buckets
mc ls zcn
List Objects inside a Bucket
mc ls zcn/mybucket
Download a File
mc cp zcn/mybucket/myfile.txt ./localcopy.txt
Remove a File
mc rm zcn/mybucket/myfile.txt
Remove a Bucket
mc rb --force zcn/mybucket
The --force
flag is needed to remove a non-empty bucket.
Advanced Operations
Sync/Mirror Data
Sync local directory to ZS3:
mc mirror /local/dir zcn/mybucket
Sync ZS3 bucket to another local directory:
mc mirror zcn/mybucket /local/dir
View Object Metadata
mc stat zcn/mybucket/myfile.txt
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
Restic installed (Restic Installation Guide)
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:
sudo apt update -y
sudo apt install restic -y
sudo restic self-update
For macOS using Homebrew:
brew install restic
Configuring Environment Variables
Set the necessary environment variables for Restic to authenticate with ZS3:
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export RESTIC_REPOSITORY="s3:https://blimp7fyct.zus.network"
You can add these exports to your ~/.bashrc
or ~/.zshrc
file to load them automatically.
Initializing the Restic Repository
restic init
Expected Output:
created restic repository 12345678 at s3:https://blimp7fyct.zus.network
Performing Backups
Backup a local directory:
restic backup /path/to/important/data
Output example:
Files: 50 new, 0 changed, 0 unmodified
Added to the repo: 12.547 MiB
...
Snapshot 12345678 saved
Listing Backup Snapshots
restic snapshots
Example Output:
ID Time Host Tags Directory
-------------------------------------------------------------------
12345678 2024-04-01 14:00:00 myserver /important/data
Restoring from Backup
Restore the latest snapshot:
restic restore latest --target /path/to/restore
Scheduling Restic Backups
You can automate regular backups with a cron job:
crontab -e
Example entry (daily at midnight):
0 0 * * * export AWS_ACCESS_KEY_ID=... && export AWS_SECRET_ACCESS_KEY=... && export RESTIC_REPOSITORY=s3:https://blimp7fyct.zus.network && restic backup /path/to/data
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:
http://192.168.1.50:8080/logs
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
curl http://192.168.1.50:8080/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:
curl http://192.168.1.50:8080/logs?type=error&bucket=mybucket
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