Configuring S3 Object Lock - Amazon Simple Storage Service
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).

Configuring S3 Object Lock

With Amazon S3 Object Lock, you can store objects in Amazon S3 by using a write-once-read-many (WORM) model. You can use S3 Object Lock to prevent an object from being deleted or overwritten for a fixed amount of time or indefinitely. For general information about Object Lock capabilities, see Using S3 Object Lock.

Before you lock any objects, you must enable S3 Versioning and Object Lock on a bucket. Afterward, you can set a retention period, a legal hold, or both.

To work with Object Lock, you must have certain permissions. For a list of the permissions related to various Object Lock operations, see Required permissions.

Important
  • After you enable Object Lock on a bucket, you can't disable Object Lock or suspend versioning for that bucket.

  • S3 buckets with Object Lock can't be used as destination buckets for server access logs. For more information, see Logging requests with server access logging.

Enable Object Lock when creating a new S3 bucket

You can enable Object Lock when creating a new S3 bucket by using the Amazon S3 console, Amazon Command Line Interface (Amazon CLI), Amazon SDKs, or Amazon S3 REST API.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. Choose Create bucket.

    The Create bucket page opens.

  4. For Bucket name, enter a name for your bucket.

    Note

    After you create a bucket, you can't change its name. For more information about naming buckets, see Bucket naming rules.

  5. For Region, choose the Amazon Web Services Region where you want the bucket to reside.

  6. Under Object Ownership, choose to disable or enable access control lists (ACLs) and control ownership of objects uploaded in your bucket.

  7. Under Block Public Access settings for this bucket, choose the Block Public Access settings that you want to apply to the bucket.

  8. Under Bucket Versioning, choose Enabled.

    Object Lock works only with versioned buckets.

  9. (Optional) Under Tags, you can choose to add tags to your bucket. Tags are key-value pairs that are used to categorize storage and allocate costs.

  10. Under Advanced settings, find Object Lock and choose Enable.

    You must acknowledge that enabling Object Lock will permanently allow objects in this bucket to be locked.

  11. Choose Create bucket.

The following create-bucket example creates a new S3 bucket named DOC-EXAMPLE-BUCKET1 with Object Lock enabled:

aws s3api create-bucket --bucket DOC-EXAMPLE-BUCKET1 --object-lock-enabled-for-bucket

For more information and examples, see create-bucket in the Amazon CLI Command Reference.

Note

You can run Amazon CLI commands from the console by using Amazon CloudShell. Amazon CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the Amazon Web Services Management Console. For more information, see What is CloudShell? in the Amazon CloudShell User Guide.

You can use the REST API to create a new S3 bucket with Object Lock enabled. For more information, see CreateBucket in the Amazon Simple Storage Service API Reference.

Enable Object Lock on an existing S3 bucket

You can enable Object Lock for an existing S3 bucket by using the Amazon S3 console, the Amazon CLI, Amazon SDKs, or Amazon S3 REST API.

Note

Object Lock works only with versioned buckets.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. In the Buckets list, choose the name of the bucket that you want to enable Object Lock on.

  4. Choose the Properties tab.

  5. Under Properties, scroll down to the Object Lock section, and choose Edit.

  6. Under Object Lock, choose Enable.

    You must acknowledge that enabling Object Lock will permanently allow objects in this bucket to be locked.

  7. Choose Save changes.

The following put-object-lock-configuration example command sets a 50-day Object Lock retention period on a bucket named DOC-EXAMPLE-BUCKET1:

aws s3api put-object-lock-configuration --bucket DOC-EXAMPLE-BUCKET1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}'

For more information and examples, see put-object-lock-configuration in the Amazon CLI Command Reference.

Note

You can run Amazon CLI commands from the console by using Amazon CloudShell. Amazon CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the Amazon Web Services Management Console. For more information, see What is CloudShell? in the Amazon CloudShell User Guide.

You can use the Amazon S3 REST API to enable Object Lock on an existing S3 bucket. For more information, see PutObjectLockConfiguration in the Amazon Simple Storage Service API Reference.

You can set or remove a legal hold on an S3 object by using the Amazon S3 console, Amazon CLI, Amazon SDKs, or Amazon S3 REST API.

Important
  • If you want to set a legal hold on an object, the object's bucket must already have Object Lock enabled.

  • When you PUT an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings.

For more information, see Legal holds.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. In the Buckets list, choose the name of the bucket that contains the object that you want to set or modify a legal hold on.

  4. In the Objects list, select the object that you want to set or modify a legal hold on.

  5. On the Object properties page, find the Object Lock legal hold section, and choose Edit.

  6. Choose Enable to set a legal hold or Disable to remove a legal hold.

  7. Choose Save changes.

The following put-object-legal-hold example sets a legal hold on the object my-image.fs in the bucket named DOC-EXAMPLE-BUCKET1:

aws s3api put-object-legal-hold --bucket DOC-EXAMPLE-BUCKET1 --key my-image.fs --legal-hold="Status=ON"

