1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2026 voidanix <voidanix@FreeBSD.org> 4.\" 5.Dd August 4, 2026 6.Dt GZONED 8 7.Os 8.Sh NAME 9.Nm gzoned 10.Nd "emulate a host-managed zoned device on top of a regular provider" 11.Sh SYNOPSIS 12.Nm 13.Cm create 14.Op Fl uv 15.Op Fl s Ar zonesize 16.Op Fl c Ar zones 17.Op Fl m Ar maxopen 18.Ar dev 19.Nm 20.Cm fault 21.Op Fl v 22.Fl z Ar zone 23.Fl s Ar state 24.Ar name 25.Nm 26.Cm destroy 27.Op Fl fv 28.Ar name ... 29.Nm 30.Cm stop 31.Op Fl fv 32.Ar name ... 33.Nm 34.Cm clear 35.Op Fl v 36.Ar dev ... 37.Nm 38.Cm list 39.Nm 40.Cm status 41.Nm 42.Cm load 43.Nm 44.Cm unload 45.Sh DESCRIPTION 46The 47.Nm 48utility presents to the system a host-managed zoned block device backed by a 49regular, non-zoned provider. 50The exposed device is of the kind described by the 51SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command Set (ZAC) 52specifications. 53.Pp 54The backing provider is divided into equally sized, sequential-write-required 55zones, unless marked conventional by the 56.Fl c 57option. 58For each zone the GEOM class maintains a write pointer and answers the 59zone-management commands 60.Pq see Xr zonectl 8 61issued through the 62.Dv DIOCZONECMD 63ioctl. 64.Pp 65Resetting a write pointer issues a best-effort 66.Dv BIO_DELETE 67for the zone's range to the backing provider, resembling a real drives 68de-allocating a reset zone. 69.Dv BIO_DELETE 70requests to the zoned device itself are rejected, as zoned devices have no 71unmap. 72Sequential zones are reclaimed by resetting the write pointer. 73.Pp 74The configuration for a device is persistent. 75A metadata block and the per-zone state are stored in a small area reserved at 76the tail of the backing provider, so the zoned device is recreated 77automatically whenever the provider appears 78.Pq at boot, module load or hot-plug , 79with its write pointers restored. 80Note that because of the metadata location on the backing provider, the zoned 81device is torn down if the backing provider is resized with unflushed zone state 82changes being discarded. 83Zone state changes are committed to the backing provider on a BIO_FLUSH. 84Changes made since the last flush may be rolled back by an unclean shutdown, 85resembling a drive whose zone state is volatile until flushed. 86.Pp 87The first argument to 88.Nm 89indicates an action to be performed: 90.Bl -tag -width ".Cm destroy" 91.It Cm create 92Mark 93.Ar dev 94as zoned, creating a device named after the backing provider with 95.Dq .zoned 96appended 97.Pq e.g. Pa /dev/da0.zoned . 98The number of zones is the usable size of 99.Ar dev 100divided by 101.Ar zonesize ; 102a small reservation at the tail of 103.Ar dev 104holds the zone metadata; any trailing space that does not make up a full zone 105is not exposed. 106Host-managed zoned providers are refused: their tail normally lies in a 107sequential-write-required zone and cannot hold the metadata and zone state 108table. 109.It Cm fault 110Inject a zone fault into the running device 111.Ar name . 112.Fl z Ar zone 113selects the zone by number and 114.Fl s Ar state 115is one of 116.Ar ro 117.Pq Ar readonly , 118.Ar offline , 119.Ar reset 120.Pq zone needs a write-pointer reset 121or 122.Ar clear 123.Pq return the zone to its normal state implied by its write pointer . 124Readonly and offline zones reject writes and zone-management commands; 125the fault persists with the rest of the zone state until cleared. 126.It Cm clear 127Permanently un-zone the given backing device(s) by clearing the on-disk 128metadata. 129A backing device carrying a live zoned device is held open and cannot be 130cleared: tear the device down with 131.Cm stop 132first. 133.It Cm stop 134Tear down the given zoned device(s) without touching the on-disk metadata. 135.Ar name 136is the zoned device 137.Pq e.g. Pa da0.zoned . 138Unflushed zone state is committed to the backing provider first. 139The device comes back the next time the backing provider is tasted 140.Pq e.g. at boot or when it is opened and closed again . 141.It Cm destroy 142Same as 143.Cm stop . 144.It Cm list 145See 146.Xr geom 8 . 147.It Cm status 148See 149.Xr geom 8 . 150.It Cm load 151See 152.Xr geom 8 . 153.It Cm unload 154See 155.Xr geom 8 . 156.El 157.Pp 158Additional options: 159.Bl -tag -width ".Fl s Ar zonesize" 160.It Fl c Ar zones 161Mark the given zones as conventional 162.Pq randomly writable, no write pointer . 163.Ar zones 164is a comma-separated list of zone numbers and inclusive ranges, counted 165from zero, e.g.\& 166.Ar 60 , 167.Ar 60-70 168or 169.Ar 0-3,60,90-95 . 170At most 16 comma-separated entries may be given. 171By default all zones are sequential-write-required. 172.It Fl f 173Tear down the device even if it is still open. 174.It Fl m Ar maxopen 175Limit the number of simultaneously open sequential zones. 176Once the limit is reached, implicitly opened zones are implicitly closed to make 177room. 178If every open zone was opened explicitly, further writes and explicit opens fail 179with 180.Er ENOSPC . 181The default of 0 means unlimited. 182.It Fl s Ar zonesize 183Size of a single zone. 184The value must be a multiple of the backing provider's sector size and may use 185the usual size suffixes 186.Pq e.g. Ar 7G , 64M . 187The default is 188.Ar 256M . 189It must also leave the device with at least one, and at most 4294967295 zones. 190.It Fl u 191Restrict reads in sequential-write-required zones 192.Pq unset URSWRZ bit . 193Similarly to real zoned drives, the device supports unrestricted reads that are 194passed through unchecked by default. 195With 196.Fl u 197the device instead reports URSWRZ as unset and rejects with 198.Er EIO 199any read in a sequential zone that extends beyond that zone's write pointer, as 200well as any read that crosses out of a conventional zone into a sequential one. 201Note that this renders the device unreadable to zone-unaware consumers. 202Tasting the zoned provider 203.Pq e.g. partition table scanning 204will also fail until the accessed zones have been written. 205.It Fl v 206Be more verbose. 207.El 208.Sh SYSCTL VARIABLES 209The following 210.Xr sysctl 8 211variable can be used to control the behavior of the 212.Nm ZONED 213GEOM class. 214.Bl -tag -width indent 215.It Va kern.geom.zoned.debug : No 0 216Debug level of the 217.Nm ZONED 218GEOM class. 219This can be set to a number between 0 and 3 inclusive. 220If set to 0, minimal debug information is printed; if set to 3, the maximum 221amount of debug information is printed. 222.El 223.Sh EXIT STATUS 224.Ex -std 225.Sh EXAMPLES 226Expose the memory disk 227.Pa /dev/md0 228as a host-managed zoned device 229.Pa /dev/md0.zoned 230with one-gigabyte zones, the first four of which are conventional. 231Inspect its zones, then permanently un-zone it: 232.Bd -literal -offset indent 233mdconfig -t malloc -s 10G -u md0 234gzoned create -s 1G -c 0-3 /dev/md0 235zonectl -d /dev/md0.zoned -c params 236zonectl -d /dev/md0.zoned -c rz 237gzoned clear /dev/md0 238.Ed 239.Pp 240The same operations are also available through the 241.Xr geom 8 242front end: 243.Bd -literal -offset indent 244geom zoned create -s 128M /dev/da0 245geom zoned stop da0.zoned 246geom zoned clear /dev/da0 247.Ed 248.Sh SEE ALSO 249.Xr geom 4 , 250.Xr md 4 , 251.Xr geom 8 , 252.Xr mdconfig 8 , 253.Xr zonectl 8 254.Sh HISTORY 255The 256.Nm 257utility appeared in 258.Fx 16.0 . 259.Sh AUTHORS 260.An voidanix Aq Mt voidanix@FreeBSD.org 261