fs setserverprefs          AFS Commands       fs setserverprefs


NAME

   fs  setserverprefs -- set  Cache  Manager's preferences for

                       file server machines.


                                                       +
   fs setserverprefs  [-servers <machine name and rank> ]
   [-file <dir/file path>]  [-stdin]  [-help]

ACCEPTABLE ABBREVIATIONS/ALIASES

                                        +
   fs sets  [-se <machine name and rank> ]  [-f <dir/file
   path>]
   [-st]  [-h]
                                      +
   fs sp  [-se <machine name and rank> ]  [-f <dir/file path>]
        [-st]  [-h]

DESCRIPTION

   Sets the Cache Manager's preference for  one  or  more  file
   server  machines.  Each Cache Manager stores a table of file
   server machines and their respective "ranks."  A file server
   machine's  rank  is an integer in the range from 1 to 65,534
   that determines the Cache Manager's preference for selecting
   the  server  machine  when  the  Cache Manager must access a
   ReadOnly replica that resides on it.  Ranks bias  the  Cache
   Manager  to  prefer  to  access  replicas  on  "near" server
   machines rather than those on "distant" server machines.

   When the Cache Manager needs to access a  ReadOnly  replica,
   it  first  contacts  the  Volume  Location  (VL)  Server  to
   ascertain the names of the file server machines on which the
   replica  resides.    It  then  checks  its internal table to
   determine the rank associated with each of the  file  server
   machines.    After  comparing  the ranks of the machines, it
   attempts to access the replica on the  server  machine  that
   has the lowest integer rank.

   If  the  Cache  Manager  cannot  access  the  replica on the
   machine with the lowest rank (possibly because of  a  server
   process,  machine, or network outage), it attempts to access
   the replica on the machine with the next lowest  rank.    It
   continues  in  this way until it either accesses the replica
   or determines that all of the file server machines on  which
   the replica is housed are unavailable.

   Each time it is initialized with the afsd command, the Cache
   Manager assigns preferences to any database server  machines
   listed  in  the local /usr/vice/etc/CellServDB file that are
   also file server machines.  It  stores  the  preferences  as
   machine  IP  addresses and associated ranks in the kernel of
   the  client  machine.    (See  the  DETERMINING  PREFERENCES
   section  for  more  information  about how the Cache Manager
   determines actual file server machine ranks.)  Because  they
   are  stored  in the kernel, the preferences are recalculated
   when the client machine is rebooted.

   The Cache Manager assigns ranks to file server  machines  in



   the local cell and from foreign cells as necessary.  When it
   needs to access a ReadOnly volume, it first  determines  the
   machines  on  which  the  replica  resides.  It then assigns
   ranks to any of the machines that do not already  have  them
   and  stores the ranks in the kernel, after which it uses the
   ranks as the basis of  its  selection  of  the  file  server
   machine from which to access the replica.

   The  fs  setserverprefs  command  can  be  used to define or
   change the rank associated with  a  local  or  foreign  file
   server  machine.    If the Cache Manager has no rank for the
   machine, the command defines the machine's initial rank.  If
   the  Cache  Manager  already has a rank for the machine, the
   command changes the rank to match the one specified  by  the
   issuer; the old rank is overwritten.

   Preferences  are  specified  as  pairs of values.  The first
   value is the file server machine, the second  the  machine's
   rank.    File server machines can be specified by name or by
   IP address.  Depending on the naming  service  available  at
   the time the command is issued, abbreviated forms of machine
   names may be allowed.    See  the  introductory  About  This
   Manual chapter for more information.

   Pairs  of  file  server  machines  and  their  ranks  can be
   specified

      - on the command line with the -servers switch

      - from a file with the -file switch

      - from stdin with the -stdin flag

   The -file switch and -stdin flag are especially  useful  for
   configuring  multiple Cache Managers in a cell with the same
   preferences.  The -file switch can be  used  to  indicate  a
   file created manually or generated automatically with the fs
   getserverprefs command.  Similarly, the -stdin flag  can  be
   used  to  accept  preferences  piped  directly  from another
   process (possibly from another Cache  Manager  with  the  fs
   getserverprefs  command).    The -servers, -file, and -stdin
   switches and flag are not mutually  exclusive,  so  multiple
   sources of preferences are permitted.

   It is possible for the Cache Manager or a user to assign the
   same rank to multiple file server machines housing a replica
   of  the  same  volume.  In this case, the Cache Manager uses
   methods  described  in  the  following  section,   ASSIGNING
   PREFERENCES, to break the tie.  It then increments the ranks
   of the file server machines from which it  does  not  access
   the replica.

