| blob | 07c8383efd112345b3cf734f363eeb1c0530958e |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .\" Copyright (c) 2015 Toomas Soome <tsoome@me.com>
7 .TH BOOTADM 1M "Jul 26, 2015"
8 .SH NAME
9 bootadm \- manage bootability of GRUB-enabled operating system
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/sbin/bootadm\fR update-archive [\fB-vn\fR] [\fB-R\fR \fIaltroot\fR [\fB-p\fR \fIplatform\fR]]
14 .fi
16 .LP
17 .nf
18 \fB/sbin/bootadm\fR list-archive [\fB-vn\fR] [\fB-R\fR \fIaltroot\fR [\fB-p\fR \fIplatform\fR]]
19 .fi
21 .LP
22 .nf
23 \fB/sbin/bootadm\fR install-bootloader [\fB-Mfv\fR] [\fB-R\fR \fIaltroot\fR] [\fB-P\fR \fIpool\fR]
24 .fi
26 .LP
27 .nf
28 x86 only
29 .fi
31 .LP
32 .nf
33 \fB/sbin/bootadm\fR set-menu [\fB-R\fR \fIaltroot\fR] \fIkey\fR=\fIvalue\fR
34 .fi
36 .LP
37 .nf
38 \fB/sbin/bootadm\fR list-menu [\fB-R\fR \fIaltroot\fR]
39 .fi
41 .SH DESCRIPTION
42 .LP
43 The \fBbootadm\fR command manages the boot archive and, with x86 boot
44 environments, the GRUB (GRand Unified Bootloader) menu. The
45 \fBupdate-archive\fR option provides a way for user to update the boot archive
46 as a preventative measure or as part of a recovery procedure. The
47 \fBset-menu\fR subcommand allows you to switch the \fBauto-boot\fR timeout and
48 default boot entry in the GRUB menu.
49 .sp
50 .LP
51 The \fBinstall-bootloader\fR subcommand installs the system boot loader on a
52 ZFS pool. If ZFS pool was not specified with the \fB-P\fR option, then the boot
53 loader is installed on the ZFS pool that the system booted from. If the
54 system did not boot from a ZFS pool (for example, it booted an installer via PXE
55 or CD-ROM) then the \fB-P\fR option is required.
56 .sp
57 This subcommand can be used to install, update, and repair the boot loader on a
58 ZFS pool intended for booting. When disks in the ZFS pool used for booting the
59 system have been replaced, one should run \fBbootadm install-bootloader\fR to
60 ensure that all disks in that pool have the system boot loader installed.
61 .sp
62 .LP
63 The \fBlist-menu\fR subcommand displays the location of the GRUB menu and the
64 current GRUB menu entries. While the typical location of the GRUB menu is
65 \fB/boot/grub/menu.lst\fR, depending on the install method used the active GRUB
66 menu might be located somewhere else. Use the \fBlist-menu\fR subcommand to
67 locate the active GRUB menu. See the EXAMPLES section for typical output from
68 the \fBlist-menu\fR option.
69 .sp
70 .LP
71 Note that OpenBoot PROM (OBP)-based machines, such as SPARC systems, do not use
72 GRUB and have no boot menu manageable by \fBbootadm\fR.
73 .sp
74 .LP
75 The \fBbootadm\fR command determines dynamically the options supported by the
76 image to be managed, so that \fBbootadm\fR invoked on one platform can be used
77 to manage diskless clients of a different platform type.
78 .SH SUBCOMMANDS
79 .LP
80 The \fBbootadm\fR command has the following subcommands:
81 .sp
82 .ne 2
83 .na
84 \fB\fBupdate-archive\fR\fR
85 .ad
86 .sp .6
87 .RS 4n
88 Updates current boot archive if required. Applies to both SPARC and x86
89 platforms.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fBlist-archive\fR\fR
96 .ad
97 .sp .6
98 .RS 4n
99 Lists the files and directories to be included in the boot archive. Applies to
100 both SPARC and x86 platforms.
101 .RE
103 .sp
104 .ne 2
105 .na
106 \fB\fBinstall-bootloader\fR\fR
107 .ad
108 .sp .6
109 .RS 4n
110 Applies platform specific method to install the system boot loader to the disks
111 that are part of the selected ZFS pool (either specified with \fB-P\fR or
112 the default).
113 .sp
114 On SPARC, the boot loader is installed in the boot area of the disk partition
115 used by the ZFS pool.
116 .sp
117 On x86, disks are formatted using either \fBMBR Partitioning\fR (Master Boot
118 Record) or using \fBGPT Partitioning\fR (GUID Partition Tables). The first
119 sector on the disk that is used by the \fBBIOS\fR to find a boot loader
120 is referred to as the \fBMBR\fR (Master Boot Record) and is always used
121 regardless of the partition scheme.
122 .sp
123 On x86, disks in a ZFS pool may be a combination of either type of partitioning
124 scheme. If an entire disk was added to a ZFS pool (e.g. c0t0d0), then it was
125 formatted with \fBGPT\fR partitioning and the fact is recorded. The
126 \fBinstall-bootloader\fR subcommand will always update the system boot loader on
127 the disks. However, unless the entire disk was given a ZFS pool or the \fB-M\fR
128 option is specified, the \fBMBR\fR of the disk will not updated, as the system
129 cannot guarantee that the \fBMBR\fR belongs to it. If, for example, the system
130 was being dual booted, a different initial boot loader may be installed there.
131 .sp
132 When \fBGRUB\fR is being used as the system boot loader (currently on x86), to
133 reinstall the boot loader on some or all of the disks, the \fB-f\fR option must
134 be passed to the \fBinstall-bootloader\fR subcommand.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fBset-menu\fR\fR
141 .ad
142 .sp .6
143 .RS 4n
144 Maintain the GRUB menu. The current GRUB menu is \fBboot/grub/menu.lst\fR,
145 relative to root. Do not depend on this location, because it is subject to
146 change. Applies to x86 platforms only.
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fBlist-menu\fR\fR
153 .ad
154 .sp .6
155 .RS 4n
156 Lists the location of the active GRUB menu, as well as the current GRUB menu
157 entries. This includes the autoboot-timeout, the default entry number, and the
158 title of each entry. Applies to x86 platforms only.
159 .RE
161 .SH OPTIONS
162 .LP
163 The \fBbootadm\fR command has the following options:
164 .sp
165 .ne 2
166 .na
167 \fB\fB-f\fR\fR
168 .ad
169 .sp .6
170 .RS 4n
171 In an \fBinstall-bootloader\fR operation, override boot loader versioning
172 constraints.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fB-n\fR\fR
179 .ad
180 .sp .6
181 .RS 4n
182 In an \fBupdate-archive\fR operation, archive content is checked but not
183 updated.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-p\fR \fIplatform\fR\fR
190 .ad
191 .sp .6
192 .RS 4n
193 The platform, or machine hardware class, of the client. The platform type can
194 only be specified together with \fB-R\fR, and is generally useful only for
195 managing a diskless client where the client is of a different platform class
196 than the server. Platform must be one of \fBi86pc\fR, \fBsun4u\fR, or
197 \fBsun4v\fR.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fB-v\fR\fR
204 .ad
205 .sp .6
206 .RS 4n
207 In an \fBupdate-archive\fR operation, stale files are displayed on stderr.
208 .sp
209 In an \fBinstall-bootloader\fR operation, display any output from tasks
210 performed.
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fB-M\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 On x86 systems, in an \fBinstall-bootloader\fR operation, additionally installs
221 the system boot loader to the \fBMBR\fR (master boot record). For more
222 information, see the discussion of \fBinstall-bootloader\fR in the
223 \fBSUBCOMMANDS\fR section.
224 .sp
225 This option is not supported on non-x86 systems, and it is an error to specify
226 it.
227 .RE
229 .sp
230 .ne 2
231 .na
232 \fB-P\fR\ \fIpool\fR
233 .ad
234 .sp .6
235 .RS 4n
236 In an \fBinstall-bootloader\fR operation, the boot loader is installed on
237 the disks in the ZFS pool \fIpool\fR. If the \fB-P\fR option is not specified,
238 then the boot loader is installed on the ZFS pool that the system booted from.
239 If the system did not boot from a ZFS pool then the \fB-P\fR option is required.
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fB-R\fR\ \fIaltroot\fR\fR
246 .ad
247 .sp .6
248 .RS 4n
249 Operation is applied to an alternate root path. In an \fBinstall-bootloader\fR
250 operation, the boot loader is still installed on the specified pool; however,
251 the boot loader itself will come from the alternate root.
252 .LP
253 Note -
254 .sp
255 .RS 2
256 The root file system of any non-global zones must not be referenced with the
257 \fB-R\fR option. Doing so might damage the global zone's file system, might
258 compromise the security of the global zone, and might damage the non-global
259 zone's file system. See \fBzones\fR(5).
260 .RE
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fIkey\fR=\fIvalue\fR\fR
267 .ad
268 .sp .6
269 .RS 4n
270 Possible values are:
271 .sp
272 .ne 2
273 .na
274 \fB\fBdefault=\fR\fIentrynum\fR\fR
275 .ad
276 .sp .6
277 .RS 4n
278 The item number (for example, 0, 1, or 2) in the GRUB menu designating the
279 operating system to boot when the timer expires.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBtimeout=\fR\fIseconds\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 The number of seconds before the operating system designated by the default
290 item number is booted. If the value is -1, auto boot is disabled.
291 .RE
293 .RE
295 .SH EXAMPLES
296 .LP
297 \fBExample 1 \fRUpdating the Current Boot Archive
298 .sp
299 .LP
300 The following command updates the current boot archive:
302 .sp
303 .in +2
304 .nf
305 # bootadm update-archive
306 .fi
307 .in -2
309 .LP
310 \fBExample 2 \fRUpdating the Boot Archive on an Alternate Root
311 .sp
312 .LP
313 The following command updates the boot archive on an alternate root:
315 .sp
316 .in +2
317 .nf
318 # bootadm update-archive -R /a
319 .fi
320 .in -2
322 .LP
323 \fBExample 3 \fRListing Installed OS Instances
324 .sp
325 .LP
326 The following command lists the installed operating system instances in a GRUB
327 menu:
329 .sp
330 .in +2
331 .nf
332 # bootadm list-menu
334 default=0
335 timeout=10
336 (0) Solaris10
337 (1) Solaris10 Failsafe
338 (2) Linux
339 .fi
340 .in -2
342 .LP
343 \fBExample 4 \fRSwitching Default Boot Entry
344 .sp
345 .LP
346 The following command refers to the menu displayed in the previous example. The
347 user selects Linux (item 2).
349 .sp
350 .in +2
351 .nf
352 # bootadm set-menu default=2
353 .fi
354 .in -2
356 .LP
357 \fBExample 5 \fRListing GRUB Menu Entries and Location of GRUB Menu
358 .sp
359 .LP
360 The following command lists the GRUB menu entries and the location of the GRUB
361 menu:
363 .sp
364 .in +2
365 .nf
366 # bootadm list-menu
367 The location for the active GRUB menu is: /stubboot/boot/grub/menu.lst
368 default 0
369 timeout 10
370 0 Solaris10
371 1 Solaris10 failsafe
372 2 Linux
373 .fi
374 .in -2
376 .LP
377 \fBExample 6 \fRDisplaying Location of GRUB Menu
378 .sp
379 .LP
380 The following command displays the location of the GRUB menu:
382 .sp
383 .in +2
384 .nf
385 # bootadm list-menu
386 The location for the active GRUB menu is: /dev/dsk/c0t1d0s0 (not mounted)
387 The filesystem type of the menu device is <ufs>
388 default 2
389 timeout 10
390 0 c0t1d0s3
391 1 c0t1d0s3 failsafe
392 2 Solaris10
393 3 Solaris10 failsafe
394 .fi
395 .in -2
397 .sp
398 .LP
399 In this example, the active GRUB menu is located on a device which is \fBnot\fR
400 mounted. To access the GRUB menu, mount the device and access the GRUB menu at
401 \fB\fI<mountpoint>\fR/boot/grub/menu.lst\fR.
403 .SH EXIT STATUS
404 .LP
405 The following exit values are returned:
406 .sp
407 .ne 2
408 .na
409 \fB\fB0\fR\fR
410 .ad
411 .sp .6
412 .RS 4n
413 The command completed successfully.
414 .RE
416 .sp
417 .ne 2
418 .na
419 \fB\fB1\fR\fR
420 .ad
421 .sp .6
422 .RS 4n
423 The command exited due to an error.
424 .RE
426 .SH ATTRIBUTES
427 .LP
428 See \fBattributes\fR(5) for descriptions of the following attributes:
429 .sp
431 .sp
432 .TS
433 box;
434 c | c
435 l | l .
436 ATTRIBUTE TYPE ATTRIBUTE VALUE
437 _
438 Interface Stability Committed
439 .TE
441 .SH SEE ALSO
442 .LP
443 \fBboot\fR(1M), \fBbeadm\fR(1M), \fBinstallgrub\fR(1M), \fBinstallboot\fR(1M),
444 \fBattributes\fR(5)
445 .sp
446 .LP
447 Consult the GRUB home page, under:
448 .sp
449 .in +2
450 .nf
451 http://www.gnu.org/
452 .fi
453 .in -2