Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | salvageserver - Initializes the Salvageserver component of the dafs process | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<salvageserver> [I<initcmd>] S<<< [B<-partition> <I<name of partition to salvage>>] >>> | |
11 | S<<< [B<-volumeid> <I<volume id to salvage>>] >>> [B<-debug>] [B<-nowrite>] | |
12 | [B<-inodes>] [B<-force>] [B<-oktozap>] [B<-rootinodes>] | |
13 | [B<-salvagedirs>] [B<-blockreads>] | |
14 | S<<< [B<-parallel> <I<# of max parallel partition salvaging>>] >>> | |
15 | S<<< [B<-tmpdir> <I<name of dir to place tmp files>>] >>> | |
16 | S<<< [B<-orphans> (ignore | remove | attach)] >>> | |
17 | [B<-syslog>] | |
18 | S<<< [B<-syslogfacility> <I<Syslog facility number to use>>] >>> | |
19 | [B<-client>] [B<-help>] | |
20 | ||
21 | =for html | |
22 | </div> | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | In its typical mode of operation, the B<salvageserver> is a daemon process | |
27 | responsible for salvaging volumes. It is a component of the C<dafs> | |
28 | process type. In the conventional configuration, its binary file is | |
29 | located in the F</usr/afs/bin> directory on a file server machine. | |
30 | ||
31 | The Salvageserver daemon is responsible for scheduling and executing | |
32 | volume salvage operations on behalf of client processes. The fileserver | |
33 | acts as the primary salvageserver client: any failed volume attach | |
34 | operation results in a salvageserver scheduling request. The | |
35 | salvageserver also accepts periodic volume activity messages in order to | |
36 | update its salvage request priority queue. Other clients of the | |
37 | salvageserver daemon include the B<salvsync-debug> utility, and the | |
38 | salvageserver command itself by passing the B<-client> flag. | |
39 | ||
40 | The salvage operations performed on vice partition data are nearly | |
41 | identical to those performed by the standalone Salvager command. The | |
42 | key differences between the two commands are: | |
43 | ||
44 | =over 4 | |
45 | ||
46 | =item * | |
47 | ||
48 | The Salvageserver is a daemon process which runs concurrently with the | |
49 | fileserver. In contrast, the Salvager is a stand-alone application which | |
50 | is invoked when the fileserver and volserver are not running. | |
51 | ||
52 | =item * | |
53 | ||
54 | The Salvageserver is incapable of performing whole partition salvage | |
55 | operations; it operates at volume group granularity. | |
56 | ||
57 | =back | |
58 | ||
59 | The Salvageserver normally creates new inodes as it repairs damage. If the | |
60 | partition is so full that there is no room for new inodes, use the | |
61 | B<-nowrite> argument to bringing undamaged volumes online without | |
62 | attempting to salvage damaged volumes. Then use the B<vos move> command to | |
63 | move one or more of the undamaged volumes to other partitions, freeing up | |
64 | the space that the Salvageserver needs to create new inodes. | |
65 | ||
66 | By default, multiple Salvageserver subprocesses run in parallel: one for each | |
67 | volume group. By default, four concurrent salvage operations are | |
68 | permitted. You may alter this default by providing a positive integer | |
69 | value for the B<-parallel> argument. The maximum permitted value is 32 | |
70 | concurrent salvageserver subprocesses. | |
71 | ||
72 | By default, the salvageserver enables a heuristic which attempts to stop | |
73 | disk head thrashing by concurrent salvageserver subprocesses. Unfortunately, | |
74 | this heuristic significantly degrades performance in many cases. In at least | |
75 | the following environments, passing the C<all> string to the B<-parallel> | |
76 | argument is strongly encouraged: | |
77 | ||
78 | =over 4 | |
79 | ||
80 | =item * | |
81 | ||
82 | On NAMEI fileservers | |
83 | ||
84 | =item * | |
85 | ||
86 | When a vice partition is backed by multiple disks (e.g. RAID) | |
87 | ||
88 | =item * | |
89 | ||
90 | When a vice partition is backed by SAN-attached storage, LVM, or some other | |
91 | form of storage virtualization which would cause unix device id numbers to | |
92 | be unpredictable. | |
93 | ||
94 | =back | |
95 | ||
96 | The Salvageserver creates temporary files as it runs, by default writing them | |
97 | to the partition it is salvaging. The number of files can be quite large, | |
98 | and if the partition is too full to accommodate them, the Salvageserver | |
99 | terminates without completing the salvage operation (it always removes the | |
100 | temporary files before exiting). Other Salvageserver subprocesses running at | |
101 | the same time continue until they finish salvaging all other partitions | |
102 | where there is enough disk space for temporary files. To complete the | |
103 | interrupted salvage, reissue the command against the appropriate | |
104 | partitions, adding the B<-tmpdir> argument to redirect the temporary files | |
105 | to a local disk directory that has enough space. | |
106 | ||
107 | The B<-orphans> argument controls how the Salvageserver handles orphaned files | |
108 | and directories that it finds on server partitions it is salvaging. An | |
109 | I<orphaned> element is completely inaccessible because it is not | |
110 | referenced by the vnode of any directory that can act as its parent (is | |
111 | higher in the filespace). Orphaned objects occupy space on the server | |
112 | partition, but do not count against the volume's quota. | |
113 | ||
114 | This command does not use the syntax conventions of the AFS command | |
115 | suites. Provide the command name and all option names in full. | |
116 | ||
117 | =head1 OPTIONS | |
118 | ||
119 | =over 4 | |
120 | ||
121 | =item [I<initcmd>] | |
122 | ||
123 | Accommodates the command's use of the AFS command parser, and is optional. | |
124 | ||
125 | =item B<-partition> <I<name of partition to salvage>> | |
126 | ||
127 | Specifies the name of the partition to salvage. Specify the full partition | |
128 | name using the form F</vicepI<x>> or F</vicepI<xx>>. Omit this argument to | |
129 | salvage every partition on the file server machine. | |
130 | ||
131 | =item B<-volumeid> <I<volume id to salvage>> | |
132 | ||
133 | Specifies the volume ID of a specific read/write volume to salvage. The | |
134 | B<-partition> argument must be provided along with this one and specify | |
135 | the volume's actual site. | |
136 | ||
137 | =item B<-debug> | |
138 | ||
139 | This flag should be considered deprecated. Its primary purpose was to disable | |
140 | forking and parallelization of the Salvager so that log messages were not | |
141 | interleaved. Due to the manner in which F</usr/afs/logs/SalsrvLog> is | |
142 | written, log messages from subprocesses are never interleaved; the entire log | |
143 | for a volume group salvage is appended to the master log as one atomic | |
144 | transaction. | |
145 | ||
146 | =item B<-nowrite> | |
147 | ||
148 | Brings all undamaged volumes online without attempting to salvage any | |
149 | damaged volumes. | |
150 | ||
151 | =item B<-inodes> | |
152 | ||
153 | Records in the F</usr/afs/logs/SalsrvLog> file a list of all AFS inodes | |
154 | that the Salvageserver modified. | |
155 | ||
156 | =item B<-force> | |
157 | ||
158 | Inspects all volumes for corruption, not just those that are marked as | |
159 | having been active when a crash occurred. | |
160 | ||
161 | =item B<-oktozap> | |
162 | ||
163 | Removes a volume that is so damaged that even issuing the B<vos zap> | |
164 | command with the B<-force> flag is ineffective. Combine it with the | |
165 | B<-partition> and B<-volumeid> arguments to identify the volume to remove. | |
166 | Using this flag will destroy data that cannot be read, so use only with | |
167 | caution and when you're certain that nothing in that volume is still | |
168 | needed. | |
169 | ||
170 | =item B<-rootinodes> | |
171 | ||
172 | Records in the F</usr/afs/logs/SalsrvLog> file a list of all AFS inodes | |
173 | owned by the local superuser C<root>. | |
174 | ||
175 | =item B<-salvagedirs> | |
176 | ||
177 | Salvages entire directory structures, even if they do not appear to be | |
178 | damaged. By default, the Salvageserver salvages a directory only if it is | |
179 | flagged as corrupted. | |
180 | ||
181 | =item B<-blockreads> | |
182 | ||
183 | Forces the Salvageserver to read a partition one disk block (512 bytes) at a | |
184 | time and to skip any blocks that are too badly damaged to be salvaged. | |
185 | This allows it to salvage as many volumes as possible. By default, the | |
186 | Salvageserver reads large disk blocks, which can cause it to exit prematurely | |
187 | if it encounters disk errors. Use this flag if the partition to be | |
188 | salvaged has disk errors. | |
189 | ||
190 | =item B<-parallel> <I<# of max parallel partition salvaging>> | |
191 | ||
192 | Specifies the maximum number of Salvageserver subprocesses to run in parallel. | |
193 | Provide one of three values: | |
194 | ||
195 | =over 4 | |
196 | ||
197 | =item * | |
198 | ||
199 | An integer from the range C<1> to C<32>. A value of C<1> means that a | |
200 | single Salvageserver subprocess salvages the volume groups sequentially. | |
201 | The disk partition heuristic (see above) based upon unix device ids is | |
202 | enabled. | |
203 | ||
204 | =item * | |
205 | ||
206 | The disk partition heuristic (see above) based upon unix device ids is | |
207 | disabled. | |
208 | ||
209 | =item * | |
210 | ||
211 | The string C<all> followed immediately (with no intervening space) by an | |
212 | integer from the range C<1> to C<32>, to run the specified number of | |
213 | Salvageserver subprocesses in parallel on volume groups. The disk partition | |
214 | heuristic (see above) based upon unix device ids is disabled. | |
215 | ||
216 | =back | |
217 | ||
218 | If this argument is omitted, up to four Salvageserver subprocesses run | |
219 | in parallel. | |
220 | ||
221 | =item B<-tmpdir> <I<name of dir to place tmp files>> | |
222 | ||
223 | Names a local disk directory in which the Salvageserver places the temporary | |
224 | files it creates during a salvage operation, instead of writing them to | |
225 | the partition being salvaged (the default). If the Salvageserver cannot write | |
226 | to the specified directory, it attempts to write to the partition being | |
227 | salvaged. | |
228 | ||
229 | =item B<-orphans> (ignore | remove | attach) | |
230 | ||
231 | Controls how the Salvageserver handles orphaned files and directories. Choose | |
232 | one of the following three values: | |
233 | ||
234 | =over 4 | |
235 | ||
236 | =item ignore | |
237 | ||
238 | Leaves the orphaned objects on the disk, but prints a message to the | |
239 | F</usr/afs/logs/SalsrvLog> file reporting how many orphans were found and | |
240 | the approximate number of kilobytes they are consuming. This is the | |
241 | default if the B<-orphans> argument is omitted. | |
242 | ||
243 | =item remove | |
244 | ||
245 | Removes the orphaned objects, and prints a message to the | |
246 | F</usr/afs/logs/SalsrvLog> file reporting how many orphans were removed | |
247 | and the approximate number of kilobytes they were consuming. | |
248 | ||
249 | =item attach | |
250 | ||
251 | Attaches the orphaned objects by creating a reference to them in the vnode | |
252 | of the volume's root directory. Since each object's actual name is now | |
253 | lost, the Salvageserver assigns each one a name of the following form: | |
254 | ||
255 | =over 4 | |
256 | ||
257 | =item C<__ORPHANFILE__.I<index>> for files. | |
258 | ||
259 | =item C<__ORPHANDIR__.I<index>> for directories. | |
260 | ||
261 | =back | |
262 | ||
263 | where I<index> is a two-digit number that uniquely identifies each | |
264 | object. The orphans are charged against the volume's quota and appear in | |
265 | the output of the B<ls> command issued against the volume's root | |
266 | directory. | |
267 | ||
268 | =back | |
269 | ||
270 | =item B<-syslog> | |
271 | ||
272 | Specifies that logging output should go to syslog instead of the log file. | |
273 | ||
274 | =item B<-syslogfacility> <I<Syslog facility number to use>> | |
275 | ||
276 | Specify to which facility log messages should be sent when B<-syslog> is | |
277 | given. | |
278 | ||
279 | =item B<-client> | |
280 | ||
281 | Salvageserver runs in client Mode. The requested volume on the requested | |
282 | partition will be scheduled for salvaging by the Salvageserver daemon. | |
283 | ||
284 | =item B<-logfile> <I<log file>> | |
285 | ||
286 | Sets the file to use for server logging. If logfile is not specified and | |
287 | no other logging options are supplied, this will be F</usr/afs/logs/SalsrvLog>. | |
288 | Note that this option is intended for debugging and testing purposes. | |
289 | Changing the location of the log file from the command line may result | |
290 | in undesirable interactions with tools such as B<bos>. | |
291 | ||
292 | =item B<-help> | |
293 | ||
294 | Prints the online help for this command. All other valid options are | |
295 | ignored. | |
296 | ||
297 | =back | |
298 | ||
299 | =head1 EXAMPLES | |
300 | ||
301 | The following command instructs the Salvageserver to schedule the salvage | |
302 | of the volume with volume ID 258347486 on F</vicepg> on the local machine. | |
303 | ||
304 | % /usr/afs/bin/salvageserver -partition /vicepg -volumeid 258347486 -client | |
305 | ||
306 | =head1 PRIVILEGE REQUIRED | |
307 | ||
308 | To issue the command at the shell prompt, the issuer must be logged in as | |
309 | the local superuser C<root>. | |
310 | ||
311 | =head1 SEE ALSO | |
312 | ||
313 | L<BosConfig(5)>, | |
314 | L<SalvageLog(5)>, | |
315 | L<salvager(8)>, | |
316 | L<bos_create(8)>, | |
317 | L<bos_getlog(8)>, | |
318 | L<bos_salvage(8)>, | |
319 | L<vos_move(1)> | |
320 | ||
321 | =head1 COPYRIGHT | |
322 | ||
323 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
324 | Sine Nomine Associates 2008. All Rights Reserved. | |
325 | ||
326 | This documentation is covered by the IBM Public License Version 1.0. It was | |
327 | converted from HTML to POD by software written by Chas Williams and Russ | |
328 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. This document | |
329 | was adapted from the Salvager POD documentation. |