ksmbd.rst (7610B)
1.. SPDX-License-Identifier: GPL-2.0 2 3========================== 4KSMBD - SMB3 Kernel Server 5========================== 6 7KSMBD is a linux kernel server which implements SMB3 protocol in kernel space 8for sharing files over network. 9 10KSMBD architecture 11================== 12 13The subset of performance related operations belong in kernelspace and 14the other subset which belong to operations which are not really related with 15performance in userspace. So, DCE/RPC management that has historically resulted 16into number of buffer overflow issues and dangerous security bugs and user 17account 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 VFS 20interface for all file operations. 21 22ksmbd (kernel daemon) 23--------------------- 24 25When the server daemon is started, It starts up a forker thread 26(ksmbd/interface name) at initialization time and open a dedicated port 445 27for listening to SMB requests. Whenever new clients make request, Forker 28thread will accept the client connection and fork a new thread for dedicated 29communication channel between the client and the server. It allows for parallel 30processing of SMB requests(commands) from clients as well as allowing for new 31clients to make new connections. Each instance is named ksmbd/1~n(port number) 32to indicate connected clients. Depending on the SMB request types, each new 33thread 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 commands 36as workitems and to be executed in the handlers of the ksmbd-io kworker threads. 37It allows for multiplexing of the handlers as the kernel take care of initiating 38extra worker threads if the load is increased and vice versa, if the load is 39decreased it destroys the extra worker threads. So, after connection is 40established with client. Dedicated ksmbd/1..n(port number) takes complete 41ownership of receiving/parsing of SMB commands. Each received command is worked 42in parallel i.e., There can be multiple clients commands which are worked in 43parallel. After receiving each command a separated kernel workitem is prepared 44for 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 load 46sharing to be managed optimally by the default kernel and optimizing client 47performance by handling client commands in parallel. 48 49ksmbd.mountd (user space daemon) 50-------------------------------- 51 52ksmbd.mountd is userspace process to, transfer user account and password that 53are registered using ksmbd.adduser (part of utils for user space). Further it 54allows sharing information parameters that parsed from smb.conf to ksmbd in 55kernel. For the execution part it has a daemon which is continuously running 56and connected to the kernel interface using netlink socket, it waits for the 57requests (dcerpc and share/user info). It handles RPC calls (at a minimum few 58dozen) that are most important for file server from NetShareEnum and 59NetServerGetInfo. Complete DCE/RPC response is prepared from the user space 60and passed over to the associated kernel thread for the client. 61 62 63KSMBD Feature Status 64==================== 65 66============================== ================================================= 67Feature name Status 68============================== ================================================= 69Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects 70 (intentionally excludes security vulnerable SMB1 71 dialect). 72Auto Negotiation Supported. 73Compound Request Supported. 74Oplock Cache Mechanism Supported. 75SMB2 leases(v1 lease) Supported. 76Directory leases(v2 lease) Planned for future. 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 and GCM128 supported, GCM256 in 84 progress) 85SMB direct(RDMA) Supported. 86SMB3 Multi-channel Partially Supported. Planned to implement 87 replay/retry mechanisms for future. 88Receive Side Scaling mode Supported. 89SMB3.1.1 POSIX extension Supported. 90ACLs Partially Supported. only DACLs available, SACLs 91 (auditing) is planned for the future. For 92 ownership (SIDs) ksmbd generates random subauth 93 values(then store it to disk) and use uid/gid 94 get from inode as RID for local domain SID. 95 The current acl implementation is limited to 96 standalone server, not a domain member. 97 Integration with Samba tools is being worked on 98 to allow future support for running as a domain 99 member. 100Kerberos Supported. 101Durable handle v1,v2 Planned for future. 102Persistent handle Planned for future. 103SMB2 notify Planned for future. 104Sparse file support Supported. 105DCE/RPC support Partially Supported. a few calls(NetShareEnumAll, 106 NetServerGetInfo, SAMR, LSARPC) that are needed 107 for file server handled via netlink interface 108 from ksmbd.mountd. Additional integration with 109 Samba tools and libraries via upcall is being 110 investigated to allow support for additional 111 DCE/RPC management calls (and future support 112 for Witness protocol e.g.) 113ksmbd/nfsd interoperability Planned for future. The features that ksmbd 114 support are Leases, Notify, ACLs and Share modes. 115============================== ================================================= 116 117 118How to run 119========== 120 1211. Download ksmbd-tools and compile them. 122 - https://github.com/cifsd-team/ksmbd-tools 123 1242. Create user/password for SMB share. 125 126 # mkdir /etc/ksmbd/ 127 # ksmbd.adduser -a <Enter USERNAME for SMB share access> 128 1293. Create /etc/ksmbd/smb.conf file, add SMB share in smb.conf file 130 - Refer smb.conf.example and 131 https://github.com/cifsd-team/ksmbd-tools/blob/master/Documentation/configuration.txt 132 1334. Insert ksmbd.ko module 134 135 # insmod ksmbd.ko 136 1375. Start ksmbd user space daemon 138 # ksmbd.mountd 139 1406. Access share from Windows or Linux using CIFS 141 142Shutdown KSMBD 143============== 144 1451. kill user and kernel space daemon 146 # sudo ksmbd.control -s 147 148How to turn debug print on 149========================== 150 151Each layer 152/sys/class/ksmbd-control/debug 153 1541. Enable all component prints 155 # sudo ksmbd.control -d "all" 156 1572. Enable one of components (smb, auth, vfs, oplock, ipc, conn, rdma) 158 # sudo ksmbd.control -d "smb" 159 1603. Show what prints are enabled. 161 # cat /sys/class/ksmbd-control/debug 162 [smb] auth vfs oplock ipc conn [rdma] 163 1644. Disable prints: 165 If you try the selected component once more, It is disabled without brackets.