diff -r d176b9443312 -r 8231f7b00052 bin/amdumpext
--- a/bin/amdumpext	Mon Dec 16 15:29:52 2013 +0100
+++ b/bin/amdumpext	Mon Dec 16 16:36:15 2013 +0100
@@ -37,7 +37,7 @@
 use constant FD3       => 3;
 use constant FD4       => 4;
 
-$SIG{__DIE__} = sub { die "$ME: ", @_ };
+$SIG{__DIE__} = sub { die $^S ? '' : "$ME: ", @_ };
 
 my %SUPPORT = (
     CONFIG          => YES,    # --config … (default)
@@ -123,7 +123,7 @@
     OK "$ME version $VERSION";
     OK "euid=$> (" . getpwuid($>) . ')';
     OK "egid=" . do {
-        my $gid = (split ' ', $))[0];
+        my ($gid, undef) = split ' ', $);
         my $group = getgrgid $gid;
         "$gid ($group)";
     };
@@ -135,7 +135,8 @@
 
     foreach my $tool (qw(dump restore)) {
         if ($_ = (grep { -x ($_ .= "/$tool") } split /:/ => $ENV{PATH})[0]) {
-            chomp(my $version = (`$_ 2>&1`)[0]);
+            my ($version, undef) = `$_ 2>&1`;
+	    chomp $version;
             OK "$tool is $version";
         }
         else {
@@ -156,8 +157,8 @@
         my $dumpdates = $opt_dumpdates ? expand($opt_dumpdates) : DUMPDATES;
 
         eval { open(my $x, "+>>", $dumpdates) or die "$!\n" };
-        if   (chomp $@) { ERROR "dumpdates file \"$dumpdates\": $@" }
-        else            { OK "dumpdates file: \"$dumpdates\"" }
+        if   (chomp $@) { ERROR "dumpdates file $dumpdates: $@" }
+        else            { OK "dumpdates file is $dumpdates" }
     }
 
     exit 0;
@@ -421,62 +422,78 @@
   amdumpext selfcheck [options] [--level <level>]    --device <device> 
   amdumpext estimate [options]  [--level <level>]... --device <device> 
 
+=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.
+
 =head1 COMMANDS
 
+The B<amdumpext> supports the commands from the API description found on 
+L<http://wiki.zmanda.com/index.php/Application_API/Operations>.
+
+=head1 COMMON OPTIONS
+
 =over
 
-=item B<support>
-
-Send a list of supported features.
-
-=back
-
-=head1 OPTIONS
-
-=head2 Common Options
+=item B<--device> I<device>
 
-The following options have to be supported by the application.
-
-=over 4
-
-=item B<--config> I<config>
-
-The configuration to be used (the backup set).
-
-=item B<--host> I<host>
-
-The host from the DLE.
+The disk device from the disklist.
 
 =item B<--disk> I<disk>
 
-The disk to be saved. It's some "label" for the device to be backed up.
+The diskname from the disklist. Currently ignored.
+
+=item B<--host> I<host>
+
+The hostname from the disklist. Currently ignored.
+
+=item B<--config> I<config>
+
+The name of the configuration.
+
+=item B<--level> I<level>
 
-=item B<--device> I<device>
+The level of the backup. 0 means full backup.
+
+=item B<--index> I<xml|line>
 
-The device to be backed up (may be a device name, a mountpoint).
+Create an index of the files backed up. XML is not supported yet.
+(Default: not set, means no index at all)
+
+=item B<--message> I<xml|line>
+
+The format used for messages. XML is not supported yet.
+(Default: line)
 
 =back
 
-=head2 Optional options
+=head1 COMMANDS
+
+=head2 support
+
+This command returns the list of supported features.
 
-The following options need to be supported if indicated by the "support"
-command.
+=head2 selfcheck
 
-=over
+This command instructs B<amdumpext> to so some selfchecks. In an ideal
+world it will detect any problem that might prevent a successful backup.
 
-=item B<--message> "line"
+mandatory options: device, level
 
-Send messages line by line.
+=head2 estimate
 
-=item B<--index> "line"
-
-Send the index line by line.
+Create an estimate about the amount of data we may expect for the
+backup. Multi-Level estimates are supported.
 
-=back
+mandatory options: device, level, ...
+
+=head1 PROPERTIES
 
-=cut
-
-=head2 Properties
+The properties may be set on the server side to tune the behaviour
+of the application. Currently property setting on the client side is
+not supported.
 
 =over 4
 
@@ -487,14 +504,58 @@
 
 =back
 
+=head1 TESTING
+
+The B<amdumpext> may be tested on the command line. The following output
+file descriptors are used:
+
+=over
+
+=item 1 (STDOUT)
+
+The normal command output, the data stream.
+
+=item 2 (STDERR)
+
+Not used by the API, but probably redirected to some log files.
+
+=item 3 (messages)
+
+Operational messages, often it's postprocessed output of some of 
+the invoked tools
+
+=item 4 (index)
+
+If index generation is ordered (via the B<--index> option), the index is 
+sent to this file descriptor.
+
+=back
+
+The following shell command line is suitable to test the B<amdumpext>:
+
+    $ amdumpext backup --device /dev/sda1 --level 0 1>dump 3>messages 4>index
+
+If you're interested in reading the messages as they appear:
+
+    $ amdumpext backup --device /dev/sda1 --level 0 3>&1 1>dump 4>index
+
+
 =head1 EXAMPLE
 
-    define application "dump" {
+The C<amanda.conf> should contain something similiar to the following
+stanza:
+
+    define application "mydump" {
         plugin "amdumpext"
 	# optional - define some additional parameters
         property "dumpdates" "/tmp/dumpdates.${c}"
    }
 
+   define dumptype "dump" {
+	program "APPLICATION"
+	application "mydump"
+    }
+
 
 =cut