| blob | 5276786d82e2ad7591b6df7216231ad780de7c68 |
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 2016 Toomas Soome <tsoome@me.com>
7 .TH BOOTADM 1M "Aug 18, 2016"
8 .SH NAME
9 bootadm \- manage bootability of the 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] [\fB-o\fR \fIkey\fR=\fIvalue\fR\fR]
39 .fi
41 .SH DESCRIPTION
42 .LP
43 The \fBbootadm\fR command manages the boot archive and, with x86 boot
44 environments, the boot loader 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 boot 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 boot menu and the
64 current boot menu entries. The location of the boot menu list is
65 \fB/<boot pool root dataset mountpoint>/boot/menu.lst\fR.
66 Use the \fBlist-menu\fR subcommand to
67 locate the boot 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, use
72 PROM variables to set boot behavior and are managed by the \fBeeprom\fR(1M)
73 command.
74 .sp
75 .LP
76 The \fBbootadm\fR command determines dynamically the options supported by the
77 image to be managed, so that \fBbootadm\fR invoked on one platform can be used
78 to manage diskless clients of a different platform type.
79 .SH SUBCOMMANDS
80 .LP
81 The \fBbootadm\fR command has the following subcommands:
82 .sp
83 .ne 2
84 .na
85 \fB\fBupdate-archive\fR\fR
86 .ad
87 .sp .6
88 .RS 4n
89 Updates current boot archive if required. Applies to both SPARC and x86
90 platforms.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fBlist-archive\fR\fR
97 .ad
98 .sp .6
99 .RS 4n
100 Lists the files and directories to be included in the boot archive. Applies to
101 both SPARC and x86 platforms.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fBinstall-bootloader\fR\fR
108 .ad
109 .sp .6
110 .RS 4n
111 Applies platform specific method to install the system boot loader to the disks
112 that are part of the selected ZFS pool (either specified with \fB-P\fR or
113 the default).
114 .sp
115 On SPARC, the boot loader is installed in the boot area of the disk partition
116 used by the ZFS pool.
117 .sp
118 On x86, disks are formatted using either \fBMBR Partitioning\fR (Master Boot
119 Record) or using \fBGPT Partitioning\fR (GUID Partition Tables). The first
120 sector on the disk that is used by the \fBBIOS\fR to find a boot loader
121 is referred to as the \fBMBR\fR (Master Boot Record) and is always used
122 regardless of the partition scheme.
123 .sp
124 On x86, disks in a ZFS pool may be a combination of either type of partitioning
125 scheme. If an entire disk was added to a ZFS pool (e.g. c0t0d0), then it was
126 formatted with \fBGPT\fR partitioning and the fact is recorded. The
127 \fBinstall-bootloader\fR subcommand will always update the system boot loader on
128 the disks. However, unless the entire disk was given a ZFS pool or the \fB-M\fR
129 option is specified, the \fBMBR\fR of the disk will not updated, as the system
130 cannot guarantee that the \fBMBR\fR belongs to it. If, for example, the system
131 was being dual booted, a different initial boot loader may be installed there.
132 .sp
133 To reinstall the boot loader on some or all of the disks, the \fB-f\fR option
134 must be passed to the \fBinstall-bootloader\fR subcommand to override boot
135 program version checks.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBset-menu\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 Maintain the menu configuration. The index of menu entries is listed in the
146 \fBmenu.lst\fR file, and the actual configuration of the menu entry is located
147 in the boot environment \fB/boot\fR directory.
148 Applies to x86 platforms only.
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBlist-menu\fR\fR
155 .ad
156 .sp .6
157 .RS 4n
158 Lists the location of the \fBmenu.lst\fR, as well as the current menu
159 entries. This listing includes the default entry, dataset name, and the
160 title of each entry. Applies to x86 platforms only.
161 .RE
163 .SH OPTIONS
164 .LP
165 The \fBbootadm\fR command has the following options:
166 .sp
167 .ne 2
168 .na
169 \fB\fB-f\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 In an \fBinstall-bootloader\fR operation, override the boot loader versioning
174 constraints.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fB-n\fR\fR
181 .ad
182 .sp .6
183 .RS 4n
184 In an \fBupdate-archive\fR operation, archive content is checked but not
185 updated.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fB-o\fR\fR \fIkey\fR=\fIvalue\fR
192 .ad
193 .sp .6
194 .RS 4n
195 In a \fBlist-menu\fR operation, specify the menu entry for detailed inspection.
196 Possible keys are \fBentry\fR and \fBtitle\fR, taking either entry number or
197 title name as values.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fB-p\fR \fIplatform\fR\fR
204 .ad
205 .sp .6
206 .RS 4n
207 The platform, or machine hardware class, of the client. The platform type can
208 only be specified together with \fB-R\fR, and is generally useful only for
209 managing a diskless client where the client is of a different platform class
210 than the server. Platform must be one of \fBi86pc\fR, \fBsun4u\fR, or
211 \fBsun4v\fR.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fB-v\fR\fR
218 .ad
219 .sp .6
220 .RS 4n
221 In an \fBupdate-archive\fR operation, stale files are displayed on stderr.
222 .sp
223 In an \fBinstall-bootloader\fR operation, display any output from tasks
224 performed.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fB-M\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 On x86 systems, in an \fBinstall-bootloader\fR operation, additionally installs
235 the system boot loader to the \fBMBR\fR (master boot record). For more
236 information, see the discussion of \fBinstall-bootloader\fR in the
237 \fBSUBCOMMANDS\fR section.
238 .sp
239 This option is not supported on non-x86 systems, and it is an error to specify
240 it.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB-P\fR\ \fIpool\fR
247 .ad
248 .sp .6
249 .RS 4n
250 In an \fBinstall-bootloader\fR operation, the boot loader is installed on
251 the disks in the ZFS pool \fIpool\fR. If the \fB-P\fR option is not specified,
252 then the boot loader is installed on the ZFS pool that the system booted from.
253 If the system did not boot from a ZFS pool then the \fB-P\fR option is required.
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fB-R\fR\ \fIaltroot\fR\fR
260 .ad
261 .sp .6
262 .RS 4n
263 Operation is applied to an alternate root path. In an \fBinstall-bootloader\fR
264 operation, the boot loader is still installed on the specified pool; however,
265 the boot loader itself will come from the alternate root.
266 .LP
267 Note -
268 .sp
269 .RS 2
270 The root file system of any non-global zones must not be referenced with the
271 \fB-R\fR option. Doing so might damage the global zone's file system, might
272 compromise the security of the global zone, and might damage the non-global
273 zone's file system. See \fBzones\fR(5).
274 .RE
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fIkey\fR=\fIvalue\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Possible values are:
285 .sp
286 .ne 2
287 .na
288 \fB\fBdefault=\fR\fIentrynum\fR\fR
289 .ad
290 .sp .6
291 .RS 4n
292 The item number (for example, 0, 1, or 2) in the boot menu designating the
293 operating system to boot when the timer expires.
294 .RE
296 .sp
297 .ne 2
298 .na
299 \fB\fBtimeout=\fR\fIseconds\fR\fR
300 .ad
301 .sp .6
302 .RS 4n
303 The number of seconds before the operating system designated by the default
304 item number is booted. If the value is -1, auto boot is disabled.
305 .RE
307 .RE
309 .SH EXAMPLES
310 .LP
311 \fBExample 1 \fRUpdating the Current Boot Archive
312 .sp
313 .LP
314 The following command updates the current boot archive:
316 .sp
317 .in +2
318 .nf
319 # bootadm update-archive
320 .fi
321 .in -2
323 .LP
324 \fBExample 2 \fRUpdating the Boot Archive on an Alternate Root
325 .sp
326 .LP
327 The following command updates the boot archive on an alternate root:
329 .sp
330 .in +2
331 .nf
332 # bootadm update-archive -R /a
333 .fi
334 .in -2
336 .LP
337 \fBExample 3 \fRListing Boot Menu Entries and Location of Boot Menu
338 .sp
339 .LP
340 The following command lists the boot environments and the location of the
341 \fBmenu.lst\fR:
343 .sp
344 .in +2
345 .nf
346 # bootadm list-menu
347 the location for the active menu is: /raid/boot/menu.lst
348 Index Default Dataset Menu
349 0 - raid/ROOT/test-182 test-182
350 1 - raid/ROOT/test-183 test-183
351 2 * raid/ROOT/test-184 test-184
352 .fi
353 .in -2
355 .LP
356 \fBExample 4 \fRSwitching Default Boot Entry
357 .sp
358 .LP
359 The following command refers to the menu displayed in the previous example. The
360 user selects test-183 (item 1).
362 .sp
363 .in +2
364 .nf
365 # bootadm set-menu default=1
366 .fi
367 .in -2
369 .LP
370 \fBExample 5 \fRDetailed information about menu entry.
371 .sp
372 .LP
373 The following command lists more detailed information about a boot menu entry:
375 .sp
376 .in +2
377 .nf
378 # bootadm list-menu -o entry=2
379 the location for the active menu is: /raid/boot/menu.lst
381 Title: test-184
382 Timeout: 10
383 Console: text
384 Bootfs: raid/ROOT/test-184
385 Kernel: /platform/i86pc/kernel/amd64/unix
386 Boot-args: "-v"
388 Modules:
389 Name: boot_archive
390 Path: /platform/i86pc/${ISADIR}/boot_archive
391 Type: rootfs
392 Status: Load
394 Name: boot_archive.hash
395 Path: /platform/i86pc/${ISADIR}/boot_archive.hash
396 Type: hash
397 Status: Load
399 Name: system
400 Path: /boot/modules/etc/system
401 Type: file
402 Hash: 4f4fe2d2dfae393a2a87ce29e3c71b803938c5fb
403 Flags: name=etc/system
404 Status: Load
406 .fi
407 .in -2
409 .SH EXIT STATUS
410 .LP
411 The following exit values are returned:
412 .sp
413 .ne 2
414 .na
415 \fB\fB0\fR\fR
416 .ad
417 .sp .6
418 .RS 4n
419 The command completed successfully.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fB1\fR\fR
426 .ad
427 .sp .6
428 .RS 4n
429 The command exited due to an error.
430 .RE
432 .SH ATTRIBUTES
433 .LP
434 See \fBattributes\fR(5) for descriptions of the following attributes:
435 .sp
437 .sp
438 .TS
439 box;
440 c | c
441 l | l .
442 ATTRIBUTE TYPE ATTRIBUTE VALUE
443 _
444 Interface Stability Committed
445 .TE
447 .SH SEE ALSO
448 .LP
449 \fBboot\fR(1M), \fBbeadm\fR(1M), \fBinstallboot\fR(1M), \fBattributes\fR(5)