vldb_convert               AFS Commands            vldb_convert


NAME

   vldb_convert -- convert  Volume  Location Database from AFS

                       3.1 to AFS 3.2.


   vldb_convert  [initcmd]  [-to <goal version>]  [-from
   <current version>]
   [-path <pathname>]  [-showversion]  [-help]

ACCEPTABLE ABBREVIATIONS

   The name of this command must be typed in  full.    However,
   its  switches can be omitted (if appropriate) or abbreviated
   as follows:

   vldb_convert  [-t <goal version>]  [-f <current version>]
   [-p <pathname>]  [-s]  [-h]

DESCRIPTION

   Converts a Volume Location  Database  (VLDB)  from  AFS  3.1
   format  to  AFS 3.2 format.  Due to a limitation in the VLDB
   in prior versions of AFS, a cell could have no more than  31
   file server machines.  With the AFS 3.2 version of the VLDB,
   a cell can have as many as 255 file server machines.

   The vldb_convert command converts an existing AFS  3.1  VLDB
   for   use   as   an   AFS   3.2   VLDB.      It   reads  the
   /usr/afs/db/vldb.DB0 database file  for  the  old  VLDB  and
   writes  a  new,  converted  version  of  the database into a
   temporary file in the /usr/afs/db directory.  If successful,
   it then removes the old vldb.DB0 file from the directory and
   replaces it with the new version from  the  temporary  file.
   After  the  conversion,  the  database  functions  as it did
   before, with the  exception  that  it  can  accommodate  the
   entries for the additional file server machines.  The binary
   file for the vldb_convert command resides in /usr/afsws/etc.

   The command requires the  file  system  in  which  the  VLDB
   resides  to  have free space at least equivalent to the size
   of the old VLDB plus  9  kilobytes.    Because  the  command
   removes the old VLDB and replaces it with the new version of
   the database, the additional space is  required  only  while
   the  command  executes.    (The  new version of the database
   requires  a  small  amount  of  additional  space,  but  the
   difference is inconsequential.)

   Begin the conversion of the VLDB by shutting down the Volume
   Location (VL) Servers on all three database server machines.
   (The  instructions assume the cell has three database server
   machines; adjust the steps accordingly  if  it  has  fewer.)
   This causes a service outage in the cell, but the outage for
   the entire conversion procedure should last no more than  15
   to 20 minutes.

   Replace  the  AFS  3.1  version of the /usr/afs/bin/vlserver
   file on all three database server machines with the AFS  3.2
   version  of  the  file.    The new VL Server understands the
   format of the new version of the VLDB.  The old  version  of



   the  VL  Server  cannot  be  run with the new version of the
   VLDB, and vice versa.  Make sure you  replace  the  vlserver
   binary files on each binary distribution machine; otherwise,
   the Update Servers  overwrite  the  version  stored  on  the
   database  server  machines  by automatically propagating the
   old version of the binary file to the machines.

   Determine which database server machine has  the  lowest  IP
   address;  Ubik  will use this machine as the synchronization
   site when the VL Servers are restarted.    Remove  the  VLDB
   from  the other two database server machines by deleting the
   /usr/afs/db/vldb.DB0  database  and  /usr/afs/db/vldb.DBSYS1
   log  files  from  the  other  machines.    Remove  only  the
   /usr/afs/db/vldb.DBSYS1 log file from  the  database  server
   machine  with  the  lowest  IP  address.   Do not remove the
   /usr/afs/db/vldb.DB0 database file from the machine with the
   lowest IP address.

   Copy  the  /usr/afs/db/vldb.DB0  file on the database server
   machine with the lowest IP address to a different directory.
   Then  execute the vldb_convert command on that machine.  The
   command takes no  more  than  a  few  minutes  to  complete.
   However, it displays no messages while it executes.

   When  the  command is finished, restart the VL Server on the
   machine with the lowest IP address.   Then  restart  the  VL
   Servers on the remaining two database server machines.  Ubik
   elects the  database  server  machine  with  the  lowest  IP
   address as the synchronization site and distributes the copy
   of the new VLDB from that machine to the other two  database
   server machines.  The VLDB is then available.

   The  vldb_convert  command  can  be also used to convert the
   VLDB from AFS 3.2 format  back  to  AFS  3.1  format.    The
   command's  -to  and  -from  switches are used to specify the
   direction of the conversion.  The -to switch  specifies  the
   version  to which the database is to be converted; the -from
   switch indicates the version from which the database  is  to
   be converted.

   Both  switches  accept  a  1,  to  indicate  3.1, or a 2, to
   indicate 3.2.  When converting from 3.1 to 3.2, specify  -to
   as  2  and  -from  as  1.   Should the need to revert to 3.1
   arise, specify -to as 1 and -from as  2.    When  converting
   from  3.1  to  3.2,  you  can omit both options; the command
   automatically converts  the  database  to  the  next  higher
   version.

   Finally,  the  command can be used to display the version of
   the current VLDB.  The -showversion flag directs the command
   to  display  the  version number (3.1 or 3.2) of the VLDB at
   the time the command is issued.  Do not specify the  -to  or
   -from switch if the -showversion flag is used.



