Extended DFS referral for SMB 3

This blog talks about site-aware DFS referral introduced in Windows Server 2012. Extended DFS referrals provide remote client computers with optimal DFS referrals when the computers connect to the corporate network by using DirectAccess. This blog also describes how to configure a Window 8 client to issue extended DFS referral request for testing a SMB 3 server implementation.

Feature summary

Windows Server 2012 added extended DFS referral which enables the support of site awareness for Direct Access clients on Windows 8.

When a user on Windows 8 connects to Windows Server 2012 based DFS namespaces over Direct Access, the client receives referrals to the namespace servers and folder targets that are closest to their location.

In Windows 7, a remote computer (e.g. connected over Direct Access) whose IP address is outside of the sites specified in Active Directory would receive DFS referrals in a random order (from Windows Server 2008 R2 namespace server), including servers in distant sites. This may cause network latency and increased bandwidth usage.

In Windows 8, Direct Access was enhanced with site awareness. When accessing a DFS namespace over a Direct Access connection, the client provides a site name in the DFS referral request to Windows Server 2012 namespace server. The server uses the site name to order the referrals so that the client can get to the closest site available.

The extended DFS referral is sent using the new control code FSCTL_DFS_GET_REFERRALS_EX [MS-SMB2].  It is important to note that if an SMB 3.x server is DFS capable, it must support extended DFS referral. All Windows-based SMB 3.x servers (2012 and 2012 R2) support this new FSCTL.

Windows 8 implementation-specific triggers

A Windows-based DFS client decides to use FSCTL_DFS_GET_REFERRALS_EX if the computer is connected over Direct Access and the negotiated SMB dialect is 3.0 or above.

The extended referral provisioning is done on Windows 8/8.1 by Direct Access configuration.
The DFS client detects that the client is connected over Direct Access if UseDcLocatorSiteName != 0. Direct Access also provisions the SiteName configuration. Recall that the value of the SiteName entry takes precedence over the value of DynamicSiteName (which is dynamically set by Netlogon service; the site that the computer belongs to can be determined with DsGetSiteName API call). 

The following instructions may be practical for testing an SMB 3 server implementation with extended DFS referral. The key is to get the client issue the new FSCTL by setting the configuration that Direct Access would have provisioned.
When a Windows client requests for site-aware referrals, the server should not fail with the request, even with STATUS_NOT_SUPPORTED, otherwise the client will not be able to access the SMB 3 share, because there is no fallback mechanism from FSCTL_DFS_GET_REFERRALS_EX to FSCTL_DFS_GET_REFERRALS.

Windows-based extended DFS referrals testing

In my testing environment, I have a configuration similar to the following.

DC01 is running Windows Server 2012 in this site MS-SMB_Internal.
DFS Management \ Namespaces
SiteName MS-SMB_Internal
Namespace \\contoso.com\ShareVolume1, Add folder Share1 with target \\dc01\FileShare2

On the Windows 8 client:
UseDcLocatorSiteName = 1
This indicates to the DFS client that the client is connected over “Direct Access”.
SiteName MS-SMB_Internal
(SiteName is a string)
NOTE: If the SiteName is not configured, the client will issue FSCTL_DFS_GET_REFERRALS.
Restart Workstation service, and accept to restart Netlogon and Dfs Namespace services.

With the proper configuration, the client will send site-aware referral requests when asking for DFS referrals over SMB 3 connections.

--- Site-aware DFS referral request example ---

  - CIoCtl:
     StructureSize: 57 (0x39)
     Reserved: 0 (0x0)
   + FileId: Persistent: 0xFFFFFFFFFFFFFFFF, Volatile: 0xFFFFFFFFFFFFFFFF
     InputOffset: 120 (0x78)
     InputCount: 97 (0x61)
     MaxInputResponse: 0 (0x0)
     OutputOffset: 120 (0x78)
     OutputCount: 0 (0x0)
     MaxOutputResponse: 4096 (0x1000)
     Flags: (00000000000000000000000000000001) FSCTL request
     Reserved2: 0 (0x0)
   - ReqGetDFSReferralEx:
      MaxReferralLevel: 4 (0x4)
    - RequestFlags: 1 (0x1)
       SiteName: (...............1) - SiteName present: The SiteName bit MUST be set to 1 if the packet contains the site name of the client.
       Unused:   (000000000000000.) - Unused
      RequestDataLength: 88 (0x58)
    - RequestData:
       RequestFileNameLength: 52 (0x34)
       RequestFileName: \contoso.com\ShareVolume1
       SiteNameLength: 32 (0x20)
       SiteName: MS-SMB_Internal
    padding: Binary Large Object (1 Bytes)

--- Response example ---

  - RIoCtl:
     StructureSize: 49 (0x31)
     Reserved: 0 (0x0)
   + FileId: Persistent: 0xFFFFFFFFFFFFFFFF, Volatile: 0xFFFFFFFFFFFFFFFF
     InputOffset: 112 (0x70)
     InputCount: 0 (0x0)
     OutputOffset: 112 (0x70)
     OutputCount: 184 (0xB8)
     Flags: 0 (0x0)
     Reserved2: 0 (0x0)
   - RespGetDFSReferral:
      PathConsumed: 50 bytes
      NumberOfReferrals: 1 (0x1)
    + ReferralHeaderFlags: 3 (0x3)
    - ReferralEntries: Version:4
     - ReferralV4: Index:1 TTL:300 Seconds
        VersionNumber: 0x4, MUST be set to 0x4
        Size: 34 (0x22)
        ServerType: Root targets returned
      + ReferralEntryFlags: 4 (0x4)
        TimeToLive: 300 Seconds
        DfsPathOffset: 34 (0x22) Offset:0xD4
        DfsAlternatePathOffset: 86 (0x56) Offset:0x108
        NetworkAddressOffset: 138 (0x8A) Offset:0x13C
        ServiceSiteGuid: {00000000-0000-0000-0000-000000000000} 
       DfsPath: Index:1 \contoso.com\ShareVolume1
       DfsAlternatePath: Index:1 \contoso.com\ShareVolume1
       TargetPath: Index:1 \DC01\ShareVolume1 


What's New in DFS Namespaces and DFS Replication in Windows Server 2012

How DFS Works

[MS-DFSC]: Distributed File System (DFS): Referral Protocol
[MS-CIFS]: Common Internet File System (CIFS) Protocol
[MS-SMB2]: Server Message Block (SMB) Protocol Versions 2 and 3


Comments (0)

Skip to main content