Clone VM With Custom Settings operation

The Clone VM With Custom Settings operation enables you to create a virtual machine clone that has advanced configuration options. This operation enables you to add virtual devices like a hard disk or an ethernet card to the clone virtual machine. This operation also supports the customization of the guest operating system on the clone virtual machine.

Note

Use this operation only if you want to customize the VM while cloning; otherwise, use the Clone VM operation.

You can also use this operation to clone a virtual machine into a template.

If the <status> response element contains _success_, the <Task> response element contains the ID of the queued task, which you can use to obtain the task status.

The following table describes the elements for this request.

Adapter request elements for the Clone VM With Custom Settings operation

Element

Definition

Required

<operation-type>

Defines the type of the operation: Configure_Vm

Yes

<operation-name>

Defines the name of the operation: Clone_VM_With_Custom_Settings

Yes

<soap-url>

Specifies the URL for the remote SOAP service running on the VMware VirtualCenter

If the <soap-url> element is not specified, the request uses the VirtualCenter Server details specified in the adapter configuration.

Default format for HTTPS: https://<hostName>:<port>/sdk/vim

Default format for HTTP: http://<hostName>:<port>/sdk/vim

Note

If you want to use an HTTP value, you might need to change the configuration of the VMware Infrastructure application.

No

<transport>

Specifies the transport protocol for the message

If the <transport> element is not provided, the request uses the VirtualCenter Server details specified in the adapter configuration.

Valid values: https-rpc (default), http-rpc

Note

If the value of the <transport> element is https-rpc, you must install the security certificate for the VMware Virtual Center to the keystore of the peer on which the adapter is enabled.

No

<user-name>

Specifies the user name that is used for HTTP basic authentication on the VMware Virtual Center

If no user name is specified, the request is executed with the user name that is specified in the configuration.

No

<password>

Specifies the password corresponding to <user-name>

Conditional; required if <user-name> is specified

<parameters>

Contains the elements required to execute the operation

Yes

<virtual-machine>

Specifies the name of the virtual machine to be cloned

Yes

<folder>

Specifies the folder in which the clone virtual machine is to be created

If this element is not specified, the clone virtual machine is created in the default vm folder.

No

<datacenter>

Specifies the data center in which the clone virtual machine is to be created

Yes

<name>

Specifies a name for the clone virtual machine

Yes

<power-on>

Specifies whether to power on the clone virtual machine after creation

As part of a customization, this flag is generally set to true because the first power-on operation completes the customization process. This flag is ignored if a template is being created.

Valid values: true, false

Yes

<template>

Specifies whether the new virtual machine should be marked as a template

Valid values: true, false

Yes

<location>

Specifies the location of resources that the clone virtual machine uses

For more information about the child elements of <location>, see location.

Conditional; not required if the virtual machine is cloned from a template

<version>

Specifies the version string for the virtual machine

No

<guest-id>

Specifies the short identifier for the guest operating system

If the guest operating system is not specified, the virtual machine is cloned with the same operating system as the original virtual machine.

For more information about short identifiers for guest operation systems, see Guest-operating-system-identifiers-for-VMware-Infrastructure.

No

<annotation>

Contains a description of the clone virtual machine

No

<tools>

Specifies the configuration of VMware tools running on the guest operating system on the clone

For more information about the child elements of <tools>, see tools.

No

<flags>

Encapsulates the flag settings for the clone virtual machine

For more information about the child elements of <flags>, see flags.

No

<console-preferences>

Specifies the preferences for the legacy console application that affect the way the console behaves during power operations on the clone virtual machine

For more information about the child elements of <console-preferences>, see console-preferences.

No

<power-op-info>

Specifies the configuration for the clone's default power operations

For more information about the child elements of <power-op-info>, see power-op-info.

No

<num-cpus>

Specifies the number of virtual processors in the clone virtual machine

No

<memory-mb>

Specifies the memory size of the clone virtual machine, in MB

Valid values: Any number

No

<device-change-list>

Specifies the set of virtual devices being added to the clone by the configuration operation

For more information about the child elements of <device-change-list>, see device-change-list for adding and device-change-list for updating devices.

No

<cpu-allocation>

Specifies the resource limits for the CPU on the clone

For more information about the child elements of <cpu-allocation>, see cpu-allocation.

No

<memory-allocation>

Specifies the resource limits for memory on the clone

For more information about the child elements of <memory-allocation>, see memory-allocation.

No

<memory-affinity>

