SFSMOUNT(1)

📦
version 5.8.0 · 4 versions
, in ubuntu stonking

🍓 sfsmount(1) — the mount-SaunaFS girlies' edition 🍓

okay bestie, buckle in, because this is sfsmount — the section 1 manual page — and she is a long one. no cap. we're doing this together, one flag at a time. 💅

✨ NAME ✨

sfsmount — mount Sauna File System 🧖♀️🔥

🌸 SYNOPSIS 🌸

sfsmount [HOST:[PORT]]:[PATH] [-d] [-f] [-s] [-m] [-n] [-p]
         [-H HOST] [-P PORT] [-S PATH] [-o opt[,opt]...]

sfsmount -h|--help

sfsmount -V|--version

🦋 DESCRIPTION 🦋

Mount Sauna File System. that's it, that's the whole vibe, she does what it says on the tin. iconic. now let's get into the options because there are, um, a LOT.

🎀 General options

  • -h, --help — show the help text and dip out. ✨
  • -V — print the version info and exit. that's it, that's her whole arc.

💜 FUSE options

  • -d, -o debug — turn on debug mode (implies -f, so you're automatically in foreground, no escape). 🐛
  • -f — foreground operation. she stays right there in your terminal, watching. 👀
  • -s — disable multi-threaded operation. one thing at a time, she's a single-task girly (by request). 🙈

🌈 SaunaFS options

  • -c CFGFILE, -o sfscfgfile=CFGFILE — loads a file with extra mount options. your lil cheat sheet. 📝
  • -m, --meta, -o sfsmeta — mounts the SFSMETA companion filesystem instead of the primary SaunaFS one. this is how you get to hang with trashed and reserved files. (peep the NOTES bestie) 💀
  • -n, --nostdopts — omits the default mount options (-o allow_other,default_permissions). same energy as -o nostdmountoptions. 🚫
  • --nonempty — allows mounts over a non-empty file/dir. same as -o nonempty. 🫶
  • -p, -o askpassword — prompts you for a password. it's the interactive version of -o sfspassword=PASS. 🔐
  • -H HOST, -o sfsmaster=HOST — connect to the SaunaFS master on HOST (default is sfsmaster). 📡
  • -P PORT, -o sfsport=PORT — connect to the SaunaFS master on PORT (default is 9421). 🔌
  • -B HOST, -o sfsbind=HOST — the local address to use for connecting with the master instead of the default one. 🏠
  • -S PATH, -o sfssubfolder=PATH — mount that specific SaunaFS directory (default is /, aka the whole entire filesystem, all of it, the whole three-course meal). 📂
  • -o enablefilelocks=[0,1] — enables/disables global file locking (disabled by default, so like, off unless you say otherwise). 🔒
  • -o sfspassword=PASSWORD — authenticate to the SaunaFS master with PASSWORD. 🗝️
  • -o sfsmd5pass=MD5 — authenticate to the SaunaFS master using a directly given MD5. this one only kicks in if sfspassword isn't specified. 🧮
  • -o tlsconfigfile=PATH — path to the TLS configuration file for client-side TLS settings. (there is no default value, so if you want TLS, you bring your own file.) 🛡️
  • -o sfsdelayedinit — the connection with the master happens in the background. big deal because with this option the mount can be run without network — perfect for being run from fstab / init scripts etc. main character energy for boot sequences. ⏳
  • -o sfsacl — enable ACL support (disabled by default). 📋
  • -o sfsaclcacheto=SEC — set ACL cache timeout in seconds (default: 1.0). ⏱️
  • -o sfsaclcachesize=N — define ACL cache size as a number of entries (0: no cache; default: 1000). 📦
  • -o sfsrwlock=0|1 — when set to 1, parallel reads from the same descriptor are performed (default: 1). 🏃♀️🏃♀️
  • -o sfsmkdircopysgid=N — whether the sgid bit should be copied during a mkdir operation (on Linux default: 1, otherwise: 0). 🧬
  • -o sfssugidclearmode=SMODE — set the sugid clear mode (see below). 🧹
  • -o sfsdebug — print some SaunaFS-specific debugging information. 🐞
  • -o sfscachemode=CACHEMODE — set the cache mode (see DATA CACHE MODES; default is AUTO). 🗂️
  • -o sfsattrcacheto=SEC — set attributes cache timeout in seconds (default: 1.0). ⏲️
  • -o sfsentrycacheto=SEC — set file entry cache timeout in seconds (default: 0.0, i.e. no cache). 🙅♀️
  • -o sfsdirentrycacheto=SEC — set directory entry cache timeout in seconds (default: 1.0). 📁
  • -o sfswritecachesize=N — specify write cache size in MiB (in range: 16..2048 — default: 128). ✍️
  • -o sfschunkserverwavewriteto=MSEC — set timeout for executing each wave of a write operation, in milliseconds (default: 50). 🌊
  • -o sfscacheperinodepercentage=N — specify what part of the write cache, when it's not occupied by other inodes, a single inode can occupy (measured in %). E.g. When N=75 and the inode X uses 10 MiB, and all other inodes use 20 MiB out of 100 MiB cache, X can use 50 MiB more (since 75% of 80 MiB is 60 MiB). Default: 25. 🍰
  • -o sfschunkserverreadto=MSEC — set timeout for the whole communication with a chunkserver during a read operation, in milliseconds (default: 2000). 📖
  • -o sfschunkserverwriteto=MSEC — set chunkserver response timeout during a write operation, in milliseconds (default: 5000). 📝
  • -o sfschunkserverrtt=MSEC — set the timeout after which a SYN packet is considered lost during the first retry of connecting a chunkserver (default: 200). 📶
  • -o sfschunkserverconnectreadto=MSEC — set timeout for connecting with chunkservers during a read operation, in milliseconds (default: 2000). 🤝
  • -o sfschunkserverwavereadto=MSEC — set timeout for executing each wave of a read operation, in milliseconds (default: 500). 🌊
  • -o sfschunkservertotalreadto=MSEC — set timeout for the whole communication with chunkservers during a read operation, in milliseconds (default: 2000). ⏳
  • -o cacheexpirationtime=MSEC — set the timeout for read cache entries to be considered valid, in milliseconds. 0 disables the cache (default: 1000). ⌛
  • -o readbuffersexpirationtime=MSEC — set the timeout for read cache buffers to expire. Read buffers get recycled among read operations to save on allocating and deallocating that memory. Those buffers get held aside for this amount of milliseconds before being released (default: 1000). ♻️
  • -o readaheadmaxwindowsize=KB — set the max value of the readahead window per single descriptor, in kibibytes (default: 16384). 🔭
  • -o readcachemaxsizepercentage=P — set the percentage of system memory used for the max value of the read cache size (default: 60%). 🧠
  • -o readworkers=N — define the number of read workers (default: 30). 👷♀️
  • -o maxreadaheadrequests=N — define the number of readahead requests per inode (default: 2). 🔢
  • -o sfsrlimitnofile=N — try to change the limit of simultaneously opened file descriptors on startup (default: 100000). 🗃️
  • -o sfsnice=LEVEL — try to change the nice level to the specified value on startup (default: -19). 😇
  • -o sfswriteworkers=N — define the number of write workers (default: 10). 👷
  • -o sfswritewindowsize=N — define the write window size (in blocks) for each chunk (default: 15). 🪟
  • -o sfsmemlock — try to lock memory (must be enabled at build time, so it's a build-time situationship). 🔐
  • -o sfsdonotrememberpassword — do not remember the password in memory — more secure, BUT when the session is lost then a new session is created without a password. tradeoffs bestie. ⚠️
  • -o sfsioretries=N — specify the number of retries before an I/O error is returned (default: 30). 🔁
  • -o sfsreportreservedperiod=N — specify the interval for reporting reserved inodes, in seconds (default: 30). 📅
  • -o sfsiolimits=PATH — specify the local I/O limiting configuration file (default: no I/O limiting). 🚦
  • -o symlinkcachetimeout=N — set the timeout value for the symlink cache timeout, in seconds. Default value is 3600. 🔗
  • -o bandwidthoveruse=N — define the ratio of allowed bandwidth overuse when fetching data. Default value is 1.0. This option is effective only with N+M goals (erasure codes). 📈
  • -o nostdmountoptions — equivalent to the --nostdopts (-n) option, for use in fstab. 📜
  • -o nonempty — equivalent to the --nonempty option, for use in fstab. 📜
  • -o sfsuseinodebasedwritealgorithm=0|1 — use the inode based write algorithm when set to 1. use the chunk based write algorithm when set to 0. though the chunk based algorithm is faster in most cases, the inode based algorithm may prove useful in some scenarios (default: 0). ⚖️
  • -o sfsignoreflush=0|1 — Advanced: use with caution. ignore the usual behaviour of flush by replying SUCCESS to it immediately. targets fast creation of small files, but it may cause data loss during crashes when allegedly flushed data is still being processed (default: 0). 💀🔥
okay bestie, for real, that one above? sfsignoreflush? that's the "she's beauty, she's grace, she will lose your data" option. read the warning. respect the warning. 🙏
  • -o sfsdirectio=0|1 — whether to use FUSE DirectIO. this may improve performance when reading large files under certain conditions. 🚀
  • -o limitglibcmallocarenas=N — Linux only: limit glibc malloc arenas to the given value — prevents using a huge amount of virtual memory. this can influence performance by reducing memory fragmentation and improving cache locality, but it may also lead to contention and reduced parallelism in multi-threaded applications. use it in constrained memory environments, recommended values are 4 or 8. (default is 0: disabled or let glibc decide). 🧵
  • -o malloctrimperiod=MSEC — Linux only: call malloc_trim on a periodical basis — prevents using a huge amount of virtual memory by returning already freed memory to the OS. this can influence performance by increasing memory fragmentation and worsening cache locality. use it in constrained memory environments, recommended values are 300 or 1000. minimum value is 100 to avoid excessive calls to malloc_trim. (default is 0: disabled periodic trimming). 🧽
  • -o sfslognotificationarea=0|1 — enable/disable logging to the Linux notification area (default: 0). 🔔
  • -o sfsmessagesuppressionperiod=N — set the period of message suppression, in seconds, for logging on the notification area (default: 10). 🤫
  • -o statfscachetimeout=MSEC — set the statfs cache timeout in milliseconds. when equal to 0 the cache is disabled (default: 0). 📊
  • -o usequotainvolumesize=0|1 — when set to 1, use the user and group specific quota hard limit to calculate the volume size (default: 0). 🧾
  • -o maxwaitretrytime=SECS — set the maximum wait time, in seconds, for retrying a master server communication attempt, in seconds (default: 10). ⏰
  • -o mastercommsleeptimedivisor=N — specify the number of retry attempts between each increase of the master-communication sleep interval. the client starts with a 1 second pause and adds 1 second every N retries, up to the maxwaitretrytime limit. when reconnecting, the client makes up to sfsioretries attempts, applying the computed pause at each zero-based retry. for example, with mastercommsleeptimedivisor=2, maxwaitretrytime=3 and sfsioretries=10 the sleep intervals are: try 0 → 1 s, try 1 → 1 s, try 2 → 2 s, try 3 → 2 s, try 4 → 3 s, then 3 s for all subsequent retries until reaching the last retry counter index, which would be try 9 (default: 3). 😴

💫 General mount options (see mount(8) manual)

  • -o rw | -o ro — mount the file-system in read-write (default) or read-only mode respectively. ✍️ / 🔏
  • -o suid | -o nosuid — enable or disable suid/sgid attributes to work. 🪪
  • -o dev | -o nodev — enable or disable character or block special device files interpretation. 🎛️
  • -o exec | -o noexec — allow or disallow execution of binaries. ▶️

okay we are not done yet, there's more of this page coming, so don't go anywhere bestie 💖

✨ DATA CACHE MODES ✨

bestie there are three cache modes and they are NO, YES and AUTO 💖 The default option is AUTO and you genuinely should not change it unless you really know what you are doing, like, actually know. In AUTO mode the data cache is managed automatically by sfsmaster and it just… handles it. queen behavior 👑

  • NO, NONE or NEVER — never allow files data to be kept in cache (safest but can reduce efficiency) 🛡️
  • YES or ALWAYS — always allow files data to be kept in cache (dangerous) 💀
  • AUTO — file cache is managed by sfsmaster automatically (should be very safe and efficient) 🌟

🎀 SUGID CLEAR MODE 🎀

okay so SMODE can be set to:

  • NEVER - SFS will not change suid and sgid bit on chown
  • ALWAYS - clear suid and sgid on every chown - safest operation
  • OSX - standard behavior in OS X and Solaris (chown made by unprivileged user clear suid and sgid)
  • BSD - standard behavior in BSD systems (like in OSX, but only when something is really changed)
  • EXT - standard behavior in most file systems on Linux (directories not changed, others: suid cleared always, sgid only when group exec bit is set)
  • SFS - standard behavior in SFS on Linux (like EXT but directories are changed by unprivileged users)

💅 SMODE extra info 💅

btrfs, ext2, ext3, ext4, hfs[+], jfs, ntfs and reiserfs on Linux work as EXT.

Only sfs on Linux works a little different. Beware that there is a strange operation - chown(-1,-1) which is usually converted by a kernel into something like chmod ug-s, and therefore can't be controlled by SFS as chown 😭

🌸 FSTAB 🌸

You can define your /etc/fstab SaunaFS share like this:

saunafs-master:/ /mnt/sauna default 0 0

🦋 REPORTING BUGS 🦋

Report bugs to the GitHub repository https://github.com/leil-io/saunafs as an issue. (yes bestie, they want the issues filed there, not slid into anyone's DMs 🫶)

⭐ NOTES ⭐

The metadata mount point has two directories available: trash and reserved. 👑

In trash you can see files that have been deleted but are still being kept in master trash. You can undelete them by moving the files into trash/undel, and delete permanently by deleting them again. ✨

There is a bug with this though. See BUGS for more details. 🙈

💀 BUGS 💀

Due to a limit in the protocol, the metadata mount point can at most return the first 1 million trash/reserved files. To see more, you will need to either delete or undelete the existing files. Older versions of master (4.9.0 or earlier) will crash when reading a lot of files in trash/reserved. After more than 1 million files in trash/reserved, it becomes unsafe to read trash on those versions.

This limit was fixed and removed in master and sfsmount version 5.3.0. 🎉

Copyright 2008-2009 Gemius SA

Copyright 2013-2019 Skytechnology sp. z o.o.

Copyright 2023-2024 Leil Storage OÜ

SaunaFS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

SaunaFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with SaunaFS. If not, see http://www.gnu.org/licenses/.

🌈 SEE ALSO 🌈

sfsmaster(8) sfs(7), mount(8)

and that's the whole page bestie, we ate and left absolutely no crumbs 💅 this version is dated 2026-07-29 and it's from SFSMOUNT(1) — go mount something iconic, ily 🫶💖✨

📦 where this page comes from