For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
See how MongoDB 9.0 delivers up to 2x higher throughput.
MongoDB Branding Shape
Register now >
Docs Menu
Docs Home
/
Management
/
Ops Manager
Docs Home
/
Management
/
Ops Manager
Docs Home
/
Management
/
Ops Manager

Immutable S3 Backups with Object Lock

Ops Manager can store backups, including snapshots and oplogs, in an S3 or S3-compatible object store by writing backup data as blocks to an S3 bucket and tracking metadata in the Ops Manager application database. With immutable S3 backups, Ops Manager integrates with S3 Object Lock or an equivalent to provide the following capabilities:

  • Store backup data and backup metadata together in the S3 bucket.

  • Protect backup objects from deletion or modification until a defined retention period expires, enforced by the object store.

  • Import a full point-in-time restore chain, snapshot and oplog together, from an Object-Lock-enabled bucket into a new or rebuilt Ops Manager deployment for disaster recovery or migration.

Use this feature to protect backups against malicious or accidental deletion, such as ransomware attacks or operator error. You can restore backups in a new Ops Manager instance using only what you store in S3.

This guide covers immutable S3 backups for Ops Manager deployments that you install and manage directly on a host. If you deploy Ops Manager using the MongoDB Controllers for Kubernetes Operator (MCK), see the Ops Manager resource specification example.

Important

Ops Manager supports immutable S3 snapshots starting in version 8.0.19. Immutable S3 oplogs, which extend this protection to support point-in-time restore from a fully immutable, importable backup, require version 9.0 or 8.0.28.

How Immutable S3 Backups Work

After you configure an S3 snapshot store with an Object-Lock-enabled bucket and enable immutable backups:

  • Ops Manager writes snapshot blocks and the metadata required for restore into the S3 bucket, instead of keeping metadata only in the Ops Manager application database.

  • If configured, Ops Manager extends the Object Lock retention for each snapshot so that the object store prevents deletion or modification before the backup job retention window ends.

  • Ops Manager can discover and import these immutable snapshots from a pre-populated bucket into another Ops Manager instance by reading only what the S3 bucket stores.

If you also configure an S3 oplog store with Object Lock enabled:

  • Ops Manager writes oplog slices and the metadata required for restore into the S3 oplog store's bucket, the same way it does for snapshot data.

  • The MongoDB Agent tails only majority-committed oplog entries for that backup job, so Ops Manager never backs up an oplog entry that a later rollback could remove.

  • Ops Manager can discover and import these immutable oplogs, together with an imported immutable snapshot, into another Ops Manager instance to support point-in-time restore from the imported backup.

Prerequisites

To use immutable S3 backups, ensure you have the following:

  • Ops Manager 8.0.19 or later for immutable snapshots. Immutable oplogs additionally require version 9.0 or 8.0.28.

  • S3 snapshot store (blockstore) configured in Ops Manager. Immutable snapshots support only S3-based snapshot stores, not MongoDB blockstores or filesystem snapshot stores.

  • Object store that supports Object Lock, such as AWS S3 or compatible appliances, with Object Lock enabled on the bucket you use for the store. Most S3 providers require Object versioning for Object Lock to function, and some providers allow Object Lock only during bucket creation.

  • Standard backup requirements, such as a MongoDB Agent with backup enabled on suitable nodes and an oplog (operations log) store for PITR.

  • An S3 bucket with Object Lock enabled for your snapshot store. The bucket doesn't need to be new, and doesn't need to be dedicated to this store, though a dedicated bucket is recommended. You cannot enable Object Lock on an existing S3 snapshot store's configuration in Ops Manager by changing its settings. You must configure a new S3 snapshot store that points to a bucket with Object Lock enabled.

  • If you use immutable oplogs: an S3 bucket with versioning and Object Lock enabled for your oplog store. The bucket doesn't need to be new, and doesn't need to be dedicated to this store, though a dedicated bucket is recommended. You cannot enable Object Lock on an existing S3 oplog store's configuration in Ops Manager by changing its settings. You must configure a new S3 oplog store that points to a bucket with versioning and Object Lock enabled.

Considerations

