Sophie: taper-7.0-0.pre1.19.mga7 armv7hl

taper-7.0-0.pre1.19.mga7.armv7hl.rpm

Taper
Yusuf Nagree
Version 7.0pre-1. 19MAY02.
____________________________________________________________

Table of Contents

1. Disclaimer
2. Warning
3. Introduction
4. Requirements
5. Unpacking and Compiling
5.1 File locations
5.2 Modifying defaults.h

6. Terminology
7. Tape Devices
8. Tape drives
8.1 ftape
8.2 zftape
8.3 SCSI Drives
8.4 IDE tape drives
8.5 Floppies and other removable media

9. Quick fast forwards
10. Can seek
11. Formatting and Erasing Tapes
12. /proc Filesystem
13. Compression
14. Running Taper
14.1 Command line options
14.2 Backup Module
14.2.1 Backup modes
14.3 Restore
14.3.1 Restore modes
14.3.1.1 Full restore
14.3.1.2 Most recent volume restore
14.3.1.3 Fixed volume restore
14.4 Recreate info file
14.5 Verify archive
14.6 Utilities
14.6.1 Make tape
14.6.2 Test make tape
14.6.3 Which proc
14.6.4 Test fast fsf
14.6.5 Test can seek
14.6.6 Test end of tape
14.6.7 Erase volumes
14.6.8 Reindex info file
14.6.9 Look for recursive links
14.6.10 Attempt Recovery

15. Unattended Backup
16. File Sets
16.1 File Set format

17. Environment variables
18. Preferences
18.1 Changing preferences
18.2 Saving preferences
18.3 Preference file format
18.4 Special preferences

19. Screen Colours
20. Multiple Tape Backups
20.1 Writing
20.2 Reading

21. Cross platform support
22. Limitations
23. Bugs
24. Major bugs in early versions
25. Finally
______________________________________________________________________

11.. DDiissccllaaiimmeerr

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation;

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

22.. WWaarrnniinngg

Please note that this is BETA software. This means that it is still
under development. This program works fine on my setup (DX2-66, Jumbo
250, Floppy controller, 32Mb RAM, 3 IDE hard drives (120mb, 120mb,
540mb), Suprafax modem, Mitsumi Quad Speed IDE CD-ROM, serial mouse).

However, there are hundreds (if not thousands) of different
configurations out there. I cannot test them all (which why this
software is beta). Before using this program for 'production' backups,
PLEASE ensure that both the backup and restore programs work correctly
on YOUR system. Until you have confirmed this (several times, I
suggest), then only should you use this as your only means of backup.
Until then, please also backup using a method you KNOW works for you.

Having said this, from the comments I have received so far, it does
seem to work on a fair few systems so I hope it does work on yours.
If it doesn't, I'd like to know.

33.. IInnttrroodduuccttiioonn

Taper is a user friendly archive program especially designed for
backing up to tape drives. It also supports backing up to files on a
hard disk

It, I hope, overcomes the lack of programs available currently for
Linux for user friendly archiving.

Tar/cpio, apart from having an unfriendly user interface, lack one
essential feature that I needed - there was no information stored in
the beginning of the archive about what files were on the archive. The
only way to get such a list was to traverse the whole archive, getting
cpio/tar to print out a list of files that it found. With a 250mB
archive, this could easily take 5 min. It was a real hassle to
maintain lists of files on all my tapes and it could take 20 min to
locate a file if I didn't know which tape it was on - printing out
file lists of each tape.

I solved this by maintaining an archive information file on the hard
disk. This file contains all the information about files stored on
the archive. When files are added to the archive, the archive
information file is updated. This archive information file can be
reconstructed from the archive should the file get
deleted/corrupted/lost - it just takes time.

To speed access to the files, the info file cluster consists of four
files - two main files and two indexes. The names of the main files
are taper_x and taper_x.0, while the two indexes are taper_x.1 and
taper_x.2. The files are placed in the default info file directory.
Note that 'x' is the archive ID (see below).

Should you wish to restore an archive on a different machine than one
to where the backup was made, you have two options

+o make a copy of the two main info files on a floppy and take this
floppy with you as well as the tape. You will have to reindex the
file on your target machine. If you do not want to reindex, then
take all four files on the floppy with you.

+o reconstruct the archive information file on the restoring machine.

Since reconstructing the archive information file can take a while,
the first method is recommended. Info files can be quite long and
there are three of them. A short housekeeping file, a main file and an
index file. When transporting info files, on the short file and the
main file need be transported - the index file can be reindexed.
Although these info files can be long, they compress very well -
typically more than 10:1 so it is important that you have the compress
info files preference ON.

Note, that as a security measure, archives created by one user cannot
be read by another user, unless the archive information file is copied
from the backup user's directory to the restore user's directory.
Thus, if you want to make a backup and don't want others to be able to
restore it, set your permissions on the archive information file as
rw------- (which _t_a_p_e_r does by default). Note that this is not
completely foolproof, since a restorer can run _r_e_c_r_e_a_t_e _i_n_f_o _f_i_l_e_s and
create the information file and then access the archive. It is more a
deterrent rather than secure system.

The second problem with both tar and cpio was that using the floppy
interface tape drive, you could not append files. The only way to
append files was using a combination of tar and mt - a very clumsy and
time consuming method of backing up.

Note that the archive device doesn't have to be a tape drive - it can
be an ordinary file on a filesystem, or a floppy, or in fact, any file
that the Linux can write to.

Each archive is given a unique archive ID (which is actually the
system time that the archive was created). This is used to identify
it.

Development of this system has been done using gcc and based on a
Colorado Jumbo 250 drive using the ftape driver (v3.03). As I do not
have access to any other tape drives, I don't know if it will work on
other setups. If you have any problems, contact me an I'll see if I
can help.

The main program is called _t_a_p_e_r.

Note that currently _t_a_p_e_r is not really designed for backing up more
than about 30,000 files (unless you have a large amount of physical
memory).

44.. RReeqquuiirreemmeennttss

+o ncurses library >= v1.9.6 with the forms library

+o kernel >= v1.2.5 (I think it will work for lesser versions but I
have not tested it) - Your kernel must have SYS_V_IPC support
enabled if you wish to take advantage of the triple buffering
system.

+o gcc >= 2.6.1

55.. UUnnppaacckkiinngg aanndd CCoommppiilliinngg

Unpack the source file distribution by issuing the following command:

tar xzf taper-7.0pre-1.tar.gz

Modify Makefile.common as required and then

make clean
make all

TTRRIIPPLLEE__BBUUFFFFEERR
Enable this option if you wish to take advantage of _t_a_p_e_r's new
triple buffering system. You must compile your kernel with
SYSV_IPC support. If you haven't, can't or don't want to, then
you can't use triple buffering. If you don't enable
TRIPLE_BUFFER, then your error counts in restore will be
invalid.

On slow drives, triple buffering can really improve performance
however, on faster drives, can slow down performance. The best
thing to do is to compile with triple buffering and look at your
performance. If it is slow, then recompile with triple buffering
off.

I consider a fast drive to be one that delivers a throughput of
more than 8mB/minute.

TTAAPPEERR__BBIIGG__EENNDDIIAANN
_T_a_p_e_r stores all data to the tape in little endian format. To
use _t_a_p_e_r on a big endian machine, define TAPER_BIG_ENDIAN.

FFIIFFOO__PPRROOBBLLEEMMSS
If you are using libc5, and are getting strange errors about
"Broken Pipes", segmentation faults etc.., uncomment this option

55..11.. FFiillee llooccaattiioonnss

To place the binaries and the man page in the appropriate locations,

make install

The binaries are placed in /sbin and the man page is /usr/man/cat1
which is in accordance with the Linux FSSTND.

To remove the files

make uninstall

55..22.. MMooddiiffyyiinngg ddeeffaauullttss..hh

For the hackers, there are a few options at the beginning of
_d_e_f_a_u_l_t_s_._h that you can alter if you wish. They include things such as
the environment variable names, internal defaults, and compression
program. Don't play around unless you know what you are doing.

66.. TTeerrmmiinnoollooggyy

An archive refers to all the files on a tape. A volume is the files
that are written to in one backup session. Thus, if you make one
backup to a tape, then it will have one volume. If you then append
files to this tape, it will have two volumes. If you append again, it
will have three volumes.

For all intents & purposes, volumes are transparent to the user. When
selecting files to restore, all the files on all the volumes are
presented in alphabetical order (not volume order).

77.. TTaappee DDeevviicceess

This program requires a device driver for the tape drive. For users of
the floppy controller type (eg. Jumbo), there are now two drivers
available.

