3 This is the README for dumptool, a program to interactively restore
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
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.
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:
26 /afs/transarc.com/public/afs-contrib/dumptool/
29 INSTALLATION & OPERATION
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
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:
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:
46 -l Generates a "long" listing, similar to the -l switch for
47 the Unix ls. Displays Unix mode mask, owner, group,
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.
58 cd Change the current directory
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).
65 vcp Copy a file from the dump, by the vnode. The first
66 argument is the vnode number, optionally followed by
70 vcp 126278.43289 /tmp/file2
76 ADDITIONAL OPTIONS TO DUMPTOOL
78 Dumptool supports a number of command-line options. They are detailed
81 -v Verbose mode. Output additional information during dump
82 processing. Each -v will increate output.
84 -f Force dump processing. Attempt to continue processing
85 a dump even when some errors are detected. Not completely
88 -i Inode dump. Dump a list of all files in the volume,
89 with their volume/vnode/uniqifier information.
94 Dumptool also supports the extra information in MR-AFS dumps, and
95 provides some extra commands/options for dealing with MR-AFS dumps:
97 Additional command line options:
99 -d Dump all residency filenames in the dump file to standard
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
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.
113 file Displays to standard output the residency filename of a
114 given dump filename. All residencies available are shown.
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.
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
130 I welcome changes to dumptool, but I have some guidelines.
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.
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).
141 If you're making MR-AFS specific changes, please follow the example
142 I've set and protect them with #ifdef RESIDENCY.
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.
151 As always, please send comments, suggestions, or new features to me,
152 Ken Hornstein <kenh@cmf.nrl.navy.mil>. Shar and enjoy.