src/tests/README.dumptool

   1 $Id$
   2
   3 This is the README for dumptool, a program to interactively restore
   4 AFS volume dump files.
   5
   6
   7 INTRODUCTION
   8
   9 Dumptool arose out of a need here at NRL to perform maintenance of
  10 MR-AFS (Multi-Resident AFS) volumes.  After it was written, we found
  11 that it worked great on standard AFS volumes as well, and relatively
  12 few changes were required to make it compile with a standard AFS
  13 installation.
  14
  15 Dumptool provides an interface similar to the interactive Unix restore;
  16 given a dump file, a user can navigate through the filesystem inside
  17 the dump using familiar commands such as "cd" and "ls".  Also provided
  18 is a "cp" command to copy individual files out of the dump into a
  19 normal filesystem space.  This eliminates the need to restore an
  20 entire volume just to retrieve a single file.
  21
  22 Dumptool was written at the Naval Research Laboratory by Ken Hornstein
  23 <kenh@cmf.nrl.navy.mil>.  The latest and greatest version of dumptool
  24 can always be found in the AFS contrib directory at:
  25
  26 /afs/transarc.com/public/afs-contrib/dumptool/
  27
  28
  29 INSTALLATION & OPERATION
  30
  31 The standard Makefile target will build a dumptool for a vanilla AFS
  32 installation.  The "mrafs" target will build a dumptool that can
  33 operate on MR-AFS dumps.  In either case, you may need to change some
  34 of the Makefile variables to reflect your site; see the Makefile for
  35 more information.
  36
  37 Once dumptool is built successfully, you can run it on any AFS dump
  38 file.  Without any additional arguments, dumptool will scan the dump file,
  39 build indexes of all listed vnodes, and present a prompt (">") that
  40 accepts the following commands:
  41
  42         ls      Lists files in the current directory.  Filename globbing
  43                 (e.g., wildcards such as * ?) are supported via the system
  44                 fnmatch() function.  Accepts the following flags:
  45
  46             -l  Generates a "long" listing, similar to the -l switch for
  47                 the Unix ls.  Displays Unix mode mask, owner, group,
  48                 and file size.
  49             -i  Displays volume, vnode, and uniquifier for each matching
  50                 file in the format volume.vnode.uniquifier.  Note that
  51                 the volume displayed is that of the _parent_ volume,
  52                 which in the case of a backup volume is the _original_
  53                 volume from which it was generated.
  54             -F  Append / to filenames for directories, @ for symlinks,
  55                 and * for files which have the execute bits set.
  56             -R  Recurse through all subdirectories.
  57
  58         cd      Change the current directory
  59
  60         cp      Copy a file from the dump.  Note that globbing is NOT
  61                 supported, and you must give a filename (the Unix
  62                 idiom of just giving a destination directory for the
  63                 second argument to cp will NOT work).
  64
  65         vcp     Copy a file from the dump, by the vnode.  The first
  66                 argument is the vnode number, optionally followed by
  67                 the uniquifier.  E.g:
  68
  69                 vcp 126278 /tmp/file1
  70                 vcp 126278.43289 /tmp/file2
  71
  72         quit    Exits dumptool.
  73         exit
  74
  75
  76 ADDITIONAL OPTIONS TO DUMPTOOL
  77
  78 Dumptool supports a number of command-line options.  They are detailed
  79 below:
  80
  81         -v      Verbose mode.  Output additional information during dump
  82                 processing.  Each -v will increase output.
  83
  84         -f      Force dump processing.  Attempt to continue processing
  85                 a dump even when some errors are detected.  Not completely
  86                 tested.
  87
  88         -i      Inode dump.  Dump a list of all files in the volume,
  89                 with their volume/vnode/uniquifier information.
  90
  91
  92 SUPPORT FOR MR-AFS
  93
  94 Dumptool also supports the extra information in MR-AFS dumps, and
  95 provides some extra commands/options for dealing with MR-AFS dumps:
  96
  97 Additional command line options:
  98
  99         -d      Dump all residency filenames in the dump file to standard
 100                 output.
 101
 102         -t      Residency tag information.  Allows a user to specify the
 103                 tag of a residency if the rsserver is not available.
 104                 Format of option is Residency/Tag
 105
 106         -r      Residency filesystem information.  Allows a user to specify
 107                 the residency filesystem information if dumptool is not
 108                 run on the same host as the residency in the dump.  Format
 109                 of option is Residency/Type/Size/Algorithm.
 110
 111 Additional commands:
 112
 113         file    Displays to standard output the residency filename of a
 114                 given dump filename.  All residencies available are shown.
 115
 116
 117 CAVEATS
 118
 119 The user interface needs some work.  "ls" doesn't support nearly as many
 120 options as the standard Unix one.  "cp" also doesn't have all of the features
 121 found in common Unix variants.
 122
 123 Right now two passes are done through the dump file to scan all vnodes.
 124 With some clever work this could be sped up somewhat and changed to only
 125 do a single scan.
 126
 127
 128 MODIFYING DUMPTOOL
 129
 130 I welcome changes to dumptool, but I have some guidelines.
 131
 132 First, I DEMAND that the changes be sent in context diff format.  I prefer
 133 unidiff (diff -u), but standard context diffs are okay.  It's extremely
 134 difficult to deal with new code in any other way.
 135
 136 If the changes you want to do require some significant
 137 rearchitecturing, it might be a good idea to contact me first.  That
 138 way we can coordinate the modifications in a meaningful way (I might
 139 have made changes since the last released version).
 140
 141 If you're making MR-AFS specific changes, please follow the example
 142 I've set and protect them with #ifdef RESIDENCY.
 143
 144 And please ... follow my code style, okay?  I always try to follow
 145 whatever wacky code style I find in source code that I modify, and I
 146 think it's only polite for you to do the same.
 147
 148
 149 CONTACT INFORMATION
 150
 151 As always, please send comments, suggestions, or new features to me,
 152 Ken Hornstein <kenh@cmf.nrl.navy.mil>.  Share and enjoy.