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 2021 Toomas Soome <tsoome@me.com> 13.\" 14.Dd Oct 16, 2021 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 b Ar boot_dir 41.Op Fl u Ar verstr 42.Op Ar stage1 stage2 43raw-device 44.Nm 45.Op Fl enV 46.Fl i 47.Ar raw-device | Ar file 48.Nm 49.Op Fl n 50.Fl M 51.Ar raw-device attach-raw-device 52.Sh DESCRIPTION 53The 54.Xr boot 8 55boot program is loaded from disk and is responsible of loading kernel and its 56support files from specific file system. 57.Pp 58The SPARC systems have one boot loader program file to be installed on the boot 59area of a disk slice. 60As the SPARC zfs boot loader is too large to fit into boot area at the start of 61the disk slice, 62.Nm 63command will split the zfs boot loader between disk slice boot area, and zfs 64pool boot area. 65.Pp 66The x86 BIOS systems have boot loader implemented as three stages: 67.Bl -tag -width Ds 68.It Sy stage1 69.Pa /boot/pmbr 70is used as master boot record 71.Pq MBR 72and partition boot program. 73.It Sy stage2 74.Pa /boot/gptzfsboot 75is responsible for loading files from file system. 76The 77.Sy stage2 78on x86 systems is always installed to zfs pool boot area, and therefore only zfs 79boot is supported. 80.Nm 81command will record the location of 82.Sy stage2 83to 84.Sy stage1 , 85which is always installed at least on partition 86.Pq MBR or GPT 87boot area, making it possible to boot via chainload from other boot loaders. 88.Pp 89When 90.Nm 91command is used with the 92.Fl m 93option, 94.Nm 95installs the stage1 file on the master boot sector of the disk as well. 96.It Sy stage3 97.Pa /boot/loader 98is read from file system and executed by 99.Sy stage2 100and will provide boot loader user environment and is responsible of loading 101and starting the operating system kernel. 102.Pp 103In case of GPT partitioning scheme, if the file system to boot from is either 104UFS or PCFS, there must be 105.Sy boot 106partition defined to store stage2 boot program. 107This is needed because UFS and PCFS do not have sufficient space reserved to 108store boot programs. 109.Pp 110The boot partition must use following GPT UUID: 111.Bd -literal -offset indent 1126a82cb45-1dd2-11b2-99a6-080020736631 113.Ed 114.Pp 115which is provided by 116.Qq boot 117tag in 118.Xr format 8 119partition menu. 120.El 121.Pp 122The x86 UEFI systems load and start boot loader program from 123.Sy /EFI/Boot 124directory of the EFI System Partition (ESP). 125The boot loader program in ESP is named 126.Sy bootx64.efi 127for AMD64 system and 128.Sy bootia32.efi 129for i386 system. 130Note, only a 64-bit kernel is supported, even on i386 systems. 131The 132.Sy bootia32.efi 133boot program is only provided to support systems with 32-bit UEFI firmware, 134but which can support 64-bit mode. 135.Pp 136The 137.Sy bootx64.efi 138is copied from 139.Sy /boot/loader64.efi 140and 141.Sy bootia32.efi 142is copied from 143.Sy /boot/loader32.efi . 144.Ss Options 145The 146.Nm 147command accepts the following options: 148.Bl -tag -width Ds 149.It Fl b Ar boot_dir 150Provide path to the directory, where loader boot programs are located. 151.Nm 152will automatically pick the needed programs and will install to the 153specified disk device. 154.It Fl h 155Prints short usage message. 156.It Fl m 157Installs 158.Sy stage1 159on the master boot sector interactively. 160You must use this option if OS is installed on an extended FDISK or an EFI/GPT 161partition. 162.It Fl f 163Suppresses interaction when overwriting the master boot sector on x86. 164Force update on SPARC. 165.It Fl n 166Dry run session. 167Will not write to disk. 168.It Fl F 169On SPARC, specify file system type. 170On x86, inhibit version check and enforce boot loader update. 171.It Fl u Ar verstr 172Specify custom version string. 173Can be used to add version on non-versioned boot loader or change built in 174version string. 175.It Fl i 176Print version string from installed boot loader or from indicated file. 177.It Fl e 178Print version string from installed boot loader without description. 179.It Fl V 180Print version string from installed boot loader with full description. 181.It Fl M 182Mirror boot loader from installed disk partition. 183.El 184.Ss Operands 185The 186.Nm 187command accepts the following operands: 188.Bl -tag -width Ds 189.It Ar bootblk 190The name of the SPARC boot loader code. 191.It Ar stage1 192The name of the loader stage 1 file. 193.It Ar stage2 194The name of the loader stage 2 file. 195.It Ar raw-device 196The name of the device onto which bootloader code is to be installed. 197It must be a character device that is readable and writable and part of boot 198pool. 199.El 200.Sh FILES 201.Bl -tag -width Ds 202.It Pa /boot 203Directory where x86 loader files reside. 204.It Pa /usr/platform/platform name/lib/fs 205Directory where SPARC boot loader files reside. 206.El 207.Sh EXAMPLES 208.Bl -tag -width Ds 209.It Sy Example 1 No Installing zfs boot loader on SPARC disk slice 210The following command installs zfs boot loader on SPARC system: 211.Bd -literal 212# installboot -F zfs /usr/platform/`uname -i`/lib/fs/zfs/bootblk \e 213 /dev/rdsk/c0t0d0s0 214.Ed 215.It Sy Example 2 No Installing boot loader on x86 system 216The following command installs loader stage files and master boot record: 217.Bd -literal 218# installboot -m /boot/pmbr /boot/gptzfsboot /dev/rdsk/c0t0d0s0 219.Ed 220.El 221.Sh INTERFACE STABILITY 222.Sy Uncommitted 223.Sh SEE ALSO 224.Xr attributes 7 , 225.Xr boot 8 , 226.Xr bootadm 8 , 227.Xr fdisk 8 , 228.Xr fmthard 8 , 229.Xr format 8 , 230.Xr kernel 8 231.Sh WARNINGS 232Installing 233.Sy stage1 234on the master boot sector 235.Po 236.Fl m 237option 238.Pc 239overrides any boot loader currently installed on the machine. 240The system will always boot the current OS partition regardless of which fdisk 241partition is active. 242.Pp 243If version string indicates the source boot loader might be more recent, 244.Nm 245will also verify md5 checksums to determine if update is really necessary. 246If checksums match, the install will not be performed. 247