doc/man-pages/pod1/fs_getserverprefs.pod

   1 =head1 NAME
   2
   3 fs_getserverprefs - Displays preference ranks for file servers or VL servers
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fs getserverprefs> S<<< [B<-file> <I<output to named file>>] >>>
  11     [B<-numeric>] [B<-vlservers>] [B<-help>]
  12
  13 B<fs gets> S<<< [B<-f> <I<output to named file>>] >>> [B<-n>] [B<-v>] [B<-h>]
  14
  15 B<fs gp> S<<< [B<-f> <I<output to named file>>] >>> [B<-n>] [B<-v>] [B<-h>]
  16
  17 =for html
  18 </div>
  19
  20 =head1 DESCRIPTION
  21
  22 The B<fs getserverprefs> command displays preference ranks for file server
  23 machine interfaces (file server machines run the B<fs> process) or, if the
  24 B<-vlserver> flag is provided, for Volume Location (VL) Server machines
  25 (which run the B<vlserver> process). For file server machines, the Cache
  26 Manager tracks up to 15 interfaces per machine and assigns a separate rank
  27 to each interface. The ranks indicate the order in which the local Cache
  28 Manager attempts to contact the interfaces of machines that are housing a
  29 volume when it needs to fetch data from the volume. For VL Server
  30 machines, the ranks indicate the order in which the Cache Manager attempts
  31 to contact a cell's VL Servers when requesting VLDB information. For both
  32 types of rank, lower integer values are more preferred.
  33
  34 The Cache Manager stores ranks in kernel memory. Once set, a rank persists
  35 until the machine reboots, or until the B<fs setserverprefs> command is
  36 used to change it. L<fs_setserverprefs(1)> explains how the Cache Manager
  37 sets default ranks, and how to use that command to change the default
  38 values.
  39
  40 Default VL Server ranks range from 10,000 to 10,126. The Cache Manager
  41 assigns ranks to every machine listed in its copy of the
  42 F</usr/vice/etc/CellServDB> file or found via DNS AFSDB or SRV records for
  43 the cell when it initializes. When the Cache Manager needs to fetch VLDB
  44 information from a cell, it compares the ranks for the VL Server machines
  45 belonging to that cell, and attempts to contact the VL Server with the
  46 lowest integer rank. If the Cache Manager cannot reach the VL Server
  47 (because of server process, machine or network outage), it tries to
  48 contact the VL Server with the next lowest integer rank, and so on. If all
  49 of a cell's VL Server machines are unavailable, the Cache Manager cannot
  50 fetch data from the cell.
  51
  52 Default file server ranks range from 5,000 to 40,000, excluding the range
  53 used for VL Servers (10,000 to 10,126); the maximum possible rank is
  54 65,534. When the Cache Manager needs to fetch data from a volume, it
  55 compares the ranks for the interfaces of machines that house the volume,
  56 and attempts to contact the interface that has the lowest integer rank. If
  57 it cannot reach the B<fileserver> process via that interface (because of
  58 server process, machine or network outage), it tries to contact the
  59 interface with the next lowest integer rank, and so on. If it cannot reach
  60 any of the interfaces for machines that house the volume, it cannot fetch
  61 data from the volume.
  62
  63 For both file server machines and VL Server machines, it is possible for a
  64 machine or interface in a foreign cell to have the same rank as a machine
  65 or interface in the local cell. This does not present a problem, because
  66 the Cache Manager only ever compares ranks for machines belonging to one
  67 cell at a time.
  68
  69 =head1 OPTIONS
  70
  71 =over 4
  72
  73 =item B<-file> <I<output file>>
  74
  75 Specifies the full pathname of a file to which to write the preference
  76 ranks. If the specified file already exists, the command overwrites its
  77 contents. If the pathname is invalid, the command fails. If this argument
  78 is not provided, the preference ranks appear on the standard output
  79 stream.
  80
  81 =item B<-numeric>
  82
  83 Displays the IP addresses of file server machine interfaces or VL Server
  84 machines, rather than their hostnames. If this argument is not provided,
  85 the B<fs> command interpreter has the IP addresses translated to hostnames
  86 such as C<fs1.example.com>.
  87
  88 =item B<-vlservers>
  89
  90 Displays preference ranks for VL Server machines rather than file server
  91 machine interfaces.
  92
  93 =item B<-help>
  94
  95 Prints the online help for this command. All other valid options are
  96 ignored.
  97
  98 =back
  99
 100 =head1 OUTPUT
 101
 102 The output consists of a separate line for each file server machine
 103 interface or VL Server machine, pairing the machine's hostname or IP
 104 address with its rank. The Cache Manager stores IP addresses in its kernel
 105 list of ranks, but the command by default identifies interfaces by
 106 hostname, by calling a translation routine that refers to either the
 107 cell's name service (such as the Domain Name Server) or the local host
 108 table. If an IP address appears in the output, it is because the
 109 translation attempt failed. To bypass the translation step and display IP
 110 addresses rather than hostnames, include the B<-numeric> flag. This can
 111 significantly speed the production of output.
 112
 113 By default, the command writes to the standard output stream. Use the
 114 B<-file> argument to write the output to a file instead.
 115
 116 =head1 EXAMPLES
 117
 118 The following example displays the local Cache Manager's preference ranks
 119 for file server machines. The local machine belongs to the AFS cell named
 120 B<example.com>, and in this example the ranks of file server machines in its
 121 local cell are lower than the ranks of file server machines from the
 122 foreign cell, C<example.net>. It is not possible to translate the IP addresses
 123 of two machines on the 138.255 network.
 124
 125    % fs getserverprefs
 126    fs2.example.com       20007
 127    fs3.example.com       30002
 128    fs1.example.com       20011
 129    fs4.example.com       30010
 130    server1.example.net   40002
 131    138.255.33.34         40000
 132    server6.example.net   40012
 133    138.255.33.37         40005
 134
 135 The following example shows hows the output displays IP addresses when the
 136 B<-numeric> flag is included, and illustrates how network proximity
 137 determines default ranks (as described on the B<fs setserverprefs>
 138 reference page). The local machine has IP address 192.12.107.210, and the
 139 two file server machines on its subnetwork have ranks of 20,007 and
 140 20,011. The two file server machines on a different subnetwork of the
 141 local machine's network have higher ranks, 30,002 and 30,010, whereas the
 142 ranks of the remaining machines range from 40,000 to 40,012 because they
 143 are in a completely different network.
 144
 145    % fs getserverprefs -numeric
 146    192.12.107.214          20007
 147    192.12.105.99           30002
 148    192.12.107.212          20011
 149    192.12.105.100          30010
 150    138.255.33.41           40002
 151    138.255.33.34           40000
 152    138.255.33.36           40012
 153    138.255.33.37           40005
 154
 155 The example shows how the B<-vlservers> flag displays preference ranks for
 156 VL Server machines:
 157
 158    % fs getserverprefs -vlservers
 159    fs2.example.com        10052
 160    fs3.example.com        10113
 161    fs1.example.com        10005
 162
 163 =head1 PRIVILEGE REQUIRED
 164
 165 None
 166
 167 =head1 SEE ALSO
 168
 169 L<fs_setserverprefs(1)>
 170
 171 =head1 COPYRIGHT
 172
 173 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 174
 175 This documentation is covered by the IBM Public License Version 1.0.  It was
 176 converted from HTML to POD by software written by Chas Williams and Russ
 177 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.