doc: the last partition name is /vicepiu
[openafs.git] / doc / man-pages / pod8 / bos_salvage.pod
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    /vicepiu    =     vicepiu     =      iu     =      254
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.