freebsd-dev/sbin/nextboot/nextboot.8

.\" $FreeBSD$
.Dd July 9, 1996
.Dt NEXTBOOT 8
.Os FreeBSD
.Sh NAME
.Nm nextboot
.Nd install a default bootstring block on the boot disk
.Sh SYNOPSIS
.Nm
.Op Fl b
.Ar filename bootstring
.Ar
.Nm
.Op Fl ed
.Ar filename
.Sh DESCRIPTION
The
.Fx
program
.Nm
controls the actions of the boot blocks at the time of the next boot.
If compiled with the correct option,
the boot blocks will check the nameblock for a magic number and a 
default name to use for booting.
If compiled to do so they will also 
delete the name from the block, ensuring that if the boot should fail,
then it will not be tried again.
It is the job of
.Pa /etc/rc
to use 
.Nm
to re-install the string if that boot is found to have succeeded.
This allows a one-time only boot string to be used for such applications
as remote debugging, and installation of new, untrusted kernels.
The nameblock is defined at compile time to be the second physical block
on the disk.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl b
Is used for bootstrapping (initially configuring) the nameblock.
Without
this, 
.Nm
will refuse to write to a block that does not already contain the magic
number.
.It Fl d
Disable (temporarily) an existing name block by changing a bit
in the magic number.
.It Fl e
Restore the good magic number on a block disabled by
.Fl d .
.El
.Pp
The
.Fl e
and
.Fl d
flags are mutually exclusive.
.Sh DESCRIPTION
.Nm Nextboot
first checks that the disk has an fdisk table and checks that none of the 
partitions defined in that table include the nameblock.
If the name block is 
shown to be unused, it will install the bootstrings given as arguments,
one after the other, each preceded by a small magic number, and NULL
terminated.
The end of the list of strings is delimited by a sequence of 
0xff bytes.
If the boot blocks are compiled to write back the nameblock
after each boot, it will zero out the supplied names as it uses them,
one per boot,
until it reaches the 0xff, at which time it will revert to the compiled in
boot string.
At this time the nameblock will contain only zeroed out names.
.Pp
An example of usage might be:
.Bd -literal
   nextboot -b  /dev/rwd0 1:sd(0,a)/kernel.experimental wd(0,a)/kernel.old
