percona · radoslawszulgo · Apr 28, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -4,7 +4,7 @@
 build
 source/ext/__pycache__
 .vscode/
-
+venv/
 
 # Local Netlify folder
 .netlify

diff --git a/docs/features/known-limitations.md b/docs/features/known-limitations.md
@@ -14,15 +14,18 @@ PBM supports various backup and restore types. Some of them have known limitatio
 5. System collections in ``admin``, ``config``, and ``local`` databases cannot be backed up and restored selectively. You must make a full backup and restore to include them.
 6. Selective point-in-time recovery is not supported for sharded clusters.
 
+## Physical backups and restores
+1. Physical restores are not supported for MongoDB instances running without authentication if the PBM agent connects via a non-localhost interface (such as a container hostname or external IP). Because MongoDB restricts the shutdown command to the localhost interface in non-authenticated environments, PBM will be unable to stop the node to perform the restore. To avoid this limitation, ensure that the PBM_MONGODB_URI uses a localhost connection or enable authentication for your MongoDB deployment.
+
 ## Oplog slicing for point-in-time recovery
 
 Oplog slicing is an integral part of the point-in-time recovery routine that enables you to restore from a backup up to a specific moment. Read more about [point-in-time recovery](point-in-time-recovery.md).
 
-**For MongoDB 8.0 and higher versions**
+**MongoDB 8.0 and higher versions**
 
 If you [unshard a collection :octicons-link-external-16:](https://www.mongodb.com/docs/v8.0/reference/command/unshardCollection/), make a fresh backup and re-enable point-in-time recovery oplog slicing to prevent data inconsistency and restore failure.
 
-**For in MongoDB 5.0 and higher versions**
+**MongoDB 5.0 and higher versions**
 
 If you [reshard :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/sharding-reshard-a-collection/) a collection, make a fresh backup and re-enable point-in-time recovery oplog slicing to prevent data inconsistency and restore failure.
 

diff --git a/docs/features/multi-storage.md b/docs/features/multi-storage.md
@@ -163,9 +163,11 @@ Before you start, make sure that `pbm-agents` have the read permissions to backu
 2. To make a point-in-time restore, you must explicitly pass the backup name for the `pbm restore` command:
 
     ```bash
-    pbm-restore --time=<timestamp> --base-snapshot <backup-name>
+    pbm restore --time=<timestamp> --base-snapshot <backup-name>
     ```
 
+    !!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)"
+        Before a restore operation is executed you have to confirm the action (to bypass it, add the `-y` or `--yes` flag).
 3. After the restore is complete, do the required post-restore steps depending on the restore type.
 4. Make a fresh backup to serve as the new base for future restores. 
 

diff --git a/docs/features/physical.md b/docs/features/physical.md
@@ -30,7 +30,7 @@ During physical backups and restores, ``pbm-agents`` don't export / import data
 
 ## Availability and system requirements
 
-* Percona Server for MongoDB starting from versions 4.2.15-16, 4.4.6-8, 5.0 and higher. 
+* For current Percona Backup for MongoDB versions, physical backups require Percona Server for MongoDB 7.0 or newer. For support on older Percona Server for MongoDB versions, see the compatibility matrix in [Supported versions](../details/versions.md).
 * WiredTiger storage engine, since physical backups heavily rely on the WiredTiger [`$backupCursor` :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/latest/backup-cursor.html) functionality.
 
 !!! warning 
