| .\" -*- nroff -*- |
| .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. |
| .\" Written by David Howells (dhowells@redhat.com) |
| .\" |
| .\" This program is free software; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License |
| .\" as published by the Free Software Foundation; either version |
| .\" 2 of the License, or (at your option) any later version. |
| .\" |
| .TH CACHEFILESD.CONF 5 "14 November 2005" Linux "Cache Files Utilities" |
| .SH NAME |
| /etc/cachefilesd.conf \- Local file caching configuration file |
| .SH SYNOPSIS |
| .P |
| 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. |
| .SH DESCRIPTION |
| .P |
| 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. |
| .P |
| The only mandatory command is: |
| .TP |
| .B dir <path> |
| This command specifies the directory containing the root of the cache. It may |
| only specified once per configuration file. |
| .P |
| All the other commands are optional: |
| .TP |
| .B 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. |
| .TP |
| .B brun <N>% |
| .TP |
| .B bcull <N>% |
| .TP |
| .B bstop <N>% |
| .TP |
| .B frun <N>% |
| .TP |
| .B fcull <N>% |
| .TP |
| .B 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. |
| .IP |
| The commands beginning with a 'b' are file space (block) limits, those |
| beginning with an 'f' are file count limits. |
| .TP |
| .B 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". |
| .TP |
| .B 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. |
| .IP |
| 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. |
| .TP |
| .B 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. |
| .TP |
| .B 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: |
| .RS |
| .TP |
| .B 1 |
| Turn on trace of function entry (_enter() macros) |
| .TP |
| .B 2 |
| Turn on trace of function exit (_leave() macros) |
| .TP |
| .B 4 |
| Turn on trace of internal debug points (_debug()) |
| .RE |
| .IP |
| This mask can also be set through /sys/module/cachefiles/parameters/debug. |
| .RE |
| .SH EXAMPLES |
| .P |
| As an example, consider the following: |
| .P |
| .RS |
| dir /var/cache/fscache |
| .br |
| secctx cachefiles_kernel_t |
| .br |
| tag mycache |
| .br |
| brun 10% |
| .br |
| bcull 7% |
| .br |
| bstop 3% |
| .br |
| secctx system_u:system_r:cachefiles_kernel_t:s0 |
| .RE |
| .P |
| 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. |
| .P |
| 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. |
| .SH CACHE CULLING |
| .P |
| 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. |
| .P |
| 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": |
| .TP |
| .B brun |
| .TP |
| .B 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. |
| .TP |
| .B bcull |
| .TP |
| .B 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. |
| .TP |
| .B bstop |
| .TP |
| .B 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. |
| .P |
| These must be configured thusly: |
| .IP |
| 0 <= bstop < bcull < brun < 100 |
| .br |
| 0 <= fstop < fcull < frun < 100 |
| .P |
| Note that these are percentages of available space and available files, and do |
| \fInot\fP appear as 100 minus the percentage displayed by the \fBdf\fP program. |
| .P |
| 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. |
| .P |
| Culling can be disabled with the \fBnocull\fP option. |
| .SH SEE ALSO |
| \fBcachefilesd\fR(8), \fBdf\fR(1), /usr/share/doc/cachefilesd-*/README |
| .SH AUTHORS |
| .br |
| David Howells <dhowells@redhat.com> |