CIFS/SMB3: Update documentation to reflect SMB3 and various changes

Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)

Scott Lovenberg

Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)

Aurelien Aptel (for DFS SMB3 work and some key bug fixes)

Ronnie Sahlberg (for SMB3 xattr work and bug fixes)

Shirish Pargaonkar (for many ACL patches over the years)

Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)

Test case and Bug Report contributors

-------------------------------------

The CIFS VFS support for Linux supports many advanced network filesystem 

features such as hierarchical dfs like namespace, hardlinks, locking and more.  

This module supports the SMB3 family of advanced network protocols (as well

as older dialects, originally called "CIFS" or SMB1).

The CIFS VFS module for Linux supports many advanced network filesystem

features such as hierarchical DFS like namespace, hardlinks, locking and more.

It was designed to comply with the SNIA CIFS Technical Reference (which 

supersedes the 1992 X/Open SMB Standard) as well as to perform best practice 

practical interoperability with Windows 2000, Windows XP, Samba and equivalent 

servers.  This code was developed in participation with the Protocol Freedom

Information Foundation.

Information Foundation.  CIFS and now SMB3 has now become a defacto

standard for interoperating between Macs and Windows and major NAS appliances.

Please see

  http://protocolfreedom.org/ and

For questions or bug reports please contact:

    sfrench@samba.org (sfrench@us.ibm.com) 

See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils

Build instructions:

==================

For Linux 2.4:

