3.2.5.5 Receiving a Root Referral Request or Link Referral Request

  • Article

If the DFS namespace for which referral is sought, as identified by the second path component, is not present in DFSNamespaceList, for a stand-alone namespace the server SHOULD<21> fail the referral request with a STATUS_NOT_FOUND (0xC0000225) return code, and for a domain-based DFS namespace the server SHOULD<22> fail the referral request with a STATUS_DFS_UNAVAILABLE (0xC000026D) return code.

If the DFS referral request path has more than two components, the server MUST attempt to find a DFS link in the DFSNamespaceList, which is a prefix match starting with the DFS Namespace root name of the DFS referral request path. For example, if the DFS referral request path is "\MyServer\MyDfs\dir1\link1\dir2", the DFS link "\MyDfs\dir1\link1" is a prefix match starting with the DFS Namespace root name of the DFS referral request path. On the other hand, the same DFS link is not a prefix match starting with the DFS Namespace root name of the DFS referral request path "\MyServer\MyDfs\dir1\link2\dir2". The server MUST do the comparison in a case-insensitive manner, taking into account the situation of a DFS referral request path whose first path component is in the fully qualified domain name form when the DFS root or DFS link's first path component is in the NetBIOS form (or vice versa). NetBIOS and fully qualified domain names MUST be supported for a DFS referral request path.

If a DFS link that is a prefix match starting with the DFS Namespace root name of the DFS referral request path is identified, the server MUST return a DFS link referral response; otherwise, if it has a match for the DFS root, it MUST return a root referral response.

For a domain-based DFS namespace, the server MUST use the DFS metadata in the object of the DFS namespace (as specified in [MS-DFSNM] section 2.3) to respond to the DFS referral request. The DFS metadata is set as specified in [MS-DFSNM] section 3.1.4.1. When the server maintains DFSMetadataCache, it MAY use the cached information to respond to referral requests. The relevant fields in the DFS metadata for a domain-based DFS namespace are as follows:

  • The DFSNamespaceRootBLOB contains DFS root information.

  • The DFSNamespaceLinkBLOB contains DFS link information.

  • The Prefix and ShortPrefix fields of a DFS DFSRootOrLinkIDBLOB MUST contain a DFS root or a DFS link name.

  • The ReferralTTL field of a DFSNamespaceRootBLOB or a DFSNamespaceLinkBLOB MUST contain the time-out associated with the DFS root or link.

  • The DFSTargetListBLOB of a DFSNamespaceRootBLOB or a DFSNamespaceLinkBLOB MUST contain DFS root or DFS link target information.

  • The PKT_ENTRY_TYPE_COST_BASED_SITE_SELECTION bit in the Type field of a DFSRootOrLinkIDBLOB of a DFSNamespaceRootBLOB MUST be set to indicate that the DFS referral site costing is enabled for the DFS namespace.

  • The PKT_ENTRY_TYPE_TARGET_FAILBACK and PKT_ENTRY_TYPE_INSITE_ONLY bits in the Type field of a DFSRootOrLinkIDBLOB of a DFSNamespaceRootBLOB or a DFSnamespaceLinkBLOB MUST be set to indicate that the DFS client target failback and DFS in-site referral mode are enabled for the DFS root or DFS link.

  • The PKT_ENTRY_TYPE_OUTSIDE_MY_DOM bit of the Type field in a DFSRootOrLinkIDBLOB of a DFSnamespaceLinkBLOB MUST be set for a DFS interlink.

  • When not used as a time stamp, the TargetTimeStamp field of a TargetEntryBLOB MUST contain the DFS root or DFS link target priority information. The PriorityClass and PriorityRank fields in such a TargetTimeStamp field MUST contain the priority class and priority rank of the target respectively.

The server SHOULD do the following once it has identified the DFS root targets or DFS link targets that correspond to the DFS root or DFS link to be used for the DFS referral response.

  • From the IP address of the client, determine the site of the client as specified in [MS-NRPC] section 3.5.4.3.8.

  • Determine the site of each target. For a domain-based DFS namespace, the server SHOULD NOT use the SiteInformationBLOB in the DFS metadata. The site of a DFS target SHOULD instead be determined from the IP address of the DFS target as specified in [MS-NRPC] section 3.5.4.3.8. The server MUST use the host name of the target-the first component in the path - to determine the IP address of the target.<23>

  • If the server supports DFS referral site costing, and site costing is enabled for the DFS namespace, determine the site cost from the client's site (3) to the target's site as specified in [MS-DRSR] section 4.1.16.<24>

If the server does not support DFS target priority as specified in [MS-DFSNM] section 2.2.2.7 or if all the targets have the default priority, the server MUST proceed as follows:

  • If DFS referral site costing is disabled or not supported, sort the targets based on the site location as specified in section 3.2.1.1.

  • If DFS referral site costing is enabled, sort the targets based on the site cost as specified in section 3.2.1.2.

  • If the DFS_PROPERTY_FLAG_INSITE_REFERRALS flag in NameSpaceElement.Properties (as specified in [MS-DFSNM] section 3.1.1.3) is set for the root of DFS namespace, the root and link referrals SHOULD<25> return only targets that are in the same site as the client. If no root or link targets exist in the same site as the client, then no referral is returned and the client cannot access that portion of the namespace.

  • If the DFS_PROPERTY_FLAG_INSITE_REFERRALS flag is not set in NameSpaceElement.Properties for the root of DFS namespace but is set for a link, then the link referrals MUST return only targets that are in the same site as the client. If no link targets exist in the same site as the client, then no referral is returned and the client cannot access the link.

A server that supports DFS referral version 4 MUST also support DFS target priority.

