Create a VSS application-consistent snapshot - Amazon Elastic Compute Cloud
Install the VSS packageCreate VSS-enabled EBS snapshotsTroubleshoot VSS-enabled EBS snapshots
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create a VSS application-consistent snapshot

This section includes procedures for creating VSS-enabled EBS snapshots by using the Amazon CLI or Amazon Tools for Windows PowerShell. It also contains an advanced method for creating VSS-enabled snapshots using the AWSEC2-ManageVssIO SSM document.

Install the VSS package

Use one of the following command-line procedures to download and install the VSS components to the Windows on EC2 instance.

Install the VSS package using the Amazon CLI

Use the following procedure to download and install the AwsVssComponents package on your instances by using Run Command from the Amazon CLI. The package installs two components: a VSS requestor and a VSS provider. The system copies these components to a directory on the instance, and then registers the provider DLL as a VSS provider.

To install the VSS package by using the Amazon CLI

  • Run the following command to download and install the required VSS components for Systems Manager.

    aws ssm send-command \
    --document-name "AWS-ConfigureAWSPackage" \
    --instance-ids "i-12345678" \
    --parameters '{"action":["Install"],"name":["AwsVssComponents"]}'

Install the VSS package using the Tools for Windows PowerShell

Use the following procedure to download and install the AwsVssComponents package on your instances by using Run Command from the Tools for Windows PowerShell. The package installs two components: a VSS requestor and a VSS provider. The system copies these components to a directory on the instance, and then registers the provider DLL as a VSS provider.

To install the VSS package using the Amazon Tools for Windows PowerShell

  1. Open Amazon Tools for Windows PowerShell and run the following command to specify your user access keys. Your user must either have administrative access for Amazon EC2 or it must have the required permissions granted. For more information, see Setting Up Amazon Systems Manager in the Amazon Systems Manager User Guide.

    Set-AWSCredentials –AccessKey key_name –SecretKey key_name

  2. Run the following command to set the Region for your PowerShell session. The example uses the us-east-2 Region.

    Set-DefaultAWSRegion -Region us-east-2

  3. Run the following command to download and install the required VSS components for Systems Manager.

    Send-SSMCommand -DocumentName AWS-ConfigureAWSPackage -InstanceId "$instance" -Parameter @{'action'='Install';'name'='AwsVssComponents'}

Create VSS-enabled EBS snapshots

You can create VSS-enabled EBS snapshots of stand-alone instances and the primary node of a Windows Server Failover Cluster (WSFC) with shared EBS storage using the Amazon CLI. Before you attempt to create a VSS-enabled snapshot, ensure the requirements are met in Before you begin. For information about creating VSS-enabled snapshots using the Amazon Web Services Management Console, see Create a VSS application-consistent snapshot using the console.

You can use any of the following command-line procedures to create a VSS-enabled snapshot of a stand-alone instance or the primary node of your cluster. The document must be run on the primary node in your cluster. The document will fail on the secondary nodes as they don't have access to the shared disks. If your primary and secondary change dynamically, you can run the Amazon Systems Manager Run Command document on multiple nodes with the expectation that the command will succeed on the primary node and fail on secondary nodes.

Create VSS-enabled EBS snapshots using the Amazon CLI

Use the following procedure to create VSS-enabled EBS snapshots by using the Amazon CLI. When you run the command, you can specify the following parameters:

  • Instance (Required): Specify one or more Amazon EC2 Windows instances. You can either manually specify instances, or you can specify tags.

  • Description (Optional): Specify details about this backup.

  • Tags (Optional): Specify key-value tag pairs that you want to assign to the snapshots. Tags can help you locate, manage, and restore volumes from a list of snapshots. By default, the system populates the tag parameter with a Name key. For the value of this key, specify a name that you want to apply to snapshots created by this process. You can also add custom tags to this list by using the following format: Key=Environment,Value=Test;Key=User,Value=TestUser1.

    This parameter is optional, but we recommended that you tag snapshots. By default, the systems tags snapshots with the device ID, and AppConsistent (for indicating successful, application-consistent VSS-enabled EBS snapshots).

  • Exclude Boot Volume (Optional): Use this parameter to exclude boot volumes from the backup process.

