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