svn commit: r252492 - in head: sbin/geom/class/part sbin/reboot sys/boot/i386/gptboot
Warren Block
wblock at FreeBSD.org
Mon Jul 1 22:38:38 UTC 2013
Author: wblock (doc committer)
Date: Mon Jul 1 22:38:36 2013
New Revision: 252492
URL: http://svnweb.freebsd.org/changeset/base/252492
Log:
Add a new gptboot(8) man page. Factor out the redundant information
in gpart(8) and boot(8), adding references to gptboot(8) in both.
Reviewed by: jhb, ae, pjd, Paul Schenkeveld <bsdcan at psconsult.nl>, david_a_bright at dell.com (portions), gjb
MFC after: 1 week
Added:
head/sys/boot/i386/gptboot/gptboot.8 (contents, props changed)
Modified:
head/sbin/geom/class/part/gpart.8
head/sbin/reboot/boot_i386.8
head/sys/boot/i386/gptboot/Makefile
Modified: head/sbin/geom/class/part/gpart.8
==============================================================================
--- head/sbin/geom/class/part/gpart.8 Mon Jul 1 22:21:42 2013 (r252491)
+++ head/sbin/geom/class/part/gpart.8 Mon Jul 1 22:38:36 2013 (r252492)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd January 25, 2013
+.Dd July 1, 2013
.Dt GPART 8
.Os
.Sh NAME
@@ -645,14 +645,12 @@ The scheme-specific attributes for GPT:
When set, the
.Nm gptboot
stage 1 boot loader will try to boot the system from this partition.
-Multiple partitions might be marked with the
+Multiple partitions can be marked with the
.Cm bootme
attribute.
-In such scenario the
-.Nm gptboot
-will try all
-.Cm bootme
-partitions one by one, until the next boot stage is successfully entered.
+See
+.Xr gptboot 8
+for more details.
.It Cm bootonce
Setting this attribute automatically sets the
.Cm bootme
@@ -660,49 +658,14 @@ attribute.
When set, the
.Nm gptboot
stage 1 boot loader will try to boot the system from this partition only once.
-Partitions with both
-.Cm bootonce
-and
-.Cm bootme
-attributes are tried before partitions with only the
-.Cm bootme
-attribute.
-Before
-.Cm bootonce
-partition is tried, the
-.Nm gptboot
-removes the
-.Cm bootme
-attribute and tries to execute the next boot stage.
-If it fails, the
-.Cm bootonce
-attribute that is now alone is replaced with the
-.Cm bootfailed
-attribute.
-If the execution of the next boot stage succeeds, but the system is not fully
-booted, the
-.Nm gptboot
-will look for
-.Cm bootonce
-attributes alone (without the
-.Cm bootme
-attribute) on the next system boot and will replace those with the
-.Cm bootfailed
-attribute.
-If the system is fully booted, the
-.Pa /etc/rc.d/gptboot
-start-up script will look for partition with the
-.Cm bootonce
-attribute alone, will remove the attribute and log that the system was
-successfully booted from this partition.
-There should be at most one
-.Cm bootonce
-partition when system is successfully booted.
-Multiple partitions might be marked with the
+Multiple partitions can be marked with the
.Cm bootonce
and
.Cm bootme
attribute pairs.
+See
+.Xr gptboot 8
+for more details.
.It Cm bootfailed
This attribute should not be manually managed.
It is managed by the
@@ -710,14 +673,9 @@ It is managed by the
stage 1 boot loader and the
.Pa /etc/rc.d/gptboot
start-up script.
-This attribute is used to mark partitions that had the
-.Cm bootonce
-attribute set, but we failed to boot from them.
-Once we successfully boot, the
-.Pa /etc/rc.d/gptboot
-script will log all the partitions we failed to boot from and will remove the
-.Cm bootfailed
-attributes.
+See
+.Xr gptboot 8
+for more details.
.El
.Pp
The scheme-specific attributes for MBR:
@@ -795,20 +753,17 @@ There are two variants of bootstrap code
.Pa /boot/gptboot
and
.Pa /boot/gptzfsboot .
+.Pp
.Pa /boot/gptboot
-is used to boot from UFS.
-It searches through
+is used to boot from UFS partitions.
+.Cm gptboot
+searches through
.Cm freebsd-ufs
-partitions in the GPT and boots from the first one with the
+partitions in the GPT and selects one to boot based on the
.Cm bootonce
-attribute set.
-If that attribute is not found,
-.Pa /boot/gptboot
-boots from the first
-.Cm freebsd-ufs
-partition with the
+and
.Cm bootme
-attribute set.
+attributes.
If neither attribute is found,
.Pa /boot/gptboot
boots from the first
@@ -817,6 +772,10 @@ partition.
.Pa /boot/loader
.Pq the third bootstrap stage
is loaded from the first partition that matches these conditions.
+See
+.Xr gptboot 8
+for more information.
+.Pp
.Pa /boot/gptzfsboot
is used to boot from ZFS.
It searches through the GPT for
@@ -1105,7 +1064,8 @@ and
.Xr dd 1 ,
.Xr geom 4 ,
.Xr boot0cfg 8 ,
-.Xr geom 8
+.Xr geom 8 ,
+.Xr gptboot 8
.Sh HISTORY
The
.Nm
Modified: head/sbin/reboot/boot_i386.8
==============================================================================
--- head/sbin/reboot/boot_i386.8 Mon Jul 1 22:21:42 2013 (r252491)
+++ head/sbin/reboot/boot_i386.8 Mon Jul 1 22:38:36 2013 (r252492)
@@ -36,7 +36,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 4, 2010
+.Dd July 1, 2013
.Dt BOOT 8 i386
.Os
.Sh NAME
@@ -351,6 +351,7 @@ requirement has not been adhered to.
.Xr bsdlabel 8 ,
.Xr btxld 8 ,
.Xr config 8 ,
+.Xr gptboot 8 ,
.Xr halt 8 ,
.Xr loader 8 ,
.Xr nextboot 8 ,
Modified: head/sys/boot/i386/gptboot/Makefile
==============================================================================
--- head/sys/boot/i386/gptboot/Makefile Mon Jul 1 22:21:42 2013 (r252491)
+++ head/sys/boot/i386/gptboot/Makefile Mon Jul 1 22:38:36 2013 (r252492)
@@ -3,6 +3,7 @@
.PATH: ${.CURDIR}/../boot2 ${.CURDIR}/../common ${.CURDIR}/../../common
FILES= gptboot
+MAN= gptboot.8
NM?= nm
Added: head/sys/boot/i386/gptboot/gptboot.8
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/sys/boot/i386/gptboot/gptboot.8 Mon Jul 1 22:38:36 2013 (r252492)
@@ -0,0 +1,236 @@
+.\" Copyright (c) 2013 Warren Block
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 1, 2013
+.Dt GPTBOOT 8
+.Os
+.Sh NAME
+.Nm gptboot
+.Nd GPT bootcode for UFS on BIOS-based computers
+.Sh DESCRIPTION
+.Nm
+is used on BIOS-based computers to boot from a UFS partition on a
+GPT-partitioned disk.
+.Nm
+is installed in a
+.Cm freebsd-boot
+partition with
+.Xr gpart 8 .
+.Sh IMPLEMENTATION NOTES
+The GPT standard allows a variable number of partitions, but
+.Nm
+only boots from tables with 128 partitions or less.
+.Sh PARTITION ATTRIBUTES
+.Nm
+checks and manages several attributes of GPT UFS partitions.
+.Bl -tag -width ".Cm bootfailed"
+.It Cm bootme
+Attempt to boot from this partition.
+If more than one partition has the
+.Cm bootme
+attribute set,
+.Nm
+will attempt to boot each one until successful.
+.It Cm bootonce
+Attempt to boot from this partition only one time.
+Setting this attribute with
+.Xr gpart 8
+automatically also sets the
+.Cm bootme
+attribute.
+Multiple partitions may have the
+.Cm bootonce
+and
+.Cm bootme
+attributes set.
+.It Cm bootfailed
+The
+.Cm bootfailed
+attribute marks partitions that had the
+.Cm bootonce
+attribute set, but failed to boot.
+This attribute is managed by the system.
+See
+.Sx "BOOTING"
+and
+.Sx "POST-BOOT ACTIONS"
+below for details.
+.El
+.Sh USAGE
+For normal usage, the user does not have to set or manage any of the
+partition attributes.
+.Nm
+will boot from the first UFS partition found.
+.Pp
+The
+.Cm bootonce
+attribute can be used for testing an upgraded operating system on
+an already-working computer.
+The existing system partition is left untouched, and the new version
+of the operating system to be tested is installed on another partition.
+The
+.Cm bootonce
+attribute is set on that new test partition.
+The next boot is attempted from the test partition.
+Success or failure will be shown in the system log files.
+After a successful boot of the test partition, a user script can check
+the logs and change the
+.Cm bootme
+attributes so the test partition becomes the new system partition.
+Because the
+.Cm bootonce
+attribute is cleared after an attempted boot, a failed boot will not
+leave the system attempting to boot from a partition that will never
+succeed.
+Instead, the system will boot from the older, known-working operating
+system that has not been modified.
+If the
+.Cm bootme
+attribute is set on any partitions, booting will be attempted from them
+first.
+If no partitions with
+.Cm bootme
+attributes are found, booting will be attempted from the first UFS
+partition found.
+.Sh BOOTING
+.Nm
+first reads the partition table.
+All
+.Cm freebsd-ufs
+partitions with only the
+.Cm bootonce
+attribute set, indicating a failed boot, are set to
+.Cm bootfailed .
+.Nm
+then scans through all of the
+.Cm freebsd-ufs
+partitions.
+Boot behavior depends on the combination of
+.Cm bootme
+and
+.Cm bootonce
+attributes set on those partitions.
+.Bl -tag -width ".Cm bootonce + .Cm bootme"
+.It Cm bootonce + Cm bootme
+Highest priority: booting is attempted from each of the
+.Cm freebsd-ufs
+partitions with both of these attributes.
+On each partition, the
+.Cm bootme
+attribute is removed and the boot attempted.
+.It Cm bootme
+Middle priority: booting is attempted from each of the
+.Cm freebsd-ufs
+partitions with the
+.Cm bootme
+attribute.
+.It neither
+If neither
+.Cm bootonce
+nor
+.Cm bootme
+attributes are found on any partitions, booting is attempted from the
+first
+.Cm freebsd-ufs
+partition on the disk.
+.El
+.Sh POST-BOOT ACTIONS
+The startup script
+.Pa /etc/rc.d/gptboot
+checks the attributes of
+.Cm freebsd-ufs
+partitions on all GPT disks.
+Partitions with the
+.Cm bootfailed
+attribute generate a
+.Dq boot from X failed
+system log message.
+Partitions with only the
+.Cm bootonce
+attribute, indicating a partition that successfully booted, generate a
+.Dq boot from X succeeded
+system log message.
+The
+.Cm bootfailed
+attributes are cleared from all the partitions.
+The
+.Cm bootonce
+attribute is cleared from the partition that successfully booted.
+There is normally only one of these.
+.Sh FILES
+.Bl -tag -width /boot/loader -compact
+.It Pa /boot/gptboot
+.It Pa /boot.config
+.El
+.Sh EXAMPLES
+.Nm
+is typically installed in combination with a
+.Dq protective MBR
+.Po
+see
+.Xr gpart 8
+.Pc .
+Install
+.Nm
+on the
+.Pa ada0
+drive:
+.Bd -literal -offset indent
+gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0
+.Ed
+.Pp
+.Nm
+can also be installed without the PMBR:
+.Bd -literal -offset indent
+gpart bootcode -p /boot/gptboot -i 1 ada0
+.Ed
+.Pp
+Set the
+.Cm bootme
+attribute for partition 2:
+.Bd -literal -offset indent
+gpart set -a bootme -i 2 ada0
+.Ed
+.Pp
+Set the
+.Cm bootonce
+attribute for partition 2, automatically also setting the
+.Cm bootme
+attribute:
+.Bd -literal -offset indent
+gpart set -a bootonce -i 2 ada0
+.Ed
+.Pp
+.Sh SEE ALSO
+.Xr boot.config 5 ,
+.Xr rc.conf 5 ,
+.Xr boot 8 ,
+.Xr gpart 8
+.Sh HISTORY
+.Nm
+appeared in FreeBSD 7.1.
+.Sh AUTHORS
+Warren Block <wblock at FreeBSD.org>
More information about the svn-src-head
mailing list