3.3 Example 3: Two Applications Communicate Via a Shared File

  • Article

This example illustrates the interaction between two applications, one using the NFS File Access Protocol and another using the SMB File Access Protocol, to share a file on a remote file server. This example demonstrates the use case described in section 2.5.3. The application in this example accesses an NFS file using NFS version 2 (as described in [RFC1094]) or NFS version 3 (as described in [RFC1813]).

Prerequisites

All general requirements as set forth in section 2.4 Assumptions and Preconditions are met.

  • The participating client and server computers are configured to belong to the same Active Directory domain.

  • The NFS and SMB File shares are preconfigured on the file server computer to have access to the same directory in the object store, and are provisioned to allow SMB user and NFS user access to the SMB file share and NFS file share, respectively. Further, the client computer from which the NFS User will access the NFS file share is granted access on the NFS file share.

  • A handle already exists for the NFS file share.

  • The NFS file service is configured to use Active Directory as the LDAP mapping store for user account mapping, as described in [RFC2307].

  • The file server hosting the NFS file share is configured to do LDAP lookups on the Active Directory.

  • The user account corresponding to the SMB User in Active Directory has the uidNumber attribute set to the value of the user ID field of the AUTH_SYS credentials corresponding to the NFS User.

  • A group account corresponding to the group that the SMB User belongs to in Active Directory has the gidNumber attribute set to the value of the group ID field of the AUTH_SYS credentials corresponding to the NFS user.

  • The directory in the object store on the file server that is being shared by the SMB file share and NFS file share does not already have a file with the same name as the file being shared in this example.

Initial System State

None.

Final System State

A new file has been created in the directory on the object store that backs the NFS file share and SMB file share. This file contains the data from both the NFS user and SMB user.

Sequence of Events

This example is divided into nine tasks:

  1. Open a file in an SMB file share

  2. Request a directory change notification using SMB

  3. Open a file in an NFS file share.

  4. Write a file using the NFS protocol

  5. Receive a directory change notification using SMB

  6. Read a file using the SMB protocol

  7. Write a file using SMB protocol

  8. Close a file using the SMB protocol

  9. Read a file using NFS protocol

Task 1: Open a File in an SMB File Share (Common Task 1)

Task 2: Request Directory Change Notification Using SMB

The sequence described in this example details how Application 1 uses the file client to request directory change notifications from the SMB file service for a directory on the SMB file share.

Sequence diagram for Request directory change notification using SMB

Figure 12: Sequence diagram for Request directory change notification using SMB

  1. Application 1 registers for a change notification by passing the directory handle and a notification filter that contains the type of notifications it is supposed to receive.

  2. The file client sends an SMB2 CHANGE NOTIFY request (see [MS-SMB2] section 2.2.35) to the file service in order to register a change notification on the directory that was successfully opened in the previous step.

  3. On successful completion of the SMB2 CHANGE NOTIFY request, the SMB file service returns the directory handle back to the file client.

  4. The file client returns the directory handle to Application 1. This is described further in [MS-SMB2] section 3.3.5.19.

Task 3: Open a File in an NFS File Share

The sequence described in this example details how an application uses the file client to open a file on an NFS file share.

Sequence diagram for Open a file in an NFS file share

Figure 13: Sequence diagram for Open a file in an NFS file share

  1. The NFS file client extracts the file server name, NFS file share, and the relative path to the file to be opened from the unc_path as indicated in the message Parse UNC Path To Mount Dir().

  2. The NFS file client contacts the file service to obtain the port number of the NFS file service by sending a PMAPPROC_GETPORT request, as described in [RFC1833] section 3.2.

  3. The file service returns the port number of the NFS file service.

  4. The NFS file client then contacts the mount file service on the file server with the MOUNTPROC3_MNT request (as described in [RFC1833] section 5.2.1), in order to get the NFS file handle corresponding to the NFS share name.

  5. The file client sends an LDAP Bind_request to the file service in order to configure the Active Directory service, as described in [RFC2251] section 4.2.

  6. The file service verifies the credentials of the incoming bind request and binds to the configured Active Directory service.

  7. The file service sends an LDAP Search request message to the Active Directory service in order to translate the supplied NFS identity (UID) to an account name that can be presented to the authentication service.

  8. The Active Directory service returns a list of zero or more account names, with related records and a count, as described in [RFC2251] section 4.5. Whenever there is no unique translation from the supplied identity, the NFS file service fails the authentication and returns STATUS_NOT_FOUND back to the caller.

  9. Whenever there is a unique translation from the supplied NFS identity, the NFS file service continues the authentication process. The file service sends a logon user request message to the authentication service in order to authenticate the user identified by the account name obtained as a result of the LDAP search request, as described in section 6 of [MS-AUTHSOD].

  10. The authentication service returns a security token, used in subsequent operations to identify the user account.

  11. On successful completion of authentication, the mount service validates the directory path, by verifying that the path sent by the NFS file client is provisioned for NFS sharing on the file server.

  12. The file client then traverses the path to the file on the NFS file share, in order to obtain an NFS File Handle corresponding to the file. The file client uses a LOOKUP request as described in [RFC1813] section 3.3.3 to obtain an NFS file handle corresponding to the component path to the target file.

  13. If the user identity has been authenticated previously, the file service returns a file handle that points to a file on the NFS file share. If there are more files to process, return to step 12.

