Skip to main content

Usage

The MooseFS Windows® Client is installed as a Windows® service. It starts upon Windows® startup and it tries to connect to the MooseFS Master Server. If it succeeds, a new drive letter appears in the system.

All client configuration parameters are stored in the Windows® registry.

Due to POSIX compliance of MooseFS file system, a few aspects need to be taken into account:

  • User ID and group ID need to be mapped between Windows® and POSIX filsesystem and vice versa.
  • The driver supports a traditional POSIX file system object permission model. Those permissions are much less flexible than Windows® ACL.

MooseFS Windows® Client supports following Windows® attributes:

  • Archive
  • Hidden
  • System
  • Read-only

Other Windows® ACL attributes are not supported yet.

Managing the client’s service​

The MooseFS Windows® Client can be started, stopped and restarted from Windows® Services – core system component. To start Services management tool, press the Win+R shortcut, type services.msc or press the Win key to open Start Menu and type Services. Appropriate administrative rights are needed to run the tool, so right click on the Services icon app and select the Run as Administrator option. Then you should be able to find the MooseFS Windows Client service on the list.

MooseFS logs in Windows® Event Log​

The service does not show any prompts or dialogs. It logs its activity in Windows® Event Log. Event Log can be opened by typing Event Viewer in the Windows® start menu. The source of all logs From MooseFS Windows® Client is called MooseFS

Below you can see an example of how Event Log looks like:

Level		Date and Time		Source	Event ID	Task Category 	Log body
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=Mounted
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=Windows client is allowed
Warning		12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=time desync between client and master is higher than a second - it might lead to strange atime/mtime behaviour - consider time synchronization in your moosefs cluster
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=mfsmaster accepted connection with parameters: read-write,restricted_ip,admin ; root mapped to 0:0
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=mfsmaster 192.168.100.10 - found leader: 192.168.100.11
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=Using dc=mfs,dc=lan for LDAP queries
Information	12.12.2022 14:14:56	MooseFS	1		None		Module=MooseFS Message=Connected to LDAP server

Windows® registry key​

The service can be reconfigured after installation using a number of keys in the Windows® Registry. To affect the configuration of MooseFS, run regedit.exe with appropriate permissions.

Note: A user, which is not a member of Administrators group, cannot read entries in the MooseFS registry key.

Values are stored in the HKEY_LOCAL_MACHINE\SOFTWARE\MooseFS registry key when the driver is installed as a service.

Basic parameters​

  • MASTER_HOST
    MooseFS Master Server address

  • MASTER_PORT
    MooseFS Master Server port (default: 9421)

  • MASTER_PASSWORD
    Password needed to connect to the cluster (defined in mfsexports.cfg file on MooseFS Master Server)

Advanced UID2SID parameter​

This parameter allows to change the strategy of mapping UID and SID and there are two allowed values: STATIC and LDAP.

UID2SID = STATIC

This option requires two dword value variables: STATIC_UID and STATIC_GID.
In this setting, each call to MooseFS always passes the same uid and gid stored in the registry (regardless of which Windows® user performs the operation).

  • STATIC_UID
    Static user ID dword type

  • STATIC_GID
    Static group ID dword type

Configuration example for static UID to SID mapping:

[HKEY_LOCAL_MACHINE\SOFTWARE\MooseFS]
"READ_CACHE_MB"=dword:00000064
"MASTER_HOST"="mfsmaster.mfs.lan"
"MASTER_PORT"="9421"
"MOUNT_POINT"="M:"
"MASTER_PASSWORD"=""
"MASTER_PATH"="/"
"UID2SID"="STATIC"
"STATIC_UID"=dword:000003e9
"STATIC_GID"=dword:000003e9

UID2SID = LDAP

If your compuer already joined an Active Directory domain you can leave all the fields empty. The values will be mapped based on the domain name of the computer and logged in user credentials.

Available LDAP variables:

  • LDAP_HOST
    AD/LDAP IP or hostname

  • LDAP_PORT
    AD/LDAP port number

  • LDAP_BASE_DN
    Base DN for connections e.g. dc=mfs,dc=lan.

  • LDAP_USER_DN
    Name of the AD/LDAP user with the appropriate query permissions

  • LDAP_USER_PASS
    Password of the AD/LDAP user

