GPTZFSBOOT(8)           FreeBSD System Manager's Manual          GPTZFSBOOT(8)

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).

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) 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).

     The ZFS GUIDs of the first successfully probed device and the first
     detected pool are made available to loader(8) 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), it is possible to interrupt the automatic boot process and
     interact with gptzfsboot through a prompt.  gptzfsboot accepts all the
     options that boot(8) supports.

     The filesystem specification and the path to loader(8) are different from
     boot(8).  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)).

     The configured or automatically determined ZFS boot filesystem is stored
     in the loader(8) 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)).  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(8), gpart(8), loader(8), zpool(8)

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) 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.

FreeBSD 13.1-RELEASE-p6       September 15, 2014       FreeBSD 13.1-RELEASE-p6