xml-docbook-documentation-first-pass-20060915

[openafs.git] / doc / xml / AdminReference / sect1 / vos_rename.xml

diff --git a/doc/xml/AdminReference/sect1/vos_rename.xml b/doc/xml/AdminReference/sect1/vos_rename.xml
new file mode 100644 (file)
index 0000000..d844c8f
--- /dev/null
+++ b/doc/xml/AdminReference/sect1/vos_rename.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry id="vos_rename1">
+  <refmeta>
+    <refentrytitle>vos rename</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>vos rename</refname>
+    <refpurpose>Renames a volume</refpurpose>
+  </refnamediv>
+  <refsect1>
+    <title>Synopsis</title>
+    <para><emphasis role="bold">vos rename</emphasis> <emphasis role="bold">-oldname</emphasis> &lt;<emphasis>old volume name</emphasis>&gt;
+        <emphasis role="bold">-newname</emphasis> &lt;<emphasis>new volume name</emphasis>&gt; [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
+        [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-verbose</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
+
+    <para><emphasis role="bold">vos ren</emphasis> <emphasis role="bold">-o</emphasis> &lt;<emphasis>old volume name</emphasis>&gt; <emphasis role="bold">-ne</emphasis> &lt;<emphasis>new volume name</emphasis>&gt;
+        [-c &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 rename</emphasis> command changes the name of the read/write volume
+    specified with the <emphasis role="bold">-oldname</emphasis> argument to the name specified with the
+    <emphasis role="bold">-newname</emphasis> argument. The names of the read/write's read-only copies and
+    backup copy, if any, change automatically to match.</para>
+
+    <para>After issuing this command, remember to correct any mount points that
+    refer to the old volume name, by removing the old mount point with the
+    <emphasis role="bold">fs rmmount</emphasis> command and creating a new one with the <emphasis role="bold">fs mkmount</emphasis>
+    command.</para>
+
+  </refsect1>
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+        <term><emphasis role="bold">-oldname</emphasis> &lt;<emphasis>old volume name</emphasis>&gt;</term>
+        <listitem>
+          <para>Is the current name of the read/write volume.</para>
+
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis role="bold">-newname</emphasis> &lt;<emphasis>new volume name</emphasis>&gt;</term>
+        <listitem>
+          <para>Is the desired new name for the volume.</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>Output</title>
+    <para>The <emphasis role="bold">vos rename</emphasis> command produces no output if the command succeeds.</para>
+
+    <para>If the volume named by the <emphasis role="bold">-oldname</emphasis> argument does not exist, the
+    following message appears:</para>
+
+<programlisting>
+   vos: Could not find entry for volume &amp;lt;old volume name&amp;gt;.
+
+</programlisting>
+    </refsect1>
+    <refsect1>
+      <title>Examples</title>
+      <para>The following example changes the mistaken volume name <computeroutput>sun4x_56.afsws</computeroutput>
+      to the correct alternative <computeroutput>sun4x_56.usr.afsws</computeroutput>.</para>
+
+<programlisting>
+   % vos rename -oldname sun4x_56.afsws -newname sun4x_56.usr.afsws
+
+</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></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>