db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-01-18 04:58:51 +02:00
Code Issues Releases Activity

More work on automated docs. Merging this to go back to some feature/bug work for a while.

Browse Source
This commit is contained in:
David Steele 2015-03-16 14:01:01 -04:00
parent 882f068254
commit 258fb9c6e2
6 changed files with 654 additions and 461 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
README.md
View File

@ -75,6 +75,219 @@ Setup trusted ssh between test user account and backrest_dev
Backrest user and test user must be in the same group
```
## Operations
PgBackRest is intended to be run from a scheduler like cron as there is no built-in scheduler.
### General Options
These options are either global or used by all operations.
#### `type` option
By default PgBackRest expects the its configuration file to be located at `/etc/pg_backrest.conf`. Use this option to specify another location.
```
required: n
example: type=/path/to/backrest/pg_backrest.conf
```
#### `stanza` option
Defines the stanza for the operation. A stanza is the configuration for a database that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one Postgres cluster and therefore one stanza, whereas backup servers will have a stanza for every database that needs to be backed up.
Examples of how to configure a stanza can be found in the `configuration examples` section.
```
required: n
example: stanza=main
```
#### `help` option
Displays the PgBackRest help.
```
required: n
```
#### `version` option
Displays the PgBackRest version.
```
required: n
```
### Commands
Sample text for the commands, which I'm sure will be very, very interesting.
#### `backup` command
Perform a database backup.
##### `type` option
The following backup types are supported:
- `full` - all database files will be copied and there will be no dependencies on previous backups.
- `incr` - incremental from the last successful backup.
- `warn` - like an incremental backup but always based on the last full backup.
```
required: n
default: incr
example: type=full
```
##### `no-start-stop` option
This option prevents PgBackRest from running `pg_start_backup()` and `pg_stop_backup()` on the database. In order for this to work Postgres should be shut down and PgBackRest will generate an error if it is not.
The purpose of this option is to allow cold backups. The `pg_xlog` directory is copied as-is and `archive-required` is automatically disabled for the backup.
```
required: n
default: n
```
##### `force` option
When used with `--no-start-stop` a backup will be run even if PgBackRest thinks that Postgres is running. **This option should be used with extreme care as it will likely result in a bad backup.**
There are some scenarios where a backup might still be desirable under these conditions. For example, if a server crashes and database volume can only be mounted read-only, it would be a good idea to take a backup even if `postmaster.pid` is present. In this case it would be better to revert to the prior backup and replay WAL, but possibly there is a very important transaction in a WAL log that did not get archived.
```
required: n
default: n
```
##### Example: Full Backup
```
/path/to/pg_backrest.pl --stanza=db --type=full backup
```
Run a `full` backup on the `db` stanza. `--type` can also be set to `incr` or `diff` for incremental or differential backups. However, if no `full` backup exists then a `full` backup will be forced even if `incr` or `diff` is requested.
#### `archive-push` command
Archive a WAL segment to the repository.
##### Example
```
/path/to/pg_backrest.pl --stanza=db archive-push %p
```
Accepts a WAL segment from PostgreSQL and archives it in the repository. `%p` is how PostgreSQL specifies the location of the WAL segment to be archived.
#### `archive-get` command
Get a WAL segment from the repository.
##### Example
```
/path/to/pg_backrest.pl --stanza=db archive-get %f %p
```
Retrieves a WAL segment from the repository. This command is used in `restore.conf` to restore a backup, perform PITR, or as an alternative to streaming for keeping a replica up to date. `%f` is how PostgreSQL specifies the WAL segment it needs, and `%p` is the location where it should be copied.
#### `expire` command
PgBackRest does backup rotation, but it is not concerned with when the backups were created. So if two full backups are configured in rentention, PgBackRest will keep two full backup no matter whether they occur 2 hours apart or two weeks apart.
##### Example
```
/path/to/pg_backrest.pl --stanza=db expire
```
Expire (rotate) any backups that exceed the defined retention. Expiration is run automatically after every successful backup, so there's no need to run this command on its own unless you have reduced rentention, usually to free up some space.
#### `restore` command
Perform a database restore.
PITR should start after the stop time in the .backup file.
[reference this when writing about tablespace remapping]
http://www.databasesoup.com/2013/11/moving-tablespaces.html
##### `set` option
The backup set to be restored. `latest` will restore the latest backup, otherwise provide the name of the backup to restore.
```
required: n
default: default
example: set=20150131-153358F_20150131-153401I
```
##### `delta` option
By default the PostgreSQL data and tablespace directories are expected to be present but empty. This option performs a delta restore using checksums.
```
required: n
default: n
```
##### `force` option
By itself this option forces the PostgreSQL data and tablespace paths to be completely overwritten. In combination with `--delta` a timestamp/size delta will be performed instead of using checksums.
```
required: n
default: n
```
##### `type` option
The following recovery types are supported:
- `default` - recover to the end of the archive stream.
- `name` - recover the restore point specified in `--target`.
- `xid` - recover to the transaction id specified in `--target`.
- `time` - recover to the time specified in `--target`.
- `preserve` - preserve the existing `recovery.conf` file.
- `none` - no recovery past database becoming consistent
Note that the `none` option may produce duplicate archive log (WAL) if the database is started with archive logging enabled. It is recommended that a new stanza be created for production databases restored in this way.
```
required: n
default: default
example: type=xid
```
##### `target` option
Defines the recovery target when `--type` is `name`, `xid`, or `time`.
```
required: y
example: target=--target=2015-01-30 14:15:11 EST
```
##### `target-exclusive` option
Defines whether recovery to the target whould be exclusive (the default is inclusive) and is only valid when `--type` is `time` or `xid`. For example, using `--target-exclusive` would exclude the contents of transaction `1007` when `--type=xid` and `--target=1007`. See `recovery_target_inclusive` option in the PostgreSQL docs for more information.
```
required: n
default: n
```
##### `target-resume` option
Specifies whether recovery should resume when the recovery target is reached. See `pause_at_recovery_target` in the PostgreSQL docs for more information.
```
required: n
default: n
```
##### `target-timeline` option
Recovers along the specified timeline. See `recovery_target_timeline` in the PostgreSQL docs for more information.
```
required: n
```
##### Example: Restore Latest
```
/path/to/pg_backrest.pl --stanza=db --set=latest --type=name --target=release
```
Restores the latest database backup and then recovers to the `release` restore point.
## Configuration
PgBackRest takes some command-line parameters, but depends on a configuration file for most of the settings. The default location for the configuration file is `/etc/pg_backrest.conf`.
@ -234,6 +447,15 @@ allow: 4096 - 8388608
example: buffer-size=16384
```
##### `compress` key
Enable gzip compression. Backup files are compatible with command-line gzip tools.
```
required: n
default: y
example: compress=n
```
##### `compress-level` key
Sets the zlib level to be used for file compression when `compress=y`.
@ -286,15 +508,6 @@ required: y
example: path=/var/lib/backrest
```
##### `compress` key
Enable gzip compression. Backup files are compatible with command-line gzip tools.
```
required: n
default: y
example: compress=n
```
##### `start-fast` key
Forces a checkpoint (by passing `true` to the `fast` parameter of `pg_start_backup()`) so the backup begins immediately.
@ -398,14 +611,6 @@ required: n
example: differential-retention=3
```
##### `differential-retention` key
Number of differential backups to keep. When a differential backup expires, all incremental backups associated with the differential backup will also expire. When not defined all differential backups will be kept.
```
required: n
example: differential-retention=3
```
##### `archive-retention-type` key
Type of backup to use for archive retention (full or differential). If set to full, then PgBackRest will keep archive logs for the number of full backups defined by `archive-retention`. If set to differential, then PgBackRest will keep archive logs for the number of differential backups defined by `archive-retention`.
@ -424,20 +629,6 @@ required: n
example: archive-retention=2
```
#### `restore` section
[Not much to put here, but think of something]
#### `restore-option` section
Archive Recovery and Standby Server restore.conf options can be specified here. See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on restore.conf options (replace X.X with your database version).
Note: `restore_command` will automatically be generated unless overridden in this section. Be careful about specifying your own `restore_command` as PgBackRest is designed to handle this for you.
Target Recovery options are specified on the command-line since they end to change from restore to restore (or not be needed at all in the case of a standby server).
Since PgBackRest does not start PostgreSQL after writing the `recovery.conf` file, it is always possible to edit/check the file before manually restarting.
#### `stanza` section
A stanza defines a backup for a specific database. The stanza section must define the base database path and host/user if the database is remote. Also, any global configuration sections can be overridden to define stanza-specific settings.

216
README.old.md
View File

@ -1,216 +0,0 @@
# PgBackRest Installation
## sample ubuntu 12.04 install
1. Starting from a clean install, update the OS:
```
apt-get update
apt-get upgrade (reboot if required)
```
2. Install ssh, git and cpanminus
```
apt-get install ssh
apt-get install git
apt-get install cpanminus
```
3. Install Postgres (instructions from http://www.postgresql.org/download/linux/ubuntu/)
Create the file /etc/apt/sources.list.d/pgdg.list, and add a line for the repository:
```
deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main
```
Then run the following:
```
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
apt-get install postgresql-9.3
apt-get install postgresql-server-dev-9.3
```
4. Install required Perl modules:
```
cpanm JSON
cpanm Net::OpenSSH
cpanm DBI
cpanm DBD::Pg
cpanm IPC::System::Simple
cpanm Digest::SHA
cpanm Compress::ZLib
```
5. Install PgBackRest
Backrest can be installed by downloading the most recent release:
https://github.com/pgmasters/backrest/releases
6. To run unit tests:
* Create backrest_dev user
* Setup trusted ssh between test user account and backrest_dev
* Backrest user and test user must be in the same group
## operations
PgBackRest is intended to be run from a scheduler like cron as there is no built-in scheduler.
### general options
These options are either global or used by all operations.
#### stanza
Defines the stanza for the operation. A stanza is the configuration for a database that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one Postgres cluster and therefore one stanza, whereas backup servers will have a stanza for every database that needs to be backed up.
Examples of how to configure a stanza can be found in the `configuration examples` section.
#### config
By default PgBackRest expects the its configuration file to be located at `/etc/pg_backrest.conf`. Use this option to specify another location.
#### version
Returns the PgBackRest version.
#### help
Prints help with a summary of all options.
### backup
Perform a database backup.
#### options
##### type
The following backup types are supported:
- `full` - all database files will be copied and there will be no dependencies on previous backups.
- `incr` - incremental from the last successful backup.
- `diff` - like an incremental backup but always based on the last full backup.
##### no-start-stop
This option prevents PgBackRest from running `pg_start_backup()` and `pg_stop_backup()` on the database. In order for this to work Postgres should be shut down and PgBackRest will generate an error if it is not.
The purpose of this option is to allow cold backups. The `pg_xlog` directory is copied as-is and `backup::archive-required` is automatically set to `n` for the backup.
##### force
When used with `--no-start-stop` a backup will be run even if PgBackRest thinks that Postgres is running. **This option should be used with extreme care as it will likely result in a bad backup.**
There are some scenarios where a backup might still be desirable under these conditions. For example, if a server crashes and database volume can only be mounted read-only, it would be a good idea to take a backup even if `postmaster.pid` is present. In this case it would be better to revert to the prior backup and replay WAL, but possibly there is a very important transaction in a WAL log that did not get archived.
#### usage examples
```
/path/to/pg_backrest.pl --stanza=db --type=full backup
```
Run a `full` backup on the `db` stanza. `--type` can also be set to `incr` or `diff` for incremental or differential backups. However, if no `full` backup exists then a `full` backup will be forced even if `incr` or `diff` is requested.
### archive-push
```
/path/to/pg_backrest.pl --stanza=db archive-push %p
```
Accepts an archive file from Postgres and pushes it to the backup. `%p` is how Postgres specifies the location of the file to be archived. This command has no other purpose.
### archive-get
```
/path/to/pg_backrest.pl --stanza=db archive-get %f %p
```
Retrieves an archive log from the backup. This is used in `restore.conf` to restore a backup to that last archive log, do PITR, or as an alternative to streaming for keep a replica up to date. `%f` is how Postgres specifies the archive log it needs, and `%p` is the location where it should be copied.
### expire
PgBackRest does backup rotation, but it is not concerned with when the backups were created. So if two full backups are configured in rentention, PgBackRest will keep two full backup no matter whether they occur 2 hours apart or two weeks apart.
```
/path/to/pg_backrest.pl --stanza=db expire
```
Expire (rotate) any backups that exceed the defined retention. Expiration is run automatically after every successful backup, so there's no need to run this command on its own unless you have reduced rentention, usually to free up some space.
### restore
Restore a database from the PgBackRest repository.
#### restore options
##### set
The backup set to be restored. `latest` will restore the latest backup, otherwise provide the name of the backup to restore. For example: `20150131-153358F` or `20150131-153358F_20150131-153401I`.
##### delta
By default the database base and tablespace directories are expected to be present but empty. This option performs a delta restore using checksums.
##### force
By itself this option forces the database base and tablespace paths to be completely overwritten. In combination with `--delta` a timestamp/size delta will be performed instead of using checksums.
#### recovery options
##### type
The following recovery types are supported:
- `default` - recover to the end of the archive stream.
- `name` - recover the restore point specified in `--target`.
- `xid` - recover to the transaction id specified in `--target`.
- `time` - recover to the time specified in `--target`.
- `preserve` - preserve the existing `recovery.conf` file.
- `none` - no recovery past database becoming consistent.
Note that the `none` option may produce duplicate WAL if the database is started with archive logging enabled. It is recommended that a new stanza be created for production databases restored in this way.
##### target
Defines the recovery target when `--type` is `name`, `xid`, or `time`. For example, `--type=time` and `--target=2015-01-30 14:15:11 EST`.
##### target-exclusive
Defines whether recovery to the target whould be exclusive (the default is inclusive) and is only valid when `--type` is `time` or `xid`. For example, using `--target-exclusive` would exclude the contents of transaction `1007` when `--type=xid` and `-target=1007`. See `recovery_target_inclusive` option in Postgres docs for more information.
##### target-resume
Specifies whether recovery should resume when the recovery target is reached. See `pause_at_recovery_target` in Postgres docs for more information.
##### target-timeline
Recovers along the specified timeline. See `recovery_target_timeline` in Postgres docs for more information.
#### usage examples
```
/path/to/pg_backrest.pl --stanza=db --set=latest --type=name --target=release
```
Restores the latest database backup and then recovers to the `release` restore point.
**MORE TO BE ADDED HERE**
PITR should start after the stop time in the .backup file.
[reference this when writing about tablespace remapping]
http://www.databasesoup.com/2013/11/moving-tablespaces.html
## structure
PgBackRest stores files in a way that is easy for users to work with directly. Each backup directory has one file and two subdirectories:
* `backup.manifest` file
Stores information about all the directories, links, and files in the backup. The file is plaintext and should be very clear, but documentation of the format is planned in a future release.
* `base` directory
Contains the Postgres data directory as defined by the data_directory setting in `postgresql.conf`.
* `tablespace` directory
If tablespaces are present in the database, contains each tablespace in a separate subdirectory. Tablespace names are used for the subdirectories unless --no-start-stop is specified in which case oids will be used instead. The links in `base/pg_tblspc` are rewritten to the tablespace directory in either case.

30
doc/doc.dtd
View File

@ -1,4 +1,4 @@
<!ELEMENT doc (intro, install, config, release, recognition)>
<!ELEMENT doc (intro, install, operation, config, release, recognition)>
<!ATTLIST doc title CDATA #REQUIRED>
<!ATTLIST doc subtitle CDATA #REQUIRED>
@ -12,6 +12,29 @@
<!ELEMENT install-system (text)>
<!ATTLIST install-system title CDATA #REQUIRED>
<!ELEMENT operation (text, operation-general, command-list)>
<!ATTLIST operation title CDATA #REQUIRED>
<!ELEMENT operation-general (text, option-list)>
<!ATTLIST operation-general title CDATA #REQUIRED>
<!ELEMENT command-list (text?, command+)>
<!ATTLIST command-list title CDATA #REQUIRED>
<!ELEMENT command (text, option-list?, command-example-list)>
<!ATTLIST command id CDATA #REQUIRED>
<!ELEMENT command-example-list (text?, command-example+)>
<!ATTLIST command-example-list title CDATA "Examples">
<!ELEMENT command-example (text)>
<!ATTLIST command-example title CDATA "Example">
<!ELEMENT option-list (option+)>
<!ELEMENT option (text, example?)>
<!ATTLIST option id CDATA #REQUIRED>
<!ELEMENT config (text, config-example-list, config-section-list)>
<!ATTLIST config title CDATA #REQUIRED>
@ -54,13 +77,13 @@
<!ELEMENT recognition (text)>
<!ATTLIST recognition title CDATA #REQUIRED>
<!ELEMENT text (#PCDATA|b|i|bi|ul|ol|id|code|code-block|file|path|cmd|param|setting|backrest)*>
<!ELEMENT text (#PCDATA|b|i|bi|ul|ol|id|code|code-block|file|path|cmd|param|setting|backrest|postgres)*>
<!ELEMENT i (#PCDATA)>
<!ELEMENT b (#PCDATA)>
<!ELEMENT bi (#PCDATA)>
<!ELEMENT ul (li+)>
<!ELEMENT ol (li+)>
<!ELEMENT li (#PCDATA|id)*>
<!ELEMENT li (#PCDATA|b|i|bi|ul|ol|id|code|code-block|file|path|cmd|param|setting|backrest|postgres)*>
<!ELEMENT id (#PCDATA)>
<!ELEMENT code (#PCDATA)>
<!ELEMENT code-block (#PCDATA)>
@ -70,3 +93,4 @@
<!ELEMENT param (#PCDATA)>
<!ELEMENT setting (#PCDATA)>
<!ELEMENT backrest EMPTY>
<!ELEMENT postgres EMPTY>

257
doc/doc.pl
View File

@ -17,6 +17,7 @@ use XML::Checker::Parser;
use lib dirname($0) . '/../lib';
use BackRest::Utility;
use BackRest::Config;
####################################################################################################################################
# Usage
@ -57,6 +58,7 @@ my $oRenderTag =
'code' => ['`', '`'],
'code-block' => ['```', '```'],
'backrest' => ['PgBackRest', ''],
'postgres' => ['PostgreSQL', '']
},
'html' =>
@ -404,154 +406,8 @@ if ($@)
}
####################################################################################################################################
# Parse the doc
# Build the document from xml
####################################################################################################################################
# my %oDocOut;
# Doc Build
#-----------------------------------------------------------------------------------------------------------------------------------
# $oDocOut{title} = $$oDocIn{param}{title};
# $oDocOut{subtitle} = $$oDocIn{param}{subtitle};
# $oDocOut{children} = [];
# my $strReadMe = "# ${strTitle} - ${strSubTitle}";
# Intro Build
#-----------------------------------------------------------------------------------------------------------------------------------
# my $oIntroOut = {name => 'intro'};
#
# $$oIntroOut{text} = doc_get(doc_get($oDocIn, $$oIntroOut{name}), 'text');
# push($oDocOut{children}, $oIntroOut);
# Config Build
#-----------------------------------------------------------------------------------------------------------------------------------
# my $oConfigOut = {name => 'config', children => []};
# my $oConfig = doc_get($oDocIn, $$oConfigOut{name});
#
# $$oConfigOut{title} = $$oConfig{param}{title};
# $$oConfigOut{text} = doc_get($oConfig, 'text');
# push($oDocOut{children}, $oConfigOut);
#
# # Config Example List
# my $oConfigExampleOut = {name => 'config-example-list', children => []};
# my $oConfigExampleList = doc_get($oConfig, $$oConfigExampleOut{name});
#
# $$oConfigExampleOut{title} = $$oConfigExampleList{param}{title};
# $$oConfigExampleOut{text} = doc_get($oConfigExampleList, 'text', false);
# push($$oConfigExampleOut{children}, $oConfigExampleOut);
#
# #$strReadMe .= "\n\n## " . $$oConfigExampleList{param}{title};
#
# $oDocOut{config}{exampleListText} = doc_get($oConfigExampleList, 'text', false);
# my @oExampleList;
#
# # if (doc_exists($oConfigExampleList, 'text', false))
# # {
# # $strReadMe .= "\n\n" . doc_render_text(doc_get($oConfigExampleList, 'text'), 'markdown');
# # }
#
# foreach my $oConfigExample (@{doc_list($oConfigExampleList, 'config-example')})
# {
# my %oExampleOut;
#
# $oExampleOut{title} = $$oConfigExample{param}{title};
# $oExampleOut{text} = doc_get($oConfigExample, 'text', false);
# # $strReadMe .= "\n\n### " . $$oConfigExample{param}{title} .
# # "\n\n" . doc_render_text(doc_get($oConfigExample, 'text'), 'markdown');
#
# push(@oExampleList, \%oExampleOut);
# }
#
# $oDocOut{config}{exampleList} = \@oExampleList;
# # Config Section List
# my $oConfigSectionList = doc_get($oConfig, 'config-section-list');
#
# $strReadMe .= "\n\n## " . $$oConfigSectionList{param}{title};
#
# if (doc_exists($oConfigSectionList, 'text', false))
# {
# $strReadMe .= "\n\n" . doc_render_text(doc_get($oConfigSectionList, 'text'), 'markdown');
# }
#
# foreach my $oConfigSection (@{doc_list($oConfigSectionList, 'config-section')})
# {
# my $strConfigSectionId = $$oConfigSection{param}{id};
#
# $strReadMe .= "\n\n#### `" . $strConfigSectionId . "` section" .
# "\n\n" . doc_render_text(doc_get($oConfigSection, 'text'), 'markdown');
#
# foreach my $oConfigKey (@{doc_list($oConfigSection, 'config-key', false)})
# {
# my $strConfigKeyId = $$oConfigKey{param}{id};
# my $strError = "config section ${strConfigSectionId}, key ${strConfigKeyId} requires";
#
# my $bRequired = doc_exists($oConfigKey, 'required');
# my $strDefault = !$bRequired ? doc_value(doc_get($oConfigKey, 'default', false)) : undef;
# my $strAllow = doc_value(doc_get($oConfigKey, 'allow', false));
# my $strOverride = doc_value(doc_get($oConfigKey, 'override', false));
# my $strExample = doc_value(doc_get($oConfigKey, 'example', false));
#
# defined($strExample) or die "${strError} example";
#
# $strReadMe .= "\n\n##### `" . $strConfigKeyId . "` key" .
# "\n\n" . doc_render_text(doc_get($oConfigKey, 'text'), 'markdown') .
# "\n```\n" .
# "required: " . ($bRequired ? 'y' : 'n') . "\n" .
# (defined($strDefault) ? "default: ${strDefault}\n" : '') .
# (defined($strAllow) ? "allow: ${strAllow}\n" : '') .
# (defined($strOverride) ? "override: ${strOverride}\n" : '') .
# "example: ${strConfigKeyId}=${strExample}\n" .
# "```";
# }
# }
# Release Build
#-----------------------------------------------------------------------------------------------------------------------------------
# my $oReleaseOut = {name => 'release'};
# my $oRelease = doc_get($oDocIn, 'release');
#
# $$oReleaseOut{title} = $$oRelease{param}{title};
# $$oReleaseOut{text} = doc_get($oRelease, 'text', false);
# $$oReleaseOut{children} = [];
#
# my $oReleaseList = doc_get($oRelease, 'release-list');
#
# foreach my $oReleaseVersion (@{doc_list($oReleaseList, 'release-version')})
# {
# my %oVersionOut;
# my @oFeatureList;
#
# $oVersionOut{version} = $$oReleaseVersion{param}{version};
# $oVersionOut{title} = $$oReleaseVersion{param}{title};
# $oVersionOut{text} = doc_get($oReleaseVersion, 'text', false);
# $oVersionOut{list} = true;
# $oVersionOut{children} = [];
#
# foreach my $oReleaseFeature (@{doc_list($oReleaseVersion, 'release-feature')})
# {
# my %oFeatureOut;
# $oFeatureOut{text} = doc_get($oReleaseFeature, 'text');
# push ($oVersionOut{children}, \%oFeatureOut);
# }
#
# push($$oReleaseOut{children}, \%oVersionOut);
# }
#
# push($oDocOut{children}, $oReleaseOut);
# Recognition Build
#-----------------------------------------------------------------------------------------------------------------------------------
# my $oRecognitionOut = {name => 'recognition'};
# my $oRecognition = doc_get($oDocIn, $$oRecognitionOut{name});
#
# $$oRecognitionOut{title} = $$oRecognition{param}{title};
# $$oRecognitionOut{text} = doc_get($oRecognition, 'text');
# push($oDocOut{children}, $oRecognitionOut);
# Build
#-----------------------------------------------------------------------------------------------------------------------------------
my $oDocIn = doc_parse(${$oTree}[0], ${$oTree}[1]);
sub doc_build
@ -602,8 +458,101 @@ sub doc_build
my $oDocOut = doc_build($oDocIn);
# Render
#-----------------------------------------------------------------------------------------------------------------------------------
####################################################################################################################################
# Build commands pulled from the code
####################################################################################################################################
sub doc_out_get
{
my $oNode = shift;
my $strName = shift;
my $bRequired = shift;
foreach my $oChild (@{$$oNode{children}})
{
if ($$oChild{name} eq $strName)
{
return $oChild;
}
}
if (!defined($bRequired) || $bRequired)
{
confess "unable to find child node '${strName}' in node '$$oNode{name}'";
}
return undef;
}
# Get the option rules
my $oOptionRule = optionRuleGet();
# Ouput commands
my $oCommandListOut = doc_out_get(doc_out_get($oDocOut, 'operation'), 'command-list');
foreach my $oCommandOut (@{$$oCommandListOut{children}})
{
my $strOperation = $$oCommandOut{param}{id};
my $oOptionListOut = doc_out_get($oCommandOut, 'option-list', false);
if (defined($oOptionListOut))
{
foreach my $oOptionOut (@{$$oOptionListOut{children}})
{
my $strOption = $$oOptionOut{param}{id};
$$oOptionOut{field}{default} = optionDefault($strOption, $strOperation);
if (defined($$oOptionOut{field}{default}))
{
$$oOptionOut{field}{required} = false;
if ($$oOptionRule{$strOption}{&OPTION_RULE_TYPE} eq &OPTION_TYPE_BOOLEAN)
{
$$oOptionOut{field}{default} = $$oOptionOut{field}{default} ? 'y' : 'n';
}
}
else
{
$$oOptionOut{field}{required} = optionRequired($strOption, $strOperation);
}
&log(INFO, "operation ${strOperation}, option ${strOption}, required $$oOptionOut{field}{required}" .
", default " . (defined($$oOptionOut{field}{default}) ? $$oOptionOut{field}{default} : 'undef'));
}
}
my $oExampleListOut = doc_out_get($oCommandOut, 'command-example-list');
foreach my $oExampleOut (@{$$oExampleListOut{children}})
{
if (defined($$oExampleOut{param}{title}))
{
$$oExampleOut{param}{title} = 'Example: ' . $$oExampleOut{param}{title};
}
else
{
$$oExampleOut{param}{title} = 'Example';
}
}
# $$oExampleListOut{param}{title} = 'Examples';
}
my $oSectionListOut = doc_out_get(doc_out_get($oDocOut, 'config'), 'config-section-list');
foreach my $oSectionOut (@{$$oSectionListOut{children}})
{
my $oOptionListOut = doc_out_get($oSectionOut, 'config-key-list');
foreach my $oOptionOut (@{$$oOptionListOut{children}})
{
}
}
####################################################################################################################################
# Render the document
####################################################################################################################################
sub doc_render
{
my $oDoc = shift;
@ -668,24 +617,24 @@ sub doc_render
$strBuffer .= doc_render_text($$oDoc{field}{text}, $strType);
}
if ($$oDoc{name} eq 'config-key')
if ($$oDoc{name} eq 'config-key' || $$oDoc{name} eq 'option')
{
my $strError = "config section ?, key $$oDoc{param}{id} requires";
my $bRequired = defined($$oDoc{field}{required});
my $strDefault = !$bRequired ? $$oDoc{field}{default} : undef;
my $bRequired = defined($$oDoc{field}{required}) && $$oDoc{field}{required};
my $strDefault = $$oDoc{field}{default};
my $strAllow = $$oDoc{field}{allow};
my $strOverride = $$oDoc{field}{override};
my $strExample = $$oDoc{field}{example};
defined($strExample) or die "${strError} example";
# defined($strExample) or die "${strError} example";
$strBuffer .= "\n```\n" .
"required: " . ($bRequired ? 'y' : 'n') . "\n" .
(defined($strDefault) ? "default: ${strDefault}\n" : '') .
(defined($strAllow) ? "allow: ${strAllow}\n" : '') .
(defined($strOverride) ? "override: ${strOverride}\n" : '') .
"example: $$oDoc{param}{id}=${strExample}\n" .
(defined($strExample) ? "example: $$oDoc{param}{id}=${strExample}\n" : '') .
"```";
}

