Amanda::Recovery::Clerk - handle assembling dumpfiles from multiple parts
step setup => sub {
$clerk->get_xfer_src(
dump => $dump, # from Amanda::Recovery::Planner or Amanda::DB::Catalog2
xfer_src_cb => $steps->{'xfer_src_cb'});
};
step xfer_src_cb => sub {
my ($errors, $header, $xfer_src, $directtcp_supported) = @_;
die join("\n", @$errors) if ($errors);
print "restoring from " . $header->summary() . "\n";
my $xfer = Amanda::Xfer->new([$xfer_src, $xfer_dest]);
$xfer->start(sub { $clerk->handle_xmsg(@_); });
$clerk->start_recovery(
xfer => $xfer,
recovery_cb => $steps->{'recovery_cb'});
};
step recovery_cb => sub {
my %params = @_;
die join("\n", @{$params{'errors'}}) if ($params{'errors'});
print "result: $params{result}\n";
};
# ...
$clerk->quit(finished_cb => sub {
$next_op_cb->();
};This package is the counterpart to Amanda::Taper::Scribe, and handles re-assembling dumpfiles from multiple parts, possibly distributed over several volumes.
A Clerk manages a source element in a transfer. The destination is up to the caller - it could be a file, or even an element obtained from a Scribe. A particular Clerk instance only handles one transfer at a time, but maintains its state between transfers, so multiple transfers from the same device will proceed without rewinding or reloading the volume.
At a high level, the Clerk is operated as follows: the caller provides a dump, which includes information on the volumes, and file numbers on those volumes, from which to read the data. The dump object is from Amanda::DB::Catalog2, usually by awy of Amanda::Recovery::Planner. The Clerk responds with a transfer source element, which the caller then uses to construct an start a transfer. The clerk then uses a changer to find the required volumes, seeks to the appropriate files, and reads the data into the transfer. Note that the clerk can also recover holding-disk files.
Because the clerk operates transfers (see Amanda::Xfer) and the Changer API (Amanda::Changer), its operations assume that Amanda::MainLoop is in use.
To use a Clerk, first create a new object, giving the changer object that the Clerk should use to load devices:
my $clerk = Amanda::Recovery::Clerk->new(
scan => $scan);If the optional parameter debug is given with a true value, then the Clerk will log additional debug information to the Amanda debug logs. This value is also set to true if the DEBUG_RECOVERY configuration parameter is set.
The optional feedback parameter gives an object which will handle feedback form the clerk. See FEEDBACK, below.
The scan parameter must be an Amanda::Recovery::Scan instance, which will be used to find the volumes required for the recovery.
Next, get a dump object and supply it to the Clerk to get a transfer source element. The Clerk will verify that the supplied dump matches the on-medium header during the recovery operation, taking into account the single_part flag added by the Planner for single-part recoveries.
$clerk->get_xfer_src(
dump => $dump,
xfer_src_cb => $xfer_src_cb);During this operation, the Clerk looks up the first part in the dump and fetches its header. Callers often need this header to construct a transfer appropriate to the data on the volume. The $xfer_src_cb is called with a transfer element and with the first header, or with a list of errors if something goes wrong. The final argument is true if the device from which the restore is done supports directtcp.
$xfer_src_cb->(undef, $header, $xfer_src, $dtcp_supp); # OK
$xfer_src_cb->([ $err, $err2 ], undef, undef, undef); # errorsOnce $xfer_src_cb has been called, build the transfer element into a transfer, and start the transfer. Send all transfer messages to the clerk:
my $xfer->start(sub {
my ($src, $msg, $xfer) = @_;
$clerk->handle_xmsg($src, $msg, $xfer);
});Once the transfer is started, inform the Clerk:
$clerk->recovery_started(
xfer => $xfer,
recovery_cb => $recovery_cb);The $recovery_cb will be called when the recovery is complete - either successfully or unsuccessfully. It is called as:
$recovery_cb->(
result => "DONE", # or "FAILED"
errors => [], # or a list of error messages
);Once the recovery callback has been invoked, it is safe to start a new transfer with the same Clerk.
Note that, because the Clerk only handles one transfer at a time, if dumpfiles are interleaved on a volume then the recovery process will need to seek to and read all parts from one dumpfile before reading any parts from the next dumpfile. Amanda does not generate interleaved dumps, so in practice this limitation is not significant.
When all necessary dumpfiles have been transferred, the Clerk must be cleanly shut down. This is done with the quit method:
$clerk->quit(
finished_cb => $finished_cb);The process should not exit until the finished_cb has been invoked.
A feedback object implements a number of methods that are called at various times in the recovery process, allowing the user to customize that behavior. A user-defined feedback object should inherit from Amanda::Recovery::Clerk::Feedback, which implements no-op versions of all of the methods.
The clerk_notif_part method is called just before each part is restored, and is given the label, filenum, and header. Its return value, if any, is ignored. Similarly, clerk_notif_holding is called for a holding-disk recovery and is given the holding filename and its header. Note that clerk_notif_holding is called before the xfer_src_cb, since data will begin flowing from a holding disk immediately when the transfer is started.
A typical Clerk feedback class might look like:
use 'Amanda::Recovery::Clerk';
use parent -norequire, 'Amanda::Recovery::Clerk::Feedback';
sub clerk_notif_part {
my $self = shift;
my ($label, $filenum, $hdr) = @_;
print "restoring part ", $hdr->{'partnum'},
" from '$label' file $filenum\n";
}This page was automatically generated Tue Mar 19 07:08:16 2019 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.