Amanda::Recovery modules list
Amanda modules list
List of All Modules
All Amanda Releases



Amanda::Recovery::Planner - use the catalog to plan recoveries


    my $plan;
    $subs{'make_plan'} = make_cb(make_plan => sub {
            dumpspecs => [ $ds1, $ds2 ],
            algorithm => $algo,
            changer => $changer,
            plan_cb => $subs{'plan_cb'});
    $subs{'plan_cb'} = make_cb(plan_cb => sub {
        my ($err, $pl) = @_;
        die $err if $err;
        $plan = $pl;
    $subs{'start_next_dumpfile'} = make_cb(start_next_dumpfile => sub {
        my $dump = shift @{$plan->{'dumps'}};
        if (!$dump) {
            # .. all done!
        print "recovering ", $dump->{'hostname'}, " ", $dump->{'diskname'}, "\n";
        $clerk->get_xfer_src( .. dump => $dump .. );
        # ..


This package determines the optimal way to recover dump files from storage. Its function is superficially fairly simple: given a collection of desired dumpfiles, it returns a Plan to recover those dumpfiles, specifying exactly the volumes and files that are needed, and the order in which they should be accesed.


Several algorithms will soon be available for selecting volumes when a dumpfile appears in several places (e.g., from an amvault operation). At the moment, the algorithm argument should be omitted, as this will eventually indicate that the user-configured algorithm should be applied.


For most purposes, you should call make_plan with the desired dumpspecs, a changer, and a callback:

        dumpspecs => [ $ds1, $ds2, .. ],
        changer => $chg,
        plan_cb => $plan_cb);

As a shortcut, you may also specify a single dumpspec:

        dumpspec => $ds,
        changer => $chg,
        plan_cb => $plan_cb);

Note that in this case, the resulting plan may contain more than one dump, if the dumpspec was not unambiguous.

To select the planner algorithm, pass an algorithm argument. This argument is currently ignored and should be omitted. If the optional argument debug is given with a true value, then the Planner will log additional debug information to the Amanda debug logs. Debugging is automatically enabled if the DEBUG_RECOVERY configuration parameter is set to anything greater than 1.

The optional argument one_dump_per_part will create a "no-reassembly" plan, where each part appears as the only part in a unique dump. The dump objects will have the key single_part set to 1.

The plan_cb is called with two arguments:

    $plan_cb->($err, $plan);

If $err is defined, it describes an error that occurred; otherwise, $plan is the generated plan, as described below.

Some algorithms may consult the changer's inventory to determine what volumes are available. It is because of this asynchronous operation that make_plan takes a callback instead of simply returning the plan.

Pre-defined Plans

In some cases, you already know exactly where the data is, and just need a proper plan object to hand to Amanda::Recovery::Clerk. One such case is a recovery from a holding file. In this case, use make_plan like this:

        holding_file => $hf,
        dumpspec => $ds,
        plan_cb => $plan_cb);

This will create a plan to recover the data in $fh. The dumpspec is optional, but if present will be used to verify that the holding file contains the appropriate dump.

Similarly, if you have a list of label:fileno pairs to use, call make_plan like this:

        filelist => [
            $label => [ $filenum, $filenum, .. ],
            $label => ..
        dumpspec => $ds,
        plan_cb => $plan_cb);

This will verify the requested files against the catalog and the dumpspec, then hand back a plan that essentially embodies filelist.

Note that both of these functions will only create a single-dump plan.


A Plan is a perl object describing the process for recovering zero or more dumpfiles. Its principal components are dumps, in order, that are to be recovered, but the object presents some other interfaces that return useful information about the plan.

The 'dumps' key holds the list of dumps, in the order they should be performed. Callers should shift dumps off this list to present to the Clerk.

To get a list of volumes that the plan requires, in order, use get_volume_list. Each volume is represented as a hash:

  { label => 'DATA182', available => 1 }

where available is false if the planner did not find this volume in the changer. Planners which do not consult the changer will have a false value for available.

Similarly, to get a list of holding files that the plan requires, in order, use get_holding_file_list. Each file is represented as a string giving the fully qualified pathname.


This page was automatically generated Tue Feb 21 19:14:01 2012 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.