v0.5.5: SFTP-over-SSH remote shares (russh, pure-Rust, ring backend)

Adds SFTP as a third remote ISO-library protocol alongside SMB and NFS.
Pure-Rust russh + russh-sftp on the ring crypto backend — no kernel
mount, no subprocess, no OpenSSL, no new C deps. Like NFS (and unlike
SMB), SFTP-sourced ISOs support HTTP Range requests because SFTP opens
a seekable file handle.

- iso-store: SftpShareManager (connect/auth/READDIR/seekable stream),
  IsoSource::Sftp, password OR SSH-key auth, trust-on-first-use host-key
  pinning, 0600 credential sidecar with a restart-safe derived path.
- http-api: /api/sftp-shares routes, Range-aware ISO dispatch arm,
  status/metrics counts, /api/docs entry, `sftp` terminal commands.
- webui: "SFTP (SSH)" protocol option with a password/key auth toggle,
  host-key fingerprint display, dashboard tile, updated copy.

SCP was deliberately rejected: sequential-only (no Range) and its crates
wrap libssh2 (C + OpenSSL), which would break the static-musl build.

russh is pinned to =0.55.0: russh 0.61 needs the stable RustCrypto
generation (pkcs8 0.11), which is API-incompatible with the release-
candidate crates bergshamra-crypto pins (pkcs8 =0.11.0-rc.11). 0.55 is
the newest russh on the prior generation (pkcs8 0.7) that coexists. Do
not bump past 0.55 until bergshamra adopts stable RustCrypto.

252 tests pass, clippy clean, static musl x86_64 binary (ring already
present via rustls + bergshamra, so no new crypto/C deps).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Cargo.toml

@@ -12,7 +12,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.5.4"
+version = "0.5.5"
 edition = "2021"
 rust-version = "1.95"
 license = "MIT OR Apache-2.0"
@@ -85,6 +85,36 @@ x509-parser = "0.18"
 flate2 = "1.1"
 base64 = "0.22"
 
+# v0.5.5: pure-Rust SSH/SFTP client for reading remote ISO libraries
+# over SFTP without a kernel mount.
+#
+# CRITICAL #1 — crypto backend: `default-features = false` +
+# `features = ["ring"]`. russh's *default* backend is `aws-lc-rs`, which
+# pulls `aws-lc-sys` (C code, fiddly under musl); the `ring` feature
+# instead reuses `ring 0.17` — the exact crate+version already in the
+# binary via rustls + bergshamra — so SFTP adds ZERO new C/crypto deps
+# and the static-musl build stays OpenSSL-free.
+#
+# CRITICAL #2 — pinned to EXACTLY 0.55.0, the newest russh that
+# coexists with bergshamra-crypto (our SAML core). The RustCrypto
+# ecosystem is mid-transition: bergshamra-crypto pins a constellation of
+# release-CANDIDATE crates (`pkcs8 =0.11.0-rc.11` and its matching
+# pkcs5/spki RCs) that are API-incompatible with the STABLE versions of
+# the same crates in the same semver bucket. russh 0.56+ pulls those
+# stable crates (`pkcs5 0.8`), which silently replaces bergshamra's RC
+# copies and breaks compilation. russh ≤0.55 stays on the previous stable
+# generation (`pkcs5 0.7`, `ssh-key 0.6`), which unifies with bergshamra's
+# *stable* deps and leaves the RC bucket untouched — verified to compile.
+# 0.55 still has the merged `russh::keys` API (keys merged at 0.50).
+# IMPORTANT: do NOT bump russh past 0.55 until bergshamra-crypto adopts
+# the stable RustCrypto generation; 0.56+ will not compile in this tree.
+#
+# SCP was deliberately rejected: the protocol is sequential-only (no
+# random access → no HTTP Range, unlike SFTP/NFS) and the mature SCP
+# crates wrap libssh2 (C + OpenSSL), which would break this build.
+russh = { version = "=0.55.0", default-features = false, features = ["ring"] }
+russh-sftp = "2.3"
+
 openpxe-core = { path = "crates/core" }
 openpxe-dhcp-proxy = { path = "crates/dhcp-proxy" }
 openpxe-tftp = { path = "crates/tftp" }

crates/http-api/src/app.rs

@@ -37,8 +37,8 @@ use openpxe_core::{
 };
 use openpxe_ipxe_assets::asset_bytes;
 use openpxe_iso_store::{
-    render_template, IsoCategory, IsoMeta, IsoSource, NfsAddRequest, SmbAddRequest, SmbState,
-    UnattendedKind, UnattendedMeta,
+    render_template, IsoCategory, IsoMeta, IsoSource, NfsAddRequest, SftpAddRequest, SmbAddRequest,
+    SmbState, UnattendedKind, UnattendedMeta,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::json;
@@ -188,6 +188,15 @@ pub fn build_router(state: AppState) -> Router {
         )
         .route("/api/nfs-shares/:id", delete(api_nfs_shares_remove))
         .route("/api/nfs-shares/:id/scan", post(api_nfs_shares_scan))
+        // v0.5.5: SFTP-over-SSH share manager (pure-Rust russh client).
+        // Parallel to SMB/NFS so the UI reuses the same form/error/hint
+        // rendering. Like NFS, SFTP-sourced ISOs support Range requests.
+        .route(
+            "/api/sftp-shares",
+            get(api_sftp_shares_list).post(api_sftp_shares_add),
+        )
+        .route("/api/sftp-shares/:id", delete(api_sftp_shares_remove))
+        .route("/api/sftp-shares/:id/scan", post(api_sftp_shares_scan))
         // Phase 4: Network info (read-only) + DNS edit.
         .route("/api/network", get(api_network).put(api_network_put))
         // Phase 4: live-log stream + recent buffer for the Terminal tab.
@@ -856,6 +865,57 @@ async fn iso_raw(
                 Err(e) => (StatusCode::BAD_GATEWAY, format!("nfs stream: {e}")).into_response(),
             }
         }
