1 .. SPDX-License-Identifier: GPL-2.0 2 3 ========================== 4 KSMBD - SMB3 Kernel Server 5 ========================== 6 7 KSMBD is a linux kernel server which implements SMB3 protocol in kernel space 8 for sharing files over network. 9 10 KSMBD architecture 11 ================== 12 13 The subset of performance related operations belong in kernelspace and 14 the other subset which belong to operations which are not really related with 15 performance in userspace. So, DCE/RPC management that has historically resulted 16 into a number of buffer overflow issues and dangerous security bugs and user 17 account management are implemented in user space as ksmbd.mountd. 18 File operations that are related with performance (open/read/write/close etc.) 19 in kernel space (ksmbd). This also allows for easier integration with VFS 20 interface for all file operations. 21 22 ksmbd (kernel daemon) 23 --------------------- 24 25 When the server daemon is started, It starts up a forker thread 26 (ksmbd/interface name) at initialization time and open a dedicated port 445 27 for listening to SMB requests. Whenever new clients make a request, the Forker 28 thread will accept the client connection and fork a new thread for a dedicated 29 communication channel between the client and the server. It allows for parallel 30 processing of SMB requests(commands) from clients as well as allowing for new 31 clients to make new connections. Each instance is named ksmbd/1~n(port number) 32 to indicate connected clients. Depending on the SMB request types, each new 33 thread can decide to pass through the commands to the user space (ksmbd.mountd), 34 currently DCE/RPC commands are identified to be handled through the user space. 35 To further utilize the linux kernel, it has been chosen to process the commands 36 as workitems and to be executed in the handlers of the ksmbd-io kworker threads. 37 It allows for multiplexing of the handlers as the kernel takes care of initiating 38 extra worker threads if the load is increased and vice versa, if the load is 39 decreased it destroys the extra worker threads. So, after the connection is 40 established with the client. Dedicated ksmbd/1..n(port number) takes complete 41 ownership of receiving/parsing of SMB commands. Each received command is worked 42 in parallel i.e., there can be multiple client commands which are worked in 43 parallel. After receiving each command a separated kernel workitem is prepared 44 for each command which is further queued to be handled by ksmbd-io kworkers. 45 So, each SMB workitem is queued to the kworkers. This allows the benefit of load 46 sharing to be managed optimally by the default kernel and optimizing client 47 performance by handling client commands in parallel. 48 49 ksmbd.mountd (user space daemon) 50 -------------------------------- 51 52 ksmbd.mountd is a userspace process to, transfer the user account and password that 53 are registered using ksmbd.adduser (part of utils for user space). Further it 54 allows sharing information parameters that are parsed from smb.conf to ksmbd in 55 kernel. For the execution part it has a daemon which is continuously running 56 and connected to the kernel interface using netlink socket, it waits for the 57 requests (dcerpc and share/user info). It handles RPC calls (at a minimum few 58 dozen) that are most important for file server from NetShareEnum and 59 NetServerGetInfo. Complete DCE/RPC response is prepared from the user space 60 and passed over to the associated kernel thread for the client. 61 62 63 KSMBD Feature Status 64 ==================== 65 66 ============================== ================================================= 67 Feature name Status 68 ============================== ================================================= 69 Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects 70 (intentionally excludes security vulnerable SMB1 71 dialect). 72 Auto Negotiation Supported. 73 Compound Request Supported. 74 Oplock Cache Mechanism Supported. 75 SMB2 leases(v1 lease) Supported. 76 Directory leases(v2 lease) Supported. 77 Multi-credits Supported. 78 NTLM/NTLMv2 Supported. 79 HMAC-SHA256 Signing Supported. 80 Secure negotiate Supported. 81 Signing Update Supported. 82 Pre-authentication integrity Supported. 83 SMB3 encryption(CCM, GCM) Supported. (CCM/GCM128 and CCM/GCM256 supported) 84 SMB direct(RDMA) Supported. 85 SMB3 Multi-channel Partially Supported. Planned to implement 86 replay/retry mechanisms for future. 87 Receive Side Scaling mode Supported. 88 SMB3.1.1 POSIX extension Supported. 89 ACLs Partially Supported. only DACLs available, SACLs 90 (auditing) is planned for the future. For 91 ownership (SIDs) ksmbd generates random subauth 92 values(then store it to disk) and use uid/gid 93 get from inode as RID for local domain SID. 94 The current acl implementation is limited to 95 standalone server, not a domain member. 96 Integration with Samba tools is being worked on 97 to allow future support for running as a domain 98 member. 99 Kerberos Supported. 100 Durable handle v1,v2 Planned for future. 101 Persistent handle Planned for future. 102 SMB2 notify Planned for future. 103 Sparse file support Supported. 104 DCE/RPC support Partially Supported. a few calls(NetShareEnumAll, 105 NetServerGetInfo, SAMR, LSARPC) that are needed 106 for file server handled via netlink interface 107 from ksmbd.mountd. Additional integration with 108 Samba tools and libraries via upcall is being 109 investigated to allow support for additional 110 DCE/RPC management calls (and future support 111 for Witness protocol e.g.) 112 ksmbd/nfsd interoperability Planned for future. The features that ksmbd 113 support are Leases, Notify, ACLs and Share modes. 114 SMB3.1.1 Compression Planned for future. 115 SMB3.1.1 over QUIC Planned for future. 116 Signing/Encryption over RDMA Planned for future. 117 SMB3.1.1 GMAC signing support Planned for future. 118 ============================== ================================================= 119 120 121 How to run 122 ========== 123 124 1. Download ksmbd-tools(https://github.com/cifsd-team/ksmbd-tools/releases) and 125 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 utils 129 130 $ ./autogen.sh 131 $ ./configure --with-rundir=/run 132 $ make && sudo make install 133 134 2. 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 manpage 137 for details to configure shares. 138 139 $ man ksmbd.conf 140 141 3. Create user/password for SMB share. 142 143 - See ksmbd.adduser manpage. 144 145 $ man ksmbd.adduser 146 $ sudo ksmbd.adduser -a <Enter USERNAME for SMB share access> 147 148 4. Insert the ksmbd.ko module after you build your kernel. No need to load the module 149 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.ko 156 157 5. Start ksmbd user space daemon 158 159 $ sudo ksmbd.mountd 160 161 6. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba) 162 163 Shutdown KSMBD 164 ============== 165 166 1. kill user and kernel space daemon 167 # sudo ksmbd.control -s 168 169 How to turn debug print on 170 ========================== 171 172 Each layer 173 /sys/class/ksmbd-control/debug 174 175 1. Enable all component prints 176 # sudo ksmbd.control -d "all" 177 178 2. Enable one of the components (smb, auth, vfs, oplock, ipc, conn, rdma) 179 # sudo ksmbd.control -d "smb" 180 181 3. Show what prints are enabled. 182 # cat /sys/class/ksmbd-control/debug 183 [smb] auth vfs oplock ipc conn [rdma] 184 185 4. Disable prints: 186 If you try the selected component once more, It is disabled without brackets.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.