1.\" Copyright (c) 2014 Andriy Gapon <avg@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd September 15, 2014 26.Dt GPTZFSBOOT 8 27.Os 28.Sh NAME 29.Nm gptzfsboot 30.Nd GPT bootcode for ZFS on BIOS-based computers 31.Sh DESCRIPTION 32.Nm 33is used on BIOS-based computers to boot from a filesystem in 34a ZFS pool. 35.Nm 36is installed in a 37.Cm freebsd-boot 38partition of a GPT-partitioned disk with 39.Xr gpart 8 . 40.Sh IMPLEMENTATION NOTES 41The GPT standard allows a variable number of partitions, but 42.Nm 43only boots from tables with 128 partitions or less. 44.Sh BOOTING 45.Nm 46tries to find all ZFS pools that are composed of BIOS-visible 47hard disks or partitions on them. 48.Nm 49looks for ZFS device labels on all visible disks and in discovered 50supported partitions for all supported partition scheme types. 51The search starts with the disk from which 52.Nm 53itself was loaded. 54Other disks are probed in BIOS defined order. 55After a disk is probed and 56.Nm 57determines that the whole disk is not a ZFS pool member, the 58individual partitions are probed in their partition table order. 59Currently GPT and MBR partition schemes are supported. 60With the GPT scheme, only partitions of type 61.Cm freebsd-zfs 62are probed. 63The first pool seen during probing is used as a default boot pool. 64.Pp 65The filesystem specified by the 66.Cm bootfs 67property of the pool is used as a default boot filesystem. 68If the 69.Cm bootfs 70property is not set, then the root filesystem of the pool is used as 71the default. 72.Xr loader 8 73is loaded from the boot filesystem. 74If 75.Pa /boot.config 76or 77.Pa /boot/config 78is present in the boot filesystem, boot options are read from it 79in the same way as 80.Xr boot 8 . 81.Pp 82The ZFS GUIDs of the first successfully probed device and the first 83detected pool are made available to 84.Xr loader 8 85in the 86.Cm vfs.zfs.boot.primary_vdev 87and 88.Cm vfs.zfs.boot.primary_pool 89variables. 90.Sh USAGE 91Normally 92.Nm 93will boot in fully automatic mode. 94However, like 95.Xr boot 8 , 96it is possible to interrupt the automatic boot process and interact with 97.Nm 98through a prompt. 99.Nm 100accepts all the options that 101.Xr boot 8 102supports. 103.Pp 104The filesystem specification and the path to 105.Xr loader 8 106are different from 107.Xr boot 8 . 108The format is 109.Pp 110.Sm off 111.Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc 112.Sm on 113.Pp 114Both the filesystem and the path can be specified. 115If only a path is specified, then the default filesystem is used. 116If only a pool and filesystem are specified, then 117.Pa /boot/loader 118is used as a path. 119.Pp 120Additionally, the 121.Ic status 122command can be used to query information about discovered pools. 123The output format is similar to that of 124.Cm zpool status 125.Pq see Xr zpool 8 . 126.Pp 127The configured or automatically determined ZFS boot filesystem is 128stored in the 129.Xr loader 8 130.Cm loaddev 131variable, and also set as the initial value of the 132.Cm currdev 133variable. 134.Sh FILES 135.Bl -tag -width /boot/gptzfsboot -compact 136.It Pa /boot/gptzfsboot 137boot code binary 138.It Pa /boot.config 139parameters for the boot block 140.Pq optional 141.It Pa /boot/config 142alternative parameters for the boot block 143.Pq optional 144.El 145.Sh EXAMPLES 146.Nm 147is typically installed in combination with a 148.Dq protective MBR 149.Po 150see 151.Xr gpart 8 152.Pc . 153To install 154.Nm 155on the 156.Pa ada0 157drive: 158.Bd -literal -offset indent 159gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 160.Ed 161.Pp 162.Nm 163can also be installed without the PMBR: 164.Bd -literal -offset indent 165gpart bootcode -p /boot/gptzfsboot -i 1 ada0 166.Ed 167.Sh SEE ALSO 168.Xr boot.config 5 , 169.Xr boot 8 , 170.Xr gpart 8 , 171.Xr loader 8 , 172.Xr zpool 8 173.Sh HISTORY 174.Nm 175appeared in FreeBSD 7.3. 176.Sh AUTHORS 177This manual page was written by 178.An Andriy Gapon Aq avg@FreeBSD.org . 179.Sh BUGS 180.Nm 181looks for ZFS meta-data only in MBR partitions 182.Pq known on FreeBSD as slices . 183It does not look into BSD 184.Xr disklabel 8 185partitions that are traditionally called partitions. 186If a disklabel partition happens to be placed so that ZFS meta-data can be 187found at the fixed offsets relative to a slice, then 188.Nm 189will recognize the partition as a part of a ZFS pool, 190but this is not guaranteed to happen. 191