2.0 Protocol Operation Overview

In order to access a file on a server, a client has to:

Parse the full file name to determine the server name, and the relative name within that server.
Resolve the server name to a transport address (this may be cached).
Make a connection to the server (if no connection is already available).
Exchange CIFS messages (see below for an example).

This process may be repeated as many times as desired. Once the connection has been idle for a while, it may be torn down.

2.1 Server Name Determination

How the client determines the name of the server and the relative name within the server is outside the scope of this specification. However, for expository purposes, here are three examples.

In the URL "file://fs.megacorp.com/users/fred/stuff.txt," the client could take the part between the leading double slashes and the next slash as the server name and the remainder as the relative name—in this example "fs.megacorp.com" and "/users/fred/stuff.txt," respectively.

In the path name "\\corpserver\public\policy.doc," the client could take the part between the leading double backslashes and the next slash as the server name, and the remainder as the relative name—in this example, "corpserver" and "\public\policy.doc," respectively.

In the path name "x:\policy.doc," the client could use "x" as an index into a table that contains a server name and a file name prefix. If the contents of such a table for "x" were "corpserver" and "\public," then the server name and relative name would be the same as in the previous example.

2.2 Server Name Resolution

Like server name determination, how the client resolves the name to the transport address of the server is outside the scope of this specification. All that is required by CIFS is that a CIFS client must have some means to resolve the name of a CIFS server to a transport address, and that a CIFS server must register its name with a name resolution service known to its clients.

Some examples of name resolution mechanisms include: using the Domain Name System (DNS) [1,2] and NETBIOS name resolution (see RFC 1001 and RFC 1002 [3,4]). The server name might also be specified as the string form of an IPv4 address in the usual dotted decimal notation, e.g., "157.33.135.101." In this case, "resolution" consists of converting to the 32-bit IPv4 address.

Which method is used is configuration-dependent; the default should be DNS to encourage interoperability over the Internet.

Note The name resolution mechanism used may place constraints on the form of the server name; for example, in the case of NETBIOS, the server name must be 15 characters or less, and must be uppercase.

2.3 Sample Message Flow

The following illustrates a typical message exchange sequence for a client connecting to a user level server, opening a file, reading its data, closing the file, and disconnecting from the server.

Note Using the CIFS request batching mechanism (called the "AndX" mechanism), the second to sixth messages in this sequence can be combined into one. So there are really only three round trips in the sequence, and the last one can be done asynchronously by the client.

Client Command ====================	Server Response ===========================
`SMB_COM_NEGOTIATE`	Must be the first message sent by client to the server. Includes a list of SMB dialects supported by the client. Server response indicates which SMB dialect should be used.
`SMB_COM_SESSION_SETUP_ANDX`	Transmits the user's name and credentials to the server for verification. Successful server response has Uid field set in SMB header used for subsequent SMBs on behalf of this user.
`SMB_COM_TREE_CONNECT_ANDX`	Transmits the name of the disk share the client wants to access. Successful server response has Tid field set in SMB header used for subsequent SMBs referring to this resource.
`SMB_COM_OPEN_ANDX`	Transmits the name of the file, relative to Tid, the client wants to open. Successful server response includes a file id (Fid) the client should supply for subsequent operations on this file.
`SMB_COM_READ`	Client supplies Tid, Fid, file offset, and number of bytes to read. Successful server response includes the requested file data.
`SMB_COM_CLOSE`	Client closes the file represented by Tid and Fid. Server responds with success code.
`SMB_COM_TREE_DISCONNECT`	Client disconnects from resource represented by Tid.

2.4 CIFS Protocol Dialect Negotiation

The first message sent from a CIFS client to a CIFS server must be one whose Command field is SMB_COM_NEGOTIATE. The format of this client request includes an array of NULL terminated strings indicating the dialects of the CIFS protocol the client supports. The server compares this list against the list of dialects the server supports and returns the index of the chosen dialect in the response message.

