Documentation/filesystems/caching/cachefiles.txt

   1                ===============================================
   2                CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM
   3                ===============================================
   4
   5 Contents:
   6
   7  (*) Overview.
   8
   9  (*) Requirements.
  10
  11  (*) Configuration.
  12
  13  (*) Starting the cache.
  14
  15  (*) Things to avoid.
  16
  17
  18 ========
  19 OVERVIEW
  20 ========
  21
  22 CacheFiles is a caching backend that's meant to use as a cache a directory on
  23 an already mounted filesystem of a local type (such as Ext3).
  24
  25 CacheFiles uses a userspace daemon to do some of the cache management - such as
  26 reaping stale nodes and culling.  This is called cachefilesd and lives in
  27 /sbin.
  28
  29 The filesystem and data integrity of the cache are only as good as those of the
  30 filesystem providing the backing services.  Note that CacheFiles does not
  31 attempt to journal anything since the journalling interfaces of the various
  32 filesystems are very specific in nature.
  33
  34 CacheFiles creates a proc-file - "/proc/fs/cachefiles" - that is used for
  35 communication with the daemon.  Only one thing may have this open at once, and
  36 whilst it is open, a cache is at least partially in existence.  The daemon
  37 opens this and sends commands down it to control the cache.
  38
  39 CacheFiles is currently limited to a single cache.
  40
  41 CacheFiles attempts to maintain at least a certain percentage of free space on
  42 the filesystem, shrinking the cache by culling the objects it contains to make
  43 space if necessary - see the "Cache Culling" section.  This means it can be
  44 placed on the same medium as a live set of data, and will expand to make use of
  45 spare space and automatically contract when the set of data requires more
  46 space.
  47
  48
  49 ============
  50 REQUIREMENTS
  51 ============
  52
  53 The use of CacheFiles and its daemon requires the following features to be
  54 available in the system and in the cache filesystem:
  55
  56         - dnotify.
  57
  58         - extended attributes (xattrs).
  59
  60         - openat() and friends.
  61
  62         - bmap() support on files in the filesystem (FIBMAP ioctl).
  63
  64         - The use of bmap() to detect a partial page at the end of the file.
  65
  66 It is strongly recommended that the "dir_index" option is enabled on Ext3
  67 filesystems being used as a cache.
  68
  69
  70 =============
  71 CONFIGURATION
  72 =============
  73
  74 The cache is configured by a script in /etc/cachefilesd.conf.  These commands
  75 set up cache ready for use.  The following script commands are available:
  76
  77  (*) brun <N>%
  78  (*) bcull <N>%
  79  (*) bstop <N>%
  80
  81         Configure the culling limits.  Optional.  See the section on culling
  82         The defaults are 7%, 5% and 1% respectively.
  83
  84  (*) dir <path>
  85
  86         Specify the directory containing the root of the cache.  Mandatory.
  87
  88  (*) tag <name>
  89
  90         Specify a tag to FS-Cache to use in distinguishing multiple caches.
  91         Optional.  The default is "CacheFiles".
  92
  93  (*) debug <mask>
  94
  95         Specify a numeric bitmask to control debugging in the kernel module.
  96         Optional.  The default is zero (all off).  The following values can be
  97         OR'd into the mask to collect various information:
  98
  99                 1       Turn on trace of function entry (_enter() macros)
 100                 2       Turn on trace of function exit (_leave() macros)
 101                 4       Turn on trace of internal debug points (_debug())
 102
 103         This mask can also be set through /proc/sys/fs/cachefiles/debug.
 104
 105
 106 ==================
 107 STARTING THE CACHE
 108 ==================
 109
 110 The cache is started by running the daemon.  The daemon opens the cache proc
 111 file, configures the cache and tells it to begin caching.  At that point the
 112 cache binds to fscache and the cache becomes live.
 113
 114 The daemon is run as follows:
 115
 116         /sbin/cachefilesd [-d]* [-s] [-n] [-f <configfile>]
 117
 118 The flags are:
 119
 120  (*) -d
 121
 122         Increase the debugging level.  This can be specified multiple times and
 123         is cumulative with itself.
 124
 125  (*) -s
 126
 127         Send messages to stderr instead of syslog.
 128
 129  (*) -n
 130
 131         Don't daemonise and go into background.
 132
 133  (*) -f <configfile>
 134
 135         Use an alternative configuration file rather than the default one.
 136
 137
 138 ===============
 139 THINGS TO AVOID
 140 ===============
 141
 142 Do not mount other things within the cache as this will cause problems.  The
 143 kernel module contains its own very cut-down path walking facility that ignores
 144 mountpoints, but the daemon can't avoid them.
 145
 146 Do not create, rename or unlink files and directories in the cache whilst the
 147 cache is active, as this may cause the state to become uncertain.
 148
 149 Renaming files in the cache might make objects appear to be other objects (the
 150 filename is part of the lookup key).
 151
 152 Do not change or remove the extended attributes attached to cache files by the
 153 cache as this will cause the cache state management to get confused.
 154
 155 Do not create files or directories in the cache, lest the cache get confused or
 156 serve incorrect data.
 157
 158 Do not chmod files in the cache.  The module creates things with minimal
 159 permissions to prevent random users being able to access them directly.
 160
 161
 162 =============
 163 CACHE CULLING
 164 =============
 165
 166 The cache may need culling occasionally to make space.  This involves
 167 discarding objects from the cache that have been used less recently than
 168 anything else.  Culling is based on the access time of data objects.  Empty
 169 directories are culled if not in use.
 170
 171 Cache culling is done on the basis of the percentage of blocks available in the
 172 underlying filesystem.  There are three "limits":
 173
 174  (*) brun
 175
 176      If the amount of available space in the cache rises above this limit, then
 177      culling is turned off.
 178
 179  (*) bcull
 180
 181      If the amount of available space in the cache falls below this limit, then
 182      culling is started.
 183
 184  (*) bstop
 185
 186      If the amount of available space in the cache falls below this limit, then
 187      no further allocation of disk space is permitted until culling has raised
 188      the amount above this limit again.
 189
 190 These must be configured thusly:
 191
 192         0 <= bstop < bcull < brun < 100
 193
 194 Note that these are percentages of available space, and do _not_ appear as 100
 195 minus the percentage displayed by the "df" program.
 196
 197 The userspace daemon scans the cache to build up a table of cullable objects.
 198 These are then culled in least recently used order.  A new scan of the cache is
 199 started as soon as space is made in the table.  Objects will be skipped if
 200 their atimes have changed or if the kernel module says it is still using them.
 201
 202
 203 ===============
 204 CACHE STRUCTURE
 205 ===============
 206
 207 The CacheFiles module will create two directories in the directory it was
 208 given:
 209
 210  (*) cache/
 211
 212  (*) graveyard/
 213
 214 The active cache objects all reside in the first directory.  The CacheFiles
 215 kernel module moves any retired or culled objects that it can't simply unlink
 216 to the graveyard from which the daemon will actually delete them.
 217
 218 The daemon uses dnotify to monitor the graveyard directory, and will delete
 219 anything that appears therein.
 220
 221
 222 The module represents index objects as directories with the filename "I..." or
 223 "J...".  Note that the "cache/" directory is itself a special index.
 224
 225 Data objects are represented as files if they have no children, or directories
 226 if they do.  Their filenames all begin "D..." or "E...".  If represented as a
 227 directory, data objects will have a file in the directory called "data" that
 228 actually holds the data.
 229
 230 Special objects are similar to data objects, except their filenames begin
 231 "S..." or "T...".
 232
 233
 234 If an object has children, then it will be represented as a directory.
 235 Immediately in the representative directory are a collection of directories
 236 named for hash values of the child object keys with an '@' prepended.  Into
 237 this directory, if possible, will be placed the representations of the child
 238 objects:
 239
 240         INDEX     INDEX      INDEX                             DATA FILES
 241         ========= ========== ================================= ================
 242         cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400
 243         cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...DB1ry
 244         cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...N22ry
 245         cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...FP1ry
 246
 247
 248 If the key is so long that it exceeds NAME_MAX with the decorations added on to
 249 it, then it will be cut into pieces, the first few of which will be used to
 250 make a nest of directories, and the last one of which will be the objects
 251 inside the last directory.  The names of the intermediate directories will have
 252 '+' prepended:
 253
 254         J1223/@23/+xy...z/+kl...m/Epqr
 255
 256
 257 Note that keys are raw data, and not only may they exceed NAME_MAX in size,
 258 they may also contain things like '/' and NUL characters, and so they may not
 259 be suitable for turning directly into a filename.
 260
 261 To handle this, CacheFiles will use a suitably printable filename directly and
 262 "base-64" encode ones that aren't directly suitable.  The two versions of
 263 object filenames indicate the encoding:
 264
 265         OBJECT TYPE     PRINTABLE       ENCODED
 266         =============== =============== ===============
 267         Index           "I..."          "J..."
 268         Data            "D..."          "E..."
 269         Special         "S..."          "T..."
 270
 271 Intermediate directories are always "@" or "+" as appropriate.
 272
 273
 274 Each object in the cache has an extended attribute label that holds the object
 275 type ID (required to distinguish special objects) and the auxiliary data from
 276 the netfs.  The latter is used to detect stale objects in the cache and update
 277 or retire them.
 278
 279
 280 Note that CacheFiles will erase from the cache any file it doesn't recognise or
 281 any file of an incorrect type (such as a FIFO file or a device file).