f6757cd0e8fc8f5072a20bc523d7e6c689b90ee7
[openafs.git] / 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.