lib: Add --download-only flag for upgrade

Add support for downloading and staging updates without automatic
application on reboot. This allows users to prepare updates and apply
them at a controlled time.

User-facing changes:
- Add --download-only flag to bootc upgrade command
- bootc upgrade --download-only: locks staged deployment
- bootc upgrade (no flags): unlocks locked staged deployment
- bootc upgrade --apply: unlocks and immediately reboots
- bootc upgrade --check: read-only, doesn't change lock state
- bootc status --verbose: shows "Locked: yes/no" for staged deployments

Implementation details:
- Internally uses OSTree finalization locking APIs
- Sets opts.locked in SysrootDeployTreeOpts when staging deployments
- Added change_finalization() method to SysrootLock wrapper
- Handles lock state transitions for existing staged deployments
- Field name in BootEntry is finalization_locked for clarity
- Display name is shortened to "Locked" for user convenience
- Uses deployment.is_finalization_locked() API (OSTree v2023.8+)

Testing and documentation:
- Added TMT integration test (test-upgrade-download-only.nu)
- Test verifies 3-boot workflow: lock, reboot (stays old), unlock, reboot (applies)
- Updated docs/src/upgrades.md with comprehensive workflow examples
- Generated man pages and JSON schemas updated

The download-only flag is only available for upgrade, not switch.
The implementation is designed to support future composefs backend.

Assisted-by: Claude Code (Sonnet 4.5)
Signed-off-by: Wei Shi <wshi@redhat.com>

Author: shi2wei3

crates/lib/src/bootc_composefs/status.rs

