Invoke-XenVM

Last published : Nov 12, 2026
Invokes an operation on a VM object.
Related information
VM cmdlets

Syntax

Invoke-XenVM [-VM] <VM>
    -XenAction {Snapshot | SnapshotWithQuiesce | Clone | Copy | Revert | Checkpoint | Provision | Start | StartOn | Pause | Unpause | CleanShutdown | Shutdown | CleanReboot | HardShutdown | PowerStateReset | HardReboot | Suspend | Resume | ResumeOn | PoolMigrate | ComputeMemoryOverhead | WaitMemoryTargetLive | SendSysrq | SendTrigger | MaximiseMemory | MigrateSend | AssertCanMigrate | RecordDataSource | QueryDataSource | ForgetDataSourceArchives | AssertOperationValid | UpdateAllowedOperations | AssertCanBootHere | CreateNewBlob | AssertAgile | RetrieveWlbRecommendations | CopyBiosStrings | AssertCanBeRecovered | Recover | ImportConvert | QueryServices | CallPlugin | CallHostPlugin | Import | RestartDeviceModels | UpdateSecurebootCertificatesOnBoot | Sysprep}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVM [-Ref] <XenRef[VM]>
    -XenAction {Snapshot | SnapshotWithQuiesce | Clone | Copy | Revert | Checkpoint | Provision | Start | StartOn | Pause | Unpause | CleanShutdown | Shutdown | CleanReboot | HardShutdown | PowerStateReset | HardReboot | Suspend | Resume | ResumeOn | PoolMigrate | ComputeMemoryOverhead | WaitMemoryTargetLive | SendSysrq | SendTrigger | MaximiseMemory | MigrateSend | AssertCanMigrate | RecordDataSource | QueryDataSource | ForgetDataSourceArchives | AssertOperationValid | UpdateAllowedOperations | AssertCanBootHere | CreateNewBlob | AssertAgile | RetrieveWlbRecommendations | CopyBiosStrings | AssertCanBeRecovered | Recover | ImportConvert | QueryServices | CallPlugin | CallHostPlugin | Import | RestartDeviceModels | UpdateSecurebootCertificatesOnBoot | Sysprep}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVM [-Uuid] <guid>
    -XenAction {Snapshot | SnapshotWithQuiesce | Clone | Copy | Revert | Checkpoint | Provision | Start | StartOn | Pause | Unpause | CleanShutdown | Shutdown | CleanReboot | HardShutdown | PowerStateReset | HardReboot | Suspend | Resume | ResumeOn | PoolMigrate | ComputeMemoryOverhead | WaitMemoryTargetLive | SendSysrq | SendTrigger | MaximiseMemory | MigrateSend | AssertCanMigrate | RecordDataSource | QueryDataSource | ForgetDataSourceArchives | AssertOperationValid | UpdateAllowedOperations | AssertCanBootHere | CreateNewBlob | AssertAgile | RetrieveWlbRecommendations | CopyBiosStrings | AssertCanBeRecovered | Recover | ImportConvert | QueryServices | CallPlugin | CallHostPlugin | Import | RestartDeviceModels | UpdateSecurebootCertificatesOnBoot | Sysprep}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVM [-Name] <string>
    -XenAction {Snapshot | SnapshotWithQuiesce | Clone | Copy | Revert | Checkpoint | Provision | Start | StartOn | Pause | Unpause | CleanShutdown | Shutdown | CleanReboot | HardShutdown | PowerStateReset | HardReboot | Suspend | Resume | ResumeOn | PoolMigrate | ComputeMemoryOverhead | WaitMemoryTargetLive | SendSysrq | SendTrigger | MaximiseMemory | MigrateSend | AssertCanMigrate | RecordDataSource | QueryDataSource | ForgetDataSourceArchives | AssertOperationValid | UpdateAllowedOperations | AssertCanBootHere | CreateNewBlob | AssertAgile | RetrieveWlbRecommendations | CopyBiosStrings | AssertCanBeRecovered | Recover | ImportConvert | QueryServices | CallPlugin | CallHostPlugin | Import | RestartDeviceModels | UpdateSecurebootCertificatesOnBoot | Sysprep}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]

