Project

General

Profile

Bug #391 ยป beadm.1m.txt

Damian Wojslaw, 2010-11-02 12:56 AM

 
1
System Administration Commands                       beadm(1M)
2

    
3
NAME
4
     beadm - utility for managing zfs boot environments
5

    
6
SYNOPSIS
7
     /usr/sbin/beadm 
8

    
9
     beadm create [-a] [-d description]
10
         [-e non-activeBeName | beName@snapshot]
11
         [-o property=value] ... [-p zpool] beName  
12

    
13
     beadm create beName@snapshot
14

    
15
     beadm destroy [-fF] beName | beName@snapshot
16

    
17
     beadm list [-a | -ds] [-H] [beName]
18

    
19
     beadm mount beName mountpoint
20

    
21
     beadm unmount [-f] beName
22

    
23
     beadm rename beName newBeName
24
 
25
     beadm activate beName
26
 
27

    
28
DESCRIPTION
29
     The beadm command is the user interface for managing zfs
30
     Boot Environments (BEs). This utility is intended to be
31
     used by System Administrators who want to manage multiple
32
     Solaris Instances on a single system.
33

    
34
     The beadm command will support the following operations:
35

    
36
     - Create a new BE, based on the active BE.
37
     - Create a new BE, based on an inactive BE.
38
     - Create a snapshot of an existing BE.
39
     - Create a new BE, based on an existing snapshot.
40
     - Create a new BE, and copy it to a different zpool.
41
     - Activate an existing, inactive BE.
42
     - Mount a BE.
43
     - Unmount a BE.
44
     - Destroy a BE.
45
     - Destroy a snapshot of a BE.
46
     - Rename an existing, inactive BE.
47
     - Display information about your snapshots and datasets.
48

    
49

    
50
SUBCOMMANDS
51
     The beadm command has the subcommands and options listed
52
     below. Also see EXAMPLES below.
53

    
54
     beadm
55

    
56
	Displays command usage.
57

    
58
     beadm create [-a] [-d description]
59
         [-e non-activeBeName | beName@snapshot]
60
         [-o property=value] ... [-p zpool] beName
61

    
62
        Creates a new boot environment named beName.  If the
63
	-e option is not provided, the new boot environment will
64
	be created as a clone of the currently running boot
65
	environment. If the -d option is provided then the
66
	description is also used as the title for the BE's
67
	entry in the GRUB menu for x86 systems or in the boot
68
	menu for SPARC systems. If the -d option is not provided,
69
	beName will be used as the title.
70

    
71
	-a			Activate the newly created BE
72
				upon creation.  The default is to
73
				not activate the newly created
74
				BE.
75

    
76
	-d description		Create a new BE with a desc-
77
				ription associated with it.
78

    
79
	-e non-activeBeName	Create a new BE from an existing
80
				inactive BE.
81

    
82
	-e beName@snapshot	Create a new BE from an existing
83
				snapshot of the BE named beName.
84

    
85
	-o property=value	Create the datasets for new BE
86
				with specific ZFS properties.
87
				Multiple -o options can be
88
				specified.  See zfs(1M) for more
89
				information on the -o option.
90

    
91
	-p zpool		Create the new BE in the
92
				specified zpool.  If this is not
93
				provided, the default behavior is
94
				to create the new BE in the same
95
				pool as as the origin BE.
96

    
97
     beadm create beName@snapshot
98

    
99
	Creates a snapshot of the existing BE named beName.
100

    
101
     beadm destroy [-fF] beName | beName@snapshot
102

    
103
	Destroys the boot environment named beName or destroys
104
	an existing snapshot of the boot environment named
105
	beName@snapshot.  Destroying a boot environment will also
106
	destroy all snapshots of that boot environment.  Use
107
	this command with caution.
108

    
109
	-f		Forcefully unmount the boot environment
110
			if it is currently mounted.
111

    
112
	-F		Force the action without prompting to
113
			verify the destruction of the boot
114
			environment.
115

    
116
     beadm list [-a | -ds] [-H] [beName]
117

    
118
	Lists information about the existing boot environment
119
	named beName, or lists information for all boot
120
	environments if beName is not provided.  The 'Active'
121
	field indicates whether the boot environment is active
