diff mbox series

[v2,01/10] cifsd: add document

Message ID 20210422002824.12677-2-namjae.jeon@samsung.com (mailing list archive)
State New
Headers show
Series cifsd: introduce new SMB3 kernel server | expand

Commit Message

Namjae Jeon April 22, 2021, 12:28 a.m. UTC
This adds a document describing ksmbd design, key features and usage.

Signed-off-by: Namjae Jeon <namjae.jeon@samsung.com>
Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
Signed-off-by: Hyunchul Lee <hyc.lee@gmail.com>
Acked-by: Ronnie Sahlberg <lsahlber@redhat.com>
Signed-off-by: Steve French <stfrench@microsoft.com>
---
 Documentation/filesystems/cifs/cifsd.rst | 152 +++++++++++++++++++++++
 Documentation/filesystems/cifs/index.rst |  10 ++
 Documentation/filesystems/index.rst      |   2 +-
 3 files changed, 163 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/filesystems/cifs/cifsd.rst
 create mode 100644 Documentation/filesystems/cifs/index.rst

Comments

Amir Goldstein April 22, 2021, 4:06 a.m. UTC | #1
On Thu, Apr 22, 2021 at 4:31 AM Namjae Jeon <namjae.jeon@samsung.com> wrote:
>
> This adds a document describing ksmbd design, key features and usage.
>
> Signed-off-by: Namjae Jeon <namjae.jeon@samsung.com>
> Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
> Signed-off-by: Hyunchul Lee <hyc.lee@gmail.com>
> Acked-by: Ronnie Sahlberg <lsahlber@redhat.com>
> Signed-off-by: Steve French <stfrench@microsoft.com>
> ---
>  Documentation/filesystems/cifs/cifsd.rst | 152 +++++++++++++++++++++++
>  Documentation/filesystems/cifs/index.rst |  10 ++
>  Documentation/filesystems/index.rst      |   2 +-
>  3 files changed, 163 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/filesystems/cifs/cifsd.rst
>  create mode 100644 Documentation/filesystems/cifs/index.rst
>
> diff --git a/Documentation/filesystems/cifs/cifsd.rst b/Documentation/filesystems/cifs/cifsd.rst
> new file mode 100644
> index 000000000000..cb9f87b8529f
> --- /dev/null
> +++ b/Documentation/filesystems/cifs/cifsd.rst
> @@ -0,0 +1,152 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==========================
> +CIFSD - SMB3 Kernel Server
> +==========================
> +
> +CIFSD is a linux kernel server which implements SMB3 protocol in kernel space
> +for sharing files over network.
> +

Hello cifsd team!

I am very excited to see your work posted and especially excited to
learn about the collaboration with the samba team.

One of the benefits from kernel smbd implementation is improved ability
to interoperate with VFS in general and nfsd in particular.

For example, I have discussed with several samba team members
the option that ksmbd will serve as a kernel lease agent for samba,
instead of having to work around the limitations of file lock UAPI.

Could you share your plans (if any) for interoperability improvements
with vfs/nfsd?

It would be useful to add an "Interop" column to the Features table below
to document the current state and future plans or just include a note about
it in the Status column.

Off the top of my head, a list of features that samba supports
partial kernel/nfsd interop with are:
- Leases (level 1)
- Notify
- ACLs (NT to POSIX map)
- Share modes

In all of those features, ksmbd is in a position to do a better job.

I only assume that ksmbd implementation of POSIX extensions
is a "native" implementation (i.e. a symlink is implemented as a symlink)
so ksmbd and nfsd exporting the same POSIX fs would at least observe
the same objects(?), but I would rather see this explicitly documented.

Thanks,
Amir.

[...]

