Start-VMFailover
Starts failover on a virtual machine.
Syntax
Start-VMFailover
[-ComputerName <String[]>]
[-VMName] <String[]>
[-Prepare]
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Start-VMFailover
[-ComputerName <String[]>]
[-VMName] <String[]>
[-AsTest]
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Start-VMFailover
[-VM] <VirtualMachine[]>
[-Prepare]
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Start-VMFailover
[-VM] <VirtualMachine[]>
[-AsTest]
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Start-VMFailover
[-VMRecoverySnapshot] <VMSnapshot>
[-AsTest]
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Start-VMFailover
[-VMRecoverySnapshot] <VMSnapshot>
[-AsJob]
[-PassThru]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Start-VMFailover cmdlet can be used for the following tasks:
-- Fail over a Replica virtual machine to a chosen recovery point. -- Start a planned failover on a primary virtual machine. -- Create a test virtual machine on a Replica virtual machine.
Examples
Example 1
PS C:\> Get-VMSnapshot VM01 -Name Snapshot01 | Start-VMFailover
This example starts failover of a virtual machine named VM01 with recovery point Snapshot01.
Note: Recovery points are stored as snapshots. To get a list of all snapshots, use the Get-VMSnapshot cmdlet.
Example 2
PS C:\> Start-VMFailover VM01 -AsTest
This example starts a test failover of a virtual machine named VM01.
Example 3
PS C:\> Get-VMSnapshot VM01 -Name Snapshot01 | Start-VMFailover -AsTest
Starts a test failover of a virtual machine named VM01 with recovery point Snapshot01.
Example 4
PS C:\> Start-VMFailover -Prepare -VMName VM01 -computername MyPrimary.contoso.com
PS C:\> Start-VMFailover -VMName VM01 -computername MyReplica.contoso.com
PS C:\> Set-VMReplication -Reverse -VMName VM01 -computername MyReplica.contoso.com
PS C:\> Start-VM -VMName VM01 -computername MyReplica.contoso.com
This example shows the cmdlets you use to perform a planned failover. The first command prepares for the planned failover of a primary virtual machine named VM01 by replicating any pending changes. The second command fails over the Replica virtual machine. The third command switches the Replica virtual machine to a primary virtual machine. The fourth command starts the virtual machine that has been switched from a Replica virtual machine to a primary virtual machine.
Parameters
-AsJob
Runs the command as a background job.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AsTest
Creates a test virtual machine using the chosen recovery point. You can use a test virtual machine to validate a Replica virtual machine. To stop a test failover, use the Stop-VMFailover cmdlet.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ComputerName
Specifies one or more Hyper-V hosts on which failover is to be started. NetBIOS names, IP addresses, and fully-qualified domain names are allowable. The default is the local computer - use "localhost" or a dot (".") to specify the local computer explicitly.
Type: | String[] |
Position: | Named |
Default value: | . |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PassThru
Specifies that a virtual machine object is to be passed through to the pipeline representing the virtual machine on which failover is to be started.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Prepare
Starts the planned failover on the primary virtual machine and replicates any pending changes. To complete the planned failover, use the Set-VMReplication and Start-VM cmdlets as shown in Example 4.
Note: The primary virtual machine must be shut down to prepare it for failover.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VM
Specifies the virtual machine for which failover is to be started.
Type: | VirtualMachine[] |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-VMName
Specifies the name of the virtual machine for which failover is to be started.
Type: | String[] |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-VMRecoverySnapshot
Specifies the recovery snapshot to use during a failover. (This parameter is not required for a planned failover.)
Type: | VMSnapshot |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Outputs
None by default; Microsoft.HyperV.PowerShell.VirtualMachine if -PassThru is specified.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for