db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-09-16 09:06:18 +02:00
Code Issues Releases Activity

Improvements to command/command-line help:

Browse Source 
* Move repository options into a separate section in command/command-line help. (Suggested by Stephen Frost.)
* Fix description of --online based on the command context.
* Remove vestigial repository options from backup command.
This commit is contained in:
David Steele
2017-07-26 09:33:10 -04:00
parent 156fd4d54d
commit df7d633683
7 changed files with 244 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
doc/lib/BackRestDoc/Common/DocConfig.pm
View File

@@ -858,23 +858,15 @@ sub helpCommandDocGetOptionFind
{ {
$oOption = $$oConfigHelpData{&CONFIG_HELP_OPTION}{$strOption}; $oOption = $$oConfigHelpData{&CONFIG_HELP_OPTION}{$strOption};
if (defined($$oOption{&CONFIG_HELP_SECTION})) if (defined($$oOption{&CONFIG_HELP_SECTION}) && $strSection ne $strCommand)
{ {
$strSection = $$oOption{&CONFIG_HELP_SECTION}; $strSection = $$oOption{&CONFIG_HELP_SECTION};
if ($strSection eq CONFIG_SECTION_COMMAND)
{
$strSection = CONFIG_SECTION_GENERAL;
}
}
else
{
$strSection = CONFIG_SECTION_GENERAL;
} }
if (($strSection ne CONFIG_SECTION_GENERAL && $strSection ne CONFIG_SECTION_LOG && if (($strSection ne CONFIG_SECTION_GENERAL && $strSection ne CONFIG_SECTION_LOG &&
$strSection ne CONFIG_SECTION_STANZA && $strSection ne CONFIG_SECTION_EXPIRE) || $strSection ne CONFIG_SECTION_REPOSITORY && $strSection ne CONFIG_SECTION_STANZA &&
$strSection eq $strCommand) $strSection ne CONFIG_SECTION_EXPIRE) ||
$strSection eq $strCommand)
{ {
$strSection = CONFIG_HELP_COMMAND; $strSection = CONFIG_HELP_COMMAND;
} }

223
doc/xml/reference.xml
View File

@@ -69,6 +69,15 @@
<example>error</example> <example>error</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - LOG-PATH KEY -->
<config-key id="log-path" name="Log Path">
<summary>Path where log files are stored.</summary>
<text>The log path provides a location for <backrest/> to store log files. Note that if <setting>log-level-file=none</setting> then no log path is required.</text>
<example>/backup/db/log</example>
</config-key>
<!-- CONFIG - LOG SECTION - LOG-TIMESTAMP KEY --> <!-- CONFIG - LOG SECTION - LOG-TIMESTAMP KEY -->
<config-key id="log-timestamp" name="Log Timestamp"> <config-key id="log-timestamp" name="Log Timestamp">
<summary>Enable timestamp in logging.</summary> <summary>Enable timestamp in logging.</summary>
@@ -82,18 +91,9 @@
<!-- CONFIG - GENERAL --> <!-- CONFIG - GENERAL -->
<config-section id="general" name="General"> <config-section id="general" name="General">
<text>The <setting>general</setting> section defines settings that are shared between multiple operations.</text> <text>The <setting>general</setting> section defines options that are common for many commands.</text>
<!-- CONFIG - GENERAL SECTION - ARCHIVE-TIMEOUT -->
<config-key-list> <config-key-list>
<config-key id="archive-timeout" name="Archive Timeout">
<summary>Archive timeout.</summary>
<text>Set maximum time, in seconds, to wait for WAL segments to reach the archive. The timeout applies to the <cmd>check</cmd> command and to the <cmd>backup</cmd> command when waiting for WAL segments required to make the backup consistent to be archived.</text>
<example>30</example>
</config-key>
<config-key id="buffer-size" name="Buffer Size"> <config-key id="buffer-size" name="Buffer Size">
<summary>Buffer size for file operations.</summary> <summary>Buffer size for file operations.</summary>
@@ -141,17 +141,6 @@
<example>1</example> <example>1</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - CHECKSUM-PAGE KEY -->
<config-key id="checksum-page" name="Page Checksums">
<summary>Validate data page checksums.</summary>
<text>Directs <backrest/> to validate all data page checksums while backing up a cluster. This option will be automatically enabled when the required C library is present and checksums are enabled on the cluster.
Failures in checksum validation will not abort a backup. Rather, warnings will be emitted in the log (and to the console with default settings) and the list of invalid pages will be stored in the backup manifest.</text>
<example>n</example>
</config-key>
<!-- CONFIG - GENERAL SECTION - DB-TIMEOUT KEY --> <!-- CONFIG - GENERAL SECTION - DB-TIMEOUT KEY -->
<config-key id="db-timeout" name="Database Timeout"> <config-key id="db-timeout" name="Database Timeout">
<summary>Database query timeout.</summary> <summary>Database query timeout.</summary>
@@ -170,15 +159,6 @@
<example>/backup/db/lock</example> <example>/backup/db/lock</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - LOG-PATH KEY -->
<config-key id="log-path" name="Log Path">
<summary>Path where log files are stored.</summary>
<text>The log path provides a location for <backrest/> to store log files. Note that if <setting>log-level-file=none</setting> then no log path is required.</text>
<example>/backup/db/log</example>
</config-key>
<!-- CONFIG - GENERAL SECTION - NEUTRAL-UMASK --> <!-- CONFIG - GENERAL SECTION - NEUTRAL-UMASK -->
<config-key id="neutral-umask" name="Neutral Umask"> <config-key id="neutral-umask" name="Neutral Umask">
<summary>Use a neutral umask.</summary> <summary>Use a neutral umask.</summary>
@@ -217,8 +197,54 @@
<example>630</example> <example>630</example>
</config-key> </config-key>
</config-key-list>
</config-section>
<!-- CONFIG - GENERAL SECTION - REPO-PATH KEY --> <!-- CONFIG - REPO -->
<config-section id="repository" name="Repository">
<text>The <setting>repository</setting> section defines options used to configure the repository.</text>
<config-key-list>
<!-- CONFIG - REPO SECTION - BACKUP-CMD KEY -->
<config-key id="backup-cmd" name="Backup Host Command">
<summary><backrest/> exe path on the backup host.</summary>
<text>Required only if the path to <exe/> is different on the local and backup hosts. If not defined, the backup host exe path will be set the same as the local exe path.</text>
<default>same as local</default>
<example>/usr/lib/backrest/bin/pgbackrest</example>
</config-key>
<!-- CONFIG - REPO SECTION - BACKUP-CONFIG KEY -->
<config-key id="backup-config" name="Backup Host Configuration">
<summary><backrest/> backup host configuration file.</summary>
<text>Sets the location of the configuration file on the backup host. This is only required if the backup host configuration file is in a different location than the local configuration file.</text>
<example>/etc/pgbackrest_backup.conf</example>
</config-key>
<!-- CONFIG - REPO SECTION - BACKUP-HOST KEY -->
<config-key id="backup-host" name="Backup Host">
<summary>Backup host when operating remotely via SSH.</summary>
<text>Make sure that trusted SSH authentication is configured between the db host and the backup host.
When backing up to a locally mounted network filesystem this setting is not required.</text>
<example>backup.domain.com</example>
</config-key>
<!-- CONFIG - REPO SECTION - BACKUP-USER KEY -->
<config-key id="backup-user" name="Backup User">
<summary>Backup host user when <setting>backup-host</setting> is set.</summary>
<text>Defines the user that will be used for operations on the backup server. Preferably this is not the <id>postgres</id> user but rather some other user like <id>backrest</id>. If <postgres/> runs on the backup server the <id>postgres</id> user can be placed in the <id>backrest</id> group so it has read permissions on the repository without being able to damage the contents accidentally.</text>
<example>backrest</example>
</config-key>
<!-- CONFIG - REPO SECTION - REPO-PATH KEY -->
<config-key id="repo-path" name="Repository Path"> <config-key id="repo-path" name="Repository Path">
<summary>Repository path where WAL segments and backups stored.</summary> <summary>Repository path where WAL segments and backups stored.</summary>
@@ -229,7 +255,7 @@
<example>/backup/db/backrest</example> <example>/backup/db/backrest</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-KEY KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-KEY KEY -->
<config-key id="repo-s3-key" name="S3 Repository Access Key"> <config-key id="repo-s3-key" name="S3 Repository Access Key">
<summary>S3 repository access key.</summary> <summary>S3 repository access key.</summary>
@@ -238,7 +264,7 @@
<example>AKIAIOSFODNN7EXAMPLE</example> <example>AKIAIOSFODNN7EXAMPLE</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-KEY-SECRET KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-KEY-SECRET KEY -->
<config-key id="repo-s3-key-secret" name="S3 Repository Secret Access Key"> <config-key id="repo-s3-key-secret" name="S3 Repository Secret Access Key">
<summary>S3 repository secret access key.</summary> <summary>S3 repository secret access key.</summary>
@@ -247,7 +273,7 @@
<example>wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY</example> <example>wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-BUCKET KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-BUCKET KEY -->
<config-key id="repo-s3-bucket" name="S3 Repository Bucket"> <config-key id="repo-s3-bucket" name="S3 Repository Bucket">
<summary>S3 repository bucket.</summary> <summary>S3 repository bucket.</summary>
@@ -258,7 +284,7 @@
<example>db-backup</example> <example>db-backup</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-CA-FILE KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-CA-FILE KEY -->
<config-key id="repo-s3-ca-file" name="S3 SSL CA File"> <config-key id="repo-s3-ca-file" name="S3 SSL CA File">
<summary>S3 SSL CA File.</summary> <summary>S3 SSL CA File.</summary>
@@ -267,7 +293,7 @@
<example>/etc/pki/tls/certs/ca-bundle.crt</example> <example>/etc/pki/tls/certs/ca-bundle.crt</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-CA-PATH KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-CA-PATH KEY -->
<config-key id="repo-s3-ca-path" name="S3 SSL CA Path"> <config-key id="repo-s3-ca-path" name="S3 SSL CA Path">
<summary>S3 SSL CA Path.</summary> <summary>S3 SSL CA Path.</summary>
@@ -276,7 +302,7 @@
<example>/etc/pki/tls/certs</example> <example>/etc/pki/tls/certs</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-ENDPOINT KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-ENDPOINT KEY -->
<config-key id="repo-s3-endpoint" name="S3 Repository Endpoint"> <config-key id="repo-s3-endpoint" name="S3 Repository Endpoint">
<summary>S3 repository endpoint.</summary> <summary>S3 repository endpoint.</summary>
@@ -285,7 +311,7 @@
<example>s3.amazonaws.com</example> <example>s3.amazonaws.com</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-HOST KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-HOST KEY -->
<config-key id="repo-s3-host" name="S3 Repository Host"> <config-key id="repo-s3-host" name="S3 Repository Host">
<summary>S3 repository host.</summary> <summary>S3 repository host.</summary>
@@ -294,7 +320,7 @@
<example>127.0.0.1</example> <example>127.0.0.1</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-REGION KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-REGION KEY -->
<config-key id="repo-s3-region" name="S3 Repository Region"> <config-key id="repo-s3-region" name="S3 Repository Region">
<summary>S3 repository region.</summary> <summary>S3 repository region.</summary>
@@ -303,7 +329,7 @@
<example>us-east-1</example> <example>us-east-1</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-S3-VERIFY-SSL KEY --> <!-- CONFIG - REPO SECTION - REPO-S3-VERIFY-SSL KEY -->
<config-key id="repo-s3-verify-ssl" name="S3 Repository Verify SSL"> <config-key id="repo-s3-verify-ssl" name="S3 Repository Verify SSL">
<summary>Verify S3 server certificate.</summary> <summary>Verify S3 server certificate.</summary>
@@ -312,7 +338,7 @@
<example>n</example> <example>n</example>
</config-key> </config-key>
<!-- CONFIG - GENERAL SECTION - REPO-TYPE KEY --> <!-- CONFIG - REPO SECTION - REPO-TYPE KEY -->
<config-key id="repo-type" name="Repository Type"> <config-key id="repo-type" name="Repository Type">
<summary>Type of storage used for the repository.</summary> <summary>Type of storage used for the repository.</summary>
@@ -353,45 +379,6 @@
<example>y</example> <example>y</example>
</config-key> </config-key>
<!-- CONFIG - BACKUP SECTION - BACKUP-CMD KEY -->
<config-key id="backup-cmd" name="Backup Host Command">
<summary><backrest/> exe path on the backup host.</summary>
<text>Required only if the path to <exe/> is different on the local and backup hosts. If not defined, the backup host exe path will be set the same as the local exe path.</text>
<default>same as local</default>
<example>/usr/lib/backrest/bin/pgbackrest</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - BACKUP-CONFIG KEY -->
<config-key id="backup-config" name="Backup Host Configuration">
<summary><backrest/> backup host configuration file.</summary>
<text>Sets the location of the configuration file on the backup host. This is only required if the backup host configuration file is in a different location than the local configuration file.</text>
<example>/etc/pgbackrest_backup.conf</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - BACKUP-HOST KEY -->
<config-key id="backup-host" name="Backup Host">
<summary>Backup host when operating remotely via SSH.</summary>
<text>Make sure that trusted SSH authentication is configured between the db host and the backup host.
When backing up to a locally mounted network filesystem this setting is not required.</text>
<example>backup.domain.com</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - BACKUP-USER KEY -->
<config-key id="backup-user" name="Backup User">
<summary>Backup host user when <setting>backup-host</setting> is set.</summary>
<text>Defines the user that will be used for operations on the backup server. Preferably this is not the <id>postgres</id> user but rather some other user like <id>backrest</id>. If <postgres/> runs on the backup server the <id>postgres</id> user can be placed in the <id>backrest</id> group so it has read permissions on the repository without being able to damage the contents accidentally.</text>
<example>backrest</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - BACKUP-STANDBY KEY --> <!-- CONFIG - BACKUP SECTION - BACKUP-STANDBY KEY -->
<config-key id="backup-standby" name="Backup from Standby"> <config-key id="backup-standby" name="Backup from Standby">
<summary>Backup from the standby cluster.</summary> <summary>Backup from the standby cluster.</summary>
@@ -401,6 +388,17 @@
<example>y</example> <example>y</example>
</config-key> </config-key>
<!-- CONFIG - BACKUP SECTION - CHECKSUM-PAGE KEY -->
<config-key id="checksum-page" name="Page Checksums">
<summary>Validate data page checksums.</summary>
<text>Directs <backrest/> to validate all data page checksums while backing up a cluster. This option will be automatically enabled when the required C library is present and checksums are enabled on the cluster.
Failures in checksum validation will not abort a backup. Rather, warnings will be emitted in the log (and to the console with default settings) and the list of invalid pages will be stored in the backup manifest.</text>
<example>n</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - HARDLINK --> <!-- CONFIG - BACKUP SECTION - HARDLINK -->
<config-key id="hardlink" name="Hardlink"> <config-key id="hardlink" name="Hardlink">
<summary>Hardlink files between backups.</summary> <summary>Hardlink files between backups.</summary>
@@ -485,6 +483,15 @@
<example>1073741824</example> <example>1073741824</example>
</config-key> </config-key>
<!-- ======================================================================================================= -->
<config-key id="archive-timeout" name="Archive Timeout">
<summary>Archive timeout.</summary>
<text>Set maximum time, in seconds, to wait for WAL segments to reach the archive. The timeout applies to the <cmd>check</cmd> command and to the <cmd>backup</cmd> command when waiting for WAL segments required to make the backup consistent to be archived.</text>
<example>30</example>
</config-key>
</config-key-list> </config-key-list>
</config-section> </config-section>
@@ -702,7 +709,7 @@
<!-- OPERATION - GENERAL - STANZA OPTION --> <!-- OPERATION - GENERAL - STANZA OPTION -->
<option id="stanza" name="Stanza"> <option id="stanza" name="Stanza">
<summary>Defines a stanza.</summary> <summary>Defines the stanza.</summary>
<text>A stanza is the configuration for a <postgres/> database cluster that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one Postgres database cluster and therefore one stanza, whereas backup servers will have a stanza for every database cluster that needs to be backed up. <text>A stanza is the configuration for a <postgres/> database cluster that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one Postgres database cluster and therefore one stanza, whereas backup servers will have a stanza for every database cluster that needs to be backed up.
@@ -710,18 +717,6 @@
<example>main</example> <example>main</example>
</option> </option>
<!-- OPERATION - GENERAL - ONLINE OPTION -->
<option id="online" name="Online">
<summary>Perform an online backup.</summary>
<text>Specifying --no-online prevents <backrest/> from running <code>pg_start_backup()</code> and <code>pg_stop_backup()</code> on the database cluster. In order for this to work <postgres/> should be shut down and <backrest/> will generate an error if it is not.
The purpose of this option is to allow offline backups. The <path>pg_xlog</path> directory is copied as-is and <setting>archive-check</setting> is automatically disabled for the backup.</text>
<example>n</example>
</option>
</option-list> </option-list>
</operation-general> </operation-general>
@@ -757,6 +752,17 @@
<example>y</example> <example>y</example>
</option> </option>
<!-- ======================================================================================================= -->
<option id="online" name="Online">
<summary>Perform an online backup.</summary>
<text>Specifying --no-online prevents <backrest/> from running <code>pg_start_backup()</code> and <code>pg_stop_backup()</code> on the database cluster. In order for this to work <postgres/> should be shut down and <backrest/> will generate an error if it is not.
The purpose of this option is to allow offline backups. The <path>pg_xlog</path> directory is copied as-is and <setting>archive-check</setting> is automatically disabled for the backup.</text>
<example>n</example>
</option>
</option-list> </option-list>
<command-example-list> <command-example-list>
@@ -809,6 +815,17 @@
Note that <code>pg_create_restore_point('pgBackRest Archive Check')</code> and <code>pg_switch_xlog()</code> are called to force <postgres/> to archive a WAL segment. Restore points are only supported in <postgres/> &gt;= 9.1 so for older versions the <cmd>check</cmd> command may fail if there has been no write activity since the last log rotation, therefore it is recommended that activity be generated by the user if there have been no writes since the last xlog switch before running the <cmd>check</cmd> command.</text> Note that <code>pg_create_restore_point('pgBackRest Archive Check')</code> and <code>pg_switch_xlog()</code> are called to force <postgres/> to archive a WAL segment. Restore points are only supported in <postgres/> &gt;= 9.1 so for older versions the <cmd>check</cmd> command may fail if there has been no write activity since the last log rotation, therefore it is recommended that activity be generated by the user if there have been no writes since the last xlog switch before running the <cmd>check</cmd> command.</text>
<option-list>
<!-- ======================================================================================================= -->
<option id="online" name="Online">
<summary>Check an online cluster.</summary>
<text>Specifying --no-online prevents <backrest/> from connecting to <postgres/> and will disable some checks.</text>
<example>n</example>
</option>
</option-list>
<command-example-list> <command-example-list>
<command-example> <command-example>
<text><code-block title=""> <text><code-block title="">
@@ -1082,6 +1099,15 @@
<example>n</example> <example>n</example>
</option> </option>
<!-- ======================================================================================================= -->
<option id="online" name="Online">
<summary>Create on an online cluster.</summary>
<text>Specifying --no-online prevents <backrest/> from connecting to <postgres/> when creating the stanza.</text>
<example>n</example>
</option>
</option-list> </option-list>
<command-example-list> <command-example-list>
@@ -1101,6 +1127,17 @@
<text>Immediately after upgrading <postgres/> to a newer major version, the <br-option>db-path</br-option> for all <backrest/> configurations must be set to the new database location and the <cmd>stanza-upgrade</cmd> run on the backup host. If the database is offline use the <br-option>--no-online</br-option> option.</text> <text>Immediately after upgrading <postgres/> to a newer major version, the <br-option>db-path</br-option> for all <backrest/> configurations must be set to the new database location and the <cmd>stanza-upgrade</cmd> run on the backup host. If the database is offline use the <br-option>--no-online</br-option> option.</text>
<option-list>
<!-- ======================================================================================================= -->
<option id="online" name="Online">
<summary>Update an online cluster.</summary>
<text>Specifying --no-online prevents <backrest/> from connecting to <postgres/> when upgrading the stanza.</text>
<example>n</example>
</option>
</option-list>
<command-example-list> <command-example-list>
<command-example title="Upgrade a stanza"> <command-example title="Upgrade a stanza">
<text><code-block title=""> <text><code-block title="">

18
doc/xml/release.xml
View File

@@ -193,6 +193,12 @@
</release-core-list> </release-core-list>
<release-doc-list> <release-doc-list>
<release-bug-list>
<release-item>
<p>Fix description of <br-option>--online</br-option> based on the command context.</p>
</release-item>
</release-bug-list>
<release-feature-list> <release-feature-list>
<release-item> <release-item>
<p>Add creation of <file>/etc/pgbackrest.conf</file> to manual installation instructions.</p> <p>Add creation of <file>/etc/pgbackrest.conf</file> to manual installation instructions.</p>
@@ -203,6 +209,18 @@
<release-item> <release-item>
<p>Debian/Ubuntu documentation now builds on Ubuntu 16.</p> <p>Debian/Ubuntu documentation now builds on Ubuntu 16.</p>
</release-item> </release-item>
<release-item>
<release-item-contributor-list>
<release-item-ideator id="frost.stephen"/>
</release-item-contributor-list>
<p>Move repository options into a separate section in command/command-line help.</p>
</release-item>
<release-item>
<p>Remove vestigial repository options from <cmd>backup</cmd> command.</p>
</release-item>
</release-refactor-list> </release-refactor-list>
</release-doc-list> </release-doc-list>

4
lib/pgBackRest/Config/Config.pm
View File

@@ -1600,7 +1600,6 @@ my %oOptionRule =
{ {
&CMD_ARCHIVE_GET => true, &CMD_ARCHIVE_GET => true,
&CMD_ARCHIVE_PUSH => true, &CMD_ARCHIVE_PUSH => true,
&CMD_BACKUP => true,
&CMD_CHECK => true, &CMD_CHECK => true,
&CMD_INFO => true, &CMD_INFO => true,
&CMD_LOCAL => true, &CMD_LOCAL => true,
@@ -1625,7 +1624,6 @@ my %oOptionRule =
{ {
&CMD_ARCHIVE_GET => true, &CMD_ARCHIVE_GET => true,
&CMD_ARCHIVE_PUSH => true, &CMD_ARCHIVE_PUSH => true,
&CMD_BACKUP => true,
&CMD_CHECK => true, &CMD_CHECK => true,
&CMD_INFO => true, &CMD_INFO => true,
&CMD_LOCAL => true, &CMD_LOCAL => true,
@@ -1650,9 +1648,7 @@ my %oOptionRule =
{ {
&CMD_ARCHIVE_GET => true, &CMD_ARCHIVE_GET => true,
&CMD_ARCHIVE_PUSH => true, &CMD_ARCHIVE_PUSH => true,
&CMD_BACKUP => true,
&CMD_CHECK => true, &CMD_CHECK => true,
&CMD_EXPIRE => true,
&CMD_INFO => true, &CMD_INFO => true,
&CMD_LOCAL => true, &CMD_LOCAL => true,
&CMD_RESTORE => true, &CMD_RESTORE => true,

7
lib/pgBackRest/Config/ConfigHelp.pm
View File

@@ -56,6 +56,8 @@ use constant CONFIG_SECTION_LOG => 'log';
push @EXPORT, qw(CONFIG_SECTION_LOG); push @EXPORT, qw(CONFIG_SECTION_LOG);
use constant CONFIG_SECTION_EXPIRE => 'expire'; use constant CONFIG_SECTION_EXPIRE => 'expire';
push @EXPORT, qw(CONFIG_SECTION_EXPIRE); push @EXPORT, qw(CONFIG_SECTION_EXPIRE);
use constant CONFIG_SECTION_REPOSITORY => 'repository';
push @EXPORT, qw(CONFIG_SECTION_REPOSITORY);
#################################################################################################################################### ####################################################################################################################################
# configHelp # configHelp
@@ -368,8 +370,9 @@ sub configHelpOptionFind
} }
if (($strSection ne CONFIG_SECTION_GENERAL && $strSection ne CONFIG_SECTION_LOG && if (($strSection ne CONFIG_SECTION_GENERAL && $strSection ne CONFIG_SECTION_LOG &&
$strSection ne CONFIG_SECTION_STANZA && $strSection ne CONFIG_SECTION_EXPIRE) || $strSection ne CONFIG_SECTION_REPOSITORY && $strSection ne CONFIG_SECTION_STANZA &&
$strSection eq $strCommand) $strSection ne CONFIG_SECTION_EXPIRE) ||
$strSection eq $strCommand)
{ {
$strSection = CONFIG_HELP_COMMAND; $strSection = CONFIG_HELP_COMMAND;
} }

110
lib/pgBackRest/Config/ConfigHelpData.pm
View File

@@ -91,7 +91,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'archive-timeout' => 'archive-timeout' =>
{ {
section => 'general', section => 'archive',
summary => summary =>
"Archive timeout.", "Archive timeout.",
description => description =>
@@ -104,7 +104,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'backup-cmd' => 'backup-cmd' =>
{ {
section => 'backup', section => 'repository',
summary => summary =>
"pgBackRest exe path on the backup host.", "pgBackRest exe path on the backup host.",
description => description =>
@@ -116,7 +116,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'backup-config' => 'backup-config' =>
{ {
section => 'backup', section => 'repository',
summary => summary =>
"pgBackRest backup host configuration file.", "pgBackRest backup host configuration file.",
description => description =>
@@ -128,7 +128,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'backup-host' => 'backup-host' =>
{ {
section => 'backup', section => 'repository',
summary => summary =>
"Backup host when operating remotely via SSH.", "Backup host when operating remotely via SSH.",
description => description =>
@@ -153,7 +153,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'backup-user' => 'backup-user' =>
{ {
section => 'backup', section => 'repository',
summary => summary =>
"Backup host user when backup-host is set.", "Backup host user when backup-host is set.",
description => description =>
@@ -179,7 +179,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'checksum-page' => 'checksum-page' =>
{ {
section => 'general', section => 'backup',
summary => summary =>
"Validate data page checksums.", "Validate data page checksums.",
description => description =>
@@ -483,7 +483,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'log-path' => 'log-path' =>
{ {
section => 'general', section => 'log',
summary => summary =>
"Path where log files are stored.", "Path where log files are stored.",
description => description =>
@@ -532,21 +532,6 @@ my $oConfigHelpData =
"the command line." "the command line."
}, },
# ONLINE Option Help
#---------------------------------------------------------------------------------------------------------------------------
'online' =>
{
summary =>
"Perform an online backup.",
description =>
"Specifying --no-online prevents pgBackRest from running pg_start_backup() and pg_stop_backup() on the database " .
"cluster. In order for this to work PostgreSQL should be shut down and pgBackRest will generate an error if " .
"it is not.\n" .
"\n" .
"The purpose of this option is to allow offline backups. The pg_xlog directory is copied as-is and " .
"archive-check is automatically disabled for the backup."
},
# PROCESS-MAX Option Help # PROCESS-MAX Option Help
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'process-max' => 'process-max' =>
@@ -596,7 +581,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-path' => 'repo-path' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"Repository path where WAL segments and backups stored.", "Repository path where WAL segments and backups stored.",
description => description =>
@@ -612,7 +597,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-bucket' => 'repo-s3-bucket' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository bucket.", "S3 repository bucket.",
description => description =>
@@ -626,7 +611,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-ca-file' => 'repo-s3-ca-file' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 SSL CA File.", "S3 SSL CA File.",
description => description =>
@@ -637,7 +622,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-ca-path' => 'repo-s3-ca-path' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 SSL CA Path.", "S3 SSL CA Path.",
description => description =>
@@ -648,7 +633,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-endpoint' => 'repo-s3-endpoint' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository endpoint.", "S3 repository endpoint.",
description => description =>
@@ -659,7 +644,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-host' => 'repo-s3-host' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository host.", "S3 repository host.",
description => description =>
@@ -670,7 +655,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-key' => 'repo-s3-key' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository access key.", "S3 repository access key.",
description => description =>
@@ -681,7 +666,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-key-secret' => 'repo-s3-key-secret' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository secret access key.", "S3 repository secret access key.",
description => description =>
@@ -692,7 +677,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-region' => 'repo-s3-region' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"S3 repository region.", "S3 repository region.",
description => description =>
@@ -703,7 +688,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-s3-verify-ssl' => 'repo-s3-verify-ssl' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"Verify S3 server certificate.", "Verify S3 server certificate.",
description => description =>
@@ -715,7 +700,7 @@ my $oConfigHelpData =
#--------------------------------------------------------------------------------------------------------------------------- #---------------------------------------------------------------------------------------------------------------------------
'repo-type' => 'repo-type' =>
{ {
section => 'general', section => 'repository',
summary => summary =>
"Type of storage used for the repository.", "Type of storage used for the repository.",
description => description =>
@@ -822,7 +807,7 @@ my $oConfigHelpData =
'stanza' => 'stanza' =>
{ {
summary => summary =>
"Defines a stanza.", "Defines the stanza.",
description => description =>
"A stanza is the configuration for a PostgreSQL database cluster that defines where it is located, how it will " . "A stanza is the configuration for a PostgreSQL database cluster that defines where it is located, how it will " .
"be backed up, archiving options, etc. Most db servers will only have one Postgres database cluster and " . "be backed up, archiving options, etc. Most db servers will only have one Postgres database cluster and " .
@@ -1018,9 +1003,6 @@ my $oConfigHelpData =
'archive-check' => 'section', 'archive-check' => 'section',
'archive-copy' => 'section', 'archive-copy' => 'section',
'archive-timeout' => 'section', 'archive-timeout' => 'section',
'backup-cmd' => 'section',
'backup-config' => 'section',
'backup-host' => 'section',
'backup-standby' => 'section', 'backup-standby' => 'section',
'buffer-size' => 'section', 'buffer-size' => 'section',
'checksum-page' => 'section', 'checksum-page' => 'section',
@@ -1064,7 +1046,22 @@ my $oConfigHelpData =
'log-timestamp' => 'section', 'log-timestamp' => 'section',
'manifest-save-threshold' => 'section', 'manifest-save-threshold' => 'section',
'neutral-umask' => 'section', 'neutral-umask' => 'section',
'online' => 'default',
# ONLINE Option Help
#-------------------------------------------------------------------------------------------------------------------
'online' =>
{
summary =>
"Perform an online backup.",
description =>
"Specifying --no-online prevents pgBackRest from running pg_start_backup() and pg_stop_backup() on the " .
"database cluster. In order for this to work PostgreSQL should be shut down and pgBackRest will " .
"generate an error if it is not.\n" .
"\n" .
"The purpose of this option is to allow offline backups. The pg_xlog directory is copied as-is and " .
"archive-check is automatically disabled for the backup."
},
'process-max' => 'section', 'process-max' => 'section',
'protocol-timeout' => 'section', 'protocol-timeout' => 'section',
'repo-path' => 'section', 'repo-path' => 'section',
@@ -1151,7 +1148,17 @@ my $oConfigHelpData =
'log-path' => 'section', 'log-path' => 'section',
'log-timestamp' => 'section', 'log-timestamp' => 'section',
'neutral-umask' => 'section', 'neutral-umask' => 'section',
'online' => 'default',
# ONLINE Option Help
#-------------------------------------------------------------------------------------------------------------------
'online' =>
{
summary =>
"Check an online cluster.",
description =>
"Specifying --no-online prevents pgBackRest from connecting to PostgreSQL and will disable some checks."
},
'protocol-timeout' => 'section', 'protocol-timeout' => 'section',
'repo-path' => 'section', 'repo-path' => 'section',
'repo-s3-bucket' => 'section', 'repo-s3-bucket' => 'section',
@@ -1181,7 +1188,6 @@ my $oConfigHelpData =
option => option =>
{ {
'backup-host' => 'section',
'cmd-ssh' => 'section', 'cmd-ssh' => 'section',
'config' => 'default', 'config' => 'default',
'db-cmd' => 'section', 'db-cmd' => 'section',
@@ -1494,7 +1500,17 @@ my $oConfigHelpData =
'log-path' => 'section', 'log-path' => 'section',
'log-timestamp' => 'section', 'log-timestamp' => 'section',
'neutral-umask' => 'section', 'neutral-umask' => 'section',
'online' => 'default',
# ONLINE Option Help
#-------------------------------------------------------------------------------------------------------------------
'online' =>
{
summary =>
"Create on an online cluster.",
description =>
"Specifying --no-online prevents pgBackRest from connecting to PostgreSQL when creating the stanza."
},
'protocol-timeout' => 'section', 'protocol-timeout' => 'section',
'repo-path' => 'section', 'repo-path' => 'section',
'repo-s3-bucket' => 'section', 'repo-s3-bucket' => 'section',
@@ -1546,7 +1562,17 @@ my $oConfigHelpData =
'log-level-file' => 'section', 'log-level-file' => 'section',
'log-path' => 'section', 'log-path' => 'section',
'neutral-umask' => 'section', 'neutral-umask' => 'section',
'online' => 'default',
# ONLINE Option Help
#-------------------------------------------------------------------------------------------------------------------
'online' =>
{
summary =>
"Update an online cluster.",
description =>
"Specifying --no-online prevents pgBackRest from connecting to PostgreSQL when upgrading the stanza."
},
'protocol-timeout' => 'section', 'protocol-timeout' => 'section',
'repo-path' => 'section', 'repo-path' => 'section',
'repo-s3-bucket' => 'section', 'repo-s3-bucket' => 'section',

35
test/expect/help-help-001.log
View File

@@ -53,13 +53,6 @@ experimental so the format may change between versions.
Command Options: Command Options:
--backup-cmd pgBackRest exe path on the backup host
[default=[BACKREST-BIN]]
--backup-config pgBackRest backup host configuration file
[default=/etc/pgbackrest.conf]
--backup-host backup host when operating remotely via SSH
--backup-user backup host user when backup-host is set
[default=backrest]
--output output format [current=json, default=text] --output output format [current=json, default=text]
General Options: General Options:
@@ -73,9 +66,27 @@ compress=n [default=3]
[default=/etc/pgbackrest.conf] [default=/etc/pgbackrest.conf]
--lock-path path where lock files are stored --lock-path path where lock files are stored
[default=/tmp/pgbackrest] [default=/tmp/pgbackrest]
--protocol-timeout protocol timeout [default=1830]
--stanza defines the stanza [current=main]
Log Options:
--log-level-console level for console logging [default=warn]
--log-level-file level for file logging [default=info]
--log-level-stderr level for stderr logging [default=warn]
--log-path path where log files are stored --log-path path where log files are stored
[default=/var/log/pgbackrest] [default=/var/log/pgbackrest]
--protocol-timeout protocol timeout [default=1830] --log-timestamp enable timestamp in logging [default=y]
Repository Options:
--backup-cmd pgBackRest exe path on the backup host
[default=[BACKREST-BIN]]
--backup-config pgBackRest backup host configuration file
[default=/etc/pgbackrest.conf]
--backup-host backup host when operating remotely via SSH
--backup-user backup host user when backup-host is set
[default=backrest]
--repo-path repository path where WAL segments and backups --repo-path repository path where WAL segments and backups
stored [default=/var/lib/pgbackrest] stored [default=/var/lib/pgbackrest]
--repo-s3-bucket s3 repository bucket --repo-s3-bucket s3 repository bucket
@@ -89,14 +100,6 @@ stored [default=/var/lib/pgbackrest]
--repo-s3-verify-ssl verify S3 server certificate [default=y] --repo-s3-verify-ssl verify S3 server certificate [default=y]
--repo-type type of storage used for the repository --repo-type type of storage used for the repository
[default=posix] [default=posix]
--stanza defines a stanza [current=main]
Log Options:
--log-level-console level for console logging [default=warn]
--log-level-file level for file logging [default=info]
--log-level-stderr level for stderr logging [default=warn]
--log-timestamp enable timestamp in logging [default=y]
Use 'pgbackrest help info [option]' for more information. Use 'pgbackrest help info [option]' for more information.