The original one was _f_t_a_p_e and was written by Bas Laarhoven and, at
the time of writing this, is currently at version 2.11a. It is
available from sunsite.unc.edu. It should be in
_/_p_u_b_/_L_i_n_u_x_/_k_e_r_n_e_l_/_t_a_p_e_s. At the time of writing, it was still in
_/_p_u_b_/_L_i_n_u_x_/_I_n_c_o_m_i_n_g.

A new driver, _z_f_t_a_p_e, was written by Claus-Justus Heine, and is found
at ftp://sunsite.unc.edu/pub/Linux/kernel/tapes/zftape-1.06.tar.gz.
It uses the basic _f_t_a_p_e code, however, it contains many enhancements
over _f_t_a_p_e including support for compression and a true seekable
device. The latest version at time of writing was 1.06a. You must
use version 1.02 or later.

However, Claus-Justus Heine has taken over maintaining both _f_t_a_p_e and
_z_f_t_a_p_e. His latest project is to integrate the code of _f_t_a_p_e and
_z_f_t_a_p_e into one source, which is has called _f_t_a_p_e and have version
numbers >= 3. That is, _f_t_a_p_e_-_3_._x_x and above is actually a combination
of the old _z_f_t_a_p_e and _f_t_a_p_e. The moral of the story is... iiff yyoouu aarree
uussiinngg _f_t_a_p_e vveerrssiioonn >>== 33,, yyoouu ccaann tteellll _t_a_p_e_r tthhaatt yyoouu aarree uussiinngg _z_f_t_a_p_e
ssiinnccee vveerrssiioonn 33 aanndd aabboovvee hhaass aallll tthhee ffuunnccttiioonnaalliittyy ooff tthhee oolldd _z_f_t_a_p_e.
If you are using the _f_t_a_p_e version 3 or above, for the purposes of
this documentation, assume that you are using _z_f_t_a_p_e.

Claus has a home page http://samuel.math.rwth-
aachen.de/~LBFM/claus/ftape where the latest _f_t_a_p_e and _z_f_t_a_p_e can be
obtained.

Two devices are needed - a rewinding device - when using this device,
the tape drive is automatically rewound when closed, and a non-
rewinding device - when using this device, the tape drive is not
rewound when closed but left where is. The names of these devices
depend on whether you are using a SCSI drive, _f_t_a_p_e or _z_f_t_a_p_e.
Alternatively, you can change the names in the global preferences
menu, via the preference file, from the environment, or via the
command line.

It is important that both a rewinding and a non-rewinding device is
given.

When making an archive as a file on a hard disk, the filename should
be given for both the rewinding and non-rewinding device. To make
things easier, you can use the -b command line option or the BOTH
preference.

88.. TTaappee ddrriivveess

88..11.. ffttaappee

_f_t_a_p_e is the original floppy tape driver for Linux and now supports a
wide variety of floppy tape drives and a few enhanced controllers. In
the later development kernels, _f_t_a_p_e is part of the kernel source
tree. It is still available separately for those running older
kernels. I am not referring to _f_t_a_p_e version 3 or above in this
section. If you are using _f_t_a_p_e version >= 3, for the purposes of this
documentation, you should assume that you are using _z_f_t_a_p_e.

Start _t_a_p_e_r with the --TT ffttaappee option.

The device names are /dev/ftape (which should point to /dev/rft0) for
the rewinding device, and /dev/nftape (which should point to
/dev/nrft0) for the non-rewinding device. These are the values that
_t_a_p_e_r uses as defaults; if your devices are different, modify the
values using the environment variables, preferences file, or command
line (see below).

If you are still using _f_t_a_p_e, I would strongly suggest that you update
to _z_f_t_a_p_e which is basically _f_t_a_p_e with quite a few enhancements which
should drastically improve _t_a_p_e_r performance. If you have multiple
volume backups made under _f_t_a_p_e, however, you should not upgrade
because you will not be able to access volumes other than 1 using
_z_f_t_a_p_e.

88..22.. zzffttaappee

This section also applies to those people using _f_t_a_p_e version >= 3.

Start _t_a_p_e_r with the --TT zzffttaappee option.

This driver supports several modes - one is the generic _f_t_a_p_e mode.
The second is a QIC compliant mode (zftape) and the third is a
compressed QIC compliant mode (czftape). It is possible to access
archives made with _f_t_a_p_e using the generic mode (see below), however,
if you make a backup using the QIC compliant mode (zftape), then you
cannot use this if you decide to go back to _f_t_a_p_e. As this is rarely
done, and because the QIC compliant mode is so superior to the generic
mode, I would recommend that you use it.

Backups made under _f_t_a_p_e will work with _z_f_t_a_p_e if you:

1. Make sure that you use the device names _/_d_e_v_/_f_t_a_p_e and _/_d_e_v_/_n_f_t_a_p_e.
You will have to change this manually under Global preferences

2. You only restore files from the first volume. It is not possible to
restore files from other volumes. This is because _z_f_t_a_p_e does not
support the fsf ioctl for _f_t_a_p_e drives. I am currently
corresponding with Claus to see if we can resolve this problem.

3. Do not try and append data to an archive created with _f_t_a_p_e using
_z_f_t_a_p_e

4. You change the _s_e_t_-_b_l_k_s_i_z_e & _g_e_t_-_b_l_k_s_i_z_e preferences to yes and
change the _b_l_o_c_k_-_s_i_z_e to 10K.

If you have multiple volume backups, then you had best use _f_t_a_p_e
until you fully migrate all your backups to _z_f_t_a_p_e.

Do not try and make backups with the generic driver of _z_f_t_a_p_e and then
go back to _f_t_a_p_e and hope that it will work - it won't!

Under _t_a_p_e_r, the biggest advantage of _z_t_a_p_e is the ability to quickly
fast forward through archives. You should notice quite a difference,
especially when doing a _m_k_i_n_f_o and when restoring from multiple
volumes. Although _z_f_t_a_p_e has support for compression, you are better
off letting _t_a_p_e_r compress since _t_a_p_e_r buffers a bit better and has
the option of using _g_z_i_p which is more efficient than the algorithm
used by _z_f_t_a_p_e.

The devices for this driver should be created using

make mknod

in the Makefile that comes with the driver. Note that the permissions
will be set up so that only root has write access to the tape drive.
You will have to change this manually if you want to allow other users
access.

The device names are /dev/qft0 for the rewinding device and /dev/nqf0
for the non-rewinding device.

If you make a backup with _f_t_a_p_e version >= 3, you cannot restore with
_z_f_t_a_p_e.

88..33.. SSCCSSII DDrriivveess

Start _t_a_p_e_r with the --TT ssccssii option.

Unfortunately, I do not have a SCSI drive and therefore am unable to
test _t_a_p_e_r code with SCSIs. I rely on SCSI users sending me
information about how _t_a_p_e_r works for them and then I try and use that
information to help other SCSI users who are having problems. The
following information was sent to me by AP Harris
(apharris@onShore.com) and I've included it to help SCSI users.
The SCSI rewinding device is /dev/st0 (or /dev/st1 on the 2nd tape
drive) and the non-rewinding device is /dev/nst0. You'll probably
have to prepare all your tapes using _m_k_t_a_p_e from the _u_t_i_l_i_e_s menu.

If you are using a SCSI tape device, make sure you've complied the
kernel with SCSI (CONFIG_SCSI) support, SCSI tape support
(CONFIG_CHR_DEV_ST) and, of course, support for your SCSI host
adapter. If all is well, when you boot, you should see a message like
this (your details may vary):

Detected scsi tape st0 at scsi0, id 4, lun 0
scsi : detected 1 SCSI tape 1 SCSI disk total.

No additional drivers are needed (although the st-aware mt is nice).

The block size (-x option below) should be set below the tape device
driver buffer size (which can be changed at kernel compile time in the
kernel and defaults at 32K).

SCSI tapes generally do not need formatting - see below for full
details.

88..44.. IIDDEE ttaappee ddrriivveess

Start _t_a_p_e_r with the --TT iiddee option.

The default device names are /dev/ht0 and /dev/nht0. Support for IDE
drives is in alpha stage and I would encourage users to give me
feedback on how _t_a_p_e_r is working with their IDE drives

88..55.. FFllooppppiieess aanndd ootthheerr rreemmoovvaabbllee mmeeddiiaa

Start _t_a_p_e_r with the --TT rreemmoovvaabbllee option.

When the floppy (or whatever) is full, _t_a_p_e_r will prompt you for the
next floppy/tape. This works in exactly the same way as multiple tape
backups. The default device names are set to /dev/fd0 - ie. the first
floppy drive.

If you are using a ZIP drive, then make sure that the whole disk has
been partitioned as a Linux native partition then start _t_a_p_e_r:

taper -T removable -b /dev/sda1

Substitute /dev/sda1 with the device name of your ZIP drive. Note:
Your ZIP drive must have oonnee partition only since _t_a_p_e_r ignores the
partition table.