226
doc/doc.xml
View File

@ -80,6 +80,201 @@
</install-system-list>
</install>
<operation title="Operations">
<text><backrest/> is intended to be run from a scheduler like cron as there is no built-in scheduler.</text>
<operation-general title="General Options">
<text>These options are either global or used by all operations.</text>
<option-list>
<!-- OPERATION - GENERAL - CONFIG OPTION -->
<option id="type">
<text>By default PgBackRest expects the its configuration file to be located at `/etc/pg_backrest.conf`. Use this option to specify another location.</text>
<example>/path/to/backrest/pg_backrest.conf</example>
</option>
<!-- OPERATION - GENERAL - STANZA OPTION -->
<option id="stanza">
<text>Defines the stanza for the operation. A stanza is the configuration for a database that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one Postgres cluster and therefore one stanza, whereas backup servers will have a stanza for every database that needs to be backed up.
Examples of how to configure a stanza can be found in the `configuration examples` section.</text>
<example>main</example>
</option>
<!-- OPERATION - GENERAL - HELP OPTION -->
<option id="help">
<text>Displays the <backrest/> help.</text>
</option>
<!-- OPERATION - GENERAL - VERSION OPTION -->
<option id="version">
<text>Displays the <backrest/> version.</text>
</option>
</option-list>
</operation-general>
<command-list title="Commands">
<text>Sample text for the commands, which I'm sure will be very, very interesting.</text>
<!-- OPERATION - BACKUP COMMAND -->
<command id="backup">
<text>Perform a database backup.</text>
<option-list>
<!-- OPERATION - BACKUP COMMAND - TYPE OPTION -->
<option id="type">
<text>The following backup types are supported:
<ul>
<li><id>full</id> - all database files will be copied and there will be no dependencies on previous backups.</li>
<li><id>incr</id> - incremental from the last successful backup.</li>
<li><id>warn</id> - like an incremental backup but always based on the last full backup.</li>
</ul></text>
<example>full</example>
</option>
<!-- OPERATION - BACKUP COMMAND - NO-START-STOP OPTION -->
<option id="no-start-stop">
<text>This option prevents <backrest/> from running <code>pg_start_backup()</code> and <code>pg_stop_backup()</code> on the database. 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 cold backups. The <path>pg_xlog</path> directory is copied as-is and <setting>archive-required</setting> is automatically disabled for the backup.</text>
</option>
<!-- OPERATION - BACKUP COMMAND - FORCE OPTION -->
<option id="force">
<text>When used with <param>--no-start-stop</param> a backup will be run even if <backrest/> thinks that Postgres is running. <b>This option should be used with extreme care as it will likely result in a bad backup.</b>
There are some scenarios where a backup might still be desirable under these conditions. For example, if a server crashes and database volume can only be mounted read-only, it would be a good idea to take a backup even if <file>postmaster.pid</file> is present. In this case it would be better to revert to the prior backup and replay WAL, but possibly there is a very important transaction in a WAL log that did not get archived.</text>
</option>
</option-list>
<command-example-list>
<command-example title="Full Backup">
<text><code-block>
/path/to/pg_backrest.pl --stanza=db --type=full backup
</code-block>
Run a <id>full</id> backup on the <id>db</id> stanza. <param>--type</param> can also be set to <id>incr</id> or <id>diff</id> for incremental or differential backups. However, if no <id>full</id> backup exists then a <id>full</id> backup will be forced even if <id>incr</id> or <id>diff</id> is requested.</text>
</command-example>
</command-example-list>
</command>
<!-- OPERATION - ARCHIVE-PUSH COMMAND -->
<command id="archive-push">
<text>Archive a WAL segment to the repository.</text>
<command-example-list>
<command-example>
<text><code-block>
/path/to/pg_backrest.pl --stanza=db archive-push %p
</code-block>
Accepts a WAL segment from <postgres/> and archives it in the repository. <param>%p</param> is how <postgres/> specifies the location of the WAL segment to be archived.</text>
</command-example>
</command-example-list>
</command>
<!-- OPERATION - ARCHIVE-GET COMMAND -->
<command id="archive-get">
<text>Get a WAL segment from the repository.</text>
<command-example-list>
<command-example>
<text><code-block>
/path/to/pg_backrest.pl --stanza=db archive-get %f %p
</code-block>
Retrieves a WAL segment from the repository. This command is used in <file>restore.conf</file> to restore a backup, perform PITR, or as an alternative to streaming for keeping a replica up to date. <param>%f</param> is how <postgres/> specifies the WAL segment it needs, and <param>%p</param> is the location where it should be copied.</text>
</command-example>
</command-example-list>
</command>
<!-- OPERATION - EXPIRE COMMAND -->
<command id="expire">
<text><backrest/> does backup rotation, but it is not concerned with when the backups were created. So if two full backups are configured in rentention, <backrest/> will keep two full backup no matter whether they occur 2 hours apart or two weeks apart.</text>
<command-example-list>
<command-example>
<text><code-block>
/path/to/pg_backrest.pl --stanza=db expire
</code-block>
Expire (rotate) any backups that exceed the defined retention. Expiration is run automatically after every successful backup, so there's no need to run this command on its own unless you have reduced rentention, usually to free up some space.</text>
</command-example>
</command-example-list>
</command>
<!-- OPERATION - RESTORE COMMAND -->
<command id="restore">
<text>Perform a database restore.
PITR should start after the stop time in the .backup file.
[reference this when writing about tablespace remapping]
http://www.databasesoup.com/2013/11/moving-tablespaces.html</text>
<option-list>
<!-- OPERATION - RESTORE COMMAND - SET OPTION -->
<option id="set">
<text>The backup set to be restored. <id>latest</id> will restore the latest backup, otherwise provide the name of the backup to restore.</text>
<example>20150131-153358F_20150131-153401I</example>
</option>
<!-- OPERATION - RESTORE COMMAND - DELTA OPTION -->
<option id="delta">
<text>By default the <postgres/> data and tablespace directories are expected to be present but empty. This option performs a delta restore using checksums.</text>
</option>
<!-- OPERATION - RESTORE COMMAND - FORCE OPTION -->
<option id="force">
<text>By itself this option forces the <postgres/> data and tablespace paths to be completely overwritten. In combination with <param>--delta</param> a timestamp/size delta will be performed instead of using checksums.</text>
</option>
<!-- OPERATION - RESTORE COMMAND - TYPE OPTION -->
<option id="type">
<text>The following recovery types are supported:
<ul>
<li><id>default</id> - recover to the end of the archive stream.</li>
<li><id>name</id> - recover the restore point specified in <param>--target</param>.</li>
<li><id>xid</id> - recover to the transaction id specified in <param>--target</param>.</li>
<li><id>time</id> - recover to the time specified in <param>--target</param>.</li>
<li><id>preserve</id> - preserve the existing <file>recovery.conf</file> file.</li>
<li><id>none</id> - no recovery past database becoming consistent</li>
</ul>
Note that the <id>none</id> option may produce duplicate archive log (WAL) if the database is started with archive logging enabled. It is recommended that a new stanza be created for production databases restored in this way.</text>
<example>xid</example>
</option>
<!-- OPERATION - RESTORE COMMAND - TARGET OPTION -->
<option id="target">
<text>Defines the recovery target when <param>--type</param> is <id>name</id>, <id>xid</id>, or <id>time</id>.</text>
<example>--target=2015-01-30 14:15:11 EST</example>
</option>
<!-- OPERATION - RESTORE COMMAND - TARGET-EXCLUSIVE OPTION -->
<option id="target-exclusive">
<text>Defines whether recovery to the target whould be exclusive (the default is inclusive) and is only valid when <param>--type</param> is <id>time</id> or <id>xid</id>. For example, using <param>--target-exclusive</param> would exclude the contents of transaction <id>1007</id> when <param>--type=xid</param> and <param>--target=1007</param>. See <param>recovery_target_inclusive</param> option in the <postgres/> docs for more information.</text>
</option>
<!-- OPERATION - RESTORE COMMAND - TARGET-RESUME OPTION -->
<option id="target-resume">
<text>Specifies whether recovery should resume when the recovery target is reached. See <setting>pause_at_recovery_target</setting> in the <postgres/> docs for more information.</text>
</option>
<!-- OPERATION - RESTORE COMMAND - TARGET-TIMELINE OPTION -->
<option id="target-timeline">
<text>Recovers along the specified timeline. See <setting>recovery_target_timeline</setting> in the <postgres/> docs for more information.</text>
</option>
</option-list>
<command-example-list>
<command-example title="Restore Latest">
<text>
<code-block>
/path/to/pg_backrest.pl --stanza=db --set=latest --type=name --target=release
</code-block>
Restores the latest database backup and then recovers to the <id>release</id> restore point.</text>
</command-example>
</command-example-list>
</command>
</command-list>
</operation>
<config title="Configuration">
<text><backrest/> takes some command-line parameters, but depends on a configuration file for most of the settings. The default location for the configuration file is <file>/etc/pg_backrest.conf</file>.</text>
@ -239,6 +434,14 @@
<example>16384</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - COMPRESS -->
<config-key id="compress">
<text>Enable gzip compression. Backup files are compatible with command-line gzip tools.</text>
<default>y</default>
<example>n</example>
</config-key>
<!-- CONFIG - GENERAL SECTION - COMPRESS-LEVEL KEY -->
<config-key id="compress-level">
<text>Sets the zlib level to be used for file compression when <setting>compress=y</setting>.</text>
@ -290,14 +493,6 @@
<example>/var/lib/backrest</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - COMPRESS -->
<config-key id="compress">
<text>Enable gzip compression. Backup files are compatible with command-line gzip tools.</text>
<default>y</default>
<example>n</example>
</config-key>
<!-- CONFIG - BACKUP SECTION - START-FAST -->
<config-key id="start-fast">
<text>Forces a checkpoint (by passing <id>true</id> to the <id>fast</id> parameter of <code>pg_start_backup()</code>) so the backup begins immediately.</text>
@ -397,13 +592,6 @@
<example>3</example>
</config-key>
<!-- CONFIG - RETENTION SECTION - DIFFERENTIAL-RETENTION KEY -->
<config-key id="differential-retention">
<text>Number of differential backups to keep. When a differential backup expires, all incremental backups associated with the differential backup will also expire. When not defined all differential backups will be kept.</text>
<example>3</example>
</config-key>
<!-- CONFIG - RETENTION SECTION - ARCHIVE-RETENTION-TYPE KEY -->
<config-key id="archive-retention-type">
<text>Type of backup to use for archive retention (full or differential). If set to full, then PgBackRest will keep archive logs for the number of full backups defined by <setting>archive-retention</setting>. If set to differential, then PgBackRest will keep archive logs for the number of differential backups defined by <setting>archive-retention</setting>.
@ -423,12 +611,12 @@
</config-section>
<!-- CONFIG - RESTORE -->
<config-section id="restore">
<!-- <config-section id="restore">
<text>[Not much to put here, but think of something]</text>
</config-section>
</config-section> -->
<!-- CONFIG - RESTORE-OPTION -->
<config-section id="restore-option">
<!-- <config-section id="restore-option">
<text>Archive Recovery and Standby Server restore.conf options can be specified here. See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on restore.conf options (replace X.X with your database version).
Note: <setting>restore_command</setting> will automatically be generated unless overridden in this section. Be careful about specifying your own <setting>restore_command</setting> as PgBackRest is designed to handle this for you.
@ -436,7 +624,7 @@ Note: <setting>restore_command</setting> will automatically be generated unless
Target Recovery options are specified on the command-line since they end to change from restore to restore (or not be needed at all in the case of a standby server).
Since <backrest/> does not start PostgreSQL after writing the <file>recovery.conf</file> file, it is always possible to edit/check the file before manually restarting.</text>
</config-section>
</config-section>-->
<!-- CONFIG - STANZA -->
<config-section id="stanza">

