From ab6cacf833ba337b41700ee193d2c8936f1d049e Mon Sep 17 00:00:00 2001 From: Steve French Date: Mon, 22 May 2023 09:50:33 -0500 Subject: smb3: move Documentation/filesystems/cifs to Documentation/filesystems/smb Documentation/filesystems/cifs contains both server and client information so its pathname is misleading. In addition, the directory fs/smb now contains both server and client, so move Documentation/filesystems/cifs to Documentation/filesystems/smb Suggested-by: Namjae Jeon Acked-by: Namjae Jeon Signed-off-by: Steve French --- Documentation/filesystems/cifs/cifsroot.rst | 105 ---------------- Documentation/filesystems/cifs/index.rst | 10 -- Documentation/filesystems/cifs/ksmbd.rst | 183 ---------------------------- Documentation/filesystems/index.rst | 2 +- Documentation/filesystems/smb/cifsroot.rst | 105 ++++++++++++++++ Documentation/filesystems/smb/index.rst | 10 ++ Documentation/filesystems/smb/ksmbd.rst | 183 ++++++++++++++++++++++++++++ 7 files changed, 299 insertions(+), 299 deletions(-) delete mode 100644 Documentation/filesystems/cifs/cifsroot.rst delete mode 100644 Documentation/filesystems/cifs/index.rst delete mode 100644 Documentation/filesystems/cifs/ksmbd.rst create mode 100644 Documentation/filesystems/smb/cifsroot.rst create mode 100644 Documentation/filesystems/smb/index.rst create mode 100644 Documentation/filesystems/smb/ksmbd.rst (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/cifs/cifsroot.rst b/Documentation/filesystems/cifs/cifsroot.rst deleted file mode 100644 index bf2d9db3acb9..000000000000 --- a/Documentation/filesystems/cifs/cifsroot.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -=========================================== -Mounting root file system via SMB (cifs.ko) -=========================================== - -Written 2019 by Paulo Alcantara - -Written 2019 by Aurelien Aptel - -The CONFIG_CIFS_ROOT option enables experimental root file system -support over the SMB protocol via cifs.ko. - -It introduces a new kernel command-line option called 'cifsroot=' -which will tell the kernel to mount the root file system over the -network by utilizing SMB or CIFS protocol. - -In order to mount, the network stack will also need to be set up by -using 'ip=' config option. For more details, see -Documentation/admin-guide/nfs/nfsroot.rst. - -A CIFS root mount currently requires the use of SMB1+UNIX Extensions -which is only supported by the Samba server. SMB1 is the older -deprecated version of the protocol but it has been extended to support -POSIX features (See [1]). The equivalent extensions for the newer -recommended version of the protocol (SMB3) have not been fully -implemented yet which means SMB3 doesn't support some required POSIX -file system objects (e.g. block devices, pipes, sockets). - -As a result, a CIFS root will default to SMB1 for now but the version -to use can nonetheless be changed via the 'vers=' mount option. This -default will change once the SMB3 POSIX extensions are fully -implemented. - -Server configuration -==================== - -To enable SMB1+UNIX extensions you will need to set these global -settings in Samba smb.conf:: - - [global] - server min protocol = NT1 - unix extension = yes # default - -Kernel command line -=================== - -:: - - root=/dev/cifs - -This is just a virtual device that basically tells the kernel to mount -the root file system via SMB protocol. - -:: - - cifsroot=///[,options] - -Enables the kernel to mount the root file system via SMB that are -located in the and specified in this option. - -The default mount options are set in fs/smb/client/cifsroot.c. - -server-ip - IPv4 address of the server. - -share - Path to SMB share (rootfs). - -options - Optional mount options. For more information, see mount.cifs(8). - -Examples -======== - -Export root file system as a Samba share in smb.conf file:: - - ... - [linux] - path = /path/to/rootfs - read only = no - guest ok = yes - force user = root - force group = root - browseable = yes - writeable = yes - admin users = root - public = yes - create mask = 0777 - directory mask = 0777 - ... - -Restart smb service:: - - # systemctl restart smb - -Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and -CONFIG_IP_PNP options enabled:: - - # qemu-system-x86_64 -enable-kvm -cpu host -m 1024 \ - -kernel /path/to/linux/arch/x86/boot/bzImage -nographic \ - -append "root=/dev/cifs rw ip=dhcp cifsroot=//10.0.2.2/linux,username=foo,password=bar console=ttyS0 3" - - -1: https://wiki.samba.org/index.php/UNIX_Extensions diff --git a/Documentation/filesystems/cifs/index.rst b/Documentation/filesystems/cifs/index.rst deleted file mode 100644 index 1c8597a679ab..000000000000 --- a/Documentation/filesystems/cifs/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -=============================== -CIFS -=============================== - - -.. toctree:: - :maxdepth: 1 - - ksmbd - cifsroot diff --git a/Documentation/filesystems/cifs/ksmbd.rst b/Documentation/filesystems/cifs/ksmbd.rst deleted file mode 100644 index 7bed96d794fc..000000000000 --- a/Documentation/filesystems/cifs/ksmbd.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -========================== -KSMBD - SMB3 Kernel Server -========================== - -KSMBD is a linux kernel server which implements SMB3 protocol in kernel space -for sharing files over network. - -KSMBD architecture -================== - -The subset of performance related operations belong in kernelspace and -the other subset which belong to operations which are not really related with -performance in userspace. So, DCE/RPC management that has historically resulted -into number of buffer overflow issues and dangerous security bugs and user -account management are implemented in user space as ksmbd.mountd. -File operations that are related with performance (open/read/write/close etc.) -in kernel space (ksmbd). This also allows for easier integration with VFS -interface for all file operations. - -ksmbd (kernel daemon) ---------------------- - -When the server daemon is started, It starts up a forker thread -(ksmbd/interface name) at initialization time and open a dedicated port 445 -for listening to SMB requests. Whenever new clients make request, Forker -thread will accept the client connection and fork a new thread for dedicated -communication channel between the client and the server. It allows for parallel -processing of SMB requests(commands) from clients as well as allowing for new -clients to make new connections. Each instance is named ksmbd/1~n(port number) -to indicate connected clients. Depending on the SMB request types, each new -thread can decide to pass through the commands to the user space (ksmbd.mountd), -currently DCE/RPC commands are identified to be handled through the user space. -To further utilize the linux kernel, it has been chosen to process the commands -as workitems and to be executed in the handlers of the ksmbd-io kworker threads. -It allows for multiplexing of the handlers as the kernel take care of initiating -extra worker threads if the load is increased and vice versa, if the load is -decreased it destroys the extra worker threads. So, after connection is -established with client. Dedicated ksmbd/1..n(port number) takes complete -ownership of receiving/parsing of SMB commands. Each received command is worked -in parallel i.e., There can be multiple clients commands which are worked in -parallel. After receiving each command a separated kernel workitem is prepared -for each command which is further queued to be handled by ksmbd-io kworkers. -So, each SMB workitem is queued to the kworkers. This allows the benefit of load -sharing to be managed optimally by the default kernel and optimizing client -performance by handling client commands in parallel. - -ksmbd.mountd (user space daemon) --------------------------------- - -ksmbd.mountd is userspace process to, transfer user account and password that -are registered using ksmbd.adduser (part of utils for user space). Further it -allows sharing information parameters that parsed from smb.conf to ksmbd in -kernel. For the execution part it has a daemon which is continuously running -and connected to the kernel interface using netlink socket, it waits for the -requests (dcerpc and share/user info). It handles RPC calls (at a minimum few -dozen) that are most important for file server from NetShareEnum and -NetServerGetInfo. Complete DCE/RPC response is prepared from the user space -and passed over to the associated kernel thread for the client. - - -KSMBD Feature Status -==================== - -============================== ================================================= -Feature name Status -============================== ================================================= -Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects - (intentionally excludes security vulnerable SMB1 - dialect). -Auto Negotiation Supported. -Compound Request Supported. -Oplock Cache Mechanism Supported. -SMB2 leases(v1 lease) Supported. -Directory leases(v2 lease) Planned for future. -Multi-credits Supported. -NTLM/NTLMv2 Supported. -HMAC-SHA256 Signing Supported. -Secure negotiate Supported. -Signing Update Supported. -Pre-authentication integrity Supported. -SMB3 encryption(CCM, GCM) Supported. (CCM and GCM128 supported, GCM256 in - progress) -SMB direct(RDMA) Supported. -SMB3 Multi-channel Partially Supported. Planned to implement - replay/retry mechanisms for future. -Receive Side Scaling mode Supported. -SMB3.1.1 POSIX extension Supported. -ACLs Partially Supported. only DACLs available, SACLs - (auditing) is planned for the future. For - ownership (SIDs) ksmbd generates random subauth - values(then store it to disk) and use uid/gid - get from inode as RID for local domain SID. - The current acl implementation is limited to - standalone server, not a domain member. - Integration with Samba tools is being worked on - to allow future support for running as a domain - member. -Kerberos Supported. -Durable handle v1,v2 Planned for future. -Persistent handle Planned for future. -SMB2 notify Planned for future. -Sparse file support Supported. -DCE/RPC support Partially Supported. a few calls(NetShareEnumAll, - NetServerGetInfo, SAMR, LSARPC) that are needed - for file server handled via netlink interface - from ksmbd.mountd. Additional integration with - Samba tools and libraries via upcall is being - investigated to allow support for additional - DCE/RPC management calls (and future support - for Witness protocol e.g.) -ksmbd/nfsd interoperability Planned for future. The features that ksmbd - support are Leases, Notify, ACLs and Share modes. -============================== ================================================= - - -How to run -========== - -1. Download ksmbd-tools(https://github.com/cifsd-team/ksmbd-tools/releases) and - compile them. - - - Refer README(https://github.com/cifsd-team/ksmbd-tools/blob/master/README.md) - to know how to use ksmbd.mountd/adduser/addshare/control utils - - $ ./autogen.sh - $ ./configure --with-rundir=/run - $ make && sudo make install - -2. Create /usr/local/etc/ksmbd/ksmbd.conf file, add SMB share in ksmbd.conf file. - - - Refer ksmbd.conf.example in ksmbd-utils, See ksmbd.conf manpage - for details to configure shares. - - $ man ksmbd.conf - -3. Create user/password for SMB share. - - - See ksmbd.adduser manpage. - - $ man ksmbd.adduser - $ sudo ksmbd.adduser -a - -4. Insert ksmbd.ko module after build your kernel. No need to load module - if ksmbd is built into the kernel. - - - Set ksmbd in menuconfig(e.g. $ make menuconfig) - [*] Network File Systems ---> - SMB3 server support (EXPERIMENTAL) - - $ sudo modprobe ksmbd.ko - -5. Start ksmbd user space daemon - - $ sudo ksmbd.mountd - -6. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba) - -Shutdown KSMBD -============== - -1. kill user and kernel space daemon - # sudo ksmbd.control -s - -How to turn debug print on -========================== - -Each layer -/sys/class/ksmbd-control/debug - -1. Enable all component prints - # sudo ksmbd.control -d "all" - -2. Enable one of components (smb, auth, vfs, oplock, ipc, conn, rdma) - # sudo ksmbd.control -d "smb" - -3. Show what prints are enabled. - # cat /sys/class/ksmbd-control/debug - [smb] auth vfs oplock ipc conn [rdma] - -4. Disable prints: - If you try the selected component once more, It is disabled without brackets. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index fbb2b5ada95b..eb252fc972aa 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -72,7 +72,6 @@ Documentation for filesystem implementations. befs bfs btrfs - cifs/index ceph coda configfs @@ -111,6 +110,7 @@ Documentation for filesystem implementations. ramfs-rootfs-initramfs relay romfs + smb/index spufs/index squashfs sysfs diff --git a/Documentation/filesystems/smb/cifsroot.rst b/Documentation/filesystems/smb/cifsroot.rst new file mode 100644 index 000000000000..bf2d9db3acb9 --- /dev/null +++ b/Documentation/filesystems/smb/cifsroot.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================== +Mounting root file system via SMB (cifs.ko) +=========================================== + +Written 2019 by Paulo Alcantara + +Written 2019 by Aurelien Aptel + +The CONFIG_CIFS_ROOT option enables experimental root file system +support over the SMB protocol via cifs.ko. + +It introduces a new kernel command-line option called 'cifsroot=' +which will tell the kernel to mount the root file system over the +network by utilizing SMB or CIFS protocol. + +In order to mount, the network stack will also need to be set up by +using 'ip=' config option. For more details, see +Documentation/admin-guide/nfs/nfsroot.rst. + +A CIFS root mount currently requires the use of SMB1+UNIX Extensions +which is only supported by the Samba server. SMB1 is the older +deprecated version of the protocol but it has been extended to support +POSIX features (See [1]). The equivalent extensions for the newer +recommended version of the protocol (SMB3) have not been fully +implemented yet which means SMB3 doesn't support some required POSIX +file system objects (e.g. block devices, pipes, sockets). + +As a result, a CIFS root will default to SMB1 for now but the version +to use can nonetheless be changed via the 'vers=' mount option. This +default will change once the SMB3 POSIX extensions are fully +implemented. + +Server configuration +==================== + +To enable SMB1+UNIX extensions you will need to set these global +settings in Samba smb.conf:: + + [global] + server min protocol = NT1 + unix extension = yes # default + +Kernel command line +=================== + +:: + + root=/dev/cifs + +This is just a virtual device that basically tells the kernel to mount +the root file system via SMB protocol. + +:: + + cifsroot=///[,options] + +Enables the kernel to mount the root file system via SMB that are +located in the and specified in this option. + +The default mount options are set in fs/smb/client/cifsroot.c. + +server-ip + IPv4 address of the server. + +share + Path to SMB share (rootfs). + +options + Optional mount options. For more information, see mount.cifs(8). + +Examples +======== + +Export root file system as a Samba share in smb.conf file:: + + ... + [linux] + path = /path/to/rootfs + read only = no + guest ok = yes + force user = root + force group = root + browseable = yes + writeable = yes + admin users = root + public = yes + create mask = 0777 + directory mask = 0777 + ... + +Restart smb service:: + + # systemctl restart smb + +Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and +CONFIG_IP_PNP options enabled:: + + # qemu-system-x86_64 -enable-kvm -cpu host -m 1024 \ + -kernel /path/to/linux/arch/x86/boot/bzImage -nographic \ + -append "root=/dev/cifs rw ip=dhcp cifsroot=//10.0.2.2/linux,username=foo,password=bar console=ttyS0 3" + + +1: https://wiki.samba.org/index.php/UNIX_Extensions diff --git a/Documentation/filesystems/smb/index.rst b/Documentation/filesystems/smb/index.rst new file mode 100644 index 000000000000..1c8597a679ab --- /dev/null +++ b/Documentation/filesystems/smb/index.rst @@ -0,0 +1,10 @@ +=============================== +CIFS +=============================== + + +.. toctree:: + :maxdepth: 1 + + ksmbd + cifsroot diff --git a/Documentation/filesystems/smb/ksmbd.rst b/Documentation/filesystems/smb/ksmbd.rst new file mode 100644 index 000000000000..7bed96d794fc --- /dev/null +++ b/Documentation/filesystems/smb/ksmbd.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +KSMBD - SMB3 Kernel Server +========================== + +KSMBD is a linux kernel server which implements SMB3 protocol in kernel space +for sharing files over network. + +KSMBD architecture +================== + +The subset of performance related operations belong in kernelspace and +the other subset which belong to operations which are not really related with +performance in userspace. So, DCE/RPC management that has historically resulted +into number of buffer overflow issues and dangerous security bugs and user +account management are implemented in user space as ksmbd.mountd. +File operations that are related with performance (open/read/write/close etc.) +in kernel space (ksmbd). This also allows for easier integration with VFS +interface for all file operations. + +ksmbd (kernel daemon) +--------------------- + +When the server daemon is started, It starts up a forker thread +(ksmbd/interface name) at initialization time and open a dedicated port 445 +for listening to SMB requests. Whenever new clients make request, Forker +thread will accept the client connection and fork a new thread for dedicated +communication channel between the client and the server. It allows for parallel +processing of SMB requests(commands) from clients as well as allowing for new +clients to make new connections. Each instance is named ksmbd/1~n(port number) +to indicate connected clients. Depending on the SMB request types, each new +thread can decide to pass through the commands to the user space (ksmbd.mountd), +currently DCE/RPC commands are identified to be handled through the user space. +To further utilize the linux kernel, it has been chosen to process the commands +as workitems and to be executed in the handlers of the ksmbd-io kworker threads. +It allows for multiplexing of the handlers as the kernel take care of initiating +extra worker threads if the load is increased and vice versa, if the load is +decreased it destroys the extra worker threads. So, after connection is +established with client. Dedicated ksmbd/1..n(port number) takes complete +ownership of receiving/parsing of SMB commands. Each received command is worked +in parallel i.e., There can be multiple clients commands which are worked in +parallel. After receiving each command a separated kernel workitem is prepared +for each command which is further queued to be handled by ksmbd-io kworkers. +So, each SMB workitem is queued to the kworkers. This allows the benefit of load +sharing to be managed optimally by the default kernel and optimizing client +performance by handling client commands in parallel. + +ksmbd.mountd (user space daemon) +-------------------------------- + +ksmbd.mountd is userspace process to, transfer user account and password that +are registered using ksmbd.adduser (part of utils for user space). Further it +allows sharing information parameters that parsed from smb.conf to ksmbd in +kernel. For the execution part it has a daemon which is continuously running +and connected to the kernel interface using netlink socket, it waits for the +requests (dcerpc and share/user info). It handles RPC calls (at a minimum few +dozen) that are most important for file server from NetShareEnum and +NetServerGetInfo. Complete DCE/RPC response is prepared from the user space +and passed over to the associated kernel thread for the client. + + +KSMBD Feature Status +==================== + +============================== ================================================= +Feature name Status +============================== ================================================= +Dialects Supported. SMB2.1 SMB3.0, SMB3.1.1 dialects + (intentionally excludes security vulnerable SMB1 + dialect). +Auto Negotiation Supported. +Compound Request Supported. +Oplock Cache Mechanism Supported. +SMB2 leases(v1 lease) Supported. +Directory leases(v2 lease) Planned for future. +Multi-credits Supported. +NTLM/NTLMv2 Supported. +HMAC-SHA256 Signing Supported. +Secure negotiate Supported. +Signing Update Supported. +Pre-authentication integrity Supported. +SMB3 encryption(CCM, GCM) Supported. (CCM and GCM128 supported, GCM256 in + progress) +SMB direct(RDMA) Supported. +SMB3 Multi-channel Partially Supported. Planned to implement + replay/retry mechanisms for future. +Receive Side Scaling mode Supported. +SMB3.1.1 POSIX extension Supported. +ACLs Partially Supported. only DACLs available, SACLs + (auditing) is planned for the future. For + ownership (SIDs) ksmbd generates random subauth + values(then store it to disk) and use uid/gid + get from inode as RID for local domain SID. + The current acl implementation is limited to + standalone server, not a domain member. + Integration with Samba tools is being worked on + to allow future support for running as a domain + member. +Kerberos Supported. +Durable handle v1,v2 Planned for future. +Persistent handle Planned for future. +SMB2 notify Planned for future. +Sparse file support Supported. +DCE/RPC support Partially Supported. a few calls(NetShareEnumAll, + NetServerGetInfo, SAMR, LSARPC) that are needed + for file server handled via netlink interface + from ksmbd.mountd. Additional integration with + Samba tools and libraries via upcall is being + investigated to allow support for additional + DCE/RPC management calls (and future support + for Witness protocol e.g.) +ksmbd/nfsd interoperability Planned for future. The features that ksmbd + support are Leases, Notify, ACLs and Share modes. +============================== ================================================= + + +How to run +========== + +1. Download ksmbd-tools(https://github.com/cifsd-team/ksmbd-tools/releases) and + compile them. + + - Refer README(https://github.com/cifsd-team/ksmbd-tools/blob/master/README.md) + to know how to use ksmbd.mountd/adduser/addshare/control utils + + $ ./autogen.sh + $ ./configure --with-rundir=/run + $ make && sudo make install + +2. Create /usr/local/etc/ksmbd/ksmbd.conf file, add SMB share in ksmbd.conf file. + + - Refer ksmbd.conf.example in ksmbd-utils, See ksmbd.conf manpage + for details to configure shares. + + $ man ksmbd.conf + +3. Create user/password for SMB share. + + - See ksmbd.adduser manpage. + + $ man ksmbd.adduser + $ sudo ksmbd.adduser -a + +4. Insert ksmbd.ko module after build your kernel. No need to load module + if ksmbd is built into the kernel. + + - Set ksmbd in menuconfig(e.g. $ make menuconfig) + [*] Network File Systems ---> + SMB3 server support (EXPERIMENTAL) + + $ sudo modprobe ksmbd.ko + +5. Start ksmbd user space daemon + + $ sudo ksmbd.mountd + +6. Access share from Windows or Linux using SMB3 client (cifs.ko or smbclient of samba) + +Shutdown KSMBD +============== + +1. kill user and kernel space daemon + # sudo ksmbd.control -s + +How to turn debug print on +========================== + +Each layer +/sys/class/ksmbd-control/debug + +1. Enable all component prints + # sudo ksmbd.control -d "all" + +2. Enable one of components (smb, auth, vfs, oplock, ipc, conn, rdma) + # sudo ksmbd.control -d "smb" + +3. Show what prints are enabled. + # cat /sys/class/ksmbd-control/debug + [smb] auth vfs oplock ipc conn [rdma] + +4. Disable prints: + If you try the selected component once more, It is disabled without brackets. -- cgit v1.2.3