Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GPTBOOT(8)		FreeBSD	System Manager's Manual		    GPTBOOT(8)

     gptboot --	GPT bootcode for UFS on	BIOS-based computers

     gptboot is	used on	BIOS-based computers to	boot from a UFS	partition on a
     GPT-partitioned disk.  gptboot is installed in a freebsd-boot partition
     with gpart(8).

     When it starts, gptboot first reads the GPT and determines	which drive
     and partition to boot from, as described under BOOTING, below.  If	it
     does not find an eligible partition, or if	the user hits a	key within
     three seconds, gptboot switches from auto-boot to interactive mode.  In-
     teractive mode allows manual selection of the disk, partition, filename,
     and boot option flags, as described in boot(8).

     The GPT standard allows a variable	number of partitions, but gptboot only
     boots from	tables with 128	partitions or less.

     gptboot checks and	manages	several	attributes of GPT UFS partitions.

     bootme	 Attempt to boot from this partition.  If more than one	parti-
		 tion has the bootme attribute set, gptboot will attempt to
		 boot each one until successful.

     bootonce	 Attempt to boot from this partition only one time.  Setting
		 this attribute	with gpart(8) automatically also sets the
		 bootme	attribute.  Multiple partitions	may have the bootonce
		 and bootme attributes set.

     bootfailed	 The bootfailed	attribute marks	partitions that	had the
		 bootonce attribute set, but failed to boot.  This attribute
		 is managed by the system.  See	BOOTING	and POST-BOOT ACTIONS
		 below for details.

     For normal	usage, the user	does not have to set or	manage any of the par-
     tition attributes.	 gptboot will boot from	the first UFS partition	found.

     The bootonce attribute can	be used	for testing an upgraded	operating sys-
     tem 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 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	suc-
     cessful boot of the test partition, a user	script can check the logs and
     change the	bootme attributes so the test partition	becomes	the new	system
     partition.	 Because the 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 bootme	attribute is set on any	partitions, booting will be attempted
     from them first.  If no partitions	with bootme attributes are found,
     booting will be attempted from the	first UFS partition found.

     gptboot first reads the partition table.  All freebsd-ufs partitions with
     only the bootonce attribute set, indicating a failed boot,	are set	to
     bootfailed.  gptboot then scans through all of the	freebsd-ufs parti-
     tions.  Boot behavior depends on the combination of bootme	and bootonce
     attributes	set on those partitions.

     bootonce +	bootme	    Highest priority: booting is attempted from	each
			    of the freebsd-ufs partitions with both of these
			    attributes.	 On each partition, the	bootme attri-
			    bute is removed and	the boot attempted.

     bootme		    Middle priority: booting is	attempted from each of
			    the	freebsd-ufs partitions with the	bootme attri-

     If	neither	bootonce nor bootme attributes are found on any	partitions,
     booting is	attempted from the first freebsd-ufs partition on the disk.

     The startup script	/etc/rc.d/gptboot checks the attributes	of freebsd-ufs
     partitions	on all GPT disks.  Partitions with the bootfailed attribute
     generate a	"boot from X failed" system log	message.  Partitions with only
     the bootonce attribute, indicating	a partition that successfully booted,
     generate a	"boot from X succeeded"	system log message.  The bootfailed
     attributes	are cleared from all the partitions.  The bootonce attribute
     is	cleared	from the partition that	successfully booted.  There is nor-
     mally only	one of these.

     /boot/gptboot  bootcode binary
     /boot.config   parameters for the boot blocks (optional)

     gptboot is	installed in a freebsd-boot partition, usually the first par-
     tition on the disk.  A "protective	MBR" (see gpart(8)) is typically in-
     stalled in	combination with gptboot.

     Install gptboot on	the ada0 drive:

	   gpart bootcode -b /boot/pmbr	-p /boot/gptboot -i 1 ada0

     gptboot can also be installed without the PMBR:

	   gpart bootcode -p /boot/gptboot -i 1	ada0

     Set the bootme attribute for partition 2:

	   gpart set -a	bootme -i 2 ada0

     Set the bootonce attribute	for partition 2, automatically also setting
     the bootme	attribute:

	   gpart set -a	bootonce -i 2 ada0

     boot.config(5), rc.conf(5), boot(8), gpart(8)

     gptboot appeared in FreeBSD 7.1.

     This manual page written by Warren	Block <>.

FreeBSD	13.0			April 30, 2019			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help