2025-05-10 17:00:32 +00:00
<!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" >
2025-05-10 12:35:08 -05:00
< link rel = "canonical" href = "https://trapexit.github.io/mergerfs/runtime_interfaces/" >
2025-05-10 17:00:32 +00:00
< link rel = "prev" href = "../error_handling_and_logging/" >
< link rel = "next" href = "../remote_filesystems/" >
< link rel = "icon" href = "../logo.png" >
2025-05-10 11:24:17 -06:00
< meta name = "generator" content = "mkdocs-1.6.1, mkdocs-material-9.6.12" >
2025-05-10 17:00:32 +00:00
< title > Runtime Interfaces - mergerfs< / title >
2025-05-10 11:24:17 -06:00
< link rel = "stylesheet" href = "../assets/stylesheets/main.2afb09e1.min.css" >
2025-05-10 17:00:32 +00:00
< 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 = "#runtime-interfaces" class = "md-skip" >
Skip to content
< / a >
< / div >
< div data-md-component = "announce" >
< / div >
< div data-md-color-scheme = "default" data-md-component = "outdated" hidden >
< / 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.png" 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" >
Runtime Interfaces
< / 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 >
< div class = "md-search__suggest" data-md-component = "search-suggest" > < / div >
< / 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.png" 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" >
< a href = "../intro_to_filesystems/" class = "md-nav__link" >
< span class = "md-ellipsis" >
Intro to Filesystems
< / span >
< / a >
< / li >
< li class = "md-nav__item md-nav__item--nested" >
< input class = "md-nav__toggle md-toggle " type = "checkbox" id = "__nav_6" >
< label class = "md-nav__link" for = "__nav_6" id = "__nav_6_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_6_label" aria-expanded = "false" >
< label class = "md-nav__title" for = "__nav_6" >
< 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 = "../config/options/" class = "md-nav__link" >
< span class = "md-ellipsis" >
Options
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/deprecated_options/" class = "md-nav__link" >
< span class = "md-ellipsis" >
Deprecated Options
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/branches/" class = "md-nav__link" >
< span class = "md-ellipsis" >
branches
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/branches_mount_timeout/" class = "md-nav__link" >
< span class = "md-ellipsis" >
branches-mount-timeout
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/functions_categories_policies/" class = "md-nav__link" >
< span class = "md-ellipsis" >
functions, categories and policies
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/minfreespace/" class = "md-nav__link" >
< span class = "md-ellipsis" >
minfreespace
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/func_readdir/" class = "md-nav__link" >
< span class = "md-ellipsis" >
func.readdir
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/rename_and_link/" class = "md-nav__link" >
< span class = "md-ellipsis" >
rename and link
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/moveonenospc/" class = "md-nav__link" >
< span class = "md-ellipsis" >
moveonenospc
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/cache/" class = "md-nav__link" >
< span class = "md-ellipsis" >
caching
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/readahead/" class = "md-nav__link" >
< span class = "md-ellipsis" >
readahead
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/inodecalc/" class = "md-nav__link" >
< span class = "md-ellipsis" >
inodecalc
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/threads/" class = "md-nav__link" >
< span class = "md-ellipsis" >
threads
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/pin-threads/" class = "md-nav__link" >
< span class = "md-ellipsis" >
pin-threads
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/link_cow/" class = "md-nav__link" >
< span class = "md-ellipsis" >
link_cow
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/fuse_msg_size/" class = "md-nav__link" >
< span class = "md-ellipsis" >
fuse_msg_size
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/follow-symlinks/" class = "md-nav__link" >
< span class = "md-ellipsis" >
follow-symlinks
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/link-exdev/" class = "md-nav__link" >
< span class = "md-ellipsis" >
link-exdev
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/rename-exdev/" class = "md-nav__link" >
< span class = "md-ellipsis" >
rename-exdev
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/symlinkify/" class = "md-nav__link" >
< span class = "md-ellipsis" >
symlinkify
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/nullrw/" class = "md-nav__link" >
< span class = "md-ellipsis" >
nullrw
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/xattr/" class = "md-nav__link" >
< span class = "md-ellipsis" >
xattr
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/nfsopenhack/" class = "md-nav__link" >
< span class = "md-ellipsis" >
nfsopenhack
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/statfs/" class = "md-nav__link" >
< span class = "md-ellipsis" >
statfs / statvfs
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/flush-on-close/" class = "md-nav__link" >
< span class = "md-ellipsis" >
flush-on-close
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/export-support/" class = "md-nav__link" >
< span class = "md-ellipsis" >
export-support
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "../config/kernel-permissions-check/" class = "md-nav__link" >
< span class = "md-ellipsis" >
kernel-permissions-check
< / 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 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" >
Runtime Interfaces
< / span >
< span class = "md-nav__icon md-icon" > < / span >
< / label >
< a href = "./" class = "md-nav__link md-nav__link--active" >
< span class = "md-ellipsis" >
Runtime Interfaces
< / 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 = "#runtime-config" class = "md-nav__link" >
< span class = "md-ellipsis" >
Runtime Config
< / span >
< / a >
< nav class = "md-nav" aria-label = "Runtime Config" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#mergerfs-pseudo-file" class = "md-nav__link" >
< span class = "md-ellipsis" >
.mergerfs pseudo file
< / span >
< / a >
< nav class = "md-nav" aria-label = ".mergerfs pseudo file" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#keys" class = "md-nav__link" >
< span class = "md-ellipsis" >
Keys
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#values" class = "md-nav__link" >
< span class = "md-ellipsis" >
Values
< / span >
< / a >
< nav class = "md-nav" aria-label = "Values" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#usermergerfsbranches" class = "md-nav__link" >
< span class = "md-ellipsis" >
user.mergerfs.branches
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#example" class = "md-nav__link" >
< span class = "md-ellipsis" >
Example
< / span >
< / a >
< / li >
< / ul >
< / nav >
< / li >
< / ul >
< / nav >
< / li >
< li class = "md-nav__item" >
< a href = "#file-directory-xattrs" class = "md-nav__link" >
< span class = "md-ellipsis" >
file / directory xattrs
< / span >
< / a >
< / li >
< / ul >
< / nav >
< / li >
< li class = "md-nav__item" >
< a href = "#signals" class = "md-nav__link" >
< span class = "md-ellipsis" >
Signals
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#ioctl" class = "md-nav__link" >
< span class = "md-ellipsis" >
ioctl
< / span >
< / a >
< / li >
< / ul >
< / nav >
< / 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_17" >
< label class = "md-nav__link" for = "__nav_17" id = "__nav_17_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_17_label" aria-expanded = "false" >
< label class = "md-nav__title" for = "__nav_17" >
< 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/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/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/have_you_considered/" class = "md-nav__link" >
< span class = "md-ellipsis" >
"Have You Considered?"
< / 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 = "#runtime-config" class = "md-nav__link" >
< span class = "md-ellipsis" >
Runtime Config
< / span >
< / a >
< nav class = "md-nav" aria-label = "Runtime Config" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#mergerfs-pseudo-file" class = "md-nav__link" >
< span class = "md-ellipsis" >
.mergerfs pseudo file
< / span >
< / a >
< nav class = "md-nav" aria-label = ".mergerfs pseudo file" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#keys" class = "md-nav__link" >
< span class = "md-ellipsis" >
Keys
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#values" class = "md-nav__link" >
< span class = "md-ellipsis" >
Values
< / span >
< / a >
< nav class = "md-nav" aria-label = "Values" >
< ul class = "md-nav__list" >
< li class = "md-nav__item" >
< a href = "#usermergerfsbranches" class = "md-nav__link" >
< span class = "md-ellipsis" >
user.mergerfs.branches
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#example" class = "md-nav__link" >
< span class = "md-ellipsis" >
Example
< / span >
< / a >
< / li >
< / ul >
< / nav >
< / li >
< / ul >
< / nav >
< / li >
< li class = "md-nav__item" >
< a href = "#file-directory-xattrs" class = "md-nav__link" >
< span class = "md-ellipsis" >
file / directory xattrs
< / span >
< / a >
< / li >
< / ul >
< / nav >
< / li >
< li class = "md-nav__item" >
< a href = "#signals" class = "md-nav__link" >
< span class = "md-ellipsis" >
Signals
< / span >
< / a >
< / li >
< li class = "md-nav__item" >
< a href = "#ioctl" class = "md-nav__link" >
< span class = "md-ellipsis" >
ioctl
< / 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/runtime_interfaces.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/runtime_interfaces.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 = "runtime-interfaces" > Runtime Interfaces< / h1 >
< h2 id = "runtime-config" > Runtime Config< / h2 >
< h3 id = "mergerfs-pseudo-file" > .mergerfs pseudo file< / h3 >
< div class = "language-text highlight" > < pre > < span > < / span > < code > < span id = "__span-0-1" > < a id = "__codelineno-0-1" name = "__codelineno-0-1" href = "#__codelineno-0-1" > < / a > < mountpoint> /.mergerfs
< / span > < / code > < / pre > < / div >
< p > There is a pseudo file available at the mount point which allows for
the runtime modification of certain < strong > mergerfs< / strong > options. The file
will not show up in < strong > readdir< / strong > but can be < strong > stat< / strong > 'ed and manipulated
via < a href = "http://linux.die.net/man/2/listxattr" > {list,get,set}xattrs< / a >
calls.< / p >
< p > Any changes made at runtime are < strong > not< / strong > persisted. If you wish for
values to persist they must be included as options wherever you
configure the mounting of mergerfs (/etc/fstab).< / p >
< h4 id = "keys" > Keys< / h4 >
< p > Use < code > getfattr -d /mountpoint/.mergerfs< / code > or < code > xattr -l
/mountpoint/.mergerfs< / code > to see all supported keys. Some are
informational and therefore read-only. < code > setxattr< / code > will return EINVAL
(invalid argument) on read-only keys.< / p >
< h4 id = "values" > Values< / h4 >
< p > Same as the command line.< / p >
< h5 id = "usermergerfsbranches" > user.mergerfs.branches< / h5 >
< p > Used to query or modify the list of branches. When modifying there are
several shortcuts to easy manipulation of the list.< / p >
< table >
< thead >
< tr >
< th > Value< / th >
< th > Description< / th >
< / tr >
< / thead >
< tbody >
< tr >
< td > [list]< / td >
< td > set< / td >
< / tr >
< tr >
< td > +< [list]< / td >
< td > prepend< / td >
< / tr >
< tr >
< td > +> [list]< / td >
< td > append< / td >
< / tr >
< tr >
< td > -[list]< / td >
< td > remove all values provided< / td >
< / tr >
< tr >
< td > -< < / td >
< td > remove first in list< / td >
< / tr >
< tr >
< td > -> < / td >
< td > remove last in list< / td >
< / tr >
< / tbody >
< / table >
< p > < code > xattr -w user.mergerfs.branches +< /mnt/drive3 /mnt/pool/.mergerfs< / code > < / p >
< p > The < code > =NC< / code > , < code > =RO< / code > , < code > =RW< / code > syntax works just as on the command line.< / p >
< h5 id = "example" > Example< / h5 >
< div class = "language-text highlight" > < pre > < span > < / span > < code > < span id = "__span-1-1" > < a id = "__codelineno-1-1" name = "__codelineno-1-1" href = "#__codelineno-1-1" > < / a > [trapexit:/mnt/mergerfs] $ getfattr -d .mergerfs
< / span > < span id = "__span-1-2" > < a id = "__codelineno-1-2" name = "__codelineno-1-2" href = "#__codelineno-1-2" > < / a > user.mergerfs.branches=" /mnt/a=RW:/mnt/b=RW"
< / span > < span id = "__span-1-3" > < a id = "__codelineno-1-3" name = "__codelineno-1-3" href = "#__codelineno-1-3" > < / a > user.mergerfs.minfreespace=" 4294967295"
< / span > < span id = "__span-1-4" > < a id = "__codelineno-1-4" name = "__codelineno-1-4" href = "#__codelineno-1-4" > < / a > user.mergerfs.moveonenospc=" false"
< / span > < span id = "__span-1-5" > < a id = "__codelineno-1-5" name = "__codelineno-1-5" href = "#__codelineno-1-5" > < / a > ...
< / span > < span id = "__span-1-6" > < a id = "__codelineno-1-6" name = "__codelineno-1-6" href = "#__codelineno-1-6" > < / a >
< / span > < span id = "__span-1-7" > < a id = "__codelineno-1-7" name = "__codelineno-1-7" href = "#__codelineno-1-7" > < / a > [trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.category.search .mergerfs
< / span > < span id = "__span-1-8" > < a id = "__codelineno-1-8" name = "__codelineno-1-8" href = "#__codelineno-1-8" > < / a > user.mergerfs.category.search=" ff"
< / span > < span id = "__span-1-9" > < a id = "__codelineno-1-9" name = "__codelineno-1-9" href = "#__codelineno-1-9" > < / a >
< / span > < span id = "__span-1-10" > < a id = "__codelineno-1-10" name = "__codelineno-1-10" href = "#__codelineno-1-10" > < / a > [trapexit:/mnt/mergerfs] $ setfattr -n user.mergerfs.category.search -v newest .mergerfs
< / span > < span id = "__span-1-11" > < a id = "__codelineno-1-11" name = "__codelineno-1-11" href = "#__codelineno-1-11" > < / a > [trapexit:/mnt/mergerfs] $ getfattr -n user.mergerfs.category.search .mergerfs
< / span > < span id = "__span-1-12" > < a id = "__codelineno-1-12" name = "__codelineno-1-12" href = "#__codelineno-1-12" > < / a > user.mergerfs.category.search=" newest"
< / span > < / code > < / pre > < / div >
< h3 id = "file-directory-xattrs" > file / directory xattrs< / h3 >
< p > While they won't show up when using < code > getfattr< / code > < strong > mergerfs< / strong > offers a
number of special xattrs to query information about the files
served. To access the values you will need to issue a
< a href = "http://linux.die.net/man/2/getxattr" > getxattr< / a > for one of the
following:< / p >
< ul >
< li > < strong > user.mergerfs.basepath< / strong > : the base mount point for the file given the current getattr policy< / li >
< li > < strong > user.mergerfs.relpath< / strong > : the relative path of the file from the perspective of the mount point< / li >
< li > < strong > user.mergerfs.fullpath< / strong > : the full path of the original file given the getattr policy< / li >
< li > < strong > user.mergerfs.allpaths< / strong > : a NUL ('\0') separated list of full paths to all files found< / li >
< / ul >
< h2 id = "signals" > Signals< / h2 >
< ul >
< li > USR1: This will cause mergerfs to send invalidation notifications to
the kernel for all files. This will cause all unused files to be
released from memory.< / li >
< li > USR2: Trigger a general cleanup of currently unused memory. A more
thorough version of what happens every ~15 minutes.< / li >
< / ul >
< h2 id = "ioctl" > ioctl< / h2 >
< p > Found in < code > fuse_ioctl.cpp< / code > :< / p >
< div class = "language-C++ highlight" > < pre > < span > < / span > < code > < span id = "__span-2-1" > < a id = "__codelineno-2-1" name = "__codelineno-2-1" href = "#__codelineno-2-1" > < / a > < span class = "k" > typedef< / span > < span class = "w" > < / span > < span class = "kt" > char< / span > < span class = "w" > < / span > < span class = "n" > IOCTL_BUF< / span > < span class = "p" > [< / span > < span class = "mi" > 4096< / span > < span class = "p" > ];< / span >
< / span > < span id = "__span-2-2" > < a id = "__codelineno-2-2" name = "__codelineno-2-2" href = "#__codelineno-2-2" > < / a > < span class = "cp" > #define IOCTL_APP_TYPE 0xDF< / span >
< / span > < span id = "__span-2-3" > < a id = "__codelineno-2-3" name = "__codelineno-2-3" href = "#__codelineno-2-3" > < / a > < span class = "cp" > #define IOCTL_FILE_INFO _IOWR(IOCTL_APP_TYPE,0,IOCTL_BUF)< / span >
< / span > < span id = "__span-2-4" > < a id = "__codelineno-2-4" name = "__codelineno-2-4" href = "#__codelineno-2-4" > < / a > < span class = "cp" > #define IOCTL_GC _IO(IOCTL_APP_TYPE,1)< / span >
< / span > < span id = "__span-2-5" > < a id = "__codelineno-2-5" name = "__codelineno-2-5" href = "#__codelineno-2-5" > < / a > < span class = "cp" > #define IOCTL_GC1 _IO(IOCTL_APP_TYPE,2)< / span >
< / span > < span id = "__span-2-6" > < a id = "__codelineno-2-6" name = "__codelineno-2-6" href = "#__codelineno-2-6" > < / a > < span class = "cp" > #define IOCTL_INVALIDATE_ALL_NODES _IO(IOCTL_APP_TYPE,3)< / span >
< / span > < / code > < / pre > < / div >
< ul >
< li > IOCTL_FILE_INFO: Same as the "file / directory xattrs" mentioned
above. Use a buffer size of 4096 bytes. Pass in a string of
"basepath", "relpath", "fullpath", or "allpaths". Receive details in
same buffer.< / li >
< li > IOCTL_GC: Triggers a thorough garbage collection of excess
memory. Same as SIGUSR2.< / li >
< li > IOCTL_GC1: Triggers a simple garbage collection of excess
memory. Same as what happens every 15 minutes normally.< / li >
< li > IOCTL_INVALIDATE_ALL_NODES: Same as SIGUSR1. Send invalidation
notifications to the kernel for all files causing unused files to be
released from memory.< / li >
< / ul >
< / 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 = "../error_handling_and_logging/" class = "md-footer__link md-footer__link--prev" aria-label = "Previous: Error Handling and Logging" >
< 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" >
Error Handling and Logging
< / div >
< / div >
< / a >
< a href = "../remote_filesystems/" class = "md-footer__link md-footer__link--next" aria-label = "Next: Remote Filesystems" >
< div class = "md-footer__title" >
< span class = "md-footer__direction" >
Next
< / span >
< div class = "md-ellipsis" >
Remote Filesystems
< / 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 >
2025-05-10 11:24:17 -06:00
< 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" , "search.suggest" , "toc.follow" ] , "search" : "../assets/javascripts/workers/search.f8cc74c7.min.js" , "tags" : null , "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" } , "version" : { "provider" : "mike" } } < / script >
2025-05-10 17:00:32 +00:00
2025-05-10 11:24:17 -06:00
< script src = "../assets/javascripts/bundle.c8b220af.min.js" > < / script >
2025-05-10 17:00:32 +00:00
< / body >
< / html >
