doc/man-pages/pod1/vos_release.pod.in

   1 =head1 NAME
   2
   3 vos_release - Updates read-only volumes to match the read/write source volume
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos release> S<<< B<-id> <I<volume name or ID>> >>>
  11     [B<-force>] [B<-force-reclone>]
  12     S<<< [B<-cell> <I<cell name>>] >>>
  13     [B<-noauth>] [B<-localauth>]
  14     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
  15     S<<< [B<-config> <I<config directory>>] >>>
  16     [B<-help>]
  17
  18 B<vos rel> S<<< B<-i> <I<volume name or ID>> >>>
  19     [B<-force>] [B<-force-r>]
  20     S<<< [B<-c> <I<cell name>>] >>>
  21     [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
  22     S<<< [B<-co> <I<config directory>>] >>>
  23     [B<-h>]
  24
  25 =for html
  26 </div>
  27
  28 =head1 DESCRIPTION
  29
  30 The B<vos release> command copies the contents of the indicated read/write
  31 source volume to each read-only site defined in the source volume's Volume
  32 Location Database (VLDB) entry. (Use the B<vos addsite> command to define
  33 sites as necessary before issuing this command). Each read-only copy has
  34 the same name as read/write source with the addition of a C<.readonly>
  35 extension.
  36
  37 For users to have a consistent view of the file system, the release of the
  38 new volume version must be atomic: either all read-only sites receive the
  39 new version, or all sites keep the version they currently have. The B<vos
  40 release> command is designed to ensure that all copies of the volume's
  41 read-only version match both the read/write source and each other. In
  42 cases where problems such as machine or server process outages prevent
  43 successful completion of the release operation, AFS uses two mechanisms to
  44 alert the administrator.
  45
  46 First, the command interpreter generates an error message on the standard
  47 error stream naming each read-only site that did not receive the new
  48 volume version. Second, during the release operation the Volume Location
  49 (VL) Server marks site definitions in the VLDB entry with flags (C<New
  50 release> and C<Old release>) that indicate whether or not the site has the
  51 new volume version. If any flags remain after the operation completes, it
  52 was not successful. The Cache Manager refuses to access a read-only site
  53 marked with the C<Old release> flag, which potentially imposes a greater
  54 load on the sites marked with the C<New release> flag. It is important to
  55 investigate and eliminate the cause of the failure and then to issue the
  56 B<vos release> command as many times as necessary to complete the release
  57 without errors.
  58
  59 The pattern of site flags remaining in the volume's VLDB entry after a
  60 failed release operation can help determine the point at which the
  61 operation failed. Use the B<vos examine> or B<vos listvldb> command to
  62 display the VLDB entry. The VL Server sets the flags in concert with the
  63 Volume Server's operations, as follows:
  64
  65 =over 4
  66
  67 =item *
  68
  69 Before the operation begins, the VL Server sets the C<New release> flag on
  70 the read/write site definition in the VLDB entry and the C<Old release>
  71 flag on read-only site definitions (unless the read-only site has been
  72 defined since the last release operation and has no actual volume, in
  73 which case its site flag remains C<Not released>).
  74
  75 =item *
  76
  77 If necessary, the Volume Server creates a temporary copy (a I<clone>) of
  78 the read/write source called the ReleaseClone (see the following
  79 discussion of when the Volume Server does or does not create a new
  80 ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which
  81 the VL Server records in the C<RClone> field of the source volume's VLDB
  82 entry.
  83
  84 =item *
  85
  86 The Volume Server distributes a copy of the ReleaseClone to each read-only
  87 site defined in the VLDB entry. As the site successfully receives the new
  88 clone, the VL Server sets the site's flag in the VLDB entry to C<New
  89 release>.
  90
  91 =item *
  92
  93 When all the read-only copies are successfully released, the VL Server
  94 clears all the C<New release> site flags. The ReleaseClone is no longer
  95 needed, so the Volume Server deletes it and the VL Server erases its ID
  96 from the VLDB entry.
  97
  98 =back
  99
 100 By default, the Volume Server determines automatically whether or not it
 101 needs to create a new ReleaseClone:
 102
 103 =over 4
 104
 105 =item *
 106
 107 If there are no flags (C<New release>, C<Old release>, or C<Not released>)
 108 on site definitions in the VLDB entry, the previous B<vos release> command
 109 completed successfully and all read-only sites currently have the same
 110 volume. The Volume Server infers that the current B<vos release> command
 111 was issued because the read/write volume has changed. The Volume Server
 112 creates a new ReleaseClone volume and distributes a copy of the clone
 113 volume to all the read-only sites.  In order to reduce the amount of data
 114 transferred during a release, the Volume Server sends incremental changes to
 115 remote sites during the release.  The Volume Server only sends files and
 116 directories which have been changed in the read/write volume since the
 117 previous release.
 118
 119 =item *
 120
 121 If any site definition in the VLDB entry is marked with a flag, either the
 122 previous release operation did not complete successfully or a new
 123 read-only site was defined since the last release. The Volume Server does
 124 not create a new ReleaseClone, instead distributing the entire existing
 125 ReleaseClone to sites marked with the C<Old release> or C<Not released>
 126 flag. As previously noted, the VL Server marks each VLDB site definition
 127 with the C<New release> flag as the site receives the ReleaseClone, and
 128 clears all flags after all sites successfully receive it.
 129
 130 =back
 131
 132 To override the default behavior, forcing the Volume Server to create and
 133 release a new ReleaseClone to the read-only sites, include the B<-force>
 134 flag. This is appropriate if, for example, the data at the read/write site
 135 has changed since the existing ReleaseClone was created during the
 136 previous release operation.
 137
 138 The B<-force-reclone> will force the creation of a new release clone volume,
 139 but will not force a full volume dump to be distributed to the remote sites.
 140 Instead, incremental changes will be distributed when possible.
 141
 142 =head1 OPTIONS
 143
 144 =over 4
 145
 146 =item B<-id> <I<volume name or id>>
 147
 148 Specifies either the complete name or volume ID number of a read/write
 149 volume.
 150
 151 =item B<-force>
 152
 153 Creates a new ReleaseClone and distributes the entire clone volume to
 154 all read-only sites, regardless of the C<New release>, C<Old release>, or
 155 C<Not released> site flags.
 156
 157 =item B<-force-reclone>
 158
 159 Creates a new ReleaseClone and incrementally distributes the clone volume to
 160 all read-only sites, regardless of the C<New release>, C<Old release>, or
 161 C<Not released> site flags.
 162
 163 =include fragments/vos-common.pod
 164
 165 =back
 166
 167 =head1 EXAMPLES
 168
 169 The following command clones the read/write volume usr and releases it to
 170 the read-only sites defined in its VLDB entry.
 171
 172    % vos release usr
 173
 174 =head1 PRIVILEGE REQUIRED
 175
 176 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 177 machine specified with the B<-server> argument and on each database server
 178 machine. If the B<-localauth> flag is included, the issuer must instead be
 179 logged on to a server machine as the local superuser C<root>.
 180
 181 =head1 SEE ALSO
 182
 183 L<vos(1)>,
 184 L<vos_addsite(1)>,
 185 L<vos_examine(1)>,
 186 L<vos_listvldb(1)>
 187
 188 =head1 COPYRIGHT
 189
 190 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 191
 192 This documentation is covered by the IBM Public License Version 1.0.  It was
 193 converted from HTML to POD by software written by Chas Williams and Russ
 194 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.