Add docs for wal_streaming_conninfo and wal_conninfo

barman/cli.py

@@ -609,9 +609,10 @@ def status(args):
             choices=("backup-host", "wal-host"),
             default="backup-host",
             help="""
-                        Possible values are: 'backup-host' (only show replications
-                        running on the backup host) or 'wal-host' (only show replications
-                        running on the wal host). Defaults to %(default)s""",
+                        Possible values are: 'backup-host' (list clients using the
+                        backup conninfo for a server) or `wal-host` (list clients using
+                        the WAL streaming conninfo for a server). Defaults to
+                        %(default)s""",
         ),
     ]
 )

doc/barman.1.d/50-replication-status.md

@@ -13,3 +13,11 @@ replication-status *\[OPTIONS\]* *SERVER_NAME*
          - *wal-streamer*: lists only WAL streaming clients, such as
                           pg_receivewal
          - *all*: any streaming client (default)
+
+    --source *SOURCE_TYPE*
+    :    Possible values for SOURCE_TYPE are:
+
+         - *backup-host*: list clients using the backup conninfo for
+                          a server (default)
+         - *wal-host*: list clients using the WAL streaming conninfo
+                       for a server

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

@@ -0,0 +1,7 @@
+wal_conninfo
+:   A connection string which, if set, will be used by Barman to connect to the
+    Postgres server when checking the status of the replication slot used for
+    receiving WALs. If left unset then Barman will use the connection string
+    defined by `wal_streaming_conninfo`. If `wal_conninfo` is set but
+    `wal_streaming_conninfo` is unset then `wal_conninfo` will be ignored.
+    Server.

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

@@ -0,0 +1,5 @@
+wal_streaming_conninfo
+:   A connection string which, if set, will be used by Barman to connect to
+    the Postgres server when receiving WAL segments via the streaming
+    replication protocol. If left unset then Barman will use the connection
+    string defined by `streaming_conninfo` for receiving WAL segments. Server.

doc/manual/23-wal_streaming.en.md

@@ -104,6 +104,45 @@ create the replication slot by setting:
 create_slot = auto
 ```
 
+### Streaming WALs and backups from different hosts (Barman 3.10.0 and later)
+
+Barman uses the connection info defined in `streaming_conninfo` when creating
+`pg_receivewal` processes to stream WAL segments and uses `conninfo` when
+checking the status of replication slots. Because `conninfo` and
+`streaming_conninfo` are also used when taking backups this default
+configuration forces Barman to stream WALs and take backups from the same host.
+
+If an alternative configuration is required, such as backups being sourced from
+a standby with WALs being streamed from the primary, then this can be achieved
+using the following options:
+
+- `wal_streaming_conninfo`: A connection string which Barman will use instead
+   of `streaming_conninfo` when receiving WAL segments via the streaming
+  replication protocol and when checking the status of the replication slot
+  used for receiving WALs.
+- `wal_conninfo`: A connection string which Barman will use instead of
+  `wal_streaming_conninfo` when checking the status of the replication slot
+  used for receiving WALs.
+
+The following restrictions apply and are enforced by Barman during checks:
+
+- Connections defined by `wal_streaming_conninfo` and `wal_conninfo` must reach
+  a PostgreSQL instance which belongs to the same cluster reached by the
+  `streaming_conninfo` and `conninfo` connections.
+- The `wal_streaming_conninfo` connection string must be able to create
+  streaming replication connections. If `wal_conninfo` is unset it must also
+  have monitoring permissions (either the `pg_monitor` or `superuser` role) so
+  that it can check replication slot status.
+- If `wal_conninfo` is set the it must have monitoring permissions (either the
+  `pg_monitor` or `superuser` role).
+
+> **IMPORTANT:**
+> While it is possible to stream WALs from *any* PostgreSQL instance in a
+> cluster there is a risk that WAL segments can be lost when streaming WALs
+> from a standby, if such a standby is unable to keep up with its own upstream
+> source. For this reason it is *strongly recommended* that WALs are always
+> streamed directly from the primary.
+
 ### Limitations of partial WAL files with recovery
 
 The standard behaviour of `pg_receivewal` is to write transactional