Determining the Cache Type, Size, and Location

This section explains how to configure a memory or disk cache, how to display and set the size of either type of cache, and how to set the location of the cache directory for a disk cache.

The Cache Manager uses a disk cache by default, and it is the preferred type of caching. To configure a memory cache, include the -memcache flag on the afsd command, which is normally invoked in the machine's AFS initialization file. If configured to use a memory cache, the Cache Manager does no disk caching, even if the machine has a disk.

Choosing the Cache Size

Cache size influences the performance of a client machine more directly than perhaps any other cache parameter. The larger the cache, the faster the Cache Manager is likely to deliver files to users. A small cache can impair performance because it increases the frequency at which the Cache Manager must discard cached data to make room for newly requested data. When an application asks for data that has been discarded, the Cache Manager must request it from the File Server, and fetching data across the network is almost always slower than fetching it from the local disk. The Cache Manager never discards data from a file that has been modified locally but not yet stored back to the File Server. If the cache is very small, the Cache Manager possible cannot find any data to discard. For more information about the algorithm it uses when discarding cached data, see How the Cache Manager Chooses Data to Discard).

The amount of disk or memory you devote to caching depends on several factors. The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute limit. In addition, you cannot allocate more than 95% of the space available on the cache directory's partition to a disk cache. The afsd program exits without starting the Cache Manager and prints an appropriate message to the standard output stream if you violate this restriction. For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate more memory than is actually available, the afsd program exits without initializing the Cache Manager and produces the following message on the standard output stream:

   afsd: memCache allocation failure at number KB

where number is how many kilobytes were allocated just before the failure.

Within these hard limits, the factors that determine appropriate cache size include the number of users working on the machine, the size of the files with which they usually work, and (for a memory cache) the number of processes that usually run on the machine. The higher the demand from these factors, the larger the cache needs to be to maintain good performance.

Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on the factors mentioned previously, and is difficult to predict.

Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use a smaller memory cache.

AFS imposes an absolute limit on cache size in some versions. See the OpenAFS Release Notes for the version you are using.

Displaying and Setting the Cache Size and Location

The Cache Manager determines how big to make the cache by reading the /usr/vice/etc/cacheinfo file as it initializes. As directed in the OpenAFS Quick Beginnings, you must create the file before running the afsd program. The file also defines the directory on which to mount AFS (by convention, /afs), and the local disk directory to use for a cache directory.

To change any of the values in the file, log in as the local superuser root. You must reboot the machine to have the new value take effect. For instructions, see To edit the cacheinfo file.

To change the cache size at reboot without editing the cacheinfo file, include the -blocks argument to the afsd command; see the command's reference page in the OpenAFS Administration Reference.

For a disk cache, you can also use the fs setcachesize command to reset the cache size without rebooting. The value you set persists until the next reboot, at which time the cache size returns to the value specified in the cacheinfo file or by the -blocks argument to the afsd command. For instructions, see To change the disk cache size without rebooting.

To display the current cache size and the amount of space the Cache Manager is using at the moment, use the fs getcacheparms command as detailed in To display the current cache size.

To display the cache size set at reboot

  1. Use a text editor or the cat command to display the contents of the /usr/vice/etc/cacheinfo file.

       % cat /usr/vice/etc/cacheinfo
    

To display the current cache size

  1. Issue the fs getcacheparms command on the client machine.

       % fs getcacheparms
    

    where getca is the shortest acceptable abbreviation of getcacheparms.

    The output shows the number of kilobyte blocks the Cache Manager is using as a cache at the moment the command is issued, and the current size of the cache. For example:

       AFS using 13709 of the cache's available 15000 1K byte blocks.
    

To edit the cacheinfo file

  1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: <root_password>
    
  2. Use a text editor to edit the /usr/vice/etc/cacheinfo file, which has three fields, separated by colons:

    • The first field names the local directory on which to mount the AFS filespace. The conventional location is /afs.

    • The second field defines the local disk directory to use for the disk cache. The conventional location is the /usr/vice/cache directory, but you can specify an alternate directory if another partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the machine uses a memory cache.

    • The third field defines cache size as a number of kilobyte (1024-byte) blocks.

    The following example mounts the AFS filespace at the /afs directory, names /usr/vice/cache as the cache directory, and sets cache size to 50,000 KB:

                /afs:/usr/vice/cache:50000
              

To change the disk cache size without rebooting

  1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: <root_password>
    
  2. Issue the fs setcachesize command to set a new disk cache size.

    Note

    This command does not work for a memory cache.

       # fs setcachesize <size in 1K byte blocks (0 => reset)>
    

    where

    setca

    Is the shortest acceptable abbreviation of setcachesize.

    size in 1K byte blocks (0 => reset)

    Sets the number of kilobyte blocks to be used for the cache. Specify a positive integer (1024 equals 1 MB), or 0 (zero) to reset the cache size to the value specified in the cacheinfo file.

To reset the disk cache size to the default without rebooting

  1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: <root_password>
    
  2. Issue the fs setcachesize command to reset the size of the local disk cache (the command does not work for a memory cache). Choose one of the two following options:

    • To reset the cache size to the value specified in the local cacheinfo file, specify the value 0 (zero)

         # fs setcachesize 0
      
    • To reset the cache size to the value set at the last reboot of the machine, include the -reset flag. Unless the -blocks argument was used on the afsd command, this is also the value in the cacheinfo file.

         # fs setcachesize -reset
      

    where

    setca

    Is the shortest acceptable abbreviation of setcachesize.

    0

    Resets the disk cache size to the value in the third field of the /usr/vice/etc/cacheinfo file.

    -reset

    Resets the cache size to the value set at the last reboot.

How the Cache Manager Chooses Data to Discard

When the cache is full and application programs request more data from AFS, the Cache Manager must flush out cache chunks to make room for the data. The Cache Manager considers two factors:

  1. How recently an application last accessed the data.

  2. Whether the chunk is dirty. A dirty chunk contains changes to a file that have not yet been saved back to the permanent copy stored on a file server machine.

The Cache Manager first checks the least-recently used chunk. If it is not dirty, the Cache Manager discards the data in that chunk. If the chunk is dirty, the Cache Manager moves on to check the next least recently used chunk. It continues in this manner until it has created a sufficient number of empty chunks.

Chunks that contain data fetched from a read-only volume are by definition never dirty, so the Cache Manager can always discard them. Normally, the Cache Manager can also find chunks of data fetched from read/write volumes that are not dirty, but a small cache makes it difficult to find enough eligible data. If the Cache Manager cannot find any data to discard, it must return I/O errors to application programs that request more data from AFS. Application programs usually have a means for notifying the user of such errors, but not for revealing their cause.