doc/xml/AdminReference/sect8/salvager.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="salvager8">
   3   <refmeta>
   4     <refentrytitle>salvager</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>salvager</refname>
   9     <refpurpose>Initializes the Salvager component of the fs process</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">salvager</emphasis> [<emphasis>initcmd</emphasis>] [<emphasis role="bold">-partition</emphasis> &lt;<emphasis>name of partition to salvage</emphasis>&gt;]
  14         [<emphasis role="bold">-volumeid</emphasis> &lt;<emphasis>volume id to salvage</emphasis>&gt;] [<emphasis role="bold">-debug</emphasis>] [<emphasis role="bold">-nowrite</emphasis>]
  15         [<emphasis role="bold">-inodes</emphasis>] [<emphasis role="bold">-force</emphasis>] [<emphasis role="bold">-oktozap</emphasis>] [<emphasis role="bold">-rootinodes</emphasis>]
  16         [<emphasis role="bold">-salvagedirs</emphasis>] [<emphasis role="bold">-blockreads</emphasis>]
  17         [<emphasis role="bold">-parallel</emphasis> &lt;<emphasis># of max parallel partition salvaging</emphasis>&gt;]
  18         [<emphasis role="bold">-tmpdir</emphasis> &lt;<emphasis>name of dir to place tmp files</emphasis>&gt;]
  19         [<emphasis role="bold">-showlog</emphasis>] [<emphasis role="bold">-showsuid</emphasis>] [<emphasis role="bold">-showmounts</emphasis>]
  20         [<emphasis role="bold">-orphans</emphasis> (ignore | remove | attach)] [<emphasis role="bold">-help</emphasis>]</para>
  21
  22   </refsect1>
  23   <refsect1>
  24     <title>Description</title>
  25     <para>The <emphasis role="bold">salvager</emphasis> command initializes the Salvager component of the <computeroutput>fs</computeroutput>
  26     process. In the conventional configuration, its binary file is located in
  27     the <replaceable>/usr/afs/bin</replaceable> directory on a file server machine.</para>
  28
  29     <para>The Salvager restores internal consistency to corrupted read/write volumes
  30     on the local file server machine where possible. For read-only or backup
  31     volumes, it inspects only the volume header:</para>
  32
  33     <itemizedlist>
  34       <listitem>
  35         <para>If the volume header is corrupted, the Salvager removes the volume
  36         completely and records the removal in its log file,
  37         <replaceable>/usr/afs/logs/SalvageLog</replaceable>. Issue the <emphasis role="bold">vos release</emphasis> or <emphasis role="bold">vos backup</emphasis>
  38         command to create the read-only or backup volume again.</para>
  39
  40       </listitem>
  41       <listitem>
  42         <para>If the volume header is intact, the Salvager skips the volume (does not
  43         check for corruption in the contents). However, if the File Server notices
  44         corruption as it initializes, it sometimes refuses to attach the volume or
  45         bring it online. In this case, it is simplest to remove the volume by
  46         issuing the <emphasis role="bold">vos remove</emphasis> or <emphasis role="bold">vos zap</emphasis> command. Then issue the <emphasis role="bold">vos
  47         release</emphasis> or <emphasis role="bold">vos backup</emphasis> command to create it again.</para>
  48
  49       </listitem>
  50     </itemizedlist>
  51     <para>Unlike other server process initialization commands, the <emphasis role="bold">salvager</emphasis>
  52     command is designed to be issued at the command shell prompt, as well as
  53     being placed into a file server machine's <replaceable>/usr/afs/local/BosConfig</replaceable> file
  54     with the <emphasis role="bold">bos create</emphasis> command. It is also possible to invoke the Salvager
  55     remotely by issuing the <emphasis role="bold">bos salvage</emphasis> command.</para>
  56
  57     <para>Combine the command's options as indicated to salvage different numbers of
  58     read/write volumes:</para>
  59
  60     <itemizedlist>
  61       <listitem>
  62         <para>To salvage all volumes on the file server machine, provide no arguments.
  63         No volumes on the machine are accessible to Cache Managers during the
  64         salvage, because the BOS Server stops the File Server and Volume Server
  65         processes while the Salvager runs.</para>
  66
  67       </listitem>
  68       <listitem>
  69         <para>To salvage all of the volumes on one partition, provide the <emphasis role="bold">-partition</emphasis>
  70         argument. As for a salvage of all volumes on the machine, no volumes on
  71         the machine are accessible to Cache Managers during the salvage operation.</para>
  72
  73       </listitem>
  74       <listitem>
  75         <para>To salvage only one volume, combine the <emphasis role="bold">-partition</emphasis> and <emphasis role="bold">-volumeid</emphasis>
  76         arguments. Only that volume is inaccessible to Cache Managers, because the
  77         BOS Server does not shutdown the File Server and Volume Server processes.</para>
  78
  79       </listitem>
  80     </itemizedlist>
  81     <para>The Salvager normally salvages only those read/write volumes that are
  82     marked as having been active when a crash occurred. To have it salvage all
  83     relevant read/write volumes, add the <emphasis role="bold">-force</emphasis> flag.</para>
  84
  85     <para>The Salvager normally creates new inodes as it repairs damage. If the
  86     partition is so full that there is no room for new inodes, use the
  87     <emphasis role="bold">-nowrite</emphasis> argument to bringing undamaged volumes online without
  88     attempting to salvage damaged volumes. Then use the <emphasis role="bold">vos move</emphasis> command to
  89     move one or more of the undamaged volumes to other partitions, freeing up
  90     the space that the Salvager needs to create new inodes.</para>
  91
  92     <para>By default, multiple Salvager subprocesses run in parallel: one for each
  93     partition up to four, and four subprocesses for four or more
  94     partitions. To increase or decrease the number of subprocesses running in
  95     parallel, provide a positive integer value for the <emphasis role="bold">-parallel</emphasis> argument.</para>
  96
  97     <para>If there is more than one server partition on a physical disk, the
  98     Salvager by default salvages them serially to avoid the inefficiency of
  99     constantly moving the disk head from one partition to another. However,
 100     this strategy is often not ideal if the partitions are configured as
 101     logical volumes that span multiple disks. To force the Salvager to salvage
 102     logical volumes in parallel, provide the string <computeroutput>all</computeroutput> as the value for
 103     the <emphasis role="bold">-parallel</emphasis> argument. Provide a positive integer to specify the
 104     number of subprocesses to run in parallel (for example, <computeroutput>-parallel 5all</computeroutput>
 105     for five subprocesses), or omit the integer to run up to four
 106     subprocesses, depending on the number of logical volumes being salvaged.</para>
 107
 108     <para>The Salvager creates temporary files as it runs, by default writing them
 109     to the partition it is salvaging. The number of files can be quite large,
 110     and if the partition is too full to accommodate them, the Salvager
 111     terminates without completing the salvage operation (it always removes the
 112     temporary files before exiting). Other Salvager subprocesses running at
 113     the same time continue until they finish salvaging all other partitions
 114     where there is enough disk space for temporary files. To complete the
 115     interrupted salvage, reissue the command against the appropriate
 116     partitions, adding the <emphasis role="bold">-tmpdir</emphasis> argument to redirect the temporary files
 117     to a local disk directory that has enough space.</para>
 118
 119     <para>The <emphasis role="bold">-orphans</emphasis> argument controls how the Salvager handles orphaned files
 120     and directories that it finds on server partitions it is salvaging. An
 121     <emphasis>orphaned</emphasis> element is completely inaccessible because it is not
 122     referenced by the vnode of any directory that can act as its parent (is
 123     higher in the filespace). Orphaned objects occupy space on the server
 124     partition, but do not count against the volume's quota.</para>
 125
 126     <para>To generate a list of all mount points that reside in one or more volumes,
 127     rather than actually salvaging them, include the <emphasis role="bold">-showmounts</emphasis> flag.</para>
 128
 129     <para>This command does not use the syntax conventions of the AFS command
 130     suites. Provide the command name and all option names in full.</para>
 131
 132   </refsect1>
 133   <refsect1>
 134     <title>Options</title>
 135     <variablelist>
 136       <varlistentry>
 137         <term>[<emphasis>initcmd</emphasis>]</term>
 138         <listitem>
 139           <para>Accommodates the command's use of the AFS command parser, and is optional.</para>
 140
 141         </listitem>
 142       </varlistentry>
 143       <varlistentry>
 144         <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>name of partition to salvage</emphasis>&gt;</term>
 145         <listitem>
 146           <para>Specifies the name of the partition to salvage. Specify the full partition
 147           name using the form <replaceable>/vicep</replaceable><emphasis>x</emphasis><replaceable></replaceable> or <replaceable>/vicep</replaceable><emphasis>xx</emphasis><replaceable></replaceable>. Omit this argument to
 148           salvage every partition on the file server machine.</para>
 149
 150         </listitem>
 151       </varlistentry>
 152       <varlistentry>
 153         <term><emphasis role="bold">-volumeid</emphasis> &lt;<emphasis>volume id to salvage</emphasis>&gt;</term>
 154         <listitem>
 155           <para>Specifies the volume ID of a specific read/write volume to salvage.  The
 156           <emphasis role="bold">-partition</emphasis> argument must be provided along with this one and specify
 157           the volume's actual site.</para>
 158
 159         </listitem>
 160       </varlistentry>
 161       <varlistentry>
 162         <term><emphasis role="bold">-debug</emphasis></term>
 163         <listitem>
 164           <para>Allows only one Salvager subprocess to run at a time, regardless of the
 165           setting of the <emphasis role="bold">-parallel</emphasis> option. Include it when running the Salvager
 166           in a debugger to make the trace easier to interpret.</para>
 167
 168         </listitem>
 169       </varlistentry>
 170       <varlistentry>
 171         <term><emphasis role="bold">-nowrite</emphasis></term>
 172         <listitem>
 173           <para>Brings all undamaged volumes online without attempting to salvage any
 174           damaged volumes.</para>
 175
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry>
 179         <term><emphasis role="bold">-inodes</emphasis></term>
 180         <listitem>
 181           <para>Records in the <replaceable>/usr/afs/logs/SalvageLog</replaceable> file a list of all AFS inodes
 182           that the Salvager modified.</para>
 183
 184         </listitem>
 185       </varlistentry>
 186       <varlistentry>
 187         <term><emphasis role="bold">-force</emphasis></term>
 188         <listitem>
 189           <para>Inspects all volumes for corruption, not just those that are marked as
 190           having been active when a crash occurred.</para>
 191
 192         </listitem>
 193       </varlistentry>
 194       <varlistentry>
 195         <term><emphasis role="bold">-oktozap</emphasis></term>
 196         <listitem>
 197           <para>Removes a volume that is so damaged that even issuing the <emphasis role="bold">vos zap</emphasis>
 198           command with the <emphasis role="bold">-force</emphasis> flag is ineffective. Use this argument only in
 199           consultation with AFS Development or Product Support. Combine it with the
 200           <emphasis role="bold">-partition</emphasis> and <emphasis role="bold">-volumeid</emphasis> arguments to identify the volume to remove.</para>
 201
 202         </listitem>
 203       </varlistentry>
 204       <varlistentry>
 205         <term><emphasis role="bold">-rootinodes</emphasis></term>
 206         <listitem>
 207           <para>Records in the <replaceable>/usr/afs/logs/SalvageLog</replaceable> file a list of all AFS inodes
 208           owned by the local superuser <computeroutput>root</computeroutput>.</para>
 209
 210         </listitem>
 211       </varlistentry>
 212       <varlistentry>
 213         <term><emphasis role="bold">-salvagedirs</emphasis></term>
 214         <listitem>
 215           <para>Salvages entire directory structures, even if they do not appear to be
 216           damaged. By default, the Salvager salvages a directory only if it is
 217           flagged as corrupted.</para>
 218
 219         </listitem>
 220       </varlistentry>
 221       <varlistentry>
 222         <term><emphasis role="bold">-blockreads</emphasis></term>
 223         <listitem>
 224           <para>Forces the Salvager to read a partition one disk block (512 bytes) at a
 225           time and to skip any blocks that are too badly damaged to be salvaged.
 226           This allows it to salvage as many volumes as possible. By default, the
 227           Salvager reads large disk blocks, which can cause it to exit prematurely
 228           if it encounters disk errors. Use this flag if the partition to be
 229           salvaged has disk errors.</para>
 230
 231         </listitem>
 232       </varlistentry>
 233       <varlistentry>
 234         <term><emphasis role="bold">-parallel</emphasis> &lt;<emphasis># of max parallel partition salvaging</emphasis>&gt;</term>
 235         <listitem>
 236           <para>Specifies the maximum number of Salvager subprocesses to run in parallel.
 237           Provide one of three values:</para>
 238
 239           <itemizedlist>
 240             <listitem>
 241               <para>An integer from the range <computeroutput>1</computeroutput> to <computeroutput>32</computeroutput>. A value of <computeroutput>1</computeroutput> means that a
 242               single Salvager process salvages the partitions sequentially.</para>
 243
 244             </listitem>
 245             <listitem>
 246               <para>The string <computeroutput>all</computeroutput> to run up to four Salvager subprocesses in parallel on
 247               partitions formatted as logical volumes that span multiple physical
 248               disks. Use this value only with such logical volumes.</para>
 249
 250             </listitem>
 251             <listitem>
 252               <para>The string <computeroutput>all</computeroutput> followed immediately (with no intervening space) by an
 253               integer from the range <computeroutput>1</computeroutput> to <computeroutput>32</computeroutput>, to run the specified number of
 254               Salvager subprocesses in parallel on partitions formatted as logical
 255               volumes. Use this value only with such logical volumes.</para>
 256
 257             </listitem>
 258           </itemizedlist>
 259           <para>The BOS Server never starts more Salvager subprocesses than there are
 260           partitions, and always starts only one process to salvage a single
 261           volume. If this argument is omitted, up to four Salvager subprocesses run
 262           in parallel.</para>
 263
 264         </listitem>
 265       </varlistentry>
 266       <varlistentry>
 267         <term><emphasis role="bold">-tmpdir</emphasis> &lt;<emphasis>name of dir to place tmp files</emphasis>&gt;</term>
 268         <listitem>
 269           <para>Names a local disk directory in which the Salvager places the temporary
 270           files it creates during a salvage operation, instead of writing them to
 271           the partition being salvaged (the default). If the Salvager cannot write
 272           to the specified directory, it attempts to write to the partition being
 273           salvaged.</para>
 274
 275         </listitem>
 276       </varlistentry>
 277       <varlistentry>
 278         <term><emphasis role="bold">-showlog</emphasis></term>
 279         <listitem>
 280           <para>Displays on the standard output stream all log data that is being written
 281           to the <replaceable>/usr/afs/logs/SalvageLog</replaceable> file.</para>
 282
 283         </listitem>
 284       </varlistentry>
 285       <varlistentry>
 286         <term><emphasis role="bold">-showsuid</emphasis></term>
 287         <listitem>
 288           <para>Displays a list of the pathnames for all files that have the setuid or
 289           setgid mode bit set.</para>
 290
 291         </listitem>
 292       </varlistentry>
 293       <varlistentry>
 294         <term><emphasis role="bold">-showmounts</emphasis></term>
 295         <listitem>
 296           <para>Records in the <replaceable>/usr/afs/logs/SalvageLog</replaceable> file all mount points found in
 297           each volume. The Salvager does not repair corruption in the volumes, if
 298           any exists.</para>
 299
 300         </listitem>
 301       </varlistentry>
 302       <varlistentry>
 303         <term><emphasis role="bold">-orphans</emphasis> (ignore | remove | attach)</term>
 304         <listitem>
 305           <para>Controls how the Salvager handles orphaned files and directories.  Choose
 306           one of the following three values:</para>
 307
 308           <variablelist>
 309             <varlistentry>
 310               <term>ignore</term>
 311               <listitem>
 312                 <para>Leaves the orphaned objects on the disk, but prints a message to the
 313                 <replaceable>/usr/afs/logs/SalvageLog</replaceable> file reporting how many orphans were found and
 314                 the approximate number of kilobytes they are consuming. This is the
 315                 default if the <emphasis role="bold">-orphans</emphasis> argument is omitted.</para>
 316
 317               </listitem>
 318             </varlistentry>
 319             <varlistentry>
 320               <term>remove</term>
 321               <listitem>
 322                 <para>Removes the orphaned objects, and prints a message to the
 323                 <replaceable>/usr/afs/logs/SalvageLog</replaceable> file reporting how many orphans were removed
 324                 and the approximate number of kilobytes they were consuming.</para>
 325
 326               </listitem>
 327             </varlistentry>
 328             <varlistentry>
 329               <term>attach</term>
 330               <listitem>
 331                 <para>Attaches the orphaned objects by creating a reference to them in the vnode
 332                 of the volume's root directory. Since each object's actual name is now
 333                 lost, the Salvager assigns each one a name of the following form:</para>
 334
 335                 <variablelist>
 336                   <varlistentry>
 337                     <term><computeroutput>__ORPHANFILE__.</computeroutput><emphasis>index</emphasis><computeroutput></computeroutput> for files.</term>
 338                     <listitem>
 339                       <para></para>
 340
 341                     </listitem>
 342                   </varlistentry>
 343                   <varlistentry>
 344                     <term><computeroutput>__ORPHANDIR__.</computeroutput><emphasis>index</emphasis><computeroutput></computeroutput> for directories.</term>
 345                     <listitem>
 346                       <para></para>
 347
 348                     </listitem>
 349                   </varlistentry>
 350                 </variablelist>
 351                 <para>where <emphasis>index</emphasis> is a two-digit number that uniquely identifies each
 352                 object. The orphans are charged against the volume's quota and appear in
 353                 the output of the <emphasis role="bold">ls</emphasis> command issued against the volume's root
 354                 directory.</para>
 355
 356               </listitem>
 357             </varlistentry>
 358           </variablelist>
 359         </listitem>
 360       </varlistentry>
 361       <varlistentry>
 362         <term><emphasis role="bold">-help</emphasis></term>
 363         <listitem>
 364           <para>Prints the online help for this command. All other valid options are
 365           ignored.</para>
 366
 367         </listitem>
 368       </varlistentry>
 369     </variablelist>
 370   </refsect1>
 371   <refsect1>
 372     <title>Examples</title>
 373     <para>The following command instructs the Salvager to attempt to salvage the
 374     volume with volume ID 258347486 on <replaceable>/vicepg</replaceable> on the local machine.</para>
 375
 376 <programlisting>
 377    % /usr/afs/bin/salvager -partition /vicepg -volumeid 258347486
 378
 379 </programlisting>
 380     </refsect1>
 381     <refsect1>
 382       <title>Privilege Required</title>
 383       <para>To issue the command at the shell prompt, the issuer must be logged in as
 384       the local superuser <computeroutput>root</computeroutput>.</para>
 385
 386     </refsect1>
 387     <refsect1>
 388       <title>See Also</title>
 389       <para><link linkend="BosConfig5">BosConfig(5)</link>,
 390       <link linkend="SalvageLog5">SalvageLog(5)</link>,
 391       <link linkend="bos_create8">bos_create(8)</link>,
 392       <link linkend="bos_getlog8">bos_getlog(8)</link>,
 393       <link linkend="bos_salvage8">bos_salvage(8)</link>,
 394       <link linkend="vos_move1">vos_move(1)</link></para>
 395
 396     </refsect1>
 397     <refsect1>
 398       <title>Copyright</title>
 399       <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 400
 401       <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 402       converted from HTML to POD by software written by Chas Williams and Russ
 403       Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 404
 405     </refsect1>
 406   </refentry>