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
- 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_EXCLso 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, wherefdatasyncevery 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.
cargo build --release
install -Dm755 target/release/etchling ~/.local/bin/etchlingBuild needs a Rust toolchain, plus clang and cmake for the bundled
compression codecs. Runtime needs only udisks2 and a polkit agent.
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 onudisks2.
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.
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 |
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
fdatasyncevery 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-lessdd. The O_DIRECT path streams continuously with a single flush at the end, likedd oflag=direct. The other throughput win is on compressed images, where decompression and hashing run concurrently with the write instead of alternating with it.
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/DISPLAYis wrong: those are inherited into contexts whose polkit subject has no agent — a tmux server, an ssh session, a systemd unit. There,OpenDevicedoes 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
CheckAuthorizationis 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.
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/loopNcargo 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-deletedoes 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.rsdrives a real ENOSPC through/dev/fulland 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-deviceisauth_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.
- 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.
| 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 |