bootc-switch

Change the base OS to a new container image from a registry

$ sudo bootc switch [image]

$ sudo bootc switch --transport containers-storage [image]

$ sudo bootc switch --transport oci-archive [path/to/image.tar.gz]

bootc switch [OPTIONS] [DEPLOYMENT_ID]

DEPLOYMENT_ID
    The optional identifier of the target deployment to switch to. If omitted, bootc typically switches to the most recently installed deployment or the 'next' logical deployment available on the system.

--target-root
    Specifies an alternative root directory (PATH) to operate on, rather than the currently running system's root. This is particularly useful for offline maintenance or modifying a system's boot configuration from another environment.

--sysroot
    An alias for --target-root, providing an alternative system root path for the operation.

--karg
    Adds a specified kernel argument (KARG) to the boot entry of the new deployment. This option can be specified multiple times to add several kernel arguments.

--karg-remove
    Removes a specified kernel argument (KARG) from the boot entry of the new deployment. This option can be specified multiple times.

--force-atomic
    Forces an atomic switch operation, ensuring the transition is performed transactionally even if bootc determines it's not strictly necessary. This enhances reliability.

--apply-all
    When switching, attempts to apply the change to all detected bootloader entries, ensuring consistency across different boot configurations.

--current-root
    Switches the bootloader configuration to point to the currently running root filesystem. This is invaluable for recovering from a problematic bootc switch or bootc install operation that left the system in an unbootable state.

--dry-run
    Performs a simulated switch operation, displaying what changes would be made without actually modifying the system. Useful for testing and verifying commands before execution.

bootc-switch is a fundamental subcommand of the bootc tool, which is designed for managing host operating systems built from OCI container images. It provides the capability to atomically switch the active root filesystem of a system to a different, previously installed or updated bootc deployment. This command is a cornerstone for enabling robust system updates, reliable rollbacks, and A/B style system management, where a new deployment can be thoroughly tested before being made active, or quickly reverted if issues arise. By modifying the system's bootloader configuration (such as GRUB or systemd-boot), bootc-switch ensures that the system boots into the desired deployment on the next reboot, providing a safe and controlled transition between system states.

The bootc-switch command operates at a critical level of the operating system.

Prerequisites: It requires the system to be managed by bootc and for bootc itself to be correctly installed.

Bootloader Modification: Incorrect or careless use can lead to an unbootable system as it directly modifies bootloader configurations (e.g., GRUB, systemd-boot). Always ensure a backup or recovery plan.

Deployment Existence: The specified DEPLOYMENT_ID must correspond to an existing and valid deployment on the system.

Evolving Tool: bootc is a relatively new and actively developed project. Its behavior, options, and capabilities may evolve between versions, so it's recommended to consult the specific version's documentation or --help output.

bootc-switch is central to bootc's atomic update capabilities. When an update is applied, a new deployment is prepared. bootc-switch then safely transitions the system to this new deployment by updating the bootloader. If the new deployment has issues, bootc-switch (or manual bootloader selection) allows for an immediate rollback to the previous, known-good state, significantly reducing downtime and risk during system upgrades.

This command facilitates an A/B deployment model for the entire operating system. Instead of in-place modifications, new system versions are installed alongside the existing one (e.g., on a 'B' partition while 'A' is active). bootc-switch then flips the active boot partition. This ensures that the old 'A' deployment remains untouched and serves as a quick fallback, providing robust disaster recovery and enabling a safe 'test-before-activate' workflow for system updates.

The bootc project, and consequently the bootc-switch command, emerged from the Red Hat ecosystem, building upon technologies like ostree and the atomic update principles seen in Fedora CoreOS and RHEL CoreOS. Its primary motivation is to bridge the gap between OCI container images and host operating system management, allowing system images to be delivered and updated with the same tooling and practices used for application containers.

bootc-switch is integral to this vision, as it provides the core mechanism for atomically transitioning between different system states, enabling reliable A/B updates and instant rollbacks, which are critical features for modern, cloud-native infrastructure.

bootc(1), bootc-install(1), bootc-update(1), bootc-cleanup(1), ostree(1), grub(8), systemd-boot(7)