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(https://github.com/cifsd-team/ksmbd-tools/releases) and
122   compile them.
123
124   - Refer README(https://github.com/cifsd-team/ksmbd-tools/blob/master/README.md)
125     to know how to use ksmbd.mountd/adduser/addshare/control utils
126
127     $ ./autogen.sh
128     $ ./configure --with-rundir=/run
129     $ make && sudo make install
130
1312. Create /usr/local/etc/ksmbd/ksmbd.conf file, add SMB share in ksmbd.conf file.
132
133   - Refer ksmbd.conf.example in ksmbd-utils, See ksmbd.conf manpage
134     for details to configure shares.
135
136        $ man ksmbd.conf
137
1383. Create user/password for SMB share.
139
140   - See ksmbd.adduser manpage.
141
142     $ man ksmbd.adduser
143     $ sudo ksmbd.adduser -a <Enter USERNAME for SMB share access>
144
1454. Insert ksmbd.ko module after build your kernel. No need to load module
146   if ksmbd is built into the kernel.
147
148   - Set ksmbd in menuconfig(e.g. $ make menuconfig)
149       [*] Network File Systems  --->
150           <M> SMB3 server support (EXPERIMENTAL)
151
152	$ sudo modprobe ksmbd.ko
153
1545. Start ksmbd user space daemon
155
156	$ sudo ksmbd.mountd
157
1586. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba)
159
160Shutdown KSMBD
161==============
162
1631. kill user and kernel space daemon
164	# sudo ksmbd.control -s
165
166How to turn debug print on
167==========================
168
169Each layer
170/sys/class/ksmbd-control/debug
171
1721. Enable all component prints
173	# sudo ksmbd.control -d "all"
174
1752. Enable one of components (smb, auth, vfs, oplock, ipc, conn, rdma)
176	# sudo ksmbd.control -d "smb"
177
1783. Show what prints are enabled.
179	# cat /sys/class/ksmbd-control/debug
180	  [smb] auth vfs oplock ipc conn [rdma]
181
1824. Disable prints:
183	If you try the selected component once more, It is disabled without brackets.
184