man > CACHEFILESD.CONF(5)

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:

       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 cre‐
              ated 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 pro‐
              ceed 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  indi‐
              cates  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 col‐
              lect 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 access‐
       ing  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  ac‐
       cess 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.

SEE ALSO
       cachefilesd(8), df(1), /usr/share/doc/cachefilesd/README

AUTHORS
       David Howells <dhowells AT redhat.com>

Linux                                     14 November 2005                       CACHEFILESD.CONF(5)