> +
> +CIFSD Feature Status
> +====================
> +
> +============================== =================================================
> +Feature name                   Status
> +============================== =================================================
> +Dialects                       Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects
> +                               excluding security vulnerable SMB1.
> +Auto Negotiation               Supported.
> +Compound Request               Supported.
> +Oplock Cache Mechanism         Supported.
> +SMB2 leases(v1 lease)          Supported.
> +Directory leases(v2 lease)     Planned for future.
> +Multi-credits                  Supported.
> +NTLM/NTLMv2                    Supported.
> +HMAC-SHA256 Signing            Supported.
> +Secure negotiate               Supported.
> +Signing Update                 Supported.
> +Pre-authentication integrity   Supported.
> +SMB3 encryption(CCM, GCM)      Supported.
> +SMB direct(RDMA)               Partial Supported. SMB3 Multi-channel is required
> +                               to connect to Windows client.
> +SMB3 Multi-channel             In Progress.
> +SMB3.1.1 POSIX extension       Supported.
> +ACLs                           Partial Supported. only DACLs available, SACLs is
> +                               planned for future. ksmbd generate random subauth
> +                               values(then store it to disk) and use uid/gid
> +                               get from inode as RID for local domain SID.
> +                               The current acl implementation is limited to
> +                               standalone server, not a domain member.
> +Kerberos                       Supported.
> +Durable handle v1,v2           Planned for future.
> +Persistent handle              Planned for future.
> +SMB2 notify                    Planned for future.
> +Sparse file support            Supported.
> +DCE/RPC support                Partial Supported. a few calls(NetShareEnumAll,
> +                               NetServerGetInfo, SAMR, LSARPC) that needed as
> +                               file server via netlink interface from
> +                               ksmbd.mountd.
> +============================== =================================================
> +
Namjae Jeon April 22, 2021, 8:11 a.m. UTC | #2
> 
> On Thu, Apr 22, 2021 at 4:31 AM Namjae Jeon <namjae.jeon@samsung.com> wrote:
> >
> > This adds a document describing ksmbd design, key features and usage.
> >
> > Signed-off-by: Namjae Jeon <namjae.jeon@samsung.com>
> > Signed-off-by: Sergey Senozhatsky <sergey.senozhatsky@gmail.com>
> > Signed-off-by: Hyunchul Lee <hyc.lee@gmail.com>
> > Acked-by: Ronnie Sahlberg <lsahlber@redhat.com>
> > Signed-off-by: Steve French <stfrench@microsoft.com>
> > ---
> >  Documentation/filesystems/cifs/cifsd.rst | 152
> > +++++++++++++++++++++++  Documentation/filesystems/cifs/index.rst |  10 ++
> >  Documentation/filesystems/index.rst      |   2 +-
> >  3 files changed, 163 insertions(+), 1 deletion(-)  create mode 100644
> > Documentation/filesystems/cifs/cifsd.rst
> >  create mode 100644 Documentation/filesystems/cifs/index.rst
> >
> > diff --git a/Documentation/filesystems/cifs/cifsd.rst
> > b/Documentation/filesystems/cifs/cifsd.rst
> > new file mode 100644
> > index 000000000000..cb9f87b8529f
> > --- /dev/null
> > +++ b/Documentation/filesystems/cifs/cifsd.rst
> > @@ -0,0 +1,152 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +==========================
> > +CIFSD - SMB3 Kernel Server
> > +==========================
> > +
> > +CIFSD is a linux kernel server which implements SMB3 protocol in
> > +kernel space for sharing files over network.
> > +
> 
> Hello cifsd team!
Hi Amir,
> 
> I am very excited to see your work posted and especially excited to learn about the collaboration with
> the samba team.
Thanks!
> 
> One of the benefits from kernel smbd implementation is improved ability to interoperate with VFS in
> general and nfsd in particular.
Agreed. This seems to be an important issue, I was missing this.
> 
> For example, I have discussed with several samba team members the option that ksmbd will serve as a
> kernel lease agent for samba, instead of having to work around the limitations of file lock UAPI.
> 
> Could you share your plans (if any) for interoperability improvements with vfs/nfsd?
> 
> It would be useful to add an "Interop" column to the Features table below to document the current
> state and future plans or just include a note about it in the Status column.
Okay, First, I need to check your previous mails about this. Then I will update it in features table.
> 
> Off the top of my head, a list of features that samba supports partial kernel/nfsd interop with are:
> - Leases (level 1)
> - Notify
> - ACLs (NT to POSIX map)
> - Share modes
> 
> In all of those features, ksmbd is in a position to do a better job.
Right.
> 
> I only assume that ksmbd implementation of POSIX extensions is a "native" implementation (i.e. a
> symlink is implemented as a symlink) so ksmbd and nfsd exporting the same POSIX fs would at least
> observe the same objects(?), but I would rather see this explicitly documented.
Okay.
> 
> Thanks,
Thank you!
> Amir.
> 
> [...]
> 
> > +
> > +CIFSD Feature Status
> > +====================
> > +
> > +============================== =================================================
> > +Feature name                   Status
> > +============================== =================================================
> > +Dialects                       Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects
> > +                               excluding security vulnerable SMB1.
> > +Auto Negotiation               Supported.
> > +Compound Request               Supported.
> > +Oplock Cache Mechanism         Supported.
> > +SMB2 leases(v1 lease)          Supported.
> > +Directory leases(v2 lease)     Planned for future.
> > +Multi-credits                  Supported.
> > +NTLM/NTLMv2                    Supported.
> > +HMAC-SHA256 Signing            Supported.
> > +Secure negotiate               Supported.
> > +Signing Update                 Supported.
> > +Pre-authentication integrity   Supported.
> > +SMB3 encryption(CCM, GCM)      Supported.
> > +SMB direct(RDMA)               Partial Supported. SMB3 Multi-channel is required
> > +                               to connect to Windows client.
> > +SMB3 Multi-channel             In Progress.
> > +SMB3.1.1 POSIX extension       Supported.
> > +ACLs                           Partial Supported. only DACLs available, SACLs is
> > +                               planned for future. ksmbd generate random subauth
> > +                               values(then store it to disk) and use uid/gid
> > +                               get from inode as RID for local domain SID.
> > +                               The current acl implementation is limited to
> > +                               standalone server, not a domain member.
> > +Kerberos                       Supported.
> > +Durable handle v1,v2           Planned for future.
> > +Persistent handle              Planned for future.
> > +SMB2 notify                    Planned for future.
> > +Sparse file support            Supported.
> > +DCE/RPC support                Partial Supported. a few calls(NetShareEnumAll,
> > +                               NetServerGetInfo, SAMR, LSARPC) that needed as
> > +                               file server via netlink interface from
> > +                               ksmbd.mountd.
> > +==============================
> > +=================================================
> > +
diff mbox series

