> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/system-overview/storage/zs3-server/backup-and-recovery-with-restic-on-blimp-+-zs3-server.md). # Backup & Recovery with Restic on Blimp + ZS3 Server In this guide, we’ll show you how to leverage **Blimp’s** intuitive UI alongside the **ZS3 Server** S3-compatible gateway to build a robust, versioned backup and recovery pipeline for your business. **Blimp** lets you spin up and manage Züs allocations with a few clicks, while **ZS3 Server** translates those allocations into standard S3 endpoints—so you can keep using your favorite tools (AWS CLI, MinIO Client, Restic, etc.) without learning anything new. By combining ZS3 Server’s decentralized, blockchain-anchored storage with Restic’s source-dedupe, encryption, and versioning, Blimp delivers an enterprise-grade backup solution that is **standards-based** (S3 API), **auditable, performant, and cost-effective.** This solution would be helpful for small-to-mid-size businesses and enterprises running Linux servers that need daily, off-site backups. {% hint style="info" %} Prerequisite: * Have an active Blimp account. If you don't have one yet, sign up [here](https://www.blimp.software/authentication). Check out our docs on how to go through the registration [here](https://docs.zus.network/zus-docs/webapps/blimp/login-register) * Public-facing Linux server : A VM or bare-metal box (Ubuntu 22.04+, Debian, CentOS, etc.) with a public IP , SSH access, and ports 80/443 open * Basic command-line skills {% endhint %} ## Create an S3 Allocation **Step 1: Navigate to the S3 Tab** * Open the Blimp UI and navigate to the **S3** tab. Click on the **Create New Allocation** button to start the process of setting up a new allocation.

**Step 2: Fill in Allocation Details** * In the form that appears, enter the required details about your allocation. * Once all fields are completed, click the **Confirm** button to proceed.

{% hint style="info" %} All Blobber types can use USD for payment. If you want to pay in ZCN, you must select "All Blobbers" or "Unbranded". {% endhint %} **Step 3: Select Storage Providers** * By default, Blobbers are automatically chosen based on geodiversity. Optionally, manually select up to five sharded providers if needed. * After finalizing your provider selection, click on the **Pay with USD** button. Or if you want to pay in ZCN, click the text "Pay with ZCN" located to the right of the header.

**Step 4: Complete Payment (in ZCN)** * You can pay using ZCN from your existing balance. If you do not have sufficient ZCN in your wallet, you have the option to purchase more ZCN by connecting your Metamask or Coinbase wallet.

Upon successful payment, the allocation with be created. *** ## Deploy your Blimp ZS3 Gateway #### Step 0: Have Access to a Public-facing Linux Server * Your ZS3 gateway needs to run on a machine that: * **Has a publicly reachable IP** * **Runs a Linux distro** (Ubuntu, Debian, CentOS, Amazon Linux, etc.) * **Allows SSH access** on port 22 (for deploying the script) * **Has ports 80 & 443 open** (so Caddy can obtain and serve TLS certificates) * **Has Key Pairs** to enable access into SSH **Firewall rules for HTTP(S)**

Direction	Protocol	Port Range	Source	Purpose
Inbound	TCP	22	YOUR·IP/32	SSH (from your location)
Inbound	TCP	80	0.0.0.0/0, ::/0	HTTP (for ACME HTTP-01)
Inbound	TCP	443	0.0.0.0/0, ::/0	HTTPS (Caddy + S3 gateway)
Outbound	ALL	ALL	0.0.0.0/0, ::/0	Allow your instance to reach the Internet for Docker pulls, ACME, etc.

* In this example, we use an AWS EC2 Instance: * AMI: Ubuntu Server 22.04 LTS (HVM) * Instance: t3.medium (2 vCPU, 4GB RAM) * Storage: 20 GiB root + 50–100 GiB gp3 data volume #### Step 1: Identify your IP address * Find your server's IP address. In AWS, go to the EC2 Instance Dashboard. Select the instance you are using and look for the Public IPv4 address in your Details>Instance Summary.

**Step 2: Generate the Script** * Click "Manage Allocations". Find the allocation you would like to work with and click the ellipses at the last column of your allocation row. Once drop down opens, click "Setup".

* Enter your server's IP address in the provided field within the Blimp UI. Click on the **Generate Script** button.

* A modal will then pop out to set the password for the S3 deployment. This will be used to access your Blimp S3 server allocation

{% hint style="warning" %} Note you cannot use special characters in this password. It will cause future errors such as : "The request signature we calculated does not match the signature you provided. Check your key and signing method." {% endhint %} **Step 3: Execute the Script** * Start by accessing your server using your key pair .pem or .ppk file. As an example, you can ssh into your terminal by typing: ``` ssh -i ~/.ssh/yourkey.pem ubuntu@your-ec2-public-ip ``` * Once inside, copy the cURL Script from the S3 server setup page. Looks something like this:

