# Windows NFS 4.1 Client Instructions

1. Building from Source
2. Installing Binaries
3. Ldap Configuration
4. Starting the Client
5. Mounting
6. Connectation
7. Known Issues

## 1. Building from Source

### Requirements

- Windows Vista, Windows Server 2008 R2, or Windows 7 (Windows XP and previous versions are not supported)
- Microsoft Visual Studio 2010
- Windows Driver Development Kit (WinDDK 6000 or later)
- ms-nfs41-client source code:
  `> git clone git://citi.umich.edu/projects/ms-nfs41-client.git`

### Building the rpc library and nfs client daemon

- WinDDK does not include the ldap library, so we build the rpc library and nfs client daemon with Visual Studio 2010.

1. Open Windows Explorer and navigate to ms-nfs41-client\build.vc10.
2. Make a copy of env.props.example, and rename it to env.props.
3. Open env.props in a text editor, and verify that the value in `<WDKPATH>C:\WinDDK\7600.16385.0</WDKPATH>` points to your WinDDK installation.
4. Open the solution file ms-nfs41-client.sln in Visual Studio 2010.
5. Select the desired configuration and platform (accessible via Build->Configuration Manager).
6. Right-click on the daemon project and select Build. The project and its dependencies should build without errors. The resulting binaries, nfsd.exe and libtirpc.dll, can be found under ms-nfs41-client\build.vc10\x64\Debug\.

### Building the driver and utilities

1. From the Start menu, open the WinDDK 'Checked Build Environment' for the target platform.
2. Change directory to ms-nfs41-client and type `build`. All projects should build without errors.

### Signing the driver

1. Open a WinDDK 'Checked Build Environment' as Administrator in this directory (right click and 'Run as administrator').
2. Create a certificate for test-signing the driver (Creating Test Certificates):
   `> makecert /pe /ss PrivateCertStore /n CN=nfs41_driver nfs41_driver.cer`
3. Use the certificate to sign nfs41_driver.sys (Test-Signing a Driver File):
   `> signtool sign /v /s PrivateCertStore /n nfs41_driver /t http://timestamp.verisign.com/scripts/timestamp.dll path\to\nfs41_driver.sys`

## 2. Installing Binaries

### Requirements

- ms-nfs41-client binaries: nfs41_driver.sys, nfs41_np.dll, libtirpc.dll, nfs_install.exe, nfsd.exe, nfs_mount.exe
- ms-nfs41-client configuration files: nfs41_driver.cer, nfs41rdr.inf, install.bat, uninstall.bat, etc_netconfig, ms-nfs41-idmap.conf
- Microsoft Visual Studio 2010, or Microsoft Visual C++ 2010 Redistributable Libraries (x86 or x64). An installer for the redistributable libraries are included with binary releases.

### Instructions

1. Copy or extract all ms-nfs41-client binaries and configuration files into a directory that's convenient for testing.
2. Run vcredist_x*.exe to install the Visual C++ Redistributable Libraries.
3. Double-click on nfs41_driver.cer and select 'Install Certificate', then place it in the 'Trusted Root Certificate Authorities' store.
4. Open a command prompt as Administrator in this directory.
5. Install the driver and update the registry:
   `> install.bat`
6. Copy configuration files:
   `> mkdir C:\etc`
   `> copy etc_netconfig C:\etc\netconfig`
   `> copy ms-nfs41-idmap.conf C:\etc\`
7. Allow windows to load test-signed drivers:
   `> bcdedit /set testsigning on`
8. Reboot.

## 3. Ldap Configuration

### Requirements:

- C:\etc\ms-nfs41-idmap.conf from Installation step 7.

### Instructions

1. Open C:\etc\ms-nfs41-idmap.conf in a text editor.
2. Uncomment the `ldap_hostname` and `ldap_base` lines, and configure as appropriate to match your ldap server configuration (we'll add suggestions later).

## 4. Starting the Client

- If you've installed the binary distribution, you'll find two versions of the nfs client daemon: nfsd.exe and nfsd_debug.exe. nfsd.exe is built to run as a service, and does not provide easy access to debug output. We strongly recommend trying nfsd_debug.exe first (using the Instructions below) to verify that you can start the daemon and mount/unmount an nfs share. You can then close nfsd_debug.exe and start running nfsd.exe as a service with:
  `> nfsd.exe -install`.

### Instructions

1. From a Windows command prompt, run nfsd.exe to start the nfs client daemon. Leave this running in the background until all mapped drives are unmounted.
   Usage:
   `> nfsd.exe -d <debug level> [--noldap]`
   - `<debug level>` determines the log verbosity (1, 2, 3 or 0 to disable)
   - `--noldap` disables id mapping and uses a default uid=666 and gid=777

## 5. Mounting

### Instructions

1. From a Windows command prompt run nfs_mount.exe to mount a share:
   `> nfs_mount.exe Z: <server_name>:\`
2. To specify the security flavor, add the 'sec=' mount option with sys, krb5, krb5i, or krb5p:
   `> nfs_mount.exe -o sec=<flavor> Z: <server_name>:\`
3. You can later unmount with:
   `> nfs_mount.exe -d Z`

## 6. Connectathon

### Requirements

- Cygwin, including packages gcc-core, make, time, tirpc, git
- Connectathon Test Suite
- ms-nfs41-client source code (patches for connectathon are located in ms-nfs41-client\tests)

### Instructions

1. Extract nfstests.zip into a directory that's convenient for testing (i.e. cthon04).
2. Open a Cygwin shell, and change directory to cthon04.
3. Create a git repository to track changes:
   `> git init`
   `> git add *`
   `> git commit -m "files from nfstests.zip"`
4. Apply all cthon patches:
   `> git am /path/to/ms-nfs41-client/tests/*.patch`
5. Build the tests:
   `> make`
6. Run the test suite on a mounted directory:
   `> ./runtests -a -t z:/testdir`

## 7. Known Issues

- krb5p security with AES keys do not work against the linux server, as it does not support gss krb5 v2 tokens with rotated data.
- When recovering opens and locks outside of the server's grace period, client does not check whether the file has been modified by another client.
- If nfsd.exe is restarted while a drive is mapped, that drive needs to be remounted before further use.
- Symbolic links are not supported in Cygwin. Connectathon's basic test8 and special test nfsidem have been commented out.
- Does not allow renaming a file on top of an existing open file. Connectathon's special test op_ren has been commented out.
- The Windows DFS client interferes with some requests, indicated by long delays during operation. To disable the DFS client, use regedit.exe to navigate to HKLM\System\CurrentControlSet\Services\Mup, and add a REG_DWORD entry named 'DisableDfs' with a value of 1. See http://support.microsoft.com/kb/171386 for more information.

Please direct any questions to ms-nfs41-client-devel@lists.sourceforge.net.