Apache CloudStack 4.17.0.0 Root Admin API Reference
updateVirtualMachine
Updates properties of a virtual machine. The VM has to be stopped and restarted for the new properties to take effect. UpdateVirtualMachine does not first check whether the VM is stopped. Therefore, stop the VM manually before issuing this call.
Request parameters
| Parameter Name | Description | Required |
| id | The ID of the virtual machine | true |
| cleanupdetails | optional boolean field, which indicates if details should be cleaned up or not (if set to true, details removed for this resource, details field ignored; if false or not set, no action) | false |
| customid | an optional field, in case you want to set a custom id to the resource. Allowed to Root Admins only | false |
| details | Details in key/value pairs. 'extraconfig' is not allowed to be passed in details. | false |
| dhcpoptionsnetworklist | DHCP options which are passed to the VM on start up Example: dhcpoptionsnetworklist[0].dhcp:114=url&dhcpoptionsetworklist[0].networkid=networkid&dhcpoptionsetworklist[0].dhcp:66=www.test.com | false |
| displayname | user generated name | false |
| displayvm | an optional field, whether to the display the vm to the end user or not. | false |
| extraconfig | an optional URL encoded string that can be passed to the virtual machine upon successful deployment | false |
| group | group of the virtual machine | false |
| haenable | true if high-availability is enabled for the virtual machine, false otherwise | false |
| instancename | instance name of the user vm | false |
| isdynamicallyscalable | true if VM contains XS/VMWare tools inorder to support dynamic scaling of VM cpu/memory. This can be updated only when dynamic scaling is enabled on template, service offering and the corresponding global setting | false |
| name | new host name of the vm. The VM has to be stopped/started for this update to take affect | false |
| ostypeid | the ID of the OS type that best represents this VM. | false |
| securitygroupids | list of security group ids to be applied on the virtual machine. | false |
| securitygroupnames | comma separated list of security groups names that going to be applied to the virtual machine. Should be passed only when vm is created from a zone with Basic Network support. Mutually exclusive with securitygroupids parameter | false |
| userdata | an optional binary data that can be sent to the virtual machine upon a successful deployment. This binary data must be base64 encoded before adding it to the request. Using HTTP GET (via querystring), you can send up to 4KB of data after base64 encoding. Using HTTP POST(via POST body), you can send up to 1MB of data after base64 encoding.You also need to change vm.userdata.max.length value | false |
Response Tags
| Response Name | Description |
| id | the ID of the virtual machine |
| account | the account associated with the virtual machine |
| backupofferingid | the ID of the backup offering of the virtual machine |
| backupofferingname | the name of the backup offering of the virtual machine |
| bootmode | Guest vm Boot Mode |
| boottype | Guest vm Boot Type |
| cpunumber | the number of vCPUs this virtual machine is using |
| cpuspeed | the speed of each vCPU |
| cpuused | the amount of the vm's CPU currently used |
| created | the date when this virtual machine was created |
| details | Vm details in key/value pairs. |
| diskioread | the read (IO) of disk on the VM |
| diskiowrite | the write (IO) of disk on the VM |
| diskkbsread | the VM's disk read in KiB |
| diskkbswrite | the VM's disk write in KiB |
| diskofferingid | the ID of the disk offering of the virtual machine |
| diskofferingname | the name of the disk offering of the virtual machine |
| displayname | user generated name. The name of the virtual machine is returned if no displayname exists. |
| displayvm | an optional field whether to the display the vm to the end user or not. |
| domain | the name of the domain in which the virtual machine exists |
| domainid | the ID of the domain in which the virtual machine exists |
| forvirtualnetwork | the virtual network for the service offering |
| group | the group name of the virtual machine |
| groupid | the group ID of the virtual machine |
| guestosid | Os type ID of the virtual machine |
| haenable | true if high-availability is enabled, false otherwise |
| hostid | the ID of the host for the virtual machine |
| hostname | the name of the host for the virtual machine |
| hypervisor | the hypervisor on which the template runs |
| icon | Base64 string representation of the resource icon |
| instancename | instance name of the user vm; this parameter is returned to the ROOT admin only |
| isdynamicallyscalable | true if vm contains XS/VMWare tools inorder to support dynamic scaling of VM cpu/memory. |
| isodisplaytext | an alternate display text of the ISO attached to the virtual machine |
| isoid | the ID of the ISO attached to the virtual machine |
| isoname | the name of the ISO attached to the virtual machine |
| keypairs | ssh key-pairs |
| lastupdated | the date when this virtual machine was updated last time |
| memory | the memory allocated for the virtual machine |
| memoryintfreekbs | the internal memory (KiB) that's free in VM or zero if it can not be calculated |
| memorykbs | the memory used by the VM in KiB |
| memorytargetkbs | the target memory in VM (KiB) |
| name | the name of the virtual machine |
| networkkbsread | the incoming network traffic on the VM in KiB |
| networkkbswrite | the outgoing network traffic on the host in KiB |
| osdisplayname | OS name of the vm |
| ostypeid | OS type id of the vm |
| password | the password (if exists) of the virtual machine |
| passwordenabled | true if the password rest feature is enabled, false otherwise |
| pooltype | the pool type of the virtual machine |
| project | the project name of the vm |
| projectid | the project id of the vm |
| publicip | public IP address id associated with vm via Static nat rule |
| publicipid | public IP address id associated with vm via Static nat rule |
| readonlydetails | List of read-only Vm details as comma separated string. |
| receivedbytes | the total number of network traffic bytes received |
| rootdeviceid | device ID of the root volume |
| rootdevicetype | device type of the root volume |
| sentbytes | the total number of network traffic bytes sent |
| serviceofferingid | the ID of the service offering of the virtual machine |
| serviceofferingname | the name of the service offering of the virtual machine |
| servicestate | State of the Service from LB rule |
| state | the state of the virtual machine |
| templatedisplaytext | an alternate display text of the template for the virtual machine |
| templateid | the ID of the template for the virtual machine. A -1 is returned if the virtual machine was created from an ISO file. |
| templatename | the name of the template for the virtual machine |
| userid | the user's ID who deployed the virtual machine |
| username | the user's name who deployed the virtual machine |
| vgpu | the vGPU type used by the virtual machine |
| zoneid | the ID of the availablility zone for the virtual machine |
| zonename | the name of the availability zone for the virtual machine |
| affinitygroup(*) | list of affinity groups associated with the virtual machine |
| id | the ID of the affinity group |
| account | the account owning the affinity group |
| description | the description of the affinity group |
| domain | the domain name of the affinity group |
| domainid | the domain ID of the affinity group |
| name | the name of the affinity group |
| project | the project name of the affinity group |
| projectid | the project ID of the affinity group |
| type | the type of the affinity group |
| virtualmachineIds | virtual machine IDs associated with this affinity group |
| nic(*) | the list of nics associated with vm |
| id | the ID of the nic |
| adaptertype | Type of adapter if available |
| broadcasturi | the broadcast uri of the nic |
| deviceid | device id for the network when plugged into the virtual machine |
| extradhcpoption | the extra dhcp options on the nic |
| gateway | the gateway of the nic |
| ip6address | the IPv6 address of network |
| ip6cidr | the cidr of IPv6 network |
| ip6gateway | the gateway of IPv6 network |
| ipaddress | the ip address of the nic |
| ipaddresses | IP addresses associated with NIC found for unmanaged VM |
| isdefault | true if nic is default, false otherwise |
| isolatedpvlan | the isolated private VLAN if available |
| isolatedpvlantype | the isolated private VLAN type if available |
| isolationuri | the isolation uri of the nic |
| macaddress | true if nic is default, false otherwise |
| netmask | the netmask of the nic |
| networkid | the ID of the corresponding network |
| networkname | the name of the corresponding network |
| nsxlogicalswitch | Id of the NSX Logical Switch (if NSX based), null otherwise |
| nsxlogicalswitchport | Id of the NSX Logical Switch Port (if NSX based), null otherwise |
| secondaryip | the Secondary ipv4 addr of nic |
| traffictype | the traffic type of the nic |
| type | the type of the nic |
| virtualmachineid | Id of the vm to which the nic belongs |
| vlanid | ID of the VLAN/VNI if available |
| securitygroup(*) | list of security groups associated with the virtual machine |
| id | the ID of the security group |
| account | the account owning the security group |
| description | the description of the security group |
| domain | the domain name of the security group |
| domainid | the domain ID of the security group |
| name | the name of the security group |
| project | the project name of the group |
| projectid | the project id of the group |
| virtualmachinecount | the number of virtualmachines associated with this securitygroup |
| virtualmachineids | the list of virtualmachine ids associated with this securitygroup |
| egressrule(*) | the list of egress rules associated with the security group |
| account | account owning the security group rule |
| cidr | the CIDR notation for the base IP address of the security group rule |
| endport | the ending IP of the security group rule |
| icmpcode | the code for the ICMP message response |
| icmptype | the type of the ICMP message response |
| protocol | the protocol of the security group rule |
| ruleid | the id of the security group rule |
| securitygroupname | security group name |
| startport | the starting IP of the security group rule |
| tags(*) | the list of resource tags associated with the rule |
| ingressrule(*) | the list of ingress rules associated with the security group |
| account | account owning the security group rule |
| cidr | the CIDR notation for the base IP address of the security group rule |
| endport | the ending IP of the security group rule |
| icmpcode | the code for the ICMP message response |
| icmptype | the type of the ICMP message response |
| protocol | the protocol of the security group rule |
| ruleid | the id of the security group rule |
| securitygroupname | security group name |
| startport | the starting IP of the security group rule |
| tags(*) | the list of resource tags associated with the rule |
| tags(*) | the list of resource tags associated with the rule |
| account | the account associated with the tag |
| customer | customer associated with the tag |
| domain | the domain associated with the tag |
| domainid | the ID of the domain associated with the tag |
| key | tag key name |
| project | the project name where tag belongs to |
| projectid | the project id the tag belongs to |
| resourceid | id of the resource |
| resourcetype | resource type |
| value | tag value |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |