Taper
  Yusuf Nagree
  Version 6.9b. 02MAR00.
  ____________________________________________________________

  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

  Copyright (C) 1996-2000 by Yusuf Nagree (yusuf@e-survey.net.au)

  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 6.9b.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


     GGLLIIBBCC
        If you are using glibc (aka libc6), this must be set to TRUE





  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@e-survey.net.au
  02MAR00