toolkit: install from local/latest afw + from-stock/restore seams + fix zynq offsets

Integrate the SDK installer into the toolkit so it can put alkane-os on a
compatible miner (for now the Antminer S17 / zynq-7010) from a local .afw or an
auto-pulled latest release, and remove it (back to stock). Release host is the
self-hosted Gitea (GitHub is retired).

- FIX (brick risk): boards/zynq.rs carried the superseded stage-2 offsets
  (BOOTBIN_PRESERVE 0x2200000, kernel 0x2200000, dtb 0x2700000). Corrected to the
  live S17 / SDK-plan layout: BOOT.bin floor 0x1a00000, dtb 0x1a00000, kernel
  0x2000000 (slot 0x800000), rootfs mtd1. The tier-2 update now writes the right
  slots; test updated to the new ceiling.
- alkane-artifacts/fetch.rs: resolve and download the latest .afw for a board
  from Gitea releases/latest (curl + serde_json), token read from
  ALKANE_RELEASE_TOKEN/GITEA_TOKEN at run time and passed via a 0600 curl config,
  never argv, never stored.
- alkane-flash/stock.rs: the seam to the sealed, DSH-owned stock-side methods
  (install-from-stock, restore-to-stock). Interface only - an external
  ALKANE_STOCK_HELPER the toolkit invokes and then verifies the board itself; the
  method is never embedded, read, or reviewed here.
- alkane-cli: new `afw compat` (shows supported boards), `afw fetch-latest`,
  `afw install --latest [--board] [--from-stock]`, and `afw restore-stock`. The
  install/restore commands gate on a supported board. --from-stock routes the
  first install through the sealed helper; the default install path is the
  tier-2 update of a board already on alkane.
- docs/install.md documents the flow and the two env seams.

