'\" t
.\"     Title: amanda-taperscan
.\"    Author: Dustin J. Mitchell <dustin@zmanda.com>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 12/01/2017
.\"    Manual: Miscellanea
.\"    Source: Amanda 3.5.1
.\"  Language: English
.\"
.TH "AMANDA\-TAPERSCAN" "7" "12/01/2017" "Amanda 3\&.5\&.1" "Miscellanea"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
amanda-taperscan \- Amanda Taperscan Algorithms
.SH "DESCRIPTION"
.PP
Amanda uses a
\fItaperscan algorithm\fR
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\&.
.PP
The taperscan algorithm is specified with the
\fBtaperscan\fR
parameter, which has a default value of
\fBtraditional\fR\&.
.PP
Taperscan algorithms are implemented as perl packages with the prefix
Amanda::Taper::Scan::\&. See the perl documentation for
Amanda::Taper::Scan
for more information\&.
.SH "DEFINING A TAPERSCAN"
.PP
An taperscan is defined in
\fBamanda.conf\fR(5)
as follows:
.sp
.nf
define taperscan $taperscan_name {
   comment "$comment"
   plugin "$pluginname"
   property "$PROPERTY_NAME" "$PROPERTY_VALUE"
   \&.\&.\&.
}
.fi
and then referenced in the global section as
.sp
.nf
  taperscan "$taperscan_name"
.fi
.PP
Taperscan properties, like Amanda configuration parameters, are insensitive to case, and
\-
(dash) and
_
(underscore) may be used interchangeably\&.
.PP
See the individual plugin documentation below for properties applicable to each plugin\&.
.SH "TAPERSCAN ALGORITHMS"
.PP
In general, these algorithms will only select reusable volumes\&. These are volumes which are listed in the
\fBtapelist\fR(5)
with the
\fIreuse\fR
flag, and which are not among the
\fItapecycle\-1\fR
most recent volumes in the list\&. Put another way, reusable volumes do not contain data that must be retained\&. Note that if fewer than
\fItapecycle\-1\fR
volumes have been written then there are no reusable volumes\&. Newly labeled volumes (volumes that have been labeled with
\fBamlabel\fR
but never used) are considered reusable\&.
.PP
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\&.
.SS "traditional"
.PP
This algorithm duplicates Amanda\*(Aqs historical behavior, and it operates in two stages\&.
.PP
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\&.
.PP
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
\fBautolabel\fR
includes
\fBempty\fR, a blank volume\&. Even across multiple invocations (when
\fIruntapes > 1\fR), it will not return the same slot twice\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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
\fIchg\-multi\fR, \fIchg\-disk\fR and, if
\fIhavereader=0\fR, \fIchg\-zd\-mtx\fR), 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\&..sp .5v
.RE
.SS "oldest"
.PP
This algorithm works with the Changer API (see
\fBamanda-changers\fR(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\&.
.PP
An acceptable volume is a reusable volume, a new labeled volume or an unlabeled volume that can be labeled according to
\fBautolabel\fR\&. 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\&.
.PP
Use
\fBamtape CONF inventory\fR
to see the changer\*(Aqs inventory, and use
\fBamtape CONF update\fR
to update it\&.
.SS "lexical"
.PP
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\&.,
CORP\-010, this algorithm will run through the volumes in the natural order\&.
.PP
It scans unknown slots only if no usable volume is found in the inventory\&.
.PP
See
\fBoldest\fR, above, for a definition of acceptable volumes\&.
.SH "SEE ALSO"
.PP
\fBamanda\fR(8),
\fBamanda.conf\fR(5),
\fBtapelist\fR(5),
\fBamanda-changers\fR(7),
\fBamanda-interactivity\fR(7)
.PP
The Amanda Wiki:
: http://wiki.zmanda.com/
.SH "AUTHOR"
.PP
\fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
.RS 4
Zmanda, Inc\&. (http://www\&.zmanda\&.com)
.RE