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