share/man/man8/installboot.8

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2018 Toomas Soome <tsoome@me.com>
  13 .\"
  14 .Dd July 20, 2018
  15 .Dt INSTALLBOOT 8
  16 .Os
  17 .Sh NAME
  18 .Nm installboot
  19 .Nd install bootloader in a disk partition
  20 .Sh SYNOPSIS
  21 .Ss SPARC
  22 .Nm
  23 .Op Fl fn
  24 .Op Fl F Sy zfs Ns | Ns Sy ufs Ns | Ns Sy hsfs
  25 .Op Fl u Ar verstr
  26 .Ar bootblk raw-device
  27 .Nm
  28 .Op Fl enV
  29 .Fl F Sy zfs
  30 .Fl i
  31 .Ar raw-device | Ar file
  32 .Nm
  33 .Op Fl n
  34 .Fl F Sy zfs
  35 .Fl M
  36 .Ar raw-device attach-raw-device
  37 .Ss x86
  38 .Nm
  39 .Op Fl fFmn
  40 .Op Fl u Ar verstr
  41 .Ar stage1 stage2 raw-device
  42 .Nm
  43 .Op Fl enV
  44 .Fl i
  45 .Ar raw-device | Ar file
  46 .Nm
  47 .Op Fl n
  48 .Fl M
  49 .Ar raw-device attach-raw-device
  50 .Sh DESCRIPTION
  51 The
  52 .Xr boot 8
  53 boot program is loaded from disk and is responsible of loading kernel and its
  54 support files from specific file system.
  55 .Pp
  56 The SPARC systems have one boot loader program file to be installed on the boot
  57 area of a disk slice.
  58 As the SPARC zfs boot loader is too large to fit into boot area at the start of
  59 the disk slice,
  60 .Nm
  61 command will split the zfs boot loader between disk slice boot area, and zfs
  62 pool boot area.
  63 .Pp
  64 The x86 systems have boot loader implemented as three stages:
  65 .Bl -tag -width Ds
  66 .It Sy stage1
  67 .Pa /boot/pmbr
  68 is used as master boot record
  69 .Pq MBR
  70 and partition boot program.
  71 .It Sy stage2
  72 .Pa /boot/gptzfsboot
  73 is responsible for loading files from file system.
  74 The
  75 .Sy stage2
  76 on x86 systems is always installed to zfs pool boot area, and therefore only zfs
  77 boot is supported.
  78 .Nm
  79 command will record the location of
  80 .Sy stage2
  81 to
  82 .Sy stage1 ,
  83 which is always installed at least on partition
  84 .Pq MBR or GPT
  85 boot area, making it possible to boot via chainload from other boot loaders.
  86 .Pp
  87 When
  88 .Nm
  89 command is used with the
  90 .Fl m
  91 option,
  92 .Nm
  93 installs the stage1 file on the master boot sector of the disk as well.
  94 .It Sy stage3
  95 .Pa /boot/loader
  96 is read from file system and executed by
  97 .Sy stage2
  98 and will provide boot loader user environment and is responsible of loading
  99 and starting the operating system kernel.
 100 .Pp
 101 In case of GPT partitioning scheme, if the file system to boot from is either
 102 UFS or PCFS, there must be
 103 .Sy boot
 104 partition defined to store stage2 boot program.
 105 This is needed because UFS and PCFS do not have sufficient space reserved to
 106 store boot programs.
 107 .Pp
 108 The boot partition must use following GPT UUID:
 109 .Bd -literal -offset indent
 110 6a82cb45-1dd2-11b2-99a6-080020736631
 111 .Ed
 112 .Pp
 113 which is provided by
 114 .Qq boot
 115 tag in
 116 .Xr format 8
 117 partition menu.
 118 .El
 119 .Ss Options
 120 The
 121 .Nm
 122 command accepts the following options:
 123 .Bl -tag -width Ds
 124 .It Fl h
 125 Prints short usage message.
 126 .It Fl m
 127 Installs
 128 .Sy stage1
 129 on the master boot sector interactively.
 130 You must use this option if OS is installed on an extended FDISK or an EFI/GPT
 131 partition.
 132 .It Fl f
 133 Suppresses interaction when overwriting the master boot sector on x86.
 134 Force update on SPARC.
 135 .It Fl n
 136 Dry run session.
 137 Will not write to disk.
 138 .It Fl F
 139 On SPARC, specify file system type.
 140 On x86, inhibit version check and enforce boot loader update.
 141 .It Fl u Ar verstr
 142 Specify custom version string.
 143 Can be used to add version on non-versioned boot loader or change built in
 144 version string.
 145 .It Fl i
 146 Print version string from installed boot loader or from indicated file.
 147 .It Fl e
 148 Print version string from installed boot loader without description.
 149 .It Fl V
 150 Print version string from installed boot loader with full description.
 151 .It Fl M
 152 Mirror boot loader from installed disk partition.
 153 .El
 154 .Ss Operands
 155 The
 156 .Nm
 157 command accepts the following operands:
 158 .Bl -tag -width Ds
 159 .It Ar bootblk
 160 The name of the SPARC boot loader code.
 161 .It Ar stage1
 162 The name of the loader stage 1 file.
 163 .It Ar stage2
 164 The name of the loader stage 2 file.
 165 .It Ar raw-device
 166 The name of the device onto which bootloader code is to be installed.
 167 It must be a character device that is readable and writable and part of boot
 168 pool.
 169 .El
 170 .Sh FILES
 171 .Bl -tag -width Ds
 172 .It Pa /boot
 173 Directory where x86 loader files reside.
 174 .It Pa /usr/platform/platform name/lib/fs
 175 Directory where SPARC boot loader files reside.
 176 .El
 177 .Sh EXAMPLES
 178 .Bl -tag -width Ds
 179 .It Sy Example 1 No Installing zfs boot loader on SPARC disk slice
 180 The following command installs zfs boot loader on SPARC system:
 181 .Bd -literal
 182 # installboot -F zfs /usr/platform/`uname -i`/lib/fs/zfs/bootblk \e
 183   /dev/rdsk/c0t0d0s0
 184 .Ed
 185 .It Sy Example 2 No Installing boot loader on x86 system
 186 The following command installs loader stage files and master boot record:
 187 .Bd -literal
 188 # installboot -m /boot/pmbr /boot/gptzfsboot /dev/rdsk/c0t0d0s0
 189 .Ed
 190 .El
 191 .Sh INTERFACE STABILITY
 192 .Sy Uncommitted
 193 .Sh SEE ALSO
 194 .Xr boot 8 ,
 195 .Xr bootadm 8 ,
 196 .Xr fdisk 8 ,
 197 .Xr fmthard 8 ,
 198 .Xr format 8 ,
 199 .Xr kernel 8 ,
 200 .Xr attributes 5
 201 .Sh WARNINGS
 202 Installing
 203 .Sy stage1
 204 on the master boot sector
 205 .Po
 206 .Fl m
 207 option
 208 .Pc
 209 overrides any boot loader currently installed on the machine.
 210 The system will always boot the current OS partition regardless of which fdisk
 211 partition is active.
 212 .Pp
 213 If version string indicates the source boot loader might be more recent,
 214 .Nm
 215 will also verify md5 checksums to determine if update is really necessary.
 216 If checksums match, the install will not be performed.