| @@ -1,8 +1,10 @@ |
| 1 | =============================================== | 1 | .. SPDX-License-Identifier: GPL-2.0 |
| 2 | CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM | | |
| 3 | =============================================== | | |
| 4 | | 2 | |
| 5 | Contents: | 3 | =============================================== |
| | 4 | CacheFiles: CACHE ON ALREADY MOUNTED FILESYSTEM |
| | 5 | =============================================== |
| | 6 | |
| | 7 | .. Contents: |
| 6 | | 8 | |
| 7 | (*) Overview. | 9 | (*) Overview. |
| 8 | | 10 | |
| @@ -27,8 +29,8 @@ Contents: · 18 unmodified lines |
| 27 | (*) Debugging. | 29 | (*) Debugging. |
| 28 | | 30 | |
| 29 | | 31 | |
| 30 | ======== | 32 | |
| 31 | OVERVIEW | 33 | Overview |
| 32 | ======== | 34 | ======== |
| 33 | | 35 | |
| 34 | CacheFiles is a caching backend that's meant to use as a cache a directory on | 36 | CacheFiles is a caching backend that's meant to use as a cache a directory on |
| @@ -58,8 +60,8 @@ spare space and automatically contract when the set of data requires more · 23 unmodified lines |
| 58 | space. | 60 | space. |
| 59 | | 61 | |
| 60 | | 62 | |
| 61 | ============ | 63 | |
| 62 | REQUIREMENTS | 64 | Requirements |
| 63 | ============ | 65 | ============ |
| 64 | | 66 | |
| 65 | The use of CacheFiles and its daemon requires the following features to be | 67 | The use of CacheFiles and its daemon requires the following features to be |
| @@ -79,84 +81,70 @@ It is strongly recommended that the "dir_index" option is enabled on Ext3 · 13 unmodified lines |
| 79 | filesystems being used as a cache. | 81 | filesystems being used as a cache. |
| 80 | | 82 | |
| 81 | | 83 | |
| 82 | ============= | 84 | Configuration |
| 83 | CONFIGURATION | | |
| 84 | ============= | 85 | ============= |
| 85 | | 86 | |
| 86 | The cache is configured by a script in /etc/cachefilesd.conf. These commands | 87 | The cache is configured by a script in /etc/cachefilesd.conf. These commands |
| 87 | set up cache ready for use. The following script commands are available: | 88 | set up cache ready for use. The following script commands are available: |
| 88 | | 89 | |
| 89 | (*) brun <N>% | 90 | brun <N>%, bcull <N>%, bstop <N>%, frun <N>%, fcull <N>%, fstop <N>% |
| 90 | (*) bcull <N>% | | |
| 91 | (*) bstop <N>% | | |
| 92 | (*) frun <N>% | | |
| 93 | (*) fcull <N>% | | |
| 94 | (*) fstop <N>% | | |
| 95 | | | |
| 96 | Configure the culling limits. Optional. See the section on culling | 91 | Configure the culling limits. Optional. See the section on culling |
| 97 | The defaults are 7% (run), 5% (cull) and 1% (stop) respectively. | 92 | The defaults are 7% (run), 5% (cull) and 1% (stop) respectively. |
| 98 | | 93 | |
| 99 | The commands beginning with a 'b' are file space (block) limits, those | 94 | The commands beginning with a 'b' are file space (block) limits, those |
| 100 | beginning with an 'f' are file count limits. | 95 | beginning with an 'f' are file count limits. |
| 101 | | 96 | |
| 102 | (*) dir <path> | 97 | dir <path> |
| 103 | | | |
| 104 | Specify the directory containing the root of the cache. Mandatory. | 98 | Specify the directory containing the root of the cache. Mandatory. |
| 105 | | 99 | |
| 106 | (*) tag <name> | 100 | tag <name> |
| 107 | | | |
| 108 | Specify a tag to FS-Cache to use in distinguishing multiple caches. | 101 | Specify a tag to FS-Cache to use in distinguishing multiple caches. |
| 109 | Optional. The default is "CacheFiles". | 102 | Optional. The default is "CacheFiles". |
| 110 | | 103 | |
| 111 | (*) debug <mask> | 104 | debug <mask> |
| 112 | | | |
| 113 | Specify a numeric bitmask to control debugging in the kernel module. | 105 | Specify a numeric bitmask to control debugging in the kernel module. |
| 114 | Optional. The default is zero (all off). The following values can be | 106 | Optional. The default is zero (all off). The following values can be |
| 115 | OR'd into the mask to collect various information: | 107 | OR'd into the mask to collect various information: |
| 116 | | 108 | |
| | 109 | == ================================================= |
| 117 | 1 Turn on trace of function entry (_enter() macros) | 110 | 1 Turn on trace of function entry (_enter() macros) |
| 118 | 2 Turn on trace of function exit (_leave() macros) | 111 | 2 Turn on trace of function exit (_leave() macros) |
| 119 | 4 Turn on trace of internal debug points (_debug()) | 112 | 4 Turn on trace of internal debug points (_debug()) |
| | 113 | == ================================================= |
| 120 | | 114 | |
| 121 | This mask can also be set through sysfs, eg: | 115 | This mask can also be set through sysfs, eg:: |
| 122 | | 116 | |
| 123 | echo 5 >/sys/modules/cachefiles/parameters/debug | 117 | echo 5 >/sys/modules/cachefiles/parameters/debug |
| 124 | | 118 | |
| 125 | | 119 | |
| 126 | ================== | 120 | Starting the Cache |
| 127 | STARTING THE CACHE | | |
| 128 | ================== | 121 | ================== |
| 129 | | 122 | |
| 130 | The cache is started by running the daemon. The daemon opens the cache device, | 123 | The cache is started by running the daemon. The daemon opens the cache device, |
| 131 | configures the cache and tells it to begin caching. At that point the cache | 124 | configures the cache and tells it to begin caching. At that point the cache |
| 132 | binds to fscache and the cache becomes live. | 125 | binds to fscache and the cache becomes live. |
| 133 | | 126 | |
| 134 | The daemon is run as follows: | 127 | The daemon is run as follows:: |
| 135 | | 128 | |
| 136 | /sbin/cachefilesd [-d]* [-s] [-n] [-f <configfile>] | 129 | /sbin/cachefilesd [-d]* [-s] [-n] [-f <configfile>] |
| 137 | | 130 | |
| 138 | The flags are: | 131 | The flags are: |
| 139 | | 132 | |
| 140 | (*) -d | 133 | ``-d`` |
| 141 | | | |
| 142 | Increase the debugging level. This can be specified multiple times and | 134 | Increase the debugging level. This can be specified multiple times and |
| 143 | is cumulative with itself. | 135 | is cumulative with itself. |
| 144 | | 136 | |
| 145 | (*) -s | 137 | ``-s`` |
| 146 | | | |
| 147 | Send messages to stderr instead of syslog. | 138 | Send messages to stderr instead of syslog. |
| 148 | | 139 | |
| 149 | (*) -n | 140 | ``-n`` |
| 150 | | | |
| 151 | Don't daemonise and go into background. | 141 | Don't daemonise and go into background. |
| 152 | | 142 | |
| 153 | (*) -f <configfile> | 143 | ``-f <configfile>`` |
| 154 | | | |
| 155 | Use an alternative configuration file rather than the default one. | 144 | Use an alternative configuration file rather than the default one. |
| 156 | | 145 | |
| 157 | | 146 | |
| 158 | =============== | 147 | Things to Avoid |
| 159 | THINGS TO AVOID | | |
| 160 | =============== | 148 | =============== |
| 161 | | 149 | |
| 162 | Do not mount other things within the cache as this will cause problems. The | 150 | Do not mount other things within the cache as this will cause problems. The |
| @@ -179,8 +167,7 @@ Do not chmod files in the cache. The module creates things with minimal · 16 unmodified lines |
| 179 | permissions to prevent random users being able to access them directly. | 167 | permissions to prevent random users being able to access them directly. |
| 180 | | 168 | |
| 181 | | 169 | |
| 182 | ============= | 170 | Cache Culling |
| 183 | CACHE CULLING | | |
| 184 | ============= | 171 | ============= |
| 185 | | 172 | |
| 186 | The cache may need culling occasionally to make space. This involves | 173 | The cache may need culling occasionally to make space. This involves |
| @@ -192,27 +179,21 @@ Cache culling is done on the basis of the percentage of blocks and the · 5 unmodified lines |
| 192 | percentage of files available in the underlying filesystem. There are six | 179 | percentage of files available in the underlying filesystem. There are six |
| 193 | "limits": | 180 | "limits": |
| 194 | | 181 | |
| 195 | (*) brun | 182 | brun, frun |
| 196 | (*) frun | | |
| 197 | | | |
| 198 | If the amount of free space and the number of available files in the cache | 183 | If the amount of free space and the number of available files in the cache |
| 199 | rises above both these limits, then culling is turned off. | 184 | rises above both these limits, then culling is turned off. |
| 200 | | 185 | |
| 201 | (*) bcull | 186 | bcull, fcull |
| 202 | (*) fcull | | |
| 203 | | | |
| 204 | If the amount of available space or the number of available files in the | 187 | If the amount of available space or the number of available files in the |
| 205 | cache falls below either of these limits, then culling is started. | 188 | cache falls below either of these limits, then culling is started. |
| 206 | | 189 | |
| 207 | (*) bstop | 190 | bstop, fstop |
| 208 | (*) fstop | | |
| 209 | | | |
| 210 | If the amount of available space or the number of available files in the | 191 | If the amount of available space or the number of available files in the |
| 211 | cache falls below either of these limits, then no further allocation of | 192 | cache falls below either of these limits, then no further allocation of |
| 212 | disk space or files is permitted until culling has raised things above | 193 | disk space or files is permitted until culling has raised things above |
| 213 | these limits again. | 194 | these limits again. |
| 214 | | 195 | |
| 215 | These must be configured thusly: | 196 | These must be configured thusly:: |
| 216 | | 197 | |
| 217 | 0 <= bstop < bcull < brun < 100 | 198 | 0 <= bstop < bcull < brun < 100 |
| 218 | 0 <= fstop < fcull < frun < 100 | 199 | 0 <= fstop < fcull < frun < 100 |
| @@ -226,16 +207,14 @@ started as soon as space is made in the table. Objects will be skipped if · 7 unmodified lines |
| 226 | their atimes have changed or if the kernel module says it is still using them. | 207 | their atimes have changed or if the kernel module says it is still using them. |
| 227 | | 208 | |
| 228 | | 209 | |
| 229 | =============== | 210 | Cache Structure |
| 230 | CACHE STRUCTURE | | |
| 231 | =============== | 211 | =============== |
| 232 | | 212 | |
| 233 | The CacheFiles module will create two directories in the directory it was | 213 | The CacheFiles module will create two directories in the directory it was |
| 234 | given: | 214 | given: |
| 235 | | 215 | |
| 236 | (*) cache/ | 216 | * cache/ |
| 237 | | 217 | * graveyard/ |
| 238 | (*) graveyard/ | | |
| 239 | | 218 | |
| 240 | The active cache objects all reside in the first directory. The CacheFiles | 219 | The active cache objects all reside in the first directory. The CacheFiles |
| 241 | kernel module moves any retired or culled objects that it can't simply unlink | 220 | kernel module moves any retired or culled objects that it can't simply unlink |
| @@ -261,10 +240,10 @@ If an object has children, then it will be represented as a directory. · 19 unmodified lines |
| 261 | Immediately in the representative directory are a collection of directories | 240 | Immediately in the representative directory are a collection of directories |
| 262 | named for hash values of the child object keys with an '@' prepended. Into | 241 | named for hash values of the child object keys with an '@' prepended. Into |
| 263 | this directory, if possible, will be placed the representations of the child | 242 | this directory, if possible, will be placed the representations of the child |
| 264 | objects: | 243 | objects:: |
| 265 | | 244 | |
| 266 | INDEX INDEX INDEX DATA FILES | 245 | /INDEX /INDEX /INDEX /DATA FILES |
| 267 | ========= ========== ================================= ================ | 246 | /=========/==========/=================================/================ |
| 268 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400 | 247 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400 |
| 269 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...DB1ry | 248 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...DB1ry |
| 270 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...N22ry | 249 | cache/@4a/I03nfs/@30/Ji000000000000000--fHg8hi8400/@75/Es0g000w...N22ry |
| @@ -275,7 +254,7 @@ If the key is so long that it exceeds NAME_MAX with the decorations added on to · 4 unmodified lines |
| 275 | it, then it will be cut into pieces, the first few of which will be used to | 254 | it, then it will be cut into pieces, the first few of which will be used to |
| 276 | make a nest of directories, and the last one of which will be the objects | 255 | make a nest of directories, and the last one of which will be the objects |
| 277 | inside the last directory. The names of the intermediate directories will have | 256 | inside the last directory. The names of the intermediate directories will have |
| 278 | '+' prepended: | 257 | '+' prepended:: |
| 279 | | 258 | |
| 280 | J1223/@23/+xy...z/+kl...m/Epqr | 259 | J1223/@23/+xy...z/+kl...m/Epqr |
| 281 | | 260 | |
| @@ -288,11 +267,13 @@ To handle this, CacheFiles will use a suitably printable filename directly and · 6 unmodified lines |
| 288 | "base-64" encode ones that aren't directly suitable. The two versions of | 267 | "base-64" encode ones that aren't directly suitable. The two versions of |
| 289 | object filenames indicate the encoding: | 268 | object filenames indicate the encoding: |
| 290 | | 269 | |
| | 270 | =============== =============== =============== |
| 291 | OBJECT TYPE PRINTABLE ENCODED | 271 | OBJECT TYPE PRINTABLE ENCODED |
| 292 | =============== =============== =============== | 272 | =============== =============== =============== |
| 293 | Index "I..." "J..." | 273 | Index "I..." "J..." |
| 294 | Data "D..." "E..." | 274 | Data "D..." "E..." |
| 295 | Special "S..." "T..." | 275 | Special "S..." "T..." |
| | 276 | =============== =============== =============== |
| 296 | | 277 | |
| 297 | Intermediate directories are always "@" or "+" as appropriate. | 278 | Intermediate directories are always "@" or "+" as appropriate. |
| 298 | | 279 | |
| @@ -307,8 +288,7 @@ Note that CacheFiles will erase from the cache any file it doesn't recognise or · 8 unmodified lines |
| 307 | any file of an incorrect type (such as a FIFO file or a device file). | 288 | any file of an incorrect type (such as a FIFO file or a device file). |
| 308 | | 289 | |
| 309 | | 290 | |
| 310 | ========================== | 291 | Security Model and SELinux |
| 311 | SECURITY MODEL AND SELINUX | | |
| 312 | ========================== | 292 | ========================== |
| 313 | | 293 | |
| 314 | CacheFiles is implemented to deal properly with the LSM security features of | 294 | CacheFiles is implemented to deal properly with the LSM security features of |
| @@ -331,26 +311,26 @@ When the CacheFiles module is asked to bind to its cache, it: · 16 unmodified lines |
| 331 | | 311 | |
| 332 | (1) Finds the security label attached to the root cache directory and uses | 312 | (1) Finds the security label attached to the root cache directory and uses |
| 333 | that as the security label with which it will create files. By default, | 313 | that as the security label with which it will create files. By default, |
| 334 | this is: | 314 | this is:: |
| 335 | | 315 | |
| 336 | cachefiles_var_t | 316 | cachefiles_var_t |
| 337 | | 317 | |
| 338 | (2) Finds the security label of the process which issued the bind request | 318 | (2) Finds the security label of the process which issued the bind request |
| 339 | (presumed to be the cachefilesd daemon), which by default will be: | 319 | (presumed to be the cachefilesd daemon), which by default will be:: |
| 340 | | 320 | |
| 341 | cachefilesd_t | 321 | cachefilesd_t |
| 342 | | 322 | |
| 343 | and asks LSM to supply a security ID as which it should act given the | 323 | and asks LSM to supply a security ID as which it should act given the |
| 344 | daemon's label. By default, this will be: | 324 | daemon's label. By default, this will be:: |
| 345 | | 325 | |
| 346 | cachefiles_kernel_t | 326 | cachefiles_kernel_t |
| 347 | | 327 | |
| 348 | SELinux transitions the daemon's security ID to the module's security ID | 328 | SELinux transitions the daemon's security ID to the module's security ID |
| 349 | based on a rule of this form in the policy. | 329 | based on a rule of this form in the policy:: |
| 350 | | 330 | |
| 351 | type_transition <daemon's-ID> kernel_t : process <module's-ID>; | 331 | type_transition <daemon's-ID> kernel_t : process <module's-ID>; |
| 352 | | 332 | |
| 353 | For instance: | 333 | For instance:: |
| 354 | | 334 | |
| 355 | type_transition cachefilesd_t kernel_t : process cachefiles_kernel_t; | 335 | type_transition cachefilesd_t kernel_t : process cachefiles_kernel_t; |
| 356 | | 336 | |
| @@ -370,7 +350,7 @@ There are policy source files available in: · 13 unmodified lines |
| 370 | | 350 | |
| 371 | http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 | 351 | http://people.redhat.com/~dhowells/fscache/cachefilesd-0.8.tar.bz2 |
| 372 | | 352 | |
| 373 | and later versions. In that tarball, see the files: | 353 | and later versions. In that tarball, see the files:: |
| 374 | | 354 | |
| 375 | cachefilesd.te | 355 | cachefilesd.te |
| 376 | cachefilesd.fc | 356 | cachefilesd.fc |
| @@ -379,7 +359,7 @@ and later versions. In that tarball, see the files: · 2 unmodified lines |
| 379 | They are built and installed directly by the RPM. | 359 | They are built and installed directly by the RPM. |
| 380 | | 360 | |
| 381 | If a non-RPM based system is being used, then copy the above files to their own | 361 | If a non-RPM based system is being used, then copy the above files to their own |
| 382 | directory and run: | 362 | directory and run:: |
| 383 | | 363 | |
| 384 | make -f /usr/share/selinux/devel/Makefile | 364 | make -f /usr/share/selinux/devel/Makefile |
| 385 | semodule -i cachefilesd.pp | 365 | semodule -i cachefilesd.pp |
| @@ -394,7 +374,7 @@ an auxiliary policy must be installed to label the alternate location of the · 8 unmodified lines |
| 394 | cache. | 374 | cache. |
| 395 | | 375 | |
| 396 | For instructions on how to add an auxiliary policy to enable the cache to be | 376 | For instructions on how to add an auxiliary policy to enable the cache to be |
| 397 | located elsewhere when SELinux is in enforcing mode, please see: | 377 | located elsewhere when SELinux is in enforcing mode, please see:: |
| 398 | | 378 | |
| 399 | /usr/share/doc/cachefilesd-*/move-cache.txt | 379 | /usr/share/doc/cachefilesd-*/move-cache.txt |
| 400 | | 380 | |
| @@ -402,8 +382,7 @@ When the cachefilesd rpm is installed; alternatively, the document can be found · 1 unmodified line |
| 402 | in the sources. | 382 | in the sources. |
| 403 | | 383 | |
| 404 | | 384 | |
| 405 | ================== | 385 | A Note on Security |
| 406 | A NOTE ON SECURITY | | |
| 407 | ================== | 386 | ================== |
| 408 | | 387 | |
| 409 | CacheFiles makes use of the split security in the task_struct. It allocates | 388 | CacheFiles makes use of the split security in the task_struct. It allocates |
| @@ -445,17 +424,18 @@ for CacheFiles to run in a context of a specific security label, or to create · 35 unmodified lines |
| 445 | files and directories with another security label. | 424 | files and directories with another security label. |
| 446 | | 425 | |
| 447 | | 426 | |
| 448 | ======================= | 427 | Statistical Information |
| 449 | STATISTICAL INFORMATION | | |
| 450 | ======================= | 428 | ======================= |
| 451 | | 429 | |
| 452 | If FS-Cache is compiled with the following option enabled: | 430 | If FS-Cache is compiled with the following option enabled:: |
| 453 | | 431 | |
| 454 | CONFIG_CACHEFILES_HISTOGRAM=y | 432 | CONFIG_CACHEFILES_HISTOGRAM=y |
| 455 | | 433 | |
| 456 | then it will gather certain statistics and display them through a proc file. | 434 | then it will gather certain statistics and display them through a proc file. |
| 457 | | 435 | |
| 458 | (*) /proc/fs/cachefiles/histogram | 436 | /proc/fs/cachefiles/histogram |
| | 437 | |
| | 438 | :: |
| 459 | | 439 | |
| 460 | cat /proc/fs/cachefiles/histogram | 440 | cat /proc/fs/cachefiles/histogram |
| 461 | JIFS SECS LOOKUPS MKDIRS CREATES | 441 | JIFS SECS LOOKUPS MKDIRS CREATES |
| @@ -465,36 +445,39 @@ then it will gather certain statistics and display them through a proc file. · 3 unmodified lines |
| 465 | between 0 jiffies and HZ-1 jiffies a variety of tasks took to run. The | 445 | between 0 jiffies and HZ-1 jiffies a variety of tasks took to run. The |
| 466 | columns are as follows: | 446 | columns are as follows: |
| 467 | | 447 | |
| | 448 | ======= ======================================================= |
| 468 | COLUMN TIME MEASUREMENT | 449 | COLUMN TIME MEASUREMENT |
| 469 | ======= ======================================================= | 450 | ======= ======================================================= |
| 470 | LOOKUPS Length of time to perform a lookup on the backing fs | 451 | LOOKUPS Length of time to perform a lookup on the backing fs |
| 471 | MKDIRS Length of time to perform a mkdir on the backing fs | 452 | MKDIRS Length of time to perform a mkdir on the backing fs |
| 472 | CREATES Length of time to perform a create on the backing fs | 453 | CREATES Length of time to perform a create on the backing fs |
| | 454 | ======= ======================================================= |
| 473 | | 455 | |
| 474 | Each row shows the number of events that took a particular range of times. | 456 | Each row shows the number of events that took a particular range of times. |
| 475 | Each step is 1 jiffy in size. The JIFS column indicates the particular | 457 | Each step is 1 jiffy in size. The JIFS column indicates the particular |
| 476 | jiffy range covered, and the SECS field the equivalent number of seconds. | 458 | jiffy range covered, and the SECS field the equivalent number of seconds. |
| 477 | | 459 | |
| 478 | | 460 | |
| 479 | ========= | 461 | Debugging |
| 480 | DEBUGGING | | |
| 481 | ========= | 462 | ========= |
| 482 | | 463 | |
| 483 | If CONFIG_CACHEFILES_DEBUG is enabled, the CacheFiles facility can have runtime | 464 | If CONFIG_CACHEFILES_DEBUG is enabled, the CacheFiles facility can have runtime |
| 484 | debugging enabled by adjusting the value in: | 465 | debugging enabled by adjusting the value in:: |
| 485 | | 466 | |
| 486 | /sys/module/cachefiles/parameters/debug | 467 | /sys/module/cachefiles/parameters/debug |
| 487 | | 468 | |
| 488 | This is a bitmask of debugging streams to enable: | 469 | This is a bitmask of debugging streams to enable: |
| 489 | | 470 | |
| | 471 | ======= ======= =============================== ======================= |
| 490 | BIT VALUE STREAM POINT | 472 | BIT VALUE STREAM POINT |
| 491 | ======= ======= =============================== ======================= | 473 | ======= ======= =============================== ======================= |
| 492 | 0 1 General Function entry trace | 474 | 0 1 General Function entry trace |
| 493 | 1 2 Function exit trace | 475 | 1 2 Function exit trace |
| 494 | 2 4 General | 476 | 2 4 General |
| | 477 | ======= ======= =============================== ======================= |
| 495 | | 478 | |
| 496 | The appropriate set of values should be OR'd together and the result written to | 479 | The appropriate set of values should be OR'd together and the result written to |
| 497 | the control file. For example: | 480 | the control file. For example:: |
| 498 | | 481 | |
| 499 | echo $((1|4|8)) >/sys/module/cachefiles/parameters/debug | 482 | echo $((1|4|8)) >/sys/module/cachefiles/parameters/debug |
| 500 | | 483 | |