Blame SOURCES/0021-Update-man-page-for-mount.cifs-to-add-new-options.patch

75f41f
From 0b3c633002a10419080312ce72cf1a971fd383d0 Mon Sep 17 00:00:00 2001
75f41f
From: Steve French <stfrench@microsoft.com>
75f41f
Date: Wed, 3 Apr 2019 23:46:34 -0500
75f41f
Subject: [PATCH 21/36] Update man page for mount.cifs to add new options
75f41f
75f41f
Add description of "snapshot" and "handletimeout" mount
75f41f
options and a security section noting that the use of
75f41f
cifs is discouraged, and various minor updates.
75f41f
75f41f
Signed-off-by: Steve French <stfrench@microsoft.com>
75f41f
Signed-off-by: Pavel Shilovsky <pshilov@microsoft.com>
75f41f
Reviewed-by: Paulo Alcantara <palcantara@suse.de>
75f41f
(cherry picked from commit cbdd6552bc5978476e344a253941e714d983c27b)
75f41f
Signed-off-by: Sachin Prabhu <sprabhu@redhat.com>
75f41f
---
75f41f
 mount.cifs.rst | 98 +++++++++++++++++++++++++++++++++++-----------------------
75f41f
 1 file changed, 60 insertions(+), 38 deletions(-)
75f41f
75f41f
diff --git a/mount.cifs.rst b/mount.cifs.rst
75f41f
index f64d1f1..8ba6e7b 100644
75f41f
--- a/mount.cifs.rst
75f41f
+++ b/mount.cifs.rst
75f41f
@@ -15,13 +15,13 @@ SYNOPSIS
75f41f
 
75f41f
 This tool is part of the cifs-utils suite.
75f41f
 
75f41f
-``mount.cifs`` mounts a Linux CIFS filesystem. It is usually invoked
75f41f
-indirectly by the mount(8) command when using the "-t cifs"
75f41f
+``mount.cifs`` mounts a CIFS or SMB3 filesystem from Linux. It is
75f41f
+usually invoked indirectly by the mount(8) command when using the "-t cifs"
75f41f
 option. This command only works in Linux, and the kernel must support
75f41f
-the cifs filesystem. The CIFS protocol is the successor to the SMB
75f41f
-protocol and is supported by most Windows servers and many other
75f41f
-commercial servers and Network Attached Storage appliances as well as
75f41f
-by the popular Open Source server Samba.
75f41f
+the cifs filesystem. The SMB3 protocol is the successor to the CIFS (SMB)
75f41f
+protocol and is supported by most Windows servers, Azure (cloud storage),
75f41f
+Macs and many other commercial servers and Network Attached Storage
75f41f
+appliances as well as by the popular Open Source server Samba.
75f41f
 
