utils: add BOOTC_EXP_EXTERNAL_CONTAINER_TOOL env override

Add a single environment variable that allows callers to substitute an
alternative binary for both podman and skopeo without creating hard
links or symlinks on the filesystem. The _EXP prefix makes clear that
this interface is experimental and subject to change.

BOOTC_EXP_EXTERNAL_CONTAINER_TOOL defaults to the conventional tool
name ("podman" or "skopeo") when unset, preserving existing behaviour.
Helper functions podman_bin() and skopeo_bin() are added to
bootc-internal-utils and used at every call site across crates/lib
and crates/ostree-ext.

This unblocks downstream projects that ship a single alternative
binary (e.g. dtool) in place of both tools by pointing the env var
at that binary rather than hard-linking it into /usr/bin.

Assisted-by: OpenCode (claude-sonnet-4-6)
Signed-off-by: Eric Curtin <eric.curtin@docker.com>

Author: ericcurtin

crates/lib/src/cli.rs

@@ -1853,7 +1853,7 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
                         );
                     }
                     // And ensure we're finding the image in the host storage
-                    let mut cmd = Command::new("skopeo");
+                    let mut cmd = Command::new(bootc_utils::skopeo_bin());
                     set_additional_image_store(&mut cmd, "/run/host-container-storage");
                     proxycfg.skopeo_cmd = Some(cmd);
                     iid

crates/lib/src/deploy.rs

@@ -9,6 +9,7 @@ use std::process::Command;
 
 use anyhow::{Context, Result, anyhow};
 use bootc_kernel_cmdline::utf8::CmdlineOwned;
+use bootc_utils::skopeo_bin;
 use cap_std::fs::{Dir, MetadataExt};
 use cap_std_ext::cap_std;
 use cap_std_ext::dirext::CapStdExtDirExt;