99.. QQuuiicckk ffaasstt ffoorrwwaarrddss

Some tape drives are capable of doing quick fast forwards. A quick
fast forward means that the tape drive is able to find the start of
the next volume even when in the middle of the previous volume. Drives
based on _f_t_a_p_e are _N_O_T capable of doing this, however, _z_f_t_a_p_e, is able
to do quick fast forwards, as are most SCSI drives.

With _f_t_a_p_e, therefore, the only way to find the next volume is to
rewind the tape to the beginning, and then forward to the desired
volume. As you can imagine, this constant rewinding and forwarding can
take quite a while.

By default, _t_a_p_e_r assumes that zftape, SCSIs and IDE tape drives can
do a quick fast forward, while removable and ftape tape drives cannot.

To test whether your drive can do quick fast forwards, go into the
_u_t_i_l_i_e_s menu and run the _T_e_s_t _f_a_s_t _f_s_f program which will tell you if
your drive supports quick fast forwards or not. Note that _t_a_p_e_r will
overwrite all the data on the tape used for the test.

If you find that your tape drive doesn't support quick fast forwards,
you will have to change the appropriate preference.

1100.. CCaann sseeeekk

Some tape drives support a seek ioctl which allows positioning of the
tape drive at a particular block. This makes restore a lot quicker,
since _t_a_p_e_r can calculate which block a file(s) lies on an advance
straight to that block.

By default, _t_a_p_e_r assumes that zftape, and SCSI drives support this
ioctl while removable,ftape and IDE don't.

You can test if your tape drive supports seek by running the _T_e_s_t _c_a_n
_s_e_e_k utility and changing the appropriate preference.

1111.. FFoorrmmaattttiinngg aanndd EErraassiinngg TTaappeess

Like floppy disks, there are two steps in the preparation of new
tapes:

1. low level format

2. preparing for use with Linux/_t_a_p_e_r

People with floppy tape drives need to do both. At present, there is
no program available to low level format a tape, and thus, you will
have to rely on DOS/WIN/OS-2 programs to do so. If you are planning on
using _t_a_p_e_r, then you do not need to worry about step 2, since _t_a_p_e_r
will take care of that for you. If you are not going to be using _t_a_p_e_r
on that particular tape, then you will need to do a _m_t _e_r_a_s_e. Note
that if you buy pre-formatted tapes (which I'd STRONGLY recommend
since formatting can take 2-3 hours), then you by-pass step 1 ONLY -
you still have to prepare the tape for Linux.

People with SCSI drives (esp DAT) may not need to format tapes for use
under Linux. See your tape drive documentation for details.
Similarly, you may not need to do step 2. Those drives that do not
require step 2 may still require some information to be written on the
tape before they will work correctly under _t_a_p_e_r, therefore, run
_m_k_t_a_p_e from the _u_t_i_l_t_i_e_s menu before running tape. You can use the
_t_e_s_t _m_a_k_e _t_a_p_e option from the _u_t_i_l_i_t_i_e_s menu to see if your tape
drive needs to have _m_k_t_a_p_e run on new tapes. It is important that you
put a brand new tape in the tape drive when testing.

STOP PRESS: The new _f_t_a_p_e drivers (versions greater than or equal to
3.03) do not require tapes to be erased, however, the older ones do.
Therefore, if you use the new _f_t_a_p_e driver, you can set this
preference OFF.

In addition, the new _f_t_a_p_e driver can format tapes but it still takes
time - save yourself a headache - buy preformatted tapes.

_-_-_e_r_a_s_e_-_t_a_p_e_-_o_f_f to tell _t_a_p_e_r that your tape doesn't need erasing.
This is the default behaviour if you have started _t_a_p_e_r with _-_-_t_a_p_e_-
_t_y_p_e _s_c_s_i.

1122.. //pprroocc FFiilleessyysstteemm

Under Linux, it is possible to have a /proc filesystem. This directory
doesn't contain files, but rather contains information about all the
running processes and environment information. Its purpose is to allow
programmers to obtain information about the current state of the
machine (eg. the ps program). Because it contains run-time
information, we obviously don't want to back it up.

_t_a_p_e_r has an option of trying to detect the /proc system and ignoring
it when doing the backup. Normally, the /proc system is on device
number 1. If your /proc system is on another device, then you can tell
_t_a_p_e_r this with the -j (--proc-device) option, or preference.

If you are not sure what device your /proc is mounted on, then run the
program _w_h_i_c_h___d_e_v_i_c_e which is in the _u_t_i_l_i_t_i_e_s menu. Give the name
/proc (or whatever name your /proc is) and _t_a_p_e_r will tell you the
device your /proc is mounted on.

Before using _t_a_p_e_r, it is a good idea to confirm that your /proc is on
device 1 and if it isn't change the appropriate preference.

1133.. CCoommpprreessssiioonn

There are several compression methods available.

EExxtteerrnnaall ccoommpprreessssiioonn -- ttyyppee 11
This method calls an external compression program to do the
compression. The default is set to _g_z_i_p but can be changed in
the _d_e_f_a_u_l_t_s_._h file at compile time. The compression program is
expected to read the file from standard input and write the
compressed output to standard output. If your compression
program doesn't do this, you will have to modify the _t_a_p_e_r
sources.

IInntteerrnnaall ccoommpprreessssiioonn -- ttyyppee 22
This is a very good compression method - it is very fast and
reasonably good at compression. Because of this, it is the
default compression method. The only problem is that is uses an
extra 2MB of memory which can degrade system performance on
heavily loaded machines.

IInntteerrnnaall ggzziipp -- ttyyppee 33
This method is basically the gzip compression method, however,
the source has been hacked around to accommodate _t_a_p_e_r. The
advantage of using this over the eexxtteerrnnaall ccoommpprreessssiioonn method is
that it is a bit quicker because it is internal, however, it is
still a very slow compression method. The other disadvantage is
that although the compression method is that of _g_z_i_p, it doesn't
produce compressed files that can be read by _g_z_i_p. You need
_t_a_p_e_r to read the archives.

In summary then:

+o Memory use, type 2 > type 3 > type 1.

+o Speed, type 2 > type 3 > type 1.

+o Compression ratio, type 3 > type 1 > type 2.

You should use compression 2 unless you have a very heavily loaded
system or less than 4MB of RAM.

If _t_a_p_e_r is still too memory hungry for you, try the following:

+o Turn off triple buffering

+o In ddeeffaauullttss..hh, reduce the size of DEFAULT_TR_SIZE

+o Don't use use ccoommpprreessss--ttyyppee set at 2 because this is a very memory
hungry compression (but also the quickest of the lot). CCoommpprreessss--
ttyyppee set at 3 is a good alternative.

+o In ddeeffaauullttss..hh, change the line

#define COMPRESS2_BUFFER_SIZE 1000000

to:

#define COMPRESS2_BUFFER_SIZE 1

You will not be able to use ccoommpprreessss--ttyyppee 22, but if memory is a prob-
lem, you shouldn't be using this anyway.

+o In ddeeffaauullttss..hh, add the following line:

#define MAXNAMLEN 125

This assumes that the maximum filename length you have is 125 charac-
ters. If this is not the case, change it to match your system.

1144.. RRuunnnniinngg TTaappeerr

To start _t_a_p_e_r, type _t_a_p_e_r at the command line. You will be presented
with a menu from which you select the appropriate option. To move
between options, press the up or down arrow (or left & right). To
select and option, press the ENTER key.

_t_a_p_e_r accepts the following command line options. Note that there are
two formats for options - short (one letter) and long (GNU style).
Either one (or a mixture of both) can be used. Alternatively, options
can be stored in a preference file (see below for details).
1144..11.. CCoommmmaanndd lliinnee ooppttiioonnss

----ttaappee--ttyyppee ((--TT))
which tape drive you are using. There are three valid options

((ss))ccssii
scsi drive

((ff))ttaappee
ftape based tape drive

((zz))ffttaappee
zftape based tape drive (or ftape version >= 3)

((ii))ddee
ide based tape drive

ffii((ll))ee
a regular file on the hard disk

((rr))eemmoovvaabbllee
a device that needs mounting, eg. floppy disk

This option mmuusstt be specified. NB: Only the bracketed letter of
the option is required.

----hheellpp ((--??))
prints help on command line options

----aappppeenndd--oonn ((++aa))
Append files to archive if it exists. DDeeffaauulltt.

----aappppeenndd--ooffff ((--aa))
Overwrites existing archive if found.

NOTE: The append options are only for unattended backups. If you
use the main _t_a_p_e_r program, you will be prompted for whether you
wish to append or overwrite an existing archive.

----aarrcchhiivvee--ddiiffff ((--AA)) aarrcchhiivvee__iidd
Prints differences between the archive and filesystem. If
archive_id equals 0, then the tape that is in the tape drive is
used, otherwise, uses archive_id.

