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