curl -fSsL https://raw.githubusercontent.com/0chain/zcnwebappscripts/main/blimp.sh | sed 's/0chainminiousername/<blimp-username>/; s/0chainminiopassword/MySecretPa55word/; s/0chainallocationid/<s3-allocation-id>/; s/0chainblockworker/https:\/\/mainnet.zus.network\/dns\//; s/0chainminiotoken/12345/; s/blimpdomain/blimp8fbfl.zus.network/; s/0chainwalletid/<wallet-id>/; s/0chainwalletpublickey/<public-key>/; s/0chainwalletprivatekey/<private-key>/; s/0chainmnemonics/<mnemonic-if-not-using-split-key>/ '| bash

Fig10. S3 Server Setup after Script Generation

* Run the script on your server terminal

Once the script runs successfully, Blimp will automatically detect your server and guide you to the next step. {% hint style="danger" %} If you clear your browser cache (or use private/incognito mode) and click **Setup** again for the same allocation, Blimp will generate a brand-new deployment script. That script won’t match your existing ZS3 Server, so you’ll have to run it again on your host and effectively redeploy the gateway. **Tip:** Only run **Setup** once per allocation—unless you *want* to reset and redeploy your server. {% endhint %} #### Step 4: Create a Bucket * **Create a Bucket**: Select **Create Bucket** from the **Type of Request** menu.

* Enter your desired bucket name. Click on **Run cURL Request**.

* The response will be displayed in the right-hand panel.

* **List Existing Buckets**: Choose **Buckets** from the **List Operations** section under the **Type of Request** menu. Click on **Run cURL Request** to view the list of buckets.

