Using CLI with Blimp

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

1. Navigate to blimp.software. Click Sign Up for Free and choose an authentication method:

   1. Google, Apple, or Okta SSO

   2. Email and one-time password (OTP)

2. Enter your mobile number and verify it with a second OTP

3. You will now receive your wallet mnemonics — a 24-word seed phrase

4. 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.

CLIs

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

• 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

1. Client issues standard S3 API call (upload/download)

2. MinIO Gateway parses the request

3. ZS3 Cache batches changes

4. GoSDK validates, signs, and submits changes to the Züs network

5. Blobbers store shards redundantly and securely

6. 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 Server

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

• 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

When 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 server

• Replace <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

1. Go to the Blimp Dashboard.

2. Select your allocation.

3. Use the "Conduct Operations" menu.

4. List buckets and verify object presence.

5. 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 and aws s3 sync auto-handle this).

• Split large file uploads into smaller batches.