Skip to main content

MooseFS PRO only.

Usage

The Windows Client runs as a Windows service. The service starts with Windows and connects to the MooseFS Master Server. When the connection succeeds, the cluster appears in the system under the drive letter chosen at installation. This page covers the tasks of running the client: the service, its log, the registry parameters, the mount mode, and the handling of permissions that the cluster cannot map.

All configuration parameters of the client are stored in the Windows registry. MooseFS is a POSIX file system, so two consequences apply to every task below:

  • Every call carries a user ID and a group ID, so Windows identities are mapped to POSIX identities. The mapping mode is chosen at installation and changed in the registry.
  • Permissions follow the traditional POSIX permission model for objects, which is much less flexible than Windows ACLs. Permissions mapping lists what maps between Windows and POSIX and what does not.

The client supports the Windows attributes Archive, Hidden, System, and Read-only. Other Windows ACL attributes are not supported, because the POSIX permission model that the cluster stores cannot express them (permissions mapping).

The service starts, stops, and restarts from Services​

The client is managed like any Windows service, from the Services console. Open it with Win+R and services.msc, or press the Win key and type Services in the Start Menu. The console needs administrative rights: right-click the Services icon and select Run as Administrator. The service is listed as MooseFS Pro Windows Client.

A restart is visible in the system: the drive letter appears again once the service reconnects. The Event Log records a new Mounted.

The client logs to the Windows Event Log​

The service shows no prompts or dialogs. The service records its activity in the Windows Event Log instead. Open the Event Log by typing Event Viewer in the Start Menu. Every entry from the client has the source MooseFS. A connection produces entries like these:

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

The registry key holds the configuration​

The service reads its configuration from the HKEY_LOCAL_MACHINE\SOFTWARE\MooseFS registry key, where the values are stored when the driver is installed as a service. To change them, run regedit.exe with appropriate permissions. A user outside the Administrators group cannot read the entries of this key.

.params in the root of the mounted drive shows the parameters that a connection actually uses, under the same names (Windows Client troubleshooting).

The basic parameters name the cluster and the mount​

Every parameter in this section is a string value.

  • MASTER_HOST
    MooseFS Master Server address

  • MASTER_PORT
    MooseFS Master Server port (default: 9421)

  • MASTER_BIND
    Local address that the client connects from, on a machine that has more than one address

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

  • MASTER_MD5_PASSWORD
    The same password given as its MD5 digest, 32 hexadecimal digits, instead of clear text

  • MASTER_PATH
    MooseFS subdirectory mounted as the root of the drive (default: /, the root of the whole cluster)

  • MOUNT_POINT
    Drive letter at which the cluster is mounted, colon included, for example M:

  • PREFERRED_LABELS
    Ordered list of label expressions, most preferred first. The Chunkservers that match those expressions are placed at the front of every list of Chunkservers that the Master Server gives this client, for reads and writes alike (preferred labels)

The I/O parameters set the caches, the read-ahead, and the retries​

Every parameter in this section is a dword value. A value of -1 means that the parameter is not set. The client then leaves the parameter out of the configuration that it passes to the Master Server when it connects. The built-in default named below applies. Among the string values above, an empty string has the same meaning.

  • READ_CACHE_MB
    Size of the read cache that the client keeps, in MiB (default: 128)

  • WRITE_CACHE_MB
    Size of the write cache that the client keeps, in MiB (default: 128)

  • READAHEAD_LENG
    Size of the window read past the current position, in bytes (default: 2 MiB) (client cache and read-ahead)

  • READAHEAD_TRIGGER
    Number of bytes read sequentially before the client starts reading ahead (default: 20 MiB)

  • IO_TRY_CNT
    Number of attempts that an I/O operation gets before it fails (default: 30) (client and mount problems)

  • IO_TIMEOUT
    Time limit of one I/O operation, in seconds (default: 0). 0 sets no limit, so only IO_TRY_CNT ends the operation

  • ERROR_ON_LOST_CHUNK
    When this parameter is set to 1, an operation on a chunk with no valid copy left fails immediately instead of being retried (default: 0)

  • ERROR_ON_NO_SPACE
    When this parameter is set to 1, an operation that finds no space left fails immediately instead of being retried (default: 0)

  • MIN_LOG_ENTRY
    Number of attempts that a failing data operation reaches before the client records it in the Event Log (default: 5)