2.5 Message Transport

CIFS is transport-independent. The CIFS protocol assumes:

A reliable connection-oriented message-stream transport, and makes no higher-level attempts to ensure sequenced delivery of messages between the client and server.
A well known endpoint for the CIFS service
Some mechanism to detect failures of either the client or server node, and to deliver such an indication to the client or server software so they can clean up state. When a reliable transport connection from a client terminates, all work in progress by that client is terminated by the server, and all resources open by that client on the server are closed.

It can run over any transport that meets these requirements. Some transports do not natively meet all the requirements, and a standard encapsulation of CIFS for that transport may need to be defined. Appendix A defines how to run CIFS over NETBIOS over TCP; Appendix B defines how to run CIFS over TCP.

2.5.1 Connection Management

After a connection is established, the rules for reliable transport connection dissolution are:

If a server receives a transport establishment request from a client with which it is already conversing, the server may terminate all other transport connections to that client. This is to recover from the situation where the client was suddenly rebooted and was unable to cleanly terminate its resource-sharing activities with the server.
A server may drop the transport connection to a client at any time if the client is generating malformed or illogical requests. However, wherever possible, the server should first return an error code to the client indicating the cause of the abort.
If a server gets a hard error on the transport (such as a send failure) the transport connection to that client may be aborted.
A server may terminate the transport connection when the client has no open resources on the server. However, we recommend that the termination be performed only after some time has passed or if resources are scarce on the server. This will help performance, in that the transport connection will not need to be reestablished if activity soon begins anew. Client software is expected to be able to automatically reconnect to the server if this happens.

2.6 Opportunistic Locks

Network performance can be increased if a client does not need to inform the server immediately about every change it makes to a file, or have to worry that other clients can make its information about the file out of date. For example, a client does not have to immediately write information into a file on the server if the client knows that no other process is accessing the data. Likewise, the client can buffer read-ahead data from the file if the client knows that no other process is writing the data.

The mechanism that allows clients to dynamically alter their buffering strategy in a consistent manner is knows as "opportunistic locks," or oplocks for short. Versions of the CIFS file-sharing protocol including and newer than the "LANMAN1.0" dialect support oplocks.

Note However, an implementation, even of these later dialects, can implement oplocks trivially by always refusing to grant them.

There are three different types of oplocks:

A Level II oplock, when held, informs a client that there are multiple concurrent clients of a file, and none has yet modified it. It allows the client to perform reads and file-attribute fetches using cached or read-ahead local information, but all other requests have to be sent to the server.
An exclusive oplock, when held, informs a client that it is the only one to have a file open. It allows the client to perform all file operations using cached or read-ahead local information until it closes the file, at which time the server has to be updated with any changes made to the state of the file (contents and attributes).
A batch oplock, when held, informs a client that it is the only one to have a file open. It allows the client to perform all file operations on cached or read-ahead local information (including opens and closes).

If a client holds no oplocks, all requests other than reads must be sent to the server. Reads may be performed using cached or read-ahead data as long as the byte range has been locked by the client; otherwise they too must be sent to the server.

When a client opens a file, it may request that the server grant it an exclusive or batch oplock on the file. The response from the server indicates the type of oplock granted to the client. If cached or read-ahead information was retained after the file was last closed, the client must verify that the last modified time is unchanged when the file is reopened before using the retained information.

The SMB_COM_LOCKING_ANDX SMB is used to convey oplock break requests and acknowledgements (as well as lock and unlock requests).

2.6.1 Exclusive Oplocks

The exclusive oplock protocol is:

Client		<->	Server
A ========	B =======	==	======================
Open ("foo")		`->`
		`<-`	Open OK. Exclusive oplock granted.
<locks, writes>
read (large)		`->`
		`<-`	read data
<reads from read-ahead >
	Open("foo")	`->`
		`<-`	oplock break to A
lock(s)		`->`
		`<-`	lock(s) response(s)