When you plan immutable S3 backups, consider the following items:

  • No retroactive immutability. Ops Manager protects only snapshots written to a bucket with Object Lock after you enable immutable backup. Ops Manager does not apply Object Lock to existing snapshot objects.

  • Object Lock configuration. Ops Manager does not provide immutability for S3 buckets that do not support Object Lock. You must configure Object Lock on the bucket separately. Configuring Object Lock settings in Ops Manager or updating bucket settings after creation does not enable Object Lock on the bucket.

  • No automatic migration of existing data. The Migrate Backup Between S3 Stores feature lets you change which S3 snapshot store a backup job uses for future snapshots. It does not copy or move existing snapshot data between buckets.

  • Retention and Object Lock on managed stores. When a snapshot ages out according to the backup job retention policy, Ops Manager stops exposing it and attempts to delete related objects. Ops Manager can delete the objects only after the Object Lock retention period expires.

  • Retention on imported stores. Ops Manager never deletes data from the S3 bucket you imported from. Ops Manager can delete the metadata it imported into its own application database. Retention affects only metadata visibility in Ops Manager.

  • No retroactive oplog immutability. You can enable Object Lock only when you create an S3 oplog store. You cannot enable Object Lock on an existing S3 oplog store by changing its settings; you must create a new store instead.

  • Oplog version-pinning defaults to off. By default, Ops Manager doesn't use the exact S3 object version it recorded when it reads an oplog slice back from an immutable oplog store. The brs.oplogStoreFallBackToLatestVersion application setting defaults to true, which causes Ops Manager to always fetch the latest version of the object instead of the version it recorded. To require Ops Manager to use the exact recorded version, a global administrator must set brs.oplogStoreFallBackToLatestVersion to false.

  • Majority-commit topology requirement for oplog tailing. Ops Manager only tails majority-committed oplog entries for an Object-Lock-enabled oplog store, since Object Lock means Ops Manager can never undo or change data already written to the store. On a PSA topology with the secondary down, or a PAA topology, the oplog tail can never reach majority commit, so tailing stalls until the topology recovers. Ops Manager raises an alert naming the cause and the remedy when this happens.

Warning

Ops Manager does not read your bucket's actual retention mode or period, for either snapshot or oplog stores. If the retention values you set in Ops Manager don't match the retention settings you configured directly on the S3 bucket, your backups may not be protected against deletion or modification, and Ops Manager cleanup jobs can fail if the bucket enforces retention that Ops Manager doesn't know about.

Configure Immutable Snapshot Storage

To configure immutable snapshot storage, complete the following tasks:

  1. Enable immutable backups in Ops Manager.

  2. Prepare an Object-Lock-enabled S3 bucket.

  3. Configure a new S3 snapshot store in Ops Manager.

Enable Immutable Backups

An application setting controls immutable backups. A global administrator must enable this setting before you configure an S3 snapshot store with Object Lock.

1

Navigate to the Ops Manager Config page.

Click Admin, General, Ops Manager Config.

2

Add the immutable backup application setting.

  1. Click the Custom tab.

  2. Click + Add Option.

  3. In the Key field, enter brs.immutableBackupEnabled.

  4. In the Value field, enter true.

  5. Click Save.

This setting enables S3 snapshot immutability for stores backed by Object-Lock-enabled buckets. Ops Manager applies this setting immediately. You do not need to restart Ops Manager.

Note

You can also set brs.immutableBackupEnabled to true in conf-mms.properties instead of using the Admin UI. If you set the setting in both places, Ops Manager uses the conf-mms.properties value.

Prepare an Object-Lock-Enabled S3 Bucket

1

Use an existing bucket, or create a new one.

You can use an existing S3 or S3-compatible bucket. A bucket dedicated to immutable MongoDB backups isn't required, but is recommended.

2

Enable Object Lock.

Enable Object Lock on the bucket. Depending on your provider, you can do this during bucket creation or afterward. Most S3 providers require Object versioning for Object Lock to work, and some providers allow Object Lock only during bucket creation.

3

(Optional) Configure conditional writes on the bucket.

Ops Manager uses your bucket's conditional write support by default to reduce the storage space that immutable snapshot metadata uses. Configure your bucket to support conditional writes.

Important

Conditional write support is recommended, not required. If your bucket does not support conditional writes, Ops Manager still protects your snapshots with Object Lock, but the bucket can grow at an unexpected rate.

4

Configure default retention.

Configure a default retention mode (GOVERNANCE or COMPLIANCE) and period in your object store. Ops Manager does not set Object Lock retention headers on individual objects, so your bucket's default retention setting is what actually protects your data. Without a default retention configured on the bucket, Object Lock does not protect your objects from deletion or modification.

