Welcome to the upcoming version of the MinIO Documentation! The content on this page is under active development and may change at any time. If you can't find what you're looking for, check our legacy documentation. Thank you for your patience.

MinIO Object Locking

Overview

MinIO Object Locking (“Object Retention”) enforces Write-Once Read-Many (WORM) immutability to protect versioned objects from deletion. MinIO supports both duration based object retention and indefinite Legal Hold retention.

MinIO Object Locking provides key data retention compliance and meets SEC17a-4(f), FINRA 4511(C), and CFTC 1.31(c)-(d) requirements as per Cohasset Associates.

MinIO object locking is feature and API compatible with AWS S3. This page summarizes Object Locking / Retention concepts as implemented by MinIO. See the AWS S3 documentation on How S3 Object Lock works for additional resources.

You can only enable object locking during bucket creation as per S3 behavior. You cannot enable object locking on a bucket created without locking enabled. You can then configure object retention rules at any time. Object locking requires versioning and enables the feature implicitly.

Interaction with Versioning

Objects held under WORM locked are immutable until the lock expires or is explicitly lifted. Locking is per-object version, where each version is independently immutable.

If an application performs an unversioned delete operation on a locked object, the operation produces a delete marker. Attempts to explicitly delete any WORM-locked object fail with an error. Delete Markers are not eligible for protection under WORM locking. See the S3 documentation on Managing delete markers and object lifecycles for more information.

For example, consider the following bucket with GOVERNANCE Mode locking enabled by default:

$ mc ls --versions play/locking-guide

  [DATETIME]    29B 62429eb1-9cb7-4dc5-b507-9cc23d0cc691 v3 PUT data.csv
  [DATETIME]    32B 78b3105a-02a1-4763-8054-e66add087710 v2 PUT data.csv
  [DATETIME]    23B c6b581ca-2883-41e2-9905-0a1867b535b8 v1 PUT data.csv

Attempting to perform a delete on a specific version of data.csv fails due to the object locking settings:

$ mc rm --version-id 62429eb1-9cb7-4dc5-b507-9cc23d0cc691 play/data.csv

  Removing `play/locking-guide/data.csv` (versionId=62429eb1-9cb7-4dc5-b507-9cc23d0cc691).
  mc: <ERROR> Failed to remove `play/locking-guide/data.csv`.
      Object, 'data.csv (Version ID=62429eb1-9cb7-4dc5-b507-9cc23d0cc691)' is
      WORM protected and cannot be overwritten

Attempting to perform an unversioned delete on data.csv succeeds and creates a new DeleteMarker for the object:

$ mc rm play/locking-guide/data.csv

  [DATETIME]     0B acce329f-ad32-46d9-8649-5fe8bf4ec6e0 v4 DEL data.csv
  [DATETIME]    29B 62429eb1-9cb7-4dc5-b507-9cc23d0cc691 v3 PUT data.csv
  [DATETIME]    32B 78b3105a-02a1-4763-8054-e66add087710 v2 PUT data.csv
  [DATETIME]    23B c6b581ca-2883-41e2-9905-0a1867b535b8 v1 PUT data.csv

Interaction with Lifecycle Management

MinIO object expiration respects any active object lock and retention settings for objects covered by the expiration rule.

  • For expiration rules operating on only the current object version, MinIO creates a Delete Marker for the locked object.

  • For expiration rules operating on non-current object versions, MinIO can only expire the non-current versions after the retention period has passed or has been explicitly lifted (e.g. Legal Holds).

For example, consider the following bucket with GOVERNANCE Mode locking enabled by default for 45 days:

$ mc ls --versions play/locking-guide

  [7D]    29B 62429eb1-9cb7-4dc5-b507-9cc23d0cc691 v3 PUT data.csv
  [30D]    32B 78b3105a-02a1-4763-8054-e66add087710 v2 PUT data.csv
  [60D]    23B c6b581ca-2883-41e2-9905-0a1867b535b8 v1 PUT data.csv

Creating an expiration rule for current objects older than 7 days results in a Delete Marker for the object:

