dpmhv-createVMFromTemplateEx (Funclet) Command--Create a VM Using a Template

Reference Guide › AutoShell › AutoShell Loadable Modules' Command Reference › CA Microsoft Hyper-V AutoShell Commands › dpmhv-createVMFromTemplateEx (Funclet) Command--Create a VM Using a Template

dpmhv-createVMFromTemplateEx (Funclet) Command--Create a VM Using a Template

The dpmhv-createVMFromTemplate command lets you create VM using existing templates. If the original template is created in Sysprep state, you can customize the (Windows) settings of the VM created (image) using the command parameters. Upon the creation of the VM, you can create system components using respective commands. You can use one template to create multiple virtual machines.

Note: You can customize the Windows Settings image when the command is run synchronously. For asynchronous execution, you can use dpmhv-setSysprepProperties command to customize the image after the execution is complete.

This command has the following format:

dpmhv-createVMFromTemplateEx 
-host hostname 
-vm vmname 
-template templatename 
-dest pathname
[-computerName computerName] 
[-ip4addr ip4addr] 
[-ip4dhcp ip4dhcpInt] 
[-ip4mask ip4mask] 
[-ip4gw ip4gw]
[-ip4metric ip4metric] 
[-ip4dns ip4dns]
[-disableAdmin]
[-adminPass adminPW]
[-autoLogon alcnt]
[-duplicatorString dupstr]
[-timeZone timezone]
[-productKey key] 
[-userName UserName] 
[-organization orgname] 
[-domain domainname] 
[-domainAdmin domad] 
[-domainAdminPass dompw] 
[-workgroup wgname] 
[-adminUser adminUser] 
[-adminUserPass adminUserPW]
[-custom custom] 
[-async]
[-mem mem]
[-cpus cpus]
[-cpuidlimit limit] 
[-cpufeatlimit limit] 
[-cpureserve reserve] 
[-cpulimit limit]
[-cpuweight weight]
[-startAction {none,auto,always}]
[-startDelay delay] 
[-stopAction {save,off,shutdown}]
[-recoveryAction {none,restart,revert}]
[-scvmmHost  scvmmHostname]
[-hardwareProf hwprof]
[-guestOSProf osprof]
[-startVM]

-host hostname

Specifies the name of the Hyper-V server host.

-vm vmname

Specifies the name of the VM.

-template templatename

Specifies the name of the source template that you want to use to create the VM.

Note: The template name must be unique in the local template catalog.

-dest pathname

(Optional) Specifies the path of the VM that you want to create (template is stored). If this option is not specified, VM is created in the Hyper-V Server default location. The name of the template created is stored in the following location: %ALLUSERSPROFILE%\ca\vpm\Hyper-V_Templates.

Note: We recommend not creating VMs in the Hyper-V default location. It conflicts with virtual disk image file names that do not change when creating VMs using templates.

-computerName computerName

(Optional) Specifies the computer name of the VM. Support for this parameter requires an image using Sysprep tool. This option is invalid for asynchronous execution of the command.

-ip4addr ip4addr

(Optional) Specifies the static IPv4 address that you want to assign to an interface of the VM. To set an IP address for a specific interface, the IP address is prefixed with known interface name and '#' as separator. For example,
-ip4addr "Local Area Connection#192.168.1.200". If the template image has more than one network adaptor, the IP address is assigned to the first interface. This option is invalid for asynchronous execution of the command.

-ip4dhcp ip4dhcpInt

(Optional) Specifies an option to turn on DHCP of a particular interface of the VM. You can also specify the interface name for this option. For example,
-ip4dhcp "Local Area Connection." If the template image has more than one network adaptor, DHCP is turned on for the first interface. This option is invalid for asynchronous execution of the command.

Default: local

-ip4mask ip4mask

(Optional) Specifies the subnet mask that you want to assign for the VM. This option is used with
-ip4ddr option. If an interface name is specified in the
-ip4addr option, same interface name must be used in this option. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of the command.

-ip4gw ip4gw

(Optional) Specifies the option to set the gateway for VM. This option is used with -ip4ddr option. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

Note: If an interface name is specified in the
-ip4addr option, same interface name must be used in this option.

-ip4metric ip4metric

(Optional) Specifies the interface metric that you want to set for the VM. This option is used with -ip4ddr option. If an interface name is specified in the
-ip4addr option, same interface name must be used in this option. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

Default: 1

-ip4dns ip4dns

(Optional) Specifies the DNS server that you want to set for the VM. This option is used with -ip4ddr option. If an interface name is specified in the
-ip4addr option, same interface name must be used in this option. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-disableAdmin

(Optional) Specifies an option to disable default administrator account for the VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-adminPass adminPW

(Optional) This option is used to set the default administrator account password for the VM. Support for this parameter requires a Windows image created using Sysprep tool. This parameter is ignored in asynchronous execution.

Note: To set this option successfully, set the Windows Server administrator password which is created using Sysprep tool as empty.

-autoLogon alcnt

(Optional) Specifies an option to set the number of accounts that you want to create to log in automatically with default administrator account. The accounts are created after the completion of Sysprep process. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

Default:
-1

-duplicatorString dupstr

(Optional) Specifies the name of the system duplicator that you want to set in the registry of the VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-timeZone timezone

(Optional) Specifies the time zone used by the VM that are created using the template. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

Default:
-1

