3 fs_setserverprefs - Sets the preference ranks for file servers or VL servers
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>]
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>]
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>]
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.
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
42 =head2 Calculation of Default Preference Ranks
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.
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.
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.
75 If the local machine is a file server machine, the base rank for each of
76 its interfaces is 5,000.
80 If the file server machine interface is on the same subnetwork as the
81 client interface, its base rank is 20,000.
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.
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.
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.
109 =head2 Setting Non-default Preference Ranks
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.
117 Specify each preference rank as a pair of values separated by one or more
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
130 The second member of the pair is an integer. The possible ranks range from
131 C<1> through C<65535>.
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.
142 There are several ways to provide ranks for file server machine interfaces
143 (but not for VL Server machines):
149 On the command line, following the B<-servers> argument.
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.
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
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.
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.
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
187 =item B<-servers> <I<file server names and ranks>>+
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.
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.
204 =item B<-vlservers> <I<VL server names and ranks>>+
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.
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.
220 =item B<-file> <I<input file>>
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
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
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.
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.
251 Prints the online help for this command. All other valid options are
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.
266 # fs setserverprefs -servers fs3.example.com 25000 192.12.105.100 25000
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>:
273 # fs setserverprefs -servers fs3.example.com 25000 192.12.105.100 25000 \
276 The /etc/fs.prefs file has the following contents and format:
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.
290 # calc_prefs | fs setserverprefs -stdin
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
297 # fs setserverprefs -vlservers fs1.example.com 1 fs3.example.com 11000 \
298 fs4.example.com 65521
300 =head1 PRIVILEGE REQUIRED
302 The issuer must be logged in as the local superuser root.
306 L<fs_getserverprefs(1)>
310 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
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.