Add documentation clarifications regarding standby repositories.

Clarify that placing the repository on a standby is not a robust configuration and recommend against it.

doc/xml/faq.xml

@@ -88,6 +88,14 @@ process-max=1
         <p>If you really need a backup, the solution is to have more standbys or remove <br-option>backup-standby</br-option>. This can be overridden on the command line with <br-option>--no-backup-standby</br-option>, so there is no need to reconfigure for a one-off backup.</p>
     </section>
 
+    <section id="standby-repo">
+        <title>Should I setup my repository on a standby host?</title>
+
+        <p>No. When primary and standby databases are configured, the <backrest/> configuration files should be symmetric in order to seamlessly handle failovers. If they are not, the configurations will need to be changed on failover or further problems may result.</p>
+
+        <p>See the <link url="user-guide.html#repo-host">Dedicated Repository Host</link> section of the <proper>User Guide</proper> for more information.</p>
+    </section>
+
     <!-- <section id="different-server">
         <title>How to restore a backup to a different server (for example, a production backup to a development server)?</title>
 

doc/xml/reference.xml

@@ -740,7 +740,7 @@
             <config-section id="stanza" name="Stanza">
                 <text>A stanza defines the backup configuration for a specific <postgres/> database cluster.  The stanza section must define the database cluster path and host/user if the database cluster is remote.  Also, any global configuration sections can be overridden to define stanza-specific settings.
 
-                <b>Indexing</b>: All <setting>pg-</setting> options are indexed to allow for configuring multiple <postgres/> hosts. For example, a single master is configured with the <setting>pg1-path</setting>, <setting>pg1-host</setting>, etc. options.  If a standby is configured then index the <setting>pg-</setting> options as <setting>pg2-</setting> (e.g. pg2-host, pg2-path, etc).</text>
+                <b>Indexing</b>: All <setting>pg-</setting> options are indexed to allow for configuring multiple <postgres/> hosts. For example, a single primary is configured with the <setting>pg1-path</setting>, <setting>pg1-port</setting>, etc. options.  If a standby is configured then index the <setting>pg-</setting> options on the repository host as <setting>pg2-</setting> (e.g. pg2-host, pg2-path, etc).</text>
 
                 <config-key-list>
                     <!-- CONFIG - STANZA SECTION - PG-HOST-CMD KEY -->

doc/xml/release.xml

@@ -43,6 +43,14 @@
 
                         <p>Document the relationship between <br-option>db-timeout</br-option> and <br-option>protocol-timeout</br-option>.</p>
                     </release-item>
+
+                    <release-item>
+                        <release-item-contributor-list>
+                            <release-item-contributor id="cynthia.shang"/>
+                        </release-item-contributor-list>
+
+                        <p>Add documentation clarifications regarding standby repositories.</p>
+                    </release-item>
                 </release-improvement-list>
             </release-doc-list>
         </release>

doc/xml/user-guide.xml

@@ -2194,6 +2194,8 @@
 
         <p>The configuration described in <link section="/quickstart">Quickstart</link> is suitable for simple installations but for enterprise configurations it is more typical to have a dedicated <host>repository</host> host where the backups and WAL archive files are stored.  This separates the backups and WAL archive from the database server so <host>database</host> host failures have less impact.  It is still a good idea to employ traditional backup software to backup the <host>repository</host> host.</p>
 
+        <p>On <postgres/> hosts, <br-option>pg1-path</br-option> is required to be the path of the local PostgreSQL cluster and no <br-option>pg1-host</br-option> should be configured. When configuring a repository host, the pgbackrest configuration file must have the <br-option>pg-host</br-option> option configured to connect to the primary and standby (if any) hosts. The repository host has the only pgbackrest configuration that should be aware of more than one <postgres/> host. Order does not matter, e.g. pg1-path/pg1-host, pg2-path/pg2-host can be primary or standby.</p>
+
         <section id="install">
             <title>Installation</title>