7640f7883ad780a6172fb6ab86082b65b407b04d
[openafs.git] / doc / man-pages / pod1 / vos_restore.pod
1 =head1 NAME
2
3 vos_restore - Converts an ASCII dump file into an AFS volume
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos restore> S<<< B<-server> <I<machine name>> >>> S<<< B<-partition> <I<partition name>> >>>
11     S<<< B<-name> <I<name of volume to be restored>> >>> S<<< [B<-file> <I<dump file>>] >>>
12     S<<< [B<-id> <I<volume ID>>] >>> S<<< [B<-overwrite> (abort | full | incremental)] >>>
13     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] [-verbose]
14     [B<-help>]
15
16 B<vos res> S<<< B<-s> <I<machine name>> >>> S<<< B<-p> <I<partition name>> >>>
17     S<<< B<-na> <I<name of volume to be restored>> >>> S<<< [B<-f> <I<dump file>>] >>>
18     S<<< [B<-i> <I<volume ID>>] >>> S<<< [B<-o> (a | f | i)] >>> S<<< [B<-c> <I<cell name>>] >>>
19     [B<-no>] [B<-l>] [B<-v>] [B<-h>]
20
21 =for html
22 </div>
23
24 =head1 DESCRIPTION
25
26 The B<vos restore> command converts a volume dump file previously created
27 with the B<vos dump> command from ASCII into the volume format appropriate
28 for the machine type indicated by the B<-server> argument, and restores it
29 as a read/write volume to the partition named by the B<-partition>
30 argument on that machine. The Volume Server assigns the volume name
31 indicated with the B<-name> argument, and resets the volume's creation
32 timestamp to the time at which the restore operation begins (the creation
33 timestamp is stored in the volume header and reported in the C<Creation>
34 field in the output from the B<vos examine> and B<vos listvol> commands.)
35
36 Use the B<-file> argument to name the dump file, or omit the argument to
37 provide the file via the standard input stream, presumably through a
38 pipe. The pipe can be named, which enables interoperation with third-party
39 backup utilities.
40
41 As described in the following list, the command can create a completely
42 new volume or overwrite an existing volume. In all cases, the full dump of
43 the volume must be restored before any incremental dumps. If there are
44 multiple incremental dump files, they must be restored in the order they
45 were created.
46
47 =over 4
48
49 =item *
50
51 To create a new read/write volume, use the B<-name> argument to specify a
52 volume name that does not already exist in the Volume Location Database
53 (VLDB), and the B<-server> and B<-partition> arguments to specify the new
54 volume's site. It is best to omit the B<-id> argument so that the Volume
55 Location (VL) Server allocates a volume ID automatically. Do not include
56 the B<-overwrite> argument, because there is no existing volume to
57 overwrite.
58
59 =item *
60
61 To overwrite an existing volume at its current site, specify its name and
62 site with the B<-name>, B<-server>, and B<-partition> arguments. The
63 volume retains its current volume ID number unless the B<-id> argument is
64 provided. Specify the value C<f> or C<i> for the B<-overwrite> argument to
65 indicate whether the dump file is full or incremental, respectively.
66
67 =item *
68
69 To overwrite an existing volume and move it to a new site, specify its
70 name and the new site with the B<-name>, B<-server>, and B<-partition>
71 arguments. The volume retains its current volume ID number unless the
72 B<-id> argument is provided. The volume is removed from its original
73 site. Specify the value C<f> for the B<-overwrite> argument to indicate
74 that the dump file is a full dump (it is not possible to restore an
75 incremental dump and move the volume at the same time).
76
77 =back
78
79 If the volume named by the B<-name> argument already exists and the
80 B<-overwrite> argument is omitted, the command interpreter produces the
81 following prompt:
82
83    Do you want to do a full/incremental restore or abort? [fia](a):
84
85 Respond by entering one of the following values:
86
87 =over 4
88
89 =item *
90
91 C<f> if restoring a full dump file
92
93 =item *
94
95 C<i> if restoring an incremental dump file
96
97 =item *
98
99 C<a> or Return to cancel the restore operation
100
101 =back
102
103 =head1 CAUTIONS
104
105 If the B<-file> argument is omitted, the issuer must provide all other
106 necessary arguments, because the standard input stream is unavailable for
107 responding to the command interpreter's prompts for missing
108 information. In particular, the issuer must provide the B<-overwrite>
109 argument if overwriting an existing volume.
110
111 =head1 OPTIONS
112
113 =over 4
114
115 =item B<-server> <I<server name>>
116
117 Identifies the file server machine onto which to restore the
118 volume. Provide the machine's IP address or its host name (either fully
119 qualified or using an unambiguous abbreviation). For details, see
120 L<vos(1)>.
121
122 =item B<-partition> <I<partition name>>
123
124 Identifies the partition (on the file server machine specified by the
125 B<-server> argument) onto which to restore the volume. Provide the
126 partition's complete name with preceding slash (for example, F</vicepa>)
127 or use one of the three acceptable abbreviated forms. For details, see
128 L<vos(1)>.
129
130 =item B<-name> <I<name of volume>>
131
132 Specifies the name under which to restore the volume. It can be up to 22
133 characters long, but cannot end with a C<.readonly> or C<.backup>
134 extension. If the volume already exists, it is overwritten subject to the
135 value of the B<-overwrite> argument.
136
137 =item B<-file> <I<dump file>>
138
139 Names the dump file to restore. Incomplete pathnames are interpreted
140 relative to the current working directory. Omit this argument to provide
141 the dump file via the standard input stream.
142
143 =item B<-id> <I<volume ID>>
144
145 Specifies the volume ID number to assign to the restored volume.
146
147 =item B<-overwrite> (a | f | i)
148
149 Specifies which type of dump file is being restored when overwriting an
150 existing volume. Provide one of the following values:
151
152 =over 4
153
154 =item *
155
156 C<a> to terminate the restore operation.
157
158 =item *
159
160 C<f> if restoring a full dump file.
161
162 =item *
163
164 C<i> if restoring an incremental dump file. This value is not acceptable
165 if the B<-server> and B<-partition> arguments do not indicate the volume's
166 current site.
167
168 =back
169
170 This argument is mandatory if the B<-file> argument is not provided.
171
172 =item B<-cell> <I<cell name>>
173
174 Names the cell in which to run the command. Do not combine this argument
175 with the B<-localauth> flag. For more details, see L<vos(1)>.
176
177 =item B<-noauth>
178
179 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
180 combine this flag with the B<-localauth> flag. For more details, see
181 L<vos(1)>.
182
183 =item B<-localauth>
184
185 Constructs a server ticket using a key from the local
186 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
187 to the Volume Server and Volume Location Server during mutual
188 authentication. Do not combine this flag with the B<-cell> argument or
189 B<-noauth> flag. For more details, see L<vos(1)>.
190
191 =item B<-verbose>
192
193 Produces on the standard output stream a detailed trace of the command's
194 execution. If this argument is omitted, only warnings and error messages
195 appear.
196
197 =item B<-help>
198
199 Prints the online help for this command. All other valid options are
200 ignored.
201
202 =back
203
204 =head1 EXAMPLES
205
206 The following command restores the contents of the dump file
207 F</afs/abc.com/common/dumps/terry.dump> to the F</vicepc> partition on the
208 file server machine C<fs3.abc.com>. The restored volume is named
209 C<user.terry>.
210
211    % cd /afs/abc.com/common/dumps
212    % vos restore -file terry.dump -server fs3.abc.com -partition c \
213        -name user.terry
214
215 =head1 PRIVILEGE REQUIRED
216
217 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
218 machine specified with the B<-server> argument and on each database server
219 machine. If the B<-localauth> flag is included, the issuer must instead be
220 logged on to a server machine as the local superuser C<root>.
221
222 =head1 SEE ALSO
223
224 L<restorevol(8)>,
225 L<vos(1)>,
226 L<vos_dump(1)>,
227 L<vos_examine(1)>,
228 L<vos_listvol(1)>
229
230 =head1 COPYRIGHT
231
232 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
233
234 This documentation is covered by the IBM Public License Version 1.0.  It was
235 converted from HTML to POD by software written by Chas Williams and Russ
236 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.