Documentation/filesystems/smb/ksmbd.rst

   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.