----sseett--oowwnneerrsshhiipp--oonn ((++BB))
After restoring a file, restore the ownership attributes of the
file

----sseett--oowwnneerrsshhiipp--ooffff ((--BB))
Don't attempt to set the ownership attributes of a file after
restore

----ttaappee--nnaammee ffiillee ((--ff)) ffiillee
use file as the rewinding archive file. If not specified, will
use the file specified in the environment variable TAPE. You can
use a networked format like ttaarr (eg. myhost.com:/dev/tape to use
the tape drive on myhost.com).

----nnttaappee--nnaammee ffiillee ((--nn)) ffiillee
use file as the non-rewinding archive file. If not specified,
will use the file specified in the environment variable NTAPE.
You can use a networked format like ttaarr (eg.
myhost.com:/dev/tape to use the tape drive on myhost.com).

----bbootthh--ddeevviicceess ffiillee ((--bb)) ffiillee
equivalent to -n file -f file useful when not using tape drives,
but archive files. You can use a networked format like ttaarr (eg.
myhost.com:/dev/tape to use the tape drive on myhost.com).

----eexxcclluuddee--ffiilleess ffiillee ((--FF)) ffiillee
a list of files not to include in the backup. Consists of a
series of suffixes to exclude separated by spaces. It is not
case sensitive (ie. .o is the same as .O) For example, the
ddeeffaauulltt setting of ".o ~" excludes all files that end in .o and
all files that end in ~ .

----bbaadd--cchheecckkssuumm--oonn ((++CC))
When doing a mkinfo or complete restore, if a file with a bad
checksum is encountered, you will have the option of trying to
continue, or assuming the rest of the backup is bad and fudging
the info file to reflect this. DDeeffaauulltt.

----bbaadd--cchheecckkssuumm--ooffff ((--CC))
When doing a mkinfo or complete restore, if a file with a bad
checksum is encountered, will try to continue without prompting.

----ccoommpprreessss--ttyyppee ((--cc)) nnuumm

00 No compression

11 Use an external compression program. The program to use is
hard compiled and can be changed by editing _d_e_f_a_u_l_t_s_._h. The
ddeeffaauulltt is set to use _g_z_i_p.

22 Use the internal compression program which is similar to
_c_o_m_p_r_e_s_s. It doesn't provide as good a compression as _g_z_i_p
but it is much quicker. Note that this compression uses about
2MB of RAM extra so on heavily loaded machines, it can
degrade performance. _D_e_f_a_u_l_t.

33 Use the internal compression program which is similar to
_g_z_i_p. It provides the same level of compression as _g_z_i_p and
is much quicker than the external version. It is not as
quick as option 2, but much faster than 1. In addition, it
doesn't use anywhere near the memory or system load that _2
requires.

----eexxcclluuddee--ccoommpprreessss ((--XX)) ffiillee
Specifies which group of files to exclude from compressing.
Comprises a string of suffixes separated by a space - eg. ``.gz
.gif'' would exclude files ending in .gz and .gif. It is not
case sensitive (ie. JPG = jPg etc..) DDeeffaauulltt is ``.gz .gif .Z
.zip .jpg .bmp''

_g_z_i_p is used for compression. It assumes that gzip is on your
path. If you use another compress program, change the entry in
_d_e_f_a_u_l_t_s_._h and recompile.

----pprriinntt--ddiirr ((--dd)) aarrcchhiivvee__iidd
Prints the directory of the archive whose id is archive_id and
exits. If archive_id equals 0, then the directory of the archive
of the tape currently in the drive is printed.

----aauuttoo--ddeesscceenndd--oonn ((++DD))
If this option is on, in restore, if there are any empty
directories, they will automatically be skipped. For example,
your files may be in /usr/local/src/xzy with nothing in /usr,
/usr/local or /usr/local/src. When you select /usr from the top
restore directory, you will automatically be placed in to
/usr/local/src/xyz where the files are, and the empty
directories will be skipped. DDeeffaauulltt.

----aauuttoo--ddeesscceenndd--ooffff ((--DD))
Turn the above off.

----pprroommpptt--aarrcchhiivvee--oonn ((++ee))
When selecting restore, prints a list of all known archives and
the user can select which one of these to restore from. DDeeffaauulltt.

----pprroommpptt--aarrcchhiivvee--ooffff ((--ee))
When selecting restore, automatically selects the archive in the
tape drive (or regular file). User not given the option of which
archive s/he would like to restore from

----ccaann--sseeeekk--oonn ((++EE))
Tells _t_a_p_e_r that your tape drive supports a seek ioctl for
positioning to a particular block. Default depends on tape drive
type.

----ccaann--sseeeekk--ooffff ((--EE))
You tape drive doesn't support an ioctl for positioning to a
particular block. _T_a_p_e_r will use reads to position. Default
depends on tape drive type.

----vvoolluummee--ttiittllee ((--gg)) ttiittllee
Title of volume. DDeeffaauulltt is NULL. Only applicable in backup.

----ggeett--bblloocckkssiizzee--oonn ((++GG))
If this option is defined, then after _t_a_p_e_r opens a tape, it
tries to get the block size using an ioctl call. This is only
for the new _z_f_t_a_p_e driver. DDeeffaauulltt is on for _z_f_t_a_p_e and off for
others.

----ggeett--bblloocckkssiizzee--ooffff ((--GG))
Do not try and get the block size.

----ssoofftt--lliinnkkss--ooffff ((--hh))
With soft links, store link details only and not linked file.
DDeeffaauulltt.

----ssoofftt--lliinnkkss--oonn ((++hh))
With soft links, store the file, not the link.

----ccoommpp--hheeaadd--ssttaarrtt ((++HH)) mmiinnuutteess
It is useful for _t_a_p_e_r to always have a full buffer of data
available to send to the tape drive so that the tape drive never
has to sit and wait. This can be a problem if compression is
taking a long time. By giving the compression program a head
start, you can try and ensure that _t_a_p_e_r always has data
available to write. A good starting number for large backups is
10 minutes. _D_e_f_a_u_l_t _i_s _0.

----iinnffoo--ffiilleess ppaatthh ((--ii)) ppaatthh
directory where archive information files are saved. Also where
file sets are saved. DDeeffaauulltt ~/taper_info).

----ccoommpprreessss--iinnffoo--oonn ((++II))
turns on compression of info files. Automatically will compress
&after creation and will decompress when required. DDeeffaauulltt.

----ccoommpprreessss--iinnffoo--ooffff ((--II))
Don't compress info files.

----pprroocc--ddeevviiccee ((--jj)) nnuumm
This specifies the device number of the /proc system. This is
avoid backing up of the /proc filesystem which is a runtime
filesystem used to store the current state of the operating
system. If this value is set to 0, then no checking is
performed. The ddeeffaauulltt value is 1 (which is the device number of
the /proc filesystem under Linux).

----mmiinn--bbeeffoorree--sseeeekk ((--JJ)) nnuumm
When restoring, if the tape needs to be advanced by less than
_m_i_n_-_b_e_f_o_r_e_-_s_e_e_k blocks, then a seek will not be issued, rather
the tape will continue streaming. This is because if you have a
lot of files close together, it's more efficient to just let the
drive continue streaming. DDeeffaauulltt 1100.