Specifies the list of non-uniform memory access (NUMA) nodes that can be used by the clone virtual machine

If the array is empty when you modify the affinity setting, any existing affinity is removed.

No

<network-shaper>

Specifies the network traffic shaping specification used to configure the network utilization characteristics of the clone virtual machine

For information about child elements of <network-shaper>, see network-shaper.

No

<cpu-feature-mask-list>

Specifies the CPU feature compatibility masks

For more information about the child elements of <cpu-feature-mask-list>, see cpu-feature-mask-list.

No

<customization>

Specifies the details for customizing the guest operating system of the clone virtual machine

For more information about the child elements of <customization>, see customization.

Yes

<gui-run-once>

Specifies the list of commands to run when the user logs on for the first time after guest customization

No

The following code sample shows a sample adapter request for the Clone VM With Custom Settings operation.

Sample adapter request for the Clone VM With Custom Settings operation when the* {{*<operation>*}} *element is "add" within the* {{*<device-change>*}} *element

<vmware-infrastructure-request>
 <operation-type>Configure_Vm</operation-type>
 <operation-name>Clone_VM _With_Custom_Settings</operation-name>
 <soap-url></soap-url>
 <transport></transport>
 <user-name></user-name>
 <password></password>
 <parameters>
   <virtual-machine>win1</virtual-machine>
   <folder>TestVMFolder</folder>
   <datacenter>Development</datacenter>
   <name>win8</name>
   <spec>
     <power-on>false</power-on>
     <template>false</template>
     <location>
       <resource-pool>TestRP</resource-pool>
       <cluster-compute-resource>TestCluster</cluster-compute-resource>
       <host-system>xyz.abc.com</host-system>
       <datastore>storage1</datastore>
       <transform>flat</transform>
       <disk-list>
     <disk>
       <disk-name>Hard Disk 1</disk-name>
       <datastore>storage1</datastore>
     </disk>
   </disk-list>
     </location>
     <config>
       <name>win8</name>
   <version>vmx-04</version>
   <guest-id>rhel4Guest</guest-id>
   <annotation>Test Linux machine</annotation>
   <tools>
     <tools-version></tools-version>
     <after-power-on>true</after-power-on>
     <after-resume>false</after-resume>
     <before-guest-standby>true</before-guest-standby>
     <before-guest-shutdown>true</before-guest-shutdown>
     <before-guest-reboot>false</before-guest-reboot>
   </tools>
   <flags>
     <disable-acceleration>false</disable-acceleration>
     <enable-logging>false</enable-logging>
     <use-toe>false</use-toe>
     <run-with-debug-info>true</run-with-debug-info>
     <ht-sharing>any</ht-sharing>
   </flags>
   <console-preferences>
     <power-on-when-opened>true</power-on-when-opened>
     <enter-full-screen-on-power-on>false</enter-full-screen-on-power-on>
     <close-on-power-off-or-suspend>true</close-on-power-off-or-suspend>
   </console-preferences>
   <power-op-info>
     <power-off-type>soft</power-off-type>
     <suspend-type>soft</suspend-type>
     <reset-type>soft</reset-type>
     <default-power-off-type>soft</default-power-off-type>
     <default-suspend-type>soft</default-suspend-type>
     <default-reset-type>soft</default-reset-type>
     <standby-action>checkpoint</standby-action>
   </power-op-info>
   <num-cpus>1</num-cpus>
   <memory-mb>32</memory-mb>
   <device-change-list>
     <device-change>
           <operation>add</operation>
       <device type="VirtualBusLogicController">
       <bus-number>0</bus-number>
       <device>0</device>
       <shared-bus>noSharing</shared-bus>
       </device>
     </device-change>
         <device-change>
           <operation>add</operation>
       <fileOperation>create</fileOperation>
       <device type="VirtualDisk">
       <backing type="VirtualDiskFlatVer2BackingInfo">
         <fileName>[dev1 disk2]</fileName>
         <diskMode>persistent</diskMode>
         <split>true</split>
         <writeThrough>true</writeThrough>
         <thinProvisioned>false</thinProvisioned>
       </backing>
       <controllerKey>0</controllerKey>
       <unitNumber>-1</unitNumber>
       <capacityInKB>1024</capacityInKB>
           <shares>
             <shares>1024</shares>
         <level>low</level>
           </shares>
       </device>
     </device-change>
     <device-change>
       <operation>add</operation>
       <device type="VirtualPCIController">
       <bus-number>0</bus-number>
       <device>0</device>
       </device>
     </device-change>
     <device-change>
       <operation>add</operation>
       <device type="VirtualPCNet32">
       <backing type="VirtualEthernetCardNetworkBackingInfo">
         <device-name>VM Network</device-name>
       </backing>
       <connectable>
         <start-connected>false</start-connected>
         <allow-guest-control>true</allow-guest-control>
         <connected>false</connected>
       </connectable>
       <controllerKey>0</controllerKey>
       <unitNumber>0</unitNumber>
       <address-type>manual</address-type>
       <mac-address>00:50:56:84:2f:6b</mac-address>
       <wake-on-lan-enabled>false</wake-on-lan-enabled>
           </device>
         </device-change>
   </device-change-list>
   <cpu-allocation>
     <reservation>0</reservation>
     <limit>-1</limit>
     <shares>
       <shares>1862</shares>
       <level>custom</level>
     </shares>
   </cpu-allocation>
   <memory-allocation>
     <reservation>0</reservation>
     <limit>2048</limit>
     <shares>
       <shares>2048</shares>
       <level>custom</level>
     </shares>
   </memory-allocation>
   <cpu-affinity>
     <affinity-set-list>
       <affinity-set>1</affinity-set>
       <affinity-set>2</affinity-set>
     </affinity-set-list>
   </cpu-affinity>
   <memory-affinity>
     <affinity-set-list>
       <affinity-set>1</affinity-set>
       <affinity-set>2</affinity-set>
     </affinity-set-list>
   </memory-affinity>
   <network-shaper>
     <enabled>true</enabled>
     <peak-bps>10</peak-bps>
     <average-bps>5</average-bps>
     <burst-size>8</burst-size>
   </network-shaper>
   <cpu-feature-mask-list>
     <cpu-feature-mask>
       <operation>add</operation>
       <info>
         <level>-2147483648</level>
             <vendor>amd</vendor>
         <eax></eax>
         <ebx></ebx>
         <ecx></ecx>
         <edx></edx>
       </info>
     </cpu-feature-mask>
     <cpu-feature-mask>
       <operation>add</operation>
       <info>
         <level>-2147483647</level>
         <vendor></vendor>
         <eax></eax>
         <ebx></ebx>
         <ecx></ecx>
         <edx></edx>
       </info>
     </cpu-feature-mask>
   </cpu-feature-mask-list>
     </config>
     <customization>
   <identity type='CustomizationSysprep'>
   <gui-unattended>
         <password>
           <value>abc123</value>
           <plain-text>true</plain-text>
         </password>
         <time-zone>123</time-zone>
     <auto-logon>false</auto-logon>
     <auto-logon-count>1</auto-logon-count>
   </gui-unattended>
   <user-data>
     <full-name>User1</full-name>
     <org-name>BMC</org-name>
     <computer-name>
       <name>AdapterDev</name>
     </computer-name>
     <product-id></product-id>
   </user-data>
       <gui-run-once>
         <command>C:\run.bat</command>
         <command>cmd.exe /c mkdir test</command>
       </gui-run-once>
   <identification>
     <join-workgroup>WORKGROUP</join-workgroup>
   </identification>
   <license-file-print-data>
     <auto-mode></auto-mode>
     <auto-users></auto-users>
   </license-file-print-data>
   <host-name>
     <name></name>
   </host-name>
   <domain></domain>
   </identity>
   <globalIPSettings>
     <dns-server-list>
       <dns-server-list>10.254.1.10</dns-server-list>
       <dns-server-list>10.254.1.11</dns-server-list>
     </dns-server-list>
     <dns-suffix-list>
       <dns-suffix-list>abc.com</dns-suffix-list>
       <dns-suffix-list>vmware.com</dns-suffix-list>
     </dns-suffix-list>
   </globalIPSettings>
   <nic-setting-map>
     <adapter>
       <ip type="CustomizationDhcpIpGenerator">
       <ipAddress></ipAddress>
       </ip>
       <subnet-mask>255.255.255.0</subnet-mask>
       <gateway>172.1.114.1</gateway>
       <dns-domain>abc.com</dns-domain>
     </adapter>
   </nic-setting-map>
     </customization>
   </spec>
 </parameters>
