percona · nastena1606 · Jul 13, 2023 · Jun 1, 2023 · Jun 1, 2023 · Jun 1, 2023
diff --git a/docs/_images/backups-infographic.png b/docs/_images/backups-infographic.png
diff --git a/docs/features/backup-types.md b/docs/features/backup-types.md
@@ -9,5 +9,6 @@
 | [Selective](selective-backup.md) | [Tech preview](../reference/glossary.md#technical-preview-feature)| 2.0.0         | Sharded clusters (starting with version 2.0.3) and non-sharded replica sets. Sharded collections are not yet supported. | Yes | Yes | 
 | [Incremental](incremental-backup.md) | GA | 2.1.0 (Supported for PSMDB versions 4.2.24-24, 4.4.18-18, 5.0.2-1, 6.0.2-1 and higher) | Sharded clusters and non-sharded replica sets | Yes  | No |  
 | [Point-in-time recovery](point-in-time-recovery.md) | GA (automatic for logical backups, manual for physical backups) | 1.3.0   | Sharded clusters and non-sharded replica sets | Yes | Yes | 
+| [Snapshot-based](snapshots.md) | Tech preview](../reference/glossary.md#technical-preview-feature) | 2.2.0 | Sharded clusters and non-sharded replica sets | Yes | No | 
 
 
diff --git a/docs/features/snapshots.md b/docs/features/snapshots.md
@@ -0,0 +1,160 @@
+# Snapshot-based physical backups
+
+!!! admonition "Version added: [2.2.0](../release-notes/2.2.0.md)"
+
+## Considerations 
+
+1. This is a [technical preview feature](../reference/glossary.md#technical-preview-feature).
+2. Supported only for full physical backups
+3. Available only if you run Percona Server for MongoDB in your environment  as PBM uses the [`$backupCursor and $backupCursorExtended aggregation stages`](https://docs.percona.com/percona-server-for-mongodb/6.0/backup-cursor.html). 
+
+While a physical backup is a physical copy of your data directory, a snapshot is a point in time copy of your disk or a volume where the data files are stored. Restoring from snapshots is much faster and allows almost immediate access to data, while the database is unavailable during physical restore. Snapshot-based backups are especially useful for owners of large data sets with terabytes of data. Yet the snapshots don’t guarantee data consistency in sharded clusters.
+
+This is where Percona Backup for MongoDB steps in. It provides the interface to make snapshot-based physical backups and restores and ensures data consistency. As a result, database owners benefit from increased performance and reduced downtime, and are sure that their data remains consistent.
+
+The snapshot-based physical backup / restore flow consists of three distinct stages:
+
+* Preparing the database — done by PBM
+* Copying files — done by the user / client app
+* Completing the backup / restore — done by PBM. 
+
+This is the first stage of the snapshot-based backups where you can make them manually. Automated snapshot-based backups are planned for the future.
+
+## Make a backup
+
+1. Refer to the [Before you start](../usage/start-backup.md#before-you-start) section and make sure that you have made all the preparation steps for the backup. 
+
+2. To make a snapshot-based backup, run the [`pbm backup`](../reference/pbm-commands.md#pbm-backup) command with the type `external`:
+
+    ```{.bash data-prompt="$"}
+    $ pbm backup -t external 
+    ```    
+
+    When executing the command, PBM does the following:    
+
+    * opens the `$backupCursor`
+    * prepares the database for file copy
+    * stores the backup metadata on the storage and adds it to the files to copy
+    * prints the prompt similar to the following:    
+
+       ```{.text .no-copy}
+       Ready to copy data from:
+       <node-list>
+       ```    
+
+    You also see the backup name. 
+
+3. (Optional) You can check the backup progress with the [`pbm describe-backup`](../reference/pbm-commands.md#pbm-describe-backup). The command output provides the backup state and what nodes are running backup.
+
+4. At this stage, you can copy the `dataDir` contents to the storage / make a snapshot using the technology of your choice. 
+
+5. After the file copy, run the following command to close the `$backupCursor` and complete the backup: 
+
+    ```{.bash data-prompt="$"}
+    $ pbm backup-finish <backup_name>
+    ```
+
+## Restore a backup 
+
+### Before you start:
+
+1. Shut down all `mongos` nodes. If you have set up the automatic restart of the database, disable it.
+2. Stop the arbiter nodes manually since there’s no `pbm-agent` on these nodes to do that automatically.
+
+### Restore from a backup made through PBM
+
+The following procedure describes the restore from backups [made through PBM](#make-a-backup). See [Restore from a backup made outside PBM](#restore-from-a-backup-made-outside-pbm) for how to restore from a backup made outside of PBM.
+
+1. To make a restore, run the following command:
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore --external 
+    ```    
+
+    Percona Backup for MongoDB stops the database, cleans up data directories on all nodes, provides the restore name and prompts you to copy the data:    
+
+    ```{.text .no-copy}
+    Starting restore <restore_name> from '[external]'.................................................................................................................................Ready to copy data to the nodes data directory.
+        After the copy is done, run: pbm restore-finish <restore_name> -c </path/to/pbm.conf.yaml>
+        Check restore status with: pbm describe-restore <restore_name> -c </path/to/pbm.conf.yaml>
+        No other pbm command is available while the restore is running!
+    ``` 
+
+2. Copy the data. While a backup is made from a single node of a replica set, for the restore you must **copy the data on every node of a corresponding replica set in a cluster**. For example, copy files from a backup for a replica set `rs1` to all nodes in `rs1` in the target cluster and so on.
+
+3. After you copied the files to the nodes, complete the restore with the following command:    
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore-finish <restore_name> -c </path/to/pbm-conf.yaml>
+    ```    
+
+    At this stage, Percona Backup for MongoDB reads the metadata from the backup, prepares the data for the cluster / replica set start and ensures its consistency. The database is restored to the timestamp specified in the `restore_to_time` of the metadata.
+
+4. Optional. You can track the restore progress by running the [`pbm describe-restore`](../reference/pbm-commands.md#pbm-descrbe-restore) command.
+
+#### Post-restore steps 
+
+After the restore is complete, do the following:
+
+1. Start all `mongod` nodes
+
+2. Start all `pbm-agents`
+
+3. Run the following command to resync the backup list with the storage:
+
+    ```{.bash data-prompt="$"}
+    $ pbm config --force-resync
+    ``` 
+
+4. Start the balancer and start `mongos` nodes.
+
+5. Make a fresh backup to serve as the new base for future restores. 
+
+### Restore form a backup made outside PBM
+
+!!! important
+
+    For external backups made through PBM, PBM performs compatibility checks for the backup and the target cluster. If you restore the backup made outside PBM, it cannot ensure that the backup was made properly and in a consistent manner. Therefore, the backup compatibility is your responsibility.
+
+To restore an external backup made outside PBM, you need to specify the following for the `pbm restore` command:
+
+* a path to the configuration file of the `mongod` node on the source cluster from where the backup was made. This is the configuration file that PBM uses during the restore. It should contain the [storage options](https://www.mongodb.com/docs/manual/reference/configuration-options/#storage-options ) per replica set name, for example:
+
+   ```yaml
+   rs1:
+       storage:
+           directoryPerDB: true
+   rs2:
+       storage:
+           directoryPerDB: true
+   ```
+
+   To restore the data encrypted at rest, make sure data-at-rest encryption settings on the source and target clusters are the same. 
+
+* a timestamp to restore to
+
+To restore from a backup, do the following:
+
+1. Start a restore
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore --external -c </path/to/mongod.conf> --ts 
+    ```
+
+    If the path to the source cluster `mongod.conf` is undefined, PBM tries to retrieve the required configuration options from the `mongod.conf` of the target cluster.    
+
+    If the timestamp to restore to is undefined, PBM looks into the actual data during the restore and defines the most recent common cluster time across all shards. PBM restores the database up to this time.
+
+2. Next, copy the data files. Note that you must copy the data **on every data-bearing node of your cluster / replica set**.
+
+3. Complete the restore by running:
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore-finish <restore_name> -c </path/to/pbm.conf.yaml>
+    ```    
+
+    At this stage, Percona Backup for MongoDB prepares the data for the cluster / replica set start and ensures its consistency. 
+
+4. Don't forget to complete the [post-restore steps](#post-restore-steps)
+
+
diff --git a/docs/index.md b/docs/index.md
@@ -12,17 +12,19 @@ With Percona Backup for MongoDB, you can make backups on a running server and re
 
 ## What you can do
 
-![image](_images/backups-infographic.png#only-light)
-![image](_images/backups-infographic-dark.png#only-dark)
+![image](_images/backups-infographic.png)
+
 
 * [Logical backups](features/logical.md) to back up and / or migrate data to different platforms and database versions
 * [Physical backups](features/physical.md) to speed up performance for large (multi-terabyte) data sets
 * [Selective backups](features/selective-backup.md) to work with the desired data set
 * [Incremental physical backups](features/incremental-backup.md) to ensure that critical data is regularly backed up and to save on costs for storage and transfer
+* [Snapshot-based physical backups](features/snapshots.md) using the technology of your choice.
 * [Restore the full database or specific data set](usage/restore.md) from a backup
 * [Restore the database to a specific point in time](features/point-in-time-recovery.md)
 * [Replay oplog](usage/oplog-replay.md) on top of [EBS-snapshots](reference/glossary.md#ebs-snapshot)
 
+
 [Explore features](features/backup-types.md){ .md-button .md-button }
 
 ## What's in it for you?

diff --git a/docs/reference/pbm-commands.md b/docs/reference/pbm-commands.md
@@ -20,12 +20,13 @@
 
 | Flag           | Description                                           |
 | -------------- | ----------------------------------------------------- |
-| `-t`, `--type` | The type of backup. Supported values: physical, logical (default), incremental. When not specified, Percona Backup for MongoDB makes a logical backup. <br> **NOTE**: Incremental physical backups is the [technical preview feature](glossary.md#technical-preview-feature).|
+| `-t`, `--type` | The type of backup. Supported values: physical, logical (default), incremental, [external](../features/snapshots.md). When not specified, Percona Backup for MongoDB makes a logical backup. |
 | `--base`       | For incremental backups only. Set the backup as the base and start tracking the incremental backup history to calculate and save the difference in data blocks for subsequent incremental backups. |  
 | `--compression`| Create a backup with compression. <br> Supported compression methods: `gzip`, `snappy`, `lz4`, `s2`, `pgzip`, `zstd`. Default: `s2` <br> The `none` value means no compression is done during backup. |
 | `--compression-level` | Configure the compression level from 0 to 10. The default value depends on the compression method used.  |
 | `-o`, `--out=text`    | Shows the output format as either plain text or a JSON object. Supported values: `text`, `json` |
 | `--wait`       | Wait for the backup to finish. The flag blocks the shell session.|
+| `-l`, `--list-files` | For external backups only. Shows the list of fines per node to copy.|
 | `--ns="database.collection"`| Makes a logical backup of the specified namespace - the database and collection(s). To back up all collections in the database, specify the value in the `--ns="database.*"` format. In version 2.0.0, only a single namespace is supported for the backup.|
 
 ??? "JSON output"
@@ -37,6 +38,16 @@
     }
     ```
 
+## pbm backup-finish
+
+Closes the `backupCursor` and finishes the external backup. Must be run after running `pbm backup -t external`. To learn more, refer to [API for snapshot-based physical backups](../features/snapshots.md).
+
+The command has the following syntax:
+
+```{.bash data-prompt="$"}
+$ pbm backup-finish [backup-name] 
+```
+
 ## pbm cancel-backup
 
 Cancels a running backup. The backup is marked as canceled in the backup list.
@@ -187,6 +198,7 @@
 - last transition time - the timestamp when a backup changed its status
 - cluster information: the replica set name, the backup status on this replica set, whether it is used as a config server replica set, last write timestamp
 - replica set info: name, backup status, last write timestamp and last transition time, `mongod` security options, if encryption is configured.
+- for snapshot-based backups, provides the list of files being copied
 
 The command has the following syntax:
 
@@ -197,6 +209,7 @@
 | Flag                  | Description                           |
 | --------------------- | ------------------------------------- |
 | `-o`, `--out=text`    | Shows the status as either plain text or a JSON object. Supported values: `text`, `json`|
+| `-l`, `--list-files`  | Shows the list of files being copied for snapshot-based backups |
 
 ??? admonition "JSON output"
 
@@ -512,7 +525,7 @@
 
 ## pbm restore
 
-Restores database from a specified backup / to a specified point in time. Depending on the backup type, makes either logical or physical restore.
+Restores database from a specified backup / to a specified point in time. Depending on the backup type, makes either logical, physical, or a snapshot-based restore.
 
 The command has the following syntax:
 
@@ -526,12 +539,14 @@
 
 | Flag                | Description                           |
 | ------------------- | ------------------------------------- |
+| `--external`        | Indicates the backup as the one made outside PBM (for example, snapshot-based)       |
 | `--time=TIME`       | Restores the database to the specified point in time. Available for logical restores and if [Point-in-time recovery](../features/point-in-time-recovery.md) is enabled. |
 | `-w`                | Wait for the restore to finish. The flag blocks the shell session. |
 | `-o`, `--out=text`  | Shows the output format as either plain text or a JSON object. Supported values: `text`, `json` |
 | `--base-snapshot`   | Restores the database from a specified backup to the specified point in time. Without this flag, the most recent backup preceding the timestamp is used for point in recovery. Available in Percona Backup for MongoDB starting from version 1.6.0.|
 | `--replset-remapping`| Maps the replica set names for the data restore / oplog replay. The value format is `to_name_1=from_name_1,to_name_2=from_name_2`|
 | `--ns="database.collection"`| Restores the specified namespace(s) - databases and collections. To restore all collections in the database, specify the values as `--ns="database.*"`. The `--ns` flag accepts several namespaces as the comma-separated list. For example, ns="db1.*,db2.coll2,db3.coll1,db3.collX"|
+| `-c`, `--config`     | The path to the `mongod.conf` file 
 
 ??? "Restore output"
 
@@ -550,6 +565,22 @@
       "point-in-time":"<backup_name>"
     }
     ```
+## pbm restore-finish
+
+Instructs PBM to complete the snapshot-based physical restore. Must be run after running `pbm restore --external`. To learn more, refer to [API for snapshot-based physical backups](../features/snapshots.md).
+
+The command has the following syntax:
+
+```{.bash data-prompt="$"}
+$ pbm restore-finish <restore_name> [flags]
+```
+
+The command accepts the following flags:
+
+| Flag                | Description                           |
+| ------------------- | ------------------------------------- |
+| `-c`                | The path to the PBM configuration file. Required to complete the restore.|
+
 
 ## pbm status
 
@@ -659,5 +690,3 @@
     }
     ```
 
-
-[^1]: Tech Preview Features are not yet ready for enterprise use and are not included in support via SLA. They are included in this release so that users can provide feedback prior to the full release of the feature in a future GA release (or removal of the feature if it is deemed not useful). This functionality can change (APIs, CLIs, etc.) from tech preview to GA.
diff --git a/docs/usage/restore.md b/docs/usage/restore.md
@@ -52,6 +52,7 @@ To restore a backup, use the [`pbm restore`](../reference/pbm-commands.md#pbm-re
 
     Before you start, shut down all `mongos` nodes as the database won’t be available while the restore is in progress.
 
+
 ## Restore a database
 
 === "Logical"
@@ -270,6 +271,11 @@ To restore a backup, use the [`pbm restore`](../reference/pbm-commands.md#pbm-re
     3. Start the balancer and the `mongos` node.
     4. As the general recommendation, make a new base backup to renew the starting point for subsequent incremental backups.
 
+=== "Snapshot-based"
+
+     See [snapshot-based backups](../features/snapshots.md#restore-a-backup).
+
+
 ## Restoring a backup into a new environment
 
 To restore a backup from one environment to another, ensure the following:

diff --git a/docs/usage/start-backup.md b/docs/usage/start-backup.md
@@ -83,6 +83,12 @@
         2022-11-24T14:45:53Z 220.13GB <incremental, base> [restore_to_time: 2022-11-24T14:45:55Z]
     ```
 
+=== "Snapshot-based"
+
+    See [snapshot-based backups](../features/snapshots.md#make-a-backup).
+
+
+
 ### Compressed backups
 
 By default, Percona Backup for MongoDB uses the `s2` compression method when making a backup.

diff --git a/mkdocs-base.yml b/mkdocs-base.yml
@@ -134,6 +134,7 @@ nav:
           - features/selective-backup.md
           - features/incremental-backup.md
           - features/point-in-time-recovery.md 
+          - features/snapshots.md
       - Comparison with MongoDB: 'features/comparison.md' 
   - Discover PBM:
       - How PBM works: 'intro.md'