[cifs-utils,v2,1/1] mount.cifs.rst: document missing options, correct wrong ones

Message ID 20180716101935.25801-1-aaptel@suse.com
State New
Headers show
Series
  • [cifs-utils,v2,1/1] mount.cifs.rst: document missing options, correct wrong ones
Related show

Commit Message

Aurélien Aptel July 16, 2018, 10:19 a.m.
Suggested-by: Kenneth Dsouza <kdsouza@redhat.com>
Suggested-by: Jacob Shivers <jshivers@redhat.com>
Signed-off-by: Aurelien Aptel <aaptel@suse.com>
---

Re-roll of the man page changes (please keep the commit with the
checkopt script as is)

Changes since v1:
* typos
* documented version requirements for rdma (thx Kenneth)
* documented regression for domainauto (thx Jacob)

Please check and comment on the documentation of the options as I'm
not sure what the true purpose or inner working of some options
are. In particular:

* nostrictsync: why would you need that and how can it be correct?
* locallease: same
* noblocksend: same
* noautotune: should we document the actual size used? should it be configurable?
* idsfromsid: does this work with any server? should we document the format?

mount.cifs.rst | 121 ++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 86 insertions(+), 35 deletions(-)

Comments

Aurélien Aptel Aug. 6, 2018, 8:52 a.m. | #1
Aurelien Aptel <aaptel@suse.com> writes:
> Suggested-by: Kenneth Dsouza <kdsouza@redhat.com>
> Suggested-by: Jacob Shivers <jshivers@redhat.com>
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>
> Re-roll of the man page changes (please keep the commit with the
> checkopt script as is)
>
> Changes since v1:
> * typos
> * documented version requirements for rdma (thx Kenneth)
> * documented regression for domainauto (thx Jacob)
>
> Please check and comment on the documentation of the options as I'm
> not sure what the true purpose or inner working of some options
> are. In particular:
>
> * nostrictsync: why would you need that and how can it be correct?
> * locallease: same
> * noblocksend: same
> * noautotune: should we document the actual size used? should it be configurable?
> * idsfromsid: does this work with any server? should we document the format?

Friendly ping
Pavel Shilovsky Aug. 6, 2018, 5:03 p.m. | #2
2018-07-16 3:19 GMT-07:00 Aurelien Aptel <aaptel@suse.com>:
> Suggested-by: Kenneth Dsouza <kdsouza@redhat.com>
> Suggested-by: Jacob Shivers <jshivers@redhat.com>
> Signed-off-by: Aurelien Aptel <aaptel@suse.com>
> ---
>
> Re-roll of the man page changes (please keep the commit with the
> checkopt script as is)
>
> Changes since v1:
> * typos
> * documented version requirements for rdma (thx Kenneth)
> * documented regression for domainauto (thx Jacob)
>
> Please check and comment on the documentation of the options as I'm
> not sure what the true purpose or inner working of some options
> are. In particular:
>
> * nostrictsync: why would you need that and how can it be correct?

Some servers do non-buffered writes by default, so there is no need to
ping them one more time for Flush. E.g. for in workloads when a client
is doing a lot of small write + fsync combinations and network latency
is much higher than a server latency, this would bring 2x performance
improvement. Or there might be a scenario when we want to avoid syncs
choosing performance over consistency.


