1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry id="fs_setserverprefs1">
4 <refentrytitle>fs setserverprefs</refentrytitle>
5 <manvolnum>1</manvolnum>
8 <refname>fs setserverprefs</refname>
9 <refpurpose>Sets the preference ranks for file servers or VL servers</refpurpose>
12 <title>Synopsis</title>
13 <para><emphasis role="bold">fs setserverprefs</emphasis> [<emphasis role="bold">-servers</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
14 [<emphasis role="bold">-vlservers</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
15 [<emphasis role="bold">-file</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-stdin</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
17 <para><emphasis role="bold">fs sets</emphasis> [<emphasis role="bold">-se</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
18 [<emphasis role="bold">-vl</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
19 [<emphasis role="bold">-f</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-st</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
21 <para><emphasis role="bold">fs sp</emphasis> [<emphasis role="bold">-se</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
22 [<emphasis role="bold">-vl</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
23 [<emphasis role="bold">-f</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-st</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
27 <title>Description</title>
28 <para>The <emphasis role="bold">fs setserverprefs</emphasis> command sets the local Cache Manager's preference
29 ranks for one or more file server machine interfaces or, if the
30 <emphasis role="bold">-vlserver</emphasis> argument is provided, for Volume Location (VL) Server
31 machines. For file server machines, the numerical ranks determine the
32 order in which the Cache Manager attempts to contact the interfaces of
33 machines that are housing a volume. For VL Server machines, the ranks
34 determine the order in which the Cache Manager attempts to contact a
35 cell's VL Servers when requesting VLDB information.</para>
37 <para>The <emphasis role="bold">fs getserverprefs</emphasis> reference page explains how the Cache Manager
38 uses preference ranks when contacting file server machines or VL Server
39 machines. The following paragraphs explain how the Cache Manager
40 calculates default ranks, and how to use this command to change the
44 <title>Calculation of Default Preference Ranks</title>
45 <para>The Cache Manager stores a preference rank in kernel memory as a paired IP
46 address and numerical rank. If a file server machine is multihomed, the
47 Cache Manager assigns a distinct rank to each of the machine's addresses
48 (up to the number of addresses that the VLDB can store per machine, which
49 is specified in the <emphasis>IBM AFS Release Notes</emphasis>). Once calculated, a rank
50 persists until the machine reboots, or until this command is used to
53 <para>The Cache Manager sets default VL Server preference ranks as it
54 initializes, randomly assigning a rank from the range 10,000 to 10,126 to
55 each of the machines listed in the local <replaceable>/usr/vice/etc/CellServDB</replaceable>
56 file. Machines from different cells can have the same rank, but this does
57 not present a problem because the Cache Manager consults only one cell's
58 ranks at a time.</para>
60 <para>The Cache Manager sets default preference ranks for file server machine as
61 it fetches volume location information from the VLDB. Each time it learns
62 about file server machine interfaces for which it has not already set
63 ranks, it assigns a rank to each interface. If the local client machine
64 has only one IP address, the Cache Manager compares it to the server
65 interface's IP address and sets a rank according to the following
66 algorithm. If the client machine is multihomed, the Cache Manager applies
67 the algorithm to each of the client machine's addresses and assigns to the
68 file server machine interface the lowest rank that results.</para>
72 <para>If the local machine is a file server machine, the base rank for each of
73 its interfaces is 5,000.</para>
77 <para>If the file server machine interface is on the same subnetwork as the
78 client interface, its base rank is 20,000.</para>
82 <para>If the file server machine interface is on the same network as the client
83 interface, or is at the distant end of a point-to-point link with the
84 client interface, its base rank is 30,000.</para>
88 <para>If the file server machine interface is on a different network than the
89 client interface, or the Cache Manager cannot obtain network information
90 about it, its base rank is 40,000.</para>
94 <para>After assigning a base rank to a file server machine interface, the Cache
95 Manager adds to it a number randomly chosen from the range 0 (zero) to
96 14. As an example, a file server machine interface in the same subnetwork
97 as the local machine receives a base rank of 20,000, but the Cache Manager
98 records the actual rank as an integer between 20,000 and 20,014. This
99 process reduces the number of interfaces that have exactly the same
100 rank. As with VL Server machine ranks, it is possible for file server
101 machine interfaces from foreign cells to have the same rank as interfaces
102 in the local cell, but this does not present a problem. Only the relative
103 ranks of the interfaces that house a given volume are relevant, and AFS
104 only supports storage of a volume in one cell at a time.</para>
108 <title>Setting Non-default Preference Ranks</title>
109 <para>Use the <emphasis role="bold">fs setserverprefs</emphasis> 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 <emphasis role="bold">fs
113 setserverprefs</emphasis> command in the machine's AFS initialization file.</para>
115 <para>Specify each preference rank as a pair of values separated by one or more
120 <para>The first member of the pair is the fully-qualified hostname (for example,
121 <computeroutput>fs1.abc.com</computeroutput>), or the IP address in dotted decimal format, of a file
122 server machine interface or VL Server machine</para>
126 <para>The second member of the pair is an integer. The possible ranks range from
127 <computeroutput>1</computeroutput> through <computeroutput>65535</computeroutput>.</para>
131 <para>As with default ranks, the Cache Manager adds a randomly chosen integer to
132 a rank specified by this command. For file server machine interfaces, the
133 integer is from the range 0 (zero) to 14; for VL Server machines, it is
134 from the range 0 (zero) to 126. For example, if the administrator assigns
135 a rank of 15,000 to a file server machine interface, the Cache Manager
136 stores an integer between 15,000 to 15,014.</para>
138 <para>There are several ways to provide ranks for file server machine interfaces
139 (but not for VL Server machines):</para>
143 <para>On the command line, following the <emphasis role="bold">-servers</emphasis> argument.</para>
147 <para>In a file named by the <emphasis role="bold">-file</emphasis> argument. Place each pair on its own line
148 in the file. Directing the output from the <emphasis role="bold">fs getserverprefs</emphasis> command to
149 a file automatically generates a file with the proper format.</para>
153 <para>Via the standard input stream, by providing the <emphasis role="bold">-stdin</emphasis> flag. This
154 method enables the issuer to feed in values directly from a program or
155 script that generates preference ranks by using an algorithm appropriate
156 to the local cell. The AFS distribution does not include such programs or
161 <para>When setting file server machine preference ranks, it is legal to combine
162 the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>, and <emphasis role="bold">-stdin</emphasis> options on a single command
163 line. If different options specify a different rank for the same
164 interface, the Cache Manager stores and uses the rank assigned with the
165 <emphasis role="bold">-servers</emphasis> argument.</para>
167 <para>The <emphasis role="bold">-vlservers</emphasis> argument is the only way to assign VL Server machine
168 ranks. It can be combined with one or more of the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>,
169 and <emphasis role="bold">-stdin</emphasis> options, but the Cache Manager applies the values provided
170 for those options to file server machine ranks only.</para>
172 <para>The fs command interpreter does not verify hostnames or IP addresses, and
173 so assigns preference ranks to invalid machine names or addresses. The
174 Cache Manager never uses such ranks unless the same incorrect information
175 is in the VLDB.</para>
180 <title>Options</title>
183 <term><emphasis role="bold">-servers</emphasis> <<emphasis>file server names and ranks</emphasis>>+</term>
185 <para>Specifies one or more file server machine preference ranks. Each rank
186 pairs the fully-qualified hostname or IP address (in dotted decimal
187 format) of a file server machine's interface with an integer rank,
188 separated by one or more spaces; also separate each pair with one or more
189 spaces. Acceptable values for the rank range from <computeroutput>1</computeroutput> through <computeroutput>65521</computeroutput>; a
190 lower value indicates a greater preference. Providing ranks outside this
191 range can have unpredictable results. Providing a value no larger than
192 <computeroutput>65521</computeroutput> guarantees that the rank does not exceed the maximum possible
193 value of 65,535 even if the largest random factor (14) is added.</para>
195 <para>This argument can be combined with the <emphasis role="bold">-file</emphasis> argument, <emphasis role="bold">-stdin</emphasis> flag,
196 or both. If more than one of the arguments sets a rank for the same
197 interface, the rank set by this argument takes precedence. It can also be
198 combined with the <emphasis role="bold">-vlservers</emphasis> argument, but does not interact with it.</para>
203 <term><emphasis role="bold">-vlservers</emphasis> <<emphasis>VL server names and ranks</emphasis>>+</term>
205 <para>Specifies one or more VL Server preference ranks. Each rank pairs the
206 fully-qualified hostname or IP address (in dotted decimal format) of a VL
207 Server machine with an integer rank, separated by one or more spaces; also
208 separate each pair with one or more spaces. Acceptable values for the rank
209 range from <computeroutput>1</computeroutput> through <computeroutput>65521</computeroutput>; a lower value indicates a greater
210 preference. Providing ranks outside this range can have unpredictable
211 results. Providing a value no larger than <computeroutput>65521</computeroutput> guarantees that the
212 rank does not exceed the maximum possible value of 65,535 even if the
213 largest random factor (14) is added.</para>
215 <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, <emphasis role="bold">-file</emphasis>
216 argument, <emphasis role="bold">-stdin</emphasis> flag, or any combination of the three, but does not
217 interact with any of them. They apply only to file server machine ranks.</para>
222 <term><emphasis role="bold">-file</emphasis> <<emphasis>input file</emphasis>></term>
224 <para>Specifies the full pathname of a file from which to read pairs of file
225 server machine interfaces and their ranks, using the same notation and
226 range of values as for the <emphasis role="bold">-servers</emphasis> argument. In the file, place each
227 pair on its own line and separate the two parts of each pair with one or
230 <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, <emphasis role="bold">-stdin</emphasis>
231 flag, or both. If more than one of the arguments sets a rank for the same
232 interface, the rank set by the <emphasis role="bold">-server</emphasis> argument takes precedence. It
233 can also be combined with the <emphasis role="bold">-vlservers</emphasis> argument, but does not
234 interact with it.</para>
239 <term><emphasis role="bold">-stdin</emphasis></term>
241 <para>Reads pairs of file server machine interface and integer rank from the
242 standard input stream. The intended use is to accept input piped in from a
243 user-defined program or script that generates ranks in the appropriate
244 format, but it also accepts input typed to the shell. Format the interface
245 and rank pairs as for the <emphasis role="bold">-file</emphasis> argument. If typing at the shell, type
246 Ctrl-D after the final newline to complete the input.</para>
248 <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, the <emphasis role="bold">-file</emphasis>
249 argument, or both. If more than one of the arguments sets a rank for the
250 same interface, the rank set by the <emphasis role="bold">-server</emphasis> argument takes
251 precedence. It can also be combined with the <emphasis role="bold">-vlservers</emphasis> argument, but
252 does not interact with it.</para>
257 <term><emphasis role="bold">-help</emphasis></term>
259 <para>Prints the online help for this command. All other valid options are
267 <title>Examples</title>
268 <para>The following command sets the Cache Manager's preference ranks for the
269 file server machines named <computeroutput>fs3.abc.com</computeroutput> and <computeroutput>fs4.abc.com</computeroutput>, the latter
270 of which is specified by its IP address, 192.12.105.100. The machines
271 reside in another subnetwork of the local machine's network, so their
272 default base rank is 30,000. To increase the Cache Manager's preference
273 for these machines, the issuer assigns a rank of <computeroutput>25000</computeroutput>, to which the
274 Cache Manager adds an integer in the range from 0 to 15.</para>
277 # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
280 <para>The following command uses the <emphasis role="bold">-servers</emphasis> argument to set the Cache
281 Manager's preference ranks for the same two file server machines, but it
282 also uses the <emphasis role="bold">-file</emphasis> argument to read a collection of preference ranks
283 from a file that resides in the local file <replaceable>/etc/fs.prefs</replaceable>:</para>
286 # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \
290 <para>The /etc/fs.prefs file has the following contents and format:</para>
301 <para>The following command uses the <emphasis role="bold">-stdin</emphasis> flag to read preference ranks
302 from the standard input stream. The ranks are piped to the command from a
303 program, <emphasis role="bold">calc_prefs</emphasis>, which was written by the issuer to calculate
304 preferences based on values significant to the local cell.</para>
307 # calc_prefs | fs setserverprefs -stdin
310 <para>The following command uses the <emphasis role="bold">-vlservers</emphasis> argument to set the Cache
311 Manager's preferences for the VL server machines named <computeroutput>fs1.abc.com</computeroutput>,
312 <computeroutput>fs3.abc.com</computeroutput>, and <computeroutput>fs4.abc.com</computeroutput> to base ranks of 1, 11000, and 65521,
316 # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
322 <title>Privilege Required</title>
323 <para>The issuer must be logged in as the local superuser root.</para>
327 <title>See Also</title>
328 <para><link linkend="fs_getserverprefs1">fs_getserverprefs(1)</link></para>
332 <title>Copyright</title>
333 <para>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</para>
335 <para>This documentation is covered by the IBM Public License Version 1.0. It was
336 converted from HTML to POD by software written by Chas Williams and Russ
337 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>