Windows client

The current SaunaFS Windows Client (1.1.6) consists of the Command Line Interface (CLI) client, the SaunaFS Admin tool and the helper of the CLI client. Install our client from the provided exe file. The CLI client is in “C:\Program Files\SaunaFS\sfsmount.exe” on default installation path.

The CLI client works as an executable that receives commands passed by command line, like from CMD or PowerShell. After moving the console to the installation folder, you may start using the app, as well as the saunafs-admin and sfsmount-manager tools.

For saunafs-admin help, please check the output of the saunafs-admin --help. This article will describe most of the options of the CLI client and the ones of the sfsmount-manager.

Windows Client is licensed separately from the other parts of the SaunaFS software. For more information about the licensing terms for Windows Client, please see the Licensing section of this documentation.

General options

Option	Description
-H HOST | -o sfsmaster=HOST	define sfsmaster location (default: sfsmaster). It defines the IP of the master of the SaunaFS system, i.e. it defines to which system the client is connecting to.
-P PORT | -o sfsport=PORT	define sfsmaster port number (default: 9421).
-D LETTER | -o sfsdriveletter=LETTER	mount filesystem as drive with letter LETTER (default: Z).

For instance, the command:

sfsmount -H 192.168.56.1 -P 9521 -D S

should display a new local drive mounted in the letter S. The IP 192.168.56.1 must host a SaunaFS master server listening for incoming client communications on port 9521.

Extended general options

Option	Description
-S PATH | -o sfssubfolder=PATH	define subfolder to mount as root (default: /). The storage could have a number of folders, this option allows the user to display inside a mounted drive only the content of one of those specific folders.
-o sfsvolumelabel=NAME	mounted filesystem will appear with label NAME.
-o sfsuncpath=PATH	mount filesystem as a network drive with UNC path PATH. PATH format is SERVER/DRIVE.
-o sfsmountingsubfolder=PATH	mount filesystem at a specified PATH folder. When this option is set the drive letter option must not be set.

The pairs of options sfsvolumelabel-sfsuncpath and sfsuncpath-sfsmountingsubfolder are mutually exclusive. Please only use one of the two while writing mount command because some options will be ignored.

Example 1

sfsmount -H 192.168.56.1 -P 9521 -D S -S /data/ProjectS -o sfsvolumelabel=ProjectS

should display the following regular drive:

i.e. a regular drive labeled ProjectS and displaying only the contents of the folder “/data/ProjectS” of the storage.

Example 2

sfsmount -H 192.168.56.1 -P 9521 -D S -o sfsuncpath=storage/ProjectS

should display the following drive:

i.e. a network drive on the desired UNC path.

Example 3

sfsmount -H 192.168.56.1 -P 9521 -o sfsmountingsubfolder=C:\\mnt -o sfsvolumelabel=ProjectS

should create the “ProjectS” folder in the “C:\mnt” folder displaying the content of the storage.

Example 4

sfsmount -H 192.168.56.1 -P 9521 -o sfssubfolder=/storage/volume01 -o sfsdriveletter=S

should display the content of the subfolder "/storage/volume01" in the drive S.

Security/permissions related options

Option	Description
-o sfspassword=PASSWORD	authenticate to sfsmaster with password. (Raw password option)
-o sfsmd5pass=MD5	authenticate to sfsmaster using directly given md5 (only if sfspassword is not defined).(Password after MD5 processing).
-p | --password | -o askpassword	similar to '-o sfspassword=PASSWORD’ but show prompt and ask user for password. Password won’t be displayed while typing it.
-o sfsdonotrememberpassword	do not remember password in memory - more secure, but when session is lost then new session is created without password.
--uid UID | -o sfsuid=UID	set user id of the mounting user as UID (default behavior uses WinFSP local mapping of Windows SID).
--gid GID | -o sfsgid=GID	set group id of the mounting user as GID (default behavior uses WinFSP "No group" mapping).
-o sfsumaskfile=MASK	set permissions for newly created file (octal) (default: 002). This option represents the unset file permission bits. So, for the default setting the resulting file permission mask is 775.
-o sfsumaskdir=MASK	set permissions for newly created folder (octal) (default: 002). This option is very much like sfsumaskfile option one.
-o sfsallowedusers=UID1:UID2:...:UIDk	treat users provided as regular local users (default: none). This option hacks some inner client workarounds to make it able to support specific opertions.

Passwords can be set on the master side to provide layers of security to some specific paths of the storage, the first four options of this group provide the users the tools to fulfill those security requirements.

Current Windows Client does not support Active Directory and cannot provide a true translation from the Windows context of users (client side) to the Linux context of users (master side). The sfsuid and sfsgid options provide manual translation. Thus, the command