Patch

diff --git a/Documentation/filesystems/cifs/cifsd.rst b/Documentation/filesystems/cifs/cifsd.rst
new file mode 100644
index 000000000000..cb9f87b8529f
--- /dev/null
+++ b/Documentation/filesystems/cifs/cifsd.rst
@@ -0,0 +1,152 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+CIFSD - SMB3 Kernel Server
+==========================
+
+CIFSD is a linux kernel server which implements SMB3 protocol in kernel space
+for sharing files over network.
+
+CIFSD architecture
+==================
+
+The subset of performance related operations belong in kernelspace and
+the other subset which belong to operations which are not really related with
+performance in userspace. So, DCE/RPC management that has historically resulted
+into number of buffer overflow issues and dangerous security bugs and user
+account management are implemented in user space as ksmbd.mountd.
+File operations that are related with performance (open/read/write/close etc.)
+in kernel space (ksmbd). This also allows for easier integration with VFS
+interface for all file operations.
+
+ksmbd (kernel daemon)
+---------------------
+
+When the server daemon is started, It starts up a forker thread
+(ksmbd/interface name) at initialization time and open a dedicated port 445
+for listening to SMB requests. Whenever new clients make request, Forker
+thread will accept the client connection and fork a new thread for dedicated
+communication channel between the client and the server. It allows for parallel
+processing of SMB requests(commands) from clients as well as allowing for new
+clients to make new connections. Each instance is named ksmbd/1~n(port number)
+to indicate connected clients. Depending on the SMB request types, each new
+thread can decide to pass through the commands to the user space (ksmbd.mountd),
+currently DCE/RPC commands are identified to be handled through the user space.
+To further utilize the linux kernel, it has been chosen to process the commands
+as workitems and to be executed in the handlers of the ksmbd-io kworker threads.
+It allows for multiplexing of the handlers as the kernel take care of initiating
+extra worker threads if the load is increased and vice versa, if the load is
+decreased it destroys the extra worker threads. So, after connection is
+established with client. Dedicated ksmbd/1..n(port number) takes complete
+ownership of receiving/parsing of SMB commands. Each received command is worked
+in parallel i.e., There can be multiple clients commands which are worked in
+parallel. After receiving each command a separated kernel workitem is prepared
+for each command which is further queued to be handled by ksmbd-io kworkers.
+So, each SMB workitem is queued to the kworkers. This allows the benefit of load
+sharing to be managed optimally by the default kernel and optimizing client
+performance by handling client commands in parallel.
+
+ksmbd.mountd (user space daemon)
+--------------------------------
+
+ksmbd.mountd is userspace process to, transfer user account and password that
+are registered using ksmbd.adduser(part of utils for user space). Further it
+allows sharing information parameters that parsed from smb.conf to ksmbd in
+kernel. For the execution part it has a daemon which is continuously running
+and connected to the kernel interface using netlink socket, it waits for the
+requests(dcerpc and share/user info). It handles RPC calls (at a minimum few
+dozen) that are most important for file server from NetShareEnum and
+NetServerGetInfo. Complete DCE/RPC response is prepared from the user space
+and passed over to the associated kernel thread for the client.
+
+
+CIFSD Feature Status
+====================
+
+============================== =================================================
+Feature name                   Status
+============================== =================================================
+Dialects                       Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects
+                               excluding security vulnerable SMB1.
+Auto Negotiation               Supported.
+Compound Request               Supported.
+Oplock Cache Mechanism         Supported.
+SMB2 leases(v1 lease)          Supported.
+Directory leases(v2 lease)     Planned for future.
+Multi-credits                  Supported.
+NTLM/NTLMv2                    Supported.
+HMAC-SHA256 Signing            Supported.
+Secure negotiate               Supported.
+Signing Update                 Supported.
+Pre-authentication integrity   Supported.
+SMB3 encryption(CCM, GCM)      Supported.
+SMB direct(RDMA)               Partial Supported. SMB3 Multi-channel is required
+                               to connect to Windows client.
+SMB3 Multi-channel             In Progress.
+SMB3.1.1 POSIX extension       Supported.
+ACLs                           Partial Supported. only DACLs available, SACLs is
+                               planned for future. ksmbd generate random subauth
+                               values(then store it to disk) and use uid/gid
+                               get from inode as RID for local domain SID.
+                               The current acl implementation is limited to
+                               standalone server, not a domain member.
+Kerberos                       Supported.
+Durable handle v1,v2           Planned for future.
+Persistent handle              Planned for future.
+SMB2 notify                    Planned for future.
+Sparse file support            Supported.
+DCE/RPC support                Partial Supported. a few calls(NetShareEnumAll,
+                               NetServerGetInfo, SAMR, LSARPC) that needed as
+                               file server via netlink interface from
+                               ksmbd.mountd.
+============================== =================================================
+
+
+How to run
+==========
+
+1. Download ksmbd-tools and compile them.
+	- https://github.com/cifsd-team/ksmbd-tools
+
+2. Create user/password for SMB share.
+
+	# mkdir /etc/ksmbd/
+	# ksmbd.adduser -a <Enter USERNAME for SMB share access>
+
+3. Create /etc/ksmbd/smb.conf file, add SMB share in smb.conf file
+	- Refer smb.conf.example and
+          https://github.com/cifsd-team/ksmbd-tools/blob/master/Documentation/configuration.txt
+
+4. Insert ksmbd.ko module
+
+	# insmod ksmbd.ko
+
+5. Start ksmbd user space daemon
+	# ksmbd.mountd
+
+6. Access share from Windows or Linux using CIFS
+
+Shutdown CIFSD
+==============
+
+1. kill user and kernel space daemon
+	# sudo ksmbd.control -s
+
+How to turn debug print on
+==========================
+
+Each layer
+/sys/class/ksmbd-control/debug
+
+1. Enable all component prints
+	# sudo ksmbd.control -d "all"
+
+2. Enable one of components(smb, auth, vfs, oplock, ipc, conn, rdma)
+	# sudo ksmbd.control -d "smb"
+
+3. Show what prints are enable.
+	# cat/sys/class/ksmbd-control/debug
+	  [smb] auth vfs oplock ipc conn [rdma]
+
+4. Disable prints:
+	If you try the selected component once more, It is disabled without brackets.
diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst
new file mode 100644
index 000000000000..e762586b5dc7
--- /dev/null
+++ b/Documentation/filesystems/cifs/index.rst
@@ -0,0 +1,10 @@ 
+===============================
+CIFS
+===============================
+
+
+.. toctree::
+   :maxdepth: 1
+
+   cifsd
+   cifsroot
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1f76b1cb3348..085702b5dbba 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -71,7 +71,7 @@  Documentation for filesystem implementations.
    befs
    bfs
    btrfs
-   cifs/cifsroot
+   cifs/index
    ceph
    coda
    configfs