summaryrefslogtreecommitdiff
path: root/Documentation/filesystems/cifs
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2019-09-19 20:32:16 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2019-09-19 20:32:16 +0300
commit7e3d2c8210e67ebff472a0b371bb0efb4236ef52 (patch)
tree534510c301bc6733393281755d24501be41615c5 /Documentation/filesystems/cifs
parent7a0d796100daa8e75cda2c166c85d57775704fd4 (diff)
parent4d6bcba70aeb4a512ead9c9eaf9edc6bbab00b14 (diff)
downloadlinux-7e3d2c8210e67ebff472a0b371bb0efb4236ef52.tar.xz
Merge tag '5.4-smb3-fixes' of git://git.samba.org/sfrench/cifs-2.6
Pull cifs updates from Steve French: "Various cifs/smb3 fixes (including for share deleted cases) and features including improved encrypted read performance, and various debugging improvements. Note that since I am at a test event this week with the Samba team, and at the annual Storage Developer Conference/SMB3 Plugfest test event next week a higher than usual number of fixes is expected later next week as other features in progress get additional testing and review during these two events" * tag '5.4-smb3-fixes' of git://git.samba.org/sfrench/cifs-2.6: (38 commits) cifs: update internal module version number cifs: modefromsid: write mode ACE first cifs: cifsroot: add more err checking smb3: add missing worker function for SMB3 change notify cifs: Add support for root file systems cifs: modefromsid: make room for 4 ACE smb3: fix potential null dereference in decrypt offload smb3: fix unmount hang in open_shroot smb3: allow disabling requesting leases smb3: improve handling of share deleted (and share recreated) smb3: display max smb3 requests in flight at any one time smb3: only offload decryption of read responses if multiple requests cifs: add a helper to find an existing readable handle to a file smb3: enable offload of decryption of large reads via mount option smb3: allow parallelizing decryption of reads cifs: add a debug macro that prints \\server\share for errors smb3: fix signing verification of large reads smb3: allow skipping signature verification for perf sensitive configurations smb3: add dynamic tracepoints for flush and close smb3: log warning if CSC policy conflicts with cache mount option ...
Diffstat (limited to 'Documentation/filesystems/cifs')
-rw-r--r--Documentation/filesystems/cifs/cifsroot.txt97
1 files changed, 97 insertions, 0 deletions
diff --git a/Documentation/filesystems/cifs/cifsroot.txt b/Documentation/filesystems/cifs/cifsroot.txt
new file mode 100644
index 000000000000..0fa1a2c36a40
--- /dev/null
+++ b/Documentation/filesystems/cifs/cifsroot.txt
@@ -0,0 +1,97 @@
+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/filesystems/nfs/nfsroot.txt.
+
+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/cifs/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