+        IsoSource::Sftp {
+            share_id,
+            relative_path,
+        } => {
+            // v0.5.5: SFTP sources support Range requests because SFTP
+            // opens a seekable file handle (seek to offset, then bounded
+            // reads). Identical handling to the NFS arm above.
+            let total = meta.size_bytes;
+            let range = match parse_range(headers.get(header::RANGE), total) {
+                Some(triple) => triple,
+                None if headers.get(header::RANGE).is_some() => {
+                    return Response::builder()
+                        .status(StatusCode::RANGE_NOT_SATISFIABLE)
+                        .header(header::CONTENT_RANGE, format!("bytes */{total}"))
+                        .body(Body::empty())
+                        .unwrap();
+                }
+                // No Range header — serve the whole file.
+                None => (0, total.saturating_sub(1), false),
+            };
+            let (start, end, partial) = range;
+            let len = if total == 0 { 0 } else { end - start + 1 };
+            let max_len = if total == 0 { None } else { Some(len) };
+            match state
+                .sftp_shares
+                .stream_iso(share_id, relative_path, start, max_len)
+                .await
+            {
+                Ok(stream) => {
+                    let body = Body::from_stream(stream);
+                    let status = if partial {
+                        StatusCode::PARTIAL_CONTENT
+                    } else {
+                        StatusCode::OK
+                    };
+                    let mut builder = Response::builder()
+                        .status(status)
+                        .header(header::CONTENT_TYPE, "application/octet-stream")
+                        .header(header::ACCEPT_RANGES, "bytes")
+                        .header(header::CONTENT_LENGTH, len);
+                    if partial {
+                        builder = builder.header(
+                            header::CONTENT_RANGE,
+                            format!("bytes {start}-{end}/{total}"),
+                        );
+                    }
+                    builder.body(body).unwrap()
+                }
+                Err(e) => (StatusCode::BAD_GATEWAY, format!("sftp stream: {e}")).into_response(),
+            }
+        }
     }
 }
 
@@ -1490,6 +1550,19 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "Re-list a share for new ISOs."},
                 ],
             },
