openafs/doc/xml/AdminReference/sect1/vos_restore.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="vos_restore1">
  <refmeta>
    <refentrytitle>vos restore</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>vos restore</refname>
    <refpurpose>Converts an ASCII dump file into an AFS volume</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Synopsis</title>
    <para><emphasis role="bold">vos restore</emphasis> <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;
        <emphasis role="bold">-name</emphasis> &lt;<emphasis>name of volume to be restored</emphasis>&gt; [<emphasis role="bold">-file</emphasis> &lt;<emphasis>dump file</emphasis>&gt;]
        [<emphasis role="bold">-id</emphasis> &lt;<emphasis>volume ID</emphasis>&gt;] [<emphasis role="bold">-overwrite</emphasis> (abort | full | incremental)]
        [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [-verbose]
        [<emphasis role="bold">-help</emphasis>]</para>

    <para><emphasis role="bold">vos res</emphasis> <emphasis role="bold">-s</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-p</emphasis> &lt;<emphasis>partition name</emphasis>&gt;
        <emphasis role="bold">-na</emphasis> &lt;<emphasis>name of volume to be restored</emphasis>&gt; [<emphasis role="bold">-f</emphasis> &lt;<emphasis>dump file</emphasis>&gt;]
        [<emphasis role="bold">-i</emphasis> &lt;<emphasis>volume ID</emphasis>&gt;] [<emphasis role="bold">-o</emphasis> (a | f | i)] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<emphasis role="bold">-no</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-v</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>

  </refsect1>
  <refsect1>
    <title>Description</title>
    <para>The <emphasis role="bold">vos restore</emphasis> command converts a volume dump file previously created
    with the <emphasis role="bold">vos dump</emphasis> command from ASCII into the volume format appropriate
    for the machine type indicated by the <emphasis role="bold">-server</emphasis> argument, and restores it
    as a read/write volume to the partition named by the <emphasis role="bold">-partition</emphasis>
    argument on that machine. The Volume Server assigns the volume name
    indicated with the <emphasis role="bold">-name</emphasis> argument, and resets the volume's creation
    timestamp to the time at which the restore operation begins (the creation
    timestamp is stored in the volume header and reported in the <computeroutput>Creation</computeroutput>
    field in the output from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.)</para>

    <para>Use the <emphasis role="bold">-file</emphasis> argument to name the dump file, or omit the argument to
    provide the file via the standard input stream, presumably through a
    pipe. The pipe can be named, which enables interoperation with third-party
    backup utilities.</para>

    <para>As described in the following list, the command can create a completely
    new volume or overwrite an existing volume. In all cases, the full dump of
    the volume must be restored before any incremental dumps. If there are
    multiple incremental dump files, they must be restored in the order they
    were created.</para>

    <itemizedlist>
      <listitem>
        <para>To create a new read/write volume, use the <emphasis role="bold">-name</emphasis> argument to specify a
        volume name that does not already exist in the Volume Location Database
        (VLDB), and the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to specify the new
        volume's site. It is best to omit the <emphasis role="bold">-id</emphasis> argument so that the Volume
        Location (VL) Server allocates a volume ID automatically. Do not include
        the <emphasis role="bold">-overwrite</emphasis> argument, because there is no existing volume to
        overwrite.</para>

      </listitem>
      <listitem>
        <para>To overwrite an existing volume at its current site, specify its name and
        site with the <emphasis role="bold">-name</emphasis>, <emphasis role="bold">-server</emphasis>, and <emphasis role="bold">-partition</emphasis> arguments. The
        volume retains its current volume ID number unless the <emphasis role="bold">-id</emphasis> argument is
        provided. Specify the value <computeroutput>f</computeroutput> or <computeroutput>i</computeroutput> for the <emphasis role="bold">-overwrite</emphasis> argument to
        indicate whether the dump file is full or incremental, respectively.</para>

      </listitem>
      <listitem>
        <para>To overwrite an existing volume and move it to a new site, specify its
        name and the new site with the <emphasis role="bold">-name</emphasis>, <emphasis role="bold">-server</emphasis>, and <emphasis role="bold">-partition</emphasis>
        arguments. The volume retains its current volume ID number unless the
        <emphasis role="bold">-id</emphasis> argument is provided. The volume is removed from its original
        site. Specify the value <computeroutput>f</computeroutput> for the <emphasis role="bold">-overwrite</emphasis> argument to indicate
        that the dump file is a full dump (it is not possible to restore an
        incremental dump and move the volume at the same time).</para>

      </listitem>
    </itemizedlist>
    <para>If the volume named by the <emphasis role="bold">-name</emphasis> argument already exists and the
    <emphasis role="bold">-overwrite</emphasis> argument is omitted, the command interpreter produces the
    following prompt:</para>

<programlisting>
   Do you want to do a full/incremental restore or abort? [fia](a):

</programlisting>
      <para>Respond by entering one of the following values:</para>

      <itemizedlist>
        <listitem>
          <para><computeroutput>f</computeroutput> if restoring a full dump file</para>

        </listitem>
        <listitem>
          <para><computeroutput>i</computeroutput> if restoring an incremental dump file</para>

        </listitem>
        <listitem>
          <para><computeroutput>a</computeroutput> or Return to cancel the restore operation</para>

        </listitem>
      </itemizedlist>
    </refsect1>
    <refsect1>
      <title>Cautions</title>
      <para>If the <emphasis role="bold">-file</emphasis> argument is omitted, the issuer must provide all other
      necessary arguments, because the standard input stream is unavailable for
      responding to the command interpreter's prompts for missing
      information. In particular, the issuer must provide the <emphasis role="bold">-overwrite</emphasis>
      argument if overwriting an existing volume.</para>

    </refsect1>
    <refsect1>
      <title>Options</title>
      <variablelist>
        <varlistentry>
          <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>server name</emphasis>&gt;</term>
          <listitem>
            <para>Identifies the file server machine onto which to restore the
            volume. Provide the machine's IP address or its host name (either fully
            qualified or using an unambiguous abbreviation). For details, see
            <link linkend="vos1">vos(1)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;</term>
          <listitem>
            <para>Identifies the partition (on the file server machine specified by the
            <emphasis role="bold">-server</emphasis> argument) onto which to restore the volume. Provide the
            partition's complete name with preceding slash (for example, <replaceable>/vicepa</replaceable>)
            or use one of the three acceptable abbreviated forms. For details, see
            <link linkend="vos1">vos(1)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-name</emphasis> &lt;<emphasis>name of volume</emphasis>&gt;</term>
          <listitem>
            <para>Specifies the name under which to restore the volume. It can be up to 22
            characters long, but cannot end with a <computeroutput>.readonly</computeroutput> or <computeroutput>.backup</computeroutput>
            extension. If the volume already exists, it is overwritten subject to the
            value of the <emphasis role="bold">-overwrite</emphasis> argument.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-file</emphasis> &lt;<emphasis>dump file</emphasis>&gt;</term>
          <listitem>
            <para>Names the dump file to restore. Incomplete pathnames are interpreted
            relative to the current working directory. Omit this argument to provide
            the dump file via the standard input stream.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-id</emphasis> &lt;<emphasis>volume ID</emphasis>&gt;</term>
          <listitem>
            <para>Specifies the volume ID number to assign to the restored volume.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-overwrite</emphasis> (a | f | i)</term>
          <listitem>
            <para>Specifies which type of dump file is being restored when overwriting an
            existing volume. Provide one of the following values:</para>

            <itemizedlist>
              <listitem>
                <para><computeroutput>a</computeroutput> to terminate the restore operation.</para>

              </listitem>
              <listitem>
                <para><computeroutput>f</computeroutput> if restoring a full dump file.</para>

              </listitem>
              <listitem>
                <para><computeroutput>i</computeroutput> if restoring an incremental dump file. This value is not acceptable
                if the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments do not indicate the volume's
                current site.</para>

              </listitem>
            </itemizedlist>
            <para>This argument is mandatory if the <emphasis role="bold">-file</emphasis> argument is not provided.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
          <listitem>
            <para>Names the cell in which to run the command. Do not combine this argument
            with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-noauth</emphasis></term>
          <listitem>
            <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. Do not
            combine this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see
            <link linkend="vos1">vos(1)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-localauth</emphasis></term>
          <listitem>
            <para>Constructs a server ticket using a key from the local
            <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">vos</emphasis> command interpreter presents it
            to the Volume Server and Volume Location Server during mutual
            authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument or
            <emphasis role="bold">-noauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-verbose</emphasis></term>
          <listitem>
            <para>Produces on the standard output stream a detailed trace of the command's
            execution. If this argument is omitted, only warnings and error messages
            appear.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-help</emphasis></term>
          <listitem>
            <para>Prints the online help for this command. All other valid options are
            ignored.</para>

          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>
    <refsect1>
      <title>Examples</title>
      <para>The following command restores the contents of the dump file
      <replaceable>/afs/abc.com/common/dumps/terry.dump</replaceable> to the <replaceable>/vicepc</replaceable> partition on the
      file server machine <computeroutput>fs3.abc.com</computeroutput>. The restored volume is named
      <computeroutput>user.terry</computeroutput>.</para>

<programlisting>
   % cd /afs/abc.com/common/dumps
   % vos restore -file terry.dump -server fs3.abc.com -partition c \
       -name user.terry

</programlisting>
      </refsect1>
      <refsect1>
        <title>Privilege Required</title>
        <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
        machine specified with the <emphasis role="bold">-server</emphasis> argument and on each database server
        machine. If the <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be
        logged on to a server machine as the local superuser <computeroutput>root</computeroutput>.</para>

      </refsect1>
      <refsect1>
        <title>See Also</title>
        <para><link linkend="vos1">vos(1)</link>,
        <link linkend="vos_dump1">vos_dump(1)</link>,
        <link linkend="vos_examine1">vos_examine(1)</link>,
        <link linkend="vos_listvol1">vos_listvol(1)</link></para>

      </refsect1>
      <refsect1>
        <title>Copyright</title>
        <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>

        <para>This documentation is covered by the IBM Public License Version 1.0.  It was
        converted from HTML to POD by software written by Chas Williams and Russ
        Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>

      </refsect1>
    </refentry>