.Ed
.Pp
Which would instruct the boot blocks at the next boot,
to try boot the experimental kernel off the SCSI disk.
If for any reason this failed, the next boot attempt would 
boot the kernel
.Pa /kernel.old
off the IDE drive.  (Assuming the write-back option were enabled) If this
in turn failed.
The compiled in default would be used.
.Pp
If the write-back feature is disabled, the nextboot program is a convenient way
to change the default boot string.
Note, that should the file specified in
the nameblock be non-existent, then the name compiled into the boot blocks
will be used for the boot rather than the next name in the nameblock.
The 
nameblock is only consulted
.Em once
per boot.
.Sh SEE ALSO
.Xr boot 8 ,
.Xr disklabel 8 ,
.Xr fdisk 8
.Sh BUGS
This program works only in conjunction with the legacy boot code.
.Pp
The entire program should be made more user-friendly.
The option of whether to write back or not should be stored on the
disk and not a compile time option.
I want to rethink this at some 
later stage to make it co-exist with disks that do not have
a fdisk partitioning table (i.e. purely disklabel'd systems).
.Pp
Whether to write back or not should be specified at run-time in the nameblock
so that the boot blocks need not be altered to get this feature.
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Dd July 9, 1996`
			`.Dt NEXTBOOT 8`
mdoc(7) police: added missing .Os call. 2000-12-14 13:58:15 +00:00			`.Os FreeBSD`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Sh NAME`
			`.Nm nextboot`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`.Nd install a default bootstring block on the boot disk`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 16:52:27 +00:00			`.Nm`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Op Fl b`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`.Ar filename bootstring`
			`.Ar`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 16:52:27 +00:00			`.Nm`
Minor formatting/style fixes. Submitted by: Sandro Sigala <sandro@cat.local.net> as part of PR# 2134 1996-12-09 08:04:55 +00:00			`.Op Fl ed`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Ar filename`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`.Sh DESCRIPTION`
			`The`
Use Fx macro wherever possible. 2000-11-14 11:20:58 +00:00			`.Fx`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`program`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Nm`
			`controls the actions of the boot blocks at the time of the next boot.`
			`If compiled with the correct option,`
			`the boot blocks will check the nameblock for a magic number and a`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`default name to use for booting.`
			`If compiled to do so they will also`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`delete the name from the block, ensuring that if the boot should fail,`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`then it will not be tried again.`
			`It is the job of`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`.Pa /etc/rc`
			`to use`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Nm`
			`to re-install the string if that boot is found to have succeeded.`
			`This allows a one-time only boot string to be used for such applications`
			`as remote debugging, and installation of new, untrusted kernels.`
			`The nameblock is defined at compile time to be the second physical block`
			`on the disk.`
			`.Pp`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`The following options are available:`
			`.Bl -tag -width indent`
			`.It Fl b`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`Is used for bootstrapping (initially configuring) the nameblock.`
			`Without`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`this,`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Nm`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`will refuse to write to a block that does not already contain the magic`
			`number.`
			`.It Fl d`
			`Disable (temporarily) an existing name block by changing a bit`
			`in the magic number.`
			`.It Fl e`
			`Restore the good magic number on a block disabled by`
			`.Fl d .`
			`.El`
			`.Pp`
			`The`
			`.Fl e`
			`and`
			`.Fl d`
			`flags are mutually exclusive.`
			`.Sh DESCRIPTION`
			`.Nm Nextboot`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`first checks that the disk has an fdisk table and checks that none of the`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`partitions defined in that table include the nameblock.`
			`If the name block is`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`shown to be unused, it will install the bootstrings given as arguments,`
			`one after the other, each preceded by a small magic number, and NULL`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`terminated.`
			`The end of the list of strings is delimited by a sequence of`
			`0xff bytes.`
			`If the boot blocks are compiled to write back the nameblock`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`after each boot, it will zero out the supplied names as it uses them,`
			`one per boot,`
			`until it reaches the 0xff, at which time it will revert to the compiled in`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`boot string.`
			`At this time the nameblock will contain only zeroed out names.`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Pp`
			`An example of usage might be:`
			`.Bd -literal`
			`nextboot -b /dev/rwd0 1:sd(0,a)/kernel.experimental wd(0,a)/kernel.old`
			`.Ed`
			`.Pp`
			`Which would instruct the boot blocks at the next boot,`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`to try boot the experimental kernel off the SCSI disk.`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`If for any reason this failed, the next boot attempt would`
			`boot the kernel`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`.Pa /kernel.old`
			`off the IDE drive. (Assuming the write-back option were enabled) If this`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`in turn failed.`
			`The compiled in default would be used.`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Pp`
			`If the write-back feature is disabled, the nextboot program is a convenient way`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`to change the default boot string.`
			`Note, that should the file specified in`
Spelling police. 1997-04-23 04:46:38 +00:00			`the nameblock be non-existent, then the name compiled into the boot blocks`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`will be used for the boot rather than the next name in the nameblock.`
			`The`
Add rcsid. Remove unused #includes. Use err(3) and check spelling. Reorganize man page. 1998-06-30 06:28:18 +00:00			`nameblock is only consulted`
			`.Em once`
			`per boot.`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Sh SEE ALSO`
add missing comma(s) in .Xr macros 1996-09-23 22:24:39 +00:00			`.Xr boot 8 ,`
			`.Xr disklabel 8 ,`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Xr fdisk 8`
			`.Sh BUGS`
Note that nextboot requires the legacy boot code. 1999-02-05 09:58:39 +00:00			`This program works only in conjunction with the legacy boot code.`
			`.Pp`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`The entire program should be made more user-friendly.`
slight man page additions re: deficiencies 1996-08-09 22:41:57 +00:00			`The option of whether to write back or not should be stored on the`
Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. 2000-03-01 11:27:47 +00:00			`disk and not a compile time option.`
			`I want to rethink this at some`
slight man page additions re: deficiencies 1996-08-09 22:41:57 +00:00			`later stage to make it co-exist with disks that do not have`
Minor formatting/style fixes. Submitted by: Sandro Sigala <sandro@cat.local.net> as part of PR# 2134 1996-12-09 08:04:55 +00:00			`a fdisk partitioning table (i.e. purely disklabel'd systems).`
Obtained from: Whistle Communications control program to control the facility of the bootblocks to fetch a default bootstring from a fixed location on the disk. See the manpage for more info. 1996-07-09 02:04:32 +00:00			`.Pp`
			`Whether to write back or not should be specified at run-time in the nameblock`
			`so that the boot blocks need not be altered to get this feature.`