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