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.\" $FreeBSD$ 26.\" 27.Dd September 15, 2014 28.Dt GPTZFSBOOT 8 29.Os 30.Sh NAME 31.Nm gptzfsboot 32.Nd GPT bootcode for ZFS on BIOS-based computers 33.Sh DESCRIPTION 34.Nm 35is used on BIOS-based computers to boot from a filesystem in 36a ZFS pool. 37.Nm 38is installed in a 39.Cm freebsd-boot 40partition of a GPT-partitioned disk with 41.Xr gpart 8 . 42.Sh IMPLEMENTATION NOTES 43The GPT standard allows a variable number of partitions, but 44.Nm 45only boots from tables with 128 partitions or less. 46.Sh BOOTING 47.Nm 48tries to find all ZFS pools that are composed of BIOS-visible 49hard disks or partitions on them. 50.Nm 51looks for ZFS device labels on all visible disks and in discovered 52supported partitions for all supported partition scheme types. 53The search starts with the disk from which 54.Nm 55itself was loaded. 56Other disks are probed in BIOS defined order. 57After a disk is probed and 58.Nm 59determines that the whole disk is not a ZFS pool member, the 60individual partitions are probed in their partition table order. 61Currently GPT and MBR partition schemes are supported. 62With the GPT scheme, only partitions of type 63.Cm freebsd-zfs 64are probed. 65The first pool seen during probing is used as a default boot pool. 66.Pp 67The filesystem specified by the 68.Cm bootfs 69property of the pool is used as a default boot filesystem. 70If the 71.Cm bootfs 72property is not set, then the root filesystem of the pool is used as 73the default. 74.Xr zfsloader 8 75is loaded from the boot filesystem. 76If 77.Pa /boot.config 78or 79.Pa /boot/config 80is present in the boot filesystem, boot options are read from it 81in the same way as 82.Xr boot 8 . 83.Pp 84The ZFS GUIDs of the first successfully probed device and the first 85detected pool are made available to 86.Xr zfsloader 8 87in the 88.Cm vfs.zfs.boot.primary_vdev 89and 90.Cm vfs.zfs.boot.primary_pool 91variables. 92.Sh USAGE 93Normally 94.Nm 95will boot in fully automatic mode. 96However, like 97.Xr boot 8 , 98it is possible to interrupt the automatic boot process and interact with 99.Nm 100through a prompt. 101.Nm 102accepts all the options that 103.Xr boot 8 104supports. 105.Pp 106The filesystem specification and the path to 107.Xr zfsloader 8 108are different from 109.Xr boot 8 . 110The format is 111.Pp 112.Sm off 113.Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc 114.Sm on 115.Pp 116Both the filesystem and the path can be specified. 117If only a path is specified, then the default filesystem is used. 118If only a pool and filesystem are specified, then 119.Pa /boot/zfsloader 120is used as a path. 121.Pp 122Additionally, the 123.Ic status 124command can be used to query information about discovered pools. 125The output format is similar to that of 126.Cm zpool status 127.Pq see Xr zpool 8 . 128.Pp 129The configured or automatically determined ZFS boot filesystem is 130stored in the 131.Xr zfsloader 8 132.Cm loaddev 133variable, and also set as the initial value of the 134.Cm currdev 135variable. 136.Sh FILES 137.Bl -tag -width /boot/gptzfsboot -compact 138.It Pa /boot/gptzfsboot 139boot code binary 140.It Pa /boot.config 141parameters for the boot block 142.Pq optional 143.It Pa /boot/config 144alternative parameters for the boot block 145.Pq optional 146.El 147.Sh EXAMPLES 148.Nm 149is typically installed in combination with a 150.Dq protective MBR 151.Po 152see 153.Xr gpart 8 154.Pc . 155To install 156.Nm 157on the 158.Pa ada0 159drive: 160.Bd -literal -offset indent 161gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 162.Ed 163.Pp 164.Nm 165can also be installed without the PMBR: 166.Bd -literal -offset indent 167gpart bootcode -p /boot/gptzfsboot -i 1 ada0 168.Ed 169.Sh SEE ALSO 170.Xr boot.config 5 , 171.Xr boot 8 , 172.Xr gpart 8 , 173.Xr loader 8 , 174.Xr zfsloader 8 , 175.Xr zpool 8 176.Sh HISTORY 177.Nm 178appeared in FreeBSD 7.3. 179.Sh AUTHORS 180This manual page was written by 181.An Andriy Gapon Aq avg@FreeBSD.org . 182.Sh BUGS 183.Nm 184looks for ZFS meta-data only in MBR partitions 185.Pq known on FreeBSD as slices . 186It does not look into BSD 187.Xr disklabel 8 188partitions that are traditionally called partitions. 189If a disklabel partition happens to be placed so that ZFS meta-data can be 190found at the fixed offsets relative to a slice, then 191.Nm 192will recognize the partition as a part of a ZFS pool, 193but this is not guaranteed to happen. 194