Application API/Operations
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 and have underscores converted to dashes. Property values will be in the same case they were in the configuration file, but will be escaped (e.g. the tab character replaced with \t
, and so on, with \
being represented by \\
)
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.
Lines are terminated by the UNIX newline character ("\n", hex: 0xa)
Unimplemented
- print command
- index command
- XML message and index formats
- HEADER from backup command
- Collections
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 CLIENT-ESTIMATE YES|NO MULTI-ESTIMATE YES|NO RECOVER-MODE SMB RECOVER-PATH CWD|REMOTE DATA-PATH AMANDA|DIRECTTCP AMFEATURES YES|NO RECOVER-DUMP-STATE-FILE YES|NO DAR YES|NO STATE-STREAM YES|NO
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.
Most parameters should use either YES
or NO
for their values. Names and values must be separated by exactly one space.
Parameter | Default | Description |
---|---|---|
CONFIG | YES | Is the --config option supported?
|
HOST | YES | Is the --host option supported? See also: disklist(5)
|
DISK | YES | Is the --disk option supported? See also: disklist(5)
|
MAX-LEVEL | 0 | An integer. The maximum "depth" of incremental backups. This can not be greater than 99. |
INDEX-LINE | NO | Is line-based indexing (--index line ) supported?
|
INDEX-XML | NO | Is XML indexing (--index xml ) supported?
|
MESSAGE-LINE | NO | Is line-based message output (--message line ) supported?
|
MESSAGE-XML | NO | Is XML message output (--message xml ) supported?
|
RECORD | NO | Is the --record option supported?
|
INCLUDE-FILE | NO | Is the --include-file property supported? See also: include in amanda.conf(5)
|
INCLUDE-LIST | NO | Is the --include-list property supported? See also: include in amanda.conf(5)
|
INCLUDE-OPTIONAL | NO | Is it okay if objects referred to by include-file and include-list do not exist? See also: include optional in amanda.conf(5)
|
EXCLUDE-FILE | NO | Is the exclude-file property supported? See also: exclude in amanda.conf(5)
|
EXCLUDE-LIST | NO | Is the exclude-list property supported? See also: exclude in amanda.conf(5)
|
EXCLUDE-OPTIONAL | NO | Is it okay if objects referred to by exclude-file and exclude-list do not exist? See also: exclude optional in amanda.conf(5)
|
COLLECTION | NO | |
CALCSIZE | NO | Does the estimate command support the --calcsize option?
|
CLIENT-ESTIMATE | NO | Does the estimate command support estimate without --calcsize (client estimate)?
|
MULTI-ESTIMATE | NO | Does the estimate command support multiple --level s?
|
RECOVER-MODE | If set to SMB , sambaclient will be used during recovery
| |
RECOVER-PATH | CWD | The default restore is done on the current working directory, set it to REMOTE if it is on a remote host.
|
DATA-PATH | AMANDA | The data path supported, can have multiple line with different value. |
AMFEATURES | NO | If the application accept the amfeatures set of the server in the --amfeatures argument.
|
RECOVER-DUMP-STATE-FILE | NO | If the application accept the --recover-dump-state-file on restore command.
|
DAR | NO | If the application output DAR directives on restore command. see Application_API/DAR |
STATE-STREAM | NO | If the application output a DAR state file on backup. see Application_API/DAR |
Note: Despite the supported and advertised options set the plugin
has to accept the --config …
, --host …
, and
--disk …
options for all subcommands. But it may ignore
unsupported options. (This is considered a bug, but it's not fixed yet
(3.3.5).)
backup command
backup [--message (line|xml)] [--index (line|xml)] [--config config] [--host host] [--disk disk] --device amdevice --level level [--record] [--state-stream state_fd] [--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, the default) 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 per line similar to the output of tar -t) each name must start with a '/' and must be relative to the device. A directory must also terminate with a '/'. the simplest entry is just one '/'.
- output on fd4
- (if --index xml)
xml index stream (format not yet defined)
- output on state_fd
- (if --state-stream state_fd) see Application_API/DAR
Application proprietary format, this is the DAR state file use at restore file.
NOTE: | If your application does not produce indexing data it will not work with amrecover(8) |
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).
The -record option tell the application to record the backup it did with all the information it require to be able to do incremental at the same or higher level during the next backup. The application can record that information in the format it want and where it want. eg.
DUMP program use /etc/dumpdates amgtar use a different file for each dle and level, they are stored on the client in the GNUTAR-LISTDIR directory.
A good location is below the $amdatadir directory
restore command
restore [--message (line|xml)] [--index (line|xml)] [--config config] [--host host] [--disk disk] --device amdevice --level level [--dar YES|NO] [--recover-dump-state-file state_filename] [--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
- Output on fd3
- (if --dar) see Application_API/DAR
DAR <offset>:<size> #offset and size are in bytes, size can be -1 to get up to the end of the backup.
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 fd0: data stream output on fd1: (if --index line) index stream (One filename by line) output on fd1: (if --index xml) xml index stream output on fd2: (if no --message or --message line) error message output on fd2: (if --message xml) format not yet defined
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.
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 num_blocks block_size output 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.
Output: An estimate in KB of how much space this data set will consume. block_size is optional. If absent, it defaults to 1. The total size in KB of the backup is num_blocks*block_size
Note: If the the support command reports MULTI-ESTIMATE YES
, the multiple --level
options may be passed to the command and it can report multiple estimates with only one invocation.
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.
Unimplemented
validate command
- input on fd0
data stream
The minimum operation is to read the complete data stream and do nothing with it.
It's better if you can do more validation on the format:
checking the data stream is a valid tar file checking the data stream is a valid amanda-archive-format file ...
Must exist with an error code if the data stream is not valid. The output from fd2 is returned.
Run by amcheckdump(8) to validate a backup.