Description

Invokes an operation on a VM object. Use the -XenAction parameter to select which operation to perform.
Snapshot: Snapshots the specified VM, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM's disk images are stored (for example, Copy on Write).
SnapshotWithQuiesce: Snapshots the specified VM with quiesce, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM's disk images are stored (for example, Copy on Write). (Removed.)
Clone: Clones the specified VM, making a new VM. Clone automatically exploits the capabilities of the underlying storage repository in which the VM's disk images are stored (for example, Copy on Write). This function can only be called when the VM is in the Halted State.
Copy: Copies the specified VM, making a new VM. Unlike clone, copy does not exploit the capabilities of the underlying storage repository in which the VM's disk images are stored. Instead, copy guarantees that the disk images of the newly created VM will be 'full disks' - i.e. not part of a CoW chain. This function can only be called when the VM is in the Halted State.
Revert: Reverts the specified VM to a previous state.
Checkpoint: Checkpoints the specified VM, making a new VM. Checkpoint automatically exploits the capabilities of the underlying storage repository in which the VM's disk images are stored (for example, Copy on Write) and saves the memory image as well.
Provision: Inspects the disk configuration contained within the VM's other\_config, creates VDIs and VBDs and then executes any applicable post-install script.
Start: Start the specified VM. This function can only be called with the VM is in the Halted State.
StartOn: Start the specified VM on a particular host. This function can only be called with the VM is in the Halted State.
Pause: Pause the specified VM. This can only be called when the specified VM is in the Running state.
Unpause: Resume the specified VM. This can only be called when the specified VM is in the Paused state.
CleanShutdown: Attempt to cleanly shutdown the specified VM. (Note: this may not be supported, for example, if a guest agent is not installed). This can only be called when the specified VM is in the Running state.
Shutdown: Attempts to first clean shutdown a VM and if it should fail then perform a hard shutdown on it.
CleanReboot: Attempt to cleanly shutdown the specified VM (Note: this may not be supported, for example, if a guest agent is not installed). This can only be called when the specified VM is in the Running state.
HardShutdown: Stop executing the specified VM without attempting a clean shutdown.
PowerStateReset: Reset the power-state of the VM to halted in the database only. (Used to recover from supporter failures in pooling scenarios by resetting the power-states of VMs running on dead supporters to halted.) This is a potentially dangerous operation; use with care.
HardReboot: Stop executing the specified VM without attempting a clean shutdown and immediately restart the VM.
Suspend: Suspend the specified VM to disk. This can only be called when the specified VM is in the Running state.
Resume: Awaken the specified VM and resume it. This can only be called when the specified VM is in the Suspended state.
ResumeOn: Awaken the specified VM and resume it on a particular Host. This can only be called when the specified VM is in the Suspended state.
PoolMigrate: Migrate a VM to another Host.
ComputeMemoryOverhead: Computes the virtualization memory overhead of a VM.
WaitMemoryTargetLive: Wait for a running VM to reach its current memory target. (Deprecated.)
SendSysrq: Send the given key as a sysrq to this VM. The key is specified as a single character (a String of length 1). This can only be called when the specified VM is in the Running state.
SendTrigger: Send the named trigger to this VM. This can only be called when the specified VM is in the Running state.
MaximiseMemory: Returns the maximum amount of guest memory which will fit, together with overheads, in the supplied amount of physical memory. If 'exact' is true then an exact calculation is performed using the VM's current settings. If 'exact' is false then a more conservative approximation is used.
MigrateSend: Migrate the VM to another host. This can only be called when the specified VM is in the Running state.
AssertCanMigrate: Assert whether a VM can be migrated to the specified destination.
RecordDataSource: Start recording the specified data source.
QueryDataSource: Query the latest value of the specified data source.
ForgetDataSourceArchives: Forget the recorded statistics related to the specified data source.
AssertOperationValid: Check to see whether this operation is acceptable in the current state of the system, raising an error if the operation is invalid for some reason.
UpdateAllowedOperations: Recomputes the list of acceptable operations.
AssertCanBootHere: Returns an error if the VM could not boot on this host for some reason.
CreateNewBlob: Create a placeholder for a named binary blob of data that is associated with this VM.
AssertAgile: Returns an error if the VM is not considered agile, for example, because it is tied to a resource local to a host.
RetrieveWlbRecommendations: Returns mapping of hosts to ratings, indicating the suitability of starting the VM at that location according to wlb. Rating is replaced with an error if the VM cannot boot there.
CopyBiosStrings: Copy the BIOS strings from the given host to this VM.
AssertCanBeRecovered: Assert whether all SRs required to recover this VM are available.
Recover: Recover the VM.
ImportConvert: Import using a conversion service.
QueryServices: Query the system services advertised by this VM and register them. This can only be applied to a system domain.
CallPlugin: Call an API plugin on this vm.
CallHostPlugin: Call an API plugin on the host where this vm resides.
Import: Import an XVA from a URI.
RestartDeviceModels: Restart device models of the VM.
UpdateSecurebootCertificatesOnBoot: Mark or unmark secure boot certificate update on VM boot.
Sysprep: Pass unattend.xml to Windows sysprep and wait for the VM to shut down as part of a reboot.

