NAME

       afs_cache - Format of data stored in an AFS client disk cache

DESCRIPTION

       The disk cache on a client machine is composed of multiple Vn files that contain the data, a CacheItems
       file that records index information for all of the Vn files, and a VolumeItems file that records the
       mapping between volume name and mount point for volumes.

       When it initializes, the Cache Manager creates the cache files in the configured cache location.  The
       standard directory name is /usr/vice/cache, but it is acceptable to use a directory on a partition with
       more available space. To designate a different directory, change the value in the second field of the
       /etc/openafs/cacheinfo file before issuing the afsd command, or include the -cachedir argument to the
       afsd command.

   CacheItems
       The CacheItems file records information about each file in the disk cache on a client machine (each Vn
       file). The information includes the file ID number and associated volume version number of the AFS file
       currently stored in the Vn file, which enables the Cache Manager to determine which Vn file contains the
       AFS data it needs to present to an application.

       As it initializes, the Cache Manager creates the binary-format CacheItems file in the same local disk
       cache directory as the Vn files that the CacheItems file describes, and it must always remain there.

   VolumeItems
       The VolumeItems file records the mapping between volume name and mount point for each volume that the
       Cache Manager has accessed since it initialized on a client machine using a disk cache. The Cache Manager
       uses the mappings to respond correctly to queries about the current working directory, which can come
       from the operating system or commands such as the UNIX pwd command.

       As it initializes, the Cache Manager creates the binary-format VolumeItems file in the local disk cache
       directory, and it must always remain there.

   Vn
       A Vn file can store a chunk of cached AFS data on a client machine that is using a disk cache. As the
       Cache Manager initializes, it verifies that the local disk cache directory houses a number of Vn files
       equal to the largest of the following:

       •   100

       •   One  and  a half times the result of dividing the cache size by the chunk size (cachesize/chunksize *
           1.5).

       •   The result of dividing the cache size by 10 MB (10,240).

       The Cache Manager determines the cache size from the -blocks argument to the  afsd  command,  or  if  the
       argument  is  not  included,  from the third field of the /etc/openafs/cacheinfo file.  The default chunk
       size is 64 KB; use the -chunksize argument to the afsd command to override it. To  override  the  default
       number of chunks resulting from the calculation, include the -files argument to the afsd command. afsd(8)
       describes the restrictions on acceptable values for each of the arguments.

       If  the  disk  cache  directory houses fewer Vn files than necessary, the Cache Manager creates new ones,
       assigning each a unique integer n that distinguishes it from the other files; the integers start  with  1
       and  increment  by  one  for each Vn file created. The Cache Manager removes files if there are more than
       necessary. The Cache Manager also adds and removes Vn files in response to the fs  setcachesize  command,
       which can be used to alter the cache size between reboots.

       Vn  files  expand  and  contract  to  accommodate  the  size  of  the  AFS directory listing or file they
       temporarily house. As mentioned, by default each Vn file holds up to 64 KB (65,536 bytes) of a cached AFS
       element. AFS elements larger than 64 KB are divided among multiple Vn files. If  an  element  is  smaller
       than  64 KB, the Vn file expands only to the required size. A Vn file accommodates only a single element,
       so if there many small cached elements, it is possible to exhaust the available Vn files without reaching
       the maximum cache size.

CAUTIONS

       Editing or removing the CacheItems or VolumeItems files or a Vn file can cause a  kernel  panic.  If  the
       contents  of  Vn files seem out of date, clear the files by using the fs flush or fs flushvolume command.
       If any of the cache files are accidentally modified or deleted, rebooting the  machine  usually  restores
       normal performance.

       To  alter  cache size (and thus the number of Vn files) between reboots, use the fs setcachesize command.
       Alternatively, alter the value of the -blocks, -files or -chunksize arguments to the afsd command invoked
       in the machine's AFS initialization file, and reboot. To refresh the contents of one or  more  Vn  files,
       use the fs flush or fs flushvolume command.

SEE ALSO

       cacheinfo(5), afsd(8), fs_checkvolumes(1), fs_flush(1), fs_flushvolume(1), fs_setcachesize(1)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This  documentation  is covered by the IBM Public License Version 1.0.  It was converted from HTML to POD
       by software written by Chas Williams and Russ Allbery, based on  work  by  Alf  Wachsmann  and  Elizabeth
       Cassell.

OpenAFS                                            2024-08-27                                       AFS_CACHE(5)