Note

You cannot enable Object Lock for an existing S3 snapshot store's configuration in Ops Manager. If you already use an S3 bucket for backups but need immutable snapshots, enable Object Lock on that bucket if your provider allows it, or point to a different bucket that already has Object Lock enabled, and configure a new S3 snapshot store.

Configure a New S3 Snapshot Store in Ops Manager

1

Create a new S3 snapshot store.

Follow the Add One S3-Compatible Snapshot Store procedure to create a new S3 snapshot store that points to the Object-Lock-enabled bucket. Specify the bucket name, endpoint, region, and credentials as required by your S3 provider.

2

Select Object Lock Enabled.

Select Object Lock Enabled to confirm that the underlying bucket has Object Lock enabled.

3

Set Object Retention Period (Days).

Enter the number of days Ops Manager protects each snapshot's objects with Object Lock. This value must match the retention period you configured directly on the bucket.

4

Set Object Retention Mode.

Select the Object Lock retention mode, GOVERNANCE or COMPLIANCE, that Ops Manager applies to this snapshot store's objects. Ops Manager does not read or validate the retention mode you configure directly on the S3 bucket. You must manually set this field to match the retention mode you configured on the bucket.

5

Save the store.

Ops Manager automatically validates connectivity when you save the store.

Important

You can select Object Lock Enabled only when you create a new S3 snapshot store. You cannot change this setting after you save the store. You can change Object Retention Period (Days) and Object Retention Mode at any time.

This snapshot store serves as the target for immutable snapshots. Ops Manager writes both snapshot blocks and metadata for backups that use this store into the bucket.

Note

If you manage Ops Manager with the MongoDB Enterprise Kubernetes Operator, you must also enable Object Lock on the corresponding s3Stores entry in your MongoDBOpsManager resource. Set the spec.backup.s3Stores[].objectLockEnabled field to true so the Kubernetes Operator reconciles Ops Manager with Object-Lock awareness.

You still need a MongoDB instance to act as a metadata store for Ops Manager operations.

Configure Immutable Oplog Storage

To configure immutable oplog storage, complete the following tasks:

  1. Enable immutable backups in Ops Manager, if you haven't already.

  2. Prepare a versioned, Object-Lock-enabled S3 bucket.

  3. Configure a new S3 oplog store in Ops Manager.

  4. Switch existing backup jobs to the immutable S3 oplog store.

Enable Immutable Backups

This step uses the same Ops Manager application setting as immutable snapshot storage. If you've already completed Enable Immutable Backups while configuring immutable snapshot storage, skip this step.

Prepare a Versioned, Object-Lock-Enabled S3 Bucket

Prepare a bucket for your immutable oplog store.

1

Use an existing bucket, or create a new one.

You can use an existing S3 or S3-compatible bucket. A bucket dedicated to immutable MongoDB backups isn't required, but is recommended.

2

Enable versioning and Object Lock.

Unlike a standard oplog store, an immutable oplog store requires both versioning and Object Lock enabled on the bucket. Depending on your provider, you can enable these during bucket creation or afterward.

3

(Optional) Configure conditional writes on the bucket.

Ops Manager uses your bucket's conditional write support by default to reduce the storage space that immutable backup metadata uses. Configure your bucket to support conditional writes.

Important

Conditional write support is recommended, not required. If your bucket does not support conditional writes, Ops Manager still protects your oplogs with Object Lock, but the bucket can grow at an unexpected rate.

4

Configure default retention.

Configure a default retention mode (GOVERNANCE or COMPLIANCE) and period in your object store. Ops Manager does not set Object Lock retention headers on individual objects, so your bucket's default retention setting is what actually protects your data. Without a default retention configured on the bucket, Object Lock does not protect your objects from deletion or modification.

Note

You cannot enable Object Lock for an existing S3 oplog store's configuration in Ops Manager. If you already use an S3 bucket for oplog storage but need immutable oplogs, enable versioning and Object Lock on that bucket if your provider allows it, or point to a different bucket that already has both enabled, and configure a new S3 oplog store.

Configure a New S3 Oplog Store in Ops Manager

Configure the new bucket as an S3 oplog store.

1

Create a new S3 oplog store.

Follow the Add One S3-Compatible Oplog Store procedure to create a new S3 oplog store that points to the versioned, Object-Lock-enabled bucket. Specify the bucket name, endpoint, region, and credentials as required by your S3 provider.

2