Parameters

-Approximate

If false the limit is calculated with the guest's current exact configuration. Otherwise a more approximate calculation is performed. Accepted when -XenAction is MaximiseMemory.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Args

Arguments for the function. Accepted when -XenAction is CallPlugin, CallHostPlugin.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-Async

If set, the operation runs asynchronously and returns a Task object that can be used to track its progress.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-BestEffort

If set, the cmdlet continues processing further objects instead of throwing a terminating error when an operation fails for one object.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Confirm

Prompts for confirmation before running the cmdlet.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases cf

-DataSource

The data source to record. Accepted when -XenAction is RecordDataSource, QueryDataSource, ForgetDataSourceArchives.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Dest

The result of a Host.migrate\_receive call. Accepted when -XenAction is MigrateSend, AssertCanMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-Fn

The name of the function within the plugin. Accepted when -XenAction is CallPlugin, CallHostPlugin.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Force

Attempt to force the VM to start. If this flag is false then the VM may fail pre-boot safety checks (for example, if the CPU the VM last booted on looks substantially different to the current one). Accepted when -XenAction is Start, StartOn, Resume, ResumeOn, Recover, Import.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-FullRestore

Perform a full restore. Accepted when -XenAction is Import.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-IgnoreVdis

A list of VDIs to ignore for the snapshot. Accepted when -XenAction is Snapshot.
Attribute Value
Type List[XenRef[VDI]]
Required False
Position Named
Accepts pipeline input False

-Key

The key to send. Accepted when -XenAction is SendSysrq.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Live

Live migration. Accepted when -XenAction is MigrateSend, AssertCanMigrate.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Mark

If true: mark certificates for update on next boot. If false: remove the mark. Accepted when -XenAction is UpdateSecurebootCertificatesOnBoot.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-MimeType

The mime type for the data. Empty string translates to application/octet-stream. Accepted when -XenAction is CreateNewBlob.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Name

The name of the VM to operate on.
Attribute Value
Type string
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases name_label

-NameParam

The name associated with the blob. Accepted when -XenAction is CreateNewBlob.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-NewName

The name of the snapshotted VM. Accepted when -XenAction is Snapshot, SnapshotWithQuiesce, Clone, Copy, Checkpoint.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Op

