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 I<IBM
 143 AFS 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> file. The B<bos> command interpreter presents the
 303 ticket to the BOS Server during mutual authentication. Do not combine this
 304 flag with the B<-cell> or B<-noauth> options. For more details, see
 305 L<bos(8)>.
 306
 307 =item B<-help>
 308
 309 Prints the online help for this command. All other valid options are
 310 ignored.
 311
 312 =back
 313
 314 =head1 EXAMPLES
 315
 316 The following command salvages all volumes on the F</vicepd> partition of
 317 the machine C<db3.abc.com>:
 318
 319    % bos salvage -server db3.abc.com -partition /vicepd
 320
 321 The following command salvages the volume with volume ID number 536870988
 322 on partition F</vicepb> of the machine C<fs2.abc.com>:
 323
 324    % bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988
 325
 326 The following command salvages all volumes on the machine
 327 C<fs4.abc.com>. Six Salvager processes run in parallel rather than the
 328 default four.
 329
 330    % bos salvage -server fs4.abc.com -all -parallel 6
 331
 332 =head1 PRIVILEGE REQUIRED
 333
 334 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 335 machine named by the B<-server> argument, or must be logged onto a server
 336 machine as the local superuser C<root> if the B<-localauth> flag is
 337 included.
 338
 339 =head1 SEE ALSO
 340
 341 L<KeyFile(5)>,
 342 L<SalvageLog(5)>,
 343 L<UserList(5)>,
 344 L<bos(8)>,
 345 L<salvager(8)>,
 346 L<salvagserver(8)>,
 347 L<vos_backup(1)>,
 348 L<vos_release(1)>,
 349 L<vos_remove(1)>,
 350 L<vos_zap(1)>
 351
 352 I<IBM AFS Administration Guide>
 353
 354 =head1 COPYRIGHT
 355
 356 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 357
 358 This documentation is covered by the IBM Public License Version 1.0.  It was
 359 converted from HTML to POD by software written by Chas Williams and Russ
 360 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.