# 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: * ZS3 Server Concept & Usage: ### 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](https://github.com/0chain/zwalletcli) — for wallet creation, funding, and recovery * [zboxcli](https://github.com/0chain/zboxcli) — for managing allocations and performing file operations * [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) — for interacting with ZS3 using S3 API * [mc (MinIO client)](https://min.io/docs/minio/linux/reference/minio-mc.html) — CLI for file management on S3-compatible endpoints * [Restic](https://restic.readthedocs.io/) — 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](https://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](https://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`** ```bash git clone https://github.com/0chain/zboxcli.git cd zboxcli make install ``` **Install `zwalletcli`** ```bash 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`: ```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: ```bash ./zwallet recoverwallet --wallet zus_wallet.json --mnemonic "your twenty four word mnemonic" ``` Verify wallet creation: ```bash cat ~/.zcn/zus_wallet.json ``` You should see: ```bash {"client_id":"","client_key":"","keys":[{"public_key":"","private_key":""}],"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: ```bash ./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** ```bash ./zbox upload --localpath /My/path/file.png --remotepath / --allocation --wallet zus_wallet.json ``` **Download a File** ```bash ./zbox download --remotepath /file.png --localpath /Downloads --allocation --wallet zus_wallet.json ``` **Update a File** ```bash ./zbox update --localpath /My/path/newdata.txt --remotepath /data.txt --allocation --wallet zus_wallet.json ``` **Upload Multiple Files via JSON** Create a JSON file (e.g., `multi-upload.json`) with this format: ```json [ { "remotePath": "/", "filePath": "/My/local/cat.png", "fileName": "cat.png", "encrypt": false }, { "remotePath": "/", "filePath": "/My/local/pikachu.webp", "fileName": "pikachu.webp", "encrypt": false } ] ``` Upload with: ```bash ./zbox upload --multiuploadjson /My/local/multi-upload.json --remotepath / --allocation --wallet zus_wallet.json ``` Each upload will be confirmed via terminal output indicating upload status and content type. To verify uploads, you can use: ```bash ./zbox listrefs --allocation --wallet zus_wallet.json ``` You may also check file presence and metadata in the Blimp web UI by navigating to your allocation dashboard. {% content-ref url="/pages/xrFyLiQzPBChg5OCEFJW" %} [CLIs](/zus-docs/clis.md) {% endcontent-ref %} ### 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](https://blimp.software). 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): ```bash 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: ```bash 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`: ```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: ```bash ./mc mirror secondary// primary// --summary ``` This protects your data if the primary server fails or needs replacement. {% content-ref url="/pages/K3yu6G7GUvjwIM8Ezusn" %} [Launching ZS3 Server](/zus-docs/webapps/blimp/launching-zs3-server.md) {% endcontent-ref %} ### 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](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)) * **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: ```bash aws configure ``` You will be prompted: * **AWS Access Key ID \[None]:** `` * **AWS Secret Access Key \[None]:** `` * **Default region name \[None]:** `us-east-1` * **Default output format \[None]:** `` **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: ```bash aws --endpoint-url https:// s3 ``` If omitted, AWS CLI will default to Amazon S3 and fail the request. #### Performing File Operations with AWS CLI **Create a New Bucket** ```bash aws --endpoint-url https://blimp7fyct.zus.network s3 mb s3://mybucketname ``` Expected Output: ```bash make_bucket: mybucketname ``` **Upload a File** ```bash aws --endpoint-url https://blimp7fyct.zus.network s3 cp ./localfile.txt s3://mybucketname ``` Expected Output: ```bash upload: ./localfile.txt to s3://mybucketname/localfile.txt ``` **Download a File** ```bash aws --endpoint-url https://blimp7fyct.zus.network s3 cp s3://mybucketname/localfile.txt ./downloadedfile.txt ``` **List Buckets** ```bash aws --endpoint-url https://blimp7fyct.zus.network s3 ls ``` **List Objects in a Bucket** ```bash aws --endpoint-url https://blimp7fyct.zus.network s3 ls s3://mybucketname ``` **Delete a File** ```bash 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:** ```bash curl -X POST "https://blimp7fyct.zus.network/minioclient/admin?action=addUser&userAccessKey=newuser&userSecretKey=NewStrongPass123&accessKey=adminuser&secretAccessKey=AdminSecret" ``` * Replace placeholders accordingly. * Successful response: ```bash {"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: ```bash 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: ```bash brew install minio/stable/mc ``` #### Configuring mc with ZS3 Server Set an alias to your ZS3 endpoint: ```bash mc alias set zcn https://blimp7fyct.zus.network --api S3v2 ``` Where: * `zcn` = the shortcut name you assign to your ZS3 server * Replace ``, ``, and endpoint URL appropriately. Successful setup will output: ``` Added `zcn` successfully. ``` You can list all configured aliases: ```bash mc alias list ``` #### Performing File Operations with mc **Create a New Bucket** ```bash mc mb zcn/mybucket ``` Output: ```bash Bucket created successfully `zcn/mybucket` ``` **Upload a File** ```bash mc cp /path/to/myfile.txt zcn/mybucket ``` **Upload a Directory Recursively** ```bash mc mirror /path/to/myfolder zcn/mybucket ``` Useful for uploading a full directory structure in one shot. **List Buckets** ```bash mc ls zcn ``` **List Objects inside a Bucket** ```bash mc ls zcn/mybucket ``` **Download a File** ```bash mc cp zcn/mybucket/myfile.txt ./localcopy.txt ``` **Remove a File** ```bash mc rm zcn/mybucket/myfile.txt ``` **Remove a Bucket** ```bash 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: ```bash mc mirror /local/dir zcn/mybucket ``` Sync ZS3 bucket to another local directory: ```bash mc mirror zcn/mybucket /local/dir ``` **View Object Metadata** ```bash 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](https://restic.readthedocs.io/en/stable/020_installation.html)) * 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: ```bash sudo apt update -y sudo apt install restic -y sudo restic self-update ``` For macOS using Homebrew: ```bash brew install restic ``` **Configuring Environment Variables** Set the necessary environment variables for Restic to authenticate with ZS3: ```bash export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_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** ```bash restic init ``` Expected Output: ```bash created restic repository 12345678 at s3:https://blimp7fyct.zus.network ``` **Performing Backups** Backup a local directory: ```bash 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zus.network/zus-docs/clis/guides-and-workflows/using-cli-with-blimp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.