v11-0005-Documentation.patch

From 77ee6586cb58bdcf3acf198baf35086fc0c4e62f Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Fri, 13 Mar 2020 11:54:58 -0400
Subject: [PATCH v11 5/5] Documentation.

- Add documentation for pg_validatebackup.
- Adjust documentation for pg_basebackup.

Robert Haas and Mark Dilger
---
 doc/src/sgml/ref/allfiles.sgml          |   1 +
 doc/src/sgml/ref/pg_basebackup.sgml     |  40 ++++
 doc/src/sgml/ref/pg_validatebackup.sgml | 232 ++++++++++++++++++++++++
 doc/src/sgml/reference.sgml             |   1 +
 4 files changed, 274 insertions(+)
 create mode 100644 doc/src/sgml/ref/pg_validatebackup.sgml

diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 8d91f3529e..ab71176cdf 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -211,6 +211,7 @@ Complete list of usable sgml source files in this directory.
 <!ENTITY pgResetwal         SYSTEM "pg_resetwal.sgml">
 <!ENTITY pgRestore          SYSTEM "pg_restore.sgml">
 <!ENTITY pgRewind           SYSTEM "pg_rewind.sgml">
+<!ENTITY pgValidateBackup   SYSTEM "pg_validatebackup.sgml">
 <!ENTITY pgtestfsync        SYSTEM "pgtestfsync.sgml">
 <!ENTITY pgtesttiming       SYSTEM "pgtesttiming.sgml">
 <!ENTITY pgupgrade          SYSTEM "pgupgrade.sgml">
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 29bf2f9b97..f6175dd968 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -552,6 +552,46 @@ PostgreSQL documentation
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><option>--manifest-checksums=<replaceable class="parameter">algorithm</replaceable></option></term>
+      <listitem>
+       <para>
+        Specifies the algorithm that should be used to checksum each file
+        for purposes of the backup manifest. Currently, the available
+        algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>,
+        <literal>SHA224</literal>, <literal>SHA256</literal>,
+        <literal>SHA384</literal>, and <literal>SHA512</literal>.
+        The default is <literal>CRC32C</literal>.
+       </para>
+       <para>
+        If <literal>NONE</literal> is selected, the backup manifest will
+        not contain any checksums. Otherwise, it will contain a checksum
+        of each file in the backup using the specified algorithm. In addition,
+        the manifest itself will always contain a <literal>SHA256</literal>
+        checksum of its own contents. The <literal>SHA</literal> algorithms
+        are significantly more CPU-intensive than <literal>CRC32C</literal>,
+        so selecting one of them may increase the time required to complete
+        the backup.
+       </para>
+       <para>
+        On the other hand, <literal>CRC32C</literal> is not a cryptographic
+        hash function, so it is only suitable for protecting against
+        inadvertent or random modifications to a backup. An adversary
+        who can modify the backup could easily do so in such a way that
+        the CRC does not change, whereas a SHA collision will be hard
+        to manufacture. (However, note that if the attacker also has access
+        to modify the backup manifest itself, no checksum algorithm will
+        provide any protection.) An additional advantage of the
+        <literal>SHA</literal> family of functions is that they output
+        a much larger number of bits.
+       </para>
+       <para>
+        <xref linkend="app-pgvalidatebackup" /> can be used to check the
+        integrity of a backup against the backup manifest.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
 