</vmware-infrastructure-request>

Sample adapter request for the Clone VM With Custom Settings operation when the <operation> element is "edit" within the <device-change> element

<vmware-infrastructure-request>
 <operation-type>Configure_Vm</operation-type>
 <operation-name>Clone_VM _With_Custom_Settings</operation-name>
 <soap-url></soap-url>
 <transport></transport>
 <user-name></user-name>
 <password></password>
 <parameters>
   <virtual-machine>win1</virtual-machine>
   <folder>TestVMFolder</folder>
   <datacenter>Development</datacenter>
   <name>win8</name>
   <spec>
     <power-on>false</power-on>
     <template>false</template>
     <location>
       <resource-pool>TestRP</resource-pool>
       <cluster-compute-resource>TestCluster</cluster-compute-resource>
       <host-system>xyz.abc.com</host-system>
       <datastore>storage1</datastore>
       <transform>flat</transform>
       <disk-list>
     <disk>
       <disk-name>Hard Disk 1</disk-name>
       <datastore>storage1</datastore>
     </disk>
   </disk-list>
     </location>
     <config>
       <name>win8</name>
   <version>vmx-04</version>
   <guest-id>rhel4Guest</guest-id>
   <annotation>Test Linux machine</annotation>
   <tools>
     <tools-version></tools-version>
     <after-power-on>true</after-power-on>
     <after-resume>false</after-resume>
     <before-guest-standby>true</before-guest-standby>
     <before-guest-shutdown>true</before-guest-shutdown>
     <before-guest-reboot>false</before-guest-reboot>
   </tools>
   <flags>
     <disable-acceleration>false</disable-acceleration>
     <enable-logging>false</enable-logging>
     <use-toe>false</use-toe>
     <run-with-debug-info>true</run-with-debug-info>
     <ht-sharing>any</ht-sharing>
   </flags>
   <console-preferences>
     <power-on-when-opened>true</power-on-when-opened>
     <enter-full-screen-on-power-on>false</enter-full-screen-on-power-on>
     <close-on-power-off-or-suspend>true</close-on-power-off-or-suspend>
   </console-preferences>
   <power-op-info>
     <power-off-type>soft</power-off-type>
     <suspend-type>soft</suspend-type>
     <reset-type>soft</reset-type>
     <default-power-off-type>soft</default-power-off-type>
     <default-suspend-type>soft</default-suspend-type>
     <default-reset-type>soft</default-reset-type>
     <standby-action>checkpoint</standby-action>
   </power-op-info>
   <num-cpus>1</num-cpus>
   <memory-mb>32</memory-mb>
   <device-change-list>
     <device-change>
           <operation>edit</operation>
       <device type="VirtualE1000">
         <key>4000</key>
         <backing type="VirtualEthernetCardNetworkBackingInfo">
         <device-name>VM Network 2</device-name>
         </backing>
         <connectable>
           <start-connected>false</start-connected>
           <allow-guest-control>false</allow-guest-control>
           <connected>false</connected>
         </connectable>
             <address-type>manual</address-type>
             <mac-address>00:50:56:9d:00:1f</mac-address>
             <wake-on-lan-enabled>true</wake-on-lan-enabled>
       </device>
     </device-change>
       </device-change-list>
   <cpu-allocation>
     <reservation>0</reservation>
     <limit>-1</limit>
     <shares>
       <shares>1862</shares>
       <level>custom</level>
     </shares>
   </cpu-allocation>
   <memory-allocation>
     <reservation>0</reservation>
     <limit>2048</limit>
     <shares>
       <shares>2048</shares>
       <level>custom</level>
     </shares>
   </memory-allocation>
   <cpu-affinity>
     <affinity-set-list>
       <affinity-set>1</affinity-set>
       <affinity-set>2</affinity-set>
     </affinity-set-list>
   </cpu-affinity>
   <memory-affinity>
     <affinity-set-list>
       <affinity-set>1</affinity-set>
       <affinity-set>2</affinity-set>
     </affinity-set-list>
   </memory-affinity>
   <network-shaper>
     <enabled>true</enabled>
     <peak-bps>10</peak-bps>
     <average-bps>5</average-bps>
     <burst-size>8</burst-size>
   </network-shaper>
   <cpu-feature-mask-list>
     <cpu-feature-mask>
       <operation>add</operation>
       <info>
         <level>-2147483648</level>
             <vendor>amd</vendor>
         <eax></eax>
         <ebx></ebx>
         <ecx></ecx>
         <edx></edx>
       </info>
     </cpu-feature-mask>
     <cpu-feature-mask>
       <operation>add</operation>
       <info>
         <level>-2147483647</level>
         <vendor></vendor>
         <eax></eax>
         <ebx></ebx>
         <ecx></ecx>
         <edx></edx>
       </info>
     </cpu-feature-mask>
   </cpu-feature-mask-list>
     </config>
     <customization>
   <identity type='CustomizationSysprep'>
   <gui-unattended>
         <password>
           <value>abc123</value>
           <plain-text>true</plain-text>
         </password>
         <time-zone>123</time-zone>
     <auto-logon>false</auto-logon>
     <auto-logon-count>1</auto-logon-count>
   </gui-unattended>
   <user-data>
     <full-name>User1</full-name>
     <org-name>BMC</org-name>
     <computer-name>
       <name>AdapterDev</name>
     </computer-name>
     <product-id></product-id>
   </user-data>
       <gui-run-once>
         <command>C:\run.bat</command>
         <command>cmd.exe /c mkdir test</command>
       </gui-run-once>
   <identification>
     <join-workgroup>WORKGROUP</join-workgroup>
   </identification>
   <license-file-print-data>
     <auto-mode></auto-mode>
     <auto-users></auto-users>
   </license-file-print-data>
   <host-name>
     <name></name>
   </host-name>
   <domain></domain>
   </identity>
   <globalIPSettings>
     <dns-server-list>
       <dns-server-list>10.254.1.10</dns-server-list>
       <dns-server-list>10.254.1.11</dns-server-list>
     </dns-server-list>
     <dns-suffix-list>
       <dns-suffix-list>abc.com</dns-suffix-list>
       <dns-suffix-list>vmware.com</dns-suffix-list>
     </dns-suffix-list>
   </globalIPSettings>
   <nic-setting-map>
     <adapter>
       <ip type="CustomizationDhcpIpGenerator">
       <ipAddress></ipAddress>
       </ip>
       <subnet-mask>255.255.255.0</subnet-mask>
       <gateway>172.1.114.1</gateway>
       <dns-domain>abc.com</dns-domain>
     </adapter>
   </nic-setting-map>
     </customization>
   </spec>
 </parameters>