122
	now, represented by 'N'; active on reboot, represented
123
	by 'R'; or both, represented by 'NR'.
124

    
125
	Each line in the machine parasable output has the boot
126
	environment name as the first field.  The 'Space' field
127
	is displayed in bytes and the 'Created' field is
128
	displayed in UTC format.  The -H option used with no
129
	other options gives the boot environment's uuid in the
130
	second field.  This field will be blank if the boot
131
	environment does not have a uuid.  See the EXAMPLES
132
	section.
133

    
134
	-a		Lists all available information about
135
			the boot environment.  This includes
136
			subordinate file systems and snapshots.
137

    
138
	-d		Lists information about all subordinate
139
			file systems belonging to the boot
140
			environment.  
141

    
142
	-s		Lists information about the snapshots
143
			of the boot environment.
144

    
145
	-H		Do not list header information.  Each
146
			field in the list information is
147
			separated by a semicolon.
148

    
149
     beadm mount beName mountpoint
150

    
151
	Mounts a boot environment named beName at mountpoint.
152
        mountpoint must be an already existing empty directory.
153

    
154
     beadm unmount [-f] beName
155

    
156
	Unmounts the boot environment named beName.  
157

    
158
	-f		Forcefully unmount the boot environment
159
			even if its currently busy.
160

    
161
     beadm rename beName newBeName
162

    
163
	Renames the boot environment named beName to newBeName.
164

    
165
     beadm activate beName
166

    
167
	Makes beName the active BE on next reboot.
168

    
169

    
170
EXAMPLES
171
     
172
Example 1: Create a new BE named BE1, by cloning the current
173
	live BE.
174

    
175
    # beadm create BE1 
176

    
177
Example 2: Create a new BE named BE2, by cloning the existing
178
	inactive BE named BE1.
179

    
180
    # beadm create -e BE1 BE2
181

    
182
Example 3: Create a snapshot named now of the existing BE
183
	named BE1.
184

    
185
    # beadm create BE1@now
186

    
187
Example 4: Create a new BE named BE3, by cloning an existing
188
	snapshot of BE1.
189

    
190
    # beadm create -e BE1@now BE3
191

    
192
Example 5: Create a new BE named BE4 based on the currently
193
	running BE.  Create the new BE in rpool2.
194

    
195
    # beadm create -p rpool2 BE4
196

    
197
Example 6: Create a new BE named BE5 based on the currently
198
	running BE.  Create the new BE in rpool2, and create
199
	its datasets with compression turned on.
200

    
201
    # beadm create -p rpool2 -o compression=on BE5
202
    
203
Example 7: Create a new BE named BE6 based on the currently
204
	running BE and provide a description for it.
205

    
206
    # beadm create -d "BE6 used as test environment" BE6
207

    
208
Example 8: Activate an existing, inactive BE named BE3.
209

    
210
    # beadm activate BE3
211

    
212
Example 9: Mount the BE named BE3 at /mnt.
213

    
214
    # beadm mount BE3 /mnt
215

    
216
Example 10: Unmount the mounted BE named BE3.
217

    
218
    # beadm unmount BE3
219

    
220
Example 11: Destroy the BE named BE3 without verification.
221

    
222
    # beadm destroy -f BE3
223

    
224
Example 12: Destroy the snapshot named now of BE1.
225

    
226
    # beadm destroy BE1@now
227

    
228
Example 13: Rename the existing, inactive BE named BE1 to
229
	BE3.
230

    
231
    # beadm rename BE1 BE3
232

    
233
Example 14: List all existing boot environments.
234

    
235
.sp
236
.in +4
237
.nf
238
\fB# beadm list\fR
239
BE  Active Mountpoint Space  Policy Created
240
--  ------ ---------- -----  ------ -------
241
BE2 -      -          72.0K  static 2008-05-21 12:26
242
BE3 -      -          332.0K static 2008-08-26 10:28
243
BE4 -      -          15.78M static 2008-09-05 18:20
244
BE5 NR     /          7.25G  static 2008-09-09 16:53
245
.fi
246
.in -4
247
.sp
248

    
249
Example 14: List all existing boot environmets and list all
250
	dataset and snapshot information about those boot
