REST API - set

vcenter vm guest customization: set

Applies a customization specification in spec on the virtual machine in vm. This operation only sets the specification settings for the virtual machine. The actual customization happens inside the guest when the virtual machine is powered on. If spec has unset values, then any pending customization settings for the virtual machine are cleared. If there is a pending customization for the virtual machine and spec has valid content, then the existing customization setting will be overwritten with the new settings. This operation was added in vSphere API 7.0.0.0.

Request:

HTTP request

PUT https://{server}/rest/vcenter/vm/{vm}/guest/customization

Path Parameters

Name	Type	Description
Required
vm	string	The unique identifier of the virtual machine that needs to be customized.

Request Body Structure:

{
    "spec" : {
        "name" : "string",
        "spec" : {
            "interfaces" : [
                {
                    "adapter" : {
                        "ipv4" : {
                            "gateways" : [
                                "string",
                                "string"
                            ],
                            "prefix" : 1,
                            "ip_address" : "string",
                            "type" : "DHCP"
                        },
                        "ipv6" : {
                            "gateways" : [
                                "string",
                                "string"
                            ],
                            "ipv6" : [
                                {
                                    "prefix" : 1,
                                    "ip_address" : "string"
                                },
                                {
                                    "prefix" : 1,
                                    "ip_address" : "string"
                                }
                            ],
                            "type" : "DHCP"
                        },
                        "windows" : {
                            "dns_domain" : "string",
                            "wins_servers" : [
                                "string",
                                "string"
                            ],
                            "net_BIOS_mode" : "USE_DHCP",
                            "dns_servers" : [
                                "string",
                                "string"
                            ]
                        }
                    },
                    "mac_address" : "string"
                },
                {
                    "adapter" : {
                        "ipv4" : {
                            "gateways" : [
                                "string",
                                "string"
                            ],
                            "prefix" : 1,
                            "ip_address" : "string",
                            "type" : "DHCP"
                        },
                        "ipv6" : {
                            "gateways" : [
                                "string",
                                "string"
                            ],
                            "ipv6" : [
                                {
                                    "prefix" : 1,
                                    "ip_address" : "string"
                                },
                                {
                                    "prefix" : 1,
                                    "ip_address" : "string"
                                }
                            ],
                            "type" : "DHCP"
                        },
                        "windows" : {
                            "dns_domain" : "string",
                            "wins_servers" : [
                                "string",
                                "string"
                            ],
                            "net_BIOS_mode" : "USE_DHCP",
                            "dns_servers" : [
                                "string",
                                "string"
                            ]
                        }
                    },
                    "mac_address" : "string"
                }
            ],
            "global_DNS_settings" : {
                "dns_suffix_list" : [
                    "string",
                    "string"
                ],
                "dns_servers" : [
                    "string",
                    "string"
                ]
            },
            "configuration_spec" : {
                "windows_config" : {
                    "reboot" : "REBOOT",
                    "sysprep_xml" : "string",
                    "sysprep" : {
                        "domain" : {
                            "workgroup" : "string",
                            "domain_password" : "secret string",
                            "domain_username" : "string",
                            "domain" : "string",
                            "type" : "WORKGROUP"
                        },
                        "gui_run_once_commands" : [
                            "string",
                            "string"
                        ],
                        "user_data" : {
                            "computer_name" : {
                                "prefix" : "string",
                                "type" : "FIXED",
                                "fixed_name" : "string"
                            },
                            "full_name" : "string",
                            "product_key" : "string",
                            "organization" : "string"
                        },
                        "gui_unattended" : {
                            "password" : "secret string",
                            "auto_logon_count" : 1,
                            "auto_logon" : true,
                            "time_zone" : 1
                        }
                    }
                },
                "linux_config" : {
                    "hostname" : {
                        "prefix" : "string",
                        "type" : "FIXED",
                        "fixed_name" : "string"
                    },
                    "script_text" : "string",
                    "domain" : "string",
                    "time_zone" : "string"
                }
            }
        }
    }
}

Request Body Parameters:

Name	Type	Description
bold = required
spec	set_spec	The customization settings to be applied to the guest operating system.
spec.name	string	The name of the customization specification that has be retrieved from the virtual center inventory and applied for the virtual machine. Either one of `name` or `spec` or none of them should be specified. This attribute was added in vSphere API 7.0.0.0. Optional. If unset and `spec` is also unset when executing set operationg, then any pending customization for the virtual machine will be cleared.
spec.spec	customization_spec	The customization specification that has to be applied for the virtual machine. Either one of `name` or `spec` or none of them should be specified. This attribute was added in vSphere API 7.0.0.0. Optional. If unset and `name` is also unset when executing set operationg, then any pending customization for the virtual machine will be cleared.
spec.spec.configuration_spec	configuration_spec	Settings to be applied to the guest during the customization. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config	windows_configuration	Guest customization specification for a Windows guest operating system. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, vcenter.guest.configuration_spec.linux_config must be set. Otherwise, an appropriate fault will be thrown.
spec.spec.configuration_spec.windows_config.reboot	string	A value specifying the action that should be taken after customization. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, the REBOOT option will be chosen.
spec.spec.configuration_spec.windows_config.sysprep	windows_sysprep	Customization settings like user details, administrator details, etc for the windows guest operating system. Exactly one of `sysprep` or `sysprep_xml` must be specified. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, sysprep settings will not be applied to the windows guest operating system.
spec.spec.configuration_spec.windows_config.sysprep.gui_run_once_commands	string[]	A list of commands to run at first user logon, after customizing the guest. These commands are directly mapped to the GuiRunOnce key in the sysprep.xml answer file. These commands are transferred into the sysprep.xml file that VirtualCenter stores on the target virtual disk. For more information about performing unattended installation, check https://technet.microsoft.com/en-us/library/cc771830(v=ws.10).aspx The commands listed here ar executed when a user logs on the first time after customization completes. The logon may be driven by vcenter.guest.gui_unattended.auto_logon setting. These commands are directly mapped to the GuiRunOnce key in the. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, no commands are run.
spec.spec.configuration_spec.windows_config.sysprep.user_data	user_data	Personal data pertaining to the owner of the virtual machine. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.user_data.computer_name	hostname_generator	The computer name of the (Windows) virtual machine. A computer name may contain letters (A-Z), numbers(0-9) and hyphens (-) but no spaces or periods (.). The name may not consist entirely of digits. A computer name is restricted to 15 characters in length. If the computer name is longer than 15 characters, it will be truncated to 15 characters. Check vcenter.guest.hostname_generator for various options. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.user_data.computer_name.type	string	The type of the Name Generator. This attribute was added in vSphere API 7.0.0.0. Specifies different types of Name Generators. This enumeration was added in vSphere API 7.0.0.0. Value is one of: FIXED: Specifies that a fixed name should be used for the hostname for the virtual machine during the customization. This constant was added in vSphere API 7.0.0.0. PREFIX: Specifies that a unique name should be generated by concatenating the base string with a number including the network name of the guest. Virtual machine names are unique across the set of hosts and virtual machines known to the VirtualCenter instance. VirtualCenter tracks the network names of virtual machines as well as hosts. VMware Tools runs in a guest operating system and reports information to VirtualCenter. . This constant was added in vSphere API 7.0.0.0. VIRTUAL_MACHINE: Specifies that the VirtualCenter should generate a virtual machine name. The name is generated from a base prefix comprising the virtual machine entity name. A number is appended, if necessary, to make it unique. Virtual machine names are unique across the set of hosts and virtual machines known to the VirtualCenter instance. VirtualCenter tracks the network names of the virtual machines as well as hosts. VMware Tools runs in a guest operating system and reports information to VirtualCenter, including the network name of the guest. . This constant was added in vSphere API 7.0.0.0. USER_INPUT_REQUIRED: Indicates that the host name is not specified in advance. The user must provide a valid value when the actual customization spec is applied to a virtual machine. This constant was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.user_data.computer_name.fixed_name	string	The virtual machine name specified by the client. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value FIXED. This field is optional and it is only relevant when the value of `type` is FIXED.
spec.spec.configuration_spec.windows_config.sysprep.user_data.computer_name.prefix	string	Base prefix, to which a unique number is appended. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value PREFIX. This field is optional and it is only relevant when the value of `type` is PREFIX.
spec.spec.configuration_spec.windows_config.sysprep.user_data.full_name	string	Full name of the end user. Note that this is not the username but full name specified in "Firstname Lastname" format. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.user_data.organization	string	Name of the organization that owns the computer. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.user_data.product_key	string	The product Key to use for activating Windows guest operating system. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.domain	domain	Information needed to join a workgroup or domain. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, the guest will not be joined to any workgroup or a domain.
spec.spec.configuration_spec.windows_config.sysprep.domain.type	string	The type of network to join after the customization. This attribute was added in vSphere API 7.0.0.0. Defines the types of network the virtual machine should join to after the customization is completed. This enumeration was added in vSphere API 7.0.0.0. Value is one of: WORKGROUP: The virtual machine should be be joined to a workgroup. This constant was added in vSphere API 7.0.0.0. DOMAIN: The virtual machine should be be joined to a domain. This constant was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.domain.workgroup	string	The workgroup that the virtual machine should join. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value WORKGROUP. This field is optional and it is only relevant when the value of `type` is WORKGROUP.
spec.spec.configuration_spec.windows_config.sysprep.domain.domain	string	The domain to which the virtual machine should be joined. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value DOMAIN. This field is optional and it is only relevant when the value of `type` is DOMAIN.
spec.spec.configuration_spec.windows_config.sysprep.domain.domain_username	string	The domain user that has permission to join the domain after virtual machine is joined. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value DOMAIN. This field is optional and it is only relevant when the value of `type` is DOMAIN.
spec.spec.configuration_spec.windows_config.sysprep.domain.domain_password	secret	The domain user password that has permission to join the vcenter.guest.domain.domain_username after customization. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value DOMAIN. This field is optional and it is only relevant when the value of `type` is DOMAIN.
spec.spec.configuration_spec.windows_config.sysprep.gui_unattended	gui_unattended	Information related to unattended installation. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.gui_unattended.auto_logon	boolean	Flag to determine whether or not the machine automatically logs on as Administrator. See the vcenter.guest.gui_unattended.password property. If vcenter.guest.gui_unattended.auto_logon flag is set, then vcenter.guest.gui_unattended.password must not be unset or the guest customization will fail. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.gui_unattended.auto_logon_count	long	If the vcenter.guest.gui_unattended.auto_logon flag is set, then this property specifies the number of times the machine should automatically log on as Administrator. Generally it should be 1, but if the setup requires a number of reboots, you may want to increase it. This number may be determined by the list of commands. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep.gui_unattended.password	secret	The new administrator password for the machine. To specify that the password should be set to blank (that is, no password), leave it unset. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, blank password will be used.
spec.spec.configuration_spec.windows_config.sysprep.gui_unattended.time_zone	long	The time zone index for the virtual machine. Numbers correspond to time zones at https://support.microsoft.com/en-us/help/973627/microsoft-time-zone-index-values. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.windows_config.sysprep_xml	string	All settings specified in a XML format. This is the content of a typical answer.xml file that is used by System administrators during the Windows image customization. Check https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/update-windows-settings-and-scripts-create-your-own-answer-file-sxs Exactly one of `sysprep` or `sysprep_xml` must be specified. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, sysprep settings will not be applied to the windows guest operating system.
spec.spec.configuration_spec.linux_config	linux_configuration	Guest customization specification for a linux guest operating system. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, vcenter.guest.configuration_spec.windows_config must be set. Otherwise, an appropriate fault will be thrown.
spec.spec.configuration_spec.linux_config.hostname	hostname_generator	The network host name of the Linux virtual machine. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.linux_config.hostname.type	string	The type of the Name Generator. This attribute was added in vSphere API 7.0.0.0. Specifies different types of Name Generators. This enumeration was added in vSphere API 7.0.0.0. Value is one of: FIXED: Specifies that a fixed name should be used for the hostname for the virtual machine during the customization. This constant was added in vSphere API 7.0.0.0. PREFIX: Specifies that a unique name should be generated by concatenating the base string with a number including the network name of the guest. Virtual machine names are unique across the set of hosts and virtual machines known to the VirtualCenter instance. VirtualCenter tracks the network names of virtual machines as well as hosts. VMware Tools runs in a guest operating system and reports information to VirtualCenter. . This constant was added in vSphere API 7.0.0.0. VIRTUAL_MACHINE: Specifies that the VirtualCenter should generate a virtual machine name. The name is generated from a base prefix comprising the virtual machine entity name. A number is appended, if necessary, to make it unique. Virtual machine names are unique across the set of hosts and virtual machines known to the VirtualCenter instance. VirtualCenter tracks the network names of the virtual machines as well as hosts. VMware Tools runs in a guest operating system and reports information to VirtualCenter, including the network name of the guest. . This constant was added in vSphere API 7.0.0.0. USER_INPUT_REQUIRED: Indicates that the host name is not specified in advance. The user must provide a valid value when the actual customization spec is applied to a virtual machine. This constant was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.linux_config.hostname.fixed_name	string	The virtual machine name specified by the client. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value FIXED. This field is optional and it is only relevant when the value of `type` is FIXED.
spec.spec.configuration_spec.linux_config.hostname.prefix	string	Base prefix, to which a unique number is appended. This attribute was added in vSphere API 7.0.0.0. Optional. It is only relevant when type has value PREFIX. This field is optional and it is only relevant when the value of `type` is PREFIX.
spec.spec.configuration_spec.linux_config.domain	string	The fully qualified domain name. This attribute was added in vSphere API 7.0.0.0.
spec.spec.configuration_spec.linux_config.time_zone	string	The case-sensitive time zone, such as Europe/Sofia. Valid time zone values are based on the tz (time zone) database used by Linux. The values are strings (string) in the form "Area/Location," in which Area is a continent or ocean name, and Location is the city, island, or other regional designation. See the https://kb.vmware.com/kb/2145518 for a list of supported time zones for different versions in Linux. . This attribute was added in vSphere API 7.0.0.0. Optional. If unset, time zone is not modified inside guest operating system.
spec.spec.configuration_spec.linux_config.script_text	string	The script to run before and after Linux guest customization. The max size of the script is 1500 bytes. As long as the script (shell, perl, python...) has the right "#!" in the header, it is supported. The caller should not assume any environment variables when the script is run. The script is invoked by the customization engine using the command line: 1) with argument "precustomization" before customization, 2) with argument "postcustomization" after customization. The script should parse this argument and implement pre-customization or post-customization task code details in the corresponding block. A Linux shell script example: `#!/bin/sh if [ x$1 == x"precustomization" ]; then echo "Do Precustomization tasks" #code for pre-customization actions... elif [ x$1 == x"postcustomization" ]; then echo "Do Postcustomization tasks" #code for post-customization actions... fi` . This attribute was added in vSphere API 7.0.0.0. Optional. If unset, no script will be executed.
spec.spec.global_DNS_settings	global_DNS_settings	Global DNS settings constitute the DNS settings that are not specific to a particular virtual network adapter. This attribute was added in vSphere API 7.0.0.0.
spec.spec.global_DNS_settings.dns_suffix_list	string[]	List of name resolution suffixes for the virtual network adapter. This list applies to both Windows and Linux guest customization. For Linux, this setting is global, whereas in Windows, this setting is listed on a per-adapter basis. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, no DNS suffixes are set.
spec.spec.global_DNS_settings.dns_servers	string[]	List of DNS servers, for a virtual network adapter with a static IP address. If this list is empty, then the guest operating system is expected to use 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. This attribute was added in vSphere API 7.0.0.0. Optional. If unset, no DNS servers are set.
spec.spec.interfaces	adapter_mapping[]	IP settings that are specific to a particular virtual network adapter. The vcenter.guest.adapter_mapping structure maps a network adapter's MAC address to its vcenter.guest.IP_settings. May be empty if there are no network adapters, else should match number of network adapters configured for the VM. This attribute was added in vSphere API 7.0.0.0.

Response:

HTTP Status Code: 200

None

Errors:

HTTP Status Code	Type	Description
400	invalid_argument	if the customization settings in `spec` are not valid.
400	not_allowed_in_current_state	if the virtual machine `vm` is not in a powered off state.
404	not_found	if a customization specification is not found with the unique name in `spec`.
503	service_unavailable	if the system is unable to communicate with a service to complete the request.
401	unauthenticated	if the user can not be authenticated.
403	unauthorized	if the user doesn't have the required privileges.