[community] mabox-snapshot & mabox-persistence-usb

[muzqs]

I’m pleased to introduce 2 new tools specially created for Mabox Linux.

Mabox-Snapshot and Mabox-Persistence-Usb

(preview grub 2 kernels)

• Both tools were developed and tested on my daily-driver Mabox Linux system.
• The persistence USB tool was also tested on an old laptop.
• Once again, I found that it is best to use a USB drive whose speed matches the fastest USB port available on your computer.

Create a bootable live/install ISO from a running Mabox Linux system

mabox-snapshot

GitHub - musqz/mabox-snapshot: Create a snapshot (iso) of a mabox system.

Workflow creating a snapshot

Create a reset system ISO → save to share

This creates an ISO without preserving personal data or system changes:

mabox-snapshot create reset \  --workdir /path/to/work/dir \  --output-dir /path/to/output/dir \  --dry-run

Create a preserving system ISO → Keep this one private

This creates an ISO that preserves your system and personal data.
It contains sensitive information, encrypt it:

mabox-snapshot create preserving \  --workdir /path/to/work/dir \  --output-dir /path/to/output/dir \  --encrypt \  --dry-run

The examples above use --dry-run, which displays the actions without making changes. Remove this option when you are ready to perform the operation.

---

Create a persistent Mabox Linux USB drive from the ISO

mabox-persistence-usb

GitHub - musqz/mabox-persistence-usb: Create a persistence usb from mabox-snapshot iso

Workflow writing a persistence usb

The tool uses the entire USB drive to create a persistent Mabox Linux USB system from the ISO:

mabox-persistence-usb write /path/to/iso --dry-run

To help prevent accidentally selecting the wrong drive, the tool asks you to remove the USB drive and plug it in again. This allows it to verify that the correct device is being used. This behaviour can be flagged out.

---

This is the first release of both tools.
After testing, everything appears to be working as expected, but please let me know if you encounter any problems.
You can also create an issue on the relevant GitHub repository.

Note: This tool was developed with AI assistance and reviewed by musqz.
It is an independent project and is not an official Mabox package.

TIP: Start building the command without sudo at first.
Because then you can use <TAB> key for bash auto-complete.

$ mabox-snapshot -h
$ mabox-persistence-usb <TAB> <TAB>
$ mabox-snapshot create --help
...
...
$ mabox-snapshot excludes <TAB>
add      backups  edit     folders  -h       --help   list     remove   reset    rules

MAN

$ man mabox-snapshot
$ man mabox-persistence-usb

For creating an ISO, I use another nvme drive as --workdir to be sure to have enough work space for building the ISO.

Hope you enjoy the tools.

[napcok]

Wow! It looks like super‑useful tools for anyone who wants to create a personalized ISO or run their Mabox straight from a USB.

@muzqs, What do you think about putting both packages into the Mabox repo?
Thanks a lot for your work

[muzqs]

@napcok

putting both packages into the Mabox repo

That would be great.

Though the tools are fresh and need finetuning and more testing on bugs.

These releases are tested with the basics:
With just the basic commands one can make and create a demo or a preserved ISO, encrypted or not and write it on a usb with persistence.

• The Iso can be used in any live-creator or ventoy.
  But only this ISO can be used in the persistence tool.

• The persistence usb tool has a scaffolding to encrypt and more flags like resize space. Those are probably noise.

The persistence tool should just simply use complete disk and create a live iso and create persistence space from the empty space on the disk. Straight foreward.

It is a choose. Or we push them as is to the mabox repo.
Knowing the basics are working, but some flags(functions) are non functional.

Or wait a bit till the tools are more stabelized.

[muzqs]

Hi @napcok,

I have removed encryption and persistence space resize from mabox-persistence-usb

Encryption is done by mabox-snapshot.

The persistence tool now uses only the complete disk.

Both tools are ready for Mabox repo

[napcok]

Both packages: mabox-snapshot and mabox-persistence-usb are now available from Mabox’s repo

Thanks again @muzqs

[napcok]

Looks like amazing tool…
Tested it briefly… preserving mode… I’ve just added gnurobbo, and changed wallpaper…
Running created iso in QEMU…

[muzqs]

For your interest.

With --dry-run one can see all specs for this run.
But it is techie and not nice to read at first.

So there is --explain. As it says

–dry-run

