fix(file)!: keep image holes, map the input bmap ranges, rename bmap options

Cargo.toml

@@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0"
 name = "omnect-cli"
 readme = "README.md"
 repository = "https://github.com/omnect/omnect-cli"
-version = "0.28.5"
+version = "0.29.0"
 
 [dependencies]
 actix-web = { version = "4.17", default-features = false, features = ["macros"] }
@@ -31,7 +31,7 @@ hmac = { version = "0.13", default-features = false }
 mbrman = { version = "0.6", default-features = false }
 omnect-crypto = { git = "https://github.com/omnect/omnect-crypto.git", tag = "0.5.0" }
 keyring-core = { version = "1.0", default-features = false }
-libfs = { version = "0.9", default-features = false }
+libc = { version = "0.2", default-features = false }
 log = { version = "0.4", default-features = false }
 num_cpus = { version = "1.17", default-features = false }
 oauth2 = { version = "5.0", default-features = false, features = [
@@ -44,10 +44,13 @@ reqwest = { version = "0.13", default-features = false, features = [
     "json",
     "native-tls",
 ] }
+roxmltree = { version = "0.21", default-features = false, features = ["std"] }
+rustix = { version = "1.1", default-features = false, features = ["fs", "std"] }
 serde = { version = "1.0", default-features = false, features = ["derive"] }
 serde_json = { version = "1.0", default-features = false }
 serde_path_to_error = { version = "0.1", default-features = false }
 sha2 = { version = "0.11", default-features = false }
+signal-hook = { version = "0.4", default-features = false, features = ["iterator"] }
 stdext = { version = "0.3", default-features = false }
 strum = { version = "0.28", default-features = false }
 strum_macros = { version = "0.28", default-features = false }
@@ -81,5 +84,5 @@ tar = "0.4"
 
 # metadata for building with cargo-deb (https://crates.io/crates/cargo-deb)
 [package.metadata.deb]
-depends = "bmap-tools, e2tools, keychain, libc6 (>= 2.39), libmagic1, libssl3 (>= 3.0.0), mtools"
+depends = "e2tools, keychain, libc6 (>= 2.39), libmagic1, libssl3 (>= 3.0.0), mtools"
 revision = ""

Dockerfile

@@ -13,7 +13,6 @@ COPY ${debian_dir}/omnect-cli_${omnect_cli_version}_amd64.deb omnect-cli_${omnec
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
-    bmap-tools \
     ca-certificates \
     e2tools \
     fdisk \
@@ -34,14 +33,11 @@ RUN <<EOT
     mkdir -p /copy/status.d /copy/usr/lib
 
     executables=(
-        /usr/bin/dd \
         /usr/bin/e2cp \
         /usr/bin/e2mkdir \
-        /usr/bin/fallocate \
         /usr/bin/mcopy \
         /usr/bin/omnect-cli \
         /usr/bin/ssh-keygen \
-        /usr/bin/sync \
         /usr/sbin/fdisk \
     )
 

README.md

@@ -48,9 +48,8 @@ docker run --rm -it \
   omnect/omnect-cli:latest file copy-to-image --files /source/my-source-file,boot:/my-dest-file -i /source/my-image.wic
   ```
 
-  **Note1**: `-b` option to create bmap file is not supported by omnect-cli docker image.<br>
-  **Note2**: The ssh tunnel option requires some additional settings. See [here](Usage-with-docker) for more details.<br>
-  **Note3**: The docker inject command is not supported by omnect-cli docker image.<br>.
+  **Note1**: The ssh tunnel option requires some additional settings. See [here](Usage-with-docker) for more details.<br>
+  **Note2**: The docker inject command is not supported by omnect-cli docker image.<br>.
 
 # Build from sources
 
@@ -184,6 +183,22 @@ omnect-cli file copy-to-image --help
 - File permissions: inject `systemd-tmpfiles.d`
 - Wifi: inject `wpa_supplicant-wlan0.conf`
 
+## Output image
+
+A command that changes an image writes the result to the input image. For a compressed image it writes the uncompressed image next to it, e.g. `my-image.wic` for `my-image.wic.xz`. With `-p` (`--pack-image`) it adds the extension of the compression (`.xz`, `.bz2` or `.gzip`), e.g. `my-image.wic.xz` for `my-image.wic`. An image that already has an extension of the compression keeps its name, except that `.bzip2` becomes `.bz2`, because `bmaptool` does not read `.bzip2`. `-o` (`--output-image`) writes the result to the given path instead, and the input image stays unchanged. With `-p` its name must end in an extension of the compression that `bmaptool` reads (`.xz`, `.bz2`, `.gzip` or `.gz`), and without `-p` it must not have a compression extension.
+
+The command fails instead of overwriting an existing file that is not the input image. To overwrite it, name it with `-o`. An existing output image must be a regular file, so `-o` cannot name a device or a directory; to write a device, flash the image with `bmaptool copy`. It also fails before it starts if the output image or its bmap exists and is not writable for the user, or if the directory of the new file is not writable. The output image is written to a new file in its directory and then renamed, so the directory needs write access and space for one more image. An existing output image in a directory you cannot write is staged in `TMPDIR` instead and copied into it. Until the rename, the new file is in a hidden `.omnect-cli-*` directory. The command removes it when it ends or is stopped with Ctrl-C, `SIGTERM` or `SIGHUP`. It stays after a `SIGKILL` or a power loss, and you can delete it. A rename cannot replace a mount point, e.g. an image mounted with `docker run -v "$(pwd)/my-image.wic":/source/my-image.wic`, so the new image is staged in `TMPDIR` and copied into it. If this copy fails or is stopped, the new image stays, and the log names it. If the copy fails, the new bmap of `-b` stays next to it. With `-b` the command fails for such a mounted image, because the bmap would be written next to the mount point and not next to the image. Mount the directory instead. The new file belongs to the user who runs `omnect-cli`. `copy-from-image` only reads the image and writes nothing.
+
+A command copies each partition it reads or changes to `TMPDIR` (default `/tmp`). A command that changes an image, or reads a compressed one, also copies the uncompressed image there, and for an output image that is a mount point or in a directory you cannot write also the new image. So `TMPDIR` needs space for all of them. Ctrl-C, `SIGTERM` or `SIGHUP` removes them too. If `/tmp` is a small tmpfs, set `TMPDIR` to a directory with more space.
+
+## bmap files
+
+Commands that change an image create a bmap file with `-b` (`--output-bmap`). It is written next to the output image as `<output image>.bmap`, e.g. `my-image.wic.bmap` for `my-image.wic` and `my-image.wic.xz.bmap` for `my-image.wic.xz`, and replaces a file with this name. An image changed in place keeps the name of its bmap: the command replaces the bmap that `bmaptool` finds for it, e.g. `my-image.wic.bmap` for `-i my-image.wic.xz -p xz`. `bmaptool` finds the bmap there without `--bmap`. The command fails if `bmaptool` would use this file also for an image that stays (`<name>` or `<name>.<compression>` next to it, for which no other bmap comes first), because it would not match that image. E.g. `my-image.wic.bmap` when `-i my-image.wic.xz` writes `my-image.wic`, also if the bmap does not exist yet, or when `-i my-image.wic` changes the image in place and `my-image.wic.xz` without its own bmap is next to it. Choose another output with `-o` then.
+
+The bmap of the input image is the base for it: `omnect-cli` takes the file given with `--input-bmap`, else the bmap next to the image that `bmaptool` would use: `<image>.bmap`, else the same with one extension of the image removed at a time, e.g. `my-image.wic.bmap` for `my-image.wic.xz` as the Yocto build creates it. The input bmap must have the size of the image and sha256 range checksums that match it, otherwise the command fails. A command without `-b` fails if such a bmap exists for the output image (e.g. `my-image.wic.bmap` for `my-image.wic.xz`), because `bmaptool` would use it and it would not match the image. So when you run several commands on one image, use `-b` on each of them. `--no-input-bmap` skips a bmap next to the image that does not match, and the created bmap then maps the whole image. The created bmap maps every range of the input bmap, also when it holds only zeros, so a bmap-based flash overwrites what an earlier installation left there (partition table entries, FAT, ext4 journals). It also maps every block that the image file stores as data, which includes the blocks `omnect-cli` changed. The image file itself stays sparse.
+
+Without an input bmap, the created bmap maps the whole image, and a flash writes every block.
+
 ## ssh tunnel
 
 ### Inject ssh tunnel credentials

project-context.md

@@ -50,15 +50,19 @@
 - `src/docker.rs` — `docker pull --platform` + `docker save` for multi-arch images
 - `src/image.rs` — firmware image architecture detection (ARM32/ARM64/x86_64)
 - `src/file/mod.rs` — high-level image operations: identity config, certs, hostname patching
-- `src/file/functions.rs` — partition read/modify/write via dd + e2cp/mcopy
+- `src/file/functions.rs` — sparse partition read, modify via e2cp/mcopy, write back of changed blocks only
+- `src/file/bmap.rs` — input bmap lookup and checksum check; writes the output bmap: input ranges (or the whole image) plus data blocks
+- `src/file/output.rs` — output image name, conflict checks, staged write and commit of the output image and bmap
+- `src/file/sparse.rs` — data/hole ranges via `SEEK_DATA`/`SEEK_HOLE`, sparse range copy
+- `src/file/signal.rs` — `RegisteredTempDir`: a temp dir that SIGINT/SIGTERM/SIGHUP (unless ignored) also removes
 - `src/file/partition.rs` — GPT/MBR partition table parsing
 - `src/file/compression.rs` — xz/bzip2/gzip compress/decompress with auto-detection
 - `src/validators/` — validation for identity config (TOML), device-update config (JSON), SSH keys
 - `conf/*.template` — 11 config templates (identity, device-update, WiFi)
 
 ## 4. Repository-Specific Constraints
 
-- External tools `e2cp`, `e2mkdir`, `mcopy`, `mmd`, `dd`, `fallocate`, `ssh-keygen`, `fdisk` must be available at runtime (Dockerfile copies them explicitly).
+- External tools `e2cp`, `e2mkdir`, `mcopy`, `mmd`, `ssh-keygen`, `fdisk` must be available at runtime (Dockerfile copies them explicitly).
 - Partition enum maps partition names to numbers differently for GPT vs MBR — see `file/functions.rs`.
 - OAuth2 callback binds to `127.0.0.1:4000` and `[::1]:4000`; container mode overrides to `0.0.0.0`.
 - `conf/` directory uses `.gitignore` to track only `*.template` files — actual configs are generated, never committed.