Commit | Line | Data |
---|---|---|
805e021f CE |
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. |