---
name: "gptzfsboot"
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/gptzfsboot"
---

# gptzfsboot(8)

GPT bootcode for ZFS on BIOS-based computers

## NAME

**gptzfsboot** – GPT bootcode for ZFS on BIOS-based computers

## DESCRIPTION

**gptzfsboot** is used on BIOS-based computers to boot from a filesystem in a ZFS pool. **gptzfsboot** is installed in a **freebsd-boot** partition of a GPT-partitioned disk with [gpart(8)](/gpart/8.md).

## IMPLEMENTATION NOTES

The GPT standard allows a variable number of partitions, but **gptzfsboot** only boots from tables with 128 partitions or less.

## BOOTING

**gptzfsboot** tries to find all ZFS pools that are composed of BIOS-visible hard disks or partitions on them. **gptzfsboot** looks for ZFS device labels on all visible disks and in discovered supported partitions for all supported partition scheme types. The search starts with the disk from which **gptzfsboot** itself was loaded. Other disks are probed in BIOS defined order. After a disk is probed and **gptzfsboot** determines that the whole disk is not a ZFS pool member, the individual partitions are probed in their partition table order. Currently GPT and MBR partition schemes are supported. With the GPT scheme, only partitions of type **freebsd-zfs** are probed. The first pool seen during probing is used as a default boot pool.

The filesystem specified by the **bootfs** property of the pool is used as a default boot filesystem. If the **bootfs** property is not set, then the root filesystem of the pool is used as the default. [loader(8)](/loader/8.md) is loaded from the boot filesystem. If */boot.config* or */boot/config* is present in the boot filesystem, boot options are read from it in the same way as [boot(8)](/boot/8.md).

The ZFS GUIDs of the first successfully probed device and the first detected pool are made available to [loader(8)](/loader/8.md) in the **vfs.zfs.boot.primary\_vdev** and **vfs.zfs.boot.primary\_pool** variables.

## USAGE

Normally **gptzfsboot** will boot in fully automatic mode. However, like [boot(8)](/boot/8.md), it is possible to interrupt the automatic boot process and interact with **gptzfsboot** through a prompt. **gptzfsboot** accepts all the options that [boot(8)](/boot/8.md) supports.

The filesystem specification and the path to [loader(8)](/loader/8.md) are different from [boot(8)](/boot/8.md). The format is

\[zfs:pool/filesystem:\]\[/path/to/loader\]

Both the filesystem and the path can be specified. If only a path is specified, then the default filesystem is used. If only a pool and filesystem are specified, then */boot/loader* is used as a path.

Additionally, the **status** command can be used to query information about discovered pools. The output format is similar to that of **zpool** **status** (see [zpool(8)](/zpool/8.md)).

The configured or automatically determined ZFS boot filesystem is stored in the [loader(8)](/loader/8.md) **loaddev** variable, and also set as the initial value of the **currdev** variable.

## FILES

- */boot/gptzfsboot*

  boot code binary

- */boot.config*

  parameters for the boot block (optional)

- */boot/config*

  alternative parameters for the boot block (optional)

## EXAMPLES

**gptzfsboot** is typically installed in combination with a “protective MBR”( see [gpart(8)](/gpart/8.md)). To install **gptzfsboot** on the *ada0* drive:

```
gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0
```

**gptzfsboot** can also be installed without the PMBR:

```
gpart bootcode -p /boot/gptzfsboot -i 1 ada0
```

## SEE ALSO

[boot.config(5)](/boot.config/5.md), [boot(8)](/boot/8.md), [gpart(8)](/gpart/8.md), [loader(8)](/loader/8.md), [zpool(8)](/zpool/8.md)

## HISTORY

**gptzfsboot** appeared in FreeBSD 7.3.

## AUTHORS

This manual page was written by Andriy Gapon ⟨*avg@FreeBSD.org*⟩.

## BUGS

**gptzfsboot** looks for ZFS meta-data only in MBR partitions (known on FreeBSD as slices). It does not look into BSD [disklabel(8)](/disklabel/8.md) partitions that are traditionally called partitions. If a disklabel partition happens to be placed so that ZFS meta-data can be found at the fixed offsets relative to a slice, then **gptzfsboot** will recognize the partition as a part of a ZFS pool, but this is not guaranteed to happen.