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