doc/xml/AdminReference/sect1/vos_release.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="vos_release1">
   3   <refmeta>
   4     <refentrytitle>vos release</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>vos release</refname>
   9     <refpurpose>Updates read-only volumes to match the read/write source volume</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">vos release</emphasis> <emphasis role="bold">-id</emphasis> &lt;<emphasis>volume name or ID</emphasis>&gt; [<emphasis role="bold">-f</emphasis>]
  14         [<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>]
  15         [<emphasis role="bold">-help</emphasis>]</para>
  16
  17     <para><emphasis role="bold">vos rel</emphasis> <emphasis role="bold">-i</emphasis> &lt;<emphasis>volume name or ID</emphasis>&gt; [<emphasis role="bold">-f</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  18         [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-v</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  19
  20   </refsect1>
  21   <refsect1>
  22     <title>Description</title>
  23     <para>The <emphasis role="bold">vos release</emphasis> command copies the contents of the indicated read/write
  24     source volume to each read-only site defined in the source volume's Volume
  25     Location Database (VLDB) entry. (Use the <emphasis role="bold">vos addsite</emphasis> command to define
  26     sites as necessary before issuing this command). Each read-only copy has
  27     the same name as read/write source with the addition of a <computeroutput>.readonly</computeroutput>
  28     extension.</para>
  29
  30     <para>For users to have a consistent view of the file system, the release of the
  31     new volume version must be atomic: either all read-only sites receive the
  32     new version, or all sites keep the version they currently have. The <emphasis role="bold">vos
  33     release</emphasis> command is designed to ensure that all copies of the volume's
  34     read-only version match both the read/write source and each other. In
  35     cases where problems such as machine or server process outages prevent
  36     successful completion of the release operation, AFS uses two mechanisms to
  37     alert the administrator.</para>
  38
  39     <para>First, the command interpreter generates an error message on the standard
  40     error stream naming each read-only site that did not receive the new
  41     volume version. Second, during the release operation the Volume Location
  42     (VL) Server marks site definitions in the VLDB entry with flags (<computeroutput>New
  43     release</computeroutput> and <computeroutput>Old release</computeroutput>) that indicate whether or not the site has the
  44     new volume version. If any flags remain after the operation completes, it
  45     was not successful. The Cache Manager refuses to access a read-only site
  46     marked with the <computeroutput>Old release</computeroutput> flag, which potentially imposes a greater
  47     load on the sites marked with the <computeroutput>New release</computeroutput> flag. It is important to
  48     investigate and eliminate the cause of the failure and then to issue the
  49     <emphasis role="bold">vos release</emphasis> command as many times as necessary to complete the release
  50     without errors.</para>
  51
  52     <para>The pattern of site flags remaining in the volume's VLDB entry after a
  53     failed release operation can help determine the point at which the
  54     operation failed. Use the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis> command to
  55     display the VLDB entry. The VL Server sets the flags in concert with the
  56     Volume Server's operations, as follows:</para>
  57
  58     <itemizedlist>
  59       <listitem>
  60         <para>Before the operation begins, the VL Server sets the <computeroutput>New release</computeroutput> flag on
  61         the read/write site definition in the VLDB entry and the <computeroutput>Old release</computeroutput>
  62         flag on read-only site definitions (unless the read-only site has been
  63         defined since the last release operation and has no actual volume, in
  64         which case its site flag remains <computeroutput>Not released</computeroutput>).</para>
  65
  66       </listitem>
  67       <listitem>
  68         <para>If necessary, the Volume Server creates a temporary copy (a <emphasis>clone</emphasis>) of
  69         the read/write source called the ReleaseClone (see the following
  70         discussion of when the Volume Server does or does not create a new
  71         ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which
  72         the VL Server records in the <computeroutput>RClone</computeroutput> field of the source volume's VLDB
  73         entry.</para>
  74
  75       </listitem>
  76       <listitem>
  77         <para>The Volume Server distributes a copy of the ReleaseClone to each read-only
  78         site defined in the VLDB entry. As the site successfully receives the new
  79         clone, the VL Server sets the site's flag in the VLDB entry to <computeroutput>New
  80         release</computeroutput>.</para>
  81
  82       </listitem>
  83       <listitem>
  84         <para>When all the read-only copies are successfully released, the VL Server
  85         clears all the <computeroutput>New release</computeroutput> site flags. The ReleaseClone is no longer
  86         needed, so the Volume Server deletes it and the VL Server erases its ID
  87         from the VLDB entry.</para>
  88
  89       </listitem>
  90     </itemizedlist>
  91     <para>By default, the Volume Server determines automatically whether or not it
  92     needs to create a new ReleaseClone:</para>
  93
  94     <itemizedlist>
  95       <listitem>
  96         <para>If there are no flags (<computeroutput>New release</computeroutput>, <computeroutput>Old release</computeroutput>, or <computeroutput>Not released</computeroutput>)
  97         on site definitions in the VLDB entry, the previous <emphasis role="bold">vos release</emphasis> command
  98         completed successfully and all read-only sites currently have the same
  99         volume. The Volume Server infers that the current <emphasis role="bold">vos release</emphasis> command
 100         was issued because the read/write volume has changed. The Volume Server
 101         creates a new ReleaseClone and distributes it to all of the read-only
 102         sites.</para>
 103
 104       </listitem>
 105       <listitem>
 106         <para>If any site definition in the VLDB entry is marked with a flag, either the
 107         previous release operation did not complete successfully or a new
 108         read-only site was defined since the last release. The Volume Server does
 109         not create a new ReleaseClone, instead distributing the existing
 110         ReleaseClone to sites marked with the <computeroutput>Old release</computeroutput> or <computeroutput>Not released</computeroutput>
 111         flag. As previously noted, the VL Server marks each VLDB site definition
 112         with the <computeroutput>New release</computeroutput> flag as the site receives the ReleaseClone, and
 113         clears all flags after all sites successfully receive it.</para>
 114
 115       </listitem>
 116     </itemizedlist>
 117     <para>To override the default behavior, forcing the Volume Server to create and
 118     release a new ReleaseClone to the read-only sites, include the <emphasis role="bold">-f</emphasis>
 119     flag. This is appropriate if, for example, the data at the read/write site
 120     has changed since the existing ReleaseClone was created during the
 121     previous release operation.</para>
 122
 123   </refsect1>
 124   <refsect1>
 125     <title>Options</title>
 126     <variablelist>
 127       <varlistentry>
 128         <term><emphasis role="bold">-id</emphasis> &lt;<emphasis>volume name or id</emphasis>&gt;</term>
 129         <listitem>
 130           <para>Specifies either the complete name or volume ID number of a read/write
 131           volume.</para>
 132
 133         </listitem>
 134       </varlistentry>
 135       <varlistentry>
 136         <term><emphasis role="bold">-f</emphasis></term>
 137         <listitem>
 138           <para>Creates a new ReleaseClone and distributes it all read-only sites
 139           regardless of whether or not any site definitions in the VLDB entry are
 140           marked with a flag.</para>
 141
 142         </listitem>
 143       </varlistentry>
 144       <varlistentry>
 145         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 146         <listitem>
 147           <para>Names the cell in which to run the command. Do not combine this argument
 148           with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>
 149
 150         </listitem>
 151       </varlistentry>
 152       <varlistentry>
 153         <term><emphasis role="bold">-noauth</emphasis></term>
 154         <listitem>
 155           <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. Do not
 156           combine this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see
 157           <link linkend="vos1">vos(1)</link>.</para>
 158
 159         </listitem>
 160       </varlistentry>
 161       <varlistentry>
 162         <term><emphasis role="bold">-localauth</emphasis></term>
 163         <listitem>
 164           <para>Constructs a server ticket using a key from the local
 165           <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">vos</emphasis> command interpreter presents it
 166           to the Volume Server and Volume Location Server during mutual
 167           authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument or
 168           <emphasis role="bold">-noauth</emphasis> flag. For more details, see <link linkend="vos1">vos(1)</link>.</para>
 169
 170         </listitem>
 171       </varlistentry>
 172       <varlistentry>
 173         <term><emphasis role="bold">-verbose</emphasis></term>
 174         <listitem>
 175           <para>Produces on the standard output stream a detailed trace of the command's
 176           execution. If this argument is omitted, only warnings and error messages
 177           appear.</para>
 178
 179         </listitem>
 180       </varlistentry>
 181       <varlistentry>
 182         <term><emphasis role="bold">-help</emphasis></term>
 183         <listitem>
 184           <para>Prints the online help for this command. All other valid options are
 185           ignored.</para>
 186
 187         </listitem>
 188       </varlistentry>
 189     </variablelist>
 190   </refsect1>
 191   <refsect1>
 192     <title>Examples</title>
 193     <para>The following command clones the read/write volume usr and releases it to
 194     the read-only sites defined in its VLDB entry.</para>
 195
 196 <programlisting>
 197    % vos release usr
 198
 199 </programlisting>
 200     </refsect1>
 201     <refsect1>
 202       <title>Privilege Required</title>
 203       <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
 204       machine specified with the <emphasis role="bold">-server</emphasis> argument and on each database server
 205       machine. If the <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be
 206       logged on to a server machine as the local superuser <computeroutput>root</computeroutput>.</para>
 207
 208     </refsect1>
 209     <refsect1>
 210       <title>See Also</title>
 211       <para><link linkend="vos1">vos(1)</link>,
 212       <link linkend="vos_addsite1">vos_addsite(1)</link>,
 213       <link linkend="vos_examine1">vos_examine(1)</link>,
 214       <link linkend="vos_listvldb1">vos_listvldb(1)</link></para>
 215
 216     </refsect1>
 217     <refsect1>
 218       <title>Copyright</title>
 219       <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 220
 221       <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 222       converted from HTML to POD by software written by Chas Williams and Russ
 223       Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 224
 225     </refsect1>
 226   </refentry>