proposed operation. Accepted when -XenAction is AssertOperationValid.
Attribute Value
Type vm_operations
Required False
Position Named
Accepts pipeline input False
Accepted values snapshot, clone, copy, create_template, revert, checkpoint, snapshot_with_quiesce, provision, start, start_on, pause, unpause, clean_shutdown, clean_reboot, hard_shutdown, power_state_reset, hard_reboot, suspend, csvm, resume, resume_on, pool_migrate, migrate_send, get_boot_record, send_sysrq, send_trigger, query_services, shutdown, call_plugin, changing_memory_live, awaiting_memory_live, changing_dynamic_range, changing_static_range, changing_memory_limits, changing_shadow_memory, changing_shadow_memory_live, changing_VCPUs, changing_VCPUs_live, changing_NVRAM, assert_operation_valid, data_source_op, update_allowed_operations, make_into_template, import, export, metadata_export, reverting, destroy, create_vtpm, sysprep, unknown

-Options

Extra configuration operations: force, live, copy, compress. Each is a boolean option, taking 'true' or 'false' as a value. Option 'compress' controls the use of stream compression during migration. Accepted when -XenAction is PoolMigrate, MigrateSend, AssertCanMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-PassThru

If set, the cmdlet returns the affected object. By default the cmdlet does not generate any output.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Password

Password on the host. Accepted when -XenAction is ImportConvert.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Plugin

The name of the plugin. Accepted when -XenAction is CallPlugin, CallHostPlugin.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Public

True if the blob should be publicly available. Accepted when -XenAction is CreateNewBlob.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Ref

The VM object to operate on, specified by its opaque reference.
Attribute Value
Type XenRef[VM]
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases opaque_ref

-RemoteConfig

Remote configuration options. Accepted when -XenAction is ImportConvert.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-SR

An SR to copy all the VM's disks into (if an invalid reference then it uses the existing SRs). Accepted when -XenAction is Copy, ImportConvert, Import.
Attribute Value
Type XenRef[SR]
Required False
Position Named
Accepts pipeline input False

-SessionOpaqueRef

The session object on which to run the cmdlet. This overrides the default session and lets you target a specific open XenServer connection.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-SessionTo

The session to which the VM is to be recovered. Accepted when -XenAction is AssertCanBeRecovered, Recover.
Attribute Value
Type XenRef[Session]
Required False
Position Named
Accepts pipeline input False

-Snapshot

The snapshotted state that we revert to. Accepted when -XenAction is Revert.
Attribute Value
Type XenRef[VM]
Required False
Position Named
Accepts pipeline input False

-StartPaused

Instantiate VM in paused state if set to true. Accepted when -XenAction is Start, StartOn, Resume, ResumeOn.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Timeout

timeout in seconds for expected reboot. Accepted when -XenAction is Sysprep.
Attribute Value
Type double
Required False
Position Named
Accepts pipeline input False

-Total

Total amount of physical RAM to fit within. Accepted when -XenAction is MaximiseMemory.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-Trigger

The trigger to send. Accepted when -XenAction is SendTrigger.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Type

Type of the conversion. Accepted when -XenAction is ImportConvert.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Unattend

XML content passed to sysprep. Accepted when -XenAction is Sysprep.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Url

The URL of the XVA file. Accepted when -XenAction is Import.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Username

Admin username on the host. Accepted when -XenAction is ImportConvert.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Uuid

The UUID of the VM to operate on.
Attribute Value
Type guid
Required True
Position 0
Accepts pipeline input True (ByPropertyName)

-VM

The VM object to operate on.
Attribute Value
Type VM
Required True
Position 0
Accepts pipeline input True (ByValue)

-VdiFormatMap

Map of source VDI to it's expected type on destination. Accepted when -XenAction is MigrateSend.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-VdiMap

Map of source VDI to destination SR. Accepted when -XenAction is MigrateSend, AssertCanMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-VgpuMap

Map of source vGPU to destination GPU group. Accepted when -XenAction is MigrateSend, AssertCanMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-VifMap

Map of source VIF to destination network. Accepted when -XenAction is MigrateSend, AssertCanMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases wi

-XenAction

