Start-VMFailover

Start-VMFailover

Starts failover on a virtual machine.

Syntax

Parameter Set: VMName
Start-VMFailover [-VMName] <String[]> [-AsJob] [-ComputerName <String[]> ] [-PassThru] [-Prepare] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: VMName_Test
Start-VMFailover [-VMName] <String[]> -AsTest [-AsJob] [-ComputerName <String[]> ] [-PassThru] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: VMObject
Start-VMFailover [-VM] <VirtualMachine[]> [-AsJob] [-PassThru] [-Prepare] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: VMObject_Test
Start-VMFailover [-VM] <VirtualMachine[]> -AsTest [-AsJob] [-PassThru] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: VMSnapshot
Start-VMFailover [-VMRecoverySnapshot] <VMSnapshot> [-AsJob] [-PassThru] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: VMSnapshot_Test
Start-VMFailover [-VMRecoverySnapshot] <VMSnapshot> -AsTest [-AsJob] [-PassThru] [-Confirm] [-WhatIf] [ <CommonParameters>]

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

Parameters

-AsJob

Runs the command as a background job.

Aliases

none

Required?

false

Position?

named

Default Value

none

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.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ComputerName<String[]>

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.

Aliases

none

Required?

false

Position?

named

Default Value

.

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.

Aliases

none

Required?

false

Position?

named

Default Value

none

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.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-VM<VirtualMachine[]>

Specifies the virtual machine for which failover is to be started.

Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

True (ByValue)

Accept Wildcard Characters?

false

-VMName<String[]>

Specifies the name of the virtual machine for which failover is to be started.

Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

True (ByValue)

Accept Wildcard Characters?

false

-VMRecoverySnapshot<VMSnapshot>

Specifies the recovery snapshot to use during a failover. (This parameter is not required for a planned failover.)

Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

True (ByValue)

Accept Wildcard Characters?

false

-Confirm

Prompts you for confirmation before running the cmdlet.

Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see    about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • None by default; Microsoft.Virtualization.Powershell.VirtualMachine if –PassThru is specified.

Examples

Example 1

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.

PS C:\> Get-VMSnapshot VM01 –Name Snapshot01 | Start-Failover

Example 2

This example starts a test failover of a virtual machine named VM01.

PS C:\> Start-VMFailover VM01 -AsTest

Example 3

Starts a test failover of a virtual machine named VM01 with recovery point Snapshot01.

PS C:\> Get-VMSnapshot VM01 –Name Snapshot01 | Start-Failover -AsTest

Example 4

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 second command fails over the Replica virtual machine. The third command switches the Replica virtual machine to a primary virtual machine. The third command starts the virtual machine that has been switched from a Replica virtual machine to a primary virtual machine.

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