doc/xml/AdminReference/sect8/backup_dumpinfo.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="backup_dumpinfo8">
   3   <refmeta>
   4     <refentrytitle>backup dumpinfo</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>backup dumpinfo</refname>
   9     <refpurpose>Displays a dump record from the Backup Database</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">backup dumpinfo</emphasis> [<emphasis role="bold">-ndumps</emphasis> &lt;<emphasis>number of dumps</emphasis>&gt;] [<emphasis role="bold">-id</emphasis> &lt;<emphasis>dump id</emphasis>&gt;]
  14         [<emphasis role="bold">-verbose</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  15
  16     <para><emphasis role="bold">backup dumpi</emphasis> [<emphasis role="bold">-n</emphasis> &lt;<emphasis>no. of dumps</emphasis>&gt;] [-i &lt;<emphasis>dump id</emphasis>&gt;] [<emphasis role="bold">-v</emphasis>]
  17         [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>
  18
  19   </refsect1>
  20   <refsect1>
  21     <title>Description</title>
  22     <para>The <emphasis role="bold">backup dumpinfo</emphasis> command formats and displays the Backup Database
  23     record for the specified dumps. To specify how many of the most recent
  24     dumps to display, starting with the newest one and going back in time, use
  25     the <emphasis role="bold">-ndumps</emphasis> argument. To display more detailed information about a
  26     single dump, use the <emphasis role="bold">-id</emphasis> argument. To display the records for the 10
  27     most recent dumps, omit both the <emphasis role="bold">-ndumps</emphasis> and <emphasis role="bold">-id</emphasis> arguments.</para>
  28
  29     <para>The <emphasis role="bold">-verbose</emphasis> flag produces very detailed information that is useful
  30     mostly for debugging purposes. It can be combined only with the <emphasis role="bold">-id</emphasis>
  31     argument.</para>
  32
  33   </refsect1>
  34   <refsect1>
  35     <title>Options</title>
  36     <variablelist>
  37       <varlistentry>
  38         <term><emphasis role="bold">-ndumps</emphasis> &lt;<emphasis>number of dumps</emphasis>&gt;</term>
  39         <listitem>
  40           <para>Displays the Backup Database record for each of the specified number of
  41           dumps that were most recently performed. If the database contains fewer
  42           dumps than are requested, the output includes the records for all existing
  43           dumps. Do not combine this argument with the <emphasis role="bold">-id</emphasis> or <emphasis role="bold">-verbose</emphasis>
  44           options; omit all options to display the records for the last 10 dumps.</para>
  45
  46         </listitem>
  47       </varlistentry>
  48       <varlistentry>
  49         <term><emphasis role="bold">-id</emphasis> &lt;<emphasis>dump id</emphasis>&gt;</term>
  50         <listitem>
  51           <para>Specifies the dump ID number of a single dump for which to display the
  52           Backup Database record. Precede the <emphasis>dump id</emphasis> value with the <emphasis role="bold">-id</emphasis>
  53           switch; otherwise, the command interpreter interprets it as the value of
  54           the <emphasis role="bold">-ndumps</emphasis> argument. Combine this argument with the <emphasis role="bold">-verbose</emphasis> flag,
  55           but not with the <emphasis role="bold">-ndumps</emphasis> argument; omit all options to display the
  56           records for the last 10 dumps.</para>
  57
  58         </listitem>
  59       </varlistentry>
  60       <varlistentry>
  61         <term><emphasis role="bold">-verbose</emphasis></term>
  62         <listitem>
  63           <para>Provides more detailed information about the dump specified with the
  64           <emphasis role="bold">-id</emphasis> argument, which must be provided along with it. Do not combine this
  65           flag with the <emphasis role="bold">-ndumps</emphasis> argument.</para>
  66
  67         </listitem>
  68       </varlistentry>
  69       <varlistentry>
  70         <term><emphasis role="bold">-localauth</emphasis></term>
  71         <listitem>
  72           <para>Constructs a server ticket using a key from the local
  73           <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
  74           it to the Backup Server, Volume Server and VL Server during mutual
  75           authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
  76           more details, see <link linkend="backup8">backup(8)</link>.</para>
  77
  78         </listitem>
  79       </varlistentry>
  80       <varlistentry>
  81         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
  82         <listitem>
  83           <para>Names the cell in which to run the command. Do not combine this argument
  84           with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
  85
  86         </listitem>
  87       </varlistentry>
  88       <varlistentry>
  89         <term><emphasis role="bold">-help</emphasis></term>
  90         <listitem>
  91           <para>Prints the online help for this command. All other valid options are
  92           ignored.</para>
  93
  94         </listitem>
  95       </varlistentry>
  96     </variablelist>
  97   </refsect1>
  98   <refsect1>
  99     <title>Output</title>
 100     <para>If the <emphasis role="bold">-ndumps</emphasis> argument is provided, the output presents the following
 101     information in table form, with a separate line for each dump:</para>
 102
 103     <variablelist>
 104       <varlistentry>
 105         <term>dumpid</term>
 106         <listitem>
 107           <para>The dump ID number.</para>
 108
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term>parentid</term>
 113         <listitem>
 114           <para>The dump ID number of the dump's parent dump. A value of <computeroutput>0</computeroutput> (zero)
 115           identifies a full dump.</para>
 116
 117         </listitem>
 118       </varlistentry>
 119       <varlistentry>
 120         <term>lv</term>
 121         <listitem>
 122           <para>The depth in the dump hierarchy of the dump level used to create the
 123           dump. A value of <computeroutput>0</computeroutput> (zero) identifies a full dump, in which case the
 124           value in the <computeroutput>parentid</computeroutput> field is also <computeroutput>0</computeroutput>. A value of <computeroutput>1</computeroutput> or greater
 125           indicates an incremental dump made at the corresponding level in the dump
 126           hierarchy.</para>
 127
 128         </listitem>
 129       </varlistentry>
 130       <varlistentry>
 131         <term>created</term>
 132         <listitem>
 133           <para>The date and time at which the Backup System started the dump operation
 134           that created the dump.</para>
 135
 136         </listitem>
 137       </varlistentry>
 138       <varlistentry>
 139         <term>nt</term>
 140         <listitem>
 141           <para>The number of tapes that contain the data in the dump. A value of <computeroutput>0</computeroutput>
 142           (zero) indicates that the dump operation was terminated or failed. Use the
 143           <emphasis role="bold">backup deletedump</emphasis> command to remove such entries.</para>
 144
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term>nvols</term>
 149         <listitem>
 150           <para>The number of volumes from which the dump includes data. If a volume spans
 151           tapes, it is counted twice. A value of <computeroutput>0</computeroutput> (zero) indicates that the dump
 152           operation was terminated or failed; the value in the <computeroutput>nt</computeroutput> field is also
 153           <computeroutput>0</computeroutput> in this case.</para>
 154
 155         </listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term>dump name</term>
 159         <listitem>
 160           <para>The dump name in the form</para>
 161
 162 <programlisting>
 163    &amp;lt;volume_set_name&amp;gt;.&amp;lt;dump_level_name&amp;gt; (&amp;lt;initial_dump_ID&amp;gt;)
 164
 165 </programlisting>
 166             <para>where &lt;volume_set_name&gt; is the name of the volume set, and
 167             &lt;dump_level_name&gt; is the last element in the dump level pathname at which
 168             the volume set was dumped.</para>
 169
 170             <para>The &lt;initial_dump_ID&gt;, if displayed, is the dump ID of the initial dump in
 171             the dump set to which this dump belongs. If there is no value in
 172             parentheses, the dump is the initial dump in a dump set that has no
 173             appended dumps.</para>
 174
 175           </listitem>
 176         </varlistentry>
 177       </variablelist>
 178       <para>If the <emphasis role="bold">-id</emphasis> argument is provided alone, the first line of output begins
 179       with the string <computeroutput>Dump</computeroutput> and reports information for the entire dump in the
 180       following fields:</para>
 181
 182       <variablelist>
 183         <varlistentry>
 184           <term>id</term>
 185           <listitem>
 186             <para>The dump ID number.</para>
 187
 188           </listitem>
 189         </varlistentry>
 190         <varlistentry>
 191           <term>level</term>
 192           <listitem>
 193             <para>The depth in the dump hierarchy of the dump level used to create the
 194             dump. A value of <computeroutput>0</computeroutput> (zero) identifies a full dump. A value of <computeroutput>1</computeroutput> (one)
 195             or greater indicates an incremental dump made at the specified level in
 196             the dump hierarchy.</para>
 197
 198           </listitem>
 199         </varlistentry>
 200         <varlistentry>
 201           <term>volumes</term>
 202           <listitem>
 203             <para>The number of volumes for which the dump includes data.</para>
 204
 205           </listitem>
 206         </varlistentry>
 207         <varlistentry>
 208           <term>created</term>
 209           <listitem>
 210             <para>The date and time at which the dump operation began.</para>
 211
 212           </listitem>
 213         </varlistentry>
 214       </variablelist>
 215       <para>If an XBSA server was the backup medium for the dump (rather than a tape
 216       device or backup data file), the following line appears next:</para>
 217
 218 <programlisting>
 219    Backup Service: &amp;lt;XBSA_program&amp;gt;: Server: &amp;lt;hostname&amp;gt;
 220
 221 </programlisting>
 222         <para>where &lt;XBSA_program&gt; is the name of the XBSA-compliant program and
 223         &lt;hostname&gt; is the name of the machine on which the program runs.</para>
 224
 225         <para>Next the output includes an entry for each tape that houses volume data
 226         from the dump. Following the string <computeroutput>Tape</computeroutput>, the first two lines of each
 227         entry report information about that tape in the following fields:</para>
 228
 229         <variablelist>
 230           <varlistentry>
 231             <term>name</term>
 232             <listitem>
 233               <para>The tape's permanent name if it has one, or its AFS tape name otherwise,
 234               and its tape ID number in parentheses.</para>
 235
 236             </listitem>
 237           </varlistentry>
 238           <varlistentry>
 239             <term>nVolumes</term>
 240             <listitem>
 241               <para>The number of volumes for which this tape includes dump data.</para>
 242
 243             </listitem>
 244           </varlistentry>
 245           <varlistentry>
 246             <term>created</term>
 247             <listitem>
 248               <para>The date and time at which the Tape Coordinator began writing data to this
 249               tape.</para>
 250
 251             </listitem>
 252           </varlistentry>
 253         </variablelist>
 254         <para>Following another blank line, the tape-specific information concludes with
 255         a table that includes a line for each volume dump on the tape. The
 256         information appears in columns with the following headings:</para>
 257
 258         <variablelist>
 259           <varlistentry>
 260             <term>Pos</term>
 261             <listitem>
 262               <para>The relative position of each volume in this tape or file. On a tape, the
 263               counter begins at position 2 (the tape label occupies position 1), and
 264               increments by one for each volume. For volumes in a backup data file, the
 265               position numbers start with 1 and do not usually increment only by one,
 266               because each is the ordinal of the 16 KB offset in the file at which the
 267               volume's data begins. The difference between the position numbers
 268               therefore indicates how many 16 KB blocks each volume's data occupies. For
 269               example, if the second volume is at position 5 and the third volume in the
 270               list is at position 9, that means that the dump of the second volume
 271               occupies 64 KB (four 16-KB blocks) of space in the file.</para>
 272
 273             </listitem>
 274           </varlistentry>
 275           <varlistentry>
 276             <term>Clone time</term>
 277             <listitem>
 278               <para>For a backup or read-only volume, the time at which it was cloned from its
 279               read/write source. For a Read/Write volume, it is the same as the dump
 280               creation date reported on the first line of the output.</para>
 281
 282             </listitem>
 283           </varlistentry>
 284           <varlistentry>
 285             <term>Nbytes</term>
 286             <listitem>
 287               <para>The number of bytes of data in the dump of the volume.</para>
 288
 289             </listitem>
 290           </varlistentry>
 291           <varlistentry>
 292             <term>Volume</term>
 293             <listitem>
 294               <para>The volume name, complete with <computeroutput>.backup</computeroutput> or <computeroutput>.readonly</computeroutput> extension if
 295               appropriate.</para>
 296
 297             </listitem>
 298           </varlistentry>
 299         </variablelist>
 300         <para>If both the <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-verbose</emphasis> options are provided, the output is
 301         divided into several sections:</para>
 302
 303         <itemizedlist>
 304           <listitem>
 305             <para>The first section, headed by the underlined string <computeroutput>Dump</computeroutput>, includes
 306             information about the entire dump. The fields labeled <computeroutput>id</computeroutput>, <computeroutput>level</computeroutput>,
 307             <computeroutput>created</computeroutput>, and <computeroutput>nVolumes</computeroutput> report the same values (though in a different
 308             order) as appear on the first line of output when the <emphasis role="bold">-id</emphasis> argument is
 309             provided by itself.  Other fields of potential interest to the backup
 310             operator are:</para>
 311
 312             <variablelist>
 313               <varlistentry>
 314                 <term>Group id</term>
 315                 <listitem>
 316                   <para>The dump's <emphasis>group ID number</emphasis>, which is recorded in the dump's Backup
 317                   Database record if the <computeroutput>GROUPID</computeroutput> instruction appears in the Tape
 318                   Coordinator's <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>tcid</emphasis><replaceable></replaceable> file when the dump is
 319                   created.</para>
 320
 321                 </listitem>
 322               </varlistentry>
 323               <varlistentry>
 324                 <term>maxTapes</term>
 325                 <listitem>
 326                   <para>The number of tapes that contain the dump set to which this dump belongs.</para>
 327
 328                 </listitem>
 329               </varlistentry>
 330               <varlistentry>
 331                 <term>Start Tape Seq</term>
 332                 <listitem>
 333                   <para>The ordinal of the tape on which this dump begins in the set of tapes that
 334                   contain the dump set.</para>
 335
 336                 </listitem>
 337               </varlistentry>
 338             </variablelist>
 339           </listitem>
 340           <listitem>
 341             <para>For each tape that contains data from this dump, there follows a section
 342             headed by the underlined string <computeroutput>Tape</computeroutput>. The fields labeled <computeroutput>name</computeroutput>,
 343             <computeroutput>written</computeroutput>, and <computeroutput>nVolumes</computeroutput> report the same values (though in a different
 344             order) as appear on the second and third lines of output when the <emphasis role="bold">-id</emphasis>
 345             argument is provided by itself. Other fields of potential interest to the
 346             backup operator are:</para>
 347
 348             <variablelist>
 349               <varlistentry>
 350                 <term>expires</term>
 351                 <listitem>
 352                   <para>The date and time when this tape can be recycled, because all dumps it
 353                   contains have expired.</para>
 354
 355                 </listitem>
 356               </varlistentry>
 357               <varlistentry>
 358                 <term>nMBytes Data and nBytes Data</term>
 359                 <listitem>
 360                   <para>Summed together, these fields represent the total amount of dumped data
 361                   actually from volumes (as opposed to labels, filemarks, and other
 362                   markers).</para>
 363
 364                 </listitem>
 365               </varlistentry>
 366               <varlistentry>
 367                 <term>KBytes Tape Used</term>
 368                 <listitem>
 369                   <para>The number of kilobytes of tape (or disk space, for a backup data file)
 370                   used to store the dump data. It is generally larger than the sum of the
 371                   values in the <computeroutput>nMBytes Data</computeroutput> and <computeroutput>nBytes Data</computeroutput> fields, because it
 372                   includes the space required for the label, file marks and other markers,
 373                   and because the Backup System writes data at 16 KB offsets, even if the
 374                   data in a given block doesn't fill the entire 16 KB.</para>
 375
 376                 </listitem>
 377               </varlistentry>
 378             </variablelist>
 379           </listitem>
 380           <listitem>
 381             <para>For each volume on a given tape, there follows a section headed by the
 382             underlined string <computeroutput>Volume</computeroutput>. The fields labeled <computeroutput>name</computeroutput>, <computeroutput>position</computeroutput>,
 383             <computeroutput>clone</computeroutput>, and <computeroutput>nBytes</computeroutput> report the same values (though in a different
 384             order) as appear in the table that lists the volumes in each tape when the
 385             <emphasis role="bold">-id</emphasis> argument is provided by itself. Other fields of potential interest
 386             to the backup operator are:</para>
 387
 388             <variablelist>
 389               <varlistentry>
 390                 <term>id</term>
 391                 <listitem>
 392                   <para>The volume ID.</para>
 393
 394                 </listitem>
 395               </varlistentry>
 396               <varlistentry>
 397                 <term>tape</term>
 398                 <listitem>
 399                   <para>The name of the tape containing this volume data.</para>
 400
 401                 </listitem>
 402               </varlistentry>
 403             </variablelist>
 404           </listitem>
 405         </itemizedlist>
 406       </refsect1>
 407       <refsect1>
 408         <title>Examples</title>
 409         <para>The following example displays information about the last five dumps:</para>
 410
 411 <programlisting>
 412    % backup dumpinfo -ndumps 5
 413       dumpid   parentid lv created          nt nvols dump name
 414    924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
 415    924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
 416    924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
 417    924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
 418    925033000          0 0  04/25/1999 05:36  2    73 sys.week
 419
 420 </programlisting>
 421           <para>The following example displays a more detailed record for a single dump.</para>
 422
 423 <programlisting>
 424    % backup dumpinfo -id 922097346
 425    Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
 426    Tape: name monday.user.backup (922097346)
 427    nVolumes 1, created 03/22/1999 05:09
 428     Pos       Clone time   Nbytes Volume
 429       1 03/22/1999 04:43 27787914 user.pat.backup
 430
 431 </programlisting>
 432             <para>The following example displays even more detailed information about the
 433             dump displayed in the previous example (dump ID 922097346). This example
 434             includes only one exemplar of each type of section (<computeroutput>Dump</computeroutput>, <computeroutput>Tape</computeroutput>, and
 435             <computeroutput>Volume</computeroutput>):</para>
 436
 437 <programlisting>
 438    % backup dumpinfo -id 922097346 -verbose
 439    Dump
 440    ----
 441    id = 922097346
 442    Initial id = 0
 443    Appended id = 922099568
 444    parent = 0
 445    level = 0
 446    flags = 0x0
 447    volumeSet = user
 448    dump path = /monday1
 449    name = user.monday1
 450    created = Mon Mar 22 05:09:06 1999
 451    nVolumes = 1
 452    id  = 0
 453    tapeServer =
 454    format= user.monday1.%d
 455    maxTapes = 1
 456    Start Tape Seq = 1
 457    name = pat
 458    instance =
 459    cell =
 460    Tape
 461    ----
 462    tape name = monday.user.backup
 463    AFS tape name = user.monday1.1
 464    flags = 0x20
 465    written = Mon Mar 22 05:09:06 1999
 466    expires = NEVER
 467    kBytes Tape Used = 121
 468    nMBytes Data = 0
 469    nBytes  Data = 19092
 470    nFiles = 0
 471    nVolumes = 1
 472    seq = 1
 473    tapeid = 0
 474    useCount = 1
 475    dump = 922097346
 476    Volume
 477    ------
 478    name = user.pat.backup
 479    flags = 0x18
 480    id = 536871640
 481    server =
 482    partition = 0
 483    nFrags = 1
 484    position = 2
 485    clone = Mon Mar 22 04:43:06 1999
 486    startByte = 0
 487    nBytes = 19092
 488    seq = 0
 489    dump = 922097346
 490    tape = user.monday1.1
 491
 492 </programlisting>
 493             </refsect1>
 494             <refsect1>
 495               <title>Privilege Required</title>
 496               <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
 497               machine where the Backup Server is running, or must be logged onto a
 498               server machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
 499               included.</para>
 500
 501             </refsect1>
 502             <refsect1>
 503               <title>See Also</title>
 504               <para><link linkend="butc5">butc(5)</link>,
 505               <link linkend="backup8">backup(8)</link>,
 506               <link linkend="backup_deletedump8">backup_deletedump(8)</link></para>
 507
 508             </refsect1>
 509             <refsect1>
 510               <title>Copyright</title>
 511               <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 512
 513               <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 514               converted from HTML to POD by software written by Chas Williams and Russ
 515               Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 516
 517             </refsect1>
 518           </refentry>