ksmbd.rst

  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 a 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 a request, the Forker
 28thread will accept the client connection and fork a new thread for a 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 takes 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 the connection is
 40established with the 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 client 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 a userspace process to, transfer the user account and password that
 53are registered using ksmbd.adduser (part of utils for user space). Further it
 54allows sharing information parameters that are 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)     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 implement
 86                               replay/retry mechanisms for future.
 87Receive Side Scaling mode      Supported.
 88SMB3.1.1 POSIX extension       Supported.
 89ACLs                           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.
 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 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.)
112ksmbd/nfsd interoperability    Planned for future. The features that ksmbd
113                               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 run
122==========
123
1241. 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
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 manpage
137     for details to configure shares.
138
139        $ man ksmbd.conf
140
1413. 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
1484. 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
1575. Start ksmbd user space daemon
158
159	$ sudo ksmbd.mountd
160
1616. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba)
162
163Shutdown KSMBD
164==============
165
1661. kill user and kernel space daemon
167	# sudo ksmbd.control -s
168
169How to turn debug print on
170==========================
171
172Each layer
173/sys/class/ksmbd-control/debug
174
1751. Enable all component prints
176	# 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/debug
183	  [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.