Skip to main content

index

CI E2E

In-place conversion tool for an OSTree-backend bootc system (for example, Bluefin) to a ComposeFS-backend bootc system (for example, Dakota). It keeps /home, /var, and /etc customizations, flatpaks, container storage, and user accounts.

Contribute compute — no code needed​

Donate time with your AI CLI.

Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.

The guide covers prerequisites, verified just setup, credentials, provider costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply. Never post account credentials or API keys in issues or pull requests.

Migrate Bluefin → Dakota (quick start)​

The common case: Bluefin stable (btrfs) → Dakota stable. Five steps. Your old OSTree deployment stays in the boot menu as a fallback the whole time.

⚠️ Back up anything you can't afford to lose first. This rewrites how your system boots. It preserves /home, /var, /etc, flatpaks, container storage, and user accounts — but treat it as risky until you've rebooted and confirmed everything works. It's reversible until you run commit (step 5).

1. Get the migrator. Download the latest prebuilt binary. Use x86_64-unknown-linux-gnu on x86_64, aarch64-unknown-linux-gnu on arm64 glibc systems, or aarch64-unknown-linux-musl on arm64 musl systems such as postmarketOS and Alpine:

Release-naming note. The project changed its repository name from bootc-migrate-composefs to bootc-migrate after v0.2.0. release.yml publishes under the new name, so from v0.6.0 the tarball, binary, and container image are all bootc-migrate. The commands below reflect that. To install the older v0.2.0 artifacts, substitute bootc-migrate-composefs in the paths.

curl -fsSL -o bmc.tar.gz \
https://github.com/tuna-os/bootc-migrate/releases/latest/download/bootc-migrate-x86_64-unknown-linux-gnu.tar.gz
tar xzf bmc.tar.gz
sudo install -m755 bootc-migrate /usr/local/bin/bootc-migrate
sudo install -m755 bootc-rebase /usr/local/bin/bootc-rebase

On Bluefin LTS, /usr/local is part of the read-only /usr, so the install commands fail. Run the binaries from the directory where you unpacked them instead (sudo ./bootc-migrate …). Nothing later needs them on PATH: the bootloader resync hook keeps its own copy under /var/lib/bootc-migrate/bin.

…or pull the container image

A minimal image ships the same binary, useful when GitHub Releases is rate-limited/blocked, or to COPY --from= it into another Containerfile:

podman create --name bmc-extract ghcr.io/tuna-os/bootc-migrate:latest
podman cp bmc-extract:/usr/local/bin/bootc-migrate .
podman rm bmc-extract
sudo install -m755 bootc-migrate /usr/local/bin/bootc-migrate
…or build from source (needs Rust)
git clone https://github.com/tuna-os/bootc-migrate
cd bootc-migrate
cargo build --release
sudo install -m755 target/release/bootc-migrate /usr/local/bin/

2. Dry-run — makes no changes and checks that your system is ready:

sudo bootc-migrate \
--target-image ghcr.io/projectbluefin/dakota:stable --dry-run

3. Migrate (~5–25 min):

sudo bootc-migrate \
--target-image ghcr.io/projectbluefin/dakota:stable

4. Reboot — the new composefs entry is the default. If anything looks wrong, pick the old Bluefin / OSTree entry in the boot menu to get straight back.

sudo systemctl reboot

5. Confirm, then make it permanent:

grep -oE 'composefs(\.digest)?=[^ ]*' /proc/cmdline # confirms composefs boot
sudo bootc-migrate commit # one-way; removes the OSTree fallback

⚠️ Note: Phase 4 copies /var to the composefs side. After migration, the two /var trees are independent. Changes on the composefs side do not appear if you roll back to OSTree. Commit only when you trust the new system.

That's it. For flags, rollback, recovery steps, and phase details, see Usage — end-to-end walkthrough. On Bluefin LTS (XFS) or systems with LVM / LUKS / a dedicated /var partition, the tool handles those automatically — see docs/filesystem-support.md.

Status: CI-validated, released, and tested on real hardware. Each push to main runs a round-robin slice of the gating E2E cells. The nightly run does all cells in .github/e2e-scenarios.yml. Prebuilt binaries are on the Releases page.

Interactive wizard (TUI)​

Prefer a guided walkthrough? Run bootc-migrate with no --target-image or with tui to open the terminal wizard. The wizard helps you select a target image and options. It then shows the review and live phase logs:

sudo bootc-migrate tui

bootc-migrate TUI wizard

The image picker fetches the latest CI-published catalog, then uses a cached or bundled JSON snapshot if offline. It lists published Bluefin, Universal Blue, TunaOS, Zirconium, and Utah images. Utah is pre-alpha, so the picker offers only its :testing tag. You see the selected image reference and backend before you continue. OSTree targets use bootc-rebase, which you must install alongside bootc-migrate; ComposeFS targets use the normal migrate path. The tool does not support a return from ComposeFS to OSTree.

The wizard starts in dry-run mode. Press Enter to accept each screen, use ↑/↓ to choose an image, and press Space on the options page to change a setting. For a live run, turn off dry-run there, or press Enter after a successful dry-run to review and apply in the same session. The wizard then clears the old confirmation and does the readiness checks again. The final review needs CONFIRM and Enter before anything changes. You need root for a migration, but you can browse the catalog without it.