write(s)		`->`
		`<-`	write(s) response(s)
close or oplock ack		`->`
		`<-`	open response to B

When client A opens the file, it can request an exclusive oplock. Provided no one else has the file open on the server, the server may grant the oplock to client A.

If, at some point in the future, another client, such as client B, requests an open of the same file, or requests a path name based operation on the file, then the server must tell client A to relinquish its exclusive oplock. If client B's request will not modify the state of the file, the server may tell client A that its exclusive oplock has been replaced by a level II oplock.

When a client's exclusive oplock is broken, it must synchronize the server to the local state of the file (contents and attributes) and any locks it holds on the file, and then acknowledge the oplock break request. After the server receives the acknowledgement, it can process B's request.

2.6.2 Batch Oplocks

The batch oplock protocol is:

Client		<->	Server
A =======	B =======	===	=====================
Open("foo")		`->`
		`<-`	Open OK. Batch oplock granted.
Read		`->`
		`<-`	read data
<close>
<open>
<seek>
Read		`->`
		`<-`	Data
<close>
	Open("foo")	`->`
		`<-`	Oplock break to A
Close		`->`
		`<-`	Close OK to A
		`<-`	Open OK to B

When client A opens the file, it can request a batch oplock. Provided no one else has the file open on the server, then the server may grant the oplock to client A.

If, at some point in the future, another client, such as client B, requests any operation on the same file, then the server must tell client A to relinquish its batch oplock. If client B's request will not modify the state of the file (or rename it), the server may tell client A that its batch oplock has been replaced by a level II oplock.

If A has the file open at the time the oplock break request is received, its actions will be the same as if it had an exclusive oplock. If A does not have the file open at the time the oplock break request is received, it sends a close to the server. Once the file is actually closed at the server, client B's open request can be processed.

2.6.3 Level II Oplocks

The Level II oplock protocol is:

Client		<->	Server
A =======	B =======	==	======================
Open("foo")		`->`
		`<-`	Open OK. Exclusive oplock granted.
Read		`->`
		`<-`	data
	Open("foo")	`->`
		`<-`	Break to Level II oplock to A
lock(s)		`->`
		`<-`	lock(s) response(s)
oplock ack		`->`
		`<-`	Open OK. Oplock II oplock granted to B

When a client opens a file, it may request an exclusive or batch oplock. If the requested oplock cannot be granted, the server may grant a Level II oplock if the file currently has an oplock on it. If there is currently an exclusive or batch oplock on the file, it must be broken and the break acknowledged before the open is processed. If there is currently a Level II oplock on the file, it does not need to be broken, and the open may be processed immediately.

If any client sends a request to modify the state of a file that has a Level II oplock, the server must ask all clients holding an oplock on the file to break it, but need not wait for an acknowledgement.

2.7 Security Model

Each server makes a set of resources available to clients on the network. A resource being shared may be a directory tree, printer, etc. As far as clients are concerned, the server has no storage or service dependencies on any other servers; a client considers the server to be the sole provider of the file (or other resource) being accessed.

The CIFS protocol requires server authentication of users before file accesses are allowed, and each server authenticates its own users. A client system must send authentication information to the server before the server will allow access to its resources.

A server requires the client to provide a user name and some proof of identity (often something cryptographically derived from a password) to gain access. The granularity of authorization is up to the server. For example, it may use the account name to check access control lists on individual files, or may have one access control list that applies to all files in the directory tree.

When a server validates the account name and password presented by the client, an identifier representing that authenticated instance of the user is returned to the client in the Uid field of the response SMB. This Uid must be included in all further requests made from that client on behalf of the user.

2.8 Authentication

The information on authentication in previous revisions of this document has been moved to a different specification.

2.9 Distributed File System (Dfs) Support

Protocol dialects of NT LM 0.12 and later support distributed file system operations. The Microsoft Dfs 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 Dfs 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 pathname 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 resolve 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.