diff options
Diffstat (limited to 'doc/manual/en_US/man_VBoxManage-clonevm.xml')
| -rw-r--r-- | doc/manual/en_US/man_VBoxManage-clonevm.xml | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/manual/en_US/man_VBoxManage-clonevm.xml b/doc/manual/en_US/man_VBoxManage-clonevm.xml new file mode 100644 index 00000000..a6e9b58e --- /dev/null +++ b/doc/manual/en_US/man_VBoxManage-clonevm.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + manpage, user manual, usage: VBoxManage clonevm +--> +<!-- + Copyright (C) 2006-2023 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<refentry id="vboxmanage-clonevm" lang="en"> + <refentryinfo> + <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate> + <title>VBoxManage clonevm</title> + </refentryinfo> + + <refmeta> + <refentrytitle>VBoxManage-clonevm</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>VBoxManage-clonevm</refname> + <refpurpose>create a clone of an existing virtual machine</refpurpose> + <refclass>&product-name;</refclass> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="synopsis-vboxmanage-clonevm"> +<!-- The 'id' is mandatory and must start with 'synopsis-'. --> + <command>VBoxManage clonevm</command> + <arg choice="req"><replaceable>vmname|uuid</replaceable></arg> + + <arg>--basefolder=<replaceable>basefolder</replaceable></arg> + + <arg rep="repeat">--groups=<replaceable>group</replaceable>,</arg> + + <group choice='opt'> + <arg choice='plain'>--mode=machine</arg> + <arg choice='plain'>--mode=machinechildren</arg> + <arg choice='plain'>--mode=all</arg> + </group> + + <arg>--name=<replaceable>name</replaceable></arg> + + <arg rep="repeat">--options=<replaceable>option</replaceable>,</arg> + + <arg>--register</arg> + + <arg>--snapshot=<replaceable>snapshot-name</replaceable></arg> + + <arg>--uuid=<replaceable>uuid</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + The <command>VBoxManage clonevm</command> command creates a clone + of an existing virtual machine (VM). The clone can be a full copy + of the VM or a linked copy of a VM. + </para> + <para> + You must specify the name or the universal unique identifier + (UUID) of the VM you want to clone. + </para> + </refsect1> + + <refsect1> + <title>Command Operand and Options</title> + <para> + The following list describes the operand and the options that you + can use with the <command>VBoxManage clonevm</command> command: + </para> + <variablelist> + <varlistentry> + <term><replaceable>vmname|uuid</replaceable></term> + <listitem><para> + Specifies the name or UUID of the VM to clone. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--basefolder=<replaceable>basefolder</replaceable></option></term> + <listitem><para> + Specifies the name of the folder in which to save the + configuration for the new VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--groups=<replaceable>group</replaceable>,...</option></term> + <listitem><para> + Assigns the clone to the specified group or groups. If you + specify more than one group, separate each group name with a + comma. + </para><para> + Note that each group is identified by a group ID that starts + with a slash character (<computeroutput>/</computeroutput>) + so that groups can be nested. By default, a clone is always + assigned membership to the + <computeroutput>/</computeroutput> group. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--mode=machine|machineandchildren|all</option></term> + <listitem><para> + Specifies which of the following cloning modes to use: + </para><itemizedlist> + <listitem><para> + <computeroutput>machine</computeroutput> mode clones the + current state of the existing VM without any snapshots. + This is the default mode. + </para></listitem> + <listitem><para> + <computeroutput>machineandchildren</computeroutput> mode + clones the snapshot specified by by the + <option>--snapshot</option> option and all child + snapshots. + </para></listitem> + <listitem><para> + <computeroutput>all</computeroutput> mode clones all + snapshots and the current state of the existing VM. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>name</replaceable></option></term> + <listitem><para> + Specifies a new name for the new VM. The default value is + <computeroutput><replaceable>original-name</replaceable> + Clone</computeroutput> where + <replaceable>original-name</replaceable> is the original + name of the VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--options=<replaceable>option</replaceable>,...</option></term> + <listitem><para> + Specifies how to create the new clone.</para> + <para>The <option>--options</option> argument can be used multiple + times to enable multiple options, or the options can be given as a + comma separated list. The options are case insensitive.</para> + <para>The following options (case-insensitive) are recognized:</para> + <variablelist> + <varlistentry> + <term><option>Link</option></term> + <listitem><para> + Creates a linked clone from a snapshot only. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepAllMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM. + </para><para> + If you do not specify this option or the + <option>--options=keepnatmacs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepNATMACs</option></term> + <listitem><para> + Specifies that the new clone reuses the MAC addresses + of each virtual network card from the existing VM when + the network type is NAT. + </para><para> + If you do not specify this option or the + <option>KeepAllMACs</option> option, the + default behavior is to reinitialize the MAC addresses + of each virtual network card. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepDiskNames</option></term> + <listitem><para> + Specifies that the new clone reuses the disk image + names from the existing VM. By default, disk images + are renamed. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>KeepHwUUIDs</option></term> + <listitem><para> + Specifies that the new clone reuses the hardware IDs + from the existing VM. By default, new UUIDs are used. + </para></listitem> + </varlistentry> + </variablelist></listitem> + </varlistentry> + <varlistentry> + <term><option>--register</option></term> + <listitem><para> + Automatically registers the new clone in this &product-name; + installation. You can manually register the new VM later by + using the <command>VBoxManage registervm</command> command. + See <xref linkend="vboxmanage-registervm" />. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--snapshot=<replaceable>snapshot-name</replaceable></option></term> + <listitem><para> + Specifies the snapshot on which to base the new VM. By + default, the clone is created from the current state of the + specified VM. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--uuid=<replaceable>uuid</replaceable></option></term> + <listitem><para> + Specifies the UUID for the new VM. Ensure that this ID is + unique for the &product-name; instance if you decide to + register this new VM. By default, &product-name; provides a + new UUID. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para> + The following command creates and registers an exact clone of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-001</computeroutput>. + </para> + <para> + The new clone includes all of the source VM's snapshots. The new + VM also reuses all network interface MAC addresses, disk names, + and UUIDs from the source VM. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-001" --register --mode=all \ + --options=keepallmacs --options=keepdisknames --options=keephwuuids +</screen> + <para> + The following command creates and registers a clone of the + <computeroutput>Snapshot 1</computeroutput> snapshot of the + <computeroutput>ol7</computeroutput> VM. The clone is called + <computeroutput>ol7-dev-002</computeroutput>. + </para> +<screen> +$ VBoxManage clonevm ol7 --name="ol7-dev-002" --register --snapshot="Snapshot 1" +</screen> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <xref linkend="vboxmanage-registervm" /> + </para> + </refsect1> +</refentry> |