1 '\" te 2 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. 3 .TH BEADM 1M "Feb 26, 2011" 4 .SH NAME 5 beadm \- utility for managing zfs boot environments 6 .SH SYNOPSIS 7 .LP 8 .nf 9 \fBbeadm\fR create [\fB-a\fR] [\fB-d\fR \fIdescription\fR] 10 [\fB-e\fR \fInon-activeBeName\fR | \fIbeName@snapshot\fR] 11 [\fB-o\fR \fIproperty=value\fR] ... [\fB-p\fR \fIzpool\FI] \fIbeName\fR 12 .fi 13 14 .LP 15 .nf 16 \fBbeadm\fR \fBcreate\fR \fIbeName@snapshot\fR 17 .fi 18 19 .LP 20 .nf 21 \fBbeadm\fR \fBdestroy\fR [\fB-fFs\fR] \fIbeName\fR | \fIbeName@snapshot\fR 22 .fi 23 24 .LP 25 .nf 26 \fBbeadm\fR \fBlist\fR [\fB-a\fR | \fB-ds\fR] [\fB-H\fR] [\fIbeName\fR] 27 .fi 28 29 .LP 30 .nf 31 \fBbeadm\fR \fBmount\fR \fIbeName\fR \fImountpoint\fR 32 .fi 33 34 .LP 35 .nf 36 \fBbeadm\fR \fBunmount\fR [\fB-f\fR] \fIbeName\fR | \fImountpoint\fR 37 .fi 38 39 .LP 40 .nf 41 \fBbeadm\fR \fBrename\fR \fIbeName\fR \fInewBeName\fR 42 .fi 43 44 .LP 45 .nf 46 \fBbeadm\fR \fBactivate\fR \fIbeName\fR 47 .fi 48 49 .LP 50 .nf 51 \fBbeadm\fR \fBrollback\fR \fIbeName\fR \fIsnapshot\fR 52 .fi 53 54 .LP 55 .nf 56 \fBbeadm\fR \fBrollback\fR \fIbeName@snapshot\fR 57 .fi 58 59 .SH DESCRIPTION 60 The \fBbeadm\fR command is the user interface for managing zfs Boot 61 Environments (BEs). This utility is intended to be used by System 62 Administrators who want to manage multiple Solaris Instances on a single 63 system. 64 .sp 65 The \fBbeadm\fR command supports the following operations: 66 .RS +4 67 .TP 68 .ie t \(bu 69 .el - 70 Create a new BE, based on the active BE. 71 .RE 72 .RS +4 73 .TP 74 .ie t \(bu 75 .el - 76 Create a new BE, based on an inactive BE. 77 .RE 78 .RS +4 79 .TP 80 .ie t \(bu 81 .el - 82 Create a snapshot of an existing BE. 83 .RE 84 .RS +4 85 .TP 86 .ie t \(bu 87 .el - 88 Create a new BE, based on an existing snapshot. 89 .RE 90 .RS +4 91 .TP 92 .ie t \(bu 93 .el - 94 Create a new BE, and copy it to a different zpool. 95 .RE 96 .RS +4 97 .TP 98 .ie t \(bu 99 .el - 100 Activate an existing, inactive BE. 101 .RE 102 .RS +4 103 .TP 104 .ie t \(bu 105 .el - 106 Mount a BE. 107 .RE 108 .RS +4 109 .TP 110 .ie t \(bu 111 .el - 112 Unmount a BE. 113 .RE 114 .RS +4 115 .TP 116 .ie t \(bu 117 .el - 118 Destroy a BE. 119 .RE 120 .RS +4 121 .TP 122 .ie t \(bu 123 .el - 124 Destroy a snapshot of a BE. 125 .RE 126 .RS +4 127 .TP 128 .ie t \(bu 129 .el - 130 Rename an existing, inactive BE. 131 .RE 132 .RS +4 133 .TP 134 .ie t \(bu 135 .el - 136 Roll back a BE to an existing snapshot of a BE. 137 .RE 138 .RS +4 139 .TP 140 .ie t \(bu 141 .el - 142 Display information about your snapshots and datasets. 143 .RE 144 145 .SH SUBCOMMANDS 146 The \fBbeadm\fR command has the subcommands and options listed 147 below. Also see 148 EXAMPLES below. 149 .sp 150 .ne 2 151 .na 152 \fBbeadm\fR 153 .ad 154 .sp .6 155 .RS 4n 156 Displays command usage. 157 .RE 158 159 .sp 160 .ne 2 161 .na 162 \fBbeadm\fR \fBcreate\fR [\fB-a\fR] [\fB-d\fR \fIdescription\fR] 163 [\fB-e\fR \fInon-activeBeName\fR | \fIbeName@snapshot\fR] 164 [\fB-o\fR 165 \fIproperty=value\fR] ... [\fB-p\fR \fIzpool\fR] \fIbeName\fR 166 167 .ad 168 .sp .6 169 .RS 4n 170 Creates a new boot environment named \fIbeName\fR. If the \fB-e\fR option is 171 not 172 provided, the new boot environment will be created as a clone of the 173 currently 174 running boot environment. If the \fB-d\fR option is provided then the 175 description is 176 also used as the title for the BE's entry in the GRUB menu for 177 x86 systems or 178 in the boot menu for SPARC systems. If the \fB-d\fR option is 179 not provided, \fIbeName\fR 180 will be used as the title. 181 .sp 182 .ne 2 183 .na 184 \fB-a\fR 185 .ad 186 .sp .6 187 .RS 4n 188 Activate the newly created BE upon creation. The default is to not activate 189 the newly created BE. 190 .RE 191 .sp 192 .ne 2 193 .na 194 \fB-d\fR \fIdescription\fR 195 .ad 196 .sp .6 197 .RS 4n 198 Create a new BE with a description associated with it. 199 .RE 200 .sp 201 .ne 2 202 .na 203 \fB-e\fR \fInon-activeBeName\fR 204 .ad 205 .sp .6 206 .RS 4n 207 Create a new BE from an existing inactive BE. 208 .RE 209 .sp 210 .ne 2 211 .na 212 \fB-e\fR \fIbeName@snapshot\fR 213 .ad 214 .sp .6 215 .RS 4n 216 Create a new BE from an existing snapshot of the BE named beName. 217 .RE 218 .sp 219 .ne 2 220 .na 221 \fB-o\fR \fIproperty=value\fR 222 .ad 223 .sp .6 224 .RS 4n 225 Create the datasets for new BE with specific ZFS properties. Multiple 226 \fB-o\fR 227 options can be specified. See \fBzfs\fR(1M) for more information on 228 the 229 \fB-o\fR option. 230 .RE 231 .sp 232 .ne 2 233 .na 234 \fB-p\fR \fIzpool\fR 235 .ad 236 .sp .6 237 .RS 4n 238 Create the new BE in the specified zpool. If this is not provided, the 239 default 240 behavior is to create the new BE in the same pool as as the origin BE. 241 .RE 242 .RE 243 244 .sp 245 .ne 2 246 .na 247 \fBbeadm\fR \fBcreate\fR \fIbeName@snapshot\fR 248 .ad 249 .sp .6 250 .RS 4n 251 Creates a snapshot of the existing BE named beName. 252 .RE 253 254 .sp 255 .ne 2 256 .na 257 \fBbeadm\fR \fBdestroy\fR [\fB-fFs\fR] \fIbeName\fR | \fIbeName@snapshot\fR 258 .ad 259 .sp .6 260 .RS 4n 261 Destroys the boot environment named \fIbeName\fR or destroys an existing 262 snapshot of 263 the boot environment named \fIbeName@snapshot\fR. Destroying a 264 boot environment 265 will also destroy all snapshots of that boot environment. Use 266 this command 267 with caution. 268 .sp 269 .ne 2 270 .na 271 \fB-f\fR 272 .ad 273 .sp .6 274 .RS 4n 275 Forcefully unmount the boot environment if it is currently mounted. 276 .RE 277 .sp 278 .ne 2 279 .na 280 \fB-F\fR 281 .ad 282 .sp .6 283 .RS 4n 284 Force the action without prompting to verify the destruction of the boot 285 environment. 286 .RE 287 .sp 288 .ne 2 289 .na 290 \fB-s\fR 291 .ad 292 .sp .6 293 .RS 4n 294 Destroy all snapshots of the boot 295 environment. 296 .RE 297 .RE 298 299 .sp 300 .ne 2 301 .na 302 \fBbeadm\fR \fBlist\fR [\fB-a\fR | \fB-ds\fR] [\fB-H\fR] [\fIbeName\fR] 303 .ad 304 .sp .6 305 .RS 4n 306 Lists information about the existing boot environment named \fIbeName\fR, or 307 lists 308 information for all boot environments if \fIbeName\fR is not provided. 309 The 'Active' 310 field indicates whether the boot environment is active now, 311 represented 312 by 'N'; active on reboot, represented by 'R'; or both, represented 313 by 'NR'. 314 .sp 315 Each line in the machine parasable output has the boot environment name as the 316 first field. The 'Space' field is displayed in bytes and the 'Created' field 317 is displayed in UTC format. The \fB-H\fR option used with no other options 318 gives 319 the boot environment's uuid in the second field. This field will be 320 blank if 321 the boot environment does not have a uuid. See the EXAMPLES section. 322 .sp 323 .ne 2 324 .na 325 \fB-a\fR 326 .ad 327 .sp .6 328 .RS 4n 329 Lists all available information about the boot environment. This includes 330 subordinate file systems and snapshots. 331 .RE 332 .sp 333 .ne 2 334 .na 335 \fB-d\fR 336 .ad 337 .sp .6 338 .RS 4n 339 Lists information about all subordinate file systems belonging to the boot 340 environment. 341 .RE 342 .sp 343 .ne 2 344 .na 345 \fB-s\fR 346 .ad 347 .sp .6 348 .RS 4n 349 Lists information about the snapshots of the boot environment. 350 .RE 351 .sp 352 .ne 2 353 .na 354 \fB-H\fR 355 .ad 356 .sp .6 357 .RS 4n 358 Do not list header information. Each field in the list information is 359 separated by a semicolon. 360 .RE 361 .RE 362 363 .sp 364 .ne 2 365 .na 366 \fBbeadm\fR \fBmount\fR \fIbeName\fR \fImountpoint\fR 367 .ad 368 .sp .6 369 .RS 4n 370 Mounts a boot environment named beName at mountpoint. mountpoint must be an 371 already existing empty directory. 372 .RE 373 374 .sp 375 .ne 2 376 .na 377 \fBbeadm\fR \fBunmount\fR [\fB-f\fR] \fIbeName\fR | \fImountpoint\fR 378 .ad 379 .sp .6 380 .RS 4n 381 Unmounts the boot environment named beName. The command can also be given a path to a 382 beName mount point on the system. 383 .sp 384 .ne 2 385 .na 386 \fB-f\fR 387 .ad 388 .sp .6 389 .RS 4n 390 Forcefully unmount the boot environment even if its currently busy. 391 .RE 392 .RE 393 394 .sp 395 .ne 2 396 .na 397 \fBbeadm\fR \fBrename\fR \fIbeName\fR \fInewBeName\fR 398 .ad 399 .sp .6 400 .RS 4n 401 Renames the boot environment named \fIbeName\fR to \fInewBeName\fR. 402 .RE 403 404 .sp 405 .ne 2 406 .na 407 \fBbeadm\fR \fBrollback\fR \fIbeName\fR \fIsnapshot\fR | \fIbeName@snapshot\fR 408 .ad 409 .sp .6 410 .RS 4n 411 Roll back the boot environment named \fIbeName\fR to existing snapshot 412 of the boot environment named \fIbeName@snapshot\fR. 413 .RE 414 415 .sp 416 .ne 2 417 .na 418 \fBbeadm\fR \fBactivate\fR \fIbeName\fR 419 .ad 420 .sp .6 421 .RS 4n 422 Makes beName the active BE on next reboot. 423 .RE 424 425 .SH ALTERNATE BE LOCATION 426 .LP 427 The alternate BE location outside rpool/ROOT can be configured 428 by modifying the BENAME_STARTS_WITH parameter in /etc/default/be. 429 For example: BENAME_STARTS_WITH=rootfs 430 431 .SH EXAMPLES 432 .LP 433 \fBExample 1\fR: Create a new BE named BE1, by cloning the current live BE. 434 .sp 435 .in +2 436 .nf 437 \fB# beadm create BE1\fR 438 .fi 439 .in -2 440 .sp 441 442 .LP 443 \fBExample 2\fR: Create a new BE named BE2, by cloning the existing inactive 444 BE 445 named BE1. 446 .sp 447 .in +2 448 .nf 449 \fB# beadm create -e BE1 BE2\fR 450 .fi 451 .in -2 452 .sp 453 454 .LP 455 \fBExample 3\fR: Create a snapshot named now of the existing BE named BE1. 456 .sp 457 .in +2 458 .nf 459 \fB# beadm create BE1@now\fR 460 .fi 461 .in -2 462 .sp 463 464 .LP 465 \fBExample 4\fR: Create a new BE named BE3, by cloning an existing snapshot of 466 BE1. 467 .sp 468 .in +2 469 .nf 470 \fB# beadm create -e BE1@now BE3\fR 471 .fi 472 .in -2 473 .sp 474 475 .LP 476 \fBExample 5\fR: Create a new BE named BE4 based on the currently running BE. 477 Create the new BE in rpool2. 478 .sp 479 .in +2 480 .nf 481 \fB# beadm create -p rpool2 BE4\fR 482 .fi 483 .in -2 484 .sp 485 486 .LP 487 \fBExample 6\fR: Create a new BE named BE5 based on the currently running BE. 488 Create the new BE in rpool2, and create its datasets with compression turned 489 on. 490 .sp 491 .in +2 492 .nf 493 \fB# beadm create -p rpool2 -o compression=on BE5\fR 494 .fi 495 .in -2 496 .sp 497 498 .LP 499 \fBExample 7\fR: Create a new BE named BE6 based on the currently running BE 500 and provide a description for it. 501 .sp 502 .in +2 503 .nf 504 \fB# beadm create -d "BE6 used as test environment" BE6\fR 505 .fi 506 .in -2 507 .sp 508 509 .LP 510 \fBExample 8\fR: Activate an existing, inactive BE named BE3. 511 .sp 512 .in +2 513 .nf 514 \fB# beadm activate BE3\fR 515 .fi 516 .in -2 517 .sp 518 519 .LP 520 \fBExample 9\fR: Mount the BE named BE3 at /mnt. 521 .sp 522 .in +2 523 .nf 524 \fB# beadm mount BE3 /mnt\fR 525 .fi 526 .in -2 527 .sp 528 529 .LP 530 \fBExample 10\fR: Unmount the mounted BE named BE3. 531 .sp 532 .in +2 533 .nf 534 \fB# beadm unmount BE3\fR 535 .fi 536 .in -2 537 .sp 538 539 .LP 540 \fBExample 11\fR: Destroy the BE named BE3 without verification. 541 .sp 542 .in +2 543 .nf 544 \fB# beadm destroy -f BE3\fR 545 .fi 546 .in -2 547 .sp 548 549 .LP 550 \fBExample 12\fR: Destroy the snapshot named now of BE1. 551 .sp 552 .in +2 553 .nf 554 \fB# beadm destroy BE1@now\fR 555 .fi 556 .in -2 557 .sp 558 559 .LP 560 \fBExample 13\fR: Rename the existing, inactive BE named BE1 to BE3. 561 .sp 562 .in +2 563 .nf 564 \fB# beadm rename BE1 BE3\fR 565 .fi 566 .in -2 567 .sp 568 569 .LP 570 \fBExample 14\fR: Roll back the BE named BE1 to snapshot BE1@now. 571 .sp 572 .in +2 573 .nf 574 \fB# beadm rollback BE1 BE1@now\fR 575 .fi 576 .in -2 577 .sp 578 579 .LP 580 \fBExample 15\fR: List all existing boot environments. 581 582 .sp 583 .in +2 584 .nf 585 \fB# beadm list\fR 586 BE Active Mountpoint Space Policy Created 587 -- ------ ---------- ----- ------ ------- 588 BE2 - - 72.0K static 2008-05-21 12:26 589 BE3 - - 332.0K static 2008-08-26 10:28 590 BE4 - - 15.78M static 2008-09-05 18:20 591 BE5 NR / 7.25G static 2008-09-09 16:53 592 .fi 593 .in -2 594 .sp 595 596 .LP 597 \fBExample 16\fR: List all existing boot environmets and list all dataset and 598 snapshot information about those bootenvironments. 599 600 .sp 601 .in +2 602 .nf 603 \fB# beadm list -d -s\fR 604 605 BE/Dataset/Snapshot Active Mountpoint Space Policy Created 606 ------------------- ------ ---------- ----- ------ ------- 607 BE2 608 p/ROOT/BE2 - - 36.0K static 2008-05-21 12:26 609 p/ROOT/BE2/opt - - 18.0K static 2008-05-21 16:26 610 p/ROOT/BE2/opt@now - - 0 static 2008-09-08 22:43 611 p/ROOT/BE2@now - - 0 static 2008-09-08 22:43 612 BE3 613 p/ROOT/BE3 - - 192.0K static 2008-08-26 10:28 614 p/ROOT/BE3/opt - - 86.0K static 2008-08-26 10:28 615 p/ROOT/BE3/opt/local - - 36.0K static 2008-08-28 10:58 616 BE4 617 p/ROOT/BE4 - - 15.78M static 2008-09-05 18:20 618 BE5 619 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53 620 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53 621 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59 622 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37 623 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59 624 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37 625 .fi 626 .in -2 627 .sp 628 629 \fBExample 17\fR: List all dataset and snapshot information about BE5 630 631 .sp 632 .in +2 633 .nf 634 \fB# beadm list -a BE5\fR 635 636 BE/Dataset/Snapshot Active Mountpoint Space Policy Created 637 ------------------- ------ ---------- ----- ------ ------- 638 BE5 639 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53 640 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53 641 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59 642 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37 643 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59 644 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37 645 .fi 646 .in -2 647 .sp 648 649 .LP 650 \fBExample 18\fR: List machine parsable information about all boot 651 environments. 652 653 .sp 654 .in +2 655 .nf 656 \fB# beadm list -H\fR 657 658 BE2;;;;55296;static;1211397974 659 BE3;;;;339968;static;1219771706 660 BE4;;;;16541696;static;1220664051 661 BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384 662 .fi 663 .in -2 664 .sp 665 666 .SH EXIT STATUS 667 .sp 668 .LP 669 The following exit values are returned: 670 .sp 671 .ne 2 672 .na 673 \fB0\fR 674 .ad 675 .sp .6 676 .RS 4n 677 Successful completion 678 .RE 679 680 .sp 681 .ne 2 682 .na 683 \fB>0\fR 684 .ad 685 .sp .6 686 .RS 4n 687 Failure 688 .RE 689 690 691 .SH FILES 692 .sp 693 .LP 694 .sp 695 .ne 2 696 .na 697 \fB/var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss>\fR 698 .ad 699 .sp .6 700 .RS 4n 701 Log used for capturing beadm create output 702 .sp 703 .nf 704 \fIyyyymmdd_hhmmss\fR - 20071130_140558 705 \fIyy\fR - year; 2007 706 \fImm\fR - month; 11 707 \fIdd\fR - day; 30 708 \fIhh\fR - hour; 14 709 \fImm\fR - minute; 05 710 \fIss\fR - second; 58 711 .fi 712 .in -2 713 .sp 714 .RE 715 .sp 716 .LP 717 .sp 718 .ne 2 719 .na 720 \fB/etc/default/be\fR 721 .ad 722 .sp .6 723 .RS 4n 724 Contains default value for BENAME_STARTS_WITH parameter 725 .sp 726 .RE 727 728 .SH ATTRIBUTES 729 .sp 730 .LP 731 See \fBattributes\fR(5) for descriptions of the following attributes: 732 .sp 733 734 .sp 735 .TS 736 box; 737 c | c 738 l | l . 739 ATTRIBUTE TYPE ATTRIBUTE VALUE 740 _ 741 Interface Stability Uncommitted 742 .TE 743 744 745 .SH SEE ALSO 746 .sp 747 .LP 748 .BR zfs (1M)