sfsmount(1)
===========

== NAME

sfsmount - mount Sauna File System

== SYNOPSIS

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

[verse]
*sfsmount* *-h*|*--help*

[verse]
*sfsmount* *-V*|*--version*

== DESCRIPTION

Mount Sauna File System.

General options:

*-h*, *--help*::
Display help and exit.

*-V*::
Display version information and exit.

FUSE options:

*-d*, *-o debug*::
Enable debug mode (implies *-f*).

*-f*::
Foreground operation.

*-s*::
Disable multi-threaded operation.

SaunaFS options:

*-c* 'CFGFILE', *-o sfscfgfile=*'CFGFILE'::
Loads file with additional mount options.

*-m*, *--meta*, *-o sfsmeta*::
Mount SFSMETA companion filesystem instead of primary SaunaFS. This allows you
to interact with trashed and reserved files. (See NOTES)

*-n*, *--nostdopts*::
Omit default mount options (*-o allow_other,default_permissions*). Equivalent
to *-o nostdmountoptions*.

*--nonempty*::
Allow mounts over non-empty file/dir. Equivalent to *-o nonempty*.

*-p*, *-o askpassword*::
Prompt for password (interactive version of *-o sfspassword=*'PASS').

*-H* 'HOST', *-o sfsmaster=*'HOST'::
Connect with SaunaFS master on 'HOST' (default is sfsmaster).

*-P* 'PORT', *-o sfsport=*'PORT'::
Connect with SaunaFS master on 'PORT' (default is 9421).

*-B* 'HOST', *-o sfsbind=*'HOST'::
Local address to use for connecting with master instead of default one.

*-S* 'PATH', *-o sfssubfolder=*'PATH'::
Mount specified SaunaFS directory (default is */*, i.e. whole filesystem).

*-o enablefilelocks=*[0,1]::
Enables/disables global file locking (disabled by default).

*-o sfspassword=*'PASSWORD'::
Authenticate to SaunaFS master with 'PASSWORD'.

*-o sfsmd5pass=*'MD5'::
Authenticate to SaunaFS master using directly given 'MD5' (only if
*sfspassword* option is not specified).

*-o tlsconfigfile=*'PATH'::
Path to the TLS configuration file for client-side TLS settings.
(there is no default value).

*-o sfsdelayedinit*::
Connection with master is done in background - with this option mount can be
run without network (good for being run from fstab / init scripts etc.).

*-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 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'::
sgid bit should be copied during mkdir operation (on Linux default: 1,
otherwise: 0).

*-o sfssugidclearmode=*'SMODE'::
Set sugid clear mode (see below).

*-o sfsdebug*::
Print some SaunaFS-specific debugging information.

*-o sfscachemode=*'CACHEMODE'::
Set 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 non occupied by other inodes can a single
inode 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 whole communication with a chunkserver during read operation in
milliseconds (default: 2000).

*-o sfschunkserverwriteto=*'MSEC'::
Set chunkserver response timeout during write operation in milliseconds
(default: 5000).

*-o sfschunkserverrtt=*'MSEC'::
Set timeout after which 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 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 timeout for read cache entries to be considered valid in milliseconds. 0
disables cache (default: 1000).

*-o readbuffersexpirationtime=*'MSEC'::
Set timeout for read cache buffers to expire. Read buffers will be recycled
among read operations to save allocation and deallocation of that memory. Those
buffers will be held aside for this amount of milliseconds before releasing them
(default: 1000).

*-o readaheadmaxwindowsize=*'KB'::
Set max value of readahead window per single descriptor in kibibytes (default: 16384).

*-o readcachemaxsizepercentage=*'P'::
Set percentage of system memory used for max value of read cache size (default: 60%).

*-o readworkers=*'N'::
Define number of read workers (default: 30).

*-o maxreadaheadrequests=*'N'::
Define number of readahead requests per inode (default: 2).

*-o sfsrlimitnofile=*'N'::
Try to change limit of simultaneously opened file descriptors on startup
(default: 100000).

*-o sfsnice=*'LEVEL'::
Try to change nice level to specified value on startup (default: -19).

*-o sfswriteworkers=*'N'::
Define number of write workers (default: 10).

*-o sfswritewindowsize=*'N'::
Define write window size (in blocks) for each chunk (default: 15).

*-o sfsmemlock*::
Try to lock memory (must be enabled at build time).

*-o sfsdonotrememberpassword*::
Do not remember password in memory - more secure, but when session is lost then
new session is created without password.

*-o sfsioretries=*'N'::
Specify number of retries before I/O error is returned (default: 30).

*-o sfsreportreservedperiod=*'N'::
Specify interval for reporting reserved inodes in seconds (default: 30).

*-o sfsiolimits=*'PATH'::
Specify local I/O limiting configuration file (default: no I/O limiting).

*-o symlinkcachetimeout=*'N'::
Set timeout value for symlink cache timeout in seconds. Default value is 3600.

*-o bandwidthoveruse=*'N'::
Define 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 *--nostdopts* (*-n*) option for use in fstab.

*-o nonempty*::
Equivalent to *--nonempty* option for use in fstab.

*-o sfsuseinodebasedwritealgorithm=*'0|1'::
Use inode based write algorithm when set to 1. Use chunk based write algorithm
when set to 0. Though chunk based algorithm is faster in most cases, inode
based algorithm may prove useful in some scenarios (default: 0).

*-o sfsignoreflush=*'0|1'::
Advanced: use with caution. Ignore flush usual behavior by replying SUCCESS to
it immediately. Targets fast creation of small files, but may cause data loss
during crashes when allegedly flushed data is still being processed (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 given value - prevents from using
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 from using
huge amount of virtual memory by returning already freed memory to 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 Linux notification area (default: 0).

*-o sfsmessagesuppressionperiod=*'N'::
Set period of message suppression in seconds for logging on notification area
(default: 10).

*-o statfscachetimeout=*'MSEC'::
Set 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 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.

== DATA CACHE MODES

There are three cache modes: *NO*, *YES* and *AUTO*. Default option is *AUTO*
and you shouldn't change it unless you really know what you are doing. In
*AUTO* mode data cache is managed automatically by sfsmaster.

*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

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/saunafs safs default 0 0

== REPORTING BUGS

Report bugs to the GitHub repository <https://github.com/leil-io/saunafs> as an
issue.

== 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

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)
