+++ /dev/null
-.. SPDX-License-Identifier: GPL-2.0
-
-===========================================
-Mounting root file system via SMB (cifs.ko)
-===========================================
-
-Written 2019 by Paulo Alcantara <palcantara@suse.de>
-
-Written 2019 by Aurelien Aptel <aaptel@suse.com>
-
-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=//<server-ip>/<share>[,options]
-
-Enables the kernel to mount the root file system via SMB that are
-located in the <server-ip> and <share> 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
+++ /dev/null
-===============================
-CIFS
-===============================
-
-
-.. toctree::
- :maxdepth: 1
-
- ksmbd
- cifsroot
+++ /dev/null
-.. 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 <Enter USERNAME for SMB share access>
-
-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 --->
- <M> 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.
befs
bfs
btrfs
- cifs/index
ceph
coda
configfs
ramfs-rootfs-initramfs
relay
romfs
+ smb/index
spufs/index
squashfs
sysfs
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================
+Mounting root file system via SMB (cifs.ko)
+===========================================
+
+Written 2019 by Paulo Alcantara <palcantara@suse.de>
+
+Written 2019 by Aurelien Aptel <aaptel@suse.com>
+
+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=//<server-ip>/<share>[,options]
+
+Enables the kernel to mount the root file system via SMB that are
+located in the <server-ip> and <share> 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
--- /dev/null
+===============================
+CIFS
+===============================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ksmbd
+ cifsroot
--- /dev/null
+.. 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 <Enter USERNAME for SMB share access>
+
+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 --->
+ <M> 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.
L: linux-cifs@vger.kernel.org
S: Maintained
T: git git://git.samba.org/ksmbd.git
-F: Documentation/filesystems/cifs/ksmbd.rst
+F: Documentation/filesystems/smb/ksmbd.rst
F: fs/smb/common/
F: fs/smb/server/
projects / linux-2.6-microblaze.git / commitdiff