                           AFS Commands

   1. The vos Commands

   ------------------------------------------------------------

   This   command   defines   the   vos  commands  that  system
   administrators use to contact the Volume Server  and  Volume
   Location  (VL)  Server.    It assumes the reader is familiar
   with the concepts described in  AFS  System  Administrator's
   Guide.

   System  administrators  use  vos  commands  to  instruct the
   Volume Server to create, move, delete, replicate and  backup
   volumes.    The  Volume  Location  (VL) Server automatically
   records in the Volume Location Database (VLDB)  any  changes
   in volume status and location that result from vos commands.
   Operators can use other vos commands to  obtain  information
   from  VLDB  records.   Vos commands also help operators dump
   copies of volumes to disk  and  restore  them  to  the  file
   system if necessary.

   Note that vos commands are "idempotent."  This means that if
   execution of a certain command is interrupted in the  middle
   by  a server or process failure, then a subsequent execution
   of the same command picks  up  at  the  interruption  point,
   rather  than  at the very beginning of the operation.  (This
   does not apply  if  the  issuer  explicitly  interrupts  the
   operation  with  ^C  or  another  interrupt signal.  In that
   case, the volume is left locked and the issuer  must  unlock
   it  with  vos unlock before proceeding.) Idempotency implies
   that before executing a command, the Volume and  VL  Servers
   check  to  see  if  running  it  will have any effect (i.e.,
   whether the state that will result from running the  command
   already  holds).    If  the desired end-state already holds,
   there is no need to run the command  again,  no  matter  how
   many times it is subsequently issued.  If the end-state does
   not yet hold, the command should pick up where necessary  to
   achieve it.

   Refer to the Command Summary at the end of this document for
   a complete list of vos commands and their syntax.

   1.1 The Information in VLDB Entries
   The Volume  Location  Database  (VLDB),  maintained  by  the
   Volume  Location  (VL)  Server,  records  a  large  range of
   information about all the volumes in a  cell.    A  separate
   copy of the VLDB resides on each database server machine. To
   keep the copies synchronized, the VL Server uses  the  AFS's
   library of database management facilities, called Ubik.

   It  is important that the information in the VLDB correspond
   to the status of the actual volumes on the servers  as  much
   of  the  time as possible.  For this reason, any vos command
   that affects volume status also  changes  the  corresponding
   VLDB   entry   automatically,   as   noted  in  the  command
   descriptions below.   (It  is  possible  for  the  VLDB  and
   servers to disagree if vos operations are interrupted before
   completion; see the vos syncserv and vos syncvldb commands.)

   There  is  an  entry  in the VLDB for each ReadWrite volume.
   The entry also records information about  the  ReadOnly  and
   Backup version of the volume; ReadOnly and Backup volumes do
   AFS Command Reference Manual             The vos Commands  2


   not have their own VLDB entries.  (The one exception to this
   rule  is  that a ReadOnly volume may have its own VLDB entry
   if its ReadWrite source has been removed.)

   The following information is available from a VLDB entry:

      - the name of the ReadWrite version of  the  volume.
        The  ReadOnly  version  automatically has the same
        name  with  a  .readonly  extension,  the   Backup
        version with a .backup extension

      - the  ReadWrite volumeID number.  A volumeID number
        is simply an identification number  guaranteed  to
        be unique within a cell.  In almost all cases, the
        VL    Server    allocates     volumeID     numbers
        automatically,  but some commands allow the issuer
        to assign volumeIDs explicitly.  Each of the three
        versions  of  a  volume  has  a different volumeID
        number; they often run  consecutively,  especially
        if  the VL Server assigned them, but this is not a
        requirement.

      - the ReadOnly volumeID number.  All copies  of  the
        ReadOnly version share the same ID.

      - the Backup volumeID number

      - the    ReleaseClone    volumeID   number,   if   a
        ReleaseClone  exists.    See  the  description  of
        vos release for more about the ReleaseClone.

      - one  or  more  site  definitions,  each  of  which
        specifies a file server machine name and partition
        name.    Site  definitions specify the location of
        the  ReadWrite  version  and  each  copy  of   the
        ReadOnly  version (if any).  No site definition is
        necessary for the Backup version, if any,  because
        it   always  resides  at  the  same  site  as  its
        ReadWrite source.   There  can  be  one  ReadWrite
        definition and up to six ReadOnly definitions.

      - one or more site flags associated with each site

        One site flag tells what type of volume resides at
        the site, and has value RW for ReadWrite or RO for
        ReadOnly.

        The  other  possible  site  flag marks the copy at
        that site as NEW or OLD.  Normally, this  type  of
        flag  will not appear; its presence indicates that
        an error occurred  as  new  ReadOnly  clones  were
        being   distributed  to  their  sites.    See  the
        description of the vos release command for further
        explanation.

      - one  status  flag for each of the three versions--
        ReadWrite,  ReadOnly   and   Backup.   This   flag
        indicates  whether  the version actually exists at
        at least one site: valid indicates that  it  does,
        invalid  that it does not.  Note that there is not
        a separate status flag for each site.
   AFS Command Reference Manual             The vos Commands  3


      - a site count, which tells how many copies exist of
        the ReadWrite and ReadOnly versions of the volume.
        There is only one ReadWrite copy, but as  many  as
        six ReadOnly copies may exist.

      - an  indication if the VLDB entry is locked.  Since
        being unlocked is the default state, there  is  no
        explicit  indicator if the VLDB entry is unlocked.
        See  the  descriptions   of   the   vos lock   and
        vos unlock commands.

   The  vos listvldb  command  displays much of the information
   from the VLDB described above.  The vos examine command also
   displays VLDB information, in combination with volume header
   information.

   1.2 The Information in Volume Headers
   The previous section explained that there is a  single  VLDB
   entry for each ReadWrite volume and all of its (ReadOnly and
   Backup) clones.  In contrast, there  is  a  separate  volume
   header at the site of each copy of the volume, no matter its
   version. The volume header is the volume in a senseMit is  a
   data  structure that records which physical memory addresses
   on the partition are storing the files in the volume.    The
   volume  header  binds  all  the  files  into  a logical unit
   without requiring that they be stored in  contiguous  memory
   blocks.

   In  addition  to  data  location,  the volume header records
   other information about the volume,  some  of  it  redundant
   with  the  VLDB  so  that  the  Volume Server can access the
   information even when the VLDB is unavailable.

   The information in the volume header includes:

      - the  name  of  this  copy  of  the  volume,   with
        .readonly or .backup extension if appropriate

      - its volumeID number

      - its  type  (RW  for ReadWrite, RO for ReadOnly, BK
        for Backup)

      - its size in kilobytes (so 1024 means a megabyte)

      - its status at the site, which is unrelated to  the
        locked/unlocked  status  of the VLDB entry.  There
        are three possibilities:

           * On-line  means  that  the  volume  is   fully
             accessible through the file system

           * needs salvage   means   that  the  volume  is
             probably corrupted.  Run the  Salvager  using
             the bos salvage command.

           * Off-line   means   that  the  volume  is  not
             accessible, but there is no reason to suspect
             that it is corrupted

      - a  Parent ID number, which is the volumeID of this
   AFS Command Reference Manual             The vos Commands  4


        volume's ReadWrite source.  If this volume is  the
        ReadWrite version itself, this ID should match the
        previously mentioned volumeID.

      - a Clone ID number, which is the volumeID number of
        the  last  clone made from this volume's ReadWrite
        source for the purposes of replication.    It  may
        match  the  ReadOnly  volumeID or ReleaseClone ID,
        dependingon  whether  or  not  the   release   was
        successful.

      - a  Backup  ID number, which is the volumeID of the
        Backup version of this volume.  If this volume  is
        the  Backup  version  itself, this ID should match
        the previously mentioned volumeID.

      - a quota, which is the maximum amount of disk space
        the  ReadWrite  version  of the volume may occupy.
        It does not apply sensibly to ReadOnly  or  Backup
        volumes, but is reported for convenience anyway.

      - its  creation date, which is the day and time when
        this copy of the volume was created (for  ReadOnly
        and  Backup  copies,  this means cloned/released).
        If   the   volume   has   been    restored    with
        backup diskrestore,   backup volrestore   or  vos
        restore, this is the restore time.

      - its date of last update, which is the day and time
        when  the  contents  of  this volume last changed.
        For ReadOnly and Backup volumes, this should match
        the  creation  date, since they are not allowed to
        change.
   AFS Command Reference Manual             The vos Commands  5


      - the number of times the volume has  been  accessed
        since the later of

           * 12:00 a.m. on the day the command is issued

           * the last time the volume changed location

        An access is defined as a fetch or store operation
        on any file system object stored in the volume.

   The vos listvol command displays information from the volume
   header (as does the vos examine command, in combination with
   VLDB information).

   1.3 Common Arguments and Flags
   Most vos commands accept the  following  optional  arguments
   and  flags.    They  are  listed in the command descriptions
   where they apply, and are described in detail below:

   [-cell <cell name>]

   This argument specifies that the command should be run in  a
   different  cell,  specified  by  cell  name.    By  default,
   commands are executed in  the  local  cell,  as  defined  in
   /usr/vice/etc/ThisCell  on  the  client machine on which the
   command is issued.  The issuer may abbreviate cell  name  to
   the shortest form that distinguishes it from the other cells
   listed in /usr/vice/etc/CellServDB on the client machine  on
   which the command is issued.

   [-noauth]

   This flag instructs the Volume and/or Volume Location Server
   not to authenticate  the  user  of  the  command,  and  thus
   establishes  an  unauthenticated connection between the user
   and the server (the user is recognized as  the  unprivileged
   user  anonymous).    It  is  useful  only when authorization
   checking is disabled on the file server machine (during  the
   installation  of  a  file server machine or when bos setauth
   has been used  during  other  unusual  circumstances).    In
   normal  circumstances,  the Volume and VL Servers allow only
   authorized (privileged) users to issue commands that  change
   the  status  of  a  volume or VLDB entry, and will refuse to
   perform such an action even if the -noauth flag is used.

   [-localauth]

   This flag instructs the vos command interpreter  running  on
   the  local  machine  to  construct a server ticket using the
   server encryption key with the highest key version number in
   /usr/afs/etc/KeyFile  on  the  local  machine.   The command
   interpreter presents the ticket to the Volume and/or  Volume
   Location Server to use in mutual authentication.

   This  argument  is  only  useful for commands issued on file
   server machines, since client workstations  do  not  have  a
   KeyFile.    It  is  intended for cron-type processes or jobs
   included in the machine's /usr/afs/local/BosConfig file.  An
   example  might  be  a  command  that  automatically runs the
   vos backup command on certain  volumes  in  preparation  for
   archival  backups.    See  the  chapter  in  the  AFS System
   AFS Command Reference Manual             The vos Commands  6


   Administrator's Guide about backing up the system.  The flag
   can  also  be used if the user is unable to authenticate but
   is logged into the local UNIX file system as "root".

   [-verbose]

   This flag tells  the  Volume  Server  and/or  VL  Server  to
   display  messages  about  the operations they are performing
   while executing the command.  Useful  mainly  for  debugging
   and tracing purposes.

   [-help]

   This  flag has the same function as the vos help command: it
   prints the command's online help message on the screen.   No
   other  arguments  or  flags  should  be provided at the same
   time.  Even if they are, this flag overrides them,  and  the
   only  effect of issuing the command is that the help message
   appears.

   1.4 The Privilege Required for vos Commands
   The Volume and Volume Location Servers  consider  privileged
   those  users  listed  in the file /usr/afs/etc/UserList on a
   file server machines' local disk.  This list  is  maintained
   on each file server machine's local disk using bos commands.

   Most  vos  commands  require privilege; only those that list
   volume-related information do not.