sfsmount -H 192.168.56.1 -P 9521 -D S -o sfsuid=999 -o sfsgid=999 -o sfsumaskfile=111 -o sfsumaskdir=023

will mount the regular drive and all actions in the storage will be performed with the security clearance of the user with uid 999 and gid 999, the default permission mask of the new created files will be 666, which means full permissions to every user except execution ones and the default permission mask of the new created directories will be 754, which means full permissions to creator of the directory, no write permission for other users sharing group ID and no execution and write permissions for other users. Default behavior of the sfsuid and sfsgid options uses WinFSP local mappings of the Windows SID. It means that if this option is not set some weird values will be seen. For instance, local users are mapped to UIDs higher than 3*2^16, Administrator user gets mapped to 544, System to 18 and the "No Group" is represented with GID 197121.

Read related options

Option	Description
-o cacheexpirationtime=MSEC	set timeout for read cache entries to be considered valid in milliseconds (0 disables cache) (default: 1000).
-o readaheadmaxwindowsize=KB	set max value of readahead window per single descriptor in kibibytes (default: 65536).
-o readcachemaxsizepercentage=P	specifies the maximum percentage of system memory for the read cache (default: 60).
-o readworkers=N	define number of read workers (default: 30).
-o maxreadaheadrequests=N	define number of readahead requests per inode (default: 5).
-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 sfsprefetchxorstripes	prefetch full xor stripe on every first read of a xor chunk.
-o bandwidthoveruse=N	define ratio of allowed bandwidth overuse when fetching data (default: 1.00).

The first four of the previous options configure the readahead mechanism of the client. This mechanism improves the client performance on read operations, especially on the sequential read operations. Default values should work for most cases, but can be tuned.

The cacheexpirationtime option could be increased if the reliability of a read of the files is high, i.e., the files are not supposed to change shortly after a read. The read cache is kept in memory, so keep track of the used RAM by the client and reduce the cacheexpirationtime if necessary. The readcachemaxsize option enforces a hard limit on the amount of data that can be cached when reading, specifying the percentage of the total memory capacity of the system to be used for this purpose. The readworkers option configures the number of workers (threads) the client creates to read files, so depending on the number of files read at the same time this number can go up or down. The maxreadaheadrequests option configures how far the readahead mechanism should go when reading a file, so depending on the expected kind of reads the client is supposed to do this number can go up (sequential reads) or down (sparse reads). Please consider leaving default parameters if desired performance is achieved or there is little data about the type of reads the client is going to do.

There is not much to add on the timeout options than to explain the meaning of "read operation" and "wave of read operation". A read operation is the procedure to get the data of a specific chunk, so a read syscall or request to the client may consist of more than one read operation. Meanwhile, a read operation may consist of several waves, depending on the type of the chunk (goal) and bandwidthoveruse parameter set. In this regard, a high bandwidthoveruse parameter would decrease the number of waves planned to perform the read, posibly increasing the number of chunkservers being read at the same time. The sfschunkserverconnectreadto refers to the timeout for the start of connection with a chunkserver at the begining of a read operation.

Example

sfsmount -H 192.168.56.1 -P 9521 -D S -o cacheexpirationtime=10000 -o readaheadmaxwindowsize=32768 -o readworkers=16 -o maxreadaheadrequests=16 -o sfschunkserverwavereadto=150 -o bandwidthoveruse=0.5

Previous command would start a regular mount on S:, with the parameters:

• the data read using the readahead mechanism would last 10s in cache.
• the maximum size of the window to be read ahead is 32MB.
• the number of read workers and maximum number of read requests in advance (readahead mechanism) is set to 16.
• the timeout for each wave is 150ms.
• it is intended to use at most 50% extra of the expected bandwidth in each read operation.

Write related options

Option	Description
-o sfschunkserverwriteto=MSEC	set chunkserver response timeout during write operation in milliseconds (default: 5000).
-o sfswritecachesize=N	define size of write cache in MiB (default: 50).
-o sfscacheperinodepercentage=P	define what part of the write cache non occupied by other inodes can a single inode occupy (in %, default: 25).
-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 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 (default: 0).

Much like the sfschunkserverconnectreadto option, the sfschunkserverwriteto sets the timeout for the connection with a chunkserver at the start of a write operation. A write operation is analogous to a read operation: it is the sequence of pending updates of data inside the same chunk. The write requests are always stored in memory and processed by a pool of threads, the size of this buffer is determined by the sfswritecachesize parameter and the number of threads in the processing pool is determined by sfswriteworkers option. The sfscacheperinodepercentage option caps the amount of data regarding a single file which can be in the write buffer at a time. The sfswritewindowsize is the number of blocks each write worker will try to process at the same time.

