vos release                AFS Commands             vos release


NAME

   vos release -- place ReadOnly versions of a ReadOnly volume

                       at  the  sites  indicated  in  the  VLDB
                       entry.


   vos release  -id <volume name or ID>  [-f]  [-cell <cell
   name>]      [-noauth]  [-localauth]  [-verbose]  [-help]

ACCEPTABLE ABBREVIATIONS/ALIASES

   vos rel  -i <volume name or ID>  [-f]  [-c <cell name>]
   [-n]  [-l]  [-v]  [-h]

DESCRIPTION

   Clones  the  indicated ReadWrite volume and places a copy of
   the clone at each ReadOnly site indicated in the VLDB entry.
   Each  copy  is  named  after  the ReadWrite source, with the
   addition of a .readonly extension.  When at least  one  site
   successfully receives its copy of the clone, the VLDB status
   flag for ReadOnly is set to valid.

   The issuer must already  have  defined  the  ReadOnly  sites
   using vos  addsite.

   The vos release command is no more difficult to use than any
   other vos  command,  but  exactly  what  happens  internally
   during   its   execution   is  somewhat  complicated.    The
   complexity is necessary in order to ensure that  all  copies
   of  the  volume's  ReadOnly version match both the ReadWrite
   source and each other.  If all the ReadOnly copies  are  not
   the  same,  then users might see different data depending on
   which copy of the volume they  happen  to  access--obviously
   not  a  satisfactory  situation.    To  make  sure  that all
   ReadOnly copies match each other and the  ReadWrite  source,
   releases  should  be  "all-or-nothing"--either  all ReadOnly
   sites receive the new clone, or all sites keep the  ReadOnly
   version they currently have.

   The  "all-or-nothing"  requirement has two main implications
   that affect the issuer:

      - he or she needs to be  alert  for  error  messages
        that  indicate  an  unsuccessful  release,  and/or
        check  the  VLDB  entry  to  make   sure   certain
        error-signalling flags are not present

      - he  or  she  needs to decide whether to use the -f
        flag

   The   following   two   subsections   discuss   these    two
   implications.

   Flags that indicate a failed release

   If  the vos release command fails before the ReadOnly volume
   is in place at every defined site,  an  error  message  will
   specify which sites did not receive the ReadOnly volume.  To



   give the issuer a backup method for determining if a release
   has  completed  (and  for  its own internal use), the Volume
   Server and VL Server set various flags while  executing  the
   following  vos release steps.  The presence of some of these
   flags after an apparent completion signals failure.    After
   determining  the  cause  of  the  failure, the issuer should
   attempt to eliminate the cause and then  continue  to  issue
   the  vos release commands as many times as necessary to make
   sure the release completes successfully.

   The steps during a release, and the flags set, are

      1. Before cloning begins, the  VL  Server  sets  the
         site flag for the present ReadOnly entries in the
         VLDB to OLD.

      2. The  VL  Server  sets  the  site  flag  for   the
         ReadWrite source to NEW.

      3. The Volume Server clones the ReadWrite source, if
         required.   It  assigns  the  clone  a  temporary
         volumeID  number  and  the  VL  Server  puts that
         number in the releaseClone field in the  source's
         VLDB  entry.  (The discussion below on the use of
         the -f flag  describes  when  the  Volume  Server
         should  make  a  new  clone,  and how it uses the
         releaseClone  ID  in  case  a  release   is   not
         completely successful.)

      4. The  Volume  Server  distributes  a  copy  of the
         ReleaseClone to  each  ReadOnly  site  previously
         defined  in the VLDB (using vos addsite).  The VL
         Server changes the site flag  for  each  ReadOnly
         site  from  OLD  to  NEW  as  soon  as  the  site
         successfully receives the new clone.

      5. When all the  ReadOnly  copies  are  successfully
         released,  the  VL Server clears all the NEW site
         flags, leaving that part of the site  flag  field
         empty.    Because  it  is  no  longer needed, the
         Volume Server deletes the ReleaseClone  from  the
         system and its ID from the VLDB.

   The  presence of NEW and/or OLD site flags in the VLDB after
   the "completion" of a release  indicates  that  it  was  not
   successful.    As  mentioned  above, an unsuccessful release
   unfortunately makes it possible that  Cache  Managers  could
   see  different versions of a volume, depending on which File
   Server they contact.  In practice, this is likely to  happen
   only  if they flush their caches in order to pick up the new
   release, but the operator should avert  the  possibility  by
   taking  whatever  steps  are  necessary  to make the release
   successful.

   Using the -f flag

   If the issuer wants to make  sure  that  the  Volume  Server
   releases  a brand new clone to the ReadOnly sites, he or she
   can include the -f flag.    The  flag  "forces"  the  Volume
   Server  to  make  a new clone of the ReadWrite source volume
   and distribute it to all the possible ReadOnly sites.



   If the issuer does not  include  the  -f  flag,  the  Volume
   Server's  course  of  action  depends  on whether all of the
   ReadOnly sites already have identical copies of the volume:

      - If all the sites currently have the same copy, the
        Volume Server infers that the previous vos release
        command must have completed successfully, and that
        no  new  ReadOnly  sites  have been defined since.
        Assuming that the issuer wants to release a  brand
        new   clone,  the  Volume  Server  makes  one  and
        distributes it to all the defined sites.

      - If all the sites do not have the same  copy,  then
        the   Volume  Server  concludes  that  either  the
        previous vos release command failed in the  middle
        or  else  a system administrator has defined a new
        ReadOnly site since the last release.  (A possible
        reason  for  failure  of  a release is that one or
        more sites were inaccessible at the  time.)    The
        Volume  Server  does  not need to make an entirely
        new clone, however.  Instead, it  distributes  the
        clone  with the releaseClone volumeID to the sites
        that do not have it yet (step 3 in  the  Reference
        Manual  above  defines the ReleaseClone).  If this
        release also fails, the operator  needs  to  issue
        more  vos release  commands  until  the  same copy
        exists at all sites.