Configuration example for LDAP UID to SID mapping:

[HKEY_LOCAL_MACHINE\SOFTWARE\MooseFS]
"READ_CACHE_MB"=dword:00000064
"MASTER_HOST"="mfsmaster.mfs.lan"
"MASTER_PORT"="9421"
"MOUNT_POINT"="M:"
"MASTER_PASSWORD"=""
"MASTER_PATH"="/"
"UID2SID"="LDAP"
"LDAP_HOST"="dc1.mfs.lan"
"LDAP_PORT"=dword:00000185
"LDAP_BASE_DN"="mfs.lan"
"LDAP_USER_DN"="Administrator"
"LDAP_USER_PASS"="adminpassword"

About LDAP mode​

As MooseFS is a POSIX compliant, Linux-based system, it stores all security information in a way characteristic for systems of this kind. There is no straightforward correspondence between Windows® users/groups (identified by SIDs) and MooseFS Unix-like users and group (identified by uids and gids).

How MooseFS Windows® Client cooperates with Active Directory:

  • The user query is executed the first time the user accesses MooseFS,
  • The query is cached and will be executed the next time the user accesses MooseFS if enough time has passed (currently one hour),
  • A record of type user with the corresponding objectSid is searched for in Active Directory. From such a record, the attribute uidNumber (and possibly gidNumber, although this should rather be assigned to groups) is fetched,
  • For all groups this user is a member of (member attributes in groups) and for the primaryGroupID, the gidNumber attributes are fetched,
  • If uidNumber and gidNumber can be read, these values are used for access,
  • If uidNumber or gidNumber is missing or the user record is not in Active Directory, all operations end with permission denied,
  • Currently the client does not make an exception for system accounts (e.g. LocalSystem account S-1-5-18). They are not in Active Directory, so access will be denied.

There are special attributes like uidNumber and gidNumber in the LDAP structure for mapping users to Unix-like IDs. Microsoft® Windows® Server 2008 and later has both attributes predefined thus no Active Directory Schema change is required. For more information, refer to:

Mounting as a local disk​

By default, the MooseFS Windows® Client mounts the drive as a network resource.

To make it appear as a local disk, add the following registry parameter:

  • NETWORK_DRIVE
    Defines whether the drive should be mounted as a network or local disk.

When this parameter is set to 0, the MooseFS Windows® Client mounts the drive as a local disk. An entry is recorded in the Event Logs during mounting, indicating the selected mode, which allows verification that the registry change was applied correctly. The difference is also visible in File Explorer, where the drive is displayed differently depending on the selected mode.

Configuration example for mounting as a local disk:

[HKEY_LOCAL_MACHINE\SOFTWARE\MooseFS]
"READ_CACHE_MB"=dword:00000064
"MASTER_HOST"="mfsmaster.mfs.lan"
"MASTER_PORT"="9421"
"MOUNT_POINT"="M:"
"MASTER_PASSWORD"=""
"MASTER_PATH"="/"
"NETWORK_DRIVE"=dword:0

Permission error handling​

  • IGNORE_UNSUPPORTED_PERMISSIONS
    Defines how the Windows Client handles errors related to user/group mapping and permission modification during setsecurity operations.

When this parameter is set to 1, the client silently ignores unsupported or unmappable permissions instead of returning errors such as EINVAL.

With IGNORE_UNSUPPORTED_PERMISSIONS enabled:

Changing Owner and Group​

If an attempt is made to change the owner of a file and the provided user SID cannot be mapped to a UID (for example, because no corresponding LDAP record exists), then:

  • the owner change is ignored,

  • no EINVAL error is returned,

  • processing continues to allow other permission changes to be applied,

  • if no other modifications are needed, the operation returns OK.

  • The same behavior applies when attempting to change the group of a file.

Changing Permissions (ACL)​

If permissions are assigned to a user that cannot be mapped to a UID,
those permissions are ignored (treated as if they were not provided).
Normally this would result in an immediate error, but with this parameter enabled, no error is returned.

If permissions are assigned to a user or group that can be mapped to a UID, but is not:

  • the file owner,
  • the file group, or
  • the special identity ALL,
    those permissions are also ignored, and no error is reported.

When modifying permissions for the owner, group, or ALL, any attempt to set permissions other than ALLOW is ignored, without returning an error.