From owner-svn-src-all@FreeBSD.ORG Mon Jul 1 22:38:37 2013 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id E51D8366; Mon, 1 Jul 2013 22:38:37 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id D45FE1732; Mon, 1 Jul 2013 22:38:37 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r61Mcbee082955; Mon, 1 Jul 2013 22:38:37 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r61McbFM082949; Mon, 1 Jul 2013 22:38:37 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307012238.r61McbFM082949@svn.freebsd.org> From: Warren Block Date: Mon, 1 Jul 2013 22:38:37 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r252492 - in head: sbin/geom/class/part sbin/reboot sys/boot/i386/gptboot X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 01 Jul 2013 22:38:38 -0000 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 , david_a_bright@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