Documentation/filesystems/cifs/cifsroot.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===========================================
   4 Mounting root file system via SMB (cifs.ko)
   5 ===========================================
   6
   7 Written 2019 by Paulo Alcantara <palcantara@suse.de>
   8
   9 Written 2019 by Aurelien Aptel <aaptel@suse.com>
  10
  11 The CONFIG_CIFS_ROOT option enables experimental root file system
  12 support over the SMB protocol via cifs.ko.
  13
  14 It introduces a new kernel command-line option called 'cifsroot='
  15 which will tell the kernel to mount the root file system over the
  16 network by utilizing SMB or CIFS protocol.
  17
  18 In order to mount, the network stack will also need to be set up by
  19 using 'ip=' config option. For more details, see
  20 Documentation/admin-guide/nfs/nfsroot.rst.
  21
  22 A CIFS root mount currently requires the use of SMB1+UNIX Extensions
  23 which is only supported by the Samba server. SMB1 is the older
  24 deprecated version of the protocol but it has been extended to support
  25 POSIX features (See [1]). The equivalent extensions for the newer
  26 recommended version of the protocol (SMB3) have not been fully
  27 implemented yet which means SMB3 doesn't support some required POSIX
  28 file system objects (e.g. block devices, pipes, sockets).
  29
  30 As a result, a CIFS root will default to SMB1 for now but the version
  31 to use can nonetheless be changed via the 'vers=' mount option.  This
  32 default will change once the SMB3 POSIX extensions are fully
  33 implemented.
  34
  35 Server configuration
  36 ====================
  37
  38 To enable SMB1+UNIX extensions you will need to set these global
  39 settings in Samba smb.conf::
  40
  41     [global]
  42     server min protocol = NT1
  43     unix extension = yes        # default
  44
  45 Kernel command line
  46 ===================
  47
  48 ::
  49
  50     root=/dev/cifs
  51
  52 This is just a virtual device that basically tells the kernel to mount
  53 the root file system via SMB protocol.
  54
  55 ::
  56
  57     cifsroot=//<server-ip>/<share>[,options]
  58
  59 Enables the kernel to mount the root file system via SMB that are
  60 located in the <server-ip> and <share> specified in this option.
  61
  62 The default mount options are set in fs/cifs/cifsroot.c.
  63
  64 server-ip
  65         IPv4 address of the server.
  66
  67 share
  68         Path to SMB share (rootfs).
  69
  70 options
  71         Optional mount options. For more information, see mount.cifs(8).
  72
  73 Examples
  74 ========
  75
  76 Export 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
  93 Restart smb service::
  94
  95     # systemctl restart smb
  96
  97 Test it under QEMU on a kernel built with CONFIG_CIFS_ROOT and
  98 CONFIG_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
 105 1: https://wiki.samba.org/index.php/UNIX_Extensions