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