/etc/cachefilesd.conf - Local file caching configuration file
The configuration file for cachefilesd which can manage a
persistent cache for a variety of network filesystems using a set of files
on an already mounted filesystem as the data store.
This configuration file can contain a number of commands. Each one
should be on a separate line. Blank lines and lines beginning with a '#'
character are considered to be comments and are discarded.
The only mandatory command is:
- dir <path>
- This command specifies the directory containing the root of the cache. It
may only specified once per configuration file.
All the other commands are optional:
- secctx
<label>
- Specify an LSM security context as which the kernel will perform
operations to access the cache. The default is to use cachefilesd's
security context. Files will be created in the cache with the label of
directory specified to the 'dir' command.
- brun <N>%
- bcull <N>%
- bstop <N>%
- frun <N>%
- fcull <N>%
- fstop <N>%
- These commands configure the culling limits. The defaults are 7% (run), 5%
(cull) and 1% (stop) respectively. See the section on cache culling for
more information.
- The commands beginning with a 'b' are file space (block) limits, those
beginning with an 'f' are file count limits.
- tag <name>
- This command specifies a tag to FS-Cache to use in distinguishing multiple
caches. This is only required if more than one cache is going to be used.
The default is "CacheFiles".
- culltable
<log2size>
- This command specifies the size of the tables holding the lists of
cullable objects in the cache. The bigger the number, the faster and more
smoothly that culling can proceed when there are many objects in the
cache, but the more memory will be consumed by cachefilesd.
- The quantity is specified as log2 of the size actually required, for
example 12 indicates a table of 4096 entries and 13 indicates 8192
entries. The permissible values are between 12 and 20, the latter
indicating 1048576 entries. The default is 12.
- nocull
- Disable culling. Culling and building up the cull table take up a certain
amount of a systems resources, which may be undesirable. Supplying this
option disables all culling activity. The cache will keep building up to
the limits set and won't be shrunk, except by the removal of out-dated
cache files.
- resume_thresholds
<blocks> <files>
- This command specifies the amount of blocks or files that the kernel
should let go of before the daemon should resume from culling table scan
suspension.
- Scanning to refill the cull table is suspended when all the objects in a
cache are pinned by a live network filesystem in the kernel and there's
nothing to cull.
- Either value can be "-" to indicate that this threshold should
be ignored.
- debug
<mask>
- This command specifies a numeric bitmask to control debugging in the
kernel module. The default is zero (all off). The following values can be
OR'd into the mask to collect various information:
- 1
- Turn on trace of function entry (_enter() macros)
- 2
- Turn on trace of function exit (_leave() macros)
- 4
- Turn on trace of internal debug points (_debug())
- This mask can also be set through
/sys/module/cachefiles/parameters/debug.
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
This places the cache storage objects in a directory called
"/var/cache/fscache", names the cache "mycache", permits
the cache to run freely as long as there's at least 10% free space on
/var/cache/fscache/, 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 is suspended, it won't reactivate until
the amount of free space rises again to 10% or better.
Furthermore, this will tell 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.
The cache may need culling occasionally to make space. This
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 are culled if not in use.
Cache culling is done 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.
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
is still using them.
Culling can be disabled with the nocull option.
David Howells <dhowells@redhat.com>