@@ -234,6 +234,7 @@ async fn boot_entry_from_composefs_deployment(
         cached_update: None,
         incompatible: false,
         pinned: false,
+        finalization_locked: false, // Not yet supported for composefs backend
         store: None,
         ostree: None,
         composefs: Some(crate::spec::BootEntryComposefs {

crates/lib/src/cli.rs

@@ -100,6 +100,13 @@ pub(crate) struct UpgradeOpts {
     #[clap(long = "soft-reboot", conflicts_with = "check")]
     pub(crate) soft_reboot: Option<SoftRebootMode>,
 
+    /// Download and stage the update without applying it.
+    ///
+    /// The update will be downloaded and staged, but will not be applied automatically on reboot.
+    /// Use `bootc upgrade --apply` to apply the staged update.
+    #[clap(long, conflicts_with_all = ["check", "apply"])]
+    pub(crate) download_only: bool,
+
     #[clap(flatten)]
     pub(crate) progress: ProgressOptions,
 }
@@ -957,6 +964,26 @@ async fn upgrade(
             .unwrap_or_default();
         if staged_unchanged {
             println!("Staged update present, not changed.");
+            let staged_deployment = storage.get_ostree()?.staged_deployment();
+            if let Some(staged) = staged_deployment {
+                // Handle finalization locking based on flags
+                if opts.download_only {
+                    // --download-only: lock the deployment
+                    if !staged.is_finalization_locked() {
+                        storage.get_ostree()?.change_finalization(&staged)?;
+                        println!("Locked staged deployment.");
+                    }
+                } else if !opts.check {
+                    // --apply or no flags: unlock the deployment
+                    // (skip if --check, which is read-only)
+                    if staged.is_finalization_locked() {
+                        storage.get_ostree()?.change_finalization(&staged)?;
+                        println!("Unlocked staged deployment.");
+                    }
+                }
+            } else if opts.download_only || opts.apply {
+                anyhow::bail!("No staged deployment found");
+            }
             handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
             if opts.apply {
                 crate::reboot::reboot()?;
@@ -966,7 +993,15 @@ async fn upgrade(
         } else {
             let stateroot = booted_ostree.stateroot();
             let from = MergeState::from_stateroot(storage, &stateroot)?;
-            crate::deploy::stage(storage, from, &fetched, &spec, prog.clone()).await?;
+            crate::deploy::stage(
+                storage,
+                from,
+                &fetched,
+                &spec,
+                prog.clone(),
+                opts.download_only,
+            )
+            .await?;
             changed = true;
             if let Some(prev) = booted_image.as_ref() {
                 if let Some(fetched_manifest) = fetched.get_manifest(repo)? {
@@ -1071,7 +1106,7 @@ async fn switch_ostree(
 
     let stateroot = booted_ostree.stateroot();
     let from = MergeState::from_stateroot(storage, &stateroot)?;
-    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone()).await?;
+    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone(), false).await?;
 
     storage.update_mtime()?;
 
@@ -1200,7 +1235,7 @@ async fn edit_ostree(
 
     let stateroot = booted_ostree.stateroot();
     let from = MergeState::from_stateroot(storage, &stateroot)?;
-    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone()).await?;
+    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone(), false).await?;
 
     storage.update_mtime()?;
 

crates/lib/src/deploy.rs

@@ -581,6 +581,7 @@ async fn deploy(
     from: MergeState,
     image: &ImageState,
     origin: &glib::KeyFile,
+    lock_finalization: bool,
 ) -> Result<Deployment> {
     // Compute the kernel argument overrides. In practice today this API is always expecting
     // a merge deployment. The kargs code also always looks at the booted root (which
@@ -608,6 +609,9 @@ async fn deploy(
             let stateroot = Some(stateroot);
             let mut opts = ostree::SysrootDeployTreeOpts::default();
 
+            // Set finalization lock if requested
+            opts.locked = lock_finalization;
+
             // Because the C API expects a Vec<&str>, convert the Cmdline to string slices.
             // The references borrow from the Cmdline, which outlives this usage.
             let override_kargs_refs = override_kargs
@@ -691,6 +695,7 @@ pub(crate) async fn stage(
     image: &ImageState,
     spec: &RequiredHostSpec<'_>,
     prog: ProgressWriter,
+    lock_finalization: bool,
 ) -> Result<()> {
     // Log the staging operation to systemd journal with comprehensive upgrade information
     const STAGE_JOURNAL_ID: &str = "8f7a2b1c3d4e5f6a7b8c9d0e1f2a3b4c";
@@ -748,7 +753,8 @@ pub(crate) async fn stage(
     })
     .await;
     let origin = origin_from_imageref(spec.image)?;
-    let deployment = crate::deploy::deploy(sysroot, from, image, &origin).await?;
+    let deployment =
+        crate::deploy::deploy(sysroot, from, image, &origin, lock_finalization).await?;
 
     subtask.completed = true;
     subtasks.push(subtask.clone());

crates/lib/src/fixtures/spec-staged-locked.yaml

@@ -0,0 +1,45 @@
+apiVersion: org.containers.bootc/v1alpha1
+kind: BootcHost
+metadata:
+  name: host
+spec:
+  image:
+    image: quay.io/example/someimage:latest
+    transport: registry
+    signature: insecure
+status:
+  staged:
+    image:
+      image:
+        image: quay.io/example/someimage:latest
+        transport: registry
+        signature: insecure
+      architecture: arm64
+      version: nightly
+      timestamp: 2023-10-14T19:22:15.42Z
+      imageDigest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566
+    incompatible: false
+    pinned: false
+    finalizationLocked: true
+    ostree:
+      checksum: 3c6dad657109522e0b2e49bf44b5420f16f0b438b5b9357e5132211cfbad135d
+      deploySerial: 0
+      stateroot: default
+  booted:
+    image:
+      image:
+        image: quay.io/example/someimage:latest
+        transport: registry
+        signature: insecure
+      architecture: arm64
+      version: nightly
+      timestamp: 2023-09-30T19:22:16Z
+      imageDigest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34
+    incompatible: false
+    pinned: false
+    ostree:
+      checksum: 26836632adf6228d64ef07a26fd3efaf177104efd1f341a2cf7909a3e4e2c72c
+      deploySerial: 0
+      stateroot: default
+  rollback: null
+  isContainer: false

crates/lib/src/install.rs

@@ -2383,7 +2383,7 @@ pub(crate) async fn install_reset(opts: InstallResetOpts) -> Result<()> {
         stateroot: target_stateroot.clone(),
         kargs,
     };
-    crate::deploy::stage(sysroot, from, &fetched, &spec, prog.clone()).await?;
+    crate::deploy::stage(sysroot, from, &fetched, &spec, prog.clone(), false).await?;
 
     // Copy /boot entry from /etc/fstab to the new stateroot if it exists
     if let Some(boot_spec) = read_boot_fstab_entry(rootfs)? {

crates/lib/src/spec.rs

@@ -227,6 +227,10 @@ pub struct BootEntry {
     /// This is true if (relative to the booted system) this is a possible target for a soft reboot
     #[serde(default)]
     pub soft_reboot_capable: bool,
+    /// Whether this deployment is locked from automatic finalization on shutdown
+    #[serde(default)]
+    #[serde(skip_serializing_if = "is_false")]
+    pub finalization_locked: bool,
     /// The container storage backend
     #[serde(default)]
     pub store: Option<Store>,
@@ -236,6 +240,11 @@ pub struct BootEntry {
     pub composefs: Option<BootEntryComposefs>,
 }
 
+// Helper function for serde skip_serializing_if
+fn is_false(b: &bool) -> bool {
+    !b
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
@@ -628,6 +637,7 @@ mod tests {
                 incompatible: false,
                 soft_reboot_capable: false,
                 pinned: false,
+                finalization_locked: false,
                 store: None,
                 ostree: None,
                 composefs: None,

crates/lib/src/status.rs

@@ -267,12 +267,14 @@ fn boot_entry_from_deployment(
     };
 
     let soft_reboot_capable = has_soft_reboot_capability(sysroot, deployment);
+    let finalization_locked = deployment.is_staged() && deployment.is_finalization_locked();
     let store = Some(crate::spec::Store::OstreeContainer);
     let r = BootEntry {
         image,
         cached_update,
         incompatible,
         soft_reboot_capable,
+        finalization_locked,
         store,
         pinned: deployment.is_pinned(),
         ostree: Some(crate::spec::BootEntryOstree {
@@ -493,7 +495,7 @@ pub(crate) async fn status(opts: super::cli::StatusOpts) -> Result<()> {
     Ok(())
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone, Copy)]
 pub enum Slot {
     Staged,
     Booted,
@@ -563,6 +565,33 @@ fn write_soft_reboot(
     Ok(())
 }
 
+/// Helper function to render finalization lock status
+fn write_finalization_locked(
+    mut out: impl Write,
+    slot: Option<Slot>,
+    entry: &crate::spec::BootEntry,
+    prefix_len: usize,
+) -> Result<()> {
+    // Always show lock status for staged deployments
+    if matches!(slot, Some(Slot::Staged)) {
+        write_row_name(&mut out, "Locked", prefix_len)?;
+        writeln!(
+            out,
+            "{}",
+            if entry.finalization_locked {
+                "yes"
+            } else {
+                "no"
+            }
+        )?;
+    } else if entry.finalization_locked {
+        // For non-staged deployments, only show if locked
+        write_row_name(&mut out, "Locked", prefix_len)?;
+        writeln!(out, "yes")?;
+    }
+    Ok(())
+}
+
 /// Write the data for a container image based status.
 fn human_render_slot(
     mut out: impl Write,
@@ -654,6 +683,9 @@ fn human_render_slot(
 
         // Show soft-reboot capability
         write_soft_reboot(&mut out, entry, prefix_len)?;
+
+        // Show finalization lock status
+        write_finalization_locked(&mut out, slot, entry, prefix_len)?;
     }
 
     tracing::debug!("pinned={}", entry.pinned);
@@ -694,6 +726,9 @@ fn human_render_slot_ostree(
 
         // Show soft-reboot capability
         write_soft_reboot(&mut out, entry, prefix_len)?;
+
+        // Show finalization lock status
+        write_finalization_locked(&mut out, slot, entry, prefix_len)?;
     }
 
     tracing::debug!("pinned={}", entry.pinned);
@@ -941,4 +976,46 @@ mod tests {
         assert!(w.contains("Commit:"));
         assert!(w.contains("Soft-reboot:"));
     }
+
+    #[test]
+    fn test_human_readable_staged_locked() {
+        // Test that locked staged deployment shows the lock status in non-verbose mode
+        // Lock status is only shown in verbose mode per design
+        let w = human_status_from_spec_fixture(include_str!("fixtures/spec-staged-locked.yaml"))
+            .expect("No spec found");
+        let expected = indoc::indoc! { r"
+            Staged image: quay.io/example/someimage:latest
+                  Digest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566 (arm64)
+                 Version: nightly (2023-10-14T19:22:15Z)
+
+          ● Booted image: quay.io/example/someimage:latest
+                  Digest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34 (arm64)
+                 Version: nightly (2023-09-30T19:22:16Z)
+        "};
+        similar_asserts::assert_eq!(w, expected);
+    }
+
+    #[test]
+    fn test_human_readable_staged_locked_verbose() {
+        // Test that locked status is shown in verbose mode for staged deployments
+        let w = human_status_from_spec_fixture_verbose(include_str!(
+            "fixtures/spec-staged-locked.yaml"
+        ))
+        .expect("No spec found");
+
+        // Verbose output should include lock status
+        assert!(w.contains("Locked: yes"));
+    }
+
+    #[test]
+    fn test_human_readable_staged_unlocked_verbose() {
+        // Test that unlocked staged deployment shows "Locked: no" in verbose mode
+        let w = human_status_from_spec_fixture_verbose(include_str!(
+            "fixtures/spec-staged-booted.yaml"
+        ))
+        .expect("No spec found");
+
+        // Verbose output should include lock status as "no" for unlocked staged deployments
+        assert!(w.contains("Locked: no"));
+    }
 }

crates/ostree-ext/src/sysroot.rs

@@ -170,6 +170,27 @@ impl SysrootLock {
             unowned: true,
         }
     }
+
+    /// Toggle the finalization lock state of a staged deployment.
+    /// If the deployment is currently locked, it will be unlocked, and vice versa.
+    /// The deployment must be a staged deployment.
+    #[allow(unsafe_code)]
+    pub fn change_finalization(&self, deployment: &ostree::Deployment) -> Result<()> {
+        use ostree::glib::translate::*;
+        use std::ptr;
+        unsafe {
+            let mut error = ptr::null_mut();
+            let result = ostree::ffi::ostree_sysroot_change_finalization(
+                self.sysroot.to_glib_none().0,
+                deployment.to_glib_none().0,
+                &mut error,
+            );
+            if result == 0 {
+                return Err(from_glib_full::<_, ostree::glib::Error>(error).into());
+            }
+            Ok(())
+        }
+    }
 }
 
 #[cfg(test)]

docs/src/host-v1.schema.json

@@ -65,6 +65,10 @@
             }
           ]
         },
+        "finalizationLocked": {
+          "description": "Whether this deployment is locked from automatic finalization on shutdown",
+          "type": "boolean"
+        },
         "image": {
           "description": "The image reference",
           "anyOf": [
@@ -199,7 +203,7 @@
       "description": "Bootloader type to determine whether system was booted via Grub or Systemd",
       "oneOf": [
         {
-          "description": "Use Grub as the booloader",
+          "description": "Use Grub as the bootloader",
           "type": "string",
           "const": "Grub"
         },

docs/src/man/bootc-install-print-configuration.8.md

@@ -19,7 +19,13 @@ filesystem type from the container image.
 At the current time, the only output key is `root-fs-type` which is a
 string-valued filesystem name suitable for passing to `mkfs.\$type`.
 
+# OPTIONS
+
 <!-- BEGIN GENERATED OPTIONS -->
+**--all**
+
+    Print all configuration
+
 <!-- END GENERATED OPTIONS -->
 
 # VERSION