Merge branch 'master' into squeeze
[debian/amanda] / man / xml-source / amanda-taperscan.7.xml
diff --git a/man/xml-source/amanda-taperscan.7.xml b/man/xml-source/amanda-taperscan.7.xml
new file mode 100644 (file)
index 0000000..6882c38
--- /dev/null
@@ -0,0 +1,167 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
+  <!-- entities files to use -->
+  <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
+  %global_entities;
+]>
+
+<refentry id='amanda-taperscan.7'>
+
+<refmeta>
+<refentrytitle>amanda-taperscan</refentrytitle>
+<manvolnum>7</manvolnum>
+&rmi.source;
+&rmi.version;
+&rmi.manual.7;
+</refmeta>
+<refnamediv>
+<refname>amanda-taperscan</refname>
+<refpurpose>Amanda Taperscan Algorithms</refpurpose>
+</refnamediv>
+<refentryinfo>
+&author.dustin;
+</refentryinfo>
+<!-- body begins here -->
+
+<refsect1><title>DESCRIPTION</title>
+
+<para>Amanda uses a <emphasis>taperscan algorithm</emphasis> to select volumes
+on which to store dumps.  Historically Amanda has provided only one, fairly
+complex taperscan algorithm, but this algorithm did not suit the needs of all
+users.  Now Amanda offers a wide array of algorithms to suit varied needs.
+Adding new algorithms is not difficult.</para>
+
+<para>The taperscan algorithm is specified with the <emphasis
+remap='B'>taperscan</emphasis> parameter, which has a default value of
+<emphasis remap='B'>traditional</emphasis>.</para>
+
+<para>Taperscan algorithms are implemented as perl packages with the prefix
+<filename>Amanda::Taper::Scan::</filename>.  See the perl documentation for
+<filename>Amanda::Taper::Scan</filename> for more information.</para>
+
+</refsect1>
+
+<refsect1><title>DEFINING A TAPERSCAN</title>
+
+<para>An taperscan is defined in &amconf; as follows:
+
+<programlisting>
+define taperscan $taperscan_name {
+   comment "$comment"
+   plugin "$pluginname"
+   property "$PROPERTY_NAME" "$PROPERTY_VALUE"
+   ...
+}
+</programlisting>
+and then referenced in the global section as
+<programlisting>
+  taperscan "$taperscan_name"
+</programlisting></para>
+
+<para>Taperscan properties, like Amanda configuration parameters, are
+insensitive to case, and <literal>-</literal> (dash) and
+<literal>_</literal> (underscore) may be used interchangeably.</para>
+
+<para>See the individual plugin documentation below for properties applicable to each
+plugin.</para>
+
+</refsect1>
+
+<refsect1><title>TAPERSCAN ALGORITHMS</title>
+
+<para>In general, these algorithms will only select reusable volumes.  These are
+volumes which are listed in the &tapelist; with the <emphasis>reuse</emphasis>
+flag, and which are not among the <emphasis>tapecycle-1</emphasis> most recent
+volumes in the list.  Put another way, reusable volumes do not contain data
+that must be retained.  Note that if fewer than
+<emphasis>tapecycle-1</emphasis> volumes have been written then there are no
+reusable volumes.  Newly labeled volumes (volumes that have been labeled with
+&amlabel; but never used) are considered reusable.</para>
+
+<para>Many of these algorithms look for the oldest reusable volume.  In most
+cases, this is the best volume to overwrite, as the data it contains is older
+than that on any other volume.  If there are no reusable volumes, then there is
+no oldest reusable volume.
+</para>
+
+<refsect2><title>traditional</title>
+
+<para>This algorithm duplicates Amanda's historical behavior, and it operates
+in two stages.</para>
+
+<para>First, if there is an oldest reusable volume and if the changer supports
+"fast" searches, then the algorithm uses the changer to search for that volume.
+Newly labeled volumes are not considered when calculating the oldest reusable
+volume.  Consequently, this taperscan algorithm prefers volumes which have been
+used before to newly-labeled volumes when a fast-searchable changer is in
+use.</para>
+
+<para>Second, if there is no oldest reusable volume, or if that volume is not
+available in the changer, then the algorithm begins a sequential scan of the
+changer, starting at the current slot.  It selects the first suitable volume it
+finds: a reusable volume (perhaps newly-labeled) or, if
+<amkeyword>autolabel</amkeyword> includes <amkeyword>empty</amkeyword>, a blank volume.  Even across
+multiple invocations (when <emphasis>runtapes &gt; 1</emphasis>), it will not
+return the same slot twice.</para>
+
+<note>This algorithm shows an undue preference for volumes already containing
+data, by omitting newly-labeled volumes from its first stage.  Historically,
+many Amanda changer scripts were not fast-searchable (including
+<emphasis>chg-multi</emphasis>, <emphasis>chg-disk</emphasis> and, if
+<emphasis>havereader=0</emphasis>, <emphasis>chg-zd-mtx</emphasis>), and thus
+skipped the first stage, allowing new volumes to find their way into the tape
+cycle.  New changers are almost all fast-searchable, so both stages of the
+algorithm are used and new tapes may be unexpectedly excluded.  If this causes
+an undesirable change in behavior, consider one of the other taperscan
+algorithms.</note>
+
+</refsect2>
+
+<refsect2><title>oldest</title>
+
+<para>This algorithm works with the Changer API (see <manref
+name="amanda-changers" vol="7" />), using the inventory returned by the
+changer to locate the oldest acceptable volume available. Note that this
+will not work with changers that do not support inventory (old
+changers).  The algorithms scans
+unknown slots only if no known usable volume is found in the inventory.</para>
+
+<para>An acceptable volume is a reusable volume, a new labeled volume or an
+unlabeled volume that can be labeled according to <amkeyword>autolabel</amkeyword>.
+Note that changers do not always know the contents of every slot - for
+example, a tape with an unknown barcode will not be considered usable.</para>
+
+<para>Use <command>amtape CONF inventory</command> to see the changer's inventory, and use
+<command>amtape CONF update</command> to update it.</para>
+
+</refsect2>
+
+<refsect2><title>lexical</title>
+
+<para>This algorithm also works with the Changer API, using the inventory to
+determine the acceptable volumes; it then uses the volume which follows the
+last-used volume in lexical order.  For volume labels containing leading
+zeros, e.g., <filename>CORP-010</filename>, this algorithm will run through
+the volumes in the natural order.</para>
+
+<para>It scans unknown slots only if no usable volume
+is found in the inventory.</para>
+
+<para>See <amkeyword>oldest</amkeyword>, above, for a definition of acceptable
+volumes.</para>
+
+</refsect2>
+
+</refsect1>
+
+<seealso>
+<manref name="amanda.conf" vol="5"/>,
+<manref name="tapelist" vol="5"/>,
+<manref name="amanda-changers" vol="7"/>,
+<manref name="amanda-interactivity" vol="7"/>,
+</seealso>
+
+</refentry>
+