Legal hold - Amazon Backup
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).

Legal hold

A legal hold is an administrative tool that helps prevent backups from being deleted while under a hold. While the hold is in place, backups under a hold cannot be deleted and lifecycle policies that would alter the backup status (such as transition to a Deleted state) are delayed until the legal hold is removed. A backup can have more than one legal hold.

Legal holds can be applied to one or more backups (also known as recovery points) created by Amazon Backup if their lifecycles allow it. A type of backup called a continuous backup has a maximum lifecycle of 35 days. Legal holds will not extend a continuous backup lifecycle.

When a legal hold is created, it can take into account specific filtering criteria, such as resource types and resource IDs. Additionally, you can define the creation date range of backups you wish to include in a legal hold. Legal holds and backups have a many:many relationship, meaning a backup can have more than legal hold and a legal hold can include more than one backup. Each account can have a maximum of 50 legal holds active at one time.

Legal holds apply only to the original backup on which they are placed. When a backup is copied across Regions or accounts (if the resource supports it), it does not retain or carry its legal hold with it. A legal hold, like other resources, has a unique ARN (Amazon Resource Name) associated with it. Only recovery points created by Amazon Backup can be part of a legal hold.

Note that while Amazon Backup Vault Lock provides additional protections and immutability to a vault, a legal hold provides additional protection against deletion individual backups (recovery points). The legal hold does not expire and will retain the data within the backup indefinitely. The hold remains active until the hold is released by a user with sufficient IAM permissions.

Create a legal hold

Legal holds can be added and released only by users who have specific IAM permissions. To check your permissions or to grant permissions, log into the Amazon Identity and Access Management console.

When a legal hold is created, it contains only recovery points that have already been created. Backups (recovery points) with a status of EXPIRED or DELETING will not be included in the legal hold. Recovery points (backups) with the status of CREATING may not be included in the legal hold, depending on the time of completion.

Legal holds can be added to existing backups using the Amazon Backup console or programmatically.

Create a legal hold using the console

As you create a legal hold via the console, you will need to configure several elements, including its title, its description, its scope, and (optionally) any tags you wish to include to help with organization and filtering.

  1. Open the Amazon Backup console at https://console.amazonaws.cn/backup.

  2. In the dashboard in the left of the console, find My Account. Click Legal holds.

  3. Click Add legal hold.

  4. There will be three panels shown: Legal hold details, Legal hold scope, and Legal hold tags.

    1. Under Legal hold details, enter a legal hold title and a description for the hold in the text boxes provided.

    2. In the panel Legal hold scope, choose how you wish to select the resource to include in the hold. When you create a hold, you choose which method you want to select the resources that will be within the legal hold. You can choose to include one of the following:

      • Specific resource types and IDs;

      • Select backup vaults;

      • Include all resources types or all backup vaults within your account

    3. Specify the date range of your legal hold. Enter the dates in the YYYY:MM:DD format (dates are inclusive).

    4. Optionally, you can add tags for the hold you are creating. Tags can help categorize the hold for future reference and organization. You can add up to 50 tags total.

  5. When you are satisfied with the configuration of your new legal hold, click the button Add new hold.

You can specify the following metadata:

Title Description VaultArns Resources FromDate ToDate DateRange // Must contain FromDate and ToDate; dates cannot be in the past LegalHoldTags // optional ; if included, can have up to 5 tags: "tag1", "tag2"
  1. Copy the following JSON template and input it into the CLI.

    { Title: "Your name for the legal hold" Description: "Your description of the legal hold" ResourceSelection: { VaultArns: string[], // only one of vaultArns or resourceIds is allowed; error will return if both are included Resources: string[] } ResourceFilters: { DateRange: { FromDate: DateTime; ToDate: DateTime; } // both required: future DateTime values will not be allowed } LegalHoldTags: { // optional, up to 50 tags name: value, } }
  2. Review this example for reference.

    { "Title": "a legal hold", "Description": "some description", "ResourceSelection": { "VaultArns": [ "arn:aws:backup:Region:Account ID:backup-vault:backup vault name" ] } "ResourceFilters": { "DateRange": { "FromDate": 1516925490.087, "ToDate": 1517525490.087 } } "LegalHoldTags": { "tag1":"value1", "tag2": "value2", } }
  3. Review the response, which may contain elements of the following:

    { "Title": "a legal hold", "Status": "CREATING", "Description": "some description", "LegalHoldArn": string, "ResourceSelection": { "VaultArns": [ "arn:aws:backup:Region:Account ID:backup-vault:backup vault name" ] } "ResourceFilters": { "DateRange": { "FromDate": 1516925490.087, "ToDate": 1517525490.087 } } "LegalHoldTags": { "tag1":"value1", "tag2": "value2", } }

View legal holds

You can see legal hold details in the Amazon Backup console or programmatically.

To view all legal holds within an account using the Backup console,

  1. Open the Amazon Backup console at https://console.amazonaws.cn/backup.

  2. Using the left part of the dashboard, under My account, click Legal holds.

  3. The legal hold table displays the title, status, description, ID, and creation date of existing holds. Click on the carat (down arrow) next to the table header to filter the table by the selected column.

To view all legal holds programmatically, you can use the following API calls:

GetLegalHold: This action returns details for a specified legal hold. The details are the body of a legal hold in JSON format, in addition to metadata.

ListRecoveryPointsByLegalHold: This action returns recovery point ARNs (Amazon Resource Name) about the recovery points included in the specified legal hold. You need to include the parameters: nextToken and maxResults in your request.

The following JSON template can be used for GetLegalHold. You can copy it and input it into the CLI.

GET /legal-holds/{legalHoldId} HTTP/1.1 Request empty body Response { Title: string, Status: LegalHoldStatus, Description: string, // 280 chars max CancelDescription: string, // this is provided during cancel // 280 chars max LegalHoldId: string, LegalHoldArn: string, CreatedTime: number, CanceledTime: number, ResourceSelection: { VaultArns: [ string ] Resources: [ string ] }, ResourceFilters: { DateRange: { FromDate: number, ToDate: number } } }

The following JSON template can be used for ListLegalHolds. You can copy it and input it into the CLI.

GET /legal-holds/ &maxResults=MaxResults &nextToken=NextToken Request empty body url params: MaxResults: number // optional, NextToken: string // optional status: Valid values: CREATING | ACTIVE | CANCELED | CANCELING maxResults: 1-1000 Response { NextToken: token, LegalHolds: [ Title: string, Status: string, Description: string, // 280 chars max CancelDescription: string, // this is provided during cancel // 280 chars max LegalHoldId: string, LegalHoldArn: string, CreatedTime: number, CanceledTime: number, ] }

For details on the returned information, see GetLegalHold and ListLegalHolds in our API guide.

Status Description
CREATING Requested recovery points are in the process of being held, and delete requests of those recovery points may be successful since the hold hasn't finished being created.
ACTIVE The legal hold has been created, All recovery points listed under this legal hold are held.
CANCELLING Legal holds are in the process of being removed, and delete requests of recovery points under the hold may succeed.
CANCELED Legal hold is fully released and no longer has any effect. Recovery points can be deleted.

Release a legal hold

Legal holds will remain with one or more backups (recovery points) until they are removed by a user with sufficient IAM permissions. Removing a legal hold is also known as cancelling, deleting, or releasing a legal hold. The console uses the term release while the API uses the command cancelLegalHold. Removing a legal hold eliminates it from all backups to which it was attached.

To release a hold using the console,

  1. Open the Amazon Backup console at https://console.amazonaws.cn/backup.

  2. Enter the description you would like associated with the release.

  3. Review the details, then click Release hold.

  4. When the Release hold dialogue box appears, confirm your intent to release the hold by typing confirm into the text box.

    1. Check the box that acknowledges you are cancelling the hold.

On the Legal holds page you can see all your holds. If the release was successful, the status of that hold will be shown as Released.

To remove a hold programmatically, use the API call CancelLegalHold. You can specify the following metadata:

CancelDescription: String DeleteAfterDays: number // Optional. Default equals 30 days. This specifies number (in days to keep legal hold record after cancellation. This applies to the actual legal hold record only. Recovery points are unlocked as soon as cancelation processes and are not subject to this date.
  1. Copy the following JSON template and input it into the CLI.

    POST /legal-holds/{legalHoldId} Request { CancelDescription: String DeleteAfterDays: number // optional } DeleteAfterDays: optional. Defaults to 180 days. how long to keep legal hold record after canceled. This applies to the actual legal hold record only. Recovery points are unlocked as soon as cancelation processes and are not subject to this date. Response Empty body 200 if successful other standard codes
  2. Review the response, which may contain elements of the following:

    POST /legal-holds/abc1-4df0-989f-l9af HTTP/1.1 Request { CancelDescription: "Canceling because case is closed 4/21" }

For more information, see CancelLegalHold.