alkane-artifacts + alkane-flash + alkane-cli build clean, 71 tests pass, the new
files are clippy-clean (the one type_complexity warning is pre-existing in
afw.rs, untouched). No emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
This commit is contained in:
2026-11-10 22:12:47 -06:00
co-authored by Claude Opus 4.8
parent 462ced01a6
commit 400edbe913
7 changed files with 542 additions and 17 deletions
+221
View File
@@ -0,0 +1,221 @@
// SPDX-License-Identifier: MIT
//! Fetch the latest alkane-os `.afw` release from a Gitea repository.
//!
//! GitHub is retired for this project; releases live on the self-hosted Gitea.
//! This resolves `releases/latest`, picks the `.afw` asset for a board, and
//! downloads it so the normal verify -> plan -> preflight -> install flow runs on
//! it exactly as it would on a local file. TLS is required, so this shells out to
//! `curl` (as the GUI already does) rather than the plaintext TCP path used for
//! liveness checks.
//!
//! A private repo needs a token; it is read from the environment at run time
//! (`ALKANE_RELEASE_TOKEN`, else `GITEA_TOKEN`) and passed to curl through a
//! 0600 config file, never on the command line. No token is embedded or stored.
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use serde_json::Value;
use thiserror::Error;
#[derive(Debug, Error)]
pub enum FetchError {
#[error("curl failed: {0}")]
Curl(String),
#[error("release metadata did not parse: {0}")]
Parse(String),
#[error("no .afw asset for board {0} in the latest release")]
NoAsset(String),
#[error("io: {0}")]
Io(String),
}
/// Where releases come from. Defaults to the alkane-os repo on the self-hosted
/// Gitea; the base URL and token are read from the environment.
pub struct ReleaseSource {
pub base_url: String,
pub owner: String,
pub repo: String,
pub token: Option<String>,
}
impl ReleaseSource {
/// The alkane-os release source, honoring `ALKANE_RELEASE_BASE` and a token
/// from `ALKANE_RELEASE_TOKEN` or `GITEA_TOKEN`.
pub fn alkane_os() -> Self {
let base_url = std::env::var("ALKANE_RELEASE_BASE")
.ok()
.filter(|s| !s.is_empty())
.unwrap_or_else(|| "https://gitea.bluefla.re".to_string());
let token = std::env::var("ALKANE_RELEASE_TOKEN")
.ok()
.or_else(|| std::env::var("GITEA_TOKEN").ok())
.filter(|t| !t.is_empty());
Self {
base_url,
owner: "blueflare".to_string(),
repo: "alkane-os".to_string(),
token,
}
}
fn api_latest(&self) -> String {
format!(
"{}/api/v1/repos/{}/{}/releases/latest",
self.base_url.trim_end_matches('/'),
self.owner,
self.repo
)
}
}
/// A temp curl `--config` file carrying the auth header, removed on drop so the
/// token never lands in a process argument or a lingering file.
struct TokenConfig {
path: Option<PathBuf>,
}
impl TokenConfig {
fn new(token: &Option<String>) -> Result<Self, FetchError> {
let Some(token) = token else {
return Ok(Self { path: None });
};
let path = std::env::temp_dir().join(format!("alkane-fetch-{}.cfg", std::process::id()));
write_private(&path, &format!("header = \"Authorization: token {token}\"\n"))?;
Ok(Self { path: Some(path) })
}
fn apply(&self, cmd: &mut Command) {
if let Some(path) = &self.path {
cmd.arg("--config").arg(path);
}
}
}
impl Drop for TokenConfig {
fn drop(&mut self) {
if let Some(path) = &self.path {
let _ = fs::remove_file(path);
}
}
}
#[cfg(unix)]
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
use std::io::Write;
use std::os::unix::fs::OpenOptionsExt;
let mut file = fs::OpenOptions::new()
.write(true)
.create(true)
.truncate(true)
.mode(0o600)
.open(path)
.map_err(|e| FetchError::Io(e.to_string()))?;
file.write_all(contents.as_bytes()).map_err(|e| FetchError::Io(e.to_string()))
}
#[cfg(not(unix))]
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
fs::write(path, contents).map_err(|e| FetchError::Io(e.to_string()))
}
fn curl_bytes(src: &ReleaseSource, url: &str) -> Result<Vec<u8>, FetchError> {
let config = TokenConfig::new(&src.token)?;
let mut cmd = Command::new("curl");
cmd.arg("-fsSL").arg("--max-time").arg("120");
config.apply(&mut cmd);
cmd.arg(url);
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
if !out.status.success() {
return Err(FetchError::Curl(format!(
"{} ({})",
String::from_utf8_lossy(&out.stderr).trim(),
out.status
)));
}
Ok(out.stdout)
}
fn curl_download(src: &ReleaseSource, url: &str, dest: &Path) -> Result<(), FetchError> {
let config = TokenConfig::new(&src.token)?;
let mut cmd = Command::new("curl");
cmd.arg("-fsSL").arg("--max-time").arg("600").arg("-o").arg(dest);
config.apply(&mut cmd);
cmd.arg(url);
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
if !out.status.success() {
return Err(FetchError::Curl(format!(
"{} ({})",
String::from_utf8_lossy(&out.stderr).trim(),
out.status
)));
}
Ok(())
}
/// Resolve the latest release's `.afw` asset for `board`: returns (name, url).
pub fn latest_afw_asset(src: &ReleaseSource, board: &str) -> Result<(String, String), FetchError> {
let body = curl_bytes(src, &src.api_latest())?;
let doc: Value = serde_json::from_slice(&body).map_err(|e| FetchError::Parse(e.to_string()))?;
let assets = doc
.get("assets")
.and_then(Value::as_array)
.ok_or_else(|| FetchError::Parse("no assets array in release".to_string()))?;
let needle = format!("-{board}-");
for asset in assets {
let name = asset.get("name").and_then(Value::as_str).unwrap_or("");
if name.ends_with(".afw") && name.contains(&needle) {
let url = asset
.get("browser_download_url")
.and_then(Value::as_str)
.ok_or_else(|| FetchError::Parse("asset has no download url".to_string()))?;
return Ok((name.to_string(), url.to_string()));
}
}
Err(FetchError::NoAsset(board.to_string()))
}
/// Download the latest `.afw` for `board` into `dest_dir`; returns its path.
pub fn fetch_latest_afw(src: &ReleaseSource, board: &str, dest_dir: &Path) -> Result<PathBuf, FetchError> {
let (name, url) = latest_afw_asset(src, board)?;
fs::create_dir_all(dest_dir).map_err(|e| FetchError::Io(e.to_string()))?;
let dest = dest_dir.join(&name);
curl_download(src, &url, &dest)?;
Ok(dest)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn source_defaults_to_alkane_os_on_gitea() {
std::env::remove_var("ALKANE_RELEASE_BASE");
let src = ReleaseSource::alkane_os();
assert_eq!(src.owner, "blueflare");
assert_eq!(src.repo, "alkane-os");
assert!(src.api_latest().ends_with("/api/v1/repos/blueflare/alkane-os/releases/latest"));
assert!(src.api_latest().starts_with("https://gitea.bluefla.re"));
}
#[test]
fn asset_selection_matches_board_and_extension() {
// The selection logic over a captured release document shape.
let doc = serde_json::json!({
"assets": [
{"name": "SHA256SUMS", "browser_download_url": "u0"},
{"name": "alkane-os-0.1.0-am335x-arm.afw", "browser_download_url": "u1"},
{"name": "alkane-os-0.1.0-zynq-7010-armv7.afw", "browser_download_url": "u2"},
]
});
let assets = doc["assets"].as_array().unwrap();
let board = "zynq-7010";
let needle = format!("-{board}-");
let hit = assets.iter().find(|a| {
let n = a["name"].as_str().unwrap_or("");
n.ends_with(".afw") && n.contains(&needle)
});
assert_eq!(hit.unwrap()["browser_download_url"], "u2");
}
}
+1
View File
@@ -2,6 +2,7 @@
//! Verify local firmware artifacts before an install path consumes them.
pub mod afw;
pub mod fetch;
use sha2::{Digest, Sha256};
use std::collections::HashSet;
+144 -7
View File
@@ -6,6 +6,8 @@
//! the command line. This program never prints a credential value.
use alkane_artifacts::afw::{verify_afw, VerifiedAfw, VerifyOptions};
use alkane_artifacts::fetch::{self, ReleaseSource};
use alkane_flash::stock;
use alkane_artifacts::{seed_manifest, verify_file};
use alkane_core::platform;
use alkane_flash::boards::am335x::{
@@ -450,12 +452,46 @@ fn run_preflight(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
Ok(())
}
/// Install onto a board currently on stock via the sealed from-stock method.
fn install_from_stock_flow(
verified: &VerifiedAfw,
host: &str,
afw: &Path,
opts: &Opts,
) -> Result<(), Box<dyn std::error::Error>> {
if opts.flag("dry-run") {
println!(
"DRY RUN: would install {} onto stock board {host} via the sealed from-stock method ({})",
verified.manifest.board,
afw.display()
);
return Ok(());
}
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to install from stock without --confirm FLASH".into());
}
if !stock::available() {
return Err(
"no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided from-stock installer".into(),
);
}
println!(
"installing {} onto stock board {host} (sealed from-stock method)...",
verified.manifest.board
);
stock::install_from_stock(host, afw)?;
println!("from-stock install reported success.");
println!("verify the board is now reachable as alkane:");
println!(" alkane-cli afw verify-live --host {host} --timeout 300");
Ok(())
}
fn run_install(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(
args,
&[
ssh_values(),
&["held-backup", "backup-dir", "confirm", "expect-board"],
&["held-backup", "backup-dir", "confirm", "expect-board", "board"],
]
.concat(),
&[
@@ -464,13 +500,26 @@ fn run_install(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
"check-golden",
"dry-run",
"no-reboot",
"latest",
"from-stock",
],
)?;
let path = opts
.positionals
.first()
.ok_or("usage: alkane-cli afw install <file> --host <ip> --dry-run|--confirm FLASH")?;
let verified = load_afw(path, &opts)?;
let path = resolve_afw_source(&opts)?;
let verified = load_afw(&path.to_string_lossy(), &opts)?;
if !is_supported(&verified.manifest.board) {
return Err(format!(
"{} is not a supported install target (see: alkane-cli afw compat)",
verified.manifest.board
)
.into());
}
// A board on stock: the first install goes through the sealed from-stock
// method; the tier-2 partition-write path below is for a board already on
// alkane.
if opts.flag("from-stock") {
let host = opts.value("host").ok_or("--host is required")?.to_owned();
return install_from_stock_flow(&verified, &host, &path, &opts);
}
let (ssh, _secret) = ssh_options(&opts, DEFAULT_USER)?;
let mut transport = SshTransport::connect(ssh, true)?;
let backup_dir = opts
@@ -856,12 +905,95 @@ fn latest_backup(dir: &Path) -> Option<PathBuf> {
entries.pop()
}
/// Boards this toolkit can install alkane onto, with the miner each is the
/// control board for. The install/restore gate is the .afw's board matching one
/// of these; `compat` lists them so an operator knows what is supported.
const SUPPORTED: &[(&str, &str)] = &[("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)")];
fn is_supported(board: &str) -> bool {
SUPPORTED.iter().any(|(b, _)| *b == board)
}
fn run_compat(_args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
println!("alkane-os install is supported on:");
for (board, miner) in SUPPORTED {
println!(" {board:<12} {miner}");
}
println!("\nInstall a local bundle: alkane-cli afw install <file.afw> --host <ip> --confirm FLASH");
println!("Install the latest build: alkane-cli afw install --latest --board zynq-7010 --host <ip> --confirm FLASH");
println!("Remove (back to stock): alkane-cli afw restore-stock --host <ip> --confirm FLASH");
Ok(())
}
fn download_dir() -> PathBuf {
platform::config_path("downloads")
}
/// Fetch the latest alkane-os .afw for a board from Gitea into the cache.
fn run_fetch_latest(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, &["board", "output"], &[])?;
let board = opts.value("board").unwrap_or("zynq-7010");
if !is_supported(board) {
return Err(format!("{board} is not a supported install target (see: alkane-cli afw compat)").into());
}
let dest = opts.value("output").map(PathBuf::from).unwrap_or_else(download_dir);
let path = fetch::fetch_latest_afw(&ReleaseSource::alkane_os(), board, &dest)?;
println!("fetched {}", path.display());
Ok(())
}
/// Resolve the .afw either from `--latest` (fetch from Gitea) or a positional
/// file path.
fn resolve_afw_source(opts: &Opts) -> Result<PathBuf, Box<dyn std::error::Error>> {
if opts.flag("latest") {
let board = opts.value("board").unwrap_or("zynq-7010");
if !is_supported(board) {
return Err(format!("{board} is not a supported install target (see: alkane-cli afw compat)").into());
}
println!("fetching the latest {board} release from Gitea...");
let path = fetch::fetch_latest_afw(&ReleaseSource::alkane_os(), board, &download_dir())?;
println!("using {}", path.display());
return Ok(path);
}
opts.positionals
.first()
.map(PathBuf::from)
.ok_or_else(|| "usage: alkane-cli afw install <file>|--latest --host <ip> --confirm FLASH".into())
}
/// Return an alkane board to genuine stock via the sealed stock-restore method,
/// then leave the independent verification to the operator/bench.
fn run_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, &["host", "confirm"], &["dry-run"])?;
let host = opts.value("host").ok_or("--host is required")?;
if !stock::available() {
return Err(
"no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided restore helper".into(),
);
}
if opts.flag("dry-run") {
println!("DRY RUN: would restore {host} to stock via the sealed restore-to-stock method");
return Ok(());
}
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to restore without --confirm FLASH".into());
}
println!("restoring {host} to stock (sealed method)...");
stock::restore_to_stock(host)?;
println!("restore-to-stock reported success.");
println!("verify independently: the board should no longer answer as alkane (no alkane console/API),");
println!("and should present its genuine stock OS. Confirm over the network or serial before reuse.");
Ok(())
}
fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let subcommand = args.first().ok_or(
"usage: alkane-cli afw <verify|inspect|plan|preflight|install|verify-live|restore>",
"usage: alkane-cli afw <compat|fetch-latest|verify|inspect|plan|preflight|install|verify-live|restore|restore-stock>",
)?;
let rest = &args[1..];
match subcommand.as_str() {
"compat" => run_compat(rest),
"fetch-latest" => run_fetch_latest(rest),
"verify" => run_verify(rest),
"inspect" => run_inspect(rest),
"plan" => run_plan(rest),
@@ -869,6 +1001,7 @@ fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
"install" => run_install(rest),
"verify-live" => run_verify_live(rest),
"restore" => run_restore(rest),
"restore-stock" => run_restore_stock(rest),
other => Err(format!("unknown afw subcommand {other}").into()),
}
}
@@ -901,6 +1034,10 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
if command == "-h" || command == "--help" || command == "help" {
println!(
"usage:\n alkane-cli verify-artifact <manifest-path> <local-file>\n \
alkane-cli afw compat\n \
alkane-cli afw fetch-latest [--board zynq-7010] [--output <dir>]\n \
alkane-cli afw install --latest [--board zynq-7010] --host <ip> --confirm FLASH [--from-stock] [ssh options]\n \
alkane-cli afw restore-stock --host <ip> --confirm FLASH\n \
alkane-cli afw verify <file> [--allow-unsigned] [--expect-board <board>]\n \
alkane-cli afw inspect <file> [--allow-unsigned]\n \
alkane-cli afw plan <file> --host <ip> [ssh options]\n \
+18 -10
View File
@@ -6,9 +6,12 @@
//! (FSBL + FPGA bitstream + stock U-Boot) at the front of mtd0.
//!
//! The write offsets are DEVICE-RELATIVE and authoritative here (like the
//! am335x MTD_MAP): kernel at 0x2200000 and dtb at 0x2700000 within /dev/mtd0,
//! rootfs at 0 within /dev/mtd1. The module REFUSES to erase or write /dev/mtd0
//! below BOOTBIN_PRESERVE, so a bad offset can never clobber BOOT.bin.
//! am335x MTD_MAP): dtb at 0x1a00000 and kernel at 0x2000000 within /dev/mtd0,
//! rootfs at 0 within /dev/mtd1 - the layout the on-board stock U-Boot
//! `nandboot` reads, confirmed live on an S17 (alkane-sdk install plan
//! install/plans/zynq-7010.yaml, 2026-11-10). The module REFUSES to erase or
//! write /dev/mtd0 below BOOTBIN_PRESERVE, so a bad offset can never clobber
//! BOOT.bin.
use crate::md5::md5_hex;
use crate::preflight::{classify, parse_digest};
@@ -22,17 +25,21 @@ use thiserror::Error;
pub const BOARD: &str = "zynq-7010";
pub const ARCH: &str = "armv7";
/// mtd0 0x0..0x2200000 is BOOT.bin (FSBL + FPGA bitstream + stock U-Boot) and is
/// NEVER erased or written by this module.
pub const BOOTBIN_PRESERVE: u64 = 0x2200000;
/// mtd0 0x0..0x1a00000 is BOOT.bin (FSBL + FPGA bitstream + stock U-Boot) + the
/// U-Boot env, and is NEVER erased or written by this module. (Was 0x2200000
/// under the superseded stage-2 map; the live S17 layout places the dtb at
/// 0x1a00000, so BOOT.bin ends there.)
pub const BOOTBIN_PRESERVE: u64 = 0x1A00000;
/// Authoritative write targets: (image, device, device-relative offset, ceiling, format).
/// Written rootfs -> dtb -> kernel so a mid-write interruption never leaves a new
/// rootfs under an old kernel.
/// rootfs under an old kernel. Offsets and ceilings match the alkane-sdk install
/// plan (install/plans/zynq-7010.yaml): dtb slot 0x1a00000 (0x600000), kernel
/// slot 0x2000000 (0x800000), rootfs mtd1 (0x2000000).
const TARGETS: [(&str, &str, u64, u64, &str); 3] = [
("rootfs", "/dev/mtd1", 0x0, 0x2000000, "cpio-gzip"),
("dtb", "/dev/mtd0", 0x2700000, 0x20000, "fdt"),
("kernel", "/dev/mtd0", 0x2200000, 0x500000, "zimage"),
("dtb", "/dev/mtd0", 0x1A00000, 0x20000, "fdt"),
("kernel", "/dev/mtd0", 0x2000000, 0x800000, "zimage"),
];
#[derive(Debug, Error)]
@@ -564,7 +571,8 @@ mod tests {
#[test]
fn refuses_an_oversize_kernel() {
let big = zimage(&vec![0u8; 0x500000]);
// Over the kernel-slot ceiling (0x800000).
let big = zimage(&vec![0u8; 0x800001]);
let result = ZynqPlan::from_afw(&afw(big, dtb(), b"\x1f\x8brf".to_vec()));
assert!(matches!(result, Err(ZynqPlanError::ImageTooLarge { .. })));
}
+1
View File
@@ -10,6 +10,7 @@ pub mod boards;
pub mod install;
pub mod md5;
pub mod preflight;
pub mod stock;
pub mod transport;
use alkane_artifacts::VerifiedArtifact;
+86
View File
@@ -0,0 +1,86 @@
// SPDX-License-Identifier: MIT
//! Seam to the stock-side install/restore methods.
//!
//! Three steps trip a stock miner's safeguards: getting our first image onto a
//! stock board past its gates, getting root on stock to flash, and returning an
//! aftermarket board to genuine stock. Those methods are authored and sealed by
//! DeepSeek Harness; the toolkit never embeds, reads, or reviews them. It only
//! invokes an external helper through this fixed interface and then verifies the
//! real board state itself over the network.
//!
//! The helper is located by `ALKANE_STOCK_HELPER` (an absolute path to the
//! dsh-provided executable). It is called as:
//! <helper> install-from-stock --host <ip> --afw <file>
//! <helper> restore-to-stock --host <ip>
//! and must exit 0 on success. Everything the toolkit does around it - acquiring
//! and verifying the .afw, the compat gate, the partition writes for a board
//! already on alkane, the readback, and the post-step liveness verification - is
//! the toolkit's own (Claude's) code.
use std::path::Path;
use std::process::Command;
use thiserror::Error;
#[derive(Debug, Error)]
pub enum StockError {
#[error("no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided helper")]
NotConfigured,
#[error("stock helper {verb} failed: {detail}")]
Helper { verb: String, detail: String },
#[error("io: {0}")]
Io(String),
}
fn helper_path() -> Option<String> {
std::env::var("ALKANE_STOCK_HELPER").ok().filter(|p| !p.is_empty())
}
/// True when a stock helper is configured (the from-stock / to-stock steps are
/// available).
pub fn available() -> bool {
helper_path().is_some()
}
fn run(verb: &str, args: &[&str]) -> Result<(), StockError> {
let helper = helper_path().ok_or(StockError::NotConfigured)?;
let out = Command::new(&helper)
.arg(verb)
.args(args)
.output()
.map_err(|e| StockError::Io(e.to_string()))?;
if !out.status.success() {
return Err(StockError::Helper {
verb: verb.to_string(),
detail: format!("{} ({})", String::from_utf8_lossy(&out.stderr).trim(), out.status),
});
}
Ok(())
}
/// Put our first image onto a board currently on stock (past stock's gates and
/// root-on-stock). After this returns Ok, the caller verifies the board is
/// reachable as alkane.
pub fn install_from_stock(host: &str, afw: &Path) -> Result<(), StockError> {
run("install-from-stock", &["--host", host, "--afw", &afw.to_string_lossy()])
}
/// Return an aftermarket (alkane) board to genuine stock. After this returns Ok,
/// the caller verifies the board is on stock.
pub fn restore_to_stock(host: &str) -> Result<(), StockError> {
run("restore-to-stock", &["--host", host])
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unconfigured_helper_is_reported() {
std::env::remove_var("ALKANE_STOCK_HELPER");
assert!(!available());
assert!(matches!(
install_from_stock("10.0.0.1", Path::new("/tmp/x.afw")),
Err(StockError::NotConfigured)
));
}
}
+71
View File
@@ -0,0 +1,71 @@
# Installing and removing alkane-os
The CLI (`alkane-cli afw ...`) is the supported flashing path. In-app (GUI)
flashing is disabled while that path is reworked; it will call the same engine.
## Compatible miners
```
alkane-cli afw compat
```
Lists the control boards alkane-os can be installed on. For now that is the
Antminer S17 (`zynq-7010`). The install/restore commands refuse any board whose
`.afw` is not one of these.
## Install
From a local bundle:
```
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
--host <miner-ip> --confirm FLASH
```
From the latest release (pulled from Gitea, not GitHub, which is retired):
```
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> --confirm FLASH
# or fetch only:
alkane-cli afw fetch-latest --board zynq-7010 --output ./downloads
```
A private release repo needs a token, read from `ALKANE_RELEASE_TOKEN` (else
`GITEA_TOKEN`) at run time and passed to curl through a 0600 config file - never
on the command line, never stored by the toolkit.
### A board still on stock
Writing our first image onto a board that is still on genuine stock (past the
stock gates and getting root) is done by a sealed helper, not by this toolkit.
Point `ALKANE_STOCK_HELPER` at that helper and add `--from-stock`:
```
ALKANE_STOCK_HELPER=/path/to/helper \
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> \
--from-stock --confirm FLASH
```
The toolkit acquires and verifies the `.afw`, gates on compatibility, invokes
the helper for the stock-side step, then you verify the board came up as alkane:
```
alkane-cli afw verify-live --host <miner-ip> --timeout 300
```
Without `--from-stock`, `install` performs a tier-2 update of a board already on
alkane: it writes the dtb (`/dev/mtd0 @ 0x1a00000`), the kernel
(`/dev/mtd0 @ 0x2000000`) and the rootfs (`/dev/mtd1`), holds a backup of each,
reads them back (md5), and never writes `/dev/mtd0` below `0x1a00000`
(BOOT.bin/FSBL/FPGA/U-Boot are preserved).
## Remove (back to stock)
```
ALKANE_STOCK_HELPER=/path/to/helper \
alkane-cli afw restore-stock --host <miner-ip> --confirm FLASH
```
Returning an aftermarket board to genuine stock is also the sealed helper's job.
The toolkit orchestrates and then you verify independently that the board no
longer answers as alkane and presents its stock OS.