Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <chapter id="HDRWQ387"> | |
3 | <title>Administering Client Machines and the Cache Manager</title> | |
4 | ||
5 | <para>This chapter describes how to administer an AFS client machine, which is any machine from which users can access the AFS | |
6 | filespace and communicate with AFS server processes. (A client machine can simultaneously function as an AFS server machine if | |
7 | appropriately configured.) An AFS client machine has the following characteristics: <itemizedlist> | |
8 | <listitem> | |
9 | <para>The kernel includes the set of modifications, commonly referred to as the <emphasis>Cache Manager</emphasis>, that | |
10 | enable access to AFS files and directories. You can configure many of the Cache Manager's features to suit your users' | |
11 | needs. See <link linkend="HDRWQ390">Overview of Cache Manager Customization</link>.</para> | |
12 | </listitem> | |
13 | ||
14 | <listitem> | |
15 | <para>The <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk stores several configuration files. See | |
16 | <link linkend="HDRWQ392">Configuration Files in the /usr/vice/etc Directory</link>.</para> | |
17 | </listitem> | |
18 | ||
19 | <listitem> | |
20 | <para>A cache stores temporary copies of data fetched from AFS file server machines, either in machine memory or on a | |
21 | devoted local disk partition. See <link linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link> and <link | |
22 | linkend="HDRWQ402">Setting Other Cache Parameters with the afsd program</link>.</para> | |
23 | </listitem> | |
24 | </itemizedlist></para> | |
25 | ||
26 | <para>To learn how to install the client functionality on a machine, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para> | |
27 | ||
28 | <sect1 id="HDRWQ388"> | |
29 | <title>Summary of Instructions</title> | |
30 | ||
31 | <para>This chapter explains how to perform the following tasks by using the indicated commands:</para> | |
32 | ||
33 | <informaltable frame="none"> | |
34 | <tgroup cols="2"> | |
35 | <colspec colwidth="67*" /> | |
36 | ||
37 | <colspec colwidth="33*" /> | |
38 | ||
39 | <tbody> | |
40 | <row> | |
41 | <entry>Display cache size set at reboot</entry> | |
42 | ||
43 | <entry><emphasis role="bold">cat /usr/vice/etc/cacheinfo</emphasis></entry> | |
44 | </row> | |
45 | ||
46 | <row> | |
47 | <entry>Display current cache size and usage</entry> | |
48 | ||
49 | <entry><emphasis role="bold">fs getcacheparms</emphasis></entry> | |
50 | </row> | |
51 | ||
52 | <row> | |
53 | <entry>Change disk cache size without rebooting</entry> | |
54 | ||
55 | <entry><emphasis role="bold">fs setcachesize</emphasis></entry> | |
56 | </row> | |
57 | ||
58 | <row> | |
59 | <entry>Initialize Cache Manager</entry> | |
60 | ||
61 | <entry><emphasis role="bold">afsd</emphasis></entry> | |
62 | </row> | |
63 | ||
64 | <row> | |
65 | <entry>Display contents of <emphasis role="bold">CellServDB</emphasis> file</entry> | |
66 | ||
67 | <entry><emphasis role="bold">cat /usr/vice/etc/CellServDB</emphasis></entry> | |
68 | </row> | |
69 | ||
70 | <row> | |
71 | <entry>Display list of database server machines from kernel memory</entry> | |
72 | ||
73 | <entry><emphasis role="bold">fs listcells</emphasis></entry> | |
74 | </row> | |
75 | ||
76 | <row> | |
77 | <entry>Change list of database server machines in kernel memory</entry> | |
78 | ||
79 | <entry><emphasis role="bold">fs newcell</emphasis></entry> | |
80 | </row> | |
81 | ||
82 | <row> | |
83 | <entry>Check cell's status regarding setuid</entry> | |
84 | ||
85 | <entry><emphasis role="bold">fs getcellstatus</emphasis></entry> | |
86 | </row> | |
87 | ||
88 | <row> | |
89 | <entry>Set cell's status regarding setuid</entry> | |
90 | ||
91 | <entry><emphasis role="bold">fs setcell</emphasis></entry> | |
92 | </row> | |
93 | ||
94 | <row> | |
95 | <entry>Set server probe interval</entry> | |
96 | ||
97 | <entry><emphasis role="bold">fs checkservers -interval</emphasis></entry> | |
98 | </row> | |
99 | ||
100 | <row> | |
101 | <entry>Display machine's cell membership</entry> | |
102 | ||
103 | <entry><emphasis role="bold">cat /usr/vice/etc/ThisCell</emphasis></entry> | |
104 | </row> | |
105 | ||
106 | <row> | |
107 | <entry>Change machine's cell membership</entry> | |
108 | ||
109 | <entry>Edit <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis></entry> | |
110 | </row> | |
111 | ||
112 | <row> | |
113 | <entry>Flush cached file/directory</entry> | |
114 | ||
115 | <entry><emphasis role="bold">fs flush</emphasis></entry> | |
116 | </row> | |
117 | ||
118 | <row> | |
119 | <entry>Flush everything cached from a volume</entry> | |
120 | ||
121 | <entry><emphasis role="bold">fs flushvolume</emphasis></entry> | |
122 | </row> | |
123 | ||
124 | <row> | |
125 | <entry>Update volume-to-mount-point mappings</entry> | |
126 | ||
127 | <entry><emphasis role="bold">fs checkvolumes</emphasis></entry> | |
128 | </row> | |
129 | ||
130 | <row> | |
131 | <entry>Display Cache Manager's server preference ranks</entry> | |
132 | ||
133 | <entry><emphasis role="bold">fs getserverprefs</emphasis></entry> | |
134 | </row> | |
135 | ||
136 | <row> | |
137 | <entry>Set Cache Manager's server preference ranks</entry> | |
138 | ||
139 | <entry><emphasis role="bold">fs setserverprefs</emphasis></entry> | |
140 | </row> | |
141 | ||
142 | <row> | |
143 | <entry>Display client machine addresses to register</entry> | |
144 | ||
145 | <entry><emphasis role="bold">fs getclientaddrs</emphasis></entry> | |
146 | </row> | |
147 | ||
148 | <row> | |
149 | <entry>Set client machine addresses to register</entry> | |
150 | ||
151 | <entry><emphasis role="bold">fs setclientaddrs</emphasis></entry> | |
152 | </row> | |
153 | ||
154 | <row> | |
155 | <entry>Control the display of warning and status messages</entry> | |
156 | ||
157 | <entry><emphasis role="bold">fs messages</emphasis></entry> | |
158 | </row> | |
159 | ||
160 | <row> | |
161 | <entry>Display and change machine's system type</entry> | |
162 | ||
163 | <entry><emphasis role="bold">fs sysname</emphasis></entry> | |
164 | </row> | |
165 | ||
166 | <row> | |
167 | <entry>Enable asynchronous writes</entry> | |
168 | ||
169 | <entry><emphasis role="bold">fs storebehind</emphasis></entry> | |
170 | </row> | |
171 | </tbody> | |
172 | </tgroup> | |
173 | </informaltable> | |
174 | </sect1> | |
175 | ||
176 | <sect1 id="HDRWQ390"> | |
177 | <title>Overview of Cache Manager Customization</title> | |
178 | ||
179 | <indexterm> | |
180 | <primary>Cache Manager</primary> | |
181 | ||
182 | <secondary>configuring and customizing</secondary> | |
183 | </indexterm> | |
184 | ||
185 | <indexterm> | |
186 | <primary>configuring</primary> | |
187 | ||
188 | <secondary>Cache Manager</secondary> | |
189 | </indexterm> | |
190 | ||
191 | <indexterm> | |
192 | <primary>Cache Manager</primary> | |
193 | ||
194 | <secondary>described</secondary> | |
195 | </indexterm> | |
196 | ||
197 | <para>An AFS client machine's kernel includes a set of modifications, commonly referred to as the <emphasis>Cache | |
198 | Manager</emphasis>, that enable access to AFS files and directories and communications with AFS server processes. It is common | |
199 | to speak of the Cache Manager as a process or program, and in regular usage it appears to function like one. When configuring | |
200 | it, though, it is helpful to keep in mind that this usage is not strictly accurate.</para> | |
201 | ||
202 | <para>The Cache Manager mainly fetches files on behalf of application programs running on the machine. When an application | |
203 | requests an AFS file, the Cache Manager contacts the Volume Location (VL) Server to obtain a list of the file server machines | |
204 | that house the volume containing the file. The Cache Manager then translates the application program's system call requests into | |
205 | remote procedure calls (RPCs) to the File Server running on the appropriate machine. When the File Server delivers the file, the | |
206 | Cache Manager stores it in a local <emphasis>cache</emphasis> before delivering it to the application program.</para> | |
207 | ||
208 | <para>The File Server delivers a data structure called a <emphasis>callback</emphasis> along with the file. (To be precise, it | |
209 | delivers a callback for each file fetched from a read/write volume, and a single callback for all data fetched from a read-only | |
210 | volume.) A valid callback indicates that the Cache Manager's cached copy of a file matches the central copy maintained by the | |
211 | File Server. If an application on another AFS client machine changes the central copy, the File Server breaks the callback, and | |
212 | the Cache Manager must retrieve the new version when an application program on its machine next requests data from the file. As | |
213 | long as the callback is unbroken, however, the Cache Manager can continue to provide the cached version of the file to | |
214 | applications on its machine, which eliminates unnecessary network traffic.</para> | |
215 | ||
216 | <para>The indicated sections of this chapter explain how to configure and customize the following Cache Manager features. All | |
217 | but the first (choosing disk or memory cache) are optional, because AFS sets suitable defaults for them. <itemizedlist> | |
218 | <listitem> | |
219 | <para><emphasis>disk or memory cache</emphasis>. The AFS Cache Manager can use machine memory for caching instead of space | |
220 | on the local disk. Deciding which to use is the most basic configuration decision you must make. See <link | |
221 | linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para> | |
222 | </listitem> | |
223 | ||
224 | <listitem> | |
225 | <para><emphasis>cache size</emphasis>. Cache size probably has the most direct influence on client machine performance. It | |
226 | determines how often the Cache Manager must contact the File Server across the network or discard cached data to make room | |
227 | for newly requested files, both of which affect how quickly the Cache Manager delivers files to users. See <link | |
228 | linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para> | |
229 | </listitem> | |
230 | ||
231 | <listitem> | |
232 | <para><emphasis>cache location</emphasis>. For a disk cache, you can alter the conventional cache directory location | |
233 | (<emphasis role="bold">/usr/vice/cache</emphasis>) to take advantage of greater space availability on other disks on the | |
234 | machine. A larger cache can result in faster file delivery. See <link linkend="HDRWQ394">Determining the Cache Type, Size, | |
235 | and Location</link>.</para> | |
236 | </listitem> | |
237 | ||
238 | <listitem> | |
239 | <para><emphasis>chunk size and number</emphasis>. The <emphasis role="bold">afsd</emphasis> program, which initializes the | |
240 | Cache Manager, allows you to control the size and number of chunks into which a cache is divided, plus related parameters. | |
241 | Setting these parameters is optional, because there are reasonable defaults, but it provides precise control. The AFS | |
242 | distribution includes configuration scripts that set Cache Manager parameters to values that are reasonable for different | |
243 | configurations and usage patterns. See <link linkend="HDRWQ402">Setting Other Cache Parameters with the afsd | |
244 | program</link>.</para> | |
245 | </listitem> | |
246 | ||
247 | <listitem> | |
248 | <para><emphasis>knowledge of database server machines</emphasis>. Enable access to a cell's AFS filespace and other | |
249 | services by listing the cell's database server machines in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> | |
250 | file on the local disk. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para> | |
251 | </listitem> | |
252 | ||
253 | <listitem> | |
254 | <para><emphasis>setuid privilege</emphasis>. You can control whether the Cache Manager allows programs from a cell to | |
255 | execute with setuid permission. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid | |
256 | Programs</link>.</para> | |
257 | </listitem> | |
258 | ||
259 | <listitem> | |
260 | <para><emphasis>cell membership</emphasis>. Each client belongs to a one cell defined by the local <emphasis | |
261 | role="bold">/usr/vice/etc/ThisCell</emphasis> file. Cell membership determines the default cell in which the machine's | |
262 | users are authenticated and in which AFS commands run. See <link linkend="HDRWQ411">Setting a Client Machine's Cell | |
263 | Membership</link>.</para> | |
264 | </listitem> | |
265 | ||
266 | <listitem> | |
267 | <para><emphasis>cached file version</emphasis>. AFS's system of callbacks normally guarantees that the Cache Manager has | |
268 | the most current versions of files and directories possible. Nevertheless, you can force the Cache Manager to fetch the | |
269 | most current version of a file from the File Server if you suspect that the cache contains an outdated version. See <link | |
270 | linkend="HDRWQ412">Forcing the Update of Cached Data</link>.</para> | |
271 | </listitem> | |
272 | ||
273 | <listitem> | |
274 | <para><emphasis>File Server and Volume Location Server preferences</emphasis>. The Cache Manager sets numerical preference | |
275 | ranks for the interfaces on file server machines and Volume Server (VL) machines. The ranks determine which interface the | |
276 | Cache Manager first attempts to use when fetching data from a volume or from the Volume Location Database (VLDB). The | |
277 | Cache Manager sets default ranks as it initializes, basing them on its network proximity to each interface, but you can | |
278 | modify the preference ranks if you wish. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para> | |
279 | </listitem> | |
280 | ||
281 | <listitem> | |
282 | <para><emphasis>interfaces registered with the File Server</emphasis>. If the Cache Manager is multihomed (has multiple | |
283 | interface addresses), you can control which of them it registers for File Servers to use when they initiate RPCs to the | |
284 | client machine. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>.</para> | |
285 | </listitem> | |
286 | ||
287 | <listitem> | |
288 | <para><emphasis>display of information messages</emphasis>. By default, the Cache Manager sends basic error and | |
289 | informational messages to the client machine's console and to command shells. You can disable the messaging. See <link | |
290 | linkend="HDRWQ416">Controlling the Display of Warning and Informational Messages</link>.</para> | |
291 | </listitem> | |
292 | ||
293 | <listitem> | |
294 | <para><emphasis>system type</emphasis>. The Cache Manager records the local machine's AFS system type in kernel memory, | |
295 | and substitutes the value for the @sys variable in pathnames. See <link linkend="HDRWQ417">Displaying and Setting the | |
296 | System Type Name</link>.</para> | |
297 | </listitem> | |
298 | ||
299 | <listitem> | |
300 | <para><emphasis>delayed writes</emphasis>. By default, the Cache Manager writes all data to the File Server immediately | |
301 | and synchronously when an application program closes a file. You can enable asynchronous writes, either for an individual | |
302 | file, or all files that the Cache Manager handles, and set how much data remains to be written when the Cache Manager | |
303 | returns control to the closing application. See <link linkend="HDRWQ418">Enabling Asynchronous Writes</link>.</para> | |
304 | </listitem> | |
305 | </itemizedlist></para> | |
306 | ||
307 | <para>You must make all configuration changes on the client machine itself (at the console or over a direct connection such as a | |
308 | <emphasis role="bold">telnet</emphasis> connection). You cannot configure the Cache Manager remotely. You must be logged in as | |
309 | the local superuser <emphasis role="bold">root</emphasis> to issue some commands, whereas others require no privilege. All files | |
310 | mentioned in this chapter must actually reside on the local disk of each AFS client machine (they cannot, for example, be | |
311 | symbolic links to files in AFS).</para> | |
312 | </sect1> | |
313 | ||
314 | <sect1 id="HDRWQ391"> | |
315 | <title>Configuration and Cache-Related Files on the Local Disk</title> | |
316 | ||
317 | <indexterm> | |
318 | <primary>usr/vice/etc directory</primary> | |
319 | </indexterm> | |
320 | ||
321 | <indexterm> | |
322 | <primary>directory</primary> | |
323 | ||
324 | <secondary>/usr/vice/etc</secondary> | |
325 | </indexterm> | |
326 | ||
327 | <indexterm> | |
328 | <primary>configuration files</primary> | |
329 | ||
330 | <secondary>client machine</secondary> | |
331 | </indexterm> | |
332 | ||
333 | <indexterm> | |
334 | <primary>client machine</primary> | |
335 | ||
336 | <secondary>configuration files</secondary> | |
337 | </indexterm> | |
338 | ||
339 | <indexterm> | |
340 | <primary>client machine</primary> | |
341 | ||
342 | <secondary>/usr/vice/etc directory</secondary> | |
343 | </indexterm> | |
344 | ||
345 | <para>This section briefly describes the client configuration files that must reside in the local <emphasis | |
346 | role="bold">/usr/vice/etc</emphasis> directory on every client machine. If the machine uses a disk cache, there must be a | |
347 | partition devoted to cache files; by convention, it is mounted at the <emphasis role="bold">/usr/vice/cache</emphasis> | |
348 | directory.</para> | |
349 | ||
350 | <para><emphasis role="bold">Note for Windows users:</emphasis> Some files described in this document possibly do not exist on | |
351 | machines that run a Windows operating system. Also, Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather than a | |
352 | forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname.</para> | |
353 | ||
354 | <sect2 id="HDRWQ392"> | |
355 | <title>Configuration Files in the /usr/vice/etc Directory</title> | |
356 | ||
357 | <para>The <emphasis role="bold">/usr/vice/etc</emphasis> directory on a client machine's local disk must contain certain | |
358 | configuration files for the Cache Manager to function properly. They control the most basic aspects of Cache Manager | |
359 | configuration.</para> | |
360 | ||
361 | <para>If it is important that the client machines in your cell perform uniformly, it is most efficient to update these files | |
362 | from a central source. The following descriptions include pointers to sections that discuss how best to maintain the files. | |
363 | <variablelist> | |
364 | <indexterm> | |
365 | <primary>afsd program</primary> | |
366 | </indexterm> | |
367 | ||
368 | <indexterm> | |
369 | <primary>Cache Manager</primary> | |
370 | ||
371 | <secondary>afsd initialization program</secondary> | |
372 | </indexterm> | |
373 | ||
374 | <indexterm> | |
375 | <primary>files</primary> | |
376 | ||
377 | <secondary>afsd</secondary> | |
378 | </indexterm> | |
379 | ||
380 | <indexterm> | |
381 | <primary>commands</primary> | |
382 | ||
383 | <secondary>afsd</secondary> | |
384 | </indexterm> | |
385 | ||
386 | <indexterm> | |
387 | <primary>programs</primary> | |
388 | ||
389 | <secondary>afsd</secondary> | |
390 | </indexterm> | |
391 | ||
392 | <varlistentry> | |
393 | <term><emphasis role="bold">afsd</emphasis></term> | |
394 | ||
395 | <listitem> | |
396 | <para>The binary file for the program that initializes the Cache Manager. It must run each time the machine reboots in | |
397 | order for the machine to remain an AFS client machine. The program also initializes several daemons that improve Cache | |
398 | Manager functioning, such as the process that handles callbacks. <indexterm> | |
399 | <primary>files</primary> | |
400 | ||
401 | <secondary>cacheinfo</secondary> | |
402 | </indexterm> <indexterm> | |
403 | <primary>cacheinfo file</primary> | |
404 | </indexterm></para> | |
405 | </listitem> | |
406 | </varlistentry> | |
407 | ||
408 | <varlistentry> | |
409 | <term><emphasis role="bold">cacheinfo</emphasis></term> | |
410 | ||
411 | <listitem> | |
412 | <para>A one-line file that sets the cache's most basic configuration parameters: the local directory at which the | |
413 | Cache Manager mounts the AFS filespace, the local disk directory to use as the cache, and how many kilobytes to | |
414 | allocate to the cache.</para> | |
415 | ||
416 | <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to create this file as you install a client | |
417 | machine. To change the cache size on a machine that uses a memory cache, edit the file and reboot the machine. On a | |
418 | machine that uses a disk cache, you can change the cache size without rebooting by issuing the <emphasis | |
419 | role="bold">fs setcachesize</emphasis> command. For instructions, see <link linkend="HDRWQ394">Determining the Cache | |
420 | Type, Size, and Location</link>. <indexterm> | |
421 | <primary>CellServDB file (client)</primary> | |
422 | ||
423 | <secondary>about</secondary> | |
424 | </indexterm> <indexterm> | |
425 | <primary>files</primary> | |
426 | ||
427 | <secondary>CellServDB (client)</secondary> | |
428 | </indexterm></para> | |
429 | </listitem> | |
430 | </varlistentry> | |
431 | ||
432 | <varlistentry> | |
433 | <term><emphasis role="bold">CellServDB</emphasis></term> | |
434 | ||
435 | <listitem> | |
436 | <para>This ASCII file names the database server machines in the local cell and in any foreign cell to which you want | |
437 | to enable access from this machine. (Database server machines are the machines in a cell that run the Authentication, | |
438 | Backup, Protection, and VL Server processes; see <link linkend="HDRWQ92">Database Server Machines</link>.)</para> | |
439 | ||
440 | <para>The Cache Manager must be able to reach a cell's database server machines to fetch files from its filespace. | |
441 | Incorrect or missing information in the <emphasis role="bold">CellServDB</emphasis> file can slow or completely block | |
442 | access. It is important to update the file whenever a cell's database server machines change.</para> | |
443 | ||
444 | <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it loads the contents of the | |
445 | file into kernel memory. The Cache Manager does not read the file between reboots, so to incorporate changes to the | |
446 | file into kernel memory, you must reboot the machine. Alternatively, you can issue the <emphasis role="bold">fs | |
447 | newcell</emphasis> command to insert the changes directly into kernel memory without changing the file. It can also be | |
448 | convenient to upgrade the file from a central source. For instructions, see <link linkend="HDRWQ406">Maintaining | |
449 | Knowledge of Database Server Machines</link>.</para> | |
450 | ||
451 | <para>(The <emphasis role="bold">CellServDB</emphasis> file on client machines is not the same as the one kept in the | |
452 | <emphasis role="bold">/usr/afs/etc</emphasis> directory on server machines, which lists only the local cell's database | |
453 | server machines. For instructions on maintaining the server <emphasis role="bold">CellServDB</emphasis> file, see | |
454 | <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>). <indexterm> | |
455 | <primary>NetInfo file (client version)</primary> | |
456 | </indexterm> <indexterm> | |
457 | <primary>files</primary> | |
458 | ||
459 | <secondary>NetInfo (client version)</secondary> | |
460 | </indexterm></para> | |
461 | </listitem> | |
462 | </varlistentry> | |
463 | ||
464 | <varlistentry> | |
465 | <term><emphasis role="bold">NetInfo</emphasis></term> | |
466 | ||
467 | <listitem> | |
468 | <para>This optional ASCII file lists one or more of the network interface addresses on the client machine. If it | |
469 | exists when the Cache Manager initializes, the Cache Manager uses it as the basis for the list of interfaces that it | |
470 | registers with File Servers. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>. <indexterm> | |
471 | <primary>NetRestrict file (client version)</primary> | |
472 | </indexterm> <indexterm> | |
473 | <primary>files</primary> | |
474 | ||
475 | <secondary>NetRestrict (client version)</secondary> | |
476 | </indexterm></para> | |
477 | </listitem> | |
478 | </varlistentry> | |
479 | ||
480 | <varlistentry> | |
481 | <term><emphasis role="bold">NetRestrict</emphasis></term> | |
482 | ||
483 | <listitem> | |
484 | <para>This optional ASCII file lists one or more network interface addresses. If it exists when the Cache Manager | |
485 | initializes, the Cache Manager removes the specified addresses from the list of interfaces that it registers with File | |
486 | Servers. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>. <indexterm> | |
487 | <primary>ThisCell file (client)</primary> | |
488 | </indexterm> <indexterm> | |
489 | <primary>files</primary> | |
490 | ||
491 | <secondary>ThisCell (client)</secondary> | |
492 | </indexterm></para> | |
493 | </listitem> | |
494 | </varlistentry> | |
495 | ||
496 | <varlistentry> | |
497 | <term><emphasis role="bold">ThisCell</emphasis></term> | |
498 | ||
499 | <listitem> | |
500 | <para>This ASCII file contains a single line that specifies the complete domain-style name of the cell to which the | |
501 | machine belongs. Examples are <computeroutput>example.com</computeroutput> and | |
502 | <computeroutput>example.org</computeroutput>. This value defines the default cell in which the machine's users become | |
503 | authenticated, and in which the command interpreters (for example, the <emphasis role="bold">bos</emphasis> command) | |
504 | contact server processes.</para> | |
505 | ||
506 | <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to create this file as you install the AFS client | |
507 | functionality. To learn about changing a client machine's cell membership, see <link linkend="HDRWQ411">Setting a | |
508 | Client Machine's Cell Membership</link>.</para> | |
509 | </listitem> | |
510 | </varlistentry> | |
511 | </variablelist></para> | |
512 | ||
513 | <para>In addition to these files, the <emphasis role="bold">/usr/vice/etc</emphasis> directory also sometimes contains the | |
514 | following types of files and subdirectories: <itemizedlist> | |
515 | <indexterm> | |
516 | <primary>AFS</primary> | |
517 | ||
518 | <secondary>initialization script</secondary> | |
519 | </indexterm> | |
520 | ||
521 | <indexterm> | |
522 | <primary>files</primary> | |
523 | ||
524 | <secondary>AFS initialization script</secondary> | |
525 | </indexterm> | |
526 | ||
527 | <indexterm> | |
528 | <primary>initialization script for AFS</primary> | |
529 | </indexterm> | |
530 | ||
531 | <indexterm> | |
532 | <primary>script for AFS initialization</primary> | |
533 | </indexterm> | |
534 | ||
535 | <listitem> | |
536 | <para>The AFS initialization script, called <emphasis role="bold">afs.rc</emphasis> on many system types. In the | |
537 | conventional configuration specified by the <emphasis>OpenAFS Quick Beginnings</emphasis>, it is a symbolic link to the | |
538 | actual script kept in the same directory as other initialization files used by the operating system. <indexterm> | |
539 | <primary>dynamic kernel loader programs</primary> | |
540 | ||
541 | <secondary>directory for AFS library files</secondary> | |
542 | </indexterm> <indexterm> | |
543 | <primary>files</primary> | |
544 | ||
545 | <secondary>AFS libraries used by dynamic kernel loader programs</secondary> | |
546 | </indexterm></para> | |
547 | </listitem> | |
548 | ||
549 | <listitem> | |
550 | <para>A subdirectory that houses AFS kernel library files used by a dynamic kernel loading program. <indexterm> | |
551 | <primary>afszcm.cat file</primary> | |
552 | </indexterm> <indexterm> | |
553 | <primary>files</primary> | |
554 | ||
555 | <secondary>afszcm.cat</secondary> | |
556 | </indexterm></para> | |
557 | </listitem> | |
558 | ||
559 | <listitem> | |
560 | <para>A subdirectory called <emphasis role="bold">C</emphasis>, which houses the Cache Manager catalog file called | |
561 | <emphasis role="bold">afszcm.cat</emphasis>. The fstrace program uses the catalog file to translate operation codes into | |
562 | character strings, which makes the message in the trace log more readable. See <link linkend="HDRWQ342">About the | |
563 | fstrace Command Suite</link>.</para> | |
564 | </listitem> | |
565 | </itemizedlist></para> | |
566 | </sect2> | |
567 | ||
568 | <sect2 id="HDRWQ393"> | |
569 | <title>Cache-Related Files</title> | |
570 | ||
571 | <indexterm> | |
572 | <primary>usr/vice/cache directory</primary> | |
573 | </indexterm> | |
574 | ||
575 | <indexterm> | |
576 | <primary>directory</primary> | |
577 | ||
578 | <secondary>/usr/vice/cache</secondary> | |
579 | </indexterm> | |
580 | ||
581 | <indexterm> | |
582 | <primary>directory</primary> | |
583 | ||
584 | <secondary>disk cache</secondary> | |
585 | </indexterm> | |
586 | ||
587 | <indexterm> | |
588 | <primary>cache files (client)</primary> | |
589 | </indexterm> | |
590 | ||
591 | <indexterm> | |
592 | <primary>client machine</primary> | |
593 | ||
594 | <secondary>cache files</secondary> | |
595 | </indexterm> | |
596 | ||
597 | <para>A client machine that uses a disk cache must have a local disk directory devoted to the cache. The conventional mount | |
598 | point is <emphasis role="bold">/usr/vice/cache</emphasis>, but you can use another partition that has more available | |
599 | space.</para> | |
600 | ||
601 | <para>Do not delete or directly modify any of the files in the cache directory. Doing so can cause a kernel panic, from which | |
602 | the only way to recover is to reboot the machine. By default, only the local superuser <emphasis role="bold">root</emphasis> | |
603 | can read the files directly, by virtue of owning them.</para> | |
604 | ||
605 | <para>A client machine that uses a memory cache keeps all of the information stored in these files in machine memory instead. | |
606 | <variablelist> | |
607 | <indexterm> | |
608 | <primary>CacheItems file</primary> | |
609 | </indexterm> | |
610 | ||
611 | <indexterm> | |
612 | <primary>files</primary> | |
613 | ||
614 | <secondary>CacheItems</secondary> | |
615 | </indexterm> | |
616 | ||
617 | <varlistentry> | |
618 | <term><emphasis role="bold">CacheItems</emphasis></term> | |
619 | ||
620 | <listitem> | |
621 | <para>A binary-format file in which the Cache Manager tracks the contents of cache chunks (the <emphasis | |
622 | role="bold">V</emphasis> files in the directory, described just following), including the file ID number (fID) and the | |
623 | data version number. <indexterm> | |
624 | <primary>files</primary> | |
625 | ||
626 | <secondary>VolumeItems</secondary> | |
627 | </indexterm> <indexterm> | |
628 | <primary>VolumeItems file</primary> | |
629 | </indexterm></para> | |
630 | </listitem> | |
631 | </varlistentry> | |
632 | ||
633 | <varlistentry> | |
634 | <term><emphasis role="bold">VolumeItems</emphasis></term> | |
635 | ||
636 | <listitem> | |
637 | <para>A binary-format file in which the Cache Manager records the mapping between mount points and the volumes from | |
638 | which it has fetched data. The Cache Manager uses the information when responding to the <emphasis | |
639 | role="bold">pwd</emphasis> command, among others. <indexterm> | |
640 | <primary>files</primary> | |
641 | ||
642 | <secondary>Vn</secondary> | |
643 | </indexterm> <indexterm> | |
644 | <primary>Vn file (data cache)</primary> | |
645 | </indexterm> <indexterm> | |
646 | <primary>data cache</primary> | |
647 | ||
648 | <secondary>Vn file in</secondary> | |
649 | </indexterm></para> | |
650 | </listitem> | |
651 | </varlistentry> | |
652 | ||
653 | <varlistentry> | |
654 | <term><emphasis role="bold">Vn</emphasis></term> | |
655 | ||
656 | <listitem> | |
657 | <para>A cache chunk file, which expands to a maximum size (by default, 64 KB) to house data fetched from AFS files. | |
658 | The number of <emphasis role="bold">V</emphasis>n files in the cache depends on the cache size among other factors. | |
659 | The n is the index assigned to each file; they are numbered sequentially, but the Cache Manager does not necessarily | |
660 | use them in order or contiguously. If an AFS file is larger than the maximum size for <emphasis | |
661 | role="bold">V</emphasis>n files, the Cache Manager divides it across multiple <emphasis role="bold">V</emphasis>n | |
662 | files.</para> | |
663 | </listitem> | |
664 | </varlistentry> | |
665 | </variablelist></para> | |
666 | </sect2> | |
667 | </sect1> | |
668 | ||
669 | <sect1 id="HDRWQ394"> | |
670 | <title>Determining the Cache Type, Size, and Location</title> | |
671 | ||
672 | <para>This section explains how to configure a memory or disk cache, how to display and set the size of either type of cache, | |
673 | and how to set the location of the cache directory for a disk cache. <indexterm> | |
674 | <primary>data cache</primary> | |
675 | ||
676 | <secondary>disk versus memory</secondary> | |
677 | </indexterm> <indexterm> | |
678 | <primary>client machine</primary> | |
679 | ||
680 | <secondary>disk versus memory cache</secondary> | |
681 | </indexterm></para> | |
682 | ||
683 | <para>The Cache Manager uses a disk cache by default, and it is the preferred type of caching. To configure a memory cache, | |
684 | include the <emphasis role="bold">-memcache</emphasis> flag on the <emphasis role="bold">afsd</emphasis> command, which is | |
685 | normally invoked in the machine's AFS initialization file. If configured to use a memory cache, the Cache Manager does no disk | |
686 | caching, even if the machine has a disk.</para> | |
687 | ||
688 | <sect2 id="Header_438"> | |
689 | <title>Choosing the Cache Size</title> | |
690 | ||
691 | <indexterm> | |
692 | <primary>data cache</primary> | |
693 | ||
694 | <secondary>size</secondary> | |
695 | ||
696 | <tertiary>recommendations</tertiary> | |
697 | </indexterm> | |
698 | ||
699 | <para>Cache size influences the performance of a client machine more directly than perhaps any other cache parameter. The | |
700 | larger the cache, the faster the Cache Manager is likely to deliver files to users. A small cache can impair performance | |
701 | because it increases the frequency at which the Cache Manager must discard cached data to make room for newly requested data. | |
702 | When an application asks for data that has been discarded, the Cache Manager must request it from the File Server, and | |
703 | fetching data across the network is almost always slower than fetching it from the local disk. The Cache Manager never | |
704 | discards data from a file that has been modified locally but not yet stored back to the File Server. If the cache is very | |
705 | small, the Cache Manager possible cannot find any data to discard. For more information about the algorithm it uses when | |
706 | discarding cached data, see <link linkend="HDRWQ401">How the Cache Manager Chooses Data to Discard</link>).</para> | |
707 | ||
708 | <para>The amount of disk or memory you devote to caching depends on several factors. The amount of space available in memory | |
709 | or on the partition housing the disk cache directory imposes an absolute limit. In addition, you cannot allocate more than 95% | |
710 | of the space available on the cache directory's partition to a disk cache. The <emphasis role="bold">afsd</emphasis> program | |
711 | exits without starting the Cache Manager and prints an appropriate message to the standard output stream if you violate this | |
712 | restriction. For a memory cache, you must leave enough memory for other processes and applications to run. If you try to | |
713 | allocate more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing | |
714 | the Cache Manager and produces the following message on the standard output stream:</para> | |
715 | ||
716 | <programlisting> | |
717 | afsd: memCache allocation failure at number KB | |
718 | </programlisting> | |
719 | ||
720 | <para>where number is how many kilobytes were allocated just before the failure.</para> | |
721 | ||
722 | <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the | |
723 | machine, the size of the files with which they usually work, and (for a memory cache) the number of processes that usually run | |
724 | on the machine. The higher the demand from these factors, the larger the cache needs to be to maintain good | |
725 | performance.</para> | |
726 | ||
727 | <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better | |
728 | with a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance | |
729 | depends on the factors mentioned previously, and is difficult to predict.</para> | |
730 | ||
731 | <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually | |
732 | unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on | |
733 | memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can | |
734 | use a smaller memory cache.</para> | |
735 | ||
736 | <para>AFS imposes an absolute limit on cache size in some versions. See the <emphasis>OpenAFS Release Notes</emphasis> for the | |
737 | version you are using.</para> | |
738 | </sect2> | |
739 | ||
740 | <sect2 id="HDRWQ395"> | |
741 | <title>Displaying and Setting the Cache Size and Location</title> | |
742 | ||
743 | <indexterm> | |
744 | <primary>Cache Manager</primary> | |
745 | ||
746 | <secondary>setting</secondary> | |
747 | ||
748 | <tertiary>disk cache location</tertiary> | |
749 | </indexterm> | |
750 | ||
751 | <indexterm> | |
752 | <primary>Cache Manager</primary> | |
753 | ||
754 | <secondary>displaying</secondary> | |
755 | ||
756 | <tertiary>cache size from cacheinfo file</tertiary> | |
757 | </indexterm> | |
758 | ||
759 | <indexterm> | |
760 | <primary>Cache Manager</primary> | |
761 | ||
762 | <secondary>setting</secondary> | |
763 | ||
764 | <tertiary>cache size in cacheinfo file</tertiary> | |
765 | </indexterm> | |
766 | ||
767 | <indexterm> | |
768 | <primary>Cache Manager</primary> | |
769 | ||
770 | <secondary>data cache</secondary> | |
771 | ||
772 | <tertiary>displaying size set at reboot</tertiary> | |
773 | </indexterm> | |
774 | ||
775 | <indexterm> | |
776 | <primary>cacheinfo file</primary> | |
777 | ||
778 | <secondary>setting</secondary> | |
779 | ||
780 | <tertiary>disk cache location</tertiary> | |
781 | </indexterm> | |
782 | ||
783 | <indexterm> | |
784 | <primary>cacheinfo file</primary> | |
785 | ||
786 | <secondary>displaying contents</secondary> | |
787 | </indexterm> | |
788 | ||
789 | <indexterm> | |
790 | <primary>cacheinfo file</primary> | |
791 | ||
792 | <secondary>setting</secondary> | |
793 | ||
794 | <tertiary>cache size</tertiary> | |
795 | </indexterm> | |
796 | ||
797 | <indexterm> | |
798 | <primary>changing</primary> | |
799 | ||
800 | <secondary>data cache size specified in cacheinfo file</secondary> | |
801 | </indexterm> | |
802 | ||
803 | <indexterm> | |
804 | <primary>changing</primary> | |
805 | ||
806 | <secondary>disk cache location, in cacheinfo file</secondary> | |
807 | </indexterm> | |
808 | ||
809 | <indexterm> | |
810 | <primary>client machine</primary> | |
811 | ||
812 | <secondary>setting</secondary> | |
813 | ||
814 | <tertiary>disk cache location</tertiary> | |
815 | </indexterm> | |
816 | ||
817 | <indexterm> | |
818 | <primary>client machine</primary> | |
819 | ||
820 | <secondary>data cache size set at reboot</secondary> | |
821 | ||
822 | <tertiary>displaying</tertiary> | |
823 | </indexterm> | |
824 | ||
825 | <indexterm> | |
826 | <primary>client machine</primary> | |
827 | ||
828 | <secondary>displaying</secondary> | |
829 | ||
830 | <tertiary>data cache size from cacheinfo file</tertiary> | |
831 | </indexterm> | |
832 | ||
833 | <indexterm> | |
834 | <primary>client machine</primary> | |
835 | ||
836 | <secondary>setting</secondary> | |
837 | ||
838 | <tertiary>data cache size in cacheinfo file</tertiary> | |
839 | </indexterm> | |
840 | ||
841 | <indexterm> | |
842 | <primary>displaying</primary> | |
843 | ||
844 | <secondary>data cache size</secondary> | |
845 | ||
846 | <tertiary>set at reboot</tertiary> | |
847 | </indexterm> | |
848 | ||
849 | <indexterm> | |
850 | <primary>displaying</primary> | |
851 | ||
852 | <secondary>data cache size</secondary> | |
853 | ||
854 | <tertiary>specified in cacheinfo file</tertiary> | |
855 | </indexterm> | |
856 | ||
857 | <indexterm> | |
858 | <primary>data cache</primary> | |
859 | ||
860 | <secondary>size</secondary> | |
861 | ||
862 | <tertiary>setting in cacheinfo file</tertiary> | |
863 | </indexterm> | |
864 | ||
865 | <indexterm> | |
866 | <primary>data cache</primary> | |
867 | ||
868 | <secondary>changing location of disk cache</secondary> | |
869 | </indexterm> | |
870 | ||
871 | <indexterm> | |
872 | <primary>data cache</primary> | |
873 | ||
874 | <secondary>size</secondary> | |
875 | ||
876 | <tertiary>set at reboot, displaying</tertiary> | |
877 | </indexterm> | |
878 | ||
879 | <indexterm> | |
880 | <primary>data cache</primary> | |
881 | ||
882 | <secondary>displaying size specified in cacheinfo file</secondary> | |
883 | </indexterm> | |
884 | ||
885 | <indexterm> | |
886 | <primary>location</primary> | |
887 | ||
888 | <secondary>setting for client</secondary> | |
889 | </indexterm> | |
890 | ||
891 | <indexterm> | |
892 | <primary>setting</primary> | |
893 | ||
894 | <secondary>disk cache location in cacheinfo file</secondary> | |
895 | </indexterm> | |
896 | ||
897 | <para>The Cache Manager determines how big to make the cache by reading the <emphasis | |
898 | role="bold">/usr/vice/etc/cacheinfo</emphasis> file as it initializes. As directed in the <emphasis>OpenAFS Quick | |
899 | Beginnings</emphasis>, you must create the file before running the <emphasis role="bold">afsd</emphasis> program. The file | |
900 | also defines the directory on which to mount AFS (by convention, <emphasis role="bold">/afs</emphasis>), and the local disk | |
901 | directory to use for a cache directory.</para> | |
902 | ||
903 | <para>To change any of the values in the file, log in as the local superuser <emphasis role="bold">root</emphasis>. You must | |
904 | reboot the machine to have the new value take effect. For instructions, see <link linkend="HDRWQ398">To edit the cacheinfo | |
905 | file</link>.</para> | |
906 | ||
907 | <para>To change the cache size at reboot without editing the <emphasis role="bold">cacheinfo</emphasis> file, include the | |
908 | <emphasis role="bold">-blocks</emphasis> argument to the <emphasis role="bold">afsd</emphasis> command; see the command's | |
909 | reference page in the OpenAFS Administration Reference.</para> | |
910 | ||
911 | <para>For a disk cache, you can also use the <emphasis role="bold">fs setcachesize</emphasis> command to reset the cache size | |
912 | without rebooting. The value you set persists until the next reboot, at which time the cache size returns to the value | |
913 | specified in the <emphasis role="bold">cacheinfo</emphasis> file or by the <emphasis role="bold">-blocks</emphasis> argument | |
914 | to the <emphasis role="bold">afsd</emphasis> command. For instructions, see <link linkend="HDRWQ399">To change the disk cache | |
915 | size without rebooting</link>.</para> | |
916 | ||
917 | <para>To display the current cache size and the amount of space the Cache Manager is using at the moment, use the <emphasis | |
918 | role="bold">fs getcacheparms</emphasis> command as detailed in <link linkend="HDRWQ397">To display the current cache | |
919 | size</link>.</para> | |
920 | </sect2> | |
921 | ||
922 | <sect2 id="HDRWQ396"> | |
923 | <title>To display the cache size set at reboot</title> | |
924 | ||
925 | <orderedlist> | |
926 | <listitem> | |
927 | <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis | |
928 | role="bold">/usr/vice/etc/cacheinfo</emphasis> file. <programlisting> | |
929 | % <emphasis role="bold">cat /usr/vice/etc/cacheinfo</emphasis> | |
930 | </programlisting></para> | |
931 | </listitem> | |
932 | </orderedlist> | |
933 | ||
934 | <indexterm> | |
935 | <primary>data cache</primary> | |
936 | ||
937 | <secondary>size</secondary> | |
938 | ||
939 | <tertiary>current, displaying</tertiary> | |
940 | </indexterm> | |
941 | ||
942 | <indexterm> | |
943 | <primary>client machine</primary> | |
944 | ||
945 | <secondary>data cache size</secondary> | |
946 | ||
947 | <tertiary>displaying current</tertiary> | |
948 | </indexterm> | |
949 | ||
950 | <indexterm> | |
951 | <primary>Cache Manager</primary> | |
952 | ||
953 | <secondary>data cache size</secondary> | |
954 | ||
955 | <tertiary>displaying current</tertiary> | |
956 | </indexterm> | |
957 | ||
958 | <indexterm> | |
959 | <primary>displaying</primary> | |
960 | ||
961 | <secondary>data cache size, current</secondary> | |
962 | </indexterm> | |
963 | ||
964 | <indexterm> | |
965 | <primary>fs commands</primary> | |
966 | ||
967 | <secondary>getcacheparms</secondary> | |
968 | </indexterm> | |
969 | ||
970 | <indexterm> | |
971 | <primary>commands</primary> | |
972 | ||
973 | <secondary>fs getcacheparms</secondary> | |
974 | </indexterm> | |
975 | </sect2> | |
976 | ||
977 | <sect2 id="HDRWQ397"> | |
978 | <title>To display the current cache size</title> | |
979 | ||
980 | <orderedlist> | |
981 | <listitem> | |
982 | <para>Issue the <emphasis role="bold">fs getcacheparms</emphasis> command on the client machine. <programlisting> | |
983 | % <emphasis role="bold">fs getcacheparms</emphasis> | |
984 | </programlisting></para> | |
985 | ||
986 | <para>where <emphasis role="bold">getca</emphasis> is the shortest acceptable abbreviation of <emphasis | |
987 | role="bold">getcacheparms</emphasis>.</para> | |
988 | ||
989 | <para>The output shows the number of kilobyte blocks the Cache Manager is using as a cache at the moment the command is | |
990 | issued, and the current size of the cache. For example:</para> | |
991 | ||
992 | <programlisting> | |
993 | AFS using 13709 of the cache's available 15000 1K byte blocks. | |
994 | </programlisting> | |
995 | </listitem> | |
996 | </orderedlist> | |
997 | ||
998 | <indexterm> | |
999 | <primary>data cache</primary> | |
1000 | ||
1001 | <secondary>size</secondary> | |
1002 | ||
1003 | <tertiary>setting in cacheinfo file</tertiary> | |
1004 | </indexterm> | |
1005 | ||
1006 | <indexterm> | |
1007 | <primary>client machine</primary> | |
1008 | ||
1009 | <secondary>data cache size</secondary> | |
1010 | ||
1011 | <tertiary>setting in cacheinfo file</tertiary> | |
1012 | </indexterm> | |
1013 | ||
1014 | <indexterm> | |
1015 | <primary>Cache Manager</primary> | |
1016 | ||
1017 | <secondary>data cache size</secondary> | |
1018 | ||
1019 | <tertiary>setting in cacheinfo file</tertiary> | |
1020 | </indexterm> | |
1021 | ||
1022 | <indexterm> | |
1023 | <primary>setting</primary> | |
1024 | ||
1025 | <secondary>data cache size in cacheinfo file</secondary> | |
1026 | </indexterm> | |
1027 | ||
1028 | <indexterm> | |
1029 | <primary>cacheinfo file</primary> | |
1030 | ||
1031 | <secondary>format</secondary> | |
1032 | </indexterm> | |
1033 | </sect2> | |
1034 | ||
1035 | <sect2 id="HDRWQ398"> | |
1036 | <title>To edit the cacheinfo file</title> | |
1037 | ||
1038 | <orderedlist> | |
1039 | <listitem> | |
1040 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
1041 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
1042 | % <emphasis role="bold">su root</emphasis> | |
1043 | Password: <<replaceable>root_password</replaceable>> | |
1044 | </programlisting></para> | |
1045 | </listitem> | |
1046 | ||
1047 | <listitem> | |
1048 | <para>Use a text editor to edit the <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file, which has three fields, | |
1049 | separated by colons: <itemizedlist> | |
1050 | <listitem> | |
1051 | <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is | |
1052 | <emphasis role="bold">/afs</emphasis>.</para> | |
1053 | </listitem> | |
1054 | ||
1055 | <listitem> | |
1056 | <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the | |
1057 | <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another | |
1058 | partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if | |
1059 | the machine uses a memory cache.</para> | |
1060 | </listitem> | |
1061 | ||
1062 | <listitem> | |
1063 | <para>The third field defines cache size as a number of kilobyte (1024-byte) blocks.</para> | |
1064 | </listitem> | |
1065 | </itemizedlist></para> | |
1066 | ||
1067 | <para>The following example mounts the AFS filespace at the <emphasis role="bold">/afs</emphasis> directory, names | |
1068 | <emphasis role="bold">/usr/vice/cache</emphasis> as the cache directory, and sets cache size to 50,000 KB:</para> | |
1069 | ||
1070 | <programlisting> | |
1071 | <emphasis role="bold">/afs:/usr/vice/cache:50000</emphasis> | |
1072 | </programlisting> | |
1073 | </listitem> | |
1074 | </orderedlist> | |
1075 | ||
1076 | <indexterm> | |
1077 | <primary>data cache</primary> | |
1078 | ||
1079 | <secondary>size</secondary> | |
1080 | ||
1081 | <tertiary>setting until next reboot</tertiary> | |
1082 | </indexterm> | |
1083 | ||
1084 | <indexterm> | |
1085 | <primary>changing</primary> | |
1086 | ||
1087 | <secondary>data cache size temporarily</secondary> | |
1088 | </indexterm> | |
1089 | ||
1090 | <indexterm> | |
1091 | <primary>client machine</primary> | |
1092 | ||
1093 | <secondary>data cache size</secondary> | |
1094 | ||
1095 | <tertiary>setting until next reboot</tertiary> | |
1096 | </indexterm> | |
1097 | ||
1098 | <indexterm> | |
1099 | <primary>Cache Manager</primary> | |
1100 | ||
1101 | <secondary>data cache size</secondary> | |
1102 | ||
1103 | <tertiary>setting until next reboot</tertiary> | |
1104 | </indexterm> | |
1105 | ||
1106 | <indexterm> | |
1107 | <primary>fs commands</primary> | |
1108 | ||
1109 | <secondary>setcachesize</secondary> | |
1110 | </indexterm> | |
1111 | ||
1112 | <indexterm> | |
1113 | <primary>commands</primary> | |
1114 | ||
1115 | <secondary>fs setcachesize</secondary> | |
1116 | </indexterm> | |
1117 | </sect2> | |
1118 | ||
1119 | <sect2 id="HDRWQ399"> | |
1120 | <title>To change the disk cache size without rebooting</title> | |
1121 | ||
1122 | <orderedlist> | |
1123 | <listitem> | |
1124 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
1125 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
1126 | % <emphasis role="bold">su root</emphasis> | |
1127 | Password: <<replaceable>root_password</replaceable>> | |
1128 | </programlisting></para> | |
1129 | </listitem> | |
1130 | ||
1131 | <listitem> | |
1132 | <para>Issue the <emphasis role="bold">fs setcachesize</emphasis> command to set a new disk cache | |
1133 | size.</para> | |
1134 | ||
1135 | <note> | |
1136 | <para>This command does not work for a memory cache.</para> | |
1137 | </note> | |
1138 | ||
1139 | <programlisting> | |
1140 | # <emphasis role="bold">fs setcachesize</emphasis> <<replaceable>size in 1K byte blocks (0 =</replaceable>> reset)> | |
1141 | </programlisting> | |
1142 | ||
1143 | <para>where <variablelist> | |
1144 | <varlistentry> | |
1145 | <term><emphasis role="bold">setca</emphasis></term> | |
1146 | ||
1147 | <listitem> | |
1148 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcachesize</emphasis>.</para> | |
1149 | </listitem> | |
1150 | </varlistentry> | |
1151 | ||
1152 | <varlistentry> | |
1153 | <term><emphasis role="bold">size in 1K byte blocks (0 => reset)</emphasis></term> | |
1154 | ||
1155 | <listitem> | |
1156 | <para>Sets the number of kilobyte blocks to be used for the cache. Specify a positive integer (<emphasis | |
1157 | role="bold">1024</emphasis> equals 1 MB), or <emphasis role="bold">0</emphasis> (zero) to reset the cache size to | |
1158 | the value specified in the <emphasis role="bold">cacheinfo</emphasis> file.</para> | |
1159 | </listitem> | |
1160 | </varlistentry> | |
1161 | </variablelist></para> | |
1162 | </listitem> | |
1163 | </orderedlist> | |
1164 | ||
1165 | <indexterm> | |
1166 | <primary>data cache</primary> | |
1167 | ||
1168 | <secondary>disk cache size</secondary> | |
1169 | ||
1170 | <tertiary>resetting to default value</tertiary> | |
1171 | </indexterm> | |
1172 | ||
1173 | <indexterm> | |
1174 | <primary>changing</primary> | |
1175 | ||
1176 | <secondary>disk cache size to default value</secondary> | |
1177 | </indexterm> | |
1178 | ||
1179 | <indexterm> | |
1180 | <primary>resetting</primary> | |
1181 | ||
1182 | <secondary>disk cache size to default value</secondary> | |
1183 | </indexterm> | |
1184 | ||
1185 | <indexterm> | |
1186 | <primary>cacheinfo file</primary> | |
1187 | ||
1188 | <secondary>resetting disk cache to size specified</secondary> | |
1189 | </indexterm> | |
1190 | ||
1191 | <indexterm> | |
1192 | <primary>client machine</primary> | |
1193 | ||
1194 | <secondary>disk cache size</secondary> | |
1195 | ||
1196 | <tertiary>resetting to default value</tertiary> | |
1197 | </indexterm> | |
1198 | ||
1199 | <indexterm> | |
1200 | <primary>Cache Manager</primary> | |
1201 | ||
1202 | <secondary>data cache size</secondary> | |
1203 | ||
1204 | <tertiary>resetting to default value (for disk cache only)</tertiary> | |
1205 | </indexterm> | |
1206 | </sect2> | |
1207 | ||
1208 | <sect2 id="Header_444"> | |
1209 | <title>To reset the disk cache size to the default without rebooting</title> | |
1210 | ||
1211 | <orderedlist> | |
1212 | <listitem> | |
1213 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
1214 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
1215 | % <emphasis role="bold">su root</emphasis> | |
1216 | Password: <<replaceable>root_password</replaceable>> | |
1217 | </programlisting></para> | |
1218 | </listitem> | |
1219 | ||
1220 | <listitem> | |
1221 | <para>Issue the <emphasis role="bold">fs setcachesize</emphasis> command to reset the size of the local disk cache (the | |
1222 | command does not work for a memory cache). Choose one of the two following options: <itemizedlist> | |
1223 | <listitem> | |
1224 | <para>To reset the cache size to the value specified in the local <emphasis role="bold">cacheinfo</emphasis> file, | |
1225 | specify the value <emphasis role="bold">0</emphasis> (zero) <programlisting> | |
1226 | # <emphasis role="bold">fs setcachesize 0</emphasis> | |
1227 | </programlisting></para> | |
1228 | </listitem> | |
1229 | ||
1230 | <listitem> | |
1231 | <para>To reset the cache size to the value set at the last reboot of the machine, include the <emphasis | |
1232 | role="bold">-reset</emphasis> flag. Unless the <emphasis role="bold">-blocks</emphasis> argument was used on the | |
1233 | <emphasis role="bold">afsd</emphasis> command, this is also the value in the <emphasis | |
1234 | role="bold">cacheinfo</emphasis> file. <programlisting> | |
1235 | # <emphasis role="bold">fs setcachesize -reset</emphasis> | |
1236 | </programlisting></para> | |
1237 | </listitem> | |
1238 | </itemizedlist></para> | |
1239 | ||
1240 | <para>where <variablelist> | |
1241 | <varlistentry> | |
1242 | <term><emphasis role="bold">setca</emphasis></term> | |
1243 | ||
1244 | <listitem> | |
1245 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcachesize</emphasis>.</para> | |
1246 | </listitem> | |
1247 | </varlistentry> | |
1248 | ||
1249 | <varlistentry> | |
1250 | <term><emphasis role="bold">0</emphasis></term> | |
1251 | ||
1252 | <listitem> | |
1253 | <para>Resets the disk cache size to the value in the third field of the <emphasis | |
1254 | role="bold">/usr/vice/etc/cacheinfo</emphasis> file.</para> | |
1255 | </listitem> | |
1256 | </varlistentry> | |
1257 | ||
1258 | <varlistentry> | |
1259 | <term><emphasis role="bold">-reset</emphasis></term> | |
1260 | ||
1261 | <listitem> | |
1262 | <para>Resets the cache size to the value set at the last reboot.</para> | |
1263 | </listitem> | |
1264 | </varlistentry> | |
1265 | </variablelist></para> | |
1266 | </listitem> | |
1267 | </orderedlist> | |
1268 | </sect2> | |
1269 | ||
1270 | <sect2 id="HDRWQ401"> | |
1271 | <title>How the Cache Manager Chooses Data to Discard</title> | |
1272 | ||
1273 | <para>When the cache is full and application programs request more data from AFS, the Cache Manager must flush out cache | |
1274 | chunks to make room for the data. The Cache Manager considers two factors: <orderedlist> | |
1275 | <listitem> | |
1276 | <para>How recently an application last accessed the data.</para> | |
1277 | </listitem> | |
1278 | ||
1279 | <listitem> | |
1280 | <para>Whether the chunk is <emphasis>dirty</emphasis>. A dirty chunk contains changes to a file that have not yet been | |
1281 | saved back to the permanent copy stored on a file server machine.</para> | |
1282 | </listitem> | |
1283 | </orderedlist></para> | |
1284 | ||
1285 | <para>The Cache Manager first checks the least-recently used chunk. If it is not dirty, the Cache Manager discards the data in | |
1286 | that chunk. If the chunk is dirty, the Cache Manager moves on to check the next least recently used chunk. It continues in | |
1287 | this manner until it has created a sufficient number of empty chunks.</para> | |
1288 | ||
1289 | <para>Chunks that contain data fetched from a read-only volume are by definition never dirty, so the Cache Manager can always | |
1290 | discard them. Normally, the Cache Manager can also find chunks of data fetched from read/write volumes that are not dirty, but | |
1291 | a small cache makes it difficult to find enough eligible data. If the Cache Manager cannot find any data to discard, it must | |
1292 | return I/O errors to application programs that request more data from AFS. Application programs usually have a means for | |
1293 | notifying the user of such errors, but not for revealing their cause.</para> | |
1294 | </sect2> | |
1295 | </sect1> | |
1296 | ||
1297 | <sect1 id="HDRWQ402"> | |
1298 | <title>Setting Other Cache Parameters with the afsd program</title> | |
1299 | ||
1300 | <para>There are only three cache configuration parameters you must set: the mount directory for AFS, the location of the disk | |
1301 | cache directory, and the cache size. They correspond to the three fields in the <emphasis | |
1302 | role="bold">/usr/vice/etc/cacheinfo</emphasis> file, as discussed in <link linkend="HDRWQ394">Determining the Cache Type, Size, | |
1303 | and Location</link>. However, if you want to experiment with fine-tuning cache performance, you can use the arguments on the | |
1304 | <emphasis role="bold">afsd</emphasis> command to control several other parameters. This section discusses a few of these | |
1305 | parameters that have the most direct effect on cache performance. To learn more about the <emphasis role="bold">afsd</emphasis> | |
1306 | command's arguments, see its reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para> | |
1307 | ||
1308 | <para>In addition, the AFS initialization script included in the AFS distribution for each system type includes several | |
1309 | variables that set several <emphasis role="bold">afsd</emphasis> arguments in a way that is suitable for client machines of | |
1310 | different sizes and usage patterns. For instructions on using the script most effectively, see the section on configuring the | |
1311 | Cache Manager in the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para> | |
1312 | ||
1313 | <sect2 id="HDRWQ403"> | |
1314 | <title>Setting Cache Configuration Parameters</title> | |
1315 | ||
1316 | <para>The cache configuration parameters with the most direct effect on cache performance include the following: <itemizedlist> | |
1317 | <listitem> | |
1318 | <para><emphasis>total cache size</emphasis>. This is the amount of disk space or machine memory available for caching, | |
1319 | as discussed in detail in <link linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para> | |
1320 | </listitem> | |
1321 | ||
1322 | <listitem> | |
1323 | <para><emphasis>number of cache chunks</emphasis>. For a disk cache, each chunk is a <emphasis role="bold">V</emphasis>n | |
1324 | file in the local cache directory (see <link linkend="HDRWQ393">Cache-Related Files</link>). For a memory cache, each | |
1325 | chunk is a set of contiguous blocks allocated in machine memory.</para> | |
1326 | ||
1327 | <para>This parameter does not have as much of an effect on cache performance as total size. However, adjusting it can | |
1328 | influence how often the Cache Manager must discard cached data to make room for new data. Suppose, for example, that you | |
1329 | set the disk cache size to 50 MB and the number of chunks (<emphasis role="bold">V</emphasis>n files) to 1,000. If each | |
1330 | of the ten users on the machine caches 100 AFS files that average 20 KB in size, then all 1,000 chunks are full (a chunk | |
1331 | can contain data from only one AFS file) but the cache holds only about 20 MB of data. When a user requests more data | |
1332 | from the File Server, the Cache Manager must discard cached data to reclaim some chunks, even though the cache is filled | |
1333 | to less than 50% of its capacity. In such a situation, increasing the number of chunks enables the Cache Manager to | |
1334 | discard data less often.</para> | |
1335 | </listitem> | |
1336 | ||
1337 | <listitem> | |
1338 | <para><emphasis>chunk size</emphasis>. This parameter determines the maximum amount of data that can fit in a chunk. If | |
1339 | a cached element is smaller than the chunk size, the remaining space in the chunk is not used (a chunk can hold no more | |
1340 | than one element). If an element cannot fit in a single chunk, it is split across as many chunks as needed. This | |
1341 | parameter also determines how much data the Cache Manager requests at a time from the File Server (how much data per | |
1342 | <emphasis>fetch RPC</emphasis>, because AFS uses partial file transfer).</para> | |
1343 | ||
1344 | <para>The main reason to change chunk size is because of its relation to the amount of data fetched per RPC. If your | |
1345 | network links are very fast, it can improve performance to increase chunk size; if the network is especially slow, it | |
1346 | can make sense to decrease chunk size.</para> | |
1347 | </listitem> | |
1348 | ||
1349 | <listitem> | |
1350 | <para><emphasis>number of dcache entries in memory</emphasis>. The Cache Manager maintains one dcache entry for each | |
1351 | cache chunk, recording a small amount of information, such as the file ID (fID) and version number of the AFS file | |
1352 | corresponding to the chunk.</para> | |
1353 | ||
1354 | <para>For a disk cache, dcache entries reside in the <emphasis role="bold">/usr/vice/cache/CacheItems</emphasis> file; a | |
1355 | small number are duplicated in machine memory to speed access.</para> | |
1356 | ||
1357 | <para>For a memory cache, the number of dcache entries equals the number of cache chunks. For a discussion of the | |
1358 | implications of this correspondence, see <link linkend="HDRWQ405">Controlling Memory Cache Configuration</link>.</para> | |
1359 | </listitem> | |
1360 | </itemizedlist></para> | |
1361 | ||
1362 | <para>For a description of how the Cache Manager determines defaults for number of chunks, chunk size, and number of dcache | |
1363 | entries in a disk cache, see <link linkend="HDRWQ404">Configuring a Disk Cache</link>; for a memory cache, see <link | |
1364 | linkend="HDRWQ405">Controlling Memory Cache Configuration</link>. The instructions also explain how to use the <emphasis | |
1365 | role="bold">afsd</emphasis> command's arguments to override the defaults.</para> | |
1366 | </sect2> | |
1367 | ||
1368 | <sect2 id="HDRWQ404"> | |
1369 | <title>Configuring a Disk Cache</title> | |
1370 | ||
1371 | <para>The default number of cache chunks (<emphasis role="bold">V</emphasis>n files) in a disk cache is calculated by the | |
1372 | <emphasis role="bold">afsd</emphasis> command to be the greatest of the following: <itemizedlist> | |
1373 | <listitem> | |
1374 | <para>100</para> | |
1375 | </listitem> | |
1376 | ||
1377 | <listitem> | |
1378 | <para>1.5 times the result of dividing cache size by chunk size (cachesize/chunksize * 1.5)</para> | |
1379 | </listitem> | |
1380 | ||
1381 | <listitem> | |
1382 | <para>The result of dividing cachesize by 10 MB (cachesize/10240)</para> | |
1383 | </listitem> | |
1384 | </itemizedlist></para> | |
1385 | ||
1386 | <para>You can override this value by specifying a positive integer with the <emphasis role="bold">-files</emphasis> argument. | |
1387 | Consider increasing this value if more than 75% of the <emphasis role="bold">V</emphasis>n files are already used soon after | |
1388 | the Cache Manager finishes initializing. Consider decreasing it if only a small percentage of the chunks are used at that | |
1389 | point. In any case, never specify a value less than 100, because a smaller value can cause performance problems.</para> | |
1390 | ||
1391 | <para>The following example sets the number of <emphasis role="bold">V</emphasis>n files to 2,000:</para> | |
1392 | ||
1393 | <programlisting> | |
1394 | <emphasis role="bold">/usr/vice/etc/afsd -files 2000</emphasis> | |
1395 | </programlisting> | |
1396 | ||
1397 | <note> | |
1398 | <para>It is conventional to place the <emphasis role="bold">afsd</emphasis> command in a machine's AFS initialization file, | |
1399 | rather than entering it in a command shell. Furthermore, the values specified in this section are examples only, and are not | |
1400 | necessarily suitable for a specific machine.</para> | |
1401 | </note> | |
1402 | ||
1403 | <para>The default chunk size for a disk cache is 64 KB. In general, the only reason to change it is to adjust to exceptionally | |
1404 | slow or fast networks; see <link linkend="HDRWQ403">Setting Cache Configuration Parameters</link>. You can use the <emphasis | |
1405 | role="bold">-chunksize</emphasis> argument to override the default. Chunk size must be a power of 2, so provide an integer | |
1406 | between 0 (zero) and 30 to be used as an exponent of 2. For example, a value of 10 sets chunk size to 1 KB (210 = 1024); a | |
1407 | value of 16 equals the default for disk caches (216 = 64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk | |
1408 | size to the default. Values less than 10 (1 KB) are not recommended. The following example sets chunk size to 16 KB | |
1409 | (214):</para> | |
1410 | ||
1411 | <programlisting> | |
1412 | <emphasis role="bold">/usr/vice/etc/afsd -chunksize 14</emphasis> | |
1413 | </programlisting> | |
1414 | ||
1415 | <para>For a disk cache, the default number of dcache entries duplicated in memory is one-half the number of chunks specified | |
1416 | with the <emphasis role="bold">-files</emphasis> argument, to a maximum of 2,000 entries. You can use the <emphasis | |
1417 | role="bold">-dcache</emphasis> argument to change the default, even exceeding 2,000 if you wish. Duplicating more than half | |
1418 | the dcache entries in memory is not usually necessary, but sometimes improves performance slightly, because access to memory | |
1419 | is faster than access to disk. The following example sets the number to 750:</para> | |
1420 | ||
1421 | <programlisting> | |
1422 | <emphasis role="bold">/usr/vice/etc/afsd -dcache 750</emphasis> | |
1423 | </programlisting> | |
1424 | ||
1425 | <para>When configuring a disk cache, you can combine the <emphasis role="bold">afsd</emphasis> command's arguments in any way. | |
1426 | The main reason for this flexibility is that the setting you specify for disk cache size (in the <emphasis | |
1427 | role="bold">cacheinfo</emphasis> file or with the <emphasis role="bold">-blocks</emphasis> argument) is an absolute maximum | |
1428 | limit. You cannot override it by specifying higher values for the <emphasis role="bold">-files</emphasis> or <emphasis | |
1429 | role="bold">-chunksize</emphasis> arguments, alone or in combination. A related reason is that the Cache Manager does not have | |
1430 | to reserve a set amount of memory on disk. <emphasis role="bold">V</emphasis>n files (the chunks in a disk cache) are | |
1431 | initially zero-length, but can expand up to the specified chunk size and shrink again, as needed. If you set the number of | |
1432 | <emphasis role="bold">V</emphasis>n files to such a large value that expanding all of them to the full allowable size exceeds | |
1433 | the total cache size, they simply never grow to full size.</para> | |
1434 | </sect2> | |
1435 | ||
1436 | <sect2 id="HDRWQ405"> | |
1437 | <title>Controlling Memory Cache Configuration</title> | |
1438 | ||
1439 | <para>Configuring a memory cache differs from configuring a disk cache in that not all combinations of the <emphasis | |
1440 | role="bold">afsd</emphasis> command's arguments are allowed. This limitation results from the greater interaction between the | |
1441 | configuration parameters in a memory cache than a disk cache. If all combinations are allowed, it is possible to set the | |
1442 | parameters in an inconsistent way. A list of the acceptable and unacceptable combinations follows a discussion of default | |
1443 | values.</para> | |
1444 | ||
1445 | <para>The default chunk size for a memory cache is 8 KB. In general, the only reason to change it is to adjust to | |
1446 | exceptionally slow or fast networks; see <link linkend="HDRWQ403">Setting Cache Configuration Parameters</link>.</para> | |
1447 | ||
1448 | <para>There is no predefined default for number of chunks in a memory cache. The Cache Manager instead calculates the correct | |
1449 | number by dividing the total cache size by the chunk size. Recall that for a memory cache, all dcache entries must be in | |
1450 | memory. This implies that the number of chunks equals the number of dcache entries in memory, and that there is no default for | |
1451 | number of dcache entries (like the number of chunks, it is calculated by dividing the total size by the chunk size).</para> | |
1452 | ||
1453 | <para>The following are acceptable combinations of the <emphasis role="bold">afsd</emphasis> command's arguments when | |
1454 | configuring a memory cache: <itemizedlist> | |
1455 | <listitem> | |
1456 | <para><emphasis role="bold">-blocks</emphasis> alone, which overrides the cache size specified in the <emphasis | |
1457 | role="bold">/usr/vice/etc/cacheinfo</emphasis> file. The Cache Manager divides the value of this argument by the default | |
1458 | chunk size of eight KB to calculate the number of chunks and dcache entries. The following example sets cache size to | |
1459 | five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by 8): <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -blocks 5120</emphasis></programlisting></para> | |
1460 | </listitem> | |
1461 | ||
1462 | <listitem> | |
1463 | <para><emphasis role="bold">-chunksize</emphasis> alone, to override the default of eight KB. The chunk size must be a | |
1464 | power of two, so provide an integer between 0 (zero) and 30 to be used as an exponent of two. For example, a value of | |
1465 | ten sets chunk size to 1 KB (210 = 1024); a value of 13 equals the default for memory caches (213 = 8 KB). Specifying a | |
1466 | value of 0 (zero) or greater than 30 returns the chunk size to the default. Values less than ten (equivalent to 1 KB) | |
1467 | are not recommended. The following example sets the chunk size to four KB (212). Assuming a total cache size of four MB | |
1468 | (4,096 KB), the resulting number of chunks is 1024. <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -chunksize 12</emphasis></programlisting></para> | |
1469 | </listitem> | |
1470 | ||
1471 | <listitem> | |
1472 | <para><emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-chunksize</emphasis> together override the | |
1473 | defaults for cache size and chunk size. The Cache Manager divides the first by the second to calculate the number of | |
1474 | chunks and dcache entries. For example, the following example sets the cache size to six MB (6,144 KB) and chunksize to | |
1475 | four KB (212), resulting in 1,536 chunks: <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12</emphasis></programlisting></para> | |
1476 | </listitem> | |
1477 | </itemizedlist></para> | |
1478 | ||
1479 | <para>The following arguments or combinations explicitly set the number of chunks and dcache entries. It is best not to use | |
1480 | them, because they set the cache size indirectly, forcing you to perform a hand calculation to determine the size of the | |
1481 | cache. Instead, set the <emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-chunksize</emphasis> arguments | |
1482 | alone or in combination; in those cases, the Cache Manager determines the number of chunks and dcache entries itself. Because | |
1483 | the following combinations are not recommended, no examples are included. <itemizedlist> | |
1484 | <listitem> | |
1485 | <para>The <emphasis role="bold">-dcache</emphasis> argument alone explicitly sets the number of chunks and dcache | |
1486 | entries. The Cache Manager multiples this value times the default chunk size of 8 KB to derive the total cache size | |
1487 | (overriding the value in the <emphasis role="bold">cacheinfo</emphasis> file).</para> | |
1488 | </listitem> | |
1489 | ||
1490 | <listitem> | |
1491 | <para>The combination of <emphasis role="bold">-dcache</emphasis> and <emphasis role="bold">-chunksize</emphasis> sets | |
1492 | the chunk number and size. The Cache Manager sets the specified values and multiplies them together to obtain total | |
1493 | cache size (overriding the value in the <emphasis role="bold">cacheinfo</emphasis> file).</para> | |
1494 | </listitem> | |
1495 | </itemizedlist></para> | |
1496 | ||
1497 | <para>Do not use the following arguments for a memory cache: <itemizedlist> | |
1498 | <listitem> | |
1499 | <para><emphasis role="bold">-files</emphasis> alone. This argument controls the number of <emphasis | |
1500 | role="bold">V</emphasis>n files for a disk cache, but is ignored for a memory cache.</para> | |
1501 | </listitem> | |
1502 | ||
1503 | <listitem> | |
1504 | <para><emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-dcache</emphasis>. An error message results, | |
1505 | because it is possible to provide values such that dividing the first (total size) by the second (number of chunks) | |
1506 | results in a chunk size that is not a power of two.</para> | |
1507 | </listitem> | |
1508 | </itemizedlist></para> | |
1509 | </sect2> | |
1510 | ||
1511 | ||
1512 | <sect2 id="tuning-cache-configuration"> | |
1513 | <title>Tuning Cache Configuration</title> | |
1514 | ||
1515 | <indexterm> | |
1516 | <primary>cache</primary> | |
1517 | <secondary>tuning</secondary> | |
1518 | </indexterm> | |
1519 | ||
1520 | <indexterm> | |
1521 | <primary>performance</primary> | |
1522 | <secondary>cache</secondary> | |
1523 | </indexterm> | |
1524 | ||
1525 | <para> | |
1526 | Tuning the parameters of the OpenAFS cache for optimal performance | |
1527 | is highly dependent on the behavior of applications and users on a | |
1528 | client machine. The default options may perform poorly under | |
1529 | certain conditions. | |
1530 | </para> | |
1531 | ||
1532 | <para> | |
1533 | The <emphasis role="bold">xstat_cm_test</emphasis> command is | |
1534 | useful for measuring how effectively the cache is operating. The | |
1535 | following procedure may be used to aide in tuning the parameters | |
1536 | for the data cache (dcache) and the stats cache (vcache): | |
1537 | <orderedlist> | |
1538 | <listitem> | |
1539 | <para> | |
1540 | Run the following command and replace "hostname" with the hostname of the machine to be measured: | |
1541 | <programlisting> | |
1542 | <emphasis role="bold">xstat_cm_test hostname 2 -onceonly</emphasis> | |
1543 | </programlisting> | |
1544 | </para> | |
1545 | <para> | |
1546 | Take note of the following fields: dcacheHits, dcacheMisses, | |
1547 | vcacheHits, and vcacheMisses. Saving the above command | |
1548 | output to a file or filtering it using grep is advised. | |
1549 | </para> | |
1550 | </listitem> | |
1551 | <listitem> | |
1552 | <para> | |
1553 | Using the noted fields, compute the miss ratios for the | |
1554 | dcache and vcache using the following formulas: | |
1555 | <programlisting> | |
1556 | <emphasis role="bold"> | |
1557 | dcache miss ratio = dcacheMisses / ( dcacheMisses + dcacheHits ) | |
1558 | </emphasis> | |
1559 | </programlisting> | |
1560 | <programlisting> | |
1561 | <emphasis role="bold"> | |
1562 | vcache miss ratio = vcacheMisses / ( vcacheMisses + vcacheHits ) | |
1563 | </emphasis> | |
1564 | </programlisting> | |
1565 | As a guideline, a miss ratio of 0.05 (5 percent) or less is | |
1566 | acceptable and a miss ratio of 0.01 (1 percent) or less is | |
1567 | recommended. | |
1568 | </para> | |
1569 | </listitem> | |
1570 | <listitem> | |
1571 | <para> | |
1572 | If your dcache miss ratio is too large, then cache | |
1573 | performance is likely to improve if the data cache is made | |
1574 | larger. If the vcache miss ratio is too large, then increase | |
1575 | the size of the stat cache using | |
1576 | the <emphasis role="bold">-stat</emphasis> parameter | |
1577 | to <emphasis role="bold">afsd</emphasis> for a Unix-based | |
1578 | client or using the Control Panel or registry interfaces on | |
1579 | Microsoft Windows-based clients. The default size of the | |
1580 | stat cache is 10,000 entries on windows platforms and 300 | |
1581 | entries on Unix platforms. There may be a significant | |
1582 | performance penalty when the vcache size is much smaller | |
1583 | than the working set of commonly accessed files. On the | |
1584 | fileserver, the number of callbacks should be more than the | |
1585 | size of the vcache of any client that connects to the | |
1586 | server. If the cache is too small or there aren't enough | |
1587 | callbacks (<emphasis role="bold">-cb</emphasis>) on the | |
1588 | fileserver, then the cached entries will be discarded | |
1589 | prematurely, causing thrashing. | |
1590 | <tip> | |
1591 | <para> | |
1592 | As an example of how the wrong vcache size can degrade | |
1593 | performance, one OpenAFS site had performance issues | |
1594 | with the Apache and mod_php software on a Unix web | |
1595 | server serving web pages directly out of AFS. During | |
1596 | peak times, the load on the server would spike with an | |
1597 | excess of Apache processes. After profiling, it was | |
1598 | found that Apache and PHP made lots | |
1599 | of <emphasis role="bold">stat()</emphasis> library calls | |
1600 | and that the default vcache size of 300 was too | |
1601 | small. After some experimentation, a vcache size of | |
1602 | 50,000 was found to improve performance. This size makes | |
1603 | sense in light of that fact that the total number of | |
1604 | files in the website exceeded 350,000, including 50,000 | |
1605 | PHP files. The number of callbacks configured on the | |
1606 | fileserver was 1,500,000, so the vcache size was not too | |
1607 | large. | |
1608 | </para> | |
1609 | </tip> | |
1610 | </para> | |
1611 | </listitem> | |
1612 | <listitem> | |
1613 | <para> | |
1614 | After changing your configuration appropriately and | |
1615 | restarting the AFS client service, wait until enough data | |
1616 | has been collected before changing the configuration | |
1617 | further. The sum of the hits and misses should be at least | |
1618 | five times the value of the configured parameter before | |
1619 | making further adjustments. Repeat this process until the | |
1620 | desired miss ratio is achieved. Take note that the numbers | |
1621 | from the <emphasis role="bold">xstat_cm_test</emphasis> | |
1622 | command only reset when the client is restarted. If multiple | |
1623 | samples are taken, then subtract the previous measurement | |
1624 | from the current measurement to accurately measure the | |
1625 | activity that happened between the samples. | |
1626 | </para> | |
1627 | </listitem> | |
1628 | </orderedlist> | |
1629 | </para> | |
1630 | </sect2> | |
1631 | </sect1> | |
1632 | ||
1633 | ||
1634 | <sect1 id="HDRWQ406"> | |
1635 | <title>Maintaining Knowledge of Database Server Machines</title> | |
1636 | ||
1637 | <indexterm> | |
1638 | <primary>CellServDB file (client)</primary> | |
1639 | ||
1640 | <secondary>about</secondary> | |
1641 | </indexterm> | |
1642 | ||
1643 | <indexterm> | |
1644 | <primary>files</primary> | |
1645 | ||
1646 | <secondary>CellServDB file (client)</secondary> | |
1647 | </indexterm> | |
1648 | ||
1649 | <indexterm> | |
1650 | <primary>database server machine</primary> | |
1651 | ||
1652 | <secondary>client knowledge of</secondary> | |
1653 | </indexterm> | |
1654 | ||
1655 | <indexterm> | |
1656 | <primary>client machine</primary> | |
1657 | ||
1658 | <secondary>database server processes, contacting</secondary> | |
1659 | </indexterm> | |
1660 | ||
1661 | <indexterm> | |
1662 | <primary>Cache Manager</primary> | |
1663 | ||
1664 | <secondary>database server processes, contacting</secondary> | |
1665 | </indexterm> | |
1666 | ||
1667 | <indexterm> | |
1668 | <primary>Cache Manager</primary> | |
1669 | ||
1670 | <secondary>CellServDB file (client), using</secondary> | |
1671 | </indexterm> | |
1672 | ||
1673 | <indexterm> | |
1674 | <primary>command interpreters</primary> | |
1675 | ||
1676 | <secondary>CellServDB file (client), using</secondary> | |
1677 | </indexterm> | |
1678 | ||
1679 | <indexterm> | |
1680 | <primary>CellServDB file (client)</primary> | |
1681 | ||
1682 | <secondary>copied into kernel memory</secondary> | |
1683 | </indexterm> | |
1684 | ||
1685 | <indexterm> | |
1686 | <primary>kernel memory (client)</primary> | |
1687 | ||
1688 | <secondary>CellServDB file, reading into</secondary> | |
1689 | </indexterm> | |
1690 | ||
1691 | <para>For the users of an AFS client machine to access a cell's AFS filespace and other services, the Cache Manager and other | |
1692 | client-side agents must have an accurate list of the cell's database server machines. The affected functions include the | |
1693 | following: <itemizedlist> | |
1694 | <listitem> | |
1695 | <para>Accessing files. The Cache Manager contacts the Volume Location (VL) Server to learn which file server machine | |
1696 | houses the volume containing a requested file or directory. If the Cache Manager cannot contact a cell's VL Servers, it | |
1697 | cannot fetch files.</para> | |
1698 | </listitem> | |
1699 | ||
1700 | <listitem> | |
1701 | <para>Authenticating. The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities contact the | |
1702 | Authentication Server to obtain tokens, which the AFS server processes accept as proof that the user is | |
1703 | authenticated.</para> | |
1704 | </listitem> | |
1705 | ||
1706 | <listitem> | |
1707 | <para>Creating protection groups. The <emphasis role="bold">pts</emphasis> command interpreter contacts the Protection | |
1708 | Server when users create protection groups or request information from the Protection Database.</para> | |
1709 | </listitem> | |
1710 | ||
1711 | <listitem> | |
1712 | <para>Editing access control lists (ACLs). The <emphasis role="bold">fs</emphasis> command interpreter contacts the File | |
1713 | Server that maintains the read/write volume containing a file or directory; the location information comes from the VL | |
1714 | Server.</para> | |
1715 | </listitem> | |
1716 | </itemizedlist></para> | |
1717 | ||
1718 | <para>To enable a machine's users to access a cell, you must list the names and IP addresses of its database server machines in | |
1719 | the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the machine's local disk. In addition to the machine's | |
1720 | home cell, you can list any foreign cells that you want to enable users to access. (To enable access to a cell's filespace, you | |
1721 | must also mount its <emphasis role="bold">root.cell</emphasis> volume in the local AFS filespace; the conventional location is | |
1722 | just under the AFS root directory, <emphasis role="bold">/afs</emphasis>. For instructions, see the <emphasis>OpenAFS Quick | |
1723 | Beginnings</emphasis>.)</para> | |
1724 | ||
1725 | <sect2 id="Header_451"> | |
1726 | <title>How Clients Use the List of Database Server Machines</title> | |
1727 | ||
1728 | <para>As the <emphasis role="bold">afsd</emphasis> program runs and initializes the Cache Manager, it reads the contents of | |
1729 | the <emphasis role="bold">CellServDB</emphasis> file into kernel memory. The Cache Manager does not consult the file again | |
1730 | until the machine next reboots. In contrast, the command interpreters for the AFS command suites (such as <emphasis | |
1731 | role="bold">fs</emphasis> and <emphasis role="bold">pts</emphasis>) read the <emphasis role="bold">CellServDB</emphasis> file | |
1732 | each time they need to contact a database server process.</para> | |
1733 | ||
1734 | <para>When a cell's list of database server machines changes, you must change both the <emphasis | |
1735 | role="bold">CellServDB</emphasis> file and the list in kernel memory to preserve consistent client performance; some commands | |
1736 | probably fail if the two lists of machines disagree. One possible method for updating both the <emphasis | |
1737 | role="bold">CellServDB</emphasis> file and kernel memory is to edit the file and reboot the machine. To avoid needing to | |
1738 | reboot, you can instead perform both of the following steps: <orderedlist> | |
1739 | <listitem> | |
1740 | <para>Issue the <emphasis role="bold">fs newcell</emphasis> command to alter the list in kernel memory directly, making | |
1741 | the changes available to the Cache Manager.</para> | |
1742 | </listitem> | |
1743 | ||
1744 | <listitem> | |
1745 | <para>Edit the <emphasis role="bold">CellServDB</emphasis> file to make the changes available to command interpreters. | |
1746 | For a description of the file's format, see <link linkend="HDRWQ407">The Format of the CellServDB file</link>.</para> | |
1747 | </listitem> | |
1748 | </orderedlist></para> | |
1749 | ||
1750 | <para>The consequences of missing or incorrect information in the <emphasis role="bold">CellServDB</emphasis> file or kernel | |
1751 | memory are as follows: <itemizedlist> | |
1752 | <listitem> | |
1753 | <para>If there is no entry for a cell, the machine's users cannot access the cell.</para> | |
1754 | </listitem> | |
1755 | ||
1756 | <listitem> | |
1757 | <para>If a cell's entry does not include a database server machine, then the Cache Manager and command interpreters | |
1758 | never attempt to contact the machine. The omission does not prevent access to the cell--as long as the information about | |
1759 | the other database server machines is correct and the server processes, machines, and network are functioning | |
1760 | correctly--but it can put an undue burden on the machines that are listed. If all of the listed machines become | |
1761 | inaccessible to clients, then the cell becomes inaccessible even if the omitted database server machine is functioning | |
1762 | correctly.</para> | |
1763 | </listitem> | |
1764 | ||
1765 | <listitem> | |
1766 | <para>If a machine's name or address is incorrect, or the machine is not actually running the database server processes, | |
1767 | then requests from clients time out. Users can experience lengthy delays because they have to wait the full timeout | |
1768 | period before the Cache Manager or command interpreter contacts another database server machine.</para> | |
1769 | </listitem> | |
1770 | </itemizedlist></para> | |
1771 | </sect2> | |
1772 | ||
1773 | <sect2 id="HDRWQ407"> | |
1774 | <title>The Format of the CellServDB file</title> | |
1775 | ||
1776 | <indexterm> | |
1777 | <primary>CellServDB file (client)</primary> | |
1778 | ||
1779 | <secondary>correct format</secondary> | |
1780 | </indexterm> | |
1781 | ||
1782 | <indexterm> | |
1783 | <primary>format of CellServDB file (client)</primary> | |
1784 | </indexterm> | |
1785 | ||
1786 | <para>When editing the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, you must use the correct format for | |
1787 | cell and machine entries. Each cell has a separate entry. The first line has the following format:</para> | |
1788 | ||
1789 | <programlisting> | |
1790 | >cell_name #organization | |
1791 | </programlisting> | |
1792 | ||
1793 | <para>where cell_name is the cell's complete Internet domain name (for example, <emphasis role="bold">example.com</emphasis>) and | |
1794 | organization is an optional field that follows any number of spaces and the number sign (<computeroutput>#</computeroutput>) | |
1795 | and can name the organization to which the cell corresponds (for example, the Example Corporation). After the first line comes a | |
1796 | separate line for each database server machine. Each line has the following format:</para> | |
1797 | ||
1798 | <programlisting> | |
1799 | IP_address #machine_name | |
1800 | </programlisting> | |
1801 | ||
1802 | <para>where IP_address is the machine's IP address in dotted decimal format (for example, 192.12.105.3). Following any number | |
1803 | of spaces and the number sign (<computeroutput>#</computeroutput>) is machine_name, the machine's fully-qualified hostname | |
1804 | (for example, <emphasis role="bold">db1.example.com</emphasis>). In this case, the number sign does not indicate a comment: | |
1805 | machine_name is a required field.</para> | |
1806 | ||
1807 | <para>The order in which the cells appear is not important, but it is convenient to put the client machine's home cell first. | |
1808 | Do not include any blank lines in the file, not even after the last entry.</para> | |
1809 | ||
1810 | <para>The following example shows entries for two cells, each of which has three database server machines:</para> | |
1811 | ||
1812 | <programlisting> | |
1813 | >example.com #Example Corporation (home cell) | |
1814 | 192.12.105.3 #db1.example.com | |
1815 | 192.12.105.4 #db2.example.com | |
1816 | 192.12.105.55 #db3.example.com | |
1817 | >example.org #Example Organization cell | |
1818 | 138.255.68.93 #serverA.example.org | |
1819 | 138.255.68.72 #serverB.example.org | |
1820 | 138.255.33.154 #serverC.example.org | |
1821 | </programlisting> | |
1822 | </sect2> | |
1823 | ||
1824 | <sect2 id="HDRWQ408"> | |
1825 | <title>Maintaining the Client CellServDB File</title> | |
1826 | ||
1827 | <indexterm> | |
1828 | <primary>maintaining</primary> | |
1829 | ||
1830 | <secondary>CellServDB file (client)</secondary> | |
1831 | </indexterm> | |
1832 | ||
1833 | <indexterm> | |
1834 | <primary>CellServDB file (client)</primary> | |
1835 | ||
1836 | <secondary>maintaining</secondary> | |
1837 | </indexterm> | |
1838 | ||
1839 | <para>Because a correct entry in the <emphasis role="bold">CellServDB</emphasis> file is vital for consistent client | |
1840 | performance, you must also update the file on each client machine whenever a cell's list of database server machines changes | |
1841 | (for instance, when you follow the instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> to add or remove a | |
1842 | database server machine).</para> | |
1843 | ||
1844 | <para>Creating a symbolic or hard link from <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> to a central source file | |
1845 | in AFS is not a viable option. The <emphasis role="bold">afsd</emphasis> program reads the file into kernel memory before the | |
1846 | Cache Manager is completely initialized and able to access AFS.</para> | |
1847 | ||
1848 | <para>Because every client machine has its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in theory | |
1849 | make the set of accessible cells differ on various machines. In most cases, however, it is best to maintain consistency | |
1850 | between the files on all client machines in the cell: differences between machines are particularly confusing if users | |
1851 | commonly use a variety of machines rather than just one.</para> | |
1852 | ||
1853 | <para>The AFS Product Support group maintains a central <emphasis role="bold">CellServDB</emphasis> file that includes all | |
1854 | cells that have agreed to make their database server machines access to other AFS cells. It is advisable to check this file | |
1855 | periodically for updated information. See <link linkend="HDRWQ38">Making Your Cell Visible to Others</link>. <indexterm> | |
1856 | <primary>CellServDB file (client)</primary> | |
1857 | ||
1858 | <secondary>global source from AFS Support</secondary> | |
1859 | </indexterm></para> | |
1860 | ||
1861 | <para>An entry in the local <emphasis role="bold">CellServDB</emphasis> is one of the two requirements for accessing a cell. | |
1862 | The other is that the cell's <emphasis role="bold">root.cell</emphasis> volume is mounted in the local filespace, by | |
1863 | convention as a subdirectory of the <emphasis role="bold">/afs</emphasis> directory. For instructions, see <link | |
1864 | linkend="HDRWQ213">To create a cellular mount point</link>.</para> | |
1865 | ||
1866 | <note> | |
1867 | <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine is not the same as the | |
1868 | <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on the local disk of a file server machine. The server version | |
1869 | lists only the database server machines in the server machine's home cell, because server processes never need to contact | |
1870 | foreign cells. It is important to update both types of <emphasis role="bold">CellServDB</emphasis> file on all machines in | |
1871 | the cell whenever there is a change to your cell's database server machines. For more information about maintaining the | |
1872 | server version of the <emphasis role="bold">CellServDB</emphasis> file, see <link linkend="HDRWQ118">Maintaining the Server | |
1873 | CellServDB File</link>.</para> | |
1874 | </note> | |
1875 | ||
1876 | <indexterm> | |
1877 | <primary>CellServDB file (client)</primary> | |
1878 | ||
1879 | <secondary>displaying</secondary> | |
1880 | </indexterm> | |
1881 | ||
1882 | <indexterm> | |
1883 | <primary>displaying</primary> | |
1884 | ||
1885 | <secondary>CellServDB file (client)</secondary> | |
1886 | </indexterm> | |
1887 | ||
1888 | <indexterm> | |
1889 | <primary>database server machine</primary> | |
1890 | ||
1891 | <secondary>CellServDB file (client), displaying</secondary> | |
1892 | </indexterm> | |
1893 | ||
1894 | <indexterm> | |
1895 | <primary>client machine</primary> | |
1896 | ||
1897 | <secondary>CellServDB file, displaying</secondary> | |
1898 | </indexterm> | |
1899 | ||
1900 | <indexterm> | |
1901 | <primary>client machine</primary> | |
1902 | ||
1903 | <secondary>database server machines, displaying knowledge of</secondary> | |
1904 | </indexterm> | |
1905 | </sect2> | |
1906 | ||
1907 | <sect2 id="Header_454"> | |
1908 | <title>To display the /usr/vice/etc/CellServDB file</title> | |
1909 | ||
1910 | <orderedlist> | |
1911 | <listitem> | |
1912 | <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis | |
1913 | role="bold">/usr/vice/etc/CellServDB</emphasis> file. By default, the mode bits on the file permit anyone to read it. | |
1914 | <programlisting> | |
1915 | % <emphasis role="bold">cat /usr/vice/etc/CellServDB</emphasis> | |
1916 | </programlisting></para> | |
1917 | </listitem> | |
1918 | </orderedlist> | |
1919 | ||
1920 | <indexterm> | |
1921 | <primary>fs commands</primary> | |
1922 | ||
1923 | <secondary>listcells</secondary> | |
1924 | </indexterm> | |
1925 | ||
1926 | <indexterm> | |
1927 | <primary>commands</primary> | |
1928 | ||
1929 | <secondary>fs listcells</secondary> | |
1930 | </indexterm> | |
1931 | </sect2> | |
1932 | ||
1933 | <sect2 id="Header_455"> | |
1934 | <title>To display the list of database server machines in kernel memory</title> | |
1935 | ||
1936 | <orderedlist> | |
1937 | <listitem> | |
1938 | <para>Issue the <emphasis role="bold">fs listcells</emphasis> command. <programlisting> | |
1939 | % <emphasis role="bold">fs listcells [&]</emphasis> | |
1940 | </programlisting></para> | |
1941 | ||
1942 | <para>where <emphasis role="bold">listc</emphasis> is the shortest acceptable abbreviation of <emphasis | |
1943 | role="bold">listcells</emphasis>.</para> | |
1944 | ||
1945 | <para>To have your shell prompt return immediately, include the ampersand (<emphasis role="bold">&</emphasis>), which | |
1946 | makes the command run in the background. It can take a while to generate the complete output because the kernel stores | |
1947 | database server machines' IP addresses only, and the <emphasis role="bold">fs</emphasis> command interpreter has the | |
1948 | cell's name resolution service (such as the Domain Name Service or a local host table) translate them into hostnames. You | |
1949 | can halt the command at any time by issuing an interrupt signal such as <emphasis role="bold">Ctrl-c</emphasis>.</para> | |
1950 | ||
1951 | <para>The output includes a single line for each cell, in the following format:</para> | |
1952 | ||
1953 | <programlisting> | |
1954 | Cell cell_name on hosts list_of_hostnames. | |
1955 | </programlisting> | |
1956 | ||
1957 | <para>The name service sometimes returns hostnames in uppercase letters, and if it cannot resolve a name at all, it | |
1958 | returns its IP address. The following example illustrates all three possibilities:</para> | |
1959 | ||
1960 | <programlisting> | |
1961 | % <emphasis role="bold">fs listcells</emphasis> | |
1962 | . | |
1963 | . | |
1964 | Cell example.com on hosts db1.example.com db2.example.com db3.example.com | |
1965 | Cell example.org on hosts SERVERA.EXAMPLE.ORG SERVERB.EXAMPLE.ORG | |
1966 | SERVERC.EXAMPLE.ORG | |
1967 | Cell example.net on hosts 191.255.64.111 191.255.64.112 | |
1968 | . | |
1969 | . | |
1970 | </programlisting> | |
1971 | </listitem> | |
1972 | </orderedlist> | |
1973 | ||
1974 | <indexterm> | |
1975 | <primary>adding</primary> | |
1976 | ||
1977 | <secondary>database server machine</secondary> | |
1978 | ||
1979 | <tertiary>to client CellServDB file and kernel memory</tertiary> | |
1980 | </indexterm> | |
1981 | ||
1982 | <indexterm> | |
1983 | <primary>removing</primary> | |
1984 | ||
1985 | <secondary>database server machine</secondary> | |
1986 | ||
1987 | <tertiary>from client CellServDB file and kernel memory</tertiary> | |
1988 | </indexterm> | |
1989 | ||
1990 | <indexterm> | |
1991 | <primary>database server machine</primary> | |
1992 | ||
1993 | <secondary>adding</secondary> | |
1994 | ||
1995 | <tertiary>to client CellServDB file and kernel memory</tertiary> | |
1996 | </indexterm> | |
1997 | ||
1998 | <indexterm> | |
1999 | <primary>database server machine</primary> | |
2000 | ||
2001 | <secondary>removing</secondary> | |
2002 | ||
2003 | <tertiary>from client CellServDB file and kernel memory</tertiary> | |
2004 | </indexterm> | |
2005 | ||
2006 | <indexterm> | |
2007 | <primary>client machine</primary> | |
2008 | ||
2009 | <secondary>changing list of cells in kernel memory</secondary> | |
2010 | </indexterm> | |
2011 | ||
2012 | <indexterm> | |
2013 | <primary>cell</primary> | |
2014 | ||
2015 | <secondary>changing list in client kernel memory</secondary> | |
2016 | </indexterm> | |
2017 | ||
2018 | <indexterm> | |
2019 | <primary>client machine</primary> | |
2020 | ||
2021 | <secondary>changing CellServDB file</secondary> | |
2022 | </indexterm> | |
2023 | ||
2024 | <indexterm> | |
2025 | <primary>CellServDB file (client)</primary> | |
2026 | ||
2027 | <secondary>changing</secondary> | |
2028 | </indexterm> | |
2029 | ||
2030 | <indexterm> | |
2031 | <primary>CellServDB file (client)</primary> | |
2032 | ||
2033 | <secondary>updating</secondary> | |
2034 | </indexterm> | |
2035 | ||
2036 | <indexterm> | |
2037 | <primary>updating</primary> | |
2038 | ||
2039 | <secondary>CellServDB file (client)</secondary> | |
2040 | </indexterm> | |
2041 | </sect2> | |
2042 | ||
2043 | <sect2 id="Header_456"> | |
2044 | <title>To change the list of a cell's database server machines in kernel memory</title> | |
2045 | ||
2046 | <orderedlist> | |
2047 | <listitem> | |
2048 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
2049 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
2050 | % <emphasis role="bold">su root</emphasis> | |
2051 | Password: <<replaceable>root_password</replaceable>> | |
2052 | </programlisting></para> | |
2053 | </listitem> | |
2054 | ||
2055 | <listitem> | |
2056 | <para>If you a use a central copy of the <emphasis role="bold">CellServDB</emphasis> file as a source for client machines, | |
2057 | verify that its directory's ACL grants you the <emphasis role="bold">l</emphasis> (<emphasis | |
2058 | role="bold">lookup</emphasis>), <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>), and <emphasis | |
2059 | role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) permissions. The conventional directory is <emphasis | |
2060 | role="bold">/afs/</emphasis>cell_name<emphasis role="bold">/common/etc</emphasis>. If necessary, issue the <emphasis | |
2061 | role="bold">fs listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. | |
2062 | <programlisting> | |
2063 | # <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
2064 | </programlisting> <indexterm> | |
2065 | <primary>fs commands</primary> | |
2066 | ||
2067 | <secondary>newcell</secondary> | |
2068 | </indexterm> <indexterm> | |
2069 | <primary>commands</primary> | |
2070 | ||
2071 | <secondary>fs newcell</secondary> | |
2072 | </indexterm></para> | |
2073 | </listitem> | |
2074 | ||
2075 | <listitem> | |
2076 | <para>Issue the <emphasis role="bold">fs newcell</emphasis> command to add or change a cell's | |
2077 | entry in kernel memory. Repeat the command for each cell.</para> | |
2078 | ||
2079 | <note> | |
2080 | <para>You cannot use this command to remove a cell's entry completely from kernel memory. In the rare cases when you | |
2081 | urgently need to prevent access to a specific cell, you must edit the <emphasis role="bold">CellServDB</emphasis> file | |
2082 | and reboot the machine.</para> | |
2083 | </note> | |
2084 | ||
2085 | <programlisting> | |
2086 | # <emphasis role="bold">fs newcell</emphasis> <<replaceable>cell name</replaceable>> <<replaceable>primary servers</replaceable>>+ \ | |
2087 | [<emphasis role="bold">-linkedcell</emphasis> <<replaceable>linked cell name</replaceable>>] | |
2088 | </programlisting> | |
2089 | ||
2090 | <para>where <variablelist> | |
2091 | <varlistentry> | |
2092 | <term><emphasis role="bold">n</emphasis></term> | |
2093 | ||
2094 | <listitem> | |
2095 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">newcell</emphasis>.</para> | |
2096 | </listitem> | |
2097 | </varlistentry> | |
2098 | ||
2099 | <varlistentry> | |
2100 | <term><emphasis role="bold">cell name</emphasis></term> | |
2101 | ||
2102 | <listitem> | |
2103 | <para>Specifies the complete Internet domain name of the cell for which to record a new list of database server | |
2104 | machines.</para> | |
2105 | </listitem> | |
2106 | </varlistentry> | |
2107 | ||
2108 | <varlistentry> | |
2109 | <term><emphasis role="bold">primary servers</emphasis></term> | |
2110 | ||
2111 | <listitem> | |
2112 | <para>Specifies the fully-qualified hostname or IP address in dotted-decimal format for each database server | |
2113 | machine in the cell. The list you provide completely replaces the existing list.</para> | |
2114 | </listitem> | |
2115 | </varlistentry> | |
2116 | ||
2117 | <varlistentry> | |
2118 | <term><emphasis role="bold">-linkedcell</emphasis></term> | |
2119 | ||
2120 | <listitem> | |
2121 | <para>Specifies the complete Internet domain name of the AFS cell to link to a DCE cell for the purposes of DFS | |
2122 | fileset location. You can use this argument if the machine's AFS users access DFS via the AFS/DFS Migration | |
2123 | Toolkit Protocol Translator. For instructions, see the <emphasis>OpenAFS/DFS Migration Toolkit Administration | |
2124 | Guide and Reference</emphasis>.</para> | |
2125 | </listitem> | |
2126 | </varlistentry> | |
2127 | </variablelist></para> | |
2128 | </listitem> | |
2129 | ||
2130 | <listitem> | |
2131 | <para>Add or edit the cell's entry in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, using one | |
2132 | of the following three methods. In each case, be sure to obey the formatting requirements described in <link | |
2133 | linkend="HDRWQ407">The Format of the CellServDB file</link>. <itemizedlist> | |
2134 | <listitem> | |
2135 | <para>If you maintain a central source <emphasis role="bold">CellServDB</emphasis> file, | |
2136 | first use a text editor to alter the central copy of the file. Then use a | |
2137 | copying command such as the <emphasis role="bold">cp</emphasis> command to copy it to the local <emphasis | |
2138 | role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para> | |
2139 | </listitem> | |
2140 | ||
2141 | <listitem> | |
2142 | <para>If you do not use a central source <emphasis role="bold">CellServDB</emphasis> file, edit the local machine's | |
2143 | <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file directly.</para> | |
2144 | </listitem> | |
2145 | </itemizedlist></para> | |
2146 | </listitem> | |
2147 | </orderedlist> | |
2148 | </sect2> | |
2149 | </sect1> | |
2150 | ||
2151 | <sect1 id="HDRWQ409"> | |
2152 | <title>Determining if a Client Can Run Setuid Programs</title> | |
2153 | ||
2154 | <indexterm> | |
2155 | <primary>client machine</primary> | |
2156 | ||
2157 | <secondary>controlling running of setuid programs</secondary> | |
2158 | </indexterm> | |
2159 | ||
2160 | <indexterm> | |
2161 | <primary>Cache Manager</primary> | |
2162 | ||
2163 | <secondary>setuid programs</secondary> | |
2164 | </indexterm> | |
2165 | ||
2166 | <indexterm> | |
2167 | <primary>setuid programs</primary> | |
2168 | </indexterm> | |
2169 | ||
2170 | <para>A <emphasis>setuid program</emphasis> is one whose binary file | |
2171 | has the UNIX setuid mode bit turned on. While a setuid program runs, | |
2172 | the user who initialized it assumes the local identity (UNIX UID) of | |
2173 | the binary file's owner, and so is granted the permissions in the | |
2174 | local file system that pertain to the owner. Most commonly, the | |
2175 | issuer's assumed identity (often referred to as <emphasis>effective | |
2176 | UID</emphasis>) is the local superuser <emphasis | |
2177 | role="bold">root</emphasis>.</para> | |
2178 | ||
2179 | <para>AFS does not recognize effective UID: if a setuid program | |
2180 | accesses AFS files and directories, it uses the current AFS identity | |
2181 | of the user who initialized the program, not of the program's | |
2182 | owner. Nevertheless, it can be useful to store setuid programs in AFS | |
2183 | for use on more than one client machine. AFS enables a client | |
2184 | machine's administrator to determine and change whether the local | |
2185 | Cache Manager allows setuid programs to run or not.</para> | |
2186 | ||
2187 | <para>By default, the Cache Manager ignores all setuid permissions in | |
2188 | AFS, but this can be changed by a client machine's administrator. Each | |
2189 | cell's setuid status is set independently of other cells. To change a | |
2190 | cell's setuid status with respect to the local machine, become the | |
2191 | local superuser <emphasis role="bold">root</emphasis> and issue the | |
2192 | <emphasis role="bold">fs setcell</emphasis> command. To determine a | |
2193 | cell's current setuid status, use the <emphasis role="bold">fs | |
2194 | getcellstatus</emphasis> command.</para> | |
2195 | ||
2196 | <warning> | |
2197 | <para>Enabling support for the UNIX setuid bit for AFS programs is | |
2198 | not secure with the current AFS protocol. Enabling this capability | |
2199 | is not recommended except in very restricted environments on trusted | |
2200 | networks.</para> | |
2201 | </warning> | |
2202 | ||
2203 | <para>When you issue the <emphasis role="bold">fs setcell</emphasis> | |
2204 | command, you directly alter a cell's setuid status as recorded in | |
2205 | kernel memory, so rebooting the machine is not necessary. However, | |
2206 | nondefault settings do not persist across reboots of the machine | |
2207 | unless you add the appropriate <emphasis role="bold">fs | |
2208 | setcell</emphasis> command to the machine's AFS initialization | |
2209 | file.</para> | |
2210 | ||
2211 | <para>Only members of the <emphasis | |
2212 | role="bold">system:administrators</emphasis> group can turn on the | |
2213 | setuid mode bit on an AFS file or directory. When the setuid mode bit | |
2214 | is turned on, the UNIX <emphasis role="bold">ls -l</emphasis> command | |
2215 | displays the third user mode bit as an <emphasis | |
2216 | role="bold">s</emphasis> instead of an <emphasis | |
2217 | role="bold">x</emphasis>, but for an AFS file or directory, the | |
2218 | <emphasis role="bold">s</emphasis> appears only if setuid permission | |
2219 | is enabled for the cell in which the file resides. | |
2220 | <indexterm> | |
2221 | <primary>fs commands</primary> | |
2222 | <secondary>getcellstatus</secondary> | |
2223 | </indexterm> | |
2224 | <indexterm> | |
2225 | <primary>commands</primary> | |
2226 | <secondary>fs getcellstatus</secondary> | |
2227 | </indexterm> | |
2228 | </para> | |
2229 | ||
2230 | <sect2 id="Header_458"> | |
2231 | <title>To determine a cell's setuid status</title> | |
2232 | ||
2233 | <orderedlist> | |
2234 | <listitem> | |
2235 | <para>Issue the <emphasis role="bold">fs getcellstatus</emphasis> command to check the setuid status of each desired cell. | |
2236 | <programlisting> | |
2237 | % <emphasis role="bold">fs getcellstatus</emphasis> <<replaceable>cell name</replaceable>> | |
2238 | </programlisting></para> | |
2239 | ||
2240 | <para>where <variablelist> | |
2241 | <varlistentry> | |
2242 | <term><emphasis role="bold">getce</emphasis></term> | |
2243 | ||
2244 | <listitem> | |
2245 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getcellstatus</emphasis>.</para> | |
2246 | </listitem> | |
2247 | </varlistentry> | |
2248 | ||
2249 | <varlistentry> | |
2250 | <term><emphasis role="bold">cell name</emphasis></term> | |
2251 | ||
2252 | <listitem> | |
2253 | <para>Names each cell for which to report setuid status. Provide the complete Internet domain name or a shortened | |
2254 | form that distinguishes it from the other cells listed in the local <emphasis | |
2255 | role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para> | |
2256 | </listitem> | |
2257 | </varlistentry> | |
2258 | </variablelist></para> | |
2259 | </listitem> | |
2260 | </orderedlist> | |
2261 | ||
2262 | <para>The output reports the setuid status of each cell: <itemizedlist> | |
2263 | <listitem> | |
2264 | <para>the string <computeroutput>no setuid allowed</computeroutput> indicates that the Cache Manager does not allow | |
2265 | programs from the cell to run with <computeroutput>setuid permission</computeroutput></para> | |
2266 | </listitem> | |
2267 | ||
2268 | <listitem> | |
2269 | <para>setuid allowed indicates that the Cache Manager allows programs from the cell to run with setuid permission</para> | |
2270 | </listitem> | |
2271 | </itemizedlist></para> | |
2272 | ||
2273 | <indexterm> | |
2274 | <primary>fs commands</primary> | |
2275 | ||
2276 | <secondary>setcell</secondary> | |
2277 | </indexterm> | |
2278 | ||
2279 | <indexterm> | |
2280 | <primary>commands</primary> | |
2281 | ||
2282 | <secondary>fs setcell</secondary> | |
2283 | </indexterm> | |
2284 | </sect2> | |
2285 | ||
2286 | <sect2 id="Header_459"> | |
2287 | <title>To change a cell's setuid status</title> | |
2288 | ||
2289 | <orderedlist> | |
2290 | <listitem> | |
2291 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
2292 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
2293 | % <emphasis role="bold">su root</emphasis> | |
2294 | Password: <<replaceable>root_password</replaceable>> | |
2295 | </programlisting></para> | |
2296 | </listitem> | |
2297 | ||
2298 | <listitem> | |
2299 | <para>Issue the <emphasis role="bold">fs setcell</emphasis> command to change the setuid status of the cell. | |
2300 | <programlisting> | |
2301 | # <emphasis role="bold">fs setcell</emphasis> <<replaceable>cell name</replaceable>>+ [<emphasis role="bold">-suid</emphasis>] [<emphasis | |
2302 | role="bold">-nosuid</emphasis>] | |
2303 | </programlisting></para> | |
2304 | ||
2305 | <para>where <variablelist> | |
2306 | <varlistentry> | |
2307 | <term><emphasis role="bold">setce</emphasis></term> | |
2308 | ||
2309 | <listitem> | |
2310 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcell</emphasis>.</para> | |
2311 | </listitem> | |
2312 | </varlistentry> | |
2313 | ||
2314 | <varlistentry> | |
2315 | <term><emphasis role="bold">cell name</emphasis></term> | |
2316 | ||
2317 | <listitem> | |
2318 | <para>Names each cell for which to change setuid status as specified by the <emphasis role="bold">-suid</emphasis> | |
2319 | or <emphasis role="bold">-nosuid</emphasis> flag. Provide each cell's complete Internet domain name or a shortened | |
2320 | form that distinguishes it from the other cells listed in the local <emphasis | |
2321 | role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para> | |
2322 | </listitem> | |
2323 | </varlistentry> | |
2324 | ||
2325 | <varlistentry> | |
2326 | <term><emphasis role="bold">-suid</emphasis></term> | |
2327 | ||
2328 | <listitem> | |
2329 | <para>Enables programs from each specified cell to execute with setuid permission. Provide this flag or the | |
2330 | <emphasis role="bold">-nosuid</emphasis> flag, or omit both to disable setuid permission for each cell.</para> | |
2331 | </listitem> | |
2332 | </varlistentry> | |
2333 | ||
2334 | <varlistentry> | |
2335 | <term><emphasis role="bold">-nosuid</emphasis></term> | |
2336 | ||
2337 | <listitem> | |
2338 | <para>Prevents programs from each specified cell from executing with setuid permission. Provide this flag or the | |
2339 | <emphasis role="bold">-suid</emphasis> flag, or omit both to disable setuid permission for each cell.</para> | |
2340 | </listitem> | |
2341 | </varlistentry> | |
2342 | </variablelist></para> | |
2343 | </listitem> | |
2344 | </orderedlist> | |
2345 | </sect2> | |
2346 | </sect1> | |
2347 | ||
2348 | <sect1 id="HDRWQ410"> | |
2349 | <title>Setting the File Server Probe Interval</title> | |
2350 | ||
2351 | <indexterm> | |
2352 | <primary>file server probe interval</primary> | |
2353 | ||
2354 | <secondary>setting for a client machine</secondary> | |
2355 | </indexterm> | |
2356 | ||
2357 | <indexterm> | |
2358 | <primary>setting</primary> | |
2359 | ||
2360 | <secondary>client-to-file-server probe interval</secondary> | |
2361 | </indexterm> | |
2362 | ||
2363 | <indexterm> | |
2364 | <primary>Cache Manager</primary> | |
2365 | ||
2366 | <secondary>setting</secondary> | |
2367 | ||
2368 | <tertiary>probe interval for File Server</tertiary> | |
2369 | </indexterm> | |
2370 | ||
2371 | <para>The Cache Manager periodically sends a probe to server machines to verify that they are still accessible. Specifically, it | |
2372 | probes the database server machines in its cell and those file servers that house data it has cached.</para> | |
2373 | ||
2374 | <para>If a server process does not respond to a probe, the client machine assumes that it is inaccessible. By default, the | |
2375 | interval between probes is three minutes, so it can take up to three minutes for a client to recognize that a server process is | |
2376 | once again accessible after it was inaccessible.</para> | |
2377 | ||
2378 | <para>To adjust the probe interval, include the <emphasis role="bold">-interval</emphasis> argument to the <emphasis | |
2379 | role="bold">fs checkservers</emphasis> command while logged in as the local superuser <emphasis role="bold">root</emphasis>. The | |
2380 | new interval setting persists until you again issue the command or reboot the machine, at which time the setting returns to the | |
2381 | default. To preserve a nondefault setting across reboots, include the appropriate <emphasis role="bold">fs | |
2382 | checkservers</emphasis> command in the machine's AFS initialization file.</para> | |
2383 | ||
2384 | <sect2 id="Header_461"> | |
2385 | <title>To set a client's file server probe interval</title> | |
2386 | ||
2387 | <orderedlist> | |
2388 | <listitem> | |
2389 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
2390 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
2391 | % <emphasis role="bold">su root</emphasis> | |
2392 | Password: <<replaceable>root_password</replaceable>> | |
2393 | </programlisting></para> | |
2394 | </listitem> | |
2395 | ||
2396 | <listitem> | |
2397 | <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command with the <emphasis | |
2398 | role="bold">-interval</emphasis> argument. <indexterm> | |
2399 | <primary>fs commands</primary> | |
2400 | ||
2401 | <secondary>checkservers</secondary> | |
2402 | </indexterm> <indexterm> | |
2403 | <primary>commands</primary> | |
2404 | ||
2405 | <secondary>fs checkservers</secondary> | |
2406 | </indexterm> <programlisting> | |
2407 | # <emphasis role="bold">fs checkservers -interval</emphasis> <<replaceable>seconds between probes</replaceable>> | |
2408 | </programlisting></para> | |
2409 | ||
2410 | <para>where <variablelist> | |
2411 | <varlistentry> | |
2412 | <term><emphasis role="bold">checks</emphasis></term> | |
2413 | ||
2414 | <listitem> | |
2415 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">checkservers</emphasis>.</para> | |
2416 | </listitem> | |
2417 | </varlistentry> | |
2418 | ||
2419 | <varlistentry> | |
2420 | <term><emphasis role="bold">-interval</emphasis></term> | |
2421 | ||
2422 | <listitem> | |
2423 | <para>Specifies the number of seconds between probes. Provide an integer value greater than zero.</para> | |
2424 | </listitem> | |
2425 | </varlistentry> | |
2426 | </variablelist></para> | |
2427 | </listitem> | |
2428 | </orderedlist> | |
2429 | </sect2> | |
2430 | </sect1> | |
2431 | ||
2432 | <sect1 id="HDRWQ411"> | |
2433 | <title>Setting a Client Machine's Cell Membership</title> | |
2434 | ||
2435 | <indexterm> | |
2436 | <primary>cell</primary> | |
2437 | ||
2438 | <secondary>setting home cell for client machine</secondary> | |
2439 | </indexterm> | |
2440 | ||
2441 | <indexterm> | |
2442 | <primary>setting</primary> | |
2443 | ||
2444 | <secondary>home cell for client machine</secondary> | |
2445 | </indexterm> | |
2446 | ||
2447 | <indexterm> | |
2448 | <primary>setting</primary> | |
2449 | ||
2450 | <secondary>ThisCell file (client), value in</secondary> | |
2451 | </indexterm> | |
2452 | ||
2453 | <indexterm> | |
2454 | <primary>Cache Manager</primary> | |
2455 | ||
2456 | <secondary>setting</secondary> | |
2457 | ||
2458 | <tertiary>home cell</tertiary> | |
2459 | </indexterm> | |
2460 | ||
2461 | <indexterm> | |
2462 | <primary>client machine</primary> | |
2463 | ||
2464 | <secondary>setting</secondary> | |
2465 | ||
2466 | <tertiary>home cell</tertiary> | |
2467 | </indexterm> | |
2468 | ||
2469 | <indexterm> | |
2470 | <primary>ThisCell file (client)</primary> | |
2471 | ||
2472 | <secondary>setting value in</secondary> | |
2473 | </indexterm> | |
2474 | ||
2475 | <para>Each client machine belongs to a particular cell, as named in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> | |
2476 | on its local disk. The machine's cell membership determines three defaults important to users of the machine: <itemizedlist> | |
2477 | <listitem> | |
2478 | <para>The cell for which users of the machine obtain tokens (authenticate) when they use the <emphasis | |
2479 | role="bold">login</emphasis> program or issue the <emphasis role="bold">klog</emphasis> command. There are two effects: | |
2480 | <itemizedlist> | |
2481 | <listitem> | |
2482 | <para>The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities contact an Authentication | |
2483 | Server in the cell named in the <emphasis role="bold">ThisCell</emphasis> file.</para> | |
2484 | </listitem> | |
2485 | ||
2486 | <listitem> | |
2487 | <para>The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities combine the contents of the | |
2488 | <emphasis role="bold">ThisCell</emphasis> file with the password that the user provides, generating an encryption | |
2489 | key from the combination. The user's entry in the Authentication Database includes an encryption key also generated | |
2490 | from the combination of password and cell name. If the cell name in the <emphasis role="bold">ThisCell</emphasis> | |
2491 | file is incorrect, users cannot authenticate even if they provide the correct password.</para> | |
2492 | </listitem> | |
2493 | </itemizedlist></para> | |
2494 | </listitem> | |
2495 | ||
2496 | <listitem> | |
2497 | <para>The cell the Cache Manager considers its local, or home, cell. The Cache Manager allows programs from its local cell | |
2498 | to run with setuid permission, but not programs from foreign cells, as discussed further in <link | |
2499 | linkend="HDRWQ409">Determining if a Client Can Run Setuid Programs</link>.</para> | |
2500 | </listitem> | |
2501 | ||
2502 | <listitem> | |
2503 | <para>The default database server machines that are contacted by the AFS command interpreters running on this | |
2504 | machine.</para> | |
2505 | </listitem> | |
2506 | </itemizedlist></para> | |
2507 | ||
2508 | <sect2 id="Header_463"> | |
2509 | <title>To display a client machine's cell membership</title> | |
2510 | ||
2511 | <orderedlist> | |
2512 | <listitem> | |
2513 | <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis | |
2514 | role="bold">/usr/vice/etc/ThisCell</emphasis> file. <programlisting> | |
2515 | % <emphasis role="bold">cat /usr/vice/etc/ThisCell</emphasis> | |
2516 | </programlisting></para> | |
2517 | </listitem> | |
2518 | </orderedlist> | |
2519 | </sect2> | |
2520 | ||
2521 | <sect2 id="Header_464"> | |
2522 | <title>To set a client machine's cell membership</title> | |
2523 | ||
2524 | <orderedlist> | |
2525 | <listitem> | |
2526 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
2527 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
2528 | % <emphasis role="bold">su root</emphasis> | |
2529 | Password: <<replaceable>root_password</replaceable>> | |
2530 | </programlisting></para> | |
2531 | </listitem> | |
2532 | ||
2533 | <listitem> | |
2534 | <para>Using a text editor, replace the cell name in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> | |
2535 | file.</para> | |
2536 | </listitem> | |
2537 | ||
2538 | <listitem> | |
2539 | <para><emphasis role="bold">(Optional.)</emphasis> Reboot the machine to enable the Cache Manager to use the new cell name | |
2540 | immediately; the appropriate command depends on the machine's system type. The <emphasis role="bold">klog</emphasis> | |
2541 | program, AFS-modified login utilities, and the AFS command interpreters use the new cell name the next time they are | |
2542 | invoked; no reboot is necessary. <programlisting> | |
2543 | # <emphasis role="bold">sync</emphasis> | |
2544 | # <emphasis role="bold">shutdown</emphasis> | |
2545 | </programlisting></para> | |
2546 | </listitem> | |
2547 | </orderedlist> | |
2548 | </sect2> | |
2549 | </sect1> | |
2550 | ||
2551 | <sect1 id="HDRWQ412"> | |
2552 | <title>Forcing the Update of Cached Data</title> | |
2553 | ||
2554 | <indexterm> | |
2555 | <primary>flushing</primary> | |
2556 | ||
2557 | <secondary>data cache on client machine</secondary> | |
2558 | </indexterm> | |
2559 | ||
2560 | <indexterm> | |
2561 | <primary>data cache</primary> | |
2562 | ||
2563 | <secondary>flushing (forcing update)</secondary> | |
2564 | </indexterm> | |
2565 | ||
2566 | <indexterm> | |
2567 | <primary>Cache Manager</primary> | |
2568 | ||
2569 | <secondary>flushing cache</secondary> | |
2570 | </indexterm> | |
2571 | ||
2572 | <indexterm> | |
2573 | <primary>file</primary> | |
2574 | ||
2575 | <secondary>flushing from data cache on client machine</secondary> | |
2576 | </indexterm> | |
2577 | ||
2578 | <indexterm> | |
2579 | <primary>directory</primary> | |
2580 | ||
2581 | <secondary>flushing from data cache on client machine</secondary> | |
2582 | </indexterm> | |
2583 | ||
2584 | <indexterm> | |
2585 | <primary>volume</primary> | |
2586 | ||
2587 | <secondary>flushing from data cache on client machine</secondary> | |
2588 | </indexterm> | |
2589 | ||
2590 | <indexterm> | |
2591 | <primary>mount point</primary> | |
2592 | ||
2593 | <secondary>flushing from data cache on client machine</secondary> | |
2594 | </indexterm> | |
2595 | ||
2596 | <indexterm> | |
2597 | <primary>client machine</primary> | |
2598 | ||
2599 | <secondary>flushing data cache</secondary> | |
2600 | </indexterm> | |
2601 | ||
2602 | <para>AFS's callback mechanism normally guarantees that the Cache Manager provides the most current version of a file or | |
2603 | directory to the application programs running on its machine. However, you can force the Cache Manager to discard (flush) cached | |
2604 | data so that the next time an application program requests it, the Cache Manager fetches the latest version available at the | |
2605 | File Server.</para> | |
2606 | ||
2607 | <para>You can control how many file system elements to flush at a time: <itemizedlist> | |
2608 | <listitem> | |
2609 | <para>To flush only specific files or directories, use the <emphasis role="bold">fs flush</emphasis> command. This command | |
2610 | forces the Cache Manager to discard the data and status information it has cached from the specified files or directories. | |
2611 | It does not discard information from an application program's buffer or information that has been altered locally (changes | |
2612 | made in the cache but not yet saved permanently to the File Server). However, the next time an application requests the | |
2613 | element's data or status information, the Cache Manager has to contact the File Server to get it.</para> | |
2614 | </listitem> | |
2615 | ||
2616 | <listitem> | |
2617 | <para>To flush everything cached from a certain volume, use the <emphasis role="bold">fs flushvolume</emphasis> command. | |
2618 | This command works like the <emphasis role="bold">fs flush</emphasis> command, but differs in two ways: <itemizedlist> | |
2619 | <listitem> | |
2620 | <para>The Cache Manager discards data for all elements in the cache that come from the same volume as the specified | |
2621 | files or directories.</para> | |
2622 | </listitem> | |
2623 | ||
2624 | <listitem> | |
2625 | <para>The Cache Manager discards only data, not status information. This difference has little practical effect, but | |
2626 | can lead to different output from the <emphasis role="bold">ls</emphasis> command when the two different commands | |
2627 | are used to flush the same element.</para> | |
2628 | </listitem> | |
2629 | </itemizedlist></para> | |
2630 | </listitem> | |
2631 | </itemizedlist></para> | |
2632 | ||
2633 | <para>In addition to callbacks, the Cache Manager has a mechanism for tracking other kinds of possible changes, such as changes | |
2634 | in a volume's location. If a volume moves and the Cache Manager has not accessed any data in it for a long time, the Cache | |
2635 | Manager's volume location record can be wrong. To resynchronize it, use the <emphasis role="bold">fs checkvolumes</emphasis> | |
2636 | command. When you issue the command, the Cache Manager creates a new table of mappings between volume names, ID numbers, and | |
2637 | locations. This forces the Cache Manager to reference newly relocated and renamed volumes before it can provide data from | |
2638 | them.</para> | |
2639 | ||
2640 | <para>It is also possible for information about mount points to become corrupted in the cache. Symptoms of a corrupted mount | |
2641 | point included garbled output from the <emphasis role="bold">fs lsmount</emphasis> command, and failed attempts to change | |
2642 | directory to or list the contents of a mount point. Use the <emphasis role="bold">fs flushmount</emphasis> command to discard a | |
2643 | corrupted mount point. The Cache Manager must refetch the mount point the next time it crosses it in a pathname. (The Cache | |
2644 | Manager periodically refreshes cached mount points, but the only other way to discard them immediately is to reinitialize the | |
2645 | Cache Manager by rebooting the machine. <indexterm> | |
2646 | <primary>fs commands</primary> | |
2647 | ||
2648 | <secondary>flush</secondary> | |
2649 | </indexterm> <indexterm> | |
2650 | <primary>commands</primary> | |
2651 | ||
2652 | <secondary>fs flush</secondary> | |
2653 | </indexterm></para> | |
2654 | ||
2655 | <sect2 id="Header_466"> | |
2656 | <title>To flush certain files or directories</title> | |
2657 | ||
2658 | <orderedlist> | |
2659 | <listitem> | |
2660 | <para>Issue the <emphasis role="bold">fs flush</emphasis> command. <programlisting> | |
2661 | % <emphasis role="bold">fs flush</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
2662 | </programlisting></para> | |
2663 | ||
2664 | <para>where <variablelist> | |
2665 | <varlistentry> | |
2666 | <term><emphasis role="bold">flush</emphasis></term> | |
2667 | ||
2668 | <listitem> | |
2669 | <para>Must be typed in full.</para> | |
2670 | </listitem> | |
2671 | </varlistentry> | |
2672 | ||
2673 | <varlistentry> | |
2674 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
2675 | ||
2676 | <listitem> | |
2677 | <para>Names each file or directory structure to flush from the cache. Omit this argument to flush the current | |
2678 | working directory. Flushing a directory structure does not flush any files or subdirectories cached from | |
2679 | it.</para> | |
2680 | </listitem> | |
2681 | </varlistentry> | |
2682 | </variablelist></para> | |
2683 | </listitem> | |
2684 | </orderedlist> | |
2685 | ||
2686 | <indexterm> | |
2687 | <primary>fs commands</primary> | |
2688 | ||
2689 | <secondary>flushvolume</secondary> | |
2690 | </indexterm> | |
2691 | ||
2692 | <indexterm> | |
2693 | <primary>commands</primary> | |
2694 | ||
2695 | <secondary>fs flushvolume</secondary> | |
2696 | </indexterm> | |
2697 | </sect2> | |
2698 | ||
2699 | <sect2 id="Header_467"> | |
2700 | <title>To flush all data from a volume</title> | |
2701 | ||
2702 | <orderedlist> | |
2703 | <listitem> | |
2704 | <para>Issue the <emphasis role="bold">fs flushvolume</emphasis> command. <programlisting> | |
2705 | % <emphasis role="bold">fs flushvolume</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
2706 | </programlisting></para> | |
2707 | ||
2708 | <para>where <variablelist> | |
2709 | <varlistentry> | |
2710 | <term><emphasis role="bold">flushv</emphasis></term> | |
2711 | ||
2712 | <listitem> | |
2713 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">flushvolume</emphasis>.</para> | |
2714 | </listitem> | |
2715 | </varlistentry> | |
2716 | ||
2717 | <varlistentry> | |
2718 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
2719 | ||
2720 | <listitem> | |
2721 | <para>Names a file or directory from each volume to flush from the cache. The Cache Manager flushes everything in | |
2722 | the cache that it has fetched from the same volume. Omit this argument to flush all cached data fetched from the | |
2723 | volume that contains the current working directory.</para> | |
2724 | </listitem> | |
2725 | </varlistentry> | |
2726 | </variablelist></para> | |
2727 | </listitem> | |
2728 | </orderedlist> | |
2729 | ||
2730 | <indexterm> | |
2731 | <primary>fs commands</primary> | |
2732 | ||
2733 | <secondary>checkvolumes</secondary> | |
2734 | </indexterm> | |
2735 | ||
2736 | <indexterm> | |
2737 | <primary>commands</primary> | |
2738 | ||
2739 | <secondary>fs checkvolumes</secondary> | |
2740 | </indexterm> | |
2741 | </sect2> | |
2742 | ||
2743 | <sect2 id="Header_468"> | |
2744 | <title>To force the Cache Manager to notice other volume changes</title> | |
2745 | ||
2746 | <orderedlist> | |
2747 | <listitem> | |
2748 | <para>Issue the <emphasis role="bold">fs checkvolumes</emphasis> command. <programlisting> | |
2749 | % <emphasis role="bold">fs checkvolumes</emphasis> | |
2750 | </programlisting></para> | |
2751 | ||
2752 | <para>where <emphasis role="bold">checkv</emphasis> is the shortest acceptable abbreviation of <emphasis | |
2753 | role="bold">checkvolumes</emphasis>.</para> | |
2754 | </listitem> | |
2755 | </orderedlist> | |
2756 | ||
2757 | <para>The following command confirms that the command completed successfully:</para> | |
2758 | ||
2759 | <programlisting> | |
2760 | All volumeID/name mappings checked. | |
2761 | </programlisting> | |
2762 | ||
2763 | <indexterm> | |
2764 | <primary>fs commands</primary> | |
2765 | ||
2766 | <secondary>flushmount</secondary> | |
2767 | </indexterm> | |
2768 | ||
2769 | <indexterm> | |
2770 | <primary>commands</primary> | |
2771 | ||
2772 | <secondary>fs flushmount</secondary> | |
2773 | </indexterm> | |
2774 | </sect2> | |
2775 | ||
2776 | <sect2 id="HDRWQ413"> | |
2777 | <title>To flush one or more mount points</title> | |
2778 | ||
2779 | <orderedlist> | |
2780 | <listitem> | |
2781 | <para>Issue the <emphasis role="bold">fs flushmount</emphasis> command. <programlisting> | |
2782 | % <emphasis role="bold">fs flush</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
2783 | </programlisting></para> | |
2784 | ||
2785 | <para>where <variablelist> | |
2786 | <varlistentry> | |
2787 | <term><emphasis role="bold">flushm</emphasis></term> | |
2788 | ||
2789 | <listitem> | |
2790 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">flushmount</emphasis>.</para> | |
2791 | </listitem> | |
2792 | </varlistentry> | |
2793 | ||
2794 | <varlistentry> | |
2795 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
2796 | ||
2797 | <listitem> | |
2798 | <para>Names each mount point to flush from the cache. Omit this argument to flush the current working directory. | |
2799 | Files or subdirectories cached from the associated volume are unaffected.</para> | |
2800 | </listitem> | |
2801 | </varlistentry> | |
2802 | </variablelist></para> | |
2803 | </listitem> | |
2804 | </orderedlist> | |
2805 | </sect2> | |
2806 | </sect1> | |
2807 | ||
2808 | <sect1 id="HDRWQ414"> | |
2809 | <title>Maintaining Server Preference Ranks</title> | |
2810 | ||
2811 | <indexterm> | |
2812 | <primary>Cache Manager</primary> | |
2813 | ||
2814 | <secondary>preference ranks for File Server and VL Server</secondary> | |
2815 | </indexterm> | |
2816 | ||
2817 | <indexterm> | |
2818 | <primary>file server machine</primary> | |
2819 | ||
2820 | <secondary>Cache Manager preference ranks for</secondary> | |
2821 | </indexterm> | |
2822 | ||
2823 | <indexterm> | |
2824 | <primary>displaying</primary> | |
2825 | ||
2826 | <secondary>Cache Manager preference ranks for file server machines</secondary> | |
2827 | </indexterm> | |
2828 | ||
2829 | <indexterm> | |
2830 | <primary>setting</primary> | |
2831 | ||
2832 | <secondary>Cache Manager preferences for file server machines</secondary> | |
2833 | </indexterm> | |
2834 | ||
2835 | <indexterm> | |
2836 | <primary>server preference ranks</primary> | |
2837 | </indexterm> | |
2838 | ||
2839 | <indexterm> | |
2840 | <primary>VL Server</primary> | |
2841 | ||
2842 | <secondary>Cache Manager preference ranks for</secondary> | |
2843 | </indexterm> | |
2844 | ||
2845 | <para>As mentioned in the introduction to this chapter, AFS uses client-side data caching and callbacks to reduce the amount of | |
2846 | network traffic in your cell. The Cache Manager also tries to make its use of the network as efficient as possible by assigning | |
2847 | <emphasis>preference ranks</emphasis> to server machines based on their network proximity to the local machine. The ranks bias | |
2848 | the Cache Manager to fetch information from the server machines that are on its own subnetwork or network rather than on other | |
2849 | networks, if possible. Reducing the network distance that data travels between client and server machine tends to reduce network | |
2850 | traffic and speed the Cache Manager's delivery of data to applications.</para> | |
2851 | ||
2852 | <para>The Cache Manager stores two separate sets of preference ranks in kernel memory. The first set of ranks applies to | |
2853 | machines that run the Volume Location (VL) Server process, hereafter referred to as <emphasis>VL Server machines</emphasis>. The | |
2854 | second set of ranks applies to machines that run the File Server process, hereafter referred to as <emphasis>file server | |
2855 | machines</emphasis>. This section explains how the Cache Manager sets default ranks, how to use the <emphasis role="bold">fs | |
2856 | setserverprefs</emphasis> command to change the defaults or set new ranks, and how to use the <emphasis role="bold">fs | |
2857 | getserverprefs</emphasis> command to display the current set of ranks.</para> | |
2858 | ||
2859 | <sect2 id="Header_471"> | |
2860 | <title>How the Cache Manager Sets Default Ranks</title> | |
2861 | ||
2862 | <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it assigns a preference rank of | |
2863 | 10,000 to each of the VL Server machines listed in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. | |
2864 | It then randomizes the ranks by adding an integer randomly chosen from the range 0 (zero) to 126. It avoids assigning the same | |
2865 | rank to machines in one cell, but it is possible for machines from different cells to have the same rank. This does not | |
2866 | present a problem in use, because the Cache Manager compares the ranks of only one cell's database server machines at a time. | |
2867 | Although AFS supports the use of multihomed database server machines, the Cache Manager only uses the single address listed | |
2868 | for each database server machine in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Only Ubik can | |
2869 | take advantage of a multihomed database server machine's multiple interfaces.</para> | |
2870 | ||
2871 | <para>The Cache Manager assigns preference ranks to a file server machine when it obtains the server's VLDB record from the VL | |
2872 | Server, the first time that it accesses a volume that resides on the machine. If the machine is multihomed, the Cache Manager | |
2873 | assigns a distinct rank to each of its interfaces (up to the number of interfaces that the VLDB can store for each machine, | |
2874 | which is specified in the <emphasis>OpenAFS Release Notes</emphasis>). The Cache Manager compares the interface's IP address | |
2875 | to the local machine's address and applies the following algorithm: <itemizedlist> | |
2876 | <listitem> | |
2877 | <para>If the local machine is a file server machine, the base rank for each of its interfaces is 5,000.</para> | |
2878 | </listitem> | |
2879 | ||
2880 | <listitem> | |
2881 | <para>If the file server machine interface is on the same subnetwork as the local machine, its base rank is | |
2882 | 20,000.</para> | |
2883 | </listitem> | |
2884 | ||
2885 | <listitem> | |
2886 | <para>If the file server machine interface is on the same network as the local machine, or is at the distant end of a | |
2887 | point-to-point link with the local machine, its base rank is 30,000.</para> | |
2888 | </listitem> | |
2889 | ||
2890 | <listitem> | |
2891 | <para>If the file server machine interface is on a different network than the local machine, or the Cache Manager cannot | |
2892 | obtain network information about it, its base rank is 40,000.</para> | |
2893 | </listitem> | |
2894 | </itemizedlist></para> | |
2895 | ||
2896 | <para>If the client machine has only one interface, the Cache Manager compares it to the server interface's IP address and | |
2897 | sets a rank according to the algorithm. If the client machine is multihomed, the Cache Manager compares each of the local | |
2898 | interface addresses to the server interface, and assigns to the server interface the lowest rank that results from comparing | |
2899 | it to all of the client interfaces.</para> | |
2900 | ||
2901 | <para>After assigning a base rank to a file server machine interface, the Cache Manager adds to it a number randomly chosen | |
2902 | from the range 0 (zero) to 15. As an example, a file server machine interface in the same subnetwork as the local machine | |
2903 | receives a base rank of 20,000, but the Cache Manager records the actual rank as an integer between 20,000 and 20,015. This | |
2904 | process reduces the number of interfaces that have exactly the same rank. As with VL Server machine ranks, it is possible for | |
2905 | file server machine interfaces from foreign cells to have the same rank as interfaces in the local cell, but this does not | |
2906 | present a problem. Only the relative ranks of the interfaces that house a specific volume are relevant, and AFS supports | |
2907 | storage of a volume in only one cell at a time.</para> | |
2908 | </sect2> | |
2909 | ||
2910 | <sect2 id="Header_472"> | |
2911 | <title>How the Cache Manager Uses Preference Ranks</title> | |
2912 | ||
2913 | <para>Each preference rank pairs an interface's IP address with an integer that can range from 1 to 65,534. A lower rank | |
2914 | (lower number) indicates a stronger preference. Once set, a rank persists until the machine reboots, or until you use the | |
2915 | <emphasis role="bold">fs setserverprefs</emphasis> command to change it.</para> | |
2916 | ||
2917 | <para>The Cache Manager uses VL Server machine ranks when it needs to fetch volume location information from a cell. It | |
2918 | compares the ranks for the cell's VL Server machines and attempts to contact the VL Server process on the machine with the | |
2919 | best (lowest integer) rank. If it cannot reach that VL Server, it tries to contact the VL Server with the next best rank, and | |
2920 | so on. If all of a cell's VL Server machines are inaccessible, the Cache Manager cannot fetch data from the cell.</para> | |
2921 | ||
2922 | <para>Similarly, when the Cache Manager needs to fetch data from a volume, it compares the ranks for the interfaces of | |
2923 | machines that house the volume, and attempts to contact the interface that has the best rank. If it cannot reach the <emphasis | |
2924 | role="bold">fileserver</emphasis> process via that interface, it tries to contact the interface with the next best integer | |
2925 | rank, and so on. If it cannot reach any of the interfaces for machines that house the volume, it cannot fetch data from the | |
2926 | volume.</para> | |
2927 | </sect2> | |
2928 | ||
2929 | <sect2 id="Header_473"> | |
2930 | <title>Displaying and Setting Preference Ranks</title> | |
2931 | ||
2932 | <para>To display the file server machine ranks that the Cache Manager is using, use the <emphasis role="bold">fs | |
2933 | getserverprefs</emphasis> command. Include the <emphasis role="bold">-vlservers</emphasis> flag to display VL Server machine | |
2934 | ranks instead. By default, the output appears on the standard output stream (stdout), but you can write it to a file instead | |
2935 | by including the <emphasis role="bold">-file</emphasis> argument.</para> | |
2936 | ||
2937 | <para>The Cache Manager stores IP addresses rather than hostnames in its kernel list of ranks, but by default the output | |
2938 | identifies interfaces by hostname after calling a translation routine that refers to either the cell's name service (such as | |
2939 | the Domain Name Server) or the local host table. If an IP address appears in this case, it is because the translation attempt | |
2940 | failed. To bypass the translation step and display IP addresses rather than hostnames, include the <emphasis | |
2941 | role="bold">-numeric</emphasis> flag. This can significantly speed up the output.</para> | |
2942 | ||
2943 | <para>You can use the <emphasis role="bold">fs setserverprefs</emphasis> command to reset an existing preference rank, or to | |
2944 | set the initial rank of a file server machine interface or VL Server machine for which the Cache Manager has no rank. The | |
2945 | ranks you set persist until the machine reboots or until you issue the <emphasis role="bold">fs setserverprefs</emphasis> | |
2946 | command again. To make a rank persist across a reboot, place the appropriate <emphasis role="bold">fs | |
2947 | setserverprefs</emphasis> command in the machine's AFS initialization file.</para> | |
2948 | ||
2949 | <para>As with default ranks, the Cache Manager adds a randomly chosen integer to each rank range that you assign. For file | |
2950 | server machine interfaces, the randomizing number is from the range 0 (zero) to 15; for VL Server machines, it is from the | |
2951 | range 0 (zero) to 126. For example, if you assign a rank of 15,000 to a file server machine interface, the Cache Manager | |
2952 | stores an integer between 15,000 to 15,015.</para> | |
2953 | ||
2954 | <para>To assign VL Server machine ranks, list them after the <emphasis role="bold">-vlserver</emphasis> argument to the | |
2955 | <emphasis role="bold">fs setserverprefs</emphasis> command.</para> | |
2956 | ||
2957 | <para>To assign file server machine ranks, use or more of the three possible methods: <orderedlist> | |
2958 | <listitem> | |
2959 | <para>List them after the <emphasis role="bold">-servers</emphasis> argument on the command line.</para> | |
2960 | </listitem> | |
2961 | ||
2962 | <listitem> | |
2963 | <para>Record them in a file and name it with the <emphasis role="bold">-file</emphasis> argument. You can easily | |
2964 | generate a file with the proper format by including the <emphasis role="bold">-file</emphasis> argument to the <emphasis | |
2965 | role="bold">fs getserverprefs</emphasis> command.</para> | |
2966 | </listitem> | |
2967 | ||
2968 | <listitem> | |
2969 | <para>Provide them via the standard input stream, by including the <emphasis role="bold">-stdin</emphasis> flag. This | |
2970 | enables you to feed in values directly from a command or script that generates preferences using an algorithm | |
2971 | appropriate for your cell. It must generate them in the proper format, with one or more spaces between each pair and | |
2972 | between the two parts of the pair. The AFS distribution does not include such a script, so you must write one if you | |
2973 | want to use this method.</para> | |
2974 | </listitem> | |
2975 | </orderedlist></para> | |
2976 | ||
2977 | <para>You can combine any of the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>, and | |
2978 | <emphasis role="bold">-stdin</emphasis> options on the same command line if you wish. If more than one of them specifies a | |
2979 | rank for the same interface, the one assigned with the <emphasis role="bold">-servers</emphasis> argument takes precedence. | |
2980 | You can also provide the <emphasis role="bold">-vlservers</emphasis> argument on the same command line to set VL Server | |
2981 | machine ranks at the same time as file server machine ranks.</para> | |
2982 | ||
2983 | <para>The <emphasis role="bold">fs</emphasis> command interpreter does not verify hostnames or IP addresses, and so willingly | |
2984 | stores ranks for hostnames and addresses that don't actually exist. The Cache Manager never uses such ranks unless the same | |
2985 | VLDB record for a server machine records the same incorrect information. <indexterm> | |
2986 | <primary>fs commands</primary> | |
2987 | ||
2988 | <secondary>getserverprefs</secondary> | |
2989 | </indexterm> <indexterm> | |
2990 | <primary>commands</primary> | |
2991 | ||
2992 | <secondary>fs getserverprefs</secondary> | |
2993 | </indexterm></para> | |
2994 | </sect2> | |
2995 | ||
2996 | <sect2 id="Header_474"> | |
2997 | <title>To display server preference ranks</title> | |
2998 | ||
2999 | <orderedlist> | |
3000 | <listitem> | |
3001 | <para>Issue the <emphasis role="bold">fs getserverprefs</emphasis> command to display the Cache Manager's preference ranks | |
3002 | for file server machines or VL Server machines. <programlisting> | |
3003 | % <emphasis role="bold">fs getserverprefs</emphasis> [<emphasis role="bold">-file</emphasis> <<replaceable>output to named file</replaceable>>] [<emphasis | |
3004 | role="bold">-numeric</emphasis>] [<emphasis role="bold">-vlservers</emphasis>] | |
3005 | </programlisting></para> | |
3006 | ||
3007 | <para>where <variablelist> | |
3008 | <varlistentry> | |
3009 | <term><emphasis role="bold">gp</emphasis></term> | |
3010 | ||
3011 | <listitem> | |
3012 | <para>Is an acceptable alias for <emphasis role="bold">getserverprefs</emphasis> (<emphasis | |
3013 | role="bold">gets</emphasis> is the shortest acceptable abbreviation).</para> | |
3014 | </listitem> | |
3015 | </varlistentry> | |
3016 | ||
3017 | <varlistentry> | |
3018 | <term><emphasis role="bold">-file</emphasis></term> | |
3019 | ||
3020 | <listitem> | |
3021 | <para>Specifies the pathname of the file to which to write the list of ranks. Omit this argument to display the | |
3022 | list on the standard output stream (stdout).</para> | |
3023 | </listitem> | |
3024 | </varlistentry> | |
3025 | ||
3026 | <varlistentry> | |
3027 | <term><emphasis role="bold">-numeric</emphasis></term> | |
3028 | ||
3029 | <listitem> | |
3030 | <para>Displays the IP address, rather than the hostname, of each ranked machine interface. Omit this flag to have | |
3031 | the addresses translated into hostnames, which takes longer.</para> | |
3032 | </listitem> | |
3033 | </varlistentry> | |
3034 | ||
3035 | <varlistentry> | |
3036 | <term><emphasis role="bold">-vlservers</emphasis></term> | |
3037 | ||
3038 | <listitem> | |
3039 | <para>Displays ranks for VL Server machines rather than file server machines.</para> | |
3040 | </listitem> | |
3041 | </varlistentry> | |
3042 | </variablelist></para> | |
3043 | ||
3044 | <para>The following example displays file server machine ranks. The <emphasis role="bold">-numeric</emphasis> flag is not | |
3045 | used, so the appearance of an IP address indicates that is not currently possible to translate it to a hostname.</para> | |
3046 | ||
3047 | <programlisting> | |
3048 | % <emphasis role="bold">fs gp</emphasis> | |
3049 | fs5.example.com 20000 | |
3050 | fs1.example.com 30014 | |
3051 | server1.example.org 40011 | |
3052 | fs3.example.com 20001 | |
3053 | fs4.example.com 30001 | |
3054 | 192.12.106.120 40002 | |
3055 | 192.12.106.119 40001 | |
3056 | . . . . . . . | |
3057 | </programlisting> | |
3058 | </listitem> | |
3059 | </orderedlist> | |
3060 | ||
3061 | <indexterm> | |
3062 | <primary>fs commands</primary> | |
3063 | ||
3064 | <secondary>setserverprefs</secondary> | |
3065 | </indexterm> | |
3066 | ||
3067 | <indexterm> | |
3068 | <primary>commands</primary> | |
3069 | ||
3070 | <secondary>fs setserverprefs</secondary> | |
3071 | </indexterm> | |
3072 | ||
3073 | <indexterm> | |
3074 | <primary>preferences</primary> | |
3075 | ||
3076 | <secondary>setting</secondary> | |
3077 | </indexterm> | |
3078 | </sect2> | |
3079 | ||
3080 | <sect2 id="Header_475"> | |
3081 | <title>To set server preference ranks</title> | |
3082 | ||
3083 | <orderedlist> | |
3084 | <listitem> | |
3085 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3086 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3087 | % <emphasis role="bold">su root</emphasis> | |
3088 | Password: <<replaceable>root_password</replaceable>> | |
3089 | </programlisting></para> | |
3090 | </listitem> | |
3091 | ||
3092 | <listitem> | |
3093 | <para>Issue the <emphasis role="bold">fs setserverprefs</emphasis> command to set the Cache Manager's preference ranks for | |
3094 | one or more file server machines or VL Server machines. <programlisting> | |
3095 | # <emphasis role="bold">fs setserverprefs</emphasis> [<emphasis role="bold">-servers</emphasis> <<replaceable>fileserver names and ranks</replaceable>>+] \ | |
3096 | [<emphasis role="bold">-vlservers</emphasis> <<replaceable>VL server names and ranks</replaceable>>+] \ | |
3097 | [<emphasis role="bold">-file</emphasis> <<replaceable>input from named file</replaceable>>] [<emphasis | |
3098 | role="bold">-stdin</emphasis>] | |
3099 | </programlisting></para> | |
3100 | ||
3101 | <para>where <variablelist> | |
3102 | <varlistentry> | |
3103 | <term><emphasis role="bold">sp</emphasis></term> | |
3104 | ||
3105 | <listitem> | |
3106 | <para>Is an acceptable alias for <emphasis role="bold">setserverprefs</emphasis> (<emphasis | |
3107 | role="bold">sets</emphasis> is the shortest acceptable abbreviation).</para> | |
3108 | </listitem> | |
3109 | </varlistentry> | |
3110 | ||
3111 | <varlistentry> | |
3112 | <term><emphasis role="bold">-servers</emphasis></term> | |
3113 | ||
3114 | <listitem> | |
3115 | <para>Specifies one or more pairs of file server machine interface and rank. Identify each interface by its | |
3116 | fully-qualified hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <emphasis | |
3117 | role="bold">1</emphasis> to <emphasis role="bold">65534</emphasis>. Separate the parts of a pair, and the pairs | |
3118 | from one another, with one or more spaces.</para> | |
3119 | </listitem> | |
3120 | </varlistentry> | |
3121 | ||
3122 | <varlistentry> | |
3123 | <term><emphasis role="bold">-vlservers</emphasis></term> | |
3124 | ||
3125 | <listitem> | |
3126 | <para>Specifies one or more pairs of VL Server machine and rank. Identify each machine by its fully-qualified | |
3127 | hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <emphasis | |
3128 | role="bold">1</emphasis> to <emphasis role="bold">65534</emphasis>.</para> | |
3129 | </listitem> | |
3130 | </varlistentry> | |
3131 | ||
3132 | <varlistentry> | |
3133 | <term><emphasis role="bold">-file</emphasis></term> | |
3134 | ||
3135 | <listitem> | |
3136 | <para>Specifies the pathname of a file that contains one more pairs of file server machine interface and rank. | |
3137 | Place each pair on its own line in the file. Use the same format for interfaces and ranks as with the <emphasis | |
3138 | role="bold">-servers</emphasis> argument.</para> | |
3139 | </listitem> | |
3140 | </varlistentry> | |
3141 | ||
3142 | <varlistentry> | |
3143 | <term><emphasis role="bold">-stdin</emphasis></term> | |
3144 | ||
3145 | <listitem> | |
3146 | <para>Indicates that pairs of file server machine interface and rank are being provided via the standard input | |
3147 | stream (stdin). The program or script that generates the pairs must format them in the same manner as for the | |
3148 | <emphasis role="bold">-servers</emphasis> argument.</para> | |
3149 | </listitem> | |
3150 | </varlistentry> | |
3151 | </variablelist></para> | |
3152 | </listitem> | |
3153 | </orderedlist> | |
3154 | </sect2> | |
3155 | </sect1> | |
3156 | ||
3157 | <sect1 id="HDRWQ415"> | |
3158 | <title>Managing Multihomed Client Machines</title> | |
3159 | ||
3160 | <indexterm> | |
3161 | <primary>Cache Manager</primary> | |
3162 | ||
3163 | <secondary>use of NetInfo file</secondary> | |
3164 | </indexterm> | |
3165 | ||
3166 | <indexterm> | |
3167 | <primary>Cache Manager</primary> | |
3168 | ||
3169 | <secondary>use of NetRestrict file</secondary> | |
3170 | </indexterm> | |
3171 | ||
3172 | <indexterm> | |
3173 | <primary>Cache Manager</primary> | |
3174 | ||
3175 | <secondary>interfaces registered with File Server</secondary> | |
3176 | </indexterm> | |
3177 | ||
3178 | <indexterm> | |
3179 | <primary>File Server</primary> | |
3180 | ||
3181 | <secondary>client interfaces registered</secondary> | |
3182 | </indexterm> | |
3183 | ||
3184 | <indexterm> | |
3185 | <primary>setting</primary> | |
3186 | ||
3187 | <secondary>client interfaces registered with File Server</secondary> | |
3188 | </indexterm> | |
3189 | ||
3190 | <indexterm> | |
3191 | <primary>displaying</primary> | |
3192 | ||
3193 | <secondary>client interfaces registered with File Server</secondary> | |
3194 | </indexterm> | |
3195 | ||
3196 | <para>The File Server can choose the interface to which to send a message when it initiates communication with the Cache Manager | |
3197 | on a multihomed client machine (one with more than one network interface and IP address). If that interface is inaccessible, it | |
3198 | automatically switches to an alternate. This improves AFS performance, because it means that the outage of an interface does not | |
3199 | interrupt communication between File Server and Cache Manager.</para> | |
3200 | ||
3201 | <para>The File Server can choose the client interface when it sends two types of messages: <itemizedlist> | |
3202 | <listitem> | |
3203 | <para>A message to break the callback that the Cache Manager holds on a cached file</para> | |
3204 | </listitem> | |
3205 | ||
3206 | <listitem> | |
3207 | <para>A <emphasis>ping</emphasis> message to check that the Cache Manager is still accessible and responding; the File | |
3208 | Server sends such a message every few minutes</para> | |
3209 | </listitem> | |
3210 | </itemizedlist></para> | |
3211 | ||
3212 | <para>(The File Server does not choose which client interface to respond to when filling a Cache Manager's request for AFS data. | |
3213 | In that case, it always responds to the client interface via which the Cache Manager sent the request.)</para> | |
3214 | ||
3215 | <para>The Cache Manager compiles the list of eligible interfaces on its client machine automatically as it initializes, and | |
3216 | records them in kernel memory. When the Cache Manager first establishes a connection with the File Server, it sends along the | |
3217 | list of interface addresses. The File Server records the addresses, and uses the one at the top of the list when it needs to | |
3218 | break a callback or send a ping to the Cache Manager. If that interface is inaccessible, the File Server simultaneously sends a | |
3219 | message to all of the other interfaces in the list. Whichever interface replies first is the one to which the File Server sends | |
3220 | future messages.</para> | |
3221 | ||
3222 | <para>You can control which addresses the Cache Manager registers with File Servers by listing them in two files in the | |
3223 | <emphasis role="bold">/usr/vice/etc</emphasis> directory on the client machine's local disk: <emphasis | |
3224 | role="bold">NetInfo</emphasis> and <emphasis role="bold">NetRestrict</emphasis>. If the <emphasis role="bold">NetInfo</emphasis> | |
3225 | file exists when the Cache Manager initializes, the Cache Manager uses its contents as the basis for the list of interfaces. | |
3226 | Otherwise, the Cache Manager uses the list of interfaces configured with the operating system. It then removes from the list any | |
3227 | addresses that appear in the <emphasis role="bold">/usr/vice/etc/NetRestrict</emphasis> file, if it exists. The Cache Manager | |
3228 | records the resulting list in kernel memory.</para> | |
3229 | ||
3230 | <para>You can also use the <emphasis role="bold">fs setclientaddrs</emphasis> command to change the list of addresses stored in | |
3231 | the Cache Manager's kernel memory, without rebooting the client machine. The list of addresses you provide on the command line | |
3232 | completely replaces the current list in kernel memory. The changes you make persist only until the client machine reboots, | |
3233 | however. To preserve the revised list across reboots, list the interfaces in the <emphasis role="bold">NetInfo</emphasis> file | |
3234 | (and if appropriate, the <emphasis role="bold">NetRestrict</emphasis> file) in the local <emphasis | |
3235 | role="bold">/usr/vice/etc</emphasis> directory. (You can also place the appropriate <emphasis role="bold">fs | |
3236 | setclientaddrs</emphasis> command in the machine's AFS initialization script, but that is less efficient: by the time the Cache | |
3237 | Manager reads the command in the script, it has already compiled a list of interfaces.)</para> | |
3238 | ||
3239 | <para>To display the list of addresses that the Cache Manager is currently registering with File Servers, use the <emphasis | |
3240 | role="bold">fs getclientaddrs</emphasis> command.</para> | |
3241 | ||
3242 | <para>Keep the following in mind when you change the <emphasis role="bold">NetInfo</emphasis> or <emphasis | |
3243 | role="bold">NetRestrict</emphasis> file, or issue the <emphasis role="bold">fs getclientaddrs</emphasis> or <emphasis | |
3244 | role="bold">fs setclientaddrs</emphasis> commands: <itemizedlist> | |
3245 | <listitem> | |
3246 | <para>When you issue the <emphasis role="bold">fs setclientaddrs</emphasis> command, the revised list of addresses does | |
3247 | not propagate automatically to File Servers with which the Cache Manager has already established a connection. They | |
3248 | continue to use the list that the Cache Manager registered with them when it first established a connection. To force | |
3249 | previously contacted File Servers to use the revised list, you must either reboot each file server machine, or reboot the | |
3250 | client machine after changing its <emphasis role="bold">NetInfo</emphasis> file, <emphasis | |
3251 | role="bold">NetRestrict</emphasis> file, or both.</para> | |
3252 | </listitem> | |
3253 | ||
3254 | <listitem> | |
3255 | <para>The <emphasis role="bold">fs</emphasis> command interpreter verifies that each of the addresses you specify on the | |
3256 | <emphasis role="bold">fs setclientaddrs</emphasis> command line is actually configured with the client machine's operating | |
3257 | system. If it is not, the command fails with an error message that marks the address as a <computeroutput>Nonexistent | |
3258 | interface</computeroutput>.</para> | |
3259 | </listitem> | |
3260 | ||
3261 | <listitem> | |
3262 | <para>As previously noted, the File Server does not use the registered list of addresses when it responds to the Cache | |
3263 | Manager's request for data (as opposed to initiating communication itself). It always attempts to send its reply to the | |
3264 | interface from which the Cache Manager sent the request. If the reply attempt fails, the File Server selects an alternate | |
3265 | route for resending the reply according to its server machine's network routing configuration, not the list of addresses | |
3266 | registered by the Cache Manager.</para> | |
3267 | </listitem> | |
3268 | ||
3269 | <listitem> | |
3270 | <para>The Cache Manager does not use the list of interfaces when choosing the interface via which to establish a | |
3271 | connection to a File Server.</para> | |
3272 | </listitem> | |
3273 | ||
3274 | <listitem> | |
3275 | <para>The list of addresses that the <emphasis role="bold">fs getclientaddrs</emphasis> command displays is not | |
3276 | necessarily the one that a specific File Server is using, if an administrator has issued the <emphasis role="bold">fs | |
3277 | setclientaddrs</emphasis> command since the Cache Manager first contacted that File Server. It determines only which | |
3278 | addresses the Cache Manager registers when connecting to File Servers in future.</para> | |
3279 | </listitem> | |
3280 | </itemizedlist></para> | |
3281 | ||
3282 | <indexterm> | |
3283 | <primary>files</primary> | |
3284 | ||
3285 | <secondary>NetInfo (client version)</secondary> | |
3286 | </indexterm> | |
3287 | ||
3288 | <indexterm> | |
3289 | <primary>NetInfo file (client version)</primary> | |
3290 | </indexterm> | |
3291 | ||
3292 | <indexterm> | |
3293 | <primary>creating</primary> | |
3294 | ||
3295 | <secondary>NetInfo file (client version)</secondary> | |
3296 | </indexterm> | |
3297 | ||
3298 | <indexterm> | |
3299 | <primary>editing</primary> | |
3300 | ||
3301 | <secondary>NetInfo file (client version)</secondary> | |
3302 | </indexterm> | |
3303 | ||
3304 | <sect2 id="Header_477"> | |
3305 | <title>To create or edit the client NetInfo file</title> | |
3306 | ||
3307 | <orderedlist> | |
3308 | <listitem> | |
3309 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3310 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3311 | % <emphasis role="bold">su root</emphasis> | |
3312 | Password: <<replaceable>root_password</replaceable>> | |
3313 | </programlisting></para> | |
3314 | </listitem> | |
3315 | ||
3316 | <listitem> | |
3317 | <para>Using a text editor, open the <emphasis role="bold">/usr/vice/etc/NetInfo</emphasis> file. Place one IP address in | |
3318 | dotted decimal format (for example, <computeroutput>192.12.107.33</computeroutput>) on each line. On the first line, put | |
3319 | the address that you want each File Server to use initially. The order of the remaining machines does not matter, because | |
3320 | if an RPC to the first interface fails, the File Server simultaneously sends RPCs to all of the other interfaces in the | |
3321 | list. Whichever interface replies first is the one to which the File Server then sends pings and RPCs to break | |
3322 | callbacks.</para> | |
3323 | </listitem> | |
3324 | ||
3325 | <listitem> | |
3326 | <para>If you want the Cache Manager to start using the revised list immediately, either reboot the machine, or use the | |
3327 | <emphasis role="bold">fs setclientaddrs</emphasis> command to create the same list of addresses in kernel memory | |
3328 | directly.</para> | |
3329 | </listitem> | |
3330 | </orderedlist> | |
3331 | ||
3332 | <indexterm> | |
3333 | <primary>files</primary> | |
3334 | ||
3335 | <secondary>NetRestrict (client version)</secondary> | |
3336 | </indexterm> | |
3337 | ||
3338 | <indexterm> | |
3339 | <primary>NetRestrict file (client version)</primary> | |
3340 | </indexterm> | |
3341 | ||
3342 | <indexterm> | |
3343 | <primary>creating</primary> | |
3344 | ||
3345 | <secondary>NetRestrict file (client version)</secondary> | |
3346 | </indexterm> | |
3347 | ||
3348 | <indexterm> | |
3349 | <primary>editing</primary> | |
3350 | ||
3351 | <secondary>NetRestrict file (client version)</secondary> | |
3352 | </indexterm> | |
3353 | </sect2> | |
3354 | ||
3355 | <sect2 id="Header_478"> | |
3356 | <title>To create or edit the client NetRestrict file</title> | |
3357 | ||
3358 | <orderedlist> | |
3359 | <listitem> | |
3360 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3361 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3362 | % <emphasis role="bold">su root</emphasis> | |
3363 | Password: <<replaceable>root_password</replaceable>> | |
3364 | </programlisting></para> | |
3365 | </listitem> | |
3366 | ||
3367 | <listitem> | |
3368 | <para>Using a text editor, open the <emphasis role="bold">/usr/vice/etc/NetRestrict</emphasis> file. Place one IP address | |
3369 | in dotted decimal format on each line. The order of the addresses is not significant. Use a slash (<emphasis | |
3370 | role="bold">/</emphasis>) followed by a subnet length to represent all possible addresses in a range. For example, the entry | |
3371 | <computeroutput>192.12.105.0/24</computeroutput> indicates that the Cache Manager does not register any of the addresses in | |
3372 | the 192.12.105 subnet.</para> | |
3373 | </listitem> | |
3374 | ||
3375 | <listitem> | |
3376 | <para>If you want the Cache Manager to start using the revised list immediately, either reboot the machine, or use the | |
3377 | <emphasis role="bold">fs setclientaddrs</emphasis> command to set a list of addresses that does not included the | |
3378 | prohibited ones.</para> | |
3379 | </listitem> | |
3380 | </orderedlist> | |
3381 | ||
3382 | <indexterm> | |
3383 | <primary>fs commands</primary> | |
3384 | ||
3385 | <secondary>getclientaddrs</secondary> | |
3386 | </indexterm> | |
3387 | ||
3388 | <indexterm> | |
3389 | <primary>commands</primary> | |
3390 | ||
3391 | <secondary>fs getclientaddrs</secondary> | |
3392 | </indexterm> | |
3393 | </sect2> | |
3394 | ||
3395 | <sect2 id="Header_479"> | |
3396 | <title>To display the list of addresses from kernel memory</title> | |
3397 | ||
3398 | <orderedlist> | |
3399 | <listitem> | |
3400 | <para>Issue the <emphasis role="bold">fs getclientaddrs</emphasis> command. <programlisting> | |
3401 | % <emphasis role="bold">fs getclientaddrs</emphasis> | |
3402 | </programlisting></para> | |
3403 | ||
3404 | <para>where <emphasis role="bold">gc</emphasis> is an acceptable alias for <emphasis role="bold">getclientaddrs</emphasis> | |
3405 | (<emphasis role="bold">getcl</emphasis> is the shortest acceptable abbreviation).</para> | |
3406 | </listitem> | |
3407 | </orderedlist> | |
3408 | ||
3409 | <para>The output lists each IP address on its own line, in dotted decimal format. <indexterm> | |
3410 | <primary>fs commands</primary> | |
3411 | ||
3412 | <secondary>setclientaddrs</secondary> | |
3413 | </indexterm> <indexterm> | |
3414 | <primary>commands</primary> | |
3415 | ||
3416 | <secondary>fs setclientaddrs</secondary> | |
3417 | </indexterm></para> | |
3418 | </sect2> | |
3419 | ||
3420 | <sect2 id="Header_480"> | |
3421 | <title>To set the list of addresses in kernel memory</title> | |
3422 | ||
3423 | <orderedlist> | |
3424 | <listitem> | |
3425 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3426 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3427 | % <emphasis role="bold">su root</emphasis> | |
3428 | Password: <<replaceable>root_password</replaceable>> | |
3429 | </programlisting></para> | |
3430 | </listitem> | |
3431 | ||
3432 | <listitem> | |
3433 | <para>Issue the <emphasis role="bold">fs setclientaddrs</emphasis> command to replace the list of addresses currently in | |
3434 | kernel memory with a new list. <programlisting> | |
3435 | # <emphasis role="bold">fs setclientaddrs</emphasis> [<emphasis role="bold">-address</emphasis> <<replaceable>client network interfaces</replaceable>>+] | |
3436 | </programlisting></para> | |
3437 | ||
3438 | <para>where <variablelist> | |
3439 | <varlistentry> | |
3440 | <term><emphasis role="bold">sc</emphasis></term> | |
3441 | ||
3442 | <listitem> | |
3443 | <para>Is an acceptable alias for <emphasis role="bold">setclientaddrs</emphasis> (<emphasis | |
3444 | role="bold">setcl</emphasis> is the shortest acceptable abbreviation).</para> | |
3445 | </listitem> | |
3446 | </varlistentry> | |
3447 | ||
3448 | <varlistentry> | |
3449 | <term><emphasis role="bold">-address</emphasis></term> | |
3450 | ||
3451 | <listitem> | |
3452 | <para>Specifies one or more IP addresses in dotted decimal format (hostnames are not acceptable). Separate each | |
3453 | address with one or more spaces.</para> | |
3454 | </listitem> | |
3455 | </varlistentry> | |
3456 | </variablelist></para> | |
3457 | </listitem> | |
3458 | </orderedlist> | |
3459 | </sect2> | |
3460 | </sect1> | |
3461 | ||
3462 | <sect1 id="HDRWQ416"> | |
3463 | <title>Controlling the Display of Warning and Informational Messages</title> | |
3464 | ||
3465 | <indexterm> | |
3466 | <primary>Cache Manager</primary> | |
3467 | ||
3468 | <secondary>messages displayed, controlling</secondary> | |
3469 | </indexterm> | |
3470 | ||
3471 | <indexterm> | |
3472 | <primary>client machine</primary> | |
3473 | ||
3474 | <secondary>messages displayed, controlling</secondary> | |
3475 | </indexterm> | |
3476 | ||
3477 | <para>By default, the Cache Manager generates two types of warning and informational messages: <itemizedlist> | |
3478 | <listitem> | |
3479 | <para>It sends <emphasis>user messages</emphasis>, which provide user-level status and warning information, to user | |
3480 | screens.</para> | |
3481 | </listitem> | |
3482 | ||
3483 | <listitem> | |
3484 | <para>It sends <emphasis>console messages</emphasis>, which provide system-level status and warning information, to the | |
3485 | client machine's designated console.</para> | |
3486 | </listitem> | |
3487 | </itemizedlist></para> | |
3488 | ||
3489 | <para>You can use the <emphasis role="bold">fs messages</emphasis> command to control whether the Cache Manager displays either | |
3490 | type of message, both types, or neither. It is best not to disable messages completely, because they provide useful | |
3491 | information.</para> | |
3492 | ||
3493 | <para>If you want to monitor Cache Manager status and performance more actively, you can use the <emphasis | |
3494 | role="bold">afsmonitor</emphasis> program to collect an extensive set of statistics (it also gathers File Server statistics). If | |
3495 | you experience performance problems, you can use <emphasis role="bold">fstrace</emphasis> suite of commands to gather a | |
3496 | low-level trace of Cache Manager operations, which the AFS Support and Development groups can analyze to help solve your | |
3497 | problem. To learn about both utilities, see <link linkend="HDRWQ323">Monitoring and Auditing AFS Performance</link>. <indexterm> | |
3498 | <primary>fs commands</primary> | |
3499 | ||
3500 | <secondary>messages</secondary> | |
3501 | </indexterm> <indexterm> | |
3502 | <primary>commands</primary> | |
3503 | ||
3504 | <secondary>fs messages</secondary> | |
3505 | </indexterm></para> | |
3506 | ||
3507 | <sect2 id="Header_482"> | |
3508 | <title>To control the display of warning and status messages</title> | |
3509 | ||
3510 | <orderedlist> | |
3511 | <listitem> | |
3512 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3513 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3514 | % <emphasis role="bold">su root</emphasis> | |
3515 | Password: <<replaceable>root_password</replaceable>> | |
3516 | </programlisting></para> | |
3517 | </listitem> | |
3518 | ||
3519 | <listitem> | |
3520 | <para>Issue the <emphasis role="bold">fs messages</emphasis> command, using the <emphasis role="bold">-show</emphasis> | |
3521 | argument to specify the type of messages to be displayed. <programlisting> | |
3522 | # <emphasis role="bold">fs messages -show</emphasis> <<emphasis role="bold">user</emphasis>|<emphasis role="bold">console</emphasis>|<emphasis | |
3523 | role="bold">all</emphasis>|<emphasis role="bold">none</emphasis>> | |
3524 | </programlisting></para> | |
3525 | ||
3526 | <para>where <variablelist> | |
3527 | <varlistentry> | |
3528 | <term><emphasis role="bold">me</emphasis></term> | |
3529 | ||
3530 | <listitem> | |
3531 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">messages</emphasis>.</para> | |
3532 | </listitem> | |
3533 | </varlistentry> | |
3534 | ||
3535 | <varlistentry> | |
3536 | <term><emphasis role="bold">-show</emphasis></term> | |
3537 | ||
3538 | <listitem> | |
3539 | <para>Specifies the types of messages to display. Choose one of the following values: <variablelist> | |
3540 | <varlistentry> | |
3541 | <term><emphasis role="bold">user</emphasis></term> | |
3542 | ||
3543 | <listitem> | |
3544 | <para>Sends user messages to user screens.</para> | |
3545 | </listitem> | |
3546 | </varlistentry> | |
3547 | ||
3548 | <varlistentry> | |
3549 | <term><emphasis role="bold">console</emphasis></term> | |
3550 | ||
3551 | <listitem> | |
3552 | <para>Sends console messages to the console.</para> | |
3553 | </listitem> | |
3554 | </varlistentry> | |
3555 | ||
3556 | <varlistentry> | |
3557 | <term><emphasis role="bold">all</emphasis></term> | |
3558 | ||
3559 | <listitem> | |
3560 | <para>Sends user messages to user screens and console messages to the console (the default if the | |
3561 | <emphasis role="bold">-show</emphasis> argument is omitted).</para> | |
3562 | </listitem> | |
3563 | </varlistentry> | |
3564 | ||
3565 | <varlistentry> | |
3566 | <term><emphasis role="bold">none</emphasis></term> | |
3567 | ||
3568 | <listitem> | |
3569 | <para>Disables messages completely.</para> | |
3570 | </listitem> | |
3571 | </varlistentry> | |
3572 | </variablelist></para> | |
3573 | </listitem> | |
3574 | </varlistentry> | |
3575 | </variablelist></para> | |
3576 | </listitem> | |
3577 | </orderedlist> | |
3578 | </sect2> | |
3579 | </sect1> | |
3580 | ||
3581 | <sect1 id="HDRWQ417"> | |
3582 | <title>Displaying and Setting the System Type Name</title> | |
3583 | ||
3584 | <indexterm> | |
3585 | <primary>Cache Manager</primary> | |
3586 | ||
3587 | <secondary>system type name stored in kernel memory</secondary> | |
3588 | </indexterm> | |
3589 | ||
3590 | <indexterm> | |
3591 | <primary>client machine</primary> | |
3592 | ||
3593 | <secondary>system type name stored in Cache Manager memory</secondary> | |
3594 | </indexterm> | |
3595 | ||
3596 | <para>The Cache Manager stores the system type name of the local client machine in kernel memory. It reads in the default value | |
3597 | from a hardcoded definition in the AFS client software.</para> | |
3598 | ||
3599 | <para>The Cache Manager uses the system name as a substitute for the @sys variable in AFS pathnames. The variable is useful when | |
3600 | creating a symbolic link from the local disk to an AFS directory that houses binaries for the client machine's system type. | |
3601 | Because the @sys variable automatically steers the Cache Manager to the appropriate directory, you can create the same symbolic | |
3602 | link on client machines of different system types. | |
3603 | The link also remains valid | |
3604 | when you upgrade the machine to a new system type.</para> | |
3605 | ||
3606 | <para>Configuration is simplest if you use the system type names that AFS assigns. For a list, see the <emphasis>OpenAFS Release | |
3607 | Notes</emphasis>.</para> | |
3608 | ||
3609 | <para>To display the system name stored in kernel memory, use the <emphasis role="bold">sys</emphasis> or <emphasis | |
3610 | role="bold">fs sysname</emphasis> command. To change the name, add the latter command's <emphasis role="bold">-newsys</emphasis> | |
3611 | argument. <indexterm> | |
3612 | <primary>fs commands</primary> | |
3613 | ||
3614 | <secondary>sysname</secondary> | |
3615 | </indexterm> <indexterm> | |
3616 | <primary>commands</primary> | |
3617 | ||
3618 | <secondary>fs sysname</secondary> | |
3619 | </indexterm> <indexterm> | |
3620 | <primary>sys command</primary> | |
3621 | </indexterm> <indexterm> | |
3622 | <primary>commands</primary> | |
3623 | ||
3624 | <secondary>sys</secondary> | |
3625 | </indexterm></para> | |
3626 | ||
3627 | <sect2 id="Header_484"> | |
3628 | <title>To display the system type name</title> | |
3629 | ||
3630 | <orderedlist> | |
3631 | <listitem> | |
3632 | <para>Issue the <emphasis role="bold">fs sysname</emphasis> or <emphasis role="bold">sys</emphasis> command. | |
3633 | <programlisting> | |
3634 | % <emphasis role="bold">fs sysname</emphasis> | |
3635 | % <emphasis role="bold">sys</emphasis> | |
3636 | </programlisting></para> | |
3637 | </listitem> | |
3638 | </orderedlist> | |
3639 | ||
3640 | <para>The output of the <emphasis role="bold">fs sysname</emphasis> command has the following format:</para> | |
3641 | ||
3642 | <programlisting> | |
3643 | Current sysname is 'system_name' | |
3644 | </programlisting> | |
3645 | ||
3646 | <para>The <emphasis role="bold">sys</emphasis> command displays the system_name string with no other text.</para> | |
3647 | </sect2> | |
3648 | ||
3649 | <sect2 id="Header_485"> | |
3650 | <title>To change the system type name</title> | |
3651 | ||
3652 | <orderedlist> | |
3653 | <listitem> | |
3654 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3655 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3656 | % <emphasis role="bold">su root</emphasis> | |
3657 | Password: <<replaceable>root_password</replaceable>> | |
3658 | </programlisting></para> | |
3659 | </listitem> | |
3660 | ||
3661 | <listitem> | |
3662 | <para>Issue the <emphasis role="bold">fs sysname</emphasis> command, using the <emphasis role="bold">-newsys</emphasis> | |
3663 | argument to specify the new name. <programlisting> | |
3664 | # <emphasis role="bold">fs sysname</emphasis> <<replaceable>new sysname</replaceable>> | |
3665 | </programlisting></para> | |
3666 | ||
3667 | <para>where <variablelist> | |
3668 | <varlistentry> | |
3669 | <term><emphasis role="bold">sys</emphasis></term> | |
3670 | ||
3671 | <listitem> | |
3672 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">sysname</emphasis>.</para> | |
3673 | </listitem> | |
3674 | </varlistentry> | |
3675 | ||
3676 | <varlistentry> | |
3677 | <term><emphasis role="bold">new sysname</emphasis></term> | |
3678 | ||
3679 | <listitem> | |
3680 | <para>Specifies the new system type name.</para> | |
3681 | </listitem> | |
3682 | </varlistentry> | |
3683 | </variablelist></para> | |
3684 | </listitem> | |
3685 | </orderedlist> | |
3686 | </sect2> | |
3687 | </sect1> | |
3688 | ||
3689 | <sect1 id="HDRWQ418"> | |
3690 | <title>Enabling Asynchronous Writes</title> | |
3691 | ||
3692 | <indexterm> | |
3693 | <primary>asynchrony</primary> | |
3694 | ||
3695 | <secondary>enabling for Cache Manager write operations</secondary> | |
3696 | </indexterm> | |
3697 | ||
3698 | <indexterm> | |
3699 | <primary>synchrony</primary> | |
3700 | ||
3701 | <secondary>controlling for Cache Manager write operations</secondary> | |
3702 | </indexterm> | |
3703 | ||
3704 | <indexterm> | |
3705 | <primary>Cache Manager</primary> | |
3706 | ||
3707 | <secondary>enabling asynchrony for write operations</secondary> | |
3708 | </indexterm> | |
3709 | ||
3710 | <para>By default, the Cache Manager writes all data to the File Server immediately and synchronously when an application program | |
3711 | closes a file. That is, the <emphasis role="bold">close</emphasis> system call does not return until the Cache Manager has | |
3712 | actually written all of the cached data from the file back to the File Server. You can enable the Cache Manager to write files | |
3713 | asynchronously by specifying the number of kilobytes of a file that can remain to be written to the File Server when the Cache | |
3714 | Manager returns control to the application.</para> | |
3715 | ||
3716 | <para>Enabling asynchronous writes can be helpful to users who commonly work with very large files, because it usually means | |
3717 | that the application appears to perform faster. However, it introduces some complications. It is best not to enable asynchronous | |
3718 | writes unless the machine's users are sophisticated enough to understand the potential problems and how to avoid them. The | |
3719 | complications include the following: <itemizedlist> | |
3720 | <listitem> | |
3721 | <para>In most cases, the Cache Manager returns control to applications earlier than it does by default, but it is not | |
3722 | guaranteed to do so. Users cannot always expect faster performance.</para> | |
3723 | </listitem> | |
3724 | ||
3725 | <listitem> | |
3726 | <para>If an asynchronous write fails, there is no way to notify the application, because the <emphasis | |
3727 | role="bold">close</emphasis> system call has already returned with a code indicating success.</para> | |
3728 | </listitem> | |
3729 | ||
3730 | <listitem> | |
3731 | <para>Asynchronous writing increases the possibility that the user fails to notice when a write operation makes a volume | |
3732 | exceed its quota. As always, the portion of the file that exceeds the quota is lost, as indicated by a message like the | |
3733 | following: <programlisting> | |
3734 | No space left on device | |
3735 | </programlisting></para> | |
3736 | ||
3737 | <para>To avoid losing data because of insufficient quota, before closing a file users must verify that the volume housing | |
3738 | the file has enough free space to accommodate it.</para> | |
3739 | </listitem> | |
3740 | </itemizedlist></para> | |
3741 | ||
3742 | <para>When you enable asynchronous writes by issuing the <emphasis role="bold">fs storebehind</emphasis> command, you set the | |
3743 | number of kilobytes of a file that can still remain to be written to the File Server when the Cache Manager returns control to | |
3744 | the application program. You can apply the setting either to all files manipulated by applications running on the machine, or | |
3745 | only to certain files: <itemizedlist> | |
3746 | <listitem> | |
3747 | <para>The setting that applies to all files is called the <emphasis>default store asynchrony</emphasis> for the machine, | |
3748 | and persists until the machine reboots. If, for example, you set the default store asynchrony to 10 KB, it means that when | |
3749 | an application closes a file, the Cache Manager can return control to the application as soon as no more than 10 KB of a | |
3750 | file that the application has closed remain to be written to the File Server.</para> | |
3751 | </listitem> | |
3752 | ||
3753 | <listitem> | |
3754 | <para>The setting for an individual file overrides the default store asynchrony and persists as long as there is an entry | |
3755 | for the file in the internal table that the Cache Manager uses to track information about files. In general, such an entry | |
3756 | persists at least until an application closes the file or exits completely, but the Cache Manager is free to recycle the | |
3757 | entry if the file is inactive and it needs to free up slots in the table. To be sure the entry exists in the table, issue | |
3758 | the <emphasis role="bold">fs storebehind</emphasis> command shortly before closing the file.</para> | |
3759 | </listitem> | |
3760 | </itemizedlist></para> | |
3761 | ||
3762 | <indexterm> | |
3763 | <primary>fs commands</primary> | |
3764 | ||
3765 | <secondary>storebehind</secondary> | |
3766 | ||
3767 | <tertiary>setting default asynchrony</tertiary> | |
3768 | </indexterm> | |
3769 | ||
3770 | <indexterm> | |
3771 | <primary>commands</primary> | |
3772 | ||
3773 | <secondary>fs storebehind</secondary> | |
3774 | ||
3775 | <tertiary>setting default asynchrony</tertiary> | |
3776 | </indexterm> | |
3777 | ||
3778 | <sect2 id="Header_487"> | |
3779 | <title>To set the default store asynchrony</title> | |
3780 | ||
3781 | <orderedlist> | |
3782 | <listitem> | |
3783 | <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing | |
3784 | the <emphasis role="bold">su</emphasis> command. <programlisting> | |
3785 | % <emphasis role="bold">su root</emphasis> | |
3786 | Password: <<replaceable>root_password</replaceable>> | |
3787 | </programlisting></para> | |
3788 | </listitem> | |
3789 | ||
3790 | <listitem> | |
3791 | <para>Issue the <emphasis role="bold">fs storebehind</emphasis> command with the <emphasis | |
3792 | role="bold">-allfiles</emphasis> argument. <programlisting> | |
3793 | # <emphasis role="bold">fs storebehind -allfiles</emphasis> <<replaceable>new default (KB)</replaceable>> [<emphasis | |
3794 | role="bold">-verbose</emphasis>] | |
3795 | </programlisting></para> | |
3796 | ||
3797 | <para>where <variablelist> | |
3798 | <varlistentry> | |
3799 | <term><emphasis role="bold">st</emphasis></term> | |
3800 | ||
3801 | <listitem> | |
3802 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">storebehind</emphasis>.</para> | |
3803 | </listitem> | |
3804 | </varlistentry> | |
3805 | ||
3806 | <varlistentry> | |
3807 | <term><emphasis role="bold">-allfiles</emphasis></term> | |
3808 | ||
3809 | <listitem> | |
3810 | <para>Sets the number of kilobytes of data that can remain to be written to the File Server when the Cache Manager | |
3811 | returns control to the application that closed a file.</para> | |
3812 | </listitem> | |
3813 | </varlistentry> | |
3814 | ||
3815 | <varlistentry> | |
3816 | <term><emphasis role="bold">-verbose</emphasis></term> | |
3817 | ||
3818 | <listitem> | |
3819 | <para>Produces a message that confirms the new setting.</para> | |
3820 | </listitem> | |
3821 | </varlistentry> | |
3822 | </variablelist></para> | |
3823 | </listitem> | |
3824 | </orderedlist> | |
3825 | ||
3826 | <indexterm> | |
3827 | <primary>fs commands</primary> | |
3828 | ||
3829 | <secondary>storebehind</secondary> | |
3830 | ||
3831 | <tertiary>setting asynchrony for specific files</tertiary> | |
3832 | </indexterm> | |
3833 | ||
3834 | <indexterm> | |
3835 | <primary>commands</primary> | |
3836 | ||
3837 | <secondary>fs storebehind</secondary> | |
3838 | ||
3839 | <tertiary>setting asynchrony for specific files</tertiary> | |
3840 | </indexterm> | |
3841 | </sect2> | |
3842 | ||
3843 | <sect2 id="Header_488"> | |
3844 | <title>To set the store asynchrony for one or more files</title> | |
3845 | ||
3846 | <orderedlist> | |
3847 | <listitem> | |
3848 | <para>Verify that you have the <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) permission on | |
3849 | the access control list (ACL) of each file for which you are setting the store asynchrony, by issuing the <emphasis | |
3850 | role="bold">fs listacl</emphasis> command, which is described fully in <link linkend="HDRWQ572">Displaying ACLs</link>. | |
3851 | <programlisting> | |
3852 | % <emphasis role="bold">fs listacl</emphasis> dir/file path | |
3853 | </programlisting></para> | |
3854 | ||
3855 | <para>Alternatively, become the local superuser <emphasis role="bold">root</emphasis> on the client machine, if you are | |
3856 | not already, by issuing the <emphasis role="bold">su</emphasis> command.</para> | |
3857 | ||
3858 | <programlisting> | |
3859 | % <emphasis role="bold">su root</emphasis> | |
3860 | Password: <<replaceable>root_password</replaceable>> | |
3861 | </programlisting> | |
3862 | </listitem> | |
3863 | ||
3864 | <listitem> | |
3865 | <para>Issue the <emphasis role="bold">fs storebehind</emphasis> command with the <emphasis role="bold">-kbytes</emphasis> | |
3866 | and <emphasis role="bold">-files</emphasis> arguments. <programlisting> | |
3867 | # <emphasis role="bold">fs storebehind -kbytes</emphasis> <<replaceable>asynchrony for specified names</replaceable>> \ | |
3868 | <emphasis role="bold">-files</emphasis> <<replaceable>specific pathnames</replaceable>>+ \ | |
3869 | [<emphasis role="bold">-verbose</emphasis>] | |
3870 | </programlisting></para> | |
3871 | ||
3872 | <para>where <variablelist> | |
3873 | <varlistentry> | |
3874 | <term><emphasis role="bold">st</emphasis></term> | |
3875 | ||
3876 | <listitem> | |
3877 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">storebehind</emphasis>.</para> | |
3878 | </listitem> | |
3879 | </varlistentry> | |
3880 | ||
3881 | <varlistentry> | |
3882 | <term><emphasis role="bold">-kbytes</emphasis></term> | |
3883 | ||
3884 | <listitem> | |
3885 | <para>Sets the number of kilobytes of data that can remain to be written to the File Server when the Cache Manager | |
3886 | returns control to the application that closed a file named by the <emphasis role="bold">-files</emphasis> | |
3887 | argument.</para> | |
3888 | </listitem> | |
3889 | </varlistentry> | |
3890 | ||
3891 | <varlistentry> | |
3892 | <term><emphasis role="bold">-files</emphasis></term> | |
3893 | ||
3894 | <listitem> | |
3895 | <para>Specifies each file for which to set a store asynchrony that overrides the default. Partial pathnames are | |
3896 | interpreted relative to the current working directory.</para> | |
3897 | </listitem> | |
3898 | </varlistentry> | |
3899 | ||
3900 | <varlistentry> | |
3901 | <term><emphasis role="bold">-verbose</emphasis></term> | |
3902 | ||
3903 | <listitem> | |
3904 | <para>Produces a message that confirms that new setting.</para> | |
3905 | </listitem> | |
3906 | </varlistentry> | |
3907 | </variablelist></para> | |
3908 | </listitem> | |
3909 | </orderedlist> | |
3910 | ||
3911 | <indexterm> | |
3912 | <primary>fs commands</primary> | |
3913 | ||
3914 | <secondary>storebehind</secondary> | |
3915 | ||
3916 | <tertiary>displaying default asynchrony</tertiary> | |
3917 | </indexterm> | |
3918 | ||
3919 | <indexterm> | |
3920 | <primary>commands</primary> | |
3921 | ||
3922 | <secondary>fs storebehind</secondary> | |
3923 | ||
3924 | <tertiary>displaying default asynchrony</tertiary> | |
3925 | </indexterm> | |
3926 | </sect2> | |
3927 | ||
3928 | <sect2 id="Header_489"> | |
3929 | <title>To display the default store asynchrony</title> | |
3930 | ||
3931 | <orderedlist> | |
3932 | <listitem> | |
3933 | <para>Issue the <emphasis role="bold">fs storebehind</emphasis> command with no arguments, or with the <emphasis | |
3934 | role="bold">-verbose</emphasis> flag only. <programlisting> | |
3935 | % <emphasis role="bold">fs storebehind</emphasis> [<emphasis role="bold">-verbose</emphasis>] | |
3936 | </programlisting></para> | |
3937 | ||
3938 | <para>where <variablelist> | |
3939 | <varlistentry> | |
3940 | <term><emphasis role="bold">st</emphasis></term> | |
3941 | ||
3942 | <listitem> | |
3943 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">storebehind</emphasis>.</para> | |
3944 | </listitem> | |
3945 | </varlistentry> | |
3946 | ||
3947 | <varlistentry> | |
3948 | <term><emphasis role="bold">-verbose</emphasis></term> | |
3949 | ||
3950 | <listitem> | |
3951 | <para>Produces output that reports the default store asynchrony.</para> | |
3952 | </listitem> | |
3953 | </varlistentry> | |
3954 | </variablelist></para> | |
3955 | </listitem> | |
3956 | </orderedlist> | |
3957 | ||
3958 | <indexterm> | |
3959 | <primary>fs commands</primary> | |
3960 | ||
3961 | <secondary>storebehind</secondary> | |
3962 | ||
3963 | <tertiary>displaying asynchrony for specific files</tertiary> | |
3964 | </indexterm> | |
3965 | ||
3966 | <indexterm> | |
3967 | <primary>commands</primary> | |
3968 | ||
3969 | <secondary>fs storebehind</secondary> | |
3970 | ||
3971 | <tertiary>displaying asynchrony for specific files</tertiary> | |
3972 | </indexterm> | |
3973 | </sect2> | |
3974 | ||
3975 | <sect2 id="Header_490"> | |
3976 | <title>To display the store asynchrony for one or more files</title> | |
3977 | ||
3978 | <orderedlist> | |
3979 | <listitem> | |
3980 | <para>Issue the <emphasis role="bold">fs storebehind</emphasis> command with the <emphasis role="bold">-files</emphasis> | |
3981 | argument only. <programlisting> | |
3982 | % <emphasis role="bold">fs storebehind</emphasis> <emphasis role="bold">-files</emphasis> <<replaceable>specific pathnames</replaceable>>+ | |
3983 | </programlisting></para> | |
3984 | ||
3985 | <para>where <variablelist> | |
3986 | <varlistentry> | |
3987 | <term><emphasis role="bold">st</emphasis></term> | |
3988 | ||
3989 | <listitem> | |
3990 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">storebehind</emphasis>.</para> | |
3991 | </listitem> | |
3992 | </varlistentry> | |
3993 | ||
3994 | <varlistentry> | |
3995 | <term><emphasis role="bold">-files</emphasis></term> | |
3996 | ||
3997 | <listitem> | |
3998 | <para>Specifies each file for which to display the store asynchrony. Partial pathnames are interpreted relative to | |
3999 | the current working directory.</para> | |
4000 | </listitem> | |
4001 | </varlistentry> | |
4002 | </variablelist></para> | |
4003 | </listitem> | |
4004 | </orderedlist> | |
4005 | ||
4006 | <para>The output lists each file separately. If a value has previously been set for the specified files, the output reports | |
4007 | the following:</para> | |
4008 | ||
4009 | <programlisting> | |
4010 | Will store up to y kbytes of file asynchronously. | |
4011 | Default store asynchrony is x kbytes. | |
4012 | </programlisting> | |
4013 | ||
4014 | <para>If the default store asynchrony applies to a file (because you have not set a <emphasis role="bold">-kbytes</emphasis> | |
4015 | value for it), the output reports the following:</para> | |
4016 | ||
4017 | <programlisting> | |
4018 | Will store file according to default. | |
4019 | Default store asynchrony is x kbytes. | |
4020 | </programlisting> | |
4021 | </sect2> | |
4022 | </sect1> | |
4023 | </chapter> | |
4024 |