New-PveNodesQemu

Create or restore a virtual machine.

API: POST /nodes/{node}/qemu, Proxmox VE API viewer

Aliases: New-PveQemu

Syntax

New-PveNodesQemu
    [-PveTicket <PveTicket>]
    [-Acpi <bool>]
    [-Affinity <string>]
    [-Agent <string>]
    [-AllowKsm <bool>]
    [-AmdSev <string>]
    [-Arch <string>]
    [-Archive <string>]
    [-Args_ <string>]
    [-Audio0 <string>]
    [-Autostart <bool>]
    [-Balloon <int>]
    [-Bios <string>]
    [-Boot <string>]
    [-Bootdisk <string>]
    [-Bwlimit <int>]
    [-Cdrom <string>]
    [-Cicustom <string>]
    [-Cipassword <SecureString>]
    [-Citype <string>]
    [-Ciupgrade <bool>]
    [-Ciuser <string>]
    [-Cores <int>]
    [-Cpu <string>]
    [-Cpulimit <float>]
    [-Cpuunits <int>]
    [-Description <string>]
    [-Efidisk0 <string>]
    [-Force <bool>]
    [-Freeze <bool>]
    [-HaManaged <bool>]
    [-Hookscript <string>]
    [-HostpciN <hashtable>]
    [-Hotplug <string>]
    [-Hugepages <string>]
    [-IdeN <hashtable>]
    [-ImportWorkingStorage <string>]
    [-IntelTdx <string>]
    [-IpconfigN <hashtable>]
    [-Ivshmem <string>]
    [-Keephugepages <bool>]
    [-Keyboard <string>]
    [-Kvm <bool>]
    [-LiveRestore <bool>]
    [-Localtime <bool>]
    [-Lock <string>]
    [-Machine <string>]
    [-Memory <string>]
    [-MigrateDowntime <float>]
    [-MigrateSpeed <int>]
    [-Name <string>]
    [-Nameserver <string>]
    [-NetN <hashtable>]
    -Node <string>
    [-Numa <bool>]
    [-NumaN <hashtable>]
    [-Onboot <bool>]
    [-Ostype <string>]
    [-ParallelN <hashtable>]
    [-Pool <string>]
    [-Protection <bool>]
    [-Reboot <bool>]
    [-Rng0 <string>]
    [-SataN <hashtable>]
    [-ScsiN <hashtable>]
    [-Scsihw <string>]
    [-Searchdomain <string>]
    [-SerialN <hashtable>]
    [-Shares <int>]
    [-Smbios1 <string>]
    [-Smp <int>]
    [-Sockets <int>]
    [-SpiceEnhancements <string>]
    [-Sshkeys <string>]
    [-Start <bool>]
    [-Startdate <string>]
    [-Startup <string>]
    [-Storage <string>]
    [-Tablet <bool>]
    [-Tags <string>]
    [-Tdf <bool>]
    [-Template <bool>]
    [-Tpmstate0 <string>]
    [-Unique <bool>]
    [-UnusedN <hashtable>]
    [-UsbN <hashtable>]
    [-Vcpus <int>]
    [-Vga <string>]
    [-VirtioN <hashtable>]
    [-VirtiofsN <hashtable>]
    [-Vmgenid <string>]
    -Vmid <int>
    [-Vmstatestorage <string>]
    [-Watchdog <string>]
    [<CommonParameters>]

Parameters

