187 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==========================4KSMBD - SMB3 Kernel Server5==========================6 7KSMBD is a linux kernel server which implements SMB3 protocol in kernel space8for sharing files over network.9 10KSMBD architecture11==================12 13The subset of performance related operations belong in kernelspace and14the other subset which belong to operations which are not really related with15performance in userspace. So, DCE/RPC management that has historically resulted16into a number of buffer overflow issues and dangerous security bugs and user17account management are implemented in user space as ksmbd.mountd.18File operations that are related with performance (open/read/write/close etc.)19in kernel space (ksmbd). This also allows for easier integration with VFS20interface for all file operations.21 22ksmbd (kernel daemon)23---------------------24 25When the server daemon is started, It starts up a forker thread26(ksmbd/interface name) at initialization time and open a dedicated port 44527for listening to SMB requests. Whenever new clients make a request, the Forker28thread will accept the client connection and fork a new thread for a dedicated29communication channel between the client and the server. It allows for parallel30processing of SMB requests(commands) from clients as well as allowing for new31clients to make new connections. Each instance is named ksmbd/1~n(port number)32to indicate connected clients. Depending on the SMB request types, each new33thread can decide to pass through the commands to the user space (ksmbd.mountd),34currently DCE/RPC commands are identified to be handled through the user space.35To further utilize the linux kernel, it has been chosen to process the commands36as workitems and to be executed in the handlers of the ksmbd-io kworker threads.37It allows for multiplexing of the handlers as the kernel takes care of initiating38extra worker threads if the load is increased and vice versa, if the load is39decreased it destroys the extra worker threads. So, after the connection is40established with the client. Dedicated ksmbd/1..n(port number) takes complete41ownership of receiving/parsing of SMB commands. Each received command is worked42in parallel i.e., there can be multiple client commands which are worked in43parallel. After receiving each command a separated kernel workitem is prepared44for each command which is further queued to be handled by ksmbd-io kworkers.45So, each SMB workitem is queued to the kworkers. This allows the benefit of load46sharing to be managed optimally by the default kernel and optimizing client47performance by handling client commands in parallel.48 49ksmbd.mountd (user space daemon)50--------------------------------51 52ksmbd.mountd is a userspace process to, transfer the user account and password that53are registered using ksmbd.adduser (part of utils for user space). Further it54allows sharing information parameters that are parsed from smb.conf to ksmbd in55kernel. For the execution part it has a daemon which is continuously running56and connected to the kernel interface using netlink socket, it waits for the57requests (dcerpc and share/user info). It handles RPC calls (at a minimum few58dozen) that are most important for file server from NetShareEnum and59NetServerGetInfo. Complete DCE/RPC response is prepared from the user space60and passed over to the associated kernel thread for the client.61 62 63KSMBD Feature Status64====================65 66============================== =================================================67Feature name Status68============================== =================================================69Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects70 (intentionally excludes security vulnerable SMB171 dialect).72Auto Negotiation Supported.73Compound Request Supported.74Oplock Cache Mechanism Supported.75SMB2 leases(v1 lease) Supported.76Directory leases(v2 lease) Supported.77Multi-credits Supported.78NTLM/NTLMv2 Supported.79HMAC-SHA256 Signing Supported.80Secure negotiate Supported.81Signing Update Supported.82Pre-authentication integrity Supported.83SMB3 encryption(CCM, GCM) Supported. (CCM/GCM128 and CCM/GCM256 supported)84SMB direct(RDMA) Supported.85SMB3 Multi-channel Partially Supported. Planned to implement86 replay/retry mechanisms for future.87Receive Side Scaling mode Supported.88SMB3.1.1 POSIX extension Supported.89ACLs Partially Supported. only DACLs available, SACLs90 (auditing) is planned for the future. For91 ownership (SIDs) ksmbd generates random subauth92 values(then store it to disk) and use uid/gid93 get from inode as RID for local domain SID.94 The current acl implementation is limited to95 standalone server, not a domain member.96 Integration with Samba tools is being worked on97 to allow future support for running as a domain98 member.99Kerberos Supported.100Durable handle v1,v2 Planned for future.101Persistent handle Planned for future.102SMB2 notify Planned for future.103Sparse file support Supported.104DCE/RPC support Partially Supported. a few calls(NetShareEnumAll,105 NetServerGetInfo, SAMR, LSARPC) that are needed106 for file server handled via netlink interface107 from ksmbd.mountd. Additional integration with108 Samba tools and libraries via upcall is being109 investigated to allow support for additional110 DCE/RPC management calls (and future support111 for Witness protocol e.g.)112ksmbd/nfsd interoperability Planned for future. The features that ksmbd113 support are Leases, Notify, ACLs and Share modes.114SMB3.1.1 Compression Planned for future.115SMB3.1.1 over QUIC Planned for future.116Signing/Encryption over RDMA Planned for future.117SMB3.1.1 GMAC signing support Planned for future.118============================== =================================================119 120 121How to run122==========123 1241. Download ksmbd-tools(https://github.com/cifsd-team/ksmbd-tools/releases) and125 compile them.126 127 - Refer to README(https://github.com/cifsd-team/ksmbd-tools/blob/master/README.md)128 to know how to use ksmbd.mountd/adduser/addshare/control utils129 130 $ ./autogen.sh131 $ ./configure --with-rundir=/run132 $ make && sudo make install133 1342. Create /usr/local/etc/ksmbd/ksmbd.conf file, add SMB share in ksmbd.conf file.135 136 - Refer to ksmbd.conf.example in ksmbd-utils, See ksmbd.conf manpage137 for details to configure shares.138 139 $ man ksmbd.conf140 1413. Create user/password for SMB share.142 143 - See ksmbd.adduser manpage.144 145 $ man ksmbd.adduser146 $ sudo ksmbd.adduser -a <Enter USERNAME for SMB share access>147 1484. Insert the ksmbd.ko module after you build your kernel. No need to load the module149 if ksmbd is built into the kernel.150 151 - Set ksmbd in menuconfig(e.g. $ make menuconfig)152 [*] Network File Systems --->153 <M> SMB3 server support (EXPERIMENTAL)154 155 $ sudo modprobe ksmbd.ko156 1575. Start ksmbd user space daemon158 159 $ sudo ksmbd.mountd160 1616. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba)162 163Shutdown KSMBD164==============165 1661. kill user and kernel space daemon167 # sudo ksmbd.control -s168 169How to turn debug print on170==========================171 172Each layer173/sys/class/ksmbd-control/debug174 1751. Enable all component prints176 # sudo ksmbd.control -d "all"177 1782. Enable one of the components (smb, auth, vfs, oplock, ipc, conn, rdma)179 # sudo ksmbd.control -d "smb"180 1813. Show what prints are enabled.182 # cat /sys/class/ksmbd-control/debug183 [smb] auth vfs oplock ipc conn [rdma]184 1854. Disable prints:186 If you try the selected component once more, It is disabled without brackets.187