---------- Install-guide -- An installation guide ----------

Written by Bas Laarhoven (sjl) & Kai Harrekilde-Petersen.
Last update: 30/12/94 by sjl, for ftape v2.00


WHAT YOU NEED:
==============

1)  the floppy tape driver distribution file `ftape-1.20.tar.gz'
    (this file is a part of it).

2)  the kernel sources for Linux 0.99pl14t or later. If you know
    what you're doing you can use the driver with older kernel
    versions, but you have to hack the ftape and modules support
    in the kernel yourself!

3)  modules utilities: `modutils-0.99.14.tar.gz' (or later).
    [Note that the old ones still work even if you get a warning
    saying you're using an old insmod and no symbols will be
    inserted !]

4)  tools like `mt' and `tar' to use the driver (these can be
    found in the gnu cpio package).

(Of course, you also need a tape drive installed and the appropriate
tools to compile the sources)


INSTALLATION STEPS:
===================

  If it's the first time you install ftape, you'll want to start
with these steps, otherwise proceed with step D.

A)  Compilation of the `modules' utilities.
B)  Creation of the ftape devices.
C)  Installation of syslog[dk] (not necessary, but rather useful).

  Installation of the ftape driver consists of two main steps:

D)  Reconfiguring the kernel for ftape support.
E)  Compilation of the ftape driver proper.
F)  Loading and testing the driver.


  IMPORTANT: The version number of the running kernel must match
the version of the sources in /usr/src/linux when ftape is built !
[You may get all kind of weird errors if they aren't the same.]


Step A) - Compilation of the `modules' utilities:
-------------------------------------------------

[You can skip this step if you have a recent set of modutils ready]

  The modules utilities are in a separate package (see above) that
contains the following three programs: lsmod, insmod and rmmod.
After unpacking the sources in `/usr/src/modules' build these
utilities:

	cd /usr/src/modules ; make

  Test the utils by saying (as root) 'insmod drv_hello.o' This results
in a message like this (if you're running X, you wont see these
messages):

	module `drv_hello' (1 pages @ 0x01023000) created
	initializing module `drv_hello', 140 (0x8c) bytes
	  init entry @ 0x01023034, cleanup entry @ 0x01023074
	drv_hello.c: init_module called
	hello, world

Then do a 'lsmod'. This will result in something like:

	Module:        #pages:
	drv_hello          1

  This means that everything worked out OK.  Now that drv_hello has
served it's purpose, remove it again:

	rmmod drv_hello

  There seems to be a problem with recent tools. If you get the
message `___moddi3 undefined' when loading the module with insmod I
suggest you skip this excercise. It has relation with ftape.

  Install the *mod utilities somewhere handy, eg: in /sbin. [NOTE:
it may NOT be a good idea to install them on a NON-root partition, as
they may be needed in an emergency situation (restore after a system
crash)]

	cp *mod /sbin


Step B) - Creation of the ftape devices:
----------------------------------------

(You can skip this step if you already have these devices)

