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