Parameter	Type	Required	Description
-PveTicket	PveTicket	No	Ticket data connection.
-Acpi	bool	No	Enable/disable ACPI.
-Affinity	string	No	List of host cores used to execute guest processes, for example: 0,5,8-11.
-Agent	string	No	Enable/disable communication with the QEMU Guest Agent and its properties.
-AllowKsm	bool	No	Allow memory pages of this guest to be merged via KSM (Kernel Samepage Merging).
-AmdSev	string	No	Secure Encrypted Virtualization (SEV) features by AMD CPUs.
-Arch	string	No	Virtual processor architecture. Defaults to the host architecture. Values: x86_64, aarch64.
-Archive	string	No	The backup archive. Either the file system path to a .tar or .vma file (use ‘-’ to pipe data from stdin) or a proxmox storage backup volume identifier.
-Args_	string	No	Arbitrary arguments passed to kvm.
-Audio0	string	No	Configure a audio device, useful in combination with QXL/Spice.
-Autostart	bool	No	Automatic restart after crash (currently ignored).
-Balloon	int	No	Amount of target RAM for the VM in MiB. The balloon driver is enabled by default, unless it is explicitly disabled by setting the value to zero.
-Bios	string	No	Select BIOS implementation. Values: seabios, ovmf.
-Boot	string	No	Specify guest boot order. Use the ‘order=’ sub-property as usage with no key or ‘legacy=’ is deprecated.
-Bootdisk	string	No	Enable booting from specified disk. Deprecated: Use ‘boot: order=foo;bar’ instead.
-Bwlimit	int	No	Override I/O bandwidth limit (in KiB/s).
-Cdrom	string	No	This is an alias for option -ide2.
-Cicustom	string	No	cloud-init: Specify custom files to replace the automatically generated ones at start.
-Cipassword	SecureString	No	cloud-init: Password to assign the user. Using this is generally not recommended. Use ssh keys instead. Also note that older cloud-init versions do not support hashed passwords.
-Citype	string	No	Specifies the cloud-init configuration format. The default depends on the configured operating system type (ostype. We use the nocloud format for Linux, and configdrive2 for windows. Values: configdrive2, nocloud, opennebula.
-Ciupgrade	bool	No	cloud-init: do an automatic package upgrade after the first boot.
-Ciuser	string	No	cloud-init: User name to change ssh keys and password for instead of the image’s configured default user.
-Cores	int	No	The number of cores per socket.
-Cpu	string	No	Emulated CPU type.
-Cpulimit	float	No	Limit of CPU usage.
-Cpuunits	int	No	CPU weight for a VM, will be clamped to [1, 10000] in cgroup v2.
-Description	string	No	Description for the VM. Shown in the web-interface VM’s summary. This is saved as comment inside the configuration file.
-Efidisk0	string	No	Configure a disk for storing EFI vars. Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Note that SIZE_IN_GiB is ignored here and that the default EFI vars are copied to the volume instead. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-Force	bool	No	Allow to overwrite existing VM.
-Freeze	bool	No	Freeze CPU at startup (use ‘c’ monitor command to start execution).
-HaManaged	bool	No	Add the VM as a HA resource after it was created.
-Hookscript	string	No	Script that will be executed during various steps in the vms lifetime.
-HostpciN	hashtable	No	Map host PCI devices into guest.
-Hotplug	string	No	Selectively enable hotplug features. This is a comma separated list of hotplug features: ‘network’, ‘disk’, ‘cpu’, ‘memory’, ‘usb’ and ‘cloudinit’. Use ‘0’ to disable hotplug completely. Using ‘1’ as value is an alias for the default network,disk,usb. USB hotplugging is possible for guests with machine version >= 7.1 and ostype l26 or windows > 7.
-Hugepages	string	No	Enables hugepages memory. Sets the size of hugepages in MiB. If the value is set to ‘any’ then 1 GiB hugepages will be used if possible, otherwise the size will fall back to 2 MiB. Values: any, 2, 1024.
-IdeN	hashtable	No	Use volume as IDE hard disk or CD-ROM (n is 0 to 3). Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-ImportWorkingStorage	string	No	A file-based storage with ‘images’ content-type enabled, which is used as an intermediary extraction storage during import. Defaults to the source storage.
-IntelTdx	string	No	Trusted Domain Extension (TDX) features by Intel CPUs.
-IpconfigN	hashtable	No	cloud-init: Specify IP addresses and gateways for the corresponding interface. IP addresses use CIDR notation, gateways are optional but need an IP of the same type specified. The special string ‘dhcp’ can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided. For IPv6 the special string ‘auto’ can be used to use stateless autoconfiguration. This requires cloud-init 19.4 or newer. If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using dhcp on IPv4.
-Ivshmem	string	No	Inter-VM shared memory. Useful for direct communication between VMs, or to the host.
-Keephugepages	bool	No	Use together with hugepages. If enabled, hugepages will not not be deleted after VM shutdown and can be used for subsequent starts.
-Keyboard	string	No	Keyboard layout for VNC server. This option is generally not required and is often better handled from within the guest OS. Values: de, de-ch, da, en-gb, en-us, es, fi, fr, fr-be, fr-ca, fr-ch, hu, is, it, ja, lt, mk, nl, no, pl, pt, pt-br, sv, sl, tr.
-Kvm	bool	No	Enable/disable KVM hardware virtualization.
-LiveRestore	bool	No	Start the VM immediately while importing or restoring in the background.
-Localtime	bool	No	Set the real time clock (RTC) to local time. This is enabled by default if the ostype indicates a Microsoft Windows OS.
-Lock	string	No	Lock/unlock the VM. Values: backup, clone, create, migrate, rollback, snapshot, snapshot-delete, suspending, suspended.
-Machine	string	No	Specify the QEMU machine.
-Memory	string	No	Memory properties.
-MigrateDowntime	float	No	Set maximum tolerated downtime (in seconds) for migrations. Should the migration not be able to converge in the very end, because too much newly dirtied RAM needs to be transferred, the limit will be increased automatically step-by-step until migration can converge. Will be capped to 2000 seconds (maximum in QEMU).
-MigrateSpeed	int	No	Set maximum speed (in MB/s) for migrations. Value 0 is no limit.
-Name	string	No	Set a name for the VM. Only used on the configuration web interface.
-Nameserver	string	No	cloud-init: Sets DNS server IP address for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.
-NetN	hashtable	No	Specify network devices.
-Node	string	Yes	The cluster node name.
-Numa	bool	No	Enable/disable NUMA.
-NumaN	hashtable	No	NUMA topology.
-Onboot	bool	No	Specifies whether a VM will be started during system bootup.
-Ostype	string	No	Specify guest operating system. Values: other, wxp, w2k, w2k3, w2k8, wvista, win7, win8, win10, win11, l24, l26, solaris.
-ParallelN	hashtable	No	Map host parallel devices (n is 0 to 2).
-Pool	string	No	Add the VM to the specified pool.
-Protection	bool	No	Sets the protection flag of the VM. This will disable the remove VM and remove disk operations.
-Reboot	bool	No	Allow reboot. If set to ‘0’ the VM exit on reboot.
-Rng0	string	No	Configure a VirtIO-based Random Number Generator.
-SataN	hashtable	No	Use volume as SATA hard disk or CD-ROM (n is 0 to 5). Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-ScsiN	hashtable	No	Use volume as SCSI hard disk or CD-ROM (n is 0 to 30). Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-Scsihw	string	No	SCSI controller model. Values: lsi, lsi53c810, virtio-scsi-pci, virtio-scsi-single, megasas, pvscsi.
-Searchdomain	string	No	cloud-init: Sets DNS search domains for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.
-SerialN	hashtable	No	Create a serial device inside the VM (n is 0 to 3)
-Shares	int	No	Amount of memory shares for auto-ballooning. The larger the number is, the more memory this VM gets. Number is relative to weights of all other running VMs. Using zero disables auto-ballooning. Auto-ballooning is done by pvestatd.
-Smbios1	string	No	Specify SMBIOS type 1 fields.
-Smp	int	No	The number of CPUs. Please use option -sockets instead.
-Sockets	int	No	The number of CPU sockets.
-SpiceEnhancements	string	No	Configure additional enhancements for SPICE.
-Sshkeys	string	No	cloud-init: Setup public SSH keys (one key per line, OpenSSH format).
-Start	bool	No	Start VM after it was created successfully.
-Startdate	string	No	Set the initial date of the real time clock. Valid format for date are:‘now’ or ‘2006-06-17T16:01:21’ or ‘2006-06-17’.
-Startup	string	No	Startup and shutdown behavior. Order is a non-negative number defining the general startup order. Shutdown in done with reverse ordering. Additionally you can set the ‘up’ or ‘down’ delay in seconds, which specifies a delay to wait before the next VM is started or stopped.
-Storage	string	No	Default storage.
-Tablet	bool	No	Enable/disable the USB tablet device.
-Tags	string	No	Tags of the VM. This is only meta information.
-Tdf	bool	No	Enable/disable time drift fix.
-Template	bool	No	Enable/disable Template.
-Tpmstate0	string	No	Configure a Disk for storing TPM state. The format is fixed to ‘raw’. Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Note that SIZE_IN_GiB is ignored here and 4 MiB will be used instead. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-Unique	bool	No	Assign a unique random ethernet address.
-UnusedN	hashtable	No	Reference to unused volumes. This is used internally, and should not be modified manually.
-UsbN	hashtable	No	Configure an USB device (n is 0 to 4, for machine version >= 7.1 and ostype l26 or windows > 7, n can be up to 14).
-Vcpus	int	No	Number of hotplugged vcpus.
-Vga	string	No	Configure the VGA hardware.
-VirtioN	hashtable	No	Use volume as VIRTIO hard disk (n is 0 to 15). Use the special syntax STORAGE_ID:SIZE_IN_GiB to allocate a new volume. Use STORAGE_ID:0 and the ‘import-from’ parameter to import from an existing volume.
-VirtiofsN	hashtable	No	Configuration for sharing a directory between host and guest using Virtio-fs.
-Vmgenid	string	No	Set VM Generation ID. Use ‘1’ to autogenerate on create or update, pass ‘0’ to disable explicitly.
-Vmid	int	Yes	The (unique) ID of the VM.
-Vmstatestorage	string	No	Default storage for VM state volumes/files.
-Watchdog	string	No	Create a virtual hardware watchdog device.

Every parameter also binds by property name from the pipeline, so an object with node and vmid properties (the output of Get-PveGuest, for one) fills -Node and -Vmid. Without -PveTicket the cmdlet uses the last connection, see Connection.

Output

A PveResponse: the data returned by Proxmox VE is in .Response.data, the outcome in .IsSuccessStatusCode. See Results and Errors.