VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-clonevm.xml@ 103131

Last change on this file since 103131 was 99513, checked in by vboxsync, 19 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage clonevm
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="vboxmanage-clonevm" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 21:59:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage clonevm</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-clonevm</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-clonevm</refname>
44 <refpurpose>create a clone of an existing virtual machine</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-clonevm">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage clonevm</command>
52 <arg choice="req"><replaceable>vmname|uuid</replaceable></arg>
53
54 <arg>--basefolder=<replaceable>basefolder</replaceable></arg>
55
56 <arg rep="repeat">--groups=<replaceable>group</replaceable>,</arg>
57
58 <group choice='opt'>
59 <arg choice='plain'>--mode=machine</arg>
60 <arg choice='plain'>--mode=machinechildren</arg>
61 <arg choice='plain'>--mode=all</arg>
62 </group>
63
64 <arg>--name=<replaceable>name</replaceable></arg>
65
66 <arg rep="repeat">--options=<replaceable>option</replaceable>,</arg>
67
68 <arg>--register</arg>
69
70 <arg>--snapshot=<replaceable>snapshot-name</replaceable></arg>
71
72 <arg>--uuid=<replaceable>uuid</replaceable></arg>
73 </cmdsynopsis>
74 </refsynopsisdiv>
75
76 <refsect1 id="vboxmanage-clonevm-description">
77 <title>Description</title>
78 <para>
79 The <command>VBoxManage clonevm</command> command creates a clone
80 of an existing virtual machine (VM). The clone can be a full copy
81 of the VM or a linked copy of a VM.
82 </para>
83 <para>
84 You must specify the name or the universal unique identifier
85 (UUID) of the VM you want to clone.
86 </para>
87 </refsect1>
88
89 <refsect1 id="vboxmanage-clonevm-common-args">
90 <title>Command Operand and Options</title>
91 <para>
92 The following list describes the operand and the options that you
93 can use with the <command>VBoxManage clonevm</command> command:
94 </para>
95 <variablelist>
96 <varlistentry>
97 <term><replaceable>vmname|uuid</replaceable></term>
98 <listitem><para>
99 Specifies the name or UUID of the VM to clone.
100 </para></listitem>
101 </varlistentry>
102 <varlistentry>
103 <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term>
104 <listitem><para>
105 Specifies the name of the folder in which to save the
106 configuration for the new VM.
107 </para></listitem>
108 </varlistentry>
109 <varlistentry>
110 <term><option>--groups=<replaceable>group</replaceable>,...</option></term>
111 <listitem><para>
112 Assigns the clone to the specified group or groups. If you
113 specify more than one group, separate each group name with a
114 comma.
115 </para><para>
116 Note that each group is identified by a group ID that starts
117 with a slash character (<computeroutput>/</computeroutput>)
118 so that groups can be nested. By default, a clone is always
119 assigned membership to the
120 <computeroutput>/</computeroutput> group.
121 </para></listitem>
122 </varlistentry>
123 <varlistentry>
124 <term><option>--mode=machine|machineandchildren|all</option></term>
125 <listitem><para>
126 Specifies which of the following cloning modes to use:
127 </para><itemizedlist>
128 <listitem><para>
129 <computeroutput>machine</computeroutput> mode clones the
130 current state of the existing VM without any snapshots.
131 This is the default mode.
132 </para></listitem>
133 <listitem><para>
134 <computeroutput>machineandchildren</computeroutput> mode
135 clones the snapshot specified by by the
136 <option>--snapshot</option> option and all child
137 snapshots.
138 </para></listitem>
139 <listitem><para>
140 <computeroutput>all</computeroutput> mode clones all
141 snapshots and the current state of the existing VM.
142 </para></listitem>
143 </itemizedlist></listitem>
144 </varlistentry>
145 <varlistentry>
146 <term><option>--name=<replaceable>name</replaceable></option></term>
147 <listitem><para>
148 Specifies a new name for the new VM. The default value is
149 <computeroutput><replaceable>original-name</replaceable>
150 Clone</computeroutput> where
151 <replaceable>original-name</replaceable> is the original
152 name of the VM.
153 </para></listitem>
154 </varlistentry>
155 <varlistentry>
156 <term><option>--options=<replaceable>option</replaceable>,...</option></term>
157 <listitem><para>
158 Specifies how to create the new clone.</para>
159 <para>The <option>--options</option> argument can be used multiple
160 times to enable multiple options, or the options can be given as a
161 comma separated list. The options are case insensitive.</para>
162 <para>The following options (case-insensitive) are recognized:</para>
163 <variablelist>
164 <varlistentry>
165 <term><option>Link</option></term>
166 <listitem><para>
167 Creates a linked clone from a snapshot only.
168 </para></listitem>
169 </varlistentry>
170 <varlistentry>
171 <term><option>KeepAllMACs</option></term>
172 <listitem><para>
173 Specifies that the new clone reuses the MAC addresses
174 of each virtual network card from the existing VM.
175 </para><para>
176 If you do not specify this option or the
177 <option>--options=keepnatmacs</option> option, the
178 default behavior is to reinitialize the MAC addresses
179 of each virtual network card.
180 </para></listitem>
181 </varlistentry>
182 <varlistentry>
183 <term><option>KeepNATMACs</option></term>
184 <listitem><para>
185 Specifies that the new clone reuses the MAC addresses
186 of each virtual network card from the existing VM when
187 the network type is NAT.
188 </para><para>
189 If you do not specify this option or the
190 <option>KeepAllMACs</option> option, the
191 default behavior is to reinitialize the MAC addresses
192 of each virtual network card.
193 </para></listitem>
194 </varlistentry>
195 <varlistentry>
196 <term><option>KeepDiskNames</option></term>
197 <listitem><para>
198 Specifies that the new clone reuses the disk image
199 names from the existing VM. By default, disk images
200 are renamed.
201 </para></listitem>
202 </varlistentry>
203 <varlistentry>
204 <term><option>KeepHwUUIDs</option></term>
205 <listitem><para>
206 Specifies that the new clone reuses the hardware IDs
207 from the existing VM. By default, new UUIDs are used.
208 </para></listitem>
209 </varlistentry>
210 </variablelist></listitem>
211 </varlistentry>
212 <varlistentry>
213 <term><option>--register</option></term>
214 <listitem><para>
215 Automatically registers the new clone in this &product-name;
216 installation. You can manually register the new VM later by
217 using the <command>VBoxManage registervm</command> command.
218 See <xref linkend="vboxmanage-registervm" />.
219 </para></listitem>
220 </varlistentry>
221 <varlistentry>
222 <term><option>--snapshot=<replaceable>snapshot-name</replaceable></option></term>
223 <listitem><para>
224 Specifies the snapshot on which to base the new VM. By
225 default, the clone is created from the current state of the
226 specified VM.
227 </para></listitem>
228 </varlistentry>
229 <varlistentry>
230 <term><option>--uuid=<replaceable>uuid</replaceable></option></term>
231 <listitem><para>
232 Specifies the UUID for the new VM. Ensure that this ID is
233 unique for the &product-name; instance if you decide to
234 register this new VM. By default, &product-name; provides a
235 new UUID.
236 </para></listitem>
237 </varlistentry>
238 </variablelist>
239 </refsect1>
240
241 <refsect1 id="vboxmanage-clonevm-examples">
242 <title>Examples</title>
243 <para>
244 The following command creates and registers an exact clone of the
245 <computeroutput>ol7</computeroutput> VM. The clone is called
246 <computeroutput>ol7-dev-001</computeroutput>.
247 </para>
248 <para>
249 The new clone includes all of the source VM's snapshots. The new
250 VM also reuses all network interface MAC addresses, disk names,
251 and UUIDs from the source VM.
252 </para>
253<screen>
254$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \
255 --options=keepallmacs --options=keepdisknames --options=keephwuuids
256</screen>
257 <para>
258 The following command creates and registers a clone of the
259 <computeroutput>Snapshot 1</computeroutput> snapshot of the
260 <computeroutput>ol7</computeroutput> VM. The clone is called
261 <computeroutput>ol7-dev-002</computeroutput>.
262 </para>
263<screen>
264$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1"
265</screen>
266 </refsect1>
267
268 <refsect1 id="vboxmanage-clonevm-see-also">
269 <title>See Also</title>
270 <para>
271 <xref linkend="vboxmanage-registervm" />
272 </para>
273 </refsect1>
274</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