----eerraassee--ttaappee--oonn ((++kk))
When using a new tape, overwriting a tape with unrecognized
data, or when overwriting existing _t_a_p_e_r files, if this option
is set, _t_a_p_e_r will try and erase the tape using a standard ioctl
call. Floppy tape drives (those based on _f_t_a_p_e and _z_f_t_a_p_e
require this option to be set.

----eerraassee--ttaappee--ooffff ((--kk))
Will not try to erase a tape before writing new data to it.
Most SCSI drives do not require erasing, so you can use this
option for them.

----iilllleeggaall--eenndd--ooff--ttaappee--ooffff ((--KK))
Tells _t_a_p_e_r that your tape drive correctly handles the end of
tape condition. Use the utility tteesstt eenndd ooff ttaappee to see if your
tape drive handles this properly. DDeeffaauulltt.

----iilllleeggaall--eenndd--ooff--ttaappee--oonn ((++KK))
Tells _t_a_p_e_r that your tape drive doesn't handle the end of tape
condition as per BSD semantics. Use the utility tteesstt eenndd ooff ttaappee
to see if your tape drive handles this properly.

When _t_a_p_e_r encounters an error in the tape, it asks you whether
this signifies an end of tape or a real error.

----lloogg--ffiillee ((--ll)) ffiillee
name of log file. DDeeffaauulltt ~/taper_log.

----lloogg--lleevveell ((--mm)) nnuummbbeerr
logging level (0 = no logging..4 = all). DDeeffaauulltt = 2.

----ssiizzee--ddiirrss--oonn ((++MM))
When you select a directory in backup, it will calculate the
directory size. This may take a while for big directories.
DDeeffaauulltt.

----ssiizzee--ddiirrss--ooffff ((--MM))
No sizing of directories on selection. Quicker, but no
indication of size of backup being contemplated.

----lliimmiitt--lloogg--ffiillee ((--LL)) nnuummbbeerr
specifies how many megabytes the log file should be at a
maximum. If, after a _t_a_p_e_r operation, the log file is found to
exceed this size, enough bytes are removed from the BEGINNING of
the file to ensure the log file becomes _n_u_m_b_e_r megabytes long.
If this is 0, then no checking is done and the log file will
continue to grow indefinitely. DDeeffaauulltt iiss 22.

----oovveerrwwrriittee ((--oo)) nnuumm
level of overwrite

00 -- nnoo oovveerrwwrriittee..
If the file exists on the hard disk, then it is not
overwritten

11 -- mmoorree rreecceenntt oovveerrwwrriittee.. DDeeffaauulltt.
If the file exists on the hard disk, it is only overwritten
if the file on the backup device is more recent

22 -- uunnccoonnddiittiioonnaall oovveerrwwrriittee..
The file on the hard disk is always overwritten

----ttaappee--oovveerrwwrriittee--oonn ((++OO))
When doing unattended backups, if a tape contains unrecognized
data, then if this option is set, then the tape is automatically
overwritten.

----ttaappee--oovveerrwwrriittee--ooffff ((--OO))
When doing unattended backups, if a tape contains unrecognized
data, then the tape is not overwritten - the backup is aborted
and a message is mailed to the user. DDeeffaauulltt.

----pprreeffeerreennccee--ffiillee ((--pp)) ffiillee
Name of preference file

----ttmmpp--ddiirr ((--PP)) ddiirr
Specifies the directory where temporary files are to be placed.
DDeeffaauulltt is /usr/tmp.
----oonnllyy--vvoolluummee ((--qq)) nnuumm
Tells restore/backup to only show only volume 'num' in its
window. DDeeffaauulltt is 0 which means show all volumes.

----ffaasstt--ffssff--oonn ((++QQ))
Quick fast forwards are enabled. See the section of Quick fast
forwards for more details. DDeeffaauulltt iiss oonn ffoorr _z_f_t_a_p_e aanndd _S_C_S_I
aanndd ooffff ffoorr _f_t_a_p_e.

----ffaasstt--ffssff--ooffff ((--QQ))
Disable quick fast forwards.

----rreellaattiivvee--ppaatthh ((--rr)) ppaatthh
directory to restore to. Note that the directory structure of
the backup is preserved

----eexxcclluuddee--ddiirrss ((--RR)) ppaatthh
which directories to automatically exclude from the backup
process. The string consists of a list of space separated
directories. Note that the selection is recursive. For example,
if you exclude list was "/tmp", the contents of /tmp will not be
backed up. Also, none of the directories in /tmp (eg. /tmp/junk)
will be backed up. Users of netscape may also want to put their
cache directory on the exclude list ( /.netscape/cache) since
this is where netscape stores its list of recently visited
locations and is a waste to backup. DDeeffaauulltt iiss ""tmp /usr/tmp
/var/tmp"/.

----ssttrriipp--nnuummbbeerr ((--ss)) nnuummbbeerr
remove number leading pathnames. When backing up, the full
pathname is stored in the information file (and on the tape).
You have the option of removing number leading paths when
restoring. For example, if the file backed up was
/home/yusuf/taper/README, by specifying -s 2, the file will
appear in the restore menu as taper/README. If -s1 was
specified, the file will appear as yusuf/taper/README.

If there are more strips than paths (eg. specifying -s 6 in the
above example), then the filename only is used (eg. README).

The value -s 99 is a special value and tells restore to work out
the optimum number of strips based on common leading paths

The ddeeffaauulltt is -s 99 (ie. auto strip).

----sseett--bblloocckkssiizzee--oonn ((++SS))
If this option is defined, then before _t_a_p_e_r erase a tape, it
tries to set the block size using an ioctl call. This is mainly
for the new _z_f_t_a_p_e driver, but some SCSI drives need it.
DDeeffaauulltt is on for _z_f_t_a_p_e and off for others.

----sseett--bblloocckkssiizzee--ooffff ((--SS))
Do not try and set the block size before erasing a tape. Before
any tape manipulation, it tries to set the block size using an
ioctl call first. Also, before erasing a tape, it sets the block
size.

----aarrcchhiivvee--ttiittllee ((--tt)) ttiittllee
Title of archive. DDeeffaauulltt is NULL. Only applicable when archive
is being created for the first time. If supplied when doing an
archive append, then it is ignored.
----iinnccrreemmeennttaall--oonn ((++uu))
When doing a backup, only backup those files selected which are
more recent than the files that are on the backup archive.
DDeeffaauulltt.

----iinnccrreemmeennttaall--ooffff ((--uu))
When doing a backup, backup all files selected. This option can
be overriden when selecting files for backup.

----uunnaatttteennddeedd--ffiillee ((--UU)) ffiillee
Gives the name of a file/directory to be backed up in unattended
mode. If the filename begins with a _@, then it is taken to be
the name of a file set, otherwise, it is a file. If the first
letter of the filename is a '!', then the file is excluded
rather than selected. You can use as many -U as you like on the
command line.

----rreecceenntt--rreessttoorree--oonn ((++ww))
When doing a restore, restore the most recent file with the
given filename. For example, if /etc/hosts has been backed up
twice in different volumes, restore the file which is newer.
DDeeffaauulltt.

----rreecceenntt--rreessttoorree--ooffff ((--ww))
When doing a restore, restore the file that was selected - for
example, if you selected /etc/hosts in volume 1, this if the
file that will be restored, even if there is an /etc/hosts in
volume 2 which is more recent. This option can be overriden
when selected files for restoration.

----oolldd--aarrcchhiivvee--ooffff ((--WW))
Using an archive created by taper version 5.6 or later. DDeeffaauulltt.

----oolldd--aarrcchhiivvee--oonn ((++WW))
Using an archive created by a version less than 5.6.

----vveerrssiioonn ((--vv))
prints version being used. Also prints the options _t_a_p_e_r was
compiled with

----uunnaatttteennddeedd--iidd ((--VV))
when appending to a backup in unattended mode, if this value is
not -1, then _t_a_p_e_r will check that the tape in the drive belongs
to this archive ID before appending. If another archive is in
the drive, then the backup will not be made. DDeeffaauulltt iiss --11.

----bblloocckk--ssiizzee ((--xx)) nnuumm
The size of a block. Apart from the tape header, data is
transferred to the tape device in blocks of 'num' size. The
ddeeffaauulltt is 28K. If you use a SCSI, see then note above. Num is
in bytes. Note that this value MUST NOT exceed the size of
DOUBLE_BUFFER in ddeeffaauullttss..hh.

----uussee--eeoomm--oonn ((++yy))
Uses the ioctl eom to position to end of tape rather than fsf.

----uussee--eeoomm--ooffff ((--yy))
Uses multiple fsf to position to end of tape. DDeeffaauulltt.

----mmiinn--ffrreeee ((--YY)) nnuumm
Specifies the minimum amount of free disk space that must exist
before a file is compressed. num is in kilobytes. DDeeffaauulltt iiss
44009966KK.

----pprroommpptt--ddiirrss--oonn ((++zz))
Turns on confirmation when selecting directories for backing up.
DDeeffaauulltt.

----pprroommpptt--ddiirrss--ooffff ((--zz))
Turns off confirmation when selecting directories for backing up

----ttaappee--ssiizzee ((--ZZ)) ssiizzee
Tells _t_a_p_e_r the size of your tapes in megabytes. This must be
the _u_n_c_o_m_p_r_e_s_s_e_d size. Note that you must specify the same
number every time you start _t_a_p_e_r. See notes on multiple tape
backups for more details. If this value is 0, then _t_a_p_e_r auto-
detects the end of tape. DDeeffaauulltt iiss 00 ((aauuttoo--ddeetteecctt)).

1144..22.. BBaacckkuupp MMoodduullee

Select the backup option from the _t_a_p_e_r menu.

Four windows are displayed:

The top left represents the file system (hard disk) and you can move
it using the arrow keys. To enter a directory, press ENTER when the
highlight is on that directory. To include a file/directory in the
backup, press 's'. Selecting a directory will select all the files in
the directory recursively. To unselect a file/directory, press 'u'. If
the file is only selected because it's directory is selected (eg. if
you select /usr/john, then /usr/john/prefs is indirectly selected),
then you must exclude the file/directory. Pressing 'e' will exclude
the file/subdirectory from the backup. Pressing 'd' will show details
about the file the highlight is on. Pressing 'j' will allow you to
jump to a particular directory.