</vmware-infrastructure-request>

The following code sample shows a sample adapter request for the Clone VM With Custom Settings operation with thin provisioning for the virtual disk. 

Sample adapter request for the Clone VM With Custom Settings operation with thin provisioning

<vmware-infrastructure-request>
   <operation-type>Configure_Vm</operation-type>
   <operation-name>Clone_VM_With_Custom_Settings</operation-name>
   <parameters>
     <virtual-machine>win1</virtual-machine>
     <folder>TestVMFolder</folder>
     <datacenter>Test</datacenter>
     <name>win8</name>
     <spec>
       <power-on>false</power-on>
       <template>false</template>
       <location>
         <host-system>xyz.abc.com</host-system>
       </location>
       <config>
             <device-change-list>
       <device-change>
         <operation>add</operation>
         <device type="VirtualBusLogicController">
         <key>0</key>
         <bus-number>0</bus-number>
         <device>0</device>
         <shared-bus>noSharing</shared-bus>
         </device>
       </device-change>
       <device-change>
         <operation>add</operation>
         <fileOperation>create</fileOperation>
         <device type="VirtualDisk">
         <key>0</key>
         <backing type="VirtualDiskFlatVer2BackingInfo">
         <fileName>[dev1 disk2]</fileName>
         <diskMode>persistent</diskMode>
         <split>true</split>
         <writeThrough>true</writeThrough>
                 <thinProvisioned>true</thinProvisioned>
         </backing>
         <controllerKey>0</controllerKey>
         <unitNumber>-1</unitNumber>
         <capacityInKB>1024</capacityInKB>
         <shares>
           <shares>1024</shares>
           <level>low</level>
         </shares>
       </device>
     </device-change>
   </device-change-list>
     </config>
   </spec>
 </parameters>
</vmware-infrastructure-request>

The following code sample shows the response for the sample Clone VM With Custom Settings operation.

Sample adapter response for the Clone VM With Custom Settings operation

<vmware-infrastructure-response>
    <metadata>
       <status>success</status>
    </metadata>
    <CloneVM_TaskResponse>
       <Task>task-724</Task>
    </CloneVM_TaskResponse>
</vmware-infrastructure-response>

The following table describes the response element.

Adapter response element for the Clone VM With Custom Settings operation

Element

Definition

<Task>

Specifies the task ID of the submitted task

Use the task ID to obtain the status of the specified task.

For information about using the task ID to check the task status, see Request and response for the Retrieve_Task_Status operation.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*