Windows NFS 4.2 FileSystem Client Instructions

Table of Contents

What is this ?
Features
Requirements
Installation
Download and install Cygwin (if not installed yet)
Download and install MSYS2/64bit [OPTIONAL]
Download "ms-nfs41-client" installation tarball
Installation (as "Administrator")
Deinstallation
Usage
Preparing the NFS server
Starting the NFS client daemon
Mounting and using NFS filesystems
Notes
Known issues
Troubleshooting && finding bugs/debugging
Development
Source code
Building ms-nfs41-client
Mailing list

What is this ?

NFSv4.2/NFSv4.1 filesystem driver for Windows 10/11 & Windows Server 2019+2022+2025

Features

  • Full NFSv4.2/NFSv4.1 protocol support

  • idmapper (mapping usernames and uid/gid values between server and client)

  • Support for custom ports (NFSv4 defaults to TCP port 2049, this client can use different ports per mount)

  • Support for nfs://-URLs

  • Support ssh forwarding, e.g., mounting NFSv4 filesystems via ssh tunnel

  • Support for long paths (up to 4096 bytes), no Windows MAXPATH limit

  • Unicode and GB 18030 support for filenames

    • Unicode and GB 18030 support for file-, directory- and streamnames, including Unicode codepoints above the Basic Multilingual Plane, assuming the filesystem exported by the NFS server supports the matching Unicode codepoints.

    • nfs://-URLs can be used to mount filesystems with non-ASCII characters in the mount path, independent of current locale.

  • UNC paths

    • Mounting UNC paths without DOS drive letter

    • IPv6 support in UNC paths

    • /sbin/nfs_mount prints UNC paths in Win32+Cygwin/MSYS2 formats

    • Cygwin/MSYS2 bash+ksh93 support UNC paths, e.g., cd //derfwnb4966@NFS@2049/bigdisk/mysqldb4/

    • Symlinks on NFS can redirect to other filesystems via UNC syntax and work with Cygwin, MSYS2, cmd.exe, powershell, Microsoft CoreUtils, uutils CoreUtils etc., e.g.: 

      mklink /D symlnk1_to_h_tmp \\lab17@NFS@2049\export\home\rsm\tmp

  • WSL support

    • Mount Windows NFSv4.2 shares via drive letter or UNC path in WSL via mount -t drvfs

    • Supports NFS owner/group to WSL uid/gid mapping

  • IPv6 support

    • IPv6 address within '[', ']' (will be converted to *.ipv6-literal.net)

  • Windows ACLs <---> NFSv4 ACL translation

    • Win32 C:\Windows\system32\icacls.exe

    • Cygwin /usr/bin/setfacl+/usr/bin/getfacl

    • Windows Explorer ACL dialog

  • Sparse file support

    • Requires NFSv4.2 server which supports the NFSv4.2 operations "ALLOCATE", "DEALLOCATE", "SEEK", and the |FATTR4_WORD1_SPACE_USED| attribute.

    • Full Win32 sparse file API support, including creation, punching holes, enumeration of hole&data ranges etc.

    • Supports Win32 APIs |FSCTL_QUERY_ALLOCATED_RANGES|, |FSCTL_SET_SPARSE|, |FSCTL_SET_ZERO_DATA|; and |NfsV3Attributes.used| EA

    • Cygwin sparse file support requires >= Cygwin 3.6 to support POSIX-1.2024 |lseek(...,SEEK_HOLE/SEEK_DATA,...)|, which is needed for Cygwin/MSYS2 coreutils /usr/bin/fallocate and $ /usr/bin/cp --sparse=auto src dest #

    • /cygdrive/c/Windows/system32/fsutil sparse queryrange myfile.dat can be used to enumerate ranges where data are allocated

    • /cygdrive/c/Windows/system32/xcopy /sparse can be used to copy sparse files+sparse named streams. Requires on Win11 >= 22H2 because it relies on |CopyFile2()| flag |COPY_FILE_ENABLE_SPARSE_COPY|.

  • Windows "named streams"/Alternate Data Stream support

    • Supports Win32 APIs |FileStreamInformation|

    • Supports sparse streams (e.g. supports Win32 APIs |FSCTL_QUERY_ALLOCATED_RANGES|, |FSCTL_SET_SPARSE|, |FSCTL_SET_ZERO_DATA| etc. on Win32 named streams)

    • Supports Win32 named streams on directories.

    • Requires NFSv4.1 server which supports the NFSv4.1 named attributes.

  • Case-insensitive filesystem support

    • Requires NFSv4.1 server which supports the |FATTR4_WORD0_CASE_INSENSITIVE| attribute set to TRUE (currently Windows Server NFSv4.1 server exporting NTFS).

  • Data copy offload (server-side copy)

    • Implemented via Win32 |FSCTL_OFFLOAD_READ|+|FSCTL_OFFLOAD_WRITE| to copy data blocks directly on the server.

    • Requires NFSv4.2 server which supports the NFSv4.2 operations "COPY", "DEALLOCATE", "SEEK"

    • Sparse files+sparse Win32 named streams are correctly copied including all hole and data ranges

    • Windows 10 |CopyFile2()| API uses |FSCTL_OFFLOAD_READ|+|FSCTL_OFFLOAD_WRITE| by default

    • Windows 10 tools like xcopy.exe (on Windows 11 requires /NOCLONE, otherwise block cloning is the default), robocopy etc. all use |CopyFile2()|, and therefore server-side copies by default

  • Block cloning support

    • Implemented via Win32 |FSCTL_DUPLICATE_EXTENTS_TO_FILE| to clone file blocks from src to dst within the same filesystem.

    • Requires NFSv4.2 server which supports the NFSv4.2 operations "CLONE", "DEALLOCATE", "SEEK", and exports a filesystem which supports block cloning (e.g. Linux BTRFS+XFS, but NOT Linux tmpfs)

    • Sparse files+sparse Win32 named streams are correctly cloned, including all hole and data ranges

    • /usr/bin/winclonefile.exe can be used to clone a file

    • Windows 11 |CopyFile2()| API uses |FSCTL_DUPLICATE_EXTENTS_TO_FILE| by default

    • Windows 11 tools like xcopy.exe, robocopy etc. all use |CopyFile2()|, and therefore file cloning by default

  • Symlink reparse and translation support

    • Translates Win32/NT symlink syntax (e.g. $ mklink /D ... Y:\tmp\ #) to NFS/POSIX syntax (e.g. "/cygdrive/y/tmp/") and back

    • Translates Cygwin /cygdrive/<devletter> symlinks on NFS to Win32 <devletter>:\ and back

    • Pass-through for NFS /dev-Symlinks (e.g. /dev/null) to Cygwin

    • Interoperability for symlinks between Cygwin, cmd.exe, powershell, Microsoft CoreUtils, uutils CoreUtils, and other POSIX-compatible NFSv4.2/NFSv4.1 clients.

  • Support for NFSv4 public mounts (i.e., use the NFSv4 public file handle lookup protocol via $ nfs_mount -o public ... relative-path-or-url#)

  • Support for NFSv4 referrals

  • SFU/Cygwin/MSYS2 support, including:

    • POSIX uid/gid+mode

    • Backwards compatibility to Microsoft's NFSv3 driver

    • Cygwin ACLs, e.g., setfacl/getfacl

    • Cygwin/MSYS2 symlinks

  • Custom primary group support

    • Supports primary group changes in the calling process/thread (via |SetTokenInformation(..., TokenPrimaryGroup,...)|), e.g., if the calling process/threads switches the primary group in its access token then the NFSv4.2 client will use that group as GID for file creation.

    • newgrp(1)/sg(1)-style "winsg" utility to run cmd.exe with different primary group, e.g., $ winsg [-] -g group [-c command | /C command] #

  • Support for hosting filesystems (like OpenZFS) as (sparse) files

  • Software compatibility:

    • Any NFSv4.2/NFSv4.1 server (Linux, Solaris, Illumos, FreeBSD, nfs4j, NFS Ganesha, …)

    • All tools from Cygwin/MSYS2/MinGW

    • Microsoft CoreUtils

    • uutils CoreUtils

    • Visual Studio (tested: VS2019 Community, VS2022 Community, VS2026 Community Insiders)

    • OpenZFS - Supports ZFS pools stored as NFS (sparse) files, hosting...

      • ZFS filesystems
      • ZFS ZVOLS (ZFS virtual disk drives), which can then be used for...
        • filesystems like NTFS, ReFS, FAT, ...
        • hosting disks for Hyper/V VMs, VMware VMs, ...

    • VMware Workstation (can use VMs hosted on NFSv4.2/NFSv4.1 filesystem)

    • MariaDB (including sparse file support for page compression)

    • Windows IIS FTP server

    • Microsoft Office (tested: Office 2016)

    • Windows 16bit DOS and Windows 3.x applications via NT Virtual DOS Machine (requires case-insensitive filesystem), e.g. Borland Turbo C compiler, Total Commander for Windows 3.x, DOSNIX, DOS 16bit zip, …

    • …

Requirements

  • Operarting system:

    (Requires NTFS, ReFS or WinBTRFS for System Volume (C:); the installer requires hardlink support, which FAT does not support)

  • Cygwin:

    • Cygwin versions:

      • 64bit: >= 3.5.7, recommended >= 3.6.1

      • 32bit: >= 3.3.6

    • Packages (required): cygwin, cygrunsrv, cygutils, cygutils-extra, libiconv, libiconv2, procps-ng, util-linux, p7zip

    • Packages (optional, recommended, required to build ms-nfs41-client): bison, cygport, cygwin-devel, clang, dos2unix, pax, pbzip2, libnfs-utils (for /usr/bin/nfs-ls), libiconv-devel, make, bmake, git, gcc-core, gcc-g++, gdb, mingw64-i686-clang, mingw64-x86_64-clang, unzip, time, docbook-utils, docbook-xml45, docbook-xsl, docbook-xsl-ns, libxslt, w3m

    • Packages (only-CI):

      # required packages, but part of Cygwin default installation, listed here for CI package list ONLY

      bash, bzip2, coreutils, getent, grep, hostname, less, sed, tar, wget

  • MSYS2 (64bit, optional):

    • Packages (recommended): base-devel, gcc, clang, sed, time, coreutils, util-linux, p7zip, grep, sed, emacs, gdb, make, autoconf, automake, gettext, gettext-devel, git, subversion, flex, bison, unzip, pax, tar, libiconv-devel, ncurses-devel, gmp-devel, mpfr-devel, mpc-devel, isl-devel, procps-ng, libiconv-devel

Installation

Windows 32bit-vs.-64bit can be tested from Windows cmd.exe console:

Run this command:

echo %PROCESSOR_ARCHITECTURE%

If this returns "AMD64" then you have a Windows 64bit kernel, and if it returns "x86" then you have Windows 32bit kernel. If you get any other value then this is a (documentation) bug.

Cygwin 64bit can be installed like this:

Install Cygwin 64bit on Windows 64bit with packages required by "ms-nfs41-client" (Windows NFSv4.2 client):

  1. Create subdir

    mkdir download
cd download

  2. Get installer from https://cygwin.com/setup-x86_64.exe

    curl --remote-name "https://www.cygwin.com/setup-x86_64.exe"

  3. Run installer with these arguments:

    setup-x86_64.exe -q --site "https://mirrors.kernel.org/sourceware/cygwin" -P cygwin,cygwin-devel,cygrunsrv,cygutils,cygutils-extra,bash,bzip2,coreutils,getent,gdb,grep,hostname,less,libiconv,libiconv2,pax,pbzip2,procps-ng,sed,tar,time,util-linux,p7zip,wget,libnfs-utils,make,bmake,git,dos2unix,unzip

Cygwin 32bit can be installed like this:

Install Cygwin 32bit on Windows 32bit with packages required by "ms-nfs41-client" (Windows NFSv4.2 client):

  1. Create subdir

    mkdir download
cd download

  2. Get installer from https://www.cygwin.com/setup-x86.exe

    curl --remote-name "https://www.cygwin.com/setup-x86.exe"

  3. Run installer with these arguments:

    setup-x86.exe --allow-unsupported-windows -q --no-verify --site "http://ctm.crouchingtigerhiddenfruitbat.org/pub/cygwin/circa/2022/11/23/063457" -P cygwin,cygwin-devel,cygrunsrv,cygutils,cygutils-extra,bash,bzip2,coreutils,getent,gdb,grep,hostname,less,libiconv,libiconv2,pax,pbzip2,procps-ng,sed,tar,time,util-linux,p7zip,wget,libnfs-utils,make,git,dos2unix,unzip

  1. Download & install from Cygwin

    mkdir -p download && cd download
# ARM64: https://github.com/msys2/msys2-installer/releases/download/2025-08-30/msys2-arm64-20250830.exe
# x86_64: https://github.com/msys2/msys2-installer/releases/download/2025-08-30/msys2-x86_64-20250830.exe
wget 'https://github.com/msys2/msys2-installer/releases/download/2025-08-30/msys2-x86_64-20250830.exe'
chmod a+x 'msys2-x86_64-20250830.exe'
./msys2-x86_64-20250830 --default-answer --root 'C:\msys64' install

  2. Install extra packages:

    Start MSYS2 UCRT mintty and execute this:

    pacman -S --noconfirm base-devel gcc clang sed time coreutils util-linux p7zip grep sed emacs gdb make autoconf automake gettext gettext-devel git subversion flex bison unzip pax tar libiconv-devel ncurses-devel gmp-devel mpfr-devel mpc-devel isl-devel procps-ng libiconv-devel

Installing MSYS on NFS filesystem

NFS filesystem used as MSYS root filesystem (/) must be mounted as global filesystem (e.g. use nfs_globalmount.exe)

Known issues

  1. Edit /etc/pacman.conf and set 

    SigLevel = Never

    , because due to a Cygwin/MSYS2 bug there is a mismatch between Cygwin/MSYS2 POSIX uid/gid and Win32 owner/owner_group SIDs

  2. Permissions of the /tmp dir should be fixed: 

    chmod a+rwxt /tmp

(from a Cygwin terminal)

$ mkdir -p ~/download
$ cd ~/download
$ wget 'http://www.nrubsig.org/people/gisburn/work/msnfs41client/releases/testing/msnfs41client_cygwin_64bit32bit_binaries_20260801_13h39m_gita2eb45f.tar.bz2'
$ openssl sha256 "msnfs41client_cygwin_64bit32bit_binaries_20260801_13h39m_gita2eb45f.tar.bz2"
SHA2-256(msnfs41client_cygwin_64bit32bit_binaries_20260801_13h39m_gita2eb45f.tar.bz2)= caf406f0eb9c3fa0ccc0ea2c24d98d97abe84d00a33ac3b44c897f355153cf63
$ (cd / && tar -xf ~/download/msnfs41client_cygwin_64bit32bit_binaries_20260801_13h39m_gita2eb45f.tar.bz2 )
$ /sbin/msnfs41client install

# Configuring the idmapper:
# Copy idmapper default script to /etc/msnfs41client/cygwin_idmapper.ksh
# and then edit /etc/msnfs41client/cygwin_idmapper.ksh to
# replace the scripts default Windows domain ("GLOBAL.LOC")
# with your Windows domain and the scripts default NFS domain ("global.loc")
# with your default NFS domain
# Mappings for users and groups must be added if the account names
# on the Windows side do not match the account names on the NFS
# server side exactly.
cp /lib/msnfs41client/cygwin_idmapper.ksh /etc/msnfs41client/cygwin_idmapper.ksh
<REBOOT>
$ (set -o xtrace ; cd / && tar -tf ~/download/msnfs41client_cygwin_64bit32bit_binaries_20260801_13h39m_gita2eb45f.tar.bz2 | while read i ; do [[ -f "$i" ]] && rm "$i" ; done)
<REBOOT>

Usage

It is required that all Windows users and groups used by the Windows NFS client have user/group accounts on the server side.

If no central user&group management between NFS server and NFS clients exists the /sbin/cygwinaccount2nfs4account script can be used to manually create matching /etc/group and /etc/passwd entries on the NFS server side.

Run the NFSv4 client daemon manually:

$ /sbin/msnfs41client run_daemon

Mount a filesystem to drive N: and use it

$ /sbin/nfs_mount -o rw N 10.49.202.230:/net_tmpfs2
Successfully mounted '10.49.202.230@NFS@2049' to drive 'N:'
$ cd /cygdrive/n/
$ ls -la
total 4
drwxrwxrwt 5 Unix_User+0      Unix_Group+0      100 Dec  7 14:17 .
dr-xr-xr-x 1 roland_mainz     Kein                0 Dec 14 13:48 ..
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  80 Dec 12 16:24 10492030
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  60 Dec 13 17:58 directory_t
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  60 Dec  7 11:01 test2

Unmount filesystem:

$ cd ~ && /sbin/nfs_umount N:
# OR
$ cd ~
$ net use N: /delete

Mount a filesystem WITHOUT a dos drive assigned and use it via UNC path

$ /sbin/nfs_mount -o rw 10.49.202.230:/net_tmpfs2
Successfully mounted '10.49.202.230@NFS@2049' to drive '\\10.49.202.230@NFS@2049\net_tmpfs2'
$ cygpath -u '\\10.49.202.230@NFS@2049\net_tmpfs2'
//10.49.202.230@NFS@2049/net_tmpfs2
$ cd '//10.49.202.230@NFS@2049/net_tmpfs2'
$ ls -la
total 4
drwxrwxrwt 5 Unix_User+0      Unix_Group+0      100 Dec  7 14:17 .
dr-xr-xr-x 1 roland_mainz     Kein                0 Dec 14 13:48 ..
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  80 Dec 12 16:24 10492030
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  60 Dec 13 17:58 directory_t
drwxr-xr-x 3 Unix_User+197608 Unix_Group+197121  60 Dec  7 11:01 test2

Unmount filesystem:

$ cd ~ && /sbin/nfs_umount '\\10.49.202.230@NFS@2049\net_tmpfs2'
# OR
$ cd ~
$ net use '\\10.49.202.230@NFS@2049\net_tmpfs2' /delete

List mounted NFSv4.2 filesystems:

$ /sbin/nfs_mount

Mounts created by user "SYSTEM" are usable by all users in a system. Such mounts can be created by the /sbin/nfs_globalmount command, or adding an entry in /etc/fstab.msnfs41client.

Example usage for /etc/fstab.msnfs41client:

# Create a file /etc/fstab.msnfs41client, which list the mounts
# which should be mounted system-wide at boot
$ cat /etc/fstab.msnfs41client
nfs://[fe80::21b:1bff:fec3:7713]//bigdisk       N:       nfs     sec=sys,rw      0       0
# run "ms-nfs41-client-globalmountall-service", which runs
# /sbin/mountall_msnfs41client as user "SYSTEM" to read
# /etc/fstab.msnfs41client and mount the matching filesystems
sc start ms-nfs41-client-globalmountall-service

Example 1: Mount Windows NFSv4.2 share via Windows drive letter

Mount NFSv4.2 share in Windows to drive letter 'N':

$ /sbin/nfs_mount -o rw 'N' nfs://10.49.202.230//bigdisk
Successfully mounted '10.49.202.230@NFS@2049' to drive 'N:'

Within WSL mount drive letter 'N' to /mnt/n

$ sudo bash
$ mkdir /mnt/n
$ mount -t drvfs N: /mnt/n

Example 2: Mount Windows NFSv4.2 share via UNC path:

Mount NFSv4.2 share in Windows

$ /sbin/nfs_mount -o rw nfs://10.49.202.230//bigdisk
Successfully mounted '10.49.202.230@NFS@2049' to drive '\\10.49.202.230@NFS@2049\bigdisk'

Within WSL mount UNC path returned by /sbin/nfs_mount

$ sudo bash
$ mkdir /mnt/bigdisk
$ mount -t drvfs '\\10.49.202.230@NFS@2049\bigdisk' /mnt/bigdisk

Known issues with WSL:

Notes

Known issues

Troubleshooting && finding bugs/debugging

Development

Source code can be obtained from https://github.com/kofemann/ms-nfs41-client or as git bundle from /usr/src/msnfs41client/msnfs41client_git.bundle

Note

make installdest or make installdest64 can fail on SMB/NFSv4.1 filesystems with a "link.exe" crash. The workaround is to disable incremental linking before building, e.g., do:

cd ms-nfs41-client
sed -i -E 's/<LinkIncremental>true<\/LinkIncremental>/<LinkIncremental>false<\/LinkIncremental>/g' $(find build.vc19 -name \*.vcxproj)

This Visual Studio bug is tracked as https://developercommunity.visualstudio.com/t/Visual-Studio-link.exe-crashes-on-networ/10735424 ("Visual Studio link.exe crashes on network filesystem").

See tests/manual_testing.txt

Mailing list

Please direct any questions to (list archive)

#EOF.