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