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