> * locallease: same
> * noblocksend: same
> * noautotune: should we document the actual size used? should it be configurable?
> * idsfromsid: does this work with any server? should we document the format?
>
> mount.cifs.rst | 121 ++++++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 86 insertions(+), 35 deletions(-)
>
> diff --git a/mount.cifs.rst b/mount.cifs.rst
> index 405c459..7565355 100644
> --- a/mount.cifs.rst
> +++ b/mount.cifs.rst
> @@ -123,6 +123,11 @@ forcegid
>    of the gid= option. See the section on `FILE AND DIRECTORY OWNERSHIP
>    AND PERMISSIONS`_ below for more information.
>
> +idsfromsid
> +  Extract uid/gid from special SID instead of mapping it. See the
> +  section on `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_ below for
> +  more information.
> +
>  port=arg
>    sets the port number on which the client will attempt to contact the
>    CIFS server. If this value is specified, look for an existing
> @@ -133,8 +138,9 @@ port=arg
>    try to connect on port 445 first and then port 139 if that
>    fails. Return an error if both fail.
>
> -servernetbiosname=arg
> -  Specify the server netbios name (RFC1001 name) to use when attempting
> +
> +netbiosname=arg
> +  Specify the client netbios name (RFC1001 name) to use when attempting
>    to setup a session to the server. Although rarely needed for mounting
>    to newer servers, this option is needed for mounting to some older
>    servers (such as OS/2 or Windows 98 and Windows ME) since when
> @@ -143,7 +149,8 @@ servernetbiosname=arg
>    characters long and is usually uppercased.
>
>  servern=arg
> -  Synonym for ``servernetbiosname``
> +  Similar to ``netbiosname`` except it specifies the netbios name of
> +  the server instead of the client.
>
>  netbiosname=arg
>    When mounting to servers via port 139, specifies the RFC1001 source
> @@ -164,7 +171,14 @@ ip=arg|addr=arg
>    rarely needs to be specified by the user.
>
>  domain=arg|dom=arg|workgroup=arg
> -  sets the domain (workgroup) of the user.
> +  Sets the domain (workgroup) of the user. If no domains are given,
> +  the empty domain will be used. Use ``domainauto`` to automatically
> +  guess the domain of the server you are connecting to.
> +
> +domainauto
> +  When using NTLM authentication and not providing a domain via
> +  ``domain``, guess the domain from the server NTLM challenge.
> +  This behavior used to be the default on kernels older than 2.6.36.
>
>  guest
>    don't prompt for a password.
> @@ -237,6 +251,9 @@ cache=arg
>    The default in kernels prior to 3.7 was ``loose``. As of kernel 3.7 the
>    default is ``strict``.
>
> +nostrictsync
> +  Do not flush to the server on fsync().
> +
>  handlecache
>    (default) In SMB2 and above, the client often has to open the root
>    of the share (empty path) in various places during mount, path
> @@ -247,32 +264,6 @@ handlecache
>  nohandlecache
>    Disable caching of the share root directory handle.
>
> -directio
> -  Do not do inode data caching on files opened on this mount. This
> -  precludes mmaping files on this mount. In some cases with fast
> -  networks and little or no caching benefits on the client (e.g. when
> -  the application is doing large sequential reads bigger than page size
> -  without rereading the same data) this can provide better performance
> -  than the default behavior which caches reads (readahead) and writes
> -  (writebehind) through the local Linux client pagecache if oplock
> -  (caching token) is granted and held. Note that direct allows write
> -  operations larger than page size to be sent to the server. On some
> -  kernels this requires the cifs.ko module to be built with the
> -  ``CIFS_EXPERIMENTAL`` configure option.
> -
> -  This option is will be deprecated in 3.7. Users should use
> -  ``cache=none`` instead on more recent kernels.
> -
> -strictcache
> -  Use for switching on strict cache mode. In this mode the client reads
> -  from the cache all the time it has *Oplock Level II* , otherwise -
> -  read from the server. As for write - the client stores a data in the
> -  cache in *Exclusive Oplock* case, otherwise - write directly to the
> -  server.
> -
> -  This option is will be deprecated in 3.7. Users should use
> -  ``cache=strict`` instead on more recent kernels.
> -
>  rwpidforward
>    Forward pid of a process who opened a file to any read or write
>    operation on that file. This prevent applications like wine(1) from
> @@ -283,7 +274,7 @@ mapchars
>    including the colon, question mark, pipe, asterik, greater than and
>    less than characters) to the remap range (above 0xF000), which also
>    allows the CIFS client to recognize files created with such characters
> -  by Windows's POSIX emulation. This can also be useful when mounting to
> +  by Windows's Services for Mac. This can also be useful when mounting to
>    most versions of Samba (which also forbids creating and opening files
>    whose names contain any of these seven characters). This has no effect
>    if the server does not support Unicode on the wire. Please note that
> @@ -293,6 +284,10 @@ mapchars
>  nomapchars
>    (default) Do not translate any of these seven characters.
>
> +mapposix
> +  Translate reserved characters similarly to ``mapchars`` but use the
> +  mapping from Microsoft "Services For Unix".
> +
>  intr
>    currently unimplemented.
>
> @@ -367,8 +362,32 @@ sec=arg
>    automatically if it's enabled in */proc/fs/cifs/SecurityFlags*.
>
>  seal
> -  Request encryption at the SMB layer. Encryption is only supported in
> -  SMBv3 and above. The encryption algorithm used is AES-128-CCM.
> +  Request encryption at the SMB layer. The encryption algorithm used
> +  is AES-128-CCM. Requires SMB3 or above.
> +
> +rdma
> +  Connect directly to the server using SMB Direct via a RDMA
> +  adapter. Requires SMB3 or above.
> +
> +resilienthandles
> +  Enable resilient handles. If the server supports it, keep opened
> +  files across reconnections. Requires SMB2.1.
> +
> +noresilienthandles
> +  (default) Disable resilient handles.
> +
> +persistenthandles
> +  Enable persistent handles. If the server supports it, keep opened
> +  files across reconnections. Persistent handles are also valid across
> +  servers in a cluster and have stronger guarantees than resilient
> +  handles. Requires SMB3 or above.
> +
> +nopersistenthandles
> +  (default) Disable persistent handles.
> +
> +snapshot=time
> +  Mount a specific snapshot of the remote share. ``time`` must be a
> +  positive integer identifying the snapshot requested.

Snapshot support hasn't been completed, so, there is no need to document it now.

>
>  nobrl
>    Do not send byte range lock requests to the server. This is necessary
> @@ -376,6 +395,13 @@ nobrl
>    range locks (and most cifs servers do not yet support requesting
>    advisory byte range locks).
>
> +forcemandatorylock
> +  Do not use POSIX locks even when available via unix
> +  extensions. Always use cifs style mandatory locks.
> +
> +locallease
> +  Check cached leases locally instead of querying the server.
> +
>  sfu
>    When the CIFS Unix Extensions are not negotiated, attempt to create
>    device files and fifos in a format compatible with Services for Unix
> @@ -426,8 +452,12 @@ noserverino
>
>    See section `INODE NUMBERS`_ for more information.
>
> -nounix
> -  Disable the CIFS Unix Extensions for this mount. This can be useful in
> +unix|linux
> +  (default) Enable Unix Extensions for this mount. Requires CIFS
> +  (vers=1.0) or SMB3.1.1 (vers=3.1.1) and a server supporting them.
> +
> +nounix|nolinux
> +  Disable the Unix Extensions for this mount. This can be useful in
>    order to turn off multiple settings at once. This includes POSIX acls,
>    POSIX locks, POSIX paths, symlink support and retrieving
>    uids/gids/mode from the server. This can also be useful to work around
> @@ -439,6 +469,23 @@ nouser_xattr
>    Do not allow getfattr/setfattr to get/set xattrs, even if server would
>    support it otherwise. The default is for xattr support to be enabled.
>
> +nodfs
> +  Do not follow Distributed FileSystem referrals. IO on a file not
> +  stored on the server will fail instead of connecting to the target
> +  server transparently.
> +
> +noautotune
> +  Use fixed size for kernel recv/send socket buffers.
> +
> +nosharesock
> +  Do not try to reuse sockets if the system is already connected to
> +  the server via an existing mount point. This will make the client
> +  always make a new connection to the server no matter what he is
> +  already connected to.
> +
> +noblocksend
> +  Send data on the socket using non blocking operations (MSG_DONTWAIT flag).
> +
>  rsize=bytes
>    Maximum amount of data that the kernel will request in a read request
>    in bytes. Prior to kernel 3.2.0, the default was 16k, and the maximum
> @@ -467,6 +514,10 @@ wsize=bytes
>    this value isn't specified or it's greater or equal than the existing
>    one.
>
> +max_credits=n
> +  Maximum credits the SMB2 client can have. Default is 32000. Must be
> +  set to a number between 20 and 60000.
> +
>  fsc
>    Enable local disk caching using FS-Cache for CIFS. This option could
>    be useful to improve performance on a slow link, heavily loaded server
> --
> 2.13.6
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-cifs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


--
Best regards,
Pavel Shilovsky
--
To unsubscribe from this list: send the line "unsubscribe linux-cifs" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Aurélien Aptel Aug. 7, 2018, 8:30 a.m. | #3
Pavel Shilovsky <piastryyy@gmail.com> writes:
>> * nostrictsync: why would you need that and how can it be correct?
>
> Some servers do non-buffered writes by default, so there is no need to
> ping them one more time for Flush. E.g. for in workloads when a client
> is doing a lot of small write + fsync combinations and network latency
> is much higher than a server latency, this would bring 2x performance
> improvement. Or there might be a scenario when we want to avoid syncs
> choosing performance over consistency.

Makes more sense, thanks for the explanation.

Btw, as it is now, the next branch has RDMA documented twice from 2
different commits.

Cheers,
Aurélien Aptel Aug. 8, 2018, 9:40 a.m. | #4
I've resent a patch including those changes that applies on next (hence
it's not a new version but it's meant to be applied on top).

Cheers,

Patch

diff --git a/mount.cifs.rst b/mount.cifs.rst
index 405c459..7565355 100644
--- a/mount.cifs.rst
+++ b/mount.cifs.rst
@@ -123,6 +123,11 @@  forcegid
   of the gid= option. See the section on `FILE AND DIRECTORY OWNERSHIP
   AND PERMISSIONS`_ below for more information.
 
+idsfromsid
+  Extract uid/gid from special SID instead of mapping it. See the
+  section on `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_ below for
+  more information.
+
 port=arg
   sets the port number on which the client will attempt to contact the
   CIFS server. If this value is specified, look for an existing
@@ -133,8 +138,9 @@  port=arg
   try to connect on port 445 first and then port 139 if that
   fails. Return an error if both fail.
 
-servernetbiosname=arg
-  Specify the server netbios name (RFC1001 name) to use when attempting
+
+netbiosname=arg
+  Specify the client netbios name (RFC1001 name) to use when attempting
   to setup a session to the server. Although rarely needed for mounting
   to newer servers, this option is needed for mounting to some older
   servers (such as OS/2 or Windows 98 and Windows ME) since when
@@ -143,7 +149,8 @@  servernetbiosname=arg
   characters long and is usually uppercased.
 
 servern=arg
-  Synonym for ``servernetbiosname``
+  Similar to ``netbiosname`` except it specifies the netbios name of
+  the server instead of the client.
 
 netbiosname=arg
   When mounting to servers via port 139, specifies the RFC1001 source
@@ -164,7 +171,14 @@  ip=arg|addr=arg
   rarely needs to be specified by the user.
 
 domain=arg|dom=arg|workgroup=arg
-  sets the domain (workgroup) of the user.
+  Sets the domain (workgroup) of the user. If no domains are given,
+  the empty domain will be used. Use ``domainauto`` to automatically
+  guess the domain of the server you are connecting to.
+
+domainauto
+  When using NTLM authentication and not providing a domain via
+  ``domain``, guess the domain from the server NTLM challenge.
+  This behavior used to be the default on kernels older than 2.6.36.
 
 guest
   don't prompt for a password.