If the server supports DFS target priority and if at least one DFS target has a nondefault priority, the server MUST perform the following:

  • At a coarse-grained level, lay out the targets into 3 groups based on the priority class. For more information on priority class, see [MS-DFSNM] section 2.2.2.7.

    • Targets in the DfsGlobalHighPriorityClass priority class. This will be referred to as group 1 for identification purposes.

    • Targets in the DfsSiteCostHighPriorityClass, DfsSiteCostNormalPriorityClass, and DfsSiteCostLowPriorityClass priority classes. This will be referred to as group 2 for identification purposes.

    • Targets in the DfsGlobalLowPriorityClass priority class. This will be referred to as group 3 for identification purposes.

  • If DFS referral site costing is enabled, sort the targets within each group based on the site cost as specified in section 3.2.1.2.

  • If DFS in-site referral mode is enabled for the DFS namespace, the server MUST remove all targets that are not in the same site of the client from group 2.

  • Further sort targets having the same site cost in group 2 on the basis of priority class in the order of DfsSiteCostHighPriorityClass first, followed by DfsSiteCostNormalPriorityClass, and finally DfsSiteCostLowPriorityClass.

  • Within each of the three groups, further sort targets that have the same site cost and priority class in order of decreasing priority rank, with 0 (0x0000) being the highest priority rank and 31 (0x001F) being the lowest priority rank. The server SHOULD create target sets that consist of targets that have the same site cost, priority class, and priority rank.

  • The server SHOULD randomly reorder targets in each target set on a per-DFS referral response basis, to enable load-sharing across the targets.

Because there are three dimensions available for the sorting of targets—site cost, priority class and priority rank-additional implementation defined sorting policies MAY be used within each of the three groups previously specified.<26>

After the sorted list of targets is available, noting that the list can be empty due to DFS in-site referral mode, the server still MUST initialize the RESP_GET_DFS_REFERRAL referral header as follows:

  • For a DFS root referral response, the PathConsumed field MUST be set to the length, in bytes, of the first two path components in the referral request. For a DFS link referral response, PathConsumed MUST be set to the length, in bytes, of the DFS referral request path prefix that matches the DFS link. This field MUST consist of the length of the whole path components in their entirety. For example, if the referral request path is "\MyDomain\MyDfs\dir1\link1\dir2\file1" and "\MyDomain\MyDfs\dir\link1" is a DFS link, PathConsumed is 50 (2 bytes for each of the 25 characters).

  • NumberOfReferrals MUST be set to the number of complete DFS referral entries that can be returned in the response buffer provided by the DFS referral request. The server MAY silently drop targets that will not fit in the buffer. However, if the buffer size is insufficient to return even one referral entry, the server MUST fail the referral request, as specified in section 3.2.5.1.<27>

  • If DFS root targets are returned or if a DFS interlink is returned, the ReferralServers bit of the referral entry MUST be set to 1. In all other cases, it MUST be set to 0.

  • If DFS root targets are returned or if DFS link targets are returned, the StorageServers bit of the referral entry MUST be set to 1. In all other cases, it MUST be set to 0.

  • For a DFS referral version 1, the ReferralServers and StorageServers bits of the referral entry MUST be set to 1.

  • For a DFS referral version 4 response, the TargetFailback field MUST be set to 0x0001 in a DFS root referral response if DFS client target failback is enabled for the DFS root. For link referrals, the TargetFailback field MUST be set to 0x0001 if DFS client target failback is enabled either for the link itself or for the DFS root. In all other cases, the TargetFailback field MUST be set to 0x0000.

  • All other fields are reserved and SHOULD be set to 0.<28>

The server MUST add one referral entry structure for each target returned and initialize each referral entry as follows:

  • The VersionNumber field MUST be set to the minimum of the highest DFS referral version supported by the server and the value specified in the MaxReferralLevel field of REQ_GET_DFS_REFERRAL.

  • The Size field MUST be set to the total size of the referral entry, in bytes. The Size field of a referral entry structure MUST include the size, in bytes, of all immediately following strings so that a client can find the next referral entry in the message. The Size field of a referral entry structure MUST NOT include the size of referenced strings located after the last referral entry in the message.

  • The ServerType field MUST be set to 0x0001 if root targets are returned. In all other cases, the ServerType field MUST be set to 0x0000.

  • The NameListReferral field MUST be set to 0.

  • For DFS referral version 4 responses, the TargetSetBoundary bit MUST be set to 1 for each target that is the first target in a target set, and MUST be set to 0 for all other targets.

  • The TimeToLive field MUST be set to the time-out value associated with the DFS root or DFS link. When there is more than one referral entry, the TimeToLive field of each referral entry MUST be the same.

  • For a DFS root referral response:

    • The DFSPathOffset field MUST be set to the offset, in bytes, from the beginning of the referral entry to a string that contains the first two path components of the DFS referral request path.

  • For a link referral response:

    • The DFSPathOffset field MUST be set to the offset, in bytes, from the beginning of the referral entry to a string that contains the DFS referral request path prefix that matches a DFS link.

    • The DFSAlternatePathOffset field MUST be set as specified in section 2.2.5.3.1. This path MAY either be the same as the path as pointed to by the DFSPathOffset field or be an 8.3 name. In the former case, the string referenced MAY be the same as that in DFSPathOffset or a duplicate copy. <29>

  • The NetworkAddressOffset field MUST be set to the offset, in bytes, from the beginning of the referral entry to a string that contains the DFS target for the entry.

  • All other fields are reserved and MUST be set to 0.

Servers SHOULD<30> return fully qualified DNS host names of targets in responses to root referral requests and link referral requests.