ublkguide & libraries
Menu

go-ublk

A Go library for Linux ublk block devices. Pure Go: no cgo, no liburing, builds with CGO_ENABLED=0.

go-ublk is a library for serving Linux block devices from Go. You implement a Backend, an interface shaped like io.ReaderAt and io.WriterAt plus Size, Flush and Close — or a raw request Handler — and the library does the rest: it negotiates features and speaks the ublk control protocol on /dev/ublk-control, runs an I/O thread with its own io_uring per hardware queue on /dev/ublkcN, runs your backend concurrently, keeps the device alive across server restarts if you ask, and tears it down in the order the kernel needs.

go get github.com/ehrlich-b/go-ublk

It is written entirely in Go. The io_uring setup, the submission and completion rings, the memory barriers and the ublk UAPI structures are implemented in the module on top of golang.org/x/sys/unix, so a binary builds with CGO_ENABLED=0 and cross-compiles like any other Go program. API documentation is on pkg.go.dev.

It is a library. The deliverable is the public API; storage backends belong to the program that imports it. The two programs in examples/, a RAM disk and a losetup-style file exporter, exist to prove that contract and use nothing outside the public API.

Note

go-ublk v0.2.0 implements the whole ublk kernel interface as of Linux 7.3-rc5 and is tested by a real-kernel conformance suite under many kernels — see Testing and compatibility and the compatibility matrix. It is pre-1.0, so the API may still change. Read Deployment before running it under a filesystem that matters.

  1. Getting started

    Requirements, installing go-ublk, your first device, the example servers, and cleaning up after a crash.

  2. Writing a backend

    The Backend interface and its optional extensions: buffer ownership, concurrency, durability, and how errors reach the block layer.

  3. Configuration reference

    Every field of DeviceParams and Options: defaults, valid ranges, what each one sends to the kernel, and which kernel each feature needs.

  4. Device lifecycle

    Create, Start, Stop and Close; CreateAndServe; Done and Err; Detach and Recover; Resize; ListDevices and DeleteDevice; errors; metrics.

  5. Deployment

    Running a go-ublk server in production: the systemd unit and mount ordering it requires, signals, teardown, and kernel selection.

  6. Performance

    Measured dispatch costs, RAM throughput, and the settings that affect backend concurrency.

  7. Testing and compatibility

    How go-ublk is tested, from unit tests to crash and power-fail oracles, and which kernels it is verified on.

  8. Troubleshooting and FAQ

    Symptoms, causes and fixes: missing /dev/ublk-control, leaked devices, hangs at teardown, missing flushes and discards, and kernel oopses.

  9. Releases and changelog

    Tagged releases of go-ublk, what changed, and the versioning policy.

  10. Roadmap

    What go-ublk does not do yet, what is next, and the open defects, in priority order.

Edit this page on GitHub