docs: fs: cifs: convert to ReST and add to admin-guide book

The filenames for cifs documentation is not using the same
convention as almost all Kernel documents is using. So,
rename them to a more appropriate name. Then, manually convert
the documentation files for CIFS to ReST.

By doing a manual conversion, we can preserve the original
author's style, while making it to look more like the other
Kernel documents.

Most of the conversion here is trivial. The most complex one was
the README file (which was renamed to usage.rst).

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2019-07-31 17:08:51 -03:00 committed by Jonathan Corbet
parent 9cdd273e29
commit f139291c71
9 changed files with 460 additions and 287 deletions

View File

@ -1,5 +1,10 @@
=======
Authors
=======
Original Author
===============
---------------
Steve French (sfrench@samba.org)
The author wishes to express his appreciation and thanks to:
@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
for proving years ago that very good smb/cifs clients could be done on Unix-like
operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
Newbigin and others for their work on the Linux smbfs module. Thanks to
the other members of the Storage Network Industry Association CIFS Technical
Workgroup for their work specifying this highly complex protocol and finally
@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
Patch Contributors
------------------
Zwane Mwaikambo
Andi Kleen
Amrut Joshi
Shobhit Dayal
Sergey Vlasov
Richard Hughes
Yury Umanets
Mark Hamzy (for some of the early cifs IPv6 work)
Domen Puncer
Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
Vince Negri and Dave Stahl (for finding an important caching bug)
Adrian Bunk (kcalloc cleanups)
Miklos Szeredi
Kazeon team for various fixes especially for 2.4 version.
Asser Ferno (Change Notify support)
Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
Gunter Kukkukk (testing and suggestions for support of old servers)
Igor Mammedov (DFS support)
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, bug fixes, and lots of great work on compounding)
Shirish Pargaonkar (for many ACL patches over the years)
Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
Paulo Alcantara
Long Li (some great work on RDMA, SMB Direct)
- Zwane Mwaikambo
- Andi Kleen
- Amrut Joshi
- Shobhit Dayal
- Sergey Vlasov
- Richard Hughes
- Yury Umanets
- Mark Hamzy (for some of the early cifs IPv6 work)
- Domen Puncer
- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
- Vince Negri and Dave Stahl (for finding an important caching bug)
- Adrian Bunk (kcalloc cleanups)
- Miklos Szeredi
- Kazeon team for various fixes especially for 2.4 version.
- Asser Ferno (Change Notify support)
- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
- Gunter Kukkukk (testing and suggestions for support of old servers)
- Igor Mammedov (DFS support)
- 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, bug fixes, and lots of great work on compounding)
- Shirish Pargaonkar (for many ACL patches over the years)
- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
- Paulo Alcantara
- Long Li (some great work on RDMA, SMB Direct)
Test case and Bug Report contributors

View File