NOTE

   The  vldb_convert  command  is  also  useful  as  a means of
   removing from the VLDB  entries  for  server  machines  that
   house no volumes.  When a file server machine name or its IP
   address is changed, the VLDB still contains an entry for the
   previous  name or address.  This becomes a problem only when
   the administrators in a large cell must change the names  or
   IP  addresses  of a significant number of machines, in which
   case it is conceivable (though highly unlikely) that all 255
   possible file server machine entries will be taken.

   If  this  problem  occurs  in a cell, the administrators can
   execute vldb_convert with a value of 2 for both its -to  and
   -from  switches.    The  command removes the entries for all
   unreferenced servers from the VLDB.    The  steps  described
   previously  for  executing  the  command  (shutting down the
   servers, removing the copies of the VLDB) must  be  executed
   as they are for initially upgrading the database.

WARNING

   Copy  the /usr/afs/db/vldb.DB0 file to a different directory
   after  the  VL  Servers  are  shut  down  but   before   the
   vldb_convert command is run.  The command should perform the
   conversion without problems.  Also, it does not  remove  the
   old  database  file  until it has successfully completed the
   conversion.  However, if anything  happens  to  disrupt  the
   conversion or if the operation fails for any reason, copying
   the database beforehand allows the VLDB to be restored  from
   the copy.

   Leave  no  VL  Servers  running  while  the conversion is in
   progress.  If a number of VL Servers sufficient for Ubik  to
   attain  a  quorum  are  available while the conversion is in
   progress, changes made while the conversion is underway  are
   lost when the new version of the VLDB is distributed.

   Ensure  that all VL Servers are referencing the same version
   of the VLDB at all times.  The 3.1 version of the VL  Server
   can  reference only the 3.1 version of the VLDB, and the 3.2
   version of the VL Server can use only the 3.2 version of the
   VLDB.    The  3.1 version of the VL Server is not compatible
   with the 3.2 version of the VLDB, and vice versa.  For  this
   reason, the vldb_convert command must be used to convert the
   existing VLDB to the new format before the  new  version  of
   the   VL   Server   distributed   from   the  cell's  binary
   distribution machines via the Update Server can be used.

   Specify only valid, correct values for  the  -to  and  -from
   switches.   Specifying invalid or incorrect values for these
   switches can result in damage to the VLDB.  This is  another
   reason  to  copy  the  vldb.DB0 database file to a different
   directory before using the vldb_convert command.

   Finally, the entire procedure  takes  no  more  than  a  few
   minutes   to   complete.     However,  because  volumes  are
   inaccessible while the procedure is underway, it is best  to
   perform the operation over a weekend or overnight to disrupt
   the fewest users.



ARGUMENTS

   initcmd         is an optional string that accommodates  the
                   command's use of the AFS command parser.  It
                   can be omitted and ignored.

   -to             indicates the version of the VLDB  to  which
                   the current version of the database is to be
                   converted.  Valid values are  1,  indicating
                   that the existing version of the database is
                   to be converted to AFS  3.1  format,  or  2,
                   indicating  that the existing version of the
                   database is  to  be  converted  to  AFS  3.2
                   format.    See  the  DESCRIPTION section for
                   information about the possible  combinations
                   of  the  -to  and  -from  switches  and  the
                   effects of omitting the switches.

   -from           indicates the version of the  current  VLDB.
                   Valid  values  are  1,  indicating  that the
                   existing version of the database is  in  AFS
                   3.1   format,  or  2,  indicating  that  the
                   existing version of the database is  in  AFS
                   3.2 format.  See the DESCRIPTION section for
                   information about the possible  combinations
                   of  the  -to  and  -from  switches  and  the
                   effects of omitting the switches.

   -path           provides  the  complete  pathname   of   the
                   vldb.DB0  database  file if the file is kept
                   in  an  alternate  directory   (or   has   a
                   different name).  Always include the name of
                   the file,  even  if  it  is  vldb.DB0.    By
                   default,  the  command converts the vldb.DB0
                   database file in the /usr/afs/db  directory.
                   Use  this  switch  only  if  the database is
                   stored in a different directory  (or  has  a
                   different name).

   -showversion    displays  the  version  (3.1  or 3.2) of the
                   current VLDB.  Include the -path  switch  if
                   the VLDB is stored in a directory other than
                   /usr/afs/db.  If you use this flag, the  -to
                   and -from switches are ignored.

   -help           prints the online help for this command.  Do
                   not provide any  other  arguments  or  flags
                   with this one.

EXAMPLE

   The  following,  issued  on the database server machine with
   the lowest IP address, executes the vldb_convert command  to
   convert the VLDB from AFS 3.1 format to AFS 3.2 format:

   % vldb_convert

PRIVILEGE REQUIRED

   The  issuer  must  be able to read, delete, and write to the
   /usr/afs/db/vldb.DB0 and  /usr/afs/db/vldb.DBSYS1  files  on



   all  database server machines.  The issuer must also be able
   to insert, write to, and delete  files  in  the  /usr/afs/db
   directories on the machines.

   In  addition,  to  install the new version of the VL Server,
   the issuer must be able to delete the  /usr/afs/bin/vlserver
   file  on  all  database  server  machines  (or on all binary
   distribution machines).  The issuer must  also  be  able  to
   insert   files   in  the  /usr/afs/bin  directories  on  the
   machines.

   An issuer who is logged into the UNIX file  systems  of  the
   database  server machines as "root" has the necessary rights
   to perform the entire conversion procedure.