WARNING

   There should be a maximum of seven sites defined in the VLDB
   entry  for  the  volume  (one  ReadWrite  site and up to six
   ReadOnly sites).

   No more that 3500 volumes should reside on one partition.  A
   greater  number  can  cause  the  AFS  Salvager  process  to
   malfunction.  It is the  issuer's  responsibility  to  check
   that  issuing  this  command  will not cause the limit to be
   exceeded.  The vos listvol command  reports  the  number  of
   volumes on a partition.

ARGUMENTS

   -id             specifies   either   the  complete  name  or
                   volumeID number of a ReadWrite volume.

   -f              determines whether the Volume Server makes a
                   new  clone  before  distributing  it  to the
                   ReadOnly  sites,  in  interaction  with  the
                   state  of  the  ReadOnly  copies  already at
                   sites.  The section entitled  Using  the  -f
                   flag describes all the issues.

   -cell           specifies  the  cell  in  which  to  run the
                   command.  See section 8.3 in  the  Reference
                   Manual for more details.  -noauth
                   tells the Volume and Volume Location Servers
                   to  assign  the  identity  anonymous  to the
                   issuer.  See section 8.3  in  the  Reference
                   Manual for more details.  -localauth
                   constructs a server ticket using a key  from



                   /usr/afs/etc/KeyFile.    See  section 8.3 in
                   the  Reference  Manual  for  more   details.
                   -verbose
                   tells the Volume and Volume Location Servers
                   to  report  on  what  they are doing as they
                   execute the command.  See section 8.3 in the
                   Reference Manual for more details.  -help
                   prints the online help for this command.  Do
                   not  provide  any  other  arguments or flags
                   with this one.    See  section  8.3  in  the
                   Reference Manual for more details.

EXAMPLE

   The  following  clones the ReadWrite volume usr and releases
   it to the ReadOnly sites defined in its VLDB entry.

   % vos release usr

PRIVILEGE REQUIRED

   Issuer must be listed in /usr/afs/etc/UserList on -server.

MORE INFORMATION

   vos addsite vos listvol

   vos syncserv vos syncvldb