The top right window shows what is currently on the archive. You can
use the arrow keys to move the display up/down. If the entry is in
brackets, this means that this is an exclusion. If there is previous
archive, you can move the arrow keys down to a file/directory and
press 's' to select this entry.

The bottom left window shows the files that you have selected for
backup. To unselect a file that you have selected for backing up,
move the highlight to the file you wish to remove from the backup set
and then press 'u'.

The bottom right window shows the files that you have excluded from
the backup. If there is a '*' on the left of the entry, that means
that this entry will cause some files to be excluded. If there is no
'*', then none of the selections intersect with this exclusion.

Pressing TAB moves between the windows. Pressing 'h' will display a
help screen. Pressing 'f' will finish selection and commence backup
Pressing 'q' will abort backup

You can abort a backup by pressing q or Q while the backup is being
made. This will cleanly stop backing up.

1144..22..11.. BBaacckkuupp mmooddeess

There are two modes for backup - full and incremental. The default
incremental mode (which can be changed by changing the options, the
preference file or command line). In incremental mode, when you select
a file for backing up, _t_a_p_e_r looks at what is on the archive already.
If the file you have selected for backup is more recent (or doesn't
exist on the archive) than the one on the archive, it is backed up: if
the file you have selected for backup is the same or older than the
one on the archive, it is not backed up. For directories, _t_a_p_e_r checks
each file in the directory recursively. To see if a file will be
backed up, look at it's size in the selection (bottom) window - if it
is zero, it means that _t_a_p_e_r will not back up that file.

In full mode, _t_a_p_e_r backups the file regardless of what's on the
archive.

The backup mode can be changed for each file selection. Move the
highlight in the selection window to the file you wish to change and
then press 's'. To the left of the filename is an 'I' if the file is
to be saved as incremental, or 'F' if it is full.

1144..33.. RReessttoorree

Select the restore option from the _t_a_p_e_r menu. If you have selected
the 'prompt archives' option (default), then _t_a_p_e_r prints a list of
all the archives it knows about and lets you select which one you
would like to work with. The highlight will be automatically position
on the archive that is in the tape drive (or which the regular file
pertains to). Press ENTER to accept the archive or use the arrow keys
to move around to select another archive. If the prompt archive option
is not set, you will not be presented with this screen. Note that you
are not allowed to change directories - ie. allowed to access other
people's archives.

Three windows are displayed:

The top left window shows details of what is currently on the archive.
You can move around using the arrow keys. To enter a directory, press
ENTER when the highlight is on that directory. To select a
file/directory for restoration, press 's'. Selecting a directory will
select all the files in the directory recursively. Pressing 'd' will
show details about the file the highlight is on. Pressing 'j' will
allow you to jump to a particular directory.

The top right window shows how the archive was constructed (ie. what
files/directories were selected for inclusion in the archive). An
entry in brackets indicates that this was an exclusion. You can use
the arrow keys to move the display up/down. You can press 's' when you
are on a file or directory to select that particular file/directory.

The bottom window shows the files that you have selected for
restoration. To unselect a file that you have selected for
restoration up, move the highlight to the file you wish to remove from
the restore set and then press 'u'.

Pressing TAB moves between the windows. Pressing 'h' will display a
help screen. Pressing 'f' will finish selection and commence backup
Pressing 'q' will abort backup

While the restore is in progress, you can stop it by pressing q or Q.

1144..33..11.. RReessttoorree mmooddeess

1144..33..11..11.. FFuullll rreessttoorree

If _t_a_p_e_r cannot find an info file for the tape in the drive, then it
offers you the option of doing a full restore. In full restore mode,
all files on the archive are restored in all volumes. There is no
pathname processing, so the full path is used relative to either the
current directory, or the --restore-path option.

1144..33..11..22.. MMoosstt rreecceenntt vvoolluummee rreessttoorree

This comes in useful when you have backed up the same file several
times (eg. as it has changed) and is the default mode. When you select
a file for restoration, _t_a_p_e_r automatically selects the file which is
on the latest volume (eg. you may have three volumes and /etc/passwd
is on each. Even if you select the /etc/passwd in volume 1, _t_a_p_e_r will
automatically select the volume 3 file, not the volume 1 file). This
is indicated by an 'M' in the volume column of the selection window.
Note that even if you are in a restricted volume view (using --only-
vol), most recent restore will still automatically find the latest
volume of your file on the archive.

1144..33..11..33.. FFiixxeedd vvoolluummee rreessttoorree

In fixed volume mode, whichever file you select is the one that is
restored (eg. in the example above, the /etc/passwd on volume 1 would
be restored, despite the fact that the /etc/passwd on volume 3 is more
recent).

To toggle between fixed volume & most recent mode for a particular
file selection, press 's' when on the selected file in the selection
window.

1144..44.. RReeccrreeaattee iinnffoo ffiillee

Select the recreate info file option from the _t_a_p_e_r menu.

This recreates archive information files given an archive. It also
checks that the checksums of all the files are valid. Any errors are
printed to the log file.

Basically, it looks for an archive on the devices given. It prints the
archive ID and archive title on the screen, then prints each file as
it passes it while recreating the archive information file in the
directory specified. Because it has to traverse the whole archive, it
does take some time to recreate the information file.

As it is traversing, _m_k_i_n_f_o checks the checksums of the files on the
archives and writes any errors to the log file. Thus, you can check
the integrity of your archives with _m_k_i_n_f_o.

If _t_a_p_e_r encounters a bad checksum, you have the option of trying to
continue the _m_k_i_n_f_o or you can tell _t_a_p_e_r to assume that this is the
end of the backup. This is useful if a backup got killed by a power
failure or something.

During the traverse, you can press q or Q to stop it. If you do that,
you will corrupt your info file and you will have to re-run _m_k_i_n_f_o to
restore your info file.

_M_k_i_n_f_o may return errors when trying to advance to volumes that do not
exist. Do not worry about this - just select abort and the info file
will be correctly constructed.

1144..55.. VVeerriiffyy aarrcchhiivvee

This option goes through an archive and checks that what's on the
archive matches what is on the hard disk, byte by byte. If a file is
on the archive but not on the disk, it is ignored. Any discrepancies
are printed to the log file. It also checks the checksums and if a bad
checksum is encountered, like _m_k_i_n_f_o, you have the option of trying to
continue or to assume that the rest of the backup is bad.

1144..66.. UUttiilliittiieess

1144..66..11.. MMaakkee ttaappee

This prepares a tape for use by _t_a_p_e_r. This is not needed by _z_f_t_a_p_e or
_f_t_a_p_e tape drives. Some SCSI drives need this.

1144..66..22.. TTeesstt mmaakkee ttaappee

