From 77ee6586cb58bdcf3acf198baf35086fc0c4e62f Mon Sep 17 00:00:00 2001 From: Robert Haas 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. + 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 + + + + + + Specifies the algorithm that should be used to checksum each file + for purposes of the backup manifest. Currently, the available + algorithms are NONE, CRC32C, + SHA224, SHA256, + SHA384, and SHA512. + The default is CRC32C. + + + If NONE 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 SHA256 + checksum of its own contents. The SHA algorithms + are significantly more CPU-intensive than CRC32C, + so selecting one of them may increase the time required to complete + the backup. + + + On the other hand, CRC32C 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 + SHA family of functions is that they output + a much larger number of bits. + + + can be used to check the + integrity of a backup against the backup manifest. + + + 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 @@ + + + + + pg_validatebackup + + + + pg_validatebackup + 1 + Application + + + + pg_validatebackup + verify the integrity of a base backup of a + PostgreSQL cluster + + + + + pg_validatebackup + option + + + + + + Description + + + pg_validatebackup is used to check the integrity + of a database cluster backup. The backup being checked should have been + created by pg_basebackup or some other tool that includes + a backup_manifest 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 PostgreSQL version 13, so older backups + cannot be validated using this tool. + + + + pg_validatebackup 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 + none, 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: + + + + + + backup_manifest is ignored because the backup + manifest is logically not part of the backup and does not include + any entry for itself. + + + + + + pg_wal is ignored because WAL files are sent + separately from the backup, and are therefore not described by the + backup manifest. + + + + + + postgesql.auto.conf, + standby.signal, + and recovery.signal are ignored because they may + sometimes be created or modified by the backup client itself. + (For example, pg_basebackup -R will modify + postgresql.auto.conf and create + standby.signal.) + + + + + + + Options + + + The following command-line options control the behavior. + + + + + + + + Exit as soon as a problem with the backup is detected. If this option + is not specified, pg_basebackup will continue + checking the backup even after a problem has been detected, and will + report all problems detected as errors. + + + + + + + + + + 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. + + + + + + + + + + Use the manifest file at the specified path, rather than one located + in the root of the backup directory. + + + + + + + + + + Don't print anything when a backup is successfully validated. + + + + + + + + + + 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. + + + + + + + + Other options are also available: + + + + + + + + Print the pg_validatebackup version and exit. + + + + + + + + + + Show help about pg_validatebackup command + line arguments, and exit. + + + + + + + + + + + Examples + + + To create a base backup of the server at mydbserver and + validate the integrity of the backup: + +$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data +$ pg_validatebackup /usr/local/pgsql/data + + + + + To create a base backup of the server at mydbserver, move + the manifest somewhere outside the backup directory, and validate the + backup: + +$ pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234 +$ mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest.1234 +$ pg_validatebackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234 + + + + + To validate a backup while ignoring a file that was added manually to the + backup directory, and also skipping checksum verification: + +$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data +$ edit /usr/local/pgsql/data/note.to.self +$ pg_validatebackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data + + + + + + + See Also + + + + + + + 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)