UID2SID switches the mapping strategy​

UID2SID selects how Windows users map to POSIX identities and accepts two values: STATIC and LDAP.

With UID2SID = STATIC, each call to MooseFS always passes the same uid and gid, whatever Windows user performs the operation. The pair is read from two dword values:

  • STATIC_UID
    Static user ID, dword type

  • STATIC_GID
    Static group ID, dword type

Configuration example for static UID to SID mapping. Save it as a .reg file and import it with regedit.exe to set all the keys at once:

Windows Registry Editor Version 5.00

[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

With UID2SID = LDAP, the identities come from Active Directory. On a machine that has already joined an Active Directory domain, all the LDAP values can stay empty. The mapping then uses the domain of the machine and the credentials of the logged-in user. The LDAP values:

  • LDAP_HOST
    AD/LDAP IP or host name

  • LDAP_PORT
    AD/LDAP port number

  • LDAP_BASE_DN
    Base DN for connections, for example 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:

Windows Registry Editor Version 5.00

[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"="dc=mfs,dc=lan"
"LDAP_USER_DN"="Administrator"
"LDAP_USER_PASS"="adminpassword"

The client asks Active Directory for the POSIX identity​

MooseFS is a POSIX-compliant, Linux-based system and stores all security information in the same way as other systems of this kind. Windows users and groups, identified by SIDs, have no direct correspondence to MooseFS users and groups, identified by UIDs and GIDs. In LDAP mode the client reads the mapping from the directory:

  • The client runs the user query the first time that the user accesses MooseFS.
  • The query is cached. The client runs the query again the next time that the user accesses MooseFS after enough time has passed (currently one hour).
  • The client searches Active Directory for a record of type user with the corresponding objectSid. From that record, the client reads the attribute uidNumber, and possibly gidNumber. However, gidNumber should rather be assigned to groups.
  • For all groups that the user is a member of (member attributes in groups) and for the primaryGroupID, the client reads the gidNumber attributes.
  • If uidNumber and gidNumber can be read, the client uses these values for access.
  • If uidNumber or gidNumber is missing, or the user record is not in Active Directory, all operations end with permission denied.
  • The client makes no exception for system accounts, such as the LocalSystem account S-1-5-18. System accounts are not in Active Directory, so their access is denied, as for any unmapped user.

uidNumber and gidNumber are standard attributes of the LDAP structure for mapping users to Unix-like IDs. Windows Server 2008 and later has both attributes predefined, so no Active Directory schema change is required. Microsoft describes them in the Active Directory schema reference, under the uidNumber attribute and the gidNumber attribute.

The drive mounts as a network resource or as a local disk​

By default, the client mounts the drive as a network resource. One registry parameter changes that:

  • NETWORK_DRIVE
    Defines whether the drive is mounted as a network resource or as a local disk. When NETWORK_DRIVE is set to 0, the client mounts the drive as a local disk.

The active mode is visible in two places. An entry recorded in the Event Log during mounting names the selected mode and confirms that the registry change was applied. File Explorer shows the mode too. The drive label is the quicker of the two to check: a drive mounted as a network resource has the default name Network Drive.

Configuration example for mounting as a local disk:

Windows Registry Editor Version 5.00

[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

Unmappable permissions can be ignored instead of refused​

  • IGNORE_UNSUPPORTED_PERMISSIONS
    Defines how the client handles errors of user and group mapping and of permission modification during setsecurity operations.

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

  • An owner change whose user SID cannot be mapped to a UID, for example because no corresponding LDAP record exists, is ignored. The client returns no EINVAL. The remaining permission changes are still applied. When nothing else was requested, the operation returns OK. A group change behaves the same way.
  • Permissions assigned to a user that cannot be mapped to a UID are ignored, as if they were not provided. With the parameter disabled, they end the operation with an immediate error.
  • Permissions assigned to a user or group that does map to a UID, but is neither the file owner, nor the file group, nor the special identity ALL, are ignored as well. The client reports no error.
  • For the owner, the group, and ALL, any attempt to set permissions of a type other than ALLOW is ignored, without an error.

The change is visible in the result: an operation that previously ended with EINVAL completes without an error.