@@ -237,6 +251,9 @@  cache=arg
   The default in kernels prior to 3.7 was ``loose``. As of kernel 3.7 the
   default is ``strict``.
 
+nostrictsync
+  Do not flush to the server on fsync().
+
 handlecache
   (default) In SMB2 and above, the client often has to open the root
   of the share (empty path) in various places during mount, path
@@ -247,32 +264,6 @@  handlecache
 nohandlecache
   Disable caching of the share root directory handle.
 
-directio
-  Do not do inode data caching on files opened on this mount. This
-  precludes mmaping files on this mount. In some cases with fast
-  networks and little or no caching benefits on the client (e.g. when
-  the application is doing large sequential reads bigger than page size
-  without rereading the same data) this can provide better performance
-  than the default behavior which caches reads (readahead) and writes
-  (writebehind) through the local Linux client pagecache if oplock
-  (caching token) is granted and held. Note that direct allows write
-  operations larger than page size to be sent to the server. On some
-  kernels this requires the cifs.ko module to be built with the
-  ``CIFS_EXPERIMENTAL`` configure option.
-
-  This option is will be deprecated in 3.7. Users should use
-  ``cache=none`` instead on more recent kernels.
-
-strictcache
-  Use for switching on strict cache mode. In this mode the client reads
-  from the cache all the time it has *Oplock Level II* , otherwise -
-  read from the server. As for write - the client stores a data in the
-  cache in *Exclusive Oplock* case, otherwise - write directly to the
-  server.
-
-  This option is will be deprecated in 3.7. Users should use
-  ``cache=strict`` instead on more recent kernels.
-
 rwpidforward
   Forward pid of a process who opened a file to any read or write
   operation on that file. This prevent applications like wine(1) from
@@ -283,7 +274,7 @@  mapchars
   including the colon, question mark, pipe, asterik, greater than and
   less than characters) to the remap range (above 0xF000), which also
   allows the CIFS client to recognize files created with such characters
