Skip to content
mrlarsendkPublic

About

A tiny USB image writer for Linux — TUI, unprivileged via udisks2, O_DIRECT fast, verify built in

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

etchling

A tiny USB image writer for Linux — pick a .iso/.img, pick a stick, write, verify. A lightweight alternative to balenaEtcher: one ~3 MB static-ish binary, a terminal UI, and udisks2 doing the privileged work.

┌ Image ──────────────────────────────────────────────────────────┐
│ /home/you/iso/archlinux-x86_64.iso                              │
│ 1.2 GB — raw image                                              │
│ SHA256  e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934c…       │
├ Device ─────────────────────────────────────────────────────────┤
│ ▸ Kingston DataTraveler — 32.0 GB (/dev/sdb)                    │
│   SanDisk Ultra — 64.1 GB (/dev/sdc)                            │
├ Options ────────────────────────────────────────────────────────┤
│ [x] Verify after writing                                        │
├ Progress ───────────────────────────────────────────────────────┤
│ ██████████████░░░░░░░░░░  57%                                   │
│ Writing — 42.1 MB/s — 1:23 left                                 │
└─────────────────────────────────────────────────────────────────┘
  o open · ↑↓ device · space verify · w write · r refresh · q quit

How it works

  • The app runs unprivileged. It asks udisks2 over D-Bus for a writable file descriptor (Block.OpenDevice, the same mechanism GNOME Disks uses); polkit prompts if authorization is needed.
  • Only removable USB whole-disk devices are listed — internal disks and partitions never appear as targets, and the device is opened with O_EXCL so the kernel refuses if anything else still holds it.
  • Writing is a two-stage pipeline: one thread decompresses and hashes the image while another writes it, so decompression and device I/O overlap instead of taking turns. Buffers are a fixed ring of 4 × 8 MiB, allocated once, 4096-aligned.
  • The device fd is opened with O_DIRECT (dd's oflag=direct): writes bypass the page cache and go straight to the device, so there are no periodic flush stalls and the progress numbers are physically real. A device that refuses O_DIRECT gets the buffered fallback, where fdatasync every 64 MiB keeps progress honest instead.
  • Verify re-reads the device (page cache dropped first with posix_fadvise(DONTNEED)) and compares SHA-256 against the image stream.
  • Compressed images (.xz, .gz, .bz2, .zst) are decompressed on the fly.

Install

cargo build --release
install -Dm755 target/release/etchling ~/.local/bin/etchling

Build needs a Rust toolchain, plus clang and cmake for the bundled compression codecs. Runtime needs only udisks2 and a polkit agent.

Distributing

packaging/dist.sh builds both distributables into dist/:

  • etchling-VERSION-x86_64-linux — a fully static musl binary. One file, no library dependencies at all; runs on any x86_64 Linux with udisks2.
  • etchling_VERSION_amd64.deb — the same binary packaged for Debian/Ubuntu (sudo apt install ./etchling_VERSION_amd64.deb), depending only on udisks2.

The script needs the musl Rust target (Arch: pacman -S musl kernel-headers-musl rust-musl) and builds the .deb with nothing but tar and ar — no dpkg on the build machine.

For Arch users there is a PKGBUILD: makepkg -f builds etchling-VERSION-1-x86_64.pkg.tar.zst (running the test suite as its check phase), installable with pacman -U.

Use

etchling                  # browse for an image from inside the TUI
etchling path/to.iso      # start with an image pre-selected
key action
o open the file browser
↑ ↓ / k j choose a device
space toggle verify-after-write
w / Enter write (opens the confirm gate)
r refresh the device list
c copy the image SHA-256 (OSC 52)
x / Esc cancel a running write
q quit

The file browser is type-to-find: just start typing and the list narrows to fuzzy matches (arch64 finds archlinux-x86_64.iso), best match first, with the matched letters highlighted.

key action
any printable extend the fuzzy filter
↑ ↓ / Ctrl-k Ctrl-j / Ctrl-p Ctrl-n move
Enter / → open directory / choose file
← (or Backspace with an empty filter) parent directory
Backspace erase a filter char
Ctrl-u clear the filter
Tab toggle the image-extension filter (all files)
Alt-h toggle hidden files
Esc clear the filter, then close

What the port bought

Measured on one machine (8-core x86_64, udisks 2.11.2, 6 block devices):

Python + Qt6 Rust TUI
resident memory, idle 107 MB 6 MB
startup 154 ms just to import PySide6.QtWidgets 1.1 ms for the whole process
install footprint 51 MB (pyside6 tree) 3.3 MB (one binary)
device enumeration 25 D-Bus round trips, 25.5 ms 1 round trip, 4–8 ms

Two honest caveats:

  • The startup row flatters Rust: the Python figure counts only the Qt import, not interpreter start or widget construction, so the real gap is larger — but it is not a like-for-like measurement.
  • Raw writes are device-bound in the end, but how the device is driven matters: the original buffered path issued fdatasync every 64 MiB, and each of those is a full device cache flush — an operation cheap USB sticks handle badly, which is why it trailed a flush-less dd. The O_DIRECT path streams continuously with a single flush at the end, like dd oflag=direct. The other throughput win is on compressed images, where decompression and hashing run concurrently with the write instead of alternating with it.

Authorization, and why the screen blinks

Before opening the device, etchling releases the terminal, registers a pkttyagent polkit agent for its own process, and only then makes the authorizing call. If a prompt is needed it appears right there in your terminal; when the authorization is already cached you just see a brief blink.

Both halves of that are deliberate, and both were arrived at the hard way:

  • The call must not be made without an agent reachable. Deciding whether a graphical agent exists by looking at WAYLAND_DISPLAY/DISPLAY is wrong: those are inherited into contexts whose polkit subject has no agent — a tmux server, an ssh session, a systemd unit. There, OpenDevice does not fail. It blocks indefinitely, with the prompt nowhere you can reach it. (Reproduced: the same binary exits 0 from a login shell and times out from a detached tmux server.)
  • The agent must be registered before the call, not after. An agent that registers once CheckAuthorization is already pending is never consulted; the call simply stays blocked. So "call first, add an agent if it seems slow" does not work.
  • Registering up front is free when the authorization is already cached: polkitd answers a cache hit itself and never contacts an agent.

Testing without hardware

cargo test                               # decompressors, write/verify, error paths

truncate -s 1G /tmp/fakestick.img
udisksctl loop-setup -f /tmp/fakestick.img
ETCHLING_ALLOW_LOOP=1 etchling           # loop devices appear as targets
...
udisksctl loop-delete -b /dev/loopN

cargo run --example list-disks -- --open prints what the TUI would offer as targets and exercises the fd handover without writing a byte. Add --agent to also register a pkttyagent first, which is how the authorization behaviour above was pinned down. cargo run --release --example write-image -- IMG /dev/loopN drives the full headless unmount → open → write → verify pipeline against a device node and reports whether O_DIRECT was granted.

The full write → sync → verify pipeline runs against a loop device, so it can be exercised without risking a real disk. Three caveats found in testing:

  • loop-delete does not simulate yanking a stick. Detaching is lazy: an already-open fd stays valid, so the write completes normally. The genuine yank path is covered by unit tests instead — tests/engine.rs drives a real ENOSPC through /dev/full and asserts the error classification.
  • Writing to a loop device may still raise a polkit prompt, depending on whether an admin authorization is currently cached for your session (open-device is auth_admin_keep).
  • Do not run it from a detached tmux server unless you can answer the prompt in that pane — see the authorization note above.

Safety notes

  • The confirm gate requires typing the device name (e.g. sdb) — read it.
  • Cancelling mid-write leaves the stick in an undefined state; reformat it.

Layout

file role
src/udisks.rs all D-Bus traffic; one GetManagedObjects snapshot answers every query
src/engine.rs write / sync / verify pipeline; no D-Bus, no UI
src/image.rs compression sniffing and decoder construction
src/app.rs state machine; owns the worker threads
src/ui.rs pure renderer — a function of &App
src/fs_browser.rs the in-TUI file picker
src/main.rs terminal lifecycle, event loop, polkit handoff

About

A tiny USB image writer for Linux — TUI, unprivileged via udisks2, O_DIRECT fast, verify built in

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages