sbin/i386/nextboot/nextboot.8

   1 .\" $FreeBSD: src/sbin/i386/nextboot/nextboot.8,v 1.11.2.5 2003/01/05 19:19:39 semenu Exp $
   2 .\" $DragonFly: src/sbin/i386/nextboot/nextboot.8,v 1.3 2004/03/11 12:28:54 hmp Exp $
   3 .Dd July 9, 1996
   4 .Dt NEXTBOOT 8
   5 .Os
   6 .Sh NAME
   7 .Nm nextboot
   8 .Nd install a default bootstring block on the boot disk
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Op Fl b
  12 .Ar filename bootstring
  13 .Ar
  14 .Nm
  15 .Op Fl ed
  16 .Ar filename
  17 .Sh DESCRIPTION
  18 The
  19 .Dx
  20 program
  21 .Nm
  22 controls the actions of the boot blocks at the time of the next boot.
  23 If compiled with the correct option,
  24 the boot blocks will check the nameblock for a magic number and a
  25 default name to use for booting.
  26 If compiled to do so they will also
  27 delete the name from the block, ensuring that if the boot should fail,
  28 then it will not be tried again.
  29 It is the job of
  30 .Pa /etc/rc
  31 to use
  32 .Nm
  33 to re-install the string if that boot is found to have succeeded.
  34 This allows a one-time only boot string to be used for such applications
  35 as remote debugging, and installation of new, untrusted kernels.
  36 The nameblock is defined at compile time to be the second physical block
  37 on the disk.
  38 .Pp
  39 The following options are available:
  40 .Bl -tag -width indent
  41 .It Fl b
  42 Is used for bootstrapping (initially configuring) the nameblock.
  43 Without
  44 this,
  45 .Nm
  46 will refuse to write to a block that does not already contain the magic
  47 number.
  48 .It Fl d
  49 Disable (temporarily) an existing name block by changing a bit
  50 in the magic number.
  51 .It Fl e
  52 Restore the good magic number on a block disabled by
  53 .Fl d .
  54 .El
  55 .Pp
  56 The
  57 .Fl e
  58 and
  59 .Fl d
  60 flags are mutually exclusive.
  61 .Sh DESCRIPTION
  62 .Nm Nextboot
  63 first checks that the disk has an fdisk table and checks that none of the
  64 partitions defined in that table include the nameblock.
  65 If the name block is
  66 shown to be unused, it will install the bootstrings given as arguments,
  67 one after the other, each preceded by a small magic number, and NULL
  68 terminated.
  69 The end of the list of strings is delimited by a sequence of
  70 0xff bytes.
  71 If the boot blocks are compiled to write back the nameblock
  72 after each boot, it will zero out the supplied names as it uses them,
  73 one per boot,
  74 until it reaches the 0xff, at which time it will revert to the compiled in
  75 boot string.
  76 At this time the nameblock will contain only zeroed out names.
  77 .Pp
  78 An example of usage might be:
  79 .Bd -literal
  80    nextboot -b  /dev/rad0 1:da(0,a)/kernel.experimental ad(0,a)/kernel.old
  81 .Ed
  82 .Pp
  83 Which would instruct the boot blocks at the next boot,
  84 to try boot the experimental kernel off the SCSI disk.
  85 If for any reason this failed, the next boot attempt would
  86 boot the kernel
  87 .Pa /kernel.old
  88 off the IDE drive.  (Assuming the write-back option were enabled) If this
  89 in turn failed.
  90 The compiled in default would be used.
  91 .Pp
  92 If the write-back feature is disabled, the nextboot program is a convenient way
  93 to change the default boot string.
  94 Note, that should the file specified in
  95 the nameblock be non-existent, then the name compiled into the boot blocks
  96 will be used for the boot rather than the next name in the nameblock.
  97 The
  98 nameblock is only consulted
  99 .Em once
 100 per boot.
 101 .Sh SEE ALSO
 102 .Xr boot 8 ,
 103 .Xr disklabel 8 ,
 104 .Xr fdisk 8
 105 .Sh BUGS
 106 This program works only in conjunction with the legacy boot code.
 107 .Pp
 108 The entire program should be made more user-friendly.
 109 The option of whether to write back or not should be stored on the
 110 disk and not a compile time option.
 111 I want to rethink this at some
 112 later stage to make it co-exist with disks that do not have
 113 a fdisk partitioning table (i.e. purely disklabel'd systems).
 114 .Pp
 115 Whether to write back or not should be specified at run-time in the nameblock
 116 so that the boot blocks need not be altered to get this feature.