133
lib/BackRest/Config.pm
View File

@ -18,14 +18,14 @@ use BackRest::Utility;
####################################################################################################################################
# Export functions
####################################################################################################################################
our @EXPORT = qw(configLoad optionGet optionTest optionRuleGet operationGet operationTest operationSet);
our @EXPORT = qw(configLoad optionGet optionTest optionRuleGet optionRequired optionDefault operationGet operationTest
operationSet);
####################################################################################################################################
# Operation constants - basic operations that are allowed in backrest
####################################################################################################################################
use constant
{
OP_ARCHIVE => 'archive',
OP_ARCHIVE_GET => 'archive-get',
OP_ARCHIVE_PUSH => 'archive-push',
OP_BACKUP => 'backup',
@ -483,7 +483,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_COMMAND,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_BACKUP => true,
&OP_RESTORE => true
}
@ -522,7 +523,7 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_ARCHIVE,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true
&OP_ARCHIVE_PUSH => true
}
},
@ -559,7 +560,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_BACKUP,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_RESTORE => true
},
},
@ -570,7 +572,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_BACKUP,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_RESTORE => true
},
&OPTION_RULE_REQUIRED => false,
@ -587,7 +590,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_GENERAL,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_BACKUP => true,
&OP_RESTORE => true
},
@ -600,7 +604,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_GENERAL,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_RESTORE => true
},
},
@ -611,11 +616,15 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_STANZA,
&OPTION_RULE_OPERATION =>
{
&OP_BACKUP => true,
&OP_ARCHIVE =>
&OP_ARCHIVE_GET =>
{
&OPTION_RULE_REQUIRED => false
}
},
&OP_ARCHIVE_PUSH =>
{
&OPTION_RULE_REQUIRED => false
},
&OP_BACKUP => true
},
},
@ -635,7 +644,7 @@ my %oOptionRule =
&OPTION_RULE_SECTION => CONFIG_SECTION_ARCHIVE,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true
&OP_ARCHIVE_PUSH => true
}
},
@ -658,7 +667,8 @@ my %oOptionRule =
&OPTION_RULE_SECTION_INHERIT => CONFIG_SECTION_GENERAL,
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_BACKUP => true,
&OP_RESTORE => true
}
@ -673,7 +683,8 @@ my %oOptionRule =
&OPTION_RULE_ALLOW_RANGE => [OPTION_DEFAULT_COMPRESS_LEVEL_MIN, OPTION_DEFAULT_COMPRESS_LEVEL_MAX],
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_BACKUP => true,
&OP_RESTORE => true
}
@ -688,7 +699,8 @@ my %oOptionRule =
&OPTION_RULE_ALLOW_RANGE => [OPTION_DEFAULT_COMPRESS_LEVEL_NETWORK_MIN, OPTION_DEFAULT_COMPRESS_LEVEL_NETWORK_MAX],
&OPTION_RULE_OPERATION =>
{
&OP_ARCHIVE => true,
&OP_ARCHIVE_GET => true,
&OP_ARCHIVE_PUSH => true,
&OP_BACKUP => true,
&OP_RESTORE => true
}
@ -1170,10 +1182,7 @@ sub optionValid
}
# If the operation has rules store them for later evaluation
my $oOperationRule = defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}) &&
defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperationSection}) &&
ref($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperationSection}) eq 'HASH' ?
$oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperationSection} : undef;
my $oOperationRule = optionOperationRule($strOption, $strOperation);
# Check dependency for the operation then for the option
my $bDependResolved = true;
@ -1324,34 +1333,24 @@ sub optionValid
$oOption{$strOption} = $strValue;
}
}
# Else set the default if required
elsif (!defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}) ||
defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperationSection}))
# Else try to set a default
elsif ($bDependResolved &&
(!defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}) ||
defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperation})))
{
# Check for default in operation then option
my $strDefault = defined($oOperationRule) ? $$oOperationRule{&OPTION_RULE_DEFAULT} :
$oOptionRule{$strOption}{&OPTION_RULE_DEFAULT};
my $strDefault = optionDefault($strOption, $strOperation);
# If default is defined
if (defined($strDefault))
{
# Only set default if dependency is resolved
$oOption{$strOption} = $strDefault if $bDependResolved && !$bNegate;
$oOption{$strOption} = $strDefault if !$bNegate;
}
# Else error
else
# Else check required
elsif (optionRequired($strOption, $strOperation))
{
# Check for required in operation then option
my $bRequired = defined($oOperationRule) ? $$oOperationRule{&OPTION_RULE_REQUIRED} :
$oOptionRule{$strOption}{&OPTION_RULE_REQUIRED};
if (!defined($bRequired) || $bRequired)
{
if ($bDependResolved)
{
confess &log(ERROR, "${strOperation} operation requires option: ${strOption}", ERROR_OPTION_REQUIRED);
}
}
confess &log(ERROR, "${strOperation} operation requires option: ${strOption}", ERROR_OPTION_REQUIRED);
}
}
@ -1360,6 +1359,64 @@ sub optionValid
}
}
####################################################################################################################################
# optionOperationRule
#
# Returns the option rules based on the operation.
####################################################################################################################################
sub optionOperationRule
{
my $strOption = shift;
my $strOperation = shift;
return defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}) &&
defined($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperation}) &&
ref($oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperation}) eq 'HASH' ?
$oOptionRule{$strOption}{&OPTION_RULE_OPERATION}{$strOperation} : undef;
}
####################################################################################################################################
# optionRequired
#
# Is the option required for this operation?
####################################################################################################################################
sub optionRequired
{
my $strOption = shift;
my $strOperation = shift;
# Get the operation rule
my $oOperationRule = optionOperationRule($strOption, $strOperation);
# Check for required in operation then option
my $bRequired = defined($oOperationRule) ? $$oOperationRule{&OPTION_RULE_REQUIRED} :
$oOptionRule{$strOption}{&OPTION_RULE_REQUIRED};
# Return required
return !defined($bRequired) || $bRequired;
}
####################################################################################################################################
# optionDefault
#
# Does the option have a default for this operation?
####################################################################################################################################
sub optionDefault
{
my $strOption = shift;
my $strOperation = shift;
# Get the operation rule
my $oOperationRule = optionOperationRule($strOption, $strOperation);
# Check for default in operation
my $strDefault = defined($oOperationRule) ? $$oOperationRule{&OPTION_RULE_DEFAULT} : undef;
# If defined return, else try to grab the global default
return defined($strDefault) ? $strDefault : $oOptionRule{$strOption}{&OPTION_RULE_DEFAULT};
}
####################################################################################################################################
# operationGet
#