1 '\" te 2 .\" Copyright 2013 Nexenta Systems, Inc. All rights reserved. 3 .TH BEADM 1M "Nov 11, 2013" 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-s\fR \fBro\fR|\fBrw\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 This option is not supported in non-global zone. 243 .RE 244 .sp 245 .ne 2 246 .na 247 \fB-v\fR 248 .ad 249 .sp .6 250 .RS 4n 251 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 252 .RE 253 .RE 254 255 .sp 256 .ne 2 257 .na 258 \fBbeadm\fR \fBcreate\fR [\fB-v\fR] \fIbeName@snapshot\fR 259 .ad 260 .sp .6 261 .RS 4n 262 Creates a snapshot of the existing BE named beName. 263 .sp 264 .ne 2 265 .na 266 \fB-v\fR 267 .ad 268 .sp .6 269 .RS 4n 270 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 271 .RE 272 .RE 273 274 .sp 275 .ne 2 276 .na 277 \fBbeadm\fR \fBdestroy\fR [\fB-fFsv\fR] \fIbeName\fR | \fIbeName@snapshot\fR 278 .ad 279 .sp .6 280 .RS 4n 281 Destroys the boot environment named \fIbeName\fR or destroys an existing 282 snapshot of 283 the boot environment named \fIbeName@snapshot\fR. Destroying a 284 boot environment 285 will also destroy all snapshots of that boot environment. Use 286 this command 287 with caution. 288 .sp 289 .ne 2 290 .na 291 \fB-f\fR 292 .ad 293 .sp .6 294 .RS 4n 295 Forcefully unmount the boot environment if it is currently mounted. 296 .RE 297 .sp 298 .ne 2 299 .na 300 \fB-F\fR 301 .ad 302 .sp .6 303 .RS 4n 304 Force the action without prompting to verify the destruction of the boot 305 environment. 306 .RE 307 .sp 308 .ne 2 309 .na 310 \fB-s\fR 311 .ad 312 .sp .6 313 .RS 4n 314 Destroy all snapshots of the boot 315 environment. 316 .RE 317 .sp 318 .ne 2 319 .na 320 \fB-v\fR 321 .ad 322 .sp .6 323 .RS 4n 324 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 325 .RE 326 .RE 327 328 .sp 329 .ne 2 330 .na 331 \fBbeadm\fR \fBlist\fR [\fB-a\fR | \fB-ds\fR] [\fB-H\fR] [\fB-v\fR] [\fIbeName\fR] 332 .ad 333 .sp .6 334 .RS 4n 335 Lists information about the existing boot environment named \fIbeName\fR, or 336 lists 337 information for all boot environments if \fIbeName\fR is not provided. 338 The 'Active' 339 field indicates whether the boot environment is active now, 340 represented 341 by 'N'; active on reboot, represented by 'R'; or both, represented 342 by 'NR'. In non-global zone the 'Active' field also indicates whether the 343 boot environment has a non-active parent BE, represented by 'x'; is active 344 on boot in a non-active parent BE, represented by 'b'. Activate, rollback 345 and snapshot operations for boot environments from non-active global parent 346 BE aren't supported, destroy is allowed if these boot environments aren't 347 active on boot. 348 .sp 349 Each line in the machine parasable output has the boot environment name as the 350 first field. The 'Space' field is displayed in bytes and the 'Created' field 351 is displayed in UTC format. The \fB-H\fR option used with no other options 352 gives 353 the boot environment's uuid in the second field. This field will be 354 blank if 355 the boot environment does not have a uuid. See the EXAMPLES section. 356 In non-global zones, this field shows the uuid of the parent BE. 357 .sp 358 .ne 2 359 .na 360 \fB-a\fR 361 .ad 362 .sp .6 363 .RS 4n 364 Lists all available information about the boot environment. This includes 365 subordinate file systems and snapshots. 366 .RE 367 .sp 368 .ne 2 369 .na 370 \fB-d\fR 371 .ad 372 .sp .6 373 .RS 4n 374 Lists information about all subordinate file systems belonging to the boot 375 environment. 376 .RE 377 .sp 378 .ne 2 379 .na 380 \fB-s\fR 381 .ad 382 .sp .6 383 .RS 4n 384 Lists information about the snapshots of the boot environment. 385 .RE 386 .sp 387 .ne 2 388 .na 389 \fB-H\fR 390 .ad 391 .sp .6 392 .RS 4n 393 Do not list header information. Each field in the list information is 394 separated by a semicolon. 395 .RE 396 .sp 397 .ne 2 398 .na 399 \fB-v\fR 400 .ad 401 .sp .6 402 .RS 4n 403 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 404 .RE 405 .RE 406 407 .sp 408 .ne 2 409 .na 410 \fBbeadm\fR \fBmount\fR [\fB-s\fR \fBro\fR|\fBrw\fR] [\fB-v\fR] \fIbeName\fR \fImountpoint\fR 411 .ad 412 .sp .6 413 .RS 4n 414 Mounts a boot environment named beName at mountpoint. mountpoint must be an 415 already existing empty directory. 416 .sp 417 .ne 2 418 .na 419 \fB-s\fR \fBro\fR|\fBrw\fR 420 .ad 421 .sp .6 422 .RS 4n 423 Mount the shared filesystems of the BE in read-only or read-write mode. 424 .RE 425 .sp 426 .ne 2 427 .na 428 \fB-v\fR 429 .ad 430 .sp .6 431 .RS 4n 432 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 433 .RE 434 .RE 435 436 .sp 437 .ne 2 438 .na 439 \fBbeadm\fR \fBunmount\fR [\fB-fv\fR] \fIbeName\fR | \fImountpoint\fR 440 .ad 441 .sp .6 442 .RS 4n 443 Unmounts the boot environment named beName. The command can also be given a path to a 444 beName mount point on the system. 445 .sp 446 .ne 2 447 .na 448 \fB-f\fR 449 .ad 450 .sp .6 451 .RS 4n 452 Forcefully unmount the boot environment even if its currently busy. 453 .RE 454 .sp 455 .ne 2 456 .na 457 \fB-v\fR 458 .ad 459 .sp .6 460 .RS 4n 461 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 462 .RE 463 .RE 464 465 .sp 466 .ne 2 467 .na 468 \fBbeadm\fR \fBrename\fR [\fB-v\fR] \fIbeName\fR \fInewBeName\fR 469 .ad 470 .sp .6 471 .RS 4n 472 Renames the boot environment named \fIbeName\fR to \fInewBeName\fR. 473 .sp 474 .ne 2 475 .na 476 \fB-v\fR 477 .ad 478 .sp .6 479 .RS 4n 480 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 481 .RE 482 .RE 483 484 .sp 485 .ne 2 486 .na 487 \fBbeadm\fR \fBrollback\fR [\fB-v\fR] \fIbeName\fR \fIsnapshot\fR | \fIbeName@snapshot\fR 488 .ad 489 .sp .6 490 .RS 4n 491 Roll back the boot environment named \fIbeName\fR to existing snapshot 492 of the boot environment named \fIbeName@snapshot\fR. 493 .sp 494 .ne 2 495 .na 496 \fB-v\fR 497 .ad 498 .sp .6 499 .RS 4n 500 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 501 .RE 502 .RE 503 504 .sp 505 .ne 2 506 .na 507 \fBbeadm\fR \fBactivate\fR [\fB-v\fR] \fIbeName\fR 508 .ad 509 .sp .6 510 .RS 4n 511 Makes beName the active BE on next reboot. 512 .sp 513 .ne 2 514 .na 515 \fB-v\fR 516 .ad 517 .sp .6 518 .RS 4n 519 Verbose mode. Displays verbose error messages from \fBbeadm\fR. 520 .RE 521 .RE 522 523 .SH ALTERNATE BE LOCATION 524 .LP 525 The alternate BE location outside rpool/ROOT can be configured 526 by modifying the BENAME_STARTS_WITH parameter in /etc/default/be. 527 For example: BENAME_STARTS_WITH=rootfs 528 529 .SH EXAMPLES 530 .LP 531 \fBExample 1\fR: Create a new BE named BE1, by cloning the current live BE. 532 .sp 533 .in +2 534 .nf 535 \fB# beadm create BE1\fR 536 .fi 537 .in -2 538 .sp 539 540 .LP 541 \fBExample 2\fR: Create a new BE named BE2, by cloning the existing inactive 542 BE 543 named BE1. 544 .sp 545 .in +2 546 .nf 547 \fB# beadm create -e BE1 BE2\fR 548 .fi 549 .in -2 550 .sp 551 552 .LP 553 \fBExample 3\fR: Create a snapshot named now of the existing BE named BE1. 554 .sp 555 .in +2 556 .nf 557 \fB# beadm create BE1@now\fR 558 .fi 559 .in -2 560 .sp 561 562 .LP 563 \fBExample 4\fR: Create a new BE named BE3, by cloning an existing snapshot of 564 BE1. 565 .sp 566 .in +2 567 .nf 568 \fB# beadm create -e BE1@now BE3\fR 569 .fi 570 .in -2 571 .sp 572 573 .LP 574 \fBExample 5\fR: Create a new BE named BE4 based on the currently running BE. 575 Create the new BE in rpool2. 576 .sp 577 .in +2 578 .nf 579 \fB# beadm create -p rpool2 BE4\fR 580 .fi 581 .in -2 582 .sp 583 584 .LP 585 \fBExample 6\fR: Create a new BE named BE5 based on the currently running BE. 586 Create the new BE in rpool2, and create its datasets with compression turned 587 on. 588 .sp 589 .in +2 590 .nf 591 \fB# beadm create -p rpool2 -o compression=on BE5\fR 592 .fi 593 .in -2 594 .sp 595 596 .LP 597 \fBExample 7\fR: Create a new BE named BE6 based on the currently running BE 598 and provide a description for it. 599 .sp 600 .in +2 601 .nf 602 \fB# beadm create -d "BE6 used as test environment" BE6\fR 603 .fi 604 .in -2 605 .sp 606 607 .LP 608 \fBExample 8\fR: Activate an existing, inactive BE named BE3. 609 .sp 610 .in +2 611 .nf 612 \fB# beadm activate BE3\fR 613 .fi 614 .in -2 615 .sp 616 617 .LP 618 \fBExample 9\fR: Mount the BE named BE3 at /mnt. 619 .sp 620 .in +2 621 .nf 622 \fB# beadm mount BE3 /mnt\fR 623 .fi 624 .in -2 625 .sp 626 627 .LP 628 \fBExample 10\fR: Unmount the mounted BE named BE3. 629 .sp 630 .in +2 631 .nf 632 \fB# beadm unmount BE3\fR 633 .fi 634 .in -2 635 .sp 636 637 .LP 638 \fBExample 11\fR: Destroy the BE named BE3 without verification. 639 .sp 640 .in +2 641 .nf 642 \fB# beadm destroy -f BE3\fR 643 .fi 644 .in -2 645 .sp 646 647 .LP 648 \fBExample 12\fR: Destroy the snapshot named now of BE1. 649 .sp 650 .in +2 651 .nf 652 \fB# beadm destroy BE1@now\fR 653 .fi 654 .in -2 655 .sp 656 657 .LP 658 \fBExample 13\fR: Rename the existing, inactive BE named BE1 to BE3. 659 .sp 660 .in +2 661 .nf 662 \fB# beadm rename BE1 BE3\fR 663 .fi 664 .in -2 665 .sp 666 667 .LP 668 \fBExample 14\fR: Roll back the BE named BE1 to snapshot BE1@now. 669 .sp 670 .in +2 671 .nf 672 \fB# beadm rollback BE1 BE1@now\fR 673 .fi 674 .in -2 675 .sp 676 677 .LP 678 \fBExample 15\fR: List all existing boot environments. 679 680 .sp 681 .in +2 682 .nf 683 \fB# beadm list\fR 684 BE Active Mountpoint Space Policy Created 685 -- ------ ---------- ----- ------ ------- 686 BE2 - - 72.0K static 2008-05-21 12:26 687 BE3 - - 332.0K static 2008-08-26 10:28 688 BE4 - - 15.78M static 2008-09-05 18:20 689 BE5 NR / 7.25G static 2008-09-09 16:53 690 .fi 691 .in -2 692 .sp 693 694 .LP 695 \fBExample 16\fR: List all existing boot environmets and list all dataset and 696 snapshot information about those bootenvironments. 697 698 .sp 699 .in +2 700 .nf 701 \fB# beadm list -d -s\fR 702 703 BE/Dataset/Snapshot Active Mountpoint Space Policy Created 704 ------------------- ------ ---------- ----- ------ ------- 705 BE2 706 p/ROOT/BE2 - - 36.0K static 2008-05-21 12:26 707 p/ROOT/BE2/opt - - 18.0K static 2008-05-21 16:26 708 p/ROOT/BE2/opt@now - - 0 static 2008-09-08 22:43 709 p/ROOT/BE2@now - - 0 static 2008-09-08 22:43 710 BE3 711 p/ROOT/BE3 - - 192.0K static 2008-08-26 10:28 712 p/ROOT/BE3/opt - - 86.0K static 2008-08-26 10:28 713 p/ROOT/BE3/opt/local - - 36.0K static 2008-08-28 10:58 714 BE4 715 p/ROOT/BE4 - - 15.78M static 2008-09-05 18:20 716 BE5 717 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53 718 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53 719 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59 720 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37 721 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59 722 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37 723 .fi 724 .in -2 725 .sp 726 727 \fBExample 17\fR: List all dataset and snapshot information about BE5 728 729 .sp 730 .in +2 731 .nf 732 \fB# beadm list -a BE5\fR 733 734 BE/Dataset/Snapshot Active Mountpoint Space Policy Created 735 ------------------- ------ ---------- ----- ------ ------- 736 BE5 737 p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53 738 p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53 739 p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59 740 p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37 741 p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59 742 p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37 743 .fi 744 .in -2 745 .sp 746 747 .LP 748 \fBExample 18\fR: List machine parsable information about all boot 749 environments. 750 751 .sp 752 .in +2 753 .nf 754 \fB# beadm list -H\fR 755 756 BE2;;;;55296;static;1211397974 757 BE3;;;;339968;static;1219771706 758 BE4;;;;16541696;static;1220664051 759 BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384 760 .fi 761 .in -2 762 .sp 763 764 .SH EXIT STATUS 765 .sp 766 .LP 767 The following exit values are returned: 768 .sp 769 .ne 2 770 .na 771 \fB0\fR 772 .ad 773 .sp .6 774 .RS 4n 775 Successful completion 776 .RE 777 778 .sp 779 .ne 2 780 .na 781 \fB>0\fR 782 .ad 783 .sp .6 784 .RS 4n 785 Failure 786 .RE 787 788 789 .SH FILES 790 .sp 791 .LP 792 .sp 793 .ne 2 794 .na 795 \fB/var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss>\fR 796 .ad 797 .sp .6 798 .RS 4n 799 Log used for capturing beadm create output 800 .sp 801 .nf 802 \fIyyyymmdd_hhmmss\fR - 20071130_140558 803 \fIyy\fR - year; 2007 804 \fImm\fR - month; 11 805 \fIdd\fR - day; 30 806 \fIhh\fR - hour; 14 807 \fImm\fR - minute; 05 808 \fIss\fR - second; 58 809 .fi 810 .in -2 811 .sp 812 .RE 813 .sp 814 .LP 815 .sp 816 .ne 2 817 .na 818 \fB/etc/default/be\fR 819 .ad 820 .sp .6 821 .RS 4n 822 Contains default value for BENAME_STARTS_WITH parameter 823 .sp 824 .RE 825 826 .SH ATTRIBUTES 827 .sp 828 .LP 829 See \fBattributes\fR(5) for descriptions of the following attributes: 830 .sp 831 832 .sp 833 .TS 834 box; 835 c | c 836 l | l . 837 ATTRIBUTE TYPE ATTRIBUTE VALUE 838 _ 839 Interface Stability Uncommitted 840 .TE 841 842 843 .SH SEE ALSO 844 .sp 845 .LP 846 .BR zfs (1M)