redhat spec dkms don't strip modules
[openafs.git] / doc / man-pages / pod1 / restorevol.pod
1 =head1 NAME
2
3 restorevol - Restore a volume from vos dump to the local file system
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<restorevol> S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-dir> <I<restore dir>> ] >>>
11     S<<< [B<-extension> <I<name extension>>] >>>
12     S<<< [B<-mountpoint> <I<mount point root>>] >>>
13     S<<< [B<-umask> <I<mode mask>>] >>> [B<-verbose>] [B<-help>]
14
15 =for html
16 </div>
17
18 =head1 DESCRIPTION
19
20 B<restorevol> takes an AFS volume in the format produced by B<vos dump>
21 and restores it to the local file system.  Normally, the contents of a
22 volume are maintained by the AFS File Server in an opaque format and
23 copying a volume's raw data does not make it easily accessible.  This
24 utility will produce a directory tree that is equivalent to that seen via
25 an AFS client, but without preserving the AFS-specific Access Control
26 Lists (ACLs).  It's primary use is to recover data from a volume dump or
27 backup and make it available via a filesystem other than AFS.
28
29 The dump output will read from standard input, or from a file if B<-file>
30 is specified.
31
32 The restore process is as follows:
33
34 =over 4
35
36 =item 1.
37
38 The dump file will be restored within the current directory or that
39 specified with B<-dir>.
40
41 =item 2.
42
43 Within this directory, a subdir is created.  It's name is the RW volume
44 name that was dumped.  An extension can be appended to this directory name
45 with B<-extension>.
46
47 =item 3.
48
49 All mountpoints will appear as symbolic links to the volume name.  The
50 path name to the volume will be either that in B<-mountpoint>, or B<-dir>.
51 Symbolic links remain untouched.
52
53 =item 4.
54
55 You can change your umask during the restore with B<-umask>.  Otherwise,
56 B<restorevol> uses your current umask.  Mode bits for directories are 0777
57 (then AND'ed with the umask).  Mode bits for files are the owner mode bits
58 duplicated accross group and user (then AND'ed with the umask).
59
60 =item 5.
61
62 For restores of full dumps, if a directory says it has a file and the file
63 is not found, then a symbolic link F<< AFSFile-<#> >> will appear in that
64 restored tree.  Restores of incremental dumps remove all these files at
65 the end (expensive because it is a tree search).
66
67 =item 6.
68
69 If a file or directory was found in the dump but found not to be connected
70 to the hierarchical tree, then the file or directory will be connected at
71 the root of the tree as F<< __ORPHANEDIR__.<#> >> or F<<
72 __ORPHANFILE__.<#> >>.
73
74 =item 7.
75
76 ACLs are not restored.
77
78 =back
79
80 =head1 CAUTIONS
81
82 Normally, use L<vos_restore(1)> instead of this command.  B<restorevol> is
83 a tool of last resort to try to extract data from the data structures
84 stored in a volume dumpfile and is not as regularly tested or used as the
85 normal L<vos_restore(1)> implementation.  Using B<restorevol> bypasses
86 checks done by the L<fileserver(8)> and L<salvager(8)>.
87
88 =head1 OPTIONS
89
90 =over 4
91
92 =item B<-file> <I<dump file>>
93
94 Specifies the output file for the dump.  If this option is not given, the
95 volume will be dumped to standard output.
96
97 =item B<-dir> <I<restore dir>>
98
99 Names the directory in which to create the restored filesystem.  The
100 current directory is used by default.  Note that any mountpoints inside
101 the volume will point to the same directory unless the B<-mountpoint>
102 option is also specified.
103
104 =item B<-extension> <I<name extension>>
105
106 By default, the name of the directory created matches the RW volume name
107 of the volume in the dump file.  If this option is used, the directory
108 name will be the RW volume name I<name extension> as the suffix.
109
110 =item B<-mountpoint> <I<mount point root>>
111
112 By default, mountpoints inside the volume being restored point to the
113 value given by I<-dir>.  This option allows mountpoints to be resolved
114 relative to another path.  A common use for this would be to specify a
115 path under F</afs> as the mount point root so that mountpoints inside the
116 restored volume would be resolved via AFS.
117
118 The I<mount point root> must exist, and the process running the command
119 have read access to that directory, or the command will fail.
120
121 =back
122
123 =head1 EXAMPLES
124
125 The following command restores the contents of the dumpfile in
126 F<sample.dump> to the directory F</tmp/sample.2009-05-17>, but having all
127 mountpoints inside the volume point to AFS (note that this requires
128 knowledge of where F<sample> is mounted in AFS):
129
130    % restorevol -file sample.dump -dir /tmp -extension .2009-05-17 \
131        -mountpoint /afs/example.org/sample
132    Restoring volume dump of 'sample' to directory '/tmp/sample.2009-05-17'
133
134 =head1 PRIVILEGE REQUIRED
135
136 The issuer must have read access to the dump file and write access to the
137 directory into which the dump is restored.  If the B<-mountpoint> flag is
138 given, the issuer must also have read access to that directory.
139
140 =head1 SEE ALSO
141
142 L<salvager(8)>,
143 L<voldump(8)>,
144 L<vos_dump(1)>,
145 L<vos_restore(1)>
146
147 =head1 COPYRIGHT
148
149 Copyright 2009 Steven Jenkins <steven@endpoint.com>
150
151 This documentation is covered by the BSD License as written in the
152 doc/LICENSE file. This man page was written by Steven Jenkins for
153 OpenAFS.