Coming from a regular (non-bootc) install​

Fedora, Ubuntu, Debian, and Arch installs use package managers such as rpm, dpkg, or pacman. These systems are package hosts, not bootc deployments. bootc-rebase detects the source and selects the package → OSTree route. The TUI shows the same route, limits the image picker to OSTree targets, and keeps the run read-only.

Current status: preview only. The PackageInstall engine does not exist yet (#373). Run the readiness preview, but do not treat it as a migration:

sudo bootc-rebase rebase \
--target-image quay.io/fedora/fedora-bootc:latest \
--target-backend ostree \
--dry-run

The preview shows two reports. One covers the package host; the other covers target hardware. It checks UEFI boot, the root filesystem and subvolume layout, LUKS/LVM, /boot, /home, free space, active package transactions, and SELinux. The support matrix records evidence for each source distribution, filesystem, and boot mode.

The completed route will use this contract:

  • The bootc deployment carries user accounts, home directories, application data, and user-modified /etc files. It uses the target image's default for unmodified package-owned configuration.
  • Host packages do not carry. The software report (#377) lists missing packages, third-party repositories, services, and kernel modules. It also lists Flatpak, Homebrew, toolbox/distrobox, or derived-image replacements.
  • The old package OS stays bootable as Previous system until commit. #374 tracks creation and removal of that rollback entry.
  • Use a separate one-way commit. After you verify the new deployment, #378 guides commit and reclaims the old OS. The existing bootc-rebase commit supports only composefs → OSTree. Do not use it for the package-host route.

Architecture​

flowchart TB
%% ── Source: what we migrate from ────────────────────────────
subgraph SRC["Source · OSTree-backed Bluefin"]
direction TB
S_USR["<b>/</b> &mdash; OSTree hardlink farm<br/>/usr/etc &middot; /ostree/repo object store"]
S_ETC["<b>/etc</b><br/>live, 3-way-merge source"]
S_VAR["<b>/ostree/deploy/&lt;n&gt;/var</b><br/>user state"]
S_BOOT["<b>/boot/loader/entries</b><br/>GRUB BLS &middot; ostree-*"]
end

%% ── The migration tool: six phases, one command ─────────────
subgraph BIN["bootc-migrate &middot; 6 phases (0&ndash;5)"]
direction TB
P0["<b>Phase 0 &middot; Preflight</b><br/>ESP size &middot; NVRAM &middot; reflink"]
P1["<b>Phase 1 &middot; OSTree import</b> (optional)<br/>reflink objects &rarr; composefs store"]
P2["<b>Phase 2 &middot; OCI pull</b><br/>target image &rarr; composefs store"]
P3["<b>Phase 3 &middot; EROFS seal</b><br/>build &middot; seal &middot; capture config digest"]
P4["<b>Phase 4 &middot; Stage deploy</b><br/>3-way /etc merge (sealed mount)<br/>symlink prune &middot; identity-DB union<br/>/var copy &middot; .origin (tini)"]
P5["<b>Phase 5 &middot; Bootloader</b><br/>sd-boot from sealed mount<br/>BLS entries on ESP &middot; NVRAM"]
P0 --> P1 --> P2 --> P3 --> P4 --> P5
end

%% ── Target: what we migrate to ──────────────────────────────
subgraph DST["Target &middot; ComposeFS-backed Dakota"]
direction TB
D_CFS["<b>/composefs/</b><br/>images/ (EROFS) &middot; objects/ &middot; streams/"]
D_STATE["<b>/state/deploy/&lt;verity&gt;/</b><br/>etc/ &middot; &lt;verity&gt;.origin"]
D_VAR["<b>/state/os/default/var</b><br/>bind-mounted as /var by initramfs"]
D_BOOT["<b>/EFI/Linux/bootc_composefs-&lt;verity&gt;/</b><br/>vmlinuz &middot; initrd<br/>/loader/entries/*.conf &middot; systemd-bootx64.efi"]
end

%% ── Data flows across the lanes ─────────────────────────────
S_USR -- "ostree object reflinks" --> P1
P2 --> D_CFS
S_ETC -- "current / old / new merge" --> P4
P4 --> D_STATE
S_VAR -- "verbatim copy<br/>(containers &middot; flatpaks &middot; machine-id)" --> D_VAR
P3 -- "sealed config digest<br/>(not rootfs verity)" --> P4
P3 --> P5
P5 -- "copy from sealed mount" --> D_BOOT
P5 -. "efibootmgr &middot; Linux Boot Manager" .-> NVRAM(["UEFI NVRAM"])

RUN["<b>Booted Dakota</b><br/>/ = composefs overlay (RO)<br/>/etc writable &larr; state/<br/>/var writable &larr; state/os/default/var"]
DST -. "reboot &rarr; systemd-boot &rarr; kernel<br/>cmdline composefs=&lt;verity&gt;" .-> RUN

%% ── Lane colours ────────────────────────────────────────────
classDef src fill:#e3f0ff,stroke:#3b82c4,color:#0b2545;
classDef bin fill:#fff4e0,stroke:#d9920b,color:#5a3a00;
classDef dst fill:#e4f7e7,stroke:#3ca34a,color:#06311a;
classDef run fill:#f3e8ff,stroke:#8b5cf6,color:#2e1065;

class S_USR,S_ETC,S_VAR,S_BOOT src;
class P0,P1,P2,P3,P4,P5 bin;
class D_CFS,D_STATE,D_VAR,D_BOOT dst;
class RUN,NVRAM run;

Key insight: Phase 3 runs bootc internals cfs oci seal and prints the sealed manifest's config digest. Phases 4 and 5 pass that sealed config digest (not rootfs verity) to bootc cfs oci mount. The overlay exposes /etc, kernel, initrd, systemd-boot, and kernel modules without another OCI layer stream.

What it does​

Six phases (numbered 0–5 to match console output), run as one command:

  • Phase 0 — Preflight — free-space, reflink/CoW, UEFI, NVRAM-writable, ESP capacity.
  • Phase 1 — OSTree import (optional) — copies file objects from OSTree into the composefs store. This reduces duplicate data in Phase 2. Skip it with --skip-import.
  • Phase 2 — OCI pull — bootc internals cfs oci pull of the target bootc image into the composefs store.
  • Phase 3 — EROFS seal — builds and seals the EROFS image. It saves the sealed config digest for Phases 4 and 5.
  • Phase 4 — Stage deploy — merges /etc and combines lines from identity databases. It reads from the sealed mount and removes broken /usr/* symlinks. It keeps /home ↔ /var/home compatibility and preserves /var. .origin stores boot_digest and manifest_digest; tini writes it.
  • Phase 5 — Bootloader — copies systemd-bootx64.efi from the sealed mount to the ESP. It confirms that current wireless devices work with the target kernel. It writes BLS entries and adds a stateroot mount argument for dedicated /var. It registers Linux Boot Manager in UEFI NVRAM. The original GRUB entry stays as a rollback escape hatch.

After a successful reboot into the composefs entry, bootc-migrate commit removes the OSTree fallback and makes composefs permanent.

Usage — end-to-end walkthrough​

Before you start. This tool changes bootloader state and copies or reuses all of /var. Don't run it on a machine you can't reinstall in a pinch. Until you run commit, it's reversible — but a fresh backup is still cheap insurance.

1. Decide your target​

The migration takes a --target-image — the composefs-backed bootc image you want to end up on. Today the validated path is Bluefin → Dakota:

ghcr.io/projectbluefin/dakota:stable # default target

For other OSTree systems (Aurora, Silverblue), set --target-image to the composefs equivalent.

Utah on OSTree → Utah on composefs. Utah ships systemd-boot and the composefs initramfs module of bootc. Thus a Utah install that boots OSTree can change to the composefs backend with the image that it runs now. The OS stays the same; only the backend and the bootloader (GRUB → systemd-boot) change:

sudo bootc-migrate --target-image ghcr.io/projectbluefin/utah:testing --dry-run
sudo bootc-migrate --target-image ghcr.io/projectbluefin/utah:testing

On such a host, sudo bootc-migrate tui offers this conversion as the first choice. Utah is pre-alpha, and its utah -> utah cell (btrfs on LUKS) is non-gating.

⚠️ Not on btrfs until the target's kernel has the btrfs fs-verity fix.

On btrfs, kernels from 7.2 on can reject data that is correct (fs-verity ... FILE CORRUPTED! in dmesg). The composefs store is fs-verity data. The first local run of the cell stopped at the integrity check before it staged anything. A host that gets past the check can still read EIO from its root later. The fix is linux-next dcf8811f63af; Utah plans to ship Fedora's kernel rebuilt with it. Details and measurements are in docs/support-matrix.md.

The target must share a base lineage with the source: its ID_LIKE must overlap yours, or both images must ship the same package manager. Bluefin, Silverblue and CentOS-based images are all one dnf family. The tool refuses a target from another family, for example Fedora → openSUSE, because the standard /etc merge would carry your Fedora configuration onto openSUSE. Pass --accept-cross-base to migrate with the cross-family /etc policy instead. See "Cross-family targets" below.

To migrate to an image you built yourself instead of a published one, see docs/local-images.md. Serve it from a registry the machine can reach. An image that exists only in podman storage is not enough. The capability scan and the Phase 4/5 fallbacks read the target over the registry API.

2. Check readiness with a dry-run​

sudo bootc-migrate \
--target-image ghcr.io/projectbluefin/dakota:stable \
--dry-run

Things to confirm in the report:

  • Booted bootc backend: ostree — the conversion runs from here. composefs means the conversion is done, and the tool swaps the deployment image instead (bootc switch). Only none (not a bootc deployment) is a blocker.
  • UEFI Boot Mode: Yes + NVRAM writable: Yes — required for the systemd-boot path; on BIOS-only or locked NVRAM pass --bootloader grub2.
  • ESP Free Space: ≥ 150 MB — we copy systemd-bootx64.efi from the target image onto the ESP.
  • Reflink (CoW) Support: Yes — btrfs and XFS both support reflink.
  • ComposeFS free space includes the source OSTree import. It also includes two expanded copies of the target image for ComposeFS and podman fallback storage. Another 5 GiB provides temporary headroom for the initrd rebuild.

Optionally, preview what Phase 4's /etc merge will see before you run it:

sudo bootc-migrate etc-drift

Lists every path where your live /etc has diverged from the OSTree factory default (added/modified/removed/type-changed), read-only. Useful to find stale customizations you do not need before they carry forward into the migrated system.

3. Run the migration​

sudo bootc-migrate \
--target-image ghcr.io/projectbluefin/dakota:stable

Expect ~5–10 minutes on warm caches, ~15–25 minutes on a cold pull. Six phase headers (0–5) print as it goes:

PhaseWhat's happeningWhy it might take a while
0 — PreflightSame checks as --dry-runseconds
1 — OSTree import (optional)Reflinks existing OSTree file objects into the composefs object store so Phase 2 mostly dedupstens of seconds to a few minutes; skip with --skip-import
2 — OCI pullbootc internals cfs oci pull of the target imageminutes (network-bound)
3 — EROFS imageBuilds + fs-verity-signs the composefs metadata imageseconds
4 — Stage deploy3-way /etc merge (from sealed mount) or, across families, the cross-family policy; dangling-symlink prune, identity-DB line-union, /var copy or dedicated-subvolume preservation, .origin file written~1 minute
5 — BootloaderCopies systemd-boot from mounted image, writes BLS entries, registers NVRAM~30s

When it ends with === MIGRATION COMPLETED === the on-disk state is ready. Reboot:

sudo systemctl reboot

4. Validate the composefs boot​

Log in (your existing accounts and SSH keys still work) and check:

cat /proc/cmdline # must contain composefs=<hex>
bootc status # should report the composefs deployment
bootc status --json | jq .status.booted.composefs # non-null

Spend a day on it. Run your usual workflow — flatpaks, dnf, containers, homebrew, GNOME extensions, whatever. Everything that lived under /home, /var, and /etc on Bluefin should be where you left it. If something is missing or broken, you can roll back (see below).

A login banner (/etc/motd.d/85-bootc-migrate) reminds you to run commit on every login until you do, so a live migration doesn't sit forgotten in this dual-boot state indefinitely. It clears itself once commit runs — or once undo runs, since at that point there's nothing left to commit.

5. Make it permanent (one-way)​

Once you trust the new system:

sudo bootc-migrate commit

This removes the OSTree fallback from the ESP, drops GRUB2 boot artifacts, and reclaims ~14 GiB of OSTree object store. The systemd-boot entry becomes the sole default with timeout 0.

Flags​

FlagPurpose
--dry-runPrint every action; touch nothing
--skip-importSkip phase 1 (faster when target image is mostly new content)
--bootloader grub2Stay on GRUB2 instead of installing systemd-boot
--skip-preflightBypass preflight checks (don't, unless you know exactly why)
--forceProceed past non-fatal warnings
--accept-cross-baseMigrate to a target from another OS family with the cross-family /etc policy (see below). --force does not imply it
--accept-hardware-gapsMigrate although the hardware check (see below) expects hardware that works today to stop working. --force does not imply it

Hardware and firmware check​

The target image replaces your kernel, its modules and your firmware. Before the tool changes anything, it compares your hardware with the target. The bootc-rebase scan <image> command shows the same report.

The tool examines the PCI, USB, SDIO, virtio and HID devices. It examines only the devices that use a loadable kernel module now. It does these checks:

  • Drivers. The target must ship the same module, or a module that claims the device.
  • Out-of-tree drivers. These are drivers like NVIDIA, VirtualBox and ZFS. The target can omit one of them. Then the report names the in-kernel driver that replaces it (for NVIDIA, nouveau) and what you lose.
  • Firmware. For each module, the tool lists the firmware files that your machine has. The target must ship at least one of them.
  • CPU microcode. Your machine can have microcode updates for its CPU. Then the target must also have them.

Each result has a level:

  • [BLOCKING]: the tool refuses to migrate. A storage, display, network, wireless or USB controller loses its driver or all of its firmware. Or an out-of-tree driver has no in-kernel replacement. To continue anyway, use --accept-hardware-gaps. A better fix is an image variant that supports the hardware, for example an -nvidia image.
  • [WARNING]: something can stop, but the migration continues. A display controller without its driver is a warning when the target kernel has a firmware framebuffer driver (simpledrm, efifb). The screen then works, but without graphics acceleration and at the firmware resolution.
  • [note]: information only.

When the tool cannot read the target image, it tells you and continues. In this case, it did not check your hardware. Some image layers can be unreadable. Then no result blocks the migration, because the missing data can hide what the image ships.

Cross-family targets​

bootc-migrate reads the target image's os-release and package manager before it stages the image. Shared ID/ID_LIKE values or the same package manager mean one family. Different families (Fedora → openSUSE or Debian) refuse. If the target has no known package manager, the tool warns and checks the staged os-release again.

With --accept-cross-base, the conversion route and both bootc switch routes apply this policy:

  • Target files win. The tool drops the vendor-only files of the source.
  • Machine state and user-added files stay.
  • For identity merges, target IDs come first and source accounts append. The tool remaps the ownership of files in /var.
  • Displaced edits use <path>.rebase-old. The tool deletes no files.
  • OstreeDeploy applies after OSTree finalization and schedules /.autorelabel when needed. ImageSwap applies after composefs finalization and preserves sysusers/ldconfig repair.

If the staged image is cross-family without --accept-cross-base, the route leaves it staged and unfinalized. Remove it before you try again. Do not reboot.

The tool prints the report and keeps it across the reboot. A composefs deployment stores it at /sysroot/state/deploy/<verity>/bootc-migrate-cross-family-report.json. The composefs → OSTree route stores it in the new stateroot's /var/lib/bootc-rebase/bootc-migrate-cross-family-report.json, because an OSTree deployment root is immutable after installation. Non-gating E2E cells test the conversion route and OstreeDeploy. See ROADMAP.md and issues #258, #256, and #259.

Move system Steam into Flatpak Steam​

After you install and run com.valvesoftware.Steam once, its per-user data can absorb a system Steam install without new game downloads:

bootc-migrate system-to-flatpak-steam --dry-run
bootc-migrate system-to-flatpak-steam

Run it as the desktop user, without sudo, after you close Steam and all Steam games. The tool uses filesystem renames only to move steamapps, userdata, and config from ~/.local/share/Steam into Flatpak Steam directories. The tool keeps existing Flatpak versions and library registries in a timestamped rollback directory under ~/.var/app/com.valvesoftware.Steam/.

The command keeps runtime files for Steam and folders like ~/Games. Add a Flatpak filesystem override for ~/Games separately if Steam shortcuts need it.

Rollback / recovery​

Until you run commit, the migration is reversible. The previous OSTree deployment stays bootable:

  • Phase 5 only adds the systemd-boot composefs entry; it never deletes the existing /boot/loader/entries/ostree-*.conf files.
  • The original /ostree/deploy/<n>/deploy/<commit>.0/ rootfs and /ostree/deploy/<n>/var/ stay on disk.
  • Phase 4 copies /var or reuses it in place. The migration does not delete original data.
  • The tool pushes Linux Boot Manager to the front of NVRAM BootOrder. The Fedora shim entry remains listed.

Automatic rollback subcommand​

To return to the original OSTree deployment with the command line:

sudo bootc-migrate rollback --reboot
# or via the universal re-base CLI:
sudo bootc-rebase rollback --reboot

This verifies prerequisites, re-orders UEFI BootOrder so the OSTree entry (Fedora/GRUB) takes top priority, and reboots immediately into the OSTree deployment.

Manual firmware recovery​

If the system fails to boot into composefs or NVRAM state breaks:

  1. Power on; tap the firmware boot-menu key (commonly F12, F8, or Esc).
  2. Pick the Fedora entry. GRUB will show the original ostree:0 menu.
  3. Boot it. You land on the pre-migration system with its /var and /etc intact.

From a booted composefs session, run:

sudo efibootmgr -v | grep -E 'Fedora|Linux Boot Manager'
sudo efibootmgr --bootnext <Boot####-of-Fedora>
sudo systemctl reboot

The tool writes diagnostic snapshots and logs under /var/log/bootc-migrate/ on every run (preflight-*.json and migration.log). You can reconstruct boot settings if NVRAM is lost.

After bootc-migrate commit runs, the tool removes the OSTree fallback from the ESP. The E2E test exercises the full round-trip (composefs → OSTree → composefs) on every run.

First-boot repair​

The migration stages a unit that runs one time on the first boot. It fixes these known problems: carried home files with the wrong owner or time, a duplicated machine-id, broken Flatpak installations, and SELinux labels. Other findings stay as they are; the repair log reports them. To stop the repair, run sudo bootc-migrate repair --disable before the reboot. See docs/first-boot-repair.md.

What's preserved​

Validated end-to-end (21+ assertions per run; see tests/run-e2e.sh):

  • /var data — /var/lib/*, /var/log/*, /var/cache/*, containers, flatpak system installs, machine-id, hidden dirs and symlinks.
  • User homes — /var/home/<user>/, dotfiles, project trees, SSH keys, wallpapers, extensions, dconf user db, and flatpak installs. When an OSTree source uses /home -> /var/home, a bind mount keeps paths valid.
  • /etc state — /etc/sudoers.d/*, /etc/hosts edits, custom sshd_config.d/*, custom config files in /etc/, edits to /etc/hostname, and /etc symlinks.
  • Accounts — /etc/passwd, /etc/shadow, and /etc/group line-union merged so existing users survive and the tool adds new system users (messagebus, polkitd).

What's intentionally not carried forward:

  • OSTree/rpm-ostree state markers (.updated, .rpm-ostree-shadow-mode-fixed2.stamp)
  • GRUB2 config files (grub2.cfg, grub2-efi.cfg, /etc/grub.d/) — the target uses systemd-boot
  • Source-image /etc files the target image removed (e.g. sshd_config.d/40-redhat-crypto-policies.conf which references /etc/crypto-policies/ paths Dakota doesn't ship)

Troubleshooting​

SymptomLikely causeFix
Phase 0 refuses with "System is not booted into a bootc deployment"Neither an ostree nor a composefs deployment is bootedNothing to migrate from; check bootc status
Phase 0 refuses with insufficient free spaceThe root cannot hold the source import, ComposeFS target, podman fallback copy, and initrd rebuild headroomFree space or grow the partition, then rerun
Post-reboot cat /proc/cmdline shows ostree= not composefs=Firmware ignored the new NVRAM entry, or OVMF loaded Fedora\shim insteadUse firmware boot menu to pick Linux Boot Manager; if that fails, fall back to OSTree and report the firmware quirk
bootc status says "No manifest_digest in origin"You're on an old build of this toolUpdate to main — version info is on the first line of the migration log
SSH key auth broken post-migrationPermissions changed during /var copyBoot OSTree fallback and chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys
GNOME boots but session settings (wallpaper, accent) look wrongdconf database needs recompiledconf update as your user, or log out + back in
Phase 5 refuses because the target kernel has no module alias for a wireless deviceThe image omits the driver for Wi-Fi hardware present on the source systemFix or update the target image. Use --force only when alternate networking is available and losing Wi-Fi is acceptable
Refused with "hardware that works on this machine today is expected to stop working"The target image does not ship a driver or firmware that your storage, display, network or wireless hardware uses, or an out-of-tree driver such as NVIDIARead the [BLOCKING] lines. Pick an image variant that supports the hardware, or re-run with --accept-hardware-gaps to accept the loss
Refused with "Cross-family re-base detected"The target's ID_LIKE shares nothing with the host's and its package manager differsRe-run with --accept-cross-base to use the cross-family /etc policy, or pick a target from the same family
The new image boots, but /etc still looks like the old distributionA cross-family migration ran with a build that predates #256Update the tool, boot the OSTree entry, and migrate again with --accept-cross-base
Phase 2 fails with "podman could not refresh" on your own imageThe machine cannot pull the image, or podman rejects a plain-HTTP registryMark the registry insecure and confirm with a manual podman pull — see docs/local-images.md
Migration went wrong and you want to undo itSomething failed mid-migrationRun sudo bootc-migrate undo (removes composefs boot artifacts, keeps object store) or sudo bootc-migrate undo --full (full cleanup including object store); then reboot into OSTree

Requirements​

  • Booted on an OSTree-backed bootc system (Bluefin, Aurora, Silverblue…)
  • UEFI firmware with writable NVRAM (for the systemd-boot path; GRUB2 fallback works on BIOS)
  • Btrfs or XFS sysroot with reflink/CoW support
  • ESP with ≥150 MB free
  • ≥ 1.1 × ostree_repo_size free on /sysroot/composefs (no reflink: 1.5×)
  • Outbound registry access for bootc internals cfs oci pull. (Phase 2 fetches the target image. Later phases read artifacts from the mount.) A local registry works too — see docs/local-images.md.

Building​

cargo build --release

Drops a single binary at target/release/bootc-migrate. Needs Rust 1.85+ and a Linux host with libxkbcommon-dev.

End-to-end tests​

A QEMU-based E2E harness lives in tests/run-e2e.sh. It installs an OSTree/ComposeFS base image with bootc. In E2E_MODE=package-install, it boots an official cloud disk from Fedora or Ubuntu. tests/package-base.sh prepares that disk. The harness runs the package → OSTree migration, reboots, and validates the target plus its Previous system entry.

sudo ./tests/run-e2e.sh

Overridable via env: BASE_IMAGE, TARGET_IMAGE, DISK_SIZE, FILESYSTEM, E2E_MODE, E2E_PACKAGE_BASE, and E2E_PACKAGE_CROSS_FAMILY.

The full matrix is authoritative in .github/e2e-scenarios.yml. The nightly schedule runs alternate cells, so each cell runs every other night. Each PR and push to main runs a round-robin slice of the gating cells (see the test guide):

CellBase → targetFilesystemDisk
composefs migrationbluefin:stable → dakota:stablebtrfs60G
composefs migrationbluefin:lts → dakota:stableext460G
composefs migrationbluefin:lts → dakota:stablexfs+crypt60G
composefs migrationbluefin:lts → dakota:stablexfs+lvm+crypt60G
ostree re-basebluefin:stable → dakota:stablebtrfs40G
GRUB2 → systemd-boot trial (bootloader-trial)bluefin:lts → dakota:stablexfs+crypt60G
ostree re-base, GNOME→KDE (non-gating)bluefin:stable → aurora:stablebtrfs40G
TUI-driven migrationbluefin:stable → dakota:stablebtrfs60G
cross-family ostree re-base (non-gating)bluefin:stable → bootcrew/opensuse-bootc:latestbtrfs40G
cross-family migration (non-gating)bluefin:stable → bootcrew/opensuse-bootc:latestbtrfs60G
cross-family migration (non-gating)bluefin:stable → bootcrew/debian-bootc:latestbtrfs60G
cross-family migration (non-gating)bluefin:stable → bootcrew/ubuntu-bootc:latestbtrfs60G
cross-family migration (non-gating)bluefin:stable → bootcrew/arch-bootc:latestbtrfs60G
composefs → ostree (non-gating)dakota:stable → fedora-bootc:44btrfs40G
composefs → ostree, fault after ESP wipe (non-gating)dakota:stable → fedora-bootc:44btrfs40G
composefs → ostree, fault before BootNext (non-gating)dakota:stable → fedora-bootc:44btrfs40G
composefs → ostree, Dakota → Utah (non-gating)dakota:stable → utah:testingbtrfs80G
composefs image swap (non-gating)dakota:stable → utah:testingbtrfs40G
ostree → composefs, Utah → Utah (non-gating)utah:testing → utah:testingbtrfs on LUKS60G
cross-family image swap (non-gating)tunaOS marlin:gnome → utah:testingbtrfs60G
composefs → ostree, Marlin → Utah (non-gating)tunaOS marlin:gnome → utah:testingbtrfs80G
tunaOS desktop ring, ostree re-base with --de-migrate (4 cells, non-gating)albacore gnome → niri → cosmic → xfce → gnomebtrfs40G
package install (exploratory)Fedora Cloud → fedora-bootc:43btrfs40G
package install (exploratory)Fedora Workstation → Bluefinbtrfs + separate /boot60G
package install (exploratory)Ubuntu Cloud → fedora-bootc:43 (cross-family)ext440G

Of the composefs migration cells, only the two xfs* cells exercise the ext4-loopback composefs store (XFS has no fs-verity); btrfs and ext4 seal in place.

Layout​

A Cargo workspace with three crates (see ROADMAP.md):

  • crates/bootc-migrate-core — capability library: phases, preflight checks, /etc merge (mergetc), OSTree scans, stream extraction, transactions, capability scans, UID remaps, UEFI audits, and desktop migrations.
  • crates/bootc-migrate — the protected MVP binary described above. CLI surface (clap), commit/undo/rollback subcommands, the TUI wizard. Its E2E cells are untouchable regression gates — this binary's behavior doesn't change as new capability lands in bootc-rebase.
  • crates/bootc-rebase — the universal binary for re-base; see below.
  • tests/run-e2e.sh — QEMU E2E harness that tests both binaries.

bootc-rebase — the universal re-base engine​

bootc-migrate above does one proven thing: OSTree → ComposeFS. bootc-rebase is the general tool. It provides a table over backend × strategy to cover re-base scenarios (same-backend image swaps, cross-backend conversions, bootloader changes, cross-distro-family moves, desktop-environment switches). It's newer and less battle-tested than the MVP binary; treat subcommands marked skeleton or read-only below as previews, not yet full features.

cargo build --release -p bootc-rebase
SubcommandWhat it doesStatus
scan <image>Registry-streamed capability probe of a target image — composefs/ostree readiness, fs-verity requirement, transient root/etc, bootloader payload, desktops, base OS identity, sysusers, initramfs flavor, filesystem expectation, and a Compatible: YES/NO verdict with reasons. On a package host it also prints a host overview (distribution and family, package manager and count, filesystem layout, boot mode, Secure Boot and SELinux — #371) and compares installed software with the target image. --json includes the host overview and software report for machine consumers.Done
rebase --target-image <image>Re-base the running system, routing on --source-backend/--target-backend through the strategy table below. --plan prints the route, selected phases, and bootloader policy, then exits without touching the system.Implemented for ostree→composefs (the MVP pipeline), composefs→composefs (image swap), ostree→ostree (native bootc switch, with cross-base UID/GID remap when host and target disagree on distro family — pass --accept-cross-base to proceed past the report), and composefs→ostree (OstreeInstall, #260: the target's own bootc install to-existing-root builds an OSTree deployment beside the composefs root; /etc merged, /var copied, composefs ESP artifacts restored and its firmware entry kept first as rollback; a durable transaction journal verifies ESP/NVRAM state and uses one-shot BootNext for the target until commit; exploratory, non-gating cells). --accept-cross-base also accepts a cross-family target on all three migration routes and selects the cross-family /etc policy (#256/#259)
rollback [--reboot]Re-order UEFI BootOrder back to the previous deployment.Done
undo [--reboot]Make the staged package-host Previous system entry the bootloader default without removing the new bootc deployment. --dry-run prints the exact action.Core rollback support is implemented for the snapshot produced by PackageInstall; engine wiring is tracked separately in #373
boot-entries [--json] [--interactive] [--rename-branding] [--apply] [--undo]Enumerate and classify UEFI boot entries: dead (loader path missing), generic-label, duplicate, firmware-managed, plus which are protected and why. Dry-run by default — a bare invocation is the read-only audit. --interactive opens a checklist (protected entries are unselectable), --rename-branding proposes renaming the booted entry to PRETTY_NAME, --apply writes the result to NVRAM after a typed confirmation and a restorable snapshot, and --undo replays that snapshot.Audit and the cleanup planner are unit-tested (protections, the last-bootable-entry guard, and the "every entry looks dead ⇒ the ESP is wrong" refusal). The gating OSTree re-base E2E cell also renames a live OVMF NVRAM entry, applies the plan, undoes it, and asserts byte-identical efibootmgr -v output. This covers the executor and snapshot restore; it does not cover the separate, unimplemented GRUB2→systemd-boot flip (#31, #189)
commit [--apply] [--yes] [--force]After a composefs → ostree re-base has booted, remove the composefs state it kept as rollback (#315). Dry run by default: checks that the system booted the OSTree deployment the install report names, that the ESP snapshot and a shim/GRUB firmware entry exist, and that every path of the old /var is present in the live /var. It then lists every path it would delete, with sizes. --apply deletes after a typed confirmation. It first requires the boot transaction to classify as complete, promotes the observed-good target entry in UEFI BootOrder, and records that promotion. Then it copies the install report and ESP snapshot into the live /var/lib/bootc-rebase and removes the old /var, the composefs store and the composefs deployments. It never modifies the OSTree repo, /boot or the ESP. --force accepts failed cleanup checks, but never an unobserved boot transaction, a composefs boot, or a filesystem mounted inside a path to delete.Unit-tested against a fixture physical root. The non-gating composefs → ostree cell runs the dry run, then --apply, observes target-first BootOrder, then reboots and checks system health
de-migrate stash|restoreMove a user's desktop-environment config (GNOME dconf/gnome-shell, KDE kdeglobals/plasma, COSMIC, niri, XFCE) into or out of a stash directory around a cross-DE re-base — union of paths per issue #68, never deletes. --run-hooks executes pre-switch.d/post-switch.d scripts with REBASE_FROM_DE/REBASE_TO_DE/REBASE_STASH_DIR/REBASE_HOME set. --dry-run previews without touching anything.Done. Also runs automatically inside rebase --de-migrate; this subcommand remains the manual escape hatch for images shipping several desktops (which detection refuses to guess between)
rebase --de-migrateDetects the desktop environment the target image ships (registry-streamed session files, session binaries, and display-manager default session — no podman pull) and the one this host runs. When they differ, stashes every human account's outgoing DE config before staging and re-exposes any stash a previous re-base in the other direction left behind, running the pre-switch.d/post-switch.d hooks around each.Done, unit-tested; off by default — a re-base never touches per-user desktop state unless asked to. The non-gating Bluefin→Aurora E2E cell passes --de-migrate, seeds GNOME config, and asserts that the cross-DE plan and stash are created. Because target desktop detection uses the registry scan, this evidence depends on that exploratory cell completing successfully (#68, #188)
migrate-bootloader --to systemd-boot [--promote|--undo] [--from-image <image>]GRUB2 → systemd-boot conversion, standalone of a backend re-base.Implemented — stages every existing deployment on the ESP, installs systemd-boot, creates a one-boot BootNext trial without changing BootOrder, and installs a kernel-install resync hook. If the host does not ship systemd-bootx64.efi, --from-image <image> supplies a registry-reachable image to extract it from. --promote requires that the running system booted from the trial before making it persistent; --undo restores the prior firmware order and removes only the migration-owned files. The bootloader-trial QEMU cell covers the OVMF BootOrder swap, reboot, resync, promotion, and undo path.

The rebase route table in crates/bootc-migrate-core/src/rebase_plan.rs is the CLI source of truth before it touches anything:

From ↓ \ To →ostreecomposefs
ostreeOstreeDeploy (native bootc switch)CoreMigration (this repo's proven phase 0–5 pipeline)
composefsOstreeInstall (the target's own bootc install to-existing-root, alongside; composefs entry kept as rollback — #260, exploratory)ImageSwap
packagePackageInstall (the shared alongside-install engine binds / at /target, carries root kernel arguments, and snapshots the old /boot — #373)Two steps: package → ostree, then ostree → composefs

A package source is a system that is not a bootc deployment: a regular Fedora, Ubuntu or Arch installation. rebase finds one by its rpm, dpkg or pacman database when bootc status names no deployment and the root has no ostree or composefs state. On such a system, --target-backend auto (the default) selects ostree.

PackageInstall runs the target image's own bootc install to-existing-root against the live physical root after readiness and hardware gates pass. It snapshots the old kernels, initramfs, BLS entries, and GRUB configuration. Bootc then empties /boot. The Previous system entry and guided package-host commit remain tracked by #374 and #378.

The package-host /etc transition is ready for that install engine. It uses rpm, dpkg or pacman verification as the missing factory-copy classifier. Target defaults replace unmodified packaged files. The transition keeps package-host edits, unpackaged files and machine state. When a kept edit displaces a target version, the transition writes that version to .rebase-new.

For human accounts, the transition merges the records, and the target records come first. Numeric collisions produce an ownership-remap plan. The transition also drops the old root mount from fstab and rewrites /home to /var/home (#375).

--dry-run on a package host also prints a readiness report and the hardware report. The report refuses these systems and gives the reason for each refusal:

  • legacy BIOS boot (UEFI only for now);
  • a root filesystem other than btrfs, xfs or ext4;
  • a root, /home or /boot on LUKS or LVM;
  • a btrfs root that is not a subvolume;
  • too little free space for the image and the new deployment;
  • a read-only root, or an active package manager.

SELinux disabled on the host gives a warning, because the first boot then relabels all carried files.

The same registry pass extracts the target's rpm, dpkg or pacman inventory. scan and package-host --dry-run compare this inventory with the live host. They group packages that the image lacks into desktop applications, CLI tools, system services, kernel modules, and other packages. Suggestions first use a matching Flathub ID. They then use a known Homebrew formula, a toolbox or distrobox, or a derived image.

The report shows third-party package repositories and enabled services that the target lacks. If the registry pass is incomplete, the report does not make absence claims. It does not treat missing evidence as an empty image.

On a package host, scan also prints a host overview (#371). The overview shows the facts that the migration sees on this machine, apart from the target image. These facts are the distribution, the package manager, and the package count. They also include the layout of /, /home, /boot and /var with LUKS/LVM, the boot mode, Secure Boot, and SELinux. --json puts the overview under host.

A non-dry package-host invocation writes the machine-readable report and its Markdown twin to /var/lib/bootc-rebase/software-report.json and /var/lib/bootc-rebase/software-report.md. Dry runs and scan print the report and do not change the host.

Roadmap​

Full milestone plans, status per issue, and design decisions live in ROADMAP.md.

Contributing​

Contributions are welcome. See the contributor guide for setup and REVIEW.md for review rules. Run just check before you open a PR. AI contributions should follow AGENTS.md.

License​

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Any contribution you submit for inclusion in this project is dual-licensed as above.