By completing this step, you have successfully deployed the ZS3 server, created the S3-compatible allocation, and performed basic S3 operations. To learn more about the ZS3 server, check out the docs [here](https://docs.zus.network/zus-docs/system-overview/storage/zs3-server#zs3-feature-flow). {% hint style="warning" %} **Note:** The ZS3 gateway embeds your wallet credentials when you deploy it. If you later add that wallet to Vault for split-key management (or make any other change to it), your existing cURL/API credentials will no longer match and requests will fail. To fix this, simply go back to the allocation "setup", regenerate the deploy script, and run it again so the gateway picks up your updated wallet. {% endhint %} *** ## Extract Blimp ZS3 Server Endpoint {% embed url="" %} Tutorial 2: Extract Endpoint from Blimp-generated Script {% endembed %} When you generate and execute the deployment script using Blimp, it provides an endpoint URL for accessing your deployed ZS3 server. This endpoint is dynamically configured within the `curl` command. Going back to the script you used to deploy the ZS3 server, the script includes various parameters such as authentication credentials, location IDs, and domain configurations. In the provided example, the executed command is: {% code overflow="wrap" %} ``` curl -fSsL https://raw.githubusercontent.com/0chain/zcnwebappscripts/main/blimp.sh | sed 's/0chainminiousername//; s/0chainminiopassword/MySecretPa55word/; s/0chainallocationid//; s/0chainblockworker/https:\/\/mainnet.zus.network\/dns\//; s/0chainminiotoken/12345/; s/blimpdomain/blimp8fbfl.zus.network/; s/0chainwalletid//; s/0chainwalletpublickey//; s/0chainwalletprivatekey//; s/0chainmnemonics// '| bash ``` {% endcode %} In your cURL code, look for the "blimpdomain". ``` s/blimpdomain/blimp8fbfl.zus.network/; ``` This indicates that `blimp8fbfl.zus.network` is the assigned ZS3 endpoint for your deployed ZS3 instance. *** Restic is an open-source, cross-platform CLI tool that creates encrypted, deduplicated snapshots of local files and stores them on S3-compatible backends. In this section, we will use Restic to initialize a repository on our Blimp + ZS3 Server endpoint, run daily backups of our server data, and demonstrate restoring from those snapshots. ## Backup with Restic ### Step 1: Install Restic To get started, make sure you are still within your Linux server. Using the terminal, we will update your `apt` function then install `restic` for your current OS release: ``` sudo apt update -y sudo apt install restic -y ``` Afterwards, download the newest official Restic binary from GitHub. It will verify its signature and replace the `/usr/bin/restic` with the fresh build: ``` sudo restic self-update ``` The output should look like this : ``` Output writing restic to /usr/bin/restic find latest release of restic at GitHub latest version is 0.19.0 download SHA256SUMS download SHA256SUMS.asc GPG signature verification succeeded download restic_0.18.0_linux_amd64.bz2 downloaded restic_0.18.0_linux_amd64.bz2 saved 29765816 bytes in /usr/bin/restic successfully updated restic to version 0.18.0 ``` When seeing "successfully updated restic to version x.xx.x", you have properly installed `restic`. ### Step 2: Get Environment Variables The ACCESS\_KEY is your blimp username and the SECRET\_KEY is the password recorded when generating the deployment script. \ If you do not recall them, you can go back to the "Conduct S3 operations" page and look at your "Using CLI" cURL. It may look something like this: {% code overflow="wrap" %} ``` curl -X GET https://blimp8fbfl.zus.network/minioclient/?action=listBuckets&accessKey=rikachet&secretAccessKey=MySecretPa55word ``` {% endcode %}

Fig16. Location of cURL in Conduct S3 Operations page

At the end of the cURL you can see two items: * accessKey = rikachet ---> ACCESS\_KEY * secretAccessKey = MySecretPa55word ---> SECRET\_KEY You can extract your ACCESS\_KEY and SECRET\_KEY from here. ### Step 3: Set Environment Variables Inside of your server terminal, or in this case the AWS EC2 instance, run each line separately: ``` export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= export RESTIC_REPOSITORY="s3:https:///" ## An example of what it could look like ## export AWS_ACCESS_KEY_ID=rikachet export AWS_SECRET_ACCESS_KEY=MySecretPa55word export RESTIC_REPOSITORY="s3:https://blimp8fbfl.zus.network/s3-backup-recovery" ``` ### Step 4: Initialize the Repository To initiate a new restic repository, use: ``` restic init ``` Following this, you will be prompted to create a password. Note, this will be your password for RESTIC\_PASSWORD and will be used to access your repository. When completed, you will see: ``` Output created restic repository XXXXXXXXXX at s3:https:/// ``` {% hint style="warning" %} Please note that knowledge of your restic password is required to access the repository. Losing your password means your data is irrecoverably lost. {% endhint %} ### Step 5: Run a Backup To run a back up for a specific directory on your server, you will need your blimp endpoint and the path to your directory you would like to back up. ``` restic -r s3:https:/// --verbose backup ``` If successfully backed up, you will see a similar output as the following: ``` Output ... processed X files, XXX MiB in X:XX snapshot 2a6902ec saved ```

Fig17. Terminal Output when Backup Completes

You can also check your blimp allocation for the snapshot by going into your s3 allocation "Home" > your bucket > snapshots. You should be able to see your snapshots here.

Fig18. Snapshot Folder in Blimp S3 Allocation

{% hint style="info" %} If you cannot see the folders for your S3 Allocation, go to "Manage Allocations" and make sure your desired allocation is "Selected". Click "Select" button if not selected. {% endhint %} ### Step 6: List Snapshots To check your snapshots through your server terminal, you can run this: ``` restic -r s3:https:/// snapshots ``` Paste your restic password. Once the script is complete, you may see an output like this:

### Step 7: Automate via Crontab (Optional) Create a small wrapper script (e.g. /home/ubuntu/run-restic-backup.sh) :

#!/bin/bash
set -euo pipefail

# Environment
export AWS_ACCESS_KEY_ID=<Access-Key>
export AWS_SECRET_ACCESS_KEY=<Secret-Key>
export RESTIC_REPOSITORY="s3:https://<endpoint>/<bucket>"
export RESTIC_PASSWORD='your-restic-password'

# Backup command
/usr/bin/restic backup /home/ubuntu/test-files

Make it executable: ``` chmod +x /home/ubuntu/run-restic-backup.sh ``` Edit your crontab: ``` crontab -e ``` Add this line to run it at 2 AM daily : ``` 0 2 * * * /home/ubuntu/run-restic-backup.sh ``` {% hint style="info" %} Feel free to set a specific time and date for your cron job(s). Also, adjust the time according to the timezone of your server. {% endhint %} Verify your crontab: ``` crontab -l ``` The output should show your crontab entries. ### Step 8: Restore Snapshot If you want to restore your latest snapshot saved in blimp, run this line: ``` restic \ -r s3:https:/// \ --verbose \ restore latest \ --target ``` The output should look similar to this : ``` Output repository 3f44df87 opened (version 2, compression level auto) [0:00] 100.00% 1 / 1 index files loaded restoring snapshot 2a6902ec of [/home/ubuntu/test-files] at 2025-04-29 21:02:01.044981857 +0000 UTC by ubuntu@ip-172-31-15-36 to /home/ubuntu/restore-test Summary: Restored 7 files/dirs (113.679 MiB) in 0:02 ``` *** That is it! Congrats on backing up and recovering with Restic on Blimp and ZS3 Server! If you're interested in using Veeam for backup instead, check out the steps [here](https://docs.zus.network/zus-docs/system-overview/storage/zs3-server/configuring-veeam-backup-with-zus-s3-zs3)!