Starting with distroclone 1.4.10 and distroclone-backup 1.3.4, the two tools are fully interoperable on btrfs filesystems.
DistroClone can build a live ISO directly from the rootfs cache created by DistroClone Backup,
bypassing the live rsync clone step entirely.
This guide explains the technical architecture behind the feature, when to use it, and how
btrfs subvolume layout affects both tools.
Why Build from Cache Instead of Live rsync?
The standard DistroClone workflow clones the running system:
running system → rsync → /mnt/<distro>_live/rootfs/ → squashfs → ISO
This works well but has a limitation: the clone captures the system as it is
right now, including any transient state, open files, partially written logs,
and in-flight processes. If the system is in heavy use during the build, some files
may be inconsistent.
DistroClone Backup maintains a clean, versioned rootfs cache on a separate
btrfs volume. The cache is updated on a schedule (or on demand) and each version is
a stable, read-only btrfs snapshot. Building the ISO from the cache has several advantages:
- Reproducible state — the ISO reflects a known, stable snapshot, not the live system mid-use.
- Faster builds — the cache rsync only transfers changed files; the ISO build rsync copies from a local btrfs volume at memory speed.
- Safe iteration — the running system is never read during the squashfs phase, eliminating race conditions from concurrent writes.
- Offline builds — the cache can be on a dedicated partition or external drive, allowing ISO builds even on a different machine.
How DistroClone Backup Builds the Cache
DistroClone Backup stores the rootfs cache under a configurable base directory. The default path is:
/mnt/SysLinuxOS_backup/
Inside, it creates the following layout:
/mnt/SysLinuxOS_backup/├── .backup_meta ← metadata file (date, distro, size) └── .rootfs_cache/ ← btrfs subvolume (the live rsync target) └── .snapshots/ ← btrfs subvolume managed by snapper ├── 1/ │ ├── info.xml │ └── snapshot/ ← read-only btrfs snapshot of .rootfs_cache ├── 2/ │ ├── info.xml │ └── snapshot/ └── ...
.rootfs_cache is created as a btrfs subvolume, not a plain directory. This allows snapper to take read-only snapshots of it without copying data.
After each backup run, snapper creates a numbered snapshot inside .snapshots/ — a read-only point-in-time copy of the rootfs. A retention policy (default: keep last 10) prunes old snapshots automatically.
The .backup_meta file contains three fields used by DistroClone:
META_DATE="2026-06-17 14:30"
META_DISTRO="SysLinuxOS"
META_SIZE="8.2G"
How DistroClone Detects and Uses the Cache
Detection at startup
Before showing the welcome dialog, DistroClone checks for two conditions:
/mnt/SysLinuxOS_backup/.rootfs_cacheexists as a directory/mnt/SysLinuxOS_backup/.backup_metaexists and is readable
If both are true, DistroClone reads the metadata and builds a label string:
2026-06-17 14:30 | SysLinuxOS | 8.2GThis label appears in a checkbox added to the welcome YAD dialog:
[ ] Build from DCB cache (2026-06-17 14:30 | SysLinuxOS | 8.2G)If the cache is not present, the checkbox is not shown and the dialog is identical to
the standard workflow.
Step 7 — clone step bypass
When the user enables the checkbox, DistroClone sets SOURCE_MODE=cache.
Step 7 (source validation / live system check) is skipped entirely:
if [ "$SOURCE_MODE" != "cache" ] && [ "$SOURCE" != "/" ]; then
# live validation only runs in live mode
fi
Step 8 — rsync from cache
In cache mode, step 8 uses $CACHE_DIR as the rsync source instead of/. Two differences from the live rsync are notable:
| Flag | Live mode | Cache mode | Reason |
|---|---|---|---|
--one-file-system | yes | no | On btrfs, --one-file-system would not prevent entering btrfssubvolumes anyway (same device ID). The flag is omitted in cache mode because the source is already a filtered, standalone rootfs — not the running system with mounted virtual filesystems. |
--exclude=$LIVE_DIR | yes | no | The live build directory (/mnt/<distro>_live/) exists only on therunning system, not in the cache. |
The cache rsync excludes btrfs-specific paths to avoid carrying subvolume metadata into the ISO:
--exclude=/.snapshots
--exclude=/.snapshots/*
--exclude=/@.rollback-bak-*
Standard exclusions still apply: /dev, /proc, /sys,/run, /tmp, /mnt, /home,/root, /var/log, apt caches, etc.
btrfs Subvolume Layout and Interoperability
A typical SysLinuxOS btrfs installation uses the following subvolume layout:
btrfs root (top-level, subvolid=5) ├── @ ← mounted at / ├── @home ← mounted at /home └── .snapshots ← snapper snapshots of @/mnt/SysLinuxOS_backup/ (separate btrfs volume or subvolume) └── .rootfs_cache/ ← subvolume, rsync target └── .snapshots/ ← subvolume, snapper config "distroclone-backup" ├── 1/snapshot (read-only) ├── 2/snapshot (read-only) └── ...
Why rm -rf fails on the cache
rm -rf /mnt/SysLinuxOS_backup/ fails with Read-only file system
because the btrfs read-only snapshots inside .snapshots/N/snapshot/ cannot
be deleted by the kernel’s unlink path — only btrfs subvolume delete can
remove them.
The correct deletion order:
# 1. Delete each read-only snapshot leaf
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots/1/snapshot
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots/2/snapshot
# ... repeat for each numbered snapshot
# 2. Delete the .snapshots subvolume itself
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache/.snapshots
# 3. Delete the .rootfs_cache subvolume
sudo btrfs subvolume delete /mnt/SysLinuxOS_backup/.rootfs_cache
# 4. Now rm -rf works on the remainder
sudo rm -rf /mnt/SysLinuxOS_backup/
DistroClone Backup’s Delete Cache button (v1.3.4+) handles both snapshot
formats automatically — snapper-style numbered directories (N/snapshot) and
the legacy flat format (@YYYY-MM-DD_HH:MM).
Typical Workflow
A complete cycle using both tools together:
- Run DistroClone Backup — Full Backup
Creates/mnt/SysLinuxOS_backup/.rootfs_cache/via rsync clone of the
running system. On btrfs, snapper creates snapshot1/snapshot. - Run DistroClone Backup — Incremental Backup (optional)
Updates the cache with changes since the last run. Snapper creates the next numbered
snapshot. Previous snapshots remain for rollback. - Launch DistroClone
The welcome dialog detects the cache and shows the checkbox with the cache metadata.
Enable Build from DCB cache. - DistroClone builds the ISO from the cache
Step 7 (live validation) is skipped. Step 8 rsyncs from/mnt/SysLinuxOS_backup/.rootfs_cache/. All subsequent steps
(chroot config, Calamares setup, squashfs, GRUB, ISO assembly) run normally. - Test and distribute the ISO
The resulting ISO is a clean, reproducible snapshot of the system at the time of
the last backup run.
Requirements
- btrfs filesystem on the backup destination (required for snapper versioning; ext4/xfs falls back to plain rsync without snapshots)
- snapper installed and configured by DistroClone Backup (
sudo apt install snapper btrfs-progs) - DistroClone Backup v1.3.0 or later (snapper integration)
- DistroClone v1.4.10 or later (build-from-cache feature)
- At least 4–6 GB free space under
/mntfor the ISO build working directory
Installation
Both packages are available from the SysLinuxOS APT repository:
curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh | sudo bash
sudo apt install distroclone distroclone-backup snapper btrfs-progsOr download the .deb packages directly:
wget https://github.com/fconidi/distroClone/releases/latest/download/distroClone_1.4.10_all.deb
wget https://github.com/fconidi/distroClone-backup/releases/latest/download/distroclone-backup_1.3.4_all.deb
sudo apt install ./distroClone_1.4.10_all.deb ./distroclone-backup_1.3.4_all.debDistroClone and DistroClone Backup are part of the
SysLinuxOS toolchain — GPL-3.0-or-later — maintained by Franco Conidi aka edmond.
Further reading:
DistroClone Live ISO Builder ·
DistroClone Backup & Restore ·
SysLinuxOS APT Repository