The sfsignoreflush option disables the flush syscall, which is typically invoked at the end of a write sequence to ensure that data is successfully written to disk. By disabling this syscall, the additional layer of confirmation is removed. However, this may cause certain file copying applications, which normally copy files sequentially, to instead perform these operations in parallel behind the scenes.

Example

sfsmount -H 192.168.56.1 -P 9521 -D S -o sfschunkserverwriteto=3000 -o sfswritecachesize=1024 -o sfscacheperinodepercentage=100 -o sfswriteworkers=30 -o sfsignoreflush=1

Previous command would start a regular mount on S:, with the parameters:

• the timeout for the connection with the chunkservers during writes is set to 3s.
• the size of the write buffer is 1GB.
• the write operations on any file could take over the whole write buffer.
• the number of write workers is set to 30.
• the flushes are ignored.

Persistent mount options

Option	Description
-o sfsschedulestartmount=ID	mount the filesystem and schedule automount shortly after next boot. ID only refers to some identifier for the scheduled mount, for instance: Project1.
-o sfsstartscheduledmount=ID	start a scheduled mount with the given ID.
-o sfsstopscheduledmount=ID	stop the actual instance of the scheduled mount with the given ID.
-o sfsdeletescheduledmount=ID	delete/deschedule the scheduled mount with the given ID.
-o sfslistscheduledmounts	display ID, state, and original command line for scheduled mounts.

The persistent mount options allow client users to schedule automatic mount of the client shortly after the boot of the Windows system is finished (around a minute). It also allows to start, stop and delete/deschedule those configured mounts.

Current implementation requires running the commands using the first four of the previous options to use an elevated (Admin) prompt. Those options use the Windows OS task scheduler and require that number of permissions. Commands which do not involve those options can be run from regular prompt and must be run from regular prompt if it is intended to mount a drive for the current user. The options:

• sfsstartscheduledmount
• sfsstopscheduledmount
• sfsdeletescheduledmount
• sfslistscheduledmounts

will ignore all other options provided in the command line, so it is recommended to only use that option.

Example 1

Command

sfsmount -o sfsschedulestartmount=ProjectS -H 192.168.56.1 -P 9521 -D S -o sfsuncpath=storage/ProjectS

on elevated prompt will mount the drive with the provided options (like in the previous example) and schedule to mount the same drive after boot. If that command is run on regular prompt will receive permission denied error.

Example 2

sfsmount -H 192.168.56.1 -P 9521 -D S -o sfsuncpath=storage/ProjectS

on elevated prompt appear to successfully mount the client but won’t show the drive. If that command is run on regular prompt, it will get the already described effect.

Example 3

sfsmount -o sfsstopscheduledmount=ProjectS

will stop the already running mount.

Example 4

sfsmount -o sfslistscheduledmounts

if following the previous commands should show following:

Configuration file option

-c CFGFILE	-o sfscfgfile=CFGFILE	load some mount options from external file.

Example

sfsmount -c C:\\ProjectS.cfg

loads mount options from that file, if exists, and mounts the client using those options. Example configuration file:

The resulting mount of this example config file will be the same as shown in the Example 2 under section "Extended general options" shown as example.

Further examples

These last examples are present to show some other ways to write arguments for the mount command line. The following commands are equivalent (note it is a merge of some of the previous commands):

sfsmount -H 192.168.56.1 -P 9521 -D S -S /data/ProjectS -o cacheexpirationtime=10000 -o readaheadmaxwindowsize=32768 -o readworkers=16 -o maxreadaheadrequests=16 -o sfschunkserverwavereadto=150 -o bandwidthoveruse=0.5 --uid 999 --gid 999 -o sfsumaskfile=111 -o sfsumaskdir=023

sfsmount -H 192.168.56.1 -P 9521 -D S -S /data/ProjectS -o cacheexpirationtime=10000,readaheadmaxwindowsize=32768,readworkers=16 -o maxreadaheadrequests=16,sfschunkserverwavereadto=150 -obandwidthoveruse=0.5 --uid 999 --gid 999 -o sfsumaskfile=111,sfsumaskdir=023

sfsmount -H 192.168.56.1 -P 9521 -D S -S /data/ProjectS -o CacheExpirationTime=10000 -o ReadaheadMaxWindowSize=32768 -o ReadWorkers=16 -o MaxReadaheadRequests=16 -o SFSChunkserverWaveReadTO=150 -o BandwidthOveruse=0.5 --UiD 999 --gId 999 -o SfSuMaSkFiLe=111 -o sfsumaskdir=023

sfsmount -H 192.168.56.1 -P 9521 -D S -S /data/ProjectS -o CacheExpirationTime=10000 -o ReadaheadMaxWindowSize=32768,ReadWorkers=16,MaxReadaheadRequests=16 -o SFSChunkserverWaveReadTO=150,BandwidthOveruse=0.5 --UiD 999 --gId 999 -o SfSuMaSkFiLe=111 -osfsumaskdir=023

