LEIL-MOUNT(1)

📦 version 5.12.0, in nixpkgs unstable

💅 leil-mount — the leil-mount(1) glow-up

okay so bestie, buckle up ✨ this is the manual page for leil-mount, and by the end of it you're gonna be mounting Leil File System like it's nothing. no cap.

🌸 NAME

leil-mount — mount Leil File System 🦋

✨ SYNOPSIS

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

leil-mount -h|--help

leil-mount -V|--version

like, pick your fighter 💅

💖 DESCRIPTION

Mounts Leil File System. that's the whole vibe. let's get into it 🎀

🌈 General options

  • -h, --help — shows you the help and dips out. your lil safety net 🫶
  • -V — shows version info and exits. slay, now you know what you're running ✨

🔥 FUSE options

  • -d, -o debug — turns on debug mode. heads up: this implies -f 👑
  • -f — foreground operation. it stays right there with you, main character energy 💅
  • -s — disables multi-threaded operation. one thing at a time, and honestly? valid 🙈

🦋 LeilFS options

  • -c CFGFILE, -o sfscfgfile=CFGFILE — loads a file that has extra mount options in it. like a lil cheat sheet 📋
  • -m, --meta, -o sfsmeta — mounts the SFSMETA companion filesystem instead of the primary LeilFS. this is the one that lets you poke at trashed and reserved files, iykyk 💀 (See NOTES)
  • -n, --nostdopts — skips the default mount options (-o allow_other,default_permissions). it's equivalent to -o nostdmountoptions ⭐
  • --nonempty — lets you mount over a non-empty file/dir. equivalent to -o nonempty 🌸
  • -p, -o askpassword — prompts you for a password. it's the interactive version of -o sfspassword=PASS 🔐
  • -H HOST, -o sfsmaster=HOST — connects to the LeilFS master on HOST (default is sfsmaster) 🧚
  • -P PORT, -o sfsport=PORT — connects to the LeilFS master on PORT (default is 9421) 🔌
  • -B HOST, -o sfsbind=HOST — the local address to use when connecting to the master, instead of the default one 🏠
  • -S PATH, -o sfssubfolder=PATH — mounts that specific LeilFS directory (default is /, aka the whole entire filesystem, no big deal) 👑
  • -o enablefilelocks=[0,1] — enables/disables global file locking (disabled by default) 🔒
  • -o sfspassword=PASSWORD — authenticates to the LeilFS master with PASSWORD 🤫
  • -o sfsmd5pass=MD5 — authenticates to the LeilFS master using a directly given MD5 (only if the sfspassword option isn't specified) 🧮
  • -o tlsconfigfile=PATH — path to the TLS configuration file for client-side TLS settings. (there is no default value.) 🛡️
  • -o sfsdelayedinit — the connection to the master happens in the background, so with this option the mount can run without a network. good for being run from fstab / init scripts etc. etc. 😴
  • -o sfsacl — enables ACL support (disabled by default) 📝
  • -o sfsaclcacheto=SEC — sets the ACL cache timeout in seconds (default: 1.0) ⏱️
  • -o sfsaclcachesize=N — sets the ACL cache size in 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 — sets the sugid clear mode (see below) 🧼
  • -o sfsdebug — prints some LeilFS-specific debugging info 🐛
  • -o sfscachemode=CACHEMODE — sets the cache mode (see DATA CACHE MODES; default is AUTO) 🗄️
  • -o sfsattrcacheto=SEC — sets the attributes cache timeout in seconds (default: 1.0) 🕐
  • -o sfsentrycacheto=SEC — sets the file entry cache timeout in seconds (default: 0.0, i.e. no cache) 🚫
  • -o sfsdirentrycacheto=SEC — sets the directory entry cache timeout in seconds (default: 1.0) 📁
  • -o sfswritecachesize=N — specifies write cache size in MiB, in range 16..2048 (default: 128) ✍️
  • -o sfschunkserverwavewriteto=MSEC — sets the timeout for executing each wave of a write operation, in milliseconds (default: 50) 🌊
  • -o sfscacheperinodepercentage=N — specifies what part of the write cache not occupied by other inodes a single inode can occupy, measured in %. e.g. when N=75 and inode X uses 10 MiB, and all other inodes use 20 MiB out of a 100 MiB cache, X can use 50 MiB more (since 75% of 80 MiB is 60 MiB). default: 100 🍰
  • -o sfschunkserverreadto=MSEC — sets the timeout for the whole communication with a chunkserver during a read operation, in milliseconds (default: 2000) 📡
  • -o sfschunkserverwriteto=MSEC — sets the chunkserver response timeout during a write operation, in milliseconds (default: 5000) ⏳
  • -o sfschunkserverrtt=MSEC — sets the timeout after which a SYN packet is considered lost during the first retry of connecting a chunkserver (default: 200) 📶
  • -o sfschunkserverconnectreadto=MSEC — sets the timeout for connecting with chunkservers during a read operation, in milliseconds (default: 2000) 🔗
  • -o sfschunkserverwavereadto=MSEC — sets the timeout for executing each wave of a read operation, in milliseconds (default: 500) 🌊
  • -o sfschunkservertotalreadto=MSEC — sets the timeout for the whole communication with chunkservers during a read operation, in milliseconds (default: 2000) 🕰️
  • -o cacheexpirationtime=MSEC — sets the timeout for read cache entries to be considered valid, in milliseconds. 0 disables the cache (default: 1000) ⏲️
  • -o readbuffersexpirationtime=MSEC — sets the timeout for read cache buffers to expire. read buffers get recycled among read operations to save allocating and deallocating that memory. those buffers are held aside for this amount of milliseconds before being released (default: 1000) ♻️
  • -o readaheadmaxwindowsize=KB — sets the max value of the readahead window per single descriptor, in kibibytes (default: 16384) 🪟
  • -o readcachemaxsizepercentage=P — sets the percentage of system memory used for the max value of read cache size (default: 60%) 💾
  • -o readworkers=N — defines the number of read workers (default: 30) 👯
  • -o maxreadaheadrequests=N — defines the number of readahead requests per inode (default: 2) 🔍
  • -o sfsrlimitnofile=N — tries to change the limit of simultaneously opened file descriptors on startup (default: 100000) 📂
  • -o sfsnice=LEVEL — tries to change the nice level to the specified value on startup (default: -19) 😇
  • -o sfswriteworkers=N — defines the number of write workers (default: 10) ✏️
  • -o sfswritewindowsize=N — defines the write window size (in blocks) for each chunk. can be updated via the tweaks hidden file (default: 15) 🪟
  • -o sfsmemlock — tries to lock memory (must be enabled at build time) 🔐
  • -o sfsdonotrememberpassword — does not remember the password in memory. more secure, but when the session is lost then a new session is created without a password ⚠️
  • -o sfsioretries=N — specifies the number of retries before an I/O error is returned (default: 30) 🔁
  • -o sfsreportreservedperiod=N — specifies the interval for reporting reserved inodes, in seconds (default: 30) 📊
  • -o sfsiolimits=PATH — specifies the local I/O limiting configuration file (default: no I/O limiting) 🚦
  • -o symlinkcachetimeout=N — sets the timeout value for symlink cache timeout in seconds. default value is 3600 🔗
  • -o bandwidthoveruse=N — defines 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 sfsmaxchunkswritteninparallelperinode=N — defines the maximum number of chunks that can be written in parallel per inode. 0 stands for unlimited (default: 0) 🧱
  • -o sfsusewriteflushpacket=0|1 — when set to 1, suggests the chunkserver flush the packets received every window size blocks (option sfswritewindowsize) or when a write needs to finish (e.g. when flush() is called on the inode or when enough time has passed). can be updated via the tweaks hidden file (default: 0) 🚿
  • -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, which 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, which 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 — sets the period of message suppression in seconds for logging on the notification area (default: 10) 🤫
  • -o statfscachetimeout=MSEC — sets the statfs cache timeout in milliseconds. when equal to 0 the cache is disabled (default: 0) 📈
  • -o usequotainvolumesize=0|1 — when set to 1, uses the user and group specific quota hard limit to calculate the volume size (default: 0) 📏
  • -o maxwaitretrytime=SECS — sets the maximum wait time in seconds for retrying a master server communication attempt, in seconds (default: 10) ⏳
  • -o mastercommsleeptimedivisor=N — specifies 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 — mounts the file-system in read-write (default) or read-only mode respectively 🔁
  • -o suid | -o nosuid — enables or disables suid/sgid attributes to work 🪪
  • -o dev | -o nodev — enables or disables character or block special device files interpretation 🖥️
  • -o exec | -o noexec — allows or disallows execution of binaries 🏃‍♀️

✨ DATA CACHE MODES ✨

Okay so there are three cache modes, bestie: NO, YES and AUTO. The default option is AUTO, and ngl you should not change it unless you really, truly know what you're doing. Like, know it in your soul. 😭

🚫 NO, NONE or NEVER

Never ever allow files data to be kept in cache. Safest vibes, but it can reduce efficiency — it's giving "safe but slow" 💅

✅ YES or ALWAYS

Always allow files data to be kept in cache. And yes, this one is dangerous. Consider yourself warned, no cap. 💀

🦋 AUTO

File cache is managed by leil-master automatically. This one should be very safe and efficient — it's the main character for a reason 👑

🌸 SUGID CLEAR MODE 🌸

SMODE can be set to:

  • NEVER — SFS will not change suid and sgid bit on chown
  • ALWAYS — clear suid and sgid on every chown — the safest operation 🫶
  • OSX — standard behavior in OS X and Solaris (a chown made by an unprivileged user clears 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. And beware, bestie — there's 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. Like, it just slips right past. 🙈

🎀 FSTAB 🎀

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

leil-master:/ /mnt/leil safs rw 0 0

Screenshot it, tattoo it, whatever works for you 💖

🦋 REPORTING BUGS 🦋

Report bugs to the GitHub repository https://github.com/leil-io/leilfs as an issue. We literally read them, so don't be shy 🫶

⭐ 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. So like… don't. 😭

This limit was fixed and removed in master and leil-mount version 5.3.0. Slay 💅

Copyright 2008-2009 Gemius SA

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

Copyright 2023-2024 Leil Storage OÜ

LeilFS 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.

LeilFS 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 LeilFS. If not, see http://www.gnu.org/licenses/.

🌈 SEE ALSO 🌈

leil-master(8) leilfs(7), mount(8)

okay that's the whole page, you made it to the end, I'm so proud of you 🥹💖 this was LEIL-MOUNT(1), dated 1980-01-01 (yes really, iconic timestamp honestly 👑). go forth and mount responsibly, bestie 🎀✨

📦 where this page comes from