@@ -557,7 +558,7 @@ pub(crate) async fn prepare_for_pull_unified(
 
     // Configure the importer to use bootc storage as an additional image store
     let mut config = new_proxy_config();
-    let mut cmd = Command::new("skopeo");
+    let mut cmd = Command::new(skopeo_bin());
     // Use the physical path to bootc storage from the Storage struct
     let storage_path = format!(
         "{}/{}",

crates/lib/src/image.rs

@@ -30,7 +30,7 @@ pub(crate) const IMAGE_DEFAULT: &str = "localhost/bootc";
 /// get structured responses.
 async fn image_exists_in_host_storage(image: &str) -> Result<bool> {
     use tokio::process::Command as AsyncCommand;
-    let mut cmd = AsyncCommand::new("podman");
+    let mut cmd = AsyncCommand::new(bootc_utils::podman_bin());
     cmd.args(["image", "exists", image]);
     Ok(cmd.status().await?.success())
 }

crates/lib/src/podman.rs

@@ -24,7 +24,7 @@ pub(crate) struct ImageListEntry {
 /// Given an image ID, return its manifest digest
 pub(crate) fn imageid_to_digest(imgid: &str) -> Result<String> {
     use bootc_utils::CommandRunExt;
-    let o: Vec<Inspect> = crate::install::run_in_host_mountns("podman")?
+    let o: Vec<Inspect> = crate::install::run_in_host_mountns(bootc_utils::podman_bin())?
         .args(["inspect", imgid])
         .run_and_parse_json()?;
     let i = o

crates/lib/src/podman_client.rs

@@ -100,7 +100,7 @@ impl PodmanClient {
         std::fs::create_dir_all("/run/bootc/").ok();
         let _ = std::fs::remove_file(&socket_path);
 
-        let mut cmd = std::process::Command::new("podman");
+        let mut cmd = std::process::Command::new(bootc_utils::podman_bin());
         let mut fds = CmdFds::new();
         crate::podstorage::bind_storage_roots(&mut cmd, &mut fds, storage_root, run_root)?;
         crate::podstorage::setup_auth(&mut cmd, &mut fds, sysroot)?;
@@ -252,7 +252,7 @@ impl PodmanClient {
         tracing::debug!(
             "Image uses non-docker transport, falling back to podman pull subprocess: {image}"
         );
-        let mut cmd = Command::new("podman");
+        let mut cmd = Command::new(bootc_utils::podman_bin());
         let mut fds = CmdFds::new();
         crate::podstorage::bind_storage_roots(
             &mut cmd,

crates/lib/src/podstorage.rs

@@ -167,7 +167,7 @@ pub(crate) fn setup_auth(cmd: &mut Command, fds: &mut CmdFds, sysroot: &Dir) ->
 // - storage overridden to point to to storage_root
 // - Authentication (auth.json) using the bootc/ostree owned auth
 fn new_podman_cmd_in(sysroot: &Dir, storage_root: &Dir, run_root: &Dir) -> Result<Command> {
-    let mut cmd = Command::new("podman");
+    let mut cmd = Command::new(bootc_utils::podman_bin());
     let mut fds = CmdFds::new();
     bind_storage_roots(&mut cmd, &mut fds, storage_root, run_root)?;
     let run_root = format!("/proc/self/fd/{STORAGE_RUN_FD}");
@@ -201,7 +201,7 @@ pub fn set_additional_image_store<'c>(
 ///
 /// Call this function any time we're going to write to containers-storage.
 pub(crate) fn ensure_floating_c_storage_initialized() {
-    if let Err(e) = Command::new("podman")
+    if let Err(e) = Command::new(bootc_utils::podman_bin())
         .args(["system", "info"])
         .stdout(Stdio::null())
         .run_capture_stderr()
@@ -447,7 +447,7 @@ impl CStorage {
     /// to this storage.
     #[context("Pulling from host storage: {image}")]
     pub(crate) async fn pull_from_host_storage(&self, image: &str) -> Result<()> {
-        let mut cmd = Command::new("podman");
+        let mut cmd = Command::new(bootc_utils::podman_bin());
         cmd.stdin(Stdio::null());
         cmd.stdout(Stdio::null());
         // An ephemeral place for the transient state;

crates/ostree-ext/src/container/mod.rs

@@ -588,7 +588,7 @@ pub fn merge_default_container_proxy_opts_with_isolation(
         if let Some(authfile) = config.authfile.take() {
             config.auth_data = Some(std::fs::File::open(authfile)?);
         }
-        let cmd = crate::isolation::unprivileged_subprocess("skopeo", user);
+        let cmd = crate::isolation::unprivileged_subprocess(bootc_utils::skopeo_bin(), user);
         config.skopeo_cmd = Some(cmd);
     }
     Ok(())

crates/ostree-ext/src/container/skopeo.rs

@@ -51,7 +51,7 @@ pub(crate) fn container_policy_is_default_insecure() -> Result<bool> {
 
 /// Create a Command builder for skopeo.
 pub(crate) fn new_cmd() -> std::process::Command {
-    let mut cmd = std::process::Command::new("skopeo");
+    let mut cmd = std::process::Command::new(bootc_utils::skopeo_bin());
     cmd.stdin(Stdio::null());
     cmd
 }

crates/utils/src/lib.rs

@@ -22,6 +22,28 @@ pub use tracing_util::*;
 /// The name of our binary
 pub const NAME: &str = "bootc";
 
+/// Return the podman binary path, honouring the `BOOTC_EXP_EXTERNAL_CONTAINER_TOOL`
+/// environment variable so callers can substitute an alternative tool (e.g. `dtool`)
+/// without hard-linking it as `/usr/bin/podman`. The _EXP prefix indicates this
+/// interface is experimental and subject to change.
+pub fn podman_bin() -> &'static str {
+    static BIN: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+    BIN.get_or_init(|| {
+        std::env::var("BOOTC_EXP_EXTERNAL_CONTAINER_TOOL").unwrap_or_else(|_| "podman".to_string())
+    })
+}
+
+/// Return the skopeo binary path, honouring the `BOOTC_EXP_EXTERNAL_CONTAINER_TOOL`
+/// environment variable so callers can substitute an alternative tool (e.g. `dtool`)
+/// without hard-linking it as `/usr/bin/skopeo`. The _EXP prefix indicates this
+/// interface is experimental and subject to change.
+pub fn skopeo_bin() -> &'static str {
+    static BIN: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+    BIN.get_or_init(|| {
+        std::env::var("BOOTC_EXP_EXTERNAL_CONTAINER_TOOL").unwrap_or_else(|_| "skopeo".to_string())
+    })
+}
+
 /// Intended for use in `main`, calls an inner function and
 /// handles errors by printing them.
 pub fn run_main<F>(f: F)