-  by Windows's POSIX emulation. This can also be useful when mounting to
+  by Windows's Services for Mac. This can also be useful when mounting to
   most versions of Samba (which also forbids creating and opening files
   whose names contain any of these seven characters). This has no effect
   if the server does not support Unicode on the wire. Please note that
@@ -293,6 +284,10 @@  mapchars
 nomapchars
   (default) Do not translate any of these seven characters.
 
+mapposix
+  Translate reserved characters similarly to ``mapchars`` but use the
+  mapping from Microsoft "Services For Unix".
+
 intr
   currently unimplemented.
 
@@ -367,8 +362,32 @@  sec=arg
   automatically if it's enabled in */proc/fs/cifs/SecurityFlags*.
 
 seal
-  Request encryption at the SMB layer. Encryption is only supported in
-  SMBv3 and above. The encryption algorithm used is AES-128-CCM.
+  Request encryption at the SMB layer. The encryption algorithm used
+  is AES-128-CCM. Requires SMB3 or above.
+
+rdma
+  Connect directly to the server using SMB Direct via a RDMA
+  adapter. Requires SMB3 or above.
+
+resilienthandles
+  Enable resilient handles. If the server supports it, keep opened
+  files across reconnections. Requires SMB2.1.
+
+noresilienthandles
+  (default) Disable resilient handles.
+
+persistenthandles
+  Enable persistent handles. If the server supports it, keep opened
+  files across reconnections. Persistent handles are also valid across
+  servers in a cluster and have stronger guarantees than resilient
+  handles. Requires SMB3 or above.
+
+nopersistenthandles
+  (default) Disable persistent handles.
+
+snapshot=time
+  Mount a specific snapshot of the remote share. ``time`` must be a
+  positive integer identifying the snapshot requested.
 
 nobrl
   Do not send byte range lock requests to the server. This is necessary
@@ -376,6 +395,13 @@  nobrl
   range locks (and most cifs servers do not yet support requesting
   advisory byte range locks).
 
+forcemandatorylock
+  Do not use POSIX locks even when available via unix
+  extensions. Always use cifs style mandatory locks.
+
+locallease
+  Check cached leases locally instead of querying the server.
+
 sfu
   When the CIFS Unix Extensions are not negotiated, attempt to create
   device files and fifos in a format compatible with Services for Unix
@@ -426,8 +452,12 @@  noserverino
 
   See section `INODE NUMBERS`_ for more information.
 
-nounix
-  Disable the CIFS Unix Extensions for this mount. This can be useful in
+unix|linux
+  (default) Enable Unix Extensions for this mount. Requires CIFS
+  (vers=1.0) or SMB3.1.1 (vers=3.1.1) and a server supporting them.
+
+nounix|nolinux
+  Disable the Unix Extensions for this mount. This can be useful in
   order to turn off multiple settings at once. This includes POSIX acls,
   POSIX locks, POSIX paths, symlink support and retrieving
   uids/gids/mode from the server. This can also be useful to work around
@@ -439,6 +469,23 @@  nouser_xattr
   Do not allow getfattr/setfattr to get/set xattrs, even if server would
   support it otherwise. The default is for xattr support to be enabled.
 
+nodfs
+  Do not follow Distributed FileSystem referrals. IO on a file not
+  stored on the server will fail instead of connecting to the target
+  server transparently.
+
+noautotune
+  Use fixed size for kernel recv/send socket buffers.
+
+nosharesock
+  Do not try to reuse sockets if the system is already connected to
+  the server via an existing mount point. This will make the client
+  always make a new connection to the server no matter what he is
+  already connected to.
+
+noblocksend
+  Send data on the socket using non blocking operations (MSG_DONTWAIT flag).
+
 rsize=bytes
   Maximum amount of data that the kernel will request in a read request
   in bytes. Prior to kernel 3.2.0, the default was 16k, and the maximum
@@ -467,6 +514,10 @@  wsize=bytes
   this value isn't specified or it's greater or equal than the existing
   one.
 
+max_credits=n
+  Maximum credits the SMB2 client can have. Default is 32000. Must be
+  set to a number between 20 and 60000.
+
 fsc
   Enable local disk caching using FS-Cache for CIFS. This option could
   be useful to improve performance on a slow link, heavily loaded server