In other words, the "-o" particle could be disposed and replaced by a comma, and the arguments that should be preceded by it can be joined. Also, the space in between the "-o" and the option itself could be removed, if the option is not a sequence of options comma separated. The names of the options can be written using any case, note it does not apply to:

• keywords ("-H", "-P", "-D")
• the "-o" particle
• the parameters ("/data/ProjectS")

Both of these advanced manners to write options cann be merged, such as the last example. Any command line that does not suffice the expected pattern will display an error message with the wrong/misspelled option, and prevent the mount start.

Side note

The descriptions of previous options contain some italic and non-italic words. The italic description appears on the help command response

sfsmount -–help

The rest of the description has been added especially for the documentation. The command

sfsmount -V

displays the version info.

SFSMount Manager

SFSMount Manager is a command line application that is used for monitoring latest statuses from Windows client instances on the same Windows machine environment.

This tool provides as main functionalities listing and disconnecting current Windows client instances with some additional options.

When executing complete SaunaFS installation on Windows OS, this binary is also added as part of it.

Usage

Option	Description
--list	List client instances with current statuses.
--help	Show help information.
--disconnect <ID>	Disconnect a specific client instance identified by <ID>.
--disconnect --all	Disconnect all client instances.
--disconnect --invalid	Disconnect invalid client instances (clients not connected to a master server).

These are current possible actions that can be performed by the SFSMount Manager. All of these options request info from status files generated by Windows client instances. These files contains following info:

• MOUNTID: The clients mount point identifier, which has format <drive>:<mountpoint>.

• PID: Denotes the process id associated with the client process. It is used for stopping client when needed.

• MDS_ON: Has value 'YES' if metadata server associated to client is connected, 'NO' otherwise.

• MDS: Metadata server ip address.

• SCHEDULED: Has value 'YES' if client process is scheduled, 'NO' otherwise.

• MOUNTPOINT: Represents client's mountpoint path.

• TIME: To represent time elapsed in milliseconds since the epoch .

• STATUS: This value can be of four different forms:

  • INVALID: When client is running but no master server is connected to it.
  • SCHEDULED: Client has been scheduled
  • DISCONNECTED: Client has been disconnected more than 5 seconds since last time its status was updated on its corresponding status file.
  • WORKING: When client is running and none of above cases happend.

Example 1

.\sfsmount.exe -H 192.168.43.180 -D S 

.\sfsmount.exe -H 192.168.43.180 -D T

After mounting two separate client instances we can list them and receive the corresponding info associated with them:

Example 2

If we try to disconnect a client process by ID and considering there were the same two instances from last example running, then the result should be:

Example 3

It also possible to disconnect all current client processes and considering there is the same instance from last example running, then the result should be:

FAQs

Why can't AJA see my S: drive, only C:?

AJA only recognizes drives mounted as network drives. To ensure AJA can see your drives, you should mount them using the -o sfsuncpath=PATH option. For example, use -o sfsuncpath=server/drive to mount your drive as a network drive. Note that AJA does not recognize drives mounted as regular drives from the SYSTEM user.

Why the client is failing to mount some subfolder of the storage?

When using sfssubfolder option, it needs to be guaranteed that the subfolder represents a valid namespace, i.e, the folder exists.

Otherwise the client will not be able to export the folder. Additionally, the permissions for the folder need to match the sfsuid used to start the client.

Summarizing, before exporting a subfolder, the following steps should verified:

1. The subfolder exists, otherwise it needs to be created.
2. Assign correct permissions to the user UID (default 1000) provided (parameter sfsuid=UID) that will write/read the folder, i.e., update folder permissions using chown UID.
3. Start the Windows Client.

Windows Client can also be used to create new subfolders by following the steps below:

1. Start the Windows Client using options sfsuid=UID and sfsgid=GID to mount the root folder ("/") or an ancestor folder containing the path where the new subfolder will be created. For instance, to create folder "/storage/volume01", the client can mount "/storage" subfolder.
2. Create the desired new folder, for example, "/storage/volume01".
3. Stop the client and start it using option sfssubfolder=/storage/volume01.

Note: This works if the ancestor folder, i.e., "/storage" folder has write permissions for other group.

Why my IIS server is not able to load the data from storage?

The IIS server performs its queries for data through the Windows Client with their very own specific user. Until now, that user has been translated to the uid 17. To confirm this, please check the output of the ".oplog" hidden file (type .oplog at the root of the filesystem) while trying to load the page. That user is from the range of users which are not local (less than 3*2^16) and is not treated like them, which most likely is the cause of the issue. In order to fix the issue, you should provide the sfsallowedusers=17 option (if IIS user is 17).