Re: amvault/amvault.8 documentation updates

Nathan Stratton Treadway <[email protected]> Mon, 25 Sep 2017 13:50:18 -0400
Newsgroups gmane.comp.archivers.amanda.devel
Message-ID <[email protected]> 
On Fri, Sep 22, 2017 at 08:51:25 -0400, Jean-Louis Martineau wrote:
> On 21/09/17 05:37 PM, Nathan Stratton Treadway wrote:
[...]
> > Is there a particular reason that --src-labelstr isn't sufficient as a
> > filter by itself?
> It was designed to specify a regex, the same labelstr as in the config file.
> 
> It is sufficient if an exact label is specified, but is kind of dangerous.
> If you have a run that write dumps to 2 labels (label-1 and label-2) and 
> one of the dump is split on the two tapes.
> 
> running
> 
>   * amvault --src-labelstr label-1
>   * amvault --src-labelstr label-2
> 
> Will not vault the dump that is split on both tapes.

Okay, I've attempted to capture that info in the attached new round of
proposed edits to amvault.8.xml .

I also fixed a typo in the --dest-storage section, and updated the second
paragraph of the DESCRIPTION section to match the earlier update to the
amvault usage message.

Finally, I tried to make clear that the --exact-match option applies to
dumpspecs only (i.e. not all the other filters).

I thought it was worth including the word "dumpspec" in the SYNOPSIS
command line to make it immediately clear what the "dump specifications"
mentioned later on the page are referring to.  Feel free to format that
differently though, e.g. replacing the inner "hostname" with "dumpspec...",
or whatever.

							Nathan


----------------------------------------------------------------------------
Nathan Stratton Treadway  -  [email protected]  -  Mid-Atlantic region
Ray Ontko & Co.  -  Software consulting services  -   http://www.ontko.com/
 GPG Key: http://www.ontko.com/~nathanst/gpg_key.txt   ID: 1023D/ECFB6239
 Key fingerprint = 6AD8 485E 20B9 5C71 231C  0C32 15F3 ADCD ECFB 6239
amvault.8_updates_20170925.patch (text/x-diff, 2.7 KB) 
diff --git a/man/xml-source/amvault.8.xml b/man/xml-source/amvault.8.xml
index ab85dd7..a5932bd 100644
--- a/man/xml-source/amvault.8.xml
+++ b/man/xml-source/amvault.8.xml
@@ -53,7 +53,7 @@
             <arg choice='plain'><replaceable>level</replaceable></arg>
             <arg choice='opt'>
               <arg choice='plain'><replaceable>hostname</replaceable></arg>
-              <arg choice='opt'>...</arg>
+              <arg choice='opt'>dumpspec...</arg>
             </arg>
           </arg>
         </arg>
@@ -81,8 +81,8 @@ encouraged!</para>
 <para>Amvault is conceptually equivalent to "amfetchdump | taper".  That is, it reads
 specified dumps from secondary media and re-writes them on tertiary media.</para>
 
-<para><emphasis remap='B'>Amvault</emphasis> Copies data on <option>src-storage</option> from the run with
-timestamp <option>src-timestamp</option> onto volumes using the storage
+<para><emphasis remap='B'>Amvault</emphasis> Copies dumps selected by the
+specified filters onto volumes on the storage
 <option>dest-storage</option>.</para>
 
 <refsect2><title>Secondary Media</title>
@@ -136,7 +136,7 @@ parameters there.  Then reference that tapetype in the amvault invocation:
 
 <para>If the <replaceable>vault-storage</replaceable> option is specified
 in &amconf;, amvault will use that storage as the default destination.
-If not, a destination storage must be specific on the amvault command
+If not, a destination storage must be specified on the amvault command
 line.</para>
   </listitem>
   </varlistentry>
@@ -152,7 +152,8 @@ perform any vaulting operations.</para>
   <varlistentry>
   <term><option>--exact-match</option></term>
   <listitem>
-<para>The host and disk are parsed as exact values</para>
+<para>The host and disk names in the dumpspecs are parsed as exact
+values.</para>
   </listitem>
   </varlistentry>
 
@@ -206,6 +207,18 @@ as dumps are being copied.</para>
   <term><option>--src-labelstr</option> <replaceable>labelstr</replaceable></term>
   <listitem>
 <para>Only dumps from volumes matching labelstr are copied.</para>
+
+<para>labelstr is a Perl regular expression, and will be matched as a
+substring of the volume labels -- it may be necessary to anchor the
+labelstr with "^" and/or "$" in order to prevent undesired partial
+matches.</para>
+
+<para>Also note that if a dump is split across multiple volumes and
+labelstr matches only one of those volumes, amvault will not select
+that dump for copying.  For this reason, it is generally safer to to
+select dumps directly using other filters, in which case amvault will
+be able to retrieve parts of split dumps from whatever volume they were
+originally written to.</para>
   </listitem>
   </varlistentry>