VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-snapshot.xml@ 84151

Last change on this file since 84151 was 82969, checked in by vboxsync, 5 years ago

Copyright year updates - manual ones.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage snapshot
4
5 Copyright (C) 2006-2020 Oracle Corporation
6
7 This file is part of VirtualBox Open Source Edition (OSE), as
8 available from http://www.virtualbox.org. This file is free software;
9 you can redistribute it and/or modify it under the terms of the GNU
10 General Public License (GPL) as published by the Free Software
11 Foundation, in version 2 as it comes in the "COPYING" file of the
12 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
14 -->
15<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
16 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
17<!ENTITY % all.entities SYSTEM "all-entities.ent">
18%all.entities;
19]>
20<refentry id="vboxmanage-snapshot" lang="en">
21 <refentryinfo>
22 <pubdate>March 2019</pubdate>
23 <title>VBoxManage snapshot</title>
24 </refentryinfo>
25
26 <refmeta>
27 <refentrytitle>VBoxManage-snapshot</refentrytitle>
28 <manvolnum>1</manvolnum>
29 </refmeta>
30
31 <refnamediv>
32 <refname>VBoxManage-snapshot</refname>
33 <refpurpose>manage &product-name; virtual machine snapshots</refpurpose>
34 <refclass>Oracle VM VirtualBox</refclass>
35 </refnamediv>
36
37 <refsynopsisdiv>
38 <cmdsynopsis id="synopsis-vboxmanage-snapshot">
39<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
40 <command>VBoxManage snapshot</command>
41 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
42 </cmdsynopsis>
43
44 <cmdsynopsis id="synopsis-vboxmanage-snapshot-take">
45 <command>VBoxManage snapshot</command>
46 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
47
48 <arg choice="plain">take</arg>
49
50 <arg choice="req"><replaceable>snapshot-name</replaceable></arg>
51
52 <arg>--description=<replaceable>description</replaceable></arg>
53
54 <arg>--live</arg>
55
56 <arg>--uniquename Number,Timestamp,Space,Force</arg>
57 </cmdsynopsis>
58
59 <cmdsynopsis id="synopsis-vboxmanage-snapshot-delete">
60 <command>VBoxManage snapshot</command>
61 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
62
63 <arg choice="plain">delete</arg>
64
65 <arg choice="req"><replaceable>snapshot-name</replaceable></arg>
66 </cmdsynopsis>
67
68 <cmdsynopsis id="synopsis-vboxmanage-snapshot-restore">
69 <command>VBoxManage snapshot</command>
70 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
71
72 <arg choice="plain">restore</arg>
73
74 <arg choice="req"><replaceable>snapshot-name</replaceable></arg>
75 </cmdsynopsis>
76
77 <cmdsynopsis id="synopsis-vboxmanage-snapshot-restorecurrent">
78 <command>VBoxManage snapshot</command>
79 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
80
81 <arg choice="plain">restorecurrent</arg>
82 </cmdsynopsis>
83
84 <cmdsynopsis id="synopsis-vboxmanage-snapshot-edit">
85 <command>VBoxManage snapshot</command>
86 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
87
88 <arg choice="plain">edit</arg>
89
90 <group choice="req">
91 <arg choice="plain"><replaceable>snapshot-name</replaceable></arg>
92 <arg choice="plain">--current</arg>
93 </group>
94
95 <arg>--description=<replaceable>description</replaceable></arg>
96
97 <arg>--name=<replaceable>new-name</replaceable></arg>
98 </cmdsynopsis>
99
100 <cmdsynopsis id="synopsis-vboxmanage-snapshot-list">
101 <command>VBoxManage snapshot</command>
102 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
103
104 <arg choice="plain">list</arg>
105
106 <group choice="opt"><arg choice="opt">--details</arg><arg choice="opt">--machinereadable</arg></group>
107 </cmdsynopsis>
108
109 <cmdsynopsis id="synopsis-vboxmanage-snapshot-showvminfo">
110 <command>VBoxManage snapshot</command>
111 <arg choice="req"><replaceable>uuid|vmname</replaceable></arg>
112
113 <arg choice="plain">showvminfo</arg>
114
115 <arg choice="req"><replaceable>snapshot-name</replaceable></arg>
116 </cmdsynopsis>
117 </refsynopsisdiv>
118
119 <refsect1>
120 <title>Description</title>
121 <para>
122 The <command>VBoxManage snapshot</command> command manages
123 snapshots.
124 </para>
125 <para>
126 &product-name; uses the snapshot to capture the state of a virtual
127 machine (VM). You can later use the snapshot to revert to the
128 state described by the snapshot.
129 </para>
130 <para>
131 A snapshot is a complete copy of a VM's settings. If you take the
132 snapshot while the VM is running, the snapshot also includes the
133 VM's state file.
134 </para>
135 <para>
136 After you take a snapshot, &product-name; creates a
137 <emphasis>differencing hard disk</emphasis> for each normal hard
138 disk that is associated with the host machine. When you restore a
139 snapshot, &product-name; uses these differencing files to quickly
140 reset the contents of the VM's virtual hard disks.
141 </para>
142 <para>
143 For each <command>VBoxManage snapshot</command> command, you must
144 specify the name or the universal unique identifier (UUID) of the
145 VM for which you want to take a snapshot.
146 </para>
147 <refsect2>
148 <title>General Command Operand</title>
149 <variablelist>
150 <varlistentry>
151 <term><replaceable>uuid|vmname</replaceable></term>
152 <listitem><para>
153 Specifies the UUID or name of the VM.
154 </para></listitem>
155 </varlistentry>
156 </variablelist>
157 </refsect2>
158 <refsect2 id="vboxmanage-snapshot-take">
159 <title>Take a Snapshot of a Virtual Machine</title>
160 <remark role="help-copy-synopsis"/>
161 <para>
162 The <command>VBoxManage snapshot take</command> command takes a
163 snapshot of the current state of the VM. You must supply a name
164 for the snapshot and can optionally supply a description. The
165 new snapshot is inserted into the snapshots tree as a child of
166 the current snapshot and then becomes the new current snapshot.
167 </para>
168 <variablelist>
169 <varlistentry>
170 <term><option>--description=<replaceable>description</replaceable></option></term>
171 <listitem><para>
172 Specifies a description of the snapshot.
173 </para></listitem>
174 </varlistentry>
175 <varlistentry>
176 <term><option>--live</option></term>
177 <listitem><para>
178 Specifies that the VM is not stopped while you create the
179 snapshot. This operation is know as live snapshotting.
180 </para></listitem>
181 </varlistentry>
182 <varlistentry>
183 <term><option>--uniquename Number,Timestamp,Space,Force</option></term>
184 <listitem><para>
185 TBD.
186 </para><remark>
187 What does this option do and how is it used?
188 </remark></listitem>
189 </varlistentry>
190 <varlistentry>
191 <term><replaceable>snapshot-name</replaceable></term>
192 <listitem><para>
193 Specifies the name of the snapshot to create.
194 </para></listitem>
195 </varlistentry>
196 </variablelist>
197 </refsect2>
198 <refsect2 id="vboxmanage-snapshot-delete">
199 <title>Delete a Snapshot</title>
200 <remark role="help-copy-synopsis"/>
201 <para>
202 The <command>VBoxManage snapshot delete</command> command
203 removes the specified snapshot.
204 </para>
205 <para>
206 The delete operation may take some time to finish. This is
207 because the differencing images that are associated with the
208 snapshot may need to be merged with their child differencing
209 images.
210 </para>
211 <variablelist>
212 <varlistentry>
213 <term><replaceable>snapshot-name</replaceable></term>
214 <listitem><para>
215 Specifies the UUID or name of the snapshot.
216 </para></listitem>
217 </varlistentry>
218 </variablelist>
219 </refsect2>
220 <refsect2 id="vboxmanage-snapshot-restore">
221 <title>Restore a Snapshot</title>
222 <remark role="help-copy-synopsis"/>
223 <para>
224 The <command>VBoxManage snapshot restore</command> command
225 restores the specified snapshot. This operation resets the VM's
226 settings and current state to that of the snapshot. The state of
227 the VM on which you restore a snapshot is lost. When restored,
228 the specified snapshot becomes the new current snapshot and
229 subsequent snapshots are children of that snapshot.
230 </para>
231 <variablelist>
232 <varlistentry>
233 <term><replaceable>snapshot-name</replaceable></term>
234 <listitem><para>
235 Specifies the UUID or name of the snapshot.
236 </para></listitem>
237 </varlistentry>
238 </variablelist>
239 </refsect2>
240 <refsect2 id="vboxmanage-snapshot-restorecurrent">
241 <title>Restore the Current Snapshot</title>
242 <remark role="help-copy-synopsis"/>
243 <para>
244 The <command>VBoxManage snapshot restorecurrent</command>
245 command restores the current snapshot. The current snapshot is
246 the one from which the current state is derived. This command is
247 equivalent to using the <command>VBoxManage snapshot
248 restore</command> command and specifying the name or UUID of the
249 current snapshot.
250 </para>
251 </refsect2>
252 <refsect2 id="vboxmanage-snapshot-edit">
253 <title>Change the Name or Description of an Existing Snapshot</title>
254 <remark role="help-copy-synopsis"/>
255 <para>
256 The <command>VBoxManage snapshot edit</command> command enables
257 you to change the name or the description of a specified
258 snapshot.
259 </para>
260 <variablelist>
261 <varlistentry>
262 <term><replaceable>snapshot-name</replaceable></term>
263 <listitem><para>
264 Specifies the UUID or name of the snapshot to edit.
265 </para><para>
266 This option is mutually exclusive with the
267 <option>--current</option> option.
268 </para></listitem>
269 </varlistentry>
270 <varlistentry>
271 <term><option>--current</option></term>
272 <listitem><para>
273 Specifies that you update the current version of the
274 snapshot.
275 </para><para>
276 This option is mutually exclusive with a specific snapshot
277 name or its UUID.
278 </para></listitem>
279 </varlistentry>
280 <varlistentry>
281 <term><option>--description=<replaceable>description</replaceable></option></term>
282 <listitem><para>
283 Specifies a new description for the snapshot.
284 </para></listitem>
285 </varlistentry>
286 <varlistentry>
287 <term><option>--name=<replaceable>new-name</replaceable></option></term>
288 <listitem><para>
289 Specifies a new name for the snapshot.
290 </para></listitem>
291 </varlistentry>
292 </variablelist>
293 </refsect2>
294 <refsect2 id="vboxmanage-snapshot-list">
295 <title>List the Snapshots</title>
296 <remark role="help-copy-synopsis"/>
297 <para>
298 The <command>VBoxManage snapshot list</command> command lists
299 all the snapshots for a VM.
300 </para>
301 <variablelist>
302 <varlistentry>
303 <term><option>--details</option></term>
304 <listitem><para>
305 Specifies that the output shows detailed information about
306 the snapshot.
307 </para><para>
308 This option is mutually exclusive with the
309 <option>--machinereadable</option> option.
310 </para></listitem>
311 </varlistentry>
312 <varlistentry>
313 <term><option>--machinereadable</option></term>
314 <listitem><para>
315 Specifies that the output is shown in a machine-readable
316 format.
317 </para><para>
318 This option is mutually exclusive with the
319 <option>--details</option> option.
320 </para></listitem>
321 </varlistentry>
322 </variablelist>
323 </refsect2>
324 <refsect2 id="vboxmanage-snapshot-showvminfo">
325 <title>Show Information About a Snapshot's Settings</title>
326 <remark role="help-copy-synopsis"/>
327 <para>
328 The <command>VBoxManage snapshot showvminfo</command> command
329 enables you to view the VM settings that are part of an existing
330 snapshot.
331 </para>
332 <variablelist>
333 <varlistentry>
334 <term><replaceable>snapshot-name</replaceable></term>
335 <listitem><para>
336 Specifies the UUID or name of the snapshot.
337 </para></listitem>
338 </varlistentry>
339 </variablelist>
340 </refsect2>
341 </refsect1>
342
343 <refsect1>
344 <title>Examples</title>
345 <remark role="help-scope" condition="GLOBAL"/>
346 <para>
347 The following command creates a snapshot of the
348 <computeroutput>ol7u4</computeroutput> VM. The snapshot is called
349 <computeroutput>ol7u4-snap-001</computeroutput>. The command uses
350 the <option>--description</option> option to provide a description
351 of the snapshot contents.
352 </para>
353<screen>
354$ VBoxManage snapshot ol7u4 take ol7u4-snap-001 \
355--description="Oracle Linux 7.4"
356</screen>
357 <para>
358 The following command lists the snapshots for the
359 <computeroutput>ol7u4</computeroutput> VM.
360 </para>
361<screen>
362$ VBoxManage snapshot ol7u4 list
363</screen>
364 <para>
365 The following command changes the description for the
366 <computeroutput>ol7u4-snap-001</computeroutput> snapshot of the
367 <computeroutput>ol7u4</computeroutput> VM.
368 </para>
369<screen>
370$ VBoxManage snapshot ol7u4 edit ol7u4-snap-001 \
371--description="Oracle Linux 7.4 with UEK4 kernel"
372</screen>
373 <para>
374 The following command shows VM settings for the
375 <computeroutput>ol7u1-snap-001</computeroutput> snapshot of the
376 <computeroutput>ol7u4</computeroutput> VM.
377 </para>
378<screen>
379$ VBoxManage snapshot ol7u4 showvminfo ol7u4-snap-001
380Name: ol7u4
381Groups: /
382Guest OS: Oracle (64-bit)
383UUID: 43349d78-2ab3-4cb8-978f-0e755cd98090
384Config file: C:\Users\user1\VirtualBox VMs\ol7u4\ol7u4.vbox
385...
386Snapshots:
387
388 Name: ol7u4-snap-001 (UUID: 1cffc37d-5c37-4b86-b9c5-a0f157a55f43)
389 Description: Oracle Linux 7.4 with UEK4 kernel
390</screen>
391 </refsect1>
392</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette