doc/xml/AdminReference/sect1/vos_dump.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="vos_dump1">
   3   <refmeta>
   4     <refentrytitle>vos dump</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>vos dump</refname>
   9     <refpurpose>Converts a volume into ASCII format and writes it to a file</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">vos dump</emphasis> <emphasis role="bold">-id</emphasis> &lt;<emphasis>volume name or ID</emphasis>&gt; [<emphasis role="bold">-time</emphasis> &lt;<emphasis>dump from time</emphasis>&gt;]
  14         [<emphasis role="bold">-file</emphasis> &lt;<emphasis>dump file</emphasis>&gt;] [<emphasis role="bold">-server</emphasis> &lt;<emphasis>server</emphasis>&gt;]
  15         [<emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition</emphasis>&gt;] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  16         [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-verbose</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
  17
  18     <para><emphasis role="bold">vos du</emphasis> <emphasis role="bold">-i</emphasis> &lt;<emphasis>volume name or ID</emphasis>&gt; [<emphasis role="bold">-t</emphasis> &lt;<emphasis>dump from time</emphasis>&gt;]
  19         [<emphasis role="bold">-f</emphasis> &lt;<emphasis>dump file</emphasis>&gt;] [<emphasis role="bold">-s</emphasis> &lt;<emphasis>server</emphasis>&gt;] [<emphasis role="bold">-p</emphasis> &lt;<emphasis>partition</emphasis>&gt;]
  20         [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-v</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  21
  22   </refsect1>
  23   <refsect1>
  24     <title>Description</title>
  25     <para>The <emphasis role="bold">vos dump</emphasis> command converts the contents of the indicated volume,
  26     which can be read/write, read-only or backup, into ASCII format. The
  27     Volume Server writes the converted contents to the file named by the
  28     <emphasis role="bold">-file</emphasis> argument, or to the standard output stream. In the latter case,
  29     the output can be directed to a named pipe, which enables interoperation
  30     with third-party backup utilities.</para>
  31
  32     <para>To dump the complete contents of a volume (create a <emphasis>full dump</emphasis>), omit
  33     the <emphasis role="bold">-time</emphasis> argument or specify the value <computeroutput>0</computeroutput> (zero) for it. To create
  34     an <emphasis>incremental dump</emphasis>, which includes only the files and directories in
  35     the volume that have modification timestamps later than a certain time,
  36     specify a date and time as the value for the <emphasis role="bold">-time</emphasis> argument.</para>
  37
  38     <para>By default, the vos command interpreter consults the Volume Location
  39     Database (VLDB) to learn the volume's location, so the <emphasis role="bold">-server</emphasis> and
  40     <emphasis role="bold">-partition</emphasis> arguments are not required. If the <emphasis role="bold">-id</emphasis> argument
  41     identifies a read-only volume that resides at multiple sites, the command
  42     dumps the version from just one of them (normally, the one listed first in
  43     the volume's VLDB entry as reported by the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos
  44     listvldb</emphasis> command). To dump the read-only volume from a particular site,
  45     use the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to specify the site. To
  46     bypass the VLDB lookup entirely, provide a volume ID number (rather than a
  47     volume name) as the value for the <emphasis role="bold">-id</emphasis> argument, together with the
  48     <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. This makes it possible to dump a
  49     volume for which there is no VLDB entry.</para>
  50
  51     <para>During the dump operation, the volume is inaccessible both to Cache
  52     Managers and to other volume operations. Dumping a volume does not
  53     otherwise affect its status on the partition or its VLDB entry.</para>
  54
  55     <para>To restore a dumped volume back into AFS, use the <emphasis role="bold">vos restore</emphasis> command.</para>
  56
  57   </refsect1>
  58   <refsect1>
  59     <title>Cautions</title>
  60     <para>Support for incremental dumps is provided to facilitate interoperation
  61     with third-party backup utilities. The <emphasis role="bold">vos dump</emphasis> command does not
  62     provide any of the administrative facilities of an actual backup system,
  63     so the administrator must keep manual records of dump times and the
  64     relationship between full and incremental dumps of a volume. For a
  65     volume's contents to be consistent after restoration of incremental dumps,
  66     there must be no gap between the time at which a prior dump of the volume
  67     was created and the value of the <emphasis role="bold">-time</emphasis> argument to the <emphasis role="bold">vos dump</emphasis>
  68     command that creates the incremental dump. More specifically, for a
  69     read/write volume, the <emphasis role="bold">-time</emphasis> argument must specify the time that the
  70     prior dump was performed, and for a read-only or backup volume it must
  71     specify the time that the volume was last released (using the <emphasis role="bold">vos
  72     release</emphasis> command) or cloned (using the <emphasis role="bold">vos backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis>
  73     command) prior to dumping it. The parent dump can be either a full dump or
  74     another incremental dump.</para>
  75
  76   </refsect1>
  77   <refsect1>
  78     <title>Options</title>
  79     <variablelist>
  80       <varlistentry>
  81         <term><emphasis role="bold">-id</emphasis> &lt;<emphasis>volume name or ID</emphasis>&gt;</term>
  82         <listitem>
  83           <para>Specifies either the complete name or volume ID number of the read/write,
  84           read-only, or backup volume to dump.</para>
  85
  86         </listitem>
  87       </varlistentry>
  88       <varlistentry>
  89         <term><emphasis role="bold">-time</emphasis> &lt;<emphasis>dump from time</emphasis>&gt;</term>
  90         <listitem>
  91           <para>Specifies whether the dump is full or incremental. Omit this argument to
  92           create a full dump, or provide one of three acceptable values:</para>
  93
  94           <itemizedlist>
  95             <listitem>
  96               <para>The value <computeroutput>0</computeroutput> (zero) to create a full dump.</para>
  97
  98             </listitem>
  99             <listitem>
 100               <para>A date in the format <emphasis>mm</emphasis><emphasis role="bold">/</emphasis><emphasis>dd</emphasis><emphasis role="bold">/</emphasis><emphasis>yyyy</emphasis> (month, day and year) to
 101               create an incremental dump that includes only files and directories with
 102               modification timestamps later than midnight (12:00 a.m.) on the indicated
 103               date. Valid values for the year range from <computeroutput>1970</computeroutput> to <computeroutput>2037</computeroutput>; higher
 104               values are not valid because the latest possible date in the standard UNIX
 105               representation is in 2038. The command interpreter automatically reduces
 106               later dates to the maximum value. An example is <computeroutput>01/13/1999</computeroutput>.</para>
 107
 108             </listitem>
 109             <listitem>
 110               <para>A date and time in the format <emphasis role="bold">"</emphasis><emphasis>mm</emphasis><emphasis role="bold">/</emphasis><emphasis>dd</emphasis><emphasis role="bold">/</emphasis><emphasis>yyyy</emphasis>
 111               <emphasis>hh</emphasis><emphasis role="bold">:</emphasis><emphasis>MM</emphasis><emphasis role="bold">"</emphasis> to create an incremental dump that includes only files
 112               and directories with modification timestamps later than the specified date
 113               and time. The date format is the same as for a date alone. Express the
 114               time as hours and minutes (<emphasis>hh</emphasis>:<emphasis>MM</emphasis>) in 24-hour format (for example,
 115               <emphasis role="bold">20:30</emphasis> is 8:30 p.m.). Surround the entire expression with double quotes
 116               (<computeroutput>""</computeroutput>) because it contains a space.  An example is <computeroutput>"01/13/1999 22:30"</computeroutput>.</para>
 117
 118             </listitem>
 119           </itemizedlist>
 120         </listitem>
 121       </varlistentry>
 122       <varlistentry>
 123         <term><emphasis role="bold">-file</emphasis> &lt;<emphasis>dump file</emphasis>&gt;</term>
 124         <listitem>
 125           <para>Specifies the pathname of the file to which to write the dump. The file
 126           can be in AFS, but not in the volume being dumped. A partial pathname is
 127           interpreted relative to the current working directory. If this argument is
 128           omitted, the dump is directed to the standard output stream.</para>
 129
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>server name</emphasis>&gt;</term>
 134         <listitem>
 135           <para>Specifies the file server machine on which the volume resides.  Provide
 136           the <emphasis role="bold">-partition</emphasis> argument along with this one.</para>
 137
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;</term>
 142         <listitem>
 143           <para>Specifies the partition on which the volume resides. Provide the
 144           <emphasis role="bold">-server</emphasis> argument along with this one.</para>
 145
 146         </listitem>
 147       </varlistentry>
 148       <varlistentry>
 149         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis></term>
 150         <listitem>
 151           <para>Names the cell in which to run the command. Do not combine this argument
 152           with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>
 153
 154         </listitem>
 155       </varlistentry>
 156       <varlistentry>
 157         <term><emphasis role="bold">-noauth</emphasis></term>
 158         <listitem>
 159           <para>Assigns the unprivileged identity anonymous to the issuer. Do not combine
 160           this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>
 161
 162         </listitem>
 163       </varlistentry>
 164       <varlistentry>
 165         <term><emphasis role="bold">-localauth</emphasis></term>
 166         <listitem>
 167           <para>Constructs a server ticket using a key from the local
 168           <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">vos</emphasis> command interpreter presents it
 169           to the Volume Server and Volume Location Server during mutual
 170           authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument or
 171           <emphasis role="bold">-noauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>
 172
 173         </listitem>
 174       </varlistentry>
 175       <varlistentry>
 176         <term><emphasis role="bold">-verbose</emphasis></term>
 177         <listitem>
 178           <para>Produces on the standard output stream a detailed trace of the command's
 179           execution. If this argument is omitted, only warnings and error messages
 180           appear.</para>
 181
 182         </listitem>
 183       </varlistentry>
 184       <varlistentry>
 185         <term><emphasis role="bold">-help</emphasis></term>
 186         <listitem>
 187           <para>Prints the online help for this command. All other valid options are
 188           ignored.</para>
 189
 190         </listitem>
 191       </varlistentry>
 192     </variablelist>
 193   </refsect1>
 194   <refsect1>
 195     <title>Examples</title>
 196     <para>The following command writes a full dump of the volume <computeroutput>user.terry</computeroutput> to
 197     the file <replaceable>/afs/abc.com/common/dumps/terry.dump</replaceable>.</para>
 198
 199 <programlisting>
 200    % vos dump -id user.terry -time 0 -file /afs/abc.com/common/dumps/terry.dump
 201
 202 </programlisting>
 203       <para>The following command writes an incremental dump of the volume
 204       <computeroutput>user.smith</computeroutput> to the file <computeroutput>smith.990131.dump</computeroutput> in the current working
 205       directory. Only those files in the volume with modification time stamps
 206       later than 6:00 p.m. on 31 January 1999 are included in the dump.</para>
 207
 208 <programlisting>
 209    % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump
 210
 211 </programlisting>
 212       </refsect1>
 213       <refsect1>
 214         <title>Privilege Required</title>
 215         <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
 216         machine specified with the <emphasis role="bold">-server</emphasis> argument and on each database server
 217         machine. If the <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be
 218         logged on to a server machine as the local superuser <computeroutput>root</computeroutput>.</para>
 219
 220         <para>If the <emphasis role="bold">-file</emphasis> argument is included, the issuer must also have permission
 221         to insert and write in the directory that houses the file.</para>
 222
 223       </refsect1>
 224       <refsect1>
 225         <title>See Also</title>
 226         <para><link linkend="vos1">vos(1)</link>,
 227         <link linkend="vos_examine1">vos_examine(1)</link>,
 228         <link linkend="vos_listvldb1">vos_listvldb(1)</link>,
 229         <link linkend="vos_restore1">vos_restore(1)</link></para>
 230
 231       </refsect1>
 232       <refsect1>
 233         <title>Copyright</title>
 234         <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 235
 236         <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 237         converted from HTML to POD by software written by Chas Williams and Russ
 238         Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 239
 240       </refsect1>
 241     </refentry>