share/man/man5/gptzfsboot.5

   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 Apr 21, 2017
  26 .Dt GPTZFSBOOT 5
  27 .Os
  28 .Sh NAME
  29 .Nm gptzfsboot
  30 .Nd disk bootcode for BIOS-based computers
  31 .Sh DESCRIPTION
  32 .Nm
  33 is used on BIOS-based computers to boot from a filesystem on disk device.
  34 Depending on disk partitioning and boot file system, the
  35 .Nm
  36 is installed in a
  37 .Cm zfs pool boot area
  38 or
  39 .Cm boot
  40 partition of a disk with
  41 .Xr installboot 1M .
  42 .Ss 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 .Ss 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 Disks are probed in BIOS defined order.
  54 After a disk is probed and
  55 .Nm
  56 determines that the whole disk is not a ZFS pool member, the
  57 individual partitions are probed in their partition table order.
  58 Currently GPT and MBR partition schemes are supported.
  59 .Pp
  60 The default boot partition is recorded into
  61 .Nm
  62 binary by
  63 .Xr installboot 1M
  64 and the default boot file system is determined at run time.
  65 .Nm
  66 does support booting from the
  67 .Cm ZFS ,
  68 .Cm UFS
  69 and
  70 .Cm PCFS
  71 file systems.
  72 .Pp
  73 The filesystem specified by the
  74 .Cm bootfs
  75 property of the ZFS pool is used as a default boot filesystem.
  76 If the
  77 .Cm bootfs
  78 property is not set, then the root filesystem of the pool is used as
  79 the default.
  80 .Xr zfsloader 5
  81 is loaded from the boot filesystem.
  82 If
  83 .Pa /boot/config
  84 is present in the boot filesystem, boot options are read from it.
  85 .Pp
  86 The ZFS GUIDs of the boot pool and boot file system are made available to
  87 .Xr zfsloader 8 .
  88 .Ss USAGE
  89 Normally
  90 .Nm
  91 will boot in fully automatic mode.
  92 However, it is possible to interrupt the automatic boot process and
  93 interact with
  94 .Nm
  95 through a prompt.
  96 .Pp
  97 The filesystem specification and the path to
  98 .Xr zfsloader 5
  99 is specified as
 100 .Pp
 101 .Sm off
 102 .Oo zfs:pool/filesystem: Oc Oo /path/to/loader Oc
 103 .Sm on
 104 .Pp
 105 Both the filesystem and the path can be specified.
 106 If only a path is specified, then the default filesystem is used.
 107 If only a pool and filesystem are specified, then
 108 .Pa /boot/zfsloader
 109 is used as a path.
 110 .Pp
 111 Additionally, the
 112 .Nm
 113 does support two commands to get information about the system.
 114 .Ic ?directoryname
 115 can be used to list the content of named directory and
 116 .Ic status
 117 command can be used to query information about discovered devices.
 118 The output format for ZFS pools is similar to that of
 119 .Cm zpool status
 120 .Pq see Xr zpool 1M .
 121 .Pp
 122 The configured or automatically determined ZFS boot filesystem is
 123 stored in the
 124 .Xr zfsloader 5
 125 .Cm loaddev
 126 variable, and also set as the initial value of the
 127 .Cm currdev
 128 variable.
 129 .Sh FILES
 130 .Bl -tag -width /boot/gptzfsboot -compact
 131 .It Pa /boot/config
 132 parameters for the boot block
 133 .Pq optional
 134 .It Pa /boot/gptzfsboot
 135 boot code binary
 136 .El
 137 .Sh EXAMPLES
 138 .Nm
 139 is installed in combination with a
 140 .Dq protective MBR
 141 .Po
 142 see
 143 .Xr installboot 1M
 144 .Pc .
 145 To install
 146 .Nm
 147 on the
 148 .Pa c0t0d0s0
 149 drive:
 150 .Bd -literal -offset indent
 151 installboot /boot/pmbr /boot/gptzfsboot /dev/rdsk/c0t0d0s0
 152 .Ed
 153 .Sh SEE ALSO
 154 .Xr installboot 1M ,
 155 .Xr zpool 1M ,
 156 .Xr loader 5 ,
 157 .Xr zfsloader 5