Document changes in barman recover with incremental backups

This commit is adding an explanation on how the recover
from an incremental backup works using pg_combinebackup
and a later copy/move dependending on the final destination
(remote or local). Also explains about the use of the
local_staging_path for this operation.

A detailed NOTE was added to the manual where there is a
documentation about Backup commands and recover.

Also, the new field called local_staging_path was added to the
barman.1.d recover command documentation and a GUC file
for the field was added.

References: BAR-252

Signed-off-by: Andre <[email protected]>

doc/barman.1.d/50-recover.md

@@ -106,6 +106,14 @@ recover *\[OPTIONS\]* *SERVER_NAME* *BACKUP_ID* *DESTINATION_DIRECTORY*
         This option is *required* when recovering from compressed backups and
         has no effect otherwise.
 
+    --local-staging-path *STAGING_PATH*
+    :   A path to a location on the barman host where the chain of backups will
+        be combined before being copied to the destination directory. Contents
+        created inside the staging path are removed at the
+        end of the recovery process. This option is *required* when recovering
+        from incremental backups (backup_method=postgres) and has no effect 
+        otherwise.
+
     --recovery-conf-filename *RECOVERY_CONF_FILENAME*
     :   The name of the file where Barman should write the PostgreSQL recovery
         options when recovering backups for PostgreSQL versions 12 and later.

doc/barman.5.d/50-local_staging_path.md

@@ -0,0 +1,8 @@
+local_staging_path
+:   A path to a location on the local host where incremental backups will
+    be combined during the recovery. This location must have enough
+    available space to temporarily hold the new synthetic backup. This 
+    option is *required* when recovering from an incremental backup and
+    has no effect otherwise.
+
+    Scope: Global/Server/Model.

doc/manual/43-backup-commands.en.md

@@ -354,6 +354,37 @@ the `--recovery-staging-path` option with the `barman recover` command. If
 you do neither of these things and attempt to recover a compressed backup
 then Barman will fail rather than try to guess a suitable location.
 
+### Recovering incremental backups
+
+If a backup is incremental, `barman recover` is able to combine the chain
+of backups on recovery through `pg_combinebackup`.
+A chain of backups is the tree branch that goes from the full backup
+to the one requested for the recovery. This is a multi-step process:
+
+1. The chain of backups is combined into a new synthetic backup. A
+   folder named with the ID of the incremental backup being recovered is
+   created inside a given staging directory on the local server using
+   `pg_combinebackup`. For any type of recover (local or remote), the
+   synthetic backup is created locally in the barman server.
+2. If it's a remote recover, the content is copied to the final destination
+   using Rsync. Otherwise, when it's a local recover, the content is just
+   moved to the final destination.
+3. The folder named with the ID of the incremental backup being recovered, which
+    was created inside the provided staging directory, is removed at the end of the
+    recovery process.
+
+When recovering from an incremental backup, you *must* therefore
+either set `local_staging_path` in the global/server config *or* use
+the `--local-staging-path` option with the `barman recover` command. If
+you do neither of these things and attempt to recover an incremental backup
+then Barman fails rather than trying to guess a suitable location.
+
+> **IMPORTANT:**
+> If any of the backups in the chain were taken with checksums
+> disabled, but the final backup was taken with checksums enabled, the
+> resulting directory may contain pages with invalid checksums.
+> [Follow up the `limitations` section in pg_basebackup documentation](https://www.postgresql.org/docs/17/app-pgcombinebackup.html).
+
 ## `show-backup`
 
 You can retrieve all the available information for a particular backup of