beadm: do not prompt for destroy
[unleashed.git] / share / man / man8 / beadm.8
blob53d4d901c2c0d34d80616153c66f435811ac5179
1 '\" te
2 .\" Copyright 2013 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 2016 Toomas Soome <tsoome@me.com>
4 .TH BEADM 8 "Feb 21, 2016"
5 .SH NAME
6 beadm \- utility for managing zfs boot environments
7 .SH SYNOPSIS
8 .LP
9 .nf
10 \fBbeadm\fR \fBcreate\fR [\fB-a\fR] [\fB-d\fR \fIdescription\fR]
11      [\fB-e\fR \fInon-activeBeName\fR | \fIbeName@snapshot\fR]
12      [\fB-o\fR \fIproperty=value\fR] ... [\fB-p\fR \fIzpool\fR]
13      [\fB-v\fR] \fIbeName\fR
14 .fi
16 .LP
17 .nf
18 \fBbeadm\fR \fBcreate\fR [\fB-v\fR] \fIbeName@snapshot\fR
19 .fi
21 .LP
22 .nf
23 \fBbeadm\fR \fBdestroy\fR [\fB-fsv\fR] \fIbeName\fR | \fIbeName@snapshot\fR
24 .fi
26 .LP
27 .nf
28 \fBbeadm\fR \fBlist\fR [\fB-a\fR | \fB-ds\fR] [\fB-H\fR]
29     [\fB-k\fR|\fB-K\fR \fBdate\fR | \fBname\fR | \fBspace\fR] [\fB-v\fR] [\fIbeName\fR]
30 .fi
32 .LP
33 .nf
34 \fBbeadm\fR \fBmount\fR [\fB-s\fR \fBro\fR|\fBrw\fR] [\fB-v\fR] \fIbeName\fR \fImountpoint\fR
35 .fi
37 .LP
38 .nf
39 \fBbeadm\fR \fBunmount\fR [\fB-fv\fR] \fIbeName\fR | \fImountpoint\fR
40 .fi
42 .LP
43 .nf
44 \fBbeadm\fR \fBrename\fR [\fB-v\fR] \fIbeName\fR \fInewBeName\fR
45 .fi
47 .LP
48 .nf
49 \fBbeadm\fR \fBactivate\fR [\fB-v\fR] \fIbeName\fR
50 .fi
52 .LP
53 .nf
54 \fBbeadm\fR \fBrollback\fR [\fB-v\fR] \fIbeName\fR \fIsnapshot\fR
55 .fi
57 .LP
58 .nf
59 \fBbeadm\fR \fBrollback\fR [\fB-v\fR] \fIbeName@snapshot\fR
60 .fi
62 .SH DESCRIPTION
63 The \fBbeadm\fR command is the user interface for managing zfs Boot
64 Environments (BEs). This utility is intended to be used by System
65 Administrators who want to manage multiple Solaris Instances on a single
66 system.
67 .sp
68 The \fBbeadm\fR command supports the following operations:
69 .RS +4
70 .TP
71 .ie t \(bu
72 .el -
73 Create a new BE, based on the active BE.
74 .RE
75 .RS +4
76 .TP
77 .ie t \(bu
78 .el -
79 Create a new BE, based on an inactive BE.
80 .RE
81 .RS +4
82 .TP
83 .ie t \(bu
84 .el -
85 Create a snapshot of an existing BE.
86 .RE
87 .RS +4
88 .TP
89 .ie t \(bu
90 .el -
91 Create a new BE, based on an existing snapshot.
92 .RE
93 .RS +4
94 .TP
95 .ie t \(bu
96 .el -
97 Create a new BE, and copy it to a different zpool.
98 .RE
99 .RS +4
101 .ie t \(bu
102 .el -
103 Activate an existing, inactive BE.
105 .RS +4
107 .ie t \(bu
108 .el -
109 Mount a BE.
111 .RS +4
113 .ie t \(bu
114 .el -
115 Unmount a BE.
117 .RS +4
119 .ie t \(bu
120 .el -
121 Destroy a BE.
123 .RS +4
125 .ie t \(bu
126 .el -
127 Destroy a snapshot of a BE.
129 .RS +4
131 .ie t \(bu
132 .el -
133 Rename an existing, inactive BE.
135 .RS +4
137 .ie t \(bu
138 .el -
139 Roll back a BE to an existing snapshot of a BE.
141 .RS +4
143 .ie t \(bu
144 .el -
145 Display information about your snapshots and datasets.
148 .SH SUBCOMMANDS
149 The \fBbeadm\fR command has the subcommands and options listed
150 below. Also see
151 EXAMPLES below.
153 .ne 2
155 \fBbeadm\fR
157 .sp .6
158 .RS 4n
159 Displays command usage.
163 .ne 2
165 \fBbeadm\fR \fBcreate\fR [\fB-a\fR] [\fB-d\fR \fIdescription\fR]
166      [\fB-e\fR \fInon-activeBeName\fR | \fIbeName@snapshot\fR]
167      [\fB-o\fR \fIproperty=value\fR] ... [\fB-p\fR \fIzpool\fR]
168      [\fB-v\fR] \fIbeName\fR
171 .sp .6
172 .RS 4n
173 Creates a new boot environment named \fIbeName\fR.  If the \fB-e\fR option is
175 provided, the new boot environment will be created as a clone of the
176 currently
177 running boot environment. If the \fB-d\fR option is provided then the
178 description is
179 also used as the title for the BE's entry in the boot menu. If the \fB-d\fR
180 option is not provided, \fIbeName\fR will be used as the title.
182 .ne 2
184 \fB-a\fR
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.
192 .ne 2
194 \fB-d\fR \fIdescription\fR
196 .sp .6
197 .RS 4n
198 Create a new BE with a description associated with it.
201 .ne 2
203 \fB-e\fR \fInon-activeBeName\fR
205 .sp .6
206 .RS 4n
207 Create a new BE from an existing inactive BE.
210 .ne 2
212 \fB-e\fR \fIbeName@snapshot\fR
214 .sp .6
215 .RS 4n
216 Create a new BE from an existing snapshot of the BE named beName.
219 .ne 2
221 \fB-o\fR \fIproperty=value\fR
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(8) for more information on
229 \fB-o\fR option.
232 .ne 2
234 \fB-p\fR \fIzpool\fR
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 This option is not supported in non-global zone.
244 .ne 2
246 \fB-v\fR
248 .sp .6
249 .RS 4n
250 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
255 .ne 2
257 \fBbeadm\fR \fBcreate\fR [\fB-v\fR] \fIbeName@snapshot\fR
259 .sp .6
260 .RS 4n
261 Creates a snapshot of the existing BE named beName.
263 .ne 2
265 \fB-v\fR
267 .sp .6
268 .RS 4n
269 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
274 .ne 2
276 \fBbeadm\fR \fBdestroy\fR [\fB-fsv\fR] \fIbeName\fR | \fIbeName@snapshot\fR
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.
288 .ne 2
290 \fB-f\fR
292 .sp .6
293 .RS 4n
294 Forcefully unmount the boot environment if it is currently mounted.
297 .ne 2
299 \fB-s\fR
301 .sp .6
302 .RS 4n
303 Destroy all snapshots of the boot
304 environment.
307 .ne 2
309 \fB-v\fR
311 .sp .6
312 .RS 4n
313 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
318 .ne 2
320 \fBbeadm\fR \fBlist\fR [\fB-a\fR | \fB-ds\fR] [\fB-H\fR]
321     [\fB-k\fR|\fB-K\fR \fBdate\fR | \fBname\fR | \fBspace\fR] [\fB-v\fR] [\fIbeName\fR]
323 .sp .6
324 .RS 4n
325 Lists information about the existing boot environment named \fIbeName\fR, or
326 lists
327 information for all boot environments if \fIbeName\fR is not provided.
328 The 'Active'
329 field indicates whether the boot environment is active now,
330 represented
331 by 'N'; active on reboot, represented by 'R'; or both, represented
332 by 'NR'. In non-global zone the 'Active' field also indicates whether the
333 boot environment has a non-active parent BE, represented by 'x'; is active
334 on boot in a non-active parent BE, represented by 'b'. Activate, rollback
335 and snapshot operations for boot environments from non-active global parent
336 BE aren't supported, destroy is allowed if these boot environments aren't
337 active on boot.
339 Each line in the machine parsable output has the boot environment name as the
340 first field.  The 'Space' field is displayed in bytes and the 'Created' field
341 is displayed in UTC format.  The \fB-H\fR option used with no other options
342 gives
343 the boot environment's uuid in the second field.  This field will be
344 blank if
345 the boot environment does not have a uuid. See the EXAMPLES section.
346 In non-global zones, this field shows the uuid of the parent BE.
348 .ne 2
350 \fB-a\fR
352 .sp .6
353 .RS 4n
354 Lists all available information about the boot environment.  This includes
355 subordinate file systems and snapshots.
358 .ne 2
360 \fB-d\fR
362 .sp .6
363 .RS 4n
364 Lists information about all subordinate file systems belonging to the boot
365 environment.
368 .ne 2
370 \fB-s\fR
372 .sp .6
373 .RS 4n
374 Lists information about the snapshots of the boot environment.
377 .ne 2
379 \fB-H\fR
381 .sp .6
382 .RS 4n
383 Do not list header information.  Each field in the list information is
384 separated by a semicolon.
387 .ne 2
389 \fB-k\fR \fBdate\fR
391 .sp .6
392 .RS 4n
393 Sort BEs by date of creation in ascending order. This is default.
396 .ne 2
398 \fB-k\fR \fBname\fR
400 .sp .6
401 .RS 4n
402 Lexical sort of BEs by name in ascending order.
405 .ne 2
407 \fB-k\fR \fBspace\fR
409 .sp .6
410 .RS 4n
411 Sort BEs by space in ascending order.
414 .ne 2
416 \fB-K date\fR | \fBname\fR | \fBspace\fR
418 .sp .6
419 .RS 4n
420 Same as the \fB-k\fR option, but sorts in descending order.
423 .ne 2
425 \fB-v\fR
427 .sp .6
428 .RS 4n
429 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
434 .ne 2
436 \fBbeadm\fR \fBmount\fR [\fB-s\fR \fBro\fR|\fBrw\fR] [\fB-v\fR] \fIbeName\fR \fImountpoint\fR
438 .sp .6
439 .RS 4n
440 Mounts a boot environment named beName at mountpoint.  mountpoint must be an
441 already existing empty directory.
443 .ne 2
445 \fB-s\fR \fBro\fR|\fBrw\fR
447 .sp .6
448 .RS 4n
449 Mount the shared filesystems of the BE in read-only or read-write mode.
452 .ne 2
454 \fB-v\fR
456 .sp .6
457 .RS 4n
458 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
463 .ne 2
465 \fBbeadm\fR \fBunmount\fR [\fB-fv\fR] \fIbeName\fR | \fImountpoint\fR
467 .sp .6
468 .RS 4n
469 Unmounts the boot environment named beName. The command can also be given a path to a
470 beName mount point on the system.
472 .ne 2
474 \fB-f\fR
476 .sp .6
477 .RS 4n
478 Forcefully unmount the boot environment even if its currently busy.
481 .ne 2
483 \fB-v\fR
485 .sp .6
486 .RS 4n
487 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
492 .ne 2
494 \fBbeadm\fR \fBrename\fR [\fB-v\fR] \fIbeName\fR \fInewBeName\fR
496 .sp .6
497 .RS 4n
498 Renames the boot environment named \fIbeName\fR to \fInewBeName\fR.
500 .ne 2
502 \fB-v\fR
504 .sp .6
505 .RS 4n
506 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
511 .ne 2
513 \fBbeadm\fR \fBrollback\fR [\fB-v\fR] \fIbeName\fR \fIsnapshot\fR | \fIbeName@snapshot\fR
515 .sp .6
516 .RS 4n
517 Roll back the boot environment named \fIbeName\fR to existing snapshot
518 of the boot environment named \fIbeName@snapshot\fR.
520 .ne 2
522 \fB-v\fR
524 .sp .6
525 .RS 4n
526 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
531 .ne 2
533 \fBbeadm\fR \fBactivate\fR [\fB-v\fR] \fIbeName\fR
535 .sp .6
536 .RS 4n
537 Makes beName the active BE on next reboot.
539 .ne 2
541 \fB-v\fR
543 .sp .6
544 .RS 4n
545 Verbose mode. Displays verbose error messages from \fBbeadm\fR.
549 .SH ALTERNATE BE LOCATION
551 The alternate BE location outside rpool/ROOT can be configured
552 by modifying the BENAME_STARTS_WITH parameter in /etc/default/be.
553 For example: BENAME_STARTS_WITH=rootfs
555 .SH EXAMPLES
557 \fBExample 1\fR: Create a new BE named BE1, by cloning the current live BE.
559 .in +2
561 \fB# beadm create BE1\fR
563 .in -2
567 \fBExample 2\fR: Create a new BE named BE2, by cloning the existing inactive
569 named BE1.
571 .in +2
573 \fB# beadm create -e BE1 BE2\fR
575 .in -2
579 \fBExample 3\fR: Create a snapshot named now of the existing BE named BE1.
581 .in +2
583 \fB# beadm create BE1@now\fR
585 .in -2
589 \fBExample 4\fR: Create a new BE named BE3, by cloning an existing snapshot of
590 BE1.
592 .in +2
594 \fB# beadm create -e BE1@now BE3\fR
596 .in -2
600 \fBExample 5\fR: Create a new BE named BE4 based on the currently running BE.
601 Create the new BE in rpool2.
603 .in +2
605 \fB# beadm create -p rpool2 BE4\fR
607 .in -2
611 \fBExample 6\fR: Create a new BE named BE5 based on the currently running BE.
612 Create the new BE in rpool2, and create its datasets with compression turned
615 .in +2
617 \fB# beadm create -p rpool2 -o compression=on BE5\fR
619 .in -2
623 \fBExample 7\fR: Create a new BE named BE6 based on the currently running BE
624 and provide a description for it.
626 .in +2
628 \fB# beadm create -d "BE6 used as test environment" BE6\fR
630 .in -2
634 \fBExample 8\fR: Activate an existing, inactive BE named BE3.
636 .in +2
638 \fB# beadm activate BE3\fR
640 .in -2
644 \fBExample 9\fR: Mount the BE named BE3 at /mnt.
646 .in +2
648 \fB# beadm mount BE3 /mnt\fR
650 .in -2
654 \fBExample 10\fR: Unmount the mounted BE named BE3.
656 .in +2
658 \fB# beadm unmount BE3\fR
660 .in -2
664 \fBExample 11\fR: Destroy the BE named BE3 without verification.
666 .in +2
668 \fB# beadm destroy -f BE3\fR
670 .in -2
674 \fBExample 12\fR: Destroy the snapshot named now of BE1.
676 .in +2
678 \fB# beadm destroy BE1@now\fR
680 .in -2
684 \fBExample 13\fR: Rename the existing, inactive BE named BE1 to BE3.
686 .in +2
688 \fB# beadm rename BE1 BE3\fR
690 .in -2
694 \fBExample 14\fR: Roll back the BE named BE1 to snapshot BE1@now.
696 .in +2
698 \fB# beadm rollback BE1 BE1@now\fR
700 .in -2
704 \fBExample 15\fR: List all existing boot environments.
707 .in +2
709 \fB# beadm list\fR
710 BE  Active Mountpoint Space  Policy Created
711 --  ------ ---------- -----  ------ -------
712 BE2 -      -          72.0K  static 2008-05-21 12:26
713 BE3 -      -          332.0K static 2008-08-26 10:28
714 BE4 -      -          15.78M static 2008-09-05 18:20
715 BE5 NR     /          7.25G  static 2008-09-09 16:53
717 .in -2
721 \fBExample 16\fR: List all existing boot environmets and list all dataset and
722 snapshot information about those bootenvironments.
725 .in +2
727 \fB# beadm list -d -s\fR
729 BE/Dataset/Snapshot     Active Mountpoint Space   Policy Created
730 -------------------     ------ ---------- -----   ------ -------
732    p/ROOT/BE2           -      -          36.0K   static 2008-05-21 12:26
733    p/ROOT/BE2/opt       -      -          18.0K   static 2008-05-21 16:26
734    p/ROOT/BE2/opt@now   -      -          0       static 2008-09-08 22:43
735    p/ROOT/BE2@now       -      -          0       static 2008-09-08 22:43
737    p/ROOT/BE3           -      -          192.0K  static 2008-08-26 10:28
738    p/ROOT/BE3/opt       -      -          86.0K   static 2008-08-26 10:28
739    p/ROOT/BE3/opt/local -      -          36.0K   static 2008-08-28 10:58
741    p/ROOT/BE4           -      -          15.78M  static 2008-09-05 18:20
743    p/ROOT/BE5           NR     /          6.10G   static 2008-09-09 16:53
744    p/ROOT/BE5/opt       -      /opt       24.55M  static 2008-09-09 16:53
745    p/ROOT/BE5/opt@bar   -      -          18.38M  static 2008-09-10 00:59
746    p/ROOT/BE5/opt@foo   -      -          18.38M  static 2008-06-10 16:37
747    p/ROOT/BE5@bar       -      -          139.44M static 2008-09-10 00:59
748    p/ROOT/BE5@foo       -      -          912.85M static 2008-06-10 16:37
750 .in -2
753 \fBExample 17\fR: List all dataset and snapshot information about BE5
756 .in +2
758 \fB# beadm list -a BE5\fR
760 BE/Dataset/Snapshot   Active Mountpoint Space   Policy Created
761 -------------------   ------ ---------- -----   ------ -------
763    p/ROOT/BE5         NR     /          6.10G   static 2008-09-09 16:53
764    p/ROOT/BE5/opt     -      /opt       24.55M  static 2008-09-09 16:53
765    p/ROOT/BE5/opt@bar -      -          18.38M  static 2008-09-10 00:59
766    p/ROOT/BE5/opt@foo -      -          18.38M  static 2008-06-10 16:37
767    p/ROOT/BE5@bar     -      -          139.44M static 2008-09-10 00:59
768    p/ROOT/BE5@foo     -      -          912.85M static 2008-06-10 16:37
770 .in -2
774 \fBExample 18\fR: List machine parsable information about all boot
775 environments.
778 .in +2
780 \fB# beadm list -H\fR
782 BE2;;;;55296;static;1211397974
783 BE3;;;;339968;static;1219771706
784 BE4;;;;16541696;static;1220664051
785 BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384
787 .in -2
790 .SH EXIT STATUS
792 The following exit values are returned:
794 .ne 2
796 \fB0\fR
798 .sp .6
799 .RS 4n
800 Successful completion
804 .ne 2
806 \fB>0\fR
808 .sp .6
809 .RS 4n
810 Failure
814 .SH FILES
817 .ne 2
819 \fB/var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss>\fR
821 .sp .6
822 .RS 4n
823 Log used for capturing beadm create output
826 \fIyyyymmdd_hhmmss\fR - 20071130_140558
827 \fIyy\fR - year; 2007
828 \fImm\fR - month; 11
829 \fIdd\fR - day; 30
830 \fIhh\fR - hour; 14
831 \fImm\fR - minute; 05
832 \fIss\fR - second; 58
834 .in -2
840 .ne 2
842 \fB/etc/default/be\fR
844 .sp .6
845 .RS 4n
846 Contains default value for BENAME_STARTS_WITH parameter
850 .SH ATTRIBUTES
852 See \fBattributes\fR(5) for descriptions of the  following  attributes:
857 box;
858 c | c
859 l | l .
860 ATTRIBUTE TYPE  ATTRIBUTE VALUE
862 Interface Stability     Uncommitted
866 .SH SEE ALSO
868 .BR zfs (8)