75f41f
 The mount.cifs utility attaches the UNC name (exported network
75f41f
 resource) specified as service (using ``//server/share`` syntax, where
75f41f
@@ -266,6 +266,13 @@ handlecache
75f41f
 nohandlecache
75f41f
   Disable caching of the share root directory handle.
75f41f
 
75f41f
+handletimeout=arg
75f41f
+  The time (in milliseconds) for which the server should reserve the handle after
75f41f
+  a failover waiting for the client to reconnect.  When mounting with
75f41f
+  resilienthandles or persistenthandles mount option, or when their use is
75f41f
+  requested by the server (continuous availability shares) then this parameter
75f41f
+  overrides the server default handle timeout (which for most servers is 120 seconds).
75f41f
+
75f41f
 rwpidforward
75f41f
   Forward pid of a process who opened a file to any read or write
75f41f
   operation on that file. This prevent applications like wine(1) from
75f41f
@@ -387,6 +394,12 @@ persistenthandles
75f41f
 nopersistenthandles
75f41f
   (default) Disable persistent handles.
75f41f
 
75f41f
+snapshot=time
75f41f
+   Mount a specific snapshot of the remote share. ``time`` must be a
75f41f
+   positive integer identifying the snapshot requested (in 100-nanosecond
75f41f
+   units that have elapsed since January 1, 1601, or alternatively it can
75f41f
+   be specified in GMT format e.g. @GMT-2019.03.27-20.52.19)
75f41f
+
75f41f
 nobrl
75f41f
   Do not send byte range lock requests to the server. This is necessary
75f41f
   for certain applications that break with cifs style mandatory byte
75f41f
@@ -401,7 +414,7 @@ locallease
75f41f
   Check cached leases locally instead of querying the server.
75f41f
 
75f41f
 sfu
75f41f
-  When the CIFS Unix Extensions are not negotiated, attempt to create
75f41f
+  When the CIFS or SMB3 Unix Extensions are not negotiated, attempt to create
75f41f
   device files and fifos in a format compatible with Services for Unix
75f41f
   (SFU). In addition retrieve bits 10-12 of the mode via the
75f41f
   ``SETFILEBITS`` extended attribute (as SFU does). In the future the
75f41f
@@ -450,11 +463,11 @@ noserverino
75f41f
 
75f41f
   See section `INODE NUMBERS`_ for more information.
75f41f
 
75f41f
-unix|linux
75f41f
+posix|unix|linux
75f41f
   (default) Enable Unix Extensions for this mount. Requires CIFS
75f41f
   (vers=1.0) or SMB3.1.1 (vers=3.1.1) and a server supporting them.
75f41f
 
75f41f
-nounix|nolinux
75f41f
+noposix|nounix|nolinux
75f41f
   Disable the Unix Extensions for this mount. This can be useful in
75f41f
   order to turn off multiple settings at once. This includes POSIX acls,
75f41f
   POSIX locks, POSIX paths, symlink support and retrieving
75f41f
@@ -479,38 +492,35 @@ nosharesock
75f41f
   Do not try to reuse sockets if the system is already connected to
75f41f
   the server via an existing mount point. This will make the client
75f41f
   always make a new connection to the server no matter what he is
75f41f
-  already connected to.
75f41f
+  already connected to. This can be useful in simulating multiple
75f41f
+  clients connecting to the same server, as each mount point
75f41f
+  will use a different TCP socket.
75f41f
 
75f41f
 noblocksend
75f41f
   Send data on the socket using non blocking operations (MSG_DONTWAIT flag).
75f41f
 
75f41f
 rsize=bytes
75f41f
   Maximum amount of data that the kernel will request in a read request
75f41f
-  in bytes. Prior to kernel 3.2.0, the default was 16k, and the maximum
75f41f
-  size was limited by the ``CIFSMaxBufSize`` module parameter. As of
75f41f
-  kernel 3.2.0, the behavior varies according to whether POSIX
75f41f
-  extensions are enabled on the mount and the server supports large
75f41f
-  POSIX reads. If they are, then the default is 1M, and the maximum is
75f41f
-  16M. If they are not supported by the server, then the default is 60k
75f41f
-  and the maximum is around 127k. The reason for the 60k is because it's
75f41f
-  the maximum size read that windows servers can fill. Note that this
75f41f
-  value is a maximum, and the client may settle on a smaller size to
75f41f
-  accommodate what the server supports. In kernels prior to 3.2.0, no
75f41f
-  negotiation is performed.
75f41f
+  in bytes. Maximum size that servers will accept is typically 8MB for SMB3
75f41f
+  or later dialects. Default requested during mount is 4MB. Prior to the 4.20
75f41f
+  kernel the default requested was 1MB. Prior to the SMB2.1 dialect the
75f41f
+  maximum was usually 64K.
75f41f
 
75f41f
 wsize=bytes
75f41f
   Maximum amount of data that the kernel will send in a write request in
75f41f
-  bytes. Prior to kernel 3.0.0, the default and maximum was 57344 (14 \*
75f41f
-  4096 pages). As of 3.0.0, the default depends on whether the client
75f41f
-  and server negotiate large writes via POSIX extensions. If they do,
75f41f
-  then the default is 1M, and the maximum allowed is 16M. If they do
75f41f
-  not, then the default is 65536 and the maximum allowed is 131007. Note
75f41f
-  that this value is just a starting point for negotiation in 3.0.0 and
75f41f
-  up. The client and server may negotiate this size downward according
75f41f
-  to the server's capabilities. In kernels prior to 3.0.0, no
75f41f
-  negotiation is performed. It can end up with an existing superblock if
75f41f
-  this value isn't specified or it's greater or equal than the existing
75f41f
-  one.
75f41f
+  bytes. Maximum size that servers will accept is typically 8MB for SMB3
75f41f
+  or later dialects. Default requested during mount is 4MB. Prior to the 4.20
75f41f
+  kernel the default requested was 1MB. Prior to the SMB2.1 dialect the
75f41f
+  maximum was usually 64K.
75f41f
+
75f41f
+bsize=bytes
75f41f
+  Override the default blocksize (1MB) reported on SMB3 files (requires
75f41f
+  kernel version of 5.1 or later). Prior to kernel version 5.1, the
75f41f
+  blocksize was always reported as 16K instead of 1MB (and was not
75f41f
+  configurable) which can hurt the performance of tools like cp and scp
75f41f
+  (especially for uncached I/O) which decide on the read and write size
75f41f
+  to use for file copies based on the inode blocksize. bsize may not be
75f41f
+  less than 16K or greater than 16M.
75f41f
 
75f41f
 max_credits=n
75f41f
   Maximum credits the SMB2 client can have. Default is 32000. Must be
75f41f
@@ -885,14 +895,26 @@ CONFIGURATION
75f41f
 The primary mechanism for making configuration changes and for reading
75f41f
 debug information for the cifs vfs is via the Linux /proc
75f41f
 filesystem. In the directory */proc/fs/cifs* are various
75f41f
-configuration files and pseudo files which can display debug
75f41f
-information. There are additional startup options such as maximum
75f41f
-buffer size and number of buffers which only may be set when the
75f41f
+configuration files and pseudo files which can display debug information
75f41f
+and performance statistics. There are additional startup options such as
75f41f
+maximum buffer size and number of buffers which only may be set when the
75f41f
 kernel cifs vfs (cifs.ko module) is loaded. These can be seen by
75f41f
 running the ``modinfo`` utility against the file cifs.ko which will
75f41f
 list the options that may be passed to cifs during module installation
75f41f
 (device driver load). For more information see the kernel file
75f41f
-*fs/cifs/README*.
75f41f
+*fs/cifs/README*. When configuring dynamic tracing (trace-cmd)
75f41f
+note that the list of SMB3 events which can be enabled can be seen at:
75f41f
+*/sys/kernel/debug/tracing/events/cifs/*.
75f41f
+
75f41f
+********
75f41f
+SECURITY
75f41f
+********
75f41f
+
75f41f
+The use of SMB2.1 or later (including the latest dialect SMB3.1.1)
75f41f
+is recommended for improved security and SMB1 is no longer requested
75f41f
+by default at mount time. Old dialects such as CIFS (SMB1, ie vers=1.0)
75f41f
+have much weaker security. Use of CIFS (SMB1) can be disabled by
75f41f
+modprobe cifs disable_legacy_dialects=y.
75f41f
 
75f41f
 ****
75f41f
 BUGS
75f41f
@@ -913,8 +935,8 @@ bugs (minimum: mount.cifs (try ``mount.cifs -V``), kernel (see
75f41f
 VERSION
75f41f
 *******
75f41f
 
75f41f
-This man page is correct for version 1.74 of the cifs vfs filesystem
75f41f
-(roughly Linux kernel 3.0).
75f41f
+This man page is correct for version 2.18 of the cifs vfs filesystem
75f41f
+(roughly Linux kernel 5.0).
75f41f
 
75f41f
 ********
75f41f
 SEE ALSO
75f41f
-- 
75f41f
1.8.3.1
75f41f