1) Get the kernel source (e.g.from http://www.kernel.org)

and download the cifs vfs source (see the project page

at http://us1.samba.org/samba/Linux_CIFS_client.html)

and change directory into the top of the kernel directory

then patch the kernel (e.g. "patch -p1 < cifs_24.patch") 

to add the cifs vfs to your kernel configure options if

it has not already been added (e.g. current SuSE and UL

users do not need to apply the cifs_24.patch since the cifs vfs is

already in the kernel configure menu) and then

mkdir linux/fs/cifs and then copy the current cifs vfs files from

the cifs download to your kernel build directory e.g.

	cp <cifs_download_dir>/fs/cifs/* to <kernel_download_dir>/fs/cifs

2) make menuconfig (or make xconfig)

3) select cifs from within the network filesystem choices

4) save and exit

5) make dep

6) make modules (or "make" if CIFS VFS not to be built as a module)

For Linux 2.6:

For Linux:

1) Download the kernel (e.g. from http://www.kernel.org)

and change directory into the top of the kernel directory tree

(e.g. /usr/src/linux-2.5.73)

If you do not have the utility mount.cifs (in the Samba 3.0 source tree and on 

the CIFS VFS web site) copy it to the same directory in which mount.smbfs and 

similar files reside (usually /sbin).  Although the helper software is not  

required, mount.cifs is recommended.  Eventually the Samba 3.0 utility program 

"net" may also be helpful since it may someday provide easier mount syntax for

users who are used to Windows e.g.

	net use <mount point> <UNC name or cifs URL>

required, mount.cifs is recommended.  Most distros include a "cifs-utils"

package that includes this utility so it is recommended to install this.

Note that running the Winbind pam/nss module (logon service) on all of your

Linux clients is useful in mapping Uids and Gids consistently across the

domain to the proper network user.  The mount.cifs mount helper can be

trivially built from Samba 3.0 or later source e.g. by executing:

	gcc samba/source/client/mount.cifs.c -o mount.cifs

found at cifs-utils.git on git.samba.org

If cifs is built as a module, then the size and number of network buffers

and maximum number of simultaneous requests to one server can be configured.

on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made

at module initialization time (by running insmod cifs.ko) can be seen.

Recommendations

===============

To improve security the SMB2.1 dialect or later (usually will get SMB3) is now

the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"

on mount (or vers=2.0 for Windows Vista).  Note that the CIFS (vers=1.0) is

much older and less secure than the default dialect SMB3 which includes

many advanced security features such as downgrade attack detection

and encrypted shares and stronger signing and authentication algorithms.

There are additional mount options that may be helpful for SMB3 to get

improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):

     "mfsymlinks" and "cifsacl" and "idsfromsid"

Allowing User Mounts

====================

To permit users to mount and unmount over directories they own is possible

by default. This can be changed, as with nfs and other filesystems, 

by simply specifying "nosuid" among the mount options. For user mounts 

though to be able to pass the suid flag to mount requires rebuilding 

mount.cifs with the following flag: 

        gcc samba/source/client/mount.cifs.c -DCIFS_ALLOW_USR_SUID -o mount.cifs

mount.cifs with the following flag: CIFS_ALLOW_USR_SUID

There is a corresponding manual page for cifs mounting in the Samba 3.0 and

later source tree in docs/manpages/mount.cifs.8 

Use instructions:

================

Once the CIFS VFS support is built into the kernel or installed as a module 

(cifs.o), you can use mount syntax like the following to access Samba or Windows 

servers: 

(cifs.ko), you can use mount syntax like the following to access Samba or

Mac or Windows servers:

  mount -t cifs //9.53.216.11/e$ /mnt -o user=myname,pass=mypassword

  mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword

Before -o the option -v may be specified to make the mount.cifs

mount helper display the mount steps more verbosely.  

After -o the following commonly used cifs vfs specific options

are supported:

  user=<username>

  pass=<password>

  username=<username>

  password=<password>

  domain=<domain name>

Other cifs mount options are described below.  Use of TCP names (in addition to

filenames (ie those which contain valid Linux characters, which normally

would be forbidden for Windows/CIFS semantics) as long as the server is

configured for Unix Extensions (and the client has not disabled

/proc/fs/cifs/LinuxExtensionsEnabled).

/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option

"mapposix" can be used on CIFS (vers=1.0) to force the mapping of

illegal Windows/NTFS/SMB characters to a remap range (this mount parm

is the default for SMB3). This remap ("mapposix") range is also

compatible with Mac (and "Services for Mac" on some older Windows).

CIFS VFS Mount Options

======================

A partial list of the supported mount options follows:

  user		The user name to use when trying to establish

  username	The user name to use when trying to establish

		the CIFS session.

  password	The user password.  If the mount helper is

		installed, the user will be prompted for password

Version 2.03 August 1, 2014

Version 2.04 September 13, 2017

A Partial List of Missing Features

==================================

is a partial list of the known problems and missing features:

a) SMB3 (and SMB3.02) missing optional features:

   - RDMA

   - RDMA (started)

   - multichannel (started)

   - directory leases (improved metadata caching)

   - T10 copy offload (copy chunk is only mechanism supported)

   - encrypted shares

b) improved sparse file support

c) Directory entry caching relies on a 1 second timer, rather than

using FindNotify or equivalent.  - (started)

using Directory Leases

d) quota support (needs minor kernel change since quota calls

to make it to network filesystems or deviceless filesystems)

e) improve support for very old servers (OS/2 and Win9x for example)

Including support for changing the time remotely (utimes command).

e) Better optimize open to reduce redundant opens (using reference

counts more) and to improve use of compounding in SMB3 to reduce

number of roundtrips.

f) hook lower into the sockets api (as NFS/SunRPC does) to avoid the

extra copy in/out of the socket buffers in some cases.

g) Better optimize open (and pathbased setfilesize) to reduce the

oplock breaks coming from windows srv.  Piggyback identical file

opens on top of each other by incrementing reference count rather

than resending (helps reduce server resource utilization and avoid

spurious oplock breaks).

h) Add support for storing symlink info to Windows servers

in the Extended Attribute format their SFU clients would recognize.

i) Finish inotify support so kde and gnome file list windows

f) Finish inotify support so kde and gnome file list windows

will autorefresh (partially complete by Asser). Needs minor kernel

vfs change to support removing D_NOTIFY on a file.   

j) Add GUI tool to configure /proc/fs/cifs settings and for display of

g) Add GUI tool to configure /proc/fs/cifs settings and for display of

the CIFS statistics (started)

k) implement support for security and trusted categories of xattrs

h) implement support for security and trusted categories of xattrs

(requires minor protocol extension) to enable better support for SELINUX

l) Implement O_DIRECT flag on open (already supported on mount)

i) Implement O_DIRECT flag on open (already supported on mount)

m) Create UID mapping facility so server UIDs can be mapped on a per

j) Create UID mapping facility so server UIDs can be mapped on a per

mount or a per server basis to client UIDs or nobody if no mapping

exists.  This is helpful when Unix extensions are negotiated to

allow better permission checking when UIDs differ on the server

and client.  Add new protocol request to the CIFS protocol 

standard for asking the server for the corresponding name of a

particular uid.

exists. Also better integration with winbind for resolving SID owners

k) Add tools to take advantage of more smb3 specific ioctls and features

l) encrypted file support

m) improved stats gathering, tools (perhaps integration with nfsometer?)

n) DOS attrs - returned as pseudo-xattr in Samba format (check VFAT and NTFS for this too)

n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed

file attribute via chflags) and improve user space tools for managing and

viewing them.

o) mount check for unmatched uids

o) mount helper GUI (to simplify the various configuration options on mount)

p) Add support for new vfs entry point for fallocate

p) autonegotiation of dialects (offering more than one dialect ie SMB3.02,

SMB3, SMB2.1 not just SMB3).

q) Add tools to take advantage of cifs/smb3 specific ioctls and features

such as "CopyChunk" (fast server side file copy)

q) Allow mount.cifs to be more verbose in reporting errors with dialect

or unsupported feature errors.

r) encrypted file support

r) updating cifs documentation, and user guid.

s) improved stats gathering, tools (perhaps integration with nfsometer?)

s) Addressing bugs found by running a broader set of xfstests in standard

file system xfstest suite.

t) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed

file attribute via chflags)

t) split cifs and smb3 support into separate modules so legacy (and less

secure) CIFS dialect can be disabled in environments that don't need it

and simplify the code.

u) mount helper GUI (to simplify the various configuration options on mount)

u) Finish up SMB3.1.1 dialect support

v) POSIX Extensions for SMB3.1.1

KNOWN BUGS

====================================

  This is the client VFS module for the Common Internet File System

  (CIFS) protocol which is the successor to the Server Message Block 

  This is the client VFS module for the SMB3 NAS protocol as well

  older dialects such as the Common Internet File System (CIFS)

  protocol which was the successor to the Server Message Block

  (SMB) protocol, the native file sharing mechanism for most early

  PC operating systems. New and improved versions of CIFS are now

  called SMB2 and SMB3. These dialects are also supported by the

  CIFS VFS module. CIFS is fully supported by network

  file servers such as Windows 2000, 2003, 2008 and 2012

  file servers such as Windows 2000, 2003, 2008, 2012 and 2016

  as well by Samba (which provides excellent CIFS

  server support for Linux and many other operating systems), so

  server support for Linux and many other operating systems), Apple

  systems, as well as most Network Attached Storage vendors, so

  this network filesystem client can mount to a wide variety of

  servers.

  The intent of this module is to provide the most advanced network

  file system function for CIFS compliant servers, including better

  POSIX compliance, secure per-user session establishment, high

  performance safe distributed caching (oplock), optional packet

  file system function for SMB3 compliant servers, including advanced

  security features, excellent parallelized high performance i/o, better

  POSIX compliance, secure per-user session establishment, encryption,

  high performance safe distributed caching (leases/oplocks), optional packet

  signing, large files, Unicode support and other internationalization

  improvements. Since both Samba server and this filesystem client support

  the CIFS Unix extensions, the combination can provide a reasonable 

  alternative to NFSv4 for fileserving in some Linux to Linux environments,

  not just in Linux to Windows environments.

  the CIFS Unix extensions (and in the future SMB3 POSIX extensions),

  the combination can provide a reasonable alternative to other network and

  cluster file systems for fileserving in some Linux to Linux environments,

  not just in Linux to Windows (or Linux to Mac) environments.

  This filesystem has an mount utility (mount.cifs) that can be obtained from