Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | bos_salvage - Restores internal consistency to a file system or volume | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<bos salvage> S<<< B<-server> <I<machine name>> >>> | |
11 | S<<< [B<-partition> <I<salvage partition>>] >>> | |
12 | S<<< [B<-volume> <I<salvage volume number or volume name>>] >>> | |
13 | S<<< [B<-file> <I<salvage log output file>>] >>> [B<-all>] [B<-showlog>] | |
14 | S<<< [B<-parallel> <I<# of max parallel partition salvaging>>] >>> | |
15 | S<<< [B<-tmpdir> <I<directory to place tmp files>>] >>> | |
16 | S<<< [B<-orphans> (ignore | remove | attach)] >>> S<<< [B<-cell> <I<cell name>>] >>> | |
17 | S<<< [B<-forceDAFS>] >>> | |
18 | [B<-noauth>] [B<-localauth>] [B<-help>] | |
19 | ||
20 | B<bos sa> S<<< B<-se> <I<machine name>> >>> S<<< [B<-part> <I<salvage partition>>] >>> | |
21 | S<<< [B<-v> <I<salvage volume number or volume name>>] >>> | |
22 | S<<< [B<-f> <I<salvage log output file>>] >>> [B<-a>] [B<-sh>] | |
23 | [<-para> <I<# of max parallel partition salvaging>>] | |
24 | S<<< [B<-t> <I<directory to place tmp files>>] >>> | |
25 | S<<< [B<-o> (ignore | remove | attach)] >>> S<<< [B<-c> <I<cell name>>] >>> [B<-n>] | |
26 | S<<< [B<-force>] >>> | |
27 | [B<-l>] [B<-h>] | |
28 | ||
29 | =for html | |
30 | </div> | |
31 | ||
32 | =head1 DESCRIPTION | |
33 | ||
34 | The B<bos salvage> command salvages (restores internal consistency to) one | |
35 | or more volumes on the file server machine named by the B<-server> | |
36 | argument. When processing one or more partitions, the command restores | |
37 | consistency to corrupted read/write volumes where possible. For read-only | |
38 | or backup volumes, it inspects only the volume header: | |
39 | ||
40 | =over 4 | |
41 | ||
42 | =item * | |
43 | ||
44 | If the volume header is corrupted, the Salvager removes the volume | |
45 | completely and records the removal in its log file, | |
46 | F</usr/afs/logs/SalvageLog>. Issue the B<vos release> or B<vos backup> | |
47 | command to create the read-only or backup volume again. | |
48 | ||
49 | =item * | |
50 | ||
51 | If the volume header is intact, the Salvager skips the volume (does not | |
52 | check for corruption in the contents). However, if the File Server notices | |
53 | corruption as it initializes, it sometimes refuses to attach the volume or | |
54 | bring it online. In this case, it is simplest to remove the volume by | |
55 | issuing the B<vos remove> or B<vos zap> command. Then issue the B<vos | |
56 | release> or B<vos backup> command to create it again. | |
57 | ||
58 | =back | |
59 | ||
60 | Use the indicated arguments to salvage a specific number of volumes: | |
61 | ||
62 | =over 4 | |
63 | ||
64 | =item * | |
65 | ||
66 | To process all volumes on a file server machine, provide the B<-server> | |
67 | argument and the B<-all> flag. No volumes on the machine are accessible to | |
68 | Cache Managers during the salvage operation, because the BOS Server stops | |
69 | the File Server and Volume Server processes while the Salvager runs. The | |
70 | BOS Server automatically restarts them when the operation completes. | |
71 | ||
72 | =item * | |
73 | ||
74 | To process all volumes on one partition, provide the B<-server> and | |
75 | B<-partition> arguments. As for a salvage of the entire machine, no | |
76 | volumes on the machine are accessible to Cache Managers during the salvage | |
77 | operation. The BOS Server automatically restarts the File Server and | |
78 | Volume Server when the operation completes. | |
79 | ||
80 | =item * | |
81 | ||
82 | To salvage only one read/write volume, combine the B<-server>, | |
83 | B<-partition>, and B<-volume> arguments. Only that volume is inaccessible | |
84 | to Cache Managers, because the BOS Server does not shutdown the File | |
85 | Server and Volume Server processes during the salvage of a single | |
86 | volume. Do not name a read-only or backup volume with the B<-volume> | |
87 | argument. Instead, remove the volume, using the B<vos remove> or B<vos | |
88 | zap> command. Then create a new copy of the volume with the B<vos release> | |
89 | or B<vos backup> command. | |
90 | ||
91 | =back | |
92 | ||
93 | During the salvage of an entire machine or partition, the B<bos status> | |
94 | command reports the C<fs> process's auxiliary status as C<Salvaging file | |
95 | system>. | |
96 | ||
97 | The Salvager always writes a trace to the F</usr/afs/logs/SalvageLog> file | |
98 | on the file server machine where it runs. To record the trace in another | |
99 | file as well (either in AFS or on the local disk of the machine where the | |
100 | B<bos salvage> command is issued), name the file with the B<-file> | |
101 | argument. To display the trace on the standard output stream as it is | |
102 | written to the F</usr/afs/logs/SalvageLog> file, include the B<-showlog> | |
103 | flag. | |
104 | ||
105 | By default, multiple Salvager subprocesses run in parallel: one for each | |
106 | partition up to four, and four subprocesses for four or more | |
107 | partitions. To increase or decrease the number of subprocesses running in | |
108 | parallel, provide a positive integer value for the B<-parallel> argument. | |
109 | ||
110 | If there is more than one server partition on a physical disk, the | |
111 | Salvager by default salvages them serially to avoid the inefficiency of | |
112 | constantly moving the disk head from one partition to another. However, | |
113 | this strategy is often not ideal if the partitions are configured as | |
114 | logical volumes that span multiple disks. To force the Salvager to salvage | |
115 | logical volumes in parallel, provide the string C<all> as the value for | |
116 | the B<-parallel> argument. Provide a positive integer to specify the | |
117 | number of subprocesses to run in parallel (for example, C<-parallel 5all> | |
118 | for five subprocesses), or omit the integer to run up to four | |
119 | subprocesses, depending on the number of logical volumes being salvaged. | |
120 | ||
121 | The Salvager creates temporary files as it runs, by default writing them | |
122 | to the partition it is salvaging. The number of files can be quite large, | |
123 | and if the partition is too full to accommodate them, the Salvager | |
124 | terminates without completing the salvage operation (it always removes the | |
125 | temporary files before exiting). Other Salvager subprocesses running at | |
126 | the same time continue until they finish salvaging all other partitions | |
127 | where there is enough disk space for temporary files. To complete the | |
128 | interrupted salvage, reissue the command against the appropriate | |
129 | partitions, adding the B<-tmpdir> argument to redirect the temporary files | |
130 | to a local disk directory that has enough space. | |
131 | ||
132 | The B<-orphans> argument controls how the Salvager handles orphaned files | |
133 | and directories that it finds on server partitions it is salvaging. An | |
134 | I<orphaned> element is completely inaccessible because it is not | |
135 | referenced by the vnode of any directory that can act as its parent (is | |
136 | higher in the filespace). Orphaned objects occupy space on the server | |
137 | partition, but do not count against the volume's quota. | |
138 | ||
139 | =head1 CAUTIONS | |
140 | ||
141 | Running this command can result in data loss if the Salvager process can | |
142 | repair corruption only by removing the offending data. Consult the | |
143 | I<OpenAFS Administration Guide> for more information. | |
144 | ||
145 | =head1 OPTIONS | |
146 | ||
147 | =over 4 | |
148 | ||
149 | =item B<-server> <I<machine name>> | |
150 | ||
151 | Indicates the file server machine on which to salvage volumes. Identify | |
152 | the machine by IP address or its host name (either fully-qualified or | |
153 | abbreviated unambiguously). For details, see L<bos(8)>. | |
154 | ||
155 | =item B<-partition> <I<salvage partition>> | |
156 | ||
157 | Specifies a single partition on which to salvage all volumes. Provide the | |
158 | complete partition name (for example F</vicepa>) or one of the following | |
159 | abbreviated forms: | |
160 | ||
161 | /vicepa = vicepa = a = 0 | |
162 | /vicepb = vicepb = b = 1 | |
163 | ||
164 | After F</vicepz> (for which the index is 25) comes | |
165 | ||
166 | /vicepaa = vicepaa = aa = 26 | |
167 | /vicepab = vicepab = ab = 27 | |
168 | ||
169 | and so on through | |
170 | ||
171 | /vicepiv = vicepiv = iv = 255 | |
172 | ||
173 | =item B<-volume> <I<salvage volume id or name>> | |
174 | ||
175 | Specifies the name or volume ID number of a read/write volume to | |
176 | salvage. The B<-partition> argument must be provided along with this one. | |
177 | ||
178 | =item B<-file> <I<salvage log output file>> | |
179 | ||
180 | Specifies the complete pathname of a file into which to write a trace of | |
181 | the salvage operation, in addition to the F</usr/afs/logs/SalvageLog> file | |
182 | on the server machine. If the file pathname is local, the trace is written | |
183 | to the specified file on the local disk of the machine where the B<bos | |
184 | salvage> command is issued. If the B<-volume> argument is included, the | |
185 | file can be in AFS, though not in the volume being salvaged. Do not | |
186 | combine this argument with the B<-showlog> flag. | |
187 | ||
188 | =item B<-all> | |
189 | ||
190 | Salvages all volumes on all of the partitions on the machine named by the | |
191 | B<-server> argument. | |
192 | ||
193 | =item B<-showlog> | |
194 | ||
195 | Displays the trace of the salvage operation on the standard output stream, | |
196 | as well as writing it to the F</usr/afs/logs/SalvageLog> file. Do not | |
197 | combine this flag with the B<-file> argument. | |
198 | ||
199 | =item B<-parallel> <I<# of max parallel partition salvaging>> | |
200 | ||
201 | Specifies the maximum number of Salvager subprocesses to run in | |
202 | parallel. Provide one of three values: | |
203 | ||
204 | =over 4 | |
205 | ||
206 | =item * | |
207 | ||
208 | An integer from the range C<1> to C<32>. A value of C<1> means that a | |
209 | single Salvager process salvages the partitions sequentially. | |
210 | ||
211 | =item * | |
212 | ||
213 | The string C<all> to run up to four Salvager subprocesses in parallel on | |
214 | partitions formatted as logical volumes that span multiple physical | |
215 | disks. Use this value only with such logical volumes. | |
216 | ||
217 | =item * | |
218 | ||
219 | The string all followed immediately (with no intervening space) by an | |
220 | integer from the range C<1> to C<32>, to run the specified number of | |
221 | Salvager subprocesses in parallel on partitions formatted as logical | |
222 | volumes. Use this value only with such logical volumes. | |
223 | ||
224 | =back | |
225 | ||
226 | The BOS Server never starts more Salvager subprocesses than there are | |
227 | partitions, and always starts only one process to salvage a single | |
228 | volume. If this argument is omitted, up to four Salvager subprocesses run | |
229 | in parallel. | |
230 | ||
231 | =item B<-tmpdir> <I<directory to place tmp files>> | |
232 | ||
233 | Specifies the full pathname of a local disk directory to which the | |
234 | Salvager process writes temporary files as it runs. If this argument is | |
235 | omitted, or specifies an ineligible or nonexistent directory, the Salvager | |
236 | process writes the files to the partition it is currently salvaging. | |
237 | ||
238 | =item B<-orphans> (ignore | remove | attach) | |
239 | ||
240 | Controls how the Salvager handles orphaned files and directories. Choose | |
241 | one of the following three values: | |
242 | ||
243 | =over 4 | |
244 | ||
245 | =item ignore | |
246 | ||
247 | Leaves the orphaned objects on the disk, but prints a message to the | |
248 | F</usr/afs/logs/SalvageLog> file reporting how many orphans were found and | |
249 | the approximate number of kilobytes they are consuming. This is the | |
250 | default if the B<-orphans> argument is omitted. | |
251 | ||
252 | =item remove | |
253 | ||
254 | Removes the orphaned objects, and prints a message to the | |
255 | F</usr/afs/logs/SalvageLog> file reporting how many orphans were removed | |
256 | and the approximate number of kilobytes they were consuming. | |
257 | ||
258 | =item attach | |
259 | ||
260 | Attaches the orphaned objects by creating a reference to them in the vnode | |
261 | of the volume's root directory. Since each object's actual name is now | |
262 | lost, the Salvager assigns each one a name of the following form: | |
263 | ||
264 | =over 4 | |
265 | ||
266 | =item * | |
267 | ||
268 | C<__ORPHANFILE__.I<index>> for files. | |
269 | ||
270 | =item * | |
271 | ||
272 | C<__ORPHANDIR__.I<index>> for directories. | |
273 | ||
274 | =back | |
275 | ||
276 | where I<index> is a two-digit number that uniquely identifies each | |
277 | object. The orphans are charged against the volume's quota and appear in | |
278 | the output of the B<ls> command issued against the volume's root | |
279 | directory. | |
280 | ||
281 | =back | |
282 | ||
283 | =item B<-forceDAFS> | |
284 | ||
285 | If the fileserver is a Demand Attach File Server, then the B<-forceDAFS> | |
286 | flag must be provided in order for the B<salvager> to run. | |
287 | ||
288 | =item B<-cell> <I<cell name>> | |
289 | ||
290 | Names the cell in which to run the command. Do not combine this argument | |
291 | with the B<-localauth> flag. For more details, see L<bos(8)>. | |
292 | ||
293 | =item B<-noauth> | |
294 | ||
295 | Assigns the unprivileged identity C<anonymous> to the issuer. Do not | |
296 | combine this flag with the B<-localauth> flag. For more details, see | |
297 | L<bos(8)>. | |
298 | ||
299 | =item B<-localauth> | |
300 | ||
301 | Constructs a server ticket using a key from the local | |
302 | F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file. | |
303 | The B<bos> command interpreter presents the | |
304 | ticket to the BOS Server during mutual authentication. Do not combine this | |
305 | flag with the B<-cell> or B<-noauth> options. For more details, see | |
306 | L<bos(8)>. | |
307 | ||
308 | =item B<-help> | |
309 | ||
310 | Prints the online help for this command. All other valid options are | |
311 | ignored. | |
312 | ||
313 | =back | |
314 | ||
315 | =head1 EXAMPLES | |
316 | ||
317 | The following command salvages all volumes on the F</vicepd> partition of | |
318 | the machine C<db3.example.com>: | |
319 | ||
320 | % bos salvage -server db3.example.com -partition /vicepd | |
321 | ||
322 | The following command salvages the volume with volume ID number 536870988 | |
323 | on partition F</vicepb> of the machine C<fs2.example.com>: | |
324 | ||
325 | % bos salvage -server fs2.example.com -partition /vicepb -volume 536870988 | |
326 | ||
327 | The following command salvages all volumes on the machine | |
328 | C<fs4.example.com>. Six Salvager processes run in parallel rather than the | |
329 | default four. | |
330 | ||
331 | % bos salvage -server fs4.example.com -all -parallel 6 | |
332 | ||
333 | =head1 PRIVILEGE REQUIRED | |
334 | ||
335 | The issuer must be listed in the F</usr/afs/etc/UserList> file on the | |
336 | machine named by the B<-server> argument, or must be logged onto a server | |
337 | machine as the local superuser C<root> if the B<-localauth> flag is | |
338 | included. | |
339 | ||
340 | =head1 SEE ALSO | |
341 | ||
342 | L<KeyFile(5)>, | |
343 | L<KeyFileExt(5)>, | |
344 | L<SalvageLog(5)>, | |
345 | L<UserList(5)>, | |
346 | L<bos(8)>, | |
347 | L<salvager(8)>, | |
348 | L<salvageserver(8)>, | |
349 | L<vos_backup(1)>, | |
350 | L<vos_release(1)>, | |
351 | L<vos_remove(1)>, | |
352 | L<vos_zap(1)> | |
353 | ||
354 | The I<OpenAFS Administration Guide> at | |
355 | L<http://docs.openafs.org/AdminGuide/>. | |
356 | ||
357 | =head1 COPYRIGHT | |
358 | ||
359 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
360 | ||
361 | This documentation is covered by the IBM Public License Version 1.0. It was | |
362 | converted from HTML to POD by software written by Chas Williams and Russ | |
363 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |