[Tutorial] ZimaOS Backup and Restore using USB drive (Shared by @gelbuilding)

Insight & Feedback
,
1

This tutorial and script are written by our MOD @gelbuilding. Welcome to test it in the test environment, and give us the feedback.

Zima System Restore to USB (Complete Tutorial + Suggestion for Integration)

I’ve read many posts across the forum where users were asking for a proper system-level restore method or struggling after a bad update, system corruption, or reinstall. Because of that, I put together a complete and safe method for backing up and restoring the ZimaOS system disk to a USB device.

This lets users create a 1:1 clone of the OS disk that can be restored in minutes on ZimaBlade, ZimaCube, Proxmox, or bare metal.

It also avoids touching DATA disks, which ZimaOS will re-mount automatically after restoration.

This tutorial now includes everything needed: correct USB mounting, device verification, ZimaBlade onboard eMMC support, optional checksum validation, and complete backup + restore commands.

1. Why Only the OS Disk Should Be Backed Up

ZimaOS is designed like modern NAS systems:

  • The OS and system partitions live on a small partition (32–64 GB)
  • All media, AppData, containers, downloads, and user files sit on DATA partition

Backing up just the OS partition:

  • Keeps the backup tiny (2–6 GB compressed)
  • Finishes in under 2 minutes
  • Avoids cloning terabytes of data
  • Restores cleanly regardless of hardware

After restoration, ZimaOS automatically re-mounts DATA partitions, other storage space, and all apps reappear instantly.

2. Safety Checks Before You Begin

Identify the OS disk and USB drive

Always confirm the correct disk to avoid overwriting the wrong one:

lsblk

# In most cases:
# ZimaCube / NVMe systems: `/dev/nvme0n1`
# ZimaBlade / onboard eMMC: `/dev/mmcblk0`
# Proxmox / SATA systems: `/dev/sda`

Check USB size

Ensure at least 8–16 GB available:

df -h /media/<USB drive>

USB formatting

ext4 is recommended for large image files.
FAT32 cannot store files above 4 GB.

Format if needed:

mkfs.ext4 /dev/sdX1

3. Creating the System Backup on USB

Step 1. Identify the USB device

lsblk

Find something like /dev/sdb1.

Step 2. Create USB mount point

mkdir -p /media/usb
mkdir -p /media/usb/backup

Step 3. Mount the USB

(This step is required)

mount /dev/sdX1 /media/usb

Verify:

mount | grep /media/usb

Step 4. Back up the OS disk

NVMe systems (ZimaCube / PC / Proxmox)

dd if=/dev/nvme0n1 bs=64M status=progress | gzip > /media/usb/backup/zimaos_system_backup.img.gz
sync

Emmc onboard storage

dd if=/dev/mmcblk0 bs=64M status=progress | gzip > /media/usb/backup/zimaos_system_backup.img.gz
sync

Step 5. Optional: verify the backup

sha256sum /media/usb/backup/zimaos_system_backup.img.gz > /media/usb/backup/backup.sha256

Later check:

sha256sum -c /media/usb/backup/backup.sha256

4. Restoring ZimaOS From USB

Step 1. Confirm USB is mounted

mount | grep /media/usb

If not:

mount /dev/sdX1 /media/usb

Step 2. Restore the system image

NVMe systems

gunzip -c /media/usb/backup/zimaos_system_backup.img.gz | dd of=/dev/nvme0n1 bs=64M status=progress

Emmc onboard storage

gunzip -c /media/usb/backup/zimaos_system_backup.img.gz | dd of=/dev/mmcblk0 bs=64M status=progress

Step 3. Reboot into the restored system

reboot

ZimaOS will return exactly to the state captured in the backup.
All DATA disks will auto-mount and all apps will reappear as before.

5. How the Commands Work

dd if=/dev/nvme0n1
Reads the entire OS disk byte-for-byte.

bs=64M
Improves performance.

status=progress
Shows live status.

gzip
Compresses the output.

sync
Flushes all pending writes to USB.

gunzip -c
Decompresses the backup image for restore.

dd of=/dev/...
Writes it back exactly as it was.

Suggestion for ZimaOS

This would be a great built-in feature for ZimaOS.
A simple UI could:

  • Detect the OS disk automatically
  • Detect and validate a USB device
  • Check available space
  • Perform the backup and compression
  • Provide a one-click restore option
  • Prevent overwriting DATA disks

This would eliminate most user errors and give ZimaOS a fast, reliable, pro-level recovery system.

3 Likes
3

+1 thx

1 Like
4

Beautiful work. Thank you @gelbuilding!

2 Likes
5

This is great work! Simple to run, and only backs up what is needed!

Thanks @gelbuilding

2 Likes
6

I think it would be a good idea to do the same thing HomeAssistant does with its backups; it’s very simple.
I’m currently backing up all of ZimaOS, and I’d like to migrate the folders to a USB drive, but it won’t let me. Is this correct?
Or should I uncheck the option to keep file versions?

image
image541×448 23.5 KB

7

What should we see as output to verify this? I Apparently did something wrong trying to do this last night. I thought I had followed all the instructions. but apparently something didn’t work right. I have a 1TB drive the OS is installed on (Bare metal) , the gz file was over 700gb, and filled up to full the boot drive. This is the exact command I ran. I see 2 problems. Problem 1 is, it didn’t backup to the thumb drive. I’m sure that is related to it not mounting and me not realizing that properly, That is on me. Problem 2 is a puzzling one to me. The SIZE of it.

This is all of the partitions on the boot drive.

nvme0n1     259:2    0 931.5G  0 disk
├─nvme0n1p1 259:3    0    32M  0 part  /mnt/boot
├─nvme0n1p2 259:4    0    24M  0 part
├─nvme0n1p3 259:5    0     6G  0 part  /
├─nvme0n1p4 259:6    0    24M  0 part
├─nvme0n1p5 259:7    0     6G  0 part
├─nvme0n1p6 259:8    0     8M  0 part
├─nvme0n1p7 259:9    0    96M  0 part  /var/lib/rauc
│                                      /var/lib/zerotier-one
│                                      /mnt/overlay
└─nvme0n1p8 259:10   0 919.3G  0 part  /var/log
                                       /var/lib/libvirt
                                       /var/lib/icewhale
                                       /var/lib/extensions
                                       /var/lib/docker
                                       /var/lib/casaos
                                       /DATA
                                       /var/lib/bluetooth
                                       /opt
                                       /media
                                       /var/lib/casaos_data

And this is the command I ran

dd if=/dev/nvme0n1 bs=64M status=progress | gzip > /media/usb/backup/zimaos_system_backup.img.gz

I think the problem was I followed the example at the top

It is a NVME system, and I should have probably had ran this command (assuming the destination was correct.

dd if=/dev/nvme0n1p1 bs=64M status=progress | gzip > /media/usb/backup/zimaos_system_backup.img.gz

Just the part that is /mnt/boot ? Or would that be the p3 one that it is 6G with just /