diff --git a/doc/src/sgml/ref/pg_validatebackup.sgml b/doc/src/sgml/ref/pg_validatebackup.sgml
new file mode 100644
index 0000000000..678a14a2f1
--- /dev/null
+++ b/doc/src/sgml/ref/pg_validatebackup.sgml
@@ -0,0 +1,232 @@
+<!--
+doc/src/sgml/ref/pg_validatebackup.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="app-pgvalidatebackup">
+ <indexterm zone="app-pgvalidatebackup">
+  <primary>pg_validatebackup</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle>pg_validatebackup</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>pg_validatebackup</refname>
+  <refpurpose>verify the integrity of a base backup of a
+  <productname>PostgreSQL</productname> cluster</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_validatebackup</command>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>
+   Description
+  </title>
+  <para>
+   <application>pg_validatebackup</application> is used to check the integrity
+   of a database cluster backup.  The backup being checked should have been
+   created by <command>pg_basebackup</command> or some other tool that includes
+   a <literal>backup_manifest</literal> file with the bacup. The backup
+   must be stored in the "plain" format; a "tar" format backup can be checked
+   after extracting it. Backup manifests are created by the server beginning
+   with <productname>PostgreSQL</productname> version 13, so older backups
+   cannot be validated using this tool.
+  </para>
+
+  <para>
+   <application>pg_validatebackup</application> reads the manifest file of a
+   backup, verifies the manifest against its own internal checksum, and then
+   verifies that the same files are present in the target directory as in the
+   manifest itself. It then verifies that each file has the expected checksum,
+   unless the backup was taken the checksum algorithm set to
+   <literal>none</literal>, in which case checksum verification is not
+   performed. The presence or absence of directories is not checked, except
+   indirectly: if a directory is missing, any files it should have contained
+   will necessarily also be missing. Certain files and directories are
+   excluded from verification:
+  </para>
+
+  <itemizedlist>
+    <listitem>
+      <para>
+        <literal>backup_manifest</literal> is ignored because the backup
+        manifest is logically not part of the backup and does not include
+        any entry for itself.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        <literal>pg_wal</literal> is ignored because WAL files are sent
+        separately from the backup, and are therefore not described by the
+        backup manifest.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        <literal>postgesql.auto.conf</literal>,
+        <literal>standby.signal</literal>,
+        and <literal>recovery.signal</literal> are ignored because they may
+        sometimes be created or modified by the backup client itself.
+        (For example, <literal>pg_basebackup -R</literal> will modify
+        <literal>postgresql.auto.conf</literal> and create
+        <literal>standby.signal</literal>.)
+      </para>
+    </listitem>
+  </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+  <title>Options</title>
+
+   <para>
+    The following command-line options control the behavior.
+
+    <variablelist>
+     <varlistentry>
+      <term><option>-e</option></term>
+      <term><option>--exit-on-error</option></term>
+      <listitem>
+       <para>
+        Exit as soon as a problem with the backup is detected. If this option
+        is not specified, <literal>pg_basebackup</literal> will continue
+        checking the backup even after a problem has been detected, and will
+        report all problems detected as errors.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
+      <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
+      <listitem>
+       <para>
+        Ignore the specified file or directory, which should be expressed
+        as a relative pathname. If the backup contains extra files, is
+        missing files, or has files that have been modified as compared with
+        what is described in the manifest, this option can be used to suppress
+        the errors that would otherwise occur. If a directory is specified,
+        this option affects the entire subtree rooted at that location.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
+      <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
+      <listitem>
+       <para>
+        Use the manifest file at the specified path, rather than one located
+        in the root of the backup directory.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-q</option></term>
+      <term><option>--quiet</option></term>
+      <listitem>
+       <para>
+        Don't print anything when a backup is successfully validated.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s</option></term>
+      <term><option>--skip-checksums</option></term>
+      <listitem>
+       <para>
+        Do not validate checksums. The presence or absence of files and the
+        sizes of those files will still be checked. This is much faster,
+        because the files themselves do not need to read.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+
+   <para>
+    Other options are also available:
+
+    <variablelist>
+     <varlistentry>
+       <term><option>-V</option></term>
+       <term><option>--version</option></term>
+       <listitem>
+       <para>
+       Print the <application>pg_validatebackup</application> version and exit.
+       </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry>
+       <term><option>-?</option></term>
+       <term><option>--help</option></term>
+       <listitem>
+       <para>
+       Show help about <application>pg_validatebackup</application> command
+       line arguments, and exit.
+       </para>
+       </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   To create a base backup of the server at <literal>mydbserver</literal> and
+   validate the integrity of the backup:
+<screen>
+<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
+<prompt>$</prompt> <userinput>pg_validatebackup /usr/local/pgsql/data</userinput>
+</screen>
+  </para>
+
+  <para>
+   To create a base backup of the server at <literal>mydbserver</literal>, move
+   the manifest somewhere outside the backup directory, and validate the
+   backup:
+<screen>
+<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234</userinput>
+<prompt>$</prompt> <userinput>mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234</userinput>
+<prompt>$</prompt> <userinput>pg_validatebackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234</userinput>
+</screen>
+  </para>
+
+  <para>
+   To validate a backup while ignoring a file that was added manually to the
+   backup directory, and also skipping checksum verification:
+<screen>
+<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
+<prompt>$</prompt> <userinput>edit /usr/local/pgsql/data/note.to.self</userinput>
+<prompt>$</prompt> <userinput>pg_validatebackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data</userinput>
+</screen>
+  </para>
+
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-pgbasebackup"/></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index cef09dd38b..d25a77b13c 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -255,6 +255,7 @@
    &pgReceivewal;
    &pgRecvlogical;
    &pgRestore;
+   &pgValidateBackup;
    &psqlRef;
    &reindexdb;
    &vacuumdb;
-- 
2.17.2 (Apple Git-113)