share/man/man1m/installboot.1m

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