ZBD(8)

zbd(8) — bestie, we're managing zoned block devices today 💅

okay so this is zbd, from the System Manager's Manual, and she is that girl. let's get into it.

---

✨ NAME ✨

zbd — manage zoned block devices 🦋

---

✨ SYNOPSIS ✨

zbd command [options] device

---

✨ DESCRIPTION ✨

so zbd is the tool you use to mess with the zones of a zoned block device. and what even is a zoned block device, you ask? it's a block device that supports the SCSI Zoned Block Commands (ZBC), the ATA Zoned-device ATA Commands (ZAC), or the NVMe Zoned NameSpace commands (ZNS). iconic trio fr fr 👑

the zones you wanna operate on get picked using the offset and length options. easy.

the device argument has to be the pathname of the target zoned block device. no guessing, bestie, give her the real path 🌸

---

✨ COMMANDS ✨

lowkey the default vibe: every command starts at the zone at device offset 0 and operates on all the zones. if you want to change that range, the common options -ofst and -len are right there waiting for you 💖

---

🌈 report

zbd report is the one that grabs and shows you the device zone information. main character energy honestly.

by default she reports all zones from the start of the device up to the last zone of the device. you can change that behavior with options — move the starting zone, or change the size of the report. your call, queen ✨

🌸 Report output

• Zone — Zone number
• type — Type of the zone
• ofst — Zone start offset in Bytes
• len — Zone length in Bytes
• cap — Zone usable capacity in Bytes
• wp — Zone write pointer position in Bytes
• cond — Zone condition
• non_seq — Non-sequential write resources active
• reset — Reset write pointer recommended

🎀 Zone types

• cnv — Conventional
• swr — Sequential write required
• swp — Sequential write preferred
• ??? — Unknown (should not be reported)

🦋 Zone conditions

• nw — Not write pointer
• em — Empty
• fu — Full
• oe — Explicitly opened
• oi — Implicitly opened
• cl — Closed
• ol — Offline
• ro — Read only
• ?? — Reserved conditions (should not be reported)

bestie if you ever see ??? or ?? show up, something is deeply not giving. those are literally not supposed to be reported 💀

---

🌈 reset

zbd reset resets the write pointer of one or more zones. that's it, that's the whole job 💅

---

🌈 open

zbd open explicitly opens one or more zones. go off 👑

---

🌈 close

zbd close closes one or more zones. closed for business, periodt 🎀

---

🌈 finish

zbd finish finishes one or more zones — meaning it transitions them to full. she's done, she's booked, she's full 🔥

---

🌈 dump

save the zone information and the zone data of a zoned device to files. so cute of her.

• files go by default into the current working directory 📁
• wanna put them somewhere else? use the option -d
• file names are prefixed by default using the device base name
• device zone info lands in <devname>_zone_info.dump
• device zone data lands in <devname>_zone_data.dump
• wanna change that prefix? use the option -f

dump will save the data of all conventional zones and the written data of all sequential zones in the operation range. and yes, -ofst and -len can be used to limit the size of that operation range 🌸

ngl this part matters: the zone information file always saves zone information for all zones of the device, no matter what operation range you specified. and that file can be handed to the report command in place of a device name to inspect its content. iykyk 💜

---

🌈 restore

sets a zoned block device's zone status and zone data according to the zone information and zone data saved in files generated by the dump command. the resulting state of the target device will be identical to that of the device used to generate the dump files. literally a glow-up in reverse ✨

some rules, bestie, listen up:

• restore will only operate on the zone range that was used with the dump command
• the target zoned block device must be compatible with the zoned block device used as the source for the dump operation
• "compatible" means the target device must have the same capacity and the same zone configuration (zone type, zone size, and zone capacity) as the source device. no substitutions 🙈

you can change the path and the name prefix of the dump files used for restoring with the options -d and -f 🎀

---

✨ OPTIONS ✨

💖 Options that work with every command

• -v — Verbose mode (for debug).
• -i — Display device information before executing the command.
• -ofst offset — Start offset in Bytes of the first zone to operate on.
• -len length — Length in Bytes of the range of zones to operate on.
• -h, --help — Display help text and exit.

---

💖 Options that are ONLY for zbd report

• -csv — Output zone information using the comma-separated (csv) format.
• -n — Display the number of zones that are to be reported.
• -c — Display the total capacity of all reported zones. when you use it together with the -n and -csv options, the number of zones is output first.
• -ro filter — Specify reporting option to filter the zone report. filter can be one of the following:
  • em — Empty zones
  • oi — Implicitly opened zones
  • oe — Explicitly opened zones
  • cl — Closed zones
  • fu — Full zones
  • ro — Read only zones
  • ol — Offline zones
  • nw — Conventional zones
  • ns — Non_seq write resource zones
  • rw — Reset write pointer recommended zones

---

✨ AUTHOR ✨

Damien Le Moal <damien.lemoal@wdc.com> — thank you king 🫶

---

✨ SEE ALSO ✨

blkzone(8) — go read her too, she's the sister fr fr 💜

---

✨ AVAILABILITY ✨

the zbd command is part of the libzbd library, available from https://github.com/westerndigitalcorporation/libzbd 🌈

---

okay and one last thing before you go — this whole page is signed off as ZBD(8), the System Manager's Manual page for zbd. that's the little stamp at the very bottom, like a signature in lip gloss 💅✨ bye bestie, go zone something 🦋