src/man/fs_setserverprefs.1

   1 fs setserverprefs          AFS Commands       fs setserverprefs
   2
   3
   4 NAME
   5
   6    fs  setserverprefs -- set  Cache  Manager's preferences for
   7
   8                        file server machines.
   9
  10
  11                                                        +
  12    fs setserverprefs  [-servers <machine name and rank> ]
  13    [-file <dir/file path>]  [-stdin]  [-help]
  14
  15 ACCEPTABLE ABBREVIATIONS/ALIASES
  16
  17                                         +
  18    fs sets  [-se <machine name and rank> ]  [-f <dir/file
  19    path>]
  20    [-st]  [-h]
  21                                       +
  22    fs sp  [-se <machine name and rank> ]  [-f <dir/file path>]
  23         [-st]  [-h]
  24
  25 DESCRIPTION
  26
  27    Sets the Cache Manager's preference for  one  or  more  file
  28    server  machines.  Each Cache Manager stores a table of file
  29    server machines and their respective "ranks."  A file server
  30    machine's  rank  is an integer in the range from 1 to 65,534
  31    that determines the Cache Manager's preference for selecting
  32    the  server  machine  when  the  Cache Manager must access a
  33    ReadOnly replica that resides on it.  Ranks bias  the  Cache
  34    Manager  to  prefer  to  access  replicas  on  "near" server
  35    machines rather than those on "distant" server machines.
  36
  37    When the Cache Manager needs to access a  ReadOnly  replica,
  38    it  first  contacts  the  Volume  Location  (VL)  Server  to
  39    ascertain the names of the file server machines on which the
  40    replica  resides.    It  then  checks  its internal table to
  41    determine the rank associated with each of the  file  server
  42    machines.    After  comparing  the ranks of the machines, it
  43    attempts to access the replica on the  server  machine  that
  44    has the lowest integer rank.
  45
  46    If  the  Cache  Manager  cannot  access  the  replica on the
  47    machine with the lowest rank (possibly because of  a  server
  48    process,  machine, or network outage), it attempts to access
  49    the replica on the machine with the next lowest  rank.    It
  50    continues  in  this way until it either accesses the replica
  51    or determines that all of the file server machines on  which
  52    the replica is housed are unavailable.
  53
  54    Each time it is initialized with the afsd command, the Cache
  55    Manager assigns preferences to any database server  machines
  56    listed  in  the local /usr/vice/etc/CellServDB file that are
  57    also file server machines.  It  stores  the  preferences  as
  58    machine  IP  addresses and associated ranks in the kernel of
  59    the  client  machine.    (See  the  DETERMINING  PREFERENCES
  60    section  for  more  information  about how the Cache Manager
  61    determines actual file server machine ranks.)  Because  they
  62    are  stored  in the kernel, the preferences are recalculated
  63    when the client machine is rebooted.
  64
  65    The Cache Manager assigns ranks to file server  machines  in
  66
  67
  68
  69    the local cell and from foreign cells as necessary.  When it
  70    needs to access a ReadOnly volume, it first  determines  the
  71    machines  on  which  the  replica  resides.  It then assigns
  72    ranks to any of the machines that do not already  have  them
  73    and  stores the ranks in the kernel, after which it uses the
  74    ranks as the basis of  its  selection  of  the  file  server
  75    machine from which to access the replica.
  76
  77    The  fs  setserverprefs  command  can  be  used to define or
  78    change the rank associated with  a  local  or  foreign  file
  79    server  machine.    If the Cache Manager has no rank for the
  80    machine, the command defines the machine's initial rank.  If
  81    the  Cache  Manager  already has a rank for the machine, the
  82    command changes the rank to match the one specified  by  the
  83    issuer; the old rank is overwritten.
  84
  85    Preferences  are  specified  as  pairs of values.  The first
  86    value is the file server machine, the second  the  machine's
  87    rank.    File server machines can be specified by name or by
  88    IP address.  Depending on the naming  service  available  at
  89    the time the command is issued, abbreviated forms of machine
  90    names may be allowed.    See  the  introductory  About  This
  91    Manual chapter for more information.
  92
  93    Pairs  of  file  server  machines  and  their  ranks  can be
  94    specified
  95
  96       - on the command line with the -servers switch
  97
  98       - from a file with the -file switch
  99
 100       - from stdin with the -stdin flag
 101
 102    The -file switch and -stdin flag are especially  useful  for
 103    configuring  multiple Cache Managers in a cell with the same
 104    preferences.  The -file switch can be  used  to  indicate  a
 105    file created manually or generated automatically with the fs
 106    getserverprefs command.  Similarly, the -stdin flag  can  be
 107    used  to  accept  preferences  piped  directly  from another
 108    process (possibly from another Cache  Manager  with  the  fs
 109    getserverprefs  command).    The -servers, -file, and -stdin
 110    switches and flag are not mutually  exclusive,  so  multiple
 111    sources of preferences are permitted.
 112
 113    It is possible for the Cache Manager or a user to assign the
 114    same rank to multiple file server machines housing a replica
 115    of  the  same  volume.  In this case, the Cache Manager uses
 116    methods  described  in  the  following  section,   ASSIGNING
 117    PREFERENCES, to break the tie.  It then increments the ranks
 118    of the file server machines from which it  does  not  access
 119    the replica.
 120
 121 ASSIGNING PREFERENCES
 122
 123    When  initially  assigning  preferences,  the  Cache Manager
 124    bases the ranks on  IP  addresses,  rather  than  on  actual
 125    physical  considerations  such  as location or distance.  It
 126    calculates  file  server  machine  ranks  according  to  the
 127    following heuristic:
 128
 129       - If  the  client  machine  is  also  a  file server
 130
 131
 132
 133         machine, the machine receives a rank of 5000.
 134
 135       - If the client machine is in  a  subnet,  all  file
 136         server  machines  in the same subnet as the client
 137         machine receive an initial rank of 20000.
 138
 139       - All file server machines in the  same  network  as
 140         the  client  machine  receive  an  initial rank of
 141         30000.
 142
 143       - All file server machines on the  distant  ends  of
 144         point-to-point   links  from  the  client  machine
 145         receive an initial rank of 30000.
 146
 147       - All file server machines on networks not  directly
 148         connected  to the client machine receive a rank of
 149         40000.
 150
 151       - All file server  machines  for  which  no  network
 152         locality  information  can be determined receive a
 153         default rank of 40000.
 154
 155    The  Cache  Manager  also   considers   additional   metrics
 156    associated  with  networks,  subnets, and interfaces when it
 157    determines ranks.
 158
 159    If the same ReadOnly replica  is  stored  on  multiple  file
 160    server  machines  that have the same rank, the Cache Manager
 161    employs the metrics  mentioned  previously  to  resolve  the
 162    duplicate  rank collisions.  If necessary, the Cache Manager
 163    randomizes its ranking of the tied machines.    It  resolves
 164    the  ties internally by incrementing by one the ranks of the
 165    machines from which it chooses not to access the replica.
 166
 167 NOTE
 168
 169    The Cache Manager consults preferences only  when  accessing
 170    ReadOnly  replicas  of  volumes.    It does not consider the
 171    preferences when contacting the  VL  Server  on  a  database
 172    server  machine  to determine the location of a volume.  Its
 173    access of database server machines is still random.
 174
 175 ARGUMENTS
 176
 177    -servers        specifies one or more pairs of  file  server
 178                    machines   and   their   respective   ranks.
 179                    Identify file server machines by name or  by
 180                    IP address.  See the DESCRIPTION section for
 181                    more information on specifying  file  server
 182                    machines and their ranks.
 183
 184    -file           specifies   the  pathname  of  a  file  that
 185                    contains pairs of file server  machines  and
 186                    their   respective  ranks.    Identify  file
 187                    server machines by name or  by  IP  address.
 188                    See   the   DESCRIPTION   section  for  more
 189                    information  on   specifying   file   server
 190                    machines and their ranks.
 191
 192    -stdin          indicates that pairs of file server machines
 193                    and their respective ranks are  to  be  read
 194
 195
 196
 197                    from  stdin.   Identify file server machines
 198                    by  name  or  by  IP  address.     See   the
 199                    DESCRIPTION  section for more information on
 200                    specifying file server  machines  and  their
 201                    ranks.
 202
 203    -help           prints   the  online  help  entry  for  this
 204                    command.  Do not provide any other arguments
 205                    or  flags with this one.  See section 3.1 in
 206                    the Reference Manual for more details.
 207
 208 EXAMPLES
 209
 210    The following sets preference ranks for  three  file  server
 211    machines.    In  this  example,  the server machines have no
 212    replicas  in  common,  so  no   potential   collisions   are
 213    associated with their all having the same rank.
 214
 215    % fs sets -se fs1.transarc.com 10000 fs2.transarc.com 10000
 216    \     128.2.11.12 10000
 217
 218    The  following  defines  a  rank for one file server machine
 219    from the command line and reads ranks  for  additional  file
 220    server  machines  from a file named prefs.txt in the current
 221    directory:
 222
 223    % fs sets -se fs4.transarc.com 10010 -f prefs.txt
 224
 225 PRIVILEGE REQUIRED
 226
 227    Issuer must be logged in as "root" in the UNIX  file  system
 228    of the machine on which the command is issued.
 229
 230 MORE INFORMATION
 231
 232    fs getserverprefs