Обсуждение: Streaming Replication docs

One glaring issue with the current documentation layout is that the
documentation for the various options in recovery.conf is split in two
places. The old options, restore_command, recovery_target_* and so forth
are in section "24.3.3.1 Recovery Settings", while the new streaming
replication related options are in "25.3.1 Setup [of streaming
replication]".

It's pretty clear that we should have a single place that documents all
the recovery.conf options. I suggest that we move the "24.3.3.1 RecoverySettings" section after "High Availability,
LoadBalancing, and
 
Replication", and add the new streaming replication related options
there. The previous sections would still briefly describe the most
important settings and give examples, but the new section would be the
authoritative reference page for recovery.conf.

So the new layout would be:

III. Server Administration
   ...   21. Managing Databases   22. Localization   23. Routine Database Maintenance Tasks   24. Backup and Restore
25.High Availability, Load Balancing, and Replication
 
*    26. Recovery Configuration *   27. Monitoring Database Activity   28. Monitoring Disk Usage   29. Reliability and
theWrite-Ahead Log   30. Regression Tests
 

Thoughts, better ideas?


Another change I'd like to make is to document the new built-in way (ie.
standby_mode='on', restore_command='cp ...', primary_conninfo not set)
as the primary way of implementing file-based log shipping. Using
pg_standby or similar scripts that do the waiting would still be
documented, but I'd like to de-emphasize it, moving it into an
"Alternative way to implement File-based log shipping" section. The
description would go along the lines of "An alternative way to implement
File-based log shipping is to leave standby_mode='false', and use a
restore_command that waits until the next WAL file arrives. This offers
more flexibility and control over the process. ..."

The reason for that is that it would make the documentation flow better
with Streaming Replication. In a nutshell, there would be three steps to
set up a full streaming replication system:

1. Set up WAL archiving in master (section "24.3 Continuous Archiving
and Point-In-Time Recovery")
2. Use the WAL archive to implement file-based log shipping (Section
"25.2 File-based Log Shipping")
3. Add streaming replication to the file-based log shipping (Section
25.3 Streaming Replication") setup.

Each section could then simply refer to the previous step: "first set up
... as described in section ...". The new way of setting up file-based
log shipping is a little bit easier than pg_standby to set up anyway
(not that pg_standby is hard either), so it would be good to describe
the simpler method first anyway.

--  Heikki Linnakangas EnterpriseDB   http://www.enterprisedb.com

On Fri, Feb 12, 2010 at 6:14 PM, Heikki Linnakangas
<heikki.linnakangas@enterprisedb.com> wrote:
> So the new layout would be:
>
> III. Server Administration
>
>    ...
>    21. Managing Databases
>    22. Localization
>    23. Routine Database Maintenance Tasks
>    24. Backup and Restore
>    25. High Availability, Load Balancing, and Replication
> *    26. Recovery Configuration *
>    27. Monitoring Database Activity
>    28. Monitoring Disk Usage
>    29. Reliability and the Write-Ahead Log
>    30. Regression Tests
>
> Thoughts, better ideas?

+1

> Another change I'd like to make is to document the new built-in way (ie.
> standby_mode='on', restore_command='cp ...', primary_conninfo not set)
> as the primary way of implementing file-based log shipping. Using
> pg_standby or similar scripts that do the waiting would still be
> documented, but I'd like to de-emphasize it, moving it into an
> "Alternative way to implement File-based log shipping" section. The
> description would go along the lines of "An alternative way to implement
> File-based log shipping is to leave standby_mode='false', and use a
> restore_command that waits until the next WAL file arrives. This offers
> more flexibility and control over the process. ..."

+1

We might need to add the following code of pg_standby into the core,
to prefer it for many cases.

> #ifdef WIN32
>
>             /*
>              * Windows 'cp' sets the final file size before the copy is
>              * complete, and not yet ready to be opened by pg_standby. So we
>              * wait for sleeptime secs before attempting to restore. If that
>              * is not enough, we will rely on the retry/holdoff mechanism.
>              * GNUWin32's cp does not have this problem.
>              */
>             pg_usleep(sleeptime * 1000000L);
> #endif

Regards,

--
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center

Fujii Masao wrote:
> We might need to add the following code of pg_standby into the core,
> to prefer it for many cases.
> 
>> #ifdef WIN32
>>
>>             /*
>>              * Windows 'cp' sets the final file size before the copy is
>>              * complete, and not yet ready to be opened by pg_standby. So we
>>              * wait for sleeptime secs before attempting to restore. If that
>>              * is not enough, we will rely on the retry/holdoff mechanism.
>>              * GNUWin32's cp does not have this problem.
>>              */
>>             pg_usleep(sleeptime * 1000000L);
>> #endif

That's actually a bit questionable, always has been even in pg_standby.
It adds a constant 1 s delay to the recovery each WAL file, which
effectively rate-limits the WAL recovery to 16MB per second. I think we
should rather add a warning to the docs, suggesting the copy-then-rename
method on Windows.

--  Heikki Linnakangas EnterpriseDB   http://www.enterprisedb.com

On Fri, Feb 12, 2010 at 7:15 PM, Heikki Linnakangas
<heikki.linnakangas@enterprisedb.com> wrote:
> That's actually a bit questionable, always has been even in pg_standby.
> It adds a constant 1 s delay to the recovery each WAL file, which
> effectively rate-limits the WAL recovery to 16MB per second. I think we
> should rather add a warning to the docs, suggesting the copy-then-rename
> method on Windows.

Right. Adding a warning to the docs looks enough.

Regards,

-- 
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center

On 2/12/10 1:14 AM, Heikki Linnakangas wrote:
> It's pretty clear that we should have a single place that documents all
> the recovery.conf options. I suggest that we move the "24.3.3.1 Recovery
>  Settings" section after "High Availability, Load Balancing, and
> Replication", and add the new streaming replication related options
> there. The previous sections would still briefly describe the most
> important settings and give examples, but the new section would be the
> authoritative reference page for recovery.conf.

I'd also suggest that we should have a cross-reference from Server
Runtime Settings in Administration.

--Josh Berkus

Heikki,

Crossing this thread over to pgsql-docs, where I think it actually belongs.

In addition to the changes you've proposed, one thing our docs could
really use is a single reference page which we could go to for all of
the .conf files.  Right now, you need to rely on postgresql.org doc
search in order to find, for example, pg_hba.conf.

I think it would be good to put into server administration somewhere a
single page called "Configuration Files" which references:
    postgresql.conf
    pg_hba.conf
    recovery.conf
    pg_ident.conf
    ... hmmm, am I missing one?

--Josh Berkus

On Fri, 2010-02-12 at 10:22 -0800, Josh Berkus wrote:
> Heikki,
>
> Crossing this thread over to pgsql-docs, where I think it actually belongs.
>
> In addition to the changes you've proposed, one thing our docs could
> really use is a single reference page which we could go to for all of
> the .conf files.  Right now, you need to rely on postgresql.org doc
> search in order to find, for example, pg_hba.conf.
>
> I think it would be good to put into server administration somewhere a
> single page called "Configuration Files" which references:
>     postgresql.conf
>     pg_hba.conf
>     recovery.conf
>     pg_ident.conf
>     ... hmmm, am I missing one?


Seems that should go... under "Reference"

Joshua D. Drake


>
> --Josh Berkus
>


--
PostgreSQL.org Major Contributor
Command Prompt, Inc: http://www.commandprompt.com/ - 503.667.4564
Consulting, Training, Support, Custom Development, Engineering
Respect is earned, not gained through arbitrary and repetitive use or Mr. or Sir.

On Fri, 2010-02-12 at 10:22 -0800, Josh Berkus wrote:
> Heikki,
> 
> Crossing this thread over to pgsql-docs, where I think it actually belongs.
> 
> In addition to the changes you've proposed, one thing our docs could
> really use is a single reference page which we could go to for all of
> the .conf files.  Right now, you need to rely on postgresql.org doc
> search in order to find, for example, pg_hba.conf.
> 
> I think it would be good to put into server administration somewhere a
> single page called "Configuration Files" which references:
>     postgresql.conf
>     pg_hba.conf
>     recovery.conf
>     pg_ident.conf
>     ... hmmm, am I missing one?


Seems that should go... under "Reference"

Joshua D. Drake


> 
> --Josh Berkus
> 


-- 
PostgreSQL.org Major Contributor
Command Prompt, Inc: http://www.commandprompt.com/ - 503.667.4564
Consulting, Training, Support, Custom Development, Engineering
Respect is earned, not gained through arbitrary and repetitive use or Mr. or Sir.

On Fri, Feb 12, 2010 at 9:14 AM, Heikki Linnakangas
<heikki.linnakangas@enterprisedb.com> wrote:
> One glaring issue with the current documentation layout is that the
> documentation for the various options in recovery.conf is split in two
> places.

I've been trying to explain to someone how to set this all up and they
keep asking me why there's a separate recovery.conf file. I thought it
made sense back when it was to control PITR and was a transient file
which only applied as long as it was recovering but it seems now to
have become part of the normal setup of the server.

It seems like it would be much easier to keep things straight if you
could set up the master and all the slaves identically and they would
know when they had to store or retrieve files from the WAL archive and
when they had to make or listen for streaming connections based on
their master/slave status -- which is the only bit which needs to be
stored outside the configuration so it can be changed dynamically.

The master/slave status would be indicated by a trigger file or some
external master election daemon connecting and issuing a query calling
a magic sql function.

But having the separate recovery.conf seems kind of pointless legacy
structure at this point.
-- 
greg

On 2/13/10 10:17 AM, Greg Stark wrote:
> But having the separate recovery.conf seems kind of pointless legacy
> structure at this point.

Agreed, but I've been trying to minimize my tinkering with HS/SR.
Several things would need to be changed to get rid of Recovery.conf for
HS and PITR.

I expect that we'll get rid of Recovery.conf, and fold it into
PostgreSQL.conf, in 9.1.

--Josh Berkus

On fre, 2010-02-12 at 11:14 +0200, Heikki Linnakangas wrote:
> So the new layout would be:
> 
> III. Server Administration
> 
>     ...
>     21. Managing Databases
>     22. Localization
>     23. Routine Database Maintenance Tasks
>     24. Backup and Restore
>     25. High Availability, Load Balancing, and Replication
> *    26. Recovery Configuration *
>     27. Monitoring Database Activity
>     28. Monitoring Disk Usage
>     29. Reliability and the Write-Ahead Log
>     30. Regression Tests
> 
> Thoughts, better ideas?

Seems like 25 and 26 should be the same chapter.  And chapter 29 should
perhaps come before them (and probably before 24 as well).

Joshua D. Drake wrote:
> On Fri, 2010-02-12 at 10:22 -0800, Josh Berkus wrote:
>> In addition to the changes you've proposed, one thing our docs could
>> really use is a single reference page which we could go to for all of
>> the .conf files.  Right now, you need to rely on postgresql.org doc
>> search in order to find, for example, pg_hba.conf.
>>
>> I think it would be good to put into server administration somewhere a
>> single page called "Configuration Files" which references:
>>     postgresql.conf
>>     pg_hba.conf
>>     recovery.conf
>>     pg_ident.conf
>>     ... hmmm, am I missing one?
>
>
> Seems that should go... under "Reference"

Seems like a good idea.

Unfortunately my SGML-skills are too weak to do that, so here's a patch
to for my original proposal. There's little text changes, mostly just
moves sections around. I'm thinking of committing this now; someone else
will have to do the above reorganization if we want it.

--
  Heikki Linnakangas
  EnterpriseDB   http://www.enterprisedb.com
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 2f28da2..02d3765 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -955,7 +955,7 @@ SELECT pg_stop_backup();
    <listitem>
     <para>
      Create a recovery command file <filename>recovery.conf</> in the cluster
-     data directory (see <xref linkend="recovery-config-settings">). You might
+     data directory (see <xref linkend="recovery-config">). You might
      also want to temporarily modify <filename>pg_hba.conf</> to prevent
      ordinary users from connecting until you are sure the recovery was successful.
     </para>
@@ -1076,162 +1076,6 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
     WAL data need not be scanned again.
    </para>

-
-    <sect3 id="recovery-config-settings" xreflabel="Recovery Settings">
-     <title>Recovery Settings</title>
-
-     <para>
-      These settings can only be made in the <filename>recovery.conf</>
-      file, and apply only for the duration of the recovery.  (A sample file,
-      <filename>share/recovery.conf.sample</>, exists in the installation's
-      <filename>share/</> directory.)  They must be
-      reset for any subsequent recovery you wish to perform. They cannot be
-      changed once recovery has begun.
-      The parameters for streaming replication are described in <xref
-      linkend="replication-config-settings">.
-     </para>
-
-     <variablelist>
-
-     <varlistentry id="restore-command" xreflabel="restore_command">
-      <term><varname>restore_command</varname> (<type>string</type>)</term>
-      <listitem>
-       <para>
-        The shell command to execute to retrieve an archived segment of
-        the WAL file series. This parameter is required for archive recovery,
-        but optional for streaming replication.
-        Any <literal>%f</> in the string is
-        replaced by the name of the file to retrieve from the archive,
-        and any <literal>%p</> is replaced by the copy destination path name
-        on the server.
-        (The path name is relative to the current working directory,
-        i.e., the cluster's data directory.)
-        Any <literal>%r</> is replaced by the name of the file containing the
-        last valid restart point. That is the earliest file that must be kept
-        to allow a restore to be restartable, so this information can be used
-        to truncate the archive to just the minimum required to support
-        restarting from the current restore. <literal>%r</> is typically only
-        used by warm-standby configurations
-        (see <xref linkend="warm-standby">).
-        Write <literal>%%</> to embed an actual <literal>%</> character.
-       </para>
-
-       <para>
-        It is important for the command to return a zero exit status
-        only if it succeeds.  The command <emphasis>will</> be asked for file
-        names that are not present in the archive; it must return nonzero
-        when so asked.  Examples:
-<programlisting>
-restore_command = 'cp /mnt/server/archivedir/%f "%p"'
-restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
-</programlisting>
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="recovery-end-command" xreflabel="recovery_end_command">
-      <term><varname>recovery_end_command</varname> (<type>string</type>)</term>
-      <listitem>
-       <para>
-        This parameter specifies a shell command that will be executed once only
-        at the end of recovery. This parameter is optional. The purpose of the
-        <varname>recovery_end_command</> is to provide a mechanism for cleanup
-        following replication or recovery.
-        Any <literal>%r</> is replaced by the name of the file
-        containing the last valid restart point. That is the earliest file that
-        must be kept to allow a restore to be restartable, so this information
-        can be used to truncate the archive to just the minimum required to
-        support restart from the current restore. <literal>%r</> would
-        typically be used in a warm-standby configuration
-        (see <xref linkend="warm-standby">).
-        Write <literal>%%</> to embed an actual <literal>%</> character
-        in the command.
-       </para>
-       <para>
-        If the command returns a non-zero exit status then a WARNING log
-        message will be written and the database will proceed to start up
-        anyway.  An exception is that if the command was terminated by a
-        signal, the database will not proceed with startup.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
-      <term><varname>recovery_target_time</varname>
-           (<type>timestamp</type>)
-      </term>
-      <listitem>
-       <para>
-        This parameter specifies the time stamp up to which recovery
-        will proceed.
-        At most one of <varname>recovery_target_time</> and
-        <xref linkend="recovery-target-xid"> can be specified.
-        The default is to recover to the end of the WAL log.
-        The precise stopping point is also influenced by
-        <xref linkend="recovery-target-inclusive">.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
-      <term><varname>recovery_target_xid</varname> (<type>string</type>)</term>
-      <listitem>
-       <para>
-        This parameter specifies the transaction ID up to which recovery
-        will proceed. Keep in mind
-        that while transaction IDs are assigned sequentially at transaction
-        start, transactions can complete in a different numeric order.
-        The transactions that will be recovered are those that committed
-        before (and optionally including) the specified one.
-        At most one of <varname>recovery_target_xid</> and
-        <xref linkend="recovery-target-time"> can be specified.
-        The default is to recover to the end of the WAL log.
-        The precise stopping point is also influenced by
-        <xref linkend="recovery-target-inclusive">.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="recovery-target-inclusive"
-                   xreflabel="recovery_target_inclusive">
-      <term><varname>recovery_target_inclusive</varname>
-        (<type>boolean</type>)
-      </term>
-      <listitem>
-       <para>
-        Specifies whether we stop just after the specified recovery target
-        (<literal>true</literal>), or just before the recovery target
-        (<literal>false</literal>).
-        Applies to both <xref linkend="recovery-target-time">
-        and <xref linkend="recovery-target-xid">, whichever one is
-        specified for this recovery.  This indicates whether transactions
-        having exactly the target commit time or ID, respectively, will
-        be included in the recovery.  Default is <literal>true</>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="recovery-target-timeline"
-                   xreflabel="recovery_target_timeline">
-      <term><varname>recovery_target_timeline</varname>
-        (<type>string</type>)
-      </term>
-      <listitem>
-       <para>
-        Specifies recovering into a particular timeline.  The default is
-        to recover along the same timeline that was current when the
-        base backup was taken.  You only need to set this parameter
-        in complex re-recovery situations, where you need to return to
-        a state that itself was reached after a point-in-time recovery.
-        See <xref linkend="backup-timelines"> for discussion.
-       </para>
-      </listitem>
-     </varlistentry>
-
-   </variablelist>
-
-   </sect3>
-
   </sect2>

   <sect2 id="backup-timelines">
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 068e961..142fa06 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -42,6 +42,7 @@
 <!entity manage-ag     SYSTEM "manage-ag.sgml">
 <!entity monitoring    SYSTEM "monitoring.sgml">
 <!entity regress       SYSTEM "regress.sgml">
+<!entity recovery-config SYSTEM "recovery-config.sgml">
 <!entity runtime       SYSTEM "runtime.sgml">
 <!entity config        SYSTEM "config.sgml">
 <!entity user-manag    SYSTEM "user-manag.sgml">
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 9b68793..144180a 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -853,77 +853,15 @@ if (!triggered)
      <listitem>
       <para>
        Create a recovery command file <filename>recovery.conf</> in the data
-       directory on the standby server.
+       directory on the standby server. Set <varname>restore_command</varname>
+       as you would in normal recovery from a continuous archiving backup
+       (see <xref linkend="backup-pitr-recovery">). <literal>pg_standby</> or
+       similar tools that wait for the next WAL file to arrive cannot be used
+       with streaming replication, as the server handles retries and waiting
+       itself. Enable <varname>standby_mode</varname>. Set
+       <varname>primary_conninfo</varname> to point to the primary server.
       </para>

-      <variablelist id="replication-config-settings" xreflabel="Replication Settings">
-       <varlistentry id="standby-mode" xreflabel="standby_mode">
-        <term><varname>standby_mode</varname> (<type>boolean</type>)</term>
-        <listitem>
-         <para>
-          Specifies whether to start the <productname>PostgreSQL</> server as
-          a standby. If this parameter is <literal>on</>, the server will
-          not end recovery when the end of archived WAL is reached, but
-          will keep trying to continue recovery using <varname>restore_command</>
-          and by connecting to the primary server as specified by the
-          <varname>primary_conninfo</> setting.
-         </para>
-        </listitem>
-       </varlistentry>
-       <varlistentry>
-        <term><varname>restore_command</varname> (<type>string</type>)</term>
-        <term><varname>restore_end_command</varname> (<type>string</type>)</term>
-        <listitem>
-         <para>
-          With <varname>standby_mode</> enabled, <varname>restore_command</>
-          (and <varname>restore_end_command</>) should be set to a
-          simple command or script like in PITR. <literal>pg_standby</> or similar tools
-          that wait for the next WAL file to arrive cannot be used with
-          streaming replication, as the server handles retries and waiting
-          itself. Set <varname>restore_command</> as you would if you were
-          recovering using a Continuous archiving backup (see <xref linkend="backup-pitr-recovery">).
-         </para>
-        </listitem>
-       </varlistentry>
-       <varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
-        <term><varname>primary_conninfo</varname> (<type>string</type>)</term>
-        <listitem>
-         <para>
-          Specifies a connection string to be used for the standby server
-          to connect with the primary. This string is in the same format as
-          described in <xref linkend="libpq-connect">. If any option is
-          unspecified in this string, then the corresponding environment
-          variable (see <xref linkend="libpq-envars">) is checked. If the
-          environment variable is not set either, then
-          defaults are used.
-         </para>
-         <para>
-          The built-in replication requires that a host name (or host address)
-          or port number which the primary server listens on be
-          specified in this string. Also ensure that a role with
-          the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the
-          primary is set (see
-          <xref linkend="streaming-replication-authentication">). Note that
-          the password needs to be set if the primary demands password
-          authentication.
-         </para>
-         <para>
-          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
-         </para>
-        </listitem>
-       </varlistentry>
-       <varlistentry id="trigger-file" xreflabel="trigger_file">
-        <term><varname>trigger_file</varname> (<type>string</type>)</term>
-        <listitem>
-         <para>
-          Specifies a trigger file whose presence ends recovery in the
-          standby. If no trigger file is specified, the standby never exits
-          recovery.
-          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
-         </para>
-        </listitem>
-       </varlistentry>
-      </variablelist>
      </listitem>
      <listitem>
       <para>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2d70847..cfc8ecc 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -155,6 +155,7 @@
   &maintenance;
   &backup;
   &high-availability;
+  &recovery-config;
   &monitoring;
   &diskusage;
   &wal;
diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml
new file mode 100644
index 0000000..98617d1
--- /dev/null
+++ b/doc/src/sgml/recovery-config.sgml
@@ -0,0 +1,233 @@
+<!-- $PostgreSQL$ -->
+
+<chapter Id="recovery-config">
+  <title>Recovery Configuration</title>
+
+  <indexterm>
+   <primary>configuration</primary>
+   <secondary>of recovery</secondary>
+   <tertiary>of a standby server</tertiary>
+  </indexterm>
+
+   <para>
+      This chapter describes the settings available in
+      <filename>recovery.conf</> file. They apply only for the duration of
+      the recovery.  (A sample file, <filename>share/recovery.conf.sample</>,
+      exists in the installation's <filename>share/</> directory.)  They must
+      be reset for any subsequent recovery you wish to perform. They cannot
+      be changed once recovery has begun.
+   </para>
+
+  <sect1 id="archive-recovery-settings">
+
+    <title>Archive recovery settings</title>
+     <variablelist>
+
+     <varlistentry id="restore-command" xreflabel="restore_command">
+      <term><varname>restore_command</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        The shell command to execute to retrieve an archived segment of
+        the WAL file series. This parameter is required for archive recovery,
+        but optional for streaming replication.
+        Any <literal>%f</> in the string is
+        replaced by the name of the file to retrieve from the archive,
+        and any <literal>%p</> is replaced by the copy destination path name
+        on the server.
+        (The path name is relative to the current working directory,
+        i.e., the cluster's data directory.)
+        Any <literal>%r</> is replaced by the name of the file containing the
+        last valid restart point. That is the earliest file that must be kept
+        to allow a restore to be restartable, so this information can be used
+        to truncate the archive to just the minimum required to support
+        restarting from the current restore. <literal>%r</> is typically only
+        used by warm-standby configurations
+        (see <xref linkend="warm-standby">).
+        Write <literal>%%</> to embed an actual <literal>%</> character.
+       </para>
+
+       <para>
+        It is important for the command to return a zero exit status
+        only if it succeeds.  The command <emphasis>will</> be asked for file
+        names that are not present in the archive; it must return nonzero
+        when so asked.  Examples:
+<programlisting>
+restore_command = 'cp /mnt/server/archivedir/%f "%p"'
+restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
+</programlisting>
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="recovery-end-command" xreflabel="recovery_end_command">
+      <term><varname>recovery_end_command</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        This parameter specifies a shell command that will be executed once only
+        at the end of recovery. This parameter is optional. The purpose of the
+        <varname>recovery_end_command</> is to provide a mechanism for cleanup
+        following replication or recovery.
+        Any <literal>%r</> is replaced by the name of the file
+        containing the last valid restart point. That is the earliest file that
+        must be kept to allow a restore to be restartable, so this information
+        can be used to truncate the archive to just the minimum required to
+        support restart from the current restore. <literal>%r</> would
+        typically be used in a warm-standby configuration
+        (see <xref linkend="warm-standby">).
+        Write <literal>%%</> to embed an actual <literal>%</> character
+        in the command.
+       </para>
+       <para>
+        If the command returns a non-zero exit status then a WARNING log
+        message will be written and the database will proceed to start up
+        anyway.  An exception is that if the command was terminated by a
+        signal, the database will not proceed with startup.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+
+  </sect1>
+
+  <sect1 id="recovery-target-settings">
+
+    <title>Recovery target settings</title>
+     <variablelist>
+
+     <varlistentry id="recovery-target-time" xreflabel="recovery_target_time">
+      <term><varname>recovery_target_time</varname>
+           (<type>timestamp</type>)
+      </term>
+      <listitem>
+       <para>
+        This parameter specifies the time stamp up to which recovery
+        will proceed.
+        At most one of <varname>recovery_target_time</> and
+        <xref linkend="recovery-target-xid"> can be specified.
+        The default is to recover to the end of the WAL log.
+        The precise stopping point is also influenced by
+        <xref linkend="recovery-target-inclusive">.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="recovery-target-xid" xreflabel="recovery_target_xid">
+      <term><varname>recovery_target_xid</varname> (<type>string</type>)</term>
+      <listitem>
+       <para>
+        This parameter specifies the transaction ID up to which recovery
+        will proceed. Keep in mind
+        that while transaction IDs are assigned sequentially at transaction
+        start, transactions can complete in a different numeric order.
+        The transactions that will be recovered are those that committed
+        before (and optionally including) the specified one.
+        At most one of <varname>recovery_target_xid</> and
+        <xref linkend="recovery-target-time"> can be specified.
+        The default is to recover to the end of the WAL log.
+        The precise stopping point is also influenced by
+        <xref linkend="recovery-target-inclusive">.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="recovery-target-inclusive"
+                   xreflabel="recovery_target_inclusive">
+      <term><varname>recovery_target_inclusive</varname>
+        (<type>boolean</type>)
+      </term>
+      <listitem>
+       <para>
+        Specifies whether we stop just after the specified recovery target
+        (<literal>true</literal>), or just before the recovery target
+        (<literal>false</literal>).
+        Applies to both <xref linkend="recovery-target-time">
+        and <xref linkend="recovery-target-xid">, whichever one is
+        specified for this recovery.  This indicates whether transactions
+        having exactly the target commit time or ID, respectively, will
+        be included in the recovery.  Default is <literal>true</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="recovery-target-timeline"
+                   xreflabel="recovery_target_timeline">
+      <term><varname>recovery_target_timeline</varname>
+        (<type>string</type>)
+      </term>
+      <listitem>
+       <para>
+        Specifies recovering into a particular timeline.  The default is
+        to recover along the same timeline that was current when the
+        base backup was taken.  You only need to set this parameter
+        in complex re-recovery situations, where you need to return to
+        a state that itself was reached after a point-in-time recovery.
+        See <xref linkend="backup-timelines"> for discussion.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     </variablelist>
+   </sect1>
+
+  <sect1 id="standby-settings">
+
+    <title>Standby server settings</title>
+     <variablelist>
+
+       <varlistentry id="standby-mode" xreflabel="standby_mode">
+        <term><varname>standby_mode</varname> (<type>boolean</type>)</term>
+        <listitem>
+         <para>
+          Specifies whether to start the <productname>PostgreSQL</> server as
+          a standby. If this parameter is <literal>on</>, the server will
+          not end recovery when the end of archived WAL is reached, but
+          will keep trying to continue recovery using <varname>restore_command</>
+          and by connecting to the primary server as specified by the
+          <varname>primary_conninfo</> setting.
+         </para>
+        </listitem>
+       </varlistentry>
+       <varlistentry id="primary-conninfo" xreflabel="primary_conninfo">
+        <term><varname>primary_conninfo</varname> (<type>string</type>)</term>
+        <listitem>
+         <para>
+          Specifies a connection string to be used for the standby server
+          to connect with the primary. This string is in the same format as
+          described in <xref linkend="libpq-connect">. If any option is
+          unspecified in this string, then the corresponding environment
+          variable (see <xref linkend="libpq-envars">) is checked. If the
+          environment variable is not set either, then
+          defaults are used.
+         </para>
+         <para>
+          The built-in replication requires that a host name (or host address)
+          or port number which the primary server listens on be
+          specified in this string. Also ensure that a role with
+          the <literal>SUPERUSER</> and <literal>LOGIN</> privileges on the
+          primary is set (see
+          <xref linkend="streaming-replication-authentication">). Note that
+          the password needs to be set if the primary demands password
+          authentication.
+         </para>
+         <para>
+          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
+         </para>
+        </listitem>
+       </varlistentry>
+       <varlistentry id="trigger-file" xreflabel="trigger_file">
+        <term><varname>trigger_file</varname> (<type>string</type>)</term>
+        <listitem>
+         <para>
+          Specifies a trigger file whose presence ends recovery in the
+          standby. If no trigger file is specified, the standby never exits
+          recovery.
+          This setting has no effect if <varname>standby_mode</> is <literal>off</>.
+         </para>
+        </listitem>
+       </varlistentry>
+
+     </variablelist>
+   </sect1>
+
+</chapter>