BOOTC-INST...STING-ROOT(8)

💖 BOOTC-INSTALL-TO-EXISTING-ROOT 💖

okay bestie, gather round, because this is the bootc subcommand that installs onto the root filesystem you're already standing on. It lives in section 8 of the System Manager's Manual, so yes it's a big-girl system administration page, and yes we're gonna make it cute. 🎀

---

✨ NAME ✨

bootc-install-to-existing-root — Install to the host root filesystem. that's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

bootc install to-existing-root [OPTIONS...] [ROOT_PATH]

---

👑 DESCRIPTION 👑

Install to the host root filesystem. periodt.

This is a variant of install to-filesystem that's designed to install "alongside" the running host root filesystem. So like, right now, as of today: the host root filesystem's /boot partition will be wiped 😭 but the content of the existing root will otherwise be retained, and it will need to be cleaned up if you want it gone once you've rebooted into the new root.

no cap, /boot is getting yeeted. plan accordingly. 💀

🧚 Managing configuration: before and after reboot

When you're using to-existing-root, there are two distinct scenarios for managing configuration files, and they are NOT the same scenario, bestie:

1. Before rebooting: Injecting new configuration into the newly installed system
2. After rebooting: Migrating configuration from the old system to the new system

🌈 Before reboot: Injecting new configuration

If you need to inject new configuration files — think custom /etc/fstab entries, systemd mount units, or other config — into the newly installed system before rebooting, mount it with bootc-install-mount(8) and modify it through the mounted view. For example, to add a systemd mount unit:

mkdir /mnt/installed
bootc install mount --sysroot /target --latest /mnt/installed
vi /mnt/installed/etc/systemd/system/data.mount
umount -R /mnt/installed

⭐ Injecting kernel arguments for local state

A better approach (lowkey the superior one, fr fr) for machine-local configuration like filesystem mounts is to inject kernel arguments during installation. Kernel arguments are ideal for local/machine-specific state in a bootc system.

For filesystem mounts, use systemd.mount-extra instead of /etc/fstab:

# Add a mount via kernel argument (preferred over /etc/fstab)
bootc install to-existing-root \
  --karg="systemd.mount-extra=UUID=<uuid>:/data:xfs:defaults"

The systemd.mount-extra syntax is: source:path:type:options

You can also inject other local kernel arguments for machine-specific configuration:

# Add console settings for serial access
bootc install to-existing-root --karg="console=ttyS0,115200"

# Add storage-specific options
bootc install to-existing-root --karg="rootflags=subvol=root"

This approach is cleaner than editing configuration files because kernel arguments are explicitly designed for local/machine-specific state in a bootc system. it's giving intended usage. 💅

Note: In the future, this functionality will be provided via a dedicated bootc API to make finding and modifying the deployment more straightforward.

🦋 After reboot: Migrating data from the old system

After rebooting into the new bootc system, the previous root filesystem data is accessible at /sysroot — that's the "physical root". This lets you migrate data from the old system to the new one. slay.

Important: Any configuration data from /etc that you want to use in the new system must be manually copied from /sysroot/etc to /etc after rebooting. There is currently no automated mechanism for migrating this data. you're on your own, babe. 😭

For example, to migrate configuration after rebooting:

# After rebooting into the new system
# Copy network configuration from the old system
cp /sysroot/etc/sysconfig/network-scripts/ifcfg-eth0 /etc/sysconfig/network-scripts/

# Copy application configuration
cp -r /sysroot/etc/myapp /etc/

# Identify the old resolver policy, then migrate its authoritative
# network manager profiles or resolver configuration
stat -c '%F %N' /sysroot/etc/resolv.conf

# For user accounts, use proper tools
vipw  # Carefully review and merge users from /sysroot/etc/passwd

This applies to network configurations, user accounts, application settings, and other system configuration stored in /etc. Review files in /sysroot/etc and manually copy or merge what you need into /etc.

Note: A generated /etc/resolv.conf should not normally be copied or edited directly. It may be a dangling symlink after reboot, or it may contain only a local resolver address such as 127.0.0.53, rather than the upstream DNS servers. Migrate the authoritative configuration instead — things like NetworkManager connection profiles or resolver drop-ins — into the configuration used by the new system. If both systems intentionally use a hand-managed static file, it may instead be selectively migrated. See DNS and /etc/resolv.conf (see bootc-dns(7)) for details. 📝

Note: For filesystem mounts from /etc/fstab in the old system, consider using kernel arguments (via systemd.mount-extra) injected before reboot instead of migrating the fstab entries. See the "Injecting kernel arguments" section above. 👀

---

💅 OPTIONS 💅

• ROOT_PATH — Path to the mounted root; this is now not necessary to provide. Historically it was necessary to ensure the host rootfs was mounted at here via e.g. -v /:/target. (rip to the old ways 🫡)
• --replace=REPLACE — Configure how existing data is treated.

Possible values:

• wipe
• alongside

Default: alongside

• --source-imgref=SOURCE_IMGREF — Install the system from an explicitly given source.
• --target-transport=TARGET_TRANSPORT — The transport; e.g. oci, oci-archive, containers-storage. Defaults to registry.

Default: registry

• --target-imgref=TARGET_IMGREF — Specify the image to fetch for subsequent updates.
• --enforce-container-sigpolicy — This is the inverse of the previous --target-no-signature-verification (which is now a no-op). Enabling this option enforces that containers-policy.json (see man containers-policy.json for the full search path) includes a default policy which requires signatures. 🔒
• --run-fetch-check — Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image.
• --skip-fetch-check — Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image.
• --disable-selinux — Disable SELinux in the target (installed) system. 🙈
• --karg=KARG — Add a kernel argument. This option can be provided multiple times.
• --karg-delete=KARG_DELETE — Remove a kernel argument. This option can be provided multiple times.
• --root-ssh-authorized-keys=ROOT_SSH_AUTHORIZED_KEYS — The path to an authorized_keys that will be injected into the root account. 🔑
• --generic-image — Perform configuration changes suitable for a "generic" disk image. At the moment: (yes bestie, that's the whole description, it just trails off like that 💀)
• --bound-images=BOUND_IMAGES — How should logically bound images be retrieved.

Possible values:

• stored
• skip
• pull

Default: stored

• --stateroot=STATEROOT — The stateroot name to use. Defaults to default.
• --bootupd-skip-boot-uuid — Don't pass --write-uuid to bootupd during bootloader installation.
• --bootloader=BOOTLOADER — The bootloader to use.

Possible values:

• grub
• grub-cc
• systemd
• none

• --acknowledge-destructive — Accept that this is a destructive action and skip a warning timer. ⚠️ (the warning timer is there for a reason bestie, this flag is you saying "yes queen I know")
• --cleanup — Add the bootc-destructive-cleanup systemd service to delete files from the previous install on first boot. 🧹
• --composefs-backend — Use the composefs backend instead of ostree. This is the default for images with a UKI, and for images with /usr/lib/composefs/setup-root-conf.toml and no ostree prepare-root.conf.

Default: false

• --allow-missing-verity — Make fs-verity validation optional in case the filesystem doesn't support it (composefs backend only).

Default: false

• --uki-addon=UKI_ADDON — Name of the UKI addons to install without the ".efi.addon" suffix. This option can be provided multiple times if multiple addons are to be installed (composefs backend only).

---

🌟 VERSION 🌟

v1.17.1

---

and that's the whole page, bestie!! 🎀✨ this manual page is part of the System Manager's Manual, and this particular version is v1.17.1 — go off, bootc. now go install responsibly, acknowledge that warning timer, and copy your /etc from /sysroot like the icon you are. mwah. 💖👑🫶