Customize VM operation

The Customize VM operation customizes a virtual machine's guest operating system.

The following table describes the elements for this request:

Adapter request elements for the Customize VM operation

Element

Definition

Required

<operation-type>

Defines the type of the operation: Configure_Vm

Yes

<operation-name>

Defines the name of the operation: Customize_VM

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 specified, 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 VM whose guest OS is to be customized

Yes

<spec>

Contains child elements that specify information about the VM

Yes

<identity>

Specifies the network identity and settings, similar to Microsoft's Sysprep tool; contains the type attribute that is a Sysprep, LinuxPrep, or SysprepText object.

Valid values: CustomizationLinuxPrep, CustomizationSysPrep (default)

No

<hostName>

Contains the <name> child element; contains the type attribute

Conditional; valid only if the <identity-type> element is set to CustomizationLinuxPrep

<name>

Specifies the computer name of the virtual machine (not running on Windows)

Conditional; valid only if the <identity-type> element is set to CustomizationLinuxPrep

<domain>

Specifies the fully-qualified domain name

Conditional; valid only if the <identity-type> element is set to CustomizationLinuxPrep

<globalIPSettings>

Contains the <dns-server-list> and the <dns-suffix-list> elements and their child elements

No

<dns-server-list>

Is a child element of the <globalIPSettings> element that specifies the list of DNS servers for a virtual network adapter with a static IP address

If <dns-server-list> is empty, the guest operating system uses a DHCP server to get its DNS server settings. These settings configure the virtual machine to use the specified DNS servers.

These DNS server settings are listed in the order of preference.

Sample format:

<dns-server-list>
 <dns-server-list></dns-server-list>
 <dns-server-list></dns-server-list>
</dns-server-list>

No

<dns-suffix-list>

Specifies the list of name resolution suffixes for the virtual network adapter

The <dns-suffix-list> applies to both Windows and Linux guest customization. For Linux, this setting is global; for Windows, this setting is listed for each adapter.

Sample format:

<dns-suffix-list>
 <dns-suffix-list></dns-suffix-list>
 <dns-suffix-list></dns-suffix-list>
</dns-suffix-list>

No

<nic-setting-map>

Contains the <adapter> element which in turn contains the following virtual network adapter elements that must be customized:

  • <ip>
  • <subnet-mask>
  • <gateway>
  • <dns-server-list> and its child elements
  • <dns-domain>

    Note: To use multiple <nic-setting-map> elements, enclose them within a <nic-setting-map-list> element.

No

<ip>

Contains the <ipAddress> element; contains the type attribute that specifies the unique IP address for the virtual network adapter

Sample format:

<ip type="">
 <ipAddress></ipAddress>
</ip>


Note

<ipAddress> is valid only when the value for <ip type> is "CustomizationFixedIp".


Valid values: CustomizationFixedIp, CustomizationDhcpIpGenerator

No

<subnet-mask>

Specifies the subnet mask for the virtual network adapter

No

<gateway>

Specifies a list of gateways in the order of preference for a virtual network adapter with a static IP address

No

<dns-server-list>

Is a child element of the <nic-setting-map> element that specifies the list of DNS servers for a virtual network adapter with a static IP address

If <dns-server-list> is empty, the guest operating system uses a DHCP server to get its DNS server settings. These settings configure the virtual machine to use the specified DNS servers.

These DNS server settings are listed in the order of preference. If you specify the <dns-server-list> element, you need to set dnsFromDhcp (Where?) to false.

Sample format:

<dns-server-list>
 <dns-server-list></dns-server-list>
 <dns-server-list></dns-server-list>
</dns-server-list>

No

<dns-domain>

Specifies a DNS domain suffix such as vmware.com

Valid value: Any string

No

<primary-wins>

Specifies the IP address of the primary Windows Internet Name Service (WINS) server

This property is ignored for Linux guest operating systems.

No

<secondary-wins>

Specifies the IP address of the secondary WINS server

