From a9a17f206e7847445ec03e6f87aeb794d8c5fa25 Mon Sep 17 00:00:00 2001
From: Ian Barwick <ian@2ndquadrant.com>
Date: Wed, 15 Nov 2017 20:50:13 +0900
Subject: [PATCH] docs: improve documentation of pg_basebackup_options

---
 doc/appendix-faq.sgml     | 15 ++++++++++++---
 doc/cloning-standbys.sgml | 17 +++++++++++++++--
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/doc/appendix-faq.sgml b/doc/appendix-faq.sgml
index 480c8707..24c50c66 100644
--- a/doc/appendix-faq.sgml
+++ b/doc/appendix-faq.sgml
@@ -142,7 +142,7 @@
    <title>I've provided replication permission for the <literal>repmgr</literal> user in <filename>pg_hba.conf</filename>
      but <command>repmgr</command>/<application>repmgrd</application> complains it can't connect to the server... Why?</title>
    <para>
-    <command>repmgr</command> and<application>repmgrd</application> need to be able to connect to the repmgr database
+    <command>repmgr</command> and <application>repmgrd</application> need to be able to connect to the repmgr database
     with a normal connection to query metadata. The <literal>replication</literal> connection
     permission is for PostgreSQL's streaming replication (and doesn't  necessarily need to be the <literal>repmgr</literal> user).
    </para>
@@ -155,8 +155,17 @@
     Cloning a standby is a one-time action; the role of the server being cloned
     from could change, so fixing it in the configuration file would create
     confusion. If &repmgr; needs to establish a connection to the primary
-    server, it can retrieve this from the <literal>repmgr.nodes</literal> table or if necessary
-    scan the replication cluster until it locates the active primary.
+    server, it can retrieve this from the <literal>repmgr.nodes</literal> table on the local
+    node, and if necessary scan the replication cluster until it locates the active primary.
+   </para>
+  </sect2>
+
+  <sect2 id="faq-repmgr-clone-waldir-xlogdir" xreflabel="Providing a custom WAL directory">
+   <title>When cloning a standby, how do I ensure the WAL files are placed in a custom directory?</title>
+   <para>
+     Provide the option <literal>--waldir</literal>  (<literal>--xlogdir</literal> in PostgreSQL 9.6
+     and earlier) with the absolute path to the WAL directory in <varname>pg_basebackup_options</varname>.
+     For more details see <xref linkend="cloning-advanced-pg-basebackup-options">.
    </para>
   </sect2>
 
diff --git a/doc/cloning-standbys.sgml b/doc/cloning-standbys.sgml
index d3a589b7..68bfcbac 100644
--- a/doc/cloning-standbys.sgml
+++ b/doc/cloning-standbys.sgml
@@ -347,6 +347,11 @@
 
    <sect2 id="cloning-advanced-pg-basebackup-options" xreflabel="pg_basebackup options when cloning a standby">
     <title>pg_basebackup options when cloning a standby</title>
+    <para>
+      As &repmgr; uses <command>pg_basebackup</command> to clone a standby, it's possible to
+      provide additional parameters for <command>pg_basebackup</command> to customise the
+      cloning process.
+    </para>
     <para>
      By default, <command>pg_basebackup</command> performs a checkpoint before beginning the backup
      process. However, a normal checkpoint may take some time to complete;
@@ -362,8 +367,16 @@
       </simpara>
     </tip>
     <para>
-     Further options can be passed to the <command>pg_basebackup</command> utility via
-     the setting <varname>pg_basebackup_options</varname> in <filename>repmgr.conf</filename>.
+      Other options can be passed to <command>pg_basebackup</command> by including them
+      in the <filename>repmgr.conf</filename> setting <varname>pg_basebackup_options</varname>.
+    </para>
+    <para>
+      If using a separate directory to store WAL files, provide the option <literal>--waldir</literal>
+      (<literal>--xlogdir</literal> in PostgreSQL 9.6 and earlier) with the absolute path to the
+      WAL directory. Any WALs generated during the cloning process will be copied here, and
+      a symlink will automatically be created from the main data directory.
+    </para>
+    <para>
      See the <ulink url="https://www.postgresql.org/docs/current/static/app-pgbasebackup.html">PostgreSQL pg_basebackup documentation</ulink>
      for more details of available options.
     </para>