mergerfs/config/cache/index.html


<!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="../func_readdir/">
      
      
        <link rel="next" href="../ioctl/">
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.49">
    
    
        <title>caching - mergerfs</title>
      
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.6f8fc17f.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.1 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.1 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 md-nav__item--active md-nav__item--nested">
      
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
        
          
          <label class="md-nav__link" for="__nav_4" id="__nav_4_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_4_label" aria-expanded="true">
          <label class="md-nav__title" for="__nav_4">
            <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="../terminology/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Terminology
  </span>
  

      </a>
    </li>
  

    <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 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="../ioctl/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    ioctl
  </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">
      <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>
  

          </ul>
        </nav>
      
    </li>
  

    <li class="md-nav__item">
      <a href="../../error_handling/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Error Handling
  </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 md-nav__item--nested">
      
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
        
          
          <label class="md-nav__link" for="__nav_14" id="__nav_14_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_14_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_14">
            <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/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/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/general_information_and_overview/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    General Information and Overview
  </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/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/limit_drive_spinup/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    Limit 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="../../donations/" class="md-nav__link">
        
  
  <span class="md-ellipsis">
    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/tree/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>
  
  
<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 to
the kernel caching both the underlying filesystem's file content as
well as the file through mergerfs. However, if you want to confirm
performance differences it is recommended that you perform some
benchmark to confirm which option works best for your setup.</p>
<p>Why then would you want to enable page caching if it consumes ~2x the
RAM as normal and is on average slower? Because it is the only way to
support
<a href="https://man7.org/linux/man-pages/man2/mmap.2.html">mmap</a>. <code>mmap</code> is a
way for programs to treat a file as if it is a contiguous RAM buffer
which is regularly used by a number of programs such as those that
leverage <strong>sqlite3</strong>. Despite <code>mmap</code> not being supported by all
filesystems it is unfortunately common for software to not have an
option 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 now
transparently enable page caching when mmap is requested. This means
it should be safe to set <code>cache.files=off</code>. However, on Linux v6.5 and
below 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 entry
cache caches that those details which limits the number of requests
sent 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. If
the filesystems are changed outside mergerfs there is a risk of files
which have been removed continuing to show as available. It will fail
gracefully if a phantom file is actioned on in some way so there is
little risk in setting the value much higher. Especially if there are
no 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 a
file 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. If
the filesystems are changed outside mergerfs there is a risk of files
which have been added outside mergerfs not appearing correctly till
the cache entry times out if there had been a request for the same
name within mergerfs which didn't exist. This is mostly an
inconvenience.</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 is
collected by the
<a href="https://man7.org/linux/man-pages/man2/stat.2.html">stat</a> system call
which 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 if
changes are made to the file out-of-band there could be
inconsistencies between the actual file and the cached details which
could result in different issues depending on how the data is used. If
the simultaneous writing of a file from inside and outside is unlikely
then you should be safe. That said any simultaneous, uncoordinated
manipulation 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 the
branches being considered. This is accomplished by calling
<a href="https://man7.org/linux/man-pages/man2/statfs.2.html">statfs</a>. This
call however is a bit expensive so this cache reduces the overhead by
limiting how often the calls are actually made.</p>
<p>This will mean that if the available space of branches changed
somewhat rapidly there is a risk of <code>create</code> or <code>mkdir</code> calls made
within the timeout period ending up on the same branch. This however
should 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 symlinks
so that the kernel does not need to make a request to mergerfs every
single 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 very
regularly queries symlink values, the use of this cache could
significantly improve performance.</p>
<p>mergerfs will not error if the kernel used does not support symlink
caching.</p>
<p>As with other caches the main risk in enabling it is if you are
manipulating symlinks from both within and without the mergerfs
mount. Should the value be changed outside of mergerfs then it will
not be reflected in the mergerfs mount till the cached value is
invalidated.</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 a
significant impact on directory traversal. Especially when combined
with entry (<code>cache.entry</code>) and attribute (<code>cache.attr</code>) caching. If
the kernel doesn't support readdir caching setting the option to true
has no effect. This option is configurable at runtime via xattr
user.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 perform
writethrough caching. This behavior won't help improve performance as
each write still goes one for one through the filesystem. By enabling
the FUSE writeback cache small writes <em>may</em> be aggregated by the
kernel and then sent to mergerfs as one larger request. This can
greatly improve the throughput for apps which write to files
inefficiently. The amount the kernel can aggregate is limited by the
size of a FUSE message. Read the fuse_msg_size section for more
details.</p>
<p>There is a side effect as a result of enabling writeback
caching. Underlying files won't ever be opened with O_APPEND or
O_WRONLY. The former because the kernel then manages append mode and
the latter because the kernel may request file data from mergerfs to
populate the write cache. The O_APPEND change means that if a file is
changed outside of mergerfs it could lead to corruption as the kernel
won't know the end of the file has changed. That said any time you use
caching you should keep from writing to the same file outside of
mergerfs at the same time.</p>
<p>Note that if an application is properly sizing writes then writeback
caching will have little or no effect. It will only help with writes
of sizes below the FUSE message size (128K on older kernels, 1M on
newer). Even then its effectiveness might not be great. Given the side
effects of enabling this feature it is recommended that its benefits
be proved out with benchmarks.</p>
<div class="footnote">
<hr />
<ol>
<li id="fn:1">
<p>This is not unique to mergerfs and affects all FUSE
filesystems. It is something that the FUSE community hopes to
investigate at some point but as of early 2025 there are a number
of major reworking going on with FUSE which needs to be finished
first.&#160;<a class="footnote-backref" href="#fnref:1" title="Jump back to footnote 1 in the text">&#8617;</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>&#160;<a class="footnote-backref" href="#fnref:2" title="Jump back to footnote 2 in the text">&#8617;</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">
  
  <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.code.copy", "content.code.select", "navigation.instant", "navigation.instant.prefetch", "navigation.path", "navigation.top", "navigation.tracking", "optimize", "search.share", "toc.follow"], "search": "../../assets/javascripts/workers/search.6ce7567c.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.88dd0f4e.min.js"></script>
      
    
  </body>
</html>