$ mc ls --versions play/locking-guide

  [0D]     0B acce329f-ad32-46d9-8649-5fe8bf4ec6e0 v4 DEL data.csv
  [7D]    29B 62429eb1-9cb7-4dc5-b507-9cc23d0cc691 v3 PUT data.csv
  [30D]    32B 78b3105a-02a1-4763-8054-e66add087710 v2 PUT data.csv
  [60D]    23B c6b581ca-2883-41e2-9905-0a1867b535b8 v1 PUT data.csv

However, an expiration rule for non-current objects older than 7 days would only take effect after the configured WORM lock expires. Since the bucket has a 45 day GOVERNANCE retention set, only the v1 version of data.csv is unlocked and therefore eligible for deletion.

Tutorials

Create Bucket with Object Locking Enabled

You must enable object locking during bucket creation as per S3 behavior. You can create a bucket with object locking enabled using the MinIO Console, the MinIO mc CLI, or using an S3-compatible SDK.

Select the Buckets section of the MinIO Console to access bucket creation and management functions. Select the bucket row from the list of buckets. You can use the Search bar to filter the list.

MinIO Console Bucket Management

Click the Create Bucket button to open the bucket creation model. Toggle the Object Locking selector to enable object locking on the bucket.

MinIO Console Bucket creation

Use the mc mb command with the --with-lock option to create a bucket with object locking enabled:

mc mb --with-lock ALIAS/BUCKET
  • Replace ALIAS with the alias of a configured MinIO deployment.

  • Replace BUCKET with the name of the bucket to create.

Configure Bucket-Default Object Retention

You can configure object locking rules (“object retention”) using the MinIO Console, the MinIO mc CLI, or using an S3-compatible SDK.

MinIO supports setting both bucket-default and per-object retention rules. The following examples set bucket-default retention. For per-object retention settings, defer to the documentation for the PUT operation used by your preferred SDK.

Select the Buckets section of the MinIO Console to access bucket creation and management functions. Select the bucket row from the list of buckets. You can use the Search bar to filter the list.

MinIO Console Bucket Management

From the Bucket view, look for the Retention section and click Enabled. This section is only visible if the bucket was created with object locking enabled.

MinIO Console Bucket Management

From the Set Retention Configuration modal, set the desired bucket default retention settings.

MinIO Console Bucket Default Retention
  • For Retention Mode, select either COMPLIANCE or GOVERNANCE.

  • For Duration, select the retention duration units of Days or Years.

  • For Retention Validity, set the duration of time for which MinIO holds objects under the specified retention mode for the bucket.

Use the mc retention command with the --recursive and --default options to set the default retention mode for a bucket:

mc retention set --recursive --default MODE DURATION ALIAS/BUCKET
  • Replace MODE with either either COMPLIANCE or GOVERNANCE.

  • Replace DURATION with the duration for which the object lock remains in effect.

  • Replace ALIAS with the alias of a configured MinIO deployment.

  • Replace BUCKET with the name of the bucket on which to set the default retention rule.

Object Retention Modes

MinIO implements the following S3 Object Locking Modes:

Mode

Summary

GOVERNANCE Mode

Prevents any operation that would mutate or modify the object or its locking settings by non-privileged users.

Users with the s3:BypassGovernanceRetention permission on the bucket or object can modify the object or its locking settings.

MinIO lifts the lock automatically after the configured retention rule duration has passed.

COMPLIANCE Mode

Prevents any operation that would mutate or modify the object or its locking settings.

No MinIO user can modify the object or its settings, including the MinIO root user.

MinIO lifts the lock automatically after the configured retention rule duration has passed.

GOVERNANCE Mode

An object under GOVERNANCE lock is protected from write operations by non-privileged users.

GOVERNANCE locked objects enforce managed-immutability for locked objects, where users with the s3:BypassGovernanceRetention action can modify the locked object, change the retention duration, or lift the lock entirely. Bypassing GOVERNANCE retention also requires setting the x-amz-bypass-governance-retention:true header as part of the request.

The MinIO GOVERNANCE lock is functionally identical to the S3 GOVERNANCE mode.

COMPLIANCE Mode

An object under COMPLIANCE lock is protected from write operations by all users, including the MinIO root user.

COMPLIANCE locked objects enforce complete immutability for locked objects. You cannot change or remove the lock before the configured retention duration has passed.

The MinIO COMPLIANCE lock is functionally identical to the S3 GOVERNANCE mode.