stand/i386/gptboot/gptboot.8

   1 .\" Copyright (c) 2013 Warren Block
   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 April 30, 2019
  28 .Dt GPTBOOT 8
  29 .Os
  30 .Sh NAME
  31 .Nm gptboot
  32 .Nd GPT bootcode for UFS on BIOS-based computers
  33 .Sh DESCRIPTION
  34 .Nm
  35 is used on BIOS-based computers to boot from a UFS partition on a
  36 GPT-partitioned disk.
  37 .Nm
  38 is installed in a
  39 .Cm freebsd-boot
  40 partition with
  41 .Xr gpart 8 .
  42 .Pp
  43 When it starts,
  44 .Nm
  45 first reads the GPT and determines which drive and partition to
  46 boot from, as described under
  47 .Sx BOOTING ,
  48 below.
  49 If it does not find an eligible partition, or if the user hits a
  50 key within three seconds,
  51 .Nm
  52 switches from auto-boot to interactive mode.
  53 Interactive mode allows manual selection of the disk, partition,
  54 filename, and boot option flags, as described in
  55 .Xr boot 8 .
  56 .Sh IMPLEMENTATION NOTES
  57 The GPT standard allows a variable number of partitions, but
  58 .Nm
  59 only boots from tables with 128 partitions or less.
  60 .Sh PARTITION ATTRIBUTES
  61 .Nm
  62 checks and manages several attributes of GPT UFS partitions.
  63 .Bl -tag -width ".Cm bootfailed"
  64 .It Cm bootme
  65 Attempt to boot from this partition.
  66 If more than one partition has the
  67 .Cm bootme
  68 attribute set,
  69 .Nm
  70 will attempt to boot each one until successful.
  71 .It Cm bootonce
  72 Attempt to boot from this partition only one time.
  73 Setting this attribute with
  74 .Xr gpart 8
  75 automatically also sets the
  76 .Cm bootme
  77 attribute.
  78 Multiple partitions may have the
  79 .Cm bootonce
  80 and
  81 .Cm bootme
  82 attributes set.
  83 .It Cm bootfailed
  84 The
  85 .Cm bootfailed
  86 attribute marks partitions that had the
  87 .Cm bootonce
  88 attribute set, but failed to boot.
  89 This attribute is managed by the system.
  90 See
  91 .Sx "BOOTING"
  92 and
  93 .Sx "POST-BOOT ACTIONS"
  94 below for details.
  95 .El
  96 .Sh USAGE
  97 For normal usage, the user does not have to set or manage any of the
  98 partition attributes.
  99 .Nm
 100 will boot from the first UFS partition found.
 101 .Pp
 102 The
 103 .Cm bootonce
 104 attribute can be used for testing an upgraded operating system on
 105 an already-working computer.
 106 The existing system partition is left untouched, and the new version
 107 of the operating system to be tested is installed on another partition.
 108 The
 109 .Cm bootonce
 110 attribute is set on that new test partition.
 111 The next boot is attempted from the test partition.
 112 Success or failure will be shown in the system log files.
 113 After a successful boot of the test partition, a user script can check
 114 the logs and change the
 115 .Cm bootme
 116 attributes so the test partition becomes the new system partition.
 117 Because the
 118 .Cm bootonce
 119 attribute is cleared after an attempted boot, a failed boot will not
 120 leave the system attempting to boot from a partition that will never
 121 succeed.
 122 Instead, the system will boot from the older, known-working operating
 123 system that has not been modified.
 124 If the
 125 .Cm bootme
 126 attribute is set on any partitions, booting will be attempted from them
 127 first.
 128 If no partitions with
 129 .Cm bootme
 130 attributes are found, booting will be attempted from the first UFS
 131 partition found.
 132 .Sh BOOTING
 133 .Nm
 134 first reads the partition table.
 135 All
 136 .Cm freebsd-ufs
 137 partitions with only the
 138 .Cm bootonce
 139 attribute set, indicating a failed boot, are set to
 140 .Cm bootfailed .
 141 .Nm
 142 then scans through all of the
 143 .Cm freebsd-ufs
 144 partitions.
 145 Boot behavior depends on the combination of
 146 .Cm bootme
 147 and
 148 .Cm bootonce
 149 attributes set on those partitions.
 150 .Bl -tag -width ".Cm bootonce + .Cm bootme"
 151 .It Cm bootonce + Cm bootme
 152 Highest priority: booting is attempted from each of the
 153 .Cm freebsd-ufs
 154 partitions with both of these attributes.
 155 On each partition, the
 156 .Cm bootme
 157 attribute is removed and the boot attempted.
 158 .It Cm bootme
 159 Middle priority: booting is attempted from each of the
 160 .Cm freebsd-ufs
 161 partitions with the
 162 .Cm bootme
 163 attribute.
 164 .El
 165 .Pp
 166 If neither
 167 .Cm bootonce
 168 nor
 169 .Cm bootme
 170 attributes are found on any partitions, booting is attempted from the
 171 first
 172 .Cm freebsd-ufs
 173 partition on the disk.
 174 .Sh POST-BOOT ACTIONS
 175 The startup script
 176 .Pa /etc/rc.d/gptboot
 177 checks the attributes of
 178 .Cm freebsd-ufs
 179 partitions on all GPT disks.
 180 Partitions with the
 181 .Cm bootfailed
 182 attribute generate a
 183 .Dq boot from X failed
 184 system log message.
 185 Partitions with only the
 186 .Cm bootonce
 187 attribute, indicating a partition that successfully booted, generate a
 188 .Dq boot from X succeeded
 189 system log message.
 190 The
 191 .Cm bootfailed
 192 attributes are cleared from all the partitions.
 193 The
 194 .Cm bootonce
 195 attribute is cleared from the partition that successfully booted.
 196 There is normally only one of these.
 197 .Sh FILES
 198 .Bl -tag -width /boot/gptboot -compact
 199 .It Pa /boot/gptboot
 200 bootcode binary
 201 .It Pa /boot.config
 202 parameters for the boot blocks
 203 .Pq optional
 204 .El
 205 .Sh EXAMPLES
 206 .Nm
 207 is installed in a
 208 .Cm freebsd-boot
 209 partition, usually the first partition on the disk.
 210 A
 211 .Dq protective MBR
 212 .Po
 213 see
 214 .Xr gpart 8
 215 .Pc
 216 is typically installed in combination with
 217 .Nm .
 218 .Pp
 219 Install
 220 .Nm
 221 on the
 222 .Pa ada0
 223 drive:
 224 .Bd -literal -offset indent
 225 gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0
 226 .Ed
 227 .Pp
 228 .Nm
 229 can also be installed without the PMBR:
 230 .Bd -literal -offset indent
 231 gpart bootcode -p /boot/gptboot -i 1 ada0
 232 .Ed
 233 .Pp
 234 Set the
 235 .Cm bootme
 236 attribute for partition 2:
 237 .Bd -literal -offset indent
 238 gpart set -a bootme -i 2 ada0
 239 .Ed
 240 .Pp
 241 Set the
 242 .Cm bootonce
 243 attribute for partition 2, automatically also setting the
 244 .Cm bootme
 245 attribute:
 246 .Bd -literal -offset indent
 247 gpart set -a bootonce -i 2 ada0
 248 .Ed
 249 .Sh SEE ALSO
 250 .Xr boot.config 5 ,
 251 .Xr rc.conf 5 ,
 252 .Xr boot 8 ,
 253 .Xr gpart 8
 254 .Sh HISTORY
 255 .Nm
 256 appeared in FreeBSD 7.1.
 257 .Sh AUTHORS
 258 This manual page written by
 259 .An Warren Block Aq wblock@FreeBSD.org .