+            {
+                "name": "SFTP shares",
+                "endpoints": [
+                    {"method": "GET", "path": "/api/sftp-shares",
+                     "summary": "List configured SFTP-over-SSH shares with connection state and iso counts."},
+                    {"method": "POST", "path": "/api/sftp-shares",
+                     "summary": "Register an SFTP share. Body: { server, export, username, port?, password? | private_key? + passphrase? }. The server's SSH host key is pinned trust-on-first-use."},
+                    {"method": "DELETE", "path": "/api/sftp-shares/:id",
+                     "summary": "Forget a share, drop its entries from the ISO store, and scrub its credentials file."},
+                    {"method": "POST", "path": "/api/sftp-shares/:id/scan",
+                     "summary": "Re-list a share for new ISOs."},
+                ],
+            },
             {
                 "name": "Network",
                 "endpoints": [
@@ -1963,6 +2036,8 @@ struct StatusResponse {
     smb_share_reachable: usize,
     nfs_share_count: usize,
     nfs_share_reachable: usize,
+    sftp_share_count: usize,
+    sftp_share_reachable: usize,
     host_bindings: usize,
     custom_logo: bool,
     branding: BrandingStatus,
@@ -1983,6 +2058,9 @@ async fn api_status(State(state): State<AppState>) -> Json<StatusResponse> {
     let smb_reachable = smb_shares.iter().filter(|m| m.reachable).count();
     let nfs_shares = state.nfs_shares.list();
     let nfs_reachable = nfs_shares.iter().filter(|m| m.reachable).count();
+    // v0.5.5: SFTP shares fold into the same "reachable shares" tile.
+    let sftp_shares = state.sftp_shares.list();
+    let sftp_reachable = sftp_shares.iter().filter(|m| m.reachable).count();
     let isos = state.iso_store.list();
     let clients = state.clients.list();
     let queue_entries = state.queue.list();
@@ -2003,7 +2081,7 @@ async fn api_status(State(state): State<AppState>) -> Json<StatusResponse> {
         .set_queue_counts(queue_entries.len() as u64, imaging as u64);
     state
         .metrics
-        .set_nfs_active((smb_reachable + nfs_reachable) as u64);
+        .set_nfs_active((smb_reachable + nfs_reachable + sftp_reachable) as u64);
     state.metrics.record_http(openpxe_core::HttpRoute::Api);
     let now = time::OffsetDateTime::now_utc();
     let uptime_secs = (now - state.started_at).whole_seconds().max(0);
@@ -2025,6 +2103,9 @@ async fn api_status(State(state): State<AppState>) -> Json<StatusResponse> {
         // metric works regardless of protocol mix.
         nfs_share_count: nfs_shares.len(),
         nfs_share_reachable: nfs_reachable,
+        // v0.5.5: SFTP share counts, summed into the same dashboard tile.
+        sftp_share_count: sftp_shares.len(),
+        sftp_share_reachable: sftp_reachable,
         host_bindings: state.hosts.len(),
         custom_logo: state.branding.has_any_web_logo(),
         branding: BrandingStatus {
@@ -2348,6 +2429,48 @@ async fn api_nfs_shares_scan(
     }
 }
 
+// ─── SFTP share API (v0.5.5) ───────────────────────────────────────────────
+//
+// Parallel to the NFS shares API. The pure-Rust `russh` + `russh-sftp`
+// client gives us in-process listing and streaming, no subprocess. Like
+// NFS (and unlike SMB), SFTP-sourced ISOs support HTTP Range requests —
+// SFTP opens a seekable file handle. Auth is password OR SSH private
+// key; the server's host key is pinned trust-on-first-use.
+
+async fn api_sftp_shares_list(State(state): State<AppState>) -> Json<serde_json::Value> {
+    Json(json!({ "shares": state.sftp_shares.list() }))
+}
+
+async fn api_sftp_shares_add(
+    State(state): State<AppState>,
+    Json(req): Json<SftpAddRequest>,
+) -> Response {
+    match state.sftp_shares.add(req).await {
+        Ok(s) => (StatusCode::CREATED, Json(s)).into_response(),
+        Err(err) => (StatusCode::BAD_REQUEST, Json(err)).into_response(),
+    }
+}
+
+async fn api_sftp_shares_remove(
+    State(state): State<AppState>,
+    AxumPath(id): AxumPath<String>,
+) -> Response {
+    match state.sftp_shares.remove(&id).await {
+        Ok(()) => StatusCode::NO_CONTENT.into_response(),
+        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(),
+    }
+}
+
+async fn api_sftp_shares_scan(
+    State(state): State<AppState>,
+    AxumPath(id): AxumPath<String>,
+) -> Response {
+    match state.sftp_shares.rescan(&id).await {
+        Ok(n) => Json(json!({ "ok": true, "iso_count": n })).into_response(),
+        Err(e) => (StatusCode::BAD_REQUEST, format!("{e}")).into_response(),
+    }
+}
+
 // ─── Network info API ──────────────────────────────────────────────────────
 
 async fn api_network(State(state): State<AppState>) -> Json<serde_json::Value> {
@@ -2715,7 +2838,16 @@ async fn api_metrics(State(state): State<AppState>) -> Response {
         .iter()
         .filter(|m| m.reachable)
         .count();
-    state.metrics.set_nfs_active((smb_ok + nfs_ok) as u64);
+    // v0.5.5: SFTP shares fold into the same reachable-shares gauge.
+    let sftp_ok = state
+        .sftp_shares
+        .list()
+        .iter()
+        .filter(|m| m.reachable)
+        .count();
+    state
+        .metrics
+        .set_nfs_active((smb_ok + nfs_ok + sftp_ok) as u64);
 
     let now = time::OffsetDateTime::now_utc();
     let uptime = (now - state.started_at).whole_seconds().max(0) as u64;

crates/http-api/src/state.rs

@@ -5,7 +5,9 @@ use openpxe_core::{
     AdminStore, BootLog, BrandingStore, ClientRegistry, DeploymentQueue, HostBindings, LogBus,
     Metrics, NotifyStore, SettingsStore, SsoStore,
 };
-use openpxe_iso_store::{IsoStore, NfsShareManager, SmbManager, SmbShareManager, UnattendedStore};
+use openpxe_iso_store::{
+    IsoStore, NfsShareManager, SftpShareManager, SmbManager, SmbShareManager, UnattendedStore,
+};
 use std::sync::Arc;
 use time::OffsetDateTime;
 
@@ -67,6 +69,13 @@ pub struct AppState {
     /// In-process (no subprocess); supports HTTP Range requests on
     /// NFS-sourced ISOs because NFSv3 READ3 takes an explicit offset.
     pub nfs_shares: NfsShareManager,
+    /// v0.5.5: SFTP-over-SSH share manager — pure-Rust userspace
+    /// consumer via `russh` + `russh-sftp` (ring backend, no OpenSSL).
+    /// Ships alongside SMB/NFS as the third remote-library protocol.
+    /// In-process (no subprocess, no kernel mount); supports HTTP Range
+    /// requests because SFTP opens a seekable file handle. Authenticates
+    /// the server's SSH host key on a trust-on-first-use basis.
+    pub sftp_shares: SftpShareManager,
     /// v0.5.2: uploaded unattended-install answer files (Kickstart /
     /// Preseed / Autoinstall / Windows answer files). Served on demand to
     /// booting clients with per-host hostname/IP/MAC templating; lives in

crates/http-api/src/terminal.rs

@@ -96,6 +96,8 @@ async fn dispatch(state: &AppState, argv: &[String]) -> Result<String, String> {
         "share" | "smb-share" => smb_share_command(state, tail).await,
         "smb" => smb_command(state, tail).await,
         "nfs" => nfs_share_command(state, tail).await,
+        // v0.5.5: SFTP-over-SSH remote shares (in-process russh client).
+        "sftp" => sftp_share_command(state, tail).await,
         "log" => log_command(state, tail),
         "whoami" => Ok("operator".to_string()),
         "echo" => Ok(tail.join(" ")),
@@ -118,17 +120,21 @@ fn status_text(s: &AppState) -> String {
     // v0.4.67: NFSv3 sources too.
     let nfs_shares = s.nfs_shares.list();
     let nfs_reachable = nfs_shares.iter().filter(|m| m.reachable).count();
+    // v0.5.5: SFTP-over-SSH sources too.
+    let sftp_shares = s.sftp_shares.list();
+    let sftp_reachable = sftp_shares.iter().filter(|m| m.reachable).count();
     format!(
         "OpenPXE {ver}\n\
          base url:     {base}\n\
          interface:    {nic}\n\
          uptime:       {up}\n\
-         isos:         {n_isos}  (local: {n_local}, smb: {n_smb}, nfs: {n_nfs})\n\
+         isos:         {n_isos}  (local: {n_local}, smb: {n_smb}, nfs: {n_nfs}, sftp: {n_sftp})\n\
          clients:      {n_clients}\n\
          queue:        {n_entries}\n\
          smb server:   {smb}\n\
          smb shares:   {n_smb_total} configured ({n_smb_active} reachable)\n\
-         nfs shares:   {n_nfs_total} configured ({n_nfs_active} reachable)\n",
+         nfs shares:   {n_nfs_total} configured ({n_nfs_active} reachable)\n\
+         sftp shares:  {n_sftp_total} configured ({n_sftp_active} reachable)\n",
         ver = env!("CARGO_PKG_VERSION"),
         base = s.public_base_url,
         nic = if s.nic_name.is_empty() {
@@ -150,6 +156,10 @@ fn status_text(s: &AppState) -> String {
             .iter()
             .filter(|i| matches!(i.source, openpxe_iso_store::IsoSource::Nfs { .. }))
             .count(),
+        n_sftp = isos
+            .iter()
+            .filter(|i| matches!(i.source, openpxe_iso_store::IsoSource::Sftp { .. }))
+            .count(),
         n_clients = clients.len(),
         n_entries = queue_entries.len(),
         smb = smb.map_or_else(|| "(disabled)".into(), |s| format!("{s:?}")),
@@ -157,6 +167,8 @@ fn status_text(s: &AppState) -> String {
         n_smb_active = smb_reachable,
         n_nfs_total = nfs_shares.len(),
         n_nfs_active = nfs_reachable,
+        n_sftp_total = sftp_shares.len(),
+        n_sftp_active = sftp_reachable,
     )
 }
 
@@ -177,6 +189,8 @@ fn isos_text(s: &AppState) -> String {
             openpxe_iso_store::IsoSource::Smb { share_id, .. } => format!("smb:{share_id}"),
             // v0.4.67: NFSv3 via in-process nfs3_client.
             openpxe_iso_store::IsoSource::Nfs { share_id, .. } => format!("nfs:{share_id}"),
+            // v0.5.5: SFTP-over-SSH via in-process russh.
+            openpxe_iso_store::IsoSource::Sftp { share_id, .. } => format!("sftp:{share_id}"),
         };
         let _ = writeln!(
             out,
@@ -321,11 +335,9 @@ async fn smb_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
         }
         Some("add") => {
             // share add //server/share [guest|user:password]
-            let target = args
-                .get(1)
-                .ok_or_else(|| {
-                    "usage: share add //server/share [guest|user:password]".to_string()
-                })?;
+            let target = args.get(1).ok_or_else(|| {
+                "usage: share add //server/share [guest|user:password]".to_string()
+            })?;
             // Accept either `//server/share` (UNC-style) or
             // `server:share` (shorter to type).
             let stripped = target.trim_start_matches('/').trim_start_matches('\\');
@@ -401,11 +413,7 @@ async fn nfs_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
                 return Ok("(no NFS shares configured)".into());
             }
             let mut out = String::new();
-            let _ = writeln!(
-                out,
-                "{:<24} {:<7} {:<6} TARGET",
-                "ID", "STATUS", "ISOS"
-            );
+            let _ = writeln!(out, "{:<24} {:<7} {:<6} TARGET", "ID", "STATUS", "ISOS");
             for m in shares {
                 let status = if m.reachable { "ok" } else { "down" };
                 let _ = writeln!(
@@ -476,6 +484,104 @@ async fn nfs_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
     }
 }
 
+// ── sftp (v0.5.5) ────────────────────────────────────────────────────────
+//
+// Parallel to nfs_share_command. The terminal `add` only supports
+// password auth — pasting a multiline PEM private key through the
+// terminal is impractical, so key-based shares are added via the WebUI.
+
+async fn sftp_share_command(s: &AppState, args: &[String]) -> Result<String, String> {
+    match args.first().map(String::as_str) {
+        None | Some("list") => {
+            let shares = s.sftp_shares.list();
+            if shares.is_empty() {
+                return Ok("(no SFTP shares configured)".into());
+            }
+            let mut out = String::new();
+            let _ = writeln!(out, "{:<24} {:<7} {:<6} TARGET", "ID", "STATUS", "ISOS");
+            for m in shares {
+                let status = if m.reachable { "ok" } else { "down" };
+                let _ = writeln!(
+                    out,
+                    "{:<24} {:<7} {:<6} {}@{}:{}",
+                    truncate(&m.id, 24),
+                    status,
+                    m.iso_count,
+                    m.username,
+                    m.server,
+                    m.export,
+                );
+                if let Some(e) = m.last_error {
+                    let _ = writeln!(out, "    error: {e}");
+                }
+                if let Some(h) = m.last_hint {
+                    let _ = writeln!(out, "    hint:  {h}");
+                }
+            }
+            Ok(out)
+        }
+        Some("add") => {
+            // sftp add <user>@<server>:<export> <password> [port]
+            let target = args.get(1).ok_or_else(|| {
+                "usage: sftp add <user>@<server>:<export> <password> [port] \
+                 (key auth: use the WebUI)"
+                    .to_string()
+            })?;
+            let password = args
+                .get(2)
+                .ok_or_else(|| "a password is required (key auth: use the WebUI)".to_string())?;
+            let (user, rest) = target
+                .split_once('@')
+                .ok_or_else(|| "target must be 'user@server:/export'".to_string())?;
+            let (server, export) = rest
+                .split_once(':')
+                .ok_or_else(|| "target must be 'user@server:/export'".to_string())?;
+            let port = args.get(3).and_then(|s| s.parse::<u16>().ok());
+            let req = openpxe_iso_store::SftpAddRequest {
+                server: server.to_string(),
+                export: export.to_string(),
+                username: Some(user.to_string()),
+                port,
+                password: Some(password.clone()),
+                private_key: None,
+                passphrase: None,
+            };
+            match s.sftp_shares.add(req).await {
+                Ok(m) => Ok(format!("added {} ({} isos)", m.id, m.iso_count)),
+                Err(e) => {
+                    let mut out = format!("add failed: {}", e.error);
+                    if let Some(h) = e.hint {
+                        out.push_str("\nhint: ");
+                        out.push_str(&h);
+                    }
+                    Err(out)
+                }
+            }
+        }
+        Some("remove") => {
+            let id = args
+                .get(1)
+                .ok_or_else(|| "usage: sftp remove <id>".to_string())?;
+            match s.sftp_shares.remove(id).await {
+                Ok(()) => Ok(format!("removed {id}")),
+                Err(e) => Err(format!("remove failed: {e}")),
+            }
+        }
+        Some("scan") => {
+            let id = args
+                .get(1)
+                .ok_or_else(|| "usage: sftp scan <id>".to_string())?;
+            match s.sftp_shares.rescan(id).await {
+                Ok(n) => Ok(format!("re-scanned {id}: {n} isos")),
+                Err(e) => Err(format!("scan failed: {e}")),
+            }
+        }
+        Some(other) => Err(format!(
+            "unknown sftp subcommand: {other}\ntry: sftp [list|add|remove|scan]"
+        )),
+    }
+}
+
 // ── smb ────────────────────────────────────────────────────────────────
 
 #[allow(clippy::unused_async)]
@@ -622,6 +728,11 @@ OpenPXE terminal — available commands:
   nfs remove <id>                   forget an NFS share
   nfs scan <id>                     re-list an NFS share for new ISOs
 
+  sftp list                         list configured SFTP-over-SSH shares
+  sftp add <user>@<srv>:<export> <pass> [port]   add an SFTP share (key auth: WebUI)
+  sftp remove <id>                  forget an SFTP share
+  sftp scan <id>                    re-list an SFTP share for new ISOs
+
   smb status                        outbound Samba state (Windows install media)
   smb start | stop | reload         control the outbound smbd
 

crates/http-api/tests/full_flow.rs

@@ -14,7 +14,7 @@ use axum::body::Body;
 use axum::http::{header, Request, StatusCode};
 use openpxe_core::{ClientRegistry, DeploymentQueue, HostBindings, LogBus, Metrics, SettingsStore};
 use openpxe_http_api::{build_router, AppState};
-use openpxe_iso_store::{IsoStore, NfsShareManager, SmbShareManager};
+use openpxe_iso_store::{IsoStore, NfsShareManager, SftpShareManager, SmbShareManager};
 use tempfile::tempdir;
 use tower::ServiceExt;
 
@@ -96,6 +96,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
     let settings = SettingsStore::load_or_default(dir.path());
     let smb_shares = SmbShareManager::new(dir.path(), iso_store.clone());
     let nfs_shares = NfsShareManager::new(dir.path(), iso_store.clone());
+    let sftp_shares = SftpShareManager::new(dir.path(), iso_store.clone());
     let unattended = openpxe_iso_store::UnattendedStore::new(dir.path().join("unattended"));
     unattended.ensure_dir().await.unwrap();
     let log_bus = LogBus::new(64);
@@ -124,6 +125,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
         smb: None,
         smb_shares,
         nfs_shares,
+        sftp_shares,
         unattended,
         uploads: openpxe_http_api::uploads::UploadSessions::default(),
         log_bus,

crates/iso-store/Cargo.toml

@@ -39,6 +39,10 @@ image = { version = "0.25", default-features = false, features = ["png", "jpeg",
 # kernel mount. See crates/iso-store/src/nfs_share.rs for usage.
 nfs3_client = { workspace = true }
 nfs3_types = { workspace = true }
+# v0.5.5: pure-Rust SSH/SFTP client (ring backend) for the SFTP remote
+# share path. See crates/iso-store/src/sftp_share.rs for usage.
+russh = { workspace = true }
+russh-sftp = { workspace = true }
 # Needed for the Stream trait that wraps the mpsc receiver feeding
 # NFS read-loop bytes into axum's Body::from_stream.
 futures = { workspace = true }

crates/iso-store/src/lib.rs

@@ -20,6 +20,7 @@ pub mod entry;
 pub mod introspect;
 pub mod nfs_share;
 pub mod pxe_logo;
+pub mod sftp_share;
 pub mod smb;
 pub mod smb_share;
 pub mod store;
@@ -40,6 +41,13 @@ pub use smb_share::{SmbAddRequest, SmbShare, SmbShareError, SmbShareManager, Smb
 // "works in any container" property as SMB, plus support for HTTP
 // Range requests because NFSv3 READ3 takes an explicit offset.
 pub use nfs_share::{NfsAddRequest, NfsShare, NfsShareError, NfsShareManager, NfsStream};
+// v0.5.5: SFTP-over-SSH remote shares via the pure-Rust `russh` +
+// `russh-sftp` crates (ring backend — no OpenSSL, no new C deps). Like
+// NFS, supports HTTP Range requests because SFTP opens a seekable file
+// handle. See crates/iso-store/src/sftp_share.rs.
+pub use sftp_share::{
+    SftpAddRequest, SftpAuthKind, SftpShare, SftpShareError, SftpShareManager, SftpStream,
+};
 pub use store::{
     generate_boot_entries_for, slugify_str, IsoCategory, IsoMeta, IsoSource, IsoStore, UploadHandle,
 };

crates/iso-store/src/store.rs

@@ -24,6 +24,10 @@ use tokio::io::AsyncWriteExt;
 /// `nfs3_client` crate (in-process, no subprocess). Same "works in
 /// any container" property as SMB, plus Range requests work because
 /// NFSv3 READ3 takes an explicit offset.
+/// `Sftp` (v0.5.5) — remote SFTP-over-SSH share, streamed via the
+/// pure-Rust `russh` + `russh-sftp` crates (in-process). Like NFS it
+/// supports HTTP Range requests because SFTP opens a seekable file
+/// handle (`SSH_FXP_READ` at offset).
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum IsoSource {
@@ -42,6 +46,13 @@ pub enum IsoSource {
         /// Filename at the export root.
         relative_path: String,
     },
+    /// v0.5.5: SFTP-over-SSH via the in-process `russh` + `russh-sftp`
+    /// crates.
+    Sftp {
+        share_id: String,
+        /// Filename at the export root.
+        relative_path: String,
+    },
 }
 
 /// Where the ISO lands in the PXE menu hierarchy.
@@ -299,11 +310,11 @@ impl IsoStore {
                     None
                 }
             }
-            // SMB and NFS sources have no local path — they're
+            // SMB, NFS, and SFTP sources have no local path — they're
             // streamed in-process. Callers must inspect the source
             // kind first and dispatch to the appropriate share
             // manager.
-            IsoSource::Smb { .. } | IsoSource::Nfs { .. } => None,
+            IsoSource::Smb { .. } | IsoSource::Nfs { .. } | IsoSource::Sftp { .. } => None,
         }
     }
 
@@ -363,9 +374,9 @@ impl IsoStore {
     pub fn drop_external_source(&self, share_id: &str) {
         let mut g = self.inner.write();
         g.isos.retain(|_, m| match &m.source {
-            IsoSource::Smb { share_id: sid, .. } | IsoSource::Nfs { share_id: sid, .. } => {
-                sid != share_id
-            }
+            IsoSource::Smb { share_id: sid, .. }
+            | IsoSource::Nfs { share_id: sid, .. }
+            | IsoSource::Sftp { share_id: sid, .. } => sid != share_id,
             IsoSource::Local => true,
         });
     }
@@ -659,7 +670,10 @@ mod tests {
         // good.
         let s = linux_cmdline(DistroFamily::DebianUbuntu, "ubuntu-24-04");
         assert!(s.contains("boot=casper"), "{s}");
-        assert!(s.contains("iso-url=${base-url}/iso/ubuntu-24-04.iso"), "{s}");
+        assert!(
+            s.contains("iso-url=${base-url}/iso/ubuntu-24-04.iso"),
+            "{s}"
+        );
         assert!(s.contains("ds=nocloud"), "{s}");
         assert!(s.contains("ip=dhcp"), "{s}");
         assert!(!s.contains("netboot=url"), "legacy option leaked: {s}");

crates/openpxe/src/main.rs

@@ -9,7 +9,7 @@ use openpxe_core::{
 };
 use openpxe_dhcp_proxy::DhcpProxyServer;
 use openpxe_http_api::{build_router, AppState};
-use openpxe_iso_store::{IsoStore, NfsShareManager, SmbManager, SmbShareManager};
+use openpxe_iso_store::{IsoStore, NfsShareManager, SftpShareManager, SmbManager, SmbShareManager};
 use openpxe_tftp::TftpServer;
 use std::net::{Ipv4Addr, SocketAddr};
 use std::path::PathBuf;
@@ -100,8 +100,7 @@ async fn main() -> anyhow::Result<()> {
     iso_store.load_from_disk().await?;
     // v0.5.2: unattended answer-file store (Kickstart/Preseed/Autoinstall/
     // Windows answer files). Separate directory from the ISO store.
-    let unattended =
-        openpxe_iso_store::UnattendedStore::new(config.paths.unattended_dir.clone());
+    let unattended = openpxe_iso_store::UnattendedStore::new(config.paths.unattended_dir.clone());
     if let Err(e) = unattended.load_from_disk().await {
         tracing::warn!(
             target: "openpxe::unattended",
@@ -155,6 +154,19 @@ async fn main() -> anyhow::Result<()> {
         );
     }
 
+    // v0.5.5: SFTP-over-SSH share manager — pure-Rust in-process
+    // consumer via `russh` + `russh-sftp` (ring backend, no OpenSSL).
+    // The third remote-library protocol alongside SMB/NFS; like NFS it
+    // works in any container (no subprocess, no kernel mount) and
+    // supports HTTP Range requests because SFTP file handles seek.
+    let sftp_shares = SftpShareManager::new(&config.paths.work_dir, iso_store.clone());
+    if let Err(e) = sftp_shares.load_and_rescan().await {
+        tracing::warn!(
+            target: "openpxe::sftp",
+            "could not reload SFTP shares on startup: {e}"
+        );
+    }
+
     // Sniff network details for the Network tab. None of these are
     // required for PXE to work — they're informational, surfaced in the
     // UI so an operator doesn't have to drop to a shell to find their
@@ -183,6 +195,7 @@ async fn main() -> anyhow::Result<()> {
         smb: Some(smb.clone()),
         smb_shares: smb_shares.clone(),
         nfs_shares: nfs_shares.clone(),
+        sftp_shares: sftp_shares.clone(),
         unattended: unattended.clone(),
         uploads: openpxe_http_api::uploads::UploadSessions::default(),
         log_bus: log_bus.clone(),

crates/webui/src/app.js

@@ -291,11 +291,11 @@
           el('div', {class: 'trend'},
             isos.filter(i => i.introspection.family === 'windows_pe').length + ' Windows · ' +
             isos.filter(i => i.introspection.family !== 'windows_pe').length + ' Linux  ·  ' +
-            // v0.4.67: count both protocols. Label generically since
-            // operators may be using one, the other, or both.
-            ((status.smb_share_reachable || 0) + (status.nfs_share_reachable || 0)) +
+            // v0.4.67+v0.5.5: count all remote-share protocols. Label
+            // generically since operators may use any mix of SMB/NFS/SFTP.
+            ((status.smb_share_reachable || 0) + (status.nfs_share_reachable || 0) + (status.sftp_share_reachable || 0)) +
             ' remote share' +
-            (((status.smb_share_reachable || 0) + (status.nfs_share_reachable || 0)) === 1 ? '' : 's')),
+            (((status.smb_share_reachable || 0) + (status.nfs_share_reachable || 0) + (status.sftp_share_reachable || 0)) === 1 ? '' : 's')),
         ])),
         el('div', {class: 'card'}, el('div', {class: 'stat'}, [
           el('div', {class: 'label'}, 'Uptime'),
@@ -508,10 +508,11 @@
       // v0.4.67: NFSv3 added back as an in-process Rust client
       // (nfs3_client crate). Both protocols available side-by-side;
       // operators pick whichever their NAS prefers.
-      const [isos, settings, smbRes, nfsRes, disk, unattRes] = await Promise.all([
+      const [isos, settings, smbRes, nfsRes, sftpRes, disk, unattRes] = await Promise.all([
         getJSON('/api/isos'), getJSON('/api/settings'),
         getJSON('/api/smb-shares'),
         getJSON('/api/nfs-shares'),
+        getJSON('/api/sftp-shares'),
         getJSON('/api/storage/disk').catch(() => ({
           total_bytes: 0, available_bytes: 0, used_bytes: 0, path: '?',
         })),
@@ -519,6 +520,7 @@
       ]);
       const shares = smbRes.shares || [];
       const nfsShares = nfsRes.shares || [];
+      const sftpShares = sftpRes.shares || [];
       const unattendedFiles = unattRes.files || [];
 
       // ── Upload card ──
@@ -829,6 +831,7 @@
       const protoSelect = el('select', {}, [
         el('option', {value:'nfs'}, 'NFS (NFSv3)'),
         el('option', {value:'smb'}, 'SMB / CIFS'),
+        el('option', {value:'sftp'}, 'SFTP (SSH)'),
       ]);
 
       // SMB inputs.
@@ -893,11 +896,58 @@
         ]),
       ]);
 
+      // SFTP inputs (v0.5.5). Pure-Rust russh client, in-process, so
+      // SFTP-sourced ISOs support HTTP Range like NFS. Auth is password
+      // OR an SSH private key (PEM, optional passphrase); the server's
+      // host key is pinned trust-on-first-use on the first connect.
+      const sftpServerIn = el('input', {type:'text', placeholder:'10.0.0.5'});
+      const sftpExportIn = el('input', {type:'text', placeholder:'/srv/isos'});
+      const sftpUserIn = el('input', {type:'text', placeholder:'root'});
+      const sftpPortIn = el('input', {type:'number', placeholder:'22', min:'1', max:'65535'});
+      const sftpAuthMode = el('select', {}, [
+        el('option', {value:'password'}, 'Password'),
+        el('option', {value:'key'}, 'SSH private key'),
+      ]);
+      const sftpPassIn = el('input', {type:'password', placeholder:'••••••••'});
+      const sftpKeyIn = el('textarea', {rows:'4',
+        placeholder:'-----BEGIN OPENSSH PRIVATE KEY-----',
+        style:'width:100%;font-family:ui-monospace,monospace;font-size:12px;resize:vertical'});
+      const sftpPassphraseIn = el('input', {type:'password',
+        placeholder:'(only if the private key is encrypted)'});
+      const sftpPassBlock = el('label', {class:'field'},
+        [el('span', {class:'name'}, 'Password'), sftpPassIn]);
+      const sftpKeyBlock = el('div', {}, [
+        el('label', {class:'field'},
+          [el('span', {class:'name'}, 'SSH private key (PEM)'), sftpKeyIn]),
+        el('label', {class:'field', style:'margin-top:10px'},
+          [el('span', {class:'name'}, 'Key passphrase (optional)'), sftpPassphraseIn]),
+      ]);
+      const syncSftpAuth = () => {
+        const key = sftpAuthMode.value === 'key';
+        sftpPassBlock.style.display = key ? 'none' : '';
+        sftpKeyBlock.style.display = key ? '' : 'none';
+      };
+      sftpAuthMode.addEventListener('change', syncSftpAuth);
+      syncSftpAuth();
+      const sftpFields = el('div', {}, [
+        el('div', {class:'form-row cols-2'}, [
+          el('label', {class:'field'}, [el('span', {class:'name'}, 'SSH server'), sftpServerIn]),
+          el('label', {class:'field'}, [el('span', {class:'name'}, 'Export path'), sftpExportIn]),
+        ]),
+        el('div', {class:'form-row cols-3', style:'margin-top:14px'}, [
+          el('label', {class:'field'}, [el('span', {class:'name'}, 'Username'), sftpUserIn]),
+          el('label', {class:'field'}, [el('span', {class:'name'}, 'Port'), sftpPortIn]),
+          el('label', {class:'field'}, [el('span', {class:'name'}, 'Auth'), sftpAuthMode]),
+        ]),
+        el('div', {style:'margin-top:14px'}, [sftpPassBlock, sftpKeyBlock]),
+      ]);
+
       // Swap the visible field block + clear any stale message.
       const syncProto = () => {
-        const nfs = protoSelect.value === 'nfs';
-        smbFields.style.display = nfs ? 'none' : '';
-        nfsFields.style.display = nfs ? '' : 'none';
+        const p = protoSelect.value;
+        smbFields.style.display = p === 'smb' ? '' : 'none';
+        nfsFields.style.display = p === 'nfs' ? '' : 'none';
+        sftpFields.style.display = p === 'sftp' ? '' : 'none';
         shareMsg.replaceChildren();
         shareMsg.className = 'msg';
       };
@@ -924,6 +974,40 @@
             shareMsg.className = 'msg ok';
             render('storage');
           } else { await showShareError(r); }
+        } else if (protoSelect.value === 'sftp') {
+          if (!sftpServerIn.value || !sftpExportIn.value || !sftpUserIn.value) {
+            shareMsg.replaceChildren(document.createTextNode('Server, export, and username are required.'));
+            shareMsg.className = 'msg err'; return;
+          }
+          const useKey = sftpAuthMode.value === 'key';
+          if (useKey && !sftpKeyIn.value.trim()) {
+            shareMsg.replaceChildren(document.createTextNode('Paste the SSH private key, or switch Auth to Password.'));
+            shareMsg.className = 'msg err'; return;
+          }
+          if (!useKey && !sftpPassIn.value) {
+            shareMsg.replaceChildren(document.createTextNode('Password is required, or switch Auth to SSH private key.'));
+            shareMsg.className = 'msg err'; return;
+          }
+          shareMsg.replaceChildren(document.createTextNode('Connecting…'));
+          shareMsg.className = 'msg';
+          const body = {
+            server: sftpServerIn.value,
+            export: sftpExportIn.value,
+            username: sftpUserIn.value,
+          };
+          if (sftpPortIn.value) { body.port = parseInt(sftpPortIn.value, 10); }
+          if (useKey) {
+            body.private_key = sftpKeyIn.value;
+            if (sftpPassphraseIn.value) { body.passphrase = sftpPassphraseIn.value; }
+          } else {
+            body.password = sftpPassIn.value;
+          }
+          const r = await postJSON('/api/sftp-shares', body);
+          if (r.ok) {
+            shareMsg.replaceChildren(document.createTextNode('Connected.'));
+            shareMsg.className = 'msg ok';
+            render('storage');
+          } else { await showShareError(r); }
         } else {
           if (!nfsServerIn.value || !nfsExportIn.value) {
             shareMsg.replaceChildren(document.createTextNode('Server and export are required.'));
@@ -962,9 +1046,36 @@
         el('span'),
       ]));
 
-      const totalShares = shares.length + nfsShares.length;
+      const sftpRowEls = sftpShares.map(m => el('div', {class: 'nfs-row' + (m.reachable ? '' : ' down')}, [
+        el('span', {class: 'dot ' + (m.reachable ? 'ok' : 'err')}),
+        el('div', {}, [
+          el('div', {class:'id'}, [el('span', {class:'proto-badge'}, 'SFTP'),
+            document.createTextNode(m.username + '@' + m.server + ':' + m.export)]),
+          el('div', {class:'meta'},
+            'SSH · ' + (m.auth === 'key' ? 'key' : 'password') + ' · ' +
+            (m.reachable ? m.iso_count + ' isos' : 'not reachable')),
+          m.host_key_fingerprint
+            ? el('div', {style:'margin-top:4px;opacity:.65;font-size:11px;font-family:ui-monospace,monospace;word-break:break-all'},
+                'host key ' + m.host_key_fingerprint)
+            : null,
+          m.last_error ? el('div', {class:'err'}, '⚠ ' + m.last_error) : null,
+          m.last_hint ? el('div', {style:'margin-top:4px;opacity:.78;font-size:12px'}, m.last_hint) : null,
+        ]),
+        el('button', {class:'ghost', onclick: async () => {
+          const r = await postJSON('/api/sftp-shares/' + encodeURIComponent(m.id) + '/scan', {});
+          if (r.ok) render('storage');
+        }}, 'Re-scan'),
+        el('button', {class:'danger', onclick: async () => {
+          if (!confirm('Forget ' + m.server + ':' + m.export + '?')) return;
+          await fetch('/api/sftp-shares/' + encodeURIComponent(m.id), {method:'DELETE'});
+          render('storage');
+        }}, 'Remove'),
+        el('span'),
+      ]));
+
+      const totalShares = shares.length + nfsShares.length + sftpShares.length;
       const remoteRows = totalShares
-        ? [...smbRowEls, ...nfsRowEls]
+        ? [...smbRowEls, ...nfsRowEls, ...sftpRowEls]
         : [el('div', {class:'empty'}, 'No remote shares configured.')];
       syncProto();
 
@@ -1071,13 +1182,13 @@
               ]),
               el('span'),
             ]),
-            el('div', {style:'margin-top:14px'}, [smbFields, nfsFields]),
+            el('div', {style:'margin-top:14px'}, [smbFields, nfsFields, sftpFields]),
             addShare, shareMsg,
             el('div', {style:'margin-top:18px;display:grid;gap:8px'}, remoteRows),
             el('p', {class:'msg', style:'margin-top:14px'},
               'Remote .iso libraries are read on demand — no local cache to ' +
-              'preserve disk usage. Support for NFS 3.0 and SMB. Ensure that ' +
-              'the hosts IP address is provisioned.'),
+              'preserve disk usage. Support for NFS 3.0, SMB, and SFTP (SSH). ' +
+              'Ensure that the hosts IP address is provisioned.'),
           ]),
         ]),
         el('div', {class:'card'}, [