SFSMOUNT(1)

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.

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

SEE ALSO

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