–explain

  1. Read your live system's root filesystem (real /home, real accounts and
     passwords included), and pack it into a compressed rootfs.sfs image
     (zstd).
  2. Skip 106 exclude pattern(s) along the way (caches, logs, temp files,
     and anything on your exclude list).
  3. Encrypt rootfs.sfs with LUKS2 -- you'll be asked for a passphrase
     before the build starts. A Calamares job on the live system briefly
     remounts the unlocked source to read it, then locks it again.
  4. Build a fresh initramfs for kernel linux618 (6.18.45-1-MANJARO), so the
     ISO can boot and find its own rootfs.sfs.
  5. No custom splash image configured -- the ISO boots with GRUB's plain
     menu.
  6. Apply Mabox's own Calamares branding.
  7. Write BIOS and EFI boot images, so the ISO starts on both old and new-
     style firmware.
  8. Assemble everything into one bootable ISO file.

  mode:        preserving
  profile:     full
  source:      [rootfs] / (106 exclude pattern(s))
  kernels:     linux618 (6.18.45-1-MANJARO)
  compression: zstd
  encryption:  LUKS2 (passphrase prompted at build time)
  workdir:     /mnt/data_opslag/Mabox-Snapshots/work
  output:      /mnt/data_opslag/Mabox-Snapshots/mabox-preserving-27-08-2026-1909.iso

[muzqs]

…

Mainly esthetic, like release name fix in calamares.
To small for a release.

CHANGELOG.md

[M0nst3r]

Well, I was about to test penguins-eggs but this one looks even better.

[M0nst3r]

Trying right now the repository version, here is what I got:

error: [Errno 2] No such file or directory: '/usr/share/mabox-snapshot/calamares-branding'

Which is logic as the folder is not created during installation. If you clone directly from git the folder is there but no transferred anyway:

In a similar fashion, the /etc/mabox-snapshot/images is not created by default. Even if empty should be there. In the meantime I made it manually and copied the custom image for splash.

Regards.

Very nice tool.

[muzqs]

Thanks for the bug report. And nice you got it to work.

Working on the fix.

[muzqs]

Update: release v0.2.9

Soon in mabox repo.

1. create no longer fails when calamares is not installed on the build host. calamares is the live-ISO installer and is normally removed once Mabox is installed to disk, so most build hosts don’t have it; previously create crashed with a bare [Errno 2] No such file or directory: '/usr/share/calamares/settings.conf' (or .../calamares-branding) part way through the build. It now detects the missing installer, skips every Calamares branding/config step, and builds a live-only ISO (boots to a live session, no installer), printing a clear notice in the build summary / --explain output. doctor reports the same. Install calamares first for an installable ISO. create --encrypt still requires calamares and errors early without it – an encrypted ISO exists to be installed from, not booted live.

2. The packaged /etc/mabox-snapshot/images/ directory (drop splash.png here for a custom GRUB boot-menu background) is now created by the package instead of only being mentioned in the man page.

3. The Calamares installer’s welcome screen and window title now show the real Mabox release and codename (e.g. “Mabox Linux 26.08 Istredd”) instead of a hardcoded “1.0”. The shipped branding.desc keeps a 1.0 placeholder; create rewrites its version / versionedName strings from the build host’s /etc/lsb-release (DISTRIB_RELEASE + DISTRIB_CODENAME) at build time – Mabox’s /etc/os-release carries no version field at all, and Calamares’ own branding.desc substitution only reads os-release. Applied in both modes (reset via the overlay copy, preserving via a rendered workdir copy injected as an mksquashfs pseudo-file); falls back to the shipped placeholder if /etc/lsb-release is missing the fields. --dry-run and --explain show the resolved name.

4. create now checks for the packaged Calamares branding assets (/usr/share/mabox-snapshot/calamares-branding/) up front, before the root prompt and workdir wipe, and doctor reports on them too. A stale or partial install that was missing just that directory previously failed mid-build with a bare [Errno 2] No such file or directory; both commands now say what is wrong and that reinstalling the package fixes it.

@M0nst3r thanks for the bug report.

GitHub - musqz/mabox-snapshot: Create a snapshot (iso) of a mabox system.

[M0nst3r]

Testing the new version. It failed at this point:

-> Running build hook: [filesystems]
-> Running build hook: [keyboard]
-> Running build hook: [keymap]
==> Generating module dependencies
==> Creating xz-compressed initcpio image: '/var/lib/mabox-snapshot/work/iso/boot/initramfs-linux618.img'
-> Early uncompressed CPIO image generation successful
==> Initcpio image generation successful
mount: /var/lib/mabox-snapshot/work/iso/.efi.img.mnt: failed to set up loop device for /var/lib/mabox-snapshot/work/iso/efi.img.
Traceback (most recent call last):
File "/usr/bin/mabox-snapshot", line 8, in
sys.exit(main())
~~~~^^
File "/usr/lib/python3.14/site-packages/mabox_snapshot/cli.py", line 1184, in main
return args.func(args)
~~~~~~~~~^^^^^^
File "/usr/lib/python3.14/site-packages/mabox_snapshot/cli.py", line 666, in cmd_create
isobuild.prepare_efi_boot(iso_root, cfg.workdir)
~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.14/site-packages/mabox_snapshot/isobuild.py", line 166, in prepare_efi_boot
_build_fat_image(iso_root / "efi.img", boot_efi / "bootx64.efi", "efi/boot/bootx64.efi", efi_img_size)
~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.14/site-packages/mabox_snapshot/isobuild.py", line 127, in _build_fat_image
subprocess.run(["mount", "-o", "loop", str(dest), str(mnt)], check=True)
~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.14/subprocess.py", line 578, in run
raise CalledProcessError(retcode, process.args,
output=stdout, stderr=stderr)
subprocess.CalledProcessError: Command '['mount', '-o', 'loop', '/var/lib/mabox-snapshot/work/iso/efi.img', '/var/lib/mabox-snapshot/work/iso/.efi.img.mnt']' returned non-zero exit status 32.

Kind regards.

[muzqs]

Hi @M0nst3r,

Before I dive into it — did you reboot after updating and try again?

I can’t reproduce it here. The error is mount failing to set up a loop device for efi.img, which almost always means the loop kernel module can’t load. That’s exactly what happens when the system has pulled a new kernel (you’re on linux618) but hasn’t been rebooted yet — the running kernel no longer matches its modules on disk.

So: reboot, then run it again.

If it still fails after a clean reboot, paste the output of:

mabox-snapshot version
mabox-snapshot doctor
uname -r
lsmod | grep loop
findmnt -no FSTYPE /

Off topic: To post output that reads better.

Start with ctrl-e after that paste the terminal output.
You are doing it the other way around. You first paste the text and after you use the <>, this is fine for one-liners.

[muzqs]

Update:

Added nomodeset to GRUB. As fallback.

CHANGELOG.md

This will be added in the next release. v0.3.0.

[M0nst3r]

Hi @muzqs

First, thanks for the tip, I also hated the paragraph and couldn’t figure out the right way to do it.

Looks the same as before, here is just in case:

==> Creating xz-compressed initcpio image: '/var/lib/mabox-snapshot/work/iso/boot/initramfs-linux618.img'
  -> Early uncompressed CPIO image generation successful
==> Initcpio image generation successful
mount: /var/lib/mabox-snapshot/work/iso/.efi.img.mnt: failed to set up loop device for /var/lib/mabox-snapshot/work/iso/efi.img.
Traceback (most recent call last):
  File "/usr/bin/mabox-snapshot", line 8, in <module>
    sys.exit(main())
             ~~~~^^
  File "/usr/lib/python3.14/site-packages/mabox_snapshot/cli.py", line 1184, in main
    return args.func(args)
           ~~~~~~~~~^^^^^^
  File "/usr/lib/python3.14/site-packages/mabox_snapshot/cli.py", line 666, in cmd_create
    isobuild.prepare_efi_boot(iso_root, cfg.workdir)
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/mabox_snapshot/isobuild.py", line 166, in prepare_efi_boot
    _build_fat_image(iso_root / "efi.img", boot_efi / "bootx64.efi", "efi/boot/bootx64.efi", efi_img_size)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/mabox_snapshot/isobuild.py", line 127, in _build_fat_image
    subprocess.run(["mount", "-o", "loop", str(dest), str(mnt)], check=True)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 578, in run
    raise CalledProcessError(retcode, process.args,
                             output=stdout, stderr=stderr)
subprocess.CalledProcessError: Command '['mount', '-o', 'loop', '/var/lib/mabox-snapshot/work/iso/efi.img', '/var/lib/mabox-snapshot/work/iso/.efi.img.mnt']' returned non-zero exit status 32.

The kernel/restart part don’t fit here as I always do so after updating. Here is the rest of commands you asked:

mabox@mabox ~ $ mabox-snapshot version
mabox-snapshot 0.2.9
mabox@mabox ~ $ mabox-snapshot doctor
[ok]   /etc/os-release identifies as Mabox
[ok]   mksquashfs found
[ok]   xorriso found
[ok]   grub-mkimage found
[ok]   mkinitcpio found
[ok]   mkfs.fat found
[ok]   rsync found
[ok]   openssl found
[ok]   yay found (optional)
[ok]   magick found (optional)
[ok]   cryptsetup found (optional)
[ok]   calamares found -- ISOs will include the installer
[ok]   Mabox Calamares branding present at /usr/share/mabox-snapshot/calamares-branding
[info] 30.5 GiB free at /var/lib/mabox-snapshot
[info] 1 kernel(s) detected: linux618
mabox@mabox ~ $ uname -r
6.18.45-1-MANJARO
mabox@mabox ~ $ lsmod | grep loop
vsock_loopback         12288  0
vmw_vsock_virtio_transport_common    57344  1 vsock_loopback
vsock                  69632  3 vmw_vsock_virtio_transport_common,vsock_loopback,vmw_vsock_vmci_transport
mabox@mabox ~ $ findmnt -no FSTYPE /
ext4
mabox@mabox ~ $ 

Extra: here is the folder content:

mabox@mabox ~ $ sudo ls -lh /var/lib/mabox-snapshot/work/iso/
[sudo] contraseña para mabox: 
total 4,1M
drwxr-xr-x 3 root root 4,0K ago 29 17:54 boot
drwxr-xr-x 3 root root 4,0K ago 29 17:54 efi
-rw-r--r-- 1 root root 4,0M ago 29 17:54 efi.img
drwxr-xr-x 3 root root 4,0K ago 29 17:45 mabox

Greetings.

[M0nst3r]

Here is another clue that may help you. By issuing the command:

sudo modprobe loop

The creation right after went fine:

xorriso : UPDATE :  96.83% done, estimate finish Sat Aug 29 18:30:03 2026
xorriso : UPDATE :  97.48% done, estimate finish Sat Aug 29 18:30:03 2026
ISO image produced: 3051321 sectors
Written to medium : 3051321 sectors at LBA 0
Writing to 'stdio:/var/lib/mabox-snapshot/work/mabox-reset-29-08-2026-1820.iso' completed successfully.

ISO written to /var/lib/mabox-snapshot/work/mabox-reset-29-08-2026-1820.iso
checksum written to /var/lib/mabox-snapshot/work/mabox-reset-29-08-2026-1820.iso.sha256
note: boot this in a VM before trusting it -- BIOS+UEFI hybrid boot is not self-verifying.

Relevant:

mabox@mabox ~ $ lsmod | grep loop
loop                   45056  0
vsock_loopback         12288  0
vmw_vsock_virtio_transport_common    57344  1 vsock_loopback
vsock                  69632  3 vmw_vsock_virtio_transport_common,vsock_loopback,vmw_vsock_vmci_transport

Hope it helps.

[M0nst3r]

So far the ISO seems fine. Here is the grub:

And several random apps open:

[muzqs]

Hi @M0nst3r,

Thanks, that’s the missing piece. Sounds like the ISO boots fine now on your side — can you confirm the issue is fully solved for you?

Your lsmod output shows exactly what’s going on:

@M0nst3r

sudo modprobe loop

mabox-snapshot builds the EFI boot image (efi.img) by loop-mounting it, which needs the loop kernel module loaded and a free loop device. On a system that’s been updated to a new kernel but not rebooted, or a minimal VM, that module isn’t always there — hence the failed to set up loop device error. modprobe loop loads it and the build goes through.

That’s the correct workaround for now. This one was actually already tackled earlier and is fixed in the upcoming v0.3.0: the EFI image is populated with mtools (mcopy) instead of a loop mount — the same way archiso builds its efiboot.img.
mtools becomes a dependency and mabox-snapshot doctor checks for it.

Thanks again for the diagnostics — that saved a lot of guesswork.

[M0nst3r]

My pleasure helping out.

The loop thing is… weird. Mabox was installed “as is” from the latest ISO at the time and updated regularly. No other change/config was made except installing my set of applications.

You know what? I want to do a full VM reinstall with the new version 26.08; a fresh start with all the new toys by default.

Regards.