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 Copyright (C) 1996 by Yusuf Nagree (yusuf@nagree.net) 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