Appendix 2: CIFS Specification

CIFS (Common Internet File System) defines a standard remote file system access protocol for use over the Internet, enabling groups of users to work together and share documents across the Internet or within their corporate intranets. CIFS is an open, cross-platform technology based on the native file-sharing protocols built into the Microsoft Windows and other popular PC operating systems, and supported on dozens of other platforms, including UNIX. Dfs is covered as part of the CIFS specification, a full copy of which can be obtained from the following URL: http://www.microsoft.com/intdev/cifs/cifs.htm#spec.

Dfs details from CIFS

Distributed File System (Dfs) Support

Protocol dialects of NT LM 0.12 and later support distributed file system operations. The Distributed File System gives a way for this protocol to use a single consistent file naming scheme which may span a collection of different servers and shares. The distributed file system model employed is a referral-based model. This protocol specifies the manner in which clients receive referrals.

The client can set a flag in the request SMB header indicating that the client wants the server to resolve this SMB's paths within the Dfs known to the server. The server attempts to resolve the requested name to a file contained within the local directory tree indicated by the TID of the request and proceeds normally. If the request path name resolves to a file on a different system, the server returns the following error:

STATUS_DFS_PATH_NOT_COVERED

The server does not support the part of the Dfs namespace needed to resolved the pathname in the request. The client should request a referral from this server for further information.

A client asks for a referral with the TRANS2_DFS_GET_REFERRAL request containing the Dfs pathname of interest. The response from the server indicates how the client should proceed. The method by which the topological knowledge of the Dfs is stored and maintained by the servers is not specified by this protocol.

Dfs Path Names

A Dfs pathname adheres to the standard described in the FileNames section. A Dfs-enabled client accessing a Dfs share should set the Flags2 bit 12 in all name-based SMB Headers indicating to the server that the enclosed pathname should be resolved in the Distributed File System namespace. The path name should always have the full file name, including the server name and share name. If the server can resolve the Dfs name to a piece of local storage, the local storage will be accessed. If the server determines that the Dfs name actually maps to a different server share, the access to the name will fail with the distinguished error:

STATUS_PATH_NOT_COVERED (SMB Status code 0xC0000257)

On receiving this error, the Dfs enabled client should ask the server for a referral (see TRANS2_GET_DFS_REFERRAL). The referral request should contain the full file name.

The response to the request will contain a list of server and share names to try, and the part of the request file name that junctions to the list of server shares. If the ServerType field of the referral is set to 1 (SMB server), then the client should resubmit the request with the original file name to one of the server shares in the list, once again setting the Flags2 bit 12 bit in the SMB. If the ServerType field is not 1, then the client should strip off the part of the file name that junctions to the server share before resubmitting the request to one of servers in the list.

A response to a referral request may elicit a response that does not have the StorageServers bit set. In that case, the client should resubmit the referral request to one of the servers in the list, until it finally obtains a referral response that has the StorageServers bit set, at which point the client can resubmit the request SMB to one of the listed server shares.

If, after getting a referral with the StorageServers bit set and resubmitting the request to one of the server shares in the list, the server fails the request with STATUS_PATH_NOT_COVERED, then there is an inconsistency between the view of the Dfs namespace held by the server granting the referral and the server listed in that referral. In this case, the client may inform the server granting the referral of this inconsistency via the TRANS2_REPORT_DFS_INCONSISTENCY SMB.

TRANS2_GET_DFS_REFERRAL:
Retrieve Distributed Filesystem Referral

The client sends this request to ask the server to convert RequestFilename into an alternate name for this file. This request can be sent to the server if the server response to the NEGOTIATE SMB included the CAP_DFS capability. The TID of the request must be IPC$. Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request.

The server response is a list of Referrals which inform the client where it should resubmit the request to obtain access to the file. PathConsumed in the response indicates to the client how many characters of RequestFilename have been consumed by the server. When the client chooses one of the referrals to use for file access, the client may need to strip the leading PathConsumed characters from the front of RequestFileName before submitting the name to the target server. Whether or not the pathname should be trimmed is indicated by the individual referral as detailed below.

Flags indicates how this referral should be treated. If bit0 is clear, any entity in the Referrals list holds the storage for RequestFileName. If bit0 is set, any entity in the Referrals list has further referral information for RequestFilename – a TRANS2_GET_DFS_REFERRAL request should be sent to an entity in the Referrals list for further resolution.

The format of an individual referral contains version and length information allowing the client to skip referrals it does not understand. MaxReferralLevel indicates to the server the latest version of referral which the client can digest. Since each referral has a uniform element, MaxReferralLevel is advisory only. Each element in Referrals has this envelope:

The following referral element versions are defined:

The SMB protocol imposes no referral selection policy.

TRANS2_REPORT_DFS_INCONSISTENCY:
Inform a Server About Dfs Error

As part of the Distributed Name Resolution algorithm, a Dfs client may discover a knowledge inconsistency between the referral server (i.e., the server that handed out a referral), and the storage server (i.e., the server to which the client was redirected to by the referral server). When such an inconsistency is discovered, the Dfs client optionally sends this SMB to the referral server, allowing the referral server to take corrective action.

The data part of this request contains the referral element (Version 1 format only) believed to be in error. These are encoded as described in the TRANS2_GET_DFS_REFERRAL response. If the server returns success, the client can resubmit the TRANS2_GET_DFS_REFERRAL request to this server to get a new referral. It is not mandatory for the Dfs knowledge to be automatically repaired; the client must be prepared to receive further errant referrals and must not wind up looping between this request and the TRANS2_GET_DFS_REFERRAL request.

Bit15 of Flags2 in the SMB header must be set, indicating this is a UNICODE request.