1 files changed, 85 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 0000000..b6a3b39
--- /dev/null
+++ b/doc/src/sgml/basebackup-to-shell.sgml
@@ -0,0 +1,85 @@
+<!-- doc/src/sgml/basebackup-to-shell.sgml -->
+
+<sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell">
+ <title>basebackup_to_shell &mdash; example "shell" pg_basebackup module</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
+  <command>pg_basebackup --target=shell</command> or, depending on how this
+  module is configured,
+  <command>pg_basebackup --target=shell:<replaceable>DETAIL_STRING</replaceable></command>,
+  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 id="basebackup-to-shell-configuration-parameters">
+  <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>
+
+   <varlistentry>
+    <term>
+     <varname>basebackup_to_shell.required_role</varname> (<type>string</type>)
+     <indexterm>
+      <primary><varname>basebackup_to_shell.required_role</varname> configuration parameter</primary>
+     </indexterm>
+    </term>
+    <listitem>
+     <para>
+      The role required in order to make use of the <literal>shell</literal>
+      backup target. If this is not set, any replication user may make use of
+      the <literal>shell</literal> backup target.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2 id="basebackup-to-shell-author">
+  <title>Author</title>
+
+  <para>
+   Robert Haas <email>rhaas@postgresql.org</email>
+  </para>
+ </sect2>
+
+</sect1>