.\" Copyright (c) 2014 Andriy Gapon .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd September 15, 2014 .Dt GPTZFSBOOT 8 .Os .Sh NAME .Nm gptzfsboot .Nd GPT bootcode for ZFS on BIOS-based computers .Sh DESCRIPTION .Nm is used on BIOS-based computers to boot from a filesystem in a ZFS pool. .Nm is installed in a .Cm freebsd-boot partition of a GPT-partitioned disk with .Xr gpart 8 . .Sh IMPLEMENTATION NOTES The GPT standard allows a variable number of partitions, but .Nm only boots from tables with 128 partitions or less. .Sh BOOTING .Nm tries to find all ZFS pools that are composed of BIOS-visible hard disks or partitions on them. .Nm 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 .Nm itself was loaded. Other disks are probed in BIOS defined order. After a disk is probed and .Nm 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 .Cm freebsd-zfs are probed. The first pool seen during probing is used as a default boot pool. .Pp The filesystem specified by the .Cm bootfs property of the pool is used as a default boot filesystem. If the .Cm bootfs property is not set, then the root filesystem of the pool is used as the default. .Xr loader 8 is loaded from the boot filesystem. If .Pa /boot.config or .Pa /boot/config is present in the boot filesystem, boot options are read from it in the same way as .Xr boot 8 . .Pp The ZFS GUIDs of the first successfully probed device and the first detected pool are made available to .Xr loader 8 in the .Cm vfs.zfs.boot.primary_vdev and .Cm vfs.zfs.boot.primary_pool variables. .Sh USAGE Normally .Nm will boot in fully automatic mode. However, like .Xr boot 8 , it is possible to interrupt the automatic boot process and interact with .Nm through a prompt. .Nm accepts all the options that .Xr boot 8 supports. .Pp The filesystem specification and the path to .Xr loader 8 are different from .Xr boot 8 . The format is .Pp .Sm off .Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc .Sm on .Pp 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 .Pa /boot/loader is used as a path. .Pp Additionally, the .Ic status command can be used to query information about discovered pools. The output format is similar to that of .Cm zpool status .Pq see Xr zpool 8 . .Pp The configured or automatically determined ZFS boot filesystem is stored in the .Xr loader 8 .Cm loaddev variable, and also set as the initial value of the .Cm currdev variable. .Sh FILES .Bl -tag -width /boot/gptzfsboot -compact .It Pa /boot/gptzfsboot boot code binary .It Pa /boot.config parameters for the boot block .Pq optional .It Pa /boot/config alternative parameters for the boot block .Pq optional .El .Sh EXAMPLES .Nm is typically installed in combination with a .Dq protective MBR .Po see .Xr gpart 8 .Pc . To install .Nm on the .Pa ada0 drive: .Bd -literal -offset indent gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 .Ed .Pp .Nm can also be installed without the PMBR: .Bd -literal -offset indent gpart bootcode -p /boot/gptzfsboot -i 1 ada0 .Ed .Sh SEE ALSO .Xr boot.config 5 , .Xr boot 8 , .Xr gpart 8 , .Xr loader 8 , .Xr zpool 8 .Sh HISTORY .Nm appeared in FreeBSD 7.3. .Sh AUTHORS This manual page was written by .An Andriy Gapon Aq avg@FreeBSD.org . .Sh BUGS .Nm looks for ZFS meta-data only in MBR partitions .Pq known on FreeBSD as slices . It does not look into BSD .Xr 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 .Nm will recognize the partition as a part of a ZFS pool, but this is not guaranteed to happen.