doc/man-pages/pod1/fs_setserverprefs.pod

   1 =head1 NAME
   2
   3 fs setserverprefs - Sets the preference ranks for file servers or VL servers
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fs setserverprefs> S<<< [B<-servers> <I<fileserver names and ranks>>+] >>>
  11     S<<< [B<-vlservers> <I<VL server names and ranks>>+] >>>
  12     S<<< [B<-file> <I<input from named file>>] >>> [B<-stdin>] [B<-help>]
  13
  14 B<fs sets> S<<< [B<-se> <I<fileserver names and ranks>>+] >>>
  15     S<<< [B<-vl> <I<VL server names and ranks>>+] >>>
  16     S<<< [B<-f> <I<input from named file>>] >>> [B<-st>] [B<-h>]
  17
  18 B<fs sp> S<<< [B<-se> <I<fileserver names and ranks>>+] >>>
  19     S<<< [B<-vl> <I<VL server names and ranks>>+] >>>
  20     S<<< [B<-f> <I<input from named file>>] >>> [B<-st>] [B<-h>]
  21
  22 =for html
  23 </div>
  24
  25 =head1 DESCRIPTION
  26
  27 The B<fs setserverprefs> command sets the local Cache Manager's preference
  28 ranks for one or more file server machine interfaces or, if the
  29 B<-vlserver> argument is provided, for Volume Location (VL) Server
  30 machines. For file server machines, the numerical ranks determine the
  31 order in which the Cache Manager attempts to contact the interfaces of
  32 machines that are housing a volume. For VL Server machines, the ranks
  33 determine the order in which the Cache Manager attempts to contact a
  34 cell's VL Servers when requesting VLDB information.
  35
  36 The B<fs getserverprefs> reference page explains how the Cache Manager
  37 uses preference ranks when contacting file server machines or VL Server
  38 machines. The following paragraphs explain how the Cache Manager
  39 calculates default ranks, and how to use this command to change the
  40 defaults.
  41
  42 =head2 Calculation of Default Preference Ranks
  43
  44 The Cache Manager stores a preference rank in kernel memory as a paired IP
  45 address and numerical rank. If a file server machine is multihomed, the
  46 Cache Manager assigns a distinct rank to each of the machine's addresses
  47 (up to the number of addresses that the VLDB can store per machine, which
  48 is specified in the I<IBM AFS Release Notes>). Once calculated, a rank
  49 persists until the machine reboots, or until this command is used to
  50 change it.
  51
  52 The Cache Manager sets default VL Server preference ranks as it
  53 initializes, randomly assigning a rank from the range 10,000 to 10,126 to
  54 each of the machines listed in the local F</usr/vice/etc/CellServDB>
  55 file. Machines from different cells can have the same rank, but this does
  56 not present a problem because the Cache Manager consults only one cell's
  57 ranks at a time.
  58
  59 The Cache Manager sets default preference ranks for file server machine as
  60 it fetches volume location information from the VLDB. Each time it learns
  61 about file server machine interfaces for which it has not already set
  62 ranks, it assigns a rank to each interface. If the local client machine
  63 has only one IP address, the Cache Manager compares it to the server
  64 interface's IP address and sets a rank according to the following
  65 algorithm. If the client machine is multihomed, the Cache Manager applies
  66 the algorithm to each of the client machine's addresses and assigns to the
  67 file server machine interface the lowest rank that results.
  68
  69 =over 4
  70
  71 =item *
  72
  73 If the local machine is a file server machine, the base rank for each of
  74 its interfaces is 5,000.
  75
  76 =item *
  77
  78 If the file server machine interface is on the same subnetwork as the
  79 client interface, its base rank is 20,000.
  80
  81 =item *
  82
  83 If the file server machine interface is on the same network as the client
  84 interface, or is at the distant end of a point-to-point link with the
  85 client interface, its base rank is 30,000.
  86
  87 =item *
  88
  89 If the file server machine interface is on a different network than the
  90 client interface, or the Cache Manager cannot obtain network information
  91 about it, its base rank is 40,000.
  92
  93 =back
  94
  95 After assigning a base rank to a file server machine interface, the Cache
  96 Manager adds to it a number randomly chosen from the range 0 (zero) to
  97 14. As an example, a file server machine interface in the same subnetwork
  98 as the local machine receives a base rank of 20,000, but the Cache Manager
  99 records the actual rank as an integer between 20,000 and 20,014. This
 100 process reduces the number of interfaces that have exactly the same
 101 rank. As with VL Server machine ranks, it is possible for file server
 102 machine interfaces from foreign cells to have the same rank as interfaces
 103 in the local cell, but this does not present a problem. Only the relative
 104 ranks of the interfaces that house a given volume are relevant, and AFS
 105 only supports storage of a volume in one cell at a time.
 106
 107 =head2 Setting Non-default Preference Ranks
 108
 109 Use the B<fs setserverprefs> command to reset an existing preference rank,
 110 or to set the initial rank of a file server machine interface or VL Server
 111 machine for which the Cache Manager has no rank. To make a rank persist
 112 across a reboot of the local machine, place the appropriate B<fs
 113 setserverprefs> command in the machine's AFS initialization file.
 114
 115 Specify each preference rank as a pair of values separated by one or more
 116 spaces:
 117
 118 =over 4
 119
 120 =item *
 121
 122 The first member of the pair is the fully-qualified hostname (for example,
 123 C<fs1.abc.com>), or the IP address in dotted decimal format, of a file
 124 server machine interface or VL Server machine
 125
 126 =item *
 127
 128 The second member of the pair is an integer. The possible ranks range from
 129 C<1> through C<65535>.
 130
 131 =back
 132
 133 As with default ranks, the Cache Manager adds a randomly chosen integer to
 134 a rank specified by this command. For file server machine interfaces, the
 135 integer is from the range 0 (zero) to 14; for VL Server machines, it is
 136 from the range 0 (zero) to 126. For example, if the administrator assigns
 137 a rank of 15,000 to a file server machine interface, the Cache Manager
 138 stores an integer between 15,000 to 15,014.
 139
 140 There are several ways to provide ranks for file server machine interfaces
 141 (but not for VL Server machines):
 142
 143 =over 4
 144
 145 =item *
 146
 147 On the command line, following the B<-servers> argument.
 148
 149 =item *
 150
 151 In a file named by the B<-file> argument. Place each pair on its own line
 152 in the file. Directing the output from the B<fs getserverprefs> command to
 153 a file automatically generates a file with the proper format.
 154
 155 =item *
 156
 157 Via the standard input stream, by providing the B<-stdin> flag. This
 158 method enables the issuer to feed in values directly from a program or
 159 script that generates preference ranks by using an algorithm appropriate
 160 to the local cell. The AFS distribution does not include such programs or
 161 scripts.
 162
 163 =back
 164
 165 When setting file server machine preference ranks, it is legal to combine
 166 the B<-servers>, B<-file>, and B<-stdin> options on a single command
 167 line. If different options specify a different rank for the same
 168 interface, the Cache Manager stores and uses the rank assigned with the
 169 B<-servers> argument.
 170
 171 The B<-vlservers> argument is the only way to assign VL Server machine
 172 ranks. It can be combined with one or more of the B<-servers>, B<-file>,
 173 and B<-stdin> options, but the Cache Manager applies the values provided
 174 for those options to file server machine ranks only.
 175
 176 The fs command interpreter does not verify hostnames or IP addresses, and
 177 so assigns preference ranks to invalid machine names or addresses. The
 178 Cache Manager never uses such ranks unless the same incorrect information
 179 is in the VLDB.
 180
 181 =head1 OPTIONS
 182
 183 =over 4
 184
 185 =item B<-servers> <I<file server names and ranks>>+
 186
 187 Specifies one or more file server machine preference ranks. Each rank
 188 pairs the fully-qualified hostname or IP address (in dotted decimal
 189 format) of a file server machine's interface with an integer rank,
 190 separated by one or more spaces; also separate each pair with one or more
 191 spaces. Acceptable values for the rank range from C<1> through C<65521>; a
 192 lower value indicates a greater preference.  Providing ranks outside this
 193 range can have unpredictable results.  Providing a value no larger than
 194 C<65521> guarantees that the rank does not exceed the maximum possible
 195 value of 65,535 even if the largest random factor (14) is added.
 196
 197 This argument can be combined with the B<-file> argument, B<-stdin> flag,
 198 or both. If more than one of the arguments sets a rank for the same
 199 interface, the rank set by this argument takes precedence. It can also be
 200 combined with the B<-vlservers> argument, but does not interact with it.
 201
 202 =item B<-vlservers> <I<VL server names and ranks>>+
 203
 204 Specifies one or more VL Server preference ranks. Each rank pairs the
 205 fully-qualified hostname or IP address (in dotted decimal format) of a VL
 206 Server machine with an integer rank, separated by one or more spaces; also
 207 separate each pair with one or more spaces. Acceptable values for the rank
 208 range from C<1> through C<65521>; a lower value indicates a greater
 209 preference. Providing ranks outside this range can have unpredictable
 210 results. Providing a value no larger than C<65521> guarantees that the
 211 rank does not exceed the maximum possible value of 65,535 even if the
 212 largest random factor (14) is added.
 213
 214 This argument can be combined with the B<-servers> argument, B<-file>
 215 argument, B<-stdin> flag, or any combination of the three, but does not
 216 interact with any of them. They apply only to file server machine ranks.
 217
 218 =item B<-file> <I<input file>>
 219
 220 Specifies the full pathname of a file from which to read pairs of file
 221 server machine interfaces and their ranks, using the same notation and
 222 range of values as for the B<-servers> argument. In the file, place each
 223 pair on its own line and separate the two parts of each pair with one or
 224 more spaces.
 225
 226 This argument can be combined with the B<-servers> argument, B<-stdin>
 227 flag, or both. If more than one of the arguments sets a rank for the same
 228 interface, the rank set by the B<-server> argument takes precedence. It
 229 can also be combined with the B<-vlservers> argument, but does not
 230 interact with it.
 231
 232 =item B<-stdin>
 233
 234 Reads pairs of file server machine interface and integer rank from the
 235 standard input stream. The intended use is to accept input piped in from a
 236 user-defined program or script that generates ranks in the appropriate
 237 format, but it also accepts input typed to the shell. Format the interface
 238 and rank pairs as for the B<-file> argument. If typing at the shell, type
 239 Ctrl-D after the final newline to complete the input.
 240
 241 This argument can be combined with the B<-servers> argument, the B<-file>
 242 argument, or both. If more than one of the arguments sets a rank for the
 243 same interface, the rank set by the B<-server> argument takes
 244 precedence. It can also be combined with the B<-vlservers> argument, but
 245 does not interact with it.
 246
 247 =item B<-help>
 248
 249 Prints the online help for this command. All other valid options are
 250 ignored.
 251
 252 =back
 253
 254 =head1 EXAMPLES
 255
 256 The following command sets the Cache Manager's preference ranks for the
 257 file server machines named C<fs3.abc.com> and C<fs4.abc.com>, the latter
 258 of which is specified by its IP address, 192.12.105.100. The machines
 259 reside in another subnetwork of the local machine's network, so their
 260 default base rank is 30,000. To increase the Cache Manager's preference
 261 for these machines, the issuer assigns a rank of C<25000>, to which the
 262 Cache Manager adds an integer in the range from 0 to 15.
 263
 264    # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
 265
 266 The following command uses the B<-servers> argument to set the Cache
 267 Manager's preference ranks for the same two file server machines, but it
 268 also uses the B<-file> argument to read a collection of preference ranks
 269 from a file that resides in the local file F</etc/fs.prefs>:
 270
 271    # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \
 272        -file /etc/fs.prefs
 273
 274 The /etc/fs.prefs file has the following contents and format:
 275
 276    192.12.108.214        7500
 277    192.12.108.212        7500
 278    138.255.33.41         39000
 279    138.255.33.34         39000
 280    128.0.45.36           41000
 281    128.0.45.37           41000
 282
 283 The following command uses the B<-stdin> flag to read preference ranks
 284 from the standard input stream. The ranks are piped to the command from a
 285 program, B<calc_prefs>, which was written by the issuer to calculate
 286 preferences based on values significant to the local cell.
 287
 288    # calc_prefs | fs setserverprefs -stdin
 289
 290 The following command uses the B<-vlservers> argument to set the Cache
 291 Manager's preferences for the VL server machines named C<fs1.abc.com>,
 292 C<fs3.abc.com>, and C<fs4.abc.com> to base ranks of 1, 11000, and 65521,
 293 respectively:
 294
 295    # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
 296        fs4.abc.com 65521
 297
 298 =head1 PRIVILEGE REQUIRED
 299
 300 The issuer must be logged in as the local superuser root.
 301
 302 =head1 SEE ALSO
 303
 304 L<fs_getserverprefs(1)>
 305
 306 =head1 COPYRIGHT
 307
 308 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 309
 310 This documentation is covered by the IBM Public License Version 1.0.  It was
 311 converted from HTML to POD by software written by Chas Williams and Russ
 312 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.