--- a/bin/amdumpext	Tue Dec 17 11:43:25 2013 +0100
+++ b/bin/amdumpext	Tue Dec 17 15:58:28 2013 +0100
@@ -471,7 +471,7 @@
 
 =head1 NAME
 
-  amdumpext - the amanda dump application
+  amdumpext - the amanda dump/restore ext2/3/4 application plugin
 
 =head1 SYNOPSIS
 
@@ -480,19 +480,27 @@
   amdumpext backup    [options] [--level <level>] --device <device> 
   amdumpext estimate  [options] [--level <level>]... --device <device> 
   amdumpext validate  [options]
-  amdumpext restore   [options]
+  amdumpext restore   [options] [file system objects]
 
 =head1 DESCRIPTION
 
-The B<amdumpext> is an application plugin for amanda. It drives the
-native ext2/3/4 dump/restore programs found on most Linux systems. See L<dump(8)>
-and L<restore(8)> for more information on these tools.
+The B<amdumpext> is an application plugin for amanda.  It's not intended
+to be called directly by the user.
+
+It drives the native ext2/3/4 dump/restore programs found on most Linux
+systems. See L<dump(8)> and L<restore(8)> for more information on these
+tools.
+
+B<NOTE>: During development it turned out that dump/restore are badly
+maintained and that there might arise conditions where you can't easily
+restore from an incremtal dump. (See bug #157 at the sourceforge dump
+project site.) The problems seem start with restore 0.4b43 and do still
+exist in 0.4b44.
 
 =head1 OPTIONS
 
-The commands may need some options. These options are noted per command.
-Unsupported options are silently ignored. Unknown options are not
-allowed.
+The commands may need some options.  Unsupported options are silently
+ignored. Unknown options are not allowed.
 
 =over
 
@@ -539,11 +547,10 @@
 =item B<--dumpdates> I<dumpdates>
 
 The location of the dumpdates file. Placeholder "${c}" is allowed and
-replaced by the name of the current config.
+replaced with the name of the current config.
 
 =back
 
-
 =head1 COMMANDS
 
 The B<amdumpext> supports the commands from the API description found on 
@@ -560,6 +567,7 @@
 
 mandatory options: device, level
 
+
 =head2 estimate
 
 Create an estimate about the amount of data we may expect for the
@@ -567,6 +575,13 @@
 
 mandatory options: device, level, ...
 
+=head2 backup
+
+This commands creates a backup. It's send to fd 1, messages from the
+backup go to fd3, optional index data goes to fd4.
+
+mandatory options: device, level
+
 =head2 validate
 
 This checks if the data stream is readable and looks like a dump.
@@ -575,11 +590,19 @@
 
 =head2 restore
 
-Restore from a single dump.
+Restore from a single dump. In addition to the common options the server
+passes a list of file system objects to be restored. The list should be
+simplified, overlapping objects should be merged into one object.
+
+Currently (Amanda 3.3.5) it seems as if the server sends F<.> as object
+name for a complete file system recovery. This triggers C<restore -rf>,
+any other object name triggers the invocation of C<restore -xf>. This
+means, real incremental recoveries are only possible on the base of the
+complete file system.
 
 =head1 TESTING
 
-The B<amdumpext> may be tested on the command line. The following output
+The B<amdumpext> and it's subcommands may be tested on the command line. The following output
 file descriptors are used:
 
 =over
@@ -612,6 +635,18 @@
 
     $ amdumpext backup --device /dev/sda1 --level 0 3>&1 1>dump 4>index
 
+To validate the backup:
+
+    $ amdumpext validate <dump
+    $ echo $?
+
+And finally to check the restore process:
+
+    $ amdumpext restore . <dump
+
+Or
+    $ amdumpext restore dirA dirB file/C
+
 
 =head1 EXAMPLE
 
@@ -621,7 +656,8 @@
     define application "mydump" {
         plugin "amdumpext"
 	# optional - define some additional parameters
-        property "dumpdates" "/tmp/dumpdates.${c}"
+	# ${c} - the name of the current config
+        property "dumpdates" "/var/lib/dumpdates.${c}"
    }
 
    define dumptype "dump" {

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/misc/reproduce-restore-bug	Tue Dec 17 15:58:28 2013 +0100
@@ -0,0 +1,51 @@
+#! /bin/sh
+
+set -e
+
+cleanup() {
+    umount $mnt 2>/dev/null || true
+    losetup -vd $loop || true
+    rm -r $dir
+}
+
+trap cleanup EXIT
+
+dir=`mktemp -d`
+
+image=$dir/image
+mnt=$dir/mnt
+record=$dir/dumpdates
+
+echo "# creating sparse image file $image"
+dd of=$image count=0 bs=1M seek=128
+
+echo "# creating the mountpoint"
+mkdir $dir/mnt
+
+x=$(losetup -fv $image)
+loop=${x##* }
+echo "# image connected to $loop"
+
+mkfs -t ext4 $loop
+
+# installing sample data
+mount $loop $mnt
+mkdir $mnt/abc.d
+touch $mnt/abc.d/foo
+sync
+umount $mnt
+
+dump -0 -u -D $record -f $dir/dump-0 $loop
+
+# remove the dir
+mount $loop $mnt
+mv $mnt/abc.d/foo $mnt/
+rmdir $mnt/abc.d
+sync
+umount $mnt
+
+dump -1 -u -D $record -f $dir/dump-1 $loop
+
+# now starting a shell
+cd $dir
+$SHELL