1.. SPDX-License-Identifier: GPL-2.0
  2
  3===========================================
  4Mounting root file system via SMB (cifs.ko)
  5===========================================
  6
  7Written 2019 by Paulo Alcantara <palcantara@suse.de>
  8
  9Written 2019 by Aurelien Aptel <aaptel@suse.com>
 10
 11The CONFIG_CIFS_ROOT option enables experimental root file system
 12support over the SMB protocol via cifs.ko.
 13
 14It introduces a new kernel command-line option called 'cifsroot='
 15which will tell the kernel to mount the root file system over the
 16network by utilizing SMB or CIFS protocol.
 17
 18In order to mount, the network stack will also need to be set up by
 19using 'ip=' config option. For more details, see
 20Documentation/admin-guide/nfs/nfsroot.rst.
 21
 22A CIFS root mount currently requires the use of SMB1+UNIX Extensions
 23which is only supported by the Samba server. SMB1 is the older
 24deprecated version of the protocol but it has been extended to support
 25POSIX features (See [1]). The equivalent extensions for the newer
 26recommended version of the protocol (SMB3) have not been fully
 27implemented yet which means SMB3 doesn't support some required POSIX
 28file system objects (e.g. block devices, pipes, sockets).
 29
 30As a result, a CIFS root will default to SMB1 for now but the version
 31to use can nonetheless be changed via the 'vers=' mount option.  This
 32default will change once the SMB3 POSIX extensions are fully
 33implemented.
 34
 35Server configuration
 36====================
 37
 38To enable SMB1+UNIX extensions you will need to set these global
 39settings in Samba smb.conf::
 40
 41    [global]
 42    server min protocol = NT1
 43    unix extension = yes        # default
 44
 45Kernel command line
 46===================
 47
 48::
 49
 50    root=/dev/cifs
 51
 52This is just a virtual device that basically tells the kernel to mount
 53the root file system via SMB protocol.
 54
 55::
 56
 57    cifsroot=//<server-ip>/<share>[,options]
 58
 59Enables the kernel to mount the root file system via SMB that are
 60located in the <server-ip> and <share> specified in this option.
 61
 62The default mount options are set in fs/smb/client/cifsroot.c.
 63
 64server-ip
 65	IPv4 address of the server.
 66
 67share
 68	Path to SMB share (rootfs).
 69
 70options
 71	Optional mount options. For more information, see mount.cifs(8).
 72
 73Examples
 74========
 75
 76Export root file system as a Samba share in smb.conf file::
 77
 78    ...
 79    [linux]
 80	    path = /path/to/rootfs
 81	    read only = no
 82	    guest ok = yes
 83	    force user = root
 84	    force group = root
 85	    browseable = yes
 86	    writeable = yes
 87	    admin users = root
 88	    public = yes
 89	    create mask = 0777
 90	    directory mask = 0777
 91    ...
 92
 93Restart smb service::
 94
 95    # systemctl restart smb
 96
 97Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and
 98CONFIG_IP_PNP options enabled::
 99
100    # qemu-system-x86_64 -enable-kvm -cpu host -m 1024 \
101    -kernel /path/to/linux/arch/x86/boot/bzImage -nographic \
102    -append "root=/dev/cifs rw ip=dhcp cifsroot=//10.0.2.2/linux,username=foo,password=bar console=ttyS0 3"
103
104
1051: https://wiki.samba.org/index.php/UNIX_Extensions