251
	environments.
252

    
253
.sp
254
.in +4
255
.nf
256
\fB# beadm list -d -s\fR
257

    
258
BE/Dataset/Snapshot     Active Mountpoint Space   Policy Created
259
-------------------     ------ ---------- -----   ------ -------
260
BE2
261
   p/ROOT/BE2           -      -          36.0K   static 2008-05-21 12:26
262
   p/ROOT/BE2/opt       -      -          18.0K   static 2008-05-21 16:26
263
   p/ROOT/BE2/opt@now   -      -          0       static 2008-09-08 22:43
264
   p/ROOT/BE2@now       -      -          0       static 2008-09-08 22:43
265
BE3
266
   p/ROOT/BE3           -      -          192.0K  static 2008-08-26 10:28
267
   p/ROOT/BE3/opt       -      -          86.0K   static 2008-08-26 10:28
268
   p/ROOT/BE3/opt/local -      -          36.0K   static 2008-08-28 10:58
269
BE4
270
   p/ROOT/BE4           -      -          15.78M  static 2008-09-05 18:20
271
BE5
272
   p/ROOT/BE5           NR     /          6.10G   static 2008-09-09 16:53
273
   p/ROOT/BE5/opt       -      /opt       24.55M  static 2008-09-09 16:53
274
   p/ROOT/BE5/opt@bar   -      -          18.38M  static 2008-09-10 00:59
275
   p/ROOT/BE5/opt@foo   -      -          18.38M  static 2008-06-10 16:37
276
   p/ROOT/BE5@bar       -      -          139.44M static 2008-09-10 00:59
277
   p/ROOT/BE5@foo       -      -          912.85M static 2008-06-10 16:37
278
.fi
279
.in -4
280
.sp
281

    
282
Example 15: List all dataset and snapshot information about BE5
283

    
284
.sp
285
.in +4
286
.nf
287
\fB# beadm list -a BE5\fR
288

    
289
BE/Dataset/Snapshot   Active Mountpoint Space   Policy Created          
290
-------------------   ------ ---------- -----   ------ -------          
291
BE5
292
   p/ROOT/BE5         NR     /          6.10G   static 2008-09-09 16:53
293
   p/ROOT/BE5/opt     -      /opt       24.55M  static 2008-09-09 16:53
294
   p/ROOT/BE5/opt@bar -      -          18.38M  static 2008-09-10 00:59
295
   p/ROOT/BE5/opt@foo -      -          18.38M  static 2008-06-10 16:37
296
   p/ROOT/BE5@bar     -      -          139.44M static 2008-09-10 00:59
297
   p/ROOT/BE5@foo     -      -          912.85M static 2008-06-10 16:37
298
.fi
299
.in -4
300
.sp
301

    
302
Example 16: List machine parsable information about all boot
303
	environments.
304

    
305
.sp
306
.in +4
307
.nf
308
\fB# beadm list -H\fR
309

    
310
BE2;;;;55296;static;1211397974
311
BE3;;;;339968;static;1219771706
312
BE4;;;;16541696;static;1220664051
313
BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384
314
.fi
315
.in -4
316
.sp
317

    
318
EXIT STATUS
319
     The following exit values are returned:
320

    
321
        0 - Success
322
        >0 - Failure
323

    
324

    
325
FILES
326
     
327
    /var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss>
328
    
329
	Log used for capturing beadm create output
330

    
331
        yyyymmdd_hhmmss - 20071130_140558
332
        yy - year; 2007
333
        mm - month; 11
334
        dd - day; 30
335
        hh - hour; 14
336
        mm - minute; 05
337
        ss - second; 58
338

    
339

    
340
ATTRIBUTES
341
    See attributes(5) for descriptions of the  following  attri-
342
    butes:
343

    
344
     ____________________________________________________________
345
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
346
    |_____________________________|_____________________________|
347
    | Availability                | SUNWbeadm                   |
348
    |_____________________________|_____________________________|
349
    | Interface Stability         | Uncommitted                 |
350
    |_____________________________|_____________________________|
351

    
352

    
353
SEE ALSO
354
    zfs(1M)
355

    
356

    
357
NOTES
358
		Last change: 10 September 2008
    (1-1/1)