The following put-object-legal-hold example removes a legal hold on the object my-image.fs in the bucket named DOC-EXAMPLE-BUCKET1:

aws s3api put-object-legal-hold --bucket DOC-EXAMPLE-BUCKET1 --key my-image.fs --legal-hold="Status=OFF"

For more information and examples, see put-object-legal-hold in the Amazon CLI Command Reference.

Note

You can run Amazon CLI commands from the console by using Amazon CloudShell. Amazon CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the Amazon Web Services Management Console. For more information, see What is CloudShell? in the Amazon CloudShell User Guide.

You can use the REST API to set or modify a legal hold on an object. For more information, see PutObjectLegalHold in the Amazon Simple Storage Service API Reference.

Set or modify a retention period on an S3 object

You can set or modify a retention period on an S3 object by using the Amazon S3 console, Amazon CLI, Amazon SDKs, or Amazon S3 REST API.

Important
  • If you want to set a retention period on an object, the object's bucket must already have Object Lock enabled.

  • When you PUT an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings.

  • The only way to delete an object under the compliance mode before its retention date expires is to delete the associated Amazon Web Services account.

For more information, see Retention periods.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. In the Buckets list, choose the name of the bucket that contains the object that you want to set or modify a retention period on.

  4. In the Objects list, select the object that you want to set or modify a retention period on.

  5. On the Object properties page, find the Object Lock retention section, and choose Edit.

  6. Under Retention, choose Enable to set a retention period or Disable to remove a retention period.

  7. If you chose Enable, under Retention mode, choose either Governance mode or Compliance mode. For more information, see Retention modes.

  8. Under Retain until date, choose the date that you want to have the retention period end on. During this period, your object is WORM-protected and can't be overwritten or deleted. For more information, see Retention periods.

  9. Choose Save changes.

The following put-object-retention example sets a retention period on the object my-image.fs in the bucket named DOC-EXAMPLE-BUCKET1 until January 1, 2025:

aws s3api put-object-retention --bucket DOC-EXAMPLE-BUCKET1 --key my-image.fs --retention='{ "Mode": "GOVERNANCE", "RetainUntilDate": "2025-01-01T00:00:00" }'

For more information and examples, see put-object-retention in the Amazon CLI Command Reference.

Note

You can run Amazon CLI commands from the console by using Amazon CloudShell. Amazon CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the Amazon Web Services Management Console. For more information, see What is CloudShell? in the Amazon CloudShell User Guide.

You can use the REST API to set a retention period on an object. For more information, see PutObjectRetention in the Amazon Simple Storage Service API Reference.

Set or modify a default retention period on an S3 bucket

You can set or modify a default retention period on an S3 bucket by using the Amazon S3 console, Amazon CLI, Amazon SDKs, or Amazon S3 REST API. You specify a duration, in either days or years, for how long to protect every object version placed in the bucket.

Important
  • If you want to set a default retention period on a bucket, the bucket must already have Object Lock enabled.

  • When you PUT an object version that has an explicit individual retention mode and period in a bucket, the object version's individual Object Lock settings override any bucket property retention settings.

  • The only way to delete an object under the compliance mode before its retention date expires is to delete the associated Amazon Web Services account.

For more information, see Retention periods.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Buckets.

  3. In the Buckets list, choose the name of the bucket that you want to set or modify a default retention period on.

  4. Choose the Properties tab.

  5. Under Properties, scroll down to the Object Lock section, and choose Edit.

  6. Under Default retention, choose Enable to set a default retention or Disable to remove a default retention.

  7. If you chose Enable, under Retention mode, choose either Governance mode or Compliance mode. For more information, see Retention modes.

  8. Under Default retention period, choose the number of days or years that you want the retention period to last for. Objects placed in this bucket will be locked for this number of days or years. For more information, see Retention periods.

  9. Choose Save changes.

The following put-object-lock-configuration example command sets a 50-day Object Lock retention period on the bucket named DOC-EXAMPLE-BUCKET1 by using compliance mode:

aws s3api put-object-lock-configuration --bucket DOC-EXAMPLE-BUCKET1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}'

The following put-object-lock-configuration example removes the default retention configuration on a bucket:

aws s3api put-object-lock-configuration --bucket DOC-EXAMPLE-BUCKET1 --object-lock-configuration='{ "ObjectLockEnabled": "Enabled"}'

For more information and examples, see put-object-lock-configuration in the Amazon CLI Command Reference.

Note

You can run Amazon CLI commands from the console by using Amazon CloudShell. Amazon CloudShell is a browser-based, pre-authenticated shell that you can launch directly from the Amazon Web Services Management Console. For more information, see What is CloudShell? in the Amazon CloudShell User Guide.

You can use the REST API to enable Object Lock on an existing S3 bucket. For more information, see PutObjectLockConfiguration in the Amazon Simple Storage Service API Reference.