$Id$ This is the README for dumptool, a program to interactively restore AFS volume dump files. INTRODUCTION Dumptool arose out of a need here at NRL to perform maintenance of MR-AFS (Multi-Resident AFS) volumes. After it was written, we found that it worked great on standard AFS volumes as well, and relatively few changes were required to make it compile with a standard AFS installation. Dumptool provides an interface similar to the interactive Unix restore; given a dump file, a user can navigate through the filesystem inside the dump using familiar commands such as "cd" and "ls". Also provided is a "cp" command to copy individual files out of the dump into a normal filesystem space. This eliminates the need to restore an entire volume just to retrieve a single file. Dumptool was written at the Naval Research Laboratory by Ken Hornstein . The latest and greatest version of dumptool can always be found in the AFS contrib directory at: /afs/transarc.com/public/afs-contrib/dumptool/ INSTALLATION & OPERATION The standard Makefile target will build a dumptool for a vanilla AFS installation. The "mrafs" target will build a dumptool that can operate on MR-AFS dumps. In either case, you may need to change some of the Makefile variables to reflect your site; see the Makefile for more information. Once dumptool is built successfully, you can run it on any AFS dump file. Without any additional arguments, dumptool will scan the dump file, build indexes of all listed vnodes, and present a prompt (">") that accepts the following commands: ls Lists files in the current directory. Filename globbing (e.g., wildcards such as * ?) are supported via the system fnmatch() function. Accepts the following flags: -l Generates a "long" listing, similar to the -l switch for the Unix ls. Displays Unix mode mask, owner, group, and file size. -i Displays volume, vnode, and uniquifier for each matching file in the format volume.vnode.uniquifier. Note that the volume displayed is that of the _parent_ volume, which in the case of a backup volume is the _original_ volume from which it was generated. -F Append / to filenames for directories, @ for symlinks, and * for files which have the execute bits set. -R Recurse through all subdirectories. cd Change the current directory cp Copy a file from the dump. Note that globbing is NOT supported, and you must give a filename (the Unix idiom of just giving a destination directory for the second argument to cp will NOT work). vcp Copy a file from the dump, by the vnode. The first argument is the vnode number, optionally followed by the uniquifier. E.g: vcp 126278 /tmp/file1 vcp 126278.43289 /tmp/file2 quit Exits dumptool. exit ADDITIONAL OPTIONS TO DUMPTOOL Dumptool supports a number of command-line options. They are detailed below: -v Verbose mode. Output additional information during dump processing. Each -v will increase output. -f Force dump processing. Attempt to continue processing a dump even when some errors are detected. Not completely tested. -i Inode dump. Dump a list of all files in the volume, with their volume/vnode/uniquifier information. SUPPORT FOR MR-AFS Dumptool also supports the extra information in MR-AFS dumps, and provides some extra commands/options for dealing with MR-AFS dumps: Additional command line options: -d Dump all residency filenames in the dump file to standard output. -t Residency tag information. Allows a user to specify the tag of a residency if the rsserver is not available. Format of option is Residency/Tag -r Residency filesystem information. Allows a user to specify the residency filesystem information if dumptool is not run on the same host as the residency in the dump. Format of option is Residency/Type/Size/Algorithm. Additional commands: file Displays to standard output the residency filename of a given dump filename. All residencies available are shown. CAVEATS The user interface needs some work. "ls" doesn't support nearly as many options as the standard Unix one. "cp" also doesn't have all of the features found in common Unix variants. Right now two passes are done through the dump file to scan all vnodes. With some clever work this could be sped up somewhat and changed to only do a single scan. MODIFYING DUMPTOOL I welcome changes to dumptool, but I have some guidelines. First, I DEMAND that the changes be sent in context diff format. I prefer unidiff (diff -u), but standard context diffs are okay. It's extremely difficult to deal with new code in any other way. If the changes you want to do require some significant rearchitecturing, it might be a good idea to contact me first. That way we can coordinate the modifications in a meaningful way (I might have made changes since the last released version). If you're making MR-AFS specific changes, please follow the example I've set and protect them with #ifdef RESIDENCY. And please ... follow my code style, okay? I always try to follow whatever wacky code style I find in source code that I modify, and I think it's only polite for you to do the same. CONTACT INFORMATION As always, please send comments, suggestions, or new features to me, Ken Hornstein . Share and enjoy.