1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5 >Administering Client Machines and the Cache Manager</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
10 TITLE="AFS Administration Guide"
11 HREF="book1.html"><LINK
13 TITLE="Managing Client Machines"
14 HREF="p21471.html"><LINK
16 TITLE="Managing Client Machines"
17 HREF="p21471.html"><LINK
19 TITLE="Configuring Client Machines with the package Program"
20 HREF="c23832.html"></HEAD
31 SUMMARY="Header navigation table"
40 >AFS Administration Guide: Version 3.6</TH
77 >Chapter 10. Administering Client Machines and the Cache Manager</H1
79 >This chapter describes how to administer an AFS client machine, which is any machine from which users can access the AFS
80 filespace and communicate with AFS server processes. (A client machine can simultaneously function as an AFS server machine if
81 appropriately configured.) An AFS client machine has the following characteristics: <UL
84 >The kernel includes the set of modifications, commonly referred to as the <SPAN
91 enable access to AFS files and directories. You can configure many of the Cache Manager's features to suit your users'
93 HREF="c21473.html#HDRWQ390"
94 >Overview of Cache Manager Customization</A
105 > directory on the local disk stores several configuration files. See
107 HREF="c21473.html#HDRWQ392"
108 >Configuration Files in the /usr/vice/etc Directory</A
113 >A cache stores temporary copies of data fetched from AFS file server machines, either in machine memory or on a
114 devoted local disk partition. See <A
115 HREF="c21473.html#HDRWQ394"
116 >Determining the Cache Type, Size, and Location</A
118 HREF="c21473.html#HDRWQ402"
119 >Setting Other Cache Parameters with the afsd program</A
125 >To learn how to install the client functionality on a machine, see the <SPAN
129 >IBM AFS Quick Beginnings</I
138 >Summary of Instructions</A
141 >This chapter explains how to perform the following tasks by using the indicated commands:</P
143 CLASS="informaltable"
156 >Display cache size set at reboot</TD
162 >cat /usr/vice/etc/cacheinfo</B
168 >Display current cache size and usage</TD
180 >Change disk cache size without rebooting</TD
192 >Initialize Cache Manager</TD
204 >Display contents of <SPAN
216 >cat /usr/vice/etc/CellServDB</B
222 >Display list of database server machines from kernel memory</TD
234 >Change list of database server machines in kernel memory</TD
246 >Check cell's status regarding setuid</TD
258 >Set cell's status regarding setuid</TD
270 >Set server probe interval</TD
276 >fs checkservers -interval</B
282 >Display machine's cell membership</TD
288 >cat /usr/vice/etc/ThisCell</B
294 >Change machine's cell membership</TD
300 >/usr/vice/etc/ThisCell</B
306 >Flush cached file/directory</TD
318 >Flush everything cached from a volume</TD
330 >Update volume-to-mount-point mappings</TD
342 >Display Cache Manager's server preference ranks</TD
348 >fs getserverprefs</B
354 >Set Cache Manager's server preference ranks</TD
360 >fs setserverprefs</B
366 >Display client machine addresses to register</TD
372 >fs getclientaddrs</B
378 >Set client machine addresses to register</TD
384 >fs setclientaddrs</B
390 >Control the display of warning and status messages</TD
402 >Display and change machine's system type</TD
414 >Enable asynchronous writes</TD
434 >Overview of Cache Manager Customization</A
437 >An AFS client machine's kernel includes a set of modifications, commonly referred to as the <SPAN
444 >, that enable access to AFS files and directories and communications with AFS server processes. It is common
445 to speak of the Cache Manager as a process or program, and in regular usage it appears to function like one. When configuring
446 it, though, it is helpful to keep in mind that this usage is not strictly accurate.</P
448 >The Cache Manager mainly fetches files on behalf of application programs running on the machine. When an application
449 requests an AFS file, the Cache Manager contacts the Volume Location (VL) Server to obtain a list of the file server machines
450 that house the volume containing the file. The Cache Manager then translates the application program's system call requests into
451 remote procedure calls (RPCs) to the File Server running on the appropriate machine. When the File Server delivers the file, the
452 Cache Manager stores it in a local <SPAN
458 > before delivering it to the application program.</P
460 >The File Server delivers a data structure called a <SPAN
466 > along with the file. (To be precise, it
467 delivers a callback for each file fetched from a read/write volume, and a single callback for all data fetched from a read-only
468 volume.) A valid callback indicates that the Cache Manager's cached copy of a file matches the central copy maintained by the
469 File Server. If an application on another AFS client machine changes the central copy, the File Server breaks the callback, and
470 the Cache Manager must retrieve the new version when an application program on its machine next requests data from the file. As
471 long as the callback is unbroken, however, the Cache Manager can continue to provide the cached version of the file to
472 applications on its machine, which eliminates unnecessary network traffic.</P
474 >The indicated sections of this chapter explain how to configure and customize the following Cache Manager features. All
475 but the first (choosing disk or memory cache) are optional, because AFS sets suitable defaults for them. <UL
482 >disk or memory cache</I
484 >. The AFS Cache Manager can use machine memory for caching instead of space
485 on the local disk. Deciding which to use is the most basic configuration decision you must make. See <A
486 HREF="c21473.html#HDRWQ394"
487 >Determining the Cache Type, Size, and Location</A
498 >. Cache size probably has the most direct influence on client machine performance. It
499 determines how often the Cache Manager must contact the File Server across the network or discard cached data to make room
500 for newly requested files, both of which affect how quickly the Cache Manager delivers files to users. See <A
501 HREF="c21473.html#HDRWQ394"
502 >Determining the Cache Type, Size, and Location</A
513 >. For a disk cache, you can alter the conventional cache directory location
520 >) to take advantage of greater space availability on other disks on the
521 machine. A larger cache can result in faster file delivery. See <A
522 HREF="c21473.html#HDRWQ394"
523 >Determining the Cache Type, Size,
533 >chunk size and number</I
541 > program, which initializes the
542 Cache Manager, allows you to control the size and number of chunks into which a cache is divided, plus related parameters.
543 Setting these parameters is optional, because there are reasonable defaults, but it provides precise control. The AFS
544 distribution includes configuration scripts that set Cache Manager parameters to values that are reasonable for different
545 configurations and usage patterns. See <A
546 HREF="c21473.html#HDRWQ402"
547 >Setting Other Cache Parameters with the afsd
557 >knowledge of database server machines</I
559 >. Enable access to a cell's AFS filespace and other
560 services by listing the cell's database server machines in the <SPAN
564 >/usr/vice/etc/CellServDB</B
567 file on the local disk. See <A
568 HREF="c21473.html#HDRWQ406"
569 >Maintaining Knowledge of Database Server Machines</A
580 >. You can control whether the Cache Manager allows programs from a cell to
581 execute with setuid permission. See <A
582 HREF="c21473.html#HDRWQ409"
583 >Determining if a Client Can Run Setuid
595 >. Each client belongs to a one cell defined by the local <SPAN
599 >/usr/vice/etc/ThisCell</B
601 > file. Cell membership determines the default cell in which the machine's
602 users are authenticated and in which AFS commands run. See <A
603 HREF="c21473.html#HDRWQ411"
604 >Setting a Client Machine's Cell
614 >cached file version</I
616 >. AFS's system of callbacks normally guarantees that the Cache Manager has
617 the most current versions of files and directories possible. Nevertheless, you can force the Cache Manager to fetch the
618 most current version of a file from the File Server if you suspect that the cache contains an outdated version. See <A
619 HREF="c21473.html#HDRWQ412"
620 >Forcing the Update of Cached Data</A
629 >File Server and Volume Location Server preferences</I
631 >. The Cache Manager sets numerical preference
632 ranks for the interfaces on file server machines and Volume Server (VL) machines. The ranks determine which interface the
633 Cache Manager first attempts to use when fetching data from a volume or from the Volume Location Database (VLDB). The
634 Cache Manager sets default ranks as it initializes, basing them on its network proximity to each interface, but you can
635 modify the preference ranks if you wish. See <A
636 HREF="c21473.html#HDRWQ414"
637 >Maintaining Server Preference Ranks</A
646 >interfaces registered with the File Server</I
648 >. If the Cache Manager is multihomed (has multiple
649 interface addresses), you can control which of them it registers for File Servers to use when they initiate RPCs to the
650 client machine. See <A
651 HREF="c21473.html#HDRWQ415"
652 >Managing Multihomed Client Machines</A
661 >display of information messages</I
663 >. By default, the Cache Manager sends basic error and
664 informational messages to the client machine's console and to command shells. You can disable the messaging. See <A
665 HREF="c21473.html#HDRWQ416"
666 >Controlling the Display of Warning and Informational Messages</A
677 >. The Cache Manager records the local machine's AFS system type in kernel memory,
678 and substitutes the value for the @sys variable in pathnames. See <A
679 HREF="c21473.html#HDRWQ417"
680 >Displaying and Setting the
692 >. By default, the Cache Manager writes all data to the File Server immediately
693 and synchronously when an application program closes a file. You can enable asynchronous writes, either for an individual
694 file, or all files that the Cache Manager handles, and set how much data remains to be written when the Cache Manager
695 returns control to the closing application. See <A
696 HREF="c21473.html#HDRWQ418"
697 >Enabling Asynchronous Writes</A
703 >You must make all configuration changes on the client machine itself (at the console or over a direct connection such as a
710 > connection). You cannot configure the Cache Manager remotely. You must be logged in as
711 the local superuser <SPAN
717 > to issue some commands, whereas others require no privilege. All files
718 mentioned in this chapter must actually reside on the local disk of each AFS client machine (they cannot, for example, be
719 symbolic links to files in AFS).</P
727 > program can simplify other aspects of client machine configuration,
728 including those normally set in the machine's AFS initialization file. See <A
730 >Configuring Client Machines
731 with the package Program</A
740 >Configuration and Cache-Related Files on the Local Disk</A
743 >This section briefly describes the client configuration files that must reside in the local <SPAN
749 > directory on every client machine. If the machine uses a disk cache, there must be a
750 partition devoted to cache files; by convention, it is mounted at the <SPAN
763 >Note for Windows users:</B
765 > Some files described in this document possibly do not exist on
766 machines that run a Windows operating system. Also, Windows uses a backslash (<SPAN
779 >) to separate the elements in a pathname.</P
786 >Configuration Files in the /usr/vice/etc Directory</A
795 > directory on a client machine's local disk must contain certain
796 configuration files for the Cache Manager to function properly. They control the most basic aspects of Cache Manager
799 >If it is important that the client machines in your cell perform uniformly, it is most efficient to update these files
800 from a central source. The following descriptions include pointers to sections that discuss how best to maintain the files.
814 >The binary file for the program that initializes the Cache Manager. It must run each time the machine reboots in
815 order for the machine to remain an AFS client machine. The program also initializes several daemons that improve Cache
816 Manager functioning, such as the process that handles callbacks. </P
828 >A one-line file that sets the cache's most basic configuration parameters: the local directory at which the
829 Cache Manager mounts the AFS filespace, the local disk directory to use as the cache, and how many kilobytes to
830 allocate to the cache.</P
836 >IBM AFS Quick Beginnings</I
838 > explains how to create this file as you install a client
839 machine. To change the cache size on a machine that uses a memory cache, edit the file and reboot the machine. On a
840 machine that uses a disk cache, you can change the cache size without rebooting by issuing the <SPAN
846 > command. For instructions, see <A
847 HREF="c21473.html#HDRWQ394"
848 >Determining the Cache
849 Type, Size, and Location</A
862 >This ASCII file names the database server machines in the local cell and in any foreign cell to which you want
863 to enable access from this machine. (Database server machines are the machines in a cell that run the Authentication,
864 Backup, Protection, and VL Server processes; see <A
865 HREF="c3025.html#HDRWQ92"
866 >Database Server Machines</A
869 >The Cache Manager must be able to reach a cell's database server machines to fetch files from its filespace.
870 Incorrect or missing information in the <SPAN
876 > file can slow or completely block
877 access. It is important to update the file whenever a cell's database server machines change.</P
885 > program initializes the Cache Manager, it loads the contents of the
886 file into kernel memory. The Cache Manager does not read the file between reboots, so to incorporate changes to the
887 file into kernel memory, you must reboot the machine. Alternatively, you can issue the <SPAN
894 > command to insert the changes directly into kernel memory without changing the file. It can also be
895 convenient to upgrade the file from a central source. For instructions, see <A
896 HREF="c21473.html#HDRWQ406"
898 Knowledge of Database Server Machines</A
907 > file on client machines is not the same as the one kept in the
914 > directory on server machines, which lists only the local cell's database
915 server machines. For instructions on maintaining the server <SPAN
923 HREF="c3025.html#HDRWQ118"
924 >Maintaining the Server CellServDB File</A
937 >This optional ASCII file lists one or more of the network interface addresses on the client machine. If it
938 exists when the Cache Manager initializes, the Cache Manager uses it as the basis for the list of interfaces that it
939 registers with File Servers. See <A
940 HREF="c21473.html#HDRWQ415"
941 >Managing Multihomed Client Machines</A
954 >This optional ASCII file lists one or more network interface addresses. If it exists when the Cache Manager
955 initializes, the Cache Manager removes the specified addresses from the list of interfaces that it registers with File
957 HREF="c21473.html#HDRWQ415"
958 >Managing Multihomed Client Machines</A
971 >This ASCII file contains a single line that specifies the complete domain-style name of the cell to which the
972 machine belongs. Examples are <SAMP
973 CLASS="computeroutput"
977 CLASS="computeroutput"
979 >. This value defines the default cell in which the machine's users become
980 authenticated, and in which the command interpreters (for example, the <SPAN
987 contact server processes.</P
993 >IBM AFS Quick Beginnings</I
995 > explains how to create this file as you install the AFS client
996 functionality. To learn about changing a client machine's cell membership, see <A
997 HREF="c21473.html#HDRWQ411"
999 Client Machine's Cell Membership</A
1006 >In addition to these files, the <SPAN
1012 > directory also sometimes contains the
1013 following types of files and subdirectories: <UL
1016 >The AFS initialization script, called <SPAN
1022 > on many system types. In the
1023 conventional configuration specified by the <SPAN
1027 >IBM AFS Quick Beginnings</I
1029 >, it is a symbolic link to the
1030 actual script kept in the same directory as other initialization files used by the operating system. </P
1034 >A subdirectory that houses AFS kernel library files used by a dynamic kernel loading program. </P
1038 >A subdirectory called <SPAN
1044 >, which houses the Cache Manager catalog file called
1051 >. The fstrace program uses the catalog file to translate operation codes into
1052 character strings, which makes the message in the trace log more readable. See <A
1053 HREF="c18360.html#HDRWQ342"
1055 fstrace Command Suite</A
1067 >Cache-Related Files</A
1070 >A client machine that uses a disk cache must have a local disk directory devoted to the cache. The conventional mount
1077 >, but you can use another partition that has more available
1080 >Do not delete or directly modify any of the files in the cache directory. Doing so can cause a kernel panic, from which
1081 the only way to recover is to reboot the machine. By default, only the local superuser <SPAN
1088 can read the files directly, by virtue of owning them.</P
1090 >A client machine that uses a memory cache keeps all of the information stored in these files in machine memory instead.
1092 CLASS="variablelist"
1104 >A binary-format file in which the Cache Manager tracks the contents of cache chunks (the <SPAN
1110 > files in the directory, described just following), including the file ID number (fID) and the
1111 data version number. </P
1123 >A binary-format file in which the Cache Manager records the mapping between mount points and the volumes from
1124 which it has fetched data. The Cache Manager uses the information when responding to the <SPAN
1130 > command, among others. </P
1142 >A cache chunk file, which expands to a maximum size (by default, 64 KB) to house data fetched from AFS files.
1149 >n files in the cache depends on the cache size among other factors.
1150 The n is the index assigned to each file; they are numbered sequentially, but the Cache Manager does not necessarily
1151 use them in order or contiguously. If an AFS file is larger than the maximum size for <SPAN
1157 >n files, the Cache Manager divides it across multiple <SPAN
1177 >Determining the Cache Type, Size, and Location</A
1180 >This section explains how to configure a memory or disk cache, how to display and set the size of either type of cache,
1181 and how to set the location of the cache directory for a disk cache. </P
1183 >The Cache Manager uses a disk cache by default, and it is the preferred type of caching. To configure a memory cache,
1197 normally invoked in the machine's AFS initialization file. If configured to use a memory cache, the Cache Manager does no disk
1198 caching, even if the machine has a disk.</P
1205 >Choosing the Cache Size</A
1208 >Cache size influences the performance of a client machine more directly than perhaps any other cache parameter. The
1209 larger the cache, the faster the Cache Manager is likely to deliver files to users. A small cache can impair performance
1210 because it increases the frequency at which the Cache Manager must discard cached data to make room for newly requested data.
1211 When an application asks for data that has been discarded, the Cache Manager must request it from the File Server, and
1212 fetching data across the network is almost always slower than fetching it from the local disk. The Cache Manager never
1213 discards data from a file that has been modified locally but not yet stored back to the File Server. If the cache is very
1214 small, the Cache Manager possible cannot find any data to discard. For more information about the algorithm it uses when
1215 discarding cached data, see <A
1216 HREF="c21473.html#HDRWQ401"
1217 >How the Cache Manager Chooses Data to Discard</A
1220 >The amount of disk or memory you devote to caching depends on several factors. The amount of space available in memory
1221 or on the partition housing the disk cache directory imposes an absolute limit. In addition, you cannot allocate more than 95%
1222 of the space available on the cache directory's partition to a disk cache. The <SPAN
1229 exits without starting the Cache Manager and prints an appropriate message to the standard output stream if you violate this
1230 restriction. For a memory cache, you must leave enough memory for other processes and applications to run. If you try to
1231 allocate more memory than is actually available, the <SPAN
1237 > program exits without initializing
1238 the Cache Manager and produces the following message on the standard output stream:</P
1240 CLASS="programlisting"
1241 > afsd: memCache allocation failure at number KB
1244 >where number is how many kilobytes were allocated just before the failure.</P
1246 >Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
1247 machine, the size of the files with which they usually work, and (for a memory cache) the number of processes that usually run
1248 on the machine. The higher the demand from these factors, the larger the cache needs to be to maintain good
1251 >Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better
1252 with a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance
1253 depends on the factors mentioned previously, and is difficult to predict.</P
1255 >Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
1256 unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
1257 memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can
1258 use a smaller memory cache.</P
1260 >AFS imposes an absolute limit on cache size in some versions. See the <SPAN
1264 >IBM AFS Release Notes</I
1267 version you are using.</P
1275 >Displaying and Setting the Cache Size and Location</A
1278 >The Cache Manager determines how big to make the cache by reading the <SPAN
1282 >/usr/vice/etc/cacheinfo</B
1284 > file as it initializes. As directed in the <SPAN
1291 >, you must create the file before running the <SPAN
1298 also defines the directory on which to mount AFS (by convention, <SPAN
1304 >), and the local disk
1305 directory to use for a cache directory.</P
1307 >To change any of the values in the file, log in as the local superuser <SPAN
1314 reboot the machine to have the new value take effect. For instructions, see <A
1315 HREF="c21473.html#HDRWQ398"
1316 >To edit the cacheinfo
1320 >To change the cache size at reboot without editing the <SPAN
1333 > argument to the <SPAN
1339 > command; see the command's
1340 reference page in the IBM AFS Administration Reference.</P
1342 >For a disk cache, you can also use the <SPAN
1348 > command to reset the cache size
1349 without rebooting. The value you set persists until the next reboot, at which time the cache size returns to the value
1350 specified in the <SPAN
1356 > file or by the <SPAN
1369 > command. For instructions, see <A
1370 HREF="c21473.html#HDRWQ399"
1371 >To change the disk cache
1372 size without rebooting</A
1375 >To display the current cache size and the amount of space the Cache Manager is using at the moment, use the <SPAN
1379 >fs getcacheparms</B
1381 > command as detailed in <A
1382 HREF="c21473.html#HDRWQ397"
1383 >To display the current cache
1393 >To display the cache size set at reboot</A
1399 >Use a text editor or the <SPAN
1405 > command to display the contents of the <SPAN
1409 >/usr/vice/etc/cacheinfo</B
1412 CLASS="programlisting"
1417 >cat /usr/vice/etc/cacheinfo</B
1431 >To display the current cache size</A
1441 >fs getcacheparms</B
1443 > command on the client machine. <PRE
1444 CLASS="programlisting"
1449 >fs getcacheparms</B
1461 > is the shortest acceptable abbreviation of <SPAN
1469 >The output shows the number of kilobyte blocks the Cache Manager is using as a cache at the moment the command is
1470 issued, and the current size of the cache. For example:</P
1472 CLASS="programlisting"
1473 > AFS using 13709 of the cache's available 15000 1K byte blocks.
1484 >To edit the cacheinfo file</A
1490 >Become the local superuser <SPAN
1496 > on the machine, if you are not already, by issuing
1504 CLASS="programlisting"
1521 >Use a text editor to edit the <SPAN
1525 >/usr/vice/etc/cacheinfo</B
1527 > file, which has three fields,
1528 separated by colons: <UL
1531 >The first field names the local directory on which to mount the AFS filespace. The conventional location is
1542 >The second field defines the local disk directory to use for the disk cache. The conventional location is the
1549 > directory, but you can specify an alternate directory if another
1550 partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if
1551 the machine uses a memory cache.</P
1555 >The third field defines cache size as a number of kilobyte (1024-byte) blocks.</P
1560 >The following example mounts the AFS filespace at the <SPAN
1573 > as the cache directory, and sets cache size to 50,000 KB:</P
1575 CLASS="programlisting"
1580 >/afs:/usr/vice/cache:50000</B
1593 >To change the disk cache size without rebooting</A
1599 >Become the local superuser <SPAN
1605 > on the machine, if you are not already, by issuing
1613 CLASS="programlisting"
1639 > command to set a new disk cache
1648 >This command does not work for a memory cache.</P
1652 CLASS="programlisting"
1661 >size in 1K byte blocks (0 =</VAR
1666 CLASS="variablelist"
1678 >Is the shortest acceptable abbreviation of <SPAN
1691 >size in 1K byte blocks (0 => reset)</B
1696 >Sets the number of kilobyte blocks to be used for the cache. Specify a positive integer (<SPAN
1702 > equals 1 MB), or <SPAN
1708 > (zero) to reset the cache size to
1709 the value specified in the <SPAN
1729 >To reset the disk cache size to the default without rebooting</A
1735 >Become the local superuser <SPAN
1741 > on the machine, if you are not already, by issuing
1749 CLASS="programlisting"
1772 > command to reset the size of the local disk cache (the
1773 command does not work for a memory cache). Choose one of the two following options: <UL
1776 >To reset the cache size to the value specified in the local <SPAN
1783 specify the value <SPAN
1790 CLASS="programlisting"
1795 >fs setcachesize 0</B
1803 >To reset the cache size to the value set at the last reboot of the machine, include the <SPAN
1809 > flag. Unless the <SPAN
1815 > argument was used on the
1822 > command, this is also the value in the <SPAN
1829 CLASS="programlisting"
1834 >fs setcachesize -reset</B
1844 CLASS="variablelist"
1856 >Is the shortest acceptable abbreviation of <SPAN
1874 >Resets the disk cache size to the value in the third field of the <SPAN
1878 >/usr/vice/etc/cacheinfo</B
1892 >Resets the cache size to the value set at the last reboot.</P
1906 >How the Cache Manager Chooses Data to Discard</A
1909 >When the cache is full and application programs request more data from AFS, the Cache Manager must flush out cache
1910 chunks to make room for the data. The Cache Manager considers two factors: <OL
1914 >How recently an application last accessed the data.</P
1918 >Whether the chunk is <SPAN
1924 >. A dirty chunk contains changes to a file that have not yet been
1925 saved back to the permanent copy stored on a file server machine.</P
1930 >The Cache Manager first checks the least-recently used chunk. If it is not dirty, the Cache Manager discards the data in
1931 that chunk. If the chunk is dirty, the Cache Manager moves on to check the next least recently used chunk. It continues in
1932 this manner until it has created a sufficient number of empty chunks.</P
1934 >Chunks that contain data fetched from a read-only volume are by definition never dirty, so the Cache Manager can always
1935 discard them. Normally, the Cache Manager can also find chunks of data fetched from read/write volumes that are not dirty, but
1936 a small cache makes it difficult to find enough eligible data. If the Cache Manager cannot find any data to discard, it must
1937 return I/O errors to application programs that request more data from AFS. Application programs usually have a means for
1938 notifying the user of such errors, but not for revealing their cause.</P
1947 >Setting Other Cache Parameters with the afsd program</A
1950 >There are only three cache configuration parameters you must set: the mount directory for AFS, the location of the disk
1951 cache directory, and the cache size. They correspond to the three fields in the <SPAN
1955 >/usr/vice/etc/cacheinfo</B
1957 > file, as discussed in <A
1958 HREF="c21473.html#HDRWQ394"
1959 >Determining the Cache Type, Size,
1961 >. However, if you want to experiment with fine-tuning cache performance, you can use the arguments on the
1968 > command to control several other parameters. This section discusses a few of these
1969 parameters that have the most direct effect on cache performance. To learn more about the <SPAN
1976 command's arguments, see its reference page in the <SPAN
1980 >IBM AFS Administration Reference</I
1984 >In addition, the AFS initialization script included in the AFS distribution for each system type includes several
1985 variables that set several <SPAN
1991 > arguments in a way that is suitable for client machines of
1992 different sizes and usage patterns. For instructions on using the script most effectively, see the section on configuring the
1993 Cache Manager in the <SPAN
1997 >IBM AFS Quick Beginnings</I
2006 >Setting Cache Configuration Parameters</A
2009 >The cache configuration parameters with the most direct effect on cache performance include the following: <UL
2016 >total cache size</I
2018 >. This is the amount of disk space or machine memory available for caching,
2019 as discussed in detail in <A
2020 HREF="c21473.html#HDRWQ394"
2021 >Determining the Cache Type, Size, and Location</A
2030 >number of cache chunks</I
2032 >. For a disk cache, each chunk is a <SPAN
2039 file in the local cache directory (see <A
2040 HREF="c21473.html#HDRWQ393"
2041 >Cache-Related Files</A
2042 >). For a memory cache, each
2043 chunk is a set of contiguous blocks allocated in machine memory.</P
2045 >This parameter does not have as much of an effect on cache performance as total size. However, adjusting it can
2046 influence how often the Cache Manager must discard cached data to make room for new data. Suppose, for example, that you
2047 set the disk cache size to 50 MB and the number of chunks (<SPAN
2053 >n files) to 1,000. If each
2054 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
2055 can contain data from only one AFS file) but the cache holds only about 20 MB of data. When a user requests more data
2056 from the File Server, the Cache Manager must discard cached data to reclaim some chunks, even though the cache is filled
2057 to less than 50% of its capacity. In such a situation, increasing the number of chunks enables the Cache Manager to
2058 discard data less often.</P
2068 >. This parameter determines the maximum amount of data that can fit in a chunk. If
2069 a cached element is smaller than the chunk size, the remaining space in the chunk is not used (a chunk can hold no more
2070 than one element). If an element cannot fit in a single chunk, it is split across as many chunks as needed. This
2071 parameter also determines how much data the Cache Manager requests at a time from the File Server (how much data per
2078 >, because AFS uses partial file transfer).</P
2080 >The main reason to change chunk size is because of its relation to the amount of data fetched per RPC. If your
2081 network links are very fast, it can improve performance to increase chunk size; if the network is especially slow, it
2082 can make sense to decrease chunk size.</P
2090 >number of dcache entries in memory</I
2092 >. The Cache Manager maintains one dcache entry for each
2093 cache chunk, recording a small amount of information, such as the file ID (fID) and version number of the AFS file
2094 corresponding to the chunk.</P
2096 >For a disk cache, dcache entries reside in the <SPAN
2100 >/usr/vice/cache/CacheItems</B
2103 small number are duplicated in machine memory to speed access.</P
2105 >For a memory cache, the number of dcache entries equals the number of cache chunks. For a discussion of the
2106 implications of this correspondence, see <A
2107 HREF="c21473.html#HDRWQ405"
2108 >Controlling Memory Cache Configuration</A
2114 >For a description of how the Cache Manager determines defaults for number of chunks, chunk size, and number of dcache
2115 entries in a disk cache, see <A
2116 HREF="c21473.html#HDRWQ404"
2117 >Configuring a Disk Cache</A
2118 >; for a memory cache, see <A
2119 HREF="c21473.html#HDRWQ405"
2120 >Controlling Memory Cache Configuration</A
2121 >. The instructions also explain how to use the <SPAN
2127 > command's arguments to override the defaults.</P
2135 >Configuring a Disk Cache</A
2138 >The default number of cache chunks (<SPAN
2144 >n files) in a disk cache is calculated by the
2151 > command to be the greatest of the following: <UL
2158 >1.5 times the result of dividing cache size by chunk size (cachesize/chunksize * 1.5)</P
2162 >The result of dividing cachesize by 10 MB (cachesize/10240)</P
2167 >You can override this value by specifying a positive integer with the <SPAN
2174 Consider increasing this value if more than 75% of the <SPAN
2180 >n files are already used soon after
2181 the Cache Manager finishes initializing. Consider decreasing it if only a small percentage of the chunks are used at that
2182 point. In any case, never specify a value less than 100, because a smaller value can cause performance problems.</P
2184 >The following example sets the number of <SPAN
2190 >n files to 2,000:</P
2192 CLASS="programlisting"
2197 >/usr/vice/etc/afsd -files 2000</B
2208 >It is conventional to place the <SPAN
2214 > command in a machine's AFS initialization file,
2215 rather than entering it in a command shell. Furthermore, the values specified in this section are examples only, and are not
2216 necessarily suitable for a specific machine.</P
2220 >The default chunk size for a disk cache is 64 KB. In general, the only reason to change it is to adjust to exceptionally
2221 slow or fast networks; see <A
2222 HREF="c21473.html#HDRWQ403"
2223 >Setting Cache Configuration Parameters</A
2224 >. You can use the <SPAN
2230 > argument to override the default. Chunk size must be a power of 2, so provide an integer
2231 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
2232 value of 16 equals the default for disk caches (216 = 64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk
2233 size to the default. Values less than 10 (1 KB) are not recommended. The following example sets chunk size to 16 KB
2236 CLASS="programlisting"
2241 >/usr/vice/etc/afsd -chunksize 14</B
2246 >For a disk cache, the default number of dcache entries duplicated in memory is one-half the number of chunks specified
2253 > argument, to a maximum of 2,000 entries. You can use the <SPAN
2259 > argument to change the default, even exceeding 2,000 if you wish. Duplicating more than half
2260 the dcache entries in memory is not usually necessary, but sometimes improves performance slightly, because access to memory
2261 is faster than access to disk. The following example sets the number to 750:</P
2263 CLASS="programlisting"
2268 >/usr/vice/etc/afsd -dcache 750</B
2273 >When configuring a disk cache, you can combine the <SPAN
2279 > command's arguments in any way.
2280 The main reason for this flexibility is that the setting you specify for disk cache size (in the <SPAN
2286 > file or with the <SPAN
2292 > argument) is an absolute maximum
2293 limit. You cannot override it by specifying higher values for the <SPAN
2305 > arguments, alone or in combination. A related reason is that the Cache Manager does not have
2306 to reserve a set amount of memory on disk. <SPAN
2312 >n files (the chunks in a disk cache) are
2313 initially zero-length, but can expand up to the specified chunk size and shrink again, as needed. If you set the number of
2320 >n files to such a large value that expanding all of them to the full allowable size exceeds
2321 the total cache size, they simply never grow to full size.</P
2329 >Controlling Memory Cache Configuration</A
2332 >Configuring a memory cache differs from configuring a disk cache in that not all combinations of the <SPAN
2338 > command's arguments are allowed. This limitation results from the greater interaction between the
2339 configuration parameters in a memory cache than a disk cache. If all combinations are allowed, it is possible to set the
2340 parameters in an inconsistent way. A list of the acceptable and unacceptable combinations follows a discussion of default
2343 >The default chunk size for a memory cache is 8 KB. In general, the only reason to change it is to adjust to
2344 exceptionally slow or fast networks; see <A
2345 HREF="c21473.html#HDRWQ403"
2346 >Setting Cache Configuration Parameters</A
2349 >There is no predefined default for number of chunks in a memory cache. The Cache Manager instead calculates the correct
2350 number by dividing the total cache size by the chunk size. Recall that for a memory cache, all dcache entries must be in
2351 memory. This implies that the number of chunks equals the number of dcache entries in memory, and that there is no default for
2352 number of dcache entries (like the number of chunks, it is calculated by dividing the total size by the chunk size).</P
2354 >The following are acceptable combinations of the <SPAN
2360 > command's arguments when
2361 configuring a memory cache: <UL
2370 > alone, which overrides the cache size specified in the <SPAN
2374 >/usr/vice/etc/cacheinfo</B
2376 > file. The Cache Manager divides the value of this argument by the default
2377 chunk size of eight KB to calculate the number of chunks and dcache entries. The following example sets cache size to
2378 five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by 8): <PRE
2379 CLASS="programlisting"
2384 >/usr/vice/etc/afsd -memcache -blocks 5120</B
2397 > alone, to override the default of eight KB. The chunk size must be a
2398 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
2399 ten sets chunk size to 1 KB (210 = 1024); a value of 13 equals the default for memory caches (213 = 8 KB). Specifying a
2400 value of 0 (zero) or greater than 30 returns the chunk size to the default. Values less than ten (equivalent to 1 KB)
2401 are not recommended. The following example sets the chunk size to four KB (212). Assuming a total cache size of four MB
2402 (4,096 KB), the resulting number of chunks is 1024. <PRE
2403 CLASS="programlisting"
2408 >/usr/vice/etc/afsd -memcache -chunksize 12</B
2427 > together override the
2428 defaults for cache size and chunk size. The Cache Manager divides the first by the second to calculate the number of
2429 chunks and dcache entries. For example, the following example sets the cache size to six MB (6,144 KB) and chunksize to
2430 four KB (212), resulting in 1,536 chunks: <PRE
2431 CLASS="programlisting"
2436 >/usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12</B
2444 >The following arguments or combinations explicitly set the number of chunks and dcache entries. It is best not to use
2445 them, because they set the cache size indirectly, forcing you to perform a hand calculation to determine the size of the
2446 cache. Instead, set the <SPAN
2459 alone or in combination; in those cases, the Cache Manager determines the number of chunks and dcache entries itself. Because
2460 the following combinations are not recommended, no examples are included. <UL
2469 > argument alone explicitly sets the number of chunks and dcache
2470 entries. The Cache Manager multiples this value times the default chunk size of 8 KB to derive the total cache size
2471 (overriding the value in the <SPAN
2481 >The combination of <SPAN
2494 the chunk number and size. The Cache Manager sets the specified values and multiplies them together to obtain total
2495 cache size (overriding the value in the <SPAN
2506 >Do not use the following arguments for a memory cache: <UL
2515 > alone. This argument controls the number of <SPAN
2521 >n files for a disk cache, but is ignored for a memory cache.</P
2537 >. An error message results,
2538 because it is possible to provide values such that dividing the first (total size) by the second (number of chunks)
2539 results in a chunk size that is not a power of two.</P
2551 >Maintaining Knowledge of Database Server Machines</A
2554 >For the users of an AFS client machine to access a cell's AFS filespace and other services, the Cache Manager and other
2555 client-side agents must have an accurate list of the cell's database server machines. The affected functions include the
2559 >Accessing files. The Cache Manager contacts the Volume Location (VL) Server to learn which file server machine
2560 houses the volume containing a requested file or directory. If the Cache Manager cannot contact a cell's VL Servers, it
2561 cannot fetch files.</P
2565 >Authenticating. The <SPAN
2571 > program and AFS-modified login utilities contact the
2572 Authentication Server to obtain tokens, which the AFS server processes accept as proof that the user is
2577 >Creating protection groups. The <SPAN
2583 > command interpreter contacts the Protection
2584 Server when users create protection groups or request information from the Protection Database.</P
2588 >Editing access control lists (ACLs). The <SPAN
2594 > command interpreter contacts the File
2595 Server that maintains the read/write volume containing a file or directory; the location information comes from the VL
2601 >To enable a machine's users to access a cell, you must list the names and IP addresses of its database server machines in
2606 >/usr/vice/etc/CellServDB</B
2608 > file on the machine's local disk. In addition to the machine's
2609 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
2610 must also mount its <SPAN
2616 > volume in the local AFS filespace; the conventional location is
2617 just under the AFS root directory, <SPAN
2623 >. For instructions, see the <SPAN
2637 >How Clients Use the List of Database Server Machines</A
2646 > program runs and initializes the Cache Manager, it reads the contents of
2653 > file into kernel memory. The Cache Manager does not consult the file again
2654 until the machine next reboots. In contrast, the command interpreters for the AFS command suites (such as <SPAN
2673 each time they need to contact a database server process.</P
2675 >When a cell's list of database server machines changes, you must change both the <SPAN
2681 > file and the list in kernel memory to preserve consistent client performance; some commands
2682 probably fail if the two lists of machines disagree. One possible method for updating both the <SPAN
2688 > file and kernel memory is to edit the file and reboot the machine. To avoid needing to
2689 reboot, you can instead perform both of the following steps: <OL
2699 > command to alter the list in kernel memory directly, making
2700 the changes available to the Cache Manager.</P
2710 > file to make the changes available to command interpreters.
2711 For a description of the file's format, see <A
2712 HREF="c21473.html#HDRWQ407"
2713 >The Format of the CellServDB file</A
2719 >The consequences of missing or incorrect information in the <SPAN
2726 memory are as follows: <UL
2729 >If there is no entry for a cell, the machine's users cannot access the cell.</P
2733 >If a cell's entry does not include a database server machine, then the Cache Manager and command interpreters
2734 never attempt to contact the machine. The omission does not prevent access to the cell--as long as the information about
2735 the other database server machines is correct and the server processes, machines, and network are functioning
2736 correctly--but it can put an undue burden on the machines that are listed. If all of the listed machines become
2737 inaccessible to clients, then the cell becomes inaccessible even if the omitted database server machine is functioning
2742 >If a machine's name or address is incorrect, or the machine is not actually running the database server processes,
2743 then requests from clients time out. Users can experience lengthy delays because they have to wait the full timeout
2744 period before the Cache Manager or command interpreter contacts another database server machine.</P
2755 >The Format of the CellServDB file</A
2758 >When editing the <SPAN
2762 >/usr/vice/etc/CellServDB</B
2764 > file, you must use the correct format for
2765 cell and machine entries. Each cell has a separate entry. The first line has the following format:</P
2767 CLASS="programlisting"
2768 > >cell_name #organization
2771 >where cell_name is the cell's complete Internet domain name (for example, <SPAN
2778 organization is an optional field that follows any number of spaces and the number sign (<SAMP
2779 CLASS="computeroutput"
2782 and can name the organization to which the cell corresponds (for example, the ABC Corporation). After the first line comes a
2783 separate line for each database server machine. Each line has the following format:</P
2785 CLASS="programlisting"
2786 > IP_address #machine_name
2789 >where IP_address is the machine's IP address in dotted decimal format (for example, 192.12.105.3). Following any number
2790 of spaces and the number sign (<SAMP
2791 CLASS="computeroutput"
2793 >) is machine_name, the machine's fully-qualified hostname
2800 >). In this case, the number sign does not indicate a comment:
2801 machine_name is a required field.</P
2803 >The order in which the cells appear is not important, but it is convenient to put the client machine's home cell first.
2804 Do not include any blank lines in the file, not even after the last entry.</P
2806 >The following example shows entries for two cells, each of which has three database server machines:</P
2808 CLASS="programlisting"
2809 > >abc.com #ABC Corporation (home cell)
2810 192.12.105.3 #db1.abc.com
2811 192.12.105.4 #db2.abc.com
2812 192.12.105.55 #db3.abc.com
2813 >stateu.edu #State University cell
2814 138.255.68.93 #serverA.stateu.edu
2815 138.255.68.72 #serverB.stateu.edu
2816 138.255.33.154 #serverC.stateu.edu
2825 >Maintaining the Client CellServDB File</A
2828 >Because a correct entry in the <SPAN
2834 > file is vital for consistent client
2835 performance, you must also update the file on each client machine whenever a cell's list of database server machines changes
2836 (for instance, when you follow the instructions in the <SPAN
2840 >IBM AFS Quick Beginnings</I
2842 > to add or remove a
2843 database server machine). To facilitate the client updates, you can use the <SPAN
2850 which copies files from a central source in AFS to the local disk of client machines. It is conventional to invoke the
2857 > program in a client machine's AFS initialization file so that it runs as the machine
2858 reboots, but you can also issue the <SPAN
2864 > command at any time. For instructions, see <A
2865 HREF="c23832.html#HDRWQ448"
2866 >Running the package program</A
2869 >If you use the <SPAN
2875 > program, the conventional location for your cell's central
2892 >/common/etc/CellServDB</B
2894 >, where cell_name is your cell name. </P
2896 >Creating a symbolic or hard link from <SPAN
2900 >/usr/vice/etc/CellServDB</B
2902 > to a central source file
2903 in AFS is not a viable option. The <SPAN
2909 > program reads the file into kernel memory before the
2910 Cache Manager is completely initialized and able to access AFS.</P
2912 >Because every client machine has its own copy of the <SPAN
2918 > file, you can in theory
2919 make the set of accessible cells differ on various machines. In most cases, however, it is best to maintain consistency
2920 between the files on all client machines in the cell: differences between machines are particularly confusing if users
2921 commonly use a variety of machines rather than just one.</P
2923 >The AFS Product Support group maintains a central <SPAN
2929 > file that includes all
2930 cells that have agreed to make their database server machines access to other AFS cells. It is advisable to check this file
2931 periodically for updated information. See <A
2932 HREF="c667.html#HDRWQ38"
2933 >Making Your Cell Visible to Others</A
2936 >An entry in the local <SPAN
2942 > is one of the two requirements for accessing a cell.
2943 The other is that the cell's <SPAN
2949 > volume is mounted in the local filespace, by
2950 convention as a subdirectory of the <SPAN
2956 > directory. For instructions, see <A
2957 HREF="c8420.html#HDRWQ213"
2958 >To create a cellular mount point</A
2971 >/usr/vice/etc/CellServDB</B
2973 > file on a client machine is not the same as the
2978 >/usr/afs/etc/CellServDB</B
2980 > file on the local disk of a file server machine. The server version
2981 lists only the database server machines in the server machine's home cell, because server processes never need to contact
2982 foreign cells. It is important to update both types of <SPAN
2988 > file on all machines in
2989 the cell whenever there is a change to your cell's database server machines. For more information about maintaining the
2990 server version of the <SPAN
2997 HREF="c3025.html#HDRWQ118"
2998 >Maintaining the Server
3010 >To display the /usr/vice/etc/CellServDB file</A
3016 >Use a text editor or the <SPAN
3022 > command to display the contents of the <SPAN
3026 >/usr/vice/etc/CellServDB</B
3028 > file. By default, the mode bits on the file permit anyone to read it.
3030 CLASS="programlisting"
3035 >cat /usr/vice/etc/CellServDB</B
3049 >To display the list of database server machines in kernel memory</A
3062 CLASS="programlisting"
3067 >fs listcells [&]</B
3079 > is the shortest acceptable abbreviation of <SPAN
3087 >To have your shell prompt return immediately, include the ampersand (<SPAN
3094 makes the command run in the background. It can take a while to generate the complete output because the kernel stores
3095 database server machines' IP addresses only, and the <SPAN
3101 > command interpreter has the
3102 cell's name resolution service (such as the Domain Name Service or a local host table) translate them into hostnames. You
3103 can halt the command at any time by issuing an interrupt signal such as <SPAN
3111 >The output includes a single line for each cell, in the following format:</P
3113 CLASS="programlisting"
3114 > Cell cell_name on hosts list_of_hostnames.
3117 >The name service sometimes returns hostnames in uppercase letters, and if it cannot resolve a name at all, it
3118 returns its IP address. The following example illustrates all three possibilities:</P
3120 CLASS="programlisting"
3130 Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com
3131 Cell stateu.edu on hosts SERVERA.STATEU.EDU SERVERB.STATEU.EDU
3133 Cell ghi.org on hosts 191.255.64.111 191.255.64.112
3146 >To change the list of a cell's database server machines in kernel memory</A
3152 >Become the local superuser <SPAN
3158 > on the machine, if you are not already, by issuing
3166 CLASS="programlisting"
3183 >If you a use a central copy of the <SPAN
3189 > file as a source for client machines,
3190 verify that its directory's ACL grants you the <SPAN
3226 >) permissions. The conventional directory is <SPAN
3238 >. If necessary, issue the <SPAN
3244 > command, which is fully described in <A
3245 HREF="c31274.html#HDRWQ572"
3249 CLASS="programlisting"
3274 > command to add or change a cell's
3275 entry in kernel memory. Repeat the command for each cell.</P
3283 >You cannot use this command to remove a cell's entry completely from kernel memory. In the rare cases when you
3284 urgently need to prevent access to a specific cell, you must edit the <SPAN
3291 and reboot the machine.</P
3295 CLASS="programlisting"
3307 >primary servers</VAR
3317 >linked cell name</VAR
3322 CLASS="variablelist"
3334 >Is the shortest acceptable abbreviation of <SPAN
3352 >Specifies the complete Internet domain name of the cell for which to record a new list of database server
3365 >Specifies the fully-qualified hostname or IP address in dotted-decimal format for each database server
3366 machine in the cell. The list you provide completely replaces the existing list.</P
3378 >Specifies the complete Internet domain name of the AFS cell to link to a DCE cell for the purposes of DFS
3379 fileset location. You can use this argument if the machine's AFS users access DFS via the AFS/DFS Migration
3380 Toolkit Protocol Translator. For instructions, see the <SPAN
3384 >IBM AFS/DFS Migration Toolkit Administration
3385 Guide and Reference</I
3395 >Add or edit the cell's entry in the local <SPAN
3399 >/usr/vice/etc/CellServDB</B
3402 of the following three methods. In each case, be sure to obey the formatting requirements described in <A
3403 HREF="c21473.html#HDRWQ407"
3404 >The Format of the CellServDB file</A
3408 >If you maintain a central source version of the <SPAN
3421 > program, first use a text editor to alter the central copy of the file.
3422 Then issue the <SPAN
3428 > command to transfer the contents of the file to the local
3429 machine. For complete instructions, see <A
3430 HREF="c23832.html#HDRWQ448"
3431 >Running the package program</A
3434 CLASS="programlisting"
3439 >/etc/package -v -c</B
3443 >name of package file</VAR
3450 >If you maintain a central source <SPAN
3456 > file but do not use the <SPAN
3462 > program, first use a text editor to alter the central copy of the file. Then use a
3463 copying command such as the <SPAN
3469 > command to copy it to the local <SPAN
3473 >/usr/vice/etc/CellServDB</B
3479 >If you do not use a central source <SPAN
3485 > file, edit the local machine's
3490 >/usr/vice/etc/CellServDB</B
3506 >Determining if a Client Can Run Setuid Programs</A
3515 > is one whose binary file has the UNIX setuid mode bit turned on. While a setuid
3516 program runs, the user who initialized it assumes the local identity (UNIX UID) of the binary file's owner, and so is granted
3517 the permissions in the local file system that pertain to the owner. Most commonly, the issuer's assumed identity (often referred
3524 >) is the local superuser <SPAN
3532 >AFS does not recognize effective UID: if a setuid program accesses AFS files and directories, it uses the current AFS
3533 identity of the user who initialized the program, not of the program's owner. Nevertheless, it can be useful to store setuid
3534 programs in AFS for use on more than one client machine. AFS enables a client machine's administrator to determine whether the
3535 local Cache Manager allows setuid programs to run or not.</P
3537 >By default, the Cache Manager allows programs from its home cell to run with setuid permission, but denies setuid
3538 permission to programs from foreign cells. A program belongs to the same cell as the file server machine that houses the volume
3539 in which the file resides, as specified in the file server machine's <SPAN
3543 >/usr/afs/etc/ThisCell</B
3546 file. The Cache Manager determines its own home cell by reading the <SPAN
3550 >/usr/vice/etc/ThisCell</B
3553 at initialization.</P
3555 >To change a cell's setuid status with respect to the local machine, become the local superuser <SPAN
3561 > and issue the <SPAN
3567 > command. To determine a cell's current
3568 setuid status, use the <SPAN
3572 >fs getcellstatus</B
3576 >When you issue the <SPAN
3582 > command, you directly alter a cell's setuid status as
3583 recorded in kernel memory, so rebooting the machine is not necessary. However, nondefault settings do not persist across reboots
3584 of the machine unless you add the appropriate <SPAN
3590 > command to the machine's AFS
3591 initialization file.</P
3593 >Only members of the <SPAN
3597 >system:administrators</B
3599 > group can turn on the setuid mode bit on an AFS
3600 file or directory. When the setuid mode bit is turned on, the UNIX <SPAN
3606 > command displays the
3607 third user mode bit as an <SPAN
3613 > instead of an <SPAN
3620 file or directory, the <SPAN
3626 > appears only if setuid permission is enabled for the cell in which the
3634 >To determine a cell's setuid status</A
3644 >fs getcellstatus</B
3646 > command to check the setuid status of each desired cell.
3648 CLASS="programlisting"
3653 >fs getcellstatus</B
3663 CLASS="variablelist"
3675 >Is the shortest acceptable abbreviation of <SPAN
3693 >Names each cell for which to report setuid status. Provide the complete Internet domain name or a shortened
3694 form that distinguishes it from the other cells listed in the local <SPAN
3698 >/usr/vice/etc/CellServDB</B
3708 >The output reports the setuid status of each cell: <UL
3712 CLASS="computeroutput"
3713 >no setuid allowed</SAMP
3714 > indicates that the Cache Manager does not allow
3715 programs from the cell to run with <SAMP
3716 CLASS="computeroutput"
3717 >setuid permission</SAMP
3722 >setuid allowed indicates that the Cache Manager allows programs from the cell to run with setuid permission</P
3733 >To change a cell's setuid status</A
3739 >Become the local superuser <SPAN
3745 > on the machine, if you are not already, by issuing
3753 CLASS="programlisting"
3776 > command to change the setuid status of the cell.
3778 CLASS="programlisting"
3805 CLASS="variablelist"
3817 >Is the shortest acceptable abbreviation of <SPAN
3835 >Names each cell for which to change setuid status as specified by the <SPAN
3848 > flag. Provide each cell's complete Internet domain name or a shortened
3849 form that distinguishes it from the other cells listed in the local <SPAN
3853 >/usr/vice/etc/CellServDB</B
3867 >Enables programs from each specified cell to execute with setuid permission. Provide this flag or the
3874 > flag, or omit both to disable setuid permission for each cell.</P
3886 >Prevents programs from each specified cell from executing with setuid permission. Provide this flag or the
3893 > flag, or omit both to disable setuid permission for each cell.</P
3908 >Setting the File Server Probe Interval</A
3911 >The Cache Manager periodically sends a probe to server machines to verify that they are still accessible. Specifically, it
3912 probes the database server machines in its cell and those file servers that house data it has cached.</P
3914 >If a server process does not respond to a probe, the client machine assumes that it is inaccessible. By default, the
3915 interval between probes is three minutes, so it can take up to three minutes for a client to recognize that a server process is
3916 once again accessible after it was inaccessible.</P
3918 >To adjust the probe interval, include the <SPAN
3924 > argument to the <SPAN
3930 > command while logged in as the local superuser <SPAN
3937 new interval setting persists until you again issue the command or reboot the machine, at which time the setting returns to the
3938 default. To preserve a nondefault setting across reboots, include the appropriate <SPAN
3945 > command in the machine's AFS initialization file.</P
3952 >To set a client's file server probe interval</A
3958 >Become the local superuser <SPAN
3964 > on the machine, if you are not already, by issuing
3972 CLASS="programlisting"
3995 > command with the <SPAN
4002 CLASS="programlisting"
4007 >fs checkservers -interval</B
4011 >seconds between probes</VAR
4017 CLASS="variablelist"
4029 >Is the shortest acceptable abbreviation of <SPAN
4047 >Specifies the number of seconds between probes. Provide an integer value greater than zero.</P
4062 >Setting a Client Machine's Cell Membership</A
4065 >Each client machine belongs to a particular cell, as named in the <SPAN
4069 >/usr/vice/etc/ThisCell</B
4072 on its local disk. The machine's cell membership determines three defaults important to users of the machine: <UL
4075 >The cell for which users of the machine obtain tokens (authenticate) when they use the <SPAN
4081 > program or issue the <SPAN
4087 > command. There are two effects:
4097 > program and AFS-modified login utilities contact an Authentication
4098 Server in the cell named in the <SPAN
4114 > program and AFS-modified login utilities combine the contents of the
4121 > file with the password that the user provides, generating an encryption
4122 key from the combination. The user's entry in the Authentication Database includes an encryption key also generated
4123 from the combination of password and cell name. If the cell name in the <SPAN
4130 file is incorrect, users cannot authenticate even if they provide the correct password.</P
4137 >The cell the Cache Manager considers its local, or home, cell. The Cache Manager allows programs from its local cell
4138 to run with setuid permission, but not programs from foreign cells, as discussed further in <A
4139 HREF="c21473.html#HDRWQ409"
4140 >Determining if a Client Can Run Setuid Programs</A
4145 >The default database server machines that are contacted by the AFS command interpreters running on this
4156 >To display a client machine's cell membership</A
4162 >Use a text editor or the <SPAN
4168 > command to display the contents of the <SPAN
4172 >/usr/vice/etc/ThisCell</B
4175 CLASS="programlisting"
4180 >cat /usr/vice/etc/ThisCell</B
4194 >To set a client machine's cell membership</A
4200 >Become the local superuser <SPAN
4206 > on the machine, if you are not already, by issuing
4214 CLASS="programlisting"
4231 >Using a text editor, replace the cell name in the <SPAN
4235 >/usr/vice/etc/ThisCell</B
4248 > Reboot the machine to enable the Cache Manager to use the new cell name
4249 immediately; the appropriate command depends on the machine's system type. The <SPAN
4256 program, AFS-modified login utilities, and the AFS command interpreters use the new cell name the next time they are
4257 invoked; no reboot is necessary. <PRE
4258 CLASS="programlisting"
4285 >Forcing the Update of Cached Data</A
4288 >AFS's callback mechanism normally guarantees that the Cache Manager provides the most current version of a file or
4289 directory to the application programs running on its machine. However, you can force the Cache Manager to discard (flush) cached
4290 data so that the next time an application program requests it, the Cache Manager fetches the latest version available at the
4293 >You can control how many file system elements to flush at a time: <UL
4296 >To flush only specific files or directories, use the <SPAN
4302 > command. This command
4303 forces the Cache Manager to discard the data and status information it has cached from the specified files or directories.
4304 It does not discard information from an application program's buffer or information that has been altered locally (changes
4305 made in the cache but not yet saved permanently to the File Server). However, the next time an application requests the
4306 element's data or status information, the Cache Manager has to contact the File Server to get it.</P
4310 >To flush everything cached from a certain volume, use the <SPAN
4317 This command works like the <SPAN
4323 > command, but differs in two ways: <UL
4326 >The Cache Manager discards data for all elements in the cache that come from the same volume as the specified
4327 files or directories.</P
4331 >The Cache Manager discards only data, not status information. This difference has little practical effect, but
4332 can lead to different output from the <SPAN
4338 > command when the two different commands
4339 are used to flush the same element.</P
4347 >In addition to callbacks, the Cache Manager has a mechanism for tracking other kinds of possible changes, such as changes
4348 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
4349 Manager's volume location record can be wrong. To resynchronize it, use the <SPAN
4356 command. When you issue the command, the Cache Manager creates a new table of mappings between volume names, ID numbers, and
4357 locations. This forces the Cache Manager to reference newly relocated and renamed volumes before it can provide data from
4360 >It is also possible for information about mount points to become corrupted in the cache. Symptoms of a corrupted mount
4361 point included garbled output from the <SPAN
4367 > command, and failed attempts to change
4368 directory to or list the contents of a mount point. Use the <SPAN
4374 > command to discard a
4375 corrupted mount point. The Cache Manager must refetch the mount point the next time it crosses it in a pathname. (The Cache
4376 Manager periodically refreshes cached mount points, but the only other way to discard them immediately is to reinitialize the
4377 Cache Manager by rebooting the machine. </P
4384 >To flush certain files or directories</A
4397 CLASS="programlisting"
4412 CLASS="variablelist"
4424 >Must be typed in full.</P
4436 >Names each file or directory structure to flush from the cache. Omit this argument to flush the current
4437 working directory. Flushing a directory structure does not flush any files or subdirectories cached from
4452 >To flush all data from a volume</A
4465 CLASS="programlisting"
4480 CLASS="variablelist"
4492 >Is the shortest acceptable abbreviation of <SPAN
4510 >Names a file or directory from each volume to flush from the cache. The Cache Manager flushes everything in
4511 the cache that it has fetched from the same volume. Omit this argument to flush all cached data fetched from the
4512 volume that contains the current working directory.</P
4526 >To force the Cache Manager to notice other volume changes</A
4539 CLASS="programlisting"
4556 > is the shortest acceptable abbreviation of <SPAN
4566 >The following command confirms that the command completed successfully:</P
4568 CLASS="programlisting"
4569 > All volumeID/name mappings checked.
4578 >To flush one or more mount points</A
4591 CLASS="programlisting"
4606 CLASS="variablelist"
4618 >Is the shortest acceptable abbreviation of <SPAN
4636 >Names each mount point to flush from the cache. Omit this argument to flush the current working directory.
4637 Files or subdirectories cached from the associated volume are unaffected.</P
4652 >Maintaining Server Preference Ranks</A
4655 >As mentioned in the introduction to this chapter, AFS uses client-side data caching and callbacks to reduce the amount of
4656 network traffic in your cell. The Cache Manager also tries to make its use of the network as efficient as possible by assigning
4661 >preference ranks</I
4663 > to server machines based on their network proximity to the local machine. The ranks bias
4664 the Cache Manager to fetch information from the server machines that are on its own subnetwork or network rather than on other
4665 networks, if possible. Reducing the network distance that data travels between client and server machine tends to reduce network
4666 traffic and speed the Cache Manager's delivery of data to applications.</P
4668 >The Cache Manager stores two separate sets of preference ranks in kernel memory. The first set of ranks applies to
4669 machines that run the Volume Location (VL) Server process, hereafter referred to as <SPAN
4673 >VL Server machines</I
4676 second set of ranks applies to machines that run the File Server process, hereafter referred to as <SPAN
4683 >. This section explains how the Cache Manager sets default ranks, how to use the <SPAN
4690 > command to change the defaults or set new ranks, and how to use the <SPAN
4697 > command to display the current set of ranks.</P
4704 >How the Cache Manager Sets Default Ranks</A
4713 > program initializes the Cache Manager, it assigns a preference rank of
4714 10,000 to each of the VL Server machines listed in the local <SPAN
4718 >/usr/vice/etc/CellServDB</B
4721 It then randomizes the ranks by adding an integer randomly chosen from the range 0 (zero) to 126. It avoids assigning the same
4722 rank to machines in one cell, but it is possible for machines from different cells to have the same rank. This does not
4723 present a problem in use, because the Cache Manager compares the ranks of only one cell's database server machines at a time.
4724 Although AFS supports the use of multihomed database server machines, the Cache Manager only uses the single address listed
4725 for each database server machine in the local <SPAN
4729 >/usr/vice/etc/CellServDB</B
4731 > file. Only Ubik can
4732 take advantage of a multihomed database server machine's multiple interfaces.</P
4734 >The Cache Manager assigns preference ranks to a file server machine when it obtains the server's VLDB record from the VL
4735 Server, the first time that it accesses a volume that resides on the machine. If the machine is multihomed, the Cache Manager
4736 assigns a distinct rank to each of its interfaces (up to the number of interfaces that the VLDB can store for each machine,
4737 which is specified in the <SPAN
4741 >IBM AFS Release Notes</I
4743 >). The Cache Manager compares the interface's IP address
4744 to the local machine's address and applies the following algorithm: <UL
4747 >If the local machine is a file server machine, the base rank for each of its interfaces is 5,000.</P
4751 >If the file server machine interface is on the same subnetwork as the local machine, its base rank is
4756 >If the file server machine interface is on the same network as the local machine, or is at the distant end of a
4757 point-to-point link with the local machine, its base rank is 30,000.</P
4761 >If the file server machine interface is on a different network than the local machine, or the Cache Manager cannot
4762 obtain network information about it, its base rank is 40,000.</P
4767 >If the client machine has only one interface, the Cache Manager compares it to the server interface's IP address and
4768 sets a rank according to the algorithm. If the client machine is multihomed, the Cache Manager compares each of the local
4769 interface addresses to the server interface, and assigns to the server interface the lowest rank that results from comparing
4770 it to all of the client interfaces.</P
4772 >After assigning a base rank to a file server machine interface, the Cache Manager adds to it a number randomly chosen
4773 from the range 0 (zero) to 15. As an example, a file server machine interface in the same subnetwork as the local machine
4774 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
4775 process reduces the number of interfaces that have exactly the same rank. As with VL Server machine ranks, it is possible for
4776 file server machine interfaces from foreign cells to have the same rank as interfaces in the local cell, but this does not
4777 present a problem. Only the relative ranks of the interfaces that house a specific volume are relevant, and AFS supports
4778 storage of a volume in only one cell at a time.</P
4786 >How the Cache Manager Uses Preference Ranks</A
4789 >Each preference rank pairs an interface's IP address with an integer that can range from 1 to 65,534. A lower rank
4790 (lower number) indicates a stronger preference. Once set, a rank persists until the machine reboots, or until you use the
4795 >fs setserverprefs</B
4797 > command to change it.</P
4799 >The Cache Manager uses VL Server machine ranks when it needs to fetch volume location information from a cell. It
4800 compares the ranks for the cell's VL Server machines and attempts to contact the VL Server process on the machine with the
4801 best (lowest integer) rank. If it cannot reach that VL Server, it tries to contact the VL Server with the next best rank, and
4802 so on. If all of a cell's VL Server machines are inaccessible, the Cache Manager cannot fetch data from the cell.</P
4804 >Similarly, when the Cache Manager needs to fetch data from a volume, it compares the ranks for the interfaces of
4805 machines that house the volume, and attempts to contact the interface that has the best rank. If it cannot reach the <SPAN
4811 > process via that interface, it tries to contact the interface with the next best integer
4812 rank, and so on. If it cannot reach any of the interfaces for machines that house the volume, it cannot fetch data from the
4821 >Displaying and Setting Preference Ranks</A
4824 >To display the file server machine ranks that the Cache Manager is using, use the <SPAN
4831 > command. Include the <SPAN
4837 > flag to display VL Server machine
4838 ranks instead. By default, the output appears on the standard output stream (stdout), but you can write it to a file instead
4839 by including the <SPAN
4847 >The Cache Manager stores IP addresses rather than hostnames in its kernel list of ranks, but by default the output
4848 identifies interfaces by hostname after calling a translation routine that refers to either the cell's name service (such as
4849 the Domain Name Server) or the local host table. If an IP address appears in this case, it is because the translation attempt
4850 failed. To bypass the translation step and display IP addresses rather than hostnames, include the <SPAN
4856 > flag. This can significantly speed up the output.</P
4858 >You can use the <SPAN
4862 >fs setserverprefs</B
4864 > command to reset an existing preference rank, or to
4865 set the initial rank of a file server machine interface or VL Server machine for which the Cache Manager has no rank. The
4866 ranks you set persist until the machine reboots or until you issue the <SPAN
4870 >fs setserverprefs</B
4873 command again. To make a rank persist across a reboot, place the appropriate <SPAN
4880 > command in the machine's AFS initialization file.</P
4882 >As with default ranks, the Cache Manager adds a randomly chosen integer to each rank range that you assign. For file
4883 server machine interfaces, the randomizing number is from the range 0 (zero) to 15; for VL Server machines, it is from the
4884 range 0 (zero) to 126. For example, if you assign a rank of 15,000 to a file server machine interface, the Cache Manager
4885 stores an integer between 15,000 to 15,015.</P
4887 >To assign VL Server machine ranks, list them after the <SPAN
4898 >fs setserverprefs</B
4902 >To assign file server machine ranks, use or more of the three possible methods: <OL
4906 >List them after the <SPAN
4912 > argument on the command line.</P
4916 >Record them in a file and name it with the <SPAN
4922 > argument. You can easily
4923 generate a file with the proper format by including the <SPAN
4929 > argument to the <SPAN
4933 >fs getserverprefs</B
4939 >Provide them via the standard input stream, by including the <SPAN
4946 enables you to feed in values directly from a command or script that generates preferences using an algorithm
4947 appropriate for your cell. It must generate them in the proper format, with one or more spaces between each pair and
4948 between the two parts of the pair. The AFS distribution does not include such a script, so you must write one if you
4949 want to use this method.</P
4954 >You can combine any of the <SPAN
4973 > options on the same command line if you wish. If more than one of them specifies a
4974 rank for the same interface, the one assigned with the <SPAN
4980 > argument takes precedence.
4981 You can also provide the <SPAN
4987 > argument on the same command line to set VL Server
4988 machine ranks at the same time as file server machine ranks.</P
4996 > command interpreter does not verify hostnames or IP addresses, and so willingly
4997 stores ranks for hostnames and addresses that don't actually exist. The Cache Manager never uses such ranks unless the same
4998 VLDB record for a server machine records the same incorrect information. </P
5006 >To display server preference ranks</A
5016 >fs getserverprefs</B
5018 > command to display the Cache Manager's preference ranks
5019 for file server machines or VL Server machines. <PRE
5020 CLASS="programlisting"
5025 >fs getserverprefs</B
5035 >output to named file</VAR
5053 CLASS="variablelist"
5065 >Is an acceptable alias for <SPAN
5077 > is the shortest acceptable abbreviation).</P
5089 >Specifies the pathname of the file to which to write the list of ranks. Omit this argument to display the
5090 list on the standard output stream (stdout).</P
5102 >Displays the IP address, rather than the hostname, of each ranked machine interface. Omit this flag to have
5103 the addresses translated into hostnames, which takes longer.</P
5115 >Displays ranks for VL Server machines rather than file server machines.</P
5121 >The following example displays file server machine ranks. The <SPAN
5128 used, so the appearance of an IP address indicates that is not currently possible to translate it to a hostname.</P
5130 CLASS="programlisting"
5140 server1.stateu.edu 40011
5143 192.12.106.120 40002
5144 192.12.106.119 40001
5156 >To set server preference ranks</A
5162 >Become the local superuser <SPAN
5168 > on the machine, if you are not already, by issuing
5176 CLASS="programlisting"
5197 >fs setserverprefs</B
5199 > command to set the Cache Manager's preference ranks for
5200 one or more file server machines or VL Server machines. <PRE
5201 CLASS="programlisting"
5206 >fs setserverprefs</B
5216 >fileserver names and ranks</VAR
5226 >VL server names and ranks</VAR
5236 >input from named file</VAR
5248 CLASS="variablelist"
5260 >Is an acceptable alias for <SPAN
5272 > is the shortest acceptable abbreviation).</P
5284 >Specifies one or more pairs of file server machine interface and rank. Identify each interface by its
5285 fully-qualified hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <SPAN
5297 >. Separate the parts of a pair, and the pairs
5298 from one another, with one or more spaces.</P
5310 >Specifies one or more pairs of VL Server machine and rank. Identify each machine by its fully-qualified
5311 hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <SPAN
5335 >Specifies the pathname of a file that contains one more pairs of file server machine interface and rank.
5336 Place each pair on its own line in the file. Use the same format for interfaces and ranks as with the <SPAN
5354 >Indicates that pairs of file server machine interface and rank are being provided via the standard input
5355 stream (stdin). The program or script that generates the pairs must format them in the same manner as for the
5377 >Managing Multihomed Client Machines</A
5380 >The File Server can choose the interface to which to send a message when it initiates communication with the Cache Manager
5381 on a multihomed client machine (one with more than one network interface and IP address). If that interface is inaccessible, it
5382 automatically switches to an alternate. This improves AFS performance, because it means that the outage of an interface does not
5383 interrupt communication between File Server and Cache Manager.</P
5385 >The File Server can choose the client interface when it sends two types of messages: <UL
5388 >A message to break the callback that the Cache Manager holds on a cached file</P
5398 > message to check that the Cache Manager is still accessible and responding; the File
5399 Server sends such a message every few minutes</P
5404 >(The File Server does not choose which client interface to respond to when filling a Cache Manager's request for AFS data.
5405 In that case, it always responds to the client interface via which the Cache Manager sent the request.)</P
5407 >The Cache Manager compiles the list of eligible interfaces on its client machine automatically as it initializes, and
5408 records them in kernel memory. When the Cache Manager first establishes a connection with the File Server, it sends along the
5409 list of interface addresses. The File Server records the addresses, and uses the one at the top of the list when it needs to
5410 break a callback or send a ping to the Cache Manager. If that interface is inaccessible, the File Server simultaneously sends a
5411 message to all of the other interfaces in the list. Whichever interface replies first is the one to which the File Server sends
5414 >You can control which addresses the Cache Manager registers with File Servers by listing them in two files in the
5421 > directory on the client machine's local disk: <SPAN
5440 file exists when the Cache Manager initializes, the Cache Manager uses its contents as the basis for the list of interfaces.
5441 Otherwise, the Cache Manager uses the list of interfaces configured with the operating system. It then removes from the list any
5442 addresses that appear in the <SPAN
5446 >/usr/vice/etc/NetRestrict</B
5448 > file, if it exists. The Cache Manager
5449 records the resulting list in kernel memory.</P
5451 >You can also use the <SPAN
5455 >fs setclientaddrs</B
5457 > command to change the list of addresses stored in
5458 the Cache Manager's kernel memory, without rebooting the client machine. The list of addresses you provide on the command line
5459 completely replaces the current list in kernel memory. The changes you make persist only until the client machine reboots,
5460 however. To preserve the revised list across reboots, list the interfaces in the <SPAN
5467 (and if appropriate, the <SPAN
5473 > file) in the local <SPAN
5479 > directory. (You can also place the appropriate <SPAN
5486 > command in the machine's AFS initialization script, but that is less efficient: by the time the Cache
5487 Manager reads the command in the script, it has already compiled a list of interfaces.)</P
5489 >To display the list of addresses that the Cache Manager is currently registering with File Servers, use the <SPAN
5493 >fs getclientaddrs</B
5497 >Keep the following in mind when you change the <SPAN
5509 > file, or issue the <SPAN
5513 >fs getclientaddrs</B
5519 >fs setclientaddrs</B
5524 >When you issue the <SPAN
5528 >fs setclientaddrs</B
5530 > command, the revised list of addresses does
5531 not propagate automatically to File Servers with which the Cache Manager has already established a connection. They
5532 continue to use the list that the Cache Manager registered with them when it first established a connection. To force
5533 previously contacted File Servers to use the revised list, you must either reboot each file server machine, or reboot the
5534 client machine after changing its <SPAN
5556 > command interpreter verifies that each of the addresses you specify on the
5561 >fs setclientaddrs</B
5563 > command line is actually configured with the client machine's operating
5564 system. If it is not, the command fails with an error message that marks the address as a <SAMP
5565 CLASS="computeroutput"
5572 >As previously noted, the File Server does not use the registered list of addresses when it responds to the Cache
5573 Manager's request for data (as opposed to initiating communication itself). It always attempts to send its reply to the
5574 interface from which the Cache Manager sent the request. If the reply attempt fails, the File Server selects an alternate
5575 route for resending the reply according to its server machine's network routing configuration, not the list of addresses
5576 registered by the Cache Manager.</P
5580 >The Cache Manager does not use the list of interfaces when choosing the interface via which to establish a
5581 connection to a File Server.</P
5585 >The list of addresses that the <SPAN
5589 >fs getclientaddrs</B
5591 > command displays is not
5592 necessarily the one that a specific File Server is using, if an administrator has issued the <SPAN
5599 > command since the Cache Manager first contacted that File Server. It determines only which
5600 addresses the Cache Manager registers when connecting to File Servers in future.</P
5610 >To create or edit the client NetInfo file</A
5616 >Become the local superuser <SPAN
5622 > on the machine, if you are not already, by issuing
5630 CLASS="programlisting"
5647 >Using a text editor, open the <SPAN
5651 >/usr/vice/etc/NetInfo</B
5653 > file. Place one IP address in
5654 dotted decimal format (for example, <SAMP
5655 CLASS="computeroutput"
5656 >192.12.107.33</SAMP
5657 >) on each line. On the first line, put
5658 the address that you want each File Server to use initially. The order of the remaining machines does not matter, because
5659 if an RPC to the first interface fails, the File Server simultaneously sends RPCs to all of the other interfaces in the
5660 list. Whichever interface replies first is the one to which the File Server then sends pings and RPCs to break
5665 >If you want the Cache Manager to start using the revised list immediately, either reboot the machine, or use the
5670 >fs setclientaddrs</B
5672 > command to create the same list of addresses in kernel memory
5683 >To create or edit the client NetRestrict file</A
5689 >Become the local superuser <SPAN
5695 > on the machine, if you are not already, by issuing
5703 CLASS="programlisting"
5720 >Using a text editor, open the <SPAN
5724 >/usr/vice/etc/NetRestrict</B
5726 > file. Place one IP address
5727 in dotted decimal format on each line. The order of the addresses is not significant. Use the value <SPAN
5733 > as a wildcard that represents all possible addresses in that field. For example, the entry
5735 CLASS="computeroutput"
5736 >192.12.105.255</SAMP
5737 > indicates that the Cache Manager does not register any of the addresses in
5738 the 192.12.105 subnet.</P
5742 >If you want the Cache Manager to start using the revised list immediately, either reboot the machine, or use the
5747 >fs setclientaddrs</B
5749 > command to set a list of addresses that does not included the
5760 >To display the list of addresses from kernel memory</A
5770 >fs getclientaddrs</B
5773 CLASS="programlisting"
5778 >fs getclientaddrs</B
5790 > is an acceptable alias for <SPAN
5803 > is the shortest acceptable abbreviation).</P
5807 >The output lists each IP address on its own line, in dotted decimal format. </P
5815 >To set the list of addresses in kernel memory</A
5821 >Become the local superuser <SPAN
5827 > on the machine, if you are not already, by issuing
5835 CLASS="programlisting"
5856 >fs setclientaddrs</B
5858 > command to replace the list of addresses currently in
5859 kernel memory with a new list. <PRE
5860 CLASS="programlisting"
5865 >fs setclientaddrs</B
5875 >client network interfaces</VAR
5881 CLASS="variablelist"
5893 >Is an acceptable alias for <SPAN
5905 > is the shortest acceptable abbreviation).</P
5917 >Specifies one or more IP addresses in dotted decimal format (hostnames are not acceptable). Separate each
5918 address with one or more spaces.</P
5933 >Controlling the Display of Warning and Informational Messages</A
5936 >By default, the Cache Manager generates two types of warning and informational messages: <UL
5945 >, which provide user-level status and warning information, to user
5954 >console messages</I
5956 >, which provide system-level status and warning information, to the
5957 client machine's designated console.</P
5962 >You can use the <SPAN
5968 > command to control whether the Cache Manager displays either
5969 type of message, both types, or neither. It is best not to disable messages completely, because they provide useful
5972 >If you want to monitor Cache Manager status and performance more actively, you can use the <SPAN
5978 > program to collect an extensive set of statistics (it also gathers File Server statistics). If
5979 you experience performance problems, you can use <SPAN
5985 > suite of commands to gather a
5986 low-level trace of Cache Manager operations, which the AFS Support and Development groups can analyze to help solve your
5987 problem. To learn about both utilities, see <A
5989 >Monitoring and Auditing AFS Performance</A
5997 >To control the display of warning and status messages</A
6003 >Become the local superuser <SPAN
6009 > on the machine, if you are not already, by issuing
6017 CLASS="programlisting"
6040 > command, using the <SPAN
6047 argument to specify the type of messages to be displayed. <PRE
6048 CLASS="programlisting"
6053 >fs messages -show</B
6084 CLASS="variablelist"
6096 >Is the shortest acceptable abbreviation of <SPAN
6114 >Specifies the types of messages to display. Choose one of the following values: <DIV
6115 CLASS="variablelist"
6127 >Sends user messages to user screens.</P
6139 >Sends console messages to the console.</P
6151 >Sends user messages to user screens and console messages to the console (the default if the
6158 > argument is omitted).</P
6170 >Disables messages completely.</P
6189 >Displaying and Setting the System Type Name</A
6192 >The Cache Manager stores the system type name of the local client machine in kernel memory. It reads in the default value
6193 from a hardcoded definition in the AFS client software.</P
6195 >The Cache Manager uses the system name as a substitute for the @sys variable in AFS pathnames. The variable is useful when
6196 creating a symbolic link from the local disk to an AFS directory that houses binaries for the client machine's system type.
6197 Because the @sys variable automatically steers the Cache Manager to the appropriate directory, you can create the same symbolic
6198 link on client machines of different system types. (You can even automate the creation operation by using the package utility
6201 >Configuring Client Machines with the package Program</A
6202 >.) The link also remains valid
6203 when you upgrade the machine to a new system type.</P
6205 >Configuration is simplest if you use the system type names that AFS assigns. For a list, see the <SPAN
6214 >To display the system name stored in kernel memory, use the <SPAN
6226 > command. To change the name, add the latter command's <SPAN
6240 >To display the system type name</A
6260 CLASS="programlisting"
6280 >The output of the <SPAN
6286 > command has the following format:</P
6288 CLASS="programlisting"
6289 > Current sysname is 'system_name'
6298 > command displays the system_name string with no other text.</P
6306 >To change the system type name</A
6312 >Become the local superuser <SPAN
6318 > on the machine, if you are not already, by issuing
6326 CLASS="programlisting"
6349 > command, using the <SPAN
6356 argument to specify the new name. <PRE
6357 CLASS="programlisting"
6372 CLASS="variablelist"
6384 >Is the shortest acceptable abbreviation of <SPAN
6402 >Specifies the new system type name.</P
6417 >Enabling Asynchronous Writes</A
6420 >By default, the Cache Manager writes all data to the File Server immediately and synchronously when an application program
6421 closes a file. That is, the <SPAN
6427 > system call does not return until the Cache Manager has
6428 actually written all of the cached data from the file back to the File Server. You can enable the Cache Manager to write files
6429 asynchronously by specifying the number of kilobytes of a file that can remain to be written to the File Server when the Cache
6430 Manager returns control to the application.</P
6432 >Enabling asynchronous writes can be helpful to users who commonly work with very large files, because it usually means
6433 that the application appears to perform faster. However, it introduces some complications. It is best not to enable asynchronous
6434 writes unless the machine's users are sophisticated enough to understand the potential problems and how to avoid them. The
6435 complications include the following: <UL
6438 >In most cases, the Cache Manager returns control to applications earlier than it does by default, but it is not
6439 guaranteed to do so. Users cannot always expect faster performance.</P
6443 >If an asynchronous write fails, there is no way to notify the application, because the <SPAN
6449 > system call has already returned with a code indicating success.</P
6453 >Asynchronous writing increases the possibility that the user fails to notice when a write operation makes a volume
6454 exceed its quota. As always, the portion of the file that exceeds the quota is lost, as indicated by a message like the
6456 CLASS="programlisting"
6457 > No space left on device
6461 >To avoid losing data because of insufficient quota, before closing a file users must verify that the volume housing
6462 the file has enough free space to accommodate it.</P
6467 >When you enable asynchronous writes by issuing the <SPAN
6473 > command, you set the
6474 number of kilobytes of a file that can still remain to be written to the File Server when the Cache Manager returns control to
6475 the application program. You can apply the setting either to all files manipulated by applications running on the machine, or
6476 only to certain files: <UL
6479 >The setting that applies to all files is called the <SPAN
6483 >default store asynchrony</I
6486 and persists until the machine reboots. If, for example, you set the default store asynchrony to 10 KB, it means that when
6487 an application closes a file, the Cache Manager can return control to the application as soon as no more than 10 KB of a
6488 file that the application has closed remain to be written to the File Server.</P
6492 >The setting for an individual file overrides the default store asynchrony and persists as long as there is an entry
6493 for the file in the internal table that the Cache Manager uses to track information about files. In general, such an entry
6494 persists at least until an application closes the file or exits completely, but the Cache Manager is free to recycle the
6495 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
6502 > command shortly before closing the file.</P
6512 >To set the default store asynchrony</A
6518 >Become the local superuser <SPAN
6524 > on the machine, if you are not already, by issuing
6532 CLASS="programlisting"
6555 > command with the <SPAN
6562 CLASS="programlisting"
6567 >fs storebehind -allfiles</B
6571 >new default (KB)</VAR
6583 CLASS="variablelist"
6595 >Is the shortest acceptable abbreviation of <SPAN
6613 >Sets the number of kilobytes of data that can remain to be written to the File Server when the Cache Manager
6614 returns control to the application that closed a file.</P
6626 >Produces a message that confirms the new setting.</P
6640 >To set the store asynchrony for one or more files</A
6646 >Verify that you have the <SPAN
6659 the access control list (ACL) of each file for which you are setting the store asynchrony, by issuing the <SPAN
6665 > command, which is described fully in <A
6666 HREF="c31274.html#HDRWQ572"
6670 CLASS="programlisting"
6681 >Alternatively, become the local superuser <SPAN
6687 > on the client machine, if you are
6688 not already, by issuing the <SPAN
6696 CLASS="programlisting"
6718 > command with the <SPAN
6732 CLASS="programlisting"
6737 >fs storebehind -kbytes</B
6741 >asynchrony for specified names</VAR
6751 >specific pathnames</VAR
6764 CLASS="variablelist"
6776 >Is the shortest acceptable abbreviation of <SPAN
6794 >Sets the number of kilobytes of data that can remain to be written to the File Server when the Cache Manager
6795 returns control to the application that closed a file named by the <SPAN
6814 >Specifies each file for which to set a store asynchrony that overrides the default. Partial pathnames are
6815 interpreted relative to the current working directory.</P
6827 >Produces a message that confirms that new setting.</P
6841 >To display the default store asynchrony</A
6853 > command with no arguments, or with the <SPAN
6860 CLASS="programlisting"
6878 CLASS="variablelist"
6890 >Is the shortest acceptable abbreviation of <SPAN
6908 >Produces output that reports the default store asynchrony.</P
6922 >To display the store asynchrony for one or more files</A
6934 > command with the <SPAN
6942 CLASS="programlisting"
6957 >specific pathnames</VAR
6963 CLASS="variablelist"
6975 >Is the shortest acceptable abbreviation of <SPAN
6993 >Specifies each file for which to display the store asynchrony. Partial pathnames are interpreted relative to
6994 the current working directory.</P
7002 >The output lists each file separately. If a value has previously been set for the specified files, the output reports
7005 CLASS="programlisting"
7006 > Will store up to y kbytes of file asynchronously.
7007 Default store asynchrony is x kbytes.
7010 >If the default store asynchrony applies to a file (because you have not set a <SPAN
7017 value for it), the output reports the following:</P
7019 CLASS="programlisting"
7020 > Will store file according to default.
7021 Default store asynchrony is x kbytes.
7031 SUMMARY="Footer navigation table"
7070 >Managing Client Machines</TD
7084 >Configuring Client Machines with the package Program</TD
git://git.openafs.org / openafs.git / blob