ASSIGNING PREFERENCES

   When  initially  assigning  preferences,  the  Cache Manager
   bases the ranks on  IP  addresses,  rather  than  on  actual
   physical  considerations  such  as location or distance.  It
   calculates  file  server  machine  ranks  according  to  the
   following heuristic:

      - If  the  client  machine  is  also  a  file server



        machine, the machine receives a rank of 5000.

      - If the client machine is in  a  subnet,  all  file
        server  machines  in the same subnet as the client
        machine receive an initial rank of 20000.

      - All file server machines in the  same  network  as
        the  client  machine  receive  an  initial rank of
        30000.

      - All file server machines on the  distant  ends  of
        point-to-point   links  from  the  client  machine
        receive an initial rank of 30000.

      - All file server machines on networks not  directly
        connected  to the client machine receive a rank of
        40000.

      - All file server  machines  for  which  no  network
        locality  information  can be determined receive a
        default rank of 40000.

   The  Cache  Manager  also   considers   additional   metrics
   associated  with  networks,  subnets, and interfaces when it
   determines ranks.

   If the same ReadOnly replica  is  stored  on  multiple  file
   server  machines  that have the same rank, the Cache Manager
   employs the metrics  mentioned  previously  to  resolve  the
   duplicate  rank collisions.  If necessary, the Cache Manager
   randomizes its ranking of the tied machines.    It  resolves
   the  ties internally by incrementing by one the ranks of the
   machines from which it chooses not to access the replica.

NOTE

   The Cache Manager consults preferences only  when  accessing
   ReadOnly  replicas  of  volumes.    It does not consider the
   preferences when contacting the  VL  Server  on  a  database
   server  machine  to determine the location of a volume.  Its
   access of database server machines is still random.

ARGUMENTS

   -servers        specifies one or more pairs of  file  server
                   machines   and   their   respective   ranks.
                   Identify file server machines by name or  by
                   IP address.  See the DESCRIPTION section for
                   more information on specifying  file  server
                   machines and their ranks.

   -file           specifies   the  pathname  of  a  file  that
                   contains pairs of file server  machines  and
                   their   respective  ranks.    Identify  file
                   server machines by name or  by  IP  address.
                   See   the   DESCRIPTION   section  for  more
                   information  on   specifying   file   server
                   machines and their ranks.

   -stdin          indicates that pairs of file server machines
                   and their respective ranks are  to  be  read



                   from  stdin.   Identify file server machines
                   by  name  or  by  IP  address.     See   the
                   DESCRIPTION  section for more information on
                   specifying file server  machines  and  their
                   ranks.

   -help           prints   the  online  help  entry  for  this
                   command.  Do not provide any other arguments
                   or  flags with this one.  See section 3.1 in
                   the Reference Manual for more details.

EXAMPLES

   The following sets preference ranks for  three  file  server
   machines.    In  this  example,  the server machines have no
   replicas  in  common,  so  no   potential   collisions   are
   associated with their all having the same rank.

   % fs sets -se fs1.transarc.com 10000 fs2.transarc.com 10000
   \     128.2.11.12 10000

   The  following  defines  a  rank for one file server machine
   from the command line and reads ranks  for  additional  file
   server  machines  from a file named prefs.txt in the current
   directory:

   % fs sets -se fs4.transarc.com 10010 -f prefs.txt

PRIVILEGE REQUIRED

   Issuer must be logged in as "root" in the UNIX  file  system
   of the machine on which the command is issued.

MORE INFORMATION

   fs getserverprefs
