doc/xml/AdminReference/sect8/bos_salvage.xml

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