To create VSS-enabled EBS snapshots by using the Amazon CLI

  • Run the following command to create VSS-enabled EBS snapshots.

    aws ssm send-command \
    --document-name "AWSEC2-CreateVssSnapshot" \
    --instance-ids "i-12345678" \
    --parameters '{"ExcludeBootVolume":["False"],"description":["Description"],"tags":["Key=key_name,Value=tag_value"]}'

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed.

You can automate backups by creating a maintenance window task that uses the AWSEC2-CreateVssSnapshot SSM document. For more information, see Working with Maintenance Windows (Console) in the Amazon Systems Manager User Guide.

Create VSS-enabled EBS snapshots using Amazon Tools for Windows PowerShell

Use the following procedure to create VSS-enabled EBS snapshots by using the Amazon Tools for Windows PowerShell. When you run the command, you can specify the following parameters:

  • Instance (Required): Specify one or more Amazon EC2 Windows instances. You can either manually specify instances, or you can specify tags.

  • Description (Optional): Specify details about this backup.

  • Tags (Optional): Specify key-value tag pairs that you want to assign to the snapshots. Tags can help you locate, manage, and restore volumes from a list of snapshots. By default, the system populates the tag parameter with a Name key. For the value of this key, specify a name that you want to apply to snapshots created by this process. You can also add custom tags to this list by using the following format: Key=Environment,Value=Test;Key=User,Value=TestUser1.

    This parameter is optional, but we recommend that you tag snapshots. By default, the systems tags snapshots with the device ID, and AppConsistent (for indicating successful, application-consistent VSS-enabled EBS snapshots).

  • Exclude Boot Volume (Optional): Use this parameter to exclude boot volumes from the backup process.

To create VSS-enabled EBS snapshots by using Amazon Tools for Windows PowerShell

  1. Open Amazon Tools for Windows PowerShell and run the following command to specify your user access keys. Your user must either have administrative access for Amazon EC2 or it must have the required permissions granted. For more information, see Setting Up Amazon Systems Manager in the Amazon Systems Manager User Guide.

    Set-AWSCredentials –AccessKey key_name –SecretKey key_name

  2. Execute the following command to set the Region for your PowerShell session. The example uses the us-east-2 Region.

    Set-DefaultAWSRegion -Region us-east-2

  3. Execute the following command to create VSS-enabled EBS snapshots.

    Send-SSMCommand -DocumentName AWSEC2-CreateVssSnapshot -InstanceId "$instance" -Parameter @{'ExcludeBootVolume'='False';'description'='a_description'
;'tags'='Key=key_name,Value=tag_value'}

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed. If the command successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS snapshots.

You can automate backups by creating a maintenance window task that uses the AWSEC2-CreateVssSnapshot SSM document. For more information, see Working with Maintenance Windows (Console) in the Amazon Systems Manager User Guide.

Create VSS-enabled EBS snapshots using the AWSEC2-ManageVssIO SSM document (advanced)

You can use the following script and the pre-defined AWSEC2-ManageVssIO SSM document to temporarily pause I/O, create VSS-enabled EBS snapshots, and restart I/O. This process runs in the context of the user who runs the command. If the user has sufficient permission to create and tag snapshots, then Amazon Systems Manager can create and tag VSS-enabled EBS snapshots without the need for the additional IAM snapshot role on the instance.

In contrast, the AWSEC2-CreateVssSnapshot document requires that you assign the IAM snapshot role to each instance for which you want to create EBS snapshots. If you don’t want to provide additional IAM permissions to your instances for policy or compliance reasons, then you can use the following script.

Before you begin

Note the following important details about this process:

  • This process uses a PowerShell script (CreateVssSnapshotAdvancedScript.ps1) to take snapshots of all volumes on the instances you specify, except root volumes. If you need to take snapshots of root volumes, then you must use the AWSEC2-CreateVssSnapshot SSM document.

  • The script calls the AWSEC2-ManageVssIO document twice. The first time with the Action parameter set to Freeze, which pauses all I/O on the instances. The second time, the Action parameter is set to Thaw, which forces I/O to resume.

  • Don't attempt to use the AWSEC2-ManageVssIO document without using the CreateVssSnapshotAdvancedScript.ps1 script. A limitation in VSS requires that the Freeze and Thaw actions be called no more than ten seconds apart, and manually calling these actions without the script could result in errors.

