--- name: "gzoned" section: "8" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/gzoned" --- # gzoned(8) emulate a host-managed zoned device on top of a regular provider ## NAME **gzoned** – emulate a host-managed zoned device on top of a regular provider ## SYNOPSIS **gzoned** **create** \[**-uv**\] \[**-s** *zonesize*\] \[**-c** *zones*\] \[**-m** *maxopen*\] *dev* **gzoned** **fault** \[**-v**\] **-z** *zone* **-s** *state* *name* **gzoned** **destroy** \[**-fv**\] *name* *...* **gzoned** **stop** \[**-fv**\] *name* *...* **gzoned** **clear** \[**-v**\] *dev* *...* **gzoned** \[**--libxo**\] **list** **gzoned** \[**--libxo**\] **status** **gzoned** **load** **gzoned** **unload** ## DESCRIPTION The **gzoned** utility presents to the system a host-managed zoned block device backed by a regular, non-zoned provider. The exposed device is of the kind described by the SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command Set (ZAC) specifications. The backing provider is divided into equally sized, sequential-write-required zones, unless marked conventional by the **-c** option. For each zone the GEOM class maintains a write pointer and answers the zone-management commands (see [zonectl(8)](/zonectl/8.md)) issued through the DIOCZONECMD ioctl. Resetting a write pointer issues a best-effort BIO\_DELETE for the zone's range to the backing provider, resembling a real drives de-allocating a reset zone. BIO\_DELETE requests to the zoned device itself are rejected, as zoned devices have no unmap. Sequential zones are reclaimed by resetting the write pointer. The configuration for a device is persistent. A metadata block and the per-zone state are stored in a small area reserved at the tail of the backing provider, so the zoned device is recreated automatically whenever the provider appears (at boot, module load or hot-plug), with its write pointers restored. Note that because of the metadata location on the backing provider, the zoned device is torn down if the backing provider is resized with unflushed zone state changes being discarded. Zone state changes are committed to the backing provider on a BIO\_FLUSH. Changes made since the last flush may be rolled back by an unclean shutdown, resembling a drive whose zone state is volatile until flushed. The first argument to **gzoned** indicates an action to be performed: - **create** Mark *dev* as zoned, creating a device named after the backing provider with “.zoned” appended (e.g. */dev/da0.zoned*). The number of zones is the usable size of *dev* divided by *zonesize*; a small reservation at the tail of *dev* holds the zone metadata; any trailing space that does not make up a full zone is not exposed. Host-managed zoned providers are refused: their tail normally lies in a sequential-write-required zone and cannot hold the metadata and zone state table. - **fault** Inject a zone fault into the running device *name*. **-z** *zone* selects the zone by number and **-s** *state* is one of *ro* (*readonly*), *offline*, *reset* (zone needs a write-pointer reset) or *clear* (return the zone to its normal state implied by its write pointer). Readonly and offline zones reject writes and zone-management commands; the fault persists with the rest of the zone state until cleared. - **clear** Permanently un-zone the given backing device(s) by clearing the on-disk metadata. A backing device carrying a live zoned device is held open and cannot be cleared: tear the device down with **stop** first. - **stop** Tear down the given zoned device(s) without touching the on-disk metadata. *name* is the zoned device (e.g. *da0.zoned*). Unflushed zone state is committed to the backing provider first. The device comes back the next time the backing provider is tasted (e.g. at boot or when it is opened and closed again). - **destroy** Same as **stop**. - **list** See [geom(8)](/geom/8.md). - **status** See [geom(8)](/geom/8.md). - **load** See [geom(8)](/geom/8.md). - **unload** See [geom(8)](/geom/8.md). - **--libxo** Generate output via [libxo(3)](/libxo/3.md) in a selection of different human and machine readable formats. See [xo\_options(7)](/xo_options/7.md) for details on command line arguments. Additional options: - **-c** *zones* Mark the given zones as conventional (randomly writable, no write pointer). *zones* is a comma-separated list of zone numbers and inclusive ranges, counted from zero, e.g. *60*, *60-70* or *0-3,60,90-95*. At most 16 comma-separated entries may be given. By default all zones are sequential-write-required. - **-f** Tear down the device even if it is still open. - **-m** *maxopen* Limit the number of simultaneously open sequential zones. Once the limit is reached, implicitly opened zones are implicitly closed to make room. If every open zone was opened explicitly, further writes and explicit opens fail with ENOSPC. The default of 0 means unlimited. - **-s** *zonesize* Size of a single zone. The value must be a multiple of the backing provider's sector size and may use the usual size suffixes (e.g. *7G*, *64M*). The default is *256M*. It must also leave the device with at least one, and at most 4294967295 zones. - **-u** Restrict reads in sequential-write-required zones (unset URSWRZ bit). Similarly to real zoned drives, the device supports unrestricted reads that are passed through unchecked by default. With **-u** the device instead reports URSWRZ as unset and rejects with EIO any read in a sequential zone that extends beyond that zone's write pointer, as well as any read that crosses out of a conventional zone into a sequential one. Note that this renders the device unreadable to zone-unaware consumers. Tasting the zoned provider (e.g. partition table scanning) will also fail until the accessed zones have been written. - **-v** Be more verbose. ## SYSCTL VARIABLES The following [sysctl(8)](/sysctl/8.md) variable can be used to control the behavior of the **ZONED** GEOM class. - *kern.geom.zoned.debug*: 0 Debug level of the **ZONED** GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0, minimal debug information is printed; if set to 3, the maximum amount of debug information is printed. ## EXIT STATUS The **gzoned** utility exits 0 on success, and \>0 if an error occurs. ## EXAMPLES Expose the memory disk */dev/md0* as a host-managed zoned device */dev/md0.zoned* with one-gigabyte zones, the first four of which are conventional. Inspect its zones, then permanently un-zone it: ``` mdconfig -t malloc -s 10G -u md0 gzoned create -s 1G -c 0-3 /dev/md0 zonectl -d /dev/md0.zoned -c params zonectl -d /dev/md0.zoned -c rz gzoned clear /dev/md0 ``` The same operations are also available through the [geom(8)](/geom/8.md) front end: ``` geom zoned create -s 128M /dev/da0 geom zoned stop da0.zoned geom zoned clear /dev/da0 ``` ## SEE ALSO [geom(4)](/geom/4.md), [md(4)](/md/4.md), [xo\_options(7)](/xo_options/7.md), [geom(8)](/geom/8.md), [mdconfig(8)](/mdconfig/8.md), [zonectl(8)](/zonectl/8.md) ## HISTORY The **gzoned** utility appeared in FreeBSD 16.0. ## AUTHORS voidanix ⟨*voidanix@FreeBSD.org*⟩