Inspect and Control Zoned Block Devices with blkzone

blkzone reads, and on request rewrites, the zone state on a host-managed or host-aware zoned drive. A plain dd or filesystem trim can leave its zones in a state nothing else expects. The examples use the util-linux blkzone interface documented by the installed util-linux 2.39.3 manpage. On this machine, the shell resolves blkzone to a separate Homebrew util-linux 2.41.3 binary, so check your path and version before comparing output.

Allow about fifteen minutes. You need a shell, a zoned block device, and permission to open it. Inspection is normally read-only, but opening the device may require sudo.

Warning: the reset, open, close and finish commands change zone state and can disrupt storage workloads. Do not run those examples against a real device until you have confirmed the target and recovery plan.

1. Check the binary, package and device

Start with ordinary, read-only checks. They do not need elevated privileges:

$ command -v blkzone
/home/linuxbrew/.linuxbrew/sbin/blkzone
$ blkzone --version
blkzone from util-linux 2.41.3
$ dpkg-query -W -f='${Package} ${Version}\n' util-linux
util-linux 2.39.3-9ubuntu6.6

The package and executable can come from different installations. The manpage supplied by the Debian package describes util-linux 2.39.3, while this shell finds 2.41.3 first. Keep that distinction in an incident record or script review.

Now identify the device without changing it:

$ lsblk -dn -o NAME,PATH,TYPE,SIZE,FSTYPE,MOUNTPOINTS
NAME  PATH      TYPE  SIZE FSTYPE MOUNTPOINTS
sda   /dev/sda  disk  3.6T
sdb   /dev/sdb  disk  3.6T

Replace /dev/ZONE_DEVICE below with an exact path from your own inventory. Do not infer it from a serial number shown in a different host's output.

2. Confirm that the device is zoned

Linux exposes the device's zone model through sysfs. This check is unprivileged:

$ cat /sys/class/block/ZONE_DEVICE/queue/zoned
<zone model>

Common values include none, host-aware and host-managed. A value of none means the device is not presented as a zoned block device for this purpose, so stop there rather than forcing a zone command onto it. The placeholder in the path is a device name, not the literal string ZONE_DEVICE: for /dev/sdb, read /sys/class/block/sdb/queue/zoned.

Checkpoint: Confirm both the device path and the sysfs value immediately before using blkzone. If the device is mounted or used by a service, record those users before any state-changing command.

3. Report the zone layout

report reads zone information from the start of the device and, by default, covers all remaining zones. A block device may require elevated access:

$ sudo blkzone report /dev/ZONE_DEVICE
<zone records printed here>

The exact formatting and values depend on the device. The fields describe the zone start sector, zone length, zone capacity, write pointer, reset recommendation, non-sequential write resources, condition and type. The installed manpage documents conditions such as em for empty, oe for explicitly opened, fu for full, ro for read-only and ol for offline.

Use --count when you only need the first few zones:

$ sudo blkzone report --count 4 /dev/ZONE_DEVICE

--count is a maximum number of zones, not a byte count. Use --offset to start at a particular zone sector; the offset is measured in 512-byte sectors and should match a zone start. With --verbose, the command also displays the number of zones returned:

$ sudo blkzone report --offset 0 --count 4 --verbose /dev/ZONE_DEVICE

4. Check usable zone capacity

The capacity command reports the sum of zone capacities, in sectors, rather than the raw device size. This matters on devices where zone capacity is smaller than zone length:

$ sudo blkzone capacity /dev/ZONE_DEVICE
<capacity in sectors>

Use the output as a storage-layout fact, not as a filesystem-free-space measurement: it does not tell you how much data a filesystem has already allocated. Scope the calculation to a range when investigating one region:

$ sudo blkzone capacity --offset 0 --count 4 /dev/ZONE_DEVICE

The offset and length options accept sector values and binary or decimal suffixes such as MiB, GiB, MB and GB. The iB part is optional for binary suffixes, so 2G means 2GiB. Do not mix --length and --count; they are alternative ways to bound the operation.

5. Treat zone state commands as maintenance work

The remaining commands change the device's zone state:

reset resets one or more zones and their write pointers.
open explicitly opens one or more zones.
close closes one or more zones.
finish transitions one or more zones to full.

Warning: there is no general undo for these operations. Reset can discard the device's recorded write progress, and finish can prevent further writes to those zones. Stop services that use the device, follow the device and filesystem vendor's procedure, and make sure you can restore data before proceeding.

By default, these commands start at sector zero and act on all zones. Always bound the range explicitly in an approved maintenance window:

$ sudo blkzone reset --offset ZONE_START --count 1 /dev/ZONE_DEVICE

Replace ZONE_START with a verified zone start sector from report. Do not use --force casually: it allows a command to change zone status on a block device used by the system, which can turn a mistaken target into active data loss or service disruption.

Checkpoint: After any approved state change, report the same range again:

$ sudo blkzone report --offset ZONE_START --count 1 /dev/ZONE_DEVICE

Compare the condition and write pointer with the expected result from your storage procedure. A successful command exit only says the kernel accepted the request; it does not validate your application or filesystem's assumptions.

6. Diagnose the usual failures

cannot open or Permission denied points first at the device path and access permission. Try the read-only report with sudo only when your account is authorised to inspect that device.
If the device reports zoned=none, a zone ioctl is not the right diagnostic.
An offset that is not a zone start can fail or describe the wrong range. Obtain it from report, keep units in sectors unless you have deliberately checked a suffix conversion, and use either --count or --length, never both.

If output or supported options differ from this guide, repeat command -v blkzone and blkzone --version before relying on the manpage for a different installation.

Done means

You confirmed the executable path, util-linux version and exact target device.
The target's sysfs zoned value is compatible with the planned inspection.
You used report and, where useful, capacity before changing anything.
Every state-changing command has an explicit offset and either a count or length.
You did not use --force unless an approved maintenance procedure requires it.
You re-ran report after a permitted change and have no assumed undo for reset or finish.