.\" @(#)add-tape.8 1.0 21-Apr-92 Steve Romig, CIS, The Ohio State University
.TH ADD-TAPE 8 "21 April 1992"
.SH NAME
add-tape \- add a tape to the tape database and label it
.SH SYNOPSIS
.B add-tape
.RB "[\|" \-t
.IR number "\|]"
.RB "[\|" \-f
.IR user@host:device "\|]"
.RB "[\|" \-l 
.IR location "\|]"
.RB "[\|" \-p
.IR prefix "\|]"
.RB "[\|" \-U "\|]"
.RB "[\|" \-e "\|]"
.RB "[\|" \-d 
.IR debuglevel "\|]"
.RB "[\|" \-h "\|]"
.SH DESCRIPTION
.LP
.B add-tape
is used to add a tape to the tape database.  Each tape has a label
written onto it magnetically (as the first file on the tape) which
contains the tape ID.  This is used by various parts of the backup
system to verify that you have the correct tape mounted before doing
anything that might be dangerous, either to your file systems or to
the tape contents.  Each tape also has an entry in the tape database
that describes its type, format, number of uses, age, and current use.
This is used by the backup system to manage the free tape pool and to
automatically expire tapes that have been used too many times or which
are too old.

The tape IDs are a little unwieldy, but there's a reason for that.
Once upon a time tape IDs in this system were simple integers.
The problem with that scheme is that once you start using several
different types of tapes it can be difficult finding your tapes: is
tape 100 a quarter inch cartridge in this cabinet, or a 8mm tape in
the second rack down the hall?  So tape IDs now look like "exb-2"
(second Exabyte type), or "qic-3" (third quarter inch cartridge).  The
first part of the ID is the same as the tape type.  The second part is
a number, unique within each tape type.  This means that all of your
8mm tapes could be numbered 1 through 200, and your QIC tapes could be
numbered 1-50.  That way, you can rack them or group them in numerical
order in groups according to type, and then finding the tapes
shouldn't be too difficult.  If you set the configuration name
("config" in the 
.B backup.config
file) to something other than the
default "", then that name will be prepended to all tape IDs.  For
example, for testing I set the config name to "test", and all of the
tapes for that configuration are named "test-exb-2" and so on.  This
allows you to easily distinguish tapes belonging to different
configurations from each other.

On the other hand, if you want to devise your own tape labeling
scheme, you can use the 
.B -p prefix
option to set the name prefix, which will be used instead of
"test-exb" or "exb".  A word of advice: if you have more than one
backup database, I would take care that the tapes for each
installation are labeled so that they are distinct, since otherwise
you could easily put the wrong "exb-2" tape in the drive, and the
backup system won't know the difference.

By default, the tapes inherit the location of the drives that they are
initialized on.  You can set the location specifically with the 
.B -l location
option.

If you do not give 
.B add-tape
any command line arguments, it will ask you for the name of a tape
drive and it will find the lowest available tape ID for that type of
tape, and label the tape and update the database.  You can override
its choice of ID number with the 
.B -t
switch.  If you plan to add
several tapes, you can also give a range of tape numbers with the 
.B -t
switch, in the form
.B N:M,
in which case 
.B add-tape
will add tapes using numbers from that range.

.B add-tape
checks the database to see if there's an entry for the tape ID that
you choose.  If there is one, it asks for confirmation before reusing
that ID and rewriting the database entry.  So its about as safe as can
be.  By default, it also checks the tape to see whether it is already
labeled.  If it is, it asks for confirmation before proceeding to
minimize the risk of accidently relabeling the wrong tape.  Since that
is somewhat time consuming, there's a 
.B -U
switch (U for UNSAFE) that
turns that checking off - don't say I didn't warn you, though.


If you don't specify the name of a tape drive with 
.B -f, 
.B add-tape
will ask you for the host and device for the tape drive to be used.
If a host is not given, the device is assumed to be local to the host
that 
.B add-tape
is run on.  You can use tape aliases if they are defined in the 
.B backup.config
file - see 
.B backup.config(5)
for details.  If 
.B add-tape
doesn't know the type and format that the tape drive can write, it
will ask you.  Obviously, the tape drive and the tape that you want to
add must be of the same type and format - otherwise you'll have a hard
time putting the tape into the drive!  You can specify a remote user
to use with the rsh command for remote tape drives, if you want.

The 
.B -e
option will prevent
.B add-tape
from ejecting the tape when it is finished.

You should add a physical label to each tape and write the tape ID
number on it in pen.  I would suggest also writing other info about
the latest contents of the tape on the physical label in pencil.  It is
handy to have available, and if you do it in pencil you can easily
erase the info when the tape is reused.  We include the date and time,
chain and level numbers, host names and the initials of the person who
ran the backup on the label.

The 
.B -d
switch turns on debugging messages.
The
.B -h
switch displays a
brief usage message.

.SH EXAMPLES
To add a new tape, you could just type:
.RS
.sp .5
.nf
add-tape
Which tape drive do you want to use? [12]
This will be tape exb-7
Load the tape and press return please.
.fi
.RE
.br
.ne 6
.LP
If you wanted to add a tape, using "red" as its prefix (instead of the
tape type) and assign it a location that is different than the tape
drive, you would type:
.RS
.sp .5
.nf
add-tape -p red -l bermuda
.fi
.RE
.br
.ne 6
.LP
Tapes always inherit the type of the drive that they are added on.  If
you wanted to add a particular tape, you could say 
.B add-tape -t 5
to add tape "exb-5", for example.  If you want to add several tapes
with successive IDs, you can use 
.B add-tape -t 5:10 -f 12
which will prompt you, one at a time, to load tapes into the drive,
and it will label them exb-5 through exb-10.

.SH "SEE ALSO"
.BR backup.config (5),
.BR reuse (8)
.br
.ne 5