|
|
<!doctype html><html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta name="description" content="mergerfs - a featureful union filesystem"> <link rel="canonical" href="https://trapexit.github.io/mergerfs/config/cache/"> <link rel="prev" href="../rename_and_link/"> <link rel="next" href="../readahead/"> <link rel="icon" href="../../assets/images/favicon.png"> <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.7"> <title>caching - mergerfs</title> <link rel="stylesheet" href="../../assets/stylesheets/main.8608ea7d.min.css"> <link rel="stylesheet" href="../../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"> <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style> <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head> <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#caching" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div>
<header class="md-header md-header--shadow" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="../.." title="mergerfs" class="md-header__button md-logo" aria-label="mergerfs" data-md-component="logo"> <img src="../../logo.jpeg" alt="logo">
</a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> <span class="md-ellipsis"> mergerfs </span> </div> <div class="md-header__topic" data-md-component="header-topic"> <span class="md-ellipsis"> caching </span> </div> </div> </div> <form class="md-header__option" data-md-component="palette"> <input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0"> <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1"> <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to system preference" type="radio" name="__palette" id="__palette_2"> <label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg> </a> <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> </nav> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list" role="presentation"></ol> </div> </div> </div> </div></div> <div class="md-header__source"> <a href="https://github.com/trapexit/mergerfs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class="md-source__repository"> mergerfs </div></a> </div> </nav> </header> <div class="md-container" data-md-component="container"> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="../.." title="mergerfs" class="md-nav__button md-logo" aria-label="mergerfs" data-md-component="logo"> <img src="../../logo.jpeg" alt="logo">
</a> mergerfs </label> <div class="md-nav__source"> <a href="https://github.com/trapexit/mergerfs" title="Go to repository" class="md-source" data-md-component="source"> <div class="md-source__icon md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg> </div> <div class="md-source__repository"> mergerfs </div></a> </div> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../.." class="md-nav__link"> <span class="md-ellipsis"> Home </span>
</a> </li>
<li class="md-nav__item"> <a href="../../quickstart/" class="md-nav__link"> <span class="md-ellipsis"> QuickStart </span>
</a> </li>
<li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" > <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0"> <span class="md-ellipsis"> Installation </span>
<span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3"> <span class="md-nav__icon md-icon"></span> Installation </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../setup/installation/" class="md-nav__link"> <span class="md-ellipsis"> Installation </span>
</a> </li>
<li class="md-nav__item"> <a href="../../setup/upgrade/" class="md-nav__link"> <span class="md-ellipsis"> Upgrade </span>
</a> </li>
<li class="md-nav__item"> <a href="../../setup/build/" class="md-nav__link"> <span class="md-ellipsis"> Build </span>
</a> </li>
</ul> </nav> </li>
<li class="md-nav__item"> <a href="../../terminology/" class="md-nav__link"> <span class="md-ellipsis"> Terminology </span>
</a> </li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" checked> <label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-ellipsis"> Config </span>
<span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Config </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../options/" class="md-nav__link"> <span class="md-ellipsis"> Options </span>
</a> </li>
<li class="md-nav__item"> <a href="../deprecated_options/" class="md-nav__link"> <span class="md-ellipsis"> Deprecated Options </span>
</a> </li>
<li class="md-nav__item"> <a href="../branches/" class="md-nav__link"> <span class="md-ellipsis"> branches </span>
</a> </li>
<li class="md-nav__item"> <a href="../functions_categories_and_policies/" class="md-nav__link"> <span class="md-ellipsis"> functions, categories and policies </span>
</a> </li>
<li class="md-nav__item"> <a href="../func_readdir/" class="md-nav__link"> <span class="md-ellipsis"> func.readdir </span>
</a> </li>
<li class="md-nav__item"> <a href="../rename_and_link/" class="md-nav__link"> <span class="md-ellipsis"> rename and link </span>
</a> </li>
<li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> <span class="md-ellipsis"> caching </span>
<span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> caching </span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#cachefiles" class="md-nav__link"> <span class="md-ellipsis"> cache.files </span> </a> </li> <li class="md-nav__item"> <a href="#cacheentry" class="md-nav__link"> <span class="md-ellipsis"> cache.entry </span> </a> </li> <li class="md-nav__item"> <a href="#cachenegative_entry" class="md-nav__link"> <span class="md-ellipsis"> cache.negative_entry </span> </a> </li> <li class="md-nav__item"> <a href="#cacheattr" class="md-nav__link"> <span class="md-ellipsis"> cache.attr </span> </a> </li> <li class="md-nav__item"> <a href="#cachestatfs" class="md-nav__link"> <span class="md-ellipsis"> cache.statfs </span> </a> </li> <li class="md-nav__item"> <a href="#cachesymlinks" class="md-nav__link"> <span class="md-ellipsis"> cache.symlinks </span> </a> </li> <li class="md-nav__item"> <a href="#cachereaddir" class="md-nav__link"> <span class="md-ellipsis"> cache.readdir </span> </a> </li> <li class="md-nav__item"> <a href="#cachewriteback" class="md-nav__link"> <span class="md-ellipsis"> cache.writeback </span> </a> </li> </ul> </nav> </li>
<li class="md-nav__item"> <a href="../readahead/" class="md-nav__link"> <span class="md-ellipsis"> readahead </span>
</a> </li>
<li class="md-nav__item"> <a href="../inodecalc/" class="md-nav__link"> <span class="md-ellipsis"> inodecalc </span>
</a> </li>
<li class="md-nav__item"> <a href="../threads/" class="md-nav__link"> <span class="md-ellipsis"> threads </span>
</a> </li>
<li class="md-nav__item"> <a href="../pin-threads/" class="md-nav__link"> <span class="md-ellipsis"> pin-threads </span>
</a> </li>
<li class="md-nav__item"> <a href="../link_cow/" class="md-nav__link"> <span class="md-ellipsis"> link_cow </span>
</a> </li>
<li class="md-nav__item"> <a href="../fuse_msg_size/" class="md-nav__link"> <span class="md-ellipsis"> fuse_msg_size </span>
</a> </li>
<li class="md-nav__item"> <a href="../follow-symlinks/" class="md-nav__link"> <span class="md-ellipsis"> follow-symlinks </span>
</a> </li>
<li class="md-nav__item"> <a href="../link-exdev/" class="md-nav__link"> <span class="md-ellipsis"> link-exdev </span>
</a> </li>
<li class="md-nav__item"> <a href="../rename-exdev/" class="md-nav__link"> <span class="md-ellipsis"> rename-exdev </span>
</a> </li>
<li class="md-nav__item"> <a href="../symlinkify/" class="md-nav__link"> <span class="md-ellipsis"> symlinkify </span>
</a> </li>
<li class="md-nav__item"> <a href="../nullrw/" class="md-nav__link"> <span class="md-ellipsis"> nullrw </span>
</a> </li>
<li class="md-nav__item"> <a href="../xattr/" class="md-nav__link"> <span class="md-ellipsis"> xattr </span>
</a> </li>
<li class="md-nav__item"> <a href="../nfsopenhack/" class="md-nav__link"> <span class="md-ellipsis"> nfsopenhack </span>
</a> </li>
<li class="md-nav__item"> <a href="../statfs/" class="md-nav__link"> <span class="md-ellipsis"> statfs / statvfs </span>
</a> </li>
<li class="md-nav__item"> <a href="../flush-on-close/" class="md-nav__link"> <span class="md-ellipsis"> flush-on-close </span>
</a> </li>
<li class="md-nav__item"> <a href="../export-support/" class="md-nav__link"> <span class="md-ellipsis"> export-support </span>
</a> </li>
</ul> </nav> </li>
<li class="md-nav__item"> <a href="../../error_handling_and_logging/" class="md-nav__link"> <span class="md-ellipsis"> Error Handling and Logging </span>
</a> </li>
<li class="md-nav__item"> <a href="../../runtime_interfaces/" class="md-nav__link"> <span class="md-ellipsis"> Runtime Interfaces </span>
</a> </li>
<li class="md-nav__item"> <a href="../../remote_filesystems/" class="md-nav__link"> <span class="md-ellipsis"> Remote Filesystems </span>
</a> </li>
<li class="md-nav__item"> <a href="../../tips_notes/" class="md-nav__link"> <span class="md-ellipsis"> Tips and Notes </span>
</a> </li>
<li class="md-nav__item"> <a href="../../known_issues_bugs/" class="md-nav__link"> <span class="md-ellipsis"> Known Issues and Bugs </span>
</a> </li>
<li class="md-nav__item"> <a href="../../project_comparisons/" class="md-nav__link"> <span class="md-ellipsis"> Project Comparisons </span>
</a> </li>
<li class="md-nav__item"> <a href="../../performance/" class="md-nav__link"> <span class="md-ellipsis"> Tweaking Performance </span>
</a> </li>
<li class="md-nav__item"> <a href="../../benchmarking/" class="md-nav__link"> <span class="md-ellipsis"> Benchmarking </span>
</a> </li>
<li class="md-nav__item"> <a href="../../tooling/" class="md-nav__link"> <span class="md-ellipsis"> Tooling </span>
</a> </li>
<li class="md-nav__item"> <a href="../../usage_patterns/" class="md-nav__link"> <span class="md-ellipsis"> Usage Patterns </span>
</a> </li>
<li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_16" > <label class="md-nav__link" for="__nav_16" id="__nav_16_label" tabindex="0"> <span class="md-ellipsis"> FAQ </span>
<span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_16_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_16"> <span class="md-nav__icon md-icon"></span> FAQ </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../faq/reliability_and_scalability/" class="md-nav__link"> <span class="md-ellipsis"> Reliability and Scalability </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/usage_and_functionality/" class="md-nav__link"> <span class="md-ellipsis"> Usage and Functionality </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/configuration_and_policies/" class="md-nav__link"> <span class="md-ellipsis"> Configuration and Policies </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/compatibility_and_integration/" class="md-nav__link"> <span class="md-ellipsis"> Compatibility and Integration </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/recommendations_and_warnings/" class="md-nav__link"> <span class="md-ellipsis"> Recommendations and Warnings </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/technical_behavior_and_limitations/" class="md-nav__link"> <span class="md-ellipsis"> Technical Behavior and Limitations </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/why_isnt_it_working/" class="md-nav__link"> <span class="md-ellipsis"> "Why isn't it working?" </span>
</a> </li>
<li class="md-nav__item"> <a href="../../faq/limit_drive_spinup/" class="md-nav__link"> <span class="md-ellipsis"> Limiting drive spinup </span>
</a> </li>
</ul> </nav> </li>
<li class="md-nav__item"> <a href="../../related_projects/" class="md-nav__link"> <span class="md-ellipsis"> Related Projects </span>
</a> </li>
<li class="md-nav__item"> <a href="../../media_and_publicity/" class="md-nav__link"> <span class="md-ellipsis"> Media and Publicity </span>
</a> </li>
<li class="md-nav__item"> <a href="../../support/" class="md-nav__link"> <span class="md-ellipsis"> Support </span>
</a> </li>
<li class="md-nav__item"> <a href="../../sponsorship_and_donations/" class="md-nav__link"> <span class="md-ellipsis"> Sponsorship and Donations </span>
</a> </li>
</ul></nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#cachefiles" class="md-nav__link"> <span class="md-ellipsis"> cache.files </span> </a> </li> <li class="md-nav__item"> <a href="#cacheentry" class="md-nav__link"> <span class="md-ellipsis"> cache.entry </span> </a> </li> <li class="md-nav__item"> <a href="#cachenegative_entry" class="md-nav__link"> <span class="md-ellipsis"> cache.negative_entry </span> </a> </li> <li class="md-nav__item"> <a href="#cacheattr" class="md-nav__link"> <span class="md-ellipsis"> cache.attr </span> </a> </li> <li class="md-nav__item"> <a href="#cachestatfs" class="md-nav__link"> <span class="md-ellipsis"> cache.statfs </span> </a> </li> <li class="md-nav__item"> <a href="#cachesymlinks" class="md-nav__link"> <span class="md-ellipsis"> cache.symlinks </span> </a> </li> <li class="md-nav__item"> <a href="#cachereaddir" class="md-nav__link"> <span class="md-ellipsis"> cache.readdir </span> </a> </li> <li class="md-nav__item"> <a href="#cachewriteback" class="md-nav__link"> <span class="md-ellipsis"> cache.writeback </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset">
<a href="https://github.com/trapexit/mergerfs/edit/master/mkdocs/docs/config/cache.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <a href="https://github.com/trapexit/mergerfs/raw/master/mkdocs/docs/config/cache.md" title="View source of this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 18c.56 0 1 .44 1 1s-.44 1-1 1-1-.44-1-1 .44-1 1-1m0-3c-2.73 0-5.06 1.66-6 4 .94 2.34 3.27 4 6 4s5.06-1.66 6-4c-.94-2.34-3.27-4-6-4m0 6.5a2.5 2.5 0 0 1-2.5-2.5 2.5 2.5 0 0 1 2.5-2.5 2.5 2.5 0 0 1 2.5 2.5 2.5 2.5 0 0 1-2.5 2.5M9.27 20H6V4h7v5h5v4.07c.7.08 1.36.25 2 .49V8l-6-6H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h4.5a8.2 8.2 0 0 1-1.23-2"/></svg> </a>
<h1 id="caching">caching</h1><h2 id="cachefiles">cache.files</h2><p>Controls how <a href="https://en.wikipedia.org/wiki/Page_cache">page caching</a>works for mergerfs itself. Not the underlying filesystems.</p><ul><li><code>cache.files=off</code>: Disables page caching for mergerfs.</li><li><code>cache.files=partial</code>: Enables page caching. Files are cached while open.</li><li><code>cache.files=full</code>: Enables page caching. Files are cached across opens.</li><li><code>cache.files=auto-full</code>: Enables page caching. Files are cached across opens if mtime and size are unchanged since previous open.</li><li><code>cache.files=per-process</code>: Enable page caching (equivalent to <code>cache.files=partial</code>) only for processes whose 'comm' name matches one of the values defined in cache.files.process-names. If the name does not match the file open is equivalent to <code>cache.files=off</code>.</li></ul><p>Generally, enabling the page cache actually <em>harms</em>performance<sup id="fnref:1"><a class="footnote-ref" href="#fn:1">1</a></sup>. In part because it can lead to buffer bloat due tothe kernel caching both the underlying filesystem's file content aswell as the file through mergerfs. However, if you want to confirmperformance differences it is recommended that you perform somebenchmark to confirm which option works best for your setup.</p><p>Why then would you want to enable page caching if it consumes ~2x theRAM as normal and is on average slower? Because it is the only way tosupport<a href="https://man7.org/linux/man-pages/man2/mmap.2.html">mmap</a>. <code>mmap</code> is away for programs to treat a file as if it is a contiguous RAM bufferwhich is regularly used by a number of programs such as those thatleverage <strong>sqlite3</strong>. Despite <code>mmap</code> not being supported by allfilesystems it is unfortunately common for software to not have anoption to use regular file IO instead of <code>mmap</code>.</p><p>The good thing is that in Linux v6.6<sup id="fnref:2"><a class="footnote-ref" href="#fn:2">2</a></sup> and above FUSE can nowtransparently enable page caching when mmap is requested. This meansit should be safe to set <code>cache.files=off</code>. However, on Linux v6.5 andbelow you will need to configure <code>cache.files</code> as you need.</p><h2 id="cacheentry">cache.entry</h2><ul><li><code>cache.entry=UINT</code>: Sets the number of seconds to cache entry queries. Defaults to <code>1</code>.</li></ul><p>The kernel must ask mergerfs about the existence of files. The entrycache caches that those details which limits the number of requestssent to mergerfs.</p><p>The risk of setting this value, as with most any cache, is related to<a href="https://en.wikipedia.org/wiki/Out-of-band">out-of-band</a> changes. Ifthe filesystems are changed outside mergerfs there is a risk of fileswhich have been removed continuing to show as available. It will failgracefully if a phantom file is actioned on in some way so there islittle risk in setting the value much higher. Especially if there areno out-of-band changes.</p><h2 id="cachenegative_entry">cache.negative_entry</h2><ul><li><code>cache.negative_entry=UINT</code>: Sets the number of seconds to cache negative entry queries. Defaults to <code>1</code>.</li></ul><p>This is a cache for negative entry query responses. Such as when afile which does not exist is referenced.</p><p>The risk of setting this value, as with most any cache, is related to<a href="https://en.wikipedia.org/wiki/Out-of-band">out-of-band</a> changes. Ifthe filesystems are changed outside mergerfs there is a risk of fileswhich have been added outside mergerfs not appearing correctly tillthe cache entry times out if there had been a request for the samename within mergerfs which didn't exist. This is mostly aninconvenience.</p><h2 id="cacheattr">cache.attr</h2><ul><li><code>cache.attr=UINT</code>: Sets the number of seconds to cache file attributes. Defaults to <code>1</code>.</li></ul><p>This is a cache for file attributes and metadata such as that which iscollected by the<a href="https://man7.org/linux/man-pages/man2/stat.2.html">stat</a> system callwhich is used when you run commands such as <code>find</code> or <code>ls -lh</code>. </p><p>As with other caches the risk of enabling the attribute cache is ifchanges are made to the file out-of-band there could beinconsistencies between the actual file and the cached details whichcould result in different issues depending on how the data is used. Ifthe simultaneous writing of a file from inside and outside is unlikelythen you should be safe. That said any simultaneous, uncoordinatedmanipulation of a file can lead to unexpected results.</p><h2 id="cachestatfs">cache.statfs</h2><ul><li><code>cache.statfs=UINT</code>: Sets the number of seconds to cache <code>statfs</code> calls used by policies. Defaults to <code>0</code>.</li></ul><p>A number of policies require looking up the available space of thebranches being considered. This is accomplished by calling<a href="https://man7.org/linux/man-pages/man2/statfs.2.html">statfs</a>. Thiscall however is a bit expensive so this cache reduces the overhead bylimiting how often the calls are actually made.</p><p>This will mean that if the available space of branches changedsomewhat rapidly there is a risk of <code>create</code> or <code>mkdir</code> calls madewithin the timeout period ending up on the same branch. This howevershould even itself out over time.</p><h2 id="cachesymlinks">cache.symlinks</h2><ul><li><code>cache.symlinks=BOOL</code>: Enable kernel caching of symlink values. Defaults to <code>false</code>.</li></ul><p>As of Linux v4.20 there is an ability to cache the value of symlinksso that the kernel does not need to make a request to mergerfs everysingle time a<a href="https://man7.org/linux/man-pages/man2/readlink.2.html">readlink</a>request is made. While not a common usage pattern, if software veryregularly queries symlink values, the use of this cache couldsignificantly improve performance.</p><p>mergerfs will not error if the kernel used does not support symlinkcaching.</p><p>As with other caches the main risk in enabling it is if you aremanipulating symlinks from both within and without the mergerfsmount. Should the value be changed outside of mergerfs then it willnot be reflected in the mergerfs mount till the cached value isinvalidated.</p><h2 id="cachereaddir">cache.readdir</h2><ul><li><code>cache.readdir=BOOL</code>: Enable kernel caching of readdir results. Defaults to <code>false</code>.</li></ul><p>As of Linux v4.20 it supports readdir caching. This can have asignificant impact on directory traversal. Especially when combinedwith entry (<code>cache.entry</code>) and attribute (<code>cache.attr</code>) caching. Ifthe kernel doesn't support readdir caching setting the option to truehas no effect. This option is configurable at runtime via xattruser.mergerfs.cache.readdir.</p><h2 id="cachewriteback">cache.writeback</h2><ul><li><code>cache.writeback=BOOL</code>: Enable writeback cache. Defaults to <code>false</code>.</li></ul><p>When <code>cache.files</code> is enabled the default is for it to performwritethrough caching. This behavior won't help improve performance aseach write still goes one for one through the filesystem. By enablingthe FUSE writeback cache small writes <em>may</em> be aggregated by thekernel and then sent to mergerfs as one larger request. This cangreatly improve the throughput for apps which write to filesinefficiently. The amount the kernel can aggregate is limited by thesize of a FUSE message. Read the fuse_msg_size section for moredetails.</p><p>There is a side effect as a result of enabling writebackcaching. Underlying files won't ever be opened with O_APPEND orO_WRONLY. The former because the kernel then manages append mode andthe latter because the kernel may request file data from mergerfs topopulate the write cache. The O_APPEND change means that if a file ischanged outside of mergerfs it could lead to corruption as the kernelwon't know the end of the file has changed. That said any time you usecaching you should keep from writing to the same file outside ofmergerfs at the same time.</p><p>Note that if an application is properly sizing writes then writebackcaching will have little or no effect. It will only help with writesof sizes below the FUSE message size (128K on older kernels, 1M onnewer). Even then its effectiveness might not be great. Given the sideeffects of enabling this feature it is recommended that its benefitsbe proved out with benchmarks.</p><div class="footnote"><hr /><ol><li id="fn:1"><p>This is not unique to mergerfs and affects all FUSEfilesystems. It is something that the FUSE community hopes toinvestigate at some point but as of early 2025 there are a numberof major reworking going on with FUSE which needs to be finishedfirst. <a class="footnote-backref" href="#fnref:1" title="Jump back to footnote 1 in the text">↩</a></p></li><li id="fn:2"><p><a href="https://kernelnewbies.org/Linux_6.6#FUSE">https://kernelnewbies.org/Linux_6.6#FUSE</a> <a class="footnote-backref" href="#fnref:2" title="Jump back to footnote 2 in the text">↩</a></p></li></ol></div>
</article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top</button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../rename_and_link/" class="md-footer__link md-footer__link--prev" aria-label="Previous: rename and link"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> rename and link </div> </div> </a> <a href="../readahead/" class="md-footer__link md-footer__link--next" aria-label="Next: readahead"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> readahead </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div></footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["content.action.edit", "content.action.view", "content.code.copy", "content.code.select", "navigation.footer", "navigation.instant", "navigation.instant.prefetch", "navigation.path", "navigation.top", "navigation.tracking", "optimize", "search.share", "toc.follow"], "search": "../../assets/javascripts/workers/search.f8cc74c7.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.c8b220af.min.js"></script> </body></html>
|