@ -1,3 +1,7 @@
=======
Changes
=======
See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
information (that may be easier to read than parsing the output of
"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes

View File

@ -0,0 +1,21 @@
.. SPDX-License-Identifier: GPL-2.0
====
CIFS
====
.. toctree::
:maxdepth: 2
introduction
usage
todo
changes
authors
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

View File

@ -1,3 +1,7 @@
============
Introduction
============
This is the client VFS module for the SMB3 NAS protocol as well
as for older dialects such as the Common Internet File System (CIFS)
protocol which was the successor to the Server Message Block
@ -33,7 +37,9 @@
tools (including smbinfo and setcifsacl) that can be obtained from
https://git.samba.org/?p=cifs-utils.git
or
git://git.samba.org/cifs-utils.git
mount.cifs should be installed in the directory with the other mount helpers.
@ -41,5 +47,7 @@
For more information on the module see the project wiki page at
https://wiki.samba.org/index.php/LinuxCIFS
and
https://wiki.samba.org/index.php/LinuxCIFS_utils

View File

@ -1,3 +1,7 @@
====
TODO
====
Version 2.14 December 21, 2018
A Partial List of Missing Features
@ -8,6 +12,7 @@ for visible, important contributions to this module. Here
is a partial list of the known problems and missing features:
a) SMB3 (and SMB3.1.1) missing optional features:
- multichannel (started), integration with RDMA
- directory leases (improved metadata caching), started (root dir only)
- T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
@ -16,45 +21,46 @@ a) SMB3 (and SMB3.1.1) missing optional features:
b) improved sparse file support
c) Directory entry caching relies on a 1 second timer, rather than
using Directory Leases, currently only the root file handle is cached longer
using Directory Leases, currently only the root file handle is cached longer
d) quota support (needs minor kernel change since quota calls
to make it to network filesystems or deviceless filesystems)
to make it to network filesystems or deviceless filesystems)
e) Additional use cases where we use "compoounding" (e.g. open/query/close
and open/setinfo/close) to reduce the number of roundtrips, and also
open to reduce redundant opens (using deferred close and reference counts more).
and open/setinfo/close) to reduce the number of roundtrips, and also
open to reduce redundant opens (using deferred close and reference counts
more).
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.
will autorefresh (partially complete by Asser). Needs minor kernel
vfs change to support removing D_NOTIFY on a file.
g) Add GUI tool to configure /proc/fs/cifs settings and for display of
the CIFS statistics (started)
the CIFS statistics (started)
h) implement support for security and trusted categories of xattrs
(requires minor protocol extension) to enable better support for SELINUX
(requires minor protocol extension) to enable better support for SELINUX
i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
feature (may be especially useful for virtualization).
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. Also better integration with winbind for resolving SID owners
mount or a per server basis to client UIDs or nobody if no mapping
exists. Also better integration with winbind for resolving SID owners
k) Add tools to take advantage of more smb3 specific ioctls and features
(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
is in progress, and a passthrough query_info call is already implemented
in cifs.ko to allow smb3 info levels queries to be sent from userspace)
(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
is in progress, and a passthrough query_info call is already implemented
in cifs.ko to allow smb3 info levels queries to be sent from userspace)
l) encrypted file support
m) improved stats gathering tools (perhaps integration with nfsometer?)
to extend and make easier to use what is currently in /proc/fs/cifs/Stats
to extend and make easier to use what is currently in /proc/fs/cifs/Stats
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.
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 helper GUI (to simplify the various configuration options on mount)
@ -65,55 +71,56 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
different servers, and the server we are connected to has gone down.
q) Allow mount.cifs to be more verbose in reporting errors with dialect
or unsupported feature errors.
or unsupported feature errors.
r) updating cifs documentation, and user guide.
s) Addressing bugs found by running a broader set of xfstests in standard
file system xfstest suite.
file system xfstest suite.
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.
secure) CIFS dialect can be disabled in environments that don't need it
and simplify the code.
v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
so far).
so far).
w) Add support for additional strong encryption types, and additional spnego
authentication mechanisms (see MS-SMB2)
authentication mechanisms (see MS-SMB2)
Known Bugs
==========
KNOWN BUGS
====================================
See http://bugzilla.samba.org - search on product "CifsVFS" for
current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
1) existing symbolic links (Windows reparse points) are recognized but
can not be created remotely. They are implemented for Samba and those that
support the CIFS Unix extensions, although earlier versions of Samba
overly restrict the pathnames.
can not be created remotely. They are implemented for Samba and those that
support the CIFS Unix extensions, although earlier versions of Samba
overly restrict the pathnames.
2) follow_link and readdir code does not follow dfs junctions
but recognizes them
but recognizes them
Misc testing to do
==================
1) check out max path names and max path name components against various server
types. Try nested symlinks (8 deep). Return max path name in stat -f information
types. Try nested symlinks (8 deep). Return max path name in stat -f information
2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
cifs/smb3 better
cifs/smb3 better
3) Additional performance testing and optimization using iozone and similar -
there are some easy changes that can be done to parallelize sequential writes,
and when signing is disabled to request larger read sizes (larger than
negotiated size) and send larger write sizes to modern servers.
3) Additional performance testing and optimization using iozone and similar -
there are some easy changes that can be done to parallelize sequential writes,
and when signing is disabled to request larger read sizes (larger than
negotiated size) and send larger write sizes to modern servers.
4) More exhaustively test against less common servers
5) Continue to extend the smb3 "buildbot" which does automated xfstesting
against Windows, Samba and Azure currently - to add additional tests and
to allow the buildbot to execute the tests faster. The URL for the
buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
against Windows, Samba and Azure currently - to add additional tests and
to allow the buildbot to execute the tests faster. The URL for the
buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
6) Address various coverity warnings (most are not bugs per-se, but
the more warnings are addressed, the easier it is to spot real
problems that static analyzers will point out in the future).
the more warnings are addressed, the easier it is to spot real
problems that static analyzers will point out in the future).

View File

@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
blockdev/index
ext4
binderfs
cifs/index
xfs
jfs
ufs

View File

@ -4099,7 +4099,7 @@ L: samba-technical@lists.samba.org (moderated for non-subscribers)
W: http://linux-cifs.samba.org/
T: git git://git.samba.org/sfrench/cifs-2.6.git
S: Supported
F: Documentation/filesystems/cifs/
F: Documentation/admin-guide/cifs/
F: fs/cifs/
COMPACTPCI HOTPLUG CORE