sys/boot/i386/gptzfsboot/gptzfsboot.8

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