Select Object Lock Enabled.

Select Object Lock Enabled to enable immutable oplog backups for this store. You must enable Object Lock on the underlying S3 bucket before you select this field.

3

Set Object Retention Period (Days).

Enter the number of days Ops Manager protects each oplog slice's objects with Object Lock. This value must match the retention period you configured directly on the bucket. This field does not modify the retention settings on the S3 bucket itself, and Ops Manager does not read or validate the bucket's actual retention period.

Important

We recommend setting this field. If you leave it blank, Ops Manager has no record of when your bucket's retention period actually expires. Ops Manager attempts to delete an object as soon as its own grooming logic considers it eligible, and the S3 bucket rejects that delete until its retention period ends. Ops Manager keeps retrying the delete until the bucket allows it.

4

Set Object Retention Mode.

Select the Object Lock retention mode, GOVERNANCE or COMPLIANCE, that Ops Manager applies to this oplog store's objects. We recommend setting this field. Ops Manager does not read or validate the retention mode you configure directly on the S3 bucket. You must manually set this field to match the retention mode you configured on the bucket.

5

Save the store.

Ops Manager automatically validates connectivity when you save the store.

Important

You can select Object Lock Enabled only when you create a new S3 oplog store. You cannot change this setting after you save the store. You can change Object Retention Period (Days) and Object Retention Mode at any time.

This oplog store serves as the target for immutable oplog backups. Ops Manager writes both oplog slices and metadata for backups that use this store into the bucket.

Switch Existing Backup Jobs to the Immutable S3 Oplog Store

To reassign an existing backup job to the immutable S3 oplog store, use assignment labels:

1

Add a label to the immutable S3 oplog store.

Follow the Edit One Existing S3-Compatible Oplog Store procedure to add a label to the immutable S3 oplog store.

2

Apply the same label to the project's assignment labels.

  1. On the Jobs page, click the project name to open the project's assignment page.

  2. In the Assignment Labels list box, click Select Labels.

  3. Select the label.

  4. Click Save Changes.

3

Stop and restart backups for the deployment.

Ops Manager reassigns the backup job's oplog store to match the labels only after you restart backups.

Important

PIT restores are unavailable until Ops Manager takes the next snapshot after the reassignment.

Verify Immutability

Ops Manager automatically writes each snapshot's data and the Object Lock metadata that protects it to the S3 bucket. You do not need to manually export the data. Use the following procedure to confirm that a specific snapshot is protected by Object Lock.

1

Go to the View All Snapshots page.

Go to the View All Snapshots page for the backup you want to check, then find the snapshot you want to confirm in the list.

2

Check the Object Lock column.

Examine the Object Lock column for that snapshot. If the column displays Yes, Ops Manager manages the snapshot as immutable.

To confirm that an S3 oplog store has Object Lock enabled, go to the Oplog Storage page and check that store's settings.

Import Snapshots for Disaster Recovery

If you need to restore data from a pre-existing S3 bucket that contains immutable snapshots and backup metadata, you can import those snapshots into an Ops Manager deployment. Use this workflow for disaster recovery scenarios, such as restoring backups after rebuilding Ops Manager.

Important

Imported snapshots are for one-time restore operations only. Ops Manager does not manage the lifecycle of imported snapshots or include them in active backup schedules.

1

Go to the Imported Snapshots tab.

Click Admin, Backup, Imported Snapshots.

2

Click Import Snapshot.

Click Import Snapshot in the upper right corner of the page to open the import wizard.

3

Select or add the external S3 bucket.

Select an existing bucket, or select Add S3 bucket to define a new one. The bucket name and S3 endpoint must match the values configured on the snapshot's S3 store.

Important

The Add S3 bucket form asks for the same fields as the Add One S3-Compatible Snapshot Store procedure, including a datastore type and MongoDB host list or URI. These fields must point to the dedicated metadata store for this bucket, not to the MongoDB deployment that you are restoring.

4

Select the snapshots to import.

Select the snapshots or clustershots that you want to import from the bucket.

Important

For a clustershot with shards stored in different buckets, import each shard's bucket separately. Add each additional bucket and select that bucket's shards, one bucket at a time, until you import all of the clustershot's shards.

Ops Manager does not make the clustershot restorable, and does not display it on the Continuous Backup page, until you import all of its shards.

5

Assign the organization and project.

Select the organization and project to import the snapshots into. This selection determines which project can restore from the imported snapshots.

