CACHEFILESD.CONF(5) Cache Files Utilities CACHEFILESD.CONF(5)NAME
/etc/cachefilesd.conf - Local file caching configuration file
SYNOPSIS
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.
DESCRIPTION
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:
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 distinguish‐
ing 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 indi‐
cates 8192 entries. The permissible values are between 12 and
20, the latter indicating 1048576 entries. The default is 12.
debug <mask>
This command specifies a numeric bitmask to control debugging in
the kernel module. The default is zero (all off). The follow‐
ing values can be OR'd into the mask to collect various informa‐
tion:
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/parame‐
ters/debug.
EXAMPLES
As an example, consider the following:
dir /var/fscache
tag mycache
brun 10%
bcull 7%
bstop 3%
The places the cache storage objects in a directory called
"/var/fscache", names the cache "mycache", permits the cache to run
freely as long as there's at least 10% free space on /var/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.
CACHE CULLING
The cache may need culling occasionally to make space. This involves
discarding objects from the cache that are no longer marked as being in
use by the network filesystem. Objects are selected from this group
based on which has the least recent access time. Empty directories are
culled if not in use.
Note: The current culling algorithm has a limitation whereby
objects may remain in the cache longer than one might expect -
this is because a cache object cannot be culled until the net‐
work filesystem using it has released all its references. In
the case of NFS, this means that the in-memory record of the
inode must be discarded first. This record will be pinned in
memory whilst the inode has open file descriptors on it or bits
of the inode are memory mapped.
Once all references to the NFS inode are released, the inode
record will be retained in memory until memory pressure causes
it to be discarded, or the inode is deleted or the filesystem is
unmounted. Only then will the cache object be available for
culling.
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 pro‐
gram.
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.
SEE ALSOcachefilesd(8), df(1), /usr/share/doc/cachefilesd-*/README
AUTHORS
The cachefilesd software has been developed by David Howells
Linux 14 November 2005 CACHEFILESD.CONF(5)
