ZONECTL(8)

✨ zonectl(8) — Shingled Magnetic Recording Zone Control utility ✨

This is the zonectl(8) page from the System Manager's Manual, bestie — yes, the whole iconic thing, and we're keeping every fact intact. 🫶

🌸 NAME 🌸

zonectl — Shingled Magnetic Recording Zone Control utility. 💅

🦋 SYNOPSIS 🦋

That's the whole shape of it:

zonectl ⟨-d dev⟩ ⟨-c cmd⟩ [-a] [-l LBA] [-o rep_opts] [-P print_opts]

💖 DESCRIPTION 💖

okay so here's the tea: zonectl manages SCSI and ATA Zoned Block devices. This allows managing devices that conform to the SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command Set (ZAC) specifications. Devices using these command sets are usually hard drives using Shingled Magnetic Recording (SMR). Periodt. 💅

There are three types of SMR drives:

• Drive Managed — Drive Managed drives look and act just like a standard random access block device, but underneath, the drive reads and writes the bulk of its capacity using SMR zones. Sequential writes will yield better performance, but writing sequentially is not required.
• Host Aware — Host Aware drives expose the underlying zone layout via SCSI or ATA commands and allow the host to manage the zone conditions. The host is not required to manage the zones on the drive, though. Sequential writes will yield better performance in Sequential Write Preferred zones, but the host can write randomly in those zones.
• Host Managed — Host Managed drives expose the underlying zone layout via SCSI or ATA commands. The host is required to access the zones according to the rules described by the zone layout. Any commands that violate the rules will be returned with an error.

SMR drives are divided into zones (typically in the range of 256MB each) that fall into three general categories:

• Conventional — these are also known as Non Write Pointer zones. These zones can be randomly written without an unexpected performance penalty.
• Sequential Preferred — these zones should be written sequentially starting at the write pointer for the zone. They may be written randomly. Writes that do not conform to the zone layout may be significantly slower than expected.
• Sequential Required — these zones must be written sequentially. If they are not written sequentially, starting at the write pointer, the command will fail.

🎀 flags & subcommands 🎀

Here's the flag menu, no cap:

• -d dev — this shows up in the synopsis, and the examples use it like -d /dev/da5 for disk da5. That's all this page says about it, so I'm not inventing extra, bestie. 💀
• -c cmd — specify the zone subcommand. Your choices are:
  • params — display device parameters, including the type of device (Drive Managed, Host Aware, Host Managed, Not Zoned), the zone commands supported, and how many open zones it supports.
  • rz — issue the Report Zones command. All zones are returned by default. Specify report options with -o and printing options with -P. Specify the starting LBA with -l. Note that reportzones is also accepted as a command argument.
  • open — explicitly open the zone specified by the starting LBA.
  • close — close the zone specified by starting LBA.
  • finish — finish the zone specified by the starting LBA.
  • rwp — reset the write pointer for the zone specified by the starting LBA.
• -a — for the Open, Close, Finish, and Reset Write Pointer operations, apply the operation to all zones on the drive.
• -l lba — specify the starting LBA. For the Report Zones command, this tells the drive to report starting with the zone that starts at the given LBA. For the other commands, this allows the user to identify the zone requested by its starting LBA. The LBA may be specified in decimal, hexadecimal or octal notation.
• -o rep_opt — for the Report Zones command, specify a subset of zones to report:
  • all — report all zones. This is the default.
  • empty — report only empty zones.
  • imp_open — report zones that are implicitly open. This means that the host has sent a write to the zone without explicitly opening the zone.
  • exp_open — report zones that are explicitly open.
  • closed — report zones that have been closed by the host.
  • full — report zones that are full.
  • ro — report zones that are in the read only state. Note that readonly is also accepted as an argument.
  • offline — report zones that are in the offline state.
  • reset — report zones that the device recommends should have their write pointers reset.
  • nonseq — report zones that have the Non Sequential Resources Active flag set. These are zones that are Sequential Write Preferred, but have been written non-sequentially.
  • nonwp — report Non Write Pointer zones, also known as Conventional zones.
• -P print_opt — specify a printing option for Report Zones:
  • normal — normal Report Zones output. This is the default. The summary and column headings are printed, fields are separated by spaces and the fields themselves may contain spaces.
  • summary — just print the summary: the number of zones, the maximum LBA (LBA of the last logical block on the drive), and the value of the “same” field. The “same” field describes whether the zones on the drive are all identical, all different, or whether they are the same except for the last zone, etc.
  • script — print the zones in a script friendly format. The summary and column headings are omitted, the fields are separated by commas, and the fields do not contain spaces. The fields contain underscores where spaces would normally be used.

🔥 EXAMPLES 🔥

Examples are where it clicks, bestie:

zonectl -d /dev/da5 -c params

Display basic zoning information for disk da5.

zonectl -d /dev/da5 -c rz

Issue the Report Zones command to disk da5, and print out all zones on the drive in the default format.

zonectl -d /dev/da5 -c rz -o reset -P script

Issue the Report Zones command to disk da5, and print out all of the zones that have the Reset Write Pointer Recommended bit set to true. Print the zones in a script friendly form.

zonectl -d /dev/da5 -c rwp -l 0x2c80000

Issue the Reset Write Pointer command to disk da5 for the zone that starts at LBA 0x2c80000.

👀 SEE ALSO 👀

camcontrol(8) — go give it a look too, bestie. 🫶

🫶 AUTHORS 🫶

Kenneth Merry <ken@FreeBSD.org> — iconic. 👑

🎀 cute sign-off: this page comes from Debian, dated May 18, 2016, and it's the zonectl(8) manual. Slay. 🎀