Check that you have the correct ftape devices:

	ls -lF /dev/*rft*

crw-rw-rw-   1 root      27,   4 Feb 20 13:01 /dev/nrft0
crw-rw-rw-   1 root      27,   5 Feb 20 13:01 /dev/nrft1
crw-rw-rw-   1 root      27,   6 Feb 20 13:01 /dev/nrft2
crw-rw-rw-   1 root      27,   7 Feb 20 13:01 /dev/nrft3
crw-rw-rw-   1 root      27,   0 Feb 20 13:01 /dev/rft0
crw-rw-rw-   1 root      27,   1 Feb 20 13:01 /dev/rft1
crw-rw-rw-   1 root      27,   2 Feb 20 13:01 /dev/rft2
crw-rw-rw-   1 root      27,   3 Feb 20 13:01 /dev/rft3

If not, make them thus:

	mknod -m 666 /dev/rft0 c 27 0
	mknod -m 666 /dev/rft1 c 27 1
	mknod -m 666 /dev/rft2 c 27 2
	mknod -m 666 /dev/rft3 c 27 3
	mknod -m 666 /dev/nrft0 c 27 4
	mknod -m 666 /dev/nrft1 c 27 5
	mknod -m 666 /dev/nrft2 c 27 6
	mknod -m 666 /dev/nrft3 c 27 7

  These are the raw floppy tape devices and non-rewinding raw floppy
tape devices for drive selection methods A:,B:,C: and D:

  People used to the old naming convention may want to set up
some symbolic links once the drive select is known:

lrwxrwxrwx   1 root            9 Feb 20 13:03 /dev/ftape -> /dev/rft0
lrwxrwxrwx   1 root           10 Feb 20 13:03 /dev/nftape -> /dev/nrft0


Step C) - Installation of syslog[dk]:
-------------------------------------

  (This step is optional. Check first to see if syslogd and syslogk are
already running).

  You'll want to capture the messages that ftape issues with syslogk or
syslogd (NET-2 version).  If you don't have a syslog daemon running add
the following to your rc.local file:

        if [ -x /etc/syslogk ] ; then
                syslogk on 2>&1 >>/var/log/kernel &
        fi

  This will append the kernel messages to the file `/var/log/kernel'.
(Make sure this file exists - do `touch /var/log/kernel' as root)


Step D) - Reconfiguring the kernel for ftape support:
-----------------------------------------------------

  If you don't have the proper kernel sources installed, do so now.
The ftape driver needs access to some kernel source-files and searches
the /usr/src/linux path. If you're sources are installed somewhere
else you'll have to patch the driver or set up a symbolic link.

  Since the both the `modules' and `ftape' support are included with
the standard kernel since 0.99pl14t, there is no longer a need for
patching the kernel.

        cd /usr/src/linux ; make config

  Be sure to answer yes to 'QIC-117 tape support', and 3 for the
NR_FTAPE_BUFFERS (unless you know what you're doing!). It is *not*
necessary to include QIC-02 support for proper functioning
(contrary to what has been said on the net).

	make dep ; make clean ; make

  Take a nap, read the newspaper or drink some tea / coffee while the
kernel is being recompiled (this takes about 20 min on a 486DLC/33 box).

  Install the new kernel (keep the old one around, in case you can't
boot with the new one) and reboot.


  Assuming no errors occurred during the compile, we're now ready to
compile the modules utilities.


Step E) - Compilation of the ftape driver proper:
-------------------------------------------------

  [The ftape module (as all modules) will only run with the kernel
version it is compiled for. For ftape this is the kernel version
running when compiling the driver ! This version *must* also match
the sources in the directory /usr/src/linux.]

  Unpack the driver sources and enter the directory where they
reside. Look in the Makefile for options with their descriptions.
If you're using gcc 2.4.5 you'll *NEED* to set GCC_2_4_5_BUG, else
the driver will fail !
  Once all the options are set create the driver by:

	make clean ; make

  If you're using a kernel version 1.1.22 or earlier note that
accessing the floppy drive at the same time as the tape drive will
cause kernel panic. Later versions will prevent this problem: One
cannot access the floppy drive while running ftape and vice versa.


  There is a patch for the gnu version of mt (cpio-2.3) distributed
with the driver. It makes the `mt status' command display usefull
information. You might want to install this but it is not mandatory.


Step F) - Loading and testing the driver:
-----------------------------------------

  As said before, the `ftape.o' module will only run with the kernel
version it's compiled on, if you get an error message saying that
the kernel_version doesn't match the current kernel, remove the file
kernel-version.h (or do a `make clean') and run `make' again. There
should be *NO* warnings. *ALL* compiler warnings / errors should be
investigated and reported.

  You'll need to be root to load the driver with insmod (specify the
full path to insmod if it is not in the standard search path):

        su
	insmod ftape.o

  This results in a similar message as when you installed the
drv_hello.o module.  You'd probably like to catch the messages that
ftape generates with a syslog daemon. Some other configurations may
display them on the active console. See `Step D)' above for more. If
everything went well you got a couple of lines including a copyright
notice and some timing information.

  If you get any messages of the type `multiple definition of symbol
...' or `undefined symbol ...' something is wrong with either kernel
sources or modules utilities. *** The kernel 1.1.0 is broken: get a
later version ! ***

  You have to reload the driver *every* time you boot the system (Just
as with the modules utilities, it's a good idea to have ftape.o on the
root partition. The filesystem standard suggests somewhere under
/boot). Instead of doing it by hand, you could include the following
line in your /etc/rc.local:

	/sbin/insmod /boot/xxx/ftape.o

  Now put a tape in the drive and wait for the drive to stop making
noise (Most tape drives start calibrating the head when a new tape
is loaded.) Now try if the drive is recognized:

	mt -f /dev/rft0 rewind

  This will try to open the device. No tape motion will follow if the
tape is already rewound.
  Because initially `tracing' is set to some value greater than zero,
some debugging output (printk) is generated on the console.

  The messages generated when opening the device can start with some
"timeout on Acknowledge" lines.  This depends on the trace-level, and
is normal as long as the driver is probing for a tape drive.  If they
keep appearing after the device is opened something is wrong.

  If all goes well, messages will appear saying something about
"drive-wakeup method: xxxx" and "tape drive type: yyyy". If not,
"no tape drive found !" says that the driver cannot activate the drive.
In this case you can try the other devices (rft1-rft3). In case they
all fail the driver will not work with your drive.

  If some message appears with "unknown vendor id", follow the
instructions in the message so I can include this information with a
new release.  In the meantime the driver will function correctly if
it is compatible with one of the known types.

  Now it's time to setup the symbolic link to the appropriate device
or otherwise don't forget to substitute the correct device for the
/dev/ftape used below.

  The next test verifies if the drive does respond to some simple
commands:

	mt -f /dev/ftape reten

  The tape should wind completely to the end once and back to the
beginning again. Depending on the tape used this may take a couple
of minutes. If there are no error messages in the log everything is
going fine.

  Now we are going to try to read some data from the tape.
[Make sure a formatted tape is in the drive !]

        mt -f /dev/ftape fsf 0

  This causes the driver to read the header segment and display some
information on the tape in the drive.
`mt' may fail with an I/O error if the tape contains no file marks or
if the operation failed otherwise. Look in the log messages for errors.
This may indicate that you're using the wrong dma channel with an
FC-10 controller or other special configuration.

  Now it's time to try the write operation. Put a formatted tape in
the drive (write protect removed) and initialize the tape for usage
with the ftape driver:

        mt -f /dev/ftape erase

  This command writes a Linux tape label so you can recognize the
tape when using other operating systems, and it clears all file marks
on the tape (No real erasure takes place, all data is still accessible).
This command must be issued before file marks can be written to tape !

  At this point you're ready to use the driver to try a simple backup
of the kernel sources. We'll be using gnu tar to write and verify the
data:

        tar clvf /dev/ftape /usr/src/linux

  You'll see the file names coming by as the data is written to tape.
If the operation succeeds without errors a verification can be done:

        ( cd / ; tar dvf /dev/ftape )

  The data on tape will be compared with the files on disk and any
mismatches will be reported.

  At this point the driver seems to be cooperating with the tape drive
and you'll have to determine the method you'll use to make the
backups. Unix (and therefor Linux) has a lot of tools to do this and
it is a matter of taste which you want to use.
Some of the options are: cpio, tar, dd and dump/restore.

  One final warning: If you are using compression when writing data
to tape (e.g. tar with the `z' option) you may not be able to recover
anything if the tape gets damaged !


A short introduction to file marks:
===================================

  File marks are written to tape to separate individual files (Note
that one `tar' file may contain many data files!). So several
files can be written to tape and individually retrieved.
  The way ftape implements these file marks allows almost random
access to individual files (instead of sequentially reading the
entire tape until ones finds the right file mark).

  Every time the device is closed after writing some data two file
marks are written to tape. If the non-rewinding device is used the
tape is rewound so it is positioned right between these two marks.
  If another file is written to tape the second marks is overwritten
but the first stays causing succeeding files to be separated by
exactly one file mark.

  The following should make this clear: After writing one file to the
non-rewinding tape device the tape layout will be:

        <file-1> <eof> <eof>

  When another file is written the layout will be:

        <file 1> <eof> <file 2> <eof> <eof>


  If we want to add another file to this tape after it has been
rewound, there are to options: First to skip 2 file marks to position
right between the last two marks. In this case we have to know how
many files to skip.
  The other solution is to seek for the double file mark and position
in between. This is done with `mt eom'.
  Remember to use the non-rewinding device when positioning the tape
or it will be rewound when closing !

  Appending a file to a tape:

        mt -f /dev/nftape eom
        tar cvf /dev/ftape <files>

  Reading the first and third files from tape:

        mt -f /dev/ftape rewind
        tar xvf /dev/nftape
        mt -f /dev/nftape fsf 2
        tar xvf /dev/nftape

  The best way to understand what is happening is to picture the tape
layout and count the file marks that have to be skipped.


BTW: Keep in mind that file marks aren't written to tape until the
     header segment is updated. For non-rewinding devices this will
not happen automatically: Make sure that either the last write is to
a rewinding device or issue an `mt rewind' or `mt rewoffl' to flush
the buffers. The last command will put the drive offline until you
reload the cartridge (or the driver). While the drive is offline all
commands will fail.


How to handle Panics or Oops with ftape-2.0 and up:
===================================================

Look in kernel log for 'init_module @ 0xXXXXXXXX' where XXXXXXXX
stands for the address where init_module is loaded.
Now the module offset can be calculated:

        nm ftape.o | grep init_module

results in something like:

        00000110 T _init_module

Subtract this value (00000110 or what it really reads) from the
load address XXXXXXXX and you get the load offset.

When an oops or panic shows look for the value of the program
counter:

        EIP:    0010:YYYYYYYY

You have to subtract the load offset from the EIP value

If you don't know how to subtract hexadecimal :-) make
sure to mention all the above referenced values.

-------------------- end of the Install-guide ----------------------