This property is ignored for Linux guest operating systems.

No

<password>

Specifies the new administrator password for the virtual machine

You can use the <password> element only if the following conditions are satisfied:

  • the CustomizationSysprep data object is used
  • the password is used for auto-logon purposes

No; valid only if the <identity-type>
element is set to CustomizationSysprep

<value>

Contains the password

No

<plain-text>

Specifies whether the password is encrypted

Valid values: true (plain text), false (encrypted) (default)

No

<time-zone>

Specifies the time zone for the new virtual machine

The numbers correspond to the time zones listed in the Sysprep documentation on Microsoft Technet.

Valid value: Any integer

No; valid only if the <identity-type> element is set to "CustomizationSysprep""

<auto-logon>

Specifies whether the computer automatically logs you on as an administrator

Valid value: true, false

No; valid only if the <identity-type> element is set to CustomizationSysprep

<auto-logon-count>

Specifies the number of times the virtual machine should automatically log on as an administrator if the <auto-logon> flag is set.

Set <auto-logon-count> to 1.

However, if your setup requires a number of reboots, you might need to increase the value of <auto-logon-count>. This number is determined by the list of commands executed by the GuiRunOnce command.

Valid value: Any integer

No; valid only if the <identity-type> element is set to CustomizationSysprep

<full-name>

Specifies the full name of the user

Valid value: Any string

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<computer-name>

Specifies the computer name of the Microsoft Windows virtual machine
Sample format:

<computer-name>
 <name></name>
</computer-name>

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<org-name>

Specifies the name of the user's organization

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<product-id>

Specifies the valid serial number that Microsoft Sysprep requires in the answer file when mini-setup, an operating system setup runs

The serial number is ignored if the original guest operating system isinstalled using a volume-licensed CD.

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<command>

Specifies the command to be executed at first user logon after guest customization.

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<join-workgroup>

Specifies the work group that the virtual machine must join
If you specify a value for <join-workgroup>, the <domain-admin> and <domain-admin-password> elements must be empty.

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<join-domain>

Specifies the domain that the virtual machine must join

If you specify a value for <join-domain, you must also specify values for <domain-admin> and <domain-admin-password> and the work group name must be empty. (Where is the work group name specified)

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<domain-admin>

Specifies the domain user account to be used for authentication if the virtual machine joins a domain

The user does not need to be a domain administrator, but the account must have the privileges required to add computers to the domain.

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<domain-admin-password>

Specifies the password for the domain user account to be used for authentication if the virtual machine joins a domain

Sample format:

<domain-admin-password>
 <value></value>
 <plain-text></plain-text>
</domain-admin-password>

Conditional; valid only if the <identity-type> element is set to CustomizationSysprep

<value>

Contains the password

No

<plain-text>

Specifies whether the password is encrypted

Valid values: true (plain text), false (encrypted) (default)

No

<license-file-print-data>

Specifies the object representation of the Sysprep LicenseFilePrintData key

<license-file-print-data> is required only for a Windows 2000 server or a Windows 2003 server.

<license-file-print-data> contains the <auto-mode> and <auto-users> child elements.

No

<auto-mode>

Specifies the licensing mode for the server

Valid values: perSeat, perServer

No; valid only if the <identity-type> element is set to customizationSysprep

<auto-users>

Specifies the key that is valid only if the value of the <auto-mode> element is "PerServer"

The integer value specifies the number of client licenses purchased for the VMware VirtualCenter server installed.

No; valid only if the <identity-type> element is set to CustomizationSysprep

The following code sample shows a sample adapter request for the Customize VM operation for customizing a Linux VM:

Sample adapter request for the Customize VM operation for customizing a Linux VM

<vmware-infrastructure-request>
   <operation-type>Basic_Vm</operation-type>
   <operation-name>Customize_VM</operation-name>
   <parameters>
     <virtual-machine>customizevmtest</virtual-machine>
     <spec>
       <identity type='CustomizationLinuxPrep'>
           <hostName type="CustomizationFixedName">
               <name>rhel5vmbmc\</name>
           </hostName>
           <domain>bmc.com</domain>
       </identity>
     <globalIPSettings>
       <dns-server-list>
           <dns-server-list>172.16.6.2</dns-server-list>
           <dns-server-list>172.16.6.3</dns-server-list>
       </dns-server-list>
       <dns-suffix-list>
           <dns-suffix-list>bmc.com</dns-suffix-list>
           <dns-suffix-list>bmc.com</dns-suffix-list>
       </dns-suffix-list>
      </globalIPSettings>
      <nic-setting-map>
        <adapter>
          <ip type="CustomizationDhcpIpGenerator"></ip>
          <subnet-mask>255.255.255.0</subnet-mask>
          <gateway>172.16.49.1</gateway>
          <dns-server-list>
            <dns-server-list>172.16.6.3</dns-server-list>
            <dns-server-list>172.16.6.2</dns-server-list>
          </dns-server-list>
          <dns-domain>synapse.com</dns-domain>
        </adapter>
      </nic-setting-map>
     </spec>
   </parameters>
</vmware-infrastructure-request>  

The following code sample shows a sample adapter request for the Customize VM operation for a Windows VM:

Sample adapter request for the Customize VM operation for a Windows VM

<vmware-infrastructure-request>
 <operation-type>Configure_Vm</operation-type>
 <operation-name>Customize_VM</operation-name>
 <parameters>
   <virtual-machine>testwin2008</virtual-machine>
   <spec>
     <identity type='CustomizationSysprep'>
       <gui-unattended>
         <password>
           <value>BmcTest</value>
           <plain-text>true</plain-text>
         </password>
        <time-zone>185</time-zone>
        <auto-logon>false</auto-logon>
        <auto-logon-count>0</auto-logon-count>
      </gui-unattended>
       <user-data>
         <full-name>AODev</full-name>
         <org-name>BMC</org-name>
         <computer-name>
           <name>AdapterDev</name>
         </computer-name>
         <product-id></product-id>
       </user-data>
       <gui-run-once>
         <command>dir</command>
       </gui-run-once>
       <identification>
         <join-workgroup>AOWORKGROUP</join-workgroup>
         <join-domain>bmc.com</join-domain>
         <domain-admin>administrator</domain-admin>
         <domain-admin-password>
           <value>TestPwd</value>
           <plain-text>true</plain-text>
         </domain-admin-password>
       </identification>
     </identity>
     <globalIPSettings>
       <dns-server-list>
         <dns-server-list>10.128.248.2</dns-server-list>
         <dns-server-list>10.128.248.3</dns-server-list>
       </dns-server-list>
       <dns-suffix-list>
         <dns-suffix-list>bmc.com</dns-suffix-list>
       </dns-suffix-list>
     </globalIPSettings>
     <nic-setting-map>
       <adapter>
         <ip type="CustomizationDhcpIpGenerator"></ip>
         <subnet-mask>255.255.255.0</subnet-mask>
         <gateway>10.128.248.1</gateway>
         <dns-server-list>
           <dns-server-list>10.128.248.4</dns-server-list>
           <dns-server-list>10.128.248.5</dns-server-list>
         </dns-server-list>
         <dns-domain>bmc.com</dns-domain>
         <primary-wins>10.128.248.111</primary-wins>
         <secondary-wins>10.128.248.222</secondary-wins>
       </adapter>
     </nic-setting-map>
   </spec>
 </parameters>
</vmware-infrastructure-request>

The following code sample shows the response for the sample Customize VM operation:

Sample adapter response for the Customize_ VM operation


<vmware-infrastructure-response>
<metadata>
 <status>success</status>
</metadata>
<CustomizeVM_TaskResponse>
 <Task>task-1564</Task>
</CustomizeVM_TaskResponse>
</vmware-infrastructure-response>

 

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