Application API/Operations: Difference between revisions
(merge in calling conventions) |
(Update information based on experience) |
||
Line 7: | Line 7: | ||
Properties that are specified in the Amanda configuration are provided to the application as additional command-line options, e.g., | Properties that are specified in the Amanda configuration are provided to the application as additional command-line options, e.g., | ||
/path/to/my/app backup .... -- | /path/to/my/app backup .... --frobnication-engine ON | ||
If a property has several values, it will appear repeatedly on the command line: | If a property has several values, it will appear repeatedly on the command line: | ||
/path/to/my/app index .... -- | /path/to/my/app index .... --search-path /foo --search-path /bar | ||
{{XXX|Martineau| | Note that all property names will be folded to lowercase. Property values will be in the same case they were in the configuration file. | ||
{{XXX|Martineau|Dashes vs. underscores?}} | |||
Information about what to be backed up is specified by <code>--device</code>, <code>--include-file</code>, <code>--include-list</code>, <code>--exclude-file</code>, and <code>--exclude-list</code>. <code>--level</code> is used to support incremental backups. <code>--level 0</code> signifies a base/full backup. <code>--level 1</code> builds on level 0, 2 builds on 1, and so on. | |||
= subcommands = | = subcommands = | ||
Line 37: | Line 40: | ||
RECOVER-MODE SMB | RECOVER-MODE SMB | ||
This command informs Amanda about the capabilities of this application. Try to provide as much information as possible so Amanda doesn't have to make as many assumptions. | |||
== '''backup''' command == | == '''backup''' command == | ||
Line 44: | Line 47: | ||
data stream | data stream | ||
;output on fd3: (if no '''--message''' or '''--message line''') | ;output on fd3: (if no '''--message''' or '''--message line''') | ||
error message | | normal/informative message | ||
'''HEADER''' ''variable'''''='''''value'', information that should go in the amanda header. | ? error/strange message | ||
'''SIZE''' ''value suffix'' where ''suffix'' could be '''K''', (kilobytes) '''M''', (megabytes) or '''G''' (gigabytes) | & unknown/unrecognized message | ||
sendbackup: '''HEADER''' ''variable'''''='''''value'', information that should go in the amanda header. | |||
sendbackup: '''SIZE''' ''value suffix'' where ''suffix'' could be '''K''', (kilobytes) '''M''', (megabytes) or '''G''' (gigabytes) | |||
sendbackup: END | |||
;output on fd3: (if '''--message xml''') | ;output on fd3: (if '''--message xml''') | ||
format not yet defined | format not yet defined | ||
Line 54: | Line 60: | ||
xml index stream (format not yet defined) | xml index stream (format not yet defined) | ||
{{XXX|Martineau|Is header implemented? How does restore get this information}} | |||
Input: | Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc. | ||
Action: | Action: Creates a backup (of --level) of the specified object. | ||
Output: A set of collections (containing the backup data), and information on a set of user objects (identifier, attributes, associated collections) | Output: A set of collections (containing the backup data), and information on a set of user objects (identifier, attributes, associated collections) {{XXX|Martineau|Are collections facilitated by multiple size lines?}} | ||
== '''restore''' command == | == '''restore''' command == | ||
Line 95: | Line 101: | ||
Output: Byte offsets for each collection in the stream, and information on the set of user objects in the stream. | Output: Byte offsets for each collection in the stream, and information on the set of user objects in the stream. | ||
{{XXX|Martineau|Is this implemented?}} | |||
== '''estimate''' command == | == '''estimate''' command == | ||
Line 100: | Line 108: | ||
output on fd1: (if no '''--message''' or '''--message line''') | output on fd1: (if no '''--message''' or '''--message line''') | ||
error message that should be logged. | error message that should be logged. | ||
''' | '''level''' ''size''''suffix'' 1 where suffix could be K, M, G | ||
output on fd1: (if '''--message xml''') | output on fd1: (if '''--message xml''') | ||
format not yet defined | format not yet defined | ||
{{XXX|Martineau|can 1 be something else?}} | |||
Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc. | Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc. | ||
Line 120: | Line 129: | ||
Action: Determines if there are any configuration problems. | Action: Determines if there are any configuration problems. | ||
Output: Success or failure | Output: Success or failure messages | ||
== Print-Command == | == Print-Command == | ||
Line 126: | Line 135: | ||
Output: Prints a one-line command, if one exists, to restore this data from tape. This can be used for non-Amanda bare-metal disaster recovery. | Output: Prints a one-line command, if one exists, to restore this data from tape. This can be used for non-Amanda bare-metal disaster recovery. | ||
{{XXX|Martineau|Is this implemented?}} |
Revision as of 18:49, 3 February 2009
The Application API changes the backup server interface, but most of the code that constitutes the API itself resides on the client. The operations listed below are from the perspective of backup clients.
conventions
Commands are invoked with a single argument, the subcommand, and a number of additional options. So, for example, a simple support invocation might look like
/path/to/my/app support --config DailySet1
Properties that are specified in the Amanda configuration are provided to the application as additional command-line options, e.g.,
/path/to/my/app backup .... --frobnication-engine ON
If a property has several values, it will appear repeatedly on the command line:
/path/to/my/app index .... --search-path /foo --search-path /bar
Note that all property names will be folded to lowercase. Property values will be in the same case they were in the configuration file.
XXX | User:Martineau: Dashes vs. underscores? |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}
Information about what to be backed up is specified by --device
, --include-file
, --include-list
, --exclude-file
, and --exclude-list
. --level
is used to support incremental backups. --level 0
signifies a base/full backup. --level 1
builds on level 0, 2 builds on 1, and so on.
subcommands
support command
support [--config config] [--host host] [--disk disk] [--device device] [--PROPERTY_NAME PROPERTY_VALUE]*
- 0utput on fd1
CONFIG YES|NO HOST YES|NO DISK YES|NO MAX-LEVEL level INDEX-LINE YES|NO INDEX-XML YES|NO MESSAGE-LINE YES|NO MESSAGE-XML YES|NO RECORD YES|NO INCLUDE YES|NO INCLUDE-LIST YES|NO INCLUDE-OPTIONAL YES|NO EXCLUDE YES|NO EXCLUDE-LIST YES|NO EXCLUDE-OPTIONAL YES|NO COLLECTION YES|NO CALCSIZE YES|NO MULTI-ESTIMATE YES|NO RECOVER-MODE SMB
This command informs Amanda about the capabilities of this application. Try to provide as much information as possible so Amanda doesn't have to make as many assumptions.
backup command
backup [--message (line|xml)] [--index (line|xml)] [--config config] [--host host] [--disk disk] --device amdevice --level level [--record] [--PROPERTY_NAME PROPERTY_VALUE]*
- output on fd1
data stream
- output on fd3
- (if no --message or --message line)
| normal/informative message ? error/strange message & unknown/unrecognized message sendbackup: HEADER variable=value, information that should go in the amanda header. sendbackup: SIZE value suffix where suffix could be K, (kilobytes) M, (megabytes) or G (gigabytes) sendbackup: END
- output on fd3
- (if --message xml)
format not yet defined
- output on fd4
- (if --index line)
index stream (One filename by line)
- output on fd4
- (if --index xml)
xml index stream (format not yet defined)
XXX | User:Martineau: Is header implemented? How does restore get this information |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}
Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc.
Action: Creates a backup (of --level) of the specified object.
Output: A set of collections (containing the backup data), and information on a set of user objects (identifier, attributes, associated collections)
XXX | User:Martineau: Are collections facilitated by multiple size lines? |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}
restore command
restore [--message (line|xml)] [--index (line|xml)] [--config config] [--host host] [--disk disk] --device amdevice --level level [--PROPERTY_NAME PROPERTY_VALUE]* [./file-to-restore]+
- Input on fd0
data stream
- Output on fd1
- (if no --message or --message line)
error message
- 0utput on fd1
- (if --message xml)
format not yet defined
Input: List of user objects to be restored, relevant collections, and target locations for the restore.
Action: Reads the collections and writes the relevant user objects in their original form to the specified location.
Output: None (other than administrative messages)
index command
index [--message (line|xml)] [--index (line|xml)] [--config config] [--host host] [--disk disk] --device amdevice --level level [--PROPERTY_NAME PROPERTY_VALUE]*
input fd1: data stream output on fd3: (if no --message or --message line) error message output on fd3: (if --message xml) format not yet defined output on fd4: (if --index line) index stream (One filename by line) output on fd4: (if --index xml) xml index stream
Input: Octet stream of all the collections from a single job.
Action: regenerate index data from the datastream
Output: Byte offsets for each collection in the stream, and information on the set of user objects in the stream.
XXX | User:Martineau: Is this implemented? |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}
estimate command
estimate [--message [line|xml]] [--config config] [--host host] [--disk disk] --device amdevice --level level [--PROPERTY_NAME PROPERTY_VALUE]*
output on fd1: (if no --message or --message line) error message that should be logged. level size'suffix 1 where suffix could be K, M, G output on fd1: (if --message xml) format not yet defined
XXX | User:Martineau: can 1 be something else? |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}
Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc.
Output: An estimate of how much space this data set will consume.
selfcheck command
selfcheck [--message (line|xml)] [--config config] [--host host] [--disk disk] --device device --level level [--record] [--PROPERTY_NAME PROPERTY_VALUE]*
- Output on fd1
- (if no --message or --message line) (Could be many lines)
OK [message] ERROR [message]
- 0utput on fd1
- (if --message xml)
format not yet defined
Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc.
Action: Determines if there are any configuration problems.
Output: Success or failure messages
Print-Command
Input: Information on what is to be backed up: A filesystem, device, particular set of files, database table, etc.
Output: Prints a one-line command, if one exists, to restore this data from tape. This can be used for non-Amanda bare-metal disaster recovery.
XXX | User:Martineau: Is this implemented? |
Other languages: [[::Application API/Operations|English]] {{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Fr | • {{#if: |français| [[::Application API/Operations/Fr|français]]}}|}}
{{#ifexist: {{#if: | | {{#if: | :}}Application API/Operations}}/Zh-cn | • {{#if: |中文(中国大陆)| [[::Application API/Operations/Zh-cn|中文(中国大陆)]]}}|}}