-productKey key

(Optional) Specifies the Windows product activation key for the VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-userName UserName

(Optional) Specifies the user name of the Windows image (created using sysprep tool) which is installed on the new VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-organization orgname

(Optional) Specifies the organization name of the Windows image (created using sysprep tool) which is installed on the new VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-domain domainname

(Optional) Specifies the domain name for the VM. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command. Domain and workgroup specifications are mutually exclusive.

-domainAdmin domad

(Optional) Specifies the user account as Domain Administrator that you want to create in the domain. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-domainAdminPass dompw

(Optional) Specifies the password for Domain Administrator user account that you want to create in the domain. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-workgroup wgname

(Optional) Specifies the workgroup that you want to create for the VM. Support for this parameter requires a Windows image created using Sysprep tool. Domain and workgroup specifications are mutually exclusive. This option is invalid for asynchronous execution of command.

-adminUser adminUser

(Optional) Specifies the administrator user name that you want to create as a part of the default Administrators group. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-adminUserPass adminUserPW

(Optional) Specifies the password of the administrator user account that you want to create as a part of the default Administrators group. Support for this parameter requires a Windows image created using Sysprep tool. This option is invalid for asynchronous execution of command.

-custom custom

(Optional) Specifies the list of comma-separated custom commands that you want to execute at the end of Sysprep process. This parameter requires Windows image of Sysprep. This parameter is ignored in asynchronous execution.

-async

(Optional) Specifies the option to execute the command asynchronously. By default, this command is executed synchronously.

Note: If this command completes the execution before executing this option, it returns a job ID that is used to view the operation status.

-mem mem

(Optional) Specifies the RAM memory in megabytes (MB) for the VM that you want to create.

Default: -1

-cpus cpus

(Optional) Specifies the number of CPU core that you want to assign to the VM.

Default: -1

-cpuidlimit limit

(Optional) Specifies the limit of CPU ID functionality of VM. This option improves the compatibility with legacy operating systems such as Windows NT.

Default: -1

-cpufeatlimit limit

(Optional) Specifies the limit for the functionality of the CPU resources used by a VM. This option improves the compatibility while moving VMs between physical hosts with different CPU capabilities.

Default: -1

-cpureserve reserve

(Optional) Specifies the percentage of the CPU that you want to reserve for the VM. If this option is not specified, Hyper-V server assigns CPU cycles based on the overall system usage.

Default: -1

-cpulimit limit

(Optional) Specifies the limit for the number of CPU resources used by a VM. This option improves the compatibility while moving VMs between physical hosts with different CPU capabilities.

Default: -1

-cpuweight weight

(Optional) Specifies the relative weight of the virtual machine. This option controls resource allocation when more than one VM is running. Valid entry: integer, 1-10000.

Default: -1

-startAction {none,auto,always}

(Optional) Specifies the action that you want to perform on the VM when the Hyper-V host starts up. Options include the following:

none

Performs no action.

auto

Starts the VM automatically.

Note: Use this option if the VM was running before the Hyper-V host is shut down.

always

Starts the VM always.

-startDelay delay

(Optional) Specifies the delay in seconds to start the VM after the Hyper-V host is up and running.

Default: -1

-stopAction {save,off,shutdown}

(Optional) Specifies the action that you want to perform on the VM when the physical Hyper-V shuts down. Options include the following:

save: Suspends the VM.
off: Power offs the VM.
shutdown: Shuts down the system.

-recoveryAction {none,restart,revert}

(Optional) Specifies the action to perform on the VM after the Hyper-V host restarts from unexpected shutdown. Options include the following:

none: Performs no action.
restart: Restart the VM.
revert: Reverts to the last snapshot of the VM.

-scvmmHost scvmmHostname

(Optional) Specifies the host name of the Microsoft System Center Virtual Machine Manager (SCVMM) library server. This parameter is valid when you use SCVMM integration to provision VMs.

-hardwareProf hwprof

(Optional) Specifies the name of the hardware profile defined by the Microsoft System Center Virtual Machine Manager (SCVMM) library server. This parameter overwrites the hardware configuration settings stored in the SCVMM template. This parameter is valid when you use SCVMM integration to provision VMs.

-guestOSProf osprof

(Optional) Specifies the name of the guest operating system profile defined by the Microsoft System Center Virtual Machine Manager (SCVMM) library server. This parameter overwrites the operating system configuration settings stored in the SCVMM library server. This parameter is valid when you use SCVMM integration to provision VMs.

-startVM

(Optional) Specifies the option to start the VM automatically after it is created. By default, the new VM is in powered-off state. You must customize the IP configuration options required to start the VM.

Return Value

The dpmhv-createVMFromTemplateEX command returns an empty string when it is executed synchronously. If executed asynchronously, a string representing job ID is passed to dpmhv-getJobErrorInfo, dpmhv-getJobInfo, or dpmhv-getJobStatus. If an error occurs during execution, the command reports an exception.

Example: Create a VM from a Template

This example lets you create VM,"TestVM" using a template setting as complete static IPv4 configuration:

dpmhv-createVMFromTemplateEx -host hvserver -vm NewVM -dest c:\VMs\NewBox -template Win2k3SysPrepped 
-ip4addr 192.168.1.25 -ip4mask 255.255.255.0 -ip4gw 192.168.1.1 -ip4dns 192.168.1.1 
-computerName NewBox