@@ -88,13 +88,8 @@ You can back up and restore data which is encrypted at rest. Thereby you ensure
 
 During a backup, Percona Backup for MongoDB stores the encryption settings in the backup metadata. You can verify them using the [`pbm describe-backup`](../reference/pbm-commands.md#pbm-describe-backup) command. Note that the encryption key is not stored nor shown as part of the backup.
 
-!!! important
-
-    Make sure that you know which master encryption key was used and keep it safe, as this key is required for the restore.
-
-!!! note
-
-    Starting with [Percona Server for MongoDB version 4.4.19-19 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/4.4/release_notes/4.4.19-19.html), [5.0.15-13 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/5.0/release_notes/5.0.15-13.html), [6.0.5-4 :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/6.0/release_notes/6.0.5-4.html) and higher, the master key rotation for data-at-rest encrypted with HashiCorp Vault has been improved to use the same secret key path on every server in your entire deployment. For the restore with earlier versions of Percona Server for MongoDB and PBM 2.0.5 and earlier, see the [Restore for Percona Server for MongoDB **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 using HashiCorpVault](#restore-for-percona-server-for-mongodb-before-4419-19-5015-13-605-4-using-hashicorpvault) section.
+!!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)"
+    For data-at-rest encryption setups that use an external KMS such as HashiCorp Vault or KMIP, the master encryption key identifier is required to restore the data. PBM stores this identifier in the backup metadata. You need Percona Server for MongoDB (PSMDB) 7.0.22-12 and 8.0.12-4 or higher to use this feature. If you're using older versions of PSMDB or PBM, you have to store the identifier externally.
 
 To restore the encrypted data from the backup, configure the same data-at-rest encryption settings on all nodes of your destination cluster or replica set to match the settings of the original cluster where you made the backup.
 
@@ -105,14 +100,6 @@ To learn more about master key rotation, refer to the following documentation:
 * [Master key rotation in HashiCorp Vault server :octicons-link-external-16:](https://docs.percona.com/percona-server-for-mongodb/6.0/vault.html#key-rotation)
 * [KMIP master key rotation :octicons-link-external-16:](https://www.mongodb.com/docs/manual/tutorial/rotate-encryption-key/#kmip-master-key-rotation)
 
-### Restore for Percona Server for MongoDB **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 using HashiCorpVault
-
-In Percona Server for MongoDB version **before** 4.4.19-19, 5.0.15-13, 6.0.5-4 with Vault server used for data-at-rest encryption, the master key rotation with the same key used for 2+ nodes is not supported. If you run these versions of Percona Server for MongoDB and PBM before 2.1.0, consider using the scenario where PBM restores the data on one node of every replica set. The remaining nodes receive the data during the initial sync. 
-
-Configure data-at-rest encryption on one node of every shard in your destination cluster or a replica set.
-
-During the restore, Percona Backup for MongoDB restores the data on the node where the encryption key matches the one with which the backed up data was encrypted. The other nodes are not restored, so the restore has the "partlyDone" status. You can start this node and initiate the replica set. The remaining nodes receive the data as the result of the initial sync from the restored node.  
-
 ## Physical restores with a fallback directory
 
 !!! admonition "Version added: [2.10.0](../release-notes/2.10.0.md)"
@@ -191,7 +178,10 @@ A restore can succeed on most nodes, but it might fail on a few, resulting in a
     ```bash
     pbm restore --time <time> --fallback-enabled=true --allow-partly-done=true
     ```
-
+
+!!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)"
+    Before a restore operation is executed you have to confirm the action (to bypass it, add the `-y` or `--yes` flag).
+
 If you allow partial restores (default value), PBM finalizes the restore. Once the cluster is up and running, the failed node receives the necessary data from other members through an initial sync. 
 
 If you deny partial restores, PBM treats a cluster as unhealthy and falls it back to the original state. In this case you must have the `restore.fallbackEnabled` option set to `true` or run the `pbm restore` command with the `--fallback-enabled` flag. Otherwise, a restore won't start.

diff --git a/docs/features/restore-remapping.md b/docs/features/restore-remapping.md
@@ -38,8 +38,11 @@ Configure the replica set name mapping:
     pbm restore <timestamp> --replset-remapping="rsX=rsA,rsY=rsB"
     ```
 
-    The `--replset-remapping` flag is available for the following commands: `pbm restore`, `pbm list`, `pbm status`, `pbm oplog-replay`. 
+    The `--replset-remapping` flag is available for the following commands: `pbm restore`, `pbm list`, `pbm status`, `pbm oplog-replay`.
 
+    !!! admonition "Version added: [2.14.0](../release-notes/2.14.0.md)"
+        Before a restore operation is executed you have to confirm the action (to bypass it, add the `-y` or `--yes` flag).
+
 !!! note 
 
     Follow the [post-restore steps](../usage/restore.md#post-restore-steps) on the new environment after the restore is complete.

diff --git a/docs/reference/backup-options.md b/docs/reference/backup-options.md
@@ -15,7 +15,7 @@ backup:
   numParallelCollections: <int>
 ```
 
-### priority
+## priority
 
 *Type*: array of strings
 
@@ -27,7 +27,7 @@ If not set, the replica set nodes have the default priority as follows:
 * secondary nodes - 1.0
 * primary node - 0.5
 
-### backup.compression
+## backup.compression
 
 *Type*: string <br>
 *Default*: s2
@@ -39,7 +39,7 @@ When `none` is specified, backups are made without compression.
 Supported values: `gzip`, `snappy`, `lz4`, `s2`, `pgzip`, `zstd`. Default: `s2`.
 
 <!-- backup-compression-level: -->
-### backup.compressionLevel
+## backup.compressionLevel
 
 *Type*: int
 
@@ -56,9 +56,40 @@ The following table shows available compression levels per compression method:
 
 Note that the greater value you specify, the more time and computing resources it will take to compress the data.
 
+
+## Backup timeouts
+
+Timeout options control how long Percona Backup for MongoDB (PBM) waits for specific conditions during backup operations.
+
+### backup.timeouts.balancerStop
+
+*Type*: int <br>
+*Default*: 0 (unlimited)
+
+Defines the maximum time (in seconds) that PBM waits for the balancer to stop before starting a backup. If set to **0**, PBM waits indefinitely for the balancer to stop.
+
+PBM stops the balancer before starting a backup to ensure consistency in sharded clusters. If the balancer does not stop within the specified timeout, the backup operation fails.
+
+??? example "Example"
+
+    ```yaml
+    backup:
+      timeouts:
+        balancerStop: 60
+    ```
+
+    In this example, PBM waits up to 60 seconds for the balancer to stop. If the balancer is still running after this period, the backup fails.
+
+
+This is useful when you want to:
+
+- Avoid indefinite waits during backup operations
+- Enforce stricter operational time limits in automated environments
+- Detect and fail fast if the balancer cannot be stopped
+
 ### backup.timeouts.startingStatus
 
-*Type*: unit32 <br>
+*Type*: uint32 <br>
 *Default*: 33
 
 The wait time (in seconds) for PBM to start backups. This timeout controls how long PBM waits for the backup to transition from initial state to running status.
@@ -76,13 +107,13 @@ The wait time (in seconds) for PBM to start backups. This timeout controls how l
 
   The 0 (zero) value resets the timeout to the default 33 seconds.
 
-### backup.oplogSpanMin
+## backup.oplogSpanMin
 
 *Type*: float64 <br>
 
 The duration (in minutes) of oplog slices saved with the logical backup snapshot. By default, the duration of backup oplog slices equals to the value defined for the [`pitr.oplogSpanMin`](pitr-options.md#pitroplogspanmin) option (default - 10 minutes). You can reduce the duration in heavy-loaded environments. Note that setting the duration to shorter periods may increase the overall backup execution time. 
 
-### backup.numParallelCollections
+## backup.numParallelCollections
 
 *Type*: int <br>
 *Default*: number of CPU cores / 2