Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1m/beadm.1m.man.txt
+++ new/usr/src/man/man1m/beadm.1m.man.txt
1 1 BEADM(1M) Maintenance Commands BEADM(1M)
2 2
3 3
4 4
5 5 NAME
6 6 beadm - utility for managing zfs boot environments
7 7
8 8 SYNOPSIS
9 9 beadm create [-a] [-d description]
10 10 [-e non-activeBeName | beName@snapshot]
11 11 [-o property=value] ... [-p zpool]
12 12 [-v] beName
13 13
14 14
15 15 beadm create [-v] beName@snapshot
16 16
17 17
18 18 beadm destroy [-fFsv] beName | beName@snapshot
19 19
20 20
21 21 beadm list [-a | -ds] [-H]
22 22 [-k|-K date | name | space] [-v] [beName]
23 23
24 24
25 25 beadm mount [-s ro|rw] [-v] beName mountpoint
26 26
27 27
28 28 beadm unmount [-fv] beName | mountpoint
29 29
30 30
31 31 beadm rename [-v] beName newBeName
32 32
33 33
34 34 beadm activate [-v] beName
35 35
36 36
37 37 beadm rollback [-v] beName snapshot
38 38
39 39
40 40 beadm rollback [-v] beName@snapshot
41 41
42 42
43 43 DESCRIPTION
44 44 The beadm command is the user interface for managing zfs Boot
45 45 Environments (BEs). This utility is intended to be used by System
46 46 Administrators who want to manage multiple Solaris Instances on a
47 47 single system.
48 48
49 49 The beadm command supports the following operations:
50 50
51 51 - Create a new BE, based on the active BE.
52 52
53 53 - Create a new BE, based on an inactive BE.
54 54
55 55 - Create a snapshot of an existing BE.
56 56
57 57 - Create a new BE, based on an existing snapshot.
58 58
59 59 - Create a new BE, and copy it to a different zpool.
60 60
61 61 - Activate an existing, inactive BE.
62 62
63 63 - Mount a BE.
64 64
65 65 - Unmount a BE.
66 66
67 67 - Destroy a BE.
68 68
69 69 - Destroy a snapshot of a BE.
70 70
71 71 - Rename an existing, inactive BE.
72 72
73 73 - Roll back a BE to an existing snapshot of a BE.
74 74
75 75 - Display information about your snapshots and datasets.
76 76
77 77
78 78 SUBCOMMANDS
79 79 The beadm command has the subcommands and options listed below. Also
80 80 see EXAMPLES below.
81 81
82 82 beadm
83 83
84 84 Displays command usage.
85 85
86 86
87 87 beadm create [-a] [-d description]
88 88 [-e non-activeBeName | beName@snapshot]
89 89 [-o property=value] ... [-p zpool]
90 90 [-v] beName
91 91
92 92
93 93 Creates a new boot environment named beName. If the -e option is
94 94 not provided, the new boot environment will be created as a clone
95 95 of the currently running boot environment. If the -d option is
96 96 provided then the description is also used as the title for the
97 97 BE's entry in the boot menu. If the -d option is not provided,
98 98 beName will be used as the title.
99 99
100 100 -a
101 101
102 102 Activate the newly created BE upon creation. The default is to
103 103 not activate the newly created BE.
104 104
105 105 -d description
106 106
107 107 Create a new BE with a description associated with it.
108 108
109 109 -e non-activeBeName
110 110
111 111 Create a new BE from an existing inactive BE.
112 112
113 113 -e beName@snapshot
114 114
115 115 Create a new BE from an existing snapshot of the BE named
116 116 beName.
117 117
118 118 -o property=value
119 119
120 120 Create the datasets for new BE with specific ZFS properties.
121 121 Multiple -o options can be specified. See zfs(1M) for more
122 122 information on the -o option.
123 123
124 124 -p zpool
125 125
126 126 Create the new BE in the specified zpool. If this is not
127 127 provided, the default behavior is to create the new BE in the
128 128 same pool as as the origin BE. This option is not supported in
129 129 non-global zone.
130 130
131 131 -v
132 132
133 133 Verbose mode. Displays verbose error messages from beadm.
134 134
135 135
136 136 beadm create [-v] beName@snapshot
137 137
138 138 Creates a snapshot of the existing BE named beName.
139 139
140 140 -v
141 141
142 142 Verbose mode. Displays verbose error messages from beadm.
143 143
144 144
145 145 beadm destroy [-fFsv] beName | beName@snapshot
146 146
147 147 Destroys the boot environment named beName or destroys an existing
148 148 snapshot of the boot environment named beName@snapshot. Destroying
149 149 a boot environment will also destroy all snapshots of that boot
150 150 environment. Use this command with caution.
151 151
152 152 -f
153 153
154 154 Forcefully unmount the boot environment if it is currently
155 155 mounted.
156 156
157 157 -F
158 158
159 159 Force the action without prompting to verify the destruction of
160 160 the boot environment.
161 161
162 162 -s
163 163
164 164 Destroy all snapshots of the boot environment.
165 165
166 166 -v
167 167
168 168 Verbose mode. Displays verbose error messages from beadm.
169 169
170 170
171 171 beadm list [-a | -ds] [-H]
172 172 [-k|-K date | name | space] [-v] [beName]
173 173
174 174 Lists information about the existing boot environment named beName,
175 175 or lists information for all boot environments if beName is not
176 176 provided. The 'Active' field indicates whether the boot
177 177 environment is active now, represented by 'N'; active on reboot,
178 178 represented by 'R'; or both, represented by 'NR'. In non-global
179 179 zone the 'Active' field also indicates whether the boot environment
180 180 has a non-active parent BE, represented by 'x'; is active on boot
181 181 in a non-active parent BE, represented by 'b'. Activate, rollback
182 182 and snapshot operations for boot environments from non-active
183 183 global parent BE aren't supported, destroy is allowed if these boot
184 184 environments aren't active on boot.
185 185
186 186 Each line in the machine parsable output has the boot environment
187 187 name as the first field. The 'Space' field is displayed in bytes
188 188 and the 'Created' field is displayed in UTC format. The -H option
189 189 used with no other options gives the boot environment's uuid in the
190 190 second field. This field will be blank if the boot environment
191 191 does not have a uuid. See the EXAMPLES section. In non-global
192 192 zones, this field shows the uuid of the parent BE.
193 193
194 194 -a
195 195
196 196 Lists all available information about the boot environment.
197 197 This includes subordinate file systems and snapshots.
198 198
199 199 -d
200 200
201 201 Lists information about all subordinate file systems belonging
202 202 to the boot environment.
203 203
204 204 -s
205 205
206 206 Lists information about the snapshots of the boot environment.
207 207
208 208 -H
209 209
210 210 Do not list header information. Each field in the list
211 211 information is separated by a semicolon.
212 212
213 213 -k date
214 214
215 215 Sort BEs by date of creation in ascending order. This is
216 216 default.
217 217
218 218 -k name
219 219
220 220 Lexical sort of BEs by name in ascending order.
221 221
222 222 -k space
223 223
224 224 Sort BEs by space in ascending order.
225 225
226 226 -K date | name | space
227 227
228 228 Same as the -k option, but sorts in descending order.
229 229
230 230 -v
231 231
232 232 Verbose mode. Displays verbose error messages from beadm.
233 233
234 234
235 235 beadm mount [-s ro|rw] [-v] beName mountpoint
236 236
237 237 Mounts a boot environment named beName at mountpoint. mountpoint
238 238 must be an already existing empty directory.
239 239
240 240 -s ro|rw
241 241
242 242 Mount the shared filesystems of the BE in read-only or read-
243 243 write mode.
244 244
245 245 -v
246 246
247 247 Verbose mode. Displays verbose error messages from beadm.
248 248
249 249
250 250 beadm unmount [-fv] beName | mountpoint
251 251
252 252 Unmounts the boot environment named beName. The command can also be
253 253 given a path to a beName mount point on the system.
254 254
255 255 -f
256 256
257 257 Forcefully unmount the boot environment even if its currently
258 258 busy.
259 259
260 260 -v
261 261
262 262 Verbose mode. Displays verbose error messages from beadm.
263 263
264 264
265 265 beadm rename [-v] beName newBeName
266 266
267 267 Renames the boot environment named beName to newBeName.
268 268
269 269 -v
270 270
271 271 Verbose mode. Displays verbose error messages from beadm.
272 272
273 273
274 274 beadm rollback [-v] beName snapshot | beName@snapshot
275 275
276 276 Roll back the boot environment named beName to existing snapshot of
277 277 the boot environment named beName@snapshot.
278 278
279 279 -v
280 280
281 281 Verbose mode. Displays verbose error messages from beadm.
282 282
283 283
284 284 beadm activate [-v] beName
285 285
286 286 Makes beName the active BE on next reboot.
287 287
288 288 -v
289 289
290 290 Verbose mode. Displays verbose error messages from beadm.
291 291
292 292
293 293 ALTERNATE BE LOCATION
294 294 The alternate BE location outside rpool/ROOT can be configured by
295 295 modifying the BENAME_STARTS_WITH parameter in /etc/default/be. For
296 296 example: BENAME_STARTS_WITH=rootfs
297 297
298 298
299 299 EXAMPLES
300 300 Example 1: Create a new BE named BE1, by cloning the current live BE.
301 301
302 302 # beadm create BE1
303 303
304 304
305 305
306 306 Example 2: Create a new BE named BE2, by cloning the existing inactive
307 307 BE named BE1.
308 308
309 309 # beadm create -e BE1 BE2
310 310
311 311
312 312
313 313 Example 3: Create a snapshot named now of the existing BE named BE1.
314 314
315 315 # beadm create BE1@now
316 316
317 317
318 318
319 319 Example 4: Create a new BE named BE3, by cloning an existing snapshot
320 320 of BE1.
321 321
322 322 # beadm create -e BE1@now BE3
323 323
324 324
325 325
326 326 Example 5: Create a new BE named BE4 based on the currently running BE.
327 327 Create the new BE in rpool2.
328 328
329 329 # beadm create -p rpool2 BE4
330 330
331 331
332 332
333 333 Example 6: Create a new BE named BE5 based on the currently running BE.
334 334 Create the new BE in rpool2, and create its datasets with compression
335 335 turned on.
336 336
337 337 # beadm create -p rpool2 -o compression=on BE5
338 338
339 339
340 340
341 341 Example 7: Create a new BE named BE6 based on the currently running BE
342 342 and provide a description for it.
343 343
344 344 # beadm create -d "BE6 used as test environment" BE6
345 345
346 346
347 347
348 348 Example 8: Activate an existing, inactive BE named BE3.
349 349
350 350 # beadm activate BE3
351 351
352 352
353 353
354 354 Example 9: Mount the BE named BE3 at /mnt.
355 355
356 356 # beadm mount BE3 /mnt
357 357
358 358
359 359
360 360 Example 10: Unmount the mounted BE named BE3.
361 361
362 362 # beadm unmount BE3
363 363
364 364
365 365
366 366 Example 11: Destroy the BE named BE3 without verification.
367 367
368 368 # beadm destroy -f BE3
369 369
370 370
371 371
372 372 Example 12: Destroy the snapshot named now of BE1.
373 373
374 374 # beadm destroy BE1@now
375 375
376 376
377 377
378 378 Example 13: Rename the existing, inactive BE named BE1 to BE3.
379 379
380 380 # beadm rename BE1 BE3
381 381
382 382
383 383
384 384 Example 14: Roll back the BE named BE1 to snapshot BE1@now.
385 385
386 386 # beadm rollback BE1 BE1@now
387 387
388 388
389 389
390 390 Example 15: List all existing boot environments.
391 391
392 392
393 393 # beadm list
394 394 BE Active Mountpoint Space Policy Created
395 395 -- ------ ---------- ----- ------ -------
396 396 BE2 - - 72.0K static 2008-05-21 12:26
397 397 BE3 - - 332.0K static 2008-08-26 10:28
398 398 BE4 - - 15.78M static 2008-09-05 18:20
399 399 BE5 NR / 7.25G static 2008-09-09 16:53
400 400
401 401
402 402
403 403 Example 16: List all existing boot environmets and list all dataset and
404 404 snapshot information about those bootenvironments.
405 405
406 406
407 407 # beadm list -d -s
408 408
409 409 BE/Dataset/Snapshot Active Mountpoint Space Policy Created
410 410 ------------------- ------ ---------- ----- ------ -------
411 411 BE2
412 412 p/ROOT/BE2 - - 36.0K static 2008-05-21 12:26
413 413 p/ROOT/BE2/opt - - 18.0K static 2008-05-21 16:26
414 414 p/ROOT/BE2/opt@now - - 0 static 2008-09-08 22:43
415 415 p/ROOT/BE2@now - - 0 static 2008-09-08 22:43
416 416 BE3
417 417 p/ROOT/BE3 - - 192.0K static 2008-08-26 10:28
418 418 p/ROOT/BE3/opt - - 86.0K static 2008-08-26 10:28
419 419 p/ROOT/BE3/opt/local - - 36.0K static 2008-08-28 10:58
420 420 BE4
421 421 p/ROOT/BE4 - - 15.78M static 2008-09-05 18:20
422 422 BE5
423 423 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53
424 424 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53
425 425 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59
426 426 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37
427 427 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59
428 428 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37
429 429
430 430
431 431 Example 17: List all dataset and snapshot information about BE5
432 432
433 433
434 434 # beadm list -a BE5
435 435
436 436 BE/Dataset/Snapshot Active Mountpoint Space Policy Created
437 437 ------------------- ------ ---------- ----- ------ -------
438 438 BE5
439 439 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53
440 440 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53
441 441 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59
442 442 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37
443 443 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59
444 444 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37
445 445
446 446
447 447
448 448 Example 18: List machine parsable information about all boot
449 449 environments.
450 450
451 451
452 452 # beadm list -H
453 453
454 454 BE2;;;;55296;static;1211397974
455 455 BE3;;;;339968;static;1219771706
456 456 BE4;;;;16541696;static;1220664051
457 457 BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384
458 458
459 459
460 460
461 461 EXIT STATUS
462 462 The following exit values are returned:
463 463
464 464 0
465 465
466 466 Successful completion
467 467
468 468
469 469 >0
470 470
471 471 Failure
472 472
473 473
474 474
475 475 FILES
476 476 /var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss>
477 477
478 478 Log used for capturing beadm create output
479 479
480 480 yyyymmdd_hhmmss - 20071130_140558
481 481 yy - year; 2007
482 482 mm - month; 11
483 483 dd - day; 30
484 484 hh - hour; 14
485 485 mm - minute; 05
486 486 ss - second; 58
487 487
488 488
489 489
490 490 /etc/default/be
491 491
492 492 Contains default value for BENAME_STARTS_WITH parameter
493 493
494 494
495 495
496 496 ATTRIBUTES
497 497 See attributes(5) for descriptions of the following attributes:
498 498
499 499
500 500
501 501
502 502 +--------------------+-----------------+
503 503 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
504 504 +--------------------+-----------------+
505 505 |Interface Stability | Uncommitted |
506 506 +--------------------+-----------------+
507 507
508 508
509 509 SEE ALSO
510 510 zfs(1M)
511 511
512 512
513 513
514 514 February 21, 2016 BEADM(1M)
|
↓ open down ↓ |
514 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX