REST API - get

vcenter guest customization specs: get

Returns the guest customization specification from vCenter with the specified identifier. This operation was added in vSphere API 7.0.0.0.

Request:

HTTP request

GET https://{server}/rest/vcenter/guest/customization-specs/{name}

Path Parameters

Name Type Description
Required
name string The name of the customization specification.

Response:

HTTP Status Code: 200

Representation:

{
    "value"{
        "last_modified""2015-01-01T22:13:05.651Z",
        "spec"{
            "name""string",
            "fingerprint""string",
            "description""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"
                    }
                }
            }
        }
    }
}

Response Type:

Name Type Description
bold = required
value info A customization spec with the specified identifier.
value.last_modified date_time Time when the specification was last modified. This attribute was added in vSphere API 7.0.0.0.

value.spec spec The Spec object including specification and metadata information. This attribute was added in vSphere API 7.0.0.0.

value.spec.fingerprint string The fingerprint is a unique identifier for a given version of the configuration. Each change to the configuration will update this value. A client cannot change this value. If specified when updating a specification, the changes will only be applied if the current fingerprint matches the specified fingerprint. This field can be used to guard against updates that has happened between the specification content was read and until it is applied. This attribute was added in vSphere API 7.0.0.0.

value.spec.spec customization_spec The specification object. This attribute was added in vSphere API 7.0.0.0.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.
value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.
value.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.

value.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.

value.spec.spec.configuration_spec.linux_config.domain string The fully qualified domain name. This attribute was added in vSphere API 7.0.0.0.

value.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.

value.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.

value.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.

value.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.

value.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.

value.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.

value.spec.description string Description of the specification. This attribute was added in vSphere API 7.0.0.0.

value.spec.name string Name of the specification. This attribute was added in vSphere API 7.0.0.0.

Errors:

HTTP Status Code Type Description
404 not_found if a customization specification is not found.
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.