Instructions for using the April '89 Exabyte dump package.

This software is intended for writing 'dump' and 'tar' dumps of
filesystems or file subtrees.  Unlike the old software, it -
   - works on all the Geometry machines, not just poincare where the drive is
   - lets you use tar (nice for machines lacking 'dump' e.g. the Iris, also for
		backing up less than a full filesystem)
   - keeps human-readable copies of the tape table-of-contents sprinkled
		on the tape itself -- nice if the disk copy is lost.

For component descriptions see src/README.

===============================================================================

Programs are in /u/dump/bin and /u/dump/etc.{cputype}.

All have "Usage" messages -- try   "progname  -X" or other unrecognized
options to see them.
All must be run either as "dump" or "root" .

Most use $TAPE environment variable, set to /dev/nrrt0 by "dump" login.


inittoc     -i
	Initialize a fresh tape.  -i required  (don't destroy accidentally).

gettoc     [-a] [-r]
	Read tape's table-of-contents, set up "./toc" for scripts below.
	Position tape past last file (or -a skip&prepare to append; -r rewind)

localdump  [-n]  {0-9}[u]  /filesys
	Dump a poincare filesystem.  Optionally write toc to tape after dump.
	
remotedump [-n]  hostname  {0-9}[u]  /filesys
	Dump a filesystem elsewhere via rsh host -l dump.  Optionally add toc.

localtar   [-n] [-a] [-G] [-N yy.mm.dd[.hh.mm]]  /dir1 /dir2 -C /dir3 .  ...
	Tar poincare files to tape.  Optionally add toc.
	-a preserve access times, -G write GNU vol header & incremental dir's,
	-N write files touched since date.
	GNU tar does the work, so
	  - device and other special files are backed up;
	  - leading /'s are automatically stripped;
	  - use embedded -C's to chdir in midstream (see gnutar(1)).
	The first /dir1 is automatically converted to
	   "-C /dir ."
	Unfortunately file list options (T and X options) aren't available
	through this script.

remotetar  [-n] [-a] [-G] [-N yy.mm.dd...]   hostname /dir1 ...
	Like localtar but operates on machines other than poincare.

sofar	[tocfile]
	Print amount of data on tape & fraction (of 2.0 GB) used.

dodump
	For regular daily dumps.  Writes ./script, optionally schedules at 4AM.


Related data:

/u/dump/tocdir/yy.mm.dd.hh.mm
	Tocdir contains one file per tape, named by the tape's 'inittoc' time.
	Each one contains one line per file on the tape with the form:
  {host} {dumplevel} {filesystem} {time-of-dump} {bytes-in-dump} dump|tar|toc

	Gettoc locates the appropriate one and links it to `./toc'.



===============================================================================
			Doing dumps

First, log in as "dump" on poincare.  The password is "doadump".

* To initialize a new tape -

	inittoc -i

  The tape must be in the drive and write-enabled.
  It takes a couple of minutes.

* For daily backups -

	dodump

  It checks that there's an initialized tape in the drive (may take a
  minute or so),  then figures what to dump based on the day of week &
  tape status.   Normally -
	Fresh tapes get a level 0 dump of major poincare,
		riemann, klein, quasifuchs and schottky filesystems.
	Other Monday dumps are level 3 of the above Suns and NeXT
		plus files touched in the last week on riemann;
	Other dumps are level 5 of poincare filesystems only.

  You're prompted for a dump level (0/3/5) which defaults to the above.
  You're not prompted for each filesystem, just shown the list chosen
  based on the dump level.

  Dodump writes a "./script" file for the appropriate level and prompts
  for scheduling a dump at 4AM the next morning.  Normally say 'y'.

  If not scheduled, you can edit the dump script, execute it immediately, etc.


  The choice of filesystems is all ad hoc.  Some aren't covered here:
  Poincare's /usr5 and /usr6 are never backed up by dodump.
  These should be covered by special backups done periodically.
  It may be worthwhile including schottky and riemann in daily dumps.

* For special backups -
  It may be easiest to use the lower-level tools.

  First,

	gettoc -a

  to fetch the table-of-contents and position the tape for adding new data.
  You might try

	cat -n toc

  to see what's on this tape (one tape file per line), or

	sofar

  to check the space remaining.  Then use any of the
  {local/remote}{dump/tar} scripts to write data.  For example,

	localtar  /usr5/lamb
  or	localtar  -C /usr5/lamb  movie1  movie2  -C /usr6  stuff/moviedata
  or	remotedump  schottky  0u  /bootdisk/NeXT
  or	remotetar   riemann  /usr


* When changing tapes:

  Press the square button on the lower right front of the drive.
  After a while the tape pops out, you can insert a new one and
  close the door.

  It's a good idea to

	rm toc

  after removing a tape -- this prevents other people from running the
  dump scripts (overwriting whatever tape is in the drive) without first
  re-running gettoc to position it properly.

===============================================================================
			Restoring

To restore, the general scheme is
  0 - get the relevant tape
  1 - get the tape table-of-contents so you can find which file(s) to read
  2 - position the tape to the right file (sometimes restore will do this)
  3 - run 'restore' or 'tar'

0) Finding the right tape, getting the table of contents.

  If the /u/dump directory is available, look at the files in

	/u/dump/tocdir

  It should contain one file per tape.  Each toc file is named by the tape's
  initialization date and time (e.g. 89.04.24.14.20).
  Each file comprises a series of lines, one per tape file, listing machine,
  dump-level, filesystem, dump date, size of dump in bytes, etc.

  If the /u/dump directory isn't at hand (on a lost disk, say),
  just try reading the tape.  Typically every other file will be
  a single 63K-byte record listing the table-of-contents up to that point
  with lots of null padding.  You can look at these with

	dd if=/dev/nrrt0 bs=63k count=1 of=stuff
	tr <stuff | head -1

  If this shows a "Table of contents" line then you've found one; use

	tr <stuff

  to see the complete file.  If not, or to look further, use
	mt fsf 1
  to skip to the next file and repeat.

  Failed dumps will show up as double-EOF marks, so they are not sure signs
  of the end of the tape.  Just keep reading until you get I/O errors.

1) Finding the right file(s) on the tape.
  
  Look in the table-of-contents file for recent dumps of the
  relevant filesystem at each level.  Note the line number.
  "cat -n" is helpful on these -- it prints a number by each line.

  To restore an incrementally-dumped filesystem, you'll need to read
  the most recent dump at each level: first level 0, then the latest level 3,
  then the latest level 5, so note the positions of all of these.

2) If reloading a "tar" dump, you must position the tape now.
  (This is unnecessary with restore which can do its own positioning.)
  Supposing the desired tar is on line {n} of the table-of-contents file, use
	mt rew
	mt fsf {n-1}

  E.g. if it's on line 13, do "mt rew; mt fsf 12".

3) Now to reload a dump, follow the restore man page -- do the usual 'newfs'
   and 'mount' on the target filesystem if doing full restores, and in any case
   cd to the filesystem's root.  Then if restoring a poincare filesystem type

	restore rbfs  126  /dev/nrrt0  {n}	(for a FULL FILESYSTEM restore)
   or
	restore ibfs  126  /dev/nrrt0  {n}	(for an interactive restore)
   or
	restore tvbfs 126  /dev/nrrt0  {n}	(to survey the tape contents)
   or etc.

   where {n} is the table-of-contents line number (really {n}, not {n-1} here).
   You don't need to rewind the tape first, restore handles all positioning.
   When restoring filesystems on other machines, execute the "restore" command
   on that machine but use
		poincare:/dev/nrrt0
   rather than
		/dev/nrrt0
   in the commands above.

4) To reload a "tar" dump, position the tape (step 3),
   cd to the appropriate place (see below) and use

	gnutar  xbfpG 126 /dev/nrrt0	(to restore files)
   or
	gnutar  tvbf  126 /dev/nrrt0	(to survey the tape contents)

   If running the above on a machine other than poincare, use 
   poincare:/dev/nrrt0 rather than /dev/nrrt0 just as with restore.

   The "appropriate place" depends on how the tape was written.
   Check the third field in the table-of-contents line -- it's the complete
   list of directories fed to "{local|remote}tar" separated by ":"'s.

   A dump of /where/ever is written by cd'ing to "/where/ever" and dumping "."
   so to reload, cd to /where/ever first.

   If the original command listed multiple /-relative directories, the
   first is written relative to "." as above, and others
   written relative to / with the leading / removed.  You'll probably
   want to reload such tar's in multiple passes:
	cd /first/dir
	gnutar xbfpG 126 /dev/nrrt0  .
	mt rew; mt fsf {n-1}  (to reposition tape)
	cd /
	gnutar xbfpG 126 /dev/nrrt0  second/dir  third/dir ...

    Tar dumps with leading -C options could be easily reloaded by cd'ing there,
    and so on.  You figure it out.
