CACHEFILESD.CONF(5)

💖 CACHEFILESD.CONF(5) 💖

okay bestie, welcome to the manual page for /etc/cachefilesd.conf — that's the local file caching configuration file from the Cache Files Utilities, and we are gonna make it make sense, fr fr. 🎀

✨ SYNOPSIS ✨

This is the config file for cachefilesd, which can manage a persistent cache for a whole variety of network filesystems, using a set of files on an already-mounted filesystem as the data store. She's the blueprint, periodt. 💅

🌸 DESCRIPTION 🌸

This config file can hold a bunch of commands. Each one goes on its own line, no sharing, okay? Blank lines and any line starting with a # are comments and get yeeted immediately. Not me being selective, it's literally in the spec. 🦋

The one and only mandatory command is:

• dir <path> — says which directory holds the root of the cache. It may only be specified once per configuration file. That's it, that's the non-negotiable one. 👑

Every other command is optional, and there are a LOT of them:

• secctx <label> — specify an LSM security context that the kernel will perform operations as when it accesses the cache. The default is to use cachefilesd's own security context. Files get created in the cache with the label of the directory you gave to the dir command.
• brun <N>%
• bcull <N>%
• bstop <N>%
• frun <N>%
• fcull <N>%
• fstop <N>% — these six configure the culling limits. The defaults are 7% (run), 5% (cull) and 1% (stop) respectively. Peep the cache culling section below for the whole lore.

the commands starting with a b are file space (block) limits, and the ones starting with an f are file count limits. b for block, f for files, iconic mnemonic behavior honestly.

• tag <name> — gives FS-Cache a tag to use when telling multiple caches apart. You only need this if more than one cache is gonna be in use. Default is "CacheFiles".
• culltable <log2size> — sets the size of the tables that hold the lists of cullable objects in the cache. Bigger number = faster and smoother culling when there are a ton of objects in the cache, but it also eats more memory from cachefilesd. It's given as the log2 of the size you actually need — so 12 means a table of 4096 entries and 13 means 8192 entries. Permissible values are between 12 and 20, and 20 means 1048576 entries. Default is 12.
• nocull — disables culling entirely. Culling and building the cull table do take up a certain amount of a system's resources, which may be undesirable, so supplying this option turns off all culling activity. The cache will just keep building up to the limits that were set and won't be shrunk — except by removal of out-dated cache files. so like, it stays big. that's the deal. 😭
• resume_thresholds <blocks> <files> — says how many blocks or files the kernel should let go of before the daemon should resume from culling table scan suspension. Scanning to refill the cull table gets suspended when every object in a cache is pinned by a live network filesystem in the kernel and there's nothing to cull. Either value can be - to say that threshold should be ignored. flexible queen. 🫶
• debug <mask> — a numeric bitmask that controls debugging in the kernel module. Default is zero (all off). These values can be OR'd into the mask to collect various info:
  1. 1 — turn on trace of function entry (_enter() macros)
  2. 2 — turn on trace of function exit (_leave() macros)
  3. 4 — turn on trace of internal debug points (_debug())

This mask can also be set through /sys/module/cachefiles/parameters/debug.

🧚 EXAMPLES 🧚

As an example, consider the following:

dir /var/cache/fscache
secctx cachefiles_kernel_t
tag mycache
brun 10%
bcull 7%
bstop 3%
secctx system_u:system_r:cachefiles_kernel_t:s0

So what's happening here? This places the cache storage objects in a directory called "/var/cache/fscache", names the cache "mycache", and permits the cache to run freely as long as there's at least 10% free space on /var/cache/fscache/. It starts culling the cache when the free space drops below 7%, and stops writing new stuff into the cache if the amount of free space drops below 3%. If the cache gets suspended, it won't reactivate until the amount of free space rises again to 10% or better. self-healing behavior, we love to see it. ✨

Furthermore, this tells the kernel module the security context it should use when accessing the cache (SELinux is assumed to be the LSM in this example). In this case, SELinux would use cachefiles_kernel_t as the key into the policy. 🔑

👑 CACHE CULLING 👑

The cache may need culling occasionally to make space. That involves discarding objects from the cache that have been used less recently than anything else. Culling is based on the access time of data objects. Empty directories get culled if they're not in use. it's giving spring cleaning but automated. 🌸

Cache culling happens on the basis of the percentage of blocks and the percentage of files available in the underlying filesystem. There are six "limits":

• brun
• frun — if the amount of free space and the number of available files in the cache rises above both these limits, then culling is turned off.
• bcull
• fcull — if the amount of available space or the number of available files in the cache falls below either of these limits, then culling is started.
• bstop
• fstop — if the amount of available space or the number of available files in the cache falls below either of these limits, then no further allocation of disk space or files is permitted until culling has raised things above these limits again.

These must be configured thusly:

0 <= bstop < bcull < brun < 100
0 <= fstop < fcull < frun < 100

Note that these are percentages of available space and available files, and do not appear as 100 minus the percentage displayed by the df program. Do not get got by this. 🙈

The userspace daemon scans the cache to build up a table of cullable objects. These are then culled in least recently used order. A new scan of the cache is started as soon as space is made in the table. Objects will be skipped if their atimes have changed, or if the kernel module says it's still using them. respectful of boundaries, as she should be. 💜

Culling can be disabled with the nocull option.

🌈 SEE ALSO 🌈

• cachefilesd(8)
• df(1)
• /usr/share/doc/cachefilesd/README

🎀 AUTHORS 🎀

David Howells <dhowells@redhat.com> — thank you for your service, king. 🫶

and that's the whole page, bestie!! this one came out of the Linux world on 14 November 2005, so shoutout to the elders for keeping the receipts. you understood it, you ate, no crumbs left. bye pookie 💖✨🎀🦋🌸💅