This tests whether your tape drive needs to have _m_a_k_e _t_a_p_e run on new
tapes. It is important that a BRAND NEW tape is used when running this
test - ie. one that has never seen the inside of your (or anyone
else's) tape drive before.

1144..66..33.. WWhhiicchh pprroocc

Tells you on which device your /proc filesystem is mounted. Type in
the name of your /proc directory (usually /proc) and then _t_a_p_e_r will
give you a device number. This is then fed to _t_a_p_e_r using the --proc-
device (or -J) option. The default is 1.

1144..66..44.. TTeesstt ffaasstt ffssff

Some tape drives can quickly advance between volumes on the tape. This
also quicker restoration of files from multiple volumes. Use this
utility to see if your tape drive can use fast fsf.

1144..66..55.. TTeesstt ccaann sseeeekk

_T_a_p_e_r can use the seek ioctl to make seeking for files in restore a
lot quicker. Basically, the block on which the file should lie is
calculated and then a seek is issued to quickly advance the tape drive
to this block. However, your tape drive must support the seek ioctl
for this to happen.

You can use this utility to check if your tape drive supports the seek
ioctl.

Before using _t_e_s_t _c_a_n _s_e_e_k you must ensure that you have the correct
setting for _t_e_s_t _f_a_s_t _f_s_f.

1144..66..66.. TTeesstt eenndd ooff ttaappee

According to BSD semantics, when a program requests a further read
from a tape when at the end of the tape, it should return either a 0
error or a -1 error with errno set at ENODATA or ENOSPC.

Some tape drives do not do this, but return an I/O error which means
that _t_a_p_e_r doesn't know whether an end of tape is reached or a true
I/O error is encountered.

Therefore, this utility will check to see if your tape drive handles
the end of tape condition legally. If it does, well and good.

If it doesn't, taper assumes that I/O errors are really end of tapes.
The problem, of course, is that we don't know when true I/O errors
occur. There is no solution to this problem other than finding a
compliant tape drive.

1144..66..77.. EErraassee vvoolluummeess

Lets you erase that last `n' volumes on an archive. Tell _t_a_p_e_r the
number of volumes you wish to delete. _T_a_p_e_r then deletes these
volumes. Note that once a volume is deleted, it cannot be restored.

1144..66..88.. RReeiinnddeexx iinnffoo ffiillee

To speed up access, the info file cluster contains a couple of index
files. These files are arranged as m-tree indexes. Occasionally, these
index files can get corrupted. If you think this has happened, you can
reindex the files.

Also, if you want to restore your files onto a different machine, and
do not want to recreate the info files on that machine, you can take a
copy of the info files to the new machine. Rather than taking all four
of them, you can take the two main files, and rebuild the indexes
using this option, on the new machine.

1144..66..99.. LLooookk ffoorr rreeccuurrssiivvee lliinnkkss

It is possible on some systems that you have recursive links. For
example, you may have a soft link that points to "./". This leads to a
recursive situation which does not matter if you do not follow links.

If you follow links (via the soft-links option), then _t_a_p_e_r will crash
as it encounters this link. Running this utility identifies any
recursive links you may have so that you can either tell _t_a_p_e_r not to
use hard links, or so you can remove the offending link.

Just enter the starting directory you wish to test - _t_a_p_e_r will look
for recursive links and tell you if you have any. In some situations,
_t_a_p_e_r will seg fault at the link. This is not a problem since you will
know where the offending link is by when it seg faults.

1144..66..1100.. AAtttteemmpptt RReeccoovveerryy

If you have an archive that is corrupted, you can try to tell _t_a_p_e_r to
start recovery at a point beyond the corruption. The hardest thing is
to try an get _t_a_p_e_r back in sync at a point beyond the corruption.

An archive looks like:

tape header
volume header

file header ) repeated for each file
file ) in the archive

Once a corruption occurs, you have to find the file header of the
first file beyond the corruption and tell _t_a_p_e_r where it is and then
_t_a_p_e_r can continue to recover files.

In this utility, you tell _t_a_p_e_r where you want to start the restore
(in bytes relative to the beginning of the archive). _T_a_p_e_r will then
print the filename and file header for confirmation. If you get
garbage here, then you are not positioned on the file header and you
must continue trying until you are.

Once you are correctly positioned, say YES and _t_a_p_e_r will try and
recover files beyond the corruption point.

The easiest way to find the correct position is to use an editor such
as _m_i_d_n_i_g_h_t _c_o_m_m_a_n_d_e_r to scan the file until you can locate the
correct location.

If you are using a tape drive (especially on a volume other than the
first), it is a good idea to read the tape data into a disk file using
dddd and then work with the file, rather than the tape. It is just
quicker.

If you are trying to recover data from a volume other than the first
one, you must position the tape (using the non-rewinding device) on
the volume you wish to recover from, read the tape data into a disk
file and then work on this disk file.

When you are working with the disk file, start _t_a_p_e_r using the --TT ll
preference.

1155.. UUnnaatttteennddeedd BBaacckkuupp

It is possible to get _t_a_p_e_r to do unattended backups. This can be used
to run _t_a_p_e_r regularly through, say, _c_r_o_n. Three additional
preferences become important:
----aappppeenndd
If a _t_a_p_e_r archive exists on the tape, then if --append-on, the
files will be appended to the archive. If --append-off, then the
existing archive will be overwritten.

----eerraassee--ttaappee
If unrecognized data exists on the tape, then if --erase-tape-
on, the unrecognized data will be overwritten. If --erase-tape-
off, the data will not be overwritten and the backup session
will be aborted.

----uunnaatttteennddeedd--iidd
If this option is not -1, then _t_a_p_e_r will only append the to
this archive if it is archive "id". If some other archive's tape
is in the drive, the backup will not be made and the user will
be mailed about it.

It is important that these preferences are correctly set, since _t_a_p_e_r
is running in unattended mode, you will not be prompted for any
confirmation, rather the action will just happen.

To specify the files/directories for backup, use the _-_U (or
_-_-_u_n_a_t_t_e_n_d_e_d_-_f_i_l_e) command line options. If the filename begins with a
@, then _t_a_p_e_r interprets this to mean that a filename is a fileset and
reads in the appropriate fileset.

The files/directories are backed up either as full backups or as
incremental backups - it depends on what you have set via command line
options, or preference files. If you haven't specified anything, then
by default, incremental backups are used.

With unattended backups, it is not possible to have multi-tape backups
because _t_a_p_e_r can't prompt you to insert the next tape. If the end of
the tape is encountered, _t_a_p_e_r will stop the backup and send you a
message.

Mail is sent to the root (can be changed in _d_e_f_a_u_l_t_s_._h) via the _m_a_i_l
(can be changed in _d_e_f_a_u_l_t_s_._h) program about what happened during the
backup.

You can use _c_r_o_n to automate your backup process. A line like this:

10 20 * * * taper -U @set

will cause _t_a_p_e_r to run at 20:10 (8.10pm) every day, using the fileset
named _s_e_t.

1166.. FFiillee SSeettss

You may have a particular set of files or directories that you always
wish to backup - eg. /etc/passwd, /usr/local/bin, and /usr/local/etc.
Rather than selecting these files & directories every time you want to
make a backup, you can select them once and then save the particular
selection to a file set. Next time you wish to backup this particular
set of files, you need only load in the file set and _t_a_p_e_r will
automatically select the files for you.

To save a file set, press S in either backup or restore. You will then
be prompted for a name to give to your file set.
To restore a file set, press L in either backup or restore. You will
be presented with a list of known file sets. Select which one you want
using the arrow keys and ENTER and _t_a_p_e_r will load in the file set.

1166..11.. FFiillee SSeett ffoorrmmaatt

A file set file simply is an ASCII file that contains three lines for
each entry selected.

The first line is a capital I or E. II indicates the entry is to be
selected. EE indicates the entry is to be excluded. the selected.

The next line is the selection.

The third line is null (this contains a blank for future support of
regexp).

1177.. EEnnvviirroonnmmeenntt vvaarriiaabblleess

Several _t_a_p_e_r options can be set using environment variables which can
be set from your profile file.

TTAAPPEE__TTYYPPEE
specifies which type of tape drive you have. Valid values are

+o scsi

+o zftape

+o ftape

+o reg-file

+o ide

TTAAPPEERR__PPRREEFFSS
the name of your preference file

TTAAPPEERR__LLOOGG__FFIILLEE
the name of your log file

TTAAPPEERR__LLOOGG__LLEEVVEELL
the level of logging _t_a_p_e_r should do

TTAAPPEERR__IINNFFOO__FFIILLEESS
the directory in which your info files and set files are found

TTAAPPEE
the name of the rewinding tape device

NNTTAAPPEE
the name of the non-rewinding tape device

1188.. PPrreeffeerreenncceess

Rather than having to issue a whole lot of command line options every
time you wish to run backup/restore, it is possible to store commonly
used options in a preference file. Individual users can have their own
preference file in their ~ directory, or there can be a global
preference file in /usr/local/etc. Both backup & restore look for a
preference file in the following sequence:
1. Check if a filename is given via -p (or --preference-file) command
line option

2. Check if a filename is given via environment variable TAPER_PREFS

3. Check if ~/taper_prefs exists. If it does, use this

4. Default of /usr/local/etc/taper_prefs

If no file is given, then internal defaults (as specified above)
are used.

Note that command line options over-ride preference file and internal
default settings.

1188..11.. CChhaannggiinngg pprreeffeerreenncceess

It is possible to change and save preferences within _t_a_p_e_r. Select the
appropriate option from the _t_a_p_e_r menu (ie. either global options,
backup options or restore options). To move between options, press the
up or down arrows (or left and right). To change an option, use the
left and right arrow keys. When you have finished, press F10 (to
change this from F10, change the entry in _d_e_f_a_u_l_t_s_._h).

1188..22.. SSaavviinngg pprreeffeerreenncceess

There are two methods of saving your preferences. One is to a
preference file or, the second is to a command line file. To save to
a preference file, select the appropriate option. Give the filename of
the preference file (default is ~/taper_prefs) and then press F. Next
time you start _t_a_p_e_r, the preferences that you have selected will be
automatically loaded.

The second method of saving is to a command line file. The saves the
preferences you have selected to a shell script. Select the name of
the shell script (default is start_taper). To invoke _t_a_p_e_r using the
selected preferences, issue a `sh start_taper'. This is useful if you
have temporary (or multiple) configurations and you don't want to
overwrite your existing preference file.

1188..33.. PPrreeffeerreennccee ffiillee ffoorrmmaatt

The format of a preference file is a text file with one preference per
line. A preference is given:

PREFERENCE=VALUE

See the file 'pref_example' for an example of a preference file.

Spaces are ignored - use quotes if spaces are needed

The name of the preferences are the same as the long command line
option name. For example, to change the log file to _m_y___l_o_g___f_i_l_e, place
the following line in your preference file:

log-file = my_log_file

1188..44.. SSppeecciiaall pprreeffeerreenncceess

The following preferences can be prefixed by a letter to indicate
which tape drive they belong to.

+o set-blksize

+o get-blksize

+o erase-tape

+o fast-fsf

+o block-size

+o tape-name

+o ntape-name

+o can-seek

For example, if you have the following line in your preference file,

block-size = 12300 z-block-size = 43122 z-tape-name = /dev/qft0 z-
ntape-name = /dev/nqft0 s-tape-name = /dev/scsi s-ntape-name =
/dev/nscsi -z

then the block-size is set to 43122 only if the zftape driver is
selected, otherwise, it is set to 12300. Also, the device names are
set to /dev/qft0 & /dev/nqft0 if the zftape driver is selected, or to
/dev/scsi &/dev/nscsi if the scsi driver is selected. If the
preference given is _b_l_o_c_k_-_s_i_z_e_=_4_3_1_2_2, then the block-size will be set
to 43122 regardless of the tape driver selected.

1199.. SSccrreeeenn CCoolloouurrss

It is possible to change the colours displayed. This can be done from
the command line or from within a preference file.

The valid colours are BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN,
WHITE.

For example, to change the normal screen colour to yellow text on a
blue background:

taper --color-normal yellow, blue

from the command line, or

color-normal = yellow,blue

in a preference file.

Below is a list of the possible colors to change

ccoolloorr--ttiittllee
title bar (blue on white)

ccoolloorr--mmaaiinn
main screen (white on blue)

ccoolloorr--ddiiaalloogg
dialog boxes (white on red)

ccoolloorr--ssttaattuuss
status boxes (white on red)

ccoolloorr--ddiirreeccttoorryy
screen used to select files (black on green)

ccoolloorr--sseelleecctteedd
screen used to show selected files (white on blue)

ccoolloorr--sseelleecctteedd
screen used to show unselected files (white on blue)

ccoolloorr--bboottttoomm
status bar at bottom of the screen (blue on white)

ccoolloorr--hheellpp
screen used to show help screen (black on cyan)

ccoolloorr--oonn--vvooll
screen used to show current volume contents (white on purple)

ccoolloorr--ffoorrmm
screen used to get data (eg. change preferences, enter volume
title) (white on black).

2200.. MMuullttiippllee TTaappee BBaacckkuuppss

For the use of multiple tape backups, these are the following
assumptions made.

2200..11.. WWrriittiinngg

End of tape is indicated by one of:

+o error code == -1 && errno == ENOSPC

+o zero bytes written

+o less bytes written than we asked for

2200..22.. RReeaaddiinngg

End of tape is indicated by one of:

+o error code == -1 && errno == ENOSPC

+o error code == -1 && errno == ENODATA

+o returned less bytes than we asked for

End of volume is indicated by

+o zero bytes read

+o error code == -1 && errno == ENODATA

This is what ftape does for floppy controller tape drives. If are
using another sort of tape drive, then the multiple tape backup
feature will only work if the above is true. If it is not true and you
are able to work out what your particular tape drive does, if you send
me details, I will try and incorporate it into future releases. I'm
especially interested in users of SCSI drives since I have no access
to them.

If your tape drive doesn't support the above, you can use the ----ttaappee--
ssiizzee option to tell _t_a_p_e_r the size of your tape drive. Tape size is
specified in megabytes, eg. --tape-size 120 means that your tape is
120MB, --tape-size 250 means that your tape is 250MB. Note that these
must be _u_n_c_o_m_p_r_e_s_s_e_d sizes. You must specify the same number every
time you start _t_a_p_e_r - you can put it in your preference file if
necessary. If you don't specify the same number, you will get very
spurious, unpredictable results. Note that you should subtract about
10% from the manufacturers stated size to account for formatting etc..
(eg. for a 120MB tape, tell _t_a_p_e_r that it is 108MB).

2211.. CCrroossss ppllaattffoorrmm ssuuppppoorrtt

_T_a_p_e_r was primarily designed for linux running on an intel processor.
With linux now becoming very multi-platform, changes have been made to
_t_a_p_e_r to enable cross platform support. Some of the changes are:

+o All data is written to the tape in little endian format. If you
define the TAPER_BIG_ENDIAN makefile option, _t_a_p_e_r will convert
everything read from the tape to big endian so that your machine
can use it. Even if you make a backup from a big endian machine,
the data on the tape will be in little endian format.

+o The info files are also stored in little endian format so that they
should be portable accross different architectures.

+o Data types are defined in _c_o_n_f_i_g_._h. Taper uses 32 bit signed &
unsigned data, unsigned 16 bit, and 8 bit signed & unsigned data.
Change the appropriate types for your machine. Attributes such as
gid_t, uid_t, dev_t, umode_t, and time_t are hard-coded to the
intel defaults of unsigned short (unsigned 16 bit) and long (32
bits) respectively. If your machine uses different types for these,
then you should look at the code in _t_a_p_e_i_o_._c, specifically, the
functions tape_read_fi and tape_write_fi and modify it to convert
the intel types to a type applicable for your machine. If your
machine uses longer data types than an unsigned 16 bit used by
intel linux, then, for the time being, you are in strife. In a
future _t_a_p_e_r version, I intend to move away from the 16 bit format
and use my own representation. However this will mean that existing
archives are incompatible with the new format, so I won't be doing
this for a while.

+o Since version 6.3, _t_a_p_e_r aligns all structures on addresses that
are divisable by 4. It does this by padding out the strings so that
they have a length divisable by 4. Then an offset is added (which
is the number of bytes that the structure needs to make it a length
of a multiple of 4). Versions less than 6.3 do not support this, so
it is unlikely that these archives will work on machines that
require aligned addresses. However, for machines that do not
require aligned access, there is no problem.
+o Look at ccoonnffiigg..hh which has a couple of defines you may need to
change.

2222.. LLiimmiittaattiioonnss

Maximum length of total pathname is set by MAXNAMLEN. It is usually
set to 255 bytes long. If you have a very long pathname, then you may
cause _t_a_p_e_r to segfault.

If a file grows while _t_a_p_e_r is trying to back it up, only the
beginning part of the file is backed up (specifically, the number of
bytes the file was when _t_a_p_e_r started to back up this file) and the
rest is lost. This is because of inadequate mandatory file locking. I
know that this is being worked in the kernel and hopefully, when the
kernel code pertaining to this is stable, I can implement it in _t_a_p_e_r.

2233.. BBuuggss

Please report bugs to me at the address below. If the bug causes a
segment violation or causes the program to crash in any other way, if
you know how to use gdb, could you re-compile your source using the
Makefile.debug makefile, and tell me what source line the program
crashed. Also, please tell me what kernel version, gcc version, C
library version, ncurses version you are using.

As this is a sideline, I may not be able to respond to e-mail
immediately. However, if you do not receive a reply within one week,
then repost as I may have forgotten about it!

2244.. MMaajjoorr bbuuggss iinn eeaarrllyy vveerrssiioonnss

There was a bug in taper-5.1.1 when creating archives. If you made an
archive with 5.1.1, unfortunately, you will have to re-backup if you
find that restore doesn't work since it was a pretty major bug.
However, since taper-5.1.1 was only released a day before 5.1.2 (which
fixed the bug) was released, hopefully, not too many people are
affected.

From taper-5.0 to taper-5.1.3, there was another not so serious bug.
This caused the file counts on the archives to be incorrect in
certain, obscure situations. You will know if you have this bug
because you will find that you have funny files on your restore
screen, and some files and directories will be missing altogether.
There is no way to correct the errors on the archive other than re-
backing up, however 5.1.4 (and later) have a `fudge factor' which will
allow to your to use your archives normally. Just run _m_k_i_n_f_o on your
archive and taper will recognize the buggy archive and fudge your info
file automatically for you.

I don't believe it - the bug crept back into 5.1.5 - it's like a virus
that won't go away! Anyway, 5.2 corrects it.

In versions 5.6 to 6.1 (inclusive), there was an obscure backup bug
which causes a problem if there were two buffers queued for output
when the tape drive was closed. Unfortunately, there is no fix for
this, however, it is a relatively rare bug, and at most, you will lose
the last two blocks of the backup. This bug only occurred if you used
triple buffering.

In versions up to 6.1.3, there was a problem with internal compression
of files > 32K. It was a spurious bug.

2255.. FFiinnaallllyy

Wow! You made it through all the 'documentation'! I'm impressed.

I would appreciate a short message if you find the program useful and
are using it. This will allow me to work out whether people are using
it and whether to continue development. If you could also state what
machine you are using, hard drive/floppy controllers, tape drive type,
SCSI card etc.., then this will help me to maintain a compatibility
list.

Happy backing up,

Yusuf Nagree

yusuf@nagree.net

19MAY02