From: Mauro Carvalho Chehab Date: Mon, 27 Apr 2020 21:16:59 +0000 (+0200) Subject: docs: filesystems: convert cifs/cifsroot.txt to ReST X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=175cc46f4d667a9073270a32f40212d871c18955;p=linux.git docs: filesystems: convert cifs/cifsroot.txt to ReST - Add a SPDX header; - Adjust document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to filesystems/index.rst. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/28de01ee52283287e4195cf736d7154f122d30d4.1588021877.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/filesystems/cifs/cifsroot.rst b/Documentation/filesystems/cifs/cifsroot.rst new file mode 100644 index 0000000000000..4930bb443134a --- /dev/null +++ b/Documentation/filesystems/cifs/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/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 diff --git a/Documentation/filesystems/cifs/cifsroot.txt b/Documentation/filesystems/cifs/cifsroot.txt deleted file mode 100644 index 947b7ec6ce9e0..0000000000000 --- a/Documentation/filesystems/cifs/cifsroot.txt +++ /dev/null @@ -1,97 +0,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/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 diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 773af390c5e51..d993b33a48c46 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -59,6 +59,7 @@ Documentation for filesystem implementations. befs bfs btrfs + cifs/cifsroot ceph cramfs debugfs