From dbc60c5593f26dc777a3be032bff4fb4eab1ddd1 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Sun, 12 Apr 2020 11:26:05 -0400 Subject: Rename pg_validatebackup to pg_verifybackup. Also, use "verify" rather than "validate" to refer to the process being undertaken here. Per discussion, that is a more appropriate term. Discussion: https://www.postgresql.org/message-id/172c9d9b-1d0a-1b94-1456-376b1e017322@2ndquadrant.com Discussion: http://postgr.es/m/CA+TgmobLgMh6p8FmLbj_rv9Uhd7tPrLnAyLgGd2SoSj=qD-bVg@mail.gmail.com --- doc/src/sgml/ref/allfiles.sgml | 2 +- doc/src/sgml/ref/pg_basebackup.sgml | 4 +- doc/src/sgml/ref/pg_validatebackup.sgml | 291 -------------------------------- doc/src/sgml/ref/pg_verifybackup.sgml | 291 ++++++++++++++++++++++++++++++++ doc/src/sgml/reference.sgml | 2 +- 5 files changed, 295 insertions(+), 295 deletions(-) delete mode 100644 doc/src/sgml/ref/pg_validatebackup.sgml create mode 100644 doc/src/sgml/ref/pg_verifybackup.sgml (limited to 'doc/src') diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index ab71176cdf3..0f0064150c4 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -211,7 +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 d9c981cebb9..01ce44ee220 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -568,7 +568,7 @@ PostgreSQL documentation Disables generation of a backup manifest. If this option is not specified, the server will generate and send a backup manifest - which can be verified using . + which can be verified using . The manifest is a list of every file present in the backup with the exception of any WAL files that may be included. It also stores the size, last modification time, and an optional checksum for each file. @@ -620,7 +620,7 @@ PostgreSQL documentation verified not to have been modified since the backup was taken. - can be used to check the + 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 deleted file mode 100644 index 5c626200f68..00000000000 --- a/doc/src/sgml/ref/pg_validatebackup.sgml +++ /dev/null @@ -1,291 +0,0 @@ - - - - - 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 taken using - pg_basebackup against a - backup_manifest generated by the server at the time - of the backup. The backup must be stored in the "plain" - format; a "tar" format backup can be checked after extracting it. - - - - It is important to note that the validation which is performed by - pg_validatebackup does not and can not include - every check which will be performed by a running server when attempting - to make use of the backup. Even if you use this tool, you should still - perform test restores and verify that the resulting databases work as - expected and that they appear to contain the correct data. However, - pg_validatebackup can detect many problems - that commonly occur due to storage problems or user error. - - - - Backup verification proceeds in four stages. First, - pg_validatebackup reads the - backup_manifest file. If that file - does not exist, cannot be read, is malformed, or fails verification - against its own internal checksum, pg_validatebackup - will terminate with a fatal error. - - - - Second, pg_validatebackup will attempt to verify that - the data files currently stored on disk are exactly the same as the data - files which the server intended to send, with some exceptions that are - described below. Extra and missing files will be detected, with a few - exceptions. This step will ignore the presence or absence of, or any - modifications to, postgresql.auto.conf, - standby.signal, and recovery.signal, - because it is expected that these files may have been created or modified - as part of the process of taking the backup. It also won't complain about - a backup_manifest file in the target directory or - about anything inside pg_wal, even though these - files won't be listed in the backup manifest. Only files are checked; - the presence or absence of directories is not verified, except - indirectly: if a directory is missing, any files it should have contained - will necessarily also be missing. - - - - Next, pg_validatebackup will checksum all the files, - compare the checksums against the values in the manifest, and emit errors - for any files for which the computed checksum does not match the - checksum stored in the manifest. This step is not performed for any files - which produced errors in the previous step, since they are already known - to have problems. Also, files which were ignored in the previous step are - also ignored in this step. - - - - Finally, pg_validatebackup will use the manifest to - verify that the write-ahead log records which will be needed to recover - the backup are present and that they can be read and parsed. The - backup_manifest contains information about which - write-ahead log records will be needed, and - pg_validatebackup will use that information to - invoke pg_waldump to parse those write-ahed log - records. The --quiet flag will be used, so that - pg_waldump will only report errors, without producing - any other output. While this level of verification is sufficient to - detect obvious problems such as a missing file or one whose internal - checksums do not match, they aren't extensive enough to detect every - possible problem that might occur when attempting to recover. For - instance, a server bug that produces write-ahead log records that have - the correct checksums but specify nonsensical actions can't be detected - by this method. - - - - Note that if extra WAL files which are not required to recover the backup - are present, they will not be checked by this tool, although - a separate invocation of pg_waldump could be used for - that purpose. Also note that WAL verification is version-specific: you - must use the version of pg_validatebackup, and thus of - pg_waldump, which pertains to the backup being checked. - In contrast, the data file integrity checks should work with any version - of the server that generates a backup_manifest file. - - - - - 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_validatebackup 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, when comparing the list of data files - actually present in the backup to those listed in the - backup_manifest file. If a directory is - specified, this option affects the entire subtree rooted at that - location. Complaints about extra files, missing files, file size - differences, or checksum mismatches will be suppressed if the - relative pathname matches the specified pathname. This option - can be specified multiple times. - - - - - - - - - - Use the manifest file at the specified path, rather than one located - in the root of the backup directory. - - - - - - - - - - Don't attempt to parse write-ahead log data that will be needed - to recover from this backup. - - - - - - - - - - Don't print anything when a backup is successfully validated. - - - - - - - - - - Do not validate data file 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 be read. - - - - - - - - - - Try to parse WAL files stored in the specified directory, rather than - in pg_wal. This may be useful if the backup is - stored in a separate location from the WAL archive. - - - - - - - - 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/ref/pg_verifybackup.sgml b/doc/src/sgml/ref/pg_verifybackup.sgml new file mode 100644 index 00000000000..0ab92b38f7b --- /dev/null +++ b/doc/src/sgml/ref/pg_verifybackup.sgml @@ -0,0 +1,291 @@ + + + + + pg_verifybackup + + + + pg_verifybackup + 1 + Application + + + + pg_verifybackup + verify the integrity of a base backup of a + PostgreSQL cluster + + + + + pg_verifybackup + option + + + + + + Description + + + pg_verifybackup is used to check the + integrity of a database cluster backup taken using + pg_basebackup against a + backup_manifest generated by the server at the time + of the backup. The backup must be stored in the "plain" + format; a "tar" format backup can be checked after extracting it. + + + + It is important to note that that the validation which is performed by + pg_verifybackup does not and can not include + every check which will be performed by a running server when attempting + to make use of the backup. Even if you use this tool, you should still + perform test restores and verify that the resulting databases work as + expected and that they appear to contain the correct data. However, + pg_verifybackup can detect many problems + that commonly occur due to storage problems or user error. + + + + Backup verification proceeds in four stages. First, + pg_verifybackup reads the + backup_manifest file. If that file + does not exist, cannot be read, is malformed, or fails verification + against its own internal checksum, pg_verifybackup + will terminate with a fatal error. + + + + Second, pg_verifybackup will attempt to verify that + the data files currently stored on disk are exactly the same as the data + files which the server intended to send, with some exceptions that are + described below. Extra and missing files will be detected, with a few + exceptions. This step will ignore the presence or absence of, or any + modifications to, postgresql.auto.conf, + standby.signal, and recovery.signal, + because it is expected that these files may have been created or modified + as part of the process of taking the backup. It also won't complain about + a backup_manifest file in the target directory or + about anything inside pg_wal, even though these + files won't be listed in the backup manifest. Only files are checked; + the presence or absence of directories is not verified, except + indirectly: if a directory is missing, any files it should have contained + will necessarily also be missing. + + + + Next, pg_verifybackup will checksum all the files, + compare the checksums against the values in the manifest, and emit errors + for any files for which the computed checksum does not match the + checksum stored in the manifest. This step is not performed for any files + which produced errors in the previous step, since they are already known + to have problems. Also, files which were ignored in the previous step are + also ignored in this step. + + + + Finally, pg_verifybackup will use the manifest to + verify that the write-ahead log records which will be needed to recover + the backup are present and that they can be read and parsed. The + backup_manifest contains information about which + write-ahead log records will be needed, and + pg_verifybackup will use that information to + invoke pg_waldump to parse those write-ahed log + records. The --quiet flag will be used, so that + pg_waldump will only report errors, without producing + any other output. While this level of verification is sufficient to + detect obvious problems such as a missing file or one whose internal + checksums do not match, they aren't extensive enough to detect every + possible problem that might occur when attempting to recover. For + instance, a server bug that produces write-ahead log records that have + the correct checksums but specify nonsensical actions can't be detected + by this method. + + + + Note that if extra WAL files which are not required to recover the backup + are present, they will not be checked by this tool, although + a separate invocation of pg_waldump could be used for + that purpose. Also note that WAL verification is version-specific: you + must use the version of pg_verifybackup, and thus of + pg_waldump, which pertains to the backup being checked. + In contrast, the data file integrity checks should work with any version + of the server that generates a backup_manifest file. + + + + + 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_validatebackup 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, when comparing the list of data files + actually present in the backup to those listed in the + backup_manifest file. If a directory is + specified, this option affects the entire subtree rooted at that + location. Complaints about extra files, missing files, file size + differences, or checksum mismatches will be suppressed if the + relative pathname matches the specified pathname. This option + can be specified multiple times. + + + + + + + + + + Use the manifest file at the specified path, rather than one located + in the root of the backup directory. + + + + + + + + + + Don't attempt to parse write-ahead log data that will be needed + to recover from this backup. + + + + + + + + + + Don't print anything when a backup is successfully verified. + + + + + + + + + + Do not verify data file 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 be read. + + + + + + + + + + Try to parse WAL files stored in the specified directory, rather than + in pg_wal. This may be useful if the backup is + stored in a separate location from the WAL archive. + + + + + + + + Other options are also available: + + + + + + + + Print the pg_verifybackup version and exit. + + + + + + + + + + Show help about pg_verifybackup command + line arguments, and exit. + + + + + + + + + + + Examples + + + To create a base backup of the server at mydbserver and + verify the integrity of the backup: + +$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data +$ pg_verifybackup /usr/local/pgsql/data + + + + + To create a base backup of the server at mydbserver, move + the manifest somewhere outside the backup directory, and verify 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_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/backup1234 + + + + + To verify 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_verifybackup --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 d25a77b13c8..dd2bddab8c4 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -255,7 +255,7 @@ &pgReceivewal; &pgRecvlogical; &pgRestore; - &pgValidateBackup; + &pgVerifyBackup; &psqlRef; &reindexdb; &vacuumdb; -- cgit v1.2.3