Once the import completes, the imported snapshots appear on the Continuous Backup page under the project you assigned them to. Ops Manager displays only clustershots that are fully imported.

Ops Manager never deletes or grooms data from the S3 bucket you imported from. You control the lifecycle of imported snapshot objects at the object storage layer. Ops Manager can delete the metadata it imported into its own application database.

Import Oplogs for Disaster Recovery

If you need point-in-time restore data from a pre-existing S3 bucket that contains immutable oplogs, you can import those oplogs into an Ops Manager deployment. You must import the corresponding snapshot first. Ops Manager can only discover oplogs for a cluster that already has an imported snapshot.

Important

If a metadata file listed in the bucket is missing when Ops Manager tries to import it, Ops Manager skips that file, logs a warning, and still reports the import job as SUCCEEDED. This can leave a gap in the restorable time range that only surfaces later, as a rejection, when you attempt a point-in-time restore across that gap.

1

Click Import Oplogs on the corresponding row.

  1. Go to the Imported Snapshots page (Admin, Backup, Imported Snapshots).

  2. For the row of the snapshot you already imported, click the ellipsis (Actions) menu.

  3. Click Import Oplogs.

This opens the Import Oplogs dialog on the S3 Buckets tab.

2

Select or add the S3 bucket that contains the oplogs.

Select an existing bucket from the Select an S3 bucket list, then click Next. Or select Add S3 bucket to register a new one, then click Save to register the bucket and continue.

Important

The Add S3 bucket form asks for the same fields as the Add One S3-Compatible Snapshot Store procedure, including a datastore type and MongoDB URI.

You must also select the checkbox that acknowledges MongoDB doesn't support issues caused by your S3-compatible storage solution before Ops Manager saves the bucket.

3

Select the oplogs to import.

On the Import Oplog tab, select the oplogs you want to import. Ops Manager disables any oplog it already imported. Click Finish to start the import.

Once the import completes, Ops Manager displays a Manage Oplogs action on that row, where you can view or delete the imported oplogs.

Interactions with PITR

PITR combines a baseline snapshot with oplog data stored in an oplog store. Immutable snapshots affect only the baseline snapshot component:

  • When you switch to an immutable S3 snapshot store, PITR continues to work from existing snapshots and oplog data. Old snapshots remain in their original store, and the oplog store configuration does not change.

  • After the first full immutable snapshot completes on the new store, PITR can use that snapshot as the baseline and continue tailing oplogs from your configured oplog store.

  • PITR from an imported snapshot is available only if you also import the corresponding immutable oplogs. Otherwise, you can restore an imported snapshot only to the exact point when Ops Manager created the snapshot.

Important

For full immutability protection, use an Object-Lock-enabled oplog store together with an Object-Lock-enabled snapshot store. By default, Ops Manager doesn't enforce this pairing: a backup job can use an immutable snapshot store with a standard oplog store, and PITR still works from that combination. To require the pairing, a global administrator must enable the mms.backup.enforceObjectLockOplogsOnObjectLockSnapshot application setting. Ops Manager disables this setting by default. To create an Object-Lock-enabled oplog store, follow the Add One S3-Compatible Oplog Store procedure.

When you enable Object Lock on an oplog store, the MongoDB Agent tails only majority-committed oplog entries for that backup job. A majority-committed entry cannot be rolled back, so this behavior prevents Ops Manager from backing up an oplog entry that a later rollback could remove.

Failure Scenarios and Recovery

Immutable S3 snapshots do not introduce additional data-loss scenarios when you switch snapshot stores. Each snapshot restores from a single store, so restore logic does not require data from multiple buckets for one snapshot.

Crash Before the First Snapshot on the New Store

  • All existing snapshots remain in the original S3 store and are fully restorable.

  • PITR works from the most recent completed snapshot and oplog data.

Crash During the First Full Snapshot on the New Store

  • Ops Manager marks the in-progress snapshot to the new store as failed or incomplete and does not use it for restores.

  • The last successful snapshot in the original store remains the latest restorable snapshot.

  • After Ops Manager and the cluster recover, Ops Manager schedules a new full snapshot to the immutable store at the next snapshot window.

Because the first snapshot on the new store is always a full snapshot and each snapshot restores from a single store, restore logic does not depend on mixing data from multiple S3 buckets for a single snapshot.

Back
Direct S3 Restore
Next
Direct to S3 Backup
Rate this page

On this page