Task 4: Write a File Using the NFS Protocol

The sequence described in this example details how an application uses the file client to update the contents of a file on the NFS file share.

Sequence diagram for Write a file using the NFS protocol

Figure 14: Sequence diagram for Write a file using the NFS protocol

  1. The file client writes the equested file contents, as represented by file_data, by issuing a series of NFS requests to the file service using the NFSPROC3_WRITE message as described in [RFC1813], section 3.3.7 to write the provided file data.

  2. If the user identity has been authenticated previously, and if it is still valid for the current message call, then content is successfully written in the file. Otherwise, the file service authenticates the user identity (steps 5 to 10 in Task 3: Open a File in an NFS File Share) and then writes the content to the file.

Task 5: Receive a Directory Change Notification Using SMB

The sequence described in this example details how the Application receives change notifications in response to a previously registered Request Directory Change Notification using SMB.

Sequence diagram for Receiving directory change notification using SMB

Figure 15: Sequence diagram for Receiving directory change notification using SMB

  1. The SMB file service receives a notification from the underlying object store in response to changes in the directory that was previously registered for notifications. The mechanism of this notification is specific to the object store implementation and is not covered in this document.

  2. In response to the change notification from the object store, the SMB file service sends an SMB2 CHANGE NOTIFY response message [MS-SMB2] section 2.2.36 to the SMB file client. As a part of this message the SMB file client receives details of the changes that occurred in the directory namespace as represented by the set of notify_entries. This is described further in [MS-SMB2] section 3.3.5.19.

  3. The SMB file client indicates the receipt of notification event from the SMB file service by signaling the dir_handle that was returned previously on successful completion of the Perform File Operation SMB Request Directory Change Notification sequence.

  4. The SMB application next reads the changes that occurred in the directory representing dir_handle by sending the read_directory_changes() message to the SMB file client. read_directory_changes() is an example of an application specific message that the SMB Application uses to read the set of changes in the directory.

  5. On successful completion of this message, the SMB application receives the updates that happened in the directory as represented by dir_updates.

Task 6: Read a File Using the SMB Protocol (Common Task 3)

Task 7: Write a File Using the SMB Protocol

The sequence described in this example details how the Application1 uses the file client to update the contents of a file on the SMB file share.

Sequence diagram for Write a file using the SMB protocol

Figure 16: Sequence diagram for Write a file using the SMB protocol

  1. The file to be written can be larger than can be processed by a single SMB2 WRITE request/SMB2 WRITE response pair. If so, the file client issues a series of SMB2 WRITE requests until the complete file has been written. The file client uses internally held state and the supplied file handle to obtain the file_id used to identify the file to the SMB file service, and sends an SMB2 WRITE Request (see [MS-SMB2] section 2.2.21) to the SMB file service for a piece of the file. A single piece of the file can be defined by the offset of the start of the piece from the beginning of the file and the length of the piece to be written. This is further described in [MS-SMB2] section 3.2.4.7. The size of the piece of the file to be retrieved is limited by the upper limit of a single SMB2 WRITE Request as supplied by the SMB file service to the file client in the SMB2 NEGOTIATE response (see [MS-SMB2] section 2.2.4) during the session establishment negotiation sequence.

  2. The SMB file service returns the status code in the Status field of the SMB2 header of the response to the file client that issued the request to write data to the file. The SMB file service also returns the Count value from the SMB2 WRITE response following the SMB2 header, indicating how many bytes were written ([MS-SMB2] section 3.2.5.12).

Task 8: Close a File Using the SMB Protocol (Common Task 4)

Task 9: Read a File Using the NFS Protocol

The sequence described in this example details how an application uses the file client to read the contents of a file on an NFS file share.

Sequence diagram for Read a file using the NFS protocol

Figure 17: Sequence diagram for Read a file using the NFS protocol

  • The Application directs the file client to communicate with the file service on a file server in order to get the complete file contents by issuing a series of NFS requests to the file service. The file client uses the NFSPROC3_READ message as described in [RFC1813], section 3.3.6 to read the file data.

The file service responds to the file client with the contents of the file that the file client requested.