AFS_CACHE(5)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

✨ NAME ✨

afs_cache — the tea on how the AFS client disk cache is formatted 💾✨

okay bestie, this is the AFS_CACHE(5) page from the AFS File Reference section and it's literally about the secret inner life of your disk cache 🫶

🌸 DESCRIPTION 🌸

So. The disk cache on a client machine is made up of:

  • a bunch of Vn files that hold the actual data 💖
  • a CacheItems file that keeps the index info for all the Vn files 👑
  • a VolumeItems file that stores 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 lowkey it's totally acceptable to use a directory on a partition with more available space 💅. If you wanna point it somewhere else, change the value in the second field of the /etc/openafs/cacheinfo file before you issue the afsd command, or just include the -cachedir argument to the afsd command. easy 🎀

💖 CacheItems 💖

The CacheItems file records info about each file in the disk cache on a client machine (that's each Vn file, bestie). What kind of info? The file ID number and the associated volume version number of the AFS file currently stored in the Vn file 🗂️. That's what lets the Cache Manager figure out which Vn file has the AFS data it needs to hand to an application. iconic behavior fr fr.

When 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. no moving it, it lives there now 🏠

🌈 VolumeItems 🌈

The VolumeItems file records the mapping between volume name and mount point for every volume the Cache Manager has accessed since it initialized on a client machine using a disk cache 💫. The Cache Manager uses those mappings to answer queries about the current working directory correctly — and those queries can come from the operating system or from commands like the UNIX pwd command 👀.

When it initializes, the Cache Manager creates the binary-format VolumeItems file in the local disk cache directory, and it must always remain there. same rules, bestie 💀

🦋 Vn 🦋

A Vn file stores a chunk of cached AFS data on a client machine 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 figures out the cache size from the -blocks argument to the afsd command, or if that argument isn't 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. And if you wanna override the default number of chunks that comes out of that calculation, include the -files argument to the afsd command. afsd(8) describes the restrictions on acceptable values for each of those arguments — go read it, iykyk 📚

If the disk cache directory houses fewer Vn files than necessary, the Cache Manager creates new ones, giving each a unique integer n that tells it apart from the others; the integers start with 1 and increment by one for each Vn file created 🔢. And if there are more than necessary, the Cache Manager removes files. It also adds and removes Vn files in response to the fs setcachesize command, which you can use to alter the cache size between reboots 🌙.

Vn files expand and contract to fit the size of the AFS directory listing or file they're temporarily housing, so they're flexible like that 💃. As mentioned, by default each Vn file holds up to 64 KB (65,536 bytes) of a cached AFS element. AFS elements bigger than 64 KB get divided among multiple Vn files 🍰. If an element is smaller than 64 KB, the Vn file expands only to the required size. And here's the catch bestie — a Vn file accommodates only a single element, so if you have many small cached elements, it is possible to exhaust the available Vn files without reaching the maximum cache size. it's giving "why is my cache full, it's not even full" 😭

💀 CAUTIONS 💀

okay listen up, this part is serious. Editing or removing the CacheItems or VolumeItems files, or a Vn file, can cause a kernel panic 🚨. not cute, not slay, do not do it.

If the contents of Vn files seem out of date, clear the files by using the fs flush or fs flushvolume command 🧹. And 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 💅

bestie do NOT hand-edit cache files. i am begging. kernel panic is not a personality trait 🫶

👑 SEE ALSO 👑

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 🫶

that's the whole page bestie, we ate and left no crumbs 💖✨ this one's from the OpenAFS girlies, dated 2026-07-27 — go forth and never touch your cache files manually 🌸🦋💅

📦 where this page comes from