To create VSS-enabled EBS snapshots by using the AWSEC2-ManageVssIO SSM document

  1. Open Amazon Tools for Windows PowerShell and run the following command to specify your user access keys. Your user must either have administrative access for Amazon EC2 or it must have the required permissions granted. For more information, see Setting Up Amazon Systems Manager in the Amazon Systems Manager User Guide.

    Set-AWSCredentials –AccessKey key_name –SecretKey key_name

  2. Execute the following command to set the Region for your PowerShell session. The example uses the us-east-2 Region.

    Set-DefaultAWSRegion -Region us-east-2

  3. Download the CreateVssSnapshotAdvancedScript.zip file and extract the file contents.

  4. Open CreateVssSnapshotAdvancedScript.ps1 in a text editor, edit the sample call at the bottom of the script with a valid EC2 instance ID, snapshot description, and desired tag values, and then run the script from PowerShell.

If successful, the command populates the list of EBS snapshots with the new snapshots. You can locate these snapshots in the list of EBS snapshots by searching for the tags you specified, or by searching for AppConsistent. If the command execution failed, view the command output for details about why the execution failed. If the command was successfully completed, but a specific volume backup failed, you can troubleshoot the failure in the list of EBS volumes.

Troubleshoot VSS-enabled EBS snapshots

General: Checking the log files

If you experience problems or receive error messages when creating VSS-enabled EBS snapshots, you can view the command output in the Systems Manager console. You can also view the following logs:

  • %ProgramData%\Amazon\SSM\InstanceData\InstanceID\document\orchestration\SSMCommandID\awsrunPowerShellScript\runPowerShellScript\stdout

  • %ProgramData%\Amazon\SSM\InstanceData\InstanceID\document\orchestration\SSMCommandID\awsrunPowerShellScript\runPowerShellScript\stderr

You can also open the Event Viewer Windows application and choose Windows Logs, Application to view additional logs. To see events specifically from the EC2 Windows VSS Provider and the Volume Shadow Copy Service, filter by Source on the terms Ec2VssSoftwareProvider and VSS.

Error: Thaw pipe connection timed out, error on thaw, timeout waiting for VSS Freeze, or other timeout errors

The EC2 Windows VSS Provider might time out due to activity or services on the instance preventing VSS-enabled snapshots from proceeding in a timely manner. The Windows VSS Framework provides a non-configurable 10-second window during which communication to the file system is paused. During this time, AWSEC2-CreateVssSnapshot snapshots your volumes.

The following items can cause the EC2 Windows VSS Provider to run into time limits during a snapshot:

  • Excessive I/O to a volume

  • Slow responsiveness of the EC2 API on the instance

  • Fragmented volumes

  • Incompatibility with some antivirus software

  • Issues with a VSS Application writer

  • When Module Logging is enabled for a large number of PowerShell modules, that can cause PowerShell scripts to run slowly

Usually, when running into time limits with the AWSEC2-CreateVssSnapshot command, the cause is related to the workload on the instance being too high at the time of backup. The following actions can help you take a successful snapshot:

  • Retry the AWSEC2-CreateVssSnapshot command to see if the snapshot attempt is successful. If retrying succeeds in some cases, reducing the instance load might make snapshots more successful.

  • Wait a while for the workload on the instance to decrease, and retry the AWSEC2-CreateVssSnapshot command. Alternatively, you can attempt snapshots when the instance is known to be under low stress.

  • Attempt VSS snapshots when the antivirus software on the system is turned off. If this resolves the issue, refer to the antivirus software instructions and configure it to allow VSS snapshots.

  • If there are a lot of EC2 API calls being made at the time of the snapshot, API throttling might cause the snapshots to take too long to start. Try taking snapshots again when there is less API activity in the account.

  • Run the command vssadmin list writers in a shell and see if it reports any errors in the Last error field for any writers on the system. If any writers report a time out error, consider retrying snapshots when the instance is under less load.

  • If one or more PowerShell modules have Group Policies that enable PowerShell module logging, try temporarily disabling the logging before you take a snapshot.

Error: Cannot invoke method. Method invocation is supported only on core types in this language mode.

You will encounter this error when the PowerShell language mode is not set to FullLanguage. The AWSEC2-CreateVssSnapshot and AWSEC2-ManageVssIo SSM documents require PowerShell to be configured to FullLanguage mode.

To verify the language mode, run the following command on the instance in a PowerShell console:

$ExecutionContext.SessionState.LanguageMode

For more information about language modes, see about_Language_Modes in the Microsoft documentation.