3 files changed, 71 insertions, 0 deletions
diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml
new file mode 100644
index 00000000000..f36f37e5104
--- /dev/null
+++ b/doc/src/sgml/basebackup-to-shell.sgml
@@ -0,0 +1,69 @@
+<!-- doc/src/sgml/basebackup-to-shell.sgml -->
+
+<sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell">
+ <title>basebackup_to_shell</title>
+
+ <indexterm zone="basebackup-to-shell">
+  <primary>basebackup_to_shell</primary>
+ </indexterm>
+
+ <para>
+  <filename>basebackup_to_shell</filename> adds a custom basebackup target
+  called <literal>shell</literal>. This makes it possible to run
+  <literal>pg_basebackup --target=shell</literal> or, depending on how this
+  module is configured,
+  <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause
+  a server command chosen by the server administrator to be executed for
+  each tar archive generated by the backup process. The command will receive
+  the contents of the archive via standard input.
+ </para>
+
+ <para>
+  This module is primarily intended as an example of how to create a new
+  backup targets via an extension module, but in some scenarios it may be
+  useful for its own sake.
+  In order to function, this module must be loaded via
+  <xref linkend="guc-shared-preload-libraries"/> or
+  <xref linkend="guc-local-preload-libraries"/>.
+ </para>
+
+ <sect2>
+  <title>Configuration Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <varname>basebackup_to_shell.command</varname> (<type>string</type>)
+     <indexterm>
+      <primary><varname>basebackup_to_shell.command</varname> configuration parameter</primary>
+     </indexterm>
+    </term>
+    <listitem>
+     <para>
+      The command which the server should execute for each archive generated
+      by the backup process. If <literal>%f</literal> occurs in the command
+      string, it will be replaced by the name of the archive (e.g.
+      <literal>base.tar</literal>). If <literal>%d</literal> occurs in the
+      command string, it will be replaced by the target detail provided by
+      the user. A target detail is required if <literal>%d</literal> is
+      used in the command string, and prohibited otherwise. For security
+      reasons, it may contain only alphanumeric characters. If
+      <literal>%%</literal> occurs in the command string, it will be replaced
+      by a single <literal>%</literal>. If <literal>%</literal> occurs in
+      the command string followed by any other character or at the end of the
+      string, an error occurs.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2>
+  <title>Author</title>
+
+  <para>
+   Robert Haas <email>rhaas@postgresql.org</email>
+  </para>
+ </sect2>
+
+</sect1>
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index be9711c6f2c..1e42ce1a7f7 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -99,6 +99,7 @@ CREATE EXTENSION <replaceable>module_name</replaceable>;
  &amcheck;
  &auth-delay;
  &auto-explain;
+ &basebackup-to-shell;
  &basic-archive;
  &bloom;
  &btree-gin;
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 328cd1f378c..fd853af01fa 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -114,6 +114,7 @@
 <!ENTITY auth-delay      SYSTEM "auth-delay.sgml">
 <!ENTITY auto-explain    SYSTEM "auto-explain.sgml">
 <!ENTITY basic-archive   SYSTEM "basic-archive.sgml">
+<!ENTITY basebackup-to-shell SYSTEM "basebackup-to-shell.sgml">
 <!ENTITY bloom           SYSTEM "bloom.sgml">
 <!ENTITY btree-gin       SYSTEM "btree-gin.sgml">
 <!ENTITY btree-gist      SYSTEM "btree-gist.sgml">