doc/src/sgml/basebackup-to-shell.sgml

   1 <!-- doc/src/sgml/basebackup-to-shell.sgml -->
   2
   3 <sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell">
   4  <title>basebackup_to_shell &mdash; example "shell" pg_basebackup module</title>
   5
   6  <indexterm zone="basebackup-to-shell">
   7   <primary>basebackup_to_shell</primary>
   8  </indexterm>
   9
  10  <para>
  11   <filename>basebackup_to_shell</filename> adds a custom basebackup target
  12   called <literal>shell</literal>. This makes it possible to run
  13   <command>pg_basebackup --target=shell</command> or, depending on how this
  14   module is configured,
  15   <command>pg_basebackup --target=shell:<replaceable>DETAIL_STRING</replaceable></command>,
  16   and cause a server command chosen by the server administrator to be executed
  17   for each tar archive generated by the backup process. The command will receive
  18   the contents of the archive via standard input.
  19  </para>
  20
  21  <para>
  22   This module is primarily intended as an example of how to create a new
  23   backup targets via an extension module, but in some scenarios it may be
  24   useful for its own sake.
  25   In order to function, this module must be loaded via
  26   <xref linkend="guc-shared-preload-libraries"/> or
  27   <xref linkend="guc-local-preload-libraries"/>.
  28  </para>
  29
  30  <sect2 id="basebackup-to-shell-configuration-parameters">
  31   <title>Configuration Parameters</title>
  32
  33   <variablelist>
  34    <varlistentry>
  35     <term>
  36      <varname>basebackup_to_shell.command</varname> (<type>string</type>)
  37      <indexterm>
  38       <primary><varname>basebackup_to_shell.command</varname> configuration parameter</primary>
  39      </indexterm>
  40     </term>
  41     <listitem>
  42      <para>
  43       The command which the server should execute for each archive generated
  44       by the backup process. If <literal>%f</literal> occurs in the command
  45       string, it will be replaced by the name of the archive (e.g.
  46       <literal>base.tar</literal>). If <literal>%d</literal> occurs in the
  47       command string, it will be replaced by the target detail provided by
  48       the user. A target detail is required if <literal>%d</literal> is
  49       used in the command string, and prohibited otherwise. For security
  50       reasons, it may contain only alphanumeric characters. If
  51       <literal>%%</literal> occurs in the command string, it will be replaced
  52       by a single <literal>%</literal>. If <literal>%</literal> occurs in
  53       the command string followed by any other character or at the end of the
  54       string, an error occurs.
  55      </para>
  56     </listitem>
  57    </varlistentry>
  58
  59    <varlistentry>
  60     <term>
  61      <varname>basebackup_to_shell.required_role</varname> (<type>string</type>)
  62      <indexterm>
  63       <primary><varname>basebackup_to_shell.required_role</varname> configuration parameter</primary>
  64      </indexterm>
  65     </term>
  66     <listitem>
  67      <para>
  68       The role required in order to make use of the <literal>shell</literal>
  69       backup target. If this is not set, any replication user may make use of
  70       the <literal>shell</literal> backup target.
  71      </para>
  72     </listitem>
  73    </varlistentry>
  74   </variablelist>
  75  </sect2>
  76
  77  <sect2 id="basebackup-to-shell-author">
  78   <title>Author</title>
  79
  80   <para>
  81    Robert Haas <email>rhaas@postgresql.org</email>
  82   </para>
  83  </sect2>
  84
  85 </sect1>