Ubuntu Manpage: /etc/cachefilesd.conf - Local file caching configuration file

Provided by: cachefilesd_0.10.10-0.2ubuntu1_amd64

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:

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.

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

       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.

CACHE CULLING

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.

AUTHORS