Selects which action to use.
Attribute Value
Type XenVMAction
Required True
Position Named
Accepts pipeline input False
Accepted values Snapshot, SnapshotWithQuiesce, Clone, Copy, Revert, Checkpoint, Provision, Start, StartOn, Pause, Unpause, CleanShutdown, Shutdown, CleanReboot, HardShutdown, PowerStateReset, HardReboot, Suspend, Resume, ResumeOn, PoolMigrate, ComputeMemoryOverhead, WaitMemoryTargetLive, SendSysrq, SendTrigger, MaximiseMemory, MigrateSend, AssertCanMigrate, RecordDataSource, QueryDataSource, ForgetDataSourceArchives, AssertOperationValid, UpdateAllowedOperations, AssertCanBootHere, CreateNewBlob, AssertAgile, RetrieveWlbRecommendations, CopyBiosStrings, AssertCanBeRecovered, Recover, ImportConvert, QueryServices, CallPlugin, CallHostPlugin, Import, RestartDeviceModels, UpdateSecurebootCertificatesOnBoot, Sysprep

-XenHost

The Host on which to start the VM. Accepted when -XenAction is StartOn, ResumeOn, PoolMigrate, AssertCanBootHere, CopyBiosStrings.
Attribute Value
Type XenRef[Host]
Required False
Position Named
Accepts pipeline input False

Inputs

  • VM
  • XenRef[VM]
  • guid
  • string

Outputs

  • System.Object

Examples

Example 1: Run the Snapshot operation

PS> Get-XenVM -Name "Demo VM" | Invoke-XenVM -XenAction Snapshot -PassThru
Invokes the Snapshot operation on a VM. -PassThru writes the result to the pipeline.

Example 2: Start a VM

PS> Get-XenVM -Name "web-01" | Invoke-XenVM -XenAction Start
The VM operations are actions on one cmdlet rather than a cmdlet each, so the operation is chosen with -XenAction. The VM is piped in; -Ref or -Uuid would do as well.

Example 3: Shut down a VM cleanly or forcibly

PS> $vm = Get-XenVM -Name "web-01"
PS> $vm | Invoke-XenVM -XenAction CleanShutdown
PS> $vm | Invoke-XenVM -XenAction HardShutdown
CleanShutdown asks the guest to shut itself down and fails if it will not; HardShutdown is the equivalent of pulling the power. They are separate actions because the choice matters.

Example 4: Run an operation asynchronously

PS> Get-XenVM -Name "web-01" |
    Invoke-XenVM -XenAction Start -Async -PassThru |
    Wait-XenTask -ShowProgress
-Async returns as soon as the server has accepted the work and -PassThru emits the Task that represents it, which pipes straight into Wait-XenTask. This is the idiom for any operation that may take a while; without -Async the cmdlet blocks until it finishes.

Example 5: Snapshot a VM and revert to the snapshot

PS> $vm = Get-XenVM -Name "web-01"
PS> $snapshot = $vm |
    Invoke-XenVM -XenAction Snapshot -NewName "before upgrade" -PassThru
PS> $vm | Invoke-XenVM -XenAction Revert -Snapshot $snapshot
-PassThru is what makes the snapshot usable: without it the snapshot is taken but nothing is returned to pass to Revert. -Snapshot is one of the parameters this cmdlet adds for the Revert action, so it only appears once -XenAction is Revert.

Example 6: Clone a template into a new VM

PS> $template = Get-XenVM |
    Where-Object { $_.is_a_template } |
    Select-Object -First 1
PS> $vm = $template |
    Invoke-XenVM -XenAction Clone -NewName "web-02" -PassThru
PS> $vm | Invoke-XenVM -XenAction Provision
Clone copies the template's definition; Provision then creates the disks it describes. A cloned template is not runnable until it has been provisioned.

Example 7: Migrate a running VM within the pool

PS> $target = Get-XenHost -Name "host-02"
PS> Get-XenVM -Name "web-01" |
    Invoke-XenVM -XenAction PoolMigrate -XenHost $target
PoolMigrate moves a running VM between hosts that share its storage. Moving one to a host in another pool is a different action, MigrateSend, because it has to copy the disks too.
  • VM cmdlets
  • Class: VM
  • Using the XenServer PowerShell module