git.gag.com Git - debian/amanda/blob - man/xml-source/amanda-taperscan.7.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 [
   5   <!-- entities files to use -->
   6   <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
   7   %global_entities;
   8 ]>
   9
  10 <refentry id='amanda-taperscan.7'>
  11
  12 <refmeta>
  13 <refentrytitle>amanda-taperscan</refentrytitle>
  14 <manvolnum>7</manvolnum>
  15 &rmi.source;
  16 &rmi.version;
  17 &rmi.manual.7;
  18 </refmeta>
  19 <refnamediv>
  20 <refname>amanda-taperscan</refname>
  21 <refpurpose>Amanda Taperscan Algorithms</refpurpose>
  22 </refnamediv>
  23 <refentryinfo>
  24 &author.dustin;
  25 </refentryinfo>
  26 <!-- body begins here -->
  27
  28 <refsect1><title>DESCRIPTION</title>
  29
  30 <para>Amanda uses a <emphasis>taperscan algorithm</emphasis> to select volumes
  31 on which to store dumps.  Historically Amanda has provided only one, fairly
  32 complex taperscan algorithm, but this algorithm did not suit the needs of all
  33 users.  Now Amanda offers a wide array of algorithms to suit varied needs.
  34 Adding new algorithms is not difficult.</para>
  35
  36 <para>The taperscan algorithm is specified with the <emphasis
  37 remap='B'>taperscan</emphasis> parameter, which has a default value of
  38 <emphasis remap='B'>traditional</emphasis>.</para>
  39
  40 <para>Taperscan algorithms are implemented as perl packages with the prefix
  41 <filename>Amanda::Taper::Scan::</filename>.  See the perl documentation for
  42 <filename>Amanda::Taper::Scan</filename> for more information.</para>
  43
  44 </refsect1>
  45
  46 <refsect1><title>DEFINING A TAPERSCAN</title>
  47
  48 <para>An taperscan is defined in &amconf; as follows:
  49
  50 <programlisting>
  51 define taperscan $taperscan_name {
  52    comment "$comment"
  53    plugin "$pluginname"
  54    property "$PROPERTY_NAME" "$PROPERTY_VALUE"
  55    ...
  56 }
  57 </programlisting>
  58 and then referenced in the global section as
  59 <programlisting>
  60   taperscan "$taperscan_name"
  61 </programlisting></para>
  62
  63 <para>Taperscan properties, like Amanda configuration parameters, are
  64 insensitive to case, and <literal>-</literal> (dash) and
  65 <literal>_</literal> (underscore) may be used interchangeably.</para>
  66
  67 <para>See the individual plugin documentation below for properties applicable to each
  68 plugin.</para>
  69
  70 </refsect1>
  71
  72 <refsect1><title>TAPERSCAN ALGORITHMS</title>
  73
  74 <para>In general, these algorithms will only select reusable volumes.  These are
  75 volumes which are listed in the &tapelist; with the <emphasis>reuse</emphasis>
  76 flag, and which are not among the <emphasis>tapecycle-1</emphasis> most recent
  77 volumes in the list.  Put another way, reusable volumes do not contain data
  78 that must be retained.  Note that if fewer than
  79 <emphasis>tapecycle-1</emphasis> volumes have been written then there are no
  80 reusable volumes.  Newly labeled volumes (volumes that have been labeled with
  81 &amlabel; but never used) are considered reusable.</para>
  82
  83 <para>Many of these algorithms look for the oldest reusable volume.  In most
  84 cases, this is the best volume to overwrite, as the data it contains is older
  85 than that on any other volume.  If there are no reusable volumes, then there is
  86 no oldest reusable volume.
  87 </para>
  88
  89 <refsect2><title>traditional</title>
  90
  91 <para>This algorithm duplicates Amanda's historical behavior, and it operates
  92 in two stages.</para>
  93
  94 <para>First, if there is an oldest reusable volume and if the changer supports
  95 "fast" searches, then the algorithm uses the changer to search for that volume.
  96 Newly labeled volumes are not considered when calculating the oldest reusable
  97 volume.  Consequently, this taperscan algorithm prefers volumes which have been
  98 used before to newly-labeled volumes when a fast-searchable changer is in
  99 use.</para>
 100
 101 <para>Second, if there is no oldest reusable volume, or if that volume is not
 102 available in the changer, then the algorithm begins a sequential scan of the
 103 changer, starting at the current slot.  It selects the first suitable volume it
 104 finds: a reusable volume (perhaps newly-labeled) or, if
 105 <amkeyword>autolabel</amkeyword> includes <amkeyword>empty</amkeyword>, a blank volume.  Even across
 106 multiple invocations (when <emphasis>runtapes &gt; 1</emphasis>), it will not
 107 return the same slot twice.</para>
 108
 109 <note>This algorithm shows an undue preference for volumes already containing
 110 data, by omitting newly-labeled volumes from its first stage.  Historically,
 111 many Amanda changer scripts were not fast-searchable (including
 112 <emphasis>chg-multi</emphasis>, <emphasis>chg-disk</emphasis> and, if
 113 <emphasis>havereader=0</emphasis>, <emphasis>chg-zd-mtx</emphasis>), and thus
 114 skipped the first stage, allowing new volumes to find their way into the tape
 115 cycle.  New changers are almost all fast-searchable, so both stages of the
 116 algorithm are used and new tapes may be unexpectedly excluded.  If this causes
 117 an undesirable change in behavior, consider one of the other taperscan
 118 algorithms.</note>
 119
 120 </refsect2>
 121
 122 <refsect2><title>oldest</title>
 123
 124 <para>This algorithm works with the Changer API (see <manref
 125 name="amanda-changers" vol="7" />), using the inventory returned by the
 126 changer to locate the oldest acceptable volume available. Note that this
 127 will not work with changers that do not support inventory (old
 128 changers).  The algorithms scans
 129 unknown slots only if no known usable volume is found in the inventory.</para>
 130
 131 <para>An acceptable volume is a reusable volume, a new labeled volume or an
 132 unlabeled volume that can be labeled according to <amkeyword>autolabel</amkeyword>.
 133 Note that changers do not always know the contents of every slot - for
 134 example, a tape with an unknown barcode will not be considered usable.</para>
 135
 136 <para>Use <command>amtape CONF inventory</command> to see the changer's inventory, and use
 137 <command>amtape CONF update</command> to update it.</para>
 138
 139 </refsect2>
 140
 141 <refsect2><title>lexical</title>
 142
 143 <para>This algorithm also works with the Changer API, using the inventory to
 144 determine the acceptable volumes; it then uses the volume which follows the
 145 last-used volume in lexical order.  For volume labels containing leading
 146 zeros, e.g., <filename>CORP-010</filename>, this algorithm will run through
 147 the volumes in the natural order.</para>
 148
 149 <para>It scans unknown slots only if no usable volume
 150 is found in the inventory.</para>
 151
 152 <para>See <amkeyword>oldest</amkeyword>, above, for a definition of acceptable
 153 volumes.</para>
 154
 155 >>>>>>> 6a40a39... manpage edits
 156 </refsect2>
 157
 158 </refsect1>
 159
 160 <seealso>
 161 <manref name="amanda.conf" vol="5"/>,
 162 <manref name="tapelist" vol="5"/>,
 163 <manref name="amanda-changers" vol="7"/>,
 164 <manref name="amanda-interactivity" vol="7"/>,
 165 </seealso>
 166
 167 </refentry>
 168