Skip to Content

Update VM Configuration operation

The Update VM Configuration operation modifies one or more configuration parameters on a virtual machine. This operation can be used to add or remove a hard disk, CD-ROM drive, or an ethernet adapter from the specified virtual machine.

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.

Warning

Note

Only one hard Disk, CD-ROM, or an ethernet adapter device can be added with one method call of this operation.

The following table describes the elements for this request.

Adapter request elements for the Update_VM_Configuration operation

Element

Definition

Required

<operation-type>

Defines the type of the operation: Configure_Vm

Yes

<operation-name>

Defines the name of the operation: Update_VM_Configuration

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>

Contains the name of the virtual machine whose configuration details are to be updated

Yes

<name>

Specifies the display name of the virtual machine

No

<version>

Specifies the version string for the virtual machine

No

guest-id>

Specifies the short guest operating system identifier

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

No

<annotation>

Specifies the user-specified description of the virtual machine

No

<tools>

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

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

No

<flags>

Encapsulates the flag settings for a virtual machine

For more information about the child elements, see flags.

No

<console-preferences>

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

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

No

<power-op-info>

Specifies the configuration for default power operations

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

No

<num-cpus>

Specifies the number of virtual processors in a virtual machine

No

<memory-mb>

Specifies the amount of memory, in MB, for a virtual machine

No

<memory-hot-add-enabled>

Indicates whether memory can be added to the virtual machine while it is running

You can set this attribute only when the virtual machine is powered off.

If you do not specify a value, there is no default, and the status of <memory-hot-add-enabled> remains unaltered. In other words, if <memory-hot-add-enabled> was enabled before the update, it would continue to be enabled. If <memory-hot-add-enabled> was disabled before the update, it would continue to be disabled.

Valid values: true, false

No

<cpu-hot-add-enabled>

Indicates whether virtual processors can be added to the virtual machine while it is running

You can set this attribute only when the virtual machine is powered off.

If you do not specify a value, there is no default, and the status of <cpu-hot-add-enabled> remains unaltered. In other words, if <cpu-hot-add-enabled> was enabled before the update, it would continue to be enabled. If <cpu-hot-add-enabled> was disabled before the update, it would continue to be disabled.

Valid values: true, false

No

<cpu-hot-remove-enabled>

Indicates whether virtual processors can be removed from the virtual machine while it is running

You can set this attribute only when the virtual machine is powered off.

If you do not specify a value, there is no default, and the status of <cpu-hot-remove-enabled> remains unaltered. In other words, if <cpu-hot-remove-enabled> was enabled before the update, it would continue to be enabled. If <cpu-hot-remove-enabled> was disabled before the update, it would continue to be disabled.

Valid values: true, false

No

<device-change-list>

Specifies the set of virtual devices being added, removed, or edited by the configuration operation

Operation supported: add, remove, edit

For more information about the child elements, see:

No

<cpu-allocation>

Specifies the resource limits for CPU

For information about child elements, see cpu-allocation.

No

<memory-allocation>

Specifies the resource limits for memory

For information about child elements, see memory-allocation.

No

<cpu-affinity>

Specifies the list of nodes (processors for CPU) that can be used by the virtual machine

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

No

<memory-affinity>

Specifies the list of nodes (NUMA nodes for memory) that can be used by the virtual machine

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

 

<network-shaper>

Specifies the network traffic shaping specification

Traffic shaping is used to configure the network utilization characteristics of a virtual machine.

For information about child elements, see network-shaper.

No

<cpu-feature-mask-list>

Specifies the CPU feature compatibility masks

For information about these child elements, see cpu-feature-mask-list.

No

The following code sample shows a sample adapter request for the Update VM Configuration operation to add a hard disk, a CD ROM, and an ethernet adapter.

Sample adapter request for the Update VM Configuration operation

<vmware-infrastructure-request>
    <operation-type>Configure_Vm</operation-type>
    <operation-name>Update_VM_Configuration</operation-name>
   <soap-url></soap-url>
   <transport></transport>
    <user-name></user-name>
    <password></password>
    <parameters>
        <virtual-machine>winSix</virtual-machine>
        <spec>
            <name>winSix</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>true</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>
           <memory-hot-add-enabled>true</memory-hot-add-enabled>
           <cpu-hot-add-enabled>true</cpu-hot-add-enabled>
           <cpu-hot-remove-enabled>true</cpu-hot-remove-enabled>
            <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>
                    <file-operation>create</file-operation>
   <device type="VirtualDisk">
                   <key>0</key>
                <backing type="VirtualDiskFlatVer2BackingInfo">
                        <file-name>[dev15 disk2]</file-name>
                        <disk-mode>persistent</disk-mode>
                        <split>true</split>
                        <write-through>true</write-through>
                        <thin-provisioned>false</thin-provisioned>
                </backing>
                    <controller-key>0</controller-key>
                    <unit-number>-1</unit-number>
                    <capacity-inKB>1024</capacity-inKB>
                    <shares>
                        <shares>1024</shares>
                            <level>low</level>
                        </shares>
                    </device>
                </device-change>
                <device-change>
                <operation>add</operation>
                <device>
                    <key></key>
                    <device-info>
                        <label>Disk3</label>
                        <summary></summary>
                    </device-info>
                    <controller-key></controller-key>
                    <unit-number></unit-number>
                </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-list>
        </spec>
    </parameters>
</vmware-infrastructure-request>

The following code sample shows the response for the sample Update VM Configuration operation.

Sample adapter response for the Update VM Configuration operation

<vmware-infrastructure-response>
     <metadata>
     <status>success</status>
     </metadata>
     <ReconfigVM_TaskResponse>
         <Task>task-727</Task>
     </ReconfigVM_TaskResponse>
     </vmware-infrastructure-response>

The following table describes the response element.

Adapter response element for the Update VM Configuration 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.

The following code sample shows a sample adapter request for the Update VM Configuration operation to remove a hard disk, a CD ROM, and an ethernet adapter.

Sample adapter request for the Update VM Configuration operation

<vmware-infrastructure-request>
    <operation-type>Configure_Vm</operation-type>
    <operation-name>Update_VM_Configuration</operation-name>
   <soap-url></soap-url>
   <transport></transport>
    <user-name></user-name>
    <password></password>
    <parameters>
        <virtual-machine>winSix</virtual-machine>
        <spec>
            <name>winSix</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>true</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>remove</operation>
                    <file-operation>destroy</file-operation>
                    <device type="VirtualDisk">
                        <disk-name>Hard Disk 1</disk-name>
                    </device>
                </device-change>
                <device-change>
                <operation>remove</operation>
                <device>
                    <cdrom>CD/DVD drive 3</cdrom>
                </device>
                </device-change>
                <device-change>
                <operation>remove</operation>
                <device>
                    <ethernet-adapter>Network Adapter 1</ethernet-adapter>
                </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>

The following code sample shows a sample adapter request for the Update VM Configuration operation to update a SCSI controller configuration.

 

Sample adapter request for the Update VM Configuration operation

<vmware-infrastructure-request>
    <operation-type>Configure_Vm</operation-type>
    <operation-name>Update_VM_Configuration</operation-name>
   <soap-url></soap-url>
   <transport></transport>
    <user-name></user-name>
    <password></password>
    <parameters>
        <virtual-machine>winSix</virtual-machine>
        <spec>
            <device-change-list>
                <device-change>
                    <operation>edit</operation>
                    <device type="VirtualLsiLogicController">
                        <scsi-controller>SCSI Controller 0</scsi-controller>
                        <bus-number>0</bus-number>
                        <shared-bus>physicalSharing</shared-bus>
                    </device>
                </device-change>
            </device-change-list>
        </spec>
    </parameters>
</vmware-infrastructure-request>

The following code sample shows a sample adapter request for the Update VM Configuration operation to update an ethernet adapter configuration.

Sample adapter request for the Update VM Configuration operation

<vmware-infrastructure-request>
    <operation-type>Configure_Vm</operation-type>
    <operation-name>Update_VM_Configuration</operation-name>
   <soap-url></soap-url>
   <transport></transport>
    <user-name></user-name>
    <password></password>
    <parameters>
        <virtual-machine>winSix</virtual-machine>
        <spec>
            <device-change-list>
                <device-change>
                    <operation>edit</operation>
                    <device type="VirtualPCNet32">
                        <ethernet-adapter>Network Adapter 1</ethernet-adapter>
                        <backing type="VirtualEthernetCardNetworkBackingInfo">
                            <device-name>DummyNetwork</device-name>
                        </backing>
                        <connectable>
                            <start-connected>true</start-connected>
                            <allow-guest-control>true</allow-guest-control>
                            <connected>true</connected>
                        </connectable>
                        <address-type>assigned</address-type>
                        <mac-address></mac-address>
                        <wake-on-lan-enabled>false</wake-on-lan-enabled>
                    </device>
                </device-change>
            </device-change-list>
        </spec>
    </parameters